qinglong/docs/adr/ADR-0116-reviewed-worker-posix-executor-and-upload-before-completion.md

# ADR-0116：受审 Worker POSIX Executor 与 Upload-before-completion 闭环

- 状态：Accepted（ADR-0117 已补 HTTPS/数据库闭环，ADR-0121 已补生产执行面装配；retention 与完整 Worker 产品生命周期仍默认关闭）
- 日期：2026-07-23
- 关联 RFC：QL-RFC-0001 D-14、D-17、D-24、D-26、D-68、D-110、D-114、D-115
- 关联 ADR：ADR-0021、ADR-0069、ADR-0111、ADR-0115

## 背景

ADR-0115 交付了 Worker 本地日志 spool 和 output ownership，但仍缺真实进程启动器、可认证
完成回执和 upload-before-delete 顺序。若 Worker 复制一套 launcher，会让本机与远端执行的
安全修复漂移；若先提交 Run 终态再上传日志，控制面成功而网络失败会形成不可恢复的空
Artifact；若上传后立即删除本地文件或回执，inbox CAS 崩溃又会丢失重放证据。

另一个关键窗口是 `launching` 已落盘、进程已经 spawn、`started` 尚未写入时的 Worker 崩溃。
仅在 `started` 保存启动时间，回执无法与 durable spawn authority 做 exact 匹配，恢复只能永久
阻断或错误放宽认证。

## 决策

### 1. 复用 local-process 边界，不新增 package

`@qinglong/worker-runtime/posix-executor` 依赖现有 `@qinglong/local-process`。这是有意的单向
依赖：local-process 拥有受审 POSIX launcher、verified-fd 执行、completion receipt、durable
process identity 和 OS 路径规则；Worker 只拥有 Session/Lease/inbox 策略。它们具有真实的
platform/供应链边界，符合 D-85，不复制 launcher，也不新增只有一两个文件的 package。

Worker Executor 只接受带私有 file-plan capability 的 output。它在 spawn 前重读同一 inbox，
精确校验 offer、Run、Attempt、callback sequence/token digest、log Artifact 和启动时间；随后
关闭父写 descriptor，让受审 launcher 以 verified fd 和独立进程组启动用户命令。明确
`no_spawn` 才返回 rejected；spawn 后 identity 捕获失败为 unknown，禁止上层上报 start-failure。

当前 timeout 仍 fail closed：只要 execution revision 携带 `timeoutMs`，Executor 在 durable
spawn barrier 前拒绝。没有 durable timeout/cancellation evidence 时不得用进程内 timer 冒充。

### 2. 启动时间属于 durable pre-spawn authority

Processor 在交接 output 前把 `executorStartedAtMs` 与 log ID、callback sequence/digest 一起写入
`launching`。local-process 接受可选的上层 durable start timestamp，但必须验证它是安全整数且
不晚于本地 launch observation；launcher journal、receipt、Executor result 和最终 inbox 必须
使用同一个值。

因此崩溃发生在 spawn 后、`started` CAS 前时，可信 completion receipt 仍可从 `launching` 或
`launch_outcome_unknown` 恢复，不需要裸 PID、日志内容或宽松时间范围猜测。该状态机变化影响
`processOnce`、`launch`、`acceptOffer` 三条流程，必须由 exact transition 与 restart 测试门禁。

### 3. 回执认证只消费原始 capability，不传播它

Worker inbox 只持久化 32-byte callback capability 的 SHA-256。launcher receipt 可短暂保存
base64url 原文，协调器读取后必须 canonical decode 为恰好 32 bytes，以 constant-time 比较其
SHA-256，并精确匹配 Run、Attempt、callback sequence 和 durable start time；局部 buffer 随后
清零。上传、completion command、日志、诊断和 inbox 都不得携带 token 原文。

非法、未来时间或 authority 不匹配的回执不能触发上传或 completion。当前实现保留回执供后续
隔离/运维，不把损坏证据推导成用户任务失败。

### 4. 日志使用固定内存流，不整文件载入

现有 `WorkerFileLogArtifactAllocator` 同时实现只读 source。它按 opaque ID 定位单个文件，使用
`O_NOFOLLOW` 后复验 owner、单 link、权限、fd/path inode 和 root/shard identity；不扫描目录。
内容以最多 64 KiB chunk 单次消费，Edge 与 Node 共用协议而使用各自 4/64 MiB 总上限。

launcher 的 immutable truncation fact 以同样私有路径读取，并精确匹配 Run、Attempt、log ID、
Profile maximum 和 bounded timestamp。fact 缺失表达 `unknown`，不能伪装成未截断。

### 5. 顺序固定为 upload、completion、inbox ACK、receipt cleanup

`@qinglong/worker-runtime/completion-coordinator` 的可重放顺序固定为：

1. 重读并规范化唯一 inbox authority，复验当前 Worker Session 与 Run Lease 未过期；
2. 读取并认证 completion receipt；
3. 打开 exact log Artifact，以流式 SHA-256 和 byte count 校验 uploader ACK；
4. 只有 durable upload ACK 后才提交 lease-fenced completion，command 携带 Artifact ID、长度、
   digest 和 truncation 状态；
5. completion applied/exact replay 后 CAS 写 `completion_acknowledged`；
6. 只有该本地 terminal barrier 已耐久化，才 best-effort 删除 receipt。

本协调器绝不删除本地日志。Artifact 只能由后续 retention 在已证明 upload/control-plane ACK 且
超过策略保留期后清理。任一步网络/CAS 失败都保留可重放的 receipt、inbox 和 spool；上传端与
completion 端必须用 ID/digest/fence 提供精确幂等。

当前交付的是 Worker 侧真实文件/进程实现和严格 adapter port。ADR-0117 已补中央 Artifact store
port、认证 HTTPS upload/completion endpoint 与 PostgreSQL 终态事务；ADR-0118 已补失租停止与
durable timeout/cancellation，ADR-0120 已补具体 S3-compatible store，ADR-0121 已补默认关闭的
production execution-plane composition。retention、Session/credential 产品流程与部署入口仍未装配，
因此完整 Worker Profile 继续默认不可达。

## 被否决的替代方案

1. **为 Worker launcher 新建 package 或复制 shell**：扩大碎片并产生两套安全修复源。
2. **`started` 后才保存 start time**：spawn 后崩溃无法严格认证回执。
3. **对 base64url 字符串直接 hash**：与 Processor 保存的原始 32-byte capability digest 不一致。
4. **completion 后再上传**：终态成功但日志永久留在离线 Worker。
5. **upload 返回成功但不验证消费字节/digest**：空读或部分读可冒充 durable Artifact。
6. **上传后删除 spool**：inbox/completion CAS 窗口丢失重试源。
7. **整文件读入 Buffer**：64 MiB Node 配额会放大路由器和并发 Worker 峰值内存。
8. **为完成协调器新建 workspace package**：单一 Worker consumer、同部署/依赖/权限闭包，不满足
   D-85；使用现有 package subpath。

## 验收证据

1. reviewed-fd Worker launch 产生 exact durable handle、日志和 completion receipt，callback token
   不进入用户环境。
2. spawn barrier 漂移零 spawn；spawn 后 identity 失败保持 unknown。
3. `launching` 持久化 start time，launcher receipt 与最终 state exact；重启不二次 spawn。
4. completion coordinator 可从无 executor handle 的 durable `launching` 回执恢复。
5. capability mismatch 在 upload 前拒绝并保留全部证据。
6. 文件 source 固定 chunk 流式读取并认证 truncation fact，不枚举目录。
7. 测试证明 upload 完成先于 completion，inbox terminal ACK 先于 receipt remove。
8. upload 失败时不调用 completion、不删除 receipt，并关闭只读 descriptor。
9. 未新增 workspace package、数据库、schema、timer 或 Worker 常驻连接。