qinglong/docs/adr/ADR-0281-source-bound-cross-architecture-linux-resource-release-evidence.md

# ADR-0281：同源绑定的跨架构 Linux 资源发布证据

- 状态：Accepted（证据协议、CI 归档与聚合门已实现；远端 runner 成功记录仍由实际 GitHub Actions 运行取得）
- 日期：2026-08-07
- 关联：D-05、D-07、D-87、D-213、D-251、D-257、ADR-0088、ADR-0278、ADR-0280

## 上下文

QingLong 3.0 CI 已在原生 Linux x64 与 arm64 runner 上分别执行 128 MiB Router stress、256 MiB Edge
release guard 和 512 MiB Cluster control guard。每档都会从容器内核对 cgroup v2、swap、OOM、CPU、PID、
non-root、只读挂载、seccomp、`NoNewPrivs` 与 workload 结果，但报告过去只存在于 job 日志中。

日志不能证明三个档位属于同一架构 job，也没有机器可验证地绑定 repository、commit、workflow、run 与
run attempt；发布审核者也无法拒绝把另一提交、另一重跑或重复架构的结果拼成“双架构证据”。同时，任何
归档机制都不能把共享 CI 容器结果误写成固定路由器的物理支持声明，或用控制面空载门代替 Cluster 容量测试。

## 决策

1. 新增 `scripts/ql3-linux-resource-release-evidence.cjs`。单架构 `bundle` 必须一次性读取三个 exact tier
   报告，并绑定 `repository/revision/workflow/runId/runAttempt` 与原生 `x64` 或 `arm64` 身份。
2. 输入采用 exact-shape、fail-closed JSON：未知顶层字段、缺档、档位顺序或 workload 集漂移、Node/UID/GID/
   架构漂移、资源限额扩宽、安全挂载缺失、`max/oom/oom_kill/oom_group_kill` 增量、失败 gate 或非空
   violation 都拒绝生成 bundle。
3. 输入必须是非符号链接的普通文件且不超过 8 MiB；规范化最多 32 层、100,000 个共享节点。输出使用
   `wx` 和 `0600` 创建，不覆盖已有证据。摘要使用固定 domain separator 的 SHA-256，避免与普通 JSON
   digest 混用。
4. matrix 中每个原生 runner 先把三档 stdout 写入 runner temp，再生成只属于当前架构和当前 workflow run
   的 bundle。上传 artifact 名包含 `run_id/run_attempt/architecture`，action 固定到完整 commit，缺文件和
   overwrite 均失败关闭。
5. 独立 `linux-resource-release-evidence` job 必须依赖整个原生 matrix，按精确名字分别下载 x64/arm64
   artifact，不使用 pattern 或 `merge-multiple`。`merge` 重新验证两个 bundle 的完整摘要、原生身份、精确
   tier 集与同一 source；缺失、重复架构、跨提交或跨 workflow run 混合都拒绝。
6. 合并产物只保存每个架构的 bundle digest 与逐档 envelope/peak/workload count 摘要，并显式记录三条
   limitation：CI cgroup 不是受支持最低硬件、不能替代断电/闪存/热环境/soak、GitHub workflow identity
   绑定不是密码学硬件证明。
7. 本门不增加 workspace package、生产 dependency、数据库、migration、Pool、timer、listener 或运行时
   authority；证据脚本只在 CI/发布审核面消费既有资源报告。

## 被拒绝的方案

- **继续只保留日志**：人工可读但无法精确拼接同一 commit/run 的三个档位与两个架构。
- **只上传三份原始 JSON**：没有 source binding、单架构完整性摘要或跨架构聚合门。
- **按 artifact pattern 自动合并**：可能吸收额外或错误架构，弱化 exact two-party contract。
- **由本机 arm64 伪造 x64 报告**：架构标签不是原生执行证据；x64 结果必须来自 x64 runner。
- **把 bundle digest 称为硬件 attestation**：摘要只检测内容漂移，不证明 runner 硬件或受信执行环境。
- **把 128 MiB 档升级为路由器最低配置**：缺少固定型号、内核、文件系统、闪存、断电和长期热环境证据。
- **用 512 MiB 控制面门推导集群容量**：没有副本、数据库延迟、吞吐、queue depth、failover 与恢复负载。

## 接受证据

- 新证据协议定向测试覆盖 native x64/arm64 正向 bundle/merge，以及架构漂移、失败 gate、OOM event、未知
  字段、摘要篡改、跨 source、重复架构、缺架构、共享节点预算、符号链接输入与输出覆盖失败路径。
- Workflow contract 固定三份原始报告、五个 source 字段、原生架构、完整 commit-pinned upload/download
  action、精确 artifact 名、matrix dependency 与禁止 pattern/merge-multiple/continue-on-error。
- Linux resource gate、证据协议、workflow、cluster image release、local image、Kubernetes live contract 与
  PostgreSQL TLS workflow 的本地定向审计共 73/73 通过。
- 完整 backend 为 1,110 tests、1,108 pass/2 skip/0 fail；完整 19-package clean build/test 门退出 0。Edge
  import、cluster dependency、package boundary、cluster deployment、worker deployment 与 local image 六项
  审计全部 compatible，workspace 仍为 19 个 package。
- 十档 artifact 的 package/file/module closure 与上一轮完全一致；最大 Standalone Application AI 为
  5,970,364 bytes，距 6 MiB 仍有 321,092 bytes，新增 CI-only evidence 脚本没有进入 production closure。
- PostgreSQL 18.4 arm64 physical-streaming HA `gates.passed=true`：timeline 1→2、旧主先 fencing、
  `pg_rewind` 只读同步 rejoin、两个 fresh control replica 与全部业务 gate 全绿；执行后 `ql3-ha-*`
  container/network/volume 零残留。
- 刷新后 GitNexus 为 42,603 nodes/96,672 edges/1,677 clusters/261 flows；新脚本关键符号均为 LOW、
  0 affected process，最高 `canonicalize` 为 3 direct/8 total。仓库范围 `detect_changes` all 与 compare
  `develop` 分别为 12 files/31 symbols、14/34，均 low/0 affected process；QL3 孵化树仍未 stage，因此新增
  文件的风险以刷新后逐符号 impact 结果为准。
- 本地只能验证协议与静态 CI contract；真实 x64 与 GitHub-hosted arm64 数值、artifact URL 和成功 run ID
  必须在该 workflow 实际运行后记录，不能在仓库内预造。

## 后续边界

- 在 GitHub Actions 实际取得同一 commit/run 的 x64、arm64 bundle 与 cross-architecture artifact，并把
  run URL、artifact digest 和保留策略纳入 release candidate 审核。
- 固定路由设备仍按 ADR-0088 采集明确型号、RAM、存储、内核、文件系统、断电、闪存、热环境与 soak
  证据；只有物理矩阵完成后才能讨论受支持最低配置。
- Cluster 容量继续使用独立的多节点 PostgreSQL/Worker/queue/failover 压测，不继承本门的 512 MiB 数字。
- 联网 production dependency vulnerability audit 因依赖元数据外发权限未获批准，本轮不重跑。