@uipath/maestro-builder-sdk 6.66.6 → 6.66.8

package/dist/nodes/process/flow/refusals.d.ts

@@ -0,0 +1,8 @@
+import { type ProcessKind } from '../../../core/process-resource.js';
+/**
+ * Throw the first condition of `inputs` the serializer would write wrong, as a
+ * `CompileRefusal` on the step. For instance `rpaWorkflow({ name, folderPath })`
+ * with no `key` throws `RPA_NO_KEY` instead of writing node type
+ * `uipath.core.rpa-workflow.undefined`.
+ */
+export declare function refuseLossyProcess(kind: ProcessKind, inputs: unknown, step: string): void;

package/dist/nodes/process/flow/refusals.js

@@ -0,0 +1,92 @@
+/**
+ * What the process family's serializer refuses, because it cannot write the step
+ * the author wrote (#1518, docs/CHECK_COMPILE_CONTRACT_DESIGN.md §3.1). Since
+ * #1497 `compile` does not run `check`, so a rule whose condition the emitter
+ * silently loses has to stop the emitter itself. `check` still reports each one:
+ * it runs the serializer in collect mode, which places the refusal on the step.
+ *
+ *  - `<PREFIX>_NO_KEY`: the node type is `<prefix><key>`, so an omitted key
+ *    wrote `uipath.core.rpa-workflow.undefined` and a blank one the bare prefix.
+ *  - `<PREFIX>_LOCAL_HAS_FOLDER`: an in-solution resource is written with
+ *    folder `""` (`processResourceLocation`), so the author's folderPath is dropped.
+ *  - `AGENTIC_RESERVED_INPUT`: `fireAndForget` is the design-time switch; the
+ *    definition retypes it boolean and decompile deletes it as an argument.
+ */
+import { CompileRefusal } from '../../../core/compile-refusal.js';
+import { ownEntry } from '../../../core/own-entry.js';
+import { blank, renamedFieldMessage } from '../../../core/process-resource.js';
+/** Per kind: the codes, the label messages use, and the retired name of `key` (if any). */
+const KINDS = {
+    rpaWorkflow: {
+        noKeyCode: 'RPA_NO_KEY', localCode: 'RPA_LOCAL_HAS_FOLDER', label: 'RPA', oldField: 'process', localLabel: 'RPA step',
+        noKey: (step) => `RPA step "${step}" has no \`key\`. That is the published process's release key (a GUID), and `
+            + `it becomes part of the node's type — without it there is no process to start. Find it with `
+            + `\`uip or processes list --all-folders --process-type Process\` (the row's \`Key\`).`,
+        noKeySuggestion: `key: '486edc26-0658-4ac1-92c9-1ef953927151'`,
+    },
+    apiWorkflow: {
+        noKeyCode: 'APIWF_NO_KEY', label: 'API workflow', oldField: 'workflow',
+        noKey: (step) => `API workflow step "${step}" has no \`key\`. That is the published workflow's key (a GUID), and `
+            + `it becomes part of the node's type — without it there is no workflow to invoke. Find it with `
+            + `\`uip or processes list --all-folders\` (an API workflow's ProcessKey reads "<name>.api.<name>").`,
+        noKeySuggestion: `key: 'ce857908-ee1d-4392-b552-38bcea0be29c'`,
+    },
+    publishedFunction: {
+        noKeyCode: 'FUNCTION_NO_KEY', localCode: 'FUNCTION_LOCAL_HAS_FOLDER', label: 'Function', localLabel: 'function step',
+        noKey: (step) => `Function step "${step}" has no \`key\`. That is the published function's key (a GUID), and it becomes `
+            + `part of the node's type — without it there is no function to invoke. Find it with `
+            + `\`uip maestro flow registry search "uipath.core.function"\`.`,
+        noKeySuggestion: `key: '7059bdb5-fdd7-4e13-9d7b-1748aaeb129d'`,
+    },
+    agenticProcess: {
+        noKeyCode: 'AGENTIC_NO_KEY', localCode: 'AGENTIC_LOCAL_HAS_FOLDER', label: 'Agentic process', oldField: 'process', localLabel: 'agentic process step',
+        noKey: (step) => `Agentic process step "${step}" has no \`key\`. That is the published process's key (a GUID), `
+            + `and it becomes part of the node's type — without it there is no process to start. Find it with `
+            + `\`uip or processes list --all-folders --limit 100\` (an agentic process's ProcessKey reads `
+            + `"<name>.agentic.<name>"; the listing paginates at 50, so pass a limit or scope it to a folder).`,
+        noKeySuggestion: `key: '4fc450ab-89be-4462-8fc8-21ac4c1d6fb9'`,
+    },
+    agent: {
+        noKeyCode: 'AGENT_NO_KEY', label: 'Agent', oldField: 'agent',
+        noKey: (step) => `Agent step "${step}" has no \`key\`. It is a GUID and becomes part of the node's `
+            + `type — without it there is no agent to start. For a published agent, find the Orchestrator `
+            + `release with \`uip or processes list --all-folders --limit 200\` (take the row's \`Key\`) or `
+            + `\`uip maestro flow registry search uipath.core.agent\`. For an in-solution agent, read `
+            + `\`resource.key\` from \`resources/solution_folder/process/agent/<project>.json\`.`,
+        noKeySuggestion: `key: '6a47dc5b-5fd4-461f-b97d-6c1817abcaaa'`,
+    },
+};
+/**
+ * Throw the first condition of `inputs` the serializer would write wrong, as a
+ * `CompileRefusal` on the step. For instance `rpaWorkflow({ name, folderPath })`
+ * with no `key` throws `RPA_NO_KEY` instead of writing node type
+ * `uipath.core.rpa-workflow.undefined`.
+ */
+export function refuseLossyProcess(kind, inputs, step) {
+    const k = ownEntry(KINDS, kind);
+    const s = (inputs ?? {});
+    // Every blank form is refused: omitted writes `<prefix>undefined`, and `''`
+    // or whitespace writes the bare prefix (or one ending in spaces).
+    if (blank(s.key)) {
+        const old = k.oldField !== undefined ? s[k.oldField] : undefined;
+        if (k.oldField !== undefined && !blank(old)) {
+            throw new CompileRefusal(k.noKeyCode, renamedFieldMessage(k.label, step, k.oldField), `key: ${JSON.stringify(old)}`);
+        }
+        throw new CompileRefusal(k.noKeyCode, k.noKey(step), k.noKeySuggestion);
+    }
+    if (k.localCode !== undefined && k.localLabel !== undefined && s.location === 'in-solution' && !blank(s.folderPath)) {
+        throw new CompileRefusal(k.localCode, `In-solution ${k.localLabel} "${step}" also sets \`folderPath\` ${JSON.stringify(s.folderPath)}. An `
+            + `in-solution sibling has no folder until the solution is deployed — the platform's own manifest `
+            + `writes \`""\` — so the value would be dropped. Remove it, or drop \`location: 'in-solution'\` to `
+            + `call the published copy.`);
+    }
+    const args = s.inputs;
+    if (kind === 'agenticProcess' && args !== null && typeof args === 'object'
+        && Object.prototype.hasOwnProperty.call(args, 'fireAndForget')) {
+        throw new CompileRefusal('AGENTIC_RESERVED_INPUT', `Agentic process step "${step}" passes an input called \`fireAndForget\`. That name is RESERVED: it is `
+            + `the platform's design-time switch for starting the process without waiting, and its serializer `
+            + `removes the key from the node's inputs before emitting — so a process argument of that name never `
+            + `arrives. Locally it would appear to work, because this engine passes the whole envelope through. `
+            + `Rename the argument, or set \`completion: 'fire-and-forget'\` to start the process without waiting.`);
+    }
+}

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

@@ -20,6 +20,31 @@ export declare function itemDataIsString(def: unknown): boolean;
  * serializer's refusal, so the two say the same thing.
  */
 export declare function queueItemExprMessage(step: string, typeName: string, version: string, field: string): string;
+/**
+ * Whether `item` is something other than an object of fields: an array, a
+ * primitive, or a whole-item expression (an `Expr` is an object, but its own
+ * fields are not the item's). An omitted or null item is the empty item.
+ */
+export declare function itemIsNotObject(item: unknown): boolean;
+/**
+ * Why `serialize` refuses an `item` that is not an object (QUEUE_ITEM_NOT_OBJECT).
+ * Writing it anyway would rewrite it through `Object.entries`: `['INV-1']` would
+ * become `{ "0": "INV-1" }`, a string one field per character, a number `{}`,
+ * and a whole-item expression its own `js`/`literal` fields.
+ */
+export declare function queueItemNotObjectMessage(step: string, item: unknown): {
+    message: string;
+    suggestion: string;
+};
+/**
+ * Why `serialize` refuses `returns` on a fire-and-forget enqueue
+ * (QUEUE_RETURNS_WITHOUT_WAIT). That node publishes the item's own record, so
+ * the `.flow` has no place for `returns` and writing it would drop them.
+ */
+export declare function queueReturnsWithoutWaitMessage(step: string): {
+    message: string;
+    suggestion: string;
+};
 /**
  * Check a `queueItem(...)` call.
  *

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

@@ -14,7 +14,7 @@ export const QUEUE_DIAGNOSTICS = {
     QUEUE_ITEM_EXPR_UNSUPPORTED: { severity: 'error', summary: 'an expression in an item stored as one JSON string' },
     QUEUE_BAD_PRIORITY: { severity: 'error', summary: 'a priority the node type does not offer' },
     QUEUE_BAD_DATE: { severity: 'error', summary: 'a date Orchestrator cannot read' },
-    QUEUE_RETURNS_WITHOUT_WAIT: { severity: 'warning', summary: 'returns without wait: true' },
+    QUEUE_RETURNS_WITHOUT_WAIT: { severity: 'error', summary: 'returns without wait: true' },
     QUEUE_READ_NOT_OUTPUT: { severity: 'error', summary: 'a read outside the step\'s output' },
     QUEUE_READ_WITHOUT_RETURNS: { severity: 'error', summary: 'a field read off a wait result with no returns' },
     QUEUE_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'a read of a field the step does not publish' },
@@ -40,6 +40,50 @@ export function queueItemExprMessage(step, typeName, version, field) {
         + `cannot be an expression there. Omit the { version } to emit the SDK's default version, which `
         + `stores the item as an object of values and expressions.`;
 }
+/**
+ * Whether `item` is something other than an object of fields: an array, a
+ * primitive, or a whole-item expression (an `Expr` is an object, but its own
+ * fields are not the item's). An omitted or null item is the empty item.
+ */
+export function itemIsNotObject(item) {
+    if (item === undefined || item === null)
+        return false;
+    return item instanceof Expr || typeof item !== 'object' || Array.isArray(item);
+}
+function itemKind(item) {
+    if (item instanceof Expr)
+        return 'an expression';
+    return Array.isArray(item) ? 'an array' : typeof item;
+}
+/**
+ * Why `serialize` refuses an `item` that is not an object (QUEUE_ITEM_NOT_OBJECT).
+ * Writing it anyway would rewrite it through `Object.entries`: `['INV-1']` would
+ * become `{ "0": "INV-1" }`, a string one field per character, a number `{}`,
+ * and a whole-item expression its own `js`/`literal` fields.
+ */
+export function queueItemNotObjectMessage(step, item) {
+    return {
+        message: `Queue step "${step}"'s \`item\` is ${itemKind(item)}. It `
+            + `must be an object of field names to primitive values — that object becomes the queue `
+            + `item's \`SpecificContent\`.`,
+        suggestion: `item: { InvoiceId: 'INV-1', Amount: 120 }`,
+    };
+}
+/**
+ * Why `serialize` refuses `returns` on a fire-and-forget enqueue
+ * (QUEUE_RETURNS_WITHOUT_WAIT). That node publishes the item's own record, so
+ * the `.flow` has no place for `returns` and writing it would drop them.
+ */
+export function queueReturnsWithoutWaitMessage(step) {
+    return {
+        message: `Queue step "${step}" declares \`returns\` but does not \`wait\`, so nothing produces those `
+            + `fields and the \`.flow\` would drop them: a fire-and-forget enqueue publishes the queue ITEM's own `
+            + `Orchestrator record (\`Key\`, \`Status\`, \`Reference\`, \`SpecificContent\`, …), whose fields are `
+            + `already declared for you. \`returns\` describes what a CONSUMER wrote into a processed item's `
+            + `result, which needs \`wait: true\`.`,
+        suggestion: `wait: true`,
+    };
+}
 /**
  * Check a `queueItem(...)` call.
  *
@@ -102,12 +146,8 @@ export function checkQueueItem(inputs, ctx) {
             + `— a bare item with a reference is a real pattern — but if the work needs a payload, this `
             + `is where it goes.`, `item: { InvoiceId: input('invoiceRef') }`);
     }
-    else if (typeof item !== 'object' || Array.isArray(item)) {
-        at('QUEUE_ITEM_NOT_OBJECT', `Queue step "${step}"'s \`item\` is ${Array.isArray(item) ? 'an array' : typeof item}. It `
-            + `must be an object of field names to primitive values — that object becomes the queue `
-            + `item's \`SpecificContent\`.`, `item: { InvoiceId: 'INV-1', Amount: 120 }`);
-    }
-    else {
+    else if (!itemIsNotObject(item)) {
+        // (A non-object item is the serializer's QUEUE_ITEM_NOT_OBJECT.)
         const itemIsString = itemDataIsString(ctx.definition());
         for (const [k, v] of Object.entries(item)) {
             // An expression where the pinned version stores one JSON string is the
@@ -140,17 +180,7 @@ export function checkQueueItem(inputs, ctx) {
                 + `Orchestrator can read. It takes ISO-8601 — a full timestamp with a zone.`, `${field}: '2026-08-05T17:00:00Z'`);
         }
     }
-    // `returns` describes what a CONSUMER produced, which only exists if the step
-    // waited for one. On a fire-and-forget enqueue it is a misunderstanding worth
-    // naming: the output is the queue item's own record, and the serializer already
-    // declares its fields.
-    if (!inputs?.wait && inputs?.returns && Object.keys(inputs.returns).length) {
-        warn('QUEUE_RETURNS_WITHOUT_WAIT', `Queue step "${step}" declares \`returns\` but does not \`wait\`, so nothing produces those `
-            + `fields: a fire-and-forget enqueue publishes the queue ITEM's own Orchestrator record `
-            + `(\`Key\`, \`Status\`, \`Reference\`, \`SpecificContent\`, …), whose fields are already `
-            + `declared for you. \`returns\` describes what a CONSUMER wrote into a processed item's `
-            + `result, which needs \`wait: true\`.`, `wait: true`);
-    }
+    // `returns` without `wait` is the serializer's QUEUE_RETURNS_WITHOUT_WAIT.
 }
 /** The three priorities `core.action.queue.create[-and-wait]`'s form offers. */
 const QUEUE_PRIORITIES = ['Low', 'Normal', 'High'];

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

@@ -1,7 +1,7 @@
 import { Expr } from '../../../core/expr.js';
 import { jsonClone } from '../../../core/json-clone.js';
 import { isRecord } from '../../../core/node-envelope.js';
-import { checkQueueItem, itemDataIsString, queueItemExprMessage } from './check.js';
+import { checkQueueItem, itemDataIsString, itemIsNotObject, queueItemExprMessage, queueItemNotObjectMessage, queueReturnsWithoutWaitMessage, } from './check.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './record.js';
 import { CompileRefusal } from '../../../core/compile-refusal.js';
 const CREATE = 'core.action.queue.create';
@@ -247,6 +247,18 @@ function queueAt(typeName, wait) {
         kind: 'queueItem', typeName, version: '1.2', factory: 'queueItem', definition: 'per-tenant', errorPort: true,
         rawNode: { factory: wait ? 'queueItem({ wait: true })' : 'queueItem()' },
         serialize: ({ inputs: s }, ctx) => {
+            // Both would be written lossily, so they are refused here, on the step:
+            // a non-object item (a whole-item Expr included) would be rewritten
+            // through `Object.entries`, and a
+            // fire-and-forget node carries the item record schema, not `returns`.
+            if (itemIsNotObject(s.item)) {
+                const { message, suggestion } = queueItemNotObjectMessage(ctx.step, s.item);
+                throw new CompileRefusal('QUEUE_ITEM_NOT_OBJECT', message, suggestion);
+            }
+            if (!s.wait && s.returns && Object.keys(s.returns).length) {
+                const { message, suggestion } = queueReturnsWithoutWaitMessage(ctx.step);
+                throw new CompileRefusal('QUEUE_RETURNS_WITHOUT_WAIT', message, suggestion);
+            }
             // The bindings first: two steps on the same queue share one pair, and the
             // node's `model.context` has to name the ids that actually exist.
             const { ids, entries } = queueItemBindings(s, ctx.bindings);

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

@@ -23,7 +23,7 @@ export const TRANSFORM_DIAGNOSTICS = {
     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_UNKNOWN_OP: { severity: 'error', summary: 'an operation type compile cannot write' },
     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' },
@@ -32,44 +32,35 @@ 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 ──
+    // A missing, raw-value or literal collection has no path form at all: the
+    // serializer refuses it (TRANSFORM_NO_COLLECTION, TRANSFORM_COLLECTION_NOT_REF,
+    // TRANSFORM_COLLECTION_LITERAL in node-type.ts `collectionPath`).
     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>')`);
+    if (collection instanceof Expr && !collection.literal) {
+        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 ──
@@ -82,9 +73,6 @@ export function checkTransform(inputs, ctx) {
     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.`);
@@ -145,8 +133,8 @@ export function checkTransform(inputs, 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'.`);
+        // Any other type is the serializer's TRANSFORM_UNKNOWN_OP (node-type.ts
+        // `transformInputs`): it would otherwise be written as a groupBy.
     });
 }
 /**

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

@@ -59,6 +59,12 @@ function transformInputs(inputs, ctx) {
                 },
             };
         }
+        // Anything that is not a groupBy would be written as one below, which the
+        // runtime would then run as a real grouping (#1518). Refused instead.
+        if (op?.type !== 'groupBy') {
+            throw new CompileRefusal('TRANSFORM_UNKNOWN_OP', `Transform "${ctx.step}" operations[${i}] has type ${JSON.stringify(op?.type)}; `
+                + `compile writes only filter, map or groupBy. Use one of them.`);
+        }
         return {
             id,
             type: 'groupBy',
@@ -74,20 +80,40 @@ function transformInputs(inputs, ctx) {
             },
         };
     });
-    return { collection: ctx.renameRefs(collectionPath(inputs.collection)), operations };
+    return { collection: ctx.renameRefs(collectionPath(inputs.collection, ctx.step)), operations };
 }
 /**
  * The `collection` string. A bare reference (`v('x')` / `out('s','p')`) is
  * already the path the runtime wants, so it is emitted verbatim. Anything else
- * cannot be expressed as a path — `check` rejects it (TRANSFORM_COLLECTION_*)
- * before serialization, so reaching here with one means `compile` was called
- * without a check; emit the raw text so the failure stays visible downstream
- * rather than becoming a silently empty collection.
+ * has no faithful path form, so it is refused here rather than written (#1518):
+ * a missing one would be the string "undefined", a raw array "[object Object]",
+ * a raw string `items` reads back as the expression js`items`, and `lit([1,2])`
+ * would be "[1,2]", the same text as js`[1,2]`. `compile` does not run `check`
+ * (#1497), so this is the only place that stops them. A computed expression
+ * (TRANSFORM_COLLECTION_NOT_PATH) is written as its own text, so it stays
+ * `check`'s.
  */
-function collectionPath(collection) {
-    if (collection instanceof Expr)
-        return collection.literal ? JSON.stringify(collection.value) : collection.js;
-    return String(collection);
+function collectionPath(collection, step) {
+    if (collection === undefined || collection === null) {
+        throw new CompileRefusal('TRANSFORM_NO_COLLECTION', `Transform "${step}" has no collection. Point it at the variable or step output holding the array.`, `collection: v('catalog')`);
+    }
+    if (!(collection instanceof Expr)) {
+        // Types are stripped at run time, so `collection: [{…}]` or
+        // `collection: 'catalog'` reaches here as a raw value.
+        throw new CompileRefusal('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>')`);
+    }
+    // A decompiled canvas Transform with no collection prints as `lit([])`
+    // (`printTransform`), so recompiling it stops here too: this message names
+    // the fix for that file as well as for authored inline data.
+    if (collection.literal) {
+        throw new CompileRefusal('TRANSFORM_COLLECTION_LITERAL', `Transform "${step}" has a literal collection, and that field is a variable PATH, so inline data has no `
+            + `form there. A Transform decompiled with no collection prints as \`lit([])\` and lands here too. Bind `
+            + `\`collection\` to a variable or step output, e.g. \`v('<var>')\`; for inline data, keep the array in a `
+            + `variable default (\`.var('items', types.array, [...])\`) and reference it.`, `collection: v('<var>')`);
+    }
+    return collection.js;
 }
 /**
  * A transform node publishes a COLLECTION — always.