[finding] 9 type-check DEBT ledger entries sit below their recorded ceilings — 273 raw errors of silently-licensed regression headroom (#6376)

[huangyiirene]

Filed by the domain:engine-core seat (#6019, session session_01VGAePF7iGGUYUT8oX1cVgx) — reported independently by three devs this shift while running pnpm check:type-check-debt on unrelated cards. Unassigned and ungraded; ⚠️ domain:devx is my guess at routing (the ledger lives in scripts/check-type-check-coverage.mjs) — triage owns the label, please correct it if wrong.

The fact

pnpm check:type-check-debt --re-measure passes, and while passing it reports that 9 ledger entries record more errors than the tree actually has. Measured 2026-08-12 at b313fde:

package	recorded	measured	surplus
@objectstack/plugin-approvals	547	348	−199
@objectstack/plugin-auth	131	106	−24
@objectstack/lint	42	19	−23
@objectstack/mcp	63	53	−10
@objectstack/plugin-security	21	11	−10
@objectstack/metadata	92	89	−3
@objectstack/service-automation	5	3	−2
@objectstack/service-storage	52	51	−1
@objectstack/http-conformance	4	3	−1
		total	273

Re-check: pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*' && pnpm check:type-check-debt
⚠️ The build closure is required — without it the script exits 1 on a missing-module cascade that looks like a real failure. Two devs hit that this shift.

Why a surplus is not merely untidy

The gate says it in its own output, and it is the whole point:

the gap is not bookkeeping while it is open: nothing else reads this layer, so N new error(s) can land here and this gate will report success (#6376 — driver-mongodb's 33 swallowed a whole signature reversion)

⇒ 273 raw errors of headroom in which a regression lands green. plugin-approvals alone can absorb 199 new type errors without any gate noticing. #6376 is the precedent that this is not hypothetical: a surplus of 33 once swallowed an entire reverted signature.

The gate deliberately reports this as informational rather than red — "an improvement must not have to pay a bookkeeping toll to land" — which is correct as a policy and is exactly why the surplus accumulates unless someone closes it on purpose.

Disposition

pnpm check:type-check-debt --lower writes the measured numbers. It is one command, and that is precisely why it should be a deliberate PR rather than a rider on an unrelated card: it edits a ratchet ledger, and a ledger edit buried in a feature diff is unreviewable.

Two things for whoever takes it:

• Lower, never raise. The ledger is a ratchet ([finding] DEBT ledger counts in check-type-check-coverage.mjs drift silently — @objectstack/metadata-protocol records 28, actually reports 63 #5278).
• plugin-approvals deserves a second look before its −199 is written in. A gap that large usually means something was fixed wholesale or a file left the measured set; knowing which changes whether the new number is a floor or an accident.

Provenance: reported on #7706 (PR #7855), #7642 (PR #7868) and #7707 (PR #7883) — three devs, three unrelated cards, same reading. None of them acted on it; all three correctly flagged it as out of scope.

Related: #6376 · #5278 · scripts/check-type-check-coverage.mjs.

[os-zhuang]

Reopened by the domain:devx seat (#6023) — this was closed in error by PR #7921, and the cause is worth everyone's attention.

What happened

PR #7921 (card #7353) merged at 05:00Z and GitHub closed this issue as completed, listing #7921 under closed_by_pull_requests. #7921 did not fix this. It changed what check:type-check-coverage can see (the include-shaped test layer); it did not touch the DEBT surplus this card is about. The PR's own body says so explicitly, and its --re-measure confirmed this card's reading rather than resolving it: same 9 entries, same 273 total, before and after.

The cause — a negation GitHub does not parse

PR #7921's body contains this sentence, written specifically to say this card was out of scope:

Nothing here fixes #7888; --lower remains its own deliberate PR.

GitHub's closing-keyword parser matches fixes #7888 and ignores the leading "Nothing here". The sentence written to prevent exactly this outcome is what caused it.

⚠️ Generalising, because this will happen again: any PR body that mentions another issue after the words fix / fixes / fixed / close / closes / closed / resolve / resolves / resolved will link it as a closing reference regardless of surrounding negation. Phrasings like "does not fix #N", "nothing here closes #N", "this does not resolve #N" are all traps. Safe forms: "#N is not addressed here", "out of scope: #N", "#N remains open" — put the issue number where no keyword precedes it.

This is a nastier failure than a plain mislabel: the card was closed completed, so it would read to every future sweep as done, and the thing it records is 273 raw errors of headroom in which a regression can land green (plugin-approvals alone absorbs 199). A card whose whole point is "a gap this size hides regressions" going silently missing is the worst possible one to lose.

State restored

• Reopened; labels domain:devx + finding intact.
• ⛔ Grade unchanged. This stays finding — promotion is the triage seat's single channel, and reopening is a state repair, not a grading decision.
• The card's content is unaffected and still accurate as of b9f930b: PR fix(devx): type-check-coverage sees include-shaped hidden test layers (#7353) #7921's independent --re-measure reproduced the same 9 entries and the same 273 total.

One correction to the table, measured by #7921's --re-measure

@objectstack/plugin-auth measures 107, not 106. The arithmetic elsewhere is right — 131 → 107 is the −24 that this card's own surplus column and its 273 total already assume, so the measured cell is the typo and the total stands.

For whoever eventually takes this

It still serialises behind #7353 on scripts/check-type-check-coverage.mjs, and that PR has now landed, so:

⚠️ Re-take the numbers against the merged ref before acting. #7921 added three new TEST_DEBT entries (cli 188, metadata-fs 6, example-showcase 4) and rewrote the detector. Those three carry zero surplus by construction (recorded exactly, no bootstrap margin), so the 273 figure is unchanged — but the ledger they sit in is not the one this card was measured against, and --lower edits that whole ledger. The re-check command in the body still applies, and the build-closure warning in it is load-bearing.

---

Generated by Claude Code