@uipath/maestro-builder-sdk 6.56.0 → 6.58.0

package/dist/serialize.js

@@ -11,6 +11,7 @@ import { LOOP_DEFAULT_VERSION, bodyUsesBreak, loopDeclaredInputs, loopHasInnerHa
 import { Expr, toExpr, SCHEDULE_PRESETS, flatNameSegmentsOf, parallelFork } from './flow-sdk.js';
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
+import { CompileRefusal } from './core/compile-refusal.js';
 import { rawNodeInputProblem, registeredRawType } from './raw-node-advice.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
 import { declaredErrorPortRefusal, definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
@@ -219,7 +220,7 @@ function scheduledVersion(inputs, explicit) {
     const cron = isQuartz(String(inputs?.every ?? ''));
     if (explicit !== undefined) {
         if (cron && explicit === '1.1') {
-            throw new Error("scheduled(): a Quartz cron expression needs the trigger's 1.2 definition, but { version: '1.1' } "
+            throw new CompileRefusal('SCHEDULE_CRON_VERSION', "scheduled(): a Quartz cron expression needs the trigger's 1.2 definition, but { version: '1.1' } "
                 + 'was requested. Drop the version or request 1.2.');
         }
         return explicit;
@@ -271,6 +272,12 @@ function scheduleInputs(inputs, nodeId) {
     };
 }
 export { CONNECTOR_INPUT_MISSING } from './core/connector-inputs.js';
+/**
+ * `DraftCode` and the table's `draft` entries are one list: this fails to
+ * type-check when a code is added to one and not the other.
+ */
+const DRAFT_CODES_AGREE = true;
+void DRAFT_CODES_AGREE;
 /**
  * `serialize`, plus the extra files the flow needs on disk beside it.
  *
@@ -356,20 +363,20 @@ function emitStickyNotes(built, scope, claimNoteId) {
         const authorId = note.id ?? `stickyNote_${i + 1}`;
         const id = authorId;
         if (taken.has(id)) {
-            throw new Error(`.stickyNotes(): id "${id}" is already a node in this flow. A sticky note is a real node, `
+            throw new CompileRefusal('STICKY_NOTE_ID_TAKEN', `.stickyNotes(): id "${id}" is already a node in this flow. A sticky note is a real node, `
                 + `so its id has to be unique — name it something else.`);
         }
         if (seen.has(id))
-            throw new Error(`.stickyNotes(): duplicate id "${id}".`);
+            throw new CompileRefusal('STICKY_NOTE_DUP_ID', `.stickyNotes(): duplicate id "${id}".`);
         seen.add(id);
         if (typeof note.content !== 'string') {
-            throw new Error(`.stickyNotes(): note "${id}" needs a string \`content\`.`);
+            throw new CompileRefusal('STICKY_NOTE_NO_CONTENT', `.stickyNotes(): note "${id}" needs a string \`content\`.`);
         }
         if (!Number.isFinite(note.x) || !Number.isFinite(note.y)) {
-            throw new Error(`.stickyNotes(): note "${id}" needs finite x/y coordinates.`);
+            throw new CompileRefusal('STICKY_NOTE_POSITION', `.stickyNotes(): note "${id}" needs finite x/y coordinates.`);
         }
         if ((note.width === undefined) !== (note.height === undefined)) {
-            throw new Error(`.stickyNotes(): note "${id}" needs both width and height, or neither.`);
+            throw new CompileRefusal('STICKY_NOTE_SIZE', `.stickyNotes(): note "${id}" needs both width and height, or neither.`);
         }
         // Node ids are one namespace over the whole file (#938): pack merges every
         // subflow into one BPMN document. The author's id is kept unless another
@@ -409,7 +416,7 @@ function applyAuthorLayout(layout, scope, where) {
             ?? scope.noteNodeId?.get(key)
             ?? (scope.nodes.some((n) => n.id === key) ? key : undefined);
         if (!id) {
-            throw new Error(`${where}.layout: "${key}" names no step or node in this flow. Layout keys are the flow's own step names (plus the trigger id and "end").`);
+            throw new CompileRefusal('LAYOUT_UNKNOWN_KEY', `${where}.layout: "${key}" names no step or node in this flow. Layout keys are the flow's own step names (plus the trigger id and "end").`);
         }
         return id;
     };
@@ -428,11 +435,11 @@ function applyAuthorLayout(layout, scope, where) {
     for (const [key, route] of Object.entries(layout.edges ?? {})) {
         const m = /^(.+?)->(.+)$/.exec(key);
         if (!m)
-            throw new Error(`${where}.layout: edge key "${key}" must be "<fromStep>-><toStep>".`);
+            throw new CompileRefusal('LAYOUT_EDGE_KEY_FORM', `${where}.layout: edge key "${key}" must be "<fromStep>-><toStep>".`);
         const [src, tgt] = [resolveId(m[1].trim()), resolveId(m[2].trim())];
         const matches = scope.edges.filter((e) => e.sourceNodeId === src && e.targetNodeId === tgt);
         if (matches.length !== 1) {
-            throw new Error(`${where}.layout: edge "${key}" matches ${matches.length} emitted edges; expected exactly 1.`);
+            throw new CompileRefusal('LAYOUT_EDGE_AMBIGUOUS', `${where}.layout: edge "${key}" matches ${matches.length} emitted edges; expected exactly 1.`);
         }
         edgesOut[matches[0].id] = {
             ...(route.waypoints ? { waypoints: withIds(route.waypoints) } : {}),
@@ -668,16 +675,16 @@ export function bundledContainerDefinition(kind, requestedVersion) {
  */
 export function resolveContributionDefinition(ref, requestedVersion, where) {
     if (!ref || typeof ref.nodeType !== 'string' || !ref.nodeType || typeof ref.version !== 'string' || !ref.version) {
-        throw new Error(`${where}: contribute() returned a DefinitionReference without an exact nodeType + version.`);
+        throw new CompileRefusal('CONTRIBUTION_INVALID', `${where}: contribute() returned a DefinitionReference without an exact nodeType + version.`);
     }
     if (requestedVersion !== undefined && ref.version !== requestedVersion) {
-        throw new Error(`${where}: the author requested version ${requestedVersion}, but contribute() returned `
+        throw new CompileRefusal('CONTRIBUTION_INVALID', `${where}: the author requested version ${requestedVersion}, but contribute() returned `
             + `${ref.nodeType}@${ref.version}. A contributor must honor the requested version or throw.`);
     }
     if (ref.source === 'bundled') {
         const def = DEFS[`${ref.nodeType}@${ref.version}`];
         if (!def) {
-            throw new Error(`${where}: no bundled definition ${ref.nodeType}@${ref.version}. Bundled references resolve `
+            throw new CompileRefusal('CONTRIBUTION_INVALID', `${where}: no bundled definition ${ref.nodeType}@${ref.version}. Bundled references resolve `
                 + `from core-definitions.json only; use a snapshot reference for definitions the SDK does not ship.`);
         }
         return def;
@@ -685,22 +692,22 @@ export function resolveContributionDefinition(ref, requestedVersion, where) {
     if (ref.source === 'snapshot') {
         const m = ref.manifest;
         if (!m || typeof m !== 'object') {
-            throw new Error(`${where}: snapshot reference carries no manifest object.`);
+            throw new CompileRefusal('CONTRIBUTION_INVALID', `${where}: snapshot reference carries no manifest object.`);
         }
         if (m.nodeType !== ref.nodeType || m.version !== ref.version) {
-            throw new Error(`${where}: snapshot manifest says ${m.nodeType}@${m.version}, but the reference says `
+            throw new CompileRefusal('CONTRIBUTION_INVALID', `${where}: snapshot manifest says ${m.nodeType}@${m.version}, but the reference says `
                 + `${ref.nodeType}@${ref.version}. A snapshot is an exact copy of a real definition.`);
         }
         if (typeof m.display?.label !== 'string' || !m.display.label) {
-            throw new Error(`${where}: snapshot manifest for ${ref.nodeType} lacks display.label — not a valid node manifest.`);
+            throw new CompileRefusal('CONTRIBUTION_INVALID', `${where}: snapshot manifest for ${ref.nodeType} lacks display.label — not a valid node manifest.`);
         }
         return m;
     }
     if (ref.source === 'library') {
-        throw new Error(`${where}: library-sourced DefinitionReference is not wired yet — it lands with the `
+        throw new CompileRefusal('CONTRIBUTION_INVALID', `${where}: library-sourced DefinitionReference is not wired yet — it lands with the `
             + `connector-tool base classes (coverage design, Phase 5). Use 'bundled' or 'snapshot'.`);
     }
-    throw new Error(`${where}: unknown DefinitionReference source "${ref.source}".`);
+    throw new CompileRefusal('CONTRIBUTION_INVALID', `${where}: unknown DefinitionReference source "${ref.source}".`);
 }
 /**
  * Whether `def` declares `port` as a forward source handle: an exact id, or a
@@ -811,7 +818,7 @@ function eventDetail(rc, sub, nodeId, opts, site) {
     const objectName = String(op.objectName ?? '');
     const noObject = genericEventObjectRefusal(rc, sub, (o) => `onEvent(…, { object: '${o}' })`);
     if (noObject)
-        throw new Error(`event node "${nodeId}": ${noObject}`);
+        throw new CompileRefusal('EVENT_GENERIC_NO_OBJECT', `event node "${nodeId}": ${noObject}`);
     // An unresolved `where` lookup is swapped for its recorded id — the id
     // `prepare --resolve` stored under the EVENT-form node type — or refused.
     // Same rule as connector inputs: emitting a placeholder for a value nobody
@@ -859,7 +866,7 @@ function eventDetail(rc, sub, nodeId, opts, site) {
         .map(([k, v]) => {
         const problem = jmesStringProblem(String(v));
         if (problem)
-            throw new Error(`event node "${nodeId}": \`where.${k}\`: ${problem}`);
+            throw new CompileRefusal('EVENT_FILTER_BACKSLASH', `event node "${nodeId}": \`where.${k}\`: ${problem}`);
         return `${k} == ${jmesString(String(v))}`;
     });
     // Each authored filter is read structurally (which operator, which value) and
@@ -867,15 +874,22 @@ function eventDetail(rc, sub, nodeId, opts, site) {
     // measured table. `check` has already refused a malformed leaf; a leaf that
     // still cannot be read here is an author error, not something to drop silently.
     const conditions = filters.map((f, i) => {
-        const { read } = readEventFilter(f);
+        const { keys, read } = readEventFilter(f);
         if (!read) {
-            throw new Error(`event node "${nodeId}": filters[${i}] must carry a field and exactly ONE operator `
+            // The code `check` gives the same leaf (`core/event-checks.ts`).
+            const field = f?.field;
+            throw new CompileRefusal(typeof field !== 'string' || field === '' ? 'EVENT_FILTER_NO_FIELD'
+                : keys.length > 1 ? 'EVENT_FILTER_MANY_OPERATORS' : 'EVENT_FILTER_NO_VALUE', `event node "${nodeId}": filters[${i}] must carry a field and exactly ONE operator `
                 + `(contains, startsWith, endsWith, equals, notEquals, lessThan, lessThanOrEqual, greaterThan, `
                 + `greaterThanOrEqual) — got ${JSON.stringify(f)}.`);
         }
+        // An ambiguous backslash first, under the code `check` gives it
+        // (`core/event-checks.ts`); `eventFilterProblem` would report it too.
         const problem = eventFilterProblem(read);
-        if (problem)
-            throw new Error(`event node "${nodeId}": filters[${i}] on \`${read.field}\`: ${problem}`);
+        const backslash = typeof read.value === 'string' && jmesStringProblem(read.value) !== undefined;
+        if (problem) {
+            throw new CompileRefusal(backslash ? 'EVENT_FILTER_BACKSLASH' : 'EVENT_FILTER_BAD_VALUE', `event node "${nodeId}": filters[${i}] on \`${read.field}\`: ${problem}`);
+        }
         return read;
     });
     const filterClauses = conditions.map((c) => `(${eventFilterJmes(c)})`);
@@ -986,7 +1000,7 @@ function eventDetail(rc, sub, nodeId, opts, site) {
  */
 function renderDeep(val, rename = NO_RENAME, rendered) {
     if (isLookupToken(val))
-        throw new Error(misplacedLookupMessage(val));
+        throw new CompileRefusal('LOOKUP_MISPLACED', misplacedLookupMessage(val));
     if (val instanceof Expr)
         return renderValue(val, rename);
     // A value `ctx.render` already rendered is the file's: a `lit`'s object is
@@ -1032,14 +1046,14 @@ function emittableGlobals(built, where, kind = 'root') {
     const shared = sharedInputsOf(built, where, kind);
     const plan = planFlowGlobals({ inputs, outputs: built.outputs, vars: [...built.vars, ...shared.autoVars] });
     if (plan.problems.length) {
-        throw new Error(`${where}: ${plan.problems.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
+        throw new CompileRefusal(plan.problems[0].code, `${where}: ${plan.problems.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
     }
     // An output the flow sets from inside gets an `inout` Variable to hold the
     // value; the End copies it into the Output (#1092, `flow-output-backing.ts`).
     const sharedOutputs = new Set(shared.targets.filter((t) => t.declaredAs === 'output').map((t) => t.name));
     const backing = planOutputBacking(built, plan.outputs, plan.vars, sharedOutputs);
     if (backing.problems.length) {
-        throw new Error(`${where}: ${backing.problems.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
+        throw new CompileRefusal(backing.problems[0].code, `${where}: ${backing.problems.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
     }
     return { ...plan, backing: backing.backing, backingReads: backing.reads };
 }
@@ -1052,14 +1066,14 @@ function sharedInputsOf(built, where, kind) {
     if (kind === 'subflow') {
         const marked = built.inputs.filter((i) => i.shared !== undefined);
         if (marked.length) {
-            throw new Error(`${where}: [SHARED_INPUT_IN_SUBFLOW] input "${marked[0].name}" has { shared: "${marked[0].shared}" }, but a subflow `
+            throw new CompileRefusal('SHARED_INPUT_IN_SUBFLOW', `${where}: [SHARED_INPUT_IN_SUBFLOW] input "${marked[0].name}" has { shared: "${marked[0].shared}" }, but a subflow `
                 + `has one root — its caller — so there is nothing to merge. Read the input with input('${marked[0].name}').`);
         }
     }
     const plan = planSharedInputs({ roots: sharedInputRoots(built), outputs: built.outputs, vars: built.vars });
     const errors = plan.problems.filter((p) => p.level === 'error');
     if (errors.length)
-        throw new Error(`${where}: ${errors.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
+        throw new CompileRefusal(errors[0].code, `${where}: ${errors.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
     return plan;
 }
 function newScope(outputs, vars = [], backing = new Map(), backingReads = backing) {
@@ -1138,7 +1152,7 @@ function resolveRejoins(scope, addEdge) {
         const id = scope.stepNodeId.get(target) ?? scope.endNodeId.get(target);
         if (!id) {
             const ends = [...scope.endNodeId.keys()];
-            throw new Error(`.stepToRef('${target}') names a step this flow does not have. Known steps: `
+            throw new CompileRefusal('REF_UNKNOWN_TARGET', `.stepToRef('${target}') names a step this flow does not have. Known steps: `
                 + `${[...scope.stepNodeId.keys()].join(', ') || '(none)'}`
                 + `${ends.length ? `; named Ends: ${ends.join(', ')}` : ''}.`);
         }
@@ -1309,7 +1323,7 @@ function jsonSchemaForType(type) {
         case 'jsonSchema': return {};
         default: {
             const unmapped = type;
-            throw new Error(`jsonSchemaForType: no agent schema mapping for type '${String(unmapped)}'`);
+            throw new Error(`internal SDK error: jsonSchemaForType: no agent schema mapping for type '${String(unmapped)}'`);
         }
     }
 }
@@ -1522,6 +1536,11 @@ export function serialize(built, opts = {}) {
      * "Node type `core.datafabric.read:1.4` has no matching definition".
      */
     const emittedDefs = new Map();
+    /**
+     * The nodes a draft compile emitted unbound (their `BINDING_MISSING` finding):
+     * they write no binding rows by design, so the placeholder check exempts them.
+     */
+    const unboundDrafts = new Set();
     /**
      * RESOURCE bindings collected while emitting, keyed by binding id — `resource:
      * 'process'` for the rpa family, `resource: 'queue'` for the queue family.
@@ -1558,11 +1577,11 @@ export function serialize(built, opts = {}) {
     function refuseErrorEdgeWithoutPort(nodeId, stepName) {
         const declared = declaredErrorPorts.get(nodeId);
         if (declared?.port === false)
-            throw new Error(declaredErrorPortRefusal(stepName, declared.typeName, declared.version));
+            throw new CompileRefusal('ONERROR_NO_ERROR_PORT', declaredErrorPortRefusal(stepName, declared.typeName, declared.version));
         const contributed = contributionDefs.get(nodeId);
         const def = contributed ?? bundledNodeDefs.get(nodeId);
         if (def !== undefined && !definitionHasErrorPort(def)) {
-            throw new Error(errorPortRefusal(stepName, def, { bundled: contributed === undefined }));
+            throw new CompileRefusal('ONERROR_NO_ERROR_PORT', errorPortRefusal(stepName, def, { bundled: contributed === undefined }));
         }
     }
     /**
@@ -1639,8 +1658,8 @@ export function serialize(built, opts = {}) {
         const earlier = sidecars.find((f) => f.path === file.path);
         if (earlier !== undefined && JSON.stringify(earlier.json) !== JSON.stringify(file.json)
             && (explicitSource || explicitSidecars.has(file.path))) {
-            throw Object.assign(new Error(`two resources would both write "${file.path}" with different content, so the second would replace the first. `
-                + 'Give each resource its own `source`, or omit `source` to derive one.'), { code: 'INLINE_AGENT_RESOURCE_SOURCE_DUP' });
+            throw new CompileRefusal('INLINE_AGENT_RESOURCE_SOURCE_DUP', `two resources would both write "${file.path}" with different content, so the second would replace the first. `
+                + 'Give each resource its own `source`, or omit `source` to derive one.');
         }
         if (explicitSource)
             explicitSidecars.add(file.path);
@@ -1735,7 +1754,7 @@ export function serialize(built, opts = {}) {
             const id = safeNodeId(name);
             const end = endIds.get(id);
             if (end !== undefined) {
-                throw new Error(end === name
+                throw new CompileRefusal('DUP_END_NAME', end === name
                     ? `${where}: [DUP_END_NAME] Two .return({}, { name: '${name}' }) calls ask for the same End with different `
                         + `values, label, version or updates. To end several `
                         + `paths at one End, keep one .return and end the others with .stepToRef('${name}'); to have separate Ends, `
@@ -1745,7 +1764,7 @@ export function serialize(built, opts = {}) {
             }
             const step = stepIds.get(id);
             if (step !== undefined || reserved.includes(id)) {
-                throw new Error(`${where}: [STEP_ID_COLLISION] End "${name}" (.return({}, { name: '${name}' })) has the node id "${id}" of `
+                throw new CompileRefusal('STEP_ID_COLLISION', `${where}: [STEP_ID_COLLISION] End "${name}" (.return({}, { name: '${name}' })) has the node id "${id}" of `
                     + `${step !== undefined ? `step "${step}"` : 'the trigger or an entry point'}, and compile will not rename it "${id}2". `
                     + 'Give the End a name no step or trigger uses.');
             }
@@ -1753,7 +1772,7 @@ export function serialize(built, opts = {}) {
         }
         for (const [id, name] of endIds) {
             if (!copyPrefix && takenIds.has(id)) {
-                throw new Error(`${where}: End "${name}" has node id "${id}", which another node already holds (internal: claimEndIds ran late).`);
+                throw new Error(`internal SDK error: ${where}: End "${name}" has node id "${id}", which another node already holds (claimEndIds ran late).`);
             }
             scope.endNodeId.set(name, claimId(copyPrefix + id));
         }
@@ -1789,7 +1808,7 @@ export function serialize(built, opts = {}) {
                 // two Terminates -> end the other paths at one; a step and a Terminate
                 // -> rename one.
                 const t = first === n ? (terminates.get(n) ?? 0) : 0;
-                throw new Error(first !== n
+                throw new CompileRefusal(first !== n ? 'STEP_ID_COLLISION' : 'DUP_STEP', first !== n
                     ? `${where}: [STEP_ID_COLLISION] steps "${first}" and "${n}" would both get node id "${safe}". Give them `
                         + 'names that differ in letters, digits or "_".'
                     : t >= 2 ? `${where}: [DUP_STEP] ${terminateTwiceMessage(n)}`
@@ -1804,7 +1823,7 @@ export function serialize(built, opts = {}) {
         const prefix = copyPrefix !== undefined && [...seen.keys(), ...alsoIds].some((id) => takenIds.has(id)) ? copyPrefix : '';
         for (const [safe, n] of seen) {
             if (!prefix && takenIds.has(safe)) {
-                throw new Error(`${where}: [STEP_ID_COLLISION] step "${n}" has the trigger's node id "${safe}", and compile will not `
+                throw new CompileRefusal('STEP_ID_COLLISION', `${where}: [STEP_ID_COLLISION] step "${n}" has the trigger's node id "${safe}", and compile will not `
                     + `rename it "${safe}2". Rename the step.`);
             }
             const id = claimId(prefix + safe);
@@ -1825,9 +1844,9 @@ export function serialize(built, opts = {}) {
         if (nodeId === undefined)
             return uid(scope, derivedBase);
         if (nodeId.trim() === '' || takenIds.has(nodeId)) {
-            throw Object.assign(new Error(`${where}: \`nodeId\` ${JSON.stringify(nodeId)} `
+            throw new CompileRefusal('INLINE_AGENT_RESOURCE_NODE_ID', `${where}: \`nodeId\` ${JSON.stringify(nodeId)} `
                 + (nodeId.trim() === '' ? 'is blank.' : 'is already the id of another node in this flow.')
-                + ' Give the resource node an id no other node has, or omit `nodeId` to derive one.'), { code: 'INLINE_AGENT_RESOURCE_NODE_ID' });
+                + ' Give the resource node an id no other node has, or omit `nodeId` to derive one.');
         }
         takenIds.add(nodeId);
         return nodeId;
@@ -1845,11 +1864,11 @@ export function serialize(built, opts = {}) {
         // Unreachable after `claimStepIds`, which refuses a repeated name first;
         // kept so no future emission path can bring back the silent `<name>2`.
         if (scope.stepNodeId.has(stepName)) {
-            throw new Error(`step "${stepName}" is emitted twice in one scope (internal: DUP_STEP reached stepUid).`);
+            throw new Error(`internal SDK error: step "${stepName}" is emitted twice in one scope (DUP_STEP reached stepUid).`);
         }
         const id = scope.pending.get(stepName);
         if (id === undefined) {
-            throw new Error(`step "${stepName}" has no claimed node id (internal: stepNamesOf missed a step kind).`);
+            throw new Error(`internal SDK error: step "${stepName}" has no claimed node id (stepNamesOf missed a step kind).`);
         }
         scope.pending.delete(stepName);
         scope.stepNodeId.set(stepName, id);
@@ -1886,7 +1905,7 @@ export function serialize(built, opts = {}) {
         const hitlNode = hitlNodes.get(from.node);
         const refused = hitlNode ? hitlExitViolation(hitlNode, from.port, legacyCompletedNodes.has(from.node)) : undefined;
         if (refused)
-            throw new Error(`serialize: ${refused}`);
+            throw new CompileRefusal(refused.code, `serialize: ${refused.message}`);
         scope.edges.push({ id: `edge_${edgeSeq++}`, sourceNodeId: from.node, sourcePort: from.port, targetNodeId: toNode, targetPort: toPort });
     }
     let col = 0;
@@ -1914,7 +1933,7 @@ export function serialize(built, opts = {}) {
                 const known = o.def ? [] : [...bundledVersions(type), ...carriedVersions];
                 const resolvable = known.length > 0 ? known
                     : [def?.version].filter((v) => typeof v === 'string');
-                throw new Error(`"${label ?? id}" requests ${type}@${o.requestedVersion}, but this SDK resolves only `
+                throw new CompileRefusal('NODE_VERSION_UNREGISTERED', `"${label ?? id}" requests ${type}@${o.requestedVersion}, but this SDK resolves only `
                     + `${type}@${resolvable.join(', ') || '<none>'}. Versions are exact — omit { version } to use `
                     + `the pinned default, request a version this SDK ships, or carry that version's definition `
                     + `(the .flow file's definitions[] entry) with .definitions([...]).`);
@@ -2088,7 +2107,7 @@ export function serialize(built, opts = {}) {
     const eventTriggerRc = built.trigger?.kind === 'event'
         ? (() => {
             if (!opts.library)
-                throw new Error(`onEvent() needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+                throw new CompileRefusal('LIBRARY_REQUIRED', `onEvent() needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
             const sub = built.trigger.subscription;
             const rc = opts.library.resolveEvent('trigger', sub.connector, sub.event, sub.version, sub.object);
             refuseUnverifiedByoa(opts, 'trigger', sub);
@@ -2207,13 +2226,13 @@ export function serialize(built, opts = {}) {
         // own import), whose RawNode predates the check.
         const connectorRefusal = connectorRawNodeRefusal(def.nodeType);
         if (connectorRefusal)
-            throw new Error(`${where}: ${connectorRefusal}`);
+            throw new CompileRefusal('RAW_NODE_CONNECTOR', `${where}: ${connectorRefusal}`);
         // An input a registered node type never reads (a Data Fabric `_sortOptions`)
         // is refused for every contribution, whichever class or SDK copy made it:
         // `validate` cannot see it, and the node would ignore it at run time.
         const unknownInput = rawNodeInputProblem(def.nodeType, def.version, contribution.inputs);
         if (unknownInput?.severity === 'error')
-            throw new Error(`${where}: ${unknownInput.message}`);
+            throw new CompileRefusal('RAW_NODE_UNKNOWN_INPUT', `${where}: ${unknownInput.message}`);
         const id = stepUid(scope, stepName);
         contributionDefs.set(id, def);
         return placeStepNode({ where, stepName, id, typeName: def.nodeType, requestedVersion, def, contribution, tails, scope, parentId });
@@ -2362,7 +2381,11 @@ export function serialize(built, opts = {}) {
                 return out !== null && typeof out === 'object' ? fileCopy(out) : out;
             },
             drafting: opts.draft !== undefined,
-            draft: (code, message) => opts.draft?.({ nodeId: id, code: code, message }),
+            draft: (code, message) => {
+                if (code === 'BINDING_MISSING')
+                    unboundDrafts.add(id);
+                opts.draft?.({ nodeId: id, code: code, message });
+            },
         };
         const bound = [];
         const contribution = impl.serialize(spec, ctx);
@@ -2478,7 +2501,7 @@ export function serialize(built, opts = {}) {
             // keys and matching expression rewrites. Keep the collision check as an
             // invariant backstop: an overwrite here would drop a complete body.
             if (subflows[id]) {
-                throw new Error(`subflow "${id}": internal id allocation collision; two subflow steps claimed the same body slot.`);
+                throw new Error(`internal SDK error: subflow "${id}": id allocation collision; two subflow steps claimed the same body slot.`);
             }
             const node = makeNode(NODE_TYPE.subflow, id, step.name, { parentId, requestedVersion: step.options?.version });
             // Inputs are keyed by the CHILD's input names — that is the whole
@@ -2497,7 +2520,7 @@ export function serialize(built, opts = {}) {
         }
         if (spec.kind === 'waitEvent') {
             if (!opts.library)
-                throw new Error(`waitForEvent "${step.name}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+                throw new CompileRefusal('LIBRARY_REQUIRED', `waitForEvent "${step.name}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
             const sub = spec.subscription;
             const rc = opts.library.resolveEvent('event', sub.connector, sub.event, sub.version, sub.object);
             refuseUnverifiedByoa(opts, `waitForEvent "${step.name}"`, sub);
@@ -2527,9 +2550,9 @@ export function serialize(built, opts = {}) {
             if (maybeCustom instanceof FlowAction) {
                 return emitContribution(maybeCustom, step.name, step.options?.version, tails, scope, parentId);
             }
-            throw new Error(`step "${step.name}": not an action spec — pass a factory result, subflow(), or a FlowAction subclass instance.`);
+            throw new CompileRefusal('STEP_NOT_ACTION', `step "${step.name}": not an action spec — pass a factory result, subflow(), or a FlowAction subclass instance.`);
         }
-        throw new Error(`step "${step.name}": unknown action kind "${spec.kind}".`);
+        throw new CompileRefusal('STEP_NOT_ACTION', `step "${step.name}": unknown action kind "${spec.kind}".`);
     }
     /**
      * Wire a step's `.onError(...)` handler — the edge out of the node's `error`
@@ -2580,7 +2603,11 @@ export function serialize(built, opts = {}) {
         const node = tails[0]?.node ?? '';
         if (!(hitlNodes.has(node) || legacyCompletedNodes.has(node)) || !tails.some((t) => t.port === port))
             return;
-        throw new Error(tails.length > 1
+        // Two conditions, two codes. Several tails: the task does not route per
+        // outcome, which is check's HITL_OUTCOME_PORTS_OFF. One tail: that port
+        // already continues the main path (a routed task's primary outcome, or a
+        // legacyCompleted task's `completed`), and outcomePorts would not help.
+        throw new CompileRefusal(tails.length > 1 ? 'HITL_OUTCOME_PORTS_OFF' : 'HITL_PORT_ALREADY_WIRED', tails.length > 1
             ? `${method}('${port}', …) after human task "${source}": every outcome already continues to the next `
                 + `step, '${port}' included, because this task does not route per outcome. Add outcomePorts: true `
                 + `(the first outcome then continues and the others are routed), or route every outcome with .stepSwitch.`
@@ -2606,13 +2633,13 @@ export function serialize(built, opts = {}) {
         // from the SAME node. Tails from two nodes mean a new action shape reached
         // here without being taught about side exits; say so rather than guess.
         if (tails.length === 0 || tails.some((t) => t.node !== tails[0].node)) {
-            throw new Error(`.stepToList('${step.port}', …) after step "${source}": expected the step to leave from exactly one node, got ${tails.length} tail(s).`);
+            throw new Error(`internal SDK error: .stepToList('${step.port}', …) after step "${source}": expected the step to leave from exactly one node, got ${tails.length} tail(s).`);
         }
         refuseRewire('.stepToList', step.port, source, tails);
         const nodeId = tails[0].node;
         const node = scope.nodes.find((n) => n.id === nodeId);
         if (!node)
-            throw new Error(`.stepToList('${step.port}', …) after step "${source}": emitted node "${nodeId}" not found in scope`);
+            throw new Error(`internal SDK error: .stepToList('${step.port}', …) after step "${source}": emitted node "${nodeId}" not found in scope`);
         // Only the error port carries this: without it the platform routes but Studio
         // Web HIDES the handle, so no human can see the handler.
         if (step.port === 'error') {
@@ -2646,7 +2673,7 @@ export function serialize(built, opts = {}) {
                 return;
             const nodeId = scope.stepNodeId.get(step.name);
             if (!nodeId)
-                throw new Error(`updates on "${step.name}": emitted node not found.`);
+                throw new Error(`internal SDK error: updates on "${step.name}": emitted node not found.`);
             scope.variableUpdates[nodeId] = [
                 ...(scope.variableUpdates[nodeId] ?? []),
                 ...renderUpdates(updates, scope.rename),
@@ -2674,7 +2701,7 @@ export function serialize(built, opts = {}) {
             const nodeId = scope.stepNodeId.get(step.name);
             const node = nodeId ? scope.nodes.find((n) => n.id === nodeId) : undefined;
             if (!node)
-                throw new Error(`label on "${step.name}": emitted node not found.`);
+                throw new Error(`internal SDK error: label on "${step.name}": emitted node not found.`);
             node.display = { ...(node.display ?? {}), label };
         };
         for (const [stepIndex, step] of steps.entries()) {
@@ -2682,7 +2709,7 @@ export function serialize(built, opts = {}) {
             // follow: nothing continues from it, so a step here would hang off no edge.
             const router = lastAction !== undefined && tails.length === 0 ? routerNodes.get(lastAction) : undefined;
             if (router !== undefined && step.kind !== 'stepToList' && step.kind !== 'stepToRef') {
-                throw new Error(`step "${lastAction}": its definition declares only templated exits (such as case-{item.id}), so no `
+                throw new CompileRefusal('TEMPLATED_EXITS_ONLY', `step "${lastAction}": its definition declares only templated exits (such as case-{item.id}), so no `
                     + `path continues from it and ${'name' in step ? `"${step.name}"` : `.${step.kind}()`} after it would `
                     + `have no incoming edge. Route each exit with .stepToList('<port>', …), e.g. .stepToList('case-<id>', …).`);
             }
@@ -2725,7 +2752,7 @@ export function serialize(built, opts = {}) {
                 // discover it has one port. `stepExits` carries the reason.
                 const exits = stepExits(step.spec, step.options?.version);
                 if (!hasExits(exits)) {
-                    throw new Error(`.stepSwitch("${step.name}"): ${exits.reason}, so there are no exits to route.`
+                    throw new CompileRefusal('STEP_SWITCH_NO_EXITS', `.stepSwitch("${step.name}"): ${exits.reason}, so there are no exits to route.`
                         + (exits.suggestion ? ` ${exits.suggestion}` : ''));
                 }
                 const action = {
@@ -2741,7 +2768,7 @@ export function serialize(built, opts = {}) {
                 applyLabel(action);
                 const nodeId = scope.stepNodeId.get(step.name);
                 if (!nodeId)
-                    throw new Error(`.stepSwitch("${step.name}"): emitted node not found.`);
+                    throw new Error(`internal SDK error: .stepSwitch("${step.name}"): emitted node not found.`);
                 const armTails = [];
                 const routed = new Set();
                 // Outcomes of a human task whose path stops at an End: an arm that ends
@@ -2750,7 +2777,7 @@ export function serialize(built, opts = {}) {
                 for (const c of step.cases) {
                     const exit = exits.find((e) => e.value === c.value);
                     if (!exit) {
-                        throw new Error(`.stepSwitch("${step.name}"): no exit named ${JSON.stringify(c.value)}. `
+                        throw new CompileRefusal('STEP_SWITCH_EXIT_UNKNOWN', `.stepSwitch("${step.name}"): no exit named ${JSON.stringify(c.value)}. `
                             + `It declares ${exits.map((e) => JSON.stringify(e.value)).join(', ')}.`);
                     }
                     routed.add(exit.port);
@@ -2886,7 +2913,7 @@ export function serialize(built, opts = {}) {
                     // fan-out task's outcomes — must not both enter it: only one fires
                     // and the arms never start. Fails closed, as the join does.
                     if (tails.length > 1) {
-                        throw new Error(`.parallel("${step.name}"): its fork "${fork.name}" would receive ${tails.length} alternative edges `
+                        throw new CompileRefusal('PARALLEL_FORK_ALTERNATIVES', `.parallel("${step.name}"): its fork "${fork.name}" would receive ${tails.length} alternative edges `
                             + `(${tails.map((t) => `${t.node}@${t.port}`).join(', ')}), and only one of them fires while the gateway `
                             + `waits for all of them. Add a step before the .parallel so the paths meet there first, or drop { fork }.`);
                     }
@@ -2915,13 +2942,13 @@ export function serialize(built, opts = {}) {
                     // edge per arm, and still only one arm runs.
                     const switchTail = outcomeTail ? undefined : t.find((x) => x.humanSwitch !== undefined);
                     if (t.length >= 2 && switchTail) {
-                        throw new Error(`.parallel("${step.name}"): an arm sends ${t.length} alternative edges into join "${step.name}" — `
+                        throw new CompileRefusal('HITL_FAN_OUT_INTO_JOIN', `.parallel("${step.name}"): an arm sends ${t.length} alternative edges into join "${step.name}" — `
                             + `among them the end of an arm of human task "${switchTail.humanSwitch}"'s .stepSwitch — and only one `
                             + `of them fires, while the join waits for all of them. Add a step at the end of the arm, after the `
                             + `.stepSwitch, so its arms meet there first, or move the task out of the .parallel.`);
                     }
                     if (t.length >= 2 && outcomeTail) {
-                        throw new Error(`.parallel("${step.name}"): an arm sends ${t.length} alternative edges into join "${step.name}" — `
+                        throw new CompileRefusal('HITL_FAN_OUT_INTO_JOIN', `.parallel("${step.name}"): an arm sends ${t.length} alternative edges into join "${step.name}" — `
                             + `among them outcome edge "${outcomeTail.port}" of human task "${outcomeTail.node}" — and only one `
                             + `of them fires, while the join waits for all of them. Add a step at the end of the arm so its paths `
                             + `meet there first, or move the task out of the .parallel.`);
@@ -2930,7 +2957,7 @@ export function serialize(built, opts = {}) {
                 }
                 const starved = hitlEndExits.slice(endsBefore).find((x) => x.scope === scope && x.parentId === parentId);
                 if (starved && armTails.length > 0) {
-                    throw new Error(`.parallel("${step.name}"): human task "${starved.step}" ${starved.why} inside an arm, and join `
+                    throw new CompileRefusal('HITL_END_OUTCOME_IN_PARALLEL', `.parallel("${step.name}"): human task "${starved.step}" ${starved.why} inside an arm, and join `
                         + `"${step.name}" would wait forever for the path that continues. Give every outcome a path that `
                         + `continues to the end of the arm (drop action: 'End', add the missing .stepSwitch arm, move the `
                         + `.return() after the .parallel), or move the task out of the .parallel.`);
@@ -2974,7 +3001,7 @@ export function serialize(built, opts = {}) {
                 const loopDef = definitionFor(NODE_TYPE.loop, version);
                 const refusal = loopVersionRefusal(step.name, o, usesBreak, loopDef);
                 if (refusal)
-                    throw new Error(refusal);
+                    throw new CompileRefusal('LOOP_VERSION_UNSUPPORTED', refusal);
                 const v24 = loopHasInnerHandles(version, loopDef);
                 const declared = loopDeclaredInputs(loopDef);
                 const id = stepUid(scope, step.name);
@@ -3019,7 +3046,7 @@ export function serialize(built, opts = {}) {
             }
             else if (step.kind === 'break') {
                 if (!loopExits?.break) {
-                    throw new Error('.break() has no enclosing .loop()/.doWhile() body to exit — it is only valid inside a container.');
+                    throw new CompileRefusal('BREAK_OUTSIDE_LOOP', '.break() has no enclosing .loop()/.doWhile() body to exit — it is only valid inside a container.');
                 }
                 for (const t of tails)
                     addEdge(scope, t, loopExits.node, loopExits.break);
@@ -3030,7 +3057,7 @@ export function serialize(built, opts = {}) {
                 // to — so a handler or an arm can go on to the next iteration instead of
                 // ending the run on an End of its own (#1129).
                 if (!loopExits) {
-                    throw new Error('.continue() has no enclosing .loop()/.doWhile() body to go back to — it is only valid inside a container.');
+                    throw new CompileRefusal('CONTINUE_OUTSIDE_LOOP', '.continue() has no enclosing .loop()/.doWhile() body to go back to — it is only valid inside a container.');
                 }
                 for (const t of tails)
                     addEdge(scope, t, loopExits.node, loopExits.continue);
@@ -3051,7 +3078,7 @@ export function serialize(built, opts = {}) {
                 // The remedy depends on what holds the name: another Terminate (end the
                 // other paths at it) or a step of another kind (rename one).
                 if (scope.stepNodeId.has(step.name)) {
-                    throw new Error(terminateNames.get(scope)?.has(step.name)
+                    throw new CompileRefusal('DUP_STEP', terminateNames.get(scope)?.has(step.name)
                         ? terminateTwiceMessage(step.name)
                         : terminateStepClashMessage(step.name));
                 }
@@ -3088,7 +3115,7 @@ export function serialize(built, opts = {}) {
                     const router = tails.length === 0 && lastAction !== undefined ? routerNodes.get(lastAction) : undefined;
                     const from = tails[0] ?? (router !== undefined ? { node: router, port: step.port } : undefined);
                     if (!from)
-                        throw new Error(`.stepToRef('${step.port}', '${step.target}') has no step to leave from.`);
+                        throw new Error(`internal SDK error: .stepToRef('${step.port}', '${step.target}') has no step to leave from.`);
                     refuseRewire('.stepToRef', step.port, lastAction ?? '?', tails);
                     if (step.port === 'error') {
                         refuseErrorEdgeWithoutPort(from.node, lastAction ?? from.node);
@@ -3121,7 +3148,7 @@ export function serialize(built, opts = {}) {
                 const extra = step.options?.updates ?? {};
                 for (const name of Object.keys(extra)) {
                     if (name in step.values) {
-                        throw new Error(`.return(): "${name}" appears both as a returned value and in { updates } — one write per variable.`);
+                        throw new CompileRefusal('RETURN_UPDATES_SAME_VAR', `.return(): "${name}" appears both as a returned value and in { updates } — one write per variable.`);
                     }
                 }
                 updates.push(...renderUpdates(extra, scope.rename));
@@ -3142,7 +3169,7 @@ export function serialize(built, opts = {}) {
                     // (#1231). `check` reports it first as DUP_END_NAME; this is the
                     // backstop for `--no-check`.
                     if (prior) {
-                        throw new Error(`Two .return({}, { name: '${name}' }) calls ask for the same End with different values, label, version, updates or scope. `
+                        throw new CompileRefusal('DUP_END_NAME', `Two .return({}, { name: '${name}' }) calls ask for the same End with different values, label, version, updates or scope. `
                             + `To end several paths at one End, keep one .return and end the others with .stepToRef('${name}'); `
                             + `to have separate Ends, give each its own name.`);
                     }
@@ -3150,7 +3177,7 @@ export function serialize(built, opts = {}) {
                     // `claimEndIds` (#1253); only an unnamed End's id is the SDK's to make up.
                     const id = name === undefined ? uid(scope, 'end') : scope.endNodeId.get(name);
                     if (id === undefined) {
-                        throw new Error(`End "${name}" has no claimed node id (internal: namedNodesOf missed a step kind).`);
+                        throw new Error(`internal SDK error: End "${name}" has no claimed node id (namedNodesOf missed a step kind).`);
                     }
                     emitEnd(scope, id, tails, { label: step.options?.label, parentId, requestedVersion: step.options?.version, explicit });
                     if (updates.length)
@@ -3205,7 +3232,7 @@ export function serialize(built, opts = {}) {
         const sharedTarget = firstShared && 'name' in firstShared ? root.stepNodeId.get(firstShared.name) : undefined;
         for (const ep of entryPoints) {
             if (takenIds.has(ep.id)) {
-                throw new Error(`.entryPoint("${ep.id}"): the id collides with a step, the trigger, or another entry point.`);
+                throw new CompileRefusal('ENTRY_POINT_DUP_ID', `.entryPoint("${ep.id}"): the id collides with a step, the trigger, or another entry point.`);
             }
             takenIds.add(ep.id);
             const spec = ep.trigger;
@@ -3227,7 +3254,7 @@ export function serialize(built, opts = {}) {
             }
             else if (epSpec.kind === 'event') {
                 if (!opts.library)
-                    throw new Error(`onEvent() needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+                    throw new CompileRefusal('LIBRARY_REQUIRED', `onEvent() needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
                 const sub = epSpec.subscription;
                 const rc = opts.library.resolveEvent('trigger', sub.connector, sub.event, sub.version, sub.object);
                 refuseUnverifiedByoa(opts, 'trigger', sub);
@@ -3274,13 +3301,13 @@ export function serialize(built, opts = {}) {
                 node.inputs = { entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`) };
             }
             else {
-                throw new Error(`.entryPoint("${ep.id}"): unsupported trigger kind ${JSON.stringify(epSpec.kind)}.`);
+                throw new CompileRefusal('TRIGGER_UNKNOWN_KIND', `.entryPoint("${ep.id}"): unsupported trigger kind ${JSON.stringify(epSpec.kind)}.`);
             }
             root.nodes.push(node);
             const prefixTails = emit(ep.steps, [{ node: ep.id, port: 'output' }], root);
             for (const t of prefixTails) {
                 if (!sharedTarget) {
-                    throw new Error(`.entryPoint("${ep.id}") runs into the shared body, but the flow has no shared step to join. `
+                    throw new CompileRefusal('ENTRY_POINT_NO_SHARED_BODY', `.entryPoint("${ep.id}") runs into the shared body, but the flow has no shared step to join. `
                         + `End the prefix terminally (.return()/.terminate()) or add a shared step.`);
                 }
                 addEdge(root, t, sharedTarget);
@@ -3366,7 +3393,7 @@ export function serialize(built, opts = {}) {
     // Emitted-document invariants over connections, checked on the FINISHED file
     // so every family and every emission order is covered by one rule, not by
     // each call site remembering it (flow-builder-sdk#865/#866).
-    assertBindingPlaceholdersResolve(flow);
+    assertBindingPlaceholdersResolve(flow, unboundDrafts);
     assertFileWideIdsUnique(flow);
     assertConnectorConfigurationRestorable(flow);
     connectionConnectors(flow);
@@ -3413,7 +3440,7 @@ export function assertConnectorConfigurationRestorable(flow) {
             broken.push(node.id);
     }
     if (broken.length) {
-        throw new Error(`serialize: connector configuration on ${broken.map((id) => `"${id}"`).join(', ')} has a non-empty `
+        throw new Error(`internal SDK error: serialize: connector configuration on ${broken.map((id) => `"${id}"`).join(', ')} has a non-empty `
             + `optionalConfiguration without a fieldsContainer. Studio Web shows such a node's fields empty and a `
             + `save drops its bodyParameters (flow-builder-sdk#936). Emit { essentialConfiguration } only.`);
     }
@@ -3449,7 +3476,7 @@ export function assertFileWideIdsUnique(flow) {
         }
     }
     if (dupes.length) {
-        throw new Error(`serialize: ids must be unique across the root and all subflows; duplicated: ${dupes.join('; ')}.`);
+        throw new Error(`internal SDK error: serialize: ids must be unique across the root and all subflows; duplicated: ${dupes.join('; ')}.`);
     }
 }
 /**
@@ -3474,12 +3501,15 @@ export function assertFileWideIdsUnique(flow) {
  * 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 function assertBindingPlaceholdersResolve(flow) {
+export function assertBindingPlaceholdersResolve(flow, unbound = new Set()) {
     const bindings = Array.isArray(flow?.bindings) ? flow.bindings : [];
     const defs = new Map();
     for (const def of Array.isArray(flow?.definitions) ? flow.definitions : []) {
@@ -3498,6 +3528,8 @@ export function assertBindingPlaceholdersResolve(flow) {
         // deployed corpus carries no flow `bindings[]` entry for them.
         if (typeof node?.type !== 'string' || node.type.startsWith('uipath.agent.resource.'))
             continue;
+        if (unbound.has(node.id))
+            continue;
         const model = defs.get(`${node.type}@${node.typeVersion}`)?.model;
         if (!Array.isArray(model?.context))
             continue;