@nanobpm/workflow 0.8.2 → 0.10.0

package/src/nodes/registry.ts

@@ -0,0 +1,105 @@
+// The builder-extension seam (epic #314, S0/#315).
+//
+// Every flow-node KIND (`run`/`task`/`signal`/`timer`/`switch`/… and any kind a
+// feature slice adds) contributes THREE things from its own module under
+// `src/nodes/`, and NOTHING is edited centrally:
+//
+//   1. a `FlowNode` variant — by declaration-merging its shape into the
+//      augmentable `FlowNodeRegistry` interface (see `types.ts`), so the
+//      `FlowNode` union grows without editing a central union;
+//   2. a builder method — by declaration-merging its signature into the
+//      `FlowBuilder<C>` interface (see `declarative.ts`) and registering a
+//      `build` factory here, so `w.<method>(…)` is contributed from the module;
+//   3. `walk` + `emit` handlers — registered here, so the tree walker and the
+//      BPMN emitter DISPATCH through this table instead of a central `switch`.
+//
+// A module registers all three with a single `registerNodeKind(kind, {…})` call
+// at import time; the generated barrel `src/nodes/index.ts` imports every kind
+// module for its registration side effect. Adding a kind is therefore: drop one
+// `src/nodes/<kind>.ts` file — no edit to the union, the dispatch, or the barrel.
+//
+// See `src/nodes/README.md` for the exact pattern a slice follows.
+
+import type { FlowNode } from "../types.js";
+import type { BuildApi, BuilderMethod, Edge, EmitApi, LoopCtx } from "../declarative.js";
+
+/** Recurse the tree walker into a node's nested bodies (see `walkNodes`). */
+export type WalkRecurse = (body: FlowNode[]) => void;
+
+/** The three handlers a flow-node kind contributes. `N` is the kind's own
+ *  `FlowNode` variant (narrowed from the union by the registry key). */
+export interface NodeKindHandlers<N extends FlowNode = FlowNode> {
+  /** Factory for the `FlowBuilder` method that appends this kind's node. Given
+   *  the per-body {@link BuildApi}, returns the method installed on the builder
+   *  as `w.<builderMethod ?? kind>`. Omit for a kind with no authoring method. */
+  build?: (api: BuildApi) => BuilderMethod;
+  /** The builder method name, when it differs from the kind (defaults to the
+   *  kind). */
+  builderMethod?: string;
+  /** Depth-first recursion into the node's nested bodies. Omit for a leaf. */
+  walk?: (node: N, recurse: WalkRecurse) => void;
+  /** Emit this node into the BPMN graph, returning the outgoing (dangling)
+   *  edges its continuation attaches to. */
+  emit: (node: N, incoming: Edge[], loop: LoopCtx | null, api: EmitApi) => Edge[];
+}
+
+// The dispatcher always looks a handler up by `node.kind` before calling it, so
+// each stored handler only ever receives a node of its own kind. Storing the
+// widened `NodeKindHandlers<FlowNode>` is therefore sound; a kind registers with
+// its own narrowed variant type for authoring ergonomics.
+const kinds = new Map<string, NodeKindHandlers>();
+
+/** Register the handlers for one flow-node kind. Called once, at module import
+ *  time, from `src/nodes/<kind>.ts`. */
+export function registerNodeKind<K extends FlowNode["kind"]>(
+  kind: K,
+  handlers: NodeKindHandlers<Extract<FlowNode, { kind: K }>>,
+): void {
+  if (kinds.has(kind)) {
+    throw new Error(`flow-node kind "${kind}" is already registered`);
+  }
+  const walk = handlers.walk;
+  const emit = handlers.emit;
+  kinds.set(kind, {
+    builderMethod: handlers.builderMethod,
+    build: handlers.build,
+    walk: walk ? (node, recurse) => walk(narrow(node, kind), recurse) : undefined,
+    emit: (node, incoming, loop, api) => emit(narrow(node, kind), incoming, loop, api),
+  });
+}
+
+/** Narrow a dispatched node back to a kind's own variant. The discriminant
+ *  check is the proof — no `as` cast. The dispatcher guarantees `node.kind ===
+ *  kind`, so the throw is unreachable in practice. */
+function narrow<K extends FlowNode["kind"]>(node: FlowNode, kind: K): Extract<FlowNode, { kind: K }> {
+  if (isKind(node, kind)) return node;
+  throw new Error(`internal: node of kind "${node.kind}" dispatched to handler for "${kind}"`);
+}
+
+function isKind<K extends FlowNode["kind"]>(node: FlowNode, kind: K): node is Extract<FlowNode, { kind: K }> {
+  return node.kind === kind;
+}
+
+/** The handlers registered for a kind, or `undefined` if none. */
+export function nodeKind(kind: string): NodeKindHandlers | undefined {
+  return kinds.get(kind);
+}
+
+/** The registered kind, or a thrown error naming the unknown kind — used by the
+ *  emitter, which cannot proceed without a handler. */
+export function requireNodeKind(kind: string): NodeKindHandlers {
+  const h = kinds.get(kind);
+  if (!h) {
+    throw new Error(
+      `no handler registered for flow-node kind "${kind}" — ` +
+        `did its module under src/nodes/ import and call registerNodeKind()?`,
+    );
+  }
+  return h;
+}
+
+/** Every registered kind + its handlers, in registration order. Used by
+ *  `makeBuilder` to install each kind's builder method. */
+export function eachNodeKind(): Iterable<[string, NodeKindHandlers]> {
+  return kinds.entries();
+}

package/src/nodes/run.ts

@@ -0,0 +1,29 @@
+// 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 type { NodeEnvelopes, StepHandler } from "../types.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes };
+  }
+}
+
+registerNodeKind("run", {
+  build: (api) => (name: string, handler: StepHandler) => {
+    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/src/nodes/signal.ts

@@ -0,0 +1,35 @@
+// 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 type { Envelope } from "../envelope.js";
+import { assertIdent } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    signal: { kind: "signal"; name: string; correlationKey: string; payload?: Envelope };
+  }
+}
+
+registerNodeKind("signal", {
+  build: (api) => (name: string, opts: { correlationKey: string }) => {
+    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/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,150 @@
+// 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 type { NodeEnvelopes } from "../types.js";
+import { assertJobType, escapeXml } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+
+/** 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>;
+  }
+}
+
+/** 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: string, prompt: PromptBinding): PromptBinding {
+  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: PromptBinding = { 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: PromptBinding): string {
+  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: string, opts?: { jobType?: string; prompt?: PromptBinding }) => {
+    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/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";