test(scripts): pin the prose attached to the eager-closure baselines to the values it explains

[yinlianghui]

Fixes #7046

VERDICT_CEILING_CONSTANTS in scripts/check-eager-closure-budget.mjs deliberately excludes BASELINE and PER_CHUNK_BASELINE — no verdict is computed from them, so evaluateCeilingFreshness, the check that keeps every other constant in that file honest, structurally cannot see them, and the only thing describing them is a comment. #6778 measured what that costs. This adds the cheap backstop the card asked for, in scripts/__tests__/check-eager-closure-budget.test.ts. No constant value, ceiling, verdict path or export of the gate script changes — the diff is one test file, and the .mjs blob is byte-identical to main (proven below).

What the pins assert

Six new cases in one describe, all positive pins: a live value the prose claims must equal the value the module actually exports. The constants are read by importing the module; the prose is read out of the real file text.

Pin	Asserts
locator control	The attached block really is the attached block: control phrases that must hit and do, neighbour phrases that must not, and the commit: line excluded from the prose side
(a) positive pin	Every commit string a baseline carries as data appears in its own attached prose
carried-data shape	BASELINE carries exactly one commit; PER_CHUNK_BASELINE carries none — recorded so the pin above cannot go vacuous in silence
claim pin	Every BASELINE's `HASH` claim in either attached block names BASELINE.commit, and at least one such claim still exists
chunk-name pin	Every chunk name PER_CHUNK_BASELINE carries appears in its per-key provenance list

"Attached block" is located structurally

attachedDocs(source, exportName) finds the JSDoc block ending immediately before the export const NAME declaration, then walks the initializer — skipping comments and string literals — until the brackets it opened close again, collecting the comments met on the way. No line numbers anywhere; the card's warning that citations in this area rot within days applies to the test as much as to the prose.

Both halves are load-bearing, and this is a measurement, not a preference:

• The leading block alone is not enough. Measured on main at 64d624ded: BASELINE's leading JSDoc carries zero commit hashes. The sentence naming the commit the measurement was taken on is the JSDoc on the gzipBytes field, inside the object literal. A pin scoped to the leading block alone would be red on an honest file. This is the one place the shipped shape departs from the letter of the dispatch ruling ("the JSDoc comment that ends immediately before the declaration"); it is declared here rather than worked around, and the ruling's intent — structural, never a line number — is kept.
• The whole declaration text is too much. commit: '3d257c85a' would satisfy the pin by restating the constant: the prose about the value passing because it contains the value, which is this card's own defect one layer up. The locator case asserts the commit: line is on the code side and not the prose side.

The (a) / (b) decision, and the measurement behind it

Shipped: (a) alone. (b) is not shipped.

Measured on main at 64d624ded, 9-hex tokens per attached block (prose side only, code excluded):

Attached block	Commit tokens in its prose	Carried as data
BASELINE	3d257c85a (current), bd2a7ec50 (history — "the previous baseline")	3d257c85a
PER_CHUNK_BASELINE	2c8474c04, a64e96ca8, 3d257c85a, 350509b53, e33b44796	none

Two things follow, and both are the reason (b) stays on the shelf:

1. (b) is red on the honest file before any mutation. Under BASELINE it fires on bd2a7ec50, exactly as the dispatch's own reading predicted. Under PER_CHUNK_BASELINE it is worse: that constant carries no commit at all, so every one of its five hashes is an "other" hash and (b) fires five times on text that is correct.
2. No marker rescues it. A past-tense marker could legalise bd2a7ec50, but 2c8474c04 and a64e96ca8 are present-tense per-key provenance — marking them as history would be false, and leaving them unmarked keeps (b) red. Legalising them instead would mean pinning them against something, and there is nothing to pin them against: no export carries them. Making (b) green would take rewriting the narrative comments, which the ruling rules out as not worth it.

⚠️ The sharper finding: (a) as literally specified would not have caught #6778. That defect was a sentence in PER_CHUNK_BASELINE's block naming a retired hash as what BASELINE carried — and PER_CHUNK_BASELINE carries no commit string, so the per-constant positive pin says nothing about its block. The dispatch ruling anticipated the per-chunk constant carrying more than one commit string; read off the module, it carries zero. That is why this PR ships the claim pin as well: it is still a positive pin (a cited value must equal a live value, so it has no false-positive surface on history — nobody writes BASELINE's `x` about a hash it used to carry), and it is the leg that actually guards the shape #6778 found. The claim pin matches exactly one site in all 1,450 lines of the file today, at the sentence PR #7045 repaired.

Values are not pinned into prose: measured, neither attached block cites any of the four numeric readings the two constants carry, so a value pin would also be red on an honest file.

Ablation

Every leg mutates the real scripts/check-eager-closure-budget.mjs in the worktree, under an EXIT INT TERM trap with absolute paths. The mutation is proven on disk by grep -c before/after and by the blob hash differing from HEAD's; the restore is proven by git hash-object equalling the HEAD blob and by an empty git diff HEAD for that path — never by an exit code. HEAD blob for that path throughout: e830ac3a67b4e6c2a91db82e36dc6ee8415bbe8b.

Leg	Mutation	On-disk proof	Result	Restore
A1	prose hash in BASELINE's block to the retired 4c1623c0c	`3d257c85a` is the commit 1 to 0; injected 0 to 1; blob 6cad9fa96	exit 1 — 1 failed / 86 passed, pins every commit BASELINE carries into its own attached prose	blob back to e830ac3a6, diff empty
A2	BASELINE's `3d257c85a` to BASELINE's `4c1623c0c` — the #6778 defect restored verbatim	anchor 1 to 0; injected 0 to 1; blob f31caf4af	exit 1 — 1 failed / 86 passed, holds every "BASELINE carries X" claim in the attached prose to the live value	blob back to e830ac3a6, diff empty
A3	ui-components to ui-widgets on the 2 prose lines of PER_CHUNK_BASELINE's block (declaration untouched)	4 to 2 file-wide; injected 0 to 2; blob 1876de838	exit 1 — 1 failed / 86 passed, pins every chunk name PER_CHUNK_BASELINE carries into its own attached prose	blob back to e830ac3a6, diff empty
A4	control term Provenance is per KEY to per LOCALE	1 to 0; injected 0 to 1; blob 60134b328	exit 1 — 1 failed / 86 passed, locates the block attached to each baseline, and only that block	blob back to e830ac3a6, diff empty
A5	BASELINE.commit re-baselined to e33b44796, every word of prose left untouched	1 to 0; injected 0 to 1; blob e238500005	exit 1 — 2 failed / 85 passed (A1's and A2's cases)	blob back to e830ac3a6, diff empty

A5 is what proves the pin reads the module and not two halves of the same text — the re-baseline shape the card is about: the constant moves, the paragraph is left behind, and the test reds the same minute instead of three re-baselines later.

A4 is the "prove the assertion sees the real block" fence. The control terms are the previous baseline (in BASELINE's block) and Provenance is per KEY (in PER_CHUNK_BASELINE's), both verified present before being asserted; A4 shows the assertion actually depends on the block's real text. The same case also asserts the neighbouring ceilings' blocks are not swept in.

⚠️ One process note worth recording: A3's first attempt asserted it would rewrite 2 lines and hit 3 — the structural block walk had run past the declaration and would have mutated the constant's own key, which would have moved both sides of the pin and proven nothing. The mutation script refused instead of writing, the trap restored, and the leg was re-scoped to prose only. A mutation script's exit code is not evidence that the right bytes moved.

Gates

Run from the worktree at 2a3144b6e, exit codes captured by redirect-then-$?, never through a pipe:

• pnpm exec vitest run scripts/__tests__/check-eager-closure-budget.test.ts --maxWorkers=2 — exit 0, Test Files 1 passed (1) / Tests 87 passed (87) (81 before, 6 added).
• Widened to every test file in scripts/__tests__/ that names this gate — exit 0, Test Files 5 passed (5) / Tests 197 passed (197) on 2a3144b6e with a clean tree.
• pnpm type-check:scripts — exit 0.
• pnpm check:control-bytes — exit 0, ✅ check-control-bytes: OK (scanned 6004 tracked text file(s); skipped 85 binary).
• pnpm check:entry-guard — exit 0, ✓ check:entry-guard: 58 scripts/ file(s) — no entry guard outside the baseline; ...
• node scripts/check-changeset-presence.mjs — exit 0, ✅ No source or published contract of a released package changed in this range, so no changeset is owed. Scripts-only change, so no changeset ships.
• pnpm exec eslint scripts/__tests__/check-eager-closure-budget.test.ts --no-inline-config --format json — exit 0, 1 file linted, 0 errors, 0 warnings, 0 suppressed.
• Control-byte self-scan on the edited file beyond the gate: grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' — no match.

Declared narrowing

The full scripts/__tests__/ directory was not run locally; the shared heavy-verify lock had a holder and two waiters, and this diff touches one file with no test in that directory enumerating the directory or reading this file (checked: grep -rln "readdirSync.*__tests__" returns nothing). CI runs the directory. Repo-wide lint is not narrowed but out of reach by construction: root lint is turbo run lint, which is driven by package.json scripts and so cannot reach scripts/, a non-package directory — the direct eslint invocation above is the whole of what applies, and eslint here is not type-aware (no projectService, no project, tseslint.configs.recommended rather than recommendedTypeChecked), so no untouched file's verdict can move from this diff.

Scope

scripts/vite-declared-lazy-views.ts (#6785, closed) was not touched. The mechanism does generalise to it — attachedDocs is not specific to this file — and that is recorded as a finding for the PM rather than ridden along here.

#6785 and #6631 are not addressed by this PR; #6631 in particular stays open, and its "which side moved the headroom" question is untouched.

https://claude.ai/code/session_01BGMDbrVa8JjZcCQ7DWYH1b

---

Generated by Claude Code