@nanobpm/workflow 0.8.2 → 0.9.0

package/dist/declarative.js

@@ -36,7 +36,13 @@
 // Typed data envelopes are LIFTED into the model (nano:shape + dataEnvelope
 // zeebe:property), so the generated .bpmn is ejectable to model-first with its
 // typed contracts intact.
-import { assertIdent, assertJobType, assertTimerCycle, assertTimerDate, assertTimerDuration, escapeXml, jobType, messageName } from "./xml.js";
+import { assertIdent, assertTimerCycle, assertTimerDate, assertTimerDuration, escapeXml, jobType, messageName } from "./xml.js";
+import { eachNodeKind, requireNodeKind } from "./nodes/registry.js";
+// Import the generated barrel purely for its registration side effects: every
+// built-in (and slice-added) kind module registers its FlowNode variant, builder
+// method, and walk/emit handlers at import time. MUST run before `makeBuilder`
+// or the `Compiler` dispatch through the registry.
+import "./nodes/index.js";
 /** Ids the emitter generates for structural nodes / flows / messages. A step
  *  name that collides with one of these would produce a duplicate BPMN id and an
  *  invalid model, so reject them at authoring time. */
@@ -90,200 +96,166 @@ function makeBuilder(id, out, ctx, isRoot = false) {
         fn(makeBuilder(id, body, { ...ctx, loopDepth: 0 }));
         return body;
     };
-    const b = {
-        run(name, handler) {
-            claimName(ctx, id, name);
-            if (typeof handler !== "function")
-                throw new Error(`run("${name}") needs a handler function`);
-            ctx.handlers[name] = handler;
-            out.push({ kind: "run", name, envelopes: contractEnvelopes(ctx, name) });
-            return b;
+    const setStartTimer = (t) => {
+        if (!isRoot) {
+            throw new Error(`startOn() is only valid at the top level of flow "${id}" (not inside switch/branch/loop)`);
+        }
+        if (out.length !== 0)
+            throw new Error(`startOn() must be the first statement in flow "${id}"`);
+        if (ctx.startTimer)
+            throw new Error(`startOn() may be called only once in flow "${id}"`);
+        ctx.startTimer = t;
+    };
+    let builderRef;
+    const api = {
+        id,
+        isRoot,
+        out,
+        contracts: ctx.contracts,
+        handlers: ctx.handlers,
+        get loopDepth() {
+            return ctx.loopDepth;
         },
-        task(name, opts) {
-            claimName(ctx, id, name);
-            const override = opts?.jobType;
-            if (override !== undefined)
-                assertJobType("task jobType", override);
-            out.push({ kind: "task", name, envelopes: contractEnvelopes(ctx, name), jobType: override });
-            return b;
+        self() {
+            if (!builderRef)
+                throw new Error("internal: builder method invoked before assembly");
+            return builderRef;
         },
-        signal(name, opts) {
+        child,
+        childScoped,
+        claim(name) {
             claimName(ctx, id, name);
-            if (!opts || !opts.correlationKey)
-                throw new Error(`signal("${name}") needs { correlationKey }`);
-            assertIdent("correlationKey", opts.correlationKey);
-            out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: ctx.contracts[name]?.in });
-            return b;
-        },
-        timer(name, opts) {
-            claimName(ctx, id, name);
-            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);
-                out.push({ kind: "timer", name, after });
-            }
-            else {
-                const at = opts.at.trim();
-                assertTimerDate(`timer("${name}") at`, at);
-                out.push({ kind: "timer", name, at });
-            }
-            return b;
-        },
-        startOn(spec) {
-            if (!isRoot) {
-                throw new Error(`startOn() is only valid at the top level of flow "${id}" (not inside switch/branch/loop)`);
-            }
-            if (out.length !== 0)
-                throw new Error(`startOn() must be the first statement in flow "${id}"`);
-            if (ctx.startTimer)
-                throw new Error(`startOn() may be called only once in flow "${id}"`);
-            const setCount = TIMER_START_KEYS.filter((key) => typeof timerStartValue(spec, key) === "string").length;
-            if (setCount !== 1) {
-                throw new Error(`startOn() needs exactly one of { cycle }, { after }, or { at } in flow "${id}"`);
-            }
-            if ("cycle" in spec) {
-                const cycle = spec.cycle.trim();
-                assertTimerCycle(`startOn cycle`, cycle);
-                ctx.startTimer = { cycle };
-            }
-            else if ("after" in spec) {
-                const after = spec.after.trim();
-                assertTimerDuration(`startOn after`, after);
-                ctx.startTimer = { after };
-            }
-            else {
-                const at = spec.at.trim();
-                assertTimerDate(`startOn at`, at);
-                ctx.startTimer = { at };
-            }
-            return b;
-        },
-        switch(subject, cases) {
-            if (typeof subject !== "string" || subject.trim() === "") {
-                throw new Error(`switch() needs a non-empty subject expression`);
-            }
-            const caseNodes = [];
-            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: child(fn, false) });
-            }
-            if (caseNodes.length === 0)
-                throw new Error(`switch("${subject}") needs at least one case`);
-            const def = cases.default ? child(cases.default, false) : undefined;
-            out.push({ kind: "switch", subject, cases: caseNodes, default: def });
-            return b;
         },
-        branch(condition, arms) {
-            if (typeof condition !== "string" || condition.trim() === "") {
-                throw new Error(`branch() needs a non-empty FEEL condition`);
-            }
-            if (!arms || typeof arms.then !== "function")
-                throw new Error(`branch("${condition}") needs a then arm`);
-            out.push({
-                kind: "branch",
-                condition,
-                then: child(arms.then, false),
-                else: arms.else ? child(arms.else, false) : undefined,
-            });
-            return b;
-        },
-        loop(body) {
-            if (typeof body !== "function")
-                throw new Error(`loop() needs a body function`);
-            out.push({ kind: "loop", body: child(body, true) });
-            return b;
-        },
-        parallel(branches) {
-            if (!Array.isArray(branches) || branches.length < 2) {
-                throw new Error(`parallel() needs at least two branch blocks`);
-            }
-            for (const fn of branches) {
-                if (typeof fn !== "function")
-                    throw new Error(`parallel() branches must all be blocks (b) => {…}`);
-            }
-            // Each branch runs in its own token scope up to the AND-join, so a
-            // `break`/`continue` must not escape the fork/join into an enclosing
-            // loop. Scope branches (loopDepth resets to 0) so cross-boundary
-            // break/continue is rejected at build time, matching forEach.
-            out.push({ kind: "parallel", branches: branches.map((fn) => childScoped(fn)) });
-            return b;
-        },
-        forEach(collection, itemVar, body, opts) {
-            if (typeof collection !== "string" || collection.trim() === "") {
-                throw new Error(`forEach() needs a non-empty FEEL collection expression`);
-            }
-            // Authors may paste a leading "=" (common in Zeebe FEEL examples). Strip
-            // it so the emitter's own "=" prefix never produces an invalid "==...".
-            const collExpr = collection.trim().replace(/^=/, "").trim();
-            if (collExpr === "") {
-                throw new Error(`forEach() collection expression is empty after stripping the leading "="`);
-            }
-            assertIdent("forEach itemVar", itemVar);
-            if (typeof body !== "function")
-                throw new Error(`forEach("${itemVar}") needs a body function`);
-            const nodes = childScoped(body);
-            if (nodes.length === 0)
-                throw new Error(`forEach("${itemVar}") body declared no steps`);
-            const node = {
-                kind: "forEach",
-                collection: collExpr,
-                itemVar,
-                body: nodes,
-            };
-            if (opts?.sequential)
-                node.sequential = true;
-            if (opts?.outputCollection !== undefined) {
-                assertIdent("forEach outputCollection", opts.outputCollection);
-                node.outputCollection = opts.outputCollection;
-            }
-            if (opts?.outputElement !== undefined) {
-                if (typeof opts.outputElement !== "string" || opts.outputElement.trim() === "") {
-                    throw new Error(`forEach("${itemVar}") outputElement must be a non-empty FEEL expression`);
-                }
-                const outEl = opts.outputElement.trim().replace(/^=/, "").trim();
-                if (outEl === "") {
-                    throw new Error(`forEach("${itemVar}") outputElement is empty after stripping the leading "="`);
-                }
-                node.outputElement = outEl;
-            }
-            if (opts?.completionCondition !== undefined) {
-                if (typeof opts.completionCondition !== "string" || opts.completionCondition.trim() === "") {
-                    throw new Error(`forEach("${itemVar}") completionCondition must be a non-empty FEEL expression`);
-                }
-                const compCond = opts.completionCondition.trim().replace(/^=/, "").trim();
-                if (compCond === "") {
-                    throw new Error(`forEach("${itemVar}") completionCondition is empty after stripping the leading "="`);
-                }
-                node.completionCondition = compCond;
-            }
-            if (node.outputElement && !node.outputCollection) {
-                throw new Error(`forEach("${itemVar}") outputElement needs an outputCollection to collect into`);
-            }
-            out.push(node);
-            return b;
-        },
-        break() {
-            if (ctx.loopDepth === 0)
-                throw new Error(`break() is only valid inside a loop`);
-            out.push({ kind: "break" });
-            return b;
-        },
-        continue() {
-            if (ctx.loopDepth === 0)
-                throw new Error(`continue() is only valid inside a loop`);
-            out.push({ kind: "continue" });
-            return b;
+        contractEnvelopes(name) {
+            return contractEnvelopes(ctx, name);
         },
+        setStartTimer,
+    };
+    // `startOn` is not a node KIND — it lifts a timer onto the start event and
+    // emits no `FlowNode` — so it is installed centrally. Every actual node kind's
+    // builder method is contributed by its own module through the registry.
+    // A NULL-PROTOTYPE table: collision detection below is an OWN-property check,
+    // and building on `Object.prototype` would make both `in`/`Object.hasOwn`
+    // spuriously see inherited names (`toString`, `constructor`, …) as registered
+    // methods — so a kind whose builder method is legitimately named `toString`
+    // would be rejected as a "duplicate" — and would turn a `__proto__` method
+    // name into a prototype-mutating footgun. A null prototype removes both.
+    const methods = Object.create(null);
+    methods.startOn = startOnMethod(api);
+    for (const [kind, handlers] of eachNodeKind()) {
+        if (!handlers.build)
+            continue;
+        const method = handlers.builderMethod ?? kind;
+        if (Object.hasOwn(methods, method)) {
+            throw new Error(`two flow-node kinds both contribute the builder method "${method}"`);
+        }
+        methods[method] = handlers.build(api);
+    }
+    if (!isFlowBuilder(methods)) {
+        throw new Error(assemblyFailureMessage(methods));
+    }
+    // `methods` is now the untyped `FlowBuilder` (object) stored for `api.self()`;
+    // a chaining method's precise return type is the interface's, not this value's.
+    builderRef = methods;
+    if (!isFlowBuilder(methods)) {
+        throw new Error(assemblyFailureMessage(methods));
+    }
+    return methods;
+}
+/** The STABLE built-in authoring surface every assembled `FlowBuilder` must
+ *  expose: `startOn` (installed centrally by {@link startOnMethod}) plus every
+ *  core method a wave-0 built-in node-kind module under `src/nodes/`
+ *  contributes. The runtime guard below fails fast if any of these is missing
+ *  (e.g. a built-in module was tree-shaken away).
+ *
+ *  `satisfies readonly (keyof FlowBuilder)[]` pins each listed name to a real
+ *  `FlowBuilder` method — a typo or a renamed built-in is caught at compile
+ *  time. This is deliberately a ONE-DIRECTIONAL pin: it does NOT assert the
+ *  list mirrors *every* `FlowBuilder` key. `FlowBuilder<C>` is an OPEN,
+ *  declaration-merged interface — the whole point of the `src/nodes/` seam is
+ *  that a feature slice adds a builder method by merging into `FlowBuilder`
+ *  from its own module with NO central edit (see `src/nodes/README.md`). An
+ *  exhaustiveness check here would force every such slice to also edit this
+ *  central list, defeating that seam; a slice's own method is instead installed
+ *  and exercised through its `registerNodeKind` registration and tests. */
+const BUILTIN_BUILDER_METHODS = [
+    "startOn",
+    "run",
+    "task",
+    "signal",
+    "timer",
+    "switch",
+    "branch",
+    "loop",
+    "parallel",
+    "forEach",
+    "break",
+    "continue",
+];
+/** A dynamically-assembled builder satisfies `FlowBuilder<C>` once every core
+ *  built-in method is installed. The check is a runtime type guard (not an `as`
+ *  cast): each own-property must be a function, AND every built-in method in
+ *  {@link BUILTIN_BUILDER_METHODS} must be present — so a missing or
+ *  tree-shaken node-kind registration fails fast here at builder assembly (a
+ *  clear "missing registered methods" error) instead of surfacing later as an
+ *  opaque `w.run is not a function` at authoring time. */
+export function isFlowBuilder(x) {
+    return missingBuilderMethods(x).length === 0 && nonFunctionOwnProperties(x).length === 0;
+}
+/** The subset of {@link BUILTIN_BUILDER_METHODS} not installed as a function on
+ *  `x`. Single source of truth for both the {@link isFlowBuilder} guard and the
+ *  assembly-failure diagnostic below, so the two never drift. */
+function missingBuilderMethods(x) {
+    return BUILTIN_BUILDER_METHODS.filter((method) => typeof Reflect.get(x, method) !== "function");
+}
+/** The own-property names of `x` whose value is not a function — the second
+ *  half of the {@link isFlowBuilder} invariant, factored out so the
+ *  assembly-failure diagnostic can name the offending property without drifting
+ *  from the guard. */
+function nonFunctionOwnProperties(x) {
+    return Object.getOwnPropertyNames(x).filter((k) => typeof Reflect.get(x, k) !== "function");
+}
+/** Diagnostic for a failed builder assembly. Names the missing built-in
+ *  method(s) when a registration was tree-shaken/omitted so the failure is
+ *  actionable; otherwise, when every built-in is present but some own-property
+ *  isn't a function, names that offending property instead. Exported (like
+ *  {@link isFlowBuilder}) so the assembly invariant is unit-testable. */
+export function assemblyFailureMessage(x) {
+    const missing = missingBuilderMethods(x);
+    if (missing.length > 0) {
+        return `internal: assembled FlowBuilder is missing registered methods: ${missing.join(", ")}`;
+    }
+    const nonFunctions = nonFunctionOwnProperties(x);
+    if (nonFunctions.length > 0) {
+        const label = nonFunctions.length === 1 ? "property" : "properties";
+        return `internal: assembled FlowBuilder has non-function own-${label}: ${nonFunctions.join(", ")}`;
+    }
+    return "internal: assembled FlowBuilder failed its assembly invariant";
+}
+/** The central `startOn` builder method (not a node kind). */
+function startOnMethod(api) {
+    return (spec) => {
+        const setCount = TIMER_START_KEYS.filter((key) => typeof timerStartValue(spec, key) === "string").length;
+        if (setCount !== 1) {
+            throw new Error(`startOn() needs exactly one of { cycle }, { after }, or { at } in flow "${api.id}"`);
+        }
+        if ("cycle" in spec) {
+            const cycle = spec.cycle.trim();
+            assertTimerCycle(`startOn cycle`, cycle);
+            api.setStartTimer({ cycle });
+        }
+        else if ("after" in spec) {
+            const after = spec.after.trim();
+            assertTimerDuration(`startOn after`, after);
+            api.setStartTimer({ after });
+        }
+        else {
+            const at = spec.at.trim();
+            assertTimerDate(`startOn at`, at);
+            api.setStartTimer({ at });
+        }
+        return api.self();
     };
-    return b;
 }
 export function defineFlow(id, second, third) {
     assertIdent("workflow id", id);
@@ -315,36 +287,17 @@ export function defineFlow(id, second, third) {
     return flow;
 }
 // --- Tree walkers ------------------------------------------------------------
-/** Depth-first visit of every node in a flow tree (structural combinators
- *  recurse into their bodies). */
+/** Depth-first visit of every node in a flow tree. Recursion into a kind's
+ *  nested bodies is DISPATCHED through the registry (each kind's `walk` handler),
+ *  so a slice's structural combinator recurses without editing a central switch.
+ *  Fails fast (via `requireNodeKind`) on an unregistered kind — matching the
+ *  emitter — so a tree-shaken/missing registration surfaces as a clear error
+ *  rather than silently skipping recursion into that node's nested bodies. A
+ *  registered leaf kind with no `walk` handler is fine (nothing to recurse). */
 export function walkNodes(nodes, visit) {
     for (const n of nodes) {
         visit(n);
-        switch (n.kind) {
-            case "switch":
-                for (const c of n.cases)
-                    walkNodes(c.body, visit);
-                if (n.default)
-                    walkNodes(n.default, visit);
-                break;
-            case "branch":
-                walkNodes(n.then, visit);
-                if (n.else)
-                    walkNodes(n.else, visit);
-                break;
-            case "loop":
-                walkNodes(n.body, visit);
-                break;
-            case "parallel":
-                for (const branch of n.branches)
-                    walkNodes(branch, visit);
-                break;
-            case "forEach":
-                walkNodes(n.body, visit);
-                break;
-            default:
-                break;
-        }
+        requireNodeKind(n.kind).walk?.(n, (body) => walkNodes(body, visit));
     }
 }
 /** The job types of a flow's external `task` steps (anywhere in the tree) — the
@@ -390,8 +343,36 @@ class Compiler {
     live = [];
     seq = 0;
     gw = 0;
+    /** The emit surface handed to each kind's registered `emit` handler. */
+    emitApi;
     constructor(flow) {
         this.flow = flow;
+        this.emitApi = {
+            flowId: flow.id,
+            newEdge: (from, opts) => this.newEdge(from, opts),
+            connect: (incoming, toId) => this.connect(incoming, toId),
+            recordEnvelope: (env) => this.recordEnvelope(env),
+            emitList: (list, incoming, loop) => this.emitList(list, incoming, loop),
+            addNode: (node) => {
+                this.nodes.push({ ...node, scope: node.scope ?? this.currentScope() });
+            },
+            addServiceTask: (node, mi) => this.addServiceTask(node, mi),
+            addCatchEvent: (node) => this.addCatchEvent(node),
+            addTimerCatchEvent: (node) => this.addTimerCatchEvent(node),
+            addGateway: (id, name) => this.addGateway(id, name),
+            addParallelGateway: (id) => this.addParallelGateway(id),
+            addSubProcess: (id, mi) => this.addSubProcess(id, mi),
+            addPlainStart: (id) => this.addPlainStart(id),
+            addPlainEnd: (id) => this.addPlainEnd(id),
+            nextGw: () => this.gw++,
+            currentScope: () => this.currentScope(),
+            pushScope: (id) => {
+                this.scopeStack.push(id);
+            },
+            popScope: () => {
+                this.scopeStack.pop();
+            },
+        };
     }
     currentScope() {
         return this.scopeStack.length ? this.scopeStack[this.scopeStack.length - 1] : undefined;
@@ -529,145 +510,16 @@ class Compiler {
         this.nodes.push(node);
         return node;
     }
-    /** The `<bpmn:multiInstanceLoopCharacteristics>` block for a `forEach` node —
-     *  the same shape whether lifted onto a leaf service task or a sub-process. */
-    miCharacteristics(node) {
-        const seq = node.sequential ? "true" : "false";
-        const attrs = [
-            `inputCollection="${escapeXml(`=${node.collection}`)}"`,
-            `inputElement="${escapeXml(node.itemVar)}"`,
-        ];
-        if (node.outputCollection)
-            attrs.push(`outputCollection="${escapeXml(node.outputCollection)}"`);
-        if (node.outputElement)
-            attrs.push(`outputElement="${escapeXml(`=${node.outputElement}`)}"`);
-        const completion = node.completionCondition
-            ? `      <bpmn:completionCondition>${escapeXml(`=${node.completionCondition}`)}</bpmn:completionCondition>\n`
-            : "";
-        return (`      <bpmn:multiInstanceLoopCharacteristics isSequential="${seq}">\n` +
-            `        <bpmn:extensionElements>\n` +
-            `          <zeebe:loopCharacteristics ${attrs.join(" ")} />\n` +
-            `        </bpmn:extensionElements>\n` +
-            completion +
-            `      </bpmn:multiInstanceLoopCharacteristics>\n`);
-    }
     emitList(list, incoming, loop) {
         let cur = incoming;
         for (const node of list)
             cur = this.emitNode(node, cur, loop);
         return cur;
     }
+    /** Emit one node by DISPATCHING to its registered `emit` handler — no central
+     *  switch on `node.kind`. A slice's kind is emitted by its own module. */
     emitNode(node, incoming, loop) {
-        switch (node.kind) {
-            case "run":
-            case "task": {
-                this.addServiceTask(node);
-                this.connect(incoming, node.name);
-                return [this.newEdge(node.name)];
-            }
-            case "signal": {
-                this.addCatchEvent(node);
-                this.connect(incoming, node.name);
-                this.recordEnvelope(node.payload);
-                return [this.newEdge(node.name)];
-            }
-            case "timer": {
-                this.addTimerCatchEvent(node);
-                this.connect(incoming, node.name);
-                return [this.newEdge(node.name)];
-            }
-            case "switch": {
-                const id = `Gw_${this.gw++}`;
-                const gw = this.addGateway(id, node.subject);
-                this.connect(incoming, id);
-                const out = [];
-                for (const c of node.cases) {
-                    const e = this.newEdge(id, { condition: feelEquals(node.subject, c.value), name: c.value });
-                    out.push(...this.emitList(c.body, [e], loop));
-                }
-                // The default (or a synthesised fall-through) is the unconditional edge.
-                const de = this.newEdge(id, { name: "default" });
-                gw.defaultFlow = de.id;
-                out.push(...this.emitList(node.default ?? [], [de], loop));
-                return out;
-            }
-            case "branch": {
-                const id = `Gw_${this.gw++}`;
-                const gw = this.addGateway(id);
-                this.connect(incoming, id);
-                const te = this.newEdge(id, { condition: feel(node.condition), name: "then" });
-                const out = this.emitList(node.then, [te], loop);
-                const ee = this.newEdge(id, { name: "else" });
-                gw.defaultFlow = ee.id;
-                out.push(...this.emitList(node.else ?? [], [ee], loop));
-                return out;
-            }
-            case "loop": {
-                const headId = `Loop_${this.gw++}`;
-                this.addGateway(headId);
-                this.connect(incoming, headId);
-                const ctx = { headId, breaks: [] };
-                const headOut = this.newEdge(headId);
-                const bodyOut = this.emitList(node.body, [headOut], ctx);
-                // Normal fall-through of the body loops back to the head (continue).
-                this.connect(bodyOut, headId);
-                // The loop exits only via break edges.
-                return ctx.breaks;
-            }
-            case "break": {
-                if (!loop)
-                    throw new Error(`break outside a loop in flow "${this.flow.id}"`);
-                // The incoming edges (from the previous node) become the loop's exit
-                // danglers; this path does not fall through.
-                loop.breaks.push(...incoming);
-                return [];
-            }
-            case "continue": {
-                if (!loop)
-                    throw new Error(`continue outside a loop in flow "${this.flow.id}"`);
-                this.connect(incoming, loop.headId);
-                return [];
-            }
-            case "parallel": {
-                // A diverging parallel gateway forks a token onto every branch; a
-                // converging one joins them (AND-join) into a single continuation.
-                const splitId = `Gw_${this.gw++}`;
-                this.addParallelGateway(splitId);
-                this.connect(incoming, splitId);
-                const joinId = `Gw_${this.gw++}`;
-                this.addParallelGateway(joinId);
-                for (const branch of node.branches) {
-                    const e = this.newEdge(splitId);
-                    const branchOut = this.emitList(branch, [e], loop);
-                    this.connect(branchOut, joinId);
-                }
-                return [this.newEdge(joinId)];
-            }
-            case "forEach": {
-                const mi = this.miCharacteristics(node);
-                const only = node.body.length === 1 ? node.body[0] : undefined;
-                // A single service-task body carries the MI characteristics directly; a
-                // multi-step body is wrapped in an embedded MI sub-process (its own token
-                // scope, with its own start/end).
-                if (only && (only.kind === "run" || only.kind === "task")) {
-                    this.addServiceTask(only, mi);
-                    this.connect(incoming, only.name);
-                    return [this.newEdge(only.name)];
-                }
-                const subId = `Sub_${this.gw++}`;
-                this.addSubProcess(subId, mi);
-                this.connect(incoming, subId);
-                this.scopeStack.push(subId);
-                const startId = `${subId}_start`;
-                this.addPlainStart(startId);
-                const innerOut = this.emitList(node.body, [this.newEdge(startId)], null);
-                const endId = `${subId}_end`;
-                this.addPlainEnd(endId);
-                this.connect(innerOut, endId);
-                this.scopeStack.pop();
-                return [this.newEdge(subId)];
-            }
-        }
+        return requireNodeKind(node.kind).emit(node, incoming, loop, this.emitApi);
     }
     /** Render every node + sequence flow that belongs to `scope` (undefined = the
      *  root process, a sub-process id otherwise). Called for the process body and,
@@ -780,16 +632,22 @@ export function declarativeToBpmn(flow) {
 }
 // --- small XML / FEEL helpers ------------------------------------------------
 const envelopeProp = (dir, value) => `          <zeebe:property name="io.nanobpm.dataEnvelope.${dir}" value="${escapeXml(value)}" />`;
-/** Wrap a raw FEEL expression as a Zeebe condition body (leading `=`). */
-const feel = (expr) => `=${expr}`;
-/** A FEEL equality test `subject = "value"`, with the value as a FEEL string. */
-const feelEquals = (subject, value) => `=${subject} = "${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-function incomingOutgoing(inc, outg) {
+/** Wrap a raw FEEL expression as a Zeebe condition body (leading `=`). Exported
+ *  for slice-added combinators that emit conditional sequence flows. */
+export const feel = (expr) => `=${expr}`;
+/** A FEEL equality test `subject = "value"`, with the value as a FEEL string.
+ *  Exported for slice-added combinators that emit an XOR gateway. */
+export const feelEquals = (subject, value) => `=${subject} = "${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+/** Render the `<bpmn:incoming>`/`<bpmn:outgoing>` refs of a flow node. Exported
+ *  for slice `RenderNode.render` closures. */
+export function incomingOutgoing(inc, outg) {
     return (inc.map((f) => `      <bpmn:incoming>${f}</bpmn:incoming>\n`).join("") +
         outg.map((f) => `      <bpmn:outgoing>${f}</bpmn:outgoing>\n`).join(""));
 }
-const incomingOnly = (inc) => inc.map((f) => `<bpmn:incoming>${f}</bpmn:incoming>`).join("");
-const outgoingOnly = (outg) => outg.map((f) => `<bpmn:outgoing>${f}</bpmn:outgoing>`).join("");
+/** Render only the `<bpmn:incoming>` refs (for end-like events). Exported. */
+export const incomingOnly = (inc) => inc.map((f) => `<bpmn:incoming>${f}</bpmn:incoming>`).join("");
+/** Render only the `<bpmn:outgoing>` refs (for start-like events). Exported. */
+export const outgoingOnly = (outg) => outg.map((f) => `<bpmn:outgoing>${f}</bpmn:outgoing>`).join("");
 function sequenceFlow(e) {
     const nm = e.name ? ` name="${escapeXml(e.name)}"` : "";
     if (e.condition) {

package/dist/nodes/branch.d.ts

@@ -0,0 +1,11 @@
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        branch: {
+            kind: "branch";
+            condition: string;
+            then: FlowNode[];
+            else?: FlowNode[];
+        };
+    }
+}
+export {};