# ADR: Adopt 32 KiB USB HPT production write cap

Status: accepted
Type: adr
Updated: 2026-08-01
Next Action: none; the accepted 32 KiB decision passed USB09, the broad matrix, enumeration recovery, BOT validation, and representative regression
Parent: work/maps/map-smi-firmware-stabilization-and-qualification.md
Supersedes:
Superseded By:

## Context

The previous 1 KiB production behavior left substantial USB performance
available. Diagnostic 16/32/64/96 KiB tiers demonstrated headroom, but the
first isolated 64 KiB production HPT candidate exposed lifecycle false-success
failures. R5 corrected the lifecycle independently, after which an isolated
32 KiB production cap passed the available four-drive matrix on Controller A
and representative 2 GB/32 GB cross-controller coverage on Controller B.

All six production exports reached terminal success with zero USB/HPT errors
and passed independent Pi persistence checks. The owner considers the 32 KiB
performance improvement over 1 KiB sufficient.

## Decision

Adopt 32 KiB as the production maximum for each HPT FileX write. Do not pursue
64 KiB or greater production HPT write caps at this time.

The 128 KiB SDRAM staging window and 128 KiB USBX BOT phase are separate
buffer/transport bounds and do not authorize FileX calls above 32 KiB.
A future increase requires an explicit owner decision and a new isolated
candidate with fresh qualification; prior diagnostic results are not promotion
evidence.

## Consequences

Positive:

- Materially better HPT export performance than the prior 1 KiB behavior.
- Qualified behavior across both controller assemblies and all four available
  USB specimens without a brand/model allowlist.
- Lower compatibility and lifecycle risk than promoting the larger diagnostic
  sizes.

Negative:

- Some devices may support faster 64 KiB or larger writes, but that additional
  performance is intentionally left unused.
- The three drives with preserved FAT summary mismatches remain useful
  compatibility specimens but are not clean-filesystem qualification evidence.

## 2026-07-31 recovery application

The restored 1 KiB Stage 1 baseline is now disproven by USB09. On clean
pretested media, the 1 KiB candidate requested 99,328 bytes in 97 calls, spent
70.69 seconds in writes, then timed out in `fx_file_close()` after exactly 50
seconds with `UX_TRANSFER_TIMEOUT`; independent Pi inspection found an
incomplete temporary file and inconsistent FAT metadata. The same specimen's
clean prior 32 KiB run wrote 374,707 bytes in 12 calls, closed in 0.01 seconds,
and produced a complete independently verified CSV.

This evidence authorizes a new isolated 32 KiB recovery discriminator even
though the 1 KiB Stage 1B gate did not pass. It does not authorize promotion
without USB09 regression and the broad compatibility matrix. No drive
identity, transport fork, timeout replay, VBUS action, or other behavior may
be bundled with the write-cap change.

## Alternatives Considered

- Retain the prior 1 KiB behavior: rejected because 32 KiB provides qualified,
  materially better performance.
- Promote 64 KiB now: rejected because the owner is satisfied with 32 KiB and
  does not want further larger-cap qualification.
- Use per-brand or per-model caps: rejected; the accepted policy remains
  capability-neutral for the tested population.

## Supersession Notes

This decision closes the earlier planning preference for a 64 KiB production
successor recorded in historical workpackage text; no earlier ADR is
superseded.
