qinglong/docs/adr/ADR-0226-bounded-plugin-package-workflow-frontier.md

# ADR-0226：有界 Plugin Package Workflow Frontier

- 状态：Proposed
- 日期：2026-07-30
- 关联 RFC：QL-RFC-0001 D-03、D-207、D-212
- 关联 ADR：ADR-0156、ADR-0223、ADR-0224、ADR-0225

## 背景

ADR-0223 至 ADR-0225 已把 generation-bound Workflow DAG 原子展开为一个
runtime-owned Workflow Run、全部 StepRun、Event/mutation 与 admission receipt。
准入后的 Workflow Run 固定为 `running`，而 Task root StepRun 为 `ready`、其余
StepRun 为 `pending`。

首次 PostgreSQL HA 重跑暴露出一个恢复边界错误：通用 Cluster Run recovery 把没有
RunAttempt 的 Workflow 聚合 Run 识别成孤儿执行。该判断对普通 Task Run 成立，但
Workflow Run 本身是编排聚合，不应直接进入普通 Task dispatcher，也不应伪造一个
RunAttempt 或终态绕过恢复。

同时，低配 Edge 不能为每个 dormant Workflow 建立 timer、watcher 或内存队列；Cluster
多副本也不能依赖进程内 frontier。

## 决策

### 1. 通用恢复器排除 Workflow 聚合

PostgreSQL 通用 recovery source 必须排除
`trigger_type='plugin_package_workflow'`。这不是忽略孤儿工作，而是明确 ownership：

- 普通 Task Run/RunAttempt 继续由既有 Cluster recovery 处理；
- Workflow 聚合 Run 只由专属 Workflow frontier/recovery 处理；
- Workflow 的 Task Step 后续仍必须通过既有 RunAttempt/Executor fence 启动，不能把
  聚合 Run 作为普通 Task 分发。

### 2. 纯 frontier 契约留在现有 runtime-core

新增显式 subpath
`@qinglong/runtime-core/plugin-package-workflow-frontier`，不新增 workspace package、
第三方依赖、进程或连接。一次 resolution 只接受：

- exact normalized immutable plan；
- exact runtime-owned `plugin_package_workflow` Run fence；
- 与 plan 一一对应的最多 128 个 durable StepRun；
- 单调的存储 observation time。

契约对完整 StepRun 集合、Run/Project/Workflow/publication identity、Task
definition ref/digest 和 record digest 失败关闭。

### 3. 一次纯计算收敛依赖 frontier

resolution 使用确定性规则：

1. pending Step 的所有 `needs` 都为 `succeeded` 时生成 `pending → ready` mutation；
2. 任一祖先为 `failed|skipped|cancelled|timed_out` 时，依赖失败可在同一 pass 传递，
   下游生成 `pending → skipped`，result code 固定为
   `dependency_not_succeeded`；
3. mutation 按 canonical Step key 顺序绑定连续 Run version/event sequence；
4. frontier event ID 不超过双方言共有的 36 字节，mutation ID 由 plan、StepRun
   identity/version 与目标状态做 domain-separated digest；
5. resolution 返回 projected ready StepRun ID，但不把读取结果解释为执行 claim。

当全部 required StepRun 终结时，纯契约给出固定的 Run terminal 建议：
`failed/skipped → failed`，其次为 `timed_out`、`cancelled`，全部成功才为
`succeeded`。terminal transition 同时绑定 expected Run version/event sequence、
固定 error code、finished time 和不超过 36 字节的确定性 RunEvent identity；storage
adapter 必须把它与本轮 StepRun mutation 原子提交。

### 4. 双方言使用同一 port，不新增 package

同一显式 subpath 公开最多 64 条的 keyset candidate page 和
`listCandidates/advance` repository port：

- SQLite adapter 位于既有 `@qinglong/local-sqlite`，复用单
  `LocalSqliteOperationAuthority` 和 `BEGIN IMMEDIATE`；candidate SQL 只返回可推进
  pending dependency 或全部 StepRun 已终结但聚合 Run 未终结的 Workflow，不为 root
  ready 或等待中的 Workflow 制造空写；
- PostgreSQL adapter 位于既有 `@qinglong/cluster-postgres`，由 caller 驱动有界
  keyset page；`advance` 使用短 `SERIALIZABLE` transaction，锁定聚合 Run 和完整
  StepRun 集合，使用数据库 transaction clock，并对 serialization/deadlock 做有界
  fresh-client retry；
- 两者都先验证 immutable plan、Run identity 和所有 StepRun canonical JSON/mirror，
  再按 StepRun version/digest/status CAS；一轮只更新一次聚合 Run，version/event
  sequence 按 mutation 数加 terminal event 数整体推进；
- StepRun、RunEvent、StepRunMutation 和 terminal Run/Event 同事务提交，任一 drift、
  fence 或写入冲突整体回滚；已终态 aggregate 重放只读收敛为 `settled`。

没有新增 migration、workspace package、第三方依赖、连接、timer、watcher 或后台
scanner。ready Task 的执行 admission 仍必须在后续原子绑定 StepRun 与
RunAttempt/Executor fence，frontier 的 ready projection 本身不是执行 claim。

### 5. admission replay 只冻结准入证据，不冻结当前执行状态

双方言 admission exact replay 继续严格验证 immutable plan、receipt、初始 RunEvent、
初始 StepRun mutation 与 admission step ledger，但不再要求当前 Run/StepRun 永远停在
准入初态。当前 aggregate 只允许合法运行/终态、identity 不变、canonical record
完整且 version/event sequence 单调；初始 Event 查询固定截止 admission final sequence。
因此合法 frontier/Executor 推进后仍可 inspect/exact replay，而历史准入证据缺失或漂移
仍失败关闭。

## 不采用方案

### 把 Workflow 聚合 Run 交给普通 dispatcher

拒绝。聚合 Run 的 `taskId` 是 Workflow ID，revision 是 publication digest，不是一个
普通 Task execution revision；直接分发会错误解释定义并把一个 DAG 当成一次 Task。

### 为恢复器伪造 RunAttempt 或把聚合 Run提前置为终态

拒绝。伪造 Attempt 会制造不存在的执行事实；提前终结会隐藏尚未执行的 ready/pending
StepRun。

### 每 Workflow 常驻 coordinator

拒绝。它给低配路由器增加空闲内存、唤醒与写放大，并让 Cluster 正确性依赖进程内
ownership。

### 新建 workflow package

拒绝。纯契约没有独立部署、重依赖或权限域，另拆会违反 D-207 的 package 粒度标准。

## 当前验证

1. 通用 PostgreSQL recovery SQL 影响评估为 LOW，新增 Workflow trigger exclusion；
2. runtime-core 405/405，包含 frontier 纯契约 6/6 与后续 Attempt admission 4/4；
3. `local-sqlite` 180/180；真实 SQLite frontier 覆盖 dependency ready、失败向下游
   skipped、成功/失败 aggregate terminal、bounded page、drift rollback、settled 与
   admission-after-progress exact replay；
4. `cluster-postgres` 223 pass、1 条无测试 URL 条件 skip；mock 契约覆盖
   `SERIALIZABLE`、Run/StepRun row lock、单 aggregate CAS、terminal 原子写、
   40001 fresh-client retry、settled 与显式 subpath；
5. PostgreSQL 18.4 arm64 physical HA 在禁止 image pull 下完整通过，包含
   `remote_apply`、timeline 1→2、旧主 fencing、promotion、`pg_rewind` 和两 fresh
   control replicas；新增
   `pluginPackageWorkflowFrontierTerminalizesAtomically`、
   `pluginPackageWorkflowFrontierExactlyReplays`、
   `pluginPackageWorkflowFrontierSurvivesPromotion` 三项 gate，总
   `passed=true`；
6. HA durable facts 为 1 个 Workflow admission、5 个 Workflow RunEvent、3 个
   StepRunMutation；promotion 后 frontier 返回同一 `succeeded/settled` winner，
   admission 仍 exact replay；
7. workspace 仍为 20 个 package，未新增生产依赖或常驻资源。

## 尚未关闭

1. ready Task StepRun 到 RunAttempt/Executor 的原子执行 admission；
2. Workflow 取消、超时和 Task post-start recovery；
3. frontier caller 与 Local application/Cluster control 生命周期装配；
4. Edge/Standalone 真实断电、资源门和产品 API/CLI/UI。