feat(ql3): operationalize manual primary canary

This commit is contained in:
whyour
2026-08-19 04:29:15 +08:00
parent be98d6753b
commit 9981f47851
12 changed files with 2981 additions and 9 deletions
+29 -5
View File
@@ -11,6 +11,22 @@
最新增量证据(2026-08-19):
- D-361/ADR-0454(已接受;首次真实用户目标实例执行待运维):把 D-360 的 manual Primary evidence/gate 收敛为一次显式、可重放且不新增常驻组件的目标实例仪式。
`prepare → observe → resource → qualify → approve → status/audit → rollback` 固定为七个 operator-driven 阶段;Edge 精确 8 条,Standalone 由维护者在
32128 条内选择精确目标。prepare 绑定当时 absent/disabled rollout 基线并只输出 `QL_DEPLOYMENT_PROFILE``QL3_SHADOW_ORIGINS=manual` 和唯一
capture basename,不触发任务、重启或自动启用;observe 固定复用五分钟闭合窗口只读审计,resource 固定执行 compiled-backend full rollback。qualification 同时绑定
plan、三份原文件 SHA-256、canonical evidence SHA-256 与 Primary gateapprove 是唯一写 live manifest 的动作,显式审批最长 24 小时,并在最终写入前复核基线摘要。
写入结果只称 `activation_approved`/`primary_selected`,强制返回 `requiresRestart=true``runtimeActivationObserved=false`,不能冒充现有 bootstrap 已完成
`selected → reconciled → activated`。rollback 以 intent→摘要复核→disabled 原子替换→completion 链支持 response-loss 重放;审批过期立即按 off 解释,但仍要求显式
rollback 收敛磁盘事实。config root/证据要求当前 UID、非 symlink、group/world 不可写及 `0600` no-replace;路由设备不增加 daemon、watcher、timer、连接、package、
生产依赖、schema、migration 或部署对象。真实 compiled backend 已完成一次 Edge `prepare → resource`,只证明仪式固定 child/资源回滚入口可执行,不冒充真实产品入口的
8 条 manual admission、运行态 activation、物理路由、flash 或断电证据。阶段门已重跑:聚焦 `24/24``build:back`、完整 backend
`1,481 pass / 0 fail / 2 conditional skip`、18-package clean build/test、四项可执行架构审计与 `14/14` artifact audit 全部通过;14 档产物字节与
D-360 完全一致。使用隔离 frozen-lockfile Linux 依赖重新执行 arm64 Docker 门后,router stress 保持 `128 MiB / 0.5 CPU / 0 swap / 64 PID`cgroup peak
`81,887,232` bytesEdge release 保持 `256 MiB / 1 CPU / 0 swap / 128 PID`13 个 workload 全绿、peak `148,840,448` bytes,两档
`memory.events max/oom/oom_kill` 增量均为 0。D-361 不改 PostgreSQL schema/migration、依赖树或 Kubernetes 拓扑,故不重跑 PostgreSQL HA;相邻
D-359 的 `142/142` 与 timeline `1→2` 仅作为既有证据。
- D-360/ADR-0453(已接受;首次真实目标实例 manual canary bundle 待执行):不再用 2.x RunningInstance 推测 Legacy→Shadow 分母,也不再让 Primary
manifest 只信任维护者填写的 `"passed"`。默认 Legacy bridge 为每个已启用 origin admission 分配 process-epoch token,固定守恒
`captured + failed + pending = admitted`,失败只分 `fact/observer/initialization/accept`;只有真实 Shadow writer accept 才结算 capturedLegacy
@@ -8307,13 +8323,19 @@ Primary 不使用普通环境变量或宽泛全局开关启用。孵化配置面
- 文件缺失、不可读、超过 64 KiB、JSON 损坏、未知字段、过期审批或 gate 不完整时 fail-closed 为 `off`
- `defaultMode` 必须保持 `off`;当前 manifest 只允许声明 `manual`,不得用一个配置隐式接管 boot、定时、gRPC 或其他来源。
- 启用记录必须包含有界 revision、审批人、审批起止时间和 rollback plan 引用;审批窗口最长 30 天
- 启用记录必须包含有界 revision、审批人、审批起止时间和 rollback plan 引用;通用 loader 上限为 30 天,ADR-0454 的目标实例 manual canary 仪式进一步收紧为最长 24 小时
- `durableCancellation``startupReconciliation``atomicLegacyProjection``rollbackDrill``edgeBudget` 必须全部为 `passed`;从 schema v2 起这些声明不能
代替 Primary evidence bundle。
- enabled manifest 必须绑定同 config 目录的 `qinglong/legacy-shadow-primary-gate@v1` bundle basename 与 SHA-256。loader 必须 no-follow 读取、重算 embedded
capture/startup、terminal、resource source digest 和完整 eligibility,并复验 manual origin、实际 Profile 与审批时序;只验证 receipt 自称 eligible 不成立。
- 审计只记录路径、revision、判定、时间和源文件 SHA-256,不记录完整配置内容;接受判定必须在安装 owner router 前可观测,安装后审计失败必须撤销 router。
- edge 不启动文件 watcher。配置只在显式 bootstrap/reload 时读取,禁用时不创建 router、timer、连接或后台任务。
- ADR-0454 的 `prepare` 先以不可变 plan 绑定 Profile、精确 admission 目标和当时 absent/disabled rollout SHA-256`qualify` 再绑定 capture/terminal/resource 的原始文件摘要、
canonical 摘要和 Primary gate。只有显式 `approve` 能在复验 live 基线后写入本节 schema v2 manifest。
- `approve` 的 durable 结果是 `primary_selected`,不是 `primary_active`。operator 必须重启目标 worker,并从现有 bootstrap 的同 revision `selected → reconciled → activated`
结构化审计证明实际运行态;一次性独立 auditor 刻意不输出 active 结论。
- `rollback` 在 live manifest 替换前先写绑定 enabled/disabled 摘要的 intent,替换后再写绑定 intent 摘要的 completion;同参数重放覆盖两个 response-loss 窗口。审批过期按 off
解释但不会自动改写文件,仍需显式 rollback 和重启。
实验 manifest 结构固定为:
@@ -8352,8 +8374,8 @@ Primary 不使用普通环境变量或宽泛全局开关启用。孵化配置面
的 manual primary 配置才惰性加载真实组件。激活顺序固定为:重放 evidence→复验实际 Profile→记录 selected 审计→完整有界 startup reconciliation→记录
reconciled 审计→启动 completion/timeout/cancel lifecycle→安装 router→记录 activated;任何一步失败都会撤销 router,并按 producer → consumer 顺序停止
lifecycle。HTTP shutdown 与监听失败也会执行有界清理。`QL_DEPLOYMENT_PROFILE` 未配置时为 standalone,非法值、receipt Profile 不一致或在
cluster-control/worker 中误装本机 SQLite Primary 时 fail closed。首次目标实例 manual canary、固定物理 edge Gate、配置写入/用户可见状态和操作回滚演练完成后
仍需单独评审。
cluster-control/worker 中误装本机 SQLite Primary 时 fail closed。目标实例仪式、部署配置写入、只读选择状态和操作回滚工具已由 ADR-0454 固化;首次真实 Edge/Standalone
完整执行、bootstrap activated durable receipt、固定物理 edge/flash/断电 Gate 完成后仍需单独评审。
## 26. 交付阶段
@@ -8995,6 +9017,7 @@ flowchart LR
- 旧 Crontab 状态仍为用户可见事实源。
- 增加旧状态与 Shadow Run 对账日志和指标。
- 发现差异时只报告,不改变任务结果。
- 目标实例 canary 必须由不可变计划固定 Profile 和精确样本数,并通过真实产品 manual 入口执行;仪式不得代替用户发起任务或自动启用 Primary。
#### PR-5LocalExecutor 切换
@@ -9006,6 +9029,7 @@ flowchart LR
- 取消必须先原子写入 `run.cancel_requested`,再调用 Executor.stop;重复取消保持单事件,晚到 success 不覆盖已接受取消。
- 验证 task_before、task_after、work_dir、log_name 和多实例行为。
- Primary completion 只能写安全错误分类,不得把 Executor 原始错误、命令、环境或路径持久化到 error_summary。
- rollout 配置选择与运行态激活必须分离:短期审批只产生 `primary_selected`,重启后的 reconciliation/lifecycle/router 审计才可证明 activated;回滚必须保留可重放 intent/completion 链。
#### PR-6:只读 v3 Run API
@@ -9176,8 +9200,8 @@ flowchart LR
| PR-1 Run Schema | Incubating | Run/RunAttempt/RunEvent schema、nullable cancel request 与 Attempt deadline 字段及恢复索引、CancellationDispatch 状态/version/lease/backoff schema、Repository port、临时 Sequelize adapter、统一事件大小/分页上限、跨 adapter RunRepository contract suite(原子事务、回滚、Run/Attempt/RetryPolicy CAS、唯一错误、分页与取消恢复);ADR-0041 的 `pg-0003-run-retry-policy`、capability v2、driver-neutral PostgreSQL Run Repository 与真实 `pg.Pool` 上的共享 Repository/rollback/SQLSTATE contractADR-0063/0069/0071/0073/0074/0076 的独立 Node 24 local-sqlite typed schema、十二条 reviewed migration、capability v6、共享 operation authority、readiness/RunRepository/API credential repository/receipt journal/dispatch plan/encrypted Secret envelope/Project Policy/security audit/authorized mutation/stable Identity catalog、Drizzle↔真实 catalog table/column/index/CHECK/FK lockstep、base/adopted/application edge/standalone 产物门禁;ADR-0064 的 legacy baseline/plan digest、Online Backup recovery、side-by-side target migration、staged manifest、双库栅栏 activation、source 生命周期写栅栏、target stable identity 和重启语义;ADR-0065 的独立 cutover authority、外部副作用停机 evidence、append-only journal、start/restart/stop barrier 与 unknown→manual_required 收敛;ADR-0066 的 adopted storage→Run reconciliation→receipt maintenance→domain recovery→lifecycle→admission application gate、严格有界 recovery summary 与 admission-first reverse stopADR-0067 的 SQLite 事实驱动 Run 候选源、256 条硬上限、截断失败关闭和唯一 Repository authorityADR-0068 的 receipt-first Reconciler、callback token/sequence fence、exact local-process identity、Attempt/Run/双 Event 原子终态推进和最终 verifierADR-0069 的 local-process 单向包边界、pre-spawn journal、受审 POSIX launcher、immutable receipt、exact identity 和 Profile-aware cleanup lifecycleADR-0070 的独立 local-execution、spawn 前后双 transaction CAS、callback digest、exact stop 补偿与 fail-closed starting 保留;ADR-0071 的独立 local-dispatch、不可变 revision/context、Secret-first materializer、Profile Artifact admission、4/64 MiB output hard quota 和窄 application facadeADR-0073/0074 的 Project-bound SecretRef、AES-256-GCM、外置 keyring 生命周期、双 SQLite authority CAS、application preflight、强 Principal/Policy 和 envelope+audit 原子提交;ADR-0086 的本机 Owner provisioning/challenge/claim/delivery acknowledgement/credential recovery CLIADR-0377 的 Local/Cluster 同构、Profile-aware、Project-scoped Artifact range read | fresh database/pepper setup、credential rotation/GC 运维编排与 Secret/Project/Role/Approval 管理 CLI/API/UI、备份/rekey、2.x/target process controller、人工 recovery、target 写后 reconciliation 与完整 cutover/rollback 演练;retry 产品策略、Artifact retention/tombstone stack、具体本机 lifecycle 和 target executableLinux x64/arm64、PID namespace、断电与固定路由设备门禁;PostgreSQL 16/18 双连接并发与 failover integrationTask revision/context 跨方言 contract/并发压力与引用感知 retention、Keyv 数据迁移 |
| PR-2 Run 状态机 | Incubating | 纯转换表、终态/时间/错误/执行器元数据规则、Run version 与 event sequence CAS、事务性 RunCommandService、回滚测试 | 重复 Worker callback/fencing、并发数据库压力测试、Primary 执行链接入 |
| PR-3 Executor 端口 | Incubating | ADR-0003、ExecutionSpec/Context/Handle/Result、Executor port、LocalProcessExecutor、进程组取消/超时升级、流式背压、Legacy Cron spec builder、真实进程 contract tests、可复现 edge 基准入口 | 固定 edge/多架构设备基线、Legacy builder 与 makeCommand 差异审计、Primary 生产流量接入 |
| PR-4 Shadow Run | Incubating | origin 三态策略;默认关闭的 `QL3_SHADOW_ORIGINS`manual、scheduled_node、boot、subscription、system 与 script 现有 ChildProcess 旁路观察;system crond 显式 origin marker、Shell execution ID、finish-only 准入、确定性 Run/Attempt 与 exact replay`@once` 保持 manual、gRPC transport 不冒充 origin 的准入裁决;每个 worker 懒加载;Run/Attempt/Event 影子生命周期;稳定且不复制 caller 原文的 task identity/revision 与有界日志引用;同 worker 有界注册表和跨 worker 持久化候选关联;stop all/stop instance、Shell callback、乱序/迟到/歧义处理;监听前一次性、Profile-aware 的 keyset Startup Reconciler,终态证据补齐、lost/abandoned/pending 分流与 terminal Attempt response-loss 修复;origin-bounded 且逐级守恒的版本化 startup difference report、固定字段 metric batch 与一次性 collector;显式、只读、闭合窗口且 Profile-bounded 的 Shadow→Legacy 终态差异审计;128/256 MiB Linux arm64 资源门、SQLite 零增长与 Shadow enabled→off 进程重启回滚;process-epoch Legacy admission/capture/failure/pending 守恒;clean-shutdown `0600` no-replace capture+startup exportermanual Edge 8/Standalone 32128 canarycapture/terminal/resource 自包含 Primary bundlerollout v2 loader 重算 source digest 与 eligibility;失败开放和契约测试 | 首次真实目标实例 manual canary bundle、其他 origin 独立 capture/Primary gate、固定物理 edge/flash/断电证据 |
| PR-5 Primary LocalExecutor | Incubating(默认不激活,仅 manifest-gated manual | runtime-owned Run 创建器;持久化先于 spawnRun/Attempt 完整成功、失败、取消、超时与 lost 闭环;Executor handle 身份校验;spawn 后激活写失败的 stop+lost 补偿;completion rejection 安全收敛;独立 Primary 幂等查询与唯一索引竞态裁决;durable `run.cancel_requested`、stop-before-signal、首次请求幂等、晚到完成裁决与待取消有界恢复查询;最多 64 条一页的 cross-worker cancellation source;独立 CancellationDispatch Repository 原子 claim/result、lease expiry 接管、owner/token/version fencing、指数退避与结果 RunEvent;最多 64 页的单周期 cancel supervisor;显式 start/stop、无重叠、错误隔离、停止等待有上限且 timer unref 的 lifecycle runnerLinux durable handle 的 PID/boot/start ticks/process-group 复验与 TERM/KILL controller;完整有界分页且 fail-closed 的 startup Reconcile supervisorRunningInstance nullable `run_id/attempt_id` 关联;Primary 专用组合 Repository 在同一 SQLite 事务提交前投影 Crontab/RunningInstance,失败整体回滚;有界且防穿越的 legacy log output refmanual owner seam、真实本机装配、单 spawn/fail-closed;严格 manual-only rollout manifest loader、短期审批/gate、配置哈希审计;HTTP worker 已接轻量 lazy bootstrapaccepted 后按 receipt-first reconcile→completion receipt lifecycle→timeout intent lifecycle→cancel dispatch lifecycle→router 顺序激活,失败撤销,监听失败和 shutdown 有界停止;Primary timeout 在 spawn 前持久化绝对 deadline,有界 source/requester/supervisor 只提交 timeout 意图并复用 CancellationDispatch;代码级 edge/standalone Profile 为各 lifecycle 提供不同 cadence 与页上限,cluster-control/worker 拒绝误装本机 SQLite Primary;统一 CompletionService 原子提交 Attempt/Run/双 Eventspawn 前保存 callback token hash、终态推进 sequence,实时回调与 receipt consumer 共享入口并覆盖两个清理 crash windowmanual Primary 已接入受限 POSIX launcher、`0600` direct-file stdout/stderr、父进程退出后续写、不可覆盖 receipt 生产、回执环境清除、TERM 转发等待及 live transaction 后清理;Startup Reconciler receipt-first 双检查并在确定 exited 后执行 profile 化的单次 50/100 ms publish grace`0007` 独立 CompletionReceiptJournal 在 spawn 前登记、为升级前 active Attempt 补登记并驱动周期扫描,使终态残留继续可发现;确定无效的已知 Attempt receipt 先持久化隔离状态,再进入确定性私有分片 quarantine;终态 missing 与 quarantine 按 edge/standalone retention 有界清理;非 Journal 文件具备只读优先、固定分片/条目上限、overflow fail-closed、显式同盘隔离的 Node 24 运维 CLI;扫描具备页上限、resume cursor、timer unref、无重叠、有界 stop 和低敏计数;ENOSPC 与 launcher receipt 存储失败有代码门禁 | 部署配置写入/审批入口与用户可见状态PostgreSQL CancellationDispatch adaptercluster-control 生产启动拓扑;固定 edge/Linux 多架构与真实磁盘压力基线、完整 2.x API 契约和回滚演练 |
| PR-4 Shadow Run | Incubating | origin 三态策略;默认关闭的 `QL3_SHADOW_ORIGINS`manual、scheduled_node、boot、subscription、system 与 script 现有 ChildProcess 旁路观察;system crond 显式 origin marker、Shell execution ID、finish-only 准入、确定性 Run/Attempt 与 exact replay`@once` 保持 manual、gRPC transport 不冒充 origin 的准入裁决;每个 worker 懒加载;Run/Attempt/Event 影子生命周期;稳定且不复制 caller 原文的 task identity/revision 与有界日志引用;同 worker 有界注册表和跨 worker 持久化候选关联;stop all/stop instance、Shell callback、乱序/迟到/歧义处理;监听前一次性、Profile-aware 的 keyset Startup Reconciler,终态证据补齐、lost/abandoned/pending 分流与 terminal Attempt response-loss 修复;origin-bounded 且逐级守恒的版本化 startup difference report、固定字段 metric batch 与一次性 collector;显式、只读、闭合窗口且 Profile-bounded 的 Shadow→Legacy 终态差异审计;128/256 MiB Linux arm64 资源门、SQLite 零增长与 Shadow enabled→off 进程重启回滚;process-epoch Legacy admission/capture/failure/pending 守恒;clean-shutdown `0600` no-replace capture+startup exportermanual Edge 8/Standalone 32128 canarycapture/terminal/resource 自包含 Primary bundlerollout v2 loader 重算 source digest 与 eligibility不可变 prepare/observe/resource/qualify 目标实例仪式、独立只读 audit;失败开放和契约测试 | 首次真实目标实例完整 canary 与 bootstrap activated 记录、其他 origin 独立 capture/Primary gate、固定物理 edge/flash/断电证据 |
| PR-5 Primary LocalExecutor | Incubating(默认不激活,仅 manifest-gated manual | runtime-owned Run 创建器;持久化先于 spawnRun/Attempt 完整成功、失败、取消、超时与 lost 闭环;Executor handle 身份校验;spawn 后激活写失败的 stop+lost 补偿;completion rejection 安全收敛;独立 Primary 幂等查询与唯一索引竞态裁决;durable `run.cancel_requested`、stop-before-signal、首次请求幂等、晚到完成裁决与待取消有界恢复查询;最多 64 条一页的 cross-worker cancellation source;独立 CancellationDispatch Repository 原子 claim/result、lease expiry 接管、owner/token/version fencing、指数退避与结果 RunEvent;最多 64 页的单周期 cancel supervisor;显式 start/stop、无重叠、错误隔离、停止等待有上限且 timer unref 的 lifecycle runnerLinux durable handle 的 PID/boot/start ticks/process-group 复验与 TERM/KILL controller;完整有界分页且 fail-closed 的 startup Reconcile supervisorRunningInstance nullable `run_id/attempt_id` 关联;Primary 专用组合 Repository 在同一 SQLite 事务提交前投影 Crontab/RunningInstance,失败整体回滚;有界且防穿越的 legacy log output refmanual owner seam、真实本机装配、单 spawn/fail-closed;严格 manual-only rollout manifest loader、短期审批/gate、配置哈希审计;HTTP worker 已接轻量 lazy bootstrapaccepted 后按 receipt-first reconcile→completion receipt lifecycle→timeout intent lifecycle→cancel dispatch lifecycle→router 顺序激活,失败撤销,监听失败和 shutdown 有界停止;Primary timeout 在 spawn 前持久化绝对 deadline,有界 source/requester/supervisor 只提交 timeout 意图并复用 CancellationDispatch;代码级 edge/standalone Profile 为各 lifecycle 提供不同 cadence 与页上限,cluster-control/worker 拒绝误装本机 SQLite Primary;统一 CompletionService 原子提交 Attempt/Run/双 Eventspawn 前保存 callback token hash、终态推进 sequence,实时回调与 receipt consumer 共享入口并覆盖两个清理 crash windowmanual Primary 已接入受限 POSIX launcher、`0600` direct-file stdout/stderr、父进程退出后续写、不可覆盖 receipt 生产、回执环境清除、TERM 转发等待及 live transaction 后清理;Startup Reconciler receipt-first 双检查并在确定 exited 后执行 profile 化的单次 50/100 ms publish grace`0007` 独立 CompletionReceiptJournal 在 spawn 前登记、为升级前 active Attempt 补登记并驱动周期扫描,使终态残留继续可发现;确定无效的已知 Attempt receipt 先持久化隔离状态,再进入确定性私有分片 quarantine;终态 missing 与 quarantine 按 edge/standalone retention 有界清理;非 Journal 文件具备只读优先、固定分片/条目上限、overflow fail-closed、显式同盘隔离的 Node 24 运维 CLI;扫描具备页上限、resume cursor、timer unref、无重叠、有界 stop 和低敏计数;ENOSPC 与 launcher receipt 存储失败有代码门禁;显式最长 24 小时 approve 写入、`primary_selected` 只读状态、selection receipt、approval-expiry off 与 intent/completion crash-replay rollback | 首次真实目标实例激活/回滚及 durable runtime activation receiptPostgreSQL CancellationDispatch adaptercluster-control 生产启动拓扑;固定 edge/Linux 多架构与真实磁盘压力基线、完整 2.x API 契约和回滚演练 |
| PR-7 Worker Session、Run Lease 与启动协议基础 | Incubating(默认关闭,独立入口显式 opt-in | ADR-0012/0013/0014/0021/00570061/01080121/02310239/0377;有界 capability/Placement/DispatcherSQLite 协议孵化与 PostgreSQL v9 Session/Run Lease/credential/attestation authorityimmutable revision Placement、数据库时钟 keyset candidate、认证 Worker Pull、digest-only offer recoveryversioned capability-free ExecutionSpec response、stable claim 跨重启退避、单 owner 原子 inbox 准入与 TLS 1.3 mTLS/`ql3w` HTTPS client;同一 package journal 上 revision-fenced starting/spawn/started/running/completion 状态、callback digest、tagged no-spawn 与 ambiguous recoveryPostgreSQL starting/running/start-failure/completion 数据库权威事务、精确重放与 cancellation/timeout 优先终态;batch Secret delivery 在 Attempt advisory lock 下复验 Session/Lease/revision 完整围栏并复用单 AgentSecret-before-Artifact materializer 将同一 log ID 交给 Executor/journal/running ACKoffer-scoped `wlog-*` 私有文件 spool、Edge/Node 容量策略、append/quota/path 防护、barrier 后 output ownership、受审 POSIX Executor、truncation fact、固定内存流式 source、认证 Artifact stream、共享 immutable store port、S3-compatible SSE/checksum/条件 promotion adapter、upload-before-completion 协调,以及 Local/Cluster 同构、Profile-aware、ETag-fenced range read;用户取消 run.stop mutation 以数据库时间写 intent/Event 并在事务内复验 Project/RoleBinding fence;非执行取消 convergence lifecycle、运行期 expiry 与安全 lost retry 已接入 cluster-control 单一全局 cadence;完整 generation/version/token/Attempt fencing;独立最小权限 Worker ingress、CA/CRL 与连接 generation 热重载;offer journal、spawn barrier、receipt-first recovery;独立 `@qinglong/worker-runtime` 的本地 P-256 CSR、key/chain/trust 验证、generation + active pointer 安装和持久退避;默认关闭的 production process 已装配具体 execution graph、完整 Session heartbeat/drain/offline、direct-file bootstrap、单 Agent/单 cadence、startup reconciliation、证书 maintenance、transport fail-close/recovery 与 Edge/Node 有界预算;真实 PostgreSQL 18 + Linux Node 合约已覆盖 Run completion、credential 和 CA 双轮换且保持同一 Session;真实 K3s 合约已覆盖 TLS/credential Secret 分权、双对象 CAS、Recreate 顺序、identity generation 与单节点 PVC recovery;所有能力默认不可达且受 edge/cluster import audit 约束 | 具体 cert-manager/Vault/SPIFFE/离线 CA adapter 与模板、ingress reload controller、生产 RBAC、证书到期告警和 `ql3w` credential recovery 产品面;具体 KMS/Vault Secret provider、对象存储 credential/temporary lifecycle 与 retention/tombstoneWorker 管理 API;真实 Kubernetes 多节点 CSI/node-loss/production 360 秒 drain 与固定 edge 文件系统 suspend/时钟/断电、x64/arm64 资源门禁 |
| PR-8 Project/Policy/Approval Core | Incubating(默认拒绝、无生产业务执行入口) | ADR-0028;统一六类 ActorRef 与 exact-shape 校验;`0017` ownerless default Project 和 append-only versioned RoleBindingowner/admin/operator/viewer 固定矩阵;Project 内 mutation 幂等、expected-version CAS、双 SQLite 连接竞争门禁;archived read-only、revocation、存储损坏 fail-closedAgent 写/Secret/Tool `require_approval`ADR-0047 把六类 subject、role/permission matrix 与 fence 抽到 runtime-core`pg-0004-project-policy`/capability v3 建立 ownerless PostgreSQL baseline、严格 role/state CHECK、append-only runtime 权限、SERIALIZABLE Project lock、mutation replay、双连接单 winner 和 cluster admission authorizerADR-0049/`pg-0005` capability v4 建立 stable IdentitySubject、append-only digest-only API credential、真实 cluster bearer authenticator、write-only durable security audit 与最小权限 runtime role,且已验证 HTTP→credential→Policy→audit→handler 纵向链路;ADR-0051 建立 `/api/v3` 认证前 peer/global 双预算、transport-peer-only、无 timer 且有界内存的 overload shieldADR-0027 Artifact authorizer adapterADR-0029 `AuthenticatedPrincipal` contract、`0018` digest-only versioned challenge、CSPRNG/TTL、同事务消费 challenge + 写首 owner、精确重放与双连接竞争/崩溃回滚门禁;ADR-0030 `0019` stable identity/binding、legacy HS384 + current-session membership、logout/platform/revoke/disable、single-factor 与损坏 fail-closed 门禁;ADR-0031 `0020` digest-bound ApprovalRequest、User-only decision、Project/Role version fence、精确 expiry/重放/并发裁决及同事务 immutable dispatchADR-0032 `0021` execution backfill、三表原子 consume、稳定 due keyset、claim/renew/start/result fencing、pre-start takeover/post-start recovery-required、attempt budget、handler inspect/digest barrier 和 bounded dispatcherADR-0033/`0022` control/resolution backfill、start/renew/completion 原子联动、稳定 recovery keyset、双 resolver claim/takeover、finding/result 精确重放、自动/人工终结、迟到 completion 单 winner 和 evidence-only bounded reconcilerADR-0034/`0023` 首个 `run.create` canonical plan、Run/Attempt/Event/receipt 同事务、幂等 collision fail-closed、renew/终态 fence、真实 SQLite handler 与 automatic evidence providerADR-0035/`0024` 独立 `approval.recover` 矩阵、稳定 User + 五分钟强认证、Project/RoleBinding fence、human resolution + authorization fact 原子提交、撤权竞态与回滚门禁;ADR-0036 recovery-first 单 timer lifecycle、edge/standalone 独立 cadence/页预算、跨周期 cursor、非重叠与有界 stopADR-0074 以新的 Node 24 SQLite v5 ownerless Project/RoleBinding/audit authority 和独立 local-secret-admin 提供强 Principal、`secret.manage`、撤权 fence、envelope+allowed audit 原子提交及不回显语义;ADR-0086 以可信 POSIX console 和 staged delivery 完成本机首 Owner 产品 ceremony | fresh database/pepper setup 与安全迁移向导;`shareStore`/Express 到 authentication core 的 production migrationcredential rotation/revocation API、mTLS/Worker enrollment、恢复码;Project/Role/Approval/Secret 管理 CLI/API/UI、audit retention/query/export/alert、preview Artifact/digest/immutable plan builder、真实 MFA/hardware adapter、人工 recovery API/UI/独立 rate limit 与审计事件、handler/provider registry、lifecycle startup/shutdown/指标/admission gatePostgreSQL action/receipt/provider/recovery-authorization 与 OPA adapter、缓存 version 失效;Tool/Package/Secret/Shell 各自的 handler/evidence contractSecret/Run/Tool/Workflow waiting_approval 全入口装配;完整回滚演练 |
@@ -170,10 +170,13 @@ owner 在接受触发时写入执行上下文,并贯穿日志、指标和回
- `defaultMode` 固定为 off,当前只允许 `origins.manual`;Primary 不得通过环境变量、通配 origin 或隐式默认值开启。
- enabled manifest 必须记录 revision、approvedBy、approvedAtMs、expiresAtMs 和 rollbackPlanRef;审批窗口最长 30 天。
- `durableCancellation``startupReconciliation``atomicLegacyProjection``rollbackDrill``edgeBudget` 必须全部为 passed。
- ADR-0453 后 enabled manifest 还必须绑定可由 loader 独立重算的 manual capture/terminal/resource Primary gate bundleADR-0454 的一次性目标实例仪式进一步绑定
exact Profile/admission 计划、原始文件摘要、短期审批、selection receipt 与 rollback intent/completion。配置选择只表示 `primary_selected`,不能冒充当前 worker
已经完成 `selected → reconciled → activated`
- 审计只包含 source path/hash、revision、时间和稳定判定。接受审计先于 router 安装;安装后审计失败立即调用 disposer,恢复原 owner。
- edge 不启动 watcher;当前 bootstrap 只在 HTTP worker 启动时读取一次,未来显式 reload 必须复用同一校验和审计边界。
bootstrap 接入不代表 Primary 已默认开放。文件缺失、disabled、rejected 或 `manual` 非 primary 时保持 Legacy,且不加载完整 Runtime stack、不创建 router 或 timer。只有 accepted 且全部 gate 通过的 manifest 才按 startup reconciliation、cancel lifecycle、router 的顺序激活;任一步失败都会撤销 router 并停止 lifecycle。ADR-0007 定义的 completion/log supervisor、固定 edge 基准、部署配置写入与用户可见状态、操作回滚演练仍需再次评审。
bootstrap 接入不代表 Primary 已默认开放。文件缺失、disabled、rejected 或 `manual` 非 primary 时保持 Legacy,且不加载完整 Runtime stack、不创建 router 或 timer。只有 accepted 且全部 gate 通过的 manifest 才按 startup reconciliation、cancel lifecycle、router 的顺序激活;任一步失败都会撤销 router 并停止 lifecycle。ADR-0454 已提供部署配置写入、只读选择状态与操作回滚仪式,但首次真实目标实例执行、运行态 durable activation receipt、固定 edge 基准和 ADR-0007 的完整实机恢复仍需继续评审。
## 8. Legacy 到 Run 的身份映射
@@ -95,6 +95,7 @@ fail-closed 还会改变 Legacy 可用性。
## 后续
正式启用 manual Primary 前,维护者必须在目标 edge/standalone 实例完成一次真实、干净关闭的 manual canary,等待 settling 后运行 terminal audit,组合与同版本
resource report 生成 bundle,再由 v2 loader 重放。固定物理路由、flash 写放大、断电、非干净退出和 config-root 签名/备份仍是独立发布证据;其他 origin 必须分别建立
自己的 admission authority、样本预算和 rollback gate,不能复用 manual receipt。
ADR-0454 已把目标实例的 prepare、observe、resource、qualify、显式短期 approve、只读 audit 与 crash-replay rollback 固化为一次性状态机,并明确
`primary_selected` 不等于运行态 activated。正式启用 manual Primary 前,维护者仍必须在目标 edge/standalone 实例实际执行该仪式并保留 bootstrap activated audit
仓库内 synthetic fixture 或 compiled resource child 不能替代真实产品入口的八/三十二条 admission。固定物理路由、flash 写放大、断电、非干净退出和 config-root
签名/备份仍是独立发布证据;其他 origin 必须分别建立自己的 admission authority、样本预算和 rollback gate,不能复用 manual receipt。
@@ -0,0 +1,90 @@
# ADR-0454:目标实例 Manual Primary Canary 与显式回滚仪式
- 状态:Accepted(仪式实现完成;首次真实用户目标实例执行仍待运维)
- 日期:2026-08-19
- 关联 RFCQL-RFC-0001 D-361、PR-4、PR-5
- 关联 ADRADR-0002、ADR-0449、ADR-0450、ADR-0451、ADR-0453
- AmendsADR-0453 的首次目标实例 canary 操作缺口
## 上下文
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 会留下四类运维缺口:
1. canary 开始前没有不可变计划绑定 Profile、精确样本数和当时的 live rollout 基线;
2. terminal/resource/gate 输出容易经 shell 重定向得到宽权限、部分写入或互相不属于同一 session 的文件;
3. qualification 与写入 live manifest 之间没有显式人工边界,配置选择又容易被误报成“当前进程已经激活”;
4. rollback 没有绑定被替换 manifest 的摘要,也没有 crash-replay intent/completion 链。
Edge 可能是 128 MiB 路由设备,不能为 canary 新增 daemon、watcher、遥测栈或第二数据库;Standalone 可能运行在集群节点上,但本仪式仍只裁决本机
`edge|standalone` Profile,不得借宿主机形态伪装成 `cluster-control|worker` Primary 证据。
## 决策
1. 新增 `qinglong/manual-primary-canary-plan@v1``prepare` 只接受受控 session ID、`edge|standalone`、Edge 精确 8 条或 Standalone 32128 条中由
operator 选定的精确 admission 数;它记录当前 `qinglong3-rollout.json` 为 absent 或 disabled+SHA-256。已有 enabled manifest 时拒绝准备。
2. plan 固定派生全部 basename,不接受调用方提供输出路径。config root 必须是当前 UID 拥有、非 symlink、group/world 不可写的真实目录;所有 artifact 均以
`0600`、同目录临时 inode、file fsync、hard-link no-replace 与 directory fsync 发布。重复调用只接受逐字节相同文件。
3. `prepare` 只输出三项部署环境:实际 Profile、`QL3_SHADOW_ORIGINS=manual` 与唯一 capture basename;它不写 enabled manifest、不启动任务、不重启服务。
operator 必须在隔离窗口中通过既有 Legacy 产品入口精确执行计划数量的 manual admission,并干净关闭同一 worker;任何额外 manual execution 都使样本不相等。
4. `observe` 只有在 capture qualified、单一 manual origin、计数精确且窗口结束至少五分钟后,才以固定参数启动 Node 24 terminal auditor。数据库必须为非 symlink、
group/world 不可写的普通文件;auditor 只读打开 SQLite。调用方不能注入 origin、window、settling、child script 或 shell。
5. `resource` 用固定 `full + require-compiled + 8 samples` 启动 ADR-0451 runner。它使用自身临时 SQLite,不接触生产数据库;低配设备必须在应用停止后运行,不能把
与常驻 workload 争用内存后的失败解释为产品回归。
6. `qualify` 复用 ADR-0453 gate,但额外绑定 plan 文件摘要、三份 source 的原始文件摘要、三份 canonical JSON 摘要、精确 admission target 与 gate 文件摘要。
现有 gate、partial qualification 或 response loss 只能通过原文件重放;source 在 qualification 后被替换时,mutating CLI 与独立 auditor 都失败关闭。
7. `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。
8. 应用重启后,实际运行态仍由现有 bootstrap 的 `selected → reconciled → activated` audit 证明。独立 `audit:manual-primary-canary:ql3` 只读复核 plan、source、gate、
qualification、selection receipt 与 live manifest,可要求 `prepared|qualified|selected|off|rolled-back``off` 只证明 loader 当前关闭,`rolled-back` 还要求本 session 的
intent/completion 摘要链完整。auditor 刻意不提供 `primary_active` 结论。
9. `rollback` 只接受四个固定 reason 与有界 operator。它先 no-replace 发布 intent,绑定当前 enabled manifest SHA-256 和目标 disabled SHA-256,再复核当前摘要并原子替换
live manifest,最后发布 completionintent 或 completion response loss 可用相同参数重放。disabled 已有效但不同于本 session 的目标时拒绝覆盖。
10. 审批过期后,既有 loader 必须立即 fail-closed 为 off;状态/auditor 报 `approvalExpired=true``rolloutMode=off`。operator 仍应执行显式 rollback,把磁盘事实
收敛为 schema v2 disabled manifest,然后重启应用;过期不能被当作自动续期或自动删除 authority。
## 被拒绝的替代方案
### 常驻 watcher 自动检测 capture 并启用 Primary
拒绝。它把一次性证据变成后台控制面,增加路由设备 timer/文件监控成本,并绕过独立人工审批。
### Canary CLI 自动触发八个用户任务
拒绝。工具没有用户会话、Task Policy、脚本内容或副作用 authoritysynthetic spawn 不能证明真实 Legacy 产品入口的 admission capture。
### 用 enabled manifest 存在表示 Primary 已运行
拒绝。manifest 只在下次 bootstrap 被读取;进程可能尚未重启、startup reconciliation 可能失败或审批已经过期。selection 与 runtime activation 必须分开陈述。
### 原地覆盖证据和 rollout 文件以方便重试
拒绝。覆盖会丢失冲突和 crash window。证据采用 no-replacelive rollout 只在摘要复核后原子替换,并由 previous/intent/completion 文件保留恢复链。
## 资源、安全与部署影响
- 正常 QingLong runtime 不新增 import、timer、watcher、listener、数据库连接、schema、migration、package 或生产依赖。全部动作由 operator 一次性调用。
- plan/qualification/selection/rollback 报告不包含数据库路径、命令、Task、Run、Cron、PID、日志、用户输出、错误正文或 Secretstdout 只返回 stage、Profile、样本数和布尔状态。
- `observe` 只读生产 SQLite`resource` 只使用 runner 的临时 SQLite。Edge 应在应用停止后运行 resourceStandalone 也不得与同机生产 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 falseresource 阶段产生 qualified full rollback evidence
enabled/off 进程 peak RSS 分别为 `109,953,024 / 102,383,616` bytes,真实 Legacy child 均 exit 0Shadow 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 操作手册](../operations/ql3-manual-primary-canary.md),并保留 capture、terminal、resource、
gate、qualification、selection、bootstrap activated audit 与 rollback completion。其他 origin 必须建立自己的 admission authority 与 gate;固定物理路由/flash/断电、
运行态 durable activation receipt 和多写者 config authority 仍是独立后续工作。
+1
View File
@@ -457,6 +457,7 @@
| [ADR-0451](./ADR-0451-profile-bounded-legacy-shadow-resource-and-off-rollback-evidence.md) | 按 Profile 有界的 Legacy Shadow 资源与关闭回滚证据 | Accepted |
| [ADR-0452](./ADR-0452-atomic-flattened-backend-build-publication.md) | 原子且扁平兼容的 Backend 构建发布 | Accepted |
| [ADR-0453](./ADR-0453-origin-scoped-legacy-shadow-capture-authority-and-primary-gate.md) | Origin-scoped Legacy Shadow 捕获权威与 Primary 门禁 | Accepted(首次真实目标实例 manual canary 待执行) |
| [ADR-0454](./ADR-0454-target-instance-manual-primary-canary-ceremony.md) | 目标实例 Manual Primary Canary 与显式回滚仪式 | Accepted(首次真实用户目标实例执行待运维) |
## 规则
@@ -0,0 +1,145 @@
# QingLong 3.0 Manual Primary Canary 操作手册
本流程只适用于本机 `edge``standalone` Profile 的 `manual` origin。它不会自动执行用户任务,也不会在 `prepare``observe``resource``qualify` 阶段启用
Primary。`cluster-control``worker` 不适用。
示例使用:
```text
CONFIG_ROOT=/ql/data/config
DATABASE=/ql/data/db/database.sqlite
SESSION=edge-20260819-a
```
把示例中的绝对路径和 session 替换为目标实例的实际值。config root 必须由运行 QingLong 的同一 UID 拥有,不能是 symlink,也不能允许 group/world 写入;数据库必须是
非 symlink、group/world 不可写的普通文件。所有命令都应由该 UID 执行。
## 1. 准备不可变计划
Edge 必须精确 8 条;Standalone 可在 32128 中选择一个精确目标:
```sh
pnpm canary:manual-primary:ql3 -- \
--mode=prepare \
--root=/ql/data/config \
--session=edge-20260819-a \
--profile=edge \
--admissions=8
```
已有 enabled rollout 时命令拒绝执行;已有 disabled rollout 时 plan 绑定其 SHA-256。输出中的 `automaticActivation` 必须为 `false`,并给出三项环境值。将这些值写入目标
部署配置后重启当前 Shadow worker
```text
QL_DEPLOYMENT_PROFILE=edge
QL3_SHADOW_ORIGINS=manual
QL3_SHADOW_CAPTURE_EVIDENCE_FILE=ql3-primary-canary-edge-20260819-a.capture.json
```
不要同时配置其他 Shadow origin,不要手工创建 capture 文件。
## 2. 执行真实 Legacy manual 样本并干净关闭
在隔离维护窗口中,通过现有 QingLong 用户界面/API 的正常 manual 执行入口精确提交计划数量的任务。不要用 canary 工具直接 spawn 脚本;那不会证明产品入口。
窗口期间禁止其他 manual execution。任务全部终态后,使用部署系统的正常 shutdown 停止同一 HTTP worker。只有干净 shutdown 才会 no-replace 写 capture evidencekill -9、断电、
重复文件名或部分文件都不具备资格。
查看当前持久状态不会修改文件:
```sh
pnpm canary:manual-primary:ql3 -- \
--mode=status \
--root=/ql/data/config \
--session=edge-20260819-a
```
## 3. 等待闭合窗口并运行终态审计
从 capture window 的 `endExclusiveMs` 起等待至少五分钟,然后运行:
```sh
pnpm canary:manual-primary:ql3 -- \
--mode=observe \
--root=/ql/data/config \
--session=edge-20260819-a \
--database=/ql/data/db/database.sqlite
```
工具固定使用 `origin=manual`、plan 内的 window 和五分钟 settling,不接受调用方覆盖。SQLite 以只读方式打开;结果必须为 `terminal_observed``assessment=matched`scanned
必须等于计划样本数。
## 4. 在应用停止状态运行资源/回滚证据
低配路由设备必须保持应用停止,避免 128 MiB 预算内与常驻进程争用。命令使用临时 SQLite、compiled backend、full rollback 和固定 8 个 audit samples,不接触生产数据库:
```sh
pnpm canary:manual-primary:ql3 -- \
--mode=resource \
--root=/ql/data/config \
--session=edge-20260819-a
```
结果必须为 `resource_proven``qualified=true`。Standalone 即使部署在集群节点上,也仍是本机证据,不得据此启用 cluster-control/worker Primary。
## 5. 生成资格并独立复核
```sh
pnpm canary:manual-primary:ql3 -- \
--mode=qualify \
--root=/ql/data/config \
--session=edge-20260819-a
pnpm audit:manual-primary-canary:ql3 -- \
--root=/ql/data/config \
--session=edge-20260819-a \
--require=qualified
```
`qualify` 生成 Primary gate 与 qualification,但输出仍必须为 `automaticActivation=false`。独立 audit 重新计算 source/gate/file digest`compatible=true` 只证明可以提交人工审批。
## 6. 显式短期审批并重启验证
只有维护者完成审阅后才执行。示例审批一小时,允许范围为一分钟至 24 小时:
```sh
pnpm canary:manual-primary:ql3 -- \
--mode=approve \
--root=/ql/data/config \
--session=edge-20260819-a \
--approved-by=operator:local-owner \
--approval-ms=3600000
pnpm audit:manual-primary-canary:ql3 -- \
--root=/ql/data/config \
--session=edge-20260819-a \
--require=selected
```
正确状态是 `activation_approved`/`rolloutMode=primary_selected`,不是 `primary_active``requiresRestart=true``runtimeActivationObserved=false`。随后重启应用,并在结构化启动审计中依次确认
同一 revision 的 `selected``reconciled``activated`。缺少任一项都不能宣称运行态 Primary 已激活。
审批过期后 loader 自动 fail-closed 为 off,不会续期。不要修改原 manifest 时间;创建新 session 重新采样。
## 7. 回滚并重启
演练或出现异常时立即执行:
```sh
pnpm canary:manual-primary:ql3 -- \
--mode=rollback \
--root=/ql/data/config \
--session=edge-20260819-a \
--operator=operator:local-owner \
--reason=operator_request
pnpm audit:manual-primary-canary:ql3 -- \
--root=/ql/data/config \
--session=edge-20260819-a \
--require=rolled-back
```
支持的 reason 只有 `operator_request``runtime_failure``gate_rejected``approval_expired`。rollback 先发布 intent,再摘要复核并原子替换 live manifest,最后发布 completion;响应丢失时使用完全相同的参数重跑。
`rolled-back` 比普通 `off` 更严格:后者在初始 disabled 或审批过期时也成立,前者还要求本 session 的 intent/completion 摘要链完整。完成后重启应用,确认 rollout loader 返回
disabled/offLegacy manual 执行继续可用且 Shadow/Primary 不再接管。保留整个 session 的 `0600` 文件和启动审计用于发布复核,不要覆盖或编辑。