@nanobpm/workflow 0.8.2 → 0.10.0

package/dist/test-support/normalize.js

@@ -0,0 +1,245 @@
+// Canonicalize a BPMN 2.0 document down to its SEMANTIC structure, so two models
+// that mean the same thing compare equal regardless of element ids, child
+// ordering, or diagram-interchange (DI) layout. This is the oracle S1–S6 assert
+// their derived flows against.
+//
+// What "semantic structure" keeps (and what it deliberately drops):
+//   - DROPPED: the `bpmndi:BPMNDiagram` layout subtree (shapes, edges, bounds);
+//     every element `id` and every `sequenceFlow` id (canonicalized away — a
+//     flow node is identified by its TYPE + semantic definition, an edge by its
+//     endpoints); cosmetic `name` labels on flow nodes and gateways (the routing
+//     meaning lives in edge conditions and in derived task/message identities,
+//     not in a human label); child ORDER (everything is compared as a sorted
+//     multiset).
+//   - KEPT: flow nodes (tasks, gateways, events) with their semantic definition
+//     (task-definition job type, user-task / form / assignment / io-mapping /
+//     linked-resources extension elements, multi-instance characteristics, event
+//     definitions); sequence flows as endpoint pairs with their condition /
+//     default marker; message subscriptions (a catch event's `messageRef`
+//     resolved to the referenced message's full definition — name plus its
+//     `zeebe:subscription correlationKey` and `zeebe:properties` envelope);
+//     timer definitions; and boundary events (their `attachedToRef` modelled as
+//     a structural attach edge to the host, never as a raw-id attribute).
+import { localName, parseXml } from "./xml.js";
+const FLOW_NODES = new Set([
+    "startEvent",
+    "endEvent",
+    "intermediateCatchEvent",
+    "intermediateThrowEvent",
+    "boundaryEvent",
+    "task",
+    "serviceTask",
+    "userTask",
+    "scriptTask",
+    "sendTask",
+    "receiveTask",
+    "manualTask",
+    "businessRuleTask",
+    "callActivity",
+    "subProcess",
+    "adHocSubProcess",
+    "transaction",
+    "exclusiveGateway",
+    "parallelGateway",
+    "inclusiveGateway",
+    "eventBasedGateway",
+    "complexGateway",
+]);
+const REF_ATTRS = new Set(["messageRef", "errorRef", "signalRef", "escalationRef"]);
+function isDI(el) {
+    const prefix = el.name.includes(":") ? el.name.slice(0, el.name.indexOf(":")) : "";
+    if (prefix === "bpmndi" || prefix === "di" || prefix === "dc" || prefix === "omgdi" || prefix === "omgdc") {
+        return true;
+    }
+    const l = localName(el.name);
+    return l === "BPMNDiagram" || l === "BPMNPlane" || l === "BPMNShape" || l === "BPMNEdge" || l === "BPMNLabel";
+}
+/** Accumulates the flat graph while walking every process / sub-process. */
+class Collector {
+    refNames = new Map();
+    messageDefs = new Map();
+    nodes = new Map();
+    edges = [];
+    messages = new Set();
+    defaultFlows = new Set();
+    seqFlows = [];
+    /** Resolve a *Ref value to the referenced element's name (falling back to the
+     *  raw ref only when the target is unknown), recording message subscriptions.
+     *  A `messageRef` records the subscribed message's FULL semantic identity — the
+     *  serialized `<bpmn:message>` definition (its name plus the `zeebe:subscription
+     *  correlationKey` and any `zeebe:properties` envelope), not just its name — so
+     *  two models whose catch events share a message name but differ in correlation
+     *  key or envelope properties do NOT compare equal (the parity oracle would
+     *  otherwise be blind to a wrong-correlationKey derivation). Falls back to the
+     *  bare name only when the referenced message definition is unknown. */
+    resolveRef(attr, value) {
+        const name = this.refNames.get(value) ?? value;
+        if (attr === "messageRef") {
+            const def = this.messageDefs.get(value);
+            this.messages.add(def ? this.serialize(def) : name);
+        }
+        return `@${name}`;
+    }
+    /** Serialize a definition/extension descendant fully (all descendants), with
+     *  sorted attributes (ids dropped, refs resolved) and sorted children, so the
+     *  string is invariant to attribute/child ordering and to id renaming. */
+    serialize(el) {
+        const attrs = Object.entries(el.attrs)
+            .filter(([k]) => k !== "id")
+            .map(([k, v]) => `${k}=${REF_ATTRS.has(k) ? this.resolveRef(k, v) : v}`)
+            .sort();
+        const kids = el.children.filter((c) => !isDI(c)).map((c) => this.serialize(c)).sort();
+        const text = el.text ? `=${el.text}` : "";
+        return `${localName(el.name)}{${attrs.join(",")}}${text}[${kids.join(";")}]`;
+    }
+    /** The id-agnostic semantic descriptor of a flow node: its type, its own
+     *  discriminating attributes, and its definition subtree — but NOT nested flow
+     *  nodes / sequence flows (those are separate graph entities) and NOT cosmetic
+     *  id / name / structural-ref attributes. */
+    nodeLabel(el) {
+        const excluded = new Set(["id", "name", "default", "attachedToRef", "sourceRef", "targetRef"]);
+        const attrs = Object.entries(el.attrs)
+            .filter(([k]) => !excluded.has(k))
+            .map(([k, v]) => `${k}=${REF_ATTRS.has(k) ? this.resolveRef(k, v) : v}`)
+            .sort();
+        const defs = el.children
+            .filter((c) => {
+            const cl = localName(c.name);
+            // Skip nested flow nodes / sequence flows (separate graph entities) and
+            // the `incoming`/`outgoing` flow-id back-references (fully redundant with
+            // the sequence-flow edges, and carrying raw ids that must not leak here).
+            return !isDI(c) && !FLOW_NODES.has(cl) && cl !== "sequenceFlow" && cl !== "incoming" && cl !== "outgoing";
+        })
+            .map((c) => this.serialize(c))
+            .sort();
+        return `${localName(el.name)}(${attrs.join(",")})[${defs.join(";")}]`;
+    }
+    registerNode(el) {
+        const id = el.attrs.id;
+        if (!id)
+            return;
+        this.nodes.set(id, { id, type: localName(el.name), label: this.nodeLabel(el) });
+        if (el.attrs.default)
+            this.defaultFlows.add(el.attrs.default);
+    }
+    /** Walk a container (process or sub-process), registering its flow nodes and
+     *  sequence flows and recursing into nested sub-processes. `scope` is the
+     *  enclosing sub-process id (containment edges point scope→child). */
+    collectContainer(container, scope) {
+        for (const child of container.children) {
+            if (isDI(child))
+                continue;
+            const l = localName(child.name);
+            if (FLOW_NODES.has(l)) {
+                this.registerNode(child);
+                const id = child.attrs.id;
+                if (id && scope)
+                    this.edges.push({ kind: "contain", from: scope, to: id, tag: "" });
+                if (l === "boundaryEvent" && child.attrs.attachedToRef && id) {
+                    this.edges.push({ kind: "attach", from: id, to: child.attrs.attachedToRef, tag: "" });
+                }
+                if (l === "subProcess" || l === "adHocSubProcess" || l === "transaction") {
+                    this.collectContainer(child, id);
+                }
+            }
+            else if (l === "sequenceFlow") {
+                this.seqFlows.push(child);
+            }
+        }
+    }
+    /** Turn collected sequence-flow elements into endpoint edges once every node
+     *  and default marker is known. */
+    finalizeFlows() {
+        for (const sf of this.seqFlows) {
+            const from = sf.attrs.sourceRef;
+            const to = sf.attrs.targetRef;
+            if (!from || !to)
+                continue;
+            const cond = sf.children.find((c) => localName(c.name) === "conditionExpression");
+            let tag = "";
+            if (cond?.text)
+                tag = `if:${cond.text}`;
+            else if (sf.attrs.id && this.defaultFlows.has(sf.attrs.id))
+                tag = "default";
+            this.edges.push({ kind: "seq", from, to, tag });
+        }
+    }
+}
+/** Record every referenceable root definition (`message`/`error`/`signal`/
+ *  `escalation`) so a `*Ref` can be resolved to a stable name. */
+function collectRefs(el, c) {
+    const l = localName(el.name);
+    if ((l === "message" || l === "error" || l === "signal" || l === "escalation") && el.attrs.id) {
+        c.refNames.set(el.attrs.id, el.attrs.name ?? el.attrs.errorCode ?? el.attrs.id);
+        if (l === "message")
+            c.messageDefs.set(el.attrs.id, el);
+    }
+    for (const child of el.children)
+        if (!isDI(child))
+            collectRefs(child, c);
+}
+function findContainers(el, out) {
+    const l = localName(el.name);
+    if (l === "process")
+        out.push(el);
+    for (const child of el.children)
+        if (!isDI(child))
+            findContainers(child, out);
+}
+/** 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 function normalize(bpmnXml) {
+    const root = parseXml(bpmnXml);
+    const c = new Collector();
+    collectRefs(root, c);
+    const processes = [];
+    findContainers(root, processes);
+    if (processes.length === 0)
+        throw new Error("normalize: no <process> element found");
+    for (const p of processes)
+        c.collectContainer(p, undefined);
+    c.finalizeFlows();
+    // Per-node edge-degree signature — captures wiring (how many sequence flows in
+    // / out, whether it hosts or is a boundary, whether it contains or is
+    // contained) so a rewiring that preserves node labels still shows up.
+    const deg = new Map();
+    const bump = (id) => {
+        let d = deg.get(id);
+        if (!d) {
+            d = { si: 0, so: 0, at: 0, ah: 0, ci: 0, co: 0 };
+            deg.set(id, d);
+        }
+        return d;
+    };
+    for (const e of c.edges) {
+        if (e.kind === "seq") {
+            bump(e.from).so += 1;
+            bump(e.to).si += 1;
+        }
+        else if (e.kind === "attach") {
+            bump(e.from).at += 1; // this node is a boundary attached to something
+            bump(e.to).ah += 1; // this node hosts a boundary
+        }
+        else {
+            bump(e.from).co += 1; // this sub-process contains children
+            bump(e.to).ci += 1; // this node is contained
+        }
+    }
+    const labelWithDegree = (id) => {
+        const node = c.nodes.get(id);
+        if (!node)
+            return `«unknown:${id}»`;
+        const d = deg.get(id) ?? { si: 0, so: 0, at: 0, ah: 0, ci: 0, co: 0 };
+        return `${node.label}<in=${d.si},out=${d.so},boundary=${d.at},hosts=${d.ah},contained=${d.ci},contains=${d.co}>`;
+    };
+    const nodes = [...c.nodes.keys()].map(labelWithDegree).sort();
+    const flows = c.edges
+        .map((e) => {
+        const arrow = e.kind === "attach" ? "--attach-->" : e.kind === "contain" ? "--contains-->" : `=[${e.tag}]=>`;
+        return `${labelWithDegree(e.from)} ${arrow} ${labelWithDegree(e.to)}`;
+    })
+        .sort();
+    const messages = [...c.messages].sort();
+    return { nodes, flows, messages };
+}

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

@@ -0,0 +1,28 @@
+import { WorkflowClient } from "../client.js";
+import type { DeclarativeFlow, DeployResult, Workflow } from "../types.js";
+/** A derived flow, or the derived BPMN XML directly. */
+export type DerivedInput = DeclarativeFlow | string;
+/** Derive `derived`'s BPMN, normalize it and the golden at `goldenBpmnPath`, and
+ *  assert structural equality. Throws with a legible structural diff on
+ *  mismatch. Returns silently on parity. */
+export declare function assertDerivationParity(derived: DerivedInput, goldenBpmnPath: string): void;
+/** Options for {@link deploySmoke}. Supply a pre-built `client`, a `baseUrl`
+ *  (a client is built for you), or rely on the `WORKFLOW_GATEWAY_URL` env var. */
+export interface DeploySmokeOptions {
+    client?: WorkflowClient;
+    baseUrl?: string;
+    token?: string;
+    transport?: "auto" | "falcon" | "rest";
+}
+/** The outcome of a {@link deploySmoke}: either a completed deployment, or a
+ *  skip because no engine was reachable. */
+export interface DeploySmokeResult {
+    deployed: boolean;
+    skipped: boolean;
+    reason?: string;
+    result?: DeployResult;
+}
+/** Deploy `model` to the engine and assert the deployment is accepted. Resolves
+ *  a skip (never throws) when no engine is reachable, so it is safe to call in
+ *  unit-only CI; it throws only when a reachable engine REJECTS the model. */
+export declare function deploySmoke(model: Workflow, opts?: DeploySmokeOptions): Promise<DeploySmokeResult>;

package/dist/test-support/parity.js

@@ -0,0 +1,61 @@
+// The two assertions S1–S6 build their derivation-parity tests on:
+//
+//   assertDerivationParity(derivedFlow, goldenBpmnPath)
+//     Derive the flow's BPMN, normalize it and the checked-in golden, and assert
+//     they are structurally equal — throwing a legible red/green diff otherwise.
+//
+//   deploySmoke(derivedModel, opts?)
+//     Deploy the derived model to a live/wasm engine and assert acceptance. When
+//     no engine is reachable (no client, baseUrl, or WORKFLOW_GATEWAY_URL), it
+//     resolves `{ deployed: false, skipped: true }` so unit-only CI stays green —
+//     the caller decides whether to hard-require deployment.
+import { readFileSync } from "node:fs";
+import { WorkflowClient } from "../client.js";
+import { declarativeToBpmn } from "../declarative.js";
+import { diffModels } from "./diff.js";
+import { normalize } from "./normalize.js";
+function toBpmnXml(input) {
+    if (typeof input === "string")
+        return input;
+    return declarativeToBpmn(input);
+}
+/** Derive `derived`'s BPMN, normalize it and the golden at `goldenBpmnPath`, and
+ *  assert structural equality. Throws with a legible structural diff on
+ *  mismatch. Returns silently on parity. */
+export function assertDerivationParity(derived, goldenBpmnPath) {
+    const derivedXml = toBpmnXml(derived);
+    const goldenXml = readFileSync(goldenBpmnPath, "utf8");
+    const golden = normalize(goldenXml);
+    const actual = normalize(derivedXml);
+    const diff = diffModels(golden, actual);
+    if (diff) {
+        throw new Error(`derivation parity failed against ${goldenBpmnPath}:\n${diff}`);
+    }
+}
+function resolveClient(opts) {
+    if (opts.client)
+        return opts.client;
+    const baseUrl = opts.baseUrl ?? process.env.WORKFLOW_GATEWAY_URL;
+    if (!baseUrl)
+        return undefined;
+    const clientOpts = {
+        baseUrl,
+        ...(opts.token ? { token: opts.token } : {}),
+        ...(opts.transport ? { transport: opts.transport } : {}),
+    };
+    return new WorkflowClient(clientOpts);
+}
+/** Deploy `model` to the engine and assert the deployment is accepted. Resolves
+ *  a skip (never throws) when no engine is reachable, so it is safe to call in
+ *  unit-only CI; it throws only when a reachable engine REJECTS the model. */
+export async function deploySmoke(model, opts = {}) {
+    const client = resolveClient(opts);
+    if (!client) {
+        return { deployed: false, skipped: true, reason: "no engine reachable (set baseUrl/client/WORKFLOW_GATEWAY_URL)" };
+    }
+    const result = await client.deploy(model);
+    if (!result || typeof result !== "object" || Object.keys(result).length === 0) {
+        throw new Error(`deploySmoke: engine did not accept "${model.id}" (empty deploy result)`);
+    }
+    return { deployed: true, skipped: false, result };
+}

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

@@ -0,0 +1,17 @@
+/** A parsed XML element. `attrs` preserves declared attributes (entity-decoded);
+ *  `children` are child elements in document order; `text` is the concatenated
+ *  direct text content (trimmed), used for elements like `conditionExpression`. */
+export interface XmlElement {
+    /** The qualified name as written, e.g. `bpmn:serviceTask` or `process`. */
+    name: string;
+    attrs: Record<string, string>;
+    children: XmlElement[];
+    text: string;
+}
+/** The local (un-prefixed) name of an element or attribute. */
+export declare function localName(qualified: string): string;
+/** Parse an XML document into its root element. Throws on a malformed document
+ *  (unbalanced tags, no root, or more than one top-level element). Comments,
+ *  CDATA, the `<?xml?>` prolog and other processing instructions are handled;
+ *  CDATA content contributes to `text`. */
+export declare function parseXml(xml: string): XmlElement;

package/dist/test-support/xml.js

@@ -0,0 +1,135 @@
+// A dependency-free XML reader, just enough to parse a BPMN 2.0 document into a
+// tree the normalizer can canonicalize. BPMN files this package emits (and the
+// hand-authored goldens) are plain XML — elements, attributes, text — with no
+// DTDs, processing instructions beyond the `<?xml …?>` prolog, or mixed-content
+// subtleties that would need a full parser. We keep prefixed names verbatim
+// (`bpmn:serviceTask`, `zeebe:taskDefinition`) so the normalizer can reason about
+// namespaces by local name.
+/** The local (un-prefixed) name of an element or attribute. */
+export function localName(qualified) {
+    const i = qualified.indexOf(":");
+    return i === -1 ? qualified : qualified.slice(i + 1);
+}
+function decodeEntities(s) {
+    return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, body) => {
+        switch (body) {
+            case "lt":
+                return "<";
+            case "gt":
+                return ">";
+            case "amp":
+                return "&";
+            case "quot":
+                return '"';
+            case "apos":
+                return "'";
+        }
+        if (body[0] === "#") {
+            const code = body[1] === "x" || body[1] === "X" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+            // Only decode a valid Unicode scalar value. `String.fromCodePoint` throws
+            // a `RangeError` for code points outside 0..0x10FFFF (e.g. `&#x110000;`),
+            // and surrogate halves (0xD800..0xDFFF) are not valid characters — treat
+            // any such reference as malformed and leave it verbatim rather than
+            // throwing an opaque exception out of `parseXml`.
+            const isScalar = Number.isInteger(code) && code >= 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff);
+            return isScalar ? String.fromCodePoint(code) : m;
+        }
+        return m;
+    });
+}
+function parseAttrs(src) {
+    const attrs = {};
+    const re = /([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+    let m = re.exec(src);
+    while (m !== null) {
+        const value = m[3] !== undefined ? m[3] : (m[4] ?? "");
+        attrs[m[1]] = decodeEntities(value);
+        m = re.exec(src);
+    }
+    return attrs;
+}
+function appendText(el, chunk) {
+    if (chunk)
+        el.text = el.text ? `${el.text} ${chunk}` : chunk;
+}
+/** Parse an XML document into its root element. Throws on a malformed document
+ *  (unbalanced tags, no root, or more than one top-level element). Comments,
+ *  CDATA, the `<?xml?>` prolog and other processing instructions are handled;
+ *  CDATA content contributes to `text`. */
+export function parseXml(xml) {
+    const root = { name: "#root", attrs: {}, children: [], text: "" };
+    const stack = [root];
+    let i = 0;
+    const n = xml.length;
+    while (i < n) {
+        const lt = xml.indexOf("<", i);
+        if (lt === -1)
+            break;
+        if (lt > i)
+            appendText(stack[stack.length - 1], decodeEntities(xml.slice(i, lt)).trim());
+        if (xml.startsWith("<!--", lt)) {
+            const end = xml.indexOf("-->", lt + 4);
+            if (end === -1)
+                throw new Error("parseXml: unterminated comment");
+            i = end + 3;
+            continue;
+        }
+        if (xml.startsWith("<![CDATA[", lt)) {
+            const end = xml.indexOf("]]>", lt + 9);
+            if (end === -1)
+                throw new Error("parseXml: unterminated CDATA");
+            appendText(stack[stack.length - 1], xml.slice(lt + 9, end).trim());
+            i = end + 3;
+            continue;
+        }
+        if (xml.startsWith("<?", lt) || xml.startsWith("<!", lt)) {
+            const end = xml.indexOf(">", lt + 2);
+            if (end === -1)
+                throw new Error("parseXml: unterminated processing instruction / declaration");
+            i = end + 1;
+            continue;
+        }
+        const gt = xml.indexOf(">", lt);
+        if (gt === -1)
+            throw new Error("parseXml: unterminated tag");
+        let inner = xml.slice(lt + 1, gt);
+        if (inner.startsWith("/")) {
+            const closeName = inner.slice(1).trim();
+            if (stack.length <= 1)
+                throw new Error(`parseXml: unbalanced end tag </${closeName}>`);
+            const open = stack.pop();
+            if (open === undefined || open.name !== closeName) {
+                throw new Error(`parseXml: mismatched end tag </${closeName}> (expected </${open?.name ?? "#root"}>)`);
+            }
+            i = gt + 1;
+            continue;
+        }
+        const selfClosing = inner.endsWith("/");
+        if (selfClosing)
+            inner = inner.slice(0, -1);
+        const nameMatch = /^\s*(\S+)/.exec(inner);
+        if (!nameMatch)
+            throw new Error("parseXml: malformed start tag");
+        const name = nameMatch[1];
+        const attrs = parseAttrs(inner.slice(nameMatch[0].length));
+        const el = { name, attrs, children: [], text: "" };
+        stack[stack.length - 1].children.push(el);
+        if (!selfClosing)
+            stack.push(el);
+        i = gt + 1;
+    }
+    if (stack.length !== 1) {
+        const unclosed = stack
+            .slice(1)
+            .map((el) => `<${el.name}>`)
+            .join(", ");
+        throw new Error(`parseXml: unclosed tag(s): ${unclosed}`);
+    }
+    if (root.children.length === 0)
+        throw new Error("parseXml: no root element");
+    if (root.children.length > 1) {
+        const roots = root.children.map((el) => `<${el.name}>`).join(", ");
+        throw new Error(`parseXml: multiple root elements (${roots}) — a well-formed document has exactly one`);
+    }
+    return root.children[0];
+}

package/dist/types.d.ts

@@ -37,62 +37,26 @@ export type FlowContracts = Record<string, StepContract>;
 export type StepHandler<V extends JsonObject = JsonObject, R extends JsonObject = JsonObject> = {
     bivarianceHack(job: Job<V>): Promise<R | void> | R | void;
 }["bivarianceHack"];
-/** A node in a declarative flow tree. Leaf activities carry optional data
- *  envelopes (lifted to `nano:shape` + `dataEnvelope` in the model); structural
- *  combinators carry nested `FlowNode[]` bodies. */
-export type FlowNode = {
-    kind: "run";
-    name: string;
-    envelopes?: NodeEnvelopes;
-} | {
-    kind: "task";
-    name: string;
-    envelopes?: NodeEnvelopes;
-    jobType?: string;
-} | {
-    kind: "signal";
-    name: string;
-    correlationKey: string;
-    payload?: Envelope;
-} | ({
-    kind: "timer";
-    name: string;
-} & TimerAt) | {
-    kind: "switch";
-    subject: string;
-    cases: SwitchCase[];
-    default?: FlowNode[];
-} | {
-    kind: "branch";
-    condition: string;
-    then: FlowNode[];
-    else?: FlowNode[];
-} | {
-    kind: "loop";
-    body: FlowNode[];
-} | {
-    kind: "break";
-} | {
-    kind: "continue";
-} | {
-    kind: "parallel";
-    branches: FlowNode[][];
-} | {
-    kind: "forEach";
-    /** FEEL expression evaluating to the list to fan out over. */
-    collection: string;
-    /** Variable each item is bound to in the child's scope (`inputElement`). */
-    itemVar: string;
-    body: FlowNode[];
-    /** Run children one at a time (sequential MI) instead of all at once. */
-    sequential?: boolean;
-    /** List variable that each child's `outputElement` is collected into. */
-    outputCollection?: string;
-    /** FEEL expression producing each child's contribution to `outputCollection`. */
-    outputElement?: string;
-    /** FEEL boolean that, once true, completes the body early. */
-    completionCondition?: string;
-};
+/** The OPEN registry of flow-node kinds — the single extension seam for the
+ *  `FlowNode` union (epic #314, S0/#315). Each kind module under `src/nodes/`
+ *  declaration-merges ONE property into this interface (`kindName: NodeShape`),
+ *  so `FlowNode` grows without editing a central union here. The built-in kinds
+ *  register `run`/`task`/`signal`/`timer`/`switch`/`branch`/`loop`/`break`/
+ *  `continue`/`parallel`/`forEach` from their own modules through this same
+ *  mechanism — see `src/nodes/README.md`.
+ *
+ *  Invariant: every value type MUST be an object with a `kind` discriminant
+ *  equal to its key, so `FlowNode` stays a discriminated union.
+ *
+ *  This interface is intentionally empty here: it is the augmentation target the
+ *  per-kind modules declaration-merge their variant into. */
+export interface FlowNodeRegistry {
+}
+/** A node in a declarative flow tree, derived from the {@link FlowNodeRegistry}.
+ *  Leaf activities carry optional data envelopes (lifted to `nano:shape` +
+ *  `dataEnvelope` in the model); structural combinators carry nested
+ *  `FlowNode[]` bodies. */
+export type FlowNode = FlowNodeRegistry[keyof FlowNodeRegistry];
 /** A timer intermediate-catch definition: exactly one of `after` (an ISO-8601
  *  delay or FEEL expression) or `at` (an absolute instant or FEEL expression).
  *  Encoded as an XOR so downstream consumers can rely on exactly-one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.8.2",
+  "version": "0.10.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",
@@ -17,6 +17,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./test-support": {
+      "types": "./dist/test-support/index.d.ts",
+      "default": "./dist/test-support/index.js"
+    },
     "./source": "./src/index.ts"
   },
   "files": [
@@ -26,13 +30,17 @@
   "engines": {
     "node": ">=22.6"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/nodes/*.js",
+    "./src/nodes/*.ts"
+  ],
   "dependencies": {
     "@nanobpm/nano-sdk": "^1.2.5"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.types.json",
+    "gen:nodes": "node scripts/gen-node-registry.mjs",
+    "build": "npm run gen:nodes && tsc -p tsconfig.json",
+    "typecheck": "npm run gen:nodes && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.types.json",
     "test": "npm run build && npm run test:ci",
     "test:ci": "node --experimental-strip-types --test test/*.test.ts",
     "test:integration": "node --experimental-strip-types --test test/integration.test.ts",