@uipath/maestro-builder-sdk 6.15.3 → 6.15.5

package/dist/check.js

@@ -12,11 +12,11 @@ import { checkEventResolution, checkEventSubscription, eventParamsFor, } from '.
 import { FLOW_EXPR_DIALECT, checkBindingLabels, checkBindingPresence, checkConnectorContract as coreCheckConnectorContract, checkConnectorLookups as coreCheckConnectorLookups, checkConnectorSchema as coreCheckConnectorSchema, collectConnectionUses, connectionConnectorConflicts, } from './core/connector-checks.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { isAnswerField } from './core/hitl-answers.js';
-import { globalNameCollisionMessage, globalNameCollisions } from './core/global-names.js';
 import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
 import { childStepLists, declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
+import { planFlowGlobals } from './flow-variables.js';
 export function check(built, opts = {}) {
     let diags = [];
     const uses = collectConnectionUses(() => { diags = checkFlow(built, [], opts); });
@@ -36,12 +36,8 @@ function checkFlow(built, ancestors, opts = {}) {
     if (!built.id)
         diags.push({ level: 'error', code: 'NO_ID', message: 'flow() requires an id.' });
     checkSchemaVersion(built, ancestors, diags);
+    checkGlobalNames(built, diags);
     checkNodeUpdates(built, diags);
-    // Inputs, outputs and vars are one namespace in the .flow (variables.globals[]);
-    // `serialize` throws the same sentence (flow-builder-sdk#890).
-    for (const collision of globalNameCollisions(built.inputs ?? [], built.outputs ?? [], built.vars ?? [])) {
-        diags.push({ level: 'error', code: 'VARIABLE_NAME_COLLISION', message: globalNameCollisionMessage(collision) });
-    }
     const maybeCustomTrigger = built.trigger;
     if (maybeCustomTrigger !== undefined && !('kind' in maybeCustomTrigger) && maybeCustomTrigger instanceof FlowNode) {
         // A custom FlowTrigger subclass reports through its own diagnostics() hook;
@@ -945,7 +941,12 @@ function checkFlow(built, ancestors, opts = {}) {
         }
     }
     // Check $vars.<name>[.<field>] references resolve to a declared name or step.
+    const inputNames = new Set(built.inputs.map((x) => x.name));
     for (const { js, step, errorSource } of exprs) {
+        // Comments and string-literal text blanked out, offsets preserved: the
+        // input-read rule below fires on a VALID name, so it has to tell a read
+        // from a mention, the same way `uip maestro flow validate` does.
+        const code = codeOnly(js);
         // `rest` is the remaining dotted tail after `<name>.<field>` — needed for a
         // subflow read, where the value lives one level deeper
         // (`$vars.<call>.output.<childOutput>`). Every other rule reads only the
@@ -963,6 +964,36 @@ function checkFlow(built, ancestors, opts = {}) {
                 });
                 continue;
             }
+            // `$vars.<input>` — a flow INPUT read by its bare name.
+            //
+            // Inputs, outputs and vars share one namespace in `variables.globals[]`,
+            // but they are not read the same way. A var or output is read as
+            // `$vars.<name>`. An input is not: serialize gives EVERY input global a
+            // `triggerNodeId` (the root trigger, an entry point, or a subflow child's
+            // own Start), and the runtime surfaces such an input only under that
+            // trigger's output — `$vars.<trigger>.output.<name>`, which is exactly what
+            // `input('<name>')` lowers to. The bare read resolves only by accident (a
+            // manual trigger also emits a process-level input of the same name) and is
+            // null under any other trigger. `uip maestro flow validate` refuses it
+            // (UV-16316, UiPath/cli#4236); this rule used to treat every declared name
+            // as readable bare, so check and compile passed what validate refused
+            // (five shipped examples, found with flow-builder-sdk#904).
+            //
+            // A step with the same name wins, as it does in validate, and so does a
+            // mention in a comment or a string literal (template `${…}` is code).
+            if (inputNames.has(name) && !stepNames.has(name) && code.startsWith('$vars', m.index ?? 0)) {
+                diags.push({
+                    level: 'error',
+                    code: 'INPUT_READ_WITHOUT_TRIGGER',
+                    message: `"$vars.${name}" in "${step}" reads flow input "${name}" by its bare name. A flow input is `
+                        + `published under the trigger's output, so the runtime value is "$vars.${triggerId}.output.${name}" `
+                        + `— the bare read is null under any trigger but a manual one, and \`uip maestro flow validate\` `
+                        + `refuses it. In an expression, write input('${name}'); \`v()\` is for a .var() or an output.`,
+                    step,
+                    suggestion: `$vars.${triggerId}.output.${name}`,
+                });
+                continue;
+            }
             // A BARE `$vars.<step>` — the step itself, not its output.
             //
             // **The mechanism is now MEASURED, not inferred.** This comment used to say
@@ -1612,6 +1643,20 @@ const INTERVAL_WORDS = [
  * Without a library (`uip maestro flow check` run with no `--library`) the fields
  * are unknown, so the warning keeps the generic wording.
  */
+/**
+ * Every declared name must become exactly one global, because `flow validate`
+ * rejects a repeated id (`[variables.globals] Duplicate variable ID`;
+ * VARIABLE_NAME_COLLISION, flow-builder-sdk#890). The planning — including the one collision that is NOT an error, a same-named
+ * `.output()` + `.var()`, which merges into one `out` global carrying the var's
+ * default — lives in `planFlowGlobals`, shared with the serializer, so `check`
+ * and the emitted file cannot disagree about it (flow-builder-sdk#899: `check`
+ * said `Errors: 0`, validate refused the file).
+ */
+function checkGlobalNames(built, diags) {
+    for (const p of planFlowGlobals({ inputs: built.inputs ?? [], outputs: built.outputs ?? [], vars: built.vars ?? [] }).problems) {
+        diags.push({ level: 'error', code: p.code, message: p.message, ...(p.suggestion ? { suggestion: p.suggestion } : {}) });
+    }
+}
 /**
  * `{ updates }` writes a declared flow variable when the node completes. The
  * assignable targets are `.var()` variables and flow outputs — assigning to an
@@ -1761,6 +1806,97 @@ function declaredRefName(js, triggerId) {
     const viaTrigger = new RegExp(`^\\$vars\\.${triggerId}\\.output\\.([A-Za-z0-9_]+)$`).exec(js.trim());
     return viaTrigger?.[1];
 }
+/**
+ * The JavaScript text with `//` and `/* *\/` comments and the text of string and
+ * template literals replaced by spaces — same length, so a match offset in the
+ * original indexes the same character here. A template's `${…}` bodies are code
+ * and are kept (nested templates and strings inside them are blanked in turn).
+ *
+ * This is the read-versus-mention line `uip maestro flow validate` draws in its
+ * `$vars` extraction (`collectVarsRefs`, `inProse`): a rule that fires on a VALID
+ * name must not fire on `"pass $vars.x here"` or a commented-out line. Regex
+ * literals are not recognised; a `$vars` reference inside one is vanishingly rare.
+ */
+function codeOnly(src) {
+    const out = src.split('');
+    const n = src.length;
+    let i = 0;
+    const blank = (from, to) => {
+        for (let k = from; k < to && k < n; k++)
+            if (out[k] !== '\n')
+                out[k] = ' ';
+    };
+    /** Scan code from `i`; with `stopAtBrace`, return at the `}` closing a `${`. */
+    const code = (stopAtBrace) => {
+        let depth = 0;
+        while (i < n) {
+            const c = src[i];
+            if (c === '/' && src[i + 1] === '/') {
+                const end = src.indexOf('\n', i);
+                const stop = end === -1 ? n : end;
+                blank(i, stop);
+                i = stop;
+                continue;
+            }
+            if (c === '/' && src[i + 1] === '*') {
+                const end = src.indexOf('*/', i + 2);
+                const stop = end === -1 ? n : end + 2;
+                blank(i, stop);
+                i = stop;
+                continue;
+            }
+            if (c === '"' || c === "'") {
+                const start = i++;
+                while (i < n && src[i] !== c && src[i] !== '\n')
+                    i += src[i] === '\\' ? 2 : 1;
+                blank(start + 1, i);
+                i++;
+                continue;
+            }
+            if (c === '`') {
+                template();
+                continue;
+            }
+            if (stopAtBrace) {
+                if (c === '{')
+                    depth++;
+                else if (c === '}') {
+                    if (depth === 0)
+                        return;
+                    depth--;
+                }
+            }
+            i++;
+        }
+    };
+    const template = () => {
+        let start = ++i;
+        while (i < n) {
+            const c = src[i];
+            if (c === '\\') {
+                i += 2;
+                continue;
+            }
+            if (c === '`') {
+                blank(start, i);
+                i++;
+                return;
+            }
+            if (c === '$' && src[i + 1] === '{') {
+                blank(start, i);
+                i += 2;
+                code(true);
+                i++; // the `}` closing this `${`
+                start = i;
+                continue;
+            }
+            i++;
+        }
+        blank(start, n);
+    };
+    code(false);
+    return out.join('');
+}
 const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * The four published-resource factories once each named the release key
@@ -3940,19 +4076,46 @@ function checkHttp(step, inputs, diags) {
     // Moving to the managed node is not a rename. A plain step keeps a non-2xx on
     // the SUCCESS path (`out(step,'statusCode')`); the managed one fails on it, so
     // a status branch becomes an error handler reading the envelope's `status`.
-    // That rewrite is the author's call, so the warning states the trade rather
-    // than pretending it is mechanical.
+    //
+    // It is not a free upgrade either, and for a connection-less URL it is usually
+    // the wrong move (flow-builder-sdk#898). With no `connection` the managed node
+    // still goes through Integration Service: serialize emits the `uipath-uipath-http`
+    // connector on `ImplicitConnection`, so the request leaves from IS's SHARED
+    // egress. Measured on slack-weather-pipeline (3/3 runs): agents took the old
+    // `managed: true` hint, and Open-Meteo answered that egress 429 "Daily API
+    // request limit exceeded" while direct calls from the same box got 200. The
+    // plain node goes direct. So the hint only steers toward `managed: true` when
+    // the step was given connection settings; the two other real reasons to move
+    // (a binding, an `.onError()`) already fire as errors with that suggestion
+    // (HTTP_BINDING_REQUIRES_MANAGED, HTTP_ONERROR_V1).
     if (inputs && !inputs.managed) {
-        diags.push({
-            level: 'warning',
-            code: 'HTTP_V1_RETIRED',
-            message: `Step "${step}" emits core.action.http, which the tenant registry no longer serves (only `
-                + `core.action.http.v2). It still runs today. Moving to managed: true changes behaviour rather than just `
-                + `the node type: a non-2xx stops arriving on the success path with statusCode and fails the step instead, `
-                + `so a status branch becomes an .onError() handler reading err('${step}', 'status').`,
-            step,
-            suggestion: `http({ url: …, managed: true })`,
-        });
+        const asked = inputs;
+        const wantsConnection = asked.connection !== undefined || asked.folder !== undefined
+            || asked.targetConnector !== undefined;
+        diags.push(wantsConnection
+            ? {
+                level: 'warning',
+                code: 'HTTP_V1_RETIRED',
+                message: `Step "${step}" emits core.action.http, which the tenant registry no longer serves (only `
+                    + `core.action.http.v2). It sets Integration Service connection settings, which only the managed node `
+                    + `can use. Moving to managed: true changes behaviour rather than just the node type: a non-2xx stops `
+                    + `arriving on the success path with statusCode and fails the step instead, so a status branch becomes `
+                    + `an .onError() handler reading err('${step}', 'status').`,
+                step,
+                suggestion: `http({ url: …, managed: true, connection, folder })`,
+            }
+            : {
+                level: 'warning',
+                code: 'HTTP_V1_RETIRED',
+                message: `Step "${step}" emits core.action.http, which the tenant registry no longer serves (only `
+                    + `core.action.http.v2). It still compiles, validates and runs, and it calls the URL directly. For a URL `
+                    + `that needs no Integration Service connection, keep managed: false. managed: true is not a drop-in `
+                    + `replacement: even without a connection it sends the request through Integration Service's shared `
+                    + `egress (rate limits there are shared, and public APIs can answer 429 where a direct call succeeds), `
+                    + `and a non-2xx fails the step instead of arriving with statusCode. Switch only if the call needs an `
+                    + `Integration Service connection or an .onError() handler.`,
+                step,
+            });
     }
     const connection = inputs?.connection;
     const folder = inputs?.folder;

package/dist/cli-result.d.ts

@@ -10,6 +10,20 @@
  * @param fields - JSON-serializable values, e.g. `{ path, nodes, edges }`.
  */
 export declare function reportResult(fields: Record<string, unknown>): void;
+/**
+ * Print text that IS the verb's result (a pretty-printed object, a captured
+ * path), as opposed to a status line such as `compile: wrote X`.
+ *
+ * Under `--json` this prints nothing: the result is already the JSON object on
+ * stdout, and the umbrella routes a tool's stdout to stderr meanwhile, so a
+ * plain `console.log` of the result would land on stderr as a second copy.
+ * A caller that merges the streams (`2>&1`, an agent's shell tool) then gets
+ * two documents and `json.load` fails with `Extra data` (#901). Status lines
+ * keep using `console.log`; they are what stderr is for under `--json`.
+ *
+ * @param text - the result as text; a trailing newline is added.
+ */
+export declare function printResult(text: string): void;
 /**
  * Report a check's diagnostics as `{ errors, warnings, diagnostics }`, the one
  * shape every family's check (and compile's check pass) uses.

package/dist/cli-result.js

@@ -18,6 +18,24 @@ function slot() {
 export function reportResult(fields) {
     Object.assign(slot().fields, fields);
 }
+/**
+ * Print text that IS the verb's result (a pretty-printed object, a captured
+ * path), as opposed to a status line such as `compile: wrote X`.
+ *
+ * Under `--json` this prints nothing: the result is already the JSON object on
+ * stdout, and the umbrella routes a tool's stdout to stderr meanwhile, so a
+ * plain `console.log` of the result would land on stderr as a second copy.
+ * A caller that merges the streams (`2>&1`, an agent's shell tool) then gets
+ * two documents and `json.load` fails with `Extra data` (#901). Status lines
+ * keep using `console.log`; they are what stderr is for under `--json`.
+ *
+ * @param text - the result as text; a trailing newline is added.
+ */
+export function printResult(text) {
+    if (slot().json)
+        return;
+    process.stdout.write(`${text}\n`);
+}
 /**
  * Report a check's diagnostics as `{ errors, warnings, diagnostics }`, the one
  * shape every family's check (and compile's check pass) uses.

package/dist/core/expr.d.ts

@@ -27,9 +27,15 @@ export declare class Expr {
  */
 export declare function lit(value: unknown): Expr;
 /**
- * Reference a flow-level variable or input by name → `$vars.<name>`.
+ * Reference a flow variable or output by name → `$vars.<name>`.
  *
- * @param name - The variable or input as declared with `.var(...)` / `.input(...)`.
+ * @remarks
+ * Not for a flow INPUT: an input is published under the trigger's output, so read
+ * it with {@link input} (`$vars.start.output.<name>`). A bare `$vars.<input>` is
+ * null under any trigger but a manual one, and `check` and `uip maestro flow
+ * validate` both refuse it.
+ *
+ * @param name - The variable or output as declared with `.var(...)` / `.output(...)`.
  * @returns An {@link Expr} reading that variable at run time.
  */
 export declare function v(name: string): Expr;

package/dist/core/expr.js

@@ -33,9 +33,15 @@ export function lit(value) {
     return new Expr(JSON.stringify(value), true, value);
 }
 /**
- * Reference a flow-level variable or input by name → `$vars.<name>`.
+ * Reference a flow variable or output by name → `$vars.<name>`.
  *
- * @param name - The variable or input as declared with `.var(...)` / `.input(...)`.
+ * @remarks
+ * Not for a flow INPUT: an input is published under the trigger's output, so read
+ * it with {@link input} (`$vars.start.output.<name>`). A bare `$vars.<input>` is
+ * null under any trigger but a manual one, and `check` and `uip maestro flow
+ * validate` both refuse it.
+ *
+ * @param name - The variable or output as declared with `.var(...)` / `.output(...)`.
  * @returns An {@link Expr} reading that variable at run time.
  */
 export function v(name) {

package/dist/core/global-names.d.ts

@@ -13,13 +13,11 @@
  * `Duplicate variable ID: "x" (appears 2 times)`). Before flow-builder-sdk#890,
  * `check` and `compile` were silent and wrote both rows.
  *
- * The common shape is `.output({ summary }) + .var('summary')` — "the output
- * the arms assign". The remedy keeps the output and renames the var:
- * `.var('draftSummary')` + `.return({ summary: v('draftSummary') })`. The output
- * then stays a declared `out` global — the direction the Flow docs and the eval
- * checkers (`direction == "out"`) treat as the flow's output contract. Dropping the name from `.output()` also
- * validates — a `.var()` is an `inout` global, which the product counts as an
- * output too — but the flow then has no declared `out` for it.
+ * One pair is NOT a collision: `.output({ x }) + .var('x')` with the same type is
+ * the loop-accumulator shape ("declare the result, then seed it"), and
+ * `planFlowGlobals` (`flow-variables.ts`) merges it into ONE `out` global that
+ * carries the var's default (flow-builder-sdk#899). Every other repeat of a name
+ * is reported with the sentence below.
  */
 export type GlobalKind = 'input' | 'output' | 'var';
 export interface GlobalNameCollision {

package/dist/core/global-names.js

@@ -13,13 +13,11 @@
  * `Duplicate variable ID: "x" (appears 2 times)`). Before flow-builder-sdk#890,
  * `check` and `compile` were silent and wrote both rows.
  *
- * The common shape is `.output({ summary }) + .var('summary')` — "the output
- * the arms assign". The remedy keeps the output and renames the var:
- * `.var('draftSummary')` + `.return({ summary: v('draftSummary') })`. The output
- * then stays a declared `out` global — the direction the Flow docs and the eval
- * checkers (`direction == "out"`) treat as the flow's output contract. Dropping the name from `.output()` also
- * validates — a `.var()` is an `inout` global, which the product counts as an
- * output too — but the flow then has no declared `out` for it.
+ * One pair is NOT a collision: `.output({ x }) + .var('x')` with the same type is
+ * the loop-accumulator shape ("declare the result, then seed it"), and
+ * `planFlowGlobals` (`flow-variables.ts`) merges it into ONE `out` global that
+ * carries the var's default (flow-builder-sdk#899). Every other repeat of a name
+ * is reported with the sentence below.
  */
 /** The names declared more than once across `.input()`, `.output()` and `.var()`. */
 export function globalNameCollisions(inputs, outputs, vars) {
@@ -49,12 +47,5 @@ export function globalNameCollisionMessage({ name, kinds }) {
     const head = `"${name}" is declared ${kinds.length} times (${declared}). The .flow keeps inputs, outputs and `
         + `variables in one list, variables.globals[], so this compiles to ${kinds.length} globals with the id "${name}" `
         + `and \`uip maestro flow validate\` refuses it: Duplicate variable ID: "${name}".`;
-    const distinct = new Set(kinds);
-    if (distinct.size === 2 && distinct.has('output') && distinct.has('var')) {
-        return `${head} Keep the output and give the variable its own name: `
-            + `.var('${name}Value', …) with { updates: { ${name}Value: … } }, then .return({ ${name}: v('${name}Value') }). `
-            + `(Dropping "${name}" from .output() also validates — a .var() compiles to an \`inout\` global, which the `
-            + `product counts as an output — but then the flow declares no \`out\` variable for it.)`;
-    }
     return `${head} Rename one of them.`;
 }

package/dist/decompile.js

@@ -1762,7 +1762,7 @@ function emitVariables(e, depth, flow, imp) {
     if (inputs.length)
         e.line(depth, `.input(${shape(inputs, true)})`);
     if (outputs.length)
-        e.line(depth, `.output(${shape(outputs, false)})`);
+        e.line(depth, `.output(${shape(outputs, true)})`);
     for (const g of inouts) {
         const rich = declExpr(g, false, imp);
         const def = g.defaultValue !== undefined ? `, ${literal(g.defaultValue)}` : '';
@@ -2538,7 +2538,7 @@ function emitChildFlow(name, child, ctx) {
     };
     const parts = [`${ctx.imp.use('flow')}(${str(name)})`];
     // Variables.
-    const shape = (dir) => `{ ${globals.filter((g) => g.direction === dir).map((g) => `${key(g.name ?? g.id)}: ${declExpr(g, dir === 'in', ctx.imp)}`).join(', ')} }`;
+    const shape = (dir) => `{ ${globals.filter((g) => g.direction === dir).map((g) => `${key(g.name ?? g.id)}: ${declExpr(g, dir !== 'inout', ctx.imp)}`).join(', ')} }`;
     if (globals.some((g) => g.direction === 'in'))
         parts.push(`.input(${shape('in')})`);
     if (globals.some((g) => g.direction === 'out'))

package/dist/flow-sdk.d.ts

@@ -71,7 +71,11 @@ export interface VarSpec {
     subType?: string;
     /** JSON schema for complex type validation (object/array shapes). */
     schema?: Record<string, unknown>;
-    /** Default value — inputs and vars only; the format forbids it on outputs. */
+    /**
+     * Default value — the variable's value before anything assigns it. On an
+     * output it is the starting value a `{ updates }` accumulator reads, e.g.
+     * `.output({ product: { type: types.number, default: 1 } })`.
+     */
     default?: unknown;
 }
 /**
@@ -377,7 +381,7 @@ export interface ReturnOptions extends NodeOptions {
      * `done` become `done` and `done2`.
      *
      * ```ts
-     * .branch('checkTemperature', js`$vars.tempF > 60`,
+     * .branch('checkTemperature', js`${input('tempF')} > 60`,
      *   (t) => t.return({}, { name: 'endNiceDay', label: 'Nice Day' }),
      *   (e) => e.return({}, { name: 'endBringJacket', label: 'Bring a Jacket' }))
      * ```
@@ -741,7 +745,7 @@ declare class StepList {
      * ```ts
      * export default flow('draft-review')
      *   .output({ summary: types.string })
-     *   // Not `.var('summary')`: an output and a var share one namespace (VARIABLE_NAME_COLLISION).
+     *   // A working variable the arms assign; the return maps it onto the output.
      *   .var('result', types.string)
      *   .stepSwitch('review', hitl({ fields: [], outcomes: ['Publish', 'Revise'] }), [
      *     { value: 'Publish', body: (b) => b.step('publish', script({ code: 'return "published";', returns: 'string' }), { updates: { result: out('publish') } }) },
@@ -1323,6 +1327,25 @@ declare class FlowBuilder extends StepList {
     /**
      * Declare the flow's outputs — what `.return(...)` binds values to.
      *
+     * @remarks
+     * An output is also a flow variable: `v('<name>')` reads it and a step's
+     * `{ updates }` assigns it, so an accumulator needs no separate `.var()`. Give
+     * it a starting value with the rich spelling, `{ type, default }`. A `.var()`
+     * of the same name and type is merged into the output rather than emitted as a
+     * second variable (its default becomes the output's); a different type is a
+     * `check` error, `OUTPUT_VAR_MISMATCH`.
+     *
+     * @example
+     * **A loop accumulator**
+     * ```ts
+     * flow('multiply')
+     *   .output({ product: { type: types.number, default: 1 } })
+     *   .loop('each', lit([2, 3, 4]), (b) => b
+     *     .step('mul', script({ code: 'return $vars.product * $vars.each.currentItem;', returns: 'number' }),
+     *       { updates: { product: out('mul') } }))
+     *   .return({ product: v('product') })
+     * ```
+     *
      * @param shape - Output names to type descriptors, e.g. `{ total: types.number }`.
      * @returns This builder, so calls chain.
      */
@@ -1384,7 +1407,7 @@ export declare function flow(id: string): FlowBuilder;
  * const reverse = flow('reverse-text')
  *   .input({ text: types.string })
  *   .output({ reversed: types.string })
- *   .step('rev', script({ code: 'return $vars.text.split("").reverse().join("");' }))
+ *   .step('rev', script({ code: 'return $vars.start.output.text.split("").reverse().join("");' }))
  *   .return({ reversed: out('rev') });
  *
  * export default flow('reverse-outer')

package/dist/flow-sdk.js

@@ -63,16 +63,14 @@ function assertShape(method, shape) {
 }
 /**
  * Normalize a `TypeDesc | VarSpec` declaration value into VarDecl fields.
- * Outputs reject `default` — the format only persists defaults on `in`/`inout`.
+ * Every direction takes a `default`: the format's `workflowVariableSchema` allows
+ * `defaultValue` on `in`, `out` and `inout` alike, and the v1 CLI's
+ * `variable add --direction out --default-value` writes one on an output.
  */
 function varDeclOf(method, name, value) {
     if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
         const spec = value;
         assertType(method, name, spec.type);
-        if (method === 'output' && spec.default !== undefined) {
-            throw new TypeError(`.output() declared ${JSON.stringify(name)} with a default, but the .flow format only persists `
-                + `defaults on inputs and vars. Bind the value with .return() instead.`);
-        }
         return {
             type: spec.type,
             ...(spec.default !== undefined ? { default: spec.default } : {}),
@@ -332,7 +330,7 @@ class StepList {
      * ```ts
      * export default flow('draft-review')
      *   .output({ summary: types.string })
-     *   // Not `.var('summary')`: an output and a var share one namespace (VARIABLE_NAME_COLLISION).
+     *   // A working variable the arms assign; the return maps it onto the output.
      *   .var('result', types.string)
      *   .stepSwitch('review', hitl({ fields: [], outcomes: ['Publish', 'Revise'] }), [
      *     { value: 'Publish', body: (b) => b.step('publish', script({ code: 'return "published";', returns: 'string' }), { updates: { result: out('publish') } }) },
@@ -1096,6 +1094,25 @@ class FlowBuilder extends StepList {
     /**
      * Declare the flow's outputs — what `.return(...)` binds values to.
      *
+     * @remarks
+     * An output is also a flow variable: `v('<name>')` reads it and a step's
+     * `{ updates }` assigns it, so an accumulator needs no separate `.var()`. Give
+     * it a starting value with the rich spelling, `{ type, default }`. A `.var()`
+     * of the same name and type is merged into the output rather than emitted as a
+     * second variable (its default becomes the output's); a different type is a
+     * `check` error, `OUTPUT_VAR_MISMATCH`.
+     *
+     * @example
+     * **A loop accumulator**
+     * ```ts
+     * flow('multiply')
+     *   .output({ product: { type: types.number, default: 1 } })
+     *   .loop('each', lit([2, 3, 4]), (b) => b
+     *     .step('mul', script({ code: 'return $vars.product * $vars.each.currentItem;', returns: 'number' }),
+     *       { updates: { product: out('mul') } }))
+     *   .return({ product: v('product') })
+     * ```
+     *
      * @param shape - Output names to type descriptors, e.g. `{ total: types.number }`.
      * @returns This builder, so calls chain.
      */
@@ -1196,7 +1213,7 @@ export function flow(id) {
  * const reverse = flow('reverse-text')
  *   .input({ text: types.string })
  *   .output({ reversed: types.string })
- *   .step('rev', script({ code: 'return $vars.text.split("").reverse().join("");' }))
+ *   .step('rev', script({ code: 'return $vars.start.output.text.split("").reverse().join("");' }))
  *   .return({ reversed: out('rev') });
  *
  * export default flow('reverse-outer')

package/dist/flow-variables.d.ts

@@ -11,3 +11,69 @@ export interface FlowGlobalDeclaration {
 }
 /** Read both supported Flow variable spellings into one declaration table. */
 export declare function readFlowGlobals(variables: unknown, strict?: boolean): FlowGlobalDeclaration[];
+/** The declaration fields `planFlowGlobals` reads (structurally a `VarDecl`). */
+export interface DeclaredVariable {
+    name: string;
+    type: string;
+    default?: unknown;
+    description?: string;
+    subType?: string;
+    schema?: Record<string, unknown>;
+}
+/** One reason the declared names cannot become one global each. */
+export interface FlowGlobalsProblem {
+    code: 'VARIABLE_NAME_COLLISION' | 'OUTPUT_VAR_MISMATCH';
+    name: string;
+    message: string;
+    suggestion?: string;
+}
+/** What `variables.globals` will hold, before directions and trigger ids are stamped. */
+export interface FlowGlobalsPlan<D extends DeclaredVariable = DeclaredVariable> {
+    /** Every `.output()`, in order. One with a same-named `.var()` carries that var's default. */
+    outputs: D[];
+    /** The `.var()` declarations NOT folded into an output, in order. */
+    vars: D[];
+    /** Names declared by both `.output()` and `.var()` and merged into one `out` global. */
+    merged: string[];
+    /** Collisions that would emit two globals with one id. Empty when the plan is emittable. */
+    problems: FlowGlobalsProblem[];
+}
+/**
+ * Turn a flow's `.input()` / `.output()` / `.var()` declarations into the
+ * globals the `.flow` file will carry — one per id, because the product's
+ * `flow validate` rejects a repeated id (`[variables.globals] Duplicate variable
+ * ID`), and the three methods share that one namespace.
+ *
+ * **An output and a var with the same name are one variable** (flow-builder-sdk#899).
+ * The natural loop accumulator is
+ * `.output({ product: types.number }).var('product', types.number, 1)`: declare
+ * the result, then seed it. Both declarations describe the same value, so they
+ * merge into ONE `direction: 'out'` global that carries the var's default.
+ *
+ * Why `out` and not `inout`, measured against `@uipath/flow-converter` 0.69 and
+ * `@uipath/maestro-sdk` (the code that turns a `.flow` into what runs):
+ * - only an `out` global is a flow OUTPUT at the root — `buildNodeOutputMappings`
+ *   drops an End node's mapping for any id that is not `direction: 'out'`;
+ * - `inout` is published as an INPUT too — solution discovery puts it on the
+ *   entry point's input schema — so `inout` would widen the caller's contract;
+ * - `{ updates }` on an `out` global is the same output mapping (`var: <id>`) as
+ *   on an `inout` one, so a loop body can read and rewrite it mid-run;
+ * - the `default` on `<uipath:output>` is serialized (`collectVariablesFromNodes`)
+ *   and a subflow seeds its `out` globals from `defaultValue ?? null`
+ *   (`buildSeedTask`). The v1 CLI's `variable add --direction out
+ *   --default-value` writes the same shape.
+ *
+ * Metadata: the output's `description` / `subType` / `schema` win, falling back
+ * to the var's; the default is whichever side declared one. A disagreement the
+ * merge would have to resolve by picking a side — a different `type`, two
+ * different defaults, two different `subType`s or `schema`s — is
+ * `OUTPUT_VAR_MISMATCH` instead, because silently choosing one changes what the
+ * flow computes. Every other repeated name (two vars, two outputs, an input
+ * reused as an output or var) stays `VARIABLE_NAME_COLLISION`
+ * (`core/global-names.ts`, flow-builder-sdk#890).
+ */
+export declare function planFlowGlobals<D extends DeclaredVariable>(decl: {
+    inputs: readonly D[];
+    outputs: readonly D[];
+    vars: readonly D[];
+}): FlowGlobalsPlan<D>;