qinglong/docs/adr/ADR-0410-cluster-copilot-failure-diagnosis-output-key-authority.md

# ADR-0410：Cluster Copilot Failure Diagnosis Output Key Authority

- 状态：Accepted
- 日期：2026-08-15
- 关联 RFC：QL-RFC-0001 D-318、Phase 2
- 关联 ADR：ADR-0405、ADR-0406、ADR-0408、ADR-0409

## 问题

ADR-0409 已定义 Copilot diagnosis Model output 的独立 AES-256-GCM Artifact 与 key provider 端口，
但 Cluster 产品还没有可以注入该端口的部署密钥 authority。若复用 Plugin Prompt output、Tool
invocation 或 Tool result keyring，会让一次轮换或退役跨越不同数据域，并使最小权限部署无法证明
哪个进程能够加解密诊断结果。

同时，路由设备不应因为 Cluster Copilot 能力增加任何 keyring、watcher 或常驻内存；Cluster 节点
也不能把 Kubernetes Secret/CSI projection 的瞬时路径、可写文件或跨目录 symlink 当成可信密钥。

## 决策

1. 新增独立 schema `qinglong/copilot-failure-diagnosis-output-projected-keyring@v1`。manifest 只包含
   一个 `activeKeyId` 和最多 16 个 canonical 32-byte key；key ID 有界，JSON 必须 exact 且 canonical。
2. `ClusterCopilotFailureDiagnosisOutputProjectedKeyring` 实现 ADR-0409 的 `active()` 与
   `resolve(keyId)` 端口。每次操作重新打开 projection，不持有 cache、watcher、timer、Kubernetes
   API client 或轮换权限；返回的 key material 由调用者使用后清零。
3. 文件读取复用 Cluster Control package-private `PrivateProjectedFileReader`：配置根必须是 direct
   absolute directory；允许 Kubernetes atomic-writer 的根内 symlink，但最终 regular file 必须单链接、
   只读、不可执行、other-inaccessible，并在读取前后复验 dev/inode/size/mtime 与双 realpath fence。
4. Copilot output key ID/material 不得与 Plugin Prompt output、Tool invocation、Tool result 或 Provider
   credential 互换。不同 schema 即使 key bytes 相同也拒绝；部署文档必须要求独立 Secret 和 mount root。
5. 能力内聚在现有 `@qinglong/cluster-control` 的 `copilot/failure-diagnosis/` 目录，只通过显式
   `failure-diagnosis-output-keyring` subpath 发布；不新增 workspace package、依赖、进程、Pod、连接、
   route 或默认 Profile import。
6. 本 Gate 只建立 runtime key custody，不提前伪造产品可用性。完整 Copilot composition 仍需同时装配
   admission、Tool invocation/result keyring、Artifact/log reader、Model Gateway、PostgreSQL repository
   与恢复状态机；该入口在后续 Gate 完成前保持不可达。

## 被否决方案

1. **复用 Plugin Prompt output keyring**：两个产品域的 retention、授权和泄漏半径不同。
2. **复用 Tool invocation/result keyring**：混淆请求、Tool 结果与模型结论的加密用途。
3. **从环境变量读取 base64 key**：密钥进入进程环境与诊断面，且无法安全保留历史 key。
4. **启动时读取一次并永久缓存**：轮换无法生效，退役和文件漂移也无法失败关闭。
5. **为 keyring 新建 package**：没有独立部署进程或依赖边界，只会增加薄包。

## 验证标准

1. 覆盖 canonical manifest、active rotation、historical resolve、missing key、wrong schema、缺失 active、
   非 32-byte material、可写 projection 与根外 symlink。
2. Cluster Control 完整构建/测试、package/dependency/Edge import/Cluster deployment 审计全部通过。
3. workspace 保持 18 个 package、无单文件或浅平 package；14 档 Local Profile artifact 证明默认
   Edge/Standalone 与本地 AI/MCP 不携带该 Cluster-only subpath。

## 后续门禁

1. 在独立默认关闭的 Cluster Copilot composition 中同时装配 admission、Tool、Model 与本 keyring，
   不能把 Plugin Prompt gateway 的 completion sink 当作 Copilot sink。
2. 建立 Tool failure、日志 missing/retired、Model admission 前 deadline/cancel 与 outcome-unknown
   resolution 的 durable terminalization/recovery。
3. 再开放经 authentication、Policy、audit 和 exact source fence 的 Cluster API/CLI/UI/MCP 入口。

## 当前验证

1. 定向 keyring 与 package-boundary 回归 13/13；Cluster Control 完整测试 241 项中 239 pass、2 条
   环境条件 skip、0 fail。
2. 18 个 QL3 package 从清理 `dist` 开始顺序构建并执行全部 package tests，退出码为 0；backend
   全量 1,209 项中 1,207 pass、2 条环境条件 skip、0 fail。
3. package boundary、dependency firewall、Edge import 与 Cluster deployment 四项架构审计均为
   `compatible: true`、零 finding。workspace 仍为 18 个 package，`singleSourcePackages` 与
   `shallowSourcePackages` 均为空；Cluster Control 的 58 个源码中，56 个位于嵌套领域目录，根层仅
   保留 2 个 binary entry。
4. 14 档 Local Profile artifact 全部通过。默认 Edge/Standalone 仍为
   2,589,890/2,589,968 bytes，Edge/Standalone AI 仍为 3,061,009/3,061,099 bytes；新增
   Cluster-only subpath 未进入默认、本地 AI 或 MCP 产品闭包。
5. 本 Gate 不修改 migration、schema、PostgreSQL role、SQL、连接或 HA 拓扑，因此不重复制造一份与
   变更无关的数据库实证；ADR-0409 的 PostgreSQL 18.6 arm64 HA 130/130、timeline `1→2` 仍是当前
   数据库基线。