@nanobpm/workflow 0.8.1 → 0.9.0

package/src/nodes/switch.ts

@@ -0,0 +1,56 @@
+// 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 type { FlowNode, SwitchCase } from "../types.js";
+import type { Block, Edge } from "../declarative.js";
+import { feelEquals } from "../declarative.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    switch: { kind: "switch"; subject: string; cases: SwitchCase[]; default?: FlowNode[] };
+  }
+}
+
+registerNodeKind("switch", {
+  build: (api) => (subject: string, cases: Record<string, Block> & { default?: Block }) => {
+    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: SwitchCase[] = [];
+    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: Edge[] = [];
+    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/src/nodes/task.ts

@@ -0,0 +1,29 @@
+// 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).
+
+import type { NodeEnvelopes } from "../types.js";
+import { assertJobType } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    task: { kind: "task"; name: string; envelopes?: NodeEnvelopes; jobType?: string };
+  }
+}
+
+registerNodeKind("task", {
+  build: (api) => (name: string, opts?: { jobType?: string }) => {
+    api.claim(name);
+    const override = opts?.jobType;
+    if (override !== undefined) assertJobType("task jobType", override);
+    api.out.push({ kind: "task", name, envelopes: api.contractEnvelopes(name), jobType: override });
+    return api.self();
+  },
+  emit: (node, incoming, _loop, api) => {
+    api.addServiceTask(node);
+    api.connect(incoming, node.name);
+    return [api.newEdge(node.name)];
+  },
+});

package/src/nodes/timer.ts

@@ -0,0 +1,42 @@
+// 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 type { TimerAt } from "../types.js";
+import { assertTimerDate, assertTimerDuration } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    timer: { kind: "timer"; name: string } & TimerAt;
+  }
+}
+
+registerNodeKind("timer", {
+  build: (api) => (name: string, opts: { after: string } | { at: string }) => {
+    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/src/test-support/diff.ts

@@ -0,0 +1,69 @@
+// 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.
+
+import type { CanonicalModel } from "./normalize.js";
+
+const useColor = (): boolean => {
+  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: string, s: string): string {
+  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: string[], actual: string[]): { removed: string[]; added: string[] } {
+  const counts = new Map<string, number>();
+  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: string[] = [];
+  const added: string[] = [];
+  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: string, expected: string[], actual: string[]): string[] {
+  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: CanonicalModel, actual: CanonicalModel): boolean {
+  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: CanonicalModel, actual: CanonicalModel): string {
+  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/src/test-support/index.ts

@@ -0,0 +1,53 @@
+// @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 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";
+// The internal builder invariant guard, exposed for the fail-fast guard test.
+export { isFlowBuilder, assemblyFailureMessage } from "../declarative.js";

package/src/test-support/normalize.ts

@@ -0,0 +1,274 @@
+// 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, type XmlElement } from "./xml.js";
+
+/** 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[];
+}
+
+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: XmlElement): boolean {
+  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";
+}
+
+interface Node {
+  id: string;
+  type: string;
+  label: string;
+}
+
+interface Edge {
+  kind: "seq" | "attach" | "contain";
+  from: string;
+  to: string;
+  tag: string;
+}
+
+/** Accumulates the flat graph while walking every process / sub-process. */
+class Collector {
+  readonly refNames = new Map<string, string>();
+  readonly messageDefs = new Map<string, XmlElement>();
+  readonly nodes = new Map<string, Node>();
+  readonly edges: Edge[] = [];
+  readonly messages = new Set<string>();
+  readonly defaultFlows = new Set<string>();
+  private readonly seqFlows: XmlElement[] = [];
+
+  /** 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. */
+  private resolveRef(attr: string, value: string): string {
+    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. */
+  private serialize(el: XmlElement): string {
+    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. */
+  private nodeLabel(el: XmlElement): string {
+    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(";")}]`;
+  }
+
+  private registerNode(el: XmlElement): void {
+    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: XmlElement, scope: string | undefined): void {
+    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(): void {
+    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: XmlElement, c: Collector): void {
+  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: XmlElement, out: XmlElement[]): void {
+  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: string): CanonicalModel {
+  const root = parseXml(bpmnXml);
+  const c = new Collector();
+  collectRefs(root, c);
+
+  const processes: XmlElement[] = [];
+  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<string, { si: number; so: number; at: number; ah: number; ci: number; co: number }>();
+  const bump = (id: string) => {
+    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: string): string => {
+    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/src/test-support/parity.ts

@@ -0,0 +1,85 @@
+// 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, type WorkflowClientOptions } from "../client.js";
+import { declarativeToBpmn } from "../declarative.js";
+import type { DeclarativeFlow, DeployResult, Workflow } from "../types.js";
+import { diffModels } from "./diff.js";
+import { normalize } from "./normalize.js";
+
+/** A derived flow, or the derived BPMN XML directly. */
+export type DerivedInput = DeclarativeFlow | string;
+
+function toBpmnXml(input: DerivedInput): string {
+  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: DerivedInput, goldenBpmnPath: string): void {
+  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}`);
+  }
+}
+
+/** 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;
+}
+
+function resolveClient(opts: DeploySmokeOptions): WorkflowClient | undefined {
+  if (opts.client) return opts.client;
+  const baseUrl = opts.baseUrl ?? process.env.WORKFLOW_GATEWAY_URL;
+  if (!baseUrl) return undefined;
+  const clientOpts: WorkflowClientOptions = {
+    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: Workflow, opts: DeploySmokeOptions = {}): Promise<DeploySmokeResult> {
+  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 };
+}