@uipath/maestro-builder-sdk 6.63.0 → 6.65.0

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;
 }

package/dist/case/serialize.js

@@ -19,16 +19,17 @@ import { bindingLabelRefusal } from '../core/binding-messages.js';
 import { resolveEventWhere } from '../core/lookups.js';
 import { resolveCaseSubscription } from './subscription.js';
 import { dedupeConditionNames } from './rule-names.js';
-import { externalDescriptorRefusal, externalHybridRefusal, externalServiceType, isExternalExecutionMode } from './external.js';
+import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT, EXTERNAL_TASK_HYBRID_UNSUPPORTED, externalDescriptorRefusal, externalHybridRefusal, externalServiceType, isExternalExecutionMode, } from './external.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS } from './format-profile.js';
 import { isResourceLabelRefusal, resolveResourceRef, resourceIdentity } from './resource-identity.js';
 import { ownEntry } from '../core/own-entry.js';
 import { resolveSchemaVersion } from '../schema-version.js';
 import { caseJsonPreservation, caseJsonPreservationErrors, } from './preserve.js';
 import { businessEventProblems } from './business-event-shape.js';
-import { readEventFilter, eventFilterProblem, eventFilterTreeLeaf } from '../core/event-filters.js';
+import { readEventFilterLeaf, eventFilterTreeLeaf } from '../core/event-filters.js';
 import { responseJsonSchema } from '../core/connector-response-schema.js';
 import { ruleShapeProblems } from './rule-options.js';
+import { CompileRefusal } from '../core/compile-refusal.js';
 /**
  * Condition `displayName` allocator.
  *
@@ -135,7 +136,7 @@ export function serialize(built, opts = {}) {
     built.stages.forEach((stage, si) => {
         const sid = ids.stageId(`stage:${stage.label}`);
         if (resolver.stageIdByLabel.has(stage.label))
-            throw new Error(`duplicate stage label "${stage.label}".`);
+            throw new CompileRefusal('DUP_STAGE', `duplicate stage label "${stage.label}".`);
         resolver.stageIdByLabel.set(stage.label, sid);
         stageIds.push(sid);
         taskIds.push([]);
@@ -143,7 +144,7 @@ export function serialize(built, opts = {}) {
             taskIds[si].push([]);
             lane.forEach((task) => {
                 if (seenTaskNames.has(task.name))
-                    throw new Error(`duplicate task displayName "${task.name}" — task names must be unique across the case.`);
+                    throw new CompileRefusal('DUP_TASK', `duplicate task displayName "${task.name}" — task names must be unique across the case.`);
                 seenTaskNames.add(task.name);
                 const tid = ids.taskId(`task:${stage.label}/${task.name}`);
                 taskIds[si][li].push(tid);
@@ -187,13 +188,13 @@ export function serialize(built, opts = {}) {
     const selectNextStage = built.stages.flatMap((stage) => stage.exit)
         .filter((exit) => exit.selectNextStage !== undefined);
     if (selectNextStage.length > 1)
-        throw new Error('select-next-stage can be configured on at most one stage exit per case.');
+        throw new CompileRefusal('SELECT_NEXT_STAGE_MULTIPLE', 'select-next-stage can be configured on at most one stage exit per case.');
     if (selectNextStage[0]?.selectNextStage) {
         const { objectName, connector } = selectNextStage[0].selectNextStage;
         if (selectNextStage[0].type !== 'wait-for-user')
-            throw new Error('select-next-stage requires an exit with type "wait-for-user".');
+            throw new CompileRefusal('SELECT_NEXT_STAGE_EXIT_TYPE', 'select-next-stage requires an exit with type "wait-for-user".');
         if (!objectName.trim())
-            throw new Error('select-next-stage objectName must be non-empty.');
+            throw new CompileRefusal('SELECT_NEXT_STAGE_OBJECT_NAME', 'select-next-stage objectName must be non-empty.');
         const context = [];
         if (connector) {
             context.push(io('connectorKey', 'string', { value: connector.connectorKey }));
@@ -234,7 +235,7 @@ export function serialize(built, opts = {}) {
     if (built.businessEvents?.length) {
         const [problem] = businessEventProblems(built.businessEvents);
         if (problem)
-            throw new Error(problem.message);
+            throw new CompileRefusal(problem.code, problem.message);
         metadata.businessEvents = built.businessEvents.map(emitBusinessEvent);
     }
     // Variables: declared vars + the readable companions that REASSIGNED task
@@ -347,11 +348,11 @@ function applyAuthorLayout(result, authored) {
     const nodes = result.nodes;
     const layoutValue = result.layout;
     if (layoutValue !== undefined && (!layoutValue || typeof layoutValue !== 'object' || Array.isArray(layoutValue)))
-        throw new Error('case layout: preserved layout must be an object before authored entries can be applied.');
+        throw new Error('internal SDK error: case layout: preserved layout must be an object before authored entries can be applied.');
     const existingLayout = (layoutValue ?? {});
     const existingNodes = existingLayout.nodes;
     if (existingNodes !== undefined && (!existingNodes || typeof existingNodes !== 'object' || Array.isArray(existingNodes)))
-        throw new Error('case layout: preserved layout.nodes must be an object before authored entries can be applied.');
+        throw new Error('internal SDK error: case layout: preserved layout.nodes must be an object before authored entries can be applied.');
     const layoutNodes = { ...(existingNodes ?? {}) };
     const layout = { ...existingLayout, nodes: layoutNodes };
     for (const entry of entries) {
@@ -363,16 +364,16 @@ function applyAuthorLayout(result, authored) {
             return trigger && label === entry.name;
         });
         if (matches.length !== 1)
-            throw new Error(`case layout: ${entry.kind} "${entry.name}" matches ${matches.length} emitted nodes; expected exactly 1.`);
+            throw new CompileRefusal('CASE_LAYOUT_NODE_MATCH', `case layout: ${entry.kind} "${entry.name}" matches ${matches.length} emitted nodes; expected exactly 1.`);
         const nodeId = matches[0].id;
         if (typeof nodeId !== 'string' || !nodeId)
-            throw new Error(`case layout: ${entry.kind} "${entry.name}" has no emitted node id.`);
+            throw new Error(`internal SDK error: case layout: ${entry.kind} "${entry.name}" has no emitted node id.`);
         const unknown = Object.keys(entry.layout).filter((field) => !CASE_NODE_LAYOUT_FIELDS.includes(field));
         if (unknown.length)
-            throw new Error(`case layout: ${entry.kind} "${entry.name}" has unsupported field "${unknown[0]}".`);
+            throw new CompileRefusal('CASE_LAYOUT_UNKNOWN_FIELD', `case layout: ${entry.kind} "${entry.name}" has unsupported field "${unknown[0]}".`);
         const previous = layoutNodes[nodeId];
         if (previous !== undefined && (!previous || typeof previous !== 'object' || Array.isArray(previous)))
-            throw new Error(`case layout: preserved entry for ${entry.kind} "${entry.name}" must be an object.`);
+            throw new Error(`internal SDK error: case layout: preserved entry for ${entry.kind} "${entry.name}" must be an object.`);
         const merged = { ...(previous ?? {}) };
         for (const field of CASE_NODE_LAYOUT_FIELDS)
             if (entry.layout[field] !== undefined)
@@ -394,7 +395,7 @@ export function applyPreservation(result, preservation, options = {}) {
         return result;
     const errors = caseJsonPreservationErrors(preservation);
     if (errors.length)
-        throw new Error(`invalid Case JSON preservation payload: ${errors.join('; ')}`);
+        throw new CompileRefusal('PRESERVATION_COLLISION', `invalid Case JSON preservation payload: ${errors.join('; ')}`);
     applyPreservedIdentities(result, preservation);
     Object.assign(result, preservation.topLevel ?? {});
     Object.assign(result.metadata, preservation.metadata ?? {});
@@ -402,7 +403,7 @@ export function applyPreservation(result, preservation, options = {}) {
     if (caseAppConfig && preservation.caseAppConfigFields) {
         for (const [field, value] of Object.entries(preservation.caseAppConfigFields.fields ?? {})) {
             if (!options.overwrite && Object.prototype.hasOwnProperty.call(caseAppConfig, field))
-                throw new Error(`preserved caseAppConfig field "${field}" collides with serializer-owned output.`);
+                throw new CompileRefusal('PRESERVATION_FIELD_COLLISION', `preserved caseAppConfig field "${field}" collides with serializer-owned output.`);
             caseAppConfig[field] = value;
         }
         for (const entry of preservation.caseAppConfigFields.sections ?? []) {
@@ -411,7 +412,7 @@ export function applyPreservation(result, preservation, options = {}) {
                 continue;
             for (const [field, value] of Object.entries(entry.fields)) {
                 if (!options.overwrite && Object.prototype.hasOwnProperty.call(section, field))
-                    throw new Error(`preserved Case App section "${entry.id}" field "${field}" collides with serializer-owned output.`);
+                    throw new CompileRefusal('PRESERVATION_FIELD_COLLISION', `preserved Case App section "${entry.id}" field "${field}" collides with serializer-owned output.`);
                 section[field] = value;
             }
         }
@@ -431,10 +432,10 @@ export function applyPreservation(result, preservation, options = {}) {
             if (!row && options.overwrite)
                 continue;
             if (!row)
-                throw new Error(`preserved variable "${name}" was not regenerated in variables.${lane}.`);
+                throw new CompileRefusal('PRESERVATION_TARGET_MISSING', `preserved variable "${name}" was not regenerated in variables.${lane}.`);
             for (const [field, value] of Object.entries(fields)) {
                 if (!options.overwrite && Object.prototype.hasOwnProperty.call(row, field))
-                    throw new Error(`preserved variable "${name}" field "${field}" collides with serializer-owned output.`);
+                    throw new CompileRefusal('PRESERVATION_FIELD_COLLISION', `preserved variable "${name}" field "${field}" collides with serializer-owned output.`);
                 row[field] = value;
             }
         }
@@ -446,7 +447,7 @@ export function applyPreservation(result, preservation, options = {}) {
             if (!row && options.overwrite)
                 continue;
             if (!row)
-                throw new Error(`legacy variable default "${name}" was not regenerated in variables.${lane}.`);
+                throw new CompileRefusal('PRESERVATION_TARGET_MISSING', `legacy variable default "${name}" was not regenerated in variables.${lane}.`);
             const encoded = JSON.stringify(value);
             // The legacy row exists to carry the NON-STRING spelling of a value the
             // serializer now writes as a string, so it is only applicable while the two
@@ -457,7 +458,7 @@ export function applyPreservation(result, preservation, options = {}) {
             if (row.default !== encoded) {
                 if (options.overwrite)
                     continue;
-                throw new Error(`legacy variable default "${name}" does not match the serializer-owned default.`);
+                throw new CompileRefusal('PRESERVATION_LEGACY_DEFAULT_MISMATCH', `legacy variable default "${name}" does not match the serializer-owned default.`);
             }
             row.default = value;
         }
@@ -485,7 +486,7 @@ export function applyPreservation(result, preservation, options = {}) {
                 if (task[field] === value)
                     continue;
                 if (!options.overwrite)
-                    throw new Error(`preserved task "${entry.stage}/${entry.task}" field "${field}" collides with serializer-owned output.`);
+                    throw new CompileRefusal('PRESERVATION_FIELD_COLLISION', `preserved task "${entry.stage}/${entry.task}" field "${field}" collides with serializer-owned output.`);
             }
             task[field] = value;
         }
@@ -509,7 +510,7 @@ export function applyPreservation(result, preservation, options = {}) {
         if (!trigger && options.overwrite)
             continue;
         if (!trigger)
-            throw new Error(`trigger ${index + 1} was not regenerated for preserved data fields.`);
+            throw new CompileRefusal('PRESERVATION_TARGET_MISSING', `trigger ${index + 1} was not regenerated for preserved data fields.`);
         Object.assign(trigger.data, fields);
     }
     if (preservation.nodes?.length) {
@@ -721,7 +722,7 @@ function emitVariables(vars, ids, triggerNodeByRef) {
             return { default: vd.default };
         const value = JSON.stringify(vd.default);
         if (value === undefined)
-            throw new TypeError(`Case variable "${vd.name}" has a default that cannot be JSON encoded.`);
+            throw new CompileRefusal('CASE_VAR_DEFAULT_NOT_JSON', `Case variable "${vd.name}" has a default that cannot be JSON encoded.`);
         return { default: value };
     };
     const readableCompanion = (vd) => ({
@@ -748,7 +749,7 @@ function emitVariables(vars, ids, triggerNodeByRef) {
             // to the trigger node, so it does not also take a root companion.
             const node = triggerNodeByRef.get(vd.sourceTrigger);
             if (!node)
-                throw new Error(`In-arg "${vd.name}" is bound via { from } to a trigger that was not added with .trigger(...).`);
+                throw new CompileRefusal('CASE_IN_ARG_TRIGGER_NOT_ADDED', `In-arg "${vd.name}" is bound via { from } to a trigger that was not added with .trigger(...).`);
             entry.default = vd.default === undefined ? '' : encodedDefault(vd).default;
             entry.elementId = node.id;
             inputs.push(entry);
@@ -1038,7 +1039,7 @@ function withOutputExtracts(data, task, ids, resolver) {
     const own = Array.isArray(data.outputs) ? data.outputs : [];
     const elementId = own.find((row) => typeof row.elementId === 'string')?.elementId;
     if (!elementId)
-        throw new Error(`task "${task.name}": output extracts need the task's resolved response output.`);
+        throw new CompileRefusal('TASK_OUTPUTS_NO_RESPONSE', `task "${task.name}": output extracts need the task's resolved response output.`);
     data.outputs = [
         ...own,
         ...task.outputs.map((o, i) => emitTaskOutput(o, elementId, ids, `${elementId}:out:${i}:${o.var}`, resolver)),
@@ -1076,7 +1077,7 @@ function isResolvedSubscription(spec) {
  * by the archived v1 artifacts. Placeholder bags never enter this path. */
 function resolvedSubscriptionBag(kind, spec, resolver, elementId, where) {
     if (!resolver.library)
-        throw new Error(`${kind === 'trigger' ? 'event trigger' : 'wait-for-connector'} needs the connector library — `
+        throw new CompileRefusal('LIBRARY_REQUIRED', `${kind === 'trigger' ? 'event trigger' : 'wait-for-connector'} needs the connector library — `
             + `pass { library } to serialize or use uip maestro case compile --library.`);
     const rc = resolveCaseSubscription(resolver.library, kind, spec, { where, bindings: resolver.bindings });
     const op = rc.entry.operation ?? {};
@@ -1121,12 +1122,13 @@ function subscriptionMetadata(rc, op, filters, elementId) {
         filters: filters.map((entry, index) => {
             // Same authored shape as a flow's event filter, same designer grammar (see
             // `event-filters.ts`); a malformed leaf is refused rather than dropped.
-            const { read } = readEventFilter(entry);
-            if (!read)
-                throw new Error(`event filter ${index} must carry a field and exactly one operator — got ${JSON.stringify(entry)}.`);
-            const problem = eventFilterProblem(read);
-            if (problem)
-                throw new Error(`event filter ${index} on \`${read.field}\`: ${problem}`);
+            // The code `check` gives the same leaf (`core/event-checks.ts`).
+            const judged = readEventFilterLeaf(entry);
+            if (judged.code !== undefined)
+                throw new CompileRefusal(judged.code, judged.problem !== undefined
+                    ? `event filter ${index} on \`${judged.read?.field}\`: ${judged.problem}`
+                    : `event filter ${index} must carry a field and exactly one operator — got ${JSON.stringify(entry)}.`);
+            const { read } = judged;
             return {
                 ...eventFilterTreeLeaf(read),
                 uiId: stableUuid(`${elementId}:${read.field}:${String(read.value)}:${index}`),
@@ -1393,14 +1395,14 @@ function referenceBindings(kind, authored, resolver, ids, taskName) {
     // literal value, so the task binds exactly as the literal form does.
     const ref = resolveResourceRef(authored, resolver.bindings, `Task "${taskName}"`);
     if (isResourceLabelRefusal(ref))
-        throw new Error(`[${ref.code}] ${ref.message}`);
+        throw new CompileRefusal(ref.code, ref.message);
     const binding = kind === 'business-rule'
         ? { resource: BUSINESS_RULE_RESOURCE }
         : kind === 'action'
             ? { resource: ACTION_APP_RESOURCE }
             : ownEntry(REFERENCE_BINDING, kind);
     if (!binding)
-        throw new Error(`task kind "${kind}" is not a published-resource task.`);
+        throw new Error(`internal SDK error: task kind "${kind}" is not a published-resource task.`);
     // An in-solution resource (`folder: 'solution_folder'`) keeps the sentinel
     // in its key and binds an empty folderPath — see resource-identity.ts.
     const { resourceKey, folderPath } = resourceIdentity(ref.name, ref.folderPath);
@@ -1459,7 +1461,7 @@ function businessRuleTaskData(task, resolver, elementId, ids) {
  */
 function connectorTaskData(spec, resolver, elementId, where, executionType) {
     if (!resolver.library)
-        throw new Error(`connector task needs the connector library — pass { library } to serialize or use uip maestro case compile --library.`);
+        throw new CompileRefusal('LIBRARY_REQUIRED', `connector task needs the connector library — pass { library } to serialize or use uip maestro case compile --library.`);
     const rc = resolver.library.resolve(spec.key, spec.action, spec.version, spec.object);
     const op = rc.entry.operation ?? {};
     const context = [
@@ -1527,17 +1529,17 @@ function connectorTaskData(spec, resolver, elementId, where, executionType) {
  */
 function externalTaskData(kind, spec, resolver, elementId, where) {
     if (!resolver.library)
-        throw new Error(`${kind} task needs the connector library — pass { library } to serialize or use uip maestro case compile --library.`);
+        throw new CompileRefusal('LIBRARY_REQUIRED', `${kind} task needs the connector library — pass { library } to serialize or use uip maestro case compile --library.`);
     const rc = resolver.library.resolve(spec.connector.key, spec.connector.action, spec.connector.version, spec.connector.object);
     const refused = externalDescriptorRefusal(kind, rc);
     if (refused)
-        throw new Error(refused);
+        throw new CompileRefusal(EXTERNAL_TASK_DESCRIPTOR_CONTRACT, refused);
     if (!isExternalExecutionMode(spec.mode))
-        throw new Error(`${kind} task mode must be the connector object's executionType: "sync", "async" or "hybrid".`);
+        throw new CompileRefusal('EXTERNAL_TASK_MODE', `${kind} task mode must be the connector object's executionType: "sync", "async" or "hybrid".`);
     if (spec.mode === 'hybrid')
-        throw new Error(externalHybridRefusal(where));
+        throw new CompileRefusal(EXTERNAL_TASK_HYBRID_UNSUPPORTED, externalHybridRefusal(where));
     if (!spec.connector.connection || !spec.connector.folder)
-        throw new Error(`${kind} task requires non-empty connection and folder binding names.`);
+        throw new CompileRefusal(spec.connector.connection ? 'EXTERNAL_TASK_FOLDER' : 'EXTERNAL_TASK_CONNECTION', `${kind} task requires non-empty connection and folder binding names.`);
     const data = connectorTaskData(spec.connector, resolver, elementId, where, spec.mode);
     const context = data.context;
     const metadataAt = context.findIndex((row) => row.name === 'metadata');
@@ -1642,7 +1644,7 @@ function folderBindingRef(resolver, name, connection, site) {
     for (const row of resolver.bindingSink.values()) {
         if (row.resourceKey === connection.resourceKey && row.propertyAttribute === 'folderKey'
             && row.default !== folderKey)
-            throw new Error(`${site.where}: connection "${connection.resourceKey}" is bound to two folders: `
+            throw new CompileRefusal('BINDING_CONNECTION_TWO_FOLDERS', `${site.where}: connection "${connection.resourceKey}" is bound to two folders: `
                 + `"${String(row.name)}" (${String(row.default)}) and "${name}" (${folderKey}). `
                 + `A connection lives in one folder; use the same folder binding for every task on it.`);
     }
@@ -1826,13 +1828,13 @@ function emitRules(rules, seed, ownerId, ids, resolver, site) {
 function emitRule(r, seed, ownerId, ids, resolver, site) {
     const [shape] = ruleShapeProblems(r);
     if (shape)
-        throw new Error(`${shape.message.replace(/^Rule /, 'rule ')} (in ${site})`);
+        throw new CompileRefusal(shape.code, `${shape.message.replace(/^Rule /, 'rule ')} (in ${site})`);
     const ruleId = ids.ruleId(seed);
     const out = { rule: r.rule, id: ruleId };
     if (r.rule === 'selected-stage-completed' || r.rule === 'selected-stage-exited') {
         const sid = r.stage && resolver.stageIdByLabel.get(r.stage);
         if (!sid)
-            throw new Error(`rule "${r.rule}" references unknown stage "${r.stage}".`);
+            throw new CompileRefusal('UNKNOWN_STAGE_REF', `rule "${r.rule}" references unknown stage "${r.stage}".`);
         out[CASE_FORMAT_PROFILE.selectedStageField] = CASE_FORMAT_PROFILE.selectedStageCardinality === 'singular' ? sid : [sid];
     }
     if (r.rule === 'selected-tasks-completed') {
@@ -1840,7 +1842,7 @@ function emitRule(r, seed, ownerId, ids, resolver, site) {
         out.selectedTasksIds = names.map((n) => {
             const tid = resolver.taskIdByKey.get(n);
             if (!tid)
-                throw new Error(`rule "selected-tasks-completed" references unknown task "${n}".`);
+                throw new CompileRefusal('UNKNOWN_TASK_REF', `rule "selected-tasks-completed" references unknown task "${n}".`);
             return tid;
         });
     }
@@ -1853,12 +1855,12 @@ function emitRule(r, seed, ownerId, ids, resolver, site) {
         // preallocated id. `slaId` alone = a breach rule; adding `escalationId` = at-risk.
         const slaId = r.sla && resolver.slaIdByName.get(r.sla);
         if (!slaId)
-            throw new Error(`rule "sla-status-change" references unknown SLA "${r.sla}" — declare it with .sla({ displayName: "${r.sla}", … }).`);
+            throw new CompileRefusal('UNKNOWN_SLA_REF', `rule "sla-status-change" references unknown SLA "${r.sla}" — declare it with .sla({ displayName: "${r.sla}", … }).`);
         out.slaId = slaId;
         if (r.escalation) {
             const escId = resolver.escalationIdByName.get(r.escalation);
             if (!escId)
-                throw new Error(`rule "sla-status-change" references unknown escalation "${r.escalation}".`);
+                throw new CompileRefusal('UNKNOWN_ESCALATION_REF', `rule "sla-status-change" references unknown escalation "${r.escalation}".`);
             out.escalationId = escId;
         }
     }
@@ -1866,9 +1868,9 @@ function emitRule(r, seed, ownerId, ids, resolver, site) {
         // The event is matched by its exact name at run time; a rule without one
         // listens for nothing, so both a missing and an undeclared name refuse.
         if (!r.businessEvent)
-            throw new Error(`rule "api-event" in ${site} names no business event — write rule('api-event', { businessEvent: '<name>' }) with a name declared by .businessEvent('<name>').`);
+            throw new CompileRefusal('API_EVENT_NO_BUSINESS_EVENT', `rule "api-event" in ${site} names no business event — write rule('api-event', { businessEvent: '<name>' }) with a name declared by .businessEvent('<name>').`);
         if (!resolver.businessEvents.has(r.businessEvent))
-            throw new Error(`rule "api-event" in ${site} listens for business event "${r.businessEvent}", which the case does not declare — add .businessEvent(${JSON.stringify(r.businessEvent)}).`);
+            throw new CompileRefusal('UNKNOWN_BUSINESS_EVENT', `rule "api-event" in ${site} listens for business event "${r.businessEvent}", which the case does not declare — add .businessEvent(${JSON.stringify(r.businessEvent)}).`);
         out.businessEventType = r.businessEvent;
     }
     if (r.expression)
@@ -1939,7 +1941,7 @@ function emitExit(c, seed, ownerId, label, ids, resolver) {
     if (c.exitToStage) {
         const sid = resolver.stageIdByLabel.get(c.exitToStage);
         if (!sid)
-            throw new Error(`exit condition routes to unknown stage "${c.exitToStage}".`);
+            throw new CompileRefusal('UNKNOWN_EXIT_STAGE', `exit condition routes to unknown stage "${c.exitToStage}".`);
         out.exitToStageId = sid;
     }
     return out;

package/dist/cli/commands/flow.js

@@ -23,14 +23,16 @@ export function registerFlowCommands(program) {
         .option('--library <dir>', 'connector library directory')
         .option('--bindings <file>', 'bindings.json path')
         .option('--connectors-local <dir>', 'connection-resolved connector overlay')
-        .option('--no-check', 'skip the source-level check')
+        .option('--no-check', 'deprecated, does nothing: compile no longer runs check')
         .action(async (source, options) => {
         const argv = [source];
         addValue(argv, '-o', options.output);
         addValue(argv, '--library', options.library);
         addValue(argv, '--bindings', options.bindings);
         addValue(argv, '--connectors-local', options.connectorsLocal);
-        if (options.check === false || emitOnlyEnabled())
+        // Passed on only when given, so compile prints its deprecation warning.
+        // Emit-only mode needs nothing here: compile does not run check.
+        if (options.check === false)
             argv.push('--no-check');
         await invoke('flow compile', () => import('../../compile-cli.js'), argv);
     });

package/dist/compile-cli.js

@@ -10,12 +10,17 @@
  * --library defaults to $FLOW_SDK_LIBRARY_JSON; --bindings defaults to
  * .flow-sdk/bindings.json (or a legacy ./bindings.json) when present. Connector actions require a library.
  *
- * `--no-check` skips the SDK's static `check()` pass and emits whatever
- * `.build()` produced. It exists for loops whose verification is somewhere else
- * entirely — e.g. authoring against the product CLI (`uip maestro flow
- * validate` / `debug`), where a pre-emit static pass would answer questions the
- * product's own gates are supposed to answer. `.build()` still throws on
- * structural problems; only the diagnostic pass is skipped.
+ * `compile` only serializes (docs/CHECK_COMPILE_CONTRACT_DESIGN.md D1, D2). It
+ * does not run `check()`'s lint rules: run `flow check` first for those. It
+ * stops only when it cannot write a correct `.flow`, a refusal the serializer
+ * throws. A draft node (a connector with no connection, an empty required
+ * input) the canvas saved is written, with a warning: decompile marks its step
+ * `{ draft: true }` and carries its definition in `.definitions([...])`. Any
+ * other draft, such as one an agent just wrote (even of an operation the canvas
+ * has a draft of), is refused.
+ *
+ * `--no-check` is a deprecated no-op: it is accepted for one minor version, with
+ * a warning, and then removed.
  */
 import { diagnosticLine, reportDiagnostics, reportResult, thrownDiagnostic } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
@@ -24,8 +29,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars } from './serialize.js';
 import { compileOwnsResource } from './core/agent-tool-resources.js';
-import { check } from './check.js';
-import { flowCheckOpts, openCliLibrary } from './cli-library.js';
+import { openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
 import { connectionResources, inlineAgentResources, mergeBindingsV2, refreshInlineAgentRows } from './bindings-v2.js';
@@ -35,8 +39,8 @@ import { defaultBindingsFile } from './workdir.js';
 import { isWithin } from './path-within.js';
 import { flowSources, resourceSourcesOfOtherFlows } from './project-resource-users.js';
 import { fnv1aX4Uuid } from './core/stable-id.js';
-import { BindingRefusal } from './core/binding-messages.js';
-import { ByoaRefusal } from './core/byoa.js';
+import { CompileRefusal } from './core/compile-refusal.js';
+import { cliSpelling } from './core/cli-spelling.js';
 /** An agent folder name: a uuid, any case. */
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export async function run(argv) {
@@ -45,7 +49,9 @@ export async function run(argv) {
         return 2;
     }
     const flags = new Set(['-o', '--library', '--bindings', '--connectors-local']);
-    const noCheck = argv.includes('--no-check');
+    if (argv.includes('--no-check')) {
+        console.error(`compile: --no-check is deprecated and does nothing: compile no longer runs check. Run \`${cliSpelling()} flow check\` before \`compile\`; the flag will be removed.`);
+    }
     const pos = argv.find((a, i) => !flags.has(a) && !flags.has(argv[i - 1]));
     if (!pos) {
         console.error('compile: missing <flow.ts | BaseName>');
@@ -66,37 +72,20 @@ export async function run(argv) {
     // (e.g. HTTP-only) then compile fine even if the connector cache isn't built.
     // A connector action with no library resolves to a clear error in serialize().
     //
-    // Loaded BEFORE check() on purpose: one of check's rules (whether a connector
-    // event operation declares any event parameters) can only be answered from the
-    // library, and answering it from an assumption instead is what made
-    // EVENT_NO_SCOPE an error for HTTP Webhook, whose only correct `where` is empty.
     const library = openCliLibrary(argv);
     const bindFile = flagValue(argv, '--bindings') ?? defaultBindingsFile();
     const bindings = new Bindings(bindFile);
     // One list per run; every exit path reports it (reportResult overwrites keys).
     const diagnostics = [];
-    if (!noCheck) {
-        // Same options as `flow check`, so the two cannot disagree.
-        const diags = check(built, flowCheckOpts(library, bindings));
-        const errors = diags.filter((d) => d.level === 'error');
-        for (const d of diags)
-            console.error(`  ${diagnosticLine(d)}`);
-        diagnostics.push(...diags);
-        if (errors.length) {
-            reportDiagnostics(diagnostics);
-            console.error(`compile: ${errors.length} error(s); not emitting.`);
-            return 1;
-        }
-    }
     // The serializer's own observations — a connection or folder value that can
-    // never be a tenant resource key — printed in the same `⚠ [CODE]` shape as
-    // check()'s. Warnings are never fatal: the .flow is still written, exit stays 0.
-    // A binding LABEL the serializer refuses (its own name as the resourceKey, or a
-    // label a populated bindings.json does not declare) is an error, not a
-    // warning, and so is a BYOA-only event on a connection `prepare` never checked
-    // (EVENT_BYOA_UNVERIFIED): the check pass above reports each first, and this is
-    // the same refusal in the same `✗ [CODE]` shape when that pass was skipped
-    // (`--no-check`, or an emit-only project). Nothing is written.
+    // never be a tenant resource key, a draft node written from its carried
+    // definition — printed in the same `⚠ [CODE]` shape as check()'s. Warnings are
+    // never fatal: the .flow is still written, exit stays 0. A binding LABEL the
+    // serializer refuses (its own name as the resourceKey, or a label a populated
+    // bindings.json does not declare) is an error, not a warning, and so is a
+    // BYOA-only event on a connection `prepare` never checked
+    // (EVENT_BYOA_UNVERIFIED): printed in the same `✗ [CODE]` shape `check` uses
+    // for it. Nothing is written.
     const out = flagValue(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
     const outDir = dirname(resolve(out));
     // ONE FOLDER, ONE FLOW (#1184). An agent's `source` is the name of the folder
@@ -147,28 +136,37 @@ export async function run(argv) {
     const warnings = [];
     let emitted;
     try {
-        emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w), agentSource });
+        emitted = serializeWithSidecars(built, {
+            library, bindings, warn: (w) => warnings.push(w), agentSource,
+            carriedDrafts: (d) => warnings.push(draftWarning(d)),
+        });
     }
     catch (error) {
         for (const w of warnings)
-            console.error(`  ⚠ [${w.code}] ${w.message}`);
+            console.error(`  ${diagnosticLine(serializeWarningDiagnostic(w))}`);
         diagnostics.push(...warnings.map(serializeWarningDiagnostic));
-        if (!(error instanceof BindingRefusal || error instanceof ByoaRefusal)) {
-            // Any other throw still ends the run through the caller (exit 1, `--json`
-            // `error`); the list is reported first.
+        if (!(error instanceof CompileRefusal)) {
+            // Any other throw (an internal SDK error) still ends the run through the
+            // caller (exit 1, `--json` `error`); the list is reported first.
             diagnostics.push(thrownDiagnostic(error));
             reportDiagnostics(diagnostics);
             throw error;
         }
-        console.error(`  ✗ [${error.code}] ${error.message}`);
-        diagnostics.push({ level: 'error', code: error.code, message: error.message });
+        // A coded refusal: the serializer cannot write a correct `.flow`. Printed in
+        // `check`'s `✗ [CODE]` shape, which `check` reports for it too.
+        const refused = {
+            level: 'error', code: error.code, message: error.message,
+            ...(error.suggestion !== undefined ? { suggestion: error.suggestion } : {}),
+        };
+        console.error(`  ${diagnosticLine(refused)}`);
+        diagnostics.push(refused);
         reportDiagnostics(diagnostics);
         console.error('compile: 1 error(s); not emitting.');
         return 1;
     }
     const { flow: flowJson, sidecars } = emitted;
     for (const w of warnings)
-        console.error(`  ⚠ [${w.code}] ${w.message}`);
+        console.error(`  ${diagnosticLine(serializeWarningDiagnostic(w))}`);
     diagnostics.push(...warnings.map(serializeWarningDiagnostic));
     // An inline agent is TWO artifacts: the node, and the agent's own configuration
     // at `<source>/agent.json` — which is where flow-v1's serializer points the
@@ -325,7 +323,19 @@ export async function run(argv) {
     return 0;
 }
 function serializeWarningDiagnostic(w) {
-    return { level: 'warning', code: w.code, message: w.message };
+    return { level: 'warning', code: w.code, message: w.message, ...(w.step !== undefined ? { step: w.step } : {}) };
+}
+/**
+ * A draft node written from its carried definition, as a warning: the node is
+ * in the `.flow` as the canvas saved it, unfinished. For instance
+ * `⚠ [BINDING_MISSING] … written as a draft from its carried definition`.
+ */
+function draftWarning(d) {
+    return {
+        code: String(d.code),
+        message: `${d.message} Written as a draft, with the definition the source carries; finish the node before the flow runs.`,
+        ...(d.step !== undefined ? { step: d.step } : {}),
+    };
 }
 runWhenInvokedDirectly(import.meta.url, 'compile', run);
 /** A JSON file's contents, or `undefined` when it is missing or unreadable. */

package/dist/core/event-filters.d.ts

@@ -98,6 +98,26 @@ export declare function readEventFilter(leaf: unknown): {
     keys: EventFilterOperatorKey[];
     read?: ReadEventFilter;
 };
+/** A code `check` gives a filter leaf it refuses (`core/event-checks.ts`). */
+export type EventFilterLeafCode = 'EVENT_FILTER_NO_FIELD' | 'EVENT_FILTER_MANY_OPERATORS' | 'EVENT_FILTER_NO_VALUE' | 'EVENT_FILTER_BACKSLASH' | 'EVENT_FILTER_BAD_VALUE';
+/**
+ * Read an authored filter leaf and judge it the way `check` does: the first
+ * code `core/event-checks.ts` gives the leaf, in the same order, or the read
+ * condition when the leaf lowers. A serializer that refuses a bad leaf with one
+ * message calls this, so its code cannot drift from check's.
+ *
+ * @example
+ * readEventFilterLeaf({ field: 'subject', contains: 'Report' }) // { read: { field: 'subject', operator: 'contains', value: 'Report' } }
+ * readEventFilterLeaf({ contains: 'Report' })                   // { code: 'EVENT_FILTER_NO_FIELD', read: { field: '', ... } }
+ */
+export declare function readEventFilterLeaf(leaf: unknown): {
+    code?: undefined;
+    read: ReadEventFilter;
+} | {
+    code: EventFilterLeafCode;
+    read?: ReadEventFilter;
+    problem?: string;
+};
 export declare function isIsoDateString(value: unknown): value is string;
 /**
  * Why a filter cannot be lowered, or `undefined` when it can. Two shapes are

package/dist/core/event-filters.js

@@ -81,6 +81,33 @@ export function readEventFilter(leaf) {
         return { keys };
     return { keys, read: { field: String(f.field ?? ''), operator: keys[0], value } };
 }
+/**
+ * Read an authored filter leaf and judge it the way `check` does: the first
+ * code `core/event-checks.ts` gives the leaf, in the same order, or the read
+ * condition when the leaf lowers. A serializer that refuses a bad leaf with one
+ * message calls this, so its code cannot drift from check's.
+ *
+ * @example
+ * readEventFilterLeaf({ field: 'subject', contains: 'Report' }) // { read: { field: 'subject', operator: 'contains', value: 'Report' } }
+ * readEventFilterLeaf({ contains: 'Report' })                   // { code: 'EVENT_FILTER_NO_FIELD', read: { field: '', ... } }
+ */
+export function readEventFilterLeaf(leaf) {
+    const { keys, read } = readEventFilter(leaf);
+    const field = leaf?.field;
+    if (typeof field !== 'string' || field === '')
+        return { code: 'EVENT_FILTER_NO_FIELD', read };
+    if (keys.length > 1)
+        return { code: 'EVENT_FILTER_MANY_OPERATORS' };
+    if (!read)
+        return { code: 'EVENT_FILTER_NO_VALUE' };
+    const problem = eventFilterProblem(read);
+    const ambiguous = typeof read.value === 'string' ? jmesStringProblem(read.value) : undefined;
+    if (ambiguous)
+        return { code: 'EVENT_FILTER_BACKSLASH', read, problem: problem ?? ambiguous };
+    if (problem)
+        return { code: 'EVENT_FILTER_BAD_VALUE', read, problem };
+    return { read };
+}
 /** An ISO-8601 calendar date, optionally with a time part — what the designer serializes a date filter as. */
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
 export function isIsoDateString(value) {