@uipath/maestro-builder-sdk 5.2.0

package/dist/core/library.js

@@ -0,0 +1,1183 @@
+/**
+ * library — resolve Integration Service connector definitions from the on-disk
+ * connector library cache (the same `library-json` the Flow Code arm uses).
+ *
+ * For a connector action we need two files per action:
+ *   <key>/<action>@<ver>.json        the entry (connector key, HTTP method, endpoint)
+ *   <key>/<action>@<ver>.v1def.json  the Flow `definitions[]` shape (model, ports, …)
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadListEnvelopes, lookupListEnvelope } from './list-envelope.js';
+import { lookupSpecOf } from './lookups.js';
+import { loadInvariantCollections, loadLookupResolutions } from './lookup-store.js';
+export class Library {
+    layers = [];
+    /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */
+    envelopeRows = [];
+    /**
+     * Everything `prepare --resolve` has recorded, from the overlay only.
+     *
+     * Never from the baked library: a resolution is a fact about ONE tenant's
+     * data, so shipping one in the published archive would hand every consumer an
+     * id from someone else's connection.
+     */
+    lookupResolutions;
+    /** Collections the ledger declares connector-invariant; overlay unions over baked. */
+    invariantCollections;
+    constructor(dir, opts = {}) {
+        this.lookupResolutions = loadLookupResolutions(opts.overlayDir);
+        this.invariantCollections = new Set([
+            ...loadInvariantCollections(dir),
+            ...loadInvariantCollections(opts.overlayDir),
+        ]);
+        // Overlay first (local wins), then the baked library.
+        if (opts.overlayDir) {
+            const oidx = join(opts.overlayDir, 'index.json');
+            if (existsSync(oidx))
+                this.layers.push({ dir: opts.overlayDir, entries: JSON.parse(readFileSync(oidx, 'utf8')).entries ?? [], overlay: true });
+            this.envelopeRows.push(...loadListEnvelopes(opts.overlayDir));
+        }
+        this.envelopeRows.push(...loadListEnvelopes(dir));
+        const idx = join(dir, 'index.json');
+        if (!existsSync(idx))
+            throw new Error(`connector library not found at ${idx}. Build it first (uipath-flow-v2-setup-library) ` +
+                `or point --library / $FLOW_SDK_LIBRARY_JSON at a library-json dir.`);
+        this.layers.push({ dir, entries: JSON.parse(readFileSync(idx, 'utf8')).entries ?? [] });
+    }
+    /**
+     * Resolve a connector ACTION (`uipath.connector.<key>.<action>`).
+     *
+     * `objectName` picks WHICH object a **generic** operation addresses; see
+     * {@link Library.resolveType} for what happens when it is omitted on a
+     * nodeType that needs it, and when it names an object the library has never
+     * heard of.
+     *
+     * The event family lives under two sibling namespaces and is resolved by
+     * `resolveEvent` below — same files, same sidecar convention, different
+     * position in the flow.
+     */
+    /**
+     * One operation's resolvable lookup fields, keyed by the WIRE field name.
+     *
+     * The same set the descriptor generator emits helpers for, decided by the same
+     * rules ({@link lookupSpecOf}) over the same field vocabulary — so a `check`
+     * diagnostic can never name a `.by*` the generator did not write.
+     *
+     * @param key - Connector library key.
+     * @param action - Operation id.
+     * @param version - Pin an operation version; newest otherwise.
+     * @param objectName - The object a generic operation addresses.
+     * @returns `{ field: spec }`, empty when the operation has no resolvable lookups.
+     */
+    lookupSpecs(key, action, version, objectName) {
+        let resolved;
+        try {
+            resolved = this.resolve(key, action, version, objectName);
+        }
+        catch {
+            return {};
+        }
+        const out = {};
+        for (const field of resolved.fields) {
+            const spec = lookupSpecOf(field.reference, this.invariantCollections);
+            if (spec)
+                out[field.name] = spec;
+        }
+        return out;
+    }
+    resolve(key, action, version, objectName) {
+        return this.resolveType(`uipath.connector.${key}.${action}`, version, objectName);
+    }
+    /**
+     * Whether a connector step's schema is materialized locally — see
+     * {@link SchemaReadiness}. Index rows are enough for the `object` question
+     * (activityType + objectName travel on every row); the `customFields`
+     * question reads one canonical entry, because the discovery flags and
+     * `requiresConnectionForSchema` live there and nowhere thinner.
+     *
+     * `undefined` means "this library has never heard of the operation", which
+     * is a different answer from "unprepared": the caller fails open on it, the
+     * same rule every other check callback follows.
+     */
+    schemaReadiness(key, action, version, object) {
+        const nodeType = `uipath.connector.${key}.${action}`;
+        const rows = [];
+        for (const layer of this.layers) {
+            for (const row of layer.entries) {
+                if (row?.nodeType !== nodeType)
+                    continue;
+                if (version && String(row.version) !== version)
+                    continue;
+                rows.push({ row, dir: layer.dir, overlay: layer.overlay === true });
+            }
+        }
+        if (rows.length === 0)
+            return undefined;
+        const generic = rows.some(({ row }) => row.activityType === 'Generic'
+            || row.activityType === 'GenericExpanded'
+            || row.objectFromDiscovery === true);
+        if (object) {
+            // An explicit object on a curated op is compile's business, not owed work.
+            if (!generic)
+                return { kind: 'static', prepared: true };
+            if (rows.some(({ row }) => row.objectName === object)) {
+                return { kind: 'object', prepared: true };
+            }
+            const canonical = rows.find(({ row }) => typeof row.objectName === 'string' && row.objectName !== ''
+                && row.objectName.toLowerCase() === object.toLowerCase())?.row.objectName;
+            return {
+                kind: 'object',
+                prepared: false,
+                ...(canonical ? { canonical: String(canonical) } : {}),
+            };
+        }
+        // No object named. A Generic op without one is a different, existing
+        // failure (compile refuses it outright); nothing to add here.
+        if (generic)
+            return { kind: 'static', prepared: true };
+        // Curated: is the real field set connection-resolved? Decided FIRST, from
+        // the canonical entry, so `kind` is never a label of convenience — an
+        // overlay row alone used to earn `customFields` without anyone checking
+        // the op resolves anything, which was a lie waiting for a consumer that
+        // branches on kind. Read the baked layer's entry where one exists: a
+        // prepared overlay copy may not carry the discovery block.
+        let entry;
+        try {
+            const source = rows.find(({ overlay }) => !overlay) ?? rows[0];
+            entry = JSON.parse(readFileSync(join(source.dir, source.row.path), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+        const connectionResolved = entry?.runtime?.requiresConnectionForSchema === true
+            || entry?.connector?.discovery?.hasCustomFieldDiscovery === true;
+        if (!connectionResolved)
+            return { kind: 'static', prepared: true };
+        if (rows.some(({ overlay }) => overlay))
+            return { kind: 'customFields', prepared: true };
+        let bakedFields = [];
+        try {
+            bakedFields = this.resolve(key, action, version).fields.map((f) => f.name);
+        }
+        catch {
+            bakedFields = [];
+        }
+        return { kind: 'customFields', prepared: false, bakedFields };
+    }
+    /**
+     * Reverse a resolved connector activity back to the symbolic authoring key.
+     * Case decompile uses the same library that compile will use, so it never has
+     * to guess an action name from a display label.
+     */
+    identifyAction(wire) {
+        const prefix = `uipath.connector.${wire.connectorKey}.`;
+        for (const layer of this.layers) {
+            for (const indexed of layer.entries) {
+                if (indexed.connectorKey !== wire.connectorKey || !String(indexed.nodeType ?? '').startsWith(prefix))
+                    continue;
+                if (wire.version && indexed.version !== wire.version)
+                    continue;
+                const entry = JSON.parse(readFileSync(join(layer.dir, indexed.path), 'utf8'));
+                const operation = entry.operation ?? {};
+                if (wire.httpMethod && String(operation.httpMethod ?? '').toUpperCase() !== wire.httpMethod.toUpperCase())
+                    continue;
+                if (wire.endpoint && operation.path !== wire.endpoint)
+                    continue;
+                if (wire.objectName && operation.objectName !== wire.objectName)
+                    continue;
+                const siblings = layer.entries.filter((candidate) => candidate.nodeType === indexed.nodeType);
+                return {
+                    key: wire.connectorKey,
+                    action: String(indexed.nodeType).slice(prefix.length),
+                    version: String(indexed.version),
+                    ...(siblings.length > 1 && operation.objectName ? { object: String(operation.objectName) } : {}),
+                };
+            }
+        }
+        throw new Error(`connector activity not found in library: ${wire.connectorKey} ${wire.httpMethod ?? '?'} ${wire.endpoint ?? '?'}`);
+    }
+    /**
+     * Resolve a connector EVENT: the START trigger
+     * (`uipath.connector.trigger.<key>.<event>`, a bpmn:StartEvent — the flow
+     * begins when the event fires) or the mid-flow wait
+     * (`uipath.connector.event.<key>.<event>`, a bpmn:ReceiveTask — the flow pauses
+     * until it fires). The platform ships both for one connector operation, with
+     * the same `uiPathActivityTypeId`; the namespace is the only difference.
+     */
+    /**
+     * The connector's discovery classification, from whichever layer carries it.
+     *
+     * `resolveType` takes METADATA from the highest-priority layer, and a
+     * `prepare-connector` overlay writes `connector: { key }` with no
+     * `discovery` block — and a `runtime.requiresConnectionForSchema: false`
+     * that CONTRADICTS the baked library (jira is `hasFieldDiscovery: true`
+     * there). So reading discovery off the resolved entry silently reclassifies
+     * every prepared connector as static, which is exactly backwards: preparing
+     * is what an author does on the connectors whose schema comes from the
+     * connection. Fields legitimately come from the overlay; this connector-level
+     * fact does not, so it is read across layers and the first real block wins.
+     */
+    connectorDiscovery(kind, key, event, objectName) {
+        const nodeType = `uipath.connector.${kind}.${key}.${event}`;
+        for (const layer of this.layers) {
+            const rc = this.resolveInLayer(layer, nodeType, undefined, objectName);
+            const discovery = rc?.entry
+                ?.connector?.discovery;
+            if (discovery && typeof discovery === 'object' && Object.keys(discovery).length) {
+                return discovery;
+            }
+        }
+        return {};
+    }
+    resolveEvent(kind, key, event, version, objectName) {
+        const nodeType = `uipath.connector.${kind}.${key}.${event}`;
+        let rc;
+        try {
+            rc = this.resolveType(nodeType, version, objectName);
+        }
+        catch (error) {
+            // The registry dump carries the WAIT form of every connector event and the
+            // START form of none (448 `.event.` entries, 0 `.trigger.`; only the curated
+            // overlay adds a handful of `.trigger.` pairs). The platform ships both for
+            // one operation and the namespace is the only difference, so the start form
+            // is DERIVED from its wait sibling here — measured against the platform's
+            // own `registry get` answers for both forms (see `deriveTriggerForm`).
+            if (kind !== 'trigger')
+                throw error;
+            let sibling;
+            try {
+                sibling = this.resolveType(`uipath.connector.event.${key}.${event}`, version, objectName);
+            }
+            catch {
+                throw error;
+            }
+            rc = deriveTriggerForm(sibling, nodeType);
+        }
+        return normalizeEventOperation(rc);
+    }
+    /**
+     * Reverse a resolved connector event payload back to its symbolic event name.
+     * Case decompile uses the same library that compile will use, mirroring
+     * {@link identifyAction} for connector activities.
+     */
+    identifyEvent(kind, wire) {
+        const prefix = `uipath.connector.${kind}.${wire.connectorKey}.`;
+        for (const layer of this.layers) {
+            for (const indexed of layer.entries) {
+                if (indexed.connectorKey !== wire.connectorKey || !String(indexed.nodeType ?? '').startsWith(prefix))
+                    continue;
+                if (wire.version && indexed.version !== wire.version)
+                    continue;
+                const entry = JSON.parse(readFileSync(join(layer.dir, indexed.path), 'utf8'));
+                const operation = normalizeEventOperation({ entry, v1def: readV1def(join(layer.dir, indexed.path)) }).entry.operation ?? {};
+                // A GENERIC event's entry names no object — the wire's object is the
+                // author's choice, so it identifies nothing here and comes back as `object`.
+                const generic = operation.activityType === 'GenericTrigger';
+                if (!generic && wire.objectName && operation.objectName !== wire.objectName)
+                    continue;
+                if (wire.eventOperation && operation.eventOperation !== wire.eventOperation)
+                    continue;
+                if (wire.eventMode && operation.eventMode !== wire.eventMode)
+                    continue;
+                return {
+                    key: wire.connectorKey,
+                    event: String(indexed.nodeType).slice(prefix.length),
+                    version: String(indexed.version),
+                    ...(generic && wire.objectName ? { object: wire.objectName } : {}),
+                };
+            }
+        }
+        throw new Error(`connector ${kind} event not found in library: ${wire.connectorKey} `
+            + `${wire.eventOperation ?? '?'} ${wire.objectName ?? '?'}`);
+    }
+    /**
+     * The EVENT PARAMETERS a connector event operation declares — the `where` half
+     * of a subscription — or `undefined` if the library has never heard of the
+     * operation.
+     *
+     * `{ known: true, names: [] }` and `undefined` are DIFFERENT answers, and the
+     * difference is the whole reason this method exists: "this operation takes no
+     * event parameters" is a fact (HTTP Webhook scopes by the connection, so its
+     * only correct `where` is `{}`), while "I could not look it up" is not. Reading
+     * an empty list as "none declared, so scope it anyway" is what made
+     * `EVENT_NO_SCOPE` reject correct authoring for four of the FIVE event
+     * OPERATIONS the deployed corpus contains.
+     *
+     * Two declaration sites, in order of authority:
+     *
+     *  1. the v1def's `eventParameters.fields` — the registry's OWN enrichment,
+     *     returned verbatim by `uip maestro flow registry get <trigger nodeType>
+     *     --connection-id <id>`. Present only on the `.trigger.` form (IS enriches
+     *     per node type, not per operation), so the pair is tried together;
+     *  2. the entry's `inputSchema.fields`, where a curated def declares them as
+     *     `eventParameters.<name>` alongside `filter.<name>` — PR 10's convention.
+     *
+     * Note this is the one family where `inputSchema.fields` IS authoritative. For
+     * connector ACTIONS it is a lossy third summary (`readFields`' doc comment: 5,243
+     * of 7,029 entries disagree with the union) — but both event node types ship
+     * `inputDefinition: {}` in every version, so there is no other declaration to
+     * disagree with, and the whole population is the curated overlay's four defs (the
+     * raw library snapshot carries ZERO trigger/event entries).
+     */
+    eventParameterFields(key, event, objectName) {
+        let resolved;
+        const declaredOnEitherForm = [];
+        const selectors = [];
+        let known = false;
+        for (const kind of ['event', 'trigger']) {
+            let rc;
+            try {
+                rc = this.resolveEvent(kind, key, event, undefined, objectName);
+            }
+            catch {
+                continue; // the sibling may exist even when this one does not
+            }
+            resolved = rc;
+            const fromV1def = rc.v1def
+                ?.eventParameters?.fields;
+            if (Array.isArray(fromV1def)) {
+                known = true;
+                for (const f of fromV1def) {
+                    if (typeof f?.name !== 'string' || f.name === '')
+                        continue;
+                    declaredOnEitherForm.push(f.name);
+                    // A REQUIRED parameter outside the event bucket selects the schema
+                    // rather than scoping the subscription — Jira's `project` and
+                    // `issuetype` (both required, query-bucket) are what the connector
+                    // derives an issue's filter and output fields FROM. `uip is triggers
+                    // describe` takes no parameter values, so a vocabulary fetched
+                    // without them is a baseline that the real one extends.
+                    if (f.required && (f.bucket === 'query' || f.bucket === 'path')) {
+                        selectors.push(f.name);
+                    }
+                }
+                continue;
+            }
+            const fromEntry = rc.entry
+                ?.inputSchema?.fields;
+            if (Array.isArray(fromEntry)) {
+                known = true;
+                for (const f of fromEntry) {
+                    if (typeof f?.name !== 'string')
+                        continue;
+                    if (f.name.startsWith('eventParameters.'))
+                        declaredOnEitherForm.push(f.name.slice('eventParameters.'.length));
+                }
+            }
+        }
+        if (!resolved)
+            return undefined;
+        const activityType = String(resolved.entry?.operation?.activityType ?? '');
+        const generic = activityType === 'GenericTrigger';
+        // The same two questions `schemaReadiness` answers for an activity, asked
+        // of an event: does a variant for the named object exist, and has an
+        // overlay prepared this event at all. Both are index facts, so they are
+        // read the same way — across layers, noting which layer is the overlay.
+        let discovery = (resolved.entry
+            ?.connector?.discovery ?? {});
+        if (!Object.keys(discovery).length) {
+            for (const kind of ['event', 'trigger']) {
+                discovery = this.connectorDiscovery(kind, key, event, objectName);
+                if (Object.keys(discovery).length)
+                    break;
+            }
+        }
+        let objectPrepared = false;
+        let overlayPrepared = false;
+        for (const layer of this.layers) {
+            for (const row of layer.entries) {
+                const nodeType = String(row?.nodeType ?? '');
+                if (nodeType !== `uipath.connector.event.${key}.${event}`
+                    && nodeType !== `uipath.connector.trigger.${key}.${event}`)
+                    continue;
+                if (layer.overlay === true)
+                    overlayPrepared = true;
+                if (objectName && row.objectName === objectName)
+                    objectPrepared = true;
+            }
+        }
+        const objectsFromConnection = Boolean(discovery.hasObjectDiscovery || discovery.hasCustomObjectDiscovery);
+        return {
+            known,
+            names: [...new Set(declaredOnEitherForm)],
+            generic,
+            object: resolved.objectName,
+            selectors: [...new Set(selectors)],
+            objectUnprepared: Boolean(generic && objectsFromConnection && objectName && !objectPrepared),
+            customFieldsUnprepared: Boolean(discovery.hasCustomFieldDiscovery && !overlayPrepared),
+            // Whether a PREPARED vocabulary can still be short. For an ACTIVITY it
+            // cannot: `resources describe` takes `-f`/`--action`, so a prepare can
+            // supply the parent values and materialize the custom fields. The
+            // trigger surface has NEITHER flag — `triggers describe` accepts only
+            // connector, operation, object and `--connection-id` — so wherever the
+            // schema comes from the connection at all, the event's filter list is a
+            // subset no prepare can close. Jira's designer grows past the 2 fields
+            // `describe` returns once a project and issue type are chosen; nothing
+            // we can call reaches that.
+            //
+            // ANY discovery flag, not `hasCustomFieldDiscovery` alone: the registry
+            // classifies jira `static` with `hasFieldDiscovery: true` and
+            // `hasCustomFieldDiscovery: false`, so keying on the custom flag would
+            // hard-error on the one connector we have measured growing. This is the
+            // same predicate as `runtime.requiresConnectionForSchema`, recomputed
+            // from `discovery` because the overlay's copy of that flag is wrong.
+            filtersPartial: Object.entries(discovery)
+                .some(([name, value]) => name !== 'type' && Boolean(value)),
+        };
+    }
+    /**
+     * The filterable-field names a connector event declares — the vocabulary a
+     * `filters` leaf may name.
+     *
+     * TWO SOURCES, because the platform builds the two kinds of event's filter
+     * list differently, and reading one array for both under-advertises the
+     * generic form by an order of magnitude:
+     *
+     *  - a CURATED event filters on the fields its definition MARKS
+     *    (`order: 1` / `isCuratedEventField`), which is what `triggers describe`
+     *    returns as `FilterFields` and what lands in `v1def.filterFields.fields`.
+     *    Outlook `email-received`: 15 of the Message resource's 73 fields.
+     *  - a GENERIC event filters on EVERY field the object supports GET on,
+     *    which is exactly `triggers describe`'s `OutputFields` and lands in the
+     *    entry's `outputSchema.fields`. Verified against the connector
+     *    definitions: jira `issue` 323 fields → 258 GET → 258 output; outlook
+     *    `Message` 73 → 73 → 73; gmail `Message` 33 → 33 → 33.
+     *
+     * Reading `filterFields` for both is what made jira `record-created`
+     * advertise 2 filterable fields where the designer offers 258, and gmail
+     * `new-record-created` advertise none where it offers 33. The union is taken
+     * on the generic side rather than a swap, so a connector that populates both
+     * (outlook's generic form carries its curated sibling's 15) loses nothing.
+     *
+     * Only a connection-scoped prepare or an enriched generation writes either
+     * array: the thin baked manifests carry none, and for them this answers
+     * `undefined` (unknown), never `[]` (known-empty). A GENERIC event's
+     * vocabulary is per object, so pass the subscription's `object` to select
+     * the prepared variant.
+     */
+    eventFilterFields(key, event, objectName) {
+        const names = [];
+        let known = false;
+        for (const kind of ['event', 'trigger']) {
+            let rc;
+            try {
+                rc = this.resolveEvent(kind, key, event, undefined, objectName);
+            }
+            catch {
+                continue; // the sibling may exist even when this one does not
+            }
+            const marked = rc.v1def
+                ?.filterFields?.fields;
+            const generic = String(rc.entry?.operation?.activityType ?? '') === 'GenericTrigger';
+            const getFields = generic
+                ? rc.entry?.outputSchema?.fields
+                : undefined;
+            const sources = [marked, getFields].filter(Array.isArray);
+            if (!sources.length)
+                continue;
+            known = true;
+            for (const source of sources)
+                for (const f of source)
+                    if (typeof f?.name === 'string' && f.name !== '')
+                        names.push(f.name);
+        }
+        if (!known)
+            return undefined;
+        return [...new Set(names)];
+    }
+    /**
+     * Resolve one library entry for `nodeType`. Two orthogonal concerns compose:
+     *  - **object selection** within a layer — a GENERIC operation encodes only the
+     *    verb in its node type and the library expands it into one entry per object,
+     *    so `objectName` picks which. See `resolveInLayer` for the four cases (#143).
+     *  - **field union** across layers — a connection-scoped overlay
+     *    (`prepare-connector`) is searched before the baked library, and the fields
+     *    of the entries each layer resolves are UNIONED: the overlay can ADD fields
+     *    but never drop ones the baked library already exposed (C4).
+     */
+    resolveType(nodeType, version, objectName) {
+        // Resolve the op within each layer (overlay first), then union fields across
+        // the layers that carry it.
+        const resolved = [];
+        for (const layer of this.layers) {
+            const r = this.resolveInLayer(layer, nodeType, version, objectName);
+            if (r)
+                resolved.push(r);
+        }
+        if (resolved.length) {
+            // Metadata comes from the highest-priority layer (the overlay when
+            // present); fields are the UNION across all layers.
+            const primary = resolved[0];
+            if (resolved.length === 1)
+                return primary;
+            const byName = new Map();
+            // Insert lowest-priority (baked) first so a shared field keeps the baked
+            // position but takes the overlay's (higher-priority) definition.
+            for (let i = resolved.length - 1; i >= 0; i--) {
+                for (const f of resolved[i].fields)
+                    byName.set(f.name, f);
+            }
+            return { ...primary, fields: [...byName.values()] };
+        }
+        // Name the two event namespaces when the caller asked for one, so a typo in
+        // an event name does not read as "this connector is missing".
+        const hint = /^uipath\.connector\.(trigger|event)\./.test(nodeType)
+            ? ` Event triggers are curated per connector operation — check the event name against `
+                + `the library index (\`index.json\`), and remember the two namespaces: `
+                + `\`…connector.trigger.…\` starts a flow, \`…connector.event.…\` waits mid-flow.`
+            : '';
+        throw new Error(`connector not in library: ${nodeType}${version ? '@' + version : ''}.${hint}`
+            + this.describeMiss(nodeType));
+    }
+    /**
+     * Turn a lookup miss into something actionable: which operations this connector
+     * DOES carry, the nearest spelling to what was asked for, and where the library
+     * being searched actually is.
+     *
+     * Without this the message was a dead end. In the 2026-09-09 case eval an agent
+     * read the tenant's `objectName` (`send-mail-v2`) off `uip maestro case spec`
+     * and passed it as the OPERATION slug; the real slug is `send-email`, and
+     * `connector not in library: …send-mail-v2.` said nothing that would reveal
+     * that. It resorted to grepping the library's JSON out of `node_modules`.
+     */
+    describeMiss(nodeType) {
+        // `uipath.connector.<key>.<op>`, or `uipath.connector.(trigger|event).<key>.<ev>`
+        // for the two event namespaces. No connector key contains a dot.
+        const parts = nodeType.split('.');
+        const eventNs = parts[2] === 'trigger' || parts[2] === 'event';
+        const key = eventNs ? parts[3] : parts[2];
+        const asked = (eventNs ? parts.slice(4) : parts.slice(3)).join('.');
+        if (!key)
+            return '';
+        const prefix = eventNs ? `uipath.connector.${parts[2]}.${key}.` : `uipath.connector.${key}.`;
+        const ops = [...new Set(this.layers.flatMap((l) => l.entries
+                .map((e) => String(e.nodeType ?? ''))
+                .filter((t) => t.startsWith(prefix))
+                .map((t) => t.slice(prefix.length))))].sort();
+        const where = ` Searched: ${this.layers.map((l) => l.dir).join(', ')}.`;
+        if (!ops.length) {
+            const keys = [...new Set(this.layers.flatMap((l) => l.entries.map((e) => {
+                    const p = String(e.nodeType ?? '').split('.');
+                    return (p[2] === 'trigger' || p[2] === 'event' ? p[3] : p[2]) ?? '';
+                })))].filter(Boolean).sort();
+            const near = nearest(key, keys);
+            return ` No connector "${key}" in the library (${keys.length} indexed).`
+                + (near && near !== key ? ` Closest: ${near}.` : '')
+                + where
+                + ' If the connector is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
+        }
+        const near = asked ? nearest(asked, ops) : undefined;
+        const listed = ops.length <= 12
+            ? `Operations: ${ops.join(', ')}.`
+            : `Operations (${ops.length}, first 12): ${ops.slice(0, 12).join(', ')}, … — `
+                + `the full list is every \`nodeType\` under "${key}" in the library's index.json.`;
+        return ` Connector "${key}" is present but carries no "${asked}".`
+            + (near ? ` Closest: ${near}.` : '')
+            + ` ${listed}`
+            + where
+            + ' Note the operation slug is the nodeType segment, NOT the tenant\'s `objectName`'
+            + ' — `uip maestro case spec` reports the latter, and the two can differ.'
+            + ' If the operation is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
+    }
+    /**
+     * Resolve the op WITHIN one layer, selecting the entry by `objectName` for a
+     * GENERIC operation. Returns undefined when the layer does not carry the op;
+     * throws on an author error (a missing/ambiguous object). The four cases (#143):
+     * (1) one entry — resolved (a disagreeing `objectName` is an error, unless the
+   * entry is an un-expanded GENERIC — then accepted connection-scoped like case 4);
+     * (2) many + matching `objectName` — that entry; (3) many + no `objectName` — a
+     * named error listing the objects; (4) many + an unlisted object — accepted with
+     * a warning, synthesized from a sibling entry with the object stamped in. A
+     * connector's object set belongs to the CONNECTION, not to the registry snapshot,
+     * and the platform's designer resolves such objects live.
+     */
+    resolveInLayer(layer, nodeType, version, objectName) {
+        const matches = layer.entries.filter((e) => e.nodeType === nodeType && (!version || e.version === version));
+        if (matches.length === 0)
+            return undefined;
+        if (objectName !== undefined) {
+            const exact = matches.find((e) => e.objectName === objectName);
+            if (exact)
+                return this.build(layer.dir, exact, nodeType);
+        }
+        if (matches.length === 1) {
+            // A single entry: the object is not a choice. Refuse a DISAGREEING one
+            // rather than quietly ignoring it — an author who passed `object` meant it.
+            const only = matches[0];
+            if (objectName !== undefined && (only.objectName ?? '') !== objectName) {
+                // …unless the single entry is a GENERIC op the snapshot ships
+                // UN-EXPANDED. Its object set belongs to the CONNECTION, exactly as in
+                // case 4 below — the snapshot just carries one object-less entry
+                // instead of many expanded ones, so entry COUNT cannot be the
+                // discriminator. Older snapshots pre-expanded these ops and this shape
+                // only ever reached case 4; a snapshot that stopped expanding turned
+                // the same author input into a hard error here, which broke the
+                // documented prepare-then-compile path for every Salesforce custom
+                // object (the overlay resolved `Company__c`, then the union pass hit
+                // this throw in the baked layer).
+                // A GENERIC EVENT (`record-created` on Data Fabric, Salesforce, ServiceNow,
+                // …) is the same shape one namespace over: one object-less entry whose
+                // object belongs to the connection. There the object is not a variant to
+                // warn about but the subscription's REQUIRED target, so it is stamped in
+                // silently; `check`/`compile` refuse the subscription that omits it.
+                if (only.activityType === 'GenericTrigger') {
+                    return this.build(layer.dir, { ...only, objectName }, nodeType, { objectNameUnverified: true });
+                }
+                if (only.activityType === 'Generic' || only.objectFromDiscovery === true) {
+                    process.stderr.write(`  warn:  connector ${nodeType}: the library carries this operation un-expanded `
+                        + `(one object-less entry). Object "${objectName}" is accepted as a connection-scoped `
+                        + `object — the schema comes from the generic entry and the tenant resolves the name at `
+                        + `dispatch. If it is a typo, compile will not catch it.\n`);
+                    return this.build(layer.dir, { ...only, objectName }, nodeType, { objectNameUnverified: true });
+                }
+                throw new Error(`connector ${nodeType} does not have an object "${objectName}": it is a single, `
+                    + `non-generic operation addressing ${only.objectName ? `"${only.objectName}"` : 'no object'}. `
+                    + `Drop the \`object\` option (it is only for generic operations, whose node type covers many objects).`);
+            }
+            return this.build(layer.dir, only, nodeType);
+        }
+        // Ambiguous. Either the author said nothing — which used to resolve to
+        // whichever object sorted first, silently — or named an object the library
+        // does not list.
+        const objects = matches
+            .map((e) => e.objectName)
+            .filter((o) => typeof o === 'string' && o.length > 0)
+            .sort();
+        if (objectName === undefined) {
+            throw new Error(`connector ${nodeType} is a GENERIC operation covering ${matches.length} objects — `
+                + `say which one with the \`object\` option, e.g. `
+                + `connector('${nodeType.split('.').slice(2, 3)[0]}', '${nodeType.split('.').slice(3).join('.')}', `
+                + `{ … }, { object: '${objects[0] ?? '<object>'}' }). ${describeObjects(objects)}`);
+        }
+        // Case 4 — an object the snapshot does not list. Accept it, but say so, and
+        // offer the nearest known name: a typo and a real tenant-custom object are
+        // indistinguishable here, and only the author knows which they meant. Prefer a
+        // sibling whose path template is exactly `/<its object>` — the only shape a
+        // substitution can re-point cleanly.
+        const near = nearest(objectName, objects);
+        process.stderr.write(`  warn:  connector ${nodeType}: object "${objectName}" is not one of the `
+            + `${objects.length} the library lists for it${near ? ` (nearest: "${near}")` : ''}. `
+            + `Accepted as a connection-scoped object — the schema comes from a sibling entry and the `
+            + `tenant resolves the name at dispatch. If it is a typo, compile will not catch it.\n`);
+        const sibling = this.pickDerivationSibling(layer.dir, matches);
+        return this.build(layer.dir, { ...sibling, objectName }, nodeType, { objectNameUnverified: true });
+    }
+    /**
+     * Pick the sibling entry a connection-scoped object borrows its schema from:
+     * the first whose path template is exactly `/<its own objectName>`, else the
+     * first whose template merely CONTAINS its object name, else the first entry.
+     * Index order breaks every tie, so the choice is stable across builds.
+     */
+    pickDerivationSibling(dir, matches) {
+        const templateOf = (e) => {
+            try {
+                const entry = JSON.parse(readFileSync(join(dir, e.path), 'utf8'));
+                return entry.operation?.pathTemplate ?? entry.operation?.path ?? '';
+            }
+            catch {
+                return '';
+            }
+        };
+        const canonical = matches.find((e) => e.objectName && templateOf(e) === `/${e.objectName}`);
+        if (canonical)
+            return canonical;
+        const substitutable = matches.find((e) => e.objectName && templateOf(e).includes(e.objectName));
+        return substitutable ?? matches[0];
+    }
+    build(dir, e, nodeType, opts = {}) {
+        const entryPath = join(dir, e.path);
+        const entry = JSON.parse(readFileSync(entryPath, 'utf8'));
+        const v1defRaw = JSON.parse(readFileSync(entryPath.replace(/\.json$/, '.v1def.json'), 'utf8'));
+        const v1def = Array.isArray(v1defRaw) ? v1defRaw[0] : v1defRaw;
+        // A stamped object (case 4) reaches here with the index entry's `objectName`
+        // replaced but the sibling's FILE on disk — so restate the object and derive
+        // the endpoint from the sibling's own template, rather than shipping a node
+        // whose `objectName` and `path` name two different objects.
+        // The index and the definition file can disagree about which object the
+        // operation addresses, and the definition is the stale side: for
+        // `uipath-microsoft-outlook365.send-email` the index says `send-mail-v2`
+        // (what the tenant's typecache reports, connector 1.39.0) while the
+        // definition still says `send-mail` with `/hubs/productivity/send-mail`.
+        // `build` reads the definition, so the compiled node dispatched the retired
+        // path and the runtime SendTask failed — the whole external-outcome half of
+        // one eval task, from a one-token disagreement.
+        //
+        // The index is the fresher side and the one resolution keys on, so restate
+        // the object from it and re-derive the endpoint, exactly as the stamped
+        // branch below does. Warned, not silent: it is upstream archive data, so the
+        // author should see that the two sources disagreed. Unique in the current
+        // archive (1 of 8035 entries).
+        if (!opts.objectNameUnverified && entry.operation
+            && typeof e.objectName === 'string' && e.objectName !== ''
+            && typeof entry.operation.objectName === 'string'
+            && entry.operation.objectName !== e.objectName) {
+            const stale = entry.operation.objectName;
+            const derived = deriveObjectPath(entry.operation, e.objectName);
+            process.stderr.write(`  warn:  connector ${nodeType}: the library index says objectName "${e.objectName}" but its `
+                + `definition file says "${stale}". Using the index and deriving the endpoint`
+                + (derived.path ? ` (${entry.operation.path} -> ${derived.path})` : '')
+                + `; the definition is the stale side when these disagree.\n`);
+            entry.operation = { ...entry.operation, objectName: e.objectName, ...derived };
+        }
+        if (opts.objectNameUnverified && entry.operation) {
+            entry.operation = {
+                ...entry.operation,
+                objectName: e.objectName,
+                ...deriveObjectPath(entry.operation, e.objectName),
+            };
+            delete entry.operation.objectDisplayName; // the sibling's label, not this object's
+        }
+        const objectName = entry.operation?.objectName ?? '';
+        return {
+            nodeType,
+            version: e.version,
+            connectorKey: entry.connector?.key ?? '',
+            connectorName: entry.connector?.name ?? '',
+            httpMethod: entry.operation?.httpMethod ?? 'POST',
+            endpoint: entry.operation?.pathTemplate ?? entry.operation?.path ?? '',
+            activityTypeId: findKey(v1def, 'uiPathActivityTypeId'),
+            v1def,
+            entry,
+            fields: readFields(v1def, entry),
+            multipartParts: readMultipartParts(entry),
+            objectName,
+            ...(opts.objectNameUnverified ? { objectNameUnverified: true } : {}),
+            ...this.resolveListEnvelope(entry, nodeType, objectName),
+        };
+    }
+    /**
+     * The measured LIST envelope for one resolved operation, if any.
+     *
+     * Two sources, entry-first: an OVERLAY entry may declare `envelope` on the
+     * entry JSON (a `prepare-connector` result that measured it live), and that
+     * wins; otherwise the shipped ledger beside `index.json`. Nothing is inferred
+     * — an operation the ledger has never measured comes back undeclared, and
+     * every consumer treats that as "behave exactly as before" (#156).
+     *
+     * Fenced to the LIST verb: the envelope question is only about a collection,
+     * and a row against a non-List operation would be a ledger mistake, so it is
+     * ignored rather than honoured.
+     */
+    resolveListEnvelope(entry, nodeType, objectName) {
+        if (entry?.operation?.name !== 'List')
+            return {};
+        if (entry.envelope !== undefined) {
+            return { listEnvelope: {
+                    envelope: entry.envelope ?? null,
+                    source: typeof entry.envelopeSource === 'string' ? entry.envelopeSource : 'the library entry',
+                    tier: typeof entry.envelopeTier === 'string' ? entry.envelopeTier : 'A',
+                } };
+        }
+        const row = lookupListEnvelope(this.envelopeRows, nodeType, objectName || undefined);
+        return row
+            ? { listEnvelope: { envelope: row.envelope ?? null, source: row.source, tier: row.tier } }
+            : {};
+    }
+}
+/**
+ * Re-point a sibling entry's path template at a different object.
+ *
+ * The endpoint is **not** dispatch input — dispatch is
+ * `uip is resources run <verb> <connectorKey> <objectName>` and the platform's
+ * adapter resolves the object server-side (verified live against the tenant's
+ * ServiceNow connection) — but it IS in the artifact, so a node claiming
+ * `objectName: "acr_user"` must not also carry `path: "/advanced_curated_incident"`.
+ *
+ * Substitution only, never invention: if the sibling's template contains its own
+ * object name, swap it (`/advanced_curated_incident` → `/acr_user`, which is
+ * byte-identical to what the platform's own designer emitted for `acr_user` in
+ * all four green `generic_dynamic_node` nightlies). If it does not — 1,534 of the
+ * 5,693 generic entries have an object that never appears in their path, e.g.
+ * `Campaigns::Contact` → `/Campaigns/{id}/Contact/{contactId}` — the template is
+ * left alone and the warning already told the author the schema is a sibling's.
+ */
+function deriveObjectPath(operation, objectName) {
+    const sibling = operation.objectName ?? '';
+    const out = {};
+    if (!sibling || !objectName)
+        return out;
+    for (const key of ['pathTemplate', 'path']) {
+        const tmpl = operation[key];
+        if (typeof tmpl === 'string' && tmpl.includes(sibling)) {
+            out[key] = tmpl.split(sibling).join(objectName);
+        }
+    }
+    return out;
+}
+/** Read the `.v1def.json` sidecar beside a library entry file. */
+function readV1def(entryPath) {
+    const raw = JSON.parse(readFileSync(entryPath.replace(/\.json$/, '.v1def.json'), 'utf8'));
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+/**
+ * The platform's `connectorDetail.configuration` blob — the designer's own
+ * declaration of an event operation (`eventOperation`, `eventMode`, `activityType`,
+ * …), carried as a JSON STRING inside the v1def's form. It is the one place a raw
+ * registry entry states the event's mode, so it is read here rather than guessed.
+ */
+function connectorDetailConfiguration(v1def) {
+    const sections = Array.isArray(v1def?.form?.sections) ? v1def.form.sections : [];
+    for (const section of sections) {
+        for (const field of Array.isArray(section?.fields) ? section.fields : []) {
+            const raw = field?.componentProps?.connectorDetail?.configuration;
+            if (typeof raw !== 'string')
+                continue;
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === 'object')
+                    return parsed;
+            }
+            catch {
+                // not JSON — fall through to the next field
+            }
+        }
+    }
+    return {};
+}
+/**
+ * Fill in what a raw registry EVENT entry leaves out, so every consumer of an
+ * event operation reads one complete shape.
+ *
+ * The 448 `.event.` entries of the registry dump carry `operation.name`
+ * (`CREATED`) but neither `eventOperation` nor `eventMode` — the curated overlay's
+ * four pairs are the only entries that do. Both are stated by the platform's own
+ * `connectorDetail.configuration` blob in the v1def (`{"eventOperation":"CREATED",
+ * "eventMode":"polling",…}`), which is what the designer reads too; the
+ * operation name is the same value under its registry spelling. A node emitted
+ * without them fails `flow validate` ("eventMode is required for trigger nodes")
+ * and the platform's own dispatcher refuses it (`buildEventCall`).
+ *
+ * `objectDisplayName` follows the stamped object of a generic event — the entry's
+ * empty label is a sibling's, not this object's.
+ */
+function normalizeEventOperation(rc) {
+    const operation = rc.entry?.operation;
+    if (!operation || typeof operation !== 'object')
+        return rc;
+    const activityType = String(operation.activityType ?? '');
+    if (!/Trigger|WaitFor/.test(activityType) && !/^uipath\.connector\.(trigger|event)\./.test(rc.nodeType ?? ''))
+        return rc;
+    const declared = connectorDetailConfiguration(rc.v1def);
+    const eventOperation = operation.eventOperation
+        ?? (typeof declared.eventOperation === 'string' ? declared.eventOperation : undefined)
+        ?? (typeof operation.name === 'string' && operation.name !== '' ? operation.name : undefined);
+    const eventMode = operation.eventMode
+        ?? (typeof declared.eventMode === 'string' ? declared.eventMode : undefined)
+        ?? (typeof rc.v1def?.eventMode === 'string' ? rc.v1def.eventMode : undefined);
+    const normalized = {
+        ...operation,
+        ...(eventOperation !== undefined ? { eventOperation } : {}),
+        ...(eventMode !== undefined ? { eventMode } : {}),
+        ...(rc.objectNameUnverified && operation.objectName ? { objectDisplayName: operation.objectName } : {}),
+    };
+    return { ...rc, entry: { ...rc.entry, operation: normalized } };
+}
+/**
+ * Derive a connector event's START form (`uipath.connector.trigger.<key>.<event>`)
+ * from its WAIT form (`uipath.connector.event.<key>.<event>`).
+ *
+ * The platform serves both for one operation and the differences are structural,
+ * never per-connector — measured 2026-09-02 by asking `uip maestro flow registry
+ * get` for both forms of Data Fabric `record-created` (a GENERIC event) and
+ * comparing them with the curated OneDrive/Outlook/HTTP-webhook pairs:
+ *
+ *   category            `connector.<pkg>`        → `trigger.<pkg>`
+ *   tags                `event`                  → `trigger`
+ *   model.type          `bpmn:ReceiveTask`       → `bpmn:StartEvent`
+ *   model.serviceType   `Intsvc.WaitForEvent`    → `Intsvc.EventTrigger`
+ *   model               +`entryPointId: true`, +`eventDefinition: bpmn:MessageEventDefinition`
+ *   handles             input + output + error   → one output handle (a start has no
+ *                                                  input and no error port)
+ *   outputDefinition    output + error           → output only ("…of the connector trigger")
+ *   supportsErrorHandling, inputDefaults, debug  → dropped
+ *   activityType        `CuratedWaitFor`         → `CuratedTrigger` (a generic one stays `GenericTrigger`)
+ *   runtime.bpmnType / serviceType               → the start values above
+ *
+ * `model.bindings`, `model.context`, `display` (plus the start's `shape: circle`),
+ * the form (same `uiPathActivityTypeId`) and the version are kept verbatim.
+ */
+function deriveTriggerForm(sibling, triggerType) {
+    const entry = JSON.parse(JSON.stringify(sibling.entry ?? {}));
+    const v1def = JSON.parse(JSON.stringify(sibling.v1def ?? {}));
+    const retag = (tags) => Array.isArray(tags) ? tags.map((t) => (t === 'event' ? 'trigger' : t)) : tags;
+    const recategorize = (category) => typeof category === 'string' ? category.replace(/^connector\./, 'trigger.') : category;
+    entry.nodeType = triggerType;
+    entry.category = recategorize(entry.category);
+    entry.tags = retag(entry.tags);
+    if (entry.operation && typeof entry.operation === 'object') {
+        if (entry.operation.activityType === 'CuratedWaitFor')
+            entry.operation.activityType = 'CuratedTrigger';
+    }
+    entry.runtime = { ...(entry.runtime ?? {}), bpmnType: 'bpmn:StartEvent', serviceType: 'Intsvc.EventTrigger' };
+    v1def.nodeType = triggerType;
+    v1def.category = recategorize(v1def.category);
+    v1def.tags = retag(v1def.tags);
+    delete v1def.supportsErrorHandling;
+    delete v1def.inputDefaults;
+    delete v1def.debug;
+    v1def.display = { ...(v1def.display ?? {}), shape: 'circle' };
+    v1def.handleConfiguration = [{
+            position: 'right',
+            handles: [{
+                    id: 'output', type: 'source', handleType: 'output', showButton: true,
+                    constraints: { forbiddenTargetCategories: ['trigger'] },
+                }],
+            visible: true,
+        }];
+    const model = v1def.model ?? {};
+    v1def.model = {
+        type: 'bpmn:StartEvent',
+        entryPointId: true,
+        serviceType: 'Intsvc.EventTrigger',
+        eventDefinition: 'bpmn:MessageEventDefinition',
+        ...(model.bindings !== undefined ? { bindings: model.bindings } : {}),
+        ...(model.context !== undefined ? { context: model.context } : {}),
+    };
+    v1def.inputDefinition = {};
+    const output = v1def.outputDefinition?.output;
+    v1def.outputDefinition = {
+        output: {
+            type: 'object',
+            description: 'The return value of the connector trigger.',
+            source: '=result.response',
+            var: 'output',
+            ...(output && typeof output === 'object' && output.schema !== undefined ? { schema: output.schema } : {}),
+        },
+    };
+    return { ...sibling, nodeType: triggerType, entry, v1def };
+}
+/**
+ * Name the objects an ambiguous nodeType covers, in a message a human can act on.
+ * Whole list when it is short; a sample plus the count when it is
+ * `uipath-oracle-netsuite.update-record` (197 of them) — a 197-name error is a
+ * wall of text nobody reads, and the library index is the full answer.
+ */
+function describeObjects(objects) {
+    if (objects.length === 0)
+        return 'The library lists no object names for it.';
+    if (objects.length <= 12)
+        return `Objects: ${objects.join(', ')}.`;
+    return (`Objects (${objects.length}, first 12): ${objects.slice(0, 12).join(', ')}, … — `
+        + `the full list is every \`objectName\` for this nodeType in the library's index.json.`);
+}
+/**
+ * The closest known object name to `want`, or undefined when nothing is close.
+ *
+ * A case-insensitive hit is reported as-is (the index has **zero** case-folded
+ * collisions across all 448 ambiguous nodeTypes, so it is unambiguous); otherwise
+ * an edit distance within a third of the name's length, which catches a typo
+ * (`acr_users`) without pretending `incident` is near `acr_user`.
+ */
+function nearest(want, objects) {
+    const ci = objects.find((o) => o.toLowerCase() === want.toLowerCase());
+    if (ci)
+        return ci;
+    let best;
+    let bestD = Math.max(2, Math.floor(want.length / 3));
+    for (const o of objects) {
+        const d = editDistance(want.toLowerCase(), o.toLowerCase());
+        if (d <= bestD) {
+            bestD = d;
+            best = o;
+        }
+    }
+    return best;
+}
+/** Levenshtein distance, two rows. Short strings only (object names). */
+function editDistance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+/**
+ * The accepted input vocabulary for one connector operation, with each input's
+ * wire LOCATION.
+ *
+ * A connector operation declares its inputs in two places, and reading only the
+ * first made **515 of the library's 1,336 curated operations (38.5%)**
+ * unauthorable — every "get one by id", every "list with a filter"
+ * ([#132](https://github.com/UiPath/flow-builder-sdk/issues/132)):
+ *
+ * 1. **`<action>@<ver>.v1def.json` → `inputDefinition.fields`** — the request
+ *    BODY. For the 515 this array is literally `[]`.
+ * 2. **`<action>@<ver>.json` → `operation.parameters`** — the QUERY and PATH
+ *    parameters, each carrying `type: "query" | "path"` and a `dataType`:
+ *
+ * ```jsonc
+ * // uipath-atlassian-jira/get-issue@1.0.0.json
+ * "operation": { "httpMethod": "GETBYID", "pathTemplate": "/curated_get_issue/{issueId}",
+ *   "parameters": [ { "name": "project",  "type": "query", "dataType": "string", "required": true },
+ *                   { "name": "issuetype","type": "query", "dataType": "string", "required": true },
+ *                   { "name": "issueId",  "type": "path",  "dataType": "string", "required": true } ] }
+ * ```
+ *
+ * **Why not `entry.inputSchema.fields`**, which looks like the merged list:
+ * measured over the shipped library, **5,243 of 7,029 entries disagree** with
+ * the union — e.g. `uipath-act-act365.delete-record` declares a `contactsId`
+ * path parameter and an EMPTY `inputSchema.fields`. It is a third, lossy
+ * summary, so the union of the two authoritative declarations is what we read.
+ *
+ * **A name in both wins as the PARAMETER** (its location is the wire truth).
+ * Three curated ops do this and the endpoint template settles it: Trello
+ * `add-card-attachment` declares `id` as a body field *and* as the `{id}` of
+ * `/cards/{id}/attachments`.
+ *
+ * Multipart is a Flow-artifact transport, not a claim about the separate
+ * `uip is resources run` command. The product designer emits it as
+ * `detail.multipartParameters`, including binary expressions between connector
+ * nodes, so authoring must preserve it even though that CLI command has no
+ * multipart flag.
+ *
+ * **A multipart part is an author input only when it is a FILE.** The platform
+ * splits a multipart operation the same way it splits every other one: the
+ * author's fields are `inputDefinition.fields` (Teams `body.content`, Gmail
+ * `Body`, GenAI `prompt`), and the `string`-typed multipart parameter (`body`,
+ * `RagRequest`) is the transport CONTAINER the runtime composes from
+ * `bodyParameters`. Measured on 413 designer-authored multipart nodes in the eval
+ * archive: 0 carry a value on the string part, while `file` parts do (Slack
+ * `send-file-to-channel` 70/72, Data Service `upload-file-to-record-field`
+ * 20/20). Reading the string part as a required author field did three wrong
+ * things at once: the generated docs advertised `body` as the REQUIRED input
+ * beside the real `body.content`; `compile` refused the documented fields
+ * (`'body.content'` → `missing required input "body"`, `body: { content }` →
+ * `expected string, got object`); and the one shape it accepted, `body: 'text'`,
+ * emitted `multipartParameters[body].value`, which the runtime ignores — verified
+ * live 2026-09-02 on GenAI `content-generation`: the part value never reached the
+ * model, `bodyParameters.prompt` did. So a non-file part goes to
+ * {@link readMultipartParts}, not here, and its `required` flag does not bind the
+ * author (the container is always sent; its fields carry their own flags).
+ */
+function readFields(v1def, entry) {
+    const params = authorParameters(entry);
+    // LAST RESORT: `inputSchema.fields`, and only when the two authoritative
+    // declarations above are BOTH empty.
+    //
+    // The doc comment's reason for distrusting `inputSchema.fields` stands — it is a
+    // lossy third summary and 5,243 of 7,029 entries disagree with the union — but it
+    // argues for PREFERRING the union, not for ignoring the summary when the union
+    // says nothing at all. Where both are empty there is no disagreement to lose:
+    // the choice is between the summary's fields and NO fields.
+    //
+    // No fields is not a neutral outcome, because `convert_library_to_md.py` reads
+    // `inputSchema.fields` directly. So the markdown — the artifact the skill tells an
+    // agent to author from — advertises inputs that compile then rejects as
+    // `unknown input`, reporting `Required fields: (none required)`. Measured over the
+    // shipped library: **804 ops, 43,991 field declarations**, including Jira
+    // `insert-record`/`create_issue`, whose 83 documented fields (`fields.summary`,
+    // and the REQUIRED `fields.project.key`) were all invisible to compile. An author
+    // following the documentation exactly could not compile, and the diagnostic
+    // actively misled — it named no required fields for an operation that has two.
+    //
+    // This does not weaken the unknown-field guard: a name in neither the union nor
+    // the summary is still refused, which is what catches a typo.
+    if ((v1def?.inputDefinition?.fields ?? []).length === 0 && params.length === 0) {
+        const schema = entry?.inputSchema?.fields;
+        if (Array.isArray(schema) && schema.length > 0) {
+            return schema.map((f) => ({ ...f, location: 'body' }));
+        }
+    }
+    const out = (v1def?.inputDefinition?.fields ?? []).map((f) => ({ ...f, location: 'body' }));
+    for (const p of params) {
+        const name = typeof p?.name === 'string' ? p.name : undefined;
+        const location = PARAM_LOCATIONS[p?.type];
+        if (!name || !location)
+            continue;
+        const field = {
+            name,
+            type: scalarType(p.dataType),
+            required: p.required === true,
+            location,
+            ...(p.displayName ? { displayName: p.displayName } : {}),
+            ...(p.description ? { description: p.description } : {}),
+            // A QUERY parameter can declare a lookup too (Slack's `send_as` does).
+            // Rebuilding the field from scratch used to drop it.
+            ...(p.reference && typeof p.reference === 'object'
+                ? { reference: p.reference }
+                : {}),
+        };
+        // The parameter declaration is authoritative on location; replace a
+        // same-named body field rather than shadowing it with a duplicate entry.
+        const at = out.findIndex((f) => f.name === name);
+        if (at >= 0)
+            out[at] = field;
+        else
+            out.push(field);
+    }
+    return out;
+}
+/** `operation.parameters` minus the multipart CONTAINER parts — the ones an author fills. */
+function authorParameters(entry) {
+    const params = Array.isArray(entry?.operation?.parameters) ? entry.operation.parameters : [];
+    return params.filter((p) => !isContainerPart(p));
+}
+/** A multipart parameter that is not a file: the runtime composes it, the author does not fill it. */
+function isContainerPart(p) {
+    return p?.type === 'multipart' && String(p?.dataType ?? 'string').toLowerCase() !== 'file';
+}
+/**
+ * Every multipart part the operation declares, in declaration order, as the
+ * platform lists them under `detail.multipartParameters` — the container part
+ * (valueless) and the file parts (which take the author's value from `fields`).
+ */
+function readMultipartParts(entry) {
+    const params = Array.isArray(entry?.operation?.parameters) ? entry.operation.parameters : [];
+    const out = [];
+    for (const p of params) {
+        if (p?.type !== 'multipart' || typeof p?.name !== 'string' || !p.name)
+            continue;
+        if (out.some((x) => x.name === p.name))
+            continue;
+        out.push({ name: p.name, dataType: typeof p.dataType === 'string' && p.dataType ? p.dataType : 'string' });
+    }
+    return out;
+}
+/**
+ * `operation.parameters[].type` → the wire slot. The whole vocabulary the
+ * shipped library uses is `query` · `path` · `multipart`. Anything else is
+ * skipped: an input we cannot place is an input we must not accept.
+ */
+const PARAM_LOCATIONS = {
+    query: 'query',
+    path: 'path',
+    multipart: 'multipart',
+};
+/**
+ * A parameter's `dataType` → the three scalar names `compile`'s literal
+ * type-check understands. Measured across the curated library: `string` 2,009 ·
+ * `integer` 230 · `boolean` 160 · `number` 3 · `double` 2.
+ */
+function scalarType(dataType) {
+    switch (dataType) {
+        case 'integer':
+        case 'number':
+        case 'double':
+        case 'float':
+        case 'long': return 'number';
+        case 'boolean': return 'boolean';
+        case 'string': return 'string';
+        default: return typeof dataType === 'string' ? dataType : undefined;
+    }
+}
+/** Depth-first search for the first value of `key` anywhere in `obj`. */
+function findKey(obj, key) {
+    if (obj == null || typeof obj !== 'object')
+        return undefined;
+    if (key in obj) {
+        const v = obj[key];
+        if (typeof v === 'string')
+            return v;
+    }
+    for (const val of Object.values(obj)) {
+        const found = findKey(val, key);
+        if (found)
+            return found;
+    }
+    return undefined;
+}