@uipath/maestro-builder-sdk 6.25.1 → 6.27.0

package/dist/decompile.js

@@ -83,6 +83,13 @@ let runDefs = new Map();
  * agent that has to edit the file next.
  */
 let runRawManifests = [];
+/**
+ * The file's definitions for pinned pairs this SDK cannot resolve, by
+ * `<type>@<version>` → hoisted const name (#1128). Emitted once, in
+ * `.definitions([...])`, so compile resolves the pin against the file's own
+ * definition and the node keeps its version even when the author edits it.
+ */
+let runCarried = new Map();
 let runStrict = false;
 /** `DecompileOptions.warn` for the current run, and the messages already sent to it (one line per finding). */
 let runWarn;
@@ -131,22 +138,21 @@ function verClause(node) {
                 + `the file's definitions[] disagrees with the instance.`);
         }
     }
-    // A pin the SDK cannot resolve: `serialize` resolves an explicit { version }
-    // exactly (design §2.6) — a registered type against its registered versions,
-    // any other type against the bundle. Keeping that pin would emit source
-    // `compile` refuses (#1128: quick-form@1.6 from `node add`, @1.4 from
-    // `migrate`, script@1.0 from a pre-migrate file), so the source omits it: the
-    // node compiles at the SDK's default, and `merge --baseline` keeps the
-    // UNTOUCHED original node, with its own version and definition, verbatim
-    // (`nodeUnchanged` ignores typeVersion). Interim: a node the author EDITS is
-    // re-emitted at the default — the root fix is for compile to accept the
-    // definition the file carries.
+    // A pin the SDK cannot resolve (design §2.6: exact, against the registered
+    // or bundled versions) is kept when the file carries that pair's definition:
+    // `.definitions([...])` hands it to compile (#1128). With no definition to
+    // carry, keeping the pin would emit source `compile` refuses, so the source
+    // omits it: the node compiles at the SDK's default, and `merge --baseline`
+    // keeps the UNTOUCHED original node verbatim (`nodeUnchanged` ignores
+    // typeVersion).
     //
     // A type with no SDK-known version at all (a connector, a published-resource
     // `uipath.core.*` node, a rawNode) resolves its version elsewhere, so its pin
     // is kept.
+    if (runCarried.has(`${node.type}@${tv}`))
+        return `version: ${tsLiteral(tv)}`;
     const registered = FLOW_NODE_TYPES.byTypeName(node.type);
-    const shipped = registered ? Object.keys(registered.type.versions) : bundledVersions(node.type);
+    const shipped = shippedVersions(node.type);
     if (shipped.length > 0 && !shipped.includes(tv)) {
         const known = `${node.type}@${shipped.join(', ')}`;
         if (runStrict) {
@@ -161,6 +167,15 @@ function verClause(node) {
     }
     return `version: ${tsLiteral(tv)}`;
 }
+/**
+ * The versions this SDK resolves a `{ version }` of `type` against: a
+ * registered type's registered versions, any other type's bundled ones; `[]`
+ * for a type it ships at no version (a connector, a published resource).
+ */
+function shippedVersions(type) {
+    const registered = FLOW_NODE_TYPES.byTypeName(type);
+    return registered ? Object.keys(registered.type.versions) : bundledVersions(type);
+}
 function verArg(node) {
     const clause = verClause(node);
     return clause ? `, { ${clause} }` : '';
@@ -1494,6 +1509,92 @@ function unsupportedSpec(node, imp, o) {
     // is a safe structural stand-in, and the marker records what it replaced.
     return `${imp.use('mock')}() /* TODO: unsupported node type ${commentText(node.type)} */`;
 }
+/**
+ * Every pinned `<type>@<version>` in the file (root and subflows) that this SDK
+ * cannot resolve, for a type it ships at some version, and that the file's
+ * `definitions[]` holds — mapped to the const name decompile hoists the
+ * definition under. For instance a quick-form node at 1.6 maps
+ * `uipath.human-in-the-loop.quick-form@1.6` → `quickFormV1_6Definition`.
+ */
+function carriedPairs(flow) {
+    const out = new Map();
+    const taken = new Set();
+    const scopes = [flow.nodes ?? [], ...Object.values(flow.subflows ?? {}).map((sf) => sf?.nodes ?? [])];
+    for (const n of scopes.flat()) {
+        const key = `${n.type}@${n.typeVersion}`;
+        if (!n.typeVersion || out.has(key) || !runDefs.has(key))
+            continue;
+        const shipped = shippedVersions(n.type);
+        if (shipped.length === 0 || shipped.includes(n.typeVersion))
+            continue;
+        const base = `${camel(String(n.type).split('.').pop() ?? 'node')}V${String(n.typeVersion).replace(/[^A-Za-z0-9]+/g, '_')}Definition`;
+        let name = base;
+        for (let i = 2; taken.has(name); i++)
+            name = `${base}${i}`;
+        taken.add(name);
+        out.set(key, name);
+        warnCarriedInputDrift(n, runDefs.get(key));
+    }
+    return out;
+}
+/**
+ * The input names a definition declares: its `inputDefaults` keys and the
+ * top-level `inputs.<name>` its form fields edit. For instance quick-form@1.1
+ * gives `recipient, schema`.
+ */
+function definitionInputNames(def) {
+    const names = new Set(Object.keys(def?.inputDefaults ?? {}));
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            v.forEach(visit);
+            return;
+        }
+        if (!v || typeof v !== 'object')
+            return;
+        const field = v.name;
+        if (typeof field === 'string' && field.startsWith('inputs.'))
+            names.add(field.slice('inputs.'.length).split(/[.[]/)[0]);
+        for (const child of Object.values(v))
+            visit(child);
+    };
+    visit(def?.form);
+    return [...names].sort();
+}
+/** Compare two dotted versions numerically: `1.10` sorts after `1.9`. */
+function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * Warn when a carried definition's inputs differ from the nearest version the
+ * SDK ships (the highest one below the carried version, else the lowest). An
+ * edited node keeps the file's pin, but its inputs are rebuilt in the SDK's
+ * shape, so a renamed input would be written under the wrong name. For
+ * instance `node "review1" keeps quick-form@1.6 ...; its inputs differ from
+ * 1.1 (assignee)`.
+ */
+function warnCarriedInputDrift(node, carried) {
+    const versions = shippedVersions(node.type).filter((v) => BUNDLED_DEFINITIONS[`${node.type}@${v}`]).sort(compareVersions);
+    const below = versions.filter((v) => compareVersions(v, String(node.typeVersion)) < 0);
+    const nearest = below.length > 0 ? below[below.length - 1] : versions[0];
+    if (nearest === undefined)
+        return;
+    const shipped = BUNDLED_DEFINITIONS[`${node.type}@${nearest}`];
+    const factoryVersion = nearest;
+    const a = definitionInputNames(carried);
+    const b = definitionInputNames(shipped);
+    const differ = [...a.filter((x) => !b.includes(x)), ...b.filter((x) => !a.includes(x))].sort();
+    if (differ.length === 0)
+        return;
+    warnOnce(`node ${tsLiteral(node.id)} keeps ${node.type}@${node.typeVersion} from the file's definitions[]; its inputs differ from `
+        + `${factoryVersion} (${differ.join(', ')}), so an edit to it may need rawNode.`);
+}
 /** `some-node.id` → `someNodeId`, for a hoisted const name. */
 function camel(id) {
     const parts = String(id).split(/[^A-Za-z0-9]+/).filter(Boolean);
@@ -2528,6 +2629,11 @@ function parseSwitchCase(expr) {
  * expression is `<discriminant> === <JSON-literal>`; the discriminant (shared by
  * all cases) becomes `on`, and each RHS literal a case `value`. The case port is
  * `case-<caseId>`; the optional default arm is the `default` port.
+ *
+ * A switch whose cases do NOT share that shape — the product's per-case form,
+ * `amount > 100` / `amount <= 100`, first truthy case wins — decompiles to
+ * `when:` cases with `on` left `undefined`, so each condition round-trips
+ * as written (#1131).
  */
 function emitSwitch(node, ipdom, scope, ctx, stop, refInto) {
     const r = ipdom.get(node.id) ?? stop;
@@ -2535,70 +2641,55 @@ function emitSwitch(node, ipdom, scope, ctx, stop, refInto) {
     let caseIndex = 0;
     let disc;
     let nonUniform = false; // a case whose expr isn't `<disc> === <literal>`, or a differing discriminant
-    const caseSrcs = [];
-    for (const c of cases) {
-        const parsed = parseSwitchCase(String(c.expression ?? ''));
-        let value = '0';
-        let valueLiteral = '';
-        if (parsed) {
+    // First pass: is every case one shared `<disc> === <literal>`? If not, every
+    // case is emitted as `when:` with its expression as written.
+    const parsed = cases.map((c) => {
+        const p = parseSwitchCase(String(c.expression ?? ''));
+        if (p) {
             if (disc === undefined)
-                disc = parsed.lhs;
-            else if (disc !== parsed.lhs)
+                disc = p.lhs;
+            else if (disc !== p.lhs)
                 nonUniform = true;
-            valueLiteral = parsed.literal;
-            value = parsed.value;
         }
         else {
             nonUniform = true;
-            // Keep the best-effort output the TODO comment points at.
-            const m = String(c.expression ?? '').match(/^(.*?)\s*===?\s*(.*)$/);
-            if (m && m[1].trim() && disc === undefined)
-                disc = m[1].trim();
-            if (m) {
-                valueLiteral = m[2].trim();
-                try {
-                    value = tsLiteral(JSON.parse(valueLiteral));
-                }
-                catch {
-                    const q = valueLiteral.match(/^'(.*)'$/);
-                    value = q ? tsLiteral(q[1]) : tsLiteral(valueLiteral);
-                }
-            }
         }
+        return { c, p };
+    });
+    const caseSrcs = parsed.map(({ c, p }) => {
         const armSegs = forkRegion(portEdges(ctx.graph, node.id, `case-${c.id}`), r, scope, ipdom, ctx, refInto);
-        const defaultLabel = `Case ${valueLiteral}`;
+        caseIndex += 1;
+        const defaultLabel = nonUniform || !p ? `Case ${caseIndex}` : `Case ${p.literal}`;
         const labelPart = c.label && c.label !== defaultLabel ? `, label: ${tsLiteral(c.label)}` : '';
         // The file's case id comes back when it is not the positional one serialize
         // derives (a designer-drawn switch uses `default-1`, …), so the recompiled
         // edges leave from the ORIGINAL node's handles, which merge keeps (#1130).
-        caseIndex += 1;
         const idPart = typeof c.id === 'string' && c.id !== '' && c.id !== `case_${caseIndex}` ? `, id: ${tsLiteral(c.id)}` : '';
-        caseSrcs.push(`{ value: ${value}${labelPart}${idPart}, body: ${armCb('b', armSegs)} }`);
+        const head = nonUniform || !p
+            ? `when: ${emitBareExpr(String(c.expression ?? ''), ctx.imp, ctx.inputNames)}`
+            : `value: ${p.value}`;
+        return `{ ${head}${labelPart}${idPart}, body: ${armCb('b', armSegs)} }`;
+    });
+    // A case with no condition has no `when:` that compiles: emitting `js\`\``
+    // would fail at compile ([EXPR_SYNTAX]) with no warning here.
+    const empty = cases.filter((c) => String(c.expression ?? '').trim() === '');
+    if (empty.length > 0) {
+        const listing = empty.map((c) => tsLiteral(c.label ?? c.id)).join(', ');
+        const message = `switch ${tsLiteral(node.id)} has a case with no condition (${listing}). `
+            + '`.switch()` needs a condition on every case, so the decompiled `when:` is empty and recompiling fails. '
+            + 'Give the case a condition in the .flow, or edit this switch in the .flow JSON directly.';
+        if (runStrict)
+            throw new Error(`decompile: ${message}`);
+        warnOnce(message);
     }
-    const on = emitBareExpr(disc ?? '', ctx.imp, ctx.inputNames);
+    const on = nonUniform ? 'undefined' : emitBareExpr(disc ?? '', ctx.imp, ctx.inputNames);
     const hasDefault = (node.inputs ?? {}).hasDefault === true || portEdge(ctx.graph, node.id, 'default') !== undefined;
     const defArm = hasDefault
         ? `, ${armCb('d', forkRegion(portEdges(ctx.graph, node.id, 'default'), r, scope, ipdom, ctx, refInto))}`
         : '';
     const caseList = `[\n${caseSrcs.map((c) => reindent(c, '  ')).join(',\n')},\n]`;
-    // The builder's `.switch(on, [{value}])` models `on === value` only. A flow whose
-    // cases carry arbitrary per-case boolean expressions (or a non-uniform
-    // discriminant) cannot round-trip through it — flag it rather than emit silently
-    // wrong values.
-    if (nonUniform) {
-        const listing = cases.map((c) => `${tsLiteral(c.label ?? c.id)}: ${tsLiteral(String(c.expression ?? ''))}`).join(', ');
-        const message = `switch ${tsLiteral(node.id)} has per-case conditions that are not one shared \`<discriminant> === <value>\` `
-            + `(${listing}). \`.switch()\` models only that form, so the decompiled \`on\`/\`value\` are placeholders: `
-            + 'recompiling either fails or changes which case runs. Edit this switch in the .flow JSON directly.';
-        if (runStrict)
-            throw new Error(`decompile: ${message}`);
-        warnOnce(message);
-    }
-    const warn = nonUniform
-        ? `\n/* TODO: this switch's case expressions are not a uniform \`<discriminant> === <value>\`; the recovered on/value are best-effort and need review. */`
-        : '';
     const ver = verArg(node);
-    return `.switch(${tsLiteral(node.id)}, ${on}, ${caseList}${defArm}${ver && !defArm ? ', undefined' : ''}${ver})${warn}`;
+    return `.switch(${tsLiteral(node.id)}, ${on}, ${caseList}${defArm}${ver && !defArm ? ', undefined' : ''}${ver})`;
 }
 /**
  * Recover `.stickyNotes([...])` from the scope's `stickyNote` nodes.
@@ -2923,6 +3014,7 @@ export function decompile(flow, options = {}) {
         if (!runDefs.has(d.nodeType))
             runDefs.set(d.nodeType, d);
     }
+    runCarried = carriedPairs(flow);
     const imp = new Imports();
     const graph = new Graph(flow.nodes ?? [], flow.edges ?? []);
     const globals = readFlowGlobals(flow.variables, runStrict);
@@ -2956,6 +3048,8 @@ export function decompile(flow, options = {}) {
     if (typeof flow.description === 'string') {
         e.line(d, `.description(${tsLiteral(flow.description)})`);
     }
+    if (runCarried.size > 0)
+        e.line(d, `.definitions([${[...runCarried.values()].join(', ')}])`);
     // Trigger nodes. One root is the default: the isDefaultEntryPoint carrier
     // when the file marks one (a multi-root flow always does), else `start`.
     // A node's TYPE is not enough: `uipath.connector.event.<key>.<event>` is a
@@ -3042,7 +3136,8 @@ export function decompile(flow, options = {}) {
     const lay = layoutSeg(flow, (flow.nodes ?? []).filter((n) => !detachedIds.has(n.id)), (flow.edges ?? []).filter((edge) => !detachedIds.has(edge.sourceNodeId) && !detachedIds.has(edge.targetNodeId)));
     const layout = lay ? reindent(lay, '  ') : '';
     const chain = [header, eps, body, sticky, layout, '  .build();'].filter((s) => s.length > 0).join('\n');
-    const hoisted = runRawManifests
+    const carriedConsts = [...runCarried].map(([key, name]) => [name, JSON.stringify(runDefs.get(key), null, 2)]);
+    const hoisted = [...carriedConsts, ...runRawManifests]
         .map(([name, json]) => `const ${name} = ${json};`)
         .join('\n\n');
     return [imp.line(importSpecifier), hoisted, chain].filter((p) => p.length > 0).join('\n\n') + '\n';

package/dist/flow-expr-check.js

@@ -147,7 +147,12 @@ function walk(steps, roots, out) {
                 walk(s.otherwise, roots, out);
                 break;
             case 'switch': {
-                pushExpr(s.on, s.name, roots, out);
+                if (s.on)
+                    pushExpr(s.on, s.name, roots, out);
+                // A `when` case's condition is read like a branch condition (#1131).
+                for (const c of s.cases)
+                    if (c.when)
+                        pushExpr(c.when, s.name, roots, out);
                 // Inside a case (or default) body the discriminant is bound to
                 // `$vars.value`, so it is a valid root only there.
                 const caseRoots = new Set(roots).add('value');

package/dist/flow-node-type.d.ts

@@ -97,7 +97,12 @@ export interface FlowSerializeContext {
     bind(entry: {
         readonly id: string;
     } & Readonly<Record<string, unknown>>): void;
-    /** The bundled definition `<typeName>@<version>`, or undefined when the SDK does not ship it. */
+    /**
+     * The bundled definition `<typeName>@<version>`, else one the flow carries;
+     * undefined when neither exists. When the node is emitted at a carried
+     * version, asking for its own type answers with that carried definition at
+     * any `version`, so a type's defaults follow the file's definition.
+     */
     definition(typeName: string, version: string): unknown;
     /**
      * The flow's bindings so far, by id — read-only. For a type that SHARES a
@@ -186,8 +191,8 @@ export interface FlowCheckContext {
     /** The version the node will be emitted at. */
     readonly version: string;
     /**
-     * The SDK's bundled definition of this step's node type at `version` (the one
-     * serialize emits from), or undefined when the SDK does not ship it.
+     * The definition serialize emits this step from: the one the flow carries at
+     * a carried version, else the SDK's bundled one; undefined when neither exists.
      */
     definition(): unknown;
     /** Report a diagnostic on this step. Its severity is the family catalog's for `code`. */

package/dist/flow-sdk.d.ts

@@ -338,9 +338,33 @@ export declare function conversationTrigger(): TriggerSpec;
 export declare function voiceTrigger(): TriggerSpec;
 /** A value a `.switch` case compares the discriminant against. */
 export type CaseValue = string | number | boolean;
+/**
+ * One case of `.switch(name, on, cases)`: either `{ value }`, taken when
+ * `on === value`, or `{ when }`, taken when its own condition is true (the
+ * product switch's per-case form, #1131). Cases are tried top to bottom and the
+ * first match wins.
+ */
+export type SwitchCase = ({
+    value: CaseValue;
+    when?: undefined;
+} | {
+    when: Expr;
+    value?: undefined;
+}) & {
+    body: (b: ArmBuilder) => void;
+    label?: string;
+    id?: string;
+};
 /** One arm of a built `.switch` (the serializer's view: body already collected). */
 export interface SwitchArm {
-    value: CaseValue;
+    /** The value `on` is compared against (`on === value`). Absent on a `when` case. */
+    value?: CaseValue;
+    /**
+     * The case's own boolean condition, instead of `on === value` — the product
+     * switch stores one condition per case and takes the first that is true
+     * (#1131). Exactly one of `value` / `when`.
+     */
+    when?: Expr;
     label?: string;
     /**
      * The case's wire id — `inputs.cases[].id`, and the `case-<id>` port its arm
@@ -500,7 +524,7 @@ export type Step = {
     kind: 'switch';
     name: string;
     label?: string;
-    on: Expr;
+    on?: Expr;
     cases: SwitchArm[];
     default?: Step[];
     options?: NodeOptions;
@@ -731,6 +755,12 @@ export interface BuiltFlow {
     layout?: FlowLayout;
     /** Canvas sticky notes from `.stickyNotes()`. Inert annotations. */
     stickyNotes?: StickyNote[];
+    /**
+     * Node definitions the flow carries, from `.definitions()`: exact manifests a
+     * pinned `{ version }` resolves against when the SDK does not bundle that
+     * version.
+     */
+    definitions?: Record<string, unknown>[];
     /** Additional roots from `.entryPoint()`. The default root stays `.trigger()`/`.input()`. */
     entryPoints?: BuiltEntryPoint[];
     /**
@@ -978,23 +1008,30 @@ declare class StepList {
      * ], (other) => other.step('unknown', script({ code: 'return "Unknown";' })))
      * ```
      *
+     * @example
+     * **Cases with their own conditions** (`on` is `undefined`)
+     * ```ts
+     * .switch('route', undefined, [
+     *   { when: js`$vars.start.output.amount > 100`, label: 'High', body: (b) => b.step('review', script({ code: 'return 1;' })) },
+     *   { when: js`$vars.start.output.amount <= 100`, label: 'Low', body: (b) => b.step('auto', script({ code: 'return 2;' })) },
+     * ])
+     * ```
+     *
      * @param name - The switch node's id.
-     * @param on - The value to compare each case against.
-     * @param cases - One entry per arm, evaluated top to bottom; the first strict
-     * match wins. `label` names the arm's outgoing edge. `id` keeps a case's wire
-     * id (`inputs.cases[].id`, port `case-<id>`); omitted, it is `case_<n>`.
+     * @param on - The value to compare each `value` case against; `undefined`
+     * when every case carries its own `when` condition.
+     * @param cases - One entry per arm, evaluated top to bottom; the first match
+     * wins. A case is `{ value }` (strict `on === value`) or `{ when }` (its own
+     * boolean expression). `label` names the arm's outgoing edge. `id` keeps a
+     * case's wire id (`inputs.cases[].id`, port `case-<id>`); omitted, it is
+     * `case_<n>`.
      * @param defaultFn - Receives a sub-builder for the arm taken when nothing
      * matches. Omit it and an unmatched value simply continues.
      * @param options - Node options; `version` selects the exact definition
      * version (see {@link NodeOptions}).
      * @returns This builder, after every arm has rejoined.
      */
-    switch(name: string, on: Expr, cases: {
-        value: CaseValue;
-        body: (b: ArmBuilder) => void;
-        label?: string;
-        id?: string;
-    }[], defaultFn?: (b: StepList) => void, options?: NodeOptions): this;
+    switch(name: string, on: Expr | undefined, cases: SwitchCase[], defaultFn?: (b: StepList) => void, options?: NodeOptions): this;
     /**
      * Run two or more arms **in parallel** from this point and join them back
      * together on a Merge node — the one place the builder stops being a straight
@@ -1216,6 +1253,7 @@ declare class FlowBuilder extends StepList {
     private _stickyNotes?;
     private _version;
     private _schemaVersion?;
+    private _definitions;
     private _inputs;
     private _outputs;
     private _vars;
@@ -1423,6 +1461,47 @@ declare class FlowBuilder extends StepList {
      * @defaultValue `'1.9'` — `FLOW_FORMAT_PROFILE.version`, the fleet write floor.
      */
     schemaVersion(version: string): this;
+    /**
+     * Carry node definitions this SDK does not bundle, so a `{ version }` pin on
+     * one of those versions compiles.
+     *
+     * @remarks
+     * A pinned `{ version }` resolves exactly (design §2.6): first against the
+     * definitions the SDK was released with, then against the ones carried here.
+     * Nothing else changes — an unpinned node still takes the SDK's default, and
+     * a bundled version still compiles from the bundle.
+     *
+     * Its job is BROWNFIELD PRESERVATION. A `.flow` file holds the exact
+     * definition of every node it uses, but the registry moves faster than an SDK
+     * release: `uip maestro flow node add` writes
+     * `uipath.human-in-the-loop.quick-form@1.6` while this SDK bundles 1.0 and
+     * 1.1. `flow-decompile` copies the file's own entry into this call for each
+     * such pair, so the decompiled source compiles unedited and a node you edit
+     * keeps the file's version instead of moving to the SDK's.
+     *
+     * Each manifest must be an exact copy of one the platform served (from the
+     * file's `definitions[]`, or `uip maestro flow registry get`): it names its
+     * `nodeType` and `version`, and has a `display.label`. The SDK still emits
+     * the node's inputs from its own factory, so a version whose inputs differ
+     * from the SDK's shape needs `rawNode` instead.
+     *
+     * @example
+     * **Keep a quick-form task at the version the file pins**
+     * ```ts
+     * // The .flow file's whole definitions[] entry for quick-form@1.6 (or
+     * // `uip maestro flow registry get`), copied verbatim, as flow-decompile hoists it.
+     * // A stub with only nodeType/version/display passes validation but breaks the canvas.
+     * declare const quickFormV1_6Definition: Record<string, unknown>;
+     * flow('review')
+     *   .definitions([quickFormV1_6Definition])
+     *   .step('review', hitl({ variant: 'quick-form', fields: [], outcomes: ['Submit'] }), { version: '1.6' });
+     * ```
+     *
+     * @param manifests - Node manifests, each with its own `nodeType`, `version` and `display.label`.
+     * @returns This builder, so calls chain.
+     * @throws Error when a manifest is not a node manifest, or two differ for one `nodeType@version`.
+     */
+    definitions(manifests: readonly Record<string, unknown>[]): this;
     /**
      * Declare the flow's inputs. Read them with `input('<name>')`.
      *

package/dist/flow-sdk.js

@@ -45,6 +45,7 @@ import { builtinActionSpec, builtinTriggerSpec, subscriptionFrom } from './core/
 import { checkFlowExpressions, FlowBuildError } from './flow-expr-check.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { schemaVersionRefusal } from './schema-version.js';
+import { indexCarriedDefinitions } from './core/carried-definitions.js';
 export { FlowBuildError, checkFlowExpressions } from './flow-expr-check.js';
 const TYPE_NAMES = Object.values(types);
 /**
@@ -611,11 +612,23 @@ class StepList {
      * ], (other) => other.step('unknown', script({ code: 'return "Unknown";' })))
      * ```
      *
+     * @example
+     * **Cases with their own conditions** (`on` is `undefined`)
+     * ```ts
+     * .switch('route', undefined, [
+     *   { when: js`$vars.start.output.amount > 100`, label: 'High', body: (b) => b.step('review', script({ code: 'return 1;' })) },
+     *   { when: js`$vars.start.output.amount <= 100`, label: 'Low', body: (b) => b.step('auto', script({ code: 'return 2;' })) },
+     * ])
+     * ```
+     *
      * @param name - The switch node's id.
-     * @param on - The value to compare each case against.
-     * @param cases - One entry per arm, evaluated top to bottom; the first strict
-     * match wins. `label` names the arm's outgoing edge. `id` keeps a case's wire
-     * id (`inputs.cases[].id`, port `case-<id>`); omitted, it is `case_<n>`.
+     * @param on - The value to compare each `value` case against; `undefined`
+     * when every case carries its own `when` condition.
+     * @param cases - One entry per arm, evaluated top to bottom; the first match
+     * wins. A case is `{ value }` (strict `on === value`) or `{ when }` (its own
+     * boolean expression). `label` names the arm's outgoing edge. `id` keeps a
+     * case's wire id (`inputs.cases[].id`, port `case-<id>`); omitted, it is
+     * `case_<n>`.
      * @param defaultFn - Receives a sub-builder for the arm taken when nothing
      * matches. Omit it and an unmatched value simply continues.
      * @param options - Node options; `version` selects the exact definition
@@ -633,7 +646,14 @@ class StepList {
             // An arm's own `.label(...)` wins over the case config's `label`; either
             // overrides the serializer's derived `Case "<value>"`.
             const label = arm.armLabel ?? c.label;
-            return { value: c.value, ...(label !== undefined ? { label } : {}), ...(c.id !== undefined ? { id: c.id } : {}), body: arm.steps };
+            return {
+                // Both kept as given, so check can refuse a case with both or neither.
+                ...(c.value !== undefined ? { value: c.value } : {}),
+                ...(c.when !== undefined ? { when: toExpr(c.when) } : {}),
+                ...(label !== undefined ? { label } : {}),
+                ...(c.id !== undefined ? { id: c.id } : {}),
+                body: arm.steps,
+            };
         });
         let dflt;
         if (defaultFn) {
@@ -648,7 +668,7 @@ class StepList {
         this.steps.push({
             kind: 'switch',
             name,
-            on: toExpr(on),
+            ...(on !== undefined ? { on: toExpr(on) } : {}),
             cases: arms,
             ...(dflt !== undefined ? { default: dflt } : {}),
             ...(options ? { options } : {}),
@@ -881,6 +901,7 @@ class FlowBuilder extends StepList {
     _stickyNotes;
     _version = '1.0.0';
     _schemaVersion;
+    _definitions = [];
     _inputs = [];
     _outputs = [];
     _vars = [];
@@ -1144,6 +1165,52 @@ class FlowBuilder extends StepList {
         this._schemaVersion = version;
         return this;
     }
+    /**
+     * Carry node definitions this SDK does not bundle, so a `{ version }` pin on
+     * one of those versions compiles.
+     *
+     * @remarks
+     * A pinned `{ version }` resolves exactly (design §2.6): first against the
+     * definitions the SDK was released with, then against the ones carried here.
+     * Nothing else changes — an unpinned node still takes the SDK's default, and
+     * a bundled version still compiles from the bundle.
+     *
+     * Its job is BROWNFIELD PRESERVATION. A `.flow` file holds the exact
+     * definition of every node it uses, but the registry moves faster than an SDK
+     * release: `uip maestro flow node add` writes
+     * `uipath.human-in-the-loop.quick-form@1.6` while this SDK bundles 1.0 and
+     * 1.1. `flow-decompile` copies the file's own entry into this call for each
+     * such pair, so the decompiled source compiles unedited and a node you edit
+     * keeps the file's version instead of moving to the SDK's.
+     *
+     * Each manifest must be an exact copy of one the platform served (from the
+     * file's `definitions[]`, or `uip maestro flow registry get`): it names its
+     * `nodeType` and `version`, and has a `display.label`. The SDK still emits
+     * the node's inputs from its own factory, so a version whose inputs differ
+     * from the SDK's shape needs `rawNode` instead.
+     *
+     * @example
+     * **Keep a quick-form task at the version the file pins**
+     * ```ts
+     * // The .flow file's whole definitions[] entry for quick-form@1.6 (or
+     * // `uip maestro flow registry get`), copied verbatim, as flow-decompile hoists it.
+     * // A stub with only nodeType/version/display passes validation but breaks the canvas.
+     * declare const quickFormV1_6Definition: Record<string, unknown>;
+     * flow('review')
+     *   .definitions([quickFormV1_6Definition])
+     *   .step('review', hitl({ variant: 'quick-form', fields: [], outcomes: ['Submit'] }), { version: '1.6' });
+     * ```
+     *
+     * @param manifests - Node manifests, each with its own `nodeType`, `version` and `display.label`.
+     * @returns This builder, so calls chain.
+     * @throws Error when a manifest is not a node manifest, or two differ for one `nodeType@version`.
+     */
+    definitions(manifests) {
+        const known = indexCarriedDefinitions(this._definitions, 'definitions()');
+        indexCarriedDefinitions(manifests, 'definitions()', known);
+        this._definitions = [...known.values()];
+        return this;
+    }
     /**
      * Declare the flow's inputs. Read them with `input('<name>')`.
      *
@@ -1234,6 +1301,7 @@ class FlowBuilder extends StepList {
             ...(this._stickyNotes !== undefined ? { stickyNotes: this._stickyNotes } : {}),
             version: this._version,
             ...(this._schemaVersion !== undefined ? { schemaVersion: this._schemaVersion } : {}),
+            ...(this._definitions.length ? { definitions: this._definitions } : {}),
             inputs: this._inputs,
             outputs: this._outputs,
             vars: this._vars,

package/dist/merge.js

@@ -142,7 +142,8 @@ export function mergeFlow(original, edited, options = {}) {
             finalNodes.push(withOriginalLayout(jsonClone(e), orig, layoutNodesOf(original)));
             if (orig && orig.type === e.type && orig.typeVersion !== e.typeVersion) {
                 options.warn?.(`node ${JSON.stringify(e.id)} moved ${e.type}@${String(orig.typeVersion)} -> ${String(e.typeVersion)} `
-                    + `(the edited node takes the SDK's version; flow-builder-sdk#1167).`);
+                    + `(the edited source does not pin ${String(orig.typeVersion)}; keep the { version } pin, `
+                    + `with .definitions([...]) when the SDK does not bundle that version).`);
             }
         }
     }