`gen:openapi` 的 base spec 用 7 条手写 path 描述路由面,与 rest 真实路由无任何对账 —— 漂移了不会红(#5168 的剩余那一半)

[os-zhuang]

观察类发现,在 #5168(PR 见该单)实施中量到,越范围,未认领。基线:origin/main @ ed0d2aac0。

今天没有用户会撞到(实测未漂移),所以按 #4949 打 finding、不进 pm:queue,严重度交分诊定级。

背景:#5168 只补了「自洽」,没补「对账」

check:generated 自己的收尾行把 gen:openapi 记为无门禁,理由写的是:

{ gen: 'gen:openapi', why: 'the OpenAPI document is generated but no check gate compares it to the routes' }

#5168 补的是产物自洽门(每个 $ref 都要能解析、每个声明的契约 schema 都要真的产出),接在生成器内部、写盘之前。这条 ledger 记的是另一件事——「与真实路由对账」——#5168 没有碰,本单单独记。

事实

packages/spec/scripts/build-openapi.ts 里 generateCrudPaths / generateMetadataPaths / generateDiscoveryPaths 三个函数把路由面手写成 7 条 path:

/api/{object}                  get, post
/api/{object}/{id}             delete, get, put
/api/meta                      get
/api/meta/types                get
/api/meta/{type}               get
/api/meta/{type}/{name}        get
/api/.well-known/objectstack   get

这 7 条是模板;真实 boot 时 packages/rest 的 enrichment 把 {object} 展开成约 199 条 path 并并入声明式端点(#5078 实测)。也就是说模板本身是这份文档描述路由面的唯一事实来源,而它与 packages/rest 的实际路由注册之间没有任何一处代码或测试做对账。

后果是单向静默:rest 侧新增、改名或退役一条内建路由时,base spec 不会自动跟随,也不会有任何门禁发现两边不一致 —— 发布出去的 GET /api/v1/openapi.json 会少描述(或多描述)一条路由,而 pnpm build、check:generated、所有 rest 测试全绿。

当前未漂移:上面 7 条与今天的路由面一致,所以这是休眠缺口而不是在场缺陷。正因为没红过,它也从没被验证过能红。

顺带澄清一个提法(可能影响 #5078 旁注的定级)

#5168 与 #5078 都把 gen:openapi 的缺口顺带描述成「产物是否最新」。实测:packages/spec/json-schema/ 在 .gitignore:61,产物不入库,每次 pnpm build(gen:schema && gen:openapi && tsup)重新生成,并通过 files + exports["./openapi.json"] 随包发布。

因此「最新性门」在这里没有对象 —— 没有入库快照可以相对源码变陈旧。gen:sbom 同理(ledger 自己的 why 就写了它是 release 时产物)。ledger 里 gen:openapi 那条 why 的措辞是准的(说的是 routes 对账),把它读成「最新性」是本仓另外两处旁注的失准点,建议分诊时按「对账」而不是「最新性」来定级。

（与 #5371 不同:那单是 gen:schema 的 rmSync 抹掉 gen:openapi 产物导致 rest 路由测试假红,是产物生命周期问题;本单是内容与路由的一致性问题。）

可能的处置方向(未预设,供分诊)

1. 让 base spec 从 packages/rest 的路由台账(rest-route-ledger.ts,该文件自述「唯一台账行一直是准的」)派生这 7 条模板,而不是手写 —— 单一事实来源,漂移在结构上不可能;
2. 保留手写,但加一条对账断言:模板集合与台账声明的内建路由集合必须双向相等,不等即非零退出。比 1 便宜,但两处仍需各自正确;
3. 判定这 7 条模板是「文档面刻意的简化视图」,把它显式写进注释并降级为不需要对账 —— 若是这个结论,ledger 里那条 why 应当一并改写,否则它会一直宣称一个没人打算补的缺口。

跨包(packages/spec 的生成器读 packages/rest 的台账)是否可接受、以及 1 与 2 之间怎么选,属于契约面的决定,本单不预设。

关联

• 发布出去的 OpenAPI 文档 components.schemas 是空的,而 6 个 $ref 全部悬空 —— lazySchema Proxy 撞上 typeof === 'object' 判据 #5168(自洽门,已修)、GET /openapi.json 有两个属主:rest-server 真serve,http-dispatcher 的 generateOpenApi 分支全仓无实现(ADR-0076 D1 影子重复) #5078、gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371、AGENTS.md Prime Directive chore: version packages #10

[os-zhuang]

分诊轮判级(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-05):晋级并转 cli 队列(摘 finding,域改判 domain:cli)。定向:取 issue 方案 2 的变体 —— 对账断言落 rest 侧(rest 消费 spec 发布的 openapi.json,断言 base spec 模板集合与自家 rest-route-ledger 双向相等)。理由:方案 1(spec 生成器读 rest 台账)的依赖方向是反的(rest 依赖 spec,反向 import 成环),结构上不可取;rest 侧断言方向正确且同样让漂移必红。方案 3(降级为刻意简化视图)不采 —— ledger 的 why 记的就是对账缺口。落点 packages/rest 测试面 → cli 车道按其队列节奏派。

---

Generated by Claude Code

[baozhoutao]

认领 + 方向裁定(PM 会话 session_016FNvXhtSdnEGEfLEsMmvxh,cli 车道)

三个处置方向取 2(对账断言),两轴理由,维护者可否决(veto window,落地前有异议随时叫停):

• 1(从 rest 台账派生模板)否:build-openapi.ts 在 packages/spec,而 rest 依赖 spec —— 让 spec 的生成器读 packages/rest 的台账是构建图倒置,无论走包引用还是裸文件路径都把 spec 的产物耦合到下游包的源码布局上。单一事实来源的收益被依赖方向的代价吃掉。

• 3(降级为刻意简化视图)否:等于把 check:generated 台账里那条 why 宣称的缺口改写成没人打算补 —— 在 fix(rest): 两个端点契约面只宣告匹配器实际会服务的集合 (#5224) #5487 刚确立「faces announce only what the matcher serves」的车道语境下,文档面对路由面的漂移恰恰是要防的那类第二真相源。

• 2 的落点:对账门放在 rest 消费侧(rest 已依赖 spec,可读其导出的 openapi 产物/模板集合),断言 base spec 的 7 条模板与 rest-route-ledger.ts 声明的内建路由集合双向相等,不等即红。spec 侧模板保持手写不动;check:generated 台账中 gen:openapi 那条 why 随门落地更新(缺口已补,不能再宣称无门)。

• 分支:claude/issue-5456-openapi-route-reconcile

• 工作树:../objectstack-5456(os-dev 自建)

• 文件面:packages/rest(新对账测试/门)+ packages/spec 仅限 check:generated 台账那一行 why 的更新与(如需)模板集合的可导出化;与在飞 [17.0-rc2验收] 安全:REST /actions 与 /automation 派发路由缺少匿名拒绝门 —— 未认证调用者可触发 system 提权的 RLS/FLS 绕过写入 #5519(runtime)、OS_STORAGE_ROOT 对任何非默认值不生效:CLI 与设置服务的 env 通道错位,schema 默认值覆盖宿主构造配置(原报「swap 假警告」归因已被 #4096 时间线推翻,警告本身是准确的) #4968(cli commands)、fix(client): 让 client 测试层真的进 tsc,那处 @ts-expect-error 不再是幽灵检查 #5546(client)互不相交。

---

Generated by Claude Code

[baozhoutao]

开工(os-dev,会话 session_016FNvXhtSdnEGEfLEsMmvxh,cli 车道派发)

• 分支:claude/issue-5456-openapi-route-reconcile
• 工作树:../objectstack-5456
• 方向:按 PM 裁定取方案 2 变体 —— 对账门落 packages/rest 消费侧,断言 base spec 的 7 条模板 path 集合与 rest-route-ledger.ts 声明的内建路由集合双向相等;spec 侧仅动 check:generated 台账那条 why(如需,再把模板集合导出为可 import 的形状,不改 7 条模板语义)。
• 先证后改:先证明今天确实无对账(注入漂移 → 现有门禁全绿),再落门,再两个方向各反向验证一次。

---

Generated by Claude Code