@nanobpm/workflow 0.11.0 → 0.13.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
@@ -88,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:
 
@@ -206,6 +236,46 @@ Only `resourceId` is required; omit `append` and no `ioMapping` is emitted. A
 `w.task` **without** a `prompt` is unchanged — it emits no `linkedResources`.
 Data envelopes (via contracts) still lift alongside the prompt binding.
 
+#### Service-task I/O mappings (`w.task`/`w.run` with `{ io }`)
+
+Any service task — external (`w.task`) or locally-hosted (`w.run`) — can carry a
+general `<zeebe:ioMapping>` of arbitrary **input** (applied on activation) and
+**output** (applied on completion) variable mappings via an optional `io`. It
+reuses the same `{ input?, output? }` shape as `w.human`'s `io` (a single
+`HumanIoMapping` / `HumanIoEntry`, no parallel type):
+
+```ts
+w.task("record-conformance-ack", {
+  jobType: "pr.conformance-ack",
+  io: {
+    input: [
+      { source: "=planKey", target: "planKey" },
+      { source: "=if (is defined(note)) then note else null", target: "note" },
+    ],
+  },
+});
+```
+
+derives:
+
+```xml
+<bpmn:serviceTask id="record-conformance-ack" name="record-conformance-ack">
+  <bpmn:extensionElements>
+    <zeebe:taskDefinition type="pr.conformance-ack" />
+    <zeebe:ioMapping>
+      <zeebe:input source="=planKey" target="planKey" />
+      <zeebe:input source="=if (is defined(note)) then note else null" target="note" />
+    </zeebe:ioMapping>
+  </bpmn:extensionElements>
+</bpmn:serviceTask>
+```
+
+The `ioMapping` is emitted after `taskDefinition` (and after `linkedResources` /
+envelope `properties` when present). When a task has **both** a `prompt.append`
+and an explicit `io.input`, they merge into a **single** `<zeebe:ioMapping>` (the
+`appendPrompt` input trails the explicit inputs) — never two. Omit `io` (or pass
+an empty `{}`) and no `ioMapping` is emitted.
+
 ### Imperative (Temporal-style, engine-replayed) — experimental/internal
 
 Write the orchestration as a function. `ctx.run(name, fn)` is a durable step: its

package/dist/declarative.d.ts

@@ -1,5 +1,6 @@
 import type { DeclarativeFlow, FlowContracts, FlowNode, JsonObject, NodeEnvelopes, StepHandler, TimerStart } from "./types.js";
 import type { Envelope } from "./envelope.js";
+import type { HumanIoMapping } from "./io-mapping.js";
 import "./nodes/index.js";
 /** The TS payload type of a contract's input envelope (untyped fallback). */
 export type InPayload<Ct> = Ct extends {
@@ -42,7 +43,9 @@ export interface FlowBuilder<C extends object = object> {
      * the flow's contracts, the handler's job variables and return value are typed
      * from that contract's `in`/`out` envelopes; otherwise they are `JsonObject`.
      */
-    run<K extends string>(name: K, handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>): FlowBuilder<C>;
+    run<K extends string>(name: K, handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>, opts?: {
+        io?: HumanIoMapping;
+    }): FlowBuilder<C>;
     /**
      * A durable activity served by a worker OUTSIDE this program (a BPMN service
      * task, but no locally-hosted handler). Its job type defaults to the derived
@@ -57,6 +60,7 @@ export interface FlowBuilder<C extends object = object> {
      */
     task<K extends string>(name: K, opts?: {
         jobType?: string;
+        io?: HumanIoMapping;
     }): FlowBuilder<C>;
     /**
      * A durable wait for an external/human event, correlated on a process

package/dist/index.d.ts

@@ -3,6 +3,7 @@ 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/io-mapping.d.ts

@@ -0,0 +1,32 @@
+/** 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;
+}
+/** A `<zeebe:ioMapping>`: input mappings applied on activation and output
+ *  mappings applied on completion. */
+export interface HumanIoMapping {
+    input?: HumanIoEntry[];
+    output?: HumanIoEntry[];
+}
+/** A present, non-empty, non-whitespace-only string — the shape every id /
+ *  assignment / mapping-expression field must have. A blank value would emit a
+ *  meaningless BPMN attribute (an empty ioMapping source/target, formId,
+ *  assignee, …) 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. */
+export declare function isNonBlankString(v: unknown): v is string;
+/** Validate an optional io mapping at authoring time. `label` is the node's
+ *  self-description (e.g. `human("decide")` or `task("record")`) so the thrown
+ *  message names the offending step. An `undefined` mapping is allowed (no
+ *  ioMapping is emitted); a non-object / array value, or a malformed entry, fails
+ *  fast. */
+export declare function assertIoMapping(label: string, io: HumanIoMapping | undefined): void;
+/** Emit a single `<zeebe:ioMapping>` (inputs then outputs) for the mapping, or
+ *  the empty string when it has no entries. The 8-space element / 10-space entry
+ *  indentation matches both the user-task and service-task emission, so a caller
+ *  can splice the result straight into either `<bpmn:extensionElements>`. */
+export declare function renderIoMapping(io: HumanIoMapping | undefined): string;

package/dist/io-mapping.js

@@ -0,0 +1,67 @@
+// The single source of truth for a Zeebe `<zeebe:ioMapping>` — its shape, its
+// authoring-time validation, and its BPMN emission — shared by EVERY node kind
+// that carries variable mappings (`human` user tasks, `task`/`run` service
+// tasks). Derivation over duplication (AGENTS.md): one interface, one validator,
+// one renderer, so the ioMapping surface can never drift between node kinds.
+import { escapeXml } from "./xml.js";
+/** A present, non-empty, non-whitespace-only string — the shape every id /
+ *  assignment / mapping-expression field must have. A blank value would emit a
+ *  meaningless BPMN attribute (an empty ioMapping source/target, formId,
+ *  assignee, …) 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. */
+export 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(label, dir, entries) {
+    if (entries === undefined)
+        return;
+    if (!Array.isArray(entries))
+        throw new Error(`${label} io.${dir} must be an array of { source, target }`);
+    for (const e of entries) {
+        if (!isEntry(e)) {
+            throw new Error(`${label} io.${dir} entries must be { source: non-empty string, target: non-empty string }`);
+        }
+    }
+}
+/** Validate an optional io mapping at authoring time. `label` is the node's
+ *  self-description (e.g. `human("decide")` or `task("record")`) so the thrown
+ *  message names the offending step. An `undefined` mapping is allowed (no
+ *  ioMapping is emitted); a non-object / array value, or a malformed entry, fails
+ *  fast. */
+export function assertIoMapping(label, io) {
+    if (io === undefined)
+        return;
+    if (io === null || typeof io !== "object" || Array.isArray(io)) {
+        throw new Error(`${label} { io } must be an object { input?, output? }`);
+    }
+    validateEntries(label, "input", io.input);
+    validateEntries(label, "output", io.output);
+}
+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("");
+}
+/** Emit a single `<zeebe:ioMapping>` (inputs then outputs) for the mapping, or
+ *  the empty string when it has no entries. The 8-space element / 10-space entry
+ *  indentation matches both the user-task and service-task emission, so a caller
+ *  can splice the result straight into either `<bpmn:extensionElements>`. */
+export function renderIoMapping(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`);
+}

package/dist/nodes/human.d.ts

@@ -0,0 +1,44 @@
+import type { HumanIoMapping } from "../io-mapping.js";
+export type { HumanIoEntry, HumanIoMapping } from "../io-mapping.js";
+/** 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>;
+    }
+}

package/dist/nodes/human.js

@@ -0,0 +1,70 @@
+// 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 { assertIoMapping, isNonBlankString, renderIoMapping } from "../io-mapping.js";
+import { registerNodeKind } from "./registry.js";
+/** A present, non-empty, non-whitespace-only string — the shape every human()
+ *  id / assignment field must have. A blank value would emit a meaningless BPMN
+ *  attribute (an empty formId, assignee, or candidateGroups) that fails or
+ *  misbehaves at deploy/run time, so we fail fast at build. Shared with the
+ *  ioMapping validator via `io-mapping`. */
+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 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.io) +
+        `      </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`);
+        }
+        assertIoMapping(`human("${name}")`, opts.io);
+        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

@@ -3,6 +3,7 @@ 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

@@ -10,6 +10,7 @@ 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/run.d.ts

@@ -1,10 +1,11 @@
+import type { HumanIoMapping } from "../io-mapping.js";
 declare module "../types.js" {
     interface FlowNodeRegistry {
         run: {
             kind: "run";
             name: string;
             envelopes?: NodeEnvelopes;
+            io?: HumanIoMapping;
         };
     }
 }
-export {};

package/dist/nodes/run.js

@@ -3,18 +3,20 @@
 // 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 { assertIoMapping, renderIoMapping } from "../io-mapping.js";
 import { registerNodeKind } from "./registry.js";
 registerNodeKind("run", {
-    build: (api) => (name, handler) => {
+    build: (api) => (name, handler, opts) => {
         api.claim(name);
         if (typeof handler !== "function")
             throw new Error(`run("${name}") needs a handler function`);
+        assertIoMapping(`run("${name}")`, opts?.io);
         api.handlers[name] = handler;
-        api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name) });
+        api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name), io: opts?.io });
         return api.self();
     },
     emit: (node, incoming, _loop, api) => {
-        api.addServiceTask(node);
+        api.addServiceTask(node, node.io !== undefined ? { extraExt: renderIoMapping(node.io) } : {});
         api.connect(incoming, node.name);
         return [api.newEdge(node.name)];
     },

package/dist/nodes/task.d.ts

@@ -1,3 +1,4 @@
+import type { HumanIoMapping } from "../io-mapping.js";
 /** Binds an LLM prompt resource to an agent service task. Emits, alongside the
  *  task's `zeebe:taskDefinition` capability token, a
  *  `<zeebe:linkedResources><zeebe:linkedResource resourceId=… bindingType=…
@@ -26,6 +27,11 @@ declare module "../types.js" {
             jobType?: string;
             /** The agent prompt binding, when the task is an LLM-agent service task. */
             prompt?: PromptBinding;
+            /** An explicit `<zeebe:ioMapping>` on the service task — arbitrary input
+             *  (and output) variable mappings, using the shared ioMapping shape. When a
+             *  `prompt.append` is ALSO present it is folded into this single mapping as
+             *  an extra `appendPrompt` input (no duplicate `ioMapping` element). */
+            io?: HumanIoMapping;
         };
     }
 }
@@ -37,11 +43,13 @@ declare module "../declarative.js" {
          * (`resourceType="GenericScript" linkName="prompt"`). Pair it with a
          * `{ jobType }` capability token (e.g. `senior:retro`) so an agent pool
          * services it. `prompt.append` (optional) feeds a FEEL expression to the
-         * worker through a `zeebe:ioMapping` `appendPrompt` input.
+         * worker through a `zeebe:ioMapping` `appendPrompt` input. `io` (optional)
+         * adds arbitrary input/output variable mappings to the SAME `zeebe:ioMapping`.
          */
         task<K extends string>(name: K, opts: {
             jobType?: string;
             prompt: PromptBinding;
+            io?: HumanIoMapping;
         }): FlowBuilder<C>;
     }
 }

package/dist/nodes/task.js

@@ -11,6 +11,7 @@
 // its option type — WITHOUT re-opening the shared `FlowNode` union, the central
 // `walkNodes`/`emitNode` dispatch, or the generated barrel.
 import { assertJobType, escapeXml } from "../xml.js";
+import { assertIoMapping, renderIoMapping } from "../io-mapping.js";
 import { registerNodeKind } from "./registry.js";
 /** Normalize + validate a prompt binding at authoring time, applying the
  *  `bindingType` default. Emitted string fields are trimmed before storing (in
@@ -42,24 +43,37 @@ function resolvePrompt(name, prompt) {
     }
     return resolved;
 }
-/** Build the prompt-specific `<bpmn:extensionElements>` delta appended to the
- *  shared service-task emission: the `zeebe:linkedResources` prompt binding and
- *  (optionally) a `zeebe:ioMapping` `appendPrompt` input. The task shell
+/** Build the `<bpmn:extensionElements>` delta appended to the shared
+ *  service-task emission: the optional `zeebe:linkedResources` prompt binding
+ *  followed by a single, correctly-ordered `zeebe:ioMapping`. The task shell
  *  (taskDefinition + envelope properties) is rendered by the built-in
  *  `EmitApi.addServiceTask`, so this variant only contributes its delta and the
- *  envelope serialization can never drift from the plain service task. */
-function promptExtensions(prompt) {
-    const { resourceId, bindingType, append } = prompt;
-    const linked = `        <zeebe:linkedResources>\n` +
-        `          <zeebe:linkedResource resourceId="${escapeXml(resourceId)}" ` +
-        `bindingType="${escapeXml(bindingType ?? "latest")}" resourceType="GenericScript" linkName="prompt" />\n` +
-        `        </zeebe:linkedResources>\n`;
-    const io = append !== undefined
-        ? `        <zeebe:ioMapping>\n` +
-            `          <zeebe:input source="${escapeXml(append)}" target="appendPrompt" />\n` +
-            `        </zeebe:ioMapping>\n`
+ *  envelope serialization can never drift from the plain service task.
+ *
+ *  The `ioMapping` is the SINGLE source for all variable mappings on the task:
+ *  the explicit `io.input`/`io.output` plus — when `prompt.append` is present —
+ *  the `appendPrompt` input, folded in as one more input entry so a task with
+ *  both a `prompt.append` and an explicit `io.input` emits exactly one
+ *  `<zeebe:ioMapping>` (never two). Element order matches the golden:
+ *  `linkedResources` (when any) then `ioMapping` (when any), the latter after
+ *  `taskDefinition`/`properties`. */
+function taskExtensions(prompt, io) {
+    const linked = prompt !== undefined
+        ? `        <zeebe:linkedResources>\n` +
+            `          <zeebe:linkedResource resourceId="${escapeXml(prompt.resourceId)}" ` +
+            `bindingType="${escapeXml(prompt.bindingType ?? "latest")}" resourceType="GenericScript" linkName="prompt" />\n` +
+            `        </zeebe:linkedResources>\n`
         : "";
-    return linked + io;
+    // Merge the explicit io mapping and the prompt's `appendPrompt` input into one
+    // mapping. The append input trails the explicit inputs — it appends runtime
+    // context to the bound prompt, so it reads naturally after the task's own
+    // inputs — and outputs follow, matching `renderIoMapping`'s input-then-output
+    // ordering.
+    const inputs = [...(io?.input ?? [])];
+    if (prompt?.append !== undefined)
+        inputs.push({ source: prompt.append, target: "appendPrompt" });
+    const merged = { input: inputs, output: io?.output ?? [] };
+    return linked + renderIoMapping(merged);
 }
 registerNodeKind("task", {
     build: (api) => (name, opts) => {
@@ -68,29 +82,32 @@ registerNodeKind("task", {
         if (override !== undefined)
             assertJobType("task jobType", override);
         const prompt = opts?.prompt !== undefined ? resolvePrompt(name, opts.prompt) : undefined;
+        assertIoMapping(`task("${name}")`, opts?.io);
         api.out.push({
             kind: "task",
             name,
             envelopes: api.contractEnvelopes(name),
             jobType: override,
             prompt,
+            io: opts?.io,
         });
         return api.self();
     },
     emit: (node, incoming, _loop, api) => {
-        // No prompt → the standard service-task emission is preserved unchanged (no
-        // `linkedResources` are emitted).
-        if (node.prompt === undefined) {
+        // Neither a prompt binding nor an explicit io mapping → the standard
+        // service-task emission is preserved unchanged (no `linkedResources`, no
+        // `ioMapping`).
+        if (node.prompt === undefined && node.io === undefined) {
             api.addServiceTask(node);
             api.connect(incoming, node.name);
             return [api.newEdge(node.name)];
         }
-        // Prompt binding present → the shared `addServiceTask` renders the task
-        // shell (taskDefinition + envelope properties, recording envelopes); we only
-        // supply the `zeebe:linkedResource` (and optional `appendPrompt` ioMapping)
-        // delta, so the envelope/taskDefinition serialization has a single source.
-        const prompt = node.prompt;
-        api.addServiceTask(node, { extraExt: promptExtensions(prompt) });
+        // A prompt binding and/or an explicit io mapping present → the shared
+        // `addServiceTask` renders the task shell (taskDefinition + envelope
+        // properties, recording envelopes); we only supply the `linkedResource`
+        // and/or `ioMapping` delta, so the envelope/taskDefinition serialization has
+        // a single source.
+        api.addServiceTask(node, { extraExt: taskExtensions(node.prompt, node.io) });
         api.connect(incoming, node.name);
         return [api.newEdge(node.name)];
     },

package/package.json

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

@@ -48,6 +48,7 @@ import type {
   TimerStart,
 } from "./types.js";
 import type { Envelope, EnvelopeField } from "./envelope.js";
+import type { HumanIoMapping } from "./io-mapping.js";
 import { assertIdent, assertTimerCycle, assertTimerDate, assertTimerDuration, escapeXml, jobType, messageName } from "./xml.js";
 import { eachNodeKind, requireNodeKind } from "./nodes/registry.js";
 // Import the generated barrel purely for its registration side effects: every
@@ -98,7 +99,11 @@ export interface FlowBuilder<C extends object = object> {
    * the flow's contracts, the handler's job variables and return value are typed
    * from that contract's `in`/`out` envelopes; otherwise they are `JsonObject`.
    */
-  run<K extends string>(name: K, handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>): FlowBuilder<C>;
+  run<K extends string>(
+    name: K,
+    handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>,
+    opts?: { io?: HumanIoMapping },
+  ): FlowBuilder<C>;
   /**
    * A durable activity served by a worker OUTSIDE this program (a BPMN service
    * task, but no locally-hosted handler). Its job type defaults to the derived
@@ -111,7 +116,7 @@ export interface FlowBuilder<C extends object = object> {
    * workers must poll. Its contract envelopes (if any) type the model, not a
    * local handler.
    */
-  task<K extends string>(name: K, opts?: { jobType?: string }): FlowBuilder<C>;
+  task<K extends string>(name: K, opts?: { jobType?: string; io?: HumanIoMapping }): FlowBuilder<C>;
   /**
    * A durable wait for an external/human event, correlated on a process
    * variable (a BPMN message intermediate catch event). Resume it with

package/src/index.ts

@@ -46,6 +46,7 @@ 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/io-mapping.ts

@@ -0,0 +1,85 @@
+// The single source of truth for a Zeebe `<zeebe:ioMapping>` — its shape, its
+// authoring-time validation, and its BPMN emission — shared by EVERY node kind
+// that carries variable mappings (`human` user tasks, `task`/`run` service
+// tasks). Derivation over duplication (AGENTS.md): one interface, one validator,
+// one renderer, so the ioMapping surface can never drift between node kinds.
+
+import { escapeXml } from "./xml.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;
+}
+
+/** A `<zeebe:ioMapping>`: input mappings applied on activation and output
+ *  mappings applied on completion. */
+export interface HumanIoMapping {
+  input?: HumanIoEntry[];
+  output?: HumanIoEntry[];
+}
+
+/** A present, non-empty, non-whitespace-only string — the shape every id /
+ *  assignment / mapping-expression field must have. A blank value would emit a
+ *  meaningless BPMN attribute (an empty ioMapping source/target, formId,
+ *  assignee, …) 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. */
+export 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(label: string, dir: "input" | "output", entries: HumanIoEntry[] | undefined): void {
+  if (entries === undefined) return;
+  if (!Array.isArray(entries)) throw new Error(`${label} io.${dir} must be an array of { source, target }`);
+  for (const e of entries) {
+    if (!isEntry(e)) {
+      throw new Error(`${label} io.${dir} entries must be { source: non-empty string, target: non-empty string }`);
+    }
+  }
+}
+
+/** Validate an optional io mapping at authoring time. `label` is the node's
+ *  self-description (e.g. `human("decide")` or `task("record")`) so the thrown
+ *  message names the offending step. An `undefined` mapping is allowed (no
+ *  ioMapping is emitted); a non-object / array value, or a malformed entry, fails
+ *  fast. */
+export function assertIoMapping(label: string, io: HumanIoMapping | undefined): void {
+  if (io === undefined) return;
+  if (io === null || typeof io !== "object" || Array.isArray(io)) {
+    throw new Error(`${label} { io } must be an object { input?, output? }`);
+  }
+  validateEntries(label, "input", io.input);
+  validateEntries(label, "output", io.output);
+}
+
+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("");
+}
+
+/** Emit a single `<zeebe:ioMapping>` (inputs then outputs) for the mapping, or
+ *  the empty string when it has no entries. The 8-space element / 10-space entry
+ *  indentation matches both the user-task and service-task emission, so a caller
+ *  can splice the result straight into either `<bpmn:extensionElements>`. */
+export function renderIoMapping(io: HumanIoMapping | undefined): string {
+  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`
+  );
+}

package/src/nodes/human.ts

@@ -0,0 +1,129 @@
+// 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 { assertIoMapping, isNonBlankString, renderIoMapping } from "../io-mapping.js";
+import type { HumanIoMapping } from "../io-mapping.js";
+import { registerNodeKind } from "./registry.js";
+
+// The ioMapping shape lives in the shared `io-mapping` module (single source of
+// truth across node kinds); re-export it so existing `@nanobpm/workflow`
+// consumers keep importing `HumanIoMapping` / `HumanIoEntry` unchanged.
+export type { HumanIoEntry, HumanIoMapping } from "../io-mapping.js";
+
+/** 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 field must have. A blank value would emit a meaningless BPMN
+ *  attribute (an empty formId, assignee, or candidateGroups) that fails or
+ *  misbehaves at deploy/run time, so we fail fast at build. Shared with the
+ *  ioMapping validator via `io-mapping`. */
+
+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 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.io) +
+    `      </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`);
+    }
+    assertIoMapping(`human("${name}")`, opts.io);
+    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

@@ -11,6 +11,7 @@ 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/src/nodes/run.ts

@@ -5,24 +5,27 @@
 // handlers — with NO edit to the shared union or a central dispatch switch.
 
 import type { NodeEnvelopes, StepHandler } from "../types.js";
+import { assertIoMapping, renderIoMapping } from "../io-mapping.js";
+import type { HumanIoMapping } from "../io-mapping.js";
 import { registerNodeKind } from "./registry.js";
 
 declare module "../types.js" {
   interface FlowNodeRegistry {
-    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes };
+    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes; io?: HumanIoMapping };
   }
 }
 
 registerNodeKind("run", {
-  build: (api) => (name: string, handler: StepHandler) => {
+  build: (api) => (name: string, handler: StepHandler, opts?: { io?: HumanIoMapping }) => {
     api.claim(name);
     if (typeof handler !== "function") throw new Error(`run("${name}") needs a handler function`);
+    assertIoMapping(`run("${name}")`, opts?.io);
     api.handlers[name] = handler;
-    api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name) });
+    api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name), io: opts?.io });
     return api.self();
   },
   emit: (node, incoming, _loop, api) => {
-    api.addServiceTask(node);
+    api.addServiceTask(node, node.io !== undefined ? { extraExt: renderIoMapping(node.io) } : {});
     api.connect(incoming, node.name);
     return [api.newEdge(node.name)];
   },

package/src/nodes/task.ts

@@ -13,6 +13,8 @@
 
 import type { NodeEnvelopes } from "../types.js";
 import { assertJobType, escapeXml } from "../xml.js";
+import { assertIoMapping, renderIoMapping } from "../io-mapping.js";
+import type { HumanIoEntry, HumanIoMapping } from "../io-mapping.js";
 import { registerNodeKind } from "./registry.js";
 
 /** Binds an LLM prompt resource to an agent service task. Emits, alongside the
@@ -44,6 +46,11 @@ declare module "../types.js" {
       jobType?: string;
       /** The agent prompt binding, when the task is an LLM-agent service task. */
       prompt?: PromptBinding;
+      /** An explicit `<zeebe:ioMapping>` on the service task — arbitrary input
+       *  (and output) variable mappings, using the shared ioMapping shape. When a
+       *  `prompt.append` is ALSO present it is folded into this single mapping as
+       *  an extra `appendPrompt` input (no duplicate `ioMapping` element). */
+      io?: HumanIoMapping;
     };
   }
 }
@@ -56,9 +63,13 @@ declare module "../declarative.js" {
      * (`resourceType="GenericScript" linkName="prompt"`). Pair it with a
      * `{ jobType }` capability token (e.g. `senior:retro`) so an agent pool
      * services it. `prompt.append` (optional) feeds a FEEL expression to the
-     * worker through a `zeebe:ioMapping` `appendPrompt` input.
+     * worker through a `zeebe:ioMapping` `appendPrompt` input. `io` (optional)
+     * adds arbitrary input/output variable mappings to the SAME `zeebe:ioMapping`.
      */
-    task<K extends string>(name: K, opts: { jobType?: string; prompt: PromptBinding }): FlowBuilder<C>;
+    task<K extends string>(
+      name: K,
+      opts: { jobType?: string; prompt: PromptBinding; io?: HumanIoMapping },
+    ): FlowBuilder<C>;
   }
 }
 
@@ -93,57 +104,71 @@ function resolvePrompt(name: string, prompt: PromptBinding): PromptBinding {
   return resolved;
 }
 
-/** Build the prompt-specific `<bpmn:extensionElements>` delta appended to the
- *  shared service-task emission: the `zeebe:linkedResources` prompt binding and
- *  (optionally) a `zeebe:ioMapping` `appendPrompt` input. The task shell
+/** Build the `<bpmn:extensionElements>` delta appended to the shared
+ *  service-task emission: the optional `zeebe:linkedResources` prompt binding
+ *  followed by a single, correctly-ordered `zeebe:ioMapping`. The task shell
  *  (taskDefinition + envelope properties) is rendered by the built-in
  *  `EmitApi.addServiceTask`, so this variant only contributes its delta and the
- *  envelope serialization can never drift from the plain service task. */
-function promptExtensions(prompt: PromptBinding): string {
-  const { resourceId, bindingType, append } = prompt;
+ *  envelope serialization can never drift from the plain service task.
+ *
+ *  The `ioMapping` is the SINGLE source for all variable mappings on the task:
+ *  the explicit `io.input`/`io.output` plus — when `prompt.append` is present —
+ *  the `appendPrompt` input, folded in as one more input entry so a task with
+ *  both a `prompt.append` and an explicit `io.input` emits exactly one
+ *  `<zeebe:ioMapping>` (never two). Element order matches the golden:
+ *  `linkedResources` (when any) then `ioMapping` (when any), the latter after
+ *  `taskDefinition`/`properties`. */
+function taskExtensions(prompt: PromptBinding | undefined, io: HumanIoMapping | undefined): string {
   const linked =
-    `        <zeebe:linkedResources>\n` +
-    `          <zeebe:linkedResource resourceId="${escapeXml(resourceId)}" ` +
-    `bindingType="${escapeXml(bindingType ?? "latest")}" resourceType="GenericScript" linkName="prompt" />\n` +
-    `        </zeebe:linkedResources>\n`;
-  const io =
-    append !== undefined
-      ? `        <zeebe:ioMapping>\n` +
-        `          <zeebe:input source="${escapeXml(append)}" target="appendPrompt" />\n` +
-        `        </zeebe:ioMapping>\n`
+    prompt !== undefined
+      ? `        <zeebe:linkedResources>\n` +
+        `          <zeebe:linkedResource resourceId="${escapeXml(prompt.resourceId)}" ` +
+        `bindingType="${escapeXml(prompt.bindingType ?? "latest")}" resourceType="GenericScript" linkName="prompt" />\n` +
+        `        </zeebe:linkedResources>\n`
       : "";
-  return linked + io;
+  // Merge the explicit io mapping and the prompt's `appendPrompt` input into one
+  // mapping. The append input trails the explicit inputs — it appends runtime
+  // context to the bound prompt, so it reads naturally after the task's own
+  // inputs — and outputs follow, matching `renderIoMapping`'s input-then-output
+  // ordering.
+  const inputs: HumanIoEntry[] = [...(io?.input ?? [])];
+  if (prompt?.append !== undefined) inputs.push({ source: prompt.append, target: "appendPrompt" });
+  const merged: HumanIoMapping = { input: inputs, output: io?.output ?? [] };
+  return linked + renderIoMapping(merged);
 }
 
 registerNodeKind("task", {
-  build: (api) => (name: string, opts?: { jobType?: string; prompt?: PromptBinding }) => {
+  build: (api) => (name: string, opts?: { jobType?: string; prompt?: PromptBinding; io?: HumanIoMapping }) => {
     api.claim(name);
     const override = opts?.jobType;
     if (override !== undefined) assertJobType("task jobType", override);
     const prompt = opts?.prompt !== undefined ? resolvePrompt(name, opts.prompt) : undefined;
+    assertIoMapping(`task("${name}")`, opts?.io);
     api.out.push({
       kind: "task",
       name,
       envelopes: api.contractEnvelopes(name),
       jobType: override,
       prompt,
+      io: opts?.io,
     });
     return api.self();
   },
   emit: (node, incoming, _loop, api) => {
-    // No prompt → the standard service-task emission is preserved unchanged (no
-    // `linkedResources` are emitted).
-    if (node.prompt === undefined) {
+    // Neither a prompt binding nor an explicit io mapping → the standard
+    // service-task emission is preserved unchanged (no `linkedResources`, no
+    // `ioMapping`).
+    if (node.prompt === undefined && node.io === undefined) {
       api.addServiceTask(node);
       api.connect(incoming, node.name);
       return [api.newEdge(node.name)];
     }
-    // Prompt binding present → the shared `addServiceTask` renders the task
-    // shell (taskDefinition + envelope properties, recording envelopes); we only
-    // supply the `zeebe:linkedResource` (and optional `appendPrompt` ioMapping)
-    // delta, so the envelope/taskDefinition serialization has a single source.
-    const prompt = node.prompt;
-    api.addServiceTask(node, { extraExt: promptExtensions(prompt) });
+    // A prompt binding and/or an explicit io mapping present → the shared
+    // `addServiceTask` renders the task shell (taskDefinition + envelope
+    // properties, recording envelopes); we only supply the `linkedResource`
+    // and/or `ioMapping` delta, so the envelope/taskDefinition serialization has
+    // a single source.
+    api.addServiceTask(node, { extraExt: taskExtensions(node.prompt, node.io) });
     api.connect(incoming, node.name);
     return [api.newEdge(node.name)];
   },