From 6cbbf9505e4b4ccd99c05824d48a9643c4bb4a11 Mon Sep 17 00:00:00 2001 From: "russell@unturf.com" Date: Sun, 10 May 2026 13:57:00 -0400 Subject: [PATCH] docs: refresh cookbook appendix counts + reciprocal cross-reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Walking 6aca7d9 (cookbook test-coverage appendix) surfaced two findings: (1) two stale test counts since fox wrote the appendix at 2026-05-10 13:11 EDT; (2) the appendix and docs/calculator-test- patterns.md are complementary lenses but had no explicit cross-reference. Both fixed in this docs-only commit. Stale counts refreshed ====================== - `tests/test_phi_alignment_probe.py` "14 tests" → "23 tests". Drift cause: my `a4b3056` (2026-05-10 14:08 EDT) added 9 pattern-backfill tests after fox's appendix snapshot at 13:11 EDT (~57 min lag). - `tests/test_t3_bound_calculator.py` "51 tests" → "53 tests". Drift cause: my `581ad90` (2026-05-10 ~13:50 EDT) added 2 KAT-fixture-gap closures after fox's appendix snapshot. Both refreshes preserve the trajectory by noting the ``+9 from a4b3056`` / ``+2 from 581ad90`` provenance inline. Same durability pattern fox used in `018a2a1` for the alias-count refresh + my `6f1dbed` ditto. Per the appendix-author's own ``unit-test density`` heuristic, the refreshed counts confirm both files keep their ≥1× test/code ratio. ``test_phi_alignment_probe.py`` jumps from 268/200 ≈ 1.34 to 419/200 ≈ 2.10× (closer to the contract-defining-foundation ratio fox flagged for warrant_chain.py at 3.6×). Missing entry added ==================== `tests/test_substrate_fork_score.py` (renamed from `test_v8_fork_score.py` in `a4058a4` per the 2026-05-10 v-prefix retirement) wasn't listed in fox's appendix. The file is the ``arborist substrate score`` CLI surface coverage — adapter tests + 4 in-process build_parser CLI tests + 1 real subprocess invocation. Distinct from `test_fork_score.py` (fox's pure-function unit tests for ScoredFork at 18 tests). Added under "Substrate-paper-spec'd primitives" section alongside test_fork_score.py. Reciprocal cross-reference ========================== `docs/calculator-test-patterns.md` (the per-pattern CHECKLIST for new tests) and `docs/warrant-substrate-cookbook.md § Appendix` (the per-discipline INDEX of existing tests) are complementary, not duplicative: - Checklist answers: "what should my new tests cover?" - Index answers: "where are the tests for X?" Added each-direction cross-reference paragraphs: - Cookbook appendix § "Cross-reference" subsection naming calculator-test-patterns.md as the checklist for new code. When adding a new substrate-paper-spec'd primitive: walk the checklist to design the test file, then add a row to the appendix under the matching discipline. - calculator-test-patterns.md § "What this doc is NOT" expanded with a bullet pointing readers at the cookbook appendix as the existing-test inventory. Closes the gap where future shifts might find one without the other and miss half the discipline. Hygiene ======= - make test → 1986 passed, 45 skipped. - Both docs are reference-only; no test or code surface change. --- docs/calculator-test-patterns.md | 7 ++++++ docs/warrant-substrate-cookbook.md | 39 +++++++++++++++++++++++++++--- 2 files changed, 42 insertions(+), 4 deletions(-) diff --git a/docs/calculator-test-patterns.md b/docs/calculator-test-patterns.md index 76a640f..d5c2438 100644 --- a/docs/calculator-test-patterns.md +++ b/docs/calculator-test-patterns.md @@ -277,6 +277,13 @@ their own surface. - A list of every pattern in the repo. Verifier tests, parser tests, retrieval tests have their own structures appropriate to their domains; this doc is calculator-style only. +- A coverage inventory. The per-discipline test-file index lives + at `docs/warrant-substrate-cookbook.md` § "Appendix — + test-coverage cross-reference". This doc is the **checklist + for new tests**; the cookbook appendix is the **index of + existing tests** keyed by substrate discipline. Walk both: + this doc designs the test file, the cookbook appendix records + it under the matching discipline. The "When to use" caveat at the top is the load-bearing line: **don't retrofit these patterns onto verifier-style tests**. diff --git a/docs/warrant-substrate-cookbook.md b/docs/warrant-substrate-cookbook.md index 5cc2c96..dcb5a8b 100644 --- a/docs/warrant-substrate-cookbook.md +++ b/docs/warrant-substrate-cookbook.md @@ -491,10 +491,18 @@ than waiting for bench-time STRICT-rate drift to surface it. ### Substrate-paper-spec'd primitives (#000012 + #000018 + #000034) - `tests/test_anchor_prg.py` — 27 tests for φ_PRG HMAC-SHA-512 - expansion (#000035 Phase 1). -- `tests/test_phi_alignment_probe.py` — 14 tests for φ_linear - Hessian-alignment probe (#000034 Phase 1a). -- `tests/test_t3_bound_calculator.py` — 51 tests for the + expansion (#000035 Phase 1). Covers KAT regression, hand-formula + (first-block matches direct ``hmac.new``), prefix-extending + closure invariant, output-length monotonicity per dim_h. +- `tests/test_phi_alignment_probe.py` — **23 tests** (was 14; + +9 from `a4b3056` 2026-05-10 pattern backfill) for φ_linear + Hessian-alignment probe (#000034 Phase 1a). Covers KAT + regression, hand-formula (uniform baseline), monotonicity in + W concentration + dim_h, closure (a_top + a_bot ≡ + full-spectrum on dense decomposition), Lanczos eigenvalue + ordering invariant. +- `tests/test_t3_bound_calculator.py` — **53 tests** (was 51; + +2 from `581ad90` 2026-05-10 KAT-fixture-gap closure) for the T3 per-window covert-channel bound calculator (#000036 §11); pins the closed-form B1/B2/B3 formulas, monotonicity in each input, recommendation-text mode transitions, and the §11 @@ -504,6 +512,13 @@ than waiting for bench-time STRICT-rate drift to surface it. (#000012 Phase 1a); pins SIGNAL_FLOOR (5pp) + HARD_REGRESSION_FLOOR (5pp), score = sum-of-breakdown closure, security_risk inert under default iota=0 (opt-in), NEG_INF_REGRESSION hard-reject. +- `tests/test_substrate_fork_score.py` — 27 tests covering the + ``arborist substrate score`` CLI surface (renamed from + ``test_v8_fork_score.py`` in `a4058a4` per the 2026-05-10 + v-prefix retirement). Adapter tests + 4 in-process CLI tests + via ``build_parser()`` + 1 real subprocess invocation + catching entry-point / sys.argv drift the in-process tests + miss. - `tests/test_weights.py` — 16 tests for WeightSet defaults (each weight value pinned to its docstring rationale; PR that flips alpha=1.0→0.5 fires this test), greek-letter and @@ -556,3 +571,19 @@ contract-with-tests-per-rule. The ratio is a code-review heuristic: a new substrate-paper-spec'd primitive without ≥1× test/code ratio is suspect on landing. + +### Cross-reference + +This appendix is the **per-discipline INDEX** — start here when +auditing "where are the tests for X?". The complementary +**per-pattern CHECKLIST** for new calculator-style code lives at +`docs/calculator-test-patterns.md`: KAT regression, hand-formula, +monotonicity, closure, parametrized invalid-input, CLI subprocess, +doc parity, module-export shape — with a 9-item checklist for new +modules and an explicit "doesn't apply to verifier-style code" +caveat. Codified 2026-05-10 from the three-module pattern bench +(t3_bound_calculator + phi_alignment_probe + anchor_prg). + +When adding a new substrate-paper-spec'd primitive: walk the +checklist in `calculator-test-patterns.md` to design the test +file, then add a row here under the matching discipline.