test(spec): split key-mention.test.ts's conflated shipped-ledger case onto a witness pair

[os-trump]

Fixes#12462

packages/spec/scripts/liveness/key-mention.baseline.json declares itself, in its own _note, a SHRINK-ONLY RATCHET (#11457) — a finite, enumerated debt ledger that exists to be driven to zero. Its twin pinned that debt as PRESENT.

What was wrong

One case conflated two claims:

it('parses the SHIPPED baseline, and every row explains which name the file uses',()=>{constdoc=parseKeyMentionBaseline(JSON.parse(readFileSync(join(here,'key-mention.baseline.json'),'utf8')),);expect(doc.exemptions.length).toBeGreaterThan(0);for(constrowofdoc.exemptions)expect(row.why.length).toBeGreaterThan(40);});

• The floor is a pin on the debt being present. It goes red on the commit that deletes the last exemption — i.e. exactly when the burn-down SUCCEEDS. Both reactions available to the seat that hits it are wrong: park a row to keep the test green, or weaken the assertion.
• Deleting the floor alone would not have been the repair either. The loop one line later asserts nothing over an empty array — the second-order [].every(...) defect PR test(devx): sweep the shrink-only ratchet self-tests for baseline-presence pins — 33 derived, 1 repaired #12050's witness pair was introduced to prevent — so it would trade a red for a silent no-op.

What this changes

The two claims are split, per the PR #12050 witness-pair idiom, which the triage grading (comment 5420740937) adopted as the route:

1. The parser and the row-quality rule, carried on a SYNTHETIC witness pair. A conforming row the parser accepts and the rule holds for, and a structurally valid row that only reassures (why: 'this is fine') — which the parser accepts and the rule refuses. Neither witness reads the shipped file, so both halves keep discriminating once the ledger reaches zero.
2. The shipped ledger, held to the same rule CONDITIONALLY on rows existing. The read is asserted independently of the row count — the ledger's _note has to come back naming the ratchet — so [finding] a shrink-only ratchet whose self-test asserts its own entries are PRESENT can never reach zero — one instance found and fixed, the class unswept #11694's carried rule holds: an empty ledger cannot become readable as an empty population or as a silent no-read. The row check is vacuous at zero by design and says so; claim 1 is where the rule keeps its teeth at that point.

The rule itself (a why longer than 40 characters — the original threshold, carried over unchanged) is named once, so the pair and the shipped ledger cannot be held to two definitions of it that drift apart.

Reverse verification

Five legs. Every mutation was confirmed on disk by anchor / injection occurrence counts before the run (the mutator refuses to write at all unless the anchor occurs exactly once, and re-counts after writing), and every restore is proved by git diff HEAD coming back empty plus a blob-hash match against the HEAD blob — not by an exit code.

leg	mutation	predicted	observed
1	positive witness's why shortened below the threshold	witness-pair case RED, ledger case GREEN	1 failed / 22 passed — AssertionError: expected false to be true on the witness-pair case
2	negative witness's why lengthened past the threshold	witness-pair case RED, ledger case GREEN	1 failed / 22 passed — AssertionError: expected true to be false
3	the ledger read repointed at a missing filename	ledger case RED, witness pair GREEN	1 failed / 22 passed — Error: ENOENT ... key-mention.baseline.MUTATION-leg3-missing.json
4	ledger case parses a synthetic ZERO-row document	all GREEN — zero rows must no longer red the twin	23 passed
5	the OLD conflated assertions against that same zero-row ledger	RED — the card's premise, checked rather than assumed	1 failed / 22 passed — AssertionError: expected 0 to be greater than 0

Legs 4 and 5 are the pair that matters: the shape this PR removes fails exactly when the #11457 burn-down succeeds, and the shape it installs does not — while legs 1 and 2 show the witness pair still discriminates at that point, since both witnesses are synthetic and the ledger's contents cannot reach them. Leg 3 is #11694's other half: a file that was never read still fails loudly, where the old vacuous loop would have been silent.

Verification

Union re-run after the final commit, at aebe81bd6 — which includes a git merge origin/main bringing #12957 (scripts/check-type-check-coverage.mjs only; no overlap with this diff).

• pnpm --filter @objectstack/spec exec vitest run scripts/liveness/ — 10 files / 236 tests passed. key-mention.test.ts goes 22 to 23 cases: one case split into two.
• pnpm --filter @objectstack/spec run check:liveness — green. This PR changes the gate's TWIN, not the gate: key-mention anchoring: 402 (entry, cited file) pair(s) asked, 401 anchored, 1 exempt.
• pnpm --filter @objectstack/spec run check:scripts-typecheck — green, and tsc --listFiles confirms key-mention.test.ts is genuinely in that program, so the green is a measurement of this edit rather than a program that never read it.
• Convention-triggered by "edits a test file", all green: check:engine-double-contract, check:where-matcher, check:objectql-double-limit, check:query-options-erasure, check:cross-package-test-inputs, check:type-check-coverage. The three ratchets re-verified their baseline key set against 3404bd1 with no files added.
• Also green: check:nul-bytes, check:test-source-alias, check:published-files, check:merge-driver, and spec check:empty-state / check:strictness-ledger / check:variant-docs.

Declared narrowing:check:type-check-debt --re-measure was not run locally — it needs the whole workspace closure built and refuses outright on an unbuilt worktree. This diff adds no file and no ledger entry, scripts/** enters the spec package's type-check with ZERO ledger entries, and a plain tsc --noEmit -p tsconfig.scripts.json (green above, with the edited file proved to be in the program) is the stricter gate for that layer. CI runs it either way.

Scope

Exactly one file: packages/spec/scripts/liveness/key-mention.test.ts. key-mention.baseline.json is untouched, and so are the other seven liveness twins and the three other toBeGreaterThan(0) sites the filer measured as NOT this shape (empty-state.test.ts:273, proof-registry.test.ts:92, readme-table.test.ts:49,101) — the triage scope fence, no sweep-widening.

Releases nothing

One internal-tooling test file inside a published package. No user-visible behaviour changes, no export moves, no schema or contract change — so there is no changeset. This repo routes that through the skip-changeset label, which pr-automation.yml reads live to exempt the changeset check; the label is on this PR. Removing it restores the normal changeset requirement if the grading disagrees.

Draft on purpose: this lands through the normal ready-then-queue path after review, not from here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json fa5d137ab01015fe56a08845cb8423b08e326219 → packageMentionDocs.