feat(ql3): persist manual primary activation

This commit is contained in:
whyour
2026-08-19 05:13:58 +08:00
parent 9981f47851
commit 36035ac43e
15 changed files with 1191 additions and 43 deletions
+20 -7
View File
@@ -11,6 +11,18 @@
最新增量证据(2026-08-19):
- D-362/ADR-0455(已接受;首次真实目标实例执行待运维):manual Primary 默认 bootstrap 在 router 安装后、`activated` 审计前原子发布
`qinglong/manual-primary-runtime-receipt@v1` 当前状态,并在清理前后推进 `active → stopping → stopped`;激活或停止失败收敛为 `failed`。receipt 固定为 config root
内一个 `0600`、8 KiB 上限、有 domain-separated 自摘要的 observed-state projection,绑定 Profile、manifest revision 与原始 SHA-256,但不成为第二 rollout authority。
Linux 以 boot ID、PID、process-group 与 start ticks 联合复验,已有 live identity 时拒绝替换,旧 identity 确定退出后才允许新 generation 接管;非 Linux portable
receipt 可用于开发启动,但独立 auditor 必须返回 unsupported,不能宣称 current。canary auditor 新增 `--require=active`,同时复核 plan/qualification/selection/live manifest、
receipt binding 与进程 current`off|rolled-back` 也会拒绝仍存活的旧 Primary。由此明确了无 watcher 约束:审批过期/rollback 使下一次 bootstrap 为 off,但不会自动卸载已运行
routeroperator 必须停止/重启后再闭合审计。默认关闭路径零新增 I/O/timer/watcher/连接,不新增 package、依赖、schema、migration 或部署对象。
阶段门已重跑:聚焦 `25/25``build:back`、完整 backend `1,487 pass / 0 fail / 2 conditional skip`、18-package clean build/test、四项架构审计与 `14/14`
artifact audit 全部通过;14 档字节与 D-361 一致。隔离 frozen-dependency Linux arm64 Docker 的 128 MiB router/256 MiB Edge release peak 分别为
`87,339,008 / 145,506,304` bytes`memory.events max/oom/oom_kill` 增量均为 0。D-362 不改 PostgreSQL schema/migration、依赖树或 Kubernetes 拓扑,故不重跑
PostgreSQL HA;相邻 D-359 的 `142/142` 与 timeline `1→2` 仅作为既有证据。
- 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` 和唯一
@@ -8332,10 +8344,10 @@ Primary 不使用普通环境变量或宽泛全局开关启用。孵化配置面
- 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 结论
- `approve` 的 durable 结果是 `primary_selected`,不是 `primary_active`。operator 必须重启目标 workerADR-0455 固定 bootstrap 的同 revision
`selected → reconciled → router installed → durable active receipt → activated`,独立 auditor 只有在 receipt binding 与 Linux 联合进程身份均成立时才通过 `--require=active`
- `rollback` 在 live manifest 替换前先写绑定 enabled/disabled 摘要的 intent,替换后再写绑定 intent 摘要的 completion;同参数重放覆盖两个 response-loss 窗口。审批过期按 off
解释但不会自动改写文件,仍需显式 rollback 和重启
解释但不会自动改写文件,也不会让既有无 watcher 进程自动卸载 router,仍需显式 rollback 和停止/重启;`off|rolled-back` 审计拒绝仍 current 的 runtime receipt
实验 manifest 结构固定为:
@@ -8372,10 +8384,11 @@ Primary 不使用普通环境变量或宽泛全局开关启用。孵化配置面
当前 `next` 已在 HTTP worker 接入轻量 manifest bootstrap。文件缺失、disabled、rejected、manual 非 primary、v1 enabled 或 Primary bundle
缺失/篡改/不可重放时不会加载完整 Runtime stack、创建 router 或启动 timer;只有 schema v2、五项 capability gate 完整,且 bundle 经 loader 独立重算为 eligible
的 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 不一致或在
reconciled 审计→启动 completion/timeout/cancel lifecycle→安装 router→原子发布 `active` receipt→记录 activated;任何一步失败都会撤销 router,并按 producer → consumer 顺序停止
lifecycle。HTTP shutdown 与监听失败先写 `stopping`、执行有界清理,再写 `stopped`;异常路径尝试写 `failed`。Linux receipt 绑定 boot/PID/process-group/start ticks,非 Linux
portable receipt 不获得 current 结论。`QL_DEPLOYMENT_PROFILE` 未配置时为 standalone,非法值、Primary gate Profile 不一致或在
cluster-control/worker 中误装本机 SQLite Primary 时 fail closed。目标实例仪式、部署配置写入、只读选择状态和操作回滚工具已由 ADR-0454 固化;首次真实 Edge/Standalone
完整执行、bootstrap activated durable receipt、固定物理 edge/flash/断电 Gate 完成后仍需单独评审。
完整执行、固定物理 edge/flash/断电与多写者配置 authority Gate 完成后仍需单独评审。
## 26. 交付阶段
@@ -9201,7 +9214,7 @@ flowchart LR
| 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;不可变 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-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→durable active receipt 顺序激活,失败撤销,监听失败和 shutdown 以 stopping→有界清理→stopped/failed 失效;receipt 固定为单文件 observed-state projectionLinux 以 boot/PID/process-group/start ticks 复验,独立 auditor 支持 active 且 off/rolled-back 拒绝 live runtimePrimary 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 | 首次真实目标实例完整激活/回滚仪式PostgreSQL CancellationDispatch adaptercluster-control 生产启动拓扑;固定 edge/Linux 多架构与真实磁盘压力基线、完整 2.x API 契约和回滚演练;共享 config 多写者 authority |
| 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 全入口装配;完整回滚演练 |
@@ -5,6 +5,7 @@
- 关联 RFCQL-RFC-0001 D-361、PR-4、PR-5
- 关联 ADRADR-0002、ADR-0449、ADR-0450、ADR-0451、ADR-0453
- AmendsADR-0453 的首次目标实例 canary 操作缺口
- Amended byADR-0455 的 Profile-bounded durable runtime activation receipt
## 上下文
@@ -36,13 +37,12 @@ Edge 可能是 128 MiB 路由设备,不能为 canary 新增 daemon、watcher
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` 结论。
8. 应用重启后,实际运行态 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 结论。
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
10. 审批过期后,loader 对下一次 bootstrap 必须 fail-closed 为 off;状态/auditor 报 `approvalExpired=true``rolloutMode=off`无 watcher 的既有进程不会仅因磁盘
审批过期而自动卸载 router,故 `off` 审计会在 current receipt 仍存活时失败。operator 必须显式 rollback 并停止/重启应用;过期不能被当作自动续期自动删除或已停止证明
## 被拒绝的替代方案
@@ -87,4 +87,4 @@ Edge 可能是 128 MiB 路由设备,不能为 canary 新增 daemon、watcher
维护者仍需在一台真实目标 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 仍是独立后续工作
多写者 config authority 仍是独立后续工作;运行态 durable activation receipt 已由 ADR-0455 补齐,但首次真实目标实例执行仍待运维
@@ -0,0 +1,66 @@
# ADR-0455Profile-bounded Manual Primary 运行态激活凭据
- 状态:Accepted(实现完成;首次真实目标实例执行仍待运维)
- 日期:2026-08-19
- 关联 RFCQL-RFC-0001 D-362、PR-4、PR-5
- 关联 ADRADR-0002、ADR-0453、ADR-0454
- AmendsADR-0454 的运行态 durable activation receipt 缺口
## 上下文
ADR-0454 把 `primary_selected` 与运行态 `activated` 明确分开,但后者仍只存在于进程日志。日志可能没有持久 sink、可能被轮转,也无法在进程退出后区分“曾经激活”与“当前实例仍在运行”。仅记录 PID 又会受到 PID 重用、宿主重启和容器 namespace 变化影响。
Edge 可能只有 128 MiB 内存与低耐久 flash,不能为运行态证明增加 watcher、心跳 timer、数据库表、遥测 sidecar 或无限增长事件日志。Standalone 即使运行在集群节点上,也仍是本机 Profile,不能把宿主形态当成 cluster-control authority。
## 决策
1. 默认 HTTP worker 仅在 accepted schema v2 manifest 精确选择 `manual=primary` 且 Profile 为 `edge|standalone` 时,惰性加载凭据 adapter。disabled、rejected 和非 Primary 路径不 import adapter、不读写凭据。
2. 当前状态固定为 config root 下唯一的 `qinglong3-manual-primary-runtime.json`schema 为 `qinglong/manual-primary-runtime-receipt@v1`。它是 observed-state projection,不是 rollout authority`qinglong3-rollout.json` 仍是唯一期望配置。
3. 凭据只包含随机 activation ID、Profile、manifest revision、manifest 原始 SHA-256、激活/更新时间、`active|stopping|stopped|failed` 状态、进程身份和 domain-separated 自摘要。文件不包含 Task、Run、Cron、命令、路径、用户、日志、Secret 或错误正文。
4. 文件必须位于当前 UID 拥有、非 symlink、group/world 不可写的真实 config root,以 `0600` 临时 inode、file fsync、原子 rename 和 best-effort directory fsync 发布。大小硬上限为 8 KiB;读取使用 `O_NOFOLLOW` 并复验 owner、mode、普通文件、exact shape 与自摘要。
5. Linux 当前性使用 `/proc` 的 boot ID、PID、process-group ID 和 start-time ticks 联合身份,避免 PID 重用。已有 `active|stopping` 凭据只有在该联合身份确定 `exited|identity_mismatch` 后才能由下一实例替换;仍为 `running` 或无法反证时 fail closed。非 Linux 只写 portable PID,允许开发启动,但独立 auditor 必须返回 `unsupported`,不得宣称 current。
6. 激活顺序固定为 reconciliation → 三个 lifecycle → router install → durable `active` → structured `activated` audit。写 `active` 失败时必须立即撤销 router、停止已启动 lifecycle,并保持原激活错误;因此日志中的 `activated` 必然晚于 durable receipt。
7. 干净停止先写 `stopping`,再撤销 router 并按 timeout → cancellation → completion 停止 lifecycle,最后写 `stopped`。任一停止或凭据转换失败时尝试写 `failed`,停止调用仍返回第一个错误;`stopping|stopped|failed` 都不能被审计为 active。重复 stop 共用同一 Promise,不重复释放资源或写状态。
8. 独立 canary auditor 新增 `--require=active`:必须同时复核 plan、qualification、selection、live enabled manifest、receipt binding 和 Linux 联合进程身份。报告分开输出 `runtimeActivationObserved``runtimeActivationCurrent`、receipt state 与 process state,不输出 PID、boot ID 或 activation ID。
9. `--require=off|rolled-back` 现在还要求 `runtimeActivationCurrent=false`。manifest 已回滚或审批已过期但旧 worker 尚未停止时,loader 对下一次 bootstrap 的决策虽为 off,当前内存 router 仍可能继续拥有 manual;auditor 必须拒绝把这种状态表述为已关闭。无 watcher 的部署必须显式停止/重启后再完成 off/rollback 审计。
10. 本凭据不是跨 UID、共享卷或多写者共识锁。同一 UID 可改写 config root,启动前的 read/inspect/write 也不替代部署系统的单实例约束;共享 config、多主机签名或强互斥需要独立 authority,不能由本地 receipt 推断。
## 被拒绝的替代方案
### 用 enabled manifest 表示 active
拒绝。manifest 可能尚未被当前 worker 读取,reconciliation 可能失败,审批可能过期,回滚后旧进程也可能尚未重启。
### 每秒刷新心跳文件
拒绝。它增加永久 timer、写放大和 flash 磨损,仍需处理 suspend、时钟跳变与调度延迟。进程联合身份提供按需审计,不需要周期写盘。
### 每次启动追加一份不可变 receipt
拒绝。无限历史会在路由设备上持续增长,而且仍需另一个 current pointer。单个有摘要的 observed-state projection 足以表达本切片状态;不可变 selection 与 rollback 链继续由 ADR-0454 保存。
### 非 Linux 使用 `kill(pid, 0)` 宣称 current
拒绝。它不能防 PID 重用,也不能绑定宿主 boot。portable receipt 只证明 bootstrap 曾写入,不提供 current 结论。
## 资源、安全与部署影响
- 默认关闭路径零新增 I/O、timer、watcher、listener、连接和数据库操作。
- 激活写一次,干净停止最多再写两次;常驻内存只有一个小 receipt 对象,不随任务数增长。
- 不新增 workspace package、生产依赖、migration、PostgreSQL/Kubernetes 对象或部署端口。
- receipt 是 owner-private 运维证据,不应发布到公开 artifactauditor stdout 只输出低敏状态。
- approval expiry 不会在已运行进程内自动卸载 router。该限制是无 watcher 决策的直接结果,必须通过部署系统的显式 restart/stop 收敛。
## 验证
- 聚焦 `25/25` 覆盖 active→stopping→stopped、摘要篡改、live identity 冲突、stale generation 接管、portable identity 不冒充 Linux current、receipt 写失败撤销 ownership、停止顺序、canary `--require=active` 以及 live runtime 阻断 rolled-back。
- `build:back` 与完整 backend 通过:`1,487 pass / 0 fail / 2 conditional skip`。首次沙箱执行仅有 Vault loopback 因 `listen EPERM` 失败;允许 loopback 后原命令完整重跑为上述结果。
- 18-package clean build/test 退出 0。首次沙箱执行仅有 worker-runtime 三个 TLS/mTLS loopback contract 因相同 `listen EPERM` 失败;允许 loopback 后完整 clean 原命令重跑通过。
- Edge import、cluster dependency、package boundary、service-manager bridge 四项架构审计零 findingpackage boundary 仍为精确 18`singleSourcePackages=[]``shallowSourcePackages=[]`
- `14/14` Local Profile artifact audit 全部通过且字节与 D-361 基线一致:基础 Edge/Standalone `2589998/2590076`、adopted `2809293/2809416`、application `3632877/3632997`、application-api `3800430/3800574`、AI `3069251/3069341`、application+AI `4493151/4493283`、MCP `7315930/7316038`
- 隔离 frozen-dependency Linux arm64 Node 24 Docker 门通过:128 MiB router stress peak `87,339,008` bytes256 MiB Edge release peak `145,506,304` bytes`memory.events max/oom/oom_kill` 增量均为 0;所有 workload 通过。该证据不是物理路由或 flash/断电证明。
- 本 ADR 不修改依赖树、PostgreSQL schema/migration 或 Kubernetes 拓扑,因此 PostgreSQL HA 不因本切片重复执行。
## 后续
仍需在真实 Edge/Standalone 目标实例执行 prepare→真实 manual cohort→qualify→approve→restart→`--require=active`→rollback→restart→`--require=rolled-back` 完整仪式。物理 flash/断电、PID namespace、同 UID 恶意并发、共享配置目录和签名式多写者 authority 继续作为独立 Gate。
+1
View File
@@ -458,6 +458,7 @@
| [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(首次真实用户目标实例执行待运维) |
| [ADR-0455](./ADR-0455-profile-bounded-manual-primary-runtime-activation-receipt.md) | Profile-bounded Manual Primary 运行态激活凭据 | Accepted(首次真实目标实例执行待运维) |
## 规则
+16 -4
View File
@@ -117,9 +117,20 @@ pnpm audit:manual-primary-canary:ql3 -- \
```
正确状态是 `activation_approved`/`rolloutMode=primary_selected`,不是 `primary_active``requiresRestart=true``runtimeActivationObserved=false`。随后重启应用,并在结构化启动审计中依次确认
同一 revision 的 `selected``reconciled``activated`。缺少任一项都不能宣称运行态 Primary 已激活。
同一 revision 的 `selected``reconciled``activated`,再执行:
审批过期后 loader 自动 fail-closed 为 off,不会续期。不要修改原 manifest 时间;创建新 session 重新采样。
```sh
pnpm audit:manual-primary-canary:ql3 -- \
--root=/ql/data/config \
--session=edge-20260819-a \
--require=active
```
只有 `runtimeActivationObserved=true``runtimeActivationCurrent=true``runtimeReceiptState=active``runtimeProcessState=running` 同时成立,才能宣称当前 Linux worker 已激活。
receipt 文件固定为 owner-private `qinglong3-manual-primary-runtime.json`,不要复制到公开 artifact。非 Linux portable receipt 只能证明写入发生过,不能通过 `active` 门。
审批过期后 loader 对下一次 bootstrap 自动 fail-closed 为 off,不会续期;已经运行的 worker 没有 watcher,不会仅凭磁盘过期自动卸载 router。必须停止/重启并通过
`--require=off`,不要修改原 manifest 时间;需要重新启用时创建新 session 重新采样。
## 7. 回滚并重启
@@ -141,5 +152,6 @@ pnpm audit:manual-primary-canary:ql3 -- \
支持的 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` 文件和启动审计用于发布复核,不要覆盖或编辑。
`rolled-back` 比普通 `off` 更严格:后者在初始 disabled 或审批过期时也成立,前者还要求本 session 的 intent/completion 摘要链完整;两者现在都拒绝仍存活的 current
Primary receipt。rollback 写盘后先停止/重启应用,再运行上面的 `--require=rolled-back`,确认 loader 返回 disabled/off、receipt 为 stopped/failed 或旧 Linux identity 已退出,
Legacy manual 执行继续可用且 Primary 不再接管。保留整个 session 的 `0600` 文件和启动审计用于发布复核,不要覆盖或编辑。