rational M6: C ABI, matrix notebook, icount ratchet; family 0.5.0

[tap]

What this changes

This is M6 of rational/PLAN.md, the last milestone in the plan.

• C ABI. New in rational/capi/, built as libtap_sr_rational_capi with -DTAP_SR_BUILD_CAPI=ON or standalone.
  • tap_sr_rational_create(chain, profile, channels) takes one of the 28 named within-family chains as a stable TAP_SR_RATIONAL_* constant. It never takes a rate (D12).
  • tap_sr_rational_create_stage(L, M, profile, divisor_num, divisor_den, channels) builds one stage of the vocabulary at a stated design divisor. That is the piece a caller uses to compose a chain through bridge (R16).
  • It reports exact accounting, latency and MACs per output as rationals, the design length of each stage, and the bit-packed version.
  • The library is built with hidden visibility, so nm -D lists exactly the sixteen tap_sr_rational_* functions.
• C ABI tests. rational/tests/test_capi.cpp:
  • Every chain constant matches its named basic_chain bit for bit, with the same latency, MACs, accounting, flush and reset.
  • The profiles select their designs.
  • create_stage equals the stage built at the same divisor.
  • Invalid arguments return NULL.
  • CApi.VersionIsBitPacked returns 0x000500.
• Binding and notebook. rational/notebooks/tap_sr_rational_py.py is the ctypes binding. matrix.ipynb is committed executed and goes through the C ABIs, using bridge's C ABI for the cross rows.
• Instruction-count ratchet. rational/bench/icount/ adds twelve workloads with the guest marker RATIONAL_ICOUNT_DONE. Baselines are recorded in rational/bench/baselines.json for M33, M55 and Hexagon.
  • scripts/icount.py and scripts/update_icount_docs.py accept --engine rational.
  • CI adds a "Ratchet rational" step and puts rational in the icount-docs matrix.
  • The README table is generated by the script.
• Family version 0.5.0 (R11, D13): all three umbrella headers, the root project(), version_macros.cpp, each engine's version tests, the book's C ABI page, the READMEs and CLAUDE.md.
• Docs. rational/PLAN.md goes to v0.9 with the M6 row marked done, the measured icount table and one finding. The family PLAN.md "Next — rational" entry, both CLAUDE.md files and the READMEs are updated to match.

Why

M6's acceptance criteria are: the notebook measures the shipping C++ and reproduces the pinned matrix numbers, the ratchet is green on three targets, the nm -D symbol set is recorded, and the family is at 0.5.0.

Verification

• Notebook:
  • All 728 (row, profile) pairs reproduce both the MACs-per-output pin and the latency pin exactly, through the C ABIs.
  • The tone battery passes 182/182 rows at economy (worst stopband −71.34 dB, ripple 0.0081 dB) and 182/182 at transparent (−121.57 dB, 0.00002 dB).
• Ratchet: baselines recorded on all three targets and re-run with --exact; every count matched. Running this environment against bridge's committed baselines reproduces them to the instruction, so it matches CI.
• Host builds:
  • clang-18 with -Werror for all three engines and the C ABI ON: 285/285 tests pass.
  • gcc with -Werror: the rational label passes 112/112. On the first run after reconfiguring, ChartersFailToCompileWithTheMessage failed once. It passed on its own and then again in a full parallel run.
• Style: clang-tidy is clean on every touched or new C++ source, and clang-format is clean.
• Embedded: the M33 and M55 QEMU legs build as CI configures them and the rational battery passes 7/7 on each.

Notes for the reviewer

• The chain selectors are #define constants, not an enum. The house .clang-tidy requires lower-case enum constants, and a C ABI wants upper-case prefixed names. Bridge's and async's C headers have no enum to follow.
• Finding, recorded in plan section 6: on the M55, Q15 is not yet faster than float. ↓2 is 25.07 M instructions against 24.58 M, and ↑2 is 47.49 M against 43.44 M. On M33 and Hexagon, Q15 runs 4–15× fewer instructions. An MVE Q15 kernel is listed with the other codegen levers deferred until a consumer asks for them.
• After merge I'll ask before pushing a v0.5.0 tag.

🤖 Generated with Claude Code

https://claude.ai/code/session_015VR1VC4SDGxHZQQsQvPBaA

---

Generated by Claude Code