qinglong/docs/adr/ADR-0137-postgresql-plugin-package-install-repository-and-project-lock-authority.md

ADR-0137：PostgreSQL Plugin Package 安装仓库与 Project Lock Authority

• 状态：Accepted（PostgreSQL 三表、完整 lock、capability v17、admin-only repository、 SECURITY DEFINER Project lock、跨 adapter 合同与物理 HA 门已完成；通用 activation coordinator、标准 OCI stage verifier、Kubernetes ConfigMap publisher、一次性 admin recovery process、exact-registry credential provider、独立镜像与最小权限 Job/RBAC/真实 Kubernetes 专项门已可组合；Approved Action 产品 consumer 与管理入口仍未开放）
• 日期：2026-07-24
• 关联 RFC：QL-RFC-0001 D-08、D-09、D-127、D-132、D-134、D-135
• 关联 ADR：ADR-0125、ADR-0129、ADR-0134、ADR-0135、ADR-0136

背景

ADR-0136 已让 edge/standalone 通过单 SQLite authority 持久化 Plugin Package installation 历史、当前 head 与 mutation replay，但 cluster 节点仍没有同一 runtime-core contract 的 PostgreSQL adapter。若集群另造状态机，SQLite 与 PostgreSQL 会在 first-create、terminal replacement、旧 mutation replay 和恢复扫描 上逐渐产生不同安全语义。

实现过程中还出现一个 PostgreSQL 特有边界：创建 installation 前必须确认 Project 为 active，并把该事实锁到 transaction 结束。普通 SELECT 不能阻止并发归档； SELECT ... FOR SHARE 又要求调用角色拥有目标表 UPDATE privilege。仅为了取得行锁就 授予 ql3_admin 通用 Project UPDATE，会扩大数据库权限而不是表达所需能力。

决策

1. Adapter 留在既有 @qinglong/cluster-postgres

Repository 只通过 @qinglong/cluster-postgres/plugin-package-install 显式 subpath 导出，不从 root、 runtime、admin 或 worker-ingress 入口导出，不新增 workspace package和第三方依赖。

它只接受 admin Pool；默认 cluster-control、worker 与 migration composition 都不 加载该 subpath。实现存在不代表产品已暴露安装入口。

2. pg-0018 冻结三类耐久事实

pg-0018-plugin-package-installs 创建：

• plugin_package_installs：每个 installation 的不可变 lock_json、当前 record 和全 generation 历史；
• plugin_package_install_heads：每个 Project/Package 的唯一当前 authority；
• plugin_package_install_mutations：mutation ID/digest 与 resulting record digest。

CHECK、FK、partial recovery index、Project history index 与 mutation result index 同 typed Drizzle schema、SQL migration、migration manifest 和 readiness contract lockstep。Repository findLock 每次重新规范化并重算 lock digest。PostgreSQL stream 由 exact pg-0017 前驱推进到 18 条 migration、 control-core capability v17、30 张受审表，并发布 "plugin_package_install":1。

runtime 与 worker-ingress 对三表没有任何 table privilege。ql3_admin 对 install/head 只有 SELECT/INSERT/UPDATE，对 mutation ledger 只有 SELECT/INSERT，所有角色均无 DELETE。

3. 用单用途 SECURITY DEFINER 表达 Project 锁能力

migration 创建 ql3.lock_active_plugin_package_project(varchar) -> boolean。函数：

1. owner 固定为 ql3_migration；
2. 使用 SECURITY DEFINER 和固定 search_path=pg_catalog, ql3；
3. 以 FOR SHARE 读取目标 Project，锁住 concurrent status update/delete；
4. 只返回 active 与否，不返回 Project 数据；
5. 撤销 PUBLIC 默认 EXECUTE，只授予 ql3_admin；
6. runtime、worker-ingress 均不得执行，admin 也不因此获得 Project UPDATE。

readiness 对函数 name/signature、owner、security-definer、volatility、search path、 PUBLIC ACL 及当前角色 EXECUTE 权限进行 exact 审计。未知 ql3 function、owner 漂移、 PUBLIC execute 或角色越权都使 activation 失败关闭。

4. Repository 复用完全相同的领域合同

create/commit 使用短 SERIALIZABLE transaction，依次验证：

• active Project lock；
• exact current head 或空 head；
• runtime-core 重新计算的 create/commit command；
• installation version、record digest、mutation ID/digest CAS；
• history、head 与 mutation ledger 原子提交。

只对 PostgreSQL 40001、40P01、55P03 做最多三次 transaction retry。 连接错误、COMMIT response loss 和其他 outcome-unknown 不透明重放，必须由调用方读取 durable mutation/head 事实后裁决。exact replay 返回当前已前进 record，不倒写旧状态。

恢复只扫描当前 head 中 queued | staged | activating，使用稳定 Package/installation cursor，每页最多 64 条；旧 generation 不能重新取得 authority。

5. 两个 adapter 共享一份可执行语义合同

根级 pluginPackageInstallRepositoryContract.cjs 同时驱动 SQLite 与真实 PostgreSQL， 覆盖 create/find、exact replay、mutation drift、CAS/stale state、旧 mutation replay、 terminal head replacement 和 current-head recovery pagination。adapter-specific 测试只保留 catalog、corruption、role/entrypoint 与数据库故障行为。

6. 产品安装入口继续失败关闭

后续 ADR 已补齐标准 OCI source/stage verifier、一次性 recovery process、独立 cluster-admin image 与 namespaced ConfigMap-only Job/RBAC；这些恢复能力不等于面向 用户开放安装入口。当前仍不实现：

• 具体 Approved Action 产品 consumer 与管理入口；
• Task/Workflow/Prompt/Tool/Trigger 的原子 generation publisher；
• operator repair、旧 generation GC；
• publisher revoke/index、管理 API/CLI/UI 或自动更新；
• Runtime Extension 或动态代码加载。

因此 production cluster 可以在已存在耐久 installation 的前提下运行受限恢复门，但仍 不能通过产品入口创建安装、激活新的资源 generation 或启用动态代码。

拒绝的方案

• 新增 plugin-package-postgres workspace package：拒绝；单一 adapter 文件和迁移属于 现有 cluster-postgres，拆包只会增加 importer/build/发布成本。
• 直接授予 admin Project UPDATE 以便行锁：拒绝；技术性锁需求不应变成通用数据修改 authority。
• 普通 SELECT 后写 installation：拒绝；Project 可在检查后并发归档。
• 在 repository 内复制 SQLite 状态机：拒绝；领域语义必须由 runtime-core 和共享合同 单点定义。
• 将 repository 加入 admin/root 默认导出：拒绝；会让短生命周期安装 authority 在无产品闭环时变成易达能力。

影响

• 集群节点获得与本机完全对等的 crash-safe installation/head/mutation authority。
• 低配 edge/standalone 制品不安装或加载 cluster-postgres，本切片不改变其常驻资源。
• workspace importer 仍为 21 个，没有新增 package 或依赖。
• PostgreSQL readiness 多审计一个单用途函数，但常驻进程不增加 timer、watcher、 sidecar 或数据库连接。

验证

• migration checksum、SQL/Drizzle/schema/function contract、三角色 readiness 与显式 subpath 隔离：21/21；
• local-sqlite 全量及共享合同：68/68；
• cluster-postgres 非数据库全量：124 pass、1 个条件 skip、0 fail；
• PostgreSQL 18 单角色真实集成：26 pass、3 个角色条件 skip、0 fail；
• PostgreSQL 18 四角色真实集成：28 pass、1 个同角色 backend termination 条件 skip、0 fail；
• pnpm test:postgres-ha:ql3：21 个 HA 子门和总 passed 全为 true；2026-07-25 最近一次本机 arm64 证据为 fail-closed 312.866 ms、fresh activation 364.602 ms、旧主 pg_rewind 1,744.481 ms，0 unexpected domain side effect。

21 个 importer 的 clean build 与全量 package 聚合测试均退出 0；dependency/source boundary、edge import 和六种 Profile artifact 门禁均通过且 findings=[]。六种制品 顺序复验的最大值为 2,849,582 bytes/439 files/78 loaded modules，最大 RSS delta 13,221,888 bytes，低于 4 MiB/512 files/16 MiB 硬门禁。production composition 与 真实 operator 安装恢复仍是后续独立 Gate。