Skip to content

control-flow.mdx

Latest commit

 

History

History
291 lines (217 loc) · 19.2 KB

control-flow.mdx

File metadata and controls

291 lines (217 loc) · 19.2 KB
Raw
title Control Flow
description Control Flow protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

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:

  1. 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.
  2. 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.
  3. 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 are no longer disjoint, and since #16134 that is deliberate: the schema rejects undeclared KEYS and one structural fact — a duplicate node id — while the analysis rejects malformed STRUCTURE. They meet at two seams.

#4001 — validateControlFlow safeParses each region slot before analyzing it, so that parse is also where a region's undeclared key surfaces, reported as <where>: invalid region — <the strictObject message>. That seam duplicated nothing and removed nothing, and left the structural prose this guard exists for untouched; it simply stopped silently repairing its own input.

#16134 — FlowSchema's superRefine holds ONE node-id space across the top-level nodes[] and every region body, judged at every depth collectFlowGraphs walks. That walk stops at MAX_REGION_DEPTH (32), so past the ceiling a region is left raw and analyzeRegion's own duplicate node id line, reached through this guard, is the only refusal of a within-region duplicate (a cross-region collision beyond the ceiling is not judged). The two guards overlap there by design and hand off at that measured boundary.

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

TypeScript Usage

import { FlowRegionSchema, LoopConfigSchema, ParallelBranchSchema, ParallelConfigSchema, RetryPolicySchema, TryCatchConfigSchema, TryCatchErrorValueSchema } from '@objectstack/spec/automation';
import type { FlowRegion, LoopConfig, ParallelBranch, ParallelConfig, RetryPolicy, TryCatchConfig, TryCatchErrorValue } 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. An evaluated slot: a bare non-blank CEL string, or an envelope carrying a non-blank source — an ast-only envelope, and a source that is blank after trimming, are refused at authoring because the engine evaluates source alone and would otherwise answer a silent false.
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. An evaluated slot: a bare non-blank CEL string, or an envelope carrying a non-blank source — an ast-only envelope, and a source that is blank after trimming, are refused at authoring because the engine evaluates source alone and would otherwise answer a silent false.
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 — a TryCatchErrorValue: nodeId, message, code when the failing node carried a platform-classified error code (ADR-0112 — branch on $error.code to tell "the row is already there" from "the store is down"), and iteration / item when the failure happened inside a loop body
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.

TryCatchErrorValue

Properties

Property Type Required Description
nodeId string ✅ Node the failure is attributed to
message string ✅ Message of the error that ended the try region, after any retries
code string optional Platform-classified error code (ADR-0112) of the failure that ended the try region, e.g. create_record's DUPLICATE_RECORD; present only when the failing node's own result carried one, so a catch region branching on $error.code treats "unset" as "no classified code", never as "nothing failed". An open string, not a closed enum: the vocabulary is StandardErrorCode plus registered ledger codes plus tenant-authored codes, and third-party node executors bind their own
iteration integer optional Zero-based iteration of the enclosing loop when the failure happened inside a loop body; absent outside a loop
item any optional The loop item being processed (the enclosing loop's iteratorVariable value) when the failure happened inside a loop body; absent outside a loop