@uipath/maestro-builder-sdk 6.29.1 → 6.30.0

package/dist/api-index.md

@@ -150,7 +150,7 @@ could hand you spans for a version you do not have.
 | `HitlAssigneeType` | type | `dist/nodes/hitl/flow/spec.d.ts:16-23` | Supporting types | How the task is assigned, the platform's own vocabulary (canvas `HITL_ASSIGNEE_TYPE`): `'user'` a single user, `'group'`… |
 | `HitlChannel` | type | `dist/nodes/hitl/flow/spec.d.ts:10-15` | Supporting types | Where the task is delivered. |
 | `HitlConnection` | interface | `dist/nodes/hitl/flow/spec.d.ts:24-32` | Supporting types | A per-channel Integration Service connection (Slack / Teams delivery). |
-| `HitlInputs` | interface | `dist/nodes/hitl/flow/spec.d.ts:186-257` | Option shapes | 11 field(s) |
+| `HitlInputs` | interface | `dist/nodes/hitl/flow/spec.d.ts:186-290` | Option shapes | 12 field(s) |
 | `HitlRecipient` | interface | `dist/nodes/hitl/flow/spec.d.ts:33-69` | Supporting types | Who gets the task and over which channels. |
 | `HitlVariant` | type | `dist/nodes/hitl/flow/spec.d.ts:114-139` | Supporting types | WHICH human-task node type to emit. |
 | `http` | function | `dist/nodes/http/flow/factories.d.ts:7-14` | Actions | Declare an HTTP request action, explicitly choosing standalone or managed. |

package/dist/api-members.md

@@ -5,12 +5,12 @@
 
 # Maestro Builder SDK — member index
 
-**A lookup table of 1118 rows — match one name in it, do not read it.**
+**A lookup table of 1119 rows — match one name in it, do not read it.**
 Grep or search for the member you have; the row it lands on is the whole
 answer. Reading top to bottom costs ~20x what the one row does and tells you
 nothing you asked for.
 
-Every field and method of every exported shape — 1118 across
+Every field and method of every exported shape — 1119 across
 200 interfaces and classes — keyed by the MEMBER's own name.
 
 **Use this when the name you have is a field or a method**, which is usually
@@ -28,7 +28,7 @@ truncated summary would, for less. Read the span.
 Member names repeat across shapes (`name` is declared on 69 of them), so the
 `Declared on` column is what makes a match actionable. For the whole shape
 rather than the one field, look that name up in [`api-index.md`](api-index.md) —
-which is why its span is not repeated on all 1118 rows here.
+which is why its span is not repeated on all 1119 rows here.
 
 **A name that misses both indexes is probably not part of the API.** The one
 that comes up is a RUNTIME output key — a human task's `Action`, a step's
@@ -264,7 +264,7 @@ not find it either.
 | `displayName` | property | `RegistryInputField` | `dist/bpmn/typed-node.d.ts:58` |
 | `displayName` | property | `SlaOpts` | `dist/case/case-sdk.d.ts:170-175` |
 | `displayName` | property | `TriggerMeta` | `dist/core/connectors.d.ts:127-128` |
-| `document` | property | `HitlInputs` | `dist/nodes/hitl/flow/spec.d.ts:252-256` |
+| `document` | property | `HitlInputs` | `dist/nodes/hitl/flow/spec.d.ts:285-289` |
 | `documentClassify` | property | `FlowActionSpecs` | `dist/nodes/document/flow/spec.d.ts:56-59` |
 | `documentId` | property | `DocValidationInputs` | `dist/nodes/hitl/flow/spec.d.ts:84-85` |
 | `doWhile` | method | `StepList` | `dist/flow-sdk.d.ts:1089-1113` |
@@ -420,7 +420,7 @@ not find it either.
 | `height` | property | `StickyNote` | `dist/flow-sdk.d.ts:702-703` |
 | `hidden` | property | `RegistryContextField` | `dist/bpmn/typed-node.d.ts:27` |
 | `hidden` | property | `RegistryInputField` | `dist/bpmn/typed-node.d.ts:61` |
-| `hitl` | property | `FlowActionSpecs` | `dist/nodes/hitl/flow/spec.d.ts:260-263` |
+| `hitl` | property | `FlowActionSpecs` | `dist/nodes/hitl/flow/spec.d.ts:293-296` |
 | `http` | property | `FlowActionSpecs` | `dist/nodes/http/flow/spec.d.ts:145-148` |
 | `http` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2366-2400` |
 | `humanTask` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2595-2646` |
@@ -549,6 +549,7 @@ not find it either.
 | `layout` | property | `BuiltFlow` | `dist/flow-sdk.d.ts:754-755` |
 | `layout` | method | `CaseBuilder` | `dist/case/case-sdk.d.ts:1139-1159` |
 | `layout` | method | `FlowBuilder` | `dist/flow-sdk.d.ts:1288-1298` |
+| `legacyCompleted` | property | `HitlInputs` | `dist/nodes/hitl/flow/spec.d.ts:252-284` |
 | `limit` | property | `DataFabricReadInputs` | `dist/nodes/data-fabric/flow/spec.d.ts:95-100` |
 | `limit` | property | `DoWhileOptions` | `dist/flow-sdk.d.ts:503-504` |
 | `literal` | property | `Expr` | `dist/core/expr.d.ts:18` |

package/dist/check.js

@@ -342,9 +342,12 @@ function checkFlow(built, ancestors, opts = {}) {
                             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 none — ${ids.length === 0 ? 'it declares no outcomes'
-                                    : `the '${prevSpec.inputs?.variant}' variant reads its outcomes from its app`}, so its single `
+                                    : model.legacyCompleted ? 'it sets legacyCompleted: true'
+                                        : `the '${prevSpec.inputs?.variant}' variant reads its outcomes from its app`}, so its single `
                                 + `exit is 'completed'.`,
-                            suggestion: `route on out('${prevAction?.name}', 'Action') downstream`,
+                            suggestion: model.legacyCompleted
+                                ? 'drop `legacyCompleted` (and set outcomePorts: true to route each outcome)'
+                                : `route on out('${prevAction?.name}', 'Action') downstream`,
                         });
                     }
                     else if (!ids.includes(want)) {
@@ -425,7 +428,11 @@ function checkFlow(built, ancestors, opts = {}) {
                     const allEnd = outcomes.length > 0
                         && outcomes.every((o) => typeof o !== 'string' && o?.action === 'End');
                     // `.stepSwitch` routes every outcome as an arm, so it never belongs here.
+                    // Nor does a `legacyCompleted` task: only its primary outcome continues,
+                    // so no downstream switch can reach the others, and HITL_LEGACY_COMPLETED
+                    // already says so.
                     if (outcomes.length > 1 && !allEnd && s0.kind !== 'stepSwitch'
+                        && s.spec.inputs?.legacyCompleted !== true
                         && !hitlRoutesPerOutcome(s.spec.inputs, s.options?.version)) {
                         hitlChoiceNoPorts.set(s.name, {
                             names: outcomes.map((o) => String((typeof o === 'string' ? o : o?.name) ?? '').trim()),

package/dist/core/definition-handles.d.ts

@@ -35,4 +35,17 @@ export declare function expandSourceHandles(def: Def, inputs: unknown): string[]
  * whose handles cannot be known: such a node has no fan-out to route.
  */
 export declare function forwardFanOut(def: Def, inputs: unknown): string[] | undefined;
+/**
+ * The port a node's main path leaves on — the edge a plain `.step()` writes
+ * and a following step continues from: the first concrete forward source
+ * handle (`isDefaultForType` wins), else `output`. `undefined` when every
+ * forward source handle is templated (`case-{item.id}`), so no main path leaves
+ * the node.
+ *
+ * `serialize` writes the main-path edge on this port, and `decompile` reads the
+ * main path back off it, so the two must agree: a `core.logic.agentic-switch`
+ * (`case-{item.id}` + `default`) continues on `default`, and each other wired
+ * exit is a `.stepToList('case-<id>', …)` (#1214).
+ */
+export declare function contributionPort(def: Def): string | undefined;
 export {};

package/dist/core/definition-handles.js

@@ -72,3 +72,24 @@ export function forwardFanOut(def, inputs) {
     const handles = expandSourceHandles(def, inputs)?.filter((h) => !NOT_FORWARD.has(h));
     return handles !== undefined && handles.length > 1 ? handles : undefined;
 }
+/**
+ * The port a node's main path leaves on — the edge a plain `.step()` writes
+ * and a following step continues from: the first concrete forward source
+ * handle (`isDefaultForType` wins), else `output`. `undefined` when every
+ * forward source handle is templated (`case-{item.id}`), so no main path leaves
+ * the node.
+ *
+ * `serialize` writes the main-path edge on this port, and `decompile` reads the
+ * main path back off it, so the two must agree: a `core.logic.agentic-switch`
+ * (`case-{item.id}` + `default`) continues on `default`, and each other wired
+ * exit is a `.stepToList('case-<id>', …)` (#1214).
+ */
+export function contributionPort(def) {
+    const groups = Array.isArray(def?.handleConfiguration) ? def.handleConfiguration : [];
+    const handles = groups.flatMap((g) => (g?.handles ?? []));
+    const sources = handles.filter((h) => h?.type === 'source' && h?.id !== 'error');
+    const concrete = sources.filter((h) => typeof h?.id === 'string' && !h.id.includes('{'));
+    if (concrete.length === 0 && sources.length > 0)
+        return undefined;
+    return concrete.find((h) => h?.isDefaultForType)?.id ?? concrete[0]?.id ?? 'output';
+}

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

@@ -68,6 +68,15 @@
  * `exposeError: true` or `outcomePorts: true` select `per-outcome` on every node
  * type, including the two app-backed variants, so that `serialize` and `check`
  * refuse them there with their own message rather than silently ignoring them.
+ *
+ * **`legacyCompleted: true`** is the one way to keep a task with outcomes on the
+ * `completed` handle: the `placeholder` shape, marked `legacyCompleted`. It
+ * exists so a file saved before flow-workbench #3512, whose task leaves on one
+ * `completed` edge, round-trips through decompile and compile unchanged
+ * (flow-builder-sdk#1197). It is the file's shape, not one to author: the
+ * product runs that edge as the PRIMARY outcome only, and `check` says so
+ * (HITL_LEGACY_COMPLETED). `serialize`'s edge guard below exempts exactly the
+ * nodes that asked for it.
  */
 /**
  * The fields of a human task's inputs the routing model reads — structural, so
@@ -83,6 +92,7 @@ export interface HitlRoutingInputs {
     }>;
     readonly outcomePorts?: boolean;
     readonly exposeError?: boolean;
+    readonly legacyCompleted?: boolean;
 }
 /**
  * An outcome's stable id — the slug that names its `outcome-<id>` port.
@@ -114,6 +124,7 @@ export interface HitlOutcomeExit {
 export type HitlFanOutReason = 'outcomePorts: false' | 'quick-form' | 'pinned' | 'one outcome' | 'every outcome ends';
 export type HitlExitModel = {
     shape: 'placeholder';
+    legacyCompleted?: true;
 } | {
     shape: 'every-outcome';
     exits: HitlOutcomeExit[];
@@ -151,14 +162,17 @@ type EdgeLike = {
  * the product does not draw, and an `outcome-<id>` naming no declared outcome is
  * one `flow validate` refuses ("Edge references undeclared source handle"). A
  * real outcome named "Completed" is `outcome-completed`, which is fine — the
- * bare `completed` never is.
+ * bare `completed` never is, unless the task asked for it with
+ * `legacyCompleted: true` (`legacyCompleted` here).
  */
-export declare function hitlExitViolation(node: NodeLike, port: string): string | undefined;
+export declare function hitlExitViolation(node: NodeLike, port: string, legacyCompleted?: boolean): string | undefined;
 /**
  * The post-emit half of the guard: every edge of an emitted scope, whatever
  * path produced it (a tail, a `.stepToList` seed, a parked `.stepToRef`), is held
  * to {@link hitlExitViolation}. Fails closed — a serializer that emitted one of
  * these would ship a flow that validates and then drops outcomes at run time.
+ * `legacyCompleted` holds the ids of the tasks that set `legacyCompleted: true`,
+ * whose `completed` edge is the author's explicit choice.
  */
-export declare function assertHitlExitInvariant(nodes: readonly NodeLike[], edges: readonly EdgeLike[]): void;
+export declare function assertHitlExitInvariant(nodes: readonly NodeLike[], edges: readonly EdgeLike[], legacyCompleted?: ReadonlySet<string>): void;
 export {};

package/dist/core/hitl-routing.js

@@ -57,6 +57,8 @@ export function hitlExitModel(inputs, pinnedVersion) {
         return { shape: 'per-outcome', exits };
     if (!hitlDerivesOutcomeHandles(inputs?.variant) || exits.length === 0)
         return { shape: 'placeholder' };
+    if (inputs?.legacyCompleted === true)
+        return { shape: 'placeholder', legacyCompleted: true };
     const every = (why) => ({ shape: 'every-outcome', exits, why });
     if (inputs?.outcomePorts === false)
         return every('outcomePorts: false');
@@ -95,9 +97,10 @@ function outcomeIdsOf(node) {
  * the product does not draw, and an `outcome-<id>` naming no declared outcome is
  * one `flow validate` refuses ("Edge references undeclared source handle"). A
  * real outcome named "Completed" is `outcome-completed`, which is fine — the
- * bare `completed` never is.
+ * bare `completed` never is, unless the task asked for it with
+ * `legacyCompleted: true` (`legacyCompleted` here).
  */
-export function hitlExitViolation(node, port) {
+export function hitlExitViolation(node, port, legacyCompleted = false) {
     if (!OUTCOME_HANDLE_NODE_TYPES.has(String(node.type)))
         return undefined;
     const ids = outcomeIdsOf(node);
@@ -105,6 +108,8 @@ export function hitlExitViolation(node, port) {
         return undefined;
     const declared = ids.map((i) => `outcome-${i}`).join(', ');
     if (port === 'completed') {
+        if (legacyCompleted)
+            return undefined;
         return `human task "${String(node.id)}" has outcomes (${declared}), so the product draws no `
             + `'completed' handle on it — an edge there is remapped to the primary outcome and every other `
             + `outcome loses its path.`;
@@ -119,14 +124,16 @@ export function hitlExitViolation(node, port) {
  * path produced it (a tail, a `.stepToList` seed, a parked `.stepToRef`), is held
  * to {@link hitlExitViolation}. Fails closed — a serializer that emitted one of
  * these would ship a flow that validates and then drops outcomes at run time.
+ * `legacyCompleted` holds the ids of the tasks that set `legacyCompleted: true`,
+ * whose `completed` edge is the author's explicit choice.
  */
-export function assertHitlExitInvariant(nodes, edges) {
+export function assertHitlExitInvariant(nodes, edges, legacyCompleted = new Set()) {
     const byId = new Map(nodes.map((n) => [String(n.id), n]));
     for (const e of edges) {
         const node = byId.get(String(e.sourceNodeId));
         if (!node)
             continue;
-        const why = hitlExitViolation(node, String(e.sourcePort));
+        const why = hitlExitViolation(node, String(e.sourcePort), legacyCompleted.has(String(e.sourceNodeId)));
         if (why)
             throw new Error(`serialize: ${why}`);
     }

package/dist/decompile.js

@@ -46,7 +46,7 @@ import { mapJsCode } from './core/js-code-spans.js';
 import { missingBindingLabels } from './core/binding-messages.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
-import { forwardFanOut } from './core/definition-handles.js';
+import { contributionPort, forwardFanOut } from './core/definition-handles.js';
 import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
 import { eventFilterFromTreeLeaf } from './core/event-filters.js';
 import { sdkFormFieldType } from './core/form-field-type.js';
@@ -532,11 +532,34 @@ class Graph {
     successorEdges(id) {
         const primary = this.primaryOutcomePort(id);
         const forked = this.fullyWiredExits(id);
+        const side = forked ? undefined : this.rawSidePorts(id);
         return this.outEdges(id).filter((e) => e.sourcePort !== 'error'
             && !ARTIFACT_PORTS.has(e.sourcePort)
             && (forked?.has(e.sourcePort)
                 || (!e.sourcePort.startsWith('branch-')
-                    && (!e.sourcePort.startsWith('outcome-') || e.sourcePort === primary))));
+                    && (!e.sourcePort.startsWith('outcome-') || e.sourcePort === primary)
+                    && !side?.has(e.sourcePort))));
+    }
+    /**
+     * A multi-exit `rawNode`'s SIDE exits when not every exit is wired: each
+     * declared exit except the one its main path leaves on (`contributionPort`,
+     * the port serialize writes a plain `.step()`'s edge on — `default` for a
+     * `core.logic.agentic-switch`). Each is recovered as a
+     * `.stepToList('<port>', …)` after the `.step`, as `branch-*` and non-primary
+     * `outcome-*` exits are. `undefined` for every other node, and for a raw node
+     * whose exits are all wired (that one is a `.stepSwitch`).
+     *
+     * Without this, a partially wired agentic switch had two successors and no
+     * merge join, so the walk emitted an unstructured-fan-out TODO and dropped
+     * every arm (#1214).
+     */
+    rawSidePorts(id) {
+        const node = this.byId.get(id);
+        const exits = node ? rawNodeExits(node) : undefined;
+        if (!node || exits === undefined || this.fullyWiredExits(id) !== undefined)
+            return undefined;
+        const main = contributionPort(rawNodeDefinition(node));
+        return new Set(exits.map((e) => e.port).filter((p) => p !== main));
     }
 }
 // ─── Node → step-spec source ──────────────────────────────────────────────────
@@ -2397,6 +2420,17 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
                 segs.push(`.stepToList(${tsLiteral(oe.sourcePort)}, ${armCb('p', outSegs)})`);
             }
         }
+        // A partially wired multi-exit raw node (an agentic switch with one choice
+        // unwired): every wired exit but the main path's is its own port list, and
+        // an unwired one stays unwired (#1214).
+        const rawSide = ctx.graph.rawSidePorts(node.id);
+        for (const re of rawSide ? ctx.graph.outEdges(node.id).filter((e) => rawSide.has(e.sourcePort)) : []) {
+            const mainReach = forwardReach(succ, scope, ctx.graph);
+            const sideSegs = edgeRegion(re, EXIT, scope, ipdom, ctx, mainReach);
+            if (sideSegs.length === 0)
+                sideSegs.push('.return({})');
+            segs.push(`.stepToList(${tsLiteral(re.sourcePort)}, ${armCb('p', sideSegs)})`);
+        }
         // A body edge into the enclosing container's break handle: the path exits
         // the loop here. Emit `.break()` and end the region — recompiling recreates
         // exactly this edge and adds no continue back-edge for the path.
@@ -2565,13 +2599,20 @@ function declaredExitsOfNode(node) {
  */
 function rawNodeExits(node) {
     const type = String(node.type);
+    // A registered type (an HTTP call, say) answers from its own `exits`.
+    if (registeredImpl(node) !== undefined)
+        return undefined;
     if (Object.values(T).includes(type) || isTrigger(type))
         return undefined;
     if (['uipath.connector.', 'uipath.core.', 'uipath.ixp.', 'uipath.agent.', 'uipath.conversational.']
         .some((p) => type.startsWith(p)))
         return undefined;
-    const def = runDefs.get(`${type}@${node.typeVersion}`) ?? runDefs.get(type);
-    return forwardFanOut(def, node.inputs)?.map((port) => ({ value: port, port }));
+    return forwardFanOut(rawNodeDefinition(node), node.inputs)?.map((port) => ({ value: port, port }));
+}
+/** The definition the file carries for `node`'s type (its version's, else the type's). */
+function rawNodeDefinition(node) {
+    const type = String(node.type);
+    return runDefs.get(`${type}@${node.typeVersion}`) ?? runDefs.get(type);
 }
 /**
  * Split a switch case expression into `<discriminant> === <literal>`, the only

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

@@ -52,6 +52,12 @@ export interface FlowNodeContribution extends Omit<NodeContribution, 'definition
         readonly port: string;
         readonly endsRun?: boolean;
     }>;
+    /**
+     * The node is a human task with outcomes that leaves on its legacy `completed`
+     * handle, because its author set `legacyCompleted: true`. Exempts it from the
+     * guard that refuses a `completed` edge on such a task (`hitlExitViolation`).
+     */
+    legacyCompleted?: boolean;
     /**
      * `outputs` REPLACES the definition's `outputDefinition` on the node instead of
      * being merged over it — for an instance whose output slots are its own (a

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

@@ -6,6 +6,8 @@ import { hitlDerivesOutcomeHandles, outcomeIdOf } from '../../../core/hitl-routi
 export const HITL_DIAGNOSTICS = {
     HITL_VARIANT_UNKNOWN: { severity: 'error', summary: 'a variant that names no human-task node type' },
     HITL_OUTCOME_PORTS_VARIANT: { severity: 'error', summary: 'exposeError or outcomePorts on a variant that cannot honour it' },
+    HITL_LEGACY_COMPLETED: { severity: 'warning', summary: "a task with outcomes that leaves on the legacy 'completed' handle" },
+    HITL_LEGACY_COMPLETED_CONFLICT: { severity: 'error', summary: 'legacyCompleted with outcomePorts or exposeError, or where it changes nothing' },
     HITL_DOCUMENT_WITHOUT_VARIANT: { severity: 'error', summary: 'a document on a task that is not a validation station' },
     HITL_DOCVAL_WITH_FIELDS: { severity: 'error', summary: 'form fields on a validation station' },
     HITL_DOCVAL_NO_DOCUMENT: { severity: 'error', summary: 'a validation station with no document' },
@@ -86,6 +88,28 @@ export function checkHitl(inputs, ctx) {
             : `Route on out('${step}', 'Action') downstream.`);
         return;
     }
+    // `legacyCompleted: true` keeps a pre-#3512 file's `completed` edge (#1197).
+    // It is the file's shape, so it compiles, but what it does at run time is
+    // rarely what the author wants, and `flow validate` says nothing about it.
+    if (inputs?.legacyCompleted === true) {
+        const outcomes = Array.isArray(inputs?.outcomes) ? inputs.outcomes : [];
+        if (inputs?.outcomePorts !== undefined || inputs?.exposeError === true) {
+            at('HITL_LEGACY_COMPLETED_CONFLICT', `Human task "${step}" sets legacyCompleted: true, which leaves it on its single 'completed' handle, and also `
+                + `${inputs?.exposeError === true ? 'exposeError' : 'outcomePorts'}, which asks for per-outcome exits.`, 'Drop `legacyCompleted`.');
+            return;
+        }
+        if (!hitlDerivesOutcomeHandles(variant) || outcomes.length === 0) {
+            at('HITL_LEGACY_COMPLETED_CONFLICT', `Human task "${step}" sets legacyCompleted: true, but ${outcomes.length === 0 ? 'it has no outcomes'
+                : `its variant is "${variant}", which reads its outcomes from its app`}, so 'completed' is already its only exit.`, 'Drop `legacyCompleted`.');
+            return;
+        }
+        const first = typeof outcomes[0] === 'string' ? outcomes[0] : outcomes[0]?.name;
+        at('HITL_LEGACY_COMPLETED', `Human task "${step}" leaves on the legacy 'completed' handle (legacyCompleted: true). Studio Web and the `
+            + `runtime read that edge as the primary outcome, ${JSON.stringify(String(first ?? ''))}, only`
+            + (outcomes.length > 1 ? ': when the reviewer picks any other outcome, the run stops at the task.' : '.'), outcomes.length > 1
+            ? 'outcomePorts: false (every outcome continues to the next step), or outcomePorts: true / .stepSwitch (route each one)'
+            : 'Drop `legacyCompleted`: one outcome continues to the next step on its own handle.');
+    }
     if (inputs?.document !== undefined && !isDocval) {
         at('HITL_DOCUMENT_WITHOUT_VARIANT', `Human task "${step}" names a document to validate, but its variant is `
             + `${variant === undefined ? 'the default node type' : `"${variant}"`} — only the validation `

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

@@ -252,6 +252,12 @@ function hitlExits({ inputs }, pinnedVersion) {
     if (model.shape === 'placeholder') {
         // WHY it has no outcome exits decides what the author can do about it, so
         // the caller gets the specific one rather than "ports are off".
+        if (model.legacyCompleted) {
+            return {
+                reason: "legacyCompleted: true leaves it on its single 'completed' exit",
+                suggestion: 'Drop `legacyCompleted` to route its outcomes.',
+            };
+        }
         if ((inputs?.outcomes ?? []).length === 0) {
             return { reason: 'it declares no outcomes', suggestion: `outcomes: ['Approve', 'Reject']` };
         }
@@ -413,24 +419,24 @@ function liftHitl(node, typeName, ctx) {
     const outcomePorts = (typeName === BASE && version === '1.1')
         || (derivesHandles && !versionRoutes && !ctx.convergedFanOut()
             && outPorts.some((p) => p.startsWith('outcome-')));
-    // A lone `completed` edge on a task with several outcomes is the shape the
-    // designer stopped drawing: before flow-workbench #3512 (09-08) it was
-    // unconditioned, so every outcome continued down it; since then Studio Web and
-    // the converter remap it to the primary outcome only. Recompiling writes one
-    // `outcome-<id>` edge per outcome to the same step — the first meaning — so
-    // this is the one place decompile→compile is deliberately not exact. Say so.
-    const legacyCompleted = derivesHandles && outcomeIdsOfNode(n).length > 1 && outPorts.includes('completed');
-    // Both a converged fan-out and a legacy lone `completed` mean "every outcome
-    // continues to the next step". Say so in the source with `outcomePorts: false`
-    // rather than leaving it to the `{ version }` pin, so the intent survives an
-    // author dropping the pin.
-    const fanOut = !outcomePorts && derivesHandles && !versionRoutes && outcomeIdsOfNode(n).length > 1
-        && (legacyCompleted || ctx.convergedFanOut());
+    // A `completed` edge on a task with outcomes is the shape the designer
+    // stopped drawing: before flow-workbench #3512 (09-08) it was unconditioned,
+    // so every outcome continued down it; since then Studio Web and the converter
+    // remap it to the primary outcome only. The source keeps it as it is,
+    // `legacyCompleted: true`, so a round trip with no edits writes the same edge
+    // back (#1197) and the author decides what it should mean.
+    const legacyCompleted = derivesHandles && !versionRoutes && outcomeIdsOfNode(n).length > 0
+        && outPorts.includes('completed');
+    // A converged fan-out means "every outcome continues to the next step". Say so
+    // in the source with `outcomePorts: false` rather than leaving it to the
+    // `{ version }` pin, so the intent survives an author dropping the pin.
+    const fanOut = !outcomePorts && !legacyCompleted && derivesHandles && !versionRoutes
+        && outcomeIdsOfNode(n).length > 1 && ctx.convergedFanOut();
     if (legacyCompleted) {
         ctx.warn(`human task ${JSON.stringify(n.id)} leaves on the legacy 'completed' handle, which Studio Web no longer draws `
-            + `once a task has outcomes (it reads the edge as the primary outcome only). Recompiling emits one `
-            + `outcome-<id> edge per outcome to the same step, so every outcome continues — what the edge meant `
-            + `before flow-workbench #3512.`);
+            + `once a task has outcomes: it runs that edge as the primary outcome only, so any other outcome stops the run. `
+            + `The source keeps it (legacyCompleted: true), so recompiling writes the same edge. To continue every outcome, `
+            + `replace it with outcomePorts: false; to route each one, outcomePorts: true or .stepSwitch.`);
     }
     const title = plain(i.title);
     const priority = plain(i.priority);
@@ -447,7 +453,8 @@ function liftHitl(node, typeName, ctx) {
         // there is serialize's own, not the author's.
         ...(fields.length || (variant !== 'action-app' && variant !== 'document-validation') ? { fields } : {}),
         outcomes,
-        ...(outcomePorts ? { outcomePorts: true } : fanOut ? { outcomePorts: false } : {}),
+        ...(legacyCompleted ? { legacyCompleted: true }
+            : outcomePorts ? { outcomePorts: true } : fanOut ? { outcomePorts: false } : {}),
         ...(version === '1.2' ? { exposeError: true } : {}),
     };
     return { kind: 'hitl', inputs: lifted };
@@ -511,6 +518,7 @@ function printHitl({ inputs }, ctx) {
             ['outcomes', `[${outcomes.join(', ')}]`],
             ['outcomePorts', h.outcomePorts === true ? 'true' : h.outcomePorts === false ? 'false' : undefined],
             ['exposeError', h.exposeError ? 'true' : undefined],
+            ['legacyCompleted', h.legacyCompleted ? 'true' : undefined],
         ],
     };
 }
@@ -535,6 +543,14 @@ function hitlAt(typeName, version, factory) {
                 throw new Error(`"${ctx.step}": outcomePorts: true, but the '${inputs?.variant}' variant reads its outcomes `
                     + `from its app and leaves on its single 'completed' exit. Route on out('${ctx.step}', 'Action') downstream.`);
             }
+            if (inputs?.legacyCompleted === true && (inputs?.outcomePorts !== undefined || inputs?.exposeError === true)) {
+                throw new Error(`"${ctx.step}": legacyCompleted: true leaves the task on its single 'completed' handle, so it cannot also `
+                    + `${inputs?.exposeError === true ? 'expose the error output (exposeError)' : 'set outcomePorts'}. Drop one.`);
+            }
+            if (inputs?.legacyCompleted === true && typeName === BASE && (pinned === '1.1' || pinned === '1.2')) {
+                throw new Error(`"${ctx.step}": legacyCompleted: true, but { version: '${pinned}' } pins the task's per-outcome definition, `
+                    + `which has no 'completed' handle (flow validate refuses the edge). Drop the pin or legacyCompleted.`);
+            }
             if (inputs?.exposeError === true && pinned !== undefined && pinned !== '1.2') {
                 throw new Error(`"${ctx.step}": exposeError needs the task's 1.2 definition, but { version: '${pinned}' } pins it. `
                     + `Drop the pin or match it.`);
@@ -554,8 +570,9 @@ function hitlAt(typeName, version, factory) {
                 return { ...contribution, fanOut: exitModel.exits.map((e) => ({ port: e.port, ...(e.endsProcess ? { endsRun: true } : {}) })) };
             }
             // Every human-task definition declares one static source handle,
-            // `completed`: the real exit on an app-backed task and on one with no outcomes.
-            return { ...contribution, port: 'completed' };
+            // `completed`: the real exit on an app-backed task and on one with no
+            // outcomes, and the author's explicit choice with `legacyCompleted: true`.
+            return { ...contribution, port: 'completed', ...(exitModel.legacyCompleted ? { legacyCompleted: true } : {}) };
         },
         deserialize: (node, ctx) => liftHitl(node, typeName, ctx),
         print: printHitl,

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

@@ -249,6 +249,39 @@ export interface HitlInputs {
      * {@link HitlInputs.outcomePorts | outcomePorts}. Default node only.
      */
     exposeError?: boolean;
+    /**
+     * Leave on the task's legacy `completed` handle, as a file saved before
+     * Studio Web drew one handle per outcome does. `decompile` writes this for
+     * such a file, so a round trip with no edits gives its `completed` edge back
+     * unchanged instead of rewriting it into one `outcome-<id>` edge per outcome.
+     *
+     * Not for new flows. Studio Web and the runtime read a `completed` edge on a
+     * task with outcomes as the PRIMARY (first) outcome only: when the reviewer
+     * picks any other outcome, that path has no edge and the run stops there.
+     * `check` warns (`HITL_LEGACY_COMPLETED`). To continue every outcome to the
+     * next step, drop this and set
+     * {@link HitlInputs.outcomePorts | outcomePorts}`: false`; to route each
+     * outcome, use `outcomePorts: true` or `.stepSwitch`.
+     *
+     * Only on the default node and `'quick-form'` with at least one outcome (the
+     * other variants always leave on `completed`), and not with `outcomePorts` or
+     * `exposeError`.
+     *
+     * @example
+     * ```ts
+     * // Decompiled from a task whose one edge leaves on `completed`.
+     * export default flow('review')
+     *   .step('review1', hitl({
+     *     variant: 'quick-form',
+     *     fields: [{ id: 'comments', type: 'text', direction: 'output' }],
+     *     outcomes: ['Submit', 'Reject'],
+     *     legacyCompleted: true,
+     *   }))
+     *   .step('approved1', script({ code: 'return 1;' }))
+     *   .build();
+     * ```
+     */
+    legacyCompleted?: boolean;
     /**
      * The document to validate. Required by — and only legal with —
      * `variant: 'document-validation'`.

package/dist/serialize.js

@@ -57,6 +57,7 @@ import { resolveSchemaVersion } from './schema-version.js';
 import { planFlowGlobals, planSharedInputs, sharedInputRoots } from './flow-variables.js';
 import { outputBackingGlobal, planOutputBacking } from './flow-output-backing.js';
 import { mapJsCode } from './core/js-code-spans.js';
+import { contributionPort } from './core/definition-handles.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
 import { resourceNodeSortOrder } from './core/process-resource-sort-order.js';
@@ -3531,18 +3532,6 @@ function declaresForwardPort(def, port) {
         return port.length > head.length + tail.length && port.startsWith(head) && port.endsWith(tail);
     });
 }
-/**
- * Forward port: the first concrete source handle (`isDefaultForType` wins), else `output`;
- * `undefined` when every forward source handle is templated (`case-{item.id}`).
- */
-function contributionPort(def) {
-    const handles = (def?.handleConfiguration ?? []).flatMap((g) => g?.handles ?? []);
-    const sources = handles.filter((h) => h?.type === 'source' && h?.id !== 'error');
-    const concrete = sources.filter((h) => typeof h?.id === 'string' && !h.id.includes('{'));
-    if (concrete.length === 0 && sources.length > 0)
-        return undefined;
-    return concrete.find((h) => h?.isDefaultForType)?.id ?? concrete[0]?.id ?? 'output';
-}
 /**
  * Render a switch case value as a JS literal for the case expression.
  *
@@ -4434,6 +4423,13 @@ export function serialize(built, opts = {}) {
      * `.stepToRef` rejoins now do come through here, #938).
      */
     const hitlNodes = new Map();
+    /**
+     * Human tasks with outcomes that set `legacyCompleted: true`: they leave on
+     * `completed` by the author's choice, so the guard exempts that one port
+     * (flow-builder-sdk#1197). They are not tracked in `hitlNodes`, whose tails are
+     * outcome edges; theirs is the one `completed` edge.
+     */
+    const legacyCompletedNodes = new Set();
     /** Step name → node id of a step whose every forward exit is templated (see `contributionPort`). */
     const routerNodes = new Map();
     /**
@@ -4447,7 +4443,7 @@ export function serialize(built, opts = {}) {
     const hitlEndExits = [];
     function addEdge(scope, from, toNode, toPort = 'input') {
         const hitlNode = hitlNodes.get(from.node);
-        const refused = hitlNode ? hitlExitViolation(hitlNode, from.port) : undefined;
+        const refused = hitlNode ? hitlExitViolation(hitlNode, from.port, legacyCompletedNodes.has(from.node)) : undefined;
         if (refused)
             throw new Error(`serialize: ${refused}`);
         scope.edges.push({ id: `edge_${edgeSeq++}`, sourceNodeId: from.node, sourcePort: from.port, targetNodeId: toNode, targetPort: toPort });
@@ -4623,7 +4619,7 @@ export function serialize(built, opts = {}) {
         for (const vd of childGlobals.vars)
             globals.push({ id: vd.name, name: vd.name, direction: 'inout', type: vd.type, ...varMeta(vd) });
         resolveRejoins(scope, addEdge);
-        assertHitlExitInvariant(scope.nodes, scope.edges);
+        assertHitlExitInvariant(scope.nodes, scope.edges, legacyCompletedNodes);
         typeAgentInputSchemas(scope, globals);
         emitStickyNotes(child, scope, claimNoteId);
         const layoutEdges = applyAuthorLayout(child.layout, scope, `subflow "${nodeId}"`);
@@ -4826,7 +4822,9 @@ export function serialize(built, opts = {}) {
         // edge out of it is held to that rule (`hitlExitViolation`, in addEdge), and
         // the step list treats its tails as outcome edges. A rawNode of the type is
         // not one: it routes by the port lists its author wrote.
-        if (o.trackOutcomes && OUTCOME_HANDLE_NODE_TYPES.has(o.typeName))
+        if (o.trackOutcomes && contribution.legacyCompleted)
+            legacyCompletedNodes.add(id);
+        else if (o.trackOutcomes && OUTCOME_HANDLE_NODE_TYPES.has(o.typeName))
             hitlNodes.set(id, node);
         for (const t of o.tails)
             addEdge(scope, t, id);
@@ -5990,10 +5988,13 @@ export function serialize(built, opts = {}) {
      * Refuse a side exit on a human task's port that the step's tails already
      * continue from: that would put two edges on one port (flow-builder-sdk#741).
      * After a fan-out task that is EVERY outcome port. `check` reports the same
-     * as HITL_OUTCOME_PORTS_OFF; this is the compile-side half.
+     * as HITL_OUTCOME_PORTS_OFF; this is the compile-side half. A
+     * `legacyCompleted` task counts too: its main path leaves on `completed`, so a
+     * side route there is the same second edge.
      */
     function refuseRewire(method, port, source, tails) {
-        if (!hitlNodes.has(tails[0]?.node ?? '') || !tails.some((t) => t.port === port))
+        const node = tails[0]?.node ?? '';
+        if (!(hitlNodes.has(node) || legacyCompletedNodes.has(node)) || !tails.some((t) => t.port === port))
             return;
         throw new Error(tails.length > 1
             ? `${method}('${port}', …) after human task "${source}": every outcome already continues to the next `
@@ -6652,7 +6653,7 @@ export function serialize(built, opts = {}) {
         }
     }
     resolveRejoins(root, addEdge);
-    assertHitlExitInvariant(root.nodes, root.edges);
+    assertHitlExitInvariant(root.nodes, root.edges, legacyCompletedNodes);
     typeAgentInputSchemas(root, globals);
     emitStickyNotes(built, root, claimNoteId);
     const rootLayoutEdges = applyAuthorLayout(built.layout, root, `flow "${built.id}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.29.1",
+  "version": "6.30.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "5dee9e0ebdef1bca6c586f4802285a0f429ae432"
+  "gitref": "5b38f3fae80cbcb874c6d92afb49690b77656caf"
 }