@uipath/maestro-builder-sdk 5.2.0

package/dist/bpmn/bpmn-sdk.js

@@ -0,0 +1,1476 @@
+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';
+export { BpmnBuildError } from './bpmn-expr-check.js';
+function normTimer(t) {
+    return typeof t === 'string' ? { duration: t } : t;
+}
+// ─── Definitions registry (shared across the top process + sub-processes) ─────
+/**
+ * Collects `uipath:binding` declarations, de-duped by id.
+ *
+ * Shared with every scope rather than living on the top-level builder, because a
+ * typed node can NEED a binding — `Orchestrator.StartAgentJob` requires its
+ * process and folder to be `=bindings.<id>` references — and such a node can be
+ * authored inside a sub-process. Same reasoning as {@link DefinitionsRegistry}.
+ */
+class BindingsRegistry {
+    /** Every declared binding, in declaration order — `BuiltBpmn.bindings`. */
+    bindings = [];
+    /**
+     * Declare once and keep the FIRST declaration, so an author's own `.binding()`
+     * wins over one a typed node would have derived.
+     *
+     * @param decl - The binding to declare.
+     * @returns The declaration in force for that id — the existing one on a collision.
+     */
+    declare(decl) {
+        const existing = this.bindings.find((b) => b.id === decl.id);
+        if (existing)
+            return existing;
+        this.bindings.push(decl);
+        return decl;
+    }
+    /**
+     * @param id - The binding id to look for.
+     * @returns Whether that id is already declared.
+     */
+    has(id) {
+        return this.bindings.some((b) => b.id === id);
+    }
+}
+/** Collects definitions-level message/error declarations, de-duped by name. */
+class DefinitionsRegistry {
+    /** Every declared message, in declaration order — `BuiltBpmn.messages`. */
+    messages = [];
+    /** Every declared error, in declaration order — `BuiltBpmn.errors`. */
+    errors = [];
+    messageByName = new Map();
+    errorByName = new Map();
+    /**
+    * Declare a message once and reuse it, returning the id events reference.
+    *
+    * @param name - The message's name.
+    * @returns The message id to put in an event's definition.
+    */
+    messageRef(name) {
+        const existing = this.messageByName.get(name);
+        if (existing)
+            return existing;
+        const id = uniqueId('Message', this.messageByName.size);
+        this.messageByName.set(name, id);
+        this.messages.push({ id, name });
+        return id;
+    }
+    /**
+    * Declare an error once and reuse it, returning the id events reference.
+    *
+    * @param name - The error's name.
+    * @param code - The error code the runtime matches on.
+    * @returns The error id to put in an event's definition.
+    */
+    errorRef(name, code) {
+        const existing = this.errorByName.get(name);
+        if (existing)
+            return existing;
+        const id = uniqueId('Error', this.errorByName.size);
+        this.errorByName.set(name, id);
+        this.errors.push({ id, name, code });
+        return id;
+    }
+}
+function uniqueId(prefix, index) {
+    return `${prefix}_${index + 1}`;
+}
+/**
+ * Resolve an end/boundary error option into an error definition.
+ *
+ * **The code defaults to the name**, and must: the code is what the runtime
+ * matches a failure against, and `uip maestro bpmn validate` rejects an error
+ * boundary whose referenced error has none (`ERROR_BOUNDARY_EVENT_REQUIRES_ERROR_CODE`).
+ * Omitting it emitted `<bpmn:error name="Boom"/>` with no code, which failed
+ * validation and — because the runtime then falls back to the SYNTHESIZED
+ * 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) {
+    // `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;
+    return { type: 'error', errorRef: defs.errorRef(spec.name, spec.code ?? spec.name) };
+}
+// ─── Graph scope (shared by the top process and sub-processes) ────────────────
+/**
+ * The set of node/flow/variable methods common to the process root and every
+ * sub-process. Methods return `this`, so fluent chaining preserves the concrete
+ * builder type (top-level or sub-process).
+ */
+class ScopeBuilder {
+    /** @internal */
+    _nodes = [];
+    /** @internal */
+    _flows = [];
+    /** @internal */
+    _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.
+    /** @internal */
+    _defs;
+    /** @internal */
+    _bindingRegistry;
+    /**
+     * @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.
+     * @returns The scope builder.
+     */
+    constructor(defs, bindings) {
+        this._defs = defs;
+        this._bindingRegistry = bindings;
+    }
+    push(node) {
+        this._nodes.push(node);
+        return this;
+    }
+    // ── Events ──
+    /**
+     * A start event (authorable definitions: none / message / timer).
+     *
+     * @remarks
+     * With no definition at all, the process is started by a CALLER — an API call,
+     * `uip maestro`, a parent process, or an Orchestrator trigger configured against
+     * the deployed process. `timer` moves the schedule INTO the artifact, where the
+     * platform's scheduler reads it. `trigger` additionally declares the timed start
+     * as a typed platform trigger — see {@link StartOpts.trigger}.
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - `name`, the definition — message or timer — and `trigger`.
+     * @returns This builder, so calls chain.
+     * @throws If `trigger` is set without `timer`, which would emit a trigger with no
+     * schedule that every offline gate still calls valid.
+     */
+    startEvent(id, opts = {}) {
+        if (opts.trigger !== undefined && opts.timer === undefined) {
+            throw new Error(`startEvent "${id}": \`trigger\` needs \`timer\` — the schedule lives in the ` +
+                `bpmn:timerEventDefinition, not in the trigger extension, so a trigger without one emits an ` +
+                `empty definition and fires never. \`uip maestro bpmn validate\` reports that as Valid.`);
+        }
+        if (opts.trigger !== undefined && opts.payload !== undefined) {
+            throw new Error(`startEvent "${id}": \`trigger\` and \`payload\` both write the event's extension element; pass one.`);
+        }
+        return this.push({
+            kind: 'startEvent',
+            id,
+            name: opts.name,
+            payload: opts.payload,
+            // `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),
+            trigger: opts.trigger === undefined
+                ? undefined
+                : { type: 'Intsvc.TimerTrigger', outputVar: opts.trigger === true ? undefined : opts.trigger.outputVar },
+        });
+    }
+    /**
+     * An end event (authorable definitions: none / message / error / terminate).
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - `name`, and the definition — message, error, or terminate.
+     * @returns This builder, so calls chain.
+     */
+    endEvent(id, opts = {}) {
+        let event;
+        if (opts.terminate)
+            event = { type: 'terminate' };
+        else if (opts.error !== undefined)
+            event = toErrorDef(this._defs, opts.error);
+        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 });
+    }
+    /**
+     * An intermediate catch event (authorable: message / timer).
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - `name`, and the definition — message or timer.
+     * @returns This builder, so calls chain.
+     */
+    intermediateCatchEvent(id, opts = {}) {
+        return this.push({
+            kind: 'intermediateCatchEvent',
+            id,
+            name: opts.name,
+            event: this.startCatchDef(opts),
+            payload: opts.payload,
+        });
+    }
+    /**
+     * An intermediate throw event (authorable: none / message).
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - `name`, and the definition — none or message.
+     * @returns This builder, so calls chain.
+     */
+    intermediateThrowEvent(id, opts = {}) {
+        const event = opts.message !== undefined ? { type: 'message', messageRef: this._defs.messageRef(opts.message) } : undefined;
+        return this.push({ kind: 'intermediateThrowEvent', id, name: opts.name, event, payload: opts.payload });
+    }
+    /**
+     * A boundary event on an activity (authorable: message / timer / error).
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - The activity it attaches to, whether it interrupts, and the definition — message, timer, or error.
+     * @returns This builder, so calls chain.
+     */
+    boundaryEvent(id, opts) {
+        let event;
+        if (opts.error !== undefined)
+            event = toErrorDef(this._defs, opts.error);
+        else if (opts.timer !== undefined)
+            event = { type: 'timer', timer: normTimer(opts.timer) };
+        else if (opts.message !== undefined)
+            event = { type: 'message', messageRef: this._defs.messageRef(opts.message) };
+        else
+            throw new Error(`boundaryEvent "${id}" needs one of { message, timer, error }.`);
+        return this.push({
+            kind: 'boundaryEvent',
+            id,
+            name: opts.name,
+            attachedTo: opts.attachedTo,
+            cancelActivity: opts.cancelActivity ?? true,
+            event,
+            payload: opts.payload,
+        });
+    }
+    startCatchDef(opts) {
+        if (opts.timer !== undefined)
+            return { type: 'timer', timer: normTimer(opts.timer) };
+        if (opts.message !== undefined)
+            return { type: 'message', messageRef: this._defs.messageRef(opts.message) };
+        return undefined;
+    }
+    // ── Gateways ──
+    /**
+    * An exclusive gateway — exactly one outgoing flow is taken (`bpmn:exclusiveGateway`).
+    *
+    * @param id - The element id, unique in the process and used by `sequenceFlow`.
+    * @param opts - `name`, and the `default` flow taken when no condition matches.
+    * @returns This builder, so calls chain.
+    */
+    exclusiveGateway(id, opts = {}) {
+        return this.push({ kind: 'exclusiveGateway', id, name: opts.name, default: opts.default });
+    }
+    /**
+    * A parallel gateway — every outgoing flow is taken, and a join waits for every incoming one (`bpmn:parallelGateway`).
+    *
+    * @param id - The element id, unique in the process and used by `sequenceFlow`.
+    * @param opts - `name` for the gateway.
+    * @returns This builder, so calls chain.
+    */
+    parallelGateway(id, opts = {}) {
+        return this.push({ kind: 'parallelGateway', id, name: opts.name });
+    }
+    /**
+    * An inclusive gateway — every outgoing flow whose condition holds is taken (`bpmn:inclusiveGateway`).
+    *
+    * @param id - The element id, unique in the process and used by `sequenceFlow`.
+    * @param opts - `name`, and the `default` flow taken when no condition matches.
+    * @returns This builder, so calls chain.
+    */
+    inclusiveGateway(id, opts = {}) {
+        return this.push({ kind: 'inclusiveGateway', id, name: opts.name, default: opts.default });
+    }
+    /**
+    * An event-based gateway — the first of the events it leads to wins, and the rest are cancelled (`bpmn:eventBasedGateway`).
+    *
+    * @param id - The element id, unique in the process and used by `sequenceFlow`.
+    * @param opts - `name` for the gateway.
+    * @returns This builder, so calls chain.
+    */
+    eventBasedGateway(id, opts = {}) {
+        return this.push({ kind: 'eventBasedGateway', id, name: opts.name });
+    }
+    // ── Tasks ──
+    /**
+     * A script task (Jint JavaScript body + input/output mappings).
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - The Jint JavaScript `script`, and its input/output mappings.
+     * @returns This builder, so calls chain.
+     */
+    scriptTask(id, opts) {
+        return this.push({
+            kind: 'scriptTask',
+            id,
+            name: opts.name,
+            script: opts.script,
+            scriptFormat: opts.scriptFormat ?? 'JavaScript',
+            inputs: opts.inputs ?? {},
+            outputs: opts.outputs ?? {},
+            outputRows: opts.outputRows,
+            type: opts.type ?? 'BPMN.Variables',
+            inputSchema: opts.inputSchema,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    /**
+     * 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.
+     * @returns This builder, so calls chain.
+     */
+    task(id, opts = {}) {
+        return this.push({
+            kind: 'task',
+            id,
+            name: opts.name,
+            set: opts.set ?? {},
+            tags: opts.tags,
+            retry: opts.retry,
+            loop: opts.loop,
+            errorMapping: opts.errorMapping,
+        });
+    }
+    /**
+     * A task element carrying NO `uipath:*` payload — an abstract task, in BPMN's terms.
+     *
+     * @remarks
+     * The platform accepts all seven task elements bare, so an artifact can legitimately
+     * contain one, and until this existed the builder could not express any of them. That
+     * made such a file unimportable: `bpmn-decompile` refused six of the seven outright,
+     * and the seventh — `bpmn:task` — was worse, because it came back through `.task()`
+     * and silently GAINED a `BPMN.Variables` mapping it never had.
+     *
+     * Not the same as {@link ScopeBuilder.task}, which emits a `BPMN.Variables` mapping to
+     * assign variables, or {@link ScopeBuilder.humanTask}, which emits an `Actions.HITL`
+     * activity. Those are tasks that DO something; this is a task element that stands for
+     * work the process does not model — the shape a diagram-first tool writes before
+     * anything is wired up.
+     *
+     * @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`).
+     * @returns This builder, so calls chain.
+     *
+     * @example
+     * ```ts
+     * bpmn('review')
+     *   .startEvent('s')
+     *   .plainTask('approve', { name: 'Approve', element: 'bpmn:userTask' })
+     *   .endEvent('e')
+     * ```
+     */
+    plainTask(id, opts = {}) {
+        return this.push({
+            kind: 'plainTask',
+            id,
+            name: opts.name,
+            element: opts.element ?? 'bpmn:task',
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    connector(id, a, b, c, d) {
+        // 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);
+        if (spec.kind !== 'connector')
+            throw new Error('connector(): unexpected spec kind');
+        const bpmnOpts = (typeof a === 'string' ? d : c) ?? {};
+        return this.push({
+            kind: 'connector',
+            id,
+            name: bpmnOpts.name,
+            key: spec.key,
+            action: spec.action,
+            version: spec.version,
+            connection: spec.connection,
+            folder: spec.folder,
+            object: spec.object,
+            inputs: spec.inputs,
+            outputVar: bpmnOpts.outputVar,
+            skipCondition: bpmnOpts.skipCondition,
+            retry: bpmnOpts.retry,
+            loop: bpmnOpts.loop,
+        });
+    }
+    /**
+     * An **HTTP request** service task (`bpmn:sendTask` +
+     * `uipath:activity` / `Intsvc.UnifiedHttpRequest`).
+     *
+     * @remarks
+     * The first registry-backed typed node (`docs/BPMN_COVERAGE_DESIGN.md` Phase 3).
+     * Its wire shape — element, tag, context fields, output row — comes from the
+     * committed registry snapshot rather than hand-written emission, so it cannot
+     * drift from what the platform validates. Chosen as the pilot because it needs
+     * no tenant discovery (`RequiresDiscovery: No`) and the local engine dispatches
+     * it for real in `--mode live`.
+     *
+     * The response lands in `<id>_response` unless `outputVar` says otherwise, and
+     * that variable is readable downstream as `=vars.<name>` with no `.var()`.
+     *
+     * @example
+     * ```ts
+     * bpmn('sync')
+     *   .var('body', 'object')
+     *   .startEvent('start')
+     *   .http('fetch', { method: 'GET', url: 'https://api.example.com/orders' })
+     *   .task('keep', { set: { body: '=js:vars.fetch_response' } })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'fetch')
+     *   .sequenceFlow('fetch', 'keep')
+     *   .sequenceFlow('keep', 'done')
+     *   .build();
+     * ```
+     *
+     * @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.
+     * @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({
+            kind: 'typed',
+            id,
+            name,
+            type: 'Intsvc.UnifiedHttpRequest',
+            // These three are `json` context fields, so they go through as VALUES — the
+            // emitter encodes a json field's body. This wrapper used to `JSON.stringify`
+            // them itself, working around an emitter that wrote `[object Object]` for
+            // anything but a string; now the generic `.activity()` path accepts the same
+            // values this one does.
+            context: {
+                method: method ?? 'GET',
+                url,
+                ...(headers !== undefined ? { headers } : {}),
+                ...(parameters !== undefined ? { parameters } : {}),
+                ...(body !== undefined ? { body } : {}),
+            },
+            inputs: {},
+            outputs,
+            outputVar,
+            skipCondition,
+            retry,
+            loop,
+            errorMapping,
+        });
+    }
+    /**
+     * @internal Turn a literal into a binding reference where the platform demands
+     * one, declaring the binding on the author's behalf.
+     *
+     * `Orchestrator.StartAgentJob` requires its `name` and `folderPath` to be
+     * `=bindings.<id>` references AND requires those bindings to target
+     * `resource: process` with the right `propertyAttribute` — a literal is rejected,
+     * and so is a binding pointing at the wrong property. Both facts are in the
+     * registry snapshot, so the SDK can satisfy them from the plain value the author
+     * wrote instead of making them hand-build two bindings and get the attributes
+     * right. An author who passes an `=`-expression already knows what they want and
+     * is left alone.
+     */
+    bindRequiredContext(id, type, context) {
+        const out = { ...context };
+        for (const field of bindingRequiredFields(type)) {
+            const value = out[field.name];
+            if (typeof value !== 'string' || value.startsWith('='))
+                continue;
+            const bindingId = `${id}_${field.name}`;
+            this._bindingRegistry.declare({
+                id: bindingId,
+                name: field.displayName ?? field.name,
+                resource: field.bindingInfo?.resource ?? 'process',
+                propertyAttribute: field.bindingInfo?.propertyAttribute ?? field.name,
+                // A fact the registry omits and the validator enforces — see REGISTRY_GAPS.
+                resourceSubType: REGISTRY_GAPS[type]?.resourceSubType,
+                default: value,
+                resourceKey: value,
+            });
+            out[field.name] = `=bindings.${bindingId}`;
+        }
+        return out;
+    }
+    /** @internal Shared body of the Orchestrator process-invocation methods. */
+    orchestratorNode(id, type, opts) {
+        return this.push({
+            kind: 'typed',
+            id,
+            name: opts.name,
+            type,
+            context: this.bindRequiredContext(id, type, {
+                name: opts.process,
+                ...(opts.folder !== undefined ? { folderPath: opts.folder } : {}),
+                ...(opts.releaseKey !== undefined ? { releaseKey: opts.releaseKey } : {}),
+            }),
+            inputs: opts.input ?? {},
+            outputs: opts.outputs,
+            outputVar: opts.outputVar,
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    /**
+     * Start an **RPA process** and wait for it (`Orchestrator.StartJob`).
+     *
+     * @example
+     * ```ts
+     * bpmn('nightly')
+     *   .startEvent('start')
+     *   .startProcess('rpa', { process: 'InvoicePosting', folder: 'Finance', input: { batch: 42 } })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'rpa')
+     *   .sequenceFlow('rpa', 'done')
+     *   .build();
+     * ```
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - Which process, folder, and input arguments.
+     * @returns This builder, so calls chain.
+     */
+    startProcess(id, opts) {
+        return this.orchestratorNode(id, 'Orchestrator.StartJob', opts);
+    }
+    /**
+     * 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.
+     * @returns This builder, so calls chain.
+     */
+    startAgent(id, opts) {
+        return this.orchestratorNode(id, 'Orchestrator.StartAgentJob', opts);
+    }
+    /**
+     * Invoke an **agentic process** as a call activity
+     * (`Orchestrator.StartAgenticProcess`, or `…Async` when `async` is set).
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - Which process, folder, input arguments, and whether to wait.
+     * @returns This builder, so calls chain.
+     */
+    startAgenticProcess(id, opts) {
+        return this.orchestratorNode(id, opts.async ? 'Orchestrator.StartAgenticProcessAsync' : 'Orchestrator.StartAgenticProcess', opts);
+    }
+    /**
+     * Invoke a **case-management process** as a call activity
+     * (`Orchestrator.StartCaseMgmtProcess`, or `…Async` when `async` is set).
+     *
+     * @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.
+     * @returns This builder, so calls chain.
+     */
+    startCaseProcess(id, opts) {
+        return this.orchestratorNode(id, opts.async ? 'Orchestrator.StartCaseMgmtProcessAsync' : 'Orchestrator.StartCaseMgmtProcess', opts);
+    }
+    /**
+     * Execute an **API workflow**, fire-and-forget
+     * (`Orchestrator.ExecuteApiWorkflowAsync`).
+     *
+     * @remarks
+     * The registry offers only the async form, so there is nothing to wait on: the
+     * node maps back an error and nothing else.
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - Which workflow, folder, and input arguments.
+     * @returns This builder, so calls chain.
+     */
+    executeApiWorkflow(id, opts) {
+        return this.orchestratorNode(id, 'Orchestrator.ExecuteApiWorkflowAsync', opts);
+    }
+    /**
+     * Execute a **business rule** and wait for it (`Orchestrator.BusinessRules`, on a
+     * `bpmn:businessRuleTask`).
+     *
+     * @remarks
+     * **Not a DMN decision table**, despite the element and the label. The registry spec
+     * is an Orchestrator process invocation — `releaseKey`/`folderId`/`folderPath`/`name`
+     * plus `JobArguments`, `BindingPattern: businessRule` over `Resource: process` —
+     * structurally identical to {@link ScopeBuilder.startProcess}. `process` names a
+     * package whose Orchestrator process type is `BusinessRules`; whatever decision logic
+     * exists lives INSIDE that package, not in the `.bpmn`. So this is the job-start
+     * family's sixth member, not a rules subsystem, and it shares every option with it.
+     *
+     * Distinct from the Case SDK's `rule()`, which declares DNF lifecycle conditions
+     * (`case-entered`, `required-tasks-completed`, …) deciding when a stage enters or
+     * exits. The two share a word and nothing else.
+     *
+     * The extension type is marked `[Preview]` by the registry. That is a caveat on the
+     * SHAPE, not on this method: a preview extension type can gain or rename fields, and
+     * the snapshot refresh (`scripts/materialize-bpmn-registry.mjs`) is what would surface
+     * it as a data diff.
+     *
+     * @example
+     * ```ts
+     * bpmn('pricing')
+     *   .var('tier', 'string', { default: 'none' })
+     *   .startEvent('start')
+     *   .businessRule('tier', {
+     *     process: 'DiscountTier',
+     *     folder: 'Finance',
+     *     input: { amount: 4200 },
+     *     outputs: { tier: '=response.tier' },
+     *   })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'tier')
+     *   .sequenceFlow('tier', 'done')
+     *   .build();
+     * ```
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @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.
+     * @returns This builder, so calls chain.
+     */
+    businessRule(id, opts) {
+        // The ONE place this type departs from its family, and deliberately.
+        //
+        // Every other member takes its default output variable from the registry's
+        // `OutputName` (`Process response` → `<id>_processResponse`). This type's
+        // `OutputName` is literally its designer LABEL, `Execute business rule [Preview]`,
+        // so the derived default would be `<id>_executeBusinessRulePreview`: unreadable,
+        // and — worse — it encodes the preview marker in a name authors write expressions
+        // against. When `[Preview]` drops the label becomes `Execute business rule`, the
+        // derived default silently becomes `<id>_executeBusinessRule`, and every
+        // `vars.<id>_executeBusinessRulePreview` reference in every authored process starts
+        // resolving to undefined — a silent wrong-answer change from a cosmetic spec edit.
+        //
+        // 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`,
+        });
+    }
+    /**
+     * Add an item to an Orchestrator **queue** (`Orchestrator.CreateQueueItem`, or
+     * `Orchestrator.CreateAndWaitForQueueItem` when `wait` is set).
+     *
+     * @example
+     * ```ts
+     * bpmn('intake')
+     *   .startEvent('start')
+     *   .queueItem('enqueue', { queue: 'Invoices', folder: 'Finance', item: { id: 'INV-1' } })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'enqueue')
+     *   .sequenceFlow('enqueue', 'done')
+     *   .build();
+     * ```
+     *
+     * @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.
+     * @returns This builder, so calls chain.
+     */
+    queueItem(id, opts) {
+        return this.push({
+            kind: 'typed',
+            id,
+            name: opts.name,
+            type: opts.wait ? 'Orchestrator.CreateAndWaitForQueueItem' : 'Orchestrator.CreateQueueItem',
+            context: this.bindRequiredContext(id, opts.wait ? 'Orchestrator.CreateAndWaitForQueueItem' : 'Orchestrator.CreateQueueItem', {
+                queueName: opts.queue,
+                folderPath: opts.folder,
+            }),
+            inputs: opts.item ?? {},
+            outputs: opts.outputs,
+            outputVar: opts.outputVar,
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    /**
+     * A **human task** — an Action App task a person completes (`bpmn:userTask` +
+     * `uipath:activity` / `Actions.HITL`).
+     *
+     * @remarks
+     * The offline runtime can stand in for the human — `--hitl-response` injects an
+     * outcome — so an approval gate's branches are testable with no tenant and no
+     * waiting. That is why this is the one discovery-requiring type worth authoring
+     * early:
+     *
+     * ```bash
+     * flow-debug Invoice.bpmn --mock --virtual-time --hitl-response 'approve={"Action":"approve"}'
+     * ```
+     *
+     * Map the decision into a variable with `outputs` if anything branches on it —
+     * see {@link HumanTaskOpts.outputs} for why the type's own output is not enough.
+     *
+     * @example
+     * **An approval gate whose branches can be exercised offline**
+     * ```ts
+     * bpmn('invoice')
+     *   .var('outcome', 'string', { default: 'none' })
+     *   .startEvent('start')
+     *   .humanTask('approve', {
+     *     app: 'app-123',
+     *     title: 'Approve the invoice',
+     *     actions: ['approve', 'reject'],
+     *     input: { amount: 100 },
+     *     outputs: { decision: '=Action' },
+     *   })
+     *   .exclusiveGateway('gw', { default: 'fReject' })
+     *   .task('ok', { set: { outcome: 'approved' } })
+     *   .task('no', { set: { outcome: 'rejected' } })
+     *   .exclusiveGateway('join', { default: 'fJoin' })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'approve')
+     *   .sequenceFlow('approve', 'gw')
+     *   .sequenceFlow('gw', 'ok', { id: 'fApprove', condition: '=js:vars.decision == "approve"' })
+     *   .sequenceFlow('gw', 'no', { id: 'fReject' })
+     *   .sequenceFlow('ok', 'join', { id: 'fOk' })
+     *   .sequenceFlow('no', 'join', { id: 'fNo' })
+     *   .sequenceFlow('join', 'done', { id: 'fJoin' })
+     *   .build();
+     * ```
+     *
+     * @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.
+     * @returns This builder, so calls chain.
+     */
+    humanTask(id, opts) {
+        return this.push({
+            kind: 'typed',
+            id,
+            name: opts.name,
+            type: 'Actions.HITL',
+            context: {
+                appId: opts.app,
+                ...(opts.appVersion !== undefined ? { appVersion: opts.appVersion } : {}),
+                ...(opts.actions !== undefined ? { actions: opts.actions.join(',') } : {}),
+                ...(opts.title !== undefined ? { taskTitle: opts.title } : {}),
+                ...(opts.key !== undefined ? { key: opts.key } : {}),
+            },
+            inputs: opts.input ?? {},
+            outputVar: opts.outputVar,
+            outputs: opts.outputs,
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    /**
+     * Wait for an internal message from another Maestro process
+     * (`Maestro.ReceiveMessageEvent` on a `bpmn:intermediateCatchEvent`).
+     *
+     * @remarks
+     * **No offline behavioural assertion is possible for this node**, and that is
+     * worth knowing before relying on it. The local engine treats intermediate catch
+     * and throw events as pass-throughs (`engine.ts`: "For lightweight engine, just
+     * pass through"), so a local run walks straight past this event without waiting,
+     * without correlating, and without populating its output. A green local ladder
+     * therefore proves the graph runs and the artifact validates — nothing about the
+     * message actually arriving. See Phase 5 in `docs/BPMN_COVERAGE_DESIGN.md`.
+     *
+     * The throw side (`Maestro.SendMessageEvent`) is deliberately NOT authored: its
+     * required `Reference` payload field cannot be expressed in a way the platform
+     * validator accepts. See `unsatisfiableRequiredInputs`.
+     *
+     * @example
+     * **Wait for another process to signal a shipment**
+     * ```ts
+     * bpmn('fulfil')
+     *   .var('orderId', 'string', { default: 'ORD-1' })
+     *   .var('shipment', 'object')
+     *   .startEvent('start')
+     *   .receiveMessage('await', {
+     *     message: 'ShipmentReady',
+     *     reference: '=js:vars.orderId',
+     *     outputVar: 'shipment',
+     *   })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'await')
+     *   .sequenceFlow('await', 'done')
+     *   .build();
+     * ```
+     *
+     * @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.
+     * @returns This builder, so calls chain.
+     */
+    receiveMessage(id, opts) {
+        return this.push({
+            kind: 'typed',
+            id,
+            name: opts.name,
+            type: 'Maestro.ReceiveMessageEvent',
+            context: { name: opts.message },
+            inputs: { Reference: opts.reference },
+            outputVar: opts.outputVar,
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    /**
+     * Wait mid-flow for an Integration Service connector event
+     * (`Intsvc.WaitForEvent` on a `bpmn:receiveTask`).
+     *
+     * @remarks
+     * The sibling of {@link ScopeBuilder.eventTrigger}: one connector operation, two
+     * placements. This one pauses a RUNNING process; `.eventTrigger()` starts one.
+     * The platform ships both for the same operation and only the library namespace
+     * differs, which is the same pairing Flow models as `waitForEvent()` / `onEvent()`.
+     *
+     * **This family DOES have an offline behavioural assertion**, unlike the other
+     * wait-shaped nodes: the engine mocks a receive task like any other, so
+     * `--mock-data` supplies a payload and a gateway branches on it. Map the field
+     * with `outputs` — the type's own `source="."` row is not resolved locally.
+     *
+     * @example
+     * **Wait for an email, then branch on it**
+     * ```ts
+     * bpmn('intake')
+     *   .binding('outlook', { value: 'conn-uuid', resource: 'Connection', propertyAttribute: 'ConnectionId' })
+     *   .binding('shared', { value: 'folder-key', resource: 'Connection', propertyAttribute: 'folderKey' })
+     *   .var('subject', 'string', { default: '' })
+     *   .startEvent('start')
+     *   .waitForEvent('mail', 'uipath-microsoft-outlook365', 'email-received', {
+     *     connection: 'outlook',
+     *     folder: 'shared',
+     *     outputs: { subject: '=subject' },
+     *   })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'mail')
+     *   .sequenceFlow('mail', 'done')
+     *   .build();
+     * ```
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @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.
+     * @returns This builder, so calls chain.
+     */
+    waitForEvent(id, connector, event, opts) {
+        return this.push({
+            kind: 'connectorEvent',
+            id,
+            name: opts.name,
+            subscribe: 'event',
+            key: connector,
+            eventName: event,
+            version: opts.version,
+            connection: opts.connection,
+            folder: opts.folder,
+            folderPath: opts.folderPath,
+            filter: opts.filter,
+            parameters: opts.parameters,
+            outputVar: opts.outputVar,
+            outputs: opts.outputs,
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    /**
+     * START the process when an Integration Service connector event fires
+     * (`Intsvc.EventTrigger` on a `bpmn:startEvent` carrying a message event
+     * definition).
+     *
+     * @remarks
+     * Its own method rather than a flag on `.startEvent()` — the opposite call from
+     * the timer trigger, and for a stated reason. `Intsvc.TimerTrigger` declares NO
+     * fields, so the only thing to configure there is an output variable and a flag
+     * suffices. This type declares nine, including the connection and folder
+     * bindings, which is a method's worth of surface.
+     *
+     * **No offline behavioural assertion**, unlike `.waitForEvent()`: this is a start
+     * event, and the engine applies a start event's output rows against the variable
+     * scope rather than a mocked result, so nothing populates the payload locally.
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param connector - The connector key, e.g. `'uipath-http-webhook'`.
+     * @param event - The event name, e.g. `'http-webhook'`.
+     * @param opts - Connection/folder bindings, the `where` scope, and what to keep.
+     * @returns This builder, so calls chain.
+     */
+    eventTrigger(id, connector, event, opts) {
+        return this.push({
+            kind: 'connectorEvent',
+            id,
+            name: opts.name,
+            subscribe: 'trigger',
+            key: connector,
+            eventName: event,
+            version: opts.version,
+            connection: opts.connection,
+            folder: opts.folder,
+            folderPath: opts.folderPath,
+            filter: opts.filter,
+            parameters: opts.parameters,
+            outputVar: opts.outputVar,
+            outputs: opts.outputs,
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    /**
+     * Invoke an external agent through an Integration Service connector
+     * (`Intsvc.SyncAgentExecution` / `Intsvc.AsyncAgentExecution`).
+     *
+     * @remarks
+     * `mode: 'sync'` waits for the agent's answer; `'async'` starts it and moves on.
+     * The descriptor must be an `AgentExecution` operation — the library is the
+     * authority, and a plain connector action is refused rather than emitted as a node
+     * the validator accepts and the runtime dispatches to the wrong handler.
+     *
+     * **The shipped library contains very few of these** (2 agent operations, 1
+     * workflow), so this is a narrow surface by nature, not by omission.
+     *
+     * @example
+     * ```ts
+     * bpmn('triage')
+     *   .binding('vertex', { value: 'conn-uuid', resource: 'Connection', propertyAttribute: 'ConnectionId' })
+     *   .binding('shared', { value: 'folder-key', resource: 'Connection', propertyAttribute: 'folderKey' })
+     *   .startEvent('start')
+     *   .externalAgent('summarise', 'uipath-google-vertex', 'execute-google-vertex-agent',
+     *     { prompt: 'Summarise the ticket' },
+     *     { mode: 'sync', connection: 'vertex', folder: 'shared' })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'summarise')
+     *   .sequenceFlow('summarise', 'done')
+     *   .build();
+     * ```
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param connector - The connector key.
+     * @param action - The `AgentExecution` operation name.
+     * @param inputs - The invocation payload.
+     * @param opts - `mode`, the connection/folder bindings, and what to keep.
+     * @returns This builder, so calls chain.
+     */
+    externalAgent(id, connector, action, inputs, opts) {
+        return this.externalTask('agent', id, connector, action, inputs, opts);
+    }
+    /**
+     * Invoke an external workflow through an Integration Service connector
+     * (`Intsvc.SyncWorkflowExecution` / `Intsvc.AsyncWorkflowExecution`).
+     *
+     * @remarks
+     * The workflow counterpart of {@link ScopeBuilder.externalAgent}; the descriptor
+     * must be a `ProcessExecution` operation.
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param connector - The connector key.
+     * @param action - The `ProcessExecution` operation name.
+     * @param inputs - The invocation payload.
+     * @param opts - `mode`, the connection/folder bindings, and what to keep.
+     * @returns This builder, so calls chain.
+     */
+    externalWorkflow(id, connector, action, inputs, opts) {
+        return this.externalTask('workflow', id, connector, action, inputs, opts);
+    }
+    /** @internal Shared body of the two external-invocation methods. */
+    externalTask(family, id, connector, action, inputs, opts) {
+        return this.push({
+            kind: 'externalTask',
+            id,
+            name: opts.name,
+            family,
+            mode: opts.mode,
+            key: connector,
+            action,
+            version: opts.version,
+            inputs,
+            connection: opts.connection,
+            folder: opts.folder,
+            outputVar: opts.outputVar,
+            outputs: opts.outputs,
+            skipCondition: opts.skipCondition,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    /**
+     * ANY registry-backed node, by extension type — the generic form the typed
+     * methods are sugar over.
+     *
+     * @remarks
+     * Reach for a typed method first (`.http()`, `.startProcess()`, `.humanTask()`,
+     * …): it names the fields, defaults what the registry defaults, and declares the
+     * bindings a type demands. This is for the types that have no wrapper yet, and
+     * it is what `bpmn-decompile` emits for them — which is why it exists at all.
+     * Nothing is validated for you beyond what the registry states, so the emitted
+     * node is exactly as correct as the `context` you pass.
+     *
+     * The element, tag, input shape, output row and event definition all come from
+     * the committed registry snapshot, so the wire form is right even when the
+     * ergonomics are bare.
+     *
+     * @example
+     * ```ts
+     * bpmn('agentic')
+     *   .startEvent('start')
+     *   .activity('call', 'A2A.AgentExecution', { inputs: { prompt: 'summarise' } })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'call')
+     *   .sequenceFlow('call', 'done')
+     *   .build();
+     * ```
+     *
+     * @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.
+     * @returns This builder, so calls chain.
+     */
+    activity(id, type, opts = {}) {
+        return this.push({
+            kind: 'typed',
+            id,
+            name: opts.name,
+            type,
+            context: opts.context ?? {},
+            contextRows: opts.contextRows,
+            inputs: opts.inputs ?? {},
+            typeVersion: opts.typeVersion,
+            inputSchema: opts.inputSchema,
+            outputVar: opts.outputVar,
+            outputs: opts.outputs,
+            outputRows: opts.outputRows,
+            skipCondition: opts.skipCondition,
+            contextVerbatim: opts.contextVerbatim,
+            tags: opts.tags,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            loop: opts.loop,
+        });
+    }
+    // ── Sub-process (nested graph) ──
+    /**
+    * A sub-process — a scope of its own, with its own elements and flows (`bpmn:subProcess`).
+    *
+    * @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.
+    * @returns This builder, so calls chain.
+    */
+    subProcess(id, fn, opts = {}) {
+        const sb = new SubProcessBuilder(this._defs, this._bindingRegistry);
+        fn(sb);
+        return this.push(sb._buildNode(id, opts));
+    }
+    // ── Flows ──
+    /**
+     * A sequence flow from `source` to `target` (1-1 with `bpmn:sequenceFlow`).
+     *
+     * @param source - The id of the element the flow leaves.
+     * @param target - The id of the element it arrives at.
+     * @param opts - `name`, and the `condition` guarding it.
+     * @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,
+        });
+        return this;
+    }
+    // ── Variables ──
+    /**
+     * A mutable flow variable (`uipath:inputOutput`). Root unless `elementId` scopes it.
+     *
+     * @param id - The variable's name.
+     * @param type - A `types.*` descriptor.
+     * @param opts - `direction`, a `default`, and `elementId` to scope it to one element.
+     * @returns This builder, so calls chain.
+     */
+    var(id, type, opts = {}) {
+        return this.declareVar(id, type, 'inputOutput', opts);
+    }
+    /**
+     * A read-only entry input (`uipath:input`).
+     *
+     * @param id - The input's name.
+     * @param type - A `types.*` descriptor.
+     * @param opts - A `default`, and `elementId` to scope it to one element.
+     * @returns This builder, so calls chain.
+     */
+    input(id, type, opts = {}) {
+        return this.declareVar(id, type, 'input', opts);
+    }
+    /**
+     * A return value (`uipath:output`).
+     *
+     * @param id - The output's name.
+     * @param type - A `types.*` descriptor.
+     * @param opts - A `default`, and `elementId` to scope it to one element.
+     * @returns This builder, so calls chain.
+     */
+    output(id, type, opts = {}) {
+        return this.declareVar(id, type, 'output', opts);
+    }
+    declareVar(id, type, direction, opts) {
+        this._vars.push({
+            id,
+            name: opts.name ?? id,
+            type,
+            direction,
+            default: opts.default,
+            elementId: opts.elementId,
+            schema: opts.schema,
+            required: opts.required,
+        });
+        return this;
+    }
+}
+/**
+ * The variables a connector task's output rows land in.
+ *
+ * Per-node by default, because a `uipath:output`'s `var` IS the variable
+ * declaration as far as the platform is concerned (its canvas model maps every
+ * node output to a variable keyed by `var`). A shared name would therefore mean
+ * two connectors writing one variable, with the second silently clobbering the
+ * first — and it is the reason both the serializer and the expression check need
+ * the same answer, hence one function.
+ *
+ * @param n - The connector node.
+ * @returns The response and error variable names.
+ *
+ * @internal
+ */
+export function connectorOutputVars(n) {
+    return { response: n.outputVar ?? `${n.id}_response`, error: `${n.id}_Error` };
+}
+/**
+ * The variables a typed node writes — the ONE definition of that set.
+ *
+ * It had grown three: this one (what an expression may read), `implicitNodeVars` in
+ * serialize (what gets declared in `uipath:variables`), and `derivedVariableIds` in
+ * decompile (what a decompiled file must NOT re-declare). All three must agree, and
+ * adding `outputRows` proved they do not stay agreed on their own: two were updated,
+ * this one was missed, and a human task's mapped output stopped being visible to the
+ * expression checker — `vars.decision` reported undeclared for a variable the node
+ * plainly writes. So serialize now calls this instead of repeating it, and only
+ * decompile's copy is separate, which its own comment already flags as load-bearing.
+ *
+ * @param n - The typed node.
+ * @returns The variable ids its output rows write.
+ * @internal
+ */
+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);
+    return [...(v ? [v] : []), ...Object.keys(n.outputs ?? {})];
+}
+/**
+ * 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
+ * against it without any `uipath:variables` entry. The expression check mirrors
+ * that, or it would reject reads the platform accepts.
+ *
+ * @param n - The node to inspect.
+ * @returns The variable names it declares, if any.
+ *
+ * @internal
+ */
+export function nodeDeclaredVars(n) {
+    if (n.kind === 'connector') {
+        const { response, error } = connectorOutputVars(n);
+        return [response, error];
+    }
+    if (n.kind === 'typed')
+        return typedNodeDeclaredVars(n);
+    if (n.kind === 'scriptTask')
+        return Object.keys(n.outputs);
+    if (n.kind === 'task')
+        return Object.keys(n.set);
+    return [];
+}
+/** A sub-process body: the same graph methods, plus an internal node builder. */
+export class SubProcessBuilder extends ScopeBuilder {
+    /** @internal */
+    _buildNode(id, opts) {
+        return {
+            kind: 'subProcess',
+            id,
+            name: opts.name,
+            payload: opts.payload,
+            triggeredByEvent: opts.triggeredByEvent,
+            tags: opts.tags,
+            loop: opts.loop,
+            retry: opts.retry,
+            errorMapping: opts.errorMapping,
+            nodes: this._nodes,
+            flows: this._flows,
+            variables: this._vars,
+        };
+    }
+}
+// ─── Top-level process builder ────────────────────────────────────────────────
+/**
+ * The top-level process builder `bpmn()` returns — every graph method of the
+ * shared scope (events, gateways, tasks, sub-processes, flows, variables) plus
+ * the process's `.name()` and the `.build()` that finishes it.
+ */
+export class BpmnBuilder extends ScopeBuilder {
+    _id;
+    _name;
+    _metadata;
+    /**
+     * @param _id - The process id, as passed to `bpmn()`.
+     * @returns The top-level builder.
+     */
+    constructor(_id) {
+        super(new DefinitionsRegistry(), new BindingsRegistry());
+        this._id = _id;
+    }
+    /**
+    * Set the process's display name.
+    *
+    * @param n - The name the designer shows.
+    * @returns This builder, so calls chain.
+    */
+    name(n) {
+        this._name = n;
+        return this;
+    }
+    /**
+     * Process-level metadata — see {@link ProcessMetadata}.
+     *
+     * Repeated calls MERGE rather than replace, so a caller can set one field without
+     * knowing what an earlier call set.
+     *
+     * @param meta - The fields to declare; anything omitted stays absent.
+     * @returns This builder, so calls chain.
+     *
+     * @example
+     * ```ts
+     * bpmn('order').metadata({ migrationVersion: '11' })
+     * ```
+     */
+    metadata(meta) {
+        this._metadata = { ...this._metadata, ...meta };
+        return this;
+    }
+    /**
+     * Declare the Canvas SCHEMA generation this document targets
+     * (`uipath:migrationVersion`).
+     *
+     * @remarks
+     * The same field {@link ProcessMetadata.migrationVersion} sets, under the name
+     * the Flow and Case builders use for the same concept — a document's schema
+     * version, as opposed to anything about the process's own release. Both
+     * spellings stay valid; the later call wins, as with any `.metadata()` field.
+     *
+     * Unlike Flow's file format and Case's grammar, this one does not change what
+     * the serializer emits: the `.bpmn` is the same XML whatever generation is
+     * stamped on it, so any non-empty value is accepted and carried through
+     * verbatim. An empty one is refused, because an empty
+     * `uipath:migrationVersion` fails product validation — absent beats blank.
+     *
+     * `bpmn-decompile` emits this call with the stamp it read, which is what keeps
+     * a decompile → edit → recompile from dropping a generation Studio Web wrote
+     * and some graders require.
+     *
+     * @example
+     * ```ts
+     * bpmn('order').schemaVersion('11.5')
+     * ```
+     *
+     * @param version - The Canvas schema generation, e.g. `'11'` or `'11.5'`.
+     * @returns This builder, so calls chain.
+     * @throws Error when `version` is empty.
+     */
+    schemaVersion(version) {
+        const refusal = schemaVersionRefusal(BPMN_SCHEMA_VERSIONS, version);
+        if (refusal)
+            throw new Error(refusal);
+        this._metadata = { ...this._metadata, migrationVersion: version };
+        return this;
+    }
+    /** Named schemas declared with `.schema()`, resolved when a row references one. */
+    _schemas = new Map();
+    /**
+     * Name a JSON Schema once so several variables can share it.
+     *
+     * @remarks
+     * Purely a source-level convenience: there is no shared-schema concept on the
+     * wire, so every reference expands back to the same inline body and the emitted
+     * XML is byte-identical either way. What it saves is the source — a real process
+     * repeats a handful of shapes across dozens of variables, and one export carried
+     * 57 schema bodies of which only 13 were distinct.
+     *
+     * `schema: errorSchema` covers the platform's own error envelope, which needs no
+     * declaration at all; this is for the shapes that belong to a particular process.
+     *
+     * @param id - The name to reference it by, in `schema: id`.
+     * @param schema - The JSON Schema, as a value rather than a string.
+     * @returns This builder, so calls chain.
+     *
+     * @example
+     * ```ts
+     * bpmn('orders')
+     *   .schema('queueItem', { type: 'object', properties: { Id: { type: 'integer' } } })
+     *   .var('response1', 'jsonSchema', { name: 'response', schema: 'queueItem' })
+     *   .var('response2', 'jsonSchema', { name: 'response', schema: 'queueItem' })
+     * ```
+     */
+    schema(id, schema) {
+        this._schemas.set(id, schema);
+        return this;
+    }
+    /**
+     * Declare an external identifier the process needs supplied — a base URL, a
+     * folder path, a process name (`uipath:binding`). Expressions read it as
+     * `=bindings.<id>`, and an offline run resolves it to `value`.
+     *
+     * @remarks
+     * A connector's `connection`/`folder` already produce their own bindings at
+     * serialize time; this is for everything else, and it is what lets a value be
+     * configured per environment rather than baked into the process. Declaring the
+     * same id twice keeps the FIRST declaration.
+     *
+     * @example
+     * ```ts
+     * bpmn('sync')
+     *   .binding('apiBase', { name: 'API base URL', value: 'https://api.example.com' })
+     *   .var('url', 'string')
+     *   .startEvent('start')
+     *   .task('resolve', { set: { url: '=js:bindings.apiBase + "/v1/orders"' } })
+     * ```
+     *
+     * @param id - The binding's id — what `=bindings.<id>` refers to.
+     * @param opts - Display `name`, the `value` it defaults to, and which resource it addresses.
+     * @returns This builder, so calls chain.
+     */
+    binding(id, opts = {}) {
+        this._bindingRegistry.declare({
+            id,
+            name: opts.name ?? id,
+            resource: opts.resource ?? 'custom',
+            propertyAttribute: opts.propertyAttribute ?? 'value',
+            resourceSubType: opts.resourceSubType,
+            default: opts.value,
+            resourceKey: opts.resourceKey ?? opts.value,
+        });
+        return this;
+    }
+    /**
+     * Finish the process and return the graph the serializer turns into XML.
+     *
+     * @returns The built process — its elements, flows and variables.
+     */
+    build() {
+        const built = {
+            id: this._id,
+            name: this._name,
+            metadata: this._metadata,
+            variables: this._vars,
+            messages: this._defs.messages,
+            errors: this._defs.errors,
+            bindings: this._bindingRegistry.bindings,
+            nodes: this._nodes,
+            flows: this._flows,
+            schemas: this._schemas,
+        };
+        // First-level validation, intrinsic to running the SDK: catch a reference to
+        // an undeclared `vars.<name>` HERE — the one thing `uip maestro bpmn validate`
+        // does not check — before the `.bpmn` is serialized. See bpmn-expr-check.
+        const errors = checkBpmnExpressions(built).filter((d) => d.level === 'error');
+        if (errors.length)
+            throw new BpmnBuildError(built, errors);
+        return built;
+    }
+}
+/**
+ * The `Error` variable's shape — the platform's own error envelope.
+ *
+ * Every node that can fail writes one, so a real process declares this schema once
+ * per node and an imported one repeats it verbatim: 243 byte-identical copies across
+ * five unrelated customer exports, 27 in a single 71-element process.
+ *
+ * It is a contract, not a convention. `V2EndEventBody.BuildErrorCoreResult` in
+ * PO.BpmnEngine builds it — *"the ErrorEndEvent core result with one `Error` entry
+ * and the six expected fields"* — as `code`, `message`, `detail`, `category`,
+ * `status`, `element`, with `status` an HTTP status code and the rest strings.
+ *
+ * @example
+ * ```ts
+ * bpmn('p').var('error1', 'jsonSchema', { name: 'Error', schema: errorSchema })
+ * ```
+ *
+ * @see errorSchemaWithResponse
+ */
+export const errorSchema = {
+    type: 'object',
+    properties: {
+        code: { type: 'string' },
+        message: { type: 'string' },
+        detail: { type: 'string' },
+        category: { type: 'string' },
+        status: { type: 'number' },
+        element: { type: 'string' },
+    },
+};
+/**
+ * The same envelope plus `response` — what a node whose failure carries a payload
+ * writes, and what the same source calls *"the generic failure mapping shape, which
+ * includes a `response` key"*, distinguishing it from {@link errorSchema}.
+ *
+ * 42 copies across the corpus, against 243 of the six-field form.
+ */
+export const errorSchemaWithResponse = {
+    type: 'object',
+    properties: {
+        ...errorSchema.properties,
+        response: { type: 'string' },
+    },
+};
+/**
+ * Start building a BPMN process with the given id.
+ *
+ * @example
+ * **A minimal start → task → end process**
+ * ```ts
+ * export default bpmn('intake')
+ *   .startEvent('start')
+ *   .var('note', 'string', { default: '' })
+ *   .task('assign', { set: { note: 'hello' } })
+ *   .endEvent('done')
+ *   .sequenceFlow('start', 'assign')
+ *   .sequenceFlow('assign', 'done')
+ *   .build();
+ * ```
+ *
+ * @param id - The process id.
+ * @returns A {@link BpmnBuilder} to add elements to.
+ */
+export function bpmn(id) {
+    return new BpmnBuilder(id);
+}