@uipath/maestro-builder-sdk 5.2.0

package/dist/bpmn/typed-node.js

@@ -0,0 +1,551 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const REGISTRY = require('./registry-types.json');
+/** Every extension type in the snapshot, sorted. */
+export function registryTypeNames() {
+    return Object.keys(REGISTRY.types).sort();
+}
+/**
+ * The spec for one extension type.
+ *
+ * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
+ * @returns Its emission spec.
+ * @throws If the type is not in the committed snapshot — which means either a
+ * typo or a registry refresh the snapshot has not caught up with.
+ */
+export function registryType(type) {
+    const spec = REGISTRY.types[type];
+    if (!spec) {
+        throw new Error(`unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types; ` +
+            'refresh it with `node scripts/materialize-bpmn-registry.mjs` if the platform added one.');
+    }
+    return spec;
+}
+/**
+ * Facts the platform enforces but the registry does not state.
+ *
+ * Every entry here was found by probing `uip maestro bpmn validate`, not read out
+ * of a spec — so every entry is a liability: it can drift without the snapshot
+ * changing, and nothing upstream promises it. Keeping them in one visible table
+ * beats burying them in a builder method, and each is pinned by a test so a
+ * platform change fails loudly instead of silently emitting a rejected artifact.
+ *
+ * `resourceSubType` — `Orchestrator.StartAgentJob` requires its process bindings to
+ * carry `resourceSubType="Agent"` on top of the `resource`/`propertyAttribute` the
+ * registry does give:
+ *
+ *     [error] Orchestrator.StartAgentJob binding "x" must target Agent name.
+ *
+ * `resource="Agent"` and `resource="agent"` are both rejected; only
+ * `resource="process"` + `resourceSubType="Agent"` validates. The string matches the
+ * field's `DisplayName`, but nothing says that is the rule, so it is recorded as a
+ * constant for the one type known to need it rather than derived.
+ */
+export const REGISTRY_GAPS = {
+    'Orchestrator.StartAgentJob': { resourceSubType: 'Agent' },
+    // `notEnforcedInputs` — required InputFields the platform does NOT actually enforce.
+    //
+    // MEASURED, on a real trigger that carries `connection`, `folderKey`, `connectorKey`,
+    // `operation`, `objectName` in its `uipath:context` and none of them as `uipath:input`
+    // rows. `uip maestro bpmn validate` reports exactly ONE error for it —
+    // `connectionId` — so it satisfies required fields from context (which
+    // `missingRequiredInputs` now does too) and does not ask for `folderId` or
+    // `folderPath` at all, though the registry marks both required.
+    //
+    // Without this the SDK rejects a trigger the CLI accepts. An earlier attempt
+    // suppressed the whole type instead, on the unfounded belief that the CLI accepted
+    // that artifact — it does not, and that made the SDK accept what the platform
+    // rejects. This is the narrow, checked version of that.
+    'Intsvc.EventTrigger': { notEnforcedInputs: ['folderId', 'folderPath'] },
+    'Intsvc.WaitForEvent': { notEnforcedInputs: ['folderId', 'folderPath'] },
+    // `extraContext` — context fields the PLATFORM accepts for a type but the
+    // registry's `ContextFields` does not list. Found when `bpmn-decompile`
+    // round-tripped a connector task and the strict unknown-field guard rejected
+    // `activity` and `resourceKey`, which `bpmn/connector.ts` has always emitted and
+    // which `uip maestro bpmn validate` has always accepted. So the guard was right
+    // that they are undeclared and wrong that they are invalid — recorded here rather
+    // than by loosening the guard, which is what catches an author's typo.
+    'Intsvc.ActivityExecution': { extraContext: ['activity', 'resourceKey'] },
+    // `outputRowsFixed` — the type permits EXACTLY the output row its spec declares.
+    // A mapped second row is refused:
+    //
+    //     [error] Maestro.ReceiveMessageEvent output name must be "response".
+    //     [error] Maestro.ReceiveMessageEvent output type must be "Maestro.ReceiveMessageEvent".
+    //
+    // Recorded rather than derived because the registry gives no way to tell. Compare
+    // `Actions.HITL`: a structurally IDENTICAL output declaration (typed row, no
+    // `source`, `relative: true`) which accepts a mapped second row — and has to, since
+    // that row is the only thing an offline approval branch can read. Two types, the
+    // same spec, opposite enforcement.
+    'Maestro.ReceiveMessageEvent': { outputRowsFixed: true },
+};
+/**
+ * An output name reduced to something an expression can actually read.
+ *
+ * Registry output names are DISPLAY names, and some contain spaces — the whole
+ * Orchestrator job family calls its output `Process response`. Interpolated
+ * straight into a default variable that yields `start_Process response`, which no
+ * `vars.<name>` reference can address. Camel-casing the words keeps the default
+ * predictable (`start_processResponse`) and legal; an author who wants a nicer name
+ * passes `outputVar`.
+ */
+function identifierize(name) {
+    const words = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    if (words.length === 0)
+        return 'response';
+    return words
+        .map((w, i) => (i === 0 ? w.charAt(0).toLowerCase() + w.slice(1) : w.charAt(0).toUpperCase() + w.slice(1)))
+        .join('');
+}
+/** The variable a typed node's output row writes, or `undefined` when it has none. */
+export function typedNodeOutputVar(id, type, outputVar) {
+    const spec = registryType(type);
+    if (!spec.output)
+        return undefined;
+    return outputVar ?? `${id}_${identifierize(spec.output.name)}`;
+}
+/**
+ * `uipath:context` — one scalar `uipath:input` per field the author supplied, or
+ * that the registry gives a default.
+ *
+ * A field is emitted when the author set it OR the registry declares a default.
+ * The registry's defaults are not cosmetic: `Intsvc.UnifiedHttpRequest` declares
+ * `mode: "manual"` as REQUIRED and HIDDEN, so an author never passes it and the
+ * artifact fails validation without it.
+ */
+/**
+ * A `json` context field's CDATA body.
+ *
+ * The field IS JSON — `metadata`, `headers`, `parameters`, `body`, `decisions` and
+ * the two case-rule fields are all declared `type="json"` in the registry — so an
+ * author writes the value, not a hand-encoded string of it. Before this,
+ * `String(value)` wrote `[object Object]` into the artifact for anything but a
+ * string, silently, and nothing offline caught it.
+ *
+ * A string still goes through untouched, which is both what every existing artifact
+ * and every prior caller passes, and the only way to write a body this SDK could
+ * not otherwise spell.
+ */
+function jsonBody(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function contextRows(m, type, spec, supplied, verbatim = false) {
+    const rows = [];
+    const emitted = new Set();
+    if (verbatim) {
+        // Supplied order, supplied fields, nothing added. The declared TYPE is still
+        // honoured, so a json field lands in the body rather than an attribute.
+        const byName = new Map(spec.context.map((f) => [f.name, f]));
+        for (const [name, value] of Object.entries(supplied)) {
+            if (value === undefined || value === null)
+                continue;
+            const fieldType = byName.get(name)?.type ?? 'string';
+            rows.push(fieldType === 'json'
+                ? m.create('uipath:Input', { name, type: fieldType, body: jsonBody(value) })
+                : m.create('uipath:Input', { name, type: fieldType, value: String(value) }));
+        }
+        return rows;
+    }
+    for (const field of spec.context) {
+        const value = supplied[field.name] ?? field.default;
+        if (value === undefined || value === null)
+            continue;
+        emitted.add(field.name);
+        // A `json` field goes in the CDATA BODY, not a `value` attribute. The product
+        // validator parses that field as JSON and reads the attribute WITHOUT XML
+        // entity decoding, so an attribute-borne object arrives as
+        // `{&#34;a&#34;:1}` and is reported as `context input "…" contains malformed
+        // JSON`. The connector emitter has always used the body for json inputs; this
+        // matches it. (Neither offline validator catches this — only the CLI does.)
+        rows.push(field.type === 'json'
+            ? m.create('uipath:Input', { name: field.name, type: field.type, body: jsonBody(value) })
+            : m.create('uipath:Input', { name: field.name, type: field.type, value: String(value) }));
+    }
+    // A value the registry does not declare is USUALLY a typo — the platform ignores
+    // it and the author never learns why their setting did nothing — so it is
+    // refused. The exception is a type with a recorded `extraContext` gap, where the
+    // platform is known to accept fields the registry omits.
+    const known = new Set([...spec.context.map((f) => f.name), ...(REGISTRY_GAPS[type]?.extraContext ?? [])]);
+    const unknown = Object.keys(supplied).filter((k) => !known.has(k));
+    if (unknown.length) {
+        throw new Error(`context field(s) ${unknown.map((u) => `"${u}"`).join(', ')} are not declared by this extension type. ` +
+            `Declared: ${[...known].join(', ') || '(none)'}.`);
+    }
+    // Permitted-but-undeclared fields (a recorded `extraContext` gap) still have to
+    // be WRITTEN. The loop above walks the registry's own list, so without this they
+    // passed the guard and were then silently dropped — which a round-trip caught.
+    for (const [name, value] of Object.entries(supplied)) {
+        if (emitted.has(name) || value === undefined || value === null)
+            continue;
+        rows.push(m.create('uipath:Input', { name, type: 'string', value: String(value) }));
+    }
+    return rows;
+}
+/**
+ * The payload rows, per the type's `inputPattern`.
+ *
+ * - `none` — the type takes no payload; anything supplied is an author error.
+ * - `mergedBody` / `splitInputsItemData` — one json input under the spec's
+ *   `inputName`/`inputTarget`, carrying the whole object.
+ * - `separateInputs` — the payload's own keys become sibling json inputs, which is
+ *   how the HTTP node's `headers`/`parameters`/`body` are addressed individually.
+ * - `scriptArgs` — handled by the script-task emitter, not here.
+ */
+function inputRows(m, spec, inputs) {
+    const keys = Object.keys(inputs);
+    if (spec.inputPattern === 'none') {
+        if (keys.length) {
+            throw new Error(`this extension type takes no inputs, but ${keys.length} were supplied (${keys.join(', ')}).`);
+        }
+        return [];
+    }
+    if (spec.inputPattern === 'separateInputs') {
+        // Sibling rows, one per supplied key.
+        //
+        // The target is NOT `spec.inputTarget`. That field names the single target for
+        // the one-row patterns, and applying it here collapsed every sibling onto the
+        // same target: a connector's three rows all came out `target="body"` instead of
+        // `pathParameters` / `queryParameters` / `body`, so an artifact authored through
+        // the generic `.activity()` sent path and query parameters in the request body.
+        //
+        // Nor is it always the key. The key was the fix for that collapse, and it is
+        // right for a type whose inputs are DYNAMIC — a connector's fields come from
+        // the connector library, not the registry, so the key is the only thing to go
+        // on. But a type that DECLARES its payload fields declares their target too,
+        // and the key is then wrong: `Maestro.ReceiveMessageEvent.Reference` targets
+        // `bodyField`, so keying it produced `target="Reference"` — a target the
+        // platform does not read, and one no validator complains about.
+        //
+        // So: the declared field decides when there is one, the key when there is not.
+        const declared = new Map(spec.inputs.map((f) => [f.name, f]));
+        return keys.map((k) => {
+            const field = declared.get(k);
+            return payloadInput(m, k, field?.target ?? k, inputs[k], field?.type ?? 'json');
+        });
+    }
+    if (!spec.inputName)
+        return [];
+    return [jsonInput(m, spec.inputName, spec.inputTarget ?? 'body', inputs)];
+}
+function jsonInput(m, name, target, value) {
+    const props = { name, type: 'json', body: JSON.stringify(value ?? {}) };
+    if (target)
+        props.target = target;
+    return m.create('uipath:Input', props);
+}
+/**
+ * One payload row, typed as the registry declares the field.
+ *
+ * The body/attribute split is the same rule `contextRows` follows and for the same
+ * measured reason: a structured value must be a CDATA BODY, because the product
+ * validator reads a `value` attribute without XML entity decoding and an
+ * object-bearing attribute comes back as `{&#34;a&#34;:1}`. A SCALAR is the
+ * opposite — JSON-encoding it into a body double-quotes it, so a string
+ * correlation reference arrived as `"ORD-1"` rather than `ORD-1`. Neither
+ * offline validator catches either direction.
+ *
+ * A structured field stays in the body even when its value is an `=`-expression.
+ * That is deliberate rather than an oversight: an expression inside a JSON body IS
+ * resolved — `<uipath:input name="ItemData" type="json" target="body">
+ * {"Reference":"=vars.ref"}` reports `VARIABLE_DOES_NOT_EXIST` against an
+ * undeclared variable, so the platform is reading it — whereas an expression in a
+ * `type="json"` ATTRIBUTE is a shape nothing here has verified.
+ */
+function payloadInput(m, name, target, value, type) {
+    const structured = type === 'json' || type === 'object' || type === 'array' || type === 'jsonSchema';
+    const props = structured
+        ? { name, type: 'json', body: JSON.stringify(value ?? {}) }
+        : { name, type, value: String(value ?? '') };
+    if (target)
+        props.target = target;
+    return m.create('uipath:Input', props);
+}
+/** The `uipath:output` row, when the type declares one. */
+function outputRow(m, spec, varName) {
+    if (!spec.output)
+        return undefined;
+    const props = { name: spec.output.name, type: spec.output.type, var: varName };
+    // Only when the registry gives one: several types declare an output with no
+    // source at all, and inventing `=<name>` for them would not round-trip.
+    if (spec.output.source)
+        props.source = spec.output.source;
+    return m.create('uipath:Output', props);
+}
+/** The moddle type name for an instance tag, e.g. `uipath:activity` → `uipath:Activity`. */
+function moddleTypeOf(tag) {
+    const [ns, local] = tag.split(':');
+    return `${ns}:${local.charAt(0).toUpperCase()}${local.slice(1)}`;
+}
+/**
+ * Emit a registry-backed typed node.
+ *
+ * @param m - The moddle instance to create elements with.
+ * @param id - The BPMN element id.
+ * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
+ * @param input - Author-supplied name, context, payload, output variable and skip.
+ * @returns The moddle element, ready for the serializer to wire flows onto.
+ */
+export function createTypedNode(m, id, type, input, 
+/**
+ * Declared Maestro `type` for a variable id, for typing the extra output rows below.
+ * Optional so a caller with no variable context still gets today's behaviour.
+ */
+varType) {
+    const spec = registryType(type);
+    if (!spec.element || !spec.tag) {
+        throw new Error(`extension type "${type}" has no element/tag in the registry snapshot; it cannot be authored.`);
+    }
+    const payload = {
+        version: 'v1',
+        type: m.create('uipath:Type', { value: type, version: input.typeVersion ?? 'v1' }),
+    };
+    // `skipCondition` exists on the activity/event tags only — a mapping cannot
+    // carry it, and moddle would silently drop it (see ActivityOpts in bpmn-sdk).
+    if (input.skipCondition !== undefined) {
+        if (spec.tag === 'uipath:mapping') {
+            throw new Error(`extension type "${type}" serializes a uipath:mapping, which cannot carry a skipCondition.`);
+        }
+        payload.skipCondition = input.skipCondition;
+    }
+    const ctx = input.contextRows
+        ? input.contextRows.map((row) => {
+            const props = { name: row.name, type: row.type ?? 'string' };
+            if (row.required)
+                props.required = 'true';
+            if (row.target !== undefined)
+                props.target = row.target;
+            if (row.value !== undefined)
+                props.value = row.value;
+            if (row.body !== undefined)
+                props.body = jsonBody(row.body);
+            return m.create('uipath:Input', props);
+        })
+        : contextRows(m, type, spec, input.context ?? {}, input.contextVerbatim);
+    // The schema is a sibling of the context's rows, and can be the only thing in it —
+    // a script task's context carries an inputSchema and no rows at all.
+    if (ctx.length || input.inputSchema !== undefined) {
+        const context = {};
+        if (ctx.length)
+            context.input = ctx;
+        if (input.inputSchema !== undefined) {
+            context.inputSchema = m.create('uipath:InputSchema', {
+                type: 'jsonSchema',
+                body: typeof input.inputSchema === 'string' ? input.inputSchema : JSON.stringify(input.inputSchema),
+            });
+        }
+        payload.context = m.create('uipath:Context', context);
+    }
+    const ins = inputRows(m, spec, input.inputs ?? {});
+    if (ins.length)
+        payload.input = ins;
+    const rows = [];
+    if (input.outputRows) {
+        // Spelled out by the caller: emit exactly these, deriving nothing. See
+        // TypedNodeInput.outputRows — this is what lets a connector's response schema
+        // survive a round trip.
+        rows.push(...verbatimOutputRows(m, input.outputRows));
+        if (rows.length)
+            payload.output = rows;
+        return finish(m, spec, id, input.name, payload);
+    }
+    const outVar = typedNodeOutputVar(id, type, input.outputVar);
+    const out = outVar ? outputRow(m, spec, outVar) : undefined;
+    if (out)
+        rows.push(out);
+    for (const [varId, source] of Object.entries(input.outputs ?? {})) {
+        // Type the row from the variable it writes, not `'string'` unconditionally.
+        //
+        // The runtime coerces a value by switching on this `type`, so a boolean captured as
+        // `type="string"` is the D1 hazard one layer along: the local engine evaluates the
+        // expression and gets a real boolean, but the platform is told the row is a string, and a
+        // gateway guarded on it can then branch on the truthy string `"false"`. It also made a
+        // boolean HITL decision unauthorable — `check_quality_boolean_decision.py` requires an
+        // output whose `type` is boolean and whose `var` binds a boolean variable.
+        //
+        // `'string'` remains the fallback for a variable this node writes without declaring,
+        // which is what every row did before.
+        rows.push(m.create('uipath:Output', { name: varId, type: varType?.(varId) ?? 'string', source, var: varId }));
+    }
+    if (rows.length)
+        payload.output = rows;
+    return finish(m, spec, id, input.name, payload);
+}
+/** `uipath:Output` rows exactly as the caller spelled them, deriving nothing. */
+export function verbatimOutputRows(m, rows) {
+    return rows.map((row) => {
+        const props = { name: row.name, type: row.type ?? 'string' };
+        if (row.source !== undefined)
+            props.source = row.source;
+        if (row.var !== undefined)
+            props.var = row.var;
+        if (row.custom)
+            props.custom = true;
+        if (row.description !== undefined)
+            props.description = row.description;
+        if (row.target !== undefined)
+            props.target = row.target;
+        if (row.schema !== undefined) {
+            props.body = typeof row.schema === 'string' ? row.schema : JSON.stringify(row.schema);
+        }
+        return m.create('uipath:Output', props);
+    });
+}
+/**
+ * The extension payload for a type and its output rows, with NO element around it.
+ *
+ * `createTypedNode` takes the element from the registry, which is right for an
+ * activity and wrong everywhere the product uses a payload as DECORATION: a
+ * `uipath:mapping` on a start event, an end event or a sub-process, a
+ * `uipath:activity` on an error boundary. Those arms of `createNode` build their
+ * own element and attach this to it, rather than letting `BPMN.Variables` turn a
+ * start event into a `bpmn:Task`.
+ *
+ * @param m - The moddle instance.
+ * @param type - The extension type, e.g. `BPMN.Variables` or `uipath:Activity`.
+ * @param rows - Output rows, emitted verbatim.
+ * @returns The payload element, ready to go inside a `bpmn:ExtensionElements`.
+ */
+export function createExtensionPayload(m, type, rows) {
+    const spec = registryType(type);
+    if (!spec.tag) {
+        throw new Error(`extension type "${type}" has no tag in the registry snapshot; it cannot be authored.`);
+    }
+    const payload = {
+        version: 'v1',
+        type: m.create('uipath:Type', { value: type, version: 'v1' }),
+    };
+    const out = verbatimOutputRows(m, rows);
+    if (out.length)
+        payload.output = out;
+    return m.create(moddleTypeOf(spec.tag), payload);
+}
+/** Wrap a finished payload in its BPMN element. */
+function finish(m, spec, id, name, payload) {
+    const props = {
+        id,
+        name,
+        extensionElements: m.create('bpmn:ExtensionElements', { values: [m.create(moddleTypeOf(spec.tag), payload)] }),
+    };
+    // What makes a message event a message event — without it the platform reads a
+    // plain intermediate event and the correlation never happens.
+    if (spec.eventDefinition) {
+        props.eventDefinitions = [m.create(moddleTypeOf(spec.eventDefinition), {})];
+    }
+    return m.create(moddleElementOf(spec.element), props);
+}
+/** `bpmn:SendTask` is already the moddle type name; keep it, but validate the shape. */
+function moddleElementOf(element) {
+    if (!/^bpmn:[A-Z]/.test(element)) {
+        throw new Error(`registry element "${element}" is not a moddle type name (expected e.g. bpmn:SendTask).`);
+    }
+    return element;
+}
+/**
+ * The context fields this type requires to be a `=bindings.<id>` reference rather
+ * than a literal.
+ *
+ * Narrower than it looks, and the narrowness is measured. `binding: true` marks a
+ * field the designer OFFERS a binding picker for — `Intsvc.UnifiedHttpRequest`'s
+ * `url` is one, and a literal URL validates fine. What the platform actually
+ * enforces is `bindingInfo` AND `required`, which today selects exactly
+ * `Orchestrator.StartAgentJob`'s `name` and `folderPath`:
+ *
+ *     [error] Orchestrator.StartAgentJob context input "name" must reference project bindings.
+ *     [error] Orchestrator.StartAgentJob binding "x" must target Agent name.
+ *
+ * Both halves are enforced — a literal is rejected, and so is a binding pointing
+ * at the wrong property.
+ *
+ * @param type - The extension type.
+ * @returns Its fields that must be bound, with the target each binding needs.
+ */
+export function bindingRequiredFields(type) {
+    return registryType(type).context.filter((f) => f.bindingInfo !== null && f.required);
+}
+/**
+ * Required context fields the author left unset and the registry cannot default.
+ *
+ * Separate from emission so `check()` can report them at authoring time. Missing
+ * them is what `uip maestro bpmn validate` reports as `EMPTY_REQUIRED_FIELD`, and
+ * hearing it from the SDK is faster than hearing it from the CLI.
+ *
+ * @param type - The extension type.
+ * @param context - The context values the author supplied.
+ * @returns The names of required fields with no value and no default.
+ */
+export function missingRequiredContext(type, context = {}) {
+    return registryType(type)
+        .context.filter((f) => f.required && context[f.name] === undefined && (f.default ?? '') === '')
+        .map((f) => f.name);
+}
+/**
+ * Required PAYLOAD fields the author left unset.
+ *
+ * The counterpart of {@link missingRequiredContext}, and reported the same way: the
+ * platform's `RequiredFieldsRule` draws on `InputFields` as well as `ContextFields`,
+ * so an unset required payload field is the same `EMPTY_REQUIRED_FIELD` the CLI
+ * would report a build later.
+ *
+ * @param type - The extension type.
+ * @param inputs - The payload the author supplied.
+ * @returns The names of required payload fields with no value and no default.
+ */
+export function missingRequiredInputs(type, inputs = {}, 
+/**
+ * The node's `uipath:context` values, which SATISFY a required payload field too.
+ *
+ * The platform's `RequiredFieldsRule` draws on both, and a trigger is where that
+ * shows: `Intsvc.EventTrigger` declares seven required inputs, and a real one
+ * carries every one of them as a `uipath:context` row rather than a
+ * `uipath:input`. Checking inputs alone reported all seven; `uip maestro bpmn
+ * validate` reports exactly one — `connectionId`, the only name the artifact
+ * genuinely does not spell (it writes `connection`). Reading both makes this
+ * agree with the CLI instead of guessing on either side of it.
+ */
+context = {}) {
+    const notEnforced = new Set(REGISTRY_GAPS[type]?.notEnforcedInputs ?? []);
+    return registryType(type)
+        .inputs.filter((f) => f.required &&
+        !notEnforced.has(f.name) &&
+        inputs[f.name] === undefined &&
+        context[f.name] === undefined &&
+        (f.default ?? '') === '')
+        .map((f) => f.name);
+}
+/**
+ * Whether this type's required payload fields are UNSATISFIABLE on the wire.
+ *
+ * A platform defect, recorded here because the SDK cannot emit its way around it.
+ * `RequiredFieldsRule` builds its required-name set from `InputFields` and then
+ * fires when a name is absent from the serialized rows **by name**. Under
+ * `mergedBody` and `splitInputsItemData` every payload field collapses into ONE row
+ * — named `body` or `ItemData` — so a required input field is never present by
+ * name and the rule fires however the node is filled in:
+ *
+ *     [error] [call] EMPTY_REQUIRED_FIELD: The field 'agentUrl' in node 'call' is
+ *                    required but has no value.
+ *
+ * Note the registry's own `XmlTemplate` for `A2A.AgentExecution` emits exactly the
+ * body-only shape that fails, which is the clearest statement that the two halves
+ * of the platform disagree rather than that the SDK is writing the wrong thing.
+ *
+ * Whether a workaround exists is per-type and not derivable from the spec, so it is
+ * not encoded here. Measured: `A2A.AgentExecution` accepts redundant sibling rows
+ * alongside the merged body (`Valid`); `Maestro.SendMessageEvent` refuses them
+ * outright — `does not support input payload "Reference"` as a row, `does not
+ * support context input "Reference"` in context, and `ItemData`'s `target="body"`
+ * is enforced — so for that type NO artifact satisfies both gates.
+ *
+ * Selects exactly `A2A.AgentExecution` and `Maestro.SendMessageEvent` today. The
+ * three other types with required payload fields are `separateInputs`, whose rows
+ * DO carry their own names, and are unaffected.
+ *
+ * @param type - The extension type.
+ * @returns The required payload field names that cannot be expressed, or `[]`.
+ */
+export function unsatisfiableRequiredInputs(type) {
+    const spec = registryType(type);
+    if (spec.inputPattern !== 'mergedBody' && spec.inputPattern !== 'splitInputsItemData')
+        return [];
+    return spec.inputs.filter((f) => f.required).map((f) => f.name);
+}