@uipath/maestro-builder-sdk 6.11.6 → 6.12.1

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

@@ -22,7 +22,9 @@
 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';
+import type { RegistryTypeSpec, TypedContextRow, TypedInputRow, TypedOutputRow } from './typed-node.js';
+import { type DataServiceOperation } from './data-service.js';
+export type { DataServiceOperation } from './data-service.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). */
@@ -103,6 +105,12 @@ export type BpmnNode = {
     };
     /** A `uipath:mapping` / `uipath:activity` payload on the event — see {@link ExtensionPayload}. */
     payload?: ExtensionPayload;
+    /**
+     * `false` marks a NON-interrupting start (`isInterrupting="false"`), which only an
+     * event sub-process's start can be — see {@link StartOpts.interrupting}. Unset means
+     * BPMN's default, interrupting, and writes no attribute.
+     */
+    interrupting?: boolean;
 } | {
     kind: 'boundaryEvent';
     id: string;
@@ -123,6 +131,8 @@ export type BpmnNode = {
     name?: string;
     script: string;
     scriptFormat: string;
+    /** The `uipath:scriptVersion` value — see {@link ScriptTaskOpts.scriptVersion}. */
+    scriptVersion: string;
     inputs: Record<string, string>;
     outputs: Record<string, string>;
     /** The mapping's extension type — see {@link ScriptTaskOpts.type}. */
@@ -164,6 +174,8 @@ export type BpmnNode = {
     context: Record<string, unknown>;
     /** The payload, shaped by the type's `inputPattern`. */
     inputs: Record<string, unknown>;
+    /** Payload rows spelled out, replacing `inputs` — see {@link TypedInputRow}. */
+    inputRows?: TypedInputRow[];
     /** Variable the output lands in; defaults to `<id>_<outputName>`. */
     outputVar?: string;
     /** Extra output rows: variable id → `=`-expression against the node's result. */
@@ -178,6 +190,8 @@ export type BpmnNode = {
     contextRows?: TypedContextRow[];
     /** `=`-expression that skips the node when truthy. */
     skipCondition?: string;
+    /** The type's emission spec, supplied inline — see {@link ActivityNodeOpts.spec}. */
+    spec?: RegistryTypeSpec;
     /** Emit `context` exactly as given — for importers; see `TypedNodeInput`. */
     contextVerbatim?: boolean;
 }) | (ActivityNodeFields & {
@@ -326,6 +340,14 @@ export interface BpmnFlow {
     name?: string;
     /** `=`-expression gating this flow (exclusive/inclusive gateway outgoing). Read a declared process variable as `=vars.<id>`. */
     condition?: string;
+    /**
+     * Set on a flow the builder wrote by implication — an arm's chain, a handler's path,
+     * a construct's join, or a `flowMode('sequence')` sibling — rather than from an
+     * explicit `.sequenceFlow()`. `bpmn check --graph` marks these, so what was inferred
+     * can be reviewed against what was typed. Not serialized; an explicit
+     * `.sequenceFlow()` that restates the edge clears it.
+     */
+    implied?: true;
 }
 /**
  * How a variable is exposed: `'input'` (read-only entry input), `'output'` (a
@@ -344,8 +366,14 @@ export interface BpmnVarDecl {
     direction: VarDirection;
     /** Optional initial value. */
     default?: unknown;
-    /** When set, the variable is scoped to that element rather than root/global. */
-    elementId?: string;
+    /**
+     * The element the declaration belongs to — see {@link VarOpts.elementId}. `undefined`
+     * is written as the SDK's default for the declaration's kind — the manual start event
+     * for a top-level `input`, the end event that writes it for a top-level `output`, the
+     * owning scope (process or sub-process id) otherwise; `null` writes no `elementId` at
+     * all, which only a decompiled legacy artifact asks for.
+     */
+    elementId?: string | null;
     /** The declaration's body — a JSON Schema for a structured variable. */
     schema?: unknown;
     /** Mark the declaration `required="true"`, as a process input can be. */
@@ -437,7 +465,11 @@ export interface ProcessMetadata {
      * 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`). */
+    /**
+     * The root start event's package entry-point id (`uipath:entryPointId`). A GUID —
+     * the one `bpmn init` assigned, or `crypto.randomUUID()`; `validate` refuses any
+     * other value and `check` reports `ENTRYPOINT_ID_NOT_GUID`.
+     */
     entryPointId?: string;
     /** Free-form document tags (`uipath:tags` / `uipath:tag`). */
     tags?: string[];
@@ -573,6 +605,16 @@ export interface StartOpts {
     };
     /** A `uipath:mapping` mapping process inputs onto variables — see {@link ExtensionPayload}. */
     payload?: ExtensionPayload;
+    /**
+     * `false` makes a message or timer start NON-interrupting: the event sub-process it
+     * starts runs beside the container instead of cancelling it (`isInterrupting="false"`).
+     *
+     * Only meaningful on the start event of an event sub-process, and never for an
+     * `error` start, which BPMN defines as interrupting — the throw has already ended its
+     * scope. Defaults to `true`, the BPMN default, which writes no attribute.
+     * {@link ScopeBuilder.eventSubProcess} sets this from its own `interrupting` option.
+     */
+    interrupting?: boolean;
 }
 /**
  * Options for `.endEvent()`. `terminate`, `error`, or `message` picks the event
@@ -743,6 +785,20 @@ export interface ScriptTaskOpts extends ActivityOpts {
     script: string;
     /** The script language marker. Defaults to `'JavaScript'` (Jint). */
     scriptFormat?: string;
+    /**
+     * The `uipath:scriptVersion` the runtime reads to pick the result shape. Defaults
+     * to `'v3'`, the contract the rest of this surface is written for: the script may
+     * return any value and `=result.response` is that value.
+     *
+     * Only worth setting on an import. `v2` means the same wrapper and round-trips
+     * unchanged; `v1` (what an ABSENT element means to the runtime) spreads the
+     * returned object's fields instead, so a script written for it reads
+     * `=result.<field>` and would silently read `undefined` if the version were
+     * stamped up to `v3` on recompile — which is what this SDK did before the field
+     * existed. `bpmn-decompile` therefore emits the source's value whenever it is not
+     * `v3`, spelling an absent element as `'v1'`.
+     */
+    scriptVersion?: string;
     /** `uipath:input` rows: field name → `=`-expression read into the script. */
     inputs?: Record<string, string>;
     /**
@@ -860,6 +916,55 @@ export interface BindingOpts {
      */
     resourceSubType?: string;
 }
+/**
+ * Options for `.dataService()` — one UiPath Data Fabric (Data Service) record or
+ * file operation. Combine with a {@link DataServiceOperation} for the operation half:
+ *
+ * ```ts
+ * .binding('dataFabric', { resource: 'Connection', propertyAttribute: 'ConnectionId', value: CONNECTION_KEY })
+ * .binding('dataFabricFolder', { resource: 'Connection', propertyAttribute: 'folderKey', value: FOLDER_KEY })
+ * .dataService('create', { entity: 'ContractRegistry', connection: 'dataFabric', folder: 'dataFabricFolder',
+ *   op: 'create', record: { contractTitle: '=vars.title', status: 'Open' } })
+ * .dataService('lookup', { entity: 'ContractRegistry', connection: 'dataFabric', folder: 'dataFabricFolder',
+ *   op: 'get', recordId: '=vars.create_response.Id', expansionLevel: 3 })
+ * ```
+ */
+export interface DataServiceOpts extends ActivityOpts {
+    /** Display name the designer shows. Defaults to one built from the operation, e.g. `Create ContractRegistry`. */
+    name?: string;
+    /** The Data Service entity the operation addresses, e.g. `'ContractRegistry'`. */
+    entity: string;
+    /**
+     * The Data Fabric connection: the id of a `.binding()` declared with
+     * `propertyAttribute: 'ConnectionId'` (with or without the `=bindings.` prefix), or
+     * the connection key itself, for which a binding is declared on your behalf and
+     * shared by every node that names the same key.
+     */
+    connection: string;
+    /**
+     * The folder the connection lives in: the id of a `.binding()` declared with
+     * `propertyAttribute: 'folderKey'`, or the folder key itself. Optional on the
+     * wire, but the platform resolves the connection through it, so a process meant
+     * to run should set it.
+     *
+     * A folder binding is a COMPANION of its connection: its `resourceKey` is the
+     * connection's key, and only its `default` is the folder key. That is how every
+     * real export writes the pair, and `uip maestro bpmn validate` reports
+     * `MISSING_BINDING` when the resource key is the folder's own. The builder writes
+     * the companion form whichever way the folder was given.
+     */
+    folder?: string;
+    /** Variable the response lands in. Defaults to `<id>_response`; the error payload always lands in `<id>_Error`. */
+    outputVar?: string;
+    /**
+     * A JSON Schema for the response, when its shape matters downstream — the created
+     * record's fields, say. Typed `jsonSchema` with no body otherwise, which is what the
+     * converter writes.
+     */
+    schema?: unknown;
+    /** `=`-expression that skips the operation when truthy. */
+    skipCondition?: string;
+}
 /**
  * Options for `.http()` — an `Intsvc.UnifiedHttpRequest` node.
  *
@@ -1159,6 +1264,30 @@ export interface ActivityNodeOpts extends ActivityOpts {
     contextRows?: TypedContextRow[];
     /** The payload, shaped by the type's `inputPattern`. */
     inputs?: Record<string, unknown>;
+    /**
+     * The payload rows spelled out, replacing `inputs` — see {@link TypedInputRow}.
+     *
+     * For a `separateInputs` type whose rows carry what the record cannot say: a
+     * `target` that is not the key (a connector parameter's `path` / `query`), or a
+     * type the registry does not declare. `bpmn-decompile` writes this form when the
+     * artifact needs it; an author reaches for it to reproduce a real export exactly.
+     */
+    inputRows?: TypedInputRow[];
+    /**
+     * The type's emission spec, supplied inline — the escape hatch for a registry type
+     * the committed snapshot does not carry and no `uip` on this machine can describe,
+     * or one the snapshot describes wrongly. Used as is: which BPMN element and
+     * `uipath:*` tag to write, the context fields and their defaults, how the payload
+     * rows are shaped, and the output row. The shape is {@link RegistryTypeSpec}; the
+     * quickest way to a correct one is `uip maestro bpmn registry get <Type> --output json`
+     * on a machine that has it, then `node scripts/materialize-bpmn-registry.mjs` to add it
+     * to the snapshot for good.
+     *
+     * `bpmn-decompile` cannot recover this — it reads the artifact, not the registry — so
+     * an import of such a node comes back as a plain `.activity()` that needs the spec
+     * added by hand.
+     */
+    spec?: RegistryTypeSpec;
     /** 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. */
@@ -1219,6 +1348,17 @@ export interface PlainTaskOpts extends ActivityOpts {
     /** Which task element to emit. Defaults to `bpmn:task`. */
     element?: PlainTaskElement;
 }
+/**
+ * One implied edge whose id is pinned — see {@link ScopeBuilder.flowIds}.
+ */
+export interface PinnedFlowId {
+    /** The element the edge leaves. */
+    source: string;
+    /** The element it flows into. */
+    target: string;
+    /** The id to give it instead of the derived `Flow_<source>_<target>`. */
+    id: string;
+}
 /** Options for `.sequenceFlow()`. */
 export interface FlowOpts {
     /** The flow's element id. Defaults to `Flow_<source>_<target>`. */
@@ -1234,8 +1374,30 @@ export interface VarOpts {
     name?: string;
     /** Optional initial value. */
     default?: unknown;
-    /** When set, the variable is scoped to that element rather than root/global. */
-    elementId?: string;
+    /**
+     * The element this declaration belongs to, written as `elementId` on the wire.
+     *
+     * Left out, the declaration is written where the platform's own tools put one of
+     * its kind. A `.var()` belongs to the scope it is declared in — the process id at
+     * the top level, the sub-process id inside one. A top-level `.input()` belongs to
+     * the process's manual START event and a top-level `.output()` to the END event
+     * whose mapping writes it (or the only end event): that is how every Studio Web
+     * export and converter output declares a process's public contract, and what the
+     * canvas, the entry-point derivation and the graders read it from. The engine itself
+     * resolves `vars.<id>` by id whatever the scope, so a script may read an input
+     * directly with no start-event bridge. `uip maestro bpmn validate` (1.203+) requires
+     * SOME `elementId`: a declaration with none is `ROOT_VARIABLE_MISSING_ELEMENT_ID`,
+     * and every `vars.<id>` read of it fails `VARIABLE_DOES_NOT_EXIST`. Name an element
+     * to scope the variable to it explicitly (the node whose output fills it, a specific
+     * end event). `null` writes no `elementId` — the shape older exports have;
+     * `decompile` emits it so such an artifact round-trips byte for byte.
+     *
+     * At the start of a run, the platform matches supplied input values to declarations
+     * by their display `name` (`BpmnModelBuilder.AddProcessVariable` reads
+     * `inputOverrides[name]`), so an input given a display name is supplied under that
+     * name, not its id.
+     */
+    elementId?: string | null;
     /**
      * The declaration's BODY — a JSON Schema describing the shape of a `jsonSchema`
      * (or `json`) variable.
@@ -1253,6 +1415,269 @@ export interface VarOpts {
     /** Mark the declaration `required="true"`, as a process input can be. */
     required?: boolean;
 }
+/**
+ * Boundary events declared on the activity they attach to — the callback every
+ * activity method accepts as its last argument. See {@link ActivityBuilder}.
+ */
+export type ActivityBodyFn = (t: ActivityBuilder) => void;
+/** The elements of one branch arm or boundary-handler path — see {@link PathBuilder}. */
+export type ArmBodyFn = (b: PathBuilder) => void;
+/**
+ * What every boundary handler on an {@link ActivityBuilder} accepts —
+ * `.onError()`, `.onTimer()`, `.onMessage()`.
+ */
+export interface HandlerOpts {
+    /**
+     * The boundary event's element id. Defaults to `<activityId>_onError`,
+     * `<activityId>_onTimer` or `<activityId>_onMessage`: a pure function of the ids the
+     * author wrote, never of position, so `merge` keys stay stable when a line is
+     * inserted above. A second handler of the same kind on one activity must name its own.
+     */
+    id?: string;
+    /** Display name the designer shows on the boundary event. */
+    name?: string;
+    /** A `uipath:activity` payload on the boundary event — see {@link ExtensionPayload}. */
+    payload?: ExtensionPayload;
+}
+/** Options for {@link ActivityBuilder.onError}. An error boundary always interrupts. */
+export interface ErrorHandlerOpts extends HandlerOpts {
+    /**
+     * Capture the error payload into this variable, the way the product does on every
+     * error boundary it writes: a `uipath:activity` output row reading `=Error` into the
+     * variable, plus the variable's declaration — `jsonSchema` typed, displayed as `Error`,
+     * scoped to the boundary event — unless the author declared that id already.
+     * Downstream, read `=vars.<errorVar>.code`, `.message`, `.detail`, `.status`.
+     *
+     * Mutually exclusive with `payload`, which spells the row out by hand.
+     */
+    errorVar?: string;
+}
+/** Options for {@link ActivityBuilder.onTimer}. */
+export interface TimerHandlerOpts extends HandlerOpts {
+    /**
+     * Whether firing cancels the activity. Defaults to `true`, BPMN's default
+     * (`cancelActivity="true"`); `false` lets the activity carry on beside the handler
+     * path, as a reminder does.
+     *
+     * The two continue differently. An INTERRUPTING handler's path rejoins the process at
+     * the next statement after the activity, exactly as the activity's own path would
+     * have. A NON-INTERRUPTING one runs beside a token that is still going to reach that
+     * statement, so letting the handler reach it too would run everything after it twice.
+     * Its path must therefore end — with an end event, `.goto()`, or an explicit
+     * `.sequenceFlow()` off its last element — and the builder refuses one that does not.
+     */
+    interrupting?: boolean;
+}
+/** Options for {@link ActivityBuilder.onMessage}. */
+export interface MessageHandlerOpts extends HandlerOpts {
+    /** Whether the message cancels the activity — see {@link TimerHandlerOpts.interrupting}. */
+    interrupting?: boolean;
+}
+/**
+ * One arm of {@link ScopeBuilder.choose}: a `when` condition, or the single
+ * `otherwise` fallback. Exactly one of the two, checked by the type system, so an
+ * arm nobody gave a condition cannot be written.
+ */
+export type ChooseArm = {
+    /** `=`-expression selecting this arm, e.g. `'=vars.action == "Approved"'`. */
+    when: string;
+    /** Not on a conditioned arm. */
+    otherwise?: never;
+    /** Edge label the designer shows on the arm's flow. */
+    label?: string;
+    /**
+     * The arm's elements, in order. Omitted, the arm goes straight on to whatever
+     * follows the `choose` — an empty branch.
+     */
+    body?: ArmBodyFn;
+} | {
+    /** The fallback taken when no `when` holds — the gateway's default flow. */
+    otherwise: true;
+    /** Not on the fallback arm. */
+    when?: never;
+    /** Edge label the designer shows on the arm's flow. */
+    label?: string;
+    /** The arm's elements, in order; omitted, an empty branch. */
+    body?: ArmBodyFn;
+};
+/**
+ * The join gateway a construct emits when more than one arm falls through.
+ *
+ * Its id defaults to `<split>_join`, a pure function of the id the author wrote.
+ * Naming it is for an IMPORT: `decompile --style nested` lifts a flat process's
+ * gateway into `choose` / `fork` / `race`, and the join it finds already has an id
+ * (and often a name) that `merge` and the canvas key on, which the default could
+ * not reproduce.
+ */
+export interface JoinOpts {
+    /** The join gateway's element id. Defaults to `<split>_join`. */
+    id?: string;
+    /** Display name the designer shows on the join gateway. */
+    name?: string;
+}
+/** Options for {@link ScopeBuilder.choose}. */
+export interface ChooseOpts {
+    /** Display name the designer shows on the splitting gateway. */
+    name?: string;
+    /**
+     * `true` emits an INCLUSIVE gateway — every arm whose `when` holds is taken, not
+     * only the first — and the arms rejoin through an inclusive join.
+     */
+    inclusive?: boolean;
+    /** The join gateway's id and name, when the defaults will not do — see {@link JoinOpts}. */
+    join?: JoinOpts;
+}
+/** Options for {@link ScopeBuilder.fork} and {@link ScopeBuilder.race}. */
+export interface SplitOpts {
+    /** Display name the designer shows on the splitting gateway. */
+    name?: string;
+    /** The join gateway's id and name, when the defaults will not do — see {@link JoinOpts}. */
+    join?: JoinOpts;
+}
+/**
+ * Options for {@link ScopeBuilder.eventSubProcess}. Exactly one of `error` /
+ * `message` / `timer` names what starts it.
+ */
+export interface EventSubProcessOpts {
+    /** Display name the designer shows on the sub-process. */
+    name?: string;
+    /**
+     * Start when an error is thrown anywhere in the enclosing container that nothing
+     * closer caught: `true` for any error, or a declared kind — see {@link ErrorLike}.
+     * Always interrupting.
+     */
+    error?: ErrorLike;
+    /** Start when this message arrives while the container is active. */
+    message?: string;
+    /** Start on a timer measured from the container's own start. */
+    timer?: TimerLike;
+    /**
+     * For a `message` or `timer` start: `false` lets the container keep running while
+     * the sub-process handles the event (`isInterrupting="false"`). Defaults to `true`.
+     * Refused with `error`, which BPMN defines as interrupting.
+     */
+    interrupting?: boolean;
+    /**
+     * With `error`: the variable the caught error is captured into, through the same
+     * `=Error` output row {@link ErrorHandlerOpts.errorVar} writes on a boundary,
+     * declared `jsonSchema` and scoped to the start event unless the author declared
+     * that id already.
+     *
+     * Defaults to `` `${id}_Error` ``, so the body reads `=vars.<net>_Error.code`,
+     * `.message`, `.detail`, `.status` with nothing more written.
+     *
+     * It used to default to the bare `'Error'`, which is what the designer calls the
+     * variable but not what it names it. Measured over the five real exports in
+     * `research/bpmn-roundtrip/corpus/`: 285 error captures, every one declared with a
+     * UNIQUE id (`error`, `error2`, `error3`, …) and the display `name="Error"`, and
+     * every expression reading its own — `vars.error18`, `vars.error5`. `vars.Error`
+     * appears exactly 0 times. The `Error` spelling that IS load-bearing is the capture
+     * row's `source="=Error"`, the key the engine seeds the payload under, which is
+     * written for you either way; the row's `var` is free, and the designer keeps it
+     * distinct. A shared id is also wrong on the wire: the runtime resolves `vars.<id>`
+     * in ONE flat scope whatever a declaration's `elementId` says, and two declarations
+     * with one id is `DUPLICATE_DOCUMENT_ID`, so two nets defaulting to `Error` could
+     * only ever share a single slot. `<id>_Error` matches what `.connector()` and the
+     * typed nodes have always written for their own error payload.
+     *
+     * Name something else to choose the id; pass `false` to write no capture row at all,
+     * which is what a decompiled artifact whose error start carries none asks for.
+     */
+    errorVar?: string | false;
+    /** The synthesized start event's id. Defaults to `<id>_start`. */
+    startId?: string;
+    /** Display name the designer shows on the start event. */
+    startName?: string;
+    /** A payload on the start event, spelled out by hand — see {@link ExtensionPayload}. Exclusive with `errorVar`. */
+    startPayload?: ExtensionPayload;
+    /** `uipath:tags` on the sub-process — see {@link ActivityOpts.tags}. */
+    tags?: Record<string, string>;
+    /** A `uipath:mapping` on the sub-process itself — see {@link SubProcessOpts.payload}. */
+    payload?: ExtensionPayload;
+}
+/**
+ * How a scope wires elements no explicit `.sequenceFlow()` covers — see
+ * {@link ScopeBuilder.flowMode}.
+ *
+ * `explicit`, the default for the process root and every `.subProcess()` body: nothing
+ * is implied between siblings, and only the exits of a nested construct (a `choose`, a
+ * handler) continue to the next element placed. `sequence`: consecutive elements are
+ * wired in order. The inside of an arm, a handler and an `eventSubProcess` body is
+ * always `sequence`.
+ */
+export type FlowMode = 'explicit' | 'sequence';
+/** The builder-internal spelling of {@link FlowMode}, kept so the field types read as what they are. */
+type WiringMode = FlowMode;
+/** A gateway node of the built graph. */
+type GatewayNode = Extract<BpmnNode, {
+    kind: GatewayKind;
+}>;
+/**
+ * An edge waiting for the element that continues it: the open end of an arm, a
+ * handler, or a join, plus what the flow should carry when it is finally written.
+ */
+interface PendingExit {
+    /** The element the edge leaves. */
+    source: string;
+    /** Condition to put on the flow — an empty arm's `when`. */
+    condition?: string;
+    /** Label to put on the flow. */
+    name?: string;
+    /** The gateway whose `default` must name the flow once it exists — an `otherwise` arm. */
+    defaultOf?: GatewayNode;
+    /**
+     * Where this exit came from — an arm, a handler, a join — for the message when
+     * nothing ever consumes it. Absent for the plain tail of a sequence, which is
+     * described by the scope it is in.
+     */
+    origin?: string;
+}
+/** The arrays an arm shares with the scope it is written into. */
+interface ScopeStorage {
+    /** The scope's elements, in placement order. */
+    nodes: BpmnNode[];
+    /** The scope's sequence flows, explicit and implied alike. */
+    flows: BpmnFlow[];
+    /** The variables declared in the scope. */
+    vars: BpmnVarDecl[];
+    /** Elements whose path must be ended or wired by hand, checked when the real scope closes. */
+    mustClose: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+/** Bookkeeping the nesting sugar shares across every scope of one process. */
+declare class SugarRegistry {
+    /** Flow ids the builder wrote by implication rather than from an explicit `.sequenceFlow()`. */
+    readonly impliedFlowIds: Set<string>;
+    /**
+     * Ids to give implied edges, keyed `source\u0000target` — see {@link ScopeBuilder.flowIds}.
+     *
+     * An implied edge has no call of its own, so there is nowhere to name it and its id
+     * is derived. This is the one place an author (in practice, `decompile`) can say what
+     * a derived id should be instead.
+     */
+    readonly pinnedFlowIds: Map<string, string>;
+    /** Variables an `errorVar` asked for — declared at build unless the author declared the id. */
+    readonly autoVars: Array<{
+        id: string;
+        vars: BpmnVarDecl[];
+        elementId: string;
+    }>;
+}
+/**
+ * Whether the node serializes to a start event — nothing may flow INTO it.
+ *
+ * Exported because `graph.ts` needs the SAME answer: `check --graph` decides what is
+ * `[NO INCOMING]` and what is merely an entry point, and a second copy of this test
+ * drifted — it missed the `typed` arm, so a registry type whose element IS a start
+ * event was reported unreachable.
+ *
+ * @param n - The node.
+ * @returns True when the node is an entry point of its own.
+ * @internal
+ */
+export declare function isStartLike(n: BpmnNode): boolean;
 /**
  * Collects `uipath:binding` declarations, de-duped by id.
  *
@@ -1318,14 +1743,160 @@ declare abstract class ScopeBuilder {
     protected readonly _defs: DefinitionsRegistry;
     /** @internal */
     protected readonly _bindingRegistry: BindingsRegistry;
+    /** @internal */
+    protected readonly _storage: ScopeStorage;
+    /** @internal */
+    protected readonly _sugar: SugarRegistry;
+    /** @internal How THIS scope wires siblings — an arm's is always `sequence`. */
+    protected _mode: WiringMode;
+    /** @internal The mode of the real scope this builder writes into, which a nested `.subProcess()` inherits. */
+    protected _scopeMode: WiringMode;
+    /** @internal Whether this builder is an arm or handler path rather than a real scope. */
+    protected _isArm: boolean;
+    /** @internal The id of a start event the builder synthesized for this scope (an event sub-process body). */
+    protected _synthesizedStart?: string;
+    /** @internal Elements placed in a `sequence` scope with nothing leading into them, checked at close. */
+    protected readonly _unattached: Array<{
+        id: string;
+        after: string;
+    }>;
+    /** @internal Edges waiting for the element that continues them. */
+    protected _open: PendingExit[];
+    /** @internal Whether anything has been placed yet, so an unreachable element can be told from the first. */
+    protected _started: boolean;
+    /** @internal What left this path for good (`.goto()`), after which nothing may follow. */
+    protected _closedBy?: string;
     /**
      * @param defs - Definitions-level message/error declarations, shared with every scope.
      * @param bindings - `uipath:binding` declarations, shared so a typed node can
      * declare one from inside a sub-process.
+     * @param storage - The arrays to write into; an arm shares its enclosing scope's,
+     * a real scope gets its own.
+     * @param mode - How siblings no explicit flow covers are wired — see `WiringMode`.
+     * @param sugar - Process-wide bookkeeping for the nesting sugar.
      * @returns The scope builder.
      */
-    constructor(defs: DefinitionsRegistry, bindings: BindingsRegistry);
+    constructor(defs: DefinitionsRegistry, bindings: BindingsRegistry, storage?: ScopeStorage, mode?: WiringMode, sugar?: SugarRegistry);
+    /**
+     * Choose how this scope wires the elements no explicit `.sequenceFlow()` covers.
+     *
+     * @remarks
+     * `'explicit'` is the default: siblings are not wired to each other, only the exits
+     * of a nested construct continue to the next element. `'sequence'` wires consecutive
+     * siblings in order, so a linear process needs no `.sequenceFlow()` at all.
+     *
+     * Three rules keep `'sequence'` local and reviewable. **Explicit wins**: an element
+     * that already has an explicit outgoing flow is not also wired to the next one, so a
+     * hand-written edge never gains a silent twin. **A bare gateway implies nothing
+     * outward**: it is wired into, but its outgoing flows are yours to write (or use
+     * `.choose()` / `.fork()` / `.race()`, which imply theirs). **Nothing dangles
+     * silently**: an element nothing leads into, or a path that does not end, is refused
+     * at `.build()` rather than emitted. `bpmn check --graph` prints the wiring that
+     * resulted, implied edges marked, so a change can be reviewed against what was
+     * inferred rather than what was typed.
+     *
+     * Must come before the scope's first element. A `.subProcess()` body inherits its
+     * enclosing scope's mode and may set its own; an arm or handler body is always
+     * `sequence` and refuses the call.
+     *
+     * @example
+     * **A linear process with no sequence flows written**
+     * ```ts
+     * bpmn('intake')
+     *   .flowMode('sequence')
+     *   .var('note', 'string', { default: '' })
+     *   .startEvent('start')
+     *   .task('assign', { set: { note: 'hello' } })
+     *   .scriptTask('log', { script: 'return note;', inputs: { note: '=vars.note' } })
+     *   .endEvent('done')
+     *   .build();
+     * ```
+     *
+     * @param mode - `'explicit'` or `'sequence'`.
+     * @returns This builder, so calls chain.
+     * @throws If called inside an arm or handler body, or after an element has been placed.
+     */
+    flowMode(mode: FlowMode): this;
     private push;
+    /**
+     * Place an activity and run its body, in which boundary events are declared.
+     *
+     * @param node - The activity node.
+     * @param body - Its boundary handlers, if any.
+     * @returns This builder, so calls chain.
+     */
+    private pushActivity;
+    /**
+     * Place a node: wire every pending exit into it, record it, and — in a
+     * `sequence` scope — leave it as the open end the next element continues from.
+     *
+     * @param node - The node to place.
+     * @param viaSugar - Set when the builder itself is placing a gateway it synthesized,
+     * which a `sequence` scope otherwise refuses.
+     * @internal
+     */
+    protected place(node: BpmnNode, viaSugar?: boolean): void;
+    /** Wire every pending exit into `target`, except one the author already wired by hand. */
+    private continueTo;
+    private hasExplicitOutgoing;
+    /**
+     * Write the flow a pending exit stands for, now that its target is known.
+     *
+     * @param exit - The exit.
+     * @param target - The element it flows into.
+     * @internal
+     */
+    protected writeImpliedFlow(exit: PendingExit, target: string): void;
+    /**
+     * Check the implied wiring of a real scope once its author's function has
+     * returned: every path a handler had to end has ended, and every exit a construct
+     * left open reached something.
+     *
+     * @param what - The scope, for the message.
+     * @internal
+     */
+    protected closeScope(what: string): void;
+    /**
+     * The definitions registry, for the activity builder to intern a message or error.
+     *
+     * @returns The registry shared by every scope of this process.
+     * @internal
+     */
+    _defsOf(): DefinitionsRegistry;
+    /**
+     * This scope's variable declarations, for an `errorVar` to be declared into.
+     *
+     * @returns The array the scope declares variables into.
+     * @internal
+     */
+    _varsOf(): BpmnVarDecl[];
+    /**
+     * Attach a boundary event to an activity of this scope and run its handler path.
+     *
+     * @param activityId - The activity the boundary attaches to.
+     * @param suffix - `onError` / `onTimer` / `onMessage`, for the derived id.
+     * @param spec - The event definition and the options it came with.
+     * @param body - The handler path.
+     * @internal
+     */
+    _attach(activityId: string, suffix: 'onError' | 'onTimer' | 'onMessage', spec: {
+        event: EventDef;
+        interrupting: boolean;
+        opts: HandlerOpts & {
+            errorVar?: string;
+        };
+    }, body: ArmBodyFn | undefined): void;
+    /**
+     * The shared lowering of `choose` / `fork` / `race`: a splitting gateway, one
+     * arm per branch, and a join only when more than one arm falls through.
+     *
+     * @param split - The gateway that opens the construct.
+     * @param joinKind - The gateway kind that closes it, when one is needed.
+     * @param arms - Each arm's entry edge and body.
+     * @param what - The construct, for messages.
+     * @param mustWait - `race`: each arm has to begin with something that waits.
+     */
+    private branch;
     /**
      * A start event (authorable definitions: none / message / timer).
      *
@@ -1417,17 +1988,19 @@ declare abstract class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - The Jint JavaScript `script`, and its input/output mappings.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    scriptTask(id: string, opts: ScriptTaskOpts): this;
+    scriptTask(id: string, opts: ScriptTaskOpts, body?: ActivityBodyFn): 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.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    task(id: string, opts?: TaskOpts): this;
+    task(id: string, opts?: TaskOpts, body?: ActivityBodyFn): this;
     /**
      * A task element carrying NO `uipath:*` payload — an abstract task, in BPMN's terms.
      *
@@ -1446,6 +2019,7 @@ declare abstract class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - `name`, and which task `element` to emit (default `bpmn:task`).
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      *
      * @example
@@ -1456,7 +2030,7 @@ declare abstract class ScopeBuilder {
      *   .endEvent('e')
      * ```
      */
-    plainTask(id: string, opts?: PlainTaskOpts): this;
+    plainTask(id: string, opts?: PlainTaskOpts, body?: ActivityBodyFn): this;
     /**
      * An Integration Service **connector** service task (`bpmn:sendTask` +
      * `uipath:activity` / `Intsvc.ActivityExecution`) — the typed form, where a
@@ -1474,9 +2048,10 @@ declare abstract class ScopeBuilder {
      * @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.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    connector<I extends Record<string, unknown>, O>(id: string, descriptor: ConnectorDescriptor<I, O>, inputs: I, opts?: BpmnConnectorOpts): this;
+    connector<I extends Record<string, unknown>, O>(id: string, descriptor: ConnectorDescriptor<I, O>, inputs: I, opts?: BpmnConnectorOpts, body?: ActivityBodyFn): this;
     /**
      * Stringly form, for a connector with no prepared module.
      *
@@ -1486,9 +2061,10 @@ declare abstract class ScopeBuilder {
      * @param inputs - The activity's inputs.
      * @param opts - `name`, plus symbolic `connection` / `folder`, an action
      * `version`, and the `object` a generic operation addresses.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    connector(id: string, key: string, action: string, inputs?: Record<string, unknown>, opts?: BpmnConnectorOpts): this;
+    connector(id: string, key: string, action: string, inputs?: Record<string, unknown>, opts?: BpmnConnectorOpts, body?: ActivityBodyFn): this;
     /**
      * An **HTTP request** service task (`bpmn:sendTask` +
      * `uipath:activity` / `Intsvc.UnifiedHttpRequest`).
@@ -1520,9 +2096,44 @@ declare abstract class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - The request, plus `name`, `outputVar`, and the shared activity options.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    http(id: string, opts: HttpOpts): this;
+    http(id: string, opts: HttpOpts, body?: ActivityBodyFn): this;
+    /**
+     * A UiPath **Data Fabric** (Data Service) record or file operation — create,
+     * update, get, query, delete a record, or download / upload / delete a record's
+     * file field — as an `Intsvc.ActivityExecution` send task in the exact shape the
+     * Flow→BPMN converter and Studio Web write.
+     *
+     * @remarks
+     * The connector library ships one Data Service operation, so `.connector()` cannot
+     * author the rest, and hand-filling `.activity('Intsvc.ActivityExecution', …)` gets
+     * the wire details wrong in ways `validate` does not catch (a `recordId` in the body,
+     * a curated `objectName` on an entity-form path, a folder binding keyed by the folder).
+     * This writes each of the eight operations the way the platform's own tools do:
+     * create and update in the ENTITY form (`POST /<Entity>`, `PUT /<Entity>/{id}`,
+     * `objectName` = the entity), the others in the CURATED form (`entityName` as a
+     * path parameter, `objectName` = the curated operation), every parameter its own
+     * `path` / `query` / `file` row and the record as the one json `body` row. Needs no
+     * connector library at compile time.
+     *
+     * The response lands in `outputVar` (default `<id>_response`) and the error payload in
+     * `<id>_Error`, both declared for you.
+     *
+     * @param id - The element id, unique in the process and used by `sequenceFlow`.
+     * @param opts - The entity, connection and folder, plus the operation and its parameters — see {@link DataServiceOpts} and {@link DataServiceOperation}.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
+     * @returns This builder, so calls chain.
+     */
+    dataService(id: string, opts: DataServiceOpts & DataServiceOperation, body?: ActivityBodyFn): this;
+    /**
+     * @internal Resolve a `.dataService()` connection or folder to a `=bindings.<id>`
+     * reference: an existing binding by id, else one already declared for the same
+     * key, else a new one declared on the author's behalf. `companionKey` is the
+     * connection's key a folder binding must carry as its `resourceKey`.
+     */
+    private dataServiceBinding;
     /**
      * @internal Turn a literal into a binding reference where the platform demands
      * one, declaring the binding on the author's behalf.
@@ -1555,35 +2166,39 @@ declare abstract class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which process, folder, and input arguments.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    startProcess(id: string, opts: OrchestratorOpts): this;
+    startProcess(id: string, opts: OrchestratorOpts, body?: ActivityBodyFn): 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.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    startAgent(id: string, opts: OrchestratorOpts): this;
+    startAgent(id: string, opts: OrchestratorOpts, body?: ActivityBodyFn): 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.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    startAgenticProcess(id: string, opts: OrchestratorAsyncOpts): this;
+    startAgenticProcess(id: string, opts: OrchestratorAsyncOpts, body?: ActivityBodyFn): 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.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    startCaseProcess(id: string, opts: OrchestratorAsyncOpts): this;
+    startCaseProcess(id: string, opts: OrchestratorAsyncOpts, body?: ActivityBodyFn): this;
     /**
      * Execute an **API workflow**, fire-and-forget
      * (`Orchestrator.ExecuteApiWorkflowAsync`).
@@ -1594,9 +2209,10 @@ declare abstract class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which workflow, folder, and input arguments.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    executeApiWorkflow(id: string, opts: OrchestratorOpts): this;
+    executeApiWorkflow(id: string, opts: OrchestratorOpts, body?: ActivityBodyFn): this;
     /**
      * Execute a **business rule** and wait for it (`Orchestrator.BusinessRules`, on a
      * `bpmn:businessRuleTask`).
@@ -1640,9 +2256,10 @@ declare abstract class ScopeBuilder {
      * @param opts - Which rule package, folder, and input arguments. `outputVar` defaults
      * to `<id>_businessRuleResponse` — see the note in the implementation for why this one
      * type does not take its default from the spec.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    businessRule(id: string, opts: OrchestratorOpts): this;
+    businessRule(id: string, opts: OrchestratorOpts, body?: ActivityBodyFn): this;
     /**
      * Add an item to an Orchestrator **queue** (`Orchestrator.CreateQueueItem`, or
      * `Orchestrator.CreateAndWaitForQueueItem` when `wait` is set).
@@ -1660,9 +2277,10 @@ declare abstract class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - Which queue and folder, the item content, and whether to wait for it.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    queueItem(id: string, opts: QueueItemOpts): this;
+    queueItem(id: string, opts: QueueItemOpts, body?: ActivityBodyFn): this;
     /**
      * A **human task** — an Action App task a person completes (`bpmn:userTask` +
      * `uipath:activity` / `Actions.HITL`).
@@ -1711,9 +2329,10 @@ declare abstract class ScopeBuilder {
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - The app, the outcomes offered, what the human sees, and which
      * response fields to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    humanTask(id: string, opts: HumanTaskOpts): this;
+    humanTask(id: string, opts: HumanTaskOpts, body?: ActivityBodyFn): this;
     /**
      * Wait for an internal message from another Maestro process
      * (`Maestro.ReceiveMessageEvent` on a `bpmn:intermediateCatchEvent`).
@@ -1751,9 +2370,10 @@ declare abstract class ScopeBuilder {
      *
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param opts - The message name, the correlation reference, and what to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    receiveMessage(id: string, opts: ReceiveMessageOpts): this;
+    receiveMessage(id: string, opts: ReceiveMessageOpts, body?: ActivityBodyFn): this;
     /**
      * Wait mid-flow for an Integration Service connector event
      * (`Intsvc.WaitForEvent` on a `bpmn:receiveTask`).
@@ -1792,9 +2412,10 @@ declare abstract class ScopeBuilder {
      * @param connector - The connector key, e.g. `'uipath-microsoft-outlook365'`.
      * @param event - The event name, e.g. `'email-received'`.
      * @param opts - Connection/folder bindings, the `where` scope, and what to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    waitForEvent(id: string, connector: string, event: string, opts: ConnectorEventOpts): this;
+    waitForEvent(id: string, connector: string, event: string, opts: ConnectorEventOpts, body?: ActivityBodyFn): this;
     /**
      * START the process when an Integration Service connector event fires
      * (`Intsvc.EventTrigger` on a `bpmn:startEvent` carrying a message event
@@ -1851,9 +2472,10 @@ declare abstract class ScopeBuilder {
      * @param action - The `AgentExecution` operation name.
      * @param inputs - The invocation payload.
      * @param opts - `mode`, the connection/folder bindings, and what to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    externalAgent(id: string, connector: string, action: string, inputs: Record<string, unknown>, opts: ExternalTaskOpts): this;
+    externalAgent(id: string, connector: string, action: string, inputs: Record<string, unknown>, opts: ExternalTaskOpts, body?: ActivityBodyFn): this;
     /**
      * Invoke an external workflow through an Integration Service connector
      * (`Intsvc.SyncWorkflowExecution` / `Intsvc.AsyncWorkflowExecution`).
@@ -1867,9 +2489,10 @@ declare abstract class ScopeBuilder {
      * @param action - The `ProcessExecution` operation name.
      * @param inputs - The invocation payload.
      * @param opts - `mode`, the connection/folder bindings, and what to keep.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    externalWorkflow(id: string, connector: string, action: string, inputs: Record<string, unknown>, opts: ExternalTaskOpts): this;
+    externalWorkflow(id: string, connector: string, action: string, inputs: Record<string, unknown>, opts: ExternalTaskOpts, body?: ActivityBodyFn): this;
     /** @internal Shared body of the two external-invocation methods. */
     private externalTask;
     /**
@@ -1902,18 +2525,217 @@ declare abstract class ScopeBuilder {
      * @param id - The element id, unique in the process and used by `sequenceFlow`.
      * @param type - The registry extension type, e.g. `'A2A.AgentExecution'`.
      * @param opts - Context values, payload, output mapping and the shared activity options.
+     * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
      * @returns This builder, so calls chain.
      */
-    activity(id: string, type: string, opts?: ActivityNodeOpts): this;
+    activity(id: string, type: string, opts?: ActivityNodeOpts, body?: ActivityBodyFn): 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.
+    * @param body - Boundary events attached to this activity, declared on the {@link ActivityBuilder} it receives.
     * @returns This builder, so calls chain.
     */
-    subProcess(id: string, fn: (sp: SubProcessBuilder) => void, opts?: SubProcessOpts): this;
+    subProcess(id: string, fn: (sp: SubProcessBuilder) => void, opts?: SubProcessOpts, body?: ActivityBodyFn): this;
+    /**
+     * An EVENT sub-process — a handler that lives inside this scope and starts when
+     * an error, a message, or a timer occurs anywhere in it (`bpmn:subProcess
+     * triggeredByEvent="true"`, with its single start event synthesized).
+     *
+     * @remarks
+     * The construct BPMN has for a safety net: it has no incoming flow, and it
+     * catches what nothing closer to the failing element caught. Distinct from a
+     * boundary handler (`.onError()` on one activity), which guards one element; this
+     * guards the whole container it sits in, so where it sits is what it guards — put
+     * it inside a multi-instance sub-process to fail one iteration rather than the
+     * whole run.
+     *
+     * Its body is written in order: elements chain from the synthesized start, and
+     * branch with `.choose()` / `.fork()` / `.race()`. Every path must end — with an
+     * end event or an explicit `.sequenceFlow()` off its last element — because an
+     * event sub-process has nowhere else to go.
+     *
+     * @example
+     * **A central failure net that classifies on the error it caught**
+     * ```ts
+     * bpmn('payroll')
+     *   .var('outcome', 'string', { default: 'RUNNING' })
+     *   .startEvent('start')
+     *   .scriptTask('calculate', { script: 'return { ok: true };' })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'calculate')
+     *   .sequenceFlow('calculate', 'done')
+     *   .eventSubProcess('failures', { error: true, name: 'Failure net' }, (h) =>
+     *     h.choose('kind', [
+     *       {
+     *         // The start captures the error into `vars.Error` by default (`errorVar`).
+     *         when: '=js:String(vars.Error.code).indexOf("DATA") >= 0',
+     *         label: 'Bad data',
+     *         body: (b) => b.task('flagData', { set: { outcome: 'FAILED_BAD_DATA' } }).endEvent('badData', { name: 'Bad data handled' }),
+     *       },
+     *       {
+     *         otherwise: true,
+     *         label: 'Outage',
+     *         body: (b) => b.task('flagOutage', { set: { outcome: 'FAILED_OUTAGE' } }).endEvent('outage', { name: 'Outage escalated' }),
+     *       },
+     *     ]),
+     *   )
+     *   .build();
+     * ```
+     *
+     * @param id - The sub-process's element id. The start event is `<id>_start` unless `startId` says otherwise.
+     * @param opts - What starts it — exactly one of `error` / `message` / `timer` — and the rest of {@link EventSubProcessOpts}.
+     * @param fn - Receives the body builder; elements chain in the order they are written.
+     * @returns This builder, so calls chain.
+     * @throws If none or several of `error` / `message` / `timer` are given, if an error start
+     * is asked to be non-interrupting, or if a path in the body is left open.
+     */
+    eventSubProcess(id: string, opts: EventSubProcessOpts, fn: (sp: SubProcessBuilder) => void): this;
+    /**
+     * An exclusive decision whose arms are written in place — the splitting gateway,
+     * each arm's conditioned flow, the arm's elements and the rejoining gateway, from
+     * one call.
+     *
+     * @remarks
+     * Each arm has a `when` condition or is the single `otherwise` fallback, so an arm
+     * with no condition cannot be written, and the fallback is the gateway's default
+     * flow without anyone naming a flow id. Arms rejoin at the next element placed
+     * after the `choose`; a join gateway (`<id>_join`) is emitted only when more than
+     * one arm actually reaches it, so an arm that ends in an end event adds no join.
+     *
+     * Inside an arm, consecutive elements are wired in order, and an arm may nest
+     * further `choose` / `fork` / `race` calls, activities with boundary handlers, or
+     * `.goto()` to jump to an element written elsewhere. An arm with no body is an
+     * empty branch straight to the continuation.
+     *
+     * @example
+     * **Approve or reject, then carry on**
+     * ```ts
+     * bpmn('review')
+     *   .var('action', 'string')
+     *   .var('status', 'string')
+     *   .startEvent('start')
+     *   .task('decide', { set: { action: 'Approved' } })
+     *   .choose('approved', [
+     *     { when: '=vars.action == "Approved"', label: 'Yes', body: (b) => b.task('post', { set: { status: 'posted' } }) },
+     *     { otherwise: true, label: 'No', body: (b) => b.task('reject', { set: { status: 'rejected' } }) },
+     *   ])
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'decide')
+     *   .sequenceFlow('decide', 'approved')
+     *   .build();
+     * ```
+     *
+     * @param id - The splitting gateway's element id; the join, when emitted, is `<id>_join`.
+     * @param arms - The arms — see {@link ChooseArm}.
+     * @param opts - `name`, `inclusive` for an inclusive gateway, and `join` to name the join gateway.
+     * @returns This builder, so calls chain.
+     * @throws If there are no arms, more than one `otherwise`, or more than one empty arm.
+     */
+    choose(id: string, arms: ChooseArm[], opts?: ChooseOpts): this;
+    /**
+     * A parallel split whose arms are written in place: every arm runs, and they
+     * rejoin through a parallel join (`<id>_join`) before the next element.
+     *
+     * @example
+     * **Two lookups at once, then one summary**
+     * ```ts
+     * bpmn('enrich')
+     *   .startEvent('start')
+     *   .fork('gather', [
+     *     (b) => b.http('poLookup', { method: 'GET', url: 'https://erp.example.com/po/1' }),
+     *     (b) => b.http('vendorLookup', { method: 'GET', url: 'https://erp.example.com/vendor/1' }),
+     *   ])
+     *   .scriptTask('summarise', { script: 'return { ok: true };' })
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'gather')
+     *   .sequenceFlow('summarise', 'done')
+     *   .build();
+     * ```
+     *
+     * @param id - The splitting gateway's element id; the join is `<id>_join`.
+     * @param arms - One body per parallel arm.
+     * @param opts - `name` for the splitting gateway, and `join` to name the join gateway.
+     * @returns This builder, so calls chain.
+     */
+    fork(id: string, arms: ArmBodyFn[], opts?: SplitOpts): this;
+    /**
+     * An event-based gateway whose arms are written in place: each arm begins with
+     * something to wait for, the first to happen wins, and the rest are cancelled.
+     *
+     * @remarks
+     * An arm must begin with an `intermediateCatchEvent` (message or timer), a
+     * `receiveMessage`, or a `waitForEvent` — that is what the gateway waits on, and
+     * the builder refuses anything else in first position. Arms rejoin through an
+     * exclusive join (`<id>_join`) when more than one falls through.
+     *
+     * @example
+     * **A reply, or a three-day timeout**
+     * ```ts
+     * bpmn('vendor')
+     *   .startEvent('start')
+     *   .race('waitForEither', [
+     *     (b) => b.intermediateCatchEvent('reply', { message: 'VendorReplied' }),
+     *     (b) => b.intermediateCatchEvent('timeout', { timer: 'P3D' }).endEvent('gaveUp', { name: 'No reply' }),
+     *   ])
+     *   .endEvent('done')
+     *   .sequenceFlow('start', 'waitForEither')
+     *   .build();
+     * ```
+     *
+     * @param id - The gateway's element id; the join, when emitted, is `<id>_join`.
+     * @param arms - One body per alternative, each beginning with the event it waits for.
+     * @param opts - `name` for the gateway, and `join` to name the join gateway.
+     * @returns This builder, so calls chain.
+     * @throws If an arm does not begin with something that waits.
+     */
+    race(id: string, arms: ArmBodyFn[], opts?: SplitOpts): this;
+    /**
+     * Give the edges the nesting constructs IMPLY the ids you choose.
+     *
+     * @remarks
+     * A construct's edges have no call of their own — you write `.choose()` or place two
+     * statements in a sequence scope, and the edge between them follows — so there is
+     * nowhere to name one, and its id is derived as `Flow_<source>_<target>`. That is
+     * fine for a new process and wrong for an edited one: a `.bpmn` that came from
+     * somewhere carries ids like `edge_zOoHdO`, and `uip maestro bpmn merge` keys every
+     * element by id, flows included. Re-derive them and the merge treats every flow as
+     * new, deletes the originals, and takes their diagram edges with them — and any
+     * gateway `default` preserved from the original is left naming an id that no longer
+     * exists, which `uip maestro bpmn validate` then rejects.
+     *
+     * So this is how a decompiled process keeps the ids it arrived with while still
+     * being written in the constructs. `bpmn decompile --style nested` emits one call
+     * listing every implied edge whose original id is not the derived one.
+     *
+     * Only implied edges: an explicit `.sequenceFlow()` already takes an `id`, and a
+     * pair listed here that no implied edge ever connects is simply unused.
+     *
+     * @example
+     * **Keep an import's edge ids through a lift**
+     * ```ts
+     * bpmn('orders')
+     *   .var('total', 'number', { default: 0 })
+     *   .flowIds([
+     *     { source: 'Gw_1', target: 'Review', id: 'edge_zOoHdO' },
+     *     { source: 'Gw_1', target: 'Pay', id: 'edge_Kp2mQ1' },
+     *   ])
+     *   .startEvent('Start_1')
+     *   .choose('Gw_1', [
+     *     { when: '=vars.total > 1000', body: (b) => b.task('Review').goto('Done') },
+     *     { otherwise: true, body: (b) => b.task('Pay').goto('Done') },
+     *   ])
+     *   .endEvent('Done')
+     *   .sequenceFlow('Start_1', 'Gw_1')
+     *   .build();
+     * ```
+     *
+     * @param entries - The edges to pin, by their endpoints.
+     * @returns This builder, so calls chain.
+     */
+    flowIds(entries: PinnedFlowId[]): this;
     /**
      * A sequence flow from `source` to `target` (1-1 with `bpmn:sequenceFlow`).
      *
@@ -2031,9 +2853,186 @@ export declare function typedNodeDeclaredVars(n: Extract<BpmnNode, {
 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 {
+    /**
+     * Open an event sub-process body on its synthesized start event.
+     *
+     * @param start - The start event node.
+     * @internal
+     */
+    _begin(start: BpmnNode): void;
+    /**
+     * Close a body written in order: every path in it must have ended.
+     *
+     * @param what - The scope, for the message.
+     * @internal
+     */
+    _finishBody(what: string): void;
     /** @internal */
     _buildNode(id: string, opts: SubProcessOpts): BpmnNode;
 }
+/**
+ * One arm of a `choose` / `fork` / `race`, or one boundary handler's path: the same
+ * graph methods as any scope, written INTO the enclosing scope, with consecutive
+ * elements wired in order.
+ *
+ * @remarks
+ * An arm creates no BPMN scope of its own — its elements and flows belong to the
+ * scope the construct was written in, and variables declared here are that scope's
+ * — so an explicit `.sequenceFlow()` may reach any element of that scope, and
+ * `.goto()` jumps to one without leaving the nesting. Its path ends with an end
+ * event or `.goto()`, or falls through to whatever follows the construct.
+ *
+ * Inside an arm, branch with `.choose()` / `.fork()` / `.race()`; a bare gateway is
+ * refused, because its outgoing flows cannot be implied.
+ */
+export declare class PathBuilder extends ScopeBuilder {
+    /** @internal The first element placed — what a `race` arm waits on. */
+    _first?: BpmnNode;
+    /**
+     * @param defs - The process's message/error declarations.
+     * @param bindings - The process's bindings.
+     * @param storage - The enclosing scope's arrays, which this arm writes into.
+     * @param sugar - Process-wide bookkeeping for the nesting sugar.
+     * @param entry - The edge(s) this arm continues from.
+     * @param scopeMode - The mode of the real scope the arm writes into, for a nested `.subProcess()` to inherit.
+     * @internal
+     */
+    constructor(defs: DefinitionsRegistry, bindings: BindingsRegistry, storage: ScopeStorage, sugar: SugarRegistry, entry: PendingExit[], scopeMode: WiringMode);
+    /** @internal */
+    protected place(node: BpmnNode, viaSugar?: boolean): void;
+    /**
+     * Leave this arm for an element written elsewhere — a loop back to an earlier
+     * step, a jump into another arm, a shared exit — writing the edge without leaving
+     * the nesting. Nothing may follow it in the arm.
+     *
+     * @example
+     * **Retry from the top when the check fails**
+     * ```ts
+     * bpmn('retrying')
+     *   .var('ok', 'boolean')
+     *   .startEvent('start')
+     *   .scriptTask('attempt', { script: 'return { ok: true };', outputs: { ok: '=result.ok' } })
+     *   .choose('worked', [
+     *     { when: '=vars.ok == true', body: (b) => b.endEvent('done') },
+     *     { otherwise: true, body: (b) => b.goto('attempt') },
+     *   ])
+     *   .sequenceFlow('start', 'attempt')
+     *   .sequenceFlow('attempt', 'worked')
+     *   .build();
+     * ```
+     *
+     * @param target - The id of the element to continue at.
+     * @returns This builder; nothing more may be placed on this arm.
+     */
+    goto(target: string): this;
+    /**
+     * Finish the arm and hand its open ends back to the construct that owns it.
+     *
+     * @returns The exits still open — empty when every path ended.
+     * @internal
+     */
+    _finish(): PendingExit[];
+}
+/**
+ * The boundary events of one activity, declared on the activity itself — what the
+ * body callback every activity method accepts receives.
+ *
+ * @remarks
+ * `attachedTo` is the receiver: a handler declared here is attached to the activity
+ * whose body it is written in, so a boundary event on nothing, or on a gateway,
+ * cannot be written. Each handler's path is written in place, in order, and
+ * continues as {@link TimerHandlerOpts.interrupting} describes: an interrupting
+ * handler rejoins at the statement after the activity, a non-interrupting one must
+ * end on its own.
+ *
+ * @example
+ * **A human task with a reminder and a failure exit**
+ * ```ts
+ * bpmn('approval')
+ *   .var('reminded', 'string')
+ *   .startEvent('start')
+ *   .humanTask('approve', { app: 'InvoiceApproval', actions: ['Approve', 'Reject'] }, (t) => {
+ *     t.onTimer('PT1H', { interrupting: false }, (b) =>
+ *       b.task('remind', { set: { reminded: 'true' } }).endEvent('reminded'));
+ *     t.onError((b) => b.endEvent('failed', { name: 'Approval failed' }));
+ *   })
+ *   .endEvent('done')
+ *   .sequenceFlow('start', 'approve')
+ *   .sequenceFlow('approve', 'done')
+ *   .build();
+ * ```
+ */
+export declare class ActivityBuilder {
+    private readonly scope;
+    private readonly activity;
+    /**
+     * @param scope - The scope the activity was placed in.
+     * @param activity - The activity's id.
+     * @internal
+     */
+    constructor(scope: ScopeBuilder, activity: string);
+    /**
+     * Catch an error the activity throws — any error, or one declared kind — on an
+     * interrupting error boundary, and handle it on the path written here.
+     *
+     * @param body - The handler path; omitted, the error simply continues to the next statement.
+     * @returns This builder, so handlers chain.
+     */
+    onError(body?: ArmBodyFn): this;
+    /**
+     * Catch a specific error — see {@link ErrorLike} — or `true` for any.
+     *
+     * @param error - What to catch.
+     * @param body - The handler path.
+     * @returns This builder, so handlers chain.
+     */
+    onError(error: ErrorLike, body?: ArmBodyFn): this;
+    /**
+     * Catch an error with options — an `id`, a `name`, an `errorVar` to capture it into.
+     *
+     * @param error - What to catch: `true` for any error, or a declared kind.
+     * @param opts - See {@link ErrorHandlerOpts}.
+     * @param body - The handler path.
+     * @returns This builder, so handlers chain.
+     */
+    onError(error: ErrorLike, opts: ErrorHandlerOpts, body?: ArmBodyFn): this;
+    /**
+     * Fire a timer while the activity runs — a deadline that cancels it, or a
+     * reminder that does not (`interrupting: false`).
+     *
+     * @param timer - An ISO-8601 duration string, or a full {@link TimerSpec}.
+     * @param body - The handler path.
+     * @returns This builder, so handlers chain.
+     */
+    onTimer(timer: TimerLike, body?: ArmBodyFn): this;
+    /**
+     * Fire a timer with options — `interrupting`, an `id`, a `name`.
+     *
+     * @param timer - An ISO-8601 duration string, or a full {@link TimerSpec}.
+     * @param opts - See {@link TimerHandlerOpts}.
+     * @param body - The handler path.
+     * @returns This builder, so handlers chain.
+     */
+    onTimer(timer: TimerLike, opts: TimerHandlerOpts, body?: ArmBodyFn): this;
+    /**
+     * Catch a message while the activity runs — declaring or reusing the
+     * definitions-level `bpmn:message`.
+     *
+     * @param message - The message's name.
+     * @param body - The handler path.
+     * @returns This builder, so handlers chain.
+     */
+    onMessage(message: string, body?: ArmBodyFn): this;
+    /**
+     * Catch a message with options — `interrupting`, an `id`, a `name`.
+     *
+     * @param message - The message's name.
+     * @param opts - See {@link MessageHandlerOpts}.
+     * @param body - The handler path.
+     * @returns This builder, so handlers chain.
+     */
+    onMessage(message: string, opts: MessageHandlerOpts, body?: ArmBodyFn): this;
+}
 /**
  * The top-level process builder `bpmn()` returns — every graph method of the
  * shared scope (events, gateways, tasks, sub-processes, flows, variables) plus