@uipath/maestro-builder-sdk 6.56.0 → 6.58.0

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/script/flow/factories.d.ts

@@ -3,7 +3,48 @@
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports it.
  */
 import { type ActionSpec } from '../../../core/actions.js';
-import type { ScriptInputs } from './spec.js';
+import type { ScriptReturns } from '../../../core/script-return.js';
+import type { ScriptInputs, ScriptValue } from './spec.js';
+/**
+ * Declare an inline script action, as a TypeScript function the compiler checks.
+ *
+ * The function is never called. Its body, exactly as written, becomes the
+ * script; its parameter is an authoring-time name for the Flow runtime's own
+ * `$vars` global and is renamed to it. `returns` is the declaration that reaches
+ * the `.flow`, and tsc checks the function's return against it.
+ *
+ * The function may read only what the script runtime has (the ES2020 built-ins
+ * and `console`): a module constant, an import or a library throws here, because
+ * in the run it would be a `ReferenceError`.
+ *
+ * ```ts
+ * .step('post', script(parseMessage, { returns: { channel: 'string', threadTs: 'string' } }))
+ *
+ * function parseMessage(vars: FlowVars) {
+ *   const m = /archives\/([A-Z0-9]+)\/p(\d{10})(\d{6})/.exec(String(vars.start.output.message));
+ *   if (!m) throw new Error('not a Slack permalink');
+ *   return { channel: m[1], threadTs: m[2] + '.' + m[3] };
+ * }
+ * ```
+ *
+ * @param fn - The script, as a function of the variable scope (or of nothing).
+ * @param options - What the function returns (`returns`), as `script({ returns })` takes it.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function script<V, const R extends ScriptReturns>(fn: (vars: V) => ScriptValue<R>, options: {
+    returns: R;
+}): ActionSpec;
+/**
+ * Declare an inline script action, as a TypeScript function, with no declared
+ * return: the body's type is inferred as it is for a string body.
+ *
+ * @param fn - The script, as a function of the variable scope (or of nothing).
+ * @param options - No `returns`; pass one to have tsc check the function against it.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function script<V>(fn: (vars: V) => unknown, options?: {
+    returns?: never;
+}): ActionSpec;
 /**
  * Declare an inline script action.
  *

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

@@ -3,13 +3,12 @@
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports it.
  */
 import { builtinActionSpec } from '../../../core/actions.js';
-/**
- * Declare an inline script action.
- *
- * @param inputs - The JavaScript body (`code`, which must `return`) and what it
- * returns (`returns`).
- * @returns An action spec to pass to `.step(name, …)`.
- */
-export function script(inputs) {
-    return builtinActionSpec({ kind: 'script', inputs });
+import { lowerScriptFunction } from '../../../core/script-function.js';
+import { FLOW_SCRIPT_RUNTIME } from './runtime.js';
+export function script(arg, options) {
+    if (typeof arg !== 'function')
+        return builtinActionSpec({ kind: 'script', inputs: arg });
+    const code = lowerScriptFunction(arg, FLOW_SCRIPT_RUNTIME, `script(${arg.name || 'function'})`);
+    const returns = options?.returns;
+    return builtinActionSpec({ kind: 'script', inputs: { code, ...(returns !== undefined ? { returns } : {}) } });
 }

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

@@ -6,6 +6,8 @@
  */
 import { declaredScriptShape, inferScriptShape } from '../../../core/script-return.js';
 import { jsonClone } from '../../../core/json-clone.js';
+import { scriptBodyEarlyError, scriptBodySyntaxError, scriptBodyTypeScriptSyntax, tryLowerScriptFunction } from '../../../core/script-function.js';
+import { FLOW_SCRIPT_RUNTIME } from './runtime.js';
 import { checkScript } from './check.js';
 /**
  * Declare what a `core.action.script` node actually publishes.
@@ -83,6 +85,72 @@ function liftReturns(node, code, definitionType) {
     }
     return declared;
 }
+/** The fallback reason for a body that parses alone but not as the printed function, or comes back changed. */
+const UNCHANGED = 'its text would not come back unchanged as a function body (a line comment on its last line, for one).';
+/**
+ * The function a script step prints as, declared after the flow, or undefined
+ * when the step keeps the string form (`script({ code })`), with a warning.
+ *
+ * A designer-edited flow may hold a half-written script, and decompile still has
+ * to produce a source that builds, so a body that cannot become a function is a
+ * reason to keep the string, never to fail. It becomes one only when all of
+ * these hold (docs/SCRIPT_FUNCTION_DESIGN.md, "Decompile"):
+ *
+ *   1. it parses;
+ *   2. it has no TypeScript-only syntax, which the loader would erase or reread
+ *      (`const n: number`, or `f<T>(x)`, which JavaScript reads as comparisons);
+ *   3. `script(fn)` would accept it: it reads only names on the runtime's list
+ *      (a function that failed this would throw when the source loads);
+ *   4. it comes back from compile byte for byte. The function is printed with
+ *      the body verbatim between its braces, which lowering returns exactly, so
+ *      this holds for nearly every body that passes the others; it is checked
+ *      because it is cheap, and a line comment on the last line is the case that
+ *      fails it (it would swallow the closing brace);
+ *   5. the engine compiles it as a strict function of `$vars`: an early error
+ *      (a duplicate `let`, a `const $vars`, an octal literal) that TypeScript's
+ *      parser does not report would make the whole module unloadable.
+ *
+ * The parameter is named `$vars`, so nothing is renamed and the body's text is
+ * the node's text.
+ */
+function printAsFunction(code, ctx) {
+    if (ctx.scripts !== 'function')
+        return undefined;
+    const keep = (why) => {
+        ctx.warn(`script kept as a string: ${why} Fix the script and decompile again to get a typed function.`);
+        return undefined;
+    };
+    const syntax = scriptBodySyntaxError(code);
+    if (syntax)
+        return keep(`its body does not parse (${syntax}).`);
+    const typed = scriptBodyTypeScriptSyntax(code);
+    if (typed)
+        return keep(`it contains ${typed}, which a TypeScript loader would erase or reread, changing the script.`);
+    const name = ctx.functionName();
+    // With authoring's own rules: the printed function is lowered by `script(fn)`
+    // when the source is compiled back, so a body that rule refuses (`$vars?.x`,
+    // `$vars['x']`, an alias) must stay a string here, or compile would refuse it.
+    const lowered = tryLowerScriptFunction(`function ${name}($vars) {${code}}`, FLOW_SCRIPT_RUNTIME, { scopeReadsOnly: true });
+    if (!lowered.ok) {
+        // Worded as the SDK's list, not as a fault: whether a string body that reads
+        // the name really fails in the run is what #1411 has yet to establish.
+        if (lowered.free.length > 0) {
+            return keep(`it reads ${lowered.free.join(', ')}, which is not on the SDK's list of names the Flow script runtime provides.`);
+        }
+        // The body parses on its own (checked above) but not between the braces.
+        if (lowered.syntax)
+            return keep(UNCHANGED);
+        return keep(lowered.problems.join(' '));
+    }
+    if (lowered.code !== code)
+        return keep(UNCHANGED);
+    // Last, on what will actually be printed: an early error makes the module unloadable.
+    const early = scriptBodyEarlyError(code, FLOW_SCRIPT_RUNTIME);
+    if (early)
+        return keep(`as a function in an ES module (strict code) it would not load: ${early}.`);
+    ctx.declareFunction(`function ${name}($vars: ${ctx.typeHelper('FlowVars')}) {${code}}`);
+    return name;
+}
 /** Key-sorted copy, so a property map compares by content and not by order. */
 function sortKeys(o) {
     return Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
@@ -119,6 +187,9 @@ function scriptAt(version) {
             const returns = r === undefined ? undefined
                 : typeof r === 'string' ? ctx.string(r)
                     : `{ ${Object.entries(r).map(([k, t]) => `${ctx.key(k)}: ${ctx.string(String(t))}`).join(', ')} }`;
+            const fn = printAsFunction(inputs.code, ctx);
+            if (fn !== undefined)
+                return { factory: 'script', positional: [fn], options: [['returns', returns]] };
             return { factory: 'script', options: [['code', ctx.string(inputs.code)], ['returns', returns]] };
         },
         check: ({ inputs }, ctx) => checkScript(inputs, ctx),

package/dist/nodes/script/flow/runtime.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Flow script runtime, as `script(fn)` lowers for it. Not part of the public
+ * surface: `index.ts` does not re-export this file.
+ */
+import type { ScriptRuntime } from '../../../core/script-function.js';
+/**
+ * What a Flow script body can read: the language's ES2020 built-ins, `console`,
+ * and the runtime's `$vars`. From the Flow skill's `references/script.md` ("The
+ * JavaScript runtime"), which also lists what reads `undefined` in a real run and
+ * is therefore absent here: `Intl`, `URL`, `TextEncoder`, `Buffer`, `fetch`,
+ * `require`, `structuredClone`. Change this when the runtime changes.
+ *
+ * Annex B's `escape`/`unescape` are left off on purpose: they URL-encode, and
+ * `escape` is the likeliest name for an author's own HTML-escape helper, which
+ * the runtime's global would silently replace.
+ *
+ * Only `script(fn)` checks against it. A string body is not checked, until
+ * there is evidence the list is complete (#1411).
+ */
+export declare const FLOW_SCRIPT_RUNTIME: ScriptRuntime;

package/dist/nodes/script/flow/runtime.js

@@ -0,0 +1,29 @@
+/**
+ * What a Flow script body can read: the language's ES2020 built-ins, `console`,
+ * and the runtime's `$vars`. From the Flow skill's `references/script.md` ("The
+ * JavaScript runtime"), which also lists what reads `undefined` in a real run and
+ * is therefore absent here: `Intl`, `URL`, `TextEncoder`, `Buffer`, `fetch`,
+ * `require`, `structuredClone`. Change this when the runtime changes.
+ *
+ * Annex B's `escape`/`unescape` are left off on purpose: they URL-encode, and
+ * `escape` is the likeliest name for an author's own HTML-escape helper, which
+ * the runtime's global would silently replace.
+ *
+ * Only `script(fn)` checks against it. A string body is not checked, until
+ * there is evidence the list is complete (#1411).
+ */
+export const FLOW_SCRIPT_RUNTIME = {
+    scopeGlobal: '$vars',
+    name: 'the Flow script runtime',
+    globals: new Set([
+        'undefined', 'NaN', 'Infinity', 'globalThis', 'console',
+        'Object', 'Function', 'Array', 'Number', 'Boolean', 'String', 'Symbol', 'BigInt', 'Date', 'RegExp', 'Math', 'JSON',
+        'Promise', 'Proxy', 'Reflect', 'Map', 'Set', 'WeakMap', 'WeakSet',
+        'Error', 'EvalError', 'RangeError', 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError',
+        'ArrayBuffer', 'SharedArrayBuffer', 'DataView', 'Atomics',
+        'Int8Array', 'Uint8Array', 'Uint8ClampedArray', 'Int16Array', 'Uint16Array', 'Int32Array', 'Uint32Array',
+        'Float32Array', 'Float64Array', 'BigInt64Array', 'BigUint64Array',
+        'parseInt', 'parseFloat', 'isNaN', 'isFinite',
+        'encodeURI', 'encodeURIComponent', 'decodeURI', 'decodeURIComponent', 'eval',
+    ]),
+};

package/dist/nodes/script/flow/spec.d.ts

@@ -3,7 +3,7 @@
  * in `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md.
  */
-import type { ScriptReturns } from '../../../core/script-return.js';
+import type { ScriptReturns, ScriptReturnType } from '../../../core/script-return.js';
 export interface ScriptInputs {
     /** JavaScript body. Must `return` its result. Referenced via out('<step>'). */
     code: string;
@@ -42,6 +42,37 @@ export interface ScriptInputs {
      */
     returns?: ScriptReturns;
 }
+/**
+ * The runtime's variable scope, as a script function's parameter sees it.
+ *
+ * `$vars` is the Flow script runtime's own global, not something the SDK
+ * provides: the SDK never calls a script function, and `script(fn)` renames the
+ * parameter to `$vars` in the body it emits. This type is a loose name for what
+ * that global holds, so `vars.start.output.message` type-checks. Any other
+ * parameter type works too; the SDK cannot check it against the runtime.
+ *
+ * ```ts
+ * .step('parse', script(parse, { returns: { amount: 'number' } }))
+ *
+ * function parse(vars: FlowVars) {
+ *   return { amount: Number(vars.start.output.amount) };
+ * }
+ * ```
+ */
+export type FlowVars = Record<string, any>;
+/** The TypeScript type one of {@link ScriptReturnType}'s names stands for. */
+export type ScriptValueOf<T extends ScriptReturnType> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'array' ? readonly unknown[] : T extends 'object' ? object : unknown;
+/**
+ * What a script function must return for a given `returns`: the type a name
+ * stands for, or, for a field map, an object with those fields.
+ *
+ * This is how `script(fn, { returns })` makes tsc check the function against the
+ * declaration that reaches the `.flow`: `returns: { total: 'number' }` over a
+ * function that returns a string `total` does not compile.
+ */
+export type ScriptValue<R extends ScriptReturns> = R extends ScriptReturnType ? ScriptValueOf<R> : {
+    [F in keyof R]: R[F] extends ScriptReturnType ? ScriptValueOf<R[F]> : never;
+};
 declare module '../../../core/actions.js' {
     interface FlowActionSpecs {
         /** The spec {@link script} builds. */

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 {

package/dist/ref-resolve.d.ts

@@ -1,39 +1,3 @@
-/**
- * `$ref` resolution for SPLIT `.flow` files (design §5, Phase 5E).
- *
- * The format lets a `.flow` be split across sibling files with JSON Reference
- * (`{ "$ref": "./layout.json" }`) — used to sideline layout or definitions, or
- * to extract a subflow out of an oversized file
- * (`flow-schema/REF_RESOLUTION.md`, MST-8579). Decompile has to READ those, so
- * this resolves them into ONE object model before anything else looks at the
- * document.
- *
- * Compile keeps writing a single file, deliberately: nothing in the designer or
- * the skills splits files today, so write-through splitting would be a merge
- * concern with no producer to round-trip against.
- *
- * The semantics below are the platform resolver's, mirrored rather than
- * reinvented (`flow-schema/src/ref-resolver/`), because a file the platform
- * reads one way and the SDK another is worse than no support at all:
- *
- *  - **`$ref` replaces the whole object.** JSON Reference, not JSON Schema —
- *    sibling properties beside a `$ref` are dropped, not merged.
- *  - **Same-document fragments (`#/…`) are left ALONE.** They are legitimate
- *    internal pointers — a connector tool's `outputSchema` carries them — and
- *    they are not file references. Resolving them as filenames is the exact
- *    regression the platform's own guard exists to prevent.
- *  - **Relative paths only.** Absolute paths, Windows drive letters, protocol
- *    URIs and traversal above the referencing file's root are REFUSED, because
- *    a `.flow` is untrusted input and the alternative is a file-exfiltration
- *    primitive (`$ref: '/etc/passwd'`, `$ref: 'https://…'`).
- *  - **Any depth**, and resolved content is walked again for its own refs.
- *
- * Where this deliberately differs: an unresolvable ref is an ERROR here, not a
- * warning. The platform's resolver collects non-fatal errors because a canvas
- * can render a partial document and let a person fix it; decompile turns the
- * document into SOURCE, and a silently-missing subtree becomes source that
- * compiles to a different flow. Failing names the file that is missing.
- */
 /** How this module reads a sibling file. Injected so it is testable and so the
  * SDK core stays free of `node:fs`. */
 export type RefReader = (resolvedPath: string) => string;

package/dist/ref-resolve.js

@@ -34,6 +34,7 @@
  * document into SOURCE, and a silently-missing subtree becomes source that
  * compiles to a different flow. Failing names the file that is missing.
  */
+import { CompileRefusal } from './core/compile-refusal.js';
 /**
  * Collapse `.` and `..` segments, preserving a leading `/` for POSIX absolute
  * paths — the platform's `normalizePath`, same behavior.
@@ -60,13 +61,13 @@ function normalizePath(path) {
  */
 export function resolveRefPath(baseUri, refPath) {
     if (refPath.startsWith('#')) {
-        throw new Error(`$ref "${refPath}" is a same-document fragment, not a file — it must not be resolved as a path.`);
+        throw new CompileRefusal('JSON_REF_PATH_INVALID', `$ref "${refPath}" is a same-document fragment, not a file — it must not be resolved as a path.`);
     }
     if (refPath.startsWith('/') || /^[a-zA-Z]:/.test(refPath)) {
-        throw new Error(`$ref "${refPath}" is an absolute path; only relative paths are allowed.`);
+        throw new CompileRefusal('JSON_REF_PATH_INVALID', `$ref "${refPath}" is an absolute path; only relative paths are allowed.`);
     }
     if (refPath.includes('://')) {
-        throw new Error(`$ref "${refPath}" is a protocol URI; only relative file paths are allowed.`);
+        throw new CompileRefusal('JSON_REF_PATH_INVALID', `$ref "${refPath}" is a protocol URI; only relative file paths are allowed.`);
     }
     const normalizedBase = baseUri.replace(/\\/g, '/');
     const lastSlash = normalizedBase.lastIndexOf('/');
@@ -74,7 +75,7 @@ export function resolveRefPath(baseUri, refPath) {
     const resolved = normalizePath(`${baseDir}${refPath}`);
     const isAbsoluteBase = normalizedBase.startsWith('/') || /^[a-zA-Z]:\//.test(normalizedBase);
     if (!isAbsoluteBase && resolved.startsWith('..')) {
-        throw new Error(`$ref "${refPath}" escapes the project root.`);
+        throw new CompileRefusal('JSON_REF_PATH_INVALID', `$ref "${refPath}" escapes the project root.`);
     }
     return resolved;
 }
@@ -115,11 +116,11 @@ export function resolveFlowRefs(doc, options) {
             if (node.$ref.startsWith('#'))
                 return node;
             if (depth >= maxDepth) {
-                throw new Error(`$ref resolution exceeded ${maxDepth} levels at ${where} ("${node.$ref}").`);
+                throw new CompileRefusal('JSON_REF_TOO_DEEP', `$ref resolution exceeded ${maxDepth} levels at ${where} ("${node.$ref}").`);
             }
             const path = resolveRefPath(baseUri, node.$ref);
             if (visiting.has(path)) {
-                throw new Error(`Circular $ref at ${where}: "${node.$ref}" is already being resolved.`);
+                throw new CompileRefusal('JSON_REF_CIRCULAR', `Circular $ref at ${where}: "${node.$ref}" is already being resolved.`);
             }
             let text;
             try {
@@ -127,7 +128,7 @@ export function resolveFlowRefs(doc, options) {
             }
             catch (err) {
                 const why = err instanceof Error ? err.message : String(err);
-                throw new Error(`$ref at ${where} points at "${node.$ref}", which could not be read (${why}).`);
+                throw new CompileRefusal('JSON_REF_UNREADABLE', `$ref at ${where} points at "${node.$ref}", which could not be read (${why}).`);
             }
             let parsed;
             try {
@@ -135,7 +136,7 @@ export function resolveFlowRefs(doc, options) {
             }
             catch (err) {
                 const why = err instanceof Error ? err.message : String(err);
-                throw new Error(`$ref at ${where} points at "${node.$ref}", which is not valid JSON (${why}).`);
+                throw new CompileRefusal('JSON_REF_NOT_JSON', `$ref at ${where} points at "${node.$ref}", which is not valid JSON (${why}).`);
             }
             visiting.add(path);
             try {

package/dist/schema-version.d.ts

@@ -1,41 +1,3 @@
-/**
- * schema-version — the artifact's FILE-FORMAT version, as something an author
- * can declare and a decompile can PRESERVE.
- *
- * Every artifact family this SDK writes carries a version that describes the
- * DOCUMENT's grammar rather than the author's release: Flow's top-level
- * `version`, Case's top-level `version`, BPMN's `uipath:migrationVersion`. Until
- * now each family pinned exactly one value in its serializer's format profile
- * and overwrote whatever the input said, which is right for greenfield
- * authoring and wrong for the brownfield loop:
- *
- *   decompile(a 1.10 flow) -> compile -> a 1.9 flow, with nothing said.
- *
- * That silent rewrite is the hole this module closes. `.schemaVersion(v)` on
- * each builder declares the version the emitted document targets, decompile
- * emits the call so a round-trip re-declares what it read, and the serializer
- * writes what was declared instead of the pin.
- *
- * ## A declared version is a CLAIM, not a switch
- *
- * The rule that shapes this whole module is the one CASE_PARITY §3.8 states for
- * `.version()`: a document's version asserts that the whole document matches
- * that schema. An author writing `.version('30.0.0')` against the old
- * V20-emitting serializer produced an INVALID document, because the claim was
- * false. So `.schemaVersion()` accepts only versions this SDK can actually
- * write — {@link SchemaVersionPolicy.writable}, each row carrying the evidence
- * that says so — and refuses anything else rather than stamping a claim it
- * cannot back. Moving a document BETWEEN versions stays the product's job
- * (`uip maestro flow migrate`), because a hop can carry data repairs this SDK
- * has no way to reproduce.
- *
- * ## Comparing versions
- *
- * `'1.10' < '1.9'` as strings, which is exactly the wrong answer, and the same
- * trap sits in Case's `'30.0.0'` vs `'9.0.0'`. Nothing here compares version
- * strings with `<`; {@link compareSchemaVersions} splits on `.` and compares
- * segments numerically, and every gate goes through it.
- */
 /** The artifact families that carry a schema version. */
 export type ArtifactFamily = 'flow' | 'case' | 'bpmn';
 /** A version this SDK build can WRITE, with the evidence that says it can. */

package/dist/schema-version.js

@@ -36,6 +36,7 @@
  * strings with `<`; {@link compareSchemaVersions} splits on `.` and compares
  * segments numerically, and every gate goes through it.
  */
+import { CompileRefusal } from './core/compile-refusal.js';
 /** A version string the schema families use: dotted, numeric, e.g. `1.9`, `1.10`, `30.0.0`. */
 const SYNTAX = /^\d+(\.\d+)*$/;
 /** True when `value` is shaped like a schema version at all. */
@@ -52,7 +53,7 @@ export function isSchemaVersionSyntax(value) {
  */
 export function compareSchemaVersions(a, b) {
     if (!isSchemaVersionSyntax(a) || !isSchemaVersionSyntax(b)) {
-        throw new Error(`compareSchemaVersions: "${a}" / "${b}" is not a dotted-numeric schema version.`);
+        throw new Error(`internal SDK error: compareSchemaVersions: "${a}" / "${b}" is not a dotted-numeric schema version.`);
     }
     const left = a.split('.').map(Number);
     const right = b.split('.').map(Number);
@@ -134,7 +135,7 @@ export function resolveSchemaVersion(policy, requested) {
         return policy.default;
     const refusal = schemaVersionRefusal(policy, requested);
     if (refusal)
-        throw new Error(refusal);
+        throw new CompileRefusal('SCHEMA_VERSION_UNSUPPORTED', refusal);
     return requested;
 }
 export function preserveSchemaVersion(policy, declared) {