fix(spec): docs-gen 把 retiredKey() 墓碑渲染成 never,而不是 any (#5606)

[os-zhuang]

Fixes #5606

状态(2026-08-07,解除停放):停放条件已满足 —— #5837 分片随 #6069 落地,spec 座位独占窗口解除。本分支已按解除序列走完:merge origin/main(merge 先单独 commit)→ gen:schema && gen:docs 整体重生成 → 生成页作为独立 commit 提交。下表那条唯一的预期红 check:docs 已清零(本地实测 ✅ 232 generated files in sync with packages/spec)。⛔ 仍保持 draft,转 ready 由 PM 执行。

前提复核(对 origin/main,非引用 issue 正文)

三条都自己量过,前提成立:

1. packages/spec/scripts/lib/format-type.ts 的 formatType() 确实没有 z.never() 分支。

2. 用真实转换器探过墓碑节点,输出向与 io: 'input' 回退向都是同一个形状:

   "heading": { "description": "[REMOVED] …", "not": {} }
   

   无 type / 无 $ref / 无 enum ⇒ 一路落到 return prop.type || 'any'。

3. 页面实例仍在 origin/main:

   • content/docs/references/ui/theme.mdx:130 —— | **fontFamily** | { base?: string; heading?: any; mono?: any } | optional | |,描述列空,两条处方整页不出现。
   • content/docs/references/data/object.mdx:125 与 :199 —— ADR-0049 enforce-or-remove:IndexSchema.type 与 IndexSchema.partial 没有任何 DDL 消费者 #5248 的两处 type?: any(ObjectSchema.indexes / ObjectExtensionSchema.indexes)。

修法

两半都落在 scripts/lib/format-type.ts 内,没有碰 build-docs.ts —— INLINE_KEY_LIMIT 与内联摘要装配本来就住在 format-type.ts 里,所以派单里「可选第二半仅当落点仍在 format-type.ts 时才做」的条件成立(#5837 的 build-docs.ts 读点面未被触及)。

1. { not: {} } → never,置于 formatType() 最前:该节点什么都不接受,后面没有任何分支能比它更具体。准确的 TypeScript(该键 z.input 类型本就是 never),而且不像 any 需要旁边的散文兜底。非空的 not({ not: { type: 'string' } })是普通的否定约束,不匹配,保持原渲染。
2. 内联摘要在计入 INLINE_KEY_LIMIT 之前先剔除墓碑。 摘要格只印前 4 个声明键的 k?: type,压根没有描述列 —— 嵌套的墓碑无处安放处方。退役键已不是可写面,不该占四个槽位之一,更不该把作者必须写的键挤到 … 后面。[spec] 退役 HookContext session.roles —— #4839 双删后零消费方零生产方(ADR-0049) #5050 的「把墓碑挪到 shape 底部」规避办法覆盖不了这一类:ADR-0049 enforce-or-remove:IndexSchema.type 与 IndexSchema.partial 没有任何 DDL 消费者 #5248 把 IndexSchema 退役到只剩 3 个活键,上限为 4 时第一个墓碑在数学上必然进摘要。

渲染变化(单测里钉住的,且已由本轮重生成逐字兑现):

位置	之前	之后
Typography.fontFamily	{ base?: string; heading?: any; mono?: any }	{ base?: string }
ObjectSchema.indexes	{ name?: string; fields: string[]; unique?: …; type?: any; … }[]	{ name?: string; fields: string[]; unique?: … }[](无 …,摘要已完整)
Theme.animation 等自有表行的墓碑	类型格 any	类型格 never(描述列 [REMOVED] 处方原样保留)

测试与反向验证

新增 packages/spec/scripts/format-type.test.ts 两个 describe 块,共 8 个 case。

• 全量:pnpm --filter @objectstack/spec test → 325 files / 8316 tests passed。
• 定向:npx vitest run scripts/format-type.test.ts → 1 passed / 27 tests passed。
• pnpm --filter @objectstack/spec typecheck → 绿(check:test-typecheck OK;79 file / 691 error 的既有 debt 账本未增未减)。
• npx eslint 两个改动文件 → 退出码 0。
• node scripts/check-nul-bytes.mjs → OK(5779 个 tracked 文本文件);另按扩面自扫 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' 三个改动文件,无命中。

反向验证(实测,两半分开做;方向都是常规的「还原缺陷 → 新钉子变红」,因为这些断言的是修复产出的肯定渲染,不是「某个发现消失」):

• 注释掉 isNeverNode 前置返回 → 3 failed | 24 passed,三条红分别报 expected 'any' to be 'never' 与 expected 'any[]' to be 'never[]'。第一块里第 4 个 case 故意保持绿:它断言的是非 never 的渲染(非空 not 的越界护栏),所以是护栏不是死钉。第二块整体保持绿 —— 这是两半彼此独立的诚实信号:把墓碑从摘要里滤掉,与它本来会渲染成什么无关。
• 还原该返回、把摘要改回不过滤的 Object.keys(prop.properties) → 4 failed | 23 passed,四条红全在第二块,报出只做第一半会发布的中间态:{ base?: string; heading?: never; mono?: never }、{ dead1?: never; a: string; dead2?: never; b?: string; … }、{ x?: never; y?: never }。比 any 安全,但仍在拿读者的四个槽位养没人能写的键。

两次实测的数字与红行签名都写进了测试文件的块注释,不用重跑就能读到。

✅ 解除停放:content/docs/references/** 整体重生成(已完成,2026-08-07)

停放期间挂着的那半件事,本轮补齐。序列严格按解除条件执行:

1. git merge origin/main —— 无冲突(本分支只碰 format-type.ts + 其单测 + changeset),merge 单独 commit 在先(fix(spec): --update-base 只许锚点前移,MERGE 态与倒退一律拒绝 (#5370) #5851 MERGE-state 守卫 / os-regen 驱动指示的 gen:schema 在 merge 未 commit 时运行,会把 authorable-surface 锚点倒退回旧 merge-base —— 生成器写入、门全绿、静默撤销 main 的锚点推进 #5370 anchor 回归)。
2. pnpm --filter @objectstack/spec gen:schema —— 本座位未被权限系统拒绝,正常跑完(✅ Successfully generated 1622 schemas)。它同时物化了 gitignore 掉的 json-schema/ 树(1611 个文件)与分片产物。
3. pnpm --filter @objectstack/spec gen:docs —— ✅ Generated 232 files。
4. 生成页 content/docs/references/** 作为独立 commit 提交(⛔ 全程没有对生成页做任何文本合并 / 手改)。

重生成 diff 的量与形(逐条实测):

项	实测
变更页数	30 个 reference 页
变更行数	117 行(117 insertions / 117 deletions,全是逐行替换;无增删文件)
逐键墓碑表行	101 行,类型格 any → never;其中带 [REMOVED] 处方的 = 101,即处方无一丢失(反向核对:never 行里不带 [REMOVED] 的 = 0)
内联摘要格	16 行,墓碑在计入 INLINE_KEY_LIMIT 前被剔除
落在 content/docs/references/ 之外的改动	0
三个热点分片产物(authorable-surface/、json-schema.manifest/、api-surface/)	byte-identical —— gen:schema 跑完后 git status 对这三个目录全空,post-#6069 分片写入器无一片 CHANGED

派单里最要紧的那条「分片产物必须干净」是独立核过的:gen:schema 之后整棵树 git status --porcelain 返回 0 行,gen:docs 之后也只有 30 个 references 页。#6069 的分片与本单零交集,这点从实测面而不只是推理面成立。

归因探针(先声明预期方向,再跑): 30 页里有多少是本单渲染器改动、有多少是 main 上本来就漂的?预期 —— 若 origin/main 的生成页本就同步,则把 format-type.ts 换回 origin/main 版本再跑一次 gen:docs,content/docs/references/** 应当逐字节回到 origin/main(diff 全空)。实测正是如此:

$ git checkout origin/main -- packages/spec/scripts/lib/format-type.ts
$ pnpm --filter @objectstack/spec gen:docs      # ✅ Generated 232 files
$ git diff --stat origin/main -- content/docs/references/
(空)

⇒ main 侧零漂移,30 页 / 117 行 100% 归因于本单的渲染器改动。探针跑完已把两边都还原回本分支状态(git status 干净)。

兑现 PR 上文那张渲染变化表(从真实 diff 里摘的):

- | **typography** | `{ fontFamily?: object; fontSize?: any; fontWeight?: any; lineHeight?: any; … }` | optional | Typography settings |
+ | **typography** | `{ fontFamily?: object }` | optional | Typography settings |
- | **fontFamily** | `{ base?: string; heading?: any; mono?: any }` | optional |  |
+ | **fontFamily** | `{ base?: string }` | optional |  |
- | **indexes** | `{ name?: string; fields: string[]; unique?: boolean \| 'global' \| 'organization'; type?: any; … }[]` | optional | Database performance indexes |
+ | **indexes** | `{ name?: string; fields: string[]; unique?: boolean \| 'global' \| 'organization' }[]` | optional | Database performance indexes |

逐键表行的处方原样保留,例:

+ | **tools** | `never` | optional | [REMOVED] `agent.tools` was removed in @objectstack/spec 17 (#3894) — use `skills`. … |

预期红(已清零 ✅)

检查	原签名	现状
TypeScript Type Check 作业内的 Check generated reference docs are in sync with the spec(pnpm --filter @objectstack/spec check:docs,.github/workflows/lint.yml:616)	content/docs/references/** 与新渲染器的产出有差异	已清零 —— 生成页已随本轮 commit 补齐。本地实测:✅ 232 generated files in sync with packages/spec,退出码 0

停放期间这条红的成因(存档):CI 里 check:authorable-surface 会先生成 json-schema 树,check:docs 再拿它重渲染并逐字节比对;渲染器变了而生成页没跟着变,必红。初版正文把它挂在 ESLint 作业下是错的,check:docs 落在 typecheck: job 里(lint.yml 第 616 行),已于停放期间自我更正。

至此本 PR 不再有任何已声明的预期红。 除下节平台签名外的任何红都应当当成真问题处理。

本轮解除停放的完整验证(全部前台阻塞跑完,真实输出)

命令	结果
pnpm --filter @objectstack/spec check:docs	✅ 232 generated files in sync with packages/spec(退出码 0)—— 预期红清零点
pnpm --filter @objectstack/spec check:generated	✅ All 10 generated artifacts are up to date.(10/10 全绿,含 check:api-surface 与 check:docs)
npx vitest run scripts/format-type.test.ts	✅ Test Files 1 passed (1) / Tests 27 passed (27)
pnpm --filter @objectstack/spec test(merge 后全量复跑)	✅ Test Files 326 passed (326) / Tests 8340 passed (8340)(较停放前 325/8316 增加的 1 file / 24 tests 来自 merge 进来的 #6069 sharded-artifacts.test.ts)
pnpm --filter @objectstack/spec typecheck	✅ 绿;check:test-typecheck OK,debt 账本 79 file / 691 error 未增未减
npx eslint 两个改动源文件	✅ 退出码 0
node scripts/check-nul-bytes.mjs	✅ OK(5835 个 tracked 文本文件,无裸控制字节);另对 33 个改动文件扩面自扫 [\x00-\x08\x0b\x0c\x0e-\x1f\x7f],无命中

一个值得记下的过程坑(非缺陷):新 worktree 里首次跑 check:generated,api-surface/ 报 stale;实际是 gen:api-surface 读 packages/spec/dist/index.d.ts,而新 worktree 从未 build 过(Could not resolve module symbol for . … Is the package built?)。这正是 AGENTS.md §9 的陈旧产物陷阱。pnpm --filter @objectstack/spec build 之后复跑即 10/10 全绿,不是 main 上的真漂移,也未产生任何 api-surface 改动。

平台故障(停放期间的红,非本 PR;存档)

GitHub Actions 自 2026-08-06 15:42Z 起平台级故障(runner 引导 503)。停放期间本 PR 上除 check:docs 外的全部红/取消都是这一签名,已由 PM 验签:

• Failed to resolve action download info. / Service Unavailable(annotation 逐字相同):Auto Label、Build Core、Check PR Size、Console Pin Gate、Flag docs affected by code changes。
• 作业零步骤即被取消(同一故障,连步骤都没起来):ESLint、Console Pin Freshness、Spec property liveness、filter。
• 绿:Check Changeset、No other open PR may claim the same issue、Dogfood Regression Gate (1/3)、(3/3)、Vercel Preview Comments。

Auto Label 被这场风暴打掉,导致本 PR 停放期间零标签;本轮 push 会重新触发。

停放(已解除 ✅)

• 停放:等待 spec 生成物按 category 分片：拆掉三个单体 ratchet 文件的合并队列串行税（维护者 2026-08-06 已拍板） #5837(spec 生成物分片)落地且 spec 座位独占窗口解除 → 条件已满足:spec 生成物按 category 分片：拆掉三个单体 ratchet 文件的合并队列串行税（维护者 2026-08-06 已拍板） #5837 随 refactor(spec): 三个热点生成物按 category / entrypoint 分片,拆掉合并队列的串行税 (#5837) #6069 今日落 main,窗口解除。
• 解除后最后一轮 merge origin/main(先 commit merge,再重跑 gen:docs 整体重生成 —— ⛔ 生成页不做文本合并) → 已执行,见上节。
• 剩余动作:PM 转 ready(⛔ 本座位不自行 flip)。

关于 changeset

写了真 changeset(.changeset/docs-gen-retired-key-never.md,@objectstack/spec patch),没有走 skip-changeset。理由:本 PR 改的是读者可见的产物。reference 页是升级作者(尤其 AI 作者,ADR-0033)的主要输入面,heading?: any → 键从页面上消失、type?: any → type 从摘要里消失,是升级者会直接撞上的表述变化;而 skip-changeset 的适用面是「test-only / workflow-only / .claude/-only,什么都不发布」。本 PR 不属于那一类。改动虽然只落在 scripts/,但它是生成器,产物是发布面的一部分 —— 本轮重生成把这 30 个页面实际提交进来,这条判断被进一步坐实。Check Changeset 已绿。

对 #5729 的定价(派单要求的回答)

答:变简单(easier),而且是同文件同函数的相邻分支。

字面量加引号发生在 format-type.ts,不在 build-docs.ts:

if (prop.enum) {
  return `Enum<${prop.enum.map((e: any) => `'${e}'`).join(' | ')}>`;
}

if (prop.const !== undefined) {
  return `'${prop.const}'`;
}

两处都无条件套单引号,不看 typeof e / typeof prop.const,所以 z.literal(2) 印成 '2'、数值字面量联合印成字符串型 —— 这就是 #5729。build-docs.ts 里唯一用到 const 的地方是 union options 段的 **Type:** \${variant.properties.type.const}``(反引号,不加单引号),不参与本类缺陷。

对 #5729 的具体影响:

• 落点已锚定:参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 的修法就是给这两个分支加类型判别(数字 / 布尔 / null 不加引号),不需要再花一轮去找它住在哪。
• 测试载体已就位:format-type.test.ts 现在有现成的 fixture 惯例与断言风格,参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 直接加一个 describe 块即可。
• 生成页重生成的账已经摊过一次:参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 同样要整体重生成 content/docs/references/**,与本 PR 完全同一套流程。本轮已实测确认该流程在普通座位上可跑通(gen:schema 未被拒),参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 不必再为这一步预留不确定性。
• 唯一的代价是排队:两单改同一个函数,叠在一起 diff 会互相埋掉(这正是 gen:docs 把数组内的 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键 —— #4001 战役每个 open 分类站点都会复发 #4912 / gen:docs 给「元素是联合类型」的数组少了括号,164 处参考页单元格声明了另一种类型(string | number[] ≠ (string | number)[]) #5338 当年分开落的理由),所以 参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 应当串行排在本单之后,而不是并发。

⛔ 本 PR 不顺手修 #5729 —— 它是独立单,且正文明确要求墓碑这一单不搭车。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 12:52am

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅

[os-zhuang]

CI 红分诊(PM 座位,会话 session_014wsZeReNTqiceBfLb5Pyf5,01:0xZ):解除停放推送(1c8c497)后 Test Core (2/3) 唯一失败 = datasource-pool-support.test.ts「sqlite WITHOUT a pool still builds」——在案 flaky #6044 第 4 例(与本 PR 渲染器改动零交集,同 shard 其余 12 文件全过)。按台账原样重投(run 收尾后执行),⛔ 不改代码。预期红(check:docs)是否已随重生成清零以本轮全量 CI 结论为准。

---

Generated by Claude Code