qinglong/docs/adr/ADR-0408-cluster-copilot-failure-diagnosis-tool-execution.md

ADR-0408：Cluster Copilot Failure Diagnosis Tool Execution

• 状态：Accepted
• 日期：2026-08-15
• 关联 RFC：QL-RFC-0001 D-316、Phase 2
• 关联 ADR：ADR-0163、ADR-0226、ADR-0403、ADR-0405、ADR-0406、ADR-0407

问题

ADR-0407 只把故障诊断原子接纳为独立 Run、一个 ready Tool Step 和一个依赖它的 pending Model Step。系统仍不能执行该 Tool，也不能在崩溃、响应丢失或 PostgreSQL 主库切换后证明 Tool 是否已经产生副作用、结果是否已经加密持久化，以及 Model Step 是否可以安全解锁。

若 Copilot 绕过共享 Trusted Tool start/completion 协议直接读取日志，重放可能重复执行 adapter；若先解锁 Model 再写 completion，模型可能读取缺失、失败或未验证的结果；若复用 Prompt output key 或让 projected file 决定 Tool result active generation，又会合并本应独立的 密钥域和 durable authority。

决策

1. 新增 Copilot failure-diagnosis Tool execution coordinator。它只接受 ADR-0407 已持久化的 requestId，重新读取并规范化 exact admission plan/receipt、当前 Project Tool snapshot 和 invocation input/preview Artifact；任何 plan、Definition、binding、Artifact 或 source fence 漂移均在日志读取前失败关闭。
2. coordinator 复用 Runtime Core 的通用 Trusted Tool execution evidence、start barrier、 encrypted success/failure completion、result catalog 和 rekey 协议，并只装配内建 qinglong.run.log.excerpt@1.0.0 adapter。start/completion 使用从 plan 稳定派生的 identity； exact replay 首先打开 durable barrier/completion，不再次读取日志或执行 adapter。
3. invocation Artifact 使用独立的 Cluster projected keyring。它包含一个 active key 和最多 16 个历史 key，提供 active() 与 resolve(keyId)，每次调用重新读取 canonical 32-byte material，不使用 cache、watcher 或 timer，并复用既有 projected-file 的 canonical path、 symlink、权限、inode/size/mtime 和双 realpath fence。Tool result keyring 仍保持 resolve-only， PostgreSQL result catalog 继续独占 active/decryptable generation authority；两个密钥域不得互换。
4. 只有规范化且与 admission exact 绑定的 succeeded Tool completion 才能解锁 Model Step。 pg-9019-ai-copilot-failure-diagnosis-tool-unlocks 新增 append-only unlock ledger；一个 SERIALIZABLE 事务同时把 Model Step 从 pending 推进到 ready、递增 Run version/event sequence、写 RunEvent、StepRunMutation 和不可变 unlock receipt。Tool failed|timed_out completion 不解锁 Model，也不伪造最终 diagnosis 结论。
5. unlock transaction 重新锁定并验证 admission、success completion、当前 Model Step 和 running diagnosis Run；serialization/deadlock 只在事务提交前有界重试。response-loss replay 必须返回 结构完全一致的 receipt；缺失关联事实、旧 fence、不同 digest 或部分写入全部视为冲突/损坏。
6. ql3_runtime 对 unlock ledger 只有 SELECT, INSERT，没有 UPDATE, DELETE；数据库外调用者 不能直接把 Model Step 改为 ready。Tool execution 与 PostgreSQL storage 分别通过精确 AI subpath 发布，纯 execution 入口不隐式 re-export PostgreSQL repository。
7. 本 Gate 到 Model Step ready 为止，不调用模型、不持久化模型明文、不终态化 diagnosis Run。 ADR-0405 prompt builder、Model Gateway、Copilot 专用 encrypted model completion、失败/取消/ deadline terminalization 和产品 API 属于后续 Gate。
8. 能力内聚在既有 @qinglong/ai 与 @qinglong/cluster-control 的领域子目录，不新增 workspace package、依赖、进程、Pod、连接池、listener、daemon、timer、watcher 或 cache。默认 Edge/ Standalone 不导入 Cluster execution；显式本地 AI 制品也不会取得 PostgreSQL/S3 authority。

被否决方案

1. Copilot 自建一套 Tool completion：会分叉 start barrier、加密 Artifact、rekey 与恢复语义。
2. admission 后直接调用日志 reader：响应丢失时无法区分“未执行”和“已执行但未返回”。
3. Tool 一启动就解锁 Model：允许模型消费未完成、失败或未认证的结果。
4. 把失败 Tool completion 当成可诊断输入：当前没有经过审定的失败 Prompt/terminalization 协议，会把基础设施错误伪装成业务诊断。
5. 共用 Prompt output/result/invocation keyring：混淆密钥用途、active authority 与退役范围。
6. 为 keyring 或 coordinator 新建 package：没有独立部署/ownership 边界，并会继续加剧包碎片化。

当前验证

1. admission/execution/unlock 与 migration/readiness 聚焦契约 21/21，projected invocation keyring 2/2；AI package 最终为 229 pass、3 条件 skip、0 fail，类型检查通过。
2. 18 个 QL3 package 的 clean build/test 全部退出 0；backend 为 1,207 pass、2 条件 skip、 0 fail。
3. package boundary、Cluster dependency、Edge import 和 Cluster deployment 四项审计均 compatible 且零 finding。workspace 仍为 18 个 package，singleSourcePackages=[]、 shallowSourcePackages=[]；AI 175 个源码中 174 个、Cluster Control 56 个中 54 个位于 嵌套领域目录。
4. 14 档 Local Profile artifact 全部通过。默认 Edge/Standalone 为 2,589,890 / 2,589,968 bytes；显式 Edge/Standalone AI 为 3,135,809 / 3,135,899 bytes；最大 Standalone MCP 为 7,316,038 bytes，均在各自门内。
5. PostgreSQL 18.4 arm64 physical HA 为 130/130 Gate、timeline 1→2。门证明首次 Tool 执行只 读取两次日志、密文 JSON 不含敏感 fixture 文本、Model Step 原子进入 ready；主库提升后 exact replay 的日志读取为零。报告 SHA-256 为 d525a303696e178d777b021b376729bd2c5382fb5eb7bc98466a2b79d3940517，独立审计零 finding， 临时 Docker 资源已清理。

后续门禁

1. 从 durable Tool completion 解密受信投影，经 ADR-0405 builder 生成 prompt，并通过 Model Gateway 执行 provider credential、egress policy、quota、price 和 deadline fence。
2. 建立 Copilot 专用 encrypted model completion 和 response-loss recovery；模型输出不得进入 普通 completion、数据库 JSON、审计或日志明文。
3. 原子终态化 Model Step 与 diagnosis Run，并覆盖 Tool/Model 失败、取消、超时、未知结果和 主库切换后的恢复状态机。
4. 最后再开放默认关闭的 Cluster API/CLI/UI/MCP 产品入口，并补真实 S3、外部 Provider fault injection、多副本并发和 plaintext negative evidence。