Control Flow

@module automation/control-flow

Structured control-flow constructs (ADR-0031) — the native + AI-authored flow model: a loop container, a parallel block, and structured try/catch/retry. Unlike BPMN's gateway/boundary/token graph (kept in the protocol for interop only), these constructs are well-formed by construction, locally composable, and statically analyzable — the right substrate for LLM authoring (ADR-0010/0011).

Representation — decision: (B) nested sub-structure

ADR-0031 flagged two ways to carry structured containers in the flat nodes[]+edges[] model:

(A) marker-delimited scoped regions (a container node + a scope-end marker; the body is the edges between them in the main graph), or
(B) the container node carries a nested mini-flow in its config.

We adopt (B). Each container holds its body as a self-contained FlowRegionSchema (config.body for loop, config.branches[] for parallel, config.try/config.catch for try_catch). The reasons:

Well-formed by construction — a nested region is its own graph, so single-entry is intrinsic; there are no scope markers to balance and no way to "leak" an edge across a boundary. Validation is local.
The shared engine traversal stays untouched — the container executor runs its own body via a scoped helper; the main DAG traverseNext never learns about scope markers (important under the multi-agent discipline around engine.ts). The container's ordinary out-edges remain the "after-loop / after-block" continuation.
Cleaner AST for AI — ADR-0031 calls (B) "the cleaner long-term AST," and AI authoring is the design center.

Existing flat-graph loops (a loop node with no config.body) keep their legacy behavior — the constructs are additive, activated only when the nested structure is present.

The canonical construct type ids are LOOP_NODE_TYPE (loop, pre-existing), PARALLEL_NODE_TYPE (parallel), and TRY_CATCH_NODE_TYPE (try_catch). These are distinct from the BPMN interop node types (parallel_gateway / join_gateway / boundary_event), which remain author-invisible interchange representations.

Unknown keys are rejected (#4001 / ADR-0078)

Every shape below is strictObject. Before that they were plain z.object, so zod's default .strip applied and a key this file does not declare was discarded in silence — the container still parsed, still registered, and still ran, with the author's configuration simply absent. On these five shapes that silence is unusually expensive, because each one carries control rather than data: a swallowed maxIterations is an uncapped loop, a swallowed branch key is a branch that runs without what it was given.

How this relates to `validateControlFlow`

validateControlFlow is a sibling guard, not a key gate — it answers "is this region single-entry / single-exit / acyclic", which no amount of key strictness can answer. The two do not overlap and cannot fight: the schema rejects undeclared KEYS, the analysis rejects malformed STRUCTURE. They do now meet at one seam, deliberately — validateControlFlow safeParses each region slot before analyzing it, so from #4001 that parse is also where a region's undeclared key surfaces, reported as <where>: invalid region — <the strictObject message>. Nothing was duplicated and nothing was removed; the structural prose this guard exists for is untouched, and it simply stopped silently repairing its own input.

Source: packages/spec/src/automation/control-flow.zod.ts

TypeScript Usage

import { FlowRegionSchema, LoopConfigSchema, ParallelBranchSchema, ParallelConfigSchema, RetryPolicySchema, TryCatchConfigSchema } from '@objectstack/spec/automation';
import type { FlowRegion, LoopConfig, ParallelBranch, ParallelConfig, RetryPolicy, TryCatchConfig } from '@objectstack/spec/automation';

// Validate data
const result = FlowRegionSchema.parse(data);

FlowRegion

Properties

Property	Type	Required	Description
nodes	`{ id: string; type: string; label: string; config?: Record<string, any>; … }[]`	✅	Region body nodes (single-entry/single-exit sub-graph)
edges	`{ id: string; source: string; target: string; condition?: string \| object; … }[]`	optional	Region body edges

Nested Shape: `FlowRegion.nodes[number]`

Property	Type	Required	Description
id	`string`	✅	Node unique ID
type	`string`	✅	Action type — a built-in FlowNodeAction id or a plugin-registered node type. Validated against the live action registry at registerFlow() (ADR-0018), not by a closed enum.
label	`string`	✅	Node label
config	`Record<string, any>`	optional	Node configuration
connectorConfig	`{ connectorId: string; actionId: string; input?: Record<string, any> }`	optional
position	`{ x: number; y: number }`	optional
timeoutMs	`integer`	optional	Maximum execution time for this node in milliseconds
inputSchema	`Record<string, { type: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>; required?: boolean; description?: string }>`	optional	Input parameter schema for this node
outputSchema	`never`	optional	[REMOVED] `flow.nodes[].outputSchema` was removed in @objectstack/spec 17.0.0 (audit close-out) — it was never validated: the engine does not check node outputs against it, so it documented a contract nothing enforced. Delete the key. Downstream nodes read prior outputs via expressions (`{{nodeId.field}}`) regardless of any declaration. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
waitEventConfig	`{ eventType: Enum<'timer' \| 'signal' \| 'webhook' \| 'manual' \| 'condition'>; timerDuration?: string; signalName?: string }`	optional	Configuration for wait node event resumption
boundaryConfig	`{ attachedToNodeId: string; eventType: Enum<'error' \| 'timer' \| 'signal' \| 'cancel'>; interrupting?: boolean; errorCode?: string; … }`	optional	Configuration for boundary events attached to host nodes

Nested Shape: `FlowRegion.edges[number]`

Property	Type	Required	Description
id	`string`	✅	Edge unique ID
source	`string`	✅	Source Node ID
target	`string`	✅	Target Node ID
condition	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	optional	Predicate (CEL) returning boolean used for branching.
type	`Enum<'default' \| 'fault' \| 'conditional' \| 'back'>`	optional (default: `"default"`)	Connection type: default (normal flow), fault (error path), conditional (expression-guarded), or back (ADR-0044 declared back-edge — traversed normally at run time, but excluded from DAG cycle validation so a revise/rework loop can re-enter an earlier node)
label	`string`	optional	Label on the connector
isDefault	`boolean`	optional (default: `false`)	BPMN default flow: traverse this edge only when no sibling conditional edge of the same source node matched. Mutually exclusive with `condition`; at most one per source node.

LoopConfig

Properties

Property	Type	Required	Description
collection	`string \| any[]`	✅	Template/variable resolving to the array to iterate (an inline array is accepted)
iteratorVariable	`string`	optional (default: `"item"`)	Loop variable holding the current item
indexVariable	`string`	optional	Optional loop variable holding the current index
maxIterations	`integer`	optional	Hard cap on iterations (clamped to the engine ceiling)
body	`{ nodes: object[]; edges?: object[] }`	optional	Loop body region (omit for legacy flat-graph loops)

Nested Shape: `LoopConfig.body`

Property	Type	Required	Description
nodes	`{ id: string; type: string; label: string; config?: Record<string, any>; … }[]`	✅	Region body nodes (single-entry/single-exit sub-graph)
edges	`{ id: string; source: string; target: string; condition?: string \| object; … }[]`	optional	Region body edges

ParallelBranch

Properties

Property	Type	Required	Description
name	`string`	optional	Branch label
nodes	`{ id: string; type: string; label: string; config?: Record<string, any>; … }[]`	✅	Branch body nodes
edges	`{ id: string; source: string; target: string; condition?: string \| object; … }[]`	optional	Branch body edges

Nested Shape: `ParallelBranch.nodes[number]`

Property	Type	Required	Description
id	`string`	✅	Node unique ID
type	`string`	✅	Action type — a built-in FlowNodeAction id or a plugin-registered node type. Validated against the live action registry at registerFlow() (ADR-0018), not by a closed enum.
label	`string`	✅	Node label
config	`Record<string, any>`	optional	Node configuration
connectorConfig	`{ connectorId: string; actionId: string; input?: Record<string, any> }`	optional
position	`{ x: number; y: number }`	optional
timeoutMs	`integer`	optional	Maximum execution time for this node in milliseconds
inputSchema	`Record<string, { type: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>; required?: boolean; description?: string }>`	optional	Input parameter schema for this node
outputSchema	`never`	optional	[REMOVED] `flow.nodes[].outputSchema` was removed in @objectstack/spec 17.0.0 (audit close-out) — it was never validated: the engine does not check node outputs against it, so it documented a contract nothing enforced. Delete the key. Downstream nodes read prior outputs via expressions (`{{nodeId.field}}`) regardless of any declaration. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
waitEventConfig	`{ eventType: Enum<'timer' \| 'signal' \| 'webhook' \| 'manual' \| 'condition'>; timerDuration?: string; signalName?: string }`	optional	Configuration for wait node event resumption
boundaryConfig	`{ attachedToNodeId: string; eventType: Enum<'error' \| 'timer' \| 'signal' \| 'cancel'>; interrupting?: boolean; errorCode?: string; … }`	optional	Configuration for boundary events attached to host nodes

Nested Shape: `ParallelBranch.edges[number]`

Property	Type	Required	Description
id	`string`	✅	Edge unique ID
source	`string`	✅	Source Node ID
target	`string`	✅	Target Node ID
condition	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	optional	Predicate (CEL) returning boolean used for branching.
type	`Enum<'default' \| 'fault' \| 'conditional' \| 'back'>`	optional (default: `"default"`)	Connection type: default (normal flow), fault (error path), conditional (expression-guarded), or back (ADR-0044 declared back-edge — traversed normally at run time, but excluded from DAG cycle validation so a revise/rework loop can re-enter an earlier node)
label	`string`	optional	Label on the connector
isDefault	`boolean`	optional (default: `false`)	BPMN default flow: traverse this edge only when no sibling conditional edge of the same source node matched. Mutually exclusive with `condition`; at most one per source node.

ParallelConfig

Properties

Property	Type	Required	Description
branches	`{ name?: string; nodes: object[]; edges?: object[] }[]`	✅	Branch regions executed concurrently; implicit join at block end

Nested Shape: `ParallelConfig.branches[number]`

Property	Type	Required	Description
name	`string`	optional	Branch label
nodes	`{ id: string; type: string; label: string; config?: Record<string, any>; … }[]`	✅	Branch body nodes
edges	`{ id: string; source: string; target: string; condition?: string \| object; … }[]`	optional	Branch body edges

RetryPolicy

Properties

Property	Type	Required	Description
maxRetries	`integer`	optional (default: `0`)	Retry attempts after the initial one. 0 (the default) means no retry — state a count to opt in.
backoffMs	`integer`	optional (default: `1000`)	Base delay before the first retry (ms); subsequent delays multiply by backoffMultiplier
backoffMultiplier	`number`	optional (default: `1`)	Exponential backoff multiplier; 1 (the default) keeps the delay flat
maxRetryDelayMs	`integer`	optional (default: `30000`)	Ceiling for a single backoff delay (ms)
jitter	`boolean`	optional (default: `false`)	Randomize each delay within [50%, 100%] of its computed value — spreads a thundering herd of simultaneous retries
retryDelayMs	`never`	optional	[REMOVED] `retryDelayMs` was removed in @objectstack/spec 17.0.0 — the retry policy now has ONE spelling for its base delay across every surface that carries it: `job.retryPolicy`, a `try_catch` node's `retry` and `flow.errorHandling`. Rename the key to `backoffMs`; the value (milliseconds before the first retry) is unchanged. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.

TryCatchConfig

Properties

Property	Type	Required	Description
try	`{ nodes: object[]; edges?: object[] }`	✅	Protected region
catch	`{ nodes: object[]; edges?: object[] }`	optional	Handler region run when the try region fails
errorVariable	`string`	optional (default: `"$error"`)	Variable holding the caught error in the catch region
retry	`{ maxRetries?: integer; backoffMs?: integer; backoffMultiplier?: number; maxRetryDelayMs?: integer; … }`	optional	Optional retry policy for the try region

Nested Shape: `TryCatchConfig.try`

Property	Type	Required	Description
nodes	`{ id: string; type: string; label: string; config?: Record<string, any>; … }[]`	✅	Region body nodes (single-entry/single-exit sub-graph)
edges	`{ id: string; source: string; target: string; condition?: string \| object; … }[]`	optional	Region body edges

Nested Shape: `TryCatchConfig.catch`

Property	Type	Required	Description
nodes	`{ id: string; type: string; label: string; config?: Record<string, any>; … }[]`	✅	Region body nodes (single-entry/single-exit sub-graph)
edges	`{ id: string; source: string; target: string; condition?: string \| object; … }[]`	optional	Region body edges

Nested Shape: `TryCatchConfig.retry`

Property	Type	Required	Description
maxRetries	`integer`	optional (default: `0`)	Retry attempts after the initial one. 0 (the default) means no retry — state a count to opt in.
backoffMs	`integer`	optional (default: `1000`)	Base delay before the first retry (ms); subsequent delays multiply by backoffMultiplier
backoffMultiplier	`number`	optional (default: `1`)	Exponential backoff multiplier; 1 (the default) keeps the delay flat
maxRetryDelayMs	`integer`	optional (default: `30000`)	Ceiling for a single backoff delay (ms)
jitter	`boolean`	optional (default: `false`)	Randomize each delay within [50%, 100%] of its computed value — spreads a thundering herd of simultaneous retries
retryDelayMs	`never`	optional	[REMOVED] `retryDelayMs` was removed in @objectstack/spec 17.0.0 — the retry policy now has ONE spelling for its base delay across every surface that carries it: `job.retryPolicy`, a `try_catch` node's `retry` and `flow.errorHandling`. Rename the key to `backoffMs`; the value (milliseconds before the first retry) is unchanged. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.

Control Flow

On this page