`@objectstack/spec` 仍锁在 17.0.0-rc.0:升到 rc.1 会产生双版本 spec 图,并打红 `check:spec-symbols`

[os-zhuang]

结论

本仓当前 lockfile 把 @objectstack/spec 解析到 17.0.0-rc.0,而 registry 上 rc tag 已经是 17.0.0-rc.1。升级不是改个 range 就完事 —— 实测有两个硬阻塞。

现状

package.json 里的 range 是 ^17.0.0-rc.0(root + 24 个包),本身已经允许 rc.1,只是 lockfile 钉在 rc.0:

$ ls node_modules/.pnpm | grep '^@objectstack'
@objectstack+client@17.0.0-rc.0
@objectstack+core@17.0.0-rc.0
@objectstack+formula@17.0.0-rc.0
@objectstack+lint@17.0.0-rc.0
@objectstack+sdui-parser@17.0.0-rc.0
@objectstack+spec@17.0.0-rc.0

阻塞 1 —— 双版本 spec 图

client / core / formula / lint 对 spec 的依赖是精确版本,不是 caret:

@objectstack/client@17.0.0-rc.0  -> spec "17.0.0-rc.0"
@objectstack/core@17.0.0-rc.0    -> spec "17.0.0-rc.0"
@objectstack/formula@17.0.0-rc.0 -> spec "17.0.0-rc.0"
@objectstack/lint@17.0.0-rc.0    -> spec "17.0.0-rc.0"

所以只升 spec 之后:

$ pnpm update -r @objectstack/spec@17.0.0-rc.1
$ # 图里同时存在两份 spec:
spec copies in graph: @objectstack+spec@17.0.0-rc.0, @objectstack+spec@17.0.0-rc.1
client -> sees spec 17.0.0-rc.0
core   -> sees spec 17.0.0-rc.0
formula-> sees spec 17.0.0-rc.0
lint   -> sees spec 17.0.0-rc.0

即 objectui 自己的代码看 rc.1,@objectstack/* 内部看 rc.0。这对本仓特别危险,因为多处 guard 依赖 引用同一性 / 同一份 .d.ts:

• scripts/check-spec-symbol-derivation.mjs 和 spec-symbol-parity.test.ts 都用 createRequire 去解析 spec 的 .d.ts 再过 TS checker —— 拿到哪一份取决于解析顺序。
• spec-subschema-parity.test.ts 明确以引用同一性区分 re-export 与 fork(见 check-spec-symbol-derivation.mjs 头部关于 objectui#3003 的说明);两份 spec 会让 zod schema 对象不再是同一个引用。

结论:spec 不能单独升,必须整个 @objectstack 家族 rc.0 → rc.1 同步升(client / core / formula / lint / sdui-parser 的 rc tag 都已是 17.0.0-rc.1)。

阻塞 2 —— check:spec-symbols 由绿转红

baseline(rc.0):

$ pnpm check:spec-symbols
✅  spec symbol derivation: 1200 files scanned against 4231 spec export names;
    6 declared dialects, 77 untriaged collisions in 18 packages.
$ echo $?
0

升到 rc.1 后:

$ pnpm check:spec-symbols
❌  a spec-named symbol is hand-written, not derived:

    • @object-ui/app-shell declares 1 spec-named symbol the spec already owns:
        interface `InboxNotification`  packages/app-shell/src/layout/inboxGrouping.ts:16
        (exported by `@objectstack/spec/contracts`)

    • @object-ui/types declares 1 spec-named symbol the spec already owns:
        interface `FieldNode`  packages/types/src/data-protocol.ts:226
        (exported by `@objectstack/spec/data`)

    • @object-ui/types lists 1 symbol in DEBT that no longer collide — `JoinNode`.
    • @object-ui/react lists 1 symbol in DEBT that no longer collide — `PerformanceConfig`.
$ echo $?
1

也就是 rc.1 新增了 InboxNotification(contracts)、FieldNode(data)两个导出名,同时移除/改名了 JoinNode、PerformanceConfig。四处都得对账(前两个 import/derive/rename/ALLOW 四选一,后两个从 DEBT 台账删除,--ledger 可重生成)。

另需注意 —— rc.1 收紧了 schema 严格性

rc.1 把一批 zod schema 从 $strip 翻成 $strict(strict 会拒绝未知键,而不是静默丢弃):

subpath	rc.0	rc.1
automation	$strict=0 $strip=160	$strict=19 $strip=152
ui	$strict=3 $strip=286	$strict=6 $strip=287

共约 22 个 schema 变严。以前能通过的元数据现在可能直接抛错 —— 升级 PR 里需要专门验证 automation / ui 侧的解析路径,不能只看编译通过。

建议

单独开一个「@objectstack 家族 rc.0 → rc.1 同步升级」PR,内容至少包括:

1. client / core / formula / lint / sdui-parser / spec 一并升到 17.0.0-rc.1,确认 node_modules/.pnpm 里只剩一份 spec。
2. 处理 check:spec-symbols 的四处对账。
3. 针对 $strip → $strict 的 22 个 schema 做解析回归验证。
4. 按 AGENTS.md「版本号策略」,changeset 标 minor(不要标 major,fixed 组会整组被推走)。

影响

objectstack-ai/objectstack#4562(把 DecisionOutputDef 收敛成 spec 的纯 re-export)被本 issue 阻塞:required 只在 spec rc.1 才被建模,rc.0 没有。在当前解析的 rc.0 下收敛会直接编译失败:

src/utils/decisionOutputParams.ts(128,50): error TS2339:
  Property 'required' does not exist on type
  '{ key: string; label?: string; type?: "text" | "position" | "user" | "department" | "team"; multiple?: boolean; }'.

已备好的改动在分支 claude/issue-4562-decision-output-collapse(在 rc.1 下实测 app-shell tsc --noEmit 全绿),等本 issue 落地后即可开 PR。

---

发现于 objectstack-ai/objectstack#4562 的实施过程中,属于该 issue 范围外,故单独记录,未指派。

🤖 Generated with Claude Code

[os-zhuang]

状态更新 —— #3178 已合并,本 issue 部分过期,核心问题仍在

#3178(feat(deps)!: upgrade to @objectstack/spec 17.0.0-rc.1)已于 2026-08-02 合并。对照上面正文逐条更新:

已失效的部分

• 标题 / 「现状」一节:@objectstack/spec 已不再锁在 rc.0,main 现在解析到 17.0.0-rc.1。

• 阻塞 2(check:spec-symbols 由绿转红):已由 feat(deps)!: upgrade to @objectstack/spec 17.0.0-rc.1 and retire the wait timeout fields (#3101) #3178 一并处理完。当前 main 上:

  $ pnpm check:spec-symbols
  ✅  spec symbol derivation: 1200 files scanned against 4344 spec export names;
      8 declared dialects, 75 untriaged collisions in 18 packages.
  EXIT=0
  

  (对比升级前的 4231 spec export names / 6 declared dialects / 77 untriaged。)

• 「影响」一节:objectstack#4562 不再被阻塞,已开 PR refactor(app-shell): 把 DecisionOutputDef 收敛成 spec 的纯 re-export,并反转 parity pin #3185。

仍然成立 —— 双版本 spec 图(阻塞 1)

这是本 issue 剩下的、也是主要的价值。#3178 只升了 @objectstack/spec,家族里其余包仍是 rc.0,而它们对 spec 的依赖是精确版本,所以合并后的 main 上依旧是两份 spec 并存:

$ ls node_modules/.pnpm | grep '^@objectstack+spec'
@objectstack+spec@17.0.0-rc.0
@objectstack+spec@17.0.0-rc.1

$ # 各包实际看到的 spec:
client  -> 17.0.0-rc.0
core    -> 17.0.0-rc.0
formula -> 17.0.0-rc.0
lint    -> 17.0.0-rc.0

即 objectui 自己的代码看 rc.1,@objectstack/* 内部看 rc.0。上面正文里说明的隐患一字未改地仍然适用:spec-subschema-parity.test.ts 以引用同一性区分 re-export 与 fork,而两份 spec 会让 zod schema 不再是同一个对象;check-spec-symbol-derivation.mjs 与 spec-symbol-parity.test.ts 用 createRequire 解析 spec 的 .d.ts,拿到哪一份取决于解析顺序。

仍然成立 —— $strip → $strict

正文里那张表(automation $strict 0→19、ui 3→6,共约 22 个 schema 变严)描述的是 rc.1 本身的性质,与谁去升无关,因此在 #3178 已经落地的今天依然是需要回归验证的面 —— 只是验证的时机从「升级 PR 里」变成了「已经在 main 上」。

建议的后续

把本 issue 收窄为「把 @objectstack 家族其余包(client / core / formula / lint / sdui-parser)一并升到 17.0.0-rc.1,消除双版本 spec 图」,原「建议」一节的第 1、3、4 条仍适用,第 2 条已由 #3178 完成。

---

发现于 objectstack-ai/objectstack#4562 的实施过程中(PR #3185),顺手更新以免本 issue 变成过期记录。

🤖 Generated with Claude Code

---

Generated by Claude Code

[os-zhuang]

认领:PM 循环第 3 轮(按新升级判据:恢复不变量类——「契约族单版本」——直接派发,不再请示;维护者持否决权)
分支:claude/issue-3182-spec-family-lockstep
Worktree:objectui-issue-3182
范围:client/core/formula/lint(及其余精确钉版的 @objectstack 家族包)补齐到 17.0.0-rc.1、收敛为单一 spec 拷贝、check:spec-symbols 四项对账、$strip→$strict 翻转的解析回归。如另有会话已在做本 issue,以更早的认领评论为准,本认领让行。

---

Generated by Claude Code

[os-zhuang]

PM 验收:ACCEPT → PR #3189(已转正并启用 merge-when-ready,CI 全绿自动入队合并)。

• 单一 spec 拷贝不变量恢复:5 个 package.json 的 range 抬升 + lockfile 刷新,探针证实依赖图仅剩 @objectstack/spec@17.0.0-rc.1 一份(改前 rc.0/rc.1 并存);client/core/formula/lint 全部解析到 rc.1;
• 依赖引用同一性的四个守卫套件定向复跑 71 条全绿;check:spec-symbols 的四处对账经重测确认已由 feat(deps)!: upgrade to @objectstack/spec 17.0.0-rc.1 and retire the wait timeout fields (#3101) #3178 完成,本 PR 零涉及——与 spec-symbol-parity.test.ts 的「编译期」断言从未被编译 —— 整个 tripwire 是哑的 #3181 的 PR 无任何文件重叠;
• $strip→$strict 回归:实测翻严面 automation 11 / ui 23 个 schema,全仓 803 文件 9397 条测试零失败,无「合法元数据被新拒绝」的回归;
• changeset 按 fixed-group 政策记 minor。

过程披露已记录:agent 在资源纪律下达前用过一次 pkill -f vitest(违反 AGENTS.md 服务纪律,事后核验无误伤,已改为 PID 精确操作)——「绝不按进程名杀进程」将显式写入 os-dev 派发规程。

---

Generated by Claude Code