DR-133 — A test fixture carries bytes DISTINCT from the walked baseline

DR-133 — A test fixture carries bytes DISTINCT from the walked baseline

Context

resolve_or_mint_source_identity (20260703160100_id138_admission_identity_fn.sql) resolves source_documents identity content-hash first: the same bytes at a new path never re-mint. On a resolve it updates the mutable logical_path only — storage_path is the frozen seed-contract admission key and filename is never re-written.

The cocoindex nightly seeds and walks the whole vendored Platform corpus before the Vitest tier runs (measured S539, run 31156632408: 11 files, status=completed, item_failure_total: 0). Every CONTENT.* fixture is therefore already an admitted row by the time any test stages anything.

stageFixture performs no in-byte injection (OQ-62-6, deliberate), and pollContentItemsFor keys on filename ILIKE '<titlePrefix>%'.

Those three facts compose into a trap. A spec that stages a Platform-corpus content document under a test prefix resolves onto the baseline row, whose filename carries no prefix — so the poll times out by construction, and the failure reads as a pipeline drop rather than a fixture-choice error.

This was not hypothetical at the time of ruling:

• id-415 AC-1/2/3 instructs exactly this repoint, and could not have been executed as written.
• stage-5-row-counter (Inv-11) staged one fixture twice at -A/-B and asserted items.length >= 2 — unsatisfiable, since byte-identical bytes collapse to one row.
• source_documents f151eeb7 in Platform staging carries storage_path = content/synthetic-named-client-engagements.md against an INV-20 test’s filename and logical_path — a corpus document whose registry identity is entangled with a test fixture, already realised.
• The entanglement was also load-bearing in a data-loss defect: the nightly sweep matched on the rewritten logical_path and deleted a Platform-corpus document twice (fixed separately, S511 D1 / NM-6).

The pattern that works already existed, unregistered: scripts/tests/fixtures/entity-variants/ was created at S507 and its consumer records the reason — the pair is “deliberately distinct-bytes, so each staging lands its own source_documents row (the F4 hash-collapse gap never triggers)”.

Decision

An integration fixture staged under a per-test prefix carries bytes distinct from every walked-baseline document AND from every other per-test fixture, and is registered in the corpus manifest with staging_mode: per-test.

Walked-baseline documents are for tests that observe the baseline walk. They are not a fixture pool to re-stage. Neither is a per-test fixture a pool for a second test to re-stage: one distinct-bytes document, one consuming spec.

Amendment — the second collision axis (S543)

As first ruled, this decision named only the test ↔ baseline axis. Run 31271744240 — the first nightly to reach the Vitest tier since S539 — measured a second axis the original wording does not cover, and it accounted for more failures than the first did.

Five Stage-5 / entity specs each stage the same file, FORM_TEMPLATE.cspChecklistXlsx. Content-hash-first identity collapses all five onto one source_documents row, so each spec’s pollContentItemsFor races every other spec that stages those bytes. The forensics id-415 added at 41963a5e3 caught the row mid-collision:

filename     = [53.14-INV07-1786214321183-yj1yg5].xlsx        ← Inv-7 wrote this
logical_path = inv-7/[53.14-INV07-1786214321183-yj1yg5].xlsx
storage_path = inv-20/[28.14-INV20-1786213953199-rw8rin]-classification.xlsx
                                                              ← Inv-20 froze this
content_chunks per source_document: {}

One row, two specs’ names on it, storage_path frozen to whichever staged first and filename overwritten by whichever staged last. Inv-1, Inv-7, Inv-9, Inv-14 and Inv-17 all failed out of that single row; the test ↔ baseline axis produced two further failures (extract-contract-honour, legacy-alias-preload), both correctly refused by dropFixture rather than silently deleting a corpus document.

Why the original wording could not have caught it. “Distinct from every walked-baseline document” is satisfiable by five specs sharing one non-baseline file — and that is exactly the state the suite was in. The mechanism was never about the baseline; the baseline was just the first population large enough to collide with. Any two stagings of identical bytes collapse, whatever tree the bytes come from.

Two consequences that follow, and neither is a fixture-count nicety:

• A shared fixture constant used by more than one spec is now a defect at the declaration site, not a hazard at the staging site. FIXTURE_PATH = <shared> in two files is the bug.
• Cross-spec ordering becomes irrelevant to correctness. Under the old state, which spec ran first decided which spec’s storage_path survived — so the suite’s outcome depended on Vitest’s file scheduling, which is not a property any of these specs meant to assert.

Alternatives Considered

• Poll logical_path instead of filename. Works — logical_path is updated on resolve. Rejected: it rewrites the baseline row’s path and re-stamps its op_id, contaminating the walked baseline for every subsequent test, and it makes corpus rows look like test rows to anything keyed on path.
• Per-run byte perturbation at /stage. Rejected: reverses OQ-62-6’s explicit no-in-byte-injection ruling, and cannot work for .xlsx / .pdf / .docx without a real document writer.
• Leave it and treat the timeouts as pipeline defects. Rejected on evidence: this is what had been happening, and it cost S538 an UNDECIDABLE plus a session of forensics.

Consequences

• Some content duplication between the corpus and the test fixture trees. This is accepted: the duplication is the point, because the test document genuinely is a different document, which is what content-hash identity is entitled to assume.
• id-415 AC-1/2/3’s “repoint to Platform-corpus content docs” cannot be executed literally; the repoint is to a distinct-bytes tier.
• New fixture trees must be registered in the manifest, or the orphan rule cannot see them — entity-variants was consumed by two specs for months while being invisible to the guard.
• A fixture pair testing cross-document resolution must additionally disagree on surface form while agreeing on referent; distinct bytes alone are not enough to give Stage-5 something to resolve.
• (S543 amendment) The per-test tier grows one document per consuming spec rather than one per fixture kind. That is more files than a reader expects, and the reason has to travel with them or someone will helpfully deduplicate the tree back into the defect.