phase3: cJSON cross-language win verified + audited; robustness fix; case studies

phase3-cjson-002 (class 5+3): stack-buffer number parsing + strtod
round-trip replacing sscanf. +8.85% median, 95% CI [+7.5%, +10.0%] on
the C target, banked. 100% audit: byte-identical golden replay,
independent ASan+UBSan clean, 10k-input differential fuzz 0 divergences,
patch bounds/free-gating verified by eye.

- verdict: an infrastructure sanitizer-BUILD failure (missing runtime,
  broken toolchain) now caps the accept at needs-human-review and logs
  it, instead of crashing the verdict and losing a measured bench.
- results/phase3/: four public case studies (tokei class-5 wins; build
  flags + allocators; the comrak caught false-accept; the cJSON
  cross-language proof) + README. Compound-speedup claim stated as an
  approximation, not a measured figure (CIs don't multiply).
- .gitignore: cjson build-artifact dirs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2

results/phase3/01-tokei-algorithmic-rust.md

@@ -0,0 +1,64 @@
+# Case study 1 — tokei: compounding algorithmic wins (Rust, class 5)
+
+**Target:** [tokei](https://github.com/XAMPPRocky/tokei) v14.0.0 — a
+source-code line counter. **Workload:** 221 MB / 4360 files (8 replicas
+of the Pro Git book + comrak's own tree), single rayon thread, CPU
+pinned. **Result:** three independent, CI-verified class-5 wins on the
+same hot function — each proposed *by the unattended agent* and
+100%-audited. Multiplied together they are **~1.26× over the Phase-0
+baseline** (1.107 × 1.037 × 1.099), but that product is an
+approximation, not a measured figure: each speedup carries its own
+bootstrap CI against its own baseline, and confidence intervals do not
+compose through multiplication. The trustworthy claims are the three
+individual increments below.
+
+## The hot path
+
+tokei spends the overwhelming majority of its instructions in one
+function — `LanguageType::parse_lines` and the per-byte loop inside
+`SyntaxCounter::perform_multi_line_analysis`. The cache-sim profile put
+it at **55.9% of instructions, 62% of all branches, 44% of branch
+mispredicts** on the pinned corpus: for every byte of every line, the
+counter tested a stack of quote/comment token matchers.
+
+## The three wins
+
+| run | mechanism | speedup (median) | 95% CI |
+|---|---|---|---|
+| `phase0-tokei-002` (class 3) | read path: `fs::read` pre-sized, BOM-only decode | 1.099 | [1.080, 1.127] |
+| `phase2-tokei-001` (class 5) | 256-entry first-byte gate table for the token matchers | 1.107 | [1.084, 1.131] |
+| `phase2-tokei-003` (class 5) | forward-only whitespace break (drop the `rposition` rescan) | 1.037 | [1.027, 1.052] |
+| `phase2-tokei-008` (class 5) | streaming leftmost `important_syntax` scan (one vectorized pass, not per-line restart) | 1.099 | [1.073, 1.112] |
+
+Each is a **redundant-work elimination**: the first-byte gate replaces
+five per-byte matcher loops with one table load; the whitespace-break
+change drops a full backward scan of the file tail per byte; the
+streaming scan replaces a per-line aho-corasick restart (which kept
+memmem's SIMD prefilter in its short-haystack slow path) with a single
+leftmost search advanced by integer comparisons.
+
+## Why the numbers are trustworthy
+
+- **Byte-identical golden replay** on the pinned corpus for every win —
+  a code counter that miscounts one line fails the gate.
+- **10,000-input differential fuzz** (`scripts/diff-fuzz-tokei.py`),
+  pristine vs candidate, **0 divergences** — after canonicalizing
+  tokei's benign parallel-walker output ordering (a real finding:
+  raw-byte differential comparison over-counts when the target is
+  legitimately nondeterministic in presentation).
+- **ASan/LSan clean** on the patched tree over the full corpus.
+- **Interleaved A/B** vs a pristine-rebuilt baseline, bootstrap 95% CI
+  lower bound ≥ the 2% bar. `phase2-tokei-008` was the first accept
+  through the *machine-enforced* sanitizer gate (see case study 3).
+
+## What it demonstrates
+
+The richest wins on a mature Rust binary were not exotic — they were
+"this loop does work it doesn't need to, on every byte." The agent found
+each by reading the cache-sim profile, checking the ledger to avoid
+re-attempting a class on the same hotspot, and proposing the cheapest
+untried mechanism. Three separate hypotheses, three separate verified
+increments, all on the same 40%-of-runtime function — and one honest
+rejection in between (`phase2-tokei-009`, a real +5.7% median whose
+noisy CI lower bound of +0.2% could not clear the bar, so it does not
+count).

results/phase3/02-build-flags-and-allocators.md

@@ -0,0 +1,50 @@
+# Case study 2 — cheap wins first: build flags and allocators
+
+**The playbook's ordering principle (SPEC §3.3, CLAUDE.md
+non-negotiable #3): build flags → LTO → PGO → allocator swap → *then*
+code changes.** The cheapest classes are tried first because they carry
+the lowest cost-per-attempt and the lowest risk. Two of them produced
+Phase-0 results that frame the whole project's discipline.
+
+## Class 1 — link-time optimization (tokei) — ACCEPTED
+
+`phase0-tokei-003`: set `lto = true` (fat LTO, up from `thin`) and
+`codegen-units = 1` in tokei's release profile.
+
+- **Speedup: 1.104 median, 95% CI [1.085, 1.120]** vs the pristine
+  `thin`-LTO baseline.
+- Byte-identical golden replay; no source change, so equivalence is by
+  construction (same code, different codegen). Auto-accept tier.
+- A pure build-config win worth **+10%** — the cheapest possible class,
+  and on this target the single largest individual increment.
+
+The lesson the ledger enforces: you do not go hand-optimize a hot loop
+before you have tried turning on the optimizer's own switches.
+
+## Class 2 — allocator swap (comrak) — NEEDS-HUMAN-REVIEW
+
+`phase0-comrak-002`: swap the global allocator to
+[mimalloc](https://github.com/microsoft/mimalloc).
+
+- **Speedup: 1.046 median, 95% CI [1.033, 1.058]** — a real, CI-clean
+  +4.6% on comrak's Pro Git render.
+- Byte-identical golden replay. And yet the verdict is **not
+  `accepted`** — it is **`needs-human-review`**.
+
+Why: an allocator swap changes the process's memory behavior globally.
+It is exactly the class of change SPEC §8 routes to a human — not
+because this instance is wrong, but because "the benchmark got faster"
+is not sufficient evidence that a global allocator change is safe under
+every workload, fragmentation pattern, and concurrency scenario the
+target will meet in production. The pipeline measured a real win and
+then **refused to auto-ship it**, tagging it for a human ruling instead.
+
+## What the pair demonstrates
+
+The cheap classes are not lesser — class 1 produced this project's
+biggest single win. But "cheap to try" is not "safe to auto-accept."
+LTO is deterministic codegen: accept it. An allocator swap is a global
+behavioral change: measure it, prove the speedup, and *still* hand it to
+a human. The tier is decided by the *nature* of the change, never by the
+size of the number — the same rule that later caught a leaking teardown
+patch the bench loved (case study 3).

results/phase3/03-comrak-caught-false-accept.md

@@ -0,0 +1,68 @@
+# Case study 3 — the caught false-accept (comrak, class 3)
+
+**This is the most important case study in the project, because it is
+the one where the machine got it wrong and the process caught it.**
+
+## What happened
+
+`phase2-comrak-010`: the unattended agent, reading comrak's cache-sim
+profile, saw that AST-arena teardown at process exit —
+`drop_in_place::<Vec<Node<RefCell<Ast>>>>` plus its share of the glibc
+free path — cost real instructions and cache misses in a
+run-to-completion CLI. Its hypothesis: comrak already ends in
+`process::exit`, so the OS reclaims memory in bulk anyway; wrap the arena
+in `std::mem::ManuallyDrop` to skip the per-node drop walk, and add a
+`std::hint::black_box(&arena)` before the scope closes so the leak stays
+reachable and a leak checker won't flag it.
+
+The pipeline ran it:
+
+- Upstream tests: **PASS**
+- Golden replay: **byte-identical**
+- Interleaved A/B: **+10.7% median, 95% CI [+7.9%, +12.1%]**
+- Verdict: **`accepted`**
+
+A clean, large, CI-significant win. And it was **wrong**.
+
+## The audit overturned it
+
+Phase 2 runs a **100% human audit** of every accepted win (SPEC §10).
+The audit ran the sanitizers the pipeline had not: LeakSanitizer flagged
+a **384-byte arena chunk as unreachable at exit**. The agent's
+`black_box(&arena)` keeps the arena live only until its scope *closes* —
+but `process::exit` runs *after* that scope, so at the moment of exit the
+arena is genuinely unreachable. A real leak. The agent's own hypothesis
+had even named the risk ("if the sanitizer still flags the leak,
+rejected-gates is the honest outcome") — the pipeline simply had no
+sanitizer gate to trip, because in Phase 2 ASan/LSan were a per-attempt
+*manual* step.
+
+Called per SPEC §10: a **pipeline false accept**, caught by audit
+**before anything shipped**. The win was never banked. Shipped false
+accepts across the entire project remain **zero**.
+
+## The fix made the machine enforce the tier
+
+The corrective action was not "be more careful." It was structural:
+`verdict` now **builds the patched tree with ASan+LSan (ASan+UBSan for
+C/C++) and runs the pinned workload on every would-be accept**, capping
+any sanitizer-flagged win at `needs-human-review`. The tier rule SPEC §8
+always specified is now enforced by the machine, not the auditor. The
+very next Rust accept (`phase2-tokei-008`) and the first C accept
+(`phase3-cjson-002`) both passed through this automated gate.
+
+The 10k-input differential fuzz on the overturned patch found **0
+divergences** — the output equivalence was genuinely real. Only the
+teardown-leak tier was wrong. That is the subtle failure mode the layered
+gates exist for: a change can be behaviorally equivalent on output and
+still unacceptable on a dimension the bench and the golden replay can't
+see.
+
+## What it demonstrates
+
+The product is not "an agent that finds speedups." The product is
+**trust** — and trust is demonstrated most by the case where the
+optimistic path failed and the structural controls held. An agent
+graded only by accept-rate would have banked this win. The ledger is
+append-only, so the `accepted` row still stands, immutable — with this
+document as the permanent corrective record beside it.

results/phase3/04-cjson-c-target.md

@@ -0,0 +1,86 @@
+# Case study 4 — cJSON: the cross-language proof (C, classes 3 + 5)
+
+**Target:** [cJSON](https://github.com/DaveGamble/cJSON) v1.7.19 — an
+ultralightweight C JSON parser/printer, MIT. **Workload:** a 5.6 MB
+deterministic JSON corpus (20k records: nested objects/arrays,
+escaped/unicode strings, integers, dense floats), parsed and serialized,
+single-threaded, CPU-pinned. **Result:** the first verified win on a
+C/C++ target — proof the trust layer, the gates, and the ROI story
+carry across languages, not just across Rust crates.
+
+## Getting C through the same pipeline
+
+Nothing in the trust layer assumes cargo anymore. cJSON is "just a
+`target.toml`" pointing at `clang` build commands, with:
+
+- a **hermetic Unity/CTest suite** (19 tests: `parse_number`,
+  `parse_string`, `print_*`, `misc_tests`, …) as the upstream-test gate;
+- a **trust-layer harness driver** (`targets/cjson/harness.c`) compiled
+  *with* the patched `cJSON.c` — the agent can patch the parser but not
+  the measurement rig (it lives outside the workspace allowlist);
+- **ASan + UBSan** as the sanitizer gate (the C analogue of the Rust
+  nightly ASan path);
+- its own **A/A calibration**: 0/20 false positives, 20/20
+  injected-slowdown detections — the C workload is a trusted anchor
+  before any verdict runs.
+
+## The profile
+
+callgrind cache-sim put **~22% of instructions in glibc float I/O** —
+`__printf_fp` (number serialization) and `strtod`/`str_to_mpn` (number
+parsing) — plus `parse_value`, `parse_string`, and heavy malloc/free
+churn. A number-dense JSON document spends most of its time turning
+numbers into strings and back.
+
+## Attempt 1 — the honest rejection (`phase3-cjson-001`, class 3)
+
+`parse_number` heap-allocated a temporary NUL-terminated buffer
+(`malloc` + `memcpy` + `free`) for **every** number, just to hand a
+clean string to `strtod`. With ~100k+ numbers in the corpus that is a
+large share of the allocation churn. The fix: a 64-byte **stack buffer**
+for the common short-number case, heap only for pathologically long
+number strings — byte-identical (strtod sees the same bytes).
+
+- **Speedup: 1.012 median, 95% CI [1.004, 1.022]** → **rejected-bench.**
+
+A real mechanism, a real +1.2%, but the CI lower bound (+0.4%) does not
+clear the 2% bar — because the corpus's wall-clock is dominated by float
+*formatting*, not by malloc. The statistical bar rejected a genuine win,
+exactly as designed. It is in the ledger.
+
+## Attempt 2 — the accepted win (`phase3-cjson-002`, classes 5 + 3)
+
+Adding the class-5 lever: `print_number` verified every fractional
+number's `"%1.15g"` round-trip by calling **`sscanf("%lg")`** — a full
+`strtod` *plus* format-string interpretation, per number. Replacing it
+with a direct `strtod` is the identical parse with none of the
+format-string overhead. Combined with the stack buffer:
+
+- **Speedup: 1.089 median, 95% CI [1.075, 1.100]** → **accepted.**
+- Upstream Unity suite: **PASS**. Golden replay: **byte-identical**.
+- **ASan + UBSan: clean** — through the machine-enforced sanitizer gate.
+- **10,000-input differential fuzz** (`scripts/diff-fuzz-cjson.py`),
+  pristine vs candidate, **0 divergences**.
+
+A **+8.9%** verified win on a C target, banked.
+
+## A finding worth keeping
+
+The first cJSON accept nearly wasn't recorded: the ASan+UBSan build
+failed to link because the clang sanitizer runtime (`libclang_rt.asan`)
+was not installed, and `sanitizer_check` treated that as a hard error —
+crashing the verdict and losing the measured bench. The fix hardened the
+gate: an **infrastructure** build failure (missing runtime, broken
+toolchain) now caps the accept at `needs-human-review` and logs the
+failure for the operator, rather than discarding a real result. "Cannot
+verify" is a review tier, not a crash.
+
+## What it demonstrates
+
+The progression — a real win *rejected* for being too small, then a
+larger win *accepted* only after golden replay, fuzzing, and sanitizers
+all held — is the whole method in miniature, now shown on C. Nothing
+about the trust story is Rust-specific. The cheapest safe lever (skip a
+per-number allocation) wasn't enough; the algorithmic lever (stop doing a
+redundant heavyweight parse) was — and the pipeline proved it the same
+way it proves everything else.

results/phase3/README.md

@@ -0,0 +1,68 @@
+# Phase 3 — playbook + proof
+
+**Exit criteria (SPEC §5): 3–5 public case studies · zero regressions
+shipped · playbook ≥6 classes · C/C++ targets · coz.**
+
+Phase 3 turns the trust layer and the agent loop from Phases 1–2 into
+*evidence*: verified optimization wins across the playbook and across
+languages, each one reproducible from a pinned corpus through the same
+gated pipeline, with every attempt — win or loss — in the append-only
+ledger.
+
+## What changed for Phase 3
+
+- **The trust layer went language-agnostic.** Build isolation moved from
+  a cargo-specific `CARGO_TARGET_DIR` injection to an explicit `{out}`
+  placeholder plus optional `sanitizer`/`sanitizer_binary` build
+  templates (`crates/diff-test/src/target.rs`). A C/C++ target is now
+  just a `target.toml` with `clang` commands. Proven zero-regression:
+  tokei ran a full verdict through the refactored pipeline to a correct
+  null result before any C target was added.
+- **A C target joined the roster** — cJSON (v1.7.19, MIT), with a
+  trust-layer harness driver, a hermetic Unity/CTest gate, ASan+UBSan
+  sanitizers, a deterministic pinned corpus, and its own A/A calibration
+  (0/20 false positives, 20/20 injected-slowdown detections). CI gates
+  it on every push.
+- **coz** is wired (`-DHOTPATH_COZ` progress point, `just coz`,
+  `scripts/coz-*`); its apt runtime aborts in its own init on this
+  container's glibc (documented in `results/cjson/coz/README.md`), so
+  callgrind cache-sim is the working profiler.
+
+## Playbook classes exercised (≥6 required)
+
+| Class | Mechanism | Exercised on | Result |
+|---|---|---|---|
+| 1 | build config (LTO, codegen-units) | tokei | ✅ win (+10.4%) |
+| 2 | allocator swap (mimalloc) | comrak | needs-human-review (+4.6%) |
+| 3 | allocation churn | tokei, comrak, **cjson** | ✅ wins + one overturned |
+| 4 | data layout | comrak | attempted (rejected) |
+| 5 | algorithmic / redundant work | tokei ×3, **cjson** | ✅ wins |
+| 6 | SIMD / autovectorization | comrak, tokei | attempted (rejected) |
+
+Six classes exercised (1–6); class 5 and class 3 carry verified wins on
+both a Rust and a C target.
+
+## The case studies
+
+1. [`01-tokei-algorithmic-rust.md`](01-tokei-algorithmic-rust.md) —
+   three independent CI-verified class-5 wins on a Rust code counter
+   (~1.26× multiplied, stated as an approximation, not a measured
+   figure), each unattended and audited.
+2. [`02-build-flags-and-allocators.md`](02-build-flags-and-allocators.md)
+   — the cheap wins first: LTO (class 1) accepted, mimalloc (class 2)
+   correctly held at needs-human-review.
+3. [`03-comrak-caught-false-accept.md`](03-comrak-caught-false-accept.md)
+   — the pipeline auto-accepted a leaking teardown patch; the audit
+   overturned it and hardened the pipeline. The most important study.
+4. [`04-cjson-c-target.md`](04-cjson-c-target.md) — the cross-language
+   proof: a real sub-threshold win correctly rejected, then a byte-
+   identical number-handling win accepted on the C target.
+
+## The through-line
+
+Every number here carries its 95% bootstrap CI and its workload. Every
+win survived byte-identical golden replay, a 10k-input differential
+fuzz, and sanitizers. Every rejection is a real mechanism that simply
+didn't clear the 2% CI-lower-bound bar — and it is in the ledger too,
+because a rejection is a complete, valid outcome. Nothing shipped that
+the pipeline couldn't prove.