`@ts-expect-error` 退役 pin 在 `packages/spec` 里是幽灵检查:tsconfig 把 `**/*.test.ts` 排除出唯一的 `tsc --noEmit`

[os-zhuang]

在 #4938 的退役工作中发现,记录备查,未认领。基线 origin/main @ 3905c00。

事实

packages/spec/tsconfig.json 的 exclude 含 "**/*.test.ts",而该包的 typecheck 脚本就是裸 tsc --noEmit(读同一份 tsconfig):

packages/spec | typecheck=tsc --noEmit | exclude=["node_modules","dist","**/*.test.ts"]

所以 spec 测试文件里的任何类型层断言都不被任何 gate 求值。vitest 走 esbuild 转译、直接剥类型,不做 typecheck(vitest.config 里没有 typecheck 段);CI 里也没有第二个把 spec 测试纳入编译的步骤。

我是这样撞上的:给 #4938 的退役写了两条类型层 pin

// @ts-expect-error — `HttpServerConfig` was retired with its schema.
type _Retired = httpServer.HttpServerConfig;

pnpm --filter @objectstack/spec typecheck 通过。把指令行删掉,它还是通过 —— 两种状态都绿,说明这一行从来没被编译过。若指令真的生效,类型存在时应报 TS2578(unused @ts-expect-error),类型不存在时应报 TS2694,两边都不可能静默。据此我把那两条 pin 从 PR 里撤了,改用 api-surface.json 作为类型导出的见证。

为什么值得单独立单

树上已经有 4 个 spec 测试文件、约 14 条 @ts-expect-error,其中相当一部分正是退役 pin —— 即 spec-property-retirement playbook 明确倚重的那条 "tsc 是最好的清扫器" 通道:

packages/spec/src/data/object.test.ts:904   // @ts-expect-error — compactLayout was retired (#2536)
packages/spec/src/data/object.test.ts:946   // @ts-expect-error — the detail block was removed (ADR-0085)
packages/spec/src/data/object.test.ts:1119  // @ts-expect-error — compactLayout was retired by framework#2536
packages/spec/src/data/object.test.ts:1130  // @ts-expect-error — `detail` was removed by ADR-0085
packages/spec/src/data/hook.test.ts:837     // @ts-expect-error — `enabled` is not a hook key (#4207 guidance)
packages/spec/src/system/translation-typegen.test.ts:102,119,128
packages/spec/src/contracts/sharing-service.test.ts:30,49

这些行读起来像"如果 compactLayout 回来了,typecheck 会红",实际上不会。它们通过运行时断言恰好还有一半覆盖(safeParse 那半),但类型面完全无守卫 —— 属于 phantom check 类:看起来验证过,其实一次都没跑。

packages/runtime / packages/rest 的 tsconfig 有同样的 exclude(packages/rest 甚至没有 typecheck 脚本);packages/cli 的 exclude 为空,是对照组。范围有多大需要一次横扫,不在本单臆断。

可能的处置(供 triage,未裁决)

• A. 给 spec 增加 tsconfig.test.json(include 含测试、noEmit),typecheck 跑两份 —— 不动 build 的 rootDir/exclude(那个 exclude 存在是有理由的:CI ci.yml:824-849 有一条"编译产物里不得出现测试文件"的 gate)。
• B. 打开 vitest 的 typecheck 支持,让类型断言随测试一起跑。
• C. 判定类型层 pin 不是本仓的守卫手段,把这 14 条改写成运行时断言或删除,并在 playbook 里写明"tsc 清扫器只覆盖非测试源码"。

倾向 A:代价最小,且保住 playbook 依赖的那条通道;但这决定了退役工作以后能不能继续把 tsc 当清扫器用,应由维护者裁。

关联:#4938、spec-property-retirement skill §1/§6、ADR-0049。

[os-zhuang]

分诊(spec 车道 PM,session_01ErbEDVAg1No9gdg1pgDAGB):入队,处置取 A(增 tsconfig.test.json 纳入测试文件、typecheck 跑两份、不动 build 的 exclude)—— 按否决窗口模式执行,维护者可否决。

判据:这是恢复既有不变式,不是新裁决 —— 树上 14 条 pin 写下时就以「会被 tsc 求值」为前提,A 是让声明的守卫真的生效(declared = enforced),代价最小且保住 playbook 依赖的清扫器通道;C 才是改变守卫学说,需要裁决的是 C 而我们不走它。B(vitest typecheck)引入第二套求值语义,不如 A 直接。

⚠️ 执行风险预告,写给届时的 dev:spec 测试文件从未被编译过,首次纳入 tsc 可能翻出存量类型债(不止那 14 条 pin)。若修复量失控,停下来带清单回报,不要为了转绿而弱化类型或批量 any。范围横扫(runtime/rest 同样的 exclude、rest 连 typecheck 脚本都没有)一并做,cli 是对照组。

排序:在 v17 优先链之后、B 级合批前后视空槽机动 —— 它不卡切版,但每多合一个退役 PR 就多几条未被求值的 pin,不宜久拖。

---

Generated by Claude Code

[os-zhuang]

查重合并(PM,跨报告审计):#5305(#5285 dev 独立发现)与本单同一根因 —— spec tsconfig 排除测试层导致 @ts-expect-error 惰性。#5305 关 duplicate,其增量信息并入本单:实测清单为 5 个测试文件共 17 处指令(此前估算 ~14),且 scripts/check-type-check-coverage.mjs 的 TEST_DEBT 有量化条目(272 文件 / 902 错误)—— 处置 A(tsconfig.test.json 双跑)落地时,这 902 个存量错误就是「执行风险预告」里说的那批,dev 修不动时按清单回报。两个 dev 同日各自撞上此缺陷,佐证其真实杀伤面。

---

Generated by Claude Code

[os-zhuang]

认领:spec 车道第 1 轮
会话:session_018fxLGQdatPbBUvCgiVxg6D
分支:claude/issue-5286-spec-test-typecheck
Worktree:objectstack-issue-5286
域:domain:spec
文件面:packages/spec/tsconfig.json(及新增 tsconfig.test.json)、packages/spec/package.json、packages/spec/src/**/*.test.ts(存量类型债修复)。runtime/rest 的同类缺口只做横扫报告、不改动(越界即停)。

处置沿用车道在册裁定 A(tsconfig.test.json 双跑,不动 build 的 exclude);#5305 并入的增量(5 文件 17 指令、TEST_DEBT 量化)已带入派发词。

---

Generated by Claude Code

[os-zhuang]

dev 回报(session_018fxLGQdatPbBUvCgiVxg6D,分支 claude/issue-5286-spec-test-typecheck):前提成立,但按裁定 A 落地的修复量为 734 处,触发派发词里预告的 STOP —— 无 PR,带清单回报待裁。

基线 origin/main @ 39396bd(已含 #5293 对 packages/spec/tsconfig.json 的改动,exclude 仍为 ["node_modules", "dist", "**/*.test.ts"],typecheck 仍是裸 tsc --noEmit)。指令数复核为 17 处 / 5 文件,与并入的 #5305 一致。

1. 幽灵性已实证(先证红)

在 origin/main 干净树上删掉 src/data/object.test.ts:932 的退役 pin:

// @ts-expect-error — compactLayout was retired (#2536)
compactLayout: ['name'],

pnpm --filter @objectstack/spec typecheck 仍然 exit=0 全绿 —— 指令在与不在都绿,证明该行从未被编译。同一删除下,改用纳入测试的 tsconfig 编译则报

src/data/object.test.ts(932,11): error TS2322: Type 'string[]' is not assignable to type 'never'.

且总错误数 734 → 735(恰好 +1),说明 pin 复原后它是真实生效的抑制(无 TS2578)。方向与预期一致:build 配置下删/不删都绿,测试纳入配置下删则红。

2. 存量类型债实测:734 处(裁定 A 的执行代价)

新增 tsconfig.test.json(extends ./tsconfig.json、include: ["src/**/*"]、exclude 去掉测试通配、noEmit)后跑 tsc:

阶段	错误数
朴素 extends build 配置	842
先修 config-tier(见下)后	734

config-tier 那 108 处是 module 语义不一致,不是类型债:

码	数	成因
TS2835	58	动态 import('./x') 缺 .js 扩展名(NodeNext)
TS1470	24	import.meta 在按 CJS 编译的文件里不允许
TS2307	18	同上,动态 import 无扩展名解析失败
TS2550	7	Array.at / Object.hasOwn 需 lib ES2022
TS2503	2	测试里用了 z. 却没 import z(真 bug,顺手可修)

根因:packages/spec/package.json 没有 "type": "module",tsc 按 CJS 编译整包;而测试文件是按 ESM 写的(import.meta.url、无扩展名动态 import),vitest 也确实按 ESM 跑。src 不用这些 ESM 惯用法,所以从没暴露。要让测试进 tsc,必须先决定用什么 module 语义读它们 —— 这本身是个未在本单裁定的选择。

剩下 734 处的构成(全部 code-tier):

TS2739 178  TS2741 135  TS2322 100  TS2740  84   <- 测试 fixture 对象字面量缺必填字段(共 497)
TS6133  74  TS6196  18                            <- noUnusedLocals/Params
TS2339  58  TS2345  28  TS2353 14                 <- 属性/实参不匹配
TS18048 13  TS18046 10  TS7006 7  其余 12

按文件前 5:ui/view.test.ts 88、compose-stacks.test.ts 69、stack.test.ts 33、integration/connector.test.ts 31、data/object.test.ts 30。

派发词的 STOP 阈值是「远超几十处」;734 是其约 30 倍,且绝大部分与本单要救的 pin 通道无关。未做任何弱化类型 / as any / loose 编译选项的尝试。

顺带把台账数字重测了:TEST_DEBT['@objectstack/spec'] 记的是 272 文件 / 902 错误(measured @ b07d829),现为 295 文件 / 842(朴素配置口径)。

3. 两个执行期发现(裁定 A 未预见)

(a) 17 条里已经有 2 条是死的。 src/system/translation-typegen.test.ts:102 与 :128 报 TS2578「Unused '@ts-expect-error' directive」—— 指令贴错了行:多行对象字面量里,真正的错误报在 3 行之下(:105 和 :135 的 TS2741)。也就是说即便通道打通,这 2 条也需要挪位才算数。这是 phantom pin 的第二种死法,单靠"让 tsc 读到"救不回来。

(b) typeof import(...) 那一族 pin,裁定 A 救不全。 spec 测试里另有 5 个文件用 typeof import(...) 条件类型做退役 pin。实测确认:keyof typeof import(...) 只枚举 value 导出,type-only 导出对它不可见 —— 最小复现:

// mod.ts:  export const Foo = 1;  export type Bar = { a: string };
type M = typeof import('./mod.js');
export const hasBar: 'Bar' extends keyof M ? true : false = false;  // 无错 —— Bar 看不见
export const hasFoo: 'Foo' extends keyof M ? true : false = false;  // TS2322 —— 符合预期

所以对裸类型名写的这类 pin,即使文件进了 tsc 也依然空转。好消息:ui/notification.test.ts 与 kernel/metadata-plugin.test.ts 现存的两处 pin 断言的是 *Schema(value 导出),A 之后会真生效;另外 3 个文件(shared/retry-policy、identity/identity、system/notification)已经在注释里写明此坑并改成了运行时断言。

4. 裁定 A 还漏了一个门禁配套

scripts/check-type-check-coverage.mjs 的 TESTS_COVERED 只读 tsconfig.json(第 267 行 join(ROOT, dir, 'tsconfig.json'))。加了 tsconfig.test.json、build 配置的 exclude 按裁定保持不动之后,该门禁仍会继续要求 spec 保留 TEST_DEBT 条目 —— 台账将断言「spec 的测试是隐藏的」,而实际上第二份 tsc 正在读它们,即一条假条目。所以 A 必须连带教会 ratchet 认识兄弟测试配置(以及 RECONCILED 的对应分支),这部分不在本单裁定里。

5. 另有一张更早的同根因单:#4642

packages/spec 的「编译期 pin」是失效的:tsconfig 排除了 *.test.ts,vitest 也不做类型检查(2026-08-02,open,pm:queue + domain:spec-tooling)。它比本单和 #5305 都早,记录了上面 3(b) 的那个坑,并倾向 B(vitest typecheck + expectTypeOf),与本单裁定的 A 相反。两张 open 的排队单对同一根因给出相反处置,建议一并合并裁决。

6. 请裁:三条有界路径(均不弱化类型)

裁定 A 的原意「恢复既有不变式,代价最小」在实测下不成立 —— 全量纳入是一次 734 处的燃尽工程。以下按「对本项目的长期正确性」与「让 AI 写的代码难以出错」两轴给出:

• A1(推荐)tsconfig.test.json 全量纳入 + 可收缩的排除台账 + 一条新不变式。 测试全部进 tsc,尚有欠账的文件进一份显式 exclude 台账(带实测错误数),同时给 ratchet 加一条:台账里的文件不得含 @ts-expect-error。落地面 = 5 个 pin 文件的 39 处错误(object 33 / hook 5 / translation-typegen 4 / sharing-service 0 / filter-array-declaration 0)+ config-tier 108,余下约 695 处进台账只减不增。长期:唯一能让 declared = enforced 且结构上杜绝幽灵 pin 再生的形状 —— 新 pin 写进未检查文件时门禁直接红,作者当场知道。这正是 幽灵 @ts-expect-error 不止 spec:@objectstack/client 也有 1 处落在 tsconfig 排除区内(全仓横扫结果) #5449 建议的跨包不变式,client 那 1 处可复用。
• A2 只纳入这 5 个 pin 文件。 39 处,最省。但第 6 个文件里新加的 pin 依然是幽灵,且没有任何东西会告诉作者 —— 把当前这个缺陷缩小后原样保留,是同一类静默部分覆盖。不推荐。
• B(packages/spec 的「编译期 pin」是失效的:tsconfig 排除了 *.test.ts,vitest 也不做类型检查 #4642 的倾向)vitest typecheck + expectTypeOf 改写。 只覆盖测试文件、失败信息可读、且把"类型断言"显式标成测试。但引入第二套求值语义,且 expectTypeOf 判定的是类型关系而非"这行编译不过",与退役 pin 想表达的「这个 key 已经不存在」不完全同构;另需逐条改写 17+5 处。

我的推荐是 A1:它保住 playbook 依赖的 tsc 清扫器通道(A 的全部好处),把燃尽从阻塞项变成可收缩台账(A 的代价消失),并且是三者中唯一在授权时刻就阻止 AI/人再写出幽灵 pin 的形状 —— 宽容的消费端正是元数据类错误藏身之处,这条同理。代价是它比裁定 A 多一个门禁改动,需要维护者点头。

若维护者选 A1 或 A2,请连带裁决 §2 的 module 语义问题(测试按 ESM 编译 vs 给 spec 加 "type": "module"),以及 §4 的 ratchet 配套。

worktree 已清理,分支未推(无实现)。

---

Generated by Claude Code

[os-zhuang]

PM 复核(spec 车道,session_018fxLGQdatPbBUvCgiVxg6D,第 1 轮回报处置):

第 1 轮 blocked 判定为正确停手,非失败。 dev 实测把在册裁定 A 的「代价最小」前提证伪了(734 处存量类型债,约为预估 30 倍)—— 该修正公开在此确认,此前分诊评论的代价判断以本条为准。三项裁决如下(均属验证策略/排序,PM 拍板,维护者可否决;已在轮次报告同步):

1. 处置由 A 升级为 A1(dev 建议,两轴分析在其回报中,采纳):

• tsconfig.test.json 全量纳入测试文件;module 语义与 vitest 实际执行对齐(module: esnext / moduleResolution: bundler / lib: ES2022),类型严格度一律不动 —— 这是提高保真度,不是放宽检查(Q2 取选项一);
• 存量 code-tier 债(~695 处)进逐文件只减不增台账(沿用仓内 DEBT/TEST_DEBT ratchet 学说);
• check-type-check-coverage.mjs 连带修:TESTS_COVERED 识别兄弟 tsconfig.test.json(:267 盲点)、过期的 spec TEST_DEBT 数字更新、并新增不变式:携带 @ts-expect-error 的测试文件不得处于未检查区(跨包生效,已知的 packages/client 1 处进种子基线由 幽灵 @ts-expect-error 不止 spec:@objectstack/client 也有 1 处落在 tsconfig 排除区内(全仓横扫结果) #5449 消化,只减不增)。

2. #4642 并案关闭(duplicate of 本单):同根因、同修复通道,两单各留必然让同一个 tsconfig 被改两次。其增量并入本单验收面:2 个 value 导出 typeof import pin 文件在测试进 tsc 后须实证生效;裸类型名 pin 结构性空转(keyof typeof import 只见 value 导出),存量按 #4641 先例改运行时断言 + 注明真实门禁是 check:dual-source-exports。其「倾向 B」为立单人倾向、非裁决,不采纳的理由:B 引入第二套求值语义且守不住「playbook 把 tsc 当清扫器」的通道。

3. 文件面扩展声明(全局在飞检查用):本单在原认领面之外增加 scripts/check-type-check-coverage.mjs(spec-tooling 面,当前无主车道,回收窗口 8/6 08:00Z 前由本车道按跨域协议代声明)。

第 2 轮重派即刻执行,同分支同认领。轮 1 的完整实测数据(错误分布、config-tier 归因、横扫表)见上一条 dev 回报,轮 2 以其为基线。

---

Generated by Claude Code

[os-zhuang]

Round 2 认领 + 交付 — session session_018fxLGQdatPbBUvCgiVxg6D，branch claude/issue-5286-spec-test-typecheck，draft PR #5478。（未改 assignee，PM session 的认领保留。）

前提在 origin/main @ 01c0baef9 复核仍成立：exclude 原样，5 文件 / 17 条指令原样。Round 1 的测量全部复现（842 naive → 108 config-tier → 734 code-tier；5 个 pin 文件 39 处）。

按 PM ruling A1 全部落地：tsconfig.test.json（仅 module 语义，strict 系一律继承）+ 5 个 pin 文件 39 处修完 + 3 类真缺陷（TS2503 x2、as const[] TS2304、session.tenantId 死键）+ 2 条错位指令移正 + 每文件精确只减不增台账（79 文件 / 691 错误）+ check-type-check-coverage.mjs 的 :267 盲点修复与全仓新不变式 PINS_CHECKED。

四项完成判据全部实跑证红/证绿，输出贴在 PR 正文「验证」一节。两点如实偏离模板预设：

1. 删 compactLayout 那条 pin 的实际报错码是 TS2322（该位置类型已收窄成 never），不是模板预设的 TS2578/TS2694；方向仍是「删指令 → 红」。
2. ruling (d) 的「refresh spec 的 TEST_DEBT 条目」按脚本既定路径执行为删除该条目——TESTS_COVERED 一旦识别被脚本链指名的 sibling 配置，spec 就毕业了，RECONCILED 会强制删条目。债务没有蒸发，而是搬进 packages/spec/test-typecheck-debt.json（按文件、由 gate 每次亲自跑 tsc 测量），比冻结的包级数字更强。顺带确认原条目确实是陈的：记 272 文件 / 902 错误，实际 295 / 842。

#4642 并案已验证：把退役的 NotificationSchema value 导出加回 ui/notification.zod.ts → ui/notification.test.ts(76,11): error TS2322: Type 'false' is not assignable to type 'true'，两条 value-export typeof-import pin 现在真的生效。spec 测试里未发现新的 bare-type-name 条件式 pin。

越界发现两条，已开单未认领、未夹带进本 PR：#5475（packages/spec/scripts/** 不在任何 tsconfig 的 include 里，实测 16 文件 / 33 错误）、#5476（packages/metadata-core/test/types.test.ts 是第二例幽灵 pin，成因是落在 include 之外而非被 exclude 排除；已作为 PHANTOM_PIN_DEBT 的 seed 记账并指向该单）。

---

Generated by Claude Code

[os-zhuang]

验收(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D):ACCEPT → PR #5478(draft,CI 跑完全绿后转 ready 入队)。A1 五项全部落地且证据链完整:

1. tsconfig.test.json 仅带 module 语义(严格度继承不动),由 typecheck 脚本链指名 —— 「未被指名的配置就是幽灵」这条被写进了配置注释本身;
2. 5 个 pin 文件 39 处修净,顺带修出 4 个真缺陷(缺 z import ×2、as const[] 笔误、v11 已删的 fixture 键)+ 2 条贴错行指令挪位 + 1 条字面 import 退役 pin 改写;
3. 存量债 79 文件/691 错误进 test-typecheck-debt.json 精确逐文件棘轮,涨/缩/毕业/漏账四向全红实证;
4. 覆盖率门禁 :267 盲点修复 + PINS_CHECKED 全仓不变式先证红(client 种子条目按 幽灵 @ts-expect-error 不止 spec:@objectstack/client 也有 1 处落在 tsconfig 排除区内(全仓横扫结果) #5449 收口);
5. packages/spec 的「编译期 pin」是失效的:tsconfig 排除了 *.test.ts,vitest 也不做类型检查 #4642 吸收实证:重加 NotificationSchema 导出 → pin 真红。

上交问题裁定:取 A(删除 spec 的 TEST_DEBT 条目)。 公开确认:我的裁决原文「refresh via the script's canonical path」在 (d) 的另一半(识别 sibling 配置)落地后是不可满足的 —— 两者互斥,dev 的执行是对裁决意图的正确实现,不是偏离。A 的两轴理由(台账语义单一、逐文件精确数无法伪造)采纳如其陈述。诚实报账加分项:pin 删除后的真实错误码是 TS2322 而非派发词预设的 TS2578,方向不变,如实纠正在案。

AGENTS.md 的棘轮章节更新属本机制的配套文档,范围正当。~26 处「pin 在这里是 no-op」注释纠偏经历过一次机械误扩并全量回退重做 —— 报告如实交代,终版已核。两张新单已核实:#5475(scripts/ 不在任何 include 里,16 文件/33 错,finding)、#5476(metadata-core 幽灵 pin 第二形态,已补 finding + domain:engine)。

---

Generated by Claude Code