@uipath/maestro-builder-sdk 5.2.0

package/dist/emit.d.ts

@@ -0,0 +1,10 @@
+import type { BuiltFlow } from './flow-sdk.js';
+import type { SerializeOpts } from './serialize.js';
+export interface EmitFlowOpts extends SerializeOpts {
+    /** Connector library dir; defaults to `$FLOW_SDK_LIBRARY_JSON`. */
+    libraryDir?: string;
+    /** bindings.json path; defaults to `./bindings.json` when it exists. */
+    bindingsFile?: string;
+}
+/** Serialize `built` and write it to `path`; returns the `.flow` JSON. */
+export declare function emitFlow(built: BuiltFlow, path: string, opts?: EmitFlowOpts): any;

package/dist/emit.js

@@ -0,0 +1,60 @@
+/**
+ * emit — write a built flow to a `.flow` file, from the authored script itself.
+ *
+ * `serialize()` is the library call that turns a `BuiltFlow` into the `.flow`
+ * JSON. Using it directly means also resolving the connector library and the
+ * bindings file, which is boilerplate every author would repeat identically:
+ *
+ * ```ts
+ * const built = flow('release-rollup')…build();
+ * writeFileSync('ReleaseRollup/ReleaseRollup.flow',
+ *   JSON.stringify(serialize(built, { library: new Library(process.env.FLOW_SDK_LIBRARY_JSON!),
+ *                                     bindings: new Bindings('bindings.json') }), null, 2));
+ * ```
+ *
+ * `emitFlow(built, path)` is that, with the two resolutions defaulted the same
+ * way `compile-cli` defaults them — library from `$FLOW_SDK_LIBRARY_JSON`,
+ * bindings from `./bindings.json` when it exists:
+ *
+ * ```ts
+ * export default emitFlow(flow('release-rollup')…build(), 'ReleaseRollup/ReleaseRollup.flow');
+ * ```
+ *
+ * It deliberately does NOT run `check()`. `compile-cli` does, and refuses to
+ * emit on errors; this is the plain library path, so the only errors it raises
+ * are the ones `.build()` and `serialize()` raise themselves. Callers who want
+ * the static pass should call `check()` — or use `compile-cli`.
+ */
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { serialize } from './serialize.js';
+import { Library } from './library.js';
+import { Bindings } from './bindings.js';
+import { resolveLibraryDir } from './registry/cache.js';
+/**
+ * Resolve the connector library the same way `compile-cli` does: only load it
+ * when it is actually there, so a flow with no connectors emits fine without a
+ * built library. A connector action with no library then fails inside
+ * `serialize()` with its own clear error.
+ */
+function defaultLibrary(dir) {
+    const libDir = resolveLibraryDir(dir);
+    if (!libDir || !existsSync(join(libDir, 'index.json')))
+        return undefined;
+    return new Library(libDir);
+}
+/** Serialize `built` and write it to `path`; returns the `.flow` JSON. */
+export function emitFlow(built, path, opts = {}) {
+    const bindFile = opts.bindingsFile ?? (existsSync('bindings.json') ? 'bindings.json' : undefined);
+    const flowJson = serialize(built, {
+        library: opts.library ?? defaultLibrary(opts.libraryDir),
+        bindings: opts.bindings ?? new Bindings(bindFile),
+        // Same channel `compile` uses; a host that wants them elsewhere passes `warn`.
+        warn: opts.warn ?? ((w) => console.error(`  ⚠ [${w.code}] ${w.message}`)),
+    });
+    const dir = dirname(path);
+    if (dir && dir !== '.' && !existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(flowJson, null, 2) + '\n');
+    return flowJson;
+}

package/dist/event-filters.d.ts

@@ -0,0 +1,130 @@
+/**
+ * event-filters — ONE connector-event filter condition, lowered the way the
+ * platform's own designer lowers it.
+ *
+ * The designer (`@uipath/maestro-sdk` `JmesHelper`, bundled in the product CLI
+ * and driving `uip maestro flow node configure`) stores a filter twice: as a
+ * structured tree in `configuration.essentialConfiguration.filter` (what the
+ * canvas shows) and as the JMESPath `filterExpression` the runtime subscribes
+ * with. Both encodings below were MEASURED against that code path on 2026-09-02
+ * (a Data Fabric `record-created` trigger, one operator at a time) and against
+ * the deployed corpus (199 archived trigger/event nodes):
+ *
+ * | authored           | designer operator | JMESPath                                  |
+ * |--------------------|-------------------|-------------------------------------------|
+ * | `contains: 'v'`    | `Contains`        | `contains(f,'v')`                         |
+ * | `startsWith: 'v'`  | `StartsWith`      | `starts_with(f,'v')`                      |
+ * | `endsWith: 'v'`    | `EndsWith`        | `ends_with(f,'v')`                        |
+ * | `equals: 'v'`      | `Equals`          | `f=='v'`                                  |
+ * | `notEquals: 'v'`   | `NotEquals`       | `f!='v'`                                  |
+ * | `lessThan: 3`      | `LessThan`        | `` f<`3` ``                               |
+ * | `lessThan: '2026-08-04'` (ISO date) | `LessThan` | `to_number(f)<to_number('2026-08-04')` |
+ * | … and `lessThanOrEqual` / `greaterThan` / `greaterThanOrEqual` likewise. |
+ *
+ * Literals follow the designer's `_formatLiteral`: a string is single-quoted, a
+ * number or boolean is a JMESPath backtick literal. A DATE is the one case the
+ * designer decides from the field's type (`DateTimeOffset` → `to_number(...)` on
+ * both sides, because JMESPath compares only numbers). Offline the SDK has no
+ * field types for a connection-scoped object, so the VALUE decides: an ISO-8601
+ * date/time string under a comparison operator takes the date form. A plain
+ * string under a comparison would compare nothing at runtime (JMESPath `<` on
+ * strings is null), so `check` refuses it rather than emit a filter that never
+ * matches.
+ */
+/** The designer's operator vocabulary this SDK emits, keyed by the authored key. */
+export declare const EVENT_FILTER_OPERATORS: {
+    readonly contains: {
+        readonly designer: "Contains";
+        readonly kind: "function";
+        readonly jmes: "contains";
+    };
+    readonly startsWith: {
+        readonly designer: "StartsWith";
+        readonly kind: "function";
+        readonly jmes: "starts_with";
+    };
+    readonly endsWith: {
+        readonly designer: "EndsWith";
+        readonly kind: "function";
+        readonly jmes: "ends_with";
+    };
+    readonly equals: {
+        readonly designer: "Equals";
+        readonly kind: "comparison";
+        readonly jmes: "==";
+    };
+    readonly notEquals: {
+        readonly designer: "NotEquals";
+        readonly kind: "comparison";
+        readonly jmes: "!=";
+    };
+    readonly lessThan: {
+        readonly designer: "LessThan";
+        readonly kind: "comparison";
+        readonly jmes: "<";
+    };
+    readonly lessThanOrEqual: {
+        readonly designer: "LessThanOrEqual";
+        readonly kind: "comparison";
+        readonly jmes: "<=";
+    };
+    readonly greaterThan: {
+        readonly designer: "GreaterThan";
+        readonly kind: "comparison";
+        readonly jmes: ">";
+    };
+    readonly greaterThanOrEqual: {
+        readonly designer: "GreaterThanOrEqual";
+        readonly kind: "comparison";
+        readonly jmes: ">=";
+    };
+};
+export type EventFilterOperatorKey = keyof typeof EVENT_FILTER_OPERATORS;
+/** One authored filter, read structurally: which operator, and its value. */
+export interface ReadEventFilter {
+    field: string;
+    operator: EventFilterOperatorKey;
+    value: string | number | boolean;
+}
+/**
+ * Read an authored filter leaf. Returns the operator keys it carries (0, 1 or
+ * many) so `check` can name the exact mistake, and the parsed condition when
+ * exactly one is present.
+ */
+export declare function readEventFilter(leaf: unknown): {
+    keys: EventFilterOperatorKey[];
+    read?: ReadEventFilter;
+};
+export declare function isIsoDateString(value: unknown): value is string;
+/**
+ * Why a filter cannot be lowered, or `undefined` when it can. A comparison on a
+ * plain string is the one refused shape: JMESPath `<`/`>` compare numbers only,
+ * so the emitted expression would match nothing and nobody would be told.
+ */
+export declare function eventFilterProblem(read: ReadEventFilter): string | undefined;
+/**
+ * The JMESPath condition for one filter — the grammar the designer emits,
+ * without the outer parentheses (the caller groups conditions).
+ */
+export declare function eventFilterJmes(read: ReadEventFilter): string;
+/** The designer's tree leaf for one filter — `uiId` is the caller's (it is what keeps a rebuild byte-identical). */
+export declare function eventFilterTreeLeaf(read: ReadEventFilter): {
+    id: string;
+    operator: string;
+    value: {
+        value: string | number | boolean;
+        rawString: string;
+        isLiteral: true;
+    };
+};
+/**
+ * Read a designer tree leaf back into the authored key + value (decompile).
+ * Returns `undefined` for an operator this SDK does not author (`In`, `IsEmpty`, …).
+ */
+export declare function eventFilterFromTreeLeaf(leaf: {
+    id?: unknown;
+    operator?: unknown;
+    value?: {
+        value?: unknown;
+    };
+}): ReadEventFilter | undefined;

package/dist/event-filters.js

@@ -0,0 +1,137 @@
+/**
+ * event-filters — ONE connector-event filter condition, lowered the way the
+ * platform's own designer lowers it.
+ *
+ * The designer (`@uipath/maestro-sdk` `JmesHelper`, bundled in the product CLI
+ * and driving `uip maestro flow node configure`) stores a filter twice: as a
+ * structured tree in `configuration.essentialConfiguration.filter` (what the
+ * canvas shows) and as the JMESPath `filterExpression` the runtime subscribes
+ * with. Both encodings below were MEASURED against that code path on 2026-09-02
+ * (a Data Fabric `record-created` trigger, one operator at a time) and against
+ * the deployed corpus (199 archived trigger/event nodes):
+ *
+ * | authored           | designer operator | JMESPath                                  |
+ * |--------------------|-------------------|-------------------------------------------|
+ * | `contains: 'v'`    | `Contains`        | `contains(f,'v')`                         |
+ * | `startsWith: 'v'`  | `StartsWith`      | `starts_with(f,'v')`                      |
+ * | `endsWith: 'v'`    | `EndsWith`        | `ends_with(f,'v')`                        |
+ * | `equals: 'v'`      | `Equals`          | `f=='v'`                                  |
+ * | `notEquals: 'v'`   | `NotEquals`       | `f!='v'`                                  |
+ * | `lessThan: 3`      | `LessThan`        | `` f<`3` ``                               |
+ * | `lessThan: '2026-08-04'` (ISO date) | `LessThan` | `to_number(f)<to_number('2026-08-04')` |
+ * | … and `lessThanOrEqual` / `greaterThan` / `greaterThanOrEqual` likewise. |
+ *
+ * Literals follow the designer's `_formatLiteral`: a string is single-quoted, a
+ * number or boolean is a JMESPath backtick literal. A DATE is the one case the
+ * designer decides from the field's type (`DateTimeOffset` → `to_number(...)` on
+ * both sides, because JMESPath compares only numbers). Offline the SDK has no
+ * field types for a connection-scoped object, so the VALUE decides: an ISO-8601
+ * date/time string under a comparison operator takes the date form. A plain
+ * string under a comparison would compare nothing at runtime (JMESPath `<` on
+ * strings is null), so `check` refuses it rather than emit a filter that never
+ * matches.
+ */
+/** The designer's operator vocabulary this SDK emits, keyed by the authored key. */
+export const EVENT_FILTER_OPERATORS = {
+    contains: { designer: 'Contains', kind: 'function', jmes: 'contains' },
+    startsWith: { designer: 'StartsWith', kind: 'function', jmes: 'starts_with' },
+    endsWith: { designer: 'EndsWith', kind: 'function', jmes: 'ends_with' },
+    equals: { designer: 'Equals', kind: 'comparison', jmes: '==' },
+    notEquals: { designer: 'NotEquals', kind: 'comparison', jmes: '!=' },
+    lessThan: { designer: 'LessThan', kind: 'comparison', jmes: '<' },
+    lessThanOrEqual: { designer: 'LessThanOrEqual', kind: 'comparison', jmes: '<=' },
+    greaterThan: { designer: 'GreaterThan', kind: 'comparison', jmes: '>' },
+    greaterThanOrEqual: { designer: 'GreaterThanOrEqual', kind: 'comparison', jmes: '>=' },
+};
+/** The designer operator names that come back as each authored key on decompile. */
+const DESIGNER_TO_KEY = {
+    Contains: 'contains',
+    StartsWith: 'startsWith',
+    EndsWith: 'endsWith',
+    Equals: 'equals',
+    DateTimeEquals: 'equals',
+    NotEquals: 'notEquals',
+    DateTimeNotEqual: 'notEquals',
+    LessThan: 'lessThan',
+    Before: 'lessThan',
+    LessThanOrEqual: 'lessThanOrEqual',
+    BeforeOrEqual: 'lessThanOrEqual',
+    GreaterThan: 'greaterThan',
+    After: 'greaterThan',
+    GreaterThanOrEqual: 'greaterThanOrEqual',
+    AfterOrEqual: 'greaterThanOrEqual',
+};
+/**
+ * Read an authored filter leaf. Returns the operator keys it carries (0, 1 or
+ * many) so `check` can name the exact mistake, and the parsed condition when
+ * exactly one is present.
+ */
+export function readEventFilter(leaf) {
+    const f = (leaf ?? {});
+    const keys = Object.keys(EVENT_FILTER_OPERATORS).filter((k) => f[k] !== undefined);
+    if (keys.length !== 1)
+        return { keys };
+    const value = f[keys[0]];
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+        return { keys };
+    return { keys, read: { field: String(f.field ?? ''), operator: keys[0], value } };
+}
+/** An ISO-8601 calendar date, optionally with a time part — what the designer serializes a date filter as. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+export function isIsoDateString(value) {
+    return typeof value === 'string' && ISO_DATE.test(value);
+}
+/**
+ * Why a filter cannot be lowered, or `undefined` when it can. A comparison on a
+ * plain string is the one refused shape: JMESPath `<`/`>` compare numbers only,
+ * so the emitted expression would match nothing and nobody would be told.
+ */
+export function eventFilterProblem(read) {
+    const op = EVENT_FILTER_OPERATORS[read.operator];
+    if (op.kind === 'function' && typeof read.value !== 'string') {
+        return `\`${read.operator}\` is a text test, so its value must be a string — got ${JSON.stringify(read.value)}.`;
+    }
+    const ordering = read.operator !== 'equals' && read.operator !== 'notEquals';
+    if (op.kind === 'comparison' && ordering && typeof read.value === 'string' && !isIsoDateString(read.value)) {
+        return `\`${read.operator}\` orders numbers or dates, and ${JSON.stringify(read.value)} is neither. JMESPath `
+            + `compares only numbers, so the runtime would match nothing. Pass a number (\`${read.operator}: 100\`) or an `
+            + `ISO date (\`${read.operator}: '2026-08-04'\`); for text use \`equals\`, \`contains\`, \`startsWith\` or \`endsWith\`.`;
+    }
+    return undefined;
+}
+/** The JMESPath literal for one filter value, per the designer's `_formatLiteral`. */
+function jmesLiteral(value) {
+    return typeof value === 'string' ? `'${value}'` : `\`${JSON.stringify(value)}\``;
+}
+/**
+ * The JMESPath condition for one filter — the grammar the designer emits,
+ * without the outer parentheses (the caller groups conditions).
+ */
+export function eventFilterJmes(read) {
+    const op = EVENT_FILTER_OPERATORS[read.operator];
+    if (op.kind === 'function')
+        return `${op.jmes}(${read.field},${jmesLiteral(read.value)})`;
+    if (isIsoDateString(read.value))
+        return `to_number(${read.field})${op.jmes}to_number('${read.value}')`;
+    return `${read.field}${op.jmes}${jmesLiteral(read.value)}`;
+}
+/** The designer's tree leaf for one filter — `uiId` is the caller's (it is what keeps a rebuild byte-identical). */
+export function eventFilterTreeLeaf(read) {
+    return {
+        id: read.field,
+        operator: EVENT_FILTER_OPERATORS[read.operator].designer,
+        value: { value: read.value, rawString: JSON.stringify(read.value), isLiteral: true },
+    };
+}
+/**
+ * Read a designer tree leaf back into the authored key + value (decompile).
+ * Returns `undefined` for an operator this SDK does not author (`In`, `IsEmpty`, …).
+ */
+export function eventFilterFromTreeLeaf(leaf) {
+    const key = DESIGNER_TO_KEY[String(leaf?.operator ?? '')];
+    if (!key || typeof leaf?.id !== 'string')
+        return undefined;
+    const raw = leaf.value?.value;
+    const value = typeof raw === 'number' || typeof raw === 'boolean' ? raw : String(raw ?? '');
+    return { field: leaf.id, operator: key, value };
+}

package/dist/flow-expr-check.d.ts

@@ -0,0 +1,17 @@
+import { type ExprDiagnostic } from './core/expr-check.js';
+import type { BuiltFlow } from './flow-sdk.js';
+/** A diagnostic plus the node / field it was found in. */
+export interface LocatedDiagnostic extends ExprDiagnostic {
+    where: string;
+}
+/** Every first-level expression problem in a built flow, each stamped with its location. */
+export declare function checkFlowExpressions(built: BuiltFlow): LocatedDiagnostic[];
+/**
+ * Thrown by `build()` when the first-level expression check finds errors. Its
+ * `message` lists every problem (so a runner that prints `err.message` shows them
+ * all at once); `diagnostics` carries them structured for a caller that wants them.
+ */
+export declare class FlowBuildError extends Error {
+    readonly diagnostics: LocatedDiagnostic[];
+    constructor(built: BuiltFlow, diagnostics: LocatedDiagnostic[]);
+}

package/dist/flow-expr-check.js

@@ -0,0 +1,193 @@
+/**
+ * flow-expr-check — the FLOW adapter over the shared, format-agnostic
+ * `core/expr-check`. It is what `FlowBuilder.build()` runs, unconditionally,
+ * before it hands back the model to be serialized: a cheap first-level check that
+ * every `$vars.*` reference in an expression resolves to something the runtime
+ * will provide.
+ *
+ * WHY IN build(), AND WHY IT THROWS. The full validation is `uip maestro flow
+ * validate`, run after the `.flow` is written — richer, but a slower loop. This
+ * catches the definite mistakes at the moment the SDK code runs, so a typo'd
+ * reference fails HERE, with the node and a suggestion, instead of surviving into
+ * a serialized `.flow` and surfacing three steps later. Because `build()`'s return
+ * value IS what gets serialized, throwing is the only way to reliably stop a
+ * broken model from being written — and since a `.flow.ts` file's default export
+ * is `flow(…).build()`, the throw becomes a failed import that any runner (the
+ * compile CLI's `.catch`, or a bare `node`) surfaces as a message + non-zero exit
+ * with no file emitted.
+ *
+ * WHY IT ONLY CHECKS REFERENCE ROOTS. The rule is conservative on purpose: it
+ * flags only what it can be CERTAIN is wrong — a root that names no declared
+ * input, variable, or step. Field-shape and type checks (does step X really
+ * output `.foo`, is the comparison type-sound) are heavier and easier to get
+ * wrong offline, so they stay with the `validate` CLI. A first-level check that
+ * cried wolf would be worse than none.
+ *
+ * SCRIPT BODIES ARE NOT CHECKED YET — only expressions (`Expr` values). A script
+ * body is a plain string carrying its own `$vars.*` references; checking those is
+ * the same mechanism and a natural next step, deliberately out of this first cut.
+ */
+import { Expr } from './core/expr.js';
+import { checkExpression } from './core/expr-check.js';
+const NOUN = 'input, variable, or step';
+/**
+ * Every `$vars` root a reference may legitimately resolve to, across the WHOLE
+ * flow: declared inputs, outputs and variables, an event trigger's `start`, and
+ * every step name (the runtime's variable bag is flat, so a step's output is
+ * readable by name from anywhere it has run). Collecting names globally rather
+ * than per-scope is deliberate — it keeps the check from ever flagging a
+ * legitimate cross-scope read, which is the conservative direction.
+ *
+ * Mirrors `check.ts`'s own `declared` set so the two never disagree about what a
+ * valid root is.
+ */
+function globalRoots(built) {
+    const roots = new Set([
+        ...built.inputs.map((x) => x.name),
+        ...built.outputs.map((x) => x.name),
+        ...built.vars.map((x) => x.name),
+    ]);
+    // The trigger node is always addressable as `start`, and its output carries the
+    // flow's own inputs (`$vars.start.output.<input>`) for every trigger kind — an
+    // event trigger also publishes the event payload there. So `start` is a valid
+    // root whenever a flow reads its trigger; the conservative choice is to allow it
+    // unconditionally and leave "is this field really on the trigger" to `validate`.
+    // Both spellings are valid at CHECK time: `input('x')` always lowers to
+    // `$vars.start.output.x`, and serialize rewrites `start` to a renamed
+    // trigger id afterwards — so the check runs while both are in play.
+    roots.add('start');
+    if (built.triggerId)
+        roots.add(built.triggerId);
+    for (const ep of built.entryPoints ?? []) {
+        roots.add(ep.id);
+        addStepNames(ep.steps, roots);
+    }
+    addStepNames(built.steps, roots);
+    return roots;
+}
+function addStepNames(steps, roots) {
+    for (const s of steps) {
+        // `return` carries a synthetic name; the port-edge kinds carry none at all —
+        // they are edges, not nodes, so there is nothing to reference them by.
+        if (s.kind !== 'return' && s.kind !== 'stepToRef' && s.kind !== 'stepToList' && s.kind !== 'break')
+            roots.add(s.name);
+        switch (s.kind) {
+            case 'stepToList':
+                addStepNames(s.body, roots);
+                break;
+            case 'branch':
+                addStepNames(s.then, roots);
+                addStepNames(s.otherwise, roots);
+                break;
+            case 'switch':
+                for (const c of s.cases)
+                    addStepNames(c.body, roots);
+                if (s.default)
+                    addStepNames(s.default, roots);
+                break;
+            case 'loop':
+                addStepNames(s.body, roots);
+                break;
+            case 'doWhile':
+                addStepNames(s.body, roots);
+                break;
+            case 'parallel':
+                for (const a of s.arms)
+                    addStepNames(a, roots);
+                break;
+        }
+    }
+}
+function pushExpr(js, literal, where, roots, out) {
+    if (literal)
+        return; // a literal carries no reference to resolve
+    for (const d of checkExpression(js, { roots, noun: NOUN, syntax: 'javascript' }))
+        out.push({ ...d, where });
+}
+/** Reach `Expr`s nested anywhere in an action's inputs (connector/http/… inputs can be structured). */
+function deepExprs(val, where, roots, out) {
+    if (val instanceof Expr)
+        return pushExpr(val.js, val.literal, where, roots, out);
+    if (Array.isArray(val)) {
+        for (const v of val)
+            deepExprs(v, where, roots, out);
+        return;
+    }
+    if (val && typeof val === 'object') {
+        for (const v of Object.values(val))
+            deepExprs(v, where, roots, out);
+    }
+}
+function walk(steps, roots, out) {
+    for (const s of steps) {
+        switch (s.kind) {
+            case 'action':
+                // Only `spec.inputs` — NOT a subflow's `spec.child`, whose body is a
+                // separate scope already checked by the child's own `build()`.
+                deepExprs(s.spec.inputs, s.name, roots, out);
+                break;
+            case 'stepToList':
+                walk(s.body, roots, out);
+                break;
+            case 'branch':
+                pushExpr(s.cond.js, s.cond.literal, s.name, roots, out);
+                walk(s.then, roots, out);
+                walk(s.otherwise, roots, out);
+                break;
+            case 'switch': {
+                pushExpr(s.on.js, s.on.literal, s.name, roots, out);
+                // Inside a case (or default) body the discriminant is bound to
+                // `$vars.value`, so it is a valid root only there.
+                const caseRoots = new Set(roots).add('value');
+                for (const c of s.cases)
+                    walk(c.body, caseRoots, out);
+                if (s.default)
+                    walk(s.default, caseRoots, out);
+                break;
+            }
+            case 'loop':
+                pushExpr(s.collection.js, s.collection.literal, s.name, roots, out);
+                if (s.options?.completionCondition) {
+                    pushExpr(s.options.completionCondition.js, s.options.completionCondition.literal, s.name, roots, out);
+                }
+                walk(s.body, roots, out);
+                break;
+            case 'doWhile':
+                pushExpr(s.condition.js, s.condition.literal, s.name, roots, out);
+                walk(s.body, roots, out);
+                break;
+            case 'parallel':
+                for (const a of s.arms)
+                    walk(a, roots, out);
+                break;
+            case 'return':
+                for (const [k, v] of Object.entries(s.values))
+                    pushExpr(v.js, v.literal, `return "${k}"`, roots, out);
+                break;
+        }
+    }
+}
+/** Every first-level expression problem in a built flow, each stamped with its location. */
+export function checkFlowExpressions(built) {
+    const out = [];
+    const roots = globalRoots(built);
+    walk(built.steps, roots, out);
+    for (const ep of built.entryPoints ?? [])
+        walk(ep.steps, roots, out);
+    return out;
+}
+/**
+ * Thrown by `build()` when the first-level expression check finds errors. Its
+ * `message` lists every problem (so a runner that prints `err.message` shows them
+ * all at once); `diagnostics` carries them structured for a caller that wants them.
+ */
+export class FlowBuildError extends Error {
+    diagnostics;
+    constructor(built, diagnostics) {
+        const label = built.name || built.id || 'flow';
+        const lines = diagnostics.map((d) => `  ✗ [${d.code}] in ${d.where}: ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
+        super(`Cannot build flow "${label}" — ${diagnostics.length} expression problem(s):\n${lines.join('\n')}`);
+        this.name = 'FlowBuildError';
+        this.diagnostics = diagnostics;
+    }
+}