spec: route-ledger entry 类型加可选 `responseSchema` 字段(#3877 最小首步,维护者 2026-08-06 已批)

[os-zhuang]

Part of #3877(维护者批文见该单 2026-08-06 裁决评论)。devx 车道 PM 按跨分片协议立单转 spec 座位,未认领。

任务

给 route-ledger entry 类型(5 个 route ledger 共用的条目形状)加可选 responseSchema 字段:

• 只加类型位,不做批量填充——Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 已裁定 Stage C(批量补 ~190 条无声明路由)永不排期;字段随 Stage A 各族落地与路由被触碰时增量填。
• 它把「这条路由声明了什么响应」变成可查询数据,是 Stage D 棘轮的前置;字段缺省即「未声明」,不改变任何现有行为。

验收

• 类型编译过;5 个 ledger 现有条目零改动(字段可选);
• 至少给 discovery 族已落地的 2 条路由(PR feat(spec,runtime,metadata-protocol)!: discovery 两个生产者统一到一个 schema —— capabilities 正名、features/endpoints 退役、scoping 声明 (#4828) #5682 的面)填上引用,作为字段可用性的实证;
• 不引入「声明了但没人验证」的新面——填了 responseSchema 的路由应当已有(或同 PR 补上)feat(spec,runtime,metadata-protocol)!: discovery 两个生产者统一到一个 schema —— capabilities 正名、features/endpoints 退役、scoping 声明 (#4828) #5682 双断言口径的一致性覆盖,否则宁可不填。

关联

#3877(程序卡)、PR #5682(discovery 族一致性测试,双断言口径出处)、#5679(嵌套键同病,Stage D 递归收严时的第一个红)。

[os-zhuang]

打包建议（致 spec 座位）：本单与 #5185（ProvisionEnvironmentResponse 补 hostnameAssignment）、#5767（OWNING_BUSINESS_UNIT_ID 声明同步）同为小型补键/声明同步族，建议同一接力棒内派发，摊薄四步重建 + CI 圈的每单固定成本。背景：维护者 2026-08-06 拍板 spec 车道缩盘方案，见 #5837。

---

Generated by Claude Code

[hotlong]

Release-board audit (maintainer-directed re-audit of non-board domain:spec items, 2026-08-07): adding target:v17 — metadata-protocol change, size S, low-risk: maintainer-approved (#3877 first step) optional responseSchema field on the route-ledger entry type; additive-only, existing entries unchanged, zero behavior change. Maintainer directive: protocol changes land in v17 unless large/risky. Triage seat may veto.

---

Generated by Claude Code

[qq9340100]

认领:PM 循环轮 6(spec 车道并行分拆批次)
会话:session_011M7UwH25Unfi73UHim7ajY
分支:claude/issue-5791-route-ledger-response-schema
Worktree:objectstack-issue-5791
域:domain:spec(跨座位转移单,shared contract surface)
文件面:五个 route ledger 条目类型 —— packages/runtime/src/route-ledger.ts、packages/rest/src/rest-route-ledger.ts、packages/plugins/plugin-auth/src/auth-route-ledger.ts、packages/services/service-i18n/src/i18n-route-ledger.ts、packages/services/service-storage/src/storage-route-ledger.ts + discovery 族 2 条实证填充与其一致性测试、.changeset/。⛔ 不触 packages/spec 源码。越界即停,报告说明。

注:此前评论建议与 #5185/#5767 同棒打包摊薄接力成本 —— 本轮按维护者提速指令改为并行批次单独派发,不与在飞面冲突。

---

Generated by Claude Code

[qq9340100]

验收(ACCEPT):PR #6477 已复核通过,转 ready 并挂 auto-merge 入队。

• 验收三条全部兑现:五 interface 各加同名同措辞可选字段、现有条目零改动;discovery 族两条实证填充且刻意分处两个 ledger;「声明了没人验证」由双层守卫封住(client 侧解析守卫真调 safeParse 防 lazySchema 代理陷阱 + runtime/rest 闭环钉断言身份相等而非仅可解析),外加反空转下界与否定对照实跑。
• 反向验证两条方向先写后跑,均如预测转红;顺带修掉守卫自身一处报错质量问题(map key 缺失时的 chai 参数抱怨 → 点名丢失行)。
• CI 24 项全 success/skipped,门禁 job(ESLint / TypeScript Type Check)结论亲核为 success;mergeable_state: clean。

两处 dev 记录的决策,PM 确认(否决窗口,维护者可一行推翻):

1. responseSchema 取 DiscoverySchema 而非 GetDiscoveryResponseSchema——顺 feat(spec,runtime,metadata-protocol)!: discovery 两个生产者统一到一个 schema —— capabilities 正名、features/endpoints 退役、scoping 声明 (#4828) #5682 已录裁定(前者对生产者有约束力;后者 .partial() + strip 未知键,对着它棘 Stage D 等于把 feat(spec,runtime,metadata-protocol)!: discovery 两个生产者统一到一个 schema —— capabilities 正名、features/endpoints 退役、scoping 声明 (#4828) #5682 刚堵的洞重开)。改判成本:两处 ledger 字符串 + 两处闭环钉期望值。
2. 字段类型 string(spec 导出名)而非 live ZodTypeAny——现场测量逼出的单解(zod 仅 2/5 包可解析、三 ledger 头注释要求 import-free、仓内先例 plugin-rest-api.zod.ts:168 同为字符串);编译期不查名字的弱点由解析守卫补上。

GET /api/v1 bare-base 别名按「无覆盖不填」留空并钉住,解禁条件已写进测试与 ledger 注释——处理正确。

---

Generated by Claude Code