@uipath/maestro-builder-sdk 6.68.2 → 6.68.4

package/dist/bindings-v2.d.ts

@@ -1,13 +1,6 @@
 import type { ConnectionUse } from './core/compile-refusal.js';
-/** One declared solution resource. */
-export interface BindingsV2Resource {
-    resource: string;
-    key: string;
-    id?: string;
-    value: Record<string, unknown>;
-    metadata: Record<string, unknown>;
-    [k: string]: unknown;
-}
+import { type BindingsV2Resource } from './core/bindings-v2-resource.js';
+export type { BindingsV2Resource };
 /** The `bindings_v2.json` document. */
 export interface BindingsV2Document {
     version: string;

package/dist/bindings-v2.js

@@ -55,10 +55,11 @@
  */
 import { BindingRefusal, connectionConnectorConflictMessage } from './core/binding-messages.js';
 import { isRecord } from './core/node-envelope.js';
+import { BINDINGS_V2_DOCUMENT_VERSION, connectionResource, RESOURCE_BINDINGS_VERSION, } from './core/bindings-v2-resource.js';
 /** The document version pack emits. */
-const DOCUMENT_VERSION = '2.0';
+const DOCUMENT_VERSION = BINDINGS_V2_DOCUMENT_VERSION;
 /** The per-resource metadata version pack stamps. */
-const BINDINGS_VERSION = '2.2';
+const BINDINGS_VERSION = RESOURCE_BINDINGS_VERSION;
 function nonEmptyString(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
@@ -235,26 +236,15 @@ export function connectionResources(flow) {
         const binding = candidates[0];
         const displayLabel = nonEmptyString(binding.name) ?? key;
         const label = isRecord(node.display) ? nonEmptyString(node.display.label) : undefined;
-        resources.push({
+        // The same row Case writes (core/bindings-v2-resource.ts); pack writes no folderKey slot.
+        resources.push(connectionResource({
             resource: 'connection',
             key,
-            // Pack concatenates resource and key with no separator for a connection.
-            id: `connection${key}`,
-            value: {
-                ConnectionId: {
-                    defaultValue: nonEmptyString(binding.default) ?? key,
-                    isExpression: false,
-                    displayName: displayLabel,
-                },
-            },
-            metadata: {
-                ActivityName: label ?? nonEmptyString(node.id) ?? key,
-                BindingsVersion: BINDINGS_VERSION,
-                DisplayLabel: displayLabel,
-                UseConnectionService: 'true',
-                Connector: connector,
-            },
-        });
+            connectionId: nonEmptyString(binding.default) ?? key,
+            displayLabel,
+            activityName: label ?? nonEmptyString(node.id) ?? key,
+            connector,
+        }));
     }
     return resources;
 }

package/dist/case/bindings-v2.d.ts

@@ -0,0 +1,3 @@
+import { type BindingsV2Resource } from '../core/bindings-v2-resource.js';
+/** Every resource the caseplan's root bindings declare, in the order their rows first appear. */
+export declare function deriveCaseBindingsV2(caseplan: Record<string, unknown>): BindingsV2Resource[];

package/dist/case/bindings-v2.js

@@ -0,0 +1,281 @@
+/**
+ * The `bindings_v2.json` resources a caseplan's root `bindings[]` rows declare:
+ * the root-row pass of `uip maestro case bindings sync` (`deriveCaseBindingsV2`
+ * in cli `packages/case-tool/src/services/case-bindings-service.ts`). It is
+ * NOT the whole CLI function; see "Not ported" below.
+ *
+ * `uip maestro case validate --strict` re-derives the sidecar with that
+ * function and compares it to the file on disk entry by entry, as serialized
+ * JSON (`STRICT_BINDINGS_SIDECAR_STALE`), so field order matters as well as
+ * field values. The CLI is a restricted package the SDK cannot depend on, so
+ * this is a copy; `tests/case-bindings-v2-parity.test.ts` holds it to the
+ * CLI's own output, one resource kind at a time, from a fixture the real CLI
+ * function derived. Re-record that fixture with
+ * `bun typescript/tests/fixtures/case-bindings-v2/record.ts <uipath-cli checkout>`.
+ *
+ * Every entry comes from the root `bindings[]` rows, grouped by
+ * `(resource, resourceKey)`:
+ *
+ *   - `Connection` → the connection row Flow writes too
+ *     ({@link connectionResource}); its connector and activity label come from
+ *     the connector context that references the row's binding id.
+ *   - `app` / `process` / `ixpDeployment` → the Case Designer shape.
+ *   - any other resource → the plain shape.
+ *
+ * Not ported — the CLI function's other passes:
+ *
+ *   - `EventTrigger` / `Property` entries for a connector start trigger
+ *     (`deriveEventTriggerResources`). The SDK writes these triggers, so this
+ *     is a live gap: builder-sdk#1557, a known-gap row in the parity test.
+ *   - The stored-binding overlay: entries a connector task keeps in its
+ *     `metadata` context's `body.bindings`, merged into the derived entry's
+ *     metadata or appended. The serializer's connector `metadata` body has no
+ *     `bindings` key, so there is nothing to overlay today.
+ *   - `Role` entries from `metadata.caseRoles`. The SDK neither authors nor
+ *     preserves `caseRoles` (it is not in preserve.ts's metadata keys).
+ *
+ * If the serializer starts writing either of the last two, port the pass and
+ * add a task for it to the parity fixture (`fixtures/case-bindings-v2/plan.ts`).
+ */
+import { isRecord } from '../core/node-envelope.js';
+import { connectionResource, RESOURCE_BINDINGS_VERSION, } from '../core/bindings-v2-resource.js';
+import { isInSolutionKey, SOLUTION_FOLDER } from './resource-identity.js';
+const CONNECTION_RESOURCE = 'Connection';
+/** The placeholder a manual-mode http-request task binds; nothing declares it. */
+const IMPLICIT_CONNECTION = 'ImplicitConnection';
+const CONNECTION_ID_ATTRIBUTE = 'ConnectionId';
+const FOLDER_KEY_ATTRIBUTE = 'folderKey';
+const BINDING_REFERENCE_PREFIX = '=bindings.';
+function asBindingRow(value) {
+    if (!isRecord(value))
+        return undefined;
+    return typeof value.id === 'string'
+        && typeof value.resource === 'string'
+        && typeof value.resourceKey === 'string'
+        && value.resourceKey !== ''
+        && typeof value.propertyAttribute === 'string'
+        && (value.default === undefined || typeof value.default === 'string')
+        ? value
+        : undefined;
+}
+/** Every resource the caseplan's root bindings declare, in the order their rows first appear. */
+export function deriveCaseBindingsV2(caseplan) {
+    const groups = new Map();
+    for (const entry of Array.isArray(caseplan.bindings) ? caseplan.bindings : []) {
+        const binding = asBindingRow(entry);
+        if (!binding)
+            continue;
+        if (binding.resource === CONNECTION_RESOURCE && binding.resourceKey === IMPLICIT_CONNECTION)
+            continue;
+        const groupKey = `${binding.resource}:${binding.resourceKey}`;
+        const group = groups.get(groupKey);
+        if (group)
+            group.push(binding);
+        else
+            groups.set(groupKey, [binding]);
+    }
+    const connectorUses = collectConnectorUses(caseplan);
+    const labels = bindingLabels(caseplan.nodes);
+    return [...groups.values()].map((group) => group[0].resource === CONNECTION_RESOURCE
+        ? connectionEntry(group, connectorUses)
+        : resourceEntry(group, labels));
+}
+function attributeDefault(group, attribute) {
+    return group.find((binding) => binding.propertyAttribute === attribute)?.default;
+}
+/**
+ * A connection: its `ConnectionId` row labels it, its `folderKey` row (keyed
+ * by the connection, not the folder) gives the folder slot.
+ */
+function connectionEntry(group, uses) {
+    const key = group[0].resourceKey;
+    const use = group.map((binding) => uses.get(binding.id)).find((found) => found !== undefined);
+    const label = (group.find((binding) => binding.propertyAttribute === CONNECTION_ID_ATTRIBUTE) ?? group[0]).name;
+    return connectionResource({
+        resource: CONNECTION_RESOURCE,
+        key,
+        connectionId: attributeDefault(group, CONNECTION_ID_ATTRIBUTE) ?? key,
+        ...(typeof label === 'string' && label !== '' && { displayLabel: label }),
+        folderKey: attributeDefault(group, FOLDER_KEY_ATTRIBUTE),
+        activityName: use?.activityName,
+        connector: use?.connectorKey,
+    });
+}
+/**
+ * The Case Designer's label for each value slot of an app or process entry.
+ * These resources get the Designer shape (cli#5003, MST-16424): an `id`, each
+ * slot flagged and labelled, and the `BindingsVersion` / `SolutionsSupport`
+ * metadata without which deploy cannot override the entry.
+ */
+const DESIGNER_SLOT_NAMES = new Map([
+    ['app', { name: 'App name', folderPath: 'Folder path', solutionsSupport: true }],
+    ['process', { name: 'Process name', folderPath: 'Folder path', solutionsSupport: true }],
+    ['ixpDeployment', { name: 'name', folderPath: 'Folder path', solutionsSupport: false }],
+]);
+/**
+ * One sidecar entry for a group of root binding rows that share a resource and
+ * a resource key. The subtype comes from the rows only: a Flow's rows carry
+ * none, so its entry has none either, as the Designer saves it.
+ *
+ * `metadata.ActivityName` labels a Designer-shaped entry with the first task
+ * that references one of its rows ({@link bindingLabels}).
+ */
+function resourceEntry(group, labels) {
+    const resource = group[0].resource;
+    const key = group[0].resourceKey;
+    // An in-solution resource binds an empty folderPath in the caseplan, while
+    // the sidecar names its folder by the sentinel the key carries.
+    const folderPath = isInSolutionKey(key) ? SOLUTION_FOLDER : attributeDefault(group, 'folderPath');
+    const name = attributeDefault(group, 'name');
+    const subType = group.map((binding) => binding.resourceSubType).find((found) => found !== undefined);
+    const designer = DESIGNER_SLOT_NAMES.get(resource);
+    if (designer) {
+        const value = {};
+        if (folderPath !== undefined) {
+            value.folderPath = { defaultValue: folderPath, isExpression: false, displayName: designer.folderPath };
+        }
+        if (name !== undefined) {
+            value.name = { defaultValue: name, isExpression: false, displayName: designer.name };
+        }
+        const activityName = group.map((binding) => labels.get(binding.id)).find((found) => found !== undefined);
+        return {
+            resource,
+            key,
+            id: `${resource}${key}`,
+            value,
+            metadata: {
+                ...(activityName !== undefined && { ActivityName: activityName }),
+                BindingsVersion: RESOURCE_BINDINGS_VERSION,
+                DisplayLabel: 'name',
+                ...(designer.solutionsSupport && { SolutionsSupport: 'true' }),
+                ...(subType !== undefined && { subType }),
+            },
+        };
+    }
+    const value = {};
+    if (name !== undefined)
+        value.name = { defaultValue: name };
+    if (folderPath !== undefined)
+        value.folderPath = { defaultValue: folderPath };
+    // A solution-resource picker (such as a Data Fabric entity) carries its folder key as a slot of its own.
+    const folderKey = attributeDefault(group, FOLDER_KEY_ATTRIBUTE);
+    if (folderKey !== undefined)
+        value.folderKey = { defaultValue: folderKey };
+    return {
+        resource,
+        key,
+        value,
+        metadata: {
+            BindingsVersion: RESOURCE_BINDINGS_VERSION,
+            ...(subType !== undefined && { subType }),
+        },
+    };
+}
+/** A task's or condition's `displayName`, a trigger's `display.label`, or a legacy node's `label`. */
+function ownLabel(node) {
+    const display = isRecord(node.display) ? node.display.label : undefined;
+    return [node.displayName, display, node.label].find((label) => typeof label === 'string' && label !== '');
+}
+/**
+ * Every value under `root`, each with the label of the nearest object above it
+ * that names itself ({@link ownLabel}) — the CLI's `walkLabelled`.
+ */
+function walkLabelled(root, visit) {
+    const walk = (node, label) => {
+        visit(node, label);
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item, label);
+            return;
+        }
+        if (!isRecord(node))
+            return;
+        const scoped = ownLabel(node) ?? label;
+        for (const value of Object.values(node))
+            walk(value, scoped);
+    };
+    walk(root, undefined);
+}
+/** A `{ name, value }` context array that names a connector, by entry name; else undefined. */
+function connectorContext(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const byName = new Map();
+    for (const entry of value) {
+        if (!isRecord(entry) || typeof entry.name !== 'string')
+            return undefined;
+        if (typeof entry.value === 'string')
+            byName.set(entry.name, entry.value);
+    }
+    return byName.has('connectorKey') ? byName : undefined;
+}
+function referencedBindingId(context) {
+    const connection = context?.get('connection');
+    return connection?.startsWith(BINDING_REFERENCE_PREFIX)
+        ? connection.slice(BINDING_REFERENCE_PREFIX.length)
+        : undefined;
+}
+/**
+ * The connector whose authentication an http-request task reuses: its `body`
+ * input's `targetConnector`. Its context names the generic HTTP connector
+ * whatever the request calls, while the connection belongs to the target.
+ */
+function httpTargetConnector(node) {
+    if (!isRecord(node) || node.type !== 'http-request' || !isRecord(node.data) || !Array.isArray(node.data.inputs)) {
+        return undefined;
+    }
+    for (const input of node.data.inputs) {
+        if (!isRecord(input) || input.name !== 'body' || !isRecord(input.body))
+            continue;
+        const target = input.body.targetConnector;
+        if (typeof target === 'string' && target !== '')
+            return target;
+    }
+    return undefined;
+}
+/**
+ * The connector of each connection binding, keyed by binding id, from the
+ * connector contexts that reference it (`connection: "=bindings.<id>"`). The
+ * first use wins, as the CLI's `collectConnectorKeys` decides it.
+ */
+function collectConnectorUses(caseplan) {
+    const byBindingId = new Map();
+    walkLabelled(caseplan, (node, label) => {
+        // Before the context array beneath it, which would otherwise claim the
+        // binding for the generic HTTP connector.
+        const target = httpTargetConnector(node);
+        if (target !== undefined && isRecord(node)) {
+            const data = node.data;
+            const bindingId = referencedBindingId(connectorContext(data.context));
+            if (bindingId !== undefined && !byBindingId.has(bindingId)) {
+                byBindingId.set(bindingId, { connectorKey: target, activityName: ownLabel(node) ?? label });
+            }
+        }
+        if (!Array.isArray(node))
+            return;
+        const context = connectorContext(node);
+        const connectorKey = context?.get('connectorKey');
+        const bindingId = referencedBindingId(context);
+        if (connectorKey !== undefined && bindingId !== undefined && !byBindingId.has(bindingId)) {
+            byBindingId.set(bindingId, { connectorKey, activityName: label });
+        }
+    });
+    return byBindingId;
+}
+/**
+ * The label of the first object that references each binding id
+ * (`=bindings.<id>`), in document order: the nearest enclosing `displayName`,
+ * `display.label` or `label`. The same walk as the CLI's
+ * `collectBindingLabels`, so both name an entry after the same task.
+ */
+function bindingLabels(nodes) {
+    const found = new Map();
+    walkLabelled(nodes ?? [], (node, label) => {
+        if (typeof node !== 'string' || label === undefined || !node.startsWith(BINDING_REFERENCE_PREFIX))
+            return;
+        const id = node.slice(BINDING_REFERENCE_PREFIX.length);
+        if (!found.has(id))
+            found.set(id, label);
+    });
+    return found;
+}

package/dist/case/check.js

@@ -3,7 +3,7 @@ import { ruleShapeProblems } from './rule-options.js';
 import { types } from '../core/expr.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS, authoredCaseVersion, caseVersionMismatch } from './format-profile.js';
 import { schemaVersionRefusal } from '../schema-version.js';
-import { caseJsonPreservation, caseJsonPreservationErrors } from './preserve.js';
+import { caseJsonPreservation, caseJsonPreservationErrors, preservedBindings } from './preserve.js';
 import { EQUALS_EXPR_DIALECT, checkBindingLabels, checkConnectorContract, checkConnectorLookups, checkConnectorSchema, } from '../core/connector-checks.js';
 import { checkEventResolution } from '../core/event-checks.js';
 import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT, EXTERNAL_TASK_HYBRID_UNSUPPORTED, externalHybridRefusal, isExternalExecutionMode } from './external.js';
@@ -25,6 +25,11 @@ const ILLEGAL = [];
  */
 export function check(built, opts = {}) {
     const diags = [];
+    // The same registry `serialize` resolves against, so the two agree on which
+    // labels a decompiled source's preserved binding rows answer.
+    const bindings = preservedBindings(opts.bindings, caseJsonPreservation(built));
+    if (bindings !== opts.bindings)
+        opts = { ...opts, bindings };
     for (const message of caseJsonPreservationErrors(caseJsonPreservation(built)))
         diags.push({
             level: 'error',

package/dist/case/compile-cli.js

@@ -29,9 +29,9 @@ import { defaultBindingsFile } from '../workdir.js';
 import { flagValue, runWhenInvokedDirectly } from '../cli-run.js';
 import { ensureTypeScriptRuntime } from '../node-runtime.js';
 import { CASE_FORMAT_PROFILE } from './format-profile.js';
-import { isInSolutionKey, SOLUTION_FOLDER } from './resource-identity.js';
+import { deriveCaseBindingsV2 } from './bindings-v2.js';
+import { BINDINGS_V2_DOCUMENT_VERSION } from '../core/bindings-v2-resource.js';
 import { sha256Uuid } from '../core/stable-id.js';
-import { isRecord } from '../core/node-envelope.js';
 export async function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.error('usage: compile <case.ts | BaseName> [-o <project>/caseplan.case]');
@@ -315,210 +315,16 @@ function syncEntryPoints(caseplan, outPath) {
  * artifact. `resources refresh` reads bindings_v2.json, not caseplan.json, and
  * succeeds with zero warnings when the sidecar is stale or empty.
  *
- * Non-connector resources come from the root binding rows only, as in
- * `uip maestro case bindings sync`.
- * A connector's connection and folder relationship comes from the context[]
- * that references both binding ids.
- * No-op when compiling outside a scaffolded project.
+ * The entries are what `uip maestro case bindings sync` derives
+ * ({@link deriveCaseBindingsV2}). No-op when compiling outside a scaffolded
+ * project.
  */
 function syncBindingsV2(caseplan, outPath) {
     const sidecarPath = join(dirname(outPath), 'bindings_v2.json');
     if (!existsSync(sidecarPath))
         return -1;
-    const bindings = Array.isArray(caseplan.bindings)
-        ? caseplan.bindings.filter(isRecord)
-        : [];
-    const byId = new Map(bindings
-        .filter((binding) => typeof binding.id === 'string')
-        .map((binding) => [binding.id, binding]));
-    const resources = [];
-    // One entry per (resource, resourceKey) group of root binding rows, in the
-    // shape `uip maestro case bindings sync` derives (`deriveCaseBindingsV2` in
-    // cli case-bindings-service.ts). `validate --strict` compares the two
-    // entry by entry as serialized JSON, so field order matters as well as
-    // field values.
-    const groups = new Map();
-    for (const binding of bindings) {
-        const resource = stringValue(binding.resource);
-        const key = stringValue(binding.resourceKey);
-        if (!resource || !key || typeof binding.propertyAttribute !== 'string')
-            continue;
-        if (resource.toLowerCase() === 'connection')
-            continue;
-        const groupKey = `${resource}\0${key}`;
-        const group = groups.get(groupKey);
-        if (group)
-            group.push(binding);
-        else
-            groups.set(groupKey, [binding]);
-    }
-    const seenConnections = new Set();
-    const connectionResources = [];
-    visitRecords(caseplan, (record) => {
-        if (!Array.isArray(record.context))
-            return;
-        const context = new Map(record.context
-            .filter(isRecord)
-            .filter((row) => typeof row.name === 'string')
-            .map((row) => [row.name, row.value]));
-        const connector = stringValue(context.get('connectorKey'));
-        const connectionId = referencedBindingValue(context.get('connection'), byId);
-        const folderKey = referencedBindingValue(context.get('folderKey'), byId);
-        if (!connector || !connectionId || !folderKey || seenConnections.has(connectionId))
-            return;
-        seenConnections.add(connectionId);
-        connectionResources.push({
-            resource: 'Connection',
-            key: connectionId,
-            value: {
-                connectionId: { defaultValue: connectionId },
-                folderKey: { defaultValue: folderKey },
-            },
-            metadata: { connector },
-        });
-    });
-    const labels = bindingLabels(caseplan.nodes);
-    for (const group of groups.values())
-        resources.push(sidecarResourceEntry(group, labels));
-    resources.push(...connectionResources);
-    writeJsonFile(sidecarPath, { version: '2.0', resources });
+    const resources = deriveCaseBindingsV2(caseplan);
+    writeJsonFile(sidecarPath, { version: BINDINGS_V2_DOCUMENT_VERSION, resources });
     return resources.length;
 }
-/**
- * The Case Designer's label for each value slot of an app or process entry.
- * These resources get the Designer shape (cli#5003, MST-16424): an `id`, each
- * slot flagged and labelled, and the `BindingsVersion` / `SolutionsSupport`
- * metadata without which deploy cannot override the entry.
- */
-const DESIGNER_SLOT_NAMES = new Map([
-    ['app', { name: 'App name', folderPath: 'Folder path', solutionsSupport: true }],
-    ['process', { name: 'Process name', folderPath: 'Folder path', solutionsSupport: true }],
-    ['ixpDeployment', { name: 'name', folderPath: 'Folder path', solutionsSupport: false }],
-]);
-/** The bindings version deploy needs to override an entry. */
-const RESOURCE_BINDINGS_VERSION = '2.2';
-/**
- * One sidecar entry for a group of root binding rows that share a resource and
- * a resource key. The subtype comes from the rows only: a Flow's rows carry
- * none, so its entry has none either, as the Designer saves it.
- *
- * `metadata.ActivityName` labels a Designer-shaped entry with the first task
- * that references one of its rows ({@link bindingLabels}).
- */
-function sidecarResourceEntry(group, labels) {
-    const resource = group[0].resource;
-    const key = group[0].resourceKey;
-    const attributeDefault = (attribute) => {
-        const found = group.find((binding) => binding.propertyAttribute === attribute)?.default;
-        return typeof found === 'string' ? found : undefined;
-    };
-    // An in-solution resource binds an empty folderPath in the caseplan, while
-    // the sidecar names its folder by the sentinel the key carries.
-    const folderPath = isInSolutionKey(key) ? SOLUTION_FOLDER : attributeDefault('folderPath');
-    const name = attributeDefault('name');
-    const subType = group.map((binding) => binding.resourceSubType).find((found) => found !== undefined);
-    const designer = DESIGNER_SLOT_NAMES.get(resource);
-    if (designer) {
-        const value = {};
-        if (folderPath !== undefined) {
-            value.folderPath = { defaultValue: folderPath, isExpression: false, displayName: designer.folderPath };
-        }
-        if (name !== undefined) {
-            value.name = { defaultValue: name, isExpression: false, displayName: designer.name };
-        }
-        const activityName = group
-            .map((binding) => (typeof binding.id === 'string' ? labels.get(binding.id) : undefined))
-            .find((found) => found !== undefined);
-        return {
-            resource,
-            key,
-            id: `${resource}${key}`,
-            value,
-            metadata: {
-                ...(activityName !== undefined && { ActivityName: activityName }),
-                BindingsVersion: RESOURCE_BINDINGS_VERSION,
-                DisplayLabel: 'name',
-                ...(designer.solutionsSupport && { SolutionsSupport: 'true' }),
-                ...(subType !== undefined && { subType }),
-            },
-        };
-    }
-    const value = {};
-    if (name !== undefined)
-        value.name = { defaultValue: name };
-    if (folderPath !== undefined)
-        value.folderPath = { defaultValue: folderPath };
-    // A solution-resource picker (such as a Data Fabric entity) carries its folder key as a slot of its own.
-    const folderKey = attributeDefault('folderKey');
-    if (folderKey !== undefined)
-        value.folderKey = { defaultValue: folderKey };
-    return {
-        resource,
-        key,
-        value,
-        metadata: {
-            BindingsVersion: RESOURCE_BINDINGS_VERSION,
-            ...(subType !== undefined && { subType }),
-        },
-    };
-}
-/**
- * The label of the first object that references each binding id
- * (`=bindings.<id>`), in document order: the nearest enclosing `displayName`,
- * `display.label` or `label`. The same walk as the CLI's
- * `collectBindingLabels`, so both name an entry after the same task.
- */
-function bindingLabels(nodes) {
-    const found = new Map();
-    const ownLabel = (node) => {
-        const display = isRecord(node.display) ? node.display.label : undefined;
-        return [node.displayName, display, node.label].map(stringValue).find((label) => label !== undefined);
-    };
-    const walk = (node, label) => {
-        if (typeof node === 'string') {
-            if (label !== undefined && node.startsWith('=bindings.')) {
-                const id = node.slice('=bindings.'.length);
-                if (!found.has(id))
-                    found.set(id, label);
-            }
-            return;
-        }
-        if (Array.isArray(node)) {
-            for (const item of node)
-                walk(item, label);
-            return;
-        }
-        if (!isRecord(node))
-            return;
-        const scoped = ownLabel(node) ?? label;
-        for (const value of Object.values(node))
-            walk(value, scoped);
-    };
-    walk(nodes ?? [], undefined);
-    return found;
-}
-function referencedBindingValue(value, bindings) {
-    const ref = stringValue(value);
-    if (!ref)
-        return undefined;
-    if (!ref.startsWith('=bindings.'))
-        return ref;
-    const binding = bindings.get(ref.slice('=bindings.'.length));
-    return binding && (stringValue(binding.default) ?? stringValue(binding.resourceKey));
-}
-function visitRecords(value, visit) {
-    if (Array.isArray(value)) {
-        for (const item of value)
-            visitRecords(item, visit);
-        return;
-    }
-    if (!isRecord(value))
-        return;
-    visit(value);
-    for (const child of Object.values(value))
-        visitRecords(child, visit);
-}
-function stringValue(value) {
-    return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
 runWhenInvokedDirectly(import.meta.url, 'compile', run);

package/dist/case/decompile.d.ts

@@ -225,6 +225,7 @@ type Preservation = {
         task: string;
     }>;
     identities?: unknown;
+    bindings?: Record<string, unknown>[];
 };
 /**
  * Everything the ORIGINAL document owns and the typed builder does not model —

package/dist/case/decompile.js

@@ -1315,6 +1315,26 @@ function identityPreservation(plan) {
         ])),
     };
 }
+/**
+ * The root connection/folder rows a recompile needs to resolve the labels
+ * decompile names connectors by. `bindingLabel` writes such a label as the
+ * row's `id` (`connection: "bOC1"`), and that id means nothing without the row.
+ * Kept: `resource: "Connection"` rows with a key other than their own id. Not
+ * kept: a row `serialize` minted offline (decompile writes its authored label,
+ * and a recompile mints the same row again) and a row keyed by its own id
+ * (a placeholder, which `Bindings` would ignore anyway).
+ */
+function preservedBindingRows(plan) {
+    return (plan.bindings ?? []).filter((row) => {
+        const r = row;
+        if (typeof r.id !== 'string' || r.resource !== 'Connection')
+            return false;
+        if (offlineBindingLabel(r) !== undefined)
+            return false;
+        const key = r.resourceKey ?? r.default;
+        return typeof key === 'string' && key !== '' && key !== r.id;
+    });
+}
 /**
  * Everything the ORIGINAL document owns and the typed builder does not model —
  * ids, layout, platform metadata, annotation nodes, node order, designer
@@ -1436,6 +1456,9 @@ export function collectPreservation(plan) {
         preservation.omitTaskElementIds = omitTaskElementIds;
     if (omitStagePositions.length)
         preservation.omitStagePositions = omitStagePositions;
+    const bindingRows = preservedBindingRows(plan);
+    if (bindingRows.length)
+        preservation.bindings = bindingRows;
     const variableKnown = new Set(['id', 'name', 'type', 'default', 'body', '_jsonSchema', 'elementId', 'var', 'custom']);
     const variableFields = {};
     const legacyVariableDefaults = {};

package/dist/case/preserve.d.ts

@@ -1,4 +1,6 @@
 import type { BuiltCase } from './case-sdk.js';
+import { Bindings } from '../core/bindings.js';
+import type { BindingsView } from '../core/binding-messages.js';
 export type PreservedVariableLane = 'inputs' | 'outputs' | 'inputOutputs';
 /**
  * A preserved `inputs[]` / `outputs[]` slot id copied verbatim from its name is
@@ -143,11 +145,41 @@ export interface CaseJsonPreservation {
     omitTaskElementIds?: PreservedTaskRef[];
     /** Opaque wire identities aligned to typed constructs by name and position. */
     identities?: CaseIdentityPreservation;
+    /**
+     * The original plan's connection and folder rows from root `bindings[]`: the
+     * map from the binding id decompile names a connector by
+     * (`connection: "bOC1"`) to its resource key. Compile reads them only to
+     * resolve such a label when bindings.json does not answer it (see
+     * {@link preservedBindings}); it emits a row only when a task references it.
+     * Without them, compiling the source anywhere but over the original plan
+     * wrote `resourceKey: "bOC1"`, and nothing refused it (builder-sdk#1242).
+     */
+    bindings?: Record<string, unknown>[];
 }
 /** Attach decompiler-owned, non-authoring wire data to a built case. */
 export declare function preserveCaseJson(built: BuiltCase, payload: CaseJsonPreservation): BuiltCase;
 /** @internal Read the preservation payload attached by `preserveCaseJson`. */
 export declare function caseJsonPreservation(built: BuiltCase): CaseJsonPreservation | undefined;
+/**
+ * The bindings registry `check` and `serialize` resolve a decompiled source's
+ * connection and folder labels against: `bindings` plus the rows the source
+ * preserved ({@link CaseJsonPreservation.bindings}) as fallback rows. A fallback
+ * row answers only a label equal to its id, never counts as declared, and loses
+ * to bindings.json and to the plan `-o` writes over (the same rules as
+ * `Bindings.withFallback`). A row `serialize` minted offline is a placeholder for
+ * its label, not a key, so it answers nothing.
+ *
+ * A `Bindings` comes back as a new `Bindings`. Any other {@link BindingsView}
+ * (an SDK caller's own, or a `Bindings` from a second copy of the package) is
+ * wrapped, so the preserved rows answer there too instead of being dropped.
+ *
+ * @param bindings - The registry the caller loaded, if any.
+ * @param payload - The source's preservation payload, if any.
+ * @returns A registry with the preserved rows, or `bindings` unchanged when
+ *   there are none.
+ */
+export declare function preservedBindings(bindings: Bindings | undefined, payload: CaseJsonPreservation | undefined): Bindings | undefined;
+export declare function preservedBindings(bindings: BindingsView | undefined, payload: CaseJsonPreservation | undefined): BindingsView | undefined;
 /** @internal Validate that preservation cannot impersonate typed authoring. */
 export declare function caseJsonPreservationErrors(payload: CaseJsonPreservation | undefined): string[];
 export {};

package/dist/case/preserve.js

@@ -1,4 +1,6 @@
 import { stableId } from '../core/stable-id.js';
+import { Bindings } from '../core/bindings.js';
+import { offlineBindingLabel } from './ids.js';
 /**
  * A preserved `inputs[]` / `outputs[]` slot id copied verbatim from its name is
  * the STRICT_FORMAL_ARG_ID defect, not an identity to keep; the minted id stands.
@@ -36,6 +38,30 @@ export function preserveCaseJson(built, payload) {
 export function caseJsonPreservation(built) {
     return preserved.get(built);
 }
+export function preservedBindings(bindings, payload) {
+    const rows = payload?.bindings;
+    if (!Array.isArray(rows) || rows.length === 0)
+        return bindings;
+    const minted = (row) => offlineBindingLabel(row) !== undefined;
+    if (bindings === undefined || bindings instanceof Bindings)
+        return (bindings ?? new Bindings()).withFallbackRows(rows, minted);
+    return withPreservedRows(bindings, new Bindings().withFallbackRows(rows, minted));
+}
+/**
+ * `view` with `extra`'s fallback rows behind it: `view` answers first, and a
+ * label only `extra` answers is a fallback label (`fromFallback`), exactly as
+ * `Bindings` treats its own fallback rows.
+ */
+function withPreservedRows(view, extra) {
+    const primary = (name) => view.resolve(name) !== undefined || view.entry?.(name) !== undefined
+        || (name !== undefined && (view.declared?.() ?? []).includes(name));
+    return {
+        resolve: (name) => view.resolve(name) ?? (primary(name) ? undefined : extra.resolve(name)),
+        ...(view.declared ? { declared: () => view.declared() } : {}),
+        entry: (name) => view.entry?.(name) ?? (primary(name) ? undefined : extra.entry(name)),
+        fromFallback: (name) => view.fromFallback?.(name) === true || (!primary(name) && extra.fromFallback(name)),
+    };
+}
 const TOP_LEVEL_KEYS = new Set([
     'id', 'name', 'description', 'version', 'bindings', 'variables', 'metadata', 'nodes', 'edges', 'layout',
 ]);
@@ -123,6 +149,21 @@ export function caseJsonPreservationErrors(payload) {
             else if (TASK_KEYS.has(field))
                 errors.push(`task "${entry.task}" field "${field}" is owned by the typed Case serializer`);
     }
+    if (payload.bindings !== undefined) {
+        if (!Array.isArray(payload.bindings))
+            errors.push('preserved "bindings" must be an array of root binding rows');
+        else
+            payload.bindings.forEach((row, index) => {
+                const r = row;
+                const key = r && typeof r === 'object' ? r.resourceKey ?? r.default : undefined;
+                if (!r || typeof r !== 'object' || typeof r.id !== 'string' || r.id === '')
+                    errors.push(`preserved binding row ${index + 1} has no string id`);
+                else if (r.resource !== 'Connection')
+                    errors.push(`preserved binding row "${r.id}" is not a Connection row (only connection and folder rows are preserved)`);
+                else if (typeof key !== 'string' || key === '' || key === r.id)
+                    errors.push(`preserved binding row "${r.id}" carries no resource key other than its own id`);
+            });
+    }
     for (const [index, fields] of (payload.triggerDataFields ?? []).entries())
         for (const field of Object.keys(fields))
             if (!PRESERVED_TRIGGER_DATA_KEYS.has(field))

package/dist/case/serialize.js

@@ -25,7 +25,7 @@ import { isResourceLabelRefusal, resolveResourceRef, resourceIdentity } from './
 import { ownEntry } from '../core/own-entry.js';
 import { stableId } from '../core/stable-id.js';
 import { resolveSchemaVersion } from '../schema-version.js';
-import { caseJsonPreservation, caseJsonPreservationErrors, } from './preserve.js';
+import { caseJsonPreservation, caseJsonPreservationErrors, preservedBindings, } from './preserve.js';
 import { businessEventProblems } from './business-event-shape.js';
 import { readEventFilterLeaf, eventFilterTreeLeaf } from '../core/event-filters.js';
 import { responseJsonSchema } from '../core/connector-response-schema.js';
@@ -101,7 +101,9 @@ export function serialize(built, opts = {}) {
         stageIdByLabel: new Map(),
         taskIdByKey: new Map(),
         library: opts.library,
-        bindings: opts.bindings,
+        // A decompiled source carries its plan's connection rows: they answer the
+        // binding-id labels decompile wrote (`connection: "bOC1"`).
+        bindings: preservedBindings(opts.bindings, caseJsonPreservation(built)),
         bindingSink: new Map(),
         ids,
         offlineBindingIds: new Map(),
@@ -1875,7 +1877,7 @@ function bindingRef(resolver, name, resource, propertyAttribute, displayName, si
     const refused = bindingLabelRefusal(resolver.bindings, name, site.attribute, site.where, site.target);
     if (refused)
         throw refused;
-    const entry = resolver.bindings?.entry(name);
+    const entry = resolver.bindings?.entry?.(name);
     const resourceKey = entry?.resourceKey ?? entry?.default ?? name;
     // Only a label with no bindings.json entry gets a minted id: an entry's
     // `resourceKey` is the real key, so its id (or its name) cannot clash with it.
@@ -1912,7 +1914,7 @@ function folderBindingRef(resolver, name, connection, site) {
     const refused = bindingLabelRefusal(resolver.bindings, name, site.attribute, site.where, site.target);
     if (refused)
         throw refused;
-    const entry = resolver.bindings?.entry(name);
+    const entry = resolver.bindings?.entry?.(name);
     const baseId = entry
         ? String(entry.id ?? name)
         : offlineBindingId(resolver, offlineBindingSeed('Connection', 'folderKey', name, connection.resourceKey));

package/dist/core/bindings-v2-resource.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One `bindings_v2.json` resource row, and the connection row every artifact
+ * writes.
+ *
+ * Flow (`bindings-v2.ts`) and Case (`case/bindings-v2.ts`) both declare a
+ * connector's connection in the project sidecar, and the CLI checks each
+ * against its own generator: `uip maestro flow pack` for Flow, `uip maestro
+ * case bindings sync` (`connectionEntry` in cli
+ * `packages/case-tool/src/services/case-bindings-service.ts`) for Case. Both
+ * generators write the same row — the Designer shape, `id` + flagged
+ * `ConnectionId` slot + `BindingsVersion` / `UseConnectionService` metadata.
+ * The CLI compares rows as serialized JSON, so the key order below is part of
+ * the contract.
+ *
+ * Case used to write its own older row (`connectionId` slot, a lower-case
+ * `connector` metadata key) and `validate --strict` reported it stale
+ * (builder-sdk#1382). One builder for both artifacts is what keeps the two
+ * from drifting apart again.
+ */
+/** One declared solution resource. */
+export interface BindingsV2Resource {
+    resource: string;
+    key: string;
+    id?: string;
+    value: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** The `bindings_v2.json` document version every generator writes. */
+export declare const BINDINGS_V2_DOCUMENT_VERSION = "2.0";
+/** The per-resource `metadata.BindingsVersion` deploy needs to override an entry. */
+export declare const RESOURCE_BINDINGS_VERSION = "2.2";
+/** What one connection row is made of. Optional parts are left out of the row when absent. */
+export interface ConnectionResourceParts {
+    /** `connection` in a `.flow`, `Connection` in a caseplan: each artifact keeps its own spelling. */
+    resource: string;
+    /** The connection's resource key. */
+    key: string;
+    /** The `ConnectionId` slot's value; the key when the binding row has no default. */
+    connectionId: string;
+    /** The connection binding's name: the slot's `displayName` and `metadata.DisplayLabel`. */
+    displayLabel?: string;
+    /** The folder key slot. Case writes it; Flow's pack does not. */
+    folderKey?: string;
+    /** The label of the first step or task that uses the connection. */
+    activityName?: string;
+    /** The connector the connection belongs to. */
+    connector?: string;
+}
+/** The connection row, in the Designer shape both CLI generators derive. */
+export declare function connectionResource(parts: ConnectionResourceParts): BindingsV2Resource;

package/dist/core/bindings-v2-resource.js

@@ -0,0 +1,50 @@
+/**
+ * One `bindings_v2.json` resource row, and the connection row every artifact
+ * writes.
+ *
+ * Flow (`bindings-v2.ts`) and Case (`case/bindings-v2.ts`) both declare a
+ * connector's connection in the project sidecar, and the CLI checks each
+ * against its own generator: `uip maestro flow pack` for Flow, `uip maestro
+ * case bindings sync` (`connectionEntry` in cli
+ * `packages/case-tool/src/services/case-bindings-service.ts`) for Case. Both
+ * generators write the same row — the Designer shape, `id` + flagged
+ * `ConnectionId` slot + `BindingsVersion` / `UseConnectionService` metadata.
+ * The CLI compares rows as serialized JSON, so the key order below is part of
+ * the contract.
+ *
+ * Case used to write its own older row (`connectionId` slot, a lower-case
+ * `connector` metadata key) and `validate --strict` reported it stale
+ * (builder-sdk#1382). One builder for both artifacts is what keeps the two
+ * from drifting apart again.
+ */
+/** The `bindings_v2.json` document version every generator writes. */
+export const BINDINGS_V2_DOCUMENT_VERSION = '2.0';
+/** The per-resource `metadata.BindingsVersion` deploy needs to override an entry. */
+export const RESOURCE_BINDINGS_VERSION = '2.2';
+/** The connection row, in the Designer shape both CLI generators derive. */
+export function connectionResource(parts) {
+    const { resource, key, connectionId, displayLabel, folderKey, activityName, connector } = parts;
+    const value = {
+        ConnectionId: {
+            defaultValue: connectionId,
+            isExpression: false,
+            ...(displayLabel !== undefined && { displayName: displayLabel }),
+        },
+    };
+    if (folderKey !== undefined)
+        value.folderKey = { defaultValue: folderKey };
+    return {
+        resource,
+        key,
+        // The generators concatenate resource and key with no separator.
+        id: `${resource}${key}`,
+        value,
+        metadata: {
+            ...(activityName !== undefined && { ActivityName: activityName }),
+            BindingsVersion: RESOURCE_BINDINGS_VERSION,
+            ...(displayLabel !== undefined && { DisplayLabel: displayLabel }),
+            UseConnectionService: 'true',
+            ...(connector !== undefined && { Connector: connector }),
+        },
+    };
+}

package/dist/core/bindings.d.ts

@@ -26,6 +26,18 @@ export declare class Bindings {
      * @returns This registry, for chaining.
      */
     withFallback(file?: string, isPlaceholder?: (row: Record<string, unknown>) => boolean): this;
+    /**
+     * A NEW registry: this one's entries and fallback rows, plus `rows` as more
+     * fallback rows (same rules as {@link withFallback}; a row whose `id` is
+     * already a fallback row is skipped, so earlier fallbacks win). This registry
+     * is not changed, so a caller's `Bindings` can be shared across compiles.
+     *
+     * @param rows - Root binding rows, e.g. the ones a decompiled Case source carries.
+     * @param isPlaceholder - As for {@link withFallback}.
+     * @returns The new registry.
+     */
+    withFallbackRows(rows: readonly unknown[], isPlaceholder?: (row: Record<string, unknown>) => boolean): Bindings;
+    private addFallbackRows;
     private primary;
     /**
      * The fallback row whose `id` is `name`. A row whose key is its own id

package/dist/core/bindings.js

@@ -44,11 +44,33 @@ export class Bindings {
         catch {
             return this; // a fallback is optional; an unreadable one adds nothing
         }
+        this.addFallbackRows(normalizeBindings(parsed), isPlaceholder);
+        return this;
+    }
+    /**
+     * A NEW registry: this one's entries and fallback rows, plus `rows` as more
+     * fallback rows (same rules as {@link withFallback}; a row whose `id` is
+     * already a fallback row is skipped, so earlier fallbacks win). This registry
+     * is not changed, so a caller's `Bindings` can be shared across compiles.
+     *
+     * @param rows - Root binding rows, e.g. the ones a decompiled Case source carries.
+     * @param isPlaceholder - As for {@link withFallback}.
+     * @returns The new registry.
+     */
+    withFallbackRows(rows, isPlaceholder) {
+        const copy = new Bindings();
+        copy.list = this.list;
+        copy.fallback = [...this.fallback];
+        copy.addFallbackRows(rows, isPlaceholder);
+        return copy;
+    }
+    addFallbackRows(rows, isPlaceholder) {
         const ids = new Set(this.fallback.map((x) => x?.id));
-        for (const entry of normalizeBindings(parsed))
-            if (typeof entry?.id === 'string' && !ids.has(entry.id) && !isPlaceholder?.(entry))
+        for (const entry of rows)
+            if (typeof entry?.id === 'string' && !ids.has(entry.id) && !isPlaceholder?.(entry)) {
                 this.fallback.push(entry);
-        return this;
+                ids.add(entry.id);
+            }
     }
     primary(name) {
         return this.list.find((x) => x.name === name || x.id === name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.68.2",
+  "version": "6.68.4",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -100,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "169cc7e0b99153458305df193dd0336b44955b84"
+  "gitref": "f879560df189ceab42f899123d36f0add5b0a562"
 }