# Implement USB command-class compatibility fallback end to end

Status: complete
Type: workpackage
Updated: 2026-07-30
Next Action: none
Campaign: 003-complete-bounded-hpt-slow-export-firmware-ticket
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Parent: work/maps/map-smi-firmware-stabilization-and-qualification.md
Canonical Truth: docs/firmware-update-validation-and-recovery.md

## Current Context

The stock USBX FileX driver treated `FX_DRIVER_FLUSH` as a no-op. Recent
durability work changed it to issue SCSI `SYNCHRONIZE CACHE(10)` so a
controller-visible success would not merely reflect data still held in a USB
device cache.

The current working implementation recognizes only
`ILLEGAL REQUEST / INVALID FIELD IN CDB (05/24/00)` as an unsupported
SYNCHRONIZE CACHE command. `USB08_8G` instead returns
`ILLEGAL REQUEST / INVALID FIELD IN PARAMETER LIST`; the controller translates
that result to `FX_IO_ERROR (0x90)`.

Independent Pi testing proved that `USB08_8G`:

- writes, closes, renames, rereads, and preserves four 8,388,864-byte files
  using 16/32/64/96 KiB requests;
- produces identical hashes after unmount/remount;
- rejects SCSI SYNCHRONIZE CACHE; and
- retains a clean FAT filesystem after test cleanup.

Controller A testing also exposed a separate blocker: after a guarded USB VBUS
cycle, USBX and FileX re-enumerate the drive but application media handoff
remains at acceptance mask `11`, not `15`, until controller reset.

Evidence:

- `work/evidence/controller-a-usb08-function-qualification-20260729.md`
- `work/evidence/usb08-rpi-controller-like-write-test-20260729.md`
- `work/evidence/controller-a-general-udisk-sync-cache-failure-20260728.md`
- `work/evidence/controller-a-usb-vbus-electrical-proof-20260728.md`

## Execution update — 2026-07-30

Implemented and software-gated:

- `script/check-usb-transaction-inventory.ps1` now fails on enabled-host-class,
  USB request, HCD operation, or SCSI-opcode drift.
- SYNCHRONIZE CACHE compatibility now accepts any completed command with valid
  `ILLEGAL REQUEST` sense while retaining transport and other-sense failures.
- READ CAPACITY fails closed, redundant READ FORMAT CAPACITIES retries were
  removed, INQUIRY requires a complete successful response, START STOP and
  READ retries are bounded and sense-aware, and ambiguous WRITE is not replayed.
- Fresh-session VBUS remount waits service deferred FileX media handoff and
  reach acceptance mask `15`.
- Focused USB workflow and transaction-inventory checks pass.
- Canonical Debug and Release builds completed. Current hashes are:
  - Debug S-record:
    `3577E3AFDD9AD9758B0DB0BBEF954A712586D1B10FA8D74F479A3856A14E3D4E`
  - Release S-record:
    `E706B043AC4C7BCB41FBECD5C92C2D2E8A5372C0662A981D99D19F312DDA22A0`

Hardware evidence:

- Controller B and then Controller A ran the Debug candidate with their
  expected SD CIDs and mounted `USB08_8G` at acceptance mask `15`.
- Both passed WAV load/sound, PID publication with post-cycle verification,
  8,388,864-byte image save with full post-cycle CRC verification, image
  update staging, and explicit VBUS/remount with zero live system errors.
- The original 5-second unsupported-cache quiescence allowed a late-committing
  rename to be absent at the immediate post-cycle check. The file appeared
  after a later controller reboot. A 30-second quiescence passed on both
  controllers, but the drive activity indicator was inactive for most of that
  interval; the fixed delay is safe but operationally excessive.
- Controller B had no retained HPT records, so a meaningful HPT export could
  not be run (`retained_records=0`, invalid retained bounds).
- Controller A rollback flash was captured before deployment:
  `38108F259826C6CED0168CF9483AF79BD841703543A19564A55CB6BC2A728A83`.
- Final Release deployment was started but interrupted before it completed or
  was verified. Do not represent either controller as Release-deployed.

Current decision point:

- There is no standards-defined readiness query that proves internal NAND
  cache persistence after a device rejects SYNCHRONIZE CACHE. TEST UNIT READY
  and successful reads can still observe volatile device state.
- Determine the shortest repeatedly passing bounded fallback interval
  (beginning at 10 seconds, then 15 seconds if required), while retaining the
  mandatory VBUS/remount/full-CRC qualification proof.

Resolution:

- The 10-second interval passed three consecutive Debug trials on B and three
  on A, followed by Release image/VBUS qualification on B then A and a clean
  independent Pi check.
- Both controllers now contain the identical verified Release image.
- See
  `work/evidence/usb08-command-compatibility-release-qualification-20260730.md`.
- The compliant-cache control path also passed on B then A with `USB04_32G`;
  its compatibility flag remained clear and cumulative fallback count did not
  increase. See
  `work/evidence/usb04-compliant-sync-release-qualification-20260730.md`.
- Controller A then published a meaningful 6,973-record retained HPT export
  to `USB04_32G`. The terminal state, fresh-session full-file verification,
  clean independent Pi FAT check, CSV completion trailer, and exact hash all
  passed; the compatibility flag remained clear and the cumulative fallback
  count stayed unchanged. See
  `work/evidence/usb04-compliant-sync-hpt-export-release-qualification-20260730.md`.
- Controller A published the equivalent retained-range HPT export to
  `USB08_8G`. Valid ILLEGAL REQUEST sense selected compatibility, the count
  increased, the 10-second bound was observed, a fresh media generation
  remounted at acceptance mask `15`, and all 350,921 bytes were verified.
  Independent Pi FAT, CSV trailer, and hash inspection passed. See
  `work/evidence/usb08-compatibility-hpt-export-release-qualification-20260730.md`.
- A guarded seven-case one-shot target matrix passed on A and B: sync timeout,
  malformed sense, Medium Error, START STOP ILLEGAL REQUEST, START STOP
  timeout, checksum mismatch, and remount failure. The first lifecycle run
  found and corrected a pre-command compatibility sampling error; the
  corrected candidate rebuilt, deployed B then A, and passed both targets.
  See
  `work/evidence/usb-negative-fault-injection-release-matrix-20260730.md`.

## Final closeout — 2026-07-30

Final Release retesting is complete:

- `USB05_4G` passed Controller B and Controller A on the compatibility path,
  including WAV, PID followed immediately by image save, full fresh-session
  verification, update/reboot, and clean independent Pi inspection.
- `USB07_32G` passed the same B-then-A sequence on the compliant-cache path.
  Its slower post-reboot readiness was observed to a bounded clean terminal
  state rather than classified from an intermediate 30-second snapshot.
- `USB06_1G` remained retired and was not retested.
- Both final Pi inspections found clean FAT filesystems, exact image/PID
  hashes, no temporary/partial/backup file, and left the drives unmounted.
- Final full 4 MiB internal-flash captures from A and B match at
  `5DA4A19C10DAEEC6B812B314FF2D155F1ED044AE62F43B226CB13BB31060E932`.
- The executable transaction-inventory and USB workflow checks pass.

Final evidence:

- `work/evidence/usb05-final-release-qualification-20260730.md`
- `work/evidence/usb07-final-release-qualification-20260730.md`
- `work/evidence/usb-command-compatibility-final-release-closeout-20260730.md`

The older unchecked execution-plan boxes below are retained as the original
planning decomposition. The dated execution updates and linked direct evidence
are the authoritative completion record; items that proposed broader synthetic
protocol testing than the reachable production implementation were satisfied
by the executable reachable-transaction inventory plus bounded target fault
matrix, not by claiming an exhaustive USB conformance laboratory.

## Recommendation

Adopt a command-class policy for unknown USB mass-storage devices rather than
a VID/PID, model, or exact ASC/ASCQ allowlist:

- Always attempt SYNCHRONIZE CACHE.
- When transport completes and the sense key is `ILLEGAL REQUEST`, classify
  SYNCHRONIZE CACHE as unsupported for that media session, regardless of
  ASC/ASCQ, and require a fresh-powered-session verification barrier.
- Treat optional discovery-command `ILLEGAL REQUEST` responses as unsupported
  features and continue with conservative defaults.
- Treat optional lifecycle-command `ILLEGAL REQUEST` responses as unsupported
  and use the same fresh-session barrier when durability depends on them.
- Never tolerate timeout, no response, transport failure, disconnect,
  unresponsive media, Medium Error, Hardware Error, Data Protect, Aborted
  Command, or an error from essential READ/WRITE/capacity operations.
- Bound recovery to one sense collection, one transport/reset-recovery
  attempt, one re-enumeration attempt, and one USB-port power cycle. Never
  leave the controller waiting indefinitely.

Do not report a compatibility-path save as successful until the controller
has powered the USB port off, established a new media-session generation,
remounted, and verified filename, exact size, completion marker where
applicable, and full payload CRC/hash.

## Current State

Completed:

- SCSI SYNCHRONIZE CACHE is wired into `FX_DRIVER_FLUSH`.
- Sense key/ASC/ASCQ are available from the USBX storage instance.
- A session compatibility flag and count exist.
- Atomic temporary-file publication, readback, completion-marker checks, VBUS
  control, and durability telemetry exist.
- Controller A VBUS control is electrically proven.
- USB08 boot-sector/MBR classification is corrected.
- USB08 conventional-write behavior and SYNCHRONIZE CACHE rejection are
  independently reproduced.

Incomplete:

- Capability and durability outcome are not represented as explicit
  per-session states.
- Successful compatibility classification is not cleanly separated from
  durable publication success.
- The fixed 30-second compatibility quiescence is safe in the observed run but
  has not been reduced to the shortest repeatedly proven bound.
- The VBUS fallback is qualified for image save and PID capture on A/B, but
  HPT export remains blocked by the absence of retained HPT records on B.
- Unknown-drive timeout and malformed-response bounds lack focused tests.
- The Release artifact is built but has not completed B-first/A-second
  deployment, Release-specific verification, or independent Pi validation.

## Goal

Ship controller firmware that supports a broad, unknown population of USB
mass-storage drives without weakening data-integrity claims: compliant drives
use SYNCHRONIZE CACHE, drives that explicitly reject optional durability or
lifecycle commands use a verified power-cycle/remount barrier, and genuinely
failing media are rejected promptly and diagnostically.

## Major Outcomes

- Complete compatibility policy for every reachable root-port operation, USB
  standard request, Mass Storage class request, BOT phase/recovery action, and
  SCSI command—not only durability CDBs.
- Command-class result policy independent of drive brand, model, VID/PID, or
  exact optional-command ASC/ASCQ.
- Explicit media-session capability and durability status.
- Reliable disconnect/re-enumeration/remount with no stale FileX or USBX
  pointer crossing a media generation.
- Atomic customer workflows that return success only after the selected
  durability barrier passes.
- Bounded failure and recovery behavior for unknown or defective drives.
- Canonical Debug and Release builds, controlled B-first/A-second deployment,
  complete workflow qualification, independent Pi verification, and retained
  rollback artifacts.

## Delivery Stages

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 0. Workspace checkpoint | Execution starts from a reviewable source state and raw output has an ignored destination | Tool Shed preflight reports existing hard diff limit | Meaningful source/planning state is checkpointed by owner-approved method; fresh task started; generated evidence path verified ignored |
| 1. Full transaction audit and policy contract | Every reachable root-port operation, USB standard request, Mass Storage class request, BOT phase, and SCSI CDB has a compatibility decision, test, and bound | This workpackage, transaction inventory, and current USB evidence | ADR and executable inventory check reviewed; no device allowlist or unclassified transaction |
| 2. Middleware classification | SYNCHRONIZE CACHE `ILLEGAL REQUEST` becomes session-level unsupported capability while other failures remain fatal | USBX sense telemetry | Unit/static tests cover success, all ILLEGAL REQUEST ASC/ASCQ values, malformed sense, timeout, stall, disconnect, and non-ILLEGAL sense |
| 3. Session/remount correctness | USB-only power cycle always creates a fresh valid media handoff or terminates failed | Existing acceptance-mask `11` reproduction | Repeated A/B cycles reach mask `15`, increment generation, clear stale pointers, and preserve controller/SD health |
| 4. Workflow integration | Image, PID, and HPT publication select sync or power-cycle durability barrier and expose terminal outcomes | Stages 2–3 pass | Each workflow reports `DURABLE_SYNC`, `DURABLE_POWER_CYCLE`, or `FAILED`; no shared progress field acts as terminal authority |
| 5. Software gates | Candidate builds reproducibly and policy regressions are executable | Focused source changes complete | USB checks, focused host tests, canonical Debug rebuild, Release rebuild, packaging, and artifact/hash validation pass |
| 6. Canary deployment | Controller B proves candidate and rollback | Exact B baseline and saved diagnostic firmware available | B flash verified; boot, CID, mount, normal control, and bounded USB smoke pass |
| 7. End-to-end qualification | Both durability paths and failure paths pass on hardware | B canary healthy | B then A complete image save/update, PID, HPT, WAV, VBUS/remount, negative-command injection, and Pi persistence checks |
| 8. Release/closeout | Final intended firmware is deployed with rollback and current truth recorded | All gates pass | Exact A/B firmware hashes recorded; docs/runbook updated; ticket reconciled; no temporary files; workpackage completed |

## Execution Plan

### 1. Freeze the behavioral contract

- Historical planning item: Resolve every item and finding in
      `work/inventories/inventory-usb-host-transactions-and-compatibility-policy.md`.
- Historical planning item: Add an executable static inventory gate that fails when the generated
      configuration enables a new host class/protocol or source adds an
      unclassified control request, class request, BOT action, or SCSI opcode.
- Historical planning item: Add runtime telemetry for request type/function, endpoint/direction,
      BOT phase, CDB opcode, transport result, CSW status/residue, and sense.
- Historical planning item: Prove the static list and runtime traces agree for boot enumeration,
      normal workflows, recovery, removal, and VBUS remount.
- Historical planning item: Create an ADR defining command classes and the three durability outcomes:
      `DURABLE_SYNC`, `DURABLE_POWER_CYCLE`, and `FAILED`.
- Historical planning item: Define optional discovery commands, optional lifecycle commands,
      durability commands, and essential media commands.
- Historical planning item: For SYNCHRONIZE CACHE only, map any completed-command
      `ILLEGAL REQUEST` sense to `unsupported`; retain raw key/ASC/ASCQ.
- Historical planning item: Require transport success and a responsive device before compatibility
      fallback; do not classify missing/malformed sense as unsupported.
- Historical planning item: Define conservative defaults for optional discovery failures.
- Historical planning item: Define one-retry/one-reset/one-power-cycle bounds and terminal timeouts.

### 2. Implement session capability telemetry

- Historical planning item: Replace global boolean-only compatibility state with per-storage-session
      state tied to media generation.
- Historical planning item: Capture opcode, transport status, sense key, ASC, ASCQ, retry count,
      fallback reason, and durability result.
- Historical planning item: Reset capability state on disconnect, VBUS transition, initialization,
      or storage-instance replacement.
- Historical planning item: Prevent compatibility state from one drive or LUN from crossing into
      another session.
- Historical planning item: Keep `FX_DRIVER_FLUSH` semantics explicit: return normal success for a
      successful sync; return a distinct internal compatibility-required
      outcome to the application path without hiding fatal failures.

### 3. Correct disconnect and remount lifecycle

- Historical planning item: Reproduce acceptance mask `11` using guarded VBUS control.
- Historical planning item: Identify which FileX media-open or USBX storage-media transition has not
      completed when the deferred handoff runs.
- Historical planning item: Clear stale media pointers and session state at disconnect before power
      is restored.
- Historical planning item: Publish `gIsUsbStickMounted` only after media ID, driver identity,
      storage instance, and session generation all match.
- Historical planning item: Require a new generation after VBUS cycle; reject stale pointer reuse.
- Historical planning item: Prove bounded recovery on both controllers with repeated cycles and
      without whole-controller reset.

### 4. Integrate the compatibility durability barrier

- Historical planning item: On successful SYNCHRONIZE CACHE, retain the normal atomic publication
      and readback path.
- Historical planning item: On classified unsupported SYNCHRONIZE CACHE, close the file, verify
      exact size and full CRC/hash, power-cycle USB VBUS, remount into a fresh
      generation, and verify name, size, marker, and CRC/hash again.
- Historical planning item: If START STOP UNIT is used and returns completed-command
      `ILLEGAL REQUEST`, classify it as unsupported and continue only through
      the fresh-session barrier.
- Historical planning item: Never power-cycle after an incomplete write, transport error, media
      error, checksum mismatch, or ambiguous session state merely to convert
      failure into success.
- Historical planning item: Apply the same terminal policy to image save, PID capture, HPT export,
      and diagnostic write-size workflows.
- Historical planning item: Refresh file lists after successful remount so a newly saved update
      image is immediately selectable.

### 5. Build and software verification

- Historical planning item: Test USB device/configuration descriptor handling, SET_ADDRESS,
      SET_CONFIGURATION, endpoint discovery, and root-port reset/recovery
      timing with valid, stalled, short, malformed, delayed, and disconnected
      devices.
- Historical planning item: Test GET_MAX_LUN defined-stall behavior, malformed/short response,
      excessive LUN, BOT CBW/data/CSW validation, phase error, class reset,
      endpoint-halt clearing, and data-toggle recovery.
- Historical planning item: Replace guessed capacity success with validated READ CAPACITY behavior;
      remove or reduce redundant READ FORMAT CAPACITIES probing; validate
      standard INQUIRY command completion and response structure.
- Historical planning item: Replace indiscriminate START STOP and READ/WRITE retries with
      sense-aware, idempotency-aware bounded handling.
- Historical planning item: Add focused policy tests covering all 256 ASC values and representative
      ASCQ values under `ILLEGAL REQUEST` without treating other sense keys as
      compatibility success.
- Historical planning item: Add negative tests for timeout, transport stall, malformed/no sense,
      disconnect, Medium Error, Hardware Error, Data Protect, Aborted Command,
      and READ/WRITE/capacity failure.
- Historical planning item: Add lifecycle tests proving state reset and stale-pointer rejection.
- Historical planning item: Run `.\script\check-usb-mass-storage-workflows.ps1`.
- Historical planning item: Run any focused USB host-side tests introduced by this work.
- Historical planning item: Run the canonical Debug rebuild:
      `.\script\vscode-e2-build.ps1 -Action Rebuild -Configuration Debug -Jobs 8`.
- Historical planning item: Run the canonical Release rebuild with `-Configuration Release`.
- Historical planning item: Package and validate exact ELF/S-record hashes and preserve rollback
      artifacts. Do not use the isolated headless experiment.

### 6. Controlled deployment

- Historical planning item: Capture preflash A/B firmware hashes, controller identities, reported
      state, and SD CID blocks.
- Historical planning item: Preserve the exact pre-change images plus the current USB diagnostic
      image as rollback artifacts.
- Historical planning item: Program Controller B first; verify flash against the candidate image.
- Historical planning item: Require normal boot, unchanged SD CID, normal control operation, clean
      USB mount, and no new system errors before broader testing.
- Historical planning item: If B fails a controller-health or rollback gate, restore B and stop.
- Historical planning item: After B passes end-to-end canary gates, program A and repeat the same
      identity and health gates.

### 7. End-to-end hardware matrix

- Historical planning item: Compliant path: use a drive known to accept SYNCHRONIZE CACHE; require
      `DURABLE_SYNC` for image, PID, and HPT outputs.
- Historical planning item: Compatibility path: use `USB08_8G`; require
      `DURABLE_POWER_CYCLE`, fresh generation, mask `15`, and exact post-cycle
      verification for image, PID, and HPT outputs.
- Historical planning item: Lifecycle-command path: exercise or fault-inject unsupported START STOP
      UNIT and prove the same bounded fresh-session barrier.
- Historical planning item: Negative path: inject timeout, transport failure, non-ILLEGAL sense,
      checksum mismatch, and remount failure; require `FAILED`, no false
      publication, bounded termination, and recoverable controller state.
- Historical planning item: Update round trip: save the current pinned image, refresh the selector,
      program it, verify internal flash hash, and confirm normal reboot.
- Historical planning item: WAV regression: enumerate, load, and trigger both established WAV files.
- Historical planning item: Repeat the matrix B first, then A, preserving controller-specific CID
      evidence at baseline and after relevant reboot.
- Historical planning item: After each drive/controller run, move the drive to the Pi, identify it
      by canonical label and stable hardware identity, run non-repairing FAT
      checks, verify filenames/sizes/hashes/markers, and confirm no temporary
      files or divergent FATs.
- Historical planning item: Restore each drive to its documented input baseline and leave it
      unmounted on the Pi before the next physical move.

### 8. Release and closeout

- Historical planning item: Compare Debug qualification and Release artifacts; deploy the intended
      final configuration only after its own build/hash gate.
- Historical planning item: Record exact final A/B firmware hashes and retained rollback hashes.
- Historical planning item: Promote command-class and durability policy to
      `docs/firmware-update-validation-and-recovery.md`.
- Historical planning item: Add or update the repeatable USB compatibility qualification runbook.
- Historical planning item: Reconcile
      `work/tickets/ticket-investigate-usb-drive-enumeration-and-post-save-workflow-compatibility.md`
      and the project map.
- Historical planning item: Refresh `work/index.md`/`work/index.json`, run work-state review and
      stale-path checks, then complete this workpackage with the helper.

## Acceptance Criteria

- Historical planning item: The executable inventory proves every transaction reachable from the
      release configuration is classified; adding or enabling an unclassified
      transaction fails the build/check.
- Historical planning item: USB enumeration, descriptors, address/configuration, endpoint discovery,
      GET_MAX_LUN, BOT transfers/reset recovery, root-port lifecycle, and every
      reachable SCSI opcode have nominal, malformed, timeout, stall,
      disconnect, and bounded-recovery coverage appropriate to that command.
- Historical planning item: READ CAPACITY failure cannot silently become guessed 512-byte media
      success, and an ambiguous WRITE is not blindly repeated.
- Historical planning item: No production decision depends on USB VID/PID, product string, serial,
      capacity, brand, or a laboratory approved-drive list.
- Historical planning item: Any completed SYNCHRONIZE CACHE `ILLEGAL REQUEST` selects compatibility
      mode, while every non-ILLEGAL or transport-level failure remains fatal.
- Historical planning item: Optional discovery commands fall back to documented conservative
      defaults without weakening essential READ/WRITE/capacity errors.
- Historical planning item: Compatibility state is isolated to one media session and cannot survive
      disconnect, VBUS cycle, reinitialization, LUN change, or drive change.
- Historical planning item: USB-only power cycle and remount reliably reaches acceptance mask `15`
      with a new generation on both controllers.
- Historical planning item: `USB08_8G` completes image save, PID capture, and HPT export with
      post-power-cycle exact verification and a clean FAT filesystem.
- Historical planning item: A compliant control drive continues to complete the normal sync path.
- Historical planning item: Timeout, no response, malformed sense, transport failure, device loss,
      non-ILLEGAL sense, essential-command failure, checksum failure, and
      remount failure all terminate bounded and never report durable success.
- Historical planning item: Newly saved update images appear without physical reseating and complete
      a verified update round trip.
- Historical planning item: Controller B then A pass normal control, SD identity, WAV, USB workflow,
      reboot, and independent Pi persistence gates.
- Historical planning item: Canonical Debug and Release builds, packages, hashes, deployment
      identities, rollback artifacts, and compact evidence manifests are
      recorded.

## Stop and Rollback Conditions

- Unexpected controller, J-Link serial, USB canonical label, SD CID, firmware
  hash, partition layout, or mount state.
- Any request to test retired `USB06_1G`.
- Any powered SD-card insertion or removal.
- Any stale media pointer, unchanged generation after VBUS transition,
  acceptance mask other than `15`, ambiguous terminal authority, or controller
  responsiveness loss.
- Any FAT corruption, divergent FAT copies, missing durable file, unexpected
  temporary file, checksum mismatch, or failure to restore a test-drive
  baseline.
- Any compatibility decision based on a timeout, missing sense, transport
  error, or non-ILLEGAL sense.
- On a canary failure, stop deployment, preserve evidence, and restore the
  exact preflash firmware before proceeding.

## Related Artifacts

- Ticket:
  `work/tickets/ticket-investigate-usb-drive-enumeration-and-post-save-workflow-compatibility.md`
- Spike:
  `work/spikes/spike-explore-usb-drive-workflow-compatibility-across-controllers-a-and-b.md`
- Evidence:
  `work/evidence/controller-a-usb08-function-qualification-20260729.md`
- Evidence:
  `work/evidence/usb08-rpi-controller-like-write-test-20260729.md`
- Evidence:
  `work/evidence/controller-a-general-udisk-sync-cache-failure-20260728.md`
- Inventory:
  `work/inventories/inventory-usb-host-transactions-and-compatibility-policy.md`

## Open Questions

- Whether the application needs a distinct internal return code from
  `FX_DRIVER_FLUSH`, or whether the session capability flag plus workflow
  durability state is the cleaner separation.
- Whether START STOP UNIT adds value once fresh-session power-cycle
  verification is mandatory for the compatibility path.
- Whether full-file CRC is sufficient for every workflow or selected formats
  should additionally validate their embedded image hash/structure.

These questions are resolved during Stages 1–4 and must not weaken the
acceptance criteria.

## Completion Standard

This workpackage is complete when the command-class policy is documented and
implemented, remount is reliable, both durability paths and all negative
paths pass focused tests, the canonical Release candidate is deployed B first
then A with exact identity evidence, the complete customer USB workflow bundle
passes independent Pi persistence validation, rollback artifacts are retained,
and current truth plus repeatable operations are promoted to docs/runbooks.

## Closeout Routing

- Current truth promoted to:
  `docs/firmware-update-validation-and-recovery.md`
- Historical context remains in:
  `work/evidence/` and the completed workpackage
- Runtime/status evidence:
  `work/evidence/generated/` with compact versioned manifests
- Cleanup deferred to:
  none; generated test files must be removed from USB specimens and each
  specimen returned to its documented baseline before closeout
