@uipath/maestro-builder-sdk 5.4.1 → 6.0.1

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 {};