@uipath/maestro-builder-sdk 6.43.0 → 6.44.1

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/merge.d.ts

@@ -26,9 +26,11 @@
  *     as decompile was faithful for every node (the common case).
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
- * preserved from the original; `subflows` and edges (with their ids) come from
- * `edited`; root `variables` merge as a delta per entry, like nodes
- * (merge-variables.ts); `definitions` and `bindings` are unioned
+ * preserved from the original, apart from the `layout.nodes` entries of
+ * removed nodes (dropped) and added nodes (node-placement.ts); `subflows` and
+ * edges (with their ids) come from `edited`; root `variables` merge as a
+ * delta per entry, like nodes (merge-variables.ts); `definitions` and
+ * `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
  * authority). A binding row's identity is what it binds, not its row id, and a
  * row the no-edit recompile minted only for nodes merge kept from the original

package/dist/merge.js

@@ -26,9 +26,11 @@
  *     as decompile was faithful for every node (the common case).
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
- * preserved from the original; `subflows` and edges (with their ids) come from
- * `edited`; root `variables` merge as a delta per entry, like nodes
- * (merge-variables.ts); `definitions` and `bindings` are unioned
+ * preserved from the original, apart from the `layout.nodes` entries of
+ * removed nodes (dropped) and added nodes (node-placement.ts); `subflows` and
+ * edges (with their ids) come from `edited`; root `variables` merge as a
+ * delta per entry, like nodes (merge-variables.ts); `definitions` and
+ * `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
  * authority). A binding row's identity is what it binds, not its row id, and a
  * row the no-edit recompile minted only for nodes merge kept from the original
@@ -261,6 +263,11 @@ function layoutNodesOf(f) {
     const nodes = f.layout?.nodes;
     return nodes && typeof nodes === 'object' && !Array.isArray(nodes) ? nodes : undefined;
 }
+/** The original's `layout.nodes` when it holds positions. An SDK compile writes `{}` there and keeps them on `node.ui`. */
+function positionStoreOf(f) {
+    const nodes = layoutNodesOf(f);
+    return nodes && Object.keys(nodes).length > 0 ? nodes : undefined;
+}
 export function mergeFlow(original, edited, options = {}) {
     const { result, findings } = mergeFlowFindings(original, edited, options);
     reportOrRefuse(findings, options);
@@ -374,12 +381,13 @@ function mergeFlowFindings(original, edited, options) {
     //    one already taken elsewhere in the file, gets a fresh id, from ids unused
     //    anywhere in the file. ──
     result.edges = withFileUniqueEdgeIds(edited.edges ?? [], subflowScopes);
-    // ── Placement: a node the edit ADDED has only compile's placeholder, an
-    //    emission-index slot that can land on an original node. Put it next to
-    //    its predecessor, collision-free, in the store the
-    //    original uses — see node-placement.ts. Root scope only: a subflow is
-    //    taken from `edited` whole, layout included. ──
-    placeAddedNodes(finalNodes, result.edges, layoutNodesOf(result), (id) => !origNodes.has(id));
+    // ── Placement: a node the edit ADDED has no original position. Unless the
+    //    author set one, it has compile's placeholder, an emission-index slot
+    //    that can land on an original node. Put it next to its predecessor,
+    //    collision-free, and store every added node's position where the
+    //    original stores positions — see node-placement.ts. Root scope only: a
+    //    subflow is taken from `edited` whole, layout included. ──
+    placeAddedNodes(finalNodes, result.edges, positionStoreOf(original) && layoutNodesOf(result), (id) => !origNodes.has(id));
     // ── Definitions: the (type, version) pairs used by EVERY node in the file —
     //    root and subflows — original winning on conflict (its defs are the
     //    tenant-resolved authority). Selecting by root nodes only dropped the
@@ -398,7 +406,9 @@ function mergeFlowFindings(original, edited, options) {
     result.bindings = mergeBindings(original.bindings, edited.bindings);
     result.bindings = withoutRowsMintedForKeptNodes(result.bindings, original, edited, options.baseline, keptFromOriginal);
     // metadata / solutionId / projectId / layout / runtime were carried by the
-    // initial clone of `original` and are intentionally left untouched.
+    // initial clone of `original` and are intentionally left untouched, apart
+    // from the `layout.nodes` entries of removed nodes (dropped above) and added
+    // nodes (placement).
     //
     // The declared file-format `version` follows the same delta rule the nodes
     // do. The original's wins by default, because a compile of an edited source

package/dist/node-placement.d.ts

@@ -19,7 +19,7 @@
  * A child's position is relative to its container, as on the canvas.
  *
  * The position goes where the original stores positions: `layout.nodes[id]`
- * when it has a `layout.nodes` map, otherwise `node.ui`. Positions are read the
+ * when its `layout.nodes` has entries, otherwise `node.ui`. Positions are read the
  * way the designer reads them (flow-workbench `flow-schema`
  * `workflow-format-conversion.ts` `mergeLayout`): a `layout.nodes[id]` entry
  * wins over `node.ui`, field by field.
@@ -77,13 +77,14 @@ interface PlacedNode {
  * its placeholder, and placed nodes avoid it.
  *
  * Where the result is written follows the file: when the original stores
- * positions in `layout.nodes` (every canvas-saved file does), the position goes
- * there and the placeholder `node.ui` is dropped, so the file has one store;
- * otherwise `node.ui.position` is updated.
+ * positions in `layout.nodes` (every canvas-saved file does), every added
+ * node's `node.ui`, placed or not, sticky notes included, replaces its
+ * `layout.nodes` entry, so the node has one position; otherwise
+ * `node.ui.position` is updated.
  *
  * @param nodes - The merged root nodes (mutated).
  * @param edges - The merged root edges.
- * @param layoutNodes - The merged file's `layout.nodes`, or undefined when the original has none (mutated).
+ * @param layoutNodes - The merged file's `layout.nodes`, or undefined when the original keeps positions on `node.ui` (mutated).
  * @param isAdded - Whether a node id is new in this merge.
  */
 export declare function placeAddedNodes(nodes: PlacedNode[], edges: ReadonlyArray<{

package/dist/node-placement.js

@@ -19,7 +19,7 @@
  * A child's position is relative to its container, as on the canvas.
  *
  * The position goes where the original stores positions: `layout.nodes[id]`
- * when it has a `layout.nodes` map, otherwise `node.ui`. Positions are read the
+ * when its `layout.nodes` has entries, otherwise `node.ui`. Positions are read the
  * way the designer reads them (flow-workbench `flow-schema`
  * `workflow-format-conversion.ts` `mergeLayout`): a `layout.nodes[id]` entry
  * wins over `node.ui`, field by field.
@@ -83,6 +83,21 @@ function findFreePosition(candidate, size, others) {
     }
     return candidate;
 }
+/**
+ * Move each added node's `ui` into `layoutNodes`, replacing any entry under its
+ * id: the original can hold an entry for an id it has no node for.
+ */
+function moveAddedUi(nodes, layoutNodes, isAdded) {
+    for (const n of nodes) {
+        if (!isAdded(n.id))
+            continue;
+        if (n.ui === undefined)
+            delete layoutNodes[n.id];
+        else
+            layoutNodes[n.id] = n.ui;
+        delete n.ui;
+    }
+}
 /**
  * Give each node the edit added a position next to its predecessor, in place.
  *
@@ -95,16 +110,19 @@ function findFreePosition(candidate, size, others) {
  * its placeholder, and placed nodes avoid it.
  *
  * Where the result is written follows the file: when the original stores
- * positions in `layout.nodes` (every canvas-saved file does), the position goes
- * there and the placeholder `node.ui` is dropped, so the file has one store;
- * otherwise `node.ui.position` is updated.
+ * positions in `layout.nodes` (every canvas-saved file does), every added
+ * node's `node.ui`, placed or not, sticky notes included, replaces its
+ * `layout.nodes` entry, so the node has one position; otherwise
+ * `node.ui.position` is updated.
  *
  * @param nodes - The merged root nodes (mutated).
  * @param edges - The merged root edges.
- * @param layoutNodes - The merged file's `layout.nodes`, or undefined when the original has none (mutated).
+ * @param layoutNodes - The merged file's `layout.nodes`, or undefined when the original keeps positions on `node.ui` (mutated).
  * @param isAdded - Whether a node id is new in this merge.
  */
 export function placeAddedNodes(nodes, edges, layoutNodes, isAdded) {
+    if (layoutNodes)
+        moveAddedUi(nodes, layoutNodes, isAdded);
     const byId = new Map(nodes.map((n) => [n.id, n]));
     const uiOf = (n) => {
         const entry = layoutNodes?.[n.id];
@@ -149,13 +167,10 @@ export function placeAddedNodes(nodes, edges, layoutNodes, isAdded) {
                 .map((o) => ({ ...uiOf(o).position, ...sizeOf(o) }));
             const position = findFreePosition(candidate, sizeOf(n), others);
             const ui = { ...uiOf(n), position };
-            if (layoutNodes) {
+            if (layoutNodes)
                 layoutNodes[id] = ui;
-                delete n.ui;
-            }
-            else {
+            else
                 n.ui = ui;
-            }
             pending.delete(id);
             progress = true;
         }

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' } : {}),
     };