qinglong/docs/adr/ADR-0070-atomic-local-run-execution-coordination.md

# ADR-0070：本机 Run 原子启动协调与耐久身份补偿

- 状态：Proposed
- 日期：2026-07-20
- 关联 RFC：QL-RFC-0001 D-02、D-05、D-17、D-37、D-40、D-42、D-62、D-65、D-66、D-67、D-68、D-69
- 关联 ADR：ADR-0001、ADR-0003、ADR-0005、ADR-0007、ADR-0026、ADR-0040、ADR-0044、ADR-0063、ADR-0066、ADR-0068、ADR-0069

> ADR-0087 现行增量：本文 coordinator 已迁入 `@qinglong/local-execution/execution`；package 不提供聚合根入口，原子启动与 durable identity 补偿语义不变。

## 上下文

ADR-0069 已交付 pre-spawn journal、受审 launcher、completion receipt 与 exact Linux durable identity，但 launcher 只证明“怎样安全 spawn”，不能决定“哪个 Run/Attempt 有权 spawn”。若 scheduler、Workflow 或 application stack 直接取得 launcher，它可以在 `attempt.starting`、callback authority 或 deadline 尚未提交时创建进程；控制面此时崩溃会留下没有可解释数据库意图的外部副作用。

另一个窗口发生在 spawn 已成功、`executor_handle/pid` 尚未提交时。简单把 Attempt 标为 `lost` 会让仍在运行的原进程与后续重试并存；只按裸 PID stop 又可能杀死复用 PID。把这段策略塞回 legacy Primary orchestrator、Sequelize adapter 或 local-process，会分别重新引入 2.x 根依赖、数据库实现泄漏或基础设施反向依赖应用策略。

## 决策

### 1. 启动策略使用独立 local-execution package

新增 `@qinglong/local-execution`，生产只依赖 `@qinglong/runtime-core` port 与 `@qinglong/local-process`。固定依赖方向为：

```text
runtime-core
  <- local-process
  <- local-execution

runtime-core + local-process
  <- local-run-recovery

local-adopted-profile + local-execution + local-run-recovery
  <- local-application
```

local-execution 不导入 local-sqlite、Profile、legacy、cluster、ORM 或 HTTP。真实 `LocalSqliteRunRepository` 只在测试和组合根通过 runtime-core port 注入。local-process 不反向依赖 execution 或 recovery；execution 与 recovery 并列，前者拥有新启动协议，后者拥有崩溃后证据裁决。

launcher、coordinator 和 durable controller 均由组合根私有构造；ADR-0071 后 application 只暴露有界 dispatcher。上层不能绕过不可变执行定义、Artifact admission 或聚合事务取得裸 spawn capability。

### 2. spawn 前必须原子建立执行 authority

coordinator 只接受同时满足以下条件的 aggregate：

- Run 是 runtime-owned、`queued` 且没有 cancellation intent；
- Attempt 是该 Run 的 latest Attempt、状态为 `claimed`、executor type 为 `local_process`；
- callback sequence 为零，callback digest、Worker/Lease/Offer、handle/PID、deadline、日志、开始/结束和错误字段均未被旧 authority 占用。

它生成 256-bit callback capability，只把 SHA-256 digest 持久化。第一次 Repository transaction 依次 CAS：

1. Run `queued → dispatching` 并追加 `run.dispatching`；
2. Attempt `claimed → starting`，保存 callback digest、可选 deadline/log artifact，并追加 `attempt.starting`。

两个 event 各自消耗一个 Run version/event sequence，但整个 transaction 要么全部提交，要么全部回滚。事务失败时不得调用 launcher。callback 明文只在进程启动调用栈中传给 launcher，不进入数据库、Event、日志或 coordinator 返回值。

### 3. spawn 后必须原子保存耐久 ownership

launcher 仍按 ADR-0069 在用户代码前登记 receipt journal、验证同一 launcher fd 并捕获 exact Linux identity。返回后 coordinator 复核 handle/PID/timestamp，再在第二个 Repository transaction 内依次 CAS：

1. Attempt `starting → running`，保存完整 durable handle、PID 与 started time，追加 `attempt.running`；
2. Run `dispatching → running`，保存 started time，追加 `run.running`。

只有第二个 transaction 提交后调用方才能观察到成功启动。重复调用因 aggregate 已离开 `queued/claimed` 被拒绝，不通过内存 active map 决定唯一性。

### 4. 两类失败使用不同终态与补偿

launcher 在取得可返回 durable ownership 前失败时，它已保证任何可能 spawn 的进程组被停止。coordinator 将 `starting/dispatching` 在一个 transaction 内收敛为 Attempt/Run `failed`，错误码为 `EXECUTOR_START_FAILED`。

若 launcher 已返回 durable handle，但 running ownership transaction 失败，coordinator 必须先通过 `LocalProcessController` 停止 exact identity：

1. 解析 handle 并复验 boot ID、PID、process group 与 start ticks；
2. 只对匹配进程组发送 TERM，并在有界 grace 内复验；
3. 升级 KILL 前再次复验完整身份，PID 已退出或复用时不得 signal；
4. 只有 `stopped`/`already_exited` 才把 aggregate 原子标为 `lost`；
5. `unknown`、provider unavailable、signal failure 或 timeout 时保留 `dispatching/starting`，由 ADR-0068 startup recovery 继续 fail-closed 裁决。

补偿终态自身写失败时也保留 durable starting fact；不能为了返回一个整洁错误而伪造进程已停止。

### 5. 本切片不增加常驻资源

coordinator 是一次性调用对象，没有 timer、watcher、队列、active handle map、第二数据库连接或目录扫描。edge 与 standalone 执行相同安全语义；Profile 差异仍只存在于 recovery/cleanup cadence 和后续 admission/并发预算。cluster-control/Worker 使用 Session/Lease/attestation authority，不复用本机 PID 协议。

## 被否决的替代方案

1. **把 launcher 直接交给 scheduler/stack**：允许未提交 start intent 的 spawn，拒绝。
2. **继续复用 legacy PrimaryRunOrchestrator**：重新依赖 legacy domain、Sequelize、全局 lifecycle，拒绝。
3. **把协调逻辑放进 local-process**：基础设施开始持有 Run 状态与 Repository 策略，形成错误依赖方向，拒绝。
4. **spawn 后写失败直接 lost**：无法证明原进程已停止，会制造双执行，拒绝。
5. **用裸 PID 或只检查一次 identity 后 TERM/KILL**：PID 可复用，TERM 与 KILL 之间身份也可能变化，拒绝。
6. **用 process-local active map 防重**：跨 worker/重启无效，且绕过数据库 aggregate CAS，拒绝。

## 影响与未完成项

已完成：

- 独立 local-execution importer 与 production dependency/source/lock 审计；
- `queued/claimed → dispatching/starting → spawn → running/running` 两段原子协议；
- callback plaintext 隔离、digest 持久化和 sequence fence；
- pre-ownership failed 与 post-spawn exact stop + lost/starting 补偿；
- TERM/KILL 前 exact durable identity 复验；
- local-application 私有装配 coordinator，不再向 stack 暴露 coordinator 或 launcher；
- ADR-0071 的有界 dispatcher、不可变 execution revision/context recipe、Secret-first materializer、Artifact admission 与输出 hard quota；
- 真实 Node 24 SQLite 的成功、启动失败、持久化失败、补偿不确定和重放拒绝测试。

仍未完成：

- 具体加密本机 Secret provider、Task definition 管理权限/审计与 Artifact retention/read stack；
- ADR-0072 已闭环 live completion receipt、cancellation、timeout 与 shutdown drain；仍缺 retry 的安全产品入口与协调；
- 对 controller 的 Linux x64/arm64、PID namespace、权限拒绝、断电与固定物理路由器门禁；
- target executable、systemd/Docker/s6 controller 和 API/UI 状态。

因此本 ADR 交付的是可安全调用的 3.0 本机启动内核，不表示已有 scheduler 生产入口，也不授权插件、AI Agent 或旧 Cron 直接执行命令。

## 验证

1. launcher 观察到数据库已是 `dispatching/starting`，callback digest、deadline 与前两条 Event 已提交。
2. 成功启动后 Run/Attempt 为 `running/running`，version/event sequence 连续为四次推进，callback plaintext 不在返回值中。
3. launcher failure 收敛为双 `failed`，不会调用 durable controller。
4. running transaction 注入失败时，exact controller 先被调用；stop 成功后双 `lost`。
5. stop unavailable 时 aggregate 保持 `dispatching/starting`，重启恢复候选仍可发现。
6. controller 在 TERM 与 KILL 前都复验 full identity；invalid handle 不发 signal。
7. 第二次启动同一 Attempt 被 durable aggregate 拒绝。