@uipath/maestro-builder-sdk 5.2.0

package/dist/bpmn/bpmn-sdk.d.ts

@@ -0,0 +1,2257 @@
+/**
+ * bpmn-sdk — a fluent builder for UiPath Maestro BPMN processes (`.bpmn` XML).
+ *
+ * Like the Flow and Case builders, this constructs a plain description of a
+ * process — a **graph** of BPMN elements (events, gateways, tasks, sub-processes)
+ * wired by `sequenceFlow`s — which `serialize()` turns into real `.bpmn` XML. The
+ * builder methods are **1-1 with BPMN elements**: `.startEvent()` ↔
+ * `bpmn:startEvent`, `.exclusiveGateway()` ↔ `bpmn:exclusiveGateway`,
+ * `.sequenceFlow()` ↔ `bpmn:sequenceFlow`, and so on. `.build()` returns the
+ * in-memory graph (`BuiltBpmn`); `serialize()` walks that graph into the XML.
+ *
+ * This is the **structural core**: the elements Maestro lets you author directly
+ * (the "registry gap" half — gateways, events, boundary events, script/variable
+ * tasks, sub-processes, multi-instance loops). Registry-backed typed nodes
+ * (service/user/send/receive tasks, call activities) resolve `uipath:*` payloads
+ * from the BPMN registry and land in a later phase.
+ *
+ * Diagram interchange (`bpmndi`) is intentionally **not** emitted here: BPMN
+ * validation is layout-independent, so the SDK emits semantic-only XML and a
+ * separate "tidy" step lays it out. See serialize.ts.
+ */
+import type { TypeDesc } from '../core/expr.js';
+import { type ConnectorOpts } from '../core/actions.js';
+import type { ConnectorDescriptor } from '../core/connectors.js';
+import type { TypedContextRow, TypedOutputRow } from './typed-node.js';
+export { BpmnBuildError } from './bpmn-expr-check.js';
+export type { BpmnLocatedDiagnostic } from './bpmn-expr-check.js';
+/** ISO-8601 timer specification (one of duration / date / cycle). */
+export interface TimerSpec {
+    /** Fire after this ISO-8601 duration, e.g. `'PT30S'`. */
+    duration?: string;
+    /** Fire at this ISO-8601 date-time, e.g. `'2026-09-01T09:00:00Z'`. */
+    date?: string;
+    /** Fire on this ISO-8601 repeating interval, e.g. `'R/PT1H'`. */
+    cycle?: string;
+}
+/** A timer as an ISO-8601 duration string (shorthand for `{ duration }`) or a full spec. */
+export type TimerLike = string | TimerSpec;
+/**
+ * What an author passes for an error definition.
+ *
+ * `true` means CATCH ANY — a bare `<bpmn:errorEventDefinition />` with no
+ * `errorRef`, which is what every error boundary in five real Studio Web exports
+ * uses, and the only form any of them uses. A name (or a `{ name, code }` pair
+ * when the wire code differs) narrows it to one declared error instead.
+ */
+export type ErrorLike = true | string | {
+    name: string;
+    code?: string;
+};
+/** The resolved event definition attached to an event node. */
+export type EventDef = {
+    type: 'message';
+    messageRef: string;
+} | {
+    type: 'timer';
+    timer: TimerSpec;
+}
+/**
+ * An error definition. `errorRef` absent is BPMN's CATCH-ANY: a bare
+ * `<bpmn:errorEventDefinition />` pointing at no declaration, which catches every
+ * error rather than one named kind.
+ */
+ | {
+    type: 'error';
+    errorRef?: string;
+} | {
+    type: 'terminate';
+};
+/** The four gateway element kinds a {@link BpmnNode} can be. */
+export type GatewayKind = 'exclusiveGateway' | 'parallelGateway' | 'inclusiveGateway' | 'eventBasedGateway';
+/** The four non-boundary event element kinds a {@link BpmnNode} can be. */
+export type EventKind = 'startEvent' | 'endEvent' | 'intermediateCatchEvent' | 'intermediateThrowEvent';
+/** Multi-instance loop over a collection (`uipath:loopCharacteristics`). */
+export interface LoopSpec {
+    /** `=`-expression yielding the collection to iterate. */
+    collection: string;
+    /** Name the current item is bound to inside the body (`iterator.<itemVar>`). */
+    itemVar: string;
+    /** true = one at a time (sequential); false/omitted = parallel. */
+    sequential?: boolean;
+    /** Optional `=`-expression completion condition. */
+    completion?: string;
+}
+/**
+ * One node in the built graph — a discriminated union with one arm per BPMN
+ * element kind, which the serializer walks into the corresponding XML element.
+ */
+export type BpmnNode = {
+    kind: EventKind;
+    id: string;
+    name?: string;
+    event?: EventDef;
+    /**
+     * A registry-backed TRIGGER declaration on this event, on top of its event
+     * definition — see {@link StartOpts.trigger}. The two are orthogonal halves
+     * of one element: the definition schedules, this names the node type and
+     * declares the payload variable.
+     */
+    trigger?: {
+        type: string;
+        outputVar?: string;
+    };
+    /** A `uipath:mapping` / `uipath:activity` payload on the event — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+} | {
+    kind: 'boundaryEvent';
+    id: string;
+    name?: string;
+    attachedTo: string;
+    cancelActivity: boolean;
+    event: EventDef;
+    /** A `uipath:activity` payload on the boundary — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+} | {
+    kind: GatewayKind;
+    id: string;
+    name?: string;
+    default?: string;
+} | (ActivityNodeFields & {
+    kind: 'scriptTask';
+    id: string;
+    name?: string;
+    script: string;
+    scriptFormat: string;
+    inputs: Record<string, string>;
+    outputs: Record<string, string>;
+    /** The mapping's extension type — see {@link ScriptTaskOpts.type}. */
+    type: string;
+    /** The `uipath:inputSchema` body — see {@link ScriptTaskOpts.inputSchema}. */
+    inputSchema?: unknown;
+    /** Output rows spelled out, replacing the ones `outputs` would derive. */
+    outputRows?: TypedOutputRow[];
+}) | (ActivityNodeFields & {
+    kind: 'task';
+    id: string;
+    name?: string;
+    set: Record<string, string>;
+}) | (ActivityNodeFields & {
+    kind: 'connector';
+    id: string;
+    name?: string;
+    /** connector key + action (identify the library op), like Flow/Case. */
+    key: string;
+    action: string;
+    version?: string;
+    /** symbolic connection/folder names resolved via bindings.json. */
+    connection?: string;
+    folder?: string;
+    /** Which OBJECT a generic operation addresses — see `ConnectorOpts.object`. */
+    object?: string;
+    inputs: Record<string, unknown>;
+    /** Variable the response lands in; defaults to `<id>_response`. */
+    outputVar?: string;
+    /** `=`-expression that, when true, skips this activity (`uipath:activity/@skipCondition`). */
+    skipCondition?: string;
+}) | (ActivityNodeFields & {
+    kind: 'typed';
+    id: string;
+    name?: string;
+    /** The registry extension type, e.g. `'Intsvc.UnifiedHttpRequest'`. */
+    type: string;
+    /** `uipath:context` values, by field name. */
+    context: Record<string, unknown>;
+    /** The payload, shaped by the type's `inputPattern`. */
+    inputs: Record<string, unknown>;
+    /** Variable the output lands in; defaults to `<id>_<outputName>`. */
+    outputVar?: string;
+    /** Extra output rows: variable id → `=`-expression against the node's result. */
+    outputs?: Record<string, string>;
+    /** Output rows spelled out, replacing the derived ones — see `TypedOutputRow`. */
+    outputRows?: TypedOutputRow[];
+    /** The `uipath:type` `version` attribute — see `ActivityNodeOpts.typeVersion`. */
+    typeVersion?: string;
+    /** The `uipath:inputSchema` body — see `ActivityNodeOpts.inputSchema`. */
+    inputSchema?: unknown;
+    /** Context rows spelled out — see {@link TypedContextRow}. */
+    contextRows?: TypedContextRow[];
+    /** `=`-expression that skips the node when truthy. */
+    skipCondition?: string;
+    /** Emit `context` exactly as given — for importers; see `TypedNodeInput`. */
+    contextVerbatim?: boolean;
+}) | (ActivityNodeFields & {
+    kind: 'connectorEvent';
+    id: string;
+    name?: string;
+    /**
+     * `trigger` STARTS the process (`Intsvc.EventTrigger`, a `bpmn:startEvent`
+     * carrying a message event definition); `event` pauses one mid-flow
+     * (`Intsvc.WaitForEvent`, a `bpmn:receiveTask`). The platform ships both for
+     * one connector operation and the namespace is the only difference, which is
+     * why one node kind carries both.
+     */
+    subscribe: 'trigger' | 'event';
+    /**
+     * Connector key + event name, resolved against the library at serialize.
+     *
+     * `eventName` rather than `event`: this union's event nodes already carry an
+     * `event?: EventDef` (the BPMN event DEFINITION), and reusing the name broke
+     * the `'event' in n` narrowing `check()` uses to validate timers.
+     */
+    key: string;
+    eventName: string;
+    version?: string;
+    /** Symbolic binding names, as `.connector()` takes them. */
+    connection?: string;
+    folder?: string;
+    /** The folder PATH, which the type requires alongside the folder key. */
+    folderPath?: string;
+    /** The `where` scope and extra event parameters, when the operation declares any. */
+    filter?: Record<string, unknown>;
+    parameters?: Record<string, unknown>;
+    outputVar?: string;
+    outputs?: Record<string, string>;
+    skipCondition?: string;
+}) | (ActivityNodeFields & {
+    kind: 'externalTask';
+    id: string;
+    name?: string;
+    /** Which family — an external agent or an external workflow. */
+    family: 'agent' | 'workflow';
+    /** `sync` waits for the result; `async` starts it and moves on. */
+    mode: 'sync' | 'async';
+    /** Connector key + action, resolved against the library at serialize. */
+    key: string;
+    action: string;
+    version?: string;
+    /** The invocation payload — one merged `body` row, per the type's template. */
+    inputs: Record<string, unknown>;
+    connection?: string;
+    folder?: string;
+    outputVar?: string;
+    outputs?: Record<string, string>;
+    skipCondition?: string;
+}) | (ActivityNodeFields & {
+    kind: 'plainTask';
+    id: string;
+    name?: string;
+    /** Which task element to emit. */
+    element: PlainTaskElement;
+}) | (ActivityNodeFields & {
+    kind: 'subProcess';
+    /** A `uipath:mapping` on the sub-process element — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+    id: string;
+    name?: string;
+    triggeredByEvent?: boolean;
+    nodes: BpmnNode[];
+    flows: BpmnFlow[];
+    variables: BpmnVarDecl[];
+});
+/**
+ * One row of `uipath:errorMapping` — how an activity classifies one kind of failure.
+ *
+ * @remarks
+ * **What is enforced, and by whom, differs — worth knowing before relying on any of
+ * it.** `uip maestro bpmn validate` polices NOTHING here beyond the tag being a known
+ * one: an empty row, an unknown attribute and `retryable="yes"` all return `Valid`.
+ * The CANVAS is stricter, and it is the stricter gate that matters: a `condition`
+ * containing an assignment is a warning there, and one referencing an undeclared
+ * variable is a BLOCKING error the CLI never mentions. So `condition` is expression-
+ * checked at author time like any other expression.
+ *
+ * **Only `retryable` has runtime meaning that this repo can demonstrate.** The local
+ * engine mirrors the platform's retry policy: an activity with a retry policy that
+ * does NOT set `allErrors` retries only when the failure's code is in the mapped
+ * retryable set. Measured on a failing activity with `maxRetries: 2` — `allErrors`
+ * gives 3 attempts, and a selective policy with no mapping gives 1, because there is
+ * nothing to match against. That is what this feature supplies.
+ *
+ * `priority` and `detail` are carried faithfully and interpreted by neither this SDK
+ * nor the local engine. They are modelled because an imported artifact may hold them
+ * and dropping them would break a round trip — not because their effect is known.
+ */
+export interface ErrorMappingRow {
+    /**
+     * The error CODE this row matches — the wire's `errorRef`.
+     *
+     * Read as a code rather than a reference to a definitions-level `bpmn:error`,
+     * on engine evidence: the runtime compares it against the failure's
+     * `externalFaultCode` and `statusCode`. Both a bare code (`TIMEOUT`) and a declared
+     * error's id validate, so the platform does not disambiguate this for us.
+     */
+    code: string;
+    /** Whether a retry policy on this activity should retry this failure. */
+    retryable?: boolean;
+    /** Row id, when the artifact carries one. */
+    id?: string;
+    /** Match order. Carried, not interpreted — see the remarks above. */
+    priority?: number | string;
+    /**
+     * `=`-expression narrowing when this row applies.
+     *
+     * Expression-checked, because the canvas rejects an undeclared variable reference
+     * here as a blocking error while the CLI stays silent.
+     */
+    condition?: string;
+    /** Human-facing detail. Carried, not interpreted. */
+    detail?: string;
+}
+/**
+ * The fields every activity arm of {@link BpmnNode} carries — the built form of
+ * {@link ActivityOpts}. One shape, so the serializer emits `uipath:retry`,
+ * `uipath:errorMapping` and the loop characteristics from a single place regardless of
+ * which activity it is walking.
+ */
+export interface ActivityNodeFields {
+    /** `uipath:tags` on the node — see {@link ActivityOpts.tags}. */
+    tags?: Record<string, string>;
+    /** Retry policy (`uipath:retry`). */
+    retry?: RetrySpec;
+    /** Multi-instance loop (`bpmn:multiInstanceLoopCharacteristics` + `uipath:loopCharacteristics`). */
+    loop?: LoopSpec;
+    /** Failure classification (`uipath:errorMapping`) — see {@link ErrorMappingRow}. */
+    errorMapping?: ErrorMappingRow[];
+}
+/** One sequence flow in the built graph — the edge from `source` to `target` (`bpmn:sequenceFlow`). */
+export interface BpmnFlow {
+    /** The flow's element id. */
+    id: string;
+    /** The id of the element the flow leaves. */
+    source: string;
+    /** The id of the element it arrives at. */
+    target: string;
+    /** Edge label the designer shows. */
+    name?: string;
+    /** `=`-expression gating this flow (exclusive/inclusive gateway outgoing). Read a declared process variable as `=vars.<id>`. */
+    condition?: string;
+}
+/**
+ * How a variable is exposed: `'input'` (read-only entry input), `'output'` (a
+ * return value), or `'inputOutput'` (a mutable flow variable).
+ */
+export type VarDirection = 'input' | 'inputOutput' | 'output';
+/** A declared variable in the built graph (`uipath:input` / `uipath:inputOutput` / `uipath:output`, by `direction`). */
+export interface BpmnVarDecl {
+    /** The variable's id — what expressions read as `vars.<id>`. */
+    id: string;
+    /** Display name; `.var()`/`.input()`/`.output()` default it to the id. */
+    name: string;
+    /** The variable's `types.*` descriptor. */
+    type: TypeDesc;
+    /** How the variable crosses the process boundary — see {@link VarDirection}. */
+    direction: VarDirection;
+    /** Optional initial value. */
+    default?: unknown;
+    /** When set, the variable is scoped to that element rather than root/global. */
+    elementId?: string;
+    /** The declaration's body — a JSON Schema for a structured variable. */
+    schema?: unknown;
+    /** Mark the declaration `required="true"`, as a process input can be. */
+    required?: boolean;
+}
+/**
+ * A declared external identifier the process needs supplied at deploy time — a
+ * connection id, a folder key, a process name, a base URL (`uipath:binding`).
+ * Expressions read it as `=bindings.<id>`.
+ */
+export interface BindingDecl {
+    /** The binding's id — what `=bindings.<id>` refers to. */
+    id: string;
+    /** Display name the designer shows. Defaults to the id. */
+    name: string;
+    /** The kind of resource this identifies, e.g. `'Connection'`, `'process'`, `'queue'`. */
+    resource: string;
+    /** Which property of that resource is wanted, e.g. `'ConnectionId'`, `'Key'`. */
+    propertyAttribute: string;
+    /** The value used when nothing overrides it — what an offline run resolves to. */
+    default?: string;
+    /** The resource's key, when it differs from `default`. */
+    resourceKey?: string;
+    /**
+     * Narrows the resource, e.g. `'Agent'` for an agent process. Required by some
+     * extension types and stated by none of them — see `REGISTRY_GAPS`.
+     */
+    resourceSubType?: string;
+}
+/** A definitions-level `bpmn:message` declaration, referenced by message events. */
+export interface MessageDecl {
+    /** The declaration's id — what an event's `messageRef` points at. */
+    id: string;
+    /** The message's name, as authored on the event option. */
+    name: string;
+}
+/** A definitions-level `bpmn:error` declaration, referenced by error events. */
+export interface ErrorDecl {
+    /** The declaration's id — what an event's `errorRef` points at. */
+    id: string;
+    /** The error's name, as authored on the event option. */
+    name: string;
+    /** The error code the runtime matches on. */
+    code?: string;
+}
+/**
+ * The built in-memory process graph `.build()` returns — the IR `serialize()`
+ * walks into `.bpmn` XML.
+ */
+export interface BuiltBpmn {
+    /** The process id, as passed to `bpmn()`. */
+    id: string;
+    /** The process's display name, from `.name()`. */
+    name?: string;
+    /** Every declared variable, root and element-scoped alike. */
+    variables: BpmnVarDecl[];
+    /** definitions-level `bpmn:message` declarations referenced by message events. */
+    messages: MessageDecl[];
+    /** definitions-level `bpmn:error` declarations referenced by error events. */
+    errors: ErrorDecl[];
+    /** Author-declared `uipath:binding` entries (connector wiring adds its own at serialize). */
+    bindings: BindingDecl[];
+    /** The top-level elements, in authoring order (sub-processes nest their own). */
+    nodes: BpmnNode[];
+    /** The top-level sequence flows (sub-processes nest their own). */
+    flows: BpmnFlow[];
+    /** Process-level metadata from `.metadata()`, when any was declared. */
+    metadata?: ProcessMetadata;
+    /** Named schemas from `.schema()`, which a row's `schema` may reference by id. */
+    schemas: Map<string, unknown>;
+}
+/**
+ * Process-level metadata — the `uipath:*` children of the process's own
+ * `extensionElements` that describe the DOCUMENT rather than any element in it.
+ *
+ * Every field here is optional and omitted entirely when unset, because an empty
+ * declaration is not the same as an absent one: `uipath:migrationVersion` with no
+ * `version` fails product validation outright, so a half-filled block is worse than
+ * none. The moddle descriptor has always declared these types; only the builder had no
+ * way to reach them.
+ */
+export interface ProcessMetadata {
+    /**
+     * Canvas schema generation the document targets (`uipath:migrationVersion`), e.g.
+     * `'11'` or `'11.5'`. Studio Web stamps it on export and some graders require it, so
+     * a process that omits it is not what the platform round-trips.
+     *
+     * `.schemaVersion(v)` sets the same field under the name the Flow and Case
+     * builders use for the same concept, and is what `bpmn-decompile` emits.
+     */
+    migrationVersion?: string;
+    /** The root start event's package entry-point id (`uipath:entryPointId`). */
+    entryPointId?: string;
+    /** Free-form document tags (`uipath:tags` / `uipath:tag`). */
+    tags?: string[];
+    /** Case-management marker (`uipath:caseManagement`) — `version` plus its body value. */
+    caseManagement?: {
+        version: string;
+        value?: string;
+    };
+    /**
+     * `bpmn:process/@isExecutable`. Defaults to `true`.
+     *
+     * Worth modelling because the serializer used to hardcode `true`, so a
+     * decompile-recompile of a NON-executable process silently turned it executable — a
+     * draft or diagram-only document promoted to a runnable one, with nothing said. It is
+     * the only `bpmn:process` attribute the builder did not carry.
+     */
+    executable?: boolean;
+}
+/**
+ * An extension payload carried by an element the payload does not describe.
+ *
+ * The product hangs a `uipath:mapping` off a start event (mapping process inputs
+ * onto variables), an end event (variables onto process outputs) and a
+ * sub-process, and a `uipath:activity` off an error boundary to capture the error
+ * payload. In each case the element kind is what the element IS, and the payload
+ * only decorates it — so this rides as an option on that element's own builder
+ * method rather than turning it into a task.
+ *
+ * Rows are emitted verbatim, which is what makes an imported event round-trip:
+ * the product's `name` is the SOURCE variable's display name, not the target's,
+ * and no derivation reproduces that.
+ *
+ * @example
+ * **A start event mapping two process inputs onto variables**
+ * ```ts
+ * bpmn('intake')
+ *   .input('vClaimId', 'string', { name: 'in_claimId' })
+ *   .var('claimId', 'string', { name: 'in_claimId' })
+ *   .startEvent('start', {
+ *     payload: {
+ *       type: 'BPMN.Variables',
+ *       outputRows: [{ name: 'in_claimId', type: 'string', source: '=vars.vClaimId', var: 'claimId' }],
+ *     },
+ *   })
+ *   .endEvent('done')
+ *   .sequenceFlow('start', 'done')
+ *   .build();
+ * ```
+ */
+export interface ExtensionPayload {
+    /** The extension type, e.g. `'BPMN.Variables'` or `'uipath:Activity'`. */
+    type: string;
+    /** `uipath:output` rows, emitted exactly as given — see {@link TypedOutputRow}. */
+    outputRows: TypedOutputRow[];
+}
+/**
+ * Options for `.startEvent()`. At most one of `message` / `timer` picks the
+ * event definition (`timer` wins if both are set); neither means a plain start.
+ */
+export interface StartOpts {
+    /** Display name the designer shows on the event. */
+    name?: string;
+    /** Start when this message arrives — declares/reuses a definitions-level `bpmn:message`. */
+    message?: string;
+    /**
+     * Catch an error — an INTERRUPTING error start event
+     * (`bpmn:errorEventDefinition`), declaring/reusing a definitions-level
+     * `bpmn:error`. Pass a name, or `{ name, code }` when the wire code differs.
+     *
+     * @remarks
+     * Only legal as the single start event of an **event sub-process**
+     * (`.subProcess(id, fn, { triggeredByEvent: true })`) — that is the construct BPMN
+     * has for catching an error thrown elsewhere in the same container. At the process
+     * root it is meaningless: nothing can throw into it, so the branch is dead. `check()`
+     * reports that as `ERROR_START_OUTSIDE_EVENT_SUBPROCESS` rather than leaving it to
+     * be discovered at run time, because `uip maestro bpmn validate` accepts it.
+     *
+     * Interrupting is the only form emitted: `isInterrupting` is left unset, which is
+     * BPMN's default and what the platform's own templates produce. A
+     * non-interrupting error start is not a thing — the throw has already ended its
+     * scope by the time the handler sees it.
+     */
+    error?: ErrorLike;
+    /** Start on a timer — an ISO-8601 duration string, or a full {@link TimerSpec}. */
+    timer?: TimerLike;
+    /**
+     * Also declare this timed start as a platform TRIGGER (`Intsvc.TimerTrigger`).
+     *
+     * @remarks
+     * Requires `timer`, and refuses to be set without it.
+     *
+     * **What this does and does not add.** The schedule lives in the
+     * `bpmn:timerEventDefinition` that `timer` already writes — that is what the
+     * platform's scheduler reads, and it is what the product's own Flow→BPMN
+     * converter emits for `.trigger(scheduled(…))`, with no extension at all. This
+     * flag adds the other half: a `uipath:activity` payload naming the node type, so
+     * the designer renders it as a Timer trigger rather than a bare timed start, plus
+     * one output row carrying the fire payload into a variable.
+     *
+     * So the two are orthogonal, not alternatives, which is why this is a flag rather
+     * than a separate method — and why it cannot be set alone. The registry declares
+     * NO context fields for the type, so `outputVar` is the only thing to configure;
+     * it defaults to `<id>_result`.
+     *
+     * Setting it without `timer` would emit `<bpmn:timerEventDefinition />` empty — a
+     * trigger with no schedule — and `uip maestro bpmn validate` calls that `Valid`,
+     * so nothing downstream would catch it.
+     *
+     * @example
+     * **The same schedule, bare and then declared as a trigger**
+     * ```ts
+     * // bare — the shape the platform's own Flow→BPMN converter emits
+     * bpmn('nightly')
+     *   .startEvent('start', { timer: { cycle: 'R/P1D' } })
+     *   .scriptTask('rollup', { script: 'return { ok: true };' })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'rollup')
+     *   .sequenceFlow('rollup', 'done')
+     *   .build();
+     *
+     * // typed — same schedule, plus designer identity and a payload variable
+     * bpmn('nightly')
+     *   .startEvent('start', { timer: { cycle: 'R/P1D' }, trigger: { outputVar: 'tick' } })
+     *   .scriptTask('rollup', { script: 'return { ok: true };' })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'rollup')
+     *   .sequenceFlow('rollup', 'done')
+     *   .build();
+     * ```
+     */
+    trigger?: true | {
+        outputVar?: string;
+    };
+    /** A `uipath:mapping` mapping process inputs onto variables — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+}
+/**
+ * Options for `.endEvent()`. `terminate`, `error`, or `message` picks the event
+ * definition, checked in that order; none of them means a plain end.
+ */
+export interface EndOpts {
+    /** Display name the designer shows on the event. */
+    name?: string;
+    /** End as a TERMINATE event — abort the whole process instance, not just this path. */
+    terminate?: boolean;
+    /** End by throwing this message — declares/reuses a definitions-level `bpmn:message`. */
+    message?: string;
+    /**
+     * End by throwing this error (a name, or `{ name, code }`) — declares/reuses a
+     * definitions-level `bpmn:error`.
+     *
+     * Deliberately narrower than {@link ErrorLike}: catch-any has no meaning on a
+     * THROW, which has to say what it throws.
+     */
+    error?: string | {
+        name: string;
+        code?: string;
+    };
+    /** A `uipath:mapping` mapping variables onto process outputs — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+}
+/**
+ * Options for `.intermediateCatchEvent()`. `message` or `timer` picks what the
+ * event waits for (`timer` wins if both are set).
+ */
+export interface CatchOpts {
+    /** Display name the designer shows on the event. */
+    name?: string;
+    /** Wait for this message — declares/reuses a definitions-level `bpmn:message`. */
+    message?: string;
+    /** Wait for a timer — an ISO-8601 duration string, or a full {@link TimerSpec}. */
+    timer?: TimerLike;
+    /** An extension payload on the event — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+}
+/** Options for `.intermediateThrowEvent()` — a `message` to throw, or none. */
+export interface ThrowOpts {
+    /** Display name the designer shows on the event. */
+    name?: string;
+    /** The message to throw — declares/reuses a definitions-level `bpmn:message`. */
+    message?: string;
+    /** An extension payload on the event — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+}
+/**
+ * Options for `.boundaryEvent()`: the activity it attaches to, whether it
+ * interrupts that activity, and the event definition — exactly one of
+ * `message` / `timer` / `error` (checked in the order error, timer, message;
+ * none at all is refused).
+ */
+export interface BoundaryOpts {
+    /** Display name the designer shows on the event. */
+    name?: string;
+    /** id of the activity this boundary event is attached to. */
+    attachedTo: string;
+    /** true (default) = interrupting; false = non-interrupting. */
+    cancelActivity?: boolean;
+    /** Catch this message — declares/reuses a definitions-level `bpmn:message`. */
+    message?: string;
+    /** Fire on a timer — an ISO-8601 duration string, or a full {@link TimerSpec}. */
+    timer?: TimerLike;
+    /**
+     * Catch an error: `true` for ANY error, or a name (or `{ name, code }`) to catch
+     * one declared kind — see {@link ErrorLike}.
+     */
+    error?: ErrorLike;
+    /** A `uipath:activity` capturing the error payload — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+}
+/** Options for `.exclusiveGateway()` / `.inclusiveGateway()`. */
+export interface GatewayOpts {
+    /** Display name the designer shows on the gateway. */
+    name?: string;
+    /** Outgoing flow id taken when no condition matches (exclusive/inclusive). */
+    default?: string;
+}
+/**
+ * Retry an activity that fails (`uipath:retry`).
+ *
+ * @example
+ * **Three retries, backing off 1s, then 2s, then 4s**
+ * ```ts
+ * bpmn('sync')
+ *   .startEvent('start')
+ *   .scriptTask('fetch', {
+ *     script: 'return { ok: true };',
+ *     retry: { maxRetries: 3, backoff: 'PT1S', backoffType: 'exponential', exponentialBase: 2 },
+ *   })
+ *   .endEvent('done')
+ *   .sequenceFlow('start', 'fetch')
+ *   .sequenceFlow('fetch', 'done')
+ *   .build();
+ * ```
+ */
+export interface RetrySpec {
+    /**
+     * How many times to retry AFTER the first attempt — so `3` means up to four
+     * runs in total. Must be a positive integer; the runtime ignores a policy with
+     * a count of zero or less.
+     */
+    maxRetries: number;
+    /**
+     * Wait this long before retrying, as an ISO-8601 duration (`'PT30S'`, `'PT1M'`,
+     * `'P1DT12H'`). Days, hours, minutes and seconds only — the runtime's duration
+     * parser does not accept weeks, months or years.
+     */
+    backoff?: string;
+    /**
+     * `'static'` (default) waits `backoff` before every retry; `'exponential'`
+     * multiplies it by {@link RetrySpec.exponentialBase} each time.
+     */
+    backoffType?: 'static' | 'exponential';
+    /** Multiplier for `'exponential'` backoff, e.g. `2` for 1s → 2s → 4s. */
+    exponentialBase?: number;
+    /** Retry every failure, not only the ones the platform marks retryable. */
+    allErrors?: boolean;
+    /** Give up after this much total elapsed time, as an ISO-8601 duration. */
+    maxDuration?: string;
+}
+/**
+ * What every ACTIVITY accepts, on top of its own options — a script task, a
+ * variable task, a connector task, a sub-process.
+ *
+ * Note what is *not* here: `skipCondition`. Skipping is carried on a
+ * `uipath:activity`, and a script or variable task must use `uipath:mapping`
+ * instead (`uip maestro bpmn validate` rejects `BPMN.Variables` under
+ * `uipath:activity`), which has no such attribute — so an authored skip on one
+ * would be silently dropped in serialization and the step would run anyway. It
+ * therefore lives on {@link BpmnConnectorOpts} alone, where it works.
+ */
+export interface ActivityOpts {
+    /**
+     * `uipath:tags` on the activity — key/value pairs the designer carries alongside
+     * the node, as a SIBLING of its payload.
+     *
+     * Distinct from `.metadata({ tags })`, which is the process-level `uipath:Tags`
+     * and is a plain list of values. This one is per-node and keyed: every service
+     * task in the real exports carries `caseTaskType` this way (143 rows across five
+     * files), and nothing could express it.
+     */
+    tags?: Record<string, string>;
+    /** Retry the activity when it fails — see {@link RetrySpec}. */
+    retry?: RetrySpec;
+    /** Run it once per item of a collection — see {@link LoopSpec}. */
+    loop?: LoopSpec;
+    /**
+     * Classify the activity's failures — see {@link ErrorMappingRow}.
+     *
+     * Most useful alongside `retry` WITHOUT `allErrors`: such a policy retries only the
+     * codes marked `retryable` here, and with no mapping it retries nothing at all.
+     */
+    errorMapping?: ErrorMappingRow[];
+}
+/** Options for `.scriptTask()` — the Jint JavaScript body and its input/output mappings. */
+export interface ScriptTaskOpts extends ActivityOpts {
+    /** Display name the designer shows on the task. */
+    name?: string;
+    /**
+     * The script body (Jint JavaScript). Each `inputs` key is available as a
+     * top-level identifier (for example `inputs: { amount: '=vars.amount' }`
+     * makes the script read `amount`, not `args.amount`).
+     */
+    script: string;
+    /** The script language marker. Defaults to `'JavaScript'` (Jint). */
+    scriptFormat?: string;
+    /** `uipath:input` rows: field name → `=`-expression read into the script. */
+    inputs?: Record<string, string>;
+    /**
+     * `uipath:output` rows: variable id → `=`-expression.
+     *
+     * @remarks
+     * **Read `=result.response`, not `=result.<field>`.** The serializer emits
+     * `<uipath:scriptVersion value="v3" />`, and the runtime wraps a v2-or-later
+     * script task's return value: `ScriptActivities.DoInvokeScriptTaskAsync` in
+     * PO.BpmnEngine returns `{ "response": <whatever the script returned> }` when
+     * `IsVersionAtLeast(version, 2)`. So the script may return any JSON value and
+     * `=result.response` is that value; `=result.Error` is its error slot.
+     *
+     * Only a v1 script task spreads the return object's fields, and it must return an
+     * object or the activity throws. This SDK does not emit v1.
+     */
+    outputs?: Record<string, string>;
+    /**
+     * Output rows spelled out, replacing the ones `outputs` derives — see
+     * {@link TypedOutputRow}.
+     *
+     * For importers. `outputs` names each row after the VARIABLE it writes, which is
+     * right when you are authoring one; the product names it after the value the
+     * script returns (`scriptResponse`, `Error`) and binds a differently-named
+     * variable, and no derivation reproduces that pair.
+     */
+    outputRows?: TypedOutputRow[];
+    /**
+     * The `uipath:inputSchema` body inside the mapping's `uipath:context` — a JSON
+     * Schema for the `args` the script receives. Real script tasks all carry one.
+     */
+    inputSchema?: unknown;
+    /**
+     * The mapping's extension type. Defaults to `'BPMN.Variables'`, which is the
+     * only value the runtime contract defines.
+     *
+     * @remarks
+     * **There is no second valid value.** `BPMN.Variables` "is intended to be the
+     * common description for the context/input/output section in the
+     * `uipath:mapping`", and the script itself rides in the native `<bpmn:script>`
+     * tag — so a script task differs from a variables task by its ELEMENT, not by
+     * its extension type. `BPMN.ScriptTask`, which this SDK used to emit, "is not a
+     * valid type for `uipath:type`" (Maestro runtime contract owner, 2026-08-28;
+     * see the *BPMN Metamodel Runtime Contract — Script task* page).
+     *
+     * That matches the artifacts exactly: all 29 script tasks across the five real
+     * Studio Web exports in `research/bpmn-roundtrip` are `BPMN.Variables`, and none
+     * is anything else. `uip maestro bpmn validate` accepts both, so nothing in the
+     * toolchain catches the wrong one — which is why the SDK emitted it for so long.
+     *
+     * The option is kept rather than removed because it shipped (v3.25.0), and an
+     * importer may still meet a legacy artifact carrying the invalid value. Decompile
+     * does NOT preserve it: reproducing markup the contract rejects is propagating a
+     * defect, not fidelity — the same call the round trip already makes for a bare
+     * `<uipath:input name="args">`.
+     */
+    type?: string;
+}
+/** Options for `.task()` — a display name and the variable assignments the task makes. */
+export interface TaskOpts extends ActivityOpts {
+    /** Display name the designer shows on the task. */
+    name?: string;
+    /**
+     * Variable assignments (`BPMN.Variables`): variable id → the value to assign.
+     *
+     * A value starting with `=` is an expression evaluated against the surrounding
+     * variables (`'=js:vars.total + 1'`). Anything else is a **string literal**
+     * (`'hello'`), which the serializer wraps into an equivalent expression — so
+     * to assign a number or a boolean, write it as an expression (`'=js:5'`),
+     * since `'5'` assigns the string.
+     */
+    set?: Record<string, string>;
+}
+/** Options for `.subProcess()`. */
+export interface SubProcessOpts extends ActivityOpts {
+    /** Display name the designer shows on the sub-process. */
+    name?: string;
+    /** Mark an EVENT sub-process — started by an event inside it, not by an incoming flow. */
+    triggeredByEvent?: boolean;
+    /**
+     * A `uipath:mapping` on the sub-process itself, mapping its results back out to
+     * the enclosing scope's variables — see {@link ExtensionPayload}.
+     *
+     * Distinct from the variables the sub-process DECLARES (`sp.var(…)` inside the
+     * body), which are its own scope; this is the handoff at its boundary.
+     */
+    payload?: ExtensionPayload;
+}
+/** Options for `.binding()`. */
+export interface BindingOpts {
+    /** Display name the designer shows. Defaults to the binding's id. */
+    name?: string;
+    /**
+     * The value the binding resolves to when nothing overrides it — which is what
+     * an offline run reads, so it is the one field a local run needs.
+     */
+    value?: string;
+    /**
+     * The kind of resource this identifies. Defaults to `'custom'`, which is the
+     * right answer for a plain configurable value; use the registry's resource name
+     * (`'Connection'`, `'process'`, `'queue'`, `'businessRule'`) when the binding
+     * addresses one of those.
+     */
+    resource?: string;
+    /** Which property of that resource is wanted. Defaults to `'value'`. */
+    propertyAttribute?: string;
+    /** The resource's key, when it differs from {@link BindingOpts.value}. */
+    resourceKey?: string;
+    /**
+     * Narrows the resource, e.g. `'Agent'` for an agent process.
+     *
+     * Some extension types require it and none of them state it — `.startAgent()`
+     * supplies it from `REGISTRY_GAPS`. It is exposed here so a hand-written or
+     * DECOMPILED binding can reproduce one, which is what keeps a round-trip exact.
+     */
+    resourceSubType?: string;
+}
+/**
+ * Options for `.http()` — an `Intsvc.UnifiedHttpRequest` node.
+ *
+ * The field names are the registry's own context fields, so what you write is
+ * what the platform reads. `mode` is required-and-hidden in the registry and
+ * always emitted as `manual`; it is not an option because there is nothing to
+ * choose.
+ */
+export interface HttpOpts extends ActivityOpts {
+    /** Display name the designer shows on the task. */
+    name?: string;
+    /** Request URL. Accepts an `=`-expression, including `=bindings.<id>`. */
+    url: string;
+    /** HTTP method. Defaults to `'GET'`, matching the registry's own default. */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    /** Request headers — serialized to the node's json context field. */
+    headers?: Record<string, unknown>;
+    /** Query parameters — serialized to the node's json context field. */
+    parameters?: Record<string, unknown>;
+    /** Request body — serialized to the node's json context field. */
+    body?: unknown;
+    /**
+     * EXTRA output rows: variable id → `=`-expression read against the node's own result,
+     * e.g. `{ runStatus: '=Status' }`.
+     *
+     * Needed for the same reason `.humanTask()` has it: this family declares a TYPED output
+     * (`type="Orchestrator.RunJob"` and friends) with no `source`, which the designer resolves
+     * into sub-fields but the local engine cannot — so the variable stays `undefined` on a local
+     * run and nothing downstream can read or branch on it. An explicit row maps one field the
+     * way every other output row works. The spec's own row is still emitted, so the artifact
+     * stays what the platform expects.
+     */
+    outputs?: Record<string, string>;
+    /** Variable the response lands in. Defaults to `<id>_response`. */
+    outputVar?: string;
+    /** `=`-expression that skips the request when truthy. */
+    skipCondition?: string;
+}
+/**
+ * What every Orchestrator invocation needs: which process, in which folder, with
+ * what input.
+ *
+ * `process` becomes the node's `name` context field, which is what the runtime
+ * resolves a release key from — so a process is addressed by NAME, not by key, and
+ * the same artifact works against any tenant that has one by that name. Pass
+ * `releaseKey` only when you have a binding for the key itself.
+ */
+export interface OrchestratorOpts extends ActivityOpts {
+    /** Display name the designer shows on the node. */
+    name?: string;
+    /** The Orchestrator process to start, by name. */
+    process: string;
+    /** Folder path the process lives in. Omit for the personal/default folder. */
+    folder?: string;
+    /** Input arguments — serialized as the node's `JobArguments` body. */
+    input?: Record<string, unknown>;
+    /** The release key, when a binding supplies it (`=bindings.<id>`). */
+    releaseKey?: string;
+    /**
+     * EXTRA output rows: variable id → `=`-expression read against the node's own result,
+     * e.g. `{ runStatus: '=Status' }`.
+     *
+     * Needed for the same reason `.humanTask()` has it: this family declares a TYPED output
+     * (`type="Orchestrator.RunJob"` and friends) with no `source`, which the designer resolves
+     * into sub-fields but the local engine cannot — so the variable stays `undefined` on a local
+     * run and nothing downstream can read or branch on it. An explicit row maps one field the
+     * way every other output row works. The spec's own row is still emitted, so the artifact
+     * stays what the platform expects.
+     */
+    outputs?: Record<string, string>;
+    /** Variable the job response lands in. Defaults to `<id>_processResponse`. */
+    outputVar?: string;
+    /** `=`-expression that skips the invocation when truthy. */
+    skipCondition?: string;
+}
+/** Options for the two agentic/case call activities, which come in sync and async forms. */
+export interface OrchestratorAsyncOpts extends OrchestratorOpts {
+    /**
+     * `true` starts the process and carries on without waiting (`…Async`), so only
+     * an error is mapped back. Default `false` — start and wait.
+     */
+    async?: boolean;
+}
+/**
+ * Options for `.queueItem()`.
+ *
+ * `folder` is REQUIRED here, unlike the process family: queue items are
+ * folder-scoped and the runtime refuses to dispatch without a folder path
+ * (`queue items are folder-scoped; supply its binding`). The registry marks the
+ * field optional, so this is the SDK being stricter than the spec on purpose.
+ */
+export interface QueueItemOpts extends ActivityOpts {
+    /** Display name the designer shows on the node. */
+    name?: string;
+    /** The queue to add the item to. */
+    queue: string;
+    /** Folder path the queue lives in. */
+    folder: string;
+    /** The item's content — serialized as the node's `ItemData` body. */
+    item?: Record<string, unknown>;
+    /**
+     * `true` waits for the item to be processed and maps its outcome back
+     * (`Orchestrator.CreateAndWaitForQueueItem`); default adds it and carries on.
+     */
+    wait?: boolean;
+    /**
+     * EXTRA output rows: variable id → `=`-expression read against the node's own result,
+     * e.g. `{ runStatus: '=Status' }`.
+     *
+     * Needed for the same reason `.humanTask()` has it: this family declares a TYPED output
+     * (`type="Orchestrator.RunJob"` and friends) with no `source`, which the designer resolves
+     * into sub-fields but the local engine cannot — so the variable stays `undefined` on a local
+     * run and nothing downstream can read or branch on it. An explicit row maps one field the
+     * way every other output row works. The spec's own row is still emitted, so the artifact
+     * stays what the platform expects.
+     */
+    outputs?: Record<string, string>;
+    /** Variable the response lands in. Defaults to `<id>_response`. */
+    outputVar?: string;
+    /** `=`-expression that skips the enqueue when truthy. */
+    skipCondition?: string;
+}
+/**
+ * Options for `.humanTask()` — an `Actions.HITL` action-app task.
+ *
+ * `app` is the Action App's id and the registry marks it the type's primary key,
+ * so it comes from the tenant (`RequiresDiscovery: Yes`). Nothing offline can
+ * resolve it: pass the id, or a `=bindings.<id>` reference so it is configurable
+ * per environment.
+ */
+export interface HumanTaskOpts extends ActivityOpts {
+    /** Display name the designer shows on the task. */
+    name?: string;
+    /** The Action App's id (`appId`). Tenant-specific — see the remarks above. */
+    app: string;
+    /** The app version (`appVersion`). */
+    appVersion?: number;
+    /**
+     * The outcomes a human can pick, e.g. `['approve', 'reject']`.
+     *
+     * Joined with commas. The registry types this field as a bare `string` and says
+     * nothing about its encoding, and `uip maestro bpmn validate` accepts a
+     * comma-joined list, a JSON array, a single word and an empty string alike — so
+     * this is the plausible reading, not a verified one. If a LIVE run mis-reads the
+     * outcomes, this is the first thing to compare against a Studio Web export.
+     */
+    actions?: string[];
+    /** The task title a human sees (`taskTitle`). */
+    title?: string;
+    /** An existing task key, when resuming rather than creating (`key`). */
+    key?: string;
+    /** Data the task shows the human — the node's `HitlTaskArguments`. */
+    input?: Record<string, unknown>;
+    /**
+     * Fields to pull out of the human's response into variables, e.g.
+     * `{ decision: '=Action' }`.
+     *
+     * Worth setting whenever a gateway branches on the outcome. The type's own
+     * output row is typed (`type="Actions.HITL"`, no `source`), which the designer
+     * resolves but the local runtime leaves `undefined` — so without a mapped field
+     * here, a local run cannot branch on the decision at all. `=Action` is the field
+     * the runtime's own outcome routing reads.
+     */
+    outputs?: Record<string, string>;
+    /** Variable the whole typed response lands in. Defaults to `<id>_processResponse`. */
+    outputVar?: string;
+    /** `=`-expression that skips the task when truthy. */
+    skipCondition?: string;
+}
+/**
+ * Options for `.receiveMessage()` — `Maestro.ReceiveMessageEvent`.
+ *
+ * The typed counterpart of `.intermediateCatchEvent({ message })`, and NOT the same
+ * thing on the wire. The plain form declares a definitions-level `bpmn:message` and
+ * points the event's `messageRef` at it; the typed form carries the message name in
+ * its own `uipath:context` and takes a correlation `reference`. Reach for this one
+ * when the sender is another Maestro process; the plain form for ordinary BPMN
+ * message flow.
+ */
+export interface ReceiveMessageOpts extends ActivityOpts {
+    /** Display name the designer shows on the event. */
+    name?: string;
+    /** The message name to wait for — the type's required `name` context field. */
+    message: string;
+    /**
+     * Correlation reference matching this receive to its sender.
+     *
+     * Required by the registry. Emitted as its own `uipath:input` row targeting
+     * `bodyField`, which is the field's declared target rather than its key — see
+     * `RegistryInputField.target` for why that distinction cost a defect.
+     */
+    reference: string;
+    /** Variable the typed response lands in. Defaults to `<id>_response`. */
+    outputVar?: string;
+    /** `=`-expression that skips the event when truthy. */
+    skipCondition?: string;
+    /**
+     * There is deliberately NO `outputs` here, unlike `.humanTask()`.
+     *
+     * This type permits exactly ONE output row. A second is refused by the platform:
+     *
+     *     [error] Maestro.ReceiveMessageEvent output name must be "response".
+     *     [error] Maestro.ReceiveMessageEvent output type must be "Maestro.ReceiveMessageEvent".
+     *
+     * Which is not derivable from the registry — `Actions.HITL` declares a
+     * structurally IDENTICAL output (a typed row, no `source`) and accepts a mapped
+     * second row happily, which is the whole basis of offline approval routing. So
+     * the constraint is recorded in `REGISTRY_GAPS` rather than inferred, and this
+     * option simply does not exist. Read the message with `outputVar` and an
+     * expression against the typed row instead.
+     */
+    readonly outputs?: never;
+}
+/**
+ * Shared options for the two connector-event methods.
+ *
+ * `connection` and `folder` are SYMBOLIC binding names, exactly as `.connector()`
+ * takes them — the offline rungs compile them to `=bindings.<name>` and only a live
+ * run needs real ids. Both are required by the platform: the type declares
+ * `connectionId`, `folderId`, `folderPath` and `folderKey` all required, so a node
+ * missing either is refused at serialize rather than by the CLI a build later.
+ */
+export interface ConnectorEventOpts extends ActivityOpts {
+    /** Display name; defaults to the descriptor's own label. */
+    name?: string;
+    /** Symbolic binding name for the Integration Service connection. */
+    connection: string;
+    /** Symbolic binding name for the folder. */
+    folder: string;
+    /** The folder path the type requires alongside the key. Defaults to `/Shared`. */
+    folderPath?: string;
+    /** Pin the descriptor version, as `.connector()` does. */
+    version?: string;
+    /**
+     * The `where` scope narrowing the subscription, when the operation declares
+     * parameters. `Library.eventParameterFields()` is the authority on which names an
+     * operation accepts — and note that "declares none" is a real answer for some
+     * operations (HTTP Webhook scopes by the connection), not a lookup failure.
+     */
+    filter?: Record<string, unknown>;
+    /** Extra event parameters, for operations that declare them. */
+    parameters?: Record<string, unknown>;
+    /** Variable the event payload lands in. Defaults to `<id>_result`. */
+    outputVar?: string;
+    /**
+     * Fields to pull out of the payload into variables, e.g. `{ amount: '=amount' }`.
+     *
+     * Worth setting whenever anything branches on the payload. The type's own row is
+     * `type="custom" source="."` — the whole result — which the local engine does NOT
+     * resolve, so the default variable is `undefined` on a local run and nothing can
+     * branch on it. A mapped row IS resolved, and unlike `Maestro.ReceiveMessageEvent`
+     * this family accepts one: verified `Valid`, with both gateway arms exercised
+     * offline via `--mock-data`.
+     */
+    outputs?: Record<string, string>;
+    /** `=`-expression that skips the node when truthy. */
+    skipCondition?: string;
+}
+/** Options for `.externalAgent()` / `.externalWorkflow()`. */
+export interface ExternalTaskOpts extends ActivityOpts {
+    /** Display name; defaults to the descriptor's own label. */
+    name?: string;
+    /** `sync` waits for the result; `async` starts it and moves on. */
+    mode: 'sync' | 'async';
+    /** Symbolic binding name for the Integration Service connection. */
+    connection: string;
+    /** Symbolic binding name for the folder. */
+    folder: string;
+    /** Pin the descriptor version. */
+    version?: string;
+    /** Variable the response lands in. Defaults to `<id>_result`. */
+    outputVar?: string;
+    /** Fields to pull out of the response into variables — see {@link ConnectorEventOpts.outputs}. */
+    outputs?: Record<string, string>;
+    /** `=`-expression that skips the node when truthy. */
+    skipCondition?: string;
+}
+/**
+ * Options for `.activity()` — the generic registry-backed node.
+ *
+ * Field names are the registry's own, so this is the same surface the typed
+ * methods sit on: `context` are the `uipath:context` inputs, `inputs` the payload
+ * shaped by the type's `inputPattern`.
+ */
+export interface ActivityNodeOpts extends ActivityOpts {
+    /** Display name the designer shows. */
+    name?: string;
+    /** `uipath:context` values, by the registry's field names. */
+    context?: Record<string, unknown>;
+    /**
+     * Context rows spelled out, replacing `context` — see {@link TypedContextRow}.
+     *
+     * For importers. `context` is a name→value record, so a row's declared type comes
+     * from the registry and a field the registry does not declare is written
+     * `type="string"`; these rows carry their own.
+     */
+    contextRows?: TypedContextRow[];
+    /** The payload, shaped by the type's `inputPattern`. */
+    inputs?: Record<string, unknown>;
+    /** Variable the type's own output lands in. Defaults to `<id>_<outputName>`. */
+    outputVar?: string;
+    /** Extra output rows: variable id → `=`-expression against the node's result. */
+    outputs?: Record<string, string>;
+    /**
+     * The output rows spelled out, replacing `outputVar` and `outputs`. Set by
+     * `bpmn-decompile` when a row carries detail those cannot express — a
+     * connector's `jsonSchema` rows and their schema bodies. See
+     * {@link TypedOutputRow}.
+     */
+    outputRows?: TypedOutputRow[];
+    /**
+     * The `uipath:type` `version` attribute. Defaults to `'v1'`, which is what the
+     * registry's own `XmlTemplate` writes.
+     *
+     * @remarks
+     * Set this only to reproduce an imported artifact. Every `Orchestrator.*` and
+     * `Actions.HITL` node across five real Studio Web exports carries `version="v2"`,
+     * while the registry snapshot the SDK emits from still says `v1` — refreshing it
+     * against the live tenant changes nothing but the provenance string, so the
+     * registry is simply behind the writer. Both pass `uip maestro bpmn validate`.
+     *
+     * The authoring default follows the registry rather than the corpus, on the same
+     * reasoning as {@link ScriptTaskOpts.type}: an import must not silently rewrite
+     * what it found, and the SDK must not pick a side on the strength of five files.
+     */
+    typeVersion?: string;
+    /**
+     * The `uipath:inputSchema` body inside `uipath:context` — a JSON Schema for the
+     * payload the node accepts.
+     *
+     * A string is written through untouched; anything else is JSON-stringified. Real
+     * exports carry one on nearly every connector, agent and API-workflow call (173
+     * across five files), and it survived nothing before this existed.
+     */
+    inputSchema?: unknown;
+    /** `=`-expression that skips the node when truthy (activity/event tags only). */
+    skipCondition?: string;
+    /**
+     * Emit `context` exactly as given, injecting no registry defaults. Set by
+     * `bpmn-decompile` so an imported artifact round-trips unchanged; an author
+     * writing `.activity()` by hand wants the defaults.
+     */
+    contextVerbatim?: boolean;
+}
+/**
+ * The BPMN task elements that are legal with NO `uipath:*` payload.
+ *
+ * All seven validate clean as bare elements — `uip maestro bpmn validate` accepts every
+ * one — so an artifact can legitimately contain them and the builder has to be able to
+ * say so. See {@link ScopeBuilder.plainTask}.
+ */
+export type PlainTaskElement = 'bpmn:task' | 'bpmn:userTask' | 'bpmn:serviceTask' | 'bpmn:sendTask' | 'bpmn:manualTask' | 'bpmn:businessRuleTask' | 'bpmn:receiveTask';
+/** Options for `.plainTask()`. */
+export interface PlainTaskOpts extends ActivityOpts {
+    /** Display name the designer shows. */
+    name?: string;
+    /** Which task element to emit. Defaults to `bpmn:task`. */
+    element?: PlainTaskElement;
+}
+/** Options for `.sequenceFlow()`. */
+export interface FlowOpts {
+    /** The flow's element id. Defaults to `Flow_<source>_<target>`. */
+    id?: string;
+    /** Edge label the designer shows. */
+    name?: string;
+    /** `=`-expression gating this flow (exclusive/inclusive gateway outgoing). */
+    condition?: string;
+}
+/** Options for `.var()` / `.input()` / `.output()`. */
+export interface VarOpts {
+    /** Display name; defaults to the variable's id. */
+    name?: string;
+    /** Optional initial value. */
+    default?: unknown;
+    /** When set, the variable is scoped to that element rather than root/global. */
+    elementId?: string;
+    /**
+     * The declaration's BODY — a JSON Schema describing the shape of a `jsonSchema`
+     * (or `json`) variable.
+     *
+     * A JSON value is written as-is. A string is either the ID of a schema declared
+     * with {@link BpmnBuilder.schema}, or — when it names none — raw JSON text passed
+     * through untouched. The schema is carried, never interpreted, so a field this SDK
+     * does not know about survives.
+     *
+     * Real exports put one on nearly every structured variable — 332 rows across five
+     * of them — and without somewhere to keep it the row round-tripped as a bare
+     * declaration with its shape erased.
+     */
+    schema?: unknown;
+    /** Mark the declaration `required="true"`, as a process input can be. */
+    required?: boolean;
+}
+/**
+ * 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}.
+ */
+declare class BindingsRegistry {
+    /** Every declared binding, in declaration order — `BuiltBpmn.bindings`. */
+    readonly bindings: BindingDecl[];
+    /**
+     * 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: BindingDecl): BindingDecl;
+    /**
+     * @param id - The binding id to look for.
+     * @returns Whether that id is already declared.
+     */
+    has(id: string): boolean;
+}
+/** Collects definitions-level message/error declarations, de-duped by name. */
+declare class DefinitionsRegistry {
+    /** Every declared message, in declaration order — `BuiltBpmn.messages`. */
+    readonly messages: MessageDecl[];
+    /** Every declared error, in declaration order — `BuiltBpmn.errors`. */
+    readonly errors: ErrorDecl[];
+    private readonly messageByName;
+    private readonly errorByName;
+    /**
+    * 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: string): string;
+    /**
+    * 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: string, code?: string): string;
+}
+/**
+ * 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).
+ */
+declare abstract class ScopeBuilder {
+    /** @internal */
+    protected readonly _nodes: BpmnNode[];
+    /** @internal */
+    protected readonly _flows: BpmnFlow[];
+    /** @internal */
+    protected readonly _vars: BpmnVarDecl[];
+    /** @internal */
+    protected readonly _defs: DefinitionsRegistry;
+    /** @internal */
+    protected readonly _bindingRegistry: BindingsRegistry;
+    /**
+     * @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: DefinitionsRegistry, bindings: BindingsRegistry);
+    private push;
+    /**
+     * 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: string, opts?: StartOpts): this;
+    /**
+     * 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: string, opts?: EndOpts): this;
+    /**
+     * 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: string, opts?: CatchOpts): this;
+    /**
+     * 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: string, opts?: ThrowOpts): this;
+    /**
+     * 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: string, opts: BoundaryOpts): this;
+    private startCatchDef;
+    /**
+    * 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: string, opts?: GatewayOpts): this;
+    /**
+    * 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: string, opts?: {
+        name?: string;
+    }): this;
+    /**
+    * 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: string, opts?: GatewayOpts): this;
+    /**
+    * 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: string, opts?: {
+        name?: string;
+    }): this;
+    /**
+     * 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: string, opts: ScriptTaskOpts): this;
+    /**
+     * 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: string, opts?: TaskOpts): this;
+    /**
+     * 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: string, opts?: PlainTaskOpts): this;
+    /**
+     * An Integration Service **connector** service task (`bpmn:sendTask` +
+     * `uipath:activity` / `Intsvc.ActivityExecution`) — the typed form, where a
+     * generated descriptor supplies the operation and its input types.
+     *
+     * @remarks
+     * Identify the op by a typed descriptor or by `key`/`action` (like Flow/Case);
+     * `inputs` are the op's fields; `connection`/`folder` are symbolic
+     * bindings-names. Resolved against the connector library at serialize (pass
+     * `{ library }` to `serialize`/compile). `id` is the BPMN element id, `name`
+     * the display name.
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param descriptor - The generated operation, from a prepared connector module.
+     * @param inputs - The activity's inputs, typed by the descriptor.
+     * @param opts - `name`, plus symbolic `connection` / `folder`, an action
+     * `version`, and the `object` a generic operation addresses.
+     * @returns This builder, so calls chain.
+     */
+    connector<I extends Record<string, unknown>, O>(id: string, descriptor: ConnectorDescriptor<I, O>, inputs: I, opts?: BpmnConnectorOpts): this;
+    /**
+     * Stringly form, for a connector with no prepared module.
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param key - The connector library key, e.g. `'uipath-salesforce-slack'`.
+     * @param action - The operation id, e.g. `'send-message-to-channel'`.
+     * @param inputs - The activity's inputs.
+     * @param opts - `name`, plus symbolic `connection` / `folder`, an action
+     * `version`, and the `object` a generic operation addresses.
+     * @returns This builder, so calls chain.
+     */
+    connector(id: string, key: string, action: string, inputs?: Record<string, unknown>, opts?: BpmnConnectorOpts): this;
+    /**
+     * 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: string, opts: HttpOpts): this;
+    /**
+     * @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.
+     */
+    private bindRequiredContext;
+    /** @internal Shared body of the Orchestrator process-invocation methods. */
+    private orchestratorNode;
+    /**
+     * 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: string, opts: OrchestratorOpts): this;
+    /**
+     * 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: string, opts: OrchestratorOpts): this;
+    /**
+     * 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: string, opts: OrchestratorAsyncOpts): this;
+    /**
+     * 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: string, opts: OrchestratorAsyncOpts): this;
+    /**
+     * 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: string, opts: OrchestratorOpts): this;
+    /**
+     * 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: string, opts: OrchestratorOpts): this;
+    /**
+     * 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: string, opts: QueueItemOpts): this;
+    /**
+     * 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: string, opts: HumanTaskOpts): this;
+    /**
+     * 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: string, opts: ReceiveMessageOpts): this;
+    /**
+     * 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: string, connector: string, event: string, opts: ConnectorEventOpts): this;
+    /**
+     * 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: string, connector: string, event: string, opts: ConnectorEventOpts): this;
+    /**
+     * 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: string, connector: string, action: string, inputs: Record<string, unknown>, opts: ExternalTaskOpts): this;
+    /**
+     * 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: string, connector: string, action: string, inputs: Record<string, unknown>, opts: ExternalTaskOpts): this;
+    /** @internal Shared body of the two external-invocation methods. */
+    private externalTask;
+    /**
+     * 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: string, type: string, opts?: ActivityNodeOpts): this;
+    /**
+    * 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: string, fn: (sp: SubProcessBuilder) => void, opts?: SubProcessOpts): this;
+    /**
+     * 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: string, target: string, opts?: FlowOpts): this;
+    /**
+     * 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: string, type: TypeDesc, opts?: VarOpts): this;
+    /**
+     * 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: string, type: TypeDesc, opts?: VarOpts): this;
+    /**
+     * 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: string, type: TypeDesc, opts?: VarOpts): this;
+    private declareVar;
+}
+/**
+ * `.connector()` options: the shared connector options, plus the BPMN-only
+ * display `name` and output-variable override.
+ */
+export type BpmnConnectorOpts = ConnectorOpts & ActivityOpts & {
+    /** Display name the designer shows on the task. */
+    name?: string;
+    /**
+     * `=`-expression that skips this activity when it evaluates truthy — the step
+     * is recorded as not executed and the flow carries on
+     * (`uipath:activity/@skipCondition`).
+     *
+     * Only connectors (and other `uipath:activity` nodes) can carry it: a script or
+     * variable task serializes a `uipath:mapping`, which has no such attribute, so
+     * a skip authored there would be dropped and the step would run regardless.
+     */
+    skipCondition?: string;
+    /**
+     * Variable the connector's response lands in. Defaults to `<id>_response`,
+     * which is what makes two connectors in one process independent — a shared
+     * name would have the second clobber the first. The standard error payload
+     * always lands in `<id>_Error`.
+     */
+    outputVar?: string;
+};
+/**
+ * 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 declare function connectorOutputVars(n: Extract<BpmnNode, {
+    kind: 'connector';
+}>): {
+    response: string;
+    error: string;
+};
+/**
+ * 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 declare function typedNodeDeclaredVars(n: Extract<BpmnNode, {
+    kind: 'typed';
+}>): string[];
+/**
+ * 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 declare function nodeDeclaredVars(n: BpmnNode): string[];
+/** A sub-process body: the same graph methods, plus an internal node builder. */
+export declare class SubProcessBuilder extends ScopeBuilder {
+    /** @internal */
+    _buildNode(id: string, opts: SubProcessOpts): BpmnNode;
+}
+/**
+ * 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 declare class BpmnBuilder extends ScopeBuilder {
+    private readonly _id;
+    private _name?;
+    private _metadata?;
+    /**
+     * @param _id - The process id, as passed to `bpmn()`.
+     * @returns The top-level builder.
+     */
+    constructor(_id: string);
+    /**
+    * Set the process's display name.
+    *
+    * @param n - The name the designer shows.
+    * @returns This builder, so calls chain.
+    */
+    name(n: string): 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: ProcessMetadata): 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: string): this;
+    /** Named schemas declared with `.schema()`, resolved when a row references one. */
+    private readonly _schemas;
+    /**
+     * 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: string, schema: unknown): 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: string, opts?: BindingOpts): this;
+    /**
+     * Finish the process and return the graph the serializer turns into XML.
+     *
+     * @returns The built process — its elements, flows and variables.
+     */
+    build(): BuiltBpmn;
+}
+/**
+ * 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 declare const errorSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly code: {
+            readonly type: "string";
+        };
+        readonly message: {
+            readonly type: "string";
+        };
+        readonly detail: {
+            readonly type: "string";
+        };
+        readonly category: {
+            readonly type: "string";
+        };
+        readonly status: {
+            readonly type: "number";
+        };
+        readonly element: {
+            readonly 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 declare const errorSchemaWithResponse: {
+    readonly type: "object";
+    readonly properties: {
+        readonly response: {
+            readonly type: "string";
+        };
+        readonly code: {
+            readonly type: "string";
+        };
+        readonly message: {
+            readonly type: "string";
+        };
+        readonly detail: {
+            readonly type: "string";
+        };
+        readonly category: {
+            readonly type: "string";
+        };
+        readonly status: {
+            readonly type: "number";
+        };
+        readonly element: {
+            readonly 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 declare function bpmn(id: string): BpmnBuilder;