@uipath/maestro-builder-sdk 6.4.0 → 6.5.1

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

@@ -0,0 +1,199 @@
+import { Refusal } from "../errors.js";
+import type { UipClient } from "../uip/client.js";
+/**
+ * A scan has to stop somewhere, and the caps must be set against the MEASURED
+ * page size rather than a guess. Integration Service serves **1,000 records
+ * per page** for a curated collection (verified against a live Slack
+ * connection: `curated_channels` returns 1000 with `HasMore: "true"`).
+ *
+ * The first version of this capped at 400 records — a number chosen for how
+ * many rows a person might scroll, which is the wrong unit entirely. It meant
+ * the loop broke partway through page ONE and never paginated at all. The eval
+ * task built to exercise this puts its target channel on page 3 (record
+ * ~2,001), so the resolver reported "not found" for a channel that is plainly
+ * there.
+ *
+ * 25 pages is ~30s of requests in the worst case, spent once, in an explicit
+ * command whose whole job is this. A collection with a `filterPattern` never
+ * reaches the scan at all.
+ */
+export declare const PAGE_SIZE_HINT = 1000;
+export declare const MAX_SCANNED: number;
+export declare const PAGE_GUARD = 50;
+/** A lookup that could not be resolved, with the reason a human needs (`_resolve.ResolutionError`). */
+export declare class ResolutionRefusal extends Refusal {
+    constructor(message: string, code: string);
+}
+/** What {@link LookupExhausted} knows about the scan that found nothing. */
+export interface LookupExhaustedFacts {
+    field: string;
+    collection: string;
+    by: string;
+    value: string;
+    /** Records seen across every page fetched. */
+    scanned: number;
+    /** Pages FETCHED (not transitions): the count the message prints. */
+    pages: number;
+    /** True when a cap, not the collection's end, stopped the scan. */
+    capped: boolean;
+}
+/**
+ * The collection was read to the end on THIS connection and had no match
+ * (`_resolve.LookupExhausted`).
+ *
+ * Split out from its parent because the two failures want opposite responses
+ * and the caller cannot tell them apart from a message. A transport or
+ * permission failure says nothing about whether the value exists — retrying it
+ * on another connection would hide a broken call behind a confident "no
+ * connection has it". An exhaustive miss is positive evidence about this
+ * connection specifically, and is the signal `prepare` uses to demote it and
+ * try the next candidate (flow-builder-sdk#744).
+ *
+ * `capped` flips that: a scan stopped at the record cap did NOT reach the end,
+ * so it is not evidence of absence and must not demote anything.
+ *
+ * The attributes carry the counts so a caller can report per-candidate results
+ * without re-parsing the sentence.
+ */
+export declare class LookupExhausted extends ResolutionRefusal {
+    readonly field: string;
+    readonly collection: string;
+    readonly by: string;
+    readonly value: string;
+    readonly scanned: number;
+    readonly pages: number;
+    readonly capped: boolean;
+    constructor(message: string, facts: LookupExhaustedFacts);
+}
+/** One `--resolve <field>:<by>=<value>`, parsed. */
+export type ResolveRequest = readonly [field: string, by: string, value: string];
+/**
+ * What a lookup spec must say for `resolveOne`: the same fields a library
+ * `reference` and a `LookupSpecData` carry, read loosely.
+ */
+export interface ResolveSpec {
+    path?: string;
+    by?: readonly string[];
+    value?: string;
+    filterPattern?: string;
+    dependsOn?: readonly string[];
+    [key: string]: unknown;
+}
+/**
+ * `channel:profile.email=dustin@example.com` -> `[field, by, value]`.
+ *
+ * Split on the FIRST colon and the FIRST `=`. Both halves can legitimately
+ * contain the other delimiter — `by` is a dotted path and a value can be
+ * anything a person typed — so a greedy split silently mis-parses real input.
+ */
+export declare function parseResolveFlag(raw: string): ResolveRequest;
+type SpecTable = ReadonlyMap<string, ResolveSpec> | Readonly<Record<string, ResolveSpec>>;
+/**
+ * Order the requests so a `dependsOn` prerequisite resolves first.
+ *
+ * 27 fields in the shipped library are not addressable until another field is
+ * known — Jira's issue type needs the project, Amazon Connect's phone number
+ * needs the instance. Resolving in the order the flags were typed leaves an
+ * 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.
+ */
+export declare function orderResolutions(requested: readonly ResolveRequest[], specs: SpecTable): ResolveRequest[];
+/**
+ * The records out of a `uip is resources run list` reply.
+ *
+ * The reply is `{"Result": "Success", "Code": ..., "Data": {"items": [...],
+ * "Pagination": {...}}}` — records live under `Data`, and `Result` is the
+ * STATUS STRING, not a container. Reading a top-level `items` finds nothing
+ * and reports "scanned 0 records" against a collection that is full, which is
+ * exactly what this did until an eval run walked it into the real CLI.
+ */
+export declare function envelopeItems(payload: unknown): unknown[];
+/** The `Pagination` block, from under `Data`. */
+export declare function envelopePagination(payload: unknown): Record<string, unknown>;
+/**
+ * `HasMore` arrives as the STRING "false" as often as the boolean.
+ *
+ * `if payload["Pagination"]["HasMore"]` on the string "false" is True, which
+ * pages forever on a collection that just said it has no more.
+ */
+export declare function truthy(value: unknown): boolean;
+/**
+ * The reviver that makes `JSON.parse` read a number the way `json.loads` did.
+ *
+ * Python kept every number as its text spelled it — `1.0` stayed a float,
+ * whose `str()` is `"1.0"`, and an integer stayed exact however many digits it
+ * had — so `str(got)` lost nothing on the way into `resolutions.json`.
+ * `JSON.parse` folds both cases: `1.0` parses to the integer `1`, and an
+ * integer above 2^53 is rounded to the nearest double, and the rounded number
+ * is what would have been recorded as the id. The reviver's third argument
+ * (`JSON.parse` source text access, present in every Node the package
+ * supports — `engines` says >= 22.6) is the spelling itself, so the two lossy
+ * cases are rewritten here as the string Python's `str()` would have produced.
+ * {@link matchRecord} and the recorded id only ever see that string, so
+ * nothing downstream can tell the difference — except that it is now right,
+ * and a typed `--resolve x:count=1.0` matches a JSON `1.0` as it did in Python.
+ */
+export declare function reviveLikeJsonLoads(_key: string, value: unknown, context?: {
+    source?: string;
+}): unknown;
+/**
+ * The first JSON document in a listing's stdout, with its record values parsed
+ * as `json.loads` would have read them, or `undefined`.
+ */
+export declare function parseListingDocument(text: string): unknown;
+/**
+ * One `uip is resources run list` page, as the parsed envelope.
+ *
+ * `uip` prints a self-update failure to stderr before its real output, so
+ * stderr being non-empty is not evidence of anything. Judge the exit code and
+ * the payload.
+ */
+export declare function listPage(client: UipClient, connectorKey: string, collection: string, connectionId: string, query: string | undefined): Promise<Record<string, unknown>>;
+/** `profile.email` out of a record, or `null` (Python's `None`) when any step is missing. */
+export declare function readPath(record: unknown, dotted: string): unknown;
+type Resolved = ReadonlyMap<string, string> | Readonly<Record<string, string>>;
+/** Fill `{fields.project.key}` placeholders from already-resolved fields, in their order. */
+export declare function substitute(template: string, resolved: Resolved): string;
+/**
+ * True when the record's `by` path, coerced with `str()`, equals `value`.
+ *
+ * The coercion is the Python's: a boolean reads `True`, a missing path `None`,
+ * a nested object its `repr`. It is what lets `--resolve x:active=True` match a
+ * JSON `true`, and it is kept exactly.
+ */
+export declare function matchRecord(record: unknown, by: string, value: string): boolean;
+/** Where a scan stopped, for the refusal that reports it. */
+export interface ScanOutcome {
+    /** Records seen across every page fetched. */
+    scanned: number;
+    /** Page TRANSITIONS made: the number of pages fetched minus one. */
+    pages: number;
+    /** True when a cap, not the collection's end, stopped the scan. */
+    capped: boolean;
+}
+/**
+ * Page through a collection, yielding each page's records and returning where
+ * the scan stopped.
+ *
+ * Pages with exactly `nextPage=<token>` appended to the query. Guessing `page`
+ * / `pageToken` / `nextPageToken` is a documented way to loop forever on page
+ * one. Stops when the reply says there is no more, when it carries no token,
+ * at {@link MAX_SCANNED} records, or after {@link PAGE_GUARD} transitions.
+ */
+export declare function scanCollection(client: UipClient, connectorKey: string, collection: string, connectionId: string, query: string | undefined): AsyncGenerator<unknown[], ScanOutcome, void>;
+/**
+ * The connector-facing id for one lookup, or throw {@link ResolutionRefusal}.
+ *
+ * `resolved` carries the values of fields resolved earlier in this run, which
+ * is what makes a `dependsOn` path addressable. Parameters follow the Python
+ * `resolve_one(connector_key, spec, field, by, value, connection_id, resolved)`
+ * with the client in front.
+ *
+ * A collection read to its end with no match throws {@link LookupExhausted},
+ * the subclass the caller's retry keys on; every other failure is the parent.
+ */
+export declare function resolveOne(client: UipClient, connectorKey: string, spec: ResolveSpec, field: string, by: string, value: string, connectionId: string, resolved?: Resolved): Promise<string>;
+export {};

package/dist/registry/prepare/resolve.js

@@ -0,0 +1,470 @@
+/**
+ * Resolve a connector lookup field against a live connection.
+ *
+ * `prepare --resolve channel:profile.email=dustin@example.com` turns a
+ * human-meaningful value into the opaque id the connector wants, and records
+ * the answer so `compile` can read it offline. This module is the retrieval
+ * half.
+ *
+ * WHY IT LIVES HERE AND NOT IN COMPILE. Resolution needs the network; compile
+ * must not have it. The eval harness runs `check` and `compile` with no `uip`
+ * login, and the byte-lock gates require that the same source produces the
+ * same bytes — a compile that made live calls would make those gates depend on
+ * tenant state and they would stop meaning anything.
+ *
+ * THE STRATEGY IS DATA, NOT CODE. The spec says how to retrieve the collection:
+ * a `filterPattern` means one request; its absence means paging; `dependsOn`
+ * means another field must resolve first.
+ *
+ * Ported from `integrations/scripts/_resolve.py`; the refusal text is verbatim.
+ */
+import { pyFloatRepr } from "../codecs/pyjson.js";
+import { pyStrip, pyStripChars, splitOnce } from "../compat/pystr.js";
+import { Refusal } from "../errors.js";
+import { isResourcesRunList } from "../uip/commands.js";
+import { isPlainObject, notJsonReason, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
+/**
+ * A scan has to stop somewhere, and the caps must be set against the MEASURED
+ * page size rather than a guess. Integration Service serves **1,000 records
+ * per page** for a curated collection (verified against a live Slack
+ * connection: `curated_channels` returns 1000 with `HasMore: "true"`).
+ *
+ * The first version of this capped at 400 records — a number chosen for how
+ * many rows a person might scroll, which is the wrong unit entirely. It meant
+ * the loop broke partway through page ONE and never paginated at all. The eval
+ * task built to exercise this puts its target channel on page 3 (record
+ * ~2,001), so the resolver reported "not found" for a channel that is plainly
+ * there.
+ *
+ * 25 pages is ~30s of requests in the worst case, spent once, in an explicit
+ * command whose whole job is this. A collection with a `filterPattern` never
+ * reaches the scan at all.
+ */
+export const PAGE_SIZE_HINT = 1000;
+export const MAX_SCANNED = 25 * PAGE_SIZE_HINT;
+export const PAGE_GUARD = 50;
+/** A lookup that could not be resolved, with the reason a human needs (`_resolve.ResolutionError`). */
+export class ResolutionRefusal extends Refusal {
+    constructor(message, code) {
+        super(message, code);
+        this.name = "ResolutionRefusal";
+    }
+}
+/**
+ * The collection was read to the end on THIS connection and had no match
+ * (`_resolve.LookupExhausted`).
+ *
+ * Split out from its parent because the two failures want opposite responses
+ * and the caller cannot tell them apart from a message. A transport or
+ * permission failure says nothing about whether the value exists — retrying it
+ * on another connection would hide a broken call behind a confident "no
+ * connection has it". An exhaustive miss is positive evidence about this
+ * connection specifically, and is the signal `prepare` uses to demote it and
+ * try the next candidate (flow-builder-sdk#744).
+ *
+ * `capped` flips that: a scan stopped at the record cap did NOT reach the end,
+ * so it is not evidence of absence and must not demote anything.
+ *
+ * The attributes carry the counts so a caller can report per-candidate results
+ * without re-parsing the sentence.
+ */
+export class LookupExhausted extends ResolutionRefusal {
+    field;
+    collection;
+    by;
+    value;
+    scanned;
+    pages;
+    capped;
+    constructor(message, facts) {
+        super(message, "RESOLVE_NO_MATCH");
+        this.name = "LookupExhausted";
+        this.field = facts.field;
+        this.collection = facts.collection;
+        this.by = facts.by;
+        this.value = facts.value;
+        this.scanned = facts.scanned;
+        this.pages = facts.pages;
+        this.capped = facts.capped;
+    }
+}
+/**
+ * `channel:profile.email=dustin@example.com` -> `[field, by, value]`.
+ *
+ * Split on the FIRST colon and the FIRST `=`. Both halves can legitimately
+ * contain the other delimiter — `by` is a dotted path and a value can be
+ * anything a person typed — so a greedy split silently mis-parses real input.
+ */
+export function parseResolveFlag(raw) {
+    const [field, rest] = splitOnce(raw, ":");
+    if (rest === undefined || !field) {
+        throw new ResolutionRefusal(`--resolve ${pyRepr(raw)}: expected <field>:<by>=<value>, ` +
+            "e.g. --resolve channel:profile.email=someone@example.com", "RESOLVE_BAD_FLAG");
+    }
+    const [by, value] = splitOnce(rest, "=");
+    if (value === undefined || !by) {
+        throw new ResolutionRefusal(`--resolve ${pyRepr(raw)}: expected <field>:<by>=<value>, ` +
+            `but found no '=' after the search field ${pyRepr(by || rest)}.`, "RESOLVE_BAD_FLAG");
+    }
+    return [field, by, value];
+}
+function specOf(specs, field) {
+    if (specs instanceof Map)
+        return specs.get(field);
+    const table = specs;
+    return Object.prototype.hasOwnProperty.call(table, field) ? table[field] : undefined;
+}
+/**
+ * Order the requests so a `dependsOn` prerequisite resolves first.
+ *
+ * 27 fields in the shipped library are not addressable until another field is
+ * known — Jira's issue type needs the project, Amazon Connect's phone number
+ * needs the instance. Resolving in the order the flags were typed leaves an
+ * 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.
+ */
+export function orderResolutions(requested, specs) {
+    const byField = new Map();
+    for (const request of requested)
+        byField.set(request[0], request);
+    const ordered = [];
+    const placed = new Set();
+    const place = (field, trail) => {
+        if (placed.has(field))
+            return;
+        if (trail.includes(field)) {
+            const cycle = [...trail, field].join(" -> ");
+            throw new ResolutionRefusal(`circular dependsOn among lookup fields: ${cycle}`, "RESOLVE_CYCLE");
+        }
+        const dependsOn = specOf(specs, field)?.dependsOn;
+        for (const prerequisite of Array.isArray(dependsOn) ? dependsOn : []) {
+            if (byField.has(prerequisite)) {
+                place(prerequisite, [...trail, field]);
+            }
+            else {
+                throw new ResolutionRefusal(`cannot resolve ${pyRepr(field)}: its collection is addressed through ` +
+                    `${pyRepr(prerequisite)}, which has no --resolve of its own. Add ` +
+                    `--resolve ${prerequisite}:<by>=<value> and re-run.`, "RESOLVE_MISSING_PREREQUISITE");
+            }
+        }
+        placed.add(field);
+        ordered.push(byField.get(field));
+    };
+    for (const [field] of requested)
+        place(field, []);
+    return ordered;
+}
+/**
+ * The records out of a `uip is resources run list` reply.
+ *
+ * The reply is `{"Result": "Success", "Code": ..., "Data": {"items": [...],
+ * "Pagination": {...}}}` — records live under `Data`, and `Result` is the
+ * STATUS STRING, not a container. Reading a top-level `items` finds nothing
+ * and reports "scanned 0 records" against a collection that is full, which is
+ * exactly what this did until an eval run walked it into the real CLI.
+ */
+export function envelopeItems(payload) {
+    if (!isPlainObject(payload))
+        return [];
+    const data = payload.Data;
+    if (isPlainObject(data) && Array.isArray(data.items))
+        return data.items;
+    if (Array.isArray(payload.items))
+        return payload.items;
+    return [];
+}
+/** The `Pagination` block, from under `Data`. */
+export function envelopePagination(payload) {
+    if (!isPlainObject(payload))
+        return {};
+    const data = payload.Data;
+    if (isPlainObject(data) && isPlainObject(data.Pagination))
+        return data.Pagination;
+    if (isPlainObject(payload.Pagination))
+        return payload.Pagination;
+    return {};
+}
+/**
+ * `HasMore` arrives as the STRING "false" as often as the boolean.
+ *
+ * `if payload["Pagination"]["HasMore"]` on the string "false" is True, which
+ * pages forever on a collection that just said it has no more.
+ */
+export function truthy(value) {
+    if (typeof value === "string") {
+        const lowered = pyStrip(value).toLowerCase();
+        return lowered === "true" || lowered === "1" || lowered === "yes";
+    }
+    return pyTruthy(value);
+}
+/**
+ * The reviver that makes `JSON.parse` read a number the way `json.loads` did.
+ *
+ * Python kept every number as its text spelled it — `1.0` stayed a float,
+ * whose `str()` is `"1.0"`, and an integer stayed exact however many digits it
+ * had — so `str(got)` lost nothing on the way into `resolutions.json`.
+ * `JSON.parse` folds both cases: `1.0` parses to the integer `1`, and an
+ * integer above 2^53 is rounded to the nearest double, and the rounded number
+ * is what would have been recorded as the id. The reviver's third argument
+ * (`JSON.parse` source text access, present in every Node the package
+ * supports — `engines` says >= 22.6) is the spelling itself, so the two lossy
+ * cases are rewritten here as the string Python's `str()` would have produced.
+ * {@link matchRecord} and the recorded id only ever see that string, so
+ * nothing downstream can tell the difference — except that it is now right,
+ * and a typed `--resolve x:count=1.0` matches a JSON `1.0` as it did in Python.
+ */
+export function reviveLikeJsonLoads(_key, value, context) {
+    if (typeof value !== "number")
+        return value;
+    const source = context?.source;
+    if (source === undefined) {
+        // An engine without source access. The integral float is undetectable
+        // here; a rounded integer is not, and must not be written as if exact.
+        if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+            throw new ResolutionRefusal(`a record carries the integer ${String(value)}, which this JavaScript engine ` +
+                "rounded while parsing and cannot read exactly; run on Node >= 22.6.", "RESOLVE_IMPRECISE_NUMBER");
+        }
+        return value;
+    }
+    if (/[.eE]/.test(source)) {
+        // A float in Python. `pyStr` already renders a non-integral double as
+        // Python's repr; only an integral one loses its `.0` (or exponent form).
+        return Number.isInteger(value) ? pyFloatRepr(value) : value;
+    }
+    // An int in Python: exact whatever its length, and `-0` is plain `0`.
+    if (Object.is(value, -0))
+        return "0";
+    return Number.isSafeInteger(value) ? value : source;
+}
+/**
+ * The first JSON document in a listing's stdout, or `undefined`.
+ *
+ * The same search `uip/envelope.ts`'s `findJsonDocument` makes — the whole
+ * text first, then every line that begins with a bracket, since the banner the
+ * CLI prints ahead of its payload never starts a line with one. Repeated here
+ * because that module has no hook for a reviver and only the resolver needs
+ * one: nowhere else does a JSON number become an id that is written down.
+ */
+function findJsonDocument(text, reviver) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return undefined;
+    try {
+        return JSON.parse(trimmed, reviver);
+    }
+    catch (error) {
+        if (error instanceof ResolutionRefusal)
+            throw error;
+        // fall through to the line scan
+    }
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const head = lines[i].trimStart();
+        if (!head.startsWith("{") && !head.startsWith("["))
+            continue;
+        try {
+            return JSON.parse(lines.slice(i).join("\n"), reviver);
+        }
+        catch (error) {
+            if (error instanceof ResolutionRefusal)
+                throw error;
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * The plainly parsed envelope with only its RECORD values revived.
+ *
+ * {@link reviveLikeJsonLoads} is about ids: a record value that a flow will
+ * send back to the provider has to keep the spelling Python's `str()` gave it.
+ * The envelope AROUND the records is control data the code reads itself, and
+ * rewriting a number there changes behaviour rather than preserving it —
+ * `HasMore: 1.0` became the string `"1.0"`, which {@link truthy} reads as
+ * false, so paging stopped on a collection that had just said it has more.
+ * (Only that spelling flips: `true`, `1`, `false`, `"false"` and `0` all
+ * survive the reviver unchanged, which is why it went unnoticed.)
+ *
+ * So the records come from the revived parse and everything else from a plain
+ * one. A second `JSON.parse` of a page of listing output is cheap next to the
+ * `uip` call that produced it. A document that is not an envelope has no
+ * control fields to protect and stays fully revived.
+ */
+function recordsRevived(plain, revived) {
+    if (!isPlainObject(plain) || !isPlainObject(revived))
+        return revived;
+    const data = plain.Data;
+    const revivedData = revived.Data;
+    if (isPlainObject(data) && Array.isArray(data.items) && isPlainObject(revivedData) && Array.isArray(revivedData.items)) {
+        return { ...plain, Data: { ...data, items: revivedData.items } };
+    }
+    // The flat shape {@link envelopeItems} falls back to.
+    if (Array.isArray(plain.items) && Array.isArray(revived.items))
+        return { ...plain, items: revived.items };
+    return plain;
+}
+/**
+ * The first JSON document in a listing's stdout, with its record values parsed
+ * as `json.loads` would have read them, or `undefined`.
+ */
+export function parseListingDocument(text) {
+    const revived = findJsonDocument(text, reviveLikeJsonLoads);
+    if (revived === undefined)
+        return undefined;
+    const plain = findJsonDocument(text);
+    return plain === undefined ? revived : recordsRevived(plain, revived);
+}
+/**
+ * One `uip is resources run list` page, as the parsed envelope.
+ *
+ * `uip` prints a self-update failure to stderr before its real output, so
+ * stderr being non-empty is not evidence of anything. Judge the exit code and
+ * the payload.
+ */
+export async function listPage(client, connectorKey, collection, connectionId, query) {
+    const result = await client.run(isResourcesRunList(connectorKey, collection, connectionId, query));
+    if (result.code !== 0) {
+        throw new ResolutionRefusal(`listing ${collection} failed: ${pyStrip(result.stderr) || "no output"}`, "RESOLVE_LISTING_FAILED");
+    }
+    const envelope = parseListingDocument(result.stdout);
+    if (!isPlainObject(envelope)) {
+        throw new ResolutionRefusal(`listing ${collection} returned output that is not JSON: ${notJsonReason(result.stdout)}`, "RESOLVE_LISTING_NOT_JSON");
+    }
+    return envelope;
+}
+/** `profile.email` out of a record, or `null` (Python's `None`) when any step is missing. */
+export function readPath(record, dotted) {
+    let cursor = record;
+    for (const part of dotted.split(".")) {
+        if (!isPlainObject(cursor))
+            return null;
+        cursor = Object.prototype.hasOwnProperty.call(cursor, part) ? (cursor[part] ?? null) : null;
+    }
+    return cursor;
+}
+function resolvedEntries(resolved) {
+    return resolved instanceof Map ? [...resolved.entries()] : Object.entries(resolved);
+}
+/** Fill `{fields.project.key}` placeholders from already-resolved fields, in their order. */
+export function substitute(template, resolved) {
+    let out = template;
+    for (const [field, value] of resolvedEntries(resolved)) {
+        out = out.replaceAll(`{${field}}`, pyStrAny(value));
+    }
+    return out;
+}
+/**
+ * True when the record's `by` path, coerced with `str()`, equals `value`.
+ *
+ * The coercion is the Python's: a boolean reads `True`, a missing path `None`,
+ * a nested object its `repr`. It is what lets `--resolve x:active=True` match a
+ * JSON `true`, and it is kept exactly.
+ */
+export function matchRecord(record, by, value) {
+    return pyStrAny(readPath(record, by)) === value;
+}
+/**
+ * Page through a collection, yielding each page's records and returning where
+ * the scan stopped.
+ *
+ * Pages with exactly `nextPage=<token>` appended to the query. Guessing `page`
+ * / `pageToken` / `nextPageToken` is a documented way to loop forever on page
+ * one. Stops when the reply says there is no more, when it carries no token,
+ * at {@link MAX_SCANNED} records, or after {@link PAGE_GUARD} transitions.
+ */
+export async function* scanCollection(client, connectorKey, collection, connectionId, query) {
+    let scanned = 0;
+    let pages = 0;
+    for (;;) {
+        const payload = await listPage(client, connectorKey, collection, connectionId, query);
+        const items = envelopeItems(payload);
+        scanned += items.length;
+        yield items;
+        const pagination = envelopePagination(payload);
+        const token = pagination.NextPageToken;
+        if (!truthy(pagination.HasMore) || !pyTruthy(token) || scanned >= MAX_SCANNED)
+            break;
+        pages += 1;
+        if (pages > PAGE_GUARD)
+            break;
+        // Exactly `nextPage`. Guessing `page` / `pageToken` / `nextPageToken`
+        // is a documented way to loop forever on page one.
+        query = query ? `${query}&nextPage=${pyStrAny(token)}` : `nextPage=${pyStrAny(token)}`;
+    }
+    return { scanned, pages, capped: scanned >= MAX_SCANNED || pages > PAGE_GUARD };
+}
+/**
+ * The connector-facing id for one lookup, or throw {@link ResolutionRefusal}.
+ *
+ * `resolved` carries the values of fields resolved earlier in this run, which
+ * is what makes a `dependsOn` path addressable. Parameters follow the Python
+ * `resolve_one(connector_key, spec, field, by, value, connection_id, resolved)`
+ * with the client in front.
+ *
+ * A collection read to its end with no match throws {@link LookupExhausted},
+ * the subclass the caller's retry keys on; every other failure is the parent.
+ */
+export async function resolveOne(client, connectorKey, spec, field, by, value, connectionId, resolved = new Map()) {
+    const searchableBy = Array.isArray(spec.by) ? spec.by : [];
+    if (!searchableBy.includes(by)) {
+        const searchable = searchableBy.map(pyRepr).join(", ");
+        throw new ResolutionRefusal(`${field}: cannot search by ${pyRepr(by)}. Searchable by ${searchable || "(nothing declared)"}.`, "RESOLVE_BAD_BY");
+    }
+    const path = substitute(pyStrAny(pyOr(spec.path, "")), resolved);
+    if (path.includes("{")) {
+        const open = path.indexOf("{");
+        const close = path.indexOf("}");
+        const missing = close >= 0 ? path.slice(open + 1, close) : "?";
+        throw new ResolutionRefusal(`${field}: the collection path still contains {${missing}}. ` +
+            `Resolve ${pyRepr(missing)} first with --resolve ${missing}:<by>=<value>.`, "RESOLVE_UNSUBSTITUTED");
+    }
+    const [beforeQuery, afterQuery] = splitOnce(path, "?");
+    const collection = pyStripChars(beforeQuery, "/");
+    let query = afterQuery || undefined;
+    const send = pyStrAny(pyOr(spec.value, "id"));
+    // A server-side filter turns the whole scan into one request. Where the
+    // metadata declares one, use it; where it does not, page.
+    const filterPattern = spec.filterPattern;
+    if (pyTruthy(filterPattern)) {
+        const filtered = pyStrAny(filterPattern).replaceAll("{filter}", value);
+        query = query ? `${query}&${filtered}` : filtered;
+    }
+    const scan = scanCollection(client, connectorKey, collection, connectionId, query);
+    let step = await scan.next();
+    while (!step.done) {
+        for (const record of step.value) {
+            if (matchRecord(record, by, value)) {
+                const got = readPath(record, send);
+                if (got === null) {
+                    throw new ResolutionRefusal(`${field}: matched a record on ${by}=${pyRepr(value)}, but it ` +
+                        `carries no ${pyRepr(send)} to send.`, "RESOLVE_NO_VALUE");
+                }
+                return pyStrAny(got);
+            }
+        }
+        step = await scan.next();
+    }
+    const { scanned, pages, capped } = step.value;
+    // This states the FACT and stops; `prepare` owns the remedy, because
+    // `prepare` is what knows the other candidate connections.
+    //
+    // It deliberately carries NO "check the value" and NO `uip is resources`
+    // pointer. The old text led with both: it named only the value as suspect
+    // when the connection is equally suspect, and then sent the reader to a
+    // tenant crawl the skill explicitly rules out ("Tenant discovery is not a
+    // phase of either loop", references/CLI-LOOP.md). An agent followed that
+    // advice into exactly what it had been told not to do — 50 of 94 Bash calls
+    // hand-crawling Integration Service, 41 of them paging this collection, and
+    // the run hit its ceiling without producing a flow (flow-builder-sdk#744).
+    //
+    // 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.
+    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 });
+}