qinglong/docs/adr/ADR-0441-no-overwrite-release-catalog-discovery-publication.md

ADR-0441：Release Catalog Discovery Tag 无覆盖发布

• 状态：Accepted
• 日期：2026-08-18
• 关联 RFC：QL-RFC-0001 D-03、D-14、D-336、D-347、D-349
• 关联 ADR：ADR-0428、ADR-0430、ADR-0439
• Supersedes：ADR-0428 中允许直接向 discovery tag 重发内容的恢复语义，以及 catalog plan/receipt v1

上下文

ADR-0428 把 v<version>-<scope> 定义为无部署 authority 的发现入口，并要求部署只信任验证后的 immutable manifest digest。 ADR-0439 又要求相同 source evidence 的合法 workflow 重跑生成相同 release-set 与 catalog identity。

但发布 workflow 仍直接对远端 discovery tag 执行 regctl artifact put。OCI Distribution tag 没有跨 registry CAS；如果该 tag 已被外部 写成另一个 digest，直接 put 会先覆盖冲突事实，再在新 digest 上完成验证。response-loss 重跑也无法区分“远端已经是同一确定内容”和“远端 曾指向不同内容”。workflow 的同 ref concurrency 只能串行本仓库 Actions 运行，不能证明 registry 没有其他 package writer。

决策

1. catalog plan 升为 qinglong/release-catalog-plan@v2，publication policy 固定声明：
   • staging/discovery tag authority 均为 none；
   • discovery 冲突必须在 mutation 前失败；
   • response-loss 只能复用 exact manifest digest；
   • immutable digest 仍是唯一部署 authority。
2. publisher 必须先把 canonical release-set 发布到 runner 私有的 ocidir:// layout，并从该 layout 取得 manifest digest 和 raw manifest。绝不再直接对 discovery tag 执行 artifact put。
3. publisher 随后读取远端 catalog tag inventory。首次发布时 repository 可能尚不存在；只有在 inventory 读取失败后，才允许把本地 immutable manifest copy 到 staging-<plan-digest>。该 deterministic staging tag 无 authority，写后必须解析为同一 manifest digest，再重新读取 inventory。第二次读取失败即失败关闭。
4. qinglong/release-catalog-tag-inventory-decision@v1 对 tag inventory 执行最大 1 MiB、canonical line、OCI tag 字符集和 无重复校验。若 discovery tag 存在，必须读取其 digest；若缺失，则以显式 absent 状态进入 publication decision。
5. 新的 qinglong/release-catalog-publication-decision@v1 只接受已通过 exact manifest contract 的本地 manifest：
   • absent 产生 publish_if_absent；
   • exact digest 产生 reuse_exact_digest，用于 response-loss 恢复；
   • 任意不同、缺失格式或非 SHA-256 观察值在 discovery mutation 前失败。
6. publish_if_absent 只能从本地 immutable reference copy 到 discovery tag；reuse_exact_digest 不写 registry。两条路径都必须 再读取 discovery digest、按 immutable reference round-trip release-set、逐字节比较本地/远端 raw manifest，然后才允许签名、 provenance 和 receipt。
7. catalog receipt 升为 qinglong/release-catalog-receipt@v2，明确绑定 fail_closed_before_mutation 与 reuse_exact_manifest_digest_only。release-set v3 和 OCI media type 不变，因为被发布的 canonical release-set bytes 没有改变。
8. OCI registry 仍没有 tag CAS，因此本 Gate 不宣称能阻止仓库外 writer 在 inventory 与 copy 之间竞争。workflow 保持同 ref 串行， package write authority 必须由组织治理；最终回读会发现写入期间的竞争，而任何稍后改写也不能改变 receipt/provenance 中的 immutable digest。consumer 继续禁止把 discovery tag 当作 authority。

失败与恢复

• discovery 已指向不同 digest：不执行 discovery copy，不覆盖现场；操作者必须调查 tag/source/package authority，不能以重跑“修复”。
• discovery 已指向 exact digest：不重新发布，继续 immutable round-trip、签名和 provenance 验证，得到与首次成功相同的 durable plan/receipt bytes。
• catalog repository 尚不存在：deterministic staging copy 只用于建立 repository 和确定可读 tag inventory；staging tag 永远不能进入 deployment lock。
• registry/auth/network 不可用：staging 或第二次 inventory 失败即停止；不能把不确定读取当成 tag 缺失。
• discovery copy response 丢失：重跑后 inventory 必须看到 exact digest 并走 reuse；看到其他 digest 则失败。

部署与资源影响

• Edge/Standalone/路由设备继续只接收 catalog-bound Local selection 和 immutable image digest，不安装 regctl、Node、Cosign 或 GitHub CLI，不增加 RSS、I/O、timer、listener、updater 或后台任务。
• Cluster 节点、Kubernetes object、CloudNativePG、数据库、migration、SQL、Pool 与运行时镜像均无变化。
• 新工作只在短生命周期发布 runner：一个私有 OCI layout、至多 1 MiB tag inventory、一次 publication decision 和必要时一次 staging copy；不新增 workspace package、生产依赖或常驻服务。

被拒绝的替代方案

继续直接 artifact put 后再验 digest

拒绝。后验一致只能证明覆盖后的结果，不能保留或拒绝原有冲突。

把 workflow concurrency 当作 registry CAS

拒绝。它只串行同仓库同 ref 的 Actions run，无法约束其他 package token、组织管理员或 registry 外部 writer。

让 discovery tag 成为不可变部署入口

拒绝。OCI tag 仍可改写；唯一可持久签名、attest 和部署锁定的 authority 是 manifest digest。

为 catalog 新增常驻协调服务

拒绝。发布路径不值得引入新的服务、数据库和低配设备依赖；确定性 staging、冲突决策与 immutable consumer 已能把剩余竞态限制在非权威 tag。

验证

• contract 覆盖空/存在/重复/畸形/超限 tag inventory、absent publish、exact response-loss reuse、不同 digest 冲突、非法观察值和 closed CLI；
• workflow 静态门拒绝 direct discovery artifact put、缺失 publication decision、缺失 exact reuse、无界/malformed inventory 和未回读 immutable digest；
• catalog consumption、deployment-lock、Local/Cluster post-publication gate 必须继续只消费 immutable reference；
• 定向发布链 143/143，完整 backend 1,371 项为 1,369 pass/2 条件 skip/0 fail，18-package clean build/test 退出 0；
• 12 项静态审计和 14 档 Local artifact 全部 compatible，默认 Edge/Standalone 至 MCP 的既有字节/RSS 上限未漂移；
• PostgreSQL 18.6 arm64 physical HA 通过 142/142、timeline 1→2，证据 SHA-256 为 13e2f3793d7f418f0c1cc3b05206b393c4f09a45e1b9a5783219c12fb930b3dd，离线审计 compatible 且 Docker 资源零残留；
• 完整证据记录于 QL-RFC-0001 D-349；首份真实 GHCR conflict/reuse 证据仍须由受保护 v3 release tag 产生。