@uipath/maestro-builder-sdk 6.57.0 → 6.58.0

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

@@ -5,6 +5,7 @@ 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`];
@@ -19,7 +20,7 @@ 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();
@@ -33,10 +34,10 @@ 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.
@@ -45,7 +46,7 @@ export async function loadBuiltFlow(file) {
     if (lowered.length > 0) {
         const problem = scriptFunctionScopeProblem(file, lowered);
         if (problem)
-            throw new Error(problem);
+            throw new CompileRefusal('SCRIPT_FUNCTION_SCOPE', problem);
     }
     return built;
 }
@@ -96,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}"`);
     }
@@ -104,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;
         }

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

@@ -20,6 +20,7 @@ import { jsonClone } from '../../../core/json-clone.js';
 import { schemaId } from '../../../core/stable-id.js';
 import { wireExprBody } from '../../../core/wire-expr.js';
 import { checkHitl, checkHitlRead } from './check.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 const BASE = 'uipath.human-in-the-loop';
 const QUICK_FORM = 'uipath.human-in-the-loop.quick-form';
 const ACTION_APP = 'uipath.human-in-the-loop.coded-action-app';
@@ -556,23 +557,23 @@ function hitlAt(typeName, version, factory) {
             const pinned = ctx.pinnedVersion;
             const exitModel = hitlExitModel(inputs, pinned);
             if (typeName !== BASE && inputs?.exposeError === true) {
-                throw new Error(`"${ctx.step}": exposeError needs the base human task's 1.2 definition, which adds the `
+                throw new CompileRefusal('HITL_OUTCOME_PORTS_VARIANT', `"${ctx.step}": exposeError needs the base human task's 1.2 definition, which adds the `
                     + `error output — the '${inputs?.variant}' variant has no such version. Drop the variant or exposeError.`);
             }
             if (inputs?.outcomePorts === true && !OUTCOME_HANDLE_NODE_TYPES.has(typeName)) {
-                throw new Error(`"${ctx.step}": outcomePorts: true, but the '${inputs?.variant}' variant reads its outcomes `
+                throw new CompileRefusal('HITL_OUTCOME_PORTS_VARIANT', `"${ctx.step}": outcomePorts: true, but the '${inputs?.variant}' variant reads its outcomes `
                     + `from its app and leaves on its single 'completed' exit. Route on out('${ctx.step}', 'Action') downstream.`);
             }
             if (inputs?.legacyCompleted === true && (inputs?.outcomePorts !== undefined || inputs?.exposeError === true)) {
-                throw new Error(`"${ctx.step}": legacyCompleted: true leaves the task on its single 'completed' handle, so it cannot also `
+                throw new CompileRefusal('HITL_LEGACY_COMPLETED_CONFLICT', `"${ctx.step}": legacyCompleted: true leaves the task on its single 'completed' handle, so it cannot also `
                     + `${inputs?.exposeError === true ? 'expose the error output (exposeError)' : 'set outcomePorts'}. Drop one.`);
             }
             if (inputs?.legacyCompleted === true && typeName === BASE && (pinned === '1.1' || pinned === '1.2')) {
-                throw new Error(`"${ctx.step}": legacyCompleted: true, but { version: '${pinned}' } pins the task's per-outcome definition, `
+                throw new CompileRefusal('HITL_LEGACY_COMPLETED_VERSION', `"${ctx.step}": legacyCompleted: true, but { version: '${pinned}' } pins the task's per-outcome definition, `
                     + `which has no 'completed' handle (flow validate refuses the edge). Drop the pin or legacyCompleted.`);
             }
             if (inputs?.exposeError === true && pinned !== undefined && pinned !== '1.2') {
-                throw new Error(`"${ctx.step}": exposeError needs the task's 1.2 definition, but { version: '${pinned}' } pins it. `
+                throw new CompileRefusal('HITL_EXPOSE_ERROR_VERSION', `"${ctx.step}": exposeError needs the task's 1.2 definition, but { version: '${pinned}' } pins it. `
                     + `Drop the pin or match it.`);
             }
             const { inputs: nodeInputs, outputs } = hitlInputs(inputs, typeName, ctx);

package/dist/nodes/http/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 an HTTP request action, explicitly choosing standalone or managed.
  *
@@ -12,7 +13,7 @@ import { builtinActionSpec } from '../../../core/actions.js';
  */
 export function http(inputs) {
     if (typeof inputs.managed !== 'boolean') {
-        throw new Error('http() requires managed: true or managed: false because they emit different platform nodes. '
+        throw new CompileRefusal('HTTP_MANAGED_REQUIRED', 'http() requires managed: true or managed: false because they emit different platform nodes. '
             + 'Use true for Managed HTTP Request/core.action.http.v2 or when non-2xx statuses must reach .onError(); '
             + 'use false for the standalone core.action.http node.');
     }

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

@@ -12,6 +12,7 @@ import { MANAGED_HTTP_ACTIVITY_TYPE_ID, MANAGED_HTTP_ESSENTIAL_CONFIGURATION, MA
 import { isRecord } from '../../../core/node-envelope.js';
 import { wireExprBody } from '../../../core/wire-expr.js';
 import { checkHttpRead, checkHttpStep, plainHttpOnErrorMessage } from './check.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 const PLAIN = 'core.action.http';
 const MANAGED = 'core.action.http.v2';
 /** The definition's `inputDefaults` at the version being emitted. */
@@ -67,7 +68,7 @@ function plainHttpInputs(i, ctx) {
     if (i.connection !== undefined
         || i.folder !== undefined
         || i.targetConnector !== undefined) {
-        throw new Error('standalone http cannot use Integration Service connection settings; set managed: true');
+        throw new CompileRefusal('HTTP_BINDING_REQUIRES_MANAGED', 'standalone http cannot use Integration Service connection settings; set managed: true');
     }
     return {
         ...defaults(ctx, PLAIN),
@@ -91,7 +92,7 @@ function managedHttpBinding(i, ctx) {
         return undefined;
     if (typeof i.connection !== 'string' || i.connection.trim() === ''
         || typeof i.folder !== 'string' || i.folder.trim() === '') {
-        throw new Error('managed http connection mode requires both a non-empty connection and folder');
+        throw new CompileRefusal('HTTP_MANAGED_BINDING_INCOMPLETE', 'managed http connection mode requires both a non-empty connection and folder');
     }
     // The same resolution a connector step gets: a self-referential binding is an
     // error, a stub is a warning.
@@ -121,11 +122,11 @@ function managedHttpBinding(i, ctx) {
  */
 function managedHttpInputs(i, binding, ctx) {
     if (i.targetConnector !== undefined && !binding) {
-        throw new Error('managed http targetConnector requires both a non-empty connection and folder');
+        throw new CompileRefusal('HTTP_TARGET_CONNECTOR_REQUIRES_BINDING', 'managed http targetConnector requires both a non-empty connection and folder');
     }
     if (i.targetConnector !== undefined
         && (typeof i.targetConnector !== 'string' || i.targetConnector.trim() === '')) {
-        throw new Error('managed http targetConnector must be a non-empty connector key');
+        throw new CompileRefusal('HTTP_TARGET_CONNECTOR_EMPTY', 'managed http targetConnector must be a non-empty connector key');
     }
     const url = ctx.render(i.url);
     const bodyParameters = {
@@ -270,7 +271,7 @@ function liftHttp(node, ctx, managed) {
     const connectionValue = detail.connectionId ?? detail.connectionResourceId ?? req.connection;
     const retry = inputs.retryCount !== undefined && Number(inputs.retryCount) !== 0 ? Number(inputs.retryCount) : undefined;
     if (retry !== undefined && !Number.isFinite(retry)) {
-        throw new Error(`decompile: expected a number, got ${JSON.stringify(inputs.retryCount)}.`);
+        throw new CompileRefusal('DECOMPILE_NOT_A_NUMBER', `decompile: expected a number, got ${JSON.stringify(inputs.retryCount)}.`);
     }
     const branchRows = Array.isArray(inputs.branches) ? inputs.branches : [];
     const returns = liftReturns(node) ?? returnsFromReads(ctx.reads());

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

@@ -4,6 +4,7 @@
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports them.
  */
 import { builtinActionSpec } from '../../../core/actions.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 /**
  * Invoke a deployed RPA (robotic process automation) workflow — a classic
  * UI-automation process, published to Orchestrator, run by a robot.
@@ -166,7 +167,7 @@ export function agenticProcess(inputs) {
     // code — and silently dropping the returns would validate a read that can
     // never be satisfied.
     if (inputs.completion === 'fire-and-forget' && inputs.returns !== undefined) {
-        throw new Error("agenticProcess(): completion 'fire-and-forget' publishes no output — remove `returns`, "
+        throw new CompileRefusal('FIRE_AND_FORGET_RETURNS', "agenticProcess(): completion 'fire-and-forget' publishes no output — remove `returns`, "
             + "or use completion: 'wait' to read the process result.");
     }
     return builtinActionSpec({ kind: 'agenticProcess', inputs });

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

@@ -3,6 +3,7 @@ import { jsonClone } from '../../../core/json-clone.js';
 import { isRecord } from '../../../core/node-envelope.js';
 import { checkQueueItem, itemDataIsString, queueItemExprMessage } from './check.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './record.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 const CREATE = 'core.action.queue.create';
 const CREATE_AND_WAIT = 'core.action.queue.create-and-wait';
 /**
@@ -39,7 +40,7 @@ function queueItemDef(spec, nodeType, stepName, ids, base) {
     // The template at the version being emitted: the registry resolved it exactly
     // (an unregistered pin is NODE_VERSION_UNREGISTERED before this runs).
     if (!base)
-        throw new Error(`no bundled definition for "${nodeType}"`);
+        throw new Error(`internal SDK error: no bundled definition for "${nodeType}"`);
     const def = jsonClone(base);
     def.model.bindings.resourceKey = spec.key;
     def.model.context = [
@@ -172,7 +173,7 @@ function itemDataString(item, step, typeName, version) {
         return '';
     for (const [k, v] of rows) {
         if (v instanceof Expr)
-            throw new Error(queueItemExprMessage(step, typeName, version, k));
+            throw new CompileRefusal('QUEUE_ITEM_EXPR_UNSUPPORTED', queueItemExprMessage(step, typeName, version, k));
     }
     return JSON.stringify(item);
 }

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

@@ -11,6 +11,7 @@ import { wireExprBody } from '../../../core/wire-expr.js';
 import { jsonClone } from '../../../core/json-clone.js';
 import { VARIANT_OPERATION } from './spec.js';
 import { checkTransform } from './check.js';
+import { CompileRefusal } from '../../../core/compile-refusal.js';
 /**
  * Emit a transform's `inputs` in the canonical shape the node's runtime reads:
  * `collection` as a BARE variable path (not `=js:`-prefixed — it is a path
@@ -210,7 +211,7 @@ function transformAt(typeName, variant, version, factory) {
             // (TRANSFORM_VARIANT_UNKNOWN). A compile that skipped check refuses here
             // rather than emit the generic node, which would run and be the wrong node.
             if (variant === undefined && inputs?.variant !== undefined && inputs.variant !== null) {
-                throw new Error(`transform step "${ctx.step}": variant ${JSON.stringify(inputs.variant)} is not a Transform node type `
+                throw new CompileRefusal('TRANSFORM_VARIANT_UNKNOWN', `transform step "${ctx.step}": variant ${JSON.stringify(inputs.variant)} is not a Transform node type `
                     + `(${VARIANTS.join(', ')}), so there is no node to emit. Fix the variant, or omit it for the generic Transform.`);
             }
             const base = ctx.definition(typeName, version)?.outputDefinition;

package/dist/raw-node.js

@@ -10,6 +10,7 @@ import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { rawNodeInputProblem, rawNodeTypedFamilyWarning } from './raw-node-advice.js';
 import { forwardFanOut } from './core/definition-handles.js';
 import { RAW_NODE_EXITS } from './core/raw-node-exits.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 /**
  * Place a node this SDK has no factory for, carrying its definition verbatim
  * (`uipath.exotic.thing@2.1` and the manifest the platform served for it).
@@ -101,12 +102,12 @@ class RawNode extends FlowAction {
         // type never reads is refused by the serializer, for every contribution.)
         const refusal = connectorRawNodeRefusal(this.spec.nodeType);
         if (refusal)
-            throw new Error(refusal);
+            throw new CompileRefusal('RAW_NODE_CONNECTOR', refusal);
         const version = context.requestedVersion ?? this.spec.version;
         if (context.requestedVersion !== undefined && context.requestedVersion !== this.spec.version) {
             // Versions are exact everywhere in this SDK: a contributor may not
             // substitute its own for an explicit request (design §2.6).
-            throw new Error(`rawNode("${this.spec.nodeType}") carries version ${this.spec.version}, but the step requests `
+            throw new CompileRefusal('RAW_NODE_VERSION_MISMATCH', `rawNode("${this.spec.nodeType}") carries version ${this.spec.version}, but the step requests `
                 + `${context.requestedVersion}. Pass the manifest for the requested version, or drop { version }.`);
         }
         return {