qinglong/docs/adr/ADR-0034-approved-run-action-atomic-receipt.md

# ADR-0034：Approved Run 创建与原子恢复回执

- 状态：Proposed
- 日期：2026-07-19
- 关联：QL-RFC-0001、ADR-0031、ADR-0032、ADR-0033、ADR-0014

## 上下文

ADR-0032 已经建立 Approved Action 的 durable start barrier，ADR-0033 也规定恢复只能读取可信证据，不能再次调用 `execute`。但在没有真实 handler 和 evidence provider 时，这套协议只能证明何时不得重放，不能证明任何一种业务动作如何安全收敛。

Run 创建适合作为第一个内部数据库动作：它有稳定的 Project/Task/revision 身份、数据库唯一幂等键和明确的持久化成功边界。不过，仅把 `dispatchId` 写入 `Runs.idempotency_key` 仍不足以成为恢复证据。其他写入者可能抢占同一 key，Run 也没有保存 approval/action digest/execution fence；根据一条碰巧存在的 Run 推导审批动作成功会造成身份混淆。

因此需要一个与 Run 聚合同事务提交、完整绑定审批和 execution identity 的专用 receipt，并让恢复 provider 同时验证 receipt 与 Run 事实。

## 决策

### 1. 首个真实 action 类型是 `run.create`

`ApprovedRunCreationPlan` 是版本化、exact-shape、无 Secret 的不可变计划，首版只包含：

- `schemaVersion=1`、opaque `actionRef`、Project ID；
- Task ID、固定 Task revision；
- Executor type、priority；
- 可选低敏 task name、task snapshot ref 和 input ref。

canonical digest 使用固定字段顺序和显式 null 表示缺失可选字段，并把 `actionType=run.create` 纳入 SHA-256。inspect 只能解析计划、校验 Project/actionRef 并返回 digest；它不能创建 Run。execute 会再次解析同一 immutable plan，防止 inspect 与 start barrier 之间发生内容漂移。

创建出的 Run 使用：

- `trigger_type=approved_action`、`execution_origin=system`、`execution_owner=runtime`；
- `request_id=approvalRequestId`；
- `idempotency_key=dispatchId`；
- `accepted_at=execution.startedAtMs`。

本 action 的成功只表示 Run 聚合与初始 Attempt 已原子创建、Run 已进入 `queued`，不表示任务最终执行成功。

### 2. `0023` receipt 与 Run 在同一事务提交

`ApprovedRunActionReceipts` 以 `dispatch_id` 为主键，并通过唯一 `(resource_type,resource_id)` 防止一条 Run 被多个 dispatch 声明。receipt 固定绑定：

- schema version、dispatch/approval/Project；
- action type 和 canonical action digest；
- execution attempt、实际提交时看到的 execution version、start time；
- `idempotency_key=dispatchId`；
- `outcome=succeeded`、bounded result code；
- `resource_type=run`、Run ID、finish/create time；
- 对以上全部 canonical 字段计算的 evidence SHA-256。

SQLite adapter 使用一个 `BEGIN IMMEDIATE`：先在事务内复验当前 execution 仍为 `executing`，Project、attempt、startedAt、owner/token 均匹配，再创建 Run/Attempt/Event，最后插入 receipt。任一 Run、Event、receipt、约束或 commit 失败都会整体回滚，不允许留下“Run 已存在但可信 receipt 缺失”的合法成功路径。

### 3. renew 可以前进 version，但不能改变 execution identity

handler 获得的 context 可能在执行期间发生同 owner/token renew。事务内复验允许数据库 execution version 大于 handler context version，但必须保持：

- 同一 dispatch、Project 和 attempt；
- 同一 `startedAtMs`；
- 同一 owner/token；
- 状态仍是 `executing`。

receipt 保存事务实际读取到的当前 version。若 recovery/manual resolution 或 normal completion 已先推进终态，状态复验会在任何 Run 写入前拒绝旧 handler。这样 renew 不会把真实 receipt 误判为旧 attempt，终态也不会被陈旧 execute 绕过。

### 4. recovery provider 只读 receipt 和 Run

`LegacySequelizeApprovedRunRecoveryEvidenceProvider` 没有 execute 能力，只执行有界主键/唯一键读取：

- receipt 缺失且同 idempotency key 的 Run 也不存在：`missing`；
- receipt 缺失但存在 key collision：`conflict`，不能把碰撞 Run 当成功；
- receipt exact-shape、digest、approval/action/attempt/start/version 边界任一不匹配：`conflict`；
- receipt 匹配但 Run/Attempt、Project、request、origin/owner/trigger 不匹配：`conflict`；
- 全部匹配：`verified_succeeded` 并返回 receipt evidence digest；
- 数据库不可用或查询失败：抛出，由 reconciler 转成 `unavailable`。

provider 允许 receipt version 小于当前 recovery snapshot version，因为同一 execution identity 可以在 receipt 提交后续租；receipt version 大于当前 snapshot 则视为 conflict。它不从 Run 最终状态推导本 action 的结果，因为本 action 只负责创建 Run。

### 5. 重放只接受完整 receipt

相同 dispatch 再次进入 repository 时，只有完整 receipt 和绑定 Run/Attempt 全部匹配才返回原 Run 引用。只存在 `Runs(project_id,idempotency_key)` 而没有 receipt 时稳定冲突，不补写 receipt、不重新解释历史来源，也不创建第二条 Run。

### 6. 当前仍保持 production unreachable

本切片新增了真实 `run.create` handler、SQLite 原子 repository 和 automatic evidence provider，但没有把它们注册到 app、loader、service、API 或任何 lifecycle。生产启用仍至少需要：

- immutable plan 的真实持久化 resolver、preview builder 和管理入口；
- dispatcher/reconciler 的 profile-aware lifecycle、指标、告警和积压门禁；
- 真实强认证 adapter、人工恢复 API/UI、rate limit 和审计产品入口；
- PostgreSQL action/receipt/provider adapter 与多副本 contract；
- SQLite 断电、磁盘满、WAL、损坏与固定 edge 设备资源门禁；
- Run admission、Secret/Artifact policy 与实际 Executor 产品入口的联合验证。

`run.create` 的内部数据库原子性不能推广为任意 Tool、Shell 或外部 API 的 exactly-once；其他 action 仍必须各自提供可认证 receipt/query contract，无法提供时保持 `manual_only`。

## 影响

正面影响：

- 首次以真实业务 mutation 验证了 start barrier、atomic receipt 和 evidence-only recovery 的完整闭环；
- receipt 缺失不会被误判为失败或成功，幂等 key collision 明确 fail closed；
- 同事务写入适合 edge/standalone，无 watcher、每动作 timer 或全表扫描；
- renew 和终态并发具备清晰 fence，不依赖 wall clock 猜测 winner。

代价与风险：

- 每次 Approved Run 创建增加一行小型 receipt 和一次同事务 insert；
- receipt 表与 Run 生命周期形成保留关系，后续 retention 必须按 dispatch/audit 规则设计；
- 当前只有 SQLite adapter，cluster-control 不能共享本地数据库或本地 receipt；
- 仅证明 Run 创建成功，不证明 Run 执行结果或下游任务副作用。

## 未选择的方案

1. **只查询 `Runs.idempotency_key=dispatchId`**：没有 approval/action/fence 绑定，拒绝。
2. **Run 提交后另一个事务补 receipt**：崩溃窗口会产生不可判定的合法成功，拒绝。
3. **receipt 缺失时补写或重新 create**：无法证明原 Run 来源且可能重复动作，拒绝。
4. **receipt 绑定固定 start version 并要求永远相等**：合法 renew 会制造假 conflict，拒绝。
5. **根据 Run 最终 succeeded/failed 裁决创建动作**：混淆“创建 Run”和“执行任务”两种 action 结果，拒绝。
6. **立即接入 production dispatcher**：缺 lifecycle、强认证、PostgreSQL 和设备门禁，拒绝。

## 验证要求

- canonical plan 对字段顺序稳定，未知字段、非法版本和越界内容 fail closed；
- `0023` 被 migration/schema ownership 覆盖，索引和 tuple constraints 可审计；
- Run/Attempt/Event/receipt 同事务，receipt 插入故障时 Run 全部回滚；
- 相同 dispatch 精确重放只返回一条 Run 和一条 receipt；
- receipt/action/resource/digest 任一篡改返回 conflict；
- receipt 缺失返回 missing，幂等碰撞返回 conflict；
- 同 owner/token renew 后写入实际 execution version，并可被 recovery snapshot 验证；
- execution 已终结时，陈旧 handler 在 Run 写入前被 fence；
- production reachability 搜索证明 app/loaders/api/services/shared/data 未导入 handler、repository 或 provider；
- Node 22/24 全量测试、build、fresh migration 和 schema audit 通过。