Skip to content

Commit e7ebebd

Browse files
committed
docs(gate): stop check-engine-double-contract restating its own ledger size in prose
The pinned ledger is a generated artifact: `--write` — the action the gate's own failure messages instruct authors to take — moves its row count, and seven prose sites in this file had copied that count beside it. Five were already wrong (308/319 against a live 310/321), and one derived claim ("11 pairs carry more than one") was never right: 11 is the EXCESS of doubles over rows, while the number of rows pinning more than one is 10, as the paragraph 40 lines below already said. Each site is now either silent about the magnitude or resting on a claim the ratchets themselves guarantee (pinned is grow-only, the baseline shrink-only, so "already outnumbers" and "hundreds" cannot go stale). The two sites that state a genuinely un-derivable measurement are anchored as dated, past ones. Comment-only: no invariant, criterion, exit code, population or output string is touched. Part of #9915 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja
1 parent 90417a8 commit e7ebebd

1 file changed

Lines changed: 29 additions & 19 deletions

File tree

scripts/check-engine-double-contract.mjs

Lines changed: 29 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -203,17 +203,21 @@
203203
//
204204
// Method, stated so this can be redone rather than trusted: membership is
205205
// proxied by `assertEngine…Dispatch(` call sites in test files under the scan
206-
// roots, calibrated against this gate's own ledger at HEAD -- 0 false negatives
207-
// on the file sets, and 309 of 310 (file, verb) rows agreeing on the exact
208-
// count. Anyone re-running it must first prove their clone actually covers the
209-
// window; a shallow one silently answers for its own depth, which is the whole
210-
// reason this paragraph had to be rewritten.
206+
// roots, calibrated on 2026-08-19 against this gate's own ledger as it then
207+
// stood -- 0 false negatives on the file sets, and every (file, verb) row but
208+
// ONE agreeing on the exact count. That calibration is a dated measurement, not
209+
// a standing property; anyone re-running it must first prove their clone covers
210+
// the window; a shallow one silently answers for its own depth, which is the
211+
// whole reason this paragraph had to be rewritten.
211212
//
212213
// So the additions the ratchet does redden on are already in conversation with
213214
// this gate (they are new fakes that had to write `assert…Dispatch` because
214-
// PINNED demanded it). 310 entries today against the 135 the DEBT ledger
215-
// already carries: same file format, same order of magnitude, same
216-
// reconciliation shape.
215+
// PINNED demanded it). Set against the DEBT ledger this gate already carries,
216+
// the pinned ledger is the same file format, the same order of magnitude and
217+
// the same reconciliation shape -- so it is the maintenance cost already being
218+
// paid for the other ledger, not a new one. Both sizes are printed by a run and
219+
// countable in the artifacts; they are deliberately not copied into this prose,
220+
// because `--write` moves one of them and nothing here would notice.
217221
//
218222
// ## How a LEGITIMATE decrease is expressed (the anti-nuisance half)
219223
//
@@ -1476,10 +1480,12 @@ function readBaseline() {
14761480
* The RETAINED ledger (#9680) — the enumerated pinned population.
14771481
*
14781482
* Deliberately a SEPARATE artifact from `engine-double-contract.baseline.json`
1479-
* rather than more rows in it. The baseline is 135 hand-written MEASURED
1483+
* rather than more rows in it. The baseline is a set of hand-written MEASURED
14801484
* justifications whose readability this file's header calls the gate's whole
1481-
* value ("shrink-only, hand reviewed"); folding 308 generated rows in would
1482-
* bury the reasons under the census and blur which rows a human must agree to.
1485+
* value ("shrink-only, hand reviewed"); folding the generated rows in would
1486+
* bury the reasons under a census that ALREADY OUTNUMBERS them -- and, by the
1487+
* opposite polarities below, can only outnumber them further -- blurring which
1488+
* rows a human must agree to.
14831489
* These two ledgers also answer to opposite polarities — the baseline records
14841490
* debt and may only SHRINK, this one records coverage and may only GROW — so a
14851491
* reader who conflates them reads every ratchet in this file backwards.
@@ -1497,10 +1503,11 @@ function readPinnedLedger() {
14971503
* diff.
14981504
*
14991505
* Counted per FILE and not merely as membership, because a file may hold more
1500-
* than one pinned double for a verb — measured on this branch: 319 pinned
1501-
* doubles across 308 (file, verb) pairs, so 11 pairs carry more than one. A
1502-
* membership-only ledger would let a file that pins two deletes drop to one in
1503-
* silence, which is this card's defect at a finer grain.
1506+
* than one pinned double for a verb — the rows reading `"pinned"` above 1 in
1507+
* `engine-double-contract.pinned.json` are the live list, and the ledger is
1508+
* where to read how many there are rather than here. A membership-only ledger
1509+
* would let a file that pins two deletes drop to one in silence, which is this
1510+
* card's defect at a finer grain.
15041511
*/
15051512
function censusPinned(slices) {
15061513
const rows = [];
@@ -1537,7 +1544,8 @@ const pairKey = (file, verb) => JSON.stringify([file, verb]);
15371544
* remedy attached to the wrong story.
15381545
*
15391546
* Counted rather than a membership Set, because a file may pin several doubles
1540-
* for one verb (measured: 10 of 308 rows do). Membership alone cannot separate
1547+
* for one verb (the ledger rows reading `"pinned"` above 1 are the live list,
1548+
* as above). Membership alone cannot separate
15411549
* "the file pinned two deletes and now pins one because a MEMBER WAS DELETED"
15421550
* from "...because a member stopped calling the predicate", and those two want
15431551
* opposite remedies: restore the member vs re-pin it.
@@ -1578,8 +1586,9 @@ const REGEN = 'node scripts/check-engine-double-contract.mjs --write';
15781586
function retainedErrors(census, ledger, ledgerExists, declared, onDisk) {
15791587
const errors = [];
15801588

1581-
// Bootstrap. Without this a missing artifact reports 308 separate "not in the
1582-
// ledger" errors, which reads as a catastrophe and buries the one-line fix.
1589+
// Bootstrap. Without this a missing artifact reports one "not in the ledger"
1590+
// error per census row -- hundreds of them, and growing, since this ledger is
1591+
// grow-only -- which reads as a catastrophe and buries the one-line fix.
15831592
if (!ledgerExists) {
15841593
return [
15851594
`RETAINED: ${relative(ROOT, PINNED_LEDGER_PATH)} is missing. That file IS the pinned `
@@ -2915,7 +2924,8 @@ class Svc {
29152924
grewMore.length === 1 && anyOf(grewMore, 'Coverage grew'));
29162925

29172926
// ── Bootstrap: a missing ledger is ONE error, not one per row. The failure
2918-
// this guards is a fresh checkout reporting 308 problems for one missing file.
2927+
// this guards is a fresh checkout reporting one problem per census row for a
2928+
// single missing file.
29192929
const missing = retainedErrors(
29202930
[{ file: 'a.test.ts', verb: 'delete', pinned: 1 }, { file: 'b.test.ts', verb: 'update', pinned: 1 }],
29212931
{ entries: [] }, false, dcount([]), onDisk);

0 commit comments

Comments
 (0)