qinglong/docs/adr/ADR-0033-approved-action-recovery-evidence-and-resolution.md

ADR-0033：Approved Action 恢复证据与人工裁决

• 状态：Proposed
• 日期：2026-07-19
• 关联：QL-RFC-0001、ADR-0031、ADR-0032、ADR-0034、ADR-0035、ADR-0036、ADR-0007、ADR-0021

上下文

ADR-0032 用 durable start barrier 区分副作用前和副作用后故障：leased 过期可以安全接管，executing 过期只能得到有效状态 recovery_required。这阻止了 QingLong 因 lease timeout 自动重复一次已审批动作，但还没有回答如何把不确定执行收敛到可信终态。

单纯看到 handler 超时、进程退出、网络断开或本地 receipt 缺失，都不能证明外部副作用没有发生。反过来，一个未绑定 action digest、未经认证或来自旧执行 fence 的 receipt 也不能证明当前 dispatch 成功。edge 上不能为每个动作常驻 watcher/timer；cluster-control 的多副本 resolver 又必须避免重复探测风暴和互相覆盖裁决。

因此恢复必须把“证据观察”和“状态裁决”分开，并明确哪些动作能够自动恢复、哪些动作只能由人处理。

决策

1. recovery_required 是有效状态，不是可领取持久状态

数据库继续持久化 executing。当 now >= lease_expires_at_ms 时，读取层将其解释为 recovery_required：

• 普通 Approved Action due scan 永远不返回它；
• 普通 claim 不得把它变回 leased 或调用 execute；
• 只有 recovery resolver 或具备专门权限的人工裁决可以推进终态；
• 原执行者的迟到 completion 可以提交，但必须仍匹配未被替换的 owner/token/version fence。

这样不会出现两个可写状态互相漂移，也不会因为后台任务延迟而依赖一次额外的状态转换。

2. 恢复只能观察证据，不能重放副作用

每种真实 handler 在启用前必须声明一个 RecoveryEvidenceProvider。provider 只能执行 side-effect-free 的 receipt 读取、目标状态查询或 durable execution identity 探测，返回以下有限 finding：

• verified_succeeded：存在与当前 dispatch 完整绑定且可信的成功证据；
• verified_failed：存在与当前 dispatch 完整绑定且可信的失败证据；
• still_running：可验证的同一 durable execution identity 仍在运行；
• missing：当前没有证据，不等于未执行；
• conflict：证据身份、digest、fence 或认证不匹配；
• unsupported：该 action 类型没有可信恢复能力；
• unavailable：证据源暂时不可用。

resolver 不得调用 handler execute、重新发送 Tool call、重新安装 Package、重写 Secret、重新创建 Run 或根据日志文本猜测结果。即使下游声称幂等，首版恢复也只查询，不用“带相同 idempotency key 再发一次”替代证据。

3. 可信证据必须绑定 immutable action identity

可自动裁决的 receipt/query 结果至少绑定：

• schema version；
• dispatchId、approvalRequestId、projectId；
• actionType 与 canonical actionDigest；
• execution attempt、startedAtMs 与 dispatch idempotency key；
• outcome、低敏 result code、finished time；
• provider-specific receipt identity 的 digest；
• 可验证的完整性来源，例如受信数据库唯一约束、provider 认证响应、HMAC/签名或私有原子存储。

receipt 最大 4 KiB、exact-shape、版本化且禁止 Secret、Tool 参数、Shell、prompt、任意 provider 响应或无界错误文本。数据库只持久化低敏 finding code、receipt/evidence digest 和必要时间，不保存 capability 或原始凭据。

本地文件 receipt 只适用于 edge/standalone 的本机 action，并使用私有目录、原子不可覆盖发布和数据库 journal 定位；cluster-control 的唯一恢复证据必须位于 PostgreSQL、共享对象存储或可认证的外部 provider，不能依赖某个控制面副本的本地文件。

4. 自动恢复能力按 action 类型显式分级

Action 类型	可接受的自动恢复证据	缺少证据时
QingLong 内部数据库 mutation	同事务保存的唯一 dispatchId/mutation ID 与结果事实	保持 recovery-required
Run 创建或控制	RunRepository 中绑定 dispatch 的唯一 origin/request 与状态事实	保持 recovery-required
Package 安装	安装事务记录、目标版本/content digest 与原子 commit marker 同时匹配	人工核验，不从目录存在推断成功
外部 Tool/API	provider 接受 idempotency key，并可认证查询同一 request/receipt	人工核验，不重新发送请求
任意 Shell 或无查询能力 Tool	无	只能人工裁决

真实 handler 注册时必须声明 automatic | manual_only recovery capability。没有 provider 或 contract 测试的 handler 默认为 manual_only，不得用通用进程退出码或日志关键字升级为 automatic。

5. Recovery control 使用独立 lease，裁决写入保持原子

0022-approved-action-recovery 已为跨越 start barrier 的 dispatch 建立一对一 ApprovedActionRecoveryControls，并以唯一 ApprovedActionRecoveryResolutions 保存由恢复流程产生的终结裁决：

• control 在 leased -> executing 的同一事务中 armed；升级时为已有 executing 行回填；
• next_scan_at_ms 使用有界索引，不扫描 immutable dispatch 全表；
• recovery owner/token/version/expiry 只协调证据探测，不授予执行副作用的能力；
• edge/standalone 用短 SQLite BEGIN IMMEDIATE claim，cluster-control 用 PostgreSQL row lock/SKIP LOCKED；
• still_running/missing/unavailable 只更新有界 finding、计数与下一次扫描时间；
• verified_succeeded/verified_failed 在同一事务写唯一 resolution、推进 execution 终态并关闭 recovery control；
• conflict/unsupported 保持 recovery-required 并触发人工队列，不自动 blocked 掩盖未知结果。

normal completion 不伪造 recovery resolution，但必须在同一事务把 control 关闭为 resolved，并以 completion mutation ID 绑定 execution/control。executing renew 会增加 execution/control version、撤销陈旧 recovery lease 并把下一次扫描推迟到新的 execution lease expiry；陈旧 resolver 随后只能得到 fence rejection。

resolver 每次只处理一页，默认不超过 16、硬上限 64；没有内部 timer、递归翻页或 watcher。Profile lifecycle 决定 cadence、单周期页数、退避和 shutdown。edge 空闲时不会写 heartbeat；cluster 多副本由 recovery lease 防止探测风暴。

6. 迟到 completion 与 recovery resolution 使用同一 version 裁决

原执行者 completion 和 recovery resolution 都只能从同一 persistent executing@version 推进终态：

• completion 先赢：resolver 读取终态，不再写 resolution；
• resolution 先赢：迟到 completion 只能精确重放同一 outcome/evidence，否则 fence conflict；
• 两者并发：数据库条件更新只允许一个 winner；
• repository/storage 不可用：保持 recovery-required，不推导成功或失败；
• mutation ID 只有在所有语义字段完全一致时幂等。

wall clock 只决定何时允许进入 recovery scan，不决定哪一个结果更可信。

7. 人工裁决是显式终结，不是隐藏重试

人工裁决要求稳定 User、当前 approval.recover 权限、Project/RoleBinding version fence，以及 authentication 层提供的近期强认证。允许的决定只有：

• confirm_succeeded -> succeeded；
• confirm_failed -> failed；
• abandon_unknown -> blocked。

裁决记录包含唯一 mutation ID、expected execution version、User actor、bounded reason code、可选 evidence digest 与时间，并与 execution 终态在同一事务提交。禁止 retry、reset_to_pending、clear_start_barrier 或编辑 immutable dispatch。

如果操作者确实要重复动作，必须创建新的 action plan、ApprovalRequest 和 dispatch，并显式引用前一个 unknown dispatch；Policy/UI 必须展示可能重复副作用的风险。这让第二次执行成为新的、可审计的授权，而不是偷偷复用旧审批。

8. 当前阶段仍不接生产路径

当前已实现 recovery domain/port、0022 control/resolution migration、SQLite repository、evidence-only bounded reconciler 和 contract tests。测试覆盖 start/control 原子回滚、升级 backfill、稳定 keyset、双 SQLite resolver claim/takeover、finding 精确重放、normal completion 关闭、executing renew 重新 armed、自动/人工 resolution，以及迟到 completion 与 resolver 的单一终态 winner。ADR-0034/0023 又增加了第一个 run.create 原子 receipt 和 SQLite automatic evidence provider，覆盖 missing、collision、tamper、renew 与终态 fence。ADR-0035/0024 已增加 approval.recover Policy、稳定 User + 五分钟内强认证门禁，以及与 human resolution 同事务提交的 version-fenced authorization fact。ADR-0036 又增加 recovery-first、单 timer、分 Profile 硬预算与跨周期 cursor 的本机 lifecycle core。

这些核心仍没有 production lifecycle，run.create provider 也没有生产 plan source 或注册入口。以下内容完成前，ADR-0032 的 dispatcher 与本 ADR resolver 都继续 production unreachable：

• run.create immutable plan 的生产 resolver、preview builder 与 API/审计入口；
• profile lifecycle 的 production registry/startup/shutdown 装配、指标、告警和积压/最长年龄门禁；
• 真实 MFA/hardware/local-console authentication adapter，以及人工恢复 API/UI、rate limit 和对外错误屏蔽；
• PostgreSQL adapter 与 cluster 多副本竞争测试；
• 原子 receipt 的断电、磁盘满、损坏、认证和 retention 测试。

影响

正面影响：

• post-start crash 不会被普通重试放大为重复副作用；
• 可查询的内部/外部动作能够基于证据自动收敛；
• 无恢复能力的 Shell/Tool 会诚实暴露为人工队列；
• edge 使用有界索引和按需 lifecycle，cluster 使用独立 recovery fencing；
• 所有人工“再做一次”都需要新的审批和审计身份。

代价与风险：

• 每个真实 handler 必须额外实现并测试恢复证据 contract；
• recovery control、resolution 和 receipt/journal 增加存储与运维面；
• provider 不支持幂等查询时不能自动恢复，可能长期积压；
• 强认证和人工处置 UI/API 会成为生产启用前的硬依赖；
• 即使证据协议完整，也只能在具体下游 contract 范围内声明幂等收敛，不能泛化为跨系统 exactly-once。

未选择的方案

1. lease 过期后使用同一 idempotency key 重发：不是所有 provider 都正确实现幂等，且请求可能包含不可重复语义，拒绝。
2. receipt 缺失视为失败：缺失不能证明副作用没有发生，拒绝。
3. 进程退出或日志出现 success 视为成功：身份和完整性不足，拒绝。
4. 把 recovery_required 写成普通 due 状态：容易被通用 dispatcher 领取并重放，拒绝。
5. 允许管理员重置为 pending：绕过新审批并隐藏重复副作用风险，拒绝。
6. 每个 action 一个 watcher/timer：不满足 edge 资源预算，拒绝。
7. cluster-control 读取本地 receipt：多副本不可见且故障转移丢失唯一证据，拒绝。

验证要求

• expired executing 只进入 recovery scan，永不进入普通 due/claim/execute；
• recovery evidence provider 的 contract 证明 inspect side-effect-free，并覆盖 missing/conflict/unavailable；
• receipt exact-shape、大小、identity/digest/fence/authentication 任一不匹配均 fail closed；
• recovery control claim/renew/result 具备 owner/token/version fencing 与有界 keyset；
• 自动 resolution 与 execution 终态同事务提交，失败不留下“已解决但仍 executing”或相反状态；
• 迟到 completion 与 resolver 并发只有一个 winner，精确重放幂等、字段漂移冲突；
• manual resolution 在提交时复验 User、approval.recover、Project/RoleBinding version 和 expected execution version；
• manual path 没有 retry/reset，重复动作必须获得新 approval/dispatch；
• edge lifecycle 无 watcher、无每动作 timer、页/退避/单周期工作量有硬上限；
• cluster adapter 不依赖本地文件，并通过多副本 recovery claim contract；
• production wiring 搜索证明 run.create handler/provider、resolver 和 recovery API 均未被旧路径导入。