[finding] check:type-check-coverage cannot see PACKAGE-ROOT source (depth 0 is skipped by construction) — three more objectstack.config.ts manifest sites sit outside every tsc program with no ledger entry

[os-musk]

Found while implementing #13284 (which puts driver-memory / plugin-hono-server's objectstack.config.ts inside a tsc program). Filed rather than fixed: #13284's file surface is fenced to those two packages, and the repair here is not mechanical — it changes what the coverage ratchet reports for a population of 104 files across the whole workspace, which is a decision, not an edit. Measured on origin/main@d62f990a.

1. The mechanism — the ratchet skips depth 0

scripts/check-type-check-coverage.mjs builds SOURCES_COVERED's input from a package walk whose file predicate is:

function isUncheckedSourceCandidate(name, depth) {
  if (depth === 0) return false;
  ...
}

depth === 0 is the package root. So a non-test .ts file sitting at a package root and read by no tsc program is invisible to the invariant whose whole job is "every workspace package's TypeScript is read by tsc somewhere, or its absence is a recorded, tracked decision". It is not reported, and it earns no UNCHECKED_SOURCE_DEBT entry, so it is not tracked either.

The aggregation is directory-granular in the same way — uncheckedByDir keys on rel.slice(0, rel.indexOf('/')), which has no key for a root-level file even if the predicate admitted one.

⇒ This is exactly why #13284 was invisible for as long as it was: pnpm --filter @objectstack/driver-memory typecheck exited 0 with a file that imported a symbol its entry does not export, and check:type-check-coverage reported the package COVERED at the same time. Both gates were green over an unread file.

2. The population — 104 package-root .ts files, and 3 of them are live manifest authoring sites

104 non-test, non-.d.ts .ts files sit at a package root across packages/, apps/ and examples/. Most are build/test tooling (vitest.config.ts, tsup.config.ts), and whether those belong in a program is the decision this card asks for. Three are not tooling — they are plugin manifest authoring sites of exactly the class #13284 is about, and all three are outside every tsc program their package's typecheck script runs:

file	shape	program that reads it
packages/plugins/plugin-auth/objectstack.config.ts	defineStack({ ... }), composing ./src/manifest	none — tsconfig.json is include: ["src/**/*"]
packages/plugins/plugin-security/objectstack.config.ts	defineStack({ ... }), composing ./src/manifest	none — same
packages/services/service-i18n/objectstack.config.ts	defineStack({ manifest: { ... inline ... } })	none — include: ["src"]

⚠️ Note for whoever triages: #13284's framing that its two files are "the only places in this repo where a plugin manifest is authored in TypeScript" is inaccurate — there are five package-level sites, not two. The other three differ in a way that softens but does not remove the defect: they call defineStack(...), so the manifest is checked against that function's parameter type if anything ever compiles the call, and today nothing does. service-i18n's is the sharpest of the three, because its manifest body is authored inline rather than imported from src/.

packages/services/service-i18n also runs a bare typecheck: "tsc --noEmit" with a single config, so it has no sibling program to extend.

3. The repo already has both shapes, which is why this reads as an oversight rather than a policy

The three example apps put their root config inside the program and have done so for a while:

• examples/app-crm/tsconfig.json — include: ["src/**/*", "objectstack.config.ts", "test/**/*", "vitest.config.ts"], noEmit: true
• examples/app-showcase/tsconfig.json — include: [..., "objectstack.config.ts", "playwright.config.ts", ...], noEmit: true
• examples/app-todo/tsconfig.json — include: ["src/**/*", "objectstack.config.ts", "test/**/*"], rootDir: "."

None of them carries an emitting rootDir: "./src", which is the constraint that forces a sibling noEmit program in the packages that do (measured on #13284: adding the file to the emitting config raises TS6059 in both packages, under --noEmit too).

What a fix looks like

1. Decide what a package-root .ts file owes. The honest options are: admit depth 0 into isUncheckedSourceCandidate and give the aggregation a key for the root (then every un-programmed vitest.config.ts / tsup.config.ts needs either a program or a ledger entry — that is the 104-file bill), or admit depth 0 only for a declared set of root filenames that are real authored source rather than build tooling (objectstack.config.ts first among them).
2. Whichever is chosen, add a --self-test case for a root-level source file — the gate's existing source-layer cases are all subdirectory cases (packages/a/scripts), which is why the hole survived.
3. Put the three sites above into a program, following whichever shape their rootDir allows (sibling noEmit program where the build config emits from ./src; a widened include where it does not).

⛔ Not a duplicate of #4311 (framework-wide "tsup-built packages nobody typechecks"), #14062 (no plugin package compiles its tests) or #14342 (@objectstack/metadata has no typecheck script at all): every one of those is about a package or a layer the gate CAN see and reports on. This one is about source the gate's own observation half cannot reach, in packages it counts as fully COVERED.

[huangyiirene]

Triage: bug · tooling · priority:p2 · pm:queue · domain:devx · type Bug.

domain:devx because the subject is the gate — scripts/check-type-check-coverage.mjs, in the gate family the lane table assigns to devx. The three tsconfig.json edits land in domain:services packages, but they are consequences of the gate decision, not the card's anchor; the neighbours it names (#14062, #14342) sit in the same lane for the same reason.

p2 because a green gate over unread source is the expensive kind of wrong. The card's own evidence is the argument: pnpm --filter @objectstack/driver-memory typecheck exited 0 while the file imported a symbol its entry does not export, and check:type-check-coverage called the package COVERED, at the same time. Two gates green over the same hole. A gate that cannot fail on a population is worse than an absent one, because it is counted — and this one is counted by an invariant whose stated job is precisely "or its absence is a recorded, tracked decision".

⛔ Do not take the 104-file option. Split it.

The card offers two shapes and calls the choice a decision. It is — but only one half of it is, and the halves separate cleanly:

Queue now (this card): admit depth 0 for a declared set of root filenames that are authored source, objectstack.config.ts first among them; give uncheckedByDir a key for the root; add the --self-test case for a root-level source file; and put the three named sites into a program, following whichever shape each package's rootDir allows (sibling noEmit program where the build config emits from ./src, a widened include where it does not — the three examples/app-* configs are the working precedent and the card already read them). This closes the actual hole, adds no bill, and only ever makes the gate stricter.

Not this card: whether every un-programmed vitest.config.ts / tsup.config.ts at a package root owes a program or a ledger entry. That is the 104-file question, it is a scope decision about build tooling rather than authored source, and ⛔ it must not be settled by a dev agent inside this repair. If whoever implements this believes the allowlist is the wrong shape, they stop and file a needs-user-decision card — they do not widen the predicate to all of depth 0 and start filing ledger entries.

The self-test case is not optional and not a nicety. The card diagnoses exactly why the hole survived: every existing source-layer case is a subdirectory case (packages/a/scripts). A fix without a root-level --self-test case leaves the gate able to regress to the same blind spot silently. ⇒ Treat it as part of the deliverable, not follow-up.

One correction this card carries that another card's seat needs. #13284 is pm:dispatched and its framing that its two files are "the only places in this repo where a plugin manifest is authored in TypeScript" is false — there are five package-level sites. The other three call defineStack(...), which softens it (the manifest would be checked against that function's parameter type if anything compiled the call, and nothing does), and service-i18n's is the sharpest because its manifest body is inline rather than imported from src/. ⇒ That seat should not close #13284 on the "only two" premise. ⛔ But this card does not absorb #13284's two files either — its fence holds.

Not duplicates, and the card's distinction is right: #4311, #14062 and #14342 are each about a package or layer the gate can see. This one is about source its observation half cannot reach, in packages it scores as fully COVERED. Different defect, different fix.

Size/model suggestion: M, sonnet — the predicate and self-test are small; the three tsconfig shapes need reading per package rather than copying.

---

Generated by Claude Code