qinglong/docs/adr/ADR-0117-streamed-remote-worker-artifact-and-atomic-completion.md

# ADR-0117：流式 Remote Worker Artifact 与原子 Completion

- 状态：Accepted（S3-compatible 共享对象存储已由 ADR-0120 实现，生产执行面装配已由 ADR-0121 实现；retention 与完整 Worker 产品生命周期仍默认关闭）
- 日期：2026-07-23
- 关联 RFC：QL-RFC-0001 D-14、D-17、D-24、D-26、D-68、D-85、D-108、D-111、D-114、D-115、D-116
- 关联 ADR：ADR-0024、ADR-0058、ADR-0109、ADR-0112、ADR-0115、ADR-0116

## 背景

ADR-0116 固定了 Worker 的 upload-before-completion 顺序，但中央侧仍只有抽象 port。若通过普通
JSON/base64 发送 64 MiB 日志，Worker 和 controller 都会产生大对象复制；低配路由设备无法承受，
高并发节点也会放大 GC。若 controller 先把日志写入本地盘，多副本 completion 可能看不到上传
结果；若只信任 Worker 上报的 digest，终态可引用不存在或已漂移的内容。

completion 还必须关闭两个崩溃窗口：running ACK 已完成后的正常终结，以及进程已经完成、但
Worker 在 running ACK 前崩溃后从 durable `starting` 证据恢复。网络 upload 不得跨 PostgreSQL
事务持锁，终态又必须一次完成 Lease、Attempt、Run 和 Event，不能由多个 API 逐步拼接。

## 决策

### 1. 不新增 package，使用两个 exact versioned contract

wire contract 放入 `@qinglong/runtime-core/remote-worker-completion`；Worker adapter 放入现有
`@qinglong/worker-runtime/completion-transport`；Cluster service 与 PostgreSQL repository 分别
留在现有 cluster-control、cluster-postgres。它们与既有部署、依赖、权限和版本责任相同，不满足
D-85 的拆包条件。

Artifact schema 为 `qinglong/remote-worker-artifact-upload@v1`。request 使用 4-byte big-endian
JSON header length，header 最多 4 KiB，随后是最多 64 MiB 原始内容。header 只携带 execution
fence、Artifact identity、内容长度和 truncation；Worker/Session identity 由 path 绑定，不在 body
重复。media type 固定为 `application/vnd.qinglong.worker-artifact`，必须 identity encoding 和精确
Content-Length，不允许 chunked、压缩或 multipart 产生第二套解析语义。

completion schema 为 `qinglong/remote-worker-completion@v1`，request/response 分别最多 16/4 KiB，
字段 exact，未知字段拒绝。普通 Worker ingress JSON 的 4 KiB 默认与 64 KiB hard cap 不因 Artifact
stream 放宽；只有 Artifact route 使用独立 64 MiB + 4 KiB + 4 bytes hard cap。

### 2. 复用单一 mTLS client 和有界 backpressure

Worker Artifact uploader 与 completion client 复用 ADR-0112 的 `WorkerIngressHttpsClient`、TLS 1.3
mTLS credential provider、canonical `ql3w` authorization 和单 keep-alive Agent。stream writer 按
已知长度逐 chunk 写入，Node socket 返回 backpressure 时等待 `drain`；短读、超读、错误类型、
错误 route、响应越界或 authority 漂移全部 fail closed。

Artifact preamble、TLS credential material、JSON request/response 临时 buffer 在消费后尽力清零。
完成协调器继续只从 durable inbox 装配 lease capability；通用 Artifact source/store 不接收 Worker
credential，也不记录 capability。

### 3. 认证和授权先于内容，store 必须跨副本共享

Cluster HTTP surface 必须先完成 route、mTLS/credential、Worker/Session 和 admission prepare，再读取
stream body。Artifact service 读取有界 header 后，在共享 Attempt advisory fence 下通过 PostgreSQL
repository 精确复验 Worker generation、offer、Lease generation/token digest/version/expiry、Run、
Attempt 和状态；授权成功后才把原始内容交给 store。

`ClusterRemoteWorkerArtifactStore` 是 immutable put-if-absent port：key 至少绑定 Project、Run、
Attempt、log Artifact ID，返回实际消费的 length、SHA-256 和 truncation。实现必须跨所有
cluster-control replica 可见，并对相同 identity + digest 提供 exact replay；同 identity 不同内容
拒绝。controller 本地目录、Pod ephemeral volume 或仅 process-local Map 只能用于测试，不能声明为
生产 cluster store。

store 不接收 Worker/Session identity、raw lease token 或 callback capability。上传事务不跨 store
I/O 持有数据库锁；因此 completion 必须重新调用 `inspect`，精确匹配 immutable Artifact 的 ID、
length、SHA-256、truncation 和 Project/Run/Attempt authority 后才能进入终态事务。

### 4. completion 是一个 PostgreSQL 权威事务

repository 使用既有 Attempt advisory fence，并按 Worker Session、Run/Attempt、Run Lease 的固定
顺序 `FOR UPDATE`，随后读取一次数据库时间。它复验 path principal、Session/generation、offer、
Lease generation、raw token 的 SHA-256、expected version、callback sequence/digest 和 Artifact
receipt。raw token 只在应用内比较摘要，不进入 SQL、Event 或错误。

允许的 live 起点只有：

- `starting + dispatching`：覆盖 spawn 后/running ACK 前的 authenticated receipt 恢复；
- `running + running`：正常 completion。

Worker finished time 不能晚于数据库时间加五分钟。最终状态首先服从 durable cancellation/timeout
intent，再解释 exit code；不得让迟到成功覆盖取消或 timeout。单一 transaction 必须：完成 Lease
并把 version 加一、终结 Attempt、终结 Run、写 Attempt 与 Run 两个 Event。Event ID 由服务端生成，
terminal timestamp 取数据库 observation、Worker evidence 和既有 start/create facts 的安全上界。

### 5. exact replay 由终态和 Event 共同认证

只有 Lease 已 `completed`、Lease/Attempt version 精确为 request expected version + 1、Run/Attempt
终态和 callback/Artifact/exit/error facts 完全一致，并且已有 Attempt completion Event 具有 exact key
set 与 exact payload，才返回 `already_completed`。Event 的 `from_status` 只允许 `starting|running`。
任何字段漂移为 `replay_mismatch`；其他已终态 aggregate 返回 `already_terminal`，不能被当前 Worker
改写，也不能重复追加 Event。

### 6. 生产默认关闭条件

ADR-0120 已选择一个 S3-compatible 共享 immutable adapter；任何 production composition 都必须显式
注入它，缺失时 Artifact/completion routes 不注册或 admission fail closed。不得用 controller-local
fallback 自动降级。ADR-0121 已提供默认关闭的 Worker execution composition，但 transport 类存在仍
不得自动启动 timer、Pull 或 completion loop；完整 Session/credential 产品生命周期继续由外层门禁。

本 ADR 不完成 Artifact range read/retention、spool deletion、对象存储 credential/临时前缀 lifecycle
的产品配置，也不声明多 Pod/failover 实机支持。durable timeout/cancellation/lease-loss stop 已由
ADR-0118 完成；S3 SSE/KMS adapter 与单节点 MinIO 真实验证由 ADR-0120 完成；默认关闭的生产执行面
装配与 drain-before-release 由 ADR-0121 完成。

## 被否决的替代方案

1. **JSON/base64 Artifact**：峰值内存和复制与日志大小成正比，拒绝。
2. **multipart/form-data**：引入第二套复杂边界解析且没有当前单 Artifact 请求的收益，拒绝。
3. **controller 本地文件作为 cluster store**：多副本不可见、Pod 重建丢失，拒绝。
4. **先写 store、后信任 Worker 自报 digest**：不能证明中央内容与终态一致，拒绝。
5. **跨 upload 网络调用持 PostgreSQL transaction**：长锁和连接占用放大 store 尾延迟，拒绝。
6. **completion 分别更新 Lease、Attempt、Run**：中途崩溃产生不可解释部分终态，拒绝。
7. **只按终态行做幂等**：无法证明历史 completion payload，拒绝。
8. **为 upload/client/repository 各建 package**：没有独立依赖/权限/发布责任，违反 D-85，拒绝。

## 验收证据

1. runtime contract 拒绝未知字段、越界 header/content、错误 authority 和结果不一致。
2. HTTP surface 在读取 stream 前完成 admission，拒绝错误 media type、encoding、Content-Length 和
   未完整消费；普通 JSON cap 保持不变。
3. Worker client 使用 fixed length、backpressure 和共享 Agent；短读、超读、route confusion 拒绝。
4. 真实 TLS 1.3 mTLS 测试完成分帧 Artifact upload 与 completion，并验证 path/body identity 分离。
5. Artifact service 先授权再 store，验证实际消费 length/digest，completion 前重新 inspect。
6. PostgreSQL repository 从 `starting` 与 `running` 收敛，在单 transaction 完成 Lease/Attempt/Run/
   双 Event，cancellation/timeout 优先。
7. exact replay 同时验证终态、version 和 Event payload；非法 `from_status`、digest 漂移拒绝。
8. raw lease token 不进入 SQL/Event；Event identity 由服务端生成。
9. Worker、runtime-core、cluster-control、cluster-postgres 完整测试通过，未新增 workspace package、
   migration、schema、timer、queue 或常驻连接。
10. ADR-0125 的本机 arm64 PostgreSQL 18.4 physical-promotion 门在 runtime-role completion
    transaction 的 driver-confirmed `COMMIT` 后终止 backend，使首次调用得到 unavailable；同一
    fence/receipt/Event identity 重放为 `already_completed`。standby 在 promotion 前、promoted
    primary 在 timeline 2 上均保持 succeeded Run/Attempt、completed Lease version 5、2 条 Event、
    2 个 dedupe key 和 0 duplicate；故障范围是 PostgresClient 边界，不是 raw-wire packet-loss。