tighten transport failure semantics

docs/transport-layer-validation-2026-08-17.md

@@ -6,23 +6,38 @@ ESP-IDF's interrupt-driven USB Serial/JTAG driver.
 
 ## Transaction contract
 
-- `RETRY`: the backend accepted zero bytes, so whole-frame resubmission is safe.
+- `RETRY`: valid only from initial submission; the backend accepted zero bytes,
+  so whole-frame resubmission is safe.
 - `PENDING`: the backend owns an in-flight frame. Only completion polling is
   allowed; the caller must retain and not modify the packet buffer.
-- `COMPLETE`: the backend's completion criterion is satisfied and the caller may
-  reuse the packet buffer.
+- `COMPLETE`: the backend's documented completion criterion is satisfied and the
+  caller may reuse the packet buffer. USB means endpoint drain; reliable BLE
+  will mean application acknowledgement of the exact frame.
 - `FATAL`: a programming or backend invariant failed. The output task stops
   consuming the sample queue rather than silently discarding its in-flight data.
+  `RETRY` from a pending poll is promoted to `FATAL` because generic code cannot
+  prove resubmission is duplicate-safe.
 
 For USB, submission uses a 512-byte TX ring and a bounded 50 ms write. ESP-IDF's
 ring-buffer send is all-or-nothing for each `TRK1` frame. Once accepted, bounded
 50 ms `usb_serial_jtag_wait_tx_done()` calls continue returning `PENDING` until
-the host drains the endpoint. A timeout never resubmits the frame.
+the host drains the endpoint. The first completion poll happens immediately
+after acceptance; repeated pending polls are scheduler-paced. A timeout never
+resubmits the frame.
 
 The VFS is switched to driver mode after readable startup output so any
 unexpected diagnostic output cannot race the driver's ISR by accessing the
 hardware FIFO directly. Firmware logs are disabled before binary telemetry
-tasks start, as before.
+tasks start, as before. A terminal transport invariant re-enables error logging,
+emits one final diagnostic, and suspends the output task. Because no later binary
+frame can follow, that diagnostic cannot corrupt a recoverable stream.
+
+Queue-allocation and task-creation failure paths switch the VFS back to its
+non-driver mode and uninstall the USB driver before emitting their error, so the
+only startup diagnostic is not stranded in a TX ring that is immediately freed.
+The USB backend's zero-write-to-`RETRY` mapping depends explicitly on its checked
+initialized/sole-owner lifecycle; a torn-down backend fails the guard as
+`FATAL` instead of masquerading as backpressure.
 
 ## Verification
 
@@ -33,12 +48,24 @@ The host C transport fixture compiles the production state machine with
 - accepted transfers become pending;
 - repeated pending polls never call submission again;
 - completion returns the sender to idle;
-- backend-confirmed safe retry returns to idle;
+- retry returned after acceptance fails closed without resubmission;
 - invalid arguments and unknown backend states fail closed.
 
-The assembled ESP32-C3 prototype produced a normal 1,728-sample direct-driver
-capture with no packet gaps, sample gaps, resets, CRC failures, reported drops,
-loop overruns, trailing partial bytes, or timestamp-saturation frames.
+The assembled ESP32-C3 prototype first produced a normal 1,728-sample
+pre-commit direct-driver capture with no packet gaps, sample gaps, resets, CRC
+failures, reported drops, loop overruns, trailing partial bytes, or
+timestamp-saturation frames.
+
+After commit `3c95f3d` was built and flashed exactly, a second capture contained
+1,680 contiguous samples, sequences 0 through 1,679, with the same zero-loss
+integrity result. Its optional raw wire file contains all 563 startup bytes and
+re-decodes to CSV byte-for-byte identical to the live-rendered CSV. Both sides
+of that exact capture are tracked as fixtures:
+
+- `tests/fixtures/direct_usb_3c95f3d.trk`, SHA-256
+  `f495486f094a758bb785e145026e3934d60b52dd5083aef7f5d896195d967869`
+- `tests/fixtures/direct_usb_3c95f3d.wire`, SHA-256
+  `3bdaeadff7962c6eac48c4ebeda285c8eb359e439d5e1728104add2009122c03`
 
 For the connected-stall case, the USB endpoint was left enumerated without a
 serial reader long enough to overflow the 512-sample acquisition queue. When the