@uipath/maestro-builder-sdk 6.57.0 → 6.58.0

package/dist/case/subscription.d.ts

@@ -10,12 +10,14 @@
  */
 import type { EventSubscription } from '../core/actions.js';
 import type { Library, ResolvedConnector } from '../core/library.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 import type { BindingsView } from '../core/binding-messages.js';
 /** Check's code for {@link GenericEventNoObjectError}; Flow and BPMN `check` use the same one. */
 export declare const EVENT_GENERIC_NO_OBJECT = "EVENT_GENERIC_NO_OBJECT";
 /** A GENERIC event subscription that names no object. */
-export declare class GenericEventNoObjectError extends Error {
-    readonly code = "EVENT_GENERIC_NO_OBJECT";
+export declare class GenericEventNoObjectError extends CompileRefusal {
+    readonly code: typeof EVENT_GENERIC_NO_OBJECT;
+    constructor(message: string);
 }
 /**
  * Resolve a Case event subscription: `library.resolveEvent` with the

package/dist/case/subscription.js

@@ -1,10 +1,13 @@
 import { genericEventObjectRefusal } from '../core/event-checks.js';
 import { ByoaRefusal, byoaUnverified } from '../core/byoa.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 /** Check's code for {@link GenericEventNoObjectError}; Flow and BPMN `check` use the same one. */
 export const EVENT_GENERIC_NO_OBJECT = 'EVENT_GENERIC_NO_OBJECT';
 /** A GENERIC event subscription that names no object. */
-export class GenericEventNoObjectError extends Error {
-    code = EVENT_GENERIC_NO_OBJECT;
+export class GenericEventNoObjectError extends CompileRefusal {
+    constructor(message) {
+        super(EVENT_GENERIC_NO_OBJECT, message);
+    }
 }
 /** How a Case subscription spells the `object` of a GENERIC event, for the refusal text. */
 function caseObjectOption(object) {

package/dist/core/actions.js

@@ -13,7 +13,7 @@ class BuiltinAction extends FlowAction {
         Object.assign(this, spec);
     }
     contribute() {
-        throw new Error('built-in action specs are lowered by the serializer directly; contribute() is only called on custom FlowAction subclasses');
+        throw new Error('internal SDK error: built-in action specs are lowered by the serializer directly; contribute() is only called on custom FlowAction subclasses');
     }
 }
 class BuiltinTrigger extends FlowTrigger {
@@ -22,7 +22,7 @@ class BuiltinTrigger extends FlowTrigger {
         Object.assign(this, spec);
     }
     contribute() {
-        throw new Error('built-in trigger specs are lowered by the serializer directly; contribute() is only called on custom FlowTrigger subclasses');
+        throw new Error('internal SDK error: built-in trigger specs are lowered by the serializer directly; contribute() is only called on custom FlowTrigger subclasses');
     }
 }
 /**

package/dist/core/binding-messages.d.ts

@@ -1,3 +1,4 @@
+import { CompileRefusal } from './compile-refusal.js';
 /** A tenant resource key — an Integration Service connection id or an Orchestrator folder key — is a GUID. */
 export declare const GUID_RE: RegExp;
 /** The diagnostic codes a label refusal carries, in `check` and on the error `serialize` throws. */
@@ -18,7 +19,7 @@ export type BindingRefusalCode = 'BINDING_SELF_NAME' | 'BINDING_UNDECLARED'
  * message is the sentence `check` prints; the `code` lets `compile --no-check`
  * print it in the same `✗ [CODE]` shape as the check pass instead of a bare line.
  */
-export declare class BindingRefusal extends Error {
+export declare class BindingRefusal extends CompileRefusal {
     readonly code: BindingRefusalCode;
     constructor(code: BindingRefusalCode, message: string);
 }

package/dist/core/binding-messages.js

@@ -6,6 +6,7 @@
  * for a source `compile` then refused (teams-decision, 2026-09-01, turn 22 → 23).
  */
 import { prepareCommand } from './cli-spelling.js';
+import { CompileRefusal } from './compile-refusal.js';
 /** A tenant resource key — an Integration Service connection id or an Orchestrator folder key — is a GUID. */
 export const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
@@ -13,12 +14,10 @@ export const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f
  * message is the sentence `check` prints; the `code` lets `compile --no-check`
  * print it in the same `✗ [CODE]` shape as the check pass instead of a bare line.
  */
-export class BindingRefusal extends Error {
-    code;
+export class BindingRefusal extends CompileRefusal {
     constructor(code, message) {
-        super(message);
+        super(code, message);
         this.name = 'BindingRefusal';
-        this.code = code;
     }
 }
 export function bindingSelfNameMessage(where, name, attribute, target) {

package/dist/core/byoa.d.ts

@@ -1,3 +1,4 @@
+import { CompileRefusal } from './compile-refusal.js';
 /** The diagnostic code, in `check` and on the error `serialize` throws. */
 export declare const EVENT_BYOA_UNVERIFIED = "EVENT_BYOA_UNVERIFIED";
 /** One verification `prepare` recorded. Only a PASSING check is ever written. */
@@ -30,8 +31,8 @@ export declare function byoaLedgerKey(connectorKey: string, event: string): stri
 /** The record for `connectionId` under `nodeType`, matching the id case-insensitively. */
 export declare function byoaRecordFor(ledger: ByoaLedger | undefined, nodeType: string, connectionId: string): ByoaRecord | undefined;
 /** What `compile` throws for the refusal; `code` lets the CLI print it as `✗ [CODE]`. */
-export declare class ByoaRefusal extends Error {
-    readonly code = "EVENT_BYOA_UNVERIFIED";
+export declare class ByoaRefusal extends CompileRefusal {
+    readonly code: typeof EVENT_BYOA_UNVERIFIED;
     constructor(message: string);
 }
 /** One subscription, as the rule needs it. */

package/dist/core/byoa.js

@@ -22,6 +22,7 @@
  */
 import { GUID_RE } from './binding-messages.js';
 import { prepareCommand } from './cli-spelling.js';
+import { CompileRefusal } from './compile-refusal.js';
 /** The diagnostic code, in `check` and on the error `serialize` throws. */
 export const EVENT_BYOA_UNVERIFIED = 'EVENT_BYOA_UNVERIFIED';
 /**
@@ -45,10 +46,9 @@ export function byoaRecordFor(ledger, nodeType, connectionId) {
     return undefined;
 }
 /** What `compile` throws for the refusal; `code` lets the CLI print it as `✗ [CODE]`. */
-export class ByoaRefusal extends Error {
-    code = EVENT_BYOA_UNVERIFIED;
+export class ByoaRefusal extends CompileRefusal {
     constructor(message) {
-        super(message);
+        super(EVENT_BYOA_UNVERIFIED, message);
         this.name = 'ByoaRefusal';
     }
 }

package/dist/core/carried-definitions.d.ts

@@ -1,21 +1,3 @@
-/**
- * Node definitions a flow CARRIES — the third source a pinned `{ version }`
- * resolves from, after the SDK's bundle (#1128).
- *
- * Every `.flow` file holds the exact definition of every node it uses, in
- * `definitions[]`. The SDK bundles only the versions it was released with, so
- * a version the registry served later (`node add` writes
- * `uipath.human-in-the-loop.quick-form@1.6`; the SDK ships 1.0 and 1.1) used
- * to be refused, and the source decompile wrote for an untouched product flow
- * did not compile. A carried definition closes that: decompile copies the
- * file's own entry into `.definitions([...])`, and compile resolves the pin
- * against it.
- *
- * A carried definition is an exact copy of a real one, never a way to invent a
- * version. So it is validated the way a `rawNode` snapshot manifest is: it
- * names its own `nodeType` and `version`, and it has the `display.label` every
- * node manifest has.
- */
 /** A carried definition, by its `<nodeType>@<version>` key. */
 export type CarriedDefinitions = ReadonlyMap<string, Record<string, unknown>>;
 /**

package/dist/core/carried-definitions.js

@@ -16,6 +16,7 @@
  * names its own `nodeType` and `version`, and it has the `display.label` every
  * node manifest has.
  */
+import { CompileRefusal } from './compile-refusal.js';
 /**
  * Why `manifest` cannot be carried, or `undefined` when it can.
  *
@@ -44,12 +45,12 @@ export function indexCarriedDefinitions(manifests, where, into = new Map()) {
     for (const m of manifests) {
         const refusal = carriedDefinitionRefusal(m, where);
         if (refusal)
-            throw new Error(refusal);
+            throw new CompileRefusal('CARRIED_DEFINITION_INVALID', refusal);
         const def = m;
         const key = `${def.nodeType}@${def.version}`;
         const prior = into.get(key);
         if (prior !== undefined && stableJson(prior) !== stableJson(def)) {
-            throw new Error(`${where}: two different carried definitions for ${key}. Keep the one the file holds.`);
+            throw new CompileRefusal('CARRIED_DEFINITION_CONFLICT', `${where}: two different carried definitions for ${key}. Keep the one the file holds.`);
         }
         into.set(key, def);
     }

package/dist/core/ceql.d.ts

@@ -32,6 +32,7 @@
  * its runtime half and gets no tree — the same state as before this existed,
  * rather than a wrong one.
  */
+import { CompileRefusal } from './compile-refusal.js';
 /** A leaf's comparison operator, in the canonical PascalCase the canvas stores. */
 export type CeqlOperator = 'Equals' | 'NotEquals' | 'LessThan' | 'LessThanOrEqual' | 'GreaterThan' | 'GreaterThanOrEqual' | 'Contains' | 'NotContains' | 'StartsWith' | 'NotStartsWith' | 'EndsWith' | 'NotEndsWith' | 'Like' | 'NotLike' | 'IsNull' | 'IsNotNull';
 /** One comparison — `<field> <operator> <value>`. */
@@ -55,7 +56,7 @@ export interface CeqlTree {
     uuId?: string;
 }
 /** Raised when an expression is not CEQL this parser can represent. */
-export declare class CeqlParseError extends Error {
+export declare class CeqlParseError extends CompileRefusal {
     readonly expression: string;
     constructor(message: string, expression: string);
 }

package/dist/core/ceql.js

@@ -34,11 +34,12 @@
  */
 import { stableId } from './stable-id.js';
 import { ownEntry } from './own-entry.js';
+import { CompileRefusal } from './compile-refusal.js';
 /** Raised when an expression is not CEQL this parser can represent. */
-export class CeqlParseError extends Error {
+export class CeqlParseError extends CompileRefusal {
     expression;
     constructor(message, expression) {
-        super(message);
+        super('CEQL_UNPARSEABLE', message);
         this.expression = expression;
         this.name = 'CeqlParseError';
     }

package/dist/core/compile-refusal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The error every build-time refusal throws: a sentence for the author plus a
+ * stable `code` (docs/CHECK_COMPILE_CONTRACT_DESIGN.md §3.1, #1440).
+ *
+ * The code is what tells a refusal from a bug without matching on message text:
+ * `thrownDiagnostic` (`cli-result.ts`) reports it under this code, so
+ * `compile --output json` prints `[DUP_STEP]` instead of `COMPILE_FAILED`, and
+ * `merge` can sort it by node. Every code is listed in `core/refusals.ts` with
+ * its class (lint, lowering, draft); FB017 keeps the two in step.
+ *
+ * Only an internal error — a broken SDK invariant the author cannot act on —
+ * stays a plain `Error`, and its message starts with `internal SDK error:`.
+ *
+ * For instance:
+ *
+ *   throw new CompileRefusal('DUP_STEP', `two steps are named "notify". …`);
+ */
+export declare class CompileRefusal extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}

package/dist/core/compile-refusal.js

@@ -0,0 +1,26 @@
+/**
+ * The error every build-time refusal throws: a sentence for the author plus a
+ * stable `code` (docs/CHECK_COMPILE_CONTRACT_DESIGN.md §3.1, #1440).
+ *
+ * The code is what tells a refusal from a bug without matching on message text:
+ * `thrownDiagnostic` (`cli-result.ts`) reports it under this code, so
+ * `compile --output json` prints `[DUP_STEP]` instead of `COMPILE_FAILED`, and
+ * `merge` can sort it by node. Every code is listed in `core/refusals.ts` with
+ * its class (lint, lowering, draft); FB017 keeps the two in step.
+ *
+ * Only an internal error — a broken SDK invariant the author cannot act on —
+ * stays a plain `Error`, and its message starts with `internal SDK error:`.
+ *
+ * For instance:
+ *
+ *   throw new CompileRefusal('DUP_STEP', `two steps are named "notify". …`);
+ */
+export class CompileRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        // `name` stays `Error`, so a converted `throw new Error(…)` prints exactly as
+        // it did (`Error: …` in `String(e)` and stacks). A subclass names itself.
+        this.code = code;
+    }
+}

package/dist/core/connector-inputs.js

@@ -30,6 +30,7 @@ export { FLOW_EXPR_DIALECT } from './connector-checks.js';
 import { FLOW_EXPR_DIALECT as FLOW_DIALECT } from './connector-checks.js';
 import { ownEntry } from './own-entry.js';
 import { isRecord } from './node-envelope.js';
+import { CompileRefusal } from './compile-refusal.js';
 /** A required connector input left empty — the one draft code with no error class of its own. */
 export const CONNECTOR_INPUT_MISSING = 'CONNECTOR_INPUT_MISSING';
 /**
@@ -204,7 +205,7 @@ export function buildConnectorInputs(rc, inputs, opts) {
                     `wrong value resolves back to just the parents. ` +
                     `See the connector guide's parent-field loop.`;
         }
-        throw new Error(`connector ${rc.nodeType}: ${errs.join('; ')}. Required fields: ${req}.${hint}`);
+        throw new CompileRefusal('CONNECTOR_INPUT', `connector ${rc.nodeType}: ${errs.join('; ')}. Required fields: ${req}.${hint}`);
     }
     // Every declared part, in declaration order, as the designer lists them: the
     // container part valueless, a file part with the author's value when given. A

package/dist/core/connector-resolve-error.d.ts

@@ -3,6 +3,7 @@
  * the connector library from disk, so `serialize` can recognise the refusal
  * without loading `node:fs` (FB015). `core/library.ts` re-exports both.
  */
+import { CompileRefusal } from './compile-refusal.js';
 /** Why `Library.resolve` refused a connector action. */
 export type ConnectorResolveCode = 
 /** The library carries no such operation (or no such connector, or not at that version). */
@@ -29,7 +30,7 @@ export type ConnectorResolveCode =
  * text: `check` reports it under this code with this message, and a compile
  * that throws it carries the same code into its `--json` diagnostics (#948).
  */
-export declare class ConnectorResolveError extends Error {
+export declare class ConnectorResolveError extends CompileRefusal {
     readonly code: ConnectorResolveCode;
     constructor(code: ConnectorResolveCode, message: string);
 }

package/dist/core/connector-resolve-error.js

@@ -3,6 +3,7 @@
  * the connector library from disk, so `serialize` can recognise the refusal
  * without loading `node:fs` (FB015). `core/library.ts` re-exports both.
  */
+import { CompileRefusal } from './compile-refusal.js';
 /**
  * The refusal `Library.resolve` throws, with a `code` for each reason.
  *
@@ -10,11 +11,9 @@
  * text: `check` reports it under this code with this message, and a compile
  * that throws it carries the same code into its `--json` diagnostics (#948).
  */
-export class ConnectorResolveError extends Error {
-    code;
+export class ConnectorResolveError extends CompileRefusal {
     constructor(code, message) {
-        super(message);
+        super(code, message);
         this.name = 'ConnectorResolveError';
-        this.code = code;
     }
 }

package/dist/core/connectors.js

@@ -21,6 +21,7 @@
  * arrays; `buildConnectorInputs` validates them and projects them back to the
  * registry's flat field ids when emitting Flow JSON.
  */
+import { CompileRefusal } from './compile-refusal.js';
 /**
  * Brand a descriptor literal with its input/output types (zero runtime cost).
  * Used by codegen: `descriptor<CreateIssueInputs, CreateIssueOutputs>()({ … } as const)`.
@@ -49,7 +50,7 @@ export function splitConnectorNodeType(nodeType) {
     const rest = nodeType.replace(/^uipath\.connector\./, '');
     const dot = rest.lastIndexOf('.');
     if (dot <= 0)
-        throw new Error(`invalid connector nodeType "${nodeType}" (expected uipath.connector.<key>.<action>).`);
+        throw new CompileRefusal('CONNECTOR_NODE_TYPE_INVALID', `invalid connector nodeType "${nodeType}" (expected uipath.connector.<key>.<action>).`);
     return { key: rest.slice(0, dot), action: rest.slice(dot + 1) };
 }
 /**

package/dist/core/event-filters.js

@@ -35,6 +35,7 @@
  * matches.
  */
 import { ownEntry } from './own-entry.js';
+import { CompileRefusal } from './compile-refusal.js';
 /** The designer's operator vocabulary this SDK emits, keyed by the authored key. */
 export const EVENT_FILTER_OPERATORS = {
     contains: { designer: 'Contains', kind: 'function', jmes: 'contains' },
@@ -136,7 +137,7 @@ export function eventFilterProblem(read) {
 export function jmesString(value) {
     const problem = jmesStringProblem(value);
     if (problem)
-        throw new Error(`jmesString: ${problem}`);
+        throw new CompileRefusal('EVENT_FILTER_BACKSLASH', `jmesString: ${problem}`);
     return `'${value.replace(/'/g, "\\'")}'`;
 }
 /** A backslash whose raw-string reading depends on the engine: before `\` or `'`, or last. */

package/dist/core/hitl-routing.d.ts

@@ -1,83 +1,3 @@
-/**
- * How a human task leaves its node — the one model `serialize`, `check` and
- * `.stepSwitch` (`step-ports.ts`) all read, so the three cannot drift. They did
- * drift once, in the direction that matters least visibly: `check` keyed on the
- * `outcomePorts` FLAG while `serialize` was about to infer it, which would have
- * made `check` refuse per-outcome wiring that `compile` then emitted.
- *
- * **The product's rule, which the model follows.** On the base node
- * (`uipath.human-in-the-loop`, `type: 'quick'`) and on the quick-form variant,
- * the designer draws ONE handle per entry in `inputs.schema.outcomes`, named
- * `outcome-<id>`, whatever the node's `typeVersion` — and draws the manifest's
- * static `completed` handle only when there are no outcomes
- * (flow-workbench `build-handle-customization.ts:102-124`; it derives them on
- * every render and deliberately never saves them). A leftover `completed` edge
- * on such a node is a stale placeholder: since flow-workbench #3512 the load
- * path and the converter remap it to the PRIMARY outcome
- * (`hitl-edge-reconciliation.ts:52-63`), so every other outcome loses its path at
- * run time. So a task with outcomes never leaves on `completed` here. The two
- * app-backed variants are different: action-app and document-validation read
- * their outcomes from `inputs.app`, and `completed` really is the only handle
- * they render (`hitl-edge-reconciliation.ts:68-74`).
- *
- * (This replaces an older premise — "the definition VERSION selects the port
- * shape, and the variants have no per-outcome version" (#729). The manifests do
- * declare only `completed` statically; the designer just never reads that list
- * for these two node types once outcomes exist.)
- *
- * **Three shapes**, and what `.step()` after the task means in each — ".step()
- * continues from the task's tails":
- *
- * - `per-outcome`: the task ROUTES per outcome. One tail, the PRIMARY (first)
- *   outcome's `outcome-<id>`; the author routes the rest with `.stepToList` /
- *   `.stepToRef`, or all of them as `.stepSwitch` arms.
- * - `every-outcome`: the task does NOT route per outcome. One tail PER outcome,
- *   so `.step()` continues every outcome to the next step ("fan-out") — the
- *   decision reaches the flow as data, `out('<step>', 'Action')`, in the handles
- *   the product draws. An `action: 'End'` outcome is the exception: the flow
- *   runtime never reads `action` (flow-workbench `hitl-serialization.ts` does
- *   not; only the agent storage projection does), so the graph is the only thing
- *   that can end the run there, and `serialize` gives it an End node.
- * - `placeholder`: `completed` — action-app, document-validation, and a task
- *   with no outcomes.
- *
- * **More than one outcome infers `per-outcome`** on the base node (#739): a task
- * that publishes a choice and then routes every button the same way was the
- * modelling error behind flow-builder-sdk#735, and a warning alone did not
- * change what agents emitted. Five things keep a base or quick-form task on
- * `every-outcome` instead, in this order:
- *
- * 1. `outcomePorts: false` — the explicit "decision as data" choice.
- * 2. `variant: 'quick-form'`. Not a product limit — quick-form draws the same
- *    per-outcome handles — but its authors write `.step()` or a `.switch` on the
- *    Action after it and mean "every outcome continues" (every quick-form source
- *    in the 09-23 baseline does), so inferring primary-only there would strand
- *    the other outcomes. It routes per outcome when asked: `outcomePorts: true`,
- *    or `.stepSwitch`. Its definition version never moves.
- * 3. An explicit `{ version }` pin. `decompile` pins every node and writes
- *    `outcomePorts: true` whenever a task's outcomes lead to different places, so
- *    a pinned task that reaches `.step()` without the flag is a round-tripped
- *    artifact whose outcomes all go to one step, or a legacy lone `completed`
- *    edge, which meant "every outcome continues" before #3512. Both are this
- *    shape. The pin also wins the version: `outcomePorts: true` on a pinned 1.0
- *    routes per outcome on the 1.0 node, which `flow validate` accepts.
- * 4. A single outcome — an acknowledgement, not a choice.
- * 5. Every outcome carrying `action: 'End'` — there is no continuation to
- *    distinguish, and each outcome gets its End.
- *
- * `exposeError: true` or `outcomePorts: true` select `per-outcome` on every node
- * type, including the two app-backed variants, so that `serialize` and `check`
- * refuse them there with their own message rather than silently ignoring them.
- *
- * **`legacyCompleted: true`** is the one way to keep a task with outcomes on the
- * `completed` handle: the `placeholder` shape, marked `legacyCompleted`. It
- * exists so a file saved before flow-workbench #3512, whose task leaves on one
- * `completed` edge, round-trips through decompile and compile unchanged
- * (flow-builder-sdk#1197). It is the file's shape, not one to author: the
- * product runs that edge as the PRIMARY outcome only, and `check` says so
- * (HITL_LEGACY_COMPLETED). `serialize`'s edge guard below exempts exactly the
- * nodes that asked for it.
- */
 /**
  * The fields of a human task's inputs the routing model reads — structural, so
  * this module stays in `core/` while the authoring type (`HitlInputs`) belongs
@@ -155,7 +75,9 @@ type EdgeLike = {
     sourcePort?: unknown;
 };
 /**
- * Why an edge on `port` cannot leave `node`, or `undefined` when it can.
+ * Why an edge on `port` cannot leave `node` — the code and the sentence — or
+ * `undefined` when it can. The code is `check`'s for the same edge, so both
+ * call sites throw what this returns.
  *
  * Only the two node types whose handles the product derives from the outcomes
  * are judged, and only once they HAVE outcomes: then `completed` is a handle
@@ -165,7 +87,10 @@ type EdgeLike = {
  * bare `completed` never is, unless the task asked for it with
  * `legacyCompleted: true` (`legacyCompleted` here).
  */
-export declare function hitlExitViolation(node: NodeLike, port: string, legacyCompleted?: boolean): string | undefined;
+export declare function hitlExitViolation(node: NodeLike, port: string, legacyCompleted?: boolean): {
+    code: 'HITL_COMPLETED_PORT_GONE' | 'HITL_OUTCOME_PORT_UNKNOWN';
+    message: string;
+} | undefined;
 /**
  * The post-emit half of the guard: every edge of an emitted scope, whatever
  * path produced it (a tail, a `.stepToList` seed, a parked `.stepToRef`), is held

package/dist/core/hitl-routing.js

@@ -1,3 +1,84 @@
+/**
+ * How a human task leaves its node — the one model `serialize`, `check` and
+ * `.stepSwitch` (`step-ports.ts`) all read, so the three cannot drift. They did
+ * drift once, in the direction that matters least visibly: `check` keyed on the
+ * `outcomePorts` FLAG while `serialize` was about to infer it, which would have
+ * made `check` refuse per-outcome wiring that `compile` then emitted.
+ *
+ * **The product's rule, which the model follows.** On the base node
+ * (`uipath.human-in-the-loop`, `type: 'quick'`) and on the quick-form variant,
+ * the designer draws ONE handle per entry in `inputs.schema.outcomes`, named
+ * `outcome-<id>`, whatever the node's `typeVersion` — and draws the manifest's
+ * static `completed` handle only when there are no outcomes
+ * (flow-workbench `build-handle-customization.ts:102-124`; it derives them on
+ * every render and deliberately never saves them). A leftover `completed` edge
+ * on such a node is a stale placeholder: since flow-workbench #3512 the load
+ * path and the converter remap it to the PRIMARY outcome
+ * (`hitl-edge-reconciliation.ts:52-63`), so every other outcome loses its path at
+ * run time. So a task with outcomes never leaves on `completed` here. The two
+ * app-backed variants are different: action-app and document-validation read
+ * their outcomes from `inputs.app`, and `completed` really is the only handle
+ * they render (`hitl-edge-reconciliation.ts:68-74`).
+ *
+ * (This replaces an older premise — "the definition VERSION selects the port
+ * shape, and the variants have no per-outcome version" (#729). The manifests do
+ * declare only `completed` statically; the designer just never reads that list
+ * for these two node types once outcomes exist.)
+ *
+ * **Three shapes**, and what `.step()` after the task means in each — ".step()
+ * continues from the task's tails":
+ *
+ * - `per-outcome`: the task ROUTES per outcome. One tail, the PRIMARY (first)
+ *   outcome's `outcome-<id>`; the author routes the rest with `.stepToList` /
+ *   `.stepToRef`, or all of them as `.stepSwitch` arms.
+ * - `every-outcome`: the task does NOT route per outcome. One tail PER outcome,
+ *   so `.step()` continues every outcome to the next step ("fan-out") — the
+ *   decision reaches the flow as data, `out('<step>', 'Action')`, in the handles
+ *   the product draws. An `action: 'End'` outcome is the exception: the flow
+ *   runtime never reads `action` (flow-workbench `hitl-serialization.ts` does
+ *   not; only the agent storage projection does), so the graph is the only thing
+ *   that can end the run there, and `serialize` gives it an End node.
+ * - `placeholder`: `completed` — action-app, document-validation, and a task
+ *   with no outcomes.
+ *
+ * **More than one outcome infers `per-outcome`** on the base node (#739): a task
+ * that publishes a choice and then routes every button the same way was the
+ * modelling error behind flow-builder-sdk#735, and a warning alone did not
+ * change what agents emitted. Five things keep a base or quick-form task on
+ * `every-outcome` instead, in this order:
+ *
+ * 1. `outcomePorts: false` — the explicit "decision as data" choice.
+ * 2. `variant: 'quick-form'`. Not a product limit — quick-form draws the same
+ *    per-outcome handles — but its authors write `.step()` or a `.switch` on the
+ *    Action after it and mean "every outcome continues" (every quick-form source
+ *    in the 09-23 baseline does), so inferring primary-only there would strand
+ *    the other outcomes. It routes per outcome when asked: `outcomePorts: true`,
+ *    or `.stepSwitch`. Its definition version never moves.
+ * 3. An explicit `{ version }` pin. `decompile` pins every node and writes
+ *    `outcomePorts: true` whenever a task's outcomes lead to different places, so
+ *    a pinned task that reaches `.step()` without the flag is a round-tripped
+ *    artifact whose outcomes all go to one step, or a legacy lone `completed`
+ *    edge, which meant "every outcome continues" before #3512. Both are this
+ *    shape. The pin also wins the version: `outcomePorts: true` on a pinned 1.0
+ *    routes per outcome on the 1.0 node, which `flow validate` accepts.
+ * 4. A single outcome — an acknowledgement, not a choice.
+ * 5. Every outcome carrying `action: 'End'` — there is no continuation to
+ *    distinguish, and each outcome gets its End.
+ *
+ * `exposeError: true` or `outcomePorts: true` select `per-outcome` on every node
+ * type, including the two app-backed variants, so that `serialize` and `check`
+ * refuse them there with their own message rather than silently ignoring them.
+ *
+ * **`legacyCompleted: true`** is the one way to keep a task with outcomes on the
+ * `completed` handle: the `placeholder` shape, marked `legacyCompleted`. It
+ * exists so a file saved before flow-workbench #3512, whose task leaves on one
+ * `completed` edge, round-trips through decompile and compile unchanged
+ * (flow-builder-sdk#1197). It is the file's shape, not one to author: the
+ * product runs that edge as the PRIMARY outcome only, and `check` says so
+ * (HITL_LEGACY_COMPLETED). `serialize`'s edge guard below exempts exactly the
+ * nodes that asked for it.
+ */
+import { CompileRefusal } from './compile-refusal.js';
 /**
  * An outcome's stable id — the slug that names its `outcome-<id>` port.
  *
@@ -90,7 +171,9 @@ function outcomeIdsOf(node) {
     return outcomes.map((o) => o?.id).filter((id) => typeof id === 'string' && id !== '');
 }
 /**
- * Why an edge on `port` cannot leave `node`, or `undefined` when it can.
+ * Why an edge on `port` cannot leave `node` — the code and the sentence — or
+ * `undefined` when it can. The code is `check`'s for the same edge, so both
+ * call sites throw what this returns.
  *
  * Only the two node types whose handles the product derives from the outcomes
  * are judged, and only once they HAVE outcomes: then `completed` is a handle
@@ -110,12 +193,18 @@ export function hitlExitViolation(node, port, legacyCompleted = false) {
     if (port === 'completed') {
         if (legacyCompleted)
             return undefined;
-        return `human task "${String(node.id)}" has outcomes (${declared}), so the product draws no `
-            + `'completed' handle on it — an edge there is remapped to the primary outcome and every other `
-            + `outcome loses its path.`;
+        return {
+            code: 'HITL_COMPLETED_PORT_GONE',
+            message: `human task "${String(node.id)}" has outcomes (${declared}), so the product draws no `
+                + `'completed' handle on it — an edge there is remapped to the primary outcome and every other `
+                + `outcome loses its path.`,
+        };
     }
     if (port.startsWith('outcome-') && !ids.includes(port.slice('outcome-'.length))) {
-        return `human task "${String(node.id)}" has no outcome for port "${port}" — it declares ${declared}.`;
+        return {
+            code: 'HITL_OUTCOME_PORT_UNKNOWN',
+            message: `human task "${String(node.id)}" has no outcome for port "${port}" — it declares ${declared}.`,
+        };
     }
     return undefined;
 }
@@ -135,6 +224,6 @@ export function assertHitlExitInvariant(nodes, edges, legacyCompleted = new Set(
             continue;
         const why = hitlExitViolation(node, String(e.sourcePort), legacyCompleted.has(String(e.sourceNodeId)));
         if (why)
-            throw new Error(`serialize: ${why}`);
+            throw new CompileRefusal(why.code, `serialize: ${why.message}`);
     }
 }

package/dist/core/library.js

@@ -14,6 +14,7 @@ import { lookupSpecOf } from './lookups.js';
 import { loadByoaLedger, loadInvariantCollections, loadLookupResolutions } from './lookup-store.js';
 import { ownEntry } from './own-entry.js';
 import { ConnectorResolveError } from './connector-resolve-error.js';
+import { CompileRefusal } from './compile-refusal.js';
 export { ConnectorResolveError } from './connector-resolve-error.js';
 export class Library {
     layers = [];
@@ -59,7 +60,7 @@ export class Library {
         const idx = libraryPath(dir, 'index.json');
         const entries = libraryEntries(read, idx);
         if (entries === undefined)
-            throw new Error(`connector library not found at ${idx}. `
+            throw new CompileRefusal('LIBRARY_NOT_FOUND', `connector library not found at ${idx}. `
                 + (read === readTextFromDisk
                     ? `Run \`${PULL_COMMAND}\`, or point --library / $FLOW_SDK_LIBRARY_JSON at a library-json dir.`
                     : 'The reader passed to Library has no such file.'));
@@ -292,7 +293,7 @@ export class Library {
                 };
             }
         }
-        throw new Error(`connector activity not found in library: ${wire.connectorKey} ${wire.httpMethod ?? '?'} ${wire.endpoint ?? '?'}`);
+        throw new CompileRefusal('CONNECTOR_NOT_IN_LIBRARY', `connector activity not found in library: ${wire.connectorKey} ${wire.httpMethod ?? '?'} ${wire.endpoint ?? '?'}`);
     }
     /**
      * Resolve a connector EVENT: the START trigger
@@ -393,7 +394,7 @@ export class Library {
                 };
             }
         }
-        throw new Error(`connector ${kind} event not found in library: ${wire.connectorKey} `
+        throw new CompileRefusal('EVENT_UNKNOWN', `connector ${kind} event not found in library: ${wire.connectorKey} `
             + `${wire.eventOperation ?? '?'} ${wire.objectName ?? '?'}`);
     }
     /**