@uipath/maestro-builder-sdk 6.9.0 → 6.9.2

package/dist/check.d.ts

@@ -1,6 +1,7 @@
 import { type LookupResolutions, type LookupSpec } from './core/lookups.js';
 import type { SchemaReadiness } from './core/library.js';
 import type { BuiltFlow } from './flow-sdk.js';
+import { type BindingsView } from './core/binding-messages.js';
 export interface Diagnostic {
     level: 'error' | 'warning';
     code: string;
@@ -140,12 +141,13 @@ export interface CheckOpts {
         object?: string;
     }, inputs: Record<string, unknown>) => string | undefined;
     /**
-     * The project's `bindings.json`, when there is one — enough of it to detect an
-     * entry that answers with its own name, which `compile` refuses (BINDING_SELF_NAME).
+     * The project's `bindings.json`, when there is one — enough of it to detect the
+     * two labels `compile` refuses: an entry that answers with its own name
+     * (BINDING_SELF_NAME), and a label a populated file does not declare
+     * (BINDING_UNDECLARED). `declared` and `entry` are optional so a caller holding
+     * only `resolve` still gets the first rule; the `Bindings` class has all three.
      */
-    bindings?: {
-        resolve(name?: string): string | undefined;
-    };
+    bindings?: BindingsView;
 }
 export declare function check(built: BuiltFlow, opts?: CheckOpts): Diagnostic[];
 /**

package/dist/check.js

@@ -10,7 +10,7 @@ import { FlowNode } from './core/node-classes.js';
 import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './core/lookups.js';
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
 import { extractRefs } from './core/expr-check.js';
-import { bindingSelfNameMessage } from './core/binding-messages.js';
+import { bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
 import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
@@ -357,6 +357,14 @@ function checkFlow(built, ancestors, opts = {}) {
                     checkTransform(s.name, s.spec.inputs, diags, typeOf, triggerId);
                 if (s.spec.kind === 'http') {
                     checkHttp(s.name, s.spec.inputs, diags);
+                    // Only a complete pair: an empty half is HTTP_MANAGED_BINDING_INCOMPLETE, which
+                    // serialize refuses before it resolves either name.
+                    const pair = s.spec.inputs;
+                    const filled = (v) => typeof v === 'string' && v.trim() !== '';
+                    if (pair?.managed && filled(pair.connection) && filled(pair.folder)) {
+                        const httpStep = s.name;
+                        checkBindingLabels(`managed http "${httpStep}"`, pair, opts, (code, message) => diags.push({ level: 'error', code, step: httpStep, message }));
+                    }
                     const seen = new Set();
                     for (const b of s.spec.inputs.branches ?? []) {
                         addExpr(b.condition.js, s.name);
@@ -530,6 +538,7 @@ function checkFlow(built, ancestors, opts = {}) {
                     });
                     checkEventSubscription(s.spec.subscription, `waitForEvent "${stepName}"`, push('error'), push('warning'), eventParamsFor(s.spec.subscription, opts));
                     checkEventResolution(s.spec.subscription, `waitForEvent "${stepName}"`, 'event', opts, push('error'), push('warning'), eventParamsFor(s.spec.subscription, opts));
+                    checkBindingLabels(`waitForEvent "${stepName}"`, s.spec.subscription, opts, push('error'), eventTarget(s.spec.subscription));
                 }
                 if (s.spec.kind === 'subflow') {
                     // Only a real child goes in the map: a missing one is reported by
@@ -1470,14 +1479,41 @@ function checkConnectorContract(step, spec, opts, diags) {
     if (inputErr) {
         diags.push({ level: 'error', code: 'CONNECTOR_INPUT', step, message: `Connector step "${step}": ${inputErr}` });
     }
-    if (opts.bindings) {
-        for (const attribute of ['connection', 'folder']) {
-            const name = spec[attribute];
-            if (name !== undefined && opts.bindings.resolve(name) === name) {
-                diags.push({
-                    level: 'error', code: 'BINDING_SELF_NAME', step,
-                    message: bindingSelfNameMessage(`Connector step "${step}"`, name, attribute),
-                });
+    checkBindingLabels(`Connector step "${step}"`, spec, opts, (code, message) => diags.push({ level: 'error', code, step, message }), { key: spec.key, action: spec.action });
+}
+/** What `registry prepare` takes for an event subscription: its connector key and curated event name. */
+function eventTarget(sub) {
+    const { connector, event } = (sub ?? {});
+    return typeof connector === 'string' && connector !== ''
+        ? { key: connector, ...(typeof event === 'string' && event !== '' ? { action: event } : {}) }
+        : undefined;
+}
+/**
+ * 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).
+ */
+function checkBindingLabels(where, labels, opts, report, target) {
+    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));
             }
         }
     }
@@ -2278,6 +2314,7 @@ function checkTrigger(spec, diags, opts = {}) {
         const sub = spec.subscription;
         checkEventSubscription(sub, 'trigger', at, push('warning'), eventParamsFor(sub, opts));
         checkEventResolution(sub, 'trigger', 'trigger', opts, at, push('warning'), eventParamsFor(sub, opts));
+        checkBindingLabels('event trigger', sub, opts, at, eventTarget(sub));
         return;
     }
     // manual() is the explicit spelling of the default — nothing to validate.

package/dist/cli/commands/registry.js

@@ -130,8 +130,8 @@ export function registerRegistryCommands(program) {
         .option('--connection-id <id>', 'connection to read the schema through')
         .option('--connection <name>', 'pick the connection by name when several match')
         .option('--bindings <file>', 'bindings file to update (default: ./bindings.json)')
-        .option('--bind-connection <name>', 'symbolic connection name (default: the connector suffix)')
-        .option('--bind-folder <name>', 'symbolic folder name (default: shared)')
+        .option('--bind-connection <name>', 'symbolic connection name (default: the one label the source uses for this connector, else the connector suffix)')
+        .option('--bind-folder <name>', 'symbolic folder name (default: the one folder label the source uses, else shared)')
         // A SEPARATE key, not commander's negation of `--bindings`: sharing one key
         // made the result order-dependent, so `--no-bindings --bindings b.json` and
         // the reverse disagreed. argparse had two independent options.

package/dist/compile-cli.js

@@ -27,6 +27,7 @@ import { Bindings } from './bindings.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
 import { connectionResources, mergeBindingsV2, readBindingsV2 } from './bindings-v2.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
+import { BindingRefusal } from './core/binding-messages.js';
 function opt(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 ? argv[i + 1] : undefined;
@@ -106,11 +107,27 @@ export async function run(argv) {
     }
     // The serializer's own observations — a connection or folder value that can
     // never be a tenant resource key — printed in the same `⚠ [CODE]` shape as
-    // check()'s, and never fatal: the .flow is still written, exit stays 0.
+    // check()'s. Warnings are never fatal: the .flow is still written, exit stays 0.
+    // A binding LABEL the serializer refuses (its own name as the resourceKey, or a
+    // label a populated bindings.json does not declare) is an error, not a
+    // warning: the check pass above reports it first, and this is the same refusal
+    // in the same `✗ [CODE]` shape when that pass was skipped (`--no-check`, or an
+    // emit-only project). Nothing is written.
     const warnings = [];
-    const { flow: flowJson, sidecars } = serializeWithSidecars(built, {
-        library, bindings, warn: (w) => warnings.push(w),
-    });
+    let emitted;
+    try {
+        emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w) });
+    }
+    catch (error) {
+        if (!(error instanceof BindingRefusal))
+            throw error;
+        for (const w of warnings)
+            console.error(`  ⚠ [${w.code}] ${w.message}`);
+        console.error(`  ✗ [${error.code}] ${error.message}`);
+        console.error('compile: 1 error(s); not emitting.');
+        return 1;
+    }
+    const { flow: flowJson, sidecars } = emitted;
     for (const w of warnings)
         console.error(`  ⚠ [${w.code}] ${w.message}`);
     const out = opt(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;

package/dist/core/binding-messages.d.ts

@@ -1 +1,60 @@
-export declare function bindingSelfNameMessage(where: string, name: string, attribute: 'connection' | 'folder'): string;
+/** A tenant resource key — an Integration Service connection id or an Orchestrator folder key — is a GUID. */
+export declare const GUID_RE: RegExp;
+/** The diagnostic codes a label refusal carries, in `check` and on the error `serialize` throws. */
+export type BindingRefusalCode = 'BINDING_SELF_NAME' | 'BINDING_UNDECLARED';
+/**
+ * What `serialize` throws for a label it refuses. It is an ordinary `Error` whose
+ * message is the sentence `check` prints; the `code` lets `compile --no-check`
+ * print it in the same `✗ [CODE]` shape as the check pass instead of a bare line.
+ */
+export declare class BindingRefusal extends Error {
+    readonly code: BindingRefusalCode;
+    constructor(code: BindingRefusalCode, message: string);
+}
+/** The part of a bindings.json the label rules read — `core/bindings.ts` `Bindings` has all three. */
+export interface BindingsView {
+    resolve(name?: string): string | undefined;
+    declared?(): string[];
+    entry?(name?: string): unknown;
+}
+export declare function bindingSelfNameMessage(where: string, name: string, attribute: 'connection' | 'folder', target?: PrepareTarget): string;
+/**
+ * The names a populated bindings.json declares when it does NOT declare `name`,
+ * else `undefined`.
+ *
+ * `undefined` — nothing to refuse — when no bindings.json is loaded, when it
+ * declares no entries (offline authoring: the symbolic name is the only honest
+ * placeholder there), when `name` is itself a GUID (an author may write the
+ * resource key directly), or when any entry answers to `name`. "Answers" is the
+ * union of `entry()`, `resolve()` and `declared()`, so an entry that is declared
+ * but carries no `resourceKey` is NOT refused here — it stays the
+ * `CONNECTION_STUB` warning, which is the route a simulated or validate-only task
+ * with nothing real to bind is meant to take.
+ */
+export declare function undeclaredBinding(bindings: BindingsView | undefined, name: string): string[] | undefined;
+/**
+ * The connector and operation a label belongs to, when the call site knows them:
+ * a connector step's `key` + `action`, an event's `connector` + `event`. With it
+ * the remedy is a command the author can paste; without it (managed HTTP) the
+ * command keeps its `<connector-key> <action>` placeholders.
+ */
+export interface PrepareTarget {
+    key: string;
+    action?: string;
+}
+/**
+ * Why compile refuses `name`, and how to bind it.
+ *
+ * It names NO declared label as the one to use. bindings.json rows carry a label,
+ * a resource key and a kind (`ConnectionId` / `FolderKey`), never the connector
+ * they were bound for, so compile cannot tell which declared label — if any — is
+ * this connector's. Suggesting one sent a Data Service step to `connection:
+ * 'slack'` (the only `ConnectionId` row), and following that compiled the Slack
+ * connection id into the Data Service node with no warning at all: a real GUID of
+ * the wrong connector, which nothing downstream detects. The partial-prepare shape
+ * (ipe-drive-to-slack 09-23: `slack` bound, `drive` not yet) is exactly where
+ * that advice was on offer. So the message lists what is declared, says that a
+ * row is only reusable if it was bound for THIS connector, and gives the
+ * `prepare` command for this step's own connector and operation.
+ */
+export declare function bindingUndeclaredMessage(where: string, name: string, attribute: 'connection' | 'folder', declared: readonly string[], target?: PrepareTarget): string;

package/dist/core/binding-messages.js

@@ -1,16 +1,91 @@
 /**
- * The refusal for a bindings.json entry that answers with its own name — shared by
- * `serialize` (which throws it) and `check` (BINDING_SELF_NAME), so the author reads
- * the same sentence from the inner loop as from compile. Before this, `check`
- * printed `0 error(s)` for a source `compile` then refused (teams-decision,
- * 2026-09-01, turn 22 → 23).
+ * The refusals for a connection/folder label `compile` cannot turn into a tenant
+ * resource key — shared by `serialize` (which throws them) and `check`
+ * (BINDING_SELF_NAME, BINDING_UNDECLARED), so the author reads the same sentence
+ * from the inner loop as from compile. Before this, `check` printed `0 error(s)`
+ * for a source `compile` then refused (teams-decision, 2026-09-01, turn 22 → 23).
  */
 import { prepareCommand } from './cli-spelling.js';
-export function bindingSelfNameMessage(where, name, attribute) {
+/** A tenant resource key — an Integration Service connection id or an Orchestrator folder key — is a GUID. */
+export const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * What `serialize` throws for a label it refuses. It is an ordinary `Error` whose
+ * message is the sentence `check` prints; the `code` lets `compile --no-check`
+ * print it in the same `✗ [CODE]` shape as the check pass instead of a bare line.
+ */
+export class BindingRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'BindingRefusal';
+        this.code = code;
+    }
+}
+export function bindingSelfNameMessage(where, name, attribute, target) {
     return `${where}: binding "${name}" resolves to its own name, so the ${attribute} would compile to the `
         + `literal string "${name}" and the run would fault with "'Connection' has an invalid GUID value: `
-        + `'${name}'". Set its "resourceKey" to the real id: \`${prepareCommand('<connector-key>', '<action>')}\` `
+        + `'${name}'". Set its "resourceKey" to the real id: \`${prepareFor(target)}\` `
         + `discovers the connection and writes both the connection and the folder entry into bindings.json; by hand, `
         + `read Id and FolderKey from \`uip is connections list --all-folders --output json\` (the default listing `
         + `shows only your own folder, so a connection shared from another folder is invisible without --all-folders).`;
 }
+/**
+ * The names a populated bindings.json declares when it does NOT declare `name`,
+ * else `undefined`.
+ *
+ * `undefined` — nothing to refuse — when no bindings.json is loaded, when it
+ * declares no entries (offline authoring: the symbolic name is the only honest
+ * placeholder there), when `name` is itself a GUID (an author may write the
+ * resource key directly), or when any entry answers to `name`. "Answers" is the
+ * union of `entry()`, `resolve()` and `declared()`, so an entry that is declared
+ * but carries no `resourceKey` is NOT refused here — it stays the
+ * `CONNECTION_STUB` warning, which is the route a simulated or validate-only task
+ * with nothing real to bind is meant to take.
+ */
+export function undeclaredBinding(bindings, name) {
+    if (!bindings || typeof bindings.declared !== 'function')
+        return undefined;
+    const declared = bindings.declared();
+    if (declared.length === 0)
+        return undefined;
+    if (GUID_RE.test(name))
+        return undefined;
+    if (declared.includes(name))
+        return undefined;
+    if (typeof bindings.entry === 'function' && bindings.entry(name) !== undefined)
+        return undefined;
+    if (bindings.resolve(name) !== undefined)
+        return undefined;
+    return declared;
+}
+function prepareFor(target) {
+    return prepareCommand(target?.key ?? '<connector-key>', target?.action ?? '<action>');
+}
+/**
+ * Why compile refuses `name`, and how to bind it.
+ *
+ * It names NO declared label as the one to use. bindings.json rows carry a label,
+ * a resource key and a kind (`ConnectionId` / `FolderKey`), never the connector
+ * they were bound for, so compile cannot tell which declared label — if any — is
+ * this connector's. Suggesting one sent a Data Service step to `connection:
+ * 'slack'` (the only `ConnectionId` row), and following that compiled the Slack
+ * connection id into the Data Service node with no warning at all: a real GUID of
+ * the wrong connector, which nothing downstream detects. The partial-prepare shape
+ * (ipe-drive-to-slack 09-23: `slack` bound, `drive` not yet) is exactly where
+ * that advice was on offer. So the message lists what is declared, says that a
+ * row is only reusable if it was bound for THIS connector, and gives the
+ * `prepare` command for this step's own connector and operation.
+ */
+export function bindingUndeclaredMessage(where, name, attribute, declared, target) {
+    const key = attribute === 'connection' ? 'connection id' : 'folder key';
+    const flag = attribute === 'connection' ? '--bind-connection' : '--bind-folder';
+    return `${where}: ${attribute} "${name}" is not declared in bindings.json (it declares: ${declared.join(', ')}), `
+        + `so the .flow would carry "${name}" as its ${key} and the run would fault with `
+        + `"'Connection' has an invalid GUID value: '${name}'". Bind this one: `
+        + `\`${prepareFor(target)} ${flag} ${name}\` (several candidates: add \`--connection-id <id>\` from the list it prints). `
+        + `Switch to a declared label only if that row was bound for this same connector: bindings.json does not record `
+        + `which connector a row belongs to, and another connector's ${key} compiles without any warning and faults only at run time. `
+        + `A connector with nothing real to bind yet (a simulated or validate-only task, or one not prepared yet) `
+        + `declares the label with a placeholder resourceKey instead, which compiles with a CONNECTION_STUB warning — `
+        + `never an invented GUID.`;
+}

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

@@ -44,6 +44,27 @@ export declare function exitText(error: unknown): string;
 export declare function connectionLine(row: Record<string, unknown>, connectionId: string): string;
 /** `  bindings: <symbolic name> -> <bindings.json>`, once per row this run changed. */
 export declare function bindingsLine(symbolicName: string, bindingsPath: string): string;
+/** ` (the label Demo.flow.ts uses)` — appended to a bindings line whose name came from the source. */
+export declare function sourceLabelSuffix(files: readonly string[]): string;
+/**
+ * The source uses several labels for this one connector, and one prepare binds one
+ * connection: refused before any tenant call or write, with the command for each.
+ */
+export declare function ambiguousLabelsMessage(attribute: "connection" | "folder", connectorKey: string, action: string, labels: ReadonlyMap<string, readonly string[]>, command: string): string;
+/**
+ * The source gives this connector's steps a connection label that steps of another
+ * connector use too. One label binds one connection id, so one of them would dial the
+ * other's connection — a mismatch compile cannot see, because the label IS declared.
+ */
+export declare function sharedLabelMessage(label: string, connectorKey: string, others: readonly string[], files: readonly string[]): string;
+/** bindings.json already binds the label to a connection of ANOTHER connector: refused, the row is left as it is. */
+export declare function labelTakenMessage(label: string, connectorKey: string, existingId: string, existingConnector: string, bindingsShown: string): string;
+/** `--bind-connection`/`--bind-folder` names a label the source does not use for this connector. */
+export declare function flagDiffersFromSourceLine(attribute: "connection" | "folder", flag: string, labels: readonly string[], files: readonly string[]): string;
+/** One label was read and bound, but another call's could not be: the line names that call. */
+export declare function partlyUnreadableLabelLine(attribute: "connection" | "folder", label: string, reasons: readonly string[]): string;
+/** A label that could not be read statically: the default is bound, and the line says why. */
+export declare function unreadableLabelLine(attribute: "connection" | "folder", fallback: string, reasons: readonly string[]): string;
 /** `_missing_generic_schema_message`: a Generic action that expanded to nothing. */
 export declare function missingGenericSchemaMessage(operation: string, objectName?: string | null): string;
 /** One `registry get` probe that missed, as a refusal quotes it. */

package/dist/registry/prepare/messages.js

@@ -62,6 +62,68 @@ export function connectionLine(row, connectionId) {
 export function bindingsLine(symbolicName, bindingsPath) {
     return `  bindings: ${symbolicName} -> ${bindingsPath}`;
 }
+/** ` (the label Demo.flow.ts uses)` — appended to a bindings line whose name came from the source. */
+export function sourceLabelSuffix(files) {
+    return ` (the label ${files.join(", ")} ${files.length === 1 ? "uses" : "use"})`;
+}
+/**
+ * The source uses several labels for this one connector, and one prepare binds one
+ * connection: refused before any tenant call or write, with the command for each.
+ */
+export function ambiguousLabelsMessage(attribute, connectorKey, action, labels, command) {
+    const flag = attribute === "connection" ? "--bind-connection" : "--bind-folder";
+    const files = [...new Set([...labels.values()].flat())];
+    const lines = [...labels.keys()].map((label) => `  ${command} ${connectorKey} ${action} ${flag} ${label} --connection-id <id>`);
+    return prefixed(`${files.join(", ")} ${files.length === 1 ? "uses" : "use"} ${labels.size} ${attribute} labels for ${connectorKey} `
+        + `(${[...labels.keys()].join(", ")}), and one prepare binds one ${attribute === "connection" ? "connection" : "folder key"}. `
+        + `Bind each label to the connection it means, one run per label:\n${lines.join("\n")}\n`
+        + (files.length > 1
+            ? `The labels come from different files; if only one of them is the flow you are preparing, `
+                + `pass --source <file> to read just that one.\n`
+            : "")
+        + "Nothing was written.");
+}
+/**
+ * The source gives this connector's steps a connection label that steps of another
+ * connector use too. One label binds one connection id, so one of them would dial the
+ * other's connection — a mismatch compile cannot see, because the label IS declared.
+ */
+export function sharedLabelMessage(label, connectorKey, others, files) {
+    return prefixed(`${files.join(", ")} ${files.length === 1 ? "uses" : "use"} connection label "${label}" for ${connectorKey} and for `
+        + `${others.join(", ")}. One bindings.json label binds one connection, so one of those steps would run on the `
+        + `other connector's connection. Give each connector its own label in the source (for example `
+        + `connection: '${afterLastDash(connectorKey)}') and re-run, or pass --bind-connection <label> to choose the name `
+        + "yourself. Nothing was written.");
+}
+/** bindings.json already binds the label to a connection of ANOTHER connector: refused, the row is left as it is. */
+export function labelTakenMessage(label, connectorKey, existingId, existingConnector, bindingsShown) {
+    return prefixed(`${bindingsShown} already binds "${label}" to ${existingId}, a ${existingConnector} connection. Writing this `
+        + `${connectorKey} connection under the same label would repoint every ${existingConnector} step that uses it. `
+        + `Give the ${connectorKey} steps their own label in the source, or pass --bind-connection <label>. Nothing was written.`);
+}
+/** `--bind-connection`/`--bind-folder` names a label the source does not use for this connector. */
+export function flagDiffersFromSourceLine(attribute, flag, labels, files) {
+    const option = attribute === "connection" ? "--bind-connection" : "--bind-folder";
+    return `  WARN: ${option} ${flag}, but ${files.join(", ")} ${files.length === 1 ? "uses" : "use"} ${attribute} `
+        + `${labels.map((l) => `"${l}"`).join(", ")} for this connector; compile refuses a label bindings.json does not `
+        + `declare (BINDING_UNDECLARED), so make the two match`;
+}
+/** One label was read and bound, but another call's could not be: the line names that call. */
+export function partlyUnreadableLabelLine(attribute, label, reasons) {
+    return `  bindings: bound under "${label}", the ${attribute} label the source uses; could not read one more `
+        + `(${reasons[0]}${reasons.length > 1 ? `, and ${reasons.length - 1} more` : ""}) — if that step is this `
+        + `connector's under another label, compile refuses it (BINDING_UNDECLARED)`;
+}
+/** A label that could not be read statically: the default is bound, and the line says why. */
+export function unreadableLabelLine(attribute, fallback, reasons) {
+    const option = attribute === "connection" ? "--bind-connection" : "--bind-folder";
+    return `  bindings: could not read the ${attribute} label the source uses (${reasons[0]}${reasons.length > 1 ? `, and ${reasons.length - 1} more` : ""}); `
+        + `bound under "${fallback}" — pass ${option} <label> if the source uses another`;
+}
+function afterLastDash(key) {
+    const i = key.lastIndexOf("-");
+    return i >= 0 ? key.slice(i + 1) : key;
+}
 // ---------------------------------------------------------------------------
 // Refusals of the action path
 /** `_missing_generic_schema_message`: a Generic action that expanded to nothing. */

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

@@ -12,9 +12,12 @@ export interface PrepareOptions {
     connection?: string;
     /** `--bindings` (default `./bindings.json`). */
     bindings?: string;
-    /** `--bind-connection` (default: the connector's last dash-segment). */
+    /**
+     * `--bind-connection`. Default: the one `connection:` label the source already
+     * uses for this connector, else the connector's last dash-segment.
+     */
     bindConnection?: string;
-    /** `--bind-folder` (default `shared`). */
+    /** `--bind-folder`. Default: the one `folder:` label the source uses for this connector, else `shared`. */
     bindFolder?: string;
     noBindings?: boolean;
     /** `--object`; mutually exclusive with `allObjects`. */

package/dist/registry/prepare/pipeline.js

@@ -24,7 +24,9 @@
  * into the lines verbatim, as `args.out` and `args.bindings` did — while the
  * file system is reached through paths resolved against `cwd`.
  */
+import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { GUID_RE } from "../../core/binding-messages.js";
 import { PACKAGE_NAME } from "../../package-name.js";
 import { afterLast } from "../compat/pystr.js";
 import { extractCanonical, isHttpPassthrough, nodeOf } from "../library-build/canonical.js";
@@ -34,17 +36,18 @@ import { expandGenericForConnector, genericTemplatesByOp } from "../library-buil
 import { planLibrary } from "../library-build/plan.js";
 import { MemoryResponseCache } from "../uip/response-cache.js";
 import { registryCatalog } from "./actions.js";
-import { discoverConnection, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, } from "./connections.js";
+import { discoverConnection, listConnections, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, } from "./connections.js";
 import { prepareEvent } from "./event.js";
 import { descriptorUsage } from "./handoff.js";
 import { ResolutionsExhausted, allParentsResolved, resolvedParentValues, writeResolutions } from "./ledger.js";
-import { PREPARE_COMMAND, PrepareRefusal, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, keptSchemaMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, tsNote, unresolvedOperationMessage, } from "./messages.js";
+import { PREPARE_COMMAND, PrepareRefusal, ambiguousLabelsMessage, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, sharedLabelMessage, sourceLabelSuffix, tsNote, partlyUnreadableLabelLine, unreadableLabelLine, unresolvedOperationMessage, } from "./messages.js";
 import { ObjectMatchRefusal, RESOLUTIONS_FILENAME, matchObject, recordObjectResolution } from "./objects.js";
 import { countInputFields, keepPreparedSchema, lookupSpecsFromOverlay, mergeFilesInto, parentFields as overlayParentFields, schemaActionParents, } from "./overlay.js";
 import { declaredParents, objectActionRequest, objectActionSpecs, parseFields } from "./parents.js";
 import { regenerateDescriptors } from "./regenerate.js";
 import { retryOtherConnections } from "./retry.js";
 import { repointSource } from "./source-import.js";
+import { sourceBindingLabels } from "./source-labels.js";
 import { isPlainObject, pyGet, pyOr, pyPathJoin, pyPathlibStr, pyStrAny, pyTruthy } from "./support.js";
 function memoryCaches() {
     return { registry: new MemoryResponseCache(), is: new MemoryResponseCache(), connectors: new MemoryResponseCache() };
@@ -83,9 +86,111 @@ export async function matchCatalogObject(ctx, connectorKey, wanted, verb) {
     }
     return undefined;
 }
+/**
+ * The names to bind under, settled BEFORE any tenant call or write, so a refusal
+ * here leaves the tenant unasked and bindings.json as it was.
+ *
+ * Per attribute: the flag; else the ONE label the source already uses for this
+ * connector; else the old default (the key's last dash-segment, `shared`). The
+ * source is parsed, never run (source-labels.ts). Several labels for one
+ * connector are refused rather than picked — binding one would leave the others
+ * to compile's BINDING_UNDECLARED — and so is a connection label the source also
+ * gives another connector's steps, since one label binds one connection id. A
+ * label that cannot be read statically keeps the default and says why — unless
+ * one label WAS read, which is then bound, with a line naming the unread call.
+ */
+function chooseLabels(options, ports) {
+    const info = (line) => ports.reporter.info(line);
+    const warn = (line) => ports.reporter.warn(line);
+    const command = ports.prepareCommand ?? PREPARE_COMMAND;
+    const labels = sourceBindingLabels({
+        cwd: ports.cwd ?? process.cwd(),
+        out: options.out ?? "./connectors-local",
+        connectorKey: options.connectorKey,
+        source: options.source,
+    });
+    // `args.bind_connection or …`: an empty --bind-connection falls back, as Python's
+    // `or` did. --bind-folder was an argparse default, so an empty one STANDS.
+    const flags = {
+        connection: pyTruthy(options.bindConnection) ? options.bindConnection : undefined,
+        folder: options.bindFolder,
+    };
+    const defaults = { connection: afterLast(options.connectorKey, "-"), folder: "shared" };
+    const chosen = {};
+    for (const attribute of ["connection", "folder"]) {
+        const found = labels[attribute];
+        const files = [...new Set([...found.values()].flat())];
+        const flag = flags[attribute];
+        if (flag !== undefined) {
+            if (found.size > 0 && !found.has(flag))
+                warn(flagDiffersFromSourceLine(attribute, flag, [...found.keys()], files));
+            chosen[attribute] = flag;
+            continue;
+        }
+        if (found.size > 1) {
+            throw new PrepareRefusal(ambiguousLabelsMessage(attribute, options.connectorKey, options.action, found, command), "BINDING_LABEL_AMBIGUOUS");
+        }
+        const unreadable = labels.unreadable[attribute];
+        if (found.size === 1) {
+            const [label] = found.keys();
+            const others = attribute === "connection" ? labels.otherConnectors.get(label) : undefined;
+            if (others && others.size > 0) {
+                throw new PrepareRefusal(sharedLabelMessage(label, options.connectorKey, [...others], files), "BINDING_LABEL_SHARED");
+            }
+            // One readable label wins over the default even when another call could not
+            // be read: the default is certain to miss the step that WAS read, while the
+            // unread call, if it is this connector's under another label, is compile's
+            // BINDING_UNDECLARED. The line says which call was not read.
+            if (unreadable.length > 0)
+                info(partlyUnreadableLabelLine(attribute, label, unreadable));
+            chosen[attribute] = label;
+            chosen[attribute === "connection" ? "connectionFrom" : "folderFrom"] = files;
+            continue;
+        }
+        if (unreadable.length > 0) {
+            info(unreadableLabelLine(attribute, defaults[attribute], unreadable));
+            chosen[attribute] = defaults[attribute];
+            continue;
+        }
+        chosen[attribute] = defaults[attribute];
+    }
+    return chosen;
+}
+/**
+ * Refuse to overwrite a label that bindings.json already binds to ANOTHER
+ * connector's connection. Only for a label read from the source: that is the
+ * route that can collide by accident (two connectors named after one display
+ * name, `is-sandboxes`), and compile cannot see the result, because the label IS
+ * declared. The same connector's other connection under the same label is a
+ * reconfigure and is written as before; so is a stub or an unlisted id. The one
+ * extra listing happens only when the row exists with a different real id.
+ */
+async function refuseLabelOfAnotherConnector(client, connectorKey, label, connectionId, bindingsPath, bindingsShown) {
+    if (!existsSync(bindingsPath))
+        return;
+    let entries;
+    try {
+        entries = JSON.parse(readFileSync(bindingsPath, "utf8"))?.bindings;
+    }
+    catch {
+        return; // mergeBindings refuses an unreadable file with its own message
+    }
+    if (!Array.isArray(entries))
+        return;
+    const row = entries.find((e) => isPlainObject(e) && (e.name === label || e.id === label));
+    const existing = typeof row?.resourceKey === "string" ? row.resourceKey : undefined;
+    if (!existing || existing === connectionId || !GUID_RE.test(existing))
+        return;
+    const owner = (await listConnections(client, { allFolders: true })).find((r) => pyStrAny(r.Id) === existing);
+    const ownerKey = owner ? pyStrAny(owner.ConnectorKey) : "";
+    if (ownerKey && ownerKey !== connectorKey) {
+        throw new PrepareRefusal(labelTakenMessage(label, connectorKey, existing, ownerKey, bindingsShown), "BINDING_LABEL_TAKEN");
+    }
+}
 /** Stage 0: the connection, discovered or checked, and its row in `bindings.json`. */
 async function connect(options, ports) {
     const info = (line) => ports.reporter.info(line);
+    const labels = options.noBindings ? undefined : chooseLabels(options, ports);
     let row;
     let connectionId;
     if (!options.connectionId) {
@@ -102,25 +207,25 @@ async function connect(options, ports) {
         row = await lookupConnection(ports.client, options.connectorKey, connectionId);
     }
     info(connectionLine(row, connectionId));
-    if (options.noBindings)
+    if (!labels)
         return { connectionId, row };
     // Recorded on BOTH routes. Until 3.30.5 only discovery wrote it, and the
     // explicit-id route left the author hand-writing the id and folder key.
     const bindingsShown = options.bindings ?? "./bindings.json";
     const bindingsPath = resolve(ports.cwd ?? process.cwd(), bindingsShown);
+    if (labels.connectionFrom) {
+        await refuseLabelOfAnotherConnector(ports.client, options.connectorKey, labels.connection, connectionId, bindingsPath, bindingsShown);
+    }
     // Taken before the first write so a later refusal can undo exactly this
     // command's changes, and only them.
     const rollback = { path: bindingsPath, snapshot: snapshotBindings(bindingsPath), shown: bindingsShown };
-    // `args.bind_connection or args.key.rsplit("-", 1)[-1]`: an empty
-    // --bind-connection falls back, as Python's `or` did. --bind-folder is an
-    // argparse default, so an empty one STANDS, as it did there.
-    const symbolic = pyOr(options.bindConnection, afterLast(options.connectorKey, "-"));
-    const folder = options.bindFolder ?? "shared";
+    const symbolic = labels.connection;
+    const folder = labels.folder;
     const [wroteConnection, wroteFolder] = mergeBindings(bindingsPath, symbolic, folder, row);
     if (wroteConnection)
-        info(bindingsLine(symbolic, bindingsShown));
+        info(bindingsLine(symbolic, bindingsShown) + (labels.connectionFrom ? sourceLabelSuffix(labels.connectionFrom) : ""));
     if (wroteFolder)
-        info(bindingsLine(folder, bindingsShown));
+        info(bindingsLine(folder, bindingsShown) + (labels.folderFrom ? sourceLabelSuffix(labels.folderFrom) : ""));
     return { connectionId, row, bound: { connection: symbolic, folder }, rollback };
 }
 /**
@@ -188,7 +293,10 @@ export async function prepareConnector(options, ports) {
         // per command is the whole contract: the probe has already proved this
         // connection resolves every lookup, so a re-run that still cannot is a
         // changed tenant, not another connection to go looking through.
-        return prepareConnector({ ...options, connectionId: chosenId, refreshLookups: true }, ports);
+        // The labels this run chose ride along as flags, so the re-entry binds under
+        // the same names instead of deriving them again.
+        const labels = connected.bound ? { bindConnection: connected.bound.connection, bindFolder: connected.bound.folder } : {};
+        return prepareConnector({ ...options, ...labels, connectionId: chosenId, refreshLookups: true }, ports);
     }
 }
 /** Everything after stage 0, against one settled connection. */

package/dist/registry/prepare/source-import.d.ts

@@ -16,6 +16,8 @@ export declare function canonicalPath(p: string): string;
  * A bare package specifier never does — it is not our overlay.
  */
 export declare function resolvesTo(specifier: string, source: string, target: string): boolean;
+/** Every `*.flow.ts` file under `root`, sorted, skipping the directories a source is never in. */
+export declare function flowSources(root: string): string[];
 /**
  * `_sources_importing`: every `*.flow.ts` under `root` whose import resolves
  * to `baked`. Selection is by CONTENT rather than "the single flow in this

package/dist/registry/prepare/source-import.js

@@ -67,7 +67,7 @@ function comparePaths(a, b) {
     return a.length - b.length;
 }
 /** Every `*.flow.ts` file under `root`, sorted, skipping the directories a source is never in. */
-function flowSources(root) {
+export function flowSources(root) {
     const found = [];
     const walk = (dir, parts) => {
         let children;

package/dist/registry/prepare/source-labels.d.ts

@@ -0,0 +1,24 @@
+export interface SourceLabels {
+    /** Distinct connection labels this connector's steps use → the files (relative to cwd) that use each. */
+    connection: Map<string, string[]>;
+    /** Distinct folder labels this connector's steps use → the files that use each. */
+    folder: Map<string, string[]>;
+    /** Connection labels that steps of OTHER connectors use in the same sources → those connector keys. */
+    otherConnectors: Map<string, Set<string>>;
+    /** Why a label for this connector could not be read, one sentence each, per attribute. */
+    unreadable: {
+        connection: string[];
+        folder: string[];
+    };
+}
+export interface SourceLabelOptions {
+    /** The project root (`prepare`'s cwd). */
+    cwd: string;
+    /** The overlay directory (`--out`), relative to `cwd` or absolute. */
+    out: string;
+    connectorKey: string;
+    /** `--source`: read only this file. Otherwise every `*.flow.ts` under `cwd`. */
+    source?: string | null;
+}
+/** Every label the sources under `cwd` (or `--source`) use for `connectorKey`. Reads files, writes nothing. */
+export declare function sourceBindingLabels(options: SourceLabelOptions): SourceLabels;

package/dist/registry/prepare/source-labels.js

@@ -0,0 +1,346 @@
+/**
+ * Which `connection:` / `folder:` labels the author's `.flow.ts` already uses for
+ * ONE connector — read statically, so `prepare` can write its bindings.json
+ * entries under those names instead of inventing its own.
+ *
+ * Why this exists: `prepare` named the entries after the connector key alone
+ * (`slack`, `shared`), while the source it then repointed said
+ * `connection: 'is-sandboxes'`. Two authorities chose one name, and the mismatch
+ * reached the run as `'Connection' has an invalid GUID value: 'is-sandboxes'`
+ * (skill-flow-e2e-escalation-orchestrator-paths, 2026-09-23).
+ *
+ * The source is PARSED with the TypeScript compiler, never executed: at prepare
+ * time its other connector imports may not resolve yet, and running an author's
+ * module to learn a string is not this command's business. A label is attributed
+ * to a connector only through what the call names:
+ *
+ * - `connector('<key>', '<action>', inputs, opts)` — the stringly form, also
+ *   written `connector(...KEY, inputs, opts)` over a same-file const tuple
+ *   (`const KEY = ['<key>', '<action>'] as const`);
+ * - `connector(Descriptor, inputs, opts)` — `Descriptor` imported from
+ *   `./connectors/<key>.ts` or the prepared `<out>/<key>.ts` (named or namespace
+ *   import), so a source that a first `prepare` already repointed is still read;
+ * - `onEvent(...)` / `waitForEvent(...)` — a subscription object whose
+ *   `connector` is `'<key>'`, or a descriptor imported as above with its options.
+ *
+ * `opts` and the labels in it may be literals or same-file `const`s, through
+ * `as const`, `satisfies`, parentheses, spreads of such consts, and property
+ * reads (`OUTLOOK.connection`). Anything else — a computed value, a spread of
+ * something that is not a same-file const, a call whose connector cannot be
+ * named (a descriptor from a module that is not a generated connector module, a
+ * spread of an imported tuple), a file that does not parse — is reported as
+ * UNREADABLE, never guessed, so the caller can fall back and say why. An
+ * unplaceable call is reported for every connector key, because it may be this
+ * one's step.
+ *
+ * Managed HTTP steps (`http({ managed: true, connection, folder })`) are not
+ * read: they name no connector key to attribute a label to. `check` and
+ * `compile` still refuse an undeclared label there (BINDING_UNDECLARED).
+ * GUID-shaped labels are dropped: they are resource keys written directly, not
+ * names to bind.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { basename, dirname, extname, resolve } from "node:path";
+import * as ts from "typescript";
+import { GUID_RE } from "../../core/binding-messages.js";
+import { relativePosix } from "../compat/paths.js";
+import { canonicalPath, flowSources } from "./source-import.js";
+const CALLEES = new Set(["connector", "onEvent", "waitForEvent"]);
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Every label the sources under `cwd` (or `--source`) use for `connectorKey`. Reads files, writes nothing. */
+export function sourceBindingLabels(options) {
+    const result = { connection: new Map(), folder: new Map(), otherConnectors: new Map(), unreadable: { connection: [], folder: [] } };
+    const root = canonicalPath(options.cwd);
+    const moduleDirs = [canonicalPath(resolve(root, "connectors")), canonicalPath(resolve(options.cwd, options.out))];
+    let files;
+    if (options.source) {
+        const one = canonicalPath(resolve(options.cwd, options.source));
+        files = isFile(one) ? [one] : [];
+    }
+    else {
+        files = flowSources(root);
+    }
+    for (const file of files) {
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch {
+            continue; // unreadable: it cannot be the author's working source
+        }
+        readFile(file, relativePosix(root, file), text, options.connectorKey, moduleDirs, result);
+    }
+    return result;
+}
+/** The connector key a module specifier names, when it is one of the generated connector modules. */
+function connectorModuleKey(specifier, from, moduleDirs) {
+    if (!specifier.startsWith("."))
+        return undefined;
+    let target = canonicalPath(resolve(dirname(from), specifier));
+    if (extname(target) === "")
+        target = `${target}.ts`;
+    if (extname(target) !== ".ts" && extname(target) !== ".js")
+        return undefined;
+    if (!moduleDirs.includes(dirname(target)))
+        return undefined;
+    return basename(target).replace(/\.(ts|js)$/, "");
+}
+function unwrap(expr) {
+    let e = expr;
+    for (;;) {
+        if (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isSatisfiesExpression(e)
+            || ts.isNonNullExpression(e) || ts.isTypeAssertionExpression(e)) {
+            e = e.expression;
+        }
+        else {
+            return e;
+        }
+    }
+}
+function propertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name))
+        return name.text;
+    return undefined;
+}
+function readFile(file, shown, text, connectorKey, moduleDirs, result) {
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    // `parseDiagnostics` is where the scanner records syntax problems (see core/expr-check.ts).
+    const problems = sf.parseDiagnostics;
+    if (problems && problems.length > 0) {
+        if (text.includes(connectorKey)) {
+            const why = `${shown} does not parse, so its labels could not be read`;
+            result.unreadable.connection.push(why);
+            result.unreadable.folder.push(why);
+        }
+        return;
+    }
+    // Imports of generated connector modules: local name → key, and namespace name → key.
+    const named = new Map();
+    const namespaces = new Map();
+    // Same-file consts: name → initializer, or `null` when declared more than once.
+    const consts = new Map();
+    const visitDecls = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const key = connectorModuleKey(node.moduleSpecifier.text, file, moduleDirs);
+            const clause = node.importClause;
+            if (key && clause?.namedBindings) {
+                if (ts.isNamespaceImport(clause.namedBindings))
+                    namespaces.set(clause.namedBindings.name.text, key);
+                else
+                    for (const el of clause.namedBindings.elements)
+                        named.set(el.name.text, key);
+            }
+        }
+        if (ts.isVariableDeclarationList(node) && (node.flags & ts.NodeFlags.Const) !== 0) {
+            for (const d of node.declarations) {
+                if (!ts.isIdentifier(d.name) || !d.initializer)
+                    continue;
+                consts.set(d.name.text, consts.has(d.name.text) ? null : d.initializer);
+            }
+        }
+        ts.forEachChild(node, visitDecls);
+    };
+    visitDecls(sf);
+    const constObject = (expr, depth = 0) => {
+        const e = unwrap(expr);
+        if (ts.isObjectLiteralExpression(e))
+            return e;
+        if (depth < 8 && ts.isIdentifier(e)) {
+            const init = consts.get(e.text);
+            if (init)
+                return constObject(init, depth + 1);
+        }
+        return undefined;
+    };
+    const prop = (obj, name, depth = 0) => {
+        let found = { kind: "absent" };
+        for (const p of obj.properties) {
+            if (ts.isPropertyAssignment(p) && propertyName(p.name) === name)
+                found = { kind: "found", expr: p.initializer };
+            else if (ts.isShorthandPropertyAssignment(p) && p.name.text === name)
+                found = { kind: "found", expr: p.name };
+            else if (ts.isSpreadAssignment(p)) {
+                const inner = depth < 8 ? constObject(p.expression) : undefined;
+                if (!inner)
+                    found = { kind: "unknown", why: `a spread of \`${p.expression.getText(sf).slice(0, 60)}\`` };
+                else {
+                    const got = prop(inner, name, depth + 1);
+                    if (got.kind !== "absent")
+                        found = got;
+                }
+            }
+        }
+        return found;
+    };
+    const constString = (expr, depth = 0) => {
+        const e = unwrap(expr);
+        if (ts.isStringLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e))
+            return e.text;
+        if (depth >= 8)
+            return undefined;
+        if (ts.isIdentifier(e)) {
+            const init = consts.get(e.text);
+            return init ? constString(init, depth + 1) : undefined;
+        }
+        if (ts.isPropertyAccessExpression(e)) {
+            const obj = constObject(e.expression);
+            if (!obj)
+                return undefined;
+            const got = prop(obj, e.name.text);
+            return got.kind === "found" ? constString(got.expr, depth + 1) : undefined;
+        }
+        return undefined;
+    };
+    /** The connector key a descriptor expression was imported for. */
+    const descriptorKey = (expr) => {
+        const e = unwrap(expr);
+        if (ts.isIdentifier(e))
+            return named.get(e.text);
+        if (ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression))
+            return namespaces.get(e.expression.text);
+        return undefined;
+    };
+    const add = (map, label) => {
+        const files = map.get(label) ?? [];
+        if (!files.includes(shown))
+            files.push(shown);
+        map.set(label, files);
+    };
+    const snippet = (node) => {
+        const t = node.getText(sf).replace(/\s+/g, " ");
+        return t.length > 60 ? `${t.slice(0, 57)}...` : t;
+    };
+    const where = (node, callee) => `${shown}:${sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1} ${callee}(…)`;
+    /** Record one call's labels, attributed to `key`. `opts` undefined = the call passes none. */
+    const record = (key, opts, at) => {
+        if (opts === undefined)
+            return;
+        const obj = constObject(opts);
+        if (key !== connectorKey) {
+            // Only the connection label matters across connectors: a folder is shared by design.
+            if (!obj)
+                return;
+            const got = prop(obj, "connection");
+            const label = got.kind === "found" ? constString(got.expr) : undefined;
+            if (label !== undefined && !GUID_RE.test(label)) {
+                const keys = result.otherConnectors.get(label) ?? new Set();
+                keys.add(key);
+                result.otherConnectors.set(label, keys);
+            }
+            return;
+        }
+        if (!obj) {
+            const why = `${at} passes its options as \`${snippet(unwrap(opts))}\`, which is not a same-file object`;
+            result.unreadable.connection.push(why);
+            result.unreadable.folder.push(why);
+            return;
+        }
+        for (const attribute of ["connection", "folder"]) {
+            const got = prop(obj, attribute);
+            if (got.kind === "absent")
+                continue;
+            if (got.kind === "unknown") {
+                result.unreadable[attribute].push(`${at} takes its ${attribute} from ${got.why}`);
+                continue;
+            }
+            const label = constString(got.expr);
+            if (label === undefined) {
+                result.unreadable[attribute].push(`${at} computes its ${attribute} (\`${snippet(unwrap(got.expr))}\`)`);
+                continue;
+            }
+            if (GUID_RE.test(label))
+                continue;
+            add(result[attribute], label);
+        }
+    };
+    /**
+     * The call's arguments with spreads of same-file const arrays expanded
+     * (`connector(...SLACK, inputs, opts)`), or why a spread could not be.
+     */
+    const expandArgs = (args, depth = 0) => {
+        const out = [];
+        for (const a of args) {
+            if (!ts.isSpreadElement(a)) {
+                out.push(a);
+                continue;
+            }
+            const arr = depth < 8 ? constArray(a.expression) : undefined;
+            if (!arr)
+                return { why: `spreads \`${snippet(a.expression)}\`, which is not a same-file const array` };
+            const inner = expandArgs(arr.elements, depth + 1);
+            if (!Array.isArray(inner))
+                return inner;
+            out.push(...inner);
+        }
+        return out;
+    };
+    const constArray = (expr, depth = 0) => {
+        const e = unwrap(expr);
+        if (ts.isArrayLiteralExpression(e))
+            return e;
+        if (depth < 8 && ts.isIdentifier(e)) {
+            const init = consts.get(e.text);
+            if (init)
+                return constArray(init, depth + 1);
+        }
+        return undefined;
+    };
+    /** A call whose connector cannot be named may be this connector's: it makes every label unreadable. */
+    const unplaceable = (at, why) => {
+        const line = `${at} ${why}, so which connector it binds cannot be read`;
+        result.unreadable.connection.push(line);
+        result.unreadable.folder.push(line);
+    };
+    const visitCalls = (node) => {
+        if (ts.isCallExpression(node)) {
+            const callee = ts.isIdentifier(node.expression)
+                ? node.expression.text
+                : ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : undefined;
+            if (callee && CALLEES.has(callee) && node.arguments.length > 0) {
+                const at = where(node, callee);
+                const args = expandArgs(node.arguments);
+                if (!Array.isArray(args))
+                    unplaceable(at, args.why);
+                else if (args.length === 0)
+                    unplaceable(at, "spreads an empty array");
+                else if (callee === "connector") {
+                    const [first] = args;
+                    const literalKey = constString(first);
+                    const key = literalKey ?? descriptorKey(first);
+                    if (key === undefined)
+                        unplaceable(at, `names its connector as \`${snippet(unwrap(first))}\`, which is neither a string nor a descriptor imported from a generated connector module`);
+                    else
+                        record(key, args[literalKey !== undefined ? 3 : 2], at);
+                }
+                else {
+                    const [first] = args;
+                    const subscription = constObject(first);
+                    if (subscription) {
+                        const got = prop(subscription, "connector");
+                        const key = got.kind === "found" ? constString(got.expr) : undefined;
+                        if (key)
+                            record(key, first, at);
+                        else
+                            unplaceable(at, got.kind === "absent" ? "passes a subscription with no `connector`" : "computes its subscription's `connector`");
+                    }
+                    else {
+                        const key = descriptorKey(first);
+                        if (key)
+                            record(key, args[1], at);
+                        else
+                            unplaceable(at, `takes \`${snippet(unwrap(first))}\`, which is neither a same-file subscription object nor a descriptor imported from a generated connector module`);
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visitCalls);
+    };
+    visitCalls(sf);
+}

package/dist/serialize.js

@@ -14,7 +14,7 @@ import { Expr, toExpr, SCHEDULE_PRESETS, DELAY_PRESETS, parseIxpProjectType, fla
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { dataFabricUnknownInputs } from './core/typed-raw-node.js';
-import { bindingSelfNameMessage } from './core/binding-messages.js';
+import { BindingRefusal, GUID_RE, bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
 import { OUTCOME_HANDLE_NODE_TYPES, assertHitlExitInvariant, hitlExitModel, hitlExitViolation, outcomeSlug } from './core/hitl-routing.js';
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { buildConfiguration, transportHttpMethod } from './config.js';
@@ -3064,8 +3064,6 @@ function renderValue(val, rename = NO_RENAME) {
         return val.literal ? val.value : '=js:' + renameRefs(val.js, rename);
     return val;
 }
-/** A tenant resource key — an Integration Service connection id or an Orchestrator folder key — is a GUID. */
-const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * The all-zero prefix authors reach for when they need "a GUID" and have none:
  * `00000000-0000-0000-0000-000000000001`. No tenant issues these. The same
@@ -3087,6 +3085,12 @@ function connectionStubReason(value) {
         return 'not a GUID';
     return undefined;
 }
+/** What `registry prepare` takes for an event subscription: its connector key and curated event name. */
+function eventTarget(sub) {
+    return typeof sub.connector === 'string' && sub.connector !== ''
+        ? { key: sub.connector, ...(typeof sub.event === 'string' && sub.event !== '' ? { action: sub.event } : {}) }
+        : undefined;
+}
 /**
  * Resolve a symbolic connection/folder name to the resource key that is inlined
  * as `connectionId` / `connectionFolderKey`.
@@ -3100,30 +3104,55 @@ function connectionStubReason(value) {
  * `bindings.json` that never declares the name, and one that declares it with
  * its own name as the `resourceKey`.
  *
- * Only the SELF-REFERENTIAL case is an error here. Emitting the symbolic name
- * when nothing resolves it is long-established and deliberate — compiling
- * against partial or absent bindings is how a flow is authored offline, and the
- * name is the only honest placeholder available. A binding that declares the
- * name and then answers with the name is different: someone wrote the entry, so
- * the intent to bind is explicit, and the one thing it cannot mean is "the
- * resource key is the string `is-sandboxes`".
+ * Two cases are errors here, and they are the two where the author's intent to
+ * bind is on record and the emitted value still cannot be a resource key:
+ *
+ * - SELF-REFERENTIAL (`BINDING_SELF_NAME`): an entry declares the name and then
+ *   answers with the name. Someone wrote the entry, and the one thing it cannot
+ *   mean is "the resource key is the string `is-sandboxes`".
+ * - UNDECLARED IN A POPULATED FILE (`BINDING_UNDECLARED`): bindings.json declares
+ *   entries, none of them answers to this label, and the label is not itself a
+ *   GUID. The file is the author's statement of what is bound, so a label it
+ *   does not carry is a mismatch between two names for one connection, not
+ *   offline authoring. Measured: the 2026-09-23 orchestrator-paths run bound
+ *   `slack` (prepare's default label) while the source said `is-sandboxes`;
+ *   compile warned, exited 0, and the Slack node answered `400 'Connection' has
+ *   an invalid GUID value: 'is-sandboxes'`. Across the eval archive this shape
+ *   warned 15 times; 13 were fixed before the final compile and the 2 that were
+ *   not are that row's failures (09-18, 09-23) — no green run shipped it.
  *
  * Everything else that cannot be a resource key is a WARNING (`CONNECTION_STUB`),
- * never an error: an unbound symbol, an all-zero GUID, an `<angle>` placeholder,
- * a label. The archive shows those in green runs of simulated and validate-only
- * tasks, where no connection exists to bind — refusing them would push an author
- * with nothing real to bind into inventing a plausible GUID instead, which is
- * worse because nothing can tell. But the 2026-09-01 orchestrator-paths run
- * compiled `00000000-0000-0000-0000-000000000001` with no signal at all and the
- * Slack node answered `401 Invalid Organization or User secret` at dispatch;
- * the author deserves to hear that BEFORE the run.
+ * never an error: a symbol when NO bindings.json is loaded or it declares no
+ * entries, an entry declared without a resourceKey, an all-zero GUID, an
+ * `<angle>` placeholder, a label. Compiling against absent bindings is how a flow
+ * is authored offline, and the name is the only honest placeholder available;
+ * the archive shows those in green runs of simulated and validate-only tasks,
+ * where no connection exists to bind. Refusing them would push an author with
+ * nothing real to bind into inventing a plausible GUID instead, which is worse
+ * because nothing can tell. That is also the route for a connector that is not
+ * bound YET in a file that binds others (a two-connector flow with one prepared,
+ * or a simulated connector next to real ones): declare its label with a
+ * placeholder resourceKey and it stays a warning. Mid-loop compiles took that
+ * state in three archived runs (ipe-drive-to-slack 09-23 `drive`, ipe-jira-
+ * lifecycle 09-04 `entra`, customer-escalation-simulated 09-03 `zendesk`), and
+ * each fixed it before the final compile, so what now costs one refused compile
+ * there was never shipped. The 2026-09-01 orchestrator-paths run compiled
+ * `00000000-0000-0000-0000-000000000001` with no signal at all and the Slack node
+ * answered `401 Invalid Organization or User secret` at dispatch; the author
+ * deserves to hear that BEFORE the run.
  */
-function resolveBinding(opts, name, attribute, where) {
+function resolveBinding(opts, name, attribute, where, target) {
     if (name === undefined)
         return undefined;
     const resolved = opts.bindings?.resolve(name);
     if (resolved === name) {
-        throw new Error(bindingSelfNameMessage(where, name, attribute));
+        throw new BindingRefusal('BINDING_SELF_NAME', bindingSelfNameMessage(where, name, attribute, target));
+    }
+    if (resolved === undefined) {
+        const declared = undeclaredBinding(opts.bindings, name);
+        if (declared) {
+            throw new BindingRefusal('BINDING_UNDECLARED', bindingUndeclaredMessage(where, name, attribute, declared, target));
+        }
     }
     const value = resolved ?? name;
     const reason = connectionStubReason(value);
@@ -3136,8 +3165,10 @@ function resolveBinding(opts, name, attribute, where) {
             + `and writes both entries into bindings.json (several candidates: pass \`--connection-id <id>\` from the list it `
             + `prints); by hand, read Id and FolderKey from \`uip is connections list --all-folders --output json\`.`;
         const message = resolved === undefined
-            ? `${where}: ${attribute} "${name}" has no bindings.json entry`
-                + `${describeDeclared(opts.bindings)}, so the .flow carries the symbolic name as its ${key} and the run `
+            ? `${where}: ${declaredWithoutKey(opts.bindings, name)
+                ? `binding "${name}" is declared in bindings.json with no resourceKey`
+                : `${attribute} "${name}" has no bindings.json entry${describeDeclared(opts.bindings)}`}`
+                + `, so the .flow carries the symbolic name as its ${key} and the run `
                 + `faults at dispatch with ${fault}. ${remedy}`
             : `${where}: binding "${name}" resolves to "${value}", which is ${reason} and so never a tenant ${key}. `
                 + `The .flow carries it and the run faults at dispatch with ${fault}. ${remedy}`;
@@ -3145,6 +3176,10 @@ function resolveBinding(opts, name, attribute, where) {
     }
     return value;
 }
+/** An entry answers to `name` but carries no resourceKey or default — the placeholder route, still a warning. */
+function declaredWithoutKey(bindings, name) {
+    return (bindings?.declared?.() ?? []).includes(name) || bindings?.entry?.(name) !== undefined;
+}
 /** " (bindings.json declares: a, b)" / " (no bindings.json was loaded)" — what the author CAN refer to. */
 function describeDeclared(bindings) {
     const names = bindings?.declared?.() ?? [];
@@ -3282,8 +3317,8 @@ function flattenWhere(where, declared) {
     return out;
 }
 function eventDetail(rc, sub, nodeId, opts) {
-    const conn = resolveBinding(opts, sub.connection, 'connection', `event node "${nodeId}"`);
-    const folder = resolveBinding(opts, sub.folder, 'folder', `event node "${nodeId}"`);
+    const conn = resolveBinding(opts, sub.connection, 'connection', `event node "${nodeId}"`, eventTarget(sub));
+    const folder = resolveBinding(opts, sub.folder, 'folder', `event node "${nodeId}"`, eventTarget(sub));
     const op = (rc.entry?.operation ?? {});
     const filters = sub.filters ?? [];
     // A GENERIC event (`activityType: GenericTrigger` — Data Fabric, Salesforce,
@@ -4106,8 +4141,8 @@ export function serialize(built, opts = {}) {
         const { entries } = connectionResourceBindings({
             def: eventTriggerRc.v1def,
             connectorKey: eventTriggerRc.connectorKey,
-            connectionId: resolveBinding(opts, sub.connection, 'connection', 'event trigger'),
-            folderKey: resolveBinding(opts, sub.folder, 'folder', 'event trigger'),
+            connectionId: resolveBinding(opts, sub.connection, 'connection', 'event trigger', eventTarget(sub)),
+            folderKey: resolveBinding(opts, sub.folder, 'folder', 'event trigger', eventTarget(sub)),
         }, resourceBindings);
         for (const b of entries)
             resourceBindings.set(b.id, b);
@@ -4231,8 +4266,8 @@ export function serialize(built, opts = {}) {
             const id = stepUid(scope, step.name);
             const node = makeNode(rc.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def: rc.v1def });
             declareListOutputType(node, rc);
-            const conn = resolveBinding(opts, spec.connection, 'connection', `connector "${step.name}"`);
-            const folder = resolveBinding(opts, spec.folder, 'folder', `connector "${step.name}"`);
+            const conn = resolveBinding(opts, spec.connection, 'connection', `connector "${step.name}"`, { key: spec.key, action: spec.action });
+            const folder = resolveBinding(opts, spec.folder, 'folder', `connector "${step.name}"`, { key: spec.key, action: spec.action });
             // The platform reaches the connection through the flow's `bindings[]`,
             // never through `inputs.detail` — without this pair the run faults with
             // `[102010]` (board G-19; see connectionResourceBindings).
@@ -5131,8 +5166,8 @@ export function serialize(built, opts = {}) {
             const { entries: waitConnBindings } = connectionResourceBindings({
                 def: rc.v1def,
                 connectorKey: rc.connectorKey,
-                connectionId: resolveBinding(opts, sub.connection, 'connection', `waitForEvent "${step.name}"`),
-                folderKey: resolveBinding(opts, sub.folder, 'folder', `waitForEvent "${step.name}"`),
+                connectionId: resolveBinding(opts, sub.connection, 'connection', `waitForEvent "${step.name}"`, eventTarget(sub)),
+                folderKey: resolveBinding(opts, sub.folder, 'folder', `waitForEvent "${step.name}"`, eventTarget(sub)),
             }, resourceBindings);
             for (const b of waitConnBindings)
                 resourceBindings.set(b.id, b);
@@ -5986,8 +6021,8 @@ export function serialize(built, opts = {}) {
                 const { entries } = connectionResourceBindings({
                     def: rc.v1def,
                     connectorKey: rc.connectorKey,
-                    connectionId: resolveBinding(opts, sub.connection, 'connection', 'onEvent() entry point'),
-                    folderKey: resolveBinding(opts, sub.folder, 'folder', 'onEvent() entry point'),
+                    connectionId: resolveBinding(opts, sub.connection, 'connection', 'onEvent() entry point', eventTarget(sub)),
+                    folderKey: resolveBinding(opts, sub.folder, 'folder', 'onEvent() entry point', eventTarget(sub)),
                 }, resourceBindings);
                 for (const b of entries)
                     resourceBindings.set(b.id, b);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.9.0",
+  "version": "6.9.2",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "b7baf691c4126ec18eb3388d0d0a70b09301f24d"
+  "gitref": "25a192425e3db19a8df8f2c9aafc897c051dac02"
 }