rational M4: the chains and the coverage matrix, measured

[tap]

What this changes

Milestone M4 of rational/PLAN.md: chain.h (basic_chain<S, R...> over DspTap's chain<>, the 20 named multi-stage chains), the committed coverage-matrix generator tools/coverage/matrix.py re-run on the pinned lengths, design.h's relaxation tables (profile::relaxed), and tests/test_matrix.cpp pinning and measuring all 182 rows of section 3. The plan goes to v0.7 with section 3 regenerated from measured counts. The DspTap pin moves to tap/DspTap#52 (chain<>::flush).

Why

A chain of stages has one profile, the chain's: f_pass = p · r_min at its lowest rate, so each stage is designed at p over its design divisor, its lower rate over r_min (the plan's 3.1: stages further up a chain are shorter). basic_chain computes that divisor per stage at compile time (the largest 2^a 3^b at or below the quotient, exact within a family; the quotient itself below 1, which is the one stage at bridge's rate under a 48-family r_min, 147/160) and constructs each stage at the profile relaxed by it, with pinned lengths per divisor so construction never searches. The generator costs every stage the same way and as stage.h trims its rows, so the matrix's MACs per output and latency are the shipping chains' numbers, exact.

Re-running the plan's selection rules on the pinned lengths changed 35 of the 182 rows against the harris-estimate tables (risk S1's ledger, in the plan's section 8): a relaxed half-band saturates at m = 7 (N = 27) while a relaxed third-band stage is m = 5 (N = 29) and serves three times the rate, so third-band, 4th-band and mixed stages win where the transition is wide (8/1 is ↑2 · 4/3 · ↑3, 1/8 is ↓3 · 3/4 · ↓2, 12/1 is ↑2 · ↑6, the ↑8 / ↓8 stage moves to the middle of the long chains). The rules were not changed; the plan notes that a tie-break toward integer-factor chains at a few per cent would be one edit to best_chain plus a regeneration, if the maintainer prefers it. The named-chain count for the C ABI is 28 (the union of the two tables' chain columns), where v0.2 counted 34 before taking the union.

Nothing is skipped: bridge's rate scale (2.2) had landed, so the twelve k > 0 rows are measured like the rest. The named ratios move from the umbrella to ratio.h because chain.h needs them; the public header count is 6.

Verification

• Host, clang 18 and GCC with -Werror (the three TAP_SR_*_WERROR options on): the whole family battery passes (rational 99 ctest entries; GCC's run of the rational binary 93/93); scripts/tidy.sh clean on the new and changed TUs; clang-format clean.
• test_matrix.cpp (host suites): every row's MACs per output and latency equal the generated table as exact rationals at all four profiles; every within-family row's compile-time divisors are the table's and its basic_chain reports the same numbers; the tone battery per profile (about 1700 tones over the 182 rows: seven passband tones and up to five stopband tones per row at exact bins of an analysis window that makes every rate of the chain a bin, so the rectangular-window DFT measures each image and alias candidate leakage-free): every candidate at or below f_pass is at or below −A — worst −71.34 dB at economy, −71.84 at super_economy, −71.52 at balanced, −121.63 at transparent — and the passband within the stages' summed ripple candidates (worst 0.0087 dB at a 70 dB tier, 0.00002 dB at transparent); accounting from three positions, the impulse within half a frame of the latency and flush on every row. About 24 s for the four batteries on a host.
• test_chain.cpp: the named chains' divisors as static_asserts; a chain equals its stages run in sequence bit for bit in float, double, Q15 and Q31; seven chains against sequenced-upfirdn vectors (tools/reference/make_reference_vectors.py regenerated; the single-stage vectors are byte-identical) within the single stages' tolerances; accounting exact from every position of a superblock of all 20 named chains; chunking, reset, flush as zero padding, latency by impulse, MACs, DC, two channels.
• test_design.cpp: every entry of the four relaxation tables is what search_nyquist_m finds on the design grid with the margin (the M2 criterion).
• Cortex-M33 QEMU leg, run locally: the rational one-shot passes in 158 s with the matrix suite and the relaxation-table searches excluded by bare_metal_main.cpp (a first run with the 70 dB search included hit the 1800 s ctest timeout under soft double; the second commit excludes it and trims the chain accounting sweep to one superblock). Hexagon's row excludes the tone batteries and the transparent search by name. Not run here: M55 and Hexagon, which CI covers.
• tools/coverage/matrix.py md|pins|rows|diff|rule are deterministic; diff against the v0.6 tables lists the 35 changed rows, rule the 24 rows where the fewest-stages rule bit.

Notes for the reviewer

• Submodule pin moved. submodules/dsptap points at chain: flush, the stream drained stage by stage DspTap#52's branch commit (d4a61a9, chain<>::flush, CI green there); once Align the icount marker's format string and re-record the Hexagon baselines #52 merges by rebase I will repoint at the identical tree on DspTap main and amend this branch.
• Contract change, this engine only. profile gains relaxations (a span of the pinned rows) and relaxed(divisor); the named ratios (up_2 … ratio_3_8) are declared in ratio.h now (the umbrella still exports them). No consumer other than this tree's tests exists yet.
• The matrix's chain shapes are the plan's rules applied to measured numbers; the ledger in the plan (S1) lists every flip and its cause. If you would rather keep integer-factor chains where a mixed stage saves only a few per cent, say so and I regenerate with that tie-break.
• tests/coverage/matrix_rows.h and tests/reference/reference_vectors.h are generated; the generators' modes are documented in their docstrings.

🤖 Generated with Claude Code

https://claude.ai/code/session_015VR1VC4SDGxHZQQsQvPBaA

---

Generated by Claude Code