@uipath/maestro-builder-sdk 6.8.3 → 6.8.5

package/dist/serialize.js

@@ -14,8 +14,8 @@ import { Expr, toExpr, SCHEDULE_PRESETS, DELAY_PRESETS, parseIxpProjectType, fla
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { bindingSelfNameMessage } from './core/binding-messages.js';
-import { hitlRoutesPerOutcome } from './core/hitl-routing.js';
-import { declaredExits, hasExits } from './core/step-ports.js';
+import { OUTCOME_HANDLE_NODE_TYPES, assertHitlExitInvariant, hitlExitModel, hitlExitViolation, outcomeSlug } from './core/hitl-routing.js';
+import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { buildConfiguration, transportHttpMethod } from './config.js';
 import { stableId } from './core/stable-id.js';
 import { readEventFilter, eventFilterProblem, eventFilterJmes, eventFilterTreeLeaf } from './event-filters.js';
@@ -2793,14 +2793,13 @@ function bindingPath(value, rename) {
     // `__hitlInputBindings` the designer reads back stores the binding verbatim.
     return path.startsWith('vars.') ? path : `vars.${path}`;
 }
-/** `Approve` → `approve`; a name that slugifies to nothing falls back to its index. */
+/**
+ * `Approve` → `approve`; a name that slugifies to nothing falls back to its index.
+ * The same rule that names the `outcome-<id>` ports (`outcomeSlug`), so an id
+ * this writes into `schema.outcomes` is always one a port can name.
+ */
 function outcomeId(name, index) {
-    const slug = String(name ?? '')
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-    return slug || `outcome-${index + 1}`;
+    return outcomeSlug(name, index);
 }
 /**
  * A deterministic UUID for the form schema, derived from the flow and node ids.
@@ -3475,8 +3474,18 @@ function eventDetail(rc, sub, nodeId, opts) {
         errorState: { issues: [] },
     };
 }
-/** Recursively render Exprs nested inside objects/arrays (for connector inputs). */
+/**
+ * Recursively render Exprs nested inside objects/arrays (for connector inputs).
+ *
+ * A lookup token is REFUSED, never rendered. `buildConnectorInputs` swaps every
+ * token it can place — a field's whole value, or an element of an array — so a
+ * token that reaches here sits where nothing resolves it: inside an object value,
+ * or in a custom node's inputs. Recursing into it would put `{"__lookup": …}` on
+ * the wire where the connector expects an id.
+ */
 function renderDeep(val, rename = NO_RENAME) {
+    if (isLookupToken(val))
+        throw new Error(misplacedLookupMessage(val));
     if (val instanceof Expr)
         return renderValue(val, rename);
     if (Array.isArray(val))
@@ -3489,6 +3498,13 @@ function renderDeep(val, rename = NO_RENAME) {
     }
     return val;
 }
+/** Why {@link renderDeep} refused a token: where a lookup CAN go, and what it would have emitted. */
+function misplacedLookupMessage(token) {
+    const { field, by, value } = token.__lookup;
+    return (`lookup('${field}') (${by}=${JSON.stringify(value)}) is in a position no lookup is resolved from: ` +
+        `a lookup() must be the whole value of a connector input, or an element of an array input. ` +
+        `Emitting it here would send a raw {"__lookup": …} object where the connector expects an id.`);
+}
 function newScope(outputs, vars = []) {
     return {
         nodes: [],
@@ -3859,7 +3875,28 @@ export function serialize(built, opts = {}) {
             scope.stepNodeId.set(stepName, id);
         return id;
     }
+    /**
+     * Base and quick-form human tasks emitted so far, by node id. `addEdge` holds
+     * every edge out of one to the product's handle rule (`hitlExitViolation`), so
+     * `completed` on a task with outcomes fails at the edge that would write it;
+     * `assertHitlExitInvariant` repeats the check over each finished scope for the
+     * edges that do not come through here (parked `.stepToRef` rejoins).
+     */
+    const hitlNodes = new Map();
+    /**
+     * Human tasks with an outcome whose path stops at an End while another
+     * outcome continues — read by `.parallel`, whose join would wait forever for
+     * the continuing path (check's HITL_END_OUTCOME_IN_PARALLEL). Two ways in: a
+     * fan-out task's `action: 'End'` outcome, and a `.stepSwitch` outcome with no
+     * arm (it gets an End) or whose arm ends in `.return()`. `why` finishes the
+     * sentence "human task X …" in the refusal.
+     */
+    const hitlEndExits = [];
     function addEdge(scope, from, toNode, toPort = 'input') {
+        const hitlNode = hitlNodes.get(from.node);
+        const refused = hitlNode ? hitlExitViolation(hitlNode, from.port) : undefined;
+        if (refused)
+            throw new Error(`serialize: ${refused}`);
         scope.edges.push({ id: `edge_${edgeSeq++}`, sourceNodeId: from.node, sourcePort: from.port, targetNodeId: toNode, targetPort: toPort });
     }
     let col = 0;
@@ -3959,6 +3996,7 @@ export function serialize(built, opts = {}) {
         for (const vd of child.vars)
             globals.push({ id: vd.name, name: vd.name, direction: 'inout', type: vd.type, ...varMeta(vd) });
         resolveRejoins(scope);
+        assertHitlExitInvariant(scope.nodes, scope.edges);
         typeAgentInputSchemas(scope, globals);
         emitStickyNotes(child, scope);
         const layoutEdges = applyAuthorLayout(child.layout, scope, `subflow "${nodeId}"`);
@@ -4077,13 +4115,11 @@ export function serialize(built, opts = {}) {
         // the shipped `sample-flows/queue-operations.flow` wires its edges to it.
         if (type === NODE_TYPE.queueCreate || type === NODE_TYPE.queueCreateAndWait)
             return 'success';
-        // The human task's definition declares exactly one source handle, `completed`
-        // — it fires when the person submits, whichever outcome they chose. (Per-outcome
-        // handles exist only from typeVersion 1.1 of the node, which this SDK does not
-        // emit; routing on the outcome is a decision downstream, reading `output.Action`,
-        // which is also how flow-v1's own outcome conditions are written.)
-        // — and all three human-task node types declare the same one, so the port is
-        // the same whichever `variant` was named.
+        // Every human-task definition declares one static source handle, `completed`.
+        // It is the real exit only where the product draws it: action-app,
+        // document-validation, and a task with no outcomes. A base or quick-form task
+        // with outcomes leaves on `outcome-<id>` instead (`hitlExitModel`), and never
+        // reaches this function for its tail.
         if (type === NODE_TYPE.hitl || type === NODE_TYPE.hitlQuickForm || type === NODE_TYPE.hitlActionApp
             || type === NODE_TYPE.hitlDocValidation)
             return 'completed';
@@ -5094,28 +5130,31 @@ export function serialize(built, opts = {}) {
         if (spec.kind === 'hitl') {
             const id = stepUid(scope, step.name);
             const hitlType = hitlNodeType(spec.inputs);
-            // Rich options select a newer definition, same rule as the scheduled
-            // trigger's cron: per-outcome routing needs 1.1 (per-outcome
-            // `outcome-<id>` exits) and `exposeError` needs 1.2 (adds the `error`
-            // output; its exits are the same per-outcome handles). A zero- or
-            // one-outcome task stays on the pinned default, byte-identically.
+            // How the task leaves its node — `hitlExitModel` (core/hitl-routing.ts)
+            // has the product rule and what `.step()` means after each shape.
             //
-            // More than one outcome INFERS the routing — see `hitlRoutesPerOutcome`
-            // for the four things that turn that off, one of which is an explicit
-            // `{ version }`, which is what keeps decompile→compile exact.
+            // Only the BASE node has definition versions to select: routing per
+            // outcome picks 1.1 and `exposeError` picks 1.2 (which adds the `error`
+            // output). quick-form draws the same per-outcome handles on the one
+            // definition it has, so it routes per outcome without moving. An explicit
+            // pin wins over the inferred 1.1 — `flow validate` accepts `outcome-<id>`
+            // edges on base@1.0 — but not over `exposeError`, whose output only 1.2
+            // declares. A zero- or one-outcome task stays on the pinned default.
             const pinned = step.options?.version;
-            const outcomeRouted = hitlRoutesPerOutcome(spec.inputs, pinned);
-            const neededVersion = spec.inputs?.exposeError ? '1.2' : outcomeRouted ? '1.1' : undefined;
-            if (neededVersion !== undefined && hitlType !== NODE_TYPE.hitl) {
-                throw new Error(`"${step.name}": outcomePorts/exposeError need the base human task's ${neededVersion} `
-                    + `definition — the '${spec.inputs?.variant}' variant has no per-outcome version. `
-                    + `Drop the variant, or route on out('${step.name}', 'Action') downstream.`);
+            const exitModel = hitlExitModel(spec.inputs, pinned);
+            if (hitlType !== NODE_TYPE.hitl && spec.inputs?.exposeError === true) {
+                throw new Error(`"${step.name}": exposeError needs the base human task's 1.2 definition, which adds the `
+                    + `error output — the '${spec.inputs?.variant}' variant has no such version. Drop the variant or exposeError.`);
             }
-            // Both refusals below can only be reached by an EXPLICIT flag: the
-            // inference already declines on a variant and on a pinned version.
-            if (neededVersion !== undefined && pinned !== undefined && pinned !== neededVersion) {
-                throw new Error(`"${step.name}": ${spec.inputs?.exposeError ? 'exposeError' : 'outcomePorts'} needs the task's ${neededVersion} `
-                    + `definition, but { version: '${pinned}' } pins it. Drop the pin or match it.`);
+            if (spec.inputs?.outcomePorts === true && !OUTCOME_HANDLE_NODE_TYPES.has(hitlType)) {
+                throw new Error(`"${step.name}": outcomePorts: true, but the '${spec.inputs?.variant}' variant reads its outcomes `
+                    + `from its app and leaves on its single 'completed' exit. Route on out('${step.name}', 'Action') downstream.`);
+            }
+            const neededVersion = hitlType !== NODE_TYPE.hitl ? undefined
+                : spec.inputs?.exposeError ? '1.2' : exitModel.shape === 'per-outcome' ? '1.1' : undefined;
+            if (spec.inputs?.exposeError === true && pinned !== undefined && pinned !== '1.2') {
+                throw new Error(`"${step.name}": exposeError needs the task's 1.2 definition, but { version: '${pinned}' } pins it. `
+                    + `Drop the pin or match it.`);
             }
             const node = makeNode(hitlType, id, step.name, { parentId, requestedVersion: pinned ?? neededVersion });
             const { inputs, outputs } = hitlInputs(spec.inputs, id, built.id, step.name, scope.rename);
@@ -5124,15 +5163,19 @@ export function serialize(built, opts = {}) {
             // gives their shape (see hitlInputs), so the instance's version wins.
             node.outputs = outputs;
             scope.nodes.push(node);
+            if (OUTCOME_HANDLE_NODE_TYPES.has(hitlType))
+                hitlNodes.set(id, node);
             for (const t of tails)
                 addEdge(scope, t, id);
-            if (outcomeRouted) {
-                // 1.1+ has no `completed` handle — each outcome is its own exit. The
-                // PRIMARY (first) outcome continues the main path; the author routes
-                // the rest with .stepToList('outcome-<id>', …).
-                const first = spec.inputs.outcomes?.[0];
-                const firstName = typeof first === 'string' ? first : first?.name;
-                return [{ node: id, port: `outcome-${outcomeId(firstName, 0)}` }];
+            if (exitModel.shape === 'per-outcome') {
+                // The PRIMARY (first) outcome continues the main path; the author routes
+                // the rest with .stepToList('outcome-<id>', …) or as .stepSwitch arms.
+                return [{ node: id, port: exitModel.exits[0]?.port ?? `outcome-${outcomeSlug(undefined, 0)}` }];
+            }
+            if (exitModel.shape === 'every-outcome') {
+                // Fan-out: every outcome continues to the next step, each on its own
+                // handle. End outcomes are marked, and `emit` ends them.
+                return exitModel.exits.map((e) => ({ node: id, port: e.port, ...(e.endsProcess ? { endsRun: true } : {}) }));
             }
             return [{ node: id, port: successPort(hitlType) }];
         }
@@ -5370,6 +5413,34 @@ export function serialize(built, opts = {}) {
      * are backward — every deployed rejoin is forward convergence, which is why
      * `check` refuses a backward one outright.
      */
+    /**
+     * An End node on one exit of `nodeId`, so the run FINISHES there — a
+     * `.stepSwitch` exit with no arm, and a fan-out human task's `action: 'End'`
+     * outcome.
+     */
+    function endExit(scope, nodeId, port, stepName, parentId) {
+        const endId = uid(scope, `${stepName}${port.charAt(0).toUpperCase()}${port.slice(1)}End`);
+        const end = makeNode(NODE_TYPE.end, endId, 'End', parentId ? { parentId } : {});
+        end.inputs = {};
+        scope.nodes.push(end);
+        addEdge(scope, { node: nodeId, port }, endId);
+    }
+    /**
+     * Refuse a side exit on a human task's port that the step's tails already
+     * continue from: that would put two edges on one port (flow-builder-sdk#741).
+     * After a fan-out task that is EVERY outcome port. `check` reports the same
+     * as HITL_OUTCOME_PORTS_OFF; this is the compile-side half.
+     */
+    function refuseRewire(method, port, source, tails) {
+        if (!hitlNodes.has(tails[0]?.node ?? '') || !tails.some((t) => t.port === port))
+            return;
+        throw new Error(tails.length > 1
+            ? `${method}('${port}', …) after human task "${source}": every outcome already continues to the next `
+                + `step, '${port}' included, because this task does not route per outcome. Add outcomePorts: true `
+                + `(the first outcome then continues and the others are routed), or route every outcome with .stepSwitch.`
+            : `${method}('${port}', …) after human task "${source}": '${port}' already continues the main path, so `
+                + `routing it here too would put two edges on one port (flow-builder-sdk#741).`);
+    }
     /**
      * A step list hanging off a named PORT of the step just emitted.
      *
@@ -5379,12 +5450,14 @@ export function serialize(built, opts = {}) {
      */
     function emitPortList(step, source, tails, scope, parentId, breakTarget) {
         const handler = step.body;
-        // `emitAction` returns exactly one tail for every action kind — the node's
-        // own success port. Anything else means a new action shape reached here
-        // without being taught about error handling; say so rather than guess.
-        if (tails.length !== 1) {
-            throw new Error(`.stepToList('${step.port}', …) after step "${source}": expected the step to leave exactly one outgoing port, got ${tails.length}.`);
+        // `emitAction` returns one tail for every action kind — the node's own
+        // success port — except a fan-out human task, which returns one per outcome
+        // from the SAME node. Tails from two nodes mean a new action shape reached
+        // here without being taught about side exits; say so rather than guess.
+        if (tails.length === 0 || tails.some((t) => t.node !== tails[0].node)) {
+            throw new Error(`.stepToList('${step.port}', …) after step "${source}": expected the step to leave from exactly one node, got ${tails.length} tail(s).`);
         }
+        refuseRewire('.stepToList', step.port, source, tails);
         const nodeId = tails[0].node;
         const node = scope.nodes.find((n) => n.id === nodeId);
         if (!node)
@@ -5451,12 +5524,33 @@ export function serialize(built, opts = {}) {
                 throw new Error(`label on "${step.name}": emitted node not found.`);
             node.display = { ...(node.display ?? {}), label };
         };
-        for (const step of steps) {
+        for (const [stepIndex, step] of steps.entries()) {
             if (step.kind === 'action') {
                 tails = emitAction(step, tails, scope, parentId);
                 applyUpdates(step);
                 applyLabel(step);
                 lastAction = step.name;
+                // A fan-out human task's `action: 'End'` outcomes end the run here: the
+                // flow runtime never reads `action`, so only an End node can. When the
+                // very next step is a `.return()` they join it instead — it is an End
+                // already, and it writes the flow's return values on that path too.
+                if (tails.some((t) => t.endsRun)) {
+                    // Side exits attach to the task; the step that CONTINUES it is the
+                    // first one after them (check's HITL_UNREACHABLE_AFTER reads the same).
+                    const joinsReturn = steps.slice(stepIndex + 1)
+                        .find((x) => x.kind !== 'stepToList' && x.kind !== 'stepToRef')?.kind === 'return';
+                    const continuing = [];
+                    for (const t of tails) {
+                        if (t.endsRun && !joinsReturn)
+                            endExit(scope, t.node, t.port, step.name, parentId);
+                        else
+                            continuing.push({ node: t.node, port: t.port });
+                    }
+                    if (!joinsReturn && continuing.length > 0) {
+                        hitlEndExits.push({ scope, parentId, step: step.name, why: "ends the run on an action: 'End' outcome" });
+                    }
+                    tails = continuing;
+                }
             }
             else if (step.kind === 'stepToList') {
                 tails = emitPortList(step, lastAction ?? '?', tails, scope, parentId, breakTarget);
@@ -5489,6 +5583,9 @@ export function serialize(built, opts = {}) {
                     throw new Error(`.stepSwitch("${step.name}"): emitted node not found.`);
                 const armTails = [];
                 const routed = new Set();
+                // Outcomes of a human task whose path stops at an End: an arm that ends
+                // in `.return()` here, an outcome with no arm below.
+                const stopped = [];
                 for (const c of step.cases) {
                     const exit = exits.find((e) => e.value === c.value);
                     if (!exit) {
@@ -5501,7 +5598,12 @@ export function serialize(built, opts = {}) {
                     // from all of them. (`.stepToList` instead gives each arm a private
                     // End, which silently drops the flow's outputs on that path —
                     // flow-builder-sdk#742.)
-                    armTails.push(...emit(c.body, [{ node: nodeId, port: exit.port }], scope, parentId, breakTarget));
+                    const caseTails = emit(c.body, [{ node: nodeId, port: exit.port }], scope, parentId, breakTarget);
+                    if (caseTails.length === 0 && stopsAtEnd(c.body))
+                        stopped.push(String(c.value));
+                    armTails.push(...(hitlNodes.has(nodeId)
+                        ? caseTails.map((t) => (t.humanSwitch ? t : { ...t, humanSwitch: step.name }))
+                        : caseTails));
                 }
                 // A declared exit with no arm gets an End, so the run FINISHES there
                 // rather than reaching a port with no edge and stalling. `check` warns
@@ -5516,13 +5618,20 @@ export function serialize(built, opts = {}) {
                 // `End`. What the action changes is the WARNING, not the edge: nobody
                 // needs to be told to write an arm for an outcome that ends the run.
                 for (const e of exits) {
-                    if (routed.has(e.port))
-                        continue;
-                    const endId = uid(scope, `${step.name}${e.port.charAt(0).toUpperCase()}${e.port.slice(1)}End`);
-                    const end = makeNode(NODE_TYPE.end, endId, 'End', parentId ? { parentId } : {});
-                    end.inputs = {};
-                    scope.nodes.push(end);
-                    addEdge(scope, { node: nodeId, port: e.port }, endId);
+                    if (!routed.has(e.port)) {
+                        endExit(scope, nodeId, e.port, step.name, parentId);
+                        stopped.push(String(e.value));
+                    }
+                }
+                // On a human task those Ends sit beside the arms that continue, and only
+                // one outcome fires. Inside a `.parallel` arm the join then waits
+                // forever for the continuing path, as for an `action: 'End'` outcome.
+                if (hitlNodes.has(nodeId) && stopped.length > 0 && armTails.length > 0) {
+                    hitlEndExits.push({
+                        scope, parentId, step: step.name,
+                        why: `stops at an End on outcome${stopped.length === 1 ? '' : 's'} ${stopped.join(', ')} of its `
+                            + `.stepSwitch (no arm, or an arm that ends in .return())`,
+                    });
                 }
                 tails = armTails;
                 lastAction = step.name;
@@ -5590,9 +5699,49 @@ export function serialize(built, opts = {}) {
                 // tail and so contributes no incoming edge; that is rejected at rung 1
                 // too (PARALLEL_ARM_RETURNS), since a BPMN join waits for every branch —
                 // UNLESS no arm reaches the join at all, which is the next paragraph.
+                // The join waits for a token on EVERY incoming edge, and a fan-out human
+                // task's outcome edges are mutually exclusive — only one fires. So two
+                // of them straight into the join, or an End outcome beside a continuing
+                // one, hang the run with no incident. check reports both
+                // (HITL_FAN_OUT_INTO_JOIN, HITL_END_OUTCOME_IN_PARALLEL); this is the
+                // compile-side half, and it fails closed.
                 const armTails = [];
-                for (const arm of step.arms)
-                    armTails.push(...emit(arm, tails, scope, parentId, breakTarget));
+                const endsBefore = hitlEndExits.length;
+                for (const arm of step.arms) {
+                    const t = emit(arm, tails, scope, parentId, breakTarget);
+                    // An arm hands the join ONE edge, or several that are alternatives —
+                    // `.branch` / `.switch` / `.stepSwitch` arms, a fan-out task's
+                    // outcomes — of which only one fires. Refused when any of them is a
+                    // human task's outcome edge: however the task got there (at the arm's
+                    // end, one empty `.stepSwitch` arm beside a body, one side of a
+                    // `.branch`), the join waits for all of them. Rejoining arms with no
+                    // human task in them are the older, general case (still emitted).
+                    const outcomeTail = t.find((x) => hitlNodes.has(x.node) && x.port.startsWith('outcome-'));
+                    // The same holds when each outcome's arm ended on a step of its own:
+                    // a complete `.stepSwitch` with nothing after it hands the join one
+                    // edge per arm, and still only one arm runs.
+                    const switchTail = outcomeTail ? undefined : t.find((x) => x.humanSwitch !== undefined);
+                    if (t.length >= 2 && switchTail) {
+                        throw new Error(`.parallel("${step.name}"): an arm sends ${t.length} alternative edges into join "${step.name}" — `
+                            + `among them the end of an arm of human task "${switchTail.humanSwitch}"'s .stepSwitch — and only one `
+                            + `of them fires, while the join waits for all of them. Add a step at the end of the arm, after the `
+                            + `.stepSwitch, so its arms meet there first, or move the task out of the .parallel.`);
+                    }
+                    if (t.length >= 2 && outcomeTail) {
+                        throw new Error(`.parallel("${step.name}"): an arm sends ${t.length} alternative edges into join "${step.name}" — `
+                            + `among them outcome edge "${outcomeTail.port}" of human task "${outcomeTail.node}" — and only one `
+                            + `of them fires, while the join waits for all of them. Add a step at the end of the arm so its paths `
+                            + `meet there first, or move the task out of the .parallel.`);
+                    }
+                    armTails.push(...t);
+                }
+                const starved = hitlEndExits.slice(endsBefore).find((x) => x.scope === scope && x.parentId === parentId);
+                if (starved && armTails.length > 0) {
+                    throw new Error(`.parallel("${step.name}"): human task "${starved.step}" ${starved.why} inside an arm, and join `
+                        + `"${step.name}" would wait forever for the path that continues. Give every outcome a path that `
+                        + `continues to the end of the arm (drop action: 'End', add the missing .stepSwitch arm, move the `
+                        + `.return() after the .parallel), or move the task out of the .parallel.`);
+                }
                 // When EVERY arm is terminal — a terminate, or an End — there is nothing
                 // left to join, and emitting a Merge would add a node with no incoming
                 // edge, which is unreachable. The platform's own flows agree:
@@ -5714,6 +5863,7 @@ export function serialize(built, opts = {}) {
                     const from = tails[0];
                     if (!from)
                         throw new Error(`.stepToRef('${step.port}', '${step.target}') has no step to leave from.`);
+                    refuseRewire('.stepToRef', step.port, lastAction ?? '?', tails);
                     if (step.port === 'error') {
                         const node = scope.nodes.find((n) => n.id === from.node);
                         if (node)
@@ -5866,6 +6016,7 @@ export function serialize(built, opts = {}) {
         }
     }
     resolveRejoins(root);
+    assertHitlExitInvariant(root.nodes, root.edges);
     typeAgentInputSchemas(root, globals);
     emitStickyNotes(built, root);
     const rootLayoutEdges = applyAuthorLayout(built.layout, root, `flow "${built.id}"`);
@@ -5984,16 +6135,35 @@ function buildConnectorInputs(rc, inputs, rename = NO_RENAME, resolutions = {},
         // NOT rendered as a placeholder: emitting something for a value nobody
         // resolved would produce a flow that compiles and then talks to the wrong
         // record, which is exactly the failure the lookup surface exists to remove.
-        if (isLookupToken(nested.value)) {
-            const resolved = resolvedValue(nested.value, resolutions);
-            if (resolved === undefined) {
-                if (policy.unresolvedLookups !== 'ignore')
-                    errs.push(unresolvedLookupMessage(nested.value));
+        //
+        // A token is swapped wherever the field's value can hold one: the whole
+        // value, or an element of an array at any depth. A multiselect is
+        // `users: [lookup(…), lookup(…)]` — the form `ConnectorLookupValue`'s array
+        // branch types and the generated `## Example` prints — and until this swapped
+        // only the whole-value case, so every token inside the array reached
+        // validation as an object ("expected string, got object") with every lookup
+        // recorded. An unresolved element under 'ignore' becomes `null`, which
+        // validation skips, so `check` still type-checks the resolved siblings.
+        const unresolved = [];
+        const swapped = swapLookupTokens(nested.value, resolutions, unresolved);
+        if (unresolved.length) {
+            if (policy.unresolvedLookups !== 'ignore') {
+                for (const token of unresolved)
+                    errs.push(unresolvedLookupMessage(token));
                 continue;
             }
-            nested = { ...nested, value: resolved };
+            if (isLookupToken(nested.value))
+                continue;
         }
-        validateConnectorFieldValue(f, nested.value, flat ? 0 : nested.projectedArrays, errs);
+        nested = { ...nested, value: swapped };
+        // A FLAT key whose wire name ends in `[*]` names one array: an array value
+        // there is checked element by element, as the nested form is. A flat scalar
+        // keeps depth 0 and is emitted as the scalar it is — the product wraps it
+        // into a one-element list (flow-v1 `convertDotNotationToNested`).
+        const depth = flat
+            ? (f.name.endsWith('[*]') && Array.isArray(nested.value) ? 1 : 0)
+            : nested.projectedArrays;
+        validateConnectorFieldValue(f, nested.value, depth, errs);
         if (f.location === 'multipart') {
             partValues.set(f.name, renderDeep(nested.value, rename));
             continue;
@@ -6061,6 +6231,29 @@ function buildConnectorInputs(rc, inputs, rename = NO_RENAME, resolutions = {},
     }
     return slots;
 }
+/**
+ * `value` with every lookup token swapped for its recorded id: the value itself,
+ * or the elements of an array at any depth. An unrecorded token is pushed to
+ * `unresolved` and stands as `null`, so an array keeps its length.
+ *
+ * Objects are NOT descended: a lookup's place is a field's value or an element
+ * of an array field (`ConnectorLookupValue`), and a nested path such as
+ * `contacts[*].id` reaches here already projected to its leaf array. A token
+ * anywhere else is refused by {@link renderDeep}.
+ */
+function swapLookupTokens(value, resolutions, unresolved) {
+    if (isLookupToken(value)) {
+        const resolved = resolvedValue(value, resolutions);
+        if (resolved === undefined) {
+            unresolved.push(value);
+            return null;
+        }
+        return resolved;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => swapLookupTokens(item, resolutions, unresolved));
+    return value;
+}
 /**
  * `inputMetadata.multipart.bodyFieldName` names the CONTAINER part — the one the
  * runtime composes from `bodyParameters`. Measured on the designer's own nodes in

package/lib/library-json.samples/index.json

@@ -100,6 +100,15 @@
       "objectName": "create_issue",
       "path": "uipath-atlassian-jira/generic/create_issue/create@1.0.0.json"
     },
+    {
+      "nodeType": "uipath.connector.uipath-getresponse-getresponse.send-newsletter",
+      "version": "1.0.0",
+      "connectorKey": "uipath-getresponse-getresponse",
+      "label": "Send Newsletter",
+      "activityType": "Curated",
+      "objectName": "NewslettersSend-draft",
+      "path": "uipath-getresponse-getresponse/send-newsletter@1.0.0.json"
+    },
     {
       "nodeType": "uipath.connector.uipath-google-vertex.execute-google-vertex-agent",
       "version": "1.0.0",
@@ -136,6 +145,15 @@
       "objectName": "triggerFlow",
       "path": "uipath-microsoft-powerautomate/invoke-a-microsoft-power-automate-flow@1.0.0.json"
     },
+    {
+      "nodeType": "uipath.connector.uipath-salesforce-slack.create-group-direct-message",
+      "version": "1.0.0",
+      "connectorKey": "uipath-salesforce-slack",
+      "label": "Create Group Direct Message",
+      "activityType": "Curated",
+      "objectName": "conversations_open",
+      "path": "uipath-salesforce-slack/create-group-direct-message@1.0.0.json"
+    },
     {
       "nodeType": "uipath.connector.uipath-salesforce-slack.send-message-to-user",
       "version": "1.0.0",