# Diagnose and mitigate Controller A USB false-success durability Workpackage

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

Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Canonical Truth: docs/firmware-update-validation-and-recovery.md and docs/sd-card-operation-and-recovery.md

## Current Context

Controller A hardware variant 0 reported successful IMX, PID, and HPT writes
on exact B-qualified firmware, but removed media contained none of the new
files. The same PNY stick and firmware passed on Controller B hardware variant
1. A software reset still discovered and read the newly saved IMX, proving the
stick retained a volatile session-visible filesystem while USB VBUS stayed
powered. Only physical removal discarded that state.

## Recommendation

Success must cross the same durability boundary as physical removal. After
each USB publication, flush and STOP the device, switch `USB_PWR_EN` off long
enough to force device power loss, restore VBUS, wait for a fresh USBX/FileX
mount, and verify the named file from that fresh session. Report failure if
disconnect, remount, exact size, or completion-tail verification fails.

## Current State

Completed:

- Bounded 16 KiB HPT writes pass Controller B and three USB sticks.
- Controller A upgraded and controller-side WAV/update/flash gates pass.
- Independent Pi scan proved the A false-success boundary.

Completed:

- Shared fresh-session verifier and durability diagnostics.
- USBHS root-port power hooks and exact removed-media diagnosis.
- Fail-closed IMX, PID, and HPT behavior on unqualified hardware variant 0.
- Managed build and exact mitigated image deployment.

Blocked:

- Hardware rework remains a fallback, but comparison with `main` identified a
  newer shared USB transport change that must be ruled out first.

## Main compatibility rollback

The reliable `main` baseline used 1 KiB USB storage transfers, a 1 KiB storage
buffer, the USBHS default 512-byte bulk payload, and 1 KiB IMX writes. The
current candidate had increased those limits to 128 KiB, 8 KiB, 2 KiB, and
32 KiB respectively. Because PID also failed, the shared USBX/HCD changes are
the primary hypothesis. Deploy a conservative 1 KiB candidate while retaining
synchronize-cache, STOP, diagnostics, and fresh-remount verification.

The USBX pool remains 70,656 bytes: a deployed 63,488-byte trial did not
enumerate the inserted stick with the current branch's additional features.
That allocation is capacity, not a transport-size change.

## Goal

IMX, PID, and HPT publication cannot report success until each output survives
a controller-driven USB power cycle and fresh-session read. Controller A then
passes independent Pi FAT and content verification with one physical stick
insertion and one removal.

## Why It Matters

Same-session FileX readback and device STOP are insufficient on hardware
variant 0. Without a fresh-power verification boundary, every USB write
feature can falsely report success and silently lose customer or recovery
files at removal.

## Major Outcomes

- Shared durability telemetry identifies power-cycle, remount, and fresh-read
  failures.
- All USB write workflows use one fresh-session durability barrier.
- Exact candidate passes static/model gates, managed build, A deployment, and
  end-to-end Pi verification.

## Delivery Stages

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

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 1 | Diagnose | A/Pi disagreement | physical durability boundary identified |
| 2 | Mitigate | boundary identified | bounded fresh-session verification |
| 3 | Deploy | managed build and hash | exact A image verified |
| 4 | Qualify | clean A-CTRL-2 | host-visible outputs and clean FAT |

## Related Artifacts

- Checklists: work/checklists/checklist-controller-a-complete-usb-feature-parity-regression-with-raspberry-pi-verification.md
- Spikes:
- ADRs:
- Runbooks:
- Inventories:
- Decision matrices:

## Rough Sequence

1. Add a bounded VBUS power-cycle/remount helper and fresh-file verifier.
2. Route IMX save, PID publication, and HPT completion through the helper.
3. Extend status phases, telemetry capture, and static/model checks.
4. Managed build/package and program exact Controller A candidate.
5. Ask for `A-CTRL-2` only after no-media baseline passes.
6. Execute IMX, PID, HPT, removal, and independent Pi verification.

## Milestones

### Milestone 1: Fresh-session durability

Completion criteria:

- [x] No variant-0 publication reports false success.
- [x] Timeouts/failures remain bounded and diagnostic.

### Milestone 2: Controller A end-to-end proof

- [x] Controller A produces host-visible IMX, PID, and complete HPT CSV.
- [x] Final Pi `fsck.fat -vn` is clean with no temporary files on the B-CTRL
  comparison stick after identical Controller A PID/HPT writes. A-CTRL-2's
  separate two-cluster stale FSInfo summary is a media/format-state finding.
- [x] IMX survives physical removal: `8388864` bytes, SHA-256
  `837A8F7D780442407E0C9D5C66085C4BEBC97702D914C7A31DB6CA9A550DF12C`.
- [x] Repeat the physical-removal persistence gate for PID and HPT.

## Open Questions

- Does hardware variant 0 actually remove USB VBUS when `P4_7` is driven low?
  The first deployment records disconnect/remount timing as the proof.

## Completion Standard

The conservative `main`-compatible transport mitigation is built, deployed,
and physically proven for IMX, PID, and HPT publication. A second stick passed
the independent content and clean-FAT gate after identical Controller A
writes. Firmware USB parity is complete; A-CTRL-2's stale FSInfo summary is a
separate media/format maintenance item. Hardware rework is not indicated.

## Closeout Routing

- Current truth promoted to: docs/firmware-update-validation-and-recovery.md
- Historical context remains in: work/evidence/usb-complete-parity-controller-a-20260727.md
- Runtime/status evidence: work/evidence/controller-a-usb-fresh-session-durability-20260727.md
- Corrected physical-persistence evidence: work/evidence/controller-a-usb-main-compatible-transport-20260727.md
- Cleanup deferred to: none
