qinglong/docs/adr/ADR-0409-cluster-copilot-failure-diagnosis-model-execution.md

ADR-0409：Cluster Copilot Failure Diagnosis Model Execution

• 状态：Accepted
• 日期：2026-08-15
• 关联 RFC：QL-RFC-0001 D-317、Phase 2
• 关联 ADR：ADR-0262、ADR-0405、ADR-0407、ADR-0408

问题

ADR-0408 只把成功的日志 Tool completion 原子解锁为 ready Model Step。若调用方直接把 Tool 返回值留在进程内再调用 Provider，进程重启后无法恢复 prompt；若 Model completion 先于 密文输出写入，COMMIT response loss 会留下“Step 已成功但结果不存在”的分裂状态；若把 Copilot Artifact 继续塞进通用 Model coordinator，则每增加一个 AI 领域都会让核心层反向依赖一个新领域。

同时，diagnosis Run 不能在 Model Step 已终态后永久停留在 running。成功、Provider 失败和 deadline 必须由耐久 ModelInvocation completion 驱动 Run 终态，而不能由一次内存返回值决定。

决策

1. Model executor 只接受 ADR-0407/0408 的 exact admission、unlock receipt 和加密 Tool success。 它通过 Runtime Core 的只读 openTrustedToolSuccessCompletion 重开 ciphertext，复验 barrier、 result catalog/rekey、key material proof、Tool definition 与 completion digest；绝不重新执行 Tool。
2. 只有 available、cluster-control 且 Run/Attempt identity 与 source fence 完全一致的内建日志 projection 才能进入 ADR-0405 builder。其余 Tool 输出不会被转成任意 Prompt，也不会调用 Provider。
3. executor 使用既有 BoundedModelGateway，因此 Provider/model allowlist、egress budget、并发、 deadline、quota、price quote、usage settlement 和 content-free audit 继续由一个通用边界裁决。 Gateway 必须显式安装当前 Copilot successful-completion sink，否则执行失败关闭。
4. Copilot 输出使用独立 qinglong/copilot-failure-diagnosis-output-artifact@v1，AES-256-GCM 密封 完整 GenerateResult。AAD 与 digest 绑定 request/plan/Tool completion/Project/Run/Step/ invocation/provider/model/egress evidence/key；公开 reference 不含 nonce、ciphertext、auth tag 或明文。
5. 通用 DurableModelInvocationCoordinator 不再导入 Plugin Package Prompt Artifact。新增领域无关的 ModelInvocationAtomicSuccess<TReference> 端口，由领域负责 exact replay、冲突类型和方言事务； 原有 Plugin Prompt 通过 adapter 保持行为兼容，Copilot 使用独立 adapter。PostgreSQL 的通用 atomic-output helper 在同一 SERIALIZABLE 事务提交 StepRun/Event、Model completion、usage、 pricing/quota settlement 和领域 ciphertext，任何一步失败均整体回滚。
6. pg-9020-ai-copilot-failure-diagnosis-model-executions 新增两个 append-only ledger： copilot_failure_diagnosis_model_outputs 保存密文 Artifact； copilot_failure_diagnosis_finalizations 保存 content-free Run terminal receipt。ql3_runtime 只有 SELECT, INSERT，其他运行/管理角色不得读写，PUBLIC 无权限。
7. Model completion 提交后，独立可重放的 finalization 事务锁定 diagnosis Run 与 Model Step，复验 plan、completion、成功 Artifact 和当前计数链，再把 Run 推进为 succeeded|failed|timed_out、 写一个 copilot.diagnosis.<outcome> Event 和 receipt。两个事务之间崩溃时，恢复只执行 finalization，不再调用 Provider；Run 的成功 outputRef 只指向密文 Artifact。
8. 已存在 completion 或 finalization 的 replay 永不调用 Provider；只有 start、没有 completion 的 invocation 视为结果未知，禁止自动重试。outcome_unknown 仍必须先走既有显式 resolution，当前 finalizer 不把未知结果伪装成失败。Tool failure、Tool 输出退役/缺失、Model admission 前 deadline 和用户取消的无 Model-completion 终态化，留给下一状态机 Gate。
9. 本能力继续内聚于 @qinglong/ai 的嵌套领域目录，不新增 workspace package、Node 进程、Pod、 连接池、队列、timer、watcher 或 cache。Edge/Standalone 默认制品不导入 PostgreSQL executor； Cluster 的 Copilot output key material 必须由显式 active()/resolve() provider 注入，不能复用 Provider credential、Tool invocation/result 或 Plugin Prompt output 的密钥用途。

被否决方案

1. Model 成功后再单独写 Artifact：留下成功 Step 与缺失输出的不可恢复窗口。
2. 把 Tool 明文保存在 executor registry：崩溃后无法恢复，也扩大路由设备常驻内存与泄漏面。
3. 把第二个领域 Artifact 导入通用 coordinator：继续形成 Model core → product domain 的反向依赖。
4. 自动重试只有 start 的 Model invocation：外部 Provider 可能已完成，重试会产生重复费用和结论。
5. 将 outcome_unknown 直接标为 failed：丢失真实不确定性，破坏人工 resolution 语义。
6. 为 Copilot Model execution 新建 package：没有新的独立部署边界，只会再次制造单文件薄包。

验证标准

1. 单元/契约测试覆盖密文 round-trip、metadata/ciphertext/key tamper、content-free reference、 finalization receipt、显式 subpath、一次 Provider 调用、completion/finalization replay 零 Provider 调用。
2. 既有 Plugin Prompt exact replay、Artifact 与 settlement crash window 全部通过，证明通用原子端口 重构没有改变旧领域语义。
3. PostgreSQL 18.4 physical HA 必须应用 20 条 AI migration，证明两张新表 append-only 角色隔离、 timeline 1→2 提升后 history/schema/ACL 一致，并由独立证据审计复核。
4. 18-package clean build/test、backend、四项架构审计、14 档 Artifact 和 GitNexus staged/change detection 全部通过后才允许阶段性提交；不得把 focused test 当完整性证明。

当前验证

1. @qinglong/ai 全量测试 233 pass、3 条 PostgreSQL 条件测试 skip、0 fail；新增覆盖密文 round-trip、tamper、content-free reference、一次 Provider 调用及 completion/finalization replay。
2. 18 个 QL3 package 从清空 dist 开始全部构建并通过各自全量测试；backend 1,207 pass、 2 条条件测试 skip、0 fail。
3. package boundary、cluster dependency、Edge import、Cluster deployment 四项审计均为 compatible: true 且零 finding。workspace 仍为 18 个 package，singleSourcePackages=[]、 shallowSourcePackages=[]；AI 的 183 个源码中 182 个位于嵌套领域目录。
4. 14 档 Local Profile Artifact 全部通过；默认 Edge/Standalone 分别为 2,589,890/2,589,968 bytes，Edge/Standalone AI 为 3,061,009/3,061,099 bytes，均在预算内。
5. PostgreSQL 18.6 arm64 physical HA 130/130、timeline 1→2，20 条 AI migration、schema、 append-only ACL 与提升后一致性全部通过；报告 SHA-256 为 8401634f30635b45bfb583b02e94ac41f023bf8a0bdbcfd9744ebf459ab0d8f8，独立证据审计零 finding， Docker 容器、网络和卷零残留。

后续门禁

1. 为 Copilot output 建立 Cluster 专用 projected keyring manifest、active rotation、retirement、 external custody 与 lost-key recovery；在产品 composition 完成前 Model executor 保持不可达。
2. 终态化 Tool failure、日志 missing/retired、Model admission 前 deadline、用户 cancellation 与 outcome_unknown resolution，并加入跨主库提升的 crash-window execution matrix。
3. 最后开放默认关闭的 Cluster API/CLI/UI/MCP 入口，补真实外部 Provider、KMS/Secret projection、 plaintext negative evidence、多副本并发和费用/取消可观测性。