Add over-the-air fieldtest harness to sonance-cli

Single-machine acoustic loopback measurement: play a seeded corpus out
the speaker, record it on the mic, decode, and report PER / sync rate /
goodput / estimated SNR per payload size. This closes the gap between the
simulation-only BER gates and real-hardware behavior.

- New `fieldtest` subcommand (--profile/--trials/--sizes/--gap-ms/
  --capture-dir/--json), composed from the existing CpalSink/CpalSource,
  resampling, and WavSink plumbing; no DSP/codec changes.
- Pure, hardware-free scoring + JSON builder (xtask build_json style),
  covered by unit tests including a clean-loopback success and a
  noise->NoSync integrity check.
- docs/field-results.md: reproduction steps, column semantics, honest
  caveats, and a template for the first real run.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: sjqtentacles

docs/field-results.md

@@ -0,0 +1,83 @@
+# Over-the-air field results
+
+This is the real-hardware counterpart to the simulated sweeps in
+[`docs/architecture.md`](architecture.md). Every BER/room/drift number elsewhere
+in the project is measured against the seeded `sonance-sim` channel; this page
+records what actually happens when the signal travels through a real speaker,
+the air, and a real microphone.
+
+Measurements are produced by the `sonance fieldtest` subcommand (see
+[`sonance-cli/src/main.rs`](../sonance-cli/src/main.rs)), which plays a seeded
+corpus out the default output device, records it back on the default input
+device (single-machine acoustic loopback), decodes the capture, and scores it.
+
+## How to reproduce
+
+```bash
+# Build the CLI (cpal backend is on by default for sonance-cli).
+cargo build -p sonance-cli --release
+
+# Disable OS voice processing first (AEC / noise-suppression / auto-gain), or
+# the loopback will not decode. The tool warns when capture is not raw.
+
+# Run a loopback sweep. Defaults: profile balanced, 10 trials, sizes 64,256,1024.
+cargo run -p sonance-cli --release -- fieldtest
+
+# A fuller run, dumping each capture to WAV for inspection and emitting JSON:
+cargo run -p sonance-cli --release -- fieldtest \
+    --profile balanced --trials 20 --sizes 64,256,1024,4096 \
+    --gap-ms 500 --capture-dir target/captures --json > target/fieldtest.json
+```
+
+Outputs:
+
+- a human-readable table (PER, sync rate, goodput, estimated SNR per size),
+- `target/fieldtest.json` (or stdout with `--json`), in the same hand-built
+  JSON shape as the `xtask` sweeps so it drops into the same tooling,
+- optional per-trial WAV captures under `--capture-dir`.
+
+## What the columns mean
+
+| Column | Meaning |
+|--------|---------|
+| `sync %` | Fraction of trials where the chirp matched filter detected a frame (whether or not it then decoded). Separates sync failures from FEC failures. |
+| `ok %` | Fraction of trials that decoded byte-exact (1 - PER). |
+| `PER` | Packet error rate over the trials. |
+| `goodput b/s` | `success_rate * payload_bits / time_on_air`, the same formula as the `xtask` sweeps. |
+| `est SNR dB` | A recorded signal-vs-silence RMS ratio. **This is an estimate, not a dialed Es/N0** — the mic never hears pure signal — so it is *not* directly comparable to the simulator's `snr_db`. Use it only as a relative indicator of the run's conditions. |
+
+## Honest caveats
+
+- **Single-machine loopback** measures the speaker -> air -> mic path of *one*
+  device. It captures the real DSP/sync/FEC behavior over real hardware, but it
+  is not the same as two independent devices with independent clocks. Two-machine
+  TX/RX is the planned follow-on.
+- **OS voice processing** (echo cancellation, noise suppression, AGC) destroys
+  the modem signal. The tool warns when `raw_capture()` reports non-raw; results
+  recorded with processing on are not meaningful.
+- **Acoustic coupling** depends heavily on volume, distance, and room. These
+  are physical conditions the operator sets, not parameters the tool dials.
+
+## Results
+
+> Status: harness landed; first real run pending on hardware with raw capture.
+> Fill in the table below from `target/fieldtest.json` after a run. Record the
+> exact conditions so the numbers are interpretable and reproducible.
+
+### Run 1 — _pending_
+
+- Date: _TBD_
+- Device (speaker + mic): _e.g. MacBook Pro 14" built-in_
+- Room / distance / volume: _e.g. quiet office, self-loopback, ~70% volume_
+- Raw capture: _yes/no_ (must be yes for valid numbers)
+- Profile: `balanced`
+- Trials per size: _N_
+
+| Payload | sync % | ok % | PER | goodput b/s | est SNR dB |
+|--------:|-------:|-----:|----:|------------:|-----------:|
+| 64 B    |        |      |     |             |            |
+| 256 B   |        |      |     |             |            |
+| 1 KB    |        |      |     |             |            |
+
+Notes: _what worked, what didn't, how it compares to the sim sweep at a
+similar estimated SNR._