@uipath/maestro-builder-sdk 6.8.4 → 6.8.5

package/dist/check.js

@@ -15,7 +15,7 @@ import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from '
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
-import { prepareCommand } from './core/cli-spelling.js';
+import { prepareCommand, resolveFlagArg } from './core/cli-spelling.js';
 export function check(built, opts = {}) {
     return checkFlow(built, [], opts);
 }
@@ -1264,6 +1264,9 @@ function checkFlow(built, ancestors, opts = {}) {
 function checkConnectorLookups(step, spec, opts, diags) {
     const specs = opts.lookups?.(spec.key, spec.action, spec.version, spec.object);
     const resolutions = opts.resolutions ?? {};
+    // One LOOKUP_LITERAL_ID per field: a multiselect of three pasted ids is one
+    // mistake with one remedy, not three.
+    const literalWarned = new Set();
     const visit = (value, path) => {
         if (isLookupToken(value)) {
             // A match key the field does not declare is certainly wrong, and the
@@ -1304,7 +1307,17 @@ function checkConnectorLookups(step, spec, opts, diags) {
             return;
         }
         if (Array.isArray(value)) {
-            value.forEach((v, i) => visit(v, [...path, String(i)]));
+            // An element is named by the WIRE name the lookup table is keyed on —
+            // `users[*]`, `contacts[*].id` — not by its index. `users.0` matched no
+            // spec, so a pasted id, a token with a bad match key, or a runtime value
+            // inside a multiselect passed every rule below unseen. A name that already
+            // is the array's (a flat `'users[*]'` key, or a field typed as an array)
+            // stays as it is.
+            const last = path[path.length - 1] ?? '';
+            const element = last.endsWith('[*]') || specs?.[path.join('.')]
+                ? path
+                : [...path.slice(0, -1), `${last}[*]`];
+            value.forEach((v) => visit(v, element));
             return;
         }
         if (value && typeof value === 'object' && !(value instanceof Expr)) {
@@ -1329,6 +1342,9 @@ function checkConnectorLookups(step, spec, opts, diags) {
         const literal = value instanceof Expr ? value.value : value;
         if (typeof literal !== 'string')
             return;
+        if (literalWarned.has(field))
+            return;
+        literalWarned.add(field);
         const { target, call } = lookupPhrases(field, lookup, spec);
         diags.push({
             level: 'warning',
@@ -1340,7 +1356,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
                 + `compile nor deploy can tell. Write what you mean and resolve it late:\n`
                 + `  ${call}\n`
                 + `then record the value once with \`${prepareCommand(spec.key)} `
-                + `${spec.action} --resolve ${field}:${lookup.by[0] ?? 'id'}=<value>\`.`,
+                + `${spec.action} --resolve ${resolveFlagArg(field, lookup.by[0] ?? 'id', '<value>')}\`.`,
             step,
         });
     };
@@ -1557,7 +1573,7 @@ function runtimeLookupDiagnostic(step, spec, field, lookup, value) {
         + `neither compile nor validate can tell. Resolve the value you know instead:\n`
         + `  ${call}\n`
         + `then record it once with \`${prepareCommand(spec.key, spec.action)} `
-        + `--resolve ${field}:${lookup.by[0] ?? 'id'}=<value>\`; or read the id from a step whose `
+        + `--resolve ${resolveFlagArg(field, lookup.by[0] ?? 'id', '<value>')}\`; or read the id from a step whose `
         + `output returned one (\`${lookup.value}\`).`
         + (isEmail
             ? `\n\`${single.raw}\` reads \`${leaf}\`, an e-mail address, not a \`${target}\`.`

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

@@ -37,3 +37,13 @@ export declare function cliSpelling(env?: CliSpellingEnv): string;
  * ```
  */
 export declare function prepareCommand(...args: string[]): string;
+/**
+ * The argument of one `--resolve <field>:<by>=<value>`, single-quoted when the
+ * shell would otherwise mangle it.
+ *
+ * @param field - The lookup field's wire name, e.g. `channel` or `users[*]`.
+ * @param by - The match key, e.g. `profile.email`.
+ * @param value - The value to match, or the `<value>` placeholder.
+ * @returns `channel:profile.email=d@x.com` as is; `'users[*]:profile.real_name=Coder Evals'` quoted.
+ */
+export declare function resolveFlagArg(field: string, by: string, value: string): string;

package/dist/core/cli-spelling.js

@@ -60,3 +60,27 @@ export function cliSpelling(env = ambientEnv()) {
 export function prepareCommand(...args) {
     return [cliSpelling(), 'registry', 'prepare', ...args.filter(Boolean)].join(' ');
 }
+/**
+ * Characters that make a `--resolve` argument unsafe to paste unquoted. `[*]`
+ * is a shell glob (every multiselect wire name, `users[*]`), whitespace splits
+ * a real name (`Coder Evals`) into two arguments, and quotes, `$`, backslash
+ * and the control operators change what the shell hands over. The `<value>`
+ * placeholder a template prints is stripped before the test, so a template
+ * with nothing else unsafe keeps its bytes.
+ */
+const SHELL_UNSAFE = /[\s'"`$\\[\]*?;&|(){}!#~<>]/;
+/**
+ * The argument of one `--resolve <field>:<by>=<value>`, single-quoted when the
+ * shell would otherwise mangle it.
+ *
+ * @param field - The lookup field's wire name, e.g. `channel` or `users[*]`.
+ * @param by - The match key, e.g. `profile.email`.
+ * @param value - The value to match, or the `<value>` placeholder.
+ * @returns `channel:profile.email=d@x.com` as is; `'users[*]:profile.real_name=Coder Evals'` quoted.
+ */
+export function resolveFlagArg(field, by, value) {
+    const arg = `${field}:${by}=${value}`;
+    if (!SHELL_UNSAFE.test(arg.replaceAll('<value>', '')))
+        return arg;
+    return `'${arg.replaceAll("'", `'\\''`)}'`;
+}

package/dist/core/lookups.js

@@ -27,7 +27,7 @@
  * degenerate classes the generator excludes and why generating for them would
  * make the surface worse rather than more complete.
  */
-import { prepareCommand } from './cli-spelling.js';
+import { prepareCommand, resolveFlagArg } from './cli-spelling.js';
 /** True when `v` is an unresolved {@link LookupToken}. */
 export function isLookupToken(v) {
     return (typeof v === 'object' && v !== null &&
@@ -192,7 +192,9 @@ export function unresolvedLookupMessage(token) {
     return (`input "${field}" is an unresolved lookup (${by}=${JSON.stringify(value)}). ` +
         `Compile does not make network calls, so the value has to be resolved first:\n` +
         `  ${prepareCommand(key, action)} \\\n` +
-        `    --resolve ${field}:${by}=${String(value)}`);
+        // Quoted only when the shell would mangle it: a multiselect's `users[*]`
+        // is a glob and a real name has spaces, and the last line is meant to paste.
+        `    --resolve ${resolveFlagArg(field, by, String(value))}`);
 }
 // ─── Classification, mirroring `_lookups.py` ─────────────────────────────────
 //

package/dist/registry/generators/markdown/sections/lookups.js

@@ -11,6 +11,7 @@ import { sortedStrings } from "../../../compat/compare.js";
 import { pyStr, splitOnce } from "../../../compat/pystr.js";
 import { classify, referenceOf } from "../../../lookup-specs.js";
 import { byAliases } from "../../../naming.js";
+import { resolveFlagArg } from "../../../../core/cli-spelling.js";
 import { authoringField, referenceCollection, referenceQuery } from "../common.js";
 import { firstValue, IDENT, pyOr, pyTruthy, strList } from "../pyvalue.js";
 /** The `resources run list` call that shows what an identity-lookup field accepts. */
@@ -85,9 +86,21 @@ export function lookupLines(connectorKey, action, fields, symbol, invariant) {
             "different connection. Resolve it late:");
         out.push("");
         out.push("```ts");
-        // A dotted wire name is a legal object key only when quoted.
-        const key = IDENT.test(firstName) ? firstName : pyJsonString(firstName);
-        out.push(`${key}: ${call}${sample}`);
+        // A plain multiselect (`users[*]`) is authored as an array of lookups under
+        // its authoring name, the same form `## Example` prints and the one that
+        // compiles to one id per element. Any other wire name is written as a key —
+        // a dotted one is a legal object key only when quoted — and one ending in
+        // `[*]` (`recipients.listIds[*]`) still names ONE list, so its value is an
+        // array too: the flat key compiles to the same list the nested
+        // `recipients: { listIds: [...] }` of `## Example` does.
+        const [authoringName, , multiselectWire] = authoringField(firstField);
+        if (multiselectWire) {
+            out.push(`${authoringName}: [${call}${sample}]`);
+        }
+        else {
+            const key = IDENT.test(firstName) ? firstName : pyJsonString(firstName);
+            out.push(firstName.endsWith("[*]") ? `${key}: [${call}${sample}]` : `${key}: ${call}${sample}`);
+        }
         out.push("```");
         out.push("");
         out.push("| field | helpers | matches on | sends |");
@@ -116,10 +129,12 @@ export function lookupLines(connectorKey, action, fields, symbol, invariant) {
         // ONE command carrying every --resolve, and no `--connection-id`.
         out.push("```bash");
         out.push(`npx flow-sdk registry prepare ${connectorKey} ${action} \\`);
+        // The WIRE name (`users[*]`), which is what prepare's lookup table is keyed
+        // on — the authoring name (`users`) is refused as RESOLVE_UNKNOWN_FIELD.
         const resolves = resolvable.map(([f, reference]) => {
-            const [name] = authoringField(f);
+            const wire = pyStr(pyOr(f.name, authoringField(f)[0]));
             const names = pyOr(strList(reference.lookupNames), ["id"]);
-            return `  --resolve ${name}:${names[0]}=<value>`;
+            return `  --resolve ${resolveFlagArg(wire, names[0], "<value>")}`;
         });
         for (const line of resolves.slice(0, -1))
             out.push(`${line} \\`);

package/dist/registry/prepare/ledger.d.ts

@@ -55,7 +55,9 @@ export interface ResolutionPlan {
 export declare class ResolutionsExhausted extends LookupExhausted {
     readonly first: LookupExhausted;
     readonly plan: ResolutionPlan;
-    constructor(first: LookupExhausted, plan: ResolutionPlan);
+    constructor(first: LookupExhausted, plan: ResolutionPlan, 
+    /** Every miss of the run, when there was more to say than `first`'s own message. */
+    message?: string);
 }
 /** What one `--resolve` run needs; `objectName` narrows the overlay entry the specs are read from. */
 export interface ResolveRun {

package/dist/registry/prepare/ledger.js

@@ -20,7 +20,7 @@
 import { lookupKey } from "../../core/lookups.js";
 import { pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedStrings } from "../compat/compare.js";
-import { PrepareRefusal, resolutionLine, unknownLookupMessage, wroteResolutionsLine } from "./messages.js";
+import { PrepareRefusal, incompleteRunMessage, notTriedLine, resolutionLine, unknownLookupMessage, wroteResolutionsLine, } from "./messages.js";
 import { LedgerRefusal, RESOLUTIONS_FILENAME, ledgerPath, readLedger, writeLedger } from "./objects.js";
 import { lookupSpecsFromOverlay } from "./overlay.js";
 import { LookupExhausted, orderResolutions, parseResolveFlag, resolveOne } from "./resolve.js";
@@ -87,8 +87,10 @@ export function findResolution(existing, nodeType, field, by, value) {
 export class ResolutionsExhausted extends LookupExhausted {
     first;
     plan;
-    constructor(first, plan) {
-        super(first.message, first);
+    constructor(first, plan, 
+    /** Every miss of the run, when there was more to say than `first`'s own message. */
+    message = first.message) {
+        super(message, first);
         this.first = first;
         this.plan = plan;
         this.name = "ResolutionsExhausted";
@@ -117,13 +119,29 @@ export async function writeResolutions(run, specs) {
     const recorded = pyGet(ledger, "resolutions", null);
     const existing = isPlainObject(recorded) ? { ...recorded } : {};
     const resolved = new Map();
+    // An exhaustive miss no longer ends the run: the rest are still tried, so ONE
+    // run reports every value this connection does not hold — a multiselect of
+    // three names used to cost three runs to learn about three misses. A lookup
+    // addressed through a field that missed is skipped, since its path cannot be
+    // built. The WRITE stays all-or-nothing; see the throw below.
+    const misses = [];
+    const unresolved = new Set();
+    const notTried = [];
+    const answered = [];
     for (const [field, by, value] of ordered) {
+        const blockedBy = (table.get(field)?.dependsOn ?? []).find((prerequisite) => unresolved.has(prerequisite));
+        if (blockedBy !== undefined) {
+            unresolved.add(field);
+            notTried.push(notTriedLine(field, by, value, blockedBy));
+            continue;
+        }
         const key = resolutionKey(run.nodeType, field, by, value);
         const found = findResolution(existing, run.nodeType, field, by, value);
         if (found && !run.refreshLookups) {
             const kept = pyStrAny(pyGet(found.row, "value", null));
             resolved.set(field, kept);
             run.reporter.info(resolutionLine(field, by, value, kept, true));
+            answered.push(resolutionLine(field, by, value, kept, true));
             continue;
         }
         let got;
@@ -152,8 +170,25 @@ export async function writeResolutions(run, specs) {
             // refusal, whose text already names the remedy ("the value may be
             // further in"). Upstream's own tests never covered the row, which is
             // how it shipped unimplemented.
-            if (error instanceof LookupExhausted && !error.capped)
-                throw new ResolutionsExhausted(error, { specs: table, ordered });
+            //
+            // Only that exhaustive miss is collected; every other refusal — capped,
+            // transport, unsearchable `by` — still ends the run at once, as before,
+            // so none of them can reach the cross-connection retry.
+            if (error instanceof LookupExhausted && !error.capped) {
+                misses.push(error);
+                unresolved.add(field);
+                continue;
+            }
+            // An exhaustive miss collected EARLIER still decides the run: it is
+            // evidence against this connection, and before the misses were collected
+            // it would have ended the run and started the cross-connection retry
+            // before this lookup was ever tried. So that retry still runs, and its
+            // refusal names the collected misses and then this error.
+            if (misses.length > 0) {
+                const text = error instanceof Error ? error.message : String(error);
+                const lines = [...misses.map((miss) => miss.message), ...notTried, text.startsWith(`${field}:`) ? text : `${field}: ${text}`];
+                throw new ResolutionsExhausted(misses[0], { specs: table, ordered }, incompleteRunMessage(lines, [], answered, ordered.length));
+            }
             throw error;
         }
         resolved.set(field, got);
@@ -163,6 +198,21 @@ export async function writeResolutions(run, specs) {
             delete existing[found.key];
         existing[key] = { nodeType: run.nodeType, field, by, match: value, value: got };
         run.reporter.info(resolutionLine(field, by, value, got));
+        answered.push(resolutionLine(field, by, value, got));
+    }
+    // ALL-OR-NOTHING, deliberately, even though the rows that DID resolve are
+    // correct for this connection. A ledger row carries no connection: it is
+    // keyed `[nodeType, field, by, value]`, and a later run REUSES a recorded row
+    // without asking again unless `--refresh-lookups` is passed (above). So a
+    // partial write from connection A would hand A's workspace ids to the next
+    // run bound to connection B — the 2026-09-23 run resolved one recipient on
+    // one Slack workspace and then re-pinned to another. Until rows are keyed by
+    // connection, a run that misses records nothing and says what it found.
+    if (misses.length > 0) {
+        const message = misses.length === 1 && notTried.length === 0 && answered.length === 0
+            ? misses[0].message
+            : incompleteRunMessage(misses.map((miss) => miss.message), notTried, answered, ordered.length);
+        throw new ResolutionsExhausted(misses[0], { specs: table, ordered }, message);
     }
     const written = { ...ledger, schemaVersion: "1", resolutions: existing };
     writeLedger(path, written);

package/dist/registry/prepare/messages.d.ts

@@ -111,6 +111,14 @@ export declare function lookupVocabularyLines(connectorKey: string, action: stri
 export declare function unknownLookupMessage(unknown: readonly string[], nodeType: string, known: readonly string[]): string;
 /** `  <field>: <by>=<value> -> <id>`, with ` (already resolved)` when the ledger answered. */
 export declare function resolutionLine(field: string, by: string, value: string, got: unknown, alreadyResolved?: boolean): string;
+/** A lookup skipped because the field its collection path is built from did not resolve. */
+export declare function notTriedLine(field: string, by: string, value: string, prerequisite: string): string;
+/**
+ * Every miss of one `--resolve` run, then what DID resolve. Nothing is recorded
+ * when anything misses, and the reader needs both halves to fix every value in
+ * one pass rather than one per run.
+ */
+export declare function incompleteRunMessage(misses: readonly string[], notTried: readonly string[], answered: readonly string[], requested: number): string;
 export declare function wroteResolutionsLine(count: number, ledgerPath: string): string;
 /**
  * `generated N connector module(s) → <out>` — the descriptor generator's own

package/dist/registry/prepare/messages.js

@@ -262,6 +262,23 @@ export function unknownLookupMessage(unknown, nodeType, known) {
 export function resolutionLine(field, by, value, got, alreadyResolved = false) {
     return `  ${field}: ${by}=${value} -> ${pyStrAny(got)}${alreadyResolved ? " (already resolved)" : ""}`;
 }
+/** A lookup skipped because the field its collection path is built from did not resolve. */
+export function notTriedLine(field, by, value, prerequisite) {
+    return `${field}: ${by}=${pyRepr(value)} not tried — its collection is addressed through ${pyRepr(prerequisite)}, which did not resolve.`;
+}
+/**
+ * Every miss of one `--resolve` run, then what DID resolve. Nothing is recorded
+ * when anything misses, and the reader needs both halves to fix every value in
+ * one pass rather than one per run.
+ */
+export function incompleteRunMessage(misses, notTried, answered, requested) {
+    const failed = misses.length + notTried.length;
+    return (`${failed} of ${requested} lookup(s) did not resolve, so nothing was recorded:\n` +
+        [...misses, ...notTried].map((line) => `  ${line}`).join("\n") +
+        (answered.length > 0
+            ? `\nThese resolved, and are recorded only once every lookup of the run does:\n${answered.join("\n")}`
+            : ""));
+}
 export function wroteResolutionsLine(count, ledgerPath) {
     return `  wrote ${count} resolution(s) to ${ledgerPath}`;
 }

package/dist/registry/prepare/pipeline.js

@@ -163,7 +163,10 @@ export async function prepareConnector(options, ports) {
             connectionId: connected.connectionId,
             connection: options.connection,
             pinned,
-        }, error.plan, error.first);
+        }, error.plan, 
+        // The wrapper, not `error.first`: same facts, and its message names every
+        // miss of the run rather than only the first.
+        error);
         // Undo the bindings this run wrote for the connection that cannot serve
         // the lookups, then start over pinned to the one that can. Re-running
         // rather than switching in place is deliberate: the overlay and its

package/dist/registry/prepare/resolve.d.ts

@@ -36,7 +36,21 @@ export interface LookupExhaustedFacts {
     pages: number;
     /** True when a cap, not the collection's end, stopped the scan. */
     capped: boolean;
+    /**
+     * Every distinct value the scan saw at `by`, when the whole collection was
+     * read and holds at most {@link CANDIDATE_LIMIT} records — what to pick from.
+     */
+    candidates?: readonly string[];
+    /** A value the scan saw that equals the wanted one ignoring case; the match itself is exact. */
+    near?: string;
 }
+/**
+ * A collection this small is listed in full when a value is not in it. The
+ * 2026-09-23 run guessed `send_as` 'Bot token' from the field's description
+ * while `available_tokens` held two records, 'Bot' and 'User', and the refusal
+ * said only "scanned 2 record(s)".
+ */
+export declare const CANDIDATE_LIMIT = 20;
 /**
  * The collection was read to the end on THIS connection and had no match
  * (`_resolve.LookupExhausted`).
@@ -63,6 +77,8 @@ export declare class LookupExhausted extends ResolutionRefusal {
     readonly scanned: number;
     readonly pages: number;
     readonly capped: boolean;
+    readonly candidates?: readonly string[];
+    readonly near?: string;
     constructor(message: string, facts: LookupExhaustedFacts);
 }
 /** One `--resolve <field>:<by>=<value>`, parsed. */
@@ -97,8 +113,17 @@ type SpecTable = ReadonlyMap<string, ResolveSpec> | Readonly<Record<string, Reso
  * unsubstituted `{placeholder}` in a URL, and the error the connector returns
  * for that names neither field.
  *
- * A field requested twice keeps its first position and its LAST `by`/`value`,
- * as the Python's dict did.
+ * A field requested more than once keeps its first position and EVERY distinct
+ * `by`/`value`, in the order given; an exact repeat collapses. DELIBERATE
+ * DIVERGENCE FROM THE PYTHON, whose dict kept one request per field — its LAST
+ * `by`/`value` — and dropped the rest without a word. That is fatal for a
+ * multiselect: `--resolve users[*]:…=A --resolve users[*]:…=B --resolve
+ * users[*]:…=C`, one command as the library page prints it, resolved and
+ * recorded only C (2026-09-23, skill-flow-ipe-multiselect), and the probe of
+ * the other connections asked only about C too.
+ *
+ * A PREREQUISITE given more than one value is refused: its id is substituted
+ * into the dependent's collection path, and one placeholder takes one id.
  */
 export declare function orderResolutions(requested: readonly ResolveRequest[], specs: SpecTable): ResolveRequest[];
 /**

package/dist/registry/prepare/resolve.js

@@ -50,6 +50,13 @@ export class ResolutionRefusal extends Refusal {
         this.name = "ResolutionRefusal";
     }
 }
+/**
+ * A collection this small is listed in full when a value is not in it. The
+ * 2026-09-23 run guessed `send_as` 'Bot token' from the field's description
+ * while `available_tokens` held two records, 'Bot' and 'User', and the refusal
+ * said only "scanned 2 record(s)".
+ */
+export const CANDIDATE_LIMIT = 20;
 /**
  * The collection was read to the end on THIS connection and had no match
  * (`_resolve.LookupExhausted`).
@@ -76,6 +83,8 @@ export class LookupExhausted extends ResolutionRefusal {
     scanned;
     pages;
     capped;
+    candidates;
+    near;
     constructor(message, facts) {
         super(message, "RESOLVE_NO_MATCH");
         this.name = "LookupExhausted";
@@ -86,6 +95,10 @@ export class LookupExhausted extends ResolutionRefusal {
         this.scanned = facts.scanned;
         this.pages = facts.pages;
         this.capped = facts.capped;
+        if (facts.candidates !== undefined)
+            this.candidates = facts.candidates;
+        if (facts.near !== undefined)
+            this.near = facts.near;
     }
 }
 /**
@@ -123,13 +136,27 @@ function specOf(specs, field) {
  * unsubstituted `{placeholder}` in a URL, and the error the connector returns
  * for that names neither field.
  *
- * A field requested twice keeps its first position and its LAST `by`/`value`,
- * as the Python's dict did.
+ * A field requested more than once keeps its first position and EVERY distinct
+ * `by`/`value`, in the order given; an exact repeat collapses. DELIBERATE
+ * DIVERGENCE FROM THE PYTHON, whose dict kept one request per field — its LAST
+ * `by`/`value` — and dropped the rest without a word. That is fatal for a
+ * multiselect: `--resolve users[*]:…=A --resolve users[*]:…=B --resolve
+ * users[*]:…=C`, one command as the library page prints it, resolved and
+ * recorded only C (2026-09-23, skill-flow-ipe-multiselect), and the probe of
+ * the other connections asked only about C too.
+ *
+ * A PREREQUISITE given more than one value is refused: its id is substituted
+ * into the dependent's collection path, and one placeholder takes one id.
  */
 export function orderResolutions(requested, specs) {
     const byField = new Map();
-    for (const request of requested)
-        byField.set(request[0], request);
+    for (const request of requested) {
+        const same = byField.get(request[0]);
+        if (same === undefined)
+            byField.set(request[0], [request]);
+        else if (!same.some(([, by, value]) => by === request[1] && value === request[2]))
+            same.push(request);
+    }
     const ordered = [];
     const placed = new Set();
     const place = (field, trail) => {
@@ -141,7 +168,14 @@ export function orderResolutions(requested, specs) {
         }
         const dependsOn = specOf(specs, field)?.dependsOn;
         for (const prerequisite of Array.isArray(dependsOn) ? dependsOn : []) {
-            if (byField.has(prerequisite)) {
+            const given = byField.get(prerequisite);
+            if (given !== undefined && given.length > 1) {
+                throw new ResolutionRefusal(`cannot resolve ${pyRepr(field)}: its collection is addressed through ` +
+                    `${pyRepr(prerequisite)}, which was given ${given.length} values ` +
+                    `(${given.map(([, by, value]) => `${by}=${pyRepr(value)}`).join(", ")}). ` +
+                    `The path takes one id; keep one --resolve ${prerequisite}:<by>=<value> and re-run.`, "RESOLVE_AMBIGUOUS_PREREQUISITE");
+            }
+            if (given !== undefined) {
                 place(prerequisite, [...trail, field]);
             }
             else {
@@ -151,7 +185,7 @@ export function orderResolutions(requested, specs) {
             }
         }
         placed.add(field);
-        ordered.push(byField.get(field));
+        ordered.push(...byField.get(field));
     };
     for (const [field] of requested)
         place(field, []);
@@ -433,9 +467,21 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
         query = query ? `${query}&${filtered}` : filtered;
     }
     const scan = scanCollection(client, connectorKey, collection, connectionId, query);
+    // What the collection DOES hold at `by`, for the refusal: kept only while it
+    // could still be listed in full, plus the first case-insensitive equal.
+    const held = [];
+    let near;
     let step = await scan.next();
     while (!step.done) {
         for (const record of step.value) {
+            const at = readPath(record, by);
+            if (at !== null && at !== undefined) {
+                const text = pyStrAny(at);
+                if (held.length <= CANDIDATE_LIMIT && !held.includes(text))
+                    held.push(text);
+                if (near === undefined && text !== value && text.toLowerCase() === value.toLowerCase())
+                    near = text;
+            }
             if (matchRecord(record, by, value)) {
                 const got = readPath(record, send);
                 if (got === null) {
@@ -463,8 +509,24 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
     // The listing command is still offered, once, by the caller's terminal
     // report — where every connection has been tried and seeing what IS there
     // is finally the next step rather than a detour.
+    //
+    // What it DOES carry is what the collection holds, when that is small enough
+    // to read in one line, and a case-only near miss: facts about this
+    // connection, not a remedy. `matchRecord` stays exact — nothing is picked.
+    //
+    // Never under a server-side filter: the scan then read only the records the
+    // filter returned (`name like '%Coder Eval%'` gives 'Coder Evals' and 'Coder
+    // Eval Test'), and listing that subset as what the collection "holds" would
+    // be false. 693 library operations declare a `filterPattern`.
+    const candidates = !capped && !pyTruthy(filterPattern) && scanned <= CANDIDATE_LIMIT && held.length > 0 ? held : undefined;
     throw new LookupExhausted(`${field}: no record in ${pyRepr(collection)} has ${by}=${pyRepr(value)} ` +
         `(scanned ${scanned} record(s) across ${pages + 1} page(s)` +
         (capped ? `; STOPPED AT THE ${MAX_SCANNED}-record cap, so the value may be further in` : "; collection exhausted") +
-        `) on connection ${connectionId}.`, { field, collection, by, value, scanned, pages: pages + 1, capped });
+        `) on connection ${connectionId}.` +
+        (near !== undefined ? ` Did you mean ${pyRepr(near)}? The match is exact, case included.` : "") +
+        (candidates !== undefined ? ` It holds: ${candidates.map(pyRepr).join(", ")}.` : ""), {
+        field, collection, by, value, scanned, pages: pages + 1, capped,
+        ...(candidates !== undefined ? { candidates } : {}),
+        ...(near !== undefined ? { near } : {}),
+    });
 }

package/dist/serialize.js

@@ -3474,8 +3474,18 @@ function eventDetail(rc, sub, nodeId, opts) {
         errorState: { issues: [] },
     };
 }
-/** Recursively render Exprs nested inside objects/arrays (for connector inputs). */
+/**
+ * Recursively render Exprs nested inside objects/arrays (for connector inputs).
+ *
+ * A lookup token is REFUSED, never rendered. `buildConnectorInputs` swaps every
+ * token it can place — a field's whole value, or an element of an array — so a
+ * token that reaches here sits where nothing resolves it: inside an object value,
+ * or in a custom node's inputs. Recursing into it would put `{"__lookup": …}` on
+ * the wire where the connector expects an id.
+ */
 function renderDeep(val, rename = NO_RENAME) {
+    if (isLookupToken(val))
+        throw new Error(misplacedLookupMessage(val));
     if (val instanceof Expr)
         return renderValue(val, rename);
     if (Array.isArray(val))
@@ -3488,6 +3498,13 @@ function renderDeep(val, rename = NO_RENAME) {
     }
     return val;
 }
+/** Why {@link renderDeep} refused a token: where a lookup CAN go, and what it would have emitted. */
+function misplacedLookupMessage(token) {
+    const { field, by, value } = token.__lookup;
+    return (`lookup('${field}') (${by}=${JSON.stringify(value)}) is in a position no lookup is resolved from: ` +
+        `a lookup() must be the whole value of a connector input, or an element of an array input. ` +
+        `Emitting it here would send a raw {"__lookup": …} object where the connector expects an id.`);
+}
 function newScope(outputs, vars = []) {
     return {
         nodes: [],
@@ -6118,16 +6135,35 @@ function buildConnectorInputs(rc, inputs, rename = NO_RENAME, resolutions = {},
         // NOT rendered as a placeholder: emitting something for a value nobody
         // resolved would produce a flow that compiles and then talks to the wrong
         // record, which is exactly the failure the lookup surface exists to remove.
-        if (isLookupToken(nested.value)) {
-            const resolved = resolvedValue(nested.value, resolutions);
-            if (resolved === undefined) {
-                if (policy.unresolvedLookups !== 'ignore')
-                    errs.push(unresolvedLookupMessage(nested.value));
+        //
+        // A token is swapped wherever the field's value can hold one: the whole
+        // value, or an element of an array at any depth. A multiselect is
+        // `users: [lookup(…), lookup(…)]` — the form `ConnectorLookupValue`'s array
+        // branch types and the generated `## Example` prints — and until this swapped
+        // only the whole-value case, so every token inside the array reached
+        // validation as an object ("expected string, got object") with every lookup
+        // recorded. An unresolved element under 'ignore' becomes `null`, which
+        // validation skips, so `check` still type-checks the resolved siblings.
+        const unresolved = [];
+        const swapped = swapLookupTokens(nested.value, resolutions, unresolved);
+        if (unresolved.length) {
+            if (policy.unresolvedLookups !== 'ignore') {
+                for (const token of unresolved)
+                    errs.push(unresolvedLookupMessage(token));
                 continue;
             }
-            nested = { ...nested, value: resolved };
+            if (isLookupToken(nested.value))
+                continue;
         }
-        validateConnectorFieldValue(f, nested.value, flat ? 0 : nested.projectedArrays, errs);
+        nested = { ...nested, value: swapped };
+        // A FLAT key whose wire name ends in `[*]` names one array: an array value
+        // there is checked element by element, as the nested form is. A flat scalar
+        // keeps depth 0 and is emitted as the scalar it is — the product wraps it
+        // into a one-element list (flow-v1 `convertDotNotationToNested`).
+        const depth = flat
+            ? (f.name.endsWith('[*]') && Array.isArray(nested.value) ? 1 : 0)
+            : nested.projectedArrays;
+        validateConnectorFieldValue(f, nested.value, depth, errs);
         if (f.location === 'multipart') {
             partValues.set(f.name, renderDeep(nested.value, rename));
             continue;
@@ -6195,6 +6231,29 @@ function buildConnectorInputs(rc, inputs, rename = NO_RENAME, resolutions = {},
     }
     return slots;
 }
+/**
+ * `value` with every lookup token swapped for its recorded id: the value itself,
+ * or the elements of an array at any depth. An unrecorded token is pushed to
+ * `unresolved` and stands as `null`, so an array keeps its length.
+ *
+ * Objects are NOT descended: a lookup's place is a field's value or an element
+ * of an array field (`ConnectorLookupValue`), and a nested path such as
+ * `contacts[*].id` reaches here already projected to its leaf array. A token
+ * anywhere else is refused by {@link renderDeep}.
+ */
+function swapLookupTokens(value, resolutions, unresolved) {
+    if (isLookupToken(value)) {
+        const resolved = resolvedValue(value, resolutions);
+        if (resolved === undefined) {
+            unresolved.push(value);
+            return null;
+        }
+        return resolved;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => swapLookupTokens(item, resolutions, unresolved));
+    return value;
+}
 /**
  * `inputMetadata.multipart.bodyFieldName` names the CONTAINER part — the one the
  * runtime composes from `bodyParameters`. Measured on the designer's own nodes in