从 Checkpoint 安全恢复

Checkpoint 信封

Checkpoint 包含稳定 ID、所属 Run、单调 Revision、Namespaced Kind、Schema Version、 Payload 与更新时间。CheckpointStore::compare_and_swap 只能创建 Revision 0，并且只能 从精确当前 Revision 更新到下一个 Revision。

这是乐观并发，不是分布式 Lease。它防止旧 Writer 覆盖新语义状态；并发进程执行时， Workflow Ownership 还需要独立 Fencing。

Write-ahead Phase

外部工作前先持久化 Intent。Agent Checkpoint 区分 ReadyForTurn、TurnInFlight 与 Completed；Workflow Checkpoint 记录活跃 Step 或 Branch State。只有解释跳转所需的 全部结果都持久化后，才能写 Stable State。

外部调用后、稳定 Checkpoint 前进程停止会产生不确定性。Store 不能把该 Phase 改写成 成功或失败。

恢复策略

Completed State 无需模型、Tool 或 Workflow 执行即可 Replay；Stable State 从下一次跳转 继续；保守策略会拒绝 In-flight State。

显式 Retry Policy 表示调用者承认模型成本、Tool Call、Delegation 或自定义 Step 可能重复。 配合同一个 Effect Store，使已完成幂等工作能 Replay 记录结果。恢复后的 Usage 永不减少。

Schema 与版本

Checkpoint Payload 服务商中立，但具有版本。恢复前匹配 Agent、Model、Workflow Name 与 Definition Version。不支持的 Schema 必须拒绝，不能猜测旧 Branch 或 Phase 如何映射到新 代码。

迁移要显式执行，离线或带事务 Fencing，尽量可逆，并用所有支持版本的 Fixture 覆盖。

隐私与运维

与默认脱敏的 Journal Event 不同，Checkpoint 可能含有 Transcript、生成内容、Tool Result、 Workflow Input 与 Provider Extension。需要加密、租户授权、备份、Retention、删除与访问 审计。

监控 Revision Conflict、Ambiguous Recovery、Schema Mismatch、Resume Age 与 Checkpoint Size。在每个 Write-ahead 边界测试进程死亡，而不只是测试干净重启。

安全提交一个 Revision

let initial = Checkpoint::initial(
    CheckpointId::new(),
    run.run_id(),
    "acme.order",
    1,
    json!({ "phase": "ready" }),
);
store.compare_and_swap(&initial, None)?;
 
let loaded = store.load(initial.id)?;
let next = loaded.next(json!({ "phase": "validated" }))?;
match store.compare_and_swap(&next, Some(loaded.revision)) {
    Ok(()) => println!("committed revision {}", next.revision),
    Err(error) if error.kind == CheckpointErrorKind::Conflict => {
        // 另一个 Writer 已获胜。重新加载，不要覆盖它的决定。
        let current = store.load(initial.id)?;
        println!("current revision is {}", current.revision);
    }
    Err(error) => return Err(error.into()),
}

None 只能用于创建 Revision 0。外部工作前先持久化 In-flight Phase；只有足以解释 迁移的 Result 已经 Durable 后，才能写 Stable Phase。两者之间崩溃会故意保留 Ambiguous，必须由 Resume Policy 与 Effect Evidence 决定如何处理。