@nanobpm/workflow 0.8.2 → 0.9.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,137 @@
+// 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).
+    if (only && (only.kind === "run" || only.kind === "task")) {
+      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,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 "./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/registry.ts

@@ -0,0 +1,105 @@
+// 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.
+
+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[];
+}
+
+// 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<string, NodeKindHandlers>();
+
+/** Register the handlers for one flow-node kind. Called once, at module import
+ *  time, from `src/nodes/<kind>.ts`. */
+export function registerNodeKind<K extends FlowNode["kind"]>(
+  kind: K,
+  handlers: NodeKindHandlers<Extract<FlowNode, { kind: K }>>,
+): void {
+  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<K extends FlowNode["kind"]>(node: FlowNode, kind: K): Extract<FlowNode, { kind: K }> {
+  if (isKind(node, kind)) return node;
+  throw new Error(`internal: node of kind "${node.kind}" dispatched to handler for "${kind}"`);
+}
+
+function isKind<K extends FlowNode["kind"]>(node: FlowNode, kind: K): node is Extract<FlowNode, { kind: K }> {
+  return node.kind === kind;
+}
+
+/** The handlers registered for a kind, or `undefined` if none. */
+export function nodeKind(kind: string): NodeKindHandlers | undefined {
+  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: string): NodeKindHandlers {
+  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(): Iterable<[string, NodeKindHandlers]> {
+  return kinds.entries();
+}

package/src/nodes/run.ts

@@ -0,0 +1,29 @@
+// Built-in flow-node kind: `run` — a durable service task served by a worker
+// THIS program hosts (its handler runs in the in-process `Worker`). Contributed
+// entirely from this module through the extension seam (epic #314, S0/#315):
+// its `FlowNode` variant, its `w.run(...)` builder method, and its walk/emit
+// handlers — with NO edit to the shared union or a central dispatch switch.
+
+import type { NodeEnvelopes, StepHandler } from "../types.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes };
+  }
+}
+
+registerNodeKind("run", {
+  build: (api) => (name: string, handler: StepHandler) => {
+    api.claim(name);
+    if (typeof handler !== "function") throw new Error(`run("${name}") needs a handler function`);
+    api.handlers[name] = handler;
+    api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name) });
+    return api.self();
+  },
+  emit: (node, incoming, _loop, api) => {
+    api.addServiceTask(node);
+    api.connect(incoming, node.name);
+    return [api.newEdge(node.name)];
+  },
+});

package/src/nodes/signal.ts

@@ -0,0 +1,29 @@
+// Built-in flow-node kind: `signal` — a durable wait for an external/human event
+// correlated on a process variable (a BPMN message intermediate catch event).
+// Contributed from this module through the extension seam (epic #314, S0/#315).
+
+import type { Envelope } from "../envelope.js";
+import { assertIdent } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    signal: { kind: "signal"; name: string; correlationKey: string; payload?: Envelope };
+  }
+}
+
+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 });
+    return api.self();
+  },
+  emit: (node, incoming, _loop, api) => {
+    api.addCatchEvent(node);
+    api.connect(incoming, node.name);
+    api.recordEnvelope(node.payload);
+    return [api.newEdge(node.name)];
+  },
+});