M9 finish (2/2): §14.9 differential / reference-parser tester

[guyo13]

M9 finish, task 2 of 2 — the §14.9 differential tester

Builds on the Task-1 regrown corpus (#34, merged). This is the technique that catches a recovery-classifier error by construction — two independent implementations disagreeing — rather than probabilistically (a fuzzer happening to hit the trigger). It exists precisely because the issue-#26 sentinel hole was that class of bug: a classifier mis-mapping one byte pattern.

What's here

• tests/differential.rs — an independent reference segment parser run alongside the production recover_segment classifier, with an exact-match oracle on the SegClass variant and its offset/max_lsn.
• Independence (the hard rule): the reference calls no production parse code — not record::decode, not recover_segment, not the segment.rs read helpers. It re-derives the §5.2/§5.3 constants and re-implements the length-bound check, the all-zero-header sentinel rule (post Durability contract correctness issue - Sentinel silent truncation #26), the CRC-validation ordering, the bounded tail-vs-corruption forward scan (lsn >= expected, bound max+28), and the sealed-vs-active distinction from raw bytes. It uses only the shared crc32c primitive (a dependency, not parse logic — re-implementing CRC-32C would test the crate, not the parser).
• Post-Durability contract correctness issue - Sentinel silent truncation #26 contract: the reference treats a rec_type == 0 record with a non-zero CRC as Invalid (→ TornMidLog interior / torn-tail at the end), never a clean sentinel — the correct current spec.

Inputs (both parsers see identical bytes)

1. Scenario matrix — 184 cases, enumerating every classification arm: clean runs (payload sizes 0/1/7/8/max), torn tails (CRC flip / rec_type→0 / extend-len / reserved-type / pad-flip), interior corruption (incl. the issue-Durability contract correctness issue - Sentinel silent truncation #26 rec_type→0 vector), LSN gaps, mid-run sentinel, physical truncation, within/beyond-scan-bound continuations, len>max, non-1 bases — each for active and sealed segments. This is the exact-match oracle.
2. The committed Task-1 corpora (fuzz/corpus/{recovery,structure,decode,model}) as raw segment bodies — 1666 inputs of real fuzzer-discovered byte patterns the two parsers must still agree on.

Green here: 184 + 1666 agree, ~6 s.

Falsifiability (§14.0.3)

Injecting the pre-#26 naive rec_type == 0 ⇒ sentinel rule into the reference makes the differential fire —

DIVERGENCE [torn-last-zero_rectype] … production=Truncated { offset: 128, max_lsn: 2 } reference=Clean { max_lsn: 2 }
DIVERGENCE [corpus/recovery]        … production=Truncated { offset: 64,  max_lsn: 0 } reference=Clean { max_lsn: 0 }

— i.e. the harness would have caught the sentinel bug. Reverted.

Scope note (honest, per the kickoff)

The corpus is consumed as raw segment bodies rather than by re-decoding each fuzz target's arbitrary envelope (which would duplicate those generators and be fragile). The differential property "both parsers agree on these bytes" holds regardless of how the bytes were produced; the envelope-specific deep states are covered exhaustively by the scenario matrix. No §14.3-model-oracle→differential wiring (corpus-driven is acceptable for v1 per the kickoff).

src/ change & release impact

The only src/ change is a thin #[cfg(feature="fuzzing")] recover_segment_classify accessor in lib.rs (returns a plain SegClass). No public API widening, no second production parser. The test is #[cfg(feature="fuzzing")], so default cargo build/cargo test compile it to nothing — zero release impact.

CI

Per-PR blocking differential (§14.9) job in ci.yml (cargo test --features fuzzing --test differential, ~6 s). A classification divergence is a real recovery-classifier bug and reds the PR — same posture as the fuzz smoke; never gates an H1 dispatch.

Verification

cargo fmt --check, cargo clippy --all-targets -D warnings (default and --features fuzzing), default cargo test (differential compiles to nothing), cargo test --features fuzzing --test differential, MSRV 1.85 cargo check --all-targets --locked, actionlint — all green.

Docs

§14.9 marked implemented, §14.11 per-PR row, §14.12 D4/D5/D10/D11 rows now cite the differential, §14.13 DoD bullet, CLAUDE.md.

After this

M9 finish follow-ups remain (separate PRs, per the designer's close-out): (1+2) a deterministic interior-rec_type→0 permanent regression seed + the fuzz-coverage trust-model writeup, then (3) the DoD reconciliation audit. After those, M9 is software-complete (only the passive fuzz-hours / multi-hour-soak runner gates remain).

🤖 Generated with Claude Code

---

Generated by Claude Code