qinglong/docs/adr/ADR-0055-cluster-recovery-evidence-and-fenced-lost-transition.md

ADR-0055: Cluster Recovery Evidence 与 Fenced Lost Transition

• 状态：Proposed
• 日期：2026-07-19
• 关联 RFC：QL-RFC-0001 D-03、D-06、D-18、D-25、D-26、D-42、D-52 至 D-54

上下文

ADR-0053/0054 已把失效 ownership 候选、有界 discovery、独立 recovery claim 和多副本 fencing 建立起来，但“取得 claim”只证明当前副本可以裁决，不能证明任务已经停止，更不能证明任务可以安全重放。尤其是 starting/running Attempt：执行 lease 过期只能证明控制面失去 authority，Worker、容器或外部执行器仍可能继续产生副作用。

另一方面，claimed Attempt 尚未越过 start barrier。只要持久化状态仍是 claimed 且 lease 已按数据库时间过期，就存在控制面内的 durable pre-start 证据，可以安全地把旧 Attempt 收敛为 lost，无需调用外部 provider。

本决策只补齐 recovery 的证据分类和 lost 状态推进，不创建下一次 Attempt、不排队、不调用 Executor，也不裁决成功、失败、取消或重试策略。

决策

1. 候选、claim、证据与 mutation 是四个独立边界

一次处理固定按以下顺序进行：

1. ADR-0053 source 只发现失去有效 ownership 的候选；
2. ADR-0054 repository 只授予短期、可接管的 recovery claim；
3. evidence processor 在 claim transaction 外重读 Run/Attempt，并只在必要时查询可信 provider；
4. resolution repository 重新锁定完整 claim fence、重读聚合并原子提交状态与事件。

任何一步都不得把前一步的结论扩大为任务执行 authority。外部 provider 调用期间不持有数据库连接、transaction 或行锁。

2. 证据矩阵必须保守且可枚举

持久化事实或外部证据	自动结果	理由
claimed、lease 已过期、未越过 start barrier	Attempt/Run lost	durable pre-start 事实证明没有被允许启动，不需要外部探测
starting/running、可信 provider 返回 not_running	Attempt/Run lost	精确执行身份的可信负证据证明当前执行不存在
starting/running、provider 返回 running	bounded retry	旧执行仍可能产生副作用，不能写 lost 或重放
provider provider_unavailable	bounded retry	暂时不可观察不等于任务不存在
provider identity_unverifiable 或 conflicting_evidence	manual	身份不完整或证据冲突不能靠自动重试消除歧义
execution lease 已恢复有效	resolved	当前快照不再是 recovery 候选
cancellation intent 未收敛	bounded retry	recovery 不越权替代 cancellation coordinator
created Run、缺失 Attempt、Run/Attempt 终态矛盾或未知组合	manual	聚合不满足安全自动转换前提

provider 必须接收绑定 Run/Attempt、Attempt 状态、executor type、Worker/handle/PID、execution lease 的精确目标。它只能返回 running | not_running | unknown(reason)，不得执行 start、stop、retry、completion callback 或任意外部 mutation。

3. Lost 转换权限必须窄于通用状态机

runtime-core 只提供 recovery 专用的纯 lost 转换：

• 仅接受 executionOwner=runtime；legacy owner 不可达；
• cancellation intent 存在时拒绝转换；
• claimed/starting/running Attempt 才能转 lost；
• dispatching/running Run 才能随 Attempt 转 lost；
• 已 lost Attempt 可驱动仍 active 的 Run 补齐 lost；
• 保留原 execution lease、Worker、handle、PID 和 callback sequence 作为审计证据；
• 按顺序产生 attempt.lost、run.lost，每步独立推进 Run version/event sequence，并使用稳定 dedupe key。

该 primitive 明确不创建 Attempt N+1、不改变 RetryPolicy、不推断 terminal completion、不调用 Executor。自动重试仍必须由 ADR-0026 的冻结策略、安全性声明和新 Attempt 协议负责。

当前 legacy transitionRun、transitionRunAttempt 与版本冲突链路具有 CRITICAL blast radius。为避免以 cluster 恢复切片暗中重写 2.x 状态机，本阶段不修改这些符号；将来只有在共享 contract、调用方迁移和回退门禁齐备后，才通过独立 cutover ADR 合并实现。

4. PostgreSQL mutation 必须在完整 fence 下原子提交

applyLost() 使用短 READ COMMITTED transaction：

1. 以 (target kind, target id, state=claimed, owner, token, version) 和 PostgreSQL statement time 校验 claim 未过期，并 FOR UPDATE 锁定 control row；
2. 在锁内重读 Run 与精确/最新 Attempt；
3. 与 provider 前快照比较 status、version、event sequence、ownership、cancellation、执行身份、lease、callback sequence 和关键时间；
4. 使用 Run/Attempt CAS 提交每个状态转换，并在同一 transaction 追加对应事件；
5. 任一 CAS、事件或存储步骤失败时回滚全部业务状态。

旧 owner、过期 claim 或 takeover 必须在读取和修改 Run/Attempt 前返回 fenced。快照变化返回 stale，由后续 discovery/verifier 重新裁决，不能套用旧证据。

业务 mutation 与 ADR-0054 的 control settle 故意不是一个 transaction：外部 processor 崩溃可能发生在 mutation 已提交、claim 尚未 settle 之间，但底层 Run/Attempt 已不再满足原候选，后续 verifier/discovery 会安全收敛；反向顺序会制造“claim 已 resolved、业务事实未落库”的危险窗口。

5. Profile 和资源边界不变

该 processor 位于无 driver 的 runtime-core；PostgreSQL transaction 实现只存在于 @qinglong/cluster-postgres，并由 cluster-control assembly 显式注入。edge/standalone 的依赖树、启动 importer、SQLite lifecycle 和资源预算不得因此引入 pg、Drizzle PostgreSQL、control table 或 cluster supervisor。

集群节点通过小页、短 transaction、页内串行和每项 claim fencing 控制单副本成本，再依靠多副本横向处理；不得用单个无界 leader loop、全表常驻缓存或跨 provider I/O 的长 transaction 换取吞吐。

6. 当前仍不开放生产 recovery

ADR-0056 已增加 exact-type、identity-declared、timeout/single-flight 有界的 production registry，并由 cluster bootstrap 默认拥有；但仍没有 Remote Worker、Kubernetes 或 Container 的真实认证 provider。LocalProcess、Remote Worker、Container 与 Kubernetes 必须分别证明什么是“精确身份”和“可信 not-running”，不能用通用 process missing、网络超时或 Worker offline 冒充负证据。

默认 startup 多轮 lifecycle、取消协调、lost 后 retry PostgreSQL adapter、指标/告警、manual recovery API/UI 和强认证审计也仍未完成。因此 cluster-control 仍不能因为本 ADR 的集成测试通过就宣称具备生产自动恢复或开放 mutation admission。

被否决的替代方案

Lease 过期一律写 lost 并自动重跑

拒绝。starting/running 已越过 start barrier，lease 只证明失权，不证明副作用停止；重放会产生 split-brain 和重复业务写。

Provider 不可用时按 not-running 处理

拒绝。观察系统故障与执行不存在是不同事实；前者只能 bounded retry，身份不可验证或证据冲突必须进入 manual。

外部探测后直接调用通用 Repository 多次写入

拒绝。探测期间 Run、Attempt 或 claim 都可能变化，缺少重新 fencing、快照比较和单 transaction CAS 会留下半转换聚合或让旧 owner 晚到覆盖。

Recovery processor 直接创建 retry Attempt

拒绝。lost 判定与 retry eligibility 是两种 authority。后者还需要冻结策略、次数预算、幂等/去重声明和 Attempt N+1 原子创建，不能由 evidence provider 决定。

影响

正向

• pre-start 与 post-start 使用不同证明标准，不把 lease expiry 当成统一死亡证明；
• 多副本旧 owner 在 probe 后仍无法越过 PostgreSQL fence；
• Run/Attempt/双事件要么全部提交，要么全部回滚；
• execution identity 与 lease 证据被保留，便于后续人工取证；
• runtime-core contract 可被不同 provider/数据库复用，同时保护 edge 安装与启动闭包。

代价与未完成项

• starting/running recovery 依赖每种 Executor 的可信 evidence provider；
• 暂时故障会保守 retry，歧义会进入 manual，可能延长 admission 阻塞；
• 状态 mutation 后、control settle 前存在可恢复窗口，需要 verifier 与指标证明最终收敛；
• 通用 legacy 状态机仍有重复实现，必须在单独高风险 cutover 中消除；
• 仍需 PostgreSQL 16/18 多 Pool、failover、provider 延迟/故障注入和大 backlog 资源基准。

验证

1. runtime-core contract test 覆盖 claimed 不调用 provider、可信 not_running、running/provider unavailable retry、身份不可验证/证据冲突 manual、有效 lease/stale/fence 和纯转换版本/事件语义。
2. PostgreSQL unit test 覆盖完整 control lock fence、快照重读、Run/Attempt CAS、双事件顺序、部分 CAS 回滚，以及失权后不读取/修改 Run。
3. PostgreSQL 13.3 真实集成测试证明未启动 aggregate 在无 provider/无重放下原子 lost；provider 返回后 claim 被另一副本接管时旧 owner 被 fence，Run/Attempt 保持不变。
4. Node 22/24 package test、cluster assembly test、edge import audit、cluster dependency audit 与 GitNexus detect-changes 继续作为本地门禁；正式支持结论仍以 Node 24.18+ 和 PostgreSQL 16/18 CI 为准。