投影类生成物是否该退出仓库 —— 分清「记忆」与「投影」,前者必须留在 PR 粒度,后者可以 CI 重算

[os-zhuang]

起因

v17 收尾期 spec PR 密集,packages/spec 的生成物反复冲突(实测三次,详见 #4675)。维护者提出:这批文件是不是该在发布窗口统一生成,或者干脆不进仓库?

结论:这批文件不是一类东西,两类的答案相反。混在一起处置会破坏门禁。

分类

A. 记忆类 —— 必须留在仓库,且必须是 PR 粒度

文件	体积
dual-source-exports.baseline.json	2 KB
docs-import-surface.baseline.json	8 KB
react-declaration-parity.baseline.json	1 KB
authorable-surface.json	315 KB

它们的功能就是「上一次长什么样」。不提交 = 没有比较基准 = 门禁不存在。authorable-surface.json 自己的文案写着:

An unrecorded key is invisible to this ratchet forever after — it can only detect the disappearance of something it once saw.

推迟到发布窗口生成会直接破坏它们,理由不是性能而是归因:发布那天发现少了 N 个 key,无法归因到哪个 PR;而 ADR-0087 要求的 tombstone 升级处方必须由当时那个作者写 —— 只有他知道这个 key 为什么走、该改成什么。人散了处方就写不出来。#3733 正是没人在 PR 当场拦住才发生的。

B. 投影类 —— 可以退出仓库

文件	体积	生成自
api-surface.json	157 KB	gen:api-surface(readsDist)
spec-changes.json	55 KB	gen:spec-changes(conversion/migration 登记表的投影,ADR-0087 D4)
docs/protocol-upgrade-guide.md	—	gen:upgrade-guide(spec-changes 的投影)
content/docs/references/**	—	gen:docs

从源码任何时候都能重算,提交只为 review 可见性。

仓里已有的两处先例

1. packages/spec/json-schema/ 已经 gitignore(.gitignore:61),只提交 json-schema.manifest.json 当记忆 —— build-schemas.ts 的注释明说:「json-schema/ itself is a gitignored build artifact, so this file is the durable "last time"」。这正是本单要推广的形状:产物不进仓,记忆进仓。
2. release notes 集中在发布时写(CLAUDE.md ⛔ 规则),理由与本单起因一字不差:每个 PR 各加一行会把它变成全仓最热的冲突磁铁。

第 2 条同时划出了分界线:发布窗口生成对「摘要」有效,对「记忆」失效。

建议

投影类 gitignore,CI 重算并校验(check:generated 的对应项改为「生成后比对源码一致性」而非「比对已提交文件」)。

必须先解决的代价 —— review 可见性。 提交生成物的真实价值是 diff:

• PR feat(spec)!: 双源 C4 收敛 — Session 归 ./api,./identity 侧死删 (#4641) #4643 的 diff 直接暴露了它手删 authorable-surface.json 里 10 行 identity/Session:*(见 authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650);
• PR feat(spec)!: 双源 C5 收敛 — ActivationEventSchema 归 ./kernel 结构化形状,./studio re-export (#4653) #4662 的 diff 让我一眼确认它只有 +2 行、零删除;
• api-surface.json 的 diff 是 review 时看「这个 PR 动了哪些公开 API」的唯一现成入口。

去掉这些 diff 就等于把审查手段拿掉。替代方案必须先落地,例如门禁把 delta 打进 CI 输出或 PR 评论(+3 / -13 authorable keys,并列出具体 key)。没有替代方案就不要动。

按此,authorable-surface.json 即使抛开「记忆类」身份也应当留在仓库 —— 它的 diff 就是审查机制本身。

范围与顺序

• 本单不适合发布期做 —— 动 CI 和 review 习惯,建议排在 v17 之后。
• 立刻能缓解冲突的是 spec 生成物没有 merge driver:两个 PR 各改几行,语义上是集合运算,却每次都打成文本冲突 #4675(merge driver),窄、安全、不影响可见性,建议先做那个。
• 本单的前置是「review 可见性替代方案」的设计;没有它,本单不应开工。

关联:#4675(merge driver,先做)、#4650 / #4663(基线手编漏洞)、#4535(触发本讨论的双源清账流水线)、ADR-0059 §5、ADR-0087

[os-zhuang]

优先级更正:本单才是对合并队列有效的那个

立单时我把 #4675(merge driver)排在本单前面,理由是它窄、快、发布期安全。那个排序错了一半,更正如下(#4675 已同步更正)。

.gitattributes 的自定义 merge driver 需要 git config merge.<name>.driver 才能生效,而那是本地配置、不随仓库提交 —— GitHub 服务端合并(合并队列、Update branch、squash)不执行它。所以 #4675 消除的是本地返工,不是队列弹出。

实测(2026-08-02):PR #4670 解决完与 #4664 的冲突、全绿入队后,仍被队列以 MERGE_CONFLICT 弹出,因为期间 main 又前进了 #4668、#4660。

本单直接缩小冲突面,对队列有效。 以 #4670 的 6 个冲突文件为例:

文件	类别	本单落地后
packages/spec/api-surface.json	投影	✅ 消失
packages/spec/spec-changes.json	投影	✅ 消失
docs/protocol-upgrade-guide.md	投影	✅ 消失
content/docs/references/**	投影	✅ 消失
packages/spec/authorable-surface.json	记忆	❌ 保留(必须)
src/conversions/registry.ts、src/migrations/registry.ts	手写	❌ 保留(冲突要人看)

6 → 3,且剩下的三个冲突频率远低于投影类(登记表只在真加条目时冲突,authorable-surface.json 只在两个 PR 都动可作者化面时冲突)。

本单的前置(review 可见性替代方案)不变,仍不建议发布期开工 —— 但它在收益排序上应排在 #4675 之前。

---

Generated by Claude Code