@uipath/maestro-builder-sdk 5.4.1 → 6.0.0

package/dist/check.js

@@ -11,6 +11,8 @@ import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './core/l
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
 import { extractRefs } from './core/expr-check.js';
 import { bindingSelfNameMessage } from './core/binding-messages.js';
+import { hitlRoutesPerOutcome } from './core/hitl-routing.js';
+import { declaredExits, hasExits } from './core/step-ports.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
 import { prepareCommand } from './core/cli-spelling.js';
@@ -105,11 +107,14 @@ function checkFlow(built, ancestors, opts = {}) {
     const hitlOutcomeSteps = new Map();
     const hitlOutcomeRouted = new Map();
     // The other half of that bookkeeping: hitl steps that declare a CHOICE (more
-    // than one outcome) and did NOT opt into per-outcome exits, so the graph gives
-    // every outcome the same single exit. Whether that is a mistake depends on
-    // something no single step can see — whether anything downstream reads the
-    // chosen outcome — so the decision waits until the expressions are collected
-    // (see HITL_OUTCOMES_UNREACHABLE below).
+    // than one outcome) and still leave on ONE exit, so every outcome leaves the
+    // node the same way. Since more than one outcome infers per-outcome routing,
+    // reaching this map means the single exit was chosen — by a variant, a pinned
+    // version, or `outcomePorts: false` — and WHICH of the three decides what the
+    // remedy can be. Whether it is a mistake at all depends on something no single
+    // step can see — whether anything downstream reads the chosen outcome — so the
+    // decision waits until the expressions are collected (see
+    // HITL_OUTCOMES_UNREACHABLE below).
     const hitlChoiceNoPorts = new Map();
     const dataFabricUpdates = [];
     // Placeholder (`mock()`) step names. The platform's `core.logic.mock` declares
@@ -174,7 +179,16 @@ function checkFlow(built, ancestors, opts = {}) {
         let prevPortSource;
         /** Collect an expression, stamped with the error handler it sits in (if any). */
         const addExpr = (js, step) => { exprs.push({ js, step, errorSource }); };
-        for (const s of steps) {
+        for (const s0 of steps) {
+            // A `.stepSwitch` IS an action plus its arms, so every action rule below —
+            // name registration, the per-family `check*`, expression collection, the
+            // read maps — has to see it as one. Normalising here rather than
+            // duplicating forty lines is what keeps a new family rule from silently
+            // applying to `.step()` and not to `.stepSwitch()`. The arms and the
+            // stepSwitch-only diagnostics are handled after the loop body.
+            const s = s0.kind === 'stepSwitch'
+                ? { kind: 'action', name: s0.name, spec: s0.spec, ...(s0.options ? { options: s0.options } : {}) }
+                : s0;
             // `return` carries a synthetic `name` that names no node and is not
             // referenceable — registering it would report DUP_STEP the second time one
             // appears. The port-edge kinds carry no name at all.
@@ -201,32 +215,40 @@ function checkFlow(built, ancestors, opts = {}) {
                 }
             }
             // The mirror of HITL_OUTCOME_PORTS_OFF below: `completed` on a human task
-            // that HAS opted into per-outcome exits.
+            // that routes per outcome.
+            //
+            // Per-outcome routing moves the step to the node's 1.1/1.2 definition, and
+            // those declare ONE source handle — `outcome-{item.id}`, repeated over
+            // `inputs.schema.outcomes`. There is no `completed` handle to leave from,
+            // so this edge is refused by the product: `flow validate` answers "Edge
+            // references undeclared source handle \"completed\" on node \"<step>\""
+            // (measured). Without this rule `check` was silent, `compile` emitted it,
+            // and the author found out from validate — or from a consumer that
+            // inspects ports.
             //
-            // Turning on `outcomePorts` (or `exposeError`, which implies it) moves the
-            // step to the node's 1.1/1.2 definition, and those declare ONE source
-            // handle — `outcome-{item.id}`, repeated over `inputs.schema.outcomes`.
-            // There is no `completed` handle to leave from, so this edge is refused by
-            // the product: `flow validate` answers "Edge references undeclared source
-            // handle \"completed\" on node \"<step>\"" (measured). Without this rule
-            // `check` was silent, `compile` emitted it, and the author found out from
-            // validate — or from a consumer that inspects ports.
+            // Since more than one outcome INFERS the routing, this is now also the
+            // rule an author meets when they write the old shape on a multi-outcome
+            // task, so the message names the two ways back to a `completed` exit.
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'completed') {
                 const prevSpec = prevAction?.spec;
                 const isHitl = !!prevSpec && 'kind' in prevSpec && prevSpec.kind === 'hitl';
-                const routed = isHitl
-                    && (prevSpec.inputs?.outcomePorts === true || prevSpec.inputs?.exposeError === true);
+                const routed = isHitl && hitlRoutesPerOutcome(prevSpec.inputs, prevAction?.options?.version);
                 if (routed) {
                     const first = prevSpec.inputs.outcomes?.[0];
                     const firstId = outcomeSlug(typeof first === 'string' ? first : first?.name, 0);
+                    const why = prevSpec.inputs?.exposeError === true ? 'exposeError selects'
+                        : prevSpec.inputs?.outcomePorts === true ? 'outcomePorts selects'
+                            : `its ${(prevSpec.inputs?.outcomes ?? []).length} outcomes select`;
                     diags.push({
                         level: 'error', code: 'HITL_COMPLETED_PORT_GONE', step: prevAction?.name,
-                        message: `Port "completed" does not exist on human task "${prevAction?.name}". `
-                            + `${prevSpec.inputs?.exposeError === true ? 'exposeError' : 'outcomePorts'} selects the node's `
+                        message: `Port "completed" does not exist on human task "${prevAction?.name}". ${why} the node's `
                             + `${prevSpec.inputs?.exposeError === true ? '1.2' : '1.1'} definition, whose only source handle is `
                             + `"outcome-<id>" repeated over the outcomes — the 1.0 definition's single 'completed' exit is not `
                             + `part of it. The FIRST outcome ("outcome-${firstId}") is what continues the main path.`,
-                        suggestion: `route the outcomes (.stepToList('outcome-${firstId}', …)), or drop outcomePorts to keep the 'completed' exit`,
+                        suggestion: prevSpec.inputs?.outcomePorts === true || prevSpec.inputs?.exposeError === true
+                            ? `route the outcomes (.stepToList('outcome-${firstId}', …)), or drop outcomePorts to keep the 'completed' exit`
+                            : `route the outcomes (.stepToList('outcome-${firstId}', …)), or keep the single exit with `
+                                + `outcomePorts: false`,
                     });
                 }
             }
@@ -241,13 +263,24 @@ function checkFlow(built, ancestors, opts = {}) {
                             + `${prevAction ? `"${prevAction.name}" ` : ''}is not a human task.`,
                     });
                 }
-                else if (prevSpec.inputs?.outcomePorts !== true && prevSpec.inputs?.exposeError !== true) {
+                else if (!hitlRoutesPerOutcome(prevSpec.inputs, prevAction?.options?.version)) {
+                    // Reachable three ways now that more than one outcome infers the
+                    // routing: `outcomePorts: false`, a pinned `{ version: '1.0' }`, or a
+                    // variant that has no per-outcome definition to select.
+                    const off = prevSpec.inputs?.outcomePorts === false ? 'outcomePorts: false turns them off'
+                        : prevSpec.inputs?.variant !== undefined
+                            ? `the '${prevSpec.inputs.variant}' variant has no per-outcome definition version`
+                            : prevAction?.options?.version !== undefined
+                                ? `{ version: '${prevAction.options.version}' } pins the definition that has none`
+                                : 'it declares fewer than two outcomes';
                     diags.push({
                         level: 'error', code: 'HITL_OUTCOME_PORTS_OFF', step: prevAction?.name,
                         message: `Port "${s.port}" routes a per-outcome exit, but human task "${prevAction?.name}" `
-                            + `has not opted into them — its single exit is 'completed'. Per-outcome exits are the `
+                            + `does not have them — ${off}, so its single exit is 'completed'. Per-outcome exits are the `
                             + `node's 1.1 definition.`,
-                        suggestion: `outcomePorts: true`,
+                        suggestion: prevSpec.inputs?.variant !== undefined
+                            ? `route on out('${prevAction?.name}', 'Action') downstream`
+                            : `outcomePorts: true`,
                     });
                 }
                 else {
@@ -322,9 +355,15 @@ function checkFlow(built, ancestors, opts = {}) {
                 }
                 if (s.spec.kind === 'mock')
                     mockNames.add(s.name);
-                if (s.spec.kind === 'hitl'
-                    && (s.spec.inputs?.outcomePorts === true || s.spec.inputs?.exposeError === true)) {
-                    hitlOutcomeSteps.set(s.name, (s.spec.inputs.outcomes ?? []).map((o, i) => outcomeSlug(typeof o === 'string' ? o : o?.name, i)));
+                // `.stepSwitch` routes its exits as ARMS, so the `.stepToList` bookkeeping
+                // would report every one of them unrouted. STEP_SWITCH_EXIT_UNROUTED is
+                // that step's version of the same question.
+                if (s0.kind !== 'stepSwitch'
+                    && s.spec.kind === 'hitl' && hitlRoutesPerOutcome(s.spec.inputs, s.options?.version)) {
+                    hitlOutcomeSteps.set(s.name, (s.spec.inputs.outcomes ?? []).map((o, i) => ({
+                        id: outcomeSlug(typeof o === 'string' ? o : o?.name, i),
+                        endsProcess: typeof o !== 'string' && o?.action === 'End',
+                    })));
                 }
                 if (s.spec.kind === 'hitl') {
                     checkHitl(s.name, s.spec.inputs, diags);
@@ -336,10 +375,12 @@ function checkFlow(built, ancestors, opts = {}) {
                     const allEnd = outcomes.length > 0
                         && outcomes.every((o) => typeof o !== 'string' && o?.action === 'End');
                     if (outcomes.length > 1 && !allEnd
-                        && s.spec.inputs?.outcomePorts !== true && s.spec.inputs?.exposeError !== true) {
+                        && !hitlRoutesPerOutcome(s.spec.inputs, s.options?.version)) {
                         hitlChoiceNoPorts.set(s.name, {
                             names: outcomes.map((o) => String((typeof o === 'string' ? o : o?.name) ?? '').trim()),
                             variant: s.spec.inputs?.variant,
+                            pinned: s.options?.version,
+                            portsOff: s.spec.inputs?.outcomePorts === false,
                         });
                     }
                 }
@@ -579,6 +620,76 @@ function checkFlow(built, ancestors, opts = {}) {
                     checkOutputCategory(name, e, outputType, typeOf, diags, triggerId);
                 }
             }
+            // AFTER the dispatch chain, not inside it: `s` was normalised to an action
+            // above, so an `else if` here would be unreachable — which it silently was
+            // on the first cut. The action rules have run by now; what is left is the
+            // arms and the three things only this step can get wrong.
+            if (s0.kind === 'stepSwitch') {
+                const exits = declaredExits(s0.spec, s0.options?.version);
+                if (!hasExits(exits)) {
+                    diags.push({
+                        level: 'error', code: 'STEP_SWITCH_NO_EXITS', step: s0.name,
+                        message: `.stepSwitch("${s0.name}") routes this step's declared exits, but ${exits.reason}, `
+                            + `so there are none to route.`,
+                        ...(exits.suggestion ? { suggestion: exits.suggestion } : {}),
+                    });
+                    for (const c of s0.cases)
+                        walk(c.body, inLoop);
+                }
+                else {
+                    const seenExit = new Set();
+                    for (const c of s0.cases) {
+                        const exit = exits.find((e) => e.value === c.value);
+                        if (!exit) {
+                            const nearest = nearestName(c.value, exits.map((e) => e.value));
+                            diags.push({
+                                level: 'error', code: 'STEP_SWITCH_EXIT_UNKNOWN', step: s0.name,
+                                message: `.stepSwitch("${s0.name}") has an arm for ${JSON.stringify(c.value)}, which is not `
+                                    + `an exit it declares — those are ${exits.map((e) => JSON.stringify(e.value)).join(', ')}.`,
+                                ...(nearest !== undefined ? { suggestion: `value: '${nearest}'` } : {}),
+                            });
+                        }
+                        else if (seenExit.has(exit.port)) {
+                            diags.push({
+                                level: 'error', code: 'STEP_SWITCH_EXIT_DUP', step: s0.name,
+                                message: `.stepSwitch("${s0.name}") has two arms for ${JSON.stringify(c.value)}. A port takes `
+                                    + `exactly one outgoing edge, so put everything that exit needs in one arm.`,
+                            });
+                        }
+                        else {
+                            seenExit.add(exit.port);
+                        }
+                        if (c.body.length === 0) {
+                            diags.push({
+                                level: 'warning', code: 'EMPTY_ARM', step: s0.name,
+                                message: `.stepSwitch("${s0.name}") has an empty arm for ${JSON.stringify(c.value)}.`,
+                            });
+                        }
+                        walk(c.body, inLoop);
+                    }
+                    // An exit with no arm compiles to an End node, so the run FINISHES
+                    // there instead of reaching a port with no edge and stalling. Better
+                    // than stalling, still probably not what the author meant — and the
+                    // End carries none of the flow's output mappings, so the run answers
+                    // with nothing (flow-builder-sdk#742). An `action: 'End'` outcome
+                    // already ends the run and needs no arm.
+                    const unrouted = exits.filter((e) => !seenExit.has(e.port) && e.endsProcess !== true);
+                    if (unrouted.length > 0) {
+                        const outs = built.outputs.map((o) => o.name);
+                        diags.push({
+                            level: 'warning', code: 'STEP_SWITCH_EXIT_UNROUTED', step: s0.name,
+                            message: `.stepSwitch("${s0.name}") has no arm for `
+                                + `${unrouted.map((e) => JSON.stringify(e.value)).join(', ')}. Each compiles to an End node, `
+                                + `so the run finishes there`
+                                + (outs.length > 0
+                                    ? ` without writing the flow's declared output${outs.length === 1 ? '' : 's'} `
+                                        + `(${outs.join(', ')}).`
+                                    : '.'),
+                            suggestion: `{ value: '${unrouted[0].value}', body: (b) => … }`,
+                        });
+                    }
+                }
+            }
         }
     };
     walk(built.steps);
@@ -586,14 +697,34 @@ function checkFlow(built, ancestors, opts = {}) {
         // The FIRST (primary) outcome continues the main path — only the rest need
         // an explicit .stepToList route. An unrouted one deploys, then stalls the
         // run when the reviewer picks it (the designer flags the same, as a warning).
+        //
+        // `action: 'End'` does NOT excuse a route here. It changes the CONSEQUENCE —
+        // the run ends rather than stalling — but the designer draws a handle for
+        // every entry in `inputs.schema.outcomes` whatever its action, so an
+        // unrouted one is a handle wired to nothing either way. UiPath/skills'
+        // `assert_outcome_wiring` requires an edge per outcome with no exemption,
+        // and its convention makes every non-primary outcome an `End`, so exempting
+        // them here produced artifacts that gate refuses. (`.stepSwitch` has no such
+        // gap: an omitted exit compiles to an End node, End action or not.)
         const routed = hitlOutcomeRouted.get(step) ?? new Set();
-        const unrouted = ids.slice(1).filter((id) => !routed.has(id));
+        const unrouted = ids.slice(1).filter((o) => !routed.has(o.id));
         if (unrouted.length > 0) {
+            const names = unrouted.map((o) => `outcome-${o.id}`).join(', ');
+            const stalls = unrouted.filter((o) => !o.endsProcess);
+            const ends = unrouted.filter((o) => o.endsProcess);
             diags.push({
                 level: 'warning', code: 'HITL_OUTCOME_UNROUTED', step,
-                message: `Human task "${step}" routes per outcome, but ${unrouted.map((i) => `outcome-${i}`).join(', ')} `
-                    + `ha${unrouted.length === 1 ? 's' : 've'} no route. The run stalls if the reviewer picks one.`,
-                suggestion: `.stepToList('outcome-${unrouted[0]}', (b) => …)`,
+                message: `Human task "${step}" routes per outcome, but ${names} `
+                    + `ha${unrouted.length === 1 ? 's' : 've'} no route.`
+                    + (stalls.length > 0
+                        ? ` The run stalls if the reviewer picks ${stalls.length === 1 ? 'it' : 'one of those'}.`
+                        : '')
+                    + (ends.length > 0
+                        ? ` ${ends.map((o) => `outcome-${o.id}`).join(', ')} end${ends.length === 1 ? 's' : ''} the run `
+                            + `(action: 'End'), so nothing stalls — but the handle the canvas draws is still wired to `
+                            + `nothing. Route it to a .return() so the graph says where that outcome finishes.`
+                        : ''),
+                suggestion: `.stepToList('outcome-${unrouted[0].id}', (b) => b.return({…}))`,
             });
         }
     }
@@ -3846,24 +3977,30 @@ function outcomeSlug(name, index) {
  * HITL_OUTCOMES_UNREACHABLE — a human task offers the reviewer a CHOICE that
  * nothing downstream can act on.
  *
- * `outcomes` and `outcomePorts` are two halves of one decision, and only the
- * first half reads as load-bearing. Declaring outcomes without the flag emits
- * the node's 1.0 definition, whose ONE source handle is `completed`: the
- * outcomes still reach the reviewer and still appear in
- * `inputs.schema.outcomes`, and then every button the reviewer can press leaves
- * the node the same way. Two outcomes, one path — an approval whose approve and
- * reject arms are indistinguishable is a modelling error, not a style choice,
- * yet it compiles and `flow validate` answers `Valid` (flow-builder-sdk#735).
+ * The single-exit shape publishes the outcomes and routes none of them: the 1.0
+ * definition's ONE source handle is `completed`, so the outcomes reach the
+ * reviewer and `inputs.schema.outcomes`, and then every button the reviewer can
+ * press leaves the node the same way. Two outcomes, one path — an approval whose
+ * approve and reject arms are indistinguishable is a modelling error, not a
+ * style choice, yet it compiles and `flow validate` answers `Valid`
+ * (flow-builder-sdk#735).
+ *
+ * On a plain base task that is no longer reachable: more than one outcome now
+ * INFERS per-outcome routing (`hitlRoutesPerOutcome`, #739), because a warning
+ * alone did not change what agents emitted — #739 measured the diagnostic
+ * firing three times and the unreachable artifact shipping anyway. What is left
+ * for this rule is the cases where the single exit is CHOSEN and the choice may
+ * still be a mistake: a `variant` (no per-outcome definition version exists to
+ * select, #729), a pinned `{ version: '1.0' }`, and an explicit
+ * `outcomePorts: false`.
  *
- * The one thing that makes the single-exit shape correct is a read of the
- * chosen outcome: `out('<step>', 'Action')` feeding a `.switch()` is the
- * DEFAULT documented shape, and it is the only shape the quick-form,
- * action-app and document-validation variants have — they carry no per-outcome
- * definition for `outcomePorts` to select (HITL_OUTCOME_PORTS_VARIANT). So the
- * rule is not "outcomes without ports", which would refuse that shape; it is
- * "outcomes that no exit and no expression distinguishes". That is why it runs
- * here, after `walk`, rather than inside `checkHitl`: the deciding evidence is
- * the rest of the flow.
+ * In all three the shape is correct when something reads the chosen outcome:
+ * `out('<step>', 'Action')` feeding a `.switch()` routes the decision as data,
+ * and it is the ONLY shape the quick-form, action-app and document-validation
+ * variants have. So the rule is not "outcomes without ports", which would
+ * refuse that shape; it is "outcomes that no exit and no expression
+ * distinguishes". That is why it runs here, after `walk`, rather than inside
+ * `checkHitl`: the deciding evidence is the rest of the flow.
  *
  * A read counts when it can SEE the outcome — `.output.Action`, the whole
  * answer object (`out('<step>')` / `$vars.<step>.output`, which carries
@@ -3893,23 +4030,34 @@ function reportUnreachableHitlOutcomes(choices, exprs, diags) {
         for (const m of js.matchAll(/\$vars\.([A-Za-z0-9_]+)\s*\[/g))
             readsOutcome.add(m[1]);
     }
-    for (const [step, { names, variant }] of choices) {
+    for (const [step, { names, variant, pinned, portsOff }] of choices) {
         if (readsOutcome.has(step))
             continue;
         const ids = names.map((n, i) => outcomeSlug(n, i));
+        // Why this task kept the single exit decides which remedy is even legal:
+        // `outcomePorts: true` is refused on a variant and conflicts with a pin, so
+        // offering it there would trade a warning for a compile error.
+        // On a base task with no pin, more than one outcome would have inferred the
+        // routing — so the only way such a task reaches here is `outcomePorts:
+        // false`, and it is the only case where offering the flag is legal.
+        const canTakePorts = variant === undefined && pinned === undefined && portsOff === true;
+        const kept = variant !== undefined
+            ? `The "${variant}" variant has no per-outcome definition version to select`
+            : pinned !== undefined
+                ? `{ version: '${pinned}' } pins the definition whose only exit is 'completed'`
+                : `outcomePorts: false keeps the single exit`;
         diags.push({
             level: 'warning', code: 'HITL_OUTCOMES_UNREACHABLE', step,
             message: `Human task "${step}" declares ${names.length} outcomes (${names.join(', ')}), but nothing `
                 + `downstream tells them apart: the node emits its single 'completed' exit and every outcome leaves `
                 + `on it, and no expression reads out('${step}', 'Action') either. The outcomes reach the reviewer `
-                + `and the artifact; the decision does not reach the flow. `
-                + (variant === undefined
-                    ? `Set outcomePorts: true to give each outcome its own exit (${ids.map((i) => `'outcome-${i}'`).join(', ')}), `
-                        + `or switch on out('${step}', 'Action') to route it as data.`
-                    : `The "${variant}" variant has no per-outcome definition for outcomePorts to select, so switch on `
-                        + `out('${step}', 'Action') to route it as data.`),
-            suggestion: variant === undefined
-                ? 'outcomePorts: true'
+                + `and the artifact; the decision does not reach the flow. ${kept}, so switch on `
+                + `out('${step}', 'Action') to route the decision as data`
+                + (canTakePorts
+                    ? `, or drop outcomePorts: false for per-outcome exits (${ids.map((i) => `'outcome-${i}'`).join(', ')}).`
+                    : '.'),
+            suggestion: canTakePorts
+                ? 'drop outcomePorts: false'
                 : `.switch('route', out('${step}', 'Action'), …)`,
         });
     }

package/dist/core/actions.d.ts

@@ -564,14 +564,16 @@ export interface HitlInputs {
     /**
      * The completion buttons, e.g. `['Approve', 'Reject']`. At least one, or the
      * reviewer has no way to complete the task and the flow waits forever. The
-     * first is the primary (default) one. Declaring them creates no EXITS: with
-     * more than one, set `outcomePorts` to fork in the graph, or read
-     * `out('<step>', 'Action')` to route as data. With neither, every outcome
-     * leaves on the same `completed` exit and nothing downstream can tell them
-     * apart — which `check` warns about as `HITL_OUTCOMES_UNREACHABLE`.
+     * first is the primary (default) one. MORE THAN ONE gives each outcome its own
+     * exit, `outcome-<slug>`: the first continues the main path and the rest are
+     * routed with `.stepToList('outcome-<slug>', …)`. Only
+     * {@link HitlInputs.outcomePorts | outcomePorts}`: false`, a `variant`, an
+     * explicit `{ version }`, or every outcome ending the process keeps the older
+     * single `completed` exit.
      *
-     * Which one they pressed is `out('<step>', 'Action')` — that is what the
-     * platform's own routing conditions compare against, so branch on it.
+     * Which one they pressed is also `out('<step>', 'Action')` — that is what the
+     * platform's own routing conditions compare against, so a task on the single
+     * exit branches on it downstream.
      */
     outcomes: Outcome[];
     /** Who gets the task and how. Omit for the definition's default delivery. */
@@ -579,16 +581,18 @@ export interface HitlInputs {
     /** Action Center labels, comma-separated (the platform stores one string). */
     labels?: string;
     /**
-     * Route each outcome from its OWN port instead of the single `completed`
-     * exit. Selects the node's **1.1** definition, whose exits are
-     * `outcome-<id>` handles (one per outcome; ids are the outcome names
-     * slugified, e.g. `'Approve'` → `outcome-approve`). It REPLACES `completed`
-     * rather than adding to it, and it is not an optional refinement — see
-     * `outcomes` for the choice it is one half of.
-     *
-     * The FIRST (primary) outcome continues the main path; route the others with
-     * `.stepToList('outcome-<id>', …)`. Base variant only — the sub-typed nodes
-     * have no per-outcome definition version.
+     * Whether each outcome exits from its OWN port (`outcome-<id>`) instead of the
+     * single `completed` one. **More than one outcome does this by default**, so
+     * the useful value is `false` — an opt back into the single exit, for a task
+     * that routes the decision as DATA by reading `out('<step>', 'Action')`.
+     *
+     * Per-outcome exits select the node's **1.1** definition, whose handles are
+     * `outcome-<id>` (ids are the outcome names slugified, e.g. `'Approve'` →
+     * `outcome-approve`). They REPLACE `completed` rather than adding to it. The
+     * FIRST (primary) outcome continues the main path; route the others with
+     * `.stepToList('outcome-<id>', …)`, or the run stalls when the reviewer picks
+     * one. Base variant only — the sub-typed nodes have no per-outcome definition
+     * version, so they keep the single exit whatever this says.
      */
     outcomePorts?: boolean;
     /**

package/dist/core/hitl-routing.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Does a human task route PER OUTCOME — one `outcome-<id>` exit each — or leave
+ * on the single `completed` handle?
+ *
+ * Shared by `serialize` (which picks the node's definition version and its tail
+ * port from this) and `check` (whose four outcome-port rules all key on it), so
+ * the two cannot drift. They did drift once, in the direction that matters
+ * least visibly: `check` keyed on the `outcomePorts` FLAG while `serialize` was
+ * about to infer it, which would have made `check` refuse per-outcome wiring
+ * that `compile` then emitted.
+ *
+ * **More than one outcome infers it.** Declaring outcomes creates no exits on
+ * the 1.0 definition — its one source handle is `completed`, so every button
+ * the reviewer can press leaves the node the same way and the decision never
+ * reaches the graph. That shape is only meaningful for a zero- or one-outcome
+ * acknowledgement, and at two or more it compiled, validated `Valid`, and
+ * shipped flows whose approve and reject paths were indistinguishable — first
+ * silently (flow-builder-sdk#735), then past the warning that #738 added
+ * (#739). So the flag is what an author reaches for to *override* the shape,
+ * not what they must remember to switch it on.
+ *
+ * Four things turn the inference off, in this order:
+ *
+ * 1. `outcomePorts: false` — an explicit opt back into the single exit.
+ * 2. A `variant`. The quick-form, action-app and document-validation node types
+ *    carry no per-outcome definition version to select, so `completed` plus a
+ *    `switch` on `out('<step>', 'Action')` is their only shape (#729).
+ * 3. An explicitly pinned `{ version }`. The shape of a deployed artifact is
+ *    recorded in its `typeVersion`, and `decompile` emits that pin — so
+ *    decompiling a 1.0 flow and recompiling it round-trips exactly instead of
+ *    promoting the node to 1.1 and stranding its `completed` edge.
+ * 4. Every outcome carrying `action: 'End'`. The run stops AT the node, so no
+ *    exit can distinguish anything and per-outcome handles would only invite
+ *    routes that can never be taken. The same reasoning suppresses
+ *    HITL_OUTCOMES_UNREACHABLE.
+ */
+import type { HitlInputs } from './actions.js';
+/**
+ * An outcome's stable id — the slug that names its `outcome-<id>` port.
+ *
+ * One definition, because `serialize` emits these ids, `check` validates port
+ * names against them, and `.stepSwitch` resolves an arm's `value` through them.
+ * Three copies of one rule is three chances for a port name to be emitted that
+ * nothing else recognises.
+ */
+export declare function outcomeSlug(name: unknown, index: number): string;
+export declare function hitlRoutesPerOutcome(inputs: HitlInputs | undefined, pinnedVersion?: string): boolean;

package/dist/core/hitl-routing.js

@@ -0,0 +1,33 @@
+/**
+ * An outcome's stable id — the slug that names its `outcome-<id>` port.
+ *
+ * One definition, because `serialize` emits these ids, `check` validates port
+ * names against them, and `.stepSwitch` resolves an arm's `value` through them.
+ * Three copies of one rule is three chances for a port name to be emitted that
+ * nothing else recognises.
+ */
+export function outcomeSlug(name, index) {
+    const slug = String(name ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || `outcome-${index + 1}`;
+}
+export function hitlRoutesPerOutcome(inputs, pinnedVersion) {
+    // `exposeError` selects 1.2, which routes per outcome too. Both flags are
+    // honoured on a variant so that `serialize` still refuses them there with its
+    // own message rather than silently ignoring them.
+    if (inputs?.exposeError === true || inputs?.outcomePorts === true)
+        return true;
+    if (inputs?.outcomePorts === false)
+        return false;
+    if (inputs?.variant !== undefined)
+        return false;
+    if (pinnedVersion !== undefined)
+        return false;
+    const outcomes = inputs?.outcomes ?? [];
+    if (outcomes.length <= 1)
+        return false;
+    return !outcomes.every((o) => typeof o !== 'string' && o?.action === 'End');
+}

package/dist/core/step-ports.d.ts

@@ -0,0 +1,37 @@
+/** One author-named exit: the value an arm matches on, and the port it wires. */
+export interface DeclaredExit {
+    /** What `.stepSwitch()`'s arm `value` matches — the outcome or branch NAME. */
+    value: string;
+    /** The emitted source handle. */
+    port: string;
+    /**
+     * This exit ends the RUN, so it needs no arm and no auto-End: a human-task
+     * outcome with `action: 'End'`.
+     */
+    endsProcess?: boolean;
+    /** The fall-through exit — HTTP's `default`. Last, and optional in an arm list. */
+    isDefault?: boolean;
+}
+/** Why a spec has no routable fan-out, phrased for a diagnostic. */
+export interface NoExits {
+    reason: string;
+    /** What to do instead. */
+    suggestion?: string;
+}
+/**
+ * Structural, not the `FlowActionSpec` union: this module is imported by
+ * `flow-sdk.ts`'s dependents AND describes their specs, so naming the union
+ * here would close a cycle. Every field it reads is optional anyway.
+ */
+type SpecLike = {
+    kind?: string;
+    inputs?: unknown;
+};
+/**
+ * The author-declared exits of `spec`, or a `NoExits` explaining why there are
+ * none to route.
+ */
+export declare function declaredExits(spec: SpecLike | undefined, pinnedVersion?: string): DeclaredExit[] | NoExits;
+/** Narrowing helper — `declaredExits` returns one or the other. */
+export declare function hasExits(r: DeclaredExit[] | NoExits): r is DeclaredExit[];
+export {};

package/dist/core/step-ports.js

@@ -0,0 +1,102 @@
+/**
+ * The exits an action declares that the AUTHOR named — a human task's outcomes,
+ * an HTTP call's response branches — and the port each one leaves on.
+ *
+ * This is what `.stepSwitch()` routes over, and the reason it exists as a table
+ * rather than as two more `if (spec.kind === …)` arms: `serialize` has to turn
+ * an arm's `value` into a port, `check` has to say which values are legal and
+ * which were left out, and `decompile` has to turn a port back into a value.
+ * Those three read the same list here instead of each carrying their own copy
+ * of "how a human task names its ports" and "how an HTTP branch names its
+ * ports".
+ *
+ * `undefined` means the family has no author-declared fan-out at all, which is
+ * what makes `.stepSwitch()` on it an error rather than a no-op.
+ *
+ * The `error` port is deliberately NOT here. It is declared by the definition
+ * rather than by the author, it exists on families that have no other fan-out,
+ * and it is already routed by `.onError()` / `.stepToList('error', …)`. Folding
+ * it in would make every action a `.stepSwitch` candidate and would put failure
+ * handling and outcome routing in one list, where an omitted arm would mean two
+ * different things.
+ */
+import { hitlRoutesPerOutcome, outcomeSlug } from './hitl-routing.js';
+/**
+ * The author-declared exits of `spec`, or a `NoExits` explaining why there are
+ * none to route.
+ */
+export function declaredExits(spec, pinnedVersion) {
+    const kind = spec && 'kind' in spec ? spec.kind : undefined;
+    if (kind === 'hitl') {
+        const inputs = spec?.inputs;
+        const outcomes = (inputs?.outcomes ?? []);
+        if (outcomes.length === 0) {
+            return { reason: 'it declares no outcomes', suggestion: `outcomes: ['Approve', 'Reject']` };
+        }
+        if (!hitlRoutesPerOutcome(inputs, pinnedVersion)) {
+            // WHY it kept the single exit decides what the author can do about it, so
+            // the caller gets the specific one rather than "ports are off".
+            if (inputs?.outcomePorts === false) {
+                return {
+                    reason: 'outcomePorts: false keeps its single `completed` exit',
+                    suggestion: 'Drop `outcomePorts: false`.',
+                };
+            }
+            if (inputs?.variant !== undefined) {
+                return {
+                    reason: `the '${inputs.variant}' variant has no per-outcome definition version to select`,
+                    suggestion: `Drop the variant, or use .step() and switch on out('<step>', 'Action').`,
+                };
+            }
+            if (pinnedVersion !== undefined) {
+                return {
+                    reason: `{ version: '${pinnedVersion}' } pins the definition whose only exit is 'completed'`,
+                    suggestion: 'Drop the pin.',
+                };
+            }
+            if (outcomes.length === 1) {
+                return {
+                    reason: 'a single outcome has a single exit, so there is nothing to route',
+                    suggestion: 'Use .step() — the next step follows it unconditionally.',
+                };
+            }
+            return {
+                reason: 'every outcome ends the process, so no exit distinguishes them',
+                suggestion: 'Use .step().',
+            };
+        }
+        return outcomes.map((o, i) => {
+            const name = (typeof o === 'string' ? o : o?.name) ?? '';
+            return {
+                value: String(name),
+                port: `outcome-${outcomeSlug(name, i)}`,
+                ...(typeof o !== 'string' && o?.action === 'End' ? { endsProcess: true } : {}),
+            };
+        });
+    }
+    if (kind === 'http') {
+        const branches = (spec?.inputs?.branches
+            ?? []);
+        if (branches.length === 0) {
+            return {
+                reason: 'it declares no response branches',
+                suggestion: `branches: [{ name: 'rateLimited', condition: … }]`,
+            };
+        }
+        // The fall-through is an exit like any other here — it is what `.switch()`
+        // spells as its default arm, and leaving it out is the same omission as
+        // leaving out a branch.
+        return [
+            ...branches.map((b) => ({ value: String(b?.name ?? ''), port: `branch-${b?.name ?? ''}` })),
+            { value: 'default', port: 'default', isDefault: true },
+        ];
+    }
+    return {
+        reason: `a ${kind ?? 'custom'} step declares no author-named exits`,
+        suggestion: 'Use .step(); route failures with .onError().',
+    };
+}
+/** Narrowing helper — `declaredExits` returns one or the other. */
+export function hasExits(r) {
+    return Array.isArray(r);
+}

package/dist/decompile.js

@@ -408,16 +408,39 @@ class Graph {
         const first = outcomes[0]?.id;
         return typeof first === 'string' && first !== '' ? `outcome-${first}` : undefined;
     }
+    /**
+     * 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.
+     */
+    fullyWiredExits(id) {
+        const node = this.byId.get(id);
+        const declared = node ? declaredExitsOfNode(node) : undefined;
+        if (declared === undefined || declared.length < 2)
+            return undefined;
+        const wired = new Set(this.outEdges(id).map((e) => e.sourcePort));
+        if (!declared.every((d) => wired.has(d.port)))
+            return undefined;
+        return new Set(declared.map((d) => d.port));
+    }
     /**
      * Out-edges excluding the side paths recovered as port lists: `error`,
      * `branch-*`, and every `outcome-*` except the primary one.
+     *
+     * UNLESS every declared exit is wired. Then the node genuinely FORKS — there
+     * is no main path, each arm is a successor — and the post-dominator has to see
+     * that or it computes the join as the primary arm's first node. Which it did:
+     * a converged two-outcome task decompiled with one arm empty and the other
+     * swallowing the tail, because `ipdom(review)` came back as `publish`.
      */
     successorEdges(id) {
         const primary = this.primaryOutcomePort(id);
+        const forked = this.fullyWiredExits(id);
         return this.outEdges(id).filter((e) => e.sourcePort !== 'error'
             && !ARTIFACT_PORTS.has(e.sourcePort)
-            && !e.sourcePort.startsWith('branch-')
-            && (!e.sourcePort.startsWith('outcome-') || e.sourcePort === primary));
+            && (forked?.has(e.sourcePort)
+                || (!e.sourcePort.startsWith('branch-')
+                    && (!e.sourcePort.startsWith('outcome-') || e.sourcePort === primary))));
     }
 }
 // ─── Node → step-spec source ──────────────────────────────────────────────────
@@ -1952,6 +1975,25 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         }
         // A regular action step (mock / script / http / transform / connector / …).
         const spec = emitStepSpec(node, ctx.imp, ctx.inputNames, ctx.o, ctx.graph);
+        // `.stepSwitch` when the node's author-declared exits are ALL wired and the
+        // arms rejoin: that graph has no tacit main path to recover, so the
+        // `.step` + `.stepToList` form below cannot express it. It used to come back
+        // as `.stepToRef("end")` — a reference to the synthetic End node, which
+        // `compile` then refused (REF_UNKNOWN_TARGET), so a converged port graph did
+        // not round-trip at all. Reachable from the designer long before
+        // `.stepSwitch` existed; the arms just had nothing to decompile INTO.
+        const exitPorts = portArmExits(node, ctx);
+        if (exitPorts && exitPorts.length > 1) {
+            const r = ipdom.get(node.id) ?? stop;
+            const armSrcs = exitPorts.map(({ value, port }) => {
+                const armSegs = region(portTarget(ctx.graph, node.id, port), r, scope, ipdom, ctx, refInto);
+                return `{ value: ${str(value)}, body: ${armCb('b', armSegs)} }`;
+            });
+            const armList = `[\n${armSrcs.map((a) => reindent(a, '  ')).join(',\n')},\n]`;
+            segs.push(`.stepSwitch(${str(node.id)}, ${spec}, ${armList}${optsArg(node, ctx)})`);
+            cursor = r === EXIT ? undefined : r;
+            continue;
+        }
         segs.push(`.step(${str(node.id)}, ${spec}${optsArg(node, ctx)})`);
         // An error handler on this step (source port `error` + `errorHandlingEnabled`).
         const succ = scopeSucc(ctx.graph, node.id, scope);
@@ -2037,6 +2079,53 @@ function forwardReach(entries, scope, graph) {
     }
     return seen;
 }
+/**
+ * The node's author-declared exits when EVERY one of them is wired — the shape
+ * `.stepSwitch` authors. `undefined` when the node has no such exits, or when
+ * one is unwired, in which case the `.step` + `.stepToList` recovery still
+ * applies and the unwired port stays unwired.
+ *
+ * Deliberately strict about "every one": a partially wired node still has a
+ * tacit main path, and recovering THAT as `.stepSwitch` would invent arms the
+ * flow does not have.
+ */
+function portArmExits(node, ctx) {
+    // One predicate, on the Graph, because `successorEdges` has to agree with this
+    // exactly: if the CFG forks here the arms must be emitted as arms, and if it
+    // does not they must not be.
+    if (ctx.graph.fullyWiredExits(node.id) === undefined)
+        return undefined;
+    return declaredExitsOfNode(node);
+}
+/**
+ * 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.
+ */
+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')
+            return undefined;
+        const outcomes = (inputs.schema?.outcomes ?? []);
+        if (outcomes.length === 0)
+            return undefined;
+        return outcomes.map((o) => ({ value: String(o?.name ?? ''), port: `outcome-${o?.id ?? ''}` }));
+    }
+    if (node.type === T.http || node.type === T.httpV2) {
+        const branches = (inputs.branches ?? []);
+        if (branches.length === 0)
+            return undefined;
+        return [
+            ...branches.map((b) => ({ value: String(b?.name ?? ''), port: `branch-${b?.name ?? ''}` })),
+            { value: 'default', port: 'default' },
+        ];
+    }
+    return undefined;
+}
 /**
  * Emit a `.switch(...)` from a `core.logic.switch` node. Each case's serialized
  * expression is `<discriminant> === <JSON-literal>`; the discriminant (shared by

package/dist/flow-expr-check.js

@@ -85,6 +85,10 @@ function addStepNames(steps, roots) {
                 if (s.default)
                     addStepNames(s.default, roots);
                 break;
+            case 'stepSwitch':
+                for (const c of s.cases)
+                    addStepNames(c.body, roots);
+                break;
             case 'loop':
                 addStepNames(s.body, roots);
                 break;
@@ -145,6 +149,13 @@ function walk(steps, roots, out) {
                     walk(s.default, caseRoots, out);
                 break;
             }
+            case 'stepSwitch':
+                // The action's own inputs, then each arm — no discriminant to bind, the
+                // exits are named by the step rather than compared against a value.
+                deepExprs(s.spec.inputs, s.name, roots, out);
+                for (const c of s.cases)
+                    walk(c.body, roots, out);
+                break;
             case 'loop':
                 pushExpr(s.collection.js, s.collection.literal, s.name, roots, out);
                 if (s.options?.completionCondition) {

package/dist/flow-sdk.d.ts

@@ -292,6 +292,19 @@ export interface SwitchArm {
     label?: string;
     body: Step[];
 }
+/**
+ * One arm of a built `.stepSwitch` — the same shape as {@link SwitchArm}, but
+ * `value` names an exit the ACTION declares (a human-task outcome, an HTTP
+ * response branch) rather than a value to compare against. No `label`: a port
+ * edge carries none, and the exit's own name is already the label the canvas
+ * draws.
+ */
+export interface PortArm {
+    /** The exit this arm routes — a human-task outcome name, an HTTP branch name, or `'default'`. */
+    value: string;
+    /** The steps that run on that exit. Ends in `.return()` to be terminal; otherwise it converges. */
+    body: Step[];
+}
 /**
  * Options shared by every builder method that creates a definition-backed node:
  * `version` selects the exact node definition to compile against, and `updates`
@@ -425,6 +438,12 @@ export type Step = {
     cases: SwitchArm[];
     default?: Step[];
     options?: NodeOptions;
+} | {
+    kind: 'stepSwitch';
+    name: string;
+    spec: FlowActionSpec;
+    cases: PortArm[];
+    options?: NodeOptions;
 } | {
     kind: 'loop';
     name: string;
@@ -693,6 +712,48 @@ declare class StepList {
      * @returns This builder, so calls chain.
      */
     step(name: string, spec: FlowActionSpec | FlowAction, options?: NodeOptions): this;
+    /**
+     * Add an action node and route EVERY exit it declares, one arm per exit.
+     *
+     * The symmetric form of `.step()` + `.stepToList()`. Where those make the
+     * first exit the tacit next step and the rest side branches, this makes all
+     * of them arms of one construct — so nothing about a human task's routing
+     * depends on which outcome happens to be listed first.
+     *
+     * Arms behave exactly like `.switch()`'s: one that ends in `.return()` is
+     * terminal, and one that does not CONVERGES, so the step after the
+     * `.stepSwitch` fans in from every arm that reaches it. (That is the
+     * difference from `.stepToList`, whose arms get an End of their own.)
+     *
+     * `value` names an exit the ACTION declares — a human task's outcome name, an
+     * HTTP response branch's name, or `'default'` for HTTP's fall-through — not a
+     * value to compare against. `check` refuses a value the step does not declare
+     * and warns about a declared exit left out, which compiles to an End node.
+     *
+     * @param name - The step's id, as `.step()`.
+     * @param spec - What the node does, from an action factory.
+     * @param cases - One arm per declared exit.
+     * @param options - Node options, as `.step()`.
+     * @returns This builder, so calls chain.
+     *
+     * @example
+     * **Route a human task's outcomes, and converge on one return**
+     * ```ts
+     * export default flow('draft-review')
+     *   .output({ summary: types.string })
+     *   .var('summary', types.string)
+     *   .stepSwitch('review', hitl({ fields: [], outcomes: ['Publish', 'Revise'] }), [
+     *     { value: 'Publish', body: (b) => b.step('publish', script({ code: 'return "published";', returns: 'string' }), { updates: { summary: out('publish') } }) },
+     *     { value: 'Revise', body: (b) => b.step('sendBack', script({ code: 'return "revise";', returns: 'string' }), { updates: { summary: out('sendBack') } }) },
+     *   ])
+     *   .return({ summary: v('summary') })
+     *   .build();
+     * ```
+     */
+    stepSwitch(name: string, spec: FlowActionSpec | FlowAction, cases: {
+        value: string;
+        body: (b: ArmBuilder) => void;
+    }[], options?: NodeOptions): this;
     /**
      * Handle the PREVIOUS step's failure: if it fails, the flow runs `bodyFn`'s
      * steps instead of continuing.

package/dist/flow-sdk.js

@@ -303,6 +303,67 @@ class StepList {
         this.steps.push({ kind: 'action', name, spec: spec, ...(options ? { options } : {}) });
         return this;
     }
+    /**
+     * Add an action node and route EVERY exit it declares, one arm per exit.
+     *
+     * The symmetric form of `.step()` + `.stepToList()`. Where those make the
+     * first exit the tacit next step and the rest side branches, this makes all
+     * of them arms of one construct — so nothing about a human task's routing
+     * depends on which outcome happens to be listed first.
+     *
+     * Arms behave exactly like `.switch()`'s: one that ends in `.return()` is
+     * terminal, and one that does not CONVERGES, so the step after the
+     * `.stepSwitch` fans in from every arm that reaches it. (That is the
+     * difference from `.stepToList`, whose arms get an End of their own.)
+     *
+     * `value` names an exit the ACTION declares — a human task's outcome name, an
+     * HTTP response branch's name, or `'default'` for HTTP's fall-through — not a
+     * value to compare against. `check` refuses a value the step does not declare
+     * and warns about a declared exit left out, which compiles to an End node.
+     *
+     * @param name - The step's id, as `.step()`.
+     * @param spec - What the node does, from an action factory.
+     * @param cases - One arm per declared exit.
+     * @param options - Node options, as `.step()`.
+     * @returns This builder, so calls chain.
+     *
+     * @example
+     * **Route a human task's outcomes, and converge on one return**
+     * ```ts
+     * export default flow('draft-review')
+     *   .output({ summary: types.string })
+     *   .var('summary', types.string)
+     *   .stepSwitch('review', hitl({ fields: [], outcomes: ['Publish', 'Revise'] }), [
+     *     { value: 'Publish', body: (b) => b.step('publish', script({ code: 'return "published";', returns: 'string' }), { updates: { summary: out('publish') } }) },
+     *     { value: 'Revise', body: (b) => b.step('sendBack', script({ code: 'return "revise";', returns: 'string' }), { updates: { summary: out('sendBack') } }) },
+     *   ])
+     *   .return({ summary: v('summary') })
+     *   .build();
+     * ```
+     */
+    stepSwitch(name, spec, cases, options) {
+        if (!Array.isArray(cases) || cases.length === 0) {
+            throw new TypeError(`.stepSwitch('${name}'): needs at least one arm. With nothing to route, use .step().`);
+        }
+        const arms = cases.map((c) => {
+            const arm = new ArmBuilder();
+            c.body?.(arm);
+            // A `.switch()` arm's label becomes `inputs.cases[].label` on the decision
+            // node. There is no such slot here: an edge carries no label, and the port
+            // is already named by the outcome or branch it leaves. Refusing beats
+            // accepting it and dropping it on the floor.
+            if (arm.armLabel !== undefined) {
+                throw new TypeError(`.stepSwitch('${name}') arm '${c.value}': .label() has nowhere to go — a port edge carries no `
+                    + `label, and the exit is named by "${c.value}" already. Use options.label to rename the NODE.`);
+            }
+            return { value: String(c.value), body: arm.steps };
+        });
+        this.steps.push({
+            kind: 'stepSwitch', name, spec: spec, cases: arms,
+            ...(options ? { options } : {}),
+        });
+        return this;
+    }
     /**
      * Handle the PREVIOUS step's failure: if it fails, the flow runs `bodyFn`'s
      * steps instead of continuing.

package/dist/serialize.js

@@ -14,6 +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 { buildConfiguration, transportHttpMethod } from './config.js';
 import { stableId } from './core/stable-id.js';
 import { readEventFilter, eventFilterProblem, eventFilterJmes, eventFilterTreeLeaf } from './event-filters.js';
@@ -38,6 +40,7 @@ function bodyUsesBreak(steps) {
     return steps.some((s) => s.kind === 'break'
         || (s.kind === 'branch' && (bodyUsesBreak(s.then) || bodyUsesBreak(s.otherwise)))
         || (s.kind === 'switch' && (s.cases.some((c) => bodyUsesBreak(c.body)) || (s.default ? bodyUsesBreak(s.default) : false)))
+        || (s.kind === 'stepSwitch' && s.cases.some((c) => bodyUsesBreak(c.body)))
         || (s.kind === 'parallel' && s.arms.some(bodyUsesBreak))
         || (s.kind === 'stepToList' && bodyUsesBreak(s.body)));
 }
@@ -3676,6 +3679,8 @@ function stepNamesOf(steps, out = []) {
             s.cases.forEach((c) => stepNamesOf(c.body, out));
             stepNamesOf(s.default ?? [], out);
         }
+        else if (s.kind === 'stepSwitch')
+            s.cases.forEach((c) => stepNamesOf(c.body, out));
         else if (s.kind === 'parallel')
             s.arms.forEach((a) => stepNamesOf(a, out));
         else if (s.kind === 'loop')
@@ -4982,18 +4987,24 @@ export function serialize(built, opts = {}) {
             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: `outcomePorts` 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). Plain tasks stay on the pinned
-            // default, byte-identically.
-            const outcomeRouted = spec.inputs?.outcomePorts === true || spec.inputs?.exposeError === true;
+            // 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.
+            //
+            // 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.
+            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 pinned = step.options?.version;
+            // 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.`);
@@ -5307,6 +5318,72 @@ export function serialize(built, opts = {}) {
             else if (step.kind === 'stepToList') {
                 tails = emitPortList(step, lastAction ?? '?', tails, scope, parentId, breakTarget);
             }
+            else if (step.kind === 'stepSwitch') {
+                // The action, then EVERY exit it declares as an arm — no tacit tail.
+                //
+                // The exits are resolved BEFORE the node is emitted, because a spec with
+                // no routable fan-out (a human task pinned to 1.0, a variant, an http
+                // with no branches) must refuse rather than emit a node and then
+                // discover it has one port. `declaredExits` carries the reason.
+                const exits = declaredExits(step.spec, step.options?.version);
+                if (!hasExits(exits)) {
+                    throw new Error(`.stepSwitch("${step.name}"): ${exits.reason}, so there are no exits to route.`
+                        + (exits.suggestion ? ` ${exits.suggestion}` : ''));
+                }
+                const action = {
+                    kind: 'action', name: step.name, spec: step.spec,
+                    ...(step.options ? { options: step.options } : {}),
+                };
+                // The tail `emitAction` hands back is the family's tacit exit — the
+                // primary outcome, http's `default`. Discarded on purpose: every exit is
+                // an arm here, so that port is wired by the arm that names it (and
+                // wiring both is flow-builder-sdk#741).
+                emitAction(action, tails, scope, parentId);
+                applyUpdates(action);
+                applyLabel(action);
+                const nodeId = scope.stepNodeId.get(step.name);
+                if (!nodeId)
+                    throw new Error(`.stepSwitch("${step.name}"): emitted node not found.`);
+                const armTails = [];
+                const routed = new Set();
+                for (const c of step.cases) {
+                    const exit = exits.find((e) => e.value === c.value);
+                    if (!exit) {
+                        throw new Error(`.stepSwitch("${step.name}"): no exit named ${JSON.stringify(c.value)}. `
+                            + `It declares ${exits.map((e) => JSON.stringify(e.value)).join(', ')}.`);
+                    }
+                    routed.add(exit.port);
+                    // Arms CONVERGE, exactly as `.switch()`'s do: every arm that does not
+                    // end in `.return()` contributes its tail, so the next step fans in
+                    // 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));
+                }
+                // 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
+                // (STEP_SWITCH_EXIT_UNROUTED) — this is the compile-side half of it.
+                //
+                // `action: 'End'` outcomes get one TOO, and that is deliberate: the
+                // designer draws a handle for every entry in `inputs.schema.outcomes`
+                // whatever its action, so skipping them left a drawn handle wired to
+                // nothing. UiPath/skills' own gate says the same and is stricter than
+                // this was — `assert_outcome_wiring` requires an edge per outcome with
+                // no exemption, and its convention makes every non-primary outcome an
+                // `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);
+                }
+                tails = armTails;
+                lastAction = step.name;
+            }
             else if (step.kind === 'branch') {
                 const id = stepUid(scope, step.name);
                 const node = makeNode(NODE_TYPE.decision, id, step.options?.label ?? step.label ?? step.name, { parentId, requestedVersion: step.options?.version });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "5.4.1",
+  "version": "6.0.0",
   "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": "b5437630666554168202df6a5fbfe43ee72c43d0"
+  "gitref": "8c327b39940d34432128dd713c731027bb00fbde"
 }