@nanobpm/workflow 0.8.2 → 0.10.0

package/dist/nodes/branch.js

@@ -0,0 +1,40 @@
+// 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 { feel } from "../declarative.js";
+import { registerNodeKind } from "./registry.js";
+registerNodeKind("branch", {
+    build: (api) => (condition, arms) => {
+        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/dist/nodes/break.d.ts

@@ -0,0 +1,8 @@
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        break: {
+            kind: "break";
+        };
+    }
+}
+export {};

package/dist/nodes/break.js

@@ -0,0 +1,19 @@
+// 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";
+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/dist/nodes/continue.d.ts

@@ -0,0 +1,8 @@
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        continue: {
+            kind: "continue";
+        };
+    }
+}
+export {};

package/dist/nodes/continue.js

@@ -0,0 +1,18 @@
+// 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";
+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/dist/nodes/forEach.d.ts

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

package/dist/nodes/forEach.js

@@ -0,0 +1,109 @@
+// 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 { assertIdent, escapeXml } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+/** 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) {
+    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, itemVar, body, opts) => {
+        if (typeof collection !== "string" || collection.trim() === "") {
+            throw new Error(`forEach() needs a non-empty FEEL collection expression`);
+        }
+        // Authors may paste a leading "=" (common in Zeebe FEEL examples). Strip it
+        // so the emitter's own "=" prefix never produces an invalid "==...".
+        const collExpr = collection.trim().replace(/^=/, "").trim();
+        if (collExpr === "") {
+            throw new Error(`forEach() collection expression is empty after stripping the leading "="`);
+        }
+        assertIdent("forEach itemVar", itemVar);
+        if (typeof body !== "function")
+            throw new Error(`forEach("${itemVar}") needs a body function`);
+        const nodes = api.childScoped(body);
+        if (nodes.length === 0)
+            throw new Error(`forEach("${itemVar}") body declared no steps`);
+        const node = { kind: "forEach", collection: collExpr, itemVar, body: nodes };
+        if (opts?.sequential)
+            node.sequential = true;
+        if (opts?.outputCollection !== undefined) {
+            assertIdent("forEach outputCollection", opts.outputCollection);
+            node.outputCollection = opts.outputCollection;
+        }
+        if (opts?.outputElement !== undefined) {
+            if (typeof opts.outputElement !== "string" || opts.outputElement.trim() === "") {
+                throw new Error(`forEach("${itemVar}") outputElement must be a non-empty FEEL expression`);
+            }
+            const outEl = opts.outputElement.trim().replace(/^=/, "").trim();
+            if (outEl === "") {
+                throw new Error(`forEach("${itemVar}") outputElement is empty after stripping the leading "="`);
+            }
+            node.outputElement = outEl;
+        }
+        if (opts?.completionCondition !== undefined) {
+            if (typeof opts.completionCondition !== "string" || opts.completionCondition.trim() === "") {
+                throw new Error(`forEach("${itemVar}") completionCondition must be a non-empty FEEL expression`);
+            }
+            const compCond = opts.completionCondition.trim().replace(/^=/, "").trim();
+            if (compCond === "") {
+                throw new Error(`forEach("${itemVar}") completionCondition is empty after stripping the leading "="`);
+            }
+            node.completionCondition = compCond;
+        }
+        if (node.outputElement && !node.outputCollection) {
+            throw new Error(`forEach("${itemVar}") outputElement needs an outputCollection to collect into`);
+        }
+        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/dist/nodes/index.d.ts

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

@@ -0,0 +1,19 @@
+// 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/dist/nodes/loop.d.ts

@@ -0,0 +1,9 @@
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        loop: {
+            kind: "loop";
+            body: FlowNode[];
+        };
+    }
+}
+export {};

package/dist/nodes/loop.js

@@ -0,0 +1,25 @@
+// 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 { registerNodeKind } from "./registry.js";
+registerNodeKind("loop", {
+    build: (api) => (body) => {
+        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 = { 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/dist/nodes/parallel.d.ts

@@ -0,0 +1,9 @@
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        parallel: {
+            kind: "parallel";
+            branches: FlowNode[][];
+        };
+    }
+}
+export {};

package/dist/nodes/parallel.js

@@ -0,0 +1,40 @@
+// 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 { registerNodeKind } from "./registry.js";
+registerNodeKind("parallel", {
+    build: (api) => (branches) => {
+        if (!Array.isArray(branches) || branches.length < 2) {
+            throw new Error(`parallel() needs at least two branch blocks`);
+        }
+        for (const fn of branches) {
+            if (typeof fn !== "function")
+                throw new Error(`parallel() branches must all be blocks (b) => {…}`);
+        }
+        // Each branch runs in its own token scope up to the AND-join, so a
+        // `break`/`continue` must not escape 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/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/registry.d.ts

@@ -0,0 +1,33 @@
+import type { FlowNode } from "../types.js";
+import type { BuildApi, BuilderMethod, Edge, EmitApi, LoopCtx } from "../declarative.js";
+/** Recurse the tree walker into a node's nested bodies (see `walkNodes`). */
+export type WalkRecurse = (body: FlowNode[]) => void;
+/** The three handlers a flow-node kind contributes. `N` is the kind's own
+ *  `FlowNode` variant (narrowed from the union by the registry key). */
+export interface NodeKindHandlers<N extends FlowNode = FlowNode> {
+    /** Factory for the `FlowBuilder` method that appends this kind's node. Given
+     *  the per-body {@link BuildApi}, returns the method installed on the builder
+     *  as `w.<builderMethod ?? kind>`. Omit for a kind with no authoring method. */
+    build?: (api: BuildApi) => BuilderMethod;
+    /** The builder method name, when it differs from the kind (defaults to the
+     *  kind). */
+    builderMethod?: string;
+    /** Depth-first recursion into the node's nested bodies. Omit for a leaf. */
+    walk?: (node: N, recurse: WalkRecurse) => void;
+    /** Emit this node into the BPMN graph, returning the outgoing (dangling)
+     *  edges its continuation attaches to. */
+    emit: (node: N, incoming: Edge[], loop: LoopCtx | null, api: EmitApi) => Edge[];
+}
+/** Register the handlers for one flow-node kind. Called once, at module import
+ *  time, from `src/nodes/<kind>.ts`. */
+export declare function registerNodeKind<K extends FlowNode["kind"]>(kind: K, handlers: NodeKindHandlers<Extract<FlowNode, {
+    kind: K;
+}>>): void;
+/** The handlers registered for a kind, or `undefined` if none. */
+export declare function nodeKind(kind: string): NodeKindHandlers | undefined;
+/** The registered kind, or a thrown error naming the unknown kind — used by the
+ *  emitter, which cannot proceed without a handler. */
+export declare function requireNodeKind(kind: string): NodeKindHandlers;
+/** Every registered kind + its handlers, in registration order. Used by
+ *  `makeBuilder` to install each kind's builder method. */
+export declare function eachNodeKind(): Iterable<[string, NodeKindHandlers]>;

package/dist/nodes/registry.js

@@ -0,0 +1,71 @@
+// The builder-extension seam (epic #314, S0/#315).
+//
+// Every flow-node KIND (`run`/`task`/`signal`/`timer`/`switch`/… and any kind a
+// feature slice adds) contributes THREE things from its own module under
+// `src/nodes/`, and NOTHING is edited centrally:
+//
+//   1. a `FlowNode` variant — by declaration-merging its shape into the
+//      augmentable `FlowNodeRegistry` interface (see `types.ts`), so the
+//      `FlowNode` union grows without editing a central union;
+//   2. a builder method — by declaration-merging its signature into the
+//      `FlowBuilder<C>` interface (see `declarative.ts`) and registering a
+//      `build` factory here, so `w.<method>(…)` is contributed from the module;
+//   3. `walk` + `emit` handlers — registered here, so the tree walker and the
+//      BPMN emitter DISPATCH through this table instead of a central `switch`.
+//
+// A module registers all three with a single `registerNodeKind(kind, {…})` call
+// at import time; the generated barrel `src/nodes/index.ts` imports every kind
+// module for its registration side effect. Adding a kind is therefore: drop one
+// `src/nodes/<kind>.ts` file — no edit to the union, the dispatch, or the barrel.
+//
+// See `src/nodes/README.md` for the exact pattern a slice follows.
+// The dispatcher always looks a handler up by `node.kind` before calling it, so
+// each stored handler only ever receives a node of its own kind. Storing the
+// widened `NodeKindHandlers<FlowNode>` is therefore sound; a kind registers with
+// its own narrowed variant type for authoring ergonomics.
+const kinds = new Map();
+/** Register the handlers for one flow-node kind. Called once, at module import
+ *  time, from `src/nodes/<kind>.ts`. */
+export function registerNodeKind(kind, handlers) {
+    if (kinds.has(kind)) {
+        throw new Error(`flow-node kind "${kind}" is already registered`);
+    }
+    const walk = handlers.walk;
+    const emit = handlers.emit;
+    kinds.set(kind, {
+        builderMethod: handlers.builderMethod,
+        build: handlers.build,
+        walk: walk ? (node, recurse) => walk(narrow(node, kind), recurse) : undefined,
+        emit: (node, incoming, loop, api) => emit(narrow(node, kind), incoming, loop, api),
+    });
+}
+/** Narrow a dispatched node back to a kind's own variant. The discriminant
+ *  check is the proof — no `as` cast. The dispatcher guarantees `node.kind ===
+ *  kind`, so the throw is unreachable in practice. */
+function narrow(node, kind) {
+    if (isKind(node, kind))
+        return node;
+    throw new Error(`internal: node of kind "${node.kind}" dispatched to handler for "${kind}"`);
+}
+function isKind(node, kind) {
+    return node.kind === kind;
+}
+/** The handlers registered for a kind, or `undefined` if none. */
+export function nodeKind(kind) {
+    return kinds.get(kind);
+}
+/** The registered kind, or a thrown error naming the unknown kind — used by the
+ *  emitter, which cannot proceed without a handler. */
+export function requireNodeKind(kind) {
+    const h = kinds.get(kind);
+    if (!h) {
+        throw new Error(`no handler registered for flow-node kind "${kind}" — ` +
+            `did its module under src/nodes/ import and call registerNodeKind()?`);
+    }
+    return h;
+}
+/** Every registered kind + its handlers, in registration order. Used by
+ *  `makeBuilder` to install each kind's builder method. */
+export function eachNodeKind() {
+    return kinds.entries();
+}