qinglong/docs/adr/ADR-0031-approval-request-and-durable-action-dispatch.md

# ADR-0031：ApprovalRequest 与 Durable Action Dispatch

- 状态：Proposed
- 日期：2026-07-19
- 关联：QL-RFC-0001、ADR-0028、ADR-0030

## 上下文

ADR-0028 已规定 Agent 的写、Secret、管理和 Tool call 即使角色允许也只能得到 `require_approval`，但此前没有持久化审批状态机。若调用端把 `require_approval` 当成 allow，或只保存一个可修改的 prompt/preview，Agent 可以在人工确认后替换参数；若审批后直接执行外部副作用，进程在“标记已消费”和“真正执行”之间崩溃，又会在重复执行与永久丢失之间二选一。

审批还必须同时适配资源很小的路由设备和集群控制面。edge 不能依赖常驻 expiry timer、全表扫描或大型 JSON；cluster 则必须能够用事务、行锁、版本和 fencing 裁决多个控制面节点。审批后发生 Project archive、RoleBinding revoke 或角色变更时，旧授权也不能继续穿透当前 Policy。

## 决策

### 1. Approval 绑定不可变动作身份，不保存动作明文

`ApprovalRequest` 保存：

- Project ID、request ID 和单调 version；
- 精确 `ProjectPermission`；
- 有界 `actionType` 与 opaque `actionRef`；
- canonical action payload 的 SHA-256 `actionDigest`；
- 用户可见安全预览的 SHA-256 `previewDigest`；
- `low|medium|high|critical` risk；
- requester ActorRef、请求时间和绝对过期时间。

数据库不保存 prompt、Tool arguments、Shell、Secret 值或任意 `preview: unknown`。产品层需要展示预览时，必须从独立、受授权的 Artifact/plan 读取安全预览，并验证 `previewDigest`；真正消费时由执行计划重新计算 `actionDigest` 并精确匹配。`actionRef` 只是定位 durable plan，不是授权本身。

request ID 同时是创建幂等身份。相同 ID 与相同不可变字段返回当前资源；ID 相同但 action/risk/requester/时间漂移返回 conflict。

### 2. 持久状态与有效过期分离

持久状态机为：

```text
pending@v1 -> approved@v2 -> consumed@v3
           -> rejected@v2
```

`expired` 是 `now >= expiresAt` 且持久状态仍为 `pending|approved` 时的有效状态，不需要后台 timer 写库。决定和消费都在精确边界前完成；`now == expiresAt` 已过期。首版审批寿命最大 24 小时，审批不会延长原 expiry。

`rejected`、`consumed` 为终态。未来若增加 cancel、supersede 或 re-open，必须新增显式 version/state 和 migration，不能覆盖历史决定。

### 3. 决定只能来自当前被授权的稳定 User

决定审批必须同时满足：

1. `decidedBy` 是稳定 `user` ActorRef；
2. requester 与 decider 不同；
3. 当前 Project Policy 对 decider 的 `approval.decide` 返回 `allow`；
4. 写事务内 Project version 和 decider RoleBinding version 仍等于 Policy 读取时的 fence。

Agent、API App、MCP Client、Worker 和 System 首版不能决定审批。Agent 即使拥有高角色也不能形成递归“审批自己的审批”。身份认证、MFA/rate limit 与 wire 层审计仍是生产接入门禁，本 ADR 不把一个裸 ActorRef 当成认证证据。

### 4. 创建和消费都重新验证 Policy fence

创建只接受 Policy effect 为 `require_approval` 的动作；`deny` 和 `allow` 都不创建冗余审批。消费前重新对原 requester、Project 和原 permission 求值：只有 `allow|require_approval` 可以继续，`deny` 或 unavailable fail closed。

每次 mutation 都携带同一次 Policy resolve 返回的 `{projectVersion,bindingVersion}`。SQLite adapter 在 `BEGIN IMMEDIATE` 事务内重新读取当前 Project/RoleBinding version；不一致返回 fence conflict。这样审批与 Role revoke/archive 竞争时，只有一个顺序能提交。所有受支持的 Project/Role mutation 都必须递增或 append version，否则属于存储损坏。

PostgreSQL adapter 必须保持相同 contract，可用行锁或等价条件更新实现；不得只在 application 层先查后写。

### 5. 消费审批必须同事务创建 durable dispatch

`approved` 不等于副作用已执行。一次性消费在同一数据库事务完成两件事：

1. `ApprovalRequest approved@v2 -> consumed@v3`；
2. 创建唯一 `ApprovedActionDispatch`，复制 Project、permission、action identity、requester、consumer 和时间。

若 dispatch 插入、状态更新或 fence 校验任一步失败，事务整体回滚，Approval 仍可安全重试。`consumptionId` 与 `dispatchId` 都是有界幂等身份；完全相同的重放返回同一 dispatch，任一字段漂移返回 conflict。每个 Approval 只能关联一个 dispatch。

这提供的是“一次性授权消费 + durable handoff”，不是外部副作用的 exactly-once 保证。后续 Dispatcher/Executor 必须从 durable dispatch claim，使用 lease、owner/token/version fencing，并要求下游 action identity 幂等；不得在 Approval transaction 内直接调用网络、Shell 或 Tool。

### 6. Edge 与 Cluster 使用同一语义、不同 adapter

edge/standalone 使用 SQLite 点查、唯一索引和短 `IMMEDIATE` 事务；过期按读时计算，空闲时零 timer、零周期写。pending/actor/dispatch 索引为后续 UI 与 dispatcher 提供有界 keyset 查询，不能做无界 offset 扫描。

cluster-control 使用 PostgreSQL adapter、同一状态/version/幂等 contract 和适合多节点 claim 的行锁；`ApprovedActionDispatch` 的后续 claim schema 由 ADR-0032/`0021` 以独立 execution control 增量演进。edge 不因此依赖 PostgreSQL、消息队列或外部缓存。

### 7. 当前切片保持 production unreachable

本切片实现 `0020`、domain/port、Policy fenced SQLite repository、application service 和 contract tests，但没有：

- `/api/v3` Approval route、UI、SSE/Event 或审计 exporter；
- legacy session/identity 到 `AuthenticatedPrincipal` 的生产装配；
- owner bootstrap 的可信 issuer，因此默认 Project 仍没有 owner；
- preview Artifact/plan resolver 和 canonical action digest builder；
- 真实 ApprovedAction handler、下游 idempotency receipt 和 `recovery_required` resolver；
- PostgreSQL adapter、跨方言 contract suite、rate limit 和 MFA 产品策略；
- Run `waiting_approval` 的事务性暂停/恢复装配。

因此生产代码不得导入或调用该 service，也不得把 pending dispatch 直接交给现有 `ScheduleService`、Shell 或 Tool。完成 wire、审计、digest builder、dispatch executor 与部署门禁前，现有 2.x 行为保持不变。

## 影响

正面影响：

- 人工审批精确绑定不可变动作，参数替换会被 digest 拒绝；
- Role revoke、Project archive 与审批 mutation 有事务 fence；
- 消费后崩溃不会丢失已授权动作，durable dispatch 可恢复；
- edge 无常驻 expiry timer，表和索引均有界；
- 创建、决定和消费均支持精确幂等重放与并发裁决。

代价与风险：

- Approval 与 dispatch 各增加一张表和短写事务；
- 产品层必须建立 canonical action/preview 生成规范，digest 不能由 Agent 自报后直接信任；
- durable dispatch 已由 ADR-0032 增加独立 claim/lease/result 状态机，但仍缺真实 handler、recovery resolver 和生产 lifecycle，当前不能执行副作用；
- Policy version discipline 成为安全不变量，绕过 Repository 直接改表会破坏 fence。

## 未选择的方案

1. **直接保存 `preview: unknown` 并批准该 JSON**：可能泄漏 Secret、形状无界且难以 canonicalize，拒绝。
2. **批准 Tool 名，不绑定参数 digest**：审批后可替换目标和参数，拒绝。
3. **审批后同步调用 Tool/Shell**：数据库事务无法覆盖外部副作用，崩溃窗口不可恢复，拒绝。
4. **先标记 consumed，再投递内存队列**：进程崩溃会永久丢失动作，拒绝。
5. **审批永久有效**：Role/plan/风险会漂移，拒绝。
6. **Agent 或 System 自动决定审批**：绕过人工边界并产生递归授权，首版拒绝。
7. **每秒 timer 把过期行改成 expired**：edge 空闲写放大且没有必要，拒绝。

## 验证要求

- migration/schema ownership 覆盖两张表、唯一索引和 tuple/state constraint；
- 明文 preview、参数和 Secret 不进入 Approval/dispatch 行；
- 创建只接受 `require_approval`，决定只接受有 `approval.decide` 的 User；
- request/decision/consumption ID 的精确重放成功，漂移冲突；
- `now == expiresAt` 的决定和消费被拒绝；
- Policy version 变化使同事务 fence 失败；
- 双 SQLite 连接竞争决定或消费时只有一个提交；
- dispatch 冲突会回滚 Approval consumption；
- consume 后恰好存在一个匹配 digest 的 pending durable dispatch；
- Node 22/24 全量测试、类型检查、完整 migration chain schema audit 与 GitNexus reachability 通过；
- `app/loaders/api/services/shared/data` 不得导入 Approval core。