@bpmnkit/core 0.1.1 → 0.2.0

package/dist/bpmn/zeebe-extensions.js

@@ -1,3 +1,4 @@
+import { ZEEBE_PLACEMENT } from "./zeebe-placement.js";
 /** Convert Zeebe extensions to XmlElement array for the BPMN model. */
 export function zeebeExtensionsToXmlElements(extensions) {
     const elements = [];
@@ -91,9 +92,125 @@ export function zeebeExtensionsToXmlElements(extensions) {
             children: [],
         });
     }
+    if (extensions.assignmentDefinition) {
+        const attrs = {};
+        const { assignee, candidateGroups, candidateUsers } = extensions.assignmentDefinition;
+        if (assignee)
+            attrs.assignee = assignee;
+        if (candidateGroups)
+            attrs.candidateGroups = candidateGroups;
+        if (candidateUsers)
+            attrs.candidateUsers = candidateUsers;
+        if (Object.keys(attrs).length > 0) {
+            elements.push({ name: "zeebe:assignmentDefinition", attributes: attrs, children: [] });
+        }
+    }
+    if (extensions.taskSchedule) {
+        const attrs = {};
+        if (extensions.taskSchedule.dueDate)
+            attrs.dueDate = extensions.taskSchedule.dueDate;
+        if (extensions.taskSchedule.followUpDate) {
+            attrs.followUpDate = extensions.taskSchedule.followUpDate;
+        }
+        if (Object.keys(attrs).length > 0) {
+            elements.push({ name: "zeebe:taskSchedule", attributes: attrs, children: [] });
+        }
+    }
+    if (extensions.priorityDefinition) {
+        elements.push({
+            name: "zeebe:priorityDefinition",
+            attributes: { priority: extensions.priorityDefinition.priority },
+            children: [],
+        });
+    }
+    if (extensions.subscription) {
+        elements.push({
+            name: "zeebe:subscription",
+            attributes: { correlationKey: extensions.subscription.correlationKey },
+            children: [],
+        });
+    }
     if (extensions.unknownElements) {
         elements.push(...extensions.unknownElements);
     }
     return elements;
 }
+// ---------------------------------------------------------------------------
+// Placement
+// ---------------------------------------------------------------------------
+/**
+ * Reports where a Zeebe extension may go, from the descriptor rather than from
+ * our own idea of the rules.
+ *
+ * `zeebe.json` records a `meta.allowedIn` list per extension type;
+ * `scripts/generate-zeebe-placement.ts` resolves those entries — many of which
+ * name abstract BPMN types or Zeebe aliases — into the concrete element names in
+ * `ZEEBE_PLACEMENT`. Writing `zeebe:calledDecision` onto a service task produces
+ * a file Camunda rejects at deploy time; catching it at the write is the point.
+ *
+ * **An extension the table does not mention is allowed.** The descriptor
+ * declares no owner for `zeebe:subscription` or `zeebe:properties`, so we do not
+ * know where they may go and must not invent a rule — this check rejects only
+ * what the descriptor positively forbids. Vendor extensions outside the `zeebe:`
+ * namespace are not this function's business and are likewise allowed.
+ *
+ * @param ownerElement - The owner's BPMN element name, e.g. `bpmn:serviceTask`.
+ * @param extension - The extension element name, e.g. `zeebe:taskDefinition`.
+ */
+export function isZeebePlacementAllowed(ownerElement, extension) {
+    const owners = ZEEBE_PLACEMENT[extension];
+    return owners === undefined || owners.includes(ownerElement);
+}
+/** Thrown when a Zeebe extension is written somewhere the descriptor forbids. */
+export class ZeebePlacementError extends Error {
+    ownerElement;
+    extension;
+    allowedOn;
+    constructor(ownerElement, extension, allowedOn) {
+        super(`<${extension}> is not allowed on <${ownerElement}>. The Zeebe schema allows it on: ${allowedOn.join(", ")}.`);
+        this.ownerElement = ownerElement;
+        this.extension = extension;
+        this.allowedOn = allowedOn;
+        this.name = "ZeebePlacementError";
+    }
+}
+/**
+ * Throws {@link ZeebePlacementError} if the placement is one the descriptor
+ * forbids. See {@link isZeebePlacementAllowed} for what "forbids" covers.
+ */
+export function assertZeebePlacement(ownerElement, extension) {
+    if (isZeebePlacementAllowed(ownerElement, extension))
+        return;
+    throw new ZeebePlacementError(ownerElement, extension, ZEEBE_PLACEMENT[extension] ?? []);
+}
+/**
+ * The BPMN element name a flow element is written as.
+ *
+ * The model's `type` is the element's local name in every case but one:
+ * `eventSubProcess` is our name for a `bpmn:subProcess` carrying
+ * `triggeredByEvent`, and BPMN has no element of that name.
+ */
+export function bpmnElementName(flowElement) {
+    const local = flowElement.type === "eventSubProcess" ? "subProcess" : flowElement.type;
+    return `bpmn:${local}`;
+}
+/**
+ * Finds a Zeebe extension element on a flow element, creating it if absent, and
+ * refuses a placement the descriptor forbids.
+ *
+ * Use this rather than pushing onto `extensionElements` directly: the push
+ * cannot fail, so an extension on the wrong element becomes a deploy-time error
+ * in someone else's terminal instead of a throw here.
+ *
+ * @throws ZeebePlacementError
+ */
+export function ensureZeebeExtension(owner, extension) {
+    assertZeebePlacement(bpmnElementName(owner), extension);
+    const existing = owner.extensionElements.find((candidate) => candidate.name === extension);
+    if (existing)
+        return existing;
+    const created = { name: extension, attributes: {}, children: [] };
+    owner.extensionElements.push(created);
+    return created;
+}
 //# sourceMappingURL=zeebe-extensions.js.map

package/dist/bpmn/zeebe-placement.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Where each Zeebe extension element may be placed, keyed by element name.
+ *
+ * The value is the set of element names that may own it. Owners are BPMN
+ * elements for extensions that sit in an `extensionElements` bag, and Zeebe
+ * elements for the few that nest inside another extension.
+ *
+ * An extension absent from this table is one the descriptor says nothing about;
+ * see `isZeebePlacementAllowed` for what that means.
+ */
+export declare const ZEEBE_PLACEMENT: Readonly<Record<string, readonly string[]>>;
+//# sourceMappingURL=zeebe-placement.d.ts.map

package/dist/bpmn/zeebe-placement.js

@@ -0,0 +1,140 @@
+// Generated by scripts/generate-zeebe-placement.ts — do not edit.
+// Source: descriptors/zeebe.json (zeebe-bpmn-moddle, MIT) resolved against
+// descriptors/bpmn.json (bpmn-moddle, MIT). Regenerate with:
+//   pnpm --filter @bpmnkit/core generate:placement
+/**
+ * Where each Zeebe extension element may be placed, keyed by element name.
+ *
+ * The value is the set of element names that may own it. Owners are BPMN
+ * elements for extensions that sit in an `extensionElements` bag, and Zeebe
+ * elements for the few that nest inside another extension.
+ *
+ * An extension absent from this table is one the descriptor says nothing about;
+ * see `isZeebePlacementAllowed` for what that means.
+ */
+export const ZEEBE_PLACEMENT = {
+    "zeebe:adHoc": ["bpmn:adHocSubProcess"],
+    "zeebe:agentDefinition": ["bpmn:adHocSubProcess", "bpmn:serviceTask"],
+    "zeebe:assignmentDefinition": ["bpmn:userTask"],
+    "zeebe:calledDecision": ["bpmn:businessRuleTask"],
+    "zeebe:calledElement": ["bpmn:callActivity"],
+    "zeebe:conditionalFilter": ["bpmn:conditionalEventDefinition"],
+    "zeebe:executionListener": ["zeebe:executionListeners"],
+    "zeebe:executionListeners": [
+        "bpmn:adHocSubProcess",
+        "bpmn:boundaryEvent",
+        "bpmn:businessRuleTask",
+        "bpmn:callActivity",
+        "bpmn:endEvent",
+        "bpmn:eventBasedGateway",
+        "bpmn:exclusiveGateway",
+        "bpmn:implicitThrowEvent",
+        "bpmn:inclusiveGateway",
+        "bpmn:intermediateCatchEvent",
+        "bpmn:intermediateThrowEvent",
+        "bpmn:manualTask",
+        "bpmn:parallelGateway",
+        "bpmn:process",
+        "bpmn:receiveTask",
+        "bpmn:scriptTask",
+        "bpmn:sendTask",
+        "bpmn:serviceTask",
+        "bpmn:startEvent",
+        "bpmn:subProcess",
+        "bpmn:task",
+        "bpmn:transaction",
+        "bpmn:userTask",
+    ],
+    "zeebe:formDefinition": ["bpmn:startEvent", "bpmn:userTask"],
+    "zeebe:input": [
+        "bpmn:adHocSubProcess",
+        "bpmn:businessRuleTask",
+        "bpmn:callActivity",
+        "bpmn:endEvent",
+        "bpmn:intermediateThrowEvent",
+        "bpmn:scriptTask",
+        "bpmn:sendTask",
+        "bpmn:serviceTask",
+        "bpmn:subProcess",
+        "bpmn:transaction",
+        "bpmn:userTask",
+    ],
+    "zeebe:ioMapping": [
+        "bpmn:adHocSubProcess",
+        "bpmn:boundaryEvent",
+        "bpmn:businessRuleTask",
+        "bpmn:callActivity",
+        "bpmn:endEvent",
+        "bpmn:implicitThrowEvent",
+        "bpmn:intermediateCatchEvent",
+        "bpmn:intermediateThrowEvent",
+        "bpmn:receiveTask",
+        "bpmn:scriptTask",
+        "bpmn:sendTask",
+        "bpmn:serviceTask",
+        "bpmn:startEvent",
+        "bpmn:subProcess",
+        "bpmn:transaction",
+        "bpmn:userTask",
+    ],
+    "zeebe:jobPriorityDefinition": [
+        "bpmn:adHocSubProcess",
+        "bpmn:businessRuleTask",
+        "bpmn:endEvent",
+        "bpmn:intermediateThrowEvent",
+        "bpmn:process",
+        "bpmn:scriptTask",
+        "bpmn:sendTask",
+        "bpmn:serviceTask",
+    ],
+    "zeebe:linkedResource": ["bpmn:serviceTask"],
+    "zeebe:linkedResources": ["bpmn:serviceTask"],
+    "zeebe:loopCharacteristics": ["bpmn:multiInstanceLoopCharacteristics"],
+    "zeebe:output": [
+        "bpmn:adHocSubProcess",
+        "bpmn:boundaryEvent",
+        "bpmn:businessRuleTask",
+        "bpmn:callActivity",
+        "bpmn:endEvent",
+        "bpmn:implicitThrowEvent",
+        "bpmn:intermediateCatchEvent",
+        "bpmn:intermediateThrowEvent",
+        "bpmn:receiveTask",
+        "bpmn:scriptTask",
+        "bpmn:sendTask",
+        "bpmn:serviceTask",
+        "bpmn:startEvent",
+        "bpmn:subProcess",
+        "bpmn:transaction",
+        "bpmn:userTask",
+    ],
+    "zeebe:priorityDefinition": ["bpmn:userTask"],
+    "zeebe:script": ["bpmn:scriptTask"],
+    "zeebe:taskDefinition": [
+        "bpmn:adHocSubProcess",
+        "bpmn:businessRuleTask",
+        "bpmn:endEvent",
+        "bpmn:intermediateThrowEvent",
+        "bpmn:scriptTask",
+        "bpmn:sendTask",
+        "bpmn:serviceTask",
+    ],
+    "zeebe:taskHeaders": [
+        "bpmn:adHocSubProcess",
+        "bpmn:businessRuleTask",
+        "bpmn:endEvent",
+        "bpmn:intermediateThrowEvent",
+        "bpmn:scriptTask",
+        "bpmn:sendTask",
+        "bpmn:serviceTask",
+        "bpmn:userTask",
+        "zeebe:executionListener",
+    ],
+    "zeebe:taskListener": ["zeebe:taskListeners"],
+    "zeebe:taskListeners": ["bpmn:userTask"],
+    "zeebe:taskSchedule": ["bpmn:userTask"],
+    "zeebe:userTask": ["bpmn:userTask"],
+    "zeebe:userTaskForm": ["bpmn:process"],
+    "zeebe:versionTag": ["bpmn:process"],
+};
+//# sourceMappingURL=zeebe-placement.js.map

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import type { SemanticDiff } from "./bpmn/semantic-hash.js";
 /**
  * Typed error codes for all errors thrown by `@bpmnkit/core`.
  *
@@ -18,7 +19,11 @@ export type ErrorCode =
 /** XML could not be parsed or a required attribute was missing. */
 "parse-error"
 /** A builder received an invalid combination of options. */
- | "validation-error";
+ | "validation-error"
+/** Serialising a model and reading it back did not reproduce the model. */
+ | "write-verification-error"
+/** The output file could not be written. */
+ | "write-error";
 /**
  * Base class for all errors thrown by `@bpmnkit/core`.
  *
@@ -74,4 +79,38 @@ export declare class ParseError extends BpmnSdkError {
 export declare class ValidationError extends BpmnSdkError {
     constructor(message: string);
 }
+/**
+ * Thrown when serialising a model and parsing the result back does not
+ * reproduce the model.
+ *
+ * This means the write would have put something on disk that no longer says
+ * what the model said, so nothing is written. {@link changes} names the
+ * elements that diverged.
+ *
+ * @example
+ * ```typescript
+ * import { writeBpmn } from "@bpmnkit/core/node"
+ * import { WriteVerificationError } from "@bpmnkit/core"
+ *
+ * try {
+ *   await writeBpmn(definitions, { output: "flow.bpmn" })
+ * } catch (err) {
+ *   if (err instanceof WriteVerificationError) {
+ *     console.error("would have lost:", err.changes.removed)
+ *   }
+ * }
+ * ```
+ */
+export declare class WriteVerificationError extends BpmnSdkError {
+    /** What differed between the model and the model read back from the output. */
+    readonly changes: SemanticDiff;
+    constructor(message: string, changes: SemanticDiff);
+}
+/**
+ * Thrown when the output file cannot be written — it already exists and
+ * `force` was not given, or the filesystem refused the write.
+ */
+export declare class WriteError extends BpmnSdkError {
+    constructor(message: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -63,4 +63,45 @@ export class ValidationError extends BpmnSdkError {
         this.name = "ValidationError";
     }
 }
+/**
+ * Thrown when serialising a model and parsing the result back does not
+ * reproduce the model.
+ *
+ * This means the write would have put something on disk that no longer says
+ * what the model said, so nothing is written. {@link changes} names the
+ * elements that diverged.
+ *
+ * @example
+ * ```typescript
+ * import { writeBpmn } from "@bpmnkit/core/node"
+ * import { WriteVerificationError } from "@bpmnkit/core"
+ *
+ * try {
+ *   await writeBpmn(definitions, { output: "flow.bpmn" })
+ * } catch (err) {
+ *   if (err instanceof WriteVerificationError) {
+ *     console.error("would have lost:", err.changes.removed)
+ *   }
+ * }
+ * ```
+ */
+export class WriteVerificationError extends BpmnSdkError {
+    /** What differed between the model and the model read back from the output. */
+    changes;
+    constructor(message, changes) {
+        super(message, "write-verification-error");
+        this.name = "WriteVerificationError";
+        this.changes = changes;
+    }
+}
+/**
+ * Thrown when the output file cannot be written — it already exists and
+ * `force` was not given, or the filesystem refused the write.
+ */
+export class WriteError extends BpmnSdkError {
+    constructor(message) {
+        super(message, "write-error");
+        this.name = "WriteError";
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -1,18 +1,24 @@
-export { BpmnSdkError, ParseError, ValidationError } from "./errors.js";
+export { BpmnSdkError, ParseError, ValidationError, WriteError, WriteVerificationError, } from "./errors.js";
 export type { ErrorCode } from "./errors.js";
 export { isBpmnActivity, isBpmnAdHocSubProcess, isBpmnBoundaryEvent, isBpmnBusinessRuleTask, isBpmnCallActivity, isBpmnComplexGateway, isBpmnDataObject, isBpmnDataObjectReference, isBpmnDataStoreReference, isBpmnEndEvent, isBpmnEvent, isBpmnEventBasedGateway, isBpmnEventSubProcess, isBpmnExclusiveGateway, isBpmnGateway, isBpmnInclusiveGateway, isBpmnIntermediateCatchEvent, isBpmnIntermediateThrowEvent, isBpmnManualTask, isBpmnParallelGateway, isBpmnReceiveTask, isBpmnScriptTask, isBpmnSendTask, isBpmnServiceTask, isBpmnStartEvent, isBpmnSubProcess, isBpmnTask, isBpmnTransaction, isBpmnUserTask, } from "./bpmn/type-guards.js";
 export { findElement, findElementInProcess, findProcess, findSequenceFlow, getAllElements, getElementType, getZeebeExtensions, } from "./bpmn/utils.js";
 export { Bpmn, SAMPLE_BPMN_XML } from "./bpmn/index.js";
 export { applyAutoLayout } from "./bpmn/auto-layout.js";
+export { diffSemantics, projectSemantics, semanticHash } from "./bpmn/semantic-hash.js";
+export type { JsonValue, SemanticDiff, SemanticProjection } from "./bpmn/semantic-hash.js";
+export { sha256Hex } from "./bpmn/sha256.js";
 export { checkDiCompleteness } from "./bpmn/di-check.js";
 export type { DiCompleteness } from "./bpmn/di-check.js";
 export { planeForElement, listPlaneElementIds } from "./bpmn/di-planes.js";
-export { DiagramBuilder } from "./bpmn/bpmn-builder.js";
-export type { ProcessBuilder, BranchBuilder, SubProcessContentBuilder, ServiceTaskOptions, ScriptTaskOptions, UserTaskOptions, CallActivityOptions, BusinessRuleTaskOptions, ElementOptions, GatewayOptions, MultiInstanceOptions, SubProcessOptions, StartEventOptions, IntermediateCatchEventOptions, IntermediateThrowEventOptions, EndEventOptions, BoundaryEventOptions, AdHocSubProcessOptions, } from "./bpmn/bpmn-builder.js";
+export { DiagramBuilder, ProcessBuilder } from "./bpmn/bpmn-builder.js";
+export type { BranchBuilder, BuildOptions, MessageFlowOptions, ParticipantOptions, DiagramMessageOptions, SubProcessContentBuilder, ServiceTaskOptions, ScriptTaskOptions, UserTaskOptions, CallActivityOptions, BusinessRuleTaskOptions, ElementOptions, GatewayOptions, MultiInstanceOptions, SubProcessOptions, StartEventOptions, IntermediateCatchEventOptions, IntermediateThrowEventOptions, EndEventOptions, BoundaryEventOptions, AdHocSubProcessOptions, } from "./bpmn/bpmn-builder.js";
 export type { BpmnDefinitions, BpmnProcess, BpmnFlowNode, BpmnFlowElement, BpmnSequenceFlow, BpmnBoundaryEvent, BpmnElementType, BpmnStartEvent, BpmnEndEvent, BpmnIntermediateCatchEvent, BpmnIntermediateThrowEvent, BpmnTask, BpmnServiceTask, BpmnScriptTask, BpmnUserTask, BpmnSendTask, BpmnReceiveTask, BpmnBusinessRuleTask, BpmnManualTask, BpmnCallActivity, BpmnSubProcess, BpmnAdHocSubProcess, BpmnEventSubProcess, BpmnTransaction, BpmnExclusiveGateway, BpmnParallelGateway, BpmnInclusiveGateway, BpmnEventBasedGateway, BpmnComplexGateway, BpmnCollaboration, BpmnParticipant, BpmnMessageFlow, BpmnLane, BpmnLaneSet, BpmnError, BpmnEscalation, BpmnMessage, BpmnSignal, BpmnTextAnnotation, BpmnAssociation, BpmnGroup, BpmnDataObject, BpmnDataObjectReference, BpmnDataStoreReference, BpmnConditionExpression, BpmnEventDefinition, BpmnTimerEventDefinition, BpmnErrorEventDefinition, BpmnEscalationEventDefinition, BpmnMessageEventDefinition, BpmnSignalEventDefinition, BpmnConditionalEventDefinition, BpmnLinkEventDefinition, BpmnCancelEventDefinition, BpmnTerminateEventDefinition, BpmnCompensateEventDefinition, BpmnMultiInstanceLoopCharacteristics, BpmnDiagram, BpmnDiPlane, BpmnDiShape, BpmnDiEdge, BpmnDiLabel, BpmnBounds, BpmnWaypoint, } from "./bpmn/bpmn-model.js";
 export type { RestConnectorConfig, RestAuthentication, HttpMethod, } from "./bpmn/rest-connector.js";
-export type { ZeebeExtensions, ZeebeTaskDefinition, ZeebeIoMapping, ZeebeIoMappingEntry, ZeebeTaskHeaders, ZeebeTaskHeaderEntry, ZeebeProperties, ZeebePropertyEntry, ZeebeFormDefinition, ZeebeCalledDecision, } from "./bpmn/zeebe-extensions.js";
-export { zeebeExtensionsToXmlElements } from "./bpmn/zeebe-extensions.js";
+export type { ZeebeExtensions, ZeebeTaskDefinition, ZeebeIoMapping, ZeebeIoMappingEntry, ZeebeTaskHeaders, ZeebeTaskHeaderEntry, ZeebeProperties, ZeebePropertyEntry, ZeebeFormDefinition, ZeebeCalledDecision, ZeebeAssignmentDefinition, ZeebeTaskSchedule, ZeebePriorityDefinition, ZeebeSubscription, } from "./bpmn/zeebe-extensions.js";
+export { assertZeebePlacement, bpmnElementName, ensureZeebeExtension, isZeebePlacementAllowed, ZeebePlacementError, zeebeExtensionsToXmlElements, } from "./bpmn/zeebe-extensions.js";
+export { ZEEBE_PLACEMENT } from "./bpmn/zeebe-placement.js";
+export { buildAiAgentSubProcess, AI_AGENT_JOB_WORKER_TASK_TYPE, AI_AGENT_DEFAULT_OUTPUT_ELEMENT, } from "./bpmn/agentic.js";
+export type { AiAgentOptions, AiAgentModelConfig, AiAgentToolSpec, AiAgentToolParam, AiAgentToolParamType, AiAgentBuild, } from "./bpmn/agentic.js";
 export { Dmn, layoutDmn, benchmarkDmnLayout, compactifyDmn, expandDmn } from "./dmn/index.js";
 export type { DmnBenchmarkResult, DmnElementPosition, CompactDmn, CompactDmnDecision, CompactDmnInput, CompactDmnOutput, CompactDmnRule, } from "./dmn/index.js";
 export { Form, compactifyForm, expandForm } from "./form/index.js";
@@ -33,6 +39,7 @@ export type { StoryRenderOptions } from "./bpmn/story.js";
 export { analyzeVariableFlow, extractFeelIdentifiers } from "./bpmn/optimize/variable-flow.js";
 export type { OptimizationReport, OptimizationFinding, OptimizationSeverity, OptimizationCategory, ApplyFixResult, OptimizeOptions, } from "./bpmn/optimize/types.js";
 export { layoutProcess, layoutFlowNodes } from "./layout/index.js";
+export type { LayoutEngine } from "./layout/index.js";
 export { benchmarkLayout, compareLayouts, formatBenchmarkResult, generateAutoLayout, parseReferenceLayout, } from "./layout/index.js";
 export type { BenchmarkResult, BoundingBox, ElementComparison, ElementPosition, FlowOrderViolation, } from "./layout/index.js";
 export type { Bounds, LayoutEdge, LayoutNode, LayoutResult, Waypoint } from "./layout/index.js";
@@ -40,9 +47,13 @@ export { ELEMENT_SIZES, GRID_CELL_HEIGHT, GRID_CELL_WIDTH } from "./layout/index
 export { compactify, expand } from "./bpmn/compact.js";
 export { applyOperations } from "./bpmn/operations.js";
 export type { BpmnOperation } from "./bpmn/operations.js";
+export { applyBpmnOperations, reconcileCompact, OperationError } from "./bpmn/full-operations.js";
+export type { ApplyBpmnOperationsOptions, ApplyBpmnOperationsResult, OperationProblem, } from "./bpmn/full-operations.js";
 export { buildValidationDmn, findValidationStructure, getValidationInputNames, insertValidationStructure, removeValidationStructure, validationDecisionId, } from "./bpmn/input-validation.js";
 export type { InputVariableDef, ValidationStructure, ValidationVariableType, } from "./bpmn/input-validation.js";
 export { exportSvg } from "./bpmn/svg.js";
 export type { SvgExportOptions } from "./bpmn/svg.js";
 export type { CompactDiagram, CompactElement, CompactFlow, CompactProcess, } from "./bpmn/compact.js";
+export { compilePlan, extractPlan, mergePlan, slugify, uniqueId, } from "./plan/index.js";
+export type { CompilePlanOptions, ConnectorApplyResult, ConnectorResolver, ExtractResult, PlanAgentTool, PlanAiAgentStep, PlanBranch, PlanBusinessRuleTaskStep, PlanCallActivityStep, PlanConnectorRef, PlanConnectorStep, PlanEndStep, PlanErrorBoundary, PlanGatewayStep, PlanInputVariable, PlanProblem, PlanRawStep, PlanReceiveTaskStep, PlanScenario, PlanScriptTaskStep, PlanSendTaskStep, PlanServiceTaskStep, PlanStartStep, PlanStep, PlanSubProcessStep, PlanTimerBoundary, PlanUserTaskStep, PlanWaitStep, ProcessPlan, SynthResult, UnsupportedElement, } from "./plan/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,12 +1,16 @@
-export { BpmnSdkError, ParseError, ValidationError } from "./errors.js";
+export { BpmnSdkError, ParseError, ValidationError, WriteError, WriteVerificationError, } from "./errors.js";
 export { isBpmnActivity, isBpmnAdHocSubProcess, isBpmnBoundaryEvent, isBpmnBusinessRuleTask, isBpmnCallActivity, isBpmnComplexGateway, isBpmnDataObject, isBpmnDataObjectReference, isBpmnDataStoreReference, isBpmnEndEvent, isBpmnEvent, isBpmnEventBasedGateway, isBpmnEventSubProcess, isBpmnExclusiveGateway, isBpmnGateway, isBpmnInclusiveGateway, isBpmnIntermediateCatchEvent, isBpmnIntermediateThrowEvent, isBpmnManualTask, isBpmnParallelGateway, isBpmnReceiveTask, isBpmnScriptTask, isBpmnSendTask, isBpmnServiceTask, isBpmnStartEvent, isBpmnSubProcess, isBpmnTask, isBpmnTransaction, isBpmnUserTask, } from "./bpmn/type-guards.js";
 export { findElement, findElementInProcess, findProcess, findSequenceFlow, getAllElements, getElementType, getZeebeExtensions, } from "./bpmn/utils.js";
 export { Bpmn, SAMPLE_BPMN_XML } from "./bpmn/index.js";
 export { applyAutoLayout } from "./bpmn/auto-layout.js";
+export { diffSemantics, projectSemantics, semanticHash } from "./bpmn/semantic-hash.js";
+export { sha256Hex } from "./bpmn/sha256.js";
 export { checkDiCompleteness } from "./bpmn/di-check.js";
 export { planeForElement, listPlaneElementIds } from "./bpmn/di-planes.js";
-export { DiagramBuilder } from "./bpmn/bpmn-builder.js";
-export { zeebeExtensionsToXmlElements } from "./bpmn/zeebe-extensions.js";
+export { DiagramBuilder, ProcessBuilder } from "./bpmn/bpmn-builder.js";
+export { assertZeebePlacement, bpmnElementName, ensureZeebeExtension, isZeebePlacementAllowed, ZeebePlacementError, zeebeExtensionsToXmlElements, } from "./bpmn/zeebe-extensions.js";
+export { ZEEBE_PLACEMENT } from "./bpmn/zeebe-placement.js";
+export { buildAiAgentSubProcess, AI_AGENT_JOB_WORKER_TASK_TYPE, AI_AGENT_DEFAULT_OUTPUT_ELEMENT, } from "./bpmn/agentic.js";
 export { Dmn, layoutDmn, benchmarkDmnLayout, compactifyDmn, expandDmn } from "./dmn/index.js";
 export { Form, compactifyForm, expandForm } from "./form/index.js";
 export { FormBuilder, GroupBuilder } from "./form/form-builder.js";
@@ -21,6 +25,8 @@ export { benchmarkLayout, compareLayouts, formatBenchmarkResult, generateAutoLay
 export { ELEMENT_SIZES, GRID_CELL_HEIGHT, GRID_CELL_WIDTH } from "./layout/index.js";
 export { compactify, expand } from "./bpmn/compact.js";
 export { applyOperations } from "./bpmn/operations.js";
+export { applyBpmnOperations, reconcileCompact, OperationError } from "./bpmn/full-operations.js";
 export { buildValidationDmn, findValidationStructure, getValidationInputNames, insertValidationStructure, removeValidationStructure, validationDecisionId, } from "./bpmn/input-validation.js";
 export { exportSvg } from "./bpmn/svg.js";
+export { compilePlan, extractPlan, mergePlan, slugify, uniqueId, } from "./plan/index.js";
 //# sourceMappingURL=index.js.map

package/dist/layout/annotations.js

@@ -8,6 +8,8 @@ const ELEMENT_GAP = 30; // min gap between annotation and a non-annotation shape
 const PREFERRED_OFFSET = 50; // preferred gap to associated element
 const MIN_HEIGHT = 30;
 const HORIZONTAL_SHIFTS = [0, 60, -60, 120, -120, 180, -180, 240, -240];
+/** Cost added to a candidate whose association line would cross a shape. */
+const BLOCKED_LINE_COST = 10_000;
 function computeHeight(text, width) {
     if (!text || !text.trim())
         return MIN_HEIGHT;
@@ -189,7 +191,17 @@ export function packAnnotations(process, layoutNodes) {
                         }
                     }
                 }
-                const cost = Math.hypot(candidateX - naturalX, y - naturalY);
+                // A clear box is not enough: the association line drawn back to the
+                // element must not cut through anything either.
+                const candidate = {
+                    x: candidateX,
+                    y,
+                    width: item.bounds.width,
+                    height: item.bounds.height,
+                };
+                const { pElem, pAnn } = associationWaypoints(linked.bounds, candidate);
+                const crosses = obstacles.some((sh) => sh !== linked.bounds && segmentHitsBox(pElem, pAnn, sh));
+                const cost = Math.hypot(candidateX - naturalX, y - naturalY) + (crosses ? BLOCKED_LINE_COST : 0);
                 if (cost < best.cost)
                     best = { x: candidateX, y, cost };
             }
@@ -218,6 +230,29 @@ export function packAnnotations(process, layoutNodes) {
     }
     return result;
 }
+/** Whether a straight segment passes through a box. */
+function segmentHitsBox(a, b, box) {
+    const minX = Math.min(a.x, b.x);
+    const maxX = Math.max(a.x, b.x);
+    const minY = Math.min(a.y, b.y);
+    const maxY = Math.max(a.y, b.y);
+    if (maxX <= box.x || box.x + box.width <= minX)
+        return false;
+    if (maxY <= box.y || box.y + box.height <= minY)
+        return false;
+    if (a.x === b.x || a.y === b.y)
+        return true;
+    // Diagonal: the box is hit unless all four corners fall on one side of it.
+    const side = (p) => Math.sign((b.x - a.x) * (p.y - a.y) - (b.y - a.y) * (p.x - a.x));
+    const corners = [
+        { x: box.x, y: box.y },
+        { x: box.x + box.width, y: box.y },
+        { x: box.x + box.width, y: box.y + box.height },
+        { x: box.x, y: box.y + box.height },
+    ];
+    const first = side(corners[0] ?? { x: 0, y: 0 });
+    return corners.some((corner) => side(corner) !== first);
+}
 /**
  * Edge-to-edge, clamped association waypoints between a linked element and
  * its annotation. Port of `chooseWaypoints` (tmp/01-annotation-layouting.cjs:365-389).

package/dist/layout/collaboration/alignment.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Horizontal alignment between the pools of a collaboration.
+ *
+ * Each process is laid out on its own, so two elements that exchange a message
+ * usually end up at unrelated x positions and the message has to travel sideways
+ * to reach its partner. Sliding a whole process sideways costs nothing — the
+ * pool grows with it — and a message that leaves straight down crosses far less
+ * than one that wanders across two pools first.
+ */
+/** One message flow, as the two element centres it connects. */
+export interface MessageLink {
+    fromPool: number;
+    toPool: number;
+    /** x centre of the source element within its pool's content. */
+    fromX: number;
+    /** x centre of the target element within its pool's content. */
+    toX: number;
+}
+/**
+ * Choose a horizontal offset per pool. The widest pool anchors the diagram and
+ * the rest slide to meet it, largest first, so the biggest process never moves
+ * to chase a small one. Offsets are normalised to keep every pool at or right of
+ * the origin.
+ */
+export declare function alignPools(count: number, widths: readonly number[], links: readonly MessageLink[]): number[];
+//# sourceMappingURL=alignment.d.ts.map

package/dist/layout/collaboration/alignment.js

@@ -0,0 +1,66 @@
+/**
+ * Horizontal alignment between the pools of a collaboration.
+ *
+ * Each process is laid out on its own, so two elements that exchange a message
+ * usually end up at unrelated x positions and the message has to travel sideways
+ * to reach its partner. Sliding a whole process sideways costs nothing — the
+ * pool grows with it — and a message that leaves straight down crosses far less
+ * than one that wanders across two pools first.
+ */
+/**
+ * Choose a horizontal offset per pool. The widest pool anchors the diagram and
+ * the rest slide to meet it, largest first, so the biggest process never moves
+ * to chase a small one. Offsets are normalised to keep every pool at or right of
+ * the origin.
+ */
+export function alignPools(count, widths, links) {
+    const offsets = new Array(count).fill(0);
+    if (count < 2 || links.length === 0)
+        return offsets;
+    const order = Array.from({ length: count }, (_, i) => i).sort((a, b) => (widths[b] ?? 0) - (widths[a] ?? 0) || a - b);
+    const placed = new Set();
+    const anchor = order[0];
+    if (anchor === undefined)
+        return offsets;
+    placed.add(anchor);
+    for (let i = 1; i < order.length; i++) {
+        const pool = order[i];
+        if (pool === undefined)
+            continue;
+        const connected = links.filter((link) => (link.fromPool === pool && placed.has(link.toPool)) ||
+            (link.toPool === pool && placed.has(link.fromPool)));
+        if (connected.length === 0) {
+            placed.add(pool);
+            continue;
+        }
+        // Every connected message suggests the shift that would make it vertical;
+        // staying put is always in the running.
+        const candidates = new Set([0]);
+        for (const link of connected) {
+            const mine = link.fromPool === pool ? link.fromX : link.toX;
+            const theirs = link.fromPool === pool ? link.toX : link.fromX;
+            const otherPool = link.fromPool === pool ? link.toPool : link.fromPool;
+            candidates.add(theirs + (offsets[otherPool] ?? 0) - mine);
+        }
+        let best = 0;
+        let bestCost = Number.POSITIVE_INFINITY;
+        for (const candidate of [...candidates].sort((a, b) => Math.abs(a) - Math.abs(b) || a - b)) {
+            let cost = 0;
+            for (const link of connected) {
+                const mine = link.fromPool === pool ? link.fromX : link.toX;
+                const theirs = link.fromPool === pool ? link.toX : link.fromX;
+                const otherPool = link.fromPool === pool ? link.toPool : link.fromPool;
+                cost += Math.abs(mine + candidate - (theirs + (offsets[otherPool] ?? 0)));
+            }
+            if (cost < bestCost) {
+                bestCost = cost;
+                best = candidate;
+            }
+        }
+        offsets[pool] = Math.round(best);
+        placed.add(pool);
+    }
+    const min = Math.min(...offsets);
+    return min === 0 ? offsets : offsets.map((offset) => offset - min);
+}
+//# sourceMappingURL=alignment.js.map

package/dist/layout/collaboration/ordering.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Vertical order of the pools in a collaboration.
+ *
+ * Message flows read best when the pools they connect sit next to each other,
+ * so the order is chosen to minimise how far messages travel vertically rather
+ * than left as declared. Small collaborations can afford an exhaustive search;
+ * larger ones use repeated remove-and-reinsert, which reaches the same answer on
+ * every realistic diagram and never depends on iteration order.
+ */
+/** A message-flow relationship between two pools, by index into the input order. */
+export interface PoolLink {
+    from: number;
+    to: number;
+    weight: number;
+}
+/**
+ * Order pools by their message-flow relationships. Returns indices into the
+ * input order; an input with no message flows comes back unchanged.
+ */
+export declare function orderPools(count: number, links: readonly PoolLink[]): number[];
+//# sourceMappingURL=ordering.d.ts.map