@uipath/maestro-builder-sdk 6.18.10 → 6.20.0

package/dist/merge.js

@@ -28,7 +28,7 @@
  * preserved from the original; `subflows` and edges (with their ids) come from
  * `edited`; `definitions` and `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
- * authority). Node ids are stable by construction (decompile names every step by
+ * authority). A binding row's identity is what it binds, not its row id. Node ids are stable by construction (decompile names every step by
  * its node id), which is what lets every re-attach key on id.
  *
  * ## Definitions are keyed by `nodeType@version`, not by `nodeType`
@@ -63,8 +63,23 @@
  * A node whose pair is in NEITHER file cannot be given a definition here, and a
  * merge that stayed silent about it wrote a file it already knew would fail
  * `validate`. Those are reported through {@link MergeOptions.warn}.
+ *
+ * ## The baseline is also compared with the original
+ *
+ * `baseline` is the no-edit round trip, so wherever it differs from the original
+ * in wire identity (a node, an edge, a switch case id, a human-task outcome id,
+ * a binding row), the merged file inherits that change unless the author's edit
+ * undid it. Each difference the merged file still carries is reported through
+ * `warn`, and `strict` refuses the merge over it; the merged file is also
+ * checked for an edge that leaves a handle its kept source node does not
+ * declare. See merge-roundtrip.ts.
  */
+import { bindingIdentity } from './core/binding-identity.js';
 import { jsonClone } from './core/json-file.js';
+import { DEFINITIONLESS_NODE_TYPES } from './core/definitionless-node-types.js';
+import { MergeRefusedError, mergedFileFindings, roundTripFindings } from './merge-roundtrip.js';
+import { placeAddedNodes } from './node-placement.js';
+export { MergeRefusedError } from './merge-roundtrip.js';
 function byId(nodes) {
     return new Map((nodes ?? []).map((n) => [n.id, n]));
 }
@@ -82,11 +97,31 @@ function nodeUnchanged(a, b) {
         return false;
     return JSON.stringify(a.inputs ?? {}) === JSON.stringify(b.inputs ?? {});
 }
-/** Graft the original node's layout (`ui`) onto an edited node, by id. */
-function withOriginalLayout(edited, orig) {
-    if (!orig || orig.ui === undefined)
+/**
+ * Give an edited node the original's position, by id.
+ *
+ * The original stores it in one of two places: `node.ui` (an SDK-compiled file)
+ * or `layout.nodes[id]` (every canvas-saved file — the designer's save moves
+ * `ui` into `layout.nodes`). From `node.ui` it is grafted onto the node. With a
+ * `layout.nodes` entry, the merged file keeps that entry (it is carried over
+ * with the original's `layout`) and the edited node's compile placeholder `ui`
+ * is dropped, so the node has one position, not two.
+ */
+function withOriginalLayout(edited, orig, originalLayout) {
+    if (!orig)
         return edited;
-    return { ...edited, ui: jsonClone(orig.ui) };
+    if (orig.ui !== undefined)
+        return { ...edited, ui: jsonClone(orig.ui) };
+    if (originalLayout?.[orig.id] !== undefined) {
+        const { ui: _placeholder, ...rest } = edited;
+        return rest;
+    }
+    return edited;
+}
+/** The original's `layout.nodes` map, when it has one. */
+function layoutNodesOf(f) {
+    const nodes = f.layout?.nodes;
+    return nodes && typeof nodes === 'object' && !Array.isArray(nodes) ? nodes : undefined;
 }
 export function mergeFlow(original, edited, options = {}) {
     const result = jsonClone(original);
@@ -104,7 +139,11 @@ export function mergeFlow(original, edited, options = {}) {
         }
         else {
             // Added or edited → take the edited node, re-attaching original layout.
-            finalNodes.push(withOriginalLayout(jsonClone(e), orig));
+            finalNodes.push(withOriginalLayout(jsonClone(e), orig, layoutNodesOf(original)));
+            if (orig && orig.type === e.type && orig.typeVersion !== e.typeVersion) {
+                options.warn?.(`node ${JSON.stringify(e.id)} moved ${e.type}@${String(orig.typeVersion)} -> ${String(e.typeVersion)} `
+                    + `(the edited node takes the SDK's version; flow-builder-sdk#1167).`);
+            }
         }
     }
     result.nodes = finalNodes;
@@ -124,15 +163,25 @@ export function mergeFlow(original, edited, options = {}) {
     //    one already taken elsewhere in the file, gets a fresh id, from ids unused
     //    anywhere in the file. ──
     result.edges = withFileUniqueEdgeIds(edited.edges ?? [], subflowScopes);
+    // ── Placement: a node the edit ADDED has only compile's placeholder, an
+    //    emission-index slot that can land on an original node. Put it next to
+    //    its predecessor, collision-free, in the store the
+    //    original uses — see node-placement.ts. Root scope only: a subflow is
+    //    taken from `edited` whole, layout included. ──
+    placeAddedNodes(finalNodes, result.edges, layoutNodesOf(result), (id) => !origNodes.has(id));
     // ── Definitions: the (type, version) pairs used by EVERY node in the file —
     //    root and subflows — original winning on conflict (its defs are the
     //    tenant-resolved authority). Selecting by root nodes only dropped the
     //    definitions a subflow-only node needs, and validate refused the result
     //    ("has no matching definition"). ──
     const allNodes = [...finalNodes, ...subflowScopes.flatMap((sf) => sf?.nodes ?? [])];
-    result.definitions = mergeDefinitions(original.definitions, edited.definitions, allNodes, options.warn);
-    // ── Bindings: union by id (original wins), so resources for newly-added nodes
-    //    come from `edited` while the original's stay intact. ──
+    const originalNodes = [
+        ...(original.nodes ?? []),
+        ...Object.values(original.subflows ?? {}).flatMap((sf) => sf?.nodes ?? []),
+    ];
+    result.definitions = mergeDefinitions(original.definitions, edited.definitions, allNodes, originalNodes, options.warn);
+    // ── Bindings: union by what each row binds (original wins), so resources for
+    //    newly-added nodes come from `edited` while the original's stay intact. ──
     result.bindings = mergeBindings(original.bindings, edited.bindings);
     // metadata / solutionId / projectId / layout / runtime were carried by the
     // initial clone of `original` and are intentionally left untouched.
@@ -147,6 +196,19 @@ export function mergeFlow(original, edited, options = {}) {
     if (options.baseline && edited.version !== undefined && edited.version !== options.baseline.version) {
         result.version = edited.version;
     }
+    // ── What the no-edit round trip changed, and what mixing sources broke. ──
+    // Under strict, the findings that do not refuse are still warned, so a
+    // refused run shows them too.
+    const findings = [
+        ...(options.baseline ? roundTripFindings(original, options.baseline, result) : []),
+        ...mergedFileFindings(result, original),
+    ];
+    const refusing = options.strict ? findings.filter((f) => f.refuses) : [];
+    for (const f of findings)
+        if (!refusing.includes(f))
+            options.warn?.(f.message);
+    if (refusing.length > 0)
+        throw new MergeRefusedError(refusing);
     return result;
 }
 /**
@@ -186,8 +248,9 @@ function indexDefinitions(defs) {
     }
     return ix;
 }
-function mergeDefinitions(orig, edited, nodes, warn) {
+function mergeDefinitions(orig, edited, nodes, originalNodes, warn) {
     const origIx = indexDefinitions(orig);
+    const originalPairs = new Set(originalNodes.filter((n) => n.type !== undefined && n.typeVersion !== undefined).map((n) => defKey(n.type, n.typeVersion)));
     const editedIx = indexDefinitions(edited);
     const out = new Map();
     const missing = [];
@@ -207,25 +270,62 @@ function mergeDefinitions(orig, edited, nodes, warn) {
         const def = origIx.get(key) ?? editedIx.get(key);
         if (def)
             out.set(key, def);
-        else if (!missing.includes(key))
+        // A definitionless type is not missing anything.
+        else if (!DEFINITIONLESS_NODE_TYPES.has(n.type) && !missing.includes(key))
             missing.push(key);
     }
     for (const key of missing) {
-        warn?.(`node type ${key} is pinned by a merged node but neither the original nor the edited flow `
-            + `carries a definition for that exact pair, so the merged file has none; `
-            + `\`validate\` will report "has no matching definition". `
-            + `Recompile the edited source against an SDK that bundles ${key}, or align the node's typeVersion `
-            + `with a definition one of the inputs does carry.`);
+        // A pair the original already pinned with no definition still fails
+        // `validate`; the warning says the merge inherited it rather than caused it.
+        warn?.(originalPairs.has(key)
+            ? `node type ${key} is pinned by a merged node and already had no definition in the original, `
+                + `and the edited flow carries none either, so the merged file has none; `
+                + `\`validate\` will report "has no matching definition", as it does for the original. `
+                + `Recompile the edited source against an SDK that bundles ${key} to add one.`
+            : `node type ${key} is pinned by a merged node but neither the original nor the edited flow `
+                + `carries a definition for that exact pair, so the merged file has none; `
+                + `\`validate\` will report "has no matching definition". `
+                + `Recompile the edited source against an SDK that bundles ${key}, or align the node's typeVersion `
+                + `with a definition one of the inputs does carry.`);
     }
     return [...out.values()].map((d) => jsonClone(d));
 }
+/**
+ * The original's rows, then each edited row that binds something the original
+ * does not (a resource of a node the user added, or one an edit re-pointed).
+ *
+ * Original wins on the same identity: its rows are the tenant-resolved
+ * authority, and a canvas row can carry values (a `default`, a folder) the
+ * compile does not. An added row keeps its id unless an original row already
+ * holds it, in which case it gets a fresh one — ids are unreferenced labels, but
+ * two rows with one id are not a valid file.
+ *
+ * Rows no surviving node uses are NOT pruned. The file has no uniform
+ * node-to-row reference to decide "unused" by: an in-solution Flow is named by
+ * the node TYPE's suffix, a connection by an id in the node's inputs, a published
+ * process by a folder-qualified key that no node field spells. A wrong prune
+ * drops a row a kept node needs, and the run fails to resolve its resource; an
+ * orphan row is accepted by `validate` and ignored at run time.
+ */
 function mergeBindings(orig, edited) {
-    const byId2 = new Map();
-    for (const b of edited ?? [])
-        if (b.id)
-            byId2.set(b.id, b);
-    for (const b of orig ?? [])
-        if (b.id)
-            byId2.set(b.id, b); // original wins
-    return [...byId2.values()].map((b) => jsonClone(b));
+    const out = (orig ?? []).map((b) => jsonClone(b));
+    const identities = new Set(out.map(bindingIdentity));
+    const ids = new Set(out.map((b) => b.id).filter((id) => typeof id === 'string'));
+    for (const b of edited ?? []) {
+        const identity = bindingIdentity(b);
+        if (identities.has(identity))
+            continue;
+        identities.add(identity);
+        const row = jsonClone(b);
+        if (typeof row.id === 'string' && ids.has(row.id)) {
+            let n = 2;
+            while (ids.has(`${row.id}${n}`))
+                n++;
+            row.id = `${row.id}${n}`;
+        }
+        if (typeof row.id === 'string')
+            ids.add(row.id);
+        out.push(row);
+    }
+    return out;
 }

package/dist/node-placement.d.ts

@@ -0,0 +1,93 @@
+/**
+ * node-placement — where compile puts a node it has no position for, and where
+ * merge moves one the edit added.
+ *
+ * Compile gives every node a placeholder from its emission index,
+ * `x = 256 + 288 × index, y = 144` (`+160` inside a container). Merge replaces
+ * that placeholder on each node the edit added:
+ *
+ * - next to a positioned predecessor in the same container: one slot right;
+ * - else, when the incoming edge comes from the node's own container (the first
+ *   node of a loop body): at the body origin, inside the container's padding;
+ * - else, one slot left of a positioned successor in the same container;
+ * - then the nearest free spot around that candidate.
+ *
+ * Example: the edit inserts `auditLog` between `extractInvoice (448,144)` and
+ * `routeInvoice (640,144)`. The candidate `(640,144)` is taken, so `auditLog`
+ * goes to the first free spot, `(640,264)`.
+ *
+ * A child's position is relative to its container, as on the canvas.
+ *
+ * The position goes where the original stores positions: `layout.nodes[id]`
+ * when it has a `layout.nodes` map, otherwise `node.ui`. Positions are read the
+ * way the designer reads them (flow-workbench `flow-schema`
+ * `workflow-format-conversion.ts` `mergeLayout`): a `layout.nodes[id]` entry
+ * wins over `node.ui`, field by field.
+ *
+ * `findFreePosition` is a copy of flow-workbench `flow-core`
+ * `layout/collision-detection.ts` (same 24 px padding, 40 px step, 50 rings,
+ * offset order, 96 px default size, sticky notes excluded), because the SDK may
+ * not import `@uipath/flow-core` (lint FB015).
+ */
+/** A position on the canvas. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Compile's placeholder for the `index`-th node it emits.
+ *
+ * @param index - The node's emission index in the file.
+ * @param nested - Whether the node sits inside a container.
+ * @returns The placeholder position.
+ */
+export declare function placeholderPosition(index: number, nested: boolean): Point;
+/**
+ * Whether `p` is a compile placeholder rather than a position someone chose.
+ * An author `.layout()` entry that happens to hit the same grid point reads as
+ * a placeholder; that is the one ambiguity.
+ */
+export declare function isPlaceholderPosition(p: Point | undefined): boolean;
+/** A node's `ui` (or its `layout.nodes` entry): the fields placement reads. */
+interface Ui {
+    position?: Point;
+    size?: {
+        width?: number;
+        height?: number;
+    };
+    [k: string]: unknown;
+}
+/** A node as merge holds it; `ui` is untyped in the file model. */
+interface PlacedNode {
+    id: string;
+    type?: string;
+    parentId?: string;
+    ui?: unknown;
+    [k: string]: unknown;
+}
+/**
+ * Give each node the edit added a position next to its predecessor, in place.
+ *
+ * A node is placed when it is not in the original and its position is a
+ * compile placeholder (an author `.layout()` position is kept). Its candidate,
+ * in order: one slot right of the first predecessor in the same container that
+ * already has a position (an original node, or an added node placed before it);
+ * the body origin, when an edge enters it from its own container; one slot left
+ * of a positioned successor in the same container. With none, the node keeps
+ * its placeholder, and placed nodes avoid it.
+ *
+ * Where the result is written follows the file: when the original stores
+ * positions in `layout.nodes` (every canvas-saved file does), the position goes
+ * there and the placeholder `node.ui` is dropped, so the file has one store;
+ * otherwise `node.ui.position` is updated.
+ *
+ * @param nodes - The merged root nodes (mutated).
+ * @param edges - The merged root edges.
+ * @param layoutNodes - The merged file's `layout.nodes`, or undefined when the original has none (mutated).
+ * @param isAdded - Whether a node id is new in this merge.
+ */
+export declare function placeAddedNodes(nodes: PlacedNode[], edges: ReadonlyArray<{
+    sourceNodeId: string;
+    targetNodeId: string;
+}>, layoutNodes: Record<string, Ui> | undefined, isAdded: (id: string) => boolean): void;
+export {};

package/dist/node-placement.js

@@ -0,0 +1,163 @@
+/**
+ * node-placement — where compile puts a node it has no position for, and where
+ * merge moves one the edit added.
+ *
+ * Compile gives every node a placeholder from its emission index,
+ * `x = 256 + 288 × index, y = 144` (`+160` inside a container). Merge replaces
+ * that placeholder on each node the edit added:
+ *
+ * - next to a positioned predecessor in the same container: one slot right;
+ * - else, when the incoming edge comes from the node's own container (the first
+ *   node of a loop body): at the body origin, inside the container's padding;
+ * - else, one slot left of a positioned successor in the same container;
+ * - then the nearest free spot around that candidate.
+ *
+ * Example: the edit inserts `auditLog` between `extractInvoice (448,144)` and
+ * `routeInvoice (640,144)`. The candidate `(640,144)` is taken, so `auditLog`
+ * goes to the first free spot, `(640,264)`.
+ *
+ * A child's position is relative to its container, as on the canvas.
+ *
+ * The position goes where the original stores positions: `layout.nodes[id]`
+ * when it has a `layout.nodes` map, otherwise `node.ui`. Positions are read the
+ * way the designer reads them (flow-workbench `flow-schema`
+ * `workflow-format-conversion.ts` `mergeLayout`): a `layout.nodes[id]` entry
+ * wins over `node.ui`, field by field.
+ *
+ * `findFreePosition` is a copy of flow-workbench `flow-core`
+ * `layout/collision-detection.ts` (same 24 px padding, 40 px step, 50 rings,
+ * offset order, 96 px default size, sticky notes excluded), because the SDK may
+ * not import `@uipath/flow-core` (lint FB015).
+ */
+// Sticky notes may overlap anything (flow-core skips them in collisions).
+import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
+/** Where compile's placeholder row starts, and its spacing. */
+const PLACEHOLDER = { x0: 256, dx: 288, y0: 144, nestedDy: 160 };
+/** The default node box the canvas assumes (flow-core `resolveWidth`/`resolveHeight`). */
+const DEFAULT_SIZE = 96;
+/** One slot to the right of a node: its width plus an equal gap, the spacing of a canvas row. */
+const SLOT_DX = 192;
+/** flow-core `findFreePosition` defaults. */
+const PADDING = 24;
+const STEP = 40;
+const MAX_RINGS = 50;
+/**
+ * Where a container's first body node goes, relative to the container: inside
+ * its left and top padding (flow-core `defaultContainerFit`: 144 left, 96 top).
+ */
+const BODY_ORIGIN = { x: 144, y: 96 };
+/**
+ * Compile's placeholder for the `index`-th node it emits.
+ *
+ * @param index - The node's emission index in the file.
+ * @param nested - Whether the node sits inside a container.
+ * @returns The placeholder position.
+ */
+export function placeholderPosition(index, nested) {
+    return { x: PLACEHOLDER.x0 + index * PLACEHOLDER.dx, y: PLACEHOLDER.y0 + (nested ? PLACEHOLDER.nestedDy : 0) };
+}
+/**
+ * Whether `p` is a compile placeholder rather than a position someone chose.
+ * An author `.layout()` entry that happens to hit the same grid point reads as
+ * a placeholder; that is the one ambiguity.
+ */
+export function isPlaceholderPosition(p) {
+    if (!p)
+        return false;
+    const k = (p.x - PLACEHOLDER.x0) / PLACEHOLDER.dx;
+    return Number.isInteger(k) && k >= 0 && (p.y === PLACEHOLDER.y0 || p.y === PLACEHOLDER.y0 + PLACEHOLDER.nestedDy);
+}
+const overlaps = (a, b) => !(a.x + a.width + PADDING <= b.x || b.x + b.width + PADDING <= a.x
+    || a.y + a.height + PADDING <= b.y || b.y + b.height + PADDING <= a.y);
+/** flow-core `findFreePosition`: the candidate, else the first free spot on rings around it. */
+function findFreePosition(candidate, size, others) {
+    const free = (p) => !others.some((o) => overlaps({ ...p, ...size }, o));
+    if (free(candidate))
+        return candidate;
+    for (let d = STEP; d <= STEP * MAX_RINGS; d += STEP) {
+        for (const [dx, dy] of [[d, 0], [0, d], [d, d], [-d, 0], [0, -d], [-d, -d]]) {
+            const p = { x: candidate.x + dx, y: candidate.y + dy };
+            if (free(p))
+                return p;
+        }
+    }
+    return candidate;
+}
+/**
+ * Give each node the edit added a position next to its predecessor, in place.
+ *
+ * A node is placed when it is not in the original and its position is a
+ * compile placeholder (an author `.layout()` position is kept). Its candidate,
+ * in order: one slot right of the first predecessor in the same container that
+ * already has a position (an original node, or an added node placed before it);
+ * the body origin, when an edge enters it from its own container; one slot left
+ * of a positioned successor in the same container. With none, the node keeps
+ * its placeholder, and placed nodes avoid it.
+ *
+ * Where the result is written follows the file: when the original stores
+ * positions in `layout.nodes` (every canvas-saved file does), the position goes
+ * there and the placeholder `node.ui` is dropped, so the file has one store;
+ * otherwise `node.ui.position` is updated.
+ *
+ * @param nodes - The merged root nodes (mutated).
+ * @param edges - The merged root edges.
+ * @param layoutNodes - The merged file's `layout.nodes`, or undefined when the original has none (mutated).
+ * @param isAdded - Whether a node id is new in this merge.
+ */
+export function placeAddedNodes(nodes, edges, layoutNodes, isAdded) {
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const uiOf = (n) => {
+        const entry = layoutNodes?.[n.id];
+        const own = n.ui;
+        return entry ? { ...own, ...entry } : own;
+    };
+    const sizeOf = (n) => ({
+        width: uiOf(n)?.size?.width ?? DEFAULT_SIZE,
+        height: uiOf(n)?.size?.height ?? DEFAULT_SIZE,
+    });
+    const pending = new Set(nodes.filter((n) => isAdded(n.id) && n.type !== STICKY_NOTE_TYPE && isPlaceholderPosition(uiOf(n)?.position)).map((n) => n.id));
+    const positioned = (id) => {
+        const n = byId.get(id);
+        return n !== undefined && !pending.has(id) && uiOf(n)?.position !== undefined;
+    };
+    // Place in waves, so a run of added nodes chains off the first one placed.
+    for (let progress = true; progress && pending.size > 0;) {
+        progress = false;
+        for (const id of [...pending]) {
+            const n = byId.get(id);
+            const sameScope = (other) => byId.get(other)?.parentId === n.parentId;
+            const pred = edges.find((e) => e.targetNodeId === id && sameScope(e.sourceNodeId) && positioned(e.sourceNodeId));
+            const entersBody = !pred && n.parentId !== undefined && byId.has(n.parentId)
+                && edges.some((e) => e.targetNodeId === id && e.sourceNodeId === n.parentId);
+            const succ = pred || entersBody ? undefined
+                : edges.find((e) => e.sourceNodeId === id && sameScope(e.targetNodeId) && positioned(e.targetNodeId));
+            let candidate;
+            if (pred || succ) {
+                const anchor = uiOf(byId.get(pred?.sourceNodeId ?? succ.targetNodeId)).position;
+                candidate = { x: anchor.x + (pred ? SLOT_DX : -SLOT_DX), y: anchor.y };
+            }
+            else if (entersBody) {
+                candidate = { ...BODY_ORIGIN };
+            }
+            else {
+                continue;
+            }
+            // Still-pending nodes count at their placeholder: one that never finds an
+            // anchor stays there, and nothing may land on it.
+            const others = nodes
+                .filter((o) => o.id !== id && o.parentId === n.parentId && o.type !== STICKY_NOTE_TYPE && uiOf(o)?.position !== undefined)
+                .map((o) => ({ ...uiOf(o).position, ...sizeOf(o) }));
+            const position = findFreePosition(candidate, sizeOf(n), others);
+            const ui = { ...uiOf(n), position };
+            if (layoutNodes) {
+                layoutNodes[id] = ui;
+                delete n.ui;
+            }
+            else {
+                n.ui = ui;
+            }
+            pending.delete(id);
+            progress = true;
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { DataFabricCreateInputs, DataFabricDeleteInputs, DataFabricReadInputs, DataFabricUpdateInputs } from './spec.js';
+import type { DiagnosticCatalog, Placement } from '../../../core/nodes/family.js';
+import type { FlowCheckContext, FlowFamilyCheckContext } from '../../../flow-node-type.js';
+export declare const DATA_FABRIC_DIAGNOSTICS: DiagnosticCatalog;
+export declare function checkRead(inputs: DataFabricReadInputs, ctx: FlowCheckContext): void;
+export declare function checkCreate(inputs: DataFabricCreateInputs, ctx: FlowCheckContext): void;
+export declare function checkUpdate(inputs: DataFabricUpdateInputs, ctx: FlowCheckContext): void;
+export declare function checkWrite(inputs: DataFabricDeleteInputs, ctx: FlowCheckContext): void;
+/**
+ * Update and delete target a record `{ fromRead: '<step>' }` with the same
+ * selector, so they share the check: the step must be a read, and not a list.
+ */
+export declare function checkFromRead(placements: readonly Placement[], ctx: FlowFamilyCheckContext): void;

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

@@ -0,0 +1,164 @@
+/**
+ * The Flow Data Fabric family's rules: the per-step checks each verb runs, and
+ * the family-level `{ fromRead }` rules that need every placement at once. Moved
+ * verbatim from check.ts (Phase 2 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md);
+ * codes, messages and order are unchanged.
+ */
+import { Expr } from '../../../core/expr.js';
+export const DATA_FABRIC_DIAGNOSTICS = {
+    DATAFABRIC_NO_ENTITY: { severity: 'error', summary: 'a verb names no entity' },
+    DATAFABRIC_EMPTY_VALUES: { severity: 'error', summary: 'a create writes no non-blank column' },
+    DATAFABRIC_EMPTY_SET: { severity: 'error', summary: 'an update writes no column' },
+    DATAFABRIC_SYSTEM_COLUMN: { severity: 'error', summary: 'a write targets a system column' },
+    DATAFABRIC_FOLDER_NO_RESOURCE_KEY: { severity: 'error', summary: 'folderKey without resourceKey' },
+    DATAFABRIC_RESOURCE_KEY_NO_FOLDER: { severity: 'error', summary: 'resourceKey without folderKey' },
+    DATAFABRIC_QUERY_OPTS_WITHOUT_MULTIPLE: { severity: 'error', summary: 'list-query options on a single read' },
+    DATAFABRIC_LIMIT_RANGE: { severity: 'error', summary: 'limit outside 1–1000' },
+    DATAFABRIC_IN_REQUIRES_MULTIPLE: { severity: 'error', summary: "an 'in' filter on a single read" },
+    DATAFABRIC_FILTER_BLANK_VALUE: { severity: 'error', summary: 'a filter with a blank value' },
+    DATAFABRIC_FROMREAD_UNKNOWN: { severity: 'error', summary: '{ fromRead } names no read step' },
+    DATAFABRIC_FROMREAD_MULTIPLE: { severity: 'error', summary: "{ fromRead } names a resultMode: 'multiple' query" },
+    DATAFABRIC_DELETE_HAS_NO_OUTPUT: { severity: 'error', summary: "a read of a delete's output" },
+};
+function checkEntity(inputs, ctx) {
+    if (!String(inputs.entity ?? '').trim()) {
+        ctx.report('DATAFABRIC_NO_ENTITY', `"${ctx.step}" names no Data Fabric entity. Set { entity: '<entity name>' }.`);
+    }
+}
+export function checkRead(inputs, ctx) {
+    checkEntity(inputs, ctx);
+    checkQuery(inputs, ctx);
+    checkScope(inputs, ctx);
+}
+export function checkCreate(inputs, ctx) {
+    checkEntity(inputs, ctx);
+    // Not the same failure as an empty update: a BLANK value is omitted from the
+    // insert so the column default applies, so an all-blank `fieldValues`
+    // serializes to an empty body and runs green having inserted nothing. The
+    // node's schema rejects that — and the fix is a real value, never a
+    // placeholder to satisfy the rule.
+    const written = Object.values(inputs.values ?? {})
+        .filter((v) => (v instanceof Expr ? true : String(v ?? '').trim() !== ''));
+    if (written.length === 0) {
+        ctx.report('DATAFABRIC_EMPTY_VALUES', `"${ctx.step}" sets no column to a non-blank value, so it would insert nothing and run green. `
+            + 'The node\'s schema rejects that — give a real column a real value rather than a placeholder.');
+    }
+    checkColumns(Object.keys(inputs.values ?? {}), 'values', ctx);
+    checkScope(inputs, ctx);
+}
+export function checkUpdate(inputs, ctx) {
+    checkEntity(inputs, ctx);
+    if (Object.keys(inputs.set ?? {}).length === 0) {
+        ctx.report('DATAFABRIC_EMPTY_SET', `"${ctx.step}" writes no columns — { set } is empty, so the update would no-op green.`);
+    }
+    checkColumns(Object.keys(inputs.set ?? {}), 'set', ctx);
+    checkScope(inputs, ctx);
+}
+export function checkWrite(inputs, ctx) {
+    checkEntity(inputs, ctx);
+    checkScope(inputs, ctx);
+}
+/**
+ * Columns Data Fabric assigns and never accepts a write for.
+ *
+ * The canvas hides them from both write editors, but the serializer has no
+ * guard: a hand-authored `Id` row satisfies the node's own "at least one field"
+ * rule, ships in the body, and is rejected — and the rejection is only logged,
+ * so the row comes back unchanged and the run goes green.
+ */
+const SYSTEM_COLUMNS = new Set(['Id', 'CreateTime', 'CreatedBy', 'UpdateTime', 'UpdatedBy']);
+function checkColumns(columns, option, ctx) {
+    const system = columns.filter((c) => SYSTEM_COLUMNS.has(c));
+    if (system.length) {
+        ctx.report('DATAFABRIC_SYSTEM_COLUMN', `"${ctx.step}" writes ${system.map((c) => JSON.stringify(c)).join(', ')} in { ${option} }. `
+            + 'Data Fabric assigns its system columns (Id, CreateTime, CreatedBy, UpdateTime, UpdatedBy) and rejects a '
+            + 'write to them — and it only LOGS the rejection, so the row comes back unchanged and the run goes green.');
+    }
+}
+/**
+ * A folder-scoped entity is portable only with its `Entity` bindings.
+ *
+ * `_folderKey` on its own still serializes — it falls back to a source-org
+ * literal and logs a warning — so the flow looks fine until it is deployed to
+ * another org. Refusing the half-authored pair here is the whole point: the
+ * alternative is a defect that only appears at deploy time, in a different org,
+ * to somebody else.
+ */
+function checkScope(inputs, ctx) {
+    if (inputs.folderKey !== undefined && inputs.resourceKey === undefined) {
+        ctx.report('DATAFABRIC_FOLDER_NO_RESOURCE_KEY', `"${ctx.step}" sets { folderKey } without { resourceKey }. A folder-scoped entity needs both — with only `
+            + 'the folder key the entity serializes as a source-org literal, which validates, runs in this org, and '
+            + 'breaks on deploy to another one.', 'resolve the key with `uip solution resources list --kind Entity`, or drop { folderKey } and keep '
+            + 'the entity tenant-scoped');
+    }
+    if (inputs.resourceKey !== undefined && inputs.folderKey === undefined) {
+        ctx.report('DATAFABRIC_RESOURCE_KEY_NO_FOLDER', `"${ctx.step}" sets { resourceKey } without { folderKey }. The pair exists to scope a FOLDER entity; a `
+            + 'tenant-scoped entity needs neither and serializes as a dotted literal.');
+    }
+}
+/**
+ * The query options, none of which the node's `inputDefinition` declares — they
+ * are `_`-prefixed extras, so `uip maestro flow validate` checks none of them
+ * and every mistake here is silent at run time.
+ */
+function checkQuery(inputs, ctx) {
+    const step = ctx.step;
+    const listOnly = ['limit', 'skip', 'sort', 'fields'].filter((k) => inputs[k] !== undefined);
+    if (listOnly.length && inputs.resultMode !== 'multiple') {
+        ctx.report('DATAFABRIC_QUERY_OPTS_WITHOUT_MULTIPLE', `"${step}" sets { ${listOnly.join(', ')} }, which only a list query uses, but its resultMode is `
+            + `${inputs.resultMode ? JSON.stringify(inputs.resultMode) : 'unset (a single-record read)'}.`, "resultMode: 'multiple'");
+    }
+    // The emitted query ALWAYS carries a limit — omitted it resolves to 100 — and
+    // 1000 is a hard ceiling that TRUNCATES rather than erroring above it.
+    if (inputs.limit !== undefined && (!Number.isInteger(inputs.limit) || inputs.limit < 1 || inputs.limit > 1000)) {
+        ctx.report('DATAFABRIC_LIMIT_RANGE', `"${step}": limit must be a whole number between 1 and 1000 (got ${inputs.limit}). 1000 is a hard `
+            + 'ceiling — a larger value truncates silently, so page with { skip } instead.');
+    }
+    // `in` is honoured only on a list query; on a single read the row compiles
+    // away, and a read whose filters compiled away returns EVERY record.
+    if (inputs.resultMode !== 'multiple' && (inputs.filters ?? []).some((f) => f.operator === 'in')) {
+        ctx.report('DATAFABRIC_IN_REQUIRES_MULTIPLE', `"${step}" filters with the 'in' operator, which is honoured only when resultMode is 'multiple'. `
+            + 'On a single-record read that row compiles away — and a read whose filters compiled away matches every record.');
+    }
+    // A filter expression switched on and left blank is refused by the serializer,
+    // and it refuses the WHOLE query rather than dropping the row, which strands
+    // every downstream reference to this step.
+    for (const f of inputs.filters ?? []) {
+        const blank = f.value instanceof Expr ? f.value.js.trim() === '' : String(f.value ?? '').trim() === '';
+        if (blank) {
+            ctx.report('DATAFABRIC_FILTER_BLANK_VALUE', `"${step}" has a filter on ${JSON.stringify(f.field)} with a blank value. The serializer refuses the `
+                + 'ENTIRE query rather than dropping the row, so the step emits nothing and every downstream $vars read of '
+                + 'it breaks.');
+        }
+    }
+}
+/**
+ * Update and delete target a record `{ fromRead: '<step>' }` with the same
+ * selector, so they share the check: the step must be a read, and not a list.
+ */
+export function checkFromRead(placements, ctx) {
+    for (const p of placements) {
+        if (p.kind !== 'dataFabricUpdate' && p.kind !== 'dataFabricDelete')
+            continue;
+        const fromRead = p.spec.inputs?.record?.fromRead;
+        if (typeof fromRead !== 'string')
+            continue;
+        const factory = p.kind;
+        // A step whose version did not resolve is already an error; saying it does
+        // not exist would send the author to the selector instead of the pin.
+        if (ctx.versionUnresolved(fromRead))
+            continue;
+        const read = ctx.placementOf(fromRead);
+        if (read?.kind !== 'dataFabricRead') {
+            ctx.report(p.step, 'DATAFABRIC_FROMREAD_UNKNOWN', `"${p.step}" targets record: { fromRead: ${JSON.stringify(fromRead)} }, but no dataFabricRead step has that name.`, `${factory}({ …, record: { byId: '<record id>' } })`);
+            continue;
+        }
+        // A LIST is not a write target: the serializer refuses it and emits a plain
+        // no-op task, so the flow validates, runs green, and writes nothing.
+        if (read.spec.inputs?.resultMode === 'multiple') {
+            ctx.report(p.step, 'DATAFABRIC_FROMREAD_MULTIPLE', `"${p.step}" targets record: { fromRead: ${JSON.stringify(fromRead)} }, but "${fromRead}" is a `
+                + "resultMode: 'multiple' query. A multi-record read is refused as a write target — the step compiles to "
+                + 'a no-op and the run goes green having written nothing.', `loop the results and target each record with ${factory}({ …, record: { byId: … } })`);
+        }
+    }
+}