@uipath/maestro-builder-sdk 6.8.2 → 6.8.4

package/dist/decompile.js

@@ -37,6 +37,7 @@ import { inferScriptShape } from './core/script-return.js';
 import { DEFAULT_TRIGGER_ID } from './core/expr.js';
 import { parseIxpProjectType } from './core/actions.js';
 import { readFlowGlobals } from './flow-variables.js';
+import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
 import { eventFilterFromTreeLeaf } from './event-filters.js';
 /**
  * The trigger id of the flow currently being decompiled, so a reference through a
@@ -410,13 +411,43 @@ class Graph {
         const first = outcomes[0]?.id;
         return typeof first === 'string' && first !== '' ? `outcome-${first}` : undefined;
     }
+    /**
+     * A base or quick-form human task whose EVERY outcome is wired, all to ONE
+     * step, with no other exit edge — what `serialize` emits for `.step()` after a
+     * task that does not route per outcome (quick-form's default, a pinned 1.0,
+     * `outcomePorts: false`), and what the designer saves when every outcome
+     * handle is dragged to the same node. It decompiles to a `.step()` with
+     * `outcomePorts: false` (2+ outcomes), which recompiles to the same edges.
+     *
+     * A base task on its 1.1/1.2 definition is left out on purpose: that version
+     * IS its routing (`outcomePorts: true` / `exposeError: true` select it), and
+     * it already round-trips exactly as a `.stepSwitch` with empty arms.
+     */
+    convergedFanOut(id) {
+        const n = this.byId.get(id);
+        if (!n || !OUTCOME_HANDLE_NODE_TYPES.has(String(n.type)) || versionRoutesHitl(n))
+            return false;
+        const ids = outcomeIdsOfNode(n);
+        if (ids.length === 0)
+            return false;
+        const exits = this.outEdges(id).filter((e) => e.sourcePort !== 'error' && !ARTIFACT_PORTS.has(e.sourcePort));
+        if (exits.length !== ids.length)
+            return false;
+        const ports = new Set(exits.map((e) => e.sourcePort));
+        if (!ids.every((i) => ports.has(`outcome-${i}`)))
+            return false;
+        return new Set(exits.map((e) => e.targetNodeId)).size === 1;
+    }
     /**
      * Every declared exit of `id`, when ALL of them are wired — the `.stepSwitch`
      * shape. `undefined` otherwise, which leaves the node with a tacit main path
-     * and its siblings as side arms.
+     * and its siblings as side arms — and for a converged fan-out, whose one
+     * target is the main path.
      */
     fullyWiredExits(id) {
         const node = this.byId.get(id);
+        if (this.convergedFanOut(id))
+            return undefined;
         const declared = node ? declaredExitsOfNode(node) : undefined;
         if (declared === undefined || declared.length < 2)
             return undefined;
@@ -609,7 +640,7 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
         case T.hitlQuickForm:
         case T.hitlActionApp:
         case T.hitlDocValidation:
-            return emitHitl(node, imp, inputNames);
+            return emitHitl(node, imp, inputNames, graph);
         case T.queueCreate:
         case T.queueCreateAndWait: {
             // `itemData` is the node's name for the surface's `item` (the reference
@@ -1320,7 +1351,7 @@ function emitAgentCluster(node, imp, inputNames, graph) {
  * definition's own `inputDefaults.recipient` for delivery. Recovering those
  * would add arguments the author never wrote to every task.
  */
-function emitHitl(node, imp, inputNames) {
+function emitHitl(node, imp, inputNames, graph) {
     const i = (node.inputs ?? {});
     const schema = (i.schema ?? {});
     const plain = (v) => {
@@ -1417,11 +1448,39 @@ function emitHitl(node, imp, inputNames) {
         ['render', render !== undefined && render !== 'standard' ? str(render) : undefined],
         ['taxonomy', stationExpr(i.taxonomy)],
     ]);
-    // Per-outcome exits and the error output are VERSION-selected: 1.1 routes per
-    // outcome, 1.2 adds the error output (and implies the routing).
+    // On the base node the VERSION says it: 1.1 routes per outcome, 1.2 adds the
+    // error output (and implies the routing). Everywhere else — quick-form, a
+    // base task on 1.0 — the EDGES say it: outcomes that lead to different places
+    // are routed per outcome (`outcomePorts: true`, which a pinned 1.0 keeps at
+    // 1.0), and outcomes that all lead to one step are a fan-out, which the
+    // task's default recompiles to.
     const version = String(node.typeVersion ?? '');
     const exposeError = version === '1.2';
-    const outcomePorts = version === '1.1';
+    const outEdges = graph?.outEdges(node.id) ?? [];
+    const derivesHandles = OUTCOME_HANDLE_NODE_TYPES.has(String(node.type));
+    const outcomePorts = (node.type === T.hitl && version === '1.1')
+        || (derivesHandles && !versionRoutesHitl(node) && graph !== undefined && !graph.convergedFanOut(node.id)
+            && outEdges.some((e) => e.sourcePort.startsWith('outcome-')));
+    // A lone `completed` edge on a task with several outcomes is the shape the
+    // designer stopped drawing: before flow-workbench #3512 (09-08) it was
+    // unconditioned, so every outcome continued down it; since then Studio Web and
+    // the converter remap it to the primary outcome only. Recompiling writes one
+    // `outcome-<id>` edge per outcome to the same step — the first meaning — so
+    // this is the one place decompile→compile is deliberately not exact. Say so.
+    const legacyCompleted = derivesHandles && outcomeIdsOfNode(node).length > 1
+        && outEdges.some((e) => e.sourcePort === 'completed');
+    // Both a converged fan-out and a legacy lone `completed` mean "every outcome
+    // continues to the next step". Say so in the source with `outcomePorts: false`
+    // rather than leaving it to the `{ version }` pin, so the intent survives an
+    // author dropping the pin.
+    const fanOut = !outcomePorts && derivesHandles && !versionRoutesHitl(node) && outcomeIdsOfNode(node).length > 1
+        && (legacyCompleted || graph?.convergedFanOut(node.id) === true);
+    if (legacyCompleted) {
+        warnOnce(`human task ${str(node.id)} leaves on the legacy 'completed' handle, which Studio Web no longer draws `
+            + `once a task has outcomes (it reads the edge as the primary outcome only). Recompiling emits one `
+            + `outcome-<id> edge per outcome to the same step, so every outcome continues — what the edge meant `
+            + `before flow-workbench #3512.`);
+    }
     const title = plain(i.title);
     const priority = plain(i.priority);
     return `${imp.use('hitl')}(${opts([
@@ -1438,7 +1497,7 @@ function emitHitl(node, imp, inputNames) {
         ['fields', fields.length ? `[${fields.join(', ')}]`
                 : (variant === 'action-app' || variant === 'document-validation') ? undefined : '[]'],
         ['outcomes', `[${outcomes.join(', ')}]`],
-        ['outcomePorts', outcomePorts ? 'true' : undefined],
+        ['outcomePorts', outcomePorts ? 'true' : fanOut ? 'false' : undefined],
         ['exposeError', exposeError ? 'true' : undefined],
     ])})`;
 }
@@ -2081,7 +2140,9 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         // A per-outcome human task routes each NON-primary outcome from its own
         // `outcome-<slug>` exit; the primary one continues the main path, so it is
         // already a successor (see Graph.primaryOutcomePort).
-        {
+        // A converged fan-out has none: every outcome continues to the one
+        // successor, which is what `.step()` recompiles to.
+        if (!ctx.graph.convergedFanOut(node.id)) {
             const primary = ctx.graph.primaryOutcomePort(node.id);
             for (const oe of ctx.graph.outEdges(node.id)
                 .filter((e) => e.sourcePort.startsWith('outcome-') && e.sourcePort !== primary)) {
@@ -2165,18 +2226,28 @@ function portArmExits(node, ctx) {
         return undefined;
     return declaredExitsOfNode(node);
 }
+/** A base human task on its 1.1/1.2 definition, where the VERSION selects per-outcome routing. */
+function versionRoutesHitl(node) {
+    const version = String(node.typeVersion ?? '');
+    return node.type === T.hitl && (version === '1.1' || version === '1.2');
+}
+/** The outcome ids in a human task's `inputs.schema.outcomes`. */
+function outcomeIdsOfNode(node) {
+    const outcomes = (node.inputs?.schema?.outcomes ?? []);
+    return outcomes.map((o) => o?.id).filter((id) => typeof id === 'string' && id !== '');
+}
 /**
  * The exits a node declares, read back off the EMITTED artifact rather than off
- * an authored spec — `inputs.schema.outcomes` for a human task at 1.1/1.2,
- * `inputs.branches` plus `default` for an HTTP call. The authoring-side twin is
- * `declaredExits` in `core/step-ports.ts`; they answer about different inputs,
- * which is why this is not a call into it.
+ * an authored spec — `inputs.schema.outcomes` for a base or quick-form human
+ * task (the product draws one `outcome-<id>` handle per outcome on both, at
+ * every version), `inputs.branches` plus `default` for an HTTP call. The
+ * authoring-side twin is `declaredExits` in `core/step-ports.ts`; they answer
+ * about different inputs, which is why this is not a call into it.
  */
 function declaredExitsOfNode(node) {
     const inputs = (node.inputs ?? {});
     if (String(node.type).startsWith('uipath.human-in-the-loop')) {
-        const version = String(node.typeVersion ?? '');
-        if (version !== '1.1' && version !== '1.2')
+        if (!OUTCOME_HANDLE_NODE_TYPES.has(String(node.type)))
             return undefined;
         const outcomes = (inputs.schema?.outcomes ?? []);
         if (outcomes.length === 0)

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.
@@ -3859,7 +3858,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 +3979,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 +4098,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 +5113,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 +5146,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 +5396,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 +5433,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 +5507,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 +5566,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 +5581,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 +5601,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 +5682,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 +5846,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 +5999,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}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.8.2",
+  "version": "6.8.4",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "34be5c196660ad049240339a969f508f67898e19"
+  "gitref": "7620c5d1340ead9f1ef6a5eaff9da5317e0756f1"
 }