@uipath/maestro-builder-sdk 6.57.0 → 6.58.1

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 {

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) {

package/dist/sdk-resolve.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { register } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { PACKAGE_NAME } from './package-name.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 let registered = false;
 /**
  * Make `import … from '@uipath/maestro-builder-sdk'` in authored source resolve
@@ -25,7 +26,7 @@ export function useThisSdkForAuthoredSource() {
             registered = true;
             return;
         }
-        throw new Error(`cannot point authored source at this copy of ${PACKAGE_NAME}: ${fileURLToPath(hook)} is missing, as in a bundle, `
+        throw new CompileRefusal('SDK_RESOLVE_HOOK_MISSING', `cannot point authored source at this copy of ${PACKAGE_NAME}: ${fileURLToPath(hook)} is missing, as in a bundle, `
             + 'so its imports would load a second copy and serialize wrong. Run the installed package, or load authored source yourself.');
     }
     register(hook);

package/dist/serialize.d.ts

@@ -188,9 +188,12 @@ export declare function assertFileWideIdsUnique(flow: any): void;
  * It holds for real definitions: of the 5,102 in the local registry index
  * (2026-09-30), 4,999 reference a `<bindings.…>` name and every one of them
  * declares that name in `model.bindings.values`, which is what the emitters
- * close. Agent resource definitions are the one exemption (see below).
+ * close. Agent resource definitions are one exemption (see below); `unbound`,
+ * the nodes a draft compile reported as `BINDING_MISSING`, is the other: such a
+ * node names no connection, so it writes no binding rows, and the draft finding
+ * already says so.
  *
  * @throws BindingRefusal `BINDING_PLACEHOLDER_UNRESOLVED`, naming each dangling
  * placeholder and the step that carries it.
  */
-export declare function assertBindingPlaceholdersResolve(flow: any): void;
+export declare function assertBindingPlaceholdersResolve(flow: any, unbound?: ReadonlySet<string>): void;