# Idea Brief: Firmware Service-Code SD Qualification Direction

Status: ready-for-prm
Type: idea-brief
Updated: 2026-08-30
Next Action: carry the current synthesis and unresolved architecture, catalog, resume, evidence, and performance questions into PRM as explicit gates
Produces:
Source: work/spikes/spike-firmware-service-code-sd-qualification-direction.md

## Current Synthesis

### Idea

Explore a firmware-native, modular SD qualification suite in which individual
service codes run specific tests and one full-run service executes those same
test implementations in the required order. The full run can pause for safe
operator interventions, survive a planned controller power-off, and resume only
after validating the run, firmware/profile, checkpoint, CID, and media state.

The leading design shape is a shared qualification state machine rather than a
collection of independent service implementations. Firmware would own the
low-level test truth, prerequisites, safety gates, progress, checkpoints, and
results. The future role of the Pi/web qualifier could range from optional
operator and evidence tooling to an independent power witness and reviewer;
that boundary is deliberately unsettled.

### Why It Matters

The current qualification system distributes responsibility across firmware
services, a Pi/web coordinator, contract artifacts, and operator procedures.
That can make an isolated failed test hard to rerun and a complete procedure
hard to understand or resume safely. A common firmware test core could give the
operator both precise diagnostic entry points and one coherent full-run path
without allowing the two paths to diverge.

The direction also treats qualification-system speed as part of correctness.
A method that eventually reaches the right answer after days of avoidable
rescanning cannot produce acceptable qualification evidence merely because the
card itself may be healthy.

### Desired Outcome

An operator can select one SD qualification test or start a complete ordered
run, with both paths exercising identical underlying firmware logic. Each test
has explicit prerequisites, bounded work, expected and maximum duration,
progress/heartbeat output, safe stop behavior, and a result that distinguishes:

- SD technical outcome;
- qualification-method or performance outcome;
- USB evidence completeness; and
- operator or infrastructure interruption.

The complete run can pause for controller-power-off SD interventions without
ever instructing a powered card removal. It resumes the same session only after
identity and checkpoint validation. USB evidence is normally required and is
unique, durable, and reviewable, while an explicit USB-absence override permits
technical execution without falsely changing the SD result.

## Constraints And Non-Goals

- SD removal, insertion, transfer, replacement, and reinsertion require
  controller power off. Powered hot swapping is prohibited and is not a test.
- Every new controller/card evidence run needs the complete CID identity block
  at baseline and again after any relevant replacement, power-off reinsertion,
  initialization, or reboot. CID identifies the specimen; it does not prove
  authenticity.
- Individual and full-run services must call the same test implementations.
- Qualification scans must have defensible scaling and must avoid repeated
  full-card, full-history, or already-proven-region work when bounded methods
  can provide the required proof.
- USB behavior must remain standards-based for the USB Mass Storage class and
  FileX. Production behavior cannot depend on a drive specimen, vendor, model,
  capacity, serial number, or timing quirk.
- USB absence may bypass only USB evidence collection. It cannot bypass CID,
  destructive-operation confirmation, powered-removal protection, or another
  test prerequisite.
- Exact service-code numbers are not selected. The `480`-`489` range remains
  only a candidate pending dispatcher and lifecycle review.
- This brief does not revise the active SD qualification contract, ECR policy,
  project maps, roadmaps, campaigns, workpackages, or current runtime state.
- This brief does not authorize firmware changes, builds, controller
  programming, physical qualification, deployment, or publication.

## Possibilities And Tradeoffs

| Possibility | Benefits | Costs / Risks | Evidence / Status |
| --- | --- | --- | --- |
| Firmware owns tests and sequencing; Pi/web remains an independent witness, operator surface, and evidence ingester | Strong single source of low-level test truth; preserves independent review and power-plane observation | Requires a precise cross-system resume and evidence protocol | Leading hybrid possibility; not approved |
| Firmware owns the complete qualification workflow and USB evidence, with Pi/web optional | Can run without network infrastructure and keeps execution near the media | Controller UI, nonvolatile state, reporting, and review burden may grow substantially; weaker independent observation | Plausible but needs capacity and assurance analysis |
| Firmware exposes modular tests while Pi/web owns full-run sequencing | Reuses the existing coordinator and can keep firmware orchestration smaller | Full-run correctness depends on cross-system state; individual and full paths may drift unless the shared contract is strict | Close to current system shape; compare against the new desired operator experience |
| One state machine with a small controller-nonvolatile journal | Supports planned power-off resume without trusting the SD card under test or requiring USB | Journal placement, integrity, compatibility, and wear must be proven; incomplete destructive phases cannot auto-replay | Candidate mechanism from the source spike |
| USB run directory with manifest, append-only events, per-test summaries, and completion marker written last | Human-readable and machine-reviewable; makes incomplete publication visible | Schema, flush/finalization, capacity, and mid-run-loss behavior remain open | Candidate evidence shape |

## Open Questions

- What is the exact test catalog, required order, and smallest useful boundary
  for each individual service code?
- Which responsibilities belong in firmware, the Pi/web qualifier, and the
  operator, especially sequencing, power-off proof, evidence review, and final
  qualification disposition?
- Does planned resume happen automatically after validation, or only after the
  operator re-enters the full-run code and confirms continuation?
- Where can the controller journal live, and what update, integrity,
  compatibility, recovery, and wear rules make it trustworthy?
- What expected-duration, maximum-duration, no-progress, scaling, and work
  counter budgets apply to every test and supported media geometry?
- When an over-budget test is still advancing, should it stop, complete only
  for diagnostic evidence, or wait for an explicit operator decision?
- What proves controller power-off before firmware or the UI presents an SD
  removal instruction: the existing Pi power fixture, another witness, or an
  approved operator acknowledgement?
- What USB schema, timestamp basis, integrity and finalization protocol, and
  progress cadence are required?
- How much detailed result state must firmware retain when USB is overridden,
  and what can a later export truthfully claim?
- What happens when USB evidence is lost during a run: pause, continue with an
  explicit override, late-export retained state, or mark evidence incomplete?
- Can a technical pass without live USB evidence ever receive formal
  qualification credit, and under what reviewed equivalent-evidence rule?
- If this direction is selected, which current contract, roadmap, campaign,
  application, and firmware-service surfaces are retained, revised,
  superseded, or removed?

## Decisions

- Preserve individual-test entry and a complete ordered run as equal operator
  capabilities built on one shared test core.
- Treat performance and algorithmic scaling as qualification-system quality,
  not as an optional optimization after functional correctness.
- Keep SD outcome, method/performance outcome, evidence state, workflow state,
  and final qualification disposition separate.
- Require USB output normally, while allowing an explicit evidence-only
  override that does not turn a passing SD test into a failure.
- Support safe planned power-off pause/resume and prohibit automatic replay of
  an incomplete destructive phase after an unexpected reset.
- Keep current planning and execution surfaces authoritative until a later,
  explicit direction and PRM decision changes them.

## Don't Forget

- Record run/test start and stop times, elapsed time, applicable thresholds,
  progress/work counters, per-test pass information, errors and context,
  evidence state, and overall completion state.
- Use unique result locations and never silently overwrite a prior run.
- Preserve enough progress or heartbeat information to distinguish a long but
  advancing operation from a stall, retry storm, or pathological rescan.
- Baseline worst-supported geometry and adverse retained states, not only
  small or empty cards.
- Finish or safely stop the current committed test unit before a planned
  power-off pause.
- Validate firmware/profile identity, run identity, pinned CID, checkpoint,
  and media state before resume.
- Keep normal powered USB insertion/removal distinct from SD power-off rules;
  follow close, flush, unmount, eject, and idle-state requirements as
  applicable.
- Preserve fail-closed transport, filesystem, content, and essential-command
  error handling while avoiding optional USB-command or specimen-specific
  production dependencies.

## Exploration Log

### 2026-08-30

- The owner explicitly chose to promote IDEA-0001 through PRM with a Work2
  endpoint. Preserve the unresolved architecture and qualification-contract
  questions as explicit PRM gates; do not silently weaken safety, evidence, or
  cross-system authority boundaries while deriving the plan.

### 2026-08-28

- Created a distinct discovery thread from
  `work/spikes/spike-firmware-service-code-sd-qualification-direction.md`.
- Kept this direction separate from the already-promoted HPT2 retained-history
  performance brief. The two efforts may share performance terminology and
  counters, but they do not share scope or planning authority automatically.
- Reconciled the spike with current governing truth in
  `docs/sd-card-qualification-contract.md`: shared leaf semantics should keep
  workflow state, gate result, evidence completeness, sample disposition, and
  family conclusion distinct.
- Identified the hybrid firmware-state-machine/Pi-witness model as the leading
  possibility to examine, not an approved architecture.
- Preserved current project and campaign surfaces unchanged; no product,
  controller, or external-system action was authorized or performed.

Keep the synthesis current and append only useful dated exploration notes. Use `Status: ready-for-prm`
when the owner chooses to promote it, `promoted` after approved project-map direction captures it,
or `parked` when it is intentionally set aside. A promoted brief names its output in `Produces:`.
