@uipath/maestro-builder-sdk 6.25.0 → 6.26.0

package/dist/core/nodes/versioned.d.ts

@@ -48,3 +48,38 @@ export declare function asVersioned<Ctx extends ArtifactContexts>(t: AnyNodeType
  * node type's bug, not the author's, and throws as an internal SDK error.
  */
 export declare function resolveVersion<Spec, Ctx extends ArtifactContexts>(t: VersionedNodeType<Spec, unknown, Ctx>, spec: Spec, requested: string | undefined, where: string): NodeType<Spec, unknown, Ctx>;
+/**
+ * Looks up a definition the flow carries (`.definitions()`) for `typeName@version`.
+ * `versions`, when present, lists every version of `typeName` the flow carries,
+ * so a refusal can name them.
+ */
+export type CarriedDefinitionLookup = ((typeName: string, version: string) => Record<string, unknown> | undefined) & {
+    readonly versions?: (typeName: string) => readonly string[];
+};
+/** What {@link resolveVersionCarried} resolved: the implementation, the version to emit, and a carried definition when one answered. */
+export interface ResolvedNodeVersion<Impl> {
+    readonly impl: Impl;
+    /** The version the node is emitted at — `impl.version`, or the carried version. */
+    readonly version: string;
+    /** The definition the FLOW carries for `typeName@version`, when the registry has no implementation at that version. */
+    readonly carried?: Record<string, unknown>;
+}
+/**
+ * {@link resolveVersion} with the third definition source (#1128): a definition
+ * the flow CARRIES (`.definitions()`, decompile's copy of the file's own
+ * `definitions[]` entry).
+ *
+ * Order: a registered version resolves as before. An explicit version the type
+ * does not register, but the flow carries, is emitted AT that version with the
+ * carried definition, through the implementation the type would use unpinned
+ * (`select(spec)`, else the default) — the registry has no implementation of
+ * its own for it, and the node keeps the version the file pins instead of being
+ * refused. Anything else is refused as {@link resolveVersion} refuses it, except
+ * that an unregistered pin also names the versions the flow carries and the
+ * `.definitions()` remedy.
+ *
+ * For instance a file pinning `core.action.script@1.0` (registered: 1.0.0, 1.1)
+ * and carrying that definition emits the node at 1.0 through the default
+ * implementation.
+ */
+export declare function resolveVersionCarried<Spec, Ctx extends ArtifactContexts>(t: VersionedNodeType<Spec, unknown, Ctx>, spec: Spec, requested: string | undefined, where: string, carried: CarriedDefinitionLookup | undefined): ResolvedNodeVersion<NodeType<Spec, unknown, Ctx>>;

package/dist/core/nodes/versioned.js

@@ -44,3 +44,38 @@ export function resolveVersion(t, spec, requested, where) {
     }
     return impl;
 }
+/**
+ * {@link resolveVersion} with the third definition source (#1128): a definition
+ * the flow CARRIES (`.definitions()`, decompile's copy of the file's own
+ * `definitions[]` entry).
+ *
+ * Order: a registered version resolves as before. An explicit version the type
+ * does not register, but the flow carries, is emitted AT that version with the
+ * carried definition, through the implementation the type would use unpinned
+ * (`select(spec)`, else the default) — the registry has no implementation of
+ * its own for it, and the node keeps the version the file pins instead of being
+ * refused. Anything else is refused as {@link resolveVersion} refuses it, except
+ * that an unregistered pin also names the versions the flow carries and the
+ * `.definitions()` remedy.
+ *
+ * For instance a file pinning `core.action.script@1.0` (registered: 1.0.0, 1.1)
+ * and carrying that definition emits the node at 1.0 through the default
+ * implementation.
+ */
+export function resolveVersionCarried(t, spec, requested, where, carried) {
+    if (requested !== undefined && !ownEntry(t.versions, requested)) {
+        const def = carried?.(t.typeName, requested);
+        if (def !== undefined) {
+            return { impl: resolveVersion(t, spec, undefined, where), version: requested, carried: def };
+        }
+        // Refused: name both sources, and the way to add the second one.
+        const registered = Object.keys(t.versions).sort().join(', ');
+        const carriedVersions = [...(carried?.versions?.(t.typeName) ?? [])].sort();
+        throw new Error(`${where} requests ${t.typeName}@${requested}, but this SDK registers only ${registered}`
+            + (carriedVersions.length > 0 ? ` and the flow carries only ${carriedVersions.join(', ')}` : '')
+            + '. Versions are exact — omit { version } to use the default, request one listed here, or carry '
+            + "that version's definition (the .flow file's definitions[] entry) with .definitions([...]).");
+    }
+    const impl = resolveVersion(t, spec, requested, where);
+    return { impl, version: impl.version };
+}

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);
@@ -2923,6 +3024,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 +3058,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 +3146,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-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

@@ -731,6 +731,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[];
     /**
@@ -1216,6 +1222,7 @@ declare class FlowBuilder extends StepList {
     private _stickyNotes?;
     private _version;
     private _schemaVersion?;
+    private _definitions;
     private _inputs;
     private _outputs;
     private _vars;
@@ -1423,6 +1430,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);
 /**
@@ -881,6 +882,7 @@ class FlowBuilder extends StepList {
     _stickyNotes;
     _version = '1.0.0';
     _schemaVersion;
+    _definitions = [];
     _inputs = [];
     _outputs = [];
     _vars = [];
@@ -1144,6 +1146,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 +1282,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).`);
             }
         }
     }

package/dist/serialize.js

@@ -19,7 +19,8 @@ import { planContributionBindings } from './core/contribution-bindings.js';
 import { declaredErrorPortRefusal, definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
 import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { stepExits } from './flow-step-exits.js';
-import { resolveVersion } from './core/nodes/versioned.js';
+import { resolveVersionCarried } from './core/nodes/versioned.js';
+import { indexCarriedDefinitions } from './core/carried-definitions.js';
 import { FORM_FIELD_JSON_TYPE } from './core/form-field-type.js';
 import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingLabelRefusal, bindingMissingMessage, missingBindingLabels } from './core/binding-messages.js';
@@ -2271,8 +2272,8 @@ function declaresMemoryHandle(def) {
  * compiles. The corpus also carries 1.1 and 1.3; `shared/sample-flows/
  * inline-agent.flow` says 1.0, which appears in none of the 29.
  */
-function inlineAgentDef(version, withMemory) {
-    const bundled = DEFS[`${INLINE_AGENT_TYPE}@${version}`];
+function inlineAgentDef(version, withMemory, resolve = (t, v) => DEFS[`${t}@${v}`]) {
+    const bundled = resolve(INLINE_AGENT_TYPE, version);
     if (!bundled)
         return undefined;
     const def = jsonClone(bundled);
@@ -4240,6 +4241,17 @@ function stepNamesOf(steps, out = []) {
     return out;
 }
 export function serialize(built, opts = {}) {
+    /**
+     * Definitions the flow carries (`.definitions()`, #1128), by `type@version` —
+     * the third source a pinned `{ version }` resolves from, after the bundle and
+     * the node-type registry. A flow that carries nothing compiles exactly as
+     * before. A subflow body sees its own carried definitions plus its
+     * ancestors' (as `check` does), only while it is emitted.
+     */
+    let carriedDefs = indexCarriedDefinitions(built.definitions ?? [], `flow "${built.id}" .definitions()`);
+    const carriedFor = Object.assign((type, version) => carriedDefs.get(`${type}@${version}`), { versions: (type) => [...carriedDefs.keys()].filter((k) => k.startsWith(`${type}@`)).map((k) => k.slice(type.length + 1)) });
+    /** The exact definition of `type@version`: bundled, else carried, else `undefined`. */
+    const definitionFor = (type, version) => DEFS[`${type}@${version}`] ?? carriedFor(type, version);
     /**
      * The `definitions[]` a flow carries, keyed by `type@version` — NOT by type.
      * One flow can legitimately hold two versions of the same family (a plain
@@ -4451,19 +4463,22 @@ export function serialize(built, opts = {}) {
     function makeNode(type, id, label, o = {}) {
         let def = o.def ?? defByType.get(type);
         if (o.requestedVersion !== undefined && def?.version !== o.requestedVersion) {
-            const exact = o.def ? undefined : DEFS[`${type}@${o.requestedVersion}`];
+            const exact = o.def ? undefined : definitionFor(type, o.requestedVersion);
             if (!exact) {
-                // Name every version the SDK could have resolved: every bundled
-                // version of the type, else (a type built per resource, a connector)
-                // the definition in hand. Naming only the default sent the reader
-                // looking for a version that was shipped all along (#1128:
+                // Name every version the SDK could have resolved: every bundled or
+                // carried version of the type, else (a type built per resource, a
+                // connector) the definition in hand. Naming only the default sent the
+                // reader looking for a version that was shipped all along (#1128:
                 // quick-form bundles 1.0 AND 1.1, and the message said 1.0).
-                const bundled = bundledVersions(type);
-                const resolvable = bundled.length > 0 ? bundled
+                const prefix = `${type}@`;
+                const carriedVersions = [...carriedDefs.keys()].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+                const known = o.def ? [] : [...bundledVersions(type), ...carriedVersions];
+                const resolvable = known.length > 0 ? known
                     : [def?.version].filter((v) => typeof v === 'string');
                 throw new Error(`"${label ?? id}" requests ${type}@${o.requestedVersion}, but this SDK resolves only `
                     + `${type}@${resolvable.join(', ') || '<none>'}. Versions are exact — omit { version } to use `
-                    + `the pinned default, or request a version this SDK ships.`);
+                    + `the pinned default, request a version this SDK ships, or carry that version's definition `
+                    + `(the .flow file's definitions[] entry) with .definitions([...]).`);
             }
             def = exact;
         }
@@ -4532,6 +4547,16 @@ export function serialize(built, opts = {}) {
      * a null. It is emitted here, always, so it cannot be forgotten.
      */
     function emitSubflowBody(child, nodeId) {
+        const outer = carriedDefs;
+        carriedDefs = indexCarriedDefinitions(child.definitions ?? [], `subflow "${nodeId}" .definitions()`, new Map(outer));
+        try {
+            return emitSubflowBodyIn(child, nodeId);
+        }
+        finally {
+            carriedDefs = outer;
+        }
+    }
+    function emitSubflowBodyIn(child, nodeId) {
         const childGlobals = emittableGlobals(child, `subflow "${nodeId}"`, 'subflow');
         const scope = newScope(childGlobals.outputs, childGlobals.vars, childGlobals.backing, childGlobals.backingReads);
         // Claim this copy's node ids UP FRONT, so the rename map is complete before
@@ -4807,7 +4832,11 @@ export function serialize(built, opts = {}) {
     function emitRegistered(entry, step, tails, scope, parentId) {
         const where = `step "${step.name}"`;
         const spec = step.spec;
-        const impl = resolveVersion(entry.type, spec, step.options?.version, where);
+        // A pin the registry has no implementation for, but the flow carries, is
+        // emitted at that version with the carried definition (#1128).
+        const resolved = resolveVersionCarried(entry.type, spec, step.options?.version, where, carriedFor);
+        const impl = resolved.impl;
+        const version = resolved.version;
         const id = stepUid(scope, step.name);
         // As for every typed family: record the failure-envelope boundary before any
         // expression renders, so a handler reading this step resolves correctly.
@@ -4817,14 +4846,19 @@ export function serialize(built, opts = {}) {
             step: step.name,
             nodeId: id,
             flowId: built.id,
-            version: impl.version,
+            version,
             pinnedVersion: step.options?.version,
             render: (value) => renderValue(value, scope.rename),
             renameRefs: (js) => renameRefs(js, scope.rename),
             stepNodeId: (name) => scope.stepNodeId.get(name) ?? name,
             mint: (seed) => stableId(`${built.id}:${id}:${seed}`),
             bind: (b) => { bound.push(b); },
-            definition: (typeName, version) => bundledDefinition(typeName, version),
+            // At a carried version the node's own definition IS the carried one,
+            // whatever version the implementation asks for (it was written for a
+            // bundled one), so its defaults and outputs come from the file's entry.
+            definition: (typeName, v) => (resolved.carried !== undefined && typeName === impl.typeName
+                ? resolved.carried
+                : bundledDefinition(typeName, v) ?? carriedFor(typeName, v)),
             bindings: resourceBindings,
             resolveBinding: (name, attribute, at) => resolveBinding(opts, name, attribute, at),
             bindConnection: (c) => {
@@ -4843,26 +4877,31 @@ export function serialize(built, opts = {}) {
         // The definition contract, both halves: a per-tenant type supplies its
         // definition, and a bundled type does not (its definition is the bundle's, and
         // makeNode records it, so the error-edge refusal and check ask the same one).
-        let def;
+        let def = resolved.carried;
         if (impl.definition === 'bundled' && contribution.definition !== undefined) {
-            throw new Error(`internal SDK error: ${where}: bundled node type ${impl.typeName}@${impl.version} returned a definition; `
+            throw new Error(`internal SDK error: ${where}: bundled node type ${impl.typeName}@${version} returned a definition; `
                 + 'the bundle owns it — omit `definition`, or declare the type per-tenant.');
         }
+        // A per-tenant type builds its definition from `ctx.definition(type, version)`,
+        // which answers with the carried definition at a carried version, so the
+        // contribution's own definition wins: it is the carried template plus this
+        // instance's edits (a queue step's own resourceKey, for instance). Only a type
+        // that supplies none at a carried version takes the carried definition as is.
         if (contribution.definition !== undefined) {
-            def = resolveContributionDefinition(contribution.definition, impl.version, where);
+            def = resolveContributionDefinition(contribution.definition, version, where);
         }
-        else if (impl.definition === 'per-tenant') {
-            throw new Error(`internal SDK error: ${where}: per-tenant node type ${impl.typeName}@${impl.version} returned no definition.`);
+        else if (impl.definition === 'per-tenant' && resolved.carried === undefined) {
+            throw new Error(`internal SDK error: ${where}: per-tenant node type ${impl.typeName}@${version} returned no definition.`);
         }
         if (impl.definition === 'per-tenant') {
             const port = typeof impl.errorPort === 'function' ? impl.errorPort(spec) : impl.errorPort === true;
             // The declaration answers for check, which has no definition; here the
             // definition is in hand, and the two must agree (#1011).
             if (port && def !== undefined && !definitionHasErrorPort(def)) {
-                throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${impl.version} declares an error port, `
+                throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${version} declares an error port, `
                     + 'but the definition it supplied has no error handle and no supportsErrorHandling.');
             }
-            declaredErrorPorts.set(id, { port, typeName: impl.typeName, version: impl.version });
+            declaredErrorPorts.set(id, { port, typeName: impl.typeName, version });
         }
         // A forward port is a handle the definition declares, one of the type's
         // author-named exits, or one the product derives (`derivesPort`: a human
@@ -4871,13 +4910,17 @@ export function serialize(built, opts = {}) {
         const exitPorts = new Set(exits && hasExits(exits) ? exits.map((e) => e.port) : []);
         for (const p of [...(contribution.port !== undefined ? [contribution.port] : []), ...(contribution.fanOut ?? []).map((f) => f.port)]) {
             if (exitPorts.has(p) || impl.derivesPort?.(spec, p)
-                || declaresForwardPort(def ?? bundledDefinition(impl.typeName, impl.version), p))
+                || declaresForwardPort(def ?? bundledDefinition(impl.typeName, version), p))
                 continue;
-            throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${impl.version} leaves by port "${p}", `
+            throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${version} leaves by port "${p}", `
                 + 'which its definition declares no source handle for, and the type neither lists as an exit nor derives.');
         }
+        // A carried definition answers the error-edge refusal as a bundled one does
+        // (makeNode records only the definitions it resolved itself).
+        if (resolved.carried !== undefined)
+            bundledNodeDefs.set(id, def ?? resolved.carried);
         return placeStepNode({
-            where, stepName: step.name, id, typeName: impl.typeName, requestedVersion: impl.version, def, contribution, bound, tails, scope, parentId,
+            where, stepName: step.name, id, typeName: impl.typeName, requestedVersion: version, def, contribution, bound, tails, scope, parentId,
             trackOutcomes: true,
         });
     }
@@ -5041,11 +5084,12 @@ export function serialize(built, opts = {}) {
             // agent attaches memory keeps the handle for all of them.
             const withMemory = s.memory !== undefined
                 || declaresMemoryHandle(emittedDefs.get(`${INLINE_AGENT_TYPE}@${version}`));
-            const def = inlineAgentDef(version, withMemory);
+            const def = inlineAgentDef(version, withMemory, definitionFor);
             if (!def) {
                 throw new Error(`"${step.name}" requests ${INLINE_AGENT_TYPE}@${version}, but this SDK resolves only `
                     + `${INLINE_AGENT_VERSIONS.map((v) => `${INLINE_AGENT_TYPE}@${v}`).join(', ')}. Versions are exact — `
-                    + `omit { version } to use the default (${INLINE_AGENT_DEFAULT_VERSION}), or request a version this SDK ships.`);
+                    + `omit { version } to use the default (${INLINE_AGENT_DEFAULT_VERSION}), request a version this SDK ships, `
+                    + `or carry that version's definition with .definitions([...]).`);
             }
             if (s.memory !== undefined && !declaresMemoryHandle(def)) {
                 throw new Error(`"${step.name}" attaches \`memory\`, but ${INLINE_AGENT_TYPE}@${version} declares no \`memory\` handle. `