@nanobpm/workflow 0.10.0 → 0.12.0

package/README.md

@@ -36,13 +36,24 @@ Both compile to the same engine durability; pick per workflow.
 **The recommended surface.** Describe the flow as a **tree of nodes**: `w.run` (a
 locally-hosted service task), `w.task` (an external-worker service task — job
 type `${flowId}:${name}` by default, or pass `w.task(name, { jobType })` to
-target an existing worker pool, e.g. a `senior:pr-review` agent token), and
+target an existing worker pool, e.g. a `senior:pr-review` agent token),
 `w.signal` (a durable message catch that resumes via a correlated message — the
-human-in-the-loop path), composed with control-flow combinators:
+human-in-the-loop path), and `w.human` (a BPMN **user task** — a human-in-the-loop
+approval gate rendered on a task list), composed with control-flow combinators:
 
 - `w.switch(subject, cases)` — a multi-way exclusive choice; each case key routes
   when `subject = value`; an optional `default` case is the fallback.
 - `w.branch(condition, { then, else? })` — a two-way choice on a FEEL boolean.
+- `w.human(name, { form, assignee?, candidateGroups?, io? })` — a durable **user
+  task** (`<bpmn:userTask>` with the Zeebe user-task marker). `form` binds a
+  `zeebe:formDefinition` (the form id shown to the assignee). Add an assignment
+  with `assignee` (a static user id or a FEEL expression like
+  `=escalationAssignee`) and/or `candidateGroups` (who may claim it) — supply
+  either or both. `io` adds a `zeebe:ioMapping` of `{ input?, output? }` entries
+  (`{ source, target }`: a FEEL `source` copied to/from the process variable
+  `target`), e.g. to stamp the reviewer's decision back onto a variable on
+  completion. The token waits durably until the task is completed from a task
+  list / the Zeebe user-task API.
 - `w.loop(body)` — a durable loop (back-edge to the loop head).
 - `w.break()` / `w.continue()` — exit the enclosing loop, or jump back to its head.
 - `w.parallel([blockA, blockB, …])` — a static fork/join: every block runs
@@ -62,6 +73,13 @@ human-in-the-loop path), composed with control-flow combinators:
   (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";
@@ -81,6 +99,25 @@ const { processInstanceKey } = await client.start(onboarding, {});
 await client.signal(onboarding, "approved", userId, { by: "alice" });
 ```
 
+A human-in-the-loop **approval gate** with a form, an assignment, and an output
+mapping that stamps the decision back onto a process variable:
+
+```ts
+const review = defineFlow("plan-review", (w) => {
+  w.human("plan-review-decision", {
+    form: "plan-review-decision",         // zeebe:formDefinition formId
+    assignee: "=escalationAssignee",       // a FEEL expression (or a static user id)
+    candidateGroups: "operators",          // who may claim it
+    io: { output: [{ source: "=verdict", target: "planVerdict" }] },
+  });
+  w.switch("planVerdict", {
+    approve: (c) => c.run("apply", applyPlan),
+    default: (c) => c.run("revise", revisePlan),
+  });
+});
+```
+
+
 A durable convergence loop (the shape `urban-pr-review` uses) — a loop wrapping a
 status switch with a nested guard:
 

package/dist/declarative.js

@@ -577,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,8 @@ 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 type { HumanOptions, HumanIoMapping, HumanIoEntry } from "./nodes/human.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/human.d.ts

@@ -0,0 +1,57 @@
+/** A single Zeebe I/O mapping entry — a FEEL `source` copied to/from a process
+ *  variable `target`. */
+export interface HumanIoEntry {
+    /** FEEL expression evaluated for the mapping (e.g. `=orderId`). */
+    source: string;
+    /** The process variable the value is written to. */
+    target: string;
+}
+/** The `<zeebe:ioMapping>` for a user task: input mappings applied on activation
+ *  and output mappings applied on completion. */
+export interface HumanIoMapping {
+    input?: HumanIoEntry[];
+    output?: HumanIoEntry[];
+}
+/** Options for {@link FlowBuilder.human}. `form` is the `zeebe:formDefinition`
+ *  form id; `assignee` / `candidateGroups` populate a `zeebe:assignmentDefinition`
+ *  (supply either or both); `io` populates a `zeebe:ioMapping`. */
+export interface HumanOptions {
+    /** The `zeebe:formDefinition` form id bound to this task. */
+    form: string;
+    /** A single assignee (a static user id or a FEEL expression like
+     *  `=escalationAssignee`). */
+    assignee?: string;
+    /** The candidate groups allowed to claim the task (a static group id or a FEEL
+     *  expression). */
+    candidateGroups?: string;
+    /** Input/output variable mappings. */
+    io?: HumanIoMapping;
+}
+/** The `human` node shape (its `FlowNode` variant). */
+interface HumanNode {
+    kind: "human";
+    name: string;
+    form: string;
+    assignee?: string;
+    candidateGroups?: string;
+    io?: HumanIoMapping;
+}
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        human: HumanNode;
+    }
+}
+declare module "../declarative.js" {
+    interface FlowBuilder<C extends object> {
+        /**
+         * A human-in-the-loop approval step (a BPMN `<bpmn:userTask>` with the Zeebe
+         * user-task marker). `opts.form` binds a `zeebe:formDefinition`; the optional
+         * `assignee` / `candidateGroups` populate a `zeebe:assignmentDefinition`
+         * (either or both), and `io` populates a `zeebe:ioMapping`. Resume it from a
+         * task list / the Zeebe user-task API; the token waits durably until the task
+         * is completed.
+         */
+        human<K extends string>(name: K, opts: HumanOptions): FlowBuilder<C>;
+    }
+}
+export {};

package/dist/nodes/human.js

@@ -0,0 +1,111 @@
+// Built-in flow-node kind: `human` — a human-in-the-loop approval step (a BPMN
+// `<bpmn:userTask>` with the Zeebe user-task marker). It carries a form binding
+// and, optionally, an assignment (assignee / candidate groups) and an I/O
+// mapping — the surface every nwf approval gate (answer escalation, plan review,
+// trial-merge decision) is built from. Contributed from this module through the
+// extension seam (epic #314, S3/#318) — no central union or dispatch is edited.
+import { escapeXml } from "../xml.js";
+import { incomingOutgoing } from "../declarative.js";
+import { registerNodeKind } from "./registry.js";
+/** A present, non-empty, non-whitespace-only string — the shape every human()
+ *  id / assignment / mapping-expression field must have. A blank value would
+ *  emit a meaningless BPMN attribute (an empty formId, assignee, candidateGroups,
+ *  or ioMapping source/target) that fails or misbehaves at deploy/run time, so we
+ *  fail fast at build. Non-blank values are kept verbatim — FEEL expressions are
+ *  never trimmed or normalized. */
+function isNonBlankString(v) {
+    return typeof v === "string" && v.trim() !== "";
+}
+function isEntry(e) {
+    if (e === null || typeof e !== "object")
+        return false;
+    if (!("source" in e) || !("target" in e))
+        return false;
+    const { source, target } = e;
+    return isNonBlankString(source) && isNonBlankString(target);
+}
+function validateEntries(name, dir, entries) {
+    if (entries === undefined)
+        return;
+    if (!Array.isArray(entries))
+        throw new Error(`human("${name}") io.${dir} must be an array of { source, target }`);
+    for (const e of entries) {
+        if (!isEntry(e))
+            throw new Error(`human("${name}") io.${dir} entries must be { source: non-empty string, target: non-empty string }`);
+    }
+}
+function renderAssignment(node) {
+    if (node.assignee === undefined && node.candidateGroups === undefined)
+        return "";
+    const attrs = [
+        node.assignee !== undefined ? ` assignee="${escapeXml(node.assignee)}"` : "",
+        node.candidateGroups !== undefined ? ` candidateGroups="${escapeXml(node.candidateGroups)}"` : "",
+    ].join("");
+    return `        <zeebe:assignmentDefinition${attrs} />\n`;
+}
+function renderMappings(entries, tag) {
+    if (!entries || entries.length === 0)
+        return "";
+    return entries
+        .map((e) => `          <zeebe:${tag} source="${escapeXml(e.source)}" target="${escapeXml(e.target)}" />\n`)
+        .join("");
+}
+function renderIoMapping(node) {
+    const io = node.io;
+    if (!io || ((io.input?.length ?? 0) === 0 && (io.output?.length ?? 0) === 0))
+        return "";
+    return (`        <zeebe:ioMapping>\n` +
+        renderMappings(io.input, "input") +
+        renderMappings(io.output, "output") +
+        `        </zeebe:ioMapping>\n`);
+}
+function renderUserTask(node, inc, outg) {
+    const id = node.name;
+    const ext = `      <bpmn:extensionElements>\n` +
+        `        <zeebe:formDefinition formId="${escapeXml(node.form)}" />\n` +
+        `        <zeebe:userTask />\n` +
+        renderAssignment(node) +
+        renderIoMapping(node) +
+        `      </bpmn:extensionElements>`;
+    return (`    <bpmn:userTask id="${escapeXml(id)}" name="${escapeXml(id)}">\n` +
+        ext +
+        "\n" +
+        incomingOutgoing(inc, outg) +
+        `    </bpmn:userTask>`);
+}
+registerNodeKind("human", {
+    build: (api) => (name, opts) => {
+        api.claim(name);
+        if (opts === null || typeof opts !== "object") {
+            throw new Error(`human("${name}") needs an options object { form, … }`);
+        }
+        if (!isNonBlankString(opts.form)) {
+            throw new Error(`human("${name}") needs a non-empty { form } (the zeebe:formDefinition form id)`);
+        }
+        if (opts.assignee !== undefined && !isNonBlankString(opts.assignee)) {
+            throw new Error(`human("${name}") { assignee } must be a non-empty string`);
+        }
+        if (opts.candidateGroups !== undefined && !isNonBlankString(opts.candidateGroups)) {
+            throw new Error(`human("${name}") { candidateGroups } must be a non-empty string`);
+        }
+        if (opts.io !== undefined && (opts.io === null || typeof opts.io !== "object" || Array.isArray(opts.io))) {
+            throw new Error(`human("${name}") { io } must be an object { input?, output? }`);
+        }
+        validateEntries(name, "input", opts.io?.input);
+        validateEntries(name, "output", opts.io?.output);
+        api.out.push({
+            kind: "human",
+            name,
+            form: opts.form,
+            assignee: opts.assignee,
+            candidateGroups: opts.candidateGroups,
+            io: opts.io,
+        });
+        return api.self();
+    },
+    emit: (node, incoming, _loop, api) => {
+        api.addNode({ id: node.name, render: (inc, outg) => renderUserTask(node, inc, outg) });
+        api.connect(incoming, node.name);
+        return [api.newEdge(node.name)];
+    },
+});

package/dist/nodes/index.d.ts

@@ -1,7 +1,9 @@
+import "./boundary.js";
 import "./branch.js";
 import "./break.js";
 import "./continue.js";
 import "./forEach.js";
+import "./human.js";
 import "./loop.js";
 import "./parallel.js";
 import "./race.js";

package/dist/nodes/index.js

@@ -5,10 +5,12 @@
 // 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 "./human.js";
 import "./loop.js";
 import "./parallel.js";
 import "./race.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.10.0",
+  "version": "0.12.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

@@ -933,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,10 @@ 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 type { HumanOptions, HumanIoMapping, HumanIoEntry } from "./nodes/human.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/human.ts

@@ -0,0 +1,179 @@
+// Built-in flow-node kind: `human` — a human-in-the-loop approval step (a BPMN
+// `<bpmn:userTask>` with the Zeebe user-task marker). It carries a form binding
+// and, optionally, an assignment (assignee / candidate groups) and an I/O
+// mapping — the surface every nwf approval gate (answer escalation, plan review,
+// trial-merge decision) is built from. Contributed from this module through the
+// extension seam (epic #314, S3/#318) — no central union or dispatch is edited.
+
+import { escapeXml } from "../xml.js";
+import { incomingOutgoing } from "../declarative.js";
+import { registerNodeKind } from "./registry.js";
+
+/** A single Zeebe I/O mapping entry — a FEEL `source` copied to/from a process
+ *  variable `target`. */
+export interface HumanIoEntry {
+  /** FEEL expression evaluated for the mapping (e.g. `=orderId`). */
+  source: string;
+  /** The process variable the value is written to. */
+  target: string;
+}
+
+/** The `<zeebe:ioMapping>` for a user task: input mappings applied on activation
+ *  and output mappings applied on completion. */
+export interface HumanIoMapping {
+  input?: HumanIoEntry[];
+  output?: HumanIoEntry[];
+}
+
+/** Options for {@link FlowBuilder.human}. `form` is the `zeebe:formDefinition`
+ *  form id; `assignee` / `candidateGroups` populate a `zeebe:assignmentDefinition`
+ *  (supply either or both); `io` populates a `zeebe:ioMapping`. */
+export interface HumanOptions {
+  /** The `zeebe:formDefinition` form id bound to this task. */
+  form: string;
+  /** A single assignee (a static user id or a FEEL expression like
+   *  `=escalationAssignee`). */
+  assignee?: string;
+  /** The candidate groups allowed to claim the task (a static group id or a FEEL
+   *  expression). */
+  candidateGroups?: string;
+  /** Input/output variable mappings. */
+  io?: HumanIoMapping;
+}
+
+/** The `human` node shape (its `FlowNode` variant). */
+interface HumanNode {
+  kind: "human";
+  name: string;
+  form: string;
+  assignee?: string;
+  candidateGroups?: string;
+  io?: HumanIoMapping;
+}
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    human: HumanNode;
+  }
+}
+
+declare module "../declarative.js" {
+  interface FlowBuilder<C extends object> {
+    /**
+     * A human-in-the-loop approval step (a BPMN `<bpmn:userTask>` with the Zeebe
+     * user-task marker). `opts.form` binds a `zeebe:formDefinition`; the optional
+     * `assignee` / `candidateGroups` populate a `zeebe:assignmentDefinition`
+     * (either or both), and `io` populates a `zeebe:ioMapping`. Resume it from a
+     * task list / the Zeebe user-task API; the token waits durably until the task
+     * is completed.
+     */
+    human<K extends string>(name: K, opts: HumanOptions): FlowBuilder<C>;
+  }
+}
+
+/** A present, non-empty, non-whitespace-only string — the shape every human()
+ *  id / assignment / mapping-expression field must have. A blank value would
+ *  emit a meaningless BPMN attribute (an empty formId, assignee, candidateGroups,
+ *  or ioMapping source/target) that fails or misbehaves at deploy/run time, so we
+ *  fail fast at build. Non-blank values are kept verbatim — FEEL expressions are
+ *  never trimmed or normalized. */
+function isNonBlankString(v: unknown): v is string {
+  return typeof v === "string" && v.trim() !== "";
+}
+
+function isEntry(e: unknown): e is HumanIoEntry {
+  if (e === null || typeof e !== "object") return false;
+  if (!("source" in e) || !("target" in e)) return false;
+  const { source, target } = e;
+  return isNonBlankString(source) && isNonBlankString(target);
+}
+
+function validateEntries(name: string, dir: "input" | "output", entries: HumanIoEntry[] | undefined): void {
+  if (entries === undefined) return;
+  if (!Array.isArray(entries)) throw new Error(`human("${name}") io.${dir} must be an array of { source, target }`);
+  for (const e of entries) {
+    if (!isEntry(e)) throw new Error(`human("${name}") io.${dir} entries must be { source: non-empty string, target: non-empty string }`);
+  }
+}
+
+function renderAssignment(node: HumanNode): string {
+  if (node.assignee === undefined && node.candidateGroups === undefined) return "";
+  const attrs = [
+    node.assignee !== undefined ? ` assignee="${escapeXml(node.assignee)}"` : "",
+    node.candidateGroups !== undefined ? ` candidateGroups="${escapeXml(node.candidateGroups)}"` : "",
+  ].join("");
+  return `        <zeebe:assignmentDefinition${attrs} />\n`;
+}
+
+function renderMappings(entries: HumanIoEntry[] | undefined, tag: "input" | "output"): string {
+  if (!entries || entries.length === 0) return "";
+  return entries
+    .map((e) => `          <zeebe:${tag} source="${escapeXml(e.source)}" target="${escapeXml(e.target)}" />\n`)
+    .join("");
+}
+
+function renderIoMapping(node: HumanNode): string {
+  const io = node.io;
+  if (!io || ((io.input?.length ?? 0) === 0 && (io.output?.length ?? 0) === 0)) return "";
+  return (
+    `        <zeebe:ioMapping>\n` +
+    renderMappings(io.input, "input") +
+    renderMappings(io.output, "output") +
+    `        </zeebe:ioMapping>\n`
+  );
+}
+
+function renderUserTask(node: HumanNode, inc: string[], outg: string[]): string {
+  const id = node.name;
+  const ext =
+    `      <bpmn:extensionElements>\n` +
+    `        <zeebe:formDefinition formId="${escapeXml(node.form)}" />\n` +
+    `        <zeebe:userTask />\n` +
+    renderAssignment(node) +
+    renderIoMapping(node) +
+    `      </bpmn:extensionElements>`;
+  return (
+    `    <bpmn:userTask id="${escapeXml(id)}" name="${escapeXml(id)}">\n` +
+    ext +
+    "\n" +
+    incomingOutgoing(inc, outg) +
+    `    </bpmn:userTask>`
+  );
+}
+
+registerNodeKind("human", {
+  build: (api) => (name: string, opts: HumanOptions) => {
+    api.claim(name);
+    if (opts === null || typeof opts !== "object") {
+      throw new Error(`human("${name}") needs an options object { form, … }`);
+    }
+    if (!isNonBlankString(opts.form)) {
+      throw new Error(`human("${name}") needs a non-empty { form } (the zeebe:formDefinition form id)`);
+    }
+    if (opts.assignee !== undefined && !isNonBlankString(opts.assignee)) {
+      throw new Error(`human("${name}") { assignee } must be a non-empty string`);
+    }
+    if (opts.candidateGroups !== undefined && !isNonBlankString(opts.candidateGroups)) {
+      throw new Error(`human("${name}") { candidateGroups } must be a non-empty string`);
+    }
+    if (opts.io !== undefined && (opts.io === null || typeof opts.io !== "object" || Array.isArray(opts.io))) {
+      throw new Error(`human("${name}") { io } must be an object { input?, output? }`);
+    }
+    validateEntries(name, "input", opts.io?.input);
+    validateEntries(name, "output", opts.io?.output);
+    api.out.push({
+      kind: "human",
+      name,
+      form: opts.form,
+      assignee: opts.assignee,
+      candidateGroups: opts.candidateGroups,
+      io: opts.io,
+    });
+    return api.self();
+  },
+  emit: (node, incoming, _loop, api) => {
+    api.addNode({ id: node.name, render: (inc, outg) => renderUserTask(node, inc, outg) });
+    api.connect(incoming, node.name);
+    return [api.newEdge(node.name)];
+  },
+});

package/src/nodes/index.ts

@@ -6,10 +6,12 @@
 // 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 "./human.js";
 import "./loop.js";
 import "./parallel.js";
 import "./race.js";