qinglong/docs/adr/ADR-0109-postgresql-remote-run-activation-ack.md

# ADR-0109：PostgreSQL Remote Run 原子启动 ACK

- 状态：Accepted
- 日期：2026-07-22
- 关联 RFC：QL-RFC-0001 D-23、D-57、D-107、D-108
- 关联 ADR：ADR-0013、ADR-0014、ADR-0057、ADR-0058、ADR-0108

## 背景

ADR-0108 已让认证 Worker 用稳定 `offerId` 和自己持有的高熵 lease capability 领取经过 Placement 的 Execution Offer，但 claim 只证明某个 Session 暂时拥有 Attempt。若 delivery、Worker 收包或 spawn 被直接解释成 running，控制面就无法区分“尚未接受”“正在建立执行器”和“已取得可恢复 handle”三个崩溃窗口。

QingLong 3.0 还必须同时服务低配路由设备和集群节点。ACK 协议不能要求 Worker 维持额外 stream、服务端 mailbox 或 per-run timer，也不能为了三个短命令再增加 workspace package。多副本控制面则必须让 Worker Session、Run Lease、Run、Attempt 和 Event 在同一个 PostgreSQL authority 下裁决。

## 决策

### 1. 三个 ACK 是独立、认证且有界的命令

Worker ingress 增加 `starting`、`running` 和 `start-failure` 三个显式操作。transport 先绑定 credential principal 与路径中的 `workerId/sessionId`，完成 durable security audit 后才调用注入的 activation port。请求体不能自报 Worker ID，响应不得回显 lease token 或 callback token digest。

每个命令必须携带 Run、Attempt、Session generation、offer ID、lease generation、lease token 和 expected lease version。`running` 还必须携带最多 512 字节的稳定 executor handle、可空的 log artifact ID、callback sequence 和 lowercase SHA-256 callback token digest。所有字符串都有固定上限；协议不建立常驻连接、队列、timer 或新增 package。

### 2. PostgreSQL 是唯一启动状态 authority

每个 ACK 使用一个短事务，并按 Attempt advisory fence、Worker Session、Run/Attempt、Run Lease 的固定顺序加锁。完成锁定后才读取 PostgreSQL statement time，并验证：

- Worker Session 仍是同一 session/generation，状态为 `online|draining` 且 lease 未过期；
- Run 为 runtime-owned，Attempt executor type 为 `remote_worker`；
- Run Lease 与 Attempt 投影中的 worker/session/generation/offer/generation/token digest/version 完全一致；
- 非终态 ACK 的 Lease 仍为 leased 且按数据库时间未过期。

Worker 的本机时钟不进入 Run/Attempt 时间事实。任何 fence、状态或重放元数据漂移都以低基数 conflict 失败，事务内任何 SQL 失败都回滚全部状态和 Event。

### 3. starting 与 running 具有不同提交边界

首次 `starting` 只把 Attempt 从 `claimed` 推进为 `starting`，Run 保持 `dispatching`，并追加一条 `attempt.starting` Event。完全相同 authority 的重放返回 `already_starting`；若已正确 running，迟到 starting 返回 `already_running`。

首次 `running` 要求 Attempt 已 starting，并在同一事务中：

- 把 Attempt 与 Run 推进为 running；
- 使用数据库时间写两者的 started time；
- 固化 executor handle、可选 log artifact、callback sequence 与 callback token digest；
- 连续追加 `attempt.running`、`run.running` 两条 Event。

running 不推进 Run Lease version；renewal 仍是 active Lease version 的唯一推进者。重放只有在 handle、artifact、callback sequence、callback digest 和完整 Lease authority 都一致时才返回 `already_running`。

### 4. start-failure 原子终结并关闭晚到回调

首次 `start-failure` 只接受 starting/dispatching，并在同一事务中：

- 按 cancellation fact 选择 `failed|cancelled|timed_out`；
- 写固定错误码与低敏摘要；
- 推进 callback sequence，关闭晚到 completion receipt；
- 终结 Attempt 与 Run，追加两条对应 Event；
- 将 Run Lease 标记 completed 并推进 version，同时更新 Attempt 的 lease version 投影。

普通失败使用 `EXECUTOR_START_FAILED`；已有普通取消使用 `EXECUTION_CANCELLED`；timeout 取消优先使用 `EXECUTION_TIMED_OUT`。丢失成功响应后的 retry 允许同一原始 expected version 精确命中 `completed version = expected + 1`，但仍必须证明同一 token、offer、Session、generation 和终态映射；否则拒绝，且绝不重复 Event。

### 5. 权限与包边界不扩大

contract 放在 `@qinglong/runtime-core/remote-activation`，PostgreSQL adapter 放在既有 `@qinglong/cluster-postgres/runtime`，应用服务放在 `@qinglong/cluster-control/remote-activation`。总包数保持 23。

独立 Worker-ingress application 只持有注入 port，且 `ql3_worker_ingress` role 继续没有 Run、Attempt、Run Lease mutation 权限。权威事务由受审 runtime role 执行；transport 与 runtime 的产品装配仍必须显式建立受保护的内部边界，不能让 HTTP handler 临时获取 runtime Pool。

## 被否决的替代方案

1. **claim 或 delivery 后直接标记 running**：无法证明执行器已建立，也无法安全恢复 handle。
2. **信任 Worker startedAt**：不同路由器和集群节点的时钟漂移会污染权威顺序。
3. **只校验 token，不校验 offer/session/version**：旧 Session、renewal 前请求或 ABA Lease 可以迟到覆盖。
4. **running 只保存 handle，不保存 callback digest**：后续 completion 与 recovery 无法证明同一回调 capability。
5. **给 worker-ingress role 表级写权限**：认证 transport 会获得绕过应用 fence 的宽 Run mutation authority。
6. **为 ACK 新增 package、队列或 stream**：没有新的发布/权限/平台边界，却会扩大低配安装闭包和常驻资源。

## 影响

正向影响：

- offer、starting、running 和 start-failure 成为可区分、可恢复的 durable facts；
- 多副本 ACK、renewal、Session replacement 和 cancellation 在同一数据库 authority 下竞争；
- 明文 lease/callback capability 均不落库、不进 Event、不出现在响应；
- 路由设备只需三个短请求，集群 Worker 可按自身并发扩展，服务端不保留 per-worker 内存状态；
- 不新增 migration、package 或 edge/standalone 依赖。

仍未完成：

- 认证 ExecutionSpec delivery 与 Worker durable admission 已由 ADR-0110 完成；仍缺 package inbox 到执行 Receiver 的单 journal 状态迁移，以及 Artifact/log/completion transport；
- PostgreSQL completion、lease expiry/lost、cancellation/retry 的对等远端生命周期；
- runtime ACK port 与独立 Worker listener 之间的生产内部调用边界、过载保护和 telemetry；
- 多 Pod/failover、PostgreSQL 18、真实路由设备网络抖动和断电证据。

因此 ACK 门禁已经完成，但 Pull/Remote Worker 仍不默认进入生产组合根。

## 验收证据

1. runtime contract 拒绝越界 handle、非法 callback digest、弱 lease capability 和不完整 fence。
2. cluster-control 测试证明服务端生成 Event ID、principal/session 绑定、三个认证 ingress operation、冲突映射以及响应不回显 capability/digest。
3. PostgreSQL 16.10 真实实例以独立 migration/runtime/worker-ingress role 验证 Pull offer、digest-only 丢响应恢复、starting/running 精确重放、启动失败与 timeout 优先终态；Run/Attempt/Lease/Event/callback fence 原子提交且 token 明文不落库。
4. `ql3_worker_ingress` 保持原最小权限；ACK repository 只从 runtime entrypoint 导出。
5. 23 个 package clean build/全量测试、backend 兼容回归、cluster/edge dependency audit、六档本地 Profile 制品与 GitNexus change detection 全部通过；制品最大 2,346,992 bytes/395 files、最大抽样 RSS delta 12,419,072 bytes，QL3 production importer 为 0 high/0 critical。GitNexus 对已跟踪 diff 为 LOW/0 affected process；当前 QL3 孵化树仍是未跟踪文件，因此该结果只作补充证据。