@uipath/maestro-builder-sdk 6.8.5 → 6.9.0

package/dist/core/library.js

@@ -8,6 +8,7 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { prepareCommand } from './cli-spelling.js';
 import { loadListEnvelopes, lookupListEnvelope } from './list-envelope.js';
 import { lookupSpecOf } from './lookups.js';
 import { loadInvariantCollections, loadLookupResolutions } from './lookup-store.js';
@@ -245,11 +246,18 @@ export class Library {
             // own `registry get` answers for both forms (see `deriveTriggerForm`).
             if (kind !== 'trigger')
                 throw error;
+            const siblingType = `uipath.connector.event.${key}.${event}`;
             let sibling;
             try {
-                sibling = this.resolveType(`uipath.connector.event.${key}.${event}`, version, objectName);
+                sibling = this.resolveType(siblingType, version, objectName);
             }
-            catch {
+            catch (siblingError) {
+                // The wait form IS in the library and refused the request itself — a
+                // GENERIC event with no `object`, or a disagreeing one. That refusal is
+                // the true answer; replacing it with the start form's "not in library"
+                // told the author the connector was missing.
+                if (this.carries(siblingType, version))
+                    throw siblingError;
                 throw error;
             }
             rc = deriveTriggerForm(sibling, nodeType);
@@ -528,7 +536,7 @@ export class Library {
                 + `\`…connector.trigger.…\` starts a flow, \`…connector.event.…\` waits mid-flow.`
             : '';
         throw new Error(`connector not in library: ${nodeType}${version ? '@' + version : ''}.${hint}`
-            + this.describeMiss(nodeType));
+            + this.describeMiss(nodeType, version, objectName));
     }
     /**
      * Turn a lookup miss into something actionable: which operations this connector
@@ -541,7 +549,7 @@ export class Library {
      * `connector not in library: …send-mail-v2.` said nothing that would reveal
      * that. It resorted to grepping the library's JSON out of `node_modules`.
      */
-    describeMiss(nodeType) {
+    describeMiss(nodeType, version, objectName) {
         // `uipath.connector.<key>.<op>`, or `uipath.connector.(trigger|event).<key>.<ev>`
         // for the two event namespaces. No connector key contains a dot.
         const parts = nodeType.split('.');
@@ -550,23 +558,12 @@ export class Library {
         const asked = (eventNs ? parts.slice(4) : parts.slice(3)).join('.');
         if (!key)
             return '';
-        const prefix = eventNs ? `uipath.connector.${parts[2]}.${key}.` : `uipath.connector.${key}.`;
-        const ops = [...new Set(this.layers.flatMap((l) => l.entries
-                .map((e) => String(e.nodeType ?? ''))
-                .filter((t) => t.startsWith(prefix))
-                .map((t) => t.slice(prefix.length))))].sort();
         const where = ` Searched: ${this.layers.map((l) => l.dir).join(', ')}.`;
-        if (!ops.length) {
-            const keys = [...new Set(this.layers.flatMap((l) => l.entries.map((e) => {
-                    const p = String(e.nodeType ?? '').split('.');
-                    return (p[2] === 'trigger' || p[2] === 'event' ? p[3] : p[2]) ?? '';
-                })))].filter(Boolean).sort();
-            const near = nearest(key, keys);
-            return ` No connector "${key}" in the library (${keys.length} indexed).`
-                + (near && near !== key ? ` Closest: ${near}.` : '')
-                + where
-                + ' If the connector is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
-        }
+        if (eventNs)
+            return this.describeEventMiss(parts[2], key, asked, where, version, objectName);
+        const ops = this.opsUnder(`uipath.connector.${key}.`);
+        if (!ops.length)
+            return this.noConnector(key, where);
         const near = asked ? nearest(asked, ops) : undefined;
         const listed = ops.length <= 12
             ? `Operations: ${ops.join(', ')}.`
@@ -580,6 +577,86 @@ export class Library {
             + ' — `uip maestro case spec` reports the latter, and the two can differ.'
             + ' If the operation is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
     }
+    /** Every direct operation id under `prefix` (no further dot), across layers, sorted and de-duplicated. */
+    opsUnder(prefix) {
+        return [...new Set(this.layers.flatMap((l) => l.entries
+                .map((e) => String(e.nodeType ?? ''))
+                .filter((t) => t.startsWith(prefix))
+                .map((t) => t.slice(prefix.length))
+                .filter((op) => op !== '' && !op.includes('.'))))].sort();
+    }
+    /** Whether any layer indexes `nodeType` (at `version`, when one is asked for). */
+    carries(nodeType, version) {
+        return this.layers.some((l) => l.entries.some((e) => e.nodeType === nodeType && (!version || e.version === version)));
+    }
+    /** The connector key is in no entry at all. */
+    noConnector(key, where) {
+        const keys = [...new Set(this.layers.flatMap((l) => l.entries.map((e) => {
+                const p = String(e.nodeType ?? '').split('.');
+                return (p[2] === 'trigger' || p[2] === 'event' ? p[3] : p[2]) ?? '';
+            })))].filter(Boolean).sort();
+        const near = nearest(key, keys);
+        return ` No connector "${key}" in the library (${keys.length} indexed).`
+            + (near && near !== key ? ` Closest: ${near}.` : '')
+            + where
+            + ' If the connector is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
+    }
+    /**
+     * The event half of {@link describeMiss}: which of the connector's EVENTS the
+     * library carries, read from BOTH namespaces.
+     *
+     * Both, because the library stores almost every event in one form only: the
+     * baseline snapshot of 2026-09-23 (`2a4405dd…`) has 994 `.event.` entries and 4
+     * `.trigger.` ones, and a start trigger resolves from its `.event.` sibling
+     * ({@link resolveEvent}). Reading the asked namespace alone answered `No
+     * connector "uipath-uipath-dataservice"` for a typo'd `onEvent` event on a
+     * connector whose events were all right there, and the same words for a
+     * connector present with eight actions and no events at all (2026-09-23 eval,
+     * `skill-flow-datafabric-trigger-lifecycle`, v2 commands 45/46).
+     */
+    describeEventMiss(kind, key, asked, where, version, objectName) {
+        const starts = this.opsUnder(`uipath.connector.trigger.${key}.`);
+        const waits = this.opsUnder(`uipath.connector.event.${key}.`);
+        // A start trigger resolves from either form; a mid-flow wait needs the `.event.` form itself.
+        const usable = kind === 'trigger' ? [...new Set([...starts, ...waits])].sort() : waits;
+        const refresh = ' If the event is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
+        if (usable.length) {
+            if (usable.includes(asked)) {
+                // Only a version can make a carried event miss here: every other refusal
+                // of a carried entry is thrown by the entry itself.
+                return ` Connector "${key}" carries event "${asked}", but not at version ${version ?? '(any)'}.`
+                    + ` Drop the version, or use one the library's index.json lists for it.` + where;
+            }
+            const onlyStart = kind === 'event' && starts.includes(asked);
+            const near = onlyStart ? undefined : nearest(asked, usable);
+            const listed = usable.length <= 12
+                ? `Events: ${usable.join(', ')}.`
+                : `Events (${usable.length}, first 12): ${usable.slice(0, 12).join(', ')}, … — `
+                    + `the full list is every \`nodeType\` under "${key}" in the library's index.json.`;
+            return ` Connector "${key}" is present but carries no event "${asked}"`
+                + (onlyStart
+                    ? ` that can be waited on: it is here only as a start trigger (\`uipath.connector.trigger.${key}.${asked}\`), `
+                        + `and \`waitForEvent\` needs its \`uipath.connector.event.\` form.`
+                    : '.')
+                + (near ? ` Closest: ${near}.` : '')
+                + ` ${listed}`
+                + where
+                + refresh;
+        }
+        if (starts.length) {
+            return ` Connector "${key}" carries only start triggers in this library (${starts.join(', ')}), `
+                + `and \`waitForEvent\` needs the \`uipath.connector.event.\` form.` + where + refresh;
+        }
+        const actions = this.opsUnder(`uipath.connector.${key}.`).length;
+        if (!actions)
+            return this.noConnector(key, where);
+        const prepare = prepareCommand(key, asked, ...(objectName ? ['--object', objectName] : []));
+        return ` Connector "${key}" is present (${actions} action${actions === 1 ? '' : 's'}) but this library carries `
+            + `no events for it.` + where
+            + ` Prepare the event against a live connection: ${prepare}. If prepare reports that the registry serves `
+            + `no event for "${key}" either (after \`uip maestro flow registry pull --force\`, if its catalog looks stale), `
+            + `refreshing the library will not add one: it is built from the same catalog.`;
+    }
     /**
      * Resolve the op WITHIN one layer, selecting the entry by `objectName` for a
      * GENERIC operation. Returns undefined when the layer does not carry the op;

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

@@ -217,6 +217,14 @@ export declare abstract class FlowResource extends FlowNode<never> {
  * compile reports an input the static library does not carry; use
  * {@link onEvent} for a connector event trigger.
  *
+ * **Prefer the typed factory** for a node type that has one: `check` warns
+ * (`RAW_NODE_TYPED_FAMILY`), because `validate` cannot see an input the
+ * registry definition does not declare. For a `core.datafabric.*` type, a key
+ * the product never reads (an invented `_sortOptions` in place of `_sort`) is
+ * an error at a version the SDK bundles (`RAW_NODE_UNKNOWN_INPUT`); the
+ * canvas's snapshots, such as the `_entityFields` a related-path filter
+ * needs, stay legal.
+ *
  * @param spec - The definition to compile against, plus the node's inputs.
  * @returns A node to pass to `.step(...)`.
  */

package/dist/core/node-classes.js

@@ -24,6 +24,7 @@
  * built-in rules with the same severities.
  */
 import { connectorRawNodeRefusal } from './connector-raw-node.js';
+import { typedFamilyRawNodeWarning, dataFabricUnknownInputs } from './typed-raw-node.js';
 /**
  * The abstract root of every definition-backed node the builder can place.
  *
@@ -113,6 +114,14 @@ export class FlowResource extends FlowNode {
  * compile reports an input the static library does not carry; use
  * {@link onEvent} for a connector event trigger.
  *
+ * **Prefer the typed factory** for a node type that has one: `check` warns
+ * (`RAW_NODE_TYPED_FAMILY`), because `validate` cannot see an input the
+ * registry definition does not declare. For a `core.datafabric.*` type, a key
+ * the product never reads (an invented `_sortOptions` in place of `_sort`) is
+ * an error at a version the SDK bundles (`RAW_NODE_UNKNOWN_INPUT`); the
+ * canvas's snapshots, such as the `_entityFields` a related-path filter
+ * needs, stay legal.
+ *
  * @param spec - The definition to compile against, plus the node's inputs.
  * @returns A node to pass to `.step(...)`.
  */
@@ -126,14 +135,29 @@ class RawNode extends FlowAction {
         super();
         this.spec = spec;
     }
-    /** `check` surfaces the connector refusal as an error; `compile` throws it (see {@link contribute}). */
+    /**
+     * `check` surfaces the connector refusal as an error, a typed family as a
+     * warning, and a Data Fabric key the product never reads as an error at a
+     * bundled version (a warning at any other); `compile` throws the errors
+     * (see {@link contribute}).
+     */
     diagnostics() {
         const refusal = connectorRawNodeRefusal(this.spec.nodeType);
-        return refusal ? [{ code: 'RAW_NODE_CONNECTOR', severity: 'error', message: refusal }] : [];
+        if (refusal)
+            return [{ code: 'RAW_NODE_CONNECTOR', severity: 'error', message: refusal }];
+        const out = [];
+        const unknown = dataFabricUnknownInputs(this.spec.nodeType, this.spec.version, this.spec.inputs);
+        if (unknown)
+            out.push({ code: 'RAW_NODE_UNKNOWN_INPUT', ...unknown });
+        const typed = typedFamilyRawNodeWarning(this.spec.nodeType);
+        if (typed)
+            out.push({ code: 'RAW_NODE_TYPED_FAMILY', severity: 'warning', message: typed });
+        return out;
     }
     contribute(context) {
         // compile does not run diagnostics(); refuse here too so the escape hatch
-        // cannot emit an unconfigured connector node.
+        // cannot emit an unconfigured connector node. (A Data Fabric key the
+        // product never reads is refused by the serializer, for every contribution.)
         const refusal = connectorRawNodeRefusal(this.spec.nodeType);
         if (refusal)
             throw new Error(refusal);

package/dist/core/typed-raw-node.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Internal: what `check` and `compile` say about a `rawNode` for a node type
+ * the SDK has a typed factory for, and the Data Fabric input keys it may carry.
+ * Not re-exported from the package entry point.
+ */
+/** The factory to use for one node type, and the versions of it the SDK bundles. */
+export interface TypedFactory {
+    /** The typed spelling, as the refusal names it. */
+    factory: string;
+    /**
+     * Every `<version>` with a `<nodeType>@<version>` entry in `core-definitions.json`.
+     * Listed here rather than read from the file because this module sits under
+     * `node-classes.ts`, which must not import `node:*`; `raw-node-typed-family.test.ts`
+     * pins the two equal.
+     */
+    bundled: readonly string[];
+}
+/**
+ * Every node type the SDK authors as a STEP through a typed factory, with the
+ * factory to use. `raw-node-typed-family.test.ts` pins the key set to the
+ * `flow-coverage.json` rows with `support: 'typed'` and a `bundledKey`, so a
+ * family that gains a factory gains its row here too.
+ *
+ * Two groups of typed rows are left out, because neither is ever a step:
+ * triggers (`core.trigger.*`, placed by `.trigger()`) and agent resources
+ * (`uipath.agent.resource.*`, attached to an agent). `decompile` keeps an
+ * orphaned one as a `rawNode`, and a warning on that round trip would be noise.
+ *
+ * The Data Fabric verbs name their options, because the query and write keys
+ * an author reaches for by hand (`_filters`, `_sort`, `fieldValues`, …) each
+ * have a typed spelling.
+ */
+export declare const TYPED_FACTORIES: Readonly<Record<string, TypedFactory>>;
+/**
+ * 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 DATAFABRIC_ENTITY_CONFIG_KEYS: ReadonlySet<string>;
+/**
+ * A reminder, as a `warning`, that a `rawNode` stands in for a typed factory,
+ * or `undefined` for a type with no factory.
+ *
+ * A warning and never an error: a factory does not always write every input its
+ * node reads (the Data Fabric verbs do not write `_entityFields`, which a
+ * related-path filter needs), and nothing checks factory coverage family by
+ * family. So the raw node keeps compiling at every version. The one failure
+ * the eval archive measured, an invented key the node never reads, is refused
+ * by {@link dataFabricUnknownInputs} instead.
+ *
+ * @param nodeType - The definition's `nodeType`, as passed to `rawNode`.
+ * @returns The warning, or `undefined` for a type with no typed factory.
+ */
+export declare function typedFamilyRawNodeWarning(nodeType: string): string | undefined;
+/**
+ * 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 DATAFABRIC_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 version - The version the node is emitted at.
+ * @param inputs - The node's inputs, before rendering.
+ * @returns The diagnostic, or `undefined` for a clean node or a non-Data-Fabric type.
+ */
+export declare function dataFabricUnknownInputs(nodeType: string, version: string, inputs: unknown): {
+    severity: 'error' | 'warning';
+    message: string;
+} | undefined;

package/dist/core/typed-raw-node.js

@@ -0,0 +1,199 @@
+/**
+ * Internal: what `check` and `compile` say about a `rawNode` for a node type
+ * the SDK has a typed factory for, and the Data Fabric input keys it may carry.
+ * Not re-exported from the package entry point.
+ */
+/**
+ * Every node type the SDK authors as a STEP through a typed factory, with the
+ * factory to use. `raw-node-typed-family.test.ts` pins the key set to the
+ * `flow-coverage.json` rows with `support: 'typed'` and a `bundledKey`, so a
+ * family that gains a factory gains its row here too.
+ *
+ * Two groups of typed rows are left out, because neither is ever a step:
+ * triggers (`core.trigger.*`, placed by `.trigger()`) and agent resources
+ * (`uipath.agent.resource.*`, attached to an agent). `decompile` keeps an
+ * orphaned one as a `rawNode`, and a warning on that round trip would be noise.
+ *
+ * The Data Fabric verbs name their options, because the query and write keys
+ * an author reaches for by hand (`_filters`, `_sort`, `fieldValues`, …) each
+ * have a typed spelling.
+ */
+export const TYPED_FACTORIES = {
+    'core.action.http': { factory: 'http({ managed: false })', bundled: ['1.0.0'] },
+    'core.action.http.v2': { factory: 'http({ managed: true })', bundled: ['2.3'] },
+    'core.action.queue.create': { factory: 'queueItem()', bundled: ['1.2'] },
+    'core.action.queue.create-and-wait': { factory: 'queueItem({ wait: true })', bundled: ['1.2'] },
+    'core.action.script': { factory: 'script()', bundled: ['1.0.0', '1.1'] },
+    'core.action.transform': { factory: 'transform()', bundled: ['1.0.0', '1.1'] },
+    'core.action.transform.filter': { factory: "transform({ variant: 'filter' })", bundled: ['1.0.0', '1.1'] },
+    'core.action.transform.group-by': { factory: "transform({ variant: 'group-by' })", bundled: ['1.0.0', '1.1'] },
+    'core.action.transform.map': { factory: "transform({ variant: 'map' })", bundled: ['1.0.0', '1.1'] },
+    'core.control.end': { factory: '.return()', bundled: ['1.0.0', '1.0'] },
+    'core.datafabric.read': {
+        factory: "dataFabricRead({ entity, resultMode: 'single' | 'multiple', filters: [{ field, operator, value, or }], "
+            + 'sort: { field, direction }, limit, skip, fields, folderKey })',
+        bundled: ['1.0', '1.4'],
+    },
+    'core.datafabric.create': {
+        factory: 'dataFabricCreate({ entity, values: { <field>: <value> }, folderKey })',
+        bundled: ['1.3'],
+    },
+    'core.datafabric.update': {
+        factory: 'dataFabricUpdate({ entity, record: { byId } | { fromRead }, set: { <field>: <value> }, folderKey })',
+        bundled: ['1.0', '1.3'],
+    },
+    'core.datafabric.delete': {
+        factory: 'dataFabricDelete({ entity, record: { byId } | { fromRead }, folderKey })',
+        bundled: ['1.3'],
+    },
+    'core.logic.decision': { factory: '.branch()', bundled: ['1.0.0', '1.3'] },
+    'core.logic.delay': { factory: 'delay({ duration })', bundled: ['1.0.0', '1.0'] },
+    'core.logic.dowhile': { factory: '.doWhile(name, condition, body, { limit, breakEnabled })', bundled: ['1.0'] },
+    'core.logic.loop': { factory: '.loop()', bundled: ['1.0.0', '2.4'] },
+    'core.logic.merge': { factory: '.parallel() rejoin', bundled: ['1.0.0', '1.0'] },
+    'core.logic.mock': { factory: 'mock()', bundled: ['1.0.0', '1.0'] },
+    'core.logic.switch': { factory: '.switch()', bundled: ['1.0.0', '1.1'] },
+    'core.logic.terminate': { factory: '.terminate()', bundled: ['1.0.0', '1.0'] },
+    'core.subflow': { factory: 'subflow(child, inputs)', bundled: ['1.0.0', '1.0'] },
+    'uipath.agent.conversational': { factory: 'conversationalAgent()', bundled: ['1.6', '1.7'] },
+    'uipath.agent.voice': { factory: 'voiceAgent()', bundled: ['1.0', '1.1'] },
+    'uipath.conversational.get-conversation-context': { factory: 'conversationContext()', bundled: ['1.0'] },
+    'uipath.conversational.send-message': { factory: 'sendMessage()', bundled: ['1.0', '1.1'] },
+    'uipath.conversational.voice.create-outgoing-call': { factory: 'createOutgoingCall()', bundled: ['1.0'] },
+    'uipath.conversational.voice.end-call': { factory: 'endCall()', bundled: ['1.0'] },
+    'uipath.conversational.wait-for-message': { factory: 'waitForMessage()', bundled: ['1.0', '1.1'] },
+    'uipath.document.classify': { factory: 'documentClassify()', bundled: ['1.0'] },
+    'uipath.human-in-the-loop': { factory: 'hitl()', bundled: ['1.0', '1.1', '1.2'] },
+    'uipath.human-in-the-loop.coded-action-app': {
+        factory: "hitl({ variant: 'action-app' })",
+        bundled: ['1.0', '1.1'],
+    },
+    'uipath.human-in-the-loop.document-validation': {
+        factory: "hitl({ variant: 'document-validation' })",
+        bundled: ['1.0'],
+    },
+    'uipath.human-in-the-loop.quick-form': { factory: "hitl({ variant: 'quick-form' })", bundled: ['1.0', '1.1'] },
+    'uipath.pattern.batch-transform': { factory: 'batchTransform()', bundled: ['1.0'] },
+    'uipath.pattern.deep-rag': { factory: 'summarize()', bundled: ['1.0'] },
+    'uipath.ixp.extract-document-builder': { factory: 'dynamicExtract()', bundled: ['1.0.0'] },
+};
+/**
+ * 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 DATAFABRIC_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` (core/actions.ts `DataFabricFilter.field`).
+ */
+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.';
+/**
+ * A reminder, as a `warning`, that a `rawNode` stands in for a typed factory,
+ * or `undefined` for a type with no factory.
+ *
+ * A warning and never an error: a factory does not always write every input its
+ * node reads (the Data Fabric verbs do not write `_entityFields`, which a
+ * related-path filter needs), and nothing checks factory coverage family by
+ * family. So the raw node keeps compiling at every version. The one failure
+ * the eval archive measured, an invented key the node never reads, is refused
+ * by {@link dataFabricUnknownInputs} instead.
+ *
+ * @param nodeType - The definition's `nodeType`, as passed to `rawNode`.
+ * @returns The warning, or `undefined` for a type with no typed factory.
+ */
+export function typedFamilyRawNodeWarning(nodeType) {
+    if (typeof nodeType !== 'string')
+        return undefined;
+    const entry = TYPED_FACTORIES[nodeType];
+    if (entry === undefined)
+        return undefined;
+    const hint = nodeType.startsWith('core.datafabric.') ? DATAFABRIC_HINT : '';
+    return `rawNode("${nodeType}"): this SDK has a typed factory, ${entry.factory}. A raw node keeps its `
+        + `inputs verbatim, and \`validate\` cannot see a key the registry definition does not declare, so a `
+        + `misspelled input compiles and is ignored at run time. Prefer the factory unless you need an input it `
+        + `does not write.${hint}`;
+}
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+/**
+ * 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 DATAFABRIC_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 version - The version the node is emitted at.
+ * @param inputs - The node's inputs, before rendering.
+ * @returns The diagnostic, or `undefined` for a clean node or a non-Data-Fabric type.
+ */
+export function dataFabricUnknownInputs(nodeType, version, inputs) {
+    if (typeof nodeType !== 'string' || !nodeType.startsWith('core.datafabric.'))
+        return undefined;
+    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 (!DATAFABRIC_ENTITY_CONFIG_KEYS.has(k))
+                unknown.push(`entityConfig.${k}`);
+    }
+    if (unknown.length === 0)
+        return undefined;
+    const bundled = TYPED_FACTORIES[nodeType]?.bundled.includes(version) ?? false;
+    const named = unknown.map((k) => `\`${k}\``).join(', ');
+    const factory = TYPED_FACTORIES[nodeType]?.factory;
+    const base = `${nodeType}@${version} carries ${named}, which the platform never reads: Data Fabric `
+        + `nodes read only \`inputs.entityConfig\`, with the keys ${[...DATAFABRIC_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\`.${factory ? ` 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.',
+    };
+}

package/dist/registry/library-build/build.js

@@ -15,6 +15,7 @@ import { pyStr } from "../compat/pystr.js";
 import { mapConcurrent } from "../concurrency.js";
 import { Refusal, messageOf } from "../errors.js";
 import { registrySearchConnectors } from "../uip/commands.js";
+import { failureReason } from "../uip/envelope.js";
 import { applyCuratedOverrides, extractCanonical, filterNodeTypesByTier, mergeConnectorRecord, nodeOf, scopedConnectorKey, selectPublishedConnectors, } from "./canonical.js";
 import { SEARCH_RESULTS_NAME, createBuildContext, isConnectorGet, registryCacheName, registryGet, } from "./context.js";
 import { enrichAll } from "./enrich.js";
@@ -53,7 +54,7 @@ export async function registrySearch(ctx) {
         ctx.reporter.info("Running registry search...");
         const result = await ctx.client.run(registrySearchConnectors(), ctx.timeoutMs === undefined ? undefined : { timeoutMs: ctx.timeoutMs });
         if (result.code !== 0)
-            throw new Refusal(`Registry search failed: ${result.stderr}`, "REGISTRY_SEARCH_FAILED");
+            throw new Refusal(`Registry search failed: ${failureReason(result)}`, "REGISTRY_SEARCH_FAILED");
         ctx.caches.registry.write(SEARCH_RESULTS_NAME, undefined, result.stdout);
     }
     const data = ctx.caches.registry.read(SEARCH_RESULTS_NAME);

package/dist/registry/library-build/context.d.ts

@@ -60,6 +60,32 @@ export declare function registryCacheName(nodeType: string): string;
 export declare const SEARCH_RESULTS_NAME = "_search_results.json";
 /** `json.dump(payload, f)`: cache bytes shaped as Python wrote them. */
 export declare function writeCache(cache: ResponseCache, name: string, payload: unknown): void;
+/** A `registry get` that did not answer with the node, and why. */
+export interface RegistryMiss {
+    nodeType: string;
+    /** The CLI's own reason ({@link failureReason}); never empty. */
+    reason: string;
+    /**
+     * True only for the CLI's "Node not found" answer — the node is absent. False
+     * for every failure of the LOOKUP (an error, a refusal, a timeout), which says
+     * nothing about whether the node exists.
+     */
+    notFound: boolean;
+}
+/** {@link registryProbe}'s answer: the cache name of the reply, or the miss. */
+export type RegistryProbe = {
+    name: string;
+} | {
+    miss: RegistryMiss;
+};
+/**
+ * Cached `uip maestro flow registry get <nodeType>`, reporting nothing.
+ *
+ * The caller gets the miss with its reason and decides what to say — a caller
+ * probing which namespace an operation lives in puts every probe's reason into
+ * one refusal instead of a WARN per probe.
+ */
+export declare function registryProbe(ctx: BuildContext, nodeType: string): Promise<RegistryProbe>;
 /**
  * `registry_get`: cached `uip maestro flow registry get <nodeType>`.
  *

package/dist/registry/library-build/context.js

@@ -18,7 +18,7 @@ import { pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedByKeys } from "../compat/compare.js";
 import { isConnectorsMetadata, isResourcesDescribeObject, isResourcesDescribeOperation, isResourcesList as isResourcesListArgv, registryGet as registryGetArgv, } from "../uip/commands.js";
 import { CACHED_FAILURE, isCachedFailure, safeCacheName } from "../uip/response-cache.js";
-import { pyStrip } from "../compat/pystr.js";
+import { failureReason, isNodeNotFound } from "../uip/envelope.js";
 import { get, isRecord, pyOr, truthy } from "./py.js";
 export function createBuildContext(ports, scope = {}) {
     const parentFields = scope.parentFields instanceof Map
@@ -116,25 +116,38 @@ function envelope(payload) {
     return payload;
 }
 /**
- * `registry_get`: cached `uip maestro flow registry get <nodeType>`.
+ * Cached `uip maestro flow registry get <nodeType>`, reporting nothing.
  *
- * Returns the cache name the raw stdout lives under, or `undefined` when the
- * call failed. `quiet` suppresses the failure WARN — for a caller probing which
- * of several node-type namespaces an action lives in, where a miss is an
- * expected answer rather than a problem to report.
+ * The caller gets the miss with its reason and decides what to say — a caller
+ * probing which namespace an operation lives in puts every probe's reason into
+ * one refusal instead of a WARN per probe.
  */
-export async function registryGet(ctx, nodeType, quiet = false) {
+export async function registryProbe(ctx, nodeType) {
     const name = registryCacheName(nodeType);
     if (ctx.caches.registry.has(name))
-        return name;
+        return { name };
     const result = await runUip(ctx, registryGetArgv(nodeType, ctx.connectionId));
     if (result.code !== 0) {
-        if (!quiet)
-            ctx.reporter.warn(`  WARN: registry get failed for ${nodeType}: ${pyStrip(result.stderr)}`);
-        return undefined;
+        return { miss: { nodeType, reason: failureReason(result), notFound: isNodeNotFound(result) } };
     }
     ctx.caches.registry.write(name, undefined, result.stdout);
-    return name;
+    return { name };
+}
+/**
+ * `registry_get`: cached `uip maestro flow registry get <nodeType>`.
+ *
+ * Returns the cache name the raw stdout lives under, or `undefined` when the
+ * call failed. `quiet` suppresses the failure WARN — for a caller probing which
+ * of several node-type namespaces an action lives in, where a miss is an
+ * expected answer rather than a problem to report.
+ */
+export async function registryGet(ctx, nodeType, quiet = false) {
+    const probe = await registryProbe(ctx, nodeType);
+    if ("name" in probe)
+        return probe.name;
+    if (!quiet)
+        ctx.reporter.warn(`  WARN: registry get failed for ${nodeType}: ${probe.miss.reason}`);
+    return undefined;
 }
 function noteFailedFieldDescribe(ctx, connectorKey, objectName, operation, message) {
     if (ctx.parentFields.size > 0) {