@nanobpm/workflow 0.6.0 → 0.8.0

package/README.md

@@ -45,6 +45,14 @@ human-in-the-loop path), composed with control-flow combinators:
 - `w.branch(condition, { then, else? })` — a two-way choice on a FEEL boolean.
 - `w.loop(body)` — a durable loop (back-edge to the loop head).
 - `w.break()` / `w.continue()` — exit the enclosing loop, or jump back to its head.
+- `w.parallel([blockA, blockB, …])` — a static fork/join: every block runs
+  concurrently on its own branch, rejoined by an AND-join (all branches must
+  arrive before the flow continues).
+- `w.forEach(collection, itemVar, body, opts?)` — a data-driven fan-out over a
+  FEEL `collection`: one child instance of `body` runs per item (the item bound to
+  `itemVar`). `{ sequential }` runs children one at a time; `{ outputCollection,
+  outputElement }` collects each child's result into a list; `{ completionCondition }`
+  completes the body early.
 
 ```ts
 import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";
@@ -89,8 +97,10 @@ const convergence = defineFlow("convergence-loop", (w) => {
 Each combinator compiles to a BPMN primitive the engine already runs: `switch` /
 `branch` → an exclusive gateway (in-order conditions, first match wins, default =
 unconditional flow); `loop` → a convergent gateway whose body falls through back to
-the head; nodes with multiple incoming flows are an implicit XOR merge. See
-**ADR 0047**.
+the head; nodes with multiple incoming flows are an implicit XOR merge; `parallel`
+→ a diverging/converging **parallel gateway** pair (AND fork/join); `forEach` → a
+**parallel multi-instance** activity (a single-step body) or an embedded
+multi-instance sub-process (a multi-step body). See **ADR 0047**.
 
 #### Typed data envelopes (eject to model-first with contracts intact)
 
@@ -178,7 +188,7 @@ once.
 | Export | Purpose |
 | --- | --- |
 | `defineWorkflow(id, orchFn)` | Imperative (replayed) workflow — experimental/internal. |
-| `defineFlow(id, [contracts,] build)` | Declarative flow: `run`/`task`/`signal` + `switch`/`branch`/`loop`/`break`/`continue`, with an optional typed contracts map. |
+| `defineFlow(id, [contracts,] build)` | Declarative flow: `run`/`task`/`signal`/`timer` + `switch`/`branch`/`loop`/`break`/`continue` + `parallel`/`forEach`, with an optional typed contracts map. |
 | `envelope(name, fields)` | A typed data envelope; lifted into the model as a `nano:shape` + `dataEnvelope` wiring. |
 | `externalJobTypes(flow)` | The job types of a flow's external `task` steps (each overridable per-step via `w.task(name, { jobType })`). |
 | `WorkflowClient` | `deploy`, `start`, `signal`, `getInstance` over REST v2. |

package/dist/declarative.d.ts

@@ -22,8 +22,19 @@ type TypedHandler<V, R> = (job: {
     variables: V;
 }) => Promise<R | void> | R | void;
 /** A block: the callback that populates a nested body (a case, arm, or loop). */
-type Block<C extends FlowContracts> = (b: FlowBuilder<C>) => void;
-export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
+type Block<C extends object> = (b: FlowBuilder<C>) => void;
+/** The typed builder for a flow body.
+ *
+ * `C` is the flow's contracts map (step name → `{ in, out }` envelopes). The
+ * default is `object`, NOT `Record<string, never>`: with a `never`-valued record
+ * `keyof C` is `string`, so `VarsOf`/`ResultOf` route EVERY step name into
+ * `InPayload<never>`/`OutPayload<never>`, which distribute over `never` to
+ * `never` — typing an untyped flow's `job.variables` as `never` and forcing its
+ * handler return to `void` (so no untyped flow that returns data compiles). With
+ * `object`, `keyof C` is `never`, so every step falls back to the intended
+ * `JsonObject`. The public `defineFlow<C extends FlowContracts>` overload keeps
+ * the stricter contracts constraint; this is only the untyped-builder default. */
+export interface FlowBuilder<C extends object = object> {
     /**
      * A durable activity served by a worker THIS program hosts (a BPMN service
      * task; the handler runs in the in-process `Worker`). If `name` is a key in
@@ -55,6 +66,36 @@ export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
     signal<K extends string>(name: K, opts: {
         correlationKey: string;
     }): FlowBuilder<C>;
+    /**
+     * A durable wait for a point in time (a BPMN timer intermediate catch event).
+     * Pass exactly one of `{ after }` — an ISO-8601 delay (`PT1M30S`, `P1DT6H`) or
+     * FEEL `=`-expression measured from when the token arrives — or `{ at }` — an
+     * absolute ISO-8601 instant (or FEEL expression). The engine holds the token
+     * durably until the timer fires, then continues. Use it for in-flow delays and
+     * scheduled continuations (e.g. "wait 24h, then re-poll").
+     */
+    timer<K extends string>(name: K, opts: {
+        after: string;
+    } | {
+        at: string;
+    }): FlowBuilder<C>;
+    /**
+     * Make this flow's start event a durable TIMER start rather than an explicit
+     * `client.start(...)`. Must be the first statement, at the top level. Pass
+     * exactly one of `{ cycle }` — a recurring ISO-8601 interval (`R/PT1H`,
+     * `R5/PT30M`) the engine re-fires each period — `{ after }` — a one-shot delay
+     * from deployment — or `{ at }` — a one-shot absolute instant. A `cycle` start
+     * is the model-native, durable, single-fire-per-cluster replacement for an
+     * app-side cron: the schedule lives in the deployable model, and the engine
+     * (not each app replica) owns firing it exactly once.
+     */
+    startOn(spec: {
+        cycle: string;
+    } | {
+        after: string;
+    } | {
+        at: string;
+    }): FlowBuilder<C>;
     /**
      * A multi-way exclusive choice (a BPMN exclusive gateway). `subject` is a FEEL
      * expression (usually a variable name); each case routes when `subject` equals
@@ -79,6 +120,36 @@ export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
      * the loop run once `break()` is reached.
      */
     loop(body: Block<C>): FlowBuilder<C>;
+    /**
+     * A static parallel fork/join (a pair of BPMN parallel gateways). Every block
+     * runs concurrently on its own branch; control continues past `parallel` only
+     * once ALL branches have reached the joining gateway (AND-join). Pass at least
+     * two branch blocks. Unlike `switch`/`branch` (exclusive choice), no branch is
+     * conditional — all of them run.
+     */
+    parallel(branches: Block<C>[]): FlowBuilder<C>;
+    /**
+     * A data-driven fan-out over a runtime collection (a BPMN parallel
+     * multi-instance activity). `collection` is a FEEL expression (no leading `=`)
+     * evaluating to a list; one child instance of `body` runs per item, with the
+     * item bound to the `itemVar` variable in the child's scope. A single-activity
+     * body attaches the multi-instance characteristics to that activity; a
+     * multi-step body is wrapped in an embedded multi-instance sub-process. Options:
+     *  - `sequential` — run children one at a time (a sequential MI) instead of all
+     *    at once (the default: a parallel MI).
+     *  - `outputCollection` / `outputElement` — collect each child's `outputElement`
+     *    (a FEEL expression, no leading `=`) into the `outputCollection` list
+     *    variable, in item order.
+     *  - `completionCondition` — a FEEL boolean (no leading `=`); when it holds
+     *    after a child completes, the remaining children are cancelled and the body
+     *    completes early.
+     */
+    forEach(collection: string, itemVar: string, body: Block<C>, opts?: {
+        sequential?: boolean;
+        outputCollection?: string;
+        outputElement?: string;
+        completionCondition?: string;
+    }): FlowBuilder<C>;
     /** Exit the enclosing loop (routes to whatever follows it). Only valid inside
      *  a `loop`. */
     break(): FlowBuilder<C>;

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",
@@ -34,18 +36,18 @@
 // Typed data envelopes are LIFTED into the model (nano:shape + dataEnvelope
 // zeebe:property), so the generated .bpmn is ejectable to model-first with its
 // typed contracts intact.
-import { assertIdent, assertJobType, escapeXml, jobType, messageName } from "./xml.js";
+import { assertIdent, assertJobType, assertTimerCycle, assertTimerDate, assertTimerDuration, escapeXml, jobType, messageName } from "./xml.js";
 /** 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_)/;
 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}"`);
@@ -61,13 +63,22 @@ function contractEnvelopes(ctx, name) {
 /** Build a FlowBuilder that appends its nodes to `out`, sharing the flow-wide
  *  `ctx` (contracts, handler registry, name set, loop nesting). Structural
  *  combinators recurse with a fresh `out` array for each nested body. */
-function makeBuilder(id, out, ctx) {
+function makeBuilder(id, out, ctx, isRoot = false) {
     const child = (fn, inLoop) => {
         const body = [];
         const depth = inLoop ? ctx.loopDepth + 1 : ctx.loopDepth;
         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);
@@ -93,6 +104,54 @@ function makeBuilder(id, out, ctx) {
             out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: ctx.contracts[name]?.in });
             return b;
         },
+        timer(name, opts) {
+            claimName(ctx, id, name);
+            const hasAfter = typeof opts?.after === "string";
+            const hasAt = 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) {
+                const after = opts.after.trim();
+                assertTimerDuration(`timer("${name}") after`, after);
+                out.push({ kind: "timer", name, after });
+            }
+            else {
+                const at = opts.at.trim();
+                assertTimerDate(`timer("${name}") at`, at);
+                out.push({ kind: "timer", name, at });
+            }
+            return b;
+        },
+        startOn(spec) {
+            if (!isRoot) {
+                throw new Error(`startOn() is only valid at the top level of flow "${id}" (not inside switch/branch/loop)`);
+            }
+            if (out.length !== 0)
+                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) {
+                throw new Error(`startOn() needs exactly one of { cycle }, { after }, or { at } in flow "${id}"`);
+            }
+            if (spec.cycle !== undefined) {
+                const cycle = spec.cycle.trim();
+                assertTimerCycle(`startOn cycle`, cycle);
+                ctx.startTimer = { cycle };
+            }
+            else if (spec.after !== undefined) {
+                const after = spec.after.trim();
+                assertTimerDuration(`startOn after`, after);
+                ctx.startTimer = { after };
+            }
+            else {
+                const at = spec.at.trim();
+                assertTimerDate(`startOn at`, at);
+                ctx.startTimer = { at };
+            }
+            return b;
+        },
         switch(subject, cases) {
             if (typeof subject !== "string" || subject.trim() === "") {
                 throw new Error(`switch() needs a non-empty subject expression`);
@@ -125,6 +184,75 @@ function makeBuilder(id, out, ctx) {
             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`);
@@ -153,10 +281,13 @@ export function defineFlow(id, second, third) {
     const steps = [];
     const handlers = {};
     const ctx = { contracts, handlers, seen: new Set(), loopDepth: 0 };
-    build(makeBuilder(id, steps, ctx));
+    build(makeBuilder(id, steps, ctx, true));
     if (steps.length === 0)
         throw new Error(`flow "${id}" declared no steps`);
-    return { kind: "declarative", id, steps, handlers };
+    const flow = { kind: "declarative", id, steps, handlers };
+    if (ctx.startTimer)
+        flow.startTimer = ctx.startTimer;
+    return flow;
 }
 // --- Tree walkers ------------------------------------------------------------
 /** Depth-first visit of every node in a flow tree (structural combinators
@@ -179,6 +310,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;
         }
@@ -209,13 +347,28 @@ class Compiler {
     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;
     }
@@ -235,7 +388,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);
@@ -251,10 +404,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>`,
         });
     }
@@ -263,15 +418,33 @@ 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` +
                 `    </bpmn:intermediateCatchEvent>`,
         });
     }
+    addTimerCatchEvent(node) {
+        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`;
+        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` +
+                body +
+                `      </bpmn:timerEventDefinition>\n` +
+                `    </bpmn:intermediateCatchEvent>`,
+        });
+    }
     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)}"` : "";
@@ -283,6 +456,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)
@@ -303,6 +536,11 @@ class Compiler {
                 this.recordEnvelope(node.payload);
                 return [this.newEdge(node.name)];
             }
+            case "timer": {
+                this.addTimerCatchEvent(node);
+                this.connect(incoming, node.name);
+                return [this.newEdge(node.name)];
+            }
             case "switch": {
                 const id = `Gw_${this.gw++}`;
                 const gw = this.addGateway(id, node.subject);
@@ -355,13 +593,86 @@ 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) {
+        const t = this.flow.startTimer;
+        if (!t)
+            return `    <bpmn:startEvent id="Start">${outgoingOnly(outg)}</bpmn:startEvent>`;
+        const body = t.cycle !== undefined
+            ? `<bpmn:timeCycle>${escapeXml(t.cycle)}</bpmn:timeCycle>`
+            : t.after !== undefined
+                ? `<bpmn:timeDuration>${escapeXml(t.after)}</bpmn:timeDuration>`
+                : `<bpmn:timeDate>${escapeXml(t.at)}</bpmn:timeDate>`;
+        return (`    <bpmn:startEvent id="Start">\n` +
+            `      ${outgoingOnly(outg)}\n` +
+            `      <bpmn:timerEventDefinition>\n` +
+            `        ${body}\n` +
+            `      </bpmn:timerEventDefinition>\n` +
+            `    </bpmn:startEvent>`);
+    }
     compile() {
         // Start → top-level sequence → End.
         this.nodes.push({
             id: "Start",
-            render: (_inc, outg) => `    <bpmn:startEvent id="Start">${outgoingOnly(outg)}</bpmn:startEvent>`,
+            render: (_inc, outg) => this.renderStart(outg),
         });
         const s0 = this.newEdge("Start");
         const finalDanglers = this.emitList(this.flow.steps, [s0], null);
@@ -371,11 +682,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` +
@@ -385,9 +693,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/index.d.ts

@@ -9,4 +9,4 @@ export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./clien
 export type { WorkflowClientOptions, NanoSdkClient, NanoJobWorker, JobWorkerConfig, ActivatedJob, } from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";
-export type { Json, JsonObject, Job, StepHandler, DeclarativeFlow, DeclarativeStep, FlowNode, SwitchCase, NodeEnvelopes, StepContract, FlowContracts, ImperativeWorkflow, Orchestration, WorkflowContext, Workflow, DeployResult, StartResult, } from "./types.js";
+export type { Json, JsonObject, Job, StepHandler, DeclarativeFlow, DeclarativeStep, FlowNode, SwitchCase, TimerStart, NodeEnvelopes, StepContract, FlowContracts, ImperativeWorkflow, Orchestration, WorkflowContext, Workflow, DeployResult, StartResult, } from "./types.js";