@nanobpm/workflow 0.8.2 → 0.10.0

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 };
+}

package/src/test-support/xml.ts

@@ -0,0 +1,140 @@
+// 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.
+
+/** 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 function localName(qualified: string): string {
+  const i = qualified.indexOf(":");
+  return i === -1 ? qualified : qualified.slice(i + 1);
+}
+
+function decodeEntities(s: string): string {
+  return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, body: string) => {
+    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: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const re = /([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+  let m: RegExpExecArray | null = 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: XmlElement, chunk: string): void {
+  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: string): XmlElement {
+  const root: XmlElement = { name: "#root", attrs: {}, children: [], text: "" };
+  const stack: XmlElement[] = [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: XmlElement = { 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/src/types.ts

@@ -52,36 +52,26 @@ export type StepHandler<
   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).