Skip to content

docs(architecture): audit Recovery and resume group against implementation #4518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
me2seeks merged 2 commits into from
Sep 3, 2026
Merged

docs(architecture): audit Recovery and resume group against implementation #4518

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c04ecdd
docs(architecture): audit Recovery and resume group against implement…
ggbdpq Sep 1, 2026
f6f187d
fix(docs): close review gaps in the recovery audit group
ggbdpq Sep 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions docs/architecture/runtime-recovery-resolver-adr.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,19 +85,20 @@ Planner、CLI、UI 和未来 reconciler 不得各自组合事实。它们只消
|---|---|
| call + matching response，无 dispatch | completed；表示 T1 前合成结果，legacy 下 response 本身也是完成证据 |
| call + dispatch + matching response | completed |
| call + dispatch，无 response | indeterminate / reconcile_required |
| call + dispatch，无 response | indeterminate，Resolver 置 `requiresReconciliation`，reason 记 `dispatch_without_response` |
| call，无 dispatch、无 response，首事件声明新协议 | definitely_not_dispatched |
| call，无 dispatch、无 response，legacy/unknown protocol | indeterminate |
| dispatch 存在但对应 call 不存在 | corruption |
| response 存在但对应 call 不存在 | corruption |
| dispatch/response 的 operation、tool call、tool name 或执行身份冲突 | corruption |
| 同一 operation 出现多个不一致 dispatch 或 response | corruption |
| call（含 dispatch 后无 response）且 operation 已带 recovery decision fact | 以 recovery bundle 结算：disposition 为 completed 则 completed（reason `recovery_bundle_completed`），否则 parked 并沿用 fact 的 reasonCode；fact 本身损坏按 corruption 处理 |

Resolver 必须 fail-closed：未知组合不能退化成自动重试。Phase 3 首个恢复写入者应追加 `tool_recovery_decided` RuntimeEvent；后续 reconcile 结果同样追加事件，不回写历史事实。
Resolver 必须 fail-closed：未知组合不能退化成自动重试。Phase 3 恢复写入者经原子 recovery bundle 事务提交 `actions.toolRecovery` decision fact（`maka.tool.recovery_decision`，protocol `tool_recovery_v1`）；后续 reconcile 结果同样追加事件，不回写历史事实。

### 5. Journal 是可重建投影，不是第二份账本

Phase 2.5 保留现有表以降低查询成本，但状态缩窄为当前确有写入路径的 `prepared | outcome_committed`。未来 `indeterminate`、`reconciled`、`parked` 若需要查询状态，先定义对应 RuntimeEvent，再扩展 projector。
Phase 2.5 保留现有表以降低查询成本，状态缩窄为写入路径可达的集合（现为 `prepared | reconcile_observed | outcome_committed | recovery_completed | recovery_parked`，与 `ToolJournalState` 联合一致，其中 `reconcile_observed` 由 reconcile 追加事件写入）。未来新状态若需要查询表示，先定义对应 RuntimeEvent，再扩展 projector。

新协议的重建验收标准：清空 `tool_journal_events` 与 `tool_operations` 后，从 RuntimeEvent 投影得到相同 operation identity、dispatch/result event refs、recovery mode 与 current state。

Expand Down Expand Up @@ -139,7 +140,7 @@ Phase 2.5 保留现有表以降低查询成本，但状态缩窄为当前确有
1. Phase 2.5：增加 dispatch RuntimeEvent 和运行时 protocol marker；Journal 改为其同步投影。
2. Phase 2.5：实现稳定 revalidation error code，清理无生产调用的旧接口与虚设状态。
3. Phase 3：实现纯 RecoveryResolver 与完整决策表。
4. Phase 3：提交 `tool_recovery_decided`，先支持 park/reconcile_required，不直接自动重跑有副作用工具。
4. Phase 3：经 recovery bundle 提交 terminal decision fact（disposition `parked` / `completed`），先支持 park/reconcile，不直接自动重跑有副作用工具。
5. Phase 3：加入 replay manifest、全 source digest revalidation 与投影重建工具。

## 验收不变量
Expand Down
6 changes: 3 additions & 3 deletions docs/architecture/runtime-resume-architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ counterpart: ./runtime-resume-architecture.zh-CN.md
implementation_status: phase_0_2_and_phase_3a_authority_current
document_status: current
translation_status: synced
last_verified: 2026-08-29
last_verified: 2026-09-02
owners:
- maka-backend
---
Expand Down Expand Up @@ -608,7 +608,7 @@ Write/Edit recovery first needs durable evidence bound to:
| Observation | Action |
|---|---|
| `matches_expected_state` | Cleanup/finalize only; synthesize outcome and commit completed bundle |
| `matches_prior_state` | Park with `redo_disabled_pending_cas` |
| `matches_prior_state` | Park with `reconcile_matches_prior_state` |
| `diverged` | Park; do not overwrite outside changes |
| `unreadable` | Park; do not guess |

Expand All @@ -619,7 +619,7 @@ flowchart TD
Expected -->|"Yes"| Finalize["Finalize only<br/>do not write the file again"]
Finalize --> Completed["Commit recovered outcome<br/>+ completed decision"]
Expected -->|"No"| Prior{"current == before?"}
Prior -->|"Yes"| ParkPrior["Park<br/>redo_disabled_pending_cas"]
Prior -->|"Yes"| ParkPrior["Park<br/>reconcile_matches_prior_state"]
Prior -->|"No, content diverged"| ParkDiverged["Park<br/>protect outside writes"]
Prior -->|"Unreadable"| ParkUnreadable["Park<br/>do not guess"]
```
Expand Down
6 changes: 3 additions & 3 deletions docs/architecture/runtime-resume-architecture.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ counterpart: ./runtime-resume-architecture.md
implementation_status: phase_0_2_and_phase_3a_authority_current
document_status: current
translation_status: synced
last_verified: 2026-08-29
last_verified: 2026-09-02
owners:
- maka-backend
---
Expand Down Expand Up @@ -627,7 +627,7 @@ Writer、projection rebuild 和 `RecoveryResolver` 共享同一个 scanner/inter
| observation | 动作 |
|---|---|
| `matches_expected_state` | 只做 cleanup/finalize，合成 outcome，提交 completed bundle |
| `matches_prior_state` | park，`redo_disabled_pending_cas` |
| `matches_prior_state` | park，`reconcile_matches_prior_state` |
| `diverged` | park，不覆盖外部写入 |
| `unreadable` | park，不猜测 |

Expand All @@ -638,7 +638,7 @@ flowchart TD
Expected -->|"是"| Finalize["Finalize only<br/>不再次写文件"]
Finalize --> Completed["提交 recovered outcome<br/>+ completed decision"]
Expected -->|"否"| Prior{"current == before?"}
Prior -->|"是"| ParkPrior["Park<br/>redo_disabled_pending_cas"]
Prior -->|"是"| ParkPrior["Park<br/>reconcile_matches_prior_state"]
Prior -->|"否，内容分叉"| ParkDiverged["Park<br/>保护外部写入"]
Prior -->|"无法读取"| ParkUnreadable["Park<br/>不猜测"]
```
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/runtime-resume-extraction-ledger.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,7 @@ B3（typed retry/reattach branch）仍然 defer，不进入本 PR。
| 文件 | PR B 职责 |
|---|---|
| `continuation-replay.ts` | 每个 lineage segment 的唯一 provider replay materializer |
| `model-history.ts` | 冻结 `PROVIDER_REPLAY_PROJECTION_VERSION = 1` |
| `model-history.ts` | 冻结 `PROVIDER_REPLAY_PROJECTION_VERSION`（PR B 时为 1；#4286 起为 2） |
| `runtime-resume.ts` | immutable lineage planner、V2 replay-edge 与历史 claim authority 校验、exact claim/start/terminal 分类 |
| `runtime-kernel.ts` | immediate-source latest 重验、exact tool equality、原子 claim、provider T1 顺序 |
| `agent-run.ts` | Run create 与 backend reservation 之间提交 continuation-start |
Expand Down
8 changes: 4 additions & 4 deletions .../architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ composite replay 存在时，它是 tool-state 与 provider suffix 的唯一 gat

最终同时冻结：

- `providerProjectionVersion = 1`；
- `providerProjectionVersion`（PR B 时冻结为 1；#4286 起为 2）；
- composite `providerReplayDigest`；
- segment boundary manifest。

Expand Down Expand Up @@ -453,7 +453,7 @@ authority、同一 ledger transaction domain。lease 要携带 epoch/fencing tok
| observation | 动作 |
|---|---|
| `matches_expected_state` | cleanup/finalize，合成 outcome，提交 PR A bundle |
| `matches_prior_state` | park，reason=`redo_disabled_pending_cas` |
| `matches_prior_state` | park，reason=`reconcile_matches_prior_state` |
| `diverged` | park，不覆盖外部写入 |
| `unreadable` | park，不猜测 |

Expand All @@ -474,8 +474,8 @@ authority、同一 ledger transaction domain。lease 要携带 epoch/fencing tok
sandbox、one-call grant 和 abort boundary 的执行所有权。

PR C 沿用 PR A 的 durable vocabulary：`matches_expected_state` 可 finalize；
`matches_prior_state`、`diverged`、`unreadable` 均提交 terminal parked decision。UI 可以把
`matches_prior_state` 映射为 `redo_disabled_pending_cas`，但不新增第二套 durable fact 名称。
`matches_prior_state`、`diverged`、`unreadable` 均提交 terminal parked decision。UI 直接展示
durable reason code（如 `reconcile_matches_prior_state`），不维护第二套展示层状态名。

### PR D — Host owner lifecycle

Expand Down