qinglong/docs/adr/ADR-0263-explicit-cluster-ai-composition-and-provider-credential-authority.md

# ADR-0263：显式 Cluster AI 组合与 Provider Credential Authority

- 状态：Accepted
- 日期：2026-08-02
- 关联：RFC D-08、D-12、D-85、D-124、D-156、D-159、D-244；ADR-0167、ADR-0169、ADR-0261、ADR-0262

## 背景

ADR-0169 已定义 Project-bound Provider credential、可清零 Secret material 和
audit-before-network，但当时还没有 Cluster 产品组合：binding 与 audit 没有 PostgreSQL
authority，Secret material 没有可部署的 Cluster adapter，默认 Cluster 镜像也不能安全地
选择性包含 AI。

QingLong 3.0 同时服务低配路由设备和多副本 Cluster，因此不能通过以下方式补齐能力：

- 让默认 control image、Edge 或 Standalone 常驻安装/加载 AI；
- 为 binding、Secret adapter、composition 或 CLI 各拆一个单文件 workspace package；
- 让常驻 control 持有 Kubernetes API、Secret list/watch 或 credential mutation 权限；
- 把静态环境变量 token、ConfigMap 明文或进程内 cache 当作 credential authority；
- 只发布一个内容随构建参数变化、却共享同一镜像身份的 Cluster Control artifact。

## 决策

### 1. Credential catalog 与 audit 使用 append-only PostgreSQL authority

在既有 `@qinglong/ai` 包内新增显式 catalog/storage subpath，不新增 workspace package。
`pg-9012-ai-model-provider-credential-catalog` 在 `ql3_ai` schema 追加：

- immutable binding revision；
- generation/CAS 驱动的 `bind|revoke` transition；
- content-free credential use audit。

runtime 只取得 current binding read 与 audit append；binding mutation 只属于既有
`ql3_ai_maintenance` authority。exact mutation 可重放，generation、command 或 binding
identity 漂移必须冲突。audit 只保存 Project、Provider、request、operation、binding
revision/digest 和数据库时间，不保存 SecretRef、token、header、Prompt 或输出。

### 2. Cluster Secret material 使用只读 projected-file adapter

首个 Cluster material adapter 接受一个部署注入的绝对只读目录。文件名是 canonical
SecretRef 的 lowercase SHA-256；每次调用重新解析并读取一个有界 regular file：

- 允许 Kubernetes atomic-writer symlink，但最终文件必须仍位于受信 root 内；
- 拒绝可写、可执行、other-readable、hard-link、路径/identity/size 漂移；
- material 以 owned bytes 返回并由 authorization lease 清零；
- 不使用 Kubernetes client、ServiceAccount token、list/watch、cache、timer 或后台进程。

该 adapter 可以消费 Kubernetes Secret、CSI 或 Secret operator projection，但不把这些
projection 冒充最终 KMS/HSM。轮换由外部 authority 原子替换 projection，下一次调用自然
读取新 material。

### 3. Cluster AI 必须是显式 composition root

AI 产品组合留在 `@qinglong/cluster-control/ai-production`，复用既有认证、Project Policy、
route registry、生命周期和 PostgreSQL runtime contract。只有独立 AI entrypoint 解析
`QL3_CLUSTER_AI_ENABLED=true` 及 AI 配置，并按以下顺序 fail closed：

1. 校验 projected Secret root 与可选 Prompt output keyring；
2. 建立独立、有上限的 PostgreSQL runtime pool；
3. 装配 credential reader/audit、Secret material 与 projected Provider authority；
4. 执行有界 Prompt recovery；
5. 将 Prompt execution capability 注入既有产品 route；
6. 再启动 Cluster Control，并在任一侧不可用时统一有界停止。

默认并发为 4、recovery page 为 32、AI 数据库连接为 4，且都有硬上限。该增量只开放
已经受审的 Prompt execution；Prompt output read、credential management 和通用裸 model
gateway route 仍保持关闭。

### 4. 默认与 AI 镜像是两个独立供应链 artifact

同一 Dockerfile 提供两个显式 target：

- `runtime` / `qinglong3-cluster-control`：只含 runtime-core、cluster-postgres、
  cluster-control，使用干净输出目录编译并断言不存在 AI package、AI composition 和 AI CLI；
- `runtime-ai` / `qinglong3-cluster-control-ai`：额外包含 `@qinglong/ai` 和独立 AI CLI。

CI、OCI layout、SBOM、OS vulnerability scan、签名/证明和 release matrix 均把
`control-ai` 作为第四个独立 artifact，与 control、admin、local 分别 pin digest。不能用
同一 tag 的隐藏 build arg 改变依赖闭包。

### 5. Kubernetes Cluster AI 是 opt-in component

默认 `ql3-cluster` base 保持 AI-free。`components/cluster-ai` 只在显式 overlay 中：

- 将 control image 替换为独立 AI image；
- 注入 canonical Provider authority ConfigMap；
- 以 `0440` 只读 Secret volume 提供 digest-named material；
- 保持 `automountServiceAccountToken: false`，不增加 Kubernetes RBAC/API egress；
- 要求私有 overlay 独立 pin AI image digest。

### 6. Package 边界不因该能力继续细拆

workspace 保持 19 个 package。catalog、repository、projection adapter、composition 与 CLI
分别进入已经承担对应依赖/权限/部署责任的 `ql3-ai` 或 `ql3-cluster-control` subpath。
源码文件数量只能触发复审，不能单独决定 package；新增 package 仍必须满足 RFC D-85 的
部署、权限、依赖闭包、多个 production consumer 或独立供应链责任门。

当前唯一单源 package `@qinglong/local-command-file` 有三个 production importer，并提供
共同的 POSIX private-file/TOCTOU 安全协议，因此暂时保留；如果 consumer 收敛为单一同包
入口，或不再形成共享安全边界，则必须回并为现有 subpath。

## 被否决方案

1. **默认 control image 直接安装 AI**：让禁用 AI 的节点承担依赖、漏洞与演进成本。
2. **每个 AI adapter 一个 package**：没有独立部署或权限收益，重复单文件包问题。
3. **环境变量保存 Provider token**：无法形成 Project-bound revision、轮换和 durable audit。
4. **常驻 control 读取 Kubernetes Secret API**：扩大 ServiceAccount、RBAC、网络和缓存边界。
5. **一个镜像 tag 通过环境变量切换 AI**：无法由 SBOM、签名和 digest 证明实际闭包。
6. **把 projection 宣称为 KMS**：它只解决 Pod 内只读 material delivery，不解决外部
   key custody、wrapping、灾备或 lost-secret ceremony。

## 验证

- `@qinglong/cluster-control`：175 项中 173 通过、2 条外部条件跳过、0 失败；
- `@qinglong/ai`：154 项中 151 通过、3 条外部 PostgreSQL 条件跳过、0 失败；
- Cluster AI composition 独立测试 3/3；deployment audit 40/40；
- release/SBOM/OCI/OS vulnerability policy 合并测试 117/117；
- frozen lockfile install、Cluster dependency audit、deployment audit 和 release audit 全绿；
- 实际 Docker `runtime` 不含 AI package/CLI/composition，`runtime-ai` 三者均存在且 AI CLI
  可执行；实际 `control-ai` inventory 为 47 components，其中 4 个 internal、43 个 external；
- PostgreSQL 18.4 arm64 physical-streaming HA 完成 `remote_apply`、timeline 1→2、旧主
  fencing、`pg_rewind`、双 fresh control；binding bind/revoke/rebind 与 content-free audit
  在晋升后保持一致，总 gate `passed=true`；
- 所有 `ql3-ha-*` 临时资源已清理，既有 evidence control-plane 未被修改；
- workspace 仍为 19 个 package，dependency findings 为空。

## 后续门禁

1. 为 binding bind/revoke、测试连接和 audit query 增加经过认证、Policy 与 quota 约束的
   Cluster 管理 ceremony；常驻 runtime 不取得 mutation authority；
2. 引入真正的 KMS/Vault/HSM custody adapter、首次 provision、active rotation、备份恢复与
   lost-secret 人工流程；
3. 在真实 Kubernetes API/CSI/Secret operator 上完成投影轮换、Pod rollout、网络隔离和
   credential 丢失故障注入；
4. 补齐真实 Provider 的计费、限流、超时和故障注入后，再评审更多 HTTP/MCP/UI route；
5. 持续以镜像字节、文件数、loaded modules、RSS、连接数和冷启动验证低配与 Cluster
   两端预算，不能用 package 数替代运行成本证据。