objectstack-ai · claude · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026
diff --git a/packages/cli/src/commands/validate-json-strict-exit.e2e.test.ts b/packages/cli/src/commands/validate-json-strict-exit.e2e.test.ts
@@ -86,12 +86,20 @@
  * ## Why this file is not beside its siblings in `packages/cli/test/`
  *
  * That directory was held by another in-flight card while this one was written,
- * so it was read-only to this change. `src/` turns out to be the stronger of the
- * two homes anyway, and deliberately so for the same reason
- * `utils/format.exit-code.test.ts` gives for living here: `packages/cli/
- * tsconfig.json` includes `src`, so `pnpm typecheck` compiles this file, while
- * no tsc program reads `packages/cli/test/`. `tsconfig.build.json` excludes
- * `src/**\/*.test.ts`, so nothing here ships.
+ * so it was read-only to this change. `src/` is still the home, for the reason
+ * `utils/format.exit-code.test.ts` gives: `packages/cli/tsconfig.json` includes
+ * `src` and excludes nothing, so `pnpm typecheck`'s first leg (`tsc --noEmit`)
+ * compiles this file. `tsconfig.build.json` excludes `src/**\/*.test.ts`, so
+ * nothing here ships.
+ *
+ * ⚠ The second half of that sentence — that no tsc program reads
+ * `packages/cli/test/` — is FALSE on this tree, and is corrected here rather
+ * than dropped because it is the half that would be copied. `typecheck` is
+ * `tsc --noEmit && pnpm check:test-typecheck`, and the second half runs
+ * `--project tsconfig.test.json`, whose `include` names `test/**\/*`: 181
+ * files under that directory are in that program, measured with
+ * `tsc --listFiles`. Neither home is a phantom; they differ only in which leg
+ * of `typecheck` reads them.
  */
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';

diff --git a/packages/cli/src/utils/format.exit-code.test.ts b/packages/cli/src/utils/format.exit-code.test.ts
@@ -21,10 +21,20 @@
  *     every scripted caller.
  *
  * (2) lives in `src/` deliberately: `packages/cli/tsconfig.json` includes
- * `src`, so `pnpm typecheck` compiles this file and its `@ts-expect-error`
- * directives are real. The same test under `packages/cli/test/` would be a
- * phantom check — no tsc program reads that directory, so every directive in
- * it would evaluate never and deleting them would leave every gate green.
+ * `src` and carries no `exclude` at all, so `pnpm typecheck`'s first leg
+ * (`tsc --noEmit`) compiles this file and its `@ts-expect-error` directives
+ * are real (measured with `tsc --listFiles`).
+ *
+ * ⚠ The contrast this used to draw is FALSE on this tree and is corrected
+ * rather than deleted, because the wrong half is the half a reader copies: the
+ * same test under `packages/cli/test/` would NOT be a phantom check. This
+ * package's `typecheck` is `tsc --noEmit && pnpm check:test-typecheck`, whose
+ * second half runs `--project tsconfig.test.json`, and that config's `include`
+ * names `test/**\/*` — 181 files under `packages/cli/test/` are in that
+ * program, measured with `tsc --listFiles`. Directives in either home are
+ * evaluated. What still separates the two is WHICH leg reads them: `src/`
+ * lands in the unconditional `tsc --noEmit`, `test/` in the test-layer program
+ * whose per-file residue `packages/cli/test-typecheck-debt.json` ratchets.
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';

diff --git a/packages/drivers/driver-memory/src/memory-driver-query-narrowing.test.ts b/packages/drivers/driver-memory/src/memory-driver-query-narrowing.test.ts
@@ -19,11 +19,18 @@
  * here only because this package's `tsconfig.json` does NOT exclude the
  * test-file glob — it has no `TEST_DEBT` entry in
  * `scripts/check-type-check-coverage.mjs` and reports zero errors, which is the
- * measurable baseline these pins move away from. The sibling `driver-mongodb`
- * package DOES exclude its tests, so the identical pin written there would be
- * the phantom check AGENTS.md's `PINS_CHECKED` invariant warns about — it is
- * deliberately not written; mongodb's narrowing is held by `tsc` over its
- * source plus the repo-wide `check:type-check-debt` re-measure.
+ * measurable baseline these pins move away from.
+ *
+ * ⚠ The sentence about the sibling is corrected, not deleted, because the
+ * wrong version is the one a reader carries to that package. `driver-mongodb`'s
+ * BUILD config does still exclude its tests, but the identical pin written
+ * there would NOT be a phantom check: its `typecheck` is
+ * `tsc --noEmit && pnpm check:test-typecheck`, whose second leg runs
+ * `--project tsconfig.test.json`, and that config's `include` is `src/**\/*`
+ * with no test exclusion — 30 of its `src` test files are in that program,
+ * measured with `tsc --listFiles` (0 in its build program, the firing control).
+ * What differs between the two packages is now only WHICH leg of `typecheck`
+ * resolves the directive, not whether anything does.
  *
  * The `expect()` calls only give the assertions a home vitest will run.
  */

diff --git a/packages/lint/src/runtime-gate.derived-context-keys.test.ts b/packages/lint/src/runtime-gate.derived-context-keys.test.ts
@@ -11,11 +11,20 @@
  * `{ [K in keyof RuntimeStackContext]-?: true }`, so a collection added to the
  * interface without a row is a type error naming that collection, in
  * `runtime-gate.ts`, at `tsc --noEmit` and at the DTS build. ⛔ It is
- * deliberately NOT restated here as a runtime assertion: this package's
- * `tsconfig.json` excludes `**\/*.test.ts`, so no tsc program compiles this
- * file and a type-level witness written here would evaluate never — a phantom
- * check that deletes clean. The guard's own failure was measured instead, on
- * the card, by adding a collection and reading the build.
+ * deliberately NOT restated here as a runtime assertion — ⛔ but NOT because
+ * nothing compiles this file. This package's `typecheck` is
+ * `tsc --noEmit && pnpm check:test-typecheck`, and that second half runs
+ * `--project tsconfig.test.json`, a config whose `include` is `src/**\/*` with
+ * no test exclusion. So this file IS in a tsc program the `typecheck` script
+ * runs, and a type-level witness written here would be LIVE. Measured with
+ * `tsc --listFiles`: 103 of this package's `src` test files are in that
+ * program and 0 are in the build program, which is where the old sentence came
+ * from — `tsconfig.json` does still exclude `**\/*.test.ts`, and that stopped
+ * being the whole story when the test layer got its own program. The witness
+ * is left out on its own merit: the compiler already holds completeness at the
+ * declaration site named above, so restating it here would be a second COPY of
+ * one invariant rather than a second CHECK of it. The guard's own failure was
+ * measured instead, on the card, by adding a collection and reading the build.
  *
  * ORDER is what a test can hold, and the derivation had to be chosen so as not
  * to break it — a mapped type does not guarantee declaration order. The order

diff --git a/packages/objectql/src/datasource-def-credentials-ref.pin.ts b/packages/objectql/src/datasource-def-credentials-ref.pin.ts
@@ -21,12 +21,23 @@
  * A runtime test therefore cannot cover this card: the runtime never changed.
  * The accepted set of a public method did, and only `tsc` can see that.
  *
- * WHY A `.pin.ts` AND NOT A `*.test.ts`: `packages/objectql/tsconfig.json`
- * excludes `**\/*.test.ts`, so a `@ts-expect-error` written in a test file here
- * is a phantom check — no tsc program the `typecheck` script runs would ever
- * evaluate it, and deleting the directive would leave every gate green. This
- * file IS in that program. Same convention, and same reasoning, as
- * `register-object-authored-shape.pin.ts`. It carries no executable pin: the
+ * WHY A `.pin.ts` AND NOT A `*.test.ts`, stated to today's tree: a `.pin.ts`
+ * is not a test file, so `packages/objectql/tsconfig.json`'s exclusion of
+ * `**\/*.test.ts` does not reach it and `typecheck`'s unconditional first leg
+ * (`tsc --noEmit`) compiles it. Same convention, and same reasoning, as
+ * `register-object-authored-shape.pin.ts`.
+ *
+ * ⚠ It is NOT that a directive in a `*.test.ts` here would go unevaluated —
+ * this docblock used to say so, and that is FALSE on this tree. This package's
+ * `typecheck` is `tsc --noEmit && tsc --noEmit -p tsconfig.scripts.json &&
+ * pnpm check:test-typecheck`, and the last leg runs
+ * `--project tsconfig.test.json`, whose `include` is `src/**\/*` with no test
+ * exclusion: 299 of this package's `src` test files are in that program,
+ * measured with `tsc --listFiles` (0 in the build program — the firing control
+ * for the exclusion, and where the old sentence came from). The correction is
+ * kept rather than the sentence deleted, because the wrong version is the one
+ * a sibling file copies.
+ * It carries no executable pin: the
  * assertions live in a function nobody calls, and the companion
  * `datasource-def-credentials-ref.test.ts` covers the runtime half.
  */

diff --git a/packages/objectql/src/datasource-def-credentials-ref.test.ts b/packages/objectql/src/datasource-def-credentials-ref.test.ts
@@ -3,9 +3,17 @@
 /**
  * #12758 — runtime half of the datasource-definition credentials-reference
  * contract. The compile-time half is in
- * `datasource-def-credentials-ref.pin.ts` (it has to be: this file is excluded
- * from every tsc program the `typecheck` script runs, so a `@ts-expect-error`
- * written here would never be evaluated).
+ * `datasource-def-credentials-ref.pin.ts`, which is where the `.pin.ts`
+ * convention puts it.
+ *
+ * ⚠ NOT because nothing compiles this file. That parenthesis used to read
+ * "this file is excluded from every tsc program the `typecheck` script runs",
+ * and it is FALSE on this tree: `typecheck`'s last leg
+ * (`pnpm check:test-typecheck`) runs `--project tsconfig.test.json`, whose
+ * `include` is `src/**\/*` with no test exclusion, and this file is in that
+ * program (measured with `tsc --listFiles`; the build program, which does
+ * exclude `**\/*.test.ts`, is the firing control at 0). A directive here would
+ * be evaluated — the split is a convention, not a compiler constraint.
  *
  * ⛔ NOTHING HERE IS PHRASED AS "the reference is no longer dropped". Measured
  * on the pre-change tree, the reference was never dropped: `registerDatasourceDef`

diff --git a/packages/objectql/src/register-object-authored-shape.pin.ts b/packages/objectql/src/register-object-authored-shape.pin.ts
@@ -17,11 +17,22 @@
  *   - a genuinely wrong literal (unknown key, wrong field type, missing `name`)
  *     still fails — the loosening must not admit garbage.
  *
- * WHY A `.pin.ts` AND NOT A `*.test.ts`: `packages/objectql/tsconfig.json`
- * excludes `**\/*.test.ts`, so a `@ts-expect-error` written in a test file here
- * is a phantom check — no tsc program the `typecheck` script runs would ever
- * evaluate it, and deleting the directive would leave every gate green
- * (AGENTS.md, #5286's `PINS_CHECKED`). This file IS in that program. It carries
+ * WHY A `.pin.ts` AND NOT A `*.test.ts`, stated to today's tree: a `.pin.ts`
+ * is not a test file, so `packages/objectql/tsconfig.json`'s exclusion of
+ * `**\/*.test.ts` does not reach it and `typecheck`'s unconditional first leg
+ * (`tsc --noEmit`) compiles it.
+ *
+ * ⚠ It is NOT that a directive in a `*.test.ts` here would go unevaluated —
+ * this docblock used to say so, and that is FALSE on this tree. This package's
+ * `typecheck` is `tsc --noEmit && tsc --noEmit -p tsconfig.scripts.json &&
+ * pnpm check:test-typecheck`, and the last leg runs
+ * `--project tsconfig.test.json`, whose `include` is `src/**\/*` with no test
+ * exclusion: 299 of this package's `src` test files are in that program,
+ * measured with `tsc --listFiles` (0 in the build program — the firing control
+ * for the exclusion, and where the old sentence came from). The correction is
+ * kept rather than the sentence deleted, because the wrong version is the one
+ * a sibling file copies.
+ * It carries
  * no executable pin: the assertions live inside a function nobody calls, so the
  * only thing it costs at runtime is the literal below, which the companion
  * `register-object-authored-shape.test.ts` registers for real.

diff --git a/packages/objectql/src/register-object-authored-shape.test.ts b/packages/objectql/src/register-object-authored-shape.test.ts
@@ -3,9 +3,15 @@
 /**
  * #5543 — runtime half of the `registerObject` authored-shape contract.
  *
- * The compile-time half lives in `register-object-authored-shape.pin.ts` (it has
- * to: this file is excluded from every tsc program the `typecheck` script runs,
- * so a `@ts-expect-error` written here would never be evaluated). What this file
+ * The compile-time half lives in `register-object-authored-shape.pin.ts`, which
+ * is where the `.pin.ts` convention puts it — ⚠ NOT because nothing compiles
+ * this file. That parenthesis used to read "this file is excluded from every
+ * tsc program the `typecheck` script runs", and it is FALSE on this tree:
+ * `typecheck`'s last leg (`pnpm check:test-typecheck`) runs
+ * `--project tsconfig.test.json`, whose `include` is `src/**\/*` with no test
+ * exclusion, and this file is in that program (measured with
+ * `tsc --listFiles`; the build program, which does exclude `**\/*.test.ts`, is
+ * the firing control at 0). What this file
  * adds is the other direction — that the literal which now *compiles* also
  * *registers*, unparsed, and comes back out with the authored keys intact and
  * without the `.default(...)` products fabricated on the way through. That is

diff --git a/packages/objectql/src/registry-module-mock.ts b/packages/objectql/src/registry-module-mock.ts
@@ -37,8 +37,18 @@
  *   - vitest's default `include` collects `*.test.ts`, so a shared helper named
  *     that way is collected as a suite with no tests in it;
  *   - `packages/objectql/tsconfig.json` excludes `**\/*.test.ts`, so a helper
- *     named that way would be type-checked by no program the `typecheck` script
- *     runs. This file IS in that program.
+ *     named that way would be out of the BUILD program — `typecheck`'s
+ *     unconditional first leg. A plain `.ts` is in it.
+ *
+ * ⚠ That second reason used to read "type-checked by no program the
+ * `typecheck` script runs", which is FALSE on this tree and is corrected rather
+ * than deleted because the wrong version is what a sibling file copies:
+ * `typecheck`'s last leg (`pnpm check:test-typecheck`) runs
+ * `--project tsconfig.test.json`, whose `include` is `src/**\/*` with no test
+ * exclusion, and 299 of this package's `src` test files are in that program
+ * (measured with `tsc --listFiles`; 0 in the build program). The first reason
+ * — vitest collecting the file as an empty suite — is unaffected and is on
+ * its own sufficient.
  *
  * It is not reachable from `src/index.ts` or `src/core.ts`, so `tsup` never
  * bundles it and it is never published.

diff --git a/packages/plugins/plugin-approvals/src/exec-context-annotation.pin.ts b/packages/plugins/plugin-approvals/src/exec-context-annotation.pin.ts
@@ -38,14 +38,22 @@
  * against it. A re-narrowing is then red twice over, and neither check depends
  * on the retired export coming back.
  *
- * WHY A `.pin.ts` AND NOT A `*.test.ts`: `packages/plugins/plugin-approvals/
- * tsconfig.json` excludes `**\/*.test.ts` (measured on this card, and the same
- * exclusion `plugin-sharing` carries — see #7136 / PR #7140), so no tsc
- * program the `typecheck` script runs would ever read a pin written in a test
- * file here: it would be a phantom check that stays green however this file is
- * broken (AGENTS.md, #5286's `PINS_CHECKED`). This file IS in that program. It
- * is imported by nothing, so tsup (entry `src/index.ts`) never bundles it into
- * `dist`.
+ * WHY A `.pin.ts` AND NOT A `*.test.ts`, stated to today's tree: a `.pin.ts`
+ * is not a test file, so `packages/plugins/plugin-approvals/tsconfig.json`'s
+ * exclusion of `**\/*.test.ts` does not reach it and `typecheck`'s
+ * unconditional first leg (`tsc --noEmit`) compiles it. It is imported by
+ * nothing, so tsup (entry `src/index.ts`) never bundles it into `dist`.
+ *
+ * ⚠ The old ground for this file — that the exclusion left "no tsc program
+ * the `typecheck` script runs" able to read a pin written in a test file here
+ * — is FALSE on this tree, and is corrected rather than deleted because the
+ * wrong version is what a sibling package copies. `typecheck` is
+ * `tsc --noEmit && tsc --noEmit -p tsconfig.scripts.json &&
+ * pnpm check:test-typecheck`, and the last leg runs
+ * `--project tsconfig.test.json`, whose `include` is `src/**\/*` with no test
+ * exclusion: 42 of this package's `src` test files are in that program,
+ * measured with `tsc --listFiles`. `plugin-sharing` carries the same exclusion
+ * and the same correction (see its `exec-context-annotation.pin.ts`).
  */
 
 import type { ApprovalService } from './approval-service.js';

diff --git a/packages/plugins/plugin-sharing/src/exec-context-annotation.pin.ts b/packages/plugins/plugin-sharing/src/exec-context-annotation.pin.ts
@@ -38,15 +38,32 @@
  * against it. A re-narrowing is then red twice over, and neither check depends
  * on the retired export coming back.
  *
- * WHY A `.pin.ts` AND NOT A `*.test.ts`: `packages/plugins/plugin-sharing/
- * tsconfig.json` excludes `**\/*.test.ts` (a measured TEST_DEBT of 3 in
- * `scripts/check-type-check-coverage.mjs`), so no tsc program the `typecheck`
- * script runs would ever read a pin written in a test file here — it would be
- * a phantom check that stays green however this file is broken (AGENTS.md,
- * #5286's `PINS_CHECKED`; #6212 measured the same hole on driver-mongodb).
- * This file IS in that program. It is imported by nothing, so tsup (entry
- * `src/index.ts`) never bundles it into `dist`, exactly like the sibling
- * `.testkit.ts`.
+ * WHY A `.pin.ts` AND NOT A `*.test.ts`, stated to today's tree. This file is
+ * in the BUILD program: `packages/plugins/plugin-sharing/tsconfig.json`
+ * includes `src/**\/*` and excludes `**\/*.test.ts`, and a `.pin.ts` is not a
+ * test file, so `typecheck`'s unconditional first leg (`tsc --noEmit`) reads
+ * it. That is the whole reason for the extension, and it does not depend on
+ * anything being uncompiled.
+ *
+ * ⚠ This docblock used to ground itself the other way round — that the
+ * exclusion left "no tsc program the `typecheck` script runs" able to read a
+ * pin written in a test file here, and that the package carried "a measured
+ * TEST_DEBT of 3 in `scripts/check-type-check-coverage.mjs`". Both halves are
+ * FALSE on this tree, and the correction is kept rather than the sentence
+ * deleted, because the wrong version is the one a sibling package copies:
+ *   - `typecheck` is `tsc --noEmit && tsc --noEmit -p tsconfig.scripts.json &&
+ *     pnpm check:test-typecheck`, and the last leg runs
+ *     `--project tsconfig.test.json`, whose `include` is `src/**\/*` with no
+ *     test exclusion — 33 of this package's `src` test files are in that
+ *     program, measured with `tsc --listFiles`. A pin in a test file here
+ *     would be evaluated.
+ *   - `scripts/check-type-check-coverage.mjs` holds no `@objectstack/plugin-sharing`
+ *     key in either the `DEBT` or the `TEST_DEBT` literal (counted inside each
+ *     literal, not over the file). The 3 is real but lives elsewhere: it is the
+ *     per-file, shrink-only `test-typecheck-debt.json` beside this file.
+ *
+ * It is imported by nothing, so tsup (entry `src/index.ts`) never bundles it
+ * into `dist`, exactly like the sibling `.testkit.ts`.
  */
 
 import type { SharingService } from './sharing-service.js';

diff --git a/packages/plugins/plugin-sharing/src/logger-required-warn.pin.ts b/packages/plugins/plugin-sharing/src/logger-required-warn.pin.ts
@@ -15,12 +15,22 @@
  * pin is the refusal itself: each `@ts-expect-error` below is red exactly
  * when the refusal stops happening.
  *
- * WHY A `.pin.ts` AND NOT A `*.test.ts`: this package's `tsconfig.json`
- * excludes `**\/*.test.ts` (measured TEST_DEBT), so a pin written in a test
- * file is read by NO tsc program the `typecheck` script runs — a phantom
- * check that stays green however the contract is broken. This file IS in the
- * program, is imported by nothing, and is never bundled (tsup entry is
- * `src/index.ts`), exactly like `exec-context-annotation.pin.ts`.
+ * WHY A `.pin.ts` AND NOT A `*.test.ts`, stated to today's tree: a `.pin.ts`
+ * is not a test file, so this package's `tsconfig.json` exclusion of
+ * `**\/*.test.ts` does not reach it and `typecheck`'s unconditional first leg
+ * (`tsc --noEmit`) compiles it. It is imported by nothing and is never bundled
+ * (tsup entry is `src/index.ts`), exactly like
+ * `exec-context-annotation.pin.ts`.
+ *
+ * ⚠ It is NOT that a pin in a test file here would go unread — this
+ * docblock used to say so, and that is FALSE on this tree. `typecheck`'s third
+ * leg (`pnpm check:test-typecheck`) runs `--project tsconfig.test.json`, whose
+ * `include` is `src/**\/*` with no test exclusion: 33 of this package's `src`
+ * test files are in that program, measured with `tsc --listFiles`. The
+ * "measured TEST_DEBT" the old sentence leaned on is likewise not a key in
+ * `scripts/check-type-check-coverage.mjs` — it is the per-file, shrink-only
+ * `test-typecheck-debt.json` in this package. See
+ * `exec-context-annotation.pin.ts` for the same correction in full.
  *
  * ⚠️ SHAPE DISCIPLINE for this file: it deliberately declares NO interface,
  * no type-literal alias and no inline type literal carrying channel-named