@uipath/maestro-builder-sdk 6.14.5 → 6.15.0

package/dist/core/connector-checks.js

@@ -0,0 +1,518 @@
+/**
+ * core/connector-checks — the check rules whose facts live in the connector
+ * library, shared by every family that authors a connector activity.
+ *
+ * These were Flow's, and they are the reason Flow's `check` can say "run THIS
+ * prepare" in the loop the author is already in. BPMN had none of them: its
+ * `check` took no options at all, so a BPMN connector node reached `compile`
+ * with an unresolved lookup, an unprepared object or a self-naming binding and
+ * learned about it from `uip maestro bpmn validate`, a tenant, or a faulted run.
+ * (`flow-v2-run-8`: `skill-bpmn-e2e-customer-escalation-triage` packed
+ * `bindings_v2.json` carrying the literal strings `jiraConnection` and
+ * `slackConnection` where connection ids belong.)
+ *
+ * Nothing here knows what a step or a task is. A caller supplies:
+ *
+ *  - `where` — how the message opens (`Connector step "post"`,
+ *    `Connector task "post"`), so each family keeps its own vocabulary;
+ *  - `report` — where the diagnostic goes, so each family adds its own locator
+ *    field (Flow's `step`, BPMN's `where`);
+ *  - `dialect` — how an authored value reads, because Flow writes expressions as
+ *    `Expr` objects over `$vars` and BPMN writes them as `=`-prefixed strings
+ *    over `vars`. Without this a BPMN `'=vars.channelId'` would read as a pasted
+ *    literal id and warn about itself.
+ */
+import { isLookupToken, resolvedValue, } from './lookups.js';
+import { Expr } from './expr.js';
+import { extractRefs } from './expr-check.js';
+import { prepareCommand, resolveFlagArg } from './cli-spelling.js';
+import { bindingSelfNameMessage, bindingUndeclaredMessage, connectionConnectorConflictMessage, undeclaredBinding, } from './binding-messages.js';
+/**
+ * Flow: an input is an {@link Expr} object. A non-literal one is runtime; a
+ * literal one (`lit(…)`) carries the constant it was built from.
+ */
+export const FLOW_EXPR_DIALECT = {
+    namespace: '$vars',
+    isOpaque: (value) => value instanceof Expr,
+    descriptors: true,
+    classify(value) {
+        if (value instanceof Expr) {
+            return value.literal ? { kind: 'literal', value: value.value } : { kind: 'runtime', js: value.js };
+        }
+        if (value !== null && typeof value === 'object')
+            return { kind: 'container' };
+        return { kind: 'literal', value };
+    },
+};
+/**
+ * BPMN and Case: an expression is a string that starts with `=`.
+ *
+ * `=js:…` is the same thing with an evaluator prefix; both reduce to the source
+ * `extractRefs` reads. A string that does NOT start with `=` is a constant, which
+ * is exactly what `LOOKUP_LITERAL_ID` is about.
+ */
+export const EQUALS_EXPR_DIALECT = {
+    namespace: 'vars',
+    isOpaque: (value) => typeof value === 'string' && value.startsWith('='),
+    descriptors: false,
+    classify(value) {
+        if (typeof value === 'string' && value.startsWith('=')) {
+            return { kind: 'runtime', js: value.slice(1).replace(/^js:/, '') };
+        }
+        if (value !== null && typeof value === 'object')
+            return { kind: 'container' };
+        return { kind: 'literal', value };
+    },
+};
+/**
+ * The lookup rules: a pasted id, and an unresolved token.
+ *
+ * These are the strongest discoverability route in the design, because they
+ * need no prior knowledge and arrive in the loop the author is already in. An
+ * author who pastes `WT9RC72KU` into a lookup field is not being careless, they
+ * are being uninformed — nothing anywhere told them the field was resolvable —
+ * and the fix is to tell them at the point of the mistake.
+ *
+ * Both are WARNINGS, not errors. A literal id is legal and sometimes correct
+ * (a value that genuinely does not move), and the unresolved case is already a
+ * hard failure at compile, where the same message is repeated. Making it an
+ * error here would stop a `check` that is otherwise clean from telling the
+ * author about everything ELSE that is wrong, which is the whole point of
+ * running the cheap pass first.
+ */
+export function checkConnectorLookups(where, spec, opts, dialect, report) {
+    const specs = opts.lookups?.(spec.key, spec.action, spec.version, spec.object);
+    const resolutions = opts.resolutions ?? {};
+    // One LOOKUP_LITERAL_ID per field: a multiselect of three pasted ids is one
+    // mistake with one remedy, not three.
+    const literalWarned = new Set();
+    // ...and ONE diagnostic per NODE for both families, not one per field.
+    //
+    // The remedy is identical for every field of a node — the same `registry
+    // prepare`, which takes every `--resolve` in one invocation, exactly as the
+    // operation's own reference page prints it. Emitting it per field repeated a
+    // five-line block with two full commands for each one: a Slack send with a
+    // channel and a `send_as` produced ten such blocks across a run, and the
+    // `integration_service_boundary` eval card went from 70 turns to 86 and from
+    // 0/3 to 3/3 `max_turns_exhausted` when BPMN started reporting them at all.
+    const unresolved = [];
+    const literals = [];
+    const visit = (value, path) => {
+        if (isLookupToken(value)) {
+            // A match key the field does not declare is certainly wrong, and the
+            // spec that says so is already in hand. `fields.reporter.id` is searchable
+            // by `displayName | accountId`; `.by('name', …)` used to pass here as an
+            // ordinary unresolved lookup, and the prepare command this warning prints
+            // would then be REFUSED by the resolver — the mistake surviving both the
+            // check and its own suggested fix. `spec.by` is the field's own
+            // declaration, so it is complete by construction and may hard-error.
+            const named = path.join('.');
+            const declared = specs?.[named];
+            const by = value.__lookup.by;
+            if (declared && typeof by === 'string' && !declared.by.includes(by)) {
+                const { target, call } = lookupPhrases(named, declared, spec, dialect.descriptors);
+                report({
+                    level: 'error',
+                    code: 'LOOKUP_UNKNOWN_MATCH_KEY',
+                    message: `${where}: \`${named}\` has no match key \`${by}\`. It resolves `
+                        + `against \`${target}\`, which is searchable by `
+                        + `${declared.by.map((b) => `\`${b}\``).join(' or ')}. Resolving on `
+                        + `\`${by}\` is refused, so recording it would fail too:\n`
+                        + `  ${call}`,
+                });
+                return;
+            }
+            if (resolvedValue(value, resolutions) === undefined)
+                unresolved.push(value);
+            return;
+        }
+        const reading = dialect.classify(value);
+        if (reading.kind === 'container') {
+            if (Array.isArray(value)) {
+                // An element is named by the WIRE name the lookup table is keyed on —
+                // `users[*]`, `contacts[*].id` — not by its index. `users.0` matched no
+                // spec, so a pasted id, a token with a bad match key, or a runtime value
+                // inside a multiselect passed every rule below unseen. A name that already
+                // is the array's (a flat `'users[*]'` key, or a field typed as an array)
+                // stays as it is.
+                const last = path[path.length - 1] ?? '';
+                const element = last.endsWith('[*]') || specs?.[path.join('.')]
+                    ? path
+                    : [...path.slice(0, -1), `${last}[*]`];
+                value.forEach((v) => visit(v, element));
+                return;
+            }
+            for (const [k, v] of Object.entries(value)) {
+                visit(v, [...path, k]);
+            }
+            return;
+        }
+        if (!specs)
+            return;
+        const field = path.join('.');
+        const lookup = specs[field];
+        if (!lookup)
+            return;
+        if (reading.kind === 'runtime') {
+            const d = runtimeLookupDiagnostic(where, spec, field, lookup, reading.js, dialect);
+            if (d)
+                report(d);
+            return;
+        }
+        // A pasted id, whether bare or wrapped in `lit()`.
+        const literal = reading.value;
+        if (typeof literal !== 'string')
+            return;
+        if (literalWarned.has(field))
+            return;
+        literalWarned.add(field);
+        literals.push({ field, lookup });
+    };
+    for (const [name, value] of Object.entries(spec.inputs ?? {}))
+        visit(value, [name]);
+    if (unresolved.length)
+        report(unresolvedDiagnostic(where, spec, unresolved));
+    if (literals.length)
+        report(literalIdDiagnostic(where, spec, literals, dialect.descriptors));
+}
+/** `--resolve a:by=<v> \` … — every field of one node, in one pasteable command. */
+function resolveBlock(spec, args) {
+    const head = `  ${prepareCommand(spec.key, spec.action)}`;
+    if (args.length === 1)
+        return `${head} \\\n    --resolve ${args[0]}`;
+    return [head + ' \\', ...args.map((a, i) => `    --resolve ${a}${i < args.length - 1 ? ' \\' : ''}`)].join('\n');
+}
+/** Every unresolved token on one node, with the single prepare that records them all. */
+function unresolvedDiagnostic(where, spec, tokens) {
+    const named = tokens.map((t) => `\`${t.__lookup.field}\` (${t.__lookup.by}=${JSON.stringify(t.__lookup.value)})`);
+    const args = tokens.map((t) => resolveFlagArg(t.__lookup.field, t.__lookup.by, String(t.__lookup.value)));
+    return {
+        level: 'warning',
+        code: 'LOOKUP_UNRESOLVED',
+        message: `${where}: ${named.length === 1 ? 'input' : 'inputs'} ${named.join(', ')} `
+            + `${named.length === 1 ? 'is an' : 'are'} unresolved lookup${named.length === 1 ? '' : 's'}. `
+            + `Compile does not make network calls, so the value has to be resolved first:\n`
+            + resolveBlock(spec, args)
+            + `\nCompile will fail until ${named.length === 1 ? 'this is' : 'these are'} recorded. Running it now, `
+            + `before compiling, is the cheap order: this pass has already found everything else that is wrong.`,
+    };
+}
+/**
+ * Every pasted lookup value on one node.
+ *
+ * The JUSTIFICATION here is the one the operation's reference page settled on
+ * (#706) and this message had not caught up with. It used to assert the value
+ * is an opaque, connection-specific id — false for 320 of the library's 2,563
+ * lookup rows, and false for a field it fires on constantly: Slack's `send_as`
+ * sends the word `bot`, which is the same word on every connection. Nothing in
+ * the metadata says which case a field is in, so the id claim is stated as the
+ * CONDITION it always was, and the value each field sends is named so the
+ * reader can tell which case theirs is.
+ */
+function literalIdDiagnostic(where, spec, rows, descriptors) {
+    const sends = rows.map(({ field, lookup }) => `\`${field}\` sends \`${lookup.objectName ?? lookup.path}.${lookup.value}\``);
+    const calls = rows.map(({ field, lookup }) => `  ${lookupPhrases(field, lookup, spec, descriptors).call}`);
+    const args = rows.map(({ field, lookup }) => resolveFlagArg(field, lookup.by[0] ?? 'id', '<value>'));
+    return {
+        level: 'warning',
+        code: 'LOOKUP_LITERAL_ID',
+        message: `${where}: ${sends.join(', ')} — the value the connector defines, not the label `
+            + `you know it by. A literal is CORRECT where that value is a fixed vocabulary `
+            + `(\`bot\`, a country code), and where you have no connection to resolve against: `
+            + `resolving is a live call, so a draft authored offline writes the literal and says so. `
+            + `It is wrong only where the value is an opaque id, which is also connection-specific — `
+            + `a pasted one resolves to nobody, or to somebody else, against a different connection. `
+            + `If this is that case, resolve ${rows.length === 1 ? 'it' : 'them'} late:\n`
+            + calls.join('\n')
+            + `\nand record ${rows.length === 1 ? 'the value' : 'the values'} once, against a live connection:\n`
+            + resolveBlock(spec, args),
+    };
+}
+/**
+ * The schema rules: an unprepared object, and unprepared custom fields.
+ *
+ * Same reasoning as the lookup rules above — the author needs no prior
+ * knowledge, and the diagnostic arrives in the loop they are already in, with
+ * the one command that discharges it. Both are WARNINGS: compile accepts a
+ * connection-scoped object (stamped `objectNameUnverified`) and passes the
+ * inputs through, so `check` is the one place the gap is visible BEFORE a
+ * process dispatches against a schema nothing validated.
+ *
+ * The custom-fields rule is deliberately narrower than "unprepared op": a step
+ * that uses only baked fields owes nothing, and warning on it anyway teaches
+ * the author that the warning is noise. It fires only for inputs OUTSIDE the
+ * tenant-agnostic snapshot — the moment hand-guessing actually starts.
+ */
+export function checkConnectorSchema(where, spec, opts, dialect, report) {
+    const readiness = opts.schemaReadiness?.(spec.key, spec.action, spec.version, spec.object);
+    if (!readiness || readiness.prepared)
+        return;
+    const prepare = prepareCommand(spec.key, spec.action);
+    if (readiness.kind === 'object') {
+        report({
+            level: 'warning',
+            code: 'OBJECT_UNPREPARED',
+            message: `${where}: object "${spec.object}" has no locally materialized schema — `
+                + `this operation resolves its object against the connection, so its fields cannot be `
+                + `validated here and compile will emit it unverified. Prepare it once:\n`
+                + `  ${prepare} --object ${spec.object}\n`
+                + `The name is matched against the connected catalog (exact, then case-insensitive on `
+                + `name and display name); several matches fail with the candidates to choose from, and `
+                + `the prepared descriptor is the import to switch to.`,
+            ...(readiness.canonical ? { suggestion: readiness.canonical } : {}),
+        });
+        return;
+    }
+    if (readiness.kind === 'customFields') {
+        // Match by full dotted path, the same descent `checkConnectorLookups`
+        // uses above — a top-level comparison would let `contact:
+        // { cf_custom: … }` slide because `contact` is a baked head, and a nested
+        // hand-guessed custom field is precisely the moment this warning is for.
+        // Wire-array markers are stripped from the baked names (`users[*]` is
+        // authored as `users`).
+        const baked = (readiness.bakedFields ?? []).map((name) => name.replace(/\[\*\]/g, ''));
+        const unknown = [];
+        const visit = (value, path) => {
+            const dotted = path.join('.');
+            // A baked field, or deeper than one — the name is in the vocabulary;
+            // whether the VALUE fits is compile's business, not this warning's.
+            if (baked.some((b) => b === dotted || dotted.startsWith(b + '.')))
+                return;
+            // The head of baked fields (`contact` when `contact.email` is baked):
+            // descend to find the precise gap underneath it. Array elements keep
+            // their parent's path — the baked names index arrays as `items[*].sku`,
+            // normalized above to `items.sku` — so a guessed field inside a list
+            // element (`lineItems: [{ cf_custom }]`) warns exactly like one under
+            // an object head.
+            if (baked.some((b) => b.startsWith(dotted + '.'))) {
+                if (Array.isArray(value)) {
+                    for (const element of value)
+                        visit(element, path);
+                }
+                else if (!isLookupToken(value) && dialect.classify(value).kind === 'container') {
+                    for (const [k, v] of Object.entries(value)) {
+                        visit(v, [...path, k]);
+                    }
+                }
+                return;
+            }
+            // Neither a baked name nor on the way to one — this IS the gap,
+            // reported once at its head.
+            unknown.push(dotted);
+        };
+        for (const [name, value] of Object.entries(spec.inputs ?? {}))
+            visit(value, [name]);
+        // Array elements share their parent's path, so one guessed field across
+        // many list rows is one gap, not one per row.
+        const distinct = [...new Set(unknown)];
+        if (distinct.length === 0)
+            return;
+        report({
+            level: 'warning',
+            code: 'CUSTOM_FIELDS_UNPREPARED',
+            message: `${where}: ${distinct.map((n) => `\`${n}\``).join(', ')} `
+                + `${distinct.length === 1 ? 'is' : 'are'} not in the tenant-agnostic snapshot, and this `
+                + `operation resolves its real field set — custom fields included — from a live `
+                + `connection. Do not hand-guess the names; materialize the schema once:\n`
+                + `  ${prepare}\n`
+                + `then author against the prepared descriptor (its field names and doc comments are `
+                + `the vocabulary) and re-run check.`,
+        });
+    }
+}
+/**
+ * The field contract and the binding names `compile` enforces, reported here first.
+ *
+ * Both rules run only with the facts in hand (a library for the fields, a
+ * bindings.json for the names); without them `check` stays a pure function of the
+ * built model and says nothing, as before.
+ */
+export function checkConnectorContract(where, spec, opts, report, 
+/** The activity's own id, for {@link connectionConnectorConflicts}; omit to record nothing. */
+id) {
+    const inputErr = opts.connectorInputs?.({ key: spec.key, action: spec.action, version: spec.version, object: spec.object }, spec.inputs ?? {});
+    if (inputErr) {
+        report({ level: 'error', code: 'CONNECTOR_INPUT', message: `${where}: ${inputErr}` });
+    }
+    checkBindingLabels(where, spec, opts, (code, message) => report({ level: 'error', code, message }), { key: spec.key, action: spec.action }, id === undefined ? undefined : { id, connector: spec.key });
+}
+/**
+ * The binding-label rules `serialize`'s `resolveBinding` enforces, for one
+ * `{ connection, folder }` pair — reported at every site that resolves one
+ * (connector step, event trigger and `.entryPoint` onEvent, waitForEvent, managed
+ * HTTP), with the sentence compile throws. Without this at the event and HTTP
+ * sites `check` printed `✓ no issues` for a source `compile` then refused.
+ *
+ * Silent without a bindings.json, and for a label that resolves to anything
+ * other than its own name (stub values are compile's CONNECTION_STUB warning).
+ */
+export function checkBindingLabels(where, labels, opts, report, target, 
+/** The activity, and the connector its connection must belong to, for {@link connectionConnectorConflicts}. */
+use) {
+    const label = labels?.connection;
+    if (use?.connector && typeof label === 'string' && label !== '') {
+        connectionUsage?.push({ id: use.id, label, connector: use.connector });
+    }
+    const bindings = opts.bindings;
+    if (!bindings || !labels)
+        return;
+    for (const attribute of ['connection', 'folder']) {
+        const name = labels[attribute];
+        if (typeof name !== 'string')
+            continue;
+        const resolved = bindings.resolve(name);
+        if (resolved === name) {
+            report('BINDING_SELF_NAME', bindingSelfNameMessage(where, name, attribute, target));
+        }
+        else if (resolved === undefined) {
+            const declared = undeclaredBinding(bindings, name);
+            if (declared) {
+                report('BINDING_UNDECLARED', bindingUndeclaredMessage(where, name, attribute, declared, target));
+            }
+        }
+    }
+}
+/**
+ * The two phrases every lookup diagnostic needs: what the field sends, and how
+ * to resolve it.
+ *
+ * The `call` names BOTH authoring forms, and names which one the alias belongs
+ * to. Printing `lookup(<Descriptor>, 'entityName').byDisplayName('<value>')`
+ * alone — the old text — was a remedy with an unstated precondition: aliases
+ * are generated onto the descriptor, and `<Descriptor>` is a placeholder the
+ * reader has to fill from somewhere. An author holding the connector key and
+ * action instead (the form the library's Generic CRUD half is authored in, and
+ * the majority of its lookup fields) substitutes those for the placeholder,
+ * keeps the alias, and gets `lookup(...).byDisplayName is not a function`. Six
+ * flow-eval tasks did precisely that, each losing a check-edit-check round to
+ * a message that had told them to.
+ */
+export function lookupPhrases(field, lookup, spec, descriptors = true) {
+    const target = `${lookup.objectName ?? lookup.path}.${lookup.value}`;
+    const by = lookup.by[0] ?? 'id';
+    const alias = Object.keys(lookup.aliases)[0];
+    // The key/action form first: it needs no import, so it is the one line that
+    // is paste-ready from the message alone.
+    const generic = `lookup('${spec.key}', '${spec.action}', '${field}').by('${by}', '<value>')`;
+    const call = alias && descriptors
+        ? `${generic}\n  or \`lookup(D, '${field}').${alias}('<value>')\`, where D is the `
+            + `descriptor \`${prepareCommand(spec.key, spec.action)}\` generates — the aliases exist only there`
+        : generic;
+    return { target, call };
+}
+/**
+ * `senderEmail`, `emailAddress`, `e_mail`, `userPrincipalName` — an address. Applied
+ * to the LEAF an expression reads, and to the lookup's own `value` / `by` names,
+ * because whether an address is wrong depends on what the field sends: SendGrid's
+ * `from` sends `from_email`, PagerDuty's `From` sends `email` — there an e-mail IS
+ * the id. `emailId` is left to the id rule.
+ */
+const EMAIL_LEAF = /e[-_]?mail|principal/i;
+/**
+ * `id`, `accountId`, `channelKey`, `record_id`, `CHANNEL_KEY` — the author is
+ * already naming an id. Case-sensitive on purpose: `valid`, `paid` and `monkey`
+ * end in the same letters and are not ids.
+ */
+const ID_LEAF = /(?:^|[a-z0-9])(?:Id|ID|Key|KEY)$|(?:^|_)(?:id|key|ID|KEY|Id|Key)$/;
+/**
+ * The lookup rule for a RUNTIME value.
+ *
+ * `check` cannot evaluate `$vars.start.output.senderEmail`, but it does know what
+ * the field it lands in must carry — `reporter.accountId` — because the descriptor
+ * says so. That is the fact the author of the 09-01 escalation flow never saw: the
+ * generated type read `id: ConnectorLookupValue<string>`, the field was required,
+ * the only person-shaped input in scope was an e-mail, and nothing between the
+ * source and the tenant said an address is not an account id. Jira did, at run
+ * time, as `[102003] Integration Services bad request`.
+ *
+ * Three tiers, decided by the LEAF the expression reads, because that name is
+ * the only signal available before the process runs:
+ *   - id-shaped (`…Id`, `…Key`, or the lookup's own `value`): silence. The author
+ *     has said it is an id; a mistaken id is `LOOKUP_LITERAL_ID`'s move-between-
+ *     connections problem, not this one.
+ *   - e-mail-shaped, into a lookup that neither SENDS an e-mail (`value`) nor
+ *     SEARCHES by one (`by`): an ERROR. Jira's reporter (`accountId`, by
+ *     displayName/accountId) is the measured case — the provider rejects the
+ *     address, and stopping here is cheaper than a faulted run. Into a lookup
+ *     whose `value` is itself an e-mail (SendGrid `from` → `from_email`, PagerDuty
+ *     `From` → `email`, 19 fields in the library): silence — the address is the
+ *     id. Into one that only searches by e-mail (ActiveCampaign `contact` → `id`,
+ *     by `email`, 139 fields): a WARNING — the provider indexes people by address,
+ *     so some accept it in the id slot and some do not; the reader decides.
+ *   - anything else (a name, a whole output object, a concatenation): a WARNING
+ *     that states the identity, so the reader can decide.
+ */
+function runtimeLookupDiagnostic(where, spec, field, lookup, js, dialect) {
+    const refs = extractRefs(js, dialect.namespace);
+    const single = refs.length === 1 && js.trim() === refs[0].raw ? refs[0] : undefined;
+    const leaf = single ? (single.path.length ? single.path[single.path.length - 1] : single.root) : undefined;
+    // The lookup's value may be dotted (`properties.email`): compare against its last segment too.
+    const valueLeaf = lookup.value.split('.').pop() ?? lookup.value;
+    const valueIsEmail = EMAIL_LEAF.test(lookup.value);
+    if (leaf && (ID_LEAF.test(leaf)
+        || leaf.toLowerCase() === lookup.value.toLowerCase()
+        || leaf.toLowerCase() === valueLeaf.toLowerCase()
+        || (valueIsEmail && EMAIL_LEAF.test(leaf))))
+        return undefined;
+    const { target, call } = lookupPhrases(field, lookup, spec, dialect.descriptors);
+    const searchesByEmail = lookup.by.some((b) => EMAIL_LEAF.test(b));
+    const isEmail = !!leaf && EMAIL_LEAF.test(leaf) && !valueIsEmail && !searchesByEmail;
+    const message = `${where}: \`${field}\` is a lookup field bound to the runtime expression `
+        + `\`${js}\`. At run time it must carry a \`${target}\` — the id the connector stores — `
+        + `not a name or an address: the connector rejects anything else when the flow runs, and `
+        + `neither compile nor validate can tell. Resolve the value you know instead:\n`
+        + `  ${call}\n`
+        + `then record it once with \`${prepareCommand(spec.key, spec.action)} `
+        + `--resolve ${resolveFlagArg(field, lookup.by[0] ?? 'id', '<value>')}\`; or read the id from a step whose `
+        + `output returned one (\`${lookup.value}\`).`
+        + (isEmail
+            ? `\n\`${single.raw}\` reads \`${leaf}\`, an e-mail address, not a \`${target}\`.`
+            : '');
+    return { level: isEmail ? 'error' : 'warning', code: 'LOOKUP_RUNTIME_VALUE', message };
+}
+/**
+ * The connection uses {@link checkBindingLabels} saw during the current check —
+ * the model and every child model, which share one `bindings[]`. Module state
+ * rather than a `ConnectorCheckOpts` field because a check is synchronous and
+ * this is not an input; {@link collectConnectionUses} saves and restores it, so
+ * a nested check cannot mix two models.
+ */
+let connectionUsage;
+/** Run `check`, and hand back the connection uses its binding-label rules saw. */
+export function collectConnectionUses(check) {
+    const outer = connectionUsage;
+    connectionUsage = [];
+    try {
+        check();
+        return connectionUsage;
+    }
+    finally {
+        connectionUsage = outer;
+    }
+}
+/**
+ * CONNECTION_CONNECTOR_CONFLICT — the rule `serialize` enforces on the emitted
+ * document (`connectionConnectors`, bindings-v2.ts), reported here with the same
+ * sentence so `check` does not print `✓ no issues` for a source `compile` then
+ * refuses. Labels are grouped by what they resolve to, so two labels bound to
+ * one connection id are one connection, as they are in the artifact.
+ */
+export function connectionConnectorConflicts(uses, opts) {
+    const byConnection = new Map();
+    for (const use of uses) {
+        const key = opts.bindings?.resolve(use.label) ?? use.label;
+        const byConnector = byConnection.get(key) ?? new Map();
+        byConnection.set(key, byConnector);
+        byConnector.set(use.connector, [...(byConnector.get(use.connector) ?? []), use.id]);
+    }
+    const out = [];
+    for (const [key, byConnector] of byConnection) {
+        if (byConnector.size < 2)
+            continue;
+        out.push({
+            id: [...byConnector.values()][1][0],
+            message: connectionConnectorConflictMessage(key, byConnector),
+        });
+    }
+    return out;
+}

package/dist/core/connector-inputs.d.ts

@@ -0,0 +1,80 @@
+/**
+ * core/connector-inputs — a connector operation's authored inputs, validated
+ * against its declared field list and ROUTED to the wire slots the platform reads.
+ *
+ * Shared by every family that authors a connector activity. It was Flow's, inside
+ * `serialize.ts`, and BPMN had a fourteen-line substitute: an input the library
+ * did not declare went silently to the body, a missing required field was never
+ * reported, and a `lookup()` token was refused outright because nothing here
+ * read `connectors-local/resolutions.json`. That last one is why
+ * `skill-bpmn-paginated-reference-lookup` could resolve a Slack channel id and
+ * then emit a process that did not carry it.
+ *
+ * Two things differ between families and are injected rather than assumed:
+ *
+ *  - `dialect` — which values are opaque (a Flow `Expr`, a BPMN `=`-expression).
+ *    An opaque value is not type-checked against the field's declared type,
+ *    because nothing here can evaluate it.
+ *  - `render` — how an authored value becomes a wire value. Flow runs `renderDeep`
+ *    to lower `Expr` objects into `$vars.…` source; BPMN's values are already
+ *    plain, so it passes them through.
+ *
+ * The ROUTING is the library's business either way: a field's location is a
+ * property of the operation, not of the family emitting it.
+ */
+import { type LookupResolutions, type LookupSpec } from './lookups.js';
+import type { MultipartPart, ResolvedConnector } from './library.js';
+import type { ExprDialect } from './connector-checks.js';
+/** How one family's values reach the wire. */
+export interface ConnectorInputOpts {
+    /** Which values are opaque, and so exempt from the declared-type check. */
+    dialect: ExprDialect;
+    /** An authored value → its wire value. Identity when the family needs no lowering. */
+    render?: (value: unknown) => unknown;
+    /** Everything `registry prepare --resolve` has recorded in the local overlay. */
+    resolutions?: LookupResolutions;
+    /** The operation's generated lookup table, keyed by field — for the missing-required hint. */
+    lookups?: Readonly<Record<string, LookupSpec>>;
+    /** `ignore` skips an unresolved lookup instead of refusing it — what `check` wants. */
+    unresolvedLookups?: 'error' | 'ignore';
+}
+/** Flow's dialect, re-exported so `serialize.ts` need not reach past this module. */
+export { FLOW_EXPR_DIALECT } from './connector-checks.js';
+/**
+ * What `compile` would refuse these connector inputs with, or `undefined` when it
+ * would accept them — the SAME code path `buildConnectorInputs` runs at emit time,
+ * so `check` and `compile` cannot disagree about a missing required field, an
+ * unknown or mistyped input, or a container part passed as a value. Unresolved
+ * lookups are the one thing skipped: `check` already reports them as
+ * LOOKUP_UNRESOLVED with the resolution recipe.
+ */
+export declare function connectorInputErrors(rc: ResolvedConnector, inputs: Record<string, unknown>, resolutions?: LookupResolutions, lookups?: Readonly<Record<string, LookupSpec>>, wire?: Pick<ConnectorInputOpts, 'dialect' | 'render'>): string | undefined;
+export declare function buildConnectorInputs(rc: any, inputs: Record<string, unknown>, opts: ConnectorInputOpts): ConnectorSlots;
+/**
+ * `inputMetadata.multipart.bodyFieldName` names the CONTAINER part — the one the
+ * runtime composes from `bodyParameters`. Measured on the designer's own nodes in
+ * the eval archive: `body` ×413, `RagRequest` ×1 (GenAI `content-generation`, whose
+ * string part is named that), and `body` on 91 of 93 file-only operations. A
+ * mis-named container is fatal at dispatch — hardcoding `body` for GenAI made
+ * Integration Service answer `400 The request body is empty` (verified live
+ * 2026-09-02) — so it is the string part's own name, with `body` only as the
+ * default for an operation that has no string part.
+ */
+export declare function multipartBodyFieldName(parts: MultipartPart[]): string;
+/** The `inputs.detail` slots a connector's inputs are routed to, by field location. */
+interface ConnectorSlots {
+    bodyParameters?: Record<string, unknown>;
+    pathParameters?: Record<string, unknown>;
+    queryParameters?: Record<string, unknown>;
+    multipartParameters?: Array<{
+        name: string;
+        dataType: string;
+        value?: unknown;
+    }>;
+    inputMetadata?: {
+        type: 'multipart';
+        multipart: {
+            bodyFieldName: string;
+        };
+    };
+}