qinglong/docs/adr/ADR-0229-local-workflow-task-runtime-lifecycle.md

# ADR-0229：Local Workflow Task 单 cadence 运行生命周期

- 状态：Proposed
- 日期：2026-07-30
- 关联 RFC：QL-RFC-0001 D-18、D-19、D-71、D-115、D-175、D-207、D-212、D-213
- 关联 ADR：ADR-0066—0072、ADR-0223—0228

## 背景

Workflow admission、frontier、Task Attempt admission、cancellation 和 recovery
已经在共享领域层及 SQLite/PostgreSQL adapter 中存在，但 Local application 仍只有
普通 Run-centric scheduler/execution lifecycle。直接把 Workflow aggregate Run 交给
普通 dispatcher 会把 Workflow ID/publication digest 当成 Task identity；普通
completion/control/recovery 又会提前终结父 Run。

Local application 已经拥有 scheduler cadence、execution control cadence、单 SQLite
operation authority、completion receipt 与受审 POSIX launcher。新增 Workflow timer、
数据库连接、表或 workspace package 会增加路由设备空闲成本，也会制造第二套停止顺序。

## 决策

### 1. 一个 scheduler cadence 承载完整 Workflow 前进顺序

`LocalWorkflowSchedulerCoordinator` 是无 timer 的组合器，每个 cycle 固定执行：

1. 整体 Workflow cancellation convergence；
2. 普通 schedule；
3. Workflow frontier；
4. generation-bound Task Attempt admission；
5. 有界 local dispatch。

它复用既有 `LocalSchedulerLifecycle`。Edge 每轮 cancellation 4×1、frontier 1×1、
Task admission 1×1、dispatch 1；Standalone 分别为 32×4、16×4、16×4、dispatch
4。任何阶段失败都由原 lifecycle 隔离并在下一 cadence 重试，不增加 per-Workflow
timer、watcher、listener 或后台扫描。

### 2. Workflow Task 执行只推进 Attempt/StepRun

Local dispatch candidate 可以携带 `stepRunId`。只有 immutable Task admission ledger
与 exact ready StepRun 同时存在时，父 Run 为 `running` 的 Task Attempt 才可派发。
prepare、running、start-failure、completion、timeout 和 cancellation 都经窄
`LocalWorkflowTaskExecutionRepository` 在一个 `BEGIN IMMEDIATE` 中推进 Attempt、
StepRun、Run counter 与 Event/mutation；父 Workflow Run 保持 `running`，最终状态只
由 frontier 汇总。

普通 Run 仍要求 latest Attempt，并保持既有 `queued→dispatching→running→terminal`
语义。Workflow 分支不能改变普通 Run 的 retry、completion 或 cancellation contract。

### 3. 启动恢复按聚合类型分流

普通 startup recovery 明确排除存在 immutable Workflow admission 的父 Run。专用
Workflow Task recovery 以 Attempt 为单位：

- orphaned claimed Attempt 写 `lost`，并把 StepRun 刷新为新的 ready epoch；
- starting/running 先读取 authenticated completion receipt；
- 没有 receipt 时只接受 exact persisted process identity 的两次一致 live inspection，
  或可信 not-running evidence；
- unknown、缺 handle、身份变化和平台不可验证一律失败关闭。

恢复不终结父 Workflow，也不拥有 timer。

### 4. completion identity 与 Workflow portable identity 统一

Workflow plan 已明确使用最长 36 字节的 portable Run identity，Task admission 生成
`wta:<32 hex>` deterministic Attempt identity。Local completion receipt/journal 过去
只接受 UUIDv7，导致 adapter 单测通过而真实 launcher 永远在请求校验处失败。

receipt、journal 和文件分片统一接受
`[A-Za-z0-9][A-Za-z0-9._:-]{0,35}`。UUIDv7 是该集合的子集；空值、前导点、斜杠、
反斜杠、空白、NUL 和超长 identity 继续拒绝，因此没有扩大目录穿越 authority。

### 5. startedAt 绑定 spawn 前 durable barrier

launcher 在 spawn 前登记 journal，并把同一个 `handle.startedAtMs` 写进不可覆盖
receipt。coordinator 必须把 Attempt/StepRun 的 `startedAtMs` 保存为该 handle fact，
不能在 spawn 后用新的 wall-clock observation 覆盖。否则合法 receipt 会因早于
Attempt start 而被 quarantine。

Event 时间仍必须不早于 Run/Attempt creation；时间回退继续失败关闭。

### 6. 停机先冻结 admission，再 drain execution

application stop 顺序保持：

1. `LocalSchedulerLifecycle.stopAndDrain()`，冻结新 Workflow/Task admission；
2. `LocalExecutionControlLifecycle.stopAndDrain()`，对在途进程提交 shutdown intent、
   exact stop 与 Step-scoped terminal/recovery；
3. 关闭共享 SQLite storage 和 adoption fence。

并发 stop 复用同一个 promise，不产生第二轮 scheduler 或重复 Attempt。

## 不采用的方案

### 新建 `local-workflow` workspace package

拒绝。该能力没有独立部署或依赖边界；组合器、执行 port、SQLite adapter 分别属于既有
local-execution/local-sqlite/local-application。继续拆包会产生更多单文件 package。

### 为每个 Workflow 创建 timer 或 child Run

拒绝。前者增加路由器唤醒/RSS，后者复制 Run/取消/recovery authority，并破坏 same-Run
StepRun fence。

### 保留 receipt UUIDv7-only 并把 deterministic Attempt 强制改为随机 UUID

拒绝。会破坏 admission 的可重算 exact replay，也与已经受审的双方言 portable
identity contract 冲突。严格 portable 字符集在保持路径安全的同时覆盖两类 Run。

## 当前验证

1. `runtime-core` 419/419、`local-process` 18/18、`local-execution` 30/30、
   `local-sqlite` 189/189；
2. macOS application 全量 41 项为 38 pass、3 条 Linux 条件 skip、0 fail；
3. 本机已有 `node:24-bookworm-slim` 镜像在 `--pull never --network none` 下执行真实
   Linux product vertical：两步 Workflow 全部成功，每个 Step 恰好一个 Attempt，
   两条 admission，无重复 dispatch；
4. 启动前用户取消的 Workflow 在 application 首轮 cadence 原子收敛为 cancelled，
   普通 Run recovery 扫描为 0，且没有启动 Attempt；
   Linux 产品门还覆盖在途 Local Task：等待真实 PID/Attempt/StepRun running，
   持久化父 Workflow 取消意图，先停止进程，再将 Attempt/全部 StepRun/父 Workflow
   精确收敛为 cancelled；
5. PostgreSQL 18.4 arm64 physical HA 新增独立
   `pluginPackageWorkflowTaskAttempt*` 五项 gate：原子提交、exact replay、
   `remote_apply` 晋升前复制、runtime-only ACL、timeline 1→2 后存活全部为 true；
6. HA 继续完成旧主 fencing、`pg_rewind` 只读同步重入、两个 fresh control replica，
   `gates.passed=true`，并使用 `QL3_HA_SKIP_IMAGE_PULL=true`；
7. 真实 Local Workflow 已进入既有 Linux resource gate，没有新增 workspace
   package、依赖或常驻 cadence。arm64 Node 24.18.0 的 128 MiB/0.5 CPU 档
   `memory.peak=120217600`、Workflow process peak RSS `87449600`、RSS delta
   `16908288`，16 次 admission write-lock p95 `4.053 ms`；256 MiB/1 CPU 档
   `memory.peak=121344000`、Workflow process peak RSS `87949312`、RSS delta
   `17408000`，32 次 write-lock p95 `3.317 ms`。两档 `memory.events` 的
   max/OOM 增量为零，并完成 Edge/Standalone admission 与
   conclusive-stop/control-terminal 两组各 16 个
   `SIGKILL → reopen → exact replay` 场景。
8. PostgreSQL 18.4 arm64 HA 已完成 Remote Workflow
   `stop_requested → completion response loss/exact replay → parent convergence
   response loss/exact replay → promotion 后再次 replay`；Run/Attempt/StepRun
   cancelled、Lease completed@v6，独立四项 gate 和总 `passed` 均为 true。

## 尚未关闭

1. 固定 Edge/Standalone 物理路由设备报告、闪存/FTL 写放大、真实 ENOSPC 与受控
   突发断电门；CI `SIGKILL` crash matrix 明确不等同于物理断电；
2. Linux x64/arm64 的长期 CI 成功记录和实际低配设备基线。