No gate asserts the TYPE axis of the source-resolution invariant: check:test-source-alias reads vitest.config.* only, so every package's tsconfig can resolve workspace deps through dist with nothing saying so

[hotlong]

Filing unassigned; found while implementing #8021 (PR #8176), and deliberately not fixed there — that card's scope is one package's tsconfig, and a repo-wide gate is its own blast radius.

The asymmetry

#7849 / PR #7966 landed check:test-source-alias, which makes the source-resolution invariant mechanical rather than per-package goodwill: for every workspace package with tests, walk the imports reachable from those tests, keep the deps that resolve under dist/, simulate Vite's resolution over vitest.config.*, and demand that anything left is registered. Its own header states why a sweep is the wrong terminal state — "it leaves the NEXT package unguarded, and the symptom of the omission is a green test, so nothing would report the gap".

That reasoning is axis-independent, but the gate is not. It reads vitest.config.* and nothing else. No gate reads tsconfig.json, so the identical exposure on the type axis is unguarded repo-wide, and its symptom is likewise a green typecheck.

Measured, on the one package that has now been fixed

#8021 measured it end to end on packages/qa/downstream-contract. Identical checkout, identical stale dist, a narrowing injected into packages/spec/src/integration/connector.zod.ts in source only with no rebuild:

• without a paths block: tsc --noEmit exit 0, clean
• with a paths block: src/additional-domains.fixtures.ts(35,3): error TS2322: Type 'string' is not assignable to type 'number'.

That package is the repo's backward-compatibility gate, whose README promises "a removed or NARROWED export fails here" — so it was the loudest instance, which is why it got a card. It is not the only instance. The mechanism is generic and is in fact documented as the expected state in .github/workflows/lint.yml, beside the type-check-debt re-measure step:

tsc resolves workspace imports through each dependency's built dist/*.d.ts — so it needs the build steps above

Ordering does not reach it, same as both prior cards: turbo.json orders typecheck after ^build, so turbo run typecheck and CI are not the failing paths. What breaks is every path turbo does not mediate — pnpm --filter PKG typecheck inside a package, an editor's TS server, an agent in a tree built at an older commit. Those are exactly the paths a type contract is re-read on while someone is changing the dependency.

What a gate would have to get right (from #8021's measurements)

Not a copy of the vitest one — the resolution algorithm and the trap are both different:

1. tsc's paths algorithm, not Vite's. An exact (star-free) key wins outright; otherwise the pattern key with the longest matching prefix wins and the captured text substitutes into the target's star. Vite's is first-match-wins with prefix matching for string finds.
2. The trap has a different spelling and is worse. A tsconfig key without a * is an exact match, so the bare @objectstack/spec entry cannot swallow @objectstack/spec/ui the way a Vite object-form alias does (ENOTDIR). The tsconfig-shaped mistake is @objectstack/spec* — star not preceded by a slash — which matches every namespace and folds it onto whatever the target names. It does not crash: spec/src/index.ts re-exports most of the namespace surface, so it type-checks against the wrong module and stays green.
3. Rules fail independently and silently. Measured on downstream-contract's OTHER half — its typecheck — still resolves @objectstack/spec types through dist, so a narrowed export type reads green (measured) #8021: with the subpath rule kept and only the bare-entry rule deleted, tsc stayed clean while src/stack.ts's defineStack types came from dist.
4. tsconfig.json is JSONC. Whole-line comment stripping before JSON.parse, as scripts/check-type-check-coverage.mjs already does.
5. extends chains. Unlike vitest.config.*, tsconfigs inherit; a gate must resolve extends before reading paths.
6. The switch is not free, and the cost is not the gate's to hide. Putting a dependency's source into a consumer's program makes tsc check that source under the consumer's compilerOptions. On downstream-contract's OTHER half — its typecheck — still resolves @objectstack/spec types through dist, so a narrowed export type reads green (measured) #8021 that surfaced 2 TS2591 (spec source needs types: ["node"]) and 247 TS6059 from a rootDir that emits nothing under noEmit but is still enforced. So remediation is per-package and lands as its own card — the gate's job is to make the list of cards finite and unable to grow behind anyone's back, exactly as the vitest gate's header argues. A registry of the measured state, shrink-only and audited for set equality in both directions, is the shape that worked there.

Prior art (searched before filing)

• A package with unit tests and no vitest.config.ts lets a stale @objectstack/core dist decide its verdicts — #7668 fixed one, nothing stops the next #7849 / PR ci(test-alias): gate that a unit test judges source, not a sibling's dist #7966 — the runtime-axis gate and registry. Type resolution is explicitly outside their scope.
• packages/qa/downstream-contract — the repo's backward-compatibility gate for @objectstack/spec reports 14/14 green against a spec change that breaks its own fixture, because it reads spec/dist #7991 / PR test(qa): make the spec backward-compatibility gate read spec source, not spec dist #8129 — the runtime half of downstream-contract.
• downstream-contract's OTHER half — its typecheck — still resolves @objectstack/spec types through dist, so a narrowed export type reads green (measured) #8021 / PR test(qa): make the backward-compatibility gate's TYPE half read spec source, not spec dist #8176 — the type half of that one package; this finding is the repo-wide generalization it deliberately did not attempt.
• check:test-source-alias cannot read a template-literal alias replacement, so two packages that DO alias spec subpaths to source are still recorded as unaliased #8020, check:test-source-alias still cannot read a +-concatenated alias replacement — the #8020 defect one spelling over #8108 — defects in how the vitest gate reads alias replacements (template literal, + concatenation). Same family, and a warning about how easily a resolution-simulating gate reads a correct config as wrong.
• Three more dist-reading spec gates carry the same unenforced freshness precondition as gen:api-surface #7181 (closed) — dist-reading spec gates with unenforced freshness preconditions.
• packages/spec/scripts/** 在任何 tsconfig 的 include 之外:9 个 vitest 测试文件 + 全部构建/gate 脚本无类型检查覆盖 #5475 (closed), [P2] framework: 66 个包用 tsup 构建、无人做类型检查 —— 实测 18 个包共 380 处 code-tier 错误(#4118 的 framework 侧对应) #4311 — type-check coverage holes, a different question: those ask whether tsc reads a file at all, this asks what a file's imports resolve to once it does.

Nothing open covers the type axis.

---

Generated by Claude Code

[hotlong]

Triage: lands in scripts/ (a new gate) + a shrink-only registry, following the check:test-source-alias precedent ⇒ domain:devx, type Task, pm:queue. This is a well-scoped gate addition — the card already carries the six measured requirements (tsc paths algorithm, the star-not-after-slash trap, independent rule failure, JSONC, extends chains, per-package remediation cost stays out of the gate) — so there is nothing to ask the maintainer; the registry-of-measured-state shape was already accepted for the runtime axis in #7849/PR #7966.

Size/model suggestion: L / opus. ⚠️ Two cautions for the dispatch: (1) #8020/#8108 are on record as defects in how the vitest resolution-simulating gate misread correct configs — the type-axis gate should ship its own self-test cases for each of the six requirements; (2) remediation of individual packages is explicitly out of scope — the gate's deliverable is the finite audited list, not fixing entries.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 12
Session: session_01PaiisQMhsYxwa5ZX6Mfmv2 · dev session_018JWibNopHc8HYM18SSVqVA
Branch: claude/issue-8180-type-axis-source-resolution-gate
Worktree: objectstack-issue-8180
Domain: domain:devx
File surface: 新门禁脚本 + shrink-only 登记表 + 根 package.json 的 check: 注册(+ 有论证时 CI 接线)。⛔ 零 tsconfig.json 改动,任何包都不行
Container & model: S(全仓遍历), mode:cloud, model: opus

三条裁决,其中第一条是本席的常设跨车道规则

1. 门禁 + 登记表,⛔ 零包改动。 卡片自己也这么主张,而本席的常设承诺让它成为硬约束:downstream-contract's OTHER half — its typecheck — still resolves @objectstack/spec types through dist, so a narrowed export type reads green (measured) #8021 实测一个包切到源码解析就冒出 2 条 TS2591 + 247 条 TS6059。一个全仓整改 diff 会和每一条在飞车道在共享合并队列里相撞。门禁的职责是把整改卡的清单变成有限且无法在背后增长的,不是把它做完。逐包整改一律拆成后续卡 —— 立卡,不做。
2. 登记表 shrink-only,且双向做集合相等审计,与 check:test-source-alias 同形。能出不能进;能悄悄增长的登记表是现状台账,不是棘轮。
3. ⛔ 不得照抄 Vite 的解析算法。 tsc 是「无星精确键直接胜出,否则最长匹配前缀的模式键胜出、捕获文本填入目标的星」;Vite 是首次匹配胜出。抄错的后果不是漏报而是把正确配置读成错的 —— check:test-source-alias cannot read a template-literal alias replacement, so two packages that DO alias spec subpaths to source are still recorded as unaliased #8020 与 check:test-source-alias still cannot read a +-concatenated alias replacement — the #8020 defect one spelling over #8108 就是这个。JSONC 与 extends 继承两条同为必做项,不是加分项:vitest.config.* 两者皆无,所以移植必错两处。

⚠️ 派发令里我写得最重的一段:仪器有效性

本席今天已被同一个缺陷咬过四次,而本卡的交付物正是最容易产生第五次的那类东西:

被计数的东西	仪器为什么瞎
@objectstack/core 别名点	规范形态是正则字面量,字节里带转义斜杠
别名 replacement(#8020)	读取器取最后一个字符串字面量,而规范形态是模板字面量
已发布的拒绝消息(#8005)	消息是模板化的,渲染后的字符串在源码里根本不存在
未接线的 check:*(#8229)	普查 grep npm script 名,而修法是 node scripts/X.mjs —— 于是它会把两个已修好的成员永远报成未接线,并且一直看起来是对的

⇒ 派发令要求:在相信自家门禁产出的任何一个数字之前,先拿「所计数之物的规范正确形态」和「已知错误形态」各验一次读取器。 最低限度必须有 @objectstack/spec*(星号前无斜杠)的夹具 —— 卡片指出那是更坏的陷阱:它不崩溃,匹配整个命名空间、折到同一个目标上,对着错误的模块类型检查通过并保持绿色。门禁若认不出它,那就是造了一台专门给它要抓的缺陷发合格证的仪器。

一条我要求先测再设计的分布读数

卡片里「门禁必须做对的六件事」全部测自一个包。派发令要求先量全仓分布(多少包有 paths、多少用 extends、多少 tsconfig 带注释)再定形状 —— 3 个包和 70 个包要的东西不一样。以及登记表的初始规模:若几乎每个包都进表,本门今天什么也没找到、全部价值在棘轮,那也许仍值得,但必须带着数字明说,不能让一张大表读起来像一个大发现。

串行位置已核:新建脚本 + 登记表,与在飞面无交集(PR #8225 在 scripts/check-type-check-coverage.mjs,PR #8172 在 scripts/check-adr-merge-approval.mjs)。

---

Generated by Claude Code

[hotlong]

{
  "issue": 8180,
  "status": "done",
  "branch": "claude/issue-8180-type-axis-source-resolution-gate",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/8248",
  "premise_still_valid": true,
  "summary": "Added scripts/check-type-source-resolution.mjs plus the check:type-source-resolution npm script and a lint.yml step beside its runtime sibling. For every workspace package with a tsconfig.json it determines the tsc program's files, collects the workspace deps they import (type-only imports INCLUDED — the inversion of the runtime gate's rule), keeps the ones whose declarations resolve under dist/, resolves each specifier through the effective paths with tsc's algorithm (exact star-free key wins outright, else longest matching prefix — NOT Vite's first-match-wins), and demands that anything still landing on an artifact be registered in a shrink-only registry audited for set equality in BOTH directions. It also refuses the @objectstack/spec* spelling (star not after a separator) and a paths target that does not exist on disk. Measured distribution first, as instructed: 77 workspace packages, 76 with a tsconfig.json, 55 carrying comments and 66 using extends — so JSONC and extends are the norm here, not edge cases. ZERO package edits: no tsconfig.json changed anywhere, no remediation.",
  "tests": "node scripts/check-type-source-resolution.mjs --self-test -> 'check-type-source-resolution --self-test OK' (16 fixtures). It passed on the FIRST run, so it was mutation-tested to prove it is not vacuous — 6 mutations, each caught by its named assertion, mutant exit code 1: (1) star-trap detector removed -> 'the `@pkg*` trap (star not preceded by a separator) was NOT flagged'; (2) Vite's algorithm substituted -> 'an EXACT key declared after a matching pattern key did not win', 'the LONGEST matching prefix did not win', PLUS false reds on four compliant fixtures (the #8020/#8108 shape reproduced); (3) type-only filter inherited -> 'a TYPE-ONLY import of a dist-resolving dep was not counted'; (4) JSONC stripping removed -> 'a CORRECT config was reported because its comments were not stripped'; (5) extends resolution removed -> 'a correct `paths` block inherited through `extends` was not seen'; (6) missing-target check removed -> 'the missing-target diagnostic did not say the target is missing'. Full gate: 'check-type-source-resolution OK — 76 packages with a tsconfig.json scanned; 51 registered'. Reverse verification on REAL packages, direction predicted before running, all restored (git status clean afterwards): downstream-contract with only the bare-entry rule deleted -> exit 1 naming @objectstack/spec (the config tsc itself reports CLEAN on); with only the subpath rule deleted -> exit 1, same dep; both rules replaced by '@objectstack/spec*' -> exit 1 on the trap WHILE every specifier still lands under src/; packages/core with a rule added for spec only -> 'Narrow the entry to exactly: [\"@objectstack/metadata-core\"]' (entry narrowed, not cleared — rules judged individually, confirmed on a second package). Derived gates all green: check:nul-bytes, check:changeset-gate-self-tests, check:filter-alias-parity, check:node-version, check:required-contexts, check:shard-attestation, check:workflow-status-functions, check:type-check-coverage, check:type-source-resolution, scripts/check-changeset-no-major.mjs. Re-derivation via scripts/pm/dispatch-gates.mjs on the actual changed paths added nothing the prompt missed and already discovers the new gate itself. check:type-check-debt was derived but NOT run locally: it refuses to measure without a built workspace closure (its own guard, 55 deps unbuilt); no package source or tsconfig is touched, so no ledger number can move. CI gate status at report time: in_progress (reporting at draft-PR time per contract).",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #8249: type-axis remediation worklist — the 51 registry entries with their full dep sets, from which per-package cards get cut when picked up (unassigned, unlabeled, NOT worked)"
  ],
  "mechanism_findings": {
    "A_rules_fail_independently": "CONFIRMED and extended to a second package. downstream-contract: deleting either rule alone turns the gate red naming @objectstack/spec — including the bare-rule-only case that #8021 measured tsc staying CLEAN on. packages/core: adding a rule for spec alone narrows the entry to [@objectstack/metadata-core] rather than clearing it. The gate judges each specifier, never 'does a paths block exist'.",
    "B_distribution": "77 workspace packages; 76 with tsconfig.json; 64 with a typecheck script; 55 carry comments; 66 use extends; only 4 declare paths at all and only ONE (downstream-contract) aliases a workspace package — the other three are 'knex' x2 and apps/docs. So JSONC + extends are mandatory as the card said, and the predicate was set to 'has a tsconfig.json' (76) rather than 'has a typecheck script' (64), since an editor's TS server reads every package.",
    "C_registry_initial_size": "51 of 76 packages, 222 package-dependency pairs, 25 clean. The gate finds NO new offender today; its entire value is the ratchet. Stated plainly in the PR body with the number, per instruction, so a large registry is not read as a large finding.",
    "D_false_positives": "25 of 76 packages are NOT flagged, so the gate discriminates. The strongest real-data check: packages/qa/downstream-contract — the one package remediated on this axis before this PR — is read as clean. Self-test also pins three false-positive classes (no workspace dep at all; a dep whose types already point at source; a file outside the include/exclude program).",
    "E_cost_and_placement": "1.2s for a full run, and it needs neither node_modules nor a build — verified accidentally but decisively: it was the ONLY gate that passed in the fresh worktree before pnpm install. Wired into the lint job, which has no build step before it (confirmed by reading the job boundaries), the same job as check:test-source-alias."
  },
  "deviations_from_dispatch_prompt": [
    "建议路线 suggested one remediation card per package (51 cards). Filed ONE worklist issue (#8249) carrying every package's full dep set instead, because each card's actionable content is that package's MEASURED error classes (the 2 TS2591 + 247 TS6059 shape), which requires running tsc per package against a built closure — work well outside this card. 51 cards filed now would be content-free duplicates of the registry. #8249 states that per-package cards get cut from it when picked up, matching the runtime-axis precedent where one package's card was filed when it was taken up. Flagging this as a judgment call the PM may reverse.",
    "skip-changeset applied rather than a changeset: the diff is root tooling only (scripts/, a root package.json script, lint.yml) and releases nothing. Labels were read back before writing the union — they were ['size/xl'] (bot-applied), now ['size/xl', 'skip-changeset']."
  ],
  "notes": "The PR was auto-subscribed by the platform with a stay-resident drive-to-green posture. Per os-dev.md this dispatch contract outranks it (maintainer ruling 2026-08-11) and only the standard injected text was involved, so it is recorded here rather than in open_questions. One incidental: the designated branch already existed in the shared checkout with no commits ahead of main, so the worktree was created with --force onto that same branch rather than a fresh one; the pushed branch is the designated name."
}

---

Generated by Claude Code