@bpmnkit/core 0.0.24 → 0.0.25

package/dist/bpmn/bpmn-builder.d.ts

@@ -1,8 +1,9 @@
-import type { BpmnAssociation, BpmnDefinitions, BpmnFlowElement, BpmnSequenceFlow, BpmnTextAnnotation } from "./bpmn-model.js";
+import type { BpmnAssociation, BpmnDefinitions, BpmnError, BpmnEscalation, BpmnFlowElement, BpmnMessage, BpmnSequenceFlow, BpmnSignal, BpmnTextAnnotation } from "./bpmn-model.js";
 import type { RestConnectorConfig } from "./rest-connector.js";
 /** Options shared by all element methods. */
 export interface ElementOptions {
     name?: string;
+    isForCompensation?: boolean;
 }
 /** Options for creating a start event. */
 export interface StartEventOptions extends ElementOptions {
@@ -25,6 +26,11 @@ export interface StartEventOptions extends ElementOptions {
     modelerTemplateVersion?: string;
     /** Zeebe modeler template icon (data URI). */
     modelerTemplateIcon?: string;
+    /**
+     * Non-interrupting flag — only meaningful for start events inside event sub-processes.
+     * Pass `false` to emit `isInterrupting="false"`. Omit for the default interrupting behavior.
+     */
+    isInterrupting?: boolean;
 }
 /** Options for creating a service task. */
 export interface ServiceTaskOptions {
@@ -53,6 +59,8 @@ export interface ServiceTaskOptions {
     modelerTemplateVersion?: string;
     /** Zeebe modeler template icon (data URI). */
     modelerTemplateIcon?: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a script task. */
 export interface ScriptTaskOptions {
@@ -62,6 +70,8 @@ export interface ScriptTaskOptions {
     expression: string;
     /** Variable name to store the result. */
     resultVariable: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a user task. */
 export interface UserTaskOptions {
@@ -71,6 +81,8 @@ export interface UserTaskOptions {
     formId?: string;
     /** Emit <zeebe:userTask /> to mark as a Camunda 8 native user task. */
     zeebeUserTask?: boolean;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a call activity. */
 export interface CallActivityOptions {
@@ -80,6 +92,8 @@ export interface CallActivityOptions {
     processId: string;
     /** Whether to propagate all child variables. */
     propagateAllChildVariables?: boolean;
+    /** Mark this activity as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a business rule task. */
 export interface BusinessRuleTaskOptions {
@@ -91,6 +105,8 @@ export interface BusinessRuleTaskOptions {
     decisionId?: string;
     /** Variable to store the result. */
     resultVariable?: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for gateway elements. */
 export interface GatewayOptions extends ElementOptions {
@@ -118,12 +134,16 @@ export interface IntermediateThrowEventOptions extends ElementOptions {
     signalName?: string;
     /** Escalation code — creates an escalation throw event (aspirational). */
     escalationCode?: string;
+    /** Emit a compensateEventDefinition. */
+    compensation?: boolean;
+    /** Activity to compensate (activityRef attribute on compensateEventDefinition). */
+    activityRef?: string;
 }
 /** Options for an end event. */
 export interface EndEventOptions extends ElementOptions {
     /** Error code — creates an error end event. */
     errorCode?: string;
-    /** Error reference ID. */
+    /** Error code — creates an error end event. Alias for errorCode. */
     errorRef?: string;
     /** Message name — creates a message end event. */
     messageName?: string;
@@ -140,7 +160,7 @@ export interface BoundaryEventOptions extends ElementOptions {
     cancelActivity?: boolean;
     /** Error code — creates an error boundary event. */
     errorCode?: string;
-    /** Error reference ID. */
+    /** Error code — creates an error boundary event. Alias for errorCode. */
     errorRef?: string;
     /** Timer duration — creates a timer boundary event (aspirational). */
     timerDuration?: string;
@@ -152,6 +172,8 @@ export interface BoundaryEventOptions extends ElementOptions {
     messageName?: string;
     /** Signal name — creates a signal boundary event (aspirational). */
     signalName?: string;
+    /** Creates a compensation boundary event. */
+    compensation?: boolean;
 }
 /** Multi-instance loop configuration. */
 export interface MultiInstanceOptions {
@@ -231,8 +253,12 @@ export declare class BranchBuilder {
     /** @internal */
     readonly _associations: BpmnAssociation[];
     private readonly _annCounters;
+    private readonly rootErrors;
+    private readonly rootMessages;
+    private readonly rootSignals;
+    private readonly rootEscalations;
     /** @internal */
-    constructor(gatewayId: string, branchName: string);
+    constructor(gatewayId: string, branchName: string, rootErrors?: BpmnError[], rootMessages?: BpmnMessage[], rootSignals?: BpmnSignal[], rootEscalations?: BpmnEscalation[]);
     /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
     condition(expression: string): this;
     /** Mark this branch as the gateway's default (no-condition) flow. */
@@ -256,6 +282,8 @@ export declare class BranchBuilder {
     receiveTask(id: string, options?: ElementOptions): this;
     businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     callActivity(id: string, options: CallActivityOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
     startEvent(id?: string, options?: StartEventOptions): this;
     endEvent(id?: string, options?: EndEventOptions): this;
     intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
@@ -291,6 +319,8 @@ export declare class SubProcessContentBuilder {
     callActivity(id: string, options: CallActivityOptions): this;
     sendTask(id: string, options?: ElementOptions): this;
     receiveTask(id: string, options?: ElementOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
     exclusiveGateway(id: string, options?: GatewayOptions): this;
     parallelGateway(id: string, options?: ElementOptions): this;
     inclusiveGateway(id: string, options?: GatewayOptions): this;
@@ -313,6 +343,8 @@ export declare class ProcessBuilder {
     private readonly sequenceFlows;
     private readonly rootErrors;
     private readonly rootMessages;
+    private readonly rootSignals;
+    private readonly rootEscalations;
     private readonly _textAnnotations;
     private readonly _associations;
     private readonly _annCounters;
@@ -322,6 +354,7 @@ export declare class ProcessBuilder {
     private _autoLayout;
     private _executionPlatformVersion;
     private _serviceTaskDefaults;
+    private _savedMainFlowId;
     constructor(processId: string);
     /** Enable auto-layout: `build()` will run the layout engine and populate diagram interchange data. */
     withAutoLayout(): this;
@@ -393,6 +426,8 @@ export declare class ProcessBuilder {
     businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     /** Add a call activity referencing another process. */
     callActivity(id: string, options: CallActivityOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
     /** Add an exclusive gateway (XOR split/join). */
     exclusiveGateway(id: string, options?: GatewayOptions): this;
     /** Add a parallel gateway (AND split/join). */
@@ -432,7 +467,7 @@ export declare class ProcessBuilder {
     adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
     /** Add a sub-process (aspirational). */
     subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
-    /** Add an event sub-process (aspirational). */
+    /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
     eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
     /** Attach a text annotation to the element at the current cursor position. */
     textAnnotation(text: string): this;

package/dist/bpmn/bpmn-builder.js

@@ -7,7 +7,7 @@ const EXPORTER_VERSION = "0.0.23";
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-function buildEventDefinitions(opts, rootErrors, rootMessages) {
+function buildEventDefinitions(opts, rootErrors, rootMessages, rootSignals, rootEscalations) {
     const defs = [];
     if (opts.timerDuration || opts.timerDate || opts.timerCycle) {
         defs.push({
@@ -18,28 +18,63 @@ function buildEventDefinitions(opts, rootErrors, rootMessages) {
         });
     }
     if (opts.errorCode !== undefined || opts.errorRef !== undefined) {
-        let errorRef = opts.errorRef;
-        if (!errorRef && opts.errorCode !== undefined && rootErrors) {
-            const errorId = generateId("Error");
-            rootErrors.push({ id: errorId, name: opts.errorCode, errorCode: opts.errorCode });
-            errorRef = errorId;
+        const codeOrRef = opts.errorCode ?? opts.errorRef;
+        let errorRef;
+        if (codeOrRef !== undefined && rootErrors) {
+            let existing = rootErrors.find((e) => e.errorCode === codeOrRef || e.name === codeOrRef);
+            if (!existing) {
+                existing = { id: generateId("Error"), name: codeOrRef, errorCode: codeOrRef };
+                rootErrors.push(existing);
+            }
+            errorRef = existing.id;
+        }
+        else {
+            errorRef = codeOrRef;
         }
         defs.push({ type: "error", errorRef });
     }
     if (opts.messageName !== undefined) {
         let messageRef = opts.messageName;
         if (rootMessages) {
-            const messageId = generateId("Message");
-            rootMessages.push({ id: messageId, name: opts.messageName, unknownAttributes: {} });
-            messageRef = messageId;
+            let existing = rootMessages.find((m) => m.name === opts.messageName);
+            if (!existing) {
+                existing = { id: generateId("Message"), name: opts.messageName, unknownAttributes: {} };
+                rootMessages.push(existing);
+            }
+            messageRef = existing.id;
         }
         defs.push({ type: "message", messageRef });
     }
     if (opts.signalName !== undefined) {
-        defs.push({ type: "signal", signalRef: opts.signalName });
+        let signalRef = opts.signalName;
+        if (rootSignals) {
+            let existing = rootSignals.find((s) => s.name === opts.signalName);
+            if (!existing) {
+                existing = { id: generateId("Signal"), name: opts.signalName };
+                rootSignals.push(existing);
+            }
+            signalRef = existing.id;
+        }
+        defs.push({ type: "signal", signalRef });
     }
     if (opts.escalationCode !== undefined) {
-        defs.push({ type: "escalation", escalationRef: opts.escalationCode });
+        let escalationRef = opts.escalationCode;
+        if (rootEscalations) {
+            let existing = rootEscalations.find((e) => e.escalationCode === opts.escalationCode);
+            if (!existing) {
+                existing = {
+                    id: generateId("Escalation"),
+                    name: opts.escalationCode,
+                    escalationCode: opts.escalationCode,
+                };
+                rootEscalations.push(existing);
+            }
+            escalationRef = existing.id;
+        }
+        defs.push({ type: "escalation", escalationRef });
+    }
+    if (opts.compensation) {
+        defs.push({ type: "compensate", activityRef: opts.activityRef });
     }
     return defs;
 }
@@ -213,10 +248,12 @@ function makeServiceTaskEl(id, options) {
         extensionElements: buildServiceTaskExtensions(options),
     });
     el.unknownAttributes = unknownAttributes;
+    if (options.isForCompensation)
+        el.isForCompensation = true;
     return el;
 }
 function makeScriptTaskEl(id, options) {
-    return makeFlowElement(id, "scriptTask", {
+    const el = makeFlowElement(id, "scriptTask", {
         name: options.name,
         extensionElements: zeebeExtensionsToXmlElements({
             unknownElements: [
@@ -228,13 +265,19 @@ function makeScriptTaskEl(id, options) {
             ],
         }),
     });
+    if (options.isForCompensation)
+        el.isForCompensation = true;
+    return el;
 }
 function makeUserTaskEl(id, options) {
     const ext = zeebeExtensionsToXmlElements({
         ...(options?.zeebeUserTask ? { userTask: true } : {}),
         ...(options?.formId ? { formDefinition: { formId: options.formId } } : {}),
     });
-    return makeFlowElement(id, "userTask", { name: options?.name, extensionElements: ext });
+    const el = makeFlowElement(id, "userTask", { name: options?.name, extensionElements: ext });
+    if (options?.isForCompensation)
+        el.isForCompensation = true;
+    return el;
 }
 function makeBusinessRuleTaskEl(id, options) {
     const ext = [];
@@ -249,19 +292,28 @@ function makeBusinessRuleTaskEl(id, options) {
             },
         }));
     }
-    return makeFlowElement(id, "businessRuleTask", { name: options?.name, extensionElements: ext });
+    const el = makeFlowElement(id, "businessRuleTask", {
+        name: options?.name,
+        extensionElements: ext,
+    });
+    if (options?.isForCompensation)
+        el.isForCompensation = true;
+    return el;
 }
 function makeCallActivityEl(id, options) {
     const attrs = { processId: options.processId };
     if (options.propagateAllChildVariables !== undefined) {
         attrs.propagateAllChildVariables = String(options.propagateAllChildVariables);
     }
-    return makeFlowElement(id, "callActivity", {
+    const el = makeFlowElement(id, "callActivity", {
         name: options.name,
         extensionElements: zeebeExtensionsToXmlElements({
             unknownElements: [{ name: "zeebe:calledElement", attributes: attrs, children: [] }],
         }),
     });
+    if (options.isForCompensation)
+        el.isForCompensation = true;
+    return el;
 }
 function makeExclusiveGatewayEl(id, options) {
     const el = makeFlowElement(id, "exclusiveGateway", options);
@@ -332,15 +384,17 @@ function insertJoinGateways(elements, flows) {
             const gwType = elementTypes.get(splitId);
             if (!gwType)
                 continue;
+            // eventBasedGateway is split-only; converge through an XOR join instead
+            const joinType = gwType === "eventBasedGateway" ? "exclusiveGateway" : gwType;
             const targetType = elementTypes.get(targetId);
-            if (targetType === gwType)
+            if (targetType === joinType)
                 continue;
             const joinId = `${splitId}_join`;
             if (elementTypes.has(joinId))
                 continue;
-            const joinElement = makeFlowElement(joinId, gwType, {});
+            const joinElement = makeFlowElement(joinId, joinType, {});
             elements.push(joinElement);
-            elementTypes.set(joinId, gwType);
+            elementTypes.set(joinId, joinType);
             for (const flow of convergingFlows)
                 flow.targetRef = joinId;
             flows.push({
@@ -401,11 +455,19 @@ export class BranchBuilder {
     /** @internal */
     _associations = [];
     _annCounters = new Map();
+    rootErrors;
+    rootMessages;
+    rootSignals;
+    rootEscalations;
     /** @internal */
-    constructor(gatewayId, branchName) {
+    constructor(gatewayId, branchName, rootErrors = [], rootMessages = [], rootSignals = [], rootEscalations = []) {
         this.gatewayId = gatewayId;
         this.branchName = branchName;
         this.lastNodeId = gatewayId;
+        this.rootErrors = rootErrors;
+        this.rootMessages = rootMessages;
+        this.rootSignals = rootSignals;
+        this.rootEscalations = rootEscalations;
     }
     /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
     condition(expression) {
@@ -500,10 +562,16 @@ export class BranchBuilder {
         return this.addElement(makeScriptTaskEl(id, options));
     }
     sendTask(id, options) {
-        return this.addElement(makeFlowElement(id, "sendTask", options));
+        const el = makeFlowElement(id, "sendTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
     }
     receiveTask(id, options) {
-        return this.addElement(makeFlowElement(id, "receiveTask", options));
+        const el = makeFlowElement(id, "receiveTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
     }
     businessRuleTask(id, options) {
         return this.addElement(makeBusinessRuleTaskEl(id, options));
@@ -511,32 +579,38 @@ export class BranchBuilder {
     callActivity(id, options) {
         return this.addElement(makeCallActivityEl(id, options));
     }
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id, options) {
+        const el = makeFlowElement(id, "task", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
+    }
     startEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
-        if (el.type === "startEvent" &&
-            (options?.timerDuration || options?.timerCycle || options?.timerDate)) {
-            el.eventDefinitions = buildEventDefinitions(options);
+        if (el.type === "startEvent" && options) {
+            el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         return this.addElement(el);
     }
     endEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("EndEvent"), "endEvent", options);
         if (el.type === "endEvent" && options) {
-            el.eventDefinitions = buildEventDefinitions(options);
+            el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         return this.addElement(el);
     }
     intermediateThrowEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("IntermediateThrowEvent"), "intermediateThrowEvent", options);
         if (el.type === "intermediateThrowEvent" && options) {
-            el.eventDefinitions = buildEventDefinitions(options);
+            el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         return this.addElement(el);
     }
     intermediateCatchEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", options);
         if (el.type === "intermediateCatchEvent" && options) {
-            el.eventDefinitions = buildEventDefinitions(options);
+            el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         return this.addElement(el);
     }
@@ -600,8 +674,11 @@ export class SubProcessContentBuilder {
     // ---- Events ----
     startEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
-        if (el.type === "startEvent" && options)
+        if (el.type === "startEvent" && options) {
             el.eventDefinitions = buildEventDefinitions(options);
+            if (options.isInterrupting === false)
+                el.isInterrupting = false;
+        }
         return this.addElement(el);
     }
     endEvent(id, options) {
@@ -639,10 +716,23 @@ export class SubProcessContentBuilder {
         return this.addElement(makeCallActivityEl(id, options));
     }
     sendTask(id, options) {
-        return this.addElement(makeFlowElement(id, "sendTask", options));
+        const el = makeFlowElement(id, "sendTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
     }
     receiveTask(id, options) {
-        return this.addElement(makeFlowElement(id, "receiveTask", options));
+        const el = makeFlowElement(id, "receiveTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
+    }
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id, options) {
+        const el = makeFlowElement(id, "task", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
     }
     // ---- Gateways ----
     exclusiveGateway(id, options) {
@@ -753,6 +843,8 @@ export class ProcessBuilder {
     sequenceFlows = [];
     rootErrors = [];
     rootMessages = [];
+    rootSignals = [];
+    rootEscalations = [];
     _textAnnotations = [];
     _associations = [];
     _annCounters = new Map();
@@ -762,6 +854,7 @@ export class ProcessBuilder {
     _autoLayout = false;
     _executionPlatformVersion = "8.9.0";
     _serviceTaskDefaults = {};
+    _savedMainFlowId = undefined;
     constructor(processId) {
         this.processId = processId;
     }
@@ -811,7 +904,9 @@ export class ProcessBuilder {
             extensionElements: extElements,
         });
         if (element.type === "startEvent" && options) {
-            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
+            if (options.isInterrupting === false)
+                element.isInterrupting = false;
         }
         if (options?.modelerTemplate) {
             element.unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
@@ -850,7 +945,7 @@ export class ProcessBuilder {
         const nodeId = id ?? generateId("EndEvent");
         const element = makeFlowElement(nodeId, "endEvent", options);
         if (element.type === "endEvent" && options) {
-            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         this.addFlowElement(element);
         return this;
@@ -860,7 +955,7 @@ export class ProcessBuilder {
         const nodeId = id ?? generateId("IntermediateThrowEvent");
         const element = makeFlowElement(nodeId, "intermediateThrowEvent", options);
         if (element.type === "intermediateThrowEvent" && options) {
-            element.eventDefinitions = buildEventDefinitions(options);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         this.addFlowElement(element);
         return this;
@@ -870,7 +965,7 @@ export class ProcessBuilder {
         const nodeId = id ?? generateId("IntermediateCatchEvent");
         const element = makeFlowElement(nodeId, "intermediateCatchEvent", options);
         if (element.type === "intermediateCatchEvent" && options) {
-            element.eventDefinitions = buildEventDefinitions(options);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         this.addFlowElement(element);
         return this;
@@ -886,12 +981,17 @@ export class ProcessBuilder {
         if (element.type === "boundaryEvent") {
             element.attachedToRef = options.attachedTo;
             element.cancelActivity = options.cancelActivity;
-            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         // Boundary events never auto-connect — temporarily clear lastNodeId
         const prevLast = this.lastNodeId;
         this.lastNodeId = undefined;
         this.addFlowElement(element);
+        // For compensation boundary events, save the main-flow cursor AFTER addFlowElement
+        // so subsequent normal elements don't accidentally clear it before it's consumed.
+        if (options.compensation) {
+            this._savedMainFlowId = prevLast;
+        }
         // Don't restore prevLast — the builder now chains from the boundary event
         void prevLast;
         return this;
@@ -921,6 +1021,7 @@ export class ProcessBuilder {
         this.lastNodeId = savedLast;
         this.currentGatewayId = savedGateway;
         this.openBranchEnds = savedOpenEnds;
+        this._savedMainFlowId = undefined;
         return this;
     }
     // ---- Tasks ----
@@ -971,12 +1072,18 @@ export class ProcessBuilder {
     }
     /** Add a send task (aspirational). */
     sendTask(id, options) {
-        this.addFlowElement(makeFlowElement(id, "sendTask", options));
+        const el = makeFlowElement(id, "sendTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        this.addFlowElement(el);
         return this;
     }
     /** Add a receive task (aspirational). */
     receiveTask(id, options) {
-        this.addFlowElement(makeFlowElement(id, "receiveTask", options));
+        const el = makeFlowElement(id, "receiveTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        this.addFlowElement(el);
         return this;
     }
     /** Add a business rule task. */
@@ -989,6 +1096,14 @@ export class ProcessBuilder {
         this.addFlowElement(makeCallActivityEl(id, options));
         return this;
     }
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id, options) {
+        const el = makeFlowElement(id, "task", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        this.addFlowElement(el);
+        return this;
+    }
     // ---- Gateways ----
     /** Add an exclusive gateway (XOR split/join). */
     exclusiveGateway(id, options) {
@@ -1036,7 +1151,7 @@ export class ProcessBuilder {
         if (!this.currentGatewayId) {
             throw new Error("branch() must be called after a gateway element");
         }
-        const b = new BranchBuilder(this.currentGatewayId, name);
+        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)) {
@@ -1187,20 +1302,29 @@ export class ProcessBuilder {
         this.addFlowElement(element);
         return this;
     }
-    /** Add an event sub-process (aspirational). */
+    /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
     eventSubProcess(id, content, options) {
         const sub = new SubProcessContentBuilder();
         content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
-        const element = makeFlowElement(id, "eventSubProcess", options);
-        if (element.type === "eventSubProcess") {
+        const element = makeFlowElement(id, "subProcess", options);
+        if (element.type === "subProcess") {
+            element.triggeredByEvent = true;
             element.flowElements = sub._elements;
             element.sequenceFlows = sub._flows;
             element.textAnnotations = sub._textAnnotations;
             element.associations = sub._associations;
         }
-        this.addFlowElement(element);
+        // Event sub-processes have no incoming/outgoing sequence flows and must not
+        // 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)) {
+            throw new Error(`Duplicate element ID "${element.id}" in process "${this.processId}"`);
+        }
+        this._savedMainFlowId = undefined;
+        this.flowElements.push(element);
         return this;
     }
     // ---- Annotations ----
@@ -1283,9 +1407,9 @@ export class ProcessBuilder {
                 "modeler:executionPlatformVersion": this._executionPlatformVersion,
             },
             errors: this.rootErrors,
-            escalations: [],
+            escalations: this.rootEscalations,
             messages: this.rootMessages,
-            signals: [],
+            signals: this.rootSignals,
             collaborations: [],
             processes: [process],
             // Seed diagram stub so applyAutoLayout preserves process-specific IDs.
@@ -1323,6 +1447,24 @@ export class ProcessBuilder {
             throw new Error(`Duplicate element ID "${element.id}" in process "${this.processId}"`);
         }
         this.flowElements.push(element);
+        // 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) {
+            if (this.lastNodeId) {
+                this._associations.push({
+                    id: generateId("Association"),
+                    sourceRef: this.lastNodeId,
+                    targetRef: element.id,
+                    associationDirection: "One",
+                    unknownAttributes: {},
+                });
+            }
+            // Restore main-flow cursor (saved by boundaryEvent() when compensation: true)
+            this.lastNodeId = this._savedMainFlowId;
+            this._savedMainFlowId = undefined;
+            // Do NOT connect open branch ends — handler is outside normal flow
+            return;
+        }
         if (this.lastNodeId) {
             const flowId = generateId("Flow");
             this.sequenceFlows.push({
@@ -1345,6 +1487,9 @@ export class ProcessBuilder {
             });
         }
         this.openBranchEnds = [];
+        // Clear any saved compensation cursor — a normal element advancing the cursor
+        // means the compensation boundary/handler pattern has been interrupted.
+        this._savedMainFlowId = undefined;
         this.lastNodeId = element.id;
     }
 }

package/dist/bpmn/bpmn-model.d.ts

@@ -105,10 +105,12 @@ interface BpmnFlowNodeBase {
     documentation?: string;
     extensionElements: XmlElement[];
     unknownAttributes: Record<string, string>;
+    isForCompensation?: boolean;
 }
 export interface BpmnStartEvent extends BpmnFlowNodeBase {
     type: "startEvent";
     eventDefinitions: BpmnEventDefinition[];
+    isInterrupting?: boolean;
 }
 export interface BpmnEndEvent extends BpmnFlowNodeBase {
     type: "endEvent";

package/dist/bpmn/bpmn-parser.js

@@ -42,6 +42,7 @@ const KNOWN_ATTRS = new Set([
     "default",
     "attachedToRef",
     "cancelActivity",
+    "isForCompensation",
     "sourceRef",
     "targetRef",
     "associationDirection",
@@ -275,7 +276,15 @@ function parseFlowElement(element) {
         unknownAttributes: unknownAttrs(element),
     };
     switch (ln) {
-        case "startEvent":
+        case "startEvent": {
+            const isInterruptingAttr = attr(element, "isInterrupting");
+            return {
+                ...base,
+                type: "startEvent",
+                eventDefinitions: parseEventDefinitions(element),
+                ...(isInterruptingAttr === "false" ? { isInterrupting: false } : {}),
+            };
+        }
         case "endEvent":
         case "intermediateCatchEvent":
         case "intermediateThrowEvent":
@@ -299,7 +308,12 @@ function parseFlowElement(element) {
         case "businessRuleTask":
         case "manualTask":
         case "callActivity":
-            return { ...base, type: ln, loopCharacteristics: parseLoopCharacteristics(element) };
+            return {
+                ...base,
+                type: ln,
+                loopCharacteristics: parseLoopCharacteristics(element),
+                isForCompensation: attr(element, "isForCompensation") === "true" ? true : undefined,
+            };
         case "adHocSubProcess":
             return {
                 ...base,

package/dist/bpmn/bpmn-serializer.js

@@ -157,6 +157,8 @@ function serializeFlowElement(fe, ns) {
     const attrs = { id: fe.id, ...fe.unknownAttributes };
     if (fe.name !== undefined)
         attrs.name = fe.name;
+    if (fe.isForCompensation)
+        attrs.isForCompensation = "true";
     const children = [];
     // Documentation
     if (fe.documentation !== undefined) {
@@ -169,6 +171,10 @@ function serializeFlowElement(fe, ns) {
     children.push(...flowRefs(fe.outgoing, "outgoing", bp));
     switch (fe.type) {
         case "startEvent":
+            if (fe.isInterrupting === false)
+                attrs.isInterrupting = "false";
+            children.push(...serializeEventDefinitions(fe.eventDefinitions, bp));
+            break;
         case "endEvent":
         case "intermediateCatchEvent":
         case "intermediateThrowEvent":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/core",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",