qinglong/docs/adr/ADR-0057-postgresql-worker-session-and-run-lease-authority.md

ADR-0057：PostgreSQL Worker Session 与 Run Lease Authority

• 状态：Proposed
• 日期：2026-07-19
• 关联 RFC：QL-RFC-0001 D-05、D-06、D-23、D-34 至 D-42、D-54 至 D-56
• 关联 ADR：ADR-0012、ADR-0013、ADR-0014、ADR-0021、ADR-0039、ADR-0043、ADR-0056

上下文

cluster-control 的 run_attempts 原先同时保存 Worker、executor、lease token 和 expiry。这个扁平快照可以支持 Run 聚合读取，却不能单独表达两个不同 authority：

• Worker Session Lease 证明某个经过认证的 Worker 进程、session 和 generation 当前仍可报告容量；
• Run Lease 证明该 session 对某个 Attempt 获得了一次带 generation/version 的执行授权。

如果直接把 Attempt 行上的 worker_id + lease_expires_at_ms 当作远程恢复证据，会产生三个错误：Worker 在线不等于某个执行仍在运行，lease 过期不等于执行已经停止，多副本 Dispatcher 也没有可以原子竞争和 fencing 的独立行。ADR-0056 的 Remote Worker provider 因此不能建立在该扁平快照上。

同时，QingLong 3.0 仍必须保证 edge/standalone 不因集群 Worker 能力引入 PostgreSQL、常驻连接或新 timer。

决策

1. Session 与 Run Lease 使用独立事实表

PostgreSQL capability v8 新增：

• worker_sessions：以 worker_id 为主键，保存 session UUIDv7、generation、status、version、canonical capabilities/hash、容量、heartbeat 和数据库时间 lease；
• run_dispatch_leases：以 attempt_id 为主键，保存 Run、Worker session/generation、lease generation/version、token digest、稳定 offer ID 和终态元数据。

run_attempts 只保留用于聚合读取和 recovery snapshot CAS 的精确 fence 投影：Worker session/generation、lease generation/version、token digest、offer ID 和 expiry。run_dispatch_leases 才是执行授权的事实源；Attempt 投影不能独立续租、释放或证明执行停止。

2. Bearer lease token 不得持久化

新 cluster Run Lease API 接收内存中的高熵 bearer token，但 PostgreSQL 和返回 DTO 只保存/暴露 SHA-256 digest。claim、renew 和 release 在进程内派生 digest 后比较；事件、日志、recovery target 和诊断输出都不得包含原 token。

旧 run_attempts.lease_token 暂时保留用于迁移兼容，但新的 PostgreSQL Run Lease repository 固定写入 NULL。删除该列需要独立 migration 和 2.x 回退窗口审计。

3. 所有 lease 时间由 PostgreSQL 在取得必要锁之后观察

客户端时钟不参与 Session/Run Lease expiry。Repository 使用 statement_timestamp()，并且只能在以下锁已取得后读取 observation：

• Worker registration：按 Worker ID 的 transaction advisory lock 和现有 Worker 行锁；
• heartbeat/transition：Worker 行锁；
• Run claim：Worker、Run/Attempt 与既有 Run Lease 行锁；
• renew：Worker 与 Run Lease 行锁；
• release：Worker、Run Lease、Run/Attempt 行锁。

这样锁等待时间不能被遗漏，过期判断和新 expiry 都基于真正进行裁决时的数据库时间。

4. Worker Session replacement 与 mutation 全量 fencing

首次注册建立 generation 1/version 0。相同 session 只有 capabilities、容量和仍存活的 lease 全部一致时才是幂等重放；冲突、offline 或已过期 session 均拒绝。新 session 在同一 Worker ID 锁下原子推进 generation/version，并返回 replacedSession=true。

heartbeat、drain 和 offline 必须同时匹配 Worker ID、session、generation 和 expected version。draining/offline 容量固定为零。Repository 不认证请求体；未来 Worker transport 必须先从 mTLS/短期 enrollment credential 建立 principal，不能把 register() 直接暴露为匿名网络入口。

5. Run claim 由 Worker 行锁串行化容量裁决

claim 固定执行：

1. 锁定目标 Worker；
2. 锁定 Run/Attempt 与已有 Run Lease；
3. 读取数据库 observation；
4. 验证当前 Worker session/generation、online、session lease、Run runtime ownership、取消意图和 claimed Attempt；
5. 在 Worker 行锁保护下计算该 session 的 active lease 数，并要求它同时小于 maxConcurrentRuns 和最近一次 heartbeat 上报的 availableSlots 上界；
6. 原子写入 Run Lease、Attempt fence、Run version/event sequence 与 dispatch Event。

相同 token digest、offer ID 和完整 fence 是幂等重放；不同调用者看到 live lease 只能得到 leased。续租同时 CAS Run Lease version 和 Attempt 投影；release 只处理尚未越过启动屏障的 claimed Attempt，并在同一事务清除投影和追加 Event。starting/running 的完成、失租与取消仍由后续专用事务处理，不能借 release 扩权。

6. 权限和 Profile 保持分离

常驻 runtime role 对 worker_sessions、run_dispatch_leases 只有 SELECT/INSERT/UPDATE，无 DELETE/DDL；cluster-admin 对两表零权限。migration role 仍是唯一 DDL authority。

未来认证 Worker attestation ingress 应使用独立入口和更窄数据库 capability；不能因为 runtime role 当前可管理调度 lease，就允许普通业务 handler 伪造 not_running evidence。

runtime-core 只包含无数据库 driver 的 contract/validator。PostgreSQL repository 只从 cluster package/runtime 子入口导出，edge/standalone importer 不引入 pg、表、连接或 timer。

被否决的替代方案

1. 继续只用 Attempt 行 lease：无法区分 Session Lease、Run Lease 和恢复快照，也无法安全串行化跨 Attempt 的 Worker 容量。
2. 用控制面进程时间计算 expiry：副本时钟漂移和锁等待会让 takeover/renew 裁决不一致。
3. 在 PostgreSQL 保存原 lease token：数据库读权限、备份和诊断泄漏会直接获得执行 capability。
4. 只检查 availableSlots 是否大于零：多个 Dispatcher 可在同一 heartbeat 之间重复消费相同槽位；必须在 Worker 行锁下要求 active leases 同时低于最大并发和上报槽位上界。这个保守模型优先避免超卖；未来若要把 availableSlots 精确解释为“扣除运行中任务后的瞬时空闲数”，必须引入独立 reservation epoch/counter，不能在没有 heartbeat 代际的情况下直接递减并与 Worker 上报相互覆盖。
5. Session offline/lease expiry 直接作为 not_running：这只能证明控制面 authority 失效，不能证明远端进程已经停止。
6. 把 PostgreSQL Worker adapter 放入根应用：会重新污染 edge 安装图并让 cluster adapter 依赖 legacy Sequelize。

影响与未完成项

正向影响：

• Worker/Run 两层 lease 在多副本下有独立、可锁定、可审计的事实源；
• bearer token 不落库，recovery target 只携带 digest；
• Session replacement、capacity claim、renew/release 都有精确 fencing；
• Attempt recovery snapshot 可以绑定 session、lease generation/version 和 offer，而不把投影误当 authority；
• edge/standalone 依赖和空闲资源成本不变。

ADR-0058 已完成独立 Worker credential/ingress role、append-only attestation、Remote Worker provider 和 PostgreSQL 16.14 四角色验证。ADR-0108 又完成 PostgreSQL candidate/placement、认证 Worker Pull 与 digest-only offer recovery；ADR-0109 已完成 starting/running/start-failure 数据库权威 ACK，并用真实 PostgreSQL 16.10 runtime role 验证。该入口在 ExecutionSpec transport 与生产内部 port 门禁前仍默认不注入生产组合根。仍未完成：

• mTLS/enrollment transport、credential recovery ceremony 与 pepper rotation；
• completion、expiry/lost、cancellation 与 retry 的 PostgreSQL 原子协调；
• Worker 本地 journal 到网络 attestation 的生产装配与 Artifact/日志 transport；
• PostgreSQL 16/18 远端 CI 首次成功证据和多 Pool failover/lock-wait 基准。

验证

• runtime-core contract test 验证 bounded Worker Session、canonical snapshot hash、token digest 和 lease terminal shape；
• migration/Drizzle/schema/readiness lockstep test 冻结 pg-0009 checksum、capability v8、表/列/index/CHECK/FK 和 runtime/admin 权限；
• 真实 PostgreSQL transaction test 验证注册/replacement、幂等 claim、容量耗尽、renew version fencing、release 清权、token 不返回和 Attempt 投影；
• 本机 PostgreSQL 13.3 仅用于 SQL/锁/约束验证，production readiness 仍按策略拒绝；发布证据必须来自 PostgreSQL 16/18 CI；
• edge dependency/import audit 必须继续证明该切片没有进入 edge/standalone 产物。