qinglong/docs/adr/ADR-0053-cluster-startup-recovery-convergence-gate.md

ADR-0053: Cluster Startup Recovery Source 与 Convergence Gate

• 状态：Proposed
• 日期：2026-07-19
• 关联 RFC：QL-RFC-0001 D-06、D-36 至 D-41、D-52

上下文

cluster-control 的激活顺序已经固定为 readiness → assembly → recovery → lifecycle → admission，但此前 reconcile() 的安全摘要完全由调用方提供。一个空实现可以直接返回 safe: true，bootstrap 没有独立的 PostgreSQL 事实可以复核。与此同时，直接扫描全部非终态 Run 既可能拖垮大库，也会把正常 queued/running 工作误判为启动遗留，使有业务流量的集群无法滚动扩容。

本决策只补齐“恢复候选发现与恢复后收敛证明”，不伪装成已经实现了修改 Run/Attempt 的生产 Reconciler。

决策

1. Recovery Source 是 runtime-core 端口

ClusterControlRecoverySource 接受 limit，返回由 durable source 自己选择的 observedAtMs、按稳定时间/身份排序的候选页与 hasMore。页大小硬上限为 128；实现不得内部递归翻页、执行 COUNT(*)、创建 timer、持有全表结果或导入 legacy SQLite recovery。PostgreSQL adapter 必须在同一条 statement 内用数据库 statement_timestamp() 冻结 observation，Pod 本机时钟和调用方输入都不能决定 lease 是否过期。

source 通过 ClusterControlAssemblyInput.recovery 暴露给后续真实 Reconciler。它只授予候选读取能力，不授予绕过 RunRepository fence 的状态修改能力。

2. 候选只表示失去有效 ownership 的工作

PostgreSQL source 只返回：

• 持久化停在 created 的 runtime-owned Run；
• 状态为 dispatching/running，但不存在 lease 仍晚于同一 observedAtMs 的 active Attempt 的 Run；
• 状态为 claimed/starting/running 且 lease 缺失或已经到期的 Attempt。

正常 queued、waiting_approval、retry_wait、lost 以及仍有有效 Attempt lease 的运行任务不是本副本的启动遗留，不得阻塞滚动扩容。终态 Run/Attempt 也不得进入候选。

该定义是保守的恢复入口，不是最终状态机裁决。真实 Reconciler 仍须通过 transaction、lease/fencing 和可信执行证据决定 lost、重试或终态，不能因候选出现就重放执行。

3. SQL 与索引都必须有硬读取上限

pg-0007-cluster-recovery-indexes 为 runtime-owned created/dispatching/running Run 和 active Attempt 建立部分索引；Attempt 索引以 lease expiry 开头。查询的 Run、Attempt 两个分支各自先 ORDER BY ... LIMIT limit+1，再合并并执行同一上限，因此一次调用最多从两个候选分支各取得 129 行，不会把全部 backlog 拉进 Node.js 内存。

schema capability 推进到 control-core v6，并增加 cluster_recovery: 1。reviewed migration、冻结 checksum manifest、Drizzle schema、catalog contract 和 readiness 必须 lockstep；runtime role 继续只使用既有 Run/Attempt SELECT 权限，不新增 DDL 或管理权限。

4. Bootstrap 独立复核恢复摘要

调用方 application stack 先执行自己的 reconcile()。只有它返回精确的 safe=true, remaining=0, failed=0，bootstrap 才使用独立 ClusterControlRecoveryConvergenceVerifier 以 limit=1 查询 PostgreSQL：

• 无候选且 hasMore=false：返回安全收敛；
• 存在候选：返回 safe=false，remaining 只是至少还存在多少项的低成本下界；
• source、数据库 observation 或 row contract 异常：抛出并让 activation fail closed。

因此调用方不能用一个恒真的摘要绕过数据库事实。未收敛或验证失败时不得启动 lifecycle、安装 /api/v3 admission 或让 /readyz 返回 ready，并按既有顺序停止 stack 和 Pool。

5. 当前仍不是完整生产恢复

本切片没有实现候选 claim、lease takeover、执行证据探测、状态推进、重试策略、告警或多副本 Reconciler lifecycle。当前默认 production application stack 仍不存在，run.get route 也仍未自动注册。只有后续恢复实现能处理所有候选并通过本 verifier，cluster Profile 才能继续进入 lifecycle/admission。

被否决的替代方案

扫描所有非终态 Run 并要求清空

拒绝。queued/等待/有效 lease 都是正常集群状态；这种门禁会使活跃集群无法扩容，并把启动时间绑定到业务 backlog。

用 COUNT(*) 返回精确 remaining

拒绝。激活只需要知道是否存在遗留。精确计数会在最坏时扩大数据库扫描和锁压力；低成本下界足以 fail closed，精确 backlog 应由异步指标维护。

信任 application stack 返回的 safe: true

拒绝。composition 回调不是数据库权威，空实现、遗漏状态或测试替身都可能在恢复未完成时开放 admission。

在 bootstrap 内直接把过期 Attempt 标记 lost

拒绝。候选发现不等于拥有状态推进 authority；未经 lease/fence、执行证据和 retry policy 裁决直接改状态可能制造重复执行或覆盖其他副本。

影响

正向

• 激活门首次能从 PostgreSQL 独立证明恢复摘要不是恒真占位；
• 正常活跃工作与真正失权遗留被明确区分，支持滚动扩容；
• 单次查询、单页内存和索引范围都有硬上限；
• edge/standalone 不引入 PostgreSQL source、额外 timer 或 cluster 依赖；
• capability/readiness 可以拒绝缺少恢复索引的旧 schema。

代价与未完成项

• 新增两个部分索引及 capability v6 migration；
• source 只提供候选，真实多副本恢复 claim/supervisor 仍需后续 ADR；
• lease writer 必须使用与 PostgreSQL observation 兼容的数据库时间语义，生产仍应监控数据库节点间时钟漂移；
• 需要 PostgreSQL 16/18 EXPLAIN/大 backlog 基准证明查询计划稳定使用部分索引。

验证

1. runtime-core contract test 证明 verifier 固定只请求一项并拒绝不一致页/非法 durable observation。
2. PostgreSQL adapter test 证明两个分支和合并层都使用 limit+1，并拒绝越界 limit、终态或畸形 row。
3. migration/manifest/schema/readiness tests 证明 capability v6、两个部分索引与冻结 checksum lockstep。
4. bootstrap test 证明 application 返回 false-safe 时仍不能安装 admission，并按 stack → Pool 关闭。
5. 正常 queued、等待状态和有效 lease 不进入 SQL 候选条件；过期或缺失 lease 才进入。
6. Node 22/24、PostgreSQL integration、edge import audit、cluster dependency audit 与 GitNexus detect-changes 继续作为合并门禁。