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

[claude]

Findings triage (#4949 discipline): hold — finding retained, domain:spec unchanged. Restart condition hardened with an exit (see §3), because the current one has no deadline and its blocker has not moved in two days.

1. Stale-premise check — every claim re-read on origin/main @ ee3bde1

• gen:openapi still has no freshness or existence gate. packages/spec/scripts/build-openapi.ts:150 says so in the tree itself — "gen:openapi still has no staleness gate (check:generated …)" — and packages/spec/scripts/lib/openapi-self-consistency.ts:8–:10 repeats it: "one of the two completely ungated generators in the repo … Ungated in BOTH senses."
• The runtime consumer is unchanged: packages/rest/src/rest-server.ts still serves /openapi.json from the on-disk artifact (:3182, :3214, and the missing-authority path at :3354).
• The upstream cause is unchanged: packages/spec/scripts/build-schemas.ts:285 still does fs.rmSync(OUT_DIR, { recursive: true, force: true, … }).
• ⚠️ Do not read the openapi self-consistency check as coverage of this. openapi-self-consistency.ts (from the 发布出去的 OpenAPI 文档 components.schemas 是空的,而 6 个 $ref 全部悬空 —— lazySchema Proxy 撞上 typeof === 'object' 判据 #5168 family) asserts the document is internally coherent when it exists; it says nothing about whether the file is present or current, which is precisely the gap here. Its own header names the gap rather than closing it.

2. Blocker status

The restart condition is "#5371 落地后复看". #5371 has not landed — still open, pm:queue + domain:spec-tooling, unassigned and never dispatched, filed 2026-08-05. So the condition is literally unfired and the hold stands this round.

3. Why the condition needs an exit, and what it now is

Two facts make the existing condition weaker than it reads:

• The two landing sites are disjoint files. gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 lands in packages/spec/scripts/build-schemas.ts (the rmSync clean-up); this one lands in the gate list in packages/spec/scripts/check-generated.ts:235 (where the gen: 'gen:openapi' entry already sits, gate-less). There is no same-file serialization between them. The real dependency is weaker and one-directional: if gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371's fix happens to enrol openapi.json into check:generated, this becomes moot.
• "Wait for a queued item nobody has claimed" is an open-ended hold. gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 has sat dispatchable for ~2 days. Waiting on it indefinitely is the negative-interest storage pm-dispatch / os-dev：发现类 issue 纪律——立单前查重、就近归挂 sub-issue、finding 分级与批量分诊出水口 #4949 warns about.

Restart condition (replaces the previous one):

1. gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 lands → re-check as before: gate still absent ⇒ promote to pm:queue; enrolled incidentally ⇒ close (not planned). Or
2. gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 is still open and undispatched at the second findings round from now → promote this issue independently. It is not truly blocked — different file, different change — and the gate half has the larger blast radius of the two (the filing is explicit that gen:sbom shares the "ungated" self-report but has no runtime consumer, so the gate work must not be smuggled into gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371's PR as a rider).

Whichever fires first. Boundary note from the previous grading, still true and still worth keeping visible: #5837 (generated-artifact sharding) covers only the three monolithic ratchet files and does not absorb this.

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

---

Generated by Claude Code