test generalization

TESTING.md

@@ -331,6 +331,63 @@ See `docs/design-test-infra.md` and ROADMAP §Lane 2 Stage 2c for
 the DB-15 trajectory. This document is the near-term discipline
 for Rust-side tests while that runtime matures.
 
+## Cementing tests (Band C — lens subsumption)
+
+**Where this applies.** Whenever a brief, roadmap line, or review
+claims that v3 **subsumes** or is **behaviorally equivalent** to a
+v2 analysis for the same program text, that claim is a Band-C
+statement about the *function* of the lens, not about whether the
+`.dag` file is structurally terminal. The authoritative inventory
+is `docs/v3-lens-capability-register.md` (behavioral axis + v2
+counterpart column). Any `LensRegistryEntry` in
+`src/v3/compiler/regen.dag` whose row moves to
+`BEHAVIORALLY COMPLETE` while still naming a real v2 counterpart
+(not `None (v3-native)` / not `N/A`) inherits the same obligation.
+
+**What “cementing” means.** A cementing test is a **behavioral**
+regression that would fail if v3 silently changed the analysis
+while prose still claimed parity. Concretely:
+
+- **v2 counterpart exists:** run the same minimal fixture through
+  both implementations (v2 oracle + v3 lens output) and assert
+  semantic equality on the published carrier shape — or assert a
+  documented, reviewed projection when the types differ but the
+  claim is about a specific homomorphism.
+- **No v2 counterpart (`N/A` / v3-native) but the register marks
+  `BEHAVIORALLY COMPLETE`:** pin the lens’s published behavioral
+  contract on **minimal constructed `Dag` shapes** (or a single
+  tiny `compile_to_dag` fixture when the contract genuinely spans
+  the pipeline). This is still a cementing test: it cements the
+  `COMPLETE` row against accidental semantic drift.
+
+**Where tests live.** Add modules under
+`src/v3/compiler/tests/integration/cementing/` and register each
+file from `src/v3/compiler/tests/integration.rs` via `#[path =
+"integration/cementing/<file>.rs"]`. Prefer one focused module per
+lens (or per v2 parity claim), not a kitchen-sink file.
+
+**Dispatch (same PR as the claim).** Editing
+`src/v3/compiler/regen.dag` or promoting a register row to
+`COMPLETE` with v2 parity is not complete until the matching
+cementing module exists and `tests/integration.rs` wires it. Extend
+`CEMENTING_MODULES_FOR_V2_COMPLETE_CLAIMS` in
+`tests/integration/cementing/cementing_lens_registry_dispatch_test.rs`
+when the register row is upgraded; the test
+`cementing_escalation_slice_matches_capability_register` derives the
+required registry `name` keys from `docs/v3-lens-capability-register.md`
+plus `regen.dag` and asserts the slice matches **exactly** (the slice
+is a projection, not a parallel inventory). The test
+`cementing_test_modules_exist_for_escalated_v2_complete_registry_claims`
+then requires each listed stem to resolve to an on-disk `.rs` file under
+`cementing/` **and** to appear in `tests/integration.rs` behind an
+exact `#[path = "integration/cementing/<stem>.rs"]` attribute (so an
+orphan file cannot satisfy the ratchet).
+
+**Anti-scope.** This section is not a mandate to prove full lens
+equivalence for every `.dag` file, and it does not require new
+substrate accessors or emitters. It only governs **explicit**
+subsumption or `COMPLETE`-with-counterpart claims.
+
 ## Related
 
 - `INVARIANTS.md` — project-level invariants; some have direct
@@ -339,3 +396,5 @@ for Rust-side tests while that runtime matures.
   the modeled concepts, not rebuild them
 - `docs/design-test-infra.md` (DB-15) — the `.dag`-native test
   infrastructure this document is the stopgap for
+- `docs/v3-lens-capability-register.md` — Band-C behavioral axis;
+  cross-check before dispatching “v3 replaces v2 X” briefs

docs/v3-lens-capability-register.md

@@ -78,6 +78,7 @@ The register is a tool, not a document. If it is stale, it is worse than not exi
 3. **Review at every ROADMAP dispatch.** Before queueing a brief that depends on a lens being equivalent to its v2 counterpart (e.g., "compare v3 complexity output against v2 complexity output"), check the row. If the row says `PROXY` or `STUB`, the brief is premature and must either wait for substrate/emit work or narrow its scope to what the lens actually computes.
 4. **Downgrades are first-class.** A lens that regresses from `COMPLETE` to `PROXY` (e.g., because a cementing test failed and was weakened rather than fixed) belongs in this register immediately. Silent downgrade is the failure mode this document exists to catch.
 5. **The two axes do not trade off.** `STRUCTURALLY TERMINAL` + `BEHAVIORALLY PROXY` is a valid, honest state — a well-formed file computing a weaker function than its name implies. It is not a contradiction. Claiming `COMPLETE` because the file is structurally clean is the mistake this register is named against.
+6. **Cementing tests have a canonical home in-tree.** In-repo dispatch (fixture layout, v2-oracle vs minimal-`Dag` contract tests, and the `regen.dag` → register → test-module ratchet) lives in `TESTING.md` under *Cementing tests (Band C — lens subsumption)* and in `src/v3/compiler/tests/integration/cementing/cementing_lens_registry_dispatch_test.rs`. `cementing_escalation_slice_matches_capability_register` mechanically aligns `CEMENTING_MODULES_FOR_V2_COMPLETE_CLAIMS` with this table plus `regen.dag` (the slice is a projection, not a second authority). The follow-on ratchet checks both an on-disk `cementing/<stem>.rs` and a matching `#[path = ...]` line in `tests/integration.rs` for each escalated claim. Promoting a row to `BEHAVIORALLY COMPLETE` with a non-`N/A` v2 counterpart without landing the cementing module in the same PR is a process failure, not a modeling disagreement.
 
 ## Related docs
 

src/v3/compiler/regen.dag

@@ -24,6 +24,16 @@ import std.types { FilePath, NonEmptyStr }
 // means empty-string entries cannot be lowered into the registry,
 // closing the "illegal states representable" hole that a raw
 // `String` would leave open across all three fields.
+//
+// **Band-C cementing dispatch.** Each new `LensRegistryEntry` must
+// update `docs/v3-lens-capability-register.md` (see its Discipline
+// section). If the register row is `BEHAVIORALLY COMPLETE` and names
+// a concrete v2 counterpart, add a matching behavioral cementing
+// module under `src/v3/compiler/tests/integration/cementing/`, wire it
+// in `tests/integration.rs` via `#[path = "integration/cementing/<stem>.rs"]`,
+// and extend the ratchet slice in
+// `cementing_lens_registry_dispatch_test.rs` in the same PR. See
+// `TESTING.md` ("Cementing tests (Band C — lens subsumption)").
 
 type LensRegistryEntry {
   name: NonEmptyStr