qinglong/docs/adr/ADR-0165-trusted-tool-terminal-failure-completion.md

ADR-0165：Trusted Tool 失败与超时终态完成协议

• 状态：Accepted
• 日期：2026-07-26
• 关联：ADR-0156、ADR-0158、ADR-0162 至 ADR-0164；RFC D-152 至 D-154

背景

ADR-0163/0164 已关闭 Trusted Tool 的成功持久化与 Profile-neutral 成功协调， 但 adapter 明确失败和 deadline 到期仍会让 StepRun 停留在 running。如果每个 Profile 自行解释异常，低配路由设备和集群节点会产生不同的终态、重试和敏感信息 持久化语义；若把异常对象、stack 或未知 output 写进 RunEvent，又会扩大泄露面。

失败终态还必须与成功 completion 竞争收敛。仅在应用层先查一次成功记录不能证明 互斥：并发调用、事务提交响应丢失和 PostgreSQL 主库切换都可能让调用者观察到未知 结果。

决策

1. 失败完成只保存固定低敏事实

runtime-core 新增显式 subpath @qinglong/runtime-core/tool-execution-failure-completion。v1 只接受：

• failed：tool_adapter_failed / Trusted Tool execution failed；
• timed_out：tool_deadline_exceeded / Trusted Tool execution deadline exceeded。

completion 必须绑定 exact start、Project、Run、StepRun、Tool、adapter、Run version、 event sequence、mutation 和 event identity。它不保存 raw error、stack、adapter output， 也不创建 Result Artifact 或取得 result key authority。

2. 成功与失败 completion 必须原子互斥

SQLite 与 PostgreSQL 各增加 append-only failure completion 表和 repository。失败提交 必须在一个事务内完成：

1. 复验 start barrier、当前 running Tool StepRun、非 terminal Run；
2. 拒绝同一 start 已存在的成功 completion；
3. 将 StepRun 原子迁移到 failed 或 timed_out，保持 outputRef=null；
4. 推进 Run version/event sequence；
5. 写入固定低敏 RunEvent、StepRunMutation 与 failure completion。

成功 repository 同样必须在事务内拒绝同一 start 的失败 completion。SQLite 使用 BEGIN IMMEDIATE 串行化双方竞争；PostgreSQL 使用 serializable transaction，并锁定 exact StepRun/Run。两侧都只允许完整命令 exact replay，任何部分身份复用、跨表镜像 漂移或同时存在成功/失败记录都失败关闭。

SQLite capability 推进到 v32，共 55 张受管表；PostgreSQL control-core capability 推进到 v33。PostgreSQL runtime role 对 failure completion 只取得 SELECT, INSERT， admin、Package manager、Package executor、Worker ingress 与 PUBLIC 默认拒绝。

3. 一个协调器裁决所有 Tool 终态

runtime-core 新增显式 subpath @qinglong/runtime-core/trusted-tool-completion，由 executeAndCompleteTrustedTool 固定编排：

1. 执行 adapter 前同时读取 durable success/failure winner；
2. 只有两者均不存在才调用既有 Trusted Tool execution；
3. adapter 抛错后再次读取 durable winner，先收敛并发或未知提交结果；
4. 只把明确的 TrustedToolExecutionFailedError 归类为 failed；
5. 只把明确的 TrustedToolExecutionDeadlineExceededError 归类为 timed_out；
6. Artifact、key、binding、snapshot、storage 等缺失或损坏继续保持非终态并失败关闭；
7. failure commit 响应丢失后只读取 durable winner，同一次调用不得重新执行 adapter。

返回值是 succeeded | failed | timed_out 的判别联合。固定 system actor、start-derived dedupe、mutation 和 event identity 均由协调器生成，不接受 transport 注入。

4. 保持双 Profile 的资源边界

现有 LocalSqliteTrustedToolStorage 与 ClusterTrustedToolStorage 增加 failureCompletions port，不新增 workspace package或第三方依赖：

• edge/standalone 仍使用首次请求才动态加载的 SQLite 单例 bundle，不新增连接、 timer、watcher 或 socket；
• cluster-control 仍只通过受审 @qinglong/cluster-postgres/runtime 组合入口， 在现有单一 Pool 上装配同构 bundle；
• runtime-core root、PostgreSQL root/admin/ingress 和生产 transport 不获得执行 authority；生产 allowlist 仍只有 run.get 与 run.cancel。

被否决方案

1. 把异常序列化进 Artifact 或 RunEvent：扩大敏感信息面，且失败终态不需要解封。
2. 只有失败 repository 检查成功记录：晚到的成功事务仍可穿透，无法证明互斥。
3. 用任意异常自动终态化：会把 key 丢失、binding 漂移或数据库不可用误报为业务失败。
4. 协调器捕获后重跑全部流程：会重复 adapter 副作用。
5. 为两个 repository 各拆一个 package：没有独立部署或依赖边界，只会加重 路由设备安装、构建与审计成本。
6. 因终态闭环而开放生产 route：result key 生命周期、人工恢复和专属故障注入 尚未完成。

验证

• runtime-core：331/331，覆盖成功、失败、超时、固定事实、并发 winner、响应丢失、 adapter-call-count=1、前置条件缺失保持非终态和显式 subpath；
• local-sqlite：119/119，真实 SQLite 覆盖原子失败提交、exact replay、成功/失败双向 排斥、固定事实与 lazy storage bundle；
• cluster-postgres：181 pass / 1 条件 skip，覆盖事务 SQL、双向排斥、typed schema、 migration checksum、readiness、六角色权限和 composition entrypoint；
• cluster-control：139 pass / 2 条件 skip，覆盖单 Pool storage 装配与依赖边界；
• 21 个 QL3 workspace package 全量 build/test 为 0 fail，package 数量和第三方依赖 均未增加；edge import、cluster dependency、cluster deployment 审计无 finding；
• 全新 PostgreSQL 18 六角色真库 integration：42 pass / 1 条件 skip / 0 fail，直接 覆盖 timed_out 原子提交、exact replay、晚到成功拒绝、固定低敏事实与无 output 明文；
• PostgreSQL 18.4 arm64 物理 HA 总门 passed=true：remote_apply、timeline 1→2、 旧主 fencing、双 control replica 重新 activation、pg_rewind 只读同步重加入及 既有领域 COMMIT-response-loss 门全部通过。该 HA fixture 尚未注入 Trusted Tool failure completion 专属 COMMIT-response-loss，不能用通用事务门替代该证据。

后续门禁

1. 在真实 PostgreSQL 上执行新增 terminal completion integration，并给 Tool completion 注入 COMMIT-response-loss、主库晋升后 durable winner 和 adapter-call-count=1；
2. 给 SQLite 增加 adapter 返回后、failure/success 事务提交前后的进程 crash 矩阵；
3. 建立 result key catalog、rotation、retention/rekey 与 key-lost 人工恢复；
4. 按 Project current snapshot 构造短生命周期 adapter registry，再评审产品 use-case/transport 入口。