@uipath/maestro-builder-sdk 6.11.5 → 6.12.0

package/dist/bpmn/bpmn-sdk.js

@@ -2,11 +2,105 @@ import { connector as makeConnector } from '../core/actions.js';
 import { checkBpmnExpressions, BpmnBuildError } from './bpmn-expr-check.js';
 import { BPMN_SCHEMA_VERSIONS } from './format-profile.js';
 import { schemaVersionRefusal } from '../schema-version.js';
-import { bindingRequiredFields, REGISTRY_GAPS, typedNodeOutputVar } from './typed-node.js';
+import { bindingRequiredFields, REGISTRY_GAPS, registryType, typedNodeOutputVar } from './typed-node.js';
+import { DATA_SERVICE_ACTIVITY_TYPE, DATA_SERVICE_CONNECTOR_KEY, dataServiceWire } from './data-service.js';
 export { BpmnBuildError } from './bpmn-expr-check.js';
 function normTimer(t) {
     return typeof t === 'string' ? { duration: t } : t;
 }
+/** Bookkeeping the nesting sugar shares across every scope of one process. */
+class SugarRegistry {
+    /** Flow ids the builder wrote by implication rather than from an explicit `.sequenceFlow()`. */
+    impliedFlowIds = new Set();
+    /**
+     * Ids to give implied edges, keyed `source\u0000target` — see {@link ScopeBuilder.flowIds}.
+     *
+     * An implied edge has no call of its own, so there is nowhere to name it and its id
+     * is derived. This is the one place an author (in practice, `decompile`) can say what
+     * a derived id should be instead.
+     */
+    pinnedFlowIds = new Map();
+    /** Variables an `errorVar` asked for — declared at build unless the author declared the id. */
+    autoVars = [];
+}
+const GATEWAY_NODE_KINDS = new Set(['exclusiveGateway', 'parallelGateway', 'inclusiveGateway', 'eventBasedGateway']);
+/**
+ * Whether the node serializes to a start event — nothing may flow INTO it.
+ *
+ * Exported because `graph.ts` needs the SAME answer: `check --graph` decides what is
+ * `[NO INCOMING]` and what is merely an entry point, and a second copy of this test
+ * drifted — it missed the `typed` arm, so a registry type whose element IS a start
+ * event was reported unreachable.
+ *
+ * @param n - The node.
+ * @returns True when the node is an entry point of its own.
+ * @internal
+ */
+export function isStartLike(n) {
+    if (n.kind === 'startEvent')
+        return true;
+    if (n.kind === 'connectorEvent')
+        return n.subscribe === 'trigger';
+    if (n.kind !== 'typed')
+        return false;
+    try {
+        return registryType(n.type, n.spec).element === 'bpmn:StartEvent';
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether a pending exit may be wired into this node when it is placed. */
+function isContinuationTarget(n) {
+    if (isStartLike(n) || n.kind === 'boundaryEvent')
+        return false;
+    if (n.kind === 'subProcess' && n.triggeredByEvent)
+        return false;
+    return true;
+}
+/**
+ * Whether, in a `sequence` scope, the path continues out of this node to the next
+ * one placed. An end event ends it; a gateway's fan-out is never implied; a boundary
+ * event and an event sub-process start their own paths.
+ */
+function opensPath(n) {
+    if (n.kind === 'endEvent' || n.kind === 'boundaryEvent' || GATEWAY_NODE_KINDS.has(n.kind))
+        return false;
+    if (n.kind === 'subProcess' && n.triggeredByEvent)
+        return false;
+    return true;
+}
+/** Whether the node is something an event-based gateway can wait on. */
+function waitsForEvent(n) {
+    if (n.kind === 'intermediateCatchEvent')
+        return true;
+    if (n.kind === 'connectorEvent')
+        return n.subscribe === 'event';
+    if (n.kind !== 'typed')
+        return false;
+    try {
+        const element = registryType(n.type, n.spec).element;
+        return element === 'bpmn:IntermediateCatchEvent' || element === 'bpmn:ReceiveTask';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The product's error-capture row: an output reading `=Error` into a variable.
+ *
+ * Which extension carries it depends on the element. A boundary event takes a
+ * `uipath:activity`, as every error boundary in the real exports does; a start event
+ * cannot (`uip maestro bpmn validate`: *"uipath:Activity cannot be attached to
+ * bpmn:startEvent"*), so an event sub-process's error start carries the row on a
+ * `uipath:mapping` instead — the same element a start event's input mapping uses.
+ */
+function errorCapturePayload(varId, on) {
+    return {
+        type: on === 'boundaryEvent' ? 'uipath:Activity' : 'BPMN.Variables',
+        outputRows: [{ name: 'Error', type: 'jsonSchema', var: varId, source: '=Error' }],
+    };
+}
 // ─── Definitions registry (shared across the top process + sub-processes) ─────
 /**
  * Collects `uipath:binding` declarations, de-duped by id.
@@ -95,13 +189,34 @@ function uniqueId(prefix, index) {
  * element id (`Error_1`) — could never match a real failure, so the handler was
  * unreachable. Passing `{ name, code }` still sets them independently.
  */
-function toErrorDef(defs, error) {
+function toErrorDef(defs, error, where) {
     // `true` is catch-any: no `bpmn:error` is declared and no `errorRef` is written.
     if (error === true)
         return { type: 'error' };
     const spec = typeof error === 'string' ? { name: error } : error;
+    // A BLANK name declares a `bpmn:error` with nothing to match on, which the platform
+    // rejects (ERROR_BOUNDARY_EVENT_EMPTY_ERROR_REF on a boundary,
+    // ERROR_END_EVENT_MISSING_EXCEPTION on an end event) after a whole toolchain cycle.
+    // `error: true` is the way to say "any error"; a name is the way to say which.
+    if (spec.name.trim() === '') {
+        throw new Error(`${where}: the error name is empty, so the declared \`bpmn:error\` has nothing to match on. ` +
+            'Pass `error: true` to catch any error, or a name — `error: "PaymentFailed"`, or ' +
+            '`error: { name: "PaymentFailed", code: "PAYMENT_FAILED" }`.');
+    }
     return { type: 'error', errorRef: defs.errorRef(spec.name, spec.code ?? spec.name) };
 }
+/** The error a boundary event or event sub-process catches: its ref, or catch-all. */
+function errorCaught(n) {
+    const event = 'event' in n ? n.event : undefined;
+    if (event?.type !== 'error')
+        return undefined;
+    return { catchAll: event.errorRef === undefined, ref: event.errorRef };
+}
+/** The single start event of a built sub-process scope, when it has exactly one. */
+function loneStart(nodes) {
+    const starts = nodes.filter((n) => n.kind === 'startEvent');
+    return starts.length === 1 ? starts[0] : undefined;
+}
 // ─── Graph scope (shared by the top process and sub-processes) ────────────────
 /**
  * The set of node/flow/variable methods common to the process root and every
@@ -110,11 +225,11 @@ function toErrorDef(defs, error) {
  */
 class ScopeBuilder {
     /** @internal */
-    _nodes = [];
+    _nodes;
     /** @internal */
-    _flows = [];
+    _flows;
     /** @internal */
-    _vars = [];
+    _vars;
     // An explicit field, not a constructor parameter property: an inline comment
     // on a parameter property never reaches the emitted `.d.ts` property, so the
     // `@internal` tag would be lost there.
@@ -122,18 +237,428 @@ class ScopeBuilder {
     _defs;
     /** @internal */
     _bindingRegistry;
+    /** @internal */
+    _storage;
+    /** @internal */
+    _sugar;
+    /** @internal How THIS scope wires siblings — an arm's is always `sequence`. */
+    _mode;
+    /** @internal The mode of the real scope this builder writes into, which a nested `.subProcess()` inherits. */
+    _scopeMode;
+    /** @internal Whether this builder is an arm or handler path rather than a real scope. */
+    _isArm = false;
+    /** @internal The id of a start event the builder synthesized for this scope (an event sub-process body). */
+    _synthesizedStart;
+    /** @internal Elements placed in a `sequence` scope with nothing leading into them, checked at close. */
+    _unattached = [];
+    /** @internal Edges waiting for the element that continues them. */
+    _open = [];
+    /** @internal Whether anything has been placed yet, so an unreachable element can be told from the first. */
+    _started = false;
+    /** @internal What left this path for good (`.goto()`), after which nothing may follow. */
+    _closedBy;
     /**
      * @param defs - Definitions-level message/error declarations, shared with every scope.
      * @param bindings - `uipath:binding` declarations, shared so a typed node can
      * declare one from inside a sub-process.
+     * @param storage - The arrays to write into; an arm shares its enclosing scope's,
+     * a real scope gets its own.
+     * @param mode - How siblings no explicit flow covers are wired — see `WiringMode`.
+     * @param sugar - Process-wide bookkeeping for the nesting sugar.
      * @returns The scope builder.
      */
-    constructor(defs, bindings) {
+    constructor(defs, bindings, storage, mode = 'explicit', sugar = new SugarRegistry()) {
         this._defs = defs;
         this._bindingRegistry = bindings;
+        this._storage = storage ?? { nodes: [], flows: [], vars: [], mustClose: [] };
+        this._nodes = this._storage.nodes;
+        this._flows = this._storage.flows;
+        this._vars = this._storage.vars;
+        this._mode = mode;
+        this._scopeMode = mode;
+        this._sugar = sugar;
+    }
+    /**
+     * Choose how this scope wires the elements no explicit `.sequenceFlow()` covers.
+     *
+     * @remarks
+     * `'explicit'` is the default: siblings are not wired to each other, only the exits
+     * of a nested construct continue to the next element. `'sequence'` wires consecutive
+     * siblings in order, so a linear process needs no `.sequenceFlow()` at all.
+     *
+     * Three rules keep `'sequence'` local and reviewable. **Explicit wins**: an element
+     * that already has an explicit outgoing flow is not also wired to the next one, so a
+     * hand-written edge never gains a silent twin. **A bare gateway implies nothing
+     * outward**: it is wired into, but its outgoing flows are yours to write (or use
+     * `.choose()` / `.fork()` / `.race()`, which imply theirs). **Nothing dangles
+     * silently**: an element nothing leads into, or a path that does not end, is refused
+     * at `.build()` rather than emitted. `bpmn check --graph` prints the wiring that
+     * resulted, implied edges marked, so a change can be reviewed against what was
+     * inferred rather than what was typed.
+     *
+     * Must come before the scope's first element. A `.subProcess()` body inherits its
+     * enclosing scope's mode and may set its own; an arm or handler body is always
+     * `sequence` and refuses the call.
+     *
+     * @example
+     * **A linear process with no sequence flows written**
+     * ```ts
+     * bpmn('intake')
+     *   .flowMode('sequence')
+     *   .var('note', 'string', { default: '' })
+     *   .startEvent('start')
+     *   .task('assign', { set: { note: 'hello' } })
+     *   .scriptTask('log', { script: 'return note;', inputs: { note: '=vars.note' } })
+     *   .endEvent('done')
+     *   .build();
+     * ```
+     *
+     * @param mode - `'explicit'` or `'sequence'`.
+     * @returns This builder, so calls chain.
+     * @throws If called inside an arm or handler body, or after an element has been placed.
+     */
+    flowMode(mode) {
+        if (this._isArm) {
+            throw new Error(`.flowMode('${mode}') is not available inside an arm or handler body — those always chain in order.`);
+        }
+        if (this._nodes.length > 0) {
+            throw new Error(`.flowMode('${mode}') must come before the scope's first element; "${this._nodes[0].id}" is already placed.`);
+        }
+        this._mode = mode;
+        this._scopeMode = mode;
+        return this;
     }
     push(node) {
+        this.place(node);
+        return this;
+    }
+    /**
+     * Place an activity and run its body, in which boundary events are declared.
+     *
+     * @param node - The activity node.
+     * @param body - Its boundary handlers, if any.
+     * @returns This builder, so calls chain.
+     */
+    pushActivity(node, body) {
+        this.place(node);
+        if (body)
+            body(new ActivityBuilder(this, node.id));
+        return this;
+    }
+    /**
+     * Place a node: wire every pending exit into it, record it, and — in a
+     * `sequence` scope — leave it as the open end the next element continues from.
+     *
+     * @param node - The node to place.
+     * @param viaSugar - Set when the builder itself is placing a gateway it synthesized,
+     * which a `sequence` scope otherwise refuses.
+     * @internal
+     */
+    place(node, viaSugar = false) {
+        if (this._closedBy !== undefined) {
+            throw new Error(`"${node.id}" follows ${this._closedBy}, which already left this path — nothing can come after it.`);
+        }
+        if (this._mode === 'sequence') {
+            if (isStartLike(node)) {
+                if (this._isArm) {
+                    throw new Error(`startEvent "${node.id}": a body has no start event of its own — it begins where the enclosing element hands over to it.`);
+                }
+                if (this._synthesizedStart !== undefined) {
+                    throw new Error(`startEvent "${node.id}": an event sub-process has exactly one start event, and this one's is ` +
+                        `synthesized as "${this._synthesizedStart}" — write what follows it instead.`);
+                }
+                // Explicit wins here as everywhere: a plain exit whose element already has an
+                // explicit outgoing flow was wired by hand and is not open — the same test
+                // `continueTo` applies before implying an edge and `closeScope` applies at the
+                // end. Only an exit nothing continues, or one carrying a condition or default
+                // (a branch with nowhere to go), blocks a new chain.
+                const dangling = this._open.filter((e) => e.condition !== undefined || e.defaultOf !== undefined || !this.hasExplicitOutgoing(e.source));
+                if (dangling.length > 0) {
+                    throw new Error(`startEvent "${node.id}" begins a new chain while "${dangling.map((e) => e.source).join('", "')}" is still ` +
+                        `open — end the current path with an end event before starting another.`);
+                }
+            }
+            // Inside an arm a bare gateway is refused outright: its fan-out cannot be implied
+            // and nothing after it could be reached. In a real scope it is allowed — it is
+            // wired INTO, and its outgoing flows are the author's to write — and whatever
+            // follows it is checked at close for an explicit incoming edge.
+            if (GATEWAY_NODE_KINDS.has(node.kind) && !viaSugar && this._isArm) {
+                throw new Error(`${node.kind} "${node.id}": inside a body, branch with .choose() / .fork() / .race() — ` +
+                    `a bare gateway's outgoing flows cannot be implied.`);
+            }
+        }
+        const target = isContinuationTarget(node);
+        if (target) {
+            if (this._mode === 'sequence' && this._started && this._open.length === 0) {
+                if (this._isArm) {
+                    throw new Error(`"${node.id}" is unreachable: the path ended before it (an end event, or every arm of a branch), so nothing leads to it.`);
+                }
+                // Placed with nothing implied into it. Legal only if an explicit flow leads
+                // here — which may be written later — so it is checked when the scope closes.
+                const previous = this._nodes[this._nodes.length - 1];
+                this._unattached.push({ id: node.id, after: previous ? previous.id : '' });
+            }
+            this.continueTo(node.id);
+        }
+        this._nodes.push(node);
+        this._started = true;
+        if (this._mode === 'sequence' && opensPath(node))
+            this._open = [{ source: node.id }];
+        else if (target)
+            this._open = [];
+    }
+    /** Wire every pending exit into `target`, except one the author already wired by hand. */
+    continueTo(target) {
+        for (const exit of this._open) {
+            // Explicit wins: a plain exit whose element already has an explicit outgoing
+            // flow was wired by hand, and an implied edge beside it would be a second,
+            // silent fan-out. An exit that CARRIES something — a condition, a default —
+            // is an edge in its own right and is always written.
+            if (exit.condition === undefined && exit.defaultOf === undefined && this.hasExplicitOutgoing(exit.source))
+                continue;
+            this.writeImpliedFlow(exit, target);
+        }
+        this._open = [];
+    }
+    hasExplicitOutgoing(source) {
+        return this._flows.some((f) => f.source === source && !this._sugar.impliedFlowIds.has(f.id));
+    }
+    /**
+     * Write the flow a pending exit stands for, now that its target is known.
+     *
+     * @param exit - The exit.
+     * @param target - The element it flows into.
+     * @internal
+     */
+    writeImpliedFlow(exit, target) {
+        // An id the author pinned for this pair wins over the derived one. Nothing else
+        // changes: the edge is still implied, still counted as implied, and a gateway
+        // `default` still ends up naming whichever id the edge got.
+        let id = this._sugar.pinnedFlowIds.get(`${exit.source}\u0000${target}`) ?? `Flow_${exit.source}_${target}`;
+        const existing = this._flows.find((f) => f.id === id);
+        if (existing && existing.source === exit.source && existing.target === target) {
+            // The same edge, already there — an author's explicit restatement, or two
+            // exits converging on one target from one source. One edge, not two.
+            if (exit.defaultOf)
+                exit.defaultOf.default = id;
+            return;
+        }
+        if (existing) {
+            // A DIFFERENT edge already owns that id. `Flow_<source>_<target>` is ambiguous
+            // the moment an element id contains an underscore: `a_b → c` and `a → b_c` both
+            // spell `Flow_a_b_c`. Left alone the second edge ships with a duplicate id and
+            // `check` reports DUPLICATE_DOCUMENT_ID for a flow the author never named and,
+            // because the edge is implied, has no way to rename. So the id is suffixed until
+            // it is free. An author who wants a specific id still writes `.sequenceFlow()`.
+            let n = 2;
+            while (this._flows.some((f) => f.id === `${id}_${n}`))
+                n++;
+            id = `${id}_${n}`;
+        }
+        this._flows.push({ id, source: exit.source, target, name: exit.name, condition: exit.condition, implied: true });
+        this._sugar.impliedFlowIds.add(id);
+        if (exit.defaultOf)
+            exit.defaultOf.default = id;
+    }
+    /**
+     * Check the implied wiring of a real scope once its author's function has
+     * returned: every path a handler had to end has ended, and every exit a construct
+     * left open reached something.
+     *
+     * @param what - The scope, for the message.
+     * @internal
+     */
+    closeScope(what) {
+        // The duplicate-error refusals again, over the FINISHED node list.
+        //
+        // `_attach` and `.eventSubProcess()` catch the collision at the call site, which is
+        // where the best message lives, but only for the sugar: `.boundaryEvent()` and a
+        // hand-rolled `.subProcess(…, { triggeredByEvent: true })` never go through them, so
+        // two explicitly-written handlers on one activity, or two hand-rolled nets in one
+        // scope, reached `validate`. Order mattered too — the call-site scan sees earlier
+        // nodes only. Repeating the test here costs one pass and covers every spelling and
+        // both orders.
+        const seenOnActivity = new Map();
+        const seenNets = [];
+        for (const n of this._nodes) {
+            const here = n.kind === 'boundaryEvent'
+                ? { key: n.attachedTo, list: seenOnActivity.get(n.attachedTo) ?? [] }
+                : n.kind === 'subProcess' && n.triggeredByEvent === true
+                    ? { key: undefined, list: seenNets }
+                    : undefined;
+            if (!here)
+                continue;
+            const start = n.kind === 'subProcess' ? loneStart(n.nodes) : undefined;
+            const caught = n.kind === 'boundaryEvent' ? errorCaught(n) : start === undefined ? undefined : errorCaught(start);
+            if (caught === undefined)
+                continue;
+            const clash = here.list.find((o) => o.catchAll === caught.catchAll && o.ref === caught.ref);
+            if (clash !== undefined) {
+                const where = here.key !== undefined ? `on "${here.key}"` : 'in this scope';
+                throw new Error(`"${n.id}" catches the same error as "${clash.id}" ${where} ` +
+                    `(${caught.catchAll ? 'both catch ANY error' : `both catch "${caught.ref}"`}), so one of the two can ` +
+                    'never run. Catch a specific error in each, or keep the one catch-all.');
+            }
+            here.list.push({ id: n.id, catchAll: caught.catchAll, ref: caught.ref });
+            if (here.key !== undefined)
+                seenOnActivity.set(here.key, here.list);
+        }
+        for (const { id, after } of this._unattached) {
+            if (!this._flows.some((f) => f.target === id)) {
+                throw new Error(`"${id}" has no incoming flow. In a sequence scope it was placed after "${after}", which does not ` +
+                    `continue to it (a bare gateway's outgoing flows are never implied; an end event ends the path). ` +
+                    `Wire it with .sequenceFlow(…, "${id}"), or place it after an element that continues.`);
+            }
+        }
+        for (const { id, reason } of this._storage.mustClose) {
+            if (!this._flows.some((f) => f.source === id)) {
+                throw new Error(`${reason} ends at "${id}", which has no outgoing flow. A non-interrupting handler runs beside a token ` +
+                    `that will reach the next statement anyway, so its path cannot rejoin there: end it with an end event, ` +
+                    `leave it with .goto(), or wire it with .sequenceFlow("${id}", …).`);
+            }
+        }
+        this._storage.mustClose.length = 0;
+        for (const exit of this._open) {
+            const who = exit.origin ?? what;
+            if (exit.condition !== undefined || exit.defaultOf !== undefined) {
+                throw new Error(`${who} has nowhere to go: nothing follows the branch in ${what}. Add the element that comes ` +
+                    `next, or end every arm inside its own body.`);
+            }
+            if (!this._flows.some((f) => f.source === exit.source)) {
+                throw new Error(`${who} ends at "${exit.source}", which has no outgoing flow, and nothing follows it in ${what} ` +
+                    `to continue it. Add the element that comes next, end the path with an end event, or wire it with ` +
+                    `.sequenceFlow("${exit.source}", …).`);
+            }
+        }
+        this._open = [];
+    }
+    /**
+     * The definitions registry, for the activity builder to intern a message or error.
+     *
+     * @returns The registry shared by every scope of this process.
+     * @internal
+     */
+    _defsOf() {
+        return this._defs;
+    }
+    /**
+     * This scope's variable declarations, for an `errorVar` to be declared into.
+     *
+     * @returns The array the scope declares variables into.
+     * @internal
+     */
+    _varsOf() {
+        return this._vars;
+    }
+    /**
+     * Attach a boundary event to an activity of this scope and run its handler path.
+     *
+     * @param activityId - The activity the boundary attaches to.
+     * @param suffix - `onError` / `onTimer` / `onMessage`, for the derived id.
+     * @param spec - The event definition and the options it came with.
+     * @param body - The handler path.
+     * @internal
+     */
+    _attach(activityId, suffix, spec, body) {
+        const { opts } = spec;
+        const id = opts.id ?? `${activityId}_${suffix}`;
+        if (this._nodes.some((n) => n.id === id)) {
+            throw new Error(`"${activityId}" already has a boundary event "${id}"; a second .${suffix}() on one activity needs its own \`id\`.`);
+        }
+        if (opts.errorVar !== undefined && opts.payload !== undefined) {
+            throw new Error(`.${suffix}() on "${activityId}": pass \`errorVar\` or \`payload\`, not both — both write the event's output row.`);
+        }
+        // Two handlers on one activity catching the SAME error: whichever the runtime picks,
+        // the other is dead, and the platform rejects the pair outright
+        // (MULTIPLE_CATCH_ALL_BOUNDARY_EVENTS_ON_TASK for two catch-alls,
+        // DUPLICATE_ERROR_BOUNDARY_EVENT_ON_TASK for two of the same ref). Both handlers are
+        // in hand here, so this is a refusal rather than a diagnostic a rung later.
+        const caught = errorCaught({ kind: 'boundaryEvent', id, attachedTo: activityId, event: spec.event });
+        if (caught !== undefined) {
+            const clash = this._nodes.find((n) => {
+                if (n.kind !== 'boundaryEvent' || n.attachedTo !== activityId)
+                    return false;
+                const other = errorCaught(n);
+                return other !== undefined && other.catchAll === caught.catchAll && other.ref === caught.ref;
+            });
+            if (clash !== undefined) {
+                throw new Error(`.${suffix}() on "${activityId}" catches the same error as "${clash.id}" ` +
+                    `(${caught.catchAll ? 'both catch ANY error' : `both catch "${caught.ref}"`}), so one of the two can never ` +
+                    'run. Catch a specific error in each handler, or keep the one catch-all.');
+            }
+        }
+        const node = {
+            kind: 'boundaryEvent',
+            id,
+            name: opts.name,
+            attachedTo: activityId,
+            cancelActivity: spec.interrupting,
+            event: spec.event,
+            payload: opts.payload ?? (opts.errorVar !== undefined ? errorCapturePayload(opts.errorVar, 'boundaryEvent') : undefined),
+        };
+        // Straight into the scope, not through `place`: a boundary event is not a
+        // continuation of anything, and must not consume the exits waiting for one.
         this._nodes.push(node);
+        if (opts.errorVar !== undefined)
+            this._sugar.autoVars.push({ id: opts.errorVar, vars: this._vars, elementId: id });
+        const arm = new PathBuilder(this._defs, this._bindingRegistry, this._storage, this._sugar, [{ source: id, origin: `the handler "${id}" on "${activityId}"` }], this._scopeMode);
+        body?.(arm);
+        const tails = arm._finish();
+        if (spec.interrupting) {
+            // The activity was cancelled, so the handler's path IS the continuation: it
+            // rejoins at the next statement, as the activity's own path would have.
+            this._open.push(...tails);
+        }
+        else {
+            // The activity is still running and will reach the next statement itself;
+            // the handler's path must end on its own — checked when the scope closes,
+            // so an explicit flow written later still counts.
+            for (const t of tails)
+                this._storage.mustClose.push({ id: t.source, reason: `The non-interrupting handler "${id}" on "${activityId}"` });
+        }
+    }
+    /**
+     * The shared lowering of `choose` / `fork` / `race`: a splitting gateway, one
+     * arm per branch, and a join only when more than one arm falls through.
+     *
+     * @param split - The gateway that opens the construct.
+     * @param joinKind - The gateway kind that closes it, when one is needed.
+     * @param arms - Each arm's entry edge and body.
+     * @param what - The construct, for messages.
+     * @param mustWait - `race`: each arm has to begin with something that waits.
+     */
+    branch(split, joinKind, arms, what, mustWait = false, join = {}) {
+        this.place(split, true);
+        const exits = [];
+        arms.forEach((arm, i) => {
+            const ab = new PathBuilder(this._defs, this._bindingRegistry, this._storage, this._sugar, [arm.entry], this._scopeMode);
+            arm.body?.(ab);
+            if (mustWait) {
+                const first = ab._first;
+                if (!first || !waitsForEvent(first)) {
+                    throw new Error(`${what}: arm ${i + 1} must begin with what it waits for — an intermediateCatchEvent (message or timer), ` +
+                        `a receiveMessage, or a waitForEvent — but begins with ${first ? `${first.kind} "${first.id}"` : 'nothing'}.`);
+                }
+            }
+            exits.push(...ab._finish());
+        });
+        const empties = exits.filter((e) => e.source === split.id);
+        if (empties.length > 1) {
+            throw new Error(`${what} has ${empties.length} arms with no body; at most one arm may be empty.`);
+        }
+        if (exits.length >= 2) {
+            // Only when more than one arm actually reaches the continuation: a single
+            // fall-through needs no join, and emitting one would be the SUPERFLUOUS_GATEWAY
+            // the construct exists to make unwritable.
+            const joinNode = { kind: joinKind, id: join.id ?? `${split.id}_join`, name: join.name };
+            for (const e of exits)
+                this.writeImpliedFlow(e, joinNode.id);
+            this._nodes.push(joinNode);
+            this._open = [{ source: joinNode.id, origin: `the join of ${what}` }];
+        }
+        else {
+            this._open = exits;
+        }
         return this;
     }
     // ── Events ──
@@ -162,17 +687,21 @@ class ScopeBuilder {
         if (opts.trigger !== undefined && opts.payload !== undefined) {
             throw new Error(`startEvent "${id}": \`trigger\` and \`payload\` both write the event's extension element; pass one.`);
         }
+        if (opts.interrupting === false && opts.error !== undefined) {
+            throw new Error(`startEvent "${id}": an error start is always interrupting — the throw has already ended the scope it came from.`);
+        }
         return this.push({
             kind: 'startEvent',
             id,
             name: opts.name,
             payload: opts.payload,
+            interrupting: opts.interrupting === false ? false : undefined,
             // `error` is handled here rather than in `startCatchDef` because it needs the
             // definitions registry to intern the `bpmn:error`, exactly as `endEvent` does —
             // and because an intermediate catch event (the other `startCatchDef` caller)
             // cannot carry one: BPMN catches errors at a boundary or an event sub-process
             // start, never mid-flow.
-            event: opts.error !== undefined ? toErrorDef(this._defs, opts.error) : this.startCatchDef(opts),
+            event: opts.error !== undefined ? toErrorDef(this._defs, opts.error, `startEvent "${id}"`) : this.startCatchDef(opts),
             trigger: opts.trigger === undefined
                 ? undefined
                 : { type: 'Intsvc.TimerTrigger', outputVar: opts.trigger === true ? undefined : opts.trigger.outputVar },
@@ -190,7 +719,7 @@ class ScopeBuilder {
         if (opts.terminate)
             event = { type: 'terminate' };
         else if (opts.error !== undefined)
-            event = toErrorDef(this._defs, opts.error);
+            event = toErrorDef(this._defs, opts.error, `endEvent "${id}"`);
         else if (opts.message !== undefined)
             event = { type: 'message', messageRef: this._defs.messageRef(opts.message) };
         return this.push({ kind: 'endEvent', id, name: opts.name, event, payload: opts.payload });
@@ -232,7 +761,7 @@ class ScopeBuilder {
     boundaryEvent(id, opts) {
         let event;
         if (opts.error !== undefined)
-            event = toErrorDef(this._defs, opts.error);
+            event = toErrorDef(this._defs, opts.error, `boundaryEvent "${id}"`);
         else if (opts.timer !== undefined)
             event = { type: 'timer', timer: normTimer(opts.timer) };
         else if (opts.message !== undefined)
@@ -303,15 +832,17 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - The Jint JavaScript `script`, and its input/output mappings.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    scriptTask(id, opts) {
-        return this.push({
+    scriptTask(id, opts, body) {
+        return this.pushActivity({
             kind: 'scriptTask',
             id,
             name: opts.name,
             script: opts.script,
             scriptFormat: opts.scriptFormat ?? 'JavaScript',
+            scriptVersion: opts.scriptVersion ?? 'v3',
             inputs: opts.inputs ?? {},
             outputs: opts.outputs ?? {},
             outputRows: opts.outputRows,
@@ -321,17 +852,18 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
     /**
      * A plain task that assigns variables (`BPMN.Variables`).
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - `name`, and the variable assignments the task makes.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    task(id, opts = {}) {
-        return this.push({
+    task(id, opts = {}, body) {
+        return this.pushActivity({
             kind: 'task',
             id,
             name: opts.name,
@@ -340,7 +872,7 @@ class ScopeBuilder {
             retry: opts.retry,
             loop: opts.loop,
             errorMapping: opts.errorMapping,
-        });
+        }, body);
     }
     /**
      * A task element carrying NO `uipath:*` payload — an abstract task, in BPMN's terms.
@@ -360,6 +892,7 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - `name`, and which task `element` to emit (default `bpmn:task`).
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      *
      * @example
@@ -370,8 +903,8 @@ class ScopeBuilder {
      *   .endEvent('e')
      * ```
      */
-    plainTask(id, opts = {}) {
-        return this.push({
+    plainTask(id, opts = {}, body) {
+        return this.pushActivity({
             kind: 'plainTask',
             id,
             name: opts.name,
@@ -380,18 +913,21 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
-    connector(id, a, b, c, d) {
+    connector(id, a, b, c, d, e) {
+        // The two forms put `opts` and `body` one position apart; sort them out first.
+        const stringly = typeof a === 'string';
+        const bpmnOpts = (stringly ? (typeof d === 'function' ? undefined : d) : c) ?? {};
+        const body = stringly ? e : typeof d === 'function' ? d : undefined;
         // Reuse the shared connector() overload to parse descriptor-or-string into a
         // ConnectorSpec; then carry its fields onto the BPMN node.
-        const spec = typeof a === 'string'
-            ? makeConnector(a, b, c, d)
-            : makeConnector(a, b, c);
+        const spec = stringly
+            ? makeConnector(a, b, c, bpmnOpts)
+            : makeConnector(a, b, bpmnOpts);
         if (spec.kind !== 'connector')
             throw new Error('connector(): unexpected spec kind');
-        const bpmnOpts = (typeof a === 'string' ? d : c) ?? {};
-        return this.push({
+        return this.pushActivity({
             kind: 'connector',
             id,
             name: bpmnOpts.name,
@@ -406,7 +942,7 @@ class ScopeBuilder {
             skipCondition: bpmnOpts.skipCondition,
             retry: bpmnOpts.retry,
             loop: bpmnOpts.loop,
-        });
+        }, body);
     }
     /**
      * An **HTTP request** service task (`bpmn:sendTask` +
@@ -439,11 +975,12 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - The request, plus `name`, `outputVar`, and the shared activity options.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    http(id, opts) {
-        const { name, url, method, headers, parameters, body, outputs, outputVar, skipCondition, retry, loop, errorMapping } = opts;
-        return this.push({
+    http(id, opts, body) {
+        const { name, url, method, headers, parameters, body: requestBody, outputs, outputVar, skipCondition, retry, loop, errorMapping } = opts;
+        return this.pushActivity({
             kind: 'typed',
             id,
             name,
@@ -458,7 +995,7 @@ class ScopeBuilder {
                 url,
                 ...(headers !== undefined ? { headers } : {}),
                 ...(parameters !== undefined ? { parameters } : {}),
-                ...(body !== undefined ? { body } : {}),
+                ...(requestBody !== undefined ? { body: requestBody } : {}),
             },
             inputs: {},
             outputs,
@@ -467,7 +1004,102 @@ class ScopeBuilder {
             retry,
             loop,
             errorMapping,
+        }, body);
+    }
+    /**
+     * A UiPath **Data Fabric** (Data Service) record or file operation — create,
+     * update, get, query, delete a record, or download / upload / delete a record's
+     * file field — as an `Intsvc.ActivityExecution` send task in the exact shape the
+     * Flow→BPMN converter and Studio Web write.
+     *
+     * @remarks
+     * The connector library ships one Data Service operation, so `.connector()` cannot
+     * author the rest, and hand-filling `.activity('Intsvc.ActivityExecution', …)` gets
+     * the wire details wrong in ways `validate` does not catch (a `recordId` in the body,
+     * a curated `objectName` on an entity-form path, a folder binding keyed by the folder).
+     * This writes each of the eight operations the way the platform's own tools do:
+     * create and update in the ENTITY form (`POST /<Entity>`, `PUT /<Entity>/{id}`,
+     * `objectName` = the entity), the others in the CURATED form (`entityName` as a
+     * path parameter, `objectName` = the curated operation), every parameter its own
+     * `path` / `query` / `file` row and the record as the one json `body` row. Needs no
+     * connector library at compile time.
+     *
+     * The response lands in `outputVar` (default `<id>_response`) and the error payload in
+     * `<id>_Error`, both declared for you.
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - The entity, connection and folder, plus the operation and its parameters — see {@link DataServiceOpts} and {@link DataServiceOperation}.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
+     * @returns This builder, so calls chain.
+     */
+    dataService(id, opts, body) {
+        const wire = dataServiceWire(opts.entity, opts);
+        const connection = this.dataServiceBinding(id, 'connection', opts.connection, 'ConnectionId', 'Data Fabric connection');
+        const folder = opts.folder !== undefined
+            ? this.dataServiceBinding(id, 'folder', opts.folder, 'folderKey', 'Data Fabric folder', connection.key)
+            : undefined;
+        const responseVar = opts.outputVar ?? `${id}_response`;
+        return this.pushActivity({
+            kind: 'typed',
+            id,
+            name: opts.name ?? wire.label,
+            type: DATA_SERVICE_ACTIVITY_TYPE,
+            context: {
+                // `activity` is the selected-operation key the canvas validator requires
+                // (EMPTY_REQUIRED_FIELD without it); the converter omits it and the CLI accepts
+                // both, so it carries the same verb `operation` does — as `.connector()` writes it.
+                activity: wire.context.operation,
+                connectorKey: DATA_SERVICE_CONNECTOR_KEY,
+                connection: connection.ref,
+                ...(folder ? { folderKey: folder.ref } : {}),
+                ...wire.context,
+                activityConfigurationVersion: 'v1',
+                metadata: {},
+            },
+            inputs: {},
+            inputRows: wire.inputRows,
+            outputRows: [
+                {
+                    name: 'response',
+                    type: 'jsonSchema',
+                    source: '=response',
+                    var: responseVar,
+                    ...(opts.schema !== undefined ? { schema: opts.schema } : {}),
+                },
+                { name: 'Error', type: 'jsonSchema', source: '=Error', var: `${id}_Error`, schema: errorSchema },
+            ],
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        }, body);
+    }
+    /**
+     * @internal Resolve a `.dataService()` connection or folder to a `=bindings.<id>`
+     * reference: an existing binding by id, else one already declared for the same
+     * key, else a new one declared on the author's behalf. `companionKey` is the
+     * connection's key a folder binding must carry as its `resourceKey`.
+     */
+    dataServiceBinding(nodeId, role, given, propertyAttribute, displayName, companionKey) {
+        const byId = given.startsWith('=bindings.') ? given.slice('=bindings.'.length) : given;
+        const same = (b) => b.resource === 'Connection' && b.propertyAttribute.toLowerCase() === propertyAttribute.toLowerCase();
+        const existing = this._bindingRegistry.bindings.find((b) => b.id === byId) ??
+            this._bindingRegistry.bindings.find((b) => same(b) && b.default === given);
+        if (existing) {
+            // A folder given as a binding the author declared is re-keyed at serialize, once
+            // its companion is known — see `folderCompanionKeys` in serialize.ts.
+            return { ref: `=bindings.${existing.id}`, key: existing.resourceKey ?? existing.default ?? existing.id };
+        }
+        const decl = this._bindingRegistry.declare({
+            id: `${nodeId}_${role}`,
+            name: displayName,
+            resource: 'Connection',
+            propertyAttribute,
+            default: given,
+            resourceKey: companionKey ?? given,
         });
+        return { ref: `=bindings.${decl.id}`, key: decl.resourceKey ?? given };
     }
     /**
      * @internal Turn a literal into a binding reference where the platform demands
@@ -504,8 +1136,8 @@ class ScopeBuilder {
         return out;
     }
     /** @internal Shared body of the Orchestrator process-invocation methods. */
-    orchestratorNode(id, type, opts) {
-        return this.push({
+    orchestratorNode(id, type, opts, body) {
+        return this.pushActivity({
             kind: 'typed',
             id,
             name: opts.name,
@@ -523,7 +1155,7 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
     /**
      * Start an **RPA process** and wait for it (`Orchestrator.StartJob`).
@@ -541,20 +1173,22 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which process, folder, and input arguments.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    startProcess(id, opts) {
-        return this.orchestratorNode(id, 'Orchestrator.StartJob', opts);
+    startProcess(id, opts, body) {
+        return this.orchestratorNode(id, 'Orchestrator.StartJob', opts, body);
     }
     /**
      * Start an **agent** and wait for it (`Orchestrator.StartAgentJob`).
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which agent process, folder, and input arguments.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    startAgent(id, opts) {
-        return this.orchestratorNode(id, 'Orchestrator.StartAgentJob', opts);
+    startAgent(id, opts, body) {
+        return this.orchestratorNode(id, 'Orchestrator.StartAgentJob', opts, body);
     }
     /**
      * Invoke an **agentic process** as a call activity
@@ -562,10 +1196,11 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which process, folder, input arguments, and whether to wait.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    startAgenticProcess(id, opts) {
-        return this.orchestratorNode(id, opts.async ? 'Orchestrator.StartAgenticProcessAsync' : 'Orchestrator.StartAgenticProcess', opts);
+    startAgenticProcess(id, opts, body) {
+        return this.orchestratorNode(id, opts.async ? 'Orchestrator.StartAgenticProcessAsync' : 'Orchestrator.StartAgenticProcess', opts, body);
     }
     /**
      * Invoke a **case-management process** as a call activity
@@ -573,10 +1208,11 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which case process, folder, input arguments, and whether to wait.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    startCaseProcess(id, opts) {
-        return this.orchestratorNode(id, opts.async ? 'Orchestrator.StartCaseMgmtProcessAsync' : 'Orchestrator.StartCaseMgmtProcess', opts);
+    startCaseProcess(id, opts, body) {
+        return this.orchestratorNode(id, opts.async ? 'Orchestrator.StartCaseMgmtProcessAsync' : 'Orchestrator.StartCaseMgmtProcess', opts, body);
     }
     /**
      * Execute an **API workflow**, fire-and-forget
@@ -588,10 +1224,11 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which workflow, folder, and input arguments.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    executeApiWorkflow(id, opts) {
-        return this.orchestratorNode(id, 'Orchestrator.ExecuteApiWorkflowAsync', opts);
+    executeApiWorkflow(id, opts, body) {
+        return this.orchestratorNode(id, 'Orchestrator.ExecuteApiWorkflowAsync', opts, body);
     }
     /**
      * Execute a **business rule** and wait for it (`Orchestrator.BusinessRules`, on a
@@ -636,9 +1273,10 @@ class ScopeBuilder {
      * @param opts - Which rule package, folder, and input arguments. `outputVar` defaults
      * to `<id>_businessRuleResponse` — see the note in the implementation for why this one
      * type does not take its default from the spec.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    businessRule(id, opts) {
+    businessRule(id, opts, body) {
         // The ONE place this type departs from its family, and deliberately.
         //
         // Every other member takes its default output variable from the registry's
@@ -653,10 +1291,7 @@ class ScopeBuilder {
         //
         // Pinning it here makes the default independent of the label. The output ROW still
         // carries the registry's own `name`, so the artifact is unchanged.
-        return this.orchestratorNode(id, 'Orchestrator.BusinessRules', {
-            ...opts,
-            outputVar: opts.outputVar ?? `${id}_businessRuleResponse`,
-        });
+        return this.orchestratorNode(id, 'Orchestrator.BusinessRules', { ...opts, outputVar: opts.outputVar ?? `${id}_businessRuleResponse` }, body);
     }
     /**
      * Add an item to an Orchestrator **queue** (`Orchestrator.CreateQueueItem`, or
@@ -675,10 +1310,11 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which queue and folder, the item content, and whether to wait for it.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    queueItem(id, opts) {
-        return this.push({
+    queueItem(id, opts, body) {
+        return this.pushActivity({
             kind: 'typed',
             id,
             name: opts.name,
@@ -695,7 +1331,7 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
     /**
      * A **human task** — an Action App task a person completes (`bpmn:userTask` +
@@ -745,10 +1381,11 @@ class ScopeBuilder {
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - The app, the outcomes offered, what the human sees, and which
      * response fields to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    humanTask(id, opts) {
-        return this.push({
+    humanTask(id, opts, body) {
+        return this.pushActivity({
             kind: 'typed',
             id,
             name: opts.name,
@@ -768,7 +1405,7 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
     /**
      * Wait for an internal message from another Maestro process
@@ -807,10 +1444,11 @@ class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - The message name, the correlation reference, and what to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    receiveMessage(id, opts) {
-        return this.push({
+    receiveMessage(id, opts, body) {
+        return this.pushActivity({
             kind: 'typed',
             id,
             name: opts.name,
@@ -823,7 +1461,7 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
     /**
      * Wait mid-flow for an Integration Service connector event
@@ -863,10 +1501,11 @@ class ScopeBuilder {
      * @param connector - The connector key, e.g. `'uipath-microsoft-outlook365'`.
      * @param event - The event name, e.g. `'email-received'`.
      * @param opts - Connection/folder bindings, the `where` scope, and what to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    waitForEvent(id, connector, event, opts) {
-        return this.push({
+    waitForEvent(id, connector, event, opts, body) {
+        return this.pushActivity({
             kind: 'connectorEvent',
             id,
             name: opts.name,
@@ -886,7 +1525,7 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
     /**
      * START the process when an Integration Service connector event fires
@@ -966,10 +1605,11 @@ class ScopeBuilder {
      * @param action - The `AgentExecution` operation name.
      * @param inputs - The invocation payload.
      * @param opts - `mode`, the connection/folder bindings, and what to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    externalAgent(id, connector, action, inputs, opts) {
-        return this.externalTask('agent', id, connector, action, inputs, opts);
+    externalAgent(id, connector, action, inputs, opts, body) {
+        return this.externalTask('agent', id, connector, action, inputs, opts, body);
     }
     /**
      * Invoke an external workflow through an Integration Service connector
@@ -984,14 +1624,15 @@ class ScopeBuilder {
      * @param action - The `ProcessExecution` operation name.
      * @param inputs - The invocation payload.
      * @param opts - `mode`, the connection/folder bindings, and what to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    externalWorkflow(id, connector, action, inputs, opts) {
-        return this.externalTask('workflow', id, connector, action, inputs, opts);
+    externalWorkflow(id, connector, action, inputs, opts, body) {
+        return this.externalTask('workflow', id, connector, action, inputs, opts, body);
     }
     /** @internal Shared body of the two external-invocation methods. */
-    externalTask(family, id, connector, action, inputs, opts) {
-        return this.push({
+    externalTask(family, id, connector, action, inputs, opts, body) {
+        return this.pushActivity({
             kind: 'externalTask',
             id,
             name: opts.name,
@@ -1010,7 +1651,7 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
     /**
      * ANY registry-backed node, by extension type — the generic form the typed
@@ -1042,17 +1683,20 @@ class ScopeBuilder {
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param type - The registry extension type, e.g. `'A2A.AgentExecution'`.
      * @param opts - Context values, payload, output mapping and the shared activity options.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    activity(id, type, opts = {}) {
-        return this.push({
+    activity(id, type, opts = {}, body) {
+        return this.pushActivity({
             kind: 'typed',
             id,
             name: opts.name,
             type,
-            context: opts.context ?? {},
-            contextRows: opts.contextRows,
+            context: defaultActivityIdentity(type, opts.context ?? {}, opts.contextRows),
+            contextRows: defaultActivityIdentityRows(type, opts.context ?? {}, opts.contextRows),
             inputs: opts.inputs ?? {},
+            inputRows: opts.inputRows,
+            spec: opts.spec,
             typeVersion: opts.typeVersion,
             inputSchema: opts.inputSchema,
             outputVar: opts.outputVar,
@@ -1064,7 +1708,7 @@ class ScopeBuilder {
             retry: opts.retry,
             errorMapping: opts.errorMapping,
             loop: opts.loop,
-        });
+        }, body);
     }
     // ── Sub-process (nested graph) ──
     /**
@@ -1073,14 +1717,312 @@ class ScopeBuilder {
     * @param id - The element id, unique in the process and used by `sequenceFlow`.
     * @param fn - Receives a sub-builder for the elements inside it.
     * @param opts - `name`, and the loop characteristics when it repeats.
+    * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
     * @returns This builder, so calls chain.
     */
-    subProcess(id, fn, opts = {}) {
-        const sb = new SubProcessBuilder(this._defs, this._bindingRegistry);
+    subProcess(id, fn, opts = {}, body) {
+        // Inherits the enclosing REAL scope's mode — an arm passes its parent's on, not its
+        // own always-sequence — and the body may still call `.flowMode()` first to differ.
+        const sb = new SubProcessBuilder(this._defs, this._bindingRegistry, undefined, this._scopeMode, this._sugar);
         fn(sb);
-        return this.push(sb._buildNode(id, opts));
+        sb.closeScope(`sub-process "${id}"`);
+        return this.pushActivity(sb._buildNode(id, opts), body);
+    }
+    /**
+     * An EVENT sub-process — a handler that lives inside this scope and starts when
+     * an error, a message, or a timer occurs anywhere in it (`bpmn:subProcess
+     * triggeredByEvent="true"`, with its single start event synthesized).
+     *
+     * @remarks
+     * The construct BPMN has for a safety net: it has no incoming flow, and it
+     * catches what nothing closer to the failing element caught. Distinct from a
+     * boundary handler (`.onError()` on one activity), which guards one element; this
+     * guards the whole container it sits in, so where it sits is what it guards — put
+     * it inside a multi-instance sub-process to fail one iteration rather than the
+     * whole run.
+     *
+     * Its body is written in order: elements chain from the synthesized start, and
+     * branch with `.choose()` / `.fork()` / `.race()`. Every path must end — with an
+     * end event or an explicit `.sequenceFlow()` off its last element — because an
+     * event sub-process has nowhere else to go.
+     *
+     * @example
+     * **A central failure net that classifies on the error it caught**
+     * ```ts
+     * bpmn('payroll')
+     *   .var('outcome', 'string', { default: 'RUNNING' })
+     *   .startEvent('start')
+     *   .scriptTask('calculate', { script: 'return { ok: true };' })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'calculate')
+     *   .sequenceFlow('calculate', 'done')
+     *   .eventSubProcess('failures', { error: true, name: 'Failure net' }, (h) =>
+     *     h.choose('kind', [
+     *       {
+     *         // The start captures the error into `vars.Error` by default (`errorVar`).
+     *         when: '=js:String(vars.Error.code).indexOf("DATA") >= 0',
+     *         label: 'Bad data',
+     *         body: (b) => b.task('flagData', { set: { outcome: 'FAILED_BAD_DATA' } }).endEvent('badData', { name: 'Bad data handled' }),
+     *       },
+     *       {
+     *         otherwise: true,
+     *         label: 'Outage',
+     *         body: (b) => b.task('flagOutage', { set: { outcome: 'FAILED_OUTAGE' } }).endEvent('outage', { name: 'Outage escalated' }),
+     *       },
+     *     ]),
+     *   )
+     *   .build();
+     * ```
+     *
+     * @param id - The sub-process's element id. The start event is `<id>_start` unless `startId` says otherwise.
+     * @param opts - What starts it — exactly one of `error` / `message` / `timer` — and the rest of {@link EventSubProcessOpts}.
+     * @param fn - Receives the body builder; elements chain in the order they are written.
+     * @returns This builder, so calls chain.
+     * @throws If none or several of `error` / `message` / `timer` are given, if an error start
+     * is asked to be non-interrupting, or if a path in the body is left open.
+     */
+    eventSubProcess(id, opts, fn) {
+        const given = [opts.error !== undefined, opts.message !== undefined, opts.timer !== undefined].filter(Boolean).length;
+        if (given !== 1) {
+            throw new Error(`eventSubProcess "${id}" needs exactly one of { error, message, timer } — that is what starts it.`);
+        }
+        if (opts.error !== undefined && opts.interrupting === false) {
+            throw new Error(`eventSubProcess "${id}": an error start is always interrupting — the throw has already ended the scope it came from.`);
+        }
+        if (opts.errorVar !== undefined && opts.errorVar !== false && opts.error === undefined) {
+            throw new Error(`eventSubProcess "${id}": \`errorVar\` captures an error, so it needs \`error\`.`);
+        }
+        if (typeof opts.errorVar === 'string' && opts.startPayload !== undefined) {
+            throw new Error(`eventSubProcess "${id}": pass \`errorVar\` or \`startPayload\`, not both — both write the start event's output row.`);
+        }
+        // The capture row is on by default for an error start: without a declared `Error`
+        // the platform validator rejects every `vars.Error` read in the net. An explicit
+        // `startPayload` owns the row instead, and `errorVar: false` writes none.
+        const capture = opts.errorVar === false || opts.startPayload !== undefined
+            ? undefined
+            : (opts.errorVar ?? (opts.error !== undefined ? `${id}_Error` : undefined));
+        // The same collision one scope out: two error nets in one container, the platform's
+        // MULTIPLE_CATCH_ALL_ERROR_EVENT_SUBPROCESS / DUPLICATE_ERROR_EVENT_SUBPROCESS. The
+        // error name is interned once, so two nets naming one error share its ref and compare
+        // equal here.
+        if (opts.error !== undefined) {
+            const mine = toErrorDef(this._defs, opts.error, `eventSubProcess "${id}"`);
+            const mineRef = mine.type === 'error' ? mine.errorRef : undefined;
+            const clash = this._nodes.find((n) => {
+                if (n.kind !== 'subProcess' || n.triggeredByEvent !== true)
+                    return false;
+                const start = loneStart(n.nodes);
+                const other = start === undefined ? undefined : errorCaught(start);
+                return other !== undefined && other.catchAll === (mineRef === undefined) && other.ref === mineRef;
+            });
+            if (clash !== undefined) {
+                throw new Error(`eventSubProcess "${id}" catches the same error as "${clash.id}" in this scope ` +
+                    `(${mineRef === undefined ? 'both catch ANY error' : `both catch "${mineRef}"`}), so one of the ` +
+                    'two can never run. Catch a specific error in each net, or keep the one catch-all.');
+            }
+        }
+        const startId = opts.startId ?? `${id}_start`;
+        let event;
+        if (opts.error !== undefined)
+            event = toErrorDef(this._defs, opts.error, `eventSubProcess "${id}"`);
+        else if (opts.timer !== undefined)
+            event = { type: 'timer', timer: normTimer(opts.timer) };
+        else
+            event = { type: 'message', messageRef: this._defs.messageRef(opts.message) };
+        const sb = new SubProcessBuilder(this._defs, this._bindingRegistry, undefined, 'sequence', this._sugar);
+        sb._begin({
+            kind: 'startEvent',
+            id: startId,
+            name: opts.startName,
+            event,
+            payload: opts.startPayload ?? (capture !== undefined ? errorCapturePayload(capture, 'startEvent') : undefined),
+            interrupting: opts.interrupting === false ? false : undefined,
+        });
+        if (capture !== undefined)
+            this._sugar.autoVars.push({ id: capture, vars: sb._varsOf(), elementId: startId });
+        fn(sb);
+        sb._finishBody(`event sub-process "${id}"`);
+        return this.push(sb._buildNode(id, { name: opts.name, triggeredByEvent: true, tags: opts.tags, payload: opts.payload }));
+    }
+    // ── Branching by nesting ──
+    /**
+     * An exclusive decision whose arms are written in place — the splitting gateway,
+     * each arm's conditioned flow, the arm's elements and the rejoining gateway, from
+     * one call.
+     *
+     * @remarks
+     * Each arm has a `when` condition or is the single `otherwise` fallback, so an arm
+     * with no condition cannot be written, and the fallback is the gateway's default
+     * flow without anyone naming a flow id. Arms rejoin at the next element placed
+     * after the `choose`; a join gateway (`<id>_join`) is emitted only when more than
+     * one arm actually reaches it, so an arm that ends in an end event adds no join.
+     *
+     * Inside an arm, consecutive elements are wired in order, and an arm may nest
+     * further `choose` / `fork` / `race` calls, activities with boundary handlers, or
+     * `.goto()` to jump to an element written elsewhere. An arm with no body is an
+     * empty branch straight to the continuation.
+     *
+     * @example
+     * **Approve or reject, then carry on**
+     * ```ts
+     * bpmn('review')
+     *   .var('action', 'string')
+     *   .var('status', 'string')
+     *   .startEvent('start')
+     *   .task('decide', { set: { action: 'Approved' } })
+     *   .choose('approved', [
+     *     { when: '=vars.action == "Approved"', label: 'Yes', body: (b) => b.task('post', { set: { status: 'posted' } }) },
+     *     { otherwise: true, label: 'No', body: (b) => b.task('reject', { set: { status: 'rejected' } }) },
+     *   ])
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'decide')
+     *   .sequenceFlow('decide', 'approved')
+     *   .build();
+     * ```
+     *
+     * @param id - The splitting gateway's element id; the join, when emitted, is `<id>_join`.
+     * @param arms - The arms — see {@link ChooseArm}.
+     * @param opts - `name`, `inclusive` for an inclusive gateway, and `join` to name the join gateway.
+     * @returns This builder, so calls chain.
+     * @throws If there are no arms, more than one `otherwise`, or more than one empty arm.
+     */
+    choose(id, arms, opts = {}) {
+        if (!arms.length)
+            throw new Error(`choose "${id}" has no arms.`);
+        if (arms.filter((a) => a.otherwise).length > 1) {
+            throw new Error(`choose "${id}" has more than one \`otherwise\` arm; at most one.`);
+        }
+        for (const a of arms) {
+            if (a.when === undefined && !a.otherwise)
+                throw new Error(`choose "${id}": every arm needs \`when\` or \`otherwise: true\`.`);
+        }
+        const kind = opts.inclusive ? 'inclusiveGateway' : 'exclusiveGateway';
+        const split = { kind, id, name: opts.name };
+        return this.branch(split, kind, arms.map((a, i) => ({
+            entry: {
+                source: id,
+                condition: a.when,
+                name: a.label,
+                defaultOf: a.otherwise ? split : undefined,
+                origin: `arm ${i + 1}${a.label ? ` ("${a.label}")` : ''} of choose "${id}"`,
+            },
+            body: a.body,
+        })), `choose "${id}"`, false, opts.join);
+    }
+    /**
+     * A parallel split whose arms are written in place: every arm runs, and they
+     * rejoin through a parallel join (`<id>_join`) before the next element.
+     *
+     * @example
+     * **Two lookups at once, then one summary**
+     * ```ts
+     * bpmn('enrich')
+     *   .startEvent('start')
+     *   .fork('gather', [
+     *     (b) => b.http('poLookup', { method: 'GET', url: 'https://erp.example.com/po/1' }),
+     *     (b) => b.http('vendorLookup', { method: 'GET', url: 'https://erp.example.com/vendor/1' }),
+     *   ])
+     *   .scriptTask('summarise', { script: 'return { ok: true };' })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'gather')
+     *   .sequenceFlow('summarise', 'done')
+     *   .build();
+     * ```
+     *
+     * @param id - The splitting gateway's element id; the join is `<id>_join`.
+     * @param arms - One body per parallel arm.
+     * @param opts - `name` for the splitting gateway, and `join` to name the join gateway.
+     * @returns This builder, so calls chain.
+     */
+    fork(id, arms, opts = {}) {
+        if (!arms.length)
+            throw new Error(`fork "${id}" has no arms.`);
+        return this.branch({ kind: 'parallelGateway', id, name: opts.name }, 'parallelGateway', arms.map((body, i) => ({ entry: { source: id, origin: `arm ${i + 1} of fork "${id}"` }, body })), `fork "${id}"`, false, opts.join);
+    }
+    /**
+     * An event-based gateway whose arms are written in place: each arm begins with
+     * something to wait for, the first to happen wins, and the rest are cancelled.
+     *
+     * @remarks
+     * An arm must begin with an `intermediateCatchEvent` (message or timer), a
+     * `receiveMessage`, or a `waitForEvent` — that is what the gateway waits on, and
+     * the builder refuses anything else in first position. Arms rejoin through an
+     * exclusive join (`<id>_join`) when more than one falls through.
+     *
+     * @example
+     * **A reply, or a three-day timeout**
+     * ```ts
+     * bpmn('vendor')
+     *   .startEvent('start')
+     *   .race('waitForEither', [
+     *     (b) => b.intermediateCatchEvent('reply', { message: 'VendorReplied' }),
+     *     (b) => b.intermediateCatchEvent('timeout', { timer: 'P3D' }).endEvent('gaveUp', { name: 'No reply' }),
+     *   ])
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'waitForEither')
+     *   .build();
+     * ```
+     *
+     * @param id - The gateway's element id; the join, when emitted, is `<id>_join`.
+     * @param arms - One body per alternative, each beginning with the event it waits for.
+     * @param opts - `name` for the gateway, and `join` to name the join gateway.
+     * @returns This builder, so calls chain.
+     * @throws If an arm does not begin with something that waits.
+     */
+    race(id, arms, opts = {}) {
+        if (!arms.length)
+            throw new Error(`race "${id}" has no arms.`);
+        return this.branch({ kind: 'eventBasedGateway', id, name: opts.name }, 'exclusiveGateway', arms.map((body, i) => ({ entry: { source: id, origin: `arm ${i + 1} of race "${id}"` }, body })), `race "${id}"`, true, opts.join);
     }
     // ── Flows ──
+    /**
+     * Give the edges the nesting constructs IMPLY the ids you choose.
+     *
+     * @remarks
+     * A construct's edges have no call of their own — you write `.choose()` or place two
+     * statements in a sequence scope, and the edge between them follows — so there is
+     * nowhere to name one, and its id is derived as `Flow_<source>_<target>`. That is
+     * fine for a new process and wrong for an edited one: a `.bpmn` that came from
+     * somewhere carries ids like `edge_zOoHdO`, and `uip maestro bpmn merge` keys every
+     * element by id, flows included. Re-derive them and the merge treats every flow as
+     * new, deletes the originals, and takes their diagram edges with them — and any
+     * gateway `default` preserved from the original is left naming an id that no longer
+     * exists, which `uip maestro bpmn validate` then rejects.
+     *
+     * So this is how a decompiled process keeps the ids it arrived with while still
+     * being written in the constructs. `bpmn decompile --style nested` emits one call
+     * listing every implied edge whose original id is not the derived one.
+     *
+     * Only implied edges: an explicit `.sequenceFlow()` already takes an `id`, and a
+     * pair listed here that no implied edge ever connects is simply unused.
+     *
+     * @example
+     * **Keep an import's edge ids through a lift**
+     * ```ts
+     * bpmn('orders')
+     *   .var('total', 'number', { default: 0 })
+     *   .flowIds([
+     *     { source: 'Gw_1', target: 'Review', id: 'edge_zOoHdO' },
+     *     { source: 'Gw_1', target: 'Pay', id: 'edge_Kp2mQ1' },
+     *   ])
+     *   .startEvent('Start_1')
+     *   .choose('Gw_1', [
+     *     { when: '=vars.total > 1000', body: (b) => b.task('Review').goto('Done') },
+     *     { otherwise: true, body: (b) => b.task('Pay').goto('Done') },
+     *   ])
+     *   .endEvent('Done')
+     *   .sequenceFlow('Start_1', 'Gw_1')
+     *   .build();
+     * ```
+     *
+     * @param entries - The edges to pin, by their endpoints.
+     * @returns This builder, so calls chain.
+     */
+    flowIds(entries) {
+        for (const e of entries)
+            this._sugar.pinnedFlowIds.set(`${e.source}\u0000${e.target}`, e.id);
+        return this;
+    }
     /**
      * A sequence flow from `source` to `target` (1-1 with `bpmn:sequenceFlow`).
      *
@@ -1090,13 +2032,35 @@ class ScopeBuilder {
      * @returns This builder, so calls chain.
      */
     sequenceFlow(source, target, opts = {}) {
-        this._flows.push({
-            id: opts.id ?? `Flow_${source}_${target}`,
-            source,
-            target,
-            name: opts.name,
-            condition: opts.condition,
-        });
+        // An explicit flow out of an element whose exit is still open is how that path
+        // LEAVES — the same thing `.goto()` says, for a source named rather than implied.
+        // Without this the exit stayed open and `continueTo` silently dropped it (its
+        // source now has an explicit outgoing flow), so the next element was placed with
+        // no incoming edge at all and nothing reported it. Dropping the exit here means
+        // the next element meets the existing "unreachable" refusal instead, which says
+        // what is wrong at the call site that caused it.
+        //
+        // Only a PLAIN exit: one carrying a condition or a gateway default is an edge in
+        // its own right and is always written.
+        const openIndex = this._open.findIndex((e) => e.source === source && e.condition === undefined && e.defaultOf === undefined);
+        if (this._mode === 'sequence' && openIndex !== -1)
+            this._open.splice(openIndex, 1);
+        const id = opts.id ?? `Flow_${source}_${target}`;
+        // An explicit flow that restates one the builder implied — a handler's tail
+        // wired to the statement it was going to reach anyway — is the same edge, and
+        // becomes the author's: their label and condition win, and it no longer counts
+        // as implied.
+        const implied = this._flows.find((f) => f.id === id && f.source === source && f.target === target && this._sugar.impliedFlowIds.has(f.id));
+        if (implied) {
+            if (opts.name !== undefined)
+                implied.name = opts.name;
+            if (opts.condition !== undefined)
+                implied.condition = opts.condition;
+            delete implied.implied;
+            this._sugar.impliedFlowIds.delete(id);
+            return this;
+        }
+        this._flows.push({ id, source, target, name: opts.name, condition: opts.condition });
         return this;
     }
     // ── Variables ──
@@ -1185,9 +2149,52 @@ export function typedNodeDeclaredVars(n) {
     // Spelled-out rows REPLACE the derived pair, so they are the whole answer.
     if (n.outputRows)
         return n.outputRows.map((r) => r.var).filter((v) => v !== undefined);
-    const v = typedNodeOutputVar(n.id, n.type, n.outputVar);
+    const v = typedNodeOutputVar(n.id, n.type, n.outputVar, n.spec);
     return [...(v ? [v] : []), ...Object.keys(n.outputs ?? {})];
 }
+/**
+ * Fill in `activity` on a connector task from the `operation` beside it.
+ *
+ * `Intsvc.ActivityExecution` must carry `activity` — the platform's required-field
+ * rule reports `EMPTY_REQUIRED_FIELD` without it and the artifact is refused. The two
+ * fields name the same thing: the SDK's own connector emitter writes
+ * `op.name ?? op.objectName ?? n.action` into BOTH, so they are never independently
+ * chosen, and `connector.ts` calls `activity` "the primary-key required field (the
+ * selected op identity)".
+ *
+ * So a hand-rolled `.activity()` that sets `operation` and not `activity` has already
+ * said which operation it means, and making the author say it twice buys nothing. This
+ * is the same shape as the `operation` field's own history, recorded in `connector.ts`:
+ * every connector task the SDK emitted was rejected until the emitter supplied it.
+ *
+ * Only the absent case is filled. An author (or an imported artifact) that states
+ * `activity` explicitly keeps what it stated, even where the two differ.
+ */
+function operationToBorrow(type, context, rows) {
+    if (type !== 'Intsvc.ActivityExecution')
+        return undefined;
+    // Context reaches a node two ways and either spelling can carry either field, so
+    // both are read before deciding anything is missing — the same rule `check` applies.
+    const stated = (name) => context[name] !== undefined ? context[name] : rows?.find((r) => r.name === name)?.value;
+    if (stated('activity') !== undefined)
+        return undefined;
+    const operation = stated('operation');
+    return typeof operation === 'string' && operation !== '' ? operation : undefined;
+}
+function defaultActivityIdentity(type, context, rows) {
+    const operation = operationToBorrow(type, context, rows);
+    // When the node spells its context out as rows, the filled-in field belongs beside
+    // them rather than in a record the emitter would write separately.
+    if (operation === undefined || rows?.length)
+        return context;
+    return { ...context, activity: operation };
+}
+function defaultActivityIdentityRows(type, context, rows) {
+    const operation = operationToBorrow(type, context, rows);
+    if (operation === undefined || !rows?.length)
+        return rows;
+    return [...rows, { name: 'activity', type: 'string', value: operation }];
+}
 /**
  * Every variable name a node DECLARES by writing to it — the platform counts a
  * node's output `var` as a declaration, so a downstream `=vars.<name>` resolves
@@ -1214,8 +2221,49 @@ export function nodeDeclaredVars(n) {
 }
 /** A sub-process body: the same graph methods, plus an internal node builder. */
 export class SubProcessBuilder extends ScopeBuilder {
+    /**
+     * Open an event sub-process body on its synthesized start event.
+     *
+     * @param start - The start event node.
+     * @internal
+     */
+    _begin(start) {
+        this._nodes.push(start);
+        this._open = [{ source: start.id, origin: `the start event "${start.id}"` }];
+        this._started = true;
+        this._synthesizedStart = start.id;
+    }
+    /**
+     * Close a body written in order: every path in it must have ended.
+     *
+     * @param what - The scope, for the message.
+     * @internal
+     */
+    _finishBody(what) {
+        this.closeScope(what);
+    }
     /** @internal */
     _buildNode(id, opts) {
+        // An EVENT sub-process is started by its own start event, so that start must carry a
+        // definition; a plain sub-process is started by an incoming flow, so its start must
+        // carry none. The platform rejects each the other way round
+        // (START_EVENT_WITHOUT_DEFINITION_IN_EVENT_SUBPROCESS,
+        // START_EVENT_WITH_DEFINITION_IN_SUBPROCESS). `.eventSubProcess()` always synthesizes
+        // a definition, so this only fires on the hand-rolled `{ triggeredByEvent: true }`
+        // form and on a plain `.subProcess()` whose start was given one.
+        for (const n of this._nodes) {
+            if (n.kind !== 'startEvent')
+                continue;
+            const hasDefinition = n.event !== undefined || n.trigger !== undefined;
+            if (opts.triggeredByEvent === true && !hasDefinition) {
+                throw new Error(`sub-process "${id}" is \`triggeredByEvent\`, so its start event "${n.id}" needs the event that starts it — ` +
+                    'an `error`, `message` or `timer`. `.eventSubProcess(id, { error: true }, fn)` writes that start for you.');
+            }
+            if (opts.triggeredByEvent !== true && hasDefinition) {
+                throw new Error(`sub-process "${id}" is entered by an incoming flow, so its start event "${n.id}" must not carry an event ` +
+                    'definition. Drop it, or make this an event sub-process with `.eventSubProcess()`.');
+            }
+        }
         return {
             kind: 'subProcess',
             id,
@@ -1232,6 +2280,149 @@ export class SubProcessBuilder extends ScopeBuilder {
         };
     }
 }
+/**
+ * One arm of a `choose` / `fork` / `race`, or one boundary handler's path: the same
+ * graph methods as any scope, written INTO the enclosing scope, with consecutive
+ * elements wired in order.
+ *
+ * @remarks
+ * An arm creates no BPMN scope of its own — its elements and flows belong to the
+ * scope the construct was written in, and variables declared here are that scope's
+ * — so an explicit `.sequenceFlow()` may reach any element of that scope, and
+ * `.goto()` jumps to one without leaving the nesting. Its path ends with an end
+ * event or `.goto()`, or falls through to whatever follows the construct.
+ *
+ * Inside an arm, branch with `.choose()` / `.fork()` / `.race()`; a bare gateway is
+ * refused, because its outgoing flows cannot be implied.
+ */
+export class PathBuilder extends ScopeBuilder {
+    /** @internal The first element placed — what a `race` arm waits on. */
+    _first;
+    /**
+     * @param defs - The process's message/error declarations.
+     * @param bindings - The process's bindings.
+     * @param storage - The enclosing scope's arrays, which this arm writes into.
+     * @param sugar - Process-wide bookkeeping for the nesting sugar.
+     * @param entry - The edge(s) this arm continues from.
+     * @param scopeMode - The mode of the real scope the arm writes into, for a nested `.subProcess()` to inherit.
+     * @internal
+     */
+    constructor(defs, bindings, storage, sugar, entry, scopeMode) {
+        super(defs, bindings, storage, 'sequence', sugar);
+        this._isArm = true;
+        this._scopeMode = scopeMode;
+        this._open = entry;
+        this._started = true;
+    }
+    /** @internal */
+    place(node, viaSugar = false) {
+        super.place(node, viaSugar);
+        this._first ??= node;
+    }
+    /**
+     * Leave this arm for an element written elsewhere — a loop back to an earlier
+     * step, a jump into another arm, a shared exit — writing the edge without leaving
+     * the nesting. Nothing may follow it in the arm.
+     *
+     * @example
+     * **Retry from the top when the check fails**
+     * ```ts
+     * bpmn('retrying')
+     *   .var('ok', 'boolean')
+     *   .startEvent('start')
+     *   .scriptTask('attempt', { script: 'return { ok: true };', outputs: { ok: '=result.ok' } })
+     *   .choose('worked', [
+     *     { when: '=vars.ok == true', body: (b) => b.endEvent('done') },
+     *     { otherwise: true, body: (b) => b.goto('attempt') },
+     *   ])
+     *   .sequenceFlow('start', 'attempt')
+     *   .sequenceFlow('attempt', 'worked')
+     *   .build();
+     * ```
+     *
+     * @param target - The id of the element to continue at.
+     * @returns This builder; nothing more may be placed on this arm.
+     */
+    goto(target) {
+        if (this._closedBy !== undefined)
+            throw new Error(`.goto("${target}") follows ${this._closedBy}; an arm leaves once.`);
+        for (const exit of this._open)
+            this.writeImpliedFlow(exit, target);
+        this._open = [];
+        this._closedBy = `.goto("${target}")`;
+        return this;
+    }
+    /**
+     * Finish the arm and hand its open ends back to the construct that owns it.
+     *
+     * @returns The exits still open — empty when every path ended.
+     * @internal
+     */
+    _finish() {
+        return this._open;
+    }
+}
+/**
+ * The boundary events of one activity, declared on the activity itself — what the
+ * body callback every activity method accepts receives.
+ *
+ * @remarks
+ * `attachedTo` is the receiver: a handler declared here is attached to the activity
+ * whose body it is written in, so a boundary event on nothing, or on a gateway,
+ * cannot be written. Each handler's path is written in place, in order, and
+ * continues as {@link TimerHandlerOpts.interrupting} describes: an interrupting
+ * handler rejoins at the statement after the activity, a non-interrupting one must
+ * end on its own.
+ *
+ * @example
+ * **A human task with a reminder and a failure exit**
+ * ```ts
+ * bpmn('approval')
+ *   .var('reminded', 'string')
+ *   .startEvent('start')
+ *   .humanTask('approve', { app: 'InvoiceApproval', actions: ['Approve', 'Reject'] }, (t) => {
+ *     t.onTimer('PT1H', { interrupting: false }, (b) =>
+ *       b.task('remind', { set: { reminded: 'true' } }).endEvent('reminded'));
+ *     t.onError((b) => b.endEvent('failed', { name: 'Approval failed' }));
+ *   })
+ *   .endEvent('done')
+ *   .sequenceFlow('start', 'approve')
+ *   .sequenceFlow('approve', 'done')
+ *   .build();
+ * ```
+ */
+export class ActivityBuilder {
+    scope;
+    activity;
+    /**
+     * @param scope - The scope the activity was placed in.
+     * @param activity - The activity's id.
+     * @internal
+     */
+    constructor(scope, activity) {
+        this.scope = scope;
+        this.activity = activity;
+    }
+    onError(a, b, c) {
+        const error = a === undefined || typeof a === 'function' ? true : a;
+        const opts = b !== undefined && typeof b === 'object' ? b : {};
+        const body = typeof a === 'function' ? a : typeof b === 'function' ? b : c;
+        this.scope._attach(this.activity, 'onError', { event: toErrorDef(this.scope._defsOf(), error, `.onError() on "${this.activity}"`), interrupting: true, opts }, body);
+        return this;
+    }
+    onTimer(timer, b, c) {
+        const opts = b !== undefined && typeof b === 'object' ? b : {};
+        const body = typeof b === 'function' ? b : c;
+        this.scope._attach(this.activity, 'onTimer', { event: { type: 'timer', timer: normTimer(timer) }, interrupting: opts.interrupting ?? true, opts }, body);
+        return this;
+    }
+    onMessage(message, b, c) {
+        const opts = b !== undefined && typeof b === 'object' ? b : {};
+        const body = typeof b === 'function' ? b : c;
+        this.scope._attach(this.activity, 'onMessage', { event: { type: 'message', messageRef: this.scope._defsOf().messageRef(message) }, interrupting: opts.interrupting ?? true, opts }, body);
+        return this;
+    }
+}
 // ─── Top-level process builder ────────────────────────────────────────────────
 /**
  * The top-level process builder `bpmn()` returns — every graph method of the
@@ -1377,7 +2568,10 @@ export class BpmnBuilder extends ScopeBuilder {
             propertyAttribute: opts.propertyAttribute ?? 'value',
             resourceSubType: opts.resourceSubType,
             default: opts.value,
-            resourceKey: opts.resourceKey ?? opts.value,
+            // Left unset when not given, rather than collapsed onto `value`: the serializer
+            // fills it — with the companion connection's key for a `folderKey` binding, and
+            // with `value` for every other — see `folderCompanionKeys` in serialize.ts.
+            resourceKey: opts.resourceKey,
         });
         return this;
     }
@@ -1387,6 +2581,57 @@ export class BpmnBuilder extends ScopeBuilder {
      * @returns The built process — its elements, flows and variables.
      */
     build() {
+        this.closeScope('the process');
+        // A variable an `errorVar` asked for, declared the way the product declares one
+        // — unless the author declared that id themselves, anywhere in the document.
+        const declared = new Set();
+        const collect = (nodes, vars) => {
+            for (const v of vars)
+                declared.add(v.id);
+            for (const n of nodes)
+                if (n.kind === 'subProcess')
+                    collect(n.nodes, n.variables);
+        };
+        collect(this._nodes, this._vars);
+        // One `errorVar` id is ONE declaration, wherever the handlers asking for it sit.
+        // A variable id is unique across the whole document — two `uipath:inputOutput`
+        // elements sharing one id is DUPLICATE_DOCUMENT_ID, and the XML parser drops the
+        // second — so "declare it again in the other scope" is not available.
+        //
+        // Declared once and scoped to whichever boundary came first, a second handler's
+        // `=Error` row wrote a variable belonging to an element it has nothing to do with.
+        // So a reused id widens the declaration off that boundary, and when the handlers
+        // asking for it are in different scopes the declaration moves to the root, which
+        // is the one scope all of them can see.
+        const autoDecls = new Map();
+        for (const auto of this._sugar.autoVars) {
+            const prior = autoDecls.get(auto.id);
+            if (prior) {
+                // Shared: no longer one boundary's private variable.
+                prior.decl.elementId = undefined;
+                if (prior.vars !== auto.vars && prior.vars !== this._vars) {
+                    // Asked for from two scopes: hoist the single declaration to the root, the
+                    // only scope in view of both.
+                    prior.vars.splice(prior.vars.indexOf(prior.decl), 1);
+                    this._vars.push(prior.decl);
+                    prior.vars = this._vars;
+                }
+                continue;
+            }
+            // An id the AUTHOR declared anywhere stays theirs, scoped where they put it.
+            if (declared.has(auto.id))
+                continue;
+            const decl = {
+                id: auto.id,
+                name: 'Error',
+                type: 'jsonSchema',
+                direction: 'inputOutput',
+                elementId: auto.elementId,
+                schema: errorSchema,
+            };
+            auto.vars.push(decl);
+            autoDecls.set(auto.id, { decl, vars: auto.vars });
+        }
         const built = {
             id: this._id,
             name: this._name,