qinglong/docs/adr/ADR-0056-cluster-recovery-provider-registry-and-bootstrap-owned-convergence.md

ADR-0056: Cluster Recovery Provider Registry 与 Bootstrap-Owned Convergence

• 状态：Proposed
• 日期：2026-07-19
• 关联 RFC：QL-RFC-0001 D-05、D-06、D-25、D-37、D-39、D-42、D-52 至 D-55

上下文

ADR-0055 已规定只有 durable pre-start 事实或可信 not_running 证据才能推进 lost，但 processor 仍接受一个任意 evidence provider，cluster bootstrap 仍把 raw recovery source/claim/transition repository 交给 application，并相信 application 自己编排恢复。这个边界有三个问题：

1. application 可以使用 wildcard/default provider，把未知 Executor 当成某个已知实现；
2. provider 可以看到 recovery owner/token，或因 timeout 后被反复调用而积累无界悬挂探测；
3. application 持有 raw claim/mutation authority，bootstrap 只能事后 verifier，无法证明执行过受审的标准 recovery 链。

此外，LocalProcess、Remote Worker、Container 与 Kubernetes 的执行身份位于不同 authority。cluster-control Pod 上的 /proc 不能证明 Worker 节点上的进程状态，Worker offline、HTTP timeout 或 Kubernetes API 暂时不可用也不能证明执行已经停止。

决策

1. Provider registry 只做 exact executor-type 路由

runtime-core 提供有硬上限的 ClusterControlRecoveryEvidenceRegistry：

• 最多注册 32 个 provider，不接受 wildcard、重复或不规范 executor type；
• 每个 provider 必须声明至少一个 required identity 字段：workerId、executorHandle、pid、leaseToken；
• Run ID、Attempt ID、Attempt 状态、executor type 与 callback sequence 始终属于 probe target；
• 缺失 provider、缺失 required identity 或畸形 target 返回 identity_unverifiable，进入 manual，而不是尝试其他 provider；
• provider 注册时绑定 inspect capability，后续修改注册对象不能改变已安装 authority；
• provider 只收到冻结的 probe target、相对 timeout 和 AbortSignal，不接收 recovery owner、claim token/version，也不取得 start/stop/retry/completion capability。

provider 返回值被重新规范化，只允许 running | not_running | unknown(reason)。异常和 timeout 映射为 provider_unavailable；不合法结果映射为 conflicting_evidence。错误文本、transport detail 和 provider 私有字段不进入 disposition、事件或 wire response。

2. Timeout 不得制造无界 abandoned probe

每个 executor type 同时最多一个 provider inspection。默认 timeout 为 5 秒，硬上限 30 秒，timer 使用 unref，不会阻止进程退出。

timeout 后 registry 向 processor 返回 provider_unavailable 并发送 abort signal，但在底层 Promise 真正结束前保留该 provider 的 in-flight slot。后续同类 probe 直接返回 unavailable，不再启动第二个外部调用。这样即使 provider 忽略 abort 或永久挂起，每个 provider 也只保留一个 abandoned operation，不会按 candidate、pass 或 timer tick 无界累积。

registry dispose 会取消 timer、abort active provider，并让等待中的调用 fail closed；它不等待不合作的外部 Promise。

3. Provider budget 必须小于 recovery claim lease

cluster recovery 配置必须在打开 PostgreSQL 前验证：owner ID、claim page、lease、retry delay、provider timeout 和 startup pass 全部有硬边界。provider timeout 必须至少为 fenced mutation/settle 留出 250 ms，不能配置为等于或超过 claim lease。

该 250 ms 只是本地资源预算，不是 fencing authority。Pod wall clock 和 provider deadline 都不能证明 claim 有效；probe 返回后仍必须由 PostgreSQL statement time 重新锁定 owner/token/version/expiry fence。

4. Core Run recovery 由 bootstrap 拥有

cluster-control bootstrap 在 readiness 后自行构造：

PostgreSQL source → claim repository → provider registry → evidence processor → resolution repository → supervisor → startup coordinator → convergence verifier

业务 application 不再收到 raw PostgreSQL Pool、recovery source、claim repository 或 transition repository，只能消费受审领域 port。标准启动顺序为：

1. 用只读 limit=1 verifier 预检；没有遗留时不创建 claim、不写 recovery control；
2. 有遗留时运行有限多轮 supervisor，默认最多 8 轮、硬上限 64 轮，每轮仍只有一页且页内串行；
3. 任一 retry/manual/fenced/store failure 立即保持 unsafe，不运行 application recovery；
4. core Run recovery 安全后才运行 application 的其他受审 reconciliation；
5. application 自报安全后再用独立数据库 verifier 复核，之后才能启动 lifecycle 和 admission。

startup coordinator 没有 timer、递归分页、全表 backlog 或并行 provider fan-out。pass budget 耗尽时返回最后一个 remaining lower bound，不能伪报收敛。

5. Profile 与执行位置必须匹配

registry/coordinator 位于无 driver 的 runtime-core，PostgreSQL repository 与默认装配只存在于 cluster-control artifact。edge/standalone 不引入该路径，继续使用各自 SQLite recovery lifecycle。

不得把现有 Linux /proc LocalProcess inspector 直接注册到 cluster-control，因为它只能观察当前 Pod/主机，不能证明远端 Worker 的执行。生产 provider 必须按执行位置分别实现：

• Remote Worker：认证 transport、Worker session/generation、Run lease、offer/callback sequence 与 Worker durable receipt/identity；
• Kubernetes：cluster/namespace/Pod UID/container ID 或 Job UID/resourceVersion 的精确绑定；
• Container：daemon identity、container immutable ID 与宿主 authority；
• LocalProcess：只允许在实际执行该进程且持有 durable boot ID/PID/start ticks 的同一节点 Profile 使用。

被否决的替代方案

未知 Executor 使用 default provider

拒绝。默认 provider 会把新增插件 Executor 静默纳入旧证据语义，形成权限与副作用旁路。未知类型必须 manual，直到注册专用 provider。

Timeout 后释放 slot 并立即重试

拒绝。AbortSignal 不是强制取消；不合作 provider 仍在执行，按 pass 重试会造成连接、Promise 和远端请求无界堆积。

继续让 application 持有 claim/transition repository

拒绝。业务 stack 不需要恢复协调 authority；它会允许绕过 registry、标准 processor 或 pass budget，并迫使 bootstrap 仅依赖事后检查。

cluster-control 直接读取本机 /proc 判断 Remote Worker

拒绝。PID namespace、boot identity 和进程位置不匹配；“本机没有该 PID”对远端执行没有任何负证据意义。

影响

正向

• 未知 Executor、缺失身份和 provider 漂移默认 fail closed；
• provider 看不到 recovery claim capability，也无法通过 registry 调用执行副作用；
• 慢/失控 provider 的在途数量和 timer 数量有固定上限；
• normal startup 只做一次只读候选点查，不产生 recovery control 写放大；
• core Run recovery 不再依赖 application 自选实现，admission 前的标准链可由真实 PostgreSQL 集成测试证明；
• application assembly 的 authority 面缩小，edge/cluster 依赖方向不变。

代价与未完成项

• enabled cluster-control 现在必须显式提供 recovery owner/config；
• executor provider 缺失时 active Attempt 会进入 manual 并阻断 admission，这是安全默认值；
• 仍需 Remote Worker/Kubernetes/Container 的真实认证 provider，当前 registry 不等于这些证据已存在；
• ADR-0057 已补齐 Remote Worker provider 所需的 PostgreSQL Session/Run Lease 精确 authority 与 Attempt fence 投影，但认证 attestation ingress/provider 仍未实现，session offline 或 lease expiry 仍不得当作 not_running；
• application 其他领域仍使用一个通用 reconcile seam，后续应演进为受审 reconciler registry 与各自 verifier；
• 仍需持续 lifecycle、指标/告警、manual recovery API、PostgreSQL lost-retry/cancellation 协调和大 backlog/failover 基准。

验证

1. runtime-core contract test 覆盖 exact routing、required identity、claim capability 隔离、注册后 mutation 隔离、异常/畸形输出、timeout、single-flight abandoned probe、dispose 和配置硬上限。
2. startup coordinator contract test 覆盖多页收敛、retry/manual 立即停止、pass budget exhaustion 与畸形 summary fail closed。
3. cluster-control test 证明无候选时不打开 repository connection，配置错误在 PostgreSQL 前拒绝，core recovery 不安全时不调用 application reconcile/admission，stop 会释放 registry。
4. PostgreSQL 16–18 三角色 CI 通过真实 bootstrap 证明未启动 aggregate 在 application/admission 前原子 lost，execution lease 保留、双事件有序且最终 verifier 为空。
5. Node 22/24 package test、edge import audit、cluster dependency audit、frozen lockfile 与 GitNexus detect-changes 继续作为合并门禁。