qinglong/docs/adr/ADR-0228-bounded-plugin-package-workflow-cancellation-convergence.md

# ADR-0228：有界 Plugin Package Workflow 整体取消收敛

- 状态：Proposed
- 日期：2026-07-30
- 关联 RFC：QL-RFC-0001 D-18、D-19、D-71、D-117、D-207、D-212、D-213
- 关联 ADR：ADR-0072、ADR-0118、ADR-0121、ADR-0226、ADR-0227

## 背景

Workflow Task 已有 generation-bound admission、StepRun-aware
activation/completion 和专用 recovery，但普通 Run cancellation convergence
一次只处理一个 Run 与最新 Attempt。Workflow aggregate 则以同一个 Run 承载最多
128 个 StepRun 和多个 Task Attempt；直接复用普通逻辑会出现三类错误：

1. 父 Run 被提前写为 terminal，而在途 Worker 仍有 execution authority；
2. pending/ready StepRun 继续被 frontier 或 Task admission 推进；
3. 只终结“最新 Attempt”，其余 StepRun 永久不能收敛。

同时，不能为每个 Workflow 或 Step 增加 timer、watcher、child Run、额外 claim 表或
workspace package。Edge/Standalone 的 SQLite 单连接与 Cluster 的 PostgreSQL 多副本
必须共享同一个领域裁决，但采用各自合适的锁和分页策略。

## 决策

### 1. 取消意图只属于父 Workflow Run

`cancel_requested_at_ms` 与 `cancel_reason` 继续写在 aggregate Run。收到意图后：

- Workflow frontier 和 Task Attempt candidate 都必须排除该 Run；
- 不再产生新的 ready StepRun 或 Task Attempt；
- 已 durable 的 Task Attempt 仍由原 activation/completion/recovery authority 收敛，
  cancellation reconciler 不能伪造 Worker 已停止。

### 2. 使用一个 profile-neutral 纯状态机

`runtime-core/plugin-package-workflow-cancellation-convergence` 接收 exact Run、
全部 StepRun、immutable admission-bound active Task Attempt、lease 状态和观察时间，
确定性输出：

- 可安全终结的 claimed、尚未执行 Attempt transition 与 Event；
- non-executing StepRun mutation/Event；
- 仍持有执行 authority 的 blocked Attempt/StepRun identity；
- 仅当 projected StepRun 全部 terminal 时才生成父 Workflow terminal transition。

状态机不读取数据库、不持有连接、不创建 timer，也不决定执行器 stop。输出 ID 由
Run、取消时间、target identity 和 durable epoch 生成，最长 36 字符，可在未知提交
结果后重算。

### 3. start barrier 不能被取消协调器越过

- claimed 且没有 active lease 的 Task Attempt 可以在 exact admitted ready epoch
  直接收敛为 `cancelled|timed_out`；
- claimed + leased、starting、running 一律 blocked，等待 Worker completion 或可信
  recovery；
- running StepRun 即使缺少当前 adapter 可见的 Task Attempt，也保持 blocked，不能写
  假终态；
- pending/lost StepRun 在 aggregate timeout 下写 `cancelled`，因为它们没有实际
  执行超时；ready/waiting_approval 可写 `timed_out`；
- 用户、Policy、shutdown、reconcile 取消统一映射为 `cancelled`；父 Run 的 timeout
  映射为 `timed_out`。

### 4. 父 Run 最后终结

每个可安全 Attempt Event、StepRun mutation/Event 都先消耗连续 aggregate
version/event sequence。只有所有 StepRun projected terminal 且 blocked 集合为空时，
才追加 `workflow.cancelled|workflow.timed_out` 并终结父 Run。部分收敛后父 Run
保持 `running` 和原 cancel intent，后续 caller-driven cycle 继续处理。

一个 Workflow 可以在一页中结算多个 Attempt，因此共享 page result 的
`settledAttempts` 上界从 `settledRuns` 修正为
`scanned * MAX_STEP_RUNS_PER_RUN`；`settledRuns` 和 `blocked` 仍以 aggregate Run
计数。

### 5. PostgreSQL 使用既有 Attempt authority 锁顺序

Cluster adapter 留在 `@qinglong/cluster-postgres` 的显式 subpath/既有 cancellation
repository：

1. 普通非 Workflow Run 保留原 `SKIP LOCKED` 收敛；
2. Workflow candidate 不先锁 Run；
3. 先稳定排序 active Attempt ID，并取得 `pg_try_advisory_xact_lock`；
4. 再锁父 Run、active Attempt、lease 和全部 StepRun，重新读取 immutable admission；
5. 在一个短事务中 CAS Attempt/StepRun/Run，并追加全部 RunEvent 与
   StepRunMutation。

这保持 activation/completion/recovery 的 Attempt authority → Run/Attempt/Step
固定锁序。锁竞争返回 blocked，不以扩大 timeout 或交换锁序处理。

### 6. SQLite 使用每 Workflow 一个短事务

Edge/Standalone adapter 留在既有 `@qinglong/local-sqlite` 包并复用共享
`LocalSqliteOperationAuthority`。一页先有界读取 candidate，但每个 Workflow 单独执行
一个 `BEGIN IMMEDIATE`：

- 页面增大不会把一个 SQLite write lock 放大到整页 DAG；
- 单 Workflow 最多 128 StepRun，内存和写放大有硬上限；
- 中途故障只会留下已完整提交的前序 Workflow，重跑按 durable terminal 状态继续；
- 不增加连接、后台线程、timer、表、migration 或依赖。

## 不采用的方案

### 每个 Step 创建 child Run

拒绝。会复制 Workflow/Step 聚合、取消 intent、版本序列和 recovery authority。

### cancellation reconciler 直接终结 leased/running Attempt

拒绝。stop_requested 不是执行已停止的证据，迟到 completion 可能来自仍合法的 Worker
authority。

### 为 Workflow 新建 cancellation package、表或 cadence

拒绝。该能力没有独立部署、权限或重依赖边界；复用现有 core/storage subpath 更符合
D-207，也避免增加路由器供应链和空闲唤醒成本。

## 当前验证

1. `runtime-core` 共享状态机覆盖全部 non-executing、unleased claim、leased/running
   blocked、timeout 映射、determinism 与 stale admission，完整测试 419/419；
2. `local-sqlite` 在真实内存 SQLite 上完成 Attempt + 两 StepRun + 父 Run 原子取消、
   admission crash 与 conclusive-stop/control-terminal crash 的 exact replay，
   完整测试 189/189；
3. `cluster-postgres` 完整测试 238 项为 237 pass、1 条条件 skip、0 fail；
4. 全新 PostgreSQL 18.4 最小权限六角色实例已完成 admission→recovery→requeue→
   second admission→whole cancellation，连续事件和所有 terminal fact 同事务提交；
5. `QL3_HA_SKIP_IMAGE_PULL=true` 的 PostgreSQL 18.4 arm64 物理 HA 门再次通过
   `remote_apply`、timeline 1→2、旧主先 fencing、`pg_rewind` 只读同步重入、两个
   fresh control replica 与 `gates.passed=true`；
6. Cluster production composition 已复用原有全局 cancellation lifecycle 和同一个
   PostgreSQL repository，因此不增加第二 cadence。
7. ADR-0229 已把 Local cancellation、frontier、Task admission 与 dispatch 接入同一
   scheduler cadence；启动前取消的 Workflow 原子终结两个 StepRun、零 Attempt，
   普通 Run recovery 扫描为 0；
8. PostgreSQL physical HA 已新增独立 Workflow Task Attempt report，原子提交、
   exact replay、晋升前复制、runtime-only ACL 与晋升后存活五项 gate 全为 true；
9. Local 两步 Workflow、每 Workflow 一个 SQLite write transaction，以及
   Edge/Standalone 两组各 16 点 admission 与 conclusive-stop/control-terminal
   crash/reopen/replay 已接入既有 128/256 MiB Linux resource gate。arm64 实测的
   Workflow process peak RSS 分别为 `87449600`/`87949312` bytes，写锁 p95
   分别为 `4.053`/`3.317` ms，cgroup memory pressure/OOM 增量为零；
   workspace 仍为 20 包。
10. PostgreSQL 18.4 arm64 physical HA 新增真实 Remote Workflow cancellation
    矩阵：正式 admission/Task Attempt、`stop_requested`、成功退出映射 cancelled、
    completion 与父 Workflow convergence 两个 COMMIT response-loss 窗口、
    exact replay、`remote_apply`、timeline 1→2 与 promotion 后再次 replay 均通过；
    Run/Attempt/StepRun 为 cancelled、Lease 为 completed@v6，8 个 Event 与 3 个
    StepRun mutation 无重复。

## 尚未关闭

1. 固定 Edge/Standalone 物理设备基线、闪存/FTL 写放大和受控突发断电门；CI
   `SIGKILL` 证据不提升为物理 power-loss 结论。