qinglong/docs/adr/ADR-0190-cluster-approved-publisher-trust-overlap-add-and-safe-retire.md

ADR-0190：Cluster Approved Publisher Trust Overlap Add 与 Safe Retire

• 状态：Accepted
• 日期：2026-07-28
• 关联：RFC D-175、D-177、D-178、D-179、D-180； ADR-0185、ADR-0187、ADR-0188、ADR-0189

背景

ADR-0188 只实现 compromised-key emergency revoke；ADR-0189 已保证挂载文件是 material、 durable head 才是 effective authority。正常 key rotation 仍缺少两种受批变更：

1. 在不删除旧 key 的前提下让一个预分发的新 key 生效；
2. 在所有当前安装均不再依赖旧 key 后安全退役旧 key。

若把 ConfigMap 更新直接当作生效，会绕过 Project Policy/Approval；若 retirement 只在 executor 启动时检查一次 head，并发 stage 仍可能在退役扫描后提交旧 signer provenance。

决策

1. 两种 action，不复用 emergency revoke

新增两个 action type：

• plugin_package.publisher_key.overlap_add
• plugin_package.publisher_key.safe_retire

它们都要求 trust-authority Project 的 package.manage，固定创建 separation_of_duty Approval；请求人与确认人必须是不同的强认证 User。正常轮换不提供 break-glass；suspected/confirmed compromise 必须使用 D-178 emergency revoke。

客户端只提交：

• actionRef、approval/audit identity；
• mode；
• publisher、keyId；
• strong authenticated principal。

客户端不得提交 PEM、candidate snapshot、previous/current digest、generation、影响集或 retirement proof。

2. overlap-add 从只读 material 派生

管理进程启动时读取并严格验证 publisher material 文件。首次 observation 创建 base/head； 后续不同 snapshot 只以 digest-only candidate 写入 snapshot ledger，并返回当前 effective head，不能隐式推进 generation。

提案时，服务用进程内已审 material snapshot 与数据库 effective snapshot计算差异：

• 所有 effective key 必须逐字段保留；
• 必须只新增请求指定的一个 (publisher,keyId)；
• 新 key 在 proposal time 必须处于 lifetime；
• 禁止 removal、rewrite、批量 addition 或跨 publisher 附带变更。

proposal 绑定 candidate digest；executor 执行时再次从 durable snapshot ledger 解析并 重验同一 one-key addition。

3. safe-retire 从 durable effective set 派生

safe-retire 不要求 operator 先删除文件中的旧 PEM。服务从当前 effective snapshot 精确删除 请求 key，要求：

• 目标 key 当前存在；
• 同一 publisher 至少保留一个在 proposal time 当前有效的 successor；
• 除目标删除外没有任何 key 或 lifetime 变化。

候选 digest 由服务派生并写入 snapshot ledger。head 生效后，D-179 verifier 会排除旧 key； operator 可在确认所有 recovery Job 已观察新 generation 后再清理旧 PEM。

4. v39 schema contract / pg-0040 durable proposal 与 receipt

control-core v39 由 pg-0040-plugin-package-publisher-trust-transitions 新增：

• plugin_package_publisher_trust_transition_proposals：不可变绑定 mode、Project/Policy fence、proposer、generation、目标 key、previous/candidate digest、action/preview digest；
• plugin_package_publisher_trust_transition_receipts：绑定 approved dispatch、 proposal、previous/current generation/digest、执行 User/fence、retirement proof summary 和数据库时间。

proposal/approval/dispatch/receipt 必须 exact replay。manager 只能插入 candidate/proposal/ approval/audit；只有 package-executor 可推进 head 和写 receipt。

5. retirement 与 stage 使用同一 signer fence

所有 (publisher,keyId) mutation 继续使用 ADR-0187/0188 的同一 domain-separated advisory transaction lock。

safe-retire executor 在 SERIALIZABLE transaction 内：

1. 锁 signer；
2. FOR UPDATE 精确 authority head 并重验 generation/digest；
3. 扫描该 signer 对应的 current staged|activating|active install head；
4. 要求 matching count 为零；
5. 写 zero-impact retirement proof receipt；
6. 推进 effective head generation；
7. 原子提交 head 与 receipt，二者共同构成唯一业务提交点。

通用 Approved Action dispatcher 在业务事务返回后，将 execution 投影为 succeeded。该投影 不参与 trust authority 判定，也不能单独推进 generation。若进程在业务 COMMIT 成功后、 execution 完成前崩溃，恢复执行必须以同一 dispatch、proposal、execution start time 重新调用 transition repository；repository 只允许返回完全相同的 receipt/head， dispatcher 再收敛 execution。不得为了消除该投影窗口，把通用 dispatcher 的 execution 协议或其他 handler 的事务所有权耦合进 publisher trust repository。

provenance stage commit 在 signer lock 后必须按安装显式绑定的 trust authority 查询当前 effective snapshot，并要求 signer 仍存在。这样顺序只有两种：

• stage 先获锁并提交，retire 随后看到 impact > 0 而拒绝；
• retire 先获锁并提交，stage 随后看到 key 已不在 effective set 而拒绝。

不得仅依赖 recovery 启动时缓存的 registry。

6. authority ID 必须显式贯穿 stage

Package recovery 配置已经具有 QL3_PLUGIN_PACKAGE_TRUST_AUTHORITY_ID。D-180 将该 ID 传入 provenance repository/commit command；repository 不允许“任一 authority 包含该 key” 或隐式选择第一条 head。若未来需要一个集群多个 trust domain，必须在 Package proposal/ lock 中增加受批 authority binding，不能靠数据库枚举猜测。

7. 资源与包边界

复用现有：

• runtime-core trust/action contract；
• cluster-postgres snapshot/head、Approved Action、provenance repository 与 migration stream；
• cluster-admin management transport/process 和 caller-driven executor。

不新增 workspace package、生产依赖、listener、timer、Service 或常驻 controller。现有 executor 的最多 2 个连接、批预算和 opt-in CronJob 不变；低配节点可继续外部调用一次性 CLI。

不采用方案

ConfigMap rollout 自动推进 head

Kubernetes write authority 不能替代 Project Policy、双人 Approval 和 durable exact replay。

safe-retire 复用 emergency revoke

正常零影响 retirement 不应制造 compromise reason、revocation receipt、Run/Tool emergency deny 与 quarantine 语义。

retirement 只检查当前 catalog 或只读快照

catalog 不是 Cluster 当前 install-head authority，事务外只读也无法与并发 stage 串行化。

查询任意 authority 是否包含 signer

会在多 authority 时错误放宽 signer，属于 confused-deputy。

新拆 trust-transition package

没有新的 Profile、credential、制品或第三方依赖边界，违反 ADR-0185。

验收证据

• 纯 contract 覆盖 exact one-key add/remove、same-publisher successor、lifetime 和客户端 digest injection 拒绝；
• PostgreSQL mock 与真实 PG 覆盖 candidate observation、proposal exact replay、 manager/executor ACL、receipt/head atomicity，以及业务 COMMIT 后 execution 投影丢失的 exact replay；
• 并发真库门确定性覆盖 stage wins → retire blocked 与 retire wins → stage blocked；
• management transport 只暴露 mode/publisher/key ID；
• executor 同时消费 revoke 与 transition，保持 caller-driven bounded work；
• 本机 arm64 PostgreSQL 18.4 真库集成覆盖 generation 1→2→3、2 条 receipt、 safe-retire exact replay，以及共享 advisory lock 下 stage/retire 双向单赢家；
• qinglong/postgresql-ha-contract@v1 使用 physical streaming、remote_apply、 timeline 1→2、旧主 fencing、promotion、pg_rewind 与只读同步 rejoin，证明 old+new material 预分发、双人审批、2 proposals、2 receipts、2 succeeded executions 和 generation 1→2→3 在 WAL replay 与 promotion 后持续；
• workspace 保持 22 包；cluster dependency、cluster deployment、CloudNativePG deployment 与 edge import audit 均无 finding。