RQ-58-MIRRORS (#242): generate, don't mirror — the freshness gate can now see template-vs-code drift

[avrabe]

Lane 3 of the v0.58 hub — artifact RQ-58-MIRRORS, epic #242.

The counts, reproduced

The spec's figures reproduce exactly, and their scope is the first finding:

git ls-files 'crates/*' | grep '\.rs$' | xargs grep -lIi mirror                 -> 57
                                       | xargs grep -lIi hand-maintained        -> 11
                                       | xargs grep -lIi 'single source of truth'->  1

Repo-wide over all tracked text files the same three greps give 125 / 22 / 8. The 68 files outside crates/**/*.rs include scripts/ (18) and docs (18) — where the FEATURE_MATRIX rot actually lived. And "mentions the word mirror" is not "is a mirror": neither exec_trap_subset_op's allowlist nor the referenced_locals triplication would be found by that grep. The ranked inventory below was built by searching the shapes ("keep in sync", "must match", allowlist/decline-list literals, one enum matched exhaustively in several files).

What the freshness gate can now catch

check_generated_fresh byte-compares the rendered matrix against the template, and render_feature_matrix only substitutes {{...}}. It proves the render is faithful to the template and never that the template is faithful to the code.

Two mechanisms close different halves of that:

1. Derivation (catches code drift). artifacts/aarch64-op-surface.json is EMITTED by the op-parity oracle running the real select_typed_cf_calls over every WasmOp representative — 197 probe labels, 185 lowered / 12 declined, 0 unprobed. The template substitutes it. This is the #667 pattern, and it is what would have caught the v0.57 failure: the shipped capability that was still listed as a decline was local.set/local.tee on a param, which the artifact now records as lowered.

2. Exhaustiveness (catches unclassified assertions). check_template_facts requires every number in the template to be one of DERIVED ({{field}}), PINNED (a claim whose doc: is the template — the #880 mechanism, which existed but had no exhaustiveness), UNCHECKED (declared with a ≥20-char rationale) or MASKED (an identifier token, each mask declared with a why:). Dead entries and dead masks are red too.

Census: 25 derived · 12 pinned · 21 unchecked · 208 masked.

What remains explicitly UNCHECKED

• check_template_facts is NUMBERS-ONLY. Non-numeric prose assertions are outside its reach — including the whole module/shape-level aarch64 decline list, the exact class that went stale twice. What covers that class now is the derivation, not this gate.
• 21 declared unchecked template numbers, each with its rationale and, where one exists, the specific conversion that would close it. That list is the risk register.
• The gate does not prove a pinned or unchecked claim true. It proves every assertion was classified on purpose and fails closed on new ones. The mask list is the residual trust, in claims.yaml so it is reviewable.
• Module/shape-level aarch64 declines were verified once here (18/18 declined, one probe module each) and are re-checked by nothing per commit.

Two findings about this lane's own work

• The matrix was already stale. It said 221-variant no-wildcard tripwire while both copies of ARM_OP_VARIANT_COUNT said 222 — rotted, behind a green 43/43, in the release about doc rot. Now derived ({{a32_tripwire_variants}}), renders 222.
• I cited a gate that does not exist. An early commit referenced scripts/repro/aarch64_decline_claims_242.py in a Rust comment and in the _scope string emitted into the artifact whose entire claim is "derived, never a hand list". No such file. Both replaced with the honest statement.

Ranked inventory

Full 21-entry version with paths, the wrong-ANSWER vs wrong-DOC discriminator, and what checks each today is a comment block at the head of claims.yaml. Tier 1 (wrong answer, nothing checked it):

#	Mirror	Status
1	count_params × 3 backends — three byte-equivalent copies of an unsound read-before-write heuristic	CONVERTED → synth_core::count_params_heuristic
2	aarch64 decline list: code vs FEATURE_MATRIX	CONVERTED → derived artifact + substitution
3	ARM_OP_VARIANT_COUNT × 2 tripwire files, guarded only by a comment	CONVERTED → fields-equal
4	all_wasm_op_representatives() hand-maintained Vec — and this lane made it feed a generated doc	CONVERTED → length pinned to the enum (279 == 279)
5	exec_trap_subset_op allowlist ↔ encode_op arms ↔ the test's re-list ("one hand-maintained mirror guarding another")	NOT converted; mitigated by ArmState::unmodeled at runtime
6	shrink_callee_saved_saves ↔ body_uses_callee_saved allowlists	NOT converted; guard is the comment
7	ResolvedBranchGeometry's Label = 0 table vs the estimator	NOT converted
8	reg_effect ↔ rewrite_op positional mirror	mutual-consistency oracle, "no third ground truth"

Tier 2 (checked): estimator↔encoder (the model to copy), RV32 sizing, WCET cycle literals, sel_dsl::RULES↔manifest↔.v, trap.rs↔ordeal, WasmOp in 5 places / ArmOp in 9 (pairwise only). Tier 3 (doc): known_divergences "18 entries" prose, ORACLE_WIRING's count-min-pinned "145 wired" (so it can silently understate), CRATES_TO_PUBLISH, RV32↔ARM startup/linker mirrors, a cross-repo STPA ABI constraint.

Red-first evidence — every new gate

Gate	Negative control	Result
op-surface artifact freshness	add a MemoryFill lowering arm to the aarch64 selector, touch nothing else	red: memory.fill flips declined→lowered
…→ render chain	regenerate the artifact only	red: status.json and FEATURE_MATRIX stale
check_template_facts	type a new unpinned number into template prose	red: UNCLASSIFIED number '4212'
"	delete an unchecked span from the template	red: dead-entry
"	delete three {{}} substitutions	red: derived floor 21 < 24
"	point a mask at a string that never appears	red: dead mask + 52 newly unclassified
fields-equal	set one ARM_OP_VARIANT_COUNT copy to 223	red: "copies of one constant DISAGREE: 222, 223"
anti-regrowth count-max 0	re-grow a private count_params in the aarch64 backend	red: "trusted base grew: 1 > recorded max 0"
representative coverage	delete I32Sub from the Vec	red: "278 entries but WasmOp declares 279"

Each restored → green. The {{}}-deletion control is the vacuity control: without the floors, an empty template classifies perfectly, so deleting assertions would have been the cheapest way to green the gate.

And the byte-identity evidence was itself needle-tested. count_params_heuristic only runs on the no-declared-count path, so a 512-object md5 sweep that never reaches it would print a perfect zero diff and prove nothing (v0.56's "a mutation test that never mutated printed ok"). Negative control: return a constant 7 → 174 of 510 hashes move, 2 compiles fail. The sweep does exercise it; the zero diff is evidence.

Gates

cargo test --workspace ok (142 suites) · cargo clippy --workspace --all-targets -- -D warnings ok · cargo fmt --check ok · claim_check 45/45 · model_coverage_audit --check ok · oracle_wiring_check ok · check_version_pins ok. Each run without a pipe. Derived docs regenerated with --emit-status; FEATURE_MATRIX.md never hand-edited.

Bazel runs zero rust_test targets (crates/BUILD.bazel globs src/**), so the two new tests' repo-relative reads are not exposed to a sandboxed rust_test.

No [Unreleased] CHANGELOG edit, no version bump.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YJK5LZZEkV5smCY1jKn18L

---

Addendum after merging origin/main (#991 RQ-58-METRIC + #992)

60/60 checks pass; merge state CLEAN.

MC/DC (RQ-57-MCDC) fired on this lane, correctly, and the fix was scope — not a floor. The count_params collapse moved decisions out of synth_backend_riscv::backend::, which is a scored prefix. Measured on ubuntu-latest / rustc 1.96.1 / witness 0.42.0, 56 rows:

	dec	cond	proved	dead
main	22	130	57	50
after the collapse, no scope change	21	131	56	45
+ the whole synth_core::wasm_op::	26	145	57	54 (ceiling 50)
+ only count_params_heuristic	22	135	57	48

Scoping to the relocated function meets every floor. The module-wide form would drag in rewrite_memory_grow_zero and referenced_locals — 9 conditions no row reaches, a real gap, but widening scope needs its own rows and its own re-measured ceiling. Named as a follow-up, not smuggled in. No floor lowered, no ceiling raised.

origin/main was red on its own subtraction ratchet, and this PR is the first to carry the fix. #992 merged first (102 code-region selector lines, one _ => arm); #991 pinned 18480/62 from a base predating it. Re-derived from main's own blob: 18582 lines / 63 arms / 29839 total / 106 total arms. Pins moved here with waivers attributing the growth to #992, not to this lane — the classic stale-base merge.

mirror_marker_files 57 → 58 is this lane's, and is waived rather than laundered. The added file is crates/synth-core/src/wasm_op.rs, and what it says is a retirement notice: count_params went from three copies to one. The proxied population went down by two copies while the file count went up by one — exactly the over-count that metric's own comment predicts. Deleting the word to go green would trade an accurate doc for a nicer number.

[codecov]

Codecov Report

❌ Patch coverage is 90.47619% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/synth-backend-aarch64/src/backend.rs	0.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!