qinglong/docs/adr/ADR-0186-cluster-postgresql-plugin-package-quarantine.md

ADR-0186：Cluster PostgreSQL Plugin Package 隔离与能力撤出

• 状态：Accepted
• 日期：2026-07-28
• 关联：RFC D-137、D-149、D-152、D-154、D-158、D-174、D-175、D-176； ADR-0125、ADR-0137、ADR-0152、ADR-0154、ADR-0158、ADR-0184、ADR-0185

背景

D-174 已为 Edge/Standalone 建立 SQLite quarantine overlay，但 Cluster 仍只有 Package 安装、物化、Task reconciliation 与 Tool snapshot 的 PostgreSQL事实。若 Cluster 只在 某个 control replica 内保存 denylist，重启、水平扩容或主备提升都会重新暴露受影响 能力；若只改变 install state，则已发布的 Task revision 和历史 Tool snapshot 仍能被 新的 Run/StepRun 引用。

隔离必须同时满足：

• event、Task disable、Tool source withdrawal 和 receipt 原子提交；
• 多副本、COMMIT 响应丢失、同步复制与主备提升后语义不变；
• runtime 只能获得启动判定，不能读取隔离证据；
• 已经 durable running 的工作保留 completion/recovery，不伪装成安全热杀；
• 不为这一个领域再拆 workspace package，也不把 Cluster 代码带入路由设备 Profile。

决策

1. control-core v36 使用永久 overlay

pg-0037-plugin-package-quarantine 将 capability 从 v35 推进到 v36，并新增：

• plugin_package_quarantine_events：绑定 revocation receipt、impact、精确 install record、双人或 break-glass 主体、reason、mutation 和事件时间；
• plugin_package_withdrawal_receipts：绑定目标、前后 active vector、新 Tool snapshot、Task 撤回数量和数据库提交时间；
• plugin_package_withdrawal_tasks：绑定每个 Task 的前一 revision 与 disabled revision。

事实表只追加，不删除或改写安装历史、旧 Task revision、旧 Tool snapshot、Run、 StepRun、Artifact 与 Completion。

2. package-executor 持有唯一提交 authority

commit_plugin_package_quarantine(jsonb,jsonb,jsonb,jsonb) 是 SECURITY DEFINER，只授予 ql3_package_executor：

1. 锁定 Project 和 exact install；
2. 校验 event/receipt target、时间关系、active head 与 materialized revision；
3. 对 Package 当前拥有且仍 enabled 的 Task 追加 disabled revision；
4. 重新计算并校验排除目标 lock 后的完整 active source 集；
5. 发布 immutable Tool snapshot；
6. 写 event、receipt 和 Task withdrawal relation。

任一 identity、source、Task head、snapshot 或 authorization fence 漂移都回滚整个 事务。event digest 与 target 唯一；COMMIT 响应丢失后通过 durable read-after-write 收敛为 exact replay。

3. runtime 只获得同 Project 启动栅栏

ql3_runtime 对三张隔离表没有 SELECT/INSERT/UPDATE/DELETE，只能执行：

• plugin_package_run_start_allowed(project,task,revision)；
• plugin_package_tool_start_allowed(project,definitionRef,digest)。

guard 通过 Task reconciliation 或历史 Tool snapshot source 回溯 Package lock，并对 Project 取 FOR SHARE；quarantine commit 对同一 Project 取 FOR UPDATE。因此新 Run dispatch 与 Tool barrier 不可能越过并发隔离事务。同步副本缺失且 synchronous_commit=remote_apply 时，行锁 WAL 会使启动型 mutation fail closed； 不得为提高切换窗口可用性绕过该 fence。

Run 已经 durable 处于 dispatching/running 且 Task revision 未变化时，不重新解释为 新 start，允许既有 completion/recovery 收敛。Package install recovery、Task reconciliation recovery 和 Tool snapshot recovery 都排除已有 quarantine event 的 target/source，避免重启复活。

4. 管理入口是短生命周期 subpath

@qinglong/cluster-admin/plugin-package-quarantine 组合 readiness、PostgreSQL repository 和事务内授权复验：

• 每批 1–128 个 dense、event digest/target 唯一的 event；
• 每个 repository transaction 在写入前和 COMMIT 前调用授权复验；
• 使用独立 package-executor credential，完成后关闭数据库；
• 不进入 cluster-admin root，不新增常驻 HTTP route、listener、timer 或 workspace package。

它接收的是已经绑定 revocationReceiptDigest + impactDigest + exact lock 的事件。 Cluster 当前安装事实没有保存 OCI publisher signature provenance，因此本 ADR 不允许 从 revoked key、package 名或 registry 路径猜测受影响 lock。自动影响分析与事件生产 必须先在后续 D-177 建立不可变 signer provenance。

不采用方案

新增 quarantine workspace package

该能力与现有 cluster-postgres storage adapter、cluster-admin 短 authority 同生命周期， 新增包没有独立交付或依赖隔离收益，并违反 22-package hard cap。

给 runtime 隔离表读取权限

runtime 只需要布尔启动判定。直接 SELECT 会暴露管理主体、reason、impact 与安装历史， 也会让各消费者自行实现不一致 join。

跨多个事务撤出 Task 和 Tool

会出现 Task 已禁用而 Tool 仍可启动、或 event 已存在但 receipt 不完整的可见窗口， 并使 recovery 无法判断 winner。

在没有 provenance 时自动按 key 隔离

无法证明某个 install lock 确由该 signer 发布；猜测影响集会产生漏隔离或误隔离， 比显式承认缺口更危险。

验收证据

• @qinglong/cluster-postgres：190 pass，1 条需要外部 live URL 的 integration 条件 skip；migration checksum、schema contract、Drizzle、readiness、恢复与 barrier 单元门通过；
• @qinglong/cluster-admin：101 pass，1 条真实 Kubernetes API 条件 skip；新增 batch service 覆盖双次授权、dense/limit/duplicate target 和显式 subpath；
• PostgreSQL 18.4 Debian arm64 physical-streaming HA Docker contract：
  • 构造一个真实 Task+Tool Package，隔离前 Run/Tool guard 均为 true；
  • COMMIT 响应丢失后 durable replay 收敛，event/receipt 各 1、Task withdrawal 2；
  • 新 Tool snapshot retained source 为 0，runtime 隔离表访问返回 42501；
  • 隔离后及 timeline 1→2 promotion、pg_rewind、同步 rejoin 后双 guard 均为 false；
  • 分区提交未被确认、旧主先 fence、同步副本恢复后才重新开放 mutation；
  • 最终 pluginPackageQuarantine.* 证据全为 true，gates.passed=true。

真库门发现并修复了 JSON 运算符优先级、active install/head join、JSON text 到 UUID 显式转换和 ECONNRESET durable retry 四类静态 mock 未覆盖的问题。

后续

1. D-177/ADR-0187 已完成 Cluster Package signer provenance、durable revocation receipt/impact、receipt-first Run/Tool deny 与有界 quarantine producer；
2. 将 ADR-0187 producer 接入正式双人/break-glass Cluster 管理 transport；在该 ceremony 完成前保持 subpath 为内部短 authority，不发布“任意请求按 key 隔离”的 产品能力；
3. 为多 Project 批次补充显式并发/限流策略，但单事务仍只处理一个 Project target， 不扩大数据库锁范围。