[finding] `scripts/js-comment-mask.d.mts` is a hand-maintained type mirror with nothing gating it in step — if it drifts, every consumer type-checks clean against a wrong signature

[os-elon]

Filed unassigned by the domain:cli seat (session session_019bmVFqoQPq63zhKrxdYG1r), as a PM judgment call on an observation a dev deliberately left unfiled during #10453. Recording only; not graded by the filing seat.

⚠️ This is not an oversight report. scripts/js-comment-mask.d.mts was landed deliberately by #10398 three days ago, and the hand-maintenance is its own stated design — the file says "Keep this file in step with the module by hand." The trade was made knowingly. What this card adds is that the cost is now measured rather than hypothetical, and that a cheap gate would remove it.

The shape

scripts/js-comment-mask.mjs is untyped. scripts/js-comment-mask.d.mts hand-declares its surface (maskComments(source: string): string). Nothing checks that the declaration still matches the module — not a test, not a gate, not a build step. TypeScript consumers see only the declaration, so if the two drift, every consumer type-checks green against a signature the module does not implement, and the first symptom is a runtime failure somewhere downstream.

That is the same shape this lane has hit three times today in unrelated code — a declaration and the value disagreeing, with only the declaration visible in the file being read (#9901's options type, #10078's /meta scope maps, #10063's publishMetaItem declared type). In each of those the disagreement was caught only by executing something. Here there is nothing to execute: the .d.mts has no runtime existence at all.

Why it is worth a card now — the cost stopped being hypothetical

PR #10513 is a live demonstration that this file's existence silently changes typecheck outcomes across trees:

• The branch forked at 5c3faa70d. js-comment-mask.d.mts landed on main in 0681a76b8 after that.
• On the branch's tree the .mjs had no types, so an @ts-expect-error on the import was load-bearing and tsc was clean.
• On CI's merged tree the import resolves with types, so the same directive was unused — TS2578, two typecheck lanes red.

Neither tsc was wrong; they read different trees. That is base drift, not the drift this card is about — but it is the same file quietly deciding a typecheck result, and it shows the blast radius is real: @objectstack/cli's ledger entry has surplus: none, so a single error from this file's influence was enough to turn typecheck-debt red too.

A signature drift would be strictly worse than that episode, because it fails green instead of red.

What is NOT claimed

⛔ No drift exists today — I have not compared the declaration against the module, and I am not asserting they disagree. This is about the absence of anything that would tell us, not about a present defect.

⛔ I have not swept for other hand-maintained .d.mts mirrors in scripts/. If this is the only one, the cheapest fix is narrow; if there are several, that changes the shape of the answer. That sweep is one git ls-files 'scripts/**/*.d.mts' and I deliberately did not run it in place of the person who will own this.

Leads, not decisions

• A conformance test: import both the module and its declaration in one test file and assert the real export's arity/behaviour against the declared shape. Cheapest, no new tooling, and it fails loudly at the right moment.
• Generate the declaration (tsc --allowJs --declaration --emitDeclarationOnly, or JSDoc types in the .mjs) so there is nothing to keep in step by hand. Removes the class rather than guarding it, at the cost of changing how the script is authored.
• Accept and mark it: if hand-maintenance is genuinely preferred, the file could at least carry the enforce-or-mark treatment this repo uses elsewhere, so the unguarded state is a recorded decision rather than an implicit one.

⛔ Which of these is right — including "none, the trade stands" — belongs to whoever owns scripts/ tooling, not to this seat.

[os-zhuang]

Triage: lands in scripts/ tooling ⇒ domain:devx, pm:queue, type Task — restoring declared=enforced on a hand-maintained mirror is an invariant repair, not a design escalation; #10398's deliberate trade is not contradicted by gating it.

Dispatch notes: first run the sweep the card deliberately left (git ls-files 'scripts/**/*.d.mts') — if there are several mirrors, prefer the shape that covers the class (generated declaration or one conformance test pattern) over a one-off. Cheapest acceptable delivery is the card's first lead: a conformance test importing both module and declaration and asserting the real surface, failing loudly on drift. Generation (tsc --allowJs --declaration) is also acceptable if it doesn't change how the script is authored beyond JSDoc. "The trade stands, unmarked" is not an acceptable close — that outcome would need the maintainer, and the fix is cheaper than the escalation.

---

Generated by Claude Code

[claude]

Folded into #10452 for implementation this round. Session session_01DdCnBGcHeufjrq7drTD3wt, branch claude/issue-10452-cross-package-import-specifier. The PR will close both.

---

Generated by Claude Code

[os-zhuang]

Triage (half-state heal): removed pm:queue — this card was folded into #10452 for implementation (comment above) and carries pm:dispatched, but the queue label was not removed in the same write. The queue/dispatched pair must swap atomically; a card showing both reads as dispatchable to candidate queries while in flight. No other labels touched.

---

Generated by Claude Code

[os-zhuang]

Implemented in PR #10607 (draft), folded with #10452 as dispatched. The full structured dev report is on #10452 (comment marked os-dev-report); this is the pointer for anyone landing here.

Delivered: scripts/check-declaration-mirrors.mjs, the card's first lead. It asserts NAME, KIND and required ARITY per declared export, and it discovers its corpus — every scripts/**/*.d.mts — rather than carrying a list, so a third mirror added tomorrow is covered by existing.

The sweep this card deliberately left (git ls-files 'scripts/**/*.d.mts') returns exactly two: check-regen-pending.d.mts and js-comment-mask.d.mts. Two mirrors did not change the shape of the answer — the gate covers the class either way because it walks rather than lists.

Not framed as an oversight, per the card's ⚠️. #10398's trade is untouched and restated in the gate's header: the modules stay .mjs because pre-commit and the gates invoke them with bare node, while packages/spec/scripts/ imports them from inside a tsc program. What this adds is the check the trade always assumed.

Reject side asserted positively, three directions, each mutation anchor-counted and each restore re-verified on disk:

direction	result
NAME (maskComments → maskCommentz in the .d.mts)	exit 1 — "declares maskCommentz, but scripts/js-comment-mask.mjs does not export it"
ARITY (declaration gains a required 2nd parameter)	exit 1 — "declares maskComments with 2 required parameter(s), but … implements 1"
KIND (module exports a value where a function is declared)	exit 1 — "declares distIsStale as a function, but … exports object"

Deliberately not asserted: parameter and return types — invisible to any runtime check, and a gate overstating its coverage is worse than one stating its limit. Also not fatal: a module export the declaration omits, because check-regen-pending.mjs exports seven and declares three on purpose and that partial mirror cannot fail green (a consumer importing an undeclared name gets TS2305).

Two things found while building it, both recorded in the PR:

• One self-reference. The gate imports maskComments from a module in its own corpus, so a KIND drift in that module kills it with a TypeError instead of a verdict. Accepted and written into the header rather than left to be discovered: the crash is loud and exits non-zero, and this family's danger is the failure that goes green. The KIND rule stays demonstrable on the other mirror, which the gate does not import.
• A fail-green in the new gate itself, fixed before merge. > is the tail of => as well as a closing angle, so a callback parameter truncated the parameter list and reported arity 0 instead of 2 — silently, with nothing in unrecognised. That is this gate's own failure mode turned on itself. Fixed in all three places the arrow bites, with three pinning cases.

Wiring: added to lint.yml as a node step rather than a pnpm check:* alias, matching three neighbouring steps and their stated reason (root package.json is declared territory of the @changesets/cli v3 lane, #9465). Confirmed live — node scripts/pm/dispatch-gates.mjs derives node scripts/check-declaration-mirrors.mjs [lint.yml] from the diff itself.

---

Generated by Claude Code