feat(ql3): atomically withdraw quarantined automation

2026-09-20 16:07:11 +08:00 · 2026-08-13 03:42:38 +08:00
parent a6ad636251
commit 4c2a0b6adf
39 changed files with 983 additions and 264 deletions
@@ -24,6 +24,8 @@
  `10001:10001`、network none、read-only root、drop ALL、128 MiB/32 PIDs 下完成本地 TLS readiness 契约。14 个 Local Profile
  artifact 与 D-302 对应字节数一致；PostgreSQL 18.4 arm64 HA 123 项 gate 全绿、timeline `1→2`，证据 SHA-256 为
  `e7c1743e932f2d7c35dc9153cdf5bc4a03356a38d93fce5507354652aa207a05`，独立审计与 Docker 清理通过。完整验证证据见 ADR-0391。
+
+- D-304/ADR-0392（已接受）：Plugin Package 进入安全 quarantine 时，Workflow/Prompt automation publication 不再仅依赖运行时 start guard 间接拒绝，而是与 quarantine event、Package-owned Task disabled revisions、Project Tool snapshot 和 withdrawal receipt 在同一 SQLite/PostgreSQL 事务中收敛为 `withdrawn`。原先仅能引用普通 lifecycle event 的外键升级为 append-only disposition-event 联合引用，历史 migration 与 publication digest schema 保持不变；SQLite edge/standalone 崩溃矩阵覆盖 automation publication insert 后、event/task/receipt/COMMIT 前后，PostgreSQL 通过触发器在既有 `SECURITY DEFINER` quarantine commit 内登记 disposition，再由同一外层 SERIALIZABLE transaction CAS publication head。能力位为 `plugin_package_automation_security_withdrawal@1`；不新增 package、daemon、timer、连接或常驻缓存，适用于低配路由设备和集群节点。SQLite 全量 228/228；PostgreSQL package 311 pass/1 条外部 URL 条件 skip；完整 18-package build/test 退出 0，backend 1,188 pass/2 skip，package/dependency boundary 零 finding；PostgreSQL 18.4 arm64 HA 125 项 gate 全绿、timeline `1→2`，报告 SHA-256 为 `ab156901b9c96ec5a62259c44d83d24ded011e0616dc827d928f3e13efd11786`。
 - D-302/ADR-0390（已接受）
  Cluster operator context 增加无网络、无 mutation 的内建 `ql3-cluster-admin context validate` 预检。它先复用 owner-private context
  reader，再让每个 entry 经过与真实请求相同的 production HTTPS/Kubernetes configuration preparation，验证精确 route、hostname、CA、
@@ -0,0 +1,41 @@
+# ADR-0392：Plugin Package Automation 安全隔离原子撤回
+
+- 状态：Accepted
+- 日期：2026-08-13
+- 关联 RFC：QL-RFC-0001 D-304
+- 关联 ADR：ADR-0221、ADR-0222
+
+## 问题
+
+现有 quarantine 会原子撤回 Package-owned Task 与 Tool snapshot，并由 Run、Tool、Workflow start guard 阻止新执行；但 Workflow/Prompt automation publication head 仍可能保持 `active`。这会让产品可见状态、安全状态与恢复扫描语义不一致。
+
+早期 automation publication 的 `lifecycle_event_digest` 又通过外键只允许引用普通 lifecycle event，因此 quarantine event 无法成为合法撤回证据。修改历史 migration 或发布摘要会破坏已部署数据库与 append-only 证据链。
+
+## 决策
+
+1. 新增 append-only automation disposition event 投影，统一登记 `lifecycle|quarantine`，但保留 publication v1 字段名与 digest 计算。
+2. SQLite 以追加 migration 重建 publication 外键，运行期先插入 quarantine event，由 trigger 登记 disposition，再以窄接口只允许 `active -> withdrawn`，全部处于同一 `BEGIN IMMEDIATE`。迁移表重建窗口临时关闭 foreign key，提交后恢复并立即执行 readiness、`foreign_key_check` 与 schema lockstep。
+3. PostgreSQL 以 `pg-0058` 追加表、触发器、外键与能力位。既有 quarantine `SECURITY DEFINER` function 写入事件时触发 disposition，repository 随后在同一 SERIALIZABLE transaction 内 CAS automation publication；任一失败整体回滚。
+4. `absent` 或已 `withdrawn` 的 publication 不制造无意义版本。publication target 与 quarantine install generation 不一致时 fail closed。
+5. receipt replay 校验目标 generation 在隔离提交点之后不存在 active automation publication；缺失或被回拨的撤回证据返回 unavailable。
+6. 能力位为 `plugin_package_automation_security_withdrawal@1`。实现不得增加 package、常驻进程、定时器、连接或缓存。
+
+## 资源与部署影响
+
+- edge/standalone：新增一个两列小表和两个 INSERT trigger；每次 lifecycle/quarantine 仅追加一行，常驻内存与连接数不变。
+- cluster：新增同构表、两个 statement-local trigger 和一个只供 trigger 调用的函数；disposition 投影不向任何运行角色开放读取，无新 Pod、worker 或数据库连接。
+- 历史 publication JSON、digest、lifecycle event 与 quarantine receipt 均不改写。
+
+## 验证
+
+- SQLite local package 全量测试、typed schema/readiness、备份恢复及 edge/standalone quarantine crash matrix。
+- PostgreSQL package 全量测试、migration checksum、Drizzle/schema/readiness/least-privilege contract。
+- PostgreSQL 18 physical-streaming HA Docker gate，验证 quarantine、automation withdrawn、COMMIT-response-loss、promotion 与 rewind 后证据存活。
+
+## 当前证据
+
+- SQLite 全量 228/228；quarantine crash matrix 覆盖 edge/standalone × 6 个 event、automation withdrawal、Task/Tool、receipt 与 COMMIT 前后窗口。
+- PostgreSQL package 312 项：311 pass、1 条仅在未提供独立测试数据库 URL 时条件 skip、0 fail；migration checksum、Drizzle/schema/readiness 与最小权限契约全绿。
+- Cluster Admin 304 项：302 pass/2 条件 skip；Cluster Control 232 项：230 pass/2 条件 skip；Local Owner CLI 168 项：163 pass/5 条件 skip；完整 18-package build/test 退出 0。
+- backend 1,190 项：1,188 pass/2 条件 skip/0 fail；package boundary 保持精确 18 package、无 single-source/shallow package，两个 `ordered_ledger` 目录分别锁定为 PostgreSQL 59 与 SQLite 91 个 migration source；cluster dependency audit 零 finding。
+- PostgreSQL 18.4 arm64 physical-streaming HA 125 项 gate 全绿，timeline `1→2`；包含 quarantine COMMIT-response-loss、standby 上 disposition/withdrawn head、promotion 后精确 publication chain 与旧主 rewind/rejoin。私有报告 SHA-256 为 `ab156901b9c96ec5a62259c44d83d24ded011e0616dc827d928f3e13efd11786`，测试容器、网络与卷均已清理。
@@ -395,6 +395,7 @@
 | [ADR-0389](./ADR-0389-owner-private-cluster-operator-context.md)                                               | Owner-private Cluster Operator Context                                                                                               | Accepted |
 | [ADR-0390](./ADR-0390-offline-cluster-operator-context-preflight.md)                                          | Offline Cluster Operator Context Preflight                                                                                           | Accepted |
 | [ADR-0391](./ADR-0391-read-only-cluster-operator-context-readiness.md)                                        | Read-only Cluster Operator Context Readiness                                                                                         | Accepted |
+| [ADR-0392](./ADR-0392-atomic-plugin-package-automation-security-withdrawal.md)                                | Plugin Package Automation 安全隔离原子撤回                                                                                           | Accepted |

 ## 规则

@@ -6,13 +6,13 @@
    "reviewedDenseDirectories": [
      {
        "kind": "ordered_ledger",
-        "maxDirectSourceFiles": 58,
+        "maxDirectSourceFiles": 59,
        "path": "packages/ql3-cluster-postgres/src/migrations",
        "rationale": "PostgreSQL migrations are an append-only version ledger whose ordering and discoverability are safer in one reviewed directory."
      },
      {
        "kind": "ordered_ledger",
-        "maxDirectSourceFiles": 89,
+        "maxDirectSourceFiles": 91,
        "path": "packages/ql3-local-sqlite/src/migrations",
        "rationale": "SQLite migrations are an append-only version ledger whose ordering and discoverability are safer in one reviewed directory."
      }