@uipath/maestro-builder-sdk 6.18.10 → 6.20.0

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

@@ -19,6 +19,10 @@
  *
  * Parity reference: `docs/FLOW_PARITY.md`.
  */
+/**
+ * A diagnostic a node contributes during `check` — surfaced alongside the
+ * built-in rules with the same severities.
+ */
 export interface ContributionDiagnostic {
     /** Stable machine-readable code, SCREAMING_SNAKE by convention. */
     code: string;
@@ -177,66 +181,3 @@ export declare abstract class FlowResource extends FlowNode<never> {
     /** Always `'resource'` for an attached node. */
     get role(): 'resource';
 }
-/**
- * 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/core/node-classes.js

@@ -19,12 +19,6 @@
  *
  * Parity reference: `docs/FLOW_PARITY.md`.
  */
-/**
- * A diagnostic a node contributes during `check` — surfaced alongside the
- * built-in rules with the same severities.
- */
-import { connectorRawNodeRefusal } from './connector-raw-node.js';
-import { typedFamilyRawNodeWarning, dataFabricUnknownInputs } from './typed-raw-node.js';
 /**
  * The abstract root of every definition-backed node the builder can place.
  *
@@ -74,109 +68,3 @@ export class FlowResource extends FlowNode {
         return 'resource';
     }
 }
-/**
- * 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 a Data Fabric key the product never reads as an error at a
-     * bundled version (a warning at any other); `compile` throws the errors
-     * (see {@link contribute}).
-     */
-    diagnostics() {
-        const refusal = connectorRawNodeRefusal(this.spec.nodeType);
-        if (refusal)
-            return [{ code: 'RAW_NODE_CONNECTOR', severity: 'error', message: refusal }];
-        const out = [];
-        const unknown = dataFabricUnknownInputs(this.spec.nodeType, this.spec.version, this.spec.inputs);
-        if (unknown)
-            out.push({ code: 'RAW_NODE_UNKNOWN_INPUT', ...unknown });
-        const typed = typedFamilyRawNodeWarning(this.spec.nodeType);
-        if (typed)
-            out.push({ code: 'RAW_NODE_TYPED_FAMILY', severity: 'warning', message: typed });
-        return out;
-    }
-    contribute(context) {
-        // compile does not run diagnostics(); refuse here too so the escape hatch
-        // cannot emit an unconfigured connector node. (A Data Fabric key the
-        // product never reads is refused by the serializer, for every contribution.)
-        const refusal = connectorRawNodeRefusal(this.spec.nodeType);
-        if (refusal)
-            throw new Error(refusal);
-        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/core/nodes/family.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Node families — node types grouped under one owner (design §3, §4.4).
+ *
+ * A family is organizational: one directory, one CODEOWNERS line, one README for
+ * the developers who work on it, and one catalog of the diagnostic codes its types
+ * emit. Its only behaviour is `check`, for rules that need every placement of the
+ * family at once (a Data Fabric update whose `fromRead` names no read step). A
+ * family object is per artifact, like its node types: Flow's Data Fabric family and
+ * BPMN's are two families that may share a directory and nothing else.
+ */
+import type { ArtifactContexts } from './node-type.js';
+import type { AnyNodeType } from './versioned.js';
+/** Every code a family may emit, with its severity and a one-line summary. */
+export type DiagnosticCatalog = Readonly<Record<string, {
+    readonly severity: 'error' | 'warning';
+    readonly summary: string;
+}>>;
+/** One placed node of a family, as the family-level check sees it. */
+export interface Placement<Spec = unknown> {
+    /** The step name the author gave the node. */
+    readonly step: string;
+    /** The registered kind. */
+    readonly kind: string;
+    readonly spec: Spec;
+    /** The version the node will be emitted at. */
+    readonly version: string;
+}
+export interface NodeFamily<Ctx extends ArtifactContexts> {
+    /** Stable id, e.g. `'data-fabric'`. Unique within the artifact's registry. */
+    readonly id: string;
+    readonly title: string;
+    readonly types: readonly AnyNodeType<Ctx>[];
+    readonly diagnostics: DiagnosticCatalog;
+    /** Rules over every placement of this family's types, after the per-node checks. */
+    check?(placements: readonly Placement[], ctx: Ctx['familyCheck']): void;
+}

package/dist/core/nodes/family.js

@@ -0,0 +1 @@
+export {};

package/dist/core/nodes/node-type.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The node-type contract — one implementation per node type, per artifact, per
+ * version. docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §4.
+ *
+ * A node type owns what one placed node means and how it looks in its artifact's
+ * file: serializing a spec, deserializing a serialized node back to its spec (the
+ * lift `decompile` runs), printing the spec as the factory call an author writes,
+ * checking it, and declaring its expressions, output and error port. The artifact
+ * keeps everything structural — ids, labels, layout, edges, definition dedupe — and
+ * lends the node type a narrow context for each job, never its own internals.
+ *
+ * The pattern is the one n8n (`INodeType`, `VersionedNodeType`), Jackson
+ * (`JsonSerializer` / `JsonDeserializer` with a context) and ESLint (a rule with a
+ * reporting `context`) use; §2 of the design maps the names.
+ *
+ * Generic over the artifact: `Serialized` is what `serialize` returns (Flow's
+ * `FlowNodeContribution`), and `Ctx` names the artifact's four contexts. Each
+ * artifact exports its own specialization (`FlowNodeType<Spec>` in
+ * `flow-node-type.ts`), so a contributor never writes these parameters.
+ */
+import type { TypeDesc } from '../expr.js';
+/**
+ * Where a node type's definition comes from. `bundled`: a `<typeName>@<version>`
+ * entry the SDK ships, which every answer the definition can give (its error port,
+ * its declared inputs) is read from. `per-tenant`: built per tenant or per call —
+ * there is no bundled entry to ask, so the node type declares those answers itself.
+ */
+export type DefinitionSource = 'bundled' | 'per-tenant';
+/**
+ * One place a spec carries a value the artifact evaluates against its scope.
+ * `value` is walked deeply for expressions; `code` is a script body whose
+ * references are checked although it is a plain string.
+ */
+export type ExprSite = {
+    readonly value: unknown;
+} | {
+    readonly code: string;
+};
+/** A read of a node's output, as the output rules see it. */
+export interface OutputRead {
+    /** The step name being read. */
+    node: string;
+    /** The reference as the author wrote it, e.g. `$vars.del.output`. */
+    ref: string;
+    /** The step whose expression contains the read. */
+    reader: string;
+}
+/**
+ * What reading a node's output yields at run time.
+ *
+ * `none` keeps the diagnostic code of the rule it replaces
+ * (`DATAFABRIC_DELETE_HAS_NO_OUTPUT`, `MOCK_HAS_NO_OUTPUT`, …) and builds the
+ * message itself, so a port changes no diagnostic an author sees.
+ */
+export type OutputContract = {
+    readonly kind: 'none';
+    readonly code: string;
+    message(read: OutputRead): string;
+} | {
+    readonly kind: 'fields';
+    readonly fields: Readonly<Record<string, TypeDesc>>;
+    readonly open?: boolean;
+} | {
+    readonly kind: 'opaque';
+};
+/**
+ * A factory call as decompile prints it: the factory's name, its positional
+ * arguments, then an options object — every value already rendered as source
+ * text. An option whose source is `undefined` is left out, and an options object
+ * with nothing in it is not printed. The artifact renders the call
+ * (`connector('slack', 'send', { … }, { connection: 'x' })`), owning import
+ * tracking and formatting, so output stays byte-identical to the hand-written
+ * printers it replaces (design §7).
+ */
+export interface FactoryCall {
+    readonly factory: string;
+    readonly positional?: readonly string[];
+    readonly options?: ReadonlyArray<readonly [name: string, source: string | undefined]>;
+}
+/** The contexts an artifact lends its node types, one per job. */
+export interface ArtifactContexts {
+    serialize: unknown;
+    deserialize: unknown;
+    print: unknown;
+    check: unknown;
+    familyCheck: unknown;
+}
+/** One node type at one version, for one artifact. See the module header. */
+export interface NodeType<Spec, Serialized, Ctx extends ArtifactContexts> {
+    /** The spec discriminator, e.g. `'dataFabricRead'`. Unique within the artifact's registry. */
+    readonly kind: string;
+    /** The type name in the file, e.g. `'core.datafabric.read'`. Unique within the artifact's registry. */
+    readonly typeName: string;
+    /** The exact version this implementation serializes and recognizes. */
+    readonly version: string;
+    /** The public factory that produces this spec, e.g. `'dataFabricRead'`. */
+    readonly factory: string;
+    /** Where the definition comes from; decides who answers `errorPort` (see below). */
+    readonly definition: DefinitionSource;
+    /**
+     * Whether the node has an error port. A `bundled` type must omit it — the answer
+     * is the definition's, at this version. A `per-tenant` type must declare it,
+     * because there is no definition to ask. The registry refuses either mistake.
+     */
+    readonly errorPort?: boolean | ((spec: Spec) => boolean);
+    /** Spec → the node's type-owned fields. The artifact still owns id, label, layout, edges and dedupe. */
+    serialize(spec: Spec, ctx: Ctx['serialize']): Serialized;
+    /** The lift: one serialized node → the spec it came from, or `undefined` when it is not this type's. */
+    deserialize(node: unknown, ctx: Ctx['deserialize']): Spec | undefined;
+    /** Spec → the factory call decompile prints. Omit it for the artifact's default, `factory(spec.inputs)`. */
+    print?(spec: Spec, ctx: Ctx['print']): FactoryCall;
+    /** Node-local rules, reported through `ctx`. Never throws for an authoring mistake. */
+    check?(spec: Spec, ctx: Ctx['check']): void;
+    /**
+     * Rules for an error handler the author attached to this node, run only once the
+     * node is known to have an error port (that decision is the artifact's, from the
+     * definition or `errorPort`). For a node whose port exists but whose failures a
+     * handler cannot usefully catch — Flow's plain HTTP request completes on a
+     * 4xx/5xx and publishes no envelope. Reported through `ctx` like `check`.
+     */
+    checkErrorHandler?(spec: Spec, ctx: Ctx['check']): void;
+    /**
+     * Every authored value evaluated against the artifact's scope. Required: a type
+     * with none returns `[]`, by decision, because an omitted hook would silently
+     * switch off every reference rule for its steps.
+     */
+    expressions(spec: Spec): Iterable<ExprSite>;
+    /** What reading this node's output yields. */
+    output(spec: Spec): OutputContract;
+    /**
+     * Whether this node type is the one for `spec`, when several share a kind (see
+     * VersionedNodeType.matches). On a single-version type only; a versioned type
+     * declares it once, on the VersionedNodeType.
+     */
+    matches?(spec: Spec): boolean;
+}

package/dist/core/nodes/node-type.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,57 @@
+/**
+ * The node-type registry — one per artifact, built from an explicit list of
+ * families (design §4.5).
+ *
+ * There is no registration as a side effect of importing a module: the artifact's
+ * registry module names its families, so load order cannot change what is
+ * registered and the architecture lint's no-cycle rule (FB003) keeps holding.
+ *
+ * Construction validates every invariant the pipeline relies on, and refuses with
+ * every problem at once rather than the first:
+ *   - type names and family ids are unique, and so are kinds — except that
+ *     several node types may share one kind when each declares `matches(spec)`;
+ *   - each version's implementation agrees with the entry it is listed under
+ *     (kind, type name, factory, version key) and the default version is listed;
+ *   - a `bundled` type has the definition the artifact bundles at each version and
+ *     declares no `errorPort` (the definition answers); a `per-tenant` type
+ *     declares one (nothing else can);
+ *   - no diagnostic code is claimed by two families.
+ */
+import type { ArtifactContexts } from './node-type.js';
+import type { NodeFamily } from './family.js';
+import { type VersionedNodeType } from './versioned.js';
+/** A registered node type with the family that owns it. */
+export interface Registered<Ctx extends ArtifactContexts> {
+    readonly family: NodeFamily<Ctx>;
+    readonly type: VersionedNodeType<unknown, unknown, Ctx>;
+}
+export interface NodeTypeRegistryOptions {
+    /**
+     * Whether the artifact bundles `<typeName>@<version>`. Required to validate a
+     * `bundled` type; an artifact with no bundled definitions passes `() => false`.
+     */
+    hasBundledDefinition(typeName: string, version: string): boolean;
+}
+export declare class NodeTypeRegistry<Ctx extends ArtifactContexts> {
+    #private;
+    readonly artifact: string;
+    readonly families: readonly NodeFamily<Ctx>[];
+    /**
+     * @param artifact - The artifact's name, for messages (`'flow'`).
+     * @param families - Every family this artifact supports, in no significant order.
+     * @param options - What the artifact knows that the contract does not.
+     */
+    constructor(artifact: string, families: readonly NodeFamily<Ctx>[], options: NodeTypeRegistryOptions);
+    /**
+     * The node type for a spec, by its kind, or undefined when the kind is not
+     * registered. When several types share the kind, the one whose `matches(spec)`
+     * holds — undefined when none does; two matching is an SDK bug and throws.
+     */
+    byKind(kind: string, spec?: unknown): Registered<Ctx> | undefined;
+    /** Every node type registered for a kind (several when they share it), in registration order. */
+    typesOfKind(kind: string): readonly Registered<Ctx>[];
+    /** The node type for a type name in the file, or undefined when it is not registered. */
+    byTypeName(typeName: string): Registered<Ctx> | undefined;
+    /** Every registered kind, sorted. */
+    kinds(): string[];
+}

package/dist/core/nodes/registry.js

@@ -0,0 +1,122 @@
+import { asVersioned } from './versioned.js';
+import { ownEntry } from '../own-entry.js';
+export class NodeTypeRegistry {
+    artifact;
+    families;
+    #byKind = new Map();
+    #byTypeName = new Map();
+    /**
+     * @param artifact - The artifact's name, for messages (`'flow'`).
+     * @param families - Every family this artifact supports, in no significant order.
+     * @param options - What the artifact knows that the contract does not.
+     */
+    constructor(artifact, families, options) {
+        this.artifact = artifact;
+        this.families = families;
+        const problems = [];
+        const familyIds = new Set();
+        const codeOwner = new Map();
+        for (const family of families) {
+            if (familyIds.has(family.id))
+                problems.push(`family "${family.id}" is listed twice`);
+            familyIds.add(family.id);
+            for (const code of Object.keys(family.diagnostics)) {
+                const owner = codeOwner.get(code);
+                if (owner !== undefined && owner !== family.id) {
+                    problems.push(`diagnostic code ${code} is claimed by both "${owner}" and "${family.id}"`);
+                }
+                codeOwner.set(code, family.id);
+            }
+            for (const listed of family.types) {
+                const type = asVersioned(listed);
+                const where = `${family.id}/${type.kind}`;
+                const sharing = this.#byKind.get(type.kind);
+                if (sharing && (!type.matches || sharing.some((other) => !other.type.matches))) {
+                    problems.push(`kind "${type.kind}" is registered twice (${[...sharing, { family, type }].map((e) => `${e.family.id}/${e.type.typeName}`).join(' and ')}); node types that share a kind must each declare matches(spec)`);
+                }
+                const typeOwner = this.#byTypeName.get(type.typeName);
+                if (typeOwner) {
+                    problems.push(`type name "${type.typeName}" is registered twice (${placeOf(typeOwner)} and ${where}); one VersionedNodeType owns every version of a type`);
+                }
+                const versions = Object.keys(type.versions);
+                if (versions.length === 0)
+                    problems.push(`${where} registers no versions`);
+                if (ownEntry(type.versions, type.defaultVersion) === undefined) {
+                    problems.push(`${where}: default version ${type.defaultVersion} is not registered (${versions.join(', ')})`);
+                }
+                for (const [key, impl] of Object.entries(type.versions)) {
+                    problems.push(...implementationProblems(where, key, impl, type, options));
+                }
+                const entry = { family, type };
+                this.#byKind.set(type.kind, [...(sharing ?? []), entry]);
+                this.#byTypeName.set(type.typeName, entry);
+            }
+        }
+        if (problems.length > 0) {
+            throw new Error(`internal SDK error: the ${artifact} node-type registry is inconsistent:\n`
+                + problems.map((p) => `  - ${p}`).join('\n'));
+        }
+    }
+    /**
+     * The node type for a spec, by its kind, or undefined when the kind is not
+     * registered. When several types share the kind, the one whose `matches(spec)`
+     * holds — undefined when none does; two matching is an SDK bug and throws.
+     */
+    byKind(kind, spec) {
+        const all = this.#byKind.get(kind);
+        if (!all)
+            return undefined;
+        if (all.length === 1)
+            return all[0];
+        const hits = all.filter((e) => e.type.matches(spec));
+        if (hits.length > 1) {
+            throw new Error(`internal SDK error: a ${kind} spec matches ${hits.map((h) => h.type.typeName).join(' and ')}; exactly one may.`);
+        }
+        return hits[0];
+    }
+    /** Every node type registered for a kind (several when they share it), in registration order. */
+    typesOfKind(kind) {
+        return this.#byKind.get(kind) ?? [];
+    }
+    /** The node type for a type name in the file, or undefined when it is not registered. */
+    byTypeName(typeName) {
+        return this.#byTypeName.get(typeName);
+    }
+    /** Every registered kind, sorted. */
+    kinds() {
+        return [...this.#byKind.keys()].sort();
+    }
+}
+/** Where a registered type lives, as the registry's messages name it: `<family>/<kind>`. */
+function placeOf(entry) {
+    return `${entry.family.id}/${entry.type.kind}`;
+}
+/** What is wrong with one version's implementation, as registry problems. */
+function implementationProblems(where, key, impl, type, options) {
+    const at = `${where}@${key}`;
+    const out = [];
+    if (impl.version !== key)
+        out.push(`${at}: listed under ${key} but declares version ${impl.version}`);
+    if (impl.kind !== type.kind)
+        out.push(`${at}: declares kind "${impl.kind}"`);
+    if (impl.typeName !== type.typeName)
+        out.push(`${at}: declares type name "${impl.typeName}"`);
+    if (impl.factory !== type.factory)
+        out.push(`${at}: declares factory "${impl.factory}", the type says "${type.factory}"`);
+    // Typed as required; checked here too, for an implementation the compiler did not see.
+    if (typeof impl.expressions !== 'function') {
+        out.push(`${at}: declares no expressions(spec); return [] when the type has no expression sites`);
+    }
+    if (impl.definition === 'bundled') {
+        if (!options.hasBundledDefinition(impl.typeName, impl.version)) {
+            out.push(`${at}: is bundled, but ${impl.typeName}@${impl.version} is not a bundled definition`);
+        }
+        if (impl.errorPort !== undefined) {
+            out.push(`${at}: is bundled, so its definition answers errorPort — remove the declaration (#1011)`);
+        }
+    }
+    else if (impl.errorPort === undefined) {
+        out.push(`${at}: is per-tenant, so it must declare errorPort — there is no definition to ask`);
+    }
+    return out;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Versioned node types — one implementation per version (design §4.2, §7).
+ *
+ * A node type whose serialized shape changed between versions registers one
+ * {@link NodeType} per version under a {@link VersionedNodeType}, the way n8n's
+ * `VersionedNodeType` maps each version to its own implementation. A new version
+ * is a new entry (usually a subclass of the previous one), so adding it cannot
+ * change how a node at an older version serializes, deserializes or prints.
+ */
+import type { ArtifactContexts, NodeType } from './node-type.js';
+export interface VersionedNodeType<Spec, Serialized, Ctx extends ArtifactContexts, 
+/** The implementation type: an artifact's own extension of NodeType, when it has one. */
+Impl extends NodeType<Spec, Serialized, Ctx> = NodeType<Spec, Serialized, Ctx>> {
+    readonly kind: string;
+    readonly typeName: string;
+    readonly factory: string;
+    /** The version used when the author names none. Changing it is a breaking change. */
+    readonly defaultVersion: string;
+    /** Every registered version → its implementation. Keys equal each entry's `version`. */
+    readonly versions: Readonly<Record<string, Impl>>;
+    /**
+     * The version a spec needs when the author named none (`requested` undefined),
+     * e.g. a read that sets `resultMode` needs `core.datafabric.read@1.4`. Omit it
+     * and the default version is used. An explicit request is never second-guessed:
+     * the registry resolves it exactly or refuses it (see `resolveVersion`).
+     */
+    select?(spec: Spec): string;
+    /**
+     * Whether this node type is the one for `spec`, when several share a kind —
+     * one authoring kind can cover several node types (`transform` and its
+     * `variant`s, `http` and `{ managed }`). Required for each type of a shared
+     * kind, and exactly one of them must match a given spec; omit it for a kind
+     * this type has alone.
+     */
+    matches?(spec: Spec): boolean;
+}
+/** Either form a family may list: one version, or several. */
+export type AnyNodeType<Ctx extends ArtifactContexts> = NodeType<any, any, Ctx> | VersionedNodeType<any, any, Ctx>;
+/** True for a {@link VersionedNodeType}; a plain {@link NodeType} carries `version` instead. */
+export declare function isVersioned<Ctx extends ArtifactContexts>(t: AnyNodeType<Ctx>): t is AnyNodeType<Ctx> & VersionedNodeType<unknown, unknown, Ctx>;
+/** A single-version node type as the one-entry {@link VersionedNodeType} the registry stores. */
+export declare function asVersioned<Ctx extends ArtifactContexts>(t: AnyNodeType<Ctx>): VersionedNodeType<unknown, unknown, Ctx>;
+/**
+ * The exact version to emit for `spec`: the author's request when there is one —
+ * refused unless it is registered — else `select(spec)`, else the default.
+ * An unregistered request throws for the author, naming the step (`where`) and
+ * the registered versions; a `select` that returns an unregistered version is the
+ * 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>;

package/dist/core/nodes/versioned.js

@@ -0,0 +1,46 @@
+import { ownEntry } from '../own-entry.js';
+/** True for a {@link VersionedNodeType}; a plain {@link NodeType} carries `version` instead. */
+export function isVersioned(t) {
+    return 'versions' in t;
+}
+/** A single-version node type as the one-entry {@link VersionedNodeType} the registry stores. */
+export function asVersioned(t) {
+    if (isVersioned(t))
+        return t;
+    const one = t;
+    return {
+        kind: one.kind,
+        typeName: one.typeName,
+        factory: one.factory,
+        defaultVersion: one.version,
+        versions: { [one.version]: one },
+        ...(one.matches ? { matches: (spec) => one.matches(spec) } : {}),
+    };
+}
+/**
+ * The exact version to emit for `spec`: the author's request when there is one —
+ * refused unless it is registered — else `select(spec)`, else the default.
+ * An unregistered request throws for the author, naming the step (`where`) and
+ * the registered versions; a `select` that returns an unregistered version is the
+ * node type's bug, not the author's, and throws as an internal SDK error.
+ */
+export function resolveVersion(t, spec, requested, where) {
+    const selected = requested === undefined ? t.select?.(spec) : undefined;
+    const version = requested ?? selected ?? t.defaultVersion;
+    const impl = ownEntry(t.versions, version);
+    if (!impl) {
+        const known = Object.keys(t.versions).sort().join(', ');
+        if (requested === undefined && selected === undefined) {
+            // A registered type's default is always registered; this is a type used before registration.
+            throw new Error(`internal SDK error: ${t.typeName}'s defaultVersion ${version} is not one of its versions (${known}), `
+                + `used for ${where}. This is a bug in the node type, not in the flow; please report it.`);
+        }
+        if (requested === undefined) {
+            throw new Error(`internal SDK error: ${t.typeName}'s select() chose ${version} for ${where}, but the type registers only `
+                + `${known}. This is a bug in the node type, not in the flow; please report it.`);
+        }
+        throw new Error(`${where} requests ${t.typeName}@${version}, but this SDK registers only ${known}. `
+            + 'Versions are exact — omit { version } to use the default, or request one listed here.');
+    }
+    return impl;
+}