# ADR-0108：Worker Pull Placement 与摘要化 Execution Offer

- 状态：Accepted
- 日期：2026-07-22
- 关联 RFC：QL-RFC-0001 D-05、D-23、D-57、D-103、D-107
- 关联 ADR：ADR-0012、ADR-0013、ADR-0014、ADR-0057、ADR-0058、ADR-0104、ADR-0109

## 背景

QingLong 3.0 的 Worker 既可能是只有少量内存、连接不稳定且位于 NAT 后的路由设备，也可能是数据中心中的集群节点。PostgreSQL 已经拥有 Worker Session、Run Lease、不可变 `remote_worker` execution revision 和最小权限 Worker ingress，但此前仍缺少集群侧 candidate、Placement 与 offer 恢复闭环。

若控制面主动维护每节点推送队列、常驻 stream 或进程内 delivery timer，会把节点数量直接转换成控制面连接、timer 和恢复状态；若先把 `ExecutionSpec` 发给 Worker 再领取，又会让未获 Run Lease authority 的节点看到甚至执行任务。Run Lease 只保存 token digest 时，还必须解决 claim 成功但 HTTP 响应丢失后的安全恢复，不能把明文 bearer token 写回数据库。

## 决策

### 1. 首个集群分发协议采用认证 Worker Pull

已经建立 Session 的 Worker 主动向独立 Worker ingress 请求 offer。请求必须绑定 transport principal、当前 `workerId/sessionId/generation`，并携带：

- Worker 生成的稳定 `offerId`；
- 至少 256 bit 熵的不透明 `leaseToken`；
- 精确的 session generation。

transport 不信任请求体自报身份，必须先认证、授权和写低敏安全审计，再调用注入的 offer port。响应不得回显请求中的 token；Worker 已持有该 capability。没有注入 offer service 时入口返回 unavailable，不能临时从 handler 构造数据库 adapter。

Pull 不要求每个 Worker 一个服务端 timer、队列、长连接或内存 mailbox。低配设备可按自身网络与功耗预算退避轮询，集群节点可用更多并发的短请求扩展吞吐；两者共享相同 protocol 和硬上限。

### 2. Placement 是不可变执行修订的一部分

`qinglong/command@v1` 可声明有界 `placement`。发布 enabled cluster Task 时，compiler 把 normalized Placement 写入不可变 execution revision；未声明时自动要求 `remote-worker` executor。旧 execution revision 没有该可选字段时仍按原 digest 读取，禁止 migration 静默改写历史摘要。

WorkerCapabilities 与 Placement 都拒绝未知字段、重复项、控制字符、超限集合和非法 semver。能力 JSON 必须是规范化字节及其精确 SHA-256，required 条件全部满足后才可领取；preferred 只产生确定性 score。mismatch 只返回低基数类别，不持久化完整标签或 Secret。

### 3. Candidate discovery 使用数据库时钟和有界 keyset

PostgreSQL candidate source 只读取：

- runtime-owned、未取消、`queued|dispatching` 的 Run；
- 最新且仍为 `claimed`、executor 为 `remote_worker` 的 Attempt；
- 没有 Run Lease、已释放 Lease，或按 PostgreSQL `clock_timestamp()` 已过期且尚未启动的 Lease。

结果按 priority DESC、FIFO 和稳定 identity 做 keyset 分页，查询 `limit + 1` 后显式报告 truncated。单次 pull 默认最多读取 2×8 个 candidate、尝试 8 次 claim；硬上限分别为 16 页、64 条和 64 次。扩大集群吞吐通过更多无状态 pull 和数据库竞争完成，不通过无界放大单请求内存。

### 4. Run Lease 仍是唯一执行 authority

服务先读取 candidate，再读取请求 principal 对应的当前 Worker Session，校验 canonical capabilities、Session lease、状态和容量，解析 pinned execution revision 并执行 Placement。只有现有 PostgreSQL Run Lease repository 的原子 claim 返回 `claimed|idempotent` 才能构造 offer。

offer 精确绑定 Run、Attempt、Worker、session/generation、lease generation/version/expiry、offer ID、token digest、execution revision identity 和 content digest。任何 candidate、Session、Lease 或 revision fence 漂移都 fail closed。candidate 命中、Placement score、HTTP delivery 或 Worker 本地收包都不能代替 claim，也不能把 Run/Attempt推进到 starting/running。

### 5. 数据库只保存 token digest，重试从 authority 重建响应

claim 在进程内对 Worker 提供的 token 计算 SHA-256，数据库和 Event 只保存 digest。claim 响应丢失后，Worker 必须用完全相同的 `offerId + leaseToken + session authority` 重试。服务先查询 durable Lease 与 pinned execution revision，constant-time 比较 token digest，并在所有 fence 仍成立时重建同一个 offer。

因此不新增 `dispatch_offers` 表、明文 token outbox 或服务端 delivery queue。不同 token、不同 offer ID、替换 Session、过期/terminal Lease、Attempt 状态变化或 execution revision 漂移都返回 conflict；恢复不得创建第二条 Lease 或第二个 dispatch Event。

### 6. 保持 Profile、权限与包边界

该能力加入现有 `runtime-core`、`cluster-postgres` 与 `cluster-control` 子入口，不新增 workspace package。为让 Task 声明和 Worker capability 在写入/领取边界共享完整、可维护的 SemVer 语义，`runtime-core` 精确依赖 `semver@7.7.4`，而不是内置不完整解析器或再拆微包。它会给 edge/standalone 安装闭包增加约 268 KiB 文件，但 Profile import audit 必须证明 steady-state 入口不加载 `semver`，且总制品仍满足 4 MiB、512 文件和 16 MiB RSS delta 硬门禁；PostgreSQL adapter 与 cluster composition 则完全不得进入 edge/standalone 产物。

Worker ingress application 只依赖注入 port，不 import PostgreSQL adapter。runtime role 沿用已经受审的 Session/Lease/Run 读写权限；worker-ingress role 不获得 Run、Attempt 或 Lease mutation 权限。ADR-0109 已完成 starting/running/start-failure PostgreSQL 事务；后续 ADR-0231 已在认证 ExecutionSpec/Artifact transport 完成后，以同进程 capability port 将这些能力装入 production composition。

## 被否决的替代方案

1. **控制面主动为每个 Worker 推送**：需要每节点连接、队列、timer 和重连状态，不适合 NAT 后路由设备，也扩大多副本恢复面。
2. **先发送 ExecutionSpec，再由 Worker claim**：泄露未授权任务内容，并留下先执行后授权窗口。
3. **把原 token 存入 PostgreSQL/outbox**：数据库读取、备份或诊断泄漏即可获得执行 capability。
4. **只按 Worker ID 恢复 offer**：旧 Session 或攻击者可探测并接管已有授权；恢复必须证明同一 token capability 和完整 fence。
5. **新增 package 或 durable offer authority 表**：当前差异只是现有领域包的子入口和 Lease 派生视图，新增边界会复制版本、依赖和事实源。
6. **一次读取全部候选或 Worker**：会让单次请求内存随队列/节点规模增长，破坏 edge 和控制面过载门禁。

## 影响

正向影响：

- 路由设备和集群节点共享无状态、可退避的 pull 协议；
- 多副本只在 PostgreSQL 原子 claim 上竞争，不依赖进程内调度状态；
- 明文 token 不落库，丢响应仍可安全恢复；
- Placement 与 execution revision 一起固定，历史 Run 可解释；
- 没有新增 package、migration、常驻 timer、连接或 edge 运行时加载；代价是 edge 安装闭包增加一个受审的约 268 KiB SemVer 依赖。

代价与未完成项：

- Worker 轮询 cadence、jitter、服务端限流和大集群空轮询写/读放大仍需实测；
- 当前 pull endpoint 只有显式注入时可达，尚未默认装入 production cluster profile；
- delivery telemetry、Artifact/日志传输、Worker 本地 inbox 网络装配仍未完成；
- PostgreSQL `starting/running/start-failure` ACK 已由 ADR-0109 完成；completion、expiry/lost、cancellation 和 retry 仍需各自的原子事务，delivery 成功不得冒充这些事实。

## 验收证据

1. runtime-core 测试覆盖 canonical capabilities、required/preferred Placement、非法 semver、default `remote-worker` placement、candidate/page/offer fence 和 token digest 比较。
2. PostgreSQL repository 测试覆盖数据库时钟 candidate、priority/FIFO keyset、released/expired-unstarted 可见性和 active lease 隐藏。
3. cluster-control 测试覆盖有界扫描、Placement mismatch、原子 claim、同 token recovery、不同 token conflict，以及 ingress principal/session 绑定和响应不回显 token。
4. PostgreSQL 16.10 真实实例以独立 migration/runtime role 执行全部 migration 后，成功领取一次 offer；重放从 digest-only Lease 重建相同 offer，数据库中没有明文 token，且没有重复 Lease/Event。
5. 23 个 QL3 package、backend、cluster dependency 和 edge import/profile artifact 审计通过。ADR-0109 后六种本地 Profile 制品仍未在启动闭包加载 `semver`：edge 为 1,797,811 bytes、296 files、9,306,112 bytes RSS delta；最大 standalone-application 为 2,346,992 bytes、395 files，六档最大抽样 RSS delta 为 12,419,072 bytes，均低于发布硬门禁；QL3 production importer advisory 为 0 high/0 critical。
6. GitNexus 对已跟踪 diff 的 change detection 为 LOW、0 affected process；由于当前 QL3 孵化树仍是未跟踪文件，该结果不替代上述完整 build、test、artifact 和真实 PostgreSQL 证据。

## 后续门禁

ADR-0109 已实现 PostgreSQL starting ACK、running ACK 与 start-failure 原子状态推进；ADR-0231 又完成认证 ExecutionSpec/Artifact transport 之后的 Worker listener、生产进程/部署和 runtime ACK capability port。当前仍需补齐 Cluster Secret provider、expiry/lost/retry lifecycle 及多 Pod/failover 产品证据。