@nanobpm/workflow 0.7.0 → 0.8.1

package/src/declarative.ts

@@ -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",
@@ -52,9 +54,9 @@ import { assertIdent, assertJobType, assertTimerCycle, assertTimerDate, assertTi
 // --- Authoring surface -------------------------------------------------------
 
 /** The TS payload type of a contract's input envelope (untyped fallback). */
-type InPayload<Ct> = Ct extends { in: Envelope } ? Ct["in"]["type"] : JsonObject;
+type InPayload<Ct> = Ct extends { in: Envelope } ? Ct["in"]["type"] & JsonObject : JsonObject;
 /** The TS payload type of a contract's output envelope (untyped fallback). */
-type OutPayload<Ct> = Ct extends { out: Envelope } ? Ct["out"]["type"] : JsonObject;
+type OutPayload<Ct> = Ct extends { out: Envelope } ? Ct["out"]["type"] & JsonObject : JsonObject;
 /** The input payload type of step `K` under contracts `C`. */
 type VarsOf<C, K extends string> = K extends keyof C ? InPayload<C[K]> : JsonObject;
 /** The output payload type of step `K` under contracts `C`. */
@@ -62,7 +64,7 @@ type ResultOf<C, K extends string> = K extends keyof C ? OutPayload<C[K]> : Json
 
 /** A typed handler for a `run` step: its job variables and result are resolved
  *  from the flow contracts by the step name. */
-type TypedHandler<V, R> = (job: {
+type TypedHandler<V extends JsonObject, R extends JsonObject> = (job: {
   jobKey: string;
   processInstanceKey: string;
   elementId: string;
@@ -71,9 +73,20 @@ type TypedHandler<V, R> = (job: {
 }) => 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;
+type Block<C extends object> = (b: FlowBuilder<C>) => void;
 
-export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
+/** 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
@@ -140,6 +153,41 @@ 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>;
@@ -160,7 +208,22 @@ interface BuilderCtx {
 /** 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"] as const;
+
+function timerStartValue(
+  spec: { cycle: string } | { after: string } | { at: string },
+  key: (typeof TIMER_START_KEYS)[number],
+): string | undefined {
+  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: BuilderCtx, id: string, name: string): void {
   assertIdent("step name", name);
@@ -169,7 +232,7 @@ function claimName(ctx: BuilderCtx, id: string, name: string): void {
   }
   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}"`,
+      `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}"`);
@@ -186,7 +249,7 @@ function contractEnvelopes(ctx: BuilderCtx, name: string): { in?: Envelope; out?
 /** 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<C extends FlowContracts>(
+function makeBuilder<C extends object>(
   id: string,
   out: FlowNode[],
   ctx: BuilderCtx,
@@ -198,81 +261,97 @@ function makeBuilder<C extends FlowContracts>(
     fn(makeBuilder<C>(id, body, { ...ctx, loopDepth: depth }));
     return body;
   };
-  const b = {
-    run(name: string, handler: StepHandler): FlowBuilder<C> {
+  // 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: Block<C>): FlowNode[] => {
+    const body: FlowNode[] = [];
+    fn(makeBuilder<C>(id, body, { ...ctx, loopDepth: 0 }));
+    return body;
+  };
+  const b: FlowBuilder<C> = {
+    run<K extends string>(
+      name: K,
+      handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>,
+    ): FlowBuilder<C> {
       claimName(ctx, id, name);
       if (typeof handler !== "function") throw new Error(`run("${name}") needs a handler function`);
       ctx.handlers[name] = handler;
       out.push({ kind: "run", name, envelopes: contractEnvelopes(ctx, name) });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     task(name: string, opts?: { jobType?: string }): FlowBuilder<C> {
       claimName(ctx, id, name);
       const override = opts?.jobType;
       if (override !== undefined) assertJobType("task jobType", override);
       out.push({ kind: "task", name, envelopes: contractEnvelopes(ctx, name), jobType: override });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     signal(name: string, opts: { correlationKey: string }): FlowBuilder<C> {
       claimName(ctx, id, name);
       if (!opts || !opts.correlationKey) throw new Error(`signal("${name}") needs { correlationKey }`);
       assertIdent("correlationKey", opts.correlationKey);
       out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: ctx.contracts[name]?.in });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
-    timer(name: string, opts: { after?: string; at?: string }): FlowBuilder<C> {
+    timer(name: string, opts: { after: string } | { at: string }): FlowBuilder<C> {
       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) {
-        const after = (opts.after as string).trim();
+      if ("after" in opts) {
+        const after = opts.after.trim();
         assertTimerDuration(`timer("${name}") after`, after);
         out.push({ kind: "timer", name, after });
       } else {
-        const at = (opts.at as string).trim();
+        const at = opts.at.trim();
         assertTimerDate(`timer("${name}") at`, at);
         out.push({ kind: "timer", name, at });
       }
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
-    startOn(spec: { cycle?: string; after?: string; at?: string }): FlowBuilder<C> {
+    startOn(spec: { cycle: string } | { after: string } | { at: string }): FlowBuilder<C> {
       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"] as const).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 };
       } else {
-        const at = (spec.at as string).trim();
+        const at = spec.at.trim();
         assertTimerDate(`startOn at`, at);
         ctx.startTimer = { at };
       }
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     switch(subject: string, cases: Record<string, Block<C>> & { default?: Block<C> }): FlowBuilder<C> {
       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") as [string, Block<C>][];
-      if (entries.length === 0) throw new Error(`switch("${subject}") needs at least one case`);
-      const caseNodes: SwitchCase[] = entries.map(([value, fn]) => ({ value, body: child(fn, false) }));
+      const caseNodes: SwitchCase[] = [];
+      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 def = cases.default ? child(cases.default, false) : undefined;
       out.push({ kind: "switch", subject, cases: caseNodes, default: def });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     branch(condition: string, arms: { then: Block<C>; else?: Block<C> }): FlowBuilder<C> {
       if (typeof condition !== "string" || condition.trim() === "") {
@@ -285,25 +364,100 @@ function makeBuilder<C extends FlowContracts>(
         then: child(arms.then, false),
         else: arms.else ? child(arms.else, false) : undefined,
       });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     loop(body: Block<C>): FlowBuilder<C> {
       if (typeof body !== "function") throw new Error(`loop() needs a body function`);
       out.push({ kind: "loop", body: child(body, true) });
-      return b as unknown as FlowBuilder<C>;
+      return b;
+    },
+    parallel(branches: Block<C>[]): FlowBuilder<C> {
+      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: string,
+      itemVar: string,
+      body: Block<C>,
+      opts?: {
+        sequential?: boolean;
+        outputCollection?: string;
+        outputElement?: string;
+        completionCondition?: string;
+      },
+    ): FlowBuilder<C> {
+      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: Extract<FlowNode, { kind: "forEach" }> = {
+        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(): FlowBuilder<C> {
       if (ctx.loopDepth === 0) throw new Error(`break() is only valid inside a loop`);
       out.push({ kind: "break" });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
     continue(): FlowBuilder<C> {
       if (ctx.loopDepth === 0) throw new Error(`continue() is only valid inside a loop`);
       out.push({ kind: "continue" });
-      return b as unknown as FlowBuilder<C>;
+      return b;
     },
   };
-  return b as unknown as FlowBuilder<C>;
+  return b;
 }
 
 /**
@@ -327,14 +481,21 @@ export function defineFlow(
     throw new Error(`defineFlow("${id}"): the contracts argument must be an object`);
   }
   const contracts: FlowContracts = typeof second === "function" ? {} : second;
-  const build = (typeof second === "function" ? second : third) as (w: FlowBuilder<FlowContracts>) => void;
-  if (typeof build !== "function") {
+  if (typeof second !== "function" && typeof third !== "function") {
     throw new Error(`defineFlow("${id}"): a build callback (w) => {…} is required`);
   }
   const steps: FlowNode[] = [];
   const handlers: Record<string, StepHandler> = {};
   const ctx: BuilderCtx = { contracts, handlers, seen: new Set(), loopDepth: 0 };
-  build(makeBuilder<FlowContracts>(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<FlowContracts>(id, steps, ctx, true));
+  }
   if (steps.length === 0) throw new Error(`flow "${id}" declared no steps`);
   const flow: DeclarativeFlow = { kind: "declarative", id, steps, handlers };
   if (ctx.startTimer) flow.startTimer = ctx.startTimer;
@@ -360,6 +521,12 @@ export function walkNodes(nodes: FlowNode[], visit: (n: FlowNode) => void): void
       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;
     }
@@ -384,6 +551,16 @@ export function externalJobTypes(flow: DeclarativeFlow): string[] {
   return types;
 }
 
+function requireTimerAt(node: { at?: string }): string {
+  if (node.at === undefined) throw new Error(`timer event is missing its { at } value`);
+  return node.at;
+}
+
+function requireStartAt(timer: TimerStart): string {
+  if (timer.at === undefined) throw new Error(`timer start is missing its { at } value`);
+  return timer.at;
+}
+
 // --- Model emitter (two-phase graph compiler) --------------------------------
 
 interface RenderNode {
@@ -391,6 +568,9 @@ interface RenderNode {
   render(incoming: string[], outgoing: string[]): string;
   /** For exclusive gateways: the flow id of the unconditional default edge. */
   defaultFlow?: string;
+  /** Id of the embedded sub-process this node lives in, or undefined at the
+   *  top level (the root process). */
+  scope?: string;
 }
 
 interface Edge {
@@ -399,6 +579,9 @@ interface Edge {
   to?: string;
   condition?: string;
   name?: string;
+  /** The scope (sub-process id, or undefined = root process) this flow is
+   *  nested in — so it renders inside the right container. */
+  scope?: string;
 }
 
 interface LoopCtx {
@@ -411,13 +594,29 @@ class Compiler {
   private readonly edges: Edge[] = [];
   /** envelope name → its fields, deduped for lifting to a single nano:shape. */
   private readonly envelopes = new Map<string, EnvelopeField[]>();
+  /** 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. */
+  private readonly scopeStack: string[] = [];
+  /** Edges with a resolved target, indexed in `compile()` before rendering so a
+   *  sub-process can render its own nested scope. */
+  private live: Edge[] = [];
   private seq = 0;
   private gw = 0;
 
   constructor(private readonly flow: DeclarativeFlow) {}
 
+  private currentScope(): string | undefined {
+    return this.scopeStack.length ? this.scopeStack[this.scopeStack.length - 1] : undefined;
+  }
+
   private newEdge(from: string, opts: { condition?: string; name?: string } = {}): Edge {
-    const e: Edge = { id: `f_${this.seq++}`, from, condition: opts.condition, name: opts.name };
+    const e: Edge = {
+      id: `f_${this.seq++}`,
+      from,
+      condition: opts.condition,
+      name: opts.name,
+      scope: this.currentScope(),
+    };
     this.edges.push(e);
     return e;
   }
@@ -440,7 +639,7 @@ class Compiler {
     this.envelopes.set(env.name, env.fields);
   }
 
-  private addServiceTask(node: { name: string; envelopes?: NodeEnvelopes; jobType?: string }): void {
+  private addServiceTask(node: { name: string; envelopes?: NodeEnvelopes; jobType?: string }, mi = ""): void {
     const type = node.jobType ?? jobType(this.flow.id, node.name);
     this.recordEnvelope(node.envelopes?.in);
     this.recordEnvelope(node.envelopes?.out);
@@ -455,11 +654,13 @@ 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>`,
     });
   }
@@ -469,6 +670,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) +
@@ -482,9 +684,10 @@ class Compiler {
     const body =
       node.after !== undefined
         ? `        <bpmn:timeDuration>${escapeXml(node.after)}</bpmn:timeDuration>\n`
-        : `        <bpmn:timeDate>${escapeXml(node.at as string)}</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) +
@@ -498,6 +701,7 @@ class Compiler {
   private addGateway(id: string, name?: string): RenderNode {
     const gwNode: RenderNode = {
       id,
+      scope: this.currentScope(),
       render: (inc, outg) => {
         const def = gwNode.defaultFlow ? ` default="${gwNode.defaultFlow}"` : "";
         const nm = name ? ` name="${escapeXml(name)}"` : "";
@@ -512,6 +716,73 @@ class Compiler {
     return gwNode;
   }
 
+  private addParallelGateway(id: string): RenderNode {
+    const node: RenderNode = {
+      id,
+      scope: this.currentScope(),
+      render: (inc, outg) =>
+        `    <bpmn:parallelGateway id="${id}">\n` + incomingOutgoing(inc, outg) + `    </bpmn:parallelGateway>`,
+    };
+    this.nodes.push(node);
+    return node;
+  }
+
+  private addPlainStart(id: string): void {
+    this.nodes.push({
+      id,
+      scope: this.currentScope(),
+      render: (_inc, outg) => `    <bpmn:startEvent id="${escapeXml(id)}">${outgoingOnly(outg)}</bpmn:startEvent>`,
+    });
+  }
+
+  private addPlainEnd(id: string): void {
+    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. */
+  private addSubProcess(id: string, mi: string): RenderNode {
+    const node: RenderNode = {
+      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. */
+  private miCharacteristics(node: Extract<FlowNode, { kind: "forEach" }>): string {
+    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`
+    );
+  }
+
   private emitList(list: FlowNode[], incoming: Edge[], loop: LoopCtx | null): Edge[] {
     let cur = incoming;
     for (const node of list) cur = this.emitNode(node, cur, loop);
@@ -587,9 +858,65 @@ 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. */
+  private renderScope(scope: string | undefined): string {
+    const incomingOf = (id: string) => this.live.filter((e) => e.to === id).map((e) => e.id);
+    const outgoingOf = (id: string) => 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(...)`. */
   private renderStart(outg: string[]): string {
@@ -600,7 +927,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 as string)}</bpmn:timeDate>`;
+          : `<bpmn:timeDate>${escapeXml(requireStartAt(t))}</bpmn:timeDate>`;
     return (
       `    <bpmn:startEvent id="Start">\n` +
       `      ${outgoingOnly(outg)}\n` +
@@ -626,12 +953,9 @@ 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: string) => live.filter((e) => e.to === id).map((e) => e.id);
-    const outgoingOf = (id: string) => live.filter((e) => e.from === id).map((e) => e.id);
+    this.live = this.edges.filter((e) => e.to !== undefined);
 
-    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");
+    const bodyXml = this.renderScope(undefined);
     const messageXml = this.emitMessages();
     const shapeXml = this.emitShapes();
 
@@ -643,9 +967,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 +