@uipath/maestro-builder-sdk 6.18.9 → 6.19.0

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>;

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

@@ -0,0 +1,125 @@
+/**
+ * The Script node type, `core.action.script` (bundled 1.0.0 and 1.1). Moved from
+ * serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, the lift's printed
+ * source, codes and messages unchanged.
+ */
+import { declaredScriptShape, inferScriptShape } from '../../../core/script-return.js';
+import { jsonClone } from '../../../core/json-file.js';
+import { checkScript } from './check.js';
+/**
+ * Declare what a `core.action.script` node actually publishes.
+ *
+ * Same instance-vs-definition split as `httpOutputs` above, for the same reason
+ * one level over: the platform's definition says `output: {type: 'object'}`
+ * because a node TYPE cannot know what a particular body returns, so the
+ * designer types every script read as `Record<string, any>` and rejects mapping
+ * one into a `string` flow output — on a flow that runs. What the body returns
+ * is knowable here, at author time, and this is where it gets written down.
+ *
+ * `returns` wins; otherwise the body is read (see `inferScriptShape`, which
+ * answers only when every `return` agrees). When neither says anything the
+ * definition's open object stands, byte-identical to what this emitted before.
+ */
+function scriptOutputs(base, returns, code) {
+    const shape = returns !== undefined ? declaredScriptShape(returns) : inferScriptShape(code);
+    // Nothing knowable, or knowably the open object the definition already
+    // declares — leave the node exactly as it was.
+    if (!shape || (shape.type === 'object' && !shape.properties))
+        return base;
+    if (!base || typeof base !== 'object')
+        return base;
+    const out = jsonClone(base);
+    if (!out.output)
+        return out;
+    out.output.type = shape.type;
+    if (shape.properties)
+        out.output.properties = shape.properties;
+    return out;
+}
+/**
+ * The `returns` a script step's author declared, recovered from the node, or nothing.
+ *
+ * Recovers what the author declared by DIFFERENCE: the node says what its output
+ * is, `inferScriptShape` says what re-compiling the body would declare on its
+ * own, and only a gap between the two needs writing down. Fields are recovered
+ * the same way — a property map the body does not produce is one the author gave
+ * as `returns: {…}`.
+ */
+function liftReturns(node, code) {
+    const out = node.outputs?.output;
+    const declared = typeof out?.type === 'string' ? out.type : undefined;
+    if (!declared)
+        return undefined;
+    const props = out?.properties;
+    // What re-compiling this body with NO `returns` would declare. Mirror
+    // `scriptOutputs` exactly: an inference of a bare `object` (or none at all)
+    // leaves the definition's own `{type:'object'}` standing, untouched.
+    const inferred = inferScriptShape(code);
+    const effective = inferred && !(inferred.type === 'object' && !inferred.properties)
+        ? inferred
+        : { type: 'object', properties: undefined };
+    const same = effective.type === declared
+        && JSON.stringify(sortKeys(effective.properties ?? {})) === JSON.stringify(sortKeys(props ?? {}));
+    if (same)
+        return undefined;
+    // Not what the body alone would say — so the author declared it, and it has to
+    // be written back or the round-trip loses it. That includes declaring the OPEN
+    // object over a body that looks typed, which is a real thing to want.
+    if (props && Object.keys(props).length > 0) {
+        // A field map is the richer statement, so it wins when there is one.
+        const entries = Object.entries(props)
+            .filter(([, v]) => typeof v?.type === 'string')
+            .map(([k, v]) => [k, v.type]);
+        if (entries.length > 0)
+            return Object.fromEntries(entries);
+    }
+    return declared;
+}
+/** Key-sorted copy, so a property map compares by content and not by order. */
+function sortKeys(o) {
+    return Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
+}
+function scriptAt(version) {
+    return {
+        kind: 'script', typeName: 'core.action.script', version, factory: 'script', definition: 'bundled',
+        rawNode: { factory: 'script()' },
+        serialize: ({ inputs }, ctx) => {
+            // A script BODY is a plain string, not an Expr, and it reads step outputs
+            // the same way everything else does — so it needs the rename too, or a
+            // reused child's script would read the first copy's node.
+            const base = ctx.definition('core.action.script', version)?.outputDefinition;
+            const typed = scriptOutputs(base, inputs.returns, inputs.code);
+            return {
+                inputs: { script: ctx.renameRefs(inputs.code) },
+                ...(typed !== base ? { outputs: typed } : {}),
+            };
+        },
+        deserialize: (node) => {
+            const raw = node.inputs?.script;
+            const code = typeof raw === 'string' ? raw : '';
+            // `returns` is recovered only when the node's declared output is something
+            // re-compiling the body would NOT produce on its own: serialize infers from
+            // the body first, so a script whose type is already plain in its code
+            // round-trips without it.
+            const returns = liftReturns(node, code);
+            return { kind: 'script', inputs: { code, ...(returns !== undefined ? { returns } : {}) } };
+        },
+        print: ({ inputs }, ctx) => {
+            const r = inputs.returns;
+            const returns = r === undefined ? undefined
+                : typeof r === 'string' ? ctx.string(r)
+                    : `{ ${Object.entries(r).map(([k, t]) => `${ctx.key(k)}: ${ctx.string(String(t))}`).join(', ')} }`;
+            return { factory: 'script', options: [['code', ctx.string(inputs.code)], ['returns', returns]] };
+        },
+        check: ({ inputs }, ctx) => checkScript(inputs, ctx),
+        // The body is not an Expr, but the `$vars.<name>` references it contains are
+        // checked like any other (flow-builder-sdk#20).
+        expressions: ({ inputs }) => [{ code: inputs.code }],
+        output: () => ({ kind: 'opaque' }),
+    };
+}
+export const scriptNodeType = {
+    kind: 'script', typeName: 'core.action.script', factory: 'script', defaultVersion: '1.0.0',
+    versions: { '1.0.0': scriptAt('1.0.0'), '1.1': scriptAt('1.1') },
+};

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

@@ -0,0 +1,52 @@
+/**
+ * The Script family's authoring type (`core.action.script`), and its kind's entry
+ * in `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md.
+ */
+import type { ScriptReturns } from '../../../core/script-return.js';
+export interface ScriptInputs {
+    /** JavaScript body. Must `return` its result. Referenced via out('<step>'). */
+    code: string;
+    /**
+     * What the body RETURNS — the type of `out('<step>')`.
+     *
+     * The platform's definition can only say `output: {type: 'object'}` (a node
+     * type cannot know what a particular body returns), so the designer types
+     * every script read as `Record<string, any>` and reports mapping one into a
+     * `string` output as `Type 'Record<string, any>' is not assignable to type
+     * 'string'` — on a flow that is correct and runs.
+     *
+     * **Usually you do not need this.** The compiler reads the body and declares
+     * what it plainly returns, so `return "pending-approval"` is already a
+     * `string`. Reach for `returns` when the body does not say so syntactically —
+     * a value that comes back from a runtime read, or an object assembled
+     * dynamically:
+     *
+     * ```ts
+     * .step('policyLimit', script({
+     *   code: 'return $vars.fetchPolicy.output.body.limit;',
+     *   returns: 'number',
+     * }))
+     * ```
+     *
+     * For an object return, name the FIELDS instead — the spelling every other
+     * action's `returns` uses, and what licenses `out('<step>', '<field>')`:
+     *
+     * ```ts
+     * returns: { total: 'number', currency: 'string' }
+     * ```
+     *
+     * An explicit `returns` always wins over what the body looks like. Nothing is
+     * inferred when the body does not plainly agree with itself, and an unknown
+     * shape stays the definition's open object rather than being guessed at.
+     */
+    returns?: ScriptReturns;
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link script} builds. */
+        script: {
+            inputs: ScriptInputs;
+        };
+    }
+}

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

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

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

@@ -0,0 +1,6 @@
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+import { type TransformInputs } from './spec.js';
+/** Every code the Transform rules emit; all are errors. */
+export declare const TRANSFORM_DIAGNOSTICS: DiagnosticCatalog;
+export declare function checkTransform(inputs: TransformInputs, ctx: FlowCheckContext): void;

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

@@ -0,0 +1,229 @@
+/**
+ * The Transform family's rules. Moved verbatim from check.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; codes and messages unchanged.
+ */
+import { Expr } from '../../../core/expr.js';
+import { ownEntry } from '../../../core/own-entry.js';
+import { VARIANT_OPERATION } from './spec.js';
+/** Every code the Transform rules emit; all are errors. */
+export const TRANSFORM_DIAGNOSTICS = {
+    TRANSFORM_AGG_NO_ALIAS: { severity: 'error', summary: 'an aggregation with no alias' },
+    TRANSFORM_AGG_NO_FIELD: { severity: 'error', summary: 'an aggregation other than count with no field' },
+    TRANSFORM_BAD_VOCAB: { severity: 'error', summary: 'a condition, transformation or aggregation the runtime does not know' },
+    TRANSFORM_COLLECTION_LITERAL: { severity: 'error', summary: 'a literal collection, which cannot be a path' },
+    TRANSFORM_COLLECTION_NOT_PATH: { severity: 'error', summary: 'a computed collection, which resolves to nothing deployed' },
+    TRANSFORM_COLLECTION_NOT_REF: { severity: 'error', summary: 'a raw value as the collection' },
+    TRANSFORM_COLLECTION_SCALAR: { severity: 'error', summary: 'a collection declared as a scalar, which passes through untouched' },
+    TRANSFORM_CONTAINS_ARRAY_VALUE: { severity: 'error', summary: 'a contains rule given an array value' },
+    TRANSFORM_EMPTY_FILTER: { severity: 'error', summary: 'a filter with no rules' },
+    TRANSFORM_EMPTY_MAP: { severity: 'error', summary: 'a map with no mappings' },
+    TRANSFORM_FILTER_NO_FIELD: { severity: 'error', summary: 'a filter rule with no field' },
+    TRANSFORM_FILTER_VALUE_EXPR: { severity: 'error', summary: 'a filter value the runtime will not evaluate' },
+    TRANSFORM_MAP_NO_FIELD: { severity: 'error', summary: 'a mapping with no field' },
+    TRANSFORM_NO_COLLECTION: { severity: 'error', summary: 'no collection' },
+    TRANSFORM_NO_GROUP_FIELD: { severity: 'error', summary: 'a groupBy with no field' },
+    TRANSFORM_NO_OPERATIONS: { severity: 'error', summary: 'no operations' },
+    TRANSFORM_UNKNOWN_OP: { severity: 'error', summary: 'an operation type the runtime skips' },
+    TRANSFORM_VARIANT_ONE_OP: { severity: 'error', summary: 'a variant with more or fewer than one operation' },
+    TRANSFORM_VARIANT_OP_MISMATCH: { severity: 'error', summary: 'a variant whose operation does not match it' },
+    TRANSFORM_VARIANT_UNKNOWN: { severity: 'error', summary: 'a variant no runtime resolves' },
+};
+export function checkTransform(inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion || undefined);
+    // ── collection must be a bare variable path ──
+    const collection = inputs?.collection;
+    if (collection === undefined || collection === null) {
+        at('TRANSFORM_NO_COLLECTION', `Transform "${step}" has no collection. Point it at the variable or step output holding the array.`, `collection: v('catalog')`);
+    }
+    else if (!(collection instanceof Expr)) {
+        // Types are stripped at run time, so `collection: [{…}]` or
+        // `collection: 'catalog'` reaches here as a raw value.
+        at('TRANSFORM_COLLECTION_NOT_REF', `Transform "${step}" was given a ${Array.isArray(collection) ? 'raw array' : `raw ${typeof collection}`} as its `
+            + `collection. That field is a variable PATH — the runtime turns the string into a lookup, so a value there `
+            + `resolves to nothing and the transform silently sees an empty collection.`, typeof collection === 'string' ? `collection: v('${collection}')` : `collection: v('<varName>')`);
+    }
+    else if (collection.literal) {
+        at('TRANSFORM_COLLECTION_LITERAL', `Transform "${step}" has a literal collection. Inline data cannot be a path — keep the array in a variable `
+            + `default (\`.var('items', types.array, [...])\`) and reference it, or read an upstream step's output.`, `collection: v('items')`);
+    }
+    else if (!/^\$vars\.[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/.test(collection.js.trim())) {
+        // A computed expression (js`…`, tmpl`…`, `.concat(…)`) is the trap that
+        // survives every local rung: a local run resolves it to a value, so
+        // it runs correctly there and resolves to NOTHING once deployed, where the
+        // string is used as a lookup path.
+        at('TRANSFORM_COLLECTION_NOT_PATH', `Transform "${step}"'s collection must be a plain reference, but it is the expression `
+            + `"${collection.js.trim().slice(0, 60)}". The deployed runtime uses that string as a lookup PATH, so a `
+            + `computed expression resolves to nothing there even though it runs locally. Compute it in a script step `
+            + `first, then point the transform at that step's output.`, `collection: out('<scriptStep>')`);
+    }
+    else {
+        // A collection that is not an array is PASSED THROUGH untouched — no error,
+        // no operations applied (faithful to v1). The result is a transform that
+        // looks like it ran and changed nothing.
+        // Only a DECLARED scalar can be judged here: a step output's type is not
+        // known offline, so this stays quiet about those rather than guessing.
+        const declared = ctx.declaredRef(collection.js);
+        const refName = declared?.name;
+        const declaredType = declared?.type;
+        if (declaredType && ['string', 'number', 'boolean'].includes(declaredType)) {
+            at('TRANSFORM_COLLECTION_SCALAR', `Transform "${step}"'s collection is "${refName}", declared as ${declaredType}. A transform runs its `
+                + `operations over an ARRAY; anything else is passed through untouched — no error, nothing applied — so `
+                + `the step would look like it ran and change nothing.`, `Declare it as types.array, or point the collection at the array field: collection: out('<step>', '<field>')`);
+        }
+    }
+    // ── the operation chain ──
+    const ops = inputs?.operations;
+    if (!Array.isArray(ops) || ops.length === 0) {
+        at('TRANSFORM_NO_OPERATIONS', `Transform "${step}" has no operations, so it passes its collection straight through. Add at least one `
+            + `filter / map / groupBy operation, or drop the node.`, `operations: [{ type: 'filter', filters: [{ field: 'status', condition: 'equals', value: 'open' }] }]`);
+        return;
+    }
+    checkVariant(step, inputs, ops, at);
+    ops.forEach((op, i) => {
+        const where = `operations[${i}]`;
+        // Read the discriminant before the narrowing below exhausts the union — at
+        // run time it can be anything (an author typo survives type erasure).
+        const kind = op?.type;
+        if (op?.type === 'filter') {
+            if (!Array.isArray(op.filters) || op.filters.length === 0) {
+                at('TRANSFORM_EMPTY_FILTER', `Transform "${step}" ${where} is a filter with no rules — the runtime passes every item through it.`);
+                return;
+            }
+            for (const [j, f] of op.filters.entries()) {
+                if (!f?.field && f?.field !== '')
+                    at('TRANSFORM_FILTER_NO_FIELD', `Transform "${step}" ${where}.filters[${j}] has no field, so the rule is dropped and the filter `
+                        + `matches everything.`);
+                checkVocab(step, `${where}.filters[${j}].condition`, f?.condition, FILTER_CONDITIONS, 'filter condition', 'passes every item through the rule', ctx);
+                if (typeof f?.value === 'string' && LOOKS_LIKE_EXPRESSION.test(f.value.trim()))
+                    at('TRANSFORM_FILTER_VALUE_EXPR', `Transform "${step}" ${where}.filters[${j}] compares against ${JSON.stringify(f.value)}. Filter values `
+                        + `are LITERAL only — the runtime evaluates nothing here, so every item would be compared against that `
+                        + `text and the filter would return nothing. Use a literal, or do the comparison in a script step.`, `value: 500`);
+                // `contains` is TWO operators wearing one name — the runtime does
+                // `Array.includes` when the FIELD holds an array and `String.includes`
+                // otherwise, faithful to v1. Which
+                // one runs is decided by the data, so nothing static can pick for you —
+                // but an ARRAY on the compare side is wrong under both readings
+                // (`['a','b']` is stringified to `a,b` for the substring test, and
+                // `includes` looks for the array itself as one element), and it is the
+                // shape an author reaches for when they mean "any of these".
+                if ((f?.condition === 'contains' || f?.condition === 'not_contains') && Array.isArray(f?.value))
+                    at('TRANSFORM_CONTAINS_ARRAY_VALUE', `Transform "${step}" ${where}.filters[${j}] uses "${f.condition}" against an ARRAY. "contains" compares `
+                        + `ONE value: if the item's field holds an array it tests membership of that value, otherwise it tests `
+                        + `for that value as a substring — either way an array on the right matches nothing, silently. For `
+                        + `"any of these", use one rule per value with the filter's "or" operation.`, `condition: 'contains', value: ${JSON.stringify(f.value[0] ?? 'x')}`);
+            }
+            return;
+        }
+        if (op?.type === 'map') {
+            if (!Array.isArray(op.mappings) || op.mappings.length === 0) {
+                at('TRANSFORM_EMPTY_MAP', `Transform "${step}" ${where} is a map with no mappings — with keepOriginalFields off that turns every `
+                    + `item into {}.`);
+                return;
+            }
+            for (const [j, m] of op.mappings.entries()) {
+                if (!m?.field)
+                    at('TRANSFORM_MAP_NO_FIELD', `Transform "${step}" ${where}.mappings[${j}] has no field, so nothing is carried into the output.`);
+                // Omitted is fine — it defaults to `copy`.
+                if (m?.transformation !== undefined)
+                    checkVocab(step, `${where}.mappings[${j}].transformation`, m.transformation, TRANSFORMATIONS, 'transformation', 'copies the value unchanged', ctx);
+            }
+            return;
+        }
+        if (op?.type === 'groupBy') {
+            if (!op.groupByField)
+                at('TRANSFORM_NO_GROUP_FIELD', `Transform "${step}" ${where} is a groupBy with no groupByField, so every item lands in one anonymous `
+                    + `group.`);
+            for (const [j, a] of (op.aggregations ?? []).entries()) {
+                if (!a?.alias?.trim())
+                    at('TRANSFORM_AGG_NO_ALIAS', `Transform "${step}" ${where}.aggregations[${j}] has no alias. The runtime drops an unaliased `
+                        + `aggregation, so its result would simply be absent from the output.`);
+                if (a?.operation !== 'count' && !a?.field?.trim())
+                    at('TRANSFORM_AGG_NO_FIELD', `Transform "${step}" ${where}.aggregations[${j}] is "${a?.operation}" with no field. Only "count" `
+                        + `works without one; the runtime drops the rest, so the aggregate would be missing from the output.`);
+                checkVocab(step, `${where}.aggregations[${j}].operation`, a?.operation, AGGREGATION_OPERATIONS, 'aggregation operation', 'yields null for that aggregate', ctx);
+            }
+            return;
+        }
+        at('TRANSFORM_UNKNOWN_OP', `Transform "${step}" ${where} has type ${JSON.stringify(kind)}. The runtime skips an operation it does `
+            + `not recognize, so the collection would pass through unchanged. Use 'filter', 'map', or 'groupBy'.`);
+    });
+}
+/**
+ * Diagnose the `variant` discriminator on a transform step.
+ *
+ * A variant emits a single-purpose node type (`core.action.transform.filter`,
+ * `.map`, `.group-by`) instead of the generic one. The platform runs all four
+ * node types through the SAME script generators and dispatches on the
+ * OPERATION's type, never the node's — so a mismatch here does not fault and
+ * does not change the answer. It produces a node that lies: a `.filter` node
+ * that actually maps, whose operation the designer's filter editor cannot even
+ * show. That is exactly the class this SDK catches at rung 1, because no rung
+ * below it ever will.
+ */
+function checkVariant(step, inputs, ops, at) {
+    const variant = inputs?.variant;
+    if (variant === undefined || variant === null)
+        return; // generic — chains freely
+    const variants = Object.keys(VARIANT_OPERATION);
+    if (typeof variant !== 'string' || !variants.includes(variant)) {
+        at('TRANSFORM_VARIANT_UNKNOWN', `Transform "${step}" has variant ${JSON.stringify(variant)}, which is not a Transform node type. `
+            + `The emitted node would be "core.action.transform.${String(variant)}", which no runtime resolves. `
+            + `Valid: ${variants.join(', ')} — or omit \`variant\` for the generic chaining Transform.`, nearestIn(variant, variants));
+        return;
+    }
+    const expected = ownEntry(VARIANT_OPERATION, variant);
+    if (ops.length !== 1) {
+        at('TRANSFORM_VARIANT_ONE_OP', `Transform "${step}" is the "${variant}" variant but carries ${ops.length} operations. A variant node runs `
+            + `exactly one — the designer's ${variant} editor shows a single ${expected} operation and nothing else. `
+            + `Drop \`variant\` to chain them in one generic Transform, or split them across one node per step.`);
+        return;
+    }
+    const got = ops[0]?.type;
+    if (got !== expected) {
+        at('TRANSFORM_VARIANT_OP_MISMATCH', `Transform "${step}" is the "${variant}" variant but its operation is ${JSON.stringify(got)}, not `
+            + `"${expected}". The node type does not drive the runtime — the OPERATION does — so this would emit a `
+            + `node labelled "${variant}" that actually does ${JSON.stringify(got)}, and the designer's ${variant} `
+            + `editor could not show it. Match them, or drop \`variant\` for the generic Transform.`, typeof got === 'string' && Object.values(VARIANT_OPERATION).includes(got)
+            ? `variant: '${variants.find((v) => ownEntry(VARIANT_OPERATION, v) === got)}'`
+            : `type: '${expected}'`);
+    }
+}
+/** Nearest member of a closed vocabulary, for a "did you mean" suggestion. */
+function nearestIn(value, vocab) {
+    const v = typeof value === 'string' ? value.toLowerCase() : '';
+    return vocab.find((c) => c.replace(/[-_]/g, '') === v.replace(/[^a-z]/g, ''))
+        ?? vocab.find((c) => c.startsWith(v) || (v !== '' && v.startsWith(c)));
+}
+/** A string that is an expression the transform runtime will NOT evaluate. */
+const LOOKS_LIKE_EXPRESSION = /^(=js:|\$vars\.|\{\s*\$vars\.)/;
+// The three closed vocabularies a transform operation carries. TypeScript types
+// them, but an authored `.flow.ts` runs with types ERASED — so `condition:
+// 'greater'` reaches the runtime, whose generated script falls through on a name
+// it does not know and is silent about it:
+//   condition      → the rule passes every item
+//   transformation → the value is copied unchanged
+//   aggregation    → the aggregate is null
+// Green at every rung, wrong answer. Checked here so the author hears it at
+// rung 1 — a flow that never went through this SDK gets no such warning.
+const FILTER_CONDITIONS = [
+    'equals', 'not_equals',
+    'greater_than', 'less_than', 'greater_equal', 'less_equal',
+    'contains', 'not_contains',
+    'starts_with', 'not_starts_with',
+    'ends_with', 'not_ends_with',
+    'matches_regex',
+    'in', 'not_in',
+    'is_null', 'is_not_null',
+    'is_empty', 'is_not_empty',
+];
+const TRANSFORMATIONS = ['copy', 'uppercase', 'lowercase', 'trim'];
+const AGGREGATION_OPERATIONS = ['count', 'sum', 'average', 'min', 'max', 'first', 'last', 'collect'];
+/** Flag a value that is not a member of a closed vocabulary, suggesting the nearest. */
+function checkVocab(step, at, value, vocab, what, effect, ctx) {
+    if (typeof value === 'string' && vocab.includes(value))
+        return;
+    const near = nearestIn(value, vocab);
+    ctx.report('TRANSFORM_BAD_VOCAB', `Transform "${step}" ${at} is ${JSON.stringify(value)}, which is not a valid ${what}. The runtime does not `
+        + `recognize it and ${effect}, so the result would be silently wrong. Valid: ${vocab.join(', ')}.`, near || undefined);
+}