@uipath/maestro-builder-sdk 6.43.0 → 6.44.0

package/dist/check.js

@@ -5,7 +5,7 @@
  * duplicate step names, references to undeclared variables/steps, empty branch
  * arms, and missing terminals.
  */
-import { Expr, SCHEDULE_PRESETS, parseIxpProjectType } from './flow-sdk.js';
+import { Expr, SCHEDULE_PRESETS, parseIxpProjectType, parallelFork } from './flow-sdk.js';
 import { FlowNode } from './core/node-classes.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
 import { definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
@@ -26,10 +26,11 @@ import { terminateStepClashMessage, terminateTwiceMessage } from './flow-termina
 import { endContentKey } from './flow-end-content.js';
 import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { stepExits } from './flow-step-exits.js';
+import { stepDeclaredVariables } from './flow-step-variables.js';
 import { plainHttpOnErrorMessage } from './nodes/http/flow/family.js';
 import { resolveVersion, resolveVersionCarried } from './core/nodes/versioned.js';
 import { declaredErrorPortRefusal } from './core/error-port.js';
-import { bodyUsesBreak, loopParallelWarning, loopVersionRefusal } from './loop-version.js';
+import { bodyUsesBreak, loopParallelWarning, loopVersionRefusal, resolveLoopDefinition, loopVersion } from './loop-version.js';
 const newResourceIdLedger = () => ({ explicit: new Map(), taken: new Map(), agentSources: new Map() });
 /** INLINE_AGENT_RESOURCE_NODE_ID for each explicit `nodeId` another node of the file also gets. */
 function resourceNodeIdClashes(ledger) {
@@ -337,6 +338,11 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                 }
                 stepNames.add(s.name);
                 declared.add(s.name); // a step's output is referenceable by name
+                // …and so is every variable the step declares by running: a quick
+                // form's asked field lands in its `variable` (#1309).
+                if (s.kind === 'action')
+                    for (const v of stepDeclaredVariables(s.spec, s.options?.version))
+                        declared.add(v);
             }
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'error')
                 checkOnError(s, prevPortSource, diags, prevPortSource && checkedSteps.get(prevPortSource.name), carriedLookup([built, ...ancestors]));
@@ -687,6 +693,20 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
             }
             else if (s.kind === 'parallel') {
                 parallelNames.add(s.name);
+                // The fork node is a node too (#1310): its name is a step name for
+                // clashes, and a read of it is a read of a merge — nothing.
+                const fork = parallelFork(s.options);
+                if (fork) {
+                    if (stepNames.has(fork.name)) {
+                        diags.push({
+                            level: 'error', code: 'DUP_STEP', step: s.name,
+                            message: `Duplicate step name "${fork.name}": the fork of parallel "${s.name}" and another step share it.`,
+                        });
+                    }
+                    stepNames.add(fork.name);
+                    declared.add(fork.name);
+                    parallelNames.add(fork.name);
+                }
                 checkParallel(s, diags);
                 for (const arm of s.arms)
                     walk(arm, inLoop ? 'arm' : false);
@@ -701,10 +721,14 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                     addExpr(s.options.completionCondition.js, s.name);
                 // The same refusal serialize throws, from the same helper: an option or
                 // a `.break()` the pinned version's definition cannot express (#1186).
-                const versionRefusal = loopVersionRefusal(s.name, s.options, bodyUsesBreak(s.body));
+                // Against the definition the loop compiles against — bundled, else
+                // carried — as serialize resolves it, so a carried 1.0's `.break()`
+                // and `parallel: true` are judged here and not first at compile (#1311).
+                const loopDef = resolveLoopDefinition(loopVersion(s.options), carriedLookup([built, ...ancestors]));
+                const versionRefusal = loopVersionRefusal(s.name, s.options, bodyUsesBreak(s.body), loopDef);
                 if (versionRefusal)
                     diags.push({ level: 'error', code: 'LOOP_VERSION_UNSUPPORTED', step: s.name, message: versionRefusal });
-                const parallelWarning = loopParallelWarning(s.name, s.options);
+                const parallelWarning = loopParallelWarning(s.name, s.options, loopDef);
                 if (parallelWarning)
                     diags.push({ level: 'warning', code: 'LOOP_PARALLEL_LEGACY', step: s.name, message: parallelWarning });
                 loopNames.set(s.name, s.options?.version === '1.0.0' ? LOOP_FIELDS_1_0_0 : LOOP_FIELDS);
@@ -3316,8 +3340,22 @@ function checkStepRefs(built, diags, reservedIds = []) {
                 s.cases.forEach((c) => index(c.body, portList, scope, arm));
                 index(s.default ?? [], portList, scope, arm);
             }
-            else if (s.kind === 'parallel')
+            else if (s.kind === 'parallel') {
+                // The fork node (`{ fork }`, #1310) is a node in this scope like the
+                // join: a `.stepToRef(<fork>)` is an edge serialize resolves.
+                const fork = parallelFork(s.options);
+                if (fork) {
+                    stepNamesSeen.add(fork.name);
+                    if (!order.has(fork.name))
+                        order.set(fork.name, seq);
+                    if (portList)
+                        inPortList.add(fork.name);
+                    scopeOf.set(fork.name, scope);
+                    if (arm)
+                        armOf.set(fork.name, arm);
+                }
                 s.arms.forEach((a, i) => index(a, portList, scope, `${s.name}#${i}`));
+            }
             // A loop body is a bpmn:SubProcess — its own containment scope.
             else if (s.kind === 'loop' || s.kind === 'doWhile')
                 index(s.body, portList, s.name, arm);
@@ -3406,12 +3444,27 @@ function checkStepRefs(built, diags, reservedIds = []) {
                 s.cases.forEach((c) => collect(c.body, source, scope, arm, enclosing));
                 collect(s.default ?? [], source, scope, arm, enclosing);
             }
-            else if (s.kind === 'parallel')
-                s.arms.forEach((a, i) => collect(a, source, scope, `${s.name}#${i}`, enclosing));
+            else if (s.kind === 'parallel') {
+                // Arms that all end in `.stepToRef(<one step>)` (or stop) have no Merge:
+                // serialize writes none when no arm hands it a tail, and the refs ARE the
+                // join — the canvas shape of two steps feeding one (#1310). A ref there
+                // is not leaving the arm without reaching its merge.
+                const refJoinTarget = parallelRefJoin(s.arms);
+                s.arms.forEach((a, i) => {
+                    const key = `${s.name}#${i}`;
+                    if (refJoinTarget !== undefined)
+                        refJoin.set(key, refJoinTarget);
+                    collect(a, source, scope, key, enclosing);
+                });
+            }
             else if (s.kind === 'loop' || s.kind === 'doWhile')
                 collect(s.body, source, s.name, arm, [...enclosing, s.name]);
         }
     };
+    /** The step every arm of a parallel refs instead of a Merge, by `<parallel>#<arm>`. */
+    const refJoin = new Map();
+    /** `<parallel>\0<target>` pairs PARALLEL_REF_JOIN has been said for. */
+    const refJoinSaid = new Set();
     collect(built.steps, undefined, '', undefined);
     for (const ep of built.entryPoints ?? [])
         collect(ep.steps, ep.id, '', undefined);
@@ -3498,6 +3551,22 @@ function checkStepRefs(built, diags, reservedIds = []) {
                     + `on is a bpmn:ParallelGateway, which waits for every branch it forked — an extra token arriving inside `
                     + `an arm is not one of them, so the join may never settle. Verify with uip maestro flow validate.`);
             }
+            else if (arm !== undefined && refJoin.get(arm) === target) {
+                // The arms meet at a plain step, not a Merge: that step has one incoming
+                // edge per arm, and the runtime starts a step once per token that
+                // arrives (only a gateway waits for every incoming flow). So it runs
+                // once per arm, which is not what `.parallel`'s join promises. Said
+                // once per parallel, not once per arm (#1310).
+                const parallel = arm.slice(0, arm.lastIndexOf('#'));
+                if (!refJoinSaid.has(`${parallel}\0${target}`)) {
+                    refJoinSaid.add(`${parallel}\0${target}`);
+                    say('warning', 'PARALLEL_REF_JOIN', `"${target}" is where every arm of parallel "${parallel}" ends by .stepToRef, so it has one incoming edge `
+                        + `per arm and no Merge node. The runtime starts a step once per token that arrives, so "${target}" runs `
+                        + `once per arm — not once after all arms, as .parallel's Merge would. To run it once, end each arm on a `
+                        + `step of its own and put "${target}" after the .parallel. A canvas flow drawn this way behaves the same, `
+                        + `so leave a decompiled one as it is.`);
+                }
+            }
             else if (arm !== undefined) {
                 say('warning', 'REF_OUT_OF_PARALLEL_ARM', `.stepToRef('${target}') ${where} leaves a parallel arm without reaching its Merge. That Merge waits for `
                     + `every branch it forked, so the token this arm owed it never arrives and the join may hang. Verify with `
@@ -3648,3 +3717,28 @@ function checkContribution(node, requestedVersion, step, ownError, diags) {
         return;
     diags.push({ level: 'error', code: 'CONTRIBUTION_BINDING_UNRESOLVED', step, message: plan.problems.join(' ') });
 }
+/**
+ * The one step every arm of a `.parallel` ends by referring to, when the arms
+ * join there instead of on a Merge: each arm ends in `.stepToRef(<that step>)`
+ * on its default port, or stops (`.return()`, `.terminate()`), and at least one
+ * refs. `undefined` when some arm has a tail (serialize then emits the Merge) or
+ * the refs disagree. The decompiler writes a step fed by several steps this way
+ * (#1310).
+ */
+function parallelRefJoin(arms) {
+    let target;
+    for (const arm of arms) {
+        const last = arm[arm.length - 1];
+        if (last === undefined)
+            return undefined;
+        // An arm that ends the run or the iteration hands the join nothing either.
+        if (last.kind === 'return' || last.kind === 'terminate' || last.kind === 'break' || last.kind === 'continue')
+            continue;
+        if (last.kind !== 'stepToRef' || last.port !== 'output')
+            return undefined;
+        if (target !== undefined && target !== last.target)
+            return undefined;
+        target = last.target;
+    }
+    return target;
+}

package/dist/core/actions.d.ts

@@ -228,6 +228,15 @@ export interface AskedField extends FormFieldSettings {
     direction: 'output';
     /** Reviewer must fill it in before the task can be completed. */
     required?: boolean;
+    /**
+     * The flow variable the answer lands in, read downstream as `$vars.<variable>`
+     * (`v('<variable>')`) — the name only, without the `vars.` prefix. Defaults to
+     * the field id. Studio Web names it `<Step>_<field>` (`P_comments`) and later
+     * steps read `$vars.P_comments` or bind `vars.P_comments`; declaring it here is
+     * what makes those reads resolve, so a designer-saved approval flow round-trips
+     * through the SDK. The answer is also always `out('<step>', '<id>')`.
+     */
+    variable?: string;
 }
 /**
  * A value the reviewer READS **and can correct**: pre-filled from the flow,

package/dist/core/form-field-type.d.ts

@@ -205,6 +205,13 @@ export declare function formFieldSettingsSource(settings: FormFieldSettings, val
  * neither (the agent fills the form).
  */
 export type FormRowSite = 'human task' | 'escalation';
+/**
+ * The variable NAME an asked field's `variable` row key names — `P_comments`
+ * for `vars.P_comments` — or `undefined` when the value is not a `vars.<name>`
+ * path to one identifier. That is the only shape the SDK writes (the field's
+ * `variable` option, else its id), so anything else is reported as a loss.
+ */
+export declare function formFieldVariableName(variable: unknown): string | undefined;
 /**
  * The keys of a form row the SDK cannot carry into source, each with why.
  * Empty when decompile → compile writes the row back as it was. The lifts

package/dist/core/form-field-type.js

@@ -462,6 +462,16 @@ export function liftFormFieldSettings(row) {
 export function formFieldSettingsSource(settings, value) {
     return FORM_FIELD_SETTINGS_KEYS.map((key) => [key, settings[key] === undefined ? undefined : value(settings[key])]);
 }
+/**
+ * The variable NAME an asked field's `variable` row key names — `P_comments`
+ * for `vars.P_comments` — or `undefined` when the value is not a `vars.<name>`
+ * path to one identifier. That is the only shape the SDK writes (the field's
+ * `variable` option, else its id), so anything else is reported as a loss.
+ */
+export function formFieldVariableName(variable) {
+    const m = typeof variable === 'string' ? /^vars\.([A-Za-z_$][\w$]*)$/.exec(variable) : null;
+    return m ? m[1] : undefined;
+}
 /**
  * The keys of a form row the SDK cannot carry into source, each with why.
  * Empty when decompile → compile writes the row back as it was. The lifts
@@ -521,8 +531,8 @@ export function formFieldRowLoss(row, site) {
                 say(key, 'on an escalation form, which the SDK writes without variables');
             else if (direction !== 'output')
                 say(key, 'on a shown or pre-filled field, which the SDK writes without one');
-            else if (row.variable !== `vars.${id}`)
-                say(key, `the SDK writes 'vars.${id}', the field's own id`);
+            else if (formFieldVariableName(row.variable) === undefined)
+                say(key, `not a 'vars.<name>' path, which is what the SDK writes ('vars.${id}' by default)`);
         }
     }
     return loss;

package/dist/decompile.js

@@ -191,14 +191,30 @@ function shippedVersions(type) {
  * The options argument of `.branch()`, `.switch()` and `.parallel()`: the exact
  * `version`, and a canvas `label` that differs from the node id (what compile
  * writes when none is given). No `updates`: those constructs refuse them.
+ *
+ * `node` is the construct's own node (a `.parallel`'s join); `fork` is the
+ * merge node a designer-drawn parallel split leaves from, written as
+ * `{ fork }` (#1310). A `.parallel` whose arms rejoin on a plain step has no
+ * join node, so `node` may be absent; the fork then supplies the version.
  */
-function forkOptsArg(node) {
+function forkOptsArg(node, fork) {
     const parts = [];
-    const ver = verClause(node);
+    const ver = node ? verClause(node) : fork ? verClause(fork) : '';
     if (ver)
         parts.push(ver);
-    if (hasRenamedLabel(node, node.id))
+    if (node && hasRenamedLabel(node, node.id))
         parts.push(`label: ${tsLiteral(node.display.label)}`);
+    if (fork) {
+        // The fork's own version, when the join's clause does not already say it
+        // (no join node, or a different version on each).
+        const forkVer = node && node.typeVersion !== fork.typeVersion ? verClause(fork) : '';
+        const forkParts = [
+            `name: ${tsLiteral(fork.id)}`,
+            ...(hasRenamedLabel(fork, fork.id) ? [`label: ${tsLiteral(fork.display.label)}`] : []),
+            ...(forkVer ? [forkVer] : []),
+        ];
+        parts.push(forkParts.length === 1 ? `fork: ${tsLiteral(fork.id)}` : `fork: { ${forkParts.join(', ')} }`);
+    }
     return parts.length ? `, { ${parts.join(', ')} }` : '';
 }
 /**
@@ -322,6 +338,19 @@ function unwrapSource(v) {
     }
     return undefined;
 }
+/**
+ * The JS body of a condition slot (a decision's `expression`, a switch case's
+ * `expression`), whichever spelling the file uses: a bare JS string (the classic
+ * CLI), a `{ type: 'jsExpression', expression }` envelope (what Studio Web
+ * writes), or a `=js:`-prefixed string, with or without a space after the colon
+ * (`=js: ($vars.x ?? 0) > 0`). Before this, the envelope was stringified to
+ * `[object Object]` and the prefixed spelling was kept inside the template, so
+ * every designer-saved decision came back as source compile refused (#1308).
+ */
+function conditionText(v) {
+    const raw = unwrapSource(v);
+    return raw === undefined ? String(v ?? '') : wireExprBody(raw).trim();
+}
 /** A plain (boolean/number) input value, unwrapping a literal EV envelope if present. */
 function unwrapPlain(v) {
     if (v && typeof v === 'object' && 'expression' in v && v.type === 'literal') {
@@ -1513,7 +1542,11 @@ function forkRegion(edges, stop, scope, ipdom, ctx, refInto) {
     const targets = edges.map((e) => e.targetNodeId);
     const join = commonPostDominator(targets, ipdom);
     const joinNode = join !== undefined ? ctx.graph.byId.get(join) : undefined;
-    if (join === undefined || join === stop || joinNode?.type !== T.merge) {
+    // Arms may rejoin at the region's own continuation (`stop`) when that is a
+    // plain step: the arms end in `.stepToRef(stop)` and nothing follows them
+    // here. Not at a merge node that is `stop`: the enclosing construct continues
+    // from it, so a `.parallel` inside this arm cannot also own it.
+    if (join === undefined || joinNode === undefined || !parallelJoinable(joinNode) || (join === stop && joinNode.type === T.merge)) {
         if (ctx.o.bestEffort === false)
             throw new Error(`decompile: unstructured fan-out (${edges.length} edges).`);
         ctx.graph.accounted.add(edges[0]);
@@ -1525,22 +1558,75 @@ function forkRegion(edges, stop, scope, ipdom, ctx, refInto) {
     }
     for (const e of edges)
         ctx.graph.accounted.add(e);
-    const fork = parallelSeg(join, joinNode, targets, scope, ipdom, ctx, refInto);
+    const fork = parallelSeg(join, joinNode, targets, scope, ipdom, ctx, refInto, undefined, edges[0].sourceNodeId);
     if (fork.next.brk || fork.next.cont)
         return [fork.seg, fork.next.brk ? '.break()' : '.continue()'];
     return [fork.seg, ...region(fork.next.cursor, stop, scope, ipdom, ctx, refInto)];
 }
+/**
+ * Whether a fan-out whose arms all reconverge at `join` folds to a
+ * `.parallel(...)`: at a merge node, the SDK's own join; at any other step (a
+ * step, a decision, a loop, …), the canvas shape of several steps feeding one
+ * (#1310), which the arms spell by ending in `.stepToRef(join)` — serialize
+ * writes no merge node when no arm hands it a tail. Not at an End or a
+ * Terminate: arms that all end share the End by name (#1231/#1239) and nothing
+ * follows, which is another fold (#1267).
+ */
+function parallelJoinable(join) {
+    return join.type !== T.end && join.type !== T.terminate;
+}
 /**
  * The `.parallel(join, [arms])` segment for a fork whose `targets` (one per
- * edge; the caller accounts those edges) meet at the merge node `join`. Each
- * arm is the region up to `join`. `next` is where the walk goes after the
- * merge: its `output` edge, accounted by `continueOn` (`brk` / `cont` when
- * that edge leaves through the enclosing loop's `break` / spelled `continue`).
+ * edge; the caller accounts those edges) meet at `join`. Each arm is the
+ * region up to `join`.
+ *
+ * At a merge node, `join` names the `.parallel` and `next` is where the walk
+ * goes after it: its `output` edge, accounted by `continueOn` (`brk` / `cont`
+ * when that edge leaves through the enclosing loop's `break` / spelled
+ * `continue`). At any other step (#1310) the arms end in `.stepToRef(join)`,
+ * the `.parallel` gets a fresh name (`forkName`, after `source`) because no
+ * node carries one, and `next` is `join` itself: the main path emits it, and
+ * its only incoming edges are the arms' refs.
+ *
+ * `fork` is the merge node a designer-drawn split leaves from, written as
+ * `{ fork }` (#1310); the caller accounts its outgoing edges.
  */
-function parallelSeg(join, joinNode, targets, scope, ipdom, ctx, refInto) {
-    const arms = targets.map((t, i) => armCb(`a${i}`, region(t, join, scope, ipdom, ctx, refInto)));
-    const seg = `.parallel(${tsLiteral(join)}, [\n${arms.map((a) => reindent(a, '  ')).join(',\n')},\n]${forkOptsArg(joinNode)})`;
-    return { seg, next: continueOn(joinNode, 'output', ctx, refInto) };
+function parallelSeg(join, joinNode, targets, scope, ipdom, ctx, refInto, fork, source) {
+    const atMerge = joinNode.type === T.merge;
+    const name = atMerge ? join : forkName(source ?? fork?.id, ctx);
+    const arms = targets.map((t, i) => {
+        const segs = region(t, join, scope, ipdom, ctx, refInto);
+        // The arm hands the join a tail only when its walk ran up to the join; a
+        // path that already left (`.break()`, `.continue()`, a ref, an End, a
+        // Terminate) needs no ref — and gets none.
+        if (!atMerge && !endsPath(segs[segs.length - 1]))
+            segs.push(`.stepToRef(${tsLiteral(join)})`);
+        return armCb(`a${i}`, segs);
+    });
+    const seg = `.parallel(${tsLiteral(name)}, [\n${arms.map((a) => reindent(a, '  ')).join(',\n')},\n]${forkOptsArg(atMerge ? joinNode : undefined, fork)})`;
+    return { seg, next: atMerge ? continueOn(joinNode, 'output', ctx, refInto) : { cursor: join } };
+}
+/** Whether a chain segment ends its path, so nothing may follow it in the same list. */
+function endsPath(seg) {
+    return seg !== undefined && /^\.(stepToRef|break|continue|return|terminate)\(/.test(seg);
+}
+/**
+ * A name for a `.parallel(...)` that creates no merge node: `<source>Fork`,
+ * numbered when that is a node id, a declared input, variable or output, or a
+ * name already minted. No node carries it (the arms join on a plain step by
+ * ref), but it must still not collide with any of those: check reads a
+ * `$vars.<name>` of a parallel's name as a read of its merge, so a variable
+ * of that name would fail PARALLEL_HAS_NO_OUTPUT on recompile.
+ */
+function forkName(source, ctx) {
+    const base = `${source ?? 'parallel'}Fork`;
+    const globals = new Set(readFlowGlobals(ctx.flow.variables).map((g) => g.name ?? g.id));
+    const taken = (n) => ctx.graph.byId.has(n) || globals.has(n) || (ctx.forkNames?.has(n) ?? false);
+    let name = base;
+    for (let i = 2; taken(name); i++)
+        name = `${base}${i}`;
+    (ctx.forkNames ??= new Set()).add(name);
+    return name;
 }
 /** Re-indent every non-empty line of a (possibly multi-line) segment by `pad`. */
 function reindent(seg, pad) {
@@ -1707,21 +1793,50 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
             return segs;
         }
         if (node.type === T.merge) {
-            // A bare merge reached on the main path (its fork was not detected as a
-            // parallel). Skip it and continue from its output — best effort.
-            const next = continueOn(node, 'output', ctx, refInto);
-            if (next.brk || next.cont) {
-                segs.push(next.brk ? '.break()' : '.continue()');
+            // A merge node with several `output` edges is a FORK the designer drew
+            // (#1310): Studio Web's parallel split is a `core.logic.merge` with one
+            // incoming edge and one edge per arm, the arms rejoining at a second
+            // merge node (or at a plain step). `.parallel(join, arms, { fork })`
+            // recreates both nodes and every edge.
+            const outs = scopeSuccEdges(ctx.graph, node.id, scope).filter((e) => e.sourcePort === 'output');
+            const join = outs.length >= 2 ? ipdom.get(node.id) : undefined;
+            const joinNode = join !== undefined && join !== EXIT ? ctx.graph.byId.get(join) : undefined;
+            // As in `forkRegion`: a plain-step join may be the region's own `stop`.
+            if (join !== undefined && joinNode !== undefined && parallelJoinable(joinNode) && !(join === stop && joinNode.type === T.merge)) {
+                const targets = outs.map((e) => follow(ctx.graph, node.id, e.targetNodeId));
+                const fork = parallelSeg(join, joinNode, targets, scope, ipdom, ctx, refInto, node);
+                segs.push(fork.seg);
                 flagDropped(node, ctx, segs);
-                return segs;
+                if (fork.next.brk || fork.next.cont) {
+                    segs.push(fork.next.brk ? '.break()' : '.continue()');
+                    return segs;
+                }
+                cursor = fork.next.cursor;
+                continue;
+            }
+            // A merge node with one edge in and one out is a pass-through the
+            // designer left in place (a join whose arms were later removed). The
+            // layout names it, so it is kept: it falls through to the regular step
+            // path below and comes back as the raw node of its own definition
+            // (#1310). Skipping it dropped the node, and compile then refused the
+            // `.layout()` key. A bare merge with several edges in (a join whose fork
+            // was not detected) is still skipped — best effort.
+            const ins = ctx.graph.inEdges(node.id).filter((e) => scope.has(e.sourceNodeId));
+            if (outs.length !== 1 || ins.length !== 1) {
+                const next = continueOn(node, 'output', ctx, refInto);
+                if (next.brk || next.cont) {
+                    segs.push(next.brk ? '.break()' : '.continue()');
+                    flagDropped(node, ctx, segs);
+                    return segs;
+                }
+                cursor = next.cursor;
+                flagDropped(node, ctx, segs);
+                continue;
             }
-            cursor = next.cursor;
-            flagDropped(node, ctx, segs);
-            continue;
         }
         if (node.type === T.decision) {
             const r = ipdom.get(node.id) ?? stop;
-            const cond = emitBareExpr(String((node.inputs ?? {}).expression ?? ''), ctx.imp, ctx.inputNames);
+            const cond = emitBareExpr(conditionText((node.inputs ?? {}).expression), ctx.imp, ctx.inputNames);
             const thenSegs = forkRegion(portEdges(ctx.graph, node.id, 'true'), r, scope, ipdom, ctx, refInto);
             const elseSegs = forkRegion(portEdges(ctx.graph, node.id, 'false'), r, scope, ipdom, ctx, refInto);
             const labels = armLabels(node);
@@ -1804,7 +1919,14 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         }
         if (node.type === T.subflow) {
             segs.push(`.step(${tsLiteral(node.id)}, ${emitSubflow(node, ctx)}${optsArg(node, ctx)})`);
-            cursor = follow(ctx.graph, node.id, scopeSucc(ctx.graph, node.id, scope)[0]);
+            // A subflow step guards its body like any step: `core.subflow` declares
+            // the `error` handle, and `.onError()` after the step authors it. Without
+            // this the handler's edge had no spelling and a recompile dropped it.
+            const subflowSucc = scopeSucc(ctx.graph, node.id, scope);
+            const subflowHandler = errorHandlerSeg(node.id, subflowSucc, scope, ipdom, ctx);
+            if (subflowHandler)
+                segs.push(subflowHandler);
+            cursor = follow(ctx.graph, node.id, subflowSucc[0]);
             if (cursor === undefined)
                 accountImplicitTail(node, ctx, refInto);
             flagDropped(node, ctx, segs);
@@ -1920,11 +2042,13 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
             flagDropped(node, ctx, segs);
             continue;
         }
-        // Parallel: the fork's ipdom is the merge join; each successor is one arm.
+        // Parallel: the fork's ipdom is the join — the merge node of a `.parallel`,
+        // or a plain step several steps feed (#1310); each successor is one arm.
         const join = ipdom.get(node.id);
         const joinNode = join !== undefined ? ctx.graph.byId.get(join) : undefined;
-        if (join && join !== EXIT && joinNode?.type === T.merge) {
-            const fork = parallelSeg(join, joinNode, succ.map((t) => follow(ctx.graph, node.id, t)), scope, ipdom, ctx, refInto);
+        // A plain-step join may be the region's own `stop`: the arms end in refs to it and the walk ends there.
+        if (join && join !== EXIT && joinNode && parallelJoinable(joinNode)) {
+            const fork = parallelSeg(join, joinNode, succ.map((t) => follow(ctx.graph, node.id, t)), scope, ipdom, ctx, refInto, undefined, node.id);
             segs.push(fork.seg);
             flagDropped(node, ctx, segs);
             if (fork.next.brk || fork.next.cont) {
@@ -2164,7 +2288,7 @@ function emitSwitch(node, ipdom, scope, ctx, stop, refInto) {
     // First pass: is every case one shared `<disc> === <literal>`? If not, every
     // case is emitted as `when:` with its expression as written.
     const parsed = cases.map((c) => {
-        const p = parseSwitchCase(String(c.expression ?? ''));
+        const p = parseSwitchCase(conditionText(c.expression));
         if (p) {
             if (disc === undefined)
                 disc = p.lhs;
@@ -2186,13 +2310,13 @@ function emitSwitch(node, ipdom, scope, ctx, stop, refInto) {
         // edges leave from the ORIGINAL node's handles, which merge keeps (#1130).
         const idPart = typeof c.id === 'string' && c.id !== '' && c.id !== `case_${caseIndex}` ? `, id: ${tsLiteral(c.id)}` : '';
         const head = nonUniform || !p
-            ? `when: ${emitBareExpr(String(c.expression ?? ''), ctx.imp, ctx.inputNames)}`
+            ? `when: ${emitBareExpr(conditionText(c.expression), ctx.imp, ctx.inputNames)}`
             : `value: ${p.value}`;
         return `{ ${head}${labelPart}${idPart}, body: ${armCb('b', armSegs)} }`;
     });
     // A case with no condition has no `when:` that compiles: emitting `js\`\``
     // would fail at compile ([EXPR_SYNTAX]) with no warning here.
-    const empty = cases.filter((c) => String(c.expression ?? '').trim() === '');
+    const empty = cases.filter((c) => conditionText(c.expression) === '');
     if (empty.length > 0) {
         const listing = empty.map((c) => tsLiteral(c.label ?? c.id)).join(', ');
         const message = `switch ${tsLiteral(node.id)} has a case with no condition (${listing}). `
@@ -2365,7 +2489,10 @@ function layoutSeg(flow, nodes, edges) {
  */
 function emitSubflow(node, ctx) {
     const child = ctx.flow.subflows?.[node.id];
-    const inputsSrc = emitValMap(node.inputs, ctx.imp, ctx.inputNames) || '{}';
+    // `errorHandlingEnabled` is the flag serialize sets for `.onError()`, not a
+    // child input; `.onError(...)` after the step puts it back.
+    const { errorHandlingEnabled: _handled, ...inputs } = (node.inputs ?? {});
+    const inputsSrc = emitValMap(inputs, ctx.imp, ctx.inputNames) || '{}';
     if (!child) {
         if (ctx.o.bestEffort === false)
             throw new Error(`decompile: subflow "${node.id}" has no body in subflows[].`);
@@ -2381,7 +2508,52 @@ function emitSubflow(node, ctx) {
  * own scope; the child's trigger is its `<caller>Start` node, written as
  * `.trigger(manual(), { label })` only when its label is not `SUBFLOW_START_LABEL`.
  */
-function emitChildFlow(name, child, ctx) {
+function emitChildFlow(name, childFile, ctx) {
+    // Body: the child's trigger is its own manual Start; walk from its successor.
+    const trigger = (childFile.nodes ?? []).find((n) => isTrigger(n.type) && !(childFile.edges ?? []).some((e) => e.targetNodeId === n.id));
+    // The child's nodes read its inputs through that Start (`$vars.<caller>Start.
+    // output.<input>`); read it back as `start`, the one name both `input()` and
+    // check know a child's trigger by (#1313). Not when a child node is itself
+    // named `start`: the rename would then point the reads at that node.
+    const readAsStart = trigger !== undefined && trigger.id !== DEFAULT_TRIGGER_ID
+        && !(childFile.nodes ?? []).some((n) => n.id === DEFAULT_TRIGGER_ID);
+    const child = readAsStart ? readChildStartAsStart(childFile, trigger.id) : childFile;
+    const outerTriggerId = currentTriggerId;
+    currentTriggerId = readAsStart ? DEFAULT_TRIGGER_ID : (trigger?.id ?? DEFAULT_TRIGGER_ID);
+    try {
+        return emitChildFlowIn(name, child, trigger, ctx);
+    }
+    finally {
+        currentTriggerId = outerTriggerId;
+    }
+}
+/**
+ * A child flow's reads of its own Start node, `$vars.<caller>Start…`, read as
+ * `$vars.start…`. serialize names a child's trigger `<caller>Start` and renames
+ * `start` to it in the child scope, so `input('x')` — which lowers to
+ * `$vars.start.output.x` — reaches it; this is the inverse. Rewritten in code
+ * spans (`renameVarRoot`: `=js:` values, bare `$vars.` paths, the raw-JS
+ * fields) and in the BINDING slots that hold a variable path instead of an
+ * expression: a form row's `binding` (`vars.<caller>Start.output.x`), an agent
+ * input's `binding`, and an action app's `appInputBindings` (`=vars.…`). Only
+ * those: a literal string elsewhere that happens to read `vars.<caller>Start…`
+ * (a variable's default, a label) is data and stays as written.
+ */
+function readChildStartAsStart(child, startId) {
+    const renamed = renameVarRoot(child, startId, DEFAULT_TRIGGER_ID);
+    const path = new RegExp(`^(=?vars\\.)${startId.replace(/[$]/g, '\\$&')}(?![A-Za-z0-9_$])`);
+    const walk = (x, key, parentKey) => {
+        if (typeof x === 'string')
+            return key === 'binding' || parentKey === 'appInputBindings' ? x.replace(path, `$1${DEFAULT_TRIGGER_ID}`) : x;
+        if (Array.isArray(x))
+            return x.map((y) => walk(y, key, parentKey));
+        if (x && typeof x === 'object')
+            return Object.fromEntries(Object.entries(x).map(([k, y]) => [k, walk(y, k, key)]));
+        return x;
+    };
+    return walk(renamed);
+}
+function emitChildFlowIn(name, child, trigger, ctx) {
     const globals = readFlowGlobals(child.variables, runStrict);
     const childCtx = {
         graph: new Graph(child.nodes ?? [], child.edges ?? []),
@@ -2405,8 +2577,6 @@ function emitChildFlow(name, child, ctx) {
         const def = g.defaultValue !== undefined ? `, ${tsLiteral(g.defaultValue)}` : '';
         parts.push(`.var(${tsLiteral(g.name ?? g.id)}, ${declExpr(g, false, ctx.imp)}${def})`);
     }
-    // Body: the child's trigger is its own manual Start; walk from its successor.
-    const trigger = (child.nodes ?? []).find((n) => isTrigger(n.type) && !(child.edges ?? []).some((e) => e.targetNodeId === n.id));
     if (trigger?.type === T.triggerManual && hasRenamedLabel(trigger, SUBFLOW_START_LABEL)) {
         parts.push(`.trigger(${ctx.imp.use('manual')}(), { ${triggerOptParts(trigger, SUBFLOW_START_LABEL).join(', ')} })`);
     }

package/dist/flow-expr-check.js

@@ -29,6 +29,7 @@
  */
 import { Expr, cookedEscapesOf } from './core/expr.js';
 import { checkExpression, cookedEscapeDiagnostics } from './core/expr-check.js';
+import { stepDeclaredVariables } from './flow-step-variables.js';
 const NOUN = 'input, variable, or step';
 /**
  * Every `$vars` root a reference may legitimately resolve to, across the WHOLE
@@ -77,6 +78,10 @@ function addStepNames(steps, roots) {
         // they are edges, not nodes, so there is nothing to reference them by.
         if (s.kind !== 'return' && s.kind !== 'stepToRef' && s.kind !== 'stepToList' && s.kind !== 'break' && s.kind !== 'continue')
             roots.add(s.name);
+        // A step declares the variables its fields land in too (`check.ts` mirrors this, #1309).
+        if (s.kind === 'action' || s.kind === 'stepSwitch')
+            for (const v of stepDeclaredVariables(s.spec, s.options?.version))
+                roots.add(v);
         switch (s.kind) {
             case 'stepToList':
                 addStepNames(s.body, roots);

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

@@ -441,6 +441,15 @@ export interface FlowNodeType<Spec> extends NodeType<Spec, FlowNodeContribution,
      * one of these (`.onError()` routes it).
      */
     exits?(spec: Spec, pinnedVersion?: string): DeclaredExit[] | NoExits;
+    /**
+     * The flow variables a step of this type DECLARES by running: names a later
+     * `$vars.<name>` read resolves to that are neither a `.var()` nor a step
+     * name. A quick form's asked field lands its answer in its `variable`
+     * (`vars.<Step>_<field>`, as the designer names it), so the task declares
+     * that variable. `check` adds them to its declared set (#1309). Omitted: the
+     * type declares none.
+     */
+    declares?(spec: Spec, pinnedVersion?: string): string[];
     /**
      * Whether `port` is a forward handle the PRODUCT derives for this spec, which
      * the definition does not list — a human task's `outcome-<id>` handles, drawn