# ADR-0151：SQLite/PostgreSQL 不可变 Plugin Package 物化修订仓库

- 状态：Accepted（双方言仓库、迁移、readiness、共享合同与真实 PostgreSQL 门已实现；
  Task 批量发布、全局 Tool snapshot 和 consumer activation 尚未实现）
- 日期：2026-07-25
- 关联：ADR-0136、ADR-0137、ADR-0149、ADR-0150、QL-RFC-0001 D-144/D-145

## 背景

ADR-0150 已把同一 active Package generation 的 Task、Workflow、Prompt 和 Tool 文件
物化为自包含、可规范化的
`qinglong/plugin-package-materialized-revision@v1`。此前只有纯领域 repository port，
没有耐久 adapter：

- edge/standalone 重启后必须重新打开 staging 才能取得语义；
- Cluster 多副本无法围绕同一 `generationDigest` 收敛；
- consumer 无法在读取 active generation 后取得一份可审计的 exact revision；
- 如果分别保存 source、Task、Workflow、Prompt 和 Tool，多行提交会产生同一 generation
  的部分可见状态。

耐久化不能成为第二个 active pointer，也不能让 Package manager、常驻 runtime 或
Worker 获得原始 Package 语义写权限。

## 决策

### 1. 不新增 workspace package

repository port 继续位于
`@qinglong/runtime-core/plugin-package-resource-materialization`；SQLite adapter 放入
既有 `@qinglong/local-sqlite/plugin-package-materialized-revision`，PostgreSQL
adapter 放入
`@qinglong/cluster-postgres/plugin-package-materialized-revision`，并只从 Cluster
`package-executor` 权限入口导出。

两个 adapter 都是显式 subpath，不从 Profile-neutral root 聚合导出。不新增第三方
依赖、连接池、timer、watcher、socket 或常驻缓存；workspace importer 保持 21 个。

### 2. 一代一行，自包含保存

双方言分别新增：

- SQLite `QingLong3PluginPackageMaterializedRevisions`；
- PostgreSQL `ql3.plugin_package_materialized_revisions`。

每行保存：

- `generation_digest` 主键；
- `project_id`、`package_name`、`generation`、`lock_digest`；
- `manifest_digest`、`revision_digest`；
- 完整 canonical `revision_json`；
- 数据库观察的创建时间。

`generationDigest` 是 repository identity；`project + package + generation` 另有唯一
约束，防止同一代出现不同语义。数据库 CHECK 从 JSON 中复验上述重复 identity，
避免索引列与 payload 漂移。只外键到 Project，不外键到可变 install head 或 lock
history：语义修订需要在安装记录回收后仍可作为执行和审计事实存在。

完整 revision 单行保存是刻意选择。repository port 返回一份完整 revision，单行
`INSERT` 可以保证 publish 原子性；若拆为资源明细表，必须再引入 batch commit 标记与
复杂的 incomplete-generation 恢复协议。

### 3. create 或 exact replay

仓库只提供：

- `create(revision)`；
- `findByGenerationDigest(generationDigest)`。

`create` 先通过 runtime-core normalizer 复验完整 revision。首次写入成功；同一
`generationDigest` 重放时，只有 durable row 规范化后的完整值和摘要均 exact 相同才
返回既有记录。任何 identity、lock、Manifest、source 或语义差异都作为 conflict
失败关闭，不允许 update、delete、upsert overwrite 或“最后写入获胜”。

SQLite 在既有单 operation authority queue 内执行一个
`INSERT ... ON CONFLICT DO NOTHING` 与 exact read，不打开第二连接。PostgreSQL 使用
`INSERT ... ON CONFLICT DO NOTHING RETURNING`，冲突后 exact read；因为一行 append
本身即是原子发布，不要求连接 pinning 或跨网络长事务。

损坏的 durable JSON、数据库不可用和非预期 SQL 错误都映射为 unavailable；受审唯一/
CHECK/FK 约束映射为 conflict。调用方不得把不确定写入透明重放成不同 revision。

### 4. 明确存储与内存上限

ADR-0150 仍限制每个 resource 1 MiB、业务 resource source bytes 总计 8 MiB。
materialized revision 还包含 normalized semantic values、Manifest、lock、generation
和 JSON 编码开销，因此 durable `revision_json` 另设 24 MiB 硬上限，并在：

- runtime-core normalizer；
- SQLite CHECK；
- PostgreSQL CHECK

三处保持一致。

24 MiB 是一次显式安装/物化操作的最坏输入上限，不是常驻 RSS 预算。repository 不做
目录扫描、后台预热或全表加载；consumer 必须按 active `generationDigest` 精确读取。

### 5. 双方言 schema 与能力版本

SQLite：

- `0045-plugin-package-materialized-revisions` 建表和索引；
- `0046-capability-v23` 把 local contract 推进至 v23；
- capability 增加 `plugin_package_materialized_revision:1`。

PostgreSQL：

- `pg-0025-plugin-package-materialized-revisions` 建表、索引和角色授权；
- `control-core` capability 从 v23 推进至 v24；
- migration stream 为 25 条，catalog 为 38 张表；
- capability 增加 `plugin_package_materialized_revision:1`。

SQLite readiness 同时要求 migration、capability、表和两个业务索引。PostgreSQL
readiness 同时要求 migration、capability、表、索引、CHECK/FK 与精确 ACL。

### 6. PostgreSQL authority 只属于 Package executor

`pg-0025` 撤销 PUBLIC、runtime、admin、package-manager 和 worker-ingress 对新表的
全部权限，只授予 `ql3_package_executor`：

- `SELECT`；
- `INSERT`。

executor 没有 UPDATE/DELETE/TRUNCATE authority。Package manager 继续只负责公开管理
准入；常驻 runtime、Worker ingress 和 admin 不能读取或改写原始物化语义。迁移仍由
短生命周期 `ql3_migration` authority 执行。

### 7. durable revision 仍不是 active pointer 或执行发布

consumer 的顺序固定为：

1. 从 ADR-0149 source 读取一次 active generation；
2. 以其 `generationDigest` 精确查 revision；
3. 规范化并复验完整 identity；
4. 由后续受审 publisher 执行原子业务发布；
5. 发布前再次确认 active generation 未漂移。

repository 不提供 `current` 查询，不更新 active pointer，也不逐项创建 TaskDefinition、
注册 Tool handler、执行 Workflow/Prompt 或绑定 Secret。仓库完成只关闭“耐久语义事实”
缺口，不关闭“生产执行可见性”缺口。

## Profile 影响

- edge/standalone：复用现有单 SQLite operation authority；无新连接、线程或后台任务。
  只有显式 Package 物化/读取操作承担最多 24 MiB JSON 的短生命周期成本。
- cluster：多 executor 可以竞争同一 append；数据库唯一约束和 exact replay 使结果
  收敛。RPO-0/切换语义继续由既有 PostgreSQL HA 约束承担。
- worker：不导入 repository，不取得表权限，只消费后续 execution revision 绑定结果。

## 被否决方案

1. **新增 `plugin-package-revision-store` workspace package**：没有独立部署或依赖
   生命周期，会继续细碎化 `packages/`。
2. **按 Task/Workflow/Prompt/Tool 拆多张表**：当前 consumer 需要完整 revision，
   多表会引入部分发布和额外恢复协议。
3. **把 revision 塞进 active pointer/ConfigMap**：会突破 pointer 预算并合并文件发布、
   语义 authority 与业务激活。
4. **只存 digest、每次从 staging/OCI 重建**：无法给重启和多副本提供耐久 exact
   evidence，也把外部制品可用性带入执行读路径。
5. **给 manager 或 runtime 读写表权限**：会把公开 transport 或常驻控制面升级为
   原始 Package 语义 authority。
6. **允许 update/delete 以便升级或 GC**：升级本来就应产生新 generation；在引用感知
   retention 设计完成前删除会破坏执行与审计事实。

## 验证

- 共享 repository contract：首次 create、exact replay、按 generation digest 查询、
  absence；
- SQLite：真实 Node 24 `DatabaseSync`、单 operation authority、损坏 JSON
  fail-closed、root/subpath 隔离、typed schema/catalog/readiness lockstep；
- PostgreSQL：SQL 生成、数据库时钟、SQLSTATE conflict、损坏 JSON fail-closed、
  package-executor/root entrypoint 隔离；
- PostgreSQL 18.4 arm64 真库：25 条 migration 后完成 revision create、exact replay
  与 find；
- PostgreSQL 18.4 physical HA：`pg-0025`/v24/38 表和角色 readiness 在
  timeline 1→2 promotion 前后通过，旧主 fencing、`pg_rewind` 只读同步重入及既有
  24 项领域/HA 门全部通过；
- architecture：21-package 全量测试、edge import audit 和 cluster dependency audit
  必须保持无 finding。

## 后续

1. 设计 Package TaskDefinition 多资源单事务 reconciliation，以 generation 为批次，
   防止一代内部分可见；
2. 为全部 active generation 构造一次性 immutable Tool registry snapshot，Definition
   与受信 handler/preview publisher 分离；
3. 为 Workflow/Prompt 建立独立版本仓库和执行协议；
4. 建立 Package Secret requirement 到 Project SecretRef 的审批、rotation 和审计
   ceremony；
5. 在 execution revision/Run 引用建立后，再设计引用感知 retention；当前禁止 GC
   durable materialized revision。

上述 Gate 完成前，durable revision 仍不可直接进入生产执行路径。