qinglong/docs/adr/ADR-0124-recoverable-worker-credential-delivery-and-overlap-rotation.md

# ADR-0124：可恢复的 Worker Credential 交付确认与重叠轮换

- 状态：Proposed（共享 contract、协调器、PostgreSQL v1/v2/v3/v4 delivery ledger、capability v15 discard tombstone、有界恢复、PostgreSQL 16/18 四角色、PostgreSQL 18 physical promotion 下 v1/v2/v3/v4 COMMIT-response-loss、受控复制链分区与旧主 rewind/rejoin、POSIX adapter 与 Kubernetes resourceVersion CAS adapter/单 API server RBAC 证据已实现；生产 operator/proxy TLS、基础设施 STONITH、真实 Pod/raw-wire 分区与管理产品入口尚未完成）
- 日期：2026-07-23
- 关联 RFC：QL-RFC-0001 D-23、D-59、D-60、D-121、D-122
- 关联 ADR：ADR-0050、ADR-0058、ADR-0060、ADR-0061、ADR-0122、ADR-0123

## 背景

Cluster Admin 已能在 PostgreSQL 中原子写入 Worker credential、mutation 与 security audit，并且只在新建
mutation 时返回一次 `ql3w` token。精确重放返回 `token: null`，数据库也只保存 HMAC digest。这个边界避免
服务端长期保存 bearer secret，但还不能直接成为生产部署 ceremony：

1. 数据库提交成功后、token 发布到 Worker Secret 前崩溃，会留下无法从数据库恢复的有效 credential；
2. 对同一 credential ID 执行 `rotate` 会立即令旧 version 失效，发布失败会同时失去旧、新两个可用 token；
3. “Secret 已写入部署系统”不等于 Worker 已实际使用新 credential 完成认证；
4. 401/403 后由 Worker 自助签发会绕过管理 Policy、强认证、audit 与 version fence。

因此，生产轮换必须把一次性 secret 的暂存、数据库事实、部署发布、Worker 观察确认和旧 credential 撤销组成
可恢复状态机。现有一次性签发 service 继续作为短生命周期低层 authority，但不得直接暴露为远程产品入口。

## 决策

### 1. 产品轮换使用新 credential ID 和重叠有效期

生产 issue/recovery 每次创建新的 credential ID；不得用同 ID 的新 version 原地替换正在工作的 token。
旧 credential 在以下两个事实都耐久成立前保持 active：

- deployment adapter 已确认 exact mutation/token generation 原子发布；
- Cluster ingress 已用新 credential ID/version 认证同一 Worker，并在 Session heartbeat/transition 事务中写入
  credential observation acknowledgement。

确认后才能以独立 mutation 撤销旧 credential。确认超时只告警和停止收敛，不得提前撤销旧 credential，
也不得让 Worker 自动创建新 Session。新 credential 可在受限 overlap 窗口内与旧 credential 并存；同一
Worker 可以持有多个 credential ID，但每个 ID 仍只有一个当前 version。

### 2. Secret 必须先耐久 stage，再提交 credential

`@qinglong/cluster-admin` 定义 delivery port，不新增 package。生产 coordinator 的顺序固定为：

1. 生成 token，并以 mutation ID、credential ID、Worker ID、token digest 和目标 generation 调用
   `stage`；adapter 必须 no-replace、私有/加密、有界并可在进程重启后按 mutation ID 恢复；
2. 在 PostgreSQL 中原子 append credential、mutation 与 allowed audit；
3. 调用 adapter 将 exact staged generation 原子发布到部署目标；
4. 写入 delivery-published acknowledgement；
5. 等待同一 Worker Session 事务写入 authenticated observation acknowledgement；
6. 两类 acknowledgement 都成立后，提交旧 credential revoke mutation。

token 只能在 stage/publish adapter 的受限 secret boundary 内出现；命令 JSON、HTTP response、Session wire、
日志、metric、audit 与 PostgreSQL 行都不得包含 token。adapter 必须复制需要保留的 bytes，调用方在 stage
返回后立即清零自己的 Buffer。

### 3. PostgreSQL ledger 只保存低敏恢复事实

新增 append-only delivery ledger，至少绑定：

- mutation ID、new/previous credential ID、new credential version、Worker ID；
- staged token digest、deployment target digest 和 generation；
- `staged`、`credential_committed`、`published`、`observed`、`previous_revoked` 各阶段的时间与 fence；
- 发布 acknowledgement、认证 observation 的主体/Session/version 摘要；
- recovery attempt 的低基数结果和 security audit event ID。

ledger 不保存 token、私钥、证书、Authorization header、Session lease token 或 deployment provider
credential。阶段推进使用 expected-state/version CAS；同 mutation 的 exact replay 返回已有低敏状态，语义漂移
或同 generation 不同 digest 一律 fail closed。

### 4. Recovery 是显式、无 timer、可分页的短生命周期操作

恢复器由受审管理 CLI/API、部署 controller reconcile 或运维命令显式驱动，不在 Worker/Cluster control
常驻进程新增 timer。每次只处理有界页，并按事实执行：

- 只有 staged、数据库无 mutation：先提交数据库 cleanup authorization，再清除 staged secret；
- credential 已提交但未发布：从 exact staged record 重试发布；
- 已发布但未 observed：保留新旧 credential，等待 Session cadence 或发出告警；
- 已 observed 但旧 credential active：提交独立、可重放的 revoke；
- digest、target、Worker、Session 或 version 漂移：进入人工审查，不自动覆盖 Secret 或撤销旧 credential。

数据库结果不确定时不得删除 staged secret；部署发布结果不确定时必须 inspect exact generation 后再裁决，
不得盲目重写。所有清理都要求 ledger 终态和最小保留期。

#### 4.1 全局 orphan 清理采用数据库 tombstone，不以单次 absence 作为删除证明

部署目录的有界扫描只能发现候选 stage，不能直接授予删除权限。`resolveDelivered(deliveryId) = null`
与一个尚未提交完成的 issuer 可以同时成立；扫描器若据此删除，会让随后成功的 credential commit 永久失去
对应 token。因此 capability v15 新增 append-only cleanup ledger，并遵守同一 `deliveryId` 上的
单赢家协议：

1. cleanup coordinator 读取并规范化低敏 stage intent；
2. PostgreSQL 事务获取 `ql3-worker-credential-delivery:<deliveryId>` advisory transaction lock；
3. 在同一事务内重新检查 mutation、delivery 与既有 cleanup 记录；只有前两者均不存在时，才插入绑定
   delivery ID、Worker、credential、token digest、target digest、generation 与数据库时间的 v1
   `discard_authorized` tombstone；
4. `commitDelivered` 在插入 credential/mutation/delivery 之前获取同一把 delivery lock，并在 tombstone
   已存在时 fail closed；由此数据库 commit 与 orphan cleanup 只能有一个赢家；
5. coordinator 只有拿到 exact committed authorization 后，才调用 adapter 的 exact `discard`；删除成功或
   已证明文件不存在后，再以 expected-version CAS 追加 v2 `discarded`；
6. authorization 响应丢失时从 ledger 精确恢复，discard 响应丢失时用 adapter `inspect` 重放；任何 intent
   语义漂移、数据库不可用、锁结果不确定或未知目录项都进入人工审查。

tombstone 一旦写入不得撤销或复用该 delivery ID。全局恢复分别分页读取 deployment stage inventory 与未完成
cleanup ledger，不引入常驻 timer。POSIX adapter 仍只承担受控单写者文件语义；Kubernetes 多 Pod 由独立
resourceVersion CAS adapter 提供部署侧并发协议，并必须再通过真实 API server/RBAC 故障矩阵才能成为生产证明。

### 5. 认证观察复用现有 Session，不增加 Worker authority

Cluster authenticator 已产生 `credentialId`、`credentialVersion` 和 `authenticationId`。Session heartbeat 或
transition 在验证 Worker/Session/version fence 后，将这一低敏 principal identity 与 delivery ledger 关联；
不增加新的 Worker 写路由，也不接受 Worker 自报 credential ID/version。新 token 被部署后，现有
`WorkerProductionCredentialProvider` 在下一次请求读取它，coordinator 在同一 Session 上恢复 heartbeat。

401/403 只暂停 Pull 并触发外部运维信号；Worker 不能调用 issue/recover/revoke。409 继续按 Session fencing
处理，不能被 credential recovery 掩盖。

## 被否决的替代方案

1. **数据库提交后再直接写 Secret**：保留不可恢复的 commit-to-publish 崩溃窗口。
2. **同 credential ID 原地 rotate**：交付确认前旧 token 已失效，容易把 Worker 永久锁出。
3. **数据库保存可解密 token**：扩大 cluster 数据库泄露面，并混合 credential authority 与 delivery authority。
4. **只以 Secret provider 的写成功作为完成**：无法证明 Worker 实际读取并通过新 credential 认证。
5. **Worker 收到 401 后自动签发**：绕过管理权限、强认证、审计、审批与撤销策略。
6. **为每个 Worker 增加续期 timer/watcher**：放大路由设备常驻成本，并与 D-121 单 cadence 冲突。

## 实现 Gate

1. 定义 exact delivery port、低敏 ledger contract、错误分类和 crash matrix；实现进程内 fake adapter 测试。
2. 增加 PostgreSQL migration/repository，验证双连接 CAS、事务重试、commit response loss 和有界 recovery page。
3. 在 Session heartbeat/transition 同事务写 authenticated observation，验证 credential/Worker/Session/version 漂移。
4. 至少实现一个真实部署 adapter，并证明 no-replace、inspect-before-retry、原子发布、权限与容量上限。
5. 覆盖 stage 前后、DB commit 前后、publish 前后、observation 前后和 revoke 前后的进程终止矩阵。
6. 验证低配 Edge 不新增 timer/socket/数据库，Cluster Worker 只复用现有 Session cadence 与 mTLS Agent。
7. 完成 Gate 前保持 `Proposed`，不得把低层一次性 token 返回接口暴露为常驻远程管理 API。

## 当前实现证据

1. `@qinglong/runtime-core/worker-credential-delivery` 已定义 exact `DeliveryIntent`、append-only
   `DeliveryRecord`、credential commit/publication command、错误分类与 repository port。intent 不携带
   `credential_committed` 假事实；record 强制 v1 committed → v2 published → v3 observed → v4
   previous-revoked 的连续证据和时间单调性；discard contract 另以 exact stage intent 绑定 v1
   `discard_authorized` → v2 `discarded`，不把单次文件 absence 当作删除权限。
2. `@qinglong/cluster-admin/worker-credential-delivery` 已实现无 timer 的 stage-before-commit coordinator：
   复用既有强 Principal、HMAC、credential mutation/audit service，禁止构造一次性返回 token；token Buffer
   在 adapter 返回后清零。覆盖正常发布、publish failure、publication ledger 响应丢失、孤儿 stage 清理、
   raw mutation/missing stage/语义漂移 fail-closed 与同 ID rotation 拒绝。
3. `pg-0015-worker-credential-delivery-ledger` 将 `control-core` 推进到 capability v14，新增一张 append-only
   `worker_credential_deliveries` 表；admin 与 worker-ingress 仅获 select/insert，runtime 零权限。Drizzle、
   schema contract、冻结 checksum、readiness 和四角色权限保持一致。
4. `PostgresWorkerCredentialAdministrationRepository.commitDelivered()` 在同一 SERIALIZABLE transaction 中
   写 audit、credential、mutation 与 delivery v1；`markPublished()` 只 append v2。读取会验证完整 v1→vN
   连续历史、不可变字段和累计证据，覆盖 COMMIT response loss、publication replay、gap 与历史改写。
5. Worker Ingress pipeline 只把 authenticator 产生的 Worker/credential identity 交给
   `AuthenticatedWorkerSessionRepository`，不接受 Worker body 自报 delivery 或 credential。PostgreSQL
   heartbeat/transition 在更新 Session 的同一 transaction 中读取并验证 append-only credential delivery 历史：v2 published
   才 append v3 observed；v1 未发布会回滚 Session 更新，v3/v4 精确重放不重复写，非 delivery legacy
   credential 保持兼容。按 credential lookup 的 partial unique/indexed path 已纳入同一 reviewed migration。
6. `listRecoveryPage()` 使用 PostgreSQL statement observation、delivery ID keyset cursor、64 条硬上限，
   只返回 v1 committed、v2 published 与携带 previous credential 的 v3 observed；v4 和无需撤销的 v3 不再
   占用恢复页。`WorkerCredentialDeliveryRecoveryService` 是显式、无 timer 的短生命周期协调器：v1 复核
   exact stage 后发布并 append v2，v2 等待认证观察，v3 用 delivery ID 派生的 domain-separated mutation
   原子提交旧 credential v2 revoke、audit、mutation 与 delivery v4。所有时间取自恢复页的 PostgreSQL
   observation，不使用管理节点本地时钟；响应丢失通过确定性 mutation 与终态移出恢复页收敛。
7. PostgreSQL 16 临时真库已用独立最小权限 `ql3_admin` 与 `ql3_worker_ingress` Pool 贯通 v1 commit、v2
   publication、Session heartbeat 同事务 v3 observation、恢复页与 v4 revoke，并在 v4 的 COMMIT 已成功但响应
   丢失后精确收敛；21 项 integration 中 20 pass，只有未配置独立 runtime URL 的既有测试 skip。该测试同时
   揭示并修复了 worker-ingress 对 append-only delivery ledger 使用 `FOR UPDATE`、与既定 `SELECT+INSERT`
   权限冲突的问题；现由既有 Worker Session 行锁串行化 observation，不扩大 ingress 权限。
8. `@qinglong/cluster-admin/worker-credential-file-delivery` 在既有 package 内提供首个真实 POSIX adapter，未新增
   package、依赖、timer、socket 或数据库。adapter 绑定 stage/target 目录 owner、mode、device 与 inode；stage
   采用单一 bounded 私有文件、`O_NOFOLLOW`、fsync 与 hard-link no-replace，target 使用 previous credential ID
   fence、durable operation lock、`0600` 临时文件、rename 原子替换、目录 fsync 与发布后重读。publication digest
   绑定 delivery、credential、generation、target 与 token digest，响应丢失可由目标文件精确重放。stage root
   最多 128 项，keyset page 最多 64 项且只返回低敏 intent；不确定临时文件、未知条目、权限/目录身份漂移、
   非预期目标代际与锁竞争均 fail closed。该 adapter 已与 stage-before-commit issuer 贯通，Worker token 文件
   与现有请求时惰性 credential provider 格式兼容。
9. `pg-0016-worker-credential-stage-discard-ledger` 将 `control-core` 推进到 capability v15，新增无 delivery FK
   的 append-only `worker_credential_stage_discards`：admin 只有 `SELECT+INSERT`，runtime 与 worker-ingress
   零权限。authorization 与 credential commit 对同一 delivery ID 复用 advisory transaction lock；前者在
   同一 SERIALIZABLE transaction 内重查 mutation/delivery 并追加数据库计时 tombstone，后者在写入前重查
   tombstone，因此只能有一个赢家。短生命周期 cleanup service 分别有界分页扫描 deployment inventory 与
   未完成授权，只有 exact authorization 才 discard，随后追加 v2；响应丢失通过 ledger/inspect 收敛，语义
   漂移 fail closed。PostgreSQL 16 两个独立 admin Pool 的真实竞态已证明 commit/discard 恰有一个赢家，并
   验证赢家重放和永久 fence。
10. `@qinglong/cluster-admin/worker-credential-kubernetes-delivery` 在既有 package 内实现多写者部署 adapter；
   ADR-0239 又把 target digest v2 扩展为绑定 cluster identity、namespace、Secret name/data key 与 exact
   Recreate Deployment。每个 delivery 使用 deterministic name 的 immutable Secret；目标 Secret create/replace
   必须回传 GET 的 opaque `resourceVersion`，随后 Deployment 也以独立 GET `resourceVersion` 推进 PodTemplate。
   409 只在
   重读结果与 delivery/generation/token digest 完全一致时视为响应丢失重放，否则 conflict；discard 使用
   UID + resourceVersion delete precondition，并在 404 后重读 absence。inventory 单次最多读取 129 条、超过
   128 或出现 Kubernetes continue token 即 fail closed，再转换为领域 delivery ID keyset/64 条页；无 watcher、
   timer、cache 或新 package。fake API 双 rotation 竞态先证明同一 resourceVersion 只有一个赢家；随后固定
   `rancher/k3s:v1.34.3-k3s1`（arm64，digest `sha256:71abd3a56f57884c62732e0e0d87606052cb5f8555b7db7e8e33c04570b8175c`）
   的真实 API server 使用 10 分钟专用 ServiceAccount 重跑通过。RBAC 仅允许 Secret get/list/create/update/delete，
   明确拒绝 watch/patch 与 ConfigMap get；官方 client 实际完成双 rotation 单赢家与带 UID/resourceVersion 的
   orphan delete。HA control-plane failover、list compaction 与多 namespace 隔离仍待验证。client 精确固定 1.4.0，其历史依赖通过根
   override 收敛到 `form-data@4.0.6` 与 `js-yaml@4.3.0`，QL3 production vulnerability audit 为零 high/critical。
11. 当前验证：runtime-core 161/161、Cluster Admin 默认 37 tests 中 36 pass/1 real-API skip，且上述 real-API
   integration 显式启用后 1/1 pass；ADR-0239 后 fake adapter 定向 8/8，并在真实 K3s CoreV1/AppsV1 API
   完成双 Secret/Deployment CAS 与 Recreate/PVC Gate。Cluster PostgreSQL 105 tests 中 104 pass/1 external
   skip、Cluster Control 131 tests 中 129 pass/2 external skip；全量 23-package build/test、cluster dependency、
   Edge import 与六种 Profile artifact audit 均通过。当前 workspace 为 21 importer；最大常驻 application 为 2502983 bytes、413 files、
   72 loaded modules、12435456 bytes 单次 RSS delta，仍低于 4 MiB/512 files/16 MiB 门禁。本机 arm64 PostgreSQL 18 四角色 integration 23/23、cluster-control 6/6 已通过，并修正 CI 中随 v15 漂移的 admin/worker-ingress 最小 GRANT；前者补充 active query 连接失效的精确 availability 分类，后者以真实 idle backend terminate 验证 active admission 摘流；真实多 Pod credential/Session replacement 并发矩阵、stale lock/temp 显式修复、Kubernetes HA
   control-plane/failover、管理产品入口和固定物理设备证据仍是 Gate；不能把单 k3s API server 的
   resourceVersion 竞态或 PostgreSQL 单赢家结论扩大为生产多控制面发布证明。
12. `pnpm test:postgres-ha:ql3` 已在 `postgres:18`（18.4、arm64）两个独立数据卷和物理 replication slot
    上完成 credential delivery 的 v1 credential commit、v2 publication ledger、v3 authenticated Session
    observation 与 v4 previous credential revoke 四个独立 COMMIT-response-loss 窗口。每次都在 driver
    确认 `COMMIT` 后终止该 transaction backend，使调用方看到 unavailable/`ECONNRESET`，并在 promotion
    前从 standby 依次复验 `[1]`、`[1,2]`、`[1,2,3]`、`[1,2,3,4]`。timeline 1→2 promotion 后仍只有
    4 条连续 ledger、3 条 credential history、3 条 mutation/audit；stage、publish 与 entropy 各只发生
    1 次，旧 credential 精确为 `active → revoked`，恢复页为空，PostgreSQL 相关领域行不含 `ql3w` token。
    该故障注入位于 PostgresClient 边界，不代表 raw-wire packet-loss、网络分区或生产 Secret provider
    的响应丢失证明。