@nanobpm/workflow 0.8.1 → 0.9.0

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;

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;