@uipath/maestro-builder-sdk 5.2.0

package/dist/flow-sdk.js

@@ -0,0 +1,1164 @@
+/**
+ * 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).
+ */
+// Re-export the shared core authoring surface (Expr, lit/v/input/out/js/tmpl,
+// types, and http/script/connector action specs) so `./flow-sdk.js` remains the
+// single import an author needs.
+export * from './core/expr.js';
+export * from './core/actions.js';
+// `$ref`-split ingestion (design §5): decompile resolves local-file refs into
+// one object model. Exported so a host doing its own file reading can too.
+export { resolveFlowRefs, resolveRefPath, hasFileRefs } from './ref-resolve.js';
+export * from './core/connectors.js';
+export * from './core/lookups.js';
+export * from './core/node-classes.js';
+import { err as errRef, toExpr, types } from './core/expr.js';
+import { builtinActionSpec, builtinTriggerSpec, subscriptionFrom } from './core/actions.js';
+import { checkFlowExpressions, FlowBuildError } from './flow-expr-check.js';
+import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
+import { schemaVersionRefusal } from './schema-version.js';
+export { FlowBuildError, checkFlowExpressions } from './flow-expr-check.js';
+const TYPE_NAMES = Object.values(types);
+/**
+ * Reject a `.input()` / `.output()` argument that is not a `{ name: type }` map.
+ *
+ * WHY THIS THROWS INSTEAD OF DIAGNOSING. TypeScript's types are erased at run
+ * time, so `.output('title', 'string')` — the object-shaped API called as if it
+ * took two positional arguments — reaches the builder as the plain string
+ * `'title'`. `Object.entries('title')` is `[['0','t'],['1','i'],…]`, so the flow
+ * quietly declared five globals named `"0".."4"` with types `t,i,t,l,e`.
+ * The source checker said "no issues" (nothing it looks at was wrong — the names and types
+ * were merely nonsense), and the mistake only surfaced further down the ladder, about
+ * a file the author never wrote.
+ *
+ * This is the same class as `.branch('big','amount')` (card T1) and the same fix
+ * shape: normalize or reject at the builder, where the mistake is. `.input()` and
+ * `.output()` run while the module is being evaluated, so the throw arrives before
+ * anything else — with the call that caused it named.
+ */
+function assertShape(method, shape) {
+    if (typeof shape !== 'object' || shape === null || Array.isArray(shape)) {
+        throw new TypeError(`.${method}() takes ONE object mapping names to types — got ${Array.isArray(shape) ? 'an array' : typeof shape}`
+            + `${typeof shape === 'string' ? ` (${JSON.stringify(shape)})` : ''}. `
+            + `Write .${method}({ ${typeof shape === 'string' ? shape : 'name'}: types.string }), not `
+            + `.${method}('name', 'string'): a string would be iterated character by character and `
+            + `declare one garbage variable per letter.`);
+    }
+    return shape;
+}
+/**
+ * Normalize a `TypeDesc | VarSpec` declaration value into VarDecl fields.
+ * Outputs reject `default` — the format only persists defaults on `in`/`inout`.
+ */
+function varDeclOf(method, name, value) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const spec = value;
+        assertType(method, name, spec.type);
+        if (method === 'output' && spec.default !== undefined) {
+            throw new TypeError(`.output() declared ${JSON.stringify(name)} with a default, but the .flow format only persists `
+                + `defaults on inputs and vars. Bind the value with .return() instead.`);
+        }
+        return {
+            type: spec.type,
+            ...(spec.default !== undefined ? { default: spec.default } : {}),
+            ...(spec.description !== undefined ? { description: spec.description } : {}),
+            ...(spec.subType !== undefined ? { subType: spec.subType } : {}),
+            ...(spec.schema !== undefined ? { schema: spec.schema } : {}),
+        };
+    }
+    assertType(method, name, value);
+    return { type: value };
+}
+/** A declared variable's type must be one of the seven `types.*` names. */
+function assertType(method, name, type) {
+    if (typeof type === 'string' && TYPE_NAMES.includes(type))
+        return;
+    throw new TypeError(`.${method}() declared ${JSON.stringify(name)} with type ${JSON.stringify(type)}, which is not `
+        + `a type. Use one of ${TYPE_NAMES.map((t) => `types.${t}`).join(', ')}.`);
+}
+// ─── Triggers (what starts the flow) ────────────────────────────────────────
+//
+// Every flow starts at one trigger node. Omit `.trigger(...)` and you get the
+// manual trigger — started by a caller, on demand — which is what all the
+// examples do and stays the default.
+//
+// `scheduled(...)` is the other start trigger: the platform fires the flow on a
+// recurring interval, with no caller. Note what that means for a LOCAL run —
+// the interval is packaged into the flow's BPMN as a timer expression, and the
+// thing that reads it and fires is the platform's scheduler. Nothing in this
+// repo's ladder runs a timer, so locally a scheduled flow starts exactly like a
+// manual one; what we can verify here is that the emitted node is the right
+// node carrying the right interval.
+/**
+ * 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 const SCHEDULE_PRESETS = [
+    'R/PT5M', 'R/PT15M', 'R/PT30M', 'R/PT1H', 'R/PT6H', 'R/PT12H', 'R/P1D', 'R/P1W',
+];
+/**
+ * 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 function manual() {
+    return builtinTriggerSpec({ kind: 'manual' });
+}
+export function onEvent(a, opts) {
+    return builtinTriggerSpec({ kind: 'event', subscription: subscriptionFrom(a, opts) });
+}
+/**
+ * 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 function scheduled(inputs) {
+    return builtinTriggerSpec({ kind: 'scheduled', inputs });
+}
+/**
+ * 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 function formTrigger() {
+    return builtinTriggerSpec({ kind: 'form' });
+}
+/**
+ * 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 function conversationTrigger() {
+    return builtinTriggerSpec({ kind: 'conversation' });
+}
+/**
+ * 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 function voiceTrigger() {
+    return builtinTriggerSpec({ kind: 'voice' });
+}
+/**
+ * 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 const STICKY_NOTE_COLORS = ['yellow', 'pink', 'blue', 'green', 'white'];
+// ─── Builder ────────────────────────────────────────────────────────────────
+/** Collects a sequence of steps. Used for the flow body and each branch/loop arm. */
+class StepList {
+    steps = [];
+    /**
+     * 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.
+     */
+    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) {
+        if (!this.errorSource) {
+            throw new TypeError('err(field) with no step name is only available inside an error handler — the sub-builder '
+                + '.onError((h) => …) / .stepToList(\'error\', (h) => …) passes. Elsewhere, name the step: '
+                + "err('<step>', 'message').");
+        }
+        return errRef(this.errorSource, field);
+    }
+    /**
+     * 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, spec, options) {
+        // A custom FlowAction subclass carries no `kind` and is lowered through its
+        // own contribution; the built-in kind-switched paths never see it, so the
+        // stored Step keeps the structural spec type.
+        this.steps.push({ kind: 'action', name, spec: spec, ...(options ? { options } : {}) });
+        return 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) {
+        return this.addPortList('error', bodyFn, '.onError()', 'handler');
+    }
+    /**
+     * 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.
+     */
+    portSource(port, called) {
+        let i = this.steps.length - 1;
+        const attached = [];
+        while (i >= 0 && (this.steps[i].kind === 'stepToList' || this.steps[i].kind === 'stepToRef')) {
+            attached.push(this.steps[i]);
+            i--;
+        }
+        const source = this.steps[i];
+        // A `.loop()` CONTAINER is a legal source for the error port. Its definition
+        // declares the handle at both bundled versions (`core.logic.loop@1.0.0` and
+        // `@2.4`, gated on `errorHandlingEnabled` like every other error handle), and
+        // the platform routes it: a body step throwing inside a measured run left the
+        // instance Completed with the container's envelope published — `detail` the
+        // body's own message, `element` the id of the body step that failed.
+        //
+        // `.doWhile()` is NOT: `core.logic.dowhile@1.0` declares an error VARIABLE
+        // and no error HANDLE, so an edge would leave a handle the node does not
+        // have — the same shape as the agent `memory` handle that fails validate.
+        const containerPort = port === 'error' && source?.kind === 'loop';
+        if (!source || (source.kind !== 'action' && !containerPort)) {
+            throw new TypeError(`${called} leaves a port of the step BEFORE it, and ${source ? `the previous step is a ${source.kind}` : 'there is no previous step'}. `
+                + `Write .step('fetch', http({…}))${called}`
+                + (source?.kind === 'doWhile' && port === 'error'
+                    ? ' — a .doWhile() declares an error variable but no error HANDLE (core.logic.dowhile@1.0), so the edge '
+                        + 'would leave a handle the node does not have. Handle the failure inside the body instead.'
+                    : ' — a branch, parallel, terminate or return has no port to leave from; a .loop() has one only for '
+                        + "'error'."));
+        }
+        const taken = attached.some((s) => (s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === port);
+        if (taken) {
+            throw new TypeError(`${called} is already set on step "${source.name}"'s "${port}" port. A port takes exactly ONE outgoing edge `
+                + `(the definition says so: maxConnections: 1), so put everything that path needs in one place.`);
+        }
+        return source;
+    }
+    /**
+     * 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, bodyFn) {
+        return this.addPortList(port, bodyFn, '.stepToList()', 'body');
+    }
+    /**
+     * 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.
+     */
+    addPortList(port, bodyFn, called, noun) {
+        const prev = this.portSource(port, called);
+        const h = new StepList();
+        // The handler knows which step failed, so `h.err(field)` does not have to be
+        // told. Set for the error port only: on any other port list the preceding
+        // step SUCCEEDED, and there is no envelope to read.
+        if (port === 'error')
+            h.errorSource = prev.name;
+        bodyFn?.(h);
+        if (h.steps.length === 0) {
+            throw new TypeError(`${called} on step "${prev.name}" has an empty ${noun}. An edge to nothing is worse than none — `
+                + `the path still leaves the main flow. Return a value, terminate the run, or do the compensating work.`);
+        }
+        this.steps.push({ kind: 'stepToList', port, body: h.steps });
+        return this;
+    }
+    /**
+     * 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, cond, thenFn, elseFn, options) {
+        if (options?.updates) {
+            throw new TypeError('.branch(): { updates } is not supported here — the platform strips variable updates from '
+                + 'decision/switch/merge nodes on save. Attach them to a step before or after instead.');
+        }
+        const t = new ArmBuilder();
+        thenFn(t);
+        const e = new ArmBuilder();
+        if (elseFn)
+            elseFn(e);
+        // Normalize the condition the way `.switch` normalizes its discriminant: an
+        // authored `.flow.ts` runs with TYPES ERASED, so a bare value reaches here
+        // as itself rather than an Expr, and every later reader (check's reference
+        // scan, the serializer) then walks `undefined`. Wrapping it makes the
+        // mistake a named rung-1 diagnostic (BRANCH_CONST_COND) instead of
+        // `Cannot read properties of undefined (reading 'matchAll')`.
+        this.steps.push({
+            kind: 'branch',
+            name,
+            ...(t.armLabel !== undefined ? { trueLabel: t.armLabel } : {}),
+            ...(e.armLabel !== undefined ? { falseLabel: e.armLabel } : {}),
+            cond: toExpr(cond),
+            then: t.steps,
+            otherwise: e.steps,
+            ...(options ? { options } : {}),
+        });
+        return 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, on, cases, defaultFn, options) {
+        if (options?.updates) {
+            throw new TypeError('.switch(): { updates } is not supported here — the platform strips variable updates from '
+                + 'decision/switch/merge nodes on save. Attach them to a step before or after instead.');
+        }
+        const arms = (cases ?? []).map((c) => {
+            const arm = new ArmBuilder();
+            c.body?.(arm);
+            // An arm's own `.label(...)` wins over the case config's `label`; either
+            // overrides the serializer's derived `Case "<value>"`.
+            const label = arm.armLabel ?? c.label;
+            return { value: c.value, ...(label !== undefined ? { label } : {}), body: arm.steps };
+        });
+        let dflt;
+        if (defaultFn) {
+            const d = new StepList();
+            defaultFn(d);
+            dflt = d.steps;
+        }
+        // `on` is coerced rather than trusted: the authored `.flow.ts` runs with
+        // types stripped, so a plain string here (`.switch('q', 'quarter', …)`)
+        // would otherwise reach the serializer as `undefined === 2`. As a literal
+        // Expr it becomes a check-time diagnostic instead (SWITCH_CONST_ON).
+        this.steps.push({
+            kind: 'switch',
+            name,
+            on: toExpr(on),
+            cases: arms,
+            ...(dflt !== undefined ? { default: dflt } : {}),
+            ...(options ? { options } : {}),
+        });
+        return 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, arms, options) {
+        if (options?.updates) {
+            throw new TypeError('.parallel(): { updates } is not supported here — the platform strips variable updates from '
+                + 'decision/switch/merge nodes on save. Attach them to a step before or after instead.');
+        }
+        const built = (arms ?? []).map((armFn) => {
+            const a = new StepList();
+            armFn?.(a);
+            return a.steps;
+        });
+        this.steps.push({ kind: 'parallel', name, arms: built, ...(options ? { options } : {}) });
+        return 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, collection, bodyFn, options) {
+        const b = new StepList();
+        bodyFn(b);
+        this.steps.push({ kind: 'loop', name, collection: toExpr(collection), body: b.steps, ...(options ? { options } : {}) });
+        return 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, condition, bodyFn, options) {
+        const b = new StepList();
+        bodyFn(b);
+        this.steps.push({ kind: 'doWhile', name, condition: toExpr(condition), body: b.steps, ...(options ? { options } : {}) });
+        return 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.steps.push({ kind: 'break' });
+        return 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, label, options) {
+        this.steps.push({ kind: 'terminate', name, ...(label !== undefined ? { label } : {}), ...(options ? { options } : {}) });
+        return this;
+    }
+    stepToRef(portOrTarget, maybeTarget) {
+        const port = maybeTarget === undefined ? 'output' : portOrTarget;
+        const target = maybeTarget === undefined ? portOrTarget : maybeTarget;
+        if (typeof target !== 'string' || target.length === 0) {
+            throw new TypeError(`.stepToRef() takes the NAME of the step to continue at — .stepToRef('priceIt') — and got ${JSON.stringify(target)}. `
+                + `It is the same name you passed to .step(), so the edge can be wired after the whole flow is built.`);
+        }
+        // A non-default port leaves the PRECEDING step, so it is guarded the same way
+        // `.stepToList()` is; the default port continues the list and needs no source.
+        if (port !== 'output')
+            this.portSource(port, `.stepToRef('${port}', …)`);
+        this.steps.push({ kind: 'stepToRef', port, target });
+        return 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 = {}, options) {
+        const norm = {};
+        for (const [k, val] of Object.entries(values))
+            norm[k] = toExpr(val);
+        this.steps.push({ kind: 'return', name: 'return', values: norm, ...(options ? { options } : {}) });
+        return 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).
+ */
+class ArmBuilder extends StepList {
+    armLabel;
+    /**
+     * 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) {
+        this.armLabel = text;
+        return this;
+    }
+}
+class FlowBuilder extends StepList {
+    _id;
+    _name;
+    _description;
+    _layout;
+    _stickyNotes;
+    _version = '1.0.0';
+    _schemaVersion;
+    _inputs = [];
+    _outputs = [];
+    _vars = [];
+    _trigger;
+    _triggerOptions;
+    _entryPoints = [];
+    _triggerId;
+    constructor(_id) {
+        super();
+        this._id = _id;
+        this._name = _id;
+    }
+    /**
+     * 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) {
+        this._name = n;
+        return 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) {
+        this._description = text;
+        return 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) {
+        this._layout = layout;
+        return 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) {
+        this._stickyNotes = notes;
+        return 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, options) {
+        if (options?.updates) {
+            throw new TypeError('.trigger(): { updates } is not supported — a trigger has not run anything to assign from.');
+        }
+        this._trigger = spec;
+        if (options)
+            this._triggerOptions = options;
+        return 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, trigger, options, prefixFn) {
+        const inputs = [];
+        for (const [name, value] of Object.entries(options?.inputs ?? {})) {
+            inputs.push({ name, ...varDeclOf('input', name, value) });
+        }
+        const b = new StepList();
+        prefixFn?.(b);
+        this._entryPoints.push({
+            id,
+            trigger: trigger,
+            ...(options?.version !== undefined ? { options: { version: options.version } } : {}),
+            inputs,
+            steps: b.steps,
+        });
+        return 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) {
+        this._triggerId = id;
+        return 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) {
+        this._version = vsn;
+        return 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) {
+        const refusal = schemaVersionRefusal(FLOW_SCHEMA_VERSIONS, version);
+        if (refusal)
+            throw new Error(refusal);
+        this._schemaVersion = version;
+        return 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) {
+        for (const [name, value] of Object.entries(assertShape('input', shape))) {
+            this._inputs.push({ name, ...varDeclOf('input', name, value) });
+        }
+        return 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) {
+        for (const [name, value] of Object.entries(assertShape('output', shape))) {
+            this._outputs.push({ name, ...varDeclOf('output', name, value) });
+        }
+        return 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, type, defaultValue) {
+        const decl = varDeclOf('var', name, type);
+        if (defaultValue !== undefined)
+            decl.default = defaultValue;
+        this._vars.push({ name, ...decl });
+        return 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() {
+        const built = {
+            id: this._id,
+            name: this._name,
+            ...(this._description !== undefined ? { description: this._description } : {}),
+            ...(this._layout !== undefined ? { layout: this._layout } : {}),
+            ...(this._stickyNotes !== undefined ? { stickyNotes: this._stickyNotes } : {}),
+            version: this._version,
+            ...(this._schemaVersion !== undefined ? { schemaVersion: this._schemaVersion } : {}),
+            inputs: this._inputs,
+            outputs: this._outputs,
+            vars: this._vars,
+            steps: this.steps,
+            ...(this._trigger !== undefined ? { trigger: this._trigger } : {}),
+            ...(this._triggerOptions !== undefined ? { triggerOptions: this._triggerOptions } : {}),
+            ...(this._entryPoints.length ? { entryPoints: this._entryPoints } : {}),
+            ...(this._triggerId !== undefined ? { triggerId: this._triggerId } : {}),
+        };
+        // First-level validation, intrinsic to running the SDK: catch a definitely-
+        // broken expression HERE, before the model is serialized, rather than three
+        // steps later at `uip maestro flow validate`. Throws so nothing invalid is
+        // written; the deeper checks stay with the validate CLI. See flow-expr-check.
+        const errors = checkFlowExpressions(built).filter((d) => d.level === 'error');
+        if (errors.length)
+            throw new FlowBuildError(built, errors);
+        return built;
+    }
+}
+/**
+ * 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 function flow(id) {
+    return new FlowBuilder(id);
+}
+/**
+ * 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 function subflow(child, inputs = {}) {
+    // Accept the builder OR an already-built flow. Authors reach for the builder
+    // (the parent's `.build()` is the file's one terminal call), and a stray
+    // `.build()` on the child should not be an error worth a diagnostic.
+    const built = typeof child?.build === 'function'
+        ? child.build()
+        : child;
+    const norm = {};
+    for (const [k, val] of Object.entries(inputs ?? {}))
+        norm[k] = toExpr(val);
+    return builtinActionSpec({ kind: 'subflow', child: built, inputs: norm });
+}