# Mitigate and diagnose HPT USB publication durability 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

Request-bound outcome and phase telemetry correctly distinguish the failed
request from the retry. However, FileX flush reaches a USBX driver branch that
returns success without sending a device command. Replacement-media request 3
therefore displayed Success even though host inspection found only a zero-byte
temporary entry and an unlinked 128 KiB chain.

## Recommendation

Implement a real SCSI SYNCHRONIZE CACHE operation in the USB storage driver,
propagate its transport/sense result through FileX, and add application-level
post-rename reopen/size/tail verification. Extend request-specific telemetry so
J-Link identifies synchronization and verification failures. Do not repair the
evidence sticks or accept delay alone as a durability guarantee.

## Current State

Completed:

- Failure, false-success, A/B identity, and host filesystem evidence captured.
- Root implementation defect localized to USBX `FX_DRIVER_FLUSH`.
- First mitigation proved SYNCHRONIZE CACHE plus cached readback is
  insufficient for the tested device; host inspection again found a lost
  128 KiB chain and no CSV.

Incomplete:

- Device synchronization, readback verification, build/deployment, and
  host-visible end-to-end proof.
- Explicit device STOP/eject transition and repeat qualification on clean
  media.

## Goal

Controller B displays Success only after the final CSV is synchronized,
reopened, size/tail verified, safely removed, and found complete and
filesystem-clean on the host.

## Why It Matters

Customer export is evidence-bearing. A false Success can silently discard the
only removable copy and damage a previously clean filesystem.

## Major Outcomes

- Real USB storage synchronization.
- Request-specific durability diagnostics.
- Exact-image Controller B deployment.
- Controller-to-host end-to-end CSV and FAT proof.

## Delivery Stages

Use stages when sequencing, parity gates, or handoff cost matter.

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 1 | Diagnose | Preserved failure media | confirmed source defect and test contract |
| 2 | Mitigate | source defect | static gates and clean exact candidate |
| 3 | Deploy | exact candidate hash | Controller B identity/no-media baseline |
| 4 | Qualify | operator-directed insertion | durable CSV and clean host filesystem |

## Related Artifacts

- Incidents: work/incidents/incident-hpt-usb-publish-reported-success-before-durable-fat-commit.md
- Checklists:
- Spikes:
- ADRs:
- Runbooks:
- Inventories:
- Decision matrices:

## Rough Sequence

1. Patch the USB storage flush path and export verification contract.
2. Extend diagnostics and static assertions.
3. Clean-build and deploy the exact candidate to B.
4. Capture no-media state, then explicitly request operator insertion.
5. Export, wait for removal-ready Success, remove, and inspect on host.

## Milestones

### Milestone 1: Durable publication implementation

Completion criteria:

- [x] `FX_DRIVER_FLUSH` sends SYNCHRONIZE CACHE and propagates failure.
- [x] Final CSV is reopened and size/tail verified.
- [x] Telemetry distinguishes sync and verification phases.

### Milestone 2: Exact candidate

- [x] Static checks and managed clean build pass.
- [x] Candidate hashes and symbol layout are recorded.
- [x] Exact image is programmed/verified/reset on Controller B.

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

- [x] HMI displays the request-specific outcome.
- [x] Removed media contains the named CSV and completion marker.
- [x] CSV record count matches firmware telemetry.
- [x] Read-only host filesystem check reports no errors.

## Qualification Result

Controller B passed end to end with S-record
`486B048B65BCE801CA26DD6B4448F11B92F6B4C815DAFE082E48CBD4F170CCF9`.
The successful request used nine FileX writes capped at 16 KiB, published 2902
records, completed final readback/sync/STOP, and produced a 146573-byte CSV.
Independent Linux `fsck.fat -vn` was clean with no FAT divergence or orphaned
clusters; the CSV record trailer matched controller telemetry.

## Completion Standard

This workpackage is complete only when the exact Controller B candidate produces
a matching, complete CSV on removed media and the host reports a clean FAT
filesystem.

## Closeout Routing

- Current truth promoted to: docs/sd-card-operation-and-recovery.md
- Historical context remains in: work/incidents/incident-hpt-usb-publish-reported-success-before-durable-fat-commit.md
- Runtime/status evidence: work/evidence/hpt-export-terminal-authority-20260727.md
- Cleanup deferred to: none
