@nanobpm/workflow 0.7.0 → 0.8.1

package/dist/declarative.js

@@ -3,7 +3,9 @@
 // (`switch`/`branch`/`loop`) that compile to exclusive gateways + back-edges the
 // engine already runs (engine-core supports XOR gateways with in-order condition
 // evaluation and a default flow, and tasks with multiple incoming flows act as
-// an implicit XOR merge).
+// an implicit XOR merge), plus concurrency combinators — `parallel` (an AND
+// fork/join over parallel gateways) and `forEach` (a data-driven fan-out lowering
+// to a parallel/sequential multi-instance activity or sub-process).
 //
 //   const convergence = defineFlow(
 //     "convergence-loop",
@@ -38,14 +40,25 @@ import { assertIdent, assertJobType, assertTimerCycle, assertTimerDate, assertTi
 /** Ids the emitter generates for structural nodes / flows / messages. A step
  *  name that collides with one of these would produce a duplicate BPMN id and an
  *  invalid model, so reject them at authoring time. */
-const RESERVED_PREFIXES = /^(Gw_|Loop_|Msg_|f_)/;
+const RESERVED_PREFIXES = /^(Gw_|Loop_|Sub_|Msg_|f_)/;
+const TIMER_START_KEYS = ["cycle", "after", "at"];
+function timerStartValue(spec, key) {
+    switch (key) {
+        case "cycle":
+            return "cycle" in spec ? spec.cycle : undefined;
+        case "after":
+            return "after" in spec ? spec.after : undefined;
+        case "at":
+            return "at" in spec ? spec.at : undefined;
+    }
+}
 function claimName(ctx, id, name) {
     assertIdent("step name", name);
     if (name === "Start" || name === "End" || name === id) {
         throw new Error(`step name "${name}" is reserved (collides with a generated BPMN id) in flow "${id}"`);
     }
     if (RESERVED_PREFIXES.test(name)) {
-        throw new Error(`step name "${name}" uses a reserved prefix (Gw_/Loop_/Msg_/f_ are generated ids) in flow "${id}"`);
+        throw new Error(`step name "${name}" uses a reserved prefix (Gw_/Loop_/Sub_/Msg_/f_ are generated ids) in flow "${id}"`);
     }
     if (ctx.seen.has(name))
         throw new Error(`duplicate step name "${name}" in flow "${id}"`);
@@ -68,6 +81,15 @@ function makeBuilder(id, out, ctx, isRoot = false) {
         fn(makeBuilder(id, body, { ...ctx, loopDepth: depth }));
         return body;
     };
+    // A body that runs in its OWN token scope (an embedded sub-process): the
+    // enclosing loop is not reachable across the scope boundary, so `break`/
+    // `continue` inside it are rejected (loopDepth resets to 0). A `loop` declared
+    // INSIDE the body still works — it creates its own scope.
+    const childScoped = (fn) => {
+        const body = [];
+        fn(makeBuilder(id, body, { ...ctx, loopDepth: 0 }));
+        return body;
+    };
     const b = {
         run(name, handler) {
             claimName(ctx, id, name);
@@ -95,12 +117,12 @@ function makeBuilder(id, out, ctx, isRoot = false) {
         },
         timer(name, opts) {
             claimName(ctx, id, name);
-            const hasAfter = typeof opts?.after === "string";
-            const hasAt = typeof opts?.at === "string";
+            const hasAfter = "after" in opts && typeof opts.after === "string";
+            const hasAt = "at" in opts && typeof opts.at === "string";
             if (hasAfter === hasAt) {
                 throw new Error(`timer("${name}") needs exactly one of { after } (a delay) or { at } (an instant)`);
             }
-            if (hasAfter) {
+            if ("after" in opts) {
                 const after = opts.after.trim();
                 assertTimerDuration(`timer("${name}") after`, after);
                 out.push({ kind: "timer", name, after });
@@ -120,16 +142,16 @@ function makeBuilder(id, out, ctx, isRoot = false) {
                 throw new Error(`startOn() must be the first statement in flow "${id}"`);
             if (ctx.startTimer)
                 throw new Error(`startOn() may be called only once in flow "${id}"`);
-            const set = ["cycle", "after", "at"].filter((k) => typeof spec?.[k] === "string");
-            if (set.length !== 1) {
+            const setCount = TIMER_START_KEYS.filter((key) => typeof timerStartValue(spec, key) === "string").length;
+            if (setCount !== 1) {
                 throw new Error(`startOn() needs exactly one of { cycle }, { after }, or { at } in flow "${id}"`);
             }
-            if (spec.cycle !== undefined) {
+            if ("cycle" in spec) {
                 const cycle = spec.cycle.trim();
                 assertTimerCycle(`startOn cycle`, cycle);
                 ctx.startTimer = { cycle };
             }
-            else if (spec.after !== undefined) {
+            else if ("after" in spec) {
                 const after = spec.after.trim();
                 assertTimerDuration(`startOn after`, after);
                 ctx.startTimer = { after };
@@ -145,10 +167,16 @@ function makeBuilder(id, out, ctx, isRoot = false) {
             if (typeof subject !== "string" || subject.trim() === "") {
                 throw new Error(`switch() needs a non-empty subject expression`);
             }
-            const entries = Object.entries(cases).filter(([k]) => k !== "default");
-            if (entries.length === 0)
+            const caseNodes = [];
+            for (const [value, fn] of Object.entries(cases)) {
+                if (value === "default")
+                    continue;
+                if (typeof fn !== "function")
+                    throw new Error(`switch("${subject}") cases must be blocks (b) => {…}`);
+                caseNodes.push({ value, body: child(fn, false) });
+            }
+            if (caseNodes.length === 0)
                 throw new Error(`switch("${subject}") needs at least one case`);
-            const caseNodes = entries.map(([value, fn]) => ({ value, body: child(fn, false) }));
             const def = cases.default ? child(cases.default, false) : undefined;
             out.push({ kind: "switch", subject, cases: caseNodes, default: def });
             return b;
@@ -173,6 +201,75 @@ function makeBuilder(id, out, ctx, isRoot = false) {
             out.push({ kind: "loop", body: child(body, true) });
             return b;
         },
+        parallel(branches) {
+            if (!Array.isArray(branches) || branches.length < 2) {
+                throw new Error(`parallel() needs at least two branch blocks`);
+            }
+            for (const fn of branches) {
+                if (typeof fn !== "function")
+                    throw new Error(`parallel() branches must all be blocks (b) => {…}`);
+            }
+            // Each branch runs in its own token scope up to the AND-join, so a
+            // `break`/`continue` must not escape the fork/join into an enclosing
+            // loop. Scope branches (loopDepth resets to 0) so cross-boundary
+            // break/continue is rejected at build time, matching forEach.
+            out.push({ kind: "parallel", branches: branches.map((fn) => childScoped(fn)) });
+            return b;
+        },
+        forEach(collection, itemVar, body, opts) {
+            if (typeof collection !== "string" || collection.trim() === "") {
+                throw new Error(`forEach() needs a non-empty FEEL collection expression`);
+            }
+            // Authors may paste a leading "=" (common in Zeebe FEEL examples). Strip
+            // it so the emitter's own "=" prefix never produces an invalid "==...".
+            const collExpr = collection.trim().replace(/^=/, "").trim();
+            if (collExpr === "") {
+                throw new Error(`forEach() collection expression is empty after stripping the leading "="`);
+            }
+            assertIdent("forEach itemVar", itemVar);
+            if (typeof body !== "function")
+                throw new Error(`forEach("${itemVar}") needs a body function`);
+            const nodes = childScoped(body);
+            if (nodes.length === 0)
+                throw new Error(`forEach("${itemVar}") body declared no steps`);
+            const node = {
+                kind: "forEach",
+                collection: collExpr,
+                itemVar,
+                body: nodes,
+            };
+            if (opts?.sequential)
+                node.sequential = true;
+            if (opts?.outputCollection !== undefined) {
+                assertIdent("forEach outputCollection", opts.outputCollection);
+                node.outputCollection = opts.outputCollection;
+            }
+            if (opts?.outputElement !== undefined) {
+                if (typeof opts.outputElement !== "string" || opts.outputElement.trim() === "") {
+                    throw new Error(`forEach("${itemVar}") outputElement must be a non-empty FEEL expression`);
+                }
+                const outEl = opts.outputElement.trim().replace(/^=/, "").trim();
+                if (outEl === "") {
+                    throw new Error(`forEach("${itemVar}") outputElement is empty after stripping the leading "="`);
+                }
+                node.outputElement = outEl;
+            }
+            if (opts?.completionCondition !== undefined) {
+                if (typeof opts.completionCondition !== "string" || opts.completionCondition.trim() === "") {
+                    throw new Error(`forEach("${itemVar}") completionCondition must be a non-empty FEEL expression`);
+                }
+                const compCond = opts.completionCondition.trim().replace(/^=/, "").trim();
+                if (compCond === "") {
+                    throw new Error(`forEach("${itemVar}") completionCondition is empty after stripping the leading "="`);
+                }
+                node.completionCondition = compCond;
+            }
+            if (node.outputElement && !node.outputCollection) {
+                throw new Error(`forEach("${itemVar}") outputElement needs an outputCollection to collect into`);
+            }
+            out.push(node);
+            return b;
+        },
         break() {
             if (ctx.loopDepth === 0)
                 throw new Error(`break() is only valid inside a loop`);
@@ -194,14 +291,22 @@ export function defineFlow(id, second, third) {
         throw new Error(`defineFlow("${id}"): the contracts argument must be an object`);
     }
     const contracts = typeof second === "function" ? {} : second;
-    const build = (typeof second === "function" ? second : third);
-    if (typeof build !== "function") {
+    if (typeof second !== "function" && typeof third !== "function") {
         throw new Error(`defineFlow("${id}"): a build callback (w) => {…} is required`);
     }
     const steps = [];
     const handlers = {};
     const ctx = { contracts, handlers, seen: new Set(), loopDepth: 0 };
-    build(makeBuilder(id, steps, ctx, true));
+    if (typeof second === "function") {
+        second(makeBuilder(id, steps, ctx, true));
+    }
+    else {
+        const build = third;
+        if (typeof build !== "function") {
+            throw new Error(`defineFlow("${id}"): a build callback (w) => {…} is required`);
+        }
+        build(makeBuilder(id, steps, ctx, true));
+    }
     if (steps.length === 0)
         throw new Error(`flow "${id}" declared no steps`);
     const flow = { kind: "declarative", id, steps, handlers };
@@ -230,6 +335,13 @@ export function walkNodes(nodes, visit) {
             case "loop":
                 walkNodes(n.body, visit);
                 break;
+            case "parallel":
+                for (const branch of n.branches)
+                    walkNodes(branch, visit);
+                break;
+            case "forEach":
+                walkNodes(n.body, visit);
+                break;
             default:
                 break;
         }
@@ -254,19 +366,44 @@ export function externalJobTypes(flow) {
     });
     return types;
 }
+function requireTimerAt(node) {
+    if (node.at === undefined)
+        throw new Error(`timer event is missing its { at } value`);
+    return node.at;
+}
+function requireStartAt(timer) {
+    if (timer.at === undefined)
+        throw new Error(`timer start is missing its { at } value`);
+    return timer.at;
+}
 class Compiler {
     flow;
     nodes = [];
     edges = [];
     /** envelope name → its fields, deduped for lifting to a single nano:shape. */
     envelopes = new Map();
+    /** The stack of open sub-process scopes; `.at(-1)` is the current scope (a
+     *  node/edge created now nests inside it). Empty at the top level. */
+    scopeStack = [];
+    /** Edges with a resolved target, indexed in `compile()` before rendering so a
+     *  sub-process can render its own nested scope. */
+    live = [];
     seq = 0;
     gw = 0;
     constructor(flow) {
         this.flow = flow;
     }
+    currentScope() {
+        return this.scopeStack.length ? this.scopeStack[this.scopeStack.length - 1] : undefined;
+    }
     newEdge(from, opts = {}) {
-        const e = { id: `f_${this.seq++}`, from, condition: opts.condition, name: opts.name };
+        const e = {
+            id: `f_${this.seq++}`,
+            from,
+            condition: opts.condition,
+            name: opts.name,
+            scope: this.currentScope(),
+        };
         this.edges.push(e);
         return e;
     }
@@ -286,7 +423,7 @@ class Compiler {
         }
         this.envelopes.set(env.name, env.fields);
     }
-    addServiceTask(node) {
+    addServiceTask(node, mi = "") {
         const type = node.jobType ?? jobType(this.flow.id, node.name);
         this.recordEnvelope(node.envelopes?.in);
         this.recordEnvelope(node.envelopes?.out);
@@ -302,10 +439,12 @@ class Compiler {
         const id = node.name;
         this.nodes.push({
             id,
+            scope: this.currentScope(),
             render: (inc, outg) => `    <bpmn:serviceTask id="${escapeXml(id)}" name="${escapeXml(id)}">\n` +
                 ext +
                 "\n" +
                 incomingOutgoing(inc, outg) +
+                mi +
                 `    </bpmn:serviceTask>`,
         });
     }
@@ -314,6 +453,7 @@ class Compiler {
         const msgId = `Msg_${id}`;
         this.nodes.push({
             id,
+            scope: this.currentScope(),
             render: (inc, outg) => `    <bpmn:intermediateCatchEvent id="${escapeXml(id)}" name="${escapeXml(id)}">\n` +
                 incomingOutgoing(inc, outg) +
                 `      <bpmn:messageEventDefinition messageRef="${msgId}" />\n` +
@@ -324,9 +464,10 @@ class Compiler {
         const id = node.name;
         const body = node.after !== undefined
             ? `        <bpmn:timeDuration>${escapeXml(node.after)}</bpmn:timeDuration>\n`
-            : `        <bpmn:timeDate>${escapeXml(node.at)}</bpmn:timeDate>\n`;
+            : `        <bpmn:timeDate>${escapeXml(requireTimerAt(node))}</bpmn:timeDate>\n`;
         this.nodes.push({
             id,
+            scope: this.currentScope(),
             render: (inc, outg) => `    <bpmn:intermediateCatchEvent id="${escapeXml(id)}" name="${escapeXml(id)}">\n` +
                 incomingOutgoing(inc, outg) +
                 `      <bpmn:timerEventDefinition>\n` +
@@ -338,6 +479,7 @@ class Compiler {
     addGateway(id, name) {
         const gwNode = {
             id,
+            scope: this.currentScope(),
             render: (inc, outg) => {
                 const def = gwNode.defaultFlow ? ` default="${gwNode.defaultFlow}"` : "";
                 const nm = name ? ` name="${escapeXml(name)}"` : "";
@@ -349,6 +491,66 @@ class Compiler {
         this.nodes.push(gwNode);
         return gwNode;
     }
+    addParallelGateway(id) {
+        const node = {
+            id,
+            scope: this.currentScope(),
+            render: (inc, outg) => `    <bpmn:parallelGateway id="${id}">\n` + incomingOutgoing(inc, outg) + `    </bpmn:parallelGateway>`,
+        };
+        this.nodes.push(node);
+        return node;
+    }
+    addPlainStart(id) {
+        this.nodes.push({
+            id,
+            scope: this.currentScope(),
+            render: (_inc, outg) => `    <bpmn:startEvent id="${escapeXml(id)}">${outgoingOnly(outg)}</bpmn:startEvent>`,
+        });
+    }
+    addPlainEnd(id) {
+        this.nodes.push({
+            id,
+            scope: this.currentScope(),
+            render: (inc) => `    <bpmn:endEvent id="${escapeXml(id)}">${incomingOnly(inc)}</bpmn:endEvent>`,
+        });
+    }
+    /** An embedded sub-process whose body renders nested in its own scope, with the
+     *  given multi-instance characteristics lifted onto it. */
+    addSubProcess(id, mi) {
+        const node = {
+            id,
+            scope: this.currentScope(),
+            render: (inc, outg) => `    <bpmn:subProcess id="${escapeXml(id)}">\n` +
+                incomingOutgoing(inc, outg) +
+                mi +
+                this.renderScope(id) +
+                `\n    </bpmn:subProcess>`,
+        };
+        this.nodes.push(node);
+        return node;
+    }
+    /** The `<bpmn:multiInstanceLoopCharacteristics>` block for a `forEach` node —
+     *  the same shape whether lifted onto a leaf service task or a sub-process. */
+    miCharacteristics(node) {
+        const seq = node.sequential ? "true" : "false";
+        const attrs = [
+            `inputCollection="${escapeXml(`=${node.collection}`)}"`,
+            `inputElement="${escapeXml(node.itemVar)}"`,
+        ];
+        if (node.outputCollection)
+            attrs.push(`outputCollection="${escapeXml(node.outputCollection)}"`);
+        if (node.outputElement)
+            attrs.push(`outputElement="${escapeXml(`=${node.outputElement}`)}"`);
+        const completion = node.completionCondition
+            ? `      <bpmn:completionCondition>${escapeXml(`=${node.completionCondition}`)}</bpmn:completionCondition>\n`
+            : "";
+        return (`      <bpmn:multiInstanceLoopCharacteristics isSequential="${seq}">\n` +
+            `        <bpmn:extensionElements>\n` +
+            `          <zeebe:loopCharacteristics ${attrs.join(" ")} />\n` +
+            `        </bpmn:extensionElements>\n` +
+            completion +
+            `      </bpmn:multiInstanceLoopCharacteristics>\n`);
+    }
     emitList(list, incoming, loop) {
         let cur = incoming;
         for (const node of list)
@@ -426,8 +628,63 @@ class Compiler {
                 this.connect(incoming, loop.headId);
                 return [];
             }
+            case "parallel": {
+                // A diverging parallel gateway forks a token onto every branch; a
+                // converging one joins them (AND-join) into a single continuation.
+                const splitId = `Gw_${this.gw++}`;
+                this.addParallelGateway(splitId);
+                this.connect(incoming, splitId);
+                const joinId = `Gw_${this.gw++}`;
+                this.addParallelGateway(joinId);
+                for (const branch of node.branches) {
+                    const e = this.newEdge(splitId);
+                    const branchOut = this.emitList(branch, [e], loop);
+                    this.connect(branchOut, joinId);
+                }
+                return [this.newEdge(joinId)];
+            }
+            case "forEach": {
+                const mi = this.miCharacteristics(node);
+                const only = node.body.length === 1 ? node.body[0] : undefined;
+                // A single service-task body carries the MI characteristics directly; a
+                // multi-step body is wrapped in an embedded MI sub-process (its own token
+                // scope, with its own start/end).
+                if (only && (only.kind === "run" || only.kind === "task")) {
+                    this.addServiceTask(only, mi);
+                    this.connect(incoming, only.name);
+                    return [this.newEdge(only.name)];
+                }
+                const subId = `Sub_${this.gw++}`;
+                this.addSubProcess(subId, mi);
+                this.connect(incoming, subId);
+                this.scopeStack.push(subId);
+                const startId = `${subId}_start`;
+                this.addPlainStart(startId);
+                const innerOut = this.emitList(node.body, [this.newEdge(startId)], null);
+                const endId = `${subId}_end`;
+                this.addPlainEnd(endId);
+                this.connect(innerOut, endId);
+                this.scopeStack.pop();
+                return [this.newEdge(subId)];
+            }
         }
     }
+    /** Render every node + sequence flow that belongs to `scope` (undefined = the
+     *  root process, a sub-process id otherwise). Called for the process body and,
+     *  recursively, from each sub-process's render closure. */
+    renderScope(scope) {
+        const incomingOf = (id) => this.live.filter((e) => e.to === id).map((e) => e.id);
+        const outgoingOf = (id) => this.live.filter((e) => e.from === id).map((e) => e.id);
+        const nodeXml = this.nodes
+            .filter((n) => n.scope === scope)
+            .map((n) => n.render(incomingOf(n.id), outgoingOf(n.id)))
+            .join("\n");
+        const flowXml = this.live
+            .filter((e) => e.scope === scope)
+            .map((e) => sequenceFlow(e))
+            .join("\n");
+        return nodeXml + (nodeXml && flowXml ? "\n" : "") + flowXml;
+    }
     /** Render the Start event — a plain none start, or a timer start when the
      *  flow declared `startOn(...)`. */
     renderStart(outg) {
@@ -438,7 +695,7 @@ class Compiler {
             ? `<bpmn:timeCycle>${escapeXml(t.cycle)}</bpmn:timeCycle>`
             : t.after !== undefined
                 ? `<bpmn:timeDuration>${escapeXml(t.after)}</bpmn:timeDuration>`
-                : `<bpmn:timeDate>${escapeXml(t.at)}</bpmn:timeDate>`;
+                : `<bpmn:timeDate>${escapeXml(requireStartAt(t))}</bpmn:timeDate>`;
         return (`    <bpmn:startEvent id="Start">\n` +
             `      ${outgoingOnly(outg)}\n` +
             `      <bpmn:timerEventDefinition>\n` +
@@ -460,11 +717,8 @@ class Compiler {
         });
         this.connect(finalDanglers, "End");
         // A sequence flow needs both ends; drop any edge that never got a target.
-        const live = this.edges.filter((e) => e.to !== undefined);
-        const incomingOf = (id) => live.filter((e) => e.to === id).map((e) => e.id);
-        const outgoingOf = (id) => live.filter((e) => e.from === id).map((e) => e.id);
-        const nodeXml = this.nodes.map((n) => n.render(incomingOf(n.id), outgoingOf(n.id))).join("\n");
-        const flowXml = live.map((e) => sequenceFlow(e)).join("\n");
+        this.live = this.edges.filter((e) => e.to !== undefined);
+        const bodyXml = this.renderScope(undefined);
         const messageXml = this.emitMessages();
         const shapeXml = this.emitShapes();
         return (`<?xml version="1.0" encoding="UTF-8"?>\n` +
@@ -474,9 +728,7 @@ class Compiler {
             `id="Definitions_${escapeXml(this.flow.id)}" targetNamespace="http://bpmn.io/schema/bpmn">\n` +
             `  <bpmn:process id="${escapeXml(this.flow.id)}" name="${escapeXml(this.flow.id)}" isExecutable="true">\n` +
             (shapeXml ? shapeXml + "\n" : "") +
-            nodeXml +
-            "\n" +
-            flowXml +
+            bodyXml +
             "\n" +
             `  </bpmn:process>\n` +
             messageXml +

package/dist/envelope.js

@@ -29,6 +29,15 @@ const SCALARS = new Set([
     "boolean",
     "datetime",
 ]);
+class EnvelopeDef {
+    name;
+    fields;
+    type;
+    constructor(name, fields) {
+        this.name = name;
+        this.fields = fields;
+    }
+}
 function normaliseField(name, spec) {
     if (spec === null || (typeof spec !== "string" && typeof spec !== "object")) {
         throw new Error(`envelope field "${name}": must be a scalar type or a { type, optional?, list? } object`);
@@ -56,7 +65,5 @@ export function envelope(name, fields) {
         throw new Error(`envelope "${name}" declares no fields`);
     for (const f of list)
         assertIdent("envelope field name", f.name);
-    // `type` is phantom: never read at runtime; the cast keeps the value shape
-    // minimal while the declared type carries the inference.
-    return { name, fields: list, type: undefined };
+    return new EnvelopeDef(name, list);
 }

package/dist/imperative.js

@@ -55,6 +55,17 @@ export function imperativeToBpmn(wf) {
         `</bpmn:definitions>\n`);
 }
 const SUSPEND = Symbol("nanobpm.workflow.suspend");
+class SuspendError extends Error {
+    [SUSPEND];
+    constructor(key, result) {
+        super("nanobpm.workflow suspend");
+        this[SUSPEND] = { key, result };
+    }
+}
+function assertReplayValue(_value, _name) {
+    // The journal value was recorded from the same ordinal/name run call on an
+    // earlier pass; TypeScript cannot express that cross-replay invariant.
+}
 /**
  * Replay the orchestration function against a journal. Returns `{ done: true }`
  * if the function ran to completion, or the frontier step (the one un-recorded
@@ -70,12 +81,13 @@ export async function replayOnce(wf, input, journal) {
         async run(name, fn) {
             const key = `${++ordinal}:${name}`;
             if (Object.prototype.hasOwnProperty.call(journal, key)) {
-                return journal[key]; // replay: return recorded value, no side effect
+                const value = journal[key];
+                assertReplayValue(value, name);
+                return value; // replay: return recorded value, no side effect
             }
-            const result = ((await fn()) ?? null); // frontier: the ONE real side effect this turn
-            const carrier = new Error("nanobpm.workflow suspend");
-            carrier[SUSPEND] = { key, result };
-            throw carrier;
+            const result = (await fn()) ?? null; // frontier: the ONE real side effect this turn
+            assertReplayValue(result, name);
+            throw new SuspendError(key, result);
         },
     };
     try {
@@ -83,9 +95,8 @@ export async function replayOnce(wf, input, journal) {
         return { done: true };
     }
     catch (e) {
-        const s = e[SUSPEND];
-        if (s)
-            return { done: false, frontier: s };
+        if (e instanceof SuspendError)
+            return { done: false, frontier: e[SUSPEND] };
         throw e; // a genuine error in the orchestration or a handler
     }
 }

package/dist/layout.js

@@ -16,6 +16,9 @@
 // stays authoritative. Re-run layout whenever the flow changes rather than
 // hand-editing the generated diagram.
 import { declarativeToBpmn } from "./declarative.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 /**
  * Generate BPMN diagram interchange (DI) for a BPMN XML string using bpmn-io's
  * `bpmn-auto-layout`, returning the same model with an auto-laid-out diagram
@@ -36,7 +39,7 @@ export async function layoutBpmn(bpmnXml) {
         // genuinely cannot be resolved. A different failure (the package is present
         // but fails to load — syntax, a broken transitive dep, a runtime throw at
         // import time) must surface as-is so it isn't masked as a missing dependency.
-        if (cause?.code !== "ERR_MODULE_NOT_FOUND") {
+        if (!isRecord(cause) || cause.code !== "ERR_MODULE_NOT_FOUND") {
             throw cause;
         }
         throw new Error('layoutBpmn requires the optional peer dependency "bpmn-auto-layout". ' +

package/dist/types.d.ts

@@ -34,7 +34,9 @@ export interface StepContract {
  *  untyped `JsonObject`. */
 export type FlowContracts = Record<string, StepContract>;
 /** Handler for a declarative `run` step: does real work, returns variables. */
-export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject | void;
+export type StepHandler<V extends JsonObject = JsonObject, R extends JsonObject = JsonObject> = {
+    bivarianceHack(job: Job<V>): Promise<R | void> | R | void;
+}["bivarianceHack"];
 /** A node in a declarative flow tree. Leaf activities carry optional data
  *  envelopes (lifted to `nano:shape` + `dataEnvelope` in the model); structural
  *  combinators carry nested `FlowNode[]` bodies. */
@@ -72,6 +74,24 @@ export type FlowNode = {
     kind: "break";
 } | {
     kind: "continue";
+} | {
+    kind: "parallel";
+    branches: FlowNode[][];
+} | {
+    kind: "forEach";
+    /** FEEL expression evaluating to the list to fan out over. */
+    collection: string;
+    /** Variable each item is bound to in the child's scope (`inputElement`). */
+    itemVar: string;
+    body: FlowNode[];
+    /** Run children one at a time (sequential MI) instead of all at once. */
+    sequential?: boolean;
+    /** List variable that each child's `outputElement` is collected into. */
+    outputCollection?: string;
+    /** FEEL expression producing each child's contribution to `outputCollection`. */
+    outputElement?: string;
+    /** FEEL boolean that, once true, completes the body early. */
+    completionCondition?: string;
 };
 /** A timer intermediate-catch definition: exactly one of `after` (an ISO-8601
  *  delay or FEEL expression) or `at` (an absolute instant or FEEL expression).

package/dist/worker.js

@@ -17,6 +17,9 @@ import { WorkflowClient } from "./client.js";
 import { replayOnce } from "./imperative.js";
 import { walkNodes } from "./declarative.js";
 import { jobType } from "./xml.js";
+function isJsonObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 export class Worker {
     client;
     name;
@@ -47,21 +50,25 @@ export class Worker {
             this.addRoute(wf.orchestrateType, {
                 workflowId: wf.id,
                 handle: async (job) => {
-                    const input = job.variables.input ?? {};
-                    const journal = job.variables.journal ?? {};
+                    const input = isJsonObject(job.variables.input) ? job.variables.input : {};
+                    const journal = isJsonObject(job.variables.journal) ? job.variables.journal : {};
                     const step = await replayOnce(wf, input, journal);
-                    if (step.done)
-                        return { variables: { wfDone: true }, step: "__done" };
+                    if (step.done) {
+                        const variables = { wfDone: true };
+                        return { variables, step: "__done" };
+                    }
                     const next = { ...journal, [step.frontier.key]: step.frontier.result };
-                    return { variables: { journal: next, wfDone: false }, step: step.frontier.key };
+                    const variables = { journal: next, wfDone: false };
+                    return { variables, step: step.frontier.key };
                 },
             });
         }
         else {
             // Walk the flow tree; only `run` steps are hosted locally. `signal`
             // (message catch) and `task` (external worker) contribute no in-process
-            // route, and structural combinators (`switch`/`branch`/`loop`) are pure
-            // routing with no job of their own.
+            // route, and structural combinators (`switch`/`branch`/`loop`/`parallel`/
+            // `forEach`) are pure routing with no job of their own — but the `run`
+            // steps NESTED inside them are hosted, since `walkNodes` recurses.
             walkNodes(wf.steps, (s) => {
                 if (s.kind !== "run")
                     return;
@@ -75,7 +82,10 @@ export class Worker {
                 }
                 this.addRoute(jobType(wf.id, s.name), {
                     workflowId: wf.id,
-                    handle: async (job) => ({ variables: ((await handler(job)) ?? {}) }),
+                    handle: async (job) => {
+                        const variables = (await handler(job)) ?? {};
+                        return { variables };
+                    },
                 });
             });
         }