@uipath/maestro-builder-sdk 5.2.0

package/dist/flow-sdk.d.ts

@@ -0,0 +1,1341 @@
+/**
+ * flow-sdk — a small fluent builder for UiPath Flow workflows.
+ *
+ * You author a workflow as TypeScript code that *constructs* a graph of nodes
+ * and edges. Calling `.build()` returns a plain description of that graph; the
+ * `compile` tool serializes it into a real `.flow` JSON file.
+ *
+ * This is deliberately a builder, not a program: control flow (branch/loop) is
+ * expressed by calling `.branch()` / `.loop()`, not with native `if`/`for`.
+ * Data references are expressed with the expression helpers (`input`, `out`,
+ * `v`, `js`, `tmpl`) rather than by reading real values — nothing actually runs
+ * at build time except the graph construction.
+ *
+ * The expression helpers and action specs are shared across all builder SDKs
+ * and live in `core/`; this module re-exports them so the historical
+ * `flow-sdk.js` authoring surface is unchanged, and adds the Flow-specific
+ * builder (steps, branches, loops, return).
+ */
+export * from './core/expr.js';
+export * from './core/actions.js';
+export { resolveFlowRefs, resolveRefPath, hasFileRefs } from './ref-resolve.js';
+export type { RefReader, ResolveRefsOptions } from './ref-resolve.js';
+export * from './core/connectors.js';
+export * from './core/lookups.js';
+export * from './core/node-classes.js';
+import { Expr } from './core/expr.js';
+import type { ErrorEnvelopeField, TypeDesc } from './core/expr.js';
+import type { ActionSpec, EventSubscription, TriggerOptions } from './core/actions.js';
+import type { FlowAction, FlowTrigger } from './core/node-classes.js';
+import type { TriggerDescriptor } from './core/connectors.js';
+export { FlowBuildError, checkFlowExpressions } from './flow-expr-check.js';
+export type { LocatedDiagnostic } from './flow-expr-check.js';
+/** A step that runs a child flow. Built by `subflow(child, inputs)`. */
+export interface SubflowSpec {
+    kind: 'subflow';
+    /** The child flow's built description — its own inputs, outputs and steps. */
+    child: BuiltFlow;
+    /** One value per child input, keyed by the child's declared input name. */
+    inputs: Record<string, Expr>;
+}
+/** What `.step()` accepts here: the shared actions plus this SDK's subflow. */
+export type FlowActionSpec = ActionSpec | SubflowSpec;
+/** Anything `subflow()` accepts as the child: a builder, or an already-built flow. */
+export type ChildFlow = BuiltFlow | {
+    build(): BuiltFlow;
+};
+export interface VarDecl {
+    name: string;
+    type: TypeDesc;
+    default?: unknown;
+    /** Human-readable description, persisted on the variable. */
+    description?: string;
+    /** Sub-type for complex types (e.g. an array's item type). */
+    subType?: string;
+    /** JSON schema for complex type validation (object/array shapes). */
+    schema?: Record<string, unknown>;
+}
+/**
+ * The rich spelling of a variable declaration: pass it instead of a bare
+ * `types.*` descriptor wherever `.input()` / `.output()` / `.var()` take one,
+ * to carry the metadata the `.flow` format persists on a global — a
+ * description, a `subType`, a JSON `schema` for object/array shapes, and (for
+ * inputs and vars) a `default`.
+ */
+export interface VarSpec {
+    /** The variable's type, one of the `types.*` descriptors. */
+    type: TypeDesc;
+    /** Human-readable description, persisted on the variable. */
+    description?: string;
+    /** Sub-type for complex types (e.g. an array's item type). */
+    subType?: string;
+    /** JSON schema for complex type validation (object/array shapes). */
+    schema?: Record<string, unknown>;
+    /** Default value — inputs and vars only; the format forbids it on outputs. */
+    default?: unknown;
+}
+/**
+ * The eight intervals the designer offers in its Frequency dropdown. Any other
+ * valid
+ * {@link https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm | ISO-8601 repeating interval}
+ * works too (see `ScheduleEvery`) — these are
+ * just the ones that round-trip as a named preset rather than as "custom".
+ */
+export declare const SCHEDULE_PRESETS: readonly ["R/PT5M", "R/PT15M", "R/PT30M", "R/PT1H", "R/PT6H", "R/PT12H", "R/P1D", "R/P1W"];
+export type SchedulePreset = (typeof SCHEDULE_PRESETS)[number];
+/**
+ * How often a scheduled flow runs, as an
+ * {@link https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm | ISO-8601 repeating interval}:
+ * `R/` followed by a duration. `R/PT1H` = every hour, `R/PT30M` = every half
+ * hour, `R/P1D` = daily, `R/P1W` = weekly.
+ *
+ * @remarks
+ * The union with `string` is deliberate — a preset autocompletes, and any other
+ * valid interval (`R/PT45M`, `R/P3D`, `R/2026-05-14T09:00:00Z/P1W`) is accepted.
+ * `check` validates the format and rejects a schedule that can never fire.
+ */
+export type ScheduleEvery = SchedulePreset | (string & {});
+export interface ScheduledInputs {
+    /**
+     * The recurring interval, e.g. `'R/PT1H'` for hourly.
+     *
+     * @remarks
+     * ONE field, deliberately, where the emitted `.flow` has two: the platform
+     * encodes a preset in `timerPreset` and anything else as
+     * `timerPreset: 'custom'` + `timerValue`. That split is a designer-form
+     * artifact — the runtime collapses it right back to a single interval — so
+     * the serializer does the encoding and there is nothing here to get wrong.
+     */
+    every: ScheduleEvery;
+}
+/**
+ * What starts the flow. Three options: the manual trigger (the default — omit
+ * `.trigger()`), a schedule, or a CONNECTOR EVENT.
+ */
+export type TriggerSpec = {
+    kind: 'manual';
+} | {
+    kind: 'scheduled';
+    inputs: ScheduledInputs;
+} | {
+    kind: 'event';
+    subscription: EventSubscription;
+} | {
+    kind: 'form';
+} | {
+    kind: 'conversation';
+} | {
+    kind: 'voice';
+};
+/**
+ * The manual trigger, explicitly. Omitting `.trigger(...)` means exactly this —
+ * the factory exists so decompiled source can carry the trigger's exact
+ * definition version (`.trigger(manual(), { version: '1.0.0' })`) instead of
+ * leaving the default implicit, and so hand-written flows can opt into the
+ * same explicitness.
+ *
+ * @returns A trigger spec to pass to `.trigger(...)`.
+ */
+export declare function manual(): TriggerSpec;
+/**
+ * Start the flow when a connector event fires — e.g. an email arriving in a
+ * mailbox folder.
+ *
+ * @remarks
+ * ```ts
+ * export default flow('intake')
+ *   .trigger(onEvent({
+ *     connector: 'uipath-microsoft-outlook365',
+ *     event: 'email-received',
+ *     where: { parentFolderId: inboxId },
+ *   }))
+ *   .step('extract', script({ code: 'return { subject: $vars.start.output.subject };' }))
+ *   .build();
+ * ```
+ *
+ * A generated {@link TriggerDescriptor} can supply the connector/event instead —
+ * `.trigger(onEvent(EmailReceived, { where: { parentFolderId: inboxId } }))` —
+ * see `sdk/connectors/<key>.triggers.ts`.
+ *
+ * The trigger's payload is read like any step output — `out('start', 'subject')`
+ * — and locally it is supplied as flow input (`--input`), because a start trigger
+ * produces no dispatch record. **No local rung fires a real event**: what a green
+ * ladder proves is the right trigger type, the right subscription, and that the
+ * graph runs. See `references/event-trigger.md`.
+ *
+ * To pause an already-running flow instead, use `waitForEvent(...)` as a step —
+ * the same subscription, the sibling node type.
+ *
+ * This is the TYPED form — a generated trigger descriptor identifies the event,
+ * as in `onEvent(EmailReceived, { where: { … } })`.
+ *
+ * @param descriptor - The generated trigger, from a prepared connector module.
+ * @param opts - The event's `where` scope, `filters`, and symbolic
+ * `connection` / `folder`.
+ * @returns A trigger spec to pass to `.trigger(...)`.
+ */
+export declare function onEvent<W>(descriptor: TriggerDescriptor<W, unknown>, opts?: TriggerOptions<W>): TriggerSpec;
+/**
+ * Stringly form, for an event with no prepared module.
+ *
+ * @param subscription - The event to start on: `connector`, `event`, its `where`
+ * scope, and optional `filters`.
+ * @returns A trigger spec to pass to `.trigger(...)`.
+ */
+export declare function onEvent(subscription: EventSubscription): TriggerSpec;
+/**
+ * Start the flow on a recurring schedule instead of on demand.
+ *
+ * @remarks
+ * Field shapes, the interval format, and what a local run does and does not
+ * prove: `references/scheduled-trigger.md`.
+ *
+ * @example
+ * **Run a flow daily**
+ * ```ts
+ * export default flow('nightly-rollup')
+ *   .trigger(scheduled({ every: 'R/P1D' }))
+ *   .step('rollup', script({ code: 'return { ok: true };' }))
+ *   .build();
+ * ```
+ *
+ * @param inputs - The recurring interval, e.g. `{ every: 'R/PT1H' }`.
+ * @returns A trigger spec to pass to `.trigger(...)`.
+ */
+export declare function scheduled(inputs: ScheduledInputs): TriggerSpec;
+/**
+ * Start the flow from a FORM a person fills in (`core.trigger.form`) — the
+ * platform renders one field per flow input and the submitted values ARE the
+ * flow's inputs.
+ *
+ * ```ts
+ * export default flow('expense-request')
+ *   .input({ amount: types.number, reason: types.string })
+ *   .trigger(formTrigger())
+ *   .step('review', hitl({ … }))
+ *   .build();
+ * ```
+ *
+ * The form's fields are DERIVED from `.input()` — one per input, the same rule
+ * the designer's own form-trigger editor applies to a flow's arguments: the
+ * field id is the input's name (so submitted values line up by name), the label
+ * is the name sentence-cased, the field type follows the input's type, and a
+ * field is required exactly when its input declares no default.
+ *
+ * The definition is BUNDLED from the workbench manifest — the tenant registry
+ * does not serve the family (same availability note as do-while).
+ *
+ * No local rung renders a form: `--input` supplies the values locally, and a
+ * green ladder proves the trigger type, the derived schema, and that the graph
+ * runs — not that a person saw a form.
+ *
+ * @returns A trigger spec to pass to `.trigger(...)`.
+ */
+export declare function formTrigger(): TriggerSpec;
+/**
+ * Start the flow when a new CONVERSATION is created
+ * (`core.trigger.conversation`) — the entry point for a chat-driven process.
+ *
+ * ```ts
+ * export default flow('support-chat')
+ *   .trigger(conversationTrigger())
+ *   .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ *   .step('answer', sendMessage({
+ *     conversationId: out('start', 'conversationId'),
+ *     exchangeId: out('listen', 'conversationContext.latestExchangeId'),
+ *     content: 'Looking into it.',
+ *   }))
+ *   .build();
+ * ```
+ *
+ * The trigger publishes the conversation it started —
+ * `out('start', 'conversationId')` — which is what every conversational step
+ * is keyed by. Nothing else is authored on it.
+ *
+ * The definition is BUNDLED from the workbench manifest: the family is
+ * `AvailableOnTenant: false` today, so a flow compiles and validates offline
+ * while the platform catches up (the do-while precedent).
+ *
+ * @returns A trigger spec to pass to `.trigger(...)`.
+ */
+export declare function conversationTrigger(): TriggerSpec;
+/**
+ * Start the flow when a phone call comes IN (`core.trigger.voice`).
+ *
+ * ```ts
+ * export default flow('support-line')
+ *   .trigger(voiceTrigger())
+ *   .step('greet', voiceAgent({
+ *     systemPrompt: 'Greet {{input.customerName}} and find out why they called.',
+ *     inputs: { customerName: input('customerName') },
+ *     callContext: out('start', 'callContext'),
+ *   }))
+ *   .step('hangUp', endCall({ callContext: out('start', 'callContext') }))
+ *   .build();
+ * ```
+ *
+ * The trigger publishes the live call as `out('start', 'callContext')` — the
+ * object (`{ type, id, conversationId, … }`) every voice step is keyed by.
+ * Nothing else is authored on it.
+ *
+ * The definition is BUNDLED from the workbench manifest: the family is
+ * `AvailableOnTenant: false` today (the do-while precedent).
+ *
+ * @returns A trigger spec to pass to `.trigger(...)`.
+ */
+export declare function voiceTrigger(): TriggerSpec;
+/** A value a `.switch` case compares the discriminant against. */
+export type CaseValue = string | number | boolean;
+/** One arm of a built `.switch` (the serializer's view: body already collected). */
+export interface SwitchArm {
+    value: CaseValue;
+    label?: string;
+    body: Step[];
+}
+/**
+ * Options shared by every builder method that creates a definition-backed node:
+ * `version` selects the exact node definition to compile against, and `updates`
+ * assigns flow variables when the node completes.
+ */
+export interface NodeOptions {
+    /**
+     * The EXACT `definitions[].version` (and node `typeVersion`) this node must
+     * compile against — a request and a constraint, never a "latest" selector.
+     * Omit it and the SDK uses its pinned default for the node family; name a
+     * version the SDK cannot resolve exactly and compilation fails rather than
+     * substituting another version.
+     */
+    version?: string;
+    /**
+     * Flow-variable assignments applied when this node completes — the format's
+     * `variables.variableUpdates[nodeId]`, attached to the real node exactly as
+     * Flow JSON stores it. Keys name declared `.var()` variables (or flow
+     * outputs); values are `Expr`s or raw literals.
+     *
+     * @remarks
+     * Not accepted on `.branch()`, `.switch()`, `.parallel()`, or `.trigger()` —
+     * the platform strips updates from decision/switch/merge nodes on save, and a
+     * trigger has not run anything to assign from.
+     */
+    updates?: Record<string, Expr | unknown>;
+    /**
+     * What the canvas shows on this node (`display.label`). Defaults to the step
+     * name.
+     *
+     * @remarks
+     * Purely cosmetic, and deliberately separate from the step name: the NAME is
+     * the node's identity — it becomes the node id and every `out('<step>', …)`
+     * reads through it — so renaming what a reviewer sees must not move the node
+     * or rewrite its expressions. Use a step name you want to write code against
+     * and a label you want to read on the canvas.
+     *
+     * ```ts
+     * .step('fetchInv', http({ url, managed: true }), { label: 'Fetch invoice' })
+     * ```
+     *
+     * `.branch()`, `.switch()`, `.loop()`, `.doWhile()`, `.parallel()` and
+     * `.terminate()` take their label as a positional argument instead.
+     */
+    label?: string;
+}
+/**
+ * `.return(...)`-specific options.
+ *
+ * @remarks
+ * An End is the one node the builder used to give no way to name: every other
+ * construct takes its id positionally (`.step('<name>', …)`, `.terminate('<name>')`),
+ * but a `.return()` always minted `end`, `end2`, … and labelled the node `End`.
+ * That made a decompile → compile round trip impossible for any flow whose Ends
+ * carry designer-chosen ids — the normal case, since the canvas names an End
+ * after the branch arm that reaches it, so `endNiceDay` / `endBringJacket` rather
+ * than `end` / `end2`. Decompile emitted a `.layout({ nodes: { endNiceDay: … } })`
+ * block naming ids the recompile then failed to produce, and compile rejected its
+ * own round trip with `layout: "endNiceDay" names no step or node in this flow`.
+ */
+export interface ReturnOptions extends NodeOptions {
+    /**
+     * The End node's id — what `layout` keys on and what `nodes[].id` becomes.
+     * Defaults to `end`, then `end2`, `end3`, … in emission order.
+     *
+     * @remarks
+     * Like a step name this is identity, not decoration: use {@link NodeOptions.label}
+     * for what the canvas shows. Ids are de-duplicated, so two Ends both asking for
+     * `done` become `done` and `done2`.
+     *
+     * ```ts
+     * .branch('checkTemperature', js`$vars.tempF > 60`,
+     *   (t) => t.return({}, { name: 'endNiceDay', label: 'Nice Day' }),
+     *   (e) => e.return({}, { name: 'endBringJacket', label: 'Bring a Jacket' }))
+     * ```
+     */
+    name?: string;
+}
+/**
+ * Loop-specific options. Any of these — or a `b.break()` in the
+ * body — selects the loop's v2.4 definition (the current Workbench contract,
+ * with inner `start`/`continue`/`break` handles); a plain `.loop()` keeps the
+ * SDK's long-pinned 1.0.0 emission unchanged. An explicit `{ version: '1.0.0' }`
+ * combined with any of these fails compilation: that definition cannot express
+ * them.
+ */
+export interface LoopOptions extends NodeOptions {
+    /** Run iterations in parallel instead of sequentially. */
+    parallel?: boolean;
+    /**
+     * Stop early when this condition (evaluated after each iteration) is true —
+     * e.g. `js`$vars.hits.output.length >= 10``.
+     */
+    completionCondition?: Expr;
+    /**
+     * Show the loop's break handle without wiring one — set automatically when
+     * the body calls `b.break()`.
+     */
+    breakEnabled?: boolean;
+}
+/**
+ * Do-while options. `limit` caps iterations; the platform
+ * defaults a blank limit to 10,000 and rejects values outside 1–10,000.
+ */
+export interface DoWhileOptions extends NodeOptions {
+    /** Maximum iterations, 1–10,000. Blank means the platform default (10,000). */
+    limit?: number;
+    /** Show the break handle without wiring one — set automatically by `b.break()`. */
+    breakEnabled?: boolean;
+}
+export type Step = {
+    kind: 'action';
+    name: string;
+    spec: FlowActionSpec;
+    options?: NodeOptions;
+} | {
+    kind: 'branch';
+    name: string;
+    label?: string;
+    trueLabel?: string;
+    falseLabel?: string;
+    cond: Expr;
+    then: Step[];
+    otherwise: Step[];
+    options?: NodeOptions;
+} | {
+    kind: 'switch';
+    name: string;
+    label?: string;
+    on: Expr;
+    cases: SwitchArm[];
+    default?: Step[];
+    options?: NodeOptions;
+} | {
+    kind: 'loop';
+    name: string;
+    label?: string;
+    collection: Expr;
+    body: Step[];
+    options?: LoopOptions;
+}
+/**
+ * A do-while container (`core.logic.dowhile`): run the body, then repeat
+ * while `condition` is true, up to `options.limit` iterations.
+ */
+ | {
+    kind: 'doWhile';
+    name: string;
+    label?: string;
+    condition: Expr;
+    body: Step[];
+    options?: DoWhileOptions;
+}
+/**
+ * Exit the enclosing loop/do-while through its break handle. Terminal on its
+ * path — nothing after it can run. Only valid inside a container body.
+ */
+ | {
+    kind: 'break';
+}
+/**
+ * A fan-out and its join. `arms` is one step list per arm — an ARRAY, because
+ * arms are positional and carry no author-supplied keys — and `name` names the
+ * Merge node the arms converge on (the only node this step creates; the fork
+ * itself is just N edges out of one port).
+ */
+ | {
+    kind: 'parallel';
+    name: string;
+    label?: string;
+    arms: Step[][];
+    options?: NodeOptions;
+}
+/**
+ * A hard stop: `core.logic.terminate`, a BPMN End event carrying a
+ * TerminateEventDefinition. Ends the whole RUN, not just this path — which is
+ * the only difference from `return`, and the reason it needs a node id.
+ */
+ | {
+    kind: 'terminate';
+    name: string;
+    label?: string;
+    options?: NodeOptions;
+}
+/**
+ * An edge to another step, by name. Creates no node of its own: it is ONE
+ * EDGE, added after the whole flow is emitted, because the target is often
+ * declared later in the file than the step that names it.
+ *
+ * `port` is the port of the step this leaves — `'output'` (the default) hands
+ * the path off, so nothing may follow it in the same list; any other port is a
+ * side exit and the chain continues. See `StepList.stepToRef`.
+ */
+ | {
+    kind: 'stepToRef';
+    port: string;
+    target: string;
+}
+/**
+ * A step list wired from a named PORT of the step this follows — the general
+ * form of an error handler. The body is its own path: it either ends in a
+ * terminal of its own or hands control back with a `stepToRef`.
+ *
+ * `.onError(...)` is this with `port: 'error'`, which is the case nearly every
+ * flow uses. See `StepList.stepToList`.
+ */
+ | {
+    kind: 'stepToList';
+    port: string;
+    body: Step[];
+} | {
+    kind: 'return';
+    name: string;
+    values: Record<string, Expr>;
+    options?: ReturnOptions;
+};
+/** One node's designer layout: canvas position, and optionally size and collapsed state. */
+export interface NodeLayout {
+    /** Absolute canvas position. */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Node size; omit for the designer default. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** Whether the node renders collapsed. */
+    collapsed?: boolean;
+}
+/** One edge's route: user-dragged bends and/or the auto-router's waypoints. */
+export interface EdgeRoute {
+    /** Manually placed bends, in canvas coordinates. Win over the routed set. */
+    waypoints?: {
+        x: number;
+        y: number;
+        id?: string;
+    }[];
+    /** The layout engine's obstacle-avoiding route. */
+    routedWaypoints?: {
+        x: number;
+        y: number;
+        id?: string;
+    }[];
+}
+/**
+ * The designer's sticky-note palette. Any other string is passed through — the
+ * `.flow` format stores `inputs.color` unvalidated — but these five are what the
+ * canvas offers and what round-trips as a named swatch.
+ */
+export declare const STICKY_NOTE_COLORS: readonly ["yellow", "pink", "blue", "green", "white"];
+/**
+ * A sticky note's swatch. One of {@link STICKY_NOTE_COLORS} autocompletes; any
+ * other string is accepted and passed straight through, because the format
+ * stores `inputs.color` without validating it.
+ */
+export type StickyNoteColor = (typeof STICKY_NOTE_COLORS)[number] | (string & {});
+/**
+ * A canvas sticky note — free text pinned to the diagram, for the humans reading
+ * it.
+ *
+ * @remarks
+ * A note is a real entry in the file's `nodes[]` (type `stickyNote`), not a
+ * layout entry, which is why it carries an `id` and its own geometry. It has no
+ * manifest and no definition: the platform skips it during validation and
+ * conversion, and drops any edge touching it. So it is inert — it annotates the
+ * diagram and can never change what the flow does.
+ */
+export interface StickyNote {
+    /**
+     * The note's node id. Defaults to `stickyNote_1`, `stickyNote_2`, … in
+     * declaration order.
+     *
+     * @remarks
+     * Name it when the flow is round-tripped (decompile → edit → compile): the id
+     * is what makes a note the SAME note across compiles, so an unnamed note in an
+     * edited file can renumber and read as delete-plus-create.
+     */
+    id?: string;
+    /** The note's text. */
+    content: string;
+    /** Swatch; defaults to `'yellow'`. */
+    color?: StickyNoteColor;
+    /** Canvas x of the note's top-left corner. */
+    x: number;
+    /** Canvas y of the note's top-left corner. */
+    y: number;
+    /** Note width. Pass it with `height` or not at all; omit for the designer default. */
+    width?: number;
+    /** Note height. Pass it with `width` or not at all; omit for the designer default. */
+    height?: number;
+}
+/**
+ * Designer layout for a flow, keyed by AUTHOR-level ids: node
+ * entries by step name (plus the trigger id and `end`), edge entries by
+ * `"<fromStep>-><toStep>"`. Serialization resolves the keys after node ids are
+ * finalized; an unknown key is a compile error, an omitted node simply stays
+ * where the serializer's default puts it. Layout is metadata — it never
+ * affects semantic checks.
+ */
+export interface FlowLayout {
+    /** Per-node layout, keyed by step name / trigger id / `end`. */
+    nodes?: Record<string, NodeLayout>;
+    /** Per-edge routes, keyed by `"<fromStep>-><toStep>"`. */
+    edges?: Record<string, EdgeRoute>;
+}
+/** One additional flow root, built by `.entryPoint()`. */
+export interface BuiltEntryPoint {
+    /** The trigger node's id — also the root expressions read (`$vars.<id>.output.x`). */
+    id: string;
+    /** What fires this root: `manual()`, `scheduled(...)`, or `onEvent(...)`. */
+    trigger: TriggerSpec;
+    /** Node options for the trigger node — exact `version` selection. */
+    options?: NodeOptions;
+    /** Inputs scoped to this root (globals bound to it via `triggerNodeId`). */
+    inputs: VarDecl[];
+    /** The root's prefix steps, run before it joins the shared body. */
+    steps: Step[];
+}
+export interface BuiltFlow {
+    id: string;
+    name: string;
+    /** Human-readable description, persisted at the top of the .flow file. */
+    description?: string;
+    version: string;
+    /**
+     * The FILE-FORMAT version the emitted `.flow` declares, from
+     * `.schemaVersion()`. Absent means "the SDK's default write floor"
+     * (`FLOW_FORMAT_PROFILE.version`), which is what every flow authored before
+     * the method existed means too — so an absent value changes nothing.
+     */
+    schemaVersion?: string;
+    inputs: VarDecl[];
+    outputs: VarDecl[];
+    vars: VarDecl[];
+    steps: Step[];
+    /** Omitted for the manual trigger (the default), so an existing flow's built
+     *  description — and the `.flow` it serializes to — is unchanged. */
+    trigger?: TriggerSpec;
+    /** Node options given on `.trigger(spec, options)` — exact version selection. */
+    triggerOptions?: NodeOptions;
+    /** Designer layout from `.layout()`, resolved at serialization. */
+    layout?: FlowLayout;
+    /** Canvas sticky notes from `.stickyNotes()`. Inert annotations. */
+    stickyNotes?: StickyNote[];
+    /** Additional roots from `.entryPoint()`. The default root stays `.trigger()`/`.input()`. */
+    entryPoints?: BuiltEntryPoint[];
+    /**
+     * The trigger node's id. Defaults to `start`. It matters because a flow's
+     * declared inputs are published as this node's output, so `input('x')` reads
+     * `$vars.<triggerId>.output.x` — rename the node and every such reference
+     * follows.
+     */
+    triggerId?: string;
+}
+/** Collects a sequence of steps. Used for the flow body and each branch/loop arm. */
+declare class StepList {
+    steps: Step[];
+    /**
+     * The step whose failure led here, set only on the sub-builder `.onError(...)`
+     * hands its callback. `err()` on this builder needs no step name because of it.
+     */
+    private errorSource?;
+    /**
+     * Read the failure that led into this handler → `err('<the failed step>', field)`.
+     *
+     * @remarks
+     * Only available on the sub-builder `.onError(...)` / `.stepToList('error', …)`
+     * passes to its callback, because only there is "the step that failed" a fact
+     * rather than a guess.
+     *
+     * Prefer it over the free `err('<step>', field)` inside a handler. It cannot
+     * name the wrong step, it cannot drift when the step is renamed, and — the
+     * reason it exists — it keeps the envelope's LOCATION out of author-visible
+     * code entirely. Which variable carries the envelope is per node family
+     * (measured: `<step>.error` on connectors, script, deep-rag, subflow and
+     * queue; `<step>.output` on managed http), and the compiler resolves it.
+     *
+     * ```ts
+     * .step('load', script({ code: 'return JSON.parse($vars.start.output.raw);' }))
+     * .onError((h) => h.return({ note: tmpl`bad payload: ${h.err('message')}` }))
+     * ```
+     *
+     * @param field - One of the envelope's fields. Omit it to test WHETHER the
+     * step failed (the boolean the platform sets when the boundary fires).
+     * @returns An {@link Expr} reading the failure of the step this handler guards.
+     * @see err
+     */
+    err(field?: ErrorEnvelopeField): Expr;
+    /**
+     * Add an action node (see `http` / `script` / `subflow`).
+     *
+     * @param name - The step's id. Read its result downstream with `out('<name>')`,
+     * so it must be unique within the flow.
+     * @param spec - What the node does, from an action factory.
+     * @param options - Node options; `version` selects the exact definition
+     * version (see {@link NodeOptions}).
+     * @returns This builder, so calls chain.
+     */
+    step(name: string, spec: FlowActionSpec | FlowAction, options?: NodeOptions): this;
+    /**
+     * Handle the PREVIOUS step's failure: if it fails, the flow runs `bodyFn`'s
+     * steps instead of continuing.
+     *
+     * @remarks
+     * ```ts
+     * .step('fetch', http({ url: apiUrl, managed: true, returns: { items: 'array' } }))
+     * .onError((h) => h.return({ result: lit('Article not found') }))
+     * .step('total', transform({ … }))     // runs only when `fetch` SUCCEEDED
+     * .return({ result: out('total') })
+     * ```
+     *
+     * The handler is its own path — anything chained after `.onError(...)` belongs
+     * to the SUCCESS path only. Inside it, read the failure with
+     * {@link StepList.err} — `h.err('message')` — or with the free
+     * `err('<step>', 'message')` if you prefer to name the step. The envelope
+     * carries `code`, `message`, `detail`, `category` and `status` (`code` is a
+     * string even for an HTTP status, `status` a number), plus an undeclared
+     * `response` and `element` the runtime adds.
+     *
+     * Do NOT reach for `out('<step>', …)` in here. That reads the step's SUCCESS
+     * output, which was never written — the handler runs precisely because the
+     * step failed — and `check` refuses it (ERROR_ENVELOPE_VIA_OUTPUT). This doc
+     * line used to recommend `out('<step>', 'error', 'message')`, which is not
+     * even a legal call: `out(step, path?)` takes two arguments.
+     *
+     * **Three ways the handler can end**: `.return(...)` answers the flow,
+     * `.terminate(...)` stops the run, and `h.rejoin('<step>')` compensates and
+     * hands control back to a step the success path also reaches — the shape most
+     * deployed flows use. A handler that just runs out of steps still gets its own
+     * End: rejoining is something the author SAYS, never something wiring infers.
+     * See {@link StepList.stepToRef}.
+     *
+     * Two things this does for you, by construction: it sets
+     * `errorHandlingEnabled` on the node in the same write as the edge (without
+     * it the platform routes but Studio Web HIDES the handle, so no human can see
+     * your handler), and it refuses at build time on a step whose node type has no
+     * error port.
+     *
+     * **A `.loop()` container takes one too.** `core.logic.loop` declares the
+     * handle, and a body step's failure routes to it: the container's envelope
+     * carries the body's message in `detail` and the failing body step's id in
+     * `element`, and the instance completes rather than faulting. `.doWhile()` does
+     * NOT — it declares an error variable and no error handle — so that one is
+     * refused by name, and its failures belong to the body step that can fail.
+     *
+     * **A plain `http()` step is the trap worth knowing**: a 404 there is a
+     * SUCCESS with `statusCode: 404`, so the handler never runs — use
+     * `http({ …, managed: true })` when failures must route. `check` says so
+     * (HTTP_ONERROR_V1).
+     *
+     * Which node types can fail, what the envelope carries, and what a local run
+     * does and does not prove: `references/error-handling.md`.
+     *
+     * @param bodyFn - Receives a sub-builder for the handler's own path. Read the
+     * failure inside it with `h.err('message')` ({@link StepList.err}).
+     * @returns This builder, positioned on the SUCCESS path — anything chained after
+     * this call runs only when the step succeeded.
+     * @enforcedBy HTTP_ONERROR_V1 On an http step this needs `managed: true`; on the
+     * standalone node a 4xx arrives on the SUCCESS path and no handler runs.
+     */
+    onError(bodyFn: (b: StepList) => void): this;
+    /**
+     * The step a port-scoped edge leaves, and the guard that it is allowed to.
+     *
+     * Scans BACK past edges already attached to the same step: after
+     * `.onError(...)` the last entry in the list is that handler, not the action it
+     * guards, so `steps.at(-1)` would refuse a second port-edge on the same step —
+     * and would attach `.stepToRef('error', …)` to the wrong thing.
+     *
+     * A port takes exactly one outgoing edge (the definitions say so:
+     * `maxConnections: 1`), so a second edge from the same port is refused here
+     * rather than emitted and silently dropped downstream.
+     */
+    private portSource;
+    /**
+     * Run a step list from a named PORT of the step this follows — the general form
+     * of an error handler, and the reason `.onError()` needs no machinery of its own.
+     *
+     * @remarks
+     * The body is its own path. It ends by answering (`.return`), stopping the run
+     * (`.terminate`), or handing control back with `.stepToRef(...)`; a body that
+     * simply runs out of steps gets its own End, exactly as an error handler does.
+     *
+     * The main path is untouched — an edge out of a NON-default port is a side exit,
+     * so whatever you chain after this call still belongs to the step's normal
+     * continuation.
+     *
+     * ```ts
+     * .step('fetch', http({ … , managed: true }))
+     * .stepToList('error', (h) => h.step('log', script({ … })).stepToRef('settle'))
+     * .step('parse', script({ … }))     // ← still the SUCCESS path
+     * ```
+     *
+     * @param port - The port of the preceding step to leave from, e.g. `'error'`.
+     * @param bodyFn - Receives a sub-builder for the path that port leads to.
+     * @returns This builder, so calls chain.
+     * @see stepToRef
+     */
+    stepToList(port: string, bodyFn: (b: StepList) => void): this;
+    /**
+     * The shared body of `.stepToList()` and `.onError()`.
+     *
+     * Private because `called` and `noun` exist only so a refusal names the method
+     * the author actually called — they are not part of the surface, and a public
+     * parameter nobody should pass is a worse trade than one extra hop.
+     */
+    private addPortList;
+    /**
+     * Branch on a condition. `thenFn`/`elseFn` receive a sub-builder for each arm.
+     *
+     * @remarks
+     * Each arm can name itself with `.label(...)` — the then-arm's label becomes the
+     * node's `trueLabel`, the else-arm's its `falseLabel` (the text the designer
+     * shows on the two outgoing edges). Omit it and the arms keep the default
+     * `"True"` / `"False"`.
+     *
+     * @param name - The decision node's id.
+     * @param cond - The condition, as an expression — typically `js\`…\``.
+     * @param thenFn - Receives a sub-builder for the TRUE arm.
+     * @param elseFn - Receives a sub-builder for the FALSE arm. Omit it for a
+     * decision whose false path simply continues.
+     * @param options - Node options; `version` selects the exact definition
+     * version (see {@link NodeOptions}).
+     * @returns This builder, after both arms have rejoined.
+     */
+    branch(name: string, cond: Expr, thenFn: (b: ArmBuilder) => void, elseFn?: (b: ArmBuilder) => void, options?: NodeOptions): this;
+    /**
+     * N-way branch on the value of `on` — one arm per case, plus an optional
+     * default arm. Each arm gets its own sub-builder, exactly like `.branch`.
+     *
+     * @remarks
+     * A case matches when `on === case.value`, compared the way JavaScript's own
+     * `switch` compares: **strictly, so the type counts**. `value: 2` matches a
+     * `types.number` input carrying `2`; `value: '2'` does not. Cases are
+     * evaluated top to bottom and the first match wins.
+     *
+     * @example
+     * **Route on a value, with a default arm**
+     * ```ts
+     * .switch('routeQuarter', input('quarter'), [
+     *   { value: 1, body: (b) => b.step('spring', script({ code: 'return "Spring";' })) },
+     *   { value: 2, body: (b) => b.step('summer', script({ code: 'return "Summer";' })) },
+     * ], (other) => other.step('unknown', script({ code: 'return "Unknown";' })))
+     * ```
+     *
+     * @param name - The switch node's id.
+     * @param on - The value to compare each case against.
+     * @param cases - One entry per arm, evaluated top to bottom; the first strict
+     * match wins. `label` names the arm's outgoing edge.
+     * @param defaultFn - Receives a sub-builder for the arm taken when nothing
+     * matches. Omit it and an unmatched value simply continues.
+     * @param options - Node options; `version` selects the exact definition
+     * version (see {@link NodeOptions}).
+     * @returns This builder, after every arm has rejoined.
+     */
+    switch(name: string, on: Expr, cases: {
+        value: CaseValue;
+        body: (b: ArmBuilder) => void;
+        label?: string;
+    }[], defaultFn?: (b: StepList) => void, options?: NodeOptions): this;
+    /**
+     * Run two or more arms **in parallel** from this point and join them back
+     * together on a Merge node — the one place the builder stops being a straight
+     * chain.
+     *
+     * @remarks
+     * `name` names the **Merge** node (the join). Each arm is a sub-builder, just
+     * like a `.branch` arm, and every arm starts from the same place the chain had
+     * reached, so the graph forks there and reconverges on the Merge.
+     *
+     * Anything you chain afterwards continues from the Merge, so it can read every
+     * arm's output. The Merge itself computes nothing and publishes nothing — read
+     * the steps inside the arms, never `$vars.<merge>`.
+     *
+     * Arm semantics, what a local run does and does not prove, and the rules
+     * `check` enforces: `references/parallel-merge.md`.
+     *
+     * @example
+     * **Fetch two things at once, then combine them after the join**
+     * ```ts
+     * .parallel('sync', [
+     *   (a) => a.step('fetchWeather', script({ code: 'return "sunny";' })),
+     *   (b) => b.step('fetchNews',    script({ code: 'return "quiet";' })),
+     * ])
+     * .step('combine', script({ code: 'return $vars.fetchWeather.output + $vars.fetchNews.output;' }))
+     * ```
+     *
+     * @param name - The split node's id. The Merge node is derived from it.
+     * @param arms - One callback per parallel arm, each receiving its own
+     * sub-builder. Two or more.
+     * @param options - Node options; `version` selects the exact definition
+     * version (see {@link NodeOptions}).
+     * @returns This builder, positioned after the Merge — so what you chain next
+     * runs once, when every arm has finished.
+     */
+    parallel(name: string, arms: ((b: StepList) => void)[], options?: NodeOptions): this;
+    /**
+     * Iterate `collection`; `bodyFn` receives a sub-builder for the loop body.
+     *
+     * @param name - The loop node's id.
+     * @param collection - The array to iterate, as a reference — `v('items')` or
+     * `out('fetch', 'body.items')`.
+     * @param bodyFn - Receives a sub-builder for the body, run once per element.
+     * @param options - Node options; `version` selects the exact definition
+     * version (see {@link NodeOptions}).
+     * @returns This builder, positioned after the loop.
+     */
+    loop(name: string, collection: Expr, bodyFn: (b: StepList) => void, options?: LoopOptions): this;
+    /**
+     * Run the body, then repeat **while `condition` is true** — the condition is
+     * checked AFTER each iteration, so the body always runs at least once
+     * (`core.logic.dowhile`). The container publishes no data output; write
+     * results to a `.var()` from inside the body (`{ updates }`), and read the
+     * loop's progress nowhere — unlike `.loop()` there is no `currentItem`.
+     *
+     * @example
+     * **Paginate until the API says stop**
+     * ```ts
+     * .var('page', types.number, 1)
+     * .doWhile('paginate', js`$vars.fetch.output.hasNextPage === true`, (b) => b
+     *   .step('fetch', http({ url: tmpl`https://api.example.test/items?page=${v('page')}`, method: 'GET', managed: false, returns: { hasNextPage: 'boolean' } }), {
+     *     updates: { page: js`$vars.page + 1` },
+     *   }), { limit: 50 })
+     * ```
+     *
+     * @param name - The container node's id.
+     * @param condition - Repeat while this is true, checked after each pass.
+     * @param bodyFn - Receives a sub-builder for the body, run once per pass.
+     * @param options - `limit` (1–10,000; blank = platform default 10,000),
+     * `breakEnabled`, and the common node options (see {@link DoWhileOptions}).
+     * @returns This builder, positioned after the loop.
+     */
+    doWhile(name: string, condition: Expr, bodyFn: (b: StepList) => void, options?: DoWhileOptions): this;
+    /**
+     * Exit the enclosing `.loop()` / `.doWhile()` through its **break handle**,
+     * ending the whole loop now — not just this iteration. Terminal on its path:
+     * nothing may follow it, exactly like `.terminate()`. Using it enables the
+     * container's break handle automatically. Compilation fails when there is no
+     * enclosing container.
+     *
+     * @returns This builder. Nothing after this call on the same path can run.
+     */
+    break(): this;
+    /**
+     * Stop the **whole run**, here and now — not just this path.
+     *
+     * @remarks
+     * That is the only difference from `.return()`, and it is a big one: inside a
+     * `.parallel` arm a terminate **aborts the sibling arms**, whatever they were
+     * in the middle of. A `.return()` in the same place would only end its own
+     * path and leave the others running.
+     *
+     * Nothing may follow a terminate: it publishes no value, and no step after it
+     * — in its arm or chained behind it — can ever run.
+     *
+     * What aborts, what the run reports, and what each local rung can prove:
+     * `references/terminate.md`.
+     *
+     * @example
+     * **Abort the sibling arm from inside a parallel**
+     * ```ts
+     * .parallel('branches', [
+     *   (a) => a.terminate('stopEverything'),
+     *   (b) => b.step('wait', delay({ duration: 'PT10S' })).return({ message: 'done' }),
+     * ])
+     * ```
+     *
+     * @param name - The terminate node's id.
+     * @param label - Text the designer shows on the node. Omit it for the default.
+     * @param options - Node options; `version` selects the exact definition
+     * version (see {@link NodeOptions}).
+     * @returns This builder. Nothing after this call on the same path can run.
+     */
+    terminate(name: string, label?: string, options?: NodeOptions): this;
+    /**
+     * Go to another step, by name — an edge, not a node.
+     *
+     * @remarks
+     * With one argument it leaves the step's default `output` port, which HANDS THE
+     * PATH OFF: nothing may follow it in this list, because the flow continues at
+     * the target. With a port it is a side exit — the main path is untouched and
+     * chaining continues, which is how an error port reaches an existing step
+     * without a handler body.
+     *
+     * ```ts
+     * .step('fetch', http({ … }))
+     * .stepToRef('settle')                 // continue at "settle"
+     *
+     * .step('charge', http({ … , managed: true }))
+     * .stepToRef('error', 'refund')        // its failure goes to "refund"
+     * .step('receipt', script({ … }))      // ← still the SUCCESS path
+     * ```
+     *
+     * The target may be declared later in the file, and may be BACKWARD of this
+     * step: Flow JSON can express either, so this can author either. What `check`
+     * can prove it refuses; what depends on the runtime it warns about and leaves to
+     * `uip maestro flow validate`.
+     *
+     * @param target - The step to continue at, named as it was in `.step(...)`.
+     * @returns This builder. Nothing may follow: the path has been handed off.
+     * @see stepToList
+     */
+    stepToRef(target: string): this;
+    /**
+     * Go to another step from a NAMED PORT — a side exit.
+     *
+     * @remarks
+     * The main path is untouched, so whatever you chain after this call still
+     * belongs to the step's normal continuation. This is how a failure reaches an
+     * existing step without a handler body of its own.
+     *
+     * ```ts
+     * .step('charge', http({ … , managed: true }))
+     * .stepToRef('error', 'refund')        // its failure goes to "refund"
+     * .step('receipt', script({ … }))      // ← still the SUCCESS path
+     * ```
+     *
+     * @param port - The port of this step to leave, e.g. `'error'`.
+     * @param target - The step to continue at, named as it was in `.step(...)`.
+     * @returns This builder, so calls chain — a side exit ends nothing.
+     * @see stepToList
+     */
+    stepToRef(port: string, target: string): this;
+    /**
+     * Terminate this path, binding flow outputs to expressions.
+     *
+     * @param values - One entry per declared flow output. A raw value is wrapped as
+     * a literal; an {@link Expr} is emitted as a reference.
+     * @param options - Node options; `version` selects the exact definition
+     * version (see {@link NodeOptions}).
+     * @returns This builder. This path has answered, so nothing after it runs.
+     */
+    return(values?: Record<string, Expr | unknown>, options?: ReturnOptions): this;
+}
+/**
+ * The sub-builder an ARM callback receives — a `StepList` that can also name
+ * itself with `.label(...)`.
+ *
+ * @remarks
+ * It exists so `.label()` is available exactly where it means something (a
+ * `.branch` or `.switch` arm) and NOT on the top-level flow, which names itself
+ * with `.name(...)`. The parent's `branch`/`switch` reads `armLabel` back after
+ * running the callback and lowers it to the node's arm label (`trueLabel` /
+ * `falseLabel` for a decision, the case `label` for a switch).
+ */
+declare class ArmBuilder extends StepList {
+    armLabel?: string;
+    /**
+     * Name this arm. The label is what the designer shows on the arm's outgoing
+     * edge; it also survives a round-trip through Flow JSON, where a bare
+     * `"True"` / `"False"` / `Case "<value>"` would not carry the author's intent.
+     * Order-independent — call it anywhere in the arm's chain.
+     *
+     * @param text - The label the designer shows on this arm's outgoing edge.
+     * @returns This builder, so calls chain.
+     */
+    label(text: string): this;
+}
+declare class FlowBuilder extends StepList {
+    private readonly _id;
+    private _name;
+    private _description?;
+    private _layout?;
+    private _stickyNotes?;
+    private _version;
+    private _schemaVersion?;
+    private _inputs;
+    private _outputs;
+    private _vars;
+    private _trigger?;
+    private _triggerOptions?;
+    private _entryPoints;
+    private _triggerId?;
+    constructor(_id: string);
+    /**
+     * Set the flow's display name.
+     *
+     * @param n - The name the designer shows. Defaults to the flow's id.
+     * @returns This builder, so calls chain.
+     * @defaultValue the flow's id
+     */
+    name(n: string): this;
+    /**
+     * Set the flow's description — persisted as the top-level `description`
+     * field of the emitted `.flow`, shown in the designer's flow header.
+     *
+     * @param text - What this flow does, for humans.
+     * @returns This builder, so calls chain.
+     */
+    description(text: string): this;
+    /**
+     * Set designer layout — node positions/sizes and edge routes — keyed by the
+     * flow's own logical ids (step names, the trigger id, `end`). Optional pure
+     * metadata: nothing here changes what the flow does, and omitting it leaves
+     * the serializer's default arrangement. Unknown keys fail compilation rather
+     * than being dropped.
+     *
+     * @param layout - Node layout by step name, edge routes by `"from->to"`.
+     * @returns This builder, so calls chain.
+     */
+    layout(layout: FlowLayout): this;
+    /**
+     * Pin free-text notes to the canvas, for whoever reads the diagram.
+     *
+     * @remarks
+     * Sticky notes are the only annotation `.flow` has. Each becomes a real
+     * `stickyNote` node, which the platform skips during validation and
+     * conversion and whose edges it drops — so a note can never change what the
+     * flow does, and `check` treats it as inert.
+     *
+     * Calling this twice REPLACES the set rather than appending, matching
+     * `.layout()`.
+     *
+     * @example
+     * ```ts
+     * .stickyNotes([
+     *   { content: 'Rates refresh at 02:00 UTC', x: 240, y: 40 },
+     *   { id: 'why-retry', content: 'The vendor 502s under load.', color: 'pink',
+     *     x: 240, y: 320, width: 220, height: 120 },
+     * ])
+     * ```
+     *
+     * @param notes - The notes to pin. Position is required; `id`, `color` and
+     * size have defaults.
+     * @returns This builder, so calls chain.
+     */
+    stickyNotes(notes: StickyNote[]): this;
+    /**
+     * Set what starts the flow. Omit this call for the **manual** trigger (a
+     * caller starts the flow on demand) — that is the default and what most
+     * flows want.
+     *
+     * @example
+     * **Run the flow hourly instead of on demand**
+     * ```ts
+     * .trigger(scheduled({ every: 'R/PT1H' }))
+     * ```
+     *
+     * @param spec - What starts the flow, from `scheduled(...)` or `onEvent(...)`.
+     * @param options - Node options; `version` selects the exact definition
+     * version (see {@link NodeOptions}).
+     * @returns This builder, so calls chain.
+     * @defaultValue the manual trigger
+     */
+    trigger(spec: TriggerSpec | FlowTrigger, options?: NodeOptions): this;
+    /**
+     * Add an ADDITIONAL flow root: its own trigger node, its own
+     * scoped inputs (read them with `entryInput('<id>', '<name>')`), and an
+     * optional prefix that runs before the root joins the shared body. Without a
+     * prefix the root connects straight to the first shared step; a prefix that
+     * ends terminally (or hands off with `.stepToRef()`) joins nothing.
+     *
+     * @remarks
+     * The DEFAULT root stays `.trigger()` / `.input()` — one flow, one default
+     * entry point, marked `isDefaultEntryPoint` in the emitted file. Every root
+     * (default included) gets its platform entry-point identity when a flow has
+     * more than one.
+     *
+     * @example
+     * **A manual flow with a second, nightly-scheduled root**
+     * ```ts
+     * flow('order-intake')
+     *   .input({ order: types.object })                      // the default (manual) root
+     *   .entryPoint('nightly', scheduled({ every: 'R/P1D' }), {
+     *     inputs: { batchDate: types.string },
+     *   }, (b) => b.step('loadBatch', script({ code: 'return { order: { id: $vars.nightly.output.batchDate } };', returns: 'object' })))
+     *   .step('normalize', script({ code: 'return 1;' }))    // shared body
+     * ```
+     *
+     * @param id - The root's trigger-node id — unique among entry points, steps,
+     * and the default trigger id. Expressions read it as `$vars.<id>.output.*`.
+     * @param trigger - What fires this root: `manual()`, `scheduled(...)`, or
+     * `onEvent(...)`.
+     * @param options - `version` (exact trigger definition version) and `inputs`
+     * — this root's scoped inputs, declared like `.input()`.
+     * @param prefixFn - Optional sub-builder for the root's prefix steps.
+     * @returns This builder, so calls chain.
+     */
+    entryPoint(id: string, trigger: TriggerSpec | FlowTrigger, options?: {
+        version?: string;
+        inputs?: Record<string, TypeDesc | VarSpec>;
+    }, prefixFn?: (b: StepList) => void): this;
+    /**
+     * Rename the trigger node. The designer can rename it, so the SDK can too.
+     *
+     * @remarks
+     * The id is not cosmetic: a flow's declared inputs are published as the trigger
+     * node's output, so `input('amount')` reads `$vars.<triggerId>.output.amount`.
+     * Renaming the node rewrites every such reference with it.
+     *
+     * @example
+     * **Rename the trigger; input reads follow**
+     * ```ts
+     * .triggerId('intake')        // input('amount') → $vars.intake.output.amount
+     * ```
+     *
+     * @param id - The trigger node's new id. Every `input(...)` reference is
+     * rewritten to read through it.
+     * @returns This builder, so calls chain.
+     * @defaultValue `'start'`
+     */
+    triggerId(id: string): this;
+    /**
+     * Set the flow's version.
+     *
+     * @param vsn - The version string. It does NOT reach the emitted `.flow`.
+     * @returns This builder, so calls chain.
+     * @deprecated Top-level `version` in a `.flow` file is the FILE-FORMAT
+     * version, owned by the serializer's format profile (design §5.4) — it was
+     * never an author-controlled artifact version, and the serializer has always
+     * overwritten this value. The call is kept for source compatibility and
+     * ignored. To target a specific file-format version, use
+     * {@link FlowBuilder.schemaVersion}; there is no author-controlled artifact
+     * version in the format for this to have meant.
+     */
+    version(vsn: string): this;
+    /**
+     * Declare the `.flow` FILE-FORMAT (schema) version this flow targets.
+     *
+     * @remarks
+     * This is the document's grammar version — the top-level `version` a `.flow`
+     * carries — and it is the one version concept that IS the author's to set,
+     * which is exactly what {@link FlowBuilder.version} is not. Omit it and the
+     * flow declares the SDK's default (the fleet write floor, `1.9`), which is
+     * what every flow authored before this method existed already did.
+     *
+     * Its real job is BROWNFIELD PRESERVATION. `flow-decompile` emits this call
+     * with the version it read, so a decompile → edit → compile round-trip
+     * re-declares the file's own version instead of silently rewriting a `1.10`
+     * file as `1.9`. Migrating a document BETWEEN versions stays
+     * `uip maestro flow migrate`'s job: a hop can carry data repairs (the
+     * 1.9 → 1.10 hop repairs connector binding names) that this SDK has no way to
+     * reproduce from the source alone.
+     *
+     * Only versions this build can actually write are accepted — `1.6` through
+     * `1.10`, the band whose schemas are the same shape as what the serializer
+     * emits. A version is a CLAIM that the whole document matches that schema,
+     * not a switch that reshapes it, so declaring one the serializer cannot emit
+     * would write a false claim; the call throws instead. Both directions off the
+     * floor cost something — above it, a reader pinned lower (an older CLI, an
+     * Automation Suite ring) refuses the file; below it, every reader migrates
+     * forward on open — so `check()` reports `SCHEMA_VERSION_ABOVE_FLOOR` /
+     * `SCHEMA_VERSION_BELOW_FLOOR` rather than deciding for you.
+     *
+     * @example
+     * **Round-trip a 1.10 flow without downgrading it**
+     * ```ts
+     * flow('claims').schemaVersion('1.10')
+     * ```
+     *
+     * @param version - A writable file-format version, e.g. `'1.9'` or `'1.10'`.
+     * @returns This builder, so calls chain.
+     * @throws Error when this SDK build cannot write `version`.
+     * @defaultValue `'1.9'` — `FLOW_FORMAT_PROFILE.version`, the fleet write floor.
+     */
+    schemaVersion(version: string): this;
+    /**
+     * Declare the flow's inputs. Read them with `input('<name>')`.
+     *
+     * @param shape - Input names to type descriptors, e.g. `{ amount: types.number }`.
+     * @returns This builder, so calls chain.
+     * @see input
+     */
+    input(shape: Record<string, TypeDesc | VarSpec>): this;
+    /**
+     * Declare the flow's outputs — what `.return(...)` binds values to.
+     *
+     * @param shape - Output names to type descriptors, e.g. `{ total: types.number }`.
+     * @returns This builder, so calls chain.
+     */
+    output(shape: Record<string, TypeDesc | VarSpec>): this;
+    /**
+     * Declare a flow-level variable. Read it with `v('<name>')`.
+     *
+     * @param name - The variable's name.
+     * @param type - One of the `types.*` descriptors.
+     * @param defaultValue - Its initial value. Omit it to start undeclared.
+     * @returns This builder, so calls chain.
+     * @see v
+     */
+    var(name: string, type: TypeDesc | VarSpec, defaultValue?: unknown): this;
+    /**
+     * Finish the flow and return the graph the compiler serializes.
+     *
+     * @returns The built description — inputs, outputs, variables, trigger and steps.
+     * @throws FlowBuildError when an expression references something undeclared.
+     */
+    build(): BuiltFlow;
+}
+/**
+ * Start building a flow with the given id.
+ *
+ * @param id - The flow's stable identifier, and its display name until
+ * `.name(...)` says otherwise.
+ * @returns A {@link FlowBuilder} to declare inputs and chain steps onto.
+ * @example
+ * ```ts
+ * export default flow('hello').name('Hello')
+ *   .output({ greeting: types.string })
+ *   .step('greet', script({ code: 'return "hi";', returns: 'string' }))
+ *   .return({ greeting: out('greet') })
+ *   .build();
+ * ```
+ */
+export declare function flow(id: string): FlowBuilder;
+/**
+ * Run another flow as one step, and read back what it returns.
+ *
+ * @remarks
+ * The child is an ordinary `flow()` in the same file — its own inputs, steps
+ * and `.return()`. Don't call `.build()` on it; the parent's `.build()` collects
+ * it. Two scopes, joined only by this call: the child sees NOTHING of the
+ * parent's variables except the values passed in here.
+ *
+ * `inputs` keys are the CHILD's declared input names; the values are
+ * parent-scope expressions. A subflow's output is an OBJECT of the child's
+ * declared outputs, so read it with the output's name —
+ * `out('callReverse', 'reversed')`, never a bare `out('callReverse')`.
+ *
+ * Scopes, reuse, nesting, and what a local run does and does not prove:
+ * `references/subflow.md`.
+ *
+ * @example
+ * **Call a child flow and read its named output**
+ * ```ts
+ * const reverse = flow('reverse-text')
+ *   .input({ text: types.string })
+ *   .output({ reversed: types.string })
+ *   .step('rev', script({ code: 'return $vars.text.split("").reverse().join("");' }))
+ *   .return({ reversed: out('rev') });
+ *
+ * export default flow('reverse-outer')
+ *   .input({ text: types.string })
+ *   .output({ result: types.string })
+ *   .step('callReverse', subflow(reverse, { text: input('text') }))
+ *   .return({ result: out('callReverse', 'reversed') })   // NAME the child output
+ *   .build();
+ * ```
+ *
+ * @param child - The child flow — a `flow()` builder or an already-built flow.
+ * @param inputs - One value per the CHILD's declared input names, as parent-scope
+ * expressions.
+ * @returns An action spec for `.step(...)`.
+ */
+export declare function subflow(child: ChildFlow, inputs?: Record<string, Expr | unknown>): SubflowSpec;