@uipath/maestro-builder-sdk 6.56.0 → 6.58.0

package/dist/decompile.js

@@ -112,6 +112,38 @@ let runAbsorbed = new Map();
 let runFlowId = 'flow';
 /** `DecompileOptions.readSidecar` for the current run. */
 let runReadSidecar;
+/**
+ * A host's own say on decompile's default script form, beside the TypeScript
+ * hand-over in core/typescript-module.ts:
+ * `globalThis[Symbol.for('uipath.maestro-builder-sdk.scripts')] = 'string'`.
+ */
+const HOST_SCRIPTS = Symbol.for('uipath.maestro-builder-sdk.scripts');
+/**
+ * Function scripts by default only under Node. The exact text a function form
+ * stores is what the loader's `Function.prototype.toString()` returns, which is
+ * the author's own text under Node's type stripping (what `compile` and `uip`
+ * run) and a reprint under other loaders. A host that runs the SDK in a page has
+ * not been measured, so there a decompiled script stays a string unless asked.
+ */
+function defaultScripts() {
+    const host = globalThis[HOST_SCRIPTS];
+    if (host === 'function' || host === 'string')
+        return host;
+    // Real Node, tested as core/typescript-module.ts does: a page bundle may shim
+    // `process.versions.node` (cli-browser's banner sets it) but does not define
+    // `process.getBuiltinModule`.
+    return typeof globalThis.process?.getBuiltinModule === 'function' ? 'function' : 'string';
+}
+/** How this run prints scripts (`DecompileOptions.scripts`). */
+let runScripts = 'function';
+/** The module-level functions print hooks declared this run, in order. */
+let runModuleFunctions = [];
+/**
+ * Each step's reserved function name, by node: keyed by the node itself, not its
+ * id, because a root step and a subflow step may share an id, and two
+ * `function script_<id>` declarations would make the module unloadable.
+ */
+let runFunctionNames = new Map();
 function warnOnce(message) {
     if (runWarned.has(message))
         return;
@@ -336,6 +368,8 @@ class Imports {
     locals = new Set(['flow']);
     /** Names a package may not take bare: the SDK's helpers and every built-in factory. */
     reserved;
+    /** The SDK's type-only names (`FlowVars`): `import { type X }`, erased under type stripping. */
+    types = new Set();
     constructor() {
         this.reserved = new Set([
             ...SDK_HELPER_NAMES,
@@ -368,14 +402,25 @@ class Imports {
         this.locals.add(local);
         return local;
     }
+    /**
+     * A type-only name from the SDK: `import { type X }`, erased under type
+     * stripping, so it never needs a runtime export. Taken as a local, so no
+     * package factory binds the same name.
+     */
+    useType(name) {
+        this.types.add(name);
+        this.locals.add(name);
+        return name;
+    }
     /** One import per module: the SDK first, then the packages by name. */
     line(specifier) {
         const lines = [];
         for (const [module, names] of [...this.used].sort(([a], [b]) => (a === undefined ? -1 : b === undefined ? 1 : a.localeCompare(b)))) {
-            if (names.size === 0)
+            const types = module === undefined ? [...this.types].filter((t) => !names.has(t)).sort().map((t) => `type ${t}`) : [];
+            if (names.size === 0 && types.length === 0)
                 continue;
             const bindings = [...names].sort(([a], [b]) => a.localeCompare(b)).map(([name, local]) => (local === name ? name : `${name} as ${local}`));
-            lines.push(`import { ${bindings.join(', ')} } from ${tsLiteral(module ?? specifier)};`);
+            lines.push(`import { ${[...bindings, ...types].join(', ')} } from ${tsLiteral(module ?? specifier)};`);
         }
         return lines.join('\n');
     }
@@ -826,6 +871,11 @@ function emitRegisteredSpec(node, imp, inputNames, graph) {
         json: (v) => tsLiteral(v),
         key: (k) => key(k),
         helper: (name) => imp.use(name),
+        typeHelper: (name) => imp.useType(name),
+        warn: (message) => warnOnce(`step ${tsLiteral(node.id)}: ${message}`),
+        functionName: () => moduleFunctionName(node),
+        declareFunction: (source) => { runModuleFunctions.push(source); },
+        scripts: runScripts,
     };
     const call = impl.print?.(spec, print) ?? {
         factory: impl.factory,
@@ -2838,6 +2888,9 @@ function foldOutputBacking(flow) {
 }
 export function decompile(flow, options = {}) {
     flow = foldOutputBacking(flow);
+    runScripts = options.scripts ?? defaultScripts();
+    runModuleFunctions = [];
+    runFunctionNames = new Map();
     const importSpecifier = options.importSpecifier ?? './flow-sdk.js';
     runStrict = options.bestEffort === false;
     runWarn = options.warn;
@@ -2991,7 +3044,27 @@ export function decompile(flow, options = {}) {
     const hoisted = [...carriedConsts, ...runRawManifests]
         .map(([name, json]) => `const ${name} = ${json};`)
         .join('\n\n');
-    return [imp.line(importSpecifier), hoisted, chain].filter((p) => p.length > 0).join('\n\n') + '\n';
+    const functions = runModuleFunctions.join('\n\n');
+    return [imp.line(importSpecifier), hoisted, chain, functions].filter((p) => p.length > 0).join('\n\n') + '\n';
+}
+/**
+ * A step's module-level function name: `script_<id>`, with what an identifier
+ * cannot hold replaced by `_`, and a numeric suffix when two steps (in different
+ * scopes, or with ids that sanitize alike) would get the same one.
+ * The `script_` prefix keeps it clear of every SDK export (all camelCase) and of
+ * the hoisted constants.
+ */
+function moduleFunctionName(node) {
+    const have = runFunctionNames.get(node);
+    if (have)
+        return have;
+    const base = `script_${node.id.replace(/[^A-Za-z0-9_$]/g, '_')}`;
+    const taken = new Set(runFunctionNames.values());
+    let name = base;
+    for (let i = 2; taken.has(name); i++)
+        name = `${base}_${i}`;
+    runFunctionNames.set(node, name);
+    return name;
 }
 /**
  * Top-level nodes (no `parentId`) that no root trigger reaches over ANY edge —

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-node-type.d.ts

@@ -327,6 +327,27 @@ export interface FlowPrintContext {
     key(name: string): string;
     /** An authoring helper (`lit`, `input`, …) by name: imported into the printed source, and its identifier. */
     helper(name: string): string;
+    /** An exported TYPE (`FlowVars`) by name: imported as `type <name>`, and its identifier. */
+    typeHelper(name: string): string;
+    /**
+     * Report a finding about this step, printed once with the step named.
+     * Informational: it never fails `--strict`, so it is for a choice of spelling
+     * that loses nothing, not for something recompiling would drop.
+     */
+    warn(message: string): void;
+    /**
+     * The identifier of this step's module-level function: unique in the printed
+     * module, the same on every call for the step. Reserving it declares nothing;
+     * {@link declareFunction} does.
+     */
+    functionName(): string;
+    /** Add a declaration to the end of the printed module, after the flow, verbatim. */
+    declareFunction(source: string): void;
+    /**
+     * How scripts print: `function` (the default) as a TypeScript function where
+     * the body allows it, `string` always as `script({ code })`.
+     */
+    readonly scripts: 'function' | 'string';
 }
 /** What a node-local `check` may ask of the checker. */
 export interface FlowCheckContext {

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;

package/dist/load.js

@@ -3,6 +3,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { basename, dirname, join, resolve } from 'node:path';
 import { statSync } from 'node:fs';
 import { useThisSdkForAuthoredSource } from './sdk-resolve.js';
+import { scriptFunctionLowerings } from './core/script-function.js';
+import { scriptFunctionScopeProblem } from './script-function-scope.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 /** Resolve a user argument (a `.ts` path or a BaseName) to a flow source file. */
 export function resolveFlowFile(arg) {
     const candidates = [arg, `${arg}.flow.ts`, `${arg}.ts`];
@@ -17,10 +20,11 @@ export function resolveFlowFile(arg) {
         }
         return resolvedCandidate;
     }
-    throw new Error(`flow source not found: tried ${candidates.join(', ')}`);
+    throw new CompileRefusal('FLOW_SOURCE_NOT_FOUND', `flow source not found: tried ${candidates.join(', ')}`);
 }
 export async function loadBuiltFlow(file) {
     useThisSdkForAuthoredSource();
+    const firstLowering = scriptFunctionLowerings().length;
     let mod;
     try {
         mod = await import(pathToFileURL(file).href);
@@ -30,10 +34,20 @@ export async function loadBuiltFlow(file) {
     }
     const exp = mod.default ?? mod.flow ?? mod.workflow;
     if (!exp)
-        throw new Error(`${file} has no default export. Add: export default flow('id')...build();`);
+        throw new CompileRefusal('FLOW_NO_DEFAULT_EXPORT', `${file} has no default export. Add: export default flow('id')...build();`);
     const built = typeof exp.build === 'function' ? exp.build() : exp;
     if (!built || !Array.isArray(built.steps))
-        throw new Error(`${file} default export is not a built flow. Did you call .build()?`);
+        throw new CompileRefusal('FLOW_EXPORT_NOT_BUILT', `${file} default export is not a built flow. Did you call .build()?`);
+    // A `script(fn)` function was lowered from its own text, which cannot show a
+    // name it takes from its module; this source can (script-function-scope.ts).
+    // Only a flow that lowered one pays for the program this builds.
+    // The functions this import lowered; see scriptFunctionLowerings.
+    const lowered = scriptFunctionLowerings().slice(firstLowering);
+    if (lowered.length > 0) {
+        const problem = scriptFunctionScopeProblem(file, lowered);
+        if (problem)
+            throw new CompileRefusal('SCRIPT_FUNCTION_SCOPE', problem);
+    }
     return built;
 }
 /**
@@ -83,7 +97,7 @@ export function connectorImportDiagnostic(error) {
         return undefined;
     }
     if (parent === 'connectors') {
-        return new Error(`connector import "${unresolved}" does not name a file. The generated ` +
+        return new CompileRefusal('CONNECTOR_IMPORT_NOT_A_FILE', `connector import "${unresolved}" does not name a file. The generated ` +
             `descriptors are TypeScript, so the specifier keeps its real extension; ` +
             `import "${moduleFile}"`);
     }
@@ -91,7 +105,7 @@ export function connectorImportDiagnostic(error) {
     if (!statSync(descriptorData, { throwIfNoEntry: false })?.isDirectory()) {
         return undefined;
     }
-    return new Error(`connector import "${unresolved}" does not name a file; module candidate ` +
+    return new CompileRefusal('CONNECTOR_IMPORT_NOT_A_FILE', `connector import "${unresolved}" does not name a file; module candidate ` +
         `"${moduleFile}" and descriptor data "${descriptorData}" are separate; ` +
         `import "${moduleFile}"`);
 }

package/dist/nodes/agent/flow/inline-agent.js

@@ -10,6 +10,7 @@ import { processResourceBindings } from '../../../core/process-resource.js';
 import { fnv1aX4Uuid, schemaId } from '../../../core/stable-id.js';
 import { synthesizedDefinitionRefusal } from '../../../core/synthesized-definition.js';
 import { BUILTIN_TOOL_DEFS, INLINE_AGENT, PROCESS_TOOL_META, a2aToolDef, builtinToolResourceJson, connectorToolDef, connectorToolDescription, connectorToolDetail, connectorToolResourceJson, contextIndexDef, contextResourceJson, declaresMemoryHandle, escalationAppFolder, escalationDef, escalationResourceJson, fieldSchema, httpRequestToolResourceJson, inlineAgentDef, ixpToolDef, mcpToolDef, memoryResourceDef, processToolDef, renderContextQuery, toolResourceJson, } from './resources.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 /** Every bundled version of the inline agent, oldest first; the newest is the default (#956). */
 export const INLINE_AGENT_VERSIONS = ['1.2', '1.3', '1.4'];
 export const INLINE_AGENT_DEFAULT_VERSION = INLINE_AGENT_VERSIONS[INLINE_AGENT_VERSIONS.length - 1];
@@ -39,7 +40,7 @@ export function serializeInlineAgent(s, ctx) {
     if (!def)
         throw new Error(`internal SDK error: step "${step}": no definition resolves for ${INLINE_AGENT}@${version}.`);
     if (s.memory !== undefined && !declaresMemoryHandle(def)) {
-        throw new Error(`"${step}" attaches \`memory\`, but ${INLINE_AGENT}@${version} declares no \`memory\` handle. `
+        throw new CompileRefusal('AGENT_MEMORY_VERSION_NO_HANDLE', `"${step}" attaches \`memory\`, but ${INLINE_AGENT}@${version} declares no \`memory\` handle. `
             + (version === INLINE_AGENT_DEFAULT_VERSION
                 ? `Pin a version that has it with inlineAgent({ ..., version: '<x.y>' }) `
                     + `(bundled with memory: ${INLINE_AGENT_VERSIONS.filter((v) => declaresMemoryHandle(ctx.definition(INLINE_AGENT, v))).join(', ') || 'none'}), or drop \`memory\`.`
@@ -134,8 +135,8 @@ export function serializeInlineAgent(s, ctx) {
         // the type `…context.index.<slug>.`, which no tenant serves, and nothing
         // after this point would say so.
         if (typeof cx?.id !== 'string' || !GUID_RE.test(cx.id)) {
-            throw Object.assign(new Error(`inline agent "${step}": context index "${cx?.name ?? ''}" needs its index id (a GUID) as \`id\`; `
-                + `got ${JSON.stringify(cx?.id)}. \`uip solution resources list --kind Index --source remote --search "<name>"\` returns it as \`Key\`.`), { code: 'AGENT_CONTEXT_NO_ID' });
+            throw new CompileRefusal('AGENT_CONTEXT_NO_ID', `inline agent "${step}": context index "${cx?.name ?? ''}" needs its index id (a GUID) as \`id\`; `
+                + `got ${JSON.stringify(cx?.id)}. \`uip solution resources list --kind Index --source remote --search "<name>"\` returns it as \`Key\`.`);
         }
         const cdef = contextIndexDef({ name: cx.name, id: cx.id });
         // `<step>Context`, deduped for a second index on the same agent, unless the
@@ -207,7 +208,7 @@ export function serializeInlineAgent(s, ctx) {
             const bdef = ownEntry(BUILTIN_TOOL_DEFS, tr.tool);
             tdef = bdef === undefined ? undefined : jsonClone(bdef);
             if (!tdef)
-                throw new Error(`inline agent "${step}": unknown builtin tool "${tr.tool}" (analyzefiles | summarize | batchtransform).`);
+                throw new CompileRefusal('INLINE_AGENT_TOOL_UNKNOWN_BUILTIN', `inline agent "${step}": unknown builtin tool "${tr.tool}" (analyzefiles | summarize | batchtransform).`);
             label = tdef.display.label;
             // The designer-placed node carries the def's `inputDefaults` with the
             // author's values over them — the context rule, kept per builtin (each def
@@ -242,7 +243,7 @@ export function serializeInlineAgent(s, ctx) {
         }
         else if (tr.kind === 'connector') {
             if (!ctx.library)
-                throw new Error(`inline agent "${step}"'s connector tool needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+                throw new CompileRefusal('LIBRARY_REQUIRED', `inline agent "${step}"'s connector tool needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
             const rc = ctx.library.resolve(tr.connector, tr.operation, tr.version, tr.object);
             // An entry `prepare` synthesized from Integration Service compiles in BPMN
             // only — for a tool as for a step: `connectorToolDef` reads the same
@@ -337,7 +338,7 @@ export function serializeInlineAgent(s, ctx) {
         else {
             const meta = ownEntry(PROCESS_TOOL_META, tr.kind);
             if (!meta)
-                throw new Error(`inline agent "${step}": unknown tool kind "${tr.kind}".`);
+                throw new CompileRefusal('INLINE_AGENT_TOOL_UNKNOWN_KIND', `inline agent "${step}": unknown tool kind "${tr.kind}".`);
             tdef = processToolDef(tr.kind, tr);
             label = tr.name;
             // The definition's `model.context` names `<bindings.name>` /

package/dist/nodes/connector/flow/node-type.js

@@ -9,6 +9,7 @@ import { jsonClone } from '../../../core/json-clone.js';
 import { subNodeId } from '../../../core/node-id-placeholder.js';
 import { synthesizedDefinitionRefusal } from '../../../core/synthesized-definition.js';
 import { tsLiteral, tsObject } from '../../../core/ts-literal.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 const CONNECTOR_PREFIX = 'uipath.connector.';
 /** `<key>.<action>` after the prefix, split on the last dot; undefined for an event, a trigger, or a name with no action. */
 function splitOperation(typeName) {
@@ -65,7 +66,7 @@ function listOutputs(rc, nodeId) {
 function serializeConnector(spec, ctx) {
     const step = ctx.step;
     if (!ctx.library)
-        throw new Error(`connector "${step}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+        throw new CompileRefusal('LIBRARY_REQUIRED', `connector "${step}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
     let rc;
     try {
         rc = ctx.library.resolve(spec.key, spec.action, spec.version, spec.object);

package/dist/nodes/data-fabric/flow/factories.js

@@ -5,6 +5,7 @@
  * them, so authors import them exactly as before.
  */
 import { builtinActionSpec } from '../../../core/actions.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 /**
  * Query entity records from Data Fabric (`core.datafabric.read`). The result
  * publishes to the step's `output`; downstream references re-fetch fresh data
@@ -129,6 +130,6 @@ function assertOneRecordRef(record, factory) {
     const byId = record?.byId !== undefined;
     const fromRead = typeof record?.fromRead === 'string';
     if (byId === fromRead) {
-        throw new Error(`${factory}() targets exactly ONE of record: { byId } or record: { fromRead: '<step>' }.`);
+        throw new CompileRefusal('DATAFABRIC_RECORD_REF', `${factory}() targets exactly ONE of record: { byId } or record: { fromRead: '<step>' }.`);
     }
 }

package/dist/nodes/data-fabric/flow/verbs.js

@@ -1,6 +1,7 @@
 import { applyScope, baseConfig, entityConfigOf, fieldRows, filterRows, liftFields, liftRecord, liftScope, liftValue, printFields, printRecord, scopeOptions, targetRecord, } from './shared.js';
 import { checkCreate, checkRead, checkUpdate, checkWrite } from './check.js';
 import { rawNodeAdvice } from './raw.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 /**
  * Every Data Fabric node carries no node-level `model`, whichever path emits it
  * (a verb, or a rawNode of its definition). Studio Web never writes one
@@ -36,7 +37,7 @@ function readAt(version) {
         nodeModel: NODE_MODEL, rawNode: READ_ADVICE,
         serialize: ({ inputs }, ctx) => {
             if (version === '1.0' && inputs.resultMode !== undefined) {
-                throw new Error("dataFabricRead(): { resultMode } needs the node's 1.4 definition, but { version: '1.0' } was "
+                throw new CompileRefusal('DATAFABRIC_RESULT_MODE_VERSION', "dataFabricRead(): { resultMode } needs the node's 1.4 definition, but { version: '1.0' } was "
                     + 'requested. Drop the version, request 1.4, or drop resultMode.');
             }
             const cfg = baseConfig(inputs);

package/dist/nodes/delay/flow/factories.js

@@ -3,6 +3,7 @@
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports it.
  */
 import { builtinActionSpec } from '../../../core/actions.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 /**
  * Declare a delay — a step that pauses the flow for a fixed length of time and
  * then carries on.
@@ -31,7 +32,7 @@ export function delay(inputs) {
     const hasDuration = 'duration' in inputs;
     const hasUntil = 'until' in inputs;
     if (hasDuration === hasUntil) {
-        throw new Error("delay() takes exactly ONE of { duration } (an ISO-8601 duration, e.g. 'PT15M') or "
+        throw new CompileRefusal('DELAY_DURATION_XOR_UNTIL', "delay() takes exactly ONE of { duration } (an ISO-8601 duration, e.g. 'PT15M') or "
             + "{ until } (an ISO-8601 date-time, e.g. '2026-09-01T09:00:00Z').");
     }
     return builtinActionSpec({ kind: 'delay', inputs });

package/dist/nodes/document/flow/ixp.js

@@ -14,6 +14,7 @@ import { definitionHasErrorPort } from '../../../core/error-port.js';
 import { Expr } from '../../../core/expr.js';
 import { jsonClone } from '../../../core/json-clone.js';
 import { parseIxpProjectType } from './spec.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 const IXP_PREFIX = 'uipath.ixp.';
 export const IXP_DIAGNOSTICS = {
     IXP_FORBIDDEN_INPUT: { severity: 'error', summary: 'an IxP step setting an input the current node does not declare' },
@@ -65,7 +66,10 @@ const IXP_DEF = ixpDefinition;
 export function ixpExtractDef(spec) {
     const parts = parseIxpProjectType(spec.project);
     if (!parts) {
-        throw new Error(`ixpExtract: "${spec.project}" is not a resolvable extractor node type. It must be `
+        // The three conditions check tells apart, under check's three codes.
+        const code = typeof spec.project !== 'string' || spec.project.trim() === '' ? 'IXP_NO_PROJECT'
+            : !spec.project.startsWith('uipath.ixp.') ? 'IXP_PROJECT_NOT_NODE_TYPE' : 'IXP_PROJECT_TAIL_UNPARSEABLE';
+        throw new CompileRefusal(code, `ixpExtract: "${spec.project}" is not a resolvable extractor node type. It must be `
             + `uipath.ixp.<slug>.<projectVersionId>-<folderKey> — copy it from `
             + `\`uip maestro flow registry pull --force && uip maestro flow registry search -f "type:startsWith=uipath.ixp"\`.`);
     }

package/dist/nodes/hitl/flow/check.js

@@ -7,7 +7,8 @@ export const HITL_DIAGNOSTICS = {
     HITL_VARIANT_UNKNOWN: { severity: 'error', summary: 'a variant that names no human-task node type' },
     HITL_OUTCOME_PORTS_VARIANT: { severity: 'error', summary: 'exposeError or outcomePorts on a variant that cannot honour it' },
     HITL_LEGACY_COMPLETED: { severity: 'warning', summary: "a task with outcomes that leaves on the legacy 'completed' handle" },
-    HITL_LEGACY_COMPLETED_CONFLICT: { severity: 'error', summary: 'legacyCompleted with outcomePorts or exposeError, or where it changes nothing' },
+    HITL_LEGACY_COMPLETED_CONFLICT: { severity: 'error', summary: 'legacyCompleted with outcomePorts or exposeError' },
+    HITL_LEGACY_COMPLETED_NO_EFFECT: { severity: 'error', summary: "legacyCompleted where 'completed' is already the only exit" },
     HITL_DOCUMENT_WITHOUT_VARIANT: { severity: 'error', summary: 'a document on a task that is not a validation station' },
     HITL_DOCVAL_WITH_FIELDS: { severity: 'error', summary: 'form fields on a validation station' },
     HITL_DOCVAL_NO_DOCUMENT: { severity: 'error', summary: 'a validation station with no document' },
@@ -103,7 +104,8 @@ export function checkHitl(inputs, ctx) {
             return;
         }
         if (!hitlDerivesOutcomeHandles(variant) || outcomes.length === 0) {
-            at('HITL_LEGACY_COMPLETED_CONFLICT', `Human task "${step}" sets legacyCompleted: true, but ${outcomes.length === 0 ? 'it has no outcomes'
+            // Its own code: this flow compiles, so the code is check's alone.
+            at('HITL_LEGACY_COMPLETED_NO_EFFECT', `Human task "${step}" sets legacyCompleted: true, but ${outcomes.length === 0 ? 'it has no outcomes'
                 : `its variant is "${variant}", which reads its outcomes from its app`}, so 'completed' is already its only exit.`, 'Drop `legacyCompleted`.');
             return;
         }