@uipath/maestro-builder-sdk 6.14.2 → 6.14.4

package/dist/bindings-v2.d.ts

@@ -13,6 +13,22 @@ export interface BindingsV2Document {
     resources: BindingsV2Resource[];
     [k: string]: unknown;
 }
+/**
+ * Which connector each bound connection belongs to, keyed by connection id —
+ * decided by EVERY node on the connection, so the answer does not depend on
+ * which step comes first.
+ *
+ * `bindings.json` cannot answer this: `prepare --connection-id` writes a label,
+ * a resource key and a kind (`ConnectionId` / `FolderKey`), never the connector
+ * (see `core/binding-messages.ts`). The nodes are the only record of it, so
+ * all of them must agree. Two that do not — a Drive step and a Slack step on
+ * one connection, or managed HTTP whose `targetConnector` is not the connection's
+ * connector — are refused with `CONNECTION_CONNECTOR_CONFLICT`: at most one of
+ * them can run, and picking the first silently mislabels the solution resource.
+ *
+ * @throws BindingRefusal when two nodes on one connection name different connectors.
+ */
+export declare function connectionConnectors(flow: unknown): Map<string, string>;
 /**
  * The `connection` resources a compiled flow declares — one per distinct
  * connection, in node order, attributed to the FIRST node that uses it.
@@ -20,6 +36,16 @@ export interface BindingsV2Document {
  * Both halves of that are pack's behaviour, not a choice made here: a flow with
  * two Outlook steps on one connection yields a single resource whose
  * `ActivityName` is the earlier step's.
+ *
+ * What the resource IS does not follow node order: its `Connector` comes from
+ * {@link connectionConnectors} (every node on the connection, managed HTTP read
+ * through its `targetConnector`). Pack stamps the same value — measured with
+ * `uip maestro flow pack` on managed HTTP → Slack alone, before a native Slack
+ * step, and after one: `uipath-salesforce-slack` all three times, where this
+ * module used to stamp `uipath-uipath-http` for the first two (#866;
+ * uip 1.202.0-dev, 2026-09-30).
+ *
+ * @throws BindingRefusal when two nodes on one connection name different connectors.
  */
 export declare function connectionResources(flow: unknown): BindingsV2Resource[];
 /**

package/dist/bindings-v2.js

@@ -42,6 +42,7 @@
  * the connection rows.
  */
 import { existsSync, readFileSync } from 'node:fs';
+import { BindingRefusal, connectionConnectorConflictMessage } from './core/binding-messages.js';
 /** The document version pack emits. */
 const DOCUMENT_VERSION = '2.0';
 /** The per-resource metadata version pack stamps. */
@@ -56,6 +57,93 @@ function str(value) {
 function isConnection(resource) {
     return typeof resource === 'string' && resource.toLowerCase() === 'connection';
 }
+/** The managed-HTTP wrapper's own connector key — never the connection's type when a target is named. */
+const MANAGED_HTTP_CONNECTOR = 'uipath-uipath-http';
+function nodeDetail(node) {
+    return isRecord(node.inputs) && isRecord(node.inputs.detail) ? node.inputs.detail : undefined;
+}
+/** The connection a node runs on: `connectionId`, else `connectionResourceId`. */
+function nodeConnectionKey(detail) {
+    return str(detail.connectionId) ?? str(detail.connectionResourceId);
+}
+/**
+ * The connector a node's CONNECTION belongs to — not the connector the node is.
+ *
+ * The two differ for managed HTTP: its `detail.connector` is always the wrapper,
+ * `uipath-uipath-http`, and the connection it authenticates with is the one
+ * `bodyParameters.targetConnector` names (`uipath-google-drive`,
+ * `uipath-salesforce-slack`, …). Stamping the wrapper made `uip solution
+ * resources refresh` refuse the connection — "Requested type
+ * 'uipath-uipath-http'; the resource is registered as type
+ * 'uipath-google-drive'" (flow-builder-sdk#866). Every other family's
+ * `detail.connector` is its connection's connector.
+ */
+function nodeConnectionConnector(detail) {
+    const connector = str(detail.connector);
+    if (connector === MANAGED_HTTP_CONNECTOR && isRecord(detail.bodyParameters)) {
+        return str(detail.bodyParameters.targetConnector) ?? connector;
+    }
+    return connector;
+}
+/** Every node of the flow and of its inline subflows — they share one `bindings[]`. */
+function allNodes(flow) {
+    const nodes = Array.isArray(flow.nodes) ? flow.nodes.filter(isRecord) : [];
+    if (isRecord(flow.subflows)) {
+        for (const sub of Object.values(flow.subflows)) {
+            if (isRecord(sub) && Array.isArray(sub.nodes))
+                nodes.push(...sub.nodes.filter(isRecord));
+        }
+    }
+    return nodes;
+}
+/**
+ * Which connector each bound connection belongs to, keyed by connection id —
+ * decided by EVERY node on the connection, so the answer does not depend on
+ * which step comes first.
+ *
+ * `bindings.json` cannot answer this: `prepare --connection-id` writes a label,
+ * a resource key and a kind (`ConnectionId` / `FolderKey`), never the connector
+ * (see `core/binding-messages.ts`). The nodes are the only record of it, so
+ * all of them must agree. Two that do not — a Drive step and a Slack step on
+ * one connection, or managed HTTP whose `targetConnector` is not the connection's
+ * connector — are refused with `CONNECTION_CONNECTOR_CONFLICT`: at most one of
+ * them can run, and picking the first silently mislabels the solution resource.
+ *
+ * @throws BindingRefusal when two nodes on one connection name different connectors.
+ */
+export function connectionConnectors(flow) {
+    const out = new Map();
+    if (!isRecord(flow))
+        return out;
+    const bound = new Set();
+    for (const b of Array.isArray(flow.bindings) ? flow.bindings.filter(isRecord) : []) {
+        const key = str(b.resourceKey);
+        if (key && isConnection(b.resource) && str(b.propertyAttribute)?.toLowerCase() === 'connectionid')
+            bound.add(key);
+    }
+    const users = new Map();
+    for (const node of allNodes(flow)) {
+        const detail = nodeDetail(node);
+        const key = detail && nodeConnectionKey(detail);
+        if (!detail || !key || !bound.has(key))
+            continue;
+        const connector = nodeConnectionConnector(detail);
+        if (!connector)
+            continue;
+        const byConnector = users.get(key) ?? new Map();
+        users.set(key, byConnector);
+        const steps = byConnector.get(connector) ?? [];
+        steps.push((isRecord(node.display) ? str(node.display.label) : undefined) ?? str(node.id) ?? '?');
+        byConnector.set(connector, steps);
+    }
+    for (const [key, byConnector] of users) {
+        if (byConnector.size > 1) {
+            throw new BindingRefusal('CONNECTION_CONNECTOR_CONFLICT', connectionConnectorConflictMessage(key, byConnector));
+        }
+        out.set(key, [...byConnector.keys()][0]);
+    }
+    return out;
+}
 /**
  * The `connection` resources a compiled flow declares — one per distinct
  * connection, in node order, attributed to the FIRST node that uses it.
@@ -63,6 +151,16 @@ function isConnection(resource) {
  * Both halves of that are pack's behaviour, not a choice made here: a flow with
  * two Outlook steps on one connection yields a single resource whose
  * `ActivityName` is the earlier step's.
+ *
+ * What the resource IS does not follow node order: its `Connector` comes from
+ * {@link connectionConnectors} (every node on the connection, managed HTTP read
+ * through its `targetConnector`). Pack stamps the same value — measured with
+ * `uip maestro flow pack` on managed HTTP → Slack alone, before a native Slack
+ * step, and after one: `uipath-salesforce-slack` all three times, where this
+ * module used to stamp `uipath-uipath-http` for the first two (#866;
+ * uip 1.202.0-dev, 2026-09-30).
+ *
+ * @throws BindingRefusal when two nodes on one connection name different connectors.
  */
 export function connectionResources(flow) {
     if (!isRecord(flow))
@@ -78,25 +176,31 @@ export function connectionResources(flow) {
             continue;
         if (str(binding.propertyAttribute)?.toLowerCase() !== 'connectionid')
             continue;
-        if (!byKey.has(key))
-            byKey.set(key, binding);
+        byKey.set(key, [...(byKey.get(key) ?? []), binding]);
     }
     if (byKey.size === 0)
         return [];
+    const connectors = connectionConnectors(flow);
     const nodes = Array.isArray(flow.nodes) ? flow.nodes.filter(isRecord) : [];
     const resources = [];
     const seen = new Set();
     for (const node of nodes) {
-        const detail = isRecord(node.inputs) && isRecord(node.inputs.detail) ? node.inputs.detail : undefined;
+        const detail = nodeDetail(node);
         if (!detail)
             continue;
-        const key = str(detail.connectionId) ?? str(detail.connectionResourceId);
+        const key = nodeConnectionKey(detail);
         if (!key || seen.has(key))
             continue;
-        const binding = byKey.get(key);
-        if (!binding)
+        const candidates = byKey.get(key);
+        if (!candidates)
             continue;
         seen.add(key);
+        const connector = connectors.get(key) ?? nodeConnectionConnector(detail) ?? '';
+        // The label is the FIRST ConnectionId binding on the connection, even when
+        // #865's fix emits one per referencing definition — measured against `uip
+        // maestro flow pack` (uip 1.202.0-dev) on both orders of the issue's repro: pack labels
+        // the resource after the earlier step's binding, like `ActivityName`.
+        const binding = candidates[0];
         const displayLabel = str(binding.name) ?? key;
         const label = isRecord(node.display) ? str(node.display.label) : undefined;
         resources.push({
@@ -116,7 +220,7 @@ export function connectionResources(flow) {
                 BindingsVersion: BINDINGS_VERSION,
                 DisplayLabel: displayLabel,
                 UseConnectionService: 'true',
-                Connector: str(detail.connector) ?? '',
+                Connector: connector,
             },
         });
     }

package/dist/check.js

@@ -11,7 +11,7 @@ import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './core/l
 import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
 import { extractRefs } from './core/expr-check.js';
-import { bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
+import { bindingSelfNameMessage, bindingUndeclaredMessage, connectionConnectorConflictMessage, undeclaredBinding } from './core/binding-messages.js';
 import { isAnswerField } from './core/hitl-answers.js';
 import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
 import { childStepLists, declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
@@ -20,7 +20,51 @@ import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js
 import { prepareCommand, resolveFlagArg } from './core/cli-spelling.js';
 import { EVENT_BYOA_UNVERIFIED, byoaUnverified } from './core/byoa.js';
 export function check(built, opts = {}) {
-    return checkFlow(built, [], opts);
+    const outer = connectionUsage;
+    connectionUsage = [];
+    try {
+        const diags = checkFlow(built, [], opts);
+        diags.push(...connectionConnectorConflicts(connectionUsage, opts));
+        return diags;
+    }
+    finally {
+        connectionUsage = outer;
+    }
+}
+/**
+ * The connection uses {@link checkBindingLabels} saw during the current
+ * `check()` — the flow and every child flow, which share one `bindings[]`.
+ * Module state rather than a `CheckOpts` field because `check` is synchronous
+ * and this is not an input; `check()` saves and restores it, so a nested call
+ * cannot mix two flows.
+ */
+let connectionUsage;
+/**
+ * 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 `.flow`.
+ */
+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.step]);
+    }
+    const out = [];
+    for (const [key, byConnector] of byConnection) {
+        if (byConnector.size < 2)
+            continue;
+        out.push({
+            level: 'error', code: 'CONNECTION_CONNECTOR_CONFLICT',
+            step: [...byConnector.values()][1][0],
+            message: connectionConnectorConflictMessage(key, byConnector),
+        });
+    }
+    return out;
 }
 /**
  * `ancestors` is the chain of child flows currently being checked, innermost
@@ -358,7 +402,10 @@ function checkFlow(built, ancestors, opts = {}) {
                     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 target = pair.targetConnector;
+                        checkBindingLabels(`managed http "${httpStep}"`, pair, opts, (code, message) => diags.push({ level: 'error', code, step: httpStep, message }), undefined, 
+                        // The connector its CONNECTION belongs to: the target, not the wrapper.
+                        { step: httpStep, connector: typeof target === 'string' && target !== '' ? target : 'uipath-uipath-http' });
                     }
                     const seen = new Set();
                     for (const b of s.spec.inputs.branches ?? []) {
@@ -537,7 +584,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));
+                    checkBindingLabels(`waitForEvent "${stepName}"`, s.spec.subscription, opts, push('error'), eventTarget(s.spec.subscription), { step: stepName, connector: eventTarget(s.spec.subscription)?.key });
                 }
                 if (s.spec.kind === 'subflow') {
                     // Only a real child goes in the map: a missing one is reported by
@@ -1453,7 +1500,7 @@ function checkConnectorContract(step, spec, opts, diags) {
     if (inputErr) {
         diags.push({ level: 'error', code: 'CONNECTOR_INPUT', step, message: `Connector step "${step}": ${inputErr}` });
     }
-    checkBindingLabels(`Connector step "${step}"`, spec, opts, (code, message) => diags.push({ level: 'error', code, step, message }), { key: spec.key, action: spec.action });
+    checkBindingLabels(`Connector step "${step}"`, spec, opts, (code, message) => diags.push({ level: 'error', code, step, message }), { key: spec.key, action: spec.action }, { step, connector: spec.key });
 }
 /** What `registry prepare` takes for an event subscription: its connector key and curated event name. */
 function eventTarget(sub) {
@@ -1472,7 +1519,13 @@ function eventTarget(sub) {
  * 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) {
+function checkBindingLabels(where, labels, opts, report, target, 
+/** The step, and the connector its connection must belong to, for CONNECTION_CONNECTOR_CONFLICT. */
+use) {
+    const label = labels?.connection;
+    if (use?.connector && typeof label === 'string' && label !== '') {
+        connectionUsage?.push({ step: use.step, label, connector: use.connector });
+    }
     const bindings = opts.bindings;
     if (!bindings || !labels)
         return;
@@ -2285,7 +2338,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));
+        checkBindingLabels('event trigger', sub, opts, at, eventTarget(sub), { step: 'trigger', connector: eventTarget(sub)?.key });
         return;
     }
     // manual() is the explicit spelling of the default — nothing to validate.

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

@@ -1,7 +1,11 @@
 /** 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';
+export type BindingRefusalCode = 'BINDING_SELF_NAME' | 'BINDING_UNDECLARED'
+/** An emitted definition's `<bindings.NAME>` placeholder has no `bindings[]` entry named NAME (#865). */
+ | 'BINDING_PLACEHOLDER_UNRESOLVED'
+/** Two steps on one connection disagree on which connector it belongs to (#866). */
+ | 'CONNECTION_CONNECTOR_CONFLICT';
 /**
  * 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`
@@ -58,3 +62,14 @@ export interface PrepareTarget {
  * `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;
+/**
+ * Why compile refuses one connection used by steps of different connectors —
+ * shared by `serialize` (which throws it, via `connectionConnectors` in
+ * `bindings-v2.ts`) and `check`, so both print the same sentence.
+ *
+ * `users` maps each connector to the steps that use the connection as that
+ * connector. For managed HTTP the connector is its `targetConnector` — the
+ * connection it authenticates with — not the `uipath-uipath-http` wrapper
+ * (flow-builder-sdk#866).
+ */
+export declare function connectionConnectorConflictMessage(connection: string, users: ReadonlyMap<string, readonly string[]>): string;

package/dist/core/binding-messages.js

@@ -89,3 +89,24 @@ export function bindingUndeclaredMessage(where, name, attribute, declared, targe
         + `declares the label with a placeholder resourceKey instead, which compiles with a CONNECTION_STUB warning — `
         + `never an invented GUID.`;
 }
+/**
+ * Why compile refuses one connection used by steps of different connectors —
+ * shared by `serialize` (which throws it, via `connectionConnectors` in
+ * `bindings-v2.ts`) and `check`, so both print the same sentence.
+ *
+ * `users` maps each connector to the steps that use the connection as that
+ * connector. For managed HTTP the connector is its `targetConnector` — the
+ * connection it authenticates with — not the `uipath-uipath-http` wrapper
+ * (flow-builder-sdk#866).
+ */
+export function connectionConnectorConflictMessage(connection, users) {
+    const who = [...users]
+        .map(([connector, steps]) => `${steps.map((s) => `"${s}"`).join(', ')} as ${connector}`)
+        .join('; ');
+    return `connection "${connection}" is used by steps of different connectors (${who}). An Integration Service `
+        + `connection belongs to exactly one connector, so at most one of these steps can run on it, and the solution `
+        + `resource would be declared as whichever came first. Give each connector its own connection label in `
+        + `bindings.json (\`${prepareCommand('<connector-key>', '<action>')}\` binds one per connector). A managed `
+        + `\`http({ managed: true, … })\` step on another connector's connection must name that connector in `
+        + `\`targetConnector\`.`;
+}

package/dist/core/node-envelope.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The node envelope: the fields `uip maestro flow validate` requires on EVERY
+ * entry of a `.flow` file's `nodes[]` (root and every `subflows.<id>.nodes[]`),
+ * whatever its type.
+ *
+ * Mirrors the platform's file-format node schema (`@uipath/flow-schema`
+ * `fileFormatNodeSchema`, bundled into the CLI's flow tool):
+ *
+ * ```ts
+ * id:          z.string().min(1)
+ * type:        z.string().min(1)
+ * typeVersion: z.string().regex(/^\d+\.\d+(\.\d+)?$/)
+ * display:     z.object({ … })            // required, may be {}
+ * ui:          { position: { x: number, y: number }, size?: { width, height } }  // optional in the file
+ * inputs?:     Record<string, unknown>
+ * outputs?:    Record<string, unknown>
+ * parentId?:   z.string().min(1)
+ * ```
+ *
+ * `makeNode` builds this shape for every definition-backed node, but a node
+ * built any other way (sticky notes were, issue #869) had nothing holding it
+ * to the contract: `check` passed, `compile` wrote the file, and only
+ * `flow validate` refused it. `serialize` runs this over every finished scope,
+ * so a missing field is an SDK emit bug caught before a file is written — on
+ * every path, `compile --no-check` and direct `serialize()` included.
+ */
+/** Every way `node` breaks the envelope, as `<field>: <problem>` strings. Empty when it conforms. */
+export declare function nodeEnvelopeProblems(node: unknown): string[];
+/**
+ * Throw if any node in one scope breaks the envelope. `where` names the scope
+ * (`flow "x"`, `subflow "call"`) so the message points at the file section
+ * `flow validate` would have reported.
+ */
+export declare function assertNodeEnvelope(nodes: readonly unknown[], where: string): void;

package/dist/core/node-envelope.js

@@ -0,0 +1,83 @@
+/**
+ * The node envelope: the fields `uip maestro flow validate` requires on EVERY
+ * entry of a `.flow` file's `nodes[]` (root and every `subflows.<id>.nodes[]`),
+ * whatever its type.
+ *
+ * Mirrors the platform's file-format node schema (`@uipath/flow-schema`
+ * `fileFormatNodeSchema`, bundled into the CLI's flow tool):
+ *
+ * ```ts
+ * id:          z.string().min(1)
+ * type:        z.string().min(1)
+ * typeVersion: z.string().regex(/^\d+\.\d+(\.\d+)?$/)
+ * display:     z.object({ … })            // required, may be {}
+ * ui:          { position: { x: number, y: number }, size?: { width, height } }  // optional in the file
+ * inputs?:     Record<string, unknown>
+ * outputs?:    Record<string, unknown>
+ * parentId?:   z.string().min(1)
+ * ```
+ *
+ * `makeNode` builds this shape for every definition-backed node, but a node
+ * built any other way (sticky notes were, issue #869) had nothing holding it
+ * to the contract: `check` passed, `compile` wrote the file, and only
+ * `flow validate` refused it. `serialize` runs this over every finished scope,
+ * so a missing field is an SDK emit bug caught before a file is written — on
+ * every path, `compile --no-check` and direct `serialize()` included.
+ */
+const TYPE_VERSION_RE = /^\d+\.\d+(\.\d+)?$/;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+/** Every way `node` breaks the envelope, as `<field>: <problem>` strings. Empty when it conforms. */
+export function nodeEnvelopeProblems(node) {
+    if (!isRecord(node))
+        return ['node: expected an object'];
+    const problems = [];
+    if (!isNonEmptyString(node.id))
+        problems.push('id: expected a non-empty string');
+    if (!isNonEmptyString(node.type))
+        problems.push('type: expected a non-empty string');
+    if (typeof node.typeVersion !== 'string' || !TYPE_VERSION_RE.test(node.typeVersion)) {
+        problems.push(`typeVersion: expected "x.y" or "x.y.z", got ${JSON.stringify(node.typeVersion)}`);
+    }
+    if (!isRecord(node.display))
+        problems.push('display: expected an object (may be empty)');
+    if (node.ui !== undefined) {
+        const pos = isRecord(node.ui) ? node.ui.position : undefined;
+        if (!isRecord(pos) || typeof pos.x !== 'number' || typeof pos.y !== 'number') {
+            problems.push('ui.position: expected { x: number, y: number }');
+        }
+        const size = isRecord(node.ui) ? node.ui.size : undefined;
+        if (size !== undefined && (!isRecord(size) || typeof size.width !== 'number' || typeof size.height !== 'number')) {
+            problems.push('ui.size: expected { width: number, height: number }');
+        }
+    }
+    if (node.inputs !== undefined && !isRecord(node.inputs))
+        problems.push('inputs: expected an object');
+    if (node.outputs !== undefined && !isRecord(node.outputs))
+        problems.push('outputs: expected an object');
+    if (node.parentId !== undefined && !isNonEmptyString(node.parentId)) {
+        problems.push('parentId: expected a non-empty string');
+    }
+    return problems;
+}
+/**
+ * Throw if any node in one scope breaks the envelope. `where` names the scope
+ * (`flow "x"`, `subflow "call"`) so the message points at the file section
+ * `flow validate` would have reported.
+ */
+export function assertNodeEnvelope(nodes, where) {
+    const bad = [];
+    nodes.forEach((n, i) => {
+        const problems = nodeEnvelopeProblems(n);
+        if (!problems.length)
+            return;
+        const id = isRecord(n) && typeof n.id === 'string' ? n.id : `#${i}`;
+        const type = isRecord(n) && typeof n.type === 'string' ? n.type : '?';
+        bad.push(`  node "${id}" (${type}): ${problems.join('; ')}`);
+    });
+    if (!bad.length)
+        return;
+    throw new Error(`internal SDK error: ${where} would emit ${bad.length} node(s) that \`uip maestro flow validate\` `
+        + `rejects — every node needs id, type, typeVersion and display:\n${bad.join('\n')}\n`
+        + `This is a serializer bug, not an authoring mistake; please report it.`);
+}

package/dist/serialize.d.ts

@@ -54,6 +54,34 @@ export declare function serializeWithSidecars(built: BuiltFlow, opts?: Serialize
     }>;
 };
 export declare function serialize(built: BuiltFlow, opts?: SerializeOpts): any;
+/**
+ * Every `<bindings.NAME>` placeholder a node's definition carries in its
+ * `model.context` must resolve to a `bindings[]` entry for THAT node.
+ *
+ * "Resolve" is Studio Web's rule, not a looser one: flow-v1
+ * `matchContextBindings` + `getInstanceBindingKey`
+ * (flow-schema/src/packaging/resolve-context.ts) take the entries whose
+ * `resource` EQUALS the definition's `model.bindings.resource`, scope them to the
+ * node's `inputs.detail.connectionResourceId` when that resource is `connection`
+ * (or undeclared), and look the placeholder up there BY NAME. Any miss blocks
+ * publish (MST-15010), and one that slips through reaches Studio as the literal
+ * placeholder: `invalid GUID <bindings.uipath-salesforce-slack connection>`.
+ * `uip maestro flow validate` does not check this.
+ *
+ * That is how #865 shipped — a per-call-site dedupe that let the first step on a
+ * shared connection claim it — and UV-16774 before it (a `Connection` resource
+ * spelling). Checking the finished document catches that class for every family
+ * and every emission order, whichever call site produced it.
+ *
+ * It holds for real definitions: of the 5,102 in the local registry index
+ * (2026-09-30), 4,999 reference a `<bindings.…>` name and every one of them
+ * declares that name in `model.bindings.values`, which is what the emitters
+ * close. Agent resource definitions are the one exemption (see below).
+ *
+ * @throws BindingRefusal `BINDING_PLACEHOLDER_UNRESOLVED`, naming each dangling
+ * placeholder and the step that carries it.
+ */
+export declare function assertBindingPlaceholdersResolve(flow: any): void;
 /**
  * What `compile` would refuse these connector inputs with, or `undefined` when it
  * would accept them — the SAME code path `buildConnectorInputs` runs at emit time,

package/dist/serialize.js

@@ -15,10 +15,12 @@ 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 { isAnswerField } from './core/hitl-answers.js';
+import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
 import { ByoaRefusal, byoaUnverified } from './core/byoa.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 { assertNodeEnvelope } from './core/node-envelope.js';
 import { buildConfiguration, transportHttpMethod } from './config.js';
 import { stableId } from './core/stable-id.js';
 import { readEventFilter, eventFilterProblem, eventFilterJmes, eventFilterTreeLeaf } from './event-filters.js';
@@ -2305,9 +2307,15 @@ function connectionResourceBindings(spec, existing) {
     if (values.length === 0)
         return { entries: [] };
     const resourceKey = spec.resourceKey ?? spec.connectionId ?? '';
-    const have = (attr) => [...existing.values()].some((b) => b.resource === 'connection' && b.resourceKey === resourceKey && b.propertyAttribute === attr);
-    if (have('ConnectionId') && have('FolderKey'))
-        return { entries: [] };
+    // Keyed on the NAME as well (flow-builder-sdk#865). The name is the definition's
+    // own `<bindings.NAME>` placeholder, and two definitions sharing one connection
+    // can spell it differently — managed HTTP says `uipath-uipath-http connection`,
+    // the Slack connector `uipath-salesforce-slack connection`. Keyed on
+    // resourceKey + attribute alone, whichever step came first claimed the
+    // connection and the other node's placeholder never resolved: Studio showed
+    // `invalid GUID <bindings.uipath-salesforce-slack connection>`.
+    const have = (name, attr) => [...existing.values()].some((b) => b.resource === 'connection' && b.name === name && b.resourceKey === resourceKey
+        && b.propertyAttribute === attr);
     const slug = spec.connectorKey.replace(/[^A-Za-z0-9]/g, '') || 'Connector';
     let base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}`;
     for (let n = 2; existing.has(`${base}Connection`) || existing.has(`${base}FolderKey`); n++) {
@@ -2316,7 +2324,7 @@ function connectionResourceBindings(spec, existing) {
     const entries = values.flatMap((v) => {
         const name = typeof v.name === 'string' ? v.name : '';
         const attr = v.propertyAttribute;
-        if (!name || (attr !== 'ConnectionId' && attr !== 'FolderKey') || have(attr))
+        if (!name || (attr !== 'ConnectionId' && attr !== 'FolderKey') || have(name, attr))
             return [];
         const isConnection = attr === 'ConnectionId';
         const dflt = isConnection ? spec.connectionId : spec.folderKey;
@@ -3063,6 +3071,8 @@ const ERROR_ENVELOPE_VAR = {
 function errorEnvelopeVar(nodeType) {
     return ERROR_ENVELOPE_VAR[nodeType];
 }
+/** The `typeVersion` Studio Web stamps on a sticky note. The type has no manifest to take it from. */
+const STICKY_NOTE_TYPE_VERSION = '1.0.0';
 /**
  * Append the flow's `.stickyNotes()` as real `stickyNote` nodes.
  *
@@ -3100,14 +3110,20 @@ function emitStickyNotes(built, scope) {
         if ((note.width === undefined) !== (note.height === undefined)) {
             throw new Error(`.stickyNotes(): note "${id}" needs both width and height, or neither.`);
         }
+        // The envelope Studio Web writes for a note (flow-v1 canvas: the add path
+        // sets `typeVersion: '1.0.0'` and no display, and `nodeToInstance` persists
+        // `display` as `{}`). Both fields are required on every node by
+        // `flow validate`, manifest or not (#869).
         scope.nodes.push({
             id,
             type: 'stickyNote',
-            inputs: { color: note.color ?? 'yellow', content: note.content },
+            typeVersion: STICKY_NOTE_TYPE_VERSION,
             ui: {
                 position: { x: note.x, y: note.y },
                 ...(note.width !== undefined ? { size: { width: note.width, height: note.height } } : {}),
             },
+            display: {},
+            inputs: { color: note.color ?? 'yellow', content: note.content },
         });
     });
 }
@@ -4184,6 +4200,7 @@ export function serialize(built, opts = {}) {
         typeAgentInputSchemas(scope, globals);
         emitStickyNotes(child, scope);
         const layoutEdges = applyAuthorLayout(child.layout, scope, `subflow "${nodeId}"`);
+        assertNodeEnvelope(scope.nodes, `subflow "${nodeId}"`);
         return {
             nodes: scope.nodes,
             edges: scope.edges,
@@ -6241,6 +6258,7 @@ export function serialize(built, opts = {}) {
     typeAgentInputSchemas(root, globals);
     emitStickyNotes(built, root);
     const rootLayoutEdges = applyAuthorLayout(built.layout, root, `flow "${built.id}"`);
+    assertNodeEnvelope(root.nodes, `flow "${built.id}"`);
     // The FILE-FORMAT version this document declares: the author's
     // `.schemaVersion()` when they set one, else the profile's write floor. It is
     // resolved HERE rather than in `check()` alone because the serializer must not
@@ -6269,8 +6287,84 @@ export function serialize(built, opts = {}) {
     // Passing the target is what lets a version-conditional step exist at all —
     // see migrate.ts's VERSION_CONDITIONAL ladder.
     migrateToSchemaVersion(flow, schemaVersion);
+    // Emitted-document invariants over connections, checked on the FINISHED file
+    // so every family and every emission order is covered by one rule, not by
+    // each call site remembering it (flow-builder-sdk#865/#866).
+    assertBindingPlaceholdersResolve(flow);
+    connectionConnectors(flow);
     return flow;
 }
+/**
+ * Every `<bindings.NAME>` placeholder a node's definition carries in its
+ * `model.context` must resolve to a `bindings[]` entry for THAT node.
+ *
+ * "Resolve" is Studio Web's rule, not a looser one: flow-v1
+ * `matchContextBindings` + `getInstanceBindingKey`
+ * (flow-schema/src/packaging/resolve-context.ts) take the entries whose
+ * `resource` EQUALS the definition's `model.bindings.resource`, scope them to the
+ * node's `inputs.detail.connectionResourceId` when that resource is `connection`
+ * (or undeclared), and look the placeholder up there BY NAME. Any miss blocks
+ * publish (MST-15010), and one that slips through reaches Studio as the literal
+ * placeholder: `invalid GUID <bindings.uipath-salesforce-slack connection>`.
+ * `uip maestro flow validate` does not check this.
+ *
+ * That is how #865 shipped — a per-call-site dedupe that let the first step on a
+ * shared connection claim it — and UV-16774 before it (a `Connection` resource
+ * spelling). Checking the finished document catches that class for every family
+ * and every emission order, whichever call site produced it.
+ *
+ * It holds for real definitions: of the 5,102 in the local registry index
+ * (2026-09-30), 4,999 reference a `<bindings.…>` name and every one of them
+ * declares that name in `model.bindings.values`, which is what the emitters
+ * close. Agent resource definitions are the one exemption (see below).
+ *
+ * @throws BindingRefusal `BINDING_PLACEHOLDER_UNRESOLVED`, naming each dangling
+ * placeholder and the step that carries it.
+ */
+export function assertBindingPlaceholdersResolve(flow) {
+    const bindings = Array.isArray(flow?.bindings) ? flow.bindings : [];
+    const defs = new Map();
+    for (const def of Array.isArray(flow?.definitions) ? flow.definitions : []) {
+        defs.set(`${def?.nodeType}@${def?.version}`, def);
+    }
+    const nodes = [...(Array.isArray(flow?.nodes) ? flow.nodes : [])];
+    for (const sub of Object.values(flow?.subflows ?? {})) {
+        if (Array.isArray(sub?.nodes))
+            nodes.push(...sub.nodes);
+    }
+    const dangling = [];
+    for (const node of nodes) {
+        // An agent's resource nodes (`uipath.agent.resource.tool.connector.…`) carry
+        // the same placeholders, but they are resolved through the AGENT project —
+        // `uip agent refresh` generates the connector tool's resource — and the
+        // deployed corpus carries no flow `bindings[]` entry for them.
+        if (typeof node?.type !== 'string' || node.type.startsWith('uipath.agent.resource.'))
+            continue;
+        const model = defs.get(`${node.type}@${node.typeVersion}`)?.model;
+        if (!Array.isArray(model?.context))
+            continue;
+        const resource = model.bindings?.resource;
+        const scope = resource === 'connection' || resource === undefined
+            ? node.inputs?.detail?.connectionResourceId ?? node.inputs?.connectionId ?? undefined
+            : undefined;
+        const candidates = resource === undefined ? bindings : bindings.filter((b) => b?.resource === resource);
+        for (const row of model.context) {
+            const name = typeof row?.value === 'string' ? /^<bindings\.(.+)>$/.exec(row.value)?.[1] : undefined;
+            if (name === undefined)
+                continue;
+            if (candidates.some((b) => b?.name === name && (!scope || b.resourceKey === scope)))
+                continue;
+            dangling.push(`step "${node.display?.label ?? node.id}" (${node.type}): "${row.value}"`
+                + `${scope ? ` on connection ${scope}` : ''}`);
+        }
+    }
+    if (dangling.length === 0)
+        return;
+    throw new BindingRefusal('BINDING_PLACEHOLDER_UNRESOLVED', `serialize: ${dangling.join('; ')} — no bindings[] entry of that name${dangling.length === 1 ? '' : ' (each)'} `
+        + `is emitted for the step, so Studio Web reads the placeholder itself as the value (`
+        + `"invalid GUID <bindings.…>") and refuses to publish. This is a serializer defect, not an authoring `
+        + `error; report it with the flow source.`);
+}
 /**
  * Validate a connector's activity inputs against its declared field list and
  * return them ROUTED to the wire slots the platform reads. Catches the three

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.14.2",
+  "version": "6.14.4",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "cb7a821ea17b6f3022c7b90e2567e91a5495576a"
+  "gitref": "deacd660d0428eb3144e4b61a76bbfbbfc87cbe8"
 }