feat(ql3): add reviewed upgrade staging

docs/QINGLONG_3_0_ARCHITECTURE_RFC.md

@@ -1,5 +1,7 @@
 # QingLong 3.0 Architecture RFC
 
+- D-426a/ADR-0521（已实现源码候选，双架构实物待 CI）：二十天研发的阶段产物继续从“只读盘点”推进到仍不触碰生产切换的 side-by-side 暂存。Trial Kit 新增 canonical `upgrade-rehearsal.sh`，只接受操作者从 D-425 完整 evidence 中审核并显式提交的 SQLite/data-directory plan digest；它核对整包与 exact Operator identity 后，在新的 `0700/0600` rehearsal root 内以 read-only legacy bind、无网络、只读 rootfs、drop-all、128 MiB/0.5 CPU/32 PID 顺序执行 SQLite stage/verify/activation 和完整目录 stage/verify。`stage-summary.json` 绑定 source/architecture、两个 reviewed plan、SQLite manifest/activation 与目录 manifest digest，并固定 `legacySource=read_only`、`cutover=not_authorized`。Trial Kit/verification/auditor 升为 `@v7/@v5/@v4`，Local milestone 升为 `@v4` 并绑定双架构 `upgradeRehearsalSha256`；显式 artifact job 必须在将要上传的 exact bundle 上从 readiness plan 接续实跑 rehearsal。没有 transform/apply、Owner/Secret authority、2.x stop、3.0 target start、cutover、rollback、migration、依赖、package、daemon、listener、timer 或稳态资源增量；D-426b/c 才分别闭合 adopted start/clean rollback 与 write-after reconciliation。
+
 - D-425/ADR-0520（已交付同源双架构 headless Alpha 阶段实物）：二十天研发的 Local 阶段产物开始服务现有 2.x 部署，而不再只支持 fresh 数据根。Trial Kit 新增 manifest/checksum/auditor 共同绑定的 canonical `upgrade-readiness.sh`；它只接受 `edge|standalone`、canonical 2.x data root 和尚不存在的 evidence root，先核对 exact Operator image/source/architecture，再以当前 UID:GID、read-only legacy bind mount、只读 rootfs、`network=none`、drop-all capabilities、128 MiB memory/swap、0.5 CPU、32 PID 运行正式 `local-sqlite.adoption.inspect` 与 `local-data-directory.adoption.inspect`。两个完整 plan 写入独立 `0700/0600` evidence，不解析或代替人工审核，不执行 stage、activation、transform/apply、cutover 或 rollback。Trial Kit/verification/auditor 升级为 `@v6/@v4/@v3`，Local milestone 升级为 `@v3` 并直接绑定双架构 readiness script digest；显式 artifact job 必须在原生 amd64/arm64 上创建生产形态 2.x fixture，实跑将要上传的 exact 脚本并要求两个结果均为 `inspected`。无新 package、依赖、migration、listener、daemon、timer、watcher 或 Cluster authority；聚焦 bundle/milestone/stage/fixture 回归为 `30/30`。提交 `d6571e4b89eaf29ed6277dd08bbd7ffb57a3705d` 的普通 CI [run 33295923855](https://github.com/whyour/qinglong/actions/runs/33295923855) 为 41 success/3 expected artifact-finalizer skip/0 fail，同源 Kubernetes deployment [run 33295923822](https://github.com/whyour/qinglong/actions/runs/33295923822) 成功；显式 Local headless [run 33300121149](https://github.com/whyour/qinglong/actions/runs/33300121149) 为 42 success/2 scope skip/0 fail，两个原生架构均实跑 exact readiness 并由 bundle auditor 返回 `compatible=true`，下载后的 milestone v3 再确认 source/run/attempt 与两个不同 readiness digest 闭合。amd64/arm64/milestone artifact 保留至 2026-09-29；它们仍为 `alpha_candidate_not_public_release`，该切片也仍只是完整 side-by-side 升级与 clean/write-after 回退 rehearsal 的第一阶段。
 
 - 全范围 Alpha 阶段交付已形成真实实物：提交 `97333da34cce48cdfcfa1bbd5e8d48340802d2ef` 的显式 `all + headless` run `33265538836` 为 44/44 success，首次同时生成 Local headless 双架构 Trial Kit、Cluster control/control-ai/admin/worker 双架构 bundle、Local/Cluster milestone 和 `qinglong/alpha-stage-index@v2`。下载后的三个小索引均通过 `SHA256SUMS` 与仓库离线 auditor，绑定同一 source、workflow SHA/ref、run/attempt；stage index 为 Edge、Standalone、Cluster 精确选择 10 个 artifact。低配设备只需目标架构 Local 包且稳态仅运行 Application；集群节点只需目标架构 control/admin/worker，control-ai 显式可选。该交付保留至 2026-09-28，成熟度仍为 Alpha Integration Candidate，不等同于长期下载、受保护 tag、不可变 GHCR digest、签名、生产 deployment lock、2.x 升级/回退或 LTS。

docs/adr/ADR-0521-reviewed-side-by-side-local-upgrade-stage.md

@@ -0,0 +1,43 @@
+# ADR-0521：受审核计划驱动的 Local Side-by-side 升级暂存
+
+- 状态：Proposed（源码候选；原生 amd64/arm64 Trial Kit 实物待 CI 生成）
+- 日期：2026-08-30
+- 决策：D-426a
+
+## 上下文
+
+D-425 让既有 2.x 部署可以用可下载 Trial Kit 只读生成 SQLite 与完整数据目录计划，但二十天研发不能长期停留在“能盘点、不能形成下一阶段实物”。另一方面，直接把 inspect 接成自动切换会绕过计划审核，并把复制、转换、运行新目标和回退混成一个不可审计动作。
+
+## 决策
+
+Local Alpha Trial Kit 增加 canonical `upgrade-rehearsal.sh`。操作者必须显式提供 D-425 两个完整结果中已经审核的 64 位 `planDigest`；脚本不从终端输出猜测或替操作者批准计划。它只接受 `edge|standalone`、canonical 2.x data root 和尚不存在且与旧根互不包含的 rehearsal root。
+
+脚本核对整包 checksum、exact Operator image ID/source/architecture 后，以当前 POSIX UID/GID、无网络、只读 rootfs、drop-all capabilities、128 MiB、0.5 CPU、32 PID 的短生命周期 Operator 顺序执行：
+
+1. `local-sqlite.adoption.stage`；
+2. `local-sqlite.adoption.verify`；
+3. `local-sqlite.activation.prepare`；
+4. `local-data-directory.adoption.stage`；
+5. `local-data-directory.adoption.verify`。
+
+2.x root 在全部命令中始终是 read-only bind mount；目标、recovery、manifest、activation、完整目录 staging 和每次产品命令结果只写入新的 `0700/0600` rehearsal root。最终 `stage-summary.json` 精确绑定 source、架构、两个 reviewed plan digest、SQLite manifest/activation digest 和目录 manifest digest，并固定声明 `legacySource=read_only`、`cutover=not_authorized`。
+
+该阶段不执行 data-directory transform/apply，不建立 Owner/Secret authority，不停止 2.x，不创建或启动 3.0 Application 容器，也不授权 target start、cutover、Legacy rollback 或生产写入。失败后的 rehearsal root 作为诊断证据保留，不自动删除或重用。
+
+Trial Kit/verification/auditor 升级为 `qinglong/alpha-local-trial-kit@v7`、`qinglong/alpha-local-trial-kit-verification@v5`、`qinglong/alpha-local-trial-kit-audit@v4`，新增 `legacyUpgradeStage=passed` 和 `upgradeRehearsalSha256`。Local milestone 升为 `qinglong/alpha-local-milestone@v4`，直接绑定两个原生架构不同的 rehearsal script digest；Stage index 只接受该新 Local milestone schema。
+
+## 阶段实物门
+
+普通 push/PR 只验证源码，不生成可交付实物。显式 Local Alpha artifact job 必须在将要上传的 exact bundle 上：
+
+1. 创建生产形态 2.x fixture；
+2. 实跑 bundle 内 `upgrade-readiness.sh` 并读取两个 plan digest；
+3. 把这两个 exact digest 交给 bundle 内 `upgrade-rehearsal.sh`；
+4. 要求 `stage-summary.json.status=verified`、`legacySource=read_only`、`cutover=not_authorized`；
+5. 再由闭合 bundle auditor 和双架构 milestone finalizer 审计后上传。
+
+缺少任一原生架构、完整 CI、milestone v4 或 exact script digest 的 archive 都只是中间文件。
+
+## 后续
+
+D-426b 才处理受认证的 data-directory transform/apply、adopted deployment bundle、目标启动/停止和 clean `rollback_candidate`；D-426c 再闭合目标产生新事实后的 `reconciliation_required`。Public prerelease/release 仍需维护者显式授权。

docs/adr/README.md

@@ -523,7 +523,8 @@
 | [ADR-0517](./ADR-0517-strong-local-console-task-authoring-lease.md)                               | 强认证 Local Console Task authoring lease                                                                                                                                                                                        | Accepted（D-422 双架构 milestone 已交付） |
 | [ADR-0518](./ADR-0518-local-console-cron-trigger-administration.md)                               | Local Console cron Trigger 管理                                                                                                                                                                                                  | Accepted（D-423 双架构 milestone 已交付） |
 | [ADR-0519](./ADR-0519-local-console-secret-backed-automation.md)                                  | Local Console Secret-backed 自动化                                                                                                                                                                                               | Accepted（D-424 双架构 milestone 已交付）         |
-| [ADR-0520](./ADR-0520-downloadable-local-legacy-upgrade-readiness.md)                              | 可下载的 Local Legacy 升级就绪盘点                                                                                                                                                                                               | Accepted（D-425 源码候选，双架构 Alpha 实物待生成） |
+| [ADR-0520](./ADR-0520-downloadable-local-legacy-upgrade-readiness.md)                              | 可下载的 Local Legacy 升级就绪盘点                                                                                                                                                                                               | Accepted（D-425 双架构 Alpha 实物已交付） |
+| [ADR-0521](./ADR-0521-reviewed-side-by-side-local-upgrade-stage.md)                                | 受审核计划驱动的 Local Side-by-side 升级暂存                                                                                                                                                                                       | Proposed（D-426a 源码候选，双架构 Alpha 实物待生成） |
 
 ## 规则
 

docs/operations/ql3-alpha-candidate.md

@@ -31,6 +31,7 @@
 | D-423 Console cron Trigger 管理切片 | 已复用既有 immutable Trigger、Task pin、durable schedule 与原子 audit authority；Console/API 可 list/read/create/update/enable/disable `qinglong/cron@v1`，真实 SQLite/loopback 与同源双架构 Console milestone 已通过 | Cluster 不复用 Local proof；不提供删除或通用 Trigger schema 编辑；仍不是正式发布或生产升级 |
 | D-424 Console Secret-backed 自动化切片 | current-only metadata、强认证 AES-256-GCM create/rotate 与 Task pinned `SecretRef` 绑定已完成；真实 SQLite/loopback、本地与远端门、同源双架构 Console milestone 及离线 auditor 均通过 | Cluster 不复用 Local proof/custody；不提供明文读取、删除或历史浏览；仍不是正式发布或生产升级 |
 | D-425 2.x 升级就绪盘点 | 同源 v6 Trial Kit 已交付 amd64/arm64 headless 阶段实物；canonical `upgrade-readiness.sh` 把 2.x root 只读挂载，在 128 MiB/无网络边界内由 exact Operator 生成 SQLite 与完整目录两个计划；artifact job 实跑、bundle auditor 与 milestone v3 均闭合 | 只完成 inspect，不授权 stage、activation、cutover 或 rollback；不是 Public Release |
+| D-426a Side-by-side 暂存 | v7 Trial Kit 源码候选新增 reviewed-plan `upgrade-rehearsal.sh`，在新的私有 root 中执行 SQLite stage/verify/activation 与完整目录 stage/verify；legacy root 始终只读，summary 固定 `cutover=not_authorized` | 原生 amd64/arm64 artifact 与 milestone v4 待生成；不执行 transform/apply、目标启动或回退 |
 
 D-421 已关闭 D-420 记录的“Web Task mutation 必须独立设计”缺口，而且没有改名复用 run `33173769047` 的旧 archive。修复提交 `dc1686bd6fb3505174dd9a14098ae5c2c92a1a7f` 的普通主 CI [run 33229592307](https://github.com/whyour/qinglong/actions/runs/33229592307) 为 41 success/3 expected artifact-finalizer skip/0 fail，同源 Kubernetes deployment [run 33229592293](https://github.com/whyour/qinglong/actions/runs/33229592293) 成功；随后显式 Local Console milestone [run 33230227006](https://github.com/whyour/qinglong/actions/runs/33230227006) 为 42 success/2 scope skip/0 fail。由此 Web 创建能力已进入新的阶段实物，而不再只是候选源码。
 
@@ -106,7 +107,7 @@ ADR-0506 的 `qinglong/alpha-local-trial-kit@v2` 首次增加 source-bound verif
 Local artifact 含：
 
 - 一个包含所选 Application 与短生命周期 operator 的 archive；headless 为 `qinglong3-local-trial-kit-<arch>.docker.tar`，Console 为 `qinglong3-local-console-trial-kit-<arch>.docker.tar`，共享 Node 基础层在 archive 中去重；
-- schema 为 `qinglong/alpha-local-trial-kit@v6` 的 `manifest.json`，通过 `variant/archive/images/sboms/quickstart/upgradeReadiness/readme/verification` 绑定版本、完整 source commit、架构、两个 image tag/image ID 与文件长度/SHA-256；
+- schema 为 `qinglong/alpha-local-trial-kit@v7` 的 `manifest.json`，通过 `variant/archive/images/sboms/quickstart/upgradeReadiness/upgradeRehearsal/readme/verification` 绑定版本、完整 source commit、架构、两个 image tag/image ID 与文件长度/SHA-256；
 - canonical `quickstart.sh`，在目标 Linux 设备上只依赖 POSIX shell、`sha256sum` 和 Docker，完成 checksum、load、identity、fresh Owner 与 Profile-bound Application active；
 - canonical `upgrade-readiness.sh`，把 2.x data root 只读挂载给 128 MiB/无网络 Operator，生成 SQLite 与完整目录两个私有 inspect 计划，不获得 stage/cutover authority；
 - `verification-evidence.json` 绑定 `workflow_dispatch` 的 workflow ref/SHA、run ID/attempt、同架构两个 exact image ID 和完整 gate 集；下载者仍须到 GitHub 交叉检查 run，它不替代正式签名；
@@ -115,7 +116,7 @@ Local artifact 含：
 
 Cluster artifact 是每角色/架构一个六文件闭包：native Docker archive、精确 CycloneDX SBOM、workflow-bound verification evidence、README、`qinglong/alpha-cluster-image@v1` manifest 和覆盖全部内容文件的 `SHA256SUMS`。完整 CI 成功后，八个 bundle 由 `qinglong/alpha-cluster-milestone@v1` 小型索引闭合；索引本身不重复存放大 archive。
 
-Local milestone 是 `qinglong/alpha-local-milestone@v3` 三文件闭包，绑定一个 variant 的双架构 Trial Kit，并直接记录两个架构的 `upgradeReadinessSha256`。Stage index 是 `qinglong/alpha-stage-index@v2` 三文件闭包；它重新审计两个 milestone，要求 version/source/workflow SHA/ref/run/attempt 一致，并把 Local variant/Profile 与 Cluster 的 control/admin/worker 最小集、可选 control-ai 写为机器可读选择；它不重复存放任何镜像 archive。
+Local milestone 是 `qinglong/alpha-local-milestone@v4` 三文件闭包，绑定一个 variant 的双架构 Trial Kit，并直接记录两个架构的 `upgradeReadinessSha256` 与 `upgradeRehearsalSha256`。Stage index 是 `qinglong/alpha-stage-index@v2` 三文件闭包；它重新审计两个 milestone，要求 version/source/workflow SHA/ref/run/attempt 一致，并把 Local variant/Profile 与 Cluster 的 control/admin/worker 最小集、可选 control-ai 写为机器可读选择；它不重复存放任何镜像 archive。
 
 任何 required job 失败时不上传对应产物。artifact 名和 archive 内的 `ci-*` tag 都表示 commit-bound candidate，不能改名后冒充 `v3.x` release。
 

docs/operations/ql3-local-alpha-milestone.md

@@ -20,7 +20,7 @@
    ```
 
 2. 打开 `manifest.json`，确认：
-   - `schema` 为 `qinglong/alpha-local-milestone@v3`；
+   - `schema` 为 `qinglong/alpha-local-milestone@v4`；
    - `variant` 为 `headless` 或 `console`，且两个架构记录都使用同一变体；
    - `sourceRevision` 是准备试用的完整 40 位提交；
    - `workflow.event` 为 `workflow_dispatch`，`workflow.job` 为 `local-alpha-milestone`；
@@ -28,7 +28,7 @@
    - `artifacts` 恰好包含 `amd64` 与 `arm64`。
 3. 根据主机架构下载 `artifacts.<architecture>.artifactName` 指向的 Trial Kit。
 4. 对 Trial Kit 先执行其 `SHA256SUMS`，再确认其中 `manifest.json` 的 SHA-256 与 milestone 的 `bundleManifest.sha256` 完全一致。
-5. 确认 milestone 的 `upgradeReadinessSha256` 与 Trial Kit manifest 中同名入口摘要一致，再按 Trial Kit 自带 `README.md` 完成 fresh smoke 或只读 2.x 升级就绪盘点。
+5. 确认 milestone 的 `upgradeReadinessSha256`、`upgradeRehearsalSha256` 与 Trial Kit manifest 中同名入口摘要一致，再按 Trial Kit 自带 `README.md` 完成 fresh smoke、只读 2.x 升级就绪盘点或受审核计划的 side-by-side 暂存。
 
 若持有同一版本源码与 Node.js 24，可额外审计 milestone 索引：
 

docs/operations/ql3-local-alpha-trial-kit.md

@@ -25,7 +25,7 @@ sha256sum --check SHA256SUMS
 
 `manifest.json` 必须满足：
 
-- `schema` 为 `qinglong/alpha-local-trial-kit@v6`；
+- `schema` 为 `qinglong/alpha-local-trial-kit@v7`；
 - `variant` 为 `headless` 或 `console`，并与 milestone、application SBOM 和 artifact 名一致；
 - `sourceRevision` 是你准备试用的完整 40 位 commit；
 - `architecture` 与主机相同；
@@ -114,6 +114,27 @@ artifact job 必须在原生 amd64/arm64 上使用生产形态 2.x fixture 运
 `inspected` 后才能记录 `verification-evidence.json.gates.legacyUpgradeReadiness=passed` 并上传。该证明仍不是用户实际磁盘、停机窗口、I/O 峰值或
 生产数据内容兼容性承诺。
 
+## 受审核计划的 Side-by-side 暂存
+
+审核上一节两个完整结果后，把其中 exact `evidence.planDigest` 作为显式参数交给 v7 bundle 的 canonical `upgrade-rehearsal.sh`：
+
+```sh
+sh upgrade-rehearsal.sh \
+  edge \
+  /opt/qinglong/data \
+  /opt/qinglong3-alpha-upgrade-stage \
+  <reviewed-sqlite-plan-digest> \
+  <reviewed-data-directory-plan-digest>
+```
+
+脚本在新的私有 rehearsal root 中完成 SQLite stage/verify/activation 与完整 data-directory stage/verify；2.x root 全程只读，Operator 仍为无网络、
+128 MiB、0.5 CPU、32 PID 的一次性容器。成功后保存 `stage-summary.json`、全部 command result、SQLite target/recovery/manifest/activation 和完整目录
+staging manifest。summary 必须是 `status=verified`、`legacySource=read_only`、`cutover=not_authorized`。
+
+这不是升级完成：本阶段不执行 transform/apply，不安装 Owner/Secret，不停止 2.x，不启动 3.0，也不授权 cutover 或 Legacy rollback。不要编辑、移动、
+复用或当作生产数据根；后续 adopted start 必须精确消费这里的 evidence，并走独立的 D-426b 门。artifact job 必须对将要上传的 exact 脚本使用同一个
+生产形态 fixture 实跑，并记录 `verification-evidence.json.gates.legacyUpgradeStage=passed`。
+
 ## 手工加载与最小 smoke
 
 从 `manifest.json.archive.file` 找到 archive 后加载：
@@ -141,7 +162,7 @@ docker run --rm --read-only --network none --cap-drop ALL \
 
 ## Fresh 试运行边界
 
-完整 fresh setup、首 Owner ceremony、Owner presentation 安装、Application active、SIGTERM drain、SQLite integrity 和原生 cancellation 必须在 `verification-evidence.json` 指向的同架构 milestone job 中验证。Console 还必须证明首页返回 200、未认证 API 返回 401，并用真实 Owner credential 完成 Task read、fenced start、`succeeded` 终态与 bounded log marker。v6 artifact job 必须从将要上传的目录实际执行 `quickstart.sh` 和 read-only `upgrade-readiness.sh`，并完成 graceful stop。实际部署时仍必须使用独立目录，并让 operator 以最终数据文件 POSIX owner 的 UID/GID 运行；operator 默认无网络且每次只执行一个命令后退出，不应作为 sidecar 或 daemon 常驻。
+完整 fresh setup、首 Owner ceremony、Owner presentation 安装、Application active、SIGTERM drain、SQLite integrity 和原生 cancellation 必须在 `verification-evidence.json` 指向的同架构 milestone job 中验证。Console 还必须证明首页返回 200、未认证 API 返回 401，并用真实 Owner credential 完成 Task read、fenced start、`succeeded` 终态与 bounded log marker。v7 artifact job 必须从将要上传的目录实际执行 `quickstart.sh`、read-only `upgrade-readiness.sh` 和 reviewed-plan `upgrade-rehearsal.sh`，并完成 graceful stop。实际部署时仍必须使用独立目录，并让 operator 以最终数据文件 POSIX owner 的 UID/GID 运行；operator 默认无网络且每次只执行一个命令后退出，不应作为 sidecar 或 daemon 常驻。
 
 Edge 的验证上限为 Application 128 MiB、0.5 CPU、64 PID；Standalone 为 256 MiB、0.5 CPU、256 PID；operator 为 128 MiB、0.5 CPU、32 PID。这里的数值是试运行门，不是所有 workload 的容量承诺。