docs(ratchet): describe the equivalence proof that actually happened

[os-steve]

Fixes #1345

Comment text only. No executable line changed anywhere; the whole diff is prose inside one gate's header docstring, plus an empty-frontmatter changeset.

The claim, re-measured

scripts/check-source-token-ratchet.mjs's stripping-rule paragraph said the rule is

pinned by test/source-token-ratchet.test.ts — which cross-checks this scanner against the TypeScript compiler's own comment-trivia ranges over every real file in src/. TypeScript is a devDependency and stays a test-time dependency on purpose

No such cross-check exists. Re-measured on origin/main @ c772cbe (the card was filed against 08613ad; all three readings reproduce):

executable `typescript` imports under test/ or scripts/  : 0
createScanner / getLeadingCommentRanges anywhere         : 0
control — typescript IS declared                         : package.json:65  "typescript": "^7.0.2"

⚠️ The measurement has a trap worth recording, because anyone re-running it hits it. A plain grep of test/ and scripts/ for from 'typescript' returns 1 hit, not 0:

test/source-token-ratchet.test.ts:55: * package exposes no compiler API — `import ts from 'typescript'` yields

The * prefix is the tell — it is docstring prose discussing an import, not an import. That file's real imports are lines 3-9 and contain no typescript. The hit does not falsify the card; it is the same shape this defect family is about, a pattern that reaches the code and answers a different question.

Why the false claim was unusually durable

typescript really is a declared devDependency — it is tsc --noEmit's. So a reader checking the sentence the cheap way ("is typescript a dep? yes") had it confirmed while the wiring was absent, and anyone wanting to know whether the stripper is validated against a real compiler found the claim already made and stopped looking.

What is true, and where the record lives

Per the ruling on the card: describe the equivalence proof that actually happened and point at the record — do not build the cross-check, do not add esbuild. Neither was done; pnpm-lock.yaml is untouched and pnpm install reports "Lockfile is up to date".

The record is test/source-token-ratchet.test.ts:52-71, under the heading "The stripper's equivalence proof is a hand run, recorded here". Verbatim:

stripComments() is a hand-written character scanner (TypeScript 7's npm package exposes no compiler API — import ts from 'typescript' yields { version, versionMajorMinor } and nothing else — so there is no scanner to borrow). Its correctness over the whole real tree was proved by hand with esbuild, which the ObjectStack CLI already builds with:

for every first-party .ts file f (src, test, e2e, scripts — 286 files):
  esbuild.transform(f, { loader: 'ts', minify: true }).code
    === esbuild.transform(stripComments(f), { loader: 'ts', minify: true }).code

  -> 286 files, 0 divergent, 0 line-count drifts, 1,495,852 chars removed

Byte-identical minified output means the strip removed comments and nothing else — no string, regex or code byte moved. That run is in the PR body. It is not automated here because esbuild is not a declared dependency of this repo (it arrives under the ObjectStack CLI), and a test that fails when an undeclared package is laid out differently would be reporting on pnpm, not on this gate.

⇒ The card's falsifiable premise holds. No fork.

Acceptance, end to end

The new prose names the file and quotes the heading on a single unbroken line, so the pointer is greppable rather than merely readable — an earlier draft wrapped the heading across a comment line break, which would have made it un-greppable. Following it resolves:

$ grep -n "The stripper's equivalence proof is a hand run, recorded here" test/source-token-ratchet.test.ts
52: * ## The stripper's equivalence proof is a hand run, recorded here

The paragraph also re-attributes the devDependency to tsc --noEmit, and keeps the two true facts the old sentence carried: the gate imports nothing outside node: builtins and scripts/lib/main-module.mjs, so it runs with nothing installed and its number cannot move because a compiler upgraded.

One precision note: the replacement says the suite asserts the rule "against fixtures for the hazard classes it covers", borrowing the suite docstring's own wording. A first draft said "one fixture per hazard class", which implies a 1:1 mapping the suite does not have — three fixture tests cover the five clauses. On a card about an overclaiming sentence that distinction is the point.

Scope held

⛔ Unchanged, as ruled: the stripping rule, every ceiling, BUFFER, the suite, and the typescript devDependency.

Verification

pnpm verify green on 9cf5666 — the final commit of this branch, and the exact tree verify ran against (working tree clean throughout). Each stage's own verdict line:

✓ Validation passed (4140ms)                 # pnpm validate
tsc --noEmit                                 # pnpm typecheck — no diagnostics
                                             # pnpm lint — no error
✓ i18n lint gate: 0 `i18n/missing-*` issues  # pnpm lint:i18n-gate
✓ source hygiene clean                       # pnpm hygiene
✓ source token ratchet clean                 # pnpm hygiene:tokens
✓ Build complete (1872ms)                    # pnpm build
Test Files  147 passed (147)                 # pnpm test
     Tests  3061 passed | 1 skipped (3062)

The ratchet's own numbers are unmoved and cannot move: the measured surface is src/** only, and it is comment-stripped besides — scripts/ is not measured at all.

Targeted first, before the full run: the three suites that read this gate's source — source-token-ratchet, docs-readme-token-figures, script-main-guard — 39 tests, all passing.

Changeset

.changeset/ratchet-header-equivalence-proof.md, empty frontmatter, which changeset-check.yml documents as the sanctioned "this PR releases nothing" declaration. Verified true of this diff rather than assumed: every added and removed line in scripts/check-source-token-ratchet.mjs is a comment line (non-comment count = 0), and nothing under src/ changed. No skip-changeset label is needed or applied.

Found on the way, not fixed here

Filed as #1370: the run-when-main comment at scripts/check-source-token-ratchet.mjs:527-530 carries a second copy of this same claim ("cross-check the stripping rule against the TypeScript scanner"), and separately names stripComments and verdict as exported for a suite that imports neither. It sits outside this card's declared paragraph, and its correction is a choice rather than a mechanical edit — so it is reported, not ridden along, on the precedent this card set. #1344 remains open and is disjoint (the header table figures).

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 27, 2026 2:30pm