@uipath/maestro-builder-sdk 6.16.14 → 6.17.1

package/dist/check.js

@@ -7,16 +7,21 @@
  */
 import { Expr, SCHEDULE_PRESETS, DELAY_PRESETS, VARIANT_OPERATION, parseIxpProjectType, flatNameOf, flatNameSegmentsOf, FLAT_SEP } from './flow-sdk.js';
 import { FlowNode } from './core/node-classes.js';
+import { planContributionBindings } from './core/contribution-bindings.js';
+import { definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
+import { resolveContributionDefinition } from './serialize.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
+import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
 import { checkEventResolution, checkEventSubscription, eventParamsFor, } from './core/event-checks.js';
 import { checkCookedEscapes } from './flow-expr-check.js';
 import { FLOW_EXPR_DIALECT, checkBindingLabels, checkBindingPresence, checkConnectorContract as coreCheckConnectorContract, checkConnectorLookups as coreCheckConnectorLookups, checkConnectorSchema as coreCheckConnectorSchema, collectConnectionUses, connectionConnectorConflicts, } from './core/connector-checks.js';
 import { prepareCommand } from './core/cli-spelling.js';
+import { commentText } from './core/comment-text.js';
 import { editDistance } from './core/edit-distance.js';
 import { isAnswerField } from './core/hitl-answers.js';
 import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
 import { declaredExits, hasExits } from './core/step-ports.js';
-import { childStepLists, stopsAtEnd } from './flow-step-tree.js';
+import { stopsAtEnd } from './flow-step-tree.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
 import { planFlowGlobals, planSharedInputs, sharedInputRoots } from './flow-variables.js';
@@ -54,9 +59,11 @@ function checkFlow(built, ancestors, opts = {}) {
     if (maybeCustomTrigger !== undefined && !('kind' in maybeCustomTrigger) && maybeCustomTrigger instanceof FlowNode) {
         // A custom FlowTrigger subclass reports through its own diagnostics() hook;
         // the built-in trigger rules key on `kind` and don't apply.
-        for (const d of maybeCustomTrigger.diagnostics()) {
+        const own = maybeCustomTrigger.diagnostics();
+        for (const d of own) {
             diags.push({ level: d.severity, code: d.code, message: d.message, step: 'trigger' });
         }
+        checkContribution(maybeCustomTrigger, built.triggerOptions?.version, 'trigger', own.some((d) => d.severity === 'error'), diags);
     }
     else if (built.trigger !== undefined)
         checkTrigger(built.trigger, diags, opts);
@@ -251,7 +258,7 @@ function checkFlow(built, ancestors, opts = {}) {
                 stepNames.add(s.name);
                 declared.add(s.name); // a step's output is referenceable by name
             }
-            if (s.kind === 'stepToList' && s.port === 'error')
+            if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'error')
                 checkOnError(s, prevPortSource, diags);
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port.startsWith('branch-')) {
                 const want = s.port.slice('branch-'.length);
@@ -366,9 +373,11 @@ function checkFlow(built, ancestors, opts = {}) {
                 // don't apply, and it reports through its own diagnostics() hook.
                 const maybeCustom = s.spec;
                 if (!('kind' in maybeCustom) && maybeCustom instanceof FlowNode) {
-                    for (const d of maybeCustom.diagnostics()) {
+                    const own = maybeCustom.diagnostics();
+                    for (const d of own) {
                         diags.push({ level: d.severity, code: d.code, message: d.message, step: s.name });
                     }
+                    checkContribution(maybeCustom, s.options?.version, s.name, own.some((d) => d.severity === 'error'), diags);
                 }
                 if (s.spec.kind === 'transform')
                     checkTransform(s.name, s.spec.inputs, diags, typeOf, triggerId);
@@ -864,9 +873,11 @@ function checkFlow(built, ancestors, opts = {}) {
         epIds.add(ep.id);
         const maybeCustomEp = ep.trigger;
         if (!('kind' in maybeCustomEp) && maybeCustomEp instanceof FlowNode) {
-            for (const d of maybeCustomEp.diagnostics()) {
+            const own = maybeCustomEp.diagnostics();
+            for (const d of own) {
                 diags.push({ level: d.severity, code: d.code, message: d.message, step: ep.id });
             }
+            checkContribution(maybeCustomEp, ep.options?.version, ep.id, own.some((d) => d.severity === 'error'), diags);
         }
         else {
             checkTrigger(ep.trigger, diags, opts, ep.id);
@@ -1283,13 +1294,10 @@ function checkFlow(built, ancestors, opts = {}) {
             }
         }
     }
-    // Walk for a `.return()` rather than stringifying the step tree: a subflow
-    // step carries a whole child flow, so the tree can be cyclic (a flow that
-    // runs itself — SUBFLOW_CYCLE) and always contains the CHILD's returns, which
-    // say nothing about whether THIS flow terminates.
-    const hasTerminal = hasReturn(built.steps);
-    if (!hasTerminal)
-        diags.push({ level: 'warning', code: 'NO_RETURN', message: 'Flow has no return(); a default End node will be appended.' });
+    // The End compile appends when the root path runs out of steps (#941).
+    const fallOff = checkFallOffEnd(built);
+    if (fallOff)
+        diags.push(fallOff);
     // Check every child flow with the same rules, in its OWN scope — a child's
     // steps never see the parent's variables, so its undeclared references,
     // duplicate step names and type mismatches are its own. Diagnostics come back
@@ -1376,9 +1384,124 @@ function checkLoopListEnvelope(loop, connectors, opts, diags) {
         suggestion,
     });
 }
-/** True if any step on THIS flow's own tree is a `.return()`. */
-function hasReturn(steps) {
-    return steps.some((s) => s.kind === 'return' || childStepLists(s).some(hasReturn));
+/**
+ * NO_RETURN: a path that runs off the end of the flow, where a declared output
+ * is never written (#941).
+ *
+ * It asks serialize's question, not "is there a `.return()` anywhere?".
+ * serialize appends an End exactly when the root walk has tails left
+ * (`if (finalTails.length)`), and `armTails` mirrors that walk tail for tail.
+ * So a `.terminate()` path appends no End, and a branch where one arm returns
+ * and the other falls off DOES append one.
+ *
+ * The appended End maps every output from its own variable
+ * (`result <- $vars.result`), the same as a `.return()` that names no value.
+ * That loses nothing when the flow declares no outputs, or when each output
+ * was set on the way: by a `default`, a `{ shared }` input that every root
+ * feeds, or `{ updates }` on a step of that path. The warning names the outputs
+ * that are not, and the steps the path falls off from.
+ *
+ * Not covered: the private End a `.stepToList` body gets (#742). `armTails`
+ * skips those bodies, and that End is a different emission site with no
+ * output mappings at all.
+ */
+function checkFallOffEnd(built) {
+    if (built.outputs.length === 0)
+        return undefined;
+    const from = built.triggerId ?? 'start';
+    if (armTails(built.steps, [{ from }]).length === 0)
+        return undefined;
+    const preset = new Set(built.outputs.filter((o) => o.default !== undefined).map((o) => o.name));
+    // A shared input sets its variable only on runs that enter through a root
+    // feeding it, so it counts as preset only when every root does.
+    const roots = sharedInputRoots(built);
+    for (const t of planSharedInputs({ roots, outputs: built.outputs, vars: built.vars }).targets) {
+        if (t.declaredAs === 'output' && roots.every((r) => t.feeds.some((f) => f.root === r.id)))
+            preset.add(t.name);
+    }
+    const tails = writtenTails(built.steps, [{ from, written: preset }], []);
+    const missing = built.outputs.map((o) => o.name).filter((n) => tails.some((t) => !t.written.has(n)));
+    if (missing.length === 0)
+        return undefined;
+    const steps = [...new Set(tails.filter((t) => missing.some((n) => !t.written.has(n))).map((t) => t.from))];
+    const one = missing.length === 1;
+    return {
+        level: 'warning',
+        code: 'NO_RETURN',
+        message: `Path ending at ${steps.map((x) => `"${x}"`).join(', ')} falls into the End compile appends. `
+            + `${one ? 'Output' : 'Outputs'} ${missing.map((n) => `"${n}"`).join(', ')} may be unset there. `
+            + `End the path with .return({ … }) or set ${one ? 'it' : 'them'} with { updates } (a loop body may run zero times).`,
+        step: steps[0],
+        suggestion: `.return({ ${missing.map((n) => `${n}: …`).join(', ')} })`,
+    };
+}
+/**
+ * `armTails`, step for step, carrying what each path has surely written. A
+ * `.return()` value is NOT a write here: it lives on that `.return()`'s End,
+ * which is not the End this is about. Where paths meet, only what all of them
+ * wrote counts.
+ *
+ * A `.break()` leaves the enclosing loop with what its path wrote so far, so
+ * its tail goes to `breaks`, and the loop counts it as one of the ways out. A
+ * loop body may run zero times, so it writes nothing for sure. A do-while body
+ * runs at least once, and is left by its end or by a `.break()`, so what all of
+ * those wrote counts. Every `.parallel` arm runs, so what each surely writes
+ * counts.
+ */
+function writtenTails(steps, incoming, breaks) {
+    let tails = incoming;
+    for (const st of steps) {
+        if (st.kind === 'stepToList')
+            continue;
+        if (st.kind === 'stepToRef') {
+            if (st.port === 'output')
+                tails = [];
+            continue;
+        }
+        if (st.kind === 'break') {
+            breaks.push(...tails);
+            return [];
+        }
+        if (st.kind === 'return' || st.kind === 'terminate')
+            return [];
+        const before = surelyWritten(tails);
+        const written = new Set([...before, ...Object.keys(st.options?.updates ?? {})]);
+        const arm = (body) => writtenTails(body, [{ from: st.name, written }], breaks);
+        if (st.kind === 'action') {
+            tails = actionTails(st.name, st.spec, st.options?.version)
+                .map((t) => ({ from: t.from, written }));
+        }
+        else if (st.kind === 'stepSwitch') {
+            tails = st.cases.flatMap((c) => arm(c.body));
+        }
+        else if (st.kind === 'branch') {
+            tails = [...arm(st.then), ...arm(st.otherwise)];
+        }
+        else if (st.kind === 'switch') {
+            tails = [...st.cases.flatMap((c) => arm(c.body)), ...(st.default !== undefined ? arm(st.default) : [])];
+        }
+        else if (st.kind === 'doWhile') {
+            const exits = [];
+            exits.push(...writtenTails(st.body, [{ from: st.name, written }], exits));
+            surelyWritten(exits).forEach((n) => written.add(n));
+            tails = [{ from: st.name, written }];
+        }
+        else if (st.kind === 'parallel') {
+            for (const body of st.arms)
+                surelyWritten(arm(body)).forEach((n) => written.add(n));
+            tails = [{ from: st.name, written }];
+        }
+        else {
+            tails = [{ from: st.name, written }];
+        }
+    }
+    return tails;
+}
+/** What every one of `tails` has written; nothing when there are none. */
+function surelyWritten(tails) {
+    if (tails.length === 0)
+        return new Set();
+    return new Set([...tails[0].written].filter((n) => tails.every((t) => t.written.has(n))));
 }
 /**
  * Closest of `candidates` to `name`: same word ignoring case, one contained in
@@ -1982,10 +2105,11 @@ function renamedFieldMessage(label, step, oldField) {
  *  - a `key` that is not a GUID. The commonest form of this is passing the
  *    process's NAME where its release key belongs, which produces a node type
  *    the platform cannot resolve to anything.
- *  - a `folderPath` that looks like a name, or a `name` that looks like a path —
- *    the two are swappable by shape and the resulting `resourceKey` is wrong in a
- *    way that only surfaces as a 400 from Orchestrator ("Folder does not exist").
- *    That is v1's own 2026-06-26 failure mode on this task.
+ *  - a `name` that looks like a path (contains "/"). The two are swappable, and
+ *    the resulting `resourceKey` is wrong in a way that only surfaces as a 400
+ *    from Orchestrator ("Folder does not exist"). That is v1's own 2026-06-26
+ *    failure mode on this task. A single-segment `folderPath` is NOT decidable:
+ *    root folders and personal workspaces are one segment, so it is not flagged.
  */
 function checkRpaWorkflow(step, inputs, diags) {
     const at = (code, message, suggestion) => {
@@ -2009,33 +2133,33 @@ function checkRpaWorkflow(step, inputs, diags) {
         at('RPA_NO_NAME', `RPA step "${step}" has no \`name\`. The runtime starts the job by name + folder, not by the key in `
             + `the node type, so without it the process cannot be resolved and the run fails before dispatch.`, `name: 'RPA Workflow'`);
     }
-    if (blank(inputs?.folderPath)) {
+    const inSolution = inputs?.location === 'in-solution';
+    if (!inSolution && blank(inputs?.folderPath)) {
         at('RPA_NO_FOLDER', `RPA step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so the `
             + `Orchestrator folder holding the process is required.`, `folderPath: 'Shared/uipath-maestro-flow/ProjectEuler RPA'`);
     }
+    if (inSolution && blank(inputs?.projectId)) {
+        at('RPA_LOCAL_NO_PROJECT_ID', `In-solution RPA step "${step}" has no \`projectId\`. Read \`resource.projectKey\` from `
+            + `\`resources/solution_folder/process/process/<project>.json\`.`, `projectId: '<resource.projectKey>'`);
+    }
+    else if (inSolution && !GUID_RE.test(String(inputs.projectId).trim())) {
+        at('RPA_LOCAL_PROJECT_ID_NOT_GUID', `In-solution RPA step "${step}" has projectId ${JSON.stringify(inputs.projectId)}, which is not `
+            + `the sibling project's GUID. Read \`resource.projectKey\` from the generated resource file.`, `projectId: '<resource.projectKey>'`);
+    }
+    if (inSolution && !blank(inputs?.folderPath)) {
+        at('RPA_LOCAL_HAS_FOLDER', `In-solution RPA step "${step}" also sets \`folderPath\` ${JSON.stringify(inputs.folderPath)}. An `
+            + `in-solution sibling has no folder until the solution is deployed — the platform's own manifest `
+            + `writes \`""\` — so the value would be dropped. Remove it, or drop \`location: 'in-solution'\` to `
+            + `call the published copy.`);
+    }
     // The two are swappable by shape, and swapping them is invisible until
     // Orchestrator answers "Folder does not exist or the user does not have access".
     const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
-    const folder = typeof inputs?.folderPath === 'string' ? inputs.folderPath.trim() : '';
     if (name.includes('/')) {
         at('RPA_NAME_IS_PATH', `RPA step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. \`name\` is `
             + `the process's own name in Orchestrator; the path it lives in goes in \`folderPath\`. Together they `
             + `form the resourceKey "<folderPath>.<name>", so swapping them points the job at nothing.`);
     }
-    if (folder && !folder.includes('/') && name && !name.includes('/')) {
-        // A single-segment folder is legal ("Shared"), so this is only worth saying
-        // when the folder ALSO fails to look like one of the tenant's roots.
-        if (!/^(Shared|Personal|My Workspace)$/i.test(folder)) {
-            diags.push({
-                level: 'warning',
-                code: 'RPA_FOLDER_NOT_PATH',
-                message: `RPA step "${step}"'s \`folderPath\` is ${JSON.stringify(inputs.folderPath)} — a single segment with no `
-                    + `"/". Orchestrator folder paths are usually nested (e.g. "Shared/<team>/<solution>"). If this is `
-                    + `the process's name rather than its folder, the two arguments are swapped.`,
-                step,
-            });
-        }
-    }
 }
 /**
  * Check an `apiWorkflow(...)` call.
@@ -2636,10 +2760,33 @@ function checkAgenticProcess(step, inputs, diags) {
             + `the key in the node type, so without it the process cannot be resolved and the run fails before `
             + `dispatch.`, `name: 'ProcurementProcess'`);
     }
-    if (blank(inputs?.folderPath)) {
+    const inSolution = inputs?.location === 'in-solution';
+    if (!inSolution && blank(inputs?.folderPath)) {
         at('AGENTIC_NO_FOLDER', `Agentic process step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so `
             + `the Orchestrator folder holding the process is required.`, `folderPath: 'Shared/uipath-agents/ProcurementProcess'`);
     }
+    const form = inputs?.form ?? 'bpmn';
+    if (inSolution && form !== 'flow') {
+        at('AGENTIC_LOCAL_FORM_UNVERIFIED', `In-solution agentic process step "${step}" has \`form: ${JSON.stringify(form)}\`. Only \`form: 'flow'\` `
+            + `has been run against an in-solution sibling; the ${JSON.stringify(form)} shape is unproven. Call the `
+            + `published process instead (drop \`location\` and \`projectId\`, set \`folderPath\`), or use `
+            + `\`form: 'flow'\` if the sibling is a Flow.`, `location: 'published', folderPath: 'Shared/<folder>'`);
+    }
+    if (inSolution && blank(inputs?.projectId)) {
+        const folder = (AGENTIC_PROCESS_FORMS[inputs?.form ?? 'bpmn'] ?? AGENTIC_PROCESS_FORMS.bpmn).solutionFolder;
+        at('AGENTIC_LOCAL_NO_PROJECT_ID', `In-solution agentic process step "${step}" has no \`projectId\`. Read \`resource.projectKey\` from `
+            + `\`resources/solution_folder/process/${folder}/<project>.json\`.`, `projectId: '<resource.projectKey>'`);
+    }
+    else if (inSolution && !GUID_RE.test(String(inputs.projectId).trim())) {
+        at('AGENTIC_LOCAL_PROJECT_ID_NOT_GUID', `In-solution agentic process step "${step}" has projectId ${JSON.stringify(inputs.projectId)}, which is not `
+            + `the sibling project's GUID. Read \`resource.projectKey\` from the generated resource file.`, `projectId: '<resource.projectKey>'`);
+    }
+    if (inSolution && !blank(inputs?.folderPath)) {
+        at('AGENTIC_LOCAL_HAS_FOLDER', `In-solution agentic process step "${step}" also sets \`folderPath\` ${JSON.stringify(inputs.folderPath)}. An `
+            + `in-solution sibling has no folder until the solution is deployed — the platform's own manifest `
+            + `writes \`""\` — so the value would be dropped. Remove it, or drop \`location: 'in-solution'\` to `
+            + `call the published copy.`);
+    }
     const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
     if (name.includes('/')) {
         at('AGENTIC_NAME_IS_PATH', `Agentic process step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. `
@@ -3642,7 +3789,7 @@ function checkQueueItem(step, inputs, diags) {
                     + `Orchestrator rejects a queue item whose property values are not simple: `
                     + `"Property values must be simple (like numbers or text) and not complex or composite `
                     + `data types (like objects or arrays)". Flatten it, or JSON-encode it into one string `
-                    + `field.`, `item: { ${k}: JSON.stringify(...) }  // or ${k}Id, ${k}Name, …`);
+                    + `field.`, `item: { ${k}: JSON.stringify(...) }  // or ${commentText(k)}Id, ${commentText(k)}Name, …`);
             }
         }
     }
@@ -3933,7 +4080,7 @@ function fanInDiag(join, arm, steps, tails) {
             + `edge, so the run never gets past "${join}" — with no incident, and \`flow validate\` answers Valid. Add a `
             + `step at the end of the arm${last?.name ? `, after "${last.name}"` : ''}, so the paths meet on that step and `
             + `only its one edge reaches the join, or move human task "${task}" out of the \`.parallel(…)\`.`,
-        suggestion: `….step('record', …)  // last step of arm ${arm + 1}`,
+        suggestion: `….step('record', …)  // last step of arm ${commentText(arm + 1)}`,
     };
 }
 /**
@@ -5195,7 +5342,7 @@ function checkOnError(_handler, step, diags) {
     // A `.loop()` CONTAINER is fine: `core.logic.loop` declares the error handle at
     // both bundled versions, and a measured run routed a body failure to it — the
     // container's envelope carried the body's message in `detail` and the failing
-    // body step's id in `element`.
+    // body step's label in `element`.
     if (step.kind === 'loop')
         return;
     // `.doWhile()` is not. `core.logic.dowhile@1.0` declares an error VARIABLE and
@@ -5204,12 +5351,38 @@ function checkOnError(_handler, step, diags) {
     // declare that handle". The builder refuses this too; this catches a
     // hand-built flow and says the same thing.
     if (step.kind === 'doWhile') {
+        diags.push(doWhileOnErrorRefusal(step.name));
+        return;
+    }
+    // A custom FlowAction or rawNode has no `kind`: ask its DEFINITION, with the
+    // product's own rule (definitionHasErrorPort), not the kind list (#943).
+    const maybeCustom = step.spec;
+    if (!('kind' in maybeCustom) && maybeCustom instanceof FlowNode) {
+        let def;
+        try {
+            const requestedVersion = step.options?.version;
+            def = resolveContributionDefinition(maybeCustom.contribute(requestedVersion !== undefined ? { requestedVersion } : {}).definition, requestedVersion, `step "${step.name}"`);
+        }
+        catch {
+            // checkContribution already reports a contribution compile cannot lower.
+            return;
+        }
+        // A custom node backed by a typed family's bundled definition gets that
+        // family's refusals: the rules are about the node type, not the SDK kind.
+        if (def?.nodeType === 'core.logic.dowhile') {
+            diags.push(doWhileOnErrorRefusal(step.name));
+            return;
+        }
+        if (def?.nodeType === 'core.action.http') {
+            diags.push(plainHttpOnErrorRefusal(step.name));
+            return;
+        }
+        if (definitionHasErrorPort(def))
+            return;
         diags.push({
             level: 'error',
             code: 'ONERROR_NO_ERROR_PORT',
-            message: `Step "${step.name}" is a .doWhile() container. It declares an error variable but no error HANDLE `
-                + `(core.logic.dowhile@1.0: input, success, start, continue, break), so the edge would leave a handle the `
-                + `node does not have. Handle the failure inside the body, on the step that can fail.`,
+            message: errorPortRefusal(step.name, def),
             step: step.name,
         });
         return;
@@ -5240,19 +5413,33 @@ function checkOnError(_handler, step, diags) {
     // So this stays an error, and says the second part too: an author who reads
     // the old message ("use the managed node if statuses must route") could
     // reasonably conclude a transport-failure handler is fine as it is.
-    if (spec.kind === 'http' && !spec.inputs?.managed) {
-        diags.push({
-            level: 'error',
-            code: 'HTTP_ONERROR_V1',
-            message: `Step "${step.name}" handles errors on a plain http() request. A 4xx/5xx does NOT fail that node — it `
-                + `completes with out('${step.name}', 'statusCode') set — so the handler runs only on a transport failure, `
-                + `and when it does the node publishes no failure envelope at all (measured: "<step>.error" is the boolean `
-                + `true and "<step>.output" is null, in 1.0.0 and in the 1.3 flow migrate produces), so err() has nothing `
-                + `to read. The managed node is the one whose failures route AND carry the envelope.`,
-            step: step.name,
-            suggestion: `http({ url: …, managed: true })`,
-        });
-    }
+    if (spec.kind === 'http' && !spec.inputs?.managed)
+        diags.push(plainHttpOnErrorRefusal(step.name));
+}
+/** `.onError` after a `core.logic.dowhile` container: it declares no error handle. */
+function doWhileOnErrorRefusal(stepName) {
+    return {
+        level: 'error',
+        code: 'ONERROR_NO_ERROR_PORT',
+        message: `Step "${stepName}" is a .doWhile() container. It declares an error variable but no error HANDLE `
+            + `(core.logic.dowhile@1.0: input, success, start, continue, break), so the edge would leave a handle the `
+            + `node does not have. Handle the failure inside the body, on the step that can fail.`,
+        step: stepName,
+    };
+}
+/** `.onError` after a plain `core.action.http` node (see the two measured facts in {@link checkOnError}). */
+function plainHttpOnErrorRefusal(stepName) {
+    return {
+        level: 'error',
+        code: 'HTTP_ONERROR_V1',
+        message: `Step "${stepName}" handles errors on a plain http() request. A 4xx/5xx does NOT fail that node — it `
+            + `completes with out('${stepName}', 'statusCode') set — so the handler runs only on a transport failure, `
+            + `and when it does the node publishes no failure envelope at all (measured: "<step>.error" is the boolean `
+            + `true and "<step>.output" is null, in 1.0.0 and in the 1.3 flow migrate produces), so err() has nothing `
+            + `to read. The managed node is the one whose failures route AND carry the envelope.`,
+        step: stepName,
+        suggestion: `http({ url: …, managed: true })`,
+    };
 }
 /**
  * Reading a value that only ONE arm produces (flow-builder-sdk#200).
@@ -5623,3 +5810,39 @@ function checkSchemaVersion(built, ancestors, diags) {
         });
     }
 }
+/**
+ * Run a custom node's contribution lowering DRY, so `check` reports what
+ * `compile` would throw. For instance, a `rawNode` carrying an in-solution
+ * sibling's manifest with no `values` row for `<bindings.folderPath>` fails here
+ * with the same code compile throws.
+ *
+ * It calls `contribute()`, resolves the definition the way serialize does, and
+ * plans the `bindings[]` entries serialize would build
+ * ({@link planContributionBindings}). A name the plan cannot close is
+ * `CONTRIBUTION_BINDING_UNRESOLVED` — the same code and sentence serialize
+ * throws. A contribution that throws is `CONTRIBUTION_INVALID`, unless
+ * `ownError` says the node's own `diagnostics()` already reported an error (a
+ * raw connector node throws for the reason `RAW_NODE_CONNECTOR` already gives).
+ */
+function checkContribution(node, requestedVersion, step, ownError, diags) {
+    let def;
+    let supplied;
+    try {
+        const contribution = node.contribute(requestedVersion !== undefined ? { requestedVersion } : {});
+        def = resolveContributionDefinition(contribution.definition, requestedVersion, `step "${step}"`);
+        supplied = contribution.bindings;
+    }
+    catch (e) {
+        if (ownError)
+            return;
+        diags.push({
+            level: 'error', code: 'CONTRIBUTION_INVALID', step,
+            message: `compile cannot lower step "${step}": ${e instanceof Error ? e.message : String(e)}`,
+        });
+        return;
+    }
+    const plan = planContributionBindings(def, supplied);
+    if (plan.problems.length === 0)
+        return;
+    diags.push({ level: 'error', code: 'CONTRIBUTION_BINDING_UNRESOLVED', step, message: plan.problems.join(' ') });
+}

package/dist/cli-library.d.ts

@@ -1,9 +1,23 @@
 /**
- * cli-library — compatibility re-export.
+ * cli-library — Flow's check options, plus the historical re-exports.
  *
  * How a CLI opens the connector library and its `connectors-local/` overlay, and
- * the event verdicts `check` shares with `compile`, all moved to
- * `core/cli-library.ts` when BPMN's `compile` and `check` needed the same things.
- * This shim preserves the historical `./cli-library.js` import path.
+ * the connector and event verdicts every family's `check` shares with its
+ * `compile`, live in `core/cli-library.ts`. This module keeps the historical
+ * `./cli-library.js` import path and adds the one thing that is Flow's own:
+ * {@link flowCheckOpts}, the options both `flow check` and `flow compile`'s check
+ * pass run on.
  */
+import type { CheckOpts } from './check.js';
+import type { BindingsView } from './core/binding-messages.js';
+import type { Library } from './core/library.js';
 export { openCliLibrary, connectorCheckOpts, eventResolveErrorFor, byoaCheckOpts } from './core/cli-library.js';
+/**
+ * Flow's check options from a library the CLI already opened: the shared
+ * connector and event hooks, Flow's own field validator (it renders Flow
+ * expressions, as `serialize` does), and the measured list envelopes.
+ *
+ * One builder for `flow check` and `flow compile`'s check pass, so the two
+ * cannot disagree.
+ */
+export declare function flowCheckOpts(library: Library | undefined, bindings?: BindingsView): CheckOpts;

package/dist/cli-library.js

@@ -1,9 +1,27 @@
+import { connectorCheckOpts } from './core/cli-library.js';
+import { connectorInputErrors } from './serialize.js';
+export { openCliLibrary, connectorCheckOpts, eventResolveErrorFor, byoaCheckOpts } from './core/cli-library.js';
 /**
- * cli-library — compatibility re-export.
+ * Flow's check options from a library the CLI already opened: the shared
+ * connector and event hooks, Flow's own field validator (it renders Flow
+ * expressions, as `serialize` does), and the measured list envelopes.
  *
- * How a CLI opens the connector library and its `connectors-local/` overlay, and
- * the event verdicts `check` shares with `compile`, all moved to
- * `core/cli-library.ts` when BPMN's `compile` and `check` needed the same things.
- * This shim preserves the historical `./cli-library.js` import path.
+ * One builder for `flow check` and `flow compile`'s check pass, so the two
+ * cannot disagree.
  */
-export { openCliLibrary, connectorCheckOpts, eventResolveErrorFor, byoaCheckOpts } from './core/cli-library.js';
+export function flowCheckOpts(library, bindings) {
+    const shared = connectorCheckOpts(library, bindings, connectorInputErrors);
+    if (!library)
+        return shared;
+    return {
+        ...shared,
+        listEnvelope: (connector, operation, version, object) => {
+            try {
+                return library.resolve(connector, operation, version, object).listEnvelope;
+            }
+            catch {
+                return undefined; // an unresolvable operation is connectorResolveError's to report
+            }
+        },
+    };
+}

package/dist/cli-result.d.ts

@@ -34,3 +34,12 @@ export declare function reportDiagnostics(diags: ReadonlyArray<{
     message: string;
     suggestion?: string;
 }>): void;
+/**
+ * The error diagnostic for a throw that ends a compile: the error's own string
+ * `code` when it carries one, else `COMPILE_FAILED`.
+ */
+export declare function thrownDiagnostic(error: unknown): {
+    level: 'error';
+    code: string;
+    message: string;
+};

package/dist/cli-result.js

@@ -47,3 +47,15 @@ export function reportDiagnostics(diags) {
         diagnostics: diags.map((d) => ({ level: d.level, code: d.code, message: d.message, ...(d.suggestion ? { suggestion: d.suggestion } : {}) })),
     });
 }
+/**
+ * The error diagnostic for a throw that ends a compile: the error's own string
+ * `code` when it carries one, else `COMPILE_FAILED`.
+ */
+export function thrownDiagnostic(error) {
+    const code = error?.code;
+    return {
+        level: 'error',
+        code: typeof code === 'string' && code.length > 0 ? code : 'COMPILE_FAILED',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}