rational: Q15 mixed ratios going down at a power-of-two row gain

[tap]

What this changes

• Scaled rows. In Q15, the rows of the mixed ratios going down (2/3, 3/4, 3/8) now sum to G × unity instead of unity.
  • G is the largest power of two with G·L/M < 2: 2 for 2/3 and 3/4, 4 for 3/8. That keeps every tap inside Q1.14.
  • finalize_divided shifts G back out exactly in the single rounding. basic_stage::k_table_gain and finalize_output() carry it, the same mechanism as the Q15 decimators.
• Snapping. The scaled rows are snapped to 2^-34 (2^-20 of a Q1.14 LSB) before quantizing; see the notes for why.
• Tests. Twelve Q15 table pins are re-pinned (hash, MACs, stopband, RMS), and the unity-sum checks now account for the gain.
• DspTap pin. It moves to DspTap main, which carries decimate: Q15 stores M·h, the M divided out in finalize_divided DspTap#55: decimate.h's Q15 tables at M·h. This engine's tests use decimate.h only in float.
• Docs: plan v0.11, the section 6 table and limit, the stage.h contract, README and CLAUDE.md.

Why

You asked me to model the Q15 mixed-down limit and build it only if it reached the 70 dB tier. Rows normalized to unity put the centre tap near L/M (0.67 for 2/3, 0.38 for 3/8). That leaves part of the Q1.14 range unused: the same shrinkage as the decimators', at a smaller factor.

Attained Q15 stopband, measured by the test on the 16,384-point grid:

Stage	super_economy	economy	balanced	transparent
2/3	−69.1 → −71.1	−69.7 → −70.5	−71.1 → −72.1	−73.9 → −78.2
3/4	−70.7 → −71.6	−72.8 → −70.0	−68.2 → −72.4	−75.8 → −78.3
3/8	−69.2 → −71.5	−71.2 → −71.8	−69.4 → −71.7	−69.6 → −83.1

• Every Q15 stage now reaches the 70 dB tier at every 70 dB profile.
• One cell moves the wrong way: 3/4 at economy goes from −72.8 to −70.02 dB. It stays in the tier, but with no margin.
• Q15 RMS error against double is 4–10 dB lower.
• Q31, float and double are unchanged.

Verification

• Host: 286/286 tests pass with clang 18 -Werror. gcc -Werror passes the rational label (113/113). clang-tidy and clang-format are clean.
• Embedded: the rational battery passes 7/7 on M33 and on M55 under QEMU, with the tables matching the host bit for bit.
• Ratchet: every engine's counts stay within ±3 % on M33, M55 and Hexagon, so no baselines move. ratio23_q15_eco changes by +0.01 % on M33, +1.9 % on M55 and 0.00 % on Hexagon.

Notes for the reviewer

• Why the snap is needed. Without it, the M33 and M55 legs pinned a different 2/3 super_economy table than the host.
  • The cause: quantize_row_preserving_sum gives each leftover LSB to the tap with the largest remainder. A symmetric design has pairs of exactly equal remainders, and the design's last bits differ between glibc and newlib, so the tie broke differently.
  • Snapping makes those ties exact everywhere, and they break by index. Two host pins moved because of it: 2/3 transparent and 3/4 economy.
  • The same fragility exists for any table whose residual lands on a near-tie. Today's other tables happen to agree across targets. The general fix would be a deterministic near-tie rule in DspTap's quantize.h, which would move pins family-wide, so I've left it as a finding for you to decide.
• What comes next: the Q15/Q31 C ABI is ready, and I'll open it as the next PR once this one merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_015VR1VC4SDGxHZQQsQvPBaA

---

Generated by Claude Code