@nanobpm/workflow 0.8.2 → 0.10.0

package/dist/nodes/run.d.ts

@@ -0,0 +1,10 @@
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        run: {
+            kind: "run";
+            name: string;
+            envelopes?: NodeEnvelopes;
+        };
+    }
+}
+export {};

package/dist/nodes/run.js

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

package/dist/nodes/signal.d.ts

@@ -0,0 +1,11 @@
+import type { Envelope } from "../envelope.js";
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        signal: {
+            kind: "signal";
+            name: string;
+            correlationKey: string;
+            payload?: Envelope;
+        };
+    }
+}

package/dist/nodes/signal.js

@@ -0,0 +1,26 @@
+// Built-in flow-node kind: `signal` — a durable wait for an external/human event
+// correlated on a process variable (a BPMN message intermediate catch event).
+// Contributed from this module through the extension seam (epic #314, S0/#315).
+import { assertIdent } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+registerNodeKind("signal", {
+    build: (api) => (name, opts) => {
+        api.claim(name);
+        if (!opts || typeof opts.correlationKey !== "string" || opts.correlationKey.trim() === "") {
+            throw new Error(`signal("${name}") needs { correlationKey }`);
+        }
+        // Trim before validating/storing, in parity with the race() signal arm: a
+        // value like " prKey " is usable after trimming, so it must not fail the
+        // NCName check on stray whitespace. Name the node in the assertIdent context.
+        const correlationKey = opts.correlationKey.trim();
+        assertIdent(`signal("${name}") correlationKey`, correlationKey);
+        api.out.push({ kind: "signal", name, correlationKey, payload: api.contracts[name]?.in });
+        return api.self();
+    },
+    emit: (node, incoming, _loop, api) => {
+        api.addCatchEvent(node);
+        api.connect(incoming, node.name);
+        api.recordEnvelope(node.payload);
+        return [api.newEdge(node.name)];
+    },
+});

package/dist/nodes/switch.d.ts

@@ -0,0 +1,11 @@
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        switch: {
+            kind: "switch";
+            subject: string;
+            cases: SwitchCase[];
+            default?: FlowNode[];
+        };
+    }
+}
+export {};

package/dist/nodes/switch.js

@@ -0,0 +1,51 @@
+// Built-in flow-node kind: `switch` — a multi-way exclusive choice (a BPMN
+// exclusive gateway); each case routes when `subject` equals the case value, with
+// an optional unconditional `default`. Contributed through the extension seam.
+import { feelEquals } from "../declarative.js";
+import { registerNodeKind } from "./registry.js";
+registerNodeKind("switch", {
+    build: (api) => (subject, cases) => {
+        if (typeof subject !== "string" || subject.trim() === "") {
+            throw new Error(`switch() needs a non-empty subject expression`);
+        }
+        if (cases === null || typeof cases !== "object") {
+            throw new Error(`switch("${subject}") needs a cases object { value: (b) => {…} }`);
+        }
+        const caseNodes = [];
+        for (const [value, fn] of Object.entries(cases)) {
+            if (value === "default")
+                continue;
+            if (typeof fn !== "function")
+                throw new Error(`switch("${subject}") cases must be blocks (b) => {…}`);
+            caseNodes.push({ value, body: api.child(fn, false) });
+        }
+        if (caseNodes.length === 0)
+            throw new Error(`switch("${subject}") needs at least one case`);
+        if (cases.default !== undefined && typeof cases.default !== "function") {
+            throw new Error(`switch("${subject}") default must be a block (b) => {…}`);
+        }
+        const def = cases.default ? api.child(cases.default, false) : undefined;
+        api.out.push({ kind: "switch", subject, cases: caseNodes, default: def });
+        return api.self();
+    },
+    walk: (node, recurse) => {
+        for (const c of node.cases)
+            recurse(c.body);
+        if (node.default)
+            recurse(node.default);
+    },
+    emit: (node, incoming, loop, api) => {
+        const id = `Gw_${api.nextGw()}`;
+        const gw = api.addGateway(id, node.subject);
+        api.connect(incoming, id);
+        const out = [];
+        for (const c of node.cases) {
+            const e = api.newEdge(id, { condition: feelEquals(node.subject, c.value), name: c.value });
+            out.push(...api.emitList(c.body, [e], loop));
+        }
+        const de = api.newEdge(id, { name: "default" });
+        gw.defaultFlow = de.id;
+        out.push(...api.emitList(node.default ?? [], [de], loop));
+        return out;
+    },
+});

package/dist/nodes/task.d.ts

@@ -0,0 +1,47 @@
+/** 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=…
+ *  resourceType="GenericScript" linkName="prompt"/></zeebe:linkedResources>`
+ *  extension — the shape the nano-workforce agent tasks use to attach a prompt
+ *  script to the worker that services the job. */
+export interface PromptBinding {
+    /** The `GenericScript` resource id bound as the prompt (the linkedResource
+     *  `resourceId`, e.g. `"retro.md"`). Required and non-empty. */
+    resourceId: string;
+    /** The linkedResource `bindingType` — how the engine resolves the resource
+     *  version at deploy time. Defaults to `"latest"`. */
+    bindingType?: string;
+    /** Optional prompt addendum: a FEEL expression (or literal) fed to the worker
+     *  through a `<zeebe:ioMapping><zeebe:input source=… target="appendPrompt"/>`
+     *  input, the convention the agent tasks use to append runtime context to the
+     *  bound prompt. Omitted → no `ioMapping` is emitted. */
+    append?: string;
+}
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        task: {
+            kind: "task";
+            name: string;
+            envelopes?: NodeEnvelopes;
+            jobType?: string;
+            /** The agent prompt binding, when the task is an LLM-agent service task. */
+            prompt?: PromptBinding;
+        };
+    }
+}
+declare module "../declarative.js" {
+    interface FlowBuilder<C extends object> {
+        /**
+         * An AGENT external service task: as `task`, but additionally binds an LLM
+         * `prompt` resource to the worker via a `zeebe:linkedResource`
+         * (`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.
+         */
+        task<K extends string>(name: K, opts: {
+            jobType?: string;
+            prompt: PromptBinding;
+        }): FlowBuilder<C>;
+    }
+}

package/dist/nodes/task.js

@@ -0,0 +1,97 @@
+// Built-in flow-node kind: `task` — a durable service task served by a worker
+// OUTSIDE this program (no locally-hosted handler). Its job type defaults to the
+// derived `${flowId}:${name}` unless overridden with `{ jobType }`. Contributed
+// from this module through the extension seam (epic #314, S0/#315).
+//
+// This module also owns the AGENT PROMPT BINDING (epic #314, S4/#319): an
+// optional `{ prompt }` option binds an LLM prompt resource to the worker via a
+// `<zeebe:linkedResource … resourceType="GenericScript" linkName="prompt">`,
+// mirroring the nano-workforce agent service tasks. The extension is contributed
+// entirely from this module — the `task` node's own registered emit handler and
+// 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 { registerNodeKind } from "./registry.js";
+/** Normalize + validate a prompt binding at authoring time, applying the
+ *  `bindingType` default. Emitted string fields are trimmed before storing (in
+ *  parity with how `timer` normalizes `{ after }`/`{ at }`), so a value like
+ *  `resourceId: " retro.md "` passes validation AND is emitted without stray
+ *  surrounding whitespace. Returns a fully-resolved binding stored on the node. */
+function resolvePrompt(name, prompt) {
+    if (typeof prompt !== "object" || prompt === null) {
+        throw new Error(`task("${name}") prompt must be an object with a non-empty resourceId`);
+    }
+    const resourceId = prompt.resourceId;
+    if (typeof resourceId !== "string" || resourceId.trim() === "") {
+        throw new Error(`task("${name}") prompt.resourceId must be a non-empty string`);
+    }
+    // Only an ABSENT bindingType defaults to "latest"; `??` would also swallow an
+    // explicit `null`, masking an authoring mistake. Distinguish `undefined` (use
+    // the default) from any other non-string (reject), in parity with how `append`
+    // below treats `!== undefined` as "provided, so validate strictly".
+    const bindingType = prompt.bindingType === undefined ? "latest" : prompt.bindingType;
+    if (typeof bindingType !== "string" || bindingType.trim() === "") {
+        throw new Error(`task("${name}") prompt.bindingType must be a non-empty string`);
+    }
+    const resolved = { resourceId: resourceId.trim(), bindingType: bindingType.trim() };
+    if (prompt.append !== undefined) {
+        if (typeof prompt.append !== "string" || prompt.append.trim() === "") {
+            throw new Error(`task("${name}") prompt.append must be a non-empty string when provided`);
+        }
+        resolved.append = prompt.append.trim();
+    }
+    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
+ *  (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`
+        : "";
+    return linked + io;
+}
+registerNodeKind("task", {
+    build: (api) => (name, opts) => {
+        api.claim(name);
+        const override = opts?.jobType;
+        if (override !== undefined)
+            assertJobType("task jobType", override);
+        const prompt = opts?.prompt !== undefined ? resolvePrompt(name, opts.prompt) : undefined;
+        api.out.push({
+            kind: "task",
+            name,
+            envelopes: api.contractEnvelopes(name),
+            jobType: override,
+            prompt,
+        });
+        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) {
+            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) });
+        api.connect(incoming, node.name);
+        return [api.newEdge(node.name)];
+    },
+});

package/dist/nodes/timer.d.ts

@@ -0,0 +1,9 @@
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        timer: {
+            kind: "timer";
+            name: string;
+        } & TimerAt;
+    }
+}
+export {};

package/dist/nodes/timer.js

@@ -0,0 +1,34 @@
+// Built-in flow-node kind: `timer` — a durable wait for a point in time (a BPMN
+// timer intermediate catch event): exactly one of `{ after }` (a delay) or
+// `{ at }` (an instant). Contributed through the extension seam (epic #314).
+import { assertTimerDate, assertTimerDuration } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+registerNodeKind("timer", {
+    build: (api) => (name, opts) => {
+        api.claim(name);
+        if (!opts || typeof opts !== "object") {
+            throw new Error(`timer("${name}") needs exactly one of { after } (a delay) or { at } (an instant)`);
+        }
+        const hasAfter = "after" in opts && typeof opts.after === "string";
+        const hasAt = "at" in opts && typeof opts.at === "string";
+        if (hasAfter === hasAt) {
+            throw new Error(`timer("${name}") needs exactly one of { after } (a delay) or { at } (an instant)`);
+        }
+        if ("after" in opts) {
+            const after = opts.after.trim();
+            assertTimerDuration(`timer("${name}") after`, after);
+            api.out.push({ kind: "timer", name, after });
+        }
+        else {
+            const at = opts.at.trim();
+            assertTimerDate(`timer("${name}") at`, at);
+            api.out.push({ kind: "timer", name, at });
+        }
+        return api.self();
+    },
+    emit: (node, incoming, _loop, api) => {
+        api.addTimerCatchEvent(node);
+        api.connect(incoming, node.name);
+        return [api.newEdge(node.name)];
+    },
+});

package/dist/test-support/diff.d.ts

@@ -0,0 +1,8 @@
+import type { CanonicalModel } from "./normalize.js";
+/** True when two canonical models are structurally equal (all three multisets
+ *  match). */
+export declare function modelsEqual(expected: CanonicalModel, actual: CanonicalModel): boolean;
+/** Render a legible red/green structural diff, or `""` when the two models are
+ *  structurally equal. `-`/red is the `expected` (golden) side, `+`/green the
+ *  `actual` (derived) side. */
+export declare function diffModels(expected: CanonicalModel, actual: CanonicalModel): string;

package/dist/test-support/diff.js

@@ -0,0 +1,70 @@
+// A legible red/green structural diff between two canonical models. Each of the
+// three sections (flow nodes, sequence flows, message subscriptions) is compared
+// as a MULTISET: a line present more times on one side than the other is
+// reported, `-` (red) for "expected / golden only" and `+` (green) for "derived
+// only". Equal models produce an empty diff.
+const useColor = () => {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return Boolean(process.stdout?.isTTY);
+};
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+function paint(code, s) {
+    return useColor() ? `${code}${s}${RESET}` : s;
+}
+/** Multiset difference: for each distinct line, the count on `expected` minus the
+ *  count on `actual`. Positive → missing from `actual` (removed); negative →
+ *  extra in `actual` (added). */
+function multisetDiff(expected, actual) {
+    const counts = new Map();
+    for (const line of expected)
+        counts.set(line, (counts.get(line) ?? 0) + 1);
+    for (const line of actual)
+        counts.set(line, (counts.get(line) ?? 0) - 1);
+    const removed = [];
+    const added = [];
+    for (const [line, n] of counts) {
+        for (let k = 0; k < n; k++)
+            removed.push(line);
+        for (let k = 0; k < -n; k++)
+            added.push(line);
+    }
+    return { removed: removed.sort(), added: added.sort() };
+}
+function section(title, expected, actual) {
+    const { removed, added } = multisetDiff(expected, actual);
+    if (removed.length === 0 && added.length === 0)
+        return [];
+    const out = [paint(DIM, `  ${title}:`)];
+    for (const line of removed)
+        out.push(paint(RED, `    - ${line}`));
+    for (const line of added)
+        out.push(paint(GREEN, `    + ${line}`));
+    return out;
+}
+/** True when two canonical models are structurally equal (all three multisets
+ *  match). */
+export function modelsEqual(expected, actual) {
+    return diffModels(expected, actual) === "";
+}
+/** Render a legible red/green structural diff, or `""` when the two models are
+ *  structurally equal. `-`/red is the `expected` (golden) side, `+`/green the
+ *  `actual` (derived) side. */
+export function diffModels(expected, actual) {
+    const lines = [
+        ...section("flow nodes", expected.nodes, actual.nodes),
+        ...section("sequence flows", expected.flows, actual.flows),
+        ...section("message subscriptions", expected.messages, actual.messages),
+    ];
+    if (lines.length === 0)
+        return "";
+    return [
+        paint(DIM, "structural mismatch (-expected/golden, +actual/derived):"),
+        ...lines,
+    ].join("\n");
+}

package/dist/test-support/index.d.ts

@@ -0,0 +1,8 @@
+export { normalize } from "./normalize.js";
+export type { CanonicalModel } from "./normalize.js";
+export { assertDerivationParity, deploySmoke } from "./parity.js";
+export type { DerivedInput, DeploySmokeOptions, DeploySmokeResult } from "./parity.js";
+export { diffModels, modelsEqual } from "./diff.js";
+export { parseXml, localName } from "./xml.js";
+export type { XmlElement } from "./xml.js";
+export { isFlowBuilder, assemblyFailureMessage } from "../declarative.js";

package/dist/test-support/index.js

@@ -0,0 +1,49 @@
+// @nanobpm/workflow/test-support — the DERIVATION-PARITY HARNESS (the oracle).
+//
+// This is the reusable test-support surface S1–S6 (epic #314) import to assert
+// their derived flows against the hand-authored golden `.bpmn` models vendored in
+// `packages/workflow/test/fixtures/nwf/`. It ships as the package subpath export
+// `@nanobpm/workflow/test-support`:
+//
+//   import {
+//     normalize,
+//     assertDerivationParity,
+//     deploySmoke,
+//   } from "@nanobpm/workflow/test-support";
+//
+// PUBLIC SURFACE
+// ─────────────────────────────────────────────────────────────────────────────
+//
+//   normalize(bpmnXml: string): CanonicalModel
+//     Strip DI (`bpmndi:BPMNDiagram` layout) and canonicalize element ids, child
+//     ordering, and sequence-flow ids so only SEMANTIC structure remains. Returns
+//     a `CanonicalModel` — three sorted multisets: `nodes` (flow nodes with their
+//     type + definition + edge-degree signature), `flows` (sequence, attach, and
+//     containment edges by endpoint), and `messages` (each subscribed message's
+//     full definition — name plus `zeebe:subscription correlationKey` and
+//     `zeebe:properties` envelope, so correlationKey/envelope differences count).
+//     Two models mean the same thing iff their `CanonicalModel`s are equal.
+//
+//   assertDerivationParity(derived, goldenBpmnPath): void
+//     `derived` is a `DeclarativeFlow` (its BPMN is derived for you) or derived
+//     BPMN XML. Normalizes both it and the golden at `goldenBpmnPath` and asserts
+//     structural equality over flow nodes, sequence flows, message subscriptions,
+//     and timer/boundary definitions — throwing a legible red/green structural
+//     diff on mismatch.
+//
+//   deploySmoke(derivedModel, opts?): Promise<DeploySmokeResult>
+//     Deploy the derived model to the wasm/live engine and assert acceptance.
+//     Supply `{ client }`, `{ baseUrl }`, or set `WORKFLOW_GATEWAY_URL`; with no
+//     engine reachable it resolves `{ skipped: true }` (never throws) so unit-only
+//     CI stays green, and throws only when a reachable engine REJECTS the model.
+//
+// LOWER-LEVEL HELPERS (for custom assertions):
+//   modelsEqual(a, b): boolean          — structural equality predicate.
+//   diffModels(expected, actual): string — the red/green diff ("" when equal).
+//   parseXml / localName                 — the dependency-free XML reader.
+export { normalize } from "./normalize.js";
+export { assertDerivationParity, deploySmoke } from "./parity.js";
+export { diffModels, modelsEqual } from "./diff.js";
+export { parseXml, localName } from "./xml.js";
+// The internal builder invariant guard, exposed for the fail-fast guard test.
+export { isFlowBuilder, assemblyFailureMessage } from "../declarative.js";

package/dist/test-support/normalize.d.ts

@@ -0,0 +1,19 @@
+/** The id-agnostic, order-agnostic semantic structure of a BPMN model. Two
+ *  models are structurally equal iff their three multisets are equal. */
+export interface CanonicalModel {
+    /** Semantic descriptor of every flow node (task/gateway/event/subProcess),
+     *  sorted. Each carries its type, definition, and edge-degree signature. */
+    nodes: string[];
+    /** Every sequence flow as `«fromNode» =[tag]=> «toNode»`, plus structural
+     *  attach (boundary→host) and containment (subProcess→child) edges, sorted. */
+    flows: string[];
+    /** The full semantic identity of every message a catch event subscribes to,
+     *  sorted (deduped): the serialized `<bpmn:message>` definition — its name plus
+     *  the `zeebe:subscription correlationKey` and any `zeebe:properties` envelope —
+     *  so a differing correlation key or envelope is a structural difference. */
+    messages: string[];
+}
+/** Normalize a BPMN XML document to its canonical semantic model. Strips DI and
+ *  canonicalizes ids, child ordering, and sequence-flow ids so only semantic
+ *  structure remains. */
+export declare function normalize(bpmnXml: string): CanonicalModel;