@uipath/maestro-builder-sdk 5.2.0

package/dist/generators/_events.py

@@ -0,0 +1,355 @@
+#!/usr/bin/env python3
+"""Deterministic discovery for connector EVENTS — triggers and mid-flow waits.
+
+The activities pipeline resolves a connector operation's schema through
+`uip is resources list`/`describe`. Events have their own twin pair —
+`uip is triggers objects` / `uip is triggers describe` — plus the product
+registry's node manifest (`uip maestro flow registry get`, which for trigger
+node types REFUSES to answer without a live `--connection-id`, and which
+mirrors the describe sections when it does).
+
+Two shapes matter here and they are deliberately kept apart:
+
+- `triggers objects` answers PER EVENT OBJECT: the object catalog a generic
+  event ranges over, and per object the facts that change how a subscription
+  must be prepared (`ByoaConnection`, `IsWebhookUrlVisible`) and the
+  `Parameters` the object contributes to the input set.
+- `triggers describe` answers PER (event, object): `EventParameters`,
+  `FilterFields`, `OutputFields`.
+
+The V1 skill's source-of-truth contract is preserved verbatim: the complete
+event-input set is the UNION of `objects → Parameters` and
+`describe → EventParameters`, required if EITHER side says required. A field
+can appear in one and not the other (measured in the V1 corpus: required
+fields present only in describe), so neither call alone is trusted.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+__all__ = [
+    "EventDiscoveryError",
+    "triggers_objects",
+    "triggers_describe",
+    "camel_fields",
+    "normalize_bucket_fields",
+    "union_event_parameters",
+    "merge_describe_into_node",
+    "event_facts",
+]
+
+# `Parameters[].type` on a `triggers objects` row routes the value into one of
+# three `--detail` buckets at emit time. Everything unrecognized is an event
+# parameter — that is the designer's own fallback, and inventing a fourth
+# bucket here would emit a detail key the validator refuses.
+_BUCKETS = {"query": "query", "path": "path"}
+
+
+class EventDiscoveryError(Exception):
+    """A trigger metadata call failed, with the reason and the way forward."""
+
+
+def _run_json(command: list[str]) -> dict:
+    result = subprocess.run(command, capture_output=True, text=True)
+    try:
+        payload = json.loads(result.stdout)
+    except ValueError:
+        raise EventDiscoveryError(
+            f"`{' '.join(command[:5])} …` did not answer JSON: "
+            f"{(result.stderr or result.stdout).strip()[:300] or 'no output'}"
+        )
+    if payload.get("Result") != "Success":
+        raise EventDiscoveryError(
+            f"`{' '.join(command[:5])} …` failed: "
+            f"{payload.get('Message') or payload.get('Result')}"
+        )
+    return payload
+
+
+def triggers_objects(
+    key: str, operation: str, connection_id: str | None = None,
+) -> list[dict]:
+    """The event objects for `(connector, operation)`, PascalCase rows.
+
+    Rows carry `Name`/`DisplayName` (the same identity pair the activities
+    object ladder matches on) and, where the connector declares them,
+    `ByoaConnection`, `IsWebhookUrlVisible` and `Parameters`. Connectors that
+    declare none simply omit the keys (measured: sfdc's 1,178 CREATED rows
+    carry neither), so every reader treats them as optional.
+
+    `connection_id` is OPTIONAL, and what omitting it means depends on the
+    connector's object discovery. A connector whose objects do not come from
+    the connection answers identically either way (outlook `CREATED`:
+    Message + Calendar, with and without), which is what lets generation bake
+    those objects with no credentials at all. One whose objects DO come from
+    the connection answers with its declared set instead of the tenant's
+    (sfdc `CREATED`: 4 offline, 1,178 against a connection) — so a caller that
+    needs the tenant's objects must pass the id.
+    """
+    command = ["uip", "is", "triggers", "objects", key, operation]
+    if connection_id:
+        command += ["--connection-id", connection_id]
+    payload = _run_json(command + ["--output", "json"])
+    data = payload.get("Data")
+    if isinstance(data, dict):
+        data = data.get("items")
+    return data if isinstance(data, list) else []
+
+
+def triggers_describe(
+    key: str, operation: str, object_name: str,
+    connection_id: str | None = None,
+) -> dict:
+    """`EventParameters` / `FilterFields` / `OutputFields` for one object.
+
+    This call takes no node type — connector, operation and object only — so
+    it answers for the EVENT rather than for either of the two node forms the
+    platform ships it as. That is why both forms carry the same schema, and
+    why the product registry's per-node copy is a mirror of this: a lossy one,
+    measured on outlook `email-received` at 14 filter fields to this call's 15.
+
+    `connection_id` is optional here too; see `triggers_objects` for what
+    omitting it costs on a connector whose objects come from the connection.
+    """
+    command = ["uip", "is", "triggers", "describe", key, operation, object_name]
+    if connection_id:
+        command += ["--connection-id", connection_id]
+    payload = _run_json(command + ["--output", "json"])
+    return payload.get("Data") or {}
+
+
+def _camelize(value):
+    """Lower-case the first letter of every key, recursively.
+
+    `triggers describe` answers PascalCase all the way down, including the
+    `Reference` block: `{ObjectName, LookupNames, LookupValue, Path}`. Every
+    consumer of a reference — the lookup-spec generator, the `--resolve`
+    executor, the markdown — reads the registry's camelCase spelling, so a
+    verbatim copy is invisible to all of them: the field simply stops having
+    a lookup. One shape leaves this module, and this is what makes it one.
+    """
+    if isinstance(value, dict):
+        return {
+            (k[0].lower() + k[1:] if k[:1].isupper() else k): _camelize(v)
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [_camelize(v) for v in value]
+    return value
+
+
+def _is_hidden(low: dict) -> bool:
+    """True for a hidden parameter that is safe to DROP — hidden and optional.
+
+    Outlook's `sharedMailboxAddress` is `Design.IsHidden: true` and optional:
+    a transport detail of the subscription, not something an author fills in,
+    so counting it would advertise a second field on an event whose only real
+    parameter is the mail folder.
+
+    A hidden parameter that is REQUIRED is a different animal and is kept
+    (flagged `hidden`, see `_keep_hidden_marker`). Asana's `parent` and
+    `projectId` are both — path-bucket, required, hidden — and dropping a
+    value the subscription needs at dispatch is exactly the silent wrongness
+    this design exists to remove. Keeping it flagged loses nothing: a surface
+    that should not prompt for it can read the flag, while nothing can lose
+    it by accident.
+    """
+    design = low.get("design") or {}
+    if not isinstance(design, dict):
+        return False
+    # Only the TOP-level keys are lowered by the callers, so the nested block
+    # still reads `{"IsHidden": true}`. Camelize it before asking.
+    design = _camelize(design)
+    hidden = bool(design.get("isHidden") or design.get("hidden"))
+    return hidden and not low.get("required")
+
+
+def _keep_hidden_marker(low: dict, field: dict) -> dict:
+    """Flag a kept parameter the designer hides (necessarily a required one)."""
+    design = _camelize(low.get("design") or {})
+    if isinstance(design, dict) and (design.get("isHidden") or design.get("hidden")):
+        field["hidden"] = True
+    return field
+
+
+def _with_cascade(fields: list[dict]) -> list[dict]:
+    """Mark each parameter that another one has to resolve before it.
+
+    Jira's `issuetype` reference is `/project/{project}/issuetypes` — the
+    cascade is written into the path, as a placeholder naming the parameter it
+    needs. That is the same encoding `_order_by_dependency` reads for an
+    activity's parent fields, and `_resolve.order_resolutions` already honours
+    `dependsOn`, so recording it here is what makes `prepare` resolve
+    `project` first without being told to.
+    """
+    names = {f.get("name") for f in fields}
+    for field in fields:
+        reference = field.get("reference") or {}
+        path = str(reference.get("path") or "")
+        explicit = list(reference.get("dependsOn") or [])
+        depends = sorted(
+            other for other in names
+            if other and other != field.get("name")
+            and ("{" + str(other) + "}" in path or other in explicit)
+        )
+        if depends:
+            field["dependsOn"] = depends
+            reference.setdefault("dependsOn", depends)
+    # Designer order where the connector states one, so a cascade reads
+    # parent-first in every listing rather than in dict order.
+    fields.sort(key=lambda f: (f.get("sortOrder") is None, f.get("sortOrder") or 0))
+    return fields
+
+
+def camel_fields(fields: list | None) -> list[dict]:
+    """Describe/objects fields normalized to the registry's camelCase shape.
+
+    `triggers describe` answers PascalCase (`Name`/`Type`/`DisplayName`);
+    the registry definition — and everything downstream that reads a v1def —
+    is camelCase. One shape leaves this module.
+    """
+    out = []
+    for f in fields or []:
+        if not isinstance(f, dict):
+            continue
+        low = {k[0].lower() + k[1:] if k[:1].isupper() else k: v
+               for k, v in f.items()}
+        name = low.get("name")
+        if not name:
+            continue
+        if _is_hidden(low):
+            continue
+        field = {"name": name}
+        for k in ("displayName", "description", "required", "dataType",
+                  "sortOrder"):
+            if low.get(k) is not None:
+                field[k] = low[k]
+        if low.get("reference") is not None:
+            field["reference"] = _camelize(low["reference"])
+        _keep_hidden_marker(low, field)
+        # Describe's `Type` is the DATA type; an objects-row Parameter's
+        # `type` is the BUCKET. The caller that knows which source it read
+        # passes bucketed fields through `normalize_bucket_fields` instead.
+        if low.get("type") is not None and "dataType" not in field:
+            field["type"] = low["type"]
+            field["dataType"] = low["type"]
+        elif "dataType" in field:
+            field["type"] = field["dataType"]
+        out.append(field)
+    return out
+
+
+def normalize_bucket_fields(parameters: list | None) -> list[dict]:
+    """`triggers objects → Parameters[]` rows, camelCase, bucket made explicit.
+
+    On these rows `type` selects the emit-time detail bucket (`query` →
+    `queryParameters`, `path` → `pathParameters`, anything else → event
+    parameters) and `dataType` is the value type — the OPPOSITE reading of
+    `type` from every other field list, which is exactly the kind of
+    quiet trap this normalization exists to bury.
+    """
+    out = []
+    for f in parameters or []:
+        if not isinstance(f, dict):
+            continue
+        low = {k[0].lower() + k[1:] if k[:1].isupper() else k: v
+               for k, v in f.items()}
+        name = low.get("name")
+        if not name:
+            continue
+        if _is_hidden(low):
+            continue
+        field = {"name": name,
+                 "bucket": _BUCKETS.get(str(low.get("type") or "").lower(), "event")}
+        for k in ("displayName", "description", "required", "sortOrder"):
+            if low.get(k) is not None:
+                field[k] = low[k]
+        if low.get("reference") is not None:
+            field["reference"] = _camelize(low["reference"])
+        data_type = low.get("dataType") or "string"
+        field["type"] = data_type
+        field["dataType"] = data_type
+        _keep_hidden_marker(low, field)
+        out.append(field)
+    return out
+
+
+def union_event_parameters(
+    declared: list | None, object_parameters: list | None,
+) -> list[dict]:
+    """The V1 union rule: describe's EventParameters ∪ the object row's Parameters.
+
+    Deduped by name; `required` is an OR — a field required on either side is
+    required, because each side is authoritative for fields the other omits.
+    The object row's bucket survives the merge; a field only describe knows
+    is an event parameter by definition.
+    """
+    merged: dict[str, dict] = {}
+    for field in camel_fields(declared):
+        field.setdefault("bucket", "event")
+        merged[field["name"]] = field
+    for field in normalize_bucket_fields(object_parameters):
+        existing = merged.get(field["name"])
+        if existing is None:
+            merged[field["name"]] = field
+            continue
+        existing["required"] = bool(existing.get("required")) or bool(field.get("required"))
+        existing["bucket"] = field["bucket"]
+        for k in ("displayName", "description", "reference", "sortOrder"):
+            if field.get(k) is not None and existing.get(k) is None:
+                existing[k] = field[k]
+    return _with_cascade(list(merged.values()))
+
+
+def merge_describe_into_node(
+    node: dict, describe: dict, object_parameters: list | None = None,
+) -> dict:
+    """Fold a `triggers describe` answer into a registry trigger definition.
+
+    The registry definition IS the v1def the overlay ships, and
+    `Library.eventParameterFields` already reads `v1def.eventParameters.fields`
+    — so the deterministic store is "the definition, with the describe
+    sections made true for this object" rather than a new format.
+    """
+    node = dict(node)
+    node["eventParameters"] = {"fields": union_event_parameters(
+        describe.get("EventParameters"), object_parameters,
+    )}
+    node["filterFields"] = {"fields": camel_fields(describe.get("FilterFields"))}
+    if describe.get("OutputFields"):
+        node["outputResponseDefinition"] = {
+            "fields": camel_fields(describe.get("OutputFields"))}
+    for src, dst in (("EventMode", "eventMode"),
+                     ("ByoaConnection", "byoaConnection"),
+                     ("IsWebhookUrlVisible", "isWebhookUrlVisible")):
+        if describe.get(src) is not None:
+            node[dst] = describe[src]
+    return node
+
+
+def event_facts(node: dict, object_row: dict | None) -> dict:
+    """The three facts that change how a subscription is prepared or tested.
+
+    Per-object answers (the `triggers objects` row, or a describe) win over
+    the definition's: `byoaConnection` and `isWebhookUrlVisible` are declared
+    PER EVENT OBJECT, not per connector — V1 measured connectors requiring
+    BYOA for some events and not others.
+    """
+    row = object_row or {}
+    def _fact(row_key: str, node_key: str, default):
+        if row.get(row_key) is not None:
+            return row[row_key]
+        if node.get(node_key) is not None:
+            return node[node_key]
+        return default
+    return {
+        "eventMode": str(node.get("eventMode") or "polling"),
+        "byoaConnection": bool(_fact("ByoaConnection", "byoaConnection", False)),
+        "isWebhookUrlVisible": bool(_fact("IsWebhookUrlVisible", "isWebhookUrlVisible", False)),
+        "textBlocks": [
+            str(t) for t in ((row.get("Design") or {}).get("TextBlocks") or
+                             (row.get("design") or {}).get("textBlocks") or [])
+        ],
+    }

package/dist/generators/_lookups.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Classify a connector input field's `reference` block, for both generators.
+
+A `reference` with a `lookupValue` says a field's value is an opaque id that has
+to be resolved against a live connection. 1,365 input fields across the shipped
+library carry one. But not all of them are asking for a resolution, and
+generating a `.by*` helper for the ones that are not is actively harmful: a
+helper that shows up where it is not needed teaches a reader that the helper is
+noise, and then it is ignored on the fields that need it.
+
+Two classes are excluded, and they are excluded for different reasons.
+
+IDENTITY LOOKUPS (231 fields). `lookupValue` is the only entry in `lookupNames`,
+so the "resolution" is the identity function: call the API, match
+`label == 'Qualified'`, send back `'Qualified'`. Nothing is translated — the
+block enumerates legal values rather than mapping a name to an id. Detected
+mechanically here.
+
+INVARIANT COLLECTIONS (164 fields). The collection is a property of the
+CONNECTOR's API rather than of the CONNECTION — a country list is identical in
+every tenant — so the id cannot go stale on a move and resolving late buys
+nothing. NOT detectable from the metadata: `system_countries -> name` and
+`Users -> id` are structurally identical. Read from a curated ledger instead;
+see `invariant-collections.json` for why that ledger is closed at three rows.
+
+The fallback direction is deliberate and is the safe one. An unclassified field
+is treated as an ordinary lookup, which is never *wrong* — only occasionally
+ceremonial. The opposite default would drop the helper from a genuinely
+connection-scoped field and hand the author back the silent-wrongness failure
+the whole mechanism exists to remove.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+__all__ = [
+    "LEDGER_FILENAME",
+    "load_invariant_collections",
+    "reference_of",
+    "is_identity_lookup",
+    "classify",
+    "resolvable_lookup_fields",
+]
+
+LEDGER_FILENAME = "invariant-collections.json"
+
+
+def load_invariant_collections(library_dir: str | Path | None) -> set[str]:
+    """The ledger's `objectName` set, or an empty set.
+
+    An absent or malformed ledger reads as EMPTY rather than raising, which
+    matches `loadListEnvelopes` in the SDK and is the same reasoning: the
+    permissive path is the pre-ledger behaviour, so the worst case of a bad edit
+    is losing the exactness, never breaking a build.
+    """
+    if not library_dir:
+        return set()
+    path = Path(library_dir) / LEDGER_FILENAME
+    if not path.is_file():
+        return set()
+    try:
+        with path.open(encoding="utf-8") as fh:
+            parsed = json.load(fh)
+    except (OSError, ValueError):
+        return set()
+    rows = parsed.get("collections")
+    if not isinstance(rows, list):
+        return set()
+    return {
+        row["objectName"] for row in rows
+        if isinstance(row, dict) and isinstance(row.get("objectName"), str)
+    }
+
+
+def reference_of(field: dict) -> dict | None:
+    """The field's `reference` block when it declares a resolvable value."""
+    reference = field.get("reference")
+    if not isinstance(reference, dict):
+        return None
+    if not reference.get("lookupValue"):
+        return None
+    return reference
+
+
+def is_identity_lookup(reference: dict) -> bool:
+    """True when resolving would return the value it was given."""
+    names = reference.get("lookupNames") or []
+    return len(names) == 1 and reference.get("lookupValue") in names
+
+
+def classify(field: dict, invariant: set[str]) -> str:
+    """One of `'none'`, `'identity'`, `'invariant'`, `'lookup'`.
+
+    Only `'lookup'` earns a helper and a `--resolve`. The two degenerate classes
+    are reported distinctly rather than merged because the markdown treats them
+    differently: an identity lookup keeps its enumeration command (its legal
+    values exist nowhere offline), while an invariant one is just a value the
+    author already knows how to write.
+    """
+    reference = reference_of(field)
+    if reference is None:
+        return "none"
+    if is_identity_lookup(reference):
+        return "identity"
+    if reference.get("objectName") in invariant:
+        return "invariant"
+    return "lookup"
+
+
+def resolvable_lookup_fields(fields: list[dict], invariant: set[str]) -> list[dict]:
+    """The subset of `fields` that earns a `.by*` helper, in declaration order."""
+    return [f for f in fields if classify(f, invariant) == "lookup"]

package/dist/generators/_naming.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Symbol-name derivation shared by the two library generators.
+
+`library-json/` feeds two derived views (see `lib/scripts/unpack-library.sh`):
+`generate_connectors_ts.py` emits the TypeScript descriptors an author imports,
+and `convert_library_to_md.py` emits the markdown an agent reads. The markdown
+now cites the TypeScript **by name** — `connector(SendMessageToUser, …)`,
+`.byEmail(…)` — and neither name exists anywhere in the JSON. Both are derived.
+
+That makes the derivation a shared contract rather than a private detail, and
+the failure mode of re-deriving it twice is the worst one available: a wrong
+*description* costs a reader one re-read, but a wrong *symbol* is an import that
+throws, printed by documentation, for a helper the reader was being told to
+prefer over a route that already worked. They will not try the helper again.
+
+So both generators import this module and neither owns a copy. The de-collision
+loop especially cannot be duplicated even in principle — it is stateful across a
+whole connector module, so a per-page re-derivation has no way to know that the
+name it is about to print was already taken by an earlier operation.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "pascal",
+    "singular",
+    "op_identity",
+    "op_symbol_name",
+    "symbol_index",
+    "by_alias",
+    "by_aliases",
+]
+
+
+def pascal(action_id: str) -> str:
+    """`send-message-to-user` -> `SendMessageToUser`."""
+    return "".join(
+        w[:1].upper() + w[1:] for w in re.split(r"[^A-Za-z0-9]+", action_id) if w
+    ) or "Op"
+
+
+def singular(name: str) -> str:
+    """Small deterministic singularizer for array field names used as type names."""
+    if name.lower().endswith("ies") and len(name) > 3:
+        return name[:-3] + "y"
+    if name.lower().endswith("sses"):
+        return name[:-2]
+    if name.lower().endswith("s") and not name.lower().endswith(("ss", "us")):
+        return name[:-1]
+    return name
+
+
+def op_identity(entry: dict) -> tuple[str, str, str]:
+    """`(nodeType, activityType, label)` from either entry shape.
+
+    The same operation is described by two different JSON shapes: `index.json`
+    rows are flat (`activityType`, `label` at the top level) while the per-op
+    entry files nest them (`operation.activityType`, `display.label`). The
+    descriptor generator reads the nested one and the markdown generator walks
+    the flat one, so a naming helper that accepted only one of them would push
+    the caller into re-deriving the other — which is the drift this module
+    exists to prevent.
+    """
+    node_type = entry.get("nodeType") or ""
+    operation = entry.get("operation")
+    if isinstance(operation, dict):
+        activity_type = operation.get("activityType") or ""
+    else:
+        activity_type = entry.get("activityType") or ""
+    display = entry.get("display")
+    if isinstance(display, dict) and display.get("label"):
+        label = display["label"]
+    else:
+        label = entry.get("label") or ""
+    if not label:
+        label = node_type.rsplit(".", 1)[-1]
+    return node_type, activity_type, label
+
+
+def op_symbol_name(entry: dict, seen: set[str]) -> str:
+    """The exported const name for one operation, de-collided within its module.
+
+    `seen` is the per-connector-module set of names already emitted, and it is
+    MUTATED here — that is the whole point of centralising this. A module emits
+    its operations in index order, so two operations whose labels pascal to the
+    same symbol are distinguished by a trailing `_` on the later one, and which
+    one gets the underscore depends on the order the caller walks the entries in.
+    Both generators must therefore walk in the same order and share this set.
+
+    A `GenericExpanded` entry is named from its display label rather than its
+    action id, because its action id is the shared generic verb (`create`,
+    `list-all-records`) and would collide for every object the generic covers.
+    """
+    node_type, activity_type, label = op_identity(entry)
+    action_id = node_type.rsplit(".", 1)[-1]
+    name = pascal(label if activity_type == "GenericExpanded" else action_id)
+    while name in seen:
+        name += "_"
+    seen.add(name)
+    return name
+
+
+def symbol_index(
+    entries: list[dict], include_generic_expanded: bool = False
+) -> dict[str, str]:
+    """`{nodeType: exportedConstName}` for every operation a module will export.
+
+    THE reason this exists. The descriptor generator groups entries by connector
+    and walks each group sorted by `nodeType`; the markdown generator walks
+    `index.json` in its own order, one operation at a time, and never groups. The
+    de-collision loop is stateful, so those two walks assign DIFFERENT names the
+    moment any connector has two operations whose labels collide — and the
+    markdown would then print an import that does not resolve.
+
+    Computing the map once, here, from the same grouping both must agree on, is
+    what makes that impossible rather than merely unlikely.
+
+    An operation with no entry in the returned map has no generated descriptor
+    (a `GenericExpanded` one, by default) and must be authored through the
+    library by key/action/object instead.
+    """
+    by_connector: dict[str, list[dict]] = {}
+    for entry in entries:
+        node_type, activity_type, _ = op_identity(entry)
+        if activity_type == "GenericExpanded" and not include_generic_expanded:
+            continue
+        key = entry.get("connectorKey")
+        if not key:
+            # `uipath.connector.<key>.<action>` — the only other place the key lives.
+            rest = node_type.replace("uipath.connector.", "")
+            key = rest.rsplit(".", 1)[0] if "." in rest else rest
+        by_connector.setdefault(key, []).append(entry)
+
+    names: dict[str, str] = {}
+    for _key, group in sorted(by_connector.items()):
+        seen: set[str] = set()
+        for entry in sorted(group, key=lambda e: e.get("nodeType") or ""):
+            names[entry["nodeType"]] = op_symbol_name(entry, seen)
+    return names
+
+
+def by_alias(lookup_name: str) -> str:
+    """`profile.email` -> `byEmail`; `profile.real_name` -> `byRealName`.
+
+    Only the LAST dotted segment is used. The leading path is where the value
+    lives in the vendor's record, which is a fact about their API rather than
+    about what the author is searching by — `byProfileEmail` would be noise, and
+    the generic `.by('profile.email', v)` is always available for the exact form.
+    """
+    last = lookup_name.rsplit(".", 1)[-1]
+    words = [w for w in re.split(r"[^A-Za-z0-9]+", last) if w]
+    if not words:
+        return ""
+    head, *rest = words
+    return "by" + head[:1].upper() + head[1:] + "".join(
+        w[:1].upper() + w[1:] for w in rest
+    )
+
+
+def by_aliases(lookup_names: list[str]) -> dict[str, str]:
+    """`{lookupName: alias}` for every name that earns an unambiguous alias.
+
+    Two `lookupNames` can camelise to one alias — `email` and `contact.email`
+    both give `byEmail` — and there is no non-arbitrary way to award it to one of
+    them. Rather than guess, BOTH are dropped from the alias map and reachable
+    only through the generic `.by(name, value)`. Silently binding `byEmail` to
+    whichever came first in the array would compile, run, and search the wrong
+    field, which is precisely the class of quiet wrongness the lookup surface
+    exists to remove.
+
+    An empty return is normal and means "generic form only".
+    """
+    counts: dict[str, int] = {}
+    for name in lookup_names:
+        alias = by_alias(name)
+        if alias:
+            counts[alias] = counts.get(alias, 0) + 1
+    out: dict[str, str] = {}
+    for name in lookup_names:
+        alias = by_alias(name)
+        if alias and counts[alias] == 1:
+            out[name] = alias
+    return out