qinglong/docs/adr/ADR-0012-remote-worker-session-placement-and-fencing.md

ADR-0012：Remote Worker Session、能力放置与 Fencing

• 状态：Proposed
• 日期：2026-07-18
• 关联 RFC：QingLong 3.0 Architecture RFC D-05、D-06、D-23，7.6、14.6、26.12

上下文

QingLong 3.0 既要运行在低内存路由设备上，也要支持多个控制面副本和异构执行节点。TCP 连接、gRPC stream、内存中的 Worker map 或裸 hostname 都不能同时解决以下问题：

• 控制面重启或水平扩展后恢复 Worker 存活和容量；
• 区分同一 Worker ID 的新旧进程，阻止旧进程继续心跳或提交完成；
• 在架构、Runtime、Executor、内存、磁盘、GPU 和标签不匹配时拒绝调度；
• 在小设备上保持固定的消息、候选页、timer 和内存上限；
• 区分“节点在线”与“某个 RunAttempt 已被原子授权执行”。

当前 next 已有 Run/Attempt 状态、LocalProcess Executor、durable cancellation fencing 和 Profile 边界，但没有生产可用的 Remote Worker transport。本 ADR 先稳定 Worker Session、Run Lease 和 Placement 边界，避免后续由 HTTP、gRPC 或数据库实现反向定义领域语义。

决策

1. 身份由认证传输绑定

控制面从 mTLS 证书、短期签名 token 或等价认证机制得到 WorkerPrincipal。请求体可以携带 workerId 供一致性校验，但不能自行建立身份。应用层使用绑定 principal 的 client；principal 与请求 Worker ID 不一致时在访问 Repository 前拒绝。

本 ADR 不选择 HTTP、gRPC 或消息队列。任何 transport adapter 在完成身份认证、授权、重放限制、消息大小限制和速率限制前不得暴露注册 endpoint。

2. 每次进程启动建立新 Session

Worker 每次启动生成 UUIDv7 session ID，并注册以下有界快照：

• canonical capabilities 及 SHA-256；
• maxConcurrentRuns 和当前 availableSlots；
• Worker 软件版本和后续协议版本；
• 控制面签发的 session lease。

控制面持久化 workerId + sessionId + generation + version：

• 首次注册使用 generation 1、version 0；
• 相同 session 和相同注册内容是幂等重放；内容冲突时拒绝；
• 经 transport 授权的新 session 原子替换旧 session，generation 和 version 单调递增；
• 心跳、drain、offline 以及未来 Run claim/completion 必须携带 session、generation 和 expected version；
• 任一字段不匹配、lease 过期或 Worker 已 offline 时 fail closed。

被 fencing 的进程停止 heartbeat，不在后台自动重新注册或抢回 Worker ID。管理员显式重启可以建立新 session，但生产 transport 必须为 takeover 增加凭证轮换、单次 enrollment 或等价的重放防护，防止持有旧长期凭证的进程反复替换当前 session。

3. Session Lease 与 Run Lease 分离

Worker Session Lease 只表达“这个认证节点最近仍在报告状态和容量”。它不授权执行任何具体任务。

Run Lease 必须由 RunQueue 对单个 RunAttempt 原子 claim，并绑定：

• Worker ID、session ID 和 generation；
• Attempt ID 和 fencing token；
• lease expiry、续租 version 和 completion sequence。

只有 Run Lease 的 claim 事务提交后，RemoteWorkerExecutor 才能下发 ExecutionSpec。Worker 接受、Executor 建立所有权和最终完成是后续三个独立事实，分别遵循 ADR-0013 的启动 ACK 与本 ADR 的双重 fencing。完成提交必须同时验证 Worker Session 和 Run Lease fencing，并通过现有 Run CAS/CompletionService 原子写入。候选查询或 Placement 命中不能代替 claim。

4. 能力与 Placement 都必须有硬上限

WorkerCapabilities 使用严格字段、确定性排序的 canonical JSON，拒绝未知字段、控制字符、重复项和超限内容。首个实现将完整快照限制为 16 KiB，并分别限制 Executor、Runtime、标签、GPU 和 feature 数量。

PlacementSpec 分为：

• required：架构、操作系统、Executor、Runtime semver、标签、最小内存/磁盘、GPU vendor 和 feature；任一不满足即不可调度；
• preferred：有界标签权重，只影响候选排序，不可绕过 required；
• 候选页：最多 64 个节点，先对 Placement 归一化一次，再确定性按 score、available slots 和 Worker ID 排序。

没有匹配节点时，Run 保持 pending，并保留低基数、可解释的 mismatch 分类，不把完整标签或 Secret 写入事件。

5. Headless Worker 是独立启动拓扑

Worker Profile 不加载 Web 面板、Scheduler、SQLite 控制面或本机 Primary router。bootstrap 默认关闭；关闭时不得调用依赖、建立连接、创建 timer 或后台进程，并且只允许显式 worker Profile 激活。

生命周期遵循：

1. 注册后只保留一个不重叠、可 unref 的 heartbeat timer；
2. 动态上报可用槽位，但不能超过声明的最大并发；
3. shutdown 先进入 draining 且容量归零；
4. draining 期间继续 heartbeat，等待本地执行面在固定上限内排空；
5. 只有执行面已排空，才请求 offline；
6. 排空超时或 disconnect 失败必须显式返回，不能把节点伪报为已安全停止。

6. 存储边界

SQLite Workers 与 RunDispatchLeases Repository 仅服务单控制面协议孵化、standalone 兼容路径和竞争测试。注册/claim 使用 SQLite immediate transaction，并对 SQLITE_BUSY/唯一竞争做有界重试；Run Lease adapter 显式拒绝非 SQLite 方言，避免被误用于 cluster-control。

cluster-control 必须提供 PostgreSQL adapter，使 session replacement、heartbeat CAS、候选发现和未来 Run claim 在多副本下具备清晰的事务与锁语义。共享 SQLite 卷、内存 map 或“最后写入获胜”不能作为集群实现。

当前实现边界

next 当前具备：

• Worker 领域值、canonical capabilities、session fencing 错误；
• WorkerControlService 和绑定 principal 的 transport-neutral client；
• SQLite/Sequelize 临时 Registry adapter 与 0008-worker-registry migration；
• Attempt-scoped 0009-run-dispatch-lease、lease generation/token/version、expiry/Worker 索引和 token 唯一约束；
• 0010-run-dispatch-candidates priority/FIFO partial index，以及最多 64 条、稳定 keyset cursor 的 SQLite Run candidate source；
• required/preferred Placement 匹配和有界确定性候选选择；
• 默认关闭的 headless heartbeat/drain bootstrap；
• 指定 runtime-owned Run/claimed Attempt 的原子 claim、幂等重放、续租、释放、Worker 并发上限和未启动 expiry takeover；
• Worker 侧单 timer Run Lease lifecycle：无重叠续租、仅在现租期内重试、session replacement/fencing fail closed，并把 shutdown release 串行化到 in-flight renewal 之后；
• ADR-0013 的 starting/running ACK、executor handle 一致性校验、启动失败终结事务和 dispatching timeout 语义；
• ADR-0014 的单周期有界 Dispatcher：先按 2×8 页恢复 active lease，再按 candidate → Worker snapshot → plan → Placement → 原子 claim 顺序生成内存 offer；pinned Project/Task/revision 必须与 ExecutionSpec 一致，相同 lease generation 派生稳定 offer ID；
• Remote completion 在一个事务中验证 Worker Session 与 Run Lease，并复用 CompletionService 提交 lease completed、Attempt、Run 和双 Event；
• PostgreSQL capability v8 的独立 worker_sessions/run_dispatch_leases、数据库锁后取时、Session replacement fencing、Worker 行锁容量 claim、token digest-only 存储与精确 Attempt fence 投影；
• ADR-0108 的 PostgreSQL Worker Pull 切片：Task 的 Placement 随 immutable execution revision 固定，candidate 使用数据库时钟和有界 keyset，认证 Worker 自带稳定 offer ID 与高熵 token；claim 只持久化摘要，同一 capability 可从 durable Lease 重建丢失响应；
• ADR-0109 的 PostgreSQL starting/running/start-failure 短事务：数据库权威时间、完整 Session/offer/Lease fence、callback digest、精确重放和 timeout 优先终态；
• 双 SQLite 连接竞争、候选分页/过滤、lease expiry、旧 session/token fencing、错误完成 token、completion crash rollback、renew/release 竞态、Placement 和生命周期测试。

以下能力尚未实现，相关入口必须保持不可达：

• mTLS/token enrollment 与生产网络 transport；
• PostgreSQL completion、expiry/lost、cancellation 与 retry 原子事务；
• delivery attempt/退避状态、认证 ExecutionSpec transport 和 headless runtime 装配；
• Remote ExecutionSpec/Artifact/日志传输；
• 已开始运行的 Attempt 失租后标记 lost、创建新 Attempt 和按重试策略重新派发；
• cancellation、shutdown 与 Run Lease 的协调协议；
• Worker 管理 API、升级、撤销和审计 UI。

影响

正面影响：

• 领域协议独立于 gRPC/HTTP 和具体 ORM；
• 新旧进程具有可验证边界，控制面重启后可以恢复节点视图；
• capability 和候选规模有硬上限，适合路由设备与异构集群共享实现；
• Worker 模块默认关闭，不增加 edge/standalone 常驻成本。

代价与风险：

• Session、Run 两层 lease 增加协议和测试复杂度；
• 心跳会产生持续数据库写入，必须按 Profile 调整 cadence，并在 PostgreSQL adapter 中批量化或抑制无变化字段；
• 仅凭同一长期 principal 允许 session takeover 仍有旧凭证重放风险，生产 transport 必须补 enrollment/rotation；
• SQLite adapter 不能证明多副本正确性，不能用于宣称 cluster-control 可用。

被拒绝的方案

1. 只用连接是否存在表示 Worker 在线：控制面重启后丢失，且多副本视图不一致。
2. 请求体直接携带可信 Worker ID：未认证调用者可以冒充或 fencing 正常节点。
3. 只有时间 lease，没有 generation/version：时钟和迟到请求无法可靠区分新旧进程。
4. 候选命中即视为任务领取成功：并发 Dispatcher 会重复分配同一 Attempt。
5. Worker 复用完整控制面进程：把面板、Scheduler、数据库和插件常驻成本带到边缘节点，也扩大攻击面。
6. 失联后自动以同一 ID 无限重注册：旧进程可能与新进程形成 session 抢占风暴。

验证与进入生产的门禁

• 两个控制面连接竞争替换同一 Worker 时 generation 单调，旧 session 全部被拒绝；
• heartbeat 不重叠，lease 过期节点不可见，draining/offline 节点不进入候选；
• drain 与 stop 并发时仍先归零容量，disconnect 失败不返回成功；
• capability/Placement 未知字段、超限集合、非法 semver 和超限候选页全部 fail closed；
• PostgreSQL contract suite 覆盖多副本 claim、锁等待、lease expiry、重复 completion 和 fencing；
• 认证 transport 覆盖身份冒充、凭证撤销、replay、限流、超限消息和断线重连；
• 固定 256 MiB edge 设备验证禁用 Worker 时无新增 timer/连接，轻量 Worker 的 RSS、heartbeat 写放大和空闲 CPU 达到发布预算；
• Node 24 支持矩阵中的每个 Worker 架构完成注册、执行、断线恢复和 Artifact smoke test。