@nanobpm/workflow 0.8.2 → 0.10.0

package/src/nodes/README.md

@@ -0,0 +1,123 @@
+# `src/nodes/` — the flow-node kind extension seam
+
+Every flow-node **kind** in the declarative surface (`run`, `task`, `signal`,
+`timer`, `switch`, `branch`, `loop`, `break`, `continue`, `parallel`, `forEach`,
+and any kind a feature slice adds) lives in its **own module** here. Adding a
+kind is: **drop one `src/nodes/<kind>.ts` file.** You never edit a shared union,
+a central `switch`, or the barrel.
+
+This exists so the four wave-1 slices (S1–S4, #316–#319) can each add a kind in
+parallel without textually colliding on — and without any single PR's CI failing
+to exercise — the dispatch that used to be a hand-edited `switch` in two files.
+
+## What a kind module contributes (three things, one file)
+
+A kind module `src/nodes/<kind>.ts` declaration-merges its type surface and
+registers its runtime behaviour with a single `registerNodeKind(...)` call:
+
+1. **Its `FlowNode` variant** — by declaration-merging one property into the
+   augmentable `FlowNodeRegistry` interface (in `../types.js`). `FlowNode` is
+   derived from that registry (`FlowNodeRegistry[keyof FlowNodeRegistry]`), so
+   the union grows automatically — no edit to a central union.
+   - **Invariant:** the property value MUST be an object type whose `kind`
+     discriminant equals the property key, so `FlowNode` stays a discriminated
+     union.
+
+2. **Its builder method** — by declaration-merging the method signature into the
+   `FlowBuilder<C>` interface (in `../declarative.js`) **and** returning a
+   `build` factory from `registerNodeKind`. The factory receives the per-body
+   `BuildApi` and returns the method installed on the builder as
+   `w.<builderMethod ?? kind>(…)`.
+
+3. **Its `walk` + `emit` handlers** — registered in the same call. `walkNodes`
+   and the BPMN emitter DISPATCH through this table instead of a central switch:
+   - `walk(node, recurse)` — recurse into the node's nested bodies (omit for a
+     leaf kind with no nested `FlowNode[]`).
+   - `emit(node, incoming, loop, api)` — place the node's BPMN element(s) via the
+     `EmitApi` primitives and return the outgoing (dangling) `Edge[]` its
+     continuation attaches to.
+
+## The canonical example — `run.ts`
+
+```ts
+import type { NodeEnvelopes, StepHandler } from "../types.js";
+import { registerNodeKind } from "./registry.js";
+
+// (1) the FlowNode variant — declaration-merged into the open registry
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes };
+  }
+}
+
+registerNodeKind("run", {
+  // (2) the builder method — installed as `w.run(...)`
+  build: (api) => (name: string, handler: StepHandler) => {
+    api.claim(name);
+    if (typeof handler !== "function") throw new Error(`run("${name}") needs a handler`);
+    api.handlers[name] = handler;
+    api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name) });
+    return api.self();
+  },
+  // (3a) walk — omitted here: `run` is a leaf (no nested bodies)
+  // (3b) emit — place the BPMN element, wire the edges
+  emit: (node, incoming, _loop, api) => {
+    api.addServiceTask(node);
+    api.connect(incoming, node.name);
+    return [api.newEdge(node.name)];
+  },
+});
+```
+
+A kind with its OWN richer, generically-typed builder signature (like the
+built-ins) also augments `FlowBuilder<C>`:
+
+```ts
+declare module "../declarative.js" {
+  interface FlowBuilder<C extends object> {
+    myKind<K extends string>(name: K, opts: MyOpts): FlowBuilder<C>;
+  }
+}
+```
+
+A kind with nested bodies (like `switch`/`branch`/`loop`) supplies `walk` and
+uses `api.child(fn, inLoop)` / `api.childScoped(fn)` in its `build`, and
+`api.emitList(body, incoming, loop)` in its `emit` — see `switch.ts`, `loop.ts`,
+`forEach.ts`.
+
+## The APIs you get
+
+- **`BuildApi`** (authoring time, in `build`): `id`, `isRoot`, `out`,
+  `contracts`, `handlers`, `loopDepth`, `self()`, `child(fn, inLoop)`,
+  `childScoped(fn)`, `claim(name)`, `contractEnvelopes(name)`, `setStartTimer(t)`.
+- **`EmitApi`** (compile time, in `emit`): `flowId`, `newEdge`, `connect`,
+  `recordEnvelope`, `emitList`, `addNode`, `addServiceTask`, `addCatchEvent`,
+  `addTimerCatchEvent`, `addGateway`, `addParallelGateway`, `addSubProcess`,
+  `addPlainStart`, `addPlainEnd`, `nextGw()`, `currentScope()`, `pushScope`,
+  `popScope`. Node-render string helpers (`incomingOutgoing`, `escapeXml`, …) are
+  exported from `../declarative.js` / `../xml.js` for a custom `RenderNode.render`.
+
+All are exported from `../declarative.js`; the registration function and its
+`NodeKindHandlers<N>` type are in `./registry.js`.
+
+## Rules
+
+- **Never** edit `FlowNodeRegistry` in `types.ts`, the `FlowBuilder<C>` interface
+  outside your own `declare module`, or `index.ts` (it is generated — see below).
+- **Import types with `import type`** (the package uses
+  `verbatimModuleSyntax`).
+- **No `as T` assertions** (repo-wide ban — see the root `AGENTS.md`); narrow with
+  a type guard, an annotation, or `satisfies`.
+- Register **exactly once** per kind (`registerNodeKind` throws on a duplicate
+  kind; builder assembly in `makeBuilder` additionally throws when two kinds
+  contribute the same duplicate builder-method name).
+
+## The generated barrel
+
+`index.ts` is **generated** by `scripts/gen-node-registry.mjs` (a `build`/
+`typecheck` prebuild step): it scans this directory and emits a sorted list of
+side-effect imports so every kind's `registerNodeKind(...)` runs. Because it is
+regenerated and alphabetically ordered, two slices that each add a different
+`<kind>.ts` file merge without conflict and are wired automatically — **do not
+hand-edit `index.ts`.** (`package.json`'s `sideEffects` allowlist keeps a
+downstream bundler from tree-shaking these registrations away.)

package/src/nodes/branch.ts

@@ -0,0 +1,48 @@
+// Built-in flow-node kind: `branch` — a two-way exclusive choice on a FEEL
+// boolean condition (a BPMN exclusive gateway); the `then` arm is guarded, the
+// `else` arm is the gateway default. Contributed through the extension seam.
+
+import type { FlowNode } from "../types.js";
+import type { Block } from "../declarative.js";
+import { feel } from "../declarative.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    branch: { kind: "branch"; condition: string; then: FlowNode[]; else?: FlowNode[] };
+  }
+}
+
+registerNodeKind("branch", {
+  build: (api) => (condition: string, arms: { then: Block; else?: Block }) => {
+    if (typeof condition !== "string" || condition.trim() === "") {
+      throw new Error(`branch() needs a non-empty FEEL condition`);
+    }
+    if (!arms || typeof arms.then !== "function") throw new Error(`branch("${condition}") needs a then arm`);
+    if (arms.else !== undefined && typeof arms.else !== "function") {
+      throw new Error(`branch("${condition}") else arm must be a block (b) => {…}`);
+    }
+    api.out.push({
+      kind: "branch",
+      condition,
+      then: api.child(arms.then, false),
+      else: arms.else ? api.child(arms.else, false) : undefined,
+    });
+    return api.self();
+  },
+  walk: (node, recurse) => {
+    recurse(node.then);
+    if (node.else) recurse(node.else);
+  },
+  emit: (node, incoming, loop, api) => {
+    const id = `Gw_${api.nextGw()}`;
+    const gw = api.addGateway(id);
+    api.connect(incoming, id);
+    const te = api.newEdge(id, { condition: feel(node.condition), name: "then" });
+    const out = api.emitList(node.then, [te], loop);
+    const ee = api.newEdge(id, { name: "else" });
+    gw.defaultFlow = ee.id;
+    out.push(...api.emitList(node.else ?? [], [ee], loop));
+    return out;
+  },
+});

package/src/nodes/break.ts

@@ -0,0 +1,25 @@
+// Built-in flow-node kind: `break` — exit the enclosing loop (routes to whatever
+// follows it). Only valid inside a `loop`. Contributed through the extension seam.
+
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    break: { kind: "break" };
+  }
+}
+
+registerNodeKind("break", {
+  build: (api) => () => {
+    if (api.loopDepth === 0) throw new Error(`break() is only valid inside a loop`);
+    api.out.push({ kind: "break" });
+    return api.self();
+  },
+  emit: (_node, incoming, loop, api) => {
+    if (!loop) throw new Error(`break outside a loop in flow "${api.flowId}"`);
+    // The incoming edges (from the previous node) become the loop's exit
+    // danglers; this path does not fall through.
+    loop.breaks.push(...incoming);
+    return [];
+  },
+});

package/src/nodes/continue.ts

@@ -0,0 +1,24 @@
+// Built-in flow-node kind: `continue` — jump straight back to the top of the
+// enclosing loop, skipping the rest of the body. Only valid inside a `loop`.
+// Contributed through the extension seam (epic #314, S0/#315).
+
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    continue: { kind: "continue" };
+  }
+}
+
+registerNodeKind("continue", {
+  build: (api) => () => {
+    if (api.loopDepth === 0) throw new Error(`continue() is only valid inside a loop`);
+    api.out.push({ kind: "continue" });
+    return api.self();
+  },
+  emit: (_node, incoming, loop, api) => {
+    if (!loop) throw new Error(`continue outside a loop in flow "${api.flowId}"`);
+    api.connect(incoming, loop.headId);
+    return [];
+  },
+});

package/src/nodes/forEach.ts

@@ -0,0 +1,142 @@
+// Built-in flow-node kind: `forEach` — a data-driven fan-out over a runtime
+// collection (a BPMN parallel/sequential multi-instance activity). A single
+// service-task body lifts the MI characteristics directly; a multi-step body is
+// wrapped in an embedded MI sub-process. Contributed through the extension seam.
+
+import type { FlowNode } from "../types.js";
+import type { Block } from "../declarative.js";
+import { assertIdent, escapeXml } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+
+/** The `forEach` node shape (its `FlowNode` variant). */
+interface ForEachNode {
+  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;
+}
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    forEach: ForEachNode;
+  }
+}
+
+interface ForEachOpts {
+  sequential?: boolean;
+  outputCollection?: string;
+  outputElement?: string;
+  completionCondition?: string;
+}
+
+/** The `<bpmn:multiInstanceLoopCharacteristics>` block for a `forEach` node — the
+ *  same shape whether lifted onto a leaf service task or a sub-process. */
+function miCharacteristics(node: ForEachNode): 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`
+  );
+}
+
+registerNodeKind("forEach", {
+  build: (api) => (collection: string, itemVar: string, body: Block, opts?: ForEachOpts) => {
+    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 = api.childScoped(body);
+    if (nodes.length === 0) throw new Error(`forEach("${itemVar}") body declared no steps`);
+    const node: ForEachNode = { 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`);
+    }
+    api.out.push(node);
+    return api.self();
+  },
+  walk: (node, recurse) => recurse(node.body),
+  emit: (node, incoming, _loop, api) => {
+    const mi = 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). A prompt-carrying `task` is deliberately
+    // EXCLUDED from this fast path: computing its `zeebe:linkedResources`/
+    // `appendPrompt` delta lives in the `task` kind's own emitter, so lifting it
+    // here would silently drop that binding. It falls through to the sub-process
+    // path, where the `task` emitter renders the agent service task (prompt
+    // intact) inside the MI scope.
+    if (only && (only.kind === "run" || (only.kind === "task" && only.prompt === undefined))) {
+      api.addServiceTask(only, { mi });
+      api.connect(incoming, only.name);
+      return [api.newEdge(only.name)];
+    }
+    const subId = `Sub_${api.nextGw()}`;
+    api.addSubProcess(subId, mi);
+    api.connect(incoming, subId);
+    api.pushScope(subId);
+    const startId = `${subId}_start`;
+    api.addPlainStart(startId);
+    const innerOut = api.emitList(node.body, [api.newEdge(startId)], null);
+    const endId = `${subId}_end`;
+    api.addPlainEnd(endId);
+    api.connect(innerOut, endId);
+    api.popScope();
+    return [api.newEdge(subId)];
+  },
+});

package/src/nodes/index.ts

@@ -0,0 +1,20 @@
+// GENERATED by scripts/gen-node-registry.mjs — do not edit by hand.
+//
+// The barrel of built-in flow-node kind modules. Importing this module runs
+// every kind's `registerNodeKind(...)` side effect, populating the dispatch
+// table `makeBuilder`/`walkNodes`/the emitter route through. A new kind is
+// picked up automatically by re-running the generator (a prebuild step) — no
+// hand-edit here.
+
+import "./branch.js";
+import "./break.js";
+import "./continue.js";
+import "./forEach.js";
+import "./loop.js";
+import "./parallel.js";
+import "./race.js";
+import "./run.js";
+import "./signal.js";
+import "./switch.js";
+import "./task.js";
+import "./timer.js";

package/src/nodes/loop.ts

@@ -0,0 +1,34 @@
+// Built-in flow-node kind: `loop` — a durable loop (a back-edge to the loop
+// head): the body runs, then control returns to the top unless a branch calls
+// `break()`. Contributed through the extension seam (epic #314, S0/#315).
+
+import type { FlowNode } from "../types.js";
+import type { Block, LoopCtx } from "../declarative.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    loop: { kind: "loop"; body: FlowNode[] };
+  }
+}
+
+registerNodeKind("loop", {
+  build: (api) => (body: Block) => {
+    if (typeof body !== "function") throw new Error(`loop() needs a body function`);
+    api.out.push({ kind: "loop", body: api.child(body, true) });
+    return api.self();
+  },
+  walk: (node, recurse) => recurse(node.body),
+  emit: (node, incoming, _loop, api) => {
+    const headId = `Loop_${api.nextGw()}`;
+    api.addGateway(headId);
+    api.connect(incoming, headId);
+    const ctx: LoopCtx = { headId, breaks: [] };
+    const headOut = api.newEdge(headId);
+    const bodyOut = api.emitList(node.body, [headOut], ctx);
+    // Normal fall-through of the body loops back to the head (continue).
+    api.connect(bodyOut, headId);
+    // The loop exits only via break edges.
+    return ctx.breaks;
+  },
+});

package/src/nodes/parallel.ts

@@ -0,0 +1,48 @@
+// Built-in flow-node kind: `parallel` — a static parallel fork/join (a pair of
+// BPMN parallel gateways): every block runs concurrently on its own branch, and
+// control continues only once ALL branches reach the AND-join. Contributed
+// through the extension seam (epic #314, S0/#315).
+
+import type { FlowNode } from "../types.js";
+import type { Block } from "../declarative.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    parallel: { kind: "parallel"; branches: FlowNode[][] };
+  }
+}
+
+registerNodeKind("parallel", {
+  build: (api) => (branches: Block[]) => {
+    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 into an enclosing loop. Scope branches
+    // (loopDepth resets to 0) so cross-boundary break/continue is rejected.
+    api.out.push({ kind: "parallel", branches: branches.map((fn) => api.childScoped(fn)) });
+    return api.self();
+  },
+  walk: (node, recurse) => {
+    for (const branch of node.branches) recurse(branch);
+  },
+  emit: (node, incoming, loop, api) => {
+    // A diverging parallel gateway forks a token onto every branch; a converging
+    // one joins them (AND-join) into a single continuation.
+    const splitId = `Gw_${api.nextGw()}`;
+    api.addParallelGateway(splitId);
+    api.connect(incoming, splitId);
+    const joinId = `Gw_${api.nextGw()}`;
+    api.addParallelGateway(joinId);
+    for (const branch of node.branches) {
+      const e = api.newEdge(splitId);
+      const branchOut = api.emitList(branch, [e], loop);
+      api.connect(branchOut, joinId);
+    }
+    return [api.newEdge(joinId)];
+  },
+});

package/src/nodes/race.ts

@@ -0,0 +1,185 @@
+// Flow-node kind: `race` — a first-of event race (a BPMN event-based gateway).
+// The gateway forks to one intermediate catch event per arm — a MESSAGE catch for
+// a `signal` arm (correlated on a process variable) or a TIMER catch for a `timer`
+// arm — and the engine arms them all at once. The FIRST event to fire wins: its
+// arm's `do` body runs and the losing catch events are cancelled; each arm's body
+// then converges on whatever follows the race.
+//
+// Contributed entirely from this module through the wave-0 extension seam (epic
+// #314, S1/#316): its `FlowNode` variant (declaration-merged into the augmentable
+// `FlowNodeRegistry`), its `w.race(...)` builder method (merged into
+// `FlowBuilder<C>`), and its `walk`/`emit` handlers — with NO edit to the shared
+// `FlowNode` union, the `walkNodes`/`emitNode` dispatch, or the generated barrel.
+//
+// The catch arms are modelled as nested `signal`/`timer` `FlowNode`s so the whole
+// machine reuses the built-ins: `walk` recurses into them (so the shared message
+// emitter lifts each `signal` arm's `<bpmn:message>` + correlation subscription
+// automatically, and `WorkflowClient.signal` can correlate to it), and `emit`
+// dispatches each arm's catch through its own registered handler (so a race's
+// catch is byte-identical to a standalone `w.signal`/`w.timer`). Only the
+// event-based gateway itself is placed here.
+
+import type { FlowNode } from "../types.js";
+import type { Block, Edge, RenderNode } from "../declarative.js";
+import { incomingOutgoing } from "../declarative.js";
+import { assertIdent, assertTimerDate, assertTimerDuration, escapeXml } from "../xml.js";
+import { registerNodeKind, requireNodeKind } from "./registry.js";
+
+/** One arm of a {@link FlowBuilder.race}: exactly one waited-for event — a
+ *  `signal` (a message catch correlated on a process variable) OR a `timer` (a
+ *  delay `{ after }` or an instant `{ at }`) — plus the `do` body that runs when
+ *  that event wins the race. */
+export type RaceArm = ({ signal: { correlationKey: string } } | { timer: { after: string } | { at: string } }) & {
+  do: Block;
+};
+
+/** A compiled race arm: its catch event (a `signal` or `timer` `FlowNode`, reused
+ *  from the built-ins) and the body that runs when it wins. */
+interface CompiledArm {
+  event: FlowNode;
+  body: FlowNode[];
+}
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    race: { kind: "race"; arms: CompiledArm[] };
+  }
+}
+
+declare module "../declarative.js" {
+  interface FlowBuilder<C extends object> {
+    /**
+     * A first-of event race — a BPMN event-based gateway. Each named arm waits on
+     * exactly one event: a `signal` (a durable message catch correlated on a
+     * process variable) or a `timer` (`{ after }` a delay, or `{ at }` an
+     * instant). The engine arms every catch at once; the FIRST to fire wins, its
+     * arm's `do` body runs, and the losing catch events are cancelled. Every arm's
+     * body converges on whatever follows the race.
+     *
+     * ```ts
+     * w.race({
+     *   "review-ready":   { signal: { correlationKey: "prKey" }, do: (b) => b.run("re-review", reReview) },
+     *   "review-timeout": { timer:  { after: "=reviewWaitTimeout" }, do: (b) => b.run("escalate", escalate) },
+     * });
+     * ```
+     */
+    race(arms: Record<string, RaceArm>): FlowBuilder<C>;
+  }
+}
+
+function hasSignal(spec: RaceArm): spec is { signal: { correlationKey: string } } & { do: Block } {
+  return "signal" in spec && spec.signal !== null && typeof spec.signal === "object";
+}
+
+function hasTimer(spec: RaceArm): spec is { timer: { after: string } | { at: string } } & { do: Block } {
+  return "timer" in spec && spec.timer !== null && typeof spec.timer === "object";
+}
+
+registerNodeKind("race", {
+  build: (api) => (arms: Record<string, RaceArm>) => {
+    if (arms === null || typeof arms !== "object") {
+      throw new Error(`race() needs an arms object { "<name>": { signal | timer, do } }`);
+    }
+    const entries = Object.entries(arms);
+    if (entries.length < 2) {
+      throw new Error(
+        `race() needs at least two arms (an event-based gateway with fewer than two events is degenerate)`,
+      );
+    }
+    const compiled: CompiledArm[] = [];
+    for (const [name, spec] of entries) {
+      if (spec === null || typeof spec !== "object") {
+        throw new Error(`race() arm "${name}" must be an object { signal | timer, do }`);
+      }
+      const isSignal = hasSignal(spec);
+      const isTimer = hasTimer(spec);
+      if (isSignal === isTimer) {
+        throw new Error(
+          `race() arm "${name}" needs exactly one of { signal: { correlationKey } } or { timer: { after | at } }`,
+        );
+      }
+      if (typeof spec.do !== "function") {
+        throw new Error(`race() arm "${name}" needs a do block (b) => {…}`);
+      }
+      api.claim(name);
+      let event: FlowNode;
+      if (isSignal) {
+        const rawKey = spec.signal.correlationKey;
+        if (typeof rawKey !== "string" || rawKey.trim() === "") {
+          throw new Error(`race() arm "${name}" signal needs a non-empty { correlationKey }`);
+        }
+        // Trim before validating/storing, in parity with the timer arm ({ after }/
+        // { at } are trimmed above): a value like " prKey " is usable after
+        // trimming, so it must not fail the NCName check on stray whitespace. The
+        // assertIdent context names the arm so a failure says WHICH arm is invalid.
+        const correlationKey = rawKey.trim();
+        assertIdent(`race() arm "${name}" signal correlationKey`, correlationKey);
+        event = { kind: "signal", name, correlationKey, payload: api.contracts[name]?.in };
+      } else {
+        const timer = spec.timer;
+        // Enforce exactly-one on KEY PRESENCE, not string-ness: a runtime-invalid
+        // arm that supplies both keys where only one is a string (e.g.
+        // `{ after: 1, at: "…" }`) must be rejected here, not silently dispatched
+        // into `after.trim()` — which would throw an opaque TypeError. Once the
+        // branch is chosen, validate the value is a string before trimming.
+        const hasAfterKey = "after" in timer;
+        const hasAtKey = "at" in timer;
+        if (hasAfterKey === hasAtKey) {
+          throw new Error(`race() arm "${name}" timer needs exactly one of { after } (a delay) or { at } (an instant)`);
+        }
+        if ("after" in timer) {
+          if (typeof timer.after !== "string") {
+            throw new Error(`race() arm "${name}" timer { after } must be a string duration`);
+          }
+          const after = timer.after.trim();
+          assertTimerDuration(`race() arm "${name}" timer after`, after);
+          event = { kind: "timer", name, after };
+        } else {
+          if (typeof timer.at !== "string") {
+            throw new Error(`race() arm "${name}" timer { at } must be a string instant`);
+          }
+          const at = timer.at.trim();
+          assertTimerDate(`race() arm "${name}" timer at`, at);
+          event = { kind: "timer", name, at };
+        }
+      }
+      compiled.push({ event, body: api.child(spec.do, false) });
+    }
+    api.out.push({ kind: "race", arms: compiled });
+    return api.self();
+  },
+  walk: (node, recurse) => {
+    // Recurse into each arm's catch event AND its body: the catch `signal` nodes
+    // must be visited so the shared message emitter lifts their `<bpmn:message>`
+    // + correlation subscription, and body `task` nodes so their external job
+    // types are discovered — exactly as a standalone `signal`/`task` would be.
+    for (const arm of node.arms) recurse([arm.event, ...arm.body]);
+  },
+  emit: (node, incoming, loop, api) => {
+    const gwId = `Gw_${api.nextGw()}`;
+    api.addNode(eventBasedGateway(gwId, api.currentScope()));
+    api.connect(incoming, gwId);
+    const out: Edge[] = [];
+    for (const arm of node.arms) {
+      // Fork the gateway straight to the arm's catch event (BPMN requires an
+      // event-based gateway's targets to be intermediate catch events), reusing
+      // the arm kind's own registered emit so the catch is identical to a
+      // standalone `w.signal`/`w.timer`; then wire its `do` body onward.
+      const fork = api.newEdge(gwId);
+      const afterCatch = requireNodeKind(arm.event.kind).emit(arm.event, [fork], loop, api);
+      out.push(...api.emitList(arm.body, afterCatch, loop));
+    }
+    return out;
+  },
+});
+
+/** A `<bpmn:eventBasedGateway>` render node (no typed `EmitApi` primitive exists —
+ *  built as a custom {@link RenderNode} from the exported string helpers). */
+function eventBasedGateway(id: string, scope: string | undefined): RenderNode {
+  return {
+    id,
+    scope,
+    render: (inc: string[], outg: string[]) =>
+      `    <bpmn:eventBasedGateway id="${escapeXml(id)}">\n` + incomingOutgoing(inc, outg) + `    </bpmn:eventBasedGateway>`,
+  };
+}