feat: add durable safe retries with uncertainty tracking and SDK examples

docs/api/worker.md

@@ -88,9 +88,9 @@ capacity 使用单调递增序号和覆盖值。同序号同内容可重复，
 | --- | --- | --- |
 | task.start | AttemptRef | 领取后再次检查当前会话、尝试、租约、队列暂停及流程门控，保存 RUNNING 后确认 |
 | task.renew | AttemptRef | 只续期当前 RUNNING；新消息可续租，重复原消息只取回原回执 |
-| task.finish | ref: AttemptRef、outcome、result、error_code | 保存明确结果或未知效果；返回操作回执和当前授权 |
+| task.finish | ref: AttemptRef、outcome、result、error_code、可选 retryable | 保存明确结果或未知效果；返回操作回执和当前授权 |
 
-outcome 为 SUCCEEDED / FAILED / UNKNOWN。result 为非 null JSON 或证据引用。FAILED/UNKNOWN 必须带 1–64 字符的稳定 error_code；SUCCEEDED 不带错误分类。当前 FAILED 成为任务失败终态，UNKNOWN 转 NEEDS_REVIEW；策略化自动重试在 P3 实现。
+outcome 为 SUCCEEDED / FAILED / UNKNOWN。result 为非 null JSON 或证据引用。FAILED/UNKNOWN 必须带 1–64 字符的稳定 error_code；SUCCEEDED 不带错误分类。retryable 省略为 false，只有 FAILED 可设 true，表示此次明确失败可安全重试。FAILED/true 受次数与时限限制进入退避；UNKNOWN 仅在冻结策略为 IDEMPOTENT 且预算允许时自动恢复，其他情况转 NEEDS_REVIEW。历史不确定效果不会被后续失败覆盖；完整规则见 [安全重试](retries.md)。
 
 开始、续租和结束返回 CommandResult：
 
@@ -120,7 +120,7 @@ receipt 是原操作的不可变确认；lease 是本次重新核验的执行权
 - 原 start 回执可能仍表示 RUNNING，但当前 lease.active=false；旧 ACK 不能让已过期、已结束或已被替换的尝试复活。
 - 有效期不超过租约窗口、会话期限、任务总截止和从 authorized_at 起计算的单次尝试时限。
 - 客户端需要扣除请求总耗时及安全余量，用本地单调时钟停止执行，不能假定本地墙上时钟与数据库一致。
-- 同结果重报不重复释放许可或产生成功事件。同消息不同内容返回 IDEMPOTENCY_CONFLICT。
+- 同结果重报不重复释放许可或产生成功事件；即使换 message_id，也返回该结果第一次已应用的回执，不借用后续尝试的状态。同消息改变内容或 retryable 返回 IDEMPOTENCY_CONFLICT。
 - 迟到、未开始或与已保存结果冲突的内容，经过身份和秘密验证后保存为 EVIDENCE_ONLY；不改变任务权威结果，不当作新的执行授权。
 - 断线后原结果仍保留稳定消息 ID，可在新会话恢复/核对后重报。不会因重连创建第二次业务执行。
 
@@ -132,12 +132,12 @@ receipt 是原操作的不可变确认；lease 是本次重新核验的执行权
 
 每个节点每 2 秒发起一批恢复扫描，每批最多 100 项：
 
-- 未批准开始即到期：有剩余次数和截止时间时，延后 1 秒重派；否则 FAILED。
-- 已批准开始后失联：NEEDS_REVIEW，尝试 UNKNOWN，不能因网络超时断定业务未生效。
-- WAITING 超过总截止或最晚开始时间：FAILED。
+- 未批准开始即到期：有剩余次数和截止时间时按冻结策略退避；否则无历史不确定效果为 FAILED，有未核实效果为 NEEDS_REVIEW。
+- 已批准开始后失联：尝试 UNKNOWN；RECONCILE_ONLY 转 NEEDS_REVIEW，IDEMPOTENT 仅在次数及时限允许时退避重试，并保留 effect_uncertain。
+- WAITING 超过总截止或最晚开始时间：无历史不确定效果为 FAILED，否则 NEEDS_REVIEW。
 - 回收再次锁定队列、任务、尝试并读取数据库时间，与续租/完成串行化；多个节点不能重复释放许可或重复终结事件。
 
-此处的安全回收不是完整重试引擎；IDEMPOTENT 的自动重试和策略退避仍是 P3 工作。
+安全重试已使用同一决策逻辑处理有效结果与租约回收；下一执行时间持久化在任务中，重启不丢失等待。当前不提供人工重试或核查解除接口。
 
 ## 6. 连接保护与当前边界