@nanobpm/workflow 0.9.0 → 0.11.0

package/README.md

@@ -53,6 +53,22 @@ human-in-the-loop path), composed with control-flow combinators:
   `itemVar`). `{ sequential }` runs children one at a time; `{ outputCollection,
   outputElement }` collects each child's result into a list; `{ completionCondition }`
   completes the body early.
+- `w.race({ armName: { signal | timer, do }, … })` — a first-of race over ≥2
+  named arms, each waiting on **exactly one** event: a `signal` (a correlated
+  message catch, `{ correlationKey }`) or a `timer` (`{ after }` for a duration or
+  `{ at }` for a date, ISO or a leading-`=` FEEL expression). Whichever arm's event
+  fires **first wins**: its `do` block runs and the losers are cancelled. Compiles
+  to an **event-based gateway** fanning out to one intermediate catch event per arm
+  (a message- or timer-event-definition), the arm bodies rejoining downstream by an
+  implicit XOR merge. This is the shape a convergence loop uses to bound a
+  human-in-the-loop wait with a timeout.
+- `w.run(...).boundary({ timer, onTimeout, interrupting?, name? })` — attach an
+  SLA (an interrupting timer boundary event) to the PRECEDING activity: when
+  `timer` elapses the activity is cancelled and the token routes to the
+  `onTimeout` escalation body, which then converges with the activity's normal
+  continuation. `timer` is an ISO-8601 duration (`PT24H`) or a FEEL
+  `=`-expression (`=escalationSlaTimeout`). `interrupting` defaults to `true`
+  (pass `false` for a non-interrupting boundary that leaves the activity running).
 
 ```ts
 import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";
@@ -94,13 +110,35 @@ const convergence = defineFlow("convergence-loop", (w) => {
 });
 ```
 
-Each combinator compiles to a BPMN primitive the engine already runs: `switch` /
+Bound a human-in-the-loop wait with a timeout — `w.race` resolves to whichever
+arm fires first, cancelling the loser:
+
+```ts
+const reviewWait = defineFlow("review-wait", (w) => {
+  w.run("request-review", async (job) => ({ prKey: job.variables.prKey }));
+  w.race({
+    "review-arrived": {
+      signal: { correlationKey: "prKey" },
+      do: (b) => b.run("apply-review", applyReview),
+    },
+    "review-timed-out": {
+      timer: { after: "=reviewWaitTimeout" }, // FEEL duration, e.g. "PT48H"
+      do: (b) => b.run("escalate", escalate),
+    },
+  });
+  w.run("finalize", finalize);
+});
+```
+
+`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; `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**.
+multi-instance sub-process (a multi-step body); `race` → an **event-based
+gateway** fanning out to one intermediate catch event per arm (message or timer),
+first event wins and cancels the losers. See **ADR 0047**.
 
 #### Typed data envelopes (eject to model-first with contracts intact)
 
@@ -128,6 +166,46 @@ const orders = defineFlow(
 );
 ```
 
+#### Agent tasks — bind an LLM prompt to a worker (`w.task(name, { prompt })`)
+
+An **agent service task** is a `w.task` that additionally binds an LLM **prompt
+resource** to the worker that services it. Pass a `prompt` alongside the
+`jobType` capability token and the emitter adds a
+`<zeebe:linkedResource … resourceType="GenericScript" linkName="prompt">` to the
+task's `zeebe:taskDefinition` — the shape the nano-workforce agent tasks use to
+attach a prompt script to the (e.g. `senior:retro`) agent pool that runs the job:
+
+```ts
+w.task("synthesize", {
+  jobType: "senior:retro",              // the agent capability token
+  prompt: {
+    resourceId: "retro.md",             // the GenericScript resource bound as the prompt
+    bindingType: "latest",              // optional — how the version resolves (default "latest")
+    append: "=retroDigest",             // optional — FEEL fed to a zeebe:ioMapping `appendPrompt` input
+  },
+});
+```
+
+derives:
+
+```xml
+<bpmn:serviceTask id="synthesize" name="synthesize">
+  <bpmn:extensionElements>
+    <zeebe:taskDefinition type="senior:retro" />
+    <zeebe:linkedResources>
+      <zeebe:linkedResource resourceId="retro.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+    </zeebe:linkedResources>
+    <zeebe:ioMapping>
+      <zeebe:input source="=retroDigest" target="appendPrompt" />
+    </zeebe:ioMapping>
+  </bpmn:extensionElements>
+</bpmn:serviceTask>
+```
+
+Only `resourceId` is required; omit `append` and no `ioMapping` is emitted. A
+`w.task` **without** a `prompt` is unchanged — it emits no `linkedResources`.
+Data envelopes (via contracts) still lift alongside the prompt binding.
+
 ### Imperative (Temporal-style, engine-replayed) — experimental/internal
 
 Write the orchestration as a function. `ctx.run(name, fn)` is a durable step: its

package/dist/declarative.d.ts

@@ -288,12 +288,18 @@ 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). */
+     *  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;
-    }, mi?: string): void;
+    }, opts?: {
+        mi?: string;
+        extraExt?: string;
+    }): void;
     /** Place a `<bpmn:intermediateCatchEvent>` with a message event definition. */
     addCatchEvent(node: {
         name: string;

package/dist/declarative.js

@@ -356,7 +356,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),
@@ -404,7 +404,8 @@ class Compiler {
         }
         this.envelopes.set(env.name, env.fields);
     }
-    addServiceTask(node, mi = "") {
+    addServiceTask(node, opts = {}) {
+        const { mi = "", extraExt = "" } = opts;
         const type = node.jobType ?? jobType(this.flow.id, node.name);
         this.recordEnvelope(node.envelopes?.in);
         this.recordEnvelope(node.envelopes?.out);
@@ -416,6 +417,7 @@ class Compiler {
         const ext = `      <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({
@@ -575,6 +577,7 @@ class Compiler {
         const shapeXml = this.emitShapes();
         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/dist/index.d.ts

@@ -2,6 +2,7 @@ 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";
+export type { BoundaryOptions } from "./nodes/boundary.js";
 export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
 export type { Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, ScalarTs, FieldTs, } from "./envelope.js";

package/dist/nodes/boundary.d.ts

@@ -0,0 +1,46 @@
+import type { Block } from "../declarative.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>;
+    }
+}

package/dist/nodes/boundary.js

@@ -0,0 +1,92 @@
+// 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 { outgoingOnly } from "../declarative.js";
+import { assertTimerDuration, escapeXml } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+/** 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) {
+    return value.startsWith("=");
+}
+function renderBoundary(id, node, outg) {
+    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) => {
+        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 = api.newEdge(beId);
+        const escOut = api.emitList(node.onTimeout, [escalation], loop);
+        return [...incoming, ...escOut];
+    },
+});

package/dist/nodes/forEach.js

@@ -82,9 +82,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/dist/nodes/index.d.ts

@@ -1,9 +1,11 @@
+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/dist/nodes/index.js

@@ -5,12 +5,14 @@
 // 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 "./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/dist/nodes/race.d.ts

@@ -0,0 +1,54 @@
+import type { FlowNode } from "../types.js";
+import type { Block } from "../declarative.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>;
+    }
+}
+export {};

package/dist/nodes/race.js

@@ -0,0 +1,134 @@
+// 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 { incomingOutgoing } from "../declarative.js";
+import { assertIdent, assertTimerDate, assertTimerDuration, escapeXml } from "../xml.js";
+import { registerNodeKind, requireNodeKind } from "./registry.js";
+function hasSignal(spec) {
+    return "signal" in spec && spec.signal !== null && typeof spec.signal === "object";
+}
+function hasTimer(spec) {
+    return "timer" in spec && spec.timer !== null && typeof spec.timer === "object";
+}
+registerNodeKind("race", {
+    build: (api) => (arms) => {
+        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 = [];
+        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;
+            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 = [];
+        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, scope) {
+    return {
+        id,
+        scope,
+        render: (inc, outg) => `    <bpmn:eventBasedGateway id="${escapeXml(id)}">\n` + incomingOutgoing(inc, outg) + `    </bpmn:eventBasedGateway>`,
+    };
+}

package/dist/nodes/signal.js

@@ -6,10 +6,15 @@ import { registerNodeKind } from "./registry.js";
 registerNodeKind("signal", {
     build: (api) => (name, opts) => {
         api.claim(name);
-        if (!opts || !opts.correlationKey)
+        if (!opts || typeof opts.correlationKey !== "string" || opts.correlationKey.trim() === "") {
             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 });
+        }
+        // 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) => {

package/dist/nodes/task.d.ts

@@ -1,3 +1,22 @@
+/** Binds an LLM prompt resource to an agent service task. Emits, alongside the
+ *  task's `zeebe:taskDefinition` capability token, a
+ *  `<zeebe:linkedResources><zeebe:linkedResource resourceId=… bindingType=…
+ *  resourceType="GenericScript" linkName="prompt"/></zeebe:linkedResources>`
+ *  extension — the shape the nano-workforce agent tasks use to attach a prompt
+ *  script to the worker that services the job. */
+export interface PromptBinding {
+    /** The `GenericScript` resource id bound as the prompt (the linkedResource
+     *  `resourceId`, e.g. `"retro.md"`). Required and non-empty. */
+    resourceId: string;
+    /** The linkedResource `bindingType` — how the engine resolves the resource
+     *  version at deploy time. Defaults to `"latest"`. */
+    bindingType?: string;
+    /** Optional prompt addendum: a FEEL expression (or literal) fed to the worker
+     *  through a `<zeebe:ioMapping><zeebe:input source=… target="appendPrompt"/>`
+     *  input, the convention the agent tasks use to append runtime context to the
+     *  bound prompt. Omitted → no `ioMapping` is emitted. */
+    append?: string;
+}
 declare module "../types.js" {
     interface FlowNodeRegistry {
         task: {
@@ -5,7 +24,24 @@ declare module "../types.js" {
             name: string;
             envelopes?: NodeEnvelopes;
             jobType?: string;
+            /** The agent prompt binding, when the task is an LLM-agent service task. */
+            prompt?: PromptBinding;
         };
     }
 }
-export {};
+declare module "../declarative.js" {
+    interface FlowBuilder<C extends object> {
+        /**
+         * An AGENT external service task: as `task`, but additionally binds an LLM
+         * `prompt` resource to the worker via a `zeebe:linkedResource`
+         * (`resourceType="GenericScript" linkName="prompt"`). Pair it with a
+         * `{ jobType }` capability token (e.g. `senior:retro`) so an agent pool
+         * services it. `prompt.append` (optional) feeds a FEEL expression to the
+         * worker through a `zeebe:ioMapping` `appendPrompt` input.
+         */
+        task<K extends string>(name: K, opts: {
+            jobType?: string;
+            prompt: PromptBinding;
+        }): FlowBuilder<C>;
+    }
+}