@uipath/maestro-builder-sdk 6.65.0 → 6.66.0

package/dist/bpmn/bpmn-expr-check.d.ts

@@ -23,6 +23,7 @@
  */
 import { type ExprDiagnostic } from '../core/expr-check.js';
 import type { BuiltBpmn } from './bpmn-sdk.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 /** A diagnostic plus the element it was found in. */
 export interface BpmnLocatedDiagnostic extends ExprDiagnostic {
     where: string;
@@ -35,7 +36,7 @@ export declare function checkBpmnExpressions(built: BuiltBpmn): BpmnLocatedDiagn
  * `FlowBuildError`: `message` lists every problem; `diagnostics` carries them
  * structured.
  */
-export declare class BpmnBuildError extends Error {
+export declare class BpmnBuildError extends CompileRefusal {
     readonly diagnostics: BpmnLocatedDiagnostic[];
     constructor(built: BuiltBpmn, diagnostics: BpmnLocatedDiagnostic[]);
 }

package/dist/bpmn/bpmn-expr-check.js

@@ -23,6 +23,7 @@
  */
 import { checkExpression } from '../core/expr-check.js';
 import { nodeDeclaredVars } from './declared-vars.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 const NOUN = 'variable';
 const NAMESPACE = 'vars';
 const BINDING_NOUN = 'binding';
@@ -213,12 +214,13 @@ function connectorBindingNames(nodes) {
  * `FlowBuildError`: `message` lists every problem; `diagnostics` carries them
  * structured.
  */
-export class BpmnBuildError extends Error {
+export class BpmnBuildError extends CompileRefusal {
     diagnostics;
     constructor(built, diagnostics) {
         const label = built.name || built.id || 'process';
         const lines = diagnostics.map((d) => `  ✗ [${d.code}] in ${d.where}: ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
-        super(`Cannot build BPMN process "${label}" — ${diagnostics.length} expression problem(s):\n${lines.join('\n')}`);
+        // The first problem's code; `diagnostics` carries every one.
+        super(diagnostics[0]?.code ?? 'EXPR_UNDECLARED_REF', `Cannot build BPMN process "${label}" — ${diagnostics.length} expression problem(s):\n${lines.join('\n')}`);
         this.name = 'BpmnBuildError';
         this.diagnostics = diagnostics;
     }

package/dist/bpmn/bpmn-sdk.js

@@ -5,6 +5,7 @@ import { schemaVersionRefusal } from '../schema-version.js';
 import { bindingRequiredFields, REGISTRY_GAPS, registryType } from './typed-node.js';
 import { resolveResourceKeyPattern } from './resource-key-pattern.js';
 import { quickHumanTaskRows } from './human-task-form.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 import { DATA_SERVICE_ACTIVITY_TYPE, DATA_SERVICE_CONNECTOR_KEY, dataServiceWire } from './data-service.js';
 import { MANAGED_HTTP_CONNECTION_NAME, MANAGED_HTTP_CONNECTOR_KEY, MANAGED_HTTP_FOLDER_NAME, MANAGED_HTTP_TYPE, managedHttpContext, managedHttpInputs, managedHttpOutputs, } from './managed-http.js';
 import { ownEntry } from '../core/own-entry.js';
@@ -14,6 +15,10 @@ export { connectorOutputVars, nodeDeclaredVars, typedNodeDeclaredVars } from './
 function normTimer(t) {
     return typeof t === 'string' ? { duration: t } : t;
 }
+/** Every {@link PlainTaskElement}, for the run-time check in `.plainTask()`. */
+const PLAIN_TASK_ELEMENTS = new Set([
+    'bpmn:task', 'bpmn:userTask', 'bpmn:serviceTask', 'bpmn:sendTask', 'bpmn:manualTask', 'bpmn:businessRuleTask', 'bpmn:receiveTask',
+]);
 /** Bookkeeping the nesting sugar shares across every scope of one process. */
 class SugarRegistry {
     /** Flow ids the builder wrote by implication rather than from an explicit `.sequenceFlow()`. */
@@ -215,7 +220,7 @@ function toErrorDef(defs, error, where) {
     // ERROR_END_EVENT_MISSING_EXCEPTION on an end event) after a whole toolchain cycle.
     // `error: true` is the way to say "any error"; a name is the way to say which.
     if (spec.name.trim() === '') {
-        throw new Error(`${where}: the error name is empty, so the declared \`bpmn:error\` has nothing to match on. ` +
+        throw new CompileRefusal('BPMN_ERROR_NAME_EMPTY', `${where}: the error name is empty, so the declared \`bpmn:error\` has nothing to match on. ` +
             'Pass `error: true` to catch any error, or a name — `error: "PaymentFailed"`, or ' +
             '`error: { name: "PaymentFailed", code: "PAYMENT_FAILED" }`.');
     }
@@ -335,10 +340,10 @@ class ScopeBuilder {
      */
     flowMode(mode) {
         if (this._isArm) {
-            throw new Error(`.flowMode('${mode}') is not available inside an arm or handler body — those always chain in order.`);
+            throw new CompileRefusal('BPMN_FLOW_MODE_IN_BODY', `.flowMode('${mode}') is not available inside an arm or handler body — those always chain in order.`);
         }
         if (this._nodes.length > 0) {
-            throw new Error(`.flowMode('${mode}') must come before the scope's first element; "${this._nodes[0].id}" is already placed.`);
+            throw new CompileRefusal('BPMN_FLOW_MODE_AFTER_ELEMENT', `.flowMode('${mode}') must come before the scope's first element; "${this._nodes[0].id}" is already placed.`);
         }
         this._mode = mode;
         this._scopeMode = mode;
@@ -360,7 +365,7 @@ class ScopeBuilder {
         // with no output row (the fire-and-forget Async starts) would accept it and emit
         // nothing, so the author reads a variable nothing ever writes.
         if (node.kind === 'typed' && node.outputVar !== undefined && !node.outputRows && !registryType(node.type, node.spec).output) {
-            throw new Error(`"${node.id}" (${node.type}) publishes no output row, so outputVar "${node.outputVar}" would bind nothing. ` +
+            throw new CompileRefusal('BPMN_OUTPUT_VAR_NO_OUTPUT_ROW', `"${node.id}" (${node.type}) publishes no output row, so outputVar "${node.outputVar}" would bind nothing. ` +
                 (node.type.endsWith('Async')
                     ? 'The Async start returns before the job does: drop outputVar, or use the waiting form (async: false) to read the response.'
                     : 'Drop outputVar, or spell the rows with outputRows.'));
@@ -381,15 +386,15 @@ class ScopeBuilder {
      */
     place(node, viaSugar = false) {
         if (this._closedBy !== undefined) {
-            throw new Error(`"${node.id}" follows ${this._closedBy}, which already left this path — nothing can come after it.`);
+            throw new CompileRefusal('BPMN_PATH_ALREADY_LEFT', `"${node.id}" follows ${this._closedBy}, which already left this path — nothing can come after it.`);
         }
         if (this._mode === 'sequence') {
             if (isStartLike(node)) {
                 if (this._isArm) {
-                    throw new Error(`startEvent "${node.id}": a body has no start event of its own — it begins where the enclosing element hands over to it.`);
+                    throw new CompileRefusal('BPMN_START_IN_BODY', `startEvent "${node.id}": a body has no start event of its own — it begins where the enclosing element hands over to it.`);
                 }
                 if (this._synthesizedStart !== undefined) {
-                    throw new Error(`startEvent "${node.id}": an event sub-process has exactly one start event, and this one's is ` +
+                    throw new CompileRefusal('BPMN_START_ALREADY_SYNTHESIZED', `startEvent "${node.id}": an event sub-process has exactly one start event, and this one's is ` +
                         `synthesized as "${this._synthesizedStart}" — write what follows it instead.`);
                 }
                 // Explicit wins here as everywhere: a plain exit whose element already has an
@@ -399,7 +404,7 @@ class ScopeBuilder {
                 // (a branch with nowhere to go), blocks a new chain.
                 const dangling = this._open.filter((e) => e.condition !== undefined || e.defaultOf !== undefined || !this.hasExplicitOutgoing(e.source));
                 if (dangling.length > 0) {
-                    throw new Error(`startEvent "${node.id}" begins a new chain while "${dangling.map((e) => e.source).join('", "')}" is still ` +
+                    throw new CompileRefusal('BPMN_START_WHILE_PATH_OPEN', `startEvent "${node.id}" begins a new chain while "${dangling.map((e) => e.source).join('", "')}" is still ` +
                         `open — end the current path with an end event before starting another.`);
                 }
             }
@@ -408,7 +413,7 @@ class ScopeBuilder {
             // wired INTO, and its outgoing flows are the author's to write — and whatever
             // follows it is checked at close for an explicit incoming edge.
             if (GATEWAY_NODE_KINDS.has(node.kind) && !viaSugar && this._isArm) {
-                throw new Error(`${node.kind} "${node.id}": inside a body, branch with .choose() / .fork() / .race() — ` +
+                throw new CompileRefusal('BPMN_GATEWAY_IN_BODY', `${node.kind} "${node.id}": inside a body, branch with .choose() / .fork() / .race() — ` +
                     `a bare gateway's outgoing flows cannot be implied.`);
             }
         }
@@ -416,7 +421,7 @@ class ScopeBuilder {
         if (target) {
             if (this._mode === 'sequence' && this._started && this._open.length === 0) {
                 if (this._isArm) {
-                    throw new Error(`"${node.id}" is unreachable: the path ended before it (an end event, or every arm of a branch), so nothing leads to it.`);
+                    throw new CompileRefusal('BPMN_UNREACHABLE_IN_BODY', `"${node.id}" is unreachable: the path ended before it (an end event, or every arm of a branch), so nothing leads to it.`);
                 }
                 // Placed with nothing implied into it. Legal only if an explicit flow leads
                 // here — which may be written later — so it is checked when the scope closes.
@@ -520,7 +525,7 @@ class ScopeBuilder {
             const clash = here.list.find((o) => o.catchAll === caught.catchAll && o.ref === caught.ref);
             if (clash !== undefined) {
                 const where = here.key !== undefined ? `on "${here.key}"` : 'in this scope';
-                throw new Error(`"${n.id}" catches the same error as "${clash.id}" ${where} ` +
+                throw new CompileRefusal('BPMN_DUP_ERROR_CATCH', `"${n.id}" catches the same error as "${clash.id}" ${where} ` +
                     `(${caught.catchAll ? 'both catch ANY error' : `both catch "${caught.ref}"`}), so one of the two can ` +
                     'never run. Catch a specific error in each, or keep the one catch-all.');
             }
@@ -530,14 +535,14 @@ class ScopeBuilder {
         }
         for (const { id, after } of this._unattached) {
             if (!this._flows.some((f) => f.target === id)) {
-                throw new Error(`"${id}" has no incoming flow. In a sequence scope it was placed after "${after}", which does not ` +
+                throw new CompileRefusal('BPMN_SEQUENCE_NO_INCOMING', `"${id}" has no incoming flow. In a sequence scope it was placed after "${after}", which does not ` +
                     `continue to it (a bare gateway's outgoing flows are never implied; an end event ends the path). ` +
                     `Wire it with .sequenceFlow(…, "${id}"), or place it after an element that continues.`);
             }
         }
         for (const { id, reason } of this._storage.mustClose) {
             if (!this._flows.some((f) => f.source === id)) {
-                throw new Error(`${reason} ends at "${id}", which has no outgoing flow. A non-interrupting handler runs beside a token ` +
+                throw new CompileRefusal('BPMN_HANDLER_PATH_NOT_CLOSED', `${reason} ends at "${id}", which has no outgoing flow. A non-interrupting handler runs beside a token ` +
                     `that will reach the next statement anyway, so its path cannot rejoin there: end it with an end event, ` +
                     `leave it with .goto(), or wire it with .sequenceFlow("${id}", …).`);
             }
@@ -546,11 +551,11 @@ class ScopeBuilder {
         for (const exit of this._open) {
             const who = exit.origin ?? what;
             if (exit.condition !== undefined || exit.defaultOf !== undefined) {
-                throw new Error(`${who} has nowhere to go: nothing follows the branch in ${what}. Add the element that comes ` +
+                throw new CompileRefusal('BPMN_BRANCH_NOWHERE_TO_GO', `${who} has nowhere to go: nothing follows the branch in ${what}. Add the element that comes ` +
                     `next, or end every arm inside its own body.`);
             }
             if (!this._flows.some((f) => f.source === exit.source)) {
-                throw new Error(`${who} ends at "${exit.source}", which has no outgoing flow, and nothing follows it in ${what} ` +
+                throw new CompileRefusal('BPMN_PATH_NOT_CONTINUED', `${who} ends at "${exit.source}", which has no outgoing flow, and nothing follows it in ${what} ` +
                     `to continue it. Add the element that comes next, end the path with an end event, or wire it with ` +
                     `.sequenceFlow("${exit.source}", …).`);
             }
@@ -588,10 +593,10 @@ class ScopeBuilder {
         const { opts } = spec;
         const id = opts.id ?? `${activityId}_${suffix}`;
         if (this._nodes.some((n) => n.id === id)) {
-            throw new Error(`"${activityId}" already has a boundary event "${id}"; a second .${suffix}() on one activity needs its own \`id\`.`);
+            throw new CompileRefusal('BPMN_DUP_BOUNDARY_ID', `"${activityId}" already has a boundary event "${id}"; a second .${suffix}() on one activity needs its own \`id\`.`);
         }
         if (opts.errorVar !== undefined && opts.payload !== undefined) {
-            throw new Error(`.${suffix}() on "${activityId}": pass \`errorVar\` or \`payload\`, not both — both write the event's output row.`);
+            throw new CompileRefusal('BPMN_ERROR_VAR_AND_PAYLOAD', `.${suffix}() on "${activityId}": pass \`errorVar\` or \`payload\`, not both — both write the event's output row.`);
         }
         // Two handlers on one activity catching the SAME error: whichever the runtime picks,
         // the other is dead, and the platform rejects the pair outright
@@ -607,7 +612,7 @@ class ScopeBuilder {
                 return other !== undefined && other.catchAll === caught.catchAll && other.ref === caught.ref;
             });
             if (clash !== undefined) {
-                throw new Error(`.${suffix}() on "${activityId}" catches the same error as "${clash.id}" ` +
+                throw new CompileRefusal('BPMN_DUP_ERROR_CATCH', `.${suffix}() on "${activityId}" catches the same error as "${clash.id}" ` +
                     `(${caught.catchAll ? 'both catch ANY error' : `both catch "${caught.ref}"`}), so one of the two can never ` +
                     'run. Catch a specific error in each handler, or keep the one catch-all.');
             }
@@ -661,7 +666,7 @@ class ScopeBuilder {
             if (mustWait) {
                 const first = ab._first;
                 if (!first || !waitsForEvent(first)) {
-                    throw new Error(`${what}: arm ${i + 1} must begin with what it waits for — an intermediateCatchEvent (message or timer), ` +
+                    throw new CompileRefusal('BPMN_RACE_ARM_NOT_WAIT', `${what}: arm ${i + 1} must begin with what it waits for — an intermediateCatchEvent (message or timer), ` +
                         `a receiveMessage, or a waitForEvent — but begins with ${first ? `${first.kind} "${first.id}"` : 'nothing'}.`);
                 }
             }
@@ -669,7 +674,7 @@ class ScopeBuilder {
         });
         const empties = exits.filter((e) => e.source === split.id);
         if (empties.length > 1) {
-            throw new Error(`${what} has ${empties.length} arms with no body; at most one arm may be empty.`);
+            throw new CompileRefusal('BPMN_BRANCH_EMPTY_ARMS', `${what} has ${empties.length} arms with no body; at most one arm may be empty.`);
         }
         if (exits.length >= 2) {
             // Only when more than one arm actually reaches the continuation: a single
@@ -705,15 +710,15 @@ class ScopeBuilder {
      */
     startEvent(id, opts = {}) {
         if (opts.trigger !== undefined && opts.timer === undefined) {
-            throw new Error(`startEvent "${id}": \`trigger\` needs \`timer\` — the schedule lives in the ` +
+            throw new CompileRefusal('BPMN_START_TRIGGER_NO_TIMER', `startEvent "${id}": \`trigger\` needs \`timer\` — the schedule lives in the ` +
                 `bpmn:timerEventDefinition, not in the trigger extension, so a trigger without one emits an ` +
                 `empty definition and fires never. \`uip maestro bpmn validate\` reports that as Valid.`);
         }
         if (opts.trigger !== undefined && opts.payload !== undefined) {
-            throw new Error(`startEvent "${id}": \`trigger\` and \`payload\` both write the event's extension element; pass one.`);
+            throw new CompileRefusal('BPMN_START_TRIGGER_AND_PAYLOAD', `startEvent "${id}": \`trigger\` and \`payload\` both write the event's extension element; pass one.`);
         }
         if (opts.interrupting === false && opts.error !== undefined) {
-            throw new Error(`startEvent "${id}": an error start is always interrupting — the throw has already ended the scope it came from.`);
+            throw new CompileRefusal('BPMN_ERROR_START_NOT_INTERRUPTING', `startEvent "${id}": an error start is always interrupting — the throw has already ended the scope it came from.`);
         }
         return this.push({
             kind: 'startEvent',
@@ -793,7 +798,7 @@ class ScopeBuilder {
         else if (opts.message !== undefined)
             event = { type: 'message', messageRef: this._defs.messageRef(opts.message) };
         else
-            throw new Error(`boundaryEvent "${id}" needs one of { message, timer, error }.`);
+            throw new CompileRefusal('BPMN_BOUNDARY_NO_EVENT', `boundaryEvent "${id}" needs one of { message, timer, error }.`);
         return this.push({
             kind: 'boundaryEvent',
             id,
@@ -930,11 +935,16 @@ class ScopeBuilder {
      * ```
      */
     plainTask(id, opts = {}, body) {
+        const element = opts.element ?? 'bpmn:task';
+        // `element` is only type-restricted, and a `.bpmn.ts` loads without a type check.
+        if (!PLAIN_TASK_ELEMENTS.has(element)) {
+            throw new CompileRefusal('BPMN_PLAIN_TASK_ELEMENT_INVALID', `.plainTask('${id}'): element "${element}" is not a plain task element. Use one of ${[...PLAIN_TASK_ELEMENTS].join(', ')}.`);
+        }
         return this.pushActivity({
             kind: 'plainTask',
             id,
             name: opts.name,
-            element: opts.element ?? 'bpmn:task',
+            element,
             tags: opts.tags,
             retry: opts.retry,
             errorMapping: opts.errorMapping,
@@ -952,7 +962,7 @@ class ScopeBuilder {
             ? makeConnector(a, b, c, bpmnOpts)
             : makeConnector(a, b, bpmnOpts);
         if (spec.kind !== 'connector')
-            throw new Error('connector(): unexpected spec kind');
+            throw new Error('internal SDK error: connector(): unexpected spec kind');
         return this.pushActivity({
             kind: 'connector',
             id,
@@ -1013,7 +1023,7 @@ class ScopeBuilder {
         if (opts.connection !== undefined)
             return this.connectorHttp(id, opts, body);
         if (opts.folder !== undefined || opts.connectorKey !== undefined) {
-            throw new Error(`http "${id}": \`folder\` and \`connectorKey\` belong to connector mode, which \`connection\` selects — ` +
+            throw new CompileRefusal('BPMN_HTTP_CONNECTOR_FIELDS_NO_CONNECTION', `http "${id}": \`folder\` and \`connectorKey\` belong to connector mode, which \`connection\` selects — ` +
                 `pass the connection's binding name too, or drop them for a connectionless request.`);
         }
         return this.pushActivity({
@@ -1052,7 +1062,7 @@ class ScopeBuilder {
         const codeVar = `${id}_code`;
         const headersVar = `${id}_headers`;
         if (opts.outputVar === codeVar || opts.outputVar === headersVar) {
-            throw new Error(`http "${id}": outputVar "${opts.outputVar}" is the variable connector mode writes the status code or headers to. ` +
+            throw new CompileRefusal('BPMN_HTTP_OUTPUT_VAR_RESERVED', `http "${id}": outputVar "${opts.outputVar}" is the variable connector mode writes the status code or headers to. ` +
                 `Pick another name, or drop outputVar for the default "${id}_response".`);
         }
         const connection = this.dataServiceBinding(id, 'connection', opts.connection, 'ConnectionId', MANAGED_HTTP_CONNECTION_NAME);
@@ -1235,7 +1245,7 @@ class ScopeBuilder {
                         decl.resourceKey = keyed.key;
                     else if (decl.resourceKey !== keyed.key) {
                         const resource = field.bindingInfo?.resource ?? 'process';
-                        throw new Error(`${type} "${id}": its ${resource} key "${keyed.key}" is read through =bindings.${decl.id}, whose resource key is already ` +
+                        throw new CompileRefusal('BPMN_BINDING_RESOURCE_KEY_CONFLICT', `${type} "${id}": its ${resource} key "${keyed.key}" is read through =bindings.${decl.id}, whose resource key is already ` +
                             `"${decl.resourceKey}" (another node's pair, or the binding's own), so the pair would name two resources. ` +
                             `A ${resource} binding names one: declare one per node, e.g. ` +
                             `\`.binding('${decl.id}_${id}', { resource: '${decl.resource}', propertyAttribute: '${decl.propertyAttribute}', value: '${decl.default}' })\`.`);
@@ -1266,7 +1276,7 @@ class ScopeBuilder {
             const { field: blockedField, ref } = resolved.blocked;
             const refId = ref.slice('=bindings.'.length);
             const resource = field.bindingInfo?.resource ?? 'process';
-            throw new Error(`${type} "${id}": ${blockedField} reads ${ref}, which no .binding() declares with a value before this node, ` +
+            throw new CompileRefusal('BPMN_BINDING_READ_BEFORE_DECLARED', `${type} "${id}": ${blockedField} reads ${ref}, which no .binding() declares with a value before this node, ` +
                 `so the ${resource} key \`${pattern}\` it is paired under cannot be built. Declare ` +
                 `\`.binding('${refId}', { resource: '${resource}', propertyAttribute: '${blockedField}', value: '…' })\` first, or pass the value itself.`);
         }
@@ -1463,7 +1473,7 @@ class ScopeBuilder {
      */
     businessRule(id, opts, body) {
         if (opts.releaseKey !== undefined || opts.folderKey !== undefined) {
-            throw new Error(`businessRule('${id}'): a business rule is addressed by name and folder (version v3 binds the ` +
+            throw new CompileRefusal('BPMN_BUSINESS_RULE_KEY_FIELDS', `businessRule('${id}'): a business rule is addressed by name and folder (version v3 binds the ` +
                 'BusinessRule resource by `name` + `folderPath`); drop `releaseKey` / `folderKey`.');
         }
         // The default output variable is pinned rather than derived. Derived, it would come
@@ -1608,7 +1618,7 @@ class ScopeBuilder {
         const hasApp = opts.app !== undefined;
         const hasForm = opts.form !== undefined;
         if (hasApp === hasForm) {
-            throw new Error(`humanTask "${id}": pass exactly one of app (a deployed Action App) or form ({ fields, outcomes }, an inline form that needs no app).`);
+            throw new CompileRefusal('BPMN_HUMAN_TASK_APP_XOR_FORM', `humanTask "${id}": pass exactly one of app (a deployed Action App) or form ({ fields, outcomes }, an inline form that needs no app).`);
         }
         if (hasForm) {
             const o = opts;
@@ -1616,7 +1626,7 @@ class ScopeBuilder {
             // outcomes (`actions`) and what the human sees (`input`).
             const appOnly = ['appVersion', 'actions', 'key', 'input'].filter((k) => opts[k] !== undefined);
             if (appOnly.length) {
-                throw new Error(`humanTask "${id}": ${appOnly.join(', ')} belong to an app-backed task. On an inline form, put the outcomes in form.outcomes and what the human sees in form.fields.`);
+                throw new CompileRefusal('BPMN_HUMAN_TASK_APP_FIELDS_ON_FORM', `humanTask "${id}": ${appOnly.join(', ')} belong to an app-backed task. On an inline form, put the outcomes in form.outcomes and what the human sees in form.fields.`);
             }
             const rows = quickHumanTaskRows(id, this._sugar.processId, o);
             return this.pushActivity({
@@ -2046,16 +2056,16 @@ class ScopeBuilder {
     eventSubProcess(id, opts, fn) {
         const given = [opts.error !== undefined, opts.message !== undefined, opts.timer !== undefined].filter(Boolean).length;
         if (given !== 1) {
-            throw new Error(`eventSubProcess "${id}" needs exactly one of { error, message, timer } — that is what starts it.`);
+            throw new CompileRefusal('BPMN_EVENT_SUBPROCESS_START_COUNT', `eventSubProcess "${id}" needs exactly one of { error, message, timer } — that is what starts it.`);
         }
         if (opts.error !== undefined && opts.interrupting === false) {
-            throw new Error(`eventSubProcess "${id}": an error start is always interrupting — the throw has already ended the scope it came from.`);
+            throw new CompileRefusal('BPMN_ERROR_START_NOT_INTERRUPTING', `eventSubProcess "${id}": an error start is always interrupting — the throw has already ended the scope it came from.`);
         }
         if (opts.errorVar !== undefined && opts.errorVar !== false && opts.error === undefined) {
-            throw new Error(`eventSubProcess "${id}": \`errorVar\` captures an error, so it needs \`error\`.`);
+            throw new CompileRefusal('BPMN_ERROR_VAR_WITHOUT_ERROR', `eventSubProcess "${id}": \`errorVar\` captures an error, so it needs \`error\`.`);
         }
         if (typeof opts.errorVar === 'string' && opts.startPayload !== undefined) {
-            throw new Error(`eventSubProcess "${id}": pass \`errorVar\` or \`startPayload\`, not both — both write the start event's output row.`);
+            throw new CompileRefusal('BPMN_ERROR_VAR_AND_PAYLOAD', `eventSubProcess "${id}": pass \`errorVar\` or \`startPayload\`, not both — both write the start event's output row.`);
         }
         // The capture row is on by default for an error start: without a declared `Error`
         // the platform validator rejects every `vars.Error` read in the net. An explicit
@@ -2078,7 +2088,7 @@ class ScopeBuilder {
                 return other !== undefined && other.catchAll === (mineRef === undefined) && other.ref === mineRef;
             });
             if (clash !== undefined) {
-                throw new Error(`eventSubProcess "${id}" catches the same error as "${clash.id}" in this scope ` +
+                throw new CompileRefusal('BPMN_DUP_ERROR_CATCH', `eventSubProcess "${id}" catches the same error as "${clash.id}" in this scope ` +
                     `(${mineRef === undefined ? 'both catch ANY error' : `both catch "${mineRef}"`}), so one of the ` +
                     'two can never run. Catch a specific error in each net, or keep the one catch-all.');
             }
@@ -2151,13 +2161,13 @@ class ScopeBuilder {
      */
     choose(id, arms, opts = {}) {
         if (!arms.length)
-            throw new Error(`choose "${id}" has no arms.`);
+            throw new CompileRefusal('BPMN_BRANCH_NO_ARMS', `choose "${id}" has no arms.`);
         if (arms.filter((a) => a.otherwise).length > 1) {
-            throw new Error(`choose "${id}" has more than one \`otherwise\` arm; at most one.`);
+            throw new CompileRefusal('BPMN_CHOOSE_MANY_OTHERWISE', `choose "${id}" has more than one \`otherwise\` arm; at most one.`);
         }
         for (const a of arms) {
             if (a.when === undefined && !a.otherwise)
-                throw new Error(`choose "${id}": every arm needs \`when\` or \`otherwise: true\`.`);
+                throw new CompileRefusal('BPMN_CHOOSE_ARM_NO_WHEN', `choose "${id}": every arm needs \`when\` or \`otherwise: true\`.`);
         }
         const kind = opts.inclusive ? 'inclusiveGateway' : 'exclusiveGateway';
         const split = { kind, id, name: opts.name };
@@ -2199,7 +2209,7 @@ class ScopeBuilder {
      */
     fork(id, arms, opts = {}) {
         if (!arms.length)
-            throw new Error(`fork "${id}" has no arms.`);
+            throw new CompileRefusal('BPMN_BRANCH_NO_ARMS', `fork "${id}" has no arms.`);
         return this.branch({ kind: 'parallelGateway', id, name: opts.name }, 'parallelGateway', arms.map((body, i) => ({ entry: { source: id, origin: `arm ${i + 1} of fork "${id}"` }, body })), `fork "${id}"`, false, opts.join);
     }
     /**
@@ -2234,7 +2244,7 @@ class ScopeBuilder {
      */
     race(id, arms, opts = {}) {
         if (!arms.length)
-            throw new Error(`race "${id}" has no arms.`);
+            throw new CompileRefusal('BPMN_BRANCH_NO_ARMS', `race "${id}" has no arms.`);
         return this.branch({ kind: 'eventBasedGateway', id, name: opts.name }, 'exclusiveGateway', arms.map((body, i) => ({ entry: { source: id, origin: `arm ${i + 1} of race "${id}"` }, body })), `race "${id}"`, true, opts.join);
     }
     // ── Flows ──
@@ -2487,11 +2497,11 @@ export class SubProcessBuilder extends ScopeBuilder {
                 continue;
             const hasDefinition = n.event !== undefined || n.trigger !== undefined;
             if (opts.triggeredByEvent === true && !hasDefinition) {
-                throw new Error(`sub-process "${id}" is \`triggeredByEvent\`, so its start event "${n.id}" needs the event that starts it — ` +
+                throw new CompileRefusal('BPMN_SUBPROCESS_START_NO_EVENT', `sub-process "${id}" is \`triggeredByEvent\`, so its start event "${n.id}" needs the event that starts it — ` +
                     'an `error`, `message` or `timer`. `.eventSubProcess(id, { error: true }, fn)` writes that start for you.');
             }
             if (opts.triggeredByEvent !== true && hasDefinition) {
-                throw new Error(`sub-process "${id}" is entered by an incoming flow, so its start event "${n.id}" must not carry an event ` +
+                throw new CompileRefusal('BPMN_SUBPROCESS_START_HAS_EVENT', `sub-process "${id}" is entered by an incoming flow, so its start event "${n.id}" must not carry an event ` +
                     'definition. Drop it, or make this an event sub-process with `.eventSubProcess()`.');
             }
         }
@@ -2576,7 +2586,7 @@ export class PathBuilder extends ScopeBuilder {
      */
     goto(target) {
         if (this._closedBy !== undefined)
-            throw new Error(`.goto("${target}") follows ${this._closedBy}; an arm leaves once.`);
+            throw new CompileRefusal('BPMN_PATH_ALREADY_LEFT', `.goto("${target}") follows ${this._closedBy}; an arm leaves once.`);
         for (const exit of this._open)
             this.writeImpliedFlow(exit, target);
         this._open = [];
@@ -2753,7 +2763,7 @@ export class BpmnBuilder extends ScopeBuilder {
     schemaVersion(version) {
         const refusal = schemaVersionRefusal(BPMN_SCHEMA_VERSIONS, version);
         if (refusal)
-            throw new Error(refusal);
+            throw new CompileRefusal('SCHEMA_VERSION_UNSUPPORTED', refusal);
         this._metadata = { ...this._metadata, migrationVersion: version };
         return this;
     }

package/dist/bpmn/connector.js

@@ -1,10 +1,11 @@
 import { connectorOutputVars } from './declared-vars.js';
 import { EQUALS_EXPR_DIALECT } from '../core/connector-checks.js';
 import { buildConnectorInputs, nestConnectorBody, transportHttpMethod } from '../core/connector-inputs.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 export function createConnectorTask(ctx, n) {
     const { m } = ctx;
     if (!ctx.library)
-        throw new Error(`connector task "${n.id}" needs the connector library — pass { library } to serialize or use uip maestro bpmn compile --library.`);
+        throw new CompileRefusal('LIBRARY_REQUIRED', `connector task "${n.id}" needs the connector library — pass { library } to serialize or use uip maestro bpmn compile --library.`);
     const rc = ctx.library.resolve(n.key, n.action, n.version, n.object);
     const outVars = connectorOutputVars(n);
     const op = (rc.entry.operation ?? {});

package/dist/bpmn/human-task-form.js

@@ -1,6 +1,7 @@
 import { FORM_FIELD_TYPES, formFieldJsonSchema, formFieldOptionsProblem, formFieldOptionsWhy, formFieldSettingProblems, formFieldSettingsWire, formFieldTypeHint, liftFormFieldSettings, validFormFieldTypesText, wireFormFieldType, } from '../core/form-field-type.js';
 import { outcomeIdOf } from '../core/hitl-routing.js';
 import { schemaId as stableSchemaId } from '../core/stable-id.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 /** The `uipath:type` version both the converter and Studio Web write for `Actions.HITL`. */
 const QUICK_TYPE_VERSION = 'v2';
 /** The response row the app variant derives from the registry; the quick form keeps it. */
@@ -56,44 +57,44 @@ function validate(id, input) {
     const { form } = input;
     const where = `humanTask "${id}"`;
     if (!Array.isArray(form.fields))
-        throw new Error(`${where}: form.fields must be an array.`);
+        throw new CompileRefusal('BPMN_FORM_FIELDS_NOT_ARRAY', `${where}: form.fields must be an array.`);
     if (!Array.isArray(form.outcomes) || form.outcomes.length === 0) {
-        throw new Error(`${where}: the form needs at least one outcome, e.g. outcomes: ['Approve', 'Reject'].`);
+        throw new CompileRefusal('BPMN_FORM_NO_OUTCOMES', `${where}: the form needs at least one outcome, e.g. outcomes: ['Approve', 'Reject'].`);
     }
     const ids = new Set();
     for (const f of form.fields) {
         if (typeof f.id !== 'string' || f.id === '')
-            throw new Error(`${where}: every form field needs an id.`);
+            throw new CompileRefusal('BPMN_FORM_FIELD_NO_ID', `${where}: every form field needs an id.`);
         if (ids.has(f.id))
-            throw new Error(`${where}: form field id "${f.id}" is used twice.`);
+            throw new CompileRefusal('BPMN_FORM_DUP_FIELD', `${where}: form field id "${f.id}" is used twice.`);
         ids.add(f.id);
         if (f.id === OUTCOME_KEY) {
-            throw new Error(`${where}: form field "${OUTCOME_KEY}" collides with the response's own "${OUTCOME_KEY}" — the outcome picked. Rename it, e.g. id: '${OUTCOME_KEY}Value'.`);
+            throw new CompileRefusal('BPMN_FORM_FIELD_OUTCOME_COLLISION', `${where}: form field "${OUTCOME_KEY}" collides with the response's own "${OUTCOME_KEY}" — the outcome picked. Rename it, e.g. id: '${OUTCOME_KEY}Value'.`);
         }
         if (!IDENTIFIER.test(f.id)) {
-            throw new Error(`${where}: form field "${f.id}" (${f.direction}) is not a name the runtime can read back as =${f.id}. ` +
+            throw new CompileRefusal('BPMN_FORM_FIELD_ID_NOT_IDENTIFIER', `${where}: form field "${f.id}" (${f.direction}) is not a name the runtime can read back as =${f.id}. ` +
                 `Use an identifier (letters, digits, _ or $), e.g. id: '${f.id.replace(/\W+(\w)?/g, (_m, c) => (c ?? '').toUpperCase())}'.`);
         }
         if (RESERVED_WORDS.has(f.id)) {
-            throw new Error(`${where}: form field "${f.id}" is a reserved word, which the runtime cannot bind as a name — it would lose every answer and the outcome. Rename it, e.g. id: '${f.id}Value'.`);
+            throw new CompileRefusal('BPMN_FORM_FIELD_ID_RESERVED', `${where}: form field "${f.id}" is a reserved word, which the runtime cannot bind as a name — it would lose every answer and the outcome. Rename it, e.g. id: '${f.id}Value'.`);
         }
         // The SDK's own spellings only. The product also resolves platform aliases such as
         // `System.String`, but those are not `FormFieldType`s: accepting one here would let a
         // decompile lift write source that does not type-check, so such an import stays verbatim.
         if (!FORM_FIELD_TYPES.includes(String(f.type))) {
-            throw new Error(`${where}: form field "${f.id}" has type "${String(f.type)}". Valid: ${validFormFieldTypesText()}. ${formFieldTypeHint(f.type)}`.trimEnd());
+            throw new CompileRefusal('BPMN_FORM_FIELD_TYPE_UNKNOWN', `${where}: form field "${f.id}" has type "${String(f.type)}". Valid: ${validFormFieldTypesText()}. ${formFieldTypeHint(f.type)}`.trimEnd());
         }
         // The checks Flow's form checker reports as errors: a picker the reviewer cannot
         // pick from, and a setting the platform's schema refuses. (Options on a field that
         // renders no picker is a warning there, and is not refused here.)
         if (formFieldOptionsProblem(f) === 'missing') {
-            throw new Error(`${where}: form field "${f.id}" ${formFieldOptionsWhy('missing', f.type)}. Add options: [{ id: 'o1', value: 'a', label: 'A' }, …].`);
+            throw new CompileRefusal('BPMN_FORM_FIELD_NO_OPTIONS', `${where}: form field "${f.id}" ${formFieldOptionsWhy('missing', f.type)}. Add options: [{ id: 'o1', value: 'a', label: 'A' }, …].`);
         }
         const settings = formFieldSettingProblems(f);
         if (settings.length)
-            throw new Error(`${where}: form field "${f.id}" sets ${settings.join('; ')}.`);
+            throw new CompileRefusal('BPMN_FORM_FIELD_SETTING_INVALID', `${where}: form field "${f.id}" sets ${settings.join('; ')}.`);
         if (isShown(f) && (typeof f.value !== 'string' || !f.value.startsWith('='))) {
-            throw new Error(`${where}: form field "${f.id}" (${f.direction}) needs a value — a =-expression such as '=vars.${f.id}' — or the form shows it empty.`);
+            throw new CompileRefusal('BPMN_FORM_FIELD_NO_VALUE', `${where}: form field "${f.id}" (${f.direction}) needs a value — a =-expression such as '=vars.${f.id}' — or the form shows it empty.`);
         }
     }
     // One variable, one writer. Two answers landing in one variable, or an `outputs`
@@ -105,7 +106,7 @@ function validate(id, input) {
     const claim = (variable, writer) => {
         const first = writers.get(variable);
         if (first !== undefined) {
-            throw new Error(`${where}: ${first} and ${writer} both write vars.${variable}, so one would overwrite the other. Give one a different variable.`);
+            throw new CompileRefusal('BPMN_FORM_DUP_VARIABLE_WRITER', `${where}: ${first} and ${writer} both write vars.${variable}, so one would overwrite the other. Give one a different variable.`);
         }
         writers.set(variable, writer);
     };
@@ -120,9 +121,9 @@ function validate(id, input) {
     form.outcomes.forEach((o, i) => {
         const name = typeof o === 'string' ? o : o?.name;
         if (typeof name !== 'string' || name.trim() === '')
-            throw new Error(`${where}: every outcome needs a name.`);
+            throw new CompileRefusal('BPMN_FORM_OUTCOME_NO_NAME', `${where}: every outcome needs a name.`);
         if (names.has(name))
-            throw new Error(`${where}: outcome "${name}" is listed twice.`);
+            throw new CompileRefusal('BPMN_FORM_DUP_OUTCOME', `${where}: outcome "${name}" is listed twice.`);
         names.add(name);
         // The schema's outcome ids must be unique too, and two names can reach one: an
         // explicit `id` repeated, or `Needs review` and `Needs-review`, which both derive
@@ -130,7 +131,7 @@ function validate(id, input) {
         const outcomeId = outcomeIdOf(o, i);
         const clash = outcomeIds.get(outcomeId);
         if (clash !== undefined) {
-            throw new Error(`${where}: outcomes "${clash}" and "${name}" both have the id "${outcomeId}". Give one an explicit, different id: { name: '${name}', id: '…' }.`);
+            throw new CompileRefusal('BPMN_FORM_DUP_OUTCOME_ID', `${where}: outcomes "${clash}" and "${name}" both have the id "${outcomeId}". Give one an explicit, different id: { name: '${name}', id: '…' }.`);
         }
         outcomeIds.set(outcomeId, name);
     });