feat(ql3): bind local compose revisions to release catalogs

docs/QINGLONG_3_0_ARCHITECTURE_RFC.md

@@ -11,6 +11,7 @@
 
 最新增量证据（2026-08-16）：
 
+- D-340/ADR-0432（已接受；真实公开 catalog 运行待实际 release tag）：Local/Compose 最后一跳不再接受裸 `image`。现有 `@qinglong/local-owner-cli` 的 prepare/upgrade 只接收 owner-private `releaseSelection.path + expectedSelectionDigest`，以 `O_NOFOLLOW` stable descriptor 有界读取不超过 64 KiB 的 canonical v2 selection，并重新验证 self-digest、3.x release identity、release-set/catalog manifest/catalog report digest 闭包、exact workflow identity、immutable catalog reference、唯一 GHCR Local application digest 与 explicit root policy。Compose revision/active selection 升为 `qinglong/local-compose-image-selection@v2`，持久保存完整 catalog/release authority；rollback 精确复制目标 revision authority，Preflight、Apply、Restore、Evidence 与 Status 共用同一 fail-closed parser。prepare/upgrade 仍只发布 revision，不联网、不执行 rollout、不修改数据库，也不新增 package、生产依赖、常驻进程或 Cluster 对象；低配设备每次显式命令只增加一次最多 64 KiB 的私有文件读取、canonical JSON 校验和 SHA-256，Cluster 路径不变。旧 v1 裸 image 在尚未正式发布的 3.0 中失败关闭，孵化环境须从原 catalog-bound selection 重新 prepare。Local 定向 30/30、物理 Edge Compose storage 6/6；Local Owner 全量 171 项为 166 pass/5 条件 skip/0 fail，backend 共 1,317 项为 1,315 pass/2 条件 skip/0 fail，18-package clean build/test 退出 0。10 项架构/部署审计与 14 档 Local artifact 全部 compatible，package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Edge/Standalone 默认制品为 2,589,890/2,589,968 bytes，application 为 3,632,769/3,632,889 bytes，application-api 为 3,800,322/3,800,466 bytes，AI 为 3,069,143/3,069,233 bytes，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 7,315,930/7,316,038 bytes。Cluster Admin exact dry-run pack 为 250 files、271,238-byte tarball、1,690,196-byte unpacked。经允许重新运行的 PostgreSQL 18.6 arm64 physical HA 通过 142/142、timeline `1→2`，报告 SHA-256 为 `07c914551ec700da26b42cd42760ccb3b28ad31266a8bae5f62dee38eb97e6a9`，离线审计通过且无 `ql3-ha-*` Docker 资源残留。测试中的 synthetic selection 只验证本地 Compose 兼容性，不冒充公开 catalog ceremony；公开 GHCR catalog 尚未实际产生，因此不宣称真实线上验签成功。
 - D-339/ADR-0431（已接受；真实公开 catalog 运行待实际 release tag）：D337 的 deployment-lock CLI 不再接受一份无法证明来源的松散 `--release-set`；Local/Kubernetes create/audit 必须同时接收 exact source repository 和 D338 生成的 owner-private three-file `--consumption-bundle`，先完整离线重建 release-set、raw OCI manifest、catalog plan/receipt、六步 argv/transcript digest 与 self-digest report，再把同一次 audit 读取的 release-set 对象交给 materializer，避免验真后重新按裸路径读取。Local selection 与 Kubernetes lock schema 升为 v2，显式绑定 consumption schema、source repository、exact workflow identity、catalog immutable reference、manifest digest、consumption report digest、release-set digest 和 `discoveryTagAuthority=none`；Cluster 被改写资源与 Pod template 也新增 catalog manifest/report digest annotations。旧 `--release-set`、bundle symlink/open shape、identity/scope/owner/image-count/digest 漂移均在创建任何输出前失败关闭。offline audit 诚实保持 `externalToolResultsReplayed=false`；本 Gate 不联网、不访问 Kubernetes API、不执行 Compose rollout/`kubectl apply`、不修改数据库，也不新增 package、生产依赖或运行期组件。供应链工作仍留在可信工作站，低配设备只接收 catalog-bound Local v2 selection 与一个 immutable image reference；Cluster 复用既有 post-render 流程。完整定向发布链 123/123；backend 共 1,317 项，1,315 pass/2 条件 skip/0 fail；18-package clean build/test 退出 0，package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`。10 项架构/部署审计与 14 档 Local artifact 全部 compatible，默认 Edge/Standalone 为 2,589,890/2,589,968 bytes，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster Admin pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked。本 Gate 不改变数据库或 HA 拓扑，复用紧邻发布 Gate 的 PostgreSQL 18.6 arm64 physical HA 基线而不把它声明为本阶段新证据。公开 GHCR catalog 未实际产生，因此不宣称真实线上验签成功。
 - D-338/ADR-0430（已接受；真实公开 catalog 运行待实际 release tag）：发布端的 durable catalog 不再由部署者通过松散 shell 重定向手工消费。可信工作站上的 `ql3-release-catalog-consumption-ceremony.cjs` 从 exact source version/revision/tag、closed `local|cluster|all` scope 与 owner/source repository 推导唯一 discovery ref，前后两次解析必须得到同一 digest，后续只使用 catalog `@sha256:` immutable reference。ceremony 以绝对路径、dev/inode/size/SHA-256 固定 `regctl|cosign|gh`，owner-private token 只进入单个 GitHub provenance verifier；环境、cache/config/tmp 与最终写入均有封闭边界。下载的 canonical release set 经过 standalone identity/family/self-digest inspection，raw OCI manifest 同时按 digest、media type、empty config、单 layer、basename、size/content digest 与四项 annotation 重建 publication plan/receipt。成功后才以 `0700` no-replace 目录和三项 `0600` 文件发布 release set、raw manifest 与 self-digest report；offline audit 要求 exact-three-file，并完全重建结构/manifest/report，同时诚实声明网络签名结果未离线 replay。该 ceremony 无 registry/GitHub mutation、deployment action authority、Compose/Kubernetes apply 或数据库访问；D337 继续只消费审计后的 release set。Local/低配设备不安装任何工作站工具，Cluster 也不新增 controller/CRD/RBAC。独立 ceremony 20/20、完整定向发布链 121/121 已通过；backend 共 1,315 项，1,313 pass/2 条件 skip/0 fail；18-package clean build/test 退出 0，package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`。10 项架构/部署审计与 14 档 Local artifact 全部 compatible，默认 Edge/Standalone 为 2,589,890/2,589,968 bytes，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster Admin pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked。本 Gate 不改变数据库或 HA 拓扑，复用紧邻发布 Gate 的 PostgreSQL 18.6 arm64 physical HA 基线而不把它声明为本阶段新证据。公开 GHCR catalog 仍未实际产生，因此本门不宣称已取得真实 Cosign/GitHub/registry 成功证据。
 - D-337/ADR-0429（已接受）：D-336 的 durable release set 现在可以离线物化为最终部署 authority，而不是由运维者手工复制 digest。可信工作站上的 `ql3-deployment-lock-contract.cjs` 不联网、不连接 Kubernetes API、不执行 rollout：Local/All 生成绑定 release-set digest、唯一 Local `@sha256:` 与显式 root policy 的 canonical selection；Cluster/All 先消费 `kubectl kustomize` 的最终多文档 YAML，再只改写封闭的 Pod/Deployment/StatefulSet/DaemonSet/ReplicaSet/Job/CronJob container 字段和 exact Plugin Package admission ConfigMap，生成带输入/输出 digest、各 role occurrence、release annotation 与 self digest 的 locked manifest/report。调用方必须显式声明 required role，未知位置的完整 role authority、畸形 container image、缺失角色、YAML alias/cycle/非 mapping、超限或覆盖输出全部失败关闭；audit 从原 release set 与原 render byte-exact 重建。采用 post-render 是因为真实原型证明外层 Kustomize component 不能可靠覆盖内层已选 repository/digest，且 `images` transformer 不处理 ConfigMap `data.image`。本机 kubectl 1.36.1/Kustomize 5.8.1 已真实渲染 CloudNativePG Core、Cluster AI、Worker node 与 Plugin Package Executor 四类清单，内层零 digest 均被同一 release set 的精确引用替换；定向 deployment-lock 11/11、发布链路联动 101/101，静态审计冻结 224 个 YAML、31 个直接 role image 引用与两个 admission authority。工具只在工作站运行，低配路由器只消费 Local selection，不新增 Node/YAML/Kubernetes/registry 工具、package、依赖、常驻进程或资源；Cluster 也不新增 controller/webhook/CRD/RBAC。完整 backend 共 1,295 项，1,293 pass/2 条件 skip/0 fail；18-package clean build/test 退出 0，package boundary 保持 18 packages、`singleSourcePackages=[]`、`shallowSourcePackages=[]`，10 项架构/部署审计与 14 档 Local artifact 全部 compatible。默认 Edge/Standalone 为 2,589,890/2,589,968 bytes，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster Admin pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked。本 Gate 不改数据库或 HA 拓扑。

docs/adr/ADR-0432-target-side-catalog-bound-local-compose-revisions.md

@@ -0,0 +1,84 @@
+# ADR-0432：目标侧 Catalog-bound Local Compose 修订
+
+- 状态：Accepted
+- 日期：2026-08-16
+- 关联 RFC：QL-RFC-0001 D-03、D-14、D-339、D-340
+- 关联 ADR：ADR-0199、ADR-0200、ADR-0431
+
+## 上下文
+
+ADR-0431 已让可信工作站从完整 catalog consumption bundle 生成 catalog-bound Local v2 selection，
+但 Local prepare/upgrade 入口仍接收裸 `image`。运维者必须手工复制 `service.image`，目标侧的 Compose revision v1
+也只保存 image、generation 与 mutation。结果是 release-set、catalog manifest、consumption report、workflow identity
+和 immutable catalog reference 在最后一跳被丢失；一个格式正确的任意 digest 可以绕开已经完成的 catalog 证据链。
+
+把 Cosign、GitHub CLI、regctl、Kustomize 或完整 release bundle audit 下沉到低配路由器，会显著扩大磁盘、内存、网络、
+凭据与更新面。让发布验真成功后自动 rollout 又会混合 input authority 与 action authority。
+
+## 决策
+
+1. 现有 `@qinglong/local-owner-cli` 内部增加目标侧 Local selection consumer，不新增 workspace package 或生产依赖。
+   Compose prepare 与 upgrade 删除裸 `image` 输入，改为 exact `releaseSelection.path + expectedSelectionDigest`；旧输入失败关闭。
+2. selection 必须是 absolute normalized path，父目录为 canonical/current-UID `0700`，文件为 canonical/current-UID、单链接
+   `0600`、最大 64 KiB。consumer 通过 `O_NOFOLLOW` stable descriptor 有界读取 UTF-8 canonical JSON，并在读取前后复验
+   identity/size/timestamp。
+3. 目标侧重新验证 `qinglong/local-compose-release-image@v2` exact shape/self-digest、3.x release/tag/revision、`local|all`
+   scope、release-set/catalog digest 闭包、exact image-release workflow identity、immutable catalog reference、唯一
+   `ghcr.io/<owner>/qinglong3-local-application@sha256:...` 和 explicit root policy。命令提供的 expected selection digest 是
+   本次目标部署的本地 operator authority；目标机不伪称重放网络签名或 provenance verifier。
+4. Compose image selection 升为 `qinglong/local-compose-image-selection@v2`。每个 immutable revision 持久保存 image 以及
+   selection/release-set/catalog manifest/catalog report digest、release identity、catalog schema/source/workflow/immutable
+   reference、discovery tag non-authority 与 root policy；核心 digest 同时进入 container labels。
+5. upgrade 从已验证的 selection 取得完整 release authority；rollback 从目标 immutable revision 复制完整 authority，不能只复制
+   image。Preflight、Apply、Restore、Evidence collection 与 durable status 继续通过同一 active/revision parser 验证 v2 canonical
+   binding。
+6. prepare/upgrade 只发布 revision，不访问 registry/GitHub，不启动容器、不调用 Compose up、不修改数据库。Preflight 与 Apply
+   保持独立、显式命令，因此可信 selection 不会自动获得 rollout authority。
+
+## 部署与资源影响
+
+- 不新增 package、生产依赖、数据库、migration、SQL、Pool、Pod、controller、CRD、RBAC、listener、timer 或 watcher。
+- 低配路由器每次显式 prepare/upgrade 只增加一次最多 64 KiB 的私有文件读取、JSON 校验和 SHA-256；没有后台 CPU、内存或网络开销。
+- Cluster/Kubernetes lock 路径不变；本决策只闭合 Local/Compose 最后一跳。
+- v2 revision 比 v1 多约 2 KiB provenance 文本。revision 数量仍由既有显式 evidence collection/保留策略约束。
+
+## 兼容与恢复
+
+- QingLong 3.0 尚未正式发布，不保留 v1 裸 image 旁路。已有孵化环境必须用原 catalog-bound selection 重新 prepare；不要手改
+  `compose.image.yaml` 或 revision。
+- command/selection 必须作为恢复证据保留。响应丢失时原样重放同一 command、path 与 expected digest；任何 selection byte、权限、
+  parent、root policy 或 catalog binding 漂移都在 deployment mutation 前失败。
+- revision 切换后的 rollout 失败继续使用既有 generation CAS 和 roll-forward rollback；rollback revision 保留原目标 release 来源。
+
+## 被拒绝的替代方案
+
+### 继续手工复制 `service.image`
+
+拒绝。它在最后一跳重新引入无法机器证明来源的开放字段，使 ADR-0431 的 catalog binding 只停留在工作站文件中。
+
+### 在目标机重新运行完整 catalog ceremony
+
+拒绝。低配设备不应承担 registry/GitHub 凭据、外部二进制、网络和完整 bundle 成本；在线验真仍属于可信工作站。
+
+### 验证 selection 后自动 Apply
+
+拒绝。输入可信不等于变更获批；revision preparation、Docker preflight 与 rollout 必须保持不同 authority。
+
+### 新建一个 selection-consumer package
+
+拒绝。该能力只服务现有 Local deployment Compose 边界；拆包会制造单一消费者和浅 package，而不会形成可独立部署的职责。
+
+## 验证
+
+- Local deployment 定向契约 30/30，覆盖 Prepare、Upgrade、Rollback、response-loss、Preflight、Apply、Restore、Evidence
+  collection、Status，以及 raw image、expected digest、权限、mutable image 和 catalog/release-set 漂移的
+  mutation-before-failure；物理 Edge Compose storage 契约 6/6；
+- Local Owner 全量 171 项为 166 pass/5 条件 skip/0 fail；backend 1,317 项为 1,315 pass/2 条件 skip/0 fail；18-package
+  clean build/test 退出 0。workspace 保持 18 packages，`singleSourcePackages=[]`、`shallowSourcePackages=[]`；
+- 10 项架构/部署审计和 14 档 Local artifact 全部 compatible；默认 Edge/Standalone 制品保持
+  2,589,890/2,589,968 bytes，application 为 3,632,769/3,632,889 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster
+  Admin exact dry-run pack 为 250 files、271,238-byte tarball、1,690,196-byte unpacked；
+- PostgreSQL 18.6 arm64 physical HA 重新通过 142/142、timeline `1→2`，报告 SHA-256 为
+  `07c914551ec700da26b42cd42760ccb3b28ad31266a8bae5f62dee38eb97e6a9`；离线审计通过且无 `ql3-ha-*` Docker 资源残留；
+- live rollout 使用明确标记的临时 synthetic selection，只测试镜像/Compose 兼容性，不冒充公开 catalog ceremony。完整结果
+  同步记录在 QL-RFC-0001 D-340。

docs/adr/README.md

@@ -435,6 +435,7 @@
 | [ADR-0429](./ADR-0429-offline-release-set-deployment-lock-materialization.md)                 | 离线 Release-set Deployment Lock 物化                                                                                                                             | Accepted |
 | [ADR-0430](./ADR-0430-auditable-release-catalog-consumption-ceremony.md)                       | 可审计的 Release Catalog 消费工作站 Ceremony                                                                                                                       | Accepted（真实公开 catalog 运行待实际 release tag） |
 | [ADR-0431](./ADR-0431-catalog-bound-deployment-lock-chain.md)                                  | Catalog-bound Deployment Lock 证据链                                                                                                                               | Accepted（真实公开 catalog 运行待实际 release tag） |
+| [ADR-0432](./ADR-0432-target-side-catalog-bound-local-compose-revisions.md)                     | 目标侧 Catalog-bound Local Compose 修订                                                                                                                            | Accepted |
 
 ## 规则
 

docs/operations/ql3-local-deployment.md

@@ -13,6 +13,8 @@
 - 已安装 `ql3-local-deploy` 与 `ql3-local-application`；
 - 使用最终运行 QingLong 的同一个 POSIX 用户；
 - command file 的父目录为当前 UID 的 canonical `0700` 目录；
+- Compose 的 catalog-bound Local v2 selection 也必须位于当前 UID 的 canonical
+  `0700` 目录中，文件自身为 canonical、current-UID、单链接 `0600`；
 - 生产环境建议使用非 root 用户。只有 root-only 路由器才将
   `allowRootService` 明确设为 `true`。
 
@@ -502,16 +504,27 @@ sudo rc-service qinglong3 start
 
 ## 5. Rootless Compose
 
-Compose 命令只接受不可变 digest，不接受 `latest` 或普通 tag：
+Compose 命令不再接受裸 image 字段。先按
+[Release-set 部署流程](./ql3-release-set-deployment.md) 在可信工作站生成并审计
+catalog-bound Local v2 selection，再把该私有文件及 audit 返回的 exact
+`selectionDigest` 交给目标机：
 
 ```json
 {
   "kind": "compose",
-  "image": "registry.example/qinglong3-local@sha256:REPLACE_WITH_64_HEX_DIGEST",
+  "releaseSelection": {
+    "path": "/secure/operator/qinglong3-local-selection-3.0.0.json",
+    "expectedSelectionDigest": "sha256:REPLACE_WITH_64_HEX_DIGEST"
+  },
   "allowRootService": false
 }
 ```
 
+目标机只做一次有界私有 JSON 读取、canonical shape/self-digest/catalog binding
+校验并取出唯一 `ghcr.io/<owner>/qinglong3-local-application@sha256:...`。它不运行
+Cosign、GitHub CLI、regctl 或 Kustomize，不访问网络，也不会因此获得 rollout authority。
+旧 `image` 输入失败关闭，不提供手工复制旁路。
+
 它生成 `service/compose.yaml`，固定 numeric UID:GID、read-only rootfs、唯一 bind
 mount、无网络、drop all capabilities、no-new-privileges、16 MiB tmpfs 与
 Profile memory/PID 上限。application config 自动使用容器内
@@ -543,8 +556,10 @@ docker compose \
 输出必须精确等于已审核的 `@sha256` image。不得省略或调换第二个 override 文件，
 也不得另加第三个 Compose 文件覆盖 image。
 
-基础文件包含从 `instanceId` 派生的稳定 Compose project name；override 同时把
-generation/mutation 写入 container label。不要使用 `-p`、`COMPOSE_PROJECT_NAME`
+基础文件包含从 `instanceId` 派生的稳定 Compose project name；override 使用 v2
+revision 格式持久保存 selection/release-set/catalog manifest/catalog consumption report
+digest、release identity、immutable catalog reference 与 root policy，并把 generation、
+mutation 和核心 provenance 写入 container label。不要使用 `-p`、`COMPOSE_PROJECT_NAME`
 或第三个 override 改写这些身份。
 
 当前仓库仍没有可引用的本机远端 release digest。ADR-0195 已提供
@@ -574,15 +589,16 @@ pnpm sbom:local-image:ql3
 pnpm audit:image-release:ql3
 ```
 
-本地 tag/image ID 不是可发布 digest。只有 release workflow 返回的
-`ghcr.io/<owner>/qinglong3-local-application@sha256:...`，且同一 digest 的
-双架构 manifest、Cosign、SLSA、CycloneDX 远端 verify 全部成功后，才可写入
-D-184 Compose 私有输入；永远不得替换成 mutable tag。
+本地 tag/image ID 不是可发布 authority。只有 release workflow 返回的
+`ghcr.io/<owner>/qinglong3-local-application@sha256:...`，且同一 release-set 的
+双架构 manifest、Cosign、SLSA、CycloneDX、immutable catalog ceremony 与 deployment-lock
+audit 全部成功后，才可把 Local v2 selection 的路径和 digest 写入 Compose 私有输入；
+永远不得替换成裸 digest 或 mutable tag。
 
 ## 6. Compose 镜像升级和选择回退
 
-升级前先完成 D-186 的 digest/attestation/signature 回读，并把 exact image 预取到
-设备。随后创建新的私有 command file：
+升级前先完成 release catalog consumption ceremony 与 Local deployment-lock audit，并按
+独立下载策略把 selection 绑定的 exact image 预取到设备。随后创建新的私有 command file：
 
 ```json
 {
@@ -594,7 +610,10 @@ D-184 Compose 私有输入；永远不得替换成 mutable tag。
   },
   "request": {
     "expectedGeneration": 1,
-    "image": "registry.example/qinglong3-local@sha256:REPLACE_WITH_64_HEX_DIGEST",
+    "releaseSelection": {
+      "path": "/secure/operator/qinglong3-local-selection-3.0.1.json",
+      "expectedSelectionDigest": "sha256:REPLACE_WITH_64_HEX_DIGEST"
+    },
     "mutationId": "REPLACE_WITH_UUID_V4",
     "changedAtMs": 1785254500000
   }
@@ -607,8 +626,8 @@ ql3-local-deploy compose-revision \
   --command-file /secure/operator/qinglong3-compose-upgrade.json
 ```
 
-成功返回 generation 2。结果未知时原样重放同一文件；不要修改 mutation、时间或
-expected generation。再次用 `config --images` 检查 selection，再由 operator
+成功返回 generation 2，并把完整 catalog provenance 固化到 immutable revision。结果未知时原样重放同一文件；
+不要修改 selection path/digest、mutation、时间或 expected generation。再次用 `config --images` 检查 selection，再由 operator
 先执行 rollout preflight。Docker 路径和 socket 都必须使用 `realpath`；典型
 rootful Linux 分别为 `/usr/bin/docker` 与 `/var/run/docker.sock`，rootless socket
 通常位于 `/run/user/<uid>/docker.sock`：

docs/operations/ql3-release-set-deployment.md

@@ -122,9 +122,11 @@ node scripts/ql3-deployment-lock-contract.cjs \
   --selection="${selection}"
 ```
 
-v2 selection 同时绑定 catalog immutable reference、manifest digest、consumption report digest 与 release-set digest。把已审计的
-`service.image` 和 `service.allowRootService` 交给现有 Local private prepare/rollout 入口。selection 本身不修改 Compose 文件，
-也不启动容器。是否允许 root service 必须显式给出，不能由设备默认值推断。
+v2 selection 同时绑定 catalog immutable reference、manifest digest、consumption report digest 与 release-set digest。不要再手工复制
+`service.image`。把 selection 放入目标运行 UID 控制的 canonical `0700` 目录，保持文件为单链接 `0600`，然后把它的 absolute path 与
+`local-audit` 返回的 exact `selectionDigest` 写入 Local prepare/upgrade 的 `releaseSelection`。目标侧会再次验证 canonical JSON、
+self-digest、release/catalog identity、唯一 GHCR Local image 与 explicit root policy，再把完整 provenance 固化到 Compose v2 revision。
+selection 本身不修改 Compose 文件，也不启动容器；prepare/upgrade 仍不等于 preflight/apply authority。
 
 ### Kubernetes / Cluster / Worker