@uipath/maestro-builder-sdk 6.57.0 → 6.58.1

package/dist/edit-scope.d.ts

@@ -0,0 +1,180 @@
+/**
+ * edit-scope — which parts of a Flow the author edited, and where a finding
+ * sits relative to that edit.
+ *
+ * A node or subflow of the edited flow that differs from its `baseline`
+ * counterpart (compile(decompile(original)), the no-edit round trip) is one
+ * the author changed; one that equals it is untouched. `mergeFlow` takes the
+ * changed ones from the edited flow and restores the untouched ones from the
+ * original; `flow merge --baseline-from` (merge-cli.ts) sorts each draft
+ * refusal and `check()` finding by the same rule, so a finding on an untouched
+ * node is a warning and one on an edited node is an error.
+ *
+ * For instance, a canvas Slack node with no connection yet that the author did
+ * not touch is `kept`; the same node with a new message text is `refused`.
+ *
+ * Pure: no file access, so a portable entry (`check.ts`, `merge.ts`) can use
+ * it. Reading the original and compiling its baseline is merge-compile.ts's.
+ */
+import type { Diagnostic } from './check.js';
+export interface AnyNode {
+    id: string;
+    type: string;
+    typeVersion?: string;
+    parentId?: string;
+    ui?: unknown;
+    display?: unknown;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+export interface AnyEdge {
+    id?: string;
+    sourceNodeId: string;
+    sourcePort: string;
+    targetNodeId: string;
+    targetPort: string;
+    [k: string]: unknown;
+}
+export interface AnyFlow {
+    id?: string;
+    name?: string;
+    version?: string;
+    nodes?: AnyNode[];
+    edges?: AnyEdge[];
+    definitions?: Array<{
+        nodeType?: string;
+        [k: string]: unknown;
+    }>;
+    variables?: unknown;
+    subflows?: Record<string, unknown>;
+    bindings?: Array<{
+        id?: string;
+        [k: string]: unknown;
+    }>;
+    metadata?: unknown;
+    solutionId?: unknown;
+    projectId?: unknown;
+    layout?: unknown;
+    runtime?: unknown;
+    [k: string]: unknown;
+}
+export declare function byId(nodes: AnyNode[] | undefined): Map<string, AnyNode>;
+/**
+ * Whether two nodes are the SAME as far as the author is concerned — same type,
+ * same inputs and same output mappings. Layout (`ui`), `display`, `typeVersion`,
+ * and the derived parts of `outputs` (type, schema, description) are ignored,
+ * because those are exactly the parts decompile does not carry through. An
+ * output's `source` is authored, not derived: it is what an End returns, so an
+ * edit to `.return({ ... })` changes nothing else on the node. Used only to
+ * decide "did the user edit this node?" against the baseline.
+ */
+export declare function nodeUnchanged(a: AnyNode | undefined, b: AnyNode | undefined): boolean;
+/**
+ * The keys of the subflows `mergeFlow` (merge.ts) takes from `edited` rather than
+ * restoring from `original`: every subflow that is new, that the original does
+ * not have, or that differs from its `baseline` counterpart in any way the
+ * author can edit — a node's inputs, output sources or label, an edge, the
+ * scope's `variables` or `layout` (`subflowUnchanged`, #1322). With no
+ * baseline, that is every subflow. A kept subflow is the original's whole: its
+ * nodes, edges, variables and layout.
+ */
+export declare function subflowsTakenFromEdited(original: AnyFlow, edited: AnyFlow, baseline?: AnyFlow): string[];
+export type SubflowScope = {
+    nodes?: AnyNode[];
+    edges?: AnyEdge[];
+    variables?: unknown;
+    layout?: unknown;
+};
+/**
+ * Whether merge restores `e`'s ORIGINAL node instead of taking `e`: there is a
+ * baseline, the original has the node, and `e` equals its baseline counterpart.
+ * merge.ts's `mergeFlow` node loop and {@link nodesTakenFromEdited} both ask this.
+ */
+export declare function isKept(e: AnyNode, origNodes: Map<string, AnyNode>, baseNodes: Map<string, AnyNode>, baseline: AnyFlow | undefined): boolean;
+/**
+ * Why a finding is an error: `edited`, its node is one the author changed or
+ * added; `subflow`, it sits in a subflow the edit changed, which merge takes
+ * whole; `unplaced`, it names no node and the original's own round trip does
+ * not report it, so the edit introduced it.
+ */
+export type TakenReason = 'edited' | 'subflow' | 'unplaced';
+/**
+ * A finding on a node merge takes from the edited flow, with the reason it
+ * takes it: `edited`, the author changed or added the node; `subflow`, the
+ * node sits in a subflow the edit changed, which merge takes whole (`subflow`
+ * names it).
+ */
+export type Refused<T> = T & {
+    reason: TakenReason;
+    subflow?: string;
+};
+/** A finding on a node merge restores from the original; `subflow` names the untouched subflow it sits in. */
+type Kept<T> = T & {
+    subflow?: string;
+};
+/**
+ * Sort each finding by what merge does with its node: `refused` when the node
+ * comes from the edited flow (reason `edited`: the author changed or added it;
+ * reason `subflow`: it sits in a subflow the edit changed, which merge takes
+ * whole), `kept` when merge restores the original node — a root node the edit
+ * did not touch, or any node of a subflow the edit did not touch (#1322) — and
+ * `unplaced` when the finding names no node merge knows (an unnamed End's
+ * `.return`, a flow-level finding). The caller sorts those again with
+ * {@link splitUnplaced}: one the original's own round trip reports too is
+ * printed, one the edit introduced is refused.
+ *
+ * For instance a Slack node with no connection that the author did not touch
+ * is `kept`; the same node with a new message text is `refused` as `edited`.
+ */
+export declare function classifyDrafts<T extends {
+    nodeId: string;
+    subflow?: string;
+}>(original: any, edited: any, baseline: any, findings: readonly T[]): {
+    kept: Kept<T>[];
+    refused: Refused<T>[];
+    unplaced: T[];
+};
+/**
+ * A `check()` diagnostic, placed on the node its step emitted (`''` when it
+ * names no node); `subflow` is the calling step when the finding is inside a
+ * subflow, which then decides how it is classified.
+ */
+export type PlacedDiagnostic = Diagnostic & {
+    nodeId: string;
+    subflow?: string;
+};
+/**
+ * Place each `check()` diagnostic on the node its step emitted in `editedFlow`, so
+ * {@link classifyDrafts} can sort it: a root step on its node (by label, then
+ * id); a step inside a subflow (`check` reports it as `<caller> › <step>`, one
+ * segment per level) on the deepest step the path resolves to, with `subflow`
+ * set to the deepest subflow on that path, which is what decides; a named End
+ * on its End node (#1322). A diagnostic with no step, or one no node answers
+ * to, gets nodeId `''`.
+ */
+export declare function placeDiagnostics(diagnostics: readonly Diagnostic[], editedFlow: any): PlacedDiagnostic[];
+/** How many times each {@link findingKey} occurs, for {@link splitUnplaced}'s baseline. */
+export declare function findingCounts(findings: ReadonlyArray<{
+    code: string;
+    message: string;
+}>): Map<string, number>;
+/**
+ * Sort findings merge could not place on a node by whether the edit introduced
+ * them: `known` when the ORIGINAL's own round trip (`baseline`, the decompiled
+ * original compiled and checked, as {@link findingCounts}) reports the same
+ * code and message — once per occurrence, so a second copy of a finding the
+ * original has once is `introduced` — so the finding predates the edit and
+ * only prints; `introduced` otherwise, which is refused like any error on an
+ * edited node (#1322). With no baseline findings to compare against (a
+ * precompiled `--baseline` file), every one is `introduced`, as merge treated
+ * them before.
+ */
+export declare function splitUnplaced<T extends {
+    code: string;
+    message: string;
+}>(unplaced: readonly T[], baseline: ReadonlyMap<string, number> | undefined): {
+    known: T[];
+    introduced: T[];
+};
+export {};

package/dist/edit-scope.js

@@ -0,0 +1,251 @@
+export function byId(nodes) {
+    return new Map((nodes ?? []).map((n) => [n.id, n]));
+}
+/**
+ * Whether two nodes are the SAME as far as the author is concerned — same type,
+ * same inputs and same output mappings. Layout (`ui`), `display`, `typeVersion`,
+ * and the derived parts of `outputs` (type, schema, description) are ignored,
+ * because those are exactly the parts decompile does not carry through. An
+ * output's `source` is authored, not derived: it is what an End returns, so an
+ * edit to `.return({ ... })` changes nothing else on the node. Used only to
+ * decide "did the user edit this node?" against the baseline.
+ */
+export function nodeUnchanged(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.type !== b.type)
+        return false;
+    return JSON.stringify(a.inputs ?? {}) === JSON.stringify(b.inputs ?? {})
+        && JSON.stringify(outputSources(a)) === JSON.stringify(outputSources(b));
+}
+/** Each output's `source` by output name; outputs without one are left out. */
+function outputSources(n) {
+    const sources = {};
+    for (const [name, output] of Object.entries(n.outputs ?? {})) {
+        if (output && typeof output === 'object' && 'source' in output)
+            sources[name] = output.source;
+    }
+    return sources;
+}
+/**
+ * The ids of the root nodes `mergeFlow` (merge.ts) takes from `edited` rather than
+ * restoring from `original`: every node that is new, or that differs from its
+ * `baseline` counterpart. With no baseline, that is every node.
+ *
+ * For instance, with a baseline equal to `edited` and every node present in
+ * `original`, the answer is `[]` — a no-edit merge keeps them all.
+ */
+function nodesTakenFromEdited(original, edited, baseline) {
+    const origNodes = byId(original.nodes);
+    const baseNodes = byId(baseline?.nodes);
+    return (edited.nodes ?? []).filter((e) => !isKept(e, origNodes, baseNodes, baseline)).map((e) => e.id);
+}
+/**
+ * The keys of the subflows `mergeFlow` (merge.ts) takes from `edited` rather than
+ * restoring from `original`: every subflow that is new, that the original does
+ * not have, or that differs from its `baseline` counterpart in any way the
+ * author can edit — a node's inputs, output sources or label, an edge, the
+ * scope's `variables` or `layout` (`subflowUnchanged`, #1322). With no
+ * baseline, that is every subflow. A kept subflow is the original's whole: its
+ * nodes, edges, variables and layout.
+ */
+export function subflowsTakenFromEdited(original, edited, baseline) {
+    return Object.keys(edited.subflows ?? {}).filter((key) => {
+        const orig = original.subflows?.[key];
+        const base = baseline?.subflows?.[key];
+        return !baseline || orig === undefined || base === undefined
+            || !subflowUnchanged(edited.subflows[key], base);
+    });
+}
+/** A node's canvas label, when it has one. */
+const labelOf = (n) => n?.display?.label;
+/**
+ * Whether an edited subflow equals its baseline: the same node ids, each node
+ * unchanged (`nodeUnchanged`) and under the same label, the same edges by
+ * their endpoints and handles (ids are compile's own), and the same
+ * `variables` and `layout` byte for byte. The scope's variables carry what the
+ * nodes do not — a step's `{ updates }` row, a child `.input()` type, a `.var()`
+ * default — and a kept subflow is the original's whole, so any of them changing
+ * has to make the subflow a taken one.
+ */
+function subflowUnchanged(e, b) {
+    const eNodes = byId(e.nodes);
+    const bNodes = byId(b.nodes);
+    if (eNodes.size !== bNodes.size)
+        return false;
+    for (const [id, n] of eNodes) {
+        const base = bNodes.get(id);
+        if (!nodeUnchanged(n, base) || labelOf(n) !== labelOf(base))
+            return false;
+    }
+    if (JSON.stringify(e.variables ?? null) !== JSON.stringify(b.variables ?? null))
+        return false;
+    // `layout.edges` is keyed by edge id, and ids come from one file-wide
+    // counter: a step added before the call shifts every id in the subflow
+    // without touching it. So routes are compared by the endpoints the id names
+    // (as the edges themselves are), and `layout.nodes` as it is.
+    if (JSON.stringify(layoutByEndpoints(e)) !== JSON.stringify(layoutByEndpoints(b)))
+        return false;
+    const eEdges = (e.edges ?? []).map(edgeKey).sort();
+    const bEdges = (b.edges ?? []).map(edgeKey).sort();
+    return eEdges.length === bEdges.length && eEdges.every((k, i) => k === bEdges[i]);
+}
+/** `<source>@<port>-><target>@<port>`: an edge's identity apart from its id. */
+const edgeKey = (x) => `${x.sourceNodeId}@${x.sourcePort}->${x.targetNodeId}@${x.targetPort}`;
+/** A scope's layout with its `edges` re-keyed by endpoints, so an id shift does not read as a change. */
+function layoutByEndpoints(sf) {
+    const layout = sf.layout;
+    if (!layout || typeof layout !== 'object')
+        return layout ?? null;
+    const byId = new Map((sf.edges ?? []).map((x) => [x.id, edgeKey(x)]));
+    const { edges, ...rest } = layout;
+    const routes = Object.entries(edges ?? {}).map(([id, route]) => [byId.get(id) ?? id, route]).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return { ...rest, edges: Object.fromEntries(routes) };
+}
+/**
+ * Whether merge restores `e`'s ORIGINAL node instead of taking `e`: there is a
+ * baseline, the original has the node, and `e` equals its baseline counterpart.
+ * merge.ts's `mergeFlow` node loop and {@link nodesTakenFromEdited} both ask this.
+ */
+export function isKept(e, origNodes, baseNodes, baseline) {
+    return !!baseline && origNodes.has(e.id) && nodeUnchanged(e, baseNodes.get(e.id));
+}
+/**
+ * Sort each finding by what merge does with its node: `refused` when the node
+ * comes from the edited flow (reason `edited`: the author changed or added it;
+ * reason `subflow`: it sits in a subflow the edit changed, which merge takes
+ * whole), `kept` when merge restores the original node — a root node the edit
+ * did not touch, or any node of a subflow the edit did not touch (#1322) — and
+ * `unplaced` when the finding names no node merge knows (an unnamed End's
+ * `.return`, a flow-level finding). The caller sorts those again with
+ * {@link splitUnplaced}: one the original's own round trip reports too is
+ * printed, one the edit introduced is refused.
+ *
+ * For instance a Slack node with no connection that the author did not touch
+ * is `kept`; the same node with a new message text is `refused` as `edited`.
+ */
+export function classifyDrafts(original, edited, baseline, findings) {
+    const fromEdited = new Set(nodesTakenFromEdited(original, edited, baseline));
+    const takenSubflows = new Set(subflowsTakenFromEdited(original, edited, baseline));
+    const rootIds = new Set((edited?.nodes ?? []).map((n) => n.id));
+    /** A subflow's own node ids → the key (the calling step) of the subflow holding them. */
+    const subflowOfNode = new Map();
+    for (const [key, sf] of Object.entries(edited?.subflows ?? {})) {
+        for (const n of sf?.nodes ?? [])
+            subflowOfNode.set(n.id, key);
+    }
+    const kept = [];
+    const refused = [];
+    const unplaced = [];
+    for (const f of findings) {
+        // A finding inside a subflow — placed on the calling step by `checkEdited`
+        // (`subflow` set), or a draft on one of the subflow's own nodes — is judged
+        // by the SUBFLOW: taken whole when the edit changed it, else the original's.
+        const subflow = f.subflow ?? subflowOfNode.get(f.nodeId);
+        if (subflow !== undefined) {
+            if (takenSubflows.has(subflow))
+                refused.push({ ...f, reason: 'subflow', subflow });
+            else
+                kept.push({ ...f, subflow });
+        }
+        else if (rootIds.has(f.nodeId)) {
+            if (fromEdited.has(f.nodeId))
+                refused.push({ ...f, reason: 'edited' });
+            else
+                kept.push(f);
+        }
+        else {
+            unplaced.push(f);
+        }
+    }
+    return { kept, refused, unplaced };
+}
+/**
+ * Place each `check()` diagnostic on the node its step emitted in `editedFlow`, so
+ * {@link classifyDrafts} can sort it: a root step on its node (by label, then
+ * id); a step inside a subflow (`check` reports it as `<caller> › <step>`, one
+ * segment per level) on the deepest step the path resolves to, with `subflow`
+ * set to the deepest subflow on that path, which is what decides; a named End
+ * on its End node (#1322). A diagnostic with no step, or one no node answers
+ * to, gets nodeId `''`.
+ */
+export function placeDiagnostics(diagnostics, editedFlow) {
+    const byStep = new Map();
+    for (const n of editedFlow?.nodes ?? []) {
+        const label = n?.display?.label;
+        if (typeof label === 'string' && !byStep.has(label))
+            byStep.set(label, n.id);
+    }
+    const ids = new Set((editedFlow?.nodes ?? []).map((n) => n.id));
+    /** `name` as a node id in `nodes`: by label, then by id; `''` when neither answers. */
+    const resolveIn = (nodes, name) => {
+        const byLabel = nodes.find((n) => n?.display?.label === name);
+        if (byLabel)
+            return byLabel.id;
+        return nodes.some((n) => n?.id === name) ? name : '';
+    };
+    // `subflows` is flat, keyed by each caller's id at every depth, and check
+    // prefixes a finding at every level (`outer › inner › x`): the subflow that
+    // decides is the DEEPEST one on the path, since merge keeps or takes each
+    // subflow on its own (an edit inside `inner` leaves `outer` kept).
+    const place = (step) => {
+        if (step === undefined)
+            return { nodeId: '' };
+        const segments = step.split(SUBFLOW_STEP_SEPARATOR);
+        let scope = editedFlow?.nodes ?? [];
+        let subflow;
+        let nodeId = '';
+        for (const [i, segment] of segments.entries()) {
+            const id = i === 0 ? (byStep.get(segment) ?? (ids.has(segment) ? segment : '')) : resolveIn(scope, segment);
+            if (id === '')
+                break;
+            nodeId = id;
+            const child = i < segments.length - 1 ? editedFlow?.subflows?.[id] : undefined;
+            if (child === undefined)
+                break;
+            subflow = id;
+            scope = child.nodes ?? [];
+        }
+        return subflow !== undefined ? { nodeId: nodeId === '' ? subflow : nodeId, subflow } : { nodeId };
+    };
+    return diagnostics.map((d) => ({ ...d, ...place(d.step) }));
+}
+/** The identity of a finding for the introduced-or-not comparison: its code and message. */
+function findingKey(f) {
+    return `${f.code}\n${f.message}`;
+}
+/** How many times each {@link findingKey} occurs, for {@link splitUnplaced}'s baseline. */
+export function findingCounts(findings) {
+    const counts = new Map();
+    for (const f of findings)
+        counts.set(findingKey(f), (counts.get(findingKey(f)) ?? 0) + 1);
+    return counts;
+}
+/**
+ * Sort findings merge could not place on a node by whether the edit introduced
+ * them: `known` when the ORIGINAL's own round trip (`baseline`, the decompiled
+ * original compiled and checked, as {@link findingCounts}) reports the same
+ * code and message — once per occurrence, so a second copy of a finding the
+ * original has once is `introduced` — so the finding predates the edit and
+ * only prints; `introduced` otherwise, which is refused like any error on an
+ * edited node (#1322). With no baseline findings to compare against (a
+ * precompiled `--baseline` file), every one is `introduced`, as merge treated
+ * them before.
+ */
+export function splitUnplaced(unplaced, baseline) {
+    const known = [];
+    const introduced = [];
+    const left = new Map(baseline ?? []);
+    for (const f of unplaced) {
+        const n = left.get(findingKey(f)) ?? 0;
+        if (n > 0) {
+            left.set(findingKey(f), n - 1);
+            known.push(f);
+        }
+        else
+            introduced.push(f);
+    }
+    return { known, introduced };
+}
+/** How `check` joins a subflow's calling step and the step inside it in a diagnostic's `step`. */
+const SUBFLOW_STEP_SEPARATOR = ' › ';

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

@@ -1,5 +1,6 @@
 import { type ExprDiagnostic } from './core/expr-check.js';
 import type { BuiltFlow } from './flow-sdk.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 /** A diagnostic plus the node / field it was found in. */
 export interface LocatedDiagnostic extends ExprDiagnostic {
     where: string;
@@ -28,7 +29,7 @@ export declare function checkCookedEscapes(built: BuiltFlow): (LocatedDiagnostic
  * `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 {
+export declare class FlowBuildError extends CompileRefusal {
     readonly diagnostics: LocatedDiagnostic[];
     constructor(built: BuiltFlow, diagnostics: LocatedDiagnostic[]);
 }

package/dist/flow-expr-check.js

@@ -30,6 +30,7 @@
 import { Expr, cookedEscapesOf } from './core/expr.js';
 import { checkExpression, cookedEscapeDiagnostics } from './core/expr-check.js';
 import { stepDeclaredVariables } from './flow-step-variables.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 const NOUN = 'input, variable, or step';
 /**
  * Every `$vars` root a reference may legitimately resolve to, across the WHOLE
@@ -269,12 +270,13 @@ export function checkCookedEscapes(built) {
  * `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 {
+export class FlowBuildError extends CompileRefusal {
     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')}`);
+        // The first problem's code; `diagnostics` carries every one.
+        super(diagnostics[0]?.code ?? 'EXPR_SYNTAX', `Cannot build flow "${label}" — ${diagnostics.length} expression problem(s):\n${lines.join('\n')}`);
         this.name = 'FlowBuildError';
         this.diagnostics = diagnostics;
     }

package/dist/flow-sdk.js

@@ -48,6 +48,7 @@ import { checkFlowExpressions, FlowBuildError } from './flow-expr-check.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { schemaVersionRefusal } from './schema-version.js';
 import { indexCarriedDefinitions } from './core/carried-definitions.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 export { FlowBuildError, checkFlowExpressions } from './flow-expr-check.js';
 const TYPE_NAMES = Object.values(types);
 /**
@@ -69,7 +70,7 @@ const TYPE_NAMES = Object.values(types);
  */
 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}`
+        throw new CompileRefusal('DECLARATION_SHAPE', `.${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 `
@@ -89,12 +90,12 @@ function varDeclOf(method, name, value) {
         assertType(method, name, spec.type);
         if (spec.shared !== undefined) {
             if (method !== 'input') {
-                throw new TypeError(`.${method}() declared ${JSON.stringify(name)} with { shared }, which only an input takes: it names `
+                throw new CompileRefusal('SHARED_INPUT_NOT_INPUT', `.${method}() declared ${JSON.stringify(name)} with { shared }, which only an input takes: it names `
                     + `the flow variable a root's input is copied into. Declare the variable with .var() and feed it from `
                     + `.input({ <name>: { type, shared: ${JSON.stringify(spec.shared)} } }).`);
             }
             if (typeof spec.shared !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(spec.shared)) {
-                throw new TypeError(`Input ${JSON.stringify(name)}: { shared } must be a variable name (letters, digits, _), got `
+                throw new CompileRefusal('SHARED_INPUT_NAME_INVALID', `Input ${JSON.stringify(name)}: { shared } must be a variable name (letters, digits, _), got `
                     + `${JSON.stringify(spec.shared)}.`);
             }
         }
@@ -114,7 +115,7 @@ function varDeclOf(method, name, value) {
 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 `
+    throw new CompileRefusal('DECLARATION_TYPE_UNKNOWN', `.${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) ────────────────────────────────────────
@@ -374,7 +375,7 @@ class StepList {
      */
     err(field) {
         if (!this.errorSource) {
-            throw new TypeError('err(field) with no step name is only available inside an error handler — the sub-builder '
+            throw new CompileRefusal('ERROR_READ_OUTSIDE_HANDLER', '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').");
         }
@@ -438,7 +439,7 @@ class StepList {
      */
     stepSwitch(name, spec, cases, options) {
         if (!Array.isArray(cases) || cases.length === 0) {
-            throw new TypeError(`.stepSwitch('${name}'): needs at least one arm. With nothing to route, use .step().`);
+            throw new CompileRefusal('STEP_SWITCH_NO_ARMS', `.stepSwitch('${name}'): needs at least one arm. With nothing to route, use .step().`);
         }
         const arms = cases.map((c) => {
             const arm = new ArmBuilder();
@@ -448,7 +449,7 @@ class StepList {
             // is already named by the outcome or branch it leaves. Refusing beats
             // accepting it and dropping it on the floor.
             if (arm.armLabel !== undefined) {
-                throw new TypeError(`.stepSwitch('${name}') arm '${c.value}': .label() has nowhere to go — a port edge carries no `
+                throw new CompileRefusal('STEP_SWITCH_ARM_LABEL', `.stepSwitch('${name}') arm '${c.value}': .label() has nowhere to go — a port edge carries no `
                     + `label, and the exit is named by "${c.value}" already. Use options.label to rename the NODE.`);
             }
             return { value: String(c.value), body: arm.steps };
@@ -551,14 +552,14 @@ class StepList {
         // version the container emits (#1010).
         const containerPort = port === 'error' && (source?.kind === 'loop' || source?.kind === 'doWhile');
         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'}. `
+            throw new CompileRefusal('PORT_NO_SOURCE_STEP', `${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}`
                 + ' — a branch, parallel, terminate or return has no port to leave from; a .loop() or .doWhile() 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 `
+            throw new CompileRefusal('PORT_ALREADY_ROUTED', `${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;
@@ -611,7 +612,7 @@ class StepList {
             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 — `
+            throw new CompileRefusal('PORT_EMPTY_PATH', `${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 });
@@ -637,7 +638,7 @@ class StepList {
      */
     branch(name, cond, thenFn, elseFn, options) {
         if (options?.updates) {
-            throw new TypeError('.branch(): { updates } is not supported here — the platform strips variable updates from '
+            throw new CompileRefusal('UPDATES_NOT_SUPPORTED', '.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();
@@ -707,7 +708,7 @@ class StepList {
      */
     switch(name, on, cases, defaultFn, options) {
         if (options?.updates) {
-            throw new TypeError('.switch(): { updates } is not supported here — the platform strips variable updates from '
+            throw new CompileRefusal('UPDATES_NOT_SUPPORTED', '.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) => {
@@ -789,7 +790,7 @@ class StepList {
      */
     parallel(name, arms, options) {
         if (options?.updates) {
-            throw new TypeError('.parallel(): { updates } is not supported here — the platform strips variable updates from '
+            throw new CompileRefusal('UPDATES_NOT_SUPPORTED', '.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) => {
@@ -924,7 +925,7 @@ class StepList {
         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)}. `
+            throw new CompileRefusal('REF_TARGET_NOT_NAME', `.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() (or a .return() End's \`name\`), 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
@@ -1103,7 +1104,7 @@ class FlowBuilder extends StepList {
      */
     trigger(spec, options) {
         if (options?.updates) {
-            throw new TypeError('.trigger(): { updates } is not supported — a trigger has not run anything to assign from.');
+            throw new CompileRefusal('UPDATES_NOT_SUPPORTED', '.trigger(): { updates } is not supported — a trigger has not run anything to assign from.');
         }
         this._trigger = spec;
         if (options)
@@ -1263,7 +1264,7 @@ class FlowBuilder extends StepList {
     schemaVersion(version) {
         const refusal = schemaVersionRefusal(FLOW_SCHEMA_VERSIONS, version);
         if (refusal)
-            throw new Error(refusal);
+            throw new CompileRefusal('SCHEMA_VERSION_UNSUPPORTED', refusal);
         this._schemaVersion = version;
         return this;
     }

package/dist/flow-step-tree.js

@@ -44,7 +44,7 @@ export function childStepLists(step) {
             return [];
         default: {
             const unhandled = step;
-            throw new Error(`childStepLists: unhandled step kind ${JSON.stringify(unhandled.kind)}`);
+            throw new Error(`internal SDK error: childStepLists: unhandled step kind ${JSON.stringify(unhandled.kind)}`);
         }
     }
 }

package/dist/flow-variables.js

@@ -1,4 +1,5 @@
 import { globalNameCollisionMessage, globalNameCollisions } from './core/global-names.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 /** The keys of `variables` that hold declarations rather than name one (the map spelling). */
 export const CONTAINER_KEYS = new Set(['globals', 'nodes', 'variableUpdates']);
 const DIRECTIONS = new Set(['in', 'out', 'inout']);
@@ -8,7 +9,7 @@ export function readFlowGlobals(variables, strict = false) {
         return [];
     if (typeof variables !== 'object' || Array.isArray(variables)) {
         if (strict)
-            throw new Error('decompile: variables must be an object.');
+            throw new CompileRefusal('DECOMPILE_VARIABLES_SHAPE', 'decompile: variables must be an object.');
         return [];
     }
     const source = variables;
@@ -37,7 +38,7 @@ export function readFlowGlobals(variables, strict = false) {
         }
     }
     if (strict && unknown.length > 0) {
-        throw new Error(`decompile: unrecognized variables key${unknown.length === 1 ? '' : 's'}: `
+        throw new CompileRefusal('DECOMPILE_VARIABLES_SHAPE', `decompile: unrecognized variables key${unknown.length === 1 ? '' : 's'}: `
             + `${unknown.map((key) => JSON.stringify(key)).join(', ')}.`);
     }
     return globals;