`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

[baozhoutao]

进度回报 + 前提复核结论:本单的事实前提不成立,需 PM 裁决(os-dev,session_016FNvXhtSdnEGEfLEsMmvxh)

阶段:前提复核已完成并证伪,映射测绘已完成,对账测试未实现(实现前必须先裁决,见下)。远端还没有分支是因为按规程「先证后改」,而证的结果是不能按原方案改。

结论一句话

issue body 的「当前未漂移:上面 7 条与今天的路由面一致,所以这是休眠缺口而不是在场缺陷」——实测不成立。base spec 的 7 条模板(10 个 operation)没有一条对得上 packages/rest 真实挂载的路由。真实 boot 上,文档里描述的每一条路径都 404。这不是休眠缺口,是在场缺陷。

证据 1:真实 boot(pnpm dev:crm -- --fresh -p 39177,base = origin/main 5acb93add)

GET /api/v1/openapi.json → 200,151 条 path({object} 已按 CRM 对象展开)。逐条探测文档里描述的路径:

/api/crm_contact                       HTTP 404   {"error":"Not found"}     ← 文档展开出来的行
/api/meta                              HTTP 404   {"error":"Not found"}
/api/meta/types                        HTTP 404   {"error":"Not found"}
/api/.well-known/objectstack           HTTP 404   {"error":"Not found"}

/api/v1/data/crm_contact               HTTP 401   {"error":"UNAUTHENTICATED",...}   ← 真实路由(401=路由在,鉴权挡)
/api/v1/meta                           HTTP 401
/api/v1/discovery                      HTTP 200
/.well-known/objectstack               HTTP 200   ← dispatcher 在根上服务,不在 /api 下,也不是 rest 路由

动词也错。文档写 PUT {object}/{id},真实是 PATCH:

PUT   /api/v1/data/crm_contact/xyz   HTTP 405     ← 服务器明确拒绝这个动词
PATCH /api/v1/data/crm_contact/xyz   HTTP 401

也就是说:任何人拿发布出去的 /api/v1/openapi.json 生成客户端,生成出来的客户端每一个数据调用都 404。servers[0].url 被 rest 改写成了请求 origin(http://localhost:39177),路径段一个字没改写——我通读了 registerOpenApiEndpoints 的整条 enrichment(servers 覆写 / {object} 展开 / 声明式端点合并 / info.version 覆写),没有任何一步重写 path 前缀。

证据 2:in-process 枚举(与既有 rest-route-ledger.conformance.test.ts 同一个枚举口径)

RestServer.getRoutes() + 两个 direct-mount registrar = 91 条真实路由,全部在 /api/v1/...;base spec = 10 个 operation,全部在 /api/...。字面比对:0/10 命中。

即使做一次很宽容的临时归一化(补 /v1、必要时补 /data、{x}→:x):

GET /api/{object}                    → MATCH  GET /api/v1/data/:object
POST /api/{object}                   → MATCH  POST /api/v1/data/:object
GET /api/{object}/{id}               → MATCH  GET /api/v1/data/:object/:id
PUT /api/{object}/{id}               → NO MATCH   (真实是 PATCH)
DELETE /api/{object}/{id}            → MATCH  DELETE /api/v1/data/:object/:id
GET /api/meta                        → MATCH  GET /api/v1/meta
GET /api/meta/types                  → NO MATCH   (全仓没有这条路由)
GET /api/meta/{type}                 → MATCH  GET /api/v1/meta/:type
GET /api/meta/{type}/{name}          → MATCH  GET /api/v1/meta/:type/:name
GET /api/.well-known/objectstack     → NO MATCH   (dispatcher 在根上,不是 rest 路由)

7/10 只有在「凭空补两个路径段」之后才对得上,3/10 补了也对不上。

证据 3:反方向也不相等

ledger 的 family 字段正好对应 base spec 那三个生成器:crud 6 条、metadata 17 条、discovery 2 条 = 25 条真实路由,base spec 描述 10 个 operation。即使把对账收窄到「base spec 自称覆盖的三个 family」,反方向仍然差 15 条以上(POST /data/:object/query、/meta/diagnostics、/meta/_drafts、/meta/:type/:name/history|audit|diff|publish|rollback|references、/meta/book/:name/tree、PUT|DELETE /meta/:type/:name …)。

因此「双向相等」在任何读法下都落不了地

• 直接落门 → 今天就红,不可合入;
• 要绿 → 必须改那 7 条模板的内容语义,而派发词明确圈禁了这一条(且这是公共契约变更);
• 折中(带一张 10 行「已知背离」基线,只减不增)→ 等于把一份发布出去、consumer 照着生成客户端会全线 404 的文档正式登记为「有意如此」,与 Prime Directive chore: version packages #10(绝不宣传运行时不提供的能力)正面冲突。

三条都超出我的裁量权,所以我停在这里,不写投机代码。

另外:方案 1 被否的理由在这个新事实下需要复议

派发词否掉方案 1 的理由是「spec 的生成器读 rest 台账 = 构建图倒置」——这个理由本身成立。但还有第四个方向,两席都没考虑过,因为两席都在「模板今天是对的」这个前提下推理:

让 rest 自己产出 built-in 路由那一段。rest 已经在 openapi-endpoints.ts 里产出「声明式端点」那一段了;built-in 路由这一段的唯一属主同样是 rest(ADR-0076,#5078 已用真实 boot 确权)。spec 只保留它真正拥有的东西——components.schemas / info / securitySchemes。

这样:依赖方向是顺的(rest→spec,和今天一样);结构上不可能漂移,连门都不需要;而且顺手解掉一个静态产物解不了的问题——apiPath 是可配置的(api.apiPath ?? api.basePath + '/' + api.version,rest-server.ts:2830),所以 packages/spec 里的静态 JSON 原则上就不可能写对路径前缀,今天写 /api 只是错得更彻底而已。代价:@objectstack/spec/json-schema/openapi.json 单独看不再是一份可直接服务的文档(仓内唯一 runtime consumer 是 rest 自己,已核;scripts/check-published-files.mjs:271 还要它随包发布),以及 CRUD 那几段手写的 parameter/response 文案要搬家(RouteEntry.metadata 已经有 summary/tags 承载位)。

我建议的处置

1. 本单(gen:openapi 的 base spec 用 7 条手写 path 描述路由面,与 rest 真实路由无任何对账 —— 漂移了不会红(#5168 的剩余那一半) #5456)改判为 blocked-by:门要落地,先得决定 base spec 到底该描述什么。
2. 「发布出去的 openapi 文档描述的路由一条都不存在」单独立单(在场缺陷,严重度请分诊定级)——我已查重(含 closed),仓内无同类单:发布出去的 OpenAPI 文档 components.schemas 是空的,而 6 个 $ref 全部悬空 —— lazySchema Proxy 撞上 typeof === 'object' 判据 #5168 是 components.schemas 空、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 是产物生命周期,都不是这一件。
3. 方向裁决请在 A(改模板为具体 /api/v1/...)/ B(模板相对化 + rest 在 serve 期拼 basePath)/ C(built-in 段整体移交 rest 产出,不再需要对账门)之间选;我倾向 C,其次 B,理由见上(两轴:长期架构上它消灭的是第二真相源而不是给第二真相源配保安;AI 写元数据这一侧,派生出来的东西没有写错的机会)。

裁决下来我马上继续。预计:裁 C 约需 1 天(要搬文案 + 改 check:published-files 期望 + 大量测试);裁 A/B 约半天;若坚持原方案 2 + 背离基线,约 3 小时,但我认为它不该被选。

---

Generated by Claude Code