@uipath/maestro-builder-sdk 5.2.0

package/dist/core/lookups.js

@@ -0,0 +1,231 @@
+/**
+ * core/lookups — authoring a connector field whose value is an opaque id.
+ *
+ * Sending a Slack message to a person needs that person's Slack user id. The id
+ * is wrong to write down twice over: it is meaningless in review (nothing in a
+ * diff says which person `WT9RC72KU` is), and it is silently wrong after a move
+ * (deploy against another workspace and it resolves to nobody, or to somebody).
+ * An email is not immune — people leave — but it is reviewable, and it fails
+ * LOUDLY: resolution against the new workspace either finds the person or says
+ * it did not.
+ *
+ * So the author writes what they mean and resolution happens later:
+ *
+ * ```ts
+ * channel: lookup(SendMessageToUser, 'channel').byEmail('dustin@example.com')
+ * ```
+ *
+ * That call returns an unresolved {@link LookupToken}, not a string. Each stage
+ * of the pipeline can then see it for what it is: `check` reports it as owed
+ * work and prints the command that discharges it, `registry prepare --resolve`
+ * performs the one network call and records the answer, and `compile` reads the
+ * recorded answer. Compile never resolves anything itself — it is offline by
+ * design, because the byte-lock gates require that the same source produces the
+ * same bytes regardless of tenant state.
+ *
+ * Not every `reference` block earns a helper. See `_lookups.py` for the two
+ * degenerate classes the generator excludes and why generating for them would
+ * make the surface worse rather than more complete.
+ */
+import { prepareCommand } from './cli-spelling.js';
+/** True when `v` is an unresolved {@link LookupToken}. */
+export function isLookupToken(v) {
+    return (typeof v === 'object' && v !== null &&
+        typeof v.__lookup === 'object' &&
+        v.__lookup !== null &&
+        typeof v.__lookup.field === 'string');
+}
+/**
+ * The identity of one resolution, as `prepare` records it and `compile` reads it.
+ *
+ * JSON-encoded rather than delimiter-joined because every component is
+ * author-supplied text: a real name containing the delimiter would collide two
+ * distinct resolutions onto one key, and the symptom would be a flow compiled
+ * with the wrong person's id.
+ */
+export function lookupKey(nodeType, field, by, value) {
+    return JSON.stringify([nodeType, field, by, value]);
+}
+function makeBuilder(nodeType, field, spec) {
+    const token = (by, value) => ({ __lookup: { nodeType, field, by, value } });
+    const builder = {
+        by(name, value) {
+            // A `by` the collection cannot be searched by is caught here rather than
+            // at `prepare` time. The alternative is spending the network call to be
+            // told the field does not exist, which is the expensive way to learn it.
+            if (spec && !spec.by.includes(name)) {
+                throw new Error(`lookup(${nodeType}, '${field}'): cannot search by "${name}". ` +
+                    `This collection is searchable by ${spec.by.map((b) => `"${b}"`).join(', ')}.`);
+            }
+            return token(name, value);
+        },
+    };
+    for (const [alias, byName] of Object.entries(spec?.aliases ?? {})) {
+        builder[alias] = (value) => token(byName, value);
+    }
+    return builder;
+}
+export function lookup(a, b, c) {
+    if (typeof a === 'string') {
+        if (typeof c !== 'string') {
+            throw new Error("lookup(key, action, field) needs all three arguments; " +
+                "did you mean lookup(descriptor, field)?");
+        }
+        return makeBuilder(`uipath.connector.${a}.${b}`, c);
+    }
+    if (!('nodeType' in a) || a.nodeType === undefined) {
+        const event = a;
+        if (typeof event.connector === 'string' && typeof event.event === 'string') {
+            // The spec, when the descriptor carries one. Dropping it here is what
+            // made `.byDisplayName` a `TypeError` on a trigger whose generated
+            // descriptor declared that very alias: the branch is chosen on the
+            // ABSENCE of `nodeType`, not on the absence of a lookup table.
+            return makeBuilder(`uipath.connector.event.${event.connector}.${event.event}`, b, event.lookups?.[b]);
+        }
+    }
+    const bearing = a;
+    const spec = bearing.lookups?.[b];
+    if (!spec) {
+        const known = Object.keys(bearing.lookups ?? {});
+        // Naming the fields that DO have one matters: the commonest cause of this
+        // is a field whose `reference` is degenerate, where the right answer is a
+        // plain string and not a different helper call.
+        throw new Error(`lookup(${bearing.nodeType}, '${b}'): no lookup is generated for that field. ` +
+            (known.length
+                ? `Fields with a lookup: ${known.map((k) => `"${k}"`).join(', ')}.`
+                : 'This operation has no lookup fields — author the value as a plain string.'));
+    }
+    return makeBuilder(bearing.nodeType, b, spec);
+}
+/**
+ * The recorded id for a token, or `undefined`.
+ *
+ * @param token - The unresolved lookup.
+ * @param resolutions - Everything `prepare --resolve` has recorded.
+ * @returns The connector-facing id, when this exact `(nodeType, field, by, value)` was resolved.
+ */
+export function resolvedValue(token, resolutions) {
+    const { nodeType, field, by, value } = token.__lookup;
+    return resolutions[lookupKey(nodeType, field, by, value)]?.value;
+}
+/**
+ * The message for a lookup nothing has resolved — the command that fixes it.
+ *
+ * A missing resolution is the same class of error as a missing schema, and it
+ * reads the same way on purpose: name the thing, then print the one command.
+ *
+ * @param token - The unresolved lookup.
+ * @returns A diagnostic whose last line can be pasted into a shell.
+ */
+export function unresolvedLookupMessage(token) {
+    const { nodeType, field, by, value } = token.__lookup;
+    // Event tokens carry the role segment (`uipath.connector.event.<key>.<event>`);
+    // the prepare command takes the bare `<key> <event>` either way.
+    const rest = nodeType.replace(/^uipath\.connector\.(?:trigger\.|event\.)?/, '');
+    const dot = rest.lastIndexOf('.');
+    const key = dot > 0 ? rest.slice(0, dot) : rest;
+    const action = dot > 0 ? rest.slice(dot + 1) : rest;
+    // Spelled for whoever is driving. This used to hard-code `npx flow-sdk`
+    // because `uip maestro registry` offered help/path/pull/search only
+    // (@uipath/cli 1.201.0-preview.115). It carries `prepare` as of 1.202, so the
+    // hard-coding now sends a `uip` user to a different binary than the one in
+    // their hand — the same detour the old note said cost an eval agent four
+    // tool calls, pointing the other way (#695).
+    return (`input "${field}" is an unresolved lookup (${by}=${JSON.stringify(value)}). ` +
+        `Compile does not make network calls, so the value has to be resolved first:\n` +
+        `  ${prepareCommand(key, action)} \\\n` +
+        `    --resolve ${field}:${by}=${String(value)}`);
+}
+// ─── Classification, mirroring `_lookups.py` ─────────────────────────────────
+//
+// The generator decides which fields get a helper; `check` has to agree, or it
+// tells an author to call a `.by*` that was never emitted. The rules are three
+// lines, so they are restated here rather than shipped as data — but they are
+// restated ONCE, in this function, and both `check` and the compile path read
+// it. The invariant-collection ledger travels as data because it is a list
+// somebody curated, not a rule.
+/** A `reference` block whose "resolution" would return the value it was given. */
+function isIdentityLookup(reference) {
+    const names = reference.lookupNames ?? [];
+    return names.length === 1 && names[0] === reference.lookupValue;
+}
+/**
+ * The {@link LookupSpec} for one field, or `undefined` when it earns no helper.
+ *
+ * @param reference - The field's raw registry `reference` block.
+ * @param invariant - `objectName`s the ledger declares connector-invariant.
+ * @returns The spec a `.by*` helper would be generated from, or `undefined`.
+ */
+export function lookupSpecOf(reference, invariant = new Set()) {
+    if (!reference?.lookupValue)
+        return undefined;
+    if (isIdentityLookup(reference))
+        return undefined;
+    if (reference.objectName && invariant.has(reference.objectName))
+        return undefined;
+    const by = reference.lookupNames ?? [];
+    const aliases = {};
+    const counts = new Map();
+    for (const name of by) {
+        const alias = byAlias(name);
+        if (alias)
+            counts.set(alias, (counts.get(alias) ?? 0) + 1);
+    }
+    for (const name of by) {
+        const alias = byAlias(name);
+        if (alias && counts.get(alias) === 1)
+            aliases[alias] = name;
+    }
+    return {
+        ...(reference.objectName ? { objectName: reference.objectName } : {}),
+        path: reference.path ?? '',
+        by,
+        value: reference.lookupValue,
+        aliases,
+        strategy: reference.dependsOn?.length
+            ? 'dependent'
+            : reference.filterPattern ? 'filter'
+                : reference.childPath ? 'tree'
+                    : 'scan',
+        ...(reference.dependsOn?.length ? { dependsOn: reference.dependsOn } : {}),
+    };
+}
+/** `profile.email` -> `byEmail`; the last dotted segment, camelised. */
+function byAlias(lookupName) {
+    const last = lookupName.split('.').pop() ?? '';
+    const words = last.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    if (words.length === 0)
+        return '';
+    return 'by' + words.map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+}
+/**
+ * Refuse a lookup token where the family cannot resolve one.
+ *
+ * `lookup()` is a FLOW surface today: only `serialize.ts` substitutes a
+ * recorded resolution, and only `check.ts` reports an unresolved one. Case and
+ * BPMN pass connector input values straight into their emitted payload, so a
+ * token reaching either one is embedded verbatim — a `.case` carrying
+ * `{"__lookup": {…}}` where the connector expects an id.
+ *
+ * That is silent wrongness, which is the failure this whole surface exists to
+ * remove; emitting it from the tool that removes it would be the worst possible
+ * outcome. Until Case and BPMN read `resolutions.json` too, they refuse the
+ * token and say so.
+ *
+ * @param value - A connector input value.
+ * @param family - The authoring family, for the message.
+ * @param field - The input name, for the message.
+ * @throws If `value` is an unresolved {@link LookupToken}.
+ */
+export function refuseLookupToken(value, family, field) {
+    if (!isLookupToken(value))
+        return;
+    const { nodeType, by, value: wanted } = value.__lookup;
+    throw new Error(`${family}: input "${field}" is a lookup(), which ${family} cannot resolve — ` +
+        `only Flow reads connectors-local/resolutions.json today, so this would be ` +
+        `emitted as a raw token where the connector expects an id.\n` +
+        `Resolve it first and pass the value:\n` +
+        `  ${prepareCommand()} ${nodeType.replace(/^uipath\.connector\.(?:trigger\.|event\.)?/, '').replace(/\.([^.]+)$/, ' $1')} \\\n` +
+        `    --resolve ${field}:${by}=${String(wanted)}\n` +
+        `then read the id out of connectors-local/resolutions.json.`);
+}

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

@@ -0,0 +1,234 @@
+/**
+ * Definition-backed node base classes — the public extension surface.
+ *
+ * The built-in factories (`http()`, `script()`, `scheduled()`, …) cover the
+ * node families the SDK ships typed helpers for. Everything else the platform
+ * can validly express — a less-common OOTB node, a tenant-specific registry
+ * definition — is authorable by subclassing {@link FlowAction} or
+ * {@link FlowTrigger} and returning a {@link NodeContribution}: an exact
+ * definition reference plus the semantic inputs. The shared serializer keeps
+ * ownership of everything structural (instance ids, `typeVersion`, definition
+ * deduplication, edges, variables), so an extension cannot bypass the file's
+ * invariants.
+ *
+ * {@link rawNode} is the same contract without the subclass: it carries a
+ * definition and its manifest verbatim for a node type the SDK has no factory
+ * for. It is not a raw-JSON escape hatch — the serializer still owns every
+ * structural field, and the manifest must be an exact copy of one the platform
+ * serves.
+ *
+ * Parity reference: `docs/FLOW_PARITY.md`.
+ */
+export interface ContributionDiagnostic {
+    /** Stable machine-readable code, SCREAMING_SNAKE by convention. */
+    code: string;
+    /** Human-readable, single-sentence problem statement. */
+    message: string;
+    /** `error` blocks compilation; `warning` reports and continues. */
+    severity: 'error' | 'warning';
+}
+/**
+ * An exact reference to the node definition a contribution compiles against.
+ *
+ * @remarks
+ * All three forms are exact: `version` names one definition, and no form means
+ * "latest". `bundled` resolves from the SDK's own `core-definitions.json`;
+ * `library` resolves from the connector library supplied at compile time;
+ * `snapshot` carries a validated Workbench/registry manifest in memory — it is
+ * an exact copy of a real definition, not permission to invent one.
+ */
+export type DefinitionReference = {
+    /** Resolve from the SDK's bundled core definitions. */
+    source: 'bundled';
+    /** The definition's `nodeType`, e.g. `'core.logic.delay'`. */
+    nodeType: string;
+    /** The exact definition version; also becomes the node's `typeVersion`. */
+    version: string;
+} | {
+    /** Resolve from the connector library supplied at compile time. */
+    source: 'library';
+    /** The definition's `nodeType`. */
+    nodeType: string;
+    /** The exact definition version; also becomes the node's `typeVersion`. */
+    version: string;
+} | {
+    /** Carry an exact registry/Workbench definition in memory. */
+    source: 'snapshot';
+    /** The definition's `nodeType`; must equal `manifest.nodeType`. */
+    nodeType: string;
+    /** The exact definition version; must equal `manifest.version`. */
+    version: string;
+    /** The complete node manifest, exactly as the platform serves it. */
+    manifest: unknown;
+};
+/**
+ * What the serializer tells a contributor before asking for its contribution.
+ */
+export interface ContributionContext {
+    /**
+     * The exact definition version the author requested on the node-producing
+     * builder method, if any. A contributor that supports several versions must
+     * return a {@link DefinitionReference} with this exact version or throw;
+     * substituting its own default for an explicit request is forbidden.
+     */
+    requestedVersion?: string;
+}
+/**
+ * A resource binding a contribution hoists to the flow's top-level `bindings`
+ * array — the shape the `.flow` format persists.
+ */
+export interface BindingContribution {
+    /** Unique binding id within the flow. */
+    id: string;
+    /** The binding's display name. */
+    name: string;
+    /** Binding value type, e.g. `'string'`. */
+    type: string;
+    /** Bound resource kind: `'connection'`, `'process'`, `'queue'`, … */
+    resource: string;
+    /** The key the platform resolves the resource by. */
+    resourceKey: string;
+    /** Optional default value. */
+    default?: string;
+    /** Which attribute of the resource the binding reads. */
+    propertyAttribute?: string;
+    /** Optional resource sub-type discriminator. */
+    resourceSubType?: string;
+}
+/**
+ * One validated construct, returned by {@link FlowNode.contribute}.
+ *
+ * @remarks
+ * A contribution is NOT a serialized node: the serializer owns ids, labels,
+ * `typeVersion`, edge wiring, and definition deduplication. The contributor
+ * supplies author intent — which definition, which inputs — and nothing else.
+ */
+export interface NodeContribution {
+    /** The exact definition this node compiles against. */
+    definition: DefinitionReference;
+    /**
+     * The node's `inputs`. Values may be `Expr` instances; the serializer
+     * renders them with the same expression pipeline the built-in factories use.
+     */
+    inputs?: Record<string, unknown>;
+    /**
+     * Overrides for the node's `outputs` beyond what the definition's
+     * `outputDefinition` declares. Rarely needed; most contributions omit it.
+     */
+    outputs?: Record<string, unknown>;
+    /** Resource bindings to hoist into the flow's `bindings` array. */
+    bindings?: BindingContribution[];
+}
+/**
+ * The abstract root of every definition-backed node the builder can place.
+ *
+ * @remarks
+ * Do not extend this class directly — extend {@link FlowAction},
+ * {@link FlowTrigger}, or {@link FlowResource}, which fix the `role`.
+ * The built-in factory results are instances of these classes too, but they
+ * are lowered by the serializer's built-in paths; only custom subclasses have
+ * their {@link FlowNode.contribute | contribute} called.
+ */
+export declare abstract class FlowNode<TOutputs = unknown> {
+    /**
+     * Type-only phantom carrying what the node publishes; never set at runtime.
+     * It exists so a future typed `out()` can read a subclass's output shape.
+     */
+    readonly __outputs?: TOutputs;
+    /** Where this node may appear: a step, a trigger, or an attached resource. */
+    abstract readonly role: 'action' | 'trigger' | 'resource';
+    /**
+     * Produce this node's validated construct. Called once per placement during
+     * compilation, only for custom subclasses — built-in factory results are
+     * lowered by the serializer directly and never reach this method.
+     *
+     * @param context - What the serializer knows about this placement, including
+     *   any exact `version` the author requested on the builder method.
+     * @returns The exact definition reference and semantic inputs to compile.
+     */
+    abstract contribute(context: ContributionContext): NodeContribution;
+    /**
+     * Report node-specific diagnostics during `check`. The default reports
+     * nothing; override to add family-specific rules.
+     *
+     * @returns Diagnostics to merge into the flow's check results.
+     */
+    diagnostics(): ContributionDiagnostic[];
+}
+/**
+ * A node placed as a step — pass an instance to `.step(name, …)`.
+ */
+export declare abstract class FlowAction<TOutputs = unknown> extends FlowNode<TOutputs> {
+    /** Always `'action'` for a step-placed node. */
+    get role(): 'action';
+}
+/**
+ * A node that starts the flow — pass an instance to `.trigger(…)`.
+ */
+export declare abstract class FlowTrigger<TPayload = unknown> extends FlowNode<TPayload> {
+    /** Always `'trigger'` for a flow-starting node. */
+    get role(): 'trigger';
+}
+/**
+ * A node attached to another semantic node — an inline agent's tool, context,
+ * memory, or escalation. Not accepted by `.step()`.
+ */
+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.
+ *
+ * @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

@@ -0,0 +1,158 @@
+/**
+ * Definition-backed node base classes — the public extension surface.
+ *
+ * The built-in factories (`http()`, `script()`, `scheduled()`, …) cover the
+ * node families the SDK ships typed helpers for. Everything else the platform
+ * can validly express — a less-common OOTB node, a tenant-specific registry
+ * definition — is authorable by subclassing {@link FlowAction} or
+ * {@link FlowTrigger} and returning a {@link NodeContribution}: an exact
+ * definition reference plus the semantic inputs. The shared serializer keeps
+ * ownership of everything structural (instance ids, `typeVersion`, definition
+ * deduplication, edges, variables), so an extension cannot bypass the file's
+ * invariants.
+ *
+ * {@link rawNode} is the same contract without the subclass: it carries a
+ * definition and its manifest verbatim for a node type the SDK has no factory
+ * for. It is not a raw-JSON escape hatch — the serializer still owns every
+ * structural field, and the manifest must be an exact copy of one the platform
+ * serves.
+ *
+ * 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';
+/**
+ * The abstract root of every definition-backed node the builder can place.
+ *
+ * @remarks
+ * Do not extend this class directly — extend {@link FlowAction},
+ * {@link FlowTrigger}, or {@link FlowResource}, which fix the `role`.
+ * The built-in factory results are instances of these classes too, but they
+ * are lowered by the serializer's built-in paths; only custom subclasses have
+ * their {@link FlowNode.contribute | contribute} called.
+ */
+export class FlowNode {
+    /**
+     * Report node-specific diagnostics during `check`. The default reports
+     * nothing; override to add family-specific rules.
+     *
+     * @returns Diagnostics to merge into the flow's check results.
+     */
+    diagnostics() {
+        return [];
+    }
+}
+/**
+ * A node placed as a step — pass an instance to `.step(name, …)`.
+ */
+export class FlowAction extends FlowNode {
+    /** Always `'action'` for a step-placed node. */
+    get role() {
+        return 'action';
+    }
+}
+/**
+ * A node that starts the flow — pass an instance to `.trigger(…)`.
+ */
+export class FlowTrigger extends FlowNode {
+    /** Always `'trigger'` for a flow-starting node. */
+    get role() {
+        return 'trigger';
+    }
+}
+/**
+ * A node attached to another semantic node — an inline agent's tool, context,
+ * memory, or escalation. Not accepted by `.step()`.
+ */
+export class FlowResource extends FlowNode {
+    /** Always `'resource'` for an attached node. */
+    get role() {
+        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.
+ *
+ * @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; `compile` throws it (see {@link contribute}). */
+    diagnostics() {
+        const refusal = connectorRawNodeRefusal(this.spec.nodeType);
+        return refusal ? [{ code: 'RAW_NODE_CONNECTOR', severity: 'error', message: refusal }] : [];
+    }
+    contribute(context) {
+        // compile does not run diagnostics(); refuse here too so the escape hatch
+        // cannot emit an unconfigured connector node.
+        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 } : {}),
+        };
+    }
+}