@uipath/maestro-builder-sdk 6.20.6 → 6.21.0

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

@@ -0,0 +1,35 @@
+/**
+ * The Queue family's rules and their catalog. Moved from check.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; codes and messages are unchanged.
+ */
+import type { DiagnosticCatalog } from '../../../core/nodes/family.js';
+import type { FlowCheckContext } from '../../../flow-node-type.js';
+import type { QueueItemInputs } from './spec.js';
+/** Every code the family reports, with the severity it reports it at. */
+export declare const QUEUE_DIAGNOSTICS: DiagnosticCatalog;
+/**
+ * Check a `queueItem(...)` call.
+ *
+ * WHAT THESE RULES CAN AND CANNOT SEE. Whether the queue exists, whether anything
+ * drains it, and what a consumer writes into a processed item's result all live on
+ * the tenant. So these cover the mistakes decidable from the call — plus the one
+ * mistake the PLATFORM decides and rejects at run time, which is worth catching
+ * here because its error arrives from Orchestrator as an HTTP 400 three layers
+ * away:
+ *
+ *  - a missing/blank `queue`, `folderPath` or `key`. Without the first two
+ *    nothing can resolve the node's `resourceBindings.name`, and without `key`
+ *    nothing joins the node to its bindings — both read as engine errors rather
+ *    than authoring ones.
+ *  - a `key` that is not a GUID. The commonest form is passing the queue's NAME
+ *    where its Orchestrator key belongs.
+ *  - a NESTED `item`. Orchestrator answers "Property values must be simple (like
+ *    numbers or text) and not complex or composite data types (like objects or
+ *    arrays)" — a run-time 400 for something visible in the source.
+ *  - a `priority` outside the three the node type offers. The platform normalizes
+ *    an unknown one silently, so it is a wrong RESULT, not an error.
+ *  - `returns` on a step that does not wait (there is nothing per-tenant to
+ *    declare), and a `wait: true` step whose result nothing can read.
+ *  - a non-ISO `dueDate` / `deferDate`.
+ */
+export declare function checkQueueItem(inputs: QueueItemInputs | undefined, ctx: FlowCheckContext): void;

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

@@ -0,0 +1,126 @@
+import { commentText } from '../../../core/comment-text.js';
+import { nearestName } from '../../../core/edit-distance.js';
+import { Expr } from '../../../core/expr.js';
+import { GUID_RE } from '../../../core/binding-messages.js';
+/** Every code the family reports, with the severity it reports it at. */
+export const QUEUE_DIAGNOSTICS = {
+    QUEUE_NO_NAME: { severity: 'error', summary: 'no queue name' },
+    QUEUE_NO_FOLDER: { severity: 'error', summary: 'no folderPath' },
+    QUEUE_NO_KEY: { severity: 'error', summary: 'no queue key' },
+    QUEUE_KEY_NOT_GUID: { severity: 'error', summary: 'the key is not an Orchestrator GUID' },
+    QUEUE_NO_ITEM: { severity: 'warning', summary: 'the item carries no data' },
+    QUEUE_ITEM_NOT_OBJECT: { severity: 'error', summary: 'the item is not an object' },
+    QUEUE_ITEM_FIELD_NOT_PRIMITIVE: { severity: 'error', summary: 'an item field is not a primitive' },
+    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_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' },
+};
+/**
+ * Check a `queueItem(...)` call.
+ *
+ * WHAT THESE RULES CAN AND CANNOT SEE. Whether the queue exists, whether anything
+ * drains it, and what a consumer writes into a processed item's result all live on
+ * the tenant. So these cover the mistakes decidable from the call — plus the one
+ * mistake the PLATFORM decides and rejects at run time, which is worth catching
+ * here because its error arrives from Orchestrator as an HTTP 400 three layers
+ * away:
+ *
+ *  - a missing/blank `queue`, `folderPath` or `key`. Without the first two
+ *    nothing can resolve the node's `resourceBindings.name`, and without `key`
+ *    nothing joins the node to its bindings — both read as engine errors rather
+ *    than authoring ones.
+ *  - a `key` that is not a GUID. The commonest form is passing the queue's NAME
+ *    where its Orchestrator key belongs.
+ *  - a NESTED `item`. Orchestrator answers "Property values must be simple (like
+ *    numbers or text) and not complex or composite data types (like objects or
+ *    arrays)" — a run-time 400 for something visible in the source.
+ *  - a `priority` outside the three the node type offers. The platform normalizes
+ *    an unknown one silently, so it is a wrong RESULT, not an error.
+ *  - `returns` on a step that does not wait (there is nothing per-tenant to
+ *    declare), and a `wait: true` step whose result nothing can read.
+ *  - a non-ISO `dueDate` / `deferDate`.
+ */
+export function checkQueueItem(inputs, ctx) {
+    const step = ctx.step;
+    // Severity is the catalog's (QUEUE_DIAGNOSTICS): `at` and `warn` name the intent.
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const warn = at;
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    if (blank(inputs?.queue)) {
+        at('QUEUE_NO_NAME', `Queue step "${step}" has no \`queue\`. That is the queue's name in Orchestrator, and the `
+            + `runtime resolves the queue by name + folder — without it the run fails before dispatch.`, `queue: 'SupplierInvoices'`);
+    }
+    if (blank(inputs?.folderPath)) {
+        at('QUEUE_NO_FOLDER', `Queue step "${step}" has no \`folderPath\`. Queues are folder-scoped, and the runtime `
+            + `resolves this one by name + folder.`, `folderPath: 'Shared'`);
+    }
+    if (blank(inputs?.key)) {
+        at('QUEUE_NO_KEY', `Queue step "${step}" has no \`key\`. That is the queue's own Orchestrator key, and it is `
+            + `what joins this node to the flow's queue bindings — without it nothing says which `
+            + `bindings belong to the node, so it cannot be dispatched. Find it with `
+            + `\`uip or queues list --all-folders\`.`, `key: 'fa1a7328-cd17-4525-b5ab-29d86e399312'`);
+    }
+    else if (!GUID_RE.test(String(inputs.key).trim())) {
+        at('QUEUE_KEY_NOT_GUID', `Queue step "${step}"'s \`key\` is ${JSON.stringify(inputs.key)}, which is not an `
+            + `Orchestrator key. \`key\` is the GUID the tenant gives the queue; the queue's NAME goes `
+            + `in \`queue\` and its folder in \`folderPath\`.`, `key: '<guid>', queue: ${JSON.stringify(inputs.key)}`);
+    }
+    // The item's data must be FLAT. This is the platform's rule, not ours, and it is
+    // enforced at the far end: a nested value earns an HTTP 400 from Orchestrator
+    // mid-run, which is a long way from the line that caused it.
+    const item = inputs?.item;
+    if (item === undefined || item === null) {
+        warn('QUEUE_NO_ITEM', `Queue step "${step}" has no \`item\`, so it enqueues an item with no data. That is legal `
+            + `— 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 {
+        for (const [k, v] of Object.entries(item)) {
+            // An Expr is a reference the runtime resolves — its VALUE may be anything,
+            // and nothing local can know, so it is not flagged here.
+            if (v instanceof Expr)
+                continue;
+            if (v !== null && typeof v === 'object') {
+                at('QUEUE_ITEM_FIELD_NOT_PRIMITIVE', `Queue step "${step}"'s \`item.${k}\` is ${Array.isArray(v) ? 'an array' : 'an object'}. `
+                    + `Orchestrator rejects a queue item whose property values are not simple: `
+                    + `"Property values must be simple (like numbers or text) and not complex or composite `
+                    + `data types (like objects or arrays)". Flatten it, or JSON-encode it into one string `
+                    + `field.`, `item: { ${k}: JSON.stringify(...) }  // or ${commentText(k)}Id, ${commentText(k)}Name, …`);
+            }
+        }
+    }
+    if (inputs?.priority !== undefined && !QUEUE_PRIORITIES.includes(String(inputs.priority))) {
+        at('QUEUE_BAD_PRIORITY', `Queue step "${step}"'s \`priority\` is ${JSON.stringify(inputs.priority)}. The node type `
+            + `offers exactly ${QUEUE_PRIORITIES.map((p) => `"${p}"`).join(', ')} — anything else is `
+            + `normalized silently by the platform, so the item is enqueued at the wrong priority `
+            + `rather than rejected.`, `priority: '${nearestName(String(inputs.priority), QUEUE_PRIORITIES) ?? 'Normal'}'`);
+    }
+    for (const field of ['deferDate', 'dueDate']) {
+        const v = inputs?.[field];
+        if (typeof v === 'string' && v.trim() !== '' && Number.isNaN(Date.parse(v))) {
+            at('QUEUE_BAD_DATE', `Queue step "${step}"'s \`${field}\` is ${JSON.stringify(v)}, which is not a date `
+                + `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`);
+    }
+}
+/** The three priorities `core.action.queue.create[-and-wait]`'s form offers. */
+const QUEUE_PRIORITIES = ['Low', 'Normal', 'High'];

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

@@ -0,0 +1,49 @@
+/** The Queue family's factory. Moved from core/actions.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md. */
+import { type ActionSpec } from '../../../core/actions.js';
+import type { QueueItemInputs } from './spec.js';
+/**
+ * Declare an Orchestrator QUEUE ITEM step.
+ *
+ * @remarks
+ * A queue is Orchestrator's work list: something puts items on it, and an
+ * automation bound to the queue takes them off one at a time. This step is the
+ * putting-on half.
+ *
+ * `queue` + `folderPath` are what the runtime resolves the queue by, and `key` is
+ * the queue's own Orchestrator key: it joins this node to the flow's queue
+ * bindings, which the serializer emits and points the node at. All three, for the
+ * same reason `rpaWorkflow` takes three — the key is the AUTHORING identity, the
+ * two bindings are the RUNTIME one.
+ *
+ * `item` is the work item's data. It becomes the item's `SpecificContent`, and it
+ * must be FLAT: Orchestrator rejects a nested object or array outright.
+ *
+ * **`wait`** picks between the family's two node types, which are one construct
+ * with two data paths. Default `false` enqueues and moves on, publishing the queue
+ * item's own Orchestrator record — read a field with `out('<step>', 'Key')`, and
+ * nothing extra has to be declared because that record's shape is the same for
+ * every queue. `wait: true` PARKS the flow until the item has been processed and
+ * publishes the consumer's result instead, which is per-automation — so a read of
+ * it needs `returns`, exactly as an rpa process's output does.
+ *
+ * What no rung can tell you: whether anything actually drains this queue. A
+ * `wait: true` step on a queue with no consumer waits until it times out.
+ *
+ * @example
+ * **Enqueue a work item and read its Orchestrator key**
+ * ```ts
+ * .step('enqueue', queueItem({
+ *   queue: 'SupplierInvoices',
+ *   folderPath: 'Shared',
+ *   key: 'fa1a7328-cd17-4525-b5ab-29d86e399312',
+ *   item: { InvoiceId: input('invoiceRef'), Amount: input('amount') },
+ *   reference: 'INV-2031',
+ * }))
+ * .return({ itemKey: out('enqueue', 'Key') })
+ * ```
+ *
+ * @param inputs - The `queue` and `folderPath`, the `item` to add, and whether
+ * to `wait` for it to be processed.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function queueItem(inputs: QueueItemInputs): ActionSpec;

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

@@ -0,0 +1,50 @@
+/** The Queue family's factory. Moved from core/actions.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md. */
+import { builtinActionSpec } from '../../../core/actions.js';
+/**
+ * Declare an Orchestrator QUEUE ITEM step.
+ *
+ * @remarks
+ * A queue is Orchestrator's work list: something puts items on it, and an
+ * automation bound to the queue takes them off one at a time. This step is the
+ * putting-on half.
+ *
+ * `queue` + `folderPath` are what the runtime resolves the queue by, and `key` is
+ * the queue's own Orchestrator key: it joins this node to the flow's queue
+ * bindings, which the serializer emits and points the node at. All three, for the
+ * same reason `rpaWorkflow` takes three — the key is the AUTHORING identity, the
+ * two bindings are the RUNTIME one.
+ *
+ * `item` is the work item's data. It becomes the item's `SpecificContent`, and it
+ * must be FLAT: Orchestrator rejects a nested object or array outright.
+ *
+ * **`wait`** picks between the family's two node types, which are one construct
+ * with two data paths. Default `false` enqueues and moves on, publishing the queue
+ * item's own Orchestrator record — read a field with `out('<step>', 'Key')`, and
+ * nothing extra has to be declared because that record's shape is the same for
+ * every queue. `wait: true` PARKS the flow until the item has been processed and
+ * publishes the consumer's result instead, which is per-automation — so a read of
+ * it needs `returns`, exactly as an rpa process's output does.
+ *
+ * What no rung can tell you: whether anything actually drains this queue. A
+ * `wait: true` step on a queue with no consumer waits until it times out.
+ *
+ * @example
+ * **Enqueue a work item and read its Orchestrator key**
+ * ```ts
+ * .step('enqueue', queueItem({
+ *   queue: 'SupplierInvoices',
+ *   folderPath: 'Shared',
+ *   key: 'fa1a7328-cd17-4525-b5ab-29d86e399312',
+ *   item: { InvoiceId: input('invoiceRef'), Amount: input('amount') },
+ *   reference: 'INV-2031',
+ * }))
+ * .return({ itemKey: out('enqueue', 'Key') })
+ * ```
+ *
+ * @param inputs - The `queue` and `folderPath`, the `item` to add, and whether
+ * to `wait` for it to be processed.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function queueItem(inputs) {
+    return builtinActionSpec({ kind: 'queueItem', inputs });
+}

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

@@ -0,0 +1,3 @@
+/** The Queue node family, as flow-node-registry.ts lists it: `core.action.queue.create[-and-wait]`. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const queueFlowFamily: FlowNodeFamily;

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

@@ -0,0 +1,8 @@
+import { QUEUE_DIAGNOSTICS } from './check.js';
+import { queueNodeTypes } from './node-type.js';
+export const queueFlowFamily = {
+    id: 'queue',
+    title: 'Queue',
+    types: queueNodeTypes,
+    diagnostics: QUEUE_DIAGNOSTICS,
+};

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

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

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

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

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

@@ -0,0 +1,8 @@
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+import type { QueueItemInputs } from './spec.js';
+/** The spec both queue node types read. */
+export type QueueItemSpec = {
+    kind: 'queueItem';
+    inputs: QueueItemInputs;
+};
+export declare const queueNodeTypes: FlowVersionedNodeType<QueueItemSpec>[];

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

@@ -0,0 +1,265 @@
+import { Expr } from '../../../core/expr.js';
+import { jsonClone } from '../../../core/json-file.js';
+import { checkQueueItem } from './check.js';
+import { QUEUE_ITEM_RECORD_SCHEMA } from './record.js';
+const CREATE = 'core.action.queue.create';
+const CREATE_AND_WAIT = 'core.action.queue.create-and-wait';
+/**
+ * Build the definition for one queue-item node.
+ *
+ * Unlike `rpaWorkflowDef`, this one starts from the BUNDLED definition — the queue
+ * node types are generic (no tenant key in the type), so the platform's own copy
+ * can be shipped and is: `core-definitions.json` carries both at `@1.2`, verbatim
+ * from the catalogue the running `uip` consults (`@uipath/flow-core/manifest`'s
+ * `ootbNodes`). A test pins that the emitted definition is that copy plus exactly
+ * the three per-instance edits below, so the bundled snapshot stays diffable
+ * against upstream.
+ *
+ * VERSION 1.2, not the 1.0 the bundled sample carries. The platform is two
+ * migrations on, and both are semantic: 1.0 → 1.1 re-types `itemData` from
+ * `string` to `object`, and 1.1 → 1.2 makes the field validate as an object
+ * expression. `shared/sample-flows/queue-operations.flow` is v1.0-era (a JSON
+ * STRING in `itemData`) and dated 2026-05-20 — the shape the platform no longer
+ * writes. Reading it for the surface would have shipped the wrong field TYPE.
+ *
+ * The three per-instance edits:
+ *
+ *  - `model.bindings.resourceKey` — the queue's own Orchestrator key. The shipped
+ *    definition ships it BLANK, because only an instance knows which queue.
+ *  - `model.context` — the `=bindings.<id>` references. The definition ships
+ *    `<bindings.name>` placeholders; an instance names the actual binding ids,
+ *    which is the second way `resourceBindings` can be resolved and the
+ *    shape the bundled sample has.
+ *  - `outputDefinition.output.schema` — the queue item's record for a plain
+ *    create, or the author's `returns` for a create-and-wait. Without a schema a
+ *    downstream read is unresolvable.
+ */
+function queueItemDef(spec, nodeType, stepName, ids, base) {
+    // The template at the version being emitted: the registry resolved it exactly
+    // (an unregistered pin is NODE_VERSION_UNREGISTERED before this runs).
+    if (!base)
+        throw new Error(`no bundled definition for "${nodeType}"`);
+    const def = jsonClone(base);
+    def.model.bindings.resourceKey = spec.key;
+    def.model.context = [
+        { name: 'name', type: 'string', value: `=bindings.${ids.name}`, default: spec.queue },
+        { name: 'folderPath', type: 'string', value: `=bindings.${ids.folderPath}`, default: spec.folderPath },
+        { name: '_label', type: 'string', value: stepName },
+    ];
+    const schema = spec.wait
+        ? (spec.returns && Object.keys(spec.returns).length
+            ? {
+                type: 'object',
+                properties: Object.fromEntries(Object.entries(spec.returns).map(([k, t]) => [k, { type: t }])),
+            }
+            : undefined)
+        : jsonClone(QUEUE_ITEM_RECORD_SCHEMA);
+    if (schema)
+        def.outputDefinition.output.schema = schema;
+    return def;
+}
+/**
+ * The two bindings a queue reference carries — the same `name` + `folderPath` pair
+ * the process families use, keyed to the queue's own Orchestrator key rather than
+ * to a `<folderPath>.<name>` string. That is what the only queue instance the repo
+ * has (`sample-flows/queue-operations.flow`) uses, and it is the queue's stable
+ * identity: a queue can be renamed, its key cannot.
+ *
+ * ONE PAIR PER QUEUE, not per step. Bindings are addressed by
+ * `resource + resourceKey + propertyAttribute` — that is the key a bindings
+ * lookup map is built on — so a second pair for the same queue is not a second
+ * reference, it is a duplicate that shadows the first: both nodes resolve to
+ * whichever was inserted last, and the other pair sits in the file referenced by
+ * nothing. So two steps on the same queue SHARE these, and the ids come from the
+ * queue rather than from a step name.
+ *
+ * (The rpa family mints its pair from the STEP name, so two steps starting the same
+ * process emit the same duplicate-and-shadow shape. Nothing exercises it today —
+ * every rpa flow in the repo has one process step — and changing those ids would
+ * rewrite the rpa goldens, so it is recorded as a finding rather than fixed here.)
+ */
+function queueItemBindings(spec, existing) {
+    const found = (attr) => [...existing.values()].find((b) => b.resource === 'queue' && b.resourceKey === spec.key && b.propertyAttribute === attr)?.id;
+    const already = { name: found('name'), folderPath: found('folderPath') };
+    if (already.name && already.folderPath) {
+        return { ids: { name: already.name, folderPath: already.folderPath }, entries: [] };
+    }
+    // A readable, stable id per queue. Two queues that share a NAME across folders
+    // would collide, so the id is suffixed until it is free.
+    const slug = spec.queue.replace(/[^A-Za-z0-9]/g, '') || 'Queue';
+    let base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}`;
+    for (let n = 2; existing.has(`${base}Name`) || existing.has(`${base}FolderPath`); n++) {
+        base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}${n}`;
+    }
+    const ids = { name: `${base}Name`, folderPath: `${base}FolderPath` };
+    return {
+        ids,
+        entries: [
+            {
+                id: ids.name,
+                name: 'name',
+                type: 'string',
+                resource: 'queue',
+                resourceKey: spec.key,
+                default: spec.queue,
+                propertyAttribute: 'name',
+            },
+            {
+                id: ids.folderPath,
+                name: 'folderPath',
+                type: 'string',
+                resource: 'queue',
+                resourceKey: spec.key,
+                default: spec.folderPath,
+                propertyAttribute: 'folderPath',
+            },
+        ],
+    };
+}
+/** A read of a queue step's output: `QUEUE_READ_*`, in the wording the rule had before the port. */
+const read = (wait) => ({
+    codePrefix: 'QUEUE',
+    label: wait ? 'Queue wait' : 'Queue item',
+    whenUndeclared: `What the consumer writes into the processed item's result is that automation's business; `
+        + `declare the fields you read.`,
+});
+/**
+ * A plain enqueue publishes the queue ITEM's Orchestrator record (fixed, from
+ * `QUEUE_ITEM_RECORD_SCHEMA`); a `wait: true` publishes the processed result,
+ * whose fields only the author's `returns` states.
+ */
+function queueOutput(inputs, wait) {
+    if (!wait) {
+        const fields = Object.fromEntries(Object.entries(QUEUE_ITEM_RECORD_SCHEMA.properties)
+            .map(([k, v]) => [k, v.type ?? 'any']));
+        return { kind: 'fields', fields, read: read(false) };
+    }
+    const returns = inputs?.returns ?? {};
+    return {
+        kind: 'fields',
+        fields: Object.keys(returns).length ? returns : undefined,
+        read: read(true),
+    };
+}
+/**
+ * The `returns` a create-and-wait was authored with, from the field map
+ * `queueItemDef` wrote into `outputDefinition.output.schema` and `makeNode`
+ * copied onto this node's own `outputs`. Read from the NODE, not the file's
+ * `definitions[]` entry: that holds one copy per `<type>@<version>` (the last
+ * step's), so two wait steps would share one schema. Undefined when the node
+ * carries no field map, which is what an omitted `returns` emits.
+ */
+function liftReturns(node) {
+    const props = node
+        ?.outputs?.output?.schema?.properties;
+    if (!props || typeof props !== 'object')
+        return undefined;
+    const entries = Object.entries(props)
+        .filter(([, v]) => typeof v?.type === 'string')
+        .map(([k, v]) => [k, v.type]);
+    return entries.length ? Object.fromEntries(entries) : undefined;
+}
+function queueAt(typeName, wait) {
+    return {
+        kind: 'queueItem', typeName, version: '1.2', factory: 'queueItem', definition: 'per-tenant', errorPort: true,
+        rawNode: { factory: wait ? 'queueItem({ wait: true })' : 'queueItem()' },
+        serialize: ({ inputs: s }, ctx) => {
+            // 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);
+            for (const b of entries)
+                ctx.bind(b);
+            const manifest = queueItemDef(s, typeName, ctx.step, ids, ctx.definition(typeName, ctx.version));
+            return {
+                definition: { source: 'snapshot', nodeType: typeName, version: ctx.version, manifest },
+                // The result is read as `$vars.<step>.output`, like every other family: the
+                // node's own output block maps the runtime `response` onto the variable
+                // `output` (`source: "=response", var: "output"`), and the product honours
+                // that mapping for both queue variants. The node KEEPS its copy of the model,
+                // as every core action node with a model does.
+                inputs: {
+                    queue: { name: s.queue, folderPath: s.folderPath, key: s.key },
+                    // `itemData`, not `item`: the surface's name is friendlier, the node's is
+                    // the platform's. Rendered one level deep, as the item is FLAT.
+                    itemData: Object.fromEntries(Object.entries(s.item ?? {}).map(([k, v]) => [k, ctx.render(v)])),
+                    priority: s.priority ?? 'Normal',
+                    reference: s.reference === undefined ? '' : ctx.render(s.reference),
+                    deferDate: s.deferDate === undefined ? '' : ctx.render(s.deferDate),
+                    dueDate: s.dueDate === undefined ? '' : ctx.render(s.dueDate),
+                },
+            };
+        },
+        deserialize: (node, ctx) => {
+            const inputs = node.inputs ?? {};
+            const q = (inputs.queue ?? {});
+            // A value as the author wrote it: an expression back to an Expr, a literal
+            // string as itself, any other JSON as is.
+            const value = (raw) => {
+                const text = ctx.sourceText(raw);
+                if (text === undefined)
+                    return raw;
+                return text.startsWith('=js:') ? ctx.expr(text) : text;
+            };
+            // serialize writes '' for an omitted optional; that is not an authored value.
+            const optional = (raw) => {
+                const text = ctx.sourceText(raw);
+                return text === undefined || text === '' ? undefined : value(raw);
+            };
+            const priority = ctx.plainValue(inputs.priority);
+            // A wait's `returns` is the schema serialize wrote for THIS step (the
+            // template ships none), as the node's own `outputs` carries it.
+            const returns = wait ? liftReturns(node) : undefined;
+            return {
+                kind: 'queueItem',
+                inputs: {
+                    queue: q.name, folderPath: q.folderPath, key: q.key,
+                    item: Object.fromEntries(Object.entries((inputs.itemData ?? {}))
+                        .map(([k, v]) => [k, value(v)])),
+                    ...(typeof priority === 'string' ? { priority: priority } : {}),
+                    ...(optional(inputs.reference) !== undefined ? { reference: optional(inputs.reference) } : {}),
+                    ...(optional(inputs.deferDate) !== undefined ? { deferDate: optional(inputs.deferDate) } : {}),
+                    ...(optional(inputs.dueDate) !== undefined ? { dueDate: optional(inputs.dueDate) } : {}),
+                    ...(wait ? { wait: true } : {}),
+                    ...(returns ? { returns } : {}),
+                },
+            };
+        },
+        print: ({ inputs }, ctx) => {
+            const rows = Object.entries(inputs.item ?? {});
+            return {
+                factory: 'queueItem',
+                options: [
+                    ['queue', ctx.string(String(inputs.queue ?? ''))],
+                    ['folderPath', ctx.string(String(inputs.folderPath ?? ''))],
+                    ['key', ctx.string(String(inputs.key ?? ''))],
+                    // An expression as the helper an author writes; any other value as the data
+                    // the node stores, verbatim (a nested value is refused by check, but kept).
+                    ['item', rows.length
+                            ? `{ ${rows.map(([k, v]) => `${ctx.key(k)}: ${v instanceof Expr ? ctx.value(v) : ctx.json(v)}`).join(', ')} }`
+                            : '{}'],
+                    // `Normal` is the definition's default — only a departure was authored.
+                    ['priority', inputs.priority !== undefined && inputs.priority !== 'Normal' ? ctx.string(inputs.priority) : undefined],
+                    ['reference', inputs.reference === undefined ? undefined : ctx.value(inputs.reference)],
+                    ['deferDate', inputs.deferDate === undefined ? undefined : ctx.value(inputs.deferDate)],
+                    ['dueDate', inputs.dueDate === undefined ? undefined : ctx.value(inputs.dueDate)],
+                    ['wait', wait ? 'true' : undefined],
+                    ['returns', inputs.returns && Object.keys(inputs.returns).length
+                            ? `{ ${Object.entries(inputs.returns).map(([k, t]) => `${ctx.key(k)}: ${ctx.string(String(t))}`).join(', ')} }`
+                            : undefined],
+                ],
+            };
+        },
+        check: ({ inputs }, ctx) => checkQueueItem(inputs, ctx),
+        // check collected no expressions for a queue step before the port; unchanged by it.
+        expressions: () => [],
+        output: ({ inputs }) => queueOutput(inputs, wait),
+    };
+}
+function queueType(typeName, wait) {
+    return {
+        kind: 'queueItem', typeName, factory: 'queueItem', defaultVersion: '1.2',
+        versions: { '1.2': queueAt(typeName, wait) },
+        matches: ({ inputs }) => Boolean(inputs?.wait) === wait,
+    };
+}
+export const queueNodeTypes = [queueType(CREATE, false), queueType(CREATE_AND_WAIT, true)];

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

@@ -0,0 +1,92 @@
+/**
+ * The Queue family's authoring types (`core.action.queue.create` and
+ * `core.action.queue.create-and-wait`), and its kind's entry in
+ * `FlowActionSpecs`. Moved from core/actions.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md.
+ */
+import type { ReturnFieldType } from '../../../core/actions.js';
+import type { Expr } from '../../../core/expr.js';
+/** The three priorities an Orchestrator queue item can carry. */
+export type QueuePriority = 'Low' | 'Normal' | 'High';
+export interface QueueItemInputs {
+    /** The queue's name in Orchestrator — e.g. `'SupplierInvoices'`. */
+    queue: string;
+    /** The Orchestrator folder holding the queue — e.g. `'Shared'`. */
+    folderPath: string;
+    /**
+     * The queue's own Orchestrator key (a GUID). It is the JOIN between this node
+     * and the flow's queue bindings — a node which does not reference its bindings
+     * cannot be dispatched — and it is what
+     * the designer's queue picker writes. The RUNTIME resolves the queue by
+     * `queue` + `folderPath`, so all three are needed and none is redundant.
+     *
+     * Find it with `uip or queues list --all-folders`.
+     */
+    key: string;
+    /**
+     * The work item's own data: a FLAT object of primitive values. It becomes the
+     * item's `SpecificContent`, and Orchestrator rejects a nested object or array
+     * with "Property values must be simple (like numbers or text)".
+     */
+    item: Record<string, unknown>;
+    /** Processing priority. Defaults to `'Normal'`, as the node type does. */
+    priority?: QueuePriority;
+    /**
+     * A reference string for the item. Optional in general — but a queue created
+     * with "enforce unique reference" REQUIRES one and rejects a repeat with
+     * `HTTP 409: Duplicate Reference`, so derive it from the flow's input rather
+     * than hard-coding it.
+     *
+     * Which is why it takes an {@link Expr} as well as a literal: the serializer
+     * renders it through the same path as any other value, so
+     * `reference: input('invoiceRef')` and
+     * ``reference: js`${input('invoiceRef')} + "-review"` `` both emit. Typing it
+     * as a bare `string` contradicted the advice directly above and stopped two
+     * of the SDK's own examples compiling.
+     */
+    reference?: string | Expr;
+    /** Earliest the item may be processed, ISO-8601 (e.g. `'2026-08-01T09:00:00Z'`). */
+    deferDate?: string;
+    /** Latest the item should be processed, ISO-8601. What an SLA is measured against. */
+    dueDate?: string;
+    /**
+     * `false` (the default) enqueues and moves on — `core.action.queue.create`.
+     * `true` PARKS the flow until whatever consumes the queue has processed the
+     * item, and publishes that result — `core.action.queue.create-and-wait`.
+     *
+     * The two are one construct with two data paths, so this is one field rather
+     * than two factories. Waiting is not free: nothing completes the item but a
+     * consumer (an RPA process bound to the queue), so a flow that waits on a queue
+     * nobody drains waits forever.
+     */
+    wait?: boolean;
+    /**
+     * Only for `wait: true`: the fields the PROCESSED item's result carries, and
+     * their types (e.g. `{ approved: 'boolean' }`). Required if anything reads the
+     * step's output.
+     *
+     * Why you have to say: what a consumer writes into a transaction's `Output` is
+     * that automation's business, not the queue's — no definition declares it and
+     * authoring happens offline. Without it `$vars.<step>.output.<field>` reads from
+     * an object with no declared fields, and nothing could tell a real field from
+     * a typo.
+     *
+     * `wait: false` needs none: what it publishes is the queue ITEM's own
+     * Orchestrator record (`Key`, `Status`, `Reference`, `SpecificContent`, …),
+     * which is the same for every queue, so the serializer declares it for you.
+     *
+     * @enforcedBy QUEUE_READ_UNKNOWN_FIELD A read must name a field of the record
+     * (`wait: false`) or of this `returns` (`wait: true`).
+     * @enforcedBy QUEUE_READ_WITHOUT_RETURNS Reading a field off a `wait: true` result
+     * requires declaring it here.
+     */
+    returns?: Record<string, ReturnFieldType>;
+}
+declare module '../../../core/actions.js' {
+    interface FlowActionSpecs {
+        /** The spec {@link queueItem} builds. */
+        queueItem: {
+            inputs: QueueItemInputs;
+        };
+    }
+}