@uipath/maestro-builder-sdk 6.18.10 → 6.20.0

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

@@ -0,0 +1,7 @@
+import { documentClassifyNodeType, DOCUMENT_DIAGNOSTICS, dynamicExtractNodeType } from './node-type.js';
+export const documentFlowFamily = {
+    id: 'document',
+    title: 'Document understanding',
+    types: [documentClassifyNodeType, dynamicExtractNodeType],
+    diagnostics: DOCUMENT_DIAGNOSTICS,
+};

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

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

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

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

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

@@ -0,0 +1,14 @@
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { FlowNodeType } from '../../../flow-node-type.js';
+import type { DocumentClassifyInputs, DynamicExtractInputs } from './spec.js';
+export type DocumentClassifySpec = {
+    kind: 'documentClassify';
+    inputs: DocumentClassifyInputs;
+};
+export type DynamicExtractSpec = {
+    kind: 'dynamicExtract';
+    inputs: DynamicExtractInputs;
+};
+export declare const DOCUMENT_DIAGNOSTICS: DiagnosticCatalog;
+export declare const documentClassifyNodeType: FlowNodeType<DocumentClassifySpec>;
+export declare const dynamicExtractNodeType: FlowNodeType<DynamicExtractSpec>;

package/dist/nodes/document/flow/node-type.js

@@ -0,0 +1,150 @@
+/**
+ * The two document node types: Document Classify (`uipath.document.classify@1.0`)
+ * and Dynamic Extract (`uipath.ixp.extract-document-builder@1.0.0`). Moved from
+ * serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, printed source,
+ * codes and messages unchanged.
+ *
+ * Not here: `ixpExtract()` (`uipath.ixp.<project type>`), whose type name comes
+ * from the model rather than being one fixed name, which the contract does not
+ * express yet.
+ */
+import { toExpr } from '../../../core/expr.js';
+import { jsonClone } from '../../../core/json-file.js';
+export const DOCUMENT_DIAGNOSTICS = {
+    DOC_NO_FILEREF: { severity: 'error', summary: 'no fileRef, so nothing to classify or extract from' },
+    EXTRACT_SCHEMA_SHAPE: { severity: 'error', summary: 'a Dynamic Extract schema that is not an object' },
+};
+function checkFileRef(inputs, verb, ctx) {
+    const fr = inputs.fileRef;
+    const empty = fr === undefined || fr === null || (typeof fr === 'string' && fr.trim() === '');
+    if (empty) {
+        ctx.report('DOC_NO_FILEREF', `"${ctx.step}" has no fileRef — nothing to ${verb}. Reference a file input or an upstream attachment.`);
+    }
+}
+/** The definition's `inputDefaults`, which both nodes spread first. */
+function defaults(typeName, version, ctx) {
+    return jsonClone((ctx.definition(typeName, version)?.inputDefaults) ?? {});
+}
+/** `fileRef`, as the lift reads it: `=js:` text as an Expr, anything else as text. */
+function liftFileRef(node, ctx) {
+    const fr = ctx.sourceText(node.inputs?.fileRef) ?? '';
+    return fr.startsWith('=js:') ? ctx.expr(fr) : fr;
+}
+/** `pageRange` when it is a non-empty string, as the lift reads it. */
+function liftPageRange(node) {
+    const p = node.inputs?.pageRange;
+    return typeof p === 'string' && p !== '' ? p : undefined;
+}
+export const documentClassifyNodeType = {
+    kind: 'documentClassify', typeName: 'uipath.document.classify', version: '1.0', factory: 'documentClassify',
+    definition: 'bundled', rawNode: { factory: 'documentClassify()' },
+    serialize: ({ inputs }, ctx) => {
+        const d = defaults('uipath.document.classify', '1.0', ctx);
+        // Classify follows the default envelope rules for fileRef (unlike the
+        // `uipath.ixp.*` extractors — see migrate's UNWRAPPED_INPUTS).
+        return {
+            inputs: {
+                ...d,
+                fileRef: ctx.render(toExpr(inputs.fileRef)),
+                ...(inputs.pageRange !== undefined ? { pageRange: inputs.pageRange } : {}),
+                ...(inputs.splitPages !== undefined ? { splitPages: inputs.splitPages } : {}),
+                ...(inputs.modelConfig !== undefined
+                    ? { modelConfig: { ...(d.modelConfig ?? {}), ...inputs.modelConfig } }
+                    : {}),
+            },
+        };
+    },
+    deserialize: (node, ctx) => {
+        const pageRange = liftPageRange(node);
+        const split = ctx.plainValue(node.inputs?.splitPages);
+        return {
+            kind: 'documentClassify',
+            inputs: {
+                fileRef: liftFileRef(node, ctx),
+                ...(pageRange !== undefined ? { pageRange } : {}),
+                ...(split === true ? { splitPages: true } : {}),
+            },
+        };
+    },
+    print: ({ inputs }, ctx) => ({
+        factory: 'documentClassify',
+        options: [
+            ['fileRef', ctx.value(inputs.fileRef)],
+            ['pageRange', inputs.pageRange !== undefined ? ctx.string(inputs.pageRange) : undefined],
+            ['splitPages', inputs.splitPages === true ? 'true' : undefined],
+        ],
+    }),
+    check: ({ inputs }, ctx) => checkFileRef(inputs, 'classify', ctx),
+    // check collected no expressions for this kind before the port; unchanged by it.
+    expressions: () => [],
+    output: () => ({ kind: 'opaque' }),
+};
+export const dynamicExtractNodeType = {
+    kind: 'dynamicExtract', typeName: 'uipath.ixp.extract-document-builder', version: '1.0.0', factory: 'dynamicExtract',
+    definition: 'bundled', rawNode: { factory: 'dynamicExtract()' },
+    serialize: ({ inputs }, ctx) => {
+        const d = defaults('uipath.ixp.extract-document-builder', '1.0.0', ctx);
+        const m = inputs.model;
+        return {
+            inputs: {
+                ...d,
+                // The deployment identity Studio Web's panel destructures — both the
+                // nested `model` object and the flat mirrors the definition declares.
+                model: { modelName: m.modelName, folderKey: m.folderKey },
+                modelName: m.modelName,
+                folderKey: m.folderKey,
+                ...(m.projectId !== undefined ? { projectId: m.projectId } : {}),
+                ...(m.projectName !== undefined ? { projectName: m.projectName } : {}),
+                ...(m.folderName !== undefined ? { folderName: m.folderName } : {}),
+                ...(m.versionTag !== undefined ? { versionTag: m.versionTag } : {}),
+                // A `uipath.ixp.*` fileRef must stay a PLAIN `=js:` string — the
+                // platform reads it unwrapped (see migrate's UNWRAPPED_INPUTS).
+                fileRef: ctx.render(toExpr(inputs.fileRef)),
+                ...(inputs.pageRange !== undefined ? { pageRange: inputs.pageRange } : {}),
+                ...(inputs.modelConfig !== undefined
+                    ? { modelConfig: { ...(d.modelConfig ?? {}), ...inputs.modelConfig } }
+                    : {}),
+                ...(inputs.schema !== undefined ? { schemaDocument: inputs.schema } : {}),
+                // The definition's model declares `source: true`: the platform mints a
+                // stable storage slot per instance; omit it and the node validates then
+                // faults. Deterministic, like every other minted identity here.
+                source: ctx.mint('source'),
+            },
+            // IxP instances must NOT carry the manifest's model block — the slim
+            // { type, serviceType } lives only in definitions[] (product validate
+            // rejects a node-level copy). Per call, not `nodeModel`: a rawNode of this
+            // type keeps the model it always had.
+            model: 'omit',
+        };
+    },
+    deserialize: (node, ctx) => {
+        const pageRange = liftPageRange(node);
+        const schema = node.inputs?.schemaDocument;
+        return {
+            kind: 'dynamicExtract',
+            inputs: {
+                fileRef: liftFileRef(node, ctx),
+                ...(schema !== undefined ? { schema: schema } : {}),
+                ...(pageRange !== undefined ? { pageRange } : {}),
+            },
+        };
+    },
+    print: ({ inputs }, ctx) => ({
+        factory: 'dynamicExtract',
+        options: [
+            ['fileRef', ctx.value(inputs.fileRef)],
+            ['schema', inputs.schema !== undefined ? ctx.json(inputs.schema) : undefined],
+            ['pageRange', inputs.pageRange !== undefined ? ctx.string(inputs.pageRange) : undefined],
+        ],
+    }),
+    check: ({ inputs }, ctx) => {
+        checkFileRef(inputs, 'extract from', ctx);
+        if (inputs.schema !== undefined && (typeof inputs.schema !== 'object' || Array.isArray(inputs.schema))) {
+            ctx.report('EXTRACT_SCHEMA_SHAPE', `"${ctx.step}"'s schema must be an object (the inline extraction schema document).`);
+        }
+    },
+    // check collected no expressions for this kind before the port; unchanged by it.
+    expressions: () => [],
+    output: () => ({ kind: 'opaque' }),
+};

package/dist/nodes/document/flow/spec.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The document family's authoring types — Document Classify
+ * (`uipath.document.classify`) and Dynamic Extract
+ * (`uipath.ixp.extract-document-builder`) — 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 DocumentClassifyInputs {
+    /** The document to classify — a file reference (`input('file')`, `out('fetch', 'fileRef')`, …). */
+    fileRef: string | Expr;
+    /** Page range to classify, e.g. `'1-3'`. Omit for the whole document. */
+    pageRange?: string;
+    /** Split multi-document files into per-type page ranges. */
+    splitPages?: boolean;
+    /** Model configuration overrides; omit for the platform defaults (gemini_2_5_flash). */
+    modelConfig?: Record<string, unknown>;
+}
+export interface DynamicExtractInputs {
+    /** The document to extract from — a file reference. */
+    fileRef: string | Expr;
+    /**
+     * The IXP model deployment the extraction runs against. Dynamic Extract
+     * authors its SCHEMA inline, but execution still needs a model: Studio Web's
+     * panel destructures `modelName` and `folderKey`, and the platform rejects an
+     * instance without them.
+     */
+    model: {
+        /** The deployment's model name, e.g. `'invoiceixp-cef0d447-ixp'`. */
+        modelName: string;
+        /** Folder key (GUID) the deployment lives in. */
+        folderKey: string;
+        /** The IXP project's id (GUID). */
+        projectId?: string;
+        /** The IXP project's display name. */
+        projectName?: string;
+        /** Folder display name. */
+        folderName?: string;
+        /** Deployment version tag; omit for the live version. */
+        versionTag?: string;
+    };
+    /**
+     * The extraction schema (the node's inline taxonomy): a JSON-schema-shaped
+     * document describing the fields to extract. This is the Dynamic Extract
+     * node's defining input — authored inline rather than referencing a deployed
+     * IXP project (use {@link ixpExtract} for those).
+     */
+    schema?: Record<string, unknown>;
+    /** Page range to extract, e.g. `'1-3'`. Omit for the whole document. */
+    pageRange?: string;
+    /** Model configuration overrides; omit for the platform defaults. */
+    modelConfig?: Record<string, unknown>;
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link documentClassify} builds. */
+        documentClassify: {
+            inputs: DocumentClassifyInputs;
+        };
+        /** The spec {@link dynamicExtract} builds. */
+        dynamicExtract: {
+            inputs: DynamicExtractInputs;
+        };
+    }
+}

package/dist/nodes/document/flow/spec.js

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

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

@@ -0,0 +1,51 @@
+/**
+ * The placeholder factory, `mock()`. 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';
+/**
+ * Declare a PLACEHOLDER step — "a real node goes here later".
+ *
+ * @remarks
+ * A mock takes **no inputs and publishes nothing**. It is a marker on the canvas
+ * that keeps the graph wired and the flow deployable while one step is still
+ * missing — not a stub that returns test data. `out('extractInvoice')` is
+ * refused at compile time (`MOCK_HAS_NO_OUTPUT`) because it would read `null` at
+ * run time, always.
+ *
+ * Say what belongs there in the step's own name and in the label the canvas
+ * shows; the corpus's placeholders read like
+ * `"Extract Invoice Fields (mock — IxP model not yet published)"`.
+ *
+ * ### Why there are no arguments (convention #191 — the family contract)
+ *
+ * The platform's `core.logic.mock@1.0.0` declares **no `inputDefinition`** and one
+ * output whose `source` is the literal `"null"`. Measured over the 4,033 distinct
+ * archived `.flow` artifacts: **74 mock instances in 62 flows, and 0 carrying a
+ * fixture anywhere in the node** — 71 of them with `inputs: {}` or no `inputs`
+ * key. The 3 exceptions carry free-text `placeholder` / `_placeholder` keys the
+ * definition never declares, invented by agents on runs that scored 0.9 and 0.4.
+ *
+ * **This is NOT a local runner's `kind: 'mock'` test construct**, which returns a
+ * baked fixture. They are different things that share
+ * a name, and a `mock({ fixture })` surface would emit a node whose local
+ * behaviour and deployed behaviour disagree silently — see
+ * [#125](https://github.com/UiPath/flow-builder-sdk/issues/125). Nothing this SDK
+ * emits opens that channel: an SDK-authored mock publishes `null` locally,
+ * exactly as the platform does.
+ *
+ * @example
+ * **Hold a step's place until the real node exists**
+ * ```ts
+ * .step('extractInvoice', mock())      // ← swap for the IxP node once the project exists
+ * ```
+ *
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function mock(): ActionSpec;
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** A placeholder — no inputs, publishes nothing. See {@link mock}. */
+        mock: {};
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * The placeholder factory, `mock()`. 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 a PLACEHOLDER step — "a real node goes here later".
+ *
+ * @remarks
+ * A mock takes **no inputs and publishes nothing**. It is a marker on the canvas
+ * that keeps the graph wired and the flow deployable while one step is still
+ * missing — not a stub that returns test data. `out('extractInvoice')` is
+ * refused at compile time (`MOCK_HAS_NO_OUTPUT`) because it would read `null` at
+ * run time, always.
+ *
+ * Say what belongs there in the step's own name and in the label the canvas
+ * shows; the corpus's placeholders read like
+ * `"Extract Invoice Fields (mock — IxP model not yet published)"`.
+ *
+ * ### Why there are no arguments (convention #191 — the family contract)
+ *
+ * The platform's `core.logic.mock@1.0.0` declares **no `inputDefinition`** and one
+ * output whose `source` is the literal `"null"`. Measured over the 4,033 distinct
+ * archived `.flow` artifacts: **74 mock instances in 62 flows, and 0 carrying a
+ * fixture anywhere in the node** — 71 of them with `inputs: {}` or no `inputs`
+ * key. The 3 exceptions carry free-text `placeholder` / `_placeholder` keys the
+ * definition never declares, invented by agents on runs that scored 0.9 and 0.4.
+ *
+ * **This is NOT a local runner's `kind: 'mock'` test construct**, which returns a
+ * baked fixture. They are different things that share
+ * a name, and a `mock({ fixture })` surface would emit a node whose local
+ * behaviour and deployed behaviour disagree silently — see
+ * [#125](https://github.com/UiPath/flow-builder-sdk/issues/125). Nothing this SDK
+ * emits opens that channel: an SDK-authored mock publishes `null` locally,
+ * exactly as the platform does.
+ *
+ * @example
+ * **Hold a step's place until the real node exists**
+ * ```ts
+ * .step('extractInvoice', mock())      // ← swap for the IxP node once the project exists
+ * ```
+ *
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function mock() {
+    return builtinActionSpec({ kind: 'mock' });
+}

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

@@ -0,0 +1,3 @@
+/** The placeholder node family, as flow-node-registry.ts lists it: `core.logic.mock`. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const mockFlowFamily: FlowNodeFamily;

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

@@ -0,0 +1,7 @@
+import { mockNodeType } from './node-type.js';
+export const mockFlowFamily = {
+    id: 'mock',
+    title: 'Placeholder',
+    types: [mockNodeType],
+    diagnostics: { MOCK_HAS_NO_OUTPUT: { severity: 'error', summary: "a read of a placeholder's output" } },
+};

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

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

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * The placeholder node type, `core.logic.mock` (bundled 1.0.0 and 1.0). Moved
+ * from serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, codes and messages
+ * unchanged.
+ */
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+export type MockSpec = {
+    kind: 'mock';
+};
+export declare const mockNodeType: FlowVersionedNodeType<MockSpec>;

package/dist/nodes/mock/flow/node-type.js

@@ -0,0 +1,51 @@
+function mockAt(version) {
+    return {
+        kind: 'mock', typeName: 'core.logic.mock', version, factory: 'mock', definition: 'bundled',
+        rawNode: { factory: 'mock()' },
+        // A placeholder is a pure definition node: the definition supplies `model`
+        // and the single `output` (`source: "null"`), and there is nothing else to
+        // write. `inputs: {}` rather than an omitted key because that is what the
+        // vendored Studio-Web golden writes (`shared/sample-flows/new.flow`, all
+        // three of its mock nodes) and what 36 of the 74 archived instances carry.
+        //
+        // Nothing here can open a fixture channel: a runner that honours one looks
+        // for `fixture`/`output`/`value` in the node's `inputs`, and the factory
+        // takes no arguments, so `inputs` is always the empty object. That
+        // is the #125 fence, made unrepresentable rather than documented.
+        serialize: () => ({ inputs: {} }),
+        deserialize: () => ({ kind: 'mock' }),
+        // A `mock()` is a PLACEHOLDER: `core.logic.mock`'s definition declares one
+        // output whose `source` is the literal `"null"`, so the value is null at run
+        // time whatever the flow does. Unlike the other no-output rules, the node
+        // DOES declare an output slot — which is exactly why the read is silent: it
+        // resolves in the designer, it resolves in `variables.nodes`, and it hands
+        // the downstream step a null.
+        //
+        // WHY THIS RULE LIVES IN THE AUTHORING CHECKER rather than in a pass over the
+        // compiled artifact (convention #191). Reading a placeholder's output is the
+        // ARCHIVE's dominant idiom, not a rarity: 55 of the 62 archived mock-carrying
+        // artifacts do it — 110 read sites, 87 of them inside a script's body and 19
+        // in a decision's expression — and **39 of those 55 come from runs that
+        // scored 1.0**. That is an author writing the downstream code for the real
+        // node the placeholder stands in for, and a `.flow`-level rule refusing it
+        // would refuse the deployed corpus (lesson 47). An SDK author is in the
+        // other position: they wrote `mock()` here, in this file, and the SDK can
+        // say at compile time that the read is dead.
+        //   Measured 2026-08-02 over 4,033 distinct archived artifacts —
+        //   runs/flow-sdk-cleanup-2026-08-02/step0/mock-output-read-sites.txt.
+        // A placeholder carries no authored values.
+        expressions: () => [],
+        output: () => ({
+            kind: 'none',
+            code: 'MOCK_HAS_NO_OUTPUT',
+            message: ({ node, ref, reader }) => `Placeholder "${node}" publishes nothing, but "${ref}" reads it in "${reader}". `
+                + 'A mock() is a marker for a node that does not exist yet — its output is null at run time, always. '
+                + 'Keep the placeholder while the real node does not exist, and have the reader use a value you supply instead (a flow input, as example/ClaimScaffold.flow.ts does). '
+                + 'Replace the placeholder only with the real node, once `registry search` finds it; a script returning fixed values is not the real node.',
+        }),
+    };
+}
+export const mockNodeType = {
+    kind: 'mock', typeName: 'core.logic.mock', factory: 'mock', defaultVersion: '1.0.0',
+    versions: { '1.0.0': mockAt('1.0.0'), '1.0': mockAt('1.0') },
+};

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

@@ -0,0 +1,19 @@
+/**
+ * The Script family's rules. Moved verbatim 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 { FlowCheckContext } from '../../../flow-node-type.js';
+export declare const SCRIPT_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * A script step's `returns` — the author overriding what the body looks like.
+ *
+ * TypeScript already refuses a bad value at the call site, so this is the fence
+ * for everything that does NOT go through the type checker: a `.flow.ts` loaded
+ * as plain JS, a generated flow, a value read from config. Both mistakes below
+ * reach the emitted file silently and are then the designer's problem instead of
+ * the author's, which is precisely the failure this whole feature exists to undo.
+ */
+export declare function checkScript(inputs: {
+    returns?: unknown;
+}, ctx: FlowCheckContext): void;

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

@@ -0,0 +1,49 @@
+export const SCRIPT_DIAGNOSTICS = {
+    SCRIPT_RETURNS_UNKNOWN_TYPE: { severity: 'error', summary: '`returns` names a type the wire format does not know' },
+    SCRIPT_EMPTY_RETURNS: { severity: 'warning', summary: '`returns: {}` names no fields' },
+};
+/** The type vocabulary a script's `returns` may name — what the wire format accepts. */
+const SCRIPT_RETURN_TYPES = new Set(['string', 'number', 'boolean', 'object', 'array']);
+/**
+ * A script step's `returns` — the author overriding what the body looks like.
+ *
+ * TypeScript already refuses a bad value at the call site, so this is the fence
+ * for everything that does NOT go through the type checker: a `.flow.ts` loaded
+ * as plain JS, a generated flow, a value read from config. Both mistakes below
+ * reach the emitted file silently and are then the designer's problem instead of
+ * the author's, which is precisely the failure this whole feature exists to undo.
+ */
+export function checkScript(inputs, ctx) {
+    const step = ctx.step;
+    const returns = inputs?.returns;
+    if (returns === undefined)
+        return;
+    if (typeof returns === 'string') {
+        if (!SCRIPT_RETURN_TYPES.has(returns)) {
+            ctx.report('SCRIPT_RETURNS_UNKNOWN_TYPE', `Script step "${step}" declares \`returns: ${JSON.stringify(returns)}\`, which is not a type the `
+                + `wire format knows. Use one of ${[...SCRIPT_RETURN_TYPES].map((t) => `"${t}"`).join(', ')}, or a `
+                + `field map like \`{ total: "number" }\` to name an object's fields.`);
+        }
+        return;
+    }
+    if (typeof returns !== 'object' || returns === null || Array.isArray(returns)) {
+        ctx.report('SCRIPT_RETURNS_UNKNOWN_TYPE', `Script step "${step}"'s \`returns\` is ${JSON.stringify(returns)}. It takes either a type name or a `
+            + `map of field names to types (\`{ total: "number" }\`).`);
+        return;
+    }
+    const fields = returns;
+    // Same call as `APIWF_EMPTY_RETURNS` one surface over: an empty map declares
+    // nothing, emits nothing, and reads exactly like omitting the key — so it is
+    // almost always a half-finished edit rather than a statement.
+    if (Object.keys(fields).length === 0) {
+        ctx.report('SCRIPT_EMPTY_RETURNS', `Script step "${step}" declares \`returns: {}\`, which names no fields and emits nothing — the same `
+            + `as omitting it. Name the fields, or drop the key and let the body speak for itself.`);
+        return;
+    }
+    for (const [name, type] of Object.entries(fields)) {
+        if (typeof type !== 'string' || !SCRIPT_RETURN_TYPES.has(type)) {
+            ctx.report('SCRIPT_RETURNS_UNKNOWN_TYPE', `Script step "${step}" declares field "${name}" as ${JSON.stringify(type)}, which is not a type the `
+                + `wire format knows. Use one of ${[...SCRIPT_RETURN_TYPES].map((t) => `"${t}"`).join(', ')}.`);
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * The Script factory, `script()`. 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 { ScriptInputs } from './spec.js';
+/**
+ * Declare an inline script action.
+ *
+ * @param inputs - The JavaScript body (`code`, which must `return`) and what it
+ * returns (`returns`).
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function script(inputs: ScriptInputs): ActionSpec;

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

@@ -0,0 +1,15 @@
+/**
+ * The Script factory, `script()`. 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 inline script action.
+ *
+ * @param inputs - The JavaScript body (`code`, which must `return`) and what it
+ * returns (`returns`).
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function script(inputs) {
+    return builtinActionSpec({ kind: 'script', inputs });
+}

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

@@ -0,0 +1,3 @@
+/** The Script node family, as flow-node-registry.ts lists it: `core.action.script`. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const scriptFlowFamily: FlowNodeFamily;

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

@@ -0,0 +1,8 @@
+import { SCRIPT_DIAGNOSTICS } from './check.js';
+import { scriptNodeType } from './node-type.js';
+export const scriptFlowFamily = {
+    id: 'script',
+    title: 'Script',
+    types: [scriptNodeType],
+    diagnostics: SCRIPT_DIAGNOSTICS,
+};

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

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

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

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

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

@@ -0,0 +1,7 @@
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+import type { ScriptInputs } from './spec.js';
+export type ScriptSpec = {
+    kind: 'script';
+    inputs: ScriptInputs;
+};
+export declare const scriptNodeType: FlowVersionedNodeType<ScriptSpec>;