@nanobpm/workflow 0.11.0 → 0.12.0

package/README.md

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

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/nodes/human.d.ts

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

package/dist/nodes/human.js

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

package/dist/nodes/index.d.ts

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway through @nanobpm/nano-sdk (the shared engine-transport spine — ADR 0055), which negotiates the Falcon protocol on a Nano server and REST elsewhere.",
   "type": "module",
   "license": "Apache-2.0",

package/src/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/nodes/human.ts

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

package/src/nodes/index.ts

@@ -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";