@uipath/maestro-builder-sdk 5.2.0

package/dist/bpmn/format-profile.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The BPMN document-format profile.
+ *
+ * BPMN's schema version is `uipath:migrationVersion` — the Canvas schema
+ * generation the document targets, e.g. `11` or `11.5`. It is the odd one of
+ * the three families, and the policy below says so rather than pretending
+ * otherwise:
+ *
+ *  - **There is no pin.** Flow and Case each write one version by default;
+ *    BPMN writes NONE. An empty `uipath:migrationVersion` fails product
+ *    validation outright, so absent beats blank, and a process that never
+ *    declared one keeps declaring nothing.
+ *  - **The SDK's emission does not vary with it.** The `.bpmn` this SDK writes
+ *    is the same XML whatever generation is stamped on it, so unlike Flow's
+ *    file format and Case's grammar, the value is a stamp carried through
+ *    rather than a claim the serializer has to satisfy. That is what `mode:
+ *    'verbatim'` means: any non-empty stamp is accepted, because refusing an
+ *    unfamiliar one would DROP what the platform wrote — the exact loss this is
+ *    here to prevent (Studio Web stamps it on export and some graders require
+ *    it).
+ *
+ * So `.schemaVersion()` here is the named surface for the same field
+ * `.metadata({ migrationVersion })` has always set, and both spellings remain
+ * valid on the same document.
+ */
+import type { SchemaVersionPolicy } from '../schema-version.js';
+export declare const BPMN_SCHEMA_VERSIONS: SchemaVersionPolicy;

package/dist/bpmn/format-profile.js

@@ -0,0 +1,11 @@
+export const BPMN_SCHEMA_VERSIONS = {
+    family: 'bpmn',
+    mode: 'verbatim',
+    method: '.schemaVersion',
+    // No default: the document declares nothing unless the author (or the file a
+    // decompile read) says otherwise.
+    default: undefined,
+    migration: 'A Canvas schema generation is stamped by the product on export; this SDK carries the stamp through '
+        + 'and never rewrites it.',
+    writable: [],
+};

package/dist/bpmn/intsvc.d.ts

@@ -0,0 +1,77 @@
+/**
+ * bpmn/intsvc — the Phase 3d Integration Service node families.
+ *
+ * Two families, four extension types, and **no bespoke emitter**: each resolves a
+ * connector descriptor from the library, turns it into the `context`/`inputs` the
+ * registry declares, and hands that to the spec-driven `createTypedNode`. That is
+ * the Phase 3a bet paying off — once `InputFields` reached the snapshot (D12), the
+ * `separateInputs` path already emitted these correctly, so 3d is resolution and
+ * wiring rather than emission. All four shapes were validated against
+ * `uip maestro bpmn validate` as plain `.activity()` calls before this module
+ * existed.
+ *
+ * - **Connector events** (`Intsvc.EventTrigger` / `Intsvc.WaitForEvent`) — one
+ *   connector operation, two placements. `trigger` starts the process, `event`
+ *   pauses one mid-flow; the platform ships both with the same operation and only
+ *   the library namespace differs, exactly as Flow's `onEvent()` / `waitForEvent()`
+ *   pair does.
+ * - **External agent / workflow** (`Intsvc.{Sync,Async}AgentExecution`,
+ *   `Intsvc.{Sync,Async}WorkflowExecution`) — an invocation of something outside
+ *   this process, picked by the descriptor's `operation.subType` and the author's
+ *   `mode`. The same four types the Case SDK reaches through `.externalAgent()` /
+ *   `.externalWorkflow()`; the serviceType mapping is deliberately identical to
+ *   `case/format-profile.ts` so one artifact family cannot drift from the other.
+ */
+import type { ModdleElement } from 'bpmn-moddle';
+import type { BpmnNode } from './bpmn-sdk.js';
+import { type ConnectorCtx } from './connector.js';
+type El = ModdleElement;
+type EventNode = Extract<BpmnNode, {
+    kind: 'connectorEvent';
+}>;
+type ExternalNode = Extract<BpmnNode, {
+    kind: 'externalTask';
+}>;
+/**
+ * The extension type a Phase 3d node lowers to, WITHOUT consulting the library.
+ *
+ * The emitters below take a connector event's type from the library's
+ * `runtime.serviceType`, which is the authority. This is the same answer derived
+ * from the node alone, so the serializer can declare the node's output variable
+ * before it has resolved anything — and the emitter asserts the two agree, so the
+ * shortcut cannot silently diverge.
+ */
+export declare function intsvcServiceType(n: EventNode | ExternalNode): string;
+/**
+ * The variable a Phase 3d node's own output row writes.
+ *
+ * Derived from the registry spec's OUTPUT NAME rather than assumed: the event
+ * family names its output `result` and the agent/workflow family names it
+ * `response`, so hardcoding either one declares a variable the row does not use.
+ * That mismatch is invisible to both validators and was caught only by the
+ * round-trip gate.
+ */
+export declare function intsvcOutputVar(n: EventNode | ExternalNode): string | undefined;
+/**
+ * A connector event node — `Intsvc.EventTrigger` or `Intsvc.WaitForEvent`.
+ *
+ * The extension type comes from the LIBRARY (`runtime.serviceType`), not from the
+ * method the author called. That is deliberate: the descriptor is the authority on
+ * which placement it describes, so a `trigger` descriptor reached through
+ * `.waitForEvent()` is caught here rather than emitting a start-event type onto a
+ * receive task — a mismatch both offline validators accept.
+ *
+ * @param ctx - Serializer context: moddle, library, bindings, binding sink.
+ * @param n - The authored node.
+ * @returns The moddle element.
+ */
+export declare function createConnectorEvent(ctx: ConnectorCtx, n: EventNode): El;
+/**
+ * An external agent / workflow invocation.
+ *
+ * @param ctx - Serializer context: moddle, library, bindings, binding sink.
+ * @param n - The authored node.
+ * @returns The moddle element.
+ */
+export declare function createExternalTask(ctx: ConnectorCtx, n: ExternalNode): El;
+export {};

package/dist/bpmn/intsvc.js

@@ -0,0 +1,155 @@
+import { createTypedNode, typedNodeOutputVar } from './typed-node.js';
+import { connectorBindingRef } from './connector.js';
+/**
+ * Which extension type an external invocation lowers to.
+ *
+ * Kept as a literal table rather than string-built so a typo is a compile error,
+ * and mirrored field-for-field from `CASE_FORMAT_PROFILE` — the Case SDK reaches
+ * the same four types, and the two must agree.
+ */
+const EXTERNAL_SERVICE_TYPE = {
+    agent: { sync: 'Intsvc.SyncAgentExecution', async: 'Intsvc.AsyncAgentExecution' },
+    workflow: { sync: 'Intsvc.SyncWorkflowExecution', async: 'Intsvc.AsyncWorkflowExecution' },
+};
+/** The descriptor `subType` each family requires, per `case/serialize.ts`. */
+const EXTERNAL_SUBTYPE = { agent: 'AgentExecution', workflow: 'ProcessExecution' };
+/** Which extension type a connector-event node lowers to, by placement. */
+const EVENT_SERVICE_TYPE = { trigger: 'Intsvc.EventTrigger', event: 'Intsvc.WaitForEvent' };
+/**
+ * The extension type a Phase 3d node lowers to, WITHOUT consulting the library.
+ *
+ * The emitters below take a connector event's type from the library's
+ * `runtime.serviceType`, which is the authority. This is the same answer derived
+ * from the node alone, so the serializer can declare the node's output variable
+ * before it has resolved anything — and the emitter asserts the two agree, so the
+ * shortcut cannot silently diverge.
+ */
+export function intsvcServiceType(n) {
+    return n.kind === 'connectorEvent'
+        ? EVENT_SERVICE_TYPE[n.subscribe]
+        : EXTERNAL_SERVICE_TYPE[n.family][n.mode];
+}
+/**
+ * The variable a Phase 3d node's own output row writes.
+ *
+ * Derived from the registry spec's OUTPUT NAME rather than assumed: the event
+ * family names its output `result` and the agent/workflow family names it
+ * `response`, so hardcoding either one declares a variable the row does not use.
+ * That mismatch is invisible to both validators and was caught only by the
+ * round-trip gate.
+ */
+export function intsvcOutputVar(n) {
+    return typedNodeOutputVar(n.id, intsvcServiceType(n), n.outputVar);
+}
+/**
+ * A connector event node — `Intsvc.EventTrigger` or `Intsvc.WaitForEvent`.
+ *
+ * The extension type comes from the LIBRARY (`runtime.serviceType`), not from the
+ * method the author called. That is deliberate: the descriptor is the authority on
+ * which placement it describes, so a `trigger` descriptor reached through
+ * `.waitForEvent()` is caught here rather than emitting a start-event type onto a
+ * receive task — a mismatch both offline validators accept.
+ *
+ * @param ctx - Serializer context: moddle, library, bindings, binding sink.
+ * @param n - The authored node.
+ * @returns The moddle element.
+ */
+export function createConnectorEvent(ctx, n) {
+    if (!ctx.library)
+        throw new Error(`connector event "${n.id}" needs the connector library — pass { library } to serialize ` +
+            `or use uip maestro bpmn compile --library.`);
+    const rc = ctx.library.resolveEvent(n.subscribe, n.key, n.eventName, n.version);
+    const op = (rc.entry.operation ?? {});
+    const runtime = rc.entry.runtime ?? {};
+    const type = runtime.serviceType;
+    if (!type) {
+        throw new Error(`connector event ${n.key}/${n.eventName} has no runtime.serviceType in the library; ` +
+            `it cannot be authored as a BPMN node.`);
+    }
+    // The library is the authority, but the serializer has already declared this
+    // node's output variable from the placement alone (`intsvcServiceType`). If the
+    // two ever disagree, that variable is wrong — so say so rather than emit it.
+    const expected = intsvcServiceType(n);
+    if (type !== expected) {
+        throw new Error(`connector event "${n.id}" was authored as a ${n.subscribe} (${expected}), but the library ` +
+            `describes ${n.key}/${n.eventName} as ${type}. Use ` +
+            `${type === 'Intsvc.EventTrigger' ? '.eventTrigger()' : '.waitForEvent()'} instead.`);
+    }
+    const conn = connectorBindingRef(ctx, n.connection, 'Connection', 'ConnectionId', `${rc.connectorKey} connection`);
+    const folder = connectorBindingRef(ctx, n.folder, 'Connection', 'folderKey', 'FolderKey');
+    if (!conn || !folder) {
+        throw new Error(`connector event "${n.id}" needs both a connection and a folder binding name — ` +
+            `the type declares connectionId, folderId, folderPath and folderKey all required.`);
+    }
+    // The registry marks `operation` and `objectName` required AND hidden, so an
+    // author never passes them; they come off the descriptor, the same way `.http()`
+    // takes `mode` from a registry default.
+    const inputs = {
+        connectionId: `=bindings.${conn.id}`,
+        connectorKey: rc.connectorKey,
+        folderId: `=bindings.${folder.id}`,
+        folderPath: n.folderPath ?? '/Shared',
+        folderKey: `=bindings.${folder.id}`,
+        operation: op.eventOperation ?? '',
+        objectName: op.objectName ?? '',
+    };
+    if (n.filter !== undefined)
+        inputs.filter = n.filter;
+    if (n.parameters !== undefined)
+        inputs.parameters = n.parameters;
+    return createTypedNode(ctx.m, n.id, type, {
+        name: n.name ?? rc.entry.display?.label ?? n.eventName,
+        inputs,
+        outputVar: n.outputVar,
+        outputs: n.outputs,
+        skipCondition: n.skipCondition,
+    }, (varId) => ctx.varTypeOf?.(varId));
+}
+/**
+ * An external agent / workflow invocation.
+ *
+ * @param ctx - Serializer context: moddle, library, bindings, binding sink.
+ * @param n - The authored node.
+ * @returns The moddle element.
+ */
+export function createExternalTask(ctx, n) {
+    if (!ctx.library)
+        throw new Error(`external ${n.family} "${n.id}" needs the connector library — pass { library } to serialize ` +
+            `or use uip maestro bpmn compile --library.`);
+    const rc = ctx.library.resolve(n.key, n.action, n.version);
+    const op = (rc.entry.operation ?? {});
+    const wanted = EXTERNAL_SUBTYPE[n.family];
+    // The library is the authority on what a descriptor IS. Without this check an
+    // ordinary connector action authored as an external agent emits a node the
+    // validator accepts and the runtime dispatches to the wrong handler family —
+    // the Case SDK records the same trap in its Phase 4.4 notes.
+    if (op.subType !== wanted) {
+        throw new Error(`external ${n.family} "${n.id}" needs ${wanted === 'AgentExecution' ? 'an' : 'a'} ${wanted} descriptor, but ` +
+            `${n.key}/${n.action} is "${String(op.subType ?? 'untyped')}". ` +
+            `The shipped library has very few of these — ${wanted === 'AgentExecution' ? '2' : '1'} operation(s).`);
+    }
+    const conn = connectorBindingRef(ctx, n.connection, 'Connection', 'ConnectionId', `${rc.connectorKey} connection`);
+    const folder = connectorBindingRef(ctx, n.folder, 'Connection', 'folderKey', 'FolderKey');
+    if (!conn || !folder) {
+        throw new Error(`external ${n.family} "${n.id}" needs both a connection and a folder binding name.`);
+    }
+    return createTypedNode(ctx.m, n.id, EXTERNAL_SERVICE_TYPE[n.family][n.mode], {
+        name: n.name ?? rc.entry.display?.label ?? n.action,
+        context: {
+            // `activity` is the ACTIVITY TYPE ID, not the operation name — the one place
+            // this family differs from `.connector()`, and what `case/serialize.ts` uses.
+            activity: rc.activityTypeId ?? '',
+            connectorKey: rc.connectorKey,
+            connection: `=bindings.${conn.id}`,
+            folderKey: `=bindings.${folder.id}`,
+            method: rc.httpMethod || 'POST',
+            path: rc.endpoint || '',
+        },
+        // One merged `body` row, as the type's own XmlTemplate shows — not the
+        // path/query/body split a connector activity uses.
+        inputs: { body: n.inputs },
+        outputVar: n.outputVar,
+        outputs: n.outputs,
+        skipCondition: n.skipCondition,
+    }, (varId) => ctx.varTypeOf?.(varId));
+}

package/dist/bpmn/load.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltBpmn } from './bpmn-sdk.js';
+/** Resolve a user argument (a `.ts` path or a BaseName) to a bpmn source file. */
+export declare function resolveBpmnFile(arg: string): string;
+export declare function loadBuiltBpmn(file: string): Promise<BuiltBpmn>;

package/dist/bpmn/load.js

@@ -0,0 +1,22 @@
+/** Shared: dynamic-import an authored bpmn module and return its BuiltBpmn. */
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+/** Resolve a user argument (a `.ts` path or a BaseName) to a bpmn source file. */
+export function resolveBpmnFile(arg) {
+    const candidates = [arg, `${arg}.bpmn.ts`, `${arg}.ts`];
+    for (const c of candidates)
+        if (existsSync(resolve(c)))
+            return resolve(c);
+    throw new Error(`bpmn source not found: tried ${candidates.join(', ')}`);
+}
+export async function loadBuiltBpmn(file) {
+    const mod = await import(pathToFileURL(file).href);
+    const exp = mod.default ?? mod.bpmn;
+    if (!exp)
+        throw new Error(`${file} has no default export. Add: export default bpmn('id')...build();`);
+    const built = typeof exp.build === 'function' ? exp.build() : exp;
+    if (!built || !Array.isArray(built.nodes))
+        throw new Error(`${file} default export is not a built bpmn. Did you call .build()?`);
+    return built;
+}

package/dist/bpmn/merge-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { type CliExitCode } from '../cli-run.js';
+export declare function run(argv: string[]): CliExitCode;

package/dist/bpmn/merge-cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * merge-cli — merge an edited process back into the original `.bpmn` (bin `bpmn-merge`)
+ *
+ * Usage:
+ *   bpmn-merge <original.bpmn> <edited.bpmn> [-o merged.bpmn] [--baseline <baseline.bpmn>]
+ *
+ * `edited.bpmn` is compile(decompile(original)) after your edits. `--baseline` is
+ * compile(decompile(original)) BEFORE any edit — supplying it enables the delta merge, so
+ * every element you did not touch is emitted from the original byte for byte. Omit it for
+ * a two-way merge (take the edited process, keep the original diagram). See merge.ts.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { mergeBpmn } from './merge.js';
+import { runWhenInvokedDirectly } from '../cli-run.js';
+function opt(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+export function run(argv) {
+    if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+        console.error('usage: bpmn-merge <original.bpmn> <edited.bpmn> [-o merged.bpmn] [--baseline <baseline.bpmn>]');
+        return 2;
+    }
+    const flags = new Set(['-o', '--baseline']);
+    const positionals = argv.filter((a, i) => !flags.has(a) && !flags.has(argv[i - 1]) && !a.startsWith('-'));
+    const [originalPath, editedPath] = positionals;
+    if (!originalPath || !editedPath) {
+        console.error('bpmn-merge: need <original.bpmn> and <edited.bpmn>');
+        return 2;
+    }
+    const baselinePath = opt(argv, '--baseline');
+    const result = mergeBpmn(readFileSync(originalPath, 'utf8'), readFileSync(editedPath, 'utf8'), {
+        ...(baselinePath ? { baseline: readFileSync(baselinePath, 'utf8') } : {}),
+    });
+    const out = opt(argv, '-o') ?? 'merged.bpmn';
+    writeFileSync(out, result.xml);
+    // Say what was kept and what was rewritten: on a surgical edit the preserved count
+    // should dwarf the authored one, and a reader who sees otherwise has learned something.
+    console.log(`bpmn-merge: wrote ${basename(out)} (${result.preserved.length} preserved, ` +
+        `${result.authored.length} authored, ${result.removed.length} removed)`);
+    return 0;
+}
+runWhenInvokedDirectly(import.meta.url, 'bpmn-merge', run);

package/dist/bpmn/merge.d.ts

@@ -0,0 +1,19 @@
+export interface BpmnMergeOptions {
+    /**
+     * `compile(decompile(original))` captured BEFORE the author's edits — what a faithful
+     * round trip of the original produces. Enables the delta merge: an element identical
+     * to its baseline counterpart is treated as untouched and emitted from the original.
+     * Omit for a two-way merge (take `edited`, re-attach the original diagram).
+     */
+    baseline?: string;
+}
+export interface BpmnMergeResult {
+    xml: string;
+    /** Element ids emitted from the original verbatim (payload preserved). */
+    preserved: string[];
+    /** Element ids taken from the edited document (authored, or newly added). */
+    authored: string[];
+    /** Element ids present in the original but gone from the edited process. */
+    removed: string[];
+}
+export declare function mergeBpmn(originalXml: string, editedXml: string, options?: BpmnMergeOptions): BpmnMergeResult;

package/dist/bpmn/merge.js

@@ -0,0 +1,293 @@
+/**
+ * merge — write a decompiled-then-edited process back into the ORIGINAL `.bpmn`,
+ * splicing in only what changed and leaving everything else byte for byte alone.
+ *
+ * The brownfield pipeline, the BPMN counterpart of `src/merge.ts`:
+ *
+ *   original.bpmn --decompile--> X.bpmn.ts --(edit)--> --compile--> edited.bpmn
+ *   baseline.bpmn = compile(decompile(original))            # BEFORE any edit
+ *   mergeBpmn(original, edited, { baseline })  -->  merged.bpmn
+ *
+ * Why not just keep `edited`? Because decompile is **semantically** lossless, not
+ * attribute-for-attribute: it discards the diagram, and it normalises payload detail the
+ * builder models by intent rather than by wire text (an output row keyed by a variable
+ * comes back named after that variable, losing a distinct row `name`). Taking `edited`
+ * wholesale rewrites every element in the file, including the ones the author never
+ * looked at — which is exactly what a brownfield edit must not do.
+ *
+ * The merge is therefore a **delta**, and it turns on one observation: those
+ * normalisations are UNIFORM, so they land on `baseline` and on `edited` identically. An
+ * element the author did not touch is byte-identical between the two — and when it is,
+ * the merge emits the element from the ORIGINAL. The original XML is the carrier for the
+ * wire detail the builder does not model, so the builder never has to model it.
+ *
+ * Without a `baseline` the merge is two-way: take the edited process, re-attach the
+ * original diagram by element id. Correct whenever decompile was faithful for every
+ * element, and still much better than a bare recompile, which drops layout entirely.
+ *
+ * ## Two things that differ from the flow merge
+ *
+ * 1. **Wiring lives inside the element.** A flow node's edges are separate objects, so
+ *    `mergeFlow` can swap a whole node. A BPMN element carries `bpmn:incoming` /
+ *    `bpmn:outgoing` as children, so a reorder changes an element whose payload is
+ *    untouched. The comparison here therefore ignores wiring, and a preserved element
+ *    adopts the EDITED wiring while keeping its ORIGINAL payload. Without that,
+ *    reordering two tasks either loses their payloads or restores the old order.
+ *
+ * 2. **`bpmn:extensionElements` has no id**, so the process-level block is merged by
+ *    role rather than by key: the author's `uipath:variables` wins (they may have
+ *    declared one), and every other child — `migrationVersion`, `caseManagement`, and
+ *    anything else a future platform version puts there — comes from the original
+ *    untouched. Nothing in this file needs to know what those payloads mean.
+ *
+ * ## What it deliberately does NOT preserve
+ *
+ * A bare `<uipath:input name="args">`. `uip maestro bpmn validate` rejects it — the row
+ * must declare `type="json"` and target `"bodyField"` — so an original missing them is
+ * invalid, and the recompiled form is the correct one. Preserving that faithfully would
+ * mean preserving invalid markup. It is not a special case in the code: such a row only
+ * ever appears inside an element the author edited, which is taken from `edited` anyway.
+ * Recorded here because it is the one difference a reader will expect to see handled.
+ */
+import { findByLocal, parseXmlRanges } from './xml-ranges.js';
+const WIRING = new Set(['incoming', 'outgoing']);
+function processOf(xml, label) {
+    const process = findByLocal(parseXmlRanges(xml), 'process');
+    if (!process)
+        throw new Error(`merge: ${label} has no bpmn:process`);
+    return process;
+}
+/** The element's own source text. */
+function textOf(xml, range) {
+    return xml.slice(range.start, range.end);
+}
+/**
+ * The element's text with its wiring children removed and whitespace flattened — the
+ * form two documents are compared in to answer "did the author touch this element?".
+ *
+ * A textual comparison is exact here, not an approximation: `baseline` and `edited` are
+ * both output of the same serializer from the same source shape, so identical intent
+ * produces identical bytes. Structural canonicalisation would be strictly more code for
+ * the same answer.
+ */
+function withoutWiring(xml, range) {
+    const cuts = range.children.filter((c) => WIRING.has(c.local));
+    let text = '';
+    let at = range.start;
+    for (const cut of cuts) {
+        text += xml.slice(at, cut.start);
+        at = cut.end;
+    }
+    text += xml.slice(at, range.end);
+    return text.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Graft the edited element's wiring onto the original element's text.
+ *
+ * The edited wiring is written where the original's first wiring child sat, so the
+ * children stay in schema order (`extensionElements` before `incoming`/`outgoing`). An
+ * element with no wiring in either document is returned untouched.
+ */
+function withWiringFrom(originalXml, original, editedXml, edited) {
+    const originalWiring = original.children.filter((c) => WIRING.has(c.local));
+    const editedWiring = edited.children.filter((c) => WIRING.has(c.local));
+    // When the wiring is the same, the element is returned untouched — no reflowing. This
+    // is not an optimisation: splicing identical content back in still rewrites the
+    // element's whitespace, and an original that put `<bpmn:incoming/>` and
+    // `<bpmn:outgoing/>` on one line would come back on two. That is a diff on an element
+    // nobody edited, which is the one thing this function exists to avoid.
+    const wiringOf = (xml, w) => w.map((c) => `${c.local}=${xml.slice(c.innerStart, c.innerEnd).trim()}`).join(',');
+    if (wiringOf(originalXml, originalWiring) === wiringOf(editedXml, editedWiring)) {
+        return textOf(originalXml, original);
+    }
+    const replacement = editedWiring.map((w) => editedXml.slice(w.start, w.end));
+    // Indentation of the first wiring child, so the grafted lines sit where the old ones did.
+    const anchor = originalWiring[0];
+    const indent = anchor
+        ? (/([ \t]*)$/.exec(originalXml.slice(original.innerStart, anchor.start))?.[1] ?? '')
+        : '';
+    if (originalWiring.length === 0) {
+        // Nothing to replace: insert before the close tag.
+        const head = originalXml.slice(original.start, original.innerEnd);
+        const tail = originalXml.slice(original.innerEnd, original.end);
+        const block = replacement.map((w) => `${indent}  ${w}\n`).join('');
+        return `${head}${block}${indent}${tail}`;
+    }
+    let text = '';
+    let at = original.start;
+    let first = true;
+    for (const w of originalWiring) {
+        text += originalXml.slice(at, w.start);
+        if (first) {
+            text += replacement.join(`\n${indent}`);
+            first = false;
+        }
+        else {
+            // A second or later wiring child: its own text is dropped, and so is the
+            // separator that preceded it, which the slice above already added.
+            text = text.replace(/\s+$/, '');
+        }
+        at = w.end;
+    }
+    text += originalXml.slice(at, original.end);
+    return text;
+}
+/**
+ * Children of the process-level `bpmn:extensionElements` that the BUILDER can author, and
+ * which therefore come from the EDITED document.
+ *
+ * This is the whole rule for that block, which has no id and so cannot be merged by key:
+ * anything the builder models is the author's to change, and anything it does not model is
+ * preserve-only and comes from the original untouched. Nothing here needs to know what
+ * these payloads mean — only who owns them.
+ *
+ * It started as `variables` alone, which was too narrow and wrong in a way worth
+ * recording: a task that sanitized a `uipath:binding` default — replacing a real
+ * connection id with a placeholder — produced a merged file with the private value still
+ * in it, because bindings were treated as preserve-only. The author had changed them and
+ * the merge quietly put them back. Metadata is on the list for the same reason: `.metadata()`
+ * has been authorable since #474, so a changed `migrationVersion` must land too.
+ */
+const AUTHORED_EXTENSIONS = new Set([
+    'variables',
+    'bindings',
+    'migrationVersion',
+    'entryPointId',
+    'tags',
+    'caseManagement',
+]);
+/**
+ * Merge the process-level `bpmn:extensionElements`.
+ *
+ * Same delta logic as the elements: an authorable child is taken from the edited document
+ * only when the author actually CHANGED it, judged against the baseline. Ownership alone
+ * is not enough — taking every authorable child from the edited document rewrote ones
+ * nobody touched, and `caseManagement`'s `<![CDATA[…]]>` came back as plain text. Same
+ * value, but a diff on a block the author never opened, which is the thing this file
+ * exists to avoid.
+ *
+ * With no baseline there is nothing to compare against, so an authorable child comes from
+ * the edited document — the same fallback the two-way element merge makes.
+ */
+function mergeExtensionElements(originalXml, original, editedXml, edited, baselineXml, baseline) {
+    if (!original)
+        return edited ? textOf(editedXml, edited) : undefined;
+    if (!edited)
+        return textOf(originalXml, original);
+    const baselineByLocal = new Map((baseline?.children ?? []).map((c) => [c.local, c]));
+    const flat = (xml, r) => xml.slice(r.start, r.end).replace(/\s+/g, ' ').trim();
+    /** Did the author change this child, relative to a faithful round trip of the original? */
+    const changed = (child) => {
+        if (!baselineXml)
+            return true;
+        const base = baselineByLocal.get(child.local);
+        if (!base)
+            return true;
+        return flat(editedXml, child) !== flat(baselineXml, base);
+    };
+    const editedByLocal = new Map(edited.children.filter((c) => changed(c)).map((c) => [c.local, c]));
+    const seen = new Set();
+    // Walk the ORIGINAL's children so its order and formatting lead, substituting each
+    // authored child with the edited document's version of it.
+    let body = '';
+    let at = original.innerStart;
+    for (const child of original.children) {
+        body += originalXml.slice(at, child.start);
+        const replacement = AUTHORED_EXTENSIONS.has(child.local)
+            ? editedByLocal.get(child.local)
+            : undefined;
+        if (replacement) {
+            body += editedXml.slice(replacement.start, replacement.end);
+            seen.add(child.local);
+        }
+        else if (AUTHORED_EXTENSIONS.has(child.local) &&
+            baselineByLocal.has(child.local) &&
+            !edited.children.some((c) => c.local === child.local)) {
+            // The author DELETED it (e.g. dropped every binding): the baseline had it and the
+            // edit does not. Skip it, and the whitespace that preceded it, so no blank line is
+            // left behind. Requires a baseline — without one, absence is indistinguishable from
+            // a child the round trip never carried.
+            body = body.replace(/\s+$/, '');
+            seen.add(child.local);
+        }
+        else {
+            body += originalXml.slice(child.start, child.end);
+        }
+        at = child.end;
+    }
+    body += originalXml.slice(at, original.innerEnd);
+    // Authored children the original did not have at all — the author ADDED a block.
+    const indent = /([ \t]*)$/.exec(originalXml.slice(original.innerStart, original.children[0]?.start ?? original.innerEnd))?.[1] ?? '';
+    for (const child of edited.children) {
+        if (AUTHORED_EXTENSIONS.has(child.local) && !seen.has(child.local) && !original.children.some((c) => c.local === child.local)) {
+            body += `${indent}${editedXml.slice(child.start, child.end)}\n`;
+        }
+    }
+    return (originalXml.slice(original.start, original.innerStart) +
+        body +
+        originalXml.slice(original.innerEnd, original.end));
+}
+export function mergeBpmn(originalXml, editedXml, options = {}) {
+    const originalProcess = processOf(originalXml, 'original');
+    const editedProcess = processOf(editedXml, 'edited');
+    const baselineProcess = options.baseline ? processOf(options.baseline, 'baseline') : undefined;
+    const byId = (p) => new Map(p.children.filter((c) => c.id !== undefined).map((c) => [c.id, c]));
+    const originalById = byId(originalProcess);
+    const baselineById = baselineProcess ? byId(baselineProcess) : new Map();
+    const preserved = [];
+    const authored = [];
+    const kept = new Set();
+    const pieces = [];
+    const extension = mergeExtensionElements(originalXml, originalProcess.children.find((c) => c.local === 'extensionElements'), editedXml, editedProcess.children.find((c) => c.local === 'extensionElements'), options.baseline, baselineProcess?.children.find((c) => c.local === 'extensionElements'));
+    if (extension)
+        pieces.push(extension);
+    // The EDITED process decides which elements exist and in what order; the ORIGINAL
+    // decides the content of every element the author did not touch.
+    for (const element of editedProcess.children) {
+        if (element.local === 'extensionElements')
+            continue;
+        const id = element.id;
+        const original = id !== undefined ? originalById.get(id) : undefined;
+        const baseline = id !== undefined ? baselineById.get(id) : undefined;
+        const untouched = original !== undefined &&
+            baseline !== undefined &&
+            withoutWiring(editedXml, element) === withoutWiring(options.baseline, baseline);
+        if (untouched) {
+            pieces.push(withWiringFrom(originalXml, original, editedXml, element));
+            preserved.push(id);
+        }
+        else {
+            pieces.push(textOf(editedXml, element));
+            if (id !== undefined)
+                authored.push(id);
+        }
+        if (id !== undefined)
+            kept.add(id);
+    }
+    const removed = [...originalById.keys()].filter((id) => !kept.has(id));
+    // Splice the rebuilt process body into the ORIGINAL document, so the prolog,
+    // `bpmn:definitions` attributes and namespace declarations are the original's.
+    const indent = /([ \t]*)$/.exec(originalXml.slice(originalProcess.innerStart, originalProcess.children[0]?.start ?? originalProcess.innerEnd))?.[1] ?? '    ';
+    const body = `\n${indent}${pieces.join(`\n${indent}`)}\n${indent.slice(0, -2)}`;
+    let merged = originalXml.slice(0, originalProcess.innerStart) +
+        body +
+        originalXml.slice(originalProcess.innerEnd);
+    // The diagram: the original's layout survives, which is strictly better than the
+    // re-layout a bare recompile forces. Shapes and edges for deleted elements go with
+    // them; anything newly added has no DI yet, which is what `format`/`tidy` is for.
+    if (removed.length > 0) {
+        const plane = findByLocal(parseXmlRanges(merged), 'BPMNPlane');
+        if (plane) {
+            const gone = plane.children.filter((di) => {
+                const ref = di.attributes.bpmnElement;
+                return ref !== undefined && !kept.has(ref);
+            });
+            for (const di of [...gone].reverse()) {
+                // Take the whitespace before it too, so no blank line is left behind.
+                const from = /\s*$/.exec(merged.slice(0, di.start))?.index ?? di.start;
+                merged = merged.slice(0, from) + merged.slice(di.end);
+            }
+        }
+    }
+    return { xml: merged, preserved, authored, removed };
+}