@uipath/maestro-builder-sdk 6.15.4 → 6.15.6

package/dist/bpmn/data-service.js

@@ -43,9 +43,18 @@ export function dataServiceWire(entity, operation) {
                     ...optionalRow('queryExpression', 'query', operation.where),
                     scalarRow('start', 'query', operation.start ?? 0),
                     scalarRow('limit', 'query', operation.limit ?? 100),
-                    ...optionalRow('sortBy', 'query', operation.sortBy),
                     ...optionalRow('isAscending', 'query', operation.ascending),
                     ...optionalRow('expansionLevel', 'query', operation.expansionLevel),
+                    // The sort FIELD rides in the body as `_sortFieldName` — the name the curated
+                    // operation's `RequestFields` declare (`uip is resources describe
+                    // uipath-uipath-dataservice QueryEntityRecordsCurated --operation Create`), and
+                    // the only place the connector reads it: as a query parameter it is ignored and
+                    // the query comes back in default order. This used to write `sortBy` as a query
+                    // row; on flow-v2-run-12 the Query node so built validated and failed
+                    // `no Query node sorted by priority DESC` (datafabric-e2e-contract-intake-pipeline
+                    // 1.00 → 0.45) while the v1 arm wrote `{"_sortFieldName":"priority"}` by hand.
+                    // `isAscending` stays a query parameter, which is where the connector reads it.
+                    ...(operation.sortBy !== undefined ? [bodyRow({ _sortFieldName: operation.sortBy })] : []),
                 ],
             };
         case 'delete':

package/dist/bpmn/decompile.js

@@ -56,6 +56,7 @@ import BpmnModdle from 'bpmn-moddle';
 import { createRequire } from 'node:module';
 import { registryType, rowDeclaration } from './typed-node.js';
 import { errorSchema, errorSchemaWithResponse } from './bpmn-sdk.js';
+import { SCRIPT_ARGS_ENVELOPE, defaultScriptInputSchema } from './serialize.js';
 import { BPMN_SCHEMA_VERSIONS } from './format-profile.js';
 import { preserveSchemaVersion } from '../schema-version.js';
 const require = createRequire(import.meta.url);
@@ -654,7 +655,17 @@ function scriptVersionOf(el) {
 /** A `uipath:mapping` script task. */
 function emitScriptTask(chain, el, payload, type) {
     const args = (payload?.input ?? []).find((r) => r.name === 'args');
-    const inputs = args ? safeJson(args.body) : undefined;
+    // The serializer writes the product's envelope — `vars`/`metadata`, and the default
+    // inputSchema declaring them — on every script task, so the source need not repeat
+    // them: an `args` that is exactly the envelope decompiles to no `inputs` at all, and
+    // only what the designer added (`"iterator[0]":"=iterator[0]"`) comes through. A
+    // schema that differs from the default (the designer's carries `$schema`) is kept.
+    const rawInputs = args ? safeJson(args.body) : undefined;
+    const inputs = rawInputs
+        ? Object.fromEntries(Object.entries(rawInputs).filter(([k, v]) => !(k in SCRIPT_ARGS_ENVELOPE) || v !== SCRIPT_ARGS_ENVELOPE[k]))
+        : undefined;
+    const schemaBody = payload?.context?.inputSchema?.body;
+    const schemaIsDefault = schemaBody !== undefined && rawInputs !== undefined && JSON.stringify(safeJson(schemaBody)) === JSON.stringify(defaultScriptInputSchema(rawInputs));
     const outputs = {};
     for (const row of payload?.output ?? [])
         outputs[row.var ?? row.name] = row.source;
@@ -680,7 +691,7 @@ function emitScriptTask(chain, el, payload, type) {
             'type',
             type !== undefined && type !== 'BPMN.Variables' && type !== 'BPMN.ScriptTask' ? str(type) : undefined,
         ],
-        ['inputSchema', payload?.context?.inputSchema?.body !== undefined ? jsonLiteral(payload.context.inputSchema.body) : undefined],
+        ['inputSchema', schemaBody !== undefined && !schemaIsDefault ? jsonLiteral(schemaBody) : undefined],
         ['inputs', record(inputs)],
         ['outputs', verbatim ? undefined : record(outputs)],
         ['outputRows', verbatim],

package/dist/bpmn/intsvc.d.ts

@@ -66,6 +66,14 @@ export declare function intsvcOutputVar(n: EventNode | ExternalNode): string | u
  * @returns The moddle element.
  */
 export declare function createConnectorEvent(ctx: ConnectorCtx, n: EventNode): El;
+/**
+ * The `body` of a connector event node: the subscription's filter in the one place the
+ * platform reads it. `scope` (the `filter` option — the operation's event parameters, by
+ * equality) becomes both the `queryParams` and the leading `(k == 'v')` clauses;
+ * `filters` (payload conditions) follow, each in parentheses, all AND-joined. No scope and
+ * no filters is `{}`, which is what the designer writes for an unfiltered subscription.
+ */
+export declare function eventFilterBody(nodeId: string, scope: Record<string, unknown> | undefined, filters: readonly unknown[] | undefined): Record<string, unknown>;
 /**
  * An external agent / workflow invocation.
  *

package/dist/bpmn/intsvc.js

@@ -1,5 +1,6 @@
 import { createTypedNode, typedNodeOutputVar } from './typed-node.js';
 import { connectorBindingRef } from './connector.js';
+import { eventFilterJmes, eventFilterProblem, readEventFilter } from '../core/event-filters.js';
 /**
  * Which extension type an external invocation lowers to.
  *
@@ -96,8 +97,18 @@ export function createConnectorEvent(ctx, n) {
         // and watches nothing. A curated entry carries its own and the author passes none.
         objectName: n.object ?? op.objectName ?? '',
     };
-    if (n.filter !== undefined)
-        inputs.filter = n.filter;
+    // The subscription's filter goes in the `body` row, where the platform reads it:
+    // `PO.BpmnEngine` `BpmnInputExtensions.GetEventFilters` takes `body.filters.expression`
+    // (and `queryParams` registers the scope with the connector). This emitter used to write
+    // `<uipath:input name="filter" target="filter">{…}</uipath:input>`, an input no handler
+    // reads: on flow-v2-run-12 the wait so scoped validated and matched every mail in the
+    // mailbox (outlook-waitfor-email 1.00 → 0.43), while the v1 arm and every Studio Web
+    // export write `{"filters":{"expression":"(parentFolderId == '…') && (contains(subject, '…'))"},"queryParams":{"parentFolderId":"…"}}`.
+    //
+    // The expression is the scope's equality clauses AND-joined with the authored
+    // `filters`, each lowered by the designer's own grammar (`core/event-filters.ts`) — the
+    // same lowering the Flow serializer does for `onEvent`/`waitForEvent`.
+    inputs.body = eventFilterBody(n.id, n.filter, n.filters);
     if (n.parameters !== undefined)
         inputs.parameters = n.parameters;
     return createTypedNode(ctx.m, n.id, type, {
@@ -108,6 +119,36 @@ export function createConnectorEvent(ctx, n) {
         skipCondition: n.skipCondition,
     }, (varId) => ctx.varTypeOf?.(varId));
 }
+/**
+ * The `body` of a connector event node: the subscription's filter in the one place the
+ * platform reads it. `scope` (the `filter` option — the operation's event parameters, by
+ * equality) becomes both the `queryParams` and the leading `(k == 'v')` clauses;
+ * `filters` (payload conditions) follow, each in parentheses, all AND-joined. No scope and
+ * no filters is `{}`, which is what the designer writes for an unfiltered subscription.
+ */
+export function eventFilterBody(nodeId, scope, filters) {
+    const scopeEntries = Object.entries(scope ?? {}).filter(([, v]) => v !== undefined && v !== null && String(v) !== '');
+    const scopeClauses = scopeEntries.map(([k, v]) => `(${k} == '${String(v).replace(/'/g, "\\'")}')`);
+    const conditions = (filters ?? []).map((leaf, i) => {
+        const { read } = readEventFilter(leaf);
+        if (!read) {
+            throw new Error(`connector event "${nodeId}": filters[${i}] must carry a field and exactly ONE operator ` +
+                `(contains, startsWith, endsWith, equals, notEquals, lessThan, lessThanOrEqual, greaterThan, ` +
+                `greaterThanOrEqual) — got ${JSON.stringify(leaf)}.`);
+        }
+        const problem = eventFilterProblem(read);
+        if (problem)
+            throw new Error(`connector event "${nodeId}": filters[${i}] on \`${read.field}\`: ${problem}`);
+        return `(${eventFilterJmes(read)})`;
+    });
+    const expression = [...scopeClauses, ...conditions].join(' && ');
+    const body = {};
+    if (expression !== '')
+        body.filters = { expression };
+    if (scopeEntries.length > 0)
+        body.queryParams = Object.fromEntries(scopeEntries);
+    return body;
+}
 /**
  * An external agent / workflow invocation.
  *

package/dist/bpmn/serialize.d.ts

@@ -26,6 +26,20 @@ export declare function serialize(built: BuiltBpmn, opts?: BpmnSerializeOpts): P
  */
 export declare function finalizeBpmnXml(xml: string): string;
 export declare function processId(id: string): string;
+/**
+ * The `args` keys every Studio Web script task carries, in the order the designer writes
+ * them. The platform runtime injects these — and only these — into the script's scope.
+ */
+export declare const SCRIPT_ARGS_ENVELOPE: {
+    readonly vars: "=vars";
+    readonly metadata: "=metadata";
+};
+/**
+ * The `uipath:inputSchema` the product writes for a script task's `args`: `vars` and
+ * `metadata` as objects, plus an untyped property per extra key. Exported so the
+ * decompiler can recognise it and leave it out of the source.
+ */
+export declare function defaultScriptInputSchema(args: Record<string, unknown>): Record<string, unknown>;
 /**
  * The variable declarations a scope's output-bearing nodes imply.
  *

package/dist/bpmn/serialize.js

@@ -444,21 +444,50 @@ function buildErrorMappingExt(ctx, rows) {
         }),
     });
 }
+/**
+ * The `args` keys every Studio Web script task carries, in the order the designer writes
+ * them. The platform runtime injects these — and only these — into the script's scope.
+ */
+export const SCRIPT_ARGS_ENVELOPE = { vars: '=vars', metadata: '=metadata' };
+/**
+ * The `uipath:inputSchema` the product writes for a script task's `args`: `vars` and
+ * `metadata` as objects, plus an untyped property per extra key. Exported so the
+ * decompiler can recognise it and leave it out of the source.
+ */
+export function defaultScriptInputSchema(args) {
+    const properties = {};
+    for (const k of Object.keys(args))
+        properties[k] = k in SCRIPT_ARGS_ENVELOPE ? { type: 'object' } : {};
+    return { type: 'object', properties };
+}
 function createScriptTask(ctx, n) {
     const { m } = ctx;
+    // The `args` row is the product's fixed envelope — `vars` and `metadata`, always, in
+    // that order — with the author's `inputs` after it. The platform runtime injects the
+    // ENVELOPE into the script's scope and nothing else: in flow-v2-run-12 every script
+    // that read an `inputs` key as a bare identifier faulted on the cloud with
+    // `<key> is not defined` (3 of 3 cloud-executed script tasks; `check`, `compile` and
+    // `uip maestro bpmn validate` had all passed), while every Studio Web export in
+    // `research/bpmn-roundtrip` and every v1-authored process in the same run carries
+    // exactly this envelope and reads `vars.<id>`. The author's keys are kept so an import
+    // round-trips (`iterator[0]` is how the designer scopes a loop body) and so a key the
+    // author knows the runtime honours can still be passed; a bare read of one is what
+    // `check` reports as SCRIPT_BARE_INPUT_REF. See docs/BPMN_EVAL_RUN12_FINDINGS.md §4 P0-1.
+    const args = { ...SCRIPT_ARGS_ENVELOPE, ...n.inputs };
+    const inputSchema = n.inputSchema ?? defaultScriptInputSchema(args);
     const mapping = m.create('uipath:Mapping', {
         version: 'v1',
         type: m.create('uipath:Type', { value: n.type, version: 'v1' }),
-        // The context holds only the schema here — a script task has no context ROWS.
-        context: n.inputSchema === undefined
-            ? undefined
-            : m.create('uipath:Context', {
-                inputSchema: m.create('uipath:InputSchema', {
-                    type: 'jsonSchema',
-                    body: typeof n.inputSchema === 'string' ? n.inputSchema : JSON.stringify(n.inputSchema),
-                }),
+        // The context holds only the schema here — a script task has no context ROWS. Real
+        // script tasks all carry the schema; the product refuses to run without the envelope
+        // it declares, so an absent one is filled in rather than left out.
+        context: m.create('uipath:Context', {
+            inputSchema: m.create('uipath:InputSchema', {
+                type: 'jsonSchema',
+                body: typeof inputSchema === 'string' ? inputSchema : JSON.stringify(inputSchema),
             }),
-        input: [m.create('uipath:Input', { name: 'args', type: 'json', target: 'bodyField', body: JSON.stringify(n.inputs) })],
+        }),
+        input: [m.create('uipath:Input', { name: 'args', type: 'json', target: 'bodyField', body: JSON.stringify(args) })],
         // Spelled-out rows win over derived ones: `outputs` names each row after the
         // variable it writes, and the product names it after what the script returns
         // while binding a differently-named variable. See ScriptTaskOpts.outputRows.

package/dist/bpmn/typed-node.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 import { resolveFromRegistry } from './registry-fallback.js';
+import { nestConnectorBody } from '../core/connector-inputs.js';
 import { types } from '../core/expr.js';
 const require = createRequire(import.meta.url);
 const REGISTRY = require('./registry-types.json');
@@ -64,7 +65,20 @@ export function isSnapshotType(type) {
  * constant for the one type known to need it rather than derived.
  */
 export const REGISTRY_GAPS = {
-    'Orchestrator.StartAgentJob': { resourceSubType: 'Agent' },
+    // `folderKey` — the job-start family's v1 addressing field. The registry declares
+    // `folderId`, but the engine's v1 branch reads `FolderKey` (`ExecuteApiWorkflowArgs`:
+    // `input.GetValueFromContext<string>(nameof(OrchestratorFolderContext.FolderKey))`), and
+    // the v1 skill verified live that `releaseKey` without it faults with `Could not get
+    // value for key:FolderKey from context in input`. Emitted only for a node addressed by
+    // `releaseKey` — see `OrchestratorOpts.folderKey`.
+    'Orchestrator.StartAgentJob': { resourceSubType: 'Agent', extraContext: ['folderKey'] },
+    'Orchestrator.StartJob': { extraContext: ['folderKey'] },
+    'Orchestrator.ExecuteApiWorkflowAsync': { extraContext: ['folderKey'] },
+    'Orchestrator.StartAgenticProcess': { extraContext: ['folderKey'] },
+    'Orchestrator.StartAgenticProcessAsync': { extraContext: ['folderKey'] },
+    'Orchestrator.StartCaseMgmtProcess': { extraContext: ['folderKey'] },
+    'Orchestrator.StartCaseMgmtProcessAsync': { extraContext: ['folderKey'] },
+    'Orchestrator.BusinessRules': { extraContext: ['folderKey'] },
     // `notEnforcedInputs` — required InputFields the platform does NOT actually enforce.
     //
     // MEASURED, on a real trigger that carries `connection`, `folderKey`, `connectorKey`,
@@ -226,9 +240,19 @@ function contextRows(m, type, spec, supplied, verbatim = false) {
         return rows;
     }
     for (const field of spec.context) {
-        const value = supplied[field.name] ?? field.default;
+        let value = supplied[field.name] ?? field.default;
         if (value === undefined || value === null)
             continue;
+        // A json field whose REGISTRY default is the text `null` is unrunnable as declared:
+        // the platform parses the row to a JSON null and `IntSvcUnifiedHttpRequestArgs`
+        // throws `Body cannot be null` on it (incident 102018 — flow-v2-run-12
+        // slack-http-fallback, a GET with no body, faulted on exactly this after check,
+        // compile and validate had passed). Omitting the row is the same null. So a
+        // default of `null` on a json field is written as `{}`, the empty object the handler
+        // accepts; an author who wrote `null` themselves still gets it verbatim, and an
+        // import's `"null"` text round-trips untouched (see decompile's json-row rules).
+        if (field.type === 'json' && !(field.name in supplied) && field.default === 'null')
+            value = {};
         emitted.add(field.name);
         // A `json` field goes in the CDATA BODY, not a `value` attribute. The product
         // validator parses that field as JSON and reads the attribute WITHOUT XML
@@ -266,6 +290,28 @@ function contextRows(m, type, spec, supplied, verbatim = false) {
     }
     return rows;
 }
+/**
+ * The `target` values a payload row can carry — `BpmnInputTarget` in PO.BpmnEngine
+ * (`InputResolutionActivities` routes `Body`/`BodyField`/`Header`/`PathVariable`/`Query`/
+ * `PathParameters`/`QueryParameters`/`File`), plus the connector emitter's `multipart`.
+ * An undeclared `separateInputs` key that is one of these addresses a slot; any other
+ * key is a field — see `inputRows`.
+ */
+const PAYLOAD_TARGETS = new Set([
+    'body',
+    'bodyField',
+    'header',
+    'headers',
+    'pathVariable',
+    'pathParameters',
+    'query',
+    'queryParameters',
+    'file',
+    'multipart',
+]);
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * The payload rows, per the type's `inputPattern`.
  *
@@ -308,11 +354,37 @@ function inputRows(m, spec, inputs) {
         // `recordId` as `"1111-…"`, quotes included, where every real export writes
         // `type="string" value="1111-…"`. A structured value is still a json body; a
         // scalar is written as the `value` attribute, the way a declared scalar is.
+        //
+        // An undeclared key is a TARGET, then — `body`, `pathParameters`, `queryParameters`
+        // — and only a target. A key that is none of the platform's targets is a request
+        // FIELD the author wrote where a slot belongs (`inputs: { script: '…' }` on
+        // `Intsvc.ActivityExecution`), and keyed as its own target it reaches a row the
+        // platform never reads: on flow-v2-run-12 the JDBC `execute-query-synchronously` node
+        // so written went out as `<uipath:input name="script" … target="script"/>` and every
+        // one of seven cloud runs faulted `Integration Services bad request`, while the v1 arm's
+        // `<uipath:input name="body" target="body">{"script":"…"}</uipath:input>` completed
+        // first time. Such keys fold into the type's own payload row (`inputName`/`inputTarget`,
+        // `body` for the Integration Service family), nested by their dotted ids, exactly as
+        // `.connector()` writes a request. A type with no payload row keeps keying them.
         const declared = new Map(spec.inputs.map((f) => [f.name, f]));
-        return keys.map((k) => {
+        const fieldKeys = spec.inputName !== null && spec.inputTarget !== null
+            ? keys.filter((k) => !declared.has(k) && !PAYLOAD_TARGETS.has(k) && k !== spec.inputName)
+            : [];
+        const folded = new Set(fieldKeys);
+        const rows = keys
+            .filter((k) => !folded.has(k))
+            .map((k) => {
             const field = declared.get(k);
-            return payloadInput(m, k, field?.target ?? k, inputs[k], field?.type ?? inferredInputType(inputs[k]));
+            let value = inputs[k];
+            if (k === spec.inputName && fieldKeys.length > 0 && isPlainRecord(value)) {
+                value = { ...nestConnectorBody(Object.fromEntries(fieldKeys.map((f) => [f, inputs[f]]))), ...value };
+            }
+            return payloadInput(m, k, field?.target ?? k, value, field?.type ?? inferredInputType(value));
         });
+        if (fieldKeys.length > 0 && !keys.includes(spec.inputName)) {
+            rows.push(payloadInput(m, spec.inputName, spec.inputTarget, nestConnectorBody(Object.fromEntries(fieldKeys.map((f) => [f, inputs[f]]))), 'json'));
+        }
+        return rows;
     }
     if (!spec.inputName)
         return [];

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

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

@@ -78,3 +78,23 @@ interface ConnectorSlots {
         };
     };
 }
+/**
+ * Fold a body keyed by the registry's dotted field ids into the nested request
+ * object those ids describe: `{"fields.project.key":"CE"}` → `{"fields":{"project":{"key":"CE"}}}`.
+ *
+ * `buildConnectorInputs` keeps the DOTTED keys on purpose — Flow's `bodyParameters` is a
+ * flat map and Flow's runtime (`convertDotNotationToNested`) nests it before the call.
+ * The Maestro BPMN runtime does not: `IntSvcSendTaskHandler` sends the `body` input as
+ * written, so a dotted key reaches the connector as a literal property name. Measured on
+ * flow-v2-run-12: the SDK's Jira `create-issue` body went out flat and Integration
+ * Service answered 400 `project: Specify a valid project ID or key`; the v1 arm, which
+ * writes the nested form by hand, created the ticket. A BPMN body therefore goes through
+ * this before it is serialised.
+ *
+ * A `[*]` segment names an array. On a leaf (`users[*]`) an array value is kept and a
+ * scalar becomes a one-element list, as the product's own conversion does; on an inner
+ * segment (`attachments[*].url`) each element of an array value becomes one object, and
+ * a scalar one. Later keys win over earlier ones at the same leaf; a nested object the
+ * author already wrote under a plain key is merged into, not replaced.
+ */
+export declare function nestConnectorBody(flat: Record<string, unknown>): Record<string, unknown>;