@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/registry/prepare/messages.js

@@ -0,0 +1,472 @@
+/**
+ * Every line `prepare_connector.py` printed, as functions that RETURN the text.
+ *
+ * The messages are the product. An agent reads "prepare-connector: …" and does
+ * what it says, so each string here is kept verbatim from the Python — the
+ * same words, the same arrows, the same `…` — and the only thing that changed
+ * is that nothing in this module writes to a stream. The orchestration decides
+ * where a line goes (stdout for progress, stderr for `WARN:` and `note:`), and a
+ * test asserts on the text without capturing anything.
+ *
+ * Two conventions the Python had are made explicit:
+ *
+ *   - `sys.exit("prepare-connector: …")` texts carry their prefix INSIDE the
+ *     string, while a helper's exception was prefixed at the exit site
+ *     (`sys.exit(f"prepare-connector: {error}")`). {@link PrepareRefusal} is a
+ *     refusal whose message is already the full text; {@link exitText} spells
+ *     both kinds the way the terminal saw them.
+ *   - the pasteable `npx flow-sdk registry prepare` spelling is a parameter with
+ *     the Python's literal as its default, so a caller driven from `uip` can
+ *     spell the command for the binary in the reader's hand (see
+ *     `core/cli-spelling.ts`) without this module reading the environment.
+ */
+import { Refusal, messageOf } from "../errors.js";
+import { closestActions } from "./actions.js";
+import { pyGet, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
+export const PREFIX = "prepare-connector: ";
+/** The spelling the Python hard-coded into every pasteable re-run. */
+export const PREPARE_COMMAND = "npx flow-sdk registry prepare";
+/** `prepare-connector: <text>`. */
+export function prefixed(text) {
+    return `${PREFIX}${text}`;
+}
+/** `prepare-connector: next: <text>` — the last lines of a run, each one a call the reader can paste. */
+export function nextLine(text) {
+    return prefixed(`next: ${text}`);
+}
+/**
+ * A refusal whose message is the COMPLETE text the Python passed to
+ * `sys.exit`, prefix included. Every other {@link Refusal} reaching the exit
+ * boundary is a helper's and gets the prefix there, as the Python's
+ * `sys.exit(f"prepare-connector: {error}")` did.
+ */
+export class PrepareRefusal extends Refusal {
+    constructor(message, code) {
+        super(message, code);
+        this.name = "PrepareRefusal";
+    }
+}
+/** What the terminal showed for a thrown value: the Python's `sys.exit` text. */
+export function exitText(error) {
+    if (error instanceof PrepareRefusal)
+        return error.message;
+    return prefixed(messageOf(error));
+}
+// ---------------------------------------------------------------------------
+// Stage 0: the connection and bindings.json
+/** `  connection: <Name> (<id>)` — `found.get('Name')` renders `None` when the row has none, as Python did. */
+export function connectionLine(row, connectionId) {
+    return `  connection: ${pyStrAny(pyGet(row, "Name", null))} (${connectionId})`;
+}
+/** `  bindings: <symbolic name> -> <bindings.json>`, once per row this run changed. */
+export function bindingsLine(symbolicName, bindingsPath) {
+    return `  bindings: ${symbolicName} -> ${bindingsPath}`;
+}
+// ---------------------------------------------------------------------------
+// Refusals of the action path
+/** `_missing_generic_schema_message`: a Generic action that expanded to nothing. */
+export function missingGenericSchemaMessage(operation, objectName) {
+    const target = objectName
+        ? `object "${objectName}" was not found or does not support action "${operation}"`
+        : `no object in the connected catalog supports action "${operation}"`;
+    return (`${PREFIX}${target}. A connection-resolved schema requires a ` +
+        "working live connection id. For an offline/validate-only flow that does " +
+        "not need connection-specific fields, use the baked connector descriptor " +
+        "without custom fields instead.");
+}
+/**
+ * `_unresolved_action_message`: what to do when the action id is not a
+ * registry key. `actions` is what `registry search <key>` served (see
+ * `actions.ts`); the message is pure over it.
+ *
+ * NOT auto-substituted, deliberately: the baked action id and the registry key
+ * are different namespaces, and guessing between them would emit a node both
+ * offline validators accept and the runtime dispatches to the wrong operation.
+ */
+export function unresolvedActionMessage(connectorKey, action, nodeType, actions) {
+    const lines = [
+        `${PREFIX}\`registry get ${nodeType}\` found no such node.`,
+        "",
+        "The baked library's action id is not always the registry's key — a Generic",
+        "op is `list-all-records` in the library and materializes per object, while",
+        "the registry serves the un-expanded form. Re-run with a registry action id.",
+    ];
+    if (actions.length === 0) {
+        lines.push("", `\`registry search ${connectorKey}\` returned nothing. If the catalog looks`, "stale, refresh it first: `uip maestro flow registry pull --force`.");
+        return lines.join("\n");
+    }
+    const close = closestActions(action, actions);
+    if (close.length > 0)
+        lines.push("", `Closest to "${action}": ${close.slice(0, 3).join(", ")}`);
+    lines.push("", `All actions the registry serves for ${connectorKey}:`, ...actions.map((a) => `  ${a}`));
+    return lines.join("\n");
+}
+export function noCanonicalEntryMessage(nodeType) {
+    return `${PREFIX}no canonical entry for ${nodeType} (unexpected registry shape).`;
+}
+/** The `-f` names do not match any api-type ObjectAction; `specs` are the actions' parent lists. */
+export function parentFieldNamesMismatchMessage(given, specs) {
+    const expected = specs.map(([, fields]) => fields.join(", ")).join(" or ") || "<none advertised>";
+    return (`${PREFIX}parent-field names must match one api-type ObjectAction exactly. Given: ` +
+        `${given.join(", ")}. Expected: ${expected}.`);
+}
+export function genericActionNeedsObjectMessage() {
+    return (`${PREFIX}this is a Generic action; pass --object <name> to prepare one object or --all-objects ` +
+        "to prepare the full connected catalog.");
+}
+export function objectFlagsOnlyForGenericMessage() {
+    return `${PREFIX}--object/--all-objects apply only to Generic connector actions.`;
+}
+/** `_parse_fields`'s refusal of a `-f` without `=`. */
+export function fieldFlagMessage(pair) {
+    return `${PREFIX}--field expects NAME=VALUE, got ${pyRepr(pair)}.`;
+}
+/**
+ * `_rejected_parent_fields_message`: the CLI's own rejection is the actionable
+ * half and the pipeline otherwise swallows it, so quote the service.
+ * `failures` are `(connector, object, operation, message)` tuples; the first
+ * non-empty message is the one quoted.
+ */
+export function rejectedParentFieldsMessage(pairs, failures = []) {
+    const given = pairs.join(", ");
+    let detail = "";
+    for (const failure of failures) {
+        const message = failure[failure.length - 1];
+        if (pyTruthy(message)) {
+            detail = ` The service said: ${pyStrAny(message)}`;
+            break;
+        }
+    }
+    return (`${PREFIX}the parent-field set was rejected: ${given}.${detail} ` +
+        "Re-run with NO -f to list the parent fields this operation declares, " +
+        "resolve a value for EVERY one of them, then pass them all together. " +
+        "Values are connection- and parent-scoped (a Jira issue-type id is valid " +
+        "only inside its project), so they cannot be copied from another " +
+        "project, connection, or task.");
+}
+// ---------------------------------------------------------------------------
+// The object decision
+/** `  object: <note>` — the ladder's normalization sentence. */
+export function objectNoteLine(note) {
+    return `  object: ${note}`;
+}
+/** `  object: <requested> -> <matched> recorded in <ledger>`. */
+export function objectRecordedLine(requested, matched, ledgerPath) {
+    return `  object: ${requested} -> ${matched} recorded in ${ledgerPath}`;
+}
+// ---------------------------------------------------------------------------
+// The summary and its notes
+/** `_input_field_note`: `N input field(s)`, or the unavailable marker when the count could not be read. */
+export function inputFieldNote(count) {
+    return count !== undefined && count !== null ? `${count} input field(s)` : "input fields: <unavailable>";
+}
+/** `JSON overlay only` or `overlay + <key>.ts`. */
+export function tsNote(jsonOnly, connectorKey) {
+    return jsonOnly ? "JSON overlay only" : `overlay + ${connectorKey}.ts`;
+}
+/** The action path's success line. */
+export function preparedSummaryLine(nodeType, out, ts, variants, fieldNote) {
+    return `${PREFIX}${nodeType} → ${out}/ (${ts}, ${variants} variant(s), ${fieldNote})`;
+}
+/** Why this run did not overwrite the overlay (`_keep_prepared_schema`). */
+export function keptSchemaMessage(action, kept, discarded) {
+    return (`${PREFIX}kept the prepared schema for ${action} ` +
+        `(${kept} input field(s)) — this run passed no -f, so its schema ` +
+        `action did not run and the unresolved entry (${discarded} field(s)) ` +
+        "would have replaced it. The resolutions above are recorded either " +
+        "way; re-run with -f to refresh the schema itself.");
+}
+/** The set was SHAPED right but resolved to nothing new: a VALUE is wrong for this connection. */
+export function parentOnlyMessage(parents, fieldPairs) {
+    return (`${PREFIX}the parent-field values did not resolve — the ` +
+        `prepared schema is still parent-only (${parents.join(", ")}` +
+        `). Given: ${fieldPairs.join(", ")}. The names were accepted, so a ` +
+        "VALUE is wrong for this connection: resolve each one against this " +
+        "connection (ids are parent-scoped — a Jira issue-type id is valid " +
+        "only inside its project) rather than reusing one from another " +
+        "project, connection, or task.");
+}
+function valueOf(values, name) {
+    if (values instanceof Map)
+        return values.get(name);
+    const record = values;
+    return Object.prototype.hasOwnProperty.call(record, name) ? record[name] : undefined;
+}
+/**
+ * The paste-ready re-run when every schema parent already has a recorded
+ * resolution: the ids `--resolve` just wrote ARE the `-f` values.
+ */
+export function resolvedParentsNote(connectorKey, action, actionParents, resolvedParents, command = PREPARE_COMMAND) {
+    const fieldsArg = actionParents.map((name) => `-f ${name}=${valueOf(resolvedParents, name)}`).join(" ");
+    return (`${PREFIX}note: this operation resolves its fields ` +
+        "from the VALUES of parent inputs, and the resolutions above " +
+        "ARE those values. Re-run to materialize the full field set:\n" +
+        `  ${command} ${connectorKey} ${action} ${fieldsArg}`);
+}
+/** The note when some schema parent did not arrive as `-f`, with the example re-run. */
+export function missingParentsNote(connectorKey, action, actionParents, missing, parentFields, command = PREPARE_COMMAND) {
+    const given = actionParents
+        .filter((name) => valueOf(parentFields, name) !== undefined)
+        .map((name) => `-f ${name}=${valueOf(parentFields, name)}`)
+        .join(" ");
+    const example = actionParents.map((name) => `-f ${name}=${valueOf(parentFields, name) ?? "<value>"}`).join(" ");
+    const which = missing.length === actionParents.length
+        ? "none were given"
+        : `${missing.join(", ")} ${missing.length === 1 ? "was" : "were"} not${given ? ` (given: ${given})` : ""}`;
+    return (`${PREFIX}note: this operation resolves its fields ` +
+        `from the VALUES of ${actionParents.join(", ")}` +
+        ` (its schema action), and ${which}` +
+        ", so the overlay above carries only the unresolved schema — a " +
+        "body field the object declares is not there yet and compile " +
+        "will refuse it as an unknown input. Re-run passing ALL of them " +
+        "as -f NAME=VALUE (a partial set is rejected):\n" +
+        `  ${command} ${connectorKey} ${action} ${example}`);
+}
+/**
+ * `_print_lookup_vocabulary`: the lookup table for the operation just
+ * prepared, or no lines at all when it has no lookups. The markdown catalog
+ * renders this for BAKED schemas; a schema that only exists because `prepare`
+ * ran has no page, so the command is where the vocabulary first becomes
+ * knowable.
+ */
+export function lookupVocabularyLines(connectorKey, action, objectName, specs, command = PREPARE_COMMAND) {
+    if (specs.size === 0)
+        return [];
+    const where = objectName ? ` (${objectName})` : "";
+    const lines = [
+        `${PREFIX}lookup fields on ${action}${where} — these hold ids; author lookup(...) and resolve, don't paste one:`,
+    ];
+    const shown = [...specs.entries()].slice(0, 12);
+    for (const [field, spec] of shown) {
+        const by = (spec.by ?? []).join(" | ") || "?";
+        const target = `${pyOr(pyOr(spec.objectName, spec.path), "?")}.${pyOr(spec.value, "id")}`;
+        lines.push(`  ${field} — matches on ${by}, sends ${target}`);
+    }
+    if (specs.size > shown.length)
+        lines.push(`  … and ${specs.size - shown.length} more`);
+    const [field, spec] = shown[0];
+    const by = (pyTruthy(spec.by) ? spec.by : ["id"])[0];
+    const obj = objectName ? ` --object ${objectName}` : "";
+    lines.push(`${PREFIX}resolve with: ${command} ${connectorKey} ${action}${obj} --resolve ${field}:${by}=<value>`);
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// `--resolve`
+/** A `--resolve` names a field with no lookup; `known` are the fields that have one, sorted. */
+export function unknownLookupMessage(unknown, nodeType, known) {
+    return (`${PREFIX}no lookup is declared for ` +
+        `${unknown.map(pyRepr).join(", ")} on ${nodeType}. ` +
+        `Fields with a lookup: ${known.join(", ") || "(none)"}.`);
+}
+/** `  <field>: <by>=<value> -> <id>`, with ` (already resolved)` when the ledger answered. */
+export function resolutionLine(field, by, value, got, alreadyResolved = false) {
+    return `  ${field}: ${by}=${value} -> ${pyStrAny(got)}${alreadyResolved ? " (already resolved)" : ""}`;
+}
+export function wroteResolutionsLine(count, ledgerPath) {
+    return `  wrote ${count} resolution(s) to ${ledgerPath}`;
+}
+/**
+ * `generated N connector module(s) → <out>` — the descriptor generator's own
+ * last line (`generate_connectors_ts.py`), which `prepare` spawned between
+ * the resolution lines and its summary. `outDir` is `str(Path(args.output))`.
+ */
+export function generatedModulesLine(count, outDir) {
+    return `generated ${count} connector module(s) → ${outDir}`;
+}
+// ---------------------------------------------------------------------------
+// The retry across connections (flow-builder-sdk#744; `_retry_or_exit`)
+/** `<Name> (<Folder>)` for a per-candidate report line (`_candidate_label`). */
+export function candidateLabel(row) {
+    return `${pyStrAny(pyGet(row, "Name", null))} (${pyStrAny(pyGet(row, "Folder", null))})`;
+}
+/** `  <field>: not on this connection; trying N other <key> connection(s)`. */
+export function tryingOtherConnectionsLine(field, count, connectorKey) {
+    return `  ${field}: not on this connection; trying ${count} other ${connectorKey} connection(s)`;
+}
+/** `  connection: <label> resolves <field>; re-running against it (--connection-id <id>)`. */
+export function rerunAgainstLine(label, field, connectionId) {
+    return `  connection: ${label} resolves ${field}; re-running against it (--connection-id ${connectionId})`;
+}
+/** The terminal report's line for a candidate that resolved every requested lookup. */
+export function candidateResolvesAllLine(label, lookups) {
+    return `    ${label}  resolves all ${lookups} lookup(s)`;
+}
+/** The terminal report's line for a candidate whose collection was read to the end. */
+export function candidateExhaustedLine(label, field, scanned) {
+    return `    ${label}  ${field}: ${scanned} record(s) scanned, no match`;
+}
+/** The terminal report's line for a candidate whose lookup failed for another reason: the error, verbatim. */
+export function candidateErrorLine(label, error) {
+    return `    ${label}  ${messageOf(error)}`;
+}
+/**
+ * An explicit `--connection-id` / `--connection` is the author's decision and
+ * is not overridden. The alternatives are still named, because the whole cost
+ * of this bug was not knowing they existed. `first` is the exhausted lookup's
+ * own message; `others` the pasteable listing of the other candidates.
+ */
+export function pinnedConnectionExhaustedMessage(first, connectorKey, othersCount, othersListing) {
+    let extra = "";
+    if (othersCount > 0) {
+        extra =
+            `\n${othersCount} other enabled ${connectorKey} connection${othersCount > 1 ? "s" : ""} exist${othersCount > 1 ? "" : "s"}:\n` +
+                `${othersListing}\n` +
+                "Re-run against one of those, or check the value. This run kept the connection you named.";
+    }
+    return `${PREFIX}${first}${extra}`;
+}
+/** The listing of other connections itself failed; the original lookup failure is what the author asked about. */
+export function candidateListingFailedMessage(first, error) {
+    return `${PREFIX}${first}\n(could not list other connections: ${messageOf(error)})`;
+}
+export function onlyConnectionMessage(first, connectorKey) {
+    return (`${PREFIX}${first}\n` + `This is the only enabled ${connectorKey} connection on the tenant, so the value is what to check.`);
+}
+/** Two or more candidates resolve everything: reported, never chosen between. */
+export function severalConnectionsResolveMessage(count, connectorKey, listing) {
+    return (`${PREFIX}${count} ${connectorKey} connections resolve ` +
+        "every requested lookup, and they are not interchangeable — the ids " +
+        "they return differ per connection. Pick the one you mean:\n" +
+        listing);
+}
+/**
+ * Nothing resolved anywhere: every candidate and what it held, one per line.
+ * HERE is where the collection listing finally belongs — every connection has
+ * been tried, so seeing what the collection actually holds is the next step
+ * rather than the detour it is while a retry is still available.
+ */
+export function noConnectionResolvesMessage(connectorKey, first, lines, connectionId) {
+    return (`${PREFIX}no ${connectorKey} connection could resolve ` +
+        `${first.field}: ${first.by}=${pyRepr(first.value)}\n` +
+        `${lines.join("\n")}\n` +
+        "Every candidate was read to the end, so the value is what to check now. " +
+        `To see what ${pyRepr(first.collection)} holds:\n` +
+        `  uip is resources run list ${connectorKey} ${first.collection} ` +
+        `--connection-id ${connectionId}`);
+}
+// ---------------------------------------------------------------------------
+// The event path
+export function eventParentFieldsMessage() {
+    return `${PREFIX}-f parent fields apply to activities; a connector event has none.`;
+}
+export function eventAllObjectsMessage() {
+    return `${PREFIX}--all-objects applies to Generic activities; prepare a generic EVENT for one --object.`;
+}
+/** A Generic event fires for ONE object; name it. `rows` is the `triggers objects` catalog. */
+export function genericEventNeedsObjectMessage(action, rows) {
+    const sample = rows
+        .slice(0, 8)
+        .filter((row) => pyTruthy(pyGet(row, "Name", null)))
+        .map((row) => pyStrAny(row.Name))
+        .join(", ");
+    return (`${PREFIX}${action} is a Generic event — it ` +
+        "fires for ONE object of the connection. Pass --object " +
+        `<name>. This connection's objects include: ${sample}` +
+        (rows.length > 8 ? " …" : ""));
+}
+export function objectOnCuratedEventMessage(action, builtInObject) {
+    return `${PREFIX}--object applies to Generic events; ${action}'s object is built in (${pyOr(builtInObject, "none")}).`;
+}
+/** `  WARN: <error>` — a listing failure a curated event survives. */
+export function warnLine(error) {
+    return `  WARN: ${messageOf(error)}`;
+}
+/** The describe could not answer for a curated event; the definition's own sections stand in. */
+export function describeFallbackWarning(error, bakedObject) {
+    return (`  WARN: ${messageOf(error)}\n` + `  falling back to the registry definition's own schema sections for ${bakedObject}`);
+}
+export function byoaListingFailedMessage(connectionId, error) {
+    return (`${PREFIX}this event object requires a BYOA ` +
+        "(bring-your-own-app) connection, and the BYOA listing needed to " +
+        `check ${connectionId} against it failed: ${messageOf(error)}`);
+}
+export function byoaRequiredMessage(connectionId, connectorKey, listing) {
+    return (`${PREFIX}this event object requires a BYOA ` +
+        `(bring-your-own-app) connection, and ${connectionId} is not ` +
+        "one. A standard connection deploys and then faults at runtime with " +
+        `an unrelated-looking webhook error. BYOA ${connectorKey} connections:\n` +
+        listing);
+}
+export function eventSummaryLine(eventNodeType, out, operation, mode, whereParameters, filterFields) {
+    return (`${PREFIX}${eventNodeType} → ${out}/ (event overlay, ` +
+        `${operation}, ${mode}, ${whereParameters} where-parameter(s), ` +
+        `${filterFields} filter field(s))`);
+}
+/** The first eight filterable field names, or nothing when the event has none. */
+export function filterableFieldsLine(filterFields) {
+    if (filterFields.length === 0)
+        return undefined;
+    const names = filterFields
+        .slice(0, 8)
+        .map((f) => pyStrAny(pyGet(f, "name", null)))
+        .join(", ");
+    return `${PREFIX}filterable fields (${filterFields.length}): ${names}${filterFields.length > 8 ? " …" : ""}`;
+}
+/**
+ * The webhook note and the connector's own registration text, or nothing for a
+ * polling event. Registration is an act on the external service — the one step
+ * the loop cannot make deterministic — so the connector's words are handed over
+ * instead of leaving `uip is webhooks config` to be discovered.
+ */
+export function webhookNoteLines(mode, textBlocks) {
+    if (mode !== "webhooks")
+        return [];
+    return [
+        `${PREFIX}note: this event is WEBHOOK mode — it ` +
+            "cannot be debugged locally (deploy to test), and the webhook " +
+            "URL must be registered on the external service" +
+            (textBlocks.length > 0 ? ":" : " (retrieve it with `uip is webhooks config`)."),
+        ...textBlocks.map((block) => `  ${block}`),
+    ];
+}
+/** `{ connector: '…', event: '…'[, object: '…'], connection: '…', folder: '…' }`. */
+export function eventSubscription(connectorKey, action, objectName, connectionName, folderName) {
+    return (`{ connector: '${connectorKey}', event: '${action}'` +
+        (objectName !== undefined && objectName !== null ? `, object: '${objectName}'` : "") +
+        `, connection: '${connectionName}', folder: '${folderName}' }`);
+}
+export function eventNextLine(subscription) {
+    return (`${PREFIX}next: .trigger(onEvent(${subscription})) to ` +
+        "start the flow on this event — or .step('…', " +
+        `waitForEvent(${subscription})) to pause mid-flow for it`);
+}
+// ---------------------------------------------------------------------------
+// Repointing the source, and the descriptor handoff
+export function sourceNotAFileLine(source) {
+    return `--source ${source} does not name a file; left the import alone`;
+}
+export function severalSourcesLine(names) {
+    return `${names.length} sources import this connector (${names.join(", ")}); name one with --source to have it repointed`;
+}
+export function repointedLine(sourceRelative, specifier) {
+    return `repointed ${sourceRelative} -> ${specifier}`;
+}
+/** The two-line fallback when the module could not be read or exports several descriptors. */
+export function descriptorUsageFallbackLines(sourcePosix) {
+    return [
+        `open "${sourcePosix}" and import the descriptor for the object you need`,
+        "use that descriptor with connector(descriptor, inputs, opts); do not " +
+            "reconstruct its live operation/object identity from the baked catalog",
+    ];
+}
+/** The module has one descriptor but its inputs interface could not be parsed. */
+export function descriptorUsageUnparsedLines(sourcePosix, descriptorName) {
+    return [
+        `open "${sourcePosix}" and import ${descriptorName}`,
+        "read its generated inputs interface before calling connector; " + "the required-input skeleton is unavailable",
+    ];
+}
+/** The ready-to-paste handoff for a module with exactly one descriptor. */
+export function descriptorUsageLines(descriptorName, importPath, requiredFields, boundConnection, boundFolder) {
+    let inputs = "{}";
+    if (requiredFields.length > 0) {
+        const placeholders = requiredFields.map(([name, type]) => `${name}: /* ${type}, required */`).join(", ");
+        inputs = `{ ${placeholders} }`;
+    }
+    return [
+        `import { ${descriptorName} } from "${importPath}";`,
+        `connector(${descriptorName}, ${inputs}, { connection: "${boundConnection}", folder: "${boundFolder}" })`,
+        "use this descriptor as generated: it carries the resolved live " +
+            "operation and object identity even when the baked action id differs",
+    ];
+}

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

@@ -0,0 +1,130 @@
+import { Refusal } from "../errors.js";
+import type { LedgerObject } from "../model/library.js";
+/**
+ * Enough rows to choose from without dumping a catalog into the error. The
+ * most-selective-token fallback can legitimately produce dozens of rows; past
+ * this many the table stops being a choice and starts being the unfiltered
+ * list the ladder exists to avoid.
+ */
+export declare const MAX_CANDIDATES = 15;
+/** One row of `uip is resources list`: `Name`, `DisplayName`, `Custom`, `Operations`, … */
+export type CatalogueRow = Record<string, unknown>;
+/**
+ * No unique object for the requested name, with the candidates a human (or an
+ * agent with the prompt in hand) needs to choose (`_objects.ObjectMatchError`).
+ *
+ * `retriable` marks every outcome that fell PAST the name rungs — zero
+ * matches, and the substring refusals (unique or ambiguous). All of them can be
+ * caused by a stale `uip is resources list` cache hiding a real object:
+ * `--object User` on a catalog that lacks `User` but carries `UserAlias` would
+ * otherwise refuse with a recovery message pointing at the WRONG object, and
+ * the cache never invalidates itself. The caller refreshes the catalog once and
+ * re-runs the whole ladder before believing any of them. Ambiguity WITHIN a
+ * name rung (two objects whose names are case-variants) is not retriable — a
+ * fresh catalog has the same two names in it.
+ */
+export declare class ObjectMatchRefusal extends Refusal {
+    readonly retriable: boolean;
+    constructor(message: string, code: string, retriable?: boolean);
+}
+/** The ledger file exists but cannot be read back — refuse, don't clobber (`_objects.LedgerError`). */
+export declare class LedgerRefusal extends Refusal {
+    constructor(message: string, code: string);
+}
+/** `str(row.get("Name") or "")`. */
+export declare function objectName(row: CatalogueRow): string;
+/** `str(row.get("DisplayName") or "")`. */
+export declare function objectDisplayName(row: CatalogueRow): string;
+/**
+ * True when the row's `Operations` include `operation`. A catalog that does
+ * not report operations cannot be narrowed by one; keep the row rather than
+ * hiding it on missing data.
+ */
+export declare function supportsOperation(row: CatalogueRow, operation?: string): boolean;
+/**
+ * The table an ambiguous match prints: enough columns to choose with.
+ *
+ * `Custom: yes` is how a prompt's "custom" qualifier resolves — it is a facet
+ * column here precisely so nothing upstream has to parse it out of English.
+ */
+export declare function formatCandidates(rows: readonly CatalogueRow[]): string;
+/** The outcome of {@link matchObject}: the row, and how the given name became the API name. */
+export interface ObjectMatch {
+    row: CatalogueRow;
+    /** `undefined` on an exact match; the normalization sentence otherwise, for the caller to print. */
+    note: string | undefined;
+}
+/**
+ * The catalog row for `wanted`, or throw {@link ObjectMatchRefusal}.
+ *
+ * `operation` is the action's verb (`Create`, `Update`, …); rows that do not
+ * support it are dropped before any matching.
+ */
+export declare function matchObject(rows: readonly CatalogueRow[], wanted: string | undefined | null, operation?: string): ObjectMatch;
+export declare const RESOLUTIONS_FILENAME = "resolutions.json";
+/** `<outDir>/resolutions.json`. */
+export declare function ledgerPath(outDir: string): string;
+/**
+ * The ledger after {@link recordObject}: the sections `prepare` maintains,
+ * plus whatever else the file carried. Under `schemaVersion: "1"` the sections
+ * are additive — readers ignore keys they do not know.
+ */
+export interface RecordedLedger extends Record<string, unknown> {
+    schemaVersion: "1";
+    objects: Record<string, Record<string, LedgerObject>>;
+    resolutions: Record<string, unknown>;
+}
+/**
+ * The whole ledger at `path` as parsed, `{}` when there is no file, or throw
+ * {@link LedgerRefusal}.
+ *
+ * A file that will not parse is REFUSED rather than silently reset to `{}` —
+ * the same rule `bindings.json` follows: a corrupt-but-recoverable audit of
+ * every resolution prepare ever made is worth more than this run finishing,
+ * and overwriting it is the one way to make the corruption permanent.
+ * Parseable-but-not-an-object (a top-level array, a bare string) is corruption
+ * wearing valid JSON; sliding it past the refusal would overwrite whatever it
+ * used to be.
+ */
+export declare function readLedger(path: string): Record<string, unknown>;
+/**
+ * `json.dump(ledger, indent=2, sort_keys=True)` + newline: the bytes the
+ * ledger is written in. Keys sort by code point at every level, so the order a
+ * key was inserted in never reaches the file — which is also why integer-like
+ * keys (which `JSON.parse` hoists) are accepted here: sorting puts them where
+ * Python would have.
+ */
+export declare function formatLedger(ledger: Record<string, unknown>): string;
+/** Write the ledger at `path`, creating its directory. */
+export declare function writeLedger(path: string, ledger: Record<string, unknown>): void;
+/** The object decision `recordObject` writes, and what it was decided from. */
+export interface ObjectDecision {
+    row: CatalogueRow;
+    /** The action's verb, recorded as `operation` when present. */
+    operation?: string;
+}
+/** The `objects[nodeType][requested]` row for a decision. */
+export declare function ledgerObjectOf(decision: ObjectDecision): LedgerObject;
+/**
+ * The ledger with the match recorded under `objects[nodeType][requested]`.
+ *
+ * Pure: returns a new ledger and leaves `ledger` untouched. The row lands in a
+ * sibling `objects` section rather than in `resolutions`: an object identity is
+ * not a field lookup, and it should not wear a fake `field` key. Keys NEST
+ * rather than encode a tuple: the lookup rows' tuple-string keys exist to match
+ * a JavaScript `JSON.stringify` that reads them back, and nothing in JavaScript
+ * reads this section.
+ *
+ * Unlike lookup rows, the current match is ALWAYS written, `--refresh` or not.
+ * A lookup row stands because re-resolving costs a network call and can
+ * silently change an artifact; this row costs nothing to recompute and MUST
+ * agree with the overlay written beside it in this same run. The ledger
+ * records the DECISION only; the schema it selected lives in the overlay.
+ */
+export declare function recordObject(ledger: Record<string, unknown>, nodeType: string, requested: string, decision: ObjectDecision): RecordedLedger;
+/**
+ * Record the match in `<outDir>/resolutions.json` and return that path — the
+ * Python `record_object_resolution`: read (refusing a corrupt file before
+ * anything is created), record, write.
+ */
+export declare function recordObjectResolution(outDir: string, nodeType: string, requested: string, row: CatalogueRow, operation?: string): string;