gen:openapi 产物被运行时读盘但无任何门禁——缺失时 /openapi.json 静默 503,check:generated 自报「Generated but ungated」

[os-zhuang]

观察类记录(finding),发现于 #5679 实施过程(PR #5743),按 Prime Directive #10 单独登记,未在该 PR 内处理。

事实(全部实测)

1. check:generated 自报:「Generated but ungated (2): gen:openapi, gen:sbom — nothing verifies these are current」——工具链自己声明这两个生成器无新鲜度校验。
2. 其中 gen:openapi 的产物 packages/spec/json-schema/openapi.json 是 gitignore 的、且被运行时读盘消费:packages/rest/src/rest-server.ts:3388 的 /openapi.json 路由在请求时从磁盘读取该文件。
3. 缺失时的失败形态是静默 503,不是构建期报错。实证:routes.mcp 是 REST /discovery 发出、objectui 真实消费、但 ApiRoutesSchema 从未声明的键(#4828 同族,低一层) #5679 实施期间 check:authorable-surface 重跑 build-schemas.ts(不含 gen:openapi)清掉了该文件,packages/rest 随即 8 条 OpenAPI 用例以 503 判红——失败形态与「你的改动弄坏了什么」无法区分,定位耗时后才确认是生成顺序副作用(gen:openapi 重跑即恢复 755/755)。
4. CI 的 build 序列(gen:schema && gen:openapi && tsup)目前顺序正确,所以线上未爆——该缺口是潜在的:任何单跑部分生成器的本地/脚本路径都会复现。

为什么值得记

• 一个被运行时消费的产物没有「是否新鲜/存在」的门禁,违反本仓 check-generated 机制自己的完备性主张(该机制的价值正在于「生成物不新鲜必被机器发现」);
• 失败形态(运行时 503)与根因(构建期产物缺失)相距两层,已经造成一次真实的误诊成本(见上第 3 条)。

相邻工作

gen:sbom 同报无门禁,但无运行时消费者,严重度不同。与 #5040 / #5078(check-generated 机制族)相邻,修法大概率是给 check:generated 补两条 freshness/existence 条目或把 openapi.json 改为 build 产物内嵌。

不预设修法,交分诊分级。

[claude]

分诊(发现分诊轮,#4949 纪律):持有(留 finding),补域标签 domain:spec。

• 域锚定:落点是 packages/spec/scripts/(生成链)与 check:generated 的门禁清单 —— 按域表「packages/spec 及其生成物」⇒ domain:spec。与同族已入队单同一座位,避免两个座位各修一半。
• 收敛(查重结果):gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371(已 pm:queue + domain:spec)与本条是同一现场的两个半边,派发入口只保留 gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 一个。gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 修的是「gen:schema 的 rmSync(OUT_DIR) 顺手抹掉 gen:openapi 的产物 ⇒ rest 的 openapi 路由测试 503 假红」;本条要的是「一个被运行时读盘的产物缺一道 freshness / existence 门禁」。两者根因相邻但不是同一处改动,故不关 duplicate,改为交叉链接 + 排序。
• 过时前提检查(origin/main f205c32 实读):packages/spec/scripts/build-schemas.ts:137 的 fs.rmSync(OUT_DIR, { recursive: true, force: true, … }) 仍在,清场行为未变 —— 两条的前提都还成立。
• 重启条件:gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 落地后复看 —— 若它采用「各生成器只清理自己的输出」这条最小修法,gen:openapi 产物仍然无门禁(check:generated 自报的 "Generated but ungated" 不变),届时本条晋级 pm:queue;若它顺带把 openapi.json 纳入 check:generated,本条即可关闭(not planned)。
• 不合并的理由:gen:sbom 同报无门禁但无运行时消费者,严重度不同 —— 门禁那一半的作用域比 gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 大,不该塞进 gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 的 PR 里顺手扩。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-zhuang]

存量裁决轮（维护者 2026-08-06 委托，session_01LeEfA7CFwbJb7JJmXm2KM3）：维持持有，补一条边界记录防误关——#5837（生成物分片方案）只拆三个单体 ratchet 文件（authorable-surface / manifest / api-surface），不覆盖 openapi.json 的 freshness/existence 门禁，不构成对本单的收编。派发入口仍收敛在同现场的 #5371（open、pm:queue 未派发）：其落地后复看——门禁仍缺则晋级、已顺带纳入 check:generated 则关闭。

---

Generated by Claude Code