qinglong/docs/adr/ADR-0411-default-off-cluster-copilot-composition.md

ADR-0411：默认关闭的 Cluster Copilot Failure Diagnosis Composition

• 状态：Accepted
• 日期：2026-08-15
• 关联 RFC：QL-RFC-0001 D-319、Phase 2
• 关联 ADR：ADR-0407、ADR-0408、ADR-0409、ADR-0410

问题

ADR-0407 至 ADR-0410 已分别建立 diagnosis admission、Trusted Tool execution、Model execution 和独立 output key authority，但它们仍只在测试与 HA ceremony 中手工组装。若直接再启动一套 Model Gateway，会为每个 replica 复制 PostgreSQL Pool、Provider client、恢复扫描和并发预算；这对小型集群 不合理，也会让 Prompt 与 Copilot 绕过同一模型出口限额。若直接开放 HTTP route，则 Tool failure、日志 missing/retired、Model admission 前取消以及 outcome-unknown 尚未终态化，产品会暴露无法收敛的 Run。

决策

1. Copilot 只在既有显式 ql3-cluster-control-ai 进程中装配，并由独立 QL3_CLUSTER_AI_COPILOT_ENABLED=true 开关启用。默认 Cluster、Edge、Standalone 和仅 Prompt 的 Cluster AI 均不读取 Copilot 配置、keyring 或 Artifact authority。
2. Prompt 与 Copilot 共享一个 PostgreSQL runtime Pool、一个 Model Gateway、同一 Provider authority、 recovery pass、pricing/quota ledger 和 maxConcurrent 预算。新增有界 successful-completion router， 只把一次已开始的 invocation 交给声明该 invocation 的 durable sink；不得复制 Gateway 或隐藏队列。
3. Copilot Model execution 依赖 generate() 与 supportsSuccessfulCompletionSink() 的窄结构端口，不依赖 BoundedModelGateway 具体类，使 production Profile 的 drain/active-operation capability 可以直接注入， 同时保留 exact sink identity 检查。
4. Cluster Copilot application service 从当前 PostgreSQL Run、latest Attempt、Project Tool snapshot 和 Policy 派生计划；调用者不能提供 Attempt、Artifact、Tool binding、Policy fence、key ID、nonce、 plannedAtMs 或内部 Run/Step/ModelInvocation identity。模型与 egress policy 来自部署者的 canonical read-only配置，而不是请求体。
5. diagnosis admission 先持久化 exact plan/Run/Step ledger，再物化可重建的加密 Tool invocation Artifact。 replay 使用 durable plan、historical invocation key 和域分离确定性 nonce 修复 admission→Artifact crash window；只有 Artifact exact replay 成功后才允许 Tool execution。密钥副本使用后必须清零。
6. Tool execution 复用同一 PostgreSQL repository、current snapshot、Project Policy 与 Worker Artifact range reader；Model execution复用同一 Gateway，并由 ADR-0410 output keyring 原子落盘 ciphertext。 invocation、Tool result 与 Model output keyring 继续是三个不可互换的域。
7. composition 能力在进程内保持 caller-driven、无 timer、watcher、队列或后台扫描。当前 Gate 不注册 HTTP/CLI/UI/MCP route；只有下一 Gate 完成所有非成功路径的 durable terminalization/recovery 后， 才能把该能力接入认证产品面。
8. Kubernetes 以独立可选 component 投影 canonical Copilot 配置和三个 read-only keyring；它必须与 cluster-ai 以及可读 Worker Artifact storage 一起使用，不新增 Pod、ServiceAccount 权限或 sidecar。

被否决方案

1. 为 Copilot 再启动 Gateway/Pool：资源翻倍并拆散全局并发、quota 和 Provider 出口约束。
2. 让 Gateway 依赖具体业务 sink：把通用模型边界反向耦合到 Prompt/Copilot 产品域。
3. 由请求提交完整执行计划：把 source fence、Tool binding、egress policy 和内部 identity 交给不可信边界。
4. 先开放 route、以后补失败收敛：会产生用户可见但永久 running/pending 的 diagnosis Run。
5. 把三个 keyring 合并：轮换、退役与泄漏半径跨越 Tool 输入、Tool 输出和模型输出域。
6. 新增 workspace package：composition 没有独立进程或依赖闭包，薄包会恶化已有 package 粒度。

验证标准

1. completion router 证明 Prompt/Copilot 精确分发、未知 invocation 不落盘、重复/扩展 sink 拒绝。
2. 默认关闭时不读取 Copilot config、keyring、Worker Artifact 或新增 PostgreSQL authority。
3. composition 测试覆盖 server-derived source/snapshot/Policy、admission→Artifact crash repair、Tool→Model 成功链、exact replay、key rotation、配置/authority 缺失和有序 drain。
4. AI、Cluster Control、18-package clean build/test、backend、四项架构审计和 14 档 Local artifact 全通过。
5. PostgreSQL 组合证据覆盖真实 repository 上的 admission、Tool completion、Model ciphertext、finalization 与 exact replay；本 Gate 不新增 migration、schema、role 或 SQL privilege。

当前验证

1. successful-completion router 与 Cluster Copilot application/composition 定向测试全部通过；AI 完整测试 238 pass/3 条件 skip，Cluster Control 完整测试 240 pass/2 条件 skip。
2. 18-package clean build/test 全部通过；backend 1,207 pass/2 条件 skip/0 fail。package boundary、 dependency、Edge import 与 Cluster deployment 四项审计均为 compatible、零 finding。
3. workspace 仍为 18 个 package，无 single-source 或 shallow-source package；AI 187 个源码中 186 个、 Cluster Control 59 个源码中 57 个位于嵌套领域目录。新增 composition 没有制造薄 package 或根层平铺。
4. 14 档 Local Profile artifact 全部通过。默认 Edge/Standalone 保持 2,589,890/2,589,968 bytes；Edge/Standalone AI 为 3,064,454/3,064,544 bytes，均未引入 Cluster-only composition，且分别保有 1,604,414/1,604,336 与 2,178,426/2,178,336 bytes 体积余量。
5. PostgreSQL 18.6 arm64 HA 130/130、timeline 1→2，报告 SHA-256 为 981299b454dce5541e9596450b85816dc40559cba8dc42adf3d5fea571c3d3a6。本 Gate 不新增 migration、schema、role、SQL privilege 或 HA 拓扑；真实 repository 的 admission、Tool completion、 Model ciphertext、finalization 与 exact replay 沿用同一受审 authority，Docker 门禁与清理均通过。

后续门禁

1. 为 Tool failed|timed_out、日志 missing|retired|pending、deadline/cancel 和 Model outcome_unknown 建立有界 durable terminalization/recovery。
2. 完成后再增加经 authentication、Policy、audit、request identity 和 source fence 保护的 Cluster API， 随后复用该 capability 提供 CLI/UI/MCP，而不是建立旁路执行器。