@nanobpm/workflow 0.12.0 → 0.13.1

package/README.md

@@ -236,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/client.d.ts

@@ -66,6 +66,37 @@ export interface NanoJobWorker {
         waitUpToMs?: number;
     }): Promise<void>;
 }
+/** The subset of a raw `@nanobpm/nano-sdk` job worker the adapter drives. Its
+ *  `start()` may be synchronous or async: on nano-sdk >=1.2.5's Falcon/auto path
+ *  it is async and the SDK self-starts the worker after an asynchronous transport
+ *  bind (see {@link adaptJobWorker}). */
+export interface RawNanoJobWorker {
+    start(): void | Promise<void>;
+    stop(): void | Promise<void>;
+    stopGracefully(opts?: {
+        waitUpToMs?: number;
+    }): Promise<unknown>;
+}
+/** Adapt a raw `@nanobpm/nano-sdk` job worker to the {@link NanoJobWorker} handle
+ *  the Worker runtime drives, making the eager `start()` NULL-SAFE.
+ *
+ *  nano-sdk >=1.2.5's Falcon/auto worker SELF-STARTS after an ASYNCHRONOUS
+ *  transport bind: `createJobWorker` hands back a worker whose transport is null
+ *  until Nano is detected, at which point the SDK `bindTransport(t)`s it and
+ *  `start()`s the worker ITSELF. Calling `start()` before that bind dereferences
+ *  the null transport and — because `start()` is async — surfaces as an UNHANDLED
+ *  REJECTION that crashes the process
+ *  (`TypeError: Cannot read properties of null (reading 'subscribe')`, #415). The
+ *  REST/manual worker, by contrast, never self-starts, so `start()` must still be
+ *  called here. We resolve the version-skew by starting eagerly but NULL-SAFELY:
+ *  swallow ONLY the pre-bind race (the SDK self-starts once the transport binds)
+ *  and SURFACE any other start failure via `console.warn` rather than masking it.
+ *  The SDK owns the start lifecycle end to end (it logs and falls back to REST on
+ *  its own subscribe failure), so discarding the resolved result — as the previous
+ *  `void worker.start()` already did — is safe. Pairs with the library-side
+ *  null-safe, idempotent start (jwulf/nano-sdk-js#12) so neither an eager nor a
+ *  duplicate start can crash. */
+export declare function adaptJobWorker(worker: RawNanoJobWorker): NanoJobWorker;
 /** An activated job as delivered to a nano-sdk job handler: the workflow `Job`
  *  fields plus the acknowledgement actions. */
 export type ActivatedJob = Job & {

package/dist/client.js

@@ -96,6 +96,71 @@ export async function toDeployableBpmn(wf, opts = {}) {
         return semantic;
     }
 }
+/** Adapt a raw `@nanobpm/nano-sdk` job worker to the {@link NanoJobWorker} handle
+ *  the Worker runtime drives, making the eager `start()` NULL-SAFE.
+ *
+ *  nano-sdk >=1.2.5's Falcon/auto worker SELF-STARTS after an ASYNCHRONOUS
+ *  transport bind: `createJobWorker` hands back a worker whose transport is null
+ *  until Nano is detected, at which point the SDK `bindTransport(t)`s it and
+ *  `start()`s the worker ITSELF. Calling `start()` before that bind dereferences
+ *  the null transport and — because `start()` is async — surfaces as an UNHANDLED
+ *  REJECTION that crashes the process
+ *  (`TypeError: Cannot read properties of null (reading 'subscribe')`, #415). The
+ *  REST/manual worker, by contrast, never self-starts, so `start()` must still be
+ *  called here. We resolve the version-skew by starting eagerly but NULL-SAFELY:
+ *  swallow ONLY the pre-bind race (the SDK self-starts once the transport binds)
+ *  and SURFACE any other start failure via `console.warn` rather than masking it.
+ *  The SDK owns the start lifecycle end to end (it logs and falls back to REST on
+ *  its own subscribe failure), so discarding the resolved result — as the previous
+ *  `void worker.start()` already did — is safe. Pairs with the library-side
+ *  null-safe, idempotent start (jwulf/nano-sdk-js#12) so neither an eager nor a
+ *  duplicate start can crash. */
+export function adaptJobWorker(worker) {
+    return {
+        start: () => {
+            try {
+                const started = worker.start();
+                if (isPromiseLike(started))
+                    started.then(undefined, handleStartError);
+            }
+            catch (e) {
+                handleStartError(e);
+            }
+        },
+        stop: () => worker.stop(),
+        stopGracefully: async (opts) => {
+            await worker.stopGracefully(opts);
+        },
+    };
+}
+function isPromiseLike(v) {
+    return isRecord(v) && typeof v.then === "function";
+}
+/** The SDK's pre-bind start race is a NULL/undefined-transport dereference the SDK
+ *  recovers from via its own self-start: a `TypeError` from reading the transport's
+ *  `subscribe` off a `null`/`undefined` transport
+ *  (`Cannot read properties of null (reading 'subscribe')`, #415). Match it NARROWLY
+ *  — the specific `subscribe` dereference signature, not any null/undefined deref —
+ *  so a genuine start failure on the REST/manual path (or an unrelated null-deref
+ *  bug during `start()`) is never mistaken for the race and silently masked. */
+function isPreBindStartRace(e) {
+    return (e instanceof TypeError &&
+        /Cannot read propert(?:y|ies) of (?:null|undefined) \(reading ['"]subscribe['"]\)/.test(e.message));
+}
+/** Handle an eager-start error NULL-SAFELY. Swallow ONLY the SDK's known pre-bind
+ *  transport race (it self-starts once its transport binds — see
+ *  {@link adaptJobWorker}); any OTHER error is a real start failure (e.g. on the
+ *  REST/manual path) and is SURFACED via `console.warn` so it is not silently
+ *  masked. Never rethrows — callers rely on this to keep an async `start()` from
+ *  escaping as an unhandled rejection that crashes the process. The SDK owns the
+ *  start lifecycle end to end (it logs and falls back to REST on its own subscribe
+ *  failure), so we surface-and-continue rather than propagate. */
+function handleStartError(e) {
+    if (isPreBindStartRace(e))
+        return;
+    console.warn("[@nanobpm/workflow] job worker start() failed (not the known pre-bind transport " +
+        "race); the SDK owns start and REST fallback, so this is surfaced but not rethrown:", e);
+}
 export class WorkflowError extends Error {
     status;
     body;
@@ -153,15 +218,7 @@ export class WorkflowClient {
                         return JobActionReceiptSymbol;
                     },
                 });
-                return {
-                    start: () => {
-                        void worker.start();
-                    },
-                    stop: () => worker.stop(),
-                    stopGracefully: async (opts) => {
-                        await worker.stopGracefully(opts);
-                    },
-                };
+                return adaptJobWorker(worker);
             },
         };
     }

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/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

@@ -1,17 +1,5 @@
-/** 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[];
-}
+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`. */
@@ -54,4 +42,3 @@ declare module "../declarative.js" {
         human<K extends string>(name: K, opts: HumanOptions): FlowBuilder<C>;
     }
 }
-export {};

package/dist/nodes/human.js

@@ -6,34 +6,13 @@
 // 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 / 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 }`);
-    }
-}
+ *  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 "";
@@ -43,29 +22,13 @@ function renderAssignment(node) {
     ].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) +
+        renderIoMapping(node.io) +
         `      </bpmn:extensionElements>`;
     return (`    <bpmn:userTask id="${escapeXml(id)}" name="${escapeXml(id)}">\n` +
         ext +
@@ -88,11 +51,7 @@ registerNodeKind("human", {
         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);
+        assertIoMapping(`human("${name}")`, opts.io);
         api.out.push({
             kind: "human",
             name,

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.12.0",
+  "version": "0.13.1",
   "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/client.ts

@@ -154,6 +154,87 @@ export interface NanoJobWorker {
   stopGracefully?(opts?: { waitUpToMs?: number }): Promise<void>;
 }
 
+/** The subset of a raw `@nanobpm/nano-sdk` job worker the adapter drives. Its
+ *  `start()` may be synchronous or async: on nano-sdk >=1.2.5's Falcon/auto path
+ *  it is async and the SDK self-starts the worker after an asynchronous transport
+ *  bind (see {@link adaptJobWorker}). */
+export interface RawNanoJobWorker {
+  start(): void | Promise<void>;
+  stop(): void | Promise<void>;
+  stopGracefully(opts?: { waitUpToMs?: number }): Promise<unknown>;
+}
+
+/** Adapt a raw `@nanobpm/nano-sdk` job worker to the {@link NanoJobWorker} handle
+ *  the Worker runtime drives, making the eager `start()` NULL-SAFE.
+ *
+ *  nano-sdk >=1.2.5's Falcon/auto worker SELF-STARTS after an ASYNCHRONOUS
+ *  transport bind: `createJobWorker` hands back a worker whose transport is null
+ *  until Nano is detected, at which point the SDK `bindTransport(t)`s it and
+ *  `start()`s the worker ITSELF. Calling `start()` before that bind dereferences
+ *  the null transport and — because `start()` is async — surfaces as an UNHANDLED
+ *  REJECTION that crashes the process
+ *  (`TypeError: Cannot read properties of null (reading 'subscribe')`, #415). The
+ *  REST/manual worker, by contrast, never self-starts, so `start()` must still be
+ *  called here. We resolve the version-skew by starting eagerly but NULL-SAFELY:
+ *  swallow ONLY the pre-bind race (the SDK self-starts once the transport binds)
+ *  and SURFACE any other start failure via `console.warn` rather than masking it.
+ *  The SDK owns the start lifecycle end to end (it logs and falls back to REST on
+ *  its own subscribe failure), so discarding the resolved result — as the previous
+ *  `void worker.start()` already did — is safe. Pairs with the library-side
+ *  null-safe, idempotent start (jwulf/nano-sdk-js#12) so neither an eager nor a
+ *  duplicate start can crash. */
+export function adaptJobWorker(worker: RawNanoJobWorker): NanoJobWorker {
+  return {
+    start: () => {
+      try {
+        const started = worker.start();
+        if (isPromiseLike(started)) started.then(undefined, handleStartError);
+      } catch (e) {
+        handleStartError(e);
+      }
+    },
+    stop: () => worker.stop(),
+    stopGracefully: async (opts) => {
+      await worker.stopGracefully(opts);
+    },
+  };
+}
+
+function isPromiseLike(v: unknown): v is PromiseLike<unknown> {
+  return isRecord(v) && typeof v.then === "function";
+}
+
+/** The SDK's pre-bind start race is a NULL/undefined-transport dereference the SDK
+ *  recovers from via its own self-start: a `TypeError` from reading the transport's
+ *  `subscribe` off a `null`/`undefined` transport
+ *  (`Cannot read properties of null (reading 'subscribe')`, #415). Match it NARROWLY
+ *  — the specific `subscribe` dereference signature, not any null/undefined deref —
+ *  so a genuine start failure on the REST/manual path (or an unrelated null-deref
+ *  bug during `start()`) is never mistaken for the race and silently masked. */
+function isPreBindStartRace(e: unknown): boolean {
+  return (
+    e instanceof TypeError &&
+    /Cannot read propert(?:y|ies) of (?:null|undefined) \(reading ['"]subscribe['"]\)/.test(e.message)
+  );
+}
+
+/** Handle an eager-start error NULL-SAFELY. Swallow ONLY the SDK's known pre-bind
+ *  transport race (it self-starts once its transport binds — see
+ *  {@link adaptJobWorker}); any OTHER error is a real start failure (e.g. on the
+ *  REST/manual path) and is SURFACED via `console.warn` so it is not silently
+ *  masked. Never rethrows — callers rely on this to keep an async `start()` from
+ *  escaping as an unhandled rejection that crashes the process. The SDK owns the
+ *  start lifecycle end to end (it logs and falls back to REST on its own subscribe
+ *  failure), so we surface-and-continue rather than propagate. */
+function handleStartError(e: unknown): void {
+  if (isPreBindStartRace(e)) return;
+  console.warn(
+    "[@nanobpm/workflow] job worker start() failed (not the known pre-bind transport " +
+      "race); the SDK owns start and REST fallback, so this is surfaced but not rethrown:",
+    e,
+  );
+}
+
 /** An activated job as delivered to a nano-sdk job handler: the workflow `Job`
  *  fields plus the acknowledgement actions. */
 export type ActivatedJob = Job & {
@@ -253,15 +334,7 @@ export class WorkflowClient {
             return JobActionReceiptSymbol;
           },
         });
-        return {
-          start: () => {
-            void worker.start();
-          },
-          stop: () => worker.stop(),
-          stopGracefully: async (opts) => {
-            await worker.stopGracefully(opts);
-          },
-        };
+        return adaptJobWorker(worker);
       },
     };
   }

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/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

@@ -7,23 +7,14 @@
 
 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";
 
-/** 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[];
-}
+// 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`
@@ -72,29 +63,10 @@ declare module "../declarative.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: 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 }`);
-  }
-}
+ *  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 "";
@@ -105,24 +77,6 @@ function renderAssignment(node: HumanNode): string {
   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 =
@@ -130,7 +84,7 @@ function renderUserTask(node: HumanNode, inc: string[], outg: string[]): string
     `        <zeebe:formDefinition formId="${escapeXml(node.form)}" />\n` +
     `        <zeebe:userTask />\n` +
     renderAssignment(node) +
-    renderIoMapping(node) +
+    renderIoMapping(node.io) +
     `      </bpmn:extensionElements>`;
   return (
     `    <bpmn:userTask id="${escapeXml(id)}" name="${escapeXml(id)}">\n` +
@@ -156,11 +110,7 @@ registerNodeKind("human", {
     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);
+    assertIoMapping(`human("${name}")`, opts.io);
     api.out.push({
       kind: "human",
       name,

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)];
   },