@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/generators/prepare_connector.py

@@ -1,1860 +0,0 @@
-#!/usr/bin/env python3
-"""prepare-connector — fetch ONE connector op's FULL, connection-resolved schema
-into an ephemeral `./connectors-local/` overlay + a typed `.ts` (C4 / design §E).
-
-The baked library is tenant-agnostic, so schema-dynamic ops (Jira create-issue,
-Salesforce, …) ship only their connection-independent fields — the compiler then
-rejects the real fields (`fields.summary`, …) as unknown. `prepare-connector`
-closes that at author time: with a live connection it fetches the complete field
-schema for ONE op and writes the same artifacts the bulk generator produces, into
-a local overlay dir the compile CLIs auto-detect (`core/library.ts` overlay).
-
-    prepare_connector.py <key> <action> --connection-id <id> [--object <name>]
-                         [--all-objects] [-f NAME=VALUE ...] [--out ./connectors-local]
-
-Schema-dynamic ops resolve their fields from the VALUES of a few parent fields,
-not from the connection alone, so `-f` is what actually materializes them (Jira
-create-issue: 2 fields with no `-f`, 19 with project + issue type, a different
-22 for a different issue type). The values themselves have to be discovered
-first — that loop is the connector guide's, not this tool's.
-
-It's a single-op, connection-scoped slice of `generate_library_json.py`: it reuses
-that module's `registry_get` → `extract_canonical` → `enrich_entry` → `write_library`
-(routing all uip calls through `--connection-id` via `set_connection_id`), then
-runs `generate_connectors_ts.py` over the overlay. Calls ACCUMULATE — each prepared
-op merges into `--out` rather than replacing it.
-
-Needs a live connection + `uip`; it targets REAL/LIVE authoring (and the live eval
-rung), not the pure-offline arm. Custom (instance-specific) fields captured from
-one connection may not exist on another tenant at deploy — inherent to
-schema-dynamic connectors.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import shutil
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-
-HERE = Path(__file__).resolve().parent
-sys.path.insert(0, str(HERE))
-import generate_library_json as gen  # noqa: E402
-import generate_connectors_ts as gen_ts  # noqa: E402
-import _resolve  # noqa: E402
-import _connections  # noqa: E402
-import _events  # noqa: E402
-import _objects  # noqa: E402
-from _lookups import load_invariant_collections  # noqa: E402
-
-
-def _variant_key(entry: dict) -> tuple[str, str, str]:
-    """Identity for one resolvable activity schema variant.
-
-    Generic object variants intentionally share a nodeType, so keying only by
-    nodeType makes the last prepared object overwrite every earlier one.
-    """
-    return (
-        entry.get("nodeType", ""),
-        entry.get("version", ""),
-        entry.get("objectName", ""),
-    )
-
-
-def _descriptor_overlay_path(path: str) -> str:
-    parts = Path(path).parts
-    if parts and parts[0] == "descriptors":
-        return Path(*parts).as_posix()
-    return (Path("descriptors") / Path(*parts)).as_posix()
-
-
-def _migrate_legacy_descriptor_roots(dst: str, entries: list[dict]) -> None:
-    legacy_roots = {
-        Path(entry["path"]).parts[0]
-        for entry in entries
-        if entry.get("path") and Path(entry["path"]).parts[0] != "descriptors"
-    }
-    for legacy_root in legacy_roots:
-        source_root = Path(dst) / legacy_root
-        if not source_root.is_dir():
-            continue
-        destination_root = Path(dst) / "descriptors" / legacy_root
-        for root, dirs, files in os.walk(source_root, topdown=False):
-            relative_root = Path(root).relative_to(source_root)
-            destination = destination_root / relative_root
-            destination.mkdir(parents=True, exist_ok=True)
-            for name in files:
-                os.replace(Path(root) / name, destination / name)
-            for name in dirs:
-                (Path(root) / name).rmdir()
-        source_root.rmdir()
-
-
-def merge_into(src: str, dst: str) -> None:
-    """Merge a freshly-written single-op library `src` into the overlay `dst`,
-    accumulating index entries by operation/object variant and copying files."""
-    os.makedirs(dst, exist_ok=True)
-    with open(os.path.join(src, "index.json")) as src_index:
-        src_idx = json.load(src_index)
-    dst_idx_path = os.path.join(dst, "index.json")
-    if os.path.exists(dst_idx_path):
-        with open(dst_idx_path) as dst_index:
-            dst_idx = json.load(dst_index)
-    else:
-        dst_idx = {"schemaVersion": gen.SCHEMA_VERSION, "entries": []}
-    dst_entries = dst_idx.get("entries", [])
-    _migrate_legacy_descriptor_roots(dst, dst_entries)
-    for entry in dst_entries:
-        entry["path"] = _descriptor_overlay_path(entry["path"])
-    by_variant = {
-        _variant_key(e): e for e in dst_entries
-    }
-    for e in src_idx.get("entries", []):
-        # Re-preparing the same object refreshes it; preparing a different object
-        # accumulates a sibling variant under the shared generic nodeType.
-        e["path"] = _descriptor_overlay_path(e["path"])
-        by_variant[_variant_key(e)] = e
-    dst_idx["entries"] = sorted(
-        by_variant.values(),
-        key=lambda e: (
-            e.get("connectorKey", ""),
-            e.get("nodeType", ""),
-            e.get("version", ""),
-            e.get("objectName", ""),
-            e.get("path", ""),
-        ),
-    )
-    with open(dst_idx_path, "w") as f:
-        json.dump(dst_idx, f, indent=2)
-    for root, _dirs, files in os.walk(src):
-        for name in files:
-            if name == "index.json":
-                continue
-            rel = os.path.relpath(os.path.join(root, name), src)
-            rel = _descriptor_overlay_path(rel)
-            out = os.path.join(dst, rel)
-            os.makedirs(os.path.dirname(out), exist_ok=True)
-            shutil.copyfile(os.path.join(root, name), out)
-
-
-def _missing_generic_schema_message(
-    operation: str, object_name: str | None = None
-) -> str:
-    target = (
-        f'object "{object_name}" was not found or does not support action '
-        f'"{operation}"'
-        if object_name
-        else f'no object in the connected catalog supports action "{operation}"'
-    )
-    return (
-        f"prepare-connector: {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."
-    )
-
-
-def _object_action_specs(registry_path: str) -> list[tuple[str, list[str]]]:
-    """Return each api-type ObjectAction and its ordered parent-field names."""
-    try:
-        with open(registry_path) as registry_file:
-            node = json.load(registry_file)["Data"]["Node"]
-        actions = (
-            (node.get("connectorMethodInfo") or {})
-            .get("design") or {}
-        ).get("actions") or []
-    except (OSError, json.JSONDecodeError, KeyError, TypeError):
-        return []
-
-    specs = []
-    for action in actions:
-        if not isinstance(action, dict) or action.get("actionType") != "api":
-            continue
-        action_name = action.get("name")
-        if not isinstance(action_name, str) or not action_name:
-            continue
-        refs = [
-            rule.get("refFieldName")
-            for rule in (action.get("rules") or [])
-            if not rule.get("isCleared") and rule.get("refFieldName")
-        ]
-        if refs:
-            specs.append((action_name, refs))
-    return specs
-
-
-def _object_action_request(
-    registry_path: str, parent_fields: dict[str, str]
-) -> dict | None:
-    """Build the design-time schema replay request for a prepared operation.
-
-    The connection-resolved field list is only half of a schema-dynamic
-    connector configuration. Studio Web also persists the ObjectAction and the
-    parent values that produced that field list so it can replay the same
-    schema. The registry owns the action name and rule order; ``-f`` owns the
-    values.
-    """
-    if not parent_fields:
-        return None
-    for action_name, refs in _object_action_specs(registry_path):
-        if not refs or set(refs) != set(parent_fields):
-            continue
-        return {
-            "objectActionName": action_name,
-            "parameterValues": [
-                [name.replace(".", "_sub_"), parent_fields[name]]
-                for name in refs
-            ],
-        }
-    return None
-def _registry_actions(connector_key: str) -> list[str]:
-    """The action ids the REGISTRY serves for one connector, newest catalog.
-
-    `registry search` rather than a cached index: this runs only on the failure
-    path, where the whole question is what the tenant actually serves.
-    """
-    result = subprocess.run(
-        ["uip", "maestro", "flow", "registry", "search", connector_key, "--output", "json"],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        return []
-    try:
-        data = json.loads(result.stdout).get("Data") or []
-    except json.JSONDecodeError:
-        return []
-    prefix = f"uipath.connector.{connector_key}."
-    return sorted(
-        {
-            node_type[len(prefix):]
-            for entry in data
-            if isinstance(entry, dict)
-            for node_type in [entry.get("NodeType") or ""]
-            # Exact prefix only: the same search returns
-            # `uipath.agent.resource.tool.connector.<key>.<action>` and
-            # `uipath.connector.trigger.<key>.<event>`, which are not actions of
-            # this node and would read as alternatives an author could pass.
-            if node_type.startswith(prefix) and "." not in node_type[len(prefix):]
-        }
-    )
-
-
-def _closest_actions(action: str, candidates: list[str]) -> list[str]:
-    """Candidates ranked by shared hyphen tokens, best first.
-
-    Token overlap rather than edit distance because the two namespaces differ by
-    whole words, not typos: the baked library's `list-all-records` against the
-    registry's `list-records`.
-    """
-    wanted = set(action.split("-"))
-    scored = [
-        (len(wanted & set(c.split("-"))), -len(c), c)
-        for c in candidates
-        if wanted & set(c.split("-"))
-    ]
-    return [c for _, _, c in sorted(scored, reverse=True)]
-
-
-def _unresolved_action_message(connector_key: str, action: str, node_type: str) -> str:
-    """What to do when the action id is not a registry key.
-
-    NOT auto-substituted, deliberately. The baked action id and the registry key
-    are different namespaces — a generic op is `list-all-records` in the library
-    and materializes per object, while the registry serves `list-records` — and
-    guessing between them would emit a node both offline validators accept and
-    the runtime dispatches to the wrong operation. So this names the candidates
-    and lets the author choose.
-
-    The message earns its length: in the `generic-dynamic-node` eval the bare
-    "check the key/action" version sent an agent to page 18,037 objects through
-    `uip is resources list` for six turns instead of retrying with the right id.
-    """
-    actions = _registry_actions(connector_key)
-    lines = [
-        f"prepare-connector: `registry get {node_type}` 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 not actions:
-        lines += [
-            "",
-            f"`registry search {connector_key}` returned nothing. If the catalog looks",
-            "stale, refresh it first: `uip maestro flow registry pull --force`.",
-        ]
-        return "\n".join(lines)
-    close = _closest_actions(action, actions)
-    if close:
-        lines += ["", f"Closest to \"{action}\": {', '.join(close[:3])}"]
-    lines += ["", f"All actions the registry serves for {connector_key}:", *(f"  {a}" for a in actions)]
-    return "\n".join(lines)
-
-
-def main() -> None:
-    ap = argparse.ArgumentParser(description="Prepare a connector op's full schema into ./connectors-local")
-    ap.add_argument("key", help="connector key, e.g. uipath-atlassian-jira")
-    ap.add_argument("action", help="op action id, e.g. create-issue")
-    # OPTIONAL. `prepare` already knows the connector; making the author find
-    # its connection id by hand is work the command can do from what it has.
-    ap.add_argument(
-        "--connection-id", default=None,
-        help="a live connection id. Omit it and the connection is discovered "
-             "from `uip is connections list` — your folder first, the tenant "
-             "second — and its id AND folder key are written into bindings.json.")
-    ap.add_argument(
-        "--connection", default=None, metavar="NAME",
-        help="pick the connection by name when several match. Several "
-             "connections for one connector are NOT interchangeable, so an "
-             "ambiguous match is an error rather than a guess.")
-    ap.add_argument(
-        "--bindings", default="./bindings.json",
-        help="bindings file to add the discovered connection to "
-             "(default: ./bindings.json). Additive and idempotent.")
-    ap.add_argument(
-        "--bind-connection", default=None, metavar="NAME",
-        help="symbolic connection name to bind (default: the connector's last "
-             "dash-segment, e.g. `slack` for uipath-salesforce-slack)")
-    ap.add_argument(
-        "--bind-folder", default="shared",
-        help="symbolic folder name to bind (default: shared)")
-    ap.add_argument(
-        "--no-bindings", action="store_true",
-        help="discover the connection but do not touch bindings.json")
-    objects = ap.add_mutually_exclusive_group()
-    objects.add_argument(
-        "--object",
-        help="expand one connection-discovered object for a Generic action",
-    )
-    objects.add_argument(
-        "--all-objects",
-        action="store_true",
-        help="expand every connection-discovered object for a Generic action",
-    )
-    ap.add_argument(
-        "-f", "--field", action="append", default=[], metavar="NAME=VALUE",
-        help="a PARENT-field value that resolves the schema (repeatable), e.g. "
-             "-f fields.project.key=IN -f fields.issuetype.id=10620. Pass every "
-             "parent the operation declares: a partial set is rejected. See the "
-             "connector guide's parent-field loop.",
-    )
-    ap.add_argument("--out", default="./connectors-local", help="overlay dir (default: ./connectors-local)")
-    ap.add_argument("--source", default=None,
-                    help="the .flow.ts whose import should be repointed at the "
-                         "prepared descriptor (default: the one that imports "
-                         "this connector, when exactly one does)")
-    ap.add_argument("--no-source-rewrite", action="store_true",
-                    help="print the import line instead of editing the source")
-    ap.add_argument("--version", default=None, help="pin an op version (default: newest)")
-    ap.add_argument("--import", dest="imp", default="../sdk/flow-sdk.js",
-                    help="module specifier for the emitted .ts (default: ../sdk/flow-sdk.js)")
-    ap.add_argument(
-        "--resolve", action="append", default=[], metavar="FIELD:BY=VALUE",
-        help="resolve a lookup field to the id the connector wants, e.g. "
-             "--resolve channel:profile.email=someone@example.com. Repeatable; "
-             "order does not matter (a dependsOn prerequisite is resolved first). "
-             "Results land in <out>/resolutions.json, which compile reads.")
-    ap.add_argument(
-        "--refresh-lookups", action="store_true",
-        help="re-resolve lookups that are already recorded. Default is to leave "
-             "them alone: a resolved id is a snapshot either way, and silently "
-             "changing one during an unrelated prepare is worse than a stale one "
-             "you can see in a diff.")
-    ap.add_argument("--json-only", action="store_true",
-                    help="write the JSON overlay only — skip the typed .ts descriptor "
-                         "(the overlay alone already makes compile accept the fields; "
-                         "the A arm of the typed-vs-JSON study)")
-    args = ap.parse_args()
-
-    parent_fields = _parse_fields(args.field)
-    # Set when this run must NOT overwrite an already-prepared schema; see
-    # `_keep_prepared_schema`. Reported after the summary line, so the field
-    # count it explains has already been printed.
-    kept_schema: tuple[int, int] | None = None
-
-    # Discover the connection when the caller did not name one, and record it in
-    # bindings.json so the author never has to look up either key. This is the
-    # step that removes 4-7 tool calls per task: listing connections, filtering
-    # them, and then hunting Orchestrator for a folder key that was on the
-    # connection record all along.
-    # Whether the CALLER chose the connection, recorded before discovery
-    # overwrites `connection_id` with its own answer. An explicit choice is never
-    # second-guessed: the retry in `_write_resolutions` is for a connection this
-    # command picked, not for one the author named (flow-builder-sdk#744).
-    args._connection_pinned = bool(args.connection_id or args.connection)
-
-    if not args.connection_id:
-        try:
-            found = _connections.discover_connection(args.key, args.connection)
-        except _connections.ConnectionError_ as error:
-            sys.exit(f"prepare-connector: {error}")
-        args.connection_id = str(found["Id"])
-        print(f"  connection: {found.get('Name')} ({args.connection_id})")
-    else:
-        # An explicit id gets the same gate discovery applies. Without it a
-        # `State: Failed` connection went straight to `is resources describe`,
-        # which answers Success with NO request fields for a connection the
-        # tenant cannot reach — so the overlay was written with zero body
-        # inputs, reported as "0 input field(s)" success, and the next compile
-        # rejected every real field as unknown (skill-flow-ixp-routing-negative/
-        # sf-update: Salesforce update-record on a Failed connection, 0 fields;
-        # the Enabled connection carries 13, StageName among them).
-        try:
-            found = _connections.lookup_connection(args.key, args.connection_id)
-        except _connections.ConnectionError_ as error:
-            sys.exit(f"prepare-connector: {error}")
-        print(f"  connection: {found.get('Name')} ({args.connection_id})")
-
-    # Record the connection in bindings.json on BOTH routes. Until 3.30.5 only
-    # discovery wrote it: an explicit `--connection-id` — the one way past two
-    # connections that share a name — left the author hand-writing the id and
-    # folder key, and the hint below printed `<binding-name>` placeholders that
-    # went straight into source and bindings.json (measured on the eval corpus:
-    # angle-bracket and all-zero "GUIDs" in 16 archived bindings.json files).
-    if not args.no_bindings:
-        # Taken before the first write so a later refusal can undo exactly this
-        # command's changes, and only them.
-        _snapshot_bindings(args)
-        symbolic = args.bind_connection or args.key.rsplit("-", 1)[-1]
-        try:
-            wrote_conn, wrote_folder = _connections.merge_bindings(
-                args.bindings, found, symbolic, args.bind_folder)
-        except _connections.ConnectionError_ as error:
-            sys.exit(f"prepare-connector: {error}")
-        args._bound_connection = symbolic
-        args._bound_folder = args.bind_folder
-        for name, changed in ((symbolic, wrote_conn),
-                              (args.bind_folder, wrote_folder)):
-            if changed:
-                print(f"  bindings: {name} -> {args.bindings}")
-
-    gen.set_connection_id(args.connection_id)
-    gen.set_parent_fields(parent_fields)
-    gen.reset_failed_field_describes()
-    node_type = f"uipath.connector.{args.key}.{args.action}"
-
-    with tempfile.TemporaryDirectory() as tmp:
-        cache = os.path.join(tmp, "reg")
-        is_cache = os.path.join(tmp, "is")
-        os.makedirs(cache)
-        os.makedirs(is_cache)
-
-        path = gen.registry_get(node_type, cache, quiet=True)
-        if not path:
-            # Not an activity. Connector EVENTS live one namespace over —
-            # `uipath.connector.trigger.<key>.<event>` / `.event.<key>.<event>`
-            # — and their registry definition only answers with a connection,
-            # which this command has by now. Same loop, different twin pair.
-            if _prepare_event(args, tmp, cache):
-                return
-            sys.exit(_unresolved_action_message(args.key, args.action, node_type))
-        # The registry's own declaration of parent inputs, read while the file
-        # still exists: `path` lives in this temporary directory.
-        declared_parents = _declared_parents(path)
-        entry = gen.extract_canonical(path)
-        if not entry:
-            sys.exit(f"prepare-connector: no canonical entry for {node_type} (unexpected registry shape).")
-        if args.version:
-            entry["version"] = args.version
-        if parent_fields:
-            request = _object_action_request(path, parent_fields)
-            if not request:
-                expected = [
-                    ", ".join(fields)
-                    for _name, fields in _object_action_specs(path)
-                ]
-                expected_text = " or ".join(expected) or "<none advertised>"
-                sys.exit(
-                    "prepare-connector: parent-field names must match one "
-                    "api-type ObjectAction exactly. Given: "
-                    f"{', '.join(parent_fields)}. Expected: {expected_text}."
-                )
-            entry["operation"]["customFieldsRequestDetails"] = request
-
-        is_expandable_generic = (
-            entry["operation"].get("activityType") == "Generic"
-            and not gen._is_http_passthrough(entry)
-        )
-        if is_expandable_generic:
-            if not args.object and not args.all_objects:
-                sys.exit(
-                    "prepare-connector: this is a Generic action; pass "
-                    "--object <name> to prepare one object or --all-objects "
-                    "to prepare the full connected catalog."
-                )
-            templates = gen._generic_templates_by_op([entry]).get(args.key, {})
-            if args.object:
-                # The author's name, not necessarily the API's: `Company__C`
-                # from a prompt is `Company__c` in the catalog, and equality
-                # used to dead-end on exactly that. Match it deterministically
-                # BEFORE expansion — expansion re-reads the same file-cached
-                # catalog, so the match costs no extra network.
-                verb = next(iter(templates)) if len(templates) == 1 else None
-                requested = args.object
-                matched_row = _match_catalog_object(
-                    args.key, args.object, verb, is_cache
-                )
-                if matched_row is not None:
-                    args.object = matched_row.get("Name") or args.object
-                    args._object_requested = requested
-                    args._object_row = matched_row
-                    args._object_verb = verb
-            selected = None if args.all_objects else {args.object}
-            prepared_entries = gen.expand_generic_for_connector(
-                args.key, templates, is_cache, object_names=selected
-            )
-            if not prepared_entries:
-                operation = entry["operation"].get("name") or args.action
-                sys.exit(_missing_generic_schema_message(
-                    operation,
-                    None if args.all_objects else args.object,
-                ))
-        else:
-            if args.object or args.all_objects:
-                sys.exit(
-                    "prepare-connector: --object/--all-objects apply only to "
-                    "Generic connector actions."
-                )
-            gen.enrich_entry(entry, is_cache)  # full schema via --connection-id
-            prepared_entries = [entry]
-
-        tmplib = os.path.join(tmp, "lib")
-        gen.write_library(tmplib, prepared_entries, {entry["nodeType"]: path})
-        kept_schema = _keep_prepared_schema(
-            args, entry["nodeType"], tmplib, parent_fields,
-        )
-        if kept_schema is None:
-            merge_into(tmplib, args.out)
-
-    # The object decision is the FIRST resolution — recorded before any
-    # lookup rows, because it is their prerequisite: the schema the lookups
-    # were generated from is the one this match selected.
-    if getattr(args, "_object_row", None) is not None:
-        try:
-            ledger_path = _objects.record_object_resolution(
-                args.out, node_type, args._object_requested,
-                args._object_row, args._object_verb,
-            )
-        except _objects.LedgerError as error:
-            sys.exit(f"prepare-connector: {error}")
-        print(f"  object: {args._object_requested} -> {args.object} "
-              f"recorded in {ledger_path}")
-
-    if args.resolve:
-        _write_resolutions(args, node_type)
-
-    _regenerate_descriptors(args)
-    n_fields = _count_input_fields(args.out, entry["nodeType"], args.object)
-    n_variants = len(prepared_entries)
-    ts_note = "JSON overlay only" if args.json_only else f"overlay + {args.key}.ts"
-    field_note = _input_field_note(n_fields)
-    # The describe is the evidence, not the finished field count. A rejected
-    # parent set leaves `enrich_entry` returning the registry-DECLARED fields,
-    # so the overlay looks plausible (measured: project-only on Jira
-    # create-issue writes 3 declared fields) while the real answer was a
-    # Failure. Surface the CLI's own message instead of that quiet success.
-    failures = gen.failed_field_describes()
-    if args.field and (failures or n_fields == 0):
-        sys.exit(_rejected_parent_fields_message(args.field, failures))
-    print(
-        f"prepare-connector: {node_type} → {args.out}/ "
-        f"({ts_note}, {n_variants} variant(s), {field_note})"
-    )
-    if kept_schema is not None:
-        kept, discarded = kept_schema
-        print(
-            f"prepare-connector: kept the prepared schema for {args.action} "
-            f"({kept} input field(s)) — this run passed no -f, so its schema "
-            f"action did not run and the unresolved entry ({discarded} field(s)) "
-            f"would have replaced it. The resolutions above are recorded either "
-            f"way; re-run with -f to refresh the schema itself."
-        )
-    _print_lookup_vocabulary(args, node_type)
-    # Whether this operation has parent fields is answered by what we just
-    # prepared, not by a catalog flag: `extract_canonical` does not run the bulk
-    # discovery-marking pass, so `requiresConnectionForSchema` is still False
-    # here. A reference path carrying a {placeholder} IS the declaration.
-    parents, parent_only = _parent_fields(
-        args.out, entry["nodeType"], args.object
-    )
-    if parent_only and args.field:
-        # The set was SHAPED right (nothing was rejected) but resolved to
-        # nothing new, so at least one value does not exist on this connection.
-        sys.exit(
-            "prepare-connector: the parent-field values did not resolve — the "
-            "prepared schema is still parent-only (" + ", ".join(parents) +
-            f"). Given: {', '.join(args.field)}. 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."
-        )
-    # stdout is block-buffered under a pipe; flush so a `2>&1` reader sees the
-    # note after the overlay line it refers to, not before it.
-    sys.stdout.flush()
-    # Whether the schema action RAN is decided by its inputs, not by its
-    # output: every parent it names must have arrived as `-f`. Both earlier
-    # tests read the result instead, and between them let Jira's `create-issue`
-    # through silently — parent-only PLUS its own `key`, so "every field is a
-    # parent" was false and the registry declares no api-type ObjectAction for
-    # it either. The overlay then carried 3 of 19 inputs, `prepare` printed a
-    # clean "next:", and the author found out when `compile` refused `summary`.
-    # Union of both declaration sites so an overlay that omits `schemaAction`
-    # still gets the registry's answer.
-    action_parents = _schema_action_parents(args.out, entry["nodeType"], args.object)
-    action_parents += [
-        name for name in declared_parents if name not in action_parents
-    ]
-    missing = [name for name in action_parents if name not in parent_fields]
-    # Silent when the schema was KEPT: the note's premise is that the overlay
-    # now carries only the unresolved entry, and it does not — the richer one
-    # survived. Telling an author to "materialize the full field set" they are
-    # already holding sends them round a loop that changes nothing.
-    if missing and kept_schema is None:
-        # A schema parent IS a lookup: the id `--resolve` just recorded is the
-        # very value `-f` wants. The generic "resolve X and re-run" note made
-        # an agent run this prepare twice and hand-copy the id between the two
-        # commands (observed: 10732 retyped from the first run's output into
-        # the second run's -f). When every parent already has a recorded
-        # resolution, print the re-run ready to paste instead.
-        resolved_parents = _resolved_parent_values(args.out, node_type, action_parents)
-        given = " ".join(
-            f"-f {name}={parent_fields[name]}"
-            for name in action_parents
-            if name in parent_fields
-        )
-        if set(resolved_parents) == set(action_parents):
-            fields_arg = " ".join(
-                f"-f {name}={resolved_parents[name]}" for name in action_parents
-            )
-            print(
-                "prepare-connector: 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"
-                f"  npx flow-sdk registry prepare {args.key} {args.action} "
-                f"{fields_arg}",
-                file=sys.stderr,
-            )
-        else:
-            example = " ".join(
-                f"-f {name}={parent_fields.get(name, '<value>')}"
-                for name in action_parents
-            )
-            print(
-                "prepare-connector: note: this operation resolves its fields "
-                "from the VALUES of " + ", ".join(action_parents) +
-                " (its schema action), and " +
-                ("none were given" if len(missing) == len(action_parents)
-                 else f"{', '.join(missing)} " +
-                      ("was" if len(missing) == 1 else "were") + " not" +
-                      (f" (given: {given})" if given else "")) +
-                ", 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"
-                f"  npx flow-sdk registry prepare {args.key} {args.action} {example}",
-                file=sys.stderr,
-            )
-    if not args.json_only:
-        # The hint printed the placeholders `<binding-name>` /
-        # `<folder-binding-name>` even when this run had just WRITTEN both
-        # bindings and knew their names. Print what it bound, so the last line
-        # of output is a call the reader can paste.
-        usage = _descriptor_usage(
-            args.out, args.key,
-            getattr(args, "_bound_connection", None) or "<binding-name>",
-            getattr(args, "_bound_folder", None) or "<folder-binding-name>",
-        )
-        repointed = _repoint_source(args, args.key)
-        if repointed and repointed[0].startswith("repointed "):
-            # The edit is DONE, so telling the author to make it is now false.
-            # Drop the import line and keep the rest, which still teaches the
-            # call shape and the resolved-identity rule.
-            usage = [line for line in usage if not line.startswith("import {")]
-        for line in repointed:
-            print(f"prepare-connector: {line}")
-        for line in usage:
-            print(f"prepare-connector: next: {line}")
-
-
-def _print_lookup_vocabulary(args, node_type: str) -> None:
-    """Print the lookup table for the operation just prepared.
-
-    The markdown catalog renders this table for BAKED schemas; a schema that
-    only exists because this command ran has no page to carry it, so the
-    command itself is where the vocabulary first becomes knowable. Without it
-    the author meets a custom object's lookup fields one `check` warning at a
-    time instead of all at once, here, beside the import line.
-    """
-    specs = _lookup_specs_from_overlay(args.out, node_type, args.object)
-    if not specs:
-        return
-    where = f" ({args.object})" if args.object else ""
-    print(f"prepare-connector: lookup fields on {args.action}{where} — "
-          "these hold ids; author lookup(...) and resolve, don't paste one:")
-    shown = list(specs.items())[:12]
-    for field, spec in shown:
-        by = " | ".join(spec.get("by") or []) or "?"
-        target = f"{spec.get('objectName') or spec.get('path') or '?'}.{spec.get('value') or 'id'}"
-        print(f"  {field} — matches on {by}, sends {target}")
-    if len(specs) > len(shown):
-        print(f"  … and {len(specs) - len(shown)} more")
-    field, spec = shown[0]
-    by = (spec.get("by") or ["id"])[0]
-    obj = f" --object {args.object}" if args.object else ""
-    print("prepare-connector: resolve with: "
-          f"npx flow-sdk registry prepare {args.key} {args.action}{obj} "
-          f"--resolve {field}:{by}=<value>")
-
-
-def _resolved_parent_values(out_dir: str, node_type: str, parents) -> dict:
-    """`{parent: resolved id}` for every parent with a recorded resolution.
-
-    Read from the ledger just written, so the paste-ready `-f` re-run carries
-    the ids THIS invocation resolved — never guessed, never retyped.
-    """
-    try:
-        ledger = _objects.read_ledger(out_dir)
-    except _objects.LedgerError:
-        return {}
-    wanted = set(parents)
-    out: dict = {}
-    for key, row in (ledger.get("resolutions") or {}).items():
-        try:
-            key_node, field, _by, _match = json.loads(key)
-        except (ValueError, TypeError):
-            continue
-        if key_node == node_type and field in wanted:
-            out[field] = row.get("value")
-    return {k: v for k, v in out.items() if v not in (None, "")}
-
-
-def _match_catalog_object(key: str, wanted: str, verb: str | None, is_cache: str):
-    """The catalog row `--object` names, matched by `_objects.match_object`.
-
-    Returns the row, or None when the catalog itself is unavailable — that
-    failure belongs to expansion, whose message already covers it. Every
-    refusal past the name rungs (zero matches, substring — unique or
-    ambiguous) is retried once against a refreshed catalog before it is
-    believed: the `uip is resources list` cache never invalidates itself, so
-    an object the tenant gained after the cache was written reads as
-    nonexistent (measured: 18 objects stale vs 864 fresh on
-    uipath-salesforce-sfdc). The one exception — which refusal is retriable is
-    the exception's call, not this loop's — is ambiguity WITHIN a name rung:
-    two case-variant names are a fact a refresh will not change.
-    """
-    rows = gen.is_resources_list(key, is_cache, operation=verb) or []
-    if not rows:
-        return None
-    for attempt in ("cached", "refreshed"):
-        try:
-            row, note = _objects.match_object(rows, wanted, verb)
-        except _objects.ObjectMatchError as error:
-            if attempt == "cached" and error.retriable:
-                rows = gen.is_resources_list(
-                    key, is_cache, operation=verb, refresh=True
-                ) or rows
-                continue
-            sys.exit(f"prepare-connector: {error}")
-        if note:
-            print(f"  object: {note}")
-        return row
-    return None
-
-
-def _refuse_unless_byoa_connection(args) -> None:
-    """Refuse a standard connection on an event object that requires BYOA.
-
-    V1 measured the failure this prevents: the trigger deploys and then faults
-    at runtime with a webhook error naming nothing about connections. The
-    requirement is knowable now, so it is refused now, with the connections
-    that WOULD work.
-
-    A refusal must leave nothing behind. Stage 0 has already written this
-    connection into `bindings.json` by the time the event's own metadata says
-    it is the wrong KIND of connection — the BYOA fact needs a connection to
-    discover — so the file is restored to exactly what it was before the
-    refusal is raised. Otherwise the overlay keeps pointing at a connection
-    this command just forbade.
-    """
-    try:
-        rows = _connections.byoa_connections(args.key)
-    except _connections.ConnectionError_ as error:
-        # A listing that FAILED is not a tenant with no BYOA connections; the
-        # remedies are opposite and confusing them sends the reader to create
-        # a connection they may already have.
-        _restore_bindings(args)
-        sys.exit(
-            f"prepare-connector: this event object requires a BYOA "
-            f"(bring-your-own-app) connection, and the BYOA listing needed to "
-            f"check {args.connection_id} against it failed: {error}"
-        )
-    if args.connection_id in {str(row.get("Id")) for row in rows}:
-        return
-    _restore_bindings(args)
-    sys.exit(
-        f"prepare-connector: this event object requires a BYOA "
-        f"(bring-your-own-app) connection, and {args.connection_id} is not "
-        f"one. A standard connection deploys and then faults at runtime with "
-        f"an unrelated-looking webhook error. BYOA {args.key} connections:\n"
-        f"{_connections.byoa_listing(rows, args.key)}"
-    )
-
-
-def _event_operation(operation: dict) -> str:
-    """The operation key every trigger API takes.
-
-    NOT `operation.name`: that is the object's CRUD verb (`Create` on outlook
-    `email-received`), while the event's own operation is `EMAIL_RECEIVED`,
-    which `extract_canonical` stamps as `eventOperation` from the manifest's
-    `model.context`. `name` happens to fall back to the same context value
-    when the manifest omits `connectorMethodInfo.operation`, so reading it
-    works or silently queries the WRONG operation depending on which fallback
-    rung a given connector's manifest exercises — and both generation passes
-    already key on `eventOperation`.
-    """
-    return str(operation.get("eventOperation") or operation.get("name") or "")
-
-
-def _snapshot_bindings(args) -> None:
-    """Remember `bindings.json` byte-for-byte, before stage 0 touches it."""
-    path = getattr(args, "bindings", None)
-    if not path:
-        return
-    try:
-        with open(path, "rb") as handle:
-            args._bindings_before = handle.read()
-    except OSError:
-        args._bindings_before = None      # the file did not exist
-
-
-def _restore_bindings(args) -> None:
-    """Put `bindings.json` back exactly as `_snapshot_bindings` found it."""
-    path = getattr(args, "bindings", None)
-    if not path or not hasattr(args, "_bindings_before"):
-        return
-    before = args._bindings_before
-    try:
-        if before is None:
-            if os.path.exists(path):
-                os.remove(path)
-        else:
-            with open(path, "wb") as handle:
-                handle.write(before)
-    except OSError as error:
-        print(f"  WARN: could not restore {path} after refusing the "
-              f"connection: {error}", file=sys.stderr)
-
-
-def _prepare_event(args, tmp: str, cache: str) -> bool:
-    """Prepare a connector EVENT — the trigger/wait twin of an activity.
-
-    Returns False when `<key> <action>` is not an event either, so the caller
-    can raise the ordinary unknown-action error. Everything else is handled
-    here: the overlay entry is stored under the WAIT form
-    (`uipath.connector.event.<key>.<action>`) because the registry only
-    enriches the START form and the library derives the start form from its
-    wait sibling (`deriveTriggerForm`) — one stored variant serves both node
-    roles.
-    """
-    trigger_nt = f"uipath.connector.trigger.{args.key}.{args.action}"
-    event_nt = f"uipath.connector.event.{args.key}.{args.action}"
-    path = gen.registry_get(trigger_nt, cache)
-    if not path:
-        return False
-    entry = gen.extract_canonical(path)
-    if not entry:
-        return False
-    if args.field:
-        sys.exit("prepare-connector: -f parent fields apply to activities; "
-                 "a connector event has none.")
-    if args.all_objects:
-        sys.exit("prepare-connector: --all-objects applies to Generic "
-                 "activities; prepare a generic EVENT for one --object.")
-    with open(path, encoding="utf-8") as handle:
-        raw = json.load(handle)
-    node = (raw.get("Data") or {}).get("Node") or raw.get("Node") or {}
-    op = entry["operation"]
-    operation = _event_operation(op)
-    generic = op.get("activityType") == "GenericTrigger"
-
-    # The objects listing is the generic catalog AND the per-object fact sheet
-    # (BYOA, webhook visibility, bucket-scoped Parameters). For a curated
-    # event it is advisory — the definition already carries the sections — so
-    # a listing failure degrades to a warning there and is fatal only where
-    # it is the only source of truth.
-    try:
-        rows = _events.triggers_objects(args.key, operation, args.connection_id)
-    except _events.EventDiscoveryError as error:
-        if generic:
-            sys.exit(f"prepare-connector: {error}")
-        rows = []
-        print(f"  WARN: {error}", file=sys.stderr)
-
-    describe = None
-    object_row = None
-    requested_object = None
-    if generic:
-        if not args.object:
-            sample = ", ".join(
-                str(row.get("Name")) for row in rows[:8] if row.get("Name"))
-            sys.exit(
-                f"prepare-connector: {args.action} is a Generic event — it "
-                f"fires for ONE object of the connection. Pass --object "
-                f"<name>. This connection's objects include: {sample}"
-                + (" …" if len(rows) > 8 else "")
-            )
-        # The author's name, not necessarily the API's — same ladder, same
-        # refusal semantics as a Generic activity. The listing is live (no
-        # CLI-side cache), so there is nothing to refresh on a miss.
-        try:
-            object_row, note = _objects.match_object(rows, args.object, operation)
-        except _objects.ObjectMatchError as error:
-            sys.exit(f"prepare-connector: {error}")
-        if note:
-            print(f"  object: {note}")
-        requested_object = args.object
-        args.object = object_row.get("Name") or args.object
-        try:
-            describe = _events.triggers_describe(
-                args.key, operation, args.object, args.connection_id)
-        except _events.EventDiscoveryError as error:
-            sys.exit(f"prepare-connector: {error}")
-        op["objectName"] = args.object
-        op["objectDisplayName"] = str(object_row.get("DisplayName") or "")
-    else:
-        if args.object:
-            sys.exit(
-                f"prepare-connector: --object applies to Generic events; "
-                f"{args.action}'s object is built in "
-                f"({op.get('objectName') or 'none'})."
-            )
-        baked = str(op.get("objectName") or "")
-        object_row = next(
-            (row for row in rows if str(row.get("Name")) == baked), None)
-        # `triggers describe` is the AUTHORITY for a curated event too, not
-        # just a generic one. The registry definition mirrors it and the
-        # mirror is lossy: measured on outlook `email-received`, describe
-        # returns 15 filter fields and the registry 14 — `isRead` is only in
-        # describe, and both agree on all 73 output fields. Reading the mirror
-        # would leave `check` REFUSING a filter on `isRead` as an unknown
-        # field, which is the one diagnostic here that is an error. Fall back
-        # to the definition's own sections when describe cannot answer (a
-        # baked object name the trigger catalog does not list) rather than
-        # failing the prepare — the mirror is still a usable vocabulary.
-        if baked:
-            try:
-                describe = _events.triggers_describe(
-                    args.key, operation, baked, args.connection_id)
-            except _events.EventDiscoveryError as error:
-                print(f"  WARN: {error}\n"
-                      f"  falling back to the registry definition's own "
-                      f"schema sections for {baked}", file=sys.stderr)
-
-    facts = _events.event_facts(node, object_row)
-    if facts["byoaConnection"]:
-        _refuse_unless_byoa_connection(args)
-
-    # One stored shape: the registry definition with the describe sections
-    # made true for this object (generic), or with the object row's
-    # Parameters unioned in (curated). `Library.eventParameterFields` reads
-    # `v1def.eventParameters.fields`, so the overlay v1def IS the store.
-    object_parameters = (object_row or {}).get("Parameters")
-    if describe is not None:
-        node = _events.merge_describe_into_node(node, describe, object_parameters)
-    else:
-        node = dict(node)
-        node["eventParameters"] = {"fields": _events.union_event_parameters(
-            (node.get("eventParameters") or {}).get("fields"),
-            object_parameters,
-        )}
-    if (node.get("outputResponseDefinition") or {}).get("fields"):
-        entry["outputSchema"] = {
-            "fields": node["outputResponseDefinition"]["fields"]}
-    node["nodeType"] = event_nt
-    entry["nodeType"] = event_nt
-
-    merged_path = os.path.join(tmp, "event-def.json")
-    with open(merged_path, "w", encoding="utf-8") as handle:
-        json.dump({"Data": {"Node": node}}, handle)
-
-    tmplib = os.path.join(tmp, "eventlib")
-    gen.write_library(tmplib, [entry], {event_nt: merged_path})
-    merge_into(tmplib, args.out)
-
-    if generic:
-        try:
-            ledger_path = _objects.record_object_resolution(
-                args.out, event_nt, requested_object, object_row, operation)
-        except _objects.LedgerError as error:
-            sys.exit(f"prepare-connector: {error}")
-        print(f"  object: {requested_object} -> {args.object} "
-              f"recorded in {ledger_path}")
-
-    if args.resolve:
-        _write_resolutions(args, event_nt)
-
-    _regenerate_descriptors(args)
-
-    where_fields = (node.get("eventParameters") or {}).get("fields") or []
-    filter_fields = (node.get("filterFields") or {}).get("fields") or []
-    mode = facts["eventMode"]
-    print(f"prepare-connector: {event_nt} → {args.out}/ (event overlay, "
-          f"{operation}, {mode}, {len(where_fields)} where-parameter(s), "
-          f"{len(filter_fields)} filter field(s))")
-    sys.stdout.flush()
-    _print_lookup_vocabulary(args, event_nt)
-    if filter_fields:
-        names = ", ".join(str(f.get("name")) for f in filter_fields[:8])
-        print(f"prepare-connector: filterable fields ({len(filter_fields)}): "
-              f"{names}" + (" …" if len(filter_fields) > 8 else ""))
-    if mode == "webhooks":
-        # Registration is an act on the external service — the one step this
-        # loop cannot make deterministic. Hand the author the connector's own
-        # words instead of leaving `uip is webhooks config` to be discovered.
-        print("prepare-connector: 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"
-              + (":" if facts["textBlocks"] else
-                 " (retrieve it with `uip is webhooks config`)."),
-              file=sys.stderr)
-        for block in facts["textBlocks"]:
-            print(f"  {block}", file=sys.stderr)
-    connection_name = getattr(args, "_bound_connection", None) or "<connection>"
-    folder_name = getattr(args, "_bound_folder", None) or "shared"
-    subscription = (
-        f"{{ connector: '{args.key}', event: '{args.action}'"
-        + (f", object: '{args.object}'" if generic else "")
-        + f", connection: '{connection_name}', folder: '{folder_name}' }}"
-    )
-    print(f"prepare-connector: next: .trigger(onEvent({subscription})) to "
-          f"start the flow on this event — or .step('…', "
-          f"waitForEvent({subscription})) to pause mid-flow for it")
-    return True
-
-
-def _overlay_has_generic_expanded(out: str) -> bool:
-    """Does the overlay hold ANY `GenericExpanded` entry, from any prepare?"""
-    try:
-        with open(os.path.join(out, "index.json"), encoding="utf-8") as handle:
-            entries = json.load(handle).get("entries") or []
-    except (OSError, ValueError):
-        return False
-    return any(e.get("activityType") == "GenericExpanded" for e in entries)
-
-
-def _regenerate_descriptors(args) -> None:
-    """Rewrite the overlay's typed descriptors from the overlay's own JSON.
-
-    Both prepare paths end here. The EVENT path used not to: it wrote the JSON
-    overlay and returned, so a project whose only prepare was an event got no
-    `.ts` at all, and one that had prepared an action earlier kept that older
-    run's module — generated before the event's parameters were in the overlay,
-    so `where` was `Record<string, string>` and the trigger carried no
-    `lookups`. That is the module `prepare` tells the author to import, and
-    `--refresh-lookups` could not repair it, because nothing on the event path
-    regenerated TypeScript at all.
-
-    `--include-generic-expanded` is decided from the WHOLE overlay index rather
-    than the entries of this run: the generator rewrites every module under
-    `--output`, so reading one run would drop the descriptors an earlier
-    `GenericExpanded` prepare had written.
-    """
-    if args.json_only:
-        return
-    command = [
-        sys.executable, str(HERE / "generate_connectors_ts.py"),
-        "--library", args.out, "--output", args.out, "--import", args.imp,
-    ]
-    if _overlay_has_generic_expanded(args.out):
-        command.append("--include-generic-expanded")
-    subprocess.run(command, check=True)
-
-
-def _write_resolutions(args, node_type: str) -> None:
-    """Resolve every `--resolve` and merge the answers into the overlay.
-
-    A SEPARATE FILE from the schema overlay, deliberately. A prepared schema is
-    a fact about the connector; a resolution is a fact about one tenant's data,
-    so it ages differently and most consumers will want to gitignore it. Keeping
-    them apart is also what lets `--refresh-lookups` mean something later.
-
-    Existing entries STAND rather than being re-resolved. A resolved id is a
-    snapshot either way; re-resolving on every call would make an unrelated
-    `prepare` silently change an artifact, which is the opposite of what the
-    file is for. Re-resolving is a deliberate act with a visible diff.
-    """
-    specs = _lookup_specs_from_overlay(args.out, node_type, args.object)
-    requested = [_resolve.parse_resolve_flag(raw) for raw in args.resolve]
-
-    unknown = [f for f, _b, _v in requested if f not in specs]
-    if unknown:
-        known = ", ".join(sorted(specs)) or "(none)"
-        sys.exit(
-            f"prepare-connector: no lookup is declared for "
-            f"{', '.join(repr(f) for f in unknown)} on {node_type}. "
-            f"Fields with a lookup: {known}."
-        )
-
-    ordered = _resolve.order_resolutions(requested, specs)
-    path = os.path.join(args.out, "resolutions.json")
-    # Read and rewrite the WHOLE ledger, not just `resolutions`: the file also
-    # carries the `objects` section (the object decision recorded above), and
-    # rewriting only one section used to silently drop the other. A file that
-    # will not parse is REFUSED rather than reset — same rule as bindings.json.
-    try:
-        ledger = _objects.read_ledger(args.out)
-    except _objects.LedgerError as error:
-        sys.exit(f"prepare-connector: {error}")
-    existing = ledger.get("resolutions") or {}
-
-    resolved_values: dict[str, str] = {}
-    for field, by, value in ordered:
-        # COMPACT SEPARATORS, to match JavaScript exactly. `compile` computes
-        # this key with `JSON.stringify`, which emits no space after a comma;
-        # Python's default emits `", "`. The two encodings of the same tuple are
-        # different strings, so every resolution `prepare` wrote was invisible to
-        # the compile that had just asked for it — the command did the work,
-        # recorded it, and then refused to use it.
-        key = json.dumps([node_type, field, by, value], separators=(",", ":"))
-        if key in existing and not args.refresh_lookups:
-            resolved_values[field] = existing[key]["value"]
-            print(f"  {field}: {by}={value} -> {existing[key]['value']} (already resolved)")
-            continue
-        try:
-            got = _resolve.resolve_one(
-                args.key, specs[field], field, by, value,
-                args.connection_id, resolved_values,
-            )
-        except _resolve.LookupExhausted as error:
-            # The collection was read to the END on this connection and the
-            # value is not in it. That is evidence about the CONNECTION, not
-            # only about the value — so before failing, try the other enabled
-            # connections for this connector. A transport failure is the
-            # sibling exception below and is never retried: retrying it would
-            # dress a broken call up as "no connection has it".
-            _retry_or_exit(args, node_type, specs, ordered, error)
-        except _resolve.ResolutionError as error:
-            sys.exit(f"prepare-connector: {error}")
-        resolved_values[field] = got
-        existing[key] = {
-            "nodeType": node_type, "field": field, "by": by,
-            "match": value, "value": got,
-        }
-        print(f"  {field}: {by}={value} -> {got}")
-
-    os.makedirs(args.out, exist_ok=True)
-    ledger["schemaVersion"] = "1"
-    ledger["resolutions"] = existing
-    with open(path, "w", encoding="utf-8") as handle:
-        json.dump(ledger, handle, indent=2, sort_keys=True)
-        handle.write("\n")
-    print(f"  wrote {len(existing)} resolution(s) to {path}")
-
-
-def _candidate_label(row: dict) -> str:
-    """`name (folder)` for a per-candidate report line."""
-    return f"{row.get('Name')} ({row.get('Folder')})"
-
-
-def _probe_candidate(args, specs, ordered, connection_id: str):
-    """Resolve every requested lookup against one connection.
-
-    Returns `None` when all of them resolve, or the first reason they did not:
-    `("exhausted", <LookupExhausted>)` or `("error", <ResolutionError>)`. The
-    two are kept apart all the way up, because only the first is evidence about
-    the connection.
-    """
-    resolved: dict[str, str] = {}
-    for field, by, value in ordered:
-        try:
-            resolved[field] = _resolve.resolve_one(
-                args.key, specs[field], field, by, value, connection_id, resolved,
-            )
-        except _resolve.LookupExhausted as error:
-            return ("exhausted", error)
-        except _resolve.ResolutionError as error:
-            return ("error", error)
-    return None
-
-
-def _retry_or_exit(args, node_type: str, specs, ordered, first) -> None:
-    """Try the other candidate connections, or exit explaining what was tried.
-
-    NEVER RETURNS. Either it re-execs this command pinned to a connection that
-    resolves everything, or it exits with a report.
-    """
-    if args._connection_pinned:
-        # 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.
-        others = [
-            row for row in _connections.candidate_connections(args.key)
-            if str(row.get("Id")) != str(args.connection_id)
-        ]
-        extra = ""
-        if others:
-            extra = (
-                f"\n{len(others)} other enabled {args.key} connection"
-                f"{'s' if len(others) > 1 else ''} exist"
-                f"{'' if len(others) > 1 else 's'}:\n"
-                f"{_connections.candidate_listing(others)}\n"
-                "Re-run against one of those, or check the value. This run kept the "
-                "connection you named."
-            )
-        sys.exit(f"prepare-connector: {first}{extra}")
-
-    try:
-        candidates = _connections.candidate_connections(args.key, args.connection)
-    except _connections.ConnectionError_ as error:
-        # The listing itself failed; report the original lookup failure, which is
-        # the thing the author asked about.
-        sys.exit(f"prepare-connector: {first}\n(could not list other connections: {error})")
-
-    others = [row for row in candidates
-              if str(row.get("Id")) != str(args.connection_id)]
-    if not others:
-        sys.exit(
-            f"prepare-connector: {first}\n"
-            f"This is the only enabled {args.key} connection on the tenant, so the "
-            "value is what to check."
-        )
-
-    print(f"  {first.field}: not on this connection; trying "
-          f"{len(others)} other {args.key} connection(s)")
-    winners: list[dict] = []
-    report: list[str] = []
-    for row in others:
-        outcome = _probe_candidate(args, specs, ordered, str(row.get("Id")))
-        if outcome is None:
-            winners.append(row)
-            report.append(f"    {_candidate_label(row)}  resolves all "
-                          f"{len(ordered)} lookup(s)")
-            continue
-        kind, error = outcome
-        if kind == "exhausted":
-            report.append(
-                f"    {_candidate_label(row)}  {error.field}: "
-                f"{error.scanned} record(s) scanned, no match")
-        else:
-            report.append(f"    {_candidate_label(row)}  {error}")
-
-    if len(winners) == 1:
-        chosen = winners[0]
-        # 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
-        # lookup specs are described THROUGH a connection
-        # (`_lookup_specs_from_overlay`), so adopting a different connection
-        # after the describe would leave the overlay describing one connection
-        # while bindings.json names another.
-        _restore_bindings(args)
-        print(f"  connection: {_candidate_label(chosen)} resolves "
-              f"{first.field}; re-running against it "
-              f"(--connection-id {chosen.get('Id')})")
-        argv = [sys.executable, *sys.argv,
-                "--connection-id", str(chosen.get("Id"))]
-        # The ledger keys a resolution by [nodeType, field, by, value] and NOT by
-        # connection, so an id recorded against the connection just abandoned
-        # would be reused as "already resolved". Force the re-run to resolve
-        # against the connection it actually pins.
-        if not args.refresh_lookups:
-            argv.append("--refresh-lookups")
-        sys.stdout.flush()
-        try:
-            os.execv(sys.executable, argv)
-        except OSError as error:
-            # `execv` does not return on success, so reaching here means the
-            # re-run could not start. Hand back the command rather than a
-            # traceback: the author is one paste from the answer.
-            pinned = " ".join(argv[2:])
-            sys.exit(
-                f"prepare-connector: {first}\n"
-                f"{_candidate_label(chosen)} resolves it, but this command could "
-                f"not re-run itself ({error}). Run:\n  prepare {pinned}"
-            )
-        # Unreachable in production — execv replaced the process. Kept so the
-        # function can never fall through to the report below, which would
-        # contradict the line just printed.
-        raise SystemExit(0)
-
-    if len(winners) > 1:
-        sys.exit(
-            f"prepare-connector: {len(winners)} {args.key} connections resolve "
-            f"every requested lookup, and they are not interchangeable — the ids "
-            f"they return differ per connection. Pick the one you mean:\n"
-            f"{_connections.candidate_listing(winners)}"
-        )
-
-    # Nothing resolved anywhere. Report every candidate and what it held, the
-    # one connection first, so the reader can see the value really is absent
-    # rather than guess which connection was asked.
-    original = next(
-        (row for row in candidates
-         if str(row.get("Id")) == str(args.connection_id)),
-        {"Name": args.connection_id, "Folder": "?"},
-    )
-    lines = [f"    {_candidate_label(original)}  {first.field}: "
-             f"{first.scanned} record(s) scanned, no match", *report]
-    # 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.
-    sys.exit(
-        f"prepare-connector: no {args.key} connection could resolve "
-        f"{first.field}: {first.by}={first.value!r}\n"
-        + "\n".join(lines) + "\n"
-        "Every candidate was read to the end, so the value is what to check now. "
-        f"To see what {first.collection!r} holds:\n"
-        f"  uip is resources run list {args.key} {first.collection} "
-        f"--connection-id {args.connection_id}"
-    )
-
-
-def _lookup_specs_from_overlay(
-    out_dir: str, node_type: str, object_name: str | None = None,
-) -> dict:
-    """The prepared operation's lookup specs, from the overlay just written.
-
-    Read back from the overlay rather than recomputed, so a resolution is made
-    against the SAME schema the descriptors were generated from — including any
-    connection-resolved field that only exists because this `prepare` ran.
-    """
-    index_path = os.path.join(out_dir, "index.json")
-    if not os.path.exists(index_path):
-        return {}
-    with open(index_path, encoding="utf-8") as handle:
-        entries = json.load(handle).get("entries", [])
-    invariant = load_invariant_collections(out_dir)
-    for entry in entries:
-        if entry.get("nodeType") != node_type:
-            continue
-        # Generic object variants share a nodeType; without the object filter
-        # the FIRST variant answered for all of them, so a `--resolve` against
-        # the object just prepared read another object's lookup table.
-        if object_name and entry.get("objectName") not in ("", None, object_name):
-            continue
-        entry_path = os.path.join(out_dir, entry["path"])
-        v1_path = entry_path[:-5] + ".v1def.json"
-        if not os.path.exists(entry_path):
-            continue
-        with open(entry_path, encoding="utf-8") as handle:
-            canonical = json.load(handle)
-        v1def = {}
-        if os.path.exists(v1_path):
-            with open(v1_path, encoding="utf-8") as handle:
-                raw = json.load(handle)
-            v1def = raw[0] if isinstance(raw, list) else raw
-        # An EVENT's resolvable fields are its subscription parameters, and
-        # `v1def.eventParameters.fields` is the ONE authority for those — the
-        # same list the SDK, `check` and the descriptor generator read.
-        #
-        # This used to pick the source by testing whether `inputSchema` was
-        # empty, which was right only because the prepare path happens to
-        # leave `inputSchema` as the manifest wrote it while generation
-        # overwrites it. Either path changing flips the heuristic and the
-        # specs come from the manifest's message-BODY fields instead — the
-        # exact wrong list. The node kind is the fact being tested, so test
-        # it.
-        if node_type.startswith(("uipath.connector.event.",
-                                 "uipath.connector.trigger.")):
-            fields_source = {"inputSchema": {
-                "fields": (v1def.get("eventParameters") or {}).get("fields") or []
-            }}
-        else:
-            fields_source = canonical
-        specs = gen_ts.lookup_specs(fields_source, v1def, invariant)
-        # `filterPattern` is not on the descriptor spec (it is a retrieval
-        # detail, not an authoring one) but the resolver needs it.
-        catalog = {
-            f.get("name"): f["reference"]
-            for f in ((fields_source.get("inputSchema") or {}).get("fields") or [])
-            if isinstance(f.get("reference"), dict)
-        }
-        for field, spec in specs.items():
-            reference = catalog.get(field) or {}
-            if reference.get("filterPattern"):
-                spec["filterPattern"] = reference["filterPattern"]
-        return specs
-    return {}
-
-
-# `import … from "<specifier>"` — the specifier is group 3, quotes preserved.
-# Deliberately anchored to a real import STATEMENT: the instruction this
-# replaces became `sed 's|./connectors/|./connectors-local/|'` in practice,
-# which also rewrites the same text inside comments and inside the imports of
-# connectors this run did NOT prepare (#704).
-_IMPORT_RE = re.compile(
-    r"""(^\s*import\s[^;'"]*?\sfrom\s*)(['"])([^'"]+)(\2)""",
-    re.MULTILINE,
-)
-
-# Where a `.flow.ts` will not be: generated output and installed packages.
-_SOURCE_SKIP_DIRS = {"node_modules", "connectors", "connectors-local", ".git"}
-
-
-def _resolves_to(specifier: str, source: Path, target: Path) -> bool:
-    """Does `specifier`, read from `source`, name the file `target`?
-
-    Compared as RESOLVED paths, not as text, so `./connectors/x.ts` from the
-    project root and `../connectors/x.ts` from a nested source both match the
-    one file — and a same-named connector under a different root does not.
-    """
-    if not specifier.startswith("."):
-        return False                      # a bare package, never our overlay
-    try:
-        candidate = (source.parent / specifier).resolve()
-    except (OSError, ValueError):
-        return False
-    return candidate == target
-
-
-def _sources_importing(baked: Path, root: Path) -> list[Path]:
-    """Every `*.flow.ts` under `root` whose import resolves to `baked`.
-
-    Selection is by CONTENT rather than "the single flow in this directory":
-    a workspace with three flows, one of which uses this connector, has one
-    correct answer and this finds it.
-    """
-    found: list[Path] = []
-    for path in sorted(root.rglob("*.flow.ts")):
-        if _SOURCE_SKIP_DIRS & set(path.relative_to(root).parts[:-1]):
-            continue
-        try:
-            text = path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
-            continue
-        if any(_resolves_to(m.group(3), path, baked) for m in _IMPORT_RE.finditer(text)):
-            found.append(path)
-    return found
-
-
-def _repoint_import(source: Path, baked: Path, prepared: Path) -> str | None:
-    """Point `source`'s import at the prepared descriptor. The new specifier, or None.
-
-    Only the quoted path changes. The rest of the statement — the named
-    bindings, an `as` alias, the quote style — is carried through untouched,
-    which is the whole difference between this and the find-and-replace it
-    replaces.
-    """
-    try:
-        text = source.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
-        return None
-    specifier = os.path.relpath(prepared, source.parent).replace(os.sep, "/")
-    if not specifier.startswith("."):
-        specifier = f"./{specifier}"
-    changed = False
-
-    def swap(match: "re.Match[str]") -> str:
-        nonlocal changed
-        if not _resolves_to(match.group(3), source, baked):
-            return match.group(0)
-        changed = True
-        return f"{match.group(1)}{match.group(2)}{specifier}{match.group(4)}"
-
-    rewritten = _IMPORT_RE.sub(swap, text)
-    if not changed or rewritten == text:
-        return None
-    source.write_text(rewritten, encoding="utf-8")
-    return specifier
-
-
-def _repoint_source(args, connector_key: str) -> list[str]:
-    """Repoint the author's import, or explain why it was left alone.
-
-    `prepare` already writes `bindings.json`, the overlay descriptor and
-    `resolutions.json`; the one thing it did NOT do was update the import
-    naming the descriptor it had just replaced. That left a mechanical edit —
-    one specifier, one file, exactly one right answer — to the caller, who has
-    strictly less information than this command does. Measured cost: an agent
-    reaches for `sed`, which repoints connectors that were never prepared and
-    breaks the flow with `Cannot find module`.
-
-    Ambiguity keeps today's behaviour. Zero candidates or several, and nothing
-    is written — the printed import line still tells the author what to do, so
-    the fallback is exactly the status quo and never worse.
-    """
-    prepared = (Path(args.out) / f"{connector_key}.ts").resolve()
-    if getattr(args, "no_source_rewrite", False) or not prepared.is_file():
-        return []
-    baked = (Path.cwd() / "connectors" / f"{connector_key}.ts").resolve()
-
-    if getattr(args, "source", None):
-        candidates = [Path(args.source).resolve()]
-        if not candidates[0].is_file():
-            return [f"--source {args.source} does not name a file; "
-                    f"left the import alone"]
-    else:
-        candidates = _sources_importing(baked, Path.cwd())
-
-    if not candidates:
-        return []
-    if len(candidates) > 1:
-        names = ", ".join(
-            c.relative_to(Path.cwd()).as_posix() for c in candidates)
-        return [f"{len(candidates)} sources import this connector ({names}); "
-                f"name one with --source to have it repointed"]
-
-    source = candidates[0]
-    specifier = _repoint_import(source, baked, prepared)
-    if specifier is None:
-        return []
-    return [f"repointed {source.relative_to(Path.cwd()).as_posix()} "
-            f"-> {specifier}"]
-
-
-def _descriptor_usage(out_dir: str, connector_key: str,
-                      bound_connection: str = "<binding-name>",
-                      bound_folder: str = "<folder-binding-name>") -> list[str]:
-    """Teach the author how to consume the connection-resolved descriptor.
-
-    The live registry may use a different action id than the baked catalog. The
-    generated descriptor is the authority for that resolved identity, so the
-    success message must carry the author across that boundary instead of
-    leaving them to reverse-engineer index.json.
-    """
-    source = Path(out_dir) / f"{connector_key}.ts"
-    try:
-        generated = source.read_text()
-        exports = re.findall(
-            r"^export const ([A-Za-z_$][A-Za-z0-9_$]*) = "
-            r"descriptor<([A-Za-z_$][A-Za-z0-9_$]*),",
-            generated,
-            flags=re.MULTILINE,
-        )
-    except OSError:
-        generated = ""
-        exports = []
-
-    import_path = os.path.relpath(source, Path.cwd()).replace(os.sep, "/")
-    if not import_path.startswith("."):
-        import_path = f"./{import_path}"
-    if len(exports) == 1:
-        descriptor_name, inputs_interface = exports[0]
-        required_fields = _required_interface_fields(
-            generated, inputs_interface
-        )
-        if required_fields is None:
-            return [
-                f'open "{source.as_posix()}" and import {descriptor_name}',
-                "read its generated inputs interface before calling connector; "
-                "the required-input skeleton is unavailable",
-            ]
-        inputs = "{}"
-        if required_fields:
-            placeholders = ", ".join(
-                f"{name}: /* {field_type}, required */"
-                for name, field_type in required_fields
-            )
-            inputs = f"{{ {placeholders} }}"
-        return [
-            f'import {{ {descriptor_name} }} from "{import_path}";',
-            f'connector({descriptor_name}, {inputs}, '
-            f'{{ connection: "{bound_connection}", folder: "{bound_folder}" }})',
-            "use this descriptor as generated: it carries the resolved live "
-            "operation and object identity even when the baked action id differs",
-        ]
-
-    return [
-        f'open "{source.as_posix()}" 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",
-    ]
-
-
-def _required_interface_fields(
-    generated: str, interface_name: str
-) -> list[tuple[str, str]] | None:
-    match = re.search(
-        rf"^export interface {re.escape(interface_name)} \{{(?P<body>.*?)^\}}",
-        generated,
-        flags=re.MULTILINE | re.DOTALL,
-    )
-    if not match:
-        return None
-
-    required: list[tuple[str, str]] = []
-    property_pattern = re.compile(
-        r'^  (?P<name>[A-Za-z_$][A-Za-z0-9_$]*|"(?:\\.|[^"\\])*")'
-        r'(?P<optional>\?)?: (?P<type>.+);$'
-    )
-    for line in match.group("body").splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith(("/**", "*", "*/")):
-            continue
-        field = property_pattern.match(line)
-        if not field:
-            return None
-        if not field.group("optional"):
-            required.append((field.group("name"), _unwrap_value(field.group("type"))))
-    return required
-
-
-def _unwrap_value(ts_type: str) -> str:
-    """`ConnectorValue<string>` -> `string`, for the handoff skeleton.
-
-    The generated property type says what the field ACCEPTS — the literal or an
-    expression — which is the right thing for the compiler and the wrong thing
-    for a one-line "what goes here" hint. An author reading
-    `/* ConnectorValue<string>, required */` learns less than one reading
-    `/* string, required */`, and the wrapper is not something they type.
-    """
-    match = re.fullmatch(r"Connector(?:Lookup)?Value<(.+)>", ts_type.strip())
-    return match.group(1) if match else ts_type
-
-
-def _count_input_fields(
-    out_dir: str, node_type: str, object_name: str | None = None
-) -> int | None:
-    """Input-field count across matching overlay variants."""
-    try:
-        with open(os.path.join(out_dir, "index.json")) as index_file:
-            idx = json.load(index_file)
-        entries = idx["entries"]
-        if not isinstance(entries, list):
-            return None
-        total = 0
-        matched = False
-        for index_entry in entries:
-            if index_entry["nodeType"] != node_type:
-                continue
-            if object_name is not None and index_entry.get("objectName") != object_name:
-                continue
-            matched = True
-            with open(os.path.join(out_dir, index_entry["path"])) as entry_file:
-                descriptor = json.load(entry_file)
-            if not isinstance(descriptor, dict):
-                return None
-            input_schema = descriptor.get("inputSchema")
-            if not isinstance(input_schema, dict):
-                return None
-            fields = input_schema.get("fields")
-            if not isinstance(fields, list):
-                return None
-            total += len(fields)
-        return total if matched else None
-    except (OSError, json.JSONDecodeError, KeyError, TypeError):
-        return None
-
-
-def _declared_parents(registry_path: str) -> list[str]:
-    """Parent-input names the registry declares through api-type ObjectActions.
-
-    The second way an operation says "my fields depend on a value": not a
-    `{placeholder}` in a reference path (Jira), but a design-time action whose
-    rules name the inputs it reads (Data Fabric `create-entity-record` declares
-    `GenerateSchema` over `entityName`). `_object_action_specs` already reads
-    them for the replay request; this is the same list, flattened and in
-    declaration order, for the no-`-f` note.
-    """
-    names: list[str] = []
-    for _action, refs in _object_action_specs(registry_path):
-        for ref in refs:
-            if ref not in names:
-                names.append(ref)
-    return names
-
-
-def _schema_action_parents(
-    out_dir: str, node_type: str, object_name: str | None = None
-) -> list[str]:
-    """Parent inputs the PREPARED operation's own schema action names.
-
-    The third and most direct way an operation says "my fields depend on a
-    value", and the only one that is a PRECONDITION rather than a symptom: the
-    descriptor just written carries `operation.schemaAction.parents`, so with
-    any of those missing from `-f` the action cannot have run, whatever the
-    describe returned. `_parent_fields` and `_declared_parents` both read the
-    result or the registry instead, and each has a shape it cannot see:
-
-    - `_parent_fields` asks "is EVERY prepared field a parent?". Jira's
-      `create-issue` comes back parent-only PLUS `key` (its own issue key), so
-      that test reads an unresolved schema as resolved and says nothing while
-      `compile` is about to refuse `summary` as an unknown input — measured on
-      a real run that then fell back to the generic `insert-record`.
-    - `_declared_parents` reads the registry's api-type ObjectActions, which is
-      empty for that operation.
-
-    Order is the declaration's, which is also the resolution order (a Jira
-    issue-type id is valid only inside its project).
-    """
-    names: list[str] = []
-    try:
-        with open(os.path.join(out_dir, "index.json")) as index_file:
-            entries = json.load(index_file)["entries"]
-        for index_entry in entries:
-            if index_entry["nodeType"] != node_type:
-                continue
-            if object_name is not None and index_entry.get("objectName") != object_name:
-                continue
-            with open(os.path.join(out_dir, index_entry["path"])) as entry_file:
-                descriptor = json.load(entry_file)
-            action = ((descriptor.get("operation") or {}).get("schemaAction")) or {}
-            for name in action.get("parents") or []:
-                if name and name not in names:
-                    names.append(name)
-    except (OSError, KeyError, TypeError, ValueError):
-        return []
-    return names
-
-
-def _keep_prepared_schema(
-    args, node_type: str, staged: str, parent_fields: dict[str, str],
-) -> tuple[int, int] | None:
-    """`(kept, discarded)` when this run must not overwrite the overlay, else `None`.
-
-    `--resolve` records a lookup; `-f` supplies the value a schema action reads.
-    A run carrying only the former cannot have run the action, so what it has to
-    write is the UNRESOLVED entry — and `merge_into` replaces by variant key, so
-    it lands on top of a schema an earlier `-f` run resolved. Measured on Jira
-    `create-issue`: 21 fields down to 3, taking the live-only `fields.reporter.id`
-    and `fields.summary` out of `required` with it, after which `compile` accepts
-    a flow it had been refusing (#666).
-
-    The loop that provokes it is the documented one. `check` prints
-    `prepare … --resolve <field>:<by>=<value>` for every unresolved lookup, with
-    no `-f`, so an author who prepares with `-f`, authors against the live schema
-    and then does what `check` says destroys the schema they just authored
-    against. #685 made that run say so; it still wrote.
-
-    Three conditions, all necessary:
-
-    * the EXISTING overlay declares `schemaAction.parents` — read from
-      `args.out` before the merge, so this is the entry about to be replaced;
-    * none of those parents arrived as `-f`, which is what makes "the action did
-      not run" a fact about the inputs rather than a guess about the result;
-    * the staged entry has FEWER input fields than the one on disk.
-
-    The third keeps this a strict no-loss rule rather than a blanket skip: equal
-    or richer still merges, so a re-pulled library's fresher entry is never
-    pinned by a stale overlay, and a first `--resolve` on an operation with no
-    overlay writes normally (`_count_input_fields` answers `None`).
-    """
-    parents = _schema_action_parents(args.out, node_type, args.object)
-    if not parents or any(name in parent_fields for name in parents):
-        return None
-    existing = _count_input_fields(args.out, node_type, args.object)
-    incoming = _count_input_fields(staged, node_type, args.object)
-    if existing is None or incoming is None or existing <= incoming:
-        return None
-    return existing, incoming
-
-
-def _parent_fields(
-    out_dir: str, node_type: str, object_name: str | None = None
-) -> tuple[list[str], bool]:
-    """`(parent field names, whether the prepared schema is parent-ONLY)`.
-
-    A reference `path` carrying a `{placeholder}` is the declaration that an
-    operation is parent-driven: `"/project/{fields.project.key}/issuetypes"` on
-    `fields.issuetype.id` names the field whose value must be resolved first,
-    and so also fixes the resolution ORDER. (Only `path` is scanned;
-    `filterPattern` carries an unrelated `{filter}` template.)
-
-    The parent set is both halves of that relation — the placeholder names AND
-    the fields that declare them — because both must be passed as `-f`.
-    Reporting only the placeholders would name `fields.project.key` and omit
-    `fields.issuetype.id`, the very field that declared it.
-
-    "Parent-only" then means every prepared field is a parent: the describe gave
-    back nothing but the inputs that select the real schema. That is the
-    expected shape with no `-f`, and a silent failure WITH `-f` — values that do
-    not exist on the connection are accepted and resolve to exactly this.
-    A resolved schema keeps its parents (Jira's 19 still include both), so
-    subset-of-parents is the discriminator, not the presence of a placeholder.
-    """
-    names: list[str] = []
-    placeholders: set[str] = set()
-    declaring: set[str] = set()
-    try:
-        with open(os.path.join(out_dir, "index.json")) as index_file:
-            entries = json.load(index_file)["entries"]
-        for index_entry in entries:
-            if index_entry["nodeType"] != node_type:
-                continue
-            if object_name is not None and index_entry.get("objectName") != object_name:
-                continue
-            with open(os.path.join(out_dir, index_entry["path"])) as entry_file:
-                descriptor = json.load(entry_file)
-            for field in descriptor.get("inputSchema", {}).get("fields", []) or []:
-                name = field.get("name")
-                if name and name not in names:
-                    names.append(name)
-                path = ((field.get("reference") or {}).get("path")) or ""
-                found = re.findall(r"\{([^{}]+)\}", path)
-                if found:
-                    placeholders.update(found)
-                    if name:
-                        declaring.add(name)
-    except (OSError, KeyError, TypeError, ValueError):
-        return [], False
-
-    parents = placeholders | declaring
-    if not parents:
-        return [], False
-    ordered = [name for name in names if name in parents]
-    ordered += sorted(parents - set(ordered))
-    return ordered, set(names) <= parents
-
-
-def _parse_fields(pairs: list[str]) -> dict[str, str]:
-    """`['a=1', 'b=2']` → `{'a': '1', 'b': '2'}`, rejecting a missing `=`.
-
-    Values may themselves contain `=` (a Salesforce SOQL body token), so split
-    on the FIRST separator only.
-    """
-    parsed: dict[str, str] = {}
-    for pair in pairs:
-        name, sep, value = pair.partition("=")
-        if not sep or not name.strip():
-            sys.exit(
-                f"prepare-connector: --field expects NAME=VALUE, got {pair!r}."
-            )
-        parsed[name.strip()] = value
-    return parsed
-
-
-def _rejected_parent_fields_message(
-    pairs: list[str], failures: list[tuple] | None = None
-) -> str:
-    """Diagnose a rejected parent-field set, preserving the CLI's own message.
-
-    An incomplete or invalid set is refused outright — "No api-type ObjectAction
-    matched for fields [...] on operation 'Create'" — which already names the
-    fields it could not match. That message never reaches the caller on its own:
-    `is_describe_operation` maps the failure to `None` and enrichment falls back
-    to the registry-declared fields, so the overlay is written as though nothing
-    went wrong. Fail here, and quote the service.
-    """
-    given = ", ".join(pairs)
-    detail = ""
-    for failure in failures or []:
-        message = failure[-1]
-        if message:
-            detail = f" The service said: {message}"
-            break
-    return (
-        f"prepare-connector: 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."
-    )
-
-
-def _input_field_note(count: int | None) -> str:
-    return (
-        f"{count} input field(s)"
-        if count is not None
-        else "input fields: <unavailable>"
-    )
-
-
-if __name__ == "__main__":
-    main()