ADR-0506：源码绑定的 Local Alpha 验证证据

状态：Accepted
日期：2026-08-27
决策：D-411
关联：ADR-0503、ADR-0504、ADR-0505

背景

ADR-0504 把 Local Trial Kit 的写入与离线审计收敛为一个 materializer，但 v1 manifest 在 create 时会无条件写入九个 passed 字段。调用者只需提供可构建镜像和 SBOM，即可得到一份声称已经通过漏洞扫描、fresh Owner、Edge/Standalone lifecycle 与原生 cancellation 的 manifest；materializer 并未收到这些 gate 的任何证据。

提交 4239464a 的 macOS Docker Desktop 复验进一步暴露了该语义错误：bundle 内容、checksum、reload 和入口 smoke 均通过，但完整 Owner 旅程因 bind-mount UID 语义失败；同提交的原生 Linux CI 后续通过。内容完整性、源码实现通过和 exact artifact 已被验证是三种不同事实，不能由一个常量同时代替。

决策

1. Alpha bundle 必须消费独立的 verification evidence

Local Alpha schema 升为 qinglong/alpha-local-trial-kit@v2。create 新增必需的 --verification-evidence，并把 verification 从九个常量改为 verification-evidence.json 的文件记录。闭合目录从六个文件增加为七个，evidence 同时进入 manifest byte/SHA-256 绑定与 SHA256SUMS。

缺少 evidence、旧 v1 manifest、额外文件、evidence mutation 或 subject 漂移全部失败关闭。旧 schema 尚未公开发布，因此不保留会继续接受无来源 passed 声明的兼容分支。

2. evidence 绑定 exact workflow 与 artifact subject

新增同一 materializer 的 record-verification 模式，只接受：

repository whyour/qinglong；
workflow ref whyour/qinglong/.github/workflows/ql3-ci.yml@refs/heads/next；
workflow_dispatch event 与 local-image job；
完整 source/workflow SHA、十进制 run ID/attempt；
Tier-1 architecture，以及从 Docker inspection 获得的 Application/operator exact image ID。

evidence 的 subject 同时绑定版本、源码、架构和两个不同镜像 ID；九个 gate 保持 exact closed set。bundle create 与 offline audit 都重新匹配 evidence subject 和 manifest，不允许把另一架构、另一镜像或另一 run 的 evidence 复制进来。

GitHub workflow 只能在 Trivy、inventory、SBOM、128 MiB entrypoint、fresh lifecycle、完整 Trial Kit journey 与原生 cancellation 均成功之后记录 evidence；静态审计固定 journey → cancellation → record-verification → create → audit → upload 顺序。

3. workflow provenance 不是公开发布签名

evidence 提供可定位、可交叉检查的 GitHub run identity，不声称调用者无法伪造 JSON。下载者仍需到 GitHub 检查该 run 的 source、attempt 和结论。公开 Release Set 继续使用独立的 immutable digest、Cosign 与 GitHub attestation，不以 Alpha evidence 替代供应链签名。

普通 push/PR 不生成或上传 Alpha artifact；本地构建、push CI 通过或 source-equivalent native gate 只能支持工程候选判断。只有显式 milestone dispatch 产生的 exact-image evidence 才允许 materializer 声称 Local Alpha Trial Kit。

被拒绝的替代方案

保留 manifest 内的固定 `passed` 字段

拒绝。它把“脚本知道有哪些 gate”错误提升为“这些 gate 已对当前 artifact 执行”。

仅加入 GitHub run URL，不绑定镜像 ID

拒绝。同一源码可以因基础 package、构建平台或配置产生不同镜像；source-level run 不能自动证明另一个本地 archive 的 exact bytes。

在 Alpha 阶段实现第二套签名系统

拒绝。正式 release workflow 已承担签名和 attestation；Alpha 需要的是诚实、可定位的阶段证据，不应复制生产发布 authority。

影响

本地无 evidence 的 archive 不再冒充用户 Alpha，只能按工程候选处理；
手动 milestone artifact 多一个小型 JSON 文件，不增加 Docker archive layer、workspace package、设备常驻 RSS、端口或依赖；
下载者可从 bundle 确定 exact GitHub run/attempt，并验证 evidence 与 image ID/source/architecture 一致；
旧的本地 2620be05 与 4239464a v1 bundle 保留为历史工程证据，但不能通过 v2 auditor。

验证

聚焦测试覆盖 v2 七文件正常物化、非 milestone provenance、detached workflow、archive/SBOM/evidence mutation、额外文件和闭合 CLI grammar；
Local operator workflow audit 要求 GitHub workflow identity contexts、evidence input和严格 gate 顺序；
record-verification 和 create 都从 image inspection 绑定两个不同 image ID；offline audit 不调用 Docker或网络；
首个真实可下载 v2 双架构 Trial Kit 仍需维护者授权的 produce_alpha_artifacts=true workflow 生成。

4.8 KiB Raw Blame History Unescape Escape