@uipath/maestro-builder-sdk 6.19.0 → 6.20.1

package/dist/check.js

@@ -10,6 +10,7 @@ import { FlowNode } from './core/node-classes.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
 import { definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
 import { bundledActionNodeType, bundledDefinition, resolveContributionDefinition } from './serialize.js';
+import { sdkFormFieldType } from './core/form-field-type.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
 import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
 import { checkEventResolution, checkEventSubscription, eventParamsFor, } from './core/event-checks.js';
@@ -19,7 +20,7 @@ import { prepareCommand } from './core/cli-spelling.js';
 import { commentText } from './core/comment-text.js';
 import { editDistance } from './core/edit-distance.js';
 import { isAnswerField } from './core/hitl-answers.js';
-import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
+import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome, outcomeIdOf } from './core/hitl-routing.js';
 import { declaredExits, hasExits } from './core/step-ports.js';
 import { stopsAtEnd } from './flow-step-tree.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
@@ -179,6 +180,8 @@ function checkFlow(built, ancestors, opts = {}) {
     // OBJECT of the child's declared outputs, so a read of it is checked against
     // that child rather than waved through (see SUBFLOW_* below).
     const subflowChildren = new Map();
+    // `inLoop`: inside a loop/do-while body; `'arm'` when, counting from the
+    // innermost container, the path also sits in a `.parallel` arm.
     const walk = (steps, inLoop = false, errorSource) => {
         // Nothing may follow a terminate. `.return()` merely ends its own path, so a
         // later step there is at worst dead weight — but a terminate ends the RUN,
@@ -197,6 +200,22 @@ function checkFlow(built, ancestors, opts = {}) {
                 step: term.name,
             });
         }
+        // Nothing may follow a `.break()` or `.continue()` on the same path: the
+        // path leaves through the container's handle, so a later step would get no
+        // incoming edge.
+        const exitAt = steps.findIndex((st) => st.kind === 'break' || st.kind === 'continue');
+        if (exitAt !== -1 && exitAt < steps.length - 1) {
+            const after = steps[exitAt + 1];
+            const kind = steps[exitAt].kind;
+            diags.push({
+                level: 'error',
+                code: 'LOOP_EXIT_UNREACHABLE_AFTER',
+                message: `${steps.length - exitAt - 1} step(s) follow .${kind}(), starting with `
+                    + `"${'name' in after ? after.name : after.kind}". .${kind}() leaves this path through the container's `
+                    + `${kind} handle, so none of them can ever run. Move them before the .${kind}().`,
+                ...('name' in after ? { step: String(after.name) } : {}),
+            });
+        }
         // Nothing may follow a human task whose EVERY outcome ends the run, except a
         // `.return()`. Each outcome gets its own End node — the flow runtime never
         // reads `action`, so only the graph can end the run there — which leaves
@@ -311,7 +330,7 @@ function checkFlow(built, ancestors, opts = {}) {
                 }
                 else {
                     const model = hitlExitModel(prevSpec.inputs, prevAction?.options?.version);
-                    const ids = (prevSpec.inputs.outcomes ?? []).map((o, i) => outcomeSlug(typeof o === 'string' ? o : o?.name, i));
+                    const ids = (prevSpec.inputs.outcomes ?? []).map((o, i) => outcomeIdOf(o, i));
                     if (model.shape === 'placeholder') {
                         diags.push({
                             level: 'error', code: 'HITL_OUTCOME_PORTS_OFF', step: prevAction?.name,
@@ -424,7 +443,7 @@ function checkFlow(built, ancestors, opts = {}) {
                 if (s0.kind !== 'stepSwitch'
                     && s.spec.kind === 'hitl' && hitlRoutesPerOutcome(s.spec.inputs, s.options?.version)) {
                     hitlOutcomeSteps.set(s.name, (s.spec.inputs.outcomes ?? []).map((o, i) => ({
-                        id: outcomeSlug(typeof o === 'string' ? o : o?.name, i),
+                        id: outcomeIdOf(o, i),
                         endsProcess: typeof o !== 'string' && o?.action === 'End',
                     })));
                 }
@@ -442,6 +461,7 @@ function checkFlow(built, ancestors, opts = {}) {
                         && !hitlRoutesPerOutcome(s.spec.inputs, s.options?.version)) {
                         hitlChoiceNoPorts.set(s.name, {
                             names: outcomes.map((o) => String((typeof o === 'string' ? o : o?.name) ?? '').trim()),
+                            ids: outcomes.map((o, i) => outcomeIdOf(o, i)),
                             ends: outcomes.filter((o) => typeof o !== 'string' && o?.action === 'End')
                                 .map((o) => String(o.name ?? '').trim()),
                             variant: s.spec.inputs?.variant,
@@ -563,6 +583,23 @@ function checkFlow(built, ancestors, opts = {}) {
                 // Two arms with the same value: the second can never be reached, since
                 // the runtime takes the first matching case.
                 const seenValues = new Set();
+                // Two cases on one id share one `case-<id>` port (#1130: an explicit
+                // `id` can collide with a positional `case_<n>`).
+                const seenIds = new Set();
+                s.cases.forEach((c, i) => {
+                    const caseId = c.id ?? `case_${i + 1}`;
+                    if (typeof caseId !== 'string' || caseId === '' || seenIds.has(caseId)) {
+                        diags.push({
+                            level: 'error',
+                            code: 'SWITCH_CASE_ID',
+                            message: typeof caseId !== 'string' || caseId === ''
+                                ? `Switch "${s.name}" case ${JSON.stringify(c.value)} has an id that is not a non-empty string. Leave \`id\` out for the positional case_<n>.`
+                                : `Switch "${s.name}" has two cases with the id "${caseId}", so both would leave from one 'case-${caseId}' port. Give one a different \`id\`.`,
+                            step: s.name,
+                        });
+                    }
+                    seenIds.add(String(caseId));
+                });
                 for (const c of s.cases) {
                     const key = `${typeof c.value}:${String(c.value)}`;
                     if (seenValues.has(key))
@@ -601,7 +638,7 @@ function checkFlow(built, ancestors, opts = {}) {
                 parallelNames.add(s.name);
                 checkParallel(s, diags);
                 for (const arm of s.arms)
-                    walk(arm, inLoop);
+                    walk(arm, inLoop ? 'arm' : false);
             }
             else if (s.kind === 'loop') {
                 // A container is a legal ERROR-port source (its definition declares the
@@ -649,6 +686,17 @@ function checkFlow(built, ancestors, opts = {}) {
                     });
                 }
             }
+            else if (s.kind === 'continue') {
+                if (!inLoop) {
+                    diags.push({
+                        level: 'error', code: 'CONTINUE_OUTSIDE_LOOP',
+                        message: '.continue() is only valid inside a .loop() or .doWhile() body: it goes on to the container\'s next iteration.',
+                    });
+                }
+                else if (inLoop === 'arm') {
+                    diags.push(loopExitInArm());
+                }
+            }
             else if (s.kind === 'return') {
                 for (const [name, e] of Object.entries(s.values)) {
                     addExpr(e.js, 'return');
@@ -1356,6 +1404,13 @@ function writtenTails(steps, incoming, sinks) {
             breaks.push(...tails);
             return [];
         }
+        // A `.continue()` path goes to the container's next pass, not to the steps
+        // after it: for a do-while that is the condition test, one of the ways out,
+        // exactly like reaching the end of the body — so it joins the exits too.
+        if (st.kind === 'continue') {
+            breaks.push(...tails);
+            return [];
+        }
         if (st.kind === 'return' || st.kind === 'terminate')
             return [];
         const before = surelyWritten(tails);
@@ -2642,8 +2697,22 @@ function checkAgenticProcess(step, inputs, diags) {
     }
     const inSolution = inputs?.location === 'in-solution';
     if (!inSolution && blank(inputs?.folderPath)) {
-        at('AGENTIC_NO_FOLDER', `Agentic process step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so `
-            + `the Orchestrator folder holding the process is required.`, `folderPath: 'Shared/uipath-agents/ProcurementProcess'`);
+        // `registry list --local` shows an in-solution Flow sibling with folderPath: "".
+        // An explicit `form` other than 'flow' keeps the published hint: switching it would change the node type.
+        const meantInSolution = inputs?.form === 'flow'
+            || (typeof inputs?.folderPath === 'string' && inputs?.form === undefined);
+        if (meantInSolution) {
+            const formPart = inputs?.form === 'flow' ? '' : `, form: 'flow'`;
+            at('AGENTIC_NO_FOLDER', `Agentic process step "${step}" has an empty \`folderPath\`. If the process is an unpublished sibling `
+                + `Flow in this solution, call it in-solution: set \`location: 'in-solution'\`${formPart} and \`projectId\` `
+                + `(the sibling's \`resource.projectKey\` in \`resources/solution_folder/process/flow/<project>.json\`), and `
+                + `drop \`folderPath\`. If it is published, set \`folderPath\` to the Orchestrator folder that holds it — `
+                + `the runtime starts the job by name + folder.`, `location: 'in-solution'${formPart}, projectId: '<resource.projectKey>'`);
+        }
+        else {
+            at('AGENTIC_NO_FOLDER', `Agentic process step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so `
+                + `the Orchestrator folder holding the process is required.`, `folderPath: 'Shared/uipath-agents/ProcurementProcess'`);
+        }
     }
     const form = inputs?.form ?? 'bpmn';
     if (inSolution && form !== 'flow') {
@@ -3115,13 +3184,31 @@ function checkInlineAgent(step, inputs, diags, opts = {}) {
                 + `run-dependent search needs.`);
         }
     }
+    // The index id is half of the resource node's TYPE
+    // (`…context.index.<slug>.<id>`), and the platform resolves the index by it.
+    // A blank, padded or non-GUID id builds a type no tenant serves, and nothing
+    // downstream says so: the flow compiles, merges and validates, and the agent
+    // runs ungrounded. So it is an error, not a warning. The id is tested as
+    // written, not trimmed, because serialize emits it as written.
+    for (const cx of contexts) {
+        const id = typeof cx?.id === 'string' ? cx.id : '';
+        if (!GUID_RE.test(id)) {
+            at('AGENT_CONTEXT_NO_ID', `Inline agent step "${step}" grounds on context index "${cx?.name ?? ''}" with `
+                + (id.trim() === '' ? 'no `id`'
+                    : GUID_RE.test(id.trim()) ? `\`id\` ${JSON.stringify(cx?.id)}, which has whitespace around the GUID`
+                        : `\`id\` ${JSON.stringify(cx?.id)}, which is not a GUID`) + '. '
+                + `The id is the index's key: it is the tail of the resource node's type and how the runtime finds `
+                + `the index, so without a real one the agent runs ungrounded and \`validate\` does not notice. `
+                + `\`uip solution resources list --kind Index --source remote --search "<name>"\` returns it as \`Key\`.`);
+        }
+    }
     // An index outside the deployment folder needs its folder named. The resource
     // file carries no `indexId`, so `indexName` + `folderPath` is the whole locator,
     // and `@uipath/tool-agent`'s `createIndexBinding` leaves the folder off the
     // binding when `folderPath` is empty. A WARNING, not an error: an index in the
     // deployment folder resolves without it.
     for (const cx of contexts) {
-        if (cx !== undefined && cx.folderPath === undefined) {
+        if (cx != null && cx.folderPath === undefined) {
             warn('AGENT_CONTEXT_NO_FOLDER_PATH', `Inline agent step "${step}" grounds on context index "${cx.name ?? ''}" without a \`folderPath\`. `
                 + `The emitted resource carries no index id, so the folder is half of how the runtime finds the `
                 + `index, and the binding is written without one. Give the index's folder — `
@@ -3448,8 +3535,8 @@ function checkInlineAgent(step, inputs, diags, opts = {}) {
             for (const f of Array.isArray(e.fields) ? e.fields : []) {
                 if (!FORM_FIELD_TYPES.includes(String(f?.type))) {
                     at('INLINE_AGENT_ESCALATION_FIELD_TYPE_UNKNOWN', `Inline agent step "${step}"'s quick-form escalation gives the field "${String(f?.id ?? '?')}" the type `
-                        + `${JSON.stringify(f?.type)}, which the form does not recognize — it would be published as a plain `
-                        + `string. Valid: ${FORM_FIELD_TYPES.join(', ')}.`, formFieldTypeHint(f?.type));
+                        + `${JSON.stringify(f?.type)}, ${formFieldTypeWhy(f?.type, `which the form does not recognize — it would `
+                            + `be published as a plain string`)}. Valid: ${FORM_FIELD_TYPES.join(', ')}.`, formFieldTypeHint(f?.type));
                 }
             }
             continue;
@@ -3831,7 +3918,7 @@ function armTails(steps, incoming) {
                 tails = [];
             continue;
         }
-        if (st.kind === 'return' || st.kind === 'terminate' || st.kind === 'break')
+        if (st.kind === 'return' || st.kind === 'terminate' || st.kind === 'break' || st.kind === 'continue')
             return [];
         if (st.kind === 'action') {
             tails = actionTails(st.name, st.spec, st.options?.version);
@@ -4165,12 +4252,28 @@ function checkHttp(step, inputs, diags) {
         }
     }
 }
+/**
+ * Why a form-field type is refused: a product spelling of a type the SDK
+ * models (`"string"` is the platform's own name for text), or a type
+ * the SDK does not model at all. `unknownWhy` is the caller's reason for the
+ * second case; the default is a human task's.
+ */
+function formFieldTypeWhy(type, unknownWhy = `which the platform does not recognize. Older runtimes read it as text, newer ones reject `
+    + `the form`) {
+    const alias = sdkFormFieldType(type);
+    return alias !== undefined
+        ? `which is the platform's spelling of the SDK's '${alias}' — the SDK writes '${alias}'`
+        : unknownWhy;
+}
 /** Every FormFieldType, once; `Record<FormFieldType, …>` makes tsc refuse a missing or extra one. */
 const FORM_FIELD_TYPE_SET = { text: true, number: true, boolean: true, 'date-time': true };
-/** Form-field types the platform recognizes; anything else normalizes to text. */
+/** The form-field types the SDK models. */
 const FORM_FIELD_TYPES = Object.keys(FORM_FIELD_TYPE_SET);
 /** The `suggestion` for an unknown form-field type: the nearest valid one, else `type: 'text'`. */
 function formFieldTypeHint(type) {
+    const alias = sdkFormFieldType(type);
+    if (alias !== undefined)
+        return `type: '${alias}'`;
     const nearest = nearestName(String(type), FORM_FIELD_TYPES);
     return nearest !== undefined ? `type: '${nearest}'` : `type: 'text'`;
 }
@@ -4182,18 +4285,6 @@ const RESERVED_ANSWER_IDS = new Set(['output', 'status', 'Action']);
  * family — same availability note as do-while).
  */
 const HITL_VARIANTS = ['quick-form', 'action-app', 'document-validation'];
-/**
- * An outcome's stable id — the serializer's own slug rule, mirrored so the
- * `outcome-<id>` port names this file validates are the ones that get emitted.
- */
-function outcomeSlug(name, index) {
-    const slug = String(name ?? '')
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-    return slug || `outcome-${index + 1}`;
-}
 /**
  * Why a base or quick-form task continues every outcome to the next step, as a
  * clause for a diagnostic. `pinned` is the step's `{ version }`.
@@ -4263,10 +4354,9 @@ function reportUnreachableHitlOutcomes(choices, exprs, diags) {
         for (const m of js.matchAll(/\$vars\.([A-Za-z0-9_]+)\s*\[/g))
             readsOutcome.add(m[1]);
     }
-    for (const [step, { names, ends, variant, pinned, portsOff }] of choices) {
+    for (const [step, { names, ids, ends, variant, pinned, portsOff }] of choices) {
         if (readsOutcome.has(step))
             continue;
-        const ids = names.map((n, i) => outcomeSlug(n, i));
         // The base node and quick-form draw a handle per outcome, so both can route
         // it — `.stepSwitch`, or `outcomePorts: true` (a pin keeps its version). An
         // app-backed variant cannot: the Action read is its only remedy.
@@ -4449,10 +4539,8 @@ function checkHitl(step, inputs, diags) {
             return;
         }
         if (!FORM_FIELD_TYPES.includes(String(f?.type))) {
-            at('HITL_FIELD_TYPE_UNKNOWN', `Human task "${step}" gives the form field "${id}" the type ${JSON.stringify(f?.type)}, which `
-                + `the platform does not recognize — it normalizes an unknown type to text, so the reviewer `
-                + `gets a text box and the value comes back as a string. Valid: `
-                + `${FORM_FIELD_TYPES.join(', ')}.`, formFieldTypeHint(f?.type));
+            at('HITL_FIELD_TYPE_UNKNOWN', `Human task "${step}" gives the form field "${id}" the type ${JSON.stringify(f?.type)}, `
+                + `${formFieldTypeWhy(f?.type)}. Valid: ${FORM_FIELD_TYPES.join(', ')}.`, formFieldTypeHint(f?.type));
         }
         if (isAnswerField(f))
             answers++; // an `output`, or an `inOut` whose reviewed value comes back
@@ -4491,8 +4579,26 @@ function checkHitl(step, inputs, diags) {
         return;
     }
     const names = new Set();
+    const ids = new Map();
     outcomes.forEach((o, i) => {
         const name = (typeof o === 'string' ? o : o?.name)?.trim();
+        // Two outcomes on one id would share one `outcome-<id>` port, so the
+        // second's edge could never be told apart. An explicit `id` can collide
+        // with another outcome's derived slug.
+        const id = outcomeIdOf(o, i);
+        const explicitId = typeof o === 'object' && o !== null ? o.id : undefined;
+        if (explicitId !== undefined && (typeof explicitId !== 'string' || explicitId === '')) {
+            at('HITL_OUTCOME_BAD_ID', `Human task "${step}" outcome ${JSON.stringify(name ?? i)} has an id that is not a non-empty string. `
+                + `Leave \`id\` out to use the slug of the name.`, `{ name: ${JSON.stringify(name ?? 'Approve')} }`);
+        }
+        else if (ids.has(id) && ids.get(id) !== String(name ?? '')) {
+            // Same name, same id: HITL_DUP_OUTCOME below reports it once, as a name clash.
+            at('HITL_DUP_OUTCOME_ID', `Human task "${step}" gives outcomes "${ids.get(id)}" and "${name}" the same id "${id}", so both would `
+                + `leave from one 'outcome-${id}' port. Give one of them a different \`id\`.`);
+        }
+        else {
+            ids.set(id, String(name ?? ''));
+        }
         if (!name) {
             at('HITL_OUTCOME_NO_NAME', `Human task "${step}" has an outcome with no name (outcomes[${i}]). The result carries the `
                 + `outcome's NAME — it is what "$vars.${step}.output.Action" holds and what the platform's `
@@ -5227,14 +5333,14 @@ function checkStepRefs(built, diags) {
     index(built.steps, false, '', undefined);
     /** Every ref, with where it sits. */
     const found = [];
-    const collect = (steps, from, scope, arm) => {
+    const collect = (steps, from, scope, arm, enclosing = []) => {
         let source = from;
         for (const [i, s] of steps.entries()) {
             if (s.kind === 'action')
                 source = s.name;
             if (s.kind === 'stepToRef') {
                 found.push({
-                    target: s.target, port: s.port, from: source, scope, arm,
+                    target: s.target, port: s.port, from: source, scope, arm, enclosing,
                     // Only a default-port ref hands the path off, so only it can strand
                     // what follows; a side exit leaves the chain running.
                     after: s.port === 'output' ? steps.length - i - 1 : 0,
@@ -5242,23 +5348,23 @@ function checkStepRefs(built, diags) {
                 continue;
             }
             if (s.kind === 'stepToList')
-                collect(s.body, source, scope, arm);
+                collect(s.body, source, scope, arm, enclosing);
             else if (s.kind === 'branch') {
-                collect(s.then, source, scope, arm);
-                collect(s.otherwise, source, scope, arm);
+                collect(s.then, source, scope, arm, enclosing);
+                collect(s.otherwise, source, scope, arm, enclosing);
             }
             else if (s.kind === 'switch') {
-                s.cases.forEach((c) => collect(c.body, source, scope, arm));
-                collect(s.default ?? [], source, scope, arm);
+                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}`));
+                s.arms.forEach((a, i) => collect(a, source, scope, `${s.name}#${i}`, enclosing));
             else if (s.kind === 'loop' || s.kind === 'doWhile')
-                collect(s.body, source, s.name, arm);
+                collect(s.body, source, s.name, arm, [...enclosing, s.name]);
         }
     };
     collect(built.steps, undefined, '', undefined);
-    for (const { target, from, after, scope, arm } of found) {
+    for (const { target, from, after, scope, arm, enclosing } of found) {
         const where = from ? `after "${from}"` : 'at the start of the flow';
         const say = (level, code, message, suggestion) => {
             diags.push({ level, code, message, step: from ?? 'stepToRef', ...(suggestion ? { suggestion } : {}) });
@@ -5269,6 +5375,16 @@ function checkStepRefs(built, diags) {
                 + `${near ? ` (did you mean "${near}"?)` : ''}. It takes the same name you passed to .step().`, near ? `.stepToRef('${near}')` : undefined);
             continue;
         }
+        // A ref to a container the path is INSIDE names it as a step, so the edge
+        // enters it from its outer input: it starts the loop over from its first
+        // item, while the iteration the path was in never finishes. What the author
+        // means is almost always the next item, or out of the loop (#1129).
+        if (enclosing.includes(target)) {
+            say('error', 'REF_TO_OWN_LOOP', `.stepToRef('${target}') ${where} names the loop it is inside. That edge enters "${target}" from its outer `
+                + `input, which starts the loop over instead of going on to the next item. Use .continue() to go on to the `
+                + `next iteration, or .break() to leave the loop.`, '.continue()');
+            continue;
+        }
         if (inPortList.has(target)) {
             say('error', 'REF_INTO_PORT_LIST', `.stepToRef('${target}') ${where} targets a step inside another port's path. That path runs only when ITS `
                 + `port fired — it is not somewhere another edge can jump into. Point at a step on the main path, or end `
@@ -5287,12 +5403,15 @@ function checkStepRefs(built, diags) {
                     + `iteration, so those have no value. Point at a step after the loop, or do this work inside the body.`);
                 continue;
             }
-            // OUT of a loop body is a `break`. Flow has no break or continue node, and
-            // whether the runtime accepts an edge leaving a bpmn:SubProcess this way is
-            // not measured — so this warns and leaves the verdict to `validate`.
-            say('warning', 'REF_OUT_OF_LOOP', `.stepToRef('${target}') ${where} leaves the body of loop "${scope}" — a break. Flow has no break or `
-                + `continue node, and whether the runtime honours an edge out of a loop body is not something this checker `
-                + `can prove. Verify with uip maestro flow validate before relying on it.`);
+            // OUT of a loop body to a step after it. The container's own handles are
+            // the measured ways out — `.break()` (its break handle) and `.continue()`
+            // (its continue handle). Whether the runtime accepts an edge leaving a
+            // bpmn:SubProcess some other way is not measured, so this warns and leaves
+            // the verdict to `validate`.
+            say('warning', 'REF_OUT_OF_LOOP', `.stepToRef('${target}') ${where} leaves the body of loop "${scope}" by an edge straight to a step outside it. `
+                + `To leave the loop, use .break() (the loop's break handle); to go on to the next item, use .continue(). `
+                + `Whether the runtime honours any other edge out of a loop body is not something this checker can prove: `
+                + `verify with uip maestro flow validate before relying on it.`);
         }
         // Best effort from here: the mechanism is understood, the runtime's behaviour
         // is not measured, so these WARN and leave the verdict to `validate`.
@@ -5316,6 +5435,23 @@ function checkStepRefs(built, diags) {
         }
     }
 }
+/**
+ * LOOP_EXIT_IN_PARALLEL_ARM: a `.continue()` inside a `.parallel` arm sends
+ * that arm's token to the container's continue handle, so it never reaches the
+ * arm's Merge. The Merge is a bpmn:ParallelGateway that waits for every branch
+ * it forked, and the iteration it belongs to is still running: the join never
+ * fires and the iteration hangs. (`.break()` leaves the whole container, so
+ * whether the runtime cancels the pending Merge is a different, unmeasured
+ * question; it is not refused here.)
+ */
+function loopExitInArm() {
+    return {
+        level: 'error', code: 'LOOP_EXIT_IN_PARALLEL_ARM',
+        message: `.continue() inside a .parallel() arm sends that arm's path to the loop's continue handle, so it never `
+            + `reaches the arm's Merge, which waits for every branch it forked: the join never fires and the iteration `
+            + `hangs. Put the .continue() after the .parallel(), on a .branch() that reads what the arms produced.`,
+    };
+}
 /**
  * A field read off `$vars.<step>.error` — the envelope, and the one shape the
  * authoring surface writes.

package/dist/cli/commands/flow.js

@@ -108,6 +108,7 @@ export function registerFlowCommands(program) {
         .option('--original <file>', '(required) original .flow path, the artifact to merge into')
         .option('-o, --output <file>', 'merged output path')
         .option('--baseline <file>', 'compiled pristine decompile')
+        .option('--strict', 'refuse when the no-edit round trip (--baseline) differs from the original')
         .allowExcessArguments()
         .action(async (_edited, options, command) => {
         const pair = namedOrLegacySecond(command, {
@@ -120,6 +121,8 @@ export function registerFlowCommands(program) {
         const argv = [original, edited];
         addValue(argv, '-o', options.output);
         addValue(argv, '--baseline', options.baseline);
+        if (options.strict)
+            argv.push('--strict');
         await invoke('flow merge', () => loadTool(import.meta.url, '../../merge-cli.js'), argv);
     });
 }

package/dist/compile-cli.js

@@ -167,7 +167,14 @@ export async function run(argv) {
     // families the SDK cannot into the same directory (including `internal`
     // built-ins such as `load-attachments`), so anything else found there is
     // someone else's and is left alone.
+    //
+    // Owning the TYPE is not owning the FILE, though. Decompile keeps a canvas
+    // agent's `source` directory, so compiling decompiled source to another `.flow`
+    // in the same project writes into the ORIGINAL flow's agent directory, and the
+    // canvas resources there are still that flow's. A resource another
+    // `.flow` beside this one references by `inputs.source` is never pruned.
     const removedResources = [];
+    const referencedElsewhere = resourceSourcesOfOtherFlows(outDir, resolve(out));
     const owned = new Set(sidecars
         .filter((s) => /\/resources\/[^/]+\/resource\.json$/.test(s.path))
         .map((s) => resolve(outDir, s.path)));
@@ -182,6 +189,11 @@ export async function run(argv) {
             const file = join(resourcesDir, entry, 'resource.json');
             if (!existsSync(file) || owned.has(file))
                 continue;
+            const user = referencedElsewhere.get(entry);
+            if (user !== undefined) {
+                console.log(`compile: kept ${join('resources', entry, 'resource.json')}: ${user} still references it`);
+                continue;
+            }
             let body;
             try {
                 body = JSON.parse(readFileSync(file, 'utf8'));
@@ -248,3 +260,42 @@ function serializeWarningDiagnostic(w) {
     return { level: 'warning', code: w.code, message: w.message };
 }
 runWhenInvokedDirectly(import.meta.url, 'compile', run);
+/**
+ * The `inputs.source` uuids the OTHER `.flow` files in `dir` reference, each
+ * mapped to the first file that does. `dir` is the namespace sidecar paths are
+ * relative to, so these are the agent resources another flow still uses. The
+ * flow being written (`self`) is left out: what it no longer references is what
+ * pruning is for. Subflow bodies are included; an unreadable file contributes
+ * nothing.
+ */
+function resourceSourcesOfOtherFlows(dir, self) {
+    const users = new Map();
+    let entries;
+    try {
+        entries = readdirSync(dir).filter((f) => f.endsWith('.flow') && resolve(dir, f) !== self);
+    }
+    catch {
+        return users;
+    }
+    for (const f of entries) {
+        let flow;
+        try {
+            flow = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const walk = (scope) => {
+            const s = scope;
+            for (const n of Array.isArray(s?.nodes) ? s.nodes : []) {
+                const src = n?.inputs?.source;
+                if (typeof src === 'string' && !users.has(src))
+                    users.set(src, f);
+            }
+            if (s?.subflows && typeof s.subflows === 'object')
+                Object.values(s.subflows).forEach(walk);
+        };
+        walk(flow);
+    }
+    return users;
+}

package/dist/core/actions.d.ts

@@ -190,9 +190,9 @@ export interface ConnectorOpts {
     object?: string;
 }
 /**
- * A form field's type. These are the platform's own strings — an unrecognized
- * one is NOT an error there, it silently normalizes to text (so a number field
- * becomes a text box), which is why `check` rejects anything outside this set.
+ * A form field's type. The platform does not recognize a type outside this set:
+ * older runtimes read it as text (so a number field becomes a text box), newer
+ * ones reject the form. That is why `check` rejects anything outside this set.
  */
 export type FormFieldType = 'text' | 'number' | 'boolean' | 'date-time';
 /** A value the reviewer READS: shown on the form, filled in from the flow. */
@@ -330,12 +330,20 @@ export interface DocValidationInputs {
  * rather than continuing (the platform's own two-value vocabulary — anything
  * that is not exactly `'End'` reads as continue).
  *
+ * `id` is the outcome's wire id — `schema.outcomes[].id`, and the `outcome-<id>`
+ * port its edge leaves from. Leave it out and the id is a slug of `name`
+ * (`'Needs info'` → `needs-info`). Set it only to keep an id a flow already
+ * has, as decompile does for a task the designer drew
+ * (`{ name: 'Reject', id: 'outcome-1778015958049' }`): merge keeps the
+ * original node, so its edges must use that node's ids.
+ *
  * @remarks
  * A bare string is shorthand for `{ name }`.
  */
 export type Outcome = string | {
     name: string;
     action?: 'Continue' | 'End';
+    id?: string;
 };
 /**
  * WHICH human-task node type to emit. The platform ships three spellings of the
@@ -1132,7 +1140,7 @@ export interface AgentInputs {
      *
      * **Display-only, and it is the only thing that differs.** `registry get` on a
      * coded and a low-code agent returns the same node type, the same
-     * `Orchestrator.StartAgentJob` service type, the same `sortOrder: 505` and the
+     * `Orchestrator.StartAgentJob` service type, the same `sortOrder` and the
      * same bindings shape; the single difference is `display.icon` —
      * `coded-agent` vs `autonomous-agent`. Which one a given resource is cannot be
      * known offline, so it is stated here rather than guessed. Check with
@@ -2607,7 +2615,7 @@ export declare function agenticProcess(inputs: AgenticProcessInputs): ActionSpec
  * @remarks
  * **Coded and low-code agents are the same node.** This one factory authors both.
  * `registry get` on a coded agent and on a low-code one returns the same node type,
- * the same service type, the same `sortOrder: 505` and the same bindings shape; the
+ * the same service type, the same `sortOrder` and the same bindings shape; the
  * only difference is the icon, which is what `flavour` sets. Which kind a resource
  * is a property of what somebody published, not of the flow — so if a task asks for
  * "a coded agent", what it is asking you to get right is the RESOURCE you point at.

package/dist/core/actions.js

@@ -609,7 +609,7 @@ export function agenticProcess(inputs) {
  * @remarks
  * **Coded and low-code agents are the same node.** This one factory authors both.
  * `registry get` on a coded agent and on a low-code one returns the same node type,
- * the same service type, the same `sortOrder: 505` and the same bindings shape; the
+ * the same service type, the same `sortOrder` and the same bindings shape; the
  * only difference is the icon, which is what `flavour` sets. Which kind a resource
  * is a property of what somebody published, not of the flow — so if a task asks for
  * "a coded agent", what it is asking you to get right is the RESOURCE you point at.

package/dist/core/binding-identity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What a `.flow` binding row binds, as one comparable key.
+ *
+ * The key is `(resource, resourceKey, resourceSubType, propertyAttribute, name)`.
+ * It is NOT the row `id`: nodes never reference a row by id, and the two
+ * producers name rows differently (compile writes `b<Name><Prop>`, the canvas a
+ * random 9-character id), so two rows for the same property never share an id.
+ *
+ * `name` is part of the key. For a connection row it is the definition's own
+ * `<bindings.NAME>` placeholder, and two definitions sharing one connection
+ * spell it differently (`uipath-uipath-http connection`, `uipath-salesforce-slack
+ * connection`); each needs its own row, which is how compile keys them
+ * (`serialize.ts`, flow-builder-sdk#865). Process and queue rows carry
+ * `name === propertyAttribute`, so the extra field does not split them.
+ *
+ * Example: `{ resource: 'process', resourceKey: 'e05d...', resourceSubType: 'Flow',
+ * propertyAttribute: 'name', name: 'name' }` has the same identity whether its
+ * id is `bCalleeName` or `b7CE8ALjn`.
+ */
+export declare function bindingIdentity(b: {
+    readonly [k: string]: unknown;
+}): string;

package/dist/core/binding-identity.js

@@ -0,0 +1,28 @@
+/**
+ * What a `.flow` binding row binds, as one comparable key.
+ *
+ * The key is `(resource, resourceKey, resourceSubType, propertyAttribute, name)`.
+ * It is NOT the row `id`: nodes never reference a row by id, and the two
+ * producers name rows differently (compile writes `b<Name><Prop>`, the canvas a
+ * random 9-character id), so two rows for the same property never share an id.
+ *
+ * `name` is part of the key. For a connection row it is the definition's own
+ * `<bindings.NAME>` placeholder, and two definitions sharing one connection
+ * spell it differently (`uipath-uipath-http connection`, `uipath-salesforce-slack
+ * connection`); each needs its own row, which is how compile keys them
+ * (`serialize.ts`, flow-builder-sdk#865). Process and queue rows carry
+ * `name === propertyAttribute`, so the extra field does not split them.
+ *
+ * Example: `{ resource: 'process', resourceKey: 'e05d...', resourceSubType: 'Flow',
+ * propertyAttribute: 'name', name: 'name' }` has the same identity whether its
+ * id is `bCalleeName` or `b7CE8ALjn`.
+ */
+export function bindingIdentity(b) {
+    return JSON.stringify([
+        b.resource ?? null,
+        b.resourceKey ?? null,
+        b.resourceSubType ?? null,
+        b.propertyAttribute ?? null,
+        b.name ?? null,
+    ]);
+}