fix(devx): read the ledger note against its own field, and stop --lower minting the drift

[claude]

Fixes#10722

What was wrong

scripts/check-type-check-coverage.mjs freezes two ledgers whose entries pair a measured errors: with a free-prose note:. The ratchet compares errors against tsc and never reads the prose, so a note could narrate any count at all — including one its own field contradicts — with every gate green. Four hand repairs of that one shape are on record (#7038, #8982, #10721, #10775), the last two on the same day.

None of them closed the class, because --lower mints it. Its capture group ends at the digits, so the sanctioned one-command way to close a surplus is also the way to desynchronise a note.

Reproduced, not quoted. Driving the baselowerLedgerEntries() over the real @objectstack/metadata entry with a synthetic 89 → 80 measurement:

applied: [ 'DEBT @objectstack/metadata: 89 -> 80' ] skipped: []
'@objectstack/metadata': {
errors: 80,
note: 'code-tier 30 (TS2345 x30); config-tier 25 (TS2835 x25); noise 34 (TS7006 x33, TS6133). '

One command, a fresh instance of the class, no gate anywhere the wiser.

What lands, and why both halves together

Neither half is safe alone, and the order is the whole argument:

• check without the tool fix → the next --lower run leaves the ledger red, in whoever's PR ran the tool, and the operator has to hand-edit prose to get green. That breaks the "closing an entry is FREE" invariant [finding] DEBT ledger counts in check-type-check-coverage.mjs drift silently — @objectstack/metadata-protocol records 28, actually reports 63 #5278/[finding][devx] check:type-check-debt 的 ledger 余量会让新写的 pin 变哑：mongodb 曾有 33 条余量吞掉一次真实回退，另有 5 条目前带 4–19 余量 #6376 paid for.
• tool fix without the check → today's instances stay undetected.
• together, with the tool producing what the check accepts → the advertised path stays one command, and the drift becomes a declared fact instead of a silent one.

1. COMPOSITION — the check

Reads exactly one thing: the house-convention tier itemisation the notes already open with (code-tier N; config-tier N; noise N, either word order). It abstains, silently, everywhere else:

• the itemisation must be the note's opening clause, reachable across a lead-in carrying no digit and no sentence break (spec-monorepo's "the workspace root itself: code-tier 4 …" qualifies);
• a tier counted twice, or a further code-tier 9-shaped count anywhere later in the note, means the note quotes its own history → skipped, no verdict. metadata-protocol quotes the misleading note [finding] DEBT ledger counts in check-type-check-coverage.mjs drift silently — @objectstack/metadata-protocol records 28, actually reports 63 #5278 found and is skipped for exactly that reason;
• per-code tallies are NOT summed, contrary to the issue's item 2. They are partial by construction: plugin-rest's tally sums to 147 and says so in the same breath ("composition as counted at 153"). Summing them would red an entry whose author was being precise.

False-positive direction: an entry whose opening itemisation is deliberately partial, with the remainder described in words rather than digits, would fire wrongly. None exists.
False-negative direction: everything else, and it is most of the ledger — 21 of 33 entries carry no tier itemisation at all. That is the intended trade: a floor under one known class, not a reader of prose.

2. --lower stops minting it

plannedLowerings() now computes declareCompositionAt — the size the itemisation was tallied at — where it is pure and fixture-testable; lowerLedgerEntries() writes it as a sibling field beside the number the regex already locates. No prose surgery (the docblock's own warning against parsing this file's prose still stands), no invented composition (the tool knows the new total and nothing about which tier gave it up).

The same lowering, after:

planned: [{"ledger":"DEBT","name":"@objectstack/metadata","from":89,"to":80,"declareCompositionAt":89}]
'@objectstack/metadata': {
errors: 80,
compositionAt: 89,
note: 'code-tier 30 (TS2345 x30); config-tier 25 (TS2835 x25); noise 34 (TS7006 x33, TS6133). '
--- COMPOSITION read back over the rewritten ledger ---
clean: 0 problem(s)

compositionAt may only ever declare a pile LARGER than the field, so it cannot launder a raise; equal-to-errors is refused too, so the field only ever shrinks away. Declared-stale entries are named in the gate's green summary, for the reason the surplus is (#6376): a declaration nobody can see is the half that does the damage.

3. The :167-173 rule now covers downward drift

It only ever said "raise", on the reasoning that a note describing a larger pile "misleads in the safe direction". @objectstack/metadata drifted down (92 → 89), and a note itemising 34 + 24 + 34 over a field reading 89 does not mislead safely — it contradicts its own field. The paragraph now says so, names both same-day repairs, and points at the mechanical half in each place.

Evidence

Union re-run at f4d00e4e7d (the final commit), exit codes captured before any pipe:

gate	exit
pnpm check:type-check-coverage	0
pnpm check:cross-package-test-inputs	0
node scripts/check-cross-package-test-inputs.mjs	0
pnpm check:entry-guard (by hand — dispatch-gates is blind to it, #10784/#10705)	0
node scripts/check-parse-guard.mjs (by hand, same reason)	0
pnpm check:nul-bytes	0
pnpm check:ratchet-remedy-authority (this file is in its CONTROL corpus)	0
pnpm exec eslint scripts/check-type-check-coverage.mjs	0

node scripts/pm/dispatch-gates.mjs (no paths, derives its own change set) → exit 0, 4 families, all run above.

Self-test:✓ 34 semantic case(s) + 24 observation + 25 re-measure + 28 built-closure + 19 auto-lowering case(s) hold — 11 new COMPOSITION fixtures (the two real instances transplanted, the ambiguity guard, and every compositionAt reconciliation branch), 4 new plan cases, 4 new rewrite cases, and 2 round-trip cases that lower the fixture and read the result back through the check.

Corpus check, shipped implementation over every DEBT + TEST_DEBT entry:

tree	entries	checked	ambiguous	no itemisation	fire
this branch / main	33	11	1	21	0
699132f259^ (before the #10721 repair)	33	11	1	21	2 — service-automation (code-tier 5 over errors: 3) and metadata (34+24+34 = 92 over errors: 89)
699132f259 (before the #10775 repair)	33	11	1	21	1 — metadata

Both known instances, on the trees that carried them. Nothing else, on any of the three.

Ablation. Mutated tierItemisation() to if (typeof note !== 'string' || true) return null; so the rule can never fire. Confirmed on disk by anchor count, not by an editor's exit code — injected anchor 1, original anchor 0. Predicted 10 self-test failures (7 semantic, 1 plan, 2 round-trip, 0 rewrite — the rewrite cases pass the declaration explicitly). Observed 10, and the failing labels were exactly the predicted set. Restored and verified byte-identical (sha256sum -c → OK). No build is involved: this is a plain .mjs run directly by node, with no dist/ between the edit and the run.

Declared narrowing

pnpm check:type-check-debt refuses without a built workspace closure (--re-measure cannot run: 55 workspace dependenc(ies) … have no built type entry point on disk), as expected. Its structural half — which is where COMPOSITION runs — executed green before the refusal. No ledger number can move from this diff: it adds no TypeScript, and every errors: value in both ledgers is byte-identical to origin/main.

Out of scope

No changeset: gate tooling publishes nothing. skip-changeset applied additively.

Generated by Claude Code

---

Generated by Claude Code