# Make HPT export terminal outcome authoritative Workpackage

Status: complete
Type: workpackage
Updated: 2026-07-29
Next Action: none

Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md

## Current Context

Controller B on cumulative candidate `30C98F00...ADF649` exposed two related
operator-truth defects. The first export failed before its first CSV write with
USBX `UX_TRANSFER_TIMEOUT` (`0x5C`), but the firmware could localize the failure
only to temporary-file delete/create/open. After USB removal/reinsertion, the
retry completed and `gHptExportStatus` reported `PUBLISHED`, `FX_SUCCESS`, one
`131064`-byte write, and zero HPT gaps, while the shared
`gGenericProgressPercent` remained `902` and the UI reported failure.

The working tree already contains owner work for shared SDRAM USB buffering,
USBHS/USBX tuning, strict WAV handling, and atomic IMX publication. Preserve
those changes. Raw generated diagnostic captures remain ignored; compact
evidence will summarize the relevant outcomes.

## Recommendation

Make a request-bound `S_HptExportStatus` the only terminal authority for HPT
customer export. Keep `gGenericProgressPercent` only as a progress-bar input.
Record the exact USB publication phase and first failing status. Reject stale
terminal state from a prior request by matching a monotonically increasing
request ID.

## Current State

Completed:

- Controller B reproduced a real USB transport timeout.
- The same USB drive passed publication after reinsertion.
- Read-only J-Link captures proved the successful retry was displayed as 902.
- The request-bound status, USB phase telemetry, and HMI terminal arbitration
  are implemented.
- Static gates and an isolated clean Debug build pass.
- Exact S-record
  `3F498F6C473CAC39B2C09D5EA4083C4C5F87BEC50B5195705054051F312A7C81`
  was programmed and verified on Controllers B and A.
- Electronic success-path exports reached matching `PUBLISHED`, `COMPLETE`,
  and zero USB status on both controllers.
- The physical Controller B request-specific failure displayed `USB write
  error` with phase `TEMP_DELETE`, status `0x5C`, and a fresh request ID.
- The physical-HMI replacement-drive retry displayed success and used a
  distinct request ID, proving stale failure state did not control the retry.
  Host inspection correctly rejected that original retry as nondurable and
  drove the later publication-lifecycle mitigations.
- The bounded 16 KiB successor then passed Controller B physical-HMI
  publication, final readback/sync/STOP, independent clean FAT inspection, and
  a matching `COMPLETE` trailer; two additional previously failing specimens
  passed the same regression.
- R5 subsequently passed the forced removal/remount lifecycle on Controllers A
  and B with independent unmounted Pi verification.
- The accepted 32 KiB production successor passed six A/B production exports.
  Every CSV was independently read on the Pi and ended with a `COMPLETE`
  trailer matching the published record count.

## Goal

Every HPT export displays the terminal outcome of its own request, reports the
exact failing publication phase and status, and cannot be overridden by stale
or unrelated generic progress state.

## Why It Matters

A false failure can cause unnecessary media replacement, duplicate operations,
and rejection of valid release evidence. A false success would be worse. The
operator and automation must receive one fail-closed, request-specific truth.

## Major Outcomes

- Request-bound export status.
- Exact USB publication phase and first failure telemetry.
- HPT progress screen driven by the matching export state.
- A/B success parity plus controlled failure and retry evidence.

## Delivery Stages

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 1 | Contract and implementation | B failure/retry captures | static checks and host assertions pass |
| 2 | Exact candidate | clean isolated Debug build | hashes and symbol/layout checks recorded |
| 3 | Target deployment | A/B identity and recovery gates | exact image programmed and verified |
| 4 | End-to-end qualification | mounted known USB media | success, failure, reinsertion/retry, and CSV completion proof |

## Related Artifacts

- Checklists: work/checklists/checklist-hpt-media-2-autonomous-retail-card-qualification.md
- Spikes: work/spikes/spike-clarify-hpt-export-retention-range-messaging.md
- Runbooks: work/runbooks/runbook-autonomous-hpt-sd-qualification.md
- Evidence: work/evidence/hpt-export-start-adjustment-20260726.md

## Rough Sequence

1. Extend and statically validate the export contract.
2. Build in the isolated e2 environment.
3. Capture A/B CID, safe-state, firmware, and USB baselines.
4. Program and verify B, then A.
5. Run normal success on both.
6. Run a controlled non-destructive USB failure on B if an existing approved
   injection exists; do not invent cable or power procedures.
7. Reinsert only the USB drive and prove successful retry.
8. Inspect the CSV completion marker and record count.

## Milestones

### Milestone 1: Firmware contract

Completion criteria:

- [x] Every export request has a nonzero request ID.
- [x] Terminal state is accepted only for the matching request.
- [x] Publication phase and first failing USB status are retained.
- [x] Generic progress cannot override matching `PUBLISHED` or `FAILED`.

### Milestone 2: Exact candidate

Completion criteria:

- [x] Static gates pass.
- [x] Clean isolated Debug build passes.
- [x] ELF/SREC hashes and status layout are recorded.

### Milestone 3: End-to-end target proof

Completion criteria:

- [x] Exact image runs on A and B with matching identities.
- [x] Successful exports display success and contain completion markers.
- [x] Controlled failure displays the exact phase/status.
- [x] USB reinsertion and retry displays success; successor lifecycle
  qualification leaves durable CSVs verified independently on the Pi.
- [x] No stale prior success or error satisfies a new request.

## Resolution

The observed Controller B `UX_TRANSFER_TIMEOUT` supplied the controlled
request-specific failure without inventing an unsafe physical fault. USB media
was subsequently moved through the approved operator workflow and inspected
read-only on `srv-rpi00.local`. The original retry's durability failure remains
historical evidence; the bounded-write, R5, and accepted 32 KiB successors
provide the completed durability proof.

## Completion Standard

This workpackage is complete when the exact candidate passes software/build
gates and both controllers prove request-specific truthful export outcomes,
including one controlled failure/retry case, with CID-linked compact evidence.

## Closeout Routing

- Current truth promoted to: docs/sd-card-operation-and-recovery.md
- Historical context remains in: this completed workpackage
- Runtime/status evidence: work/evidence/
- Successor evidence:
  - work/evidence/hpt-export-terminal-authority-20260727.md
  - work/evidence/controller-a-usb-r5-lifecycle-qualification-20260729.md
  - work/evidence/controller-b-usb-r5-lifecycle-qualification-20260729.md
  - work/evidence/usb-32k-production-baseline-qualification-20260729.md
- Cleanup deferred to: none
