@uipath/maestro-builder-sdk 6.17.0 → 6.17.2

package/dist/check.js

@@ -8,6 +8,7 @@
 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';
@@ -257,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);
@@ -776,10 +777,10 @@ function checkFlow(built, ancestors, opts = {}) {
                     }
                     // An exit with no arm compiles to an End node, so the run FINISHES
                     // there instead of reaching a port with no edge and stalling. Better
-                    // than stalling, still probably not what the author meant — and the
-                    // End carries none of the flow's output mappings, so the run answers
-                    // with nothing (flow-builder-sdk#742). An `action: 'End'` outcome
-                    // already ends the run and needs no arm.
+                    // than stalling, still probably not what the author meant: the End
+                    // maps each output from its variable, so the run answers whatever
+                    // those hold at that point, usually nothing (flow-builder-sdk#742).
+                    // An `action: 'End'` outcome already ends the run and needs no arm.
                     const unrouted = exits.filter((e) => !seenExit.has(e.port) && e.endsProcess !== true);
                     if (unrouted.length > 0) {
                         const outs = built.outputs.map((o) => o.name);
@@ -789,8 +790,9 @@ function checkFlow(built, ancestors, opts = {}) {
                                 + `${unrouted.map((e) => JSON.stringify(e.value)).join(', ')}. Each compiles to an End node, `
                                 + `so the run finishes there`
                                 + (outs.length > 0
-                                    ? ` without writing the flow's declared output${outs.length === 1 ? '' : 's'} `
-                                        + `(${outs.join(', ')}).`
+                                    ? `, and nothing on that path sets the flow's declared output${outs.length === 1 ? '' : 's'} `
+                                        + `(${outs.join(', ')}): the End answers whatever ${outs.length === 1 ? 'its variable holds' : 'their variables hold'}, `
+                                        + `usually nothing.`
                                     : '.'),
                             suggestion: `{ value: '${unrouted[0].value}', body: (b) => … }`,
                         });
@@ -1294,9 +1296,7 @@ function checkFlow(built, ancestors, opts = {}) {
         }
     }
     // The End compile appends when the root path runs out of steps (#941).
-    const fallOff = checkFallOffEnd(built);
-    if (fallOff)
-        diags.push(fallOff);
+    diags.push(...checkFallOffEnd(built));
     // 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
@@ -1384,32 +1384,29 @@ function checkLoopListEnvelope(loop, connectors, opts, diags) {
     });
 }
 /**
- * NO_RETURN: a path that runs off the end of the flow, where a declared output
- * is never written (#941).
+ * NO_RETURN: a path that runs off the end of the flow, or off the end of a
+ * `.stepToList` / `.onError` body, where a declared output is never written
+ * (#941, #742).
  *
  * 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.
+ * and the other falls off DOES append one. A `.stepToList` body is a side exit:
+ * it never rejoins the main path, and when it runs out of steps `emitPortList`
+ * gives it an End of its own. `writtenTails` collects those bodies' tails.
  *
- * The appended End maps every output from its own variable
+ * Every such 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.
+ * feeds, or `{ updates }` on a step of that path. One warning per End: it
+ * names the outputs that are not set, and the steps the path runs out from.
  */
 function checkFallOffEnd(built) {
     if (built.outputs.length === 0)
-        return undefined;
+        return [];
     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.
@@ -1418,21 +1415,42 @@ function checkFallOffEnd(built) {
         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(', ')} })`,
+    const sideEnds = [];
+    const rootTails = writtenTails(built.steps, [{ from, written: preset }], { breaks: [], sideEnds });
+    const diags = [];
+    const unset = (tails) => {
+        const missing = built.outputs.map((o) => o.name).filter((n) => tails.some((t) => !t.written.has(n)));
+        if (missing.length === 0)
+            return undefined;
+        return { missing, steps: [...new Set(tails.filter((t) => missing.some((n) => !t.written.has(n))).map((t) => t.from))] };
     };
+    // `lead(at)` is the sentence saying where the path ends and which End it falls into.
+    const warn = (lead, u, fix) => {
+        const one = u.missing.length === 1;
+        return {
+            level: 'warning',
+            code: 'NO_RETURN',
+            message: `${lead(u.steps.map((x) => `"${x}"`).join(', '))} ${one ? 'Output' : 'Outputs'} `
+                + `${u.missing.map((n) => `"${n}"`).join(', ')} may be unset there. ${fix(one ? 'it' : 'them')}`,
+            step: u.steps[0],
+            suggestion: `.return({ ${u.missing.map((n) => `${n}: …`).join(', ')} })`,
+        };
+    };
+    // `armTails` and `writtenTails` hand on the same tails; the root End exists
+    // exactly when there are any.
+    const root = rootTails.length ? unset(rootTails) : undefined;
+    if (root) {
+        diags.push(warn((at) => `Path ending at ${at} falls into the End compile appends.`, root, (it) => `End the path with .return({ … }) or set ${it} with { updates } (a loop body may run zero times).`));
+    }
+    for (const side of sideEnds) {
+        const u = unset(side.tails);
+        if (!u)
+            continue;
+        const call = side.port === 'error' ? '.onError(…)' : `.stepToList('${side.port}', …)`;
+        diags.push(warn((at) => `The ${call} path from "${side.source}" ends at ${at} and does not rejoin the main path, `
+            + `so compile ends the run there on an End of its own.`, u, (it) => `End the path with .return({ … }), set ${it} with { updates }, or hand it back with .stepToRef('<step>').`));
+    }
+    return diags;
 }
 /**
  * `armTails`, step for step, carrying what each path has surely written. A
@@ -1446,12 +1464,31 @@ function checkFallOffEnd(built) {
  * 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.
+ *
+ * A `.stepToList` body leaves the main path as it was (as in `armTails`), but
+ * it is walked too: it starts with what was written before its port fired, and
+ * if it hands back tails, serialize ends it on an End of its own, so those
+ * tails go to `sideEnds`. On the `error` port the step failed, so its own
+ * `{ updates }` are not counted (they usually read the output it never made).
+ * Bodies nested anywhere, a plain loop's included, are walked with the same
+ * `sideEnds`.
  */
-function writtenTails(steps, incoming, breaks) {
+function writtenTails(steps, incoming, sinks) {
+    const { breaks, sideEnds } = sinks;
     let tails = incoming;
+    // What was written before the last step on this path, i.e. without its own `{ updates }`.
+    let beforeLast = surelyWritten(tails);
     for (const st of steps) {
-        if (st.kind === 'stepToList')
+        if (st.kind === 'stepToList') {
+            const source = tails[0]?.from;
+            if (source === undefined)
+                continue;
+            const entry = st.port === 'error' ? beforeLast : surelyWritten(tails);
+            const ends = writtenTails(st.body, [{ from: source, written: entry }], sinks);
+            if (ends.length)
+                sideEnds.push({ port: st.port, source, tails: ends });
             continue;
+        }
         if (st.kind === 'stepToRef') {
             if (st.port === 'output')
                 tails = [];
@@ -1464,8 +1501,9 @@ function writtenTails(steps, incoming, breaks) {
         if (st.kind === 'return' || st.kind === 'terminate')
             return [];
         const before = surelyWritten(tails);
+        beforeLast = before;
         const written = new Set([...before, ...Object.keys(st.options?.updates ?? {})]);
-        const arm = (body) => writtenTails(body, [{ from: st.name, written }], breaks);
+        const arm = (body) => writtenTails(body, [{ from: st.name, written }], sinks);
         if (st.kind === 'action') {
             tails = actionTails(st.name, st.spec, st.options?.version)
                 .map((t) => ({ from: t.from, written }));
@@ -1481,7 +1519,7 @@ function writtenTails(steps, incoming, breaks) {
         }
         else if (st.kind === 'doWhile') {
             const exits = [];
-            exits.push(...writtenTails(st.body, [{ from: st.name, written }], exits));
+            exits.push(...writtenTails(st.body, [{ from: st.name, written }], { breaks: exits, sideEnds }));
             surelyWritten(exits).forEach((n) => written.add(n));
             tails = [{ from: st.name, written }];
         }
@@ -1491,6 +1529,9 @@ function writtenTails(steps, incoming, breaks) {
             tails = [{ from: st.name, written }];
         }
         else {
+            // A plain loop's body writes nothing for sure, but its side exits still end runs.
+            if (st.kind === 'loop')
+                writtenTails(st.body, [{ from: st.name, written }], { breaks: [], sideEnds });
             tails = [{ from: st.name, written }];
         }
     }
@@ -5341,7 +5382,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
@@ -5350,12 +5391,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;
@@ -5386,19 +5453,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).

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/compile-cli.js

@@ -22,9 +22,9 @@ import { writeJsonFile } from './core/json-file.js';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
-import { serializeWithSidecars, connectorInputErrors, compileOwnsResource } from './serialize.js';
+import { serializeWithSidecars, compileOwnsResource } from './serialize.js';
 import { check } from './check.js';
-import { byoaCheckOpts, eventResolveErrorFor, openCliLibrary } from './cli-library.js';
+import { flowCheckOpts, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
 import { connectionResources, inlineAgentResources, mergeBindingsV2, mergeInlineAgentResources, readBindingsV2, readInlineAgentFiles, } from './bindings-v2.js';
@@ -70,37 +70,8 @@ export async function run(argv) {
     // One list per run; every exit path reports it (reportResult overwrites keys).
     const diagnostics = [];
     if (!noCheck) {
-        const diags = check(built, library
-            ? {
-                // The refusal serialize() would throw for an event it cannot resolve,
-                // printed as `✗ [EVENT_UNKNOWN]` before stopping instead of hiding
-                // behind "1 error(s); not emitting".
-                eventResolveError: eventResolveErrorFor(library),
-                ...byoaCheckOpts(library),
-                eventParams: (connector, event) => {
-                    try {
-                        return library.eventParameterFields(connector, event);
-                    }
-                    catch {
-                        return undefined; // unresolvable: serialize() reports it properly
-                    }
-                },
-                lookups: (connector, action, version, object) => library.lookupSpecs(connector, action, version, object),
-                resolutions: library.lookupResolutions,
-                // Same validator serialize() runs below, so the check pass names the
-                // refusal (and stops) instead of printing `0 error(s)` first.
-                connectorInputs: (spec, inputs) => {
-                    try {
-                        const rc = library.resolve(spec.key, spec.action, spec.version, spec.object);
-                        return connectorInputErrors(rc, inputs, library.lookupResolutions ?? {}, library.lookupSpecs(spec.key, spec.action, spec.version, spec.object) ?? {});
-                    }
-                    catch {
-                        return undefined;
-                    }
-                },
-                bindings,
-            }
-            : { bindings });
+        // 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(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);

package/dist/core/actions.d.ts

@@ -58,7 +58,7 @@ interface HttpInputsBase {
      *   an error port only makes sense here (`check` says so: HTTP_ONERROR_V1).
      *   The handler can answer the flow (`.return`), stop the run
      *   (`.terminate`), or compensate and continue at a step the success path
-     *   also reaches (`h.rejoin('<step>')` — see `references/error-handling.md`);
+     *   also reaches (`h.stepToRef('<step>')` — see `references/error-handling.md`);
      * - both nodes expose JSON responses as parsed values in the live product;
      *   use `returns` to declare fields before reading them. The node choice does
      *   not decide whether application/json is parsed.

package/dist/core/cli-library.d.ts

@@ -1,6 +1,7 @@
-import { Library } from './library.js';
+import { Library, type ResolvedConnector } from './library.js';
 import type { BindingsView } from './binding-messages.js';
 import { type ConnectorCheckOpts } from './connector-checks.js';
+import type { LookupResolutions, LookupSpec } from './lookups.js';
 import type { EventCheckOpts } from './event-checks.js';
 /**
  * The library for this invocation, or `undefined` when there is none.
@@ -15,17 +16,25 @@ export declare function openCliLibrary(argv: readonly string[]): Library | undef
  * The connector half of a family's check options, from a library the CLI already
  * opened.
  *
- * Every callback fails OPEN: an entry the library cannot resolve, or no library
- * at all, means "unknown", and an unknown fact fires no rule. That is what lets
- * `check` stay the fast inner-loop rung — a process with no connectors needs no
- * library, and one whose connector is absent from the library is `compile`'s
- * business to name, not this pass's to guess at.
+ * Every fact callback fails OPEN: no library at all, or an entry the library
+ * cannot resolve, means "unknown", and an unknown fact fires no rule. That is
+ * what lets `check` stay the fast inner-loop rung — a process with no
+ * connectors needs no library. The one exception is the resolution itself:
+ * `connectorResolveError` reports the refusal `compile` would throw for an
+ * action, the way `eventResolveError` does for an event, so `check` never
+ * passes a connector step `compile` refuses (#948).
+ *
+ * `inputErrors` is the family's field-contract validator. The default speaks
+ * the `=`-expression dialect BPMN uses; Flow passes its own, which renders its
+ * expressions (see `flowCheckOpts` in `../cli-library.ts`).
  *
  * The `resolutions` are the overlay's: without them every lookup already
  * recorded by `registry prepare --resolve` would be reported as still owed,
  * telling the author to re-run a prepare they already ran.
  */
-export declare function connectorCheckOpts(library: Library | undefined, bindings?: BindingsView): ConnectorCheckOpts & EventCheckOpts;
+export declare function connectorCheckOpts(library: Library | undefined, bindings?: BindingsView, inputErrors?: ConnectorInputValidator): ConnectorCheckOpts & EventCheckOpts;
+/** A family's field-contract validator: `compile`'s refusal for these inputs, or `undefined`. */
+export type ConnectorInputValidator = (rc: ResolvedConnector, inputs: Record<string, unknown>, resolutions: LookupResolutions, lookups: Readonly<Record<string, LookupSpec>>) => string | undefined;
 /**
  * `check`'s EVENT_UNKNOWN verdict: the message `library.resolveEvent` throws
  * for a subscription, or `undefined` when it resolves.

package/dist/core/cli-library.js

@@ -16,7 +16,7 @@
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { Library } from './library.js';
+import { ConnectorResolveError, Library } from './library.js';
 import { resolveLibraryDir } from './library-cache.js';
 import { flagValue } from '../cli-run.js';
 import { defaultOverlayDir } from '../workdir.js';
@@ -41,19 +41,28 @@ export function openCliLibrary(argv) {
  * The connector half of a family's check options, from a library the CLI already
  * opened.
  *
- * Every callback fails OPEN: an entry the library cannot resolve, or no library
- * at all, means "unknown", and an unknown fact fires no rule. That is what lets
- * `check` stay the fast inner-loop rung — a process with no connectors needs no
- * library, and one whose connector is absent from the library is `compile`'s
- * business to name, not this pass's to guess at.
+ * Every fact callback fails OPEN: no library at all, or an entry the library
+ * cannot resolve, means "unknown", and an unknown fact fires no rule. That is
+ * what lets `check` stay the fast inner-loop rung — a process with no
+ * connectors needs no library. The one exception is the resolution itself:
+ * `connectorResolveError` reports the refusal `compile` would throw for an
+ * action, the way `eventResolveError` does for an event, so `check` never
+ * passes a connector step `compile` refuses (#948).
+ *
+ * `inputErrors` is the family's field-contract validator. The default speaks
+ * the `=`-expression dialect BPMN uses; Flow passes its own, which renders its
+ * expressions (see `flowCheckOpts` in `../cli-library.ts`).
  *
  * The `resolutions` are the overlay's: without them every lookup already
  * recorded by `registry prepare --resolve` would be reported as still owed,
  * telling the author to re-run a prepare they already ran.
  */
-export function connectorCheckOpts(library, bindings) {
+export function connectorCheckOpts(library, bindings, inputErrors = (rc, inputs, resolutions, lookups) => connectorInputErrors(rc, inputs, resolutions, lookups, { dialect: EQUALS_EXPR_DIALECT })) {
     if (!library)
         return bindings ? { bindings } : {};
+    // One memoized resolve per connector step, shared by `connectorResolveError`
+    // and `connectorInputs`, so the second hook does not resolve again.
+    const resolve = connectorResolver(library);
     return {
         eventResolveError: eventResolveErrorFor(library),
         ...byoaCheckOpts(library),
@@ -85,26 +94,51 @@ export function connectorCheckOpts(library, bindings) {
                 return undefined;
             }
         },
+        // The refusal compile throws for an operation it cannot resolve, with its
+        // code and text: CONNECTOR_NOT_IN_LIBRARY, CONNECTOR_OBJECT_REQUIRED,
+        // CONNECTOR_OBJECT_NOT_GENERIC.
+        connectorResolveError: (spec) => {
+            const r = resolve(spec);
+            return 'error' in r ? r.error : undefined;
+        },
         // The field contract compile enforces, from the same validator, so the inner
         // loop and the emit rung cannot disagree about a missing required field, an
-        // unknown key or a mistyped value. An operation the library cannot resolve is
-        // compile's business to name — here it just means "unknown".
-        //
-        // The `=`-expression dialect, because this bag serves the families that spell
-        // an expression that way. Flow binds its own `connectorInputErrors` in
-        // `serialize.ts`, which carries `renderDeep` with it, and overrides this.
+        // unknown key or a mistyped value. An unresolvable operation is
+        // `connectorResolveError`'s to report; here it just means "unknown".
         connectorInputs: (spec, inputs) => {
-            try {
-                const rc = library.resolve(spec.key, spec.action, spec.version, spec.object);
-                return connectorInputErrors(rc, inputs, library.lookupResolutions ?? {}, library.lookupSpecs(spec.key, spec.action, spec.version, spec.object) ?? {}, { dialect: EQUALS_EXPR_DIALECT });
-            }
-            catch {
+            const r = resolve(spec);
+            if (!('rc' in r))
                 return undefined;
-            }
+            return inputErrors(r.rc, inputs, library.lookupResolutions ?? {}, library.lookupSpecs(spec.key, spec.action, spec.version, spec.object) ?? {});
         },
         ...(bindings ? { bindings } : {}),
     };
 }
+/**
+ * `library.resolve` for one connector step, memoized per step for the life of
+ * one check's options. A {@link ConnectorResolveError} is the refusal compile
+ * throws and becomes `error`; anything else thrown is not a verdict about the
+ * author's source and stays "unknown", as before.
+ */
+function connectorResolver(library) {
+    const memo = new Map();
+    return (spec) => {
+        const id = JSON.stringify([spec.key, spec.action, spec.version ?? null, spec.object ?? null]);
+        let r = memo.get(id);
+        if (!r) {
+            try {
+                r = { rc: library.resolve(spec.key, spec.action, spec.version, spec.object) };
+            }
+            catch (error) {
+                r = error instanceof ConnectorResolveError
+                    ? { error: { code: error.code, message: error.message } }
+                    : { unknown: true };
+            }
+            memo.set(id, r);
+        }
+        return r;
+    };
+}
 /**
  * `check`'s EVENT_UNKNOWN verdict: the message `library.resolveEvent` throws
  * for a subscription, or `undefined` when it resolves.

package/dist/core/connector-checks.d.ts

@@ -113,6 +113,21 @@ export interface ConnectorCheckOpts {
     resolutions?: LookupResolutions;
     /** Whether a connector step's schema is materialized locally. */
     schemaReadiness?: (connector: string, action: string, version?: string, object?: string) => SchemaReadiness | undefined;
+    /**
+     * Why `compile` could not resolve this operation at all (`library.resolve`
+     * throws), or `undefined` when it resolves. Checked before
+     * {@link ConnectorCheckOpts.connectorInputs}, which answers `undefined` for an
+     * unresolvable operation and so cannot tell "not in the library" from "no facts".
+     */
+    connectorResolveError?: (spec: {
+        key: string;
+        action: string;
+        version?: string;
+        object?: string;
+    }) => {
+        code: string;
+        message: string;
+    } | undefined;
     /** What `compile` would refuse these inputs with, or `undefined` when it would accept them. */
     connectorInputs?: (spec: {
         key: string;
@@ -157,9 +172,10 @@ export declare function checkConnectorLookups(where: string, spec: ConnectorSpec
  */
 export declare function checkConnectorSchema(where: string, spec: ConnectorSpec, opts: ConnectorCheckOpts, dialect: ExprDialect, report: ReportConnector): void;
 /**
- * The field contract and the binding names `compile` enforces, reported here first.
+ * The operation, its field contract and the binding names `compile` enforces,
+ * reported here first.
  *
- * Both rules run only with the facts in hand (a library for the fields, a
+ * Each rule runs only with the facts in hand (a library for the operation and its fields, a
  * bindings.json for the names); without them `check` stays a pure function of the
  * built model and says nothing, as before.
  */