qinglong/docs/adr/ADR-0158-atomic-tool-execution-start-barrier.md

ADR-0158：同事务 Tool Execution Start Barrier

• 状态：Accepted
• 日期：2026-07-26
• 关联：ADR-0032、ADR-0133、ADR-0154、ADR-0155、ADR-0156、ADR-0157； RFC D-03/D-29/D-30/D-131/D-148/D-149

背景

ADR-0155 已建立 snapshot-bound handler binding 和 fresh Policy admission； ADR-0156 已建立双方言 StepRun aggregate、Run/Event fence 与 mutation ledger； ADR-0157 已能原子保存 Trace、Audit 和 receipt。

但单独 prepare(evidence) 仍不是“允许 adapter 开始副作用”的证明。若 evidence 提交后、 StepRun CAS 前崩溃，数据库会留下允许审计，却没有 running 状态；若先把 StepRun 改为 running 再保存 evidence，则 adapter 或恢复器可能观察到一个没有 Trace/Audit 的已启动 步骤。多副本还可能使用相同 StepRun 发起两个不同调用，或者把一次失败后的重试误判为 第一次启动的重放。

启动授权必须把 immutable plan/admission、耐久 evidence、StepRun 状态变化、RunEvent、 mutation ledger 和可恢复的 barrier 收敛成一个数据库事务，同时保持低配路由器的单连接、 零常驻后台任务边界。

决策

1. 使用纯领域 command 和低敏 barrier record

@qinglong/runtime-core/tool-execution-start-barrier 是现有 runtime-core 的显式 subpath。它定义：

• qinglong/tool-execution-start-command@v1，canonical JSON 最大 64 KiB；
• qinglong/tool-execution-start-barrier@v1，canonical JSON 最大 16 KiB；
• domain-separated commandDigest 与 barrierDigest；
• ToolExecutionStartBarrierRepository 的 prepare、按 startId 查询和按 (runId, stepRunId, startedStepRunVersion) 查询。

command 必须精确绑定：

1. Project、current snapshot、Tool Definition 和 trusted handler binding；
2. action/plan/admission digest、Profile、execution class、timeout 和 Policy fence；
3. reviewed adapter、redaction contract、audit contract 的 identity 与 digest；
4. 可选的 exact approval request/dispatch/digest；
5. 同 Project、同 Run 的 Tool StepRun；
6. Trace anchor、Audit event 与 Audit receipt；
7. ready 或 waiting_approval 到 running 的 StepRun mutation 和对应 RunEvent。

admission、command 和 barrier 都不得携带 input、Secret、handler、函数、module path、 URL、execute seam、Tool output 或原始异常。

2. StepRun 必须先存在，barrier 只负责原子启动

产品编排先创建独立 StepRun，并把它推进到 ready；需要审批时则推进到 waiting_approval 并绑定 exact approval request。start barrier 不创建 StepRun，也不 负责解析 Workflow。

repository 在一个事务中按固定顺序执行：

1. 查找所有 start/replay identity，完全相同则返回 existing；
2. 锁定并复验 Run、StepRun、version、digest、状态、Definition 和 Project；
3. 插入 SecurityAuditEvent、Trace anchor 和 Audit receipt；
4. compare-and-set StepRun 为 running；
5. compare-and-set Run version/event sequence；
6. 插入 RunEvent 和 StepRun mutation ledger；
7. 插入 immutable start barrier；
8. commit 后才允许 composition 调用 adapter。

任一步失败必须回滚全部事实。mutation ledger 的 committed_at_ms 使用数据库事务时钟， 不能把调用方的业务事件时间冒充提交时间。

3. 重试 identity 必须包含已启动的 StepRun version

同一 startId、mutation、RunEvent、Trace、Audit 或 (runId, stepRunId, startedStepRunVersion) 只能绑定同一 barrier。完全相同的响应丢失 重放返回 existing；内容漂移返回 semantic conflict。

identity 不能只使用 (runId, stepRunId)。一个真实 adapter 在恢复后可能把 lost → ready → running 推进到下一次尝试；新的 StepRun version 必须能够拥有新的 barrier，同时历史启动事实保持不可覆盖。

4. SQLite 与 PostgreSQL 使用同一领域协议、不同事务机制

SQLite：

• 0055-tool-execution-start-barriers 新增 ToolExecutionStartBarriers；
• 0056-capability-v28 将 local-control-core 推进到 v28；
• repository 复用单一 LocalSqliteOperationAuthority 和 BEGIN IMMEDIATE；
• foreign key 把 barrier 绑定到 StepRun、mutation、RunEvent、Trace 和 Audit receipt；
• committed_at_ms 使用 SQLite 数据库时钟。

PostgreSQL：

• pg-0030-tool-execution-start-barriers 将 control-core 推进到 v29；
• ql3.tool_execution_start_barriers 只授予 ql3_runtime SELECT, INSERT，其他产品角色无权限；
• repository 使用短 SERIALIZABLE transaction、固定 statement/lock/idle timeout 和最多三次可判定 retry；
• Run 与 StepRun 在 evidence 写入前一起 FOR UPDATE，CAS 失败回滚；
• committed_at_ms 使用 transaction_timestamp()。

两种方言读取时都重新执行领域规范化，并逐项核对 JSON、镜像列、mutation digest、 started StepRun digest、Trace digest 和 Audit receipt digest。损坏或多行 identity 必须失败关闭。

5. 不新增 workspace package

虽然协议跨越领域层和两种存储实现，但它没有独立部署、依赖或版本生命周期，因此：

• 纯领域协议留在 ql3-runtime-core；
• SQLite adapter 留在 ql3-local-sqlite；
• PostgreSQL adapter 留在 ql3-cluster-postgres；
• 三者只通过显式 tool-execution-start-barrier subpath 暴露；
• root、通用 runtime、admin、package executor 和 worker ingress 不重新导出 authority。

文件少不是拆包理由，真实部署/权限/依赖边界才是 package 边界。

6. barrier 仍不执行 adapter

本 ADR 只关闭“副作用开始前是否已经原子提交完整授权事实”的缺口。repository 没有调用 built-in、process、MCP、HTTP 或 Worker adapter。当前 Tool execution 仍保持 production unreachable，直到后续完成：

1. opaque/encrypted invocation plan 与 redacted preview Artifact；
2. adapter-specific start/result/recovery contract；
3. trusted composition 在观察 created|existing barrier 后调用 adapter；
4. post-start 不确定结果的 inspect/manual recovery；
5. receipt retention/compaction 与物理 Edge 资源证据。

低配与集群资源影响

• 不新增 package、第三方依赖、timer、watcher、socket、线程或常驻进程；
• Edge/standalone 继续复用一个 SQLite authority 和一次 BEGIN IMMEDIATE；
• Cluster 每次启动只使用一个有上限的短事务，不引入队列、Redis 或新控制副本；
• 每次启动新增一条 immutable barrier，并复用既有 Audit、Trace、RunEvent 和 mutation ledger；
• 唯一索引与 exact identity 提供常数级重放查找，历史尝试不被覆盖。

被否决方案

1. evidence 提交后再单独更新 StepRun：存在半提交窗口，拒绝。
2. 先更新 StepRun，再异步写 Trace/Audit：允许观察到无证据的运行态，拒绝。
3. 用 RunEvent 代替独立 barrier：无法完整绑定 admission、adapter contract 和 evidence digest，拒绝。
4. 只以 StepRun ID 作为唯一启动 identity：阻止合法的新 version 重试，拒绝。
5. 把调用方时间写入 committed_at_ms：混淆业务时间与数据库提交观察，拒绝。
6. 在事务中直接调用 adapter：把外部 I/O 放入数据库锁窗口且仍无法原子提交外部 副作用，拒绝。
7. 为 barrier 新增 workspace package：没有独立部署或依赖生命周期，拒绝。
8. 把 authority 从 cluster runtime/admin root 导出：扩大可达性与数据库权限， 拒绝。

验证

• runtime-core 完整测试：309/309；
• local-sqlite 完整测试：111/111，其中 start barrier repository 5/5；
• cluster-postgres package：166 pass、1 条件 skip，其中 start barrier repository 4/4；
• 全新 PostgreSQL 18.4 arm64 六角色 integration：41 pass、1 条件 skip、0 fail；
• 真实 PostgreSQL 用例证明 migration v29、runtime 最小权限、同事务启动、exact replay、 双查询入口和数据库提交时钟；
• PostgreSQL 18.4 arm64 physical HA：physical streaming、remote_apply、 timeline 1→2、旧主 fencing、promotion、pg_rewind、同步复制恢复和两代双 control replica，gates.passed=true；
• 临时单实例与 HA Docker 资源均由 gate 清理。

后续门禁

1. 设计 invocation plan/preview Artifact 的加密、脱敏与 retention；
2. 实现第一类真实 built-in adapter 与 post-start recovery evidence；
3. 用产品 composition 串联 snapshot publication、StepRun、start barrier 和 adapter；
4. 增加 response-loss、进程崩溃、MCP/HTTP 超时和人工恢复实证；
5. 完成 physical Edge idle/fault/task-scale 门后再开放 production execution。