From c04ecdda87da3664da73c2a066953974de35fe12 Mon Sep 17 00:00:00 2001 From: ggbdpq Date: Wed, 2 Sep 2026 07:22:16 +0800 Subject: [PATCH 1/2] docs(architecture): audit Recovery and resume group against implementation Audit the seven Recovery and resume documents under #3522 against current main. Four documents needed corrections; three were verified accurate as written. Corrections: - recovery-resolver ADR: the Phase 3 decision fact was implemented as the `actions.toolRecovery` envelope (`maka.tool.recovery_decision`, protocol `tool_recovery_v1`) committed through the atomic recovery bundle transaction, not a `tool_recovery_decided` RuntimeEvent; the call+dispatch-without-response row resolves to `indeterminate` with a resolution-level `requiresReconciliation` (reconciled operations settle as terminal `parked` with `reconcile_*` reasons), not a `reconcile_required` status; and the journal projection states are now `prepared | outcome_committed | recovery_completed | recovery_parked`. - extraction ledger and Phase 3-4 design: `PROVIDER_REPLAY_PROJECTION_VERSION` was frozen at 1 by PR B and advanced to 2 by #4286 (cross-model reasoning replay gating). - resume architecture (en + zh-CN): the prior-state recovery park reason is the durable `reconcile_matches_prior_state`; `redo_disabled_pending_cas` never became a durable code (the Phase 3-4 design keeps it as a UI mapping note only). Verified accurate with no changes: phase0 crash contract (P0-P11 failpoint table, decision vocabulary, twelve-failpoint harness claim), phase1 safe-boundary contract (flag, planner gates, lifecycle event names, host entry points), and the extraction ledger's file inventory, capability names, and schema milestones. The paired resume-architecture documents move together and both carry `last_verified: 2026-09-02`; `translation_status: synced` is preserved. Refs #3522 Generated-by: GLM-5.3-Flash (ZCode) --- docs/architecture/runtime-recovery-resolver-adr.zh-CN.md | 8 ++++---- docs/architecture/runtime-resume-architecture.md | 6 +++--- docs/architecture/runtime-resume-architecture.zh-CN.md | 6 +++--- .../runtime-resume-extraction-ledger.zh-CN.md | 2 +- ...ume-phase3-phase4-workspace-checkpoint-design.zh-CN.md | 2 +- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md b/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md index 9d55ad7964..7d257ae87a 100644 --- a/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md +++ b/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md @@ -85,7 +85,7 @@ 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 | @@ -93,11 +93,11 @@ Planner、CLI、UI 和未来 reconciler 不得各自组合事实。它们只消 | dispatch/response 的 operation、tool call、tool name 或执行身份冲突 | corruption | | 同一 operation 出现多个不一致 dispatch 或 response | 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 | outcome_committed | recovery_completed | recovery_parked`）。未来新状态若需要查询表示，先定义对应 RuntimeEvent，再扩展 projector。 新协议的重建验收标准：清空 `tool_journal_events` 与 `tool_operations` 后，从 RuntimeEvent 投影得到相同 operation identity、dispatch/result event refs、recovery mode 与 current state。 @@ -139,7 +139,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 与投影重建工具。 ## 验收不变量 diff --git a/docs/architecture/runtime-resume-architecture.md b/docs/architecture/runtime-resume-architecture.md index 32cede1e3c..031091edc3 100644 --- a/docs/architecture/runtime-resume-architecture.md +++ b/docs/architecture/runtime-resume-architecture.md @@ -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 --- @@ -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 | @@ -619,7 +619,7 @@ flowchart TD Expected -->|"Yes"| Finalize["Finalize only
do not write the file again"] Finalize --> Completed["Commit recovered outcome
+ completed decision"] Expected -->|"No"| Prior{"current == before?"} - Prior -->|"Yes"| ParkPrior["Park
redo_disabled_pending_cas"] + Prior -->|"Yes"| ParkPrior["Park
reconcile_matches_prior_state"] Prior -->|"No, content diverged"| ParkDiverged["Park
protect outside writes"] Prior -->|"Unreadable"| ParkUnreadable["Park
do not guess"] ``` diff --git a/docs/architecture/runtime-resume-architecture.zh-CN.md b/docs/architecture/runtime-resume-architecture.zh-CN.md index c0dbccaf6f..a3aaf3681e 100644 --- a/docs/architecture/runtime-resume-architecture.zh-CN.md +++ b/docs/architecture/runtime-resume-architecture.zh-CN.md @@ -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 --- @@ -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，不猜测 | @@ -638,7 +638,7 @@ flowchart TD Expected -->|"是"| Finalize["Finalize only
不再次写文件"] Finalize --> Completed["提交 recovered outcome
+ completed decision"] Expected -->|"否"| Prior{"current == before?"} - Prior -->|"是"| ParkPrior["Park
redo_disabled_pending_cas"] + Prior -->|"是"| ParkPrior["Park
reconcile_matches_prior_state"] Prior -->|"否，内容分叉"| ParkDiverged["Park
保护外部写入"] Prior -->|"无法读取"| ParkUnreadable["Park
不猜测"] ``` diff --git a/docs/architecture/runtime-resume-extraction-ledger.zh-CN.md b/docs/architecture/runtime-resume-extraction-ledger.zh-CN.md index 4a9d942bbc..26e2f23fa2 100644 --- a/docs/architecture/runtime-resume-extraction-ledger.zh-CN.md +++ b/docs/architecture/runtime-resume-extraction-ledger.zh-CN.md @@ -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 | diff --git a/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md b/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md index 00d5adb00e..e9ddc7fe3d 100644 --- a/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md +++ b/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md @@ -167,7 +167,7 @@ composite replay 存在时，它是 tool-state 与 provider suffix 的唯一 gat 最终同时冻结： -- `providerProjectionVersion = 1`； +- `providerProjectionVersion`（PR B 时冻结为 1；#4286 起为 2）； - composite `providerReplayDigest`； - segment boundary manifest。 From f6f187d1d461a3d76c5f70f759fdf9c0ce2be8fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=B3=E5=A4=A9=E8=B1=AA?= Date: Wed, 2 Sep 2026 19:26:31 +0800 Subject: [PATCH 2/2] fix(docs): close review gaps in the recovery audit group Per review by Astro-Han and me2seeks on #4518: - The ADR journal-state list now matches the full five-member ToolJournalState union; reconcile_observed was missing while the surrounding wording claimed write-path completeness. - The ADR decision table gains the row for operations that already carry a recovery decision fact: settled from the recovery bundle (completed -> recovery_bundle_completed, else parked with the fact's reasonCode; corrupted facts stay corruption), matching recovery-resolver.ts. - The Phase 3-4 design park-reason table and its UI note now use the durable reconcile_matches_prior_state code; the redo_disabled_pending_cas mapping note is removed as it has no code presence. Refs #3522 Generated-by: GLM-5.3-Flash (ZCode) --- docs/architecture/runtime-recovery-resolver-adr.zh-CN.md | 3 ++- ...esume-phase3-phase4-workspace-checkpoint-design.zh-CN.md | 6 +++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md b/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md index 7d257ae87a..c1104224f3 100644 --- a/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md +++ b/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md @@ -92,12 +92,13 @@ Planner、CLI、UI 和未来 reconciler 不得各自组合事实。它们只消 | 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 恢复写入者经原子 recovery bundle 事务提交 `actions.toolRecovery` decision fact（`maka.tool.recovery_decision`，protocol `tool_recovery_v1`）；后续 reconcile 结果同样追加事件，不回写历史事实。 ### 5. Journal 是可重建投影，不是第二份账本 -Phase 2.5 保留现有表以降低查询成本，状态缩窄为写入路径可达的集合（现为 `prepared | outcome_committed | recovery_completed | recovery_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。 diff --git a/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md b/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md index e9ddc7fe3d..d2c95826cb 100644 --- a/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md +++ b/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md @@ -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，不猜测 | @@ -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