ADR-0454：目标实例 Manual Primary Canary 与显式回滚仪式

状态：Accepted（仪式实现完成；首次真实用户目标实例执行仍待运维）
日期：2026-08-19
关联 RFC：QL-RFC-0001 D-361、PR-4、PR-5
关联 ADR：ADR-0002、ADR-0449、ADR-0450、ADR-0451、ADR-0453
Amends：ADR-0453 的首次目标实例 canary 操作缺口
Amended by：ADR-0455 的 Profile-bounded durable runtime activation receipt

上下文

ADR-0453 已提供 process-epoch capture authority、clean-shutdown evidence、closed terminal audit、compiled-backend rollback/resource report、Primary gate bundle 与 rollout manifest v2 loader，但维护者仍需手工拼接多个命令、文件名、时间窗口和摘要。只提供底层 gate 会留下四类运维缺口：

canary 开始前没有不可变计划绑定 Profile、精确样本数和当时的 live rollout 基线；
terminal/resource/gate 输出容易经 shell 重定向得到宽权限、部分写入或互相不属于同一 session 的文件；
qualification 与写入 live manifest 之间没有显式人工边界，配置选择又容易被误报成“当前进程已经激活”；
rollback 没有绑定被替换 manifest 的摘要，也没有 crash-replay intent/completion 链。

Edge 可能是 128 MiB 路由设备，不能为 canary 新增 daemon、watcher、遥测栈或第二数据库；Standalone 可能运行在集群节点上，但本仪式仍只裁决本机 edge|standalone Profile，不得借宿主机形态伪装成 cluster-control|worker Primary 证据。

决策

新增 qinglong/manual-primary-canary-plan@v1。prepare 只接受受控 session ID、edge|standalone、Edge 精确 8 条或 Standalone 32–128 条中由 operator 选定的精确 admission 数；它记录当前 qinglong3-rollout.json 为 absent 或 disabled+SHA-256。已有 enabled manifest 时拒绝准备。
plan 固定派生全部 basename，不接受调用方提供输出路径。config root 必须是当前 UID 拥有、非 symlink、group/world 不可写的真实目录；所有 artifact 均以 0600、同目录临时 inode、file fsync、hard-link no-replace 与 directory fsync 发布。重复调用只接受逐字节相同文件。
prepare 只输出三项部署环境：实际 Profile、QL3_SHADOW_ORIGINS=manual 与唯一 capture basename；它不写 enabled manifest、不启动任务、不重启服务。 operator 必须在隔离窗口中通过既有 Legacy 产品入口精确执行计划数量的 manual admission，并干净关闭同一 worker；任何额外 manual execution 都使样本不相等。
observe 只有在 capture qualified、单一 manual origin、计数精确且窗口结束至少五分钟后，才以固定参数启动 Node 24 terminal auditor。数据库必须为非 symlink、 group/world 不可写的普通文件；auditor 只读打开 SQLite。调用方不能注入 origin、window、settling、child script 或 shell。
resource 用固定 full + require-compiled + 8 samples 启动 ADR-0451 runner。它使用自身临时 SQLite，不接触生产数据库；低配设备必须在应用停止后运行，不能把与常驻 workload 争用内存后的失败解释为产品回归。
qualify 复用 ADR-0453 gate，但额外绑定 plan 文件摘要、三份 source 的原始文件摘要、三份 canonical JSON 摘要、精确 admission target 与 gate 文件摘要。现有 gate、partial qualification 或 response loss 只能通过原文件重放；source 在 qualification 后被替换时，mutating CLI 与独立 auditor 都失败关闭。
approve 是唯一写 live manifest 的操作。它要求显式 approvedBy，审批最短一分钟、最长 24 小时；先复核 plan 时的 absent/disabled 基线，disabled 基线先 no-replace 归档，再以同目录 fsync 临时文件和最终摘要复核发布 schema v2 manifest。结果状态固定为 activation_approved/primary_selected，并明确 requiresRestart=true、runtimeActivationObserved=false；配置选择不得冒充 HTTP worker 已完成 startup reconciliation 和 router activation。
应用重启后，实际运行态由 bootstrap 的 selected → reconciled → durable active receipt → activated 证明。ADR-0455 已让独立 auditor 复核 receipt 与 Linux boot/PID/start-time 联合身份，并新增 active 要求；off|rolled-back 同时要求不存在仍 current 的 runtime。非 Linux portable receipt 不能获得 current 结论。
rollback 只接受四个固定 reason 与有界 operator。它先 no-replace 发布 intent，绑定当前 enabled manifest SHA-256 和目标 disabled SHA-256，再复核当前摘要并原子替换 live manifest，最后发布 completion；intent 或 completion response loss 可用相同参数重放。disabled 已有效但不同于本 session 的目标时拒绝覆盖。
审批过期后，loader 对下一次 bootstrap 必须 fail-closed 为 off；状态/auditor 报 approvalExpired=true 和 rolloutMode=off。无 watcher 的既有进程不会仅因磁盘审批过期而自动卸载 router，故 off 审计会在 current receipt 仍存活时失败。operator 必须显式 rollback 并停止/重启应用；过期不能被当作自动续期、自动删除或已停止证明。

被拒绝的替代方案

常驻 watcher 自动检测 capture 并启用 Primary

拒绝。它把一次性证据变成后台控制面，增加路由设备 timer/文件监控成本，并绕过独立人工审批。

Canary CLI 自动触发八个用户任务

拒绝。工具没有用户会话、Task Policy、脚本内容或副作用 authority；synthetic spawn 不能证明真实 Legacy 产品入口的 admission capture。

用 enabled manifest 存在表示 Primary 已运行

拒绝。manifest 只在下次 bootstrap 被读取；进程可能尚未重启、startup reconciliation 可能失败或审批已经过期。selection 与 runtime activation 必须分开陈述。

原地覆盖证据和 rollout 文件以方便重试

拒绝。覆盖会丢失冲突和 crash window。证据采用 no-replace；live rollout 只在摘要复核后原子替换，并由 previous/intent/completion 文件保留恢复链。

资源、安全与部署影响

正常 QingLong runtime 不新增 import、timer、watcher、listener、数据库连接、schema、migration、package 或生产依赖。全部动作由 operator 一次性调用。
plan/qualification/selection/rollback 报告不包含数据库路径、命令、Task、Run、Cron、PID、日志、用户输出、错误正文或 Secret；stdout 只返回 stage、Profile、样本数和布尔状态。
observe 只读生产 SQLite；resource 只使用 runner 的临时 SQLite。Edge 应在应用停止后运行 resource，Standalone 也不得与同机生产 canary 并发争用。
POSIX owner 是本机信任根。摘要复核能防止误覆盖和非协作漂移，但不能防御同一 UID 在最后复核与 rename 之间的恶意并发；共享 config root 或远程 delegation 需要另行引入签名/锁服务，不得把本仪式描述成多写者共识。
本仪式不适用于 cluster-control|worker，也不证明物理路由、flash wear、断电、跨主机签名或真实生产任务安全。

验证

domain/CLI 聚焦矩阵覆盖 Edge/Standalone 样本预算、exact shape、短期审批、prepare 重放、unsafe root、disabled baseline drift、source replacement、partial qualification、selection receipt response loss、审批过期、rollback intent/completion response loss及独立审计。
真实 compiled backend 已通过 D361 prepare → resource：Edge plan 保持 automatic activation false；resource 阶段产生 qualified full rollback evidence， enabled/off 进程 peak RSS 分别为 109,953,024 / 102,383,616 bytes，真实 Legacy child 均 exit 0，Shadow Run delta 从 1 收敛为 0。
阶段门已重跑：聚焦 24/24、build:back、完整 backend 1,481 pass / 0 fail / 2 conditional skip、18-package clean build/test、四项架构审计与 14/14 artifact audit 全部通过；产物字节与 D-360 一致。隔离 frozen-lockfile Linux arm64 Docker 的 128 MiB router/256 MiB Edge release peak 分别为 81,887,232 / 148,840,448 bytes，memory.events max/oom/oom_kill 增量均为 0。
D361 不修改 PostgreSQL schema/migration、依赖树或 Kubernetes 拓扑，因此不重跑 PostgreSQL HA；任何仓库 synthetic fixture、compiled resource child 或 Docker arm64 结果都不沿用、也不冒充尚未执行的真实目标实例 manual capture/activation。

后续

维护者仍需在一台真实目标 Edge 或 Standalone 实例执行 Manual Primary Canary 操作手册，并保留 capture、terminal、resource、 gate、qualification、selection、bootstrap activated audit 与 rollback completion。其他 origin 必须建立自己的 admission authority 与 gate；固定物理路由/flash/断电、多写者 config authority 仍是独立后续工作；运行态 durable activation receipt 已由 ADR-0455 补齐，但首次真实目标实例执行仍待运维。

9.0 KiB Raw Blame History Unescape Escape