@uipath/maestro-builder-sdk 6.43.0 → 6.44.0

package/dist/flow-sdk.d.ts

@@ -444,6 +444,39 @@ export interface NodeOptions {
      */
     label?: string;
 }
+/**
+ * The options of `.parallel()`: the join's {@link NodeOptions}, plus the fork
+ * node when the flow has one.
+ */
+export interface ParallelOptions extends NodeOptions {
+    /**
+     * A FORK node the arms leave from: a `core.logic.merge` with one incoming
+     * edge and one edge per arm, which is how Studio Web draws a parallel split
+     * (its "Parallel" gateway). Without it the arms leave from the previous
+     * step's own port, one edge per arm, which the platform runs the same way.
+     * Name it to round-trip a flow the canvas drew with a fork node; `label` is
+     * the canvas text, defaulting to the name, and `version` the fork node's
+     * exact `core.logic.merge` version when it differs from the join's.
+     *
+     * ```ts
+     * .parallel('join', [(a) => a.step('t1', …), (b) => b.step('t2', …)], { fork: 'split' })
+     * ```
+     */
+    fork?: string | {
+        name: string;
+        label?: string;
+        version?: string;
+    };
+}
+/**
+ * The fork node a `.parallel()` asks for, normalized, or `undefined`.
+ * @internal
+ */
+export declare function parallelFork(options: ParallelOptions | undefined): {
+    name: string;
+    label?: string;
+    version?: string;
+} | undefined;
 /**
  * `.return(...)`-specific options.
  *
@@ -588,15 +621,16 @@ export type Step = {
 /**
  * A fan-out and its join. `arms` is one step list per arm — an ARRAY, because
  * arms are positional and carry no author-supplied keys — and `name` names the
- * Merge node the arms converge on (the only node this step creates; the fork
- * itself is just N edges out of one port).
+ * Merge node the arms converge on (the only node this step creates unless
+ * `options.fork` names a fork node too; otherwise the fork is just N edges
+ * out of one port).
  */
  | {
     kind: 'parallel';
     name: string;
     label?: string;
     arms: Step[][];
-    options?: NodeOptions;
+    options?: ParallelOptions;
 }
 /**
  * A hard stop: `core.logic.terminate`, a BPMN End event carrying a
@@ -1137,11 +1171,12 @@ declare class StepList {
      * @param arms - One callback per parallel arm, each receiving its own
      * sub-builder. Two or more.
      * @param options - Node options; `version` selects the exact definition
-     * version (see {@link NodeOptions}).
+     * version (see {@link NodeOptions}), and `fork` names a fork node the arms
+     * leave from (see {@link ParallelOptions}).
      * @returns This builder, positioned after the Merge — so what you chain next
      * runs once, when every arm has finished.
      */
-    parallel(name: string, arms: ((b: StepList) => void)[], options?: NodeOptions): this;
+    parallel(name: string, arms: ((b: StepList) => void)[], options?: ParallelOptions): this;
     /**
      * Iterate `collection`; `bodyFn` receives a sub-builder for the loop body.
      *

package/dist/flow-sdk.js

@@ -264,6 +264,18 @@ export function conversationTrigger() {
 export function voiceTrigger() {
     return builtinTriggerSpec({ kind: 'voice' });
 }
+/**
+ * The fork node a `.parallel()` asks for, normalized, or `undefined`.
+ * @internal
+ */
+export function parallelFork(options) {
+    const fork = options?.fork;
+    if (fork === undefined)
+        return undefined;
+    return typeof fork === 'string'
+        ? { name: fork }
+        : { name: fork.name, ...(fork.label !== undefined ? { label: fork.label } : {}), ...(fork.version !== undefined ? { version: fork.version } : {}) };
+}
 /**
  * A node's layout at a canvas position — the short form of a {@link NodeLayout}
  * for the `nodes` map of {@link FlowBuilder.layout}.
@@ -764,7 +776,8 @@ class StepList {
      * @param arms - One callback per parallel arm, each receiving its own
      * sub-builder. Two or more.
      * @param options - Node options; `version` selects the exact definition
-     * version (see {@link NodeOptions}).
+     * version (see {@link NodeOptions}), and `fork` names a fork node the arms
+     * leave from (see {@link ParallelOptions}).
      * @returns This builder, positioned after the Merge — so what you chain next
      * runs once, when every arm has finished.
      */

package/dist/flow-step-variables.d.ts

@@ -0,0 +1,4 @@
+export declare function stepDeclaredVariables(spec: {
+    kind?: unknown;
+    inputs?: unknown;
+} | undefined, pinnedVersion?: string): string[];

package/dist/flow-step-variables.js

@@ -0,0 +1,22 @@
+/**
+ * The flow variables a step DECLARES by running (`FlowNodeType.declares`): a
+ * quick form's asked fields land in their `variable` (`vars.<Step>_<field>` as
+ * the designer names it), and later steps read `$vars.<name>`. Resolved at the
+ * version the step resolves to, the way `stepExits` does, so `check` and
+ * `flow-expr-check` agree on what a step publishes (#1309).
+ */
+import { resolveVersion } from './core/nodes/versioned.js';
+import { FLOW_NODE_TYPES } from './flow-node-registry.js';
+export function stepDeclaredVariables(spec, pinnedVersion) {
+    const entry = typeof spec?.kind === 'string' ? FLOW_NODE_TYPES.byKind(spec.kind, spec) : undefined;
+    if (!entry)
+        return [];
+    let impl;
+    try {
+        impl = resolveVersion(entry.type, spec, pinnedVersion, 'declares');
+    }
+    catch {
+        impl = resolveVersion(entry.type, spec, undefined, 'declares');
+    }
+    return impl.declares?.(spec, pinnedVersion) ?? [];
+}

package/dist/loop-version.d.ts

@@ -3,28 +3,45 @@ import type { LoopOptions, Step } from './flow-sdk.js';
 export declare const LOOP_NODE_TYPE = "core.logic.loop";
 /** The `core.logic.loop` version `.loop()` emits unless `{ version }` pins another. */
 export declare const LOOP_DEFAULT_VERSION = "2.4";
+/**
+ * The definition a loop at `version` compiles against: the bundled one, else
+ * the one the flow carries (`carried`, a `.definitions()` lookup), else
+ * `undefined`. `serialize` and `check` both resolve through this, so they agree
+ * on a carried `core.logic.loop@1.0`'s handles and inputs (#1311).
+ */
+export declare function resolveLoopDefinition(version: string, carried?: (type: string, version: string) => unknown): unknown;
 /** The version `.loop()` emits for these options. */
 export declare function loopVersion(options: LoopOptions | undefined): string;
 /**
  * True when this loop version's body runs from the inner `start` handle and goes
  * back through `continue` (2.x); false for the legacy `output`/`loopBack` shape.
- * A version with no bundled definition counts as 2.x; its lookup fails later.
+ *
+ * The answer is read off the definition's target handles. `definition` is the
+ * one the loop compiles against: the bundled one for `version` by default, or
+ * the one the flow carries (`.definitions([...])`) when the SDK bundles none —
+ * a designer-saved `core.logic.loop@1.0` keeps its `output`/`loopBack` handles
+ * only because its carried definition says so (#1311). A version with no
+ * definition at all counts as 2.x; its lookup fails later.
  */
-export declare function loopHasInnerHandles(version: string): boolean;
+export declare function loopHasInnerHandles(version: string, definition?: unknown): boolean;
 /**
  * The features this loop uses that its version's definition cannot express, in
  * a fixed order (`parallel`, `completionCondition`, `breakEnabled`, `break()`).
  * Empty when all are supported, or when no definition is bundled for the version
  * (an unknown version is reported elsewhere, by the definition lookup).
  */
-export declare function unsupportedLoopFeatures(options: LoopOptions | undefined, usesBreak: boolean): string[];
+export declare function unsupportedLoopFeatures(options: LoopOptions | undefined, usesBreak: boolean, definition?: unknown): string[];
+/** The inputs a loop definition declares (`collection`, `parallel`, `completionCondition`, `breakEnabled`, …). */
+export declare function loopDeclaredInputs(definition: unknown): Record<string, unknown>;
 /**
  * The refusal for a loop whose options or body need a definition the requested
  * version does not have, or `undefined` when there is nothing to refuse.
  * `serialize` throws it; `check` reports it as `LOOP_VERSION_UNSUPPORTED` with
- * the same text, so the author reads one message in both places.
+ * the same text, so the author reads one message in both places. `definition`
+ * is the one the loop compiles against (bundled, else carried), as for
+ * `loopHasInnerHandles`.
  */
-export declare function loopVersionRefusal(name: string, options: LoopOptions | undefined, usesBreak: boolean): string | undefined;
+export declare function loopVersionRefusal(name: string, options: LoopOptions | undefined, usesBreak: boolean, definition?: unknown): string | undefined;
 /**
  * The warning for `parallel: true` on a 1.0.0 loop, or `undefined`. The 1.0.0
  * definition declares the input, so the loop compiles and a canvas 1.0.0 loop
@@ -32,7 +49,7 @@ export declare function loopVersionRefusal(name: string, options: LoopOptions |
  * confirmed, so a new loop that needs that should use the default version.
  * `check` reports it as `LOOP_PARALLEL_LEGACY`.
  */
-export declare function loopParallelWarning(name: string, options: LoopOptions | undefined): string | undefined;
+export declare function loopParallelWarning(name: string, options: LoopOptions | undefined, definition?: unknown): string | undefined;
 /**
  * True when a container body (or an arm/handler inside it, but not a NESTED
  * container's body) breaks: a nested `.loop()`/`.doWhile()` owns its own

package/dist/loop-version.js

@@ -11,6 +11,15 @@ import { BUNDLED_DEFINITIONS } from './flow-definitions.js';
 export const LOOP_NODE_TYPE = 'core.logic.loop';
 /** The `core.logic.loop` version `.loop()` emits unless `{ version }` pins another. */
 export const LOOP_DEFAULT_VERSION = '2.4';
+/**
+ * The definition a loop at `version` compiles against: the bundled one, else
+ * the one the flow carries (`carried`, a `.definitions()` lookup), else
+ * `undefined`. `serialize` and `check` both resolve through this, so they agree
+ * on a carried `core.logic.loop@1.0`'s handles and inputs (#1311).
+ */
+export function resolveLoopDefinition(version, carried) {
+    return loopDefinition(version) ?? carried?.(LOOP_NODE_TYPE, version);
+}
 /** The version `.loop()` emits for these options. */
 export function loopVersion(options) {
     return options?.version ?? LOOP_DEFAULT_VERSION;
@@ -18,10 +27,16 @@ export function loopVersion(options) {
 /**
  * True when this loop version's body runs from the inner `start` handle and goes
  * back through `continue` (2.x); false for the legacy `output`/`loopBack` shape.
- * A version with no bundled definition counts as 2.x; its lookup fails later.
+ *
+ * The answer is read off the definition's target handles. `definition` is the
+ * one the loop compiles against: the bundled one for `version` by default, or
+ * the one the flow carries (`.definitions([...])`) when the SDK bundles none —
+ * a designer-saved `core.logic.loop@1.0` keeps its `output`/`loopBack` handles
+ * only because its carried definition says so (#1311). A version with no
+ * definition at all counts as 2.x; its lookup fails later.
  */
-export function loopHasInnerHandles(version) {
-    return loopDefinition(version) ? targetHandleIds(version).has('continue') : true;
+export function loopHasInnerHandles(version, definition = loopDefinition(version)) {
+    return definition ? targetHandleIdsOf(definition).has('continue') : true;
 }
 /** The loop options whose support depends on the version, in message order. */
 const VERSIONED_OPTIONS = ['parallel', 'completionCondition', 'breakEnabled'];
@@ -31,24 +46,29 @@ const VERSIONED_OPTIONS = ['parallel', 'completionCondition', 'breakEnabled'];
  * Empty when all are supported, or when no definition is bundled for the version
  * (an unknown version is reported elsewhere, by the definition lookup).
  */
-export function unsupportedLoopFeatures(options, usesBreak) {
-    const def = loopDefinition(loopVersion(options));
-    if (!def)
+export function unsupportedLoopFeatures(options, usesBreak, definition = loopDefinition(loopVersion(options))) {
+    if (!definition)
         return [];
-    const inputs = def.inputDefinition?.properties ?? {};
+    const inputs = loopDeclaredInputs(definition);
     const out = VERSIONED_OPTIONS.filter((k) => options?.[k] !== undefined && !(k in inputs));
-    if (usesBreak && !targetHandleIds(loopVersion(options)).has('break'))
+    if (usesBreak && !targetHandleIdsOf(definition).has('break'))
         out.push('break()');
     return out;
 }
+/** The inputs a loop definition declares (`collection`, `parallel`, `completionCondition`, `breakEnabled`, …). */
+export function loopDeclaredInputs(definition) {
+    return definition?.inputDefinition?.properties ?? {};
+}
 /**
  * The refusal for a loop whose options or body need a definition the requested
  * version does not have, or `undefined` when there is nothing to refuse.
  * `serialize` throws it; `check` reports it as `LOOP_VERSION_UNSUPPORTED` with
- * the same text, so the author reads one message in both places.
+ * the same text, so the author reads one message in both places. `definition`
+ * is the one the loop compiles against (bundled, else carried), as for
+ * `loopHasInnerHandles`.
  */
-export function loopVersionRefusal(name, options, usesBreak) {
-    const missing = unsupportedLoopFeatures(options, usesBreak);
+export function loopVersionRefusal(name, options, usesBreak, definition = loopDefinition(loopVersion(options))) {
+    const missing = unsupportedLoopFeatures(options, usesBreak, definition);
     if (missing.length === 0)
         return undefined;
     const version = loopVersion(options);
@@ -63,8 +83,8 @@ export function loopVersionRefusal(name, options, usesBreak) {
  * confirmed, so a new loop that needs that should use the default version.
  * `check` reports it as `LOOP_PARALLEL_LEGACY`.
  */
-export function loopParallelWarning(name, options) {
-    if (options?.parallel !== true || loopHasInnerHandles(loopVersion(options)))
+export function loopParallelWarning(name, options, definition = loopDefinition(loopVersion(options))) {
+    if (options?.parallel !== true || loopHasInnerHandles(loopVersion(options), definition))
         return undefined;
     return `loop "${name}": parallel: true on { version: '${loopVersion(options)}' } is written to the node, but `
         + `that version is not confirmed to run iterations in parallel, so the loop may run them one by one. `
@@ -86,9 +106,11 @@ export function bodyUsesBreak(steps) {
 function loopDefinition(version) {
     return BUNDLED_DEFINITIONS[`${LOOP_NODE_TYPE}@${version}`];
 }
-function targetHandleIds(version) {
+/** The ids of a definition's target handles (`input`, `loopBack`, `continue`, `break`, …). */
+function targetHandleIdsOf(definition) {
     const ids = new Set();
-    for (const group of loopDefinition(version)?.handleConfiguration ?? []) {
+    const groups = definition?.handleConfiguration ?? [];
+    for (const group of groups) {
         for (const h of group.handles ?? [])
             if (h.type === 'target')
                 ids.add(h.id);

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

@@ -30,6 +30,7 @@ export const HITL_DIAGNOSTICS = {
     HITL_FIELD_VALUE_NOT_REF: { severity: 'error', summary: 'a shown field filled from a literal' },
     HITL_FIELD_VALUE_NOT_PATH: { severity: 'error', summary: 'a shown field filled from a computed expression' },
     HITL_FIELD_DIRECTION: { severity: 'error', summary: 'a field direction that is not input, output or inOut' },
+    HITL_FIELD_VARIABLE: { severity: 'error', summary: "an asked field's variable that is not one identifier, or sits on a shown field" },
     HITL_NO_OUTCOMES: { severity: 'error', summary: 'no outcomes, so the task never completes' },
     HITL_OUTCOME_BAD_ID: { severity: 'error', summary: 'an outcome id that is not a non-empty string' },
     HITL_DUP_OUTCOME_ID: { severity: 'error', summary: 'two outcomes on one id' },
@@ -225,6 +226,20 @@ export function checkHitl(inputs, ctx) {
         for (const problem of formFieldSettingProblems(f)) {
             at('HITL_FIELD_SETTING_INVALID', `Human task "${step}" gives the form field "${id}" ${problem}. The platform refuses the form.`);
         }
+        // The landing variable is read as `$vars.<variable>`, so it has to be one
+        // identifier — not a path, not a `vars.` prefix — and only an asked field
+        // has one: a shown field's row is written without it (#1309).
+        const variable = f?.variable;
+        if (variable !== undefined) {
+            if (f?.direction !== 'output') {
+                at('HITL_FIELD_VARIABLE', `Human task "${step}"'s form field "${id}" sets \`variable\` on a ${f?.direction === 'inOut' ? 'pre-filled' : 'shown'} field. `
+                    + `Only an asked field (direction 'output') lands its answer in a variable; the SDK writes the row without one.`, 'Drop `variable`, or make the field direction: \'output\'.');
+            }
+            else if (typeof variable !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(variable)) {
+                at('HITL_FIELD_VARIABLE', `Human task "${step}"'s form field "${id}" has variable ${JSON.stringify(variable)}, which is not one identifier. `
+                    + `It is read as $vars.<variable>, so give the name only — no \`vars.\` prefix, no dots.`, typeof variable === 'string' && variable.startsWith('vars.') ? `variable: '${variable.slice(5)}'` : `variable: '${step}_${id}'`);
+            }
+        }
         if (isAnswerField(f))
             answers++; // an `output`, or an `inOut` whose reviewed value comes back
         if (f?.direction === 'input' || f?.direction === 'inOut') {

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

@@ -13,7 +13,7 @@
  * every edge out of an outcome-handle node to.
  */
 import { Expr, toExpr } from '../../../core/expr.js';
-import { formFieldJsonSchema, formFieldRowLoss, formFieldRowLossMessage, formFieldSettingsSource, formFieldSettingsWire, liftFormFieldSettings, sourceFormFieldType, wireFormFieldType, } from '../../../core/form-field-type.js';
+import { formFieldJsonSchema, formFieldRowLoss, formFieldRowLossMessage, formFieldSettingsSource, formFieldSettingsWire, formFieldVariableName, liftFormFieldSettings, sourceFormFieldType, wireFormFieldType, } from '../../../core/form-field-type.js';
 import { isAnswerField } from '../../../core/hitl-answers.js';
 import { OUTCOME_HANDLE_NODE_TYPES, hitlExitModel, outcomeIdOf, outcomeSlug } from '../../../core/hitl-routing.js';
 import { jsonClone } from '../../../core/json-clone.js';
@@ -82,8 +82,9 @@ function hitlInputs(inputs, nodeType, ctx) {
         else {
             // The answer's landing variable. The platform falls back to the field id
             // when this is absent; naming it keeps the emitted flow explicit and
-            // matches what the designer writes.
-            base.variable = `vars.${f.id}`;
+            // matches what the designer writes — `vars.<Step>_<field>` when the author
+            // (or the canvas) named one, else the field's own id (#1309).
+            base.variable = `vars.${f.variable ?? f.id}`;
             const required = f.required;
             if (typeof required === 'boolean')
                 base.required = required;
@@ -331,6 +332,11 @@ function liftHitl(node, typeName, ctx) {
         const id = String(f.id ?? '');
         const direction = String(f.direction ?? 'output');
         const value = direction === 'input' || direction === 'inOut' ? bindingExpr(f.binding) : undefined;
+        // An asked field's landing variable comes back when it is not the field's
+        // own id — the designer's `vars.<Step>_<field>` (#1309); `formFieldRowLoss`
+        // reports any other spelling.
+        const landing = direction === 'output' ? formFieldVariableName(f.variable) : undefined;
+        const variable = landing !== undefined && landing !== id ? landing : undefined;
         // Every row key the source cannot carry is reported, never dropped
         // silently: a warning, an error under --strict (#1250).
         const loss = formFieldRowLoss(f, 'human task');
@@ -346,6 +352,7 @@ function liftHitl(node, typeName, ctx) {
             direction,
             ...(value !== undefined ? { value } : {}),
             ...(typeof f.required === 'boolean' && direction !== 'input' ? { required: f.required } : {}),
+            ...(variable !== undefined ? { variable } : {}),
             ...liftFormFieldSettings(f),
         };
     });
@@ -509,6 +516,7 @@ function printHitl({ inputs }, ctx) {
         ['direction', ctx.string(f.direction)],
         ['value', f.value !== undefined ? ctx.value(f.value) : undefined],
         ['required', f.required !== undefined ? String(f.required) : undefined],
+        ['variable', f.variable !== undefined ? ctx.string(f.variable) : undefined],
         ...formFieldSettingsSource(f, ctx.value),
     ], ctx));
     const outcomes = h.outcomes.map((o) => (typeof o === 'string' ? ctx.string(o) : obj([
@@ -596,6 +604,13 @@ function hitlAt(typeName, version, factory) {
             .filter((f) => f?.direction === 'input')
             .map((f) => ({ value: f.value })),
         output: ({ inputs }) => ({ kind: 'reader', read: (read, report) => checkHitlRead(read, inputs, report) }),
+        // An asked field's answer lands in its `variable` (`vars.<Step>_<field>` as
+        // the designer names it), else in `vars.<id>` — serialize writes one or the
+        // other on every asked row — and later steps read it as `$vars.<name>`: the
+        // task declares that variable (#1309).
+        declares: ({ inputs }) => (inputs?.fields ?? [])
+            .map((f) => (f?.direction === 'output' ? (f.variable ?? f.id) : undefined))
+            .filter((v) => typeof v === 'string' && v !== ''),
         exits: hitlExits,
         // The base node and quick-form draw one `outcome-<id>` handle per outcome,
         // whatever the version; their definitions declare only `completed`.

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

@@ -722,6 +722,22 @@ function liftProcess(node, ctx, prefix, kind, form) {
             inputs[k] = legacyAgentTemplateInput(v);
     }
     const schema = def?.outputDefinition?.output?.schema?.properties;
+    const returns = schema && Object.keys(schema).length > 0
+        ? Object.fromEntries(Object.entries(schema).map(([k, v]) => [k, String(v?.type ?? 'string')]))
+        : undefined;
+    // The designer writes the process's output schema on the definition whether
+    // or not the step waits for it. `agenticProcess()` refuses `returns` beside
+    // `completion: 'fire-and-forget'` (a dispatch publishes no output, so nothing
+    // could read one), so the schema is not carried into source — said, not
+    // dropped silently (#1312). Merge keeps the original's definition row, so a
+    // no-edit round trip loses nothing in the file.
+    if (fireAndForget && returns !== undefined) {
+        const id = String(node.id ?? '');
+        ctx.lossy(`process step ${JSON.stringify(id)} is fire-and-forget, so the ${Object.keys(returns).length} output `
+            + `field(s) its definition declares (${Object.keys(returns).join(', ')}) are not written as \`returns\`: `
+            + `a fire-and-forget dispatch publishes no output, and agenticProcess() refuses the pair. Compile writes the `
+            + `definition without that schema. To read the process result, set completion: 'wait' and declare \`returns\`.`);
+    }
     const spec = {
         key,
         ...(name !== undefined ? { name } : {}),
@@ -729,8 +745,7 @@ function liftProcess(node, ctx, prefix, kind, form) {
         ...(!inSolution && folderPath !== undefined ? { folderPath } : {}),
         ...(inSolution && projectId !== undefined ? { projectId } : {}),
         ...(Object.keys(inputs).length ? { inputs: Object.fromEntries(Object.entries(inputs).map(([k, v]) => [k, lifted(v, ctx)])) } : {}),
-        ...(schema && Object.keys(schema).length > 0
-            ? { returns: Object.fromEntries(Object.entries(schema).map(([k, v]) => [k, String(v?.type ?? 'string')])) } : {}),
+        ...(returns !== undefined && !fireAndForget ? { returns } : {}),
         ...(form !== undefined ? { form } : {}),
         ...(fireAndForget ? { completion: 'fire-and-forget' } : {}),
     };

package/dist/serialize.js

@@ -8,8 +8,8 @@
  */
 import ixpDefinition from './core/ixp-definition.json' with { type: 'json' };
 import { BUNDLED_DEFINITIONS, bundledVersions } from './flow-definitions.js';
-import { LOOP_DEFAULT_VERSION, bodyUsesBreak, loopHasInnerHandles, loopVersion, loopVersionRefusal } from './loop-version.js';
-import { Expr, toExpr, SCHEDULE_PRESETS, parseIxpProjectType, flatNameSegmentsOf } from './flow-sdk.js';
+import { LOOP_DEFAULT_VERSION, bodyUsesBreak, loopDeclaredInputs, loopHasInnerHandles, loopVersion, loopVersionRefusal } from './loop-version.js';
+import { Expr, toExpr, SCHEDULE_PRESETS, parseIxpProjectType, flatNameSegmentsOf, parallelFork } from './flow-sdk.js';
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { rawNodeInputProblem, registeredRawType } from './raw-node-advice.js';
@@ -1656,6 +1656,12 @@ function stepNamesOf(steps, out = [], terminates) {
         // End id is claimed as `end`); `stepToRef` has no `name` at all (it is one edge).
         if ('name' in s && s.kind !== 'return')
             out.push(s.name);
+        // A `.parallel` with a fork node claims that node's name too (#1310).
+        if (s.kind === 'parallel') {
+            const fork = parallelFork(s.options);
+            if (fork)
+                out.push(fork.name);
+        }
         // How many `.terminate`s hold each name, so a clash gets the right remedy (#1239).
         if (s.kind === 'terminate' && terminates)
             terminates.set(s.name, (terminates.get(s.name) ?? 0) + 1);
@@ -1705,6 +1711,11 @@ function namedNodesOf(steps, out = { steps: [], ends: [] }, seenEnds = new Set()
         }
         else if ('name' in s)
             out.steps.push(s.name);
+        if (s.kind === 'parallel') {
+            const fork = parallelFork(s.options);
+            if (fork)
+                out.steps.push(fork.name);
+        }
         if (s.kind === 'stepToList')
             namedNodesOf(s.body, out, seenEnds);
         else if (s.kind === 'branch') {
@@ -3227,6 +3238,29 @@ export function serialize(built, opts = {}) {
                 // one, hang the run with no incident. check reports both
                 // (HITL_FAN_OUT_INTO_JOIN, HITL_END_OUTCOME_IN_PARALLEL); this is the
                 // compile-side half, and it fails closed.
+                // The fork, when the author names one (`{ fork }`, #1310): a merge node
+                // with one incoming edge and one edge per arm — the gateway Studio Web
+                // draws for a parallel split. The arms then leave from it instead of
+                // from the step before.
+                const fork = parallelFork(step.options);
+                if (fork) {
+                    // The gateway waits for a token on EVERY incoming edge, so two tails
+                    // that are alternatives — a `.branch()`'s or `.switch()`'s arms, a
+                    // fan-out task's outcomes — must not both enter it: only one fires
+                    // and the arms never start. Fails closed, as the join does.
+                    if (tails.length > 1) {
+                        throw new Error(`.parallel("${step.name}"): its fork "${fork.name}" would receive ${tails.length} alternative edges `
+                            + `(${tails.map((t) => `${t.node}@${t.port}`).join(', ')}), and only one of them fires while the gateway `
+                            + `waits for all of them. Add a step before the .parallel so the paths meet there first, or drop { fork }.`);
+                    }
+                    const forkId = stepUid(scope, fork.name);
+                    const forkNode = makeNode(NODE_TYPE.merge, forkId, fork.label ?? fork.name, { parentId, requestedVersion: fork.version ?? step.options?.version });
+                    forkNode.inputs = {};
+                    scope.nodes.push(forkNode);
+                    for (const t of tails)
+                        addEdge(scope, t, forkId);
+                    tails = [{ node: forkId, port: successPort(NODE_TYPE.merge) }];
+                }
                 const armTails = [];
                 const endsBefore = hitlEndExits.length;
                 for (const arm of step.arms) {
@@ -3292,23 +3326,30 @@ export function serialize(built, opts = {}) {
                 // An option or a .break() the pinned version's definition cannot express
                 // is a contradiction the author must resolve, not a silent drop; `check`
                 // reports the same refusal from the same helper (#1186).
-                const refusal = loopVersionRefusal(step.name, o, usesBreak);
+                const version = loopVersion(o);
+                // The definition the loop compiles against decides its handles AND its
+                // inputs: a carried `core.logic.loop@1.0` (a designer-saved file's own)
+                // keeps its `output`/`loopBack` pair, where the bundled lookup alone
+                // would have written 2.4's `start`/`continue` onto a 1.0 node (#1311),
+                // and an option is written when that definition declares the input
+                // (the carried 1.0 declares `completionCondition`; the bundled 1.0.0
+                // does not) and refused when it does not.
+                const loopDef = definitionFor(NODE_TYPE.loop, version);
+                const refusal = loopVersionRefusal(step.name, o, usesBreak, loopDef);
                 if (refusal)
                     throw new Error(refusal);
-                const version = loopVersion(o);
-                const v24 = loopHasInnerHandles(version);
+                const v24 = loopHasInnerHandles(version, loopDef);
+                const declared = loopDeclaredInputs(loopDef);
                 const id = stepUid(scope, step.name);
                 const node = makeNode(NODE_TYPE.loop, id, step.options?.label ?? step.label ?? step.name, { parentId, requestedVersion: version });
-                node.inputs = v24
-                    ? {
-                        collection: renderValue(step.collection, scope.rename),
-                        parallel: o.parallel ?? false,
-                        ...(o.completionCondition !== undefined
-                            ? { completionCondition: renameRefs(o.completionCondition.js, scope.rename) }
-                            : {}),
-                        breakEnabled: (o.breakEnabled ?? false) || usesBreak,
-                    }
-                    : { collection: renderValue(step.collection, scope.rename), parallel: o.parallel ?? false };
+                node.inputs = {
+                    collection: renderValue(step.collection, scope.rename),
+                    parallel: o.parallel ?? false,
+                    ...(o.completionCondition !== undefined && (v24 || 'completionCondition' in declared)
+                        ? { completionCondition: renameRefs(o.completionCondition.js, scope.rename) }
+                        : {}),
+                    ...(v24 || 'breakEnabled' in declared ? { breakEnabled: (o.breakEnabled ?? false) || usesBreak } : {}),
+                };
                 scope.nodes.push(node);
                 for (const t of tails)
                     addEdge(scope, t, id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.43.0",
+  "version": "6.44.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "572ec05cde3b8e5f4e1c102ed2cfa3f0baaa95b0"
+  "gitref": "7075376040d8eb546745a5457c894dbc168448c8"
 }