@uipath/maestro-builder-sdk 6.18.10 → 6.20.0

package/dist/check.js

@@ -5,11 +5,12 @@
  * duplicate step names, references to undeclared variables/steps, empty branch
  * arms, and missing terminals.
  */
-import { Expr, SCHEDULE_PRESETS, DELAY_PRESETS, VARIANT_OPERATION, parseIxpProjectType, flatNameOf, flatNameSegmentsOf, FLAT_SEP } from './flow-sdk.js';
+import { Expr, SCHEDULE_PRESETS, parseIxpProjectType, flatNameOf, flatNameSegmentsOf, FLAT_SEP } from './flow-sdk.js';
 import { FlowNode } from './core/node-classes.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
 import { definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
 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,13 +20,16 @@ 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';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
 import { planFlowGlobals, planSharedInputs, sharedInputRoots } from './flow-variables.js';
 import { ownEntry } from './core/own-entry.js';
+import { FLOW_NODE_TYPES } from './flow-node-registry.js';
+import { resolveVersion } from './core/nodes/versioned.js';
+import { declaredErrorPortRefusal } from './core/error-port.js';
 export function check(built, opts = {}) {
     let diags = [];
     const uses = collectConnectionUses(() => { diags = checkFlow(built, [], opts); });
@@ -115,6 +119,12 @@ function checkFlow(built, ancestors, opts = {}) {
     ]);
     const outputType = new Map(built.outputs.map((x) => [x.name, String(x.type)]));
     const stepNames = new Set();
+    // Steps whose kind is a registered node type (flow-node-registry.ts), by name:
+    // their node-local rules, expressions and output contract come from the node
+    // type, and their family's rules run over all of them after the walk.
+    const registeredSteps = new Map();
+    /** Steps of a registered kind whose version did not resolve (NODE_VERSION_UNREGISTERED), so a family rule can stay silent about them. */
+    const unresolvedSteps = new Set();
     /**
      * Every expression the flow carries, with the step that failed when the
      * expression sits inside that step's error handler. The failed step's own
@@ -133,8 +143,6 @@ function checkFlow(built, ancestors, opts = {}) {
     // `core.logic.merge` definition declares no outputs at all (see
     // PARALLEL_HAS_NO_OUTPUT below).
     const parallelNames = new Set();
-    const delayNames = new Set();
-    const dataFabricReads = new Set();
     // Per-outcome routing bookkeeping: which hitl steps opted into outcome ports
     // (and their declared outcome ids), and which ids actually got a route.
     const hitlOutcomeSteps = new Map();
@@ -151,22 +159,6 @@ function checkFlow(built, ancestors, opts = {}) {
     // waits until the expressions are collected (see HITL_OUTCOMES_UNREACHABLE
     // below).
     const hitlChoiceNoPorts = new Map();
-    // Data Fabric writes that target a record `{ fromRead: '<step>' }` — update and
-    // delete share the selector, so they share the check.
-    const dataFabricRefs = [];
-    // Delete step names. `core.datafabric.delete` is the one verb of the family
-    // whose definition declares NO outputDefinition, so `$vars.<delete>.output` is
-    // undefined at run time (see DATAFABRIC_DELETE_HAS_NO_OUTPUT below).
-    const dataFabricDeletes = new Set();
-    // Reads that return a LIST. A multi-record read is refused as a write target
-    // (see DATAFABRIC_FROMREAD_MULTIPLE below) — the serializer emits a plain
-    // no-op task for the write, and nothing at any rung reports it.
-    const dataFabricMultiReads = new Set();
-    // Placeholder (`mock()`) step names. The platform's `core.logic.mock` declares
-    // one output whose `source` is the literal `"null"` — it publishes nothing —
-    // so `$vars.<mock>.output` is null at run time, always (see
-    // MOCK_HAS_NO_OUTPUT below).
-    const mockNames = new Set();
     // Terminate step names. A terminate declares no action output in any registry
     // version, so `$vars.<terminate>` is undefined at run time. The terminal
     // flow-output mappings the serializer emits are validation metadata, not a
@@ -188,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,
@@ -206,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
@@ -260,7 +270,7 @@ function checkFlow(built, ancestors, opts = {}) {
                 declared.add(s.name); // a step's output is referenceable by name
             }
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'error')
-                checkOnError(s, prevPortSource, diags);
+                checkOnError(s, prevPortSource, diags, prevPortSource && registeredSteps.get(prevPortSource.name));
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port.startsWith('branch-')) {
                 const want = s.port.slice('branch-'.length);
                 const prevSpec = prevAction?.spec;
@@ -320,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,
@@ -363,7 +373,17 @@ function checkFlow(built, ancestors, opts = {}) {
             if (s.kind === 'action') {
                 prevAction = s;
                 prevPortSource = s;
-                collectActionExprs(s, exprs, errorSource);
+                const registered = registeredKind(s.spec);
+                if (registered) {
+                    const placed = checkRegisteredStep(registered, s, exprs, errorSource, opts, diags, typeOf, triggerId);
+                    if (placed)
+                        registeredSteps.set(s.name, placed);
+                    else
+                        unresolvedSteps.add(s.name);
+                }
+                else {
+                    collectActionExprs(s, exprs, errorSource);
+                }
                 if (s.spec.kind === 'connector') {
                     connectorSteps.set(s.name, s.spec);
                     checkConnectorLookups(s.name, s.spec, opts, diags);
@@ -380,8 +400,6 @@ function checkFlow(built, ancestors, opts = {}) {
                     }
                     checkContribution(maybeCustom, s.options?.version, s.name, own.some((d) => d.severity === 'error'), diags);
                 }
-                if (s.spec.kind === 'transform')
-                    checkTransform(s.name, s.spec.inputs, diags, typeOf, triggerId);
                 if (s.spec.kind === 'http') {
                     checkHttp(s.name, s.spec.inputs, diags);
                     // Only a complete pair: an empty half is HTTP_MANAGED_BINDING_INCOMPLETE, which
@@ -419,21 +437,13 @@ function checkFlow(built, ancestors, opts = {}) {
                         }
                     }
                 }
-                if (s.spec.kind === 'script')
-                    checkScript(s.name, s.spec.inputs, diags);
-                if (s.spec.kind === 'delay') {
-                    checkDelay(s.name, s.spec.inputs, diags);
-                    delayNames.add(s.name);
-                }
-                if (s.spec.kind === 'mock')
-                    mockNames.add(s.name);
                 // `.stepSwitch` routes its exits as ARMS, so the `.stepToList` bookkeeping
                 // would report every one of them unrouted. STEP_SWITCH_EXIT_UNROUTED is
                 // that step's version of the same question.
                 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',
                     })));
                 }
@@ -451,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,
@@ -497,71 +508,6 @@ function checkFlow(built, ancestors, opts = {}) {
                         outputReaders.set(stepName, (field, rest, at, d) => rule(stepName, field, rest, inputs, at, d));
                     }
                 }
-                if (s.spec.kind === 'documentClassify' || s.spec.kind === 'dynamicExtract') {
-                    const fr = s.spec.inputs.fileRef;
-                    const empty = fr === undefined || fr === null || (typeof fr === 'string' && fr.trim() === '');
-                    if (empty) {
-                        diags.push({
-                            level: 'error', code: 'DOC_NO_FILEREF', step: s.name,
-                            message: `"${s.name}" has no fileRef — nothing to ${s.spec.kind === 'documentClassify' ? 'classify' : 'extract from'}. Reference a file input or an upstream attachment.`,
-                        });
-                    }
-                    if (s.spec.kind === 'dynamicExtract' && s.spec.inputs.schema !== undefined
-                        && (typeof s.spec.inputs.schema !== 'object' || Array.isArray(s.spec.inputs.schema))) {
-                        diags.push({
-                            level: 'error', code: 'EXTRACT_SCHEMA_SHAPE', step: s.name,
-                            message: `"${s.name}"'s schema must be an object (the inline extraction schema document).`,
-                        });
-                    }
-                }
-                if (s.spec.kind === 'dataFabricRead' || s.spec.kind === 'dataFabricCreate'
-                    || s.spec.kind === 'dataFabricUpdate' || s.spec.kind === 'dataFabricDelete') {
-                    if (!String(s.spec.inputs.entity ?? '').trim()) {
-                        diags.push({
-                            level: 'error', code: 'DATAFABRIC_NO_ENTITY', step: s.name,
-                            message: `"${s.name}" names no Data Fabric entity. Set { entity: '<entity name>' }.`,
-                        });
-                    }
-                    if (s.spec.kind === 'dataFabricRead') {
-                        dataFabricReads.add(s.name);
-                        if (s.spec.inputs.resultMode === 'multiple')
-                            dataFabricMultiReads.add(s.name);
-                        checkDataFabricQuery(s.name, s.spec.inputs, diags);
-                    }
-                    if (s.spec.kind === 'dataFabricCreate') {
-                        // Not the same failure as an empty update: a BLANK value is omitted
-                        // from the insert so the column default applies, so an all-blank
-                        // `fieldValues` serializes to an empty body and runs green having
-                        // inserted nothing. The node's schema rejects that — and the fix is
-                        // a real value, never a placeholder to satisfy the rule.
-                        const written = Object.values(s.spec.inputs.values ?? {})
-                            .filter((v) => (v instanceof Expr ? true : String(v ?? '').trim() !== ''));
-                        if (written.length === 0) {
-                            diags.push({
-                                level: 'error', code: 'DATAFABRIC_EMPTY_VALUES', step: s.name,
-                                message: `"${s.name}" sets no column to a non-blank value, so it would insert nothing and run green. `
-                                    + 'The node\'s schema rejects that — give a real column a real value rather than a placeholder.',
-                            });
-                        }
-                        checkDataFabricColumns(s.name, Object.keys(s.spec.inputs.values ?? {}), 'values', diags);
-                    }
-                    if (s.spec.kind === 'dataFabricUpdate') {
-                        if (Object.keys(s.spec.inputs.set ?? {}).length === 0) {
-                            diags.push({
-                                level: 'error', code: 'DATAFABRIC_EMPTY_SET', step: s.name,
-                                message: `"${s.name}" writes no columns — { set } is empty, so the update would no-op green.`,
-                            });
-                        }
-                        checkDataFabricColumns(s.name, Object.keys(s.spec.inputs.set ?? {}), 'set', diags);
-                    }
-                    checkDataFabricScope(s.name, s.spec.inputs, diags);
-                    if (s.spec.kind === 'dataFabricUpdate' || s.spec.kind === 'dataFabricDelete') {
-                        const factory = s.spec.kind === 'dataFabricUpdate' ? 'dataFabricUpdate' : 'dataFabricDelete';
-                        dataFabricRefs.push({ step: s.name, factory, record: s.spec.inputs.record });
-                        if (s.spec.kind === 'dataFabricDelete')
-                            dataFabricDeletes.add(s.name);
-                    }
-                }
                 if (s.spec.kind === 'ixpExtract')
                     checkIxpExtract(s.name, s.spec.inputs, diags);
                 if (s.spec.kind === 'waitEvent') {
@@ -637,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))
@@ -675,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
@@ -723,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');
@@ -839,30 +813,7 @@ function checkFlow(built, ancestors, opts = {}) {
         }
     }
     reportUnreachableHitlOutcomes(hitlChoiceNoPorts, exprs, diags);
-    for (const { step, factory, record } of dataFabricRefs) {
-        const fromRead = record?.fromRead;
-        if (typeof fromRead !== 'string')
-            continue;
-        if (!dataFabricReads.has(fromRead)) {
-            diags.push({
-                level: 'error', code: 'DATAFABRIC_FROMREAD_UNKNOWN', step,
-                message: `"${step}" targets record: { fromRead: ${JSON.stringify(fromRead)} }, but no dataFabricRead step has that name.`,
-                suggestion: `${factory}({ …, record: { byId: '<record id>' } })`,
-            });
-            continue;
-        }
-        // A LIST is not a write target: the serializer refuses it and emits a plain
-        // no-op task, so the flow validates, runs green, and writes nothing.
-        if (dataFabricMultiReads.has(fromRead)) {
-            diags.push({
-                level: 'error', code: 'DATAFABRIC_FROMREAD_MULTIPLE', step,
-                message: `"${step}" targets record: { fromRead: ${JSON.stringify(fromRead)} }, but "${fromRead}" is a `
-                    + "resultMode: 'multiple' query. A multi-record read is refused as a write target — the step compiles to "
-                    + 'a no-op and the run goes green having written nothing.',
-                suggestion: `loop the results and target each record with ${factory}({ …, record: { byId: … } })`,
-            });
-        }
-    }
+    checkRegisteredFamilies(registeredSteps, unresolvedSteps, stepNames, diags);
     // Entry points: unique roots with valid triggers, colliding with nothing.
     const epIds = new Set();
     for (const ep of built.entryPoints ?? []) {
@@ -1144,6 +1095,16 @@ function checkFlow(built, ancestors, opts = {}) {
                 });
                 continue;
             }
+            // A registered node type declares what its output is; `none` reports here,
+            // at the same point as the per-family no-output rules below.
+            const placed = registeredSteps.get(name);
+            if (placed) {
+                const contract = placed.impl.output(placed.spec);
+                if (contract.kind === 'none') {
+                    diags.push(catalogued(placed.entry, step, contract.code, contract.message({ node: name, ref: `$vars.${name}${field ? '.' + field : ''}`, reader: step })));
+                    continue;
+                }
+            }
             // A switch only routes; it has no output of its own, so any read of it is
             // undefined at run time. Point the author at the arm's step instead.
             if (switchNames.has(name)) {
@@ -1186,62 +1147,6 @@ function checkFlow(built, ancestors, opts = {}) {
                 });
                 continue;
             }
-            // A Data Fabric delete is the one verb of that family whose definition
-            // declares no outputDefinition at all — the record is gone, so there is
-            // nothing to publish. Read the record on the step that FOUND it instead,
-            // which on the `{ fromRead }` form is already in the flow.
-            if (dataFabricDeletes.has(name)) {
-                diags.push({
-                    level: 'error',
-                    code: 'DATAFABRIC_DELETE_HAS_NO_OUTPUT',
-                    message: `Delete "${name}" produces no output, but "$vars.${name}${field ? '.' + field : ''}" reads one in "${step}". `
-                        + 'A Data Fabric delete declares no outputs — take the value off the dataFabricRead step that found the record, before the delete.',
-                    step,
-                });
-                continue;
-            }
-            if (delayNames.has(name)) {
-                diags.push({
-                    level: 'error',
-                    code: 'DELAY_HAS_NO_OUTPUT',
-                    message: `Delay "${name}" produces no output, but "$vars.${name}${field ? '.' + field : ''}" reads one in "${step}". `
-                        + 'A delay only waits — read the step that computed the value instead.',
-                    step,
-                });
-                continue;
-            }
-            // A `mock()` is a PLACEHOLDER: `core.logic.mock`'s definition declares one
-            // output whose `source` is the literal `"null"`, so the value is null at run
-            // time whatever the flow does. Unlike the four rules above, the node DOES
-            // declare an output slot — which is exactly why the read is silent: it
-            // resolves in the designer, it resolves in `variables.nodes`, and it hands
-            // the downstream step a null.
-            //
-            // WHY THIS RULE LIVES HERE, in the authoring checker rather than in a
-            // pass over the compiled artifact (the measurement,
-            // convention #191). Reading a placeholder's output is the ARCHIVE's
-            // dominant idiom, not a rarity: 55 of the 62 archived mock-carrying
-            // artifacts do it — 110 read sites, 87 of them inside a script's body and
-            // 19 in a decision's expression — and **39 of those 55 come from runs that
-            // scored 1.0**. That is an author writing the downstream code for the real
-            // node the placeholder stands in for, and a `.flow`-level rule refusing it
-            // would refuse the deployed corpus (lesson 47). An SDK author is in the
-            // other position: they wrote `mock()` here, in this file, and the SDK can
-            // say at compile time that the read is dead.
-            //   Measured 2026-08-02 over 4,033 distinct archived artifacts —
-            //   runs/flow-sdk-cleanup-2026-08-02/step0/mock-output-read-sites.txt.
-            if (mockNames.has(name)) {
-                diags.push({
-                    level: 'error',
-                    code: 'MOCK_HAS_NO_OUTPUT',
-                    message: `Placeholder "${name}" publishes nothing, but "$vars.${name}${field ? '.' + field : ''}" reads it in "${step}". `
-                        + 'A mock() is a marker for a node that does not exist yet — its output is null at run time, always. '
-                        + 'Keep the placeholder while the real node does not exist, and have the reader use a value you supply instead (a flow input, as example/ClaimScaffold.flow.ts does). '
-                        + 'Replace the placeholder only with the real node, once `registry search` finds it; a script returning fixed values is not the real node.',
-                    step,
-                });
-                continue;
-            }
             // A subflow hands back an OBJECT keyed by the child flow's declared
             // outputs — even when the child declares exactly one. So the reference
             // needs the output's NAME (`out('call', 'reversed')`), and the name has to
@@ -1499,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);
@@ -1985,26 +1897,6 @@ function checkTrigger(spec, diags, opts = {}, entryPointId) {
             + `comes round. Use a non-zero interval.`, `every: 'R/PT1H'`);
     }
 }
-/**
- * An EXACT ISO-8601 duration: weeks/days plus a time part, at least one
- * component. Copied in shape from the delay definition's own
- * `timerValue.pattern`, minus the years and months — see DELAY_CALENDAR below.
- */
-const DURATION_RE = /^P(?!$)(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
-/** Grammatical ISO-8601 duration, including the calendar-relative parts. */
-const ANY_DURATION_RE = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
-/** Natural-language guesses an author might reach for, mapped to a duration. */
-const DURATION_WORDS = [
-    ['second', 'PT30S'], ['minute', 'PT15M'], ['hour', 'PT1H'],
-    ['day', 'P1D'], ['daily', 'P1D'], ['week', 'P1W'], ['weekly', 'P1W'],
-];
-/**
- * Diagnose a `delay` step's wait.
- *
- * Rung 1 is the only place an author hears about a bad duration in time to fix
- * it cheaply. Anything downstream speaks in terms of `timerPreset`/`timerValue`,
- * the two fields the serializer writes, rather than the one field the author typed.
- */
 /** A release key is a GUID — the shape 45/45 deployed rpa node types carry. */
 /**
  * The DECLARED name a single reference resolves to, or undefined.
@@ -2805,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') {
@@ -3278,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 — `
@@ -3611,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;
@@ -3870,64 +3794,6 @@ function checkQueueItem(step, inputs, diags) {
 }
 /** The three priorities `core.action.queue.create[-and-wait]`'s form offers. */
 const QUEUE_PRIORITIES = ['Low', 'Normal', 'High'];
-function checkDelay(step, inputs, diags) {
-    const at = (code, message, suggestion) => {
-        diags.push({ level: 'error', code, message, step, ...(suggestion ? { suggestion } : {}) });
-    };
-    const untilRaw = inputs?.until;
-    if (typeof untilRaw === 'string' && untilRaw.trim() !== '') {
-        // The absolute-date arm: an ISO-8601 date-time, e.g. 2026-09-01T09:00:00Z.
-        const until = untilRaw.trim();
-        if (!/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?)?$/.test(until)) {
-            at('DELAY_UNTIL_NOT_ISO', `Delay "${step}"'s until ${JSON.stringify(untilRaw)} is not an ISO-8601 date-time. `
-                + `Use e.g. '2026-09-01T09:00:00Z' (a timezone-less value is read in the tenant's zone).`, `until: '2026-09-01T09:00:00Z'`);
-        }
-        return;
-    }
-    const raw = inputs?.duration;
-    if (raw === undefined || raw === null || (typeof raw === 'string' && raw.trim() === '')) {
-        at('DELAY_NO_DURATION', `Delay "${step}" has no \`duration\`, so it carries no wait at all and the flow runs straight `
-            + `past it. Give it an ISO-8601 duration — ${DELAY_PRESETS.slice(0, 8).join(', ')} … are the `
-            + `designer's presets, and any other exact duration works too.`, `duration: 'PT15M'`);
-        return;
-    }
-    const d = String(raw).trim();
-    if (!ANY_DURATION_RE.test(d)) {
-        at('DELAY_NOT_ISO', `Delay "${step}"'s duration ${JSON.stringify(raw)} is not an ISO-8601 duration. The format is `
-            + `"P" plus a date part and/or "T" plus a time part — PT30S, PT15M, PT2H, P1D, P1W. Note the `
-            + `"T": P1M is a MONTH, PT1M is a minute.`, nearestDuration(d));
-        return;
-    }
-    if (!/[1-9]/.test(d)) {
-        at('DELAY_ZERO', `Delay "${step}"'s duration ${JSON.stringify(d)} is zero-length, so the step waits for no time `
-            + `at all. Use a non-zero duration, or drop the step.`, `duration: 'PT15M'`);
-        return;
-    }
-    // Grammatical, and the platform runs it — but a month is not a fixed number
-    // of milliseconds, so NO local rung can run the flow at all.
-    // Rejected here rather than approximated: guessing 30 days would
-    // put a silent disagreement with the deployed engine back into the pipeline.
-    if (!DURATION_RE.test(d)) {
-        at('DELAY_CALENDAR', `Delay "${step}"'s duration ${JSON.stringify(d)} is calendar-relative: how long a month or a `
-            + `year is depends on when it starts. The platform resolves that at run time, but the local `
-            + `timer takes a fixed millisecond count, so this flow could not be replayed or run offline.`, `duration: 'P30D'`);
-    }
-}
-/** Best guess at what the author meant, for a `DELAY_NOT_ISO` suggestion. */
-function nearestDuration(d) {
-    // The likeliest slip: a time-part duration written without its "T".
-    if (/^P\d+[HMS]$/.test(d) && ANY_DURATION_RE.test(`PT${d.slice(1)}`))
-        return `duration: 'PT${d.slice(1)}'`;
-    const lower = d.toLowerCase();
-    const n = /(\d+)/.exec(lower)?.[1];
-    const word = DURATION_WORDS.find(([w]) => lower.includes(w));
-    if (!word)
-        return undefined;
-    if (!n)
-        return `duration: '${word[1]}'`;
-    const unit = word[1].replace(/\d+/, '');
-    return `duration: '${unit.startsWith('PT') ? `PT${n}${unit.slice(2)}` : `P${n}${unit.slice(1)}`}'`;
-}
 /** Best guess at what the author meant, for a `SCHEDULE_NOT_ISO` suggestion. */
 function nearestInterval(every) {
     // By far the likeliest slip: a correct duration missing the "R/" repeat marker.
@@ -4052,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);
@@ -4249,70 +4115,6 @@ const RETRY_COUNT_SOFT_MAX = 5;
  * not a shorter timeout, it is a value the request node fails to configure with,
  * and nothing downstream of `check` would say so in the author's own vocabulary.
  */
-/** The type vocabulary a script's `returns` may name — what the wire format accepts. */
-const SCRIPT_RETURN_TYPES = new Set(['string', 'number', 'boolean', 'object', 'array']);
-/**
- * A script step's `returns` — the author overriding what the body looks like.
- *
- * TypeScript already refuses a bad value at the call site, so this is the fence
- * for everything that does NOT go through the type checker: a `.flow.ts` loaded
- * as plain JS, a generated flow, a value read from config. Both mistakes below
- * reach the emitted file silently and are then the designer's problem instead of
- * the author's, which is precisely the failure this whole feature exists to undo.
- */
-function checkScript(step, inputs, diags) {
-    const returns = inputs?.returns;
-    if (returns === undefined)
-        return;
-    if (typeof returns === 'string') {
-        if (!SCRIPT_RETURN_TYPES.has(returns)) {
-            diags.push({
-                level: 'error',
-                code: 'SCRIPT_RETURNS_UNKNOWN_TYPE',
-                message: `Script step "${step}" declares \`returns: ${JSON.stringify(returns)}\`, which is not a type the `
-                    + `wire format knows. Use one of ${[...SCRIPT_RETURN_TYPES].map((t) => `"${t}"`).join(', ')}, or a `
-                    + `field map like \`{ total: "number" }\` to name an object's fields.`,
-                step,
-            });
-        }
-        return;
-    }
-    if (typeof returns !== 'object' || returns === null || Array.isArray(returns)) {
-        diags.push({
-            level: 'error',
-            code: 'SCRIPT_RETURNS_UNKNOWN_TYPE',
-            message: `Script step "${step}"'s \`returns\` is ${JSON.stringify(returns)}. It takes either a type name or a `
-                + `map of field names to types (\`{ total: "number" }\`).`,
-            step,
-        });
-        return;
-    }
-    const fields = returns;
-    // Same call as `APIWF_EMPTY_RETURNS` one surface over: an empty map declares
-    // nothing, emits nothing, and reads exactly like omitting the key — so it is
-    // almost always a half-finished edit rather than a statement.
-    if (Object.keys(fields).length === 0) {
-        diags.push({
-            level: 'warning',
-            code: 'SCRIPT_EMPTY_RETURNS',
-            message: `Script step "${step}" declares \`returns: {}\`, which names no fields and emits nothing — the same `
-                + `as omitting it. Name the fields, or drop the key and let the body speak for itself.`,
-            step,
-        });
-        return;
-    }
-    for (const [name, type] of Object.entries(fields)) {
-        if (typeof type !== 'string' || !SCRIPT_RETURN_TYPES.has(type)) {
-            diags.push({
-                level: 'error',
-                code: 'SCRIPT_RETURNS_UNKNOWN_TYPE',
-                message: `Script step "${step}" declares field "${name}" as ${JSON.stringify(type)}, which is not a type the `
-                    + `wire format knows. Use one of ${[...SCRIPT_RETURN_TYPES].map((t) => `"${t}"`).join(', ')}.`,
-                step,
-            });
-        }
-    }
-}
 function checkHttp(step, inputs, diags) {
     // `core.action.http` is retired on the platform side: after `registry pull
     // --force` the tenant serves only `core.action.http.v2` (2.3), and a
@@ -4450,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'`;
 }
@@ -4467,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 }`.
@@ -4548,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.
@@ -4734,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
@@ -4776,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 `
@@ -4907,211 +4728,6 @@ function checkHitlRead(name, field, rest, form, step, diags) {
         ...(nearest !== undefined ? { suggestion: `out('${name}', '${nearest}')` } : {}),
     });
 }
-function checkTransform(step, inputs, diags, typeOf = new Map(), triggerId = 'start') {
-    const at = (code, message, suggestion) => {
-        diags.push({ level: 'error', code, message, step, ...(suggestion ? { suggestion } : {}) });
-    };
-    // ── collection must be a bare variable path ──
-    const collection = inputs?.collection;
-    if (collection === undefined || collection === null) {
-        at('TRANSFORM_NO_COLLECTION', `Transform "${step}" has no collection. Point it at the variable or step output holding the array.`, `collection: v('catalog')`);
-    }
-    else if (!(collection instanceof Expr)) {
-        // Types are stripped at run time, so `collection: [{…}]` or
-        // `collection: 'catalog'` reaches here as a raw value.
-        at('TRANSFORM_COLLECTION_NOT_REF', `Transform "${step}" was given a ${Array.isArray(collection) ? 'raw array' : `raw ${typeof collection}`} as its `
-            + `collection. That field is a variable PATH — the runtime turns the string into a lookup, so a value there `
-            + `resolves to nothing and the transform silently sees an empty collection.`, typeof collection === 'string' ? `collection: v('${collection}')` : `collection: v('<varName>')`);
-    }
-    else if (collection.literal) {
-        at('TRANSFORM_COLLECTION_LITERAL', `Transform "${step}" has a literal collection. Inline data cannot be a path — keep the array in a variable `
-            + `default (\`.var('items', types.array, [...])\`) and reference it, or read an upstream step's output.`, `collection: v('items')`);
-    }
-    else if (!/^\$vars\.[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/.test(collection.js.trim())) {
-        // A computed expression (js`…`, tmpl`…`, `.concat(…)`) is the trap that
-        // survives every local rung: a local run resolves it to a value, so
-        // it runs correctly there and resolves to NOTHING once deployed, where the
-        // string is used as a lookup path.
-        at('TRANSFORM_COLLECTION_NOT_PATH', `Transform "${step}"'s collection must be a plain reference, but it is the expression `
-            + `"${collection.js.trim().slice(0, 60)}". The deployed runtime uses that string as a lookup PATH, so a `
-            + `computed expression resolves to nothing there even though it runs locally. Compute it in a script step `
-            + `first, then point the transform at that step's output.`, `collection: out('<scriptStep>')`);
-    }
-    else {
-        // A collection that is not an array is PASSED THROUGH untouched — no error,
-        // no operations applied (faithful to v1). The result is a transform that
-        // looks like it ran and changed nothing.
-        // Only a DECLARED scalar can be judged here: a step output's type is not
-        // known offline, so this stays quiet about those rather than guessing.
-        const refName = declaredRefName(collection.js, triggerId);
-        const declaredType = refName ? typeOf.get(refName) : undefined;
-        if (declaredType && ['string', 'number', 'boolean'].includes(declaredType)) {
-            at('TRANSFORM_COLLECTION_SCALAR', `Transform "${step}"'s collection is "${refName}", declared as ${declaredType}. A transform runs its `
-                + `operations over an ARRAY; anything else is passed through untouched — no error, nothing applied — so `
-                + `the step would look like it ran and change nothing.`, `Declare it as types.array, or point the collection at the array field: collection: out('<step>', '<field>')`);
-        }
-    }
-    // ── the operation chain ──
-    const ops = inputs?.operations;
-    if (!Array.isArray(ops) || ops.length === 0) {
-        at('TRANSFORM_NO_OPERATIONS', `Transform "${step}" has no operations, so it passes its collection straight through. Add at least one `
-            + `filter / map / groupBy operation, or drop the node.`, `operations: [{ type: 'filter', filters: [{ field: 'status', condition: 'equals', value: 'open' }] }]`);
-        return;
-    }
-    checkVariant(step, inputs, ops, at);
-    ops.forEach((op, i) => {
-        const where = `operations[${i}]`;
-        // Read the discriminant before the narrowing below exhausts the union — at
-        // run time it can be anything (an author typo survives type erasure).
-        const kind = op?.type;
-        if (op?.type === 'filter') {
-            if (!Array.isArray(op.filters) || op.filters.length === 0) {
-                at('TRANSFORM_EMPTY_FILTER', `Transform "${step}" ${where} is a filter with no rules — the runtime passes every item through it.`);
-                return;
-            }
-            for (const [j, f] of op.filters.entries()) {
-                if (!f?.field && f?.field !== '')
-                    at('TRANSFORM_FILTER_NO_FIELD', `Transform "${step}" ${where}.filters[${j}] has no field, so the rule is dropped and the filter `
-                        + `matches everything.`);
-                checkVocab(step, `${where}.filters[${j}].condition`, f?.condition, FILTER_CONDITIONS, 'filter condition', 'passes every item through the rule', diags);
-                if (typeof f?.value === 'string' && LOOKS_LIKE_EXPRESSION.test(f.value.trim()))
-                    at('TRANSFORM_FILTER_VALUE_EXPR', `Transform "${step}" ${where}.filters[${j}] compares against ${JSON.stringify(f.value)}. Filter values `
-                        + `are LITERAL only — the runtime evaluates nothing here, so every item would be compared against that `
-                        + `text and the filter would return nothing. Use a literal, or do the comparison in a script step.`, `value: 500`);
-                // `contains` is TWO operators wearing one name — the runtime does
-                // `Array.includes` when the FIELD holds an array and `String.includes`
-                // otherwise, faithful to v1. Which
-                // one runs is decided by the data, so nothing static can pick for you —
-                // but an ARRAY on the compare side is wrong under both readings
-                // (`['a','b']` is stringified to `a,b` for the substring test, and
-                // `includes` looks for the array itself as one element), and it is the
-                // shape an author reaches for when they mean "any of these".
-                if ((f?.condition === 'contains' || f?.condition === 'not_contains') && Array.isArray(f?.value))
-                    at('TRANSFORM_CONTAINS_ARRAY_VALUE', `Transform "${step}" ${where}.filters[${j}] uses "${f.condition}" against an ARRAY. "contains" compares `
-                        + `ONE value: if the item's field holds an array it tests membership of that value, otherwise it tests `
-                        + `for that value as a substring — either way an array on the right matches nothing, silently. For `
-                        + `"any of these", use one rule per value with the filter's "or" operation.`, `condition: 'contains', value: ${JSON.stringify(f.value[0] ?? 'x')}`);
-            }
-            return;
-        }
-        if (op?.type === 'map') {
-            if (!Array.isArray(op.mappings) || op.mappings.length === 0) {
-                at('TRANSFORM_EMPTY_MAP', `Transform "${step}" ${where} is a map with no mappings — with keepOriginalFields off that turns every `
-                    + `item into {}.`);
-                return;
-            }
-            for (const [j, m] of op.mappings.entries()) {
-                if (!m?.field)
-                    at('TRANSFORM_MAP_NO_FIELD', `Transform "${step}" ${where}.mappings[${j}] has no field, so nothing is carried into the output.`);
-                // Omitted is fine — it defaults to `copy`.
-                if (m?.transformation !== undefined)
-                    checkVocab(step, `${where}.mappings[${j}].transformation`, m.transformation, TRANSFORMATIONS, 'transformation', 'copies the value unchanged', diags);
-            }
-            return;
-        }
-        if (op?.type === 'groupBy') {
-            if (!op.groupByField)
-                at('TRANSFORM_NO_GROUP_FIELD', `Transform "${step}" ${where} is a groupBy with no groupByField, so every item lands in one anonymous `
-                    + `group.`);
-            for (const [j, a] of (op.aggregations ?? []).entries()) {
-                if (!a?.alias?.trim())
-                    at('TRANSFORM_AGG_NO_ALIAS', `Transform "${step}" ${where}.aggregations[${j}] has no alias. The runtime drops an unaliased `
-                        + `aggregation, so its result would simply be absent from the output.`);
-                if (a?.operation !== 'count' && !a?.field?.trim())
-                    at('TRANSFORM_AGG_NO_FIELD', `Transform "${step}" ${where}.aggregations[${j}] is "${a?.operation}" with no field. Only "count" `
-                        + `works without one; the runtime drops the rest, so the aggregate would be missing from the output.`);
-                checkVocab(step, `${where}.aggregations[${j}].operation`, a?.operation, AGGREGATION_OPERATIONS, 'aggregation operation', 'yields null for that aggregate', diags);
-            }
-            return;
-        }
-        at('TRANSFORM_UNKNOWN_OP', `Transform "${step}" ${where} has type ${JSON.stringify(kind)}. The runtime skips an operation it does `
-            + `not recognize, so the collection would pass through unchanged. Use 'filter', 'map', or 'groupBy'.`);
-    });
-}
-/**
- * Diagnose the `variant` discriminator on a transform step.
- *
- * A variant emits a single-purpose node type (`core.action.transform.filter`,
- * `.map`, `.group-by`) instead of the generic one. The platform runs all four
- * node types through the SAME script generators and dispatches on the
- * OPERATION's type, never the node's — so a mismatch here does not fault and
- * does not change the answer. It produces a node that lies: a `.filter` node
- * that actually maps, whose operation the designer's filter editor cannot even
- * show. That is exactly the class this SDK catches at rung 1, because no rung
- * below it ever will.
- */
-function checkVariant(step, inputs, ops, at) {
-    const variant = inputs?.variant;
-    if (variant === undefined || variant === null)
-        return; // generic — chains freely
-    const variants = Object.keys(VARIANT_OPERATION);
-    if (typeof variant !== 'string' || !variants.includes(variant)) {
-        at('TRANSFORM_VARIANT_UNKNOWN', `Transform "${step}" has variant ${JSON.stringify(variant)}, which is not a Transform node type. `
-            + `The emitted node would be "core.action.transform.${String(variant)}", which no runtime resolves. `
-            + `Valid: ${variants.join(', ')} — or omit \`variant\` for the generic chaining Transform.`, nearestIn(variant, variants));
-        return;
-    }
-    const expected = VARIANT_OPERATION[variant];
-    if (ops.length !== 1) {
-        at('TRANSFORM_VARIANT_ONE_OP', `Transform "${step}" is the "${variant}" variant but carries ${ops.length} operations. A variant node runs `
-            + `exactly one — the designer's ${variant} editor shows a single ${expected} operation and nothing else. `
-            + `Drop \`variant\` to chain them in one generic Transform, or split them across one node per step.`);
-        return;
-    }
-    const got = ops[0]?.type;
-    if (got !== expected) {
-        at('TRANSFORM_VARIANT_OP_MISMATCH', `Transform "${step}" is the "${variant}" variant but its operation is ${JSON.stringify(got)}, not `
-            + `"${expected}". The node type does not drive the runtime — the OPERATION does — so this would emit a `
-            + `node labelled "${variant}" that actually does ${JSON.stringify(got)}, and the designer's ${variant} `
-            + `editor could not show it. Match them, or drop \`variant\` for the generic Transform.`, typeof got === 'string' && Object.values(VARIANT_OPERATION).includes(got)
-            ? `variant: '${variants.find((v) => VARIANT_OPERATION[v] === got)}'`
-            : `type: '${expected}'`);
-    }
-}
-/** Nearest member of a closed vocabulary, for a "did you mean" suggestion. */
-function nearestIn(value, vocab) {
-    const v = typeof value === 'string' ? value.toLowerCase() : '';
-    return vocab.find((c) => c.replace(/[-_]/g, '') === v.replace(/[^a-z]/g, ''))
-        ?? vocab.find((c) => c.startsWith(v) || (v !== '' && v.startsWith(c)));
-}
-/** A string that is an expression the transform runtime will NOT evaluate. */
-const LOOKS_LIKE_EXPRESSION = /^(=js:|\$vars\.|\{\s*\$vars\.)/;
-// The three closed vocabularies a transform operation carries. TypeScript types
-// them, but an authored `.flow.ts` runs with types ERASED — so `condition:
-// 'greater'` reaches the runtime, whose generated script falls through on a name
-// it does not know and is silent about it:
-//   condition      → the rule passes every item
-//   transformation → the value is copied unchanged
-//   aggregation    → the aggregate is null
-// Green at every rung, wrong answer. Checked here so the author hears it at
-// rung 1 — a flow that never went through this SDK gets no such warning.
-const FILTER_CONDITIONS = [
-    'equals', 'not_equals',
-    'greater_than', 'less_than', 'greater_equal', 'less_equal',
-    'contains', 'not_contains',
-    'starts_with', 'not_starts_with',
-    'ends_with', 'not_ends_with',
-    'matches_regex',
-    'in', 'not_in',
-    'is_null', 'is_not_null',
-    'is_empty', 'is_not_empty',
-];
-const TRANSFORMATIONS = ['copy', 'uppercase', 'lowercase', 'trim'];
-const AGGREGATION_OPERATIONS = ['count', 'sum', 'average', 'min', 'max', 'first', 'last', 'collect'];
-/** Flag a value that is not a member of a closed vocabulary, suggesting the nearest. */
-function checkVocab(step, at, value, vocab, what, effect, diags) {
-    if (typeof value === 'string' && vocab.includes(value))
-        return;
-    const near = nearestIn(value, vocab);
-    diags.push({
-        level: 'error',
-        code: 'TRANSFORM_BAD_VOCAB',
-        message: `Transform "${step}" ${at} is ${JSON.stringify(value)}, which is not a valid ${what}. The runtime does not `
-            + `recognize it and ${effect}, so the result would be silently wrong. Valid: ${vocab.join(', ')}.`,
-        step,
-        ...(near ? { suggestion: near } : {}),
-    });
-}
 /**
  * Flag a case value whose type cannot match the discriminant's declared type.
  *
@@ -5174,100 +4790,116 @@ const LOOP_FIELDS = new Set(['currentItem', 'currentIteration', 'collection', 'o
  * before the 2.4 default (#868); its own fields are not audited here.
  */
 const LOOP_FIELDS_1_0_0 = new Set(['currentItem', 'currentIndex', 'collection', 'output', 'error']);
-/**
- * Columns Data Fabric assigns and never accepts a write for.
- *
- * The canvas hides them from both write editors, but the serializer has no
- * guard: a hand-authored `Id` row satisfies the node's own "at least one field"
- * rule, ships in the body, and is rejected — and the rejection is only logged,
- * so the row comes back unchanged and the run goes green.
- */
-const DATAFABRIC_SYSTEM_COLUMNS = new Set(['Id', 'CreateTime', 'CreatedBy', 'UpdateTime', 'UpdatedBy']);
-function checkDataFabricColumns(step, columns, option, diags) {
-    const system = columns.filter((c) => DATAFABRIC_SYSTEM_COLUMNS.has(c));
-    if (system.length) {
-        diags.push({
-            level: 'error', code: 'DATAFABRIC_SYSTEM_COLUMN', step,
-            message: `"${step}" writes ${system.map((c) => JSON.stringify(c)).join(', ')} in { ${option} }. `
-                + 'Data Fabric assigns its system columns (Id, CreateTime, CreatedBy, UpdateTime, UpdatedBy) and rejects a '
-                + 'write to them — and it only LOGS the rejection, so the row comes back unchanged and the run goes green.',
-        });
-    }
+/** The registered node type for a spec's kind, or undefined (a custom FlowAction has no kind). */
+function registeredKind(spec) {
+    const kind = spec?.kind;
+    return typeof kind === 'string' ? FLOW_NODE_TYPES.byKind(kind, spec) : undefined;
 }
 /**
- * A folder-scoped entity is portable only with its `Entity` bindings.
+ * Check one step whose kind is registered: its version, its node-local rules
+ * (reported through the family's catalog), and the expressions it carries.
+ * Returns its placement, or undefined when the version cannot be resolved — the
+ * step is then reported and not checked further.
  *
- * `_folderKey` on its own still serializes — it falls back to a source-org
- * literal and logs a warning — so the flow looks fine until it is deployed to
- * another org. Refusing the half-authored pair here is the whole point: the
- * alternative is a defect that only appears at deploy time, in a different org,
- * to somebody else.
+ * Its bindings are not checked here: unlike a contribution (`checkContribution`),
+ * a registered type's bindings exist only once it serializes. Closing every
+ * `<bindings.NAME>` its definition references is the node type's own contract,
+ * which serialize enforces (#942) and the type's tests pin; an author cannot
+ * cause the gap, so there is no author diagnostic to report.
  */
-function checkDataFabricScope(step, inputs, diags) {
-    if (inputs.folderKey !== undefined && inputs.resourceKey === undefined) {
-        diags.push({
-            level: 'error', code: 'DATAFABRIC_FOLDER_NO_RESOURCE_KEY', step,
-            message: `"${step}" sets { folderKey } without { resourceKey }. A folder-scoped entity needs both — with only `
-                + 'the folder key the entity serializes as a source-org literal, which validates, runs in this org, and '
-                + 'breaks on deploy to another one.',
-            suggestion: 'resolve the key with `uip solution resources list --kind Entity`, or drop { folderKey } and keep '
-                + 'the entity tenant-scoped',
-        });
+function checkRegisteredStep(entry, s, exprs, errorSource, opts, diags, typeOf, triggerId) {
+    const spec = s.spec;
+    /** The step's node-local rules and expressions, as `impl` defines them. */
+    const runRules = (impl) => {
+        const ctx = {
+            step: s.name,
+            version: impl.version,
+            report: (code, message, suggestion) => diags.push(catalogued(entry, s.name, code, message, suggestion)),
+            declaredRef: (js) => {
+                const name = declaredRefName(js, triggerId);
+                return name ? { name, type: typeOf.get(name) } : undefined;
+            },
+            options: opts,
+        };
+        impl.check?.(spec, ctx);
+        for (const site of impl.expressions(spec)) {
+            if ('code' in site) {
+                // A script body: checked for its `$vars.` refs although it is a string. No
+                // errorSource, as for `script()` (collectActionExprs).
+                exprs.push({ js: site.code, step: s.name });
+            }
+            else {
+                pushDeepExprs(site.value, s.name, errorSource, exprs);
+            }
+        }
+        return ctx;
+    };
+    let impl;
+    try {
+        impl = resolveVersion(entry.type, spec, s.options?.version, `step "${s.name}"`);
     }
-    if (inputs.resourceKey !== undefined && inputs.folderKey === undefined) {
-        diags.push({
-            level: 'error', code: 'DATAFABRIC_RESOURCE_KEY_NO_FOLDER', step,
-            message: `"${step}" sets { resourceKey } without { folderKey }. The pair exists to scope a FOLDER entity; a `
-                + 'tenant-scoped entity needs neither and serializes as a dotted literal.',
-        });
+    catch (e) {
+        // A select() that picks an unregistered version is the node type's bug, not the author's pin.
+        if (isInternalSdkError(e))
+            throw e;
+        diags.push({ level: 'error', code: 'NODE_VERSION_UNREGISTERED', step: s.name, message: e.message });
+        // Still report the step's other mistakes in this same pass, with the version it
+        // would get unpinned (select(), else the default) — as decompile lifts an
+        // unregistered version — so fixing the pin is not followed by a second round.
+        // It stays unplaced: the pin is wrong, so no family rule may rely on it.
+        runRules(resolveVersion(entry.type, spec, undefined, `step "${s.name}"`));
+        return undefined;
     }
+    const ctx = runRules(impl);
+    return { entry, impl, spec, placement: { step: s.name, kind: impl.kind, spec, version: impl.version }, ctx };
 }
-/**
- * The query options, none of which the node's `inputDefinition` declares — they
- * are `_`-prefixed extras, so `uip maestro flow validate` checks none of them
- * and every mistake here is silent at run time.
- */
-function checkDataFabricQuery(step, inputs, diags) {
-    const listOnly = ['limit', 'skip', 'sort', 'fields'].filter((k) => inputs[k] !== undefined);
-    if (listOnly.length && inputs.resultMode !== 'multiple') {
-        diags.push({
-            level: 'error', code: 'DATAFABRIC_QUERY_OPTS_WITHOUT_MULTIPLE', step,
-            message: `"${step}" sets { ${listOnly.join(', ')} }, which only a list query uses, but its resultMode is `
-                + `${inputs.resultMode ? JSON.stringify(inputs.resultMode) : 'unset (a single-record read)'}.`,
-            suggestion: "resultMode: 'multiple'",
-        });
+/** Every non-literal Expr reachable in `value`, as expressions to check. */
+function pushDeepExprs(value, step, errorSource, out) {
+    if (value instanceof Expr) {
+        if (!value.literal)
+            out.push({ js: value.js, step, errorSource });
     }
-    // The emitted query ALWAYS carries a limit — omitted it resolves to 100 — and
-    // 1000 is a hard ceiling that TRUNCATES rather than erroring above it.
-    if (inputs.limit !== undefined && (!Number.isInteger(inputs.limit) || inputs.limit < 1 || inputs.limit > 1000)) {
-        diags.push({
-            level: 'error', code: 'DATAFABRIC_LIMIT_RANGE', step,
-            message: `"${step}": limit must be a whole number between 1 and 1000 (got ${inputs.limit}). 1000 is a hard `
-                + 'ceiling — a larger value truncates silently, so page with { skip } instead.',
-        });
+    else if (Array.isArray(value)) {
+        for (const v of value)
+            pushDeepExprs(v, step, errorSource, out);
     }
-    // `in` is honoured only on a list query; on a single read the row compiles
-    // away, and a read whose filters compiled away returns EVERY record.
-    if (inputs.resultMode !== 'multiple' && (inputs.filters ?? []).some((f) => f.operator === 'in')) {
-        diags.push({
-            level: 'error', code: 'DATAFABRIC_IN_REQUIRES_MULTIPLE', step,
-            message: `"${step}" filters with the 'in' operator, which is honoured only when resultMode is 'multiple'. `
-                + 'On a single-record read that row compiles away — and a read whose filters compiled away matches every record.',
-        });
+    else if (value && typeof value === 'object') {
+        for (const v of Object.values(value))
+            pushDeepExprs(v, step, errorSource, out);
     }
-    // A filter expression switched on and left blank is refused by the serializer,
-    // and it refuses the WHOLE query rather than dropping the row, which strands
-    // every downstream reference to this step.
-    for (const f of inputs.filters ?? []) {
-        const blank = f.value instanceof Expr ? f.value.js.trim() === '' : String(f.value ?? '').trim() === '';
-        if (blank) {
-            diags.push({
-                level: 'error', code: 'DATAFABRIC_FILTER_BLANK_VALUE', step,
-                message: `"${step}" has a filter on ${JSON.stringify(f.field)} with a blank value. The serializer refuses the `
-                    + 'ENTIRE query rather than dropping the row, so the step emits nothing and every downstream $vars read of '
-                    + 'it breaks.',
-            });
-        }
+}
+/** Whether `e` is one of the SDK's own `internal SDK error:` throws, which `check` never turns into a diagnostic. */
+function isInternalSdkError(e) {
+    return e instanceof Error && e.message.startsWith('internal SDK error:');
+}
+/** A diagnostic a registered node type reports, at its family catalog's severity. */
+function catalogued(entry, step, code, message, suggestion) {
+    const known = Object.hasOwn(entry.family.diagnostics, code) ? entry.family.diagnostics[code] : undefined;
+    if (!known) {
+        throw new Error(`internal SDK error: node family "${entry.family.id}" reports ${code}, which its diagnostics catalog does not list.`);
+    }
+    // Key order as the per-family rules always wrote it — `check --json` prints it.
+    return { level: known.severity, code, step, message, ...(suggestion !== undefined ? { suggestion } : {}) };
+}
+/** Run each registered family's own rules over all of its placements in this flow. */
+function checkRegisteredFamilies(steps, unresolved, stepNames, diags) {
+    const byFamily = new Map();
+    for (const placed of steps.values()) {
+        const list = byFamily.get(placed.entry.family.id) ?? [];
+        list.push(placed);
+        byFamily.set(placed.entry.family.id, list);
+    }
+    for (const placed of byFamily.values()) {
+        const family = placed[0].entry.family;
+        if (!family.check)
+            continue;
+        const ctx = {
+            report: (step, code, message, suggestion) => diags.push(catalogued(placed[0].entry, step, code, message, suggestion)),
+            hasStep: (step) => stepNames.has(step),
+            placementOf: (step) => steps.get(step)?.placement,
+            versionUnresolved: (step) => unresolved.has(step),
+        };
+        family.check(placed.map((p) => p.placement), ctx);
     }
 }
 function collectActionExprs(s, out, errorSource) {
@@ -5294,20 +4926,6 @@ function collectActionExprs(s, out, errorSource) {
             push(val);
         return;
     }
-    if (s.spec.kind === 'script') {
-        // A script body is a plain STRING, not an Expr — so it never went through
-        // this check, and a bad `$vars.…` ref inside one used to surface only rungs
-        // later, as a type error about generated code (flow-builder-sdk#20). The body
-        // isn't parsed; the `$vars.<name>` refs it contains are checked like any other.
-        out.push({ js: s.spec.inputs.code, step: s.name });
-        return;
-    }
-    if (s.spec.kind === 'transform') {
-        // The only expression a transform carries is its collection; everything
-        // else is a literal or a field name (see checkTransform).
-        push(s.spec.inputs.collection);
-        return;
-    }
     if (s.spec.kind === 'hitl') {
         // A human task's only expressions are the values its shown fields display.
         // Without this a typo'd reference inside a form field would reach the
@@ -5326,30 +4944,6 @@ function collectActionExprs(s, out, errorSource) {
             push(val);
         return;
     }
-    if (s.spec.kind === 'dataFabricRead' || s.spec.kind === 'dataFabricCreate'
-        || s.spec.kind === 'dataFabricUpdate' || s.spec.kind === 'dataFabricDelete') {
-        // Every value a Data Fabric step carries is authored against flow scope: a
-        // filter's comparison value, the record id, the columns written. The family
-        // was missing here entirely, so a `$vars.` typo in any of them travelled to
-        // the platform unchecked — and the delete verb's no-output rule below has
-        // nothing to fire on until these are collected.
-        if (s.spec.kind === 'dataFabricRead') {
-            for (const f of s.spec.inputs.filters ?? [])
-                push(f.value);
-            return;
-        }
-        if (s.spec.kind === 'dataFabricCreate') {
-            for (const val of Object.values(s.spec.inputs.values ?? {}))
-                push(val);
-            return;
-        }
-        push(s.spec.inputs.record?.byId);
-        if (s.spec.kind === 'dataFabricUpdate') {
-            for (const val of Object.values(s.spec.inputs.set ?? {}))
-                push(val);
-        }
-        return;
-    }
     if (s.spec.kind === 'connector') {
         // Same gap on the connector surface: `messageToSend: tmpl`…${v('typo')}``
         // reached the runtime unchecked.
@@ -5376,6 +4970,17 @@ function collectActionExprs(s, out, errorSource) {
 const PER_TENANT_ERROR_PORT_KINDS = new Set([
     'connector', 'rpaWorkflow', 'apiWorkflow', 'agenticProcess', 'agent', 'ixpExtract',
 ]);
+/**
+ * The ONERROR_NO_ERROR_PORT sentence for a typed step — a built-in family or a
+ * registered node type — whose node type has no error port. One spelling for
+ * both, so porting a family onto the registry changes no message.
+ */
+function typedNoErrorPortMessage(stepName, kind, def) {
+    const nodeType = def ? ` (${def.nodeType}@${def.version})` : '';
+    return `Step "${stepName}" is a ${kind} step${nodeType}, and that node type has no error port — its definition does not `
+        + `set supportsErrorHandling, so the edge would leave a handle the node does not have. Handle the failure `
+        + `downstream instead (a delay cannot fail; a wait resumes or does not).`;
+}
 /** The five fields the platform's error envelope declares — no more, no less. */
 // The five the definitions declare, plus the two every probed runtime envelope
 // carried anyway (`response`, `element`) — see ErrorEnvelopeField in core/expr.ts.
@@ -5385,7 +4990,9 @@ const ERROR_ENVELOPE_FIELDS = ['code', 'message', 'detail', 'category', 'status'
  * mistakes at build time (no previous step, two handlers on one node, an empty
  * handler); these are the ones only a checker can see.
  */
-function checkOnError(_handler, step, diags) {
+function checkOnError(_handler, step, diags, 
+/** The step's registry record, when its kind is registered and its version resolved. */
+placed) {
     // The builder refuses a handler with no eligible step before it, so a missing
     // source here means a hand-built `BuiltFlow`; there is nothing to say about it.
     if (!step)
@@ -5439,6 +5046,35 @@ function checkOnError(_handler, step, diags) {
         return;
     }
     const spec = step.spec;
+    // A registered node type: a bundled one asks its definition at the version it
+    // will be emitted at; a per-tenant one answers for itself (its errorPort).
+    if (registeredKind(spec)) {
+        // No record: the version did not resolve, which NODE_VERSION_UNREGISTERED
+        // already reports where the step is checked.
+        if (!placed)
+            return;
+        const { impl } = placed;
+        if (impl.definition === 'per-tenant') {
+            const port = typeof impl.errorPort === 'function' ? impl.errorPort(spec) : impl.errorPort === true;
+            if (!port) {
+                diags.push({
+                    level: 'error', code: 'ONERROR_NO_ERROR_PORT', step: step.name,
+                    message: declaredErrorPortRefusal(step.name, impl.typeName, impl.version),
+                });
+                return;
+            }
+        }
+        else {
+            const def = bundledDefinition(impl.typeName, impl.version);
+            if (def !== undefined && !definitionHasErrorPort(def)) {
+                diags.push({ level: 'error', code: 'ONERROR_NO_ERROR_PORT', message: typedNoErrorPortMessage(step.name, impl.kind, def), step: step.name });
+                return;
+            }
+        }
+        // The port exists; the node type may still refuse the handler (plain HTTP's rule, once ported).
+        impl.checkErrorHandler?.(placed.spec, placed.ctx);
+        return;
+    }
     // A typed family with a bundled definition: ask the definition serialize will
     // emit, at the version it will emit (#1011). For instance `voiceAgent()`
     // defaults to uipath.agent.voice@1.0 (no error port) and `{ version: '1.1' }`
@@ -5451,13 +5087,10 @@ function checkOnError(_handler, step, diags) {
         ? bundledDef !== undefined && !definitionHasErrorPort(bundledDef)
         : !PER_TENANT_ERROR_PORT_KINDS.has(spec.kind);
     if (noPort) {
-        const nodeType = bundledDef ? ` (${bundledDef.nodeType}@${bundledDef.version})` : '';
         diags.push({
             level: 'error',
             code: 'ONERROR_NO_ERROR_PORT',
-            message: `Step "${step.name}" is a ${spec.kind} step${nodeType}, and that node type has no error port — its definition does not `
-                + `set supportsErrorHandling, so the edge would leave a handle the node does not have. Handle the failure `
-                + `downstream instead (a delay cannot fail; a wait resumes or does not).`,
+            message: typedNoErrorPortMessage(step.name, spec.kind, bundledDef),
             step: step.name,
         });
         return;
@@ -5700,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,
@@ -5715,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 } : {}) });
@@ -5742,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 `
@@ -5760,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`.
@@ -5789,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.