rational: Q15 and Q31 in the C ABI

[tap]

What this changes

• New format constants: TAP_SR_RATIONAL_FORMAT_FLOAT / _Q15 / _Q31, stable values 0 / 1 / 2.
• New entry points:
  • tap_sr_rational_create_format(chain, profile, format, channels)
  • tap_sr_rational_create_stage_format(L, M, profile, divisor_num, divisor_den, format, channels)
  • tap_sr_rational_format(c)
  • tap_sr_rational_process_q15 / _q31, taking interleaved int16_t (Q0.15) and int32_t (Q0.31)
  • tap_sr_rational_flush_q15 / _q31
• Existing float functions: unchanged. create and create_stage are the float case.
• Wrong-format calls return 0 and consume and write nothing. An unknown format returns NULL.
• Implementation: the engine behind the ABI is templated on the sample type, so each format runs the same basic_chain / basic_stage C++. The library exports exactly 23 symbols (16 before), still with hidden visibility.
• ctypes binding: Chain(name, fmt="q15") and Stage(..., fmt="q31") take int16 and int32 numpy arrays.
• Docs: README C ABI section, CLAUDE.md, plan v0.12, and the header preamble.

Why

You picked this from the post-M6 list. The fixed-point profiles exist for M33 / M55-class deployments, and an FFI consumer there needs them without wrapping the C++ itself.

Verification

• Tests: test_capi.cpp now checks every one of the 28 chain constants against its named basic_chain, bit for bit, in float, Q15 and Q31. It compares outputs, flush, accounting, latency and MACs.
  • The stage constructor is checked in Q15 and Q31 too.
  • The format is reported correctly, a wrong-format call is refused without changing state, and unknown formats return NULL.
• Builds: 286/286 tests pass with clang 18 -Werror and the C ABI on. gcc -Werror passes the rational label (113/113). clang-tidy and clang-format are clean.
• Exports: nm -D lists exactly the 23 tap_sr_rational_* functions.
• Binding: a smoke run shows Q15 down_2 within 1.5e-5 of the float converter on the same tone, and Q31 3/4 reporting its exact ratio and MACs.
• Unaffected: the notebooks measure float and don't change. The ratchet doesn't exercise the C ABI.

Notes for the reviewer

• This departs from the family convention. bridge's and async's C ABIs are float-only: the notebooks measure the golden model, and the C++ tests pin fixed point. This one carries the fixed-point profiles too, and its header says so. If you'd rather keep the family uniform, the alternative is a separate fixed-point ABI per engine; I didn't build that.

🤖 Generated with Claude Code

https://claude.ai/code/session_015VR1VC4SDGxHZQQsQvPBaA

---

Generated by Claude Code