From 67a0c2d53219788bc2e892228cf0b4b8c32d63ca Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 09:49:25 +0000 Subject: [PATCH] A10: the stale prose, swept The roadmap's A10. Each claim below had gone stale against the tree: - Root PLAN.md: the layout said the book's bridge chapters were follow-up work. Part VI, the bridge engine, landed in #68 on 2026-10-08, and the rational engine is Part VII. The migration record's "bringing async's workloads under clang-tidy is follow-up work" now notes that A2 did it on 2026-10-12. - bridge/PLAN.md section 9: the "degenerate case" chapter, "explicitly deferred", is struck through and points at Part VI, which was written from the ANCHOR: comments the code carried from day one. - async/PLAN.md: the status line said v0.4.0, but the family is at 0.6.0 (D13). Roadmap item 1, construction as a ratcheted scenario, is marked done: construct_q15 landed on 2026-10-09 in 43f3e29. Item 3, tail latency, is marked done in part: A6 gates the worst single pull() in the QEMU ratchet, and the host p99/max is Block B's. - docs/AUDIT_2026-10_PLAN.md: "execution in progress" now reads executed. All 35 disposition rows are closed, and S0 to S5 are on main. - The comparison records: docs/COMPARISON.md ("The shared tooling") and each engine's COMPARISON.md (first caveat) state that the competitors are frozen by policy at their 2026-10-09 pins. Those are libsamplerate 0.2.2, r8brain-free-src 7.6 and SpeexDSP 1.2.1; async's host rows also use the Ubuntu 24.04 packages, soxr 0.1.3 among them. A newer competitor release is not tracked, and moving a pin re-runs compare.yml and the notebooks and re-dates the tables. The generated tables are untouched: update_compare_docs.py reproduces them as committed. The roadmap marks A10 landed. Prose only, so no code, count or ceiling moves. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016GKzq1VSdcMYCRMhddiMaf --- PLAN.md | 5 +++-- async/PLAN.md | 11 +++++++++-- async/docs/COMPARISON.md | 7 +++++++ bridge/PLAN.md | 9 +++++---- bridge/docs/COMPARISON.md | 5 +++++ docs/AUDIT_2026-10_PLAN.md | 2 +- docs/COMPARISON.md | 5 +++++ docs/ROADMAP.md | 2 +- rational/docs/COMPARISON.md | 5 +++++ 9 files changed, 41 insertions(+), 10 deletions(-) diff --git a/PLAN.md b/PLAN.md index b8576cf..59a830b 100644 --- a/PLAN.md +++ b/PLAN.md @@ -326,7 +326,7 @@ SampleRateTap/ │ the bare-metal mutex stub), hoisted from async/ by the bridge comparison ├── scripts/ icount.py, tidy.sh, fetch_hexagon_toolchain.sh, │ update_icount_docs.py, update_perf_docs.py, book_figures* -├── book/ (bridge chapters are follow-up work) +├── book/ Part VI is the bridge engine (#68), Part VII the rational engine ├── docs/ Doxyfile (both engines); migration/ (removed at step 4) ├── async/ │ ├── CMakeLists.txt README.md (+ icount table) PLAN.md @@ -618,7 +618,8 @@ run first in CI. Choices the plan left open: - clang-tidy keeps each repository's old coverage: both engines' tests and examples, and bridge's icount workloads. async's workloads were never - under the gate and fail it; bringing them in is follow-up work. + under the gate and fail it; bringing them in is follow-up work (since + done: the roadmap's A2, 2026-10-12). - ci-arm64 runs `-L '^async$'` (its old scope). TSan builds both engines and runs async only. - The ratchet is one matrix job per engine, each with its own plugin marker diff --git a/async/PLAN.md b/async/PLAN.md index a9ee725..110a00c 100644 --- a/async/PLAN.md +++ b/async/PLAN.md @@ -58,7 +58,7 @@ The boundaries are identity, not policy: ## 3. Status -**v0.4.0** — the family version (D13), in the SampleRateTap tree since the +**v0.6.0** — the family version (D13), in the SampleRateTap tree since the 2026 migration; before it, SampleRateTap v0.1.0 (the campaign's PR A–C6 in `docs/PERFORMANCE.md` "Sequencing & status"). The DspTap adoption (`bridge/PLAN.md` Appendix B) moved the FIR substrate out; the @@ -75,12 +75,19 @@ In expected order; each item lands as its own PR with its measurements. the two-length differencing the comparison workloads already use — so the ±3 % gate regains per-frame sensitivity on M33 and construction becomes a first-class number (`docs/PERFORMANCE.md`, "Known debt"). + *Done* (2026-10-09, 43f3e29): `construct_q15` is a gated scenario + beside the pipelines, so `pipeline_q15 − construct_q15` is the streaming + loop alone (`docs/PERFORMANCE.md`, "`construct_q15` — construction as a + gated scenario"). 2. **Timestamp clock recovery.** Accept per-block timestamps for sub-sample phase observation, so the servo no longer depends on FIFO counts alone and block-quantized transfer stops wobbling the ppm estimate (README, "Limitations"). 3. **Tail latency.** The p99/max per-call `pull(128)` benchmark the - metrics table promises. + metrics table promises. *In part* (the roadmap's A6): the worst single + `pull()` is gated in the QEMU ratchet (`callmax_pull_float`, + `callmax_pull_q15`); the host p99/max is measured on the bench in the + roadmap's Block B and recorded as a trend, never gated on CI. 4. **MSVC `/W4` triage**, then `TAP_SR_ASYNC_WERROR=ON` on the Windows leg. *Done* (the roadmap's A2): the one warning was C4324 on `spsc_ring`'s cache-line padding, off for async's own targets with its reason. diff --git a/async/docs/COMPARISON.md b/async/docs/COMPARISON.md index 8aa1dbd..5aae79f 100644 --- a/async/docs/COMPARISON.md +++ b/async/docs/COMPARISON.md @@ -319,6 +319,13 @@ cost for devices that construct at boot. ## Caveats, stated plainly +- **The competitors are frozen at their 2026-10-09 pins.** libsamplerate + 0.2.2, r8brain-free-src 7.6 and SpeexDSP 1.2.1 as `tools/compare/` pins + them (the host wall-clock rows also use soxr 0.1.3 and libsamplerate as + the Ubuntu 24.04 packages); a newer release of any of them is not tracked. + Moving a pin re-runs `compare.yml` and the notebook and re-dates every + table here + ([the family comparison](../../docs/COMPARISON.md#the-shared-tooling)). - **Hardware rows are datasheet values, not our measurement.** Silicon is characterized through an analog test loop with its own converters and a wider notch than the ±20 Hz used here; both differences flatter a number. diff --git a/bridge/PLAN.md b/bridge/PLAN.md index a961299..f9a8f1c 100644 --- a/bridge/PLAN.md +++ b/bridge/PLAN.md @@ -460,10 +460,11 @@ still holds on the new default, re-measured in the same test batteries.* `_format`, `_process_q15` / `_q31`, `_flush_q15` / `_q31`; 17 exported symbols, hidden visibility), the shape `rational`'s ABI set, since the family decided to keep fixed point at every engine's C boundary. -- **Book/white-paper chapter** ("the degenerate case"): explicitly deferred - past v0.1. Code is written anchor-friendly (`ANCHOR:` comments on the - load-bearing excerpts) from day one so the chapter can be added without - touching the code. +- ~~**Book/white-paper chapter** ("the degenerate case")~~: deferred past + v0.1, then written: the book's Part VI, the bridge engine (#68, + 2026-10-08), from "The degenerate case: 44.1 ↔ 48 as a type" to "Three + legs, and the bridge to the ASRC", its excerpts included live from the + `ANCHOR:` comments the code carried from day one. - **AmbiTap/HOA channel-count validation** (the HVX 16-channel story): deferred to the M7+ embedded campaign. diff --git a/bridge/docs/COMPARISON.md b/bridge/docs/COMPARISON.md index 1871a55..48de909 100644 --- a/bridge/docs/COMPARISON.md +++ b/bridge/docs/COMPARISON.md @@ -324,6 +324,11 @@ construction, so 2 × (2 s) − (4 s) lands just below zero. Read it as ~0. ## Caveats, stated plainly +- **The competitors are frozen at their 2026-10-09 pins.** libsamplerate + 0.2.2, r8brain-free-src 7.6 and SpeexDSP 1.2.1 as `tools/compare/` pins + them; a newer release of any of them is not tracked. Moving a pin re-runs + `compare.yml` and the notebook and re-dates every table here + ([the family comparison](../../docs/COMPARISON.md#the-shared-tooling)). - **The matching rule is ours.** 0.1 dB at the tier's edge and "stopband at least the tier's" are the two numbers that decide every matched row; the notebook prints the whole sweep so a different rule can be read off it. diff --git a/docs/AUDIT_2026-10_PLAN.md b/docs/AUDIT_2026-10_PLAN.md index 0b41294..6069443 100644 --- a/docs/AUDIT_2026-10_PLAN.md +++ b/docs/AUDIT_2026-10_PLAN.md @@ -1,6 +1,6 @@ # Audit response plan (v0.2) -Status: **decisions taken 2026-10-09** (section 6 records them); execution in progress; ✓ in the disposition table marks a closed row (S0 to S5 landed on the branch; ↗ marks a row referred outside this tree: F25 is a taphouse PR). Answers [`AUDIT_2026-10.md`](AUDIT_2026-10.md) (35 findings: +Status: **executed 2026-10-09** (section 6 records the decisions); every row of the disposition table is closed, ✓ marking a row closed here (S0 to S5 are on `main`; ↗ marks a row referred outside this tree: F25 is a taphouse PR). Answers [`AUDIT_2026-10.md`](AUDIT_2026-10.md) (35 findings: 4 major, 14 minor, 1 disputed, 16 nits) and the cohesion assessment that followed it: the family reads as one mind at the level of the plans and one vocabulary at the level of `bridge` and `rational`, while `async`, the oldest stratum, still speaks the dialect it was diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md index 6f4a478..fe73b1a 100644 --- a/docs/COMPARISON.md +++ b/docs/COMPARISON.md @@ -58,3 +58,8 @@ its tests. The embedded counts come from one manual workflow, per engine (`/bench/compare_counts.json`) that `scripts/update_compare_docs.py` derives the tables from and the `compare-docs` CI job gates. + +The pins are frozen by policy: every record here measures the family against +libsamplerate 0.2.2, r8brain-free-src 7.6 and SpeexDSP 1.2.1 as pinned on +2026-10-09, and a newer competitor release is not tracked. Moving a pin +re-runs `compare.yml` and every engine's notebook, and re-dates every table. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 48a9b81..39c73c9 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -124,7 +124,7 @@ gated on shipping. the root README, and have each consumer's bump commit name the tag (a submodule gitlink is a SHA; TapTools' and MuTap's pins are theirs to move). DspTap is tagged on its own cadence, never released in lockstep with this tree (Q4). -- **A10. Stale prose sweep.** `PLAN.md:328` and `bridge/PLAN.md` §9 still call the book's +- **A10. Stale prose sweep.** *Landed 2026-10-15: the root `PLAN.md` layout and `bridge/PLAN.md` §9 name the book's Part VI (#68) as written, and the migration record notes A2 closed its tidy exclusion; `async/PLAN.md` states v0.6.0 and marks the construction scenario done (43f3e29) and tail latency done in part (A6); `docs/AUDIT_2026-10_PLAN.md` reads executed; the family comparison and each engine's `COMPARISON.md` state the competitor pins frozen at 2026-10-09.* `PLAN.md:328` and `bridge/PLAN.md` §9 still call the book's bridge chapters follow-up work (Part VI landed in #68, 2026-10-08); `async/PLAN.md` §3 says v0.4.0 and §4 lists the construction scenario as open (done 2026-10-09); `docs/AUDIT_2026-10_PLAN.md` still says "execution in progress"; the comparison records' diff --git a/rational/docs/COMPARISON.md b/rational/docs/COMPARISON.md index 1a922a0..30b869a 100644 --- a/rational/docs/COMPARISON.md +++ b/rational/docs/COMPARISON.md @@ -416,6 +416,11 @@ per-frame cost drifts over the run by more than its construction, so ## Caveats, stated plainly +- **The competitors are frozen at their 2026-10-09 pins.** libsamplerate + 0.2.2, r8brain-free-src 7.6 and SpeexDSP 1.2.1 as `tools/compare/` pins + them; a newer release of any of them is not tracked. Moving a pin re-runs + `compare.yml` and the notebook and re-dates every table here + ([the family comparison](../../docs/COMPARISON.md#the-shared-tooling)). - **The matching rule is ours**, the same two numbers as the bridge comparison's (0.1 dB at the edge, stopband at least the tier's), applied across four ratios at once: a setting that passes three and fails one is