# Spike: Firmware service-code SD qualification direction

Status: complete
Type: spike
Updated: 2026-08-26
Next Action: none until the owner explicitly revisits this direction after updating Tool Shed
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Campaign: standalone
Campaign Reason: This is a requirements/discovery capture only and must not change the current owner campaign queue.
Disposition: documented
Produces:

## Purpose And Authority Boundary

Preserve the owner's emerging requirements for a possible change in SD-card
qualification direction. This artifact is reference material for a later
discussion after the owner updates Tool Shed as desired.

This artifact does **not**:

- approve an architecture or assign final service-code numbers;
- create an implementation plan, roadmap revision, campaign, or delivery
  commitment;
- alter, remove, supersede, or reconcile the existing project map, Program
  Roadmap, campaign queue, workpackages, or qualification contract;
- authorize firmware changes, builds, controller programming, qualification
  execution, destructive media operations, deployment, or publication; or
- make the proposed direction current product or qualification policy.

When the owner explicitly resumes this topic, use this artifact as the
requirements input for deciding whether to retain, revise, supersede, or remove
existing roadmap and planning surfaces. Do not infer that disposition merely
from this capture.

## Owner-Stated Requirements

### Modular firmware service-code model

- Provide specific firmware service codes for individual SD qualification
  tests so an operator can isolate and rerun a particular test.
- Provide a full-run service code that executes the required individual tests
  in the qualification order.
- The full-run service and individual services must exercise the same
  underlying test implementations; the full run must not be a separate or
  divergent test implementation.
- The full-run service must pause for required operator interventions rather
  than assuming the entire qualification is uninterrupted or autonomous.
- Exact service-code numbers and the final test-to-code allocation are not yet
  decided. The previously discussed `480` through `489` range is only a
  candidate because it appears unused in the current HMI dispatcher.

### Qualification performance and bounded scanning

- Qualification test execution must be designed for the highest practical
  controller and media performance consistent with correctness, safety, and
  reproducible evidence. Performance is part of qualification-system quality,
  not an optional optimization after the tests function.
- Every scan, traversal, verification, and recovery routine must be reviewed
  for algorithmic scaling. The design must avoid repeatedly scanning the full
  card, full retained history, or already-proven regions when a bounded,
  indexed, sampled, incremental, or checkpointed method can provide the
  required proof without weakening the test.
- A routine is not acceptable merely because it eventually returns the correct
  answer. Behavior that takes days when the required evidence should be
  obtainable in minutes must be tagged as a qualification-system performance
  issue, investigated, and resolved before that test or full-run profile is
  accepted.
- Each test and phase must have an owner-approved expected-duration budget,
  maximum-duration or no-progress threshold, and scaling expectation for the
  supported media geometries. Those budgets are not yet defined and must be
  established from requirements and measured target baselines rather than
  invented during implementation.
- Measure algorithmic work as well as wall-clock time where practical. Useful
  evidence includes sectors or blocks read and written, records or regions
  examined, retries, fallback scans, bytes verified, progress rate, longest
  no-progress interval, and time spent in media, filesystem, computation, and
  evidence-publication stages.
- The service UI and USB output must provide periodic progress or heartbeat
  information sufficient to distinguish a long but advancing operation from a
  stalled or pathologically rescanning operation. The full-run service should
  also provide a defensible remaining-time estimate or phase-level timing
  guidance once baselines exist.
- Test outcome, media outcome, and qualification-system performance must remain
  distinct. A slow or defective scan methodology must not falsely fail the SD
  card; it must record a tool/method performance issue, make the affected
  qualification evidence incomplete or unacceptable, and require correction
  and an approved rerun.
- Performance qualification must include worst-supported geometry and relevant
  adverse states, not only empty or small cards. It must expose unexpected
  full-media fallbacks, repeated rescans, retry storms, and work that grows with
  irrelevant retained data.
- Performance corrections must preserve exact test coverage, fail-closed error
  handling, data integrity, powered-removal restrictions, and standards-based
  SD and USB behavior. Speed must not be obtained by silently weakening the
  evidence or skipping required regions.

### Power-off SD-card interventions

- The full run must support an intervention that requires the controller to be
  powered off, then resume the same qualification session after power is
  restored.
- SD-card removal, insertion, transfer, replacement, and reinsertion require
  controller power off. Powered SD-card hot swapping is prohibited and must
  never be presented as a test or qualification step.
- Before requesting power-off, firmware must finish or safely stop the current
  committed test unit and preserve enough run state to distinguish a planned
  pause from an interrupted test.
- The operator instruction shown while the controller is still powered must
  say to power the controller off and must not say that the SD card may be
  removed while powered.
- SD-card removal instructions may be presented only after controller power-off
  has been established. Whether power-off proof comes from the existing Pi
  power-control fixture, another electronic witness, or an approved operator
  acknowledgement remains to be decided.
- After reboot, the pending run must verify the expected firmware, run/profile
  identity, SD-card CID, prior checkpoint, and media state before continuing.
- A destructive phase found incomplete after an unexpected reset must not be
  replayed automatically.

### USB qualification output

- Qualification services must normally require a USB drive and write the
  qualification output to it.
- Output must identify the run and record at least:
  - exact running test or phase;
  - run and test start times;
  - run and test stop times;
  - per-test elapsed time, progress/work measurements, and the applicable
    duration or no-progress threshold;
  - per-test result, including pass information;
  - any qualification-system performance issue separately from the SD-card
    result;
  - errors and relevant error context per test; and
  - an overall run result or completion state.
- Output must survive planned qualification pauses and controller power cycles.
- Each run must use a unique result location and must not silently overwrite a
  prior run.
- USB handling must use the standards-based USB Mass Storage/FileX path and
  must not add vendor-, model-, capacity-, serial-, timing-, or specimen-specific
  production behavior. A canonical operator label such as `USB04_32G` may be
  recorded as evidence metadata, not used as a device exception.
- Normal USB insertion and removal are powered operations. The controller must
  not be powered off solely to move a USB drive; applicable close, flush,
  unmount, eject, or idle-state requirements still apply.

### USB-absence override

- If a USB drive is unavailable, the operator must be able to override the USB
  requirement and run the selected individual test or full test sequence
  anyway.
- USB absence under an explicit override must not create an SD test error or
  change a passing SD test into a failure.
- The override must bypass only USB evidence collection. It must not bypass CID
  checks, destructive-operation confirmation, powered-removal restrictions, or
  any other safety or test prerequisite.
- The UI and result model must keep test outcome separate from evidence state,
  for example `TEST PASS` with `USB EVIDENCE NOT RECORDED - OPERATOR OVERRIDE`.
- The controller must retain enough nonvolatile state to support planned
  power-off pause/resume without a USB drive. The amount of detailed per-test
  result data that can also be retained internally is not yet decided.
- If a USB drive becomes available later, a late export of retained results is
  desirable, but it must identify itself as a late export and must not claim
  that uncaptured live events were recorded at execution time.
- Handling of a USB drive that is lost during an already recorded run remains
  open. Any eventual behavior must keep USB evidence status separate from the
  SD test result and offer an explicit operator-controlled continuation route.

## Candidate Design Shape Discussed

The following is a candidate design, not an approved requirement or plan:

- A shared firmware qualification state machine owns test sequencing,
  prerequisites, results, stop behavior, and resume behavior.
- Narrow service codes launch one state-machine phase. A full service code
  launches or resumes a session that walks the same phases in order.
- A read-only service displays current run, test, progress, checkpoint,
  intervention, elapsed time, expected duration, performance warnings, errors,
  and results.
- The shared state machine may enforce per-phase progress checkpoints and
  collect common work counters so individual service codes and the full run use
  the same performance accounting and issue classification.
- A small controller-nonvolatile journal independent of the SD card under test
  preserves run ID, firmware/profile identity, pinned CID, completed phase,
  pending intervention, and integrity metadata across power loss.
- The Pi may remain an independent power-plane witness, operator interface,
  evidence ingester, and reviewer surface without driving the low-level tests.
- A USB result directory may contain a human-readable run manifest, an
  append-only event stream, a per-test summary, and a terminal completion
  marker written last.

## Open Decisions

- Final service-code numbers and exact per-code test boundaries.
- Exact complete test catalog and required ordering.
- Quantitative duration, progress, and scaling budgets for every individual
  test and for the complete run at each supported media geometry.
- Which work counters and subsystem timings are needed to detect full-history
  scans, repeated rescans, fallback storms, and other inefficient methods.
- The timeout and classification policy that distinguishes an SD-card failure,
  an expected slow-media result, a qualification-system performance defect,
  and an operator or evidence interruption.
- Whether an over-budget but still progressing test stops immediately,
  completes for diagnostic evidence, or pauses for an explicit operator
  decision.
- Which operator interventions occur in the full run and which require
  external equipment.
- Where and how the controller journal is stored, protected, integrity-checked,
  and wear-bounded.
- Whether a pending session resumes automatically after validation or requires
  re-entry of the full-run service code and explicit confirmation.
- Exact USB file format, schema versioning, timestamps, monotonic timing,
  progress cadence, error fields, integrity checks, and finalization protocol.
- Required internal result retention when USB evidence is overridden.
- Mid-run USB-loss behavior and the conditions for continuing, pausing,
  late-exporting, or declaring evidence incomplete.
- Whether an unrecorded technical pass can ever receive qualification credit,
  and what later review or evidence would be required.
- The continuing role and authority boundary of the Pi/web qualifier.
- Which current roadmap, campaign, workpackage, contract, and application
  surfaces would be retained, revised, superseded, or removed if the owner
  later approves this direction.

## Current-System Context For Later Review

- `README.md` documents the current SD qualification front door.
- `docs/ecr-sd-card-supply-change-resolution.md` documents the current
  controlled HPT media 2.0 retail-card procedure.
- `src/HMI_MainEventHandler.c` currently routes service 467 to read-only SD CID
  identity and service 468 to HPT classification/guarded commissioning; the
  former FAT32 services 469, 470, 471, 472, and 474 are retired in 00.05.xx.
- `work/maps/map-smi-firmware-stabilization-and-qualification.md` and the
  current owner campaign queue remain authoritative planning and execution
  surfaces until the owner explicitly approves a later change.
- `work/spikes/spike-hpt2-service-life-retrieval-performance-requirements.md`
  captures the related but separate requirement to keep production HPT2
  logging, chart retrieval, export, reopen, wrap, and recovery performant over
  years-equivalent retained history. The later planning effort should share
  performance terminology and evidence measures where appropriate without
  merging the two scopes implicitly.

## Recommendation

Preserve this document as a requirements snapshot until the owner is ready to
resume discovery. At that time, first reconcile these requirements against
current firmware, qualification-contract, Pi/web, evidence, safety, and
roadmap truth. Baseline every proposed test at relevant media geometries,
inspect scan and traversal complexity, and treat impractically slow but
functionally correct behavior as an issue requiring resolution. Then explicitly
decide the architecture and planning disposition before creating or modifying
a roadmap or implementation plan.

## Follow-Up

- [ ] Owner explicitly reopens the service-code qualification direction after
  completing the desired Tool Shed update.
- [ ] Review and revise the owner-stated requirements before treating candidate
  design details as decisions.
- [ ] Define per-test performance budgets and audit proposed scan routines for
  bounded work before accepting the future service-code qualification design.
- [ ] Decide whether the existing roadmap and plans are retained, revised,
  superseded, or removed; do not make that change implicitly.
