qinglong/docs/adr/ADR-0227-generation-bound-workflow-task-attempt-admission.md

ADR-0227：Generation-bound Workflow Task Attempt 准入

• 状态：Proposed
• 日期：2026-07-30
• 关联 RFC：QL-RFC-0001 D-03、D-207、D-212
• 关联 ADR：ADR-0031、ADR-0105、ADR-0223、ADR-0226、ADR-0228

背景

ADR-0223—0226 已把 Plugin Package Workflow 原子展开并推进到 ready StepRun。 现有 Local/Cluster dispatch 与 activation 则是 Run-centric：

• candidate 从 Run 读取 taskId/taskRevision；
• Local activation 要求 Run 为 queued 且 Attempt 是该 Run 的 latest；
• Cluster dispatch 要求 Run 为 queued|dispatching，同样排除非 latest Attempt；
• activation 会把 Run 自身推进为 dispatching|running。

这些约束适用于一个 Run 表示一次 Task 执行的普通路径，却不能直接用于 Workflow aggregate。Workflow Run 的 taskId 是 Workflow resource ID，taskRevision 是 automation publication digest，Run 已为 running，而一个 DAG 还可能有多个 ready StepRun。直接复用现有 candidate 会把 Workflow 当 Task 执行；只创建 RunAttempt 也 无法给 executor 提供正确、generation-bound 的 TaskDefinition 和 execution revision。

materialized Workflow plan 当前故意绑定 Package source Task 和 source digest；真正可执行 的 runtime Task identity/revision 要由同 generation 的 Task reconciliation 生成： pkg:<package>:<resource-task> 与 qltd:v1:<revision>:<task-definition-content-digest>。它不能在执行时从 current head 临时读取，否则长期运行的 Workflow 会混入后续 Package generation。

决策

1. 在 source plan 与 executor 之间增加原子 Attempt admission ledger

新增现有 runtime-core 的显式 subpath plugin-package-workflow-task-attempt-admission，不新增 workspace package。一次纯 admission 必须同时接受并验证：

• exact immutable Workflow plan、running aggregate Run 与一个 exact ready Task StepRun；
• 与 plan generation/project/package/lock/materialized revision 全匹配的 immutable Task reconciliation receipt；
• 一个完整且可重新计算 digest 的 Local 或 Cluster immutable execution revision；
• storage 分配的 Run-global Attempt number 和单调 database observation time。

契约从 reconciliation item 推导 runtime Task identity 和 qltd:v1 revision，拒绝 caller 单独声称 task/execution digest。Local revision 固定 local_process，Cluster revision 固定 remote_worker。

2. 一次 admission 只创建执行意图，不伪造已启动状态

纯结果包含：

• deterministic、双方言可写的最多 36 字节 Attempt ID 与 RunEvent ID；
• 带 stepRunId、Run-global Attempt number、claimed 和 exact executor type 的 RunAttempt；
• workflow.task_attempt_admitted Event；
• 保持 running、只推进一次 version/event sequence 的 aggregate Run；
• 绑定 plan、ready StepRun version/digest、reconciliation receipt digest、runtime Task identity/revision、TaskDefinition digest、execution digest、Attempt/Event/Run fence 的 immutable receipt。

StepRun 在 admission 时仍为 ready，因为 claimed 只表示 durable dispatch intent， 不等于进程/Worker 已启动。StepRun 的 attemptCount 继续只在进入 running 时增加。 后续 StepRun-aware activation 必须原子推进 Attempt 与 StepRun；不能在本 ADR 中提前 写 running。

3. 双方言 adapter 使用短事务与 current-ready-epoch 唯一性

双方言实现必须：

• 以 (run, stepRun, stepRunVersion) 作为一个 ready epoch 的 exact replay 边界；
• 在 Run lock 下分配 Run-global Attempt number，插入 Attempt、Event、admission receipt 并对 aggregate Run 做一次 CAS；
• candidate page 最多 64 条，只列 ready 且当前 epoch 尚无 admission winner 的 StepRun；
• SQLite 复用单 operation authority 和 BEGIN IMMEDIATE；Cluster 使用 caller-driven keyset 与短 SERIALIZABLE transaction；
• COMMIT response loss 只读取 durable receipt，不生成第二个 Attempt；
• 不新增 timer、watcher、listener、per-Workflow coordinator、连接或缓存。

4. execution activation 必须新增 StepRun-aware 路径

现有普通 Task Run dispatcher/activation 保持不变。Workflow Attempt candidate 后续从 admission ledger 读取 Task identity/revision/execution digest，并按 StepRun 而不是 “latest Attempt of Run”围栏。Local/Cluster activation 都必须保留 aggregate Run 为 running，原子推进 Attempt 和对应 StepRun，允许多个独立 ready Step 并行，同时仍由 Run version/event sequence 作为 aggregate serialization boundary。

Cluster 路径复用现有 cluster-postgres repository、run_attempts 和 run_dispatch_leases，不新增 Workflow executor package 或第二套 lease 表。 dispatcher 通过 immutable Task Attempt admission ledger 投影 Task project/revision/execution identity，并按 StepRun 检查 newer Attempt；普通 Task Run 继续使用原 Run-centric 条件。lease claim、starting、running、start failure 和 completion 都在同一个 repository 内按 ledger 是否存在分支，普通 Run 行为不变。

Workflow Task activation/completion 的 aggregate 规则固定为：

• 父 Run 始终保持 running，只推进 version/event sequence；
• Attempt 保存 Worker/Lease/callback/Artifact terminal evidence；
• StepRun 通过 canonical mutation/event 推进，attemptCount 只在进入 running 时增加；
• starting 后 Worker 直接完成的崩溃窗口必须原子补写 ready → running → terminal，不能跳过 StepRun start barrier；
• terminal completion exact replay 绑定 immutable Attempt/Event，即使父 Run 后续因 其他步骤取消或终结也不能改写历史结果。

5. Attempt deadline 是 Task 级停止意图，不是父 Run 取消

Workflow Task 的 deadline_at_ms 到期时，Remote Worker lease control 必须返回 stop_requested(timeout)，并以 StepRun/Attempt 绑定的 workflow.task_timeout_requested Event 留下 durable audit，但不得写父 Run 的 cancel_requested_at_ms。完成或 start-failure 回执以数据库观察时间复验 deadline， 将该 Attempt/StepRun 收敛为 timed_out；父 Run 由 frontier 汇总所有 StepRun 后决定 最终状态。

用户、Policy、shutdown 等明确的整 Run cancel intent 仍保存在父 Run，并可投影到所有 在途 Worker。Task deadline 与 Run cancellation 必须保持两个 authority，避免一步超时 取消整个 DAG。

6. Workflow Task recovery 必须拥有独立的 StepRun 语义

现有通用 lost transition 是单 Run/单 Attempt 模型，会把 active Attempt 与父 Run 一起标记为 lost，因此 Workflow aggregate Run 仍按 trigger type 排除。Task Attempt 则可以复用同一个有界 recovery source、run_recovery_controls claim 与 evidence provider，但 resolution 必须通过 immutable admission ledger 识别 workflow_task scope，禁止执行 mark_attempt_and_run_lost。

pristine、尚未获得 lease 的 claimed Workflow Task Attempt 是正常 dispatcher backlog， 不得因为 lease_expires_at_ms IS NULL 被当成 lost。获得过 lease 且过期后：

• claimed 尚未跨过 start barrier，没有外部副作用；旧 Attempt 写为 lost，exact ready StepRun 以 ready→ready 增加 version/digest，保持 attempt count、ready time 与父 Run running，从而产生一个可再次 admission 的新 epoch；
• starting 或 running 已存在外部副作用不确定性，只有可信 not_running evidence 才能恢复；Attempt 写为 lost，StepRun 收敛为 failed。running 路径必须保留 running→lost→failed Event/mutation 链。v1 没有 Step 级幂等/去重策略，因此跨过 start barrier 后禁止静默自动重试。

PostgreSQL resolution 在 live claim fence 下先取得与 activation/completion 相同的 Attempt advisory authority，再复验 Run、Attempt、admission receipt 与 canonical StepRun snapshot，并在一个事务内 CAS 父 Run counters、Attempt、StepRun，追加 Attempt Event、StepRun Event 与 mutation。父 Run 状态不变，最终状态继续由 frontier 汇总。实现复用现有 runtime-core/cluster-postgres 与 claim 表，不新增 workspace package、lease/recovery 表或常驻 timer。

不采用方案

把 Workflow aggregate 改回 queued 并复用普通 dispatcher

拒绝。它会把 Workflow ID/publication digest 当成 TaskDefinition identity，并且一次 latest Attempt 模型无法表达 DAG 并行 Step。

为每个 Step 伪造 child Run

拒绝。现有 StepRun 与 RunAttempt 的 same-Run 外键会被破坏；额外 child Run 还会复制 Workflow/Step 状态、取消、重试和终态语义，制造双聚合。

在 dispatch 时读取 current TaskDefinition head

拒绝。current head 可能已属于后续 Package generation，导致一次 immutable Workflow 执行混合不同 generation。

只保存 taskId/taskRevision，不验证完整 execution revision

拒绝。caller 可伪造 execution digest 或 executor type；必须使用既有 Local/Cluster normalizer 重新计算完整 immutable revision。

新建 workflow-executor package

拒绝。当前能力没有独立部署、重依赖或权限域，复用 runtime-core 与双方言 storage subpath 更符合 D-207。

当前验证

1. GitNexus 对 admission、dispatch、lease、activation、completion、lease control 和 recovery source 的影响均为 LOW；普通 Task Run 分支保留原行为；
2. SQLite v42 已完成 immutable ledger、readiness 与 BEGIN IMMEDIATE adapter； PostgreSQL pg-0046/control-core v45 已完成 ledger、runtime-only snapshot、 六角色 readiness 与短 SERIALIZABLE adapter；
3. Cluster 已覆盖 bounded candidate、per-Step newer Attempt、父 Run 不变的 lease、 starting/running/start-failure/completion、starting crash window、Task deadline 和父 Run 后续取消后的 exact replay，并已实现 admission-bound 专用 recovery；
4. ADR-0228 已补齐双方言整 Workflow cancellation convergence：取消后冻结 frontier/admission，尊重 start barrier，最后终结父聚合；
5. runtime-core 419/419、local-sqlite 185/185；cluster-postgres 237 项为 236 pass、1 条件 skip、0 fail；
6. 全新 PostgreSQL 18.4 六角色实例已完成 Task admission→recovery→requeue→ second admission→whole cancellation；
7. PostgreSQL 18.4 arm64 physical streaming HA 在 QL3_HA_SKIP_IMAGE_PULL=true 下通过：remote_apply、timeline 1→2、旧主先 fencing、pg_rewind 只读同步重入、两个 fresh control replica 与总 gates.passed=true；
8. workspace 仍为 20 个 package；本切片没有新增 package、第三方依赖、migration、 timer、watcher、listener、缓存或第二套 lease/cancellation 表。

尚未关闭

1. Local StepRun-aware activation、completion、deadline 与真实断电门；
2. application/control lifecycle 装配、并行度/背压、产品入口和真实低配资源门；
3. 在途 Worker stop_requested→completion/recovery→父 Workflow terminal 的产品 crash-window 门；
4. 在 PostgreSQL HA fixture 中增加 Workflow Task admission→dispatch→activation→ completion/timeout→promotion replay 的独立 domain gate。