qinglong/docs/adr/ADR-0509-cluster-alpha-bundle-and-milestone-closure.md

# ADR-0509：Cluster Alpha Bundle 与跨架构里程碑闭合

- 状态：Accepted（首份实际 Cluster milestone artifact 待维护者授权）
- 日期：2026-08-28
- 决策：D-414
- 关联：ADR-0503、ADR-0506、ADR-0508

## 背景

QingLong 3.0 已开发约二十天。Local Alpha 已有双架构 Trial Kit 和完整 CI 后置 milestone index，但 Cluster 的 control、control-ai、admin、worker 仍由矩阵 job 内的 shell 各自生成 Docker archive 和一份 v1 manifest。

旧 Cluster archive 没有 `SHA256SUMS`、闭合文件集、独立 verification evidence 或可离线 auditor；manifest 直接把 gate 写成 `passed`，没有绑定 workflow ref/SHA、run ID/attempt 和 exact image ID。八个 artifact 也没有完整 CI 后置的唯一完成信号。部署者无法区分“某个矩阵 job 上传成功”与“本次阶段版本整体成立”。

## 决策

### 1. 单镜像 bundle 由仓库脚本统一物化

新增 `ql3-cluster-alpha-bundle.cjs`，固定四角色的 repository、OCI title、runtime user 和两种架构。bundle schema 为 `qinglong/alpha-cluster-image@v1`，文件集恰好包含：单镜像 Docker archive、对应 CycloneDX SBOM、`verification-evidence.json`、README、manifest 和 `SHA256SUMS`。

物化前必须重新检查 image reference、ID、OS、architecture、non-root user、source/version/title label，复用现有 SBOM closure audit，并验证 evidence 绑定 exact source、role、architecture、image ID、workflow ref/SHA、run/attempt 和 gate 集。离线 audit 不调用 Docker或网络，拒绝额外文件、symlink、长度/digest、SBOM/evidence 或 checksum 漂移。

### 2. 八个 bundle 只有在完整 CI 后才能闭合

新增 `cluster-alpha-milestone` finalizer，依赖现有完整 CI 的 19 个顶层 job。它下载同一 source 的四角色乘 amd64/arm64 八个 artifact，逐个离线复审，并要求 version/source/run/attempt 一致，image ID、archive digest 和 verification digest 八项均互不复用。

成功后上传 `qinglong/alpha-cluster-milestone@v1` 三文件索引。索引保存八个 artifact 名、bundle manifest digest、archive digest、image ID 和 verification digest。缺少索引的零散 archive 是中间文件，不是阶段版本。

### 3. 仍不把 Integration Candidate 冒充 Public Release

Cluster milestone 的 maturity 固定为 `cluster_integration_candidate_not_public_release`。它可供隔离 registry/K3s/Kubernetes 节点做多组件集成，但没有受保护 tag、GHCR immutable digest、签名/attestation、release catalog 或生产 deployment lock。正式发布继续由 Public Release Set 独立裁决。

## 被拒绝的替代方案

- 保留 workflow 内联 shell：难以单测和离线复核，manifest 仍会自报通过。
- 只依赖 GitHub job 绿色状态：下载物与 workflow 主体没有内容级绑定，失败运行也可能留下部分 archive。
- 把八个 archive 合并为一个超大 artifact：会重复下载和存储，对只需要特定角色/架构的部署者不友好。
- 将 Cluster candidate 直接提升为正式发布：缺少 registry、签名、catalog 和生产部署闭环。

## 影响

- 显式 `alpha_artifact_scope=cluster|all` 时增加 verification 文件、离线 audit 和一次八 artifact finalization；普通 push/PR 不生成大产物；
- 每个部署者只下载目标架构/角色，milestone 本身保持三文件小索引；
- 新实现属于 repository release tooling，不新增 workspace package、runtime dependency、镜像 layer、端口、daemon、timer、连接池或稳态 RSS；
- Local 的路由/NAS 稳态边界不变，Cluster 节点获得可裁决的阶段集成产物。

## 验证

- bundle 正向测试覆盖闭合六文件、image/SBOM/evidence identity 与离线 audit；
- 负向测试覆盖 root user、archive/SBOM/evidence 篡改、额外文件和 image subject 脱离；
- milestone 正向测试闭合八项，并覆盖跨 workflow run 混用、index mutation、额外文件和 workflow 门序；
- 静态 audit 固定 19 个完整 CI dependency、八 artifact 下载和 `finalize → audit → upload`；
- 首份真实产物仍需维护者显式授权 `produce_alpha_artifacts=true + alpha_artifact_scope=cluster`。