@uipath/maestro-builder-sdk 6.11.5 → 6.12.0

package/dist/bpmn/check.js

@@ -1,5 +1,55 @@
-import { processId } from './serialize.js';
+/**
+ * bpmn/check — fast static validation of a BuiltBpmn before serialization.
+ *
+ * Surfaces the common Maestro canvas-rule failures early (dangling flow refs,
+ * duplicate ids, a gateway branch with no condition, a superfluous gateway, an
+ * implicit join, a missing start event, a boundary event attached to nothing, an
+ * empty timer) so authoring gets instant feedback. The authoritative gate is
+ * still `uip maestro bpmn validate` (`validateBpmnCanvas`) on the emitted
+ * `.bpmn`.
+ *
+ * **An `error` here must mirror a real platform rule.** Being stricter than
+ * `validate` is worse than being looser: it refuses processes that deploy and run
+ * correctly, and the author has no way to appeal. Where this file is deliberately
+ * stricter than the platform — an unconditioned inclusive-gateway branch, an
+ * implicit join — the diagnostic is a `warning`, and its comment says which
+ * platform rule it corresponds to and how the two differ.
+ */
+import { nodeDeclaredVars } from './bpmn-sdk.js';
+import { folderCompanionKeys, implicitNodeVars, processId } from './serialize.js';
+import { KNOWN_METHOD_SET } from './known-methods.js';
 import { bindingRequiredFields, missingRequiredContext, missingRequiredInputs, registryType, REGISTRY_GAPS, unsatisfiableRequiredInputs, } from './typed-node.js';
+/**
+ * Service types the platform expects to name a concrete Orchestrator resource.
+ *
+ * From the canvas rule `MISSING_RESOURCE`, copied rather than inferred: nothing in the
+ * registry marks these, and the rule turns on the service type alone.
+ */
+const SERVICE_TYPES_REQUIRING_RESOURCE = new Set([
+    'Orchestrator.StartAgentJob',
+    'Orchestrator.StartJob',
+    'Orchestrator.CreateQueueItem',
+    'Orchestrator.CreateAndWaitForQueueItem',
+    'Orchestrator.BulkAddQueueItems',
+    'Orchestrator.QueueItemAdded',
+    'Orchestrator.ExecuteApiWorkflowAsync',
+    'Orchestrator.StartFlowProcess',
+    'Orchestrator.StartFlowProcessAsync',
+    'Actions.HITL',
+    'Orchestrator.StartAgenticProcess',
+    'Orchestrator.StartAgenticProcessAsync',
+    'Orchestrator.StartCaseMgmtProcess',
+    'Orchestrator.StartCaseMgmtProcessAsync',
+]);
+/**
+ * A HITL task carrying its form inline needs no Action-app resource — the platform's
+ * own carve-out from `MISSING_RESOURCE`, and the reason this rule cannot be written as
+ * "these types need a resource".
+ */
+const HITL_QUICK_SCHEMA_CONTEXT = new Set(['_schemaFileId', 'hitlSchemaId', '__hitlFormSchema']);
+/** The bounds the platform puts on a human task's `Timer`, in MINUTES. */
+const MIN_TASK_TIMER_MINUTES = 15;
+const MAX_TASK_TIMER_MINUTES = 90 * 24 * 60;
 const GATEWAY_KINDS = new Set(['exclusiveGateway', 'parallelGateway', 'inclusiveGateway', 'eventBasedGateway']);
 /**
  * What a boundary event may attach to. `connector` belongs here: it serializes to
@@ -15,8 +65,174 @@ export function check(built) {
     checkScope(built.nodes, built.flows, 'process', diags, seenIds, true);
     checkScopedVars(built, diags);
     checkDocumentIds(built, diags);
+    checkFolderBindings(built, diags);
+    checkEntryPointId(built, diags);
+    checkMethodParentheses(built, diags);
     return diags;
 }
+/**
+ * A known method NAMED but not CALLED — `=vars.s.ToUpper` where `ToUpper()` was meant.
+ *
+ * A faithful port of the canvas rule `METHOD_MISSING_PARENTHESES`, down to its regex
+ * and its vocabulary (`known-methods.ts`, generated from the platform's own list). The
+ * platform reports it as an ERROR, so it gates — and the message it gives back names
+ * the method and an XML element id, which the author then has to map to the
+ * TypeScript that produced it.
+ *
+ * Reported here rather than refused at `.build()`, unlike the structural collisions in
+ * `bpmn-sdk.ts`. Those are two objects the builder is holding; this is a textual
+ * heuristic over expression source, and the sites this walks are the SDK's, not the
+ * platform's. If the two lists of sites ever diverge, a diagnostic is a message the
+ * author can weigh and a refusal is a wall — so the weaker rung is the honest one.
+ */
+function checkMethodParentheses(built, diags) {
+    const report = (expr, where) => {
+        if (!expr)
+            return;
+        // The platform's own pattern: a member access whose name is a known method and
+        // which is not followed by `(`. Kept character-for-character so the two agree.
+        for (const m of expr.matchAll(/\.(\w+)(?!\s*\()/g)) {
+            const method = m[1];
+            if (!KNOWN_METHOD_SET.has(method))
+                continue;
+            diags.push({
+                level: 'error',
+                code: 'METHOD_MISSING_PARENTHESES',
+                message: `${where} names method "${method}" without calling it. Write "${method}()" — the platform's ` +
+                    `expression evaluator refuses a method referenced as a property.`,
+                where,
+            });
+        }
+    };
+    const deep = (val, where) => {
+        if (typeof val === 'string')
+            return report(val, where);
+        if (Array.isArray(val))
+            return val.forEach((v) => deep(v, where));
+        if (val && typeof val === 'object')
+            for (const v of Object.values(val))
+                deep(v, where);
+    };
+    const walk = (nodes, flows) => {
+        for (const f of flows)
+            report(f.condition, `flow "${f.id}" condition`);
+        for (const n of nodes) {
+            const at = `${n.kind} "${n.id}"`;
+            for (const row of ('errorMapping' in n ? n.errorMapping : undefined) ?? [])
+                report(row.condition, `${at} errorMapping "${row.code}" condition`);
+            if ('loop' in n && n.loop) {
+                report(n.loop.collection, `${at} loop collection`);
+                report(n.loop.completion, `${at} loop completion`);
+            }
+            if (n.kind === 'scriptTask') {
+                // The script BODY is deliberately not walked. `obj.Trim` inside a program is a
+                // property access the platform never reads, and reporting it would be the SDK
+                // refusing what the platform accepts.
+                deep(n.inputs, `${at} input`);
+                deep(n.outputs, `${at} output`);
+            }
+            else if (n.kind === 'task') {
+                deep(n.set, `${at} assignment`);
+            }
+            else if (n.kind === 'connector') {
+                deep(n.inputs, `${at} input`);
+            }
+            else if (n.kind === 'typed') {
+                deep(n.context, `${at} context`);
+                deep(n.inputs, `${at} input`);
+                for (const row of n.contextRows ?? [])
+                    report(row.value, `${at} context "${row.name}"`);
+                for (const row of n.inputRows ?? [])
+                    report(row.value, `${at} input "${row.name}"`);
+            }
+            if (n.kind === 'subProcess')
+                walk(n.nodes, n.flows);
+        }
+    };
+    walk(built.nodes, built.flows);
+}
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * `.metadata({ entryPointId })` must be a GUID.
+ *
+ * The product assigns one (`bpmn init` writes it, `decompile` carries it) and
+ * `uip maestro bpmn validate` refuses anything else — `Root start event
+ * uipath:entryPointId value "WikiPageviews_Start" must be a GUID` — which an author who
+ * hand-wrote a readable id only learns at the last rung. In the 2026-09-27 A/B against
+ * main one agent spent its whole turn budget there. Reported here, at the first rung.
+ */
+function checkEntryPointId(built, diags) {
+    const id = built.metadata?.entryPointId;
+    if (id === undefined || GUID.test(id))
+        return;
+    diags.push({
+        level: 'error',
+        code: 'ENTRYPOINT_ID_NOT_GUID',
+        message: `metadata.entryPointId "${id}" is not a GUID; \`uip maestro bpmn validate\` refuses it. Use the id \`bpmn init\` ` +
+            `assigned (decompile the stub it wrote to carry it), or a fresh one from \`crypto.randomUUID()\`.`,
+    });
+}
+/**
+ * A `folderKey` binding must be keyed by its CONNECTION, not by the folder.
+ *
+ * The pair every real export writes is `ConnectionId {resourceKey: C, default: C}` +
+ * `folderKey {resourceKey: C, default: F}`: the folder is where the connection is
+ * resolved, so its resource key is the connection's. `uip maestro bpmn validate`
+ * reports `MISSING_BINDING` for a folder binding keyed by its own folder — which is
+ * what `.binding('f', { propertyAttribute: 'folderKey', value: F })` used to write, and
+ * what every run-6 agent that reached for Data Fabric or Test Manager shipped. The
+ * serializer now pairs a folder with its connection itself (`folderCompanionKeys`); this
+ * reports the two cases it cannot fix: an explicit `resourceKey` equal to the folder key,
+ * and a folder no node pairs with a connection when more than one connection exists.
+ */
+function checkFolderBindings(built, diags) {
+    const folders = built.bindings.filter((b) => String(b.propertyAttribute ?? '').toLowerCase() === 'folderkey');
+    if (!folders.length)
+        return;
+    // `serialize` pairs against its binding SINK — the connections a connector, connector
+    // event or external task declares as a side effect of being emitted, which never
+    // appear in `built.bindings` because the author named them symbolically. `check` runs
+    // before serialization and has no sink, and passing an empty one made it warn about
+    // folders the serializer goes on to pair correctly: a `.connector(..., { connection:
+    // 'conn', folder: 'myFolder' })` node contributes the only ConnectionId there is, and
+    // the one-connection rung inside `folderCompanionKeys` finds it. So the sink is
+    // reconstructed from the nodes here, which is the same set serialize will build.
+    const sink = new Map();
+    const collectConnections = (nodes) => {
+        for (const n of nodes) {
+            const named = n.kind === 'connector' || n.kind === 'connectorEvent' || n.kind === 'externalTask' ? n.connection : undefined;
+            if (named)
+                sink.set(named, { id: named, propertyAttribute: 'ConnectionId', default: named });
+            if (n.kind === 'subProcess')
+                collectConnections(n.nodes);
+        }
+    };
+    collectConnections(built.nodes);
+    const paired = folderCompanionKeys(built, sink);
+    for (const b of folders) {
+        if (b.resourceKey !== undefined && b.resourceKey === b.default) {
+            diags.push({
+                level: 'warning',
+                code: 'FOLDER_BINDING_KEYED_BY_FOLDER',
+                message: `Binding "${b.id}" (folderKey) has resourceKey equal to its own folder key. A folder binding is keyed by the ` +
+                    `CONNECTION it belongs to (\`uip maestro bpmn validate\` reports MISSING_BINDING otherwise). Drop \`resourceKey\` ` +
+                    `and the builder pairs it with the connection the node reads, or set it to that connection's key.`,
+                where: b.id,
+            });
+        }
+        else if (b.resourceKey === undefined && !paired.has(b.id)) {
+            diags.push({
+                level: 'warning',
+                code: 'FOLDER_BINDING_UNPAIRED',
+                message: `Binding "${b.id}" (folderKey) could not be paired with a connection: no node reads it beside a ` +
+                    `\`=bindings.<connection>\`, and the process does not declare exactly one ConnectionId binding. Its resourceKey ` +
+                    `will be the folder key, which \`uip maestro bpmn validate\` reports as MISSING_BINDING. Read both bindings from ` +
+                    `the same node, or set \`resourceKey\` to the connection's key.`,
+                where: b.id,
+            });
+        }
+    }
+}
 /**
  * Every `id` in the document must be unique — including across KINDS.
  *
@@ -33,7 +249,14 @@ export function check(built) {
  * is the only gate that can catch it, and it has to be an error.
  *
  * The ids in play are every element and flow, every variable and binding, the
- * synthesized `Message_n`/`Error_n` declarations, and the process itself.
+ * synthesized `Message_n`/`Error_n` declarations, and the process itself — and the
+ * declarations serialize DERIVES from output rows (a connector's `<id>_response`, a
+ * script task's `outputs`), which are variables in the document too. Those were the one
+ * kind this check could not see: a script output named after the gateway that routes
+ * on it (`outputs: { confidence }` beside `.choose('confidence', …)`) passed here and
+ * every SDK gate, and `uip maestro bpmn validate` answered with three
+ * CROSSING_SUBPROCESS_BOUNDARY errors on the gateway's flows — the validator had
+ * resolved the id to the variable. Measured on the nested_review port.
  */
 function checkDocumentIds(built, diags) {
     const owners = new Map();
@@ -52,12 +275,16 @@ function checkDocumentIds(built, diags) {
         });
     };
     claim(built.id, 'the process');
+    const owner = (nodes, id) => nodes.find((n) => nodeDeclaredVars(n).includes(id))?.id ?? '?';
     const walk = (nodes, flows) => {
         for (const n of nodes) {
             claim(n.id, `element "${n.id}"`);
             if (n.kind === 'subProcess') {
                 for (const v of n.variables)
                     claim(v.id, `variable "${v.id}"`);
+                for (const v of implicitNodeVars(n.nodes, n.variables)) {
+                    claim(v.id, `the variable serialize declares for the output row of "${owner(n.nodes, v.id)}"`);
+                }
                 walk(n.nodes, n.flows);
             }
         }
@@ -67,6 +294,9 @@ function checkDocumentIds(built, diags) {
     walk(built.nodes, built.flows);
     for (const v of built.variables)
         claim(v.id, `variable "${v.id}"`);
+    for (const v of implicitNodeVars(built.nodes, built.variables)) {
+        claim(v.id, `the variable serialize declares for the output row of "${owner(built.nodes, v.id)}"`);
+    }
     for (const b of built.bindings)
         claim(b.id, `binding "${b.id}"`);
     for (const mm of built.messages)
@@ -106,7 +336,7 @@ function checkScopedVars(built, diags) {
     };
     collect(built.nodes);
     for (const v of allVars) {
-        if (v.elementId !== undefined && !ids.has(v.elementId))
+        if (typeof v.elementId === 'string' && !ids.has(v.elementId))
             diags.push({
                 level: 'error',
                 code: 'SCOPED_VAR_UNKNOWN_ELEMENT',
@@ -124,6 +354,57 @@ function checkScopedVars(built, diags) {
  * its own `TIMER_DURATION_WEEK_UNSUPPORTED` rule.
  */
 const RUNTIME_DURATION = /^P(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/i;
+/**
+ * A spec-legal ISO-8601 duration, which is WIDER than the runtime's parser: weeks,
+ * months and years are valid here and unparseable there. The platform splits the same
+ * way — `TIMER_DURATION_INVALID` is an error against ISO-8601 (it calls luxon's
+ * `Duration.fromISO`), and `TIMER_DURATION_WEEK_UNSUPPORTED` is a separate warning — so
+ * the two tests are kept apart here for the same reason rather than collapsed.
+ */
+const ISO_DURATION = /^P(?!$)(?:\d+(?:\.\d+)?Y)?(?:\d+(?:\.\d+)?M)?(?:\d+(?:\.\d+)?W)?(?:\d+(?:\.\d+)?D)?(?:T(?!$)(?:\d+(?:\.\d+)?H)?(?:\d+(?:\.\d+)?M)?(?:\d+(?:\.\d+)?S)?)?$/i;
+function isIsoDuration(v) {
+    return ISO_DURATION.test(v) && /\d/.test(v);
+}
+/**
+ * A timer value the author supplied but left blank. The platform's `isTimerValueMissing`
+ * is `value == null || value === ''`, so an EMPTY STRING is missing — which is the case
+ * `check` used to pass, because it only asked whether all three timer fields were
+ * `undefined`. `.intermediateCatchEvent('w', { timer: '' })` reached `validate`.
+ */
+function isBlankTimerValue(v) {
+    return v !== undefined && v.trim() === '';
+}
+/**
+ * Whether an expression ASSIGNS rather than evaluates — `=vars.n = 5` where `==` was
+ * meant. A faithful port of the platform's `expressionHasAssignment`: string, template
+ * and regex literals are blanked first, then a compound assignment operator or a bare
+ * `=` that is not part of `==`, `!=`, `<=`, `>=`, `=>` or a compound operator is a hit.
+ *
+ * Scoped where the platform scopes it — flow conditions and error-mapping conditions —
+ * and reported at its severity, WARNING, because the artifact is still accepted. The
+ * point is that the author hears it at the rung they iterate on rather than the last one.
+ */
+const ASSIGNMENT_OP = /(\?\?=|&&=|\|\|=|>>>=|<<=|>>=|\*\*=|\+=|-=|\*=|\/=|%=|&=|\|=|\^=|(?<![!=<>+\-*/%.&|^?])=(?![=>]))/;
+function expressionHasAssignment(expr) {
+    if (!expr)
+        return false;
+    const body = expr.startsWith('=') ? expr.slice(1) : expr;
+    if (!body.trim())
+        return false;
+    const blank = (m) => ' '.repeat(m.length);
+    const sanitized = body
+        .replace(/"(?:[^"\\]|\\.)*"/g, blank)
+        .replace(/'(?:[^'\\]|\\.)*'/g, blank)
+        .replace(/`(?:[^`\\]|\\.)*`/g, blank)
+        // A regex literal can only START where a value can start. Matching any run between
+        // two `/` blanked real code whenever one expression divided twice:
+        // `=vars.done / vars.total > 0.5 && vars.ratio = vars.x / vars.y` had everything
+        // from the first slash to the last blanked, and the stray `=` went unreported. So
+        // the opening `/` has to sit in regex-legal position — start of expression, or after
+        // an operator or opening bracket — which is never true of a division.
+        .replace(/(^|[(,=:[!&|?{};+\-*%^~]\s*)(\/(?:[^/\\\n]|\\.)*\/[gimsuy]*)/g, (_m, pre, lit) => pre + blank(lit));
+    return ASSIGNMENT_OP.test(sanitized);
+}
 function isRuntimeDuration(v) {
     // A bare `P`/`PT` matches the shape but carries no components — the same
     // "validates, then no runtime can parse it" trap the timer eval card exists for.
@@ -181,6 +462,18 @@ function checkActivityFields(n, diags) {
                 where: n.id,
             });
     }
+    // An error-mapping condition is the platform's other ASSIGNMENT_NOT_ALLOWED site.
+    const mappings = 'errorMapping' in n ? (n.errorMapping ?? []) : [];
+    for (const row of mappings) {
+        if (expressionHasAssignment(row.condition))
+            diags.push({
+                level: 'warning',
+                code: 'ASSIGNMENT_NOT_ALLOWED',
+                message: `Error-mapping condition on "${n.id}" (code "${row.code}") contains an assignment operator; it must only ` +
+                    `evaluate. \`=\` assigns and \`==\` compares.`,
+                where: n.id,
+            });
+    }
     const loop = 'loop' in n ? n.loop : undefined;
     if (loop) {
         if (!loop.collection)
@@ -224,12 +517,66 @@ inEventSubProcess = false) {
     // NO_START on a process that has one, refusing an artifact the platform accepts.
     if (nodes.length && !nodes.some(isStartElement))
         diags.push({ level: isTop ? 'error' : 'warning', code: 'NO_START', message: `${where} has no start event.`, where });
+    // At most one BLANK start event per scope — one with no event definition and no
+    // trigger, the "start this manually" event. The platform counts them per process and
+    // per sub-process (`validateSingleBlankStartEvent`) and errors on a second; a
+    // `sequence` scope refuses one at build, but an explicit-mode scope did not, so the
+    // shape reached `validate`.
+    const blankStarts = nodes.filter((n) => n.kind === 'startEvent' && n.event === undefined && n.trigger === undefined);
+    if (blankStarts.length > 1)
+        diags.push({
+            level: 'error',
+            code: 'MULTIPLE_BLANK_START_EVENTS',
+            message: `${where} has ${blankStarts.length} blank start events (${blankStarts.map((n) => `"${n.id}"`).join(', ')}); ` +
+                `a scope may have at most one. Give the others an event definition, or merge the paths.`,
+            where: blankStarts[1].id,
+        });
     // Flow endpoints must resolve within this scope.
+    const byId = new Map(nodes.map((n) => [n.id, n]));
     for (const f of flows) {
         if (!nodeIds.has(f.source))
             diags.push({ level: 'error', code: 'DANGLING_FLOW', message: `Flow "${f.id}" source "${f.source}" is not an element in ${where}.`, where: f.id });
         if (!nodeIds.has(f.target))
             diags.push({ level: 'error', code: 'DANGLING_FLOW', message: `Flow "${f.id}" target "${f.target}" is not an element in ${where}.`, where: f.id });
+        // A flow from an element to itself. The platform reports it as INVALID_CONNECTION;
+        // an error here, to match DANGLING_FLOW, which is the same class of broken edge.
+        if (f.source === f.target)
+            diags.push({
+                level: 'error',
+                code: 'SELF_FLOW',
+                message: `Flow "${f.id}" leaves "${f.source}" and arrives at the same element; a loop needs a gateway or \`loop\`.`,
+                where: f.id,
+            });
+        // Nothing flows INTO a start event or OUT of an end event. Both are structural
+        // facts of BPMN, both are reachable through an explicit `.sequenceFlow()` — a
+        // `sequence` scope refuses them when it places the node, an explicit scope did not —
+        // and the platform reports each as INVALID_CONNECTION_TYPE. The rest of its
+        // type-compatibility matrix is NOT ported: these two are the cases an author
+        // actually writes by mistake.
+        const target = byId.get(f.target);
+        if (target !== undefined && isStartElement(target))
+            diags.push({
+                level: 'error',
+                code: 'FLOW_INTO_START',
+                message: `Flow "${f.id}" arrives at start event "${f.target}"; a start event has no incoming flow.`,
+                where: f.id,
+            });
+        const source = byId.get(f.source);
+        if (source !== undefined && source.kind === 'endEvent')
+            diags.push({
+                level: 'error',
+                code: 'FLOW_OUT_OF_END',
+                message: `Flow "${f.id}" leaves end event "${f.source}"; an end event ends its path.`,
+                where: f.id,
+            });
+        if (expressionHasAssignment(f.condition))
+            diags.push({
+                level: 'warning',
+                code: 'ASSIGNMENT_NOT_ALLOWED',
+                message: `Condition on flow "${f.id}" contains an assignment operator; it must only evaluate. ` +
+                    `\`=\` assigns and \`==\` compares.`,
+                where: f.id,
+            });
     }
     const outgoing = new Map();
     const incomingCount = new Map();
@@ -259,11 +606,55 @@ inEventSubProcess = false) {
                 for (const o of outs)
                     if (o.id !== n.default && o.condition === undefined)
                         diags.push({ level, code: 'MISSING_CONDITION_EXPRESSION', message: `Outgoing flow "${o.id}" of gateway "${n.id}" has no condition.`, where: o.id });
+                // Every branch conditioned and no default: when no condition holds the token
+                // has nowhere to go, and the instance stalls at the gateway. A WARNING, not an
+                // error: the platform has no rule for it (`uip maestro bpmn validate` says Valid),
+                // and the runtime is what discovers it — as the diagnose evals' "stuck gateway"
+                // does. `.choose()` with an `otherwise` arm cannot produce this shape.
+                if (n.kind === 'exclusiveGateway' && n.default === undefined && outs.every((o) => o.condition !== undefined))
+                    diags.push({
+                        level: 'warning',
+                        code: 'NO_DEFAULT_FLOW',
+                        message: `Gateway "${n.id}" has no default flow: when none of its ${outs.length} conditions holds, the instance ` +
+                            `stalls there. Mark one flow as the default, or add an \`otherwise\` arm.`,
+                        where: n.id,
+                    });
             }
         }
-        // A gateway with exactly one in and one out is superfluous.
-        if (GATEWAY_KINDS.has(n.kind) && ins === 1 && outs.length === 1)
-            diags.push({ level: 'warning', code: 'SUPERFLUOUS_GATEWAY', message: `Gateway "${n.id}" has one incoming and one outgoing flow; remove it.`, where: n.id });
+        // A gateway with exactly one in and one out is superfluous. An ERROR, and scoped to
+        // the three kinds the platform's rule covers: `validateSuperfluousGateway` matches
+        // ExclusiveGateway / ParallelGateway / InclusiveGateway at severity ERROR, so a
+        // warning here told the author something the last rung would refuse — measured as a
+        // `validate`-only row in the conformance ledger even though the code existed.
+        // An event-based gateway is outside the platform's rule and stays a warning.
+        if (GATEWAY_KINDS.has(n.kind) && ins === 1 && outs.length === 1) {
+            const platformRule = n.kind !== 'eventBasedGateway';
+            diags.push({
+                level: platformRule ? 'error' : 'warning',
+                code: 'SUPERFLUOUS_GATEWAY',
+                message: `Gateway "${n.id}" has one incoming and one outgoing flow, so it decides nothing; remove it and wire ` +
+                    `its source straight to its target.`,
+                where: n.id,
+            });
+        }
+        // The only outgoing flow carries a condition, so a false condition strands the token
+        // with nowhere to go. The platform's rule is on ANY node — a task with one conditional
+        // outgoing flow trips it too, not just a gateway — minus parallel and event-based
+        // gateways, and minus the exclusive/inclusive gateways the superfluous rule above
+        // already owns (one in, one out), so the two rules do not both fire on one element.
+        if (n.kind !== 'parallelGateway' && n.kind !== 'eventBasedGateway' && outs.length === 1) {
+            const ownedBySuperfluous = (n.kind === 'exclusiveGateway' || n.kind === 'inclusiveGateway') && ins === 1;
+            const only = outs[0];
+            const defaultFlowId = 'default' in n ? n.default : undefined;
+            if (!ownedBySuperfluous && only.condition !== undefined && only.id !== defaultFlowId)
+                diags.push({
+                    level: 'error',
+                    code: 'SINGLE_CONDITIONAL_OUTGOING_FLOW',
+                    message: `The only outgoing flow of "${n.id}" ("${only.id}") carries a condition, so the instance strands there ` +
+                        `whenever it is false. Drop the condition, mark the flow as the default, or add the other branch.`,
+                    where: only.id,
+                });
+        }
         // An activity or event with >1 incoming flow is an implicit join. A WARNING,
         // not an error: the platform's FAKE_JOIN rule only matches the abstract types
         // `bpmn:Activity`/`bpmn:Event`, which never appear on real exported BPMN, so
@@ -276,6 +667,42 @@ inEventSubProcess = false) {
                 message: `"${n.id}" has ${ins} incoming flows; the platform accepts this, but joining with a gateway is clearer.`,
                 where: n.id,
             });
+        // The mirror of FAKE_JOIN: an activity or event with more than one outgoing
+        // flow and no condition on any of them is an implicit PARALLEL SPLIT — every
+        // branch runs. A warning for the same reason: the platform accepts it.
+        //
+        // Worth saying because of how easily the nesting sugar produces one by accident.
+        // An explicit `.sequenceFlow()` off an element the builder has ALREADY implied a
+        // flow out of adds a second edge rather than replacing the first, so
+        // `.task('a').endEvent('done').sequenceFlow('a', 'failed')` fans out where the
+        // author meant to redirect. Writing the explicit flow BEFORE the next element
+        // takes the path off the books instead (see `sequenceFlow`), so the two orders
+        // no longer differ silently — this is what reports the one that cannot be caught
+        // at the call site.
+        const unconditioned = outs.filter((f) => f.condition === undefined);
+        if (!GATEWAY_KINDS.has(n.kind) && n.kind !== 'boundaryEvent' && unconditioned.length > 1)
+            diags.push({
+                level: 'warning',
+                code: 'IMPLICIT_SPLIT',
+                message: `"${n.id}" has ${unconditioned.length} outgoing flows and no condition on any of them ` +
+                    `(${unconditioned.map((f) => `"${f.target}"`).join(', ')}), so every one of them runs. ` +
+                    `If that is meant, split with .fork(); if one was meant to replace another, write the ` +
+                    `.sequenceFlow() before the element that follows.`,
+                where: n.id,
+            });
+        // An element nothing leaves, that is not an end. The token arriving there has
+        // nowhere to go, and the instance sits at that element for ever. A WARNING: the
+        // platform has no rule for it (`uip maestro bpmn validate` says Valid), and a
+        // process under construction legitimately has loose ends. It is here because
+        // `bpmn check --graph` showed one in a shipped example that every other gate had
+        // passed — an activity whose only exit was through its error handler.
+        if (outs.length === 0 && n.kind !== 'endEvent' && !(n.kind === 'subProcess' && n.triggeredByEvent === true))
+            diags.push({
+                level: 'warning',
+                code: 'DEAD_END',
+                message: `"${n.id}" has no outgoing flow, so a token reaching it stops there. End the path with an end event, or wire it on.`,
+                where: n.id,
+            });
         // Boundary events must attach to an activity in the same scope.
         if (n.kind === 'boundaryEvent') {
             const target = nodes.find((x) => x.id === n.attachedTo);
@@ -301,8 +728,39 @@ inEventSubProcess = false) {
         }
         if (n.kind !== 'subProcess' && 'event' in n && n.event?.type === 'timer') {
             const t = n.event.timer;
+            const blank = [t.duration, t.date, t.cycle].find(isBlankTimerValue) !== undefined;
             if (t.duration === undefined && t.date === undefined && t.cycle === undefined)
                 diags.push({ level: 'error', code: 'TIMER_MISSING_FIELD', message: `Timer on "${n.id}" needs a duration, date, or cycle.`, where: n.id });
+            else if (blank)
+                // The field is present and empty, which the platform reports as
+                // TIMER_MISSING_REQUIRED_FIELD. Same diagnosis, one rung earlier.
+                diags.push({
+                    level: 'error',
+                    code: 'TIMER_MISSING_FIELD',
+                    message: `Timer on "${n.id}" declares a field with an empty value; give it a duration, date, or cycle.`,
+                    where: n.id,
+                });
+            // An expression or a binding reference is resolved at run time, so its shape is
+            // not ours to judge — the platform skips `=`/`@` values for the same reason.
+            const d = t.duration;
+            if (d !== undefined && d.trim() !== '' && !d.startsWith('=') && !d.startsWith('@')) {
+                if (!isIsoDuration(d))
+                    diags.push({
+                        level: 'error',
+                        code: 'TIMER_DURATION_INVALID',
+                        message: `Timer duration "${d}" on "${n.id}" is not an ISO-8601 duration, e.g. "PT30S" or "P1DT12H".`,
+                        where: n.id,
+                    });
+                else if (!isRuntimeDuration(d))
+                    diags.push({
+                        level: 'warning',
+                        code: 'TIMER_DURATION_NOT_RUNTIME_PARSEABLE',
+                        message: `Timer duration "${d}" on "${n.id}" is valid ISO-8601 but the runtime parses days/hours/minutes/seconds ` +
+                            `only, so a week, month or year designator is accepted by validate and then fails at run time. ` +
+                            `Write it in days, e.g. "P7D" for a week.`,
+                        where: n.id,
+                    });
+            }
         }
         // Retry / loop options on any activity.
         checkActivityFields(n, diags);
@@ -320,7 +778,7 @@ inEventSubProcess = false) {
             const contextView = { ...n.context };
             for (const row of n.contextRows ?? [])
                 contextView[row.name] = row.value ?? row.body ?? '';
-            for (const field of bindingRequiredFields(n.type)) {
+            for (const field of bindingRequiredFields(n.type, n.spec)) {
                 const value = contextView[field.name];
                 if (typeof value === 'string' && value.startsWith('=bindings.'))
                     continue;
@@ -333,6 +791,59 @@ inEventSubProcess = false) {
                     where: n.id,
                 });
             }
+            // A human task's own timer, which the platform bounds to 15 minutes … 90 days.
+            // Note the units and the type: this is a NUMBER OF MINUTES on an `actions` node,
+            // not an ISO duration and not a boundary timer, and an `=`/`@` value is a runtime
+            // expression the rule skips. Warning, as the platform reports it.
+            if (n.type === 'actions') {
+                const raw = contextView['Timer'];
+                const str = raw === undefined || raw === null ? '' : String(raw);
+                const minutes = Number(str);
+                if (str !== '' && !str.startsWith('=') && !str.startsWith('@') && !Number.isNaN(minutes)) {
+                    if (minutes < MIN_TASK_TIMER_MINUTES || minutes > MAX_TASK_TIMER_MINUTES)
+                        diags.push({
+                            level: 'warning',
+                            code: 'TASK_TIMER_OUT_OF_RANGE',
+                            message: `"${n.id}" sets Timer to ${str}, outside the 15 minutes to 90 days the platform accepts. ` +
+                                `The value is a NUMBER OF MINUTES — "${MIN_TASK_TIMER_MINUTES}" is the shortest, ` +
+                                `"${MAX_TASK_TIMER_MINUTES}" the longest — not an ISO duration.`,
+                            where: n.id,
+                        });
+                }
+            }
+            // A service task of a type that starts or enqueues something, with nothing
+            // naming WHAT. The platform reports `MISSING_RESOURCE` at WARNING, so it does
+            // not gate — and a warning at the last rung is the weakest signal there is. It
+            // is a warning here too: the platform accepts the process, so an error would be
+            // the SDK refusing what deploys.
+            if (SERVICE_TYPES_REQUIRING_RESOURCE.has(n.type)) {
+                const quickHitl = n.type === 'Actions.HITL' &&
+                    (contextView['hitlType'] === 'quick' ||
+                        (contextView['hitlType'] !== 'custom' && Object.keys(contextView).some((k) => HITL_QUICK_SCHEMA_CONTEXT.has(k))));
+                // `appId` is a deliberate, narrow LOOSENING of the platform's list, and the one
+                // place this rule does not mirror it. The canvas rule reads only
+                // `releaseKey`/`name`/`queueName`, so every `Actions.HITL` node — including
+                // every one `.humanTask()` itself produces, which writes the app as `appId` —
+                // trips it. Warning on a shape the SDK's own wrapper emits, about a field that
+                // is not how an Action app is addressed, is noise the author cannot act on.
+                // Safe in this direction: the platform reports MISSING_RESOURCE at WARNING, so
+                // staying quiet cannot turn an accepted artifact into a rejected one. The
+                // reverse — reporting more than the platform — is what this file forbids.
+                const resourceFields = n.type === 'Actions.HITL' ? ['releaseKey', 'name', 'queueName', 'appId'] : ['releaseKey', 'name', 'queueName'];
+                const bound = resourceFields.some((f) => {
+                    const v = contextView[f];
+                    return v !== undefined && v !== null && String(v) !== '';
+                });
+                if (!quickHitl && !bound)
+                    diags.push({
+                        level: 'warning',
+                        code: 'MISSING_RESOURCE',
+                        message: `"${n.id}" (${n.type}) names no resource, so nothing says which process or queue it acts on. ` +
+                            `Set "releaseKey", or "name"/"queueName" — normally as a binding reference, e.g. ` +
+                            `\`name: '=bindings.MyProcess'\`.`,
+                        where: n.id,
+                    });
+            }
             // Context reaches a node two ways — the `context` record, or the verbatim
             // `contextRows` an importer uses when a row carries detail the record cannot
             // hold (its own type, a `target`, or the absence of a value). Both are context,
@@ -344,7 +855,7 @@ inEventSubProcess = false) {
             // emits, so whether this fired depended on a detail of the source document that
             // has nothing to do with whether the field is set.
             const contextNames = contextView;
-            for (const field of missingRequiredContext(n.type, contextNames)) {
+            for (const field of missingRequiredContext(n.type, contextNames, n.spec)) {
                 diags.push({
                     level: 'error',
                     code: 'EMPTY_REQUIRED_FIELD',
@@ -354,7 +865,12 @@ inEventSubProcess = false) {
             }
             // The same rule over the PAYLOAD fields — the platform's RequiredFieldsRule
             // draws on both, so an unset required input is the same EMPTY_REQUIRED_FIELD.
-            for (const field of missingRequiredInputs(n.type, n.inputs, contextNames)) {
+            // The payload reaches a node the same two ways — `inputs`, or the verbatim
+            // `inputRows` — and both satisfy a required field.
+            const inputView = { ...n.inputs };
+            for (const row of n.inputRows ?? [])
+                inputView[row.name] = row.value ?? row.body ?? '';
+            for (const field of missingRequiredInputs(n.type, inputView, contextNames, n.spec)) {
                 diags.push({
                     level: 'error',
                     code: 'EMPTY_REQUIRED_FIELD',
@@ -370,7 +886,7 @@ inEventSubProcess = false) {
                     code: 'OUTPUT_ROWS_FIXED',
                     message: `"${n.id}" (${n.type}) permits only its declared output row, so the extra row(s) ` +
                         `${Object.keys(n.outputs ?? {}).map((k) => `"${k}"`).join(', ')} will be refused ` +
-                        `("output name must be \\"${registryType(n.type).output?.name}\\""). Use outputVar and read the ` +
+                        `("output name must be \\"${registryType(n.type, n.spec).output?.name}\\""). Use outputVar and read the ` +
                         `typed row instead.`,
                     where: n.id,
                 });
@@ -379,13 +895,13 @@ inEventSubProcess = false) {
             // not error: the node is as correct as the registry allows, so refusing it
             // would block work the platform, not the author, has to fix. Saying nothing
             // is worse — the artifact validates here and is rejected by the CLI.
-            const unsatisfiable = unsatisfiableRequiredInputs(n.type);
+            const unsatisfiable = unsatisfiableRequiredInputs(n.type, n.spec);
             if (unsatisfiable.length) {
                 diags.push({
                     level: 'warning',
                     code: 'REQUIRED_INPUT_UNSATISFIABLE',
                     message: `"${n.id}" (${n.type}) declares required input(s) ${unsatisfiable.map((f) => `"${f}"`).join(', ')}, ` +
-                        `but its "${registryType(n.type).inputPattern}" pattern merges every input into one row, so the ` +
+                        `but its "${registryType(n.type, n.spec).inputPattern}" pattern merges every input into one row, so the ` +
                         `platform's required-field rule cannot see them. \`uip maestro bpmn validate\` will report ` +
                         `EMPTY_REQUIRED_FIELD whatever this node carries — a platform defect, not an authoring error. ` +
                         `See docs/BPMN_COVERAGE_DESIGN.md D13.`,
@@ -417,7 +933,7 @@ function isStartElement(n) {
     if (n.kind !== 'typed')
         return false;
     try {
-        return registryType(n.type).element === 'bpmn:StartEvent';
+        return registryType(n.type, n.spec).element === 'bpmn:StartEvent';
     }
     catch {
         return false;