qinglong/docs/adr/ADR-0238-production-worker-certificate-renewal-single-cadence.md

# ADR-0238：Production Worker 证书续期单 Cadence 装配

- 状态：Accepted
- 日期：2026-08-01
- 关联 RFC：QL-RFC-0001 D-23、D-58、D-60、D-175、D-207、D-218、D-222
- 关联 ADR：ADR-0060、ADR-0061、ADR-0121、ADR-0234、ADR-0235、ADR-0236

## 背景

ADR-0061 已实现 Worker 本地 CSR、证书校验、原子 generation 安装和跨重启退避，
ADR-0234 又让 production credential provider 在每个 HTTPS request 前读取当前 active
identity。然而 production Worker 组合根没有调用续期协调器：部署即使提供外部 CA
adapter，也只能另建 timer、watcher 或旁路进程触发续期，无法继承既有 Session、drain、
错误隔离和 Edge/Node 资源预算。

把外部 CA 直接放入 `cluster-control` 会扩大常驻入口的签发权限；为续期再建 package、
sidecar 或 timer 又会把空闲成本推给低性能路由设备。需要在不改变 CA authority 边界的
前提下，把已有一次性续期操作接入唯一 production cadence，并证明正在运行的 Worker
可以在不替换 Session 的情况下完成信任收缩。

## 决策

### 1. 续期是可选 Profile capability，不是内建 CA

`ProductionWorkerHeadlessApplicationEnabledOptions` 接受可选的
`certificateRenewal.run()` capability。它只返回 ADR-0061 的低敏续期结果，不取得 CA
私钥、部署 Secret、listener 或数据库。

`runProductionWorkerProcess` 提供可选 `createCertificateRenewal(config, credentials)`
factory，让具体 Worker Profile 把 cert-manager、Vault、SPIFFE 或离线签发 adapter 与同一
证书目录组合。默认 CLI 未配置 adapter 时不构造 coordinator、不加载 enrollment PKI、
也不增加任何后台活动。

### 2. 复用唯一 cadence，固定先证书后网络业务

启动顺序固定为：

1. 取得 journal owner 并完成有界 startup reconciliation；
2. 执行一次证书维护；
3. 只有 identity 可用时才注册 Worker Session；
4. 启动既有唯一 `unref` cadence。

每个 cadence 的顺序固定为 certificate maintenance → Session heartbeat → execution
supervision/Pull。并发 tick 继续由 application 和 renewal coordinator 各自 coalesce；
不新增 timer、watcher、Agent、socket、Pool、进程或 sidecar。

`not_due`、`renewed` 和 `backing_off` 继续业务；`retry_scheduled` 在旧证书仍有效时继续
业务并发出稳定的 `certificate_renewal_failed` diagnostic。issuer 原始错误、CSR、PEM、
路径和 token 不进入 diagnostic 或 process event。

### 3. 身份不可用必须本地失败关闭

续期抛错或返回 `unavailable` 时，production Session lifecycle 同时：

- 把 Session coordinator 置为 blocked，使 `current()` 不再向 execution plane 暴露可用
  Session，阻止新的 Pull；
- 把 capacity oracle 置零，阻止后续 heartbeat 宣告空闲容量；
- 发出 `certificate_unavailable` 低敏 diagnostic；
- 仍运行 execution supervision，使已有本地执行可以按 durable Lease 到期停止，而不是
  因证书失败永久逃逸监督。

本地安装新证书本身不能解除 fence。只有同一 Session 的后续真实认证 heartbeat 成功，
Session coordinator 才清除 blocked，capacity oracle 才重新 active。这样不会把“CA 已
签发”冒充“网络路径、服务端信任和业务 credential 均已恢复”。

### 4. 换证复用一个 Agent，但不能复用旧 TLS socket

credential provider 继续每请求读取 active generation。共享 HTTPS Agent 的 pool key 同时
绑定 certificate、private key 与 trust anchors；active generation 改变后，下一请求使用
新的 pool key 和 TLS socket，不创建第二个 Agent。Ingress trust reload 继续轮换 TLS
generation、关闭 idle connection，并拒绝旧 generation socket。

### 5. CA overlap 与 trust contraction 由部署编排

常驻 QingLong 控制面仍不持有 CA 私钥，也不开放匿名 CSR endpoint。标准轮换顺序为：

1. ingress 先信任 CA-A + CA-B；
2. Worker 通过外部 issuer 取得 CA-B 证书并原子切换 active generation；
3. 下一次请求使用新 pool key；
4. ingress 显式 reload，只保留 CA-B；
5. 证明 CA-A 旧证书被拒、CA-B 新证书被接受；
6. 同一 Worker Session/generation 继续 heartbeat、Pull、Lease 与 completion。

Edge 可省略 adapter，或用低频外部 maintenance/离线 ceremony 注入 capability；Cluster
节点可由 cert-manager、Vault、SPIFFE 或 Secret rollout controller 注入。两者共享相同
一次性协调语义和失败关闭策略，不为资源档位复制 runtime。

## 不采用方案

### 在 Worker 内再建续期 timer 或文件 watcher

拒绝。它会与 production cadence 竞争、增加 Edge 空闲资源，并在 Kubernetes 多文件
Secret 非原子更新时间窗读取混合材料。

### 由 cluster-control 在线签发 Worker 证书

拒绝。它把外部 transport 漏洞升级为设备根身份签发权，也混淆 transport possession 与
`ql3w`、Session、Lease 三层 authority。

### 续期成功后立即本地解除 Session fence

拒绝。证书可能尚未被 ingress 信任，网络或 credential 仍可能失败；恢复必须由真实
heartbeat 证明。

### 换证时重启 Worker 或创建第二个 Agent

拒绝。重启会扩大 Run/drain 恢复窗口，双 Agent 会增加 socket/RSS 并使旧证书连接的关闭
时点不清晰。credential-bound pool key 已能在单 Agent 内分离代际。

### 为 certificate lifecycle 新建 workspace package

拒绝。续期协调器、process composition、Session lifecycle 和 transport 已由同一 Worker
部署单元拥有；再拆包没有独立发布、authority 或 Profile 替换价值，只会恢复一文件一包。

## 影响

- workspace 保持 20 个 package；
- 不新增生产依赖、migration、表、角色、端口、listener、Pool、连接、timer、watcher、
  Agent、进程或 sidecar；
- disabled Worker 与未注入 CA adapter 的 Worker 保持零续期常驻成本；
- Edge/Node 继续只用同一个 runtime，通过现有 cadence/并发/页预算区分资源档；
- `ProductionWorkerSessionLifecycle` 增加可选 fail-closed capability；只有配置 certificate
  renewal 时才强制要求它，既有无续期 headless embedding 保持兼容；
- 外部 CA adapter、CA 私钥、Secret rollout 与 ingress reload authority 仍在部署层，不
  进入 Worker 或 Cluster 常驻业务入口。

## 验证

1. GitNexus 刷新后包含 35,661 nodes、81,415 edges、285 flows；upstream impact 中
   production headless composition 2 个直接调用者、production product root 0 个上游、
   process root 2 个上游、Worker Session coordinator 4 个上游、renewal coordinator 7 个
   上游，均为 LOW，未命中已知 execution flow。`detect-changes` 对 tracked compare 为 LOW、
   0 flow；Git 本身不会把尚未跟踪的 QL3 文件归入 compare，因此另以 strict 编译、入口
   测试、依赖审计和 live contract 补足；
2. Worker strict TypeScript closure check 通过；全量 132/132，覆盖启动前 identity
   unavailable 清理、单 cadence 顺序、
   unavailable fail-close、同 Session authenticated heartbeat 恢复和唯一 TLS Agent；
3. `test:worker-postgres-live:ql3` 在 Linux Node `24.18.0` 与 PostgreSQL
   `18.4 (Debian 18.4-1.pgdg13+1)` 上完成一次真实续期：issuer 调用 1 次，证书 SHA-256
   改变，ingress TLS generation 变为 2，CA-A 旧证书被拒，CA-B 新证书被接受；
4. trust contraction 后 Worker 保持同一 Session ID、generation 1，瞬时旧 socket 失败
   只产生有界 `session_tick_failed` diagnostic；后续真实认证请求恢复，无 Session replacement；
5. 最新一次同一合约随后完成 Offer→starting→running→67 次 Lease renew→31-byte Artifact→
   completion，Run/Attempt succeeded、Lease completed，并在运行中完成 `ql3w` credential
   A→B、A revoke、最终 drain/offline 与三个数据库角色权限断言；`gates.passed=true`；
6. 合约成功与失败路径均删除临时 PostgreSQL/Node 容器和私有证书目录，不保留 CA 私钥。
7. PostgreSQL 18.4 arm64 physical HA 独立复验 `remote_apply`、timeline 1→2、旧主先
   fencing、未确认分区写在晋升后不存在、`pg_rewind` 只读同步重入和两个 fresh control
   replicas，全部 gate `passed=true`；Worker/HA 临时容器与网络均已清理，既有
   `ql3-cnpg-evidence-control-plane` 未修改。

## 仍未完成

- cert-manager、Vault PKI、SPIFFE/SPIRE 或离线 CA 的正式 adapter/部署模板；
- Kubernetes credential/identity generation 与单节点 PVC rollout 已由 ADR-0239 完成；仍缺
  ingress reload controller、生产 RBAC、权限审计、CA overlap 分区与回滚；
- 证书到期、续期失败、blocked duration、TLS handshake 拒绝的 metric/alert；
- 真实 Kubernetes 多节点 CSI PVC detach/reattach、node loss 与 production 360 秒长 drain；
- TPM/PKCS#11/non-exportable private key provider；
- 固定 x64/arm64 路由设备的时钟跳变、断电、文件系统和资源门禁。