@uipath/maestro-builder-sdk 6.8.5 → 6.8.6

package/dist/registry/prepare/event.d.ts

@@ -1,4 +1,4 @@
-import { type BuildContext } from "../library-build/context.js";
+import { type BuildContext, type RegistryMiss } from "../library-build/context.js";
 import { type EventFacts } from "../library-build/events.js";
 import { type Dict } from "../library-build/py.js";
 import type { LibraryEntry } from "../model/library.js";
@@ -87,10 +87,19 @@ export interface EventPrepareResult {
     filterFields: unknown[];
     definition: EventDefinition;
 }
+/** `<key> <action>` is not an event: the `.trigger.` probe missed, and why. */
+export interface EventMiss {
+    missed: RegistryMiss;
+}
 /**
- * `_prepare_event`. Returns `undefined` when `<key> <action>` is not an event
- * either, so the caller can raise the ordinary unknown-action refusal;
- * everything else is handled here, refusals included. `ctx.connectionId` must
- * already be the connection: the trigger definition only answers with one.
+ * `_prepare_event`. Returns an {@link EventMiss} when `<key> <action>` is not
+ * an event either — carrying the probe's reason, so the caller can put it in
+ * the one refusal that names both namespaces; everything else is handled here,
+ * refusals included. `ctx.connectionId` must already be the connection: the
+ * trigger definition only answers with one.
+ *
+ * The probe is quiet. The Python printed a `WARN: registry get failed for …`
+ * here, and the port printed it with an empty reason, because the CLI's reason
+ * is on stdout; the reason now travels in the result instead.
  */
-export declare function prepareEvent(ctx: BuildContext, options: EventPrepareOptions): Promise<EventPrepareResult | undefined>;
+export declare function prepareEvent(ctx: BuildContext, options: EventPrepareOptions): Promise<EventPrepareResult | EventMiss>;

package/dist/registry/prepare/event.js

@@ -20,7 +20,7 @@
  * through its reporter, in the Python's order.
  */
 import { extractCanonical, nodeOf } from "../library-build/canonical.js";
-import { registryGet } from "../library-build/context.js";
+import { registryProbe } from "../library-build/context.js";
 import { EventDiscoveryError, eventFacts, mergeDescribeIntoNode, triggersDescribe, triggersObjects, unionEventParameters, } from "../library-build/events.js";
 import { get, isRecord } from "../library-build/py.js";
 import { planLibrary } from "../library-build/plan.js";
@@ -114,10 +114,15 @@ function fieldsOf(section) {
     return Array.isArray(fields) ? fields : [];
 }
 /**
- * `_prepare_event`. Returns `undefined` when `<key> <action>` is not an event
- * either, so the caller can raise the ordinary unknown-action refusal;
- * everything else is handled here, refusals included. `ctx.connectionId` must
- * already be the connection: the trigger definition only answers with one.
+ * `_prepare_event`. Returns an {@link EventMiss} when `<key> <action>` is not
+ * an event either — carrying the probe's reason, so the caller can put it in
+ * the one refusal that names both namespaces; everything else is handled here,
+ * refusals included. `ctx.connectionId` must already be the connection: the
+ * trigger definition only answers with one.
+ *
+ * The probe is quiet. The Python printed a `WARN: registry get failed for …`
+ * here, and the port printed it with an empty reason, because the CLI's reason
+ * is on stdout; the reason now travels in the result instead.
  */
 export async function prepareEvent(ctx, options) {
     const { connectorKey, action, connectionId, out } = options;
@@ -125,13 +130,16 @@ export async function prepareEvent(ctx, options) {
     const info = (line) => ctx.reporter.info(line);
     const warn = (line) => ctx.reporter.warn(line);
     const { trigger: triggerNodeType, event: eventNodeType } = eventNodeTypes(connectorKey, action);
-    const cacheName = await registryGet(ctx, triggerNodeType);
-    if (cacheName === undefined)
-        return undefined;
-    const payload = ctx.caches.registry.read(cacheName);
+    const probe = await registryProbe(ctx, triggerNodeType);
+    if ("miss" in probe)
+        return { missed: probe.miss };
+    const payload = ctx.caches.registry.read(probe.name);
     const canonical = extractCanonical(nodeOf(payload));
-    if (canonical === undefined)
-        return undefined;
+    if (canonical === undefined) {
+        // An answer, but not one this code can read as a trigger definition. Not
+        // "absent", so the caller must not say it is.
+        return { missed: { nodeType: triggerNodeType, reason: "the registry answered, but not with a node definition", notFound: false } };
+    }
     if (pyTruthy(options.fields))
         throw new PrepareRefusal(eventParentFieldsMessage(), "EVENT_NO_PARENT_FIELDS");
     if (options.allObjects)

package/dist/registry/prepare/messages.d.ts

@@ -21,6 +21,7 @@
  *     `core/cli-spelling.ts`) without this module reading the environment.
  */
 import { Refusal } from "../errors.js";
+import { type RegistryCatalog } from "./actions.js";
 export declare const PREFIX = "prepare-connector: ";
 /** The spelling the Python hard-coded into every pasteable re-run. */
 export declare const PREPARE_COMMAND = "npx flow-sdk registry prepare";
@@ -45,16 +46,43 @@ export declare function connectionLine(row: Record<string, unknown>, connectionI
 export declare function bindingsLine(symbolicName: string, bindingsPath: string): string;
 /** `_missing_generic_schema_message`: a Generic action that expanded to nothing. */
 export declare function missingGenericSchemaMessage(operation: string, objectName?: string | null): string;
+/** One `registry get` probe that missed, as a refusal quotes it. */
+export interface ProbeMiss {
+    nodeType: string;
+    /** The CLI's reason, never empty (`failureReason`). */
+    reason: string;
+}
 /**
- * `_unresolved_action_message`: what to do when the action id is not a
- * registry key. `actions` is what `registry search <key>` served (see
- * `actions.ts`); the message is pure over it.
+ * What to do when `<key> <name>` is neither an action nor an event: both
+ * `registry get` probes answered "Node not found". Pure over its inputs.
+ *
+ * It names both probes, because the author's name may have meant either
+ * namespace and the SDK cannot know which (so the code is OPERATION_UNKNOWN,
+ * not ACTION_UNKNOWN), and it lists both catalogs `registry search <key>`
+ * served. Until 2026-09 this was an action-only message: it named the action
+ * node type, said "Re-run with a registry action id" and listed only actions,
+ * because `registryActionIds` removes event ids by design. For
+ * `uipath-uipath-dataservice record-created` — an EVENT the catalog had stopped
+ * serving — that sent the author after action ids (2026-09-23 eval,
+ * `skill-flow-datafabric-trigger-lifecycle`, v2 command 33).
  *
  * NOT auto-substituted, deliberately: the baked action id and the registry key
  * are different namespaces, and guessing between them would emit a node both
  * offline validators accept and the runtime dispatches to the wrong operation.
  */
-export declare function unresolvedActionMessage(connectorKey: string, action: string, nodeType: string, actions: readonly string[]): string;
+export declare function unresolvedOperationMessage(input: {
+    connectorKey: string;
+    name: string;
+    probes: readonly ProbeMiss[];
+    catalog: RegistryCatalog;
+}): string;
+/**
+ * A `registry get` probe failed for a reason other than "Node not found" — an
+ * error inside the CLI, a refusal, a timeout, a reply that is not JSON. That is
+ * not evidence the node is absent, so this refusal says so and carries the
+ * CLI's own reasons instead of listing alternatives.
+ */
+export declare function registryGetFailedMessage(connectorKey: string, name: string, probes: readonly ProbeMiss[]): string;
 export declare function noCanonicalEntryMessage(nodeType: string): string;
 /** The `-f` names do not match any api-type ObjectAction; `specs` are the actions' parent lists. */
 export declare function parentFieldNamesMismatchMessage(given: readonly string[], specs: ReadonlyArray<readonly [string, readonly string[]]>): string;

package/dist/registry/prepare/messages.js

@@ -21,7 +21,7 @@
  *     `core/cli-spelling.ts`) without this module reading the environment.
  */
 import { Refusal, messageOf } from "../errors.js";
-import { closestActions } from "./actions.js";
+import { plausibleMatches } from "./actions.js";
 import { pyGet, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
 export const PREFIX = "prepare-connector: ";
 /** The spelling the Python hard-coded into every pasteable re-run. */
@@ -74,33 +74,98 @@ export function missingGenericSchemaMessage(operation, objectName) {
         "not need connection-specific fields, use the baked connector descriptor " +
         "without custom fields instead.");
 }
+function probeLines(probes) {
+    return probes.map((probe) => `  registry get ${probe.nodeType} → ${probe.reason}`);
+}
+/** `record-created (trigger, event)`: an event id with the forms the registry served it in. */
+function eventLabel(event) {
+    return `${event.id} (${event.forms.join(", ")})`;
+}
+/** How many of `wanted`'s hyphen tokens `candidate` shares. */
+function sharedTokens(wanted, candidate) {
+    const tokens = new Set(candidate.split("-"));
+    return [...new Set(wanted.split("-"))].filter((token) => tokens.has(token)).length;
+}
 /**
- * `_unresolved_action_message`: what to do when the action id is not a
- * registry key. `actions` is what `registry search <key>` served (see
- * `actions.ts`); the message is pure over it.
+ * What to do when `<key> <name>` is neither an action nor an event: both
+ * `registry get` probes answered "Node not found". Pure over its inputs.
+ *
+ * It names both probes, because the author's name may have meant either
+ * namespace and the SDK cannot know which (so the code is OPERATION_UNKNOWN,
+ * not ACTION_UNKNOWN), and it lists both catalogs `registry search <key>`
+ * served. Until 2026-09 this was an action-only message: it named the action
+ * node type, said "Re-run with a registry action id" and listed only actions,
+ * because `registryActionIds` removes event ids by design. For
+ * `uipath-uipath-dataservice record-created` — an EVENT the catalog had stopped
+ * serving — that sent the author after action ids (2026-09-23 eval,
+ * `skill-flow-datafabric-trigger-lifecycle`, v2 command 33).
  *
  * NOT auto-substituted, deliberately: the baked action id and the registry key
  * are different namespaces, and guessing between them would emit a node both
  * offline validators accept and the runtime dispatches to the wrong operation.
  */
-export function unresolvedActionMessage(connectorKey, action, nodeType, actions) {
+export function unresolvedOperationMessage(input) {
+    const { connectorKey: key, name, probes, catalog } = input;
     const lines = [
-        `${PREFIX}\`registry get ${nodeType}\` found no such node.`,
+        `${PREFIX}\`${key} ${name}\` is neither an action nor an event the registry serves:`,
+        ...probeLines(probes),
         "",
-        "The baked library's action id is not always the registry's key — a Generic",
-        "op is `list-all-records` in the library and materializes per object, while",
-        "the registry serves the un-expanded form. Re-run with a registry action id.",
+        // flow-v1 `packages/flow-core/src/manifest/fetchers.ts:286`, `:336-337`: the
+        // node catalog is the typecache Search/Catalog, and a trigger node exists
+        // only where it serves one.
+        "A Flow node exists only if the tenant's Flow node catalog serves it. An event that",
+        "`uip is triggers objects` lists but this registry does not cannot be prepared or",
+        "compiled, and hand-writing its node JSON does not make it offered.",
     ];
-    if (actions.length === 0) {
-        lines.push("", `\`registry search ${connectorKey}\` returned nothing. If the catalog looks`, "stale, refresh it first: `uip maestro flow registry pull --force`.");
+    if (catalog.failure !== undefined) {
+        lines.push("", `\`registry search ${key}\` failed: ${catalog.failure}`, "so what the registry does serve for it could not be listed.");
         return lines.join("\n");
     }
-    const close = closestActions(action, actions);
-    if (close.length > 0)
-        lines.push("", `Closest to "${action}": ${close.slice(0, 3).join(", ")}`);
-    lines.push("", `All actions the registry serves for ${connectorKey}:`, ...actions.map((a) => `  ${a}`));
+    if (catalog.events.length > 0) {
+        const close = plausibleMatches(name, catalog.events.map((event) => event.id));
+        const byId = new Map(catalog.events.map((event) => [event.id, event]));
+        if (close.length > 0)
+            lines.push("", `Closest event to "${name}": ${close.slice(0, 3).map((id) => eventLabel(byId.get(id))).join(", ")}`);
+        lines.push("", `Events the registry serves for ${key}:`, ...catalog.events.map((event) => `  ${eventLabel(event)}`));
+    }
+    else {
+        lines.push("", `\`registry search ${key}\` lists no \`uipath.connector.{trigger,event}.${key}.*\` node: the`, `registry serves no event for ${key}.`);
+    }
+    if (catalog.actions.length > 0) {
+        const close = plausibleMatches(name, catalog.actions);
+        if (close.length > 0)
+            lines.push("", `Closest action to "${name}": ${close.slice(0, 3).join(", ")}`);
+        // The Generic explanation only where the name reads like one of these
+        // actions (most of its words shared): `list-all-records` against
+        // `list-records`, not `record-created` against `create-entity-record`,
+        // where it would point an event request at action ids again.
+        const wanted = new Set(name.split("-")).size;
+        if (close.length > 0 && sharedTokens(name, close[0]) * 2 > wanted) {
+            lines.push("The baked library's action id is not always the registry's key — a Generic", "op is `list-all-records` in the library and materializes per object, while", "the registry serves the un-expanded form. For an action, re-run with a registry action id.");
+        }
+        lines.push("", `All actions the registry serves for ${key}:`, ...catalog.actions.map((a) => `  ${a}`));
+    }
+    else {
+        lines.push("", `\`registry search ${key}\` lists no action for ${key} either.`);
+    }
+    lines.push("", "`registry get` and `registry search` answer from the CLI's local copy of the catalog.", "If it looks stale, refresh it first: `uip maestro flow registry pull --force`.");
     return lines.join("\n");
 }
+/**
+ * A `registry get` probe failed for a reason other than "Node not found" — an
+ * error inside the CLI, a refusal, a timeout, a reply that is not JSON. That is
+ * not evidence the node is absent, so this refusal says so and carries the
+ * CLI's own reasons instead of listing alternatives.
+ */
+export function registryGetFailedMessage(connectorKey, name, probes) {
+    return [
+        `${PREFIX}could not tell whether \`${connectorKey} ${name}\` is an action or an event: a registry`,
+        "lookup failed, which does not mean the node is absent.",
+        ...probeLines(probes),
+        "",
+        "Resolve the failure above and re-run prepare.",
+    ].join("\n");
+}
 export function noCanonicalEntryMessage(nodeType) {
     return `${PREFIX}no canonical entry for ${nodeType} (unexpected registry shape).`;
 }

package/dist/registry/prepare/pipeline.js

@@ -28,17 +28,17 @@ import { resolve } from "node:path";
 import { PACKAGE_NAME } from "../../package-name.js";
 import { afterLast } from "../compat/pystr.js";
 import { extractCanonical, isHttpPassthrough, nodeOf } from "../library-build/canonical.js";
-import { createBuildContext, isResourcesList, registryGet } from "../library-build/context.js";
+import { createBuildContext, isResourcesList, registryProbe } from "../library-build/context.js";
 import { enrichEntry } from "../library-build/enrich.js";
 import { expandGenericForConnector, genericTemplatesByOp } from "../library-build/generic-expand.js";
 import { planLibrary } from "../library-build/plan.js";
 import { MemoryResponseCache } from "../uip/response-cache.js";
-import { registryActions } from "./actions.js";
+import { registryCatalog } from "./actions.js";
 import { discoverConnection, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, } from "./connections.js";
 import { prepareEvent } from "./event.js";
 import { descriptorUsage } from "./handoff.js";
 import { ResolutionsExhausted, allParentsResolved, resolvedParentValues, writeResolutions } from "./ledger.js";
-import { PREPARE_COMMAND, PrepareRefusal, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, keptSchemaMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, tsNote, unresolvedActionMessage, } from "./messages.js";
+import { PREPARE_COMMAND, PrepareRefusal, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, keptSchemaMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, tsNote, unresolvedOperationMessage, } from "./messages.js";
 import { ObjectMatchRefusal, RESOLUTIONS_FILENAME, matchObject, recordObjectResolution } from "./objects.js";
 import { countInputFields, keepPreparedSchema, lookupSpecsFromOverlay, mergeFilesInto, parentFields as overlayParentFields, schemaActionParents, } from "./overlay.js";
 import { declaredParents, objectActionRequest, objectActionSpecs, parseFields } from "./parents.js";
@@ -207,8 +207,8 @@ async function prepareOnConnection(options, ports, connected) {
     const { connectionId, bound, rollback } = connected;
     const ctx = createBuildContext({ client: ports.client, caches: ports.caches ?? memoryCaches(), reporter: ports.reporter, concurrency: 1, timeoutMs: ports.timeoutMs }, { connectionId, parentFields });
     const nodeType = `uipath.connector.${connectorKey}.${action}`;
-    const cacheName = await registryGet(ctx, nodeType, true);
-    if (cacheName === undefined) {
+    const actionProbe = await registryProbe(ctx, nodeType);
+    if ("miss" in actionProbe) {
         // Not an activity. Connector EVENTS live one namespace over, and their
         // registry definition only answers with a connection, which this command
         // has by now. Same loop, different twin pair.
@@ -230,13 +230,19 @@ async function prepareOnConnection(options, ports, connected) {
             bindings: rollback,
             prepareCommand: command,
         });
-        if (event !== undefined) {
+        if (!("missed" in event)) {
             return { kind: "event", nodeType: event.eventNodeType, connectionId, bound, objectName: event.objectName };
         }
-        const actions = await registryActions(ports.client, connectorKey, ports.timeoutMs);
-        throw new PrepareRefusal(unresolvedActionMessage(connectorKey, action, nodeType, actions), "ACTION_UNKNOWN");
+        const probes = [actionProbe.miss, event.missed];
+        // Only the CLI's "Node not found" says a node is absent. Any other failure
+        // of either lookup is reported as the failure it is, never as a verdict.
+        if (probes.some((probe) => !probe.notFound)) {
+            throw new PrepareRefusal(registryGetFailedMessage(connectorKey, action, probes), "REGISTRY_GET_FAILED");
+        }
+        const catalog = await registryCatalog(ports.client, connectorKey, ports.timeoutMs);
+        throw new PrepareRefusal(unresolvedOperationMessage({ connectorKey, name: action, probes, catalog }), "OPERATION_UNKNOWN");
     }
-    const payload = ctx.caches.registry.read(cacheName);
+    const payload = ctx.caches.registry.read(actionProbe.name);
     // The registry's own declaration of parent inputs, read from the same reply.
     const declared = declaredParents(payload);
     let entry = extractCanonical(nodeOf(payload));

package/dist/registry/prepare/resolve.js

@@ -22,6 +22,7 @@ import { pyFloatRepr } from "../codecs/pyjson.js";
 import { pyStrip, pyStripChars, splitOnce } from "../compat/pystr.js";
 import { Refusal } from "../errors.js";
 import { isResourcesRunList } from "../uip/commands.js";
+import { failureReason } from "../uip/envelope.js";
 import { isPlainObject, notJsonReason, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
 /**
  * A scan has to stop somewhere, and the caps must be set against the MEASURED
@@ -361,7 +362,7 @@ export function parseListingDocument(text) {
 export async function listPage(client, connectorKey, collection, connectionId, query) {
     const result = await client.run(isResourcesRunList(connectorKey, collection, connectionId, query));
     if (result.code !== 0) {
-        throw new ResolutionRefusal(`listing ${collection} failed: ${pyStrip(result.stderr) || "no output"}`, "RESOLVE_LISTING_FAILED");
+        throw new ResolutionRefusal(`listing ${collection} failed: ${failureReason(result)}`, "RESOLVE_LISTING_FAILED");
     }
     const envelope = parseListingDocument(result.stdout);
     if (!isPlainObject(envelope)) {

package/dist/registry/uip/envelope.d.ts

@@ -1,12 +1,4 @@
-/**
- * Reading what `uip … --output json` prints.
- *
- * The CLI is chatty: an update banner, a tool-version warning and a
- * `ManifestClient` diagnostic can precede the JSON document, and the document
- * itself is a `{ Result, Data, Message, … }` envelope whose key casing has
- * varied between tools. Three Python callers each had their own loop for
- * finding the document; this is the one loop, and the one accessor.
- */
+import type { UipResult } from "./client.js";
 /** The shape every `uip` JSON response shares, read case-insensitively. */
 export interface UipEnvelope {
     Result?: unknown;
@@ -35,3 +27,46 @@ export declare function isSuccess(envelope: UipEnvelope | undefined): boolean;
 export declare function dataItems(envelope: UipEnvelope | undefined): unknown[];
 /** The last `limit` characters of a stream, for a message. */
 export declare function tail(text: string, limit?: number): string;
+/**
+ * Why a `uip` call failed, as text a message can quote after a colon. Never empty.
+ *
+ * `uip … --output json` prints its FAILURE envelope on stdout, not stderr:
+ * `OutputFormatter.error` hands it to `logOutput`, which writes through
+ * `sink.writeOut` (uipath-cli `packages/common/src/formatter.ts:1657-1688` and
+ * `:654-675`). For example, `registry get` of a node the catalog does not serve
+ * exits 1 with this on stdout:
+ *
+ * ```json
+ * { "Result": "Failure", "Message": "Node not found",
+ *   "Instructions": "No node found with node type: uipath.connector.trigger.…" }
+ * ```
+ *
+ * and, on stderr, nothing, or a `[ManifestClient] fetchDynamicNodes ok: …`
+ * diagnostic, or a self-update banner. Callers that quoted stderr printed
+ * `registry get failed for <nodeType>: ` with nothing after the colon (2026-09-23
+ * eval, `skill-flow-datafabric-trigger-lifecycle`, v2 command 33).
+ *
+ * So the envelope is read first. The order is:
+ *
+ *  1. a call the client refused (`OfflineUipClient`): no process ran, and its
+ *     stderr already says so (`offline: refused to run …`), so that text is kept;
+ *  2. a call killed by its timeout: `timed out`, whatever partial output it left;
+ *  3. a non-Success envelope on stdout (found past any banner, keys read
+ *     case-insensitively): `<Message>: <Instructions>`, or whichever is present;
+ *  4. the end of stderr, then the end of stdout;
+ *  5. `no output`.
+ */
+export declare function failureReason(result: UipResult): string;
+/**
+ * True when a failed `registry get` answered the CLI's own "not in the catalog"
+ * envelope, `Message: "Node not found"` (uipath-cli
+ * `packages/maestro-sdk/src/registry/command.ts:595-600`).
+ *
+ * Only that answer says the node is ABSENT. Every other failure — `Error
+ * retrieving node` (`command.ts:586-591`, which carries the thrown error in
+ * `Instructions`), a refusal, a timeout, output that is not JSON — says the
+ * lookup did not work, which is a different fact with a different remedy. The
+ * `Message` is the discriminator because the envelope's `ErrorCode` is the
+ * generic `unknown_error` for both (`formatter.ts:1490-1502`).
+ */
+export declare function isNodeNotFound(result: UipResult): boolean;

package/dist/registry/uip/envelope.js

@@ -6,7 +6,12 @@
  * itself is a `{ Result, Data, Message, … }` envelope whose key casing has
  * varied between tools. Three Python callers each had their own loop for
  * finding the document; this is the one loop, and the one accessor.
+ *
+ * It is also the one place that decides why a call FAILED ({@link failureReason}).
+ * Callers outside `registry/uip/` do not read a result's stderr themselves;
+ * `tests/uip-stderr-gate.test.ts` holds them to that.
  */
+import { pyStrip } from "../compat/pystr.js";
 /**
  * The first JSON document in `text`, or `undefined`.
  *
@@ -82,3 +87,78 @@ export function dataItems(envelope) {
 export function tail(text, limit = 300) {
     return text.length <= limit ? text : text.slice(text.length - limit);
 }
+/** A non-empty trimmed string, or `undefined`. */
+function said(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const text = pyStrip(value);
+    return text === "" ? undefined : text;
+}
+/**
+ * Why a `uip` call failed, as text a message can quote after a colon. Never empty.
+ *
+ * `uip … --output json` prints its FAILURE envelope on stdout, not stderr:
+ * `OutputFormatter.error` hands it to `logOutput`, which writes through
+ * `sink.writeOut` (uipath-cli `packages/common/src/formatter.ts:1657-1688` and
+ * `:654-675`). For example, `registry get` of a node the catalog does not serve
+ * exits 1 with this on stdout:
+ *
+ * ```json
+ * { "Result": "Failure", "Message": "Node not found",
+ *   "Instructions": "No node found with node type: uipath.connector.trigger.…" }
+ * ```
+ *
+ * and, on stderr, nothing, or a `[ManifestClient] fetchDynamicNodes ok: …`
+ * diagnostic, or a self-update banner. Callers that quoted stderr printed
+ * `registry get failed for <nodeType>: ` with nothing after the colon (2026-09-23
+ * eval, `skill-flow-datafabric-trigger-lifecycle`, v2 command 33).
+ *
+ * So the envelope is read first. The order is:
+ *
+ *  1. a call the client refused (`OfflineUipClient`): no process ran, and its
+ *     stderr already says so (`offline: refused to run …`), so that text is kept;
+ *  2. a call killed by its timeout: `timed out`, whatever partial output it left;
+ *  3. a non-Success envelope on stdout (found past any banner, keys read
+ *     case-insensitively): `<Message>: <Instructions>`, or whichever is present;
+ *  4. the end of stderr, then the end of stdout;
+ *  5. `no output`.
+ */
+export function failureReason(result) {
+    if (result.refused === true)
+        return said(result.stderr) ?? "not run (offline client refused the call)";
+    if (result.timedOut === true)
+        return "timed out (the call was killed before it answered)";
+    const envelope = parseEnvelope(result.stdout);
+    if (envelope !== undefined && !isSuccess(envelope)) {
+        const parts = [said(getCI(envelope, "Message")), said(getCI(envelope, "Instructions"))].filter((part) => part !== undefined);
+        if (parts.length > 0)
+            return parts.join(": ");
+    }
+    const stderr = said(result.stderr);
+    if (stderr !== undefined)
+        return tail(stderr);
+    const stdout = said(result.stdout);
+    if (stdout !== undefined)
+        return tail(stdout);
+    return "no output";
+}
+/**
+ * True when a failed `registry get` answered the CLI's own "not in the catalog"
+ * envelope, `Message: "Node not found"` (uipath-cli
+ * `packages/maestro-sdk/src/registry/command.ts:595-600`).
+ *
+ * Only that answer says the node is ABSENT. Every other failure — `Error
+ * retrieving node` (`command.ts:586-591`, which carries the thrown error in
+ * `Instructions`), a refusal, a timeout, output that is not JSON — says the
+ * lookup did not work, which is a different fact with a different remedy. The
+ * `Message` is the discriminator because the envelope's `ErrorCode` is the
+ * generic `unknown_error` for both (`formatter.ts:1490-1502`).
+ */
+export function isNodeNotFound(result) {
+    if (result.code === 0 || result.refused === true || result.timedOut === true)
+        return false;
+    const envelope = parseEnvelope(result.stdout);
+    if (envelope === undefined || isSuccess(envelope))
+        return false;
+    return said(getCI(envelope, "Message"))?.toLowerCase() === "node not found";
+}

package/dist/serialize.js

@@ -13,6 +13,7 @@ import { dirname, join } from 'node:path';
 import { Expr, toExpr, SCHEDULE_PRESETS, DELAY_PRESETS, parseIxpProjectType, flatNameOf, flatNameSegmentsOf } from './flow-sdk.js';
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
+import { dataFabricUnknownInputs } from './core/typed-raw-node.js';
 import { bindingSelfNameMessage } from './core/binding-messages.js';
 import { OUTCOME_HANDLE_NODE_TYPES, assertHitlExitInvariant, hitlExitModel, hitlExitViolation, outcomeSlug } from './core/hitl-routing.js';
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
@@ -3928,7 +3929,14 @@ export function serialize(built, opts = {}) {
             display: { label, ...(def?.display?.icon ? { icon: def.display.icon } : {}) },
         };
         col++;
-        if (def?.model)
+        // A Data Fabric node gets no node-level `model`, whichever path emits it
+        // (the typed verbs, or a rawNode through emitContribution). Studio Web
+        // never writes one (flow-core node.ts: "`node.model` is never written";
+        // canvas `nodeToInstance` omits it), and export seeds it from the
+        // definition (services bpmn-to-xml.ts), so a copy here can only go stale.
+        // `outputs` stay: the canvas persists them (`source: '=response'`), and
+        // `variables.nodes[]` is derived from them.
+        if (def?.model && !type.startsWith('core.datafabric.'))
             node.model = subNodeId(clone(def.model), id);
         if (def?.outputDefinition)
             node.outputs = subNodeId(clone(def.outputDefinition), id);
@@ -4170,6 +4178,12 @@ export function serialize(built, opts = {}) {
         const connectorRefusal = connectorRawNodeRefusal(def.nodeType);
         if (connectorRefusal)
             throw new Error(`${where}: ${connectorRefusal}`);
+        // A Data Fabric key the product never reads (`_sortOptions`) is refused for
+        // every contribution, whichever class or SDK copy made it: `validate`
+        // cannot see it, and the node would ignore it at run time.
+        const unknownInput = dataFabricUnknownInputs(def.nodeType, def.version, contribution.inputs);
+        if (unknownInput?.severity === 'error')
+            throw new Error(`${where}: ${unknownInput.message}`);
         const id = stepUid(scope, stepName);
         const node = makeNode(def.nodeType, id, stepName, { parentId, def, requestedVersion });
         node.inputs = renderDeep(contribution.inputs ?? {}, scope.rename);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.8.5",
+  "version": "6.8.6",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "07d7820cfddf1603444213859a340b4e9dbe643e"
+  "gitref": "503ff8140144536c938e0b0ad0356b6ccb41b9f9"
 }