[finding] ResumeFailureReport.code is required, but the docblock tells callers to parse the member with ResumeFailureDetailsSchema, which silently strips it

[os-bill]

ResumeFailureReport.code 是必填,而该类型自己的 docblock 邀请调用方用 ResumeFailureDetailsSchema 去解析这个成员 —— 那个 schema 不声明 code,z.object 解析时会把它静默剥掉。照文档做的人,丢的正是文档说「只有这里才有」的那一个成员。

亲取读数(origin/main,2026-09-13T06:1xZ)

(a) 契约把 code 定为必填,packages/spec/src/contracts/approval-service.ts:617:

code: ErrorCode;

(b) docblock 明确邀请用那个 schema 解析(同文件 :570-580,逐字):

They are inherited here, never re-spelled, so the two cannot drift, and a caller that parses this member with ResumeFailureDetailsSchema reads the same three facts it reads off that door. What this adds is the one member a success envelope cannot leave to its envelope: on the resume door the registered code is the answer's own code; on a success answer nothing else names the failure class, so it rides here as code.

(c) 那个 schema 不声明 code,packages/spec/src/api/automation-api.zod.ts:

export const ResumeFailureDetailsSchema = lazySchema(() => z.object({
  runId: …,
  status: z.enum(['failed','stranded']).optional(),
  repairable: z.boolean(),
}));

⇒ 三段合起来:文档推荐的解析路径,恰好丢掉文档说「非它不可」的那个键。z.object 非 strict ⇒ 不报错、不警告,静默。

为什么这值得一张卡

docblock 自己写了 code 存在的唯一理由:成功信封里没有别的东西命名失败类别。那么一个照它做的消费者,拿到的 resumeFailure 就没有失败类别,而且没有任何信号告诉它丢了东西。⇒ 这不是「文档不够细」,是文档指的那条路把它自己的论点抹掉。

⚠️ 明确未测:有没有真实消费者在这么做。本席只读了契约与 schema,没有普查调用点。⇒ 承接者应先数人口:若无人这么解析,本卡可能只值一条 docblock 澄清;若有,那是真丢数据。

形状,⛔ offered not prescribed

复核给了两条:① 加一个 ResumeFailureReportSchema = details + code: ErrorCodeSchema,让文档能指向一个不丢键的 schema;② 或者加一条钉,把「解析会剥掉 code」这件事钉成已知行为并在 docblock 里说清楚。⛔ 两条都是形状;先数人口再选。

⛔ 不在 PR #17924 里修

那个 PR 是一行 provenance 台账 + changeset。在它里面动 automation-api.zod.ts 的 schema 形状,是把一张一行的卡撑成契约变更 —— 正是复核流程要防的。在档复核(claude-fable-5-1,档位本席从转录核验 86/86)把它判为 note 级、另立卡,本席同意。

出处

由 PR #17924(卡 #17909)的在档复核提出;上面三处读数是本席独立复取的,⛔ 非转述。

查重

600 条最新 issue/PR 标题普查,2026-09-13T06:1xZ:ResumeFailure → 0、resume-failure → 0,同批 contract-review → 6、tier → 7 会命中 ⇒ 邻词点亮,零是读数。⚠️ GitHub search API 本会话不可用(对照词也返回 total: None)。

⛔ 裸卡、未定级 —— 无 domain:*、无 priority:*,二者皆分诊席独有产出;仅预填 type。

---

Generated by Claude Code