@uipath/maestro-builder-sdk 6.18.10 → 6.20.0

package/dist/nodes/transform/flow/node-type.js

@@ -0,0 +1,245 @@
+/**
+ * The four Transform node types: the generic chaining `core.action.transform`
+ * and its single-purpose `.filter`, `.map` and `.group-by` variants, each bundled
+ * at 1.0.0 and 1.1. They share the `transform` kind; `inputs.variant` picks one
+ * (`matches`). Moved from serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, printed source,
+ * codes and messages unchanged.
+ */
+import { Expr } from '../../../core/expr.js';
+import { wireExprBody } from '../../../core/wire-expr.js';
+import { jsonClone } from '../../../core/json-file.js';
+import { VARIANT_OPERATION } from './spec.js';
+import { checkTransform } from './check.js';
+/**
+ * Emit a transform's `inputs` in the canonical shape the node's runtime reads:
+ * `collection` as a BARE variable path (not `=js:`-prefixed — it is a path
+ * field, and the runtime turns the string into a lookup), and `operations` as
+ * the array of `{ id, type, config }` descriptors the designer writes.
+ *
+ * Ids are synthesized here rather than asked of the author, the same way switch
+ * case ids are: they identify a row in the designer's editor and carry no
+ * meaning for the author. Defaults are made explicit for the same reason the
+ * HTTP case spells out `method`/`contentType` — the emitted file should say
+ * what it does rather than rely on the runtime's fallbacks.
+ */
+function transformInputs(inputs, ctx) {
+    const operations = (inputs.operations ?? []).map((op, i) => {
+        const id = `op${i + 1}`;
+        if (op.type === 'filter') {
+            return {
+                id,
+                type: 'filter',
+                config: {
+                    operation: op.operation ?? 'and',
+                    filters: (op.filters ?? []).map((f, j) => ({
+                        id: `f${j + 1}`,
+                        field: f.field,
+                        condition: f.condition,
+                        // Value-free conditions (is_null, is_empty, …) legitimately omit it.
+                        ...(f.value !== undefined ? { value: f.value } : {}),
+                    })),
+                },
+            };
+        }
+        if (op.type === 'map') {
+            return {
+                id,
+                type: 'map',
+                config: {
+                    keepOriginalFields: op.keepOriginalFields ?? false,
+                    mappings: (op.mappings ?? []).map((m, j) => ({
+                        id: `m${j + 1}`,
+                        field: m.field,
+                        transformation: m.transformation ?? 'copy',
+                        // '' is the runtime's "keep the original name" sentinel.
+                        renameTo: m.renameTo ?? '',
+                    })),
+                },
+            };
+        }
+        return {
+            id,
+            type: 'groupBy',
+            config: {
+                groupByField: op.groupByField,
+                aggregations: (op.aggregations ?? []).map((a, j) => ({
+                    id: `a${j + 1}`,
+                    // `count` needs no field; the runtime expects the key present anyway.
+                    field: a.field ?? '',
+                    operation: a.operation,
+                    alias: a.alias,
+                })),
+            },
+        };
+    });
+    return { collection: ctx.renameRefs(collectionPath(inputs.collection)), operations };
+}
+/**
+ * The `collection` string. A bare reference (`v('x')` / `out('s','p')`) is
+ * already the path the runtime wants, so it is emitted verbatim. Anything else
+ * cannot be expressed as a path — `check` rejects it (TRANSFORM_COLLECTION_*)
+ * before serialization, so reaching here with one means `compile` was called
+ * without a check; emit the raw text so the failure stays visible downstream
+ * rather than becoming a silently empty collection.
+ */
+function collectionPath(collection) {
+    if (collection instanceof Expr)
+        return collection.literal ? JSON.stringify(collection.value) : collection.js;
+    return String(collection);
+}
+/**
+ * A transform node publishes a COLLECTION — always.
+ *
+ * All four transform definitions declare `output: {type: 'object', description:
+ * 'The transformed data result'}`, which makes the designer type
+ * `out('<step>')` as `Record<string, any>` and reject mapping it into an
+ * `array` flow output — the same defect as the script node's, one node type
+ * over, and it hits five of the shipped examples.
+ *
+ * Unlike a script this needs no inference and no author declaration, because it
+ * is not a property of the particular node: `filter` and `map` are array→array,
+ * and `group-by` is too — the engine's own implementation says so in as many
+ * words (`transform-operations.ts`: "Always return an array", returning
+ * `Array.from(groups.entries()).map(…)` rather than an object keyed by group).
+ * So the type is knowable from the node TYPE alone, and is simply written down.
+ */
+function transformOutputs(base) {
+    // An unrecognized `variant` resolves to no definition at all, so there are no
+    // outputs to refine — and `jsonClone(undefined)` throws ("undefined" is not valid
+    // JSON) rather than passing the node through.
+    if (!base || typeof base !== 'object')
+        return base;
+    const out = jsonClone(base);
+    if (out.output)
+        out.output.type = 'array';
+    return out;
+}
+// ─── The lift ──────────────────────────────────────────────────────────────────
+/**
+ * A Transform node back as its spec: `collection` as the bare path the
+ * serializer writes (an Expr; absent when the node has none), and each operation
+ * from its `{ id, type, config }` descriptor. Values stay as the file has them —
+ * the printer decides what to write, exactly as the decompiler always did.
+ */
+function liftTransform(node, variant, ctx) {
+    const inputs = node.inputs ?? {};
+    const raw = ctx.sourceText(inputs.collection);
+    const ops = Array.isArray(inputs.operations) ? inputs.operations : [];
+    const operations = ops.map((op) => {
+        const cfg = op?.config ?? {};
+        if (op?.type === 'filter') {
+            return { type: 'filter', operation: cfg.operation, filters: (cfg.filters ?? []).map((f) => ({ field: f.field, condition: f.condition, ...(f.value !== undefined ? { value: f.value } : {}) })) };
+        }
+        if (op?.type === 'map') {
+            return { type: 'map', keepOriginalFields: cfg.keepOriginalFields, mappings: (cfg.mappings ?? []).map((m) => ({ field: m.field, transformation: m.transformation, renameTo: m.renameTo })) };
+        }
+        // Anything else prints as a groupBy, as the decompiler always read it.
+        return { type: 'groupBy', groupByField: cfg.groupByField, aggregations: (cfg.aggregations ?? []).map((a) => ({ operation: a.operation, alias: a.alias, field: a.field })) };
+    });
+    return {
+        kind: 'transform',
+        inputs: {
+            collection: (raw !== undefined ? new Expr(wireExprBody(raw)) : undefined),
+            ...(variant ? { variant } : {}),
+            operations: operations,
+        },
+    };
+}
+/** `{ k: v, … }` from entries (the decompiler's `objLit`): `''` when there are none. */
+function obj(entries, ctx) {
+    return entries.length === 0 ? '' : `{ ${entries.map(([k, v]) => `${ctx.key(k)}: ${v}`).join(', ')} }`;
+}
+/** The spec as `transform({ collection, variant?, operations })`, as the decompiler wrote it. */
+function printTransform({ inputs }, ctx) {
+    const s = (v) => ctx.string(v);
+    const opSrcs = (inputs.operations ?? []).map((op) => {
+        if (op.type === 'filter') {
+            const filters = (op.filters ?? []).map((f) => obj([
+                ['field', s(f.field)],
+                ['condition', s(f.condition)],
+                ...(f.value !== undefined ? [['value', s(f.value)]] : []),
+            ], ctx));
+            return obj([
+                ['type', s('filter')],
+                ...(op.operation !== undefined ? [['operation', s(op.operation)]] : []),
+                ['filters', `[${filters.join(', ')}]`],
+            ], ctx);
+        }
+        if (op.type === 'map') {
+            const mappings = (op.mappings ?? []).map((m) => obj([
+                ['field', s(m.field)],
+                ...(m.transformation && m.transformation !== 'copy' ? [['transformation', s(m.transformation)]] : []),
+                ...(m.renameTo ? [['renameTo', s(m.renameTo)]] : []),
+            ], ctx));
+            return obj([
+                ['type', s('map')],
+                ...(op.keepOriginalFields ? [['keepOriginalFields', op.keepOriginalFields ? 'true' : 'false']] : []),
+                ['mappings', `[${mappings.join(', ')}]`],
+            ], ctx);
+        }
+        const aggs = (op.aggregations ?? []).map((a) => obj([
+            ['operation', s(a.operation)],
+            ['alias', s(a.alias)],
+            ...(a.field ? [['field', s(a.field)]] : []),
+        ], ctx));
+        return obj([
+            ['type', s('groupBy')],
+            ['groupByField', s(op.groupByField)],
+            ['aggregations', `[${aggs.join(', ')}]`],
+        ], ctx);
+    });
+    const collection = inputs.collection !== undefined ? ctx.value(inputs.collection) : `${ctx.helper('lit')}([])`;
+    return {
+        factory: 'transform',
+        options: [
+            ['collection', collection],
+            ['variant', inputs.variant ? s(inputs.variant) : undefined],
+            ['operations', `[${opSrcs.join(', ')}]`],
+        ],
+    };
+}
+// ─── The four node types ───────────────────────────────────────────────────────
+const VARIANTS = Object.keys(VARIANT_OPERATION);
+function transformAt(typeName, variant, version, factory) {
+    return {
+        kind: 'transform', typeName, version, factory: 'transform', definition: 'bundled',
+        rawNode: { factory },
+        serialize: ({ inputs }, ctx) => {
+            // Only the generic type matches an UNKNOWN variant, so check reports it
+            // (TRANSFORM_VARIANT_UNKNOWN). A compile that skipped check refuses here
+            // rather than emit the generic node, which would run and be the wrong node.
+            if (variant === undefined && inputs?.variant !== undefined && inputs.variant !== null) {
+                throw new Error(`transform step "${ctx.step}": variant ${JSON.stringify(inputs.variant)} is not a Transform node type `
+                    + `(${VARIANTS.join(', ')}), so there is no node to emit. Fix the variant, or omit it for the generic Transform.`);
+            }
+            const base = ctx.definition(typeName, version)?.outputDefinition;
+            const typed = transformOutputs(base);
+            return { inputs: transformInputs(inputs, ctx), ...(typed !== base ? { outputs: typed } : {}) };
+        },
+        deserialize: (node, ctx) => liftTransform(node, variant, ctx),
+        print: printTransform,
+        check: ({ inputs }, ctx) => checkTransform(inputs, ctx),
+        // The only expression a transform carries is its collection; everything else
+        // is a literal or a field name (see checkTransform).
+        expressions: ({ inputs }) => [{ value: inputs.collection }],
+        output: () => ({ kind: 'opaque' }),
+    };
+}
+function transformType(typeName, variant, factory) {
+    return {
+        kind: 'transform', typeName, factory: 'transform', defaultVersion: '1.0.0',
+        versions: { '1.0.0': transformAt(typeName, variant, '1.0.0', factory), '1.1': transformAt(typeName, variant, '1.1', factory) },
+        // The generic type is the one for any spec without a KNOWN variant — an unknown
+        // one included, so check still reports it (see serialize above).
+        matches: ({ inputs }) => (variant === undefined
+            ? !VARIANTS.includes(inputs?.variant)
+            : inputs?.variant === variant),
+    };
+}
+export const transformNodeTypes = [
+    transformType('core.action.transform', undefined, 'transform()'),
+    transformType('core.action.transform.filter', 'filter', "transform({ variant: 'filter' })"),
+    transformType('core.action.transform.map', 'map', "transform({ variant: 'map' })"),
+    transformType('core.action.transform.group-by', 'group-by', "transform({ variant: 'group-by' })"),
+];

package/dist/nodes/transform/flow/spec.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The Transform family's authoring types (`core.action.transform` and its
+ * `.filter`, `.map`, `.group-by` variants), and its kind's entry in
+ * `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md.
+ */
+import type { Expr } from '../../../core/expr.js';
+/** How a filter combines its rules: every rule must match, or any one. */
+export type FilterMatch = 'and' | 'or';
+/** Comparison a filter rule applies to a field. */
+export type FilterCondition = 'equals' | 'not_equals' | 'greater_than' | 'less_than' | 'greater_equal' | 'less_equal' | 'contains' | 'not_contains' | 'starts_with' | 'not_starts_with' | 'ends_with' | 'not_ends_with' | 'matches_regex' | 'in' | 'not_in' | 'is_null' | 'is_not_null' | 'is_empty' | 'is_not_empty';
+export interface FilterRule {
+    /** Field on each item. Dot-paths reach nested fields (`'order.amount'`). */
+    field: string;
+    condition: FilterCondition;
+    /**
+     * What to compare against — a LITERAL only. The transform runtime reads this
+     * value as-is and evaluates nothing, so an expression here would compare every
+     * item against that text and match nothing. Hence `Expr` is not accepted: for
+     * a dynamic threshold, filter in a `script` step instead.
+     * Omit for the value-free conditions (`is_null`, `is_empty`, …).
+     */
+    value?: string | number | boolean | null;
+}
+/** What a map does to a field's value. Only `copy` is meaningful for non-text. */
+export type Transformation = 'copy' | 'uppercase' | 'lowercase' | 'trim';
+export interface FieldMapping {
+    /** Field to carry into the output. Must exist on the item, or it is skipped. */
+    field: string;
+    /** Defaults to `'copy'` (the value unchanged). */
+    transformation?: Transformation;
+    /** Output field name. Omit to keep `field`'s own name. */
+    renameTo?: string;
+}
+export type AggregationOperation = 'count' | 'sum' | 'average' | 'min' | 'max' | 'first' | 'last' | 'collect';
+export interface Aggregation {
+    operation: AggregationOperation;
+    /** Output field name for the aggregate. Required. */
+    alias: string;
+    /** Field to aggregate. Required for every operation except `count`. */
+    field?: string;
+}
+/**
+ * One link in the chain. Operations run in the order given, and each one's
+ * result is the next one's input — so a `map` that drops a field puts it out of
+ * reach of a later `filter`.
+ */
+export type TransformOperation = {
+    type: 'filter';
+    filters: FilterRule[];
+    operation?: FilterMatch;
+} | {
+    type: 'map';
+    mappings: FieldMapping[];
+    keepOriginalFields?: boolean;
+} | {
+    type: 'groupBy';
+    groupByField: string;
+    aggregations?: Aggregation[];
+};
+/**
+ * Which Transform node type to emit.
+ *
+ * @remarks
+ * The platform ships four: the generic `core.action.transform`, which chains N
+ * operations, plus three single-purpose variants that each run exactly one.
+ * They share ONE runtime — flow-v1 routes all four node types through the same
+ * script generators and dispatches on the OPERATION's `type`, never the node's
+ * (`bpmn-to-xml.ts`'s `DATA_TRANSFORM_NODE_TYPES` / `generateDataTransformScript`).
+ * So a variant is the generic constrained to one operation, wearing a
+ * self-describing node type and its own editor in the designer.
+ *
+ * Note the spelling: the node type is `core.action.transform.group-by`
+ * (hyphen), while the operation it carries is `type: 'groupBy'` (camelCase) —
+ * that mismatch is the platform's, not ours.
+ */
+export type TransformVariant = 'map' | 'filter' | 'group-by';
+/**
+ * The operation `type` each variant node must carry — one of, and only.
+ *
+ * @internal Serializer plumbing; an author states the variant, not the mapping.
+ */
+export declare const VARIANT_OPERATION: Record<TransformVariant, TransformOperation['type']>;
+export interface TransformInputs {
+    /**
+     * The array to transform, as a REFERENCE: `v('catalog')` or
+     * `out('fetchOrders', 'body.items')`.
+     *
+     * This is a variable PATH, not a value field — the runtime turns the string
+     * into a lookup. An inline array or a computed `js` expression therefore
+     * resolves to nothing, which is why the type is `Expr` and `check` rejects
+     * anything that is not a bare `$vars.…` path. Keep static data in a
+     * `.var(name, types.array, [...])` default and point here.
+     */
+    collection: Expr;
+    /**
+     * Emit a single-purpose variant node instead of the generic Transform.
+     * Omit it for the generic (the default).
+     *
+     * With a variant, `operations` must hold exactly ONE operation of the
+     * matching type — `'filter'` → `type: 'filter'`, `'map'` → `type: 'map'`,
+     * `'group-by'` → `type: 'groupBy'`. `check` rejects anything else, naming
+     * both the variant and the operation it found.
+     */
+    variant?: TransformVariant;
+    /** At least one operation — an empty chain is a no-op node. */
+    operations: TransformOperation[];
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link transform} builds. */
+        transform: {
+            inputs: TransformInputs;
+        };
+    }
+}

package/dist/nodes/transform/flow/spec.js

@@ -0,0 +1,10 @@
+/**
+ * The operation `type` each variant node must carry — one of, and only.
+ *
+ * @internal Serializer plumbing; an author states the variant, not the mapping.
+ */
+export const VARIANT_OPERATION = {
+    map: 'map',
+    filter: 'filter',
+    'group-by': 'groupBy',
+};

package/dist/raw-node-advice.d.ts

@@ -0,0 +1,16 @@
+import type { FlowNodeType } from './flow-node-type.js';
+/**
+ * The registered node type a raw node of `nodeType@version` is, at that version
+ * when it is registered and at the default otherwise (a raw node is often how an
+ * author reaches an unregistered version); undefined for an unregistered type.
+ */
+export declare function registeredRawType(nodeType: unknown, version: string): {
+    impl: FlowNodeType<unknown>;
+} | undefined;
+/** An input a registered node type never reads, as RAW_NODE_UNKNOWN_INPUT reports it; undefined otherwise. */
+export declare function rawNodeInputProblem(nodeType: unknown, version: string, inputs: unknown): {
+    severity: 'error' | 'warning';
+    message: string;
+} | undefined;
+/** RAW_NODE_TYPED_FAMILY for a raw node of a type with a typed factory — registered, or not yet ported. */
+export declare function rawNodeTypedFamilyWarning(nodeType: string): string | undefined;

package/dist/raw-node-advice.js

@@ -0,0 +1,36 @@
+/**
+ * What `rawNode` and the serializer ask about a raw node: whether its type is
+ * registered, an input that type never reads, and the typed factory to prefer.
+ * Internal — kept apart from raw-node.ts so the package entry, which re-exports
+ * that module, exports only `rawNode` itself.
+ */
+import { typedFactoryWarning, typedFamilyRawNodeWarning as tableWarning } from './core/typed-raw-node.js';
+import { hasBundledDefinition } from './flow-definitions.js';
+import { FLOW_NODE_TYPES } from './flow-node-registry.js';
+/**
+ * The registered node type a raw node of `nodeType@version` is, at that version
+ * when it is registered and at the default otherwise (a raw node is often how an
+ * author reaches an unregistered version); undefined for an unregistered type.
+ */
+export function registeredRawType(nodeType, version) {
+    const entry = typeof nodeType === 'string' ? FLOW_NODE_TYPES.byTypeName(nodeType) : undefined;
+    if (!entry)
+        return undefined;
+    const registered = Object.hasOwn(entry.type.versions, version);
+    const impl = (registered ? entry.type.versions[version] : entry.type.versions[entry.type.defaultVersion]);
+    return { impl };
+}
+/** An input a registered node type never reads, as RAW_NODE_UNKNOWN_INPUT reports it; undefined otherwise. */
+export function rawNodeInputProblem(nodeType, version, inputs) {
+    const found = registeredRawType(nodeType, version);
+    // `bundled` is the bundle's answer, not the registry's: a version the SDK ships
+    // but no node type lists yet still has a known key set (and an error).
+    return found?.impl.rawNode?.inputProblem?.(inputs, version, hasBundledDefinition(nodeType, version));
+}
+/** RAW_NODE_TYPED_FAMILY for a raw node of a type with a typed factory — registered, or not yet ported. */
+export function rawNodeTypedFamilyWarning(nodeType) {
+    const advice = registeredRawType(nodeType, '')?.impl.rawNode;
+    if (advice)
+        return typedFactoryWarning(nodeType, advice.factory, advice.hint);
+    return tableWarning(nodeType);
+}

package/dist/raw-node.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `rawNode` — place a node this SDK has no factory for, carrying its definition
+ * verbatim. Moved from core/node-classes.ts in Phase 3 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md so its diagnostics can ask the node-type
+ * registry what a registered type says about a raw node of it; the package entry
+ * re-exports it, so authors import it exactly as before.
+ */
+import { FlowAction } from './core/node-classes.js';
+/**
+ * Place a node this SDK has no factory for, carrying its definition verbatim
+ * (`uipath.exotic.thing@2.1` and the manifest the platform served for it).
+ *
+ * @remarks
+ * This is the escape hatch the coverage plan requires: an unknown registry
+ * definition is expressible without bypassing serializer invariants. The
+ * serializer still owns the node's id, label, `typeVersion` and edge wiring; you
+ * supply which definition and which inputs, exactly as a hand-written
+ * {@link FlowAction} subclass would.
+ *
+ * It is also what `decompile` emits for a node type it cannot name, so a
+ * round trip preserves the node's TYPE and VERSION instead of degrading it to a
+ * placeholder:
+ *
+ * ```ts
+ * .step('exotic', rawNode({
+ *   nodeType: 'uipath.exotic.thing',
+ *   version: '2.1',
+ *   manifest: exoticManifest,      // exactly what `registry get` returned
+ *   inputs: { where: input('scope') },
+ * }))
+ * ```
+ *
+ * `manifest` must be a real definition — an exact copy of what the registry or
+ * Workbench serves for that `nodeType@version`. It is not permission to invent
+ * one: the platform resolves the node against its own catalog at run time, so a
+ * hand-written manifest validates locally and fails on the tenant.
+ *
+ * Prefer a typed factory when one exists — it carries the family's checks, its
+ * defaults, and its output contract, none of which a raw node can know.
+ *
+ * **Never for a connector.** A `uipath.connector.*` node type is refused by
+ * `check` and `compile`: a raw node carries the author's inputs verbatim, so the
+ * emitted node has no `inputs.detail` and no connection binding — `validate`
+ * only warns ("Connector is not configured") and the run can never reach
+ * Integration Service. Use {@link connector}, and `registry prepare` when
+ * 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(...)`.
+ */
+export declare function rawNode(spec: {
+    /** The definition's `nodeType`, verbatim. */
+    nodeType: string;
+    /** The exact definition version; also becomes the node's `typeVersion`. */
+    version: string;
+    /** The complete node manifest, exactly as the platform serves it. */
+    manifest: unknown;
+    /** The node's `inputs`. `Expr` values render through the usual pipeline. */
+    inputs?: Record<string, unknown>;
+    /** Overrides for the node's `outputs`; rarely needed. */
+    outputs?: Record<string, unknown>;
+}): FlowAction;

package/dist/raw-node.js

@@ -0,0 +1,116 @@
+/**
+ * `rawNode` — place a node this SDK has no factory for, carrying its definition
+ * verbatim. Moved from core/node-classes.ts in Phase 3 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md so its diagnostics can ask the node-type
+ * registry what a registered type says about a raw node of it; the package entry
+ * re-exports it, so authors import it exactly as before.
+ */
+import { FlowAction, } from './core/node-classes.js';
+import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
+import { rawNodeInputProblem, rawNodeTypedFamilyWarning } from './raw-node-advice.js';
+/**
+ * Place a node this SDK has no factory for, carrying its definition verbatim
+ * (`uipath.exotic.thing@2.1` and the manifest the platform served for it).
+ *
+ * @remarks
+ * This is the escape hatch the coverage plan requires: an unknown registry
+ * definition is expressible without bypassing serializer invariants. The
+ * serializer still owns the node's id, label, `typeVersion` and edge wiring; you
+ * supply which definition and which inputs, exactly as a hand-written
+ * {@link FlowAction} subclass would.
+ *
+ * It is also what `decompile` emits for a node type it cannot name, so a
+ * round trip preserves the node's TYPE and VERSION instead of degrading it to a
+ * placeholder:
+ *
+ * ```ts
+ * .step('exotic', rawNode({
+ *   nodeType: 'uipath.exotic.thing',
+ *   version: '2.1',
+ *   manifest: exoticManifest,      // exactly what `registry get` returned
+ *   inputs: { where: input('scope') },
+ * }))
+ * ```
+ *
+ * `manifest` must be a real definition — an exact copy of what the registry or
+ * Workbench serves for that `nodeType@version`. It is not permission to invent
+ * one: the platform resolves the node against its own catalog at run time, so a
+ * hand-written manifest validates locally and fails on the tenant.
+ *
+ * Prefer a typed factory when one exists — it carries the family's checks, its
+ * defaults, and its output contract, none of which a raw node can know.
+ *
+ * **Never for a connector.** A `uipath.connector.*` node type is refused by
+ * `check` and `compile`: a raw node carries the author's inputs verbatim, so the
+ * emitted node has no `inputs.detail` and no connection binding — `validate`
+ * only warns ("Connector is not configured") and the run can never reach
+ * Integration Service. Use {@link connector}, and `registry prepare` when
+ * 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(...)`.
+ */
+export function rawNode(spec) {
+    return new RawNode(spec);
+}
+/** The {@link rawNode} implementation — a snapshot-backed contribution. */
+class RawNode extends FlowAction {
+    spec;
+    constructor(spec) {
+        super();
+        this.spec = spec;
+    }
+    /**
+     * `check` surfaces the connector refusal as an error, a typed family as a
+     * warning, and an input a registered node type 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);
+        if (refusal)
+            return [{ code: 'RAW_NODE_CONNECTOR', severity: 'error', message: refusal }];
+        const out = [];
+        const unknown = rawNodeInputProblem(this.spec.nodeType, this.spec.version, this.spec.inputs);
+        if (unknown)
+            out.push({ code: 'RAW_NODE_UNKNOWN_INPUT', ...unknown });
+        const typed = rawNodeTypedFamilyWarning(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. (An input a registered node
+        // type never reads is refused by the serializer, for every contribution.)
+        const refusal = connectorRawNodeRefusal(this.spec.nodeType);
+        if (refusal)
+            throw new Error(refusal);
+        const version = context.requestedVersion ?? this.spec.version;
+        if (context.requestedVersion !== undefined && context.requestedVersion !== this.spec.version) {
+            // Versions are exact everywhere in this SDK: a contributor may not
+            // substitute its own for an explicit request (design §2.6).
+            throw new Error(`rawNode("${this.spec.nodeType}") carries version ${this.spec.version}, but the step requests `
+                + `${context.requestedVersion}. Pass the manifest for the requested version, or drop { version }.`);
+        }
+        return {
+            definition: {
+                source: 'snapshot',
+                nodeType: this.spec.nodeType,
+                version,
+                manifest: this.spec.manifest,
+            },
+            ...(this.spec.inputs !== undefined ? { inputs: this.spec.inputs } : {}),
+            ...(this.spec.outputs !== undefined ? { outputs: this.spec.outputs } : {}),
+        };
+    }
+}

package/dist/registry/uip/pipeline-front-door.js

@@ -20,7 +20,9 @@
  *      folder and every folder above it, then `PATH`.
  *
  * The block brings its own imports, `existsSync` among them, and defines
- * `run(verb, args)`; the pipeline body uses both. Nothing in it names a path on
+ * `frontDoor` (`{ via: 'uip' | 'sdk', file, prefix }`) and `run(verb, args)`;
+ * the pipeline body uses them. `via` says which door won, because on Windows
+ * `file` is node.exe or a full path, never the bare name. Nothing in it names a path on
  * the machine that generated it, so a pipeline stays relocatable.
  *
  * Example, for `kind = 'flow'` on a machine whose `uip` has the commands:
@@ -61,7 +63,7 @@ function uipFrontDoor() {
     return undefined; // a uip shim that cannot be read: use the SDK instead
   }
   const probe = spawnSync(uip.file, [...uip.args, 'maestro', KIND, 'compile', '--help'], { stdio: 'ignore' });
-  return !probe.error && probe.status === 0 ? { file: uip.file, prefix: [...uip.args, 'maestro', KIND] } : undefined;
+  return !probe.error && probe.status === 0 ? { via: 'uip', file: uip.file, prefix: [...uip.args, 'maestro', KIND] } : undefined;
 }
 
 // 2. The SDK's flow-sdk bin, where \`npx --no-install flow-sdk\` looked for it.
@@ -78,7 +80,7 @@ function sdkFrontDoor() {
     const local = bins.map((bin) => join(bin, 'flow-sdk')).find((p) => existsSync(p));
     sdk = { file: local ?? 'flow-sdk', args: [] };
   }
-  return { file: sdk.file, prefix: [...sdk.args, KIND] };
+  return { via: 'sdk', file: sdk.file, prefix: [...sdk.args, KIND] };
 }
 
 const frontDoor = uipFrontDoor() ?? sdkFrontDoor();