harden USB telemetry transport

README.md

@@ -73,12 +73,16 @@ records into versioned `TRK1` frames, isolating acquisition from brief transport
 stalls. CRC, packet and sample sequences, timestamps, and cumulative
 loss/overrun counters make permanent loss detectable by the receiver.
 
-The current ESP-IDF USB VFS path reports physical disconnects, but a connected
-host that stops draining can time out below stdio and still appear successful to
-firmware. The host can detect resulting loss from packet/sample sequences and
-CRC framing, but the device cannot count that case. A direct USB driver with
-bounded drain waits, and ultimately receiver acknowledgements with replay, are
-deferred to the common USB/BLE transport layer.
+USB telemetry now uses ESP-IDF's interrupt-driven USB Serial/JTAG driver behind
+a transport-neutral state machine. A complete frame is submitted atomically to
+the driver ring and remains pending across bounded drain timeouts; firmware does
+not resubmit it ambiguously or dequeue another frame. The 512-sample queue
+therefore also protects a connected endpoint that temporarily stops draining.
+
+USB drain confirms that bytes left the device endpoint, not that the capture
+application persisted them. Packet/sample sequences and CRC expose loss after
+the fact. End-to-end receiver acknowledgements and replay remain part of the BLE
+transport milestone.
 
 Measured end-to-end framing overhead is about 2.47 kB/s at 100 Hz, or 8.47
 MiB/hour before BLE link overhead.
@@ -132,10 +136,12 @@ Status bits:
 
 The binary capture tool auto-detects a single `/dev/cu.usbmodem*` device, stores
 only CRC-valid frames, renders CSV, and reports packet, sample, timing, status,
-drop, overrun, timestamp-saturation, and trailing-partial-byte totals:
+drop, overrun, timestamp-saturation, and trailing-partial-byte totals. An
+optional `--wire` path preserves every received byte, including startup text and
+damaged or partial frames, for forensic comparison:
 
 ```sh
-python tools/capture_binary.py
+python tools/capture_binary.py --wire captures/session.wire
 ```
 
 An existing `.trk` stream can be decoded again without hardware:
@@ -144,5 +150,8 @@ An existing `.trk` stream can be decoded again without hardware:
 python tools/decode_binary.py captures/session.trk captures/session.csv
 ```
 
+Live capture and offline decoding use the same integrity tracker, including
+wrap-aware packet/sample gap classification.
+
 `tools/capture_serial.py` remains available only for decoding captures from the
 older CSV-v3 firmware snapshots.