Durable Settlement

Turn checkpoint 不是一次 save(state)

Symbol	Durable 语义
prepareCheckpointForPersistence()	落盘前处理不能可靠持久化的 token/detail state
persistCheckpoint()	transcript prepare → state checkpoint → transcript commit
persistStepCheckpoint()	中间 step durable boundary
persistFinalState()	final durable boundary
TranscriptAppendAfterCheckpointError	state checkpoint 已成功、transcript commit 失败的显式不一致窗口

提交顺序

transcriptMirror.prepareCheckpoint()
        ↓
agentStore.handleCheckpoint()
        ↓ success
transcriptMirror.commitCheckpoint()

如果 state checkpoint 失败：
  → abort prepared transcript

如果 state 成功但 transcript commit 失败：
  → TranscriptAppendAfterCheckpointError

这个设计最值得学习的是：把部分成功窗口显式建模出来。Runtime 不能假装多个外部/持久化 owner 能形成天然原子事务。

Completed Turn 与 Memory

settleCompletedTurn() 先处理 timing / labeling，再按条件触发 runTurnMemory()。Memory 不是 checkpoint commit 的同义词，它是完成后的 maintenance path。

Host-level durable files

durable-file-policy.ts 单独声明 upgrade resume、ack obligations、pending wake、cross-user turn dedupe nonce、disk-pressure reminder 等文件。它说明 durable state 可能由多个职责清晰的 owner 组成，而不是只有一个 checkpoint 文件。

本地定位

rg -n "prepareCheckpointForPersistence|persistCheckpoint|persistStepCheckpoint|persistFinalState|TranscriptAppendAfterCheckpointError|settleCompletedTurn" source/host/runner/turn-settle.ts
cat source/host/durable-file-policy.ts

固定源码

• turn-settle.ts
• durable-file-policy.ts

关联知识文章

• 局部失败如何传播：Partial Failure 与 Runtime Invariants — Checkpoint 写入本身也有 invariant 和失败窗口；persistCheckpoint() → TranscriptAppendAfterCheckpointError
• Run 怎样安全暂停再继续：Pause、Checkpoint 与 Pending Writes — Checkpoint 是 prepare → persist → commit 的恢复边界；persistCheckpoint() → persistStepCheckpoint() → persistFinalState()
• Coding Agent 如何形成闭环：Planner / Generator / Evaluator、Recovery 与 Artifact Contract — Turn settle 把完成事实、Checkpoint 与后处理分开；settleCompletedTurn() → persistFinalState()
• 恢复逻辑如何防回归：Replay / Resume Tests 与 Golden Trace — 真实持久化链天然暴露 Crash Window；prepareCheckpoint() → handleCheckpoint() → commitCheckpoint()
• Runtime 怎么做确定性验证：Unit、Contract、Fault Injection 与 Invariant Tests — 最值得故障注入的地方：Checkpoint 已写、Transcript 未 commit；persistCheckpoint() → TranscriptAppendAfterCheckpointError
• 运行中的信息放哪里：Conversation、Checkpoint 与 Short-Term Memory — Checkpoint 与 Transcript 是相邻但不同的持久化事实；persistCheckpoint() → prepareCheckpoint() → commitCheckpoint()
• Run、Session 和 Durable State 到底各保存什么 — Durable state 会按恢复职责拆成多个持久文件；SAND_UPGRADE_RESUME_FILE_NAME → SAND_PENDING_WAKE_FILE_NAME → SAND_XUSER_TURN_DEDUPE_FILE_NAME