[P2] engine ADR: durable pause inside structured regions (unlock topology-level parallel approvals / waits / subflows) #3267

Restart-when: objectstack-ai/cloud#861 (Phase 3 EE governance) is scheduled, or a real customer / example scenario needs durable suspension inside a parallel branch (parallel approval, wait signal, or a subflow containing a pause)

审批增强三阶段中的 Phase 2(引擎线):Phase 1 = #3266(节点内 quorum/会签,不依赖本 issue)→ 本 issue → Phase 3 企业版治理(objectstack-ai/cloud#861)。产出物是一份 ADR + 实现。

现状(硬限制)

流引擎的结构化区域(parallel / loop 容器)禁止持久挂起:

• service-automation/src/engine.ts:2388-2412 — “Durable pause (suspend) inside a region is not supported … converted into a clear error”
• builtin/parallel-node.ts:33-34 — 分支内 durable pause 为硬错误
• engine.ts:363-366 — “durable pause across parallel gateways is out of scope for ADR-0019 M1”

因此凡是需要挂起的节点(approval、signal wait、含挂起的 subflow)都进不了 parallel 区域;现有 parallel 块仅服务同步工作(Promise.all,parallel-node.ts:82)。

为什么以引擎通用能力立项(而不是审批特性)

受益方不止审批:并行分支内的 wait 信号等待、subflow 嵌套挂起(现有 linked-runs 模型已支持单链,见 showcase ClosureSignoffSubflow)、未来任意 human-task 节点。审批只是第一个消费者——Phase 1(#3266)已用节点内语义解决主流场景(钉钉/Salesforce 模式),本 issue 解锁的是拓扑级并行(跨对象、跨记录、审批+等待混排的复杂编排,即 Camunda parallel gateway + multi-instance 一类能力)。

ADR 需要决策的问题

1. 挂起状态模型:区域内多点挂起时 SuspendedRun 如何表示(单 run 多 suspension?子 run per branch,复用 linked-runs?)
2. join 语义:全部完成 / 任一完成(competing)/ N-of-M 完成;失败分支对 join 的影响
3. 审批约束联动:“每记录一个 pending 请求”(approval-service.ts:479)在拓扑并行下如何演进——多请求并存时的记录锁、approvalStatusField 镜像、收件箱呈现
4. 恢复语义:多挂起点的 resume 幂等性、乱序 resume、部分分支 recall
5. 兼容性:现有同步 parallel 块行为不变;BPMN interop 映射(bpmn-interop.zod.ts 的 parallel_gateway/join_gateway)是否借此落地执行语义

验收

• ADR 提交并 accepted(含上述 5 项决策)
• 引擎:区域内挂起/恢复 + join 语义实现,现有同步 parallel 行为零回归
• 两个 approval 节点在并行分支同时 pending、join 后推进的端到端用例
• wait 信号节点在并行分支内可用
• 文档(flows.mdx / approvals.mdx)更新

Generated by Claude Code