@uipath/maestro-builder-sdk 6.21.2 → 6.23.0

package/dist/nodes/ai-patterns/flow/node-type.js

@@ -0,0 +1,106 @@
+/**
+ * The two AI-pattern node types: `uipath.pattern.deep-rag` (Summarize) and
+ * `uipath.pattern.batch-transform`, each bundled at 1.0. Moved from
+ * serialize.ts / decompile.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md;
+ * serialized output and printed source unchanged.
+ */
+import { Expr } from '../../../core/expr.js';
+/** A value as the author wrote it: an expression back to an Expr, a literal string as itself, any other JSON as is. */
+function lifted(raw, ctx) {
+    const text = Array.isArray(raw) ? undefined : ctx.sourceText(raw);
+    if (text === undefined)
+        return raw;
+    return text.startsWith('=js:') ? ctx.expr(text) : text;
+}
+/** A spec value as source: an Expr as the helper an author writes, `undefined` as itself, anything else as data. */
+function printed(v, ctx) {
+    if (v === undefined)
+        return 'undefined';
+    return v instanceof Expr ? ctx.value(v) : ctx.json(v);
+}
+// Neither node carries a node-level `model`: both are `bpmn:ServiceTask`s whose
+// `serviceType` the platform resolves from `definitions[]`, and every deployed
+// instance of either carries none — v1's own structural checker fails a flow
+// that has one. The resource model stays on the DEFINITION only, as it does for
+// the published families. Per call (`model: 'omit'`), so a `rawNode` of either
+// type keeps what it has always written.
+const summarizeType = {
+    kind: 'summarize', typeName: 'uipath.pattern.deep-rag', version: '1.0', factory: 'summarize', definition: 'bundled',
+    rawNode: { factory: 'summarize()' },
+    // Each field is written under the NODE's own name, so the surface and the
+    // emitted file read alike.
+    serialize: ({ inputs }, ctx) => ({
+        model: 'omit',
+        inputs: {
+            attachment: ctx.render(inputs.attachment),
+            prompt: ctx.render(inputs.prompt),
+            returnCitations: inputs.returnCitations ?? false,
+        },
+        port: 'output',
+    }),
+    deserialize: (node, ctx) => {
+        const i = (node.inputs ?? {});
+        return {
+            kind: 'summarize',
+            inputs: {
+                attachment: lifted(i.attachment, ctx),
+                prompt: lifted(i.prompt, ctx),
+                // The flag defaults to false in the emitted node; only `true` was authored.
+                ...(ctx.plainValue(i.returnCitations) === true ? { returnCitations: true } : {}),
+            },
+        };
+    },
+    print: ({ inputs }, ctx) => ({
+        factory: 'summarize',
+        options: [
+            ['attachment', printed(inputs.attachment, ctx)],
+            ['prompt', printed(inputs.prompt, ctx)],
+            ['returnCitations', inputs.returnCitations === true ? 'true' : undefined],
+        ],
+    }),
+    // Deliberately none: references in the prompt, the attachment and the columns are not checked.
+    expressions: () => [],
+    output: () => ({ kind: 'opaque' }),
+};
+const batchTransformType = {
+    kind: 'batchTransform', typeName: 'uipath.pattern.batch-transform', version: '1.0', factory: 'batchTransform',
+    definition: 'bundled',
+    rawNode: { factory: 'batchTransform()' },
+    serialize: ({ inputs }, ctx) => ({
+        model: 'omit',
+        inputs: {
+            attachment: ctx.render(inputs.attachment),
+            prompt: ctx.render(inputs.prompt),
+            enableWebSearchGrounding: inputs.enableWebSearchGrounding ?? false,
+            // Rendered per column, so an expression in a description renders like every other input.
+            outputColumns: inputs.outputColumns.map((c) => Object.fromEntries(Object.entries(c).map(([k, v]) => [k, ctx.render(v)]))),
+        },
+        port: 'output',
+    }),
+    deserialize: (node, ctx) => {
+        const i = (node.inputs ?? {});
+        const cols = Array.isArray(i.outputColumns) ? i.outputColumns : [];
+        return {
+            kind: 'batchTransform',
+            inputs: {
+                attachment: lifted(i.attachment, ctx),
+                prompt: lifted(i.prompt, ctx),
+                outputColumns: cols.map((c) => ({ name: lifted(c.name, ctx), description: lifted(c.description, ctx) })),
+                ...(ctx.plainValue(i.enableWebSearchGrounding) === true ? { enableWebSearchGrounding: true } : {}),
+            },
+        };
+    },
+    print: ({ inputs }, ctx) => ({
+        factory: 'batchTransform',
+        options: [
+            ['attachment', printed(inputs.attachment, ctx)],
+            ['prompt', printed(inputs.prompt, ctx)],
+            ['outputColumns', `[${inputs.outputColumns.map((c) => `{ name: ${printed(c.name, ctx)}, description: ${printed(c.description, ctx)} }`).join(', ')}]`],
+            ['enableWebSearchGrounding', inputs.enableWebSearchGrounding === true ? 'true' : undefined],
+        ],
+    }),
+    // Deliberately none, as for Summarize.
+    expressions: () => [],
+    output: () => ({ kind: 'opaque' }),
+};
+export const aiPatternNodeTypes = [summarizeType, batchTransformType];

package/dist/nodes/ai-patterns/flow/spec.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The AI-pattern family's authoring types (`uipath.pattern.deep-rag`,
+ * `uipath.pattern.batch-transform`), and their kinds' entries in
+ * `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md.
+ */
+import type { Expr } from '../../../core/expr.js';
+export interface SummarizeInputs {
+    /**
+     * The document to summarize — a whole **Flow Attachment** object
+     * (`{ ID, FullName, MimeType, Metadata }`), not a path, id or URL.
+     *
+     * In practice that is a `file`-typed flow input:
+     *
+     * ```ts
+     * flow('SummarizeDemo')
+     *   .input({ documentFile: types.file })
+     *   .step('summarizeContract', summarize({ attachment: input('documentFile'), … }))
+     * ```
+     *
+     * `out('start', 'documentFile')` is the same value written the way the CANVAS
+     * writes it (`$vars.start.output.documentFile`, resolved through the input's
+     * `triggerNodeId` binding). Both forms run — measured on the real service —
+     * so prefer whichever the task asks for; `out('start', …)` is what a
+     * designer-made flow looks like.
+     *
+     * The service reads the file's CONTENT, and refuses one it cannot treat as a
+     * document: a PDF summarizes, a plain `.txt` comes back
+     * `[460005] … "No valid files to use for Summarization."`
+     */
+    attachment: Expr;
+    /** What the summary should cover, e.g. `'Write a 5-bullet executive summary…'`. */
+    prompt: string | Expr;
+    /**
+     * Ask the service for per-claim citations. Each is
+     * `{ Ordinal, PageNumber, Source, Reference }` and lands in
+     * `out('<step>', 'content.Citations')`. Defaults to `false`.
+     */
+    returnCitations?: boolean;
+}
+/** One column Batch Transform appends to the CSV. */
+export interface OutputColumn {
+    /** The new column's header, e.g. `'Category'`. */
+    name: string;
+    /** What the model should put in it, e.g. `'One of: Utility, Software, Travel, Other'`. */
+    description: string;
+}
+export interface BatchTransformInputs {
+    /**
+     * The CSV to enrich — a whole **Flow Attachment** object, same shape and same
+     * two ways of referencing it as {@link SummarizeInputs.attachment}.
+     */
+    attachment: Expr;
+    /** How to process each row, e.g. `'Classify each row and write a one-line summary.'`. */
+    prompt: string | Expr;
+    /**
+     * The columns to add, in order. The node's own field name — an array of
+     * `{ name, description }`, one per new column.
+     */
+    outputColumns: OutputColumn[];
+    /** Let the model use web search while transforming. Defaults to `false`. */
+    enableWebSearchGrounding?: boolean;
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link summarize} builds. */
+        summarize: {
+            inputs: SummarizeInputs;
+        };
+        /** The spec {@link batchTransform} builds. */
+        batchTransform: {
+            inputs: BatchTransformInputs;
+        };
+    }
+}

package/dist/nodes/ai-patterns/flow/spec.js

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

package/dist/nodes/http/flow/check.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The HTTP family's rules. Moved from check.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; codes and messages unchanged.
+ */
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { OutputPathRead } from '../../../core/nodes/node-type.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+import type { HttpInputs } from './spec.js';
+export declare const HTTP_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * The two http settings every deployed request node carries.
+ *
+ * Both definitions declare the defaults (`timeout: 'PT15M'`, `retryCount: 0`), so
+ * omitting them is safe and is what ~99% of deployed nodes do. What is NOT safe
+ * is writing them in a form the platform cannot read: an unparseable duration is
+ * not a shorter timeout, it is a value the request node fails to configure with,
+ * and nothing downstream of `check` would say so in the author's own vocabulary.
+ */
+export declare function checkHttp(inputs: HttpInputs, ctx: FlowCheckContext): void;
+/**
+ * Every node-local rule of an `http()` step, in the order check.ts ran them: the
+ * request settings, a managed step's binding labels, then the response branches.
+ */
+export declare function checkHttpStep(inputs: HttpInputs, ctx: FlowCheckContext): void;
+/**
+ * A read of an `http()` step's result.
+ *
+ * The response is an envelope — `{ body, statusCode, headers }` — and `returns`
+ * declares the parsed JSON body's top-level fields, so a declared field is read
+ * at `output.body.<field>` (`out('<step>', 'body.<field>')`). That nesting is the
+ * one thing this family does not share with the process families, and it is
+ * exactly where flow-builder-sdk#850's run went wrong: a branch kept reading
+ * `output.currentDayForecast…` (the Azure Maps connector's path) after the step
+ * became an Open-Meteo `http()`, passed `check` and `validate`, and faulted at
+ * `flow debug` as `[400302]`.
+ */
+export declare function checkHttpRead({ node: name, field, rest, reader: step }: OutputPathRead, spec: HttpInputs | undefined, report: (code: string, message: string, suggestion?: string) => void): void;
+/**
+ * `.onError` after a plain `core.action.http` node. Two separate facts about a
+ * PLAIN http step, both measured, both fatal to a handler there:
+ *
+ *  1. a 4xx/5xx does not FAIL the node — it completes carrying `statusCode`,
+ *     so the handler only ever runs on a transport failure (DNS, refused,
+ *     timeout);
+ *  2. when it does run there is nothing to read. `core.action.http@1.0.0` and
+ *     the `@1.3` that `uip maestro flow migrate` upgrades it to both publish
+ *     `<step>.error = true` and leave `<step>.output` null — no envelope
+ *     anywhere, unlike every other family. `validate` still says Valid.
+ *
+ * So this stays an error, and says the second part too: an author who reads
+ * the old message ("use the managed node if statuses must route") could
+ * reasonably conclude a transport-failure handler is fine as it is. check.ts
+ * reports the same refusal for a custom node built on the plain definition.
+ */
+export declare function plainHttpOnErrorMessage(stepName: string): {
+    message: string;
+    suggestion: string;
+};

package/dist/nodes/http/flow/check.js

@@ -0,0 +1,248 @@
+import { nearestName } from '../../../core/edit-distance.js';
+export const HTTP_DIAGNOSTICS = {
+    HTTP_V1_RETIRED: { severity: 'warning', summary: 'the plain node is retired on the tenant registry' },
+    HTTP_BINDING_REQUIRES_MANAGED: { severity: 'error', summary: 'connection settings on the standalone node' },
+    HTTP_MANAGED_BINDING_INCOMPLETE: { severity: 'error', summary: 'a managed connection without both connection and folder' },
+    HTTP_TARGET_CONNECTOR_EMPTY: { severity: 'error', summary: 'an empty targetConnector' },
+    HTTP_TARGET_CONNECTOR_REQUIRES_BINDING: { severity: 'error', summary: 'targetConnector without a connection and folder' },
+    HTTP_TIMEOUT_NOT_DURATION: { severity: 'error', summary: 'timeout is not an ISO-8601 duration' },
+    HTTP_RETRY_COUNT_INVALID: { severity: 'error', summary: 'retryCount is not a non-negative integer' },
+    HTTP_RETRY_COUNT_HIGH: { severity: 'warning', summary: 'retryCount above what a local replay exercises' },
+    HTTP_BRANCH_NAME: { severity: 'error', summary: 'a branch name that is not port-safe' },
+    HTTP_BRANCH_DUP: { severity: 'error', summary: 'a branch declared twice' },
+    HTTP_BRANCH_CONST: { severity: 'error', summary: 'a branch condition that is a constant' },
+    HTTP_READ_NOT_OUTPUT: { severity: 'error', summary: 'a read of the step outside `output`' },
+    HTTP_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'a read outside the response envelope or the declared body' },
+    HTTP_READ_WITHOUT_RETURNS: { severity: 'error', summary: 'a body field read with no `returns`' },
+    HTTP_ONERROR_V1: { severity: 'error', summary: '.onError() on the plain node' },
+};
+/**
+ * An ISO-8601 DURATION, which is what both http definitions declare `timeout` to
+ * be (`PT15M` by default) and what all 808 deployed http nodes carry.
+ *
+ * Deliberately the whole grammar rather than the `PT<n>[HMS]` subset the corpus
+ * happens to use: a too-narrow fence would refuse `P1D` or `PT1H30M`, which the
+ * platform parses perfectly well. What it does refuse is the family of things
+ * that are NOT durations at all and would reach the platform as an unparseable
+ * string — `'30s'`, `'30'`, `'PT'`, `'15 minutes'`.
+ */
+const ISO8601_DURATION = /^P(?!$)(\d+(?:\.\d+)?Y)?(\d+(?:\.\d+)?M)?(\d+(?:\.\d+)?W)?(\d+(?:\.\d+)?D)?(T(?!$)(\d+(?:\.\d+)?H)?(\d+(?:\.\d+)?M)?(\d+(?:\.\d+)?S)?)?$/;
+/**
+ * Where `check` stops treating a retry count as plainly reasonable. The
+ * platform's own ceiling is NOT measured, and the deployed corpus's largest
+ * author-set value is 3 — so above this we WARN. A too-narrow fence is fatal
+ * (it refuses something that works); a too-wide one costs nothing.
+ */
+const RETRY_COUNT_SOFT_MAX = 5;
+/**
+ * The two http settings every deployed request node carries.
+ *
+ * Both definitions declare the defaults (`timeout: 'PT15M'`, `retryCount: 0`), so
+ * omitting them is safe and is what ~99% of deployed nodes do. What is NOT safe
+ * is writing them in a form the platform cannot read: an unparseable duration is
+ * not a shorter timeout, it is a value the request node fails to configure with,
+ * and nothing downstream of `check` would say so in the author's own vocabulary.
+ */
+export function checkHttp(inputs, ctx) {
+    const step = ctx.step;
+    // `core.action.http` is retired on the platform side: after `registry pull
+    // --force` the tenant serves only `core.action.http.v2` (2.3), and a
+    // `registry get core.action.http` — bare or at the `@1.3` that `flow migrate`
+    // upgrades it to — answers "Node not found". It still compiles, validates and
+    // runs, which is why this is a warning and not an error: existing flows are
+    // not broken and `decompile` must keep round-tripping them.
+    //
+    // Moving to the managed node is not a rename. A plain step keeps a non-2xx on
+    // the SUCCESS path (`out(step,'statusCode')`); the managed one fails on it, so
+    // a status branch becomes an error handler reading the envelope's `status`.
+    //
+    // It is not a free upgrade either, and for a connection-less URL it is usually
+    // the wrong move (flow-builder-sdk#898). With no `connection` the managed node
+    // still goes through Integration Service: serialize emits the `uipath-uipath-http`
+    // connector on `ImplicitConnection`, so the request leaves from IS's SHARED
+    // egress. Measured on slack-weather-pipeline (3/3 runs): agents took the old
+    // `managed: true` hint, and Open-Meteo answered that egress 429 "Daily API
+    // request limit exceeded" while direct calls from the same box got 200. The
+    // plain node goes direct. So the hint only steers toward `managed: true` when
+    // the step was given connection settings; the two other real reasons to move
+    // (a binding, an `.onError()`) already fire as errors with that suggestion
+    // (HTTP_BINDING_REQUIRES_MANAGED, HTTP_ONERROR_V1).
+    if (inputs && !inputs.managed) {
+        const asked = inputs;
+        const wantsConnection = asked.connection !== undefined || asked.folder !== undefined
+            || asked.targetConnector !== undefined;
+        if (wantsConnection) {
+            ctx.report('HTTP_V1_RETIRED', `Step "${step}" emits core.action.http, which the tenant registry no longer serves (only `
+                + `core.action.http.v2). It sets Integration Service connection settings, which only the managed node `
+                + `can use. Moving to managed: true changes behaviour rather than just the node type: a non-2xx stops `
+                + `arriving on the success path with statusCode and fails the step instead, so a status branch becomes `
+                + `an .onError() handler reading err('${step}', 'status').`, `http({ url: …, managed: true, connection, folder })`);
+        }
+        else {
+            ctx.report('HTTP_V1_RETIRED', `Step "${step}" emits core.action.http, which the tenant registry no longer serves (only `
+                + `core.action.http.v2). It still compiles, validates and runs, and it calls the URL directly. For a URL `
+                + `that needs no Integration Service connection, keep managed: false. managed: true is not a drop-in `
+                + `replacement: even without a connection it sends the request through Integration Service's shared `
+                + `egress (rate limits there are shared, and public APIs can answer 429 where a direct call succeeds), `
+                + `and a non-2xx fails the step instead of arriving with statusCode. Switch only if the call needs an `
+                + `Integration Service connection or an .onError() handler.`);
+        }
+    }
+    const connection = inputs?.connection;
+    const folder = inputs?.folder;
+    const targetConnector = inputs?.targetConnector;
+    const bindingConfigured = connection !== undefined || folder !== undefined;
+    const targetConfigured = targetConnector !== undefined;
+    const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0;
+    if (!inputs?.managed && (bindingConfigured || targetConfigured)) {
+        ctx.report('HTTP_BINDING_REQUIRES_MANAGED', `Step "${step}" supplies Integration Service connection settings to the standalone HTTP node. `
+            + `Only the managed node can use connection, folder, or targetConnector.`, `managed: true`);
+    }
+    else if (inputs?.managed && bindingConfigured && (!nonEmpty(connection) || !nonEmpty(folder))) {
+        ctx.report('HTTP_MANAGED_BINDING_INCOMPLETE', `Managed HTTP step "${step}" must name both a non-empty \`connection\` and \`folder\`. The platform `
+            + `needs the pair to resolve the Integration Service connection at runtime.`, `connection: 'http', folder: 'shared'`);
+    }
+    if (inputs?.managed && targetConfigured && !nonEmpty(targetConnector)) {
+        ctx.report('HTTP_TARGET_CONNECTOR_EMPTY', `Managed HTTP step "${step}" sets an empty \`targetConnector\`; name its Integration Service connector key.`, `targetConnector: 'uipath-salesforce-slack'`);
+    }
+    else if (inputs?.managed && targetConfigured && !bindingConfigured) {
+        ctx.report('HTTP_TARGET_CONNECTOR_REQUIRES_BINDING', `Managed HTTP step "${step}" sets \`targetConnector\` without a connection and folder. `
+            + `A connector-specific fallback needs the binding pair whose authentication it reuses.`, `connection: 'slack', folder: 'shared'`);
+    }
+    const timeout = inputs?.timeout;
+    if (timeout !== undefined) {
+        if (typeof timeout !== 'string' || !ISO8601_DURATION.test(timeout.trim())) {
+            ctx.report('HTTP_TIMEOUT_NOT_DURATION', `Step "${step}" sets timeout to ${JSON.stringify(timeout)}, which is not an ISO-8601 duration. The `
+                + `platform reads this field as a duration string (both http definitions default it to "PT15M"), so a `
+                + `value it cannot parse configures no timeout at all.`, `timeout: 'PT30S'  // 30 seconds — also 'PT1M', 'PT15M', 'PT1H'`);
+        }
+    }
+    const retryCount = inputs?.retryCount;
+    if (retryCount !== undefined) {
+        if (typeof retryCount !== 'number' || !Number.isInteger(retryCount) || retryCount < 0) {
+            ctx.report('HTTP_RETRY_COUNT_INVALID', `Step "${step}" sets retryCount to ${JSON.stringify(retryCount)}. It is a count of RETRIES after the `
+                + `first attempt, so it must be a non-negative whole number — 0 (the definitions' default) means "try `
+                + `once", 2 means up to three attempts.`, `retryCount: 2`);
+        }
+        else if (retryCount > RETRY_COUNT_SOFT_MAX) {
+            ctx.report('HTTP_RETRY_COUNT_HIGH', `Step "${step}" asks for ${retryCount} retries. The local runtime clamps at ${RETRY_COUNT_SOFT_MAX} and `
+                + `the largest value in the deployed corpus is 3, so a local replay will not exercise what you wrote. `
+                + `The platform's own ceiling is not measured — this is a warning, not a refusal.`, `retryCount: ${RETRY_COUNT_SOFT_MAX}`);
+        }
+    }
+}
+/**
+ * Every node-local rule of an `http()` step, in the order check.ts ran them: the
+ * request settings, a managed step's binding labels, then the response branches.
+ */
+export function checkHttpStep(inputs, ctx) {
+    const step = ctx.step;
+    checkHttp(inputs, ctx);
+    // Only a complete pair: an empty half is HTTP_MANAGED_BINDING_INCOMPLETE, which
+    // serialize refuses before it resolves either name.
+    const pair = inputs;
+    const filled = (v) => typeof v === 'string' && v.trim() !== '';
+    if (pair?.managed && filled(pair.connection) && filled(pair.folder)) {
+        const target = pair.targetConnector;
+        ctx.bindingLabels(`managed http "${step}"`, pair, 
+        // The connector its CONNECTION belongs to: the target, not the wrapper.
+        { id: step, connector: typeof target === 'string' && target !== '' ? target : 'uipath-uipath-http' });
+    }
+    const seen = new Set();
+    for (const b of inputs?.branches ?? []) {
+        if (!/^[A-Za-z0-9_-]+$/.test(b.name)) {
+            ctx.report('HTTP_BRANCH_NAME', `HTTP branch ${JSON.stringify(b.name)} on "${step}" is not port-safe — use letters, digits, _ or - (it becomes the branch-<name> port).`);
+        }
+        if (seen.has(b.name)) {
+            ctx.report('HTTP_BRANCH_DUP', `HTTP branch ${JSON.stringify(b.name)} on "${step}" is declared twice.`);
+        }
+        seen.add(b.name);
+        if (b.condition.literal) {
+            ctx.report('HTTP_BRANCH_CONST', `HTTP branch ${JSON.stringify(b.name)} on "${step}" tests a constant — it would fire always or never. Reference the response, e.g. $vars.${step}.output.statusCode.`);
+        }
+    }
+}
+/**
+ * The fields every HTTP response carries at the top of `output`, whatever the
+ * API answered. `core.action.http`'s definition declares all three; the author's
+ * `returns` describes what is INSIDE `body`, never beside it.
+ */
+const HTTP_ENVELOPE_FIELDS = ['body', 'statusCode', 'headers'];
+/**
+ * A read of an `http()` step's result.
+ *
+ * The response is an envelope — `{ body, statusCode, headers }` — and `returns`
+ * declares the parsed JSON body's top-level fields, so a declared field is read
+ * at `output.body.<field>` (`out('<step>', 'body.<field>')`). That nesting is the
+ * one thing this family does not share with the process families, and it is
+ * exactly where flow-builder-sdk#850's run went wrong: a branch kept reading
+ * `output.currentDayForecast…` (the Azure Maps connector's path) after the step
+ * became an Open-Meteo `http()`, passed `check` and `validate`, and faulted at
+ * `flow debug` as `[400302]`.
+ */
+export function checkHttpRead({ node: name, field, rest, reader: step }, spec, report) {
+    if (field === undefined)
+        return; // `out('fetch')` — the whole response.
+    if (field === 'error')
+        return; // the failure envelope (managed http's error port).
+    if (field !== 'output') {
+        report('HTTP_READ_NOT_OUTPUT', `HTTP step "${name}" publishes its response under "output", but "$vars.${name}.${field}" `
+            + `(read in "${step}") asks for "${field}", which is undefined at run time.`, `out('${name}', 'body.<field>')`);
+        return;
+    }
+    const [top, inner] = rest.replace(/^\./, '').split('.');
+    if (!top)
+        return; // `$vars.<name>.output` — the whole envelope.
+    const declared = Object.keys(spec?.returns ?? {});
+    if (!HTTP_ENVELOPE_FIELDS.includes(top)) {
+        // The commonest form: a declared body field read one level too high.
+        const hoisted = declared.includes(top) ? top : undefined;
+        const nearest = hoisted ?? nearestName(top, declared);
+        report('HTTP_READ_UNKNOWN_FIELD', `"$vars.${name}.output.${top}" (read in "${step}") is not a field of HTTP step "${name}"'s `
+            + `response. An HTTP response publishes ${HTTP_ENVELOPE_FIELDS.map((f) => `"${f}"`).join(', ')}; `
+            + `the fields \`returns\` declares live under "body"`
+            + (hoisted ? `, so "${top}" is read as "$vars.${name}.output.body.${top}".` : '.')
+            + ` A read outside that shape resolves to undefined and faults a gateway at run time.`, nearest !== undefined ? `out('${name}', 'body.${nearest}')` : undefined);
+        return;
+    }
+    if (top !== 'body' || !inner)
+        return; // `statusCode`, `headers`, or the whole body.
+    if (declared.length === 0) {
+        report('HTTP_READ_WITHOUT_RETURNS', `"$vars.${name}.output.body.${inner}" (read in "${step}") reads a field of HTTP step "${name}"'s `
+            + `response body, but the step declares no \`returns\` — so the node carries no body schema and nothing `
+            + `can tell a real field from a typo. Only the API being called knows its body; declare the fields you read.`, `returns: { ${inner}: 'string' }`);
+        return;
+    }
+    if (declared.includes(inner))
+        return;
+    const nearest = nearestName(inner, declared);
+    report('HTTP_READ_UNKNOWN_FIELD', `HTTP step "${name}" declares no body field "${inner}" (read as "$vars.${name}.output.body.${inner}" `
+        + `in "${step}"). Its \`returns\` names: ${declared.join(', ')}. A read outside that set resolves to undefined.`, nearest !== undefined ? `out('${name}', 'body.${nearest}')` : undefined);
+}
+/**
+ * `.onError` after a plain `core.action.http` node. Two separate facts about a
+ * PLAIN http step, both measured, both fatal to a handler there:
+ *
+ *  1. a 4xx/5xx does not FAIL the node — it completes carrying `statusCode`,
+ *     so the handler only ever runs on a transport failure (DNS, refused,
+ *     timeout);
+ *  2. when it does run there is nothing to read. `core.action.http@1.0.0` and
+ *     the `@1.3` that `uip maestro flow migrate` upgrades it to both publish
+ *     `<step>.error = true` and leave `<step>.output` null — no envelope
+ *     anywhere, unlike every other family. `validate` still says Valid.
+ *
+ * So this stays an error, and says the second part too: an author who reads
+ * the old message ("use the managed node if statuses must route") could
+ * reasonably conclude a transport-failure handler is fine as it is. check.ts
+ * reports the same refusal for a custom node built on the plain definition.
+ */
+export function plainHttpOnErrorMessage(stepName) {
+    return {
+        message: `Step "${stepName}" handles errors on a plain http() request. A 4xx/5xx does NOT fail that node — it `
+            + `completes with out('${stepName}', 'statusCode') set — so the handler runs only on a transport failure, `
+            + `and when it does the node publishes no failure envelope at all (measured: "<step>.error" is the boolean `
+            + `true and "<step>.output" is null, in 1.0.0 and in the 1.3 flow migrate produces), so err() has nothing `
+            + `to read. The managed node is the one whose failures route AND carry the envelope.`,
+        suggestion: `http({ url: …, managed: true })`,
+    };
+}

package/dist/nodes/http/flow/factories.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The HTTP factory, `http()`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports it.
+ */
+import { type ActionSpec } from '../../../core/actions.js';
+import type { HttpInputs } from './spec.js';
+/**
+ * Declare an HTTP request action, explicitly choosing standalone or managed.
+ *
+ * @param inputs - The request: `url`, `method`, `body`, the response fields you
+ * read back via `returns`, and the `managed` node choice.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function http(inputs: HttpInputs): ActionSpec;

package/dist/nodes/http/flow/factories.js

@@ -0,0 +1,20 @@
+/**
+ * The HTTP factory, `http()`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports it.
+ */
+import { builtinActionSpec } from '../../../core/actions.js';
+/**
+ * Declare an HTTP request action, explicitly choosing standalone or managed.
+ *
+ * @param inputs - The request: `url`, `method`, `body`, the response fields you
+ * read back via `returns`, and the `managed` node choice.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function http(inputs) {
+    if (typeof inputs.managed !== 'boolean') {
+        throw new Error('http() requires managed: true or managed: false because they emit different platform nodes. '
+            + 'Use true for Managed HTTP Request/core.action.http.v2 or when non-2xx statuses must reach .onError(); '
+            + 'use false for the standalone core.action.http node.');
+    }
+    return builtinActionSpec({ kind: 'http', inputs });
+}

package/dist/nodes/http/flow/family.d.ts

@@ -0,0 +1,8 @@
+/** The HTTP node family, as flow-node-registry.ts lists it: `core.action.http` and `core.action.http.v2`. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const httpFlowFamily: FlowNodeFamily;
+/**
+ * The plain node's `.onError` refusal, for check.ts: a custom node built on the
+ * `core.action.http` definition gets the same answer as an `http()` step.
+ */
+export { plainHttpOnErrorMessage } from './check.js';

package/dist/nodes/http/flow/family.js

@@ -0,0 +1,13 @@
+import { HTTP_DIAGNOSTICS } from './check.js';
+import { httpNodeTypes } from './node-type.js';
+export const httpFlowFamily = {
+    id: 'http',
+    title: 'HTTP',
+    types: httpNodeTypes,
+    diagnostics: HTTP_DIAGNOSTICS,
+};
+/**
+ * The plain node's `.onError` refusal, for check.ts: a custom node built on the
+ * `core.action.http` definition gets the same answer as an `http()` step.
+ */
+export { plainHttpOnErrorMessage } from './check.js';

package/dist/nodes/http/flow/index.d.ts

@@ -0,0 +1,3 @@
+/** The HTTP family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/http/flow/index.js

@@ -0,0 +1,3 @@
+/** The HTTP family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

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

@@ -0,0 +1,7 @@
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+import type { HttpInputs } from './spec.js';
+export type HttpSpec = {
+    kind: 'http';
+    inputs: HttpInputs;
+};
+export declare const httpNodeTypes: FlowVersionedNodeType<HttpSpec>[];