[tap]

What this changes

PR 2 of the comparison plan (after #73 and #75; rational follows). The bridge engine measured against the four resampler libraries at exactly 44.1 ↔ 48 kHz, both directions, in quality, latency, host throughput and embedded instruction counts — and the competitor tooling hoisted to the family level so it could be.

• tools/compare/ now holds what every engine's comparison measures the competitors with: the fetch recipes (r8brain, SpeexDSP, and the libsamplerate tarball recipe that was inline in async's icount CMake), the notebook shims (renamed tap_sr_cmp_*, plus a new soxr shim because python-soxr exposes only the named recipes, not the custom quality spec the matched rows need), the bare-metal mutex stub and a warnings policy. async references it through TAP_SR_COMPARE_TOOLS; the old tap_sr_async_* shim and target names are retired words.
• bridge/bench/compare (host, Google Benchmark) and bridge/bench/icount/cmp_main.cpp (M33/M55/Hexagon, 2 s and 4 s, both directions, 40 binaries per target). compare.yml measures both engines' binaries from one list (scripts/compare_binaries.sh) and harvests one record per engine (harvest_compare.py --prefix); update_compare_docs.py derives both docs' blocks, async's byte for byte as before.
• bridge/notebooks/bridge_comparison.ipynb, executed: the AES17-style instrument calibrated at both output rates, the matched-setting sweep, THD+N and DR at the 24-bit interface, latency.
• bridge/docs/COMPARISON.md and the family index docs/COMPARISON.md at the root; README and plan links.

Why

The async comparison asked what clock recovery costs. bridge exists for one ratio pair, so its question is different and cleaner: at that pair, what does each library need to reach economy (70 dB, 18 kHz) and transparent (120 dB, 20 kHz), and what does it pay for it? The matching rule is stated once and applied by measurement: a competitor's matched setting is its cheapest whose measured stopband is at least the tier's and whose passband droops no more than 0.1 dB at the tier's edge, in both directions; its frontier is its best. The notebook asserts the picks against the constants the benches compile in, so the benches cannot drift from the measurement.

Verification

• Matched settings (notebook, asserted): economy — libsamplerate MEDIUM (its FASTEST droops 4 dB at 18 kHz), soxr 16-bit at a 0.816 passband (its lowest precision), r8brain 70 dB at a 12 % band, SpeexDSP quality 3; transparent — BEST, HQ, r8brain 120 dB at 6 %, SpeexDSP quality 9 (its fixed-point build cannot reach 120 dB, asserted None).
• Quality (notebook, 24-bit interface, asserted for bridge's rows): economy −91.4 / −86.2 dB THD+N by direction, its 70 dB imaging floor; transparent −141.7 / −142.9 dB, at the ceiling with every frontier setting. r8brain's economy-matched setting is the one true 70 dB competitor (−88 dB, 71–72 dB worst product); the others overshoot by 15–50 dB because they offer nothing closer. The 16-bit rows (bridge economy Q15, SpeexDSP fixed-point) share the ~98 dB A-weighted floor.
• Embedded counts: CI-measured (run 37985746994, the first with the bridge binaries). The record reproduces the local derivation in every steady-state cell; two Hexagon construction cells round 0.1 M lower from a constant 1,620-instruction start-up offset on the runner. The async record re-measured on the same run is identical to the committed one in every count. Headline: bridge economy Q15 is the cheapest row on every target (209 / 419 / 235 instructions per stereo frame on M55 / M33 / Hexagon going down), 3× under r8brain's matched setting on the M55 and 13–34× on the soft-double targets.
• Host table: one session, median of 5, all 34 subjects. soxr and r8brain's FFT engines win raw throughput at 1.5–17× bridge's matched tier (paid in latency); bridge is 3–5× faster than the other polyphase engines (libsamplerate, SpeexDSP).
• Gates: the family battery, 305/305 with every engine's WERROR and the C ABIs on, zero warnings; clang-format and clang-tidy clean on the shims and the bridge comparison units (house naming, mandatory braces); retired-words clean; both workflows parse; update_compare_docs.py idempotent on both records; the async notebook re-executed against the renamed shims with every number identical.
• Not run: the compare-smoke CI job's new bridge targets on the hosted compilers (built locally with GCC; this PR's CI is its first run).

Notes for the reviewer

• The finding the doc states plainly: in float, r8brain's FFT block convolution undercuts bridge's direct-form polyphase at both tiers on every target (0.8–1.0× economy's per-frame cost, 0.3–0.6× transparent's), at 4–15× the latency. bridge wins in Q15, which r8brain lacks. PLAN.md section 7 defers the multistage and FFT levers "until a consumer pulls them"; this table is the measurement that says by how much.
• Negative construction cells (libsamplerate BEST on the M33, −1.3 / −3.1 M) are the 2 s / 4 s split's resolution, not a measurement; footnote ⁴ says so rather than clamping the derived number.
• Notebooks re-executed: bridge_comparison.ipynb is new; asrc_comparison.ipynb re-executed because its cell 1 names the shim targets. Both committed executed.
• Async's cmake/ and tools/ directories are gone; everything they held is under tools/compare/. PLAN.md section 4's layout tree gains the line; its migration record keeps the old paths as history.
• One new third-party fetch path, no new third party: the soxr shim links the system package the host bench already required.

🤖 Generated with Claude Code

https://claude.ai/code/session_01G3HxzEGiZp7jStoMuYNuBK

---

Generated by Claude Code