@nanobpm/workflow 0.9.0 → 0.11.0

package/dist/nodes/task.js

@@ -2,19 +2,95 @@
 // OUTSIDE this program (no locally-hosted handler). Its job type defaults to the
 // derived `${flowId}:${name}` unless overridden with `{ jobType }`. Contributed
 // from this module through the extension seam (epic #314, S0/#315).
-import { assertJobType } from "../xml.js";
+//
+// This module also owns the AGENT PROMPT BINDING (epic #314, S4/#319): an
+// optional `{ prompt }` option binds an LLM prompt resource to the worker via a
+// `<zeebe:linkedResource … resourceType="GenericScript" linkName="prompt">`,
+// mirroring the nano-workforce agent service tasks. The extension is contributed
+// entirely from this module — the `task` node's own registered emit handler and
+// its option type — WITHOUT re-opening the shared `FlowNode` union, the central
+// `walkNodes`/`emitNode` dispatch, or the generated barrel.
+import { assertJobType, escapeXml } from "../xml.js";
 import { registerNodeKind } from "./registry.js";
+/** Normalize + validate a prompt binding at authoring time, applying the
+ *  `bindingType` default. Emitted string fields are trimmed before storing (in
+ *  parity with how `timer` normalizes `{ after }`/`{ at }`), so a value like
+ *  `resourceId: " retro.md "` passes validation AND is emitted without stray
+ *  surrounding whitespace. Returns a fully-resolved binding stored on the node. */
+function resolvePrompt(name, prompt) {
+    if (typeof prompt !== "object" || prompt === null) {
+        throw new Error(`task("${name}") prompt must be an object with a non-empty resourceId`);
+    }
+    const resourceId = prompt.resourceId;
+    if (typeof resourceId !== "string" || resourceId.trim() === "") {
+        throw new Error(`task("${name}") prompt.resourceId must be a non-empty string`);
+    }
+    // Only an ABSENT bindingType defaults to "latest"; `??` would also swallow an
+    // explicit `null`, masking an authoring mistake. Distinguish `undefined` (use
+    // the default) from any other non-string (reject), in parity with how `append`
+    // below treats `!== undefined` as "provided, so validate strictly".
+    const bindingType = prompt.bindingType === undefined ? "latest" : prompt.bindingType;
+    if (typeof bindingType !== "string" || bindingType.trim() === "") {
+        throw new Error(`task("${name}") prompt.bindingType must be a non-empty string`);
+    }
+    const resolved = { resourceId: resourceId.trim(), bindingType: bindingType.trim() };
+    if (prompt.append !== undefined) {
+        if (typeof prompt.append !== "string" || prompt.append.trim() === "") {
+            throw new Error(`task("${name}") prompt.append must be a non-empty string when provided`);
+        }
+        resolved.append = prompt.append.trim();
+    }
+    return resolved;
+}
+/** Build the prompt-specific `<bpmn:extensionElements>` delta appended to the
+ *  shared service-task emission: the `zeebe:linkedResources` prompt binding and
+ *  (optionally) a `zeebe:ioMapping` `appendPrompt` input. The task shell
+ *  (taskDefinition + envelope properties) is rendered by the built-in
+ *  `EmitApi.addServiceTask`, so this variant only contributes its delta and the
+ *  envelope serialization can never drift from the plain service task. */
+function promptExtensions(prompt) {
+    const { resourceId, bindingType, append } = prompt;
+    const linked = `        <zeebe:linkedResources>\n` +
+        `          <zeebe:linkedResource resourceId="${escapeXml(resourceId)}" ` +
+        `bindingType="${escapeXml(bindingType ?? "latest")}" resourceType="GenericScript" linkName="prompt" />\n` +
+        `        </zeebe:linkedResources>\n`;
+    const io = append !== undefined
+        ? `        <zeebe:ioMapping>\n` +
+            `          <zeebe:input source="${escapeXml(append)}" target="appendPrompt" />\n` +
+            `        </zeebe:ioMapping>\n`
+        : "";
+    return linked + io;
+}
 registerNodeKind("task", {
     build: (api) => (name, opts) => {
         api.claim(name);
         const override = opts?.jobType;
         if (override !== undefined)
             assertJobType("task jobType", override);
-        api.out.push({ kind: "task", name, envelopes: api.contractEnvelopes(name), jobType: override });
+        const prompt = opts?.prompt !== undefined ? resolvePrompt(name, opts.prompt) : undefined;
+        api.out.push({
+            kind: "task",
+            name,
+            envelopes: api.contractEnvelopes(name),
+            jobType: override,
+            prompt,
+        });
         return api.self();
     },
     emit: (node, incoming, _loop, api) => {
-        api.addServiceTask(node);
+        // No prompt → the standard service-task emission is preserved unchanged (no
+        // `linkedResources` are emitted).
+        if (node.prompt === undefined) {
+            api.addServiceTask(node);
+            api.connect(incoming, node.name);
+            return [api.newEdge(node.name)];
+        }
+        // Prompt binding present → the shared `addServiceTask` renders the task
+        // shell (taskDefinition + envelope properties, recording envelopes); we only
+        // supply the `zeebe:linkedResource` (and optional `appendPrompt` ioMapping)
+        // delta, so the envelope/taskDefinition serialization has a single source.
+        const prompt = node.prompt;
+        api.addServiceTask(node, { extraExt: promptExtensions(prompt) });
         api.connect(incoming, node.name);
         return [api.newEdge(node.name)];
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway through @nanobpm/nano-sdk (the shared engine-transport spine — ADR 0055), which negotiates the Falcon protocol on a Nano server and REST elsewhere.",
   "type": "module",
   "license": "Apache-2.0",

package/src/declarative.ts

@@ -622,8 +622,14 @@ export interface EmitApi {
   /** Place a fully custom BPMN element (a slice's own render closure). */
   addNode(node: RenderNode): void;
   /** Place a `<bpmn:serviceTask>` with the standard taskDefinition/envelope
-   *  extension elements (optionally with multi-instance characteristics). */
-  addServiceTask(node: { name: string; envelopes?: NodeEnvelopes; jobType?: string }, mi?: string): void;
+   *  extension elements. `opts.mi` adds multi-instance characteristics; `opts.extraExt`
+   *  injects additional `<bpmn:extensionElements>` content (e.g. a
+   *  `zeebe:linkedResources` prompt binding) after the taskDefinition/properties,
+   *  so a variant task only supplies its delta rather than re-rendering the shell. */
+  addServiceTask(
+    node: { name: string; envelopes?: NodeEnvelopes; jobType?: string },
+    opts?: { mi?: string; extraExt?: string },
+  ): void;
   /** Place a `<bpmn:intermediateCatchEvent>` with a message event definition. */
   addCatchEvent(node: { name: string }): void;
   /** Place a `<bpmn:intermediateCatchEvent>` with a timer event definition. */
@@ -674,7 +680,7 @@ class Compiler {
       addNode: (node) => {
         this.nodes.push({ ...node, scope: node.scope ?? this.currentScope() });
       },
-      addServiceTask: (node, mi) => this.addServiceTask(node, mi),
+      addServiceTask: (node, opts) => this.addServiceTask(node, opts),
       addCatchEvent: (node) => this.addCatchEvent(node),
       addTimerCatchEvent: (node) => this.addTimerCatchEvent(node),
       addGateway: (id, name) => this.addGateway(id, name),
@@ -727,7 +733,11 @@ class Compiler {
     this.envelopes.set(env.name, env.fields);
   }
 
-  private addServiceTask(node: { name: string; envelopes?: NodeEnvelopes; jobType?: string }, mi = ""): void {
+  private addServiceTask(
+    node: { name: string; envelopes?: NodeEnvelopes; jobType?: string },
+    opts: { mi?: string; extraExt?: string } = {},
+  ): void {
+    const { mi = "", extraExt = "" } = opts;
     const type = node.jobType ?? jobType(this.flow.id, node.name);
     this.recordEnvelope(node.envelopes?.in);
     this.recordEnvelope(node.envelopes?.out);
@@ -738,6 +748,7 @@ class Compiler {
       `      <bpmn:extensionElements>\n` +
       `        <zeebe:taskDefinition type="${escapeXml(type)}" />\n` +
       (props.length ? `        <zeebe:properties>\n${props.join("\n")}\n        </zeebe:properties>\n` : "") +
+      extraExt +
       `      </bpmn:extensionElements>`;
     const id = node.name;
     this.nodes.push({
@@ -922,6 +933,7 @@ class Compiler {
     return (
       `<?xml version="1.0" encoding="UTF-8"?>\n` +
       `<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" ` +
+      `xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ` +
       `xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" ` +
       `xmlns:nano="https://nanobpm.io/schema/shapes/1.0" ` +
       `id="Definitions_${escapeXml(this.flow.id)}" targetNamespace="http://bpmn.io/schema/bpmn">\n` +

package/src/index.ts

@@ -43,6 +43,9 @@ export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export type { Journal, ReplayStep } from "./imperative.js";
 export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
+// The `.boundary(...)` option type (its builder method augments FlowBuilder from
+// the boundary kind module — S2/#317).
+export type { BoundaryOptions } from "./nodes/boundary.js";
 export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
 export type {

package/src/nodes/boundary.ts

@@ -0,0 +1,149 @@
+// Flow-node kind: `boundary` — an activity-level attached interrupting timer
+// boundary event (an SLA). Chained onto the activity it guards, it attaches a
+// `<bpmn:boundaryEvent … attachedToRef=… ><bpmn:timerEventDefinition>` to that
+// activity: when the timer elapses the activity is cancelled (interrupting) and
+// the token routes to the `onTimeout` escalation body, which then converges with
+// the activity's normal continuation. Contributed entirely from this module
+// through the extension seam (epic #314, S2/#317) — NO edit to the shared
+// `FlowNode` union, the `walkNodes`/`emitNode` dispatch, or the generated barrel.
+
+import type { FlowNode } from "../types.js";
+import type { Block, Edge } from "../declarative.js";
+import { outgoingOnly } from "../declarative.js";
+import { assertTimerDuration, escapeXml } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+
+/** Options for `.boundary(...)`: an attached timer SLA on the preceding activity.
+ *  - `timer` — the timeout: an ISO-8601 duration (`PT24H`, `P1DT6H`) or a FEEL
+ *    `=`-expression (`=escalationSlaTimeout`); the duration need not be a literal.
+ *  - `onTimeout` — the escalation body run when the timer elapses (its danglers
+ *    converge with the activity's normal continuation).
+ *  - `interrupting` — whether firing cancels the host activity. Defaults to
+ *    `true` (an interrupting boundary; `cancelActivity` omitted, the BPMN default).
+ *    Pass `false` for a non-interrupting boundary (`cancelActivity="false"`).
+ *  - `name` — an optional label for the boundary event. */
+export interface BoundaryOptions<C extends object = object> {
+  timer: string;
+  onTimeout: Block<C>;
+  interrupting?: boolean;
+  name?: string;
+}
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    boundary: {
+      kind: "boundary";
+      /** The derived element id of the activity this boundary attaches to. */
+      attachedTo: string;
+      /** The timeout — an ISO-8601 duration or a FEEL `=`-expression. */
+      timer: string;
+      /** Whether firing cancels the host (interrupting). */
+      interrupting: boolean;
+      /** The escalation body wired from the boundary event's outgoing flow. */
+      onTimeout: FlowNode[];
+      /** Optional boundary-event label. */
+      label?: string;
+    };
+  }
+}
+
+declare module "../declarative.js" {
+  interface FlowBuilder<C extends object> {
+    /**
+     * Attach an interrupting timer boundary event (an SLA) to the PRECEDING
+     * activity (a `run`/`task`). When `timer` elapses, the activity is
+     * cancelled (for an interrupting boundary) and the token routes to the
+     * `onTimeout` escalation body; that body then converges with the activity's
+     * normal continuation. `timer` is an ISO-8601 duration or a FEEL
+     * `=`-expression. Chains as `w.run(...).boundary({ timer, onTimeout })`.
+     */
+    boundary(opts: BoundaryOptions<C>): FlowBuilder<C>;
+  }
+}
+
+/** The flow-node kinds a boundary event may attach to. BPMN restricts boundary
+ *  events to ACTIVITIES, so this is the set of activity kinds (the ones that
+ *  render as a `<bpmn:serviceTask>`) — NOT merely "any node with a `name`", which
+ *  would also admit catch events like `signal`/`timer` and produce invalid BPMN. */
+const BOUNDARY_HOST_KINDS = new Set(["run", "task"]);
+
+/** True for a FEEL expression body (a leading `=`), which renders with an
+ *  `xsi:type="bpmn:tFormalExpression"` marker on the `timeDuration`. */
+function isFeel(value: string): boolean {
+  return value.startsWith("=");
+}
+
+function renderBoundary(id: string, node: Extract<FlowNode, { kind: "boundary" }>, outg: string[]): string {
+  const nameAttr = node.label ? ` name="${escapeXml(node.label)}"` : "";
+  // An interrupting boundary omits `cancelActivity` (its BPMN default is true),
+  // matching the hand-authored nwf goldens; a non-interrupting one is explicit.
+  const cancelAttr = node.interrupting ? "" : ` cancelActivity="false"`;
+  const durType = isFeel(node.timer) ? ` xsi:type="bpmn:tFormalExpression"` : "";
+  return (
+    `    <bpmn:boundaryEvent id="${id}"${nameAttr} attachedToRef="${escapeXml(node.attachedTo)}"${cancelAttr}>\n` +
+    `      ${outgoingOnly(outg)}\n` +
+    `      <bpmn:timerEventDefinition>\n` +
+    `        <bpmn:timeDuration${durType}>${escapeXml(node.timer)}</bpmn:timeDuration>\n` +
+    `      </bpmn:timerEventDefinition>\n` +
+    `    </bpmn:boundaryEvent>`
+  );
+}
+
+registerNodeKind("boundary", {
+  build: (api) => (opts: BoundaryOptions) => {
+    if (!opts || typeof opts !== "object") {
+      throw new Error(`boundary(...) needs { timer, onTimeout }`);
+    }
+    if (typeof opts.timer !== "string" || opts.timer.trim() === "") {
+      throw new Error(`boundary(...) needs a { timer } duration (an ISO-8601 duration or a FEEL =expression)`);
+    }
+    const duration = opts.timer.trim();
+    assertTimerDuration("boundary(...) timer", duration);
+    if (typeof opts.onTimeout !== "function") {
+      throw new Error(`boundary(...) needs an { onTimeout } escalation body (b) => {…}`);
+    }
+    if (opts.interrupting !== undefined && typeof opts.interrupting !== "boolean") {
+      throw new Error(`boundary(...) { interrupting } must be a boolean`);
+    }
+    if (opts.name !== undefined && typeof opts.name !== "string") {
+      throw new Error(`boundary(...) { name } must be a string`);
+    }
+    const host = api.out[api.out.length - 1];
+    if (!host) {
+      throw new Error(`boundary(...) must follow the activity it attaches to (e.g. w.run(...).boundary(...))`);
+    }
+    if (!BOUNDARY_HOST_KINDS.has(host.kind) || !("name" in host) || typeof host.name !== "string") {
+      throw new Error(`boundary(...) can only attach to a named activity (run/task), not a "${host.kind}"`);
+    }
+    const onTimeout = api.child(opts.onTimeout, false);
+    if (onTimeout.length === 0) {
+      throw new Error(`boundary(...) needs a non-empty { onTimeout } escalation body (its outgoing flow has nowhere to go)`);
+    }
+    api.out.push({
+      kind: "boundary",
+      attachedTo: host.name,
+      timer: duration,
+      interrupting: opts.interrupting ?? true,
+      onTimeout,
+      label: opts.name,
+    });
+    return api.self();
+  },
+  walk: (node, recurse) => {
+    recurse(node.onTimeout);
+  },
+  emit: (node, incoming, loop, api) => {
+    // A boundary event has NO incoming sequence flow — it attaches to its host
+    // via `attachedToRef`. Place it, wire its outgoing to the escalation body,
+    // and return the host's normal continuation (`incoming`, passed through)
+    // PLUS the escalation danglers, so both converge on whatever follows.
+    const beId = `Be_${api.nextGw()}`;
+    api.addNode({
+      id: beId,
+      render: (_inc, outg) => renderBoundary(beId, node, outg),
+    });
+    const escalation: Edge = api.newEdge(beId);
+    const escOut = api.emitList(node.onTimeout, [escalation], loop);
+    return [...incoming, ...escOut];
+  },
+});

package/src/nodes/forEach.ts

@@ -115,9 +115,14 @@ registerNodeKind("forEach", {
     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")) {
-      api.addServiceTask(only, mi);
+    // 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)];
     }

package/src/nodes/index.ts

@@ -6,12 +6,14 @@
 // picked up automatically by re-running the generator (a prebuild step) — no
 // hand-edit here.
 
+import "./boundary.js";
 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";

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>`,
+  };
+}

package/src/nodes/signal.ts

@@ -15,9 +15,15 @@ declare module "../types.js" {
 registerNodeKind("signal", {
   build: (api) => (name: string, opts: { correlationKey: string }) => {
     api.claim(name);
-    if (!opts || !opts.correlationKey) throw new Error(`signal("${name}") needs { correlationKey }`);
-    assertIdent("correlationKey", opts.correlationKey);
-    api.out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: api.contracts[name]?.in });
+    if (!opts || typeof opts.correlationKey !== "string" || opts.correlationKey.trim() === "") {
+      throw new Error(`signal("${name}") needs { correlationKey }`);
+    }
+    // Trim before validating/storing, in parity with the race() signal arm: a
+    // value like " prKey " is usable after trimming, so it must not fail the
+    // NCName check on stray whitespace. Name the node in the assertIdent context.
+    const correlationKey = opts.correlationKey.trim();
+    assertIdent(`signal("${name}") correlationKey`, correlationKey);
+    api.out.push({ kind: "signal", name, correlationKey, payload: api.contracts[name]?.in });
     return api.self();
   },
   emit: (node, incoming, _loop, api) => {