qinglong/docs/adr/ADR-0221-atomic-plugin-package-lifecycle-overlay.md

ADR-0221：原子、可重放的 Plugin Package 生命周期 Overlay

• 状态：Proposed
• 日期：2026-07-29
• 关联 RFC：QL-RFC-0001 D-140、D-141、D-142、D-174、D-175、D-207、 D-210、D-211
• 关联 ADR：ADR-0140、ADR-0142、ADR-0143、ADR-0144、ADR-0184、 ADR-0186、ADR-0217、ADR-0220、ADR-0222

背景

QingLong 3.0 已经能安装、升级、回滚和安全隔离 Plugin Package，但安装状态机只描述 制品如何进入可用状态，publisher quarantine 则描述强制安全撤回。正常运维仍缺少三个 不同语义：

• 暂停一个正常 Package，保留随后恢复的可能；
• 恢复同一份、未被替换且仍可信的 Package；
• 在保留历史的前提下逻辑卸载 Package。

直接修改 install state 会混淆部署执行与运维意图；复用 quarantine 会伪造安全事件； 删除 install/head/history 会破坏审计、回滚和 durable execution recovery。Task 与 Tool 分两次撤出还会暴露“Task 已停、Tool 仍可启动”或相反的部分状态。

该能力同时需要覆盖资源很小的路由设备和 PostgreSQL 集群。实现不能为每个概念增加 package、后台 daemon、timer、watcher 或缓存，也不能把 Cluster 依赖带入 Edge。

决策

1. 独立 append-only lifecycle overlay

生命周期不改写 Plugin Package install record。每次 disable|enable|uninstall 追加：

1. canonical lifecycle event；
2. (Project, Package) current lifecycle head；
3. capability publication receipt；
4. 本次实际变更的 Package-owned Task transition evidence。

head disposition 只有 active|disabled|uninstalled。没有 head 表示当前安装仍按原 activation 语义为 active；head 必须精确绑定 installation、lock 和 install record digest。新的 installation 或 lock 不能继承旧 head。

event 同时绑定 mutation、Approved Action dispatch、action/impact digest、请求人与批准 人、expected lifecycle version 和完整 reference graph digest。相同 event 精确重放； mutation、dispatch、target 或预览漂移一律冲突。

2. 影响计划是批准对象，不是执行时提示

plan 在同一一致性数据库视图中重新计算：

• current install 与 materialized resource generation；
• current lifecycle head；
• current Project Tool snapshot；
• Package-owned Task；
• blocking Run/recovery reference；
• durable consumer 数量与 canonical reference graph digest。

批准绑定完整 impact digest。执行事务必须重新计算并与批准值完全一致，不能只验证 Package name。当前已落地 consumer 是 Task ownership、Project Tool snapshot 与 generation-bound Workflow/Prompt automation publication。Secret binding 尚无 durable consumer，因此 contract 保留计数、blocking reference 与全图 digest 扩展点； 未来增加 consumer 时旧执行器必须失败关闭，不能把未知引用当作零。

3. 三种 transition

disable：

• 只接受 active；
• 为当前仍 enabled 的 Package-owned Task 追加 disabled revision；
• 发布排除该 source 的 Project Tool snapshot；
• 对包含 Workflow/Prompt 的 Package 追加 active→withdrawn publication；
• 原子写 event/head/receipt/Task evidence/Tool snapshot/automation publication。

enable：

• 只接受同一 current installation 的 disabled；
• 重新验证 quarantine、publisher trust/revocation、materialized generation、Project Policy 与 active source 上限；
• 只恢复前一 disable receipt 中由生命周期实际关闭的 Task；
• 发布重新包含该 source 的 Tool snapshot；
• 对包含 Workflow/Prompt 的 Package 追加 withdrawn→active publication。

uninstall：

• 只接受 disabled；
• live Run、未收敛 recovery 或任何 durable consumer reference 都是 blocker；
• 只把 lifecycle head 推进到 uninstalled，不删除 install、proposal、approval、 execution、event、snapshot 或 audit 历史；
• OCI、offline bundle、staging 和本地缓存字节由后续独立 retention receipt 回收。

4. 新启动拒绝，已 durable 执行继续收敛

生命周期 transition 与能力 publication 在同一数据库写事务完成。事务提交后：

• Run 从 queued 推进到 dispatching/running 时，若其精确 Task revision 属于 non-active lifecycle head，立即拒绝；
• Tool start barrier 若命中同一 installation/lock 的历史 Tool definition，且 head non-active，立即拒绝；
• 已经 durable running 的 Attempt/StepRun 仍按原 revision 完成、取消或恢复，不由 disable 热杀。

enable 把同一 head 恢复为 active 后，精确历史 revision 可再次通过 start fence； Task current head 和 Tool current snapshot 仍由 lifecycle transition 发布的新版本决定。

SQLite 在唯一 BEGIN IMMEDIATE authority 内执行 transition，Run/Tool 围栏复用同一 连接和事务；PostgreSQL 使用 SERIALIZABLE repository 及 SECURITY DEFINER commit_plugin_package_lifecycle(jsonb, jsonb, jsonb, jsonb) 完成 server-side CAS。只有 ql3_package_executor 可执行该函数并只读 lifecycle ledger； runtime、admin、package manager 和 worker ingress 既不能执行函数，也不能直接写表。

5. Profile 和部署边界

• Local 固定当前 Owner human_confirmation；
• Cluster 固定 separation-of-duty，由 package manager 管理 proposal/approval，由 caller-driven package executor 执行；
• Edge 单命令只处理一个 Package，active source 上限 4；
• Standalone 单命令最多 4 个，active source 上限 16；
• Cluster 一批最多 16 个；
• 复用现有 20 个 workspace package 的显式 subpath，不新增 package、进程、端口、 timer、watcher、listener 或常驻 cache。

PostgreSQL lifecycle repository 只从 @qinglong/cluster-postgres/package-executor 和显式 @qinglong/cluster-postgres/plugin-package-lifecycle 暴露；根入口、runtime、admin、 package manager、worker ingress 不取得 mutation authority。

Cluster review 使用短生命周期、append-only 的 durable plan： ql3_package_executor 重算完整 impact 后只能 INSERT，ql3_package_manager 只能 SELECT 并据此创建 separation-of-duty Approval。executor 在消费审批前再次重算并做 exact compare；manager HTTP 不暴露 consume/execute，也不取得 lifecycle commit 权限。 plan JSON 的运行时和数据库硬上限均为 96 KiB，最长存活 15 分钟。

6. 恢复与失败语义

COMMIT response loss 通过 event digest、mutation、dispatch、target version 和 receipt 关系精确重放。SQLite readiness 与 PostgreSQL schema readiness 都复核 event/head/ receipt/Task relation；缺行、JSON/digest 漂移、Task evidence 不完整或 head CAS 丢失均 失败关闭。

隔离优先于正常恢复：存在 matching quarantine 或 publisher revocation 时，enable 拒绝。生命周期不能清除、覆盖或绕过安全隔离事实。

不采用方案

扩展 install state

拒绝。安装执行阶段和用户运维意图具有不同版本、恢复和审计语义。

把 disable 实现为 quarantine

拒绝。正常停用不是 publisher compromise，且 quarantine 不能被普通 enable 撤销。

直接删除 current head 或历史

拒绝。会破坏 rollback、durable completion、审计与 COMMIT response-loss 恢复。

Task、Tool 分事务撤出

拒绝。任一崩溃窗口都会留下部分可见能力。

uninstall 同步删除制品

拒绝。大文件删除和数据库逻辑退役不是同一原子域，会扩大路由设备写锁、闪存和恢复 成本。

新建 lifecycle package 或后台 reconciler

拒绝。现有 runtime-core/local-sqlite/cluster-postgres 权限与 Profile subpath 足以承载， 另建 package/daemon 违反 D-175/D-207，并增加低配设备供应链与空闲资源。

影响

• workspace 保持 20 个 package；
• SQLite capability 由 lifecycle v39 推进至 automation publication v40； PostgreSQL control-core 由 lifecycle plan v41 推进至 automation publication v42；
• D-210 inventory v1 不静默扩展 availability enum，后续用显式新响应 schema 返回 lifecycle disposition；
• disable 不热杀已 durable execution，运维界面必须明确“停止新启动、等待已有执行 收敛”；
• Workflow/Prompt durable publication、absent generation tombstone 与 caller-driven startup recovery 已实现；实际 Workflow/Prompt execution、Prompt 产品入口、Secret binding 与 quarantine 收敛未实现前，D-211 不能标记 Accepted。

当前验证

1. runtime-core lifecycle contract、digest、reference graph、event/receipt/head 与 replay 测试通过；
2. SQLite 0077/0078、Drizzle schema、readiness、repository 和 exact replay 已实现； lifecycle repository 5/5，Run/Tool lifecycle/quarantine 定向 18/18，相关 SQLite 回归 37 项通过；另一个 Run contract suite仅因本地缺 ts-node/register/transpile-only 未启动；
3. Run transaction GitNexus 影响为 MEDIUM（12 direct、29 total），Tool start barrier 为 LOW（2 direct、20 total）；改动只增加 non-active guard；
4. PostgreSQL pg-0041、schema contract/readiness、Drizzle schema、repository 和 package-executor 受限出口已实现；impact planner 不直接读取 runs，而经 SECURITY DEFINER plugin_package_lifecycle_blocking_runs 做 Project/Package 作用域和 129 条硬上限查询；commit 复用 lock_active_plugin_package_project，不向 package executor 扩大 Project/Run 表权限；迁移/权限契约 37/37；
5. 空 PostgreSQL 18 容器按真实六角色边界重放 41/41 migrations，最终 capability 为 40；函数 owner 为 ql3_migration 且为 SECURITY DEFINER，只有 ql3_package_executor 有 lifecycle commit/有界 Run 查询 EXECUTE，业务角色均无 lifecycle 表写权限，package executor 也没有 runs 表 SELECT；
6. 正式 PostgreSQL 18 physical-streaming HA 门已通过：remote_apply、主备提升、 旧主 fencing、pg_rewind 回归、disable COMMIT-response-loss 恰好一次收敛、 exact replay、separation-of-duty、Run/Tool 原子拒绝与 enable 恢复均为 true； 2 event、2 receipt、4 Task transition 和 lifecycle v2 active head 经 WAL、 promotion 与重新连接后保持一致；
7. 本次真实门禁额外发现并修复了 package executor 直接读取 Run/Project 的越权路径 及 PL/pgSQL previous_task 变量/别名冲突；pg-0041 冻结 checksum 更新为 99669c63c891124aa0741586d5e92bd40d7a3ddf322ec7da970790958f554101；
8. Local 产品入口已复用现有 local-admin/package-lifecycle 与 local-owner-cli/package-command：plugin-package.lifecycle.plan 先返回完整 canonical impact 和低敏摘要，plugin-package.lifecycle.execute 再以私有命令文件 携带该 impact 与稳定审批 identity，固定当前 Owner human_confirmation，串行完成 request/decision/consume/transition。任何部分完成均从 durable Approval/dispatch 继续，event 时间固定为 dispatch 创建时间，响应丢失重跑得到同一 receipt；不新增 workspace package、连接、进程或后台循环。本机 lifecycle service 定向 2/2、 local-admin 81/81、既有 ql3-package 回归 2/2；
9. Cluster 已在现有 cluster-admin/cluster-postgres package 内完成 caller-driven vertical：pg-0042-plugin-package-lifecycle-plans、capability v41、manager SELECT-only/executor SELECT+INSERT、management service、公开 lifecycle.propose|decide|inspect transport、精确客户端响应校验，以及仅由受信 caller 调用的 plan/execute executor；没有新增 package、daemon、timer 或端口。 plan 最大 96 KiB/15 分钟，pg0042 冻结 checksum 为 a242067854f4ee5231c75874fa77dda364da962a2dcaf570b5015ee069818c4b。 transport 11/11、客户端 TLS 6/6、PostgreSQL 迁移/权限 30/30 通过；
10. 正式 PostgreSQL 18.4 arm64 HA 重跑新增两轮 executor plan → manager proposer → distinct reviewer → executor re-plan/consume/ transition，disable 后再 enable。2 条 durable plan、lifecycle v4 active head、 receipt 与 plan 在 remote_apply、timeline 1→2、旧主 fencing、 pg_rewind 只读同步重入后精确保留，新增 gate pluginPackageLifecycleManagedPlanReviewExecutesExactly=true，总 gates.passed=true。依赖从本机受审 Cluster Admin 镜像离线复用，未访问 registry；
11. Local SQLite 已完成真实子进程 lifecycle crash matrix： disable|enable × edge|standalone × 8 个事务窗口共 32/32 通过。窗口依次位于 Task revision、Tool snapshot、lifecycle event/receipt/task/head 之后及 COMMIT 前/后；28 个 COMMIT 前 SIGKILL 均保持原 Task、snapshot 和 ledger/head 零部分写，重放返回 created，4 个 COMMIT 后 SIGKILL 均完整 durable 且重放 返回 existing。Edge 使用 DELETE/FULL，Standalone 使用 WAL/FULL，全部 integrity_check、foreign-key check、readiness 与 exactly-once relation 通过；
12. Cluster 管理进程已在同一正式 PostgreSQL 18.4 arm64 HA 门完成 disable|enable × plan|propose|decide|execute 共 8 个真实 Node SIGKILL 窗口：每个阶段先提交 durable fact、fsync 低敏 marker 后被杀，再由全新进程以稳定 identity 重放，8 次均返回 existing。该门发现并修复两处实际恢复顺序缺陷： plan runner 现在先按 actionRef 恢复并严格核对 action/Project/Package/requester/ lifetime；execution runner 现在先从 exact dispatch 重建 event 并检查 durable receipt，只有 receipt 不存在时才 re-plan。新增 gate pluginPackageLifecycleManagementProcessCrashesConvergeExactlyOnce=true， 8 个窗口及其 plan/receipt/head 经 remote_apply、timeline 1→2、旧主 fencing、 pg_rewind 只读同步重入后仍一致，总 gates.passed=true；
13. ADR-0222 已完成 Workflow/Prompt generation-bound durable publication： SQLite 0079/0080 与 capability v40，PostgreSQL pg-0043 与 control-core v42； append-only publication/head、exact replay、materialized/lifecycle/head readiness、双方言 transaction-bound writer、absent tombstone 与有界 keyset pending-source 已实现；
14. Local 生命周期授权失败回滚测试与完整 local-sqlite 165/165 通过；正式 PostgreSQL 18.4 arm64 HA 中 publication 从 v1 经四次 lifecycle transition 原子推进到 v5，1 Workflow + 1 Prompt 经 remote_apply、promotion、fencing、 pg_rewind 和 fresh control replicas 后保持一致，两个 automation gate 与总 passed 均为 true；
15. caller-driven publication coordinator 已接入 Local/Cluster startup，顺序固定为 Task publication → automation publication → Tool snapshot → admission；Local 启动定向 14/14、Cluster 定向 11/11。实际 Workflow/Prompt execution、Prompt 产品入口、Secret binding 以及 quarantine 下的 automation 收敛仍未完成，因此 本 ADR 保持 Proposed。本次离线 HA 成功不代表 registry 安装门已完成。
16. 最终离线复验完成 20 个 workspace package 的干净构建与全量测试，零失败； SQLite current contract v40 已同步 Compose image label、preflight、rollout、 evidence、OCI 与 physical Edge 审计。PostgreSQL 18.4 arm64 physical HA 在跳过 image pull 的条件下再次通过，新增 pluginPackageAutomationRecoverySourceConverges=true，总 gates.passed=true。