@bpmnkit/core 0.1.1 → 0.2.0

package/dist/bpmn/bpmn-builder.js

@@ -1,7 +1,7 @@
 import { generateId } from "../types/id-generator.js";
 import { applyAutoLayout } from "./auto-layout.js";
 import { restConnectorRetries, restConnectorTaskType, restConnectorToIoMappingInputs, restConnectorToTaskHeaders, } from "./rest-connector.js";
-import { zeebeExtensionsToXmlElements } from "./zeebe-extensions.js";
+import { ensureZeebeExtension, zeebeExtensionsToXmlElements, } from "./zeebe-extensions.js";
 // Keep in sync with packages/core/package.json version
 const EXPORTER_VERSION = "0.0.23";
 // ---------------------------------------------------------------------------
@@ -15,6 +15,12 @@ function resolveMessage(messageName, rootMessages) {
     }
     return existing.id;
 }
+/** Builds the `zeebe:subscription` extension element for a correlated message catch. */
+function buildMessageSubscriptionExt(correlationKey) {
+    if (!correlationKey)
+        return [];
+    return zeebeExtensionsToXmlElements({ subscription: { correlationKey } });
+}
 function buildEventDefinitions(opts, rootErrors, rootMessages, rootSignals, rootEscalations) {
     const defs = [];
     if (opts.timerDuration || opts.timerDate || opts.timerCycle) {
@@ -86,6 +92,7 @@ function makeFlowElement(id, type, options) {
         name: options?.name,
         incoming: [],
         outgoing: [],
+        documentation: options?.documentation,
         extensionElements: options?.extensionElements ?? [],
         unknownAttributes: {},
     };
@@ -200,6 +207,17 @@ function buildAdHocLoopCharacteristics(lc) {
         ],
     };
 }
+const GATEWAY_ELEMENT_TYPES = new Set([
+    "exclusiveGateway",
+    "parallelGateway",
+    "inclusiveGateway",
+    "eventBasedGateway",
+    "complexGateway",
+]);
+/** Gateways are the elements for which several outgoing flows are the point. */
+function isGatewayType(type) {
+    return GATEWAY_ELEMENT_TYPES.has(type);
+}
 function recomputeIncomingOutgoing(elements, flows) {
     for (const el of elements) {
         el.incoming = [];
@@ -232,6 +250,9 @@ function buildServiceTaskExtensions(options) {
             })),
         };
     }
+    if (options.zeebeProperties) {
+        extensions.properties = { properties: options.zeebeProperties };
+    }
     return zeebeExtensionsToXmlElements(extensions);
 }
 function makeConditionExpression(expression) {
@@ -240,6 +261,72 @@ function makeConditionExpression(expression) {
         attributes: { "xsi:type": "bpmn:tFormalExpression" },
     };
 }
+/** Builds the Zeebe extension elements + completion condition shared by all `adHocSubProcess()` overloads. */
+function buildAdHocSubProcessExtensions(options) {
+    const zeebeExt = {};
+    if (options?.taskDefinition) {
+        zeebeExt.taskDefinition = options.taskDefinition;
+    }
+    if (options?.ioMapping) {
+        zeebeExt.ioMapping = {
+            inputs: options.ioMapping.inputs ?? [],
+            outputs: options.ioMapping.outputs ?? [],
+        };
+    }
+    if (options?.taskHeaders) {
+        zeebeExt.taskHeaders = {
+            headers: Object.entries(options.taskHeaders).map(([key, value]) => ({ key, value })),
+        };
+    }
+    if (options?.zeebeProperties) {
+        zeebeExt.properties = { properties: options.zeebeProperties };
+    }
+    const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
+    const adHocAttrs = {};
+    if (options?.activeElementsCollection) {
+        adHocAttrs.activeElementsCollection = options.activeElementsCollection;
+    }
+    if (options?.outputCollection)
+        adHocAttrs.outputCollection = options.outputCollection;
+    if (options?.outputElement)
+        adHocAttrs.outputElement = options.outputElement;
+    if (Object.keys(adHocAttrs).length > 0) {
+        extensionElements.push({ name: "zeebe:adHoc", attributes: adHocAttrs, children: [] });
+    }
+    return {
+        extensionElements,
+        completionCondition: options?.completionCondition
+            ? makeConditionExpression(options.completionCondition)
+            : undefined,
+    };
+}
+/** Applies modeler-template attrs, sub-process contents, loop characteristics, and completion condition. */
+function finalizeAdHocSubProcessEl(element, options, sub, completionCondition) {
+    if (options?.modelerTemplate)
+        element.unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
+    if (options?.modelerTemplateVersion) {
+        element.unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
+    }
+    if (options?.modelerTemplateIcon) {
+        element.unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
+    }
+    if (element.type !== "adHocSubProcess")
+        return;
+    element.flowElements = sub._elements;
+    element.sequenceFlows = sub._flows;
+    element.textAnnotations = sub._textAnnotations;
+    element.associations = sub._associations;
+    if (options?.loopCharacteristics) {
+        element.loopCharacteristics = buildAdHocLoopCharacteristics(options.loopCharacteristics);
+    }
+    else if (options?.multiInstance) {
+        element.loopCharacteristics = buildMultiInstance(options.multiInstance);
+    }
+    element.completionCondition = completionCondition;
+    if (options?.cancelRemainingInstances !== undefined) {
+        element.cancelRemainingInstances = options.cancelRemainingInstances;
+    }
+}
 // ---------------------------------------------------------------------------
 // Element factory functions — shared by all three builder classes
 // ---------------------------------------------------------------------------
@@ -253,6 +340,7 @@ function makeServiceTaskEl(id, options) {
         unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
     const el = makeFlowElement(id, "serviceTask", {
         name: options.name,
+        documentation: options.documentation,
         extensionElements: buildServiceTaskExtensions(options),
     });
     el.unknownAttributes = unknownAttributes;
@@ -263,6 +351,7 @@ function makeServiceTaskEl(id, options) {
 function makeScriptTaskEl(id, options) {
     const el = makeFlowElement(id, "scriptTask", {
         name: options.name,
+        documentation: options.documentation,
         extensionElements: zeebeExtensionsToXmlElements({
             unknownElements: [
                 {
@@ -281,8 +370,27 @@ function makeUserTaskEl(id, options) {
     const ext = zeebeExtensionsToXmlElements({
         ...(options?.zeebeUserTask ? { userTask: true } : {}),
         ...(options?.formId ? { formDefinition: { formId: options.formId } } : {}),
+        ...(options?.assignee || options?.candidateGroups || options?.candidateUsers
+            ? {
+                assignmentDefinition: {
+                    assignee: options?.assignee,
+                    candidateGroups: options?.candidateGroups,
+                    candidateUsers: options?.candidateUsers,
+                },
+            }
+            : {}),
+        ...(options?.dueDate || options?.followUpDate
+            ? { taskSchedule: { dueDate: options?.dueDate, followUpDate: options?.followUpDate } }
+            : {}),
+        ...(options?.priority !== undefined
+            ? { priorityDefinition: { priority: String(options.priority) } }
+            : {}),
+    });
+    const el = makeFlowElement(id, "userTask", {
+        name: options?.name,
+        documentation: options?.documentation,
+        extensionElements: ext,
     });
-    const el = makeFlowElement(id, "userTask", { name: options?.name, extensionElements: ext });
     if (options?.isForCompensation)
         el.isForCompensation = true;
     return el;
@@ -302,6 +410,7 @@ function makeBusinessRuleTaskEl(id, options) {
     }
     const el = makeFlowElement(id, "businessRuleTask", {
         name: options?.name,
+        documentation: options?.documentation,
         extensionElements: ext,
     });
     if (options?.isForCompensation)
@@ -315,6 +424,7 @@ function makeCallActivityEl(id, options) {
     }
     const el = makeFlowElement(id, "callActivity", {
         name: options.name,
+        documentation: options.documentation,
         extensionElements: zeebeExtensionsToXmlElements({
             unknownElements: [{ name: "zeebe:calledElement", attributes: attrs, children: [] }],
         }),
@@ -471,6 +581,8 @@ function traceBackToSplit(nodeId, splitGateways, flows) {
 export class BranchBuilder {
     /** @internal */
     _elements = [];
+    /** Ids in `_elements`, for O(1) duplicate checks. */
+    _ids = new Set();
     /** @internal */
     _flows = [];
     /** @internal */
@@ -518,6 +630,7 @@ export class BranchBuilder {
     }
     addElement(element) {
         this._elements.push(element);
+        this._ids.add(element.id);
         if (this.lastNodeId) {
             const flowId = generateId("Flow");
             const flow = {
@@ -667,7 +780,10 @@ export class BranchBuilder {
         return this.addElement(el);
     }
     intermediateCatchEvent(id, options) {
-        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", options);
+        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options?.correlationKey),
+        });
         if (el.type === "intermediateCatchEvent" && options) {
             el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
@@ -698,7 +814,10 @@ export class BranchBuilder {
      * cursor to return to the task afterward.
      */
     boundaryEvent(id, options) {
-        const element = makeFlowElement(id, "boundaryEvent", options);
+        const element = makeFlowElement(id, "boundaryEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options.correlationKey),
+        });
         if (element.type === "boundaryEvent") {
             element.attachedToRef = options.attachedTo;
             element.cancelActivity = options.cancelActivity;
@@ -706,6 +825,7 @@ export class BranchBuilder {
         }
         // Push directly — no sequence flow, boundary events attach via attachedToRef
         this._elements.push(element);
+        this._ids.add(element.id);
         this.lastNodeId = element.id;
         this.isFirstElement = false;
         return this;
@@ -770,68 +890,13 @@ export class BranchBuilder {
         resolved.content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
-        const zeebeExt = {};
-        if (resolved.options?.taskDefinition) {
-            zeebeExt.taskDefinition = resolved.options.taskDefinition;
-        }
-        if (resolved.options?.ioMapping) {
-            zeebeExt.ioMapping = {
-                inputs: resolved.options.ioMapping.inputs ?? [],
-                outputs: resolved.options.ioMapping.outputs ?? [],
-            };
-        }
-        if (resolved.options?.taskHeaders) {
-            zeebeExt.taskHeaders = {
-                headers: Object.entries(resolved.options.taskHeaders).map(([key, value]) => ({
-                    key,
-                    value,
-                })),
-            };
-        }
-        const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
-        const adHocAttrs = {};
-        if (resolved.options?.activeElementsCollection) {
-            adHocAttrs.activeElementsCollection = resolved.options.activeElementsCollection;
-        }
-        if (resolved.options?.outputCollection) {
-            adHocAttrs.outputCollection = resolved.options.outputCollection;
-        }
-        if (resolved.options?.outputElement) {
-            adHocAttrs.outputElement = resolved.options.outputElement;
-        }
-        if (Object.keys(adHocAttrs).length > 0) {
-            extensionElements.push({
-                name: "zeebe:adHoc",
-                attributes: adHocAttrs,
-                children: [],
-            });
-        }
+        const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
         const element = makeFlowElement(id, "adHocSubProcess", {
             name: resolved.options?.name,
+            documentation: resolved.options?.documentation,
             extensionElements,
         });
-        if (resolved.options?.modelerTemplate) {
-            element.unknownAttributes["zeebe:modelerTemplate"] = resolved.options.modelerTemplate;
-        }
-        if (resolved.options?.modelerTemplateVersion) {
-            element.unknownAttributes["zeebe:modelerTemplateVersion"] =
-                resolved.options.modelerTemplateVersion;
-        }
-        if (resolved.options?.modelerTemplateIcon) {
-            element.unknownAttributes["zeebe:modelerTemplateIcon"] = resolved.options.modelerTemplateIcon;
-        }
-        if (element.type === "adHocSubProcess") {
-            element.flowElements = sub._elements;
-            element.sequenceFlows = sub._flows;
-            element.textAnnotations = sub._textAnnotations;
-            element.associations = sub._associations;
-            if (resolved.options?.loopCharacteristics) {
-                element.loopCharacteristics = buildAdHocLoopCharacteristics(resolved.options.loopCharacteristics);
-            }
-            else if (resolved.options?.multiInstance) {
-                element.loopCharacteristics = buildMultiInstance(resolved.options.multiInstance);
-            }
-        }
+        finalizeAdHocSubProcessEl(element, resolved.options, sub, completionCondition);
         return this.addElement(element);
     }
     /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
@@ -851,10 +916,11 @@ export class BranchBuilder {
         }
         // Event sub-processes have no incoming/outgoing sequence flows and must not
         // advance the branch cursor — mirrors ProcessBuilder.eventSubProcess.
-        if (this._elements.some((n) => n.id === element.id)) {
+        if (this._ids.has(element.id)) {
             throw new Error(`Duplicate element ID "${element.id}"`);
         }
         this._elements.push(element);
+        this._ids.add(element.id);
         return this;
     }
     /**
@@ -871,10 +937,11 @@ export class BranchBuilder {
         const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         callback(b);
         for (const el of b._elements) {
-            if (this._elements.some((n) => n.id === el.id)) {
+            if (this._ids.has(el.id)) {
                 throw new Error(`Duplicate element ID "${el.id}"`);
             }
             this._elements.push(el);
+            this._ids.add(el.id);
         }
         for (const fl of b._flows)
             this._flows.push(fl);
@@ -911,6 +978,8 @@ export class BranchBuilder {
 export class SubProcessContentBuilder {
     /** @internal */
     _elements = [];
+    /** Ids in `_elements`, for O(1) duplicate checks. */
+    _ids = new Set();
     /** @internal */
     _flows = [];
     /** @internal */
@@ -927,10 +996,11 @@ export class SubProcessContentBuilder {
         this.rootMessages = rootMessages;
     }
     addElement(element) {
-        if (this._elements.some((n) => n.id === element.id)) {
+        if (this._ids.has(element.id)) {
             throw new Error(`Duplicate element ID "${element.id}" in sub-process`);
         }
         this._elements.push(element);
+        this._ids.add(element.id);
         if (this.lastNodeId) {
             this._flows.push({
                 id: generateId("Flow"),
@@ -953,6 +1023,22 @@ export class SubProcessContentBuilder {
         this.lastNodeId = element.id;
         return this;
     }
+    /**
+     * Add an element with no sequence-flow wiring and no cursor movement.
+     *
+     * Used for ad-hoc sub-process tool activities, which the AI Agent connector
+     * requires to be root nodes (no incoming sequence flow, not a boundary event).
+     * Unlike `serviceTask()`/`userTask()`/etc., this does not auto-connect from
+     * the current cursor and does not move it.
+     */
+    addDisconnected(element) {
+        if (this._ids.has(element.id)) {
+            throw new Error(`Duplicate element ID "${element.id}" in sub-process`);
+        }
+        this._elements.push(element);
+        this._ids.add(element.id);
+        return this;
+    }
     // ---- Events ----
     startEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
@@ -976,7 +1062,10 @@ export class SubProcessContentBuilder {
         return this.addElement(el);
     }
     intermediateCatchEvent(id, options) {
-        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", options);
+        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options?.correlationKey),
+        });
         if (el.type === "intermediateCatchEvent" && options)
             el.eventDefinitions = buildEventDefinitions(options);
         return this.addElement(el);
@@ -1068,10 +1157,11 @@ export class SubProcessContentBuilder {
         const b = new BranchBuilder(this.currentGatewayId, name);
         callback(b);
         for (const el of b._elements) {
-            if (this._elements.some((n) => n.id === el.id)) {
+            if (this._ids.has(el.id)) {
                 throw new Error(`Duplicate element ID "${el.id}"`);
             }
             this._elements.push(el);
+            this._ids.add(el.id);
         }
         for (const fl of b._flows)
             this._flows.push(fl);
@@ -1114,7 +1204,7 @@ export class SubProcessContentBuilder {
         return this;
     }
     element(elementId) {
-        if (!this._elements.some((n) => n.id === elementId)) {
+        if (!this._ids.has(elementId)) {
             throw new Error(`Element "${elementId}" not found in sub-process`);
         }
         this.lastNodeId = elementId;
@@ -1131,7 +1221,10 @@ export class SubProcessContentBuilder {
      * cursor to return to the task afterward.
      */
     boundaryEvent(id, options) {
-        const element = makeFlowElement(id, "boundaryEvent", options);
+        const element = makeFlowElement(id, "boundaryEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options.correlationKey),
+        });
         if (element.type === "boundaryEvent") {
             element.attachedToRef = options.attachedTo;
             element.cancelActivity = options.cancelActivity;
@@ -1139,6 +1232,7 @@ export class SubProcessContentBuilder {
         }
         // Push directly — no sequence flow, boundary events attach via attachedToRef
         this._elements.push(element);
+        this._ids.add(element.id);
         this.lastNodeId = element.id;
         return this;
     }
@@ -1200,68 +1294,13 @@ export class SubProcessContentBuilder {
         resolved.content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
-        const zeebeExt = {};
-        if (resolved.options?.taskDefinition) {
-            zeebeExt.taskDefinition = resolved.options.taskDefinition;
-        }
-        if (resolved.options?.ioMapping) {
-            zeebeExt.ioMapping = {
-                inputs: resolved.options.ioMapping.inputs ?? [],
-                outputs: resolved.options.ioMapping.outputs ?? [],
-            };
-        }
-        if (resolved.options?.taskHeaders) {
-            zeebeExt.taskHeaders = {
-                headers: Object.entries(resolved.options.taskHeaders).map(([key, value]) => ({
-                    key,
-                    value,
-                })),
-            };
-        }
-        const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
-        const adHocAttrs = {};
-        if (resolved.options?.activeElementsCollection) {
-            adHocAttrs.activeElementsCollection = resolved.options.activeElementsCollection;
-        }
-        if (resolved.options?.outputCollection) {
-            adHocAttrs.outputCollection = resolved.options.outputCollection;
-        }
-        if (resolved.options?.outputElement) {
-            adHocAttrs.outputElement = resolved.options.outputElement;
-        }
-        if (Object.keys(adHocAttrs).length > 0) {
-            extensionElements.push({
-                name: "zeebe:adHoc",
-                attributes: adHocAttrs,
-                children: [],
-            });
-        }
+        const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
         const element = makeFlowElement(id, "adHocSubProcess", {
             name: resolved.options?.name,
+            documentation: resolved.options?.documentation,
             extensionElements,
         });
-        if (resolved.options?.modelerTemplate) {
-            element.unknownAttributes["zeebe:modelerTemplate"] = resolved.options.modelerTemplate;
-        }
-        if (resolved.options?.modelerTemplateVersion) {
-            element.unknownAttributes["zeebe:modelerTemplateVersion"] =
-                resolved.options.modelerTemplateVersion;
-        }
-        if (resolved.options?.modelerTemplateIcon) {
-            element.unknownAttributes["zeebe:modelerTemplateIcon"] = resolved.options.modelerTemplateIcon;
-        }
-        if (element.type === "adHocSubProcess") {
-            element.flowElements = sub._elements;
-            element.sequenceFlows = sub._flows;
-            element.textAnnotations = sub._textAnnotations;
-            element.associations = sub._associations;
-            if (resolved.options?.loopCharacteristics) {
-                element.loopCharacteristics = buildAdHocLoopCharacteristics(resolved.options.loopCharacteristics);
-            }
-            else if (resolved.options?.multiInstance) {
-                element.loopCharacteristics = buildMultiInstance(resolved.options.multiInstance);
-            }
-        }
+        finalizeAdHocSubProcessEl(element, resolved.options, sub, completionCondition);
         return this.addElement(element);
     }
     /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
@@ -1281,10 +1320,11 @@ export class SubProcessContentBuilder {
         }
         // Event sub-processes have no incoming/outgoing sequence flows and must not
         // advance the cursor — mirrors ProcessBuilder.eventSubProcess.
-        if (this._elements.some((n) => n.id === element.id)) {
+        if (this._ids.has(element.id)) {
             throw new Error(`Duplicate element ID "${element.id}" in sub-process`);
         }
         this._elements.push(element);
+        this._ids.add(element.id);
         return this;
     }
 }
@@ -1296,8 +1336,12 @@ export class ProcessBuilder {
     processId;
     processName;
     _isExecutable = true;
+    /** Whether `executable()` was called, so continue-mode leaves it alone if not. */
+    _executableSet = false;
     _versionTag;
     flowElements = [];
+    /** Ids in `flowElements`, for O(1) duplicate and existence checks. */
+    elementIds = new Set();
     sequenceFlows = [];
     rootErrors = [];
     rootMessages = [];
@@ -1313,9 +1357,140 @@ export class ProcessBuilder {
     _executionPlatformVersion = "8.9.0";
     _serviceTaskDefaults = {};
     _savedMainFlowId = undefined;
+    /** Set by {@link ProcessBuilder.from}; makes `build()` update rather than generate. */
+    _source;
+    /** Pre-existing flow endpoints, so `build()` can prove it did not rewire them. */
+    _sourceFlowTargets = new Map();
+    /** An `insertAfter` flow waiting to be reattached to what gets built next. */
+    _pendingSpliceFlowId;
+    /** Flows the caller deliberately spliced, exempt from the rewiring guard. */
+    _splicedFlowIds = new Set();
     constructor(processId) {
         this.processId = processId;
     }
+    /**
+     * Continues an existing model rather than generating a new one.
+     *
+     * `build()` then returns *that document* with this process's contents
+     * replaced, so everything the builder has no opinion about — other processes,
+     * the collaboration, lanes, diagram interchange, root elements, imports,
+     * unmodelled content — is still there afterwards. Generating a replacement
+     * from scratch is what loses those.
+     *
+     * The input is not mutated; the builder works on a copy.
+     *
+     * @param definitions - The parsed model to continue.
+     * @param processId - Which process to continue. Named explicitly, because
+     *   "the first process" is a guess that goes wrong on a collaboration.
+     * @example
+     * ```typescript
+     * const updated = ProcessBuilder.from(Bpmn.parse(xml), "order")
+     *   .at("validate")
+     *   .serviceTask("notify", { name: "Notify", taskType: "notify" })
+     *   .build()
+     * ```
+     */
+    static from(definitions, processId) {
+        const copy = structuredClone(definitions);
+        const process = copy.processes.find((candidate) => candidate.id === processId);
+        if (process === undefined) {
+            const available = copy.processes.map((candidate) => candidate.id);
+            throw new Error(`Process "${processId}" is not in this document. It contains: ${available.length > 0 ? available.map((id) => `"${id}"`).join(", ") : "no processes"}`);
+        }
+        const builder = new ProcessBuilder(processId);
+        builder._source = { definitions: copy, process };
+        builder.processName = process.name;
+        builder.flowElements.push(...process.flowElements);
+        for (const element of process.flowElements)
+            builder.elementIds.add(element.id);
+        builder.sequenceFlows.push(...process.sequenceFlows);
+        builder._textAnnotations.push(...process.textAnnotations);
+        builder._associations.push(...process.associations);
+        // Seeded so a message event reuses the document's existing message rather
+        // than declaring a second one with the same name.
+        builder.rootErrors.push(...copy.errors);
+        builder.rootMessages.push(...copy.messages);
+        builder.rootSignals.push(...copy.signals);
+        builder.rootEscalations.push(...copy.escalations);
+        builder._sourceFlowTargets = new Map(process.sequenceFlows.map((flow) => [flow.id, `${flow.sourceRef}→${flow.targetRef}`]));
+        return builder;
+    }
+    /**
+     * Moves the cursor to an existing flow node, so the next call chains from it.
+     *
+     * @param nodeId - A flow node directly contained by this process. Nodes inside
+     *   a sub-process are not reachable: continuing into one means building that
+     *   sub-process, not this one.
+     */
+    at(nodeId) {
+        const node = this.flowElements.find((element) => element.id === nodeId);
+        if (node === undefined) {
+            throw new Error(`"${nodeId}" is not a flow node in process "${this.processId}". Nodes inside a sub-process cannot be continued from here.`);
+        }
+        if (node.type === "endEvent") {
+            throw new Error(`Cannot continue from end event "${nodeId}": an end event has no outgoing sequence flow.`);
+        }
+        const hasOutgoing = this.sequenceFlows.some((flow) => flow.sourceRef === nodeId);
+        if (hasOutgoing && !isGatewayType(node.type)) {
+            throw new Error(`"${nodeId}" already has an outgoing sequence flow. Continuing from it would give a ${node.type} two outgoing flows, which is an uncontrolled split. Use insertAfter("${nodeId}") to splice into that path instead.`);
+        }
+        this.moveCursor(node);
+        return this;
+    }
+    /**
+     * Splices what you build next into the path leaving an existing node.
+     *
+     * `insertAfter("validate")` followed by `.serviceTask("notify", …)` turns
+     * `validate → end` into `validate → notify → end`. The existing flow keeps its
+     * id and its target and only changes where it starts, so an edge nobody asked
+     * to move keeps its identity in the diagram and in a diff.
+     *
+     * This is the counterpart to {@link at}, which continues from a node whose
+     * path is open. Which one you mean is not guessable, so it is not guessed.
+     *
+     * @param nodeId - A flow node with exactly one outgoing sequence flow.
+     */
+    insertAfter(nodeId) {
+        const node = this.flowElements.find((element) => element.id === nodeId);
+        if (node === undefined) {
+            throw new Error(`"${nodeId}" is not a flow node in process "${this.processId}".`);
+        }
+        const outgoing = this.sequenceFlows.filter((flow) => flow.sourceRef === nodeId);
+        if (outgoing.length === 0) {
+            throw new Error(`"${nodeId}" has no outgoing sequence flow, so there is nothing to insert into. Use at("${nodeId}") to continue from it.`);
+        }
+        if (outgoing.length > 1) {
+            throw new Error(`"${nodeId}" has ${outgoing.length} outgoing sequence flows, so "after" is ambiguous. Name the flow's target and insert before that instead.`);
+        }
+        this.resolvePendingSplice();
+        const flow = outgoing[0];
+        this._pendingSpliceFlowId = flow.id;
+        this._splicedFlowIds.add(flow.id);
+        this.moveCursor(node);
+        return this;
+    }
+    /** Points the cursor at an existing node and forgets any branch state. */
+    moveCursor(node) {
+        this.lastNodeId = node.id;
+        this.currentGatewayId = isGatewayType(node.type) ? node.id : undefined;
+        this.openBranchEnds = [];
+        this._savedMainFlowId = undefined;
+    }
+    /**
+     * Reattaches the flow a pending `insertAfter` detached, to whatever the cursor
+     * has reached. With nothing built in between the cursor has not moved and this
+     * is a no-op, which is the right answer for `insertAfter(x)` followed by
+     * nothing.
+     */
+    resolvePendingSplice() {
+        const flowId = this._pendingSpliceFlowId;
+        if (flowId === undefined)
+            return;
+        this._pendingSpliceFlowId = undefined;
+        const flow = this.sequenceFlows.find((candidate) => candidate.id === flowId);
+        if (flow !== undefined && this.lastNodeId !== undefined)
+            flow.sourceRef = this.lastNodeId;
+    }
     /** Enable auto-layout: `build()` will run the layout engine and populate diagram interchange data. */
     withAutoLayout() {
         this._autoLayout = true;
@@ -1340,6 +1515,7 @@ export class ProcessBuilder {
     /** Set whether this process is executable. */
     executable(value) {
         this._isExecutable = value;
+        this._executableSet = true;
         return this;
     }
     /** Set the process version tag. */
@@ -1421,7 +1597,10 @@ export class ProcessBuilder {
     /** Add an intermediate catch event (timer, message, signal). */
     intermediateCatchEvent(id, options) {
         const nodeId = id ?? generateId("IntermediateCatchEvent");
-        const element = makeFlowElement(nodeId, "intermediateCatchEvent", options);
+        const element = makeFlowElement(nodeId, "intermediateCatchEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options?.correlationKey),
+        });
         if (element.type === "intermediateCatchEvent" && options) {
             element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
@@ -1435,7 +1614,10 @@ export class ProcessBuilder {
      * They start a new outgoing chain from the boundary event itself.
      */
     boundaryEvent(id, options) {
-        const element = makeFlowElement(id, "boundaryEvent", options);
+        const element = makeFlowElement(id, "boundaryEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options.correlationKey),
+        });
         if (element.type === "boundaryEvent") {
             element.attachedToRef = options.attachedTo;
             element.cancelActivity = options.cancelActivity;
@@ -1616,10 +1798,11 @@ export class ProcessBuilder {
         const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         callback(b);
         for (const el of b._elements) {
-            if (this.flowElements.some((n) => n.id === el.id)) {
+            if (this.elementIds.has(el.id)) {
                 throw new Error(`Duplicate element ID "${el.id}"`);
             }
             this.flowElements.push(el);
+            this.elementIds.add(el.id);
         }
         for (const fl of b._flows) {
             this.sequenceFlows.push(fl);
@@ -1674,7 +1857,7 @@ export class ProcessBuilder {
      * @throws If no element with the given ID exists.
      */
     element(elementId) {
-        const found = this.flowElements.some((n) => n.id === elementId);
+        const found = this.elementIds.has(elementId);
         if (!found) {
             throw new Error(`Element "${elementId}" not found in process "${this.processId}"`);
         }
@@ -1690,69 +1873,13 @@ export class ProcessBuilder {
         resolved.content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
-        const zeebeExt = {};
-        if (resolved.options?.taskDefinition) {
-            zeebeExt.taskDefinition = resolved.options.taskDefinition;
-        }
-        if (resolved.options?.ioMapping) {
-            zeebeExt.ioMapping = {
-                inputs: resolved.options.ioMapping.inputs ?? [],
-                outputs: resolved.options.ioMapping.outputs ?? [],
-            };
-        }
-        if (resolved.options?.taskHeaders) {
-            zeebeExt.taskHeaders = {
-                headers: Object.entries(resolved.options.taskHeaders).map(([key, value]) => ({
-                    key,
-                    value,
-                })),
-            };
-        }
-        const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
-        // zeebe:adHoc element
-        const adHocAttrs = {};
-        if (resolved.options?.activeElementsCollection) {
-            adHocAttrs.activeElementsCollection = resolved.options.activeElementsCollection;
-        }
-        if (resolved.options?.outputCollection) {
-            adHocAttrs.outputCollection = resolved.options.outputCollection;
-        }
-        if (resolved.options?.outputElement) {
-            adHocAttrs.outputElement = resolved.options.outputElement;
-        }
-        if (Object.keys(adHocAttrs).length > 0) {
-            extensionElements.push({
-                name: "zeebe:adHoc",
-                attributes: adHocAttrs,
-                children: [],
-            });
-        }
+        const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
         const element = makeFlowElement(id, "adHocSubProcess", {
             name: resolved.options?.name,
+            documentation: resolved.options?.documentation,
             extensionElements,
         });
-        if (resolved.options?.modelerTemplate) {
-            element.unknownAttributes["zeebe:modelerTemplate"] = resolved.options.modelerTemplate;
-        }
-        if (resolved.options?.modelerTemplateVersion) {
-            element.unknownAttributes["zeebe:modelerTemplateVersion"] =
-                resolved.options.modelerTemplateVersion;
-        }
-        if (resolved.options?.modelerTemplateIcon) {
-            element.unknownAttributes["zeebe:modelerTemplateIcon"] = resolved.options.modelerTemplateIcon;
-        }
-        if (element.type === "adHocSubProcess") {
-            element.flowElements = sub._elements;
-            element.sequenceFlows = sub._flows;
-            element.textAnnotations = sub._textAnnotations;
-            element.associations = sub._associations;
-            if (resolved.options?.loopCharacteristics) {
-                element.loopCharacteristics = buildAdHocLoopCharacteristics(resolved.options.loopCharacteristics);
-            }
-            else if (resolved.options?.multiInstance) {
-                element.loopCharacteristics = buildMultiInstance(resolved.options.multiInstance);
-            }
-        }
+        finalizeAdHocSubProcessEl(element, resolved.options, sub, completionCondition);
         this.addFlowElement(element);
         return this;
     }
@@ -1795,11 +1922,12 @@ export class ProcessBuilder {
         // advance the flow cursor — the surrounding process wires around them.
         // openBranchEnds is intentionally NOT drained here; the next normal
         // addFlowElement call will drain it and connect branch ends to that element.
-        if (this.flowElements.some((n) => n.id === element.id)) {
+        if (this.elementIds.has(element.id)) {
             throw new Error(`Duplicate element ID "${element.id}" in process "${this.processId}"`);
         }
         this._savedMainFlowId = undefined;
         this.flowElements.push(element);
+        this.elementIds.add(element.id);
         return this;
     }
     // ---- Annotations ----
@@ -1831,19 +1959,50 @@ export class ProcessBuilder {
      *
      * Resolves all forward-referenced `incoming` / `outgoing` arrays and wraps
      * the process in a {@link BpmnDefinitions} ready for XML serialization.
+     *
+     * **The join contract.** Branches built with `.branch()` converge implicitly:
+     * where several paths from one gateway reach the same element, a matching join
+     * gateway is inserted for you. That is convenient by hand and a trap for
+     * generated code, which cannot see the element it did not write. Pass
+     * `{ explicitJoins: true }` to be told instead of helped — the build throws,
+     * naming the gateways it would have inserted, and you declare them yourself
+     * with `.connectTo(joinId)`.
+     *
+     * A join you declare only counts if it *matches the split*: an exclusive split
+     * converging on a parallel gateway is not the gateway inference would have
+     * added, so it is still inferred — and with `explicitJoins` that refusal is the
+     * only thing that tells you.
+     *
+     * {@link ProcessBuilder.from} never infers joins at all, whatever this option
+     * says: inference reads the whole topology, and on a document you were handed
+     * that means rewriting edges you never touched.
+     *
+     * @param options - `explicitJoins` refuses inferred join gateways. `strict` is
+     *   the former name for it and still works.
      */
     build(options) {
+        this.resolvePendingSplice();
         const beforeCount = this.flowElements.length;
-        insertJoinGateways(this.flowElements, this.sequenceFlows);
-        if (options?.strict && this.flowElements.length > beforeCount) {
+        // Continuing a document never infers joins. `insertJoinGateways` reads the
+        // whole topology, so on a parsed model it retargets edges the caller never
+        // touched — the corpus has a document where a no-op continue would have
+        // invented a join gateway and rerouted two flows into it. Building a branch
+        // that needs a join here means saying so with `.connectTo(joinId)`.
+        if (this._source === undefined)
+            insertJoinGateways(this.flowElements, this.sequenceFlows);
+        const explicitJoins = options?.explicitJoins ?? options?.strict ?? false;
+        if (explicitJoins && this.flowElements.length > beforeCount) {
             const inserted = this.flowElements
                 .slice(beforeCount)
                 .map((e) => e.id)
                 .join(", ");
-            throw new Error(`auto-join gateways were inserted: ${inserted}. Use explicit .connectTo(joinId) to make gateway topology explicit, or remove { strict: true }.`);
+            throw new Error(`Inferred join gateways: ${inserted}. Declare them with .connectTo(joinId), or drop { explicitJoins: true } to keep the inference.`);
         }
         this.validate();
+        this.assertSourceTopologyIntact();
         recomputeIncomingOutgoing(this.flowElements, this.sequenceFlows);
+        if (this._source !== undefined)
+            return this.buildOntoSource(this._source);
         const extensionElements = [];
         if (this._versionTag) {
             extensionElements.push({
@@ -1905,6 +2064,78 @@ export class ProcessBuilder {
         };
         return this._autoLayout ? applyAutoLayout(defs) : defs;
     }
+    /**
+     * Writes this process's contents back into the document it came from.
+     *
+     * Everything not listed here is kept by identity — other processes, the
+     * collaboration, diagram interchange, root elements, the process's own lanes,
+     * documentation, extensions and unmodelled content. That is the whole point of
+     * continuing rather than regenerating.
+     *
+     * Diagram interchange is *not* regenerated: existing shapes keep their
+     * positions, and elements added here have none until `withAutoLayout()` or a
+     * later `applyAutoLayout()` gives them one.
+     */
+    buildOntoSource(source) {
+        const { definitions, process } = source;
+        process.flowElements = this.flowElements;
+        process.sequenceFlows = this.sequenceFlows;
+        process.textAnnotations = this._textAnnotations;
+        process.associations = this._associations;
+        if (this.processName !== undefined)
+            process.name = this.processName;
+        // Only when asked. BPMN reads an absent `isExecutable` as false, so writing
+        // the builder's `true` default onto a process that never carried it makes a
+        // non-executable process executable — a change nobody requested.
+        if (this._executableSet)
+            process.isExecutable = this._isExecutable;
+        if (this._versionTag !== undefined) {
+            // Set the attribute on the existing element rather than replacing the
+            // bag: a real process carries other extensions next to it.
+            ensureZeebeExtension({ type: "process", extensionElements: process.extensionElements }, "zeebe:versionTag").attributes.value = this._versionTag;
+        }
+        definitions.errors = this.rootErrors;
+        definitions.messages = this.rootMessages;
+        definitions.signals = this.rootSignals;
+        definitions.escalations = this.rootEscalations;
+        return this._autoLayout ? applyAutoLayout(definitions) : definitions;
+    }
+    /**
+     * Refuses to rewire a flow that was already in the document.
+     *
+     * `insertJoinGateways` retargets converging flows, which is right for a
+     * topology this builder just created and wrong for one it was handed: a
+     * document would come back with edges the caller never touched pointing
+     * somewhere else. Continuing a model has to leave the model alone.
+     */
+    assertSourceTopologyIntact() {
+        if (this._source === undefined)
+            return;
+        const rewired = [];
+        const byId = new Map(this.sequenceFlows.map((flow) => [flow.id, flow]));
+        for (const [id, endpoints] of this._sourceFlowTargets) {
+            const flow = byId.get(id);
+            if (flow === undefined) {
+                rewired.push(`${id} (removed)`);
+                continue;
+            }
+            // A spliced flow was moved on purpose, but only its source may move:
+            // `insertAfter` inserts into a path, it does not redirect one.
+            const [, target] = endpoints.split("→");
+            if (this._splicedFlowIds.has(id)) {
+                if (flow.targetRef !== target) {
+                    rewired.push(`${id} (spliced flow now targets ${flow.targetRef}, not ${target})`);
+                }
+                continue;
+            }
+            const now = `${flow.sourceRef}→${flow.targetRef}`;
+            if (now !== endpoints)
+                rewired.push(`${id} (${endpoints} became ${now})`);
+        }
+        if (rewired.length > 0) {
+            throw new Error(`Building would rewire sequence flows this document already had: ${rewired.join(", ")}. Continuing a model must not change the part you did not touch.`);
+        }
+    }
     validate() {
         const elementIds = new Set(this.flowElements.map((el) => el.id));
         for (const flow of this.sequenceFlows) {
@@ -1919,10 +2150,11 @@ export class ProcessBuilder {
         }
     }
     addFlowElement(element) {
-        if (this.flowElements.some((n) => n.id === element.id)) {
+        if (this.elementIds.has(element.id)) {
             throw new Error(`Duplicate element ID "${element.id}" in process "${this.processId}"`);
         }
         this.flowElements.push(element);
+        this.elementIds.add(element.id);
         // Compensation handlers are outside the normal token flow: link via association
         // from the preceding compensation boundary event, then restore the main-flow cursor.
         if (element.isForCompensation) {
@@ -1981,6 +2213,9 @@ export class DiagramBuilder {
     _processes = [];
     _errors = [];
     _messages = [];
+    _participants = [];
+    _messageFlows = [];
+    _collaborationId = "Collaboration_1";
     _executionPlatformVersion = "8.9.0";
     constructor(id) {
         this._id = id;
@@ -1999,6 +2234,152 @@ export class DiagramBuilder {
         this._messages.push(...defs.messages);
         return this;
     }
+    /** Renames the collaboration element. Defaults to `"Collaboration_1"`. */
+    collaborationId(id) {
+        this._collaborationId = id;
+        return this;
+    }
+    /**
+     * Adds a pool.
+     *
+     * Omit `processId` for a black box — a participant whose internals are not
+     * modelled. That is a real BPMN construct, not an incomplete one: it is how
+     * you draw the counterparty you exchange messages with but do not execute.
+     *
+     * @param id - The participant's element id, used verbatim.
+     */
+    participant(id, options = {}) {
+        const participant = { id, unknownAttributes: {} };
+        if (options.name !== undefined)
+            participant.name = options.name;
+        if (options.processId !== undefined)
+            participant.processRef = options.processId;
+        this._participants.push(participant);
+        return this;
+    }
+    /**
+     * Declares a root-level message, which a message flow may name and a Camunda 8
+     * message subscription correlates on.
+     *
+     * `ProcessBuilder` already creates messages by name for message events, so
+     * only call this for a message no event declared — typically one carried by a
+     * message flow between pools.
+     *
+     * @param id - The message's element id, used verbatim.
+     */
+    message(id, options = {}) {
+        const message = { id, unknownAttributes: {} };
+        if (options.name !== undefined)
+            message.name = options.name;
+        const extensions = zeebeExtensionsToXmlElements(options.correlationKey === undefined
+            ? {}
+            : { subscription: { correlationKey: options.correlationKey } });
+        if (extensions.length > 0)
+            message.extensionElements = extensions;
+        this._messages.push(message);
+        return this;
+    }
+    /**
+     * Connects two pools.
+     *
+     * `source` and `target` name either participants or flow nodes inside them.
+     * Both forms are valid BPMN and the layout engine reads either, but they must
+     * be in *different* pools — a message flow is what crosses a pool boundary,
+     * and one that does not is the error this catches.
+     *
+     * @param id - The message flow's element id, used verbatim.
+     */
+    messageFlow(id, options) {
+        const flow = {
+            id,
+            sourceRef: options.source,
+            targetRef: options.target,
+            unknownAttributes: {},
+        };
+        if (options.name !== undefined)
+            flow.name = options.name;
+        if (options.messageRef !== undefined)
+            flow.messageRef = options.messageRef;
+        this._messageFlows.push(flow);
+        return this;
+    }
+    /**
+     * Reports every way the declared collaboration would not survive contact with
+     * a modeler, so `build()` can refuse rather than emit a file that opens broken.
+     */
+    collaborationProblems() {
+        const problems = [];
+        const seen = new Set();
+        for (const id of [
+            ...this._participants.map((p) => p.id),
+            ...this._messageFlows.map((f) => f.id),
+        ]) {
+            if (seen.has(id))
+                problems.push(`Duplicate element ID "${id}"`);
+            seen.add(id);
+        }
+        const processIds = new Set(this._processes.map((process) => process.id));
+        const claimed = new Map();
+        for (const participant of this._participants) {
+            const processId = participant.processRef;
+            if (processId === undefined)
+                continue;
+            if (!processIds.has(processId)) {
+                problems.push(`Participant "${participant.id}" references process "${processId}", which this diagram does not contain`);
+                continue;
+            }
+            const owner = claimed.get(processId);
+            if (owner !== undefined) {
+                problems.push(`Participants "${owner}" and "${participant.id}" both reference process "${processId}"; a process belongs to one pool`);
+            }
+            claimed.set(processId, participant.id);
+        }
+        const owningParticipant = this.participantIndex();
+        const messageIds = new Set(this._messages.map((message) => message.id));
+        for (const flow of this._messageFlows) {
+            for (const [role, ref] of [
+                ["source", flow.sourceRef],
+                ["target", flow.targetRef],
+            ]) {
+                if (!owningParticipant.has(ref)) {
+                    problems.push(`Message flow "${flow.id}" names ${role} "${ref}", which is not a participant or a flow node in one`);
+                }
+            }
+            const from = owningParticipant.get(flow.sourceRef);
+            const to = owningParticipant.get(flow.targetRef);
+            if (from !== undefined && from === to) {
+                problems.push(`Message flow "${flow.id}" starts and ends in participant "${from}"; a message flow crosses pools, a sequence flow stays inside one`);
+            }
+            if (flow.messageRef !== undefined && !messageIds.has(flow.messageRef)) {
+                problems.push(`Message flow "${flow.id}" references message "${flow.messageRef}", which this diagram does not declare`);
+            }
+        }
+        return problems;
+    }
+    /** Maps every participant id and every flow node id to its owning participant. */
+    participantIndex() {
+        const index = new Map();
+        const byProcess = new Map();
+        for (const participant of this._participants) {
+            index.set(participant.id, participant.id);
+            if (participant.processRef !== undefined)
+                byProcess.set(participant.processRef, participant.id);
+        }
+        const walk = (elements, owner) => {
+            for (const element of elements) {
+                index.set(element.id, owner);
+                if ("flowElements" in element && Array.isArray(element.flowElements)) {
+                    walk(element.flowElements, owner);
+                }
+            }
+        };
+        for (const process of this._processes) {
+            const owner = byProcess.get(process.id);
+            if (owner !== undefined)
+                walk(process.flowElements, owner);
+        }
+        return index;
+    }
     build() {
         return {
             id: this._id,
@@ -2022,10 +2403,35 @@ export class DiagramBuilder {
             escalations: [],
             messages: this._messages,
             signals: [],
-            collaborations: [],
+            collaborations: this.buildCollaborations(),
             processes: this._processes,
             diagrams: [],
         };
     }
+    /**
+     * A document with no participants has no collaboration — an empty
+     * `<bpmn:collaboration/>` is not a neutral addition, it makes every process a
+     * pool-less participant in a modeler.
+     */
+    buildCollaborations() {
+        if (this._participants.length === 0 && this._messageFlows.length === 0)
+            return [];
+        const problems = this.collaborationProblems();
+        if (problems.length > 0) {
+            throw new Error(`Invalid collaboration:\n  ${problems.join("\n  ")}`);
+        }
+        return [
+            {
+                id: this._collaborationId,
+                participants: this._participants,
+                messageFlows: this._messageFlows,
+                textAnnotations: [],
+                associations: [],
+                groups: [],
+                extensionElements: [],
+                unknownAttributes: {},
+            },
+        ];
+    }
 }
 //# sourceMappingURL=bpmn-builder.js.map