qinglong/docs/adr/ADR-0394-generation-bound-plugin-package-secret-materialization.md

# ADR-0394：按 Generation 固定的 Plugin Package Secret Materialization

- 状态：Accepted
- 日期：2026-08-13
- 关联 RFC：QL-RFC-0001 D-306A
- 关联 ADR：ADR-0151、ADR-0153、ADR-0393

## 问题

D-305 已把 Package 的逻辑 Secret requirement 固定为不可变、按 generation 绑定的版本化 `qlsecret://` 引用，但 Task source 仍不能消费该绑定。若在 dispatch 时才按 requirement 名称查找，会使 materialized revision 与实际 Secret 版本脱节；若允许 Package source 直接携带部署方 SecretRef，又会绕过安装方授权。

Local/Edge 还要求只读 readiness 不加载 migration 执行模块，且不能因 Secret-aware Package 引入 watcher、缓存、连接或常驻进程。Cluster 必须在直接数据库写入时也拒绝未绑定或越权的 SecretRef。

## 决策

1. Package Task source 以 `{kind:"package-secret", requirement:"NAME"}` 引用 Manifest 的逻辑 requirement，不允许直接写 `kind:"secret"` 或 `qlsecret://`。
2. materialization 读取当前 generation 的 D-305 binding，把逻辑 requirement 编译为已有、固定版本的 Task `SecretRef`；optional 且显式绑定为 `null` 的环境项被省略。普通 Task dispatch、Local 短时解密和 Cluster offer/lease-fenced delivery 继续复用现有执行链，不增加新的 Secret 传输协议。
3. materialized revision 嵌入完整 binding 快照但不含明文，binding 与最终资源共同进入 revision digest。任何 Task SecretRef 必须属于该快照；Manifest 声明 Secret 时缺失 binding 或 `secret.use` capability 均失败关闭。
4. SQLite 与 PostgreSQL 在 materialized revision INSERT 边界增加触发器，拒绝畸形 Secret 声明、未解析 placeholder、缺失/不匹配 binding 和 binding 外 SecretRef，防止绕过 core repository 直接写库。
5. SQLite 的触发器 SQL 真源位于非执行型 schema contract；migration 与 readiness 共同引用，保持只读 readiness 和 rollout-safety 不加载 DDL 模块。Local contract 升至 v47，Cluster 升至 v59。
6. 实现复用既有 SQLite authority、PostgreSQL pool、Task Secret resolution 与 Worker delivery，不增加 package、表、索引、连接、timer、watcher、cache、Pod 或 daemon。Local 仅增加一个 INSERT trigger，Cluster 增加一个 trigger function 与一个 INSERT trigger。

## 生命周期与阶段边界

- binding 与 materialized revision 均按 generation 不可变；Secret 新版本不会静默改变既有 generation。
- Package disable/quarantine/uninstall 继续由现有 generation/lifecycle start guard 阻止新执行；已开始执行仍遵循既有 Run/Worker 清理语义。
- D-306A 完成 runtime consumption 和数据库防绕过，不宣称产品授权闭环完成。面向用户的 Local bind/rebind 命令、Cluster Approved Action/API，以及通过新 generation 执行 rotation/rebinding/revocation 的编排属于 D-306B。

## 资源与部署影响

| Profile | 增量 | 常驻开销 |
| --- | --- | --- |
| Edge / Standalone | 一个 INSERT trigger；启动发布按需点查一个既有 binding row | 无新增进程、连接、缓存、timer 或 watcher |
| Cluster | 一个非 `SECURITY DEFINER` trigger function 和一个 INSERT trigger；复用 executor pool | 无新增角色、连接、workload、sidecar 或 worker |

## 验证

- core：placeholder 编译、optional-null、省略、直接 SecretRef/缺失 binding/越权引用拒绝、revision digest 与 normalize round-trip。
- SQLite：真实 migration、畸形声明与未绑定 SecretRef 直接 INSERT 拒绝、readiness DDL lazy boundary、rollout safety、edge/standalone contract。
- PostgreSQL：migration checksum、trigger/function、固定 search path、权限撤回、schema/readiness 与 physical-streaming HA gate。
- 完整 18-package clean build/test 退出 0；backend 共 1,190 项，1,188 pass、2 条件 skip、0 fail。
- package boundary、cluster dependency、edge import、service-manager bridge import、local image 五项审计零 finding；workspace 保持 18 package、1,090 source、1,072 nested source，`singleSourcePackages=[]`、`shallowSourcePackages=[]`。两个经审查的 `ordered_ledger` 目录精确为 PostgreSQL 61 与 SQLite 95 个 migration source，通用密集目录门禁未放宽。
- PostgreSQL 18.4 arm64 HA Docker gate 共 125 项全绿，timeline `1→2`；私有报告 SHA-256 为 `f9107e8e54892a788779758f0573ac8d6a80f6d086516a1f5f5bbacb59bbb4be`。