Stage 4 onto main: the compliance proof notebook (corrective for #11)

CMakeLists.txt

@@ -58,3 +58,10 @@ option(MUTAP_BUILD_CAPI "Build the C ABI shared library" OFF)
 if(MUTAP_BUILD_CAPI)
     add_subdirectory(tools/capi)
 endif()
+
+# Measurement dump for the ITU compliance proof notebook
+# (tools/notebook/build_itu_compliance.py -> notebooks/itu_compliance.ipynb).
+option(MUTAP_BUILD_ITU_DUMP "Build the ITU compliance measurement dump" OFF)
+if(MUTAP_BUILD_ITU_DUMP)
+    add_subdirectory(tools/notebook)
+endif()

HANDOFF.md

@@ -348,11 +348,33 @@ margins.*
 -> `notebooks/itu_compliance.ipynb`: one section per requirement group,
 requirement/measured/margin table per section, convergence curves vs the
 specs' time masks, double-talk timelines vs the P.340 windows.
+*DONE — the notebook's first cell compiles `tools/notebook/itu_dump.cpp`
+(option `MUTAP_BUILD_ITU_DUMP`) and re-measures the whole battery live
+(~6 min): the dump includes the test suite's own itu_chain.h machinery,
+so every notebook number is the number the assertions gate. Nine
+sections: steady state, Tier A convergence vs masks, G.168 Figures
+9/11 + the re-convergence deviation (honest figure), double talk vs
+P.340, comfort noise/pumping, path dynamics, stability/delay, G.167
+run-and-reported. CSS generation (NOTE 2 resampler from 44.1 kHz
+native) dominates the dump's runtime — memoized in the dump only,
+byte-identical output verified; the signal layer is untouched.*
 
 **Stage 5 — Externals + docs.** Post-filter attribute on `mutap.aec~`,
 C ABI extension for the notebook, maxref/help updates, book-chapter
 section, README compliance claims with margins. (Submodule dance,
 working note 6, as always.)
+*MAX HALF DONE — `mutap.aec~ @postfilter` engages the certified chain
+(raw Kalman + suppressor + comfort noise + receive guard) with the
+compliance preset's time-constant rescaling replicated for arbitrary
+(block, sample rate); maxref/help/README updated. CORE FOLLOW-UP FILED:
+the pinned compliance preset (tests/support/itu_chain.h chain_config)
+belongs in the library proper — e.g. a `mutap::aec_chain_preset(block,
+fs)` factory — so the Max external and any future consumer stop
+duplicating the scaling rule; the external's copy (mutap.aec_tilde.cpp
+make_chain_config) must be kept in lockstep until then. Note: Stage 4's
+notebook ended up NOT needing the C ABI (its dump harness includes the
+test machinery directly), so the "C ABI extension" item is now about
+FFI consumers generally — scope it when the MuTap half lands.*
 
 ---
 

README.md

@@ -230,6 +230,16 @@ algorithmically complete. What exists today:
   figures as an informative row. One documented deviation: deep
   re-convergence after *abrupt* path changes (the Kalman
   uncertainty-re-inflation follow-up in HANDOFF).
+- **The compliance proof notebook** (Stage 4) —
+  [`notebooks/itu_compliance.ipynb`](notebooks/itu_compliance.ipynb):
+  requirement/measured/margin tables for every row above, convergence
+  trajectories drawn against the recommendations' time masks, the
+  double-talk timelines against the P.340 windows, and an honest figure
+  of the re-convergence deviation. Nothing in it is pasted in: the first
+  cell compiles [`tools/notebook/itu_dump.cpp`](tools/notebook/itu_dump.cpp)
+  (`-DMUTAP_BUILD_ITU_DUMP=ON`) — a C++ battery reusing the test suite's
+  own scenario machinery and meters — and re-measures everything live
+  (~6 minutes, deterministic seeds).
 
 Next up (see [HANDOFF.md](HANDOFF.md) "What's next"): in-Max listening in
 a real room and the default-engine decision, then the M55 performance
@@ -272,7 +282,10 @@ material, IPC, burst survival — see
 [notebooks/afc_demo.ipynb](notebooks/afc_demo.ipynb), which drives the
 library through its C ABI (`-DMUTAP_BUILD_CAPI=ON`, `tools/capi/`) via
 ctypes (Python needs `numpy` and `matplotlib`; the first cell builds the
-shared library if needed).
+shared library if needed). The echo-canceller counterpart is
+[notebooks/itu_compliance.ipynb](notebooks/itu_compliance.ipynb) — the
+ITU compliance proof, every number re-measured live by a compiled C++
+battery.
 
 ## Layout
 
@@ -281,7 +294,8 @@ include/mutap/       the library (header-only; umbrella header mutap.h)
 third_party/ooura/   vendored Ooura FFT (see THIRD_PARTY_NOTICES.md)
 tests/               GoogleTest suite (fetched at configure time)
 tools/capi/          C ABI shared library for FFI consumers (notebooks)
-notebooks/           demo notebook (ctypes over the C ABI)
+tools/notebook/      notebook builders + the ITU measurement dump (C++)
+notebooks/           demo + compliance-proof notebooks (build products)
 book/                "Quieting the Loop" (mdBook) — the user-facing field guide
 platform/            Cortex-M55 bare-metal board support (startup, linker)
 cmake/               cross toolchain files (Cortex-M55 MPS3, Hexagon musl)

docs/itu-compliance.md

@@ -538,4 +538,31 @@ comfort-noise step tracking against G.168's +-2 requirement, -1.72
 after; the Tier A ComfortNoiseLevel row moves from -2.91 (target miss)
 to -2.15 (target met) at 16 kHz.
 
-Remaining: Stage 4 (proof notebook) and Stage 5 (externals/docs).
+## Stage 4 delivered: the compliance proof notebook
+
+`tools/notebook/build_itu_compliance.py` assembles and executes
+`notebooks/itu_compliance.ipynb`: one section per requirement group,
+a requirement/measured/margin table per section, the convergence
+trajectories drawn against the recommendations' time masks (quiet,
+in-noise, G.168 Figures 9/11), the double-talk rows against the P.340
+windows (per-band send attenuation and echo loss, transfer constancy,
+hangover, build-up), comfort noise/pumping, path dynamics with an
+honest figure of the re-convergence deviation, the Annex E sweep, and
+the G.167 run-and-reported row with the TCLwdt finding.
+
+Nothing in the notebook is transcribed by hand except the
+recommendations' requirement values: its first cell compiles
+`tools/notebook/itu_dump.cpp` (CMake option `MUTAP_BUILD_ITU_DUMP`,
+built in a dedicated `build-itu/` tree) and re-runs the full battery
+live (~6 minutes, deterministic seeds). The dump program includes the
+SAME `tests/support/itu_chain.h` machinery the test suite gates with —
+same pinned chain, same signals, same meters — and its scenario
+recipes mirror the gtest rows line for line, so a number in the
+notebook is the number the suite asserts. The gtest files remain the
+assertion authority; the notebook exists so a human can see the
+trajectories the assertions compress into pass/fail. (Measurement
+note: CSS generation through the NOTE 2 resampler dominates the dump's
+runtime, so it memoizes `make_css_at` — verified byte-identical output
+against the uncached run.)
+
+Remaining: Stage 5 (externals/docs).

tools/notebook/CMakeLists.txt

@@ -0,0 +1,9 @@
+# The Stage 4 measurement dump for the ITU compliance proof notebook.
+# Host-side, double precision only — never part of the emulated-target
+# builds (the option defaults OFF and the notebook builder switches it on).
+add_executable(itu_dump itu_dump.cpp)
+target_link_libraries(itu_dump PRIVATE MuTap::MuTap mutap_warnings)
+# The dump reuses the test suite's scenario machinery verbatim
+# (tests/support/itu_chain.h et al.) so the notebook's numbers come from
+# the same meters the assertions gate.
+target_include_directories(itu_dump PRIVATE ${CMAKE_SOURCE_DIR}/tests)