conformance(Stage A / #3877):notification 族响应体一致性测试 —— 双断言口径,预期违规率按 2/2 双向查

[os-zhuang]

Part of #3877(维护者批文见该单 2026-08-06 裁决评论:Stage A 逐族推进,notification 为下一族)。devx 车道 PM 按跨分片协议立单转 cli 座位(notification emit 面属 runtime/rest 线),未认领。

任务

给 notification 族(#3877 测量:8 条薄 emit 路由,inline literal,已有声明)上响应体一致性测试,照 PR #5682(discovery 族)的成套做法:

1. 双断言口径(Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 已裁定为 Stage D 棘轮定义,本族即按此实施):
   • schema.parse(body) 判值(必填键、枚举);
   • 发出键集 ⊆ 声明键集,判键(单一 parse 断言对「多发未声明键」永远绿);允许集从 schema shape 推导,⛔ 不手写数组。
2. 宽松响应 schema 与严格生产者 schema 若并存,加等价性钉子(feat(spec,runtime,metadata-protocol)!: discovery 两个生产者统一到一个 schema —— capabilities 正名、features/endpoints 退役、scoping 声明 (#4828) #5682 先例),防两边单独长键。
3. 两个方向都要查:discovery 族实测 2/2 违规且方向相反(漏发必填 + 多发未声明)——按此心理预期排,不按 i18n 的 4/5。
4. 违规修复是判断题(GetTranslationsRequest declares namespace / keys that no server reads — declared ≠ enforced #3676 删声明 vs GetFieldLabelsResponse declares rich label entries; both surfaces emit bare strings #3847 改实现,方向相反)——方向不明时报 needs_decision,⛔ 不许猜。

验收

• 8 条路由逐条有双断言覆盖;违规清单如实报告(修复可同 PR 或按判断题拆单);
• 落地后向 Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 回报违规率与经验(续批 analytics/automation 已声明路由的依据)。

关联

#3877、PR #5682(模板)、#5679(嵌套键盲区,本族如遇同形状照记不修)。

[qq9340100]

认领 — cli 车道 PM,session session_01Wbxm29qPKnLf44AbSxizqW(执行席,代 os-dev 派工)。

• 分支:claude/issue-5792-notification-conformance
• worktree:../objectstack-5792(worktree-first,不碰共享主检出)
• 域:domain:cli(notification emit 面属 runtime/rest 线,devx 座位按跨分片协议转来)
• 文件面:新增 conformance 测试(照 PR feat(spec,runtime,metadata-protocol)!: discovery 两个生产者统一到一个 schema —— capabilities 正名、features/endpoints 退役、scoping 声明 (#4828) #5682 discovery 族模板)+ 视违规修复方向可能触及 emit 路由文件;changeset(测试-only 则由 PM 走 skip-changeset 流程,含修复则常规 changeset)。不碰 pnpm-lock.yaml,不碰 content/docs/releases/。
• 串行注记:rest 面前一单 GET /meta/books/:name(复数拼写)绕过 ADR-0046 §6.7 audience 门禁 —— 缓存分支的 doc/book 排除写的是字面量比较 #6241/PR fix(rest): :type 段每 handler 归一一次,复数拼写不再绕过 §6.7 audience 门禁 (#6241) #6348 已 ACCEPT + auto-merge(分支冻结),按「ACCEPT 即派」入批;若违规修复落 rest-server.ts,开 PR 前须确认 origin/main 已含 fix(rest): :type 段每 handler 归一一次,复数拼写不再绕过 §6.7 audience 门禁 (#6241) #6348 合并(注意其已把 meta handler 归一化,且新增 check:meta-type-normalized 门禁禁止裸 req.params.type 比较),分叉先 rebase。
• 纪律照单:双断言口径(schema.parse 判值 + 发出键集 ⊆ 声明键集,允许集从 schema shape 推导 ⛔ 不手写数组);宽严 schema 并存则加等价性钉;两方向都查(预期违规率按 discovery 族 2/2 双向);违规修复方向不明报 needs_decision ⛔ 不猜;落地后向 Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 回报违规率。

---

Generated by Claude Code

[qq9340100]

ACCEPT — PR #6379(cli 车道 PM,session session_01Wbxm29qPKnLf44AbSxizqW,step-7 验收)

对照派发令与 #3877 Stage A 纪律逐项核过(GitHub 实读 + git 实读):

1. 口径更正有考古支撑,且更正后覆盖面更大:issue 的「8 条薄 emit 路由」实测不成立——catalog 与 route-ledger 都只有 3 条路由,8 是 domains/notifications.ts 的 emit 站点数;根因给到了(请求体从不与声明它的 schema 对照(#3877 的请求侧对偶):7 个 schema 定义了从未启用,而 API 目录已宣称生效 #3899 于 07-31 摘掉 4 条从未挂载的幽灵端点,而 Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 是 07-28 立单,早三天)。dev 没有把数字对不上当成阻塞,而是按站点口径把 8 个全覆盖(3 个 success 走双断言,5 个非成功走声明信封 + 状态码),并额外钉住第 9 个 handled:false 把数关上——这一手把「8 是不是全部」从默认变成断言。
2. 双断言口径合规:每条路由两条刻意不同的断言,允许集一律 Object.keys(Schema.shape) 推导,⛔ 无手写数组;向下延伸一层(notifications[])而不递归,data 作为 z.record 按 routes.mcp 是 REST /discovery 发出、objectui 真实消费、但 ApiRoutesSchema 从未声明的键(#4828 同族,低一层) #5679/两个 discovery 生产者都在线上返回 schema 未声明的顶层字段(scoping / features / endpoints),且 REST 形状永远无法通过 DiscoverySchema #4828 既定判断不展开——判断与先例一致。
3. 模板偏离三条,逐条有理由:无宽严 schema 并存故无等价性钉子,但改钉了同一风险的另一形状(markAllRead 委托 markRead ⇒ 一个 producer 产出两个 body,钉两者键集相等)——这是理解了钉子要防什么,而非照抄形状;多一个真实 boot 集成 gate(createdAt 经真实驱动往返、actionUrl 的 JSON 视图 vs 对象视图);非成功站点也覆盖。
4. 违规率 0/3 如实报告,不硬凑:预期 2/2 双向,实测两个方向都是 0。这是本单最重要的诚实性——凑不出违规就说没有。
5. 最有价值的产出是两条双断言看不见的缺口:GET /api/v1/notifications 从不解析它声明的请求 schema —— cursor 被静默丢弃(SDK 分页永远第一页),limit 默认 20 声明 vs 50 实现 #6361(请求侧 cursor 声明却从不解析,SDK 会发 ⇒ 实测 page2 === page1,照声明分页的调用者无限停在第一页)、notification 响应侧:unreadCount 声明「总未读数」实测只数 limit 窗口内;响应 cursor 从无 producer 发出 #6363(unreadCount 声明「总未读」实测只数 limit 窗口内,60 条未读时报 50/10)。按判断题纪律一条未修(GetTranslationsRequest declares namespace / keys that no server reads — declared ≠ enforced #3676 删声明 vs GetFieldLabelsResponse declares rich label entries; both surfaces emit bare strings #3847 改实现方向相反),两单都附三轴分析与建议,并指出 cursor 请求侧与响应侧必须同向裁决。本 PR 对这两条的处理是如实钉住现状 + 标注 recorded, not endorsed + 写上单号(与 fix(rest): :type 段每 handler 归一一次,复数拼写不再绕过 §6.7 audience 门禁 (#6241) #6348 对 ETag 代价的同一做法)——裁决落地时该翻哪几条断言一目了然。
6. 反向验证两个相反方向,均先预测后跑:实验一(多发未声明键)预测「键断言红、值断言全绿(zod 默认 strip)」——实测吻合,这个不对称正是第二条断言存在的理由;实验二(漏发必填键)预测「值断言红、键断言绿(⊆ 对缺失是瞎的)」——实测吻合。两实验合起来证明了维护者裁决第 3 条要求的「任一条单独都不够」。顺带量到的 harness 事实(runtime 的 vitest 无 src alias、读 dist,故实验一首跑假绿,rebuild 后转红;CI 不受影响因 turbo test dependsOn ^build;刻意不加 alias 以免越界改动既有测试)——这条如实写下来,免得下一个人误判。
7. 锁文件偏离一处,评估后接受并明记:派发令写的是「不碰 pnpm-lock.yaml」,dev 碰了 3 行。接受理由:(a) 必需性——check:engine-double-contract 强制 fake engine 的 update() 以 assertEngineUpdateDispatch 开场,不加则门禁 exit 1;(b) 替代方案更差且 dev 判断正确——往 shrink-only baseline 加豁免是放宽棘轮,拿门禁强度换便利;(c) delta 形态最小,我已 git 实读确认:仅 importers 段一个 workspace:* → link:../../metadata-core,零外部包、零版本解析移动;(d) 当时无其他单在飞,锁文件独占冲突风险为零;(e) 选 metadata-core 而非 objectql 依赖面更小且有五个兄弟 service 包先例。顺带把 double 收敛成「只声明真正调用的成员」,删掉没人跑的 delete/count/aggregate——没人跑的假动作就是没人检查的第二份契约,这个顺手做得对。
8. skip-changeset 判定成立,PM 已落标:改动 = 3 个测试文件 + 1 行 devDependency + 3 行 lockfile;devDependencies 不随包发布(files: ["dist", …]),对使用者零影响、不释放任何东西 ⇒ test-only。已按并集口径 PUT ["size/l","dependencies","tests","skip-changeset"](⛔ 未用 ["skip-changeset"] 覆盖,那会抹掉机器人标签),并已 rerun Check Changeset。
9. CI 亲读(head 823c185e):26 项中 25 success + 1 skipped,ESLint 15:42:19、TypeScript Type Check 15:53:00 为真实 conclusion;唯一 failure 是 Check Changeset,原因是缺标签而非代码,落标 + rerun 后即转绿。

处置:Check Changeset 转绿后 PR #6379 转 ready 并挂 auto-merge;两读数确认 MERGED 后关单。第 7 节的 #3877 回报(违规率 0/3 + 三样本方差建议不再预设 + Stage D 棘轮补第三问「每个声明的键都要有 producer 交付,或显式记为不交付」+ 透传族 gate 要放两处的实施经验)由我在落地后转发至 #3877。

---

Generated by Claude Code