ADR-0455：Profile-bounded Manual Primary 运行态激活凭据

状态：Accepted（实现完成；首次真实目标实例执行仍待运维）
日期：2026-08-19
关联 RFC：QL-RFC-0001 D-362、PR-4、PR-5
关联 ADR：ADR-0002、ADR-0453、ADR-0454
Amends：ADR-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。

决策

默认 HTTP worker 仅在 accepted schema v2 manifest 精确选择 manual=primary 且 Profile 为 edge|standalone 时，惰性加载凭据 adapter。disabled、rejected 和非 Primary 路径不 import adapter、不读写凭据。
当前状态固定为 config root 下唯一的 qinglong3-manual-primary-runtime.json，schema 为 qinglong/manual-primary-runtime-receipt@v1。它是 observed-state projection，不是 rollout authority；qinglong3-rollout.json 仍是唯一期望配置。
凭据只包含随机 activation ID、Profile、manifest revision、manifest 原始 SHA-256、激活/更新时间、active|stopping|stopped|failed 状态、进程身份和 domain-separated 自摘要。文件不包含 Task、Run、Cron、命令、路径、用户、日志、Secret 或错误正文。
文件必须位于当前 UID 拥有、非 symlink、group/world 不可写的真实 config root，以 0600 临时 inode、file fsync、原子 rename 和 best-effort directory fsync 发布。大小硬上限为 8 KiB；读取使用 O_NOFOLLOW 并复验 owner、mode、普通文件、exact shape 与自摘要。
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。
激活顺序固定为 reconciliation → 三个 lifecycle → router install → durable active → structured activated audit。写 active 失败时必须立即撤销 router、停止已启动 lifecycle，并保持原激活错误；因此日志中的 activated 必然晚于 durable receipt。
干净停止先写 stopping，再撤销 router 并按 timeout → cancellation → completion 停止 lifecycle，最后写 stopped。任一停止或凭据转换失败时尝试写 failed，停止调用仍返回第一个错误；stopping|stopped|failed 都不能被审计为 active。重复 stop 共用同一 Promise，不重复释放资源或写状态。
独立 canary auditor 新增 --require=active：必须同时复核 plan、qualification、selection、live enabled manifest、receipt binding 和 Linux 联合进程身份。报告分开输出 runtimeActivationObserved、runtimeActivationCurrent、receipt state 与 process state，不输出 PID、boot ID 或 activation ID。
--require=off|rolled-back 现在还要求 runtimeActivationCurrent=false。manifest 已回滚或审批已过期但旧 worker 尚未停止时，loader 对下一次 bootstrap 的决策虽为 off，当前内存 router 仍可能继续拥有 manual；auditor 必须拒绝把这种状态表述为已关闭。无 watcher 的部署必须显式停止/重启后再完成 off/rollback 审计。
本凭据不是跨 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 运维证据，不应发布到公开 artifact；auditor 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 四项架构审计零 finding；package 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 bytes，256 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。

7.6 KiB Raw Blame History Unescape Escape