feat(ql3): establish 3.0 incubation baseline

docs/adr/ADR-0189-cluster-effective-publisher-trust-material-binding.md

@@ -0,0 +1,136 @@
+# ADR-0189：Cluster Effective Publisher Trust Material Binding
+
+- 状态：Accepted
+- 日期：2026-07-28
+- 关联：RFC D-175、D-177、D-178、D-179；
+  ADR-0185、ADR-0187、ADR-0188
+
+## 背景
+
+ADR-0188 已将 Cluster publisher trust 的有效代际保存在 PostgreSQL，并明确挂载文件只用于
+初始化 base snapshot。但 recovery 进程仍直接用挂载文件中的全部 PEM 构造
+`PluginPackagePublisherTrustRegistry`。这会形成控制面与执行面的 authority 分裂：
+
+- operator 为 overlap rotation 预先分发 old+new ConfigMap 时，new key 会在 Approved
+  Action 推进 effective head 前被 recovery 信任；
+- 数据库已经撤销或退役 key 后，旧 Pod/旧挂载仍可能继续把该 key 当作 verifier material；
+- 管理面比较 base snapshot 不能约束独立使用 Package-executor credential 的 recovery Job。
+
+必须先关闭这个缺口，才能安全实现正常 overlap-add 与 retirement。
+
+## 决策
+
+### 1. 文件是 material，PostgreSQL head 是 authority
+
+publisher trust 文件继续保存公开的 Ed25519 PEM、publisher、key ID 和 lifetime。读取器对
+文件大小、regular-file、只读权限、exact JSON shape 和全部 key 定义执行既有严格验证。
+
+运行时新增纯绑定函数：
+
+1. 从全部文件定义构造 canonical low-sensitive material snapshot；
+2. 规范化 PostgreSQL 返回的 effective snapshot；
+3. 对每个 effective key 精确匹配 publisher、key ID、public-key digest、not-before 和
+   not-after；
+4. 只用匹配成功的定义构造 verifier registry；
+5. effective key 缺材料、PEM 被替换、lifetime 漂移或 effective set 为空时失败关闭。
+
+文件可以是 effective set 的真超集，因此允许先分发候选 key；额外 key 不进入 verifier。
+
+### 2. stage authority 在数据库就绪后创建
+
+`recoverClusterPluginPackages` 支持二选一：
+
+- 调用方提供已构造的 `stageAuthority`；
+- 调用方提供 `stageAuthorityFactory(pool)`。
+
+两者必须且只能存在一个。factory 只在 Package-executor 数据库资源完成 schema/readiness
+检查后调用；返回值立即执行同一 stage/verify contract 检查，并只在本次 recovery 周期内
+使用。数据库仍由既有 one-shot composition 统一关闭，factory 不建立第二个 pool，也不让
+repository 或 stage authority 逃逸。
+
+生产 recovery 使用 factory：
+
+1. 读取显式 `QL3_PLUGIN_PACKAGE_TRUST_AUTHORITY_ID`，默认 reviewed `cluster`；
+2. 用现有只读 trust repository 查询 head 与 effective snapshot；
+3. 将挂载 material 绑定为 effective registry；
+4. 再构造 OCI stage authority。
+
+因此 trust 查询、provenance recovery、stage 和 activation 共享一个最多 1 连接的
+Package-executor pool，适合低资源单节点，也适合 HA writer endpoint。
+
+### 3. 失败边界
+
+以下状态必须在 OCI fetch、签名验证、Kubernetes 写入前失败：
+
+- authority head 不存在；
+- effective snapshot 在文件中缺少 exact material；
+- public-key digest 或 lifetime 与 durable snapshot 不一致；
+- 文件权限、大小、shape 或 key 类型不合法；
+- database-bound factory 返回不完整 authority。
+
+显式测试注入的 registry/stage authority 保留，用于无网络、无数据库的确定性测试；产品
+部署不能通过环境变量选择绕过 durable head 的 registry。
+
+### 4. 与 rotation/retirement 的关系
+
+本 ADR 不新增 trust transition：
+
+- overlap-add 后续采用 `old+new material` 预分发，再由受批 executor 推进 effective
+  `old → old+new`；
+- retirement 后续采用 durable impact proof 与 generation fence 推进
+  `old+new → new`，随后才允许从文件清理 old material；
+- emergency revoke 继续使用 ADR-0188 的 receipt/impact/quarantine 链。
+
+正常 retirement 不能仅靠本次 recovery 启动时的 snapshot；后续 transition 必须在
+provenance 写入和 head 推进处增加并发 fence。
+
+## 包与资源边界
+
+不新增 workspace package、migration 或生产依赖：
+
+- `runtime-core` 保存纯 material/effective 绑定；
+- `cluster-postgres` 复用现有 Package-executor 可读 trust repository；
+- `cluster-admin` 在现有 recovery composition 内延迟构造 stage authority。
+
+workspace 保持 22 包。没有新增 listener、timer、watcher、Service 或常驻 Pod；recovery
+仍是显式 one-shot Job，数据库 pool 仍为 1 个连接。
+
+## 不采用方案
+
+### 文件 digest 必须等于 effective digest
+
+这会禁止 old+new 候选材料预分发，并迫使 ConfigMap 更新与数据库审批形成不可实现的跨介质
+原子提交。
+
+### management 把 effective registry 推送给 executor
+
+会把短生命周期 executor 依赖于管理进程可用性，并增加新的网络协议、身份和缓存一致性问题。
+
+### recovery 启动前单独打开第二个数据库 pool
+
+会增加低配设备连接开销，并让 trust 读取与实际 recovery 使用不同资源生命周期。
+
+### 为 material binding 新拆 package
+
+没有独立 Profile、credential、制品或第三方依赖边界，会违反 ADR-0185 的 package
+收敛原则。
+
+## 验收
+
+- runtime-core 测试证明候选 key 被排除、exact durable key 可用、同 identity 替换 PEM
+  失败关闭；
+- recovery composition 测试证明 factory 只在 readiness 后接收同一 pool，且数据库仍精确
+  关闭一次；
+- Package recovery 配置与 base/CloudNativePG manifest 显式绑定 authority ID；
+- 两套 Kustomize 渲染、deployment audit 与 dependency audit 无 finding；
+- runtime-core 359/359；cluster-admin 111 pass、1 条真实 Kubernetes 条件 skip；
+- PostgreSQL 18.4 arm64 physical HA 总门重跑 `gates.passed=true`，v38 Approved
+  Action、trust generation `1→2`、quarantine exact-once、timeline `1→2`、旧主
+  fence、`pg_rewind` 与同步只读重加入均无回归；
+- workspace 仍为 22 包，无 migration、依赖或常驻资源增长。
+
+## 后续
+
+1. D-180 实现单 key overlap-add 与 safe-retire proposal/action。
+2. retirement 在 signer provenance commit 与 trust-head transition 间增加 generation fence。
+3. HA 门增加 old+new material 预分发、批准前拒绝、批准后接受和旧 key 安全退役证据。