refactor(spec): 三个热点生成物按 category / entrypoint 分片,拆掉合并队列的串行税 (#5837)

[qq9340100]

Fixes #5837

维护者 2026-08-06 已拍板「分片 + 缩盘子」。本 PR 一次性落 S1-S4,不拆多 PR —— 分片布局的中间态(分片产物 + 未改的门禁 / 未改的消费方)在任何提交点都是坏的。

前提复核(在 origin/main 上实测,开工前)

单子的前提	实测	结论
三个文件仍是单体	authorable-surface.json 311KB / 7941 keys、json-schema.manifest.json 49KB / 1610 defs、api-surface.json 157KB / 16 entries / 4391 exports	成立
os-regen 路由现状	.gitattributes 把三者逐个映到 merge=os-regen,单一事实源是 scripts/regen-artifacts.mjs,check:merge-driver 双向对账	成立
schemaNameFromExportKey 的 category 结构	def key 一律 < category >/< Def >[:< prop >];category 就是 build-schemas.ts 迭代的 namespace 小写名,14 个非空	成立

单子诊断的因果也成立且是本 PR 的全部理由:merge=os-regen(#4675)只在本地 git 生效,合并队列在服务端重建 PR 时不跑自定义 merge driver,所以两个都动过这些文件的 PR 在队列里是纯文本冲突。

布局

之前	现在	分片键
packages/spec/authorable-surface.json	packages/spec/authorable-surface/< category >.json	def key 的 category 段(14 片)
packages/spec/json-schema.manifest.json	packages/spec/json-schema.manifest/< category >.json	同上(14 片)
packages/spec/api-surface.json	packages/spec/api-surface/< entry >.json	已发布入口,. → root.json(16 片)

有意维持单体,并各自写了理由:spec-changes.json(按版本键控)、api-surface-signatures.json(1.3KB)、authorable-surface.base.json(见下)。

布局、writer、完整性检查、历史基线读取一处收口:packages/spec/scripts/lib/sharded-artifacts.ts。

保持不变的那条不变量

每道门读的是整个目录、当作一个集合 —— 而不是「这次构建会写的那些分片」。

这是分片保语义的全部依据:删掉一整个分片文件 = 删掉它的 key,checks (a)/(c) 看到的缺失 key 与从前删单体文件里的行时一模一样;没人重生成的分片报陈旧而不是被跳过;#4662 的逐字节规范形式比对现在是逐分片做的,手改因此还能被指名到文件(严格变紧,不是变松)。

分片让两类新违规成为可能,两条都做成硬报错:分片的 category / entry 字段必须与文件名一致;分片里的每一条必须属于该 category。少了它们,一个分片可以替别的 category 背书,而按 category 路由的 writer 会在下一次运行时把它当作「没人做过的删除」丢掉。

锚点(#5304 / #5235 / #5358 / #5370):判据一个字没弱化

authorable-surface.base.json 保持聚合单文件,这是有意的不对称:

• 被分片的三件每个 spec PR 都会重写,那才是队列的串行点;这一件只有人手打 --update-base 才会写(check:authorable-surface 在 --check 模式下也会重写 authorable-surface.base.json —— 一次纯核验会改工作区,且任何无关 PR 都能因此静默推进删除门的锚点 #5358),从不在 churn 路径上,分片买不到任何冲突收益;
• 它的 baseRev 是整个 surface 的一个 commit。逐分片复制会允许出现「不同分片镜像不同 revision」的树 —— 任何上游 commit 都没有过的状态。

它喂的比对改为:读基线 commit 的分片并聚合。authenticity 判据两半原样保留 —— baseRev 是 origin/main 的祖先,且它记录的 keys 就是该 commit 的 surface。--update-base 只许前移(#5370)、MERGE 态拒绝(#5851)的语义未动一行,其 8 例测试在新布局下全绿。

本 PR 重新锚定了一次(⚓ authorable-surface.base.json refreshed to 44106d9e8448 (7941 keys)),原因是它的 description 字面提到 authorable-surface.json 这个即将不存在的路径 —— 而该文件的规范形式检查把 description 的每个字节都算进去(脚本注释里写着「改这段文字不是改注释」)。前移方向已由 assertAnchorMovesForward 自证:fc5f536a13b3 → 44106d9e8448。

历史布局的那一处读取

readShardedKeysAtRev 在给定 revision 早于本次迁移时读单体。这不是消费方宽容:

• revision 是已合入的上游 commit,不可变,没有可以去修的 producer;
• 工作树自己的 surface 由 aggregateCategoryShards 读,它只认分片布局。

与 release-spec-changes.sh 解包「上游 tarball 实际携带的那种形状」同类。该分支会自报家门(ℹ️ … predates the split),并在没有分叉早于迁移点的在飞分支后自行退役。

验收判据 1 的可证明形式:文件级互斥

单 PR 内无法演示合并队列,其机械等价物是关于文件的陈述,那个可测。

实测(在本工作树):给 ui 分类的一个 schema 加一个 key,重跑 gen:schema —

🔑 authorable-surface/ updated (7942 keys) — commit it.
     touched: ui.json

  authorable-surface/ai.json IDENTICAL          authorable-surface/qa.json IDENTICAL
  authorable-surface/api.json IDENTICAL         authorable-surface/security.json IDENTICAL
  authorable-surface/automation.json IDENTICAL  authorable-surface/shared.json IDENTICAL
  authorable-surface/cloud.json IDENTICAL       authorable-surface/studio.json IDENTICAL
  authorable-surface/data.json IDENTICAL        authorable-surface/system.json IDENTICAL
  authorable-surface/identity.json IDENTICAL    authorable-surface/ui.json  ** CHANGED **
  authorable-surface/integration.json IDENTICAL
  authorable-surface/kernel.json IDENTICAL      → 14 片改 1 片(cmp 逐字节)
  json-schema.manifest/*.json  14 片全部 IDENTICAL

在 main 上,同一次编辑重写的是一个 310KB、每个 spec PR 都会重写的文件。

固化为常驻测试 packages/spec/scripts/sharded-artifacts.test.ts(23 例):

• 局部性 —— 只在 category X 内不同的两个 key 集合,序列化出的分片集只有 X.json 不同,其余逐字节相同;两个「PR」触碰的文件集合交集为空;两者的并集恰好等于按 key 并集重生成的结果(该「冲突解决」是 no-op);
• 幂等 —— 同一 key 集合重写:written 为空数组。仅比字节相等不够 —— 重写相同内容仍然会动 mtime,而下游每一处「陈旧吗?」的比较都离一次 mtime 读只有一步;
• 加上路由律本身(category 段、且只有它,选定分片文件)、目录聚合、孤儿分片修剪、三条完整性硬报错、入口分片命名(./root 撞名拒绝)、历史基线读取四向。

生成器的端到端幂等由 check:authorable-surface / check:api-surface 每次 CI 自证(两者重新推导产物并逐字节比对工作树),不在这里重跑一次 7s 的全量构建去重复证明。

ratchet 语义:反向验证,方向先预测后跑

预测的是标准方向(装回违规 → 门变红),三档实测都如预测:

① src 删 key、分片不动 → 红(check (a),silent-strip 类,始终致命)

❌ 1 authorable key(s) disappeared from the contract:
     - ui/RecordPathProps:aria

② 跨分片:单个分片手改藏不住。删 ui/View:formViews 并手删 authorable-surface/ui.json 里那行之后,门在另一个分片上开火 —— 因为 ViewSchema 也经 api/GetUiViewResponse 发布:

❌ 1 authorable key(s) disappeared from the contract:
     - api/GetUiViewResponse:formViews

这条是分片布局独有的加固读数,值得单独记一笔:门读整个目录当一个集合,所以在一个分片里删行不会让另一个分片忘记它。

③ 两个分片的行都手删 → 仍红(check (c),按 merge base 44106d9e8448 判定,该 commit 早于分片,走的正是上面那条历史读取路径):

   removed authorable keys that way with a green gate. Deletions are therefore
   compared against the baseline at merge base 44106d9e8448 with origin/main,
   which this commit cannot rewrite.

一个诚实的补充读数:第一次探针选的 ui/RecordPathProps 事后被门自己判为「不可从 25 个元数据根到达」,于是删除合法地被豁免(证明 2)。那是我选的 key 的性质,不是门的松动 —— 换成可达的 ui/View 后才拿到上面 ② ③ 两条红。这一段没有按模板凑「应当变红」,而是照实记。

#5976 的 def-key 撞名守卫

守卫本身一行未动:撞名按剥后缀的 schema 名(shared/HttpMethod)判定,那才是选定 def key 的东西,与它之后落进哪个分片文件无关;它仍在两个 ratchet 之前运行。

其反向验证测试(def-key-collisions.test.ts,沙箱真跑)有一处必须改,否则会变成空跑:它断言 expect(output).not.toContain('json-schema.manifest.json')(证明守卫在 ratchet 之前退出)。分片后没有任何输出会打印那个字符串,该断言会无条件通过 —— 一个假装成 pin 的 phantom check。改为断言分片目录名,并补了一条正向断言(输出里确实出现 shared/HttpMethod),两条都实跑绿。

S3 消费方普查:零遗漏声明

git grep -n "authorable-surface\.json\|json-schema\.manifest\.json\|api-surface\.json" origin/main 全仓逐条处置。代码读点(全部已改):

读点	处置
packages/spec/scripts/build-schemas.ts	读写两个分片目录;git 基线读取走 readSurfaceKeysAtRev
packages/spec/scripts/build-api-surface.ts	写 api-surface/;--check 读整个目录并新增「字节漂移但导出名没动」的红
packages/spec/scripts/build-docs.ts	readApiSurfaceFrom(API_SURFACE_DIR)
packages/spec/scripts/build-spec-changes.ts	SURFACE 指向目录;--previous-surface 接受目录或单文件(见下)
packages/spec/scripts/root-index.test.ts	改读整个 manifest 目录聚合(读单片会重新引入该测试自己批判的「无可比较」退化)
packages/spec/scripts/check-generated.ts	GATED 表的 artifact 标签
packages/spec/scripts/def-key-collisions.test.ts	见上(否则空跑)
packages/spec/scripts/build-schemas-check-mode.test.ts	沙箱夹具全部改写为分片;45 例全绿
packages/spec/package.json files	api-surface.json → api-surface
scripts/regen-artifacts.mjs	三条路由改 /**,并写下为什么另外三件不分片
.gitattributes	同步(check:merge-driver 双向对账绿)
scripts/check-published-files.mjs	PURPOSE 表键名
scripts/release-spec-changes.sh	按上游 tarball 实际形状解包:api-surface/(本次起)、api-surface.json(protocol 15 起)、两者皆无(15 之前)

MCP spec_changes 工具:实测无需改动 —— 它是 spec-changes.json 的投影,而该文件有意维持单体(单子正文的范围外声明)。仓内 git grep spec_changes 的全部命中是散文/CHANGELOG,零代码读点触及被分片的三件。

docs build:无需改动 —— apps/docs 不读这三件;唯一相关读点是 packages/spec/scripts/build-docs.ts(已改)。

散文提及(按性质分三档处置):

• 活文档,已更新:AGENTS.md(§11 os-regen 表 + 新增一段解释为什么 driver 不够、以及哪三件有意不分片;Post-Task 第 4 条)、.github/workflows/lint.yml 注释、.claude/skills/pm-dispatch/SKILL.md(os-regen 路径清单 + 锚点措辞)、.claude/skills/spec-property-retirement/SKILL.md(退休套件里三处路径)、packages/spec/scripts/lib/{renamed-defs,docs-import-surface}.ts、check-exported-any.ts、check-dual-source-exports.ts、schema-name.test.ts、src/migrations/spec-changes.ts,以及 merge 带进来的 fix(spec): check:docs 不再以 gen:schema 开头,生成交给调用方 (#4723) #6000 那几处(build-docs.ts / check-regen-pending.mjs / check-generated-ledger.test.ts / schema-tree-freshness.test.ts)。
• ADR:只加顶部 Amended 行,不改写决策记录(AGENTS.md [WIP] Add Chinese version of the documentation #13)。ADR-0059 与 ADR-0087 各加一行「paths only — no decision changes」,说明快照现在是目录、判据未变。ADR-0112 只在举例时提到这两个文件名作为「同款生成机制」的类比,是当时的记述,不动。
• 历史叙述,有意不动:src/** 与测试里追述「当年这个 key 怎么出账」的注释(http-server.zod.ts / theme.zod.ts / data-engine.zod.ts / retry-policy.* / notification.test.ts / approval.test.ts / explain.test.ts / interaction-config-retirement.test.ts / alias-table-registry.ts / packages/lint/src/validate-org-axis-red-lines.ts / docs-import-surface.test.ts)、全部 CHANGELOG.md 与 .changeset/*.md、content/docs/releases/(⛔ 从不在代码 PR 里动)、docs/audits/** 与 docs/protocol-upgrade-guide.md / spec-changes.json 里的 rationale 文本(生成物 + 台账,内容是当时的判断)。
• 一处刻意留下的不一致,已作为补充证据评论到 build-docs.ts --update-import-baseline 用 JSON.stringify 写原始字符,与仓内 ASCII 转义编码惯例冲突 —— 每次运行产生 ~275 行纯编码 churn 淹没真实变化 #5990:packages/spec/docs-import-surface.baseline.json 的 _comment 仍写着 api-surface.json。源常量已改,但没有重跑 --update-import-baseline:实测重跑除注释外还会把该文件 137 行的 em-dash 从 — 转义归一化成裸字符(entries 数组逐条不变,已核验),那是 build-docs.ts --update-import-baseline 用 JSON.stringify 写原始字符,与仓内 ASCII 转义编码惯例冲突 —— 每次运行产生 ~275 行纯编码 churn 淹没真实变化 #5990 记的同一处编码 churn。它是手工 ratchet(NOT_DRIVER_MANAGED),在分片 PR 里顺手重写会把 274 行无关归一化混进来。

变更集档位:实测后定 patch

对照 #5967 的先例(openapi.json 因在 exports 里而判 major),实测本 PR 的发布面:

files:   ["dist","json-schema","liveness","prompts","llms.txt","README.md",
          "src/**/*.zod.ts","CHANGELOG.md","api-surface","spec-changes.json"]
exports: . ./data ./system ./kernel ./ai ./automation ./api ./ui ./contracts
         ./integration ./security ./studio ./cloud ./qa ./identity ./shared
         ./openapi.json ./package.json

api-surface           in files: true   | in exports: false
authorable-surface    in files: false  | in exports: false
json-schema.manifest  in files: false  | in exports: false

• authorable-surface / json-schema.manifest:不在发布面(既不在 files 也不在 exports),对外零可见。
• api-surface:在 files、不在 exports。因此它进 tarball,但无法经包的公开接口访问 —— exports 映射不含 ./api-surface.json,require('@objectstack/spec/api-surface.json') 在改动前就已经被 exports 挡住;唯一能读到它的方式是直接按文件系统路径钻进 node_modules,那不是受支持的访问面。对照 fix(spec): openapi 静态产物摘除 built-in 路由段，只保留契约半边 (#5744) #5967:openapi.json 是 major,正因为它在 exports 里,是公开子路径。
• 导出面本身零变化(check:api-surface 实测 0 breaking / 0 added),运行时行为、类型、schema 一律未动。

⇒ @objectstack/spec: patch。changeset 正文写了对外的迁移一句话(改读 api-surface/ 目录、按 entry 合并各分片的 exports,内容逐条相同)。

基底与 os-regen 四步

git fetch origin main 后 #6000(#4723)已合入(b5bdf48),所以 S2 的门禁构成改动是叠在它之上的:merge 唯一冲突就在 check-generated.ts 的 GATED 表,两侧都改了 check:docs / check:api-surface 两行,取并集 —— 保留 #6000 的 readsSchemaTree: 'check:authorable-surface',同时保留本分支的 artifact: 'api-surface/'。

四步纪律照做:主线未动过这三个单体(git log 44106d9..origin/main -- <三件> 为空,#5983 是纯 TS 退休),因此无 modify/delete 冲突;先提交 merge(MERGE 态跑 gen:schema 会被 #5851 守卫拒绝),再 pnpm install --frozen-lockfile + 整体重建(pnpm --filter @objectstack/spec build = gen:schema && gen:openapi && tsup,已含 #5371 要求的 gen:openapi),重建后 git status 为空 —— 合并后的源重新生成产物零 diff。

scripts/ 下的 merge driver 实现按 #4868 复查过:DRIVER_SCRIPT_EXPR 是 "$(git rev-parse --show-toplevel)/scripts/git-merge-regen.mjs",merge 时相对当前 worktree 解析,无写死绝对路径;新加的 readShardedKeysAtRev 同样只用 cwd 相对的 ls-tree + show < rev >:./< path >,不引入绝对路径。

验证(全部前台阻塞执行,持 flock /tmp/os-heavy-verify.lock,NODE_OPTIONS=--max-old-space-size=4096)

merge 后重跑:

$ pnpm --filter @objectstack/spec check:generated
  ✓ check:spec-changes ✓ check:upgrade-guide ✓ check:skill-docs ✓ check:skill-refs
  ✓ check:react-blocks ✓ check:authorable-surface  authorable-surface/ (+ its .base.json anchor) + JSON schemas
  ✓ check:api-surface  api-surface/                ✓ check:docs
  ✓ check:strictness-ledger ✓ check:test-typecheck
✓ All 10 generated artifacts are up to date.

$ git status --porcelain          # 重建之后
                                  ← 空:gen:schema + gen:openapi 在合并后的树上零 diff

merge 前完整跑过一轮(merge 只带入 check-generated.ts 一行 + 散文,已在 merge 后重跑 check:generated):

• pnpm --filter @objectstack/spec test → 325 files / 8319 tests passed(含改写后的 build-schemas-check-mode.test.ts 45 passed 与新增 sharded-artifacts.test.ts 23 passed)
• pnpm --filter @objectstack/spec typecheck → 通过(tsc --noEmit + check:test-typecheck,79 files / 691 errors 的 shrink-only 账本无变化)
• node scripts/git-merge-regen.mjs --self-test → 绿(.gitattributes ↔ regen-artifacts.mjs 9 条路径双向对账 + 真 git 端到端)
• pnpm check:published-files / check:adr-anchors / check:nul-bytes / check:doc-authoring / check:skill-frame-sync / check:docs-audit-scope → 全 OK
• eslint 改动文件 → exit 0
• 分片内容与退役单体逐条相同:surface 7941 keys、manifest 1610 defs、api-surface 16 entries / 4391 exports,三者深比对 identical: true

控制字节:check:nul-bytes OK(5825 个 tracked 文件);改动文件另跑了越过门禁盲区的自扫描 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]',零命中。

对 #5551(C2 首期铺 XParsed,55 文件全量重生成)的影响:变简单

明确回答,因为它是下一轮首单:

• 它是最大单笔受益者,但受益方式不是「它自己的 diff 变小」。55 个文件横跨多个 category,所以三件产物的多数分片都会被它改写 —— 它自己那一单的产物 diff 规模不变。
• 变的是碰撞面的形状:今天它与任何并发 spec PR 的冲突面是「三个单体文件」,即必然相撞;分片后是「同 category 的分片」,于是任何只动它没碰到的 category 的 PR 都能与它在队列里成链。按当前分布,qa(22 keys)、shared(39)、integration(138)、security(140)、studio(156)、identity(186)这些小 category 的单子从此完全不与它排队。
• 另一处直接省力:它会先落在分片布局上,所以不必再为「我的 55 文件重生成把别人的产物 diff 冲掉了吗」做人工核对 —— 未被它触及的 category 分片在 git diff 里逐字节不动,这一点现在有常驻测试兜底。
• 有一个不变的地方要说清楚,免得被读成更强的承诺:同 category 内两个 PR 仍然会撞,那部分仍由本地 merge=os-regen + 四步重建兜。分片缩的是盘子,不是取消了盘子。

未做 / 有意留下

• ⛔ 未碰 packages/spec/src/**/*.zod.ts(两次临时探针都已 git checkout 还原,git status 干净)与 strictness 台账。
• ⛔ spec-changes.json / api-surface-signatures.json 维持单体(单子正文的有意范围外),理由写进了 regen-artifacts.mjs。
• ⛔ 未碰 content/docs/releases/。
• docs/spec-generated-artifact-sharding.md:S4 要求的 docs/ 说明,记录布局、不变量、新增 category 怎么办、那一处历史读取何时退役。

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 6, 2026 4:51pm