Harden the ratchet, tests and CI ahead of the monorepo migration (step P)

[tap]

What this changes

This PR is SampleRateTap's half of step P, the pre-work for the monorepo migration. The plan is docs/MONOREPO_PLAN.md on claude/sample-rate-expansion-strategies-ezqzu6, and the companion PR is tap/RatioTap#18. The PR repairs breakage that nothing was catching. It also makes the ratchet, the tests, CI and the notebooks produce the evidence the migration's gates will compare.

P.1: repairs (98cbe9b)

• Pico 2 examples build again. Both examples were ported to the current snake_case API and given the dsptap include path. Both firmwares build against Pico SDK 2.1.1.
• The book's trace tool builds again. scripts/book_figures_trace.cpp compiles against both the current tree and the pre-fix commit 045de5d. book_figures.py passes the dsptap include path.
• .git-blame-ignore-revs is fixed. Its only entry named a commit that exists in no history. It now lists b84020e and e2f5a48.
• Cross-validation figures updated. README and book now quote RatioTap's current floors (−98/−90 dB).

P.2: harness and CI (865e32d, 64509e1)

• scripts/icount.py:
  • --exact requires identical counts.
  • --json-out and --compare-json support same-job A/B runs.
  • A recorded workload with no binary is now a failure.
  • A missing baselines file is now fatal.
  • Each workload's checksum is printed and recorded.
  • Hexagon workloads run from a fixed path, with a fixed argv[0] and an empty environment. qemu-hexagon copies these onto the guest stack, and static musl's startup walks them, so the old counts included them.
  • The Hexagon baselines are re-recorded (64509e1). The first isolated run measured every scenario 3,656–3,724 instructions lower (−0.0008% to −0.0020%). There is a ledger entry in docs/PERFORMANCE.md, and the README table was regenerated.
• Test names and labels. Tests carry an async. ctest prefix and an async label, including the bare-metal entry.
• New OutputHash suite. It prints FNV-1a hashes of the datapath output. They are compared within one job, never pinned.
• CI:
  • Push runs only on main; branches run through pull_request and dispatch. This removes the double runs on PR branches.
  • Cancellation spares main and the migration PR, but still applies to other PRs, including this one.
  • permissions: contents: read.
  • The QEMU and ratchet jobs are pinned to ubuntu-24.04, with the image OS added to the plugin-qemu cache key and image and toolchain versions logged.
  • --no-tests=error on every ctest call.
  • The QEMU jobs upload their full test logs.
• New Pico 2 build job.
• ci-arm64: the TSan ring stress filtered on SpscRing, which matched nothing, and now filters on spsc_ring.

P.3: notebooks (3e39365)

• requirements.in / requirements.lock. The notebook environment is pinned with hashes, and the same file is in RatioTap. The README points to it.
• The ctypes bridges now rebuild the C ABI library every run. The rebuild is incremental and quiet. Before, a stale library could be loaded without anyone noticing.
• notebooks/figure_digest.py prints a data digest for each figure. A changed curve then shows up as changed text. The rbj notebook's wall-clock timing cell is tagged nondeterministic.
• All four notebooks re-executed.
  • The comparison and rbj numbers reproduce exactly.
  • Two notebooks' committed outputs were stale. They predate the compensated prototype design (2026-07-04). The demo SNR is now 125.9 dB (it read 126.4). The block-size study's wideband floors are now 61.5 / 58.1 / 54.0 dB (they read 60.9 / 58.2 / 53.1). The prose quoting these numbers is updated: README, book, COMPARISON.md and the notebook summaries.

Why

The migration gates key tests by unique names and compare exact icount, output hashes, full on-target logs and notebook outputs. All of that has to exist before the snapshot. Several checks were also passing while testing nothing: the arm64 TSan filter, the Pico builds, the trace tool and the blame-ignore file. The snapshot must not record those as green.

Verification

• Host builds:
  • GCC with -Werror: 77/77 tests pass, all named async.* and labelled async.
  • Clang with -Werror: clean.
  • clang-tidy-18: clean on the new test.
• Hashes are stable across runs and identical between GCC and Clang. On M33 under QEMU the suite takes about 60 s. The Q15/Q31 hashes match x86-64 exactly; the float hashes differ, as expected. The M33 timeout goes from 30 to 40 minutes.
• icount.py on M33 under real QEMU with the plugin:
  • All 7 workloads match exactly.
  • The A/B mode passes.
  • A missing workload fails, and so does a missing baselines file.
• CI on the current head (3e39365): every job is green (17/17).
  • M33 correctness took 28 min, within the new 40-min timeout.
  • Hexagon correctness took 26 min.
  • The ratchet passes on all three targets against the re-recorded baselines.
• Notebooks were executed with pip install --require-hashes -r requirements.lock on Python 3.11.15. The digest lines are identical across two re-executions.
• Not verified: ci-arm64, because it is dispatch- and schedule-only.

Notes for the reviewer

• Contract change (test naming only): ctest names gain an async. prefix. -R and -E substring filters are unaffected.
• Notebooks re-executed. They are committed executed, and the changed numbers are listed above.
• The concurrency expression names the migration branch explicitly, so the migration PR never cancels an in-flight run.

🤖 Generated with Claude Code

https://claude.ai/code/session_015VR1VC4SDGxHZQQsQvPBaA