qinglong/docs/adr/ADR-0014-bounded-dispatcher-and-claimed-execution-offer.md

# ADR-0014：有界 Dispatcher 与 Claimed Execution Offer

- 状态：Proposed
- 日期：2026-07-18
- 关联：QL-RFC-0001、ADR-0012、ADR-0013

## 上下文

Run candidate、Worker 列表、Placement 结果、Run Lease 和 `ExecutionSpec` 已分别建立边界，但如果由 transport、定时器或 API 临时拼接，仍可能产生以下错误：

- 在 claim 前把命令、工作目录或资源策略暴露给未获授权的 Worker；
- 把 Placement 命中误认为执行权，导致多个 Dispatcher 重复下发同一 Attempt；
- 在路由设备上无界读取 Run、Worker 或构造大量 `ExecutionSpec`；
- 使用请求体中的 Worker 身份，而不是 Registry 中刚参与 Placement 的 session/generation；
- candidate 的 executor type、Placement 和 `ExecutionSpec` 身份不一致；
- claim 与消息发送之间的崩溃窗口没有被明确建模。

因此需要一个与 transport 无关、单次运行且有硬预算的应用层 Dispatcher，先稳定控制面授权顺序，再选择 HTTP、gRPC 或消息协议。

## 决策

### 1. Dispatcher 每次只执行一个有界周期

`RunDispatcher.dispatchOnce()` 不创建 timer，也不拥有后台生命周期。调用方负责调度下一周期。默认预算面向 edge：

- active lease recovery：每页 8 条，最多 2 页；
- candidate：每页 8 条，最多 2 页；
- Worker：每页 8 条，最多 2 页；
- claim：全周期最多尝试 8 次。

实现硬上限为 recovery/candidate/Worker 每页 64 条、页数 16、单周期参与 Placement 的 Worker 总数 64、claim 尝试 64。配置若使 Worker 页乘积超过 64，启动前直接拒绝。standalone 或未来 cluster-control 可以调高默认值，但不能绕过硬上限；扩展吞吐应通过更多短周期和数据库级公平性完成，而不是扩大单周期内存。

### 2. 授权顺序固定

每个周期严格执行：

1. 用同一个 `observedAtMs` 优先读取 active lease recovery；只有 Run 仍为 `dispatching`、Attempt 仍为 `claimed`、未取消、lease 未过期且 Worker session/generation 仍为当前 online/draining Session 时才可恢复；
2. recovery 没有可交付项后才读取第一页 candidate；没有 candidate 时不查询 Worker；
3. 有 candidate 后才按稳定 cursor 读取有界 Worker 快照；
4. 每次只调用 `RunDispatchPlanSource.prepare(candidate)` 构造一个 plan；
5. 对 `ExecutionSpec` 做共享领域校验、显式深拷贝和未知字段剥离，并验证 `runId/attemptId/projectId/taskId/taskRevision` 与持久化 candidate 完全一致；
6. 新 claim 的 Placement 必须包含 candidate 的 executor type；未声明时由 Dispatcher 加为 required，冲突时拒绝；
7. 按 Placement score、可用槽位和 Worker ID 确定性排序；
8. 使用所选 Registry record 的 Worker ID、session ID 和 generation 原子 claim；
9. 只有 lease recovery、`claimed` 或同一 capability 的 `idempotent` 结果才能生成 `ClaimedExecutionOffer`。

plan 可以在可信控制面内存中于 claim 前构造，但不得作为返回值、日志、Event、Trace attribute 或 transport 消息暴露。claim 失败、竞争丢失、无匹配节点或预算耗尽时只返回低基数状态和计数，不返回 `ExecutionSpec`。

### 3. Offer 是受 Lease 约束的内部 capability

`ClaimedExecutionOffer` 只包含：

- candidate 的有界身份和排序事实；
- 由 Attempt ID、lease generation 和 Worker session authority 派生的稳定 `offerId`、规范化 `ExecutionSpec` SHA-256，以及 `new_claim/lease_recovery` 来源；
- 目标 Worker 的 ID、session ID、generation；
- 已提交的 Run Lease，包括不透明 token；
- 清洗并深拷贝后的 `ExecutionSpec`；
- 新 claim 的 Placement score；恢复不依赖重新计算 score。

原始 lease token 和命令内容不得进入普通日志。offer 的消费者必须把它发送给完全相同的认证 Worker principal；不能改派给另一个 session，也不能以消息系统的 delivery ACK 代替 ADR-0013 的 starting/running ACK。

### 4. 分页与竞争 fail closed

- candidate 重复 Attempt、cursor 不前进或端口返回超页数据时拒绝本周期；
- recovery 重复 Attempt、过期 lease、非前进 cursor 或超页数据时拒绝本周期；
- Worker 重复、顺序倒退、truncated 页缺失前进 cursor 或总数超限时拒绝；
- Worker 在快照后失联或容量耗尽时，可以在全局 claim 预算内尝试下一个已匹配 Worker；
- Attempt 已被租用、变为不可领取或 claim CAS version 冲突时停止处理该 candidate，不对同一 Attempt 继续改派；
- 扫描或 claim 预算耗尽必须显式返回 `truncated` 和对应 reason，不能伪报为“没有任务”。

### 5. Run Lease 是恢复 authority，但不是 transport outbox

不新增与 Run Lease 并列的 `DispatchOffers` authority 表。已提交的 active Run Lease 已原子绑定 Attempt、Worker session/generation、lease generation/token 和 expiry；Dispatcher 重启后先从该事实有界恢复，并按 Run 中固定的 Project/Task/revision 重新 materialize plan。相同 lease generation 始终得到相同 `offerId`，因此 claim 提交后、首次发送前崩溃不必等待 lease 过期。

恢复只覆盖 Attempt 尚为 `claimed` 的窗口。Worker 已 ACK `starting` 后不再重发 `ExecutionSpec`；Worker 应重试 ADR-0013 的后续 ACK。取消、lease expiry 或 Session replacement 都立即取消恢复资格。plan 无法按原 revision 重建或 `ExecutionSpec` identity 漂移时 fail closed。

当前仍没有持久化 delivery attempt、网络发送或 delivery ACK。控制面可能在 starting ACK 前重复返回相同 offer。ADR-0021 已增加默认不可达的 Worker 本地持久化 inbox：按 `offerId` 幂等去重、拒绝同 ID 异 `ExecutionSpec` digest，并在 spawn 前写入 crash barrier。delivery ACK 仍只表示收包，不能代替 starting/running 事实。

ADR-0108 已为 PostgreSQL cluster 增加一个更窄的认证 Worker Pull 适配：Worker 自带稳定 `offerId` 与高熵 lease token，服务端用数据库时钟有界读取 candidate，只对该认证 Session 执行 Placement 和原子 claim；数据库仅保存 token digest，同一请求可从 durable Lease 重建丢失响应。该适配复用本 ADR 的授权顺序和预算，但不把 SQLite Dispatcher 的进程内 Worker 全表选择、控制面派生 token 或 transport 生命周期搬入 cluster。

生产 transport 必须另行决定：

- delivery attempt、退避、重连和可观测状态；
- 认证 transport 如何调用 ADR-0021 inbox，以及 journal 单 owner、retention 和恢复扫描；
- offer 未送达时主动 release 还是等待 lease expiry；
- Artifact 是否能按 pinned Task revision 确定性重建；
- token 的加密传输、内存生命周期和脱敏审计。

ADR-0109 已完成 PostgreSQL starting/running/start-failure ACK；在认证 ExecutionSpec transport、runtime 内部 port 和 Worker inbox 网络装配完成前，当前 Dispatcher/Pull port 必须保持默认生产不可达。

## 影响

正面影响：

- candidate discovery、Placement、claim 和 offer 的权限边界可独立测试；
- edge 无新增常驻 timer、连接或无界集合；
- Worker session fencing 来自持久化快照，不信任 transport 请求体；
- `ExecutionSpec` 的共享校验同时服务 LocalProcess 和未来 Remote Worker，避免两套规则漂移；
- cluster-control 可以复用同一应用语义，只替换 PostgreSQL Repository 和 transport。

代价与风险：

- plan 在 claim 前构造，昂贵的 Artifact 解析必须保持惰性和有界；后续可以拆成 claim 前 metadata plan 与 claim 后 payload materialization；
- 单周期公平性依赖 candidate keyset 顺序及外部 cadence，仍需多 Project/Quota 调度策略；
- starting ACK 前可能重复投递，transport 和 Worker 必须实现稳定 ID 去重与退避；
- SQLite 只能验证单控制面行为，不能证明多副本 claim 正确性。

## 未选择的方案

1. **先发送 ExecutionSpec，再由 Worker claim**：未授权节点能看到任务内容，并可能先执行后 claim。
2. **Placement 命中即更新为 running**：没有 Run Lease、starting ACK 或稳定 executor handle。
3. **一次加载全部 Worker 和 candidate**：在 edge 上失去内存上限，也放大集群热点。
4. **把 Dispatcher 直接写进 HTTP handler**：网络重试和身份字段会污染领域授权顺序。
5. **claim 成功后立即接入生产 headless runtime**：delivery、Artifact 和 ACK 恢复协议尚未完成。
6. **新建与 Lease 并列的 durable offer authority 表**：会复制 Attempt/Worker/lease 状态并引入双重真相；delivery telemetry 后续可以单独持久化，但不能取代 Lease authority。

## 验证要求

- 第一页无 candidate 时 Worker、plan 和 claim 调用次数均为 0；
- required/preferred Placement 选择正确 Worker，并用该 record 的 session/generation claim；
- candidate/Worker 跨页查找受预算限制，重复或不前进 cursor fail closed；
- 容量竞争可尝试下一 Worker，Attempt 所有权竞争停止当前 candidate；
- claim/扫描预算耗尽返回准确 reason 与 `truncated`；
- 无效或身份不一致的 `ExecutionSpec` 在 claim 前拒绝；
- 未 claim 的结果不包含 offer，序列化结果不能泄漏命令；
- `ExecutionSpec` 深拷贝，plan source 后续修改不能改变 offer；
- active lease 在新 candidate 前恢复，重启前后 `offerId` 相同；
- recovery 只接受 pinned Task identity、当前 Worker Session 和未过期 lease；取消或 Session replacement 后不再投递；
- recovery plan 缺失、revision 漂移、重复 cursor 和页数耗尽均显式 fail closed；
- Node 22、Node 24 全量回归通过；未来 PostgreSQL contract suite 覆盖多 Dispatcher 竞争。