@uipath/maestro-builder-sdk 6.18.9 → 6.19.0

package/dist/nodes/data-fabric/flow/factories.js

@@ -0,0 +1,134 @@
+/**
+ * The Flow Data Fabric factories: `dataFabricRead()`, `dataFabricCreate()`,
+ * `dataFabricUpdate()` and `dataFabricDelete()`. Moved from core/actions.ts in
+ * Phase 2c of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports
+ * them, so authors import them exactly as before.
+ */
+import { builtinActionSpec } from '../../../core/actions.js';
+/**
+ * Query entity records from Data Fabric (`core.datafabric.read`). The result
+ * publishes to the step's `output`; downstream references re-fetch fresh data
+ * at activation time (the engine re-runs the query rather than caching).
+ *
+ * @remarks
+ * This node is **read-one AND query-many**, on its 1.4 definition: `resultMode:
+ * 'multiple'` publishes the matching records under `output.results`, and the
+ * platform renames the node "Query entity records" to say so. The SDK still
+ * pins 1.0 — read-one — as the no-`{ version }` default, so passing
+ * `resultMode` is what selects 1.4; see {@link DataFabricReadInputs.resultMode}.
+ *
+ * The native family covers all four CRUD verbs: this one,
+ * {@link dataFabricCreate}, {@link dataFabricUpdate} and
+ * {@link dataFabricDelete}. What it does NOT cover is get-by-id, a query row
+ * limit, file record fields, and entity events — those are operations on the
+ * SAME product reached through its Integration Service connector,
+ * `uipath-uipath-dataservice` (the tenant displays it as **UiPath Data
+ * Fabric**). So a flow that needs one of those still straddles two surfaces,
+ * and the connector remains the one surface that covers everything:
+ *
+ * ```ts
+ * .step('byId', connector('uipath-uipath-dataservice', 'get-entity-record-by-id',
+ *   { entityName: 'Contracts', recordId: input('id') }, { connection: 'df' }))
+ * ```
+ *
+ * Get-by-id matters for long text. This node is a query even when it reads one
+ * record by an `Id` filter, and a Data Service query returns a PREVIEW of a
+ * long-text (`MULTILINE_MAX`) field: the first 10,000 characters plus
+ * `...[Truncated]`, with no flag in the output. A 15,551-character value comes
+ * back as 10,014 characters. When a field may exceed 10,000 characters, read
+ * it with `get-entity-record-by-id`, which returns the whole value
+ * (flow-builder-sdk#954).
+ *
+ * A connector operation's body fields come from the entity, so the library
+ * cannot carry them: run `uip maestro registry prepare uipath-uipath-dataservice
+ * get-entity-record-by-id -f entityName=<Entity>` first.
+ * The routing table is in the `data-fabric.md` reference and the parent-field
+ * loop in `connector-params.md` — cited by name rather than linked, because this
+ * comment renders both into the flat corpus, where those files sit alongside
+ * it, and onto the site, where each symbol is its own page and a relative
+ * `./data-fabric` resolves to nothing.
+ *
+ * @param inputs - The entity, optional filter rows, result mode, and folder scope.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dataFabricRead(inputs) {
+    return builtinActionSpec({ kind: 'dataFabricRead', inputs });
+}
+/**
+ * Create an entity record in Data Fabric (`core.datafabric.create`). The new
+ * record publishes to the step's `output`, so a following
+ * {@link dataFabricUpdate} or {@link dataFabricDelete} can read its id.
+ *
+ * @remarks
+ * `values` must name at least one column — the node's schema rejects an empty
+ * field list rather than inserting a blank row, and `check` says so before the
+ * platform does. Field names are the ENTITY's, so copy them from the scenario
+ * or the tenant; nothing offline can tell a real column from a typo.
+ *
+ * The published `output` is the record as a query returns it, so a long-text
+ * (`MULTILINE_MAX`) field longer than 10,000 characters comes back cut, with
+ * `...[Truncated]` appended, even though the whole value was stored. Use the
+ * value you passed in, or re-read the record with the connector's
+ * `get-entity-record-by-id`, when the whole text is needed (flow-builder-sdk#954).
+ *
+ * See {@link dataFabricRead} for what the native family still does not cover
+ * and which connector operation covers it.
+ *
+ * @param inputs - The entity, the columns the record starts with, and folder scope.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dataFabricCreate(inputs) {
+    return builtinActionSpec({ kind: 'dataFabricCreate', inputs });
+}
+/**
+ * Update an entity record in Data Fabric (`core.datafabric.update`). Target the
+ * record by id or through an earlier {@link dataFabricRead} step; downstream
+ * reads of this step observe the record AFTER the write.
+ *
+ * @remarks
+ * `set` must write at least one column: an empty `set` is a no-op the platform
+ * reports as success, so `check` rejects it.
+ *
+ * See {@link dataFabricRead} for what the native family still does not cover
+ * and which connector operation covers it.
+ *
+ * @param inputs - The entity, the record selector, and the columns to write.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dataFabricUpdate(inputs) {
+    assertOneRecordRef(inputs.record, 'dataFabricUpdate');
+    return builtinActionSpec({ kind: 'dataFabricUpdate', inputs });
+}
+/**
+ * Delete an entity record from Data Fabric (`core.datafabric.delete`). Target
+ * the record by id or through an earlier {@link dataFabricRead} step, exactly
+ * as {@link dataFabricUpdate} does.
+ *
+ * @remarks
+ * A delete **publishes nothing** — its definition declares no output — so
+ * `$vars.<step>.output` is undefined at run time and `check` rejects a read of
+ * it. Take what you need off the read step that found the record, before the
+ * delete.
+ *
+ * See {@link dataFabricRead} for what the native family still does not cover
+ * and which connector operation covers it.
+ *
+ * @param inputs - The entity, the record selector, and folder scope.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function dataFabricDelete(inputs) {
+    assertOneRecordRef(inputs.record, 'dataFabricDelete');
+    return builtinActionSpec({ kind: 'dataFabricDelete', inputs });
+}
+/**
+ * `record` names exactly ONE of `{ byId }` / `{ fromRead }`. Both forms are
+ * optional properties on the same object type, so TypeScript alone cannot
+ * refuse `{}` — and an empty selector compiles into a write with no target.
+ */
+function assertOneRecordRef(record, factory) {
+    const byId = record?.byId !== undefined;
+    const fromRead = typeof record?.fromRead === 'string';
+    if (byId === fromRead) {
+        throw new Error(`${factory}() targets exactly ONE of record: { byId } or record: { fromRead: '<step>' }.`);
+    }
+}

package/dist/nodes/data-fabric/flow/family.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The Flow Data Fabric node family, as flow-node-registry.ts lists it:
+ * `core.datafabric.{read,create,update,delete}`. See README.md in this directory
+ * for the developer notes, and index.ts for the public surface.
+ */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const dataFabricFlowFamily: FlowNodeFamily;

package/dist/nodes/data-fabric/flow/family.js

@@ -0,0 +1,9 @@
+import { checkFromRead, DATA_FABRIC_DIAGNOSTICS } from './check.js';
+import { dataFabricCreate, dataFabricDelete, dataFabricRead, dataFabricUpdate } from './verbs.js';
+export const dataFabricFlowFamily = {
+    id: 'data-fabric',
+    title: 'Data Fabric',
+    types: [dataFabricRead, dataFabricCreate, dataFabricUpdate, dataFabricDelete],
+    diagnostics: DATA_FABRIC_DIAGNOSTICS,
+    check: checkFromRead,
+};

package/dist/nodes/data-fabric/flow/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The Flow Data Fabric family's public surface: its authoring types and
+ * factories, which the package entry re-exports. Another family that shares a
+ * type with this one imports it from here (FB013). The node types themselves are
+ * registered through `family.ts`.
+ */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/data-fabric/flow/index.js

@@ -0,0 +1,8 @@
+/**
+ * The Flow Data Fabric family's public surface: its authoring types and
+ * factories, which the package entry re-exports. Another family that shares a
+ * type with this one imports it from here (FB013). The node types themselves are
+ * registered through `family.ts`.
+ */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/data-fabric/flow/raw.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What `rawNode` reports for a raw Data Fabric node: the typed spelling of each
+ * verb, what the factories write and do not (the hint), and the `entityConfig`
+ * keys the product reads — a raw node carrying any other key is refused at a
+ * version the SDK bundles. Moved from core/typed-raw-node.ts in Phase 3 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; messages unchanged.
+ */
+import type { FlowRawNodeAdvice } from '../../../flow-node-type.js';
+/**
+ * Every `entityConfig` key the product reads or persists on a Data Fabric node,
+ * across the four verbs. flow-workbench develop `eed682f19`:
+ *
+ * - services `serialization/entity-vdo.ts` `interface EntityConfig` (:229-272):
+ *   `entityName`, `resultMode`, `_recordLimit`, `_skip`, `_sort`,
+ *   `_selectedFieldNames`, `_filters`, `_entityFields`, `_relatedFields`,
+ *   `_folderKey`, `_entityKey`, `_resourceKey`, `_outputSchema`;
+ *   `CreateEntityConfig` (:719) adds `fieldValues`; `UpdateEntityConfig` (:744)
+ *   adds `recordSource`, `readEntityNodeId`, `recordId`, `fieldUpdates`.
+ * - canvas `properties-panel/EntityConfigField.tsx` `EntityConfigInputs`
+ *   (:85-110) and `entity/useEntityPanelState.ts` `EntitySelectionPatch`
+ *   (:248-270), which the panels persist on an entity pick:
+ *   `_entityDisplayName`, `_choiceSets`, `_folderPath`, `_entitySubType`.
+ * - Create/Update/DeleteEntityConfigField.tsx declare nothing beyond these.
+ *
+ * One union rather than one set per verb: a key another verb reads is at worst
+ * ignored, and a per-verb split would refuse a canvas-written key on a verb
+ * whose panel happens not to declare it. The test pins every key the typed
+ * factories write to this set.
+ */
+export declare const ENTITY_CONFIG_KEYS: ReadonlySet<string>;
+/** The advice for one verb: its typed spelling, the family hint, and the key check. */
+export declare function rawNodeAdvice(nodeType: string, factory: string): FlowRawNodeAdvice;

package/dist/nodes/data-fabric/flow/raw.js

@@ -0,0 +1,100 @@
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+/**
+ * Every `entityConfig` key the product reads or persists on a Data Fabric node,
+ * across the four verbs. flow-workbench develop `eed682f19`:
+ *
+ * - services `serialization/entity-vdo.ts` `interface EntityConfig` (:229-272):
+ *   `entityName`, `resultMode`, `_recordLimit`, `_skip`, `_sort`,
+ *   `_selectedFieldNames`, `_filters`, `_entityFields`, `_relatedFields`,
+ *   `_folderKey`, `_entityKey`, `_resourceKey`, `_outputSchema`;
+ *   `CreateEntityConfig` (:719) adds `fieldValues`; `UpdateEntityConfig` (:744)
+ *   adds `recordSource`, `readEntityNodeId`, `recordId`, `fieldUpdates`.
+ * - canvas `properties-panel/EntityConfigField.tsx` `EntityConfigInputs`
+ *   (:85-110) and `entity/useEntityPanelState.ts` `EntitySelectionPatch`
+ *   (:248-270), which the panels persist on an entity pick:
+ *   `_entityDisplayName`, `_choiceSets`, `_folderPath`, `_entitySubType`.
+ * - Create/Update/DeleteEntityConfigField.tsx declare nothing beyond these.
+ *
+ * One union rather than one set per verb: a key another verb reads is at worst
+ * ignored, and a per-verb split would refuse a canvas-written key on a verb
+ * whose panel happens not to declare it. The test pins every key the typed
+ * factories write to this set.
+ */
+export const ENTITY_CONFIG_KEYS = new Set([
+    'entityName', 'resultMode',
+    '_recordLimit', '_skip', '_sort', '_selectedFieldNames', '_filters',
+    '_entityFields', '_relatedFields', '_choiceSets', '_outputSchema',
+    '_folderKey', '_folderPath', '_entityKey', '_resourceKey', '_entityDisplayName', '_entitySubType',
+    'fieldValues', 'fieldUpdates', 'recordSource', 'readEntityNodeId', 'recordId',
+]);
+/**
+ * What the Data Fabric factories write, and what they do not, as the typed-family
+ * warning states it. The factories do not author the canvas's column snapshots,
+ * so a related-path filter (`customer.Name`) still needs a raw node carrying
+ * `_entityFields` (`DataFabricFilter.field`, spec.ts).
+ */
+const DATAFABRIC_HINT = ' The factory writes the query and write keys: `filters` becomes `_filters` (flat rows; `or: true` '
+    + 'starts each OR alternative), `sort` is `_sort`, `limit`/`skip`/`fields` are '
+    + '`_recordLimit`/`_skip`/`_selectedFieldNames`, `values`/`set` are `fieldValues`/`fieldUpdates`, '
+    + 'and `record` is `recordSource`. It does not write the column snapshots `_entityFields`, '
+    + '`_relatedFields`, `_choiceSets` or `_outputSchema`; a related-path filter such as '
+    + '`customer.Name` needs `_entityFields`, so for that a raw node is still the way.';
+/**
+ * Why a `core.datafabric.*` node's inputs carry a key the product never reads,
+ * or `undefined` when they do not.
+ *
+ * This is where the eval failure became possible. A raw node renders its inputs
+ * verbatim, and `core.datafabric.read@1.4`'s registry definition declares only
+ * `entityName` and `resultMode`, so `validate` cannot see any other key. Measured
+ * on the eval archive (2026-09-23, skill-flow-datafabric-native-contract-intake-pipeline):
+ * the agent wrote `_sortOptions: [{ fieldName, isDescending }]` in place of
+ * `_sort`, `check` printed "no issues", `validate` said Valid, and the query
+ * would have run unsorted. The allowed set is what the product reads
+ * ({@link ENTITY_CONFIG_KEYS}), so `_entityFields` and the other
+ * canvas snapshots stay legal.
+ *
+ * Severity follows the version: at a bundled `<nodeType>@<version>` the key set
+ * is known, so the key is refused (`error`); at a version this SDK has not
+ * synced, a newer node could read a new key, so it is reported (`warning`).
+ *
+ * @param nodeType - The node's type.
+ * @param factory - The typed spelling, as the warning names it.
+ * @param version - The version the node is emitted at.
+ * @param inputs - The node's inputs, before rendering.
+ * @param bundled - Whether the SDK bundles `<nodeType>@<version>`.
+ * @returns The diagnostic, or `undefined` for a clean node or a non-Data-Fabric type.
+ */
+function unknownInputs(nodeType, factory, version, inputs, bundled) {
+    if (!isPlainObject(inputs))
+        return undefined;
+    const unknown = Object.keys(inputs).filter((k) => k !== 'entityConfig');
+    const cfg = inputs.entityConfig;
+    if (isPlainObject(cfg)) {
+        for (const k of Object.keys(cfg))
+            if (!ENTITY_CONFIG_KEYS.has(k))
+                unknown.push(`entityConfig.${k}`);
+    }
+    if (unknown.length === 0)
+        return undefined;
+    const named = unknown.map((k) => `\`${k}\``).join(', ');
+    const base = `${nodeType}@${version} carries ${named}, which the platform never reads: Data Fabric `
+        + `nodes read only \`inputs.entityConfig\`, with the keys ${[...ENTITY_CONFIG_KEYS].join(', ')} `
+        + `(flow-workbench entity-vdo.ts \`EntityConfig\` and the entity panels). \`validate\` cannot see `
+        + `the key, so it compiles and is ignored at run time; for example a sort is \`_sort: { field, direction }\`, `
+        + `not \`_sortOptions\`. The typed factory, ${factory}, writes only keys the node reads.`;
+    if (bundled)
+        return { severity: 'error', message: base };
+    return {
+        severity: 'warning',
+        message: `${base} This SDK does not bundle ${nodeType}@${version}, so a newer node may read the key; `
+            + 'it compiles as written.',
+    };
+}
+/** The advice for one verb: its typed spelling, the family hint, and the key check. */
+export function rawNodeAdvice(nodeType, factory) {
+    return {
+        factory,
+        hint: DATAFABRIC_HINT,
+        inputProblem: (inputs, version, bundled) => unknownInputs(nodeType, factory, version, inputs, bundled),
+    };
+}

package/dist/nodes/data-fabric/flow/shared.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What the four Flow Data Fabric verbs share: the `entityConfig` envelope every
+ * one of them serializes into, the record selector update and delete use, the
+ * folder-scope bindings, and the lift back to source.
+ *
+ * Moved verbatim from serialize.ts / decompile.ts (Phase 2 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md); the comments that explain each wire
+ * decision came with the code.
+ */
+import { Expr } from '../../../core/expr.js';
+import type { DataFabricFilter, DataFabricRecordRef } from './spec.js';
+import type { FlowPrintContext, FlowSerializeContext } from '../../../flow-node-type.js';
+/** The scope options every verb takes. */
+export interface ScopeInputs {
+    entity: string;
+    folderKey?: string;
+    resourceKey?: string;
+}
+/** A serialized node's `entityConfig`, as the lift reads it. */
+export type EntityConfig = Record<string, unknown>;
+export declare function entityConfigOf(node: unknown): EntityConfig;
+/** `entityConfig` as every verb starts it. */
+export declare function baseConfig(inputs: ScopeInputs): EntityConfig;
+/**
+ * `recordSource` is how update and delete both name their target; the read
+ * step's emitted node id is rename-aware, for subflow copies.
+ */
+export declare function targetRecord(cfg: EntityConfig, record: DataFabricRecordRef, ctx: FlowSerializeContext): void;
+/** A `{ <field>: <value> }` map as the `{ field, value }` rows create and update write. */
+export declare function fieldRows(values: Record<string, string | Expr> | undefined, ctx: FlowSerializeContext): {
+    field: string;
+    value: string;
+}[];
+/**
+ * The flat `_filters` array. `join: 'OR'` on a row STARTS a new alternative —
+ * `entity-vdo.ts`'s `buildQesFromEntityConfig` splits the array into runs on that
+ * key, ANDs within a run, and ORs the runs together. So the query model is
+ * disjunctive: `alt1 OR alt2 OR …`, each `alt` an AND of its rows, which is why
+ * `[A, B(or), C]` is `A OR (B AND C)` and not `(A OR B) AND C`.
+ *
+ * The grouped `{ logicalOperator, rows, groups }` object the authoring guide
+ * shows is a NEWER shape: the vendored converter the local engine runs throws
+ * `(filters ?? []).filter is not a function` on it, so emitting it would trade
+ * a working offline rung for a shape only the current platform can read. The
+ * array is the form both accept.
+ */
+export declare function filterRows(filters: ReadonlyArray<DataFabricFilter>, ctx: FlowSerializeContext): Array<Record<string, unknown>>;
+/**
+ * The folder scope, last in `entityConfig`. A folder-scoped entity is portable
+ * only with its `Entity` bindings; the half-authored form is refused by check(),
+ * so reaching here with both means emit both. Same id for the same (entity,
+ * resourceKey), so two steps on one entity share one pair rather than
+ * duplicating it.
+ */
+export declare function applyScope(cfg: EntityConfig, inputs: ScopeInputs, ctx: FlowSerializeContext): void;
+/**
+ * A serialized value back as the spec holds it. 1.3 let `recordId` and a
+ * create's field value be a `{ type: 'jsExpression', expression }` object as well
+ * as a `=js:` string; a product-authored node can carry either, and both recover
+ * as an expression. Anything else is TEXT — a number in a field row prints as
+ * `"5"`, as it always has.
+ */
+export declare function liftValue(v: unknown): Expr | string;
+/** The scope options, read back. */
+export declare function liftScope(cfg: EntityConfig): ScopeInputs;
+/** The record selector, read back. */
+export declare function liftRecord(cfg: EntityConfig): DataFabricRecordRef;
+/** `{ field, value }` rows back as the `{ <field>: <value> }` map. */
+export declare function liftFields(rows: unknown): Record<string, Expr | string>;
+/** `entity`, then the verb's own options, then the scope — the order every verb prints in. */
+export declare function scopeOptions(inputs: ScopeInputs, ctx: FlowPrintContext): {
+    entity: [string, string];
+    tail: Array<[string, string | undefined]>;
+};
+export declare function printRecord(record: DataFabricRecordRef, ctx: FlowPrintContext): string;
+/** A field map as `{ k: v, … }` — `{  }` when empty, exactly as the decompiler always wrote it. */
+export declare function printFields(values: Record<string, unknown> | undefined, ctx: FlowPrintContext): string;

package/dist/nodes/data-fabric/flow/shared.js

@@ -0,0 +1,174 @@
+/**
+ * What the four Flow Data Fabric verbs share: the `entityConfig` envelope every
+ * one of them serializes into, the record selector update and delete use, the
+ * folder-scope bindings, and the lift back to source.
+ *
+ * Moved verbatim from serialize.ts / decompile.ts (Phase 2 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md); the comments that explain each wire
+ * decision came with the code.
+ */
+import { Expr } from '../../../core/expr.js';
+export function entityConfigOf(node) {
+    const inputs = node?.inputs ?? {};
+    return (inputs.entityConfig ?? {});
+}
+/** `entityConfig` as every verb starts it. */
+export function baseConfig(inputs) {
+    return { entityName: inputs.entity };
+}
+/**
+ * `recordSource` is how update and delete both name their target; the read
+ * step's emitted node id is rename-aware, for subflow copies.
+ */
+export function targetRecord(cfg, record, ctx) {
+    const r = record;
+    if (typeof r.fromRead === 'string') {
+        cfg.recordSource = 'fromRead';
+        cfg.readEntityNodeId = ctx.stepNodeId(r.fromRead);
+    }
+    else {
+        cfg.recordSource = 'byId';
+        cfg.recordId = String(ctx.render(r.byId));
+    }
+}
+/** A `{ <field>: <value> }` map as the `{ field, value }` rows create and update write. */
+export function fieldRows(values, ctx) {
+    return Object.entries(values ?? {}).map(([field, value]) => ({
+        field,
+        value: String(ctx.render(value)),
+    }));
+}
+/**
+ * The flat `_filters` array. `join: 'OR'` on a row STARTS a new alternative —
+ * `entity-vdo.ts`'s `buildQesFromEntityConfig` splits the array into runs on that
+ * key, ANDs within a run, and ORs the runs together. So the query model is
+ * disjunctive: `alt1 OR alt2 OR …`, each `alt` an AND of its rows, which is why
+ * `[A, B(or), C]` is `A OR (B AND C)` and not `(A OR B) AND C`.
+ *
+ * The grouped `{ logicalOperator, rows, groups }` object the authoring guide
+ * shows is a NEWER shape: the vendored converter the local engine runs throws
+ * `(filters ?? []).filter is not a function` on it, so emitting it would trade
+ * a working offline rung for a shape only the current platform can read. The
+ * array is the form both accept.
+ */
+export function filterRows(filters, ctx) {
+    return filters.map((f, i) => ({
+        field: f.field,
+        operator: f.operator ?? '=',
+        value: String(ctx.render(f.value)),
+        // Never on the first row: a leading `join` starts an empty run, which the
+        // platform's own loop guards against, and which means nothing anyway.
+        ...(i > 0 && f.or ? { join: 'OR' } : {}),
+    }));
+}
+/**
+ * The folder scope, last in `entityConfig`. A folder-scoped entity is portable
+ * only with its `Entity` bindings; the half-authored form is refused by check(),
+ * so reaching here with both means emit both. Same id for the same (entity,
+ * resourceKey), so two steps on one entity share one pair rather than
+ * duplicating it.
+ */
+export function applyScope(cfg, inputs, ctx) {
+    if (inputs.folderKey !== undefined)
+        cfg._folderKey = inputs.folderKey;
+    if (inputs.folderKey !== undefined && inputs.resourceKey !== undefined) {
+        cfg._resourceKey = inputs.resourceKey;
+        for (const entry of entityBindings(inputs.entity, inputs.folderKey, inputs.resourceKey))
+            ctx.bind(entry);
+    }
+}
+/**
+ * The two `bindings[]` rows a FOLDER-SCOPED entity needs to survive export to
+ * another org, and the `_resourceKey` that ties them to the node.
+ *
+ * Nothing else emits `resource: 'Entity'`: the kind is matched by
+ * `(resourceKey, propertyAttribute)` rather than by name, carries no
+ * `resourceSubType`, spells the folder attribute `folderKey` (never
+ * `folderPath` — a folderPath row receives the Orchestrator FQN, which the
+ * Data Fabric query rejects even in the source org), and puts a DISPLAY label
+ * in `name`. The capital `E` is load-bearing: packaging ignores a lowercase
+ * row, so deploy emits no override at all.
+ *
+ * A tenant-scoped entity needs none of this — it serializes as a dotted
+ * literal — which is why the pair is emitted only when the author supplied
+ * both `folderKey` and `resourceKey`.
+ */
+function entityBindings(entity, folderKey, resourceKey) {
+    const base = `b${entity.replace(/[^A-Za-z0-9]/g, '')}Entity`;
+    return [
+        {
+            id: `${base}Name`,
+            name: entity,
+            type: 'string',
+            resource: 'Entity',
+            resourceKey,
+            default: entity,
+            propertyAttribute: 'name',
+        },
+        {
+            id: `${base}Folder`,
+            name: `${entity}Folder`,
+            type: 'string',
+            resource: 'Entity',
+            resourceKey,
+            default: folderKey,
+            propertyAttribute: 'folderKey',
+        },
+    ];
+}
+// ─── The lift ──────────────────────────────────────────────────────────────────
+/**
+ * A serialized value back as the spec holds it. 1.3 let `recordId` and a
+ * create's field value be a `{ type: 'jsExpression', expression }` object as well
+ * as a `=js:` string; a product-authored node can carry either, and both recover
+ * as an expression. Anything else is TEXT — a number in a field row prints as
+ * `"5"`, as it always has.
+ */
+export function liftValue(v) {
+    const obj = v;
+    if (obj && typeof obj === 'object' && obj.type === 'jsExpression')
+        return new Expr(String(obj.expression ?? ''));
+    const raw = typeof v === 'string' ? v : String(v ?? '');
+    return raw.startsWith('=js:') ? new Expr(raw.slice(4)) : raw;
+}
+/** The scope options, read back. */
+export function liftScope(cfg) {
+    return {
+        entity: String(cfg.entityName ?? ''),
+        ...(typeof cfg._folderKey === 'string' ? { folderKey: cfg._folderKey } : {}),
+        ...(typeof cfg._resourceKey === 'string' ? { resourceKey: cfg._resourceKey } : {}),
+    };
+}
+/** The record selector, read back. */
+export function liftRecord(cfg) {
+    return cfg.recordSource === 'fromRead'
+        ? { fromRead: String(cfg.readEntityNodeId ?? '') }
+        : { byId: liftValue(cfg.recordId) };
+}
+/** `{ field, value }` rows back as the `{ <field>: <value> }` map. */
+export function liftFields(rows) {
+    const list = Array.isArray(rows) ? rows : [];
+    const out = {};
+    for (const r of list)
+        out[String(r.field ?? '')] = liftValue(r.value);
+    return out;
+}
+// ─── Printing ──────────────────────────────────────────────────────────────────
+/** `entity`, then the verb's own options, then the scope — the order every verb prints in. */
+export function scopeOptions(inputs, ctx) {
+    return {
+        entity: ['entity', ctx.string(inputs.entity)],
+        tail: [
+            ['folderKey', inputs.folderKey !== undefined ? ctx.string(inputs.folderKey) : undefined],
+            ['resourceKey', inputs.resourceKey !== undefined ? ctx.string(inputs.resourceKey) : undefined],
+        ],
+    };
+}
+export function printRecord(record, ctx) {
+    const r = record;
+    return typeof r.fromRead === 'string' ? `{ fromRead: ${ctx.string(r.fromRead)} }` : `{ byId: ${ctx.value(r.byId)} }`;
+}
+/** A field map as `{ k: v, … }` — `{  }` when empty, exactly as the decompiler always wrote it. */
+export function printFields(values, ctx) {
+    return `{ ${Object.entries(values ?? {}).map(([k, v]) => `${ctx.key(k)}: ${ctx.value(v)}`).join(', ')} }`;
+}