@uipath/maestro-builder-sdk 6.64.0 → 6.66.0

package/dist/bpmn/intsvc.js

@@ -1,7 +1,8 @@
 import { createTypedNode, typedNodeOutputVar } from './typed-node.js';
 import { connectorBindingRef } from './connector.js';
-import { eventFilterJmes, eventFilterProblem, jmesString, jmesStringProblem, readEventFilter } from '../core/event-filters.js';
+import { eventFilterJmes, jmesString, jmesStringProblem, readEventFilterLeaf } from '../core/event-filters.js';
 import { resolveEventWhere } from '../core/lookups.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 /**
  * Which extension type an external invocation lowers to.
  *
@@ -57,14 +58,14 @@ export function intsvcOutputVar(n) {
  */
 export function createConnectorEvent(ctx, n) {
     if (!ctx.library)
-        throw new Error(`connector event "${n.id}" needs the connector library — pass { library } to serialize ` +
+        throw new CompileRefusal('LIBRARY_REQUIRED', `connector event "${n.id}" needs the connector library — pass { library } to serialize ` +
             `or use uip maestro bpmn compile --library.`);
     const rc = ctx.library.resolveEvent(n.subscribe, n.key, n.eventName, n.version, n.object);
     const op = (rc.entry.operation ?? {});
     const runtime = rc.entry.runtime ?? {};
     const type = runtime.serviceType;
     if (!type) {
-        throw new Error(`connector event ${n.key}/${n.eventName} has no runtime.serviceType in the library; ` +
+        throw new CompileRefusal('BPMN_EVENT_NO_SERVICE_TYPE', `connector event ${n.key}/${n.eventName} has no runtime.serviceType in the library; ` +
             `it cannot be authored as a BPMN node.`);
     }
     // The PLACEMENT decides the extension type — `.eventTrigger()` starts the
@@ -79,13 +80,13 @@ export function createConnectorEvent(ctx, n) {
     // .eventTrigger() instead", while the unprepared same node compiled.
     const expected = intsvcServiceType(n);
     if (type !== 'Intsvc.EventTrigger' && type !== 'Intsvc.WaitForEvent') {
-        throw new Error(`connector event "${n.id}" was authored as a ${n.subscribe} (${expected}), but the library ` +
+        throw new CompileRefusal('BPMN_EVENT_KIND_MISMATCH', `connector event "${n.id}" was authored as a ${n.subscribe} (${expected}), but the library ` +
             `describes ${n.key}/${n.eventName} as ${type}, which is not a connector event.`);
     }
     const conn = connectorBindingRef(ctx, n.connection, 'Connection', 'ConnectionId', `${rc.connectorKey} connection`);
     const folder = connectorBindingRef(ctx, n.folder, 'Connection', 'folderKey', 'FolderKey', conn?.resourceKey);
     if (!conn || !folder) {
-        throw new Error(`connector event "${n.id}" needs both a connection and a folder binding name — ` +
+        throw new CompileRefusal('BPMN_EVENT_BINDINGS_MISSING', `connector event "${n.id}" needs both a connection and a folder binding name — ` +
             `the type declares connectionId, folderId, folderPath and folderKey all required.`);
     }
     // The registry marks `operation` and `objectName` required AND hidden, so an
@@ -144,20 +145,20 @@ export function eventFilterBody(nodeId, scope, filters) {
     const scopeClauses = scopeEntries.map(([k, v]) => {
         const problem = jmesStringProblem(String(v));
         if (problem)
-            throw new Error(`connector event "${nodeId}": \`filter.${k}\`: ${problem}`);
+            throw new CompileRefusal('EVENT_FILTER_BACKSLASH', `connector event "${nodeId}": \`filter.${k}\`: ${problem}`);
         return `(${k} == ${jmesString(String(v))})`;
     });
     const conditions = (filters ?? []).map((leaf, i) => {
-        const { read } = readEventFilter(leaf);
-        if (!read) {
-            throw new Error(`connector event "${nodeId}": filters[${i}] must carry a field and exactly ONE operator ` +
-                `(contains, startsWith, endsWith, equals, notEquals, lessThan, lessThanOrEqual, greaterThan, ` +
-                `greaterThanOrEqual) — got ${JSON.stringify(leaf)}.`);
+        // The code `check` gives the same leaf (`core/event-checks.ts`).
+        const judged = readEventFilterLeaf(leaf);
+        if (judged.code !== undefined) {
+            throw new CompileRefusal(judged.code, judged.problem !== undefined
+                ? `connector event "${nodeId}": filters[${i}] on \`${judged.read?.field}\`: ${judged.problem}`
+                : `connector event "${nodeId}": filters[${i}] must carry a field and exactly ONE operator ` +
+                    `(contains, startsWith, endsWith, equals, notEquals, lessThan, lessThanOrEqual, greaterThan, ` +
+                    `greaterThanOrEqual) — got ${JSON.stringify(leaf)}.`);
         }
-        const problem = eventFilterProblem(read);
-        if (problem)
-            throw new Error(`connector event "${nodeId}": filters[${i}] on \`${read.field}\`: ${problem}`);
-        return `(${eventFilterJmes(read)})`;
+        return `(${eventFilterJmes(judged.read)})`;
     });
     const expression = [...scopeClauses, ...conditions].join(' && ');
     const body = {};
@@ -176,7 +177,7 @@ export function eventFilterBody(nodeId, scope, filters) {
  */
 export function createExternalTask(ctx, n) {
     if (!ctx.library)
-        throw new Error(`external ${n.family} "${n.id}" needs the connector library — pass { library } to serialize ` +
+        throw new CompileRefusal('LIBRARY_REQUIRED', `external ${n.family} "${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);
     const op = (rc.entry.operation ?? {});
@@ -186,14 +187,14 @@ export function createExternalTask(ctx, n) {
     // validator accepts and the runtime dispatches to the wrong handler family —
     // the Case SDK records the same trap in its Phase 4.4 notes.
     if (op.subType !== wanted) {
-        throw new Error(`external ${n.family} "${n.id}" needs ${wanted === 'AgentExecution' ? 'an' : 'a'} ${wanted} descriptor, but ` +
+        throw new CompileRefusal('EXTERNAL_TASK_DESCRIPTOR_CONTRACT', `external ${n.family} "${n.id}" needs ${wanted === 'AgentExecution' ? 'an' : 'a'} ${wanted} descriptor, but ` +
             `${n.key}/${n.action} is "${String(op.subType ?? 'untyped')}". ` +
             `The shipped library has very few of these — ${wanted === 'AgentExecution' ? '2' : '1'} operation(s).`);
     }
     const conn = connectorBindingRef(ctx, n.connection, 'Connection', 'ConnectionId', `${rc.connectorKey} connection`);
     const folder = connectorBindingRef(ctx, n.folder, 'Connection', 'folderKey', 'FolderKey', conn?.resourceKey);
     if (!conn || !folder) {
-        throw new Error(`external ${n.family} "${n.id}" needs both a connection and a folder binding name.`);
+        throw new CompileRefusal(conn ? 'EXTERNAL_TASK_FOLDER' : 'EXTERNAL_TASK_CONNECTION', `external ${n.family} "${n.id}" needs both a connection and a folder binding name.`);
     }
     return createTypedNode(ctx.m, n.id, EXTERNAL_SERVICE_TYPE[n.family][n.mode], {
         name: n.name ?? rc.entry.display?.label ?? n.action,

package/dist/bpmn/load.js

@@ -3,22 +3,23 @@ import { pathToFileURL } from 'node:url';
 import { resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 import { useThisSdkForAuthoredSource } from '../sdk-resolve.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 /** Resolve a user argument (a `.ts` path or a BaseName) to a bpmn source file. */
 export function resolveBpmnFile(arg) {
     const candidates = [arg, `${arg}.bpmn.ts`, `${arg}.ts`];
     for (const c of candidates)
         if (existsSync(resolve(c)))
             return resolve(c);
-    throw new Error(`bpmn source not found: tried ${candidates.join(', ')}`);
+    throw new CompileRefusal('BPMN_SOURCE_NOT_FOUND', `bpmn source not found: tried ${candidates.join(', ')}`);
 }
 export async function loadBuiltBpmn(file) {
     useThisSdkForAuthoredSource();
     const mod = await import(pathToFileURL(file).href);
     const exp = mod.default ?? mod.bpmn;
     if (!exp)
-        throw new Error(`${file} has no default export. Add: export default bpmn('id')...build();`);
+        throw new CompileRefusal('BPMN_NO_DEFAULT_EXPORT', `${file} has no default export. Add: export default bpmn('id')...build();`);
     const built = typeof exp.build === 'function' ? exp.build() : exp;
     if (!built || !Array.isArray(built.nodes))
-        throw new Error(`${file} default export is not a built bpmn. Did you call .build()?`);
+        throw new CompileRefusal('BPMN_EXPORT_NOT_BUILT', `${file} default export is not a built bpmn. Did you call .build()?`);
     return built;
 }

package/dist/bpmn/serialize.js

@@ -22,6 +22,7 @@ import { connectorOutputVars, typedNodeDeclaredVars } from './declared-vars.js';
 import { defaultEntryPointId } from './entry-point-id.js';
 import { parseXmlRanges } from './xml-ranges.js';
 import { ownEntry } from '../core/own-entry.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 const require = createRequire(import.meta.url);
 const uipathDescriptor = require('./uipath-moddle.v1.json');
 const NS = {
@@ -251,7 +252,16 @@ function jsonInputBodiesAsCdata(xml) {
                 collect(node.children);
         }
     };
-    collect(parseXmlRanges(xml));
+    let ranges;
+    try {
+        ranges = parseXmlRanges(xml);
+    }
+    catch (e) {
+        // `xml` is moddle's own output, so malformed XML here is the serializer's
+        // defect, not the author's. BPMN_XML_MALFORMED stays for what `bpmn merge` reads.
+        throw new Error(`internal SDK error: the serializer wrote malformed XML: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    collect(ranges);
     let out = xml;
     // Splice from the end so the earlier offsets stay valid.
     for (const input of bodies.sort((a, b) => b.innerStart - a.innerStart)) {
@@ -289,12 +299,12 @@ function cdata(name, text) {
         value = JSON.parse(text);
     }
     catch {
-        throw new Error(`json input "${name}" contains "]]>" and is not valid JSON, so it cannot be written as the single CDATA section the engine reads.`);
+        throw new CompileRefusal('BPMN_JSON_INPUT_CDATA_END', `json input "${name}" contains "]]>" and is not valid JSON, so it cannot be written as the single CDATA section the engine reads.`);
     }
     const escaped = text.replaceAll(']]>', ']]\\u003e');
     // Holds by the argument above; checked because a wrong payload here would be silent.
     if (JSON.stringify(JSON.parse(escaped)) !== JSON.stringify(value)) {
-        throw new Error(`json input "${name}": escaping "]]>" changed its value.`);
+        throw new Error(`internal SDK error: json input "${name}": escaping "]]>" changed its value.`);
     }
     return `<![CDATA[${escaped}]]>`;
 }
@@ -356,30 +366,35 @@ function stampEntryPointIds(ctx, built, flowElements, rootDefault) {
 /** Build the flowElements array for one scope, wiring all references within it. */
 function buildScope(ctx, nodes, flows) {
     const { m } = ctx;
-    const byId = new Map();
+    const nodeById = new Map();
+    const flowById = new Map();
     const nodeEls = nodes.map((n) => {
         const el = createNode(ctx, n);
-        byId.set(n.id, el);
+        nodeById.set(n.id, el);
         return el;
     });
     const flowEls = flows.map((f) => {
         const el = m.create('bpmn:SequenceFlow', { id: f.id, name: f.name });
         if (f.condition !== undefined)
             el.conditionExpression = m.create('bpmn:FormalExpression', { body: f.condition });
-        byId.set(f.id, el);
+        flowById.set(f.id, el);
         return el;
     });
-    const ref = (id, where) => {
+    // A flow endpoint and a boundary attachment name a node in this scope, as
+    // `check` resolves them (DANGLING_FLOW, BOUNDARY_UNATTACHED); a sequence flow
+    // is never one. A gateway default names a flow, or any element as before.
+    const ref = (byId, id, where, code) => {
         const el = byId.get(id);
         if (!el)
-            throw new Error(`${where} references unknown element id "${id}".`);
+            throw new CompileRefusal(code, `${where} references unknown element id "${id}".`);
         return el;
     };
+    const anyById = new Map([...nodeById, ...flowById]);
     // Wire sequence flows to source/target and populate incoming/outgoing.
     flows.forEach((f, i) => {
         const flowEl = flowEls[i];
-        const src = ref(f.source, `sequenceFlow "${f.id}"`);
-        const tgt = ref(f.target, `sequenceFlow "${f.id}"`);
+        const src = ref(nodeById, f.source, `sequenceFlow "${f.id}"`, 'DANGLING_FLOW');
+        const tgt = ref(nodeById, f.target, `sequenceFlow "${f.id}"`, 'DANGLING_FLOW');
         flowEl.sourceRef = src;
         flowEl.targetRef = tgt;
         (src.outgoing ??= []).push(flowEl);
@@ -389,9 +404,9 @@ function buildScope(ctx, nodes, flows) {
     nodes.forEach((n, i) => {
         const el = nodeEls[i];
         if (n.kind === 'boundaryEvent')
-            el.attachedToRef = ref(n.attachedTo, `boundaryEvent "${n.id}"`);
+            el.attachedToRef = ref(nodeById, n.attachedTo, `boundaryEvent "${n.id}"`, 'BOUNDARY_UNATTACHED');
         if ((n.kind === 'exclusiveGateway' || n.kind === 'inclusiveGateway') && n.default !== undefined)
-            el.default = ref(n.default, `gateway "${n.id}" default`);
+            el.default = ref(anyById, n.default, `gateway "${n.id}" default`, 'BPMN_GATEWAY_DEFAULT_UNKNOWN');
     });
     return [...nodeEls, ...flowEls];
 }
@@ -729,8 +744,9 @@ function eventDefinition(ctx, def) {
  */
 function moddleTaskType(element) {
     const [ns, local] = element.split(':');
+    // `.plainTask()` refuses any element outside `PlainTaskElement` (BPMN_PLAIN_TASK_ELEMENT_INVALID).
     if (!ns || !local)
-        throw new Error(`plainTask: "${element}" is not a qualified element name`);
+        throw new Error(`internal SDK error: plainTask: "${element}" is not a qualified element name`);
     return `${ns}:${local.charAt(0).toUpperCase()}${local.slice(1)}`;
 }
 function outputRows(ctx, map, custom = false) {

package/dist/bpmn/typed-node.js

@@ -3,6 +3,7 @@ import { resolveFromRegistry } from './registry-fallback.js';
 import { nestConnectorBody } from '../core/connector-inputs.js';
 import { types } from '../core/expr.js';
 import { ownEntry } from '../core/own-entry.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 const require = createRequire(import.meta.url);
 const REGISTRY = require('./registry-types.json');
 /** Every extension type in the snapshot, sorted. */
@@ -33,7 +34,7 @@ export function registryType(type, inline) {
     // for one the snapshot describes wrongly. See `ActivityNodeOpts.spec`.
     const spec = inline ?? REGISTRY.types[type] ?? resolveFromRegistry(type);
     if (!spec) {
-        throw new Error(`unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types `
+        throw new CompileRefusal('BPMN_TYPE_UNKNOWN', `unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types `
             + `(uip ${REGISTRY.provenance.uipVersion}) and the registry could not be asked for this one either — `
             + 'no `uip` on PATH, not logged in, or the type does not exist. '
             + 'Check the spelling with `uip maestro bpmn registry search <term>`, then refresh the snapshot with '
@@ -306,7 +307,7 @@ function contextRows(m, type, spec, supplied, verbatim = false) {
     ]);
     const unknown = Object.keys(supplied).filter((k) => !known.has(k));
     if (unknown.length) {
-        throw new Error(`context field(s) ${unknown.map((u) => `"${u}"`).join(', ')} are not declared by this extension type. ` +
+        throw new CompileRefusal('BPMN_CONTEXT_FIELD_UNKNOWN', `context field(s) ${unknown.map((u) => `"${u}"`).join(', ')} are not declared by this extension type. ` +
             `Declared: ${[...known].join(', ') || '(none)'}.`);
     }
     // Permitted-but-undeclared fields (a recorded `extraContext` gap) still have to
@@ -355,7 +356,7 @@ function inputRows(m, spec, inputs) {
     const keys = Object.keys(inputs);
     if (spec.inputPattern === 'none') {
         if (keys.length) {
-            throw new Error(`this extension type takes no inputs, but ${keys.length} were supplied (${keys.join(', ')}).`);
+            throw new CompileRefusal('BPMN_TYPE_NO_INPUTS', `this extension type takes no inputs, but ${keys.length} were supplied (${keys.join(', ')}).`);
         }
         return [];
     }
@@ -502,7 +503,7 @@ export function createTypedNode(m, id, type, input,
 varType) {
     const spec = registryType(type, input.spec);
     if (!spec.element || !spec.tag) {
-        throw new Error(`extension type "${type}" has no element/tag in the registry snapshot; it cannot be authored.`);
+        throw new CompileRefusal('BPMN_TYPE_NOT_AUTHORABLE', `extension type "${type}" has no element/tag in the registry snapshot; it cannot be authored.`);
     }
     const payload = {
         version: 'v1',
@@ -512,7 +513,7 @@ varType) {
     // carry it, and moddle would silently drop it (see ActivityOpts in bpmn-sdk).
     if (input.skipCondition !== undefined) {
         if (spec.tag === 'uipath:mapping') {
-            throw new Error(`extension type "${type}" serializes a uipath:mapping, which cannot carry a skipCondition.`);
+            throw new CompileRefusal('BPMN_TYPE_SKIP_UNSUPPORTED', `extension type "${type}" serializes a uipath:mapping, which cannot carry a skipCondition.`);
         }
         payload.skipCondition = input.skipCondition;
     }
@@ -636,7 +637,7 @@ export function verbatimOutputRows(m, rows) {
 export function createExtensionPayload(m, type, rows) {
     const spec = registryType(type);
     if (!spec.tag) {
-        throw new Error(`extension type "${type}" has no tag in the registry snapshot; it cannot be authored.`);
+        throw new CompileRefusal('BPMN_TYPE_NOT_AUTHORABLE', `extension type "${type}" has no tag in the registry snapshot; it cannot be authored.`);
     }
     const payload = {
         version: 'v1',
@@ -664,7 +665,7 @@ function finish(m, spec, id, name, payload) {
 /** `bpmn:SendTask` is already the moddle type name; keep it, but validate the shape. */
 function moddleElementOf(element) {
     if (!/^bpmn:[A-Z]/.test(element)) {
-        throw new Error(`registry element "${element}" is not a moddle type name (expected e.g. bpmn:SendTask).`);
+        throw new CompileRefusal('BPMN_TYPE_ELEMENT_INVALID', `registry element "${element}" is not a moddle type name (expected e.g. bpmn:SendTask).`);
     }
     return element;
 }

package/dist/bpmn/xml-ranges.d.ts

@@ -1,22 +1,3 @@
-/**
- * xml-ranges — locate elements by their SOURCE RANGE in an XML document.
- *
- * A tolerant scanner, not a parser: it reports where each element's text begins and
- * ends and nothing about what it means. That is all a merge needs, and it is the only
- * shape that can preserve an element **byte for byte** — the merged document is the
- * original text with a few ranges spliced, so anything untouched is untouched in the
- * literal sense, down to attribute order, quoting and indentation.
- *
- * Why not `bpmn-moddle`, which the SDK already depends on: a moddle round trip
- * normalises. It drops attributes its descriptor does not declare, and the whole point
- * of a brownfield merge is to carry through exactly the payloads the builder does NOT
- * model. Reading with moddle would lose the thing being preserved.
- *
- * Correspondingly, this file must not be mistaken for a general XML implementation. It
- * handles what a `.bpmn` contains — elements, attributes, comments, CDATA, processing
- * instructions, a doctype — and it assumes well-formed input, because every caller has
- * either just written the file or is about to hand it to a real parser anyway.
- */
 /** One element's place in the source text. */
 export interface XmlRange {
     /** Qualified name as written, e.g. `bpmn:scriptTask`. */

package/dist/bpmn/xml-ranges.js

@@ -17,6 +17,7 @@
  * instructions, a doctype — and it assumes well-formed input, because every caller has
  * either just written the file or is about to hand it to a real parser anyway.
  */
+import { CompileRefusal } from '../core/compile-refusal.js';
 const ATTRIBUTE = /([^\s=/>]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
 function parseAttributes(source) {
     const attributes = {};
@@ -44,13 +45,13 @@ function endOfTag(xml, from) {
             return i;
         }
     }
-    throw new Error(`xml-ranges: unterminated tag at offset ${from}`);
+    throw new CompileRefusal('BPMN_XML_MALFORMED', `xml-ranges: unterminated tag at offset ${from}`);
 }
 /** Skip a construct that ends with a known terminator; returns the offset past it. */
 function skipUntil(xml, from, terminator) {
     const at = xml.indexOf(terminator, from);
     if (at < 0)
-        throw new Error(`xml-ranges: unterminated ${terminator.trim()} at offset ${from}`);
+        throw new CompileRefusal('BPMN_XML_MALFORMED', `xml-ranges: unterminated ${terminator.trim()} at offset ${from}`);
     return at + terminator.length;
 }
 function* rawTags(xml) {
@@ -122,7 +123,7 @@ export function parseXmlRanges(xml) {
         if (tag.closing) {
             const node = stack.pop();
             if (!node)
-                throw new Error(`xml-ranges: stray </${tag.name}> at offset ${tag.start}`);
+                throw new CompileRefusal('BPMN_XML_MALFORMED', `xml-ranges: stray </${tag.name}> at offset ${tag.start}`);
             finish(tag, node, tag.end);
             continue;
         }
@@ -134,7 +135,7 @@ export function parseXmlRanges(xml) {
         stack.push({ tag, children: [] });
     }
     if (stack.length > 0) {
-        throw new Error(`xml-ranges: unclosed <${stack[stack.length - 1].tag.name}>`);
+        throw new CompileRefusal('BPMN_XML_MALFORMED', `xml-ranges: unclosed <${stack[stack.length - 1].tag.name}>`);
     }
     return roots;
 }

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

@@ -16,6 +16,7 @@
  * `case/check.ts`, not here.
  */
 import { type ExprDiagnostic } from '../core/expr-check.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 import type { BuiltCase } from './case-sdk.js';
 /** A diagnostic plus the part of the case it was found in. */
 export interface CaseLocatedDiagnostic extends ExprDiagnostic {
@@ -29,7 +30,7 @@ export declare function checkCaseExpressions(built: BuiltCase): CaseLocatedDiagn
  * `FlowBuildError`: `message` lists every problem; `diagnostics` carries them
  * structured.
  */
-export declare class CaseBuildError extends Error {
+export declare class CaseBuildError extends CompileRefusal {
     readonly diagnostics: CaseLocatedDiagnostic[];
     constructor(built: BuiltCase, diagnostics: CaseLocatedDiagnostic[]);
 }

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

@@ -16,6 +16,7 @@
  * `case/check.ts`, not here.
  */
 import { checkExpression } from '../core/expr-check.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 import { defaultActionOutputVar } from './action-output-var.js';
 const NOUN = 'case variable';
 const NAMESPACE = 'vars';
@@ -83,12 +84,13 @@ export function checkCaseExpressions(built) {
  * `FlowBuildError`: `message` lists every problem; `diagnostics` carries them
  * structured.
  */
-export class CaseBuildError extends Error {
+export class CaseBuildError extends CompileRefusal {
     diagnostics;
     constructor(built, diagnostics) {
         const label = built.name || built.id || 'case';
         const lines = diagnostics.map((d) => `  ✗ [${d.code}] in ${d.where}: ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
-        super(`Cannot build case "${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 case "${label}" — ${diagnostics.length} expression problem(s):\n${lines.join('\n')}`);
         this.name = 'CaseBuildError';
         this.diagnostics = diagnostics;
     }

package/dist/case/case-sdk.js

@@ -3,6 +3,7 @@ import { isTriggerDescriptor } from '../core/connectors.js';
 import { checkCaseExpressions, CaseBuildError } from './case-expr-check.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS, recordAuthoredCaseVersion } from './format-profile.js';
 import { schemaVersionRefusal } from '../schema-version.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 export { preserveCaseJson } from './preserve.js';
 export { CaseBuildError } from './case-expr-check.js';
 /**
@@ -115,11 +116,11 @@ export function eventTrigger(descriptorOrOpts = {}, descriptorOpts = {}) {
     const object = descriptor ? undefined : opts.object;
     if (object !== undefined) {
         if (opts.subscription)
-            throw new Error('eventTrigger: pass the watched object as `subscription.object` on a resolved subscription, not as `object`.');
+            throw new CompileRefusal('CASE_TRIGGER_OBJECT_AND_SUBSCRIPTION', 'eventTrigger: pass the watched object as `subscription.object` on a resolved subscription, not as `object`.');
         // Refuse padding rather than trim it: the value must match the SDD's
         // source object exactly, and a silent trim would hide the typo.
         if (typeof object !== 'string' || !object.trim() || object !== object.trim())
-            throw new Error('eventTrigger: `object` must be a non-empty string with no surrounding whitespace.');
+            throw new CompileRefusal('CASE_TRIGGER_OBJECT_INVALID', 'eventTrigger: `object` must be a non-empty string with no surrounding whitespace.');
     }
     return {
         kind: 'event',
@@ -178,7 +179,7 @@ class TaskBuilder {
     }
     setKind(kind) {
         if (this._kind)
-            throw new Error(`task "${this._name}": kind already set to "${this._kind}", cannot also be "${kind}".`);
+            throw new CompileRefusal('TASK_KIND_TWICE', `task "${this._name}": kind already set to "${this._kind}", cannot also be "${kind}".`);
         this._kind = kind;
     }
     reference(kind, name, opts = {}) {
@@ -530,7 +531,7 @@ class TaskBuilder {
             const type = (v.type ?? 'string');
             if ('assign' in v) {
                 if ('source' in v)
-                    throw new Error(`task "${this._name}": output "${name}" sets both source and assign — use source to extract a result field, assign for a custom output.`);
+                    throw new CompileRefusal('TASK_OUTPUT_SOURCE_AND_ASSIGN', `task "${this._name}": output "${name}" sets both source and assign — use source to extract a result field, assign for a custom output.`);
                 this._outputs.push({ var: name, source: customOutputValue(v.assign), type, custom: true });
             }
             else {
@@ -553,7 +554,7 @@ class TaskBuilder {
     /** @internal */
     _build() {
         if (!this._kind)
-            throw new Error(`task "${this._name}" has no kind — call .process()/.agent()/.rpa()/.action()/.connector()/.waitForTimer()/… once.`);
+            throw new CompileRefusal('TASK_NO_KIND', `task "${this._name}" has no kind — call .process()/.agent()/.rpa()/.action()/.connector()/.waitForTimer()/… once.`);
         // Task input binding is reference-mode only (REF_IO): a connector task takes
         // its inputs in `.connector()` / `.waitForConnector()`. Output extracts also
         // work on connector and wait-for-connector tasks: the task writes its own
@@ -563,14 +564,14 @@ class TaskBuilder {
         const REF_IO = new Set(['process', 'agent', 'rpa', 'api-workflow', 'case-management', 'flow-process', 'function', 'business-rule']);
         const CONNECTOR_OUTPUTS = new Set(['connector', 'wait-for-connector']);
         if (this._inputs && !REF_IO.has(this._kind))
-            throw new Error(`task "${this._name}": .inputs()/.outputs() are only supported on reference-mode tasks (process/agent/rpa/api-workflow/case-management/flow-process/function/business-rule), not "${this._kind}". A connector task takes its inputs in .connector() / .waitForConnector().`);
+            throw new CompileRefusal('TASK_INPUTS_UNSUPPORTED', `task "${this._name}": .inputs()/.outputs() are only supported on reference-mode tasks (process/agent/rpa/api-workflow/case-management/flow-process/function/business-rule), not "${this._kind}". A connector task takes its inputs in .connector() / .waitForConnector().`);
         if (this._outputs && !REF_IO.has(this._kind) && !CONNECTOR_OUTPUTS.has(this._kind))
-            throw new Error(`task "${this._name}": .outputs() is only supported on reference-mode tasks (process/agent/rpa/api-workflow/case-management/flow-process/function/business-rule) and on connector / wait-for-connector tasks, not "${this._kind}".`);
+            throw new CompileRefusal('TASK_OUTPUTS_UNSUPPORTED', `task "${this._name}": .outputs() is only supported on reference-mode tasks (process/agent/rpa/api-workflow/case-management/flow-process/function/business-rule) and on connector / wait-for-connector tasks, not "${this._kind}".`);
         if (REF_IO.has(this._kind) && !this._ref && (this._inputs || this._outputs))
-            throw new Error(`task "${this._name}": an unresolved reference task cannot declare inputs or outputs.`);
+            throw new CompileRefusal('TASK_IO_UNRESOLVED_REFERENCE', `task "${this._name}": an unresolved reference task cannot declare inputs or outputs.`);
         if (this._kind === 'wait-for-connector' && this._outputs
             && !(this._waitConnector && 'connector' in this._waitConnector && 'event' in this._waitConnector))
-            throw new Error(`task "${this._name}": a placeholder wait-for-connector task has no event response to extract outputs from — name the event (.waitForConnector(<trigger descriptor>) or { connector, event }).`);
+            throw new CompileRefusal('TASK_OUTPUTS_PLACEHOLDER_EVENT', `task "${this._name}": a placeholder wait-for-connector task has no event response to extract outputs from — name the event (.waitForConnector(<trigger descriptor>) or { connector, event }).`);
         return {
             name: this._name,
             kind: this._kind,
@@ -824,7 +825,7 @@ class CaseBuilder {
     schemaVersion(version) {
         const refusal = schemaVersionRefusal(CASE_SCHEMA_VERSIONS, version);
         if (refusal)
-            throw new Error(refusal);
+            throw new CompileRefusal('SCHEMA_VERSION_UNSUPPORTED', refusal);
         this._schemaVersion = version;
         return this;
     }

package/dist/case/load.js

@@ -3,6 +3,7 @@ import { pathToFileURL } from 'node:url';
 import { resolve } from 'node:path';
 import { existsSync, statSync } from 'node:fs';
 import { useThisSdkForAuthoredSource } from '../sdk-resolve.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 /**
  * Resolve a user argument (a `.ts` path or a BaseName) to a case source file.
  *
@@ -19,16 +20,16 @@ export function resolveCaseFile(arg) {
         if (existsSync(resolved) && statSync(resolved).isFile())
             return resolved;
     }
-    throw new Error(`case source not found: tried ${candidates.join(', ')}`);
+    throw new CompileRefusal('CASE_SOURCE_NOT_FOUND', `case source not found: tried ${candidates.join(', ')}`);
 }
 export async function loadBuiltCase(file) {
     useThisSdkForAuthoredSource();
     const mod = await import(pathToFileURL(file).href);
     const exp = mod.default ?? mod.casePlan ?? mod.case;
     if (!exp)
-        throw new Error(`${file} has no default export. Add: export default casePlan('id')...build();`);
+        throw new CompileRefusal('CASE_NO_DEFAULT_EXPORT', `${file} has no default export. Add: export default casePlan('id')...build();`);
     const built = typeof exp.build === 'function' ? exp.build() : exp;
     if (!built || !Array.isArray(built.stages))
-        throw new Error(`${file} default export is not a built case. Did you call .build()?`);
+        throw new CompileRefusal('CASE_EXPORT_NOT_BUILT', `${file} default export is not a built case. Did you call .build()?`);
     return built;
 }