spec 双源清账 C8:RetryPolicy / RetryPolicySchema(./automation ≠ ./system)—— 2 条

[os-zhuang]

#4535 的 C8 簇,v17 收口四簇之一。基线行:

RetryPolicy       — [./automation (type)]  ≠ [./system (type)]
RetryPolicySchema — [./automation (const)] ≠ [./system (const)]

⚠️ 本簇与 C5 / C6 的关键区别:它真的在作者面上

C5 / C6 的两侧都不从 BUILTIN_METADATA_TYPE_SCHEMAS 可达,所以它们的可作者化 key 是过度收集产物,vanish 只是形式上的。C8 不是 —— 静态引用图复算确认 RetryPolicySchema 从元数据根集合可达(automation 侧经 control-flow.zod.ts 的 retry: 进 FlowSchema)。

后果:本簇任何可作者化 key 消失都是真的会静默剥离作者写的值(schema 非 .strict(),Zod 直接吞)。tombstone 要求是实打实的,不是形式主义。可作者化 key:automation 5 / system 3(自行复核)。

已知线索(开工请自行验证,不要采信)

• automation/control-flow.zod.ts:179 export type RetryPolicy = z.input<typeof RetryPolicySchema>;:194 retry: RetryPolicySchema.optional()(try 区域)。
• system/worker.zod.ts:94 另有一个同名不同物的 TaskRetryPolicySchema(:152 retryPolicy:)—— 注意别把它和 system 侧真正的 RetryPolicySchema 搞混,后者声明点要自己找。
• 两侧 key 数不同(5 vs 3)说明形状不是简单同构,收敛方向要选得让并集存活,或对被丢的键走完整 ADR-0087。

纪律(#4535 §1–§4,开工前必读)

1. 默认路线:收敛 + re-export。 优先选让两侧 key 并集存活的方向 —— 不删 key 就不需要 tombstone。
2. 若必须丢键 ⇒ 完整 ADR-0087:retiredKey() + src/conversions/registry.ts 的 D2 conversion + D3 chain step + major changeset。本簇可达,所以这条会真的被触发,别指望绕过。
3. ⛔ 禁止手编 packages/spec/authorable-surface.json(authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650)。删基线行 = 删证据,门禁不拦但这是明令禁止的。gen:schema 只允许因新增 key 而重写它。
4. ⚠️ 注意 build-schemas.ts 检查 (b) 用叶名匹配 conversion surface —— 无关簇的 .type 就能让一个 tombstone 冒充「已登记迁移」 #4659:检查 (b) 按 leaf name 匹配 conversion surface,无关 conversion 也能满足它。也就是说门禁绿不等于你的 conversion 真的对上了 —— 自己核对 surface 是否真指向你 retire 的那个 def,别让门禁替你判断。
5. 改名成本取决于改哪侧:key 记作 ${defKey}:${name},改名 ⇒ 旧 defKey 全部 key vanish。两侧都有 key,所以本簇没有零成本改名侧。
6. 回归 pin 用运行时模块命名空间断言,不要用编译期条件类型(packages/spec 的「编译期 pin」是失效的:tsconfig 排除了 *.test.ts,vitest 也不做类型检查 #4642 已证空转);必须 sabotage 验证并在 PR 贴输出。
7. 判不出来就升级,不要猜(spec 双源清账 C5:ActivationEventSchema(./kernel ≠ ./studio)—— 1 条 #4653 / spec 双源清账 C6:EventSchema(./automation ≠ ./kernel)—— 1 条 #4658 先例)。分析本身就是交付物。
8. ⛔ 不要碰 content/docs/releases/。

验收

• 基线删掉上面 2 行,22 → 20(若 C5 先落则顺延),只减不增。
• 全绿:build、check:dual-source-exports、check:generated、test,加源码审计组(check:liveness / check:strictness-ledger / check:empty-state / check:variant-docs / check:exported-any / check:skill-examples),以及全仓 pnpm typecheck。
• 删 zod 形状则同步 docs/audits/2026-07-unknown-key-strictness-ledger.md。
• changeset 一份,@objectstack/spec major,含 FROM → TO 与迁移指引。

关联:#4535(主单)、#4650 / #4659(门禁漏洞)、#4642(pin 空转)、ADR-0049、ADR-0087、ADR-0104

[os-zhuang]

🔒 Claiming this issue.

• session ID: session_01M9uWvoEp9CoLzYjNExj9sL
• branch: claude/issue-4661-retry-policy-dual-source
• worktree: /home/user/objectstack-4661

开工前已重读本 issue 评论区,无更早认领。若有其他 agent 已在 in-flight,请回复告知,我会让路。

---

Generated by Claude Code

[os-zhuang]

🛑 停在裁决点:立单的两条前提在本簇都不成立,未写任何代码

session session_01M9uWvoEp9CoLzYjNExj9sL,分支 claude/issue-4661-retry-policy-dual-source(零 commit,worktree 已清理)。

四仓扫描 + 可达性复核做完了。结论:本簇不存在「并集存活 ⇒ 零 tombstone」的路线,而且立单把成本框定在 tombstone 上是低估了 —— 真正的风险是门禁完全看不见的默认值翻转。按军规不猜,交回裁决,附实现就绪的方案。

---

1. 四仓 import 语句级扫描:两侧都活,无死侧

RetryPolicySchema / RetryPolicy 的 import 语句,packages/spec 之外:

仓	import 命中	说明
cloud / cloud-v1 / objectui	0	org code search 对 "RetryPolicySchema" 排除本仓后 total_count: 0
objectstack 本仓	0 直接 import 该符号	但两侧各有真实运行时执行方,见下

⇒ 和 #4653 一样,零 importer 不等于有死侧。两侧都被各自的执行器按属性名读取:

• system 侧:services/service-job/src/run-with-policy.ts:58-65 读 maxRetries / backoffMs / backoffMultiplier,自带回退 {3, 1000, 2};liveness/job.json 的 retryPolicy 判 live,注解写明「maxRetries/backoffMs/backoffMultiplier all drive the exponential-backoff retry loop … Enforced since [P2] Aspirational-config disposition: reconcile-or-prune the still-dead props from the 2026-06 liveness audit (Theme / Translation / Job / Webhook) #3494」。
• automation 侧:services/service-automation/src/builtin/try-catch-node.ts 用 parseNodeConfig 按 TryCatchConfigSchema 解析,5 个 key 全部真的实现了(含 jitter 的随机抖动与 maxRetryDelayMs 的封顶)。
• 另有 objectui/packages/app-shell/.../previews/JobPreview.tsx 从未类型化的 Record< string, unknown > 读 retryPolicy.{maxRetries,backoffMs,backoffMultiplier},注释自称 canonical。typecheck 抓不到它 —— 改 system 侧拼写会让这个预览静默变哑。

2. ⚠️ 立单前提修正(a):automation 侧的可达路径与立单描述不符(结论不变,机制不同)

立单说「automation 侧经 control-flow.zod.ts 的 retry: 进 FlowSchema」。静态 $ref 图上不成立:

• flow.zod.ts:163 config: z.record(z.string(), z.unknown()).optional() —— 节点 config 是开放 record(该文件 74-76 行自己写了「A node's config stays an OPEN …」)。
• TryCatchConfigSchema 在 flow.zod.ts 里一次都没被引用(引用它的只有 region-slots.ts / bpmn-mapping.ts / 测试)。

所以 C8 判 ✅ 可达,是靠 system 侧成立的:BUILTIN_METADATA_TYPE_SCHEMAS.job = JobSchema → JobSchema.retryPolicy → system/RetryPolicy。这条 #4535 §1 的表没错,只是理由记反了。

但立单的实质结论反而更强,不是更弱:automation 侧经节点 config 缝(configSchema,#4027/#4040)被作者真写、被执行器真解析,而 TryCatchConfigSchema 不是 .strict() —— 掉一个 key 就是 Zod 静默吞掉作者写的值,连报错都没有。tombstone 要求成立。

3. ⚠️ 立单前提修正(b):「并集存活 ⇒ 不用 tombstone」在本簇不可能

两侧形状(automation 5 key / system 3 key,已核 authorable-surface.json):

key	automation/RetryPolicy	system/RetryPolicy
maxRetries	int 0..10,default 0	int ≥0,无上限,default 3
基础延迟	retryDelayMs int ≥0,default 1000	backoffMs int positive,default 1000
backoffMultiplier	≥1,default 1	positive(允许 0.5),default 2
maxRetryDelayMs	int ≥0,default 30000	—
jitter	bool,default false	—

retryDelayMs 和 backoffMs 是同一个概念的两个拼写 —— 两侧的退避公式一模一样(delay = base * multiplier^(retry-1)),两个执行器的实现也一模一样。

所以「让并集存活」在字面上意味着一个 schema 里同时声明两个表示同一件事的 key,消费方再 ?? 二选一 —— 这正是军规里点名禁止的 alias/宽容消费方形态,也是 AI 生成的元数据最容易藏错的地方。并集路线不可取 ⇒ 至少一个可作者化 key 必然消失 ⇒ ADR-0087 必然触发。

4. 真正的成本不是 tombstone,是门禁看不见的默认值翻转

立单把成本框定为「key 消失 → tombstone + conversion」。但收敛后 maxRetries / backoffMultiplier 只能有一个默认值,而两侧现值是故意相反的:

	取 system 现值(3 / 2)	取 automation 现值(0 / 1)
对 try_catch	retry: {} 从「不重试」变成重试 3 次 ⇒ try 区域的副作用被重放	不变
对 job	不变	retryPolicy: { backoffMs: 5000 } 从「重试 3 次」变成不重试 ⇒ #3494 的能力静默失效

vanish 检查只看 key 的存在性(#4653 已证),默认值翻转零门禁、零 tombstone、零 conversion 记录。也就是说:本簇最危险的破坏,恰好是 ADR-0087 的机器不建模的那一类。

而这两个默认值各自都是对的:定时任务失败了该重试;flow 的 try 区域带副作用,默认不该重放。这本身就是「它们到底是不是同一个合同」的最强反证。

顺带,约束也冲突:maxRetries 上限 10 若成为规范,现存 maxRetries: 20 的 job 会硬拒(响亮,可接受);backoffMultiplier 取 min(1) 则现存 0.5 的 job 硬拒。

5. 平台上还有 3 套同概念拼写 —— 本簇选的拼写会事实上定规范

声明点	基础延迟拼写	状态
system/RetryPolicy(job)	backoffMs	enforced
data/hook.retryPolicy(.strict())	backoffMs	enforced
automation/RetryPolicy(try_catch)	retryDelayMs	enforced
system/TaskRetryPolicy(worker)	initialDelayMs + backoffStrategy	—
kernel/events/queue.retryPolicy	initialDelayMs + backoffStrategy	—
datasource.retryPolicy	baseDelayMs	已按 #4583 退休

repo 自己已经两处写下立场,都指向 backoffMs:

• liveness/job.json:「retryPolicy here is the ENFORCED spelling ({maxRetries, backoffMs, backoffMultiplier})」
• conversions/registry.ts:2252-2255(datasource 账本判定的 20 条死键至今无人处置：三个块整块无人读，其中 readOnly 让一个 shipped 示例的「只读副本」可写（ADR-0049 enforce-or-remove） #4583 注释):「hook.retryPolicy and job.retryPolicy ARE enforced. They … spell the delay backoffMs, not baseDelayMs」

⇒ 拼写这一项证据相当确定;默认值那一项没有任何既有立场可依。

---

6. 路线 × 两轴

A. 收敛到 automation 5-key 形状(system re-export)

• 消失:system/RetryPolicy:backoffMs(1)⇒ tombstone + D2 + D3 + major。
• 长期健全性:推翻 repo 自己两处写下的 enforced 拼写,并要改 contracts/JobRetryPolicy、run-with-policy.ts、objectui JobPreview.tsx(未类型化,typecheck 不报,静默变哑)。反向。
• 抗 AI 写错:job 默认 3→0 是静默失效,AI 生成的 job 元数据会以为有重试。差。

B. 收敛到 system 3-key 形状(automation re-export)

• 消失:retryDelayMs / maxRetryDelayMs / jitter(3)⇒ 3 个 tombstone。
• 长期健全性:删掉的是 try-catch-node.ts 真正实现的能力。ADR-0049 清的是 declared-but-unenforced;这里反过来删 enforced,方向相反。
• 抗 AI 写错:try_catch 默认 0→3 ⇒ 副作用静默重放,最难查的一类 bug。
• 两轴皆输,不推荐。

C. 收敛到「能力并集 + 单一基础延迟拼写」(推荐族)

C1(推荐):canonical = { maxRetries, backoffMs, backoffMultiplier, maxRetryDelayMs, jitter }(5 key),基础延迟取 backoffMs。

• 消失:仅 automation/RetryPolicy:retryDelayMs(1)⇒ 1 个诚实的 tombstone + 1 条 conversion。
• 长期健全性:两侧能力零损失(jitter / maxRetryDelayMs 给定时任务是净收益 —— 抖动正是防惊群的);与 hook.retryPolicy 拼写统一 ⇒ 平台 enforced 拼写从 3 种收到 2 种,只剩 worker/queue 的 initialDelayMs 一族,不预支那个更大的问题;与 repo 已写下的立场一致;外部消费方(contracts / service-job / objectui)零改动。
• 抗 AI 写错:唯一的可作者化改动是 flow 侧一次可机械迁移的改名,且 mapFlowNodes + renameConfigKey 现成可用,os migrate meta 能自动改写;未迁移的旧值不会静默 —— conversion 之后仍留着的话会被…… 见下 §7 的补丁。
• C2(取 retryDelayMs)= A 的变体,反向推翻既有立场,不推荐。

D. 改名一侧,承认是两个概念

• 两侧都有 key ⇒ 改 automation 侧 5 个 vanish,改 system 侧 3 个 vanish。而且这些 tombstone 是假的:作者文档里 retry.retryDelayMs / retryPolicy.backoffMs 一个字没变,registry 里却要写「已移除,请改用 X」。
• 用伪造的墓碑换门禁绿,比 feat(spec)!: 双源 C3 收敛 — 通知语汇归 ./api,./ui 与 ./system 侧死删 (#4610) #4638 / feat(spec)!: 双源 C4 收敛 — Session 归 ./api,./identity 侧死删 (#4641) #4643 的手编基线更糟(那只是删证据,这是造证据)。
• 唯一优点:零语义变化、零默认值翻转。若维护者认为 flow-retry 与 job-retry 本就是两个合同,D 是唯一诚实反映该判断的形状 —— 但需要先给它一个诚实的门禁出口(等同 authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650 要为 C6 开的窄例外:defKey 改名且 key 集合等价时,允许改基线而不伪造 tombstone)。该例外不存在之前,D 无法诚实收口。

---

7. 默认值:conversion 可以把「静默翻转」变成「零行为变化」

这是我这轮最有价值的发现,它让 §4 的风险可以被完全消掉,但方向仍要维护者定。

两个 walker 都验证过、都可达(不是假设):

• mapCollection(stack, 'jobs', …) —— jobs 确认是 stack/bundle 的集合键(runtime/src/app-plugin.ts:799-802),mapCollection 是通用的(datasource 账本判定的 20 条死键至今无人处置：三个块整块无人读，其中 readOnly 让一个 shipped 示例的「只读副本」可写（ADR-0049 enforce-or-remove） #4583 已用它走 datasources)。
• mapFlowNodes(stack, …) —— 会递归进 config.body.nodes,try_catch 节点的 config.retry 可达;renameConfigKey 现成。

于是,无论 canonical 默认值取哪一侧,D2 conversion 都可以把另一侧的旧默认值显式物化进现存文档:

• 若 canonical 取 maxRetries: 0 / multiplier: 1(automation 现值)⇒ conversion 给每个现存 job.retryPolicy 补写 maxRetries: 3 / backoffMultiplier: 2。
• 若 canonical 取 maxRetries: 3 / multiplier: 2(system 现值)⇒ conversion 给每个现存 try_catch 的 config.retry 补写 maxRetries: 0 / backoffMultiplier: 1。

任一方向,现网行为零变化,且变化是显式、可见、可 review 的,不再是门禁盲区。剩下的纯粹是前瞻语义的裁决:

作者写了 retry / retryPolicy 块但省略 maxRetries 时,应该发生什么?
0(重试必须显式 opt-in,安全)还是 3(写了 retry 就是要重试,否则这个块是废的)?

两个读法都自洽,证据不能判定,而且这决定了今后每一份 AI 生成的 job / flow 元数据的默认行为 —— 这正是军规要求停下来的那类问题。

---

8. 我的建议

C1 + maxRetries 默认取 0、backoffMultiplier 默认取 1,并用 D2 conversion 给现存 job 显式物化 {maxRetries: 3, backoffMultiplier: 2}。

• 长期健全性:C1 是唯一不删任何 enforced 能力、不推翻既有立场、不预支 worker/queue 拼写问题的路线;基线 22 → 20 只付 1 个诚实的 tombstone。默认取 0 让「保守默认 + 显式声明」成为协议姿态,与 ADR-0049「声明即执行」同向。
• 抗 AI 写错:默认 0 意味着「没写就不会重试」—— AI 生成的元数据不会隐式获得重试与副作用重放;要重试必须写出来,而写出来的东西是 enum/数值受约束、parse 时会响亮失败的。反过来默认 3,AI 写的 try_catch 会静默重放副作用,那是最难在测试里发现、最贵在生产里发现的一类 bug。
• 两轴在此不冲突;唯一的代价([P2] Aspirational-config disposition: reconcile-or-prune the still-dead props from the 2026-06 liveness audit (Theme / Translation / Job / Webhook) #3494 给 job 的默认重试要显式化)被 conversion 完全吸收,不是静默破坏。

若维护者更看重「retryPolicy: {} 不该是废块」,则取 3 / 2 并让 conversion 反向物化 —— 实现工作量相同,我按裁决走即可。

请裁三件事

1. 路线:C1(收敛到并集 + backoffMs)/ A / B / D(改名,需先开 authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650 式窄例外)。
2. canonical 默认值:maxRetries 取 0 还是 3、backoffMultiplier 取 1 还是 2?(无论哪个,我都写反向物化的 conversion,保证现网零行为变化。)
3. 约束取谁:maxRetries 上限保留 automation 的 10 吗(现存 maxRetries > 10 的 job 会硬拒,响亮但是破坏)?backoffMultiplier 取 min(1) 还是 positive()(前者会拒掉 0.5)?基础延迟取 min(0) 还是 positive()(取 min(0) 是放宽,安全)?

裁决给到我就继续。届时会一并交付:1 个 retiredKey() tombstone(automation 侧 retryDelayMs)、D2 conversion(含 fixture)+ D3 chain step、运行时模块命名空间断言的回归 pin(+ sabotage 输出)、try-catch-node.ts 里那份手写 JSON Schema 镜像的同步(它把 5 个 key 又抄了一遍,不改就会漂移)、contracts/JobRetryPolicy 的能力对齐、以及 major changeset(FROM → TO)。

顺带记录(未动手,不在本簇范围)

• content/docs/references/automation/job.mdx 与 content/docs/references/system/job.mdx 是两份都叫 Job 的自动生成参考页,各自文档一个形状不同的 RetryPolicy —— spec 同名双源:两个 MetadataWatchEvent 形状不同、分挂两个子路径入口,其中 kernel 版零消费方(ADR-0049 enforce-or-remove) #4411 陷阱在文档面的完整复现。本簇任一收敛路线都会一并消掉,故不另立单。
• try-catch-node.ts 的 configSchema 是手抄的 JSON Schema,与 RetryPolicySchema 无机器保证的一致性(今天恰好一致)。这是独立于本簇的漂移风险;若维护者要,我可以另立 unassigned issue。

---

Generated by Claude Code

[os-zhuang]

✅ 更正上条评论的最后一个「顺带记录」—— 我说错了,该处有机器保证

上条我写「try-catch-node.ts 的 configSchema 是手抄的 JSON Schema,与 RetryPolicySchema 无机器保证的一致性」。这是错的,收回。核实后:

• services/service-automation/src/builtin/control-flow-form-zod-ledger.test.ts(A designer configSchema and the keys its executor actually reads are still unreconciled — notify honours cfg.source, which no schema declares #4045)专门 pin 了 loop / parallel / try_catch 三者「手写 configSchema」与「control-flow.zod.ts 里 Zod」两侧 key 集合的关系,文件头注释写明:「so neither can gain or lose a key without the other noticing」。它比较 key set 而非生成形状,是刻意的取舍(service-automation 不依赖 zod,schema.shape 已足够),理由在文件头有完整交代。
• config-schemas.test.ts:195-205 另外 pin 了 form 那一半的具体约束,恰好覆盖本簇的键:retry.maxRetries 的 minimum: 0 / maximum: 10、retry.backoffMultiplier.minimum: 1、retry.jitter.type: 'boolean'。

所以不存在我说的那个漂移风险,也不需要另立 issue —— 这个位置已经是 #3569 / #4040 ledger 模式的正面案例。

这条更正对裁决是加分项,不是减分项:它意味着任何收敛路线里 retryDelayMs → backoffMs 的改名、以及 maxRetries 上限 / backoffMultiplier 下限的任何调整,都会被这两个测试响亮地拦下,不会悄悄漂走。实施时它们是必须同步更新的确定位点(会体现在 PR 里),而不是隐患。

上条评论的其余结论与三个待裁问题不变。

---

Generated by Claude Code