qinglong/docs/adr/ADR-0222-generation-bound-plugin-package-automation-publication.md

ADR-0222：按 generation 绑定的 Plugin Package 自动化发布账本

• 状态：Proposed
• 日期：2026-07-29
• 关联 RFC：QL-RFC-0001 D-144、D-145、D-147、D-175、D-207、D-211
• 关联 ADR：ADR-0150、ADR-0151、ADR-0153、ADR-0221

背景

ADR-0150 已把 Package 中的 Workflow 与 Prompt 解析成同一份 immutable materialized revision，但“已经物化”不等于“已经发布给运行时”。如果运行时直接读取 materialized revision，会出现以下问题：

• active generation 切换时，Workflow 与 Prompt 可能分别可见；
• disable/enable 只撤出 Task 与 Tool，自动化定义仍可被新执行消费；
• 集群多副本无法证明读取的是同一 generation、同一 publication head；
• 路由设备若用 watcher、目录扫描或常驻缓存弥补，会增加空闲内存、I/O 和恢复状态。

Secret binding 具有独立授权、密文材料和审计边界，不能与只包含低敏定义的 Workflow/Prompt publication 合并。

决策

1. Workflow 与 Prompt 使用同一 publication

qinglong/plugin-package-automation-publication@v1 一次发布同一 Package generation 中的完整 Workflow 与 Prompt 定义：

• target 精确绑定 Project、Package、installation、lock、generation、 generation digest 与 materialized revision digest；
• definitions 分别按 ID 排序并拒绝重复；
• Workflow 与 Prompt 各最多 128 项；
• canonical publication JSON 最大 12 MiB；
• publication 使用 domain-separated SHA-256 digest。

同一 generation 不拆成 Workflow head 与 Prompt head。消费者只能看到完整 generation 或旧完整 generation，不能看到半批定义。

2. append-only digest chain

每个 (Project, Package) 只有一个 CAS head，历史 publication 永不 update/delete。

• 每个 active Package generation 都必须拥有一条 publication；包含 Workflow/Prompt 时状态为 active，不包含时状态为 absent 且 definitions 为空；
• absent 是 generation tombstone，禁止旧 generation 的自动化 head 跨过一个空 generation 继续可见；
• 首条 publication 固定为 active|absent、version 1、无 predecessor；
• Package generation 升级从任意 current head 追加更高 generation 的 active|absent publication；允许恢复直接跨过已不再 active 的中间 generation， 但 generation 必须严格前进；
• lifecycle disable 追加 active → withdrawn；
• lifecycle enable 追加 withdrawn → active；
• absent 不参与 lifecycle toggle；
• lifecycle successor 必须保留同一 target 与同一 definitions，并绑定 lifecycle event digest；
• version、predecessor digest 与 publishedAtMs 单调递增。

uninstall 只能从 disabled 进入，因此 automation head 已是 withdrawn。v1 不再追加 “retired” publication，保留 withdrawn immutable history；物理回收由独立 retention 协议处理。

3. 双方言 durable repository

SQLite 使用：

• QingLong3PluginPackageAutomationPublications；
• QingLong3PluginPackageAutomationPublicationHeads；
• migration 0079-plugin-package-automation-publications；
• capability local-core@40。

PostgreSQL 使用：

• ql3.plugin_package_automation_publications；
• ql3.plugin_package_automation_publication_heads；
• migration pg-0043-plugin-package-automation-publications；
• publication capability control-core@42；
• runtime-only start guard migration pg-0044-plugin-package-automation-start-guard；
• current capability control-core@43。

publication 表 append-only，head 只允许 CAS 推进。双方言 repository 都支持 findCurrent、findByDigest、publish 与有界 keyset listPendingPage。pending source 只返回“active install 已有 materialized revision，但 automation head 缺失或 generation 不匹配”的 Package。materialized revision fence 不匹配、fork、 JSON/index projection 漂移或缺失 predecessor 均失败关闭。

PostgreSQL runtime、manager 与 package executor 可 SELECT；只有 package executor 可 INSERT publication，并对 head INSERT/UPDATE。没有业务角色取得 DELETE。

4. 生命周期同事务联动

ADR-0221 lifecycle repository 不调用另一个自带事务的 repository。automation repository 提供显式 transaction-bound writer，由 lifecycle 已持有的 SQLite BEGIN IMMEDIATE 或 PostgreSQL SERIALIZABLE transaction 调用。

对 current automation head 为 active|withdrawn 的 Package：

• disable 要求 current automation head 精确匹配 active Package generation 且为 active，然后在 lifecycle event/receipt、Task revision 与 Tool snapshot 的同一事务 追加 withdrawn publication；
• enable 要求同一 generation 的 current head 为 withdrawn，在同一事务追加 active publication；
• uninstall 要求 current head 已 withdrawn，不创建新的定义版本；
• 第二次 authorization fence 失败、外键失败、head CAS 失败或任一 capability 写失败 时，整笔事务回滚。

absent tombstone 没有可撤出的定义，因此 lifecycle transaction 不为其追加空 toggle； 消费者仍以 Package lifecycle/quarantine authority 作为外层准入围栏。

publication 的 lifecycle event 外键要求 lifecycle event 先在事务中插入，再写 publication，最后才允许 COMMIT。这个顺序不改变原子可见性。

5. Profile 与资源边界

• 不新增 workspace package；
• 不新增 daemon、timer、watcher、listener、socket 或常驻缓存；
• Edge/Standalone 复用单 SQLite operation authority；
• Cluster 复用 caller-driven package executor 与单连接 transaction；
• 禁用 AI 的 Profile 不因该账本引入 AI provider、SDK 或 credential；
• Secret material、SecretRef、Prompt 渲染输入与模型输出均不得进入 publication。

6. caller-driven publication 与恢复顺序

initial/next publication 已由 profile-neutral coordinator 发布，并在双方言启动链路中 固定为：

install recovery → Task materialize/reconcile → Workflow/Prompt publication → Tool snapshot → admission

• coordinator 在发布前后各观察一次 active generation；换代返回 superseded，不把 旧 generation 冒充 current；
• 同 generation exact replay 返回 existing，并保留 lifecycle 已写入的 withdrawn 状态；
• conflict/invalid 进入 manual_required，availability 失败进入 retry；
• 每页和每轮硬上限均为 64；Local Edge/Standalone 无显式配置时使用 8×8；
• 不创建 resident reconciler，Local 复用一个 SQLite operation authority，Cluster 复用 caller-driven package-executor Job。

7. 安全事实优先的启动门

publication head 只表达 generation 与正常 lifecycle，不把 quarantine 或 publisher revocation 重写成虚假的 withdrawn。启动必须通过独立、精确的 PluginPackageAutomationPublicationStartGuard：

• 输入固定为 Project、Package 与 current publication digest；旧 digest、非 active publication、非 current active install、non-active lifecycle 一律返回 false；
• SQLite 在同一 operation authority 内同时检查 current publication/install、 lifecycle 与精确 installation/lock quarantine event；
• PostgreSQL 只向 ql3_runtime 暴露 SECURITY DEFINER plugin_package_automation_start_allowed，runtime 不取得 quarantine、provenance 或 revocation 表的直接读取权；
• PostgreSQL guard 与 publisher revocation 使用同一 transaction-level signer advisory lock。若启动观察先完成，它发生在撤销提交之前；若撤销先取得锁，启动等待 后必定观察到 receipt 并返回 false；
• pending-source 与 publication writer 同样排除 security-fenced generation，避免 recovery 在隔离或撤销后重新发布能力；
• 不新增 safety-state 镜像表、daemon、timer、watcher 或常驻 denylist。quarantine event 与 publisher revocation receipt 始终是事实源。

调用方必须在“记录一次自动化启动”的同一数据库事务内消费 PostgreSQL guard；把一次 boolean 查询缓存后再异步启动仍属于 TOCTOU，不能视为生产执行门已经关闭。

8. 尚未关闭的产品门

本 ADR 已关闭 durable publication、lifecycle overlay、双方言 quarantine 启动收敛， 以及双方言 publisher revocation 的即时启动收敛：Local 由文件型不可变撤销 receipt 桥接到 SQLite 精确 installation/lock quarantine，Cluster 由 PostgreSQL receipt 直接参与启动判定。但不把定义解释为可执行能力。D-211 继续 Proposed， 直到至少完成：

1. Workflow Run/StepRun executor 与 admission fence；
2. Prompt 产品入口、参数绑定、Policy/Audit 与内容治理；
3. Secret binding consumer。

在这些门关闭前，消费者必须同时检查 Package lifecycle/quarantine authority，不能只因 automation head 为 active 就执行。

不采用方案

直接读取 materialized revision

拒绝。materialization 是 immutable source fact，不是运行时 publication head。

Workflow 与 Prompt 分别发布

拒绝。会引入同 generation 部分可见和双 head 恢复协议。

把 Secret binding 放入 publication

拒绝。低敏定义发布不能取得 Secret 授权和密文材料 authority。

生命周期提交后异步撤出 automation

拒绝。崩溃窗口会留下 Task/Tool 已撤出但 Workflow/Prompt 仍 active。

新建 automation workspace package 或 watcher

拒绝。现有 runtime-core 与双方言 storage subpath 足够，额外部署边界没有独立价值， 并会增加路由设备供应链和空闲资源。文件数量不是 package 边界；本能力没有独立部署、 权限域、重依赖或发布责任，因此即使代码增长也继续使用现有 package 的显式 subpath。

当前验证

1. runtime-core publication/coordinator 定向 9/9，通过 canonical digest、跨 generation successor、absent tombstone、lifecycle withdraw/restore、并发换代 与有界 recovery 分类；
2. SQLite repository 定向 8/8，覆盖 exact current start guard、quarantine 后 pending-source 收敛、publication 拒绝、跨 generation absent tombstone 与损坏 失败关闭；
3. SQLite lifecycle 定向测试证明第二次 authorization 检查失败时，Task、Tool snapshot、lifecycle facts 与 automation head 全部回滚；
4. Local application startup 固定执行 Task→automation→Tool，定向启动回归 14/14； SQLite runtime 只在调用时惰性加载 publication repository；
5. PostgreSQL 18.4 arm64 HA fixture 中，同一 Package publication 从 v1 经四次 disable/enable 原子推进到 v5，包含 1 Workflow 与 1 Prompt；5 条 publication 和 active head 经 remote_apply、timeline 1→2 promotion、旧主 fencing、 pg_rewind 及 fresh control replicas 后保持一致；
6. PostgreSQL pg-0044 把 control-core 推进至 v43；start function 只授予 runtime， package executor/admin/manager/worker ingress 均无执行权；迁移、checksum、 schema/readiness 与 repository 定向 43/43；
7. HA gates pluginPackageAutomationPublicationTransitionsAtomically=true、 pluginPackageAutomationPublicationSurvivesPromotion=true、 pluginPackageAutomationRecoverySourceConverges=true、 pluginPackagePublisherRevocationImmediatelyFencesAutomation=true、 pluginPackageAutomationSecurityFenceSurvivesPromotion=true、 pluginPackageAutomationStartGuardIsRuntimeOnly=true 且总 gates.passed=true；撤销前 current publication 允许，revocation receipt 提交后、 quarantine 后和 promotion 后均拒绝；
8. 调度器 COMMIT-response-loss 同轮修复为“发送 COMMIT 后绝不透明重试”，回归 7/7， HA 证明只产生 1 Run、1 Attempt、2 Event、0 duplicate occurrence。
9. Cluster caller-driven recovery 已把 automation publication 放在 Task publication 与 Tool snapshot 之间；Cluster PostgreSQL 全量 211 pass/1 条无 DSN 条件 skip， 最新 HA 总 gates.passed=true，且未访问 registry、未拉取镜像。
10. Local 签名 catalog 已覆盖 active install → materialized Task/Workflow/Prompt → active automation 的完整链路；撤销 publisher key 后，不可变 receipt callback 以精确 installation/lock provenance 写入 SQLite withdrawn quarantine，raw automation publication 仍保持原 generation/lifecycle 事实，但 exact start guard 立即返回 false。测试在 quarantine 与 snapshot 已 durable、文件型 trust current generation 尚未 promotion 的边界注入崩溃，观察到 current generation 3、 pending generation 4、recoveryRequired=true 且启动已拒绝；重放同一命令收敛为 generation 4，随后为 existing，SQLite 始终只有 1 条精确 quarantine event。