@bpmnkit/core 0.1.2 → 0.2.0

package/README.md

@@ -9,7 +9,7 @@
   [![ai-assisted](https://img.shields.io/badge/AI--assisted-claude-8b5cf6?style=flat-square)](https://github.com/bpmnkit/monorepo)
   [![experimental](https://img.shields.io/badge/status-experimental-f59e0b?style=flat-square)](https://github.com/bpmnkit/monorepo)
 
-  [Website](https://bpmnkit.com) · [Documentation](https://docs.bpmnkit.com) · [GitHub](https://github.com/bpmnkit/monorepo) · [Changelog](https://github.com/bpmnkit/monorepo/blob/main/packages/core/CHANGELOG.md)
+  [Website](https://bpmnkit.com) · [Documentation](https://bpmnkit.com/docs) · [GitHub](https://github.com/bpmnkit/monorepo) · [Changelog](https://github.com/bpmnkit/monorepo/blob/main/packages/core/CHANGELOG.md)
 </div>
 
 ---
@@ -139,6 +139,35 @@ const outXml = Bpmn.export(restored)
 | `Bpmn.makeEmpty(processId?, name?)` | Minimal BPMN XML with one start event |
 | `Bpmn.SAMPLE_XML` | 3-node sample diagram string |
 
+### Semantics
+
+| Export | Description |
+|--------|-------------|
+| `semanticHash(defs)` | SHA-256 of the model, excluding the diagram. Unchanged by layout |
+| `projectSemantics(defs)` | The canonical, presentation-free projection the hash covers |
+| `diffSemantics(a, b)` | What changed between two models, keyed by element id |
+
+### Editing
+
+| Export | Description |
+|--------|-------------|
+| `applyBpmnOperations(defs, ops)` | Apply edit operations to the full model. Strict: unresolved ids throw |
+| `reconcileCompact(defs, compact)` | Apply a compact diagram as changes, keeping what compact cannot carry |
+| `compactify(defs)` | Read-only token-efficient view for LLM prompts. Lossy — not an edit path |
+
+### Writing files (`@bpmnkit/core/node`)
+
+| Export | Description |
+|--------|-------------|
+| `writeBpmn(defs, opts)` | Serialize, read back, verify the model survived, then write atomically |
+
+```typescript
+import { writeBpmn } from "@bpmnkit/core/node"
+
+// Refuses rather than overwrite; pass force: true to replace.
+const { semanticHash, changes } = await writeBpmn(defs, { output: "flow.bpmn" })
+```
+
 ### DMN
 
 | Export | Description |

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

@@ -149,6 +149,52 @@ export interface GatewayOptions extends ElementOptions {
     /** ID of the default sequence flow (set manually; prefer branch().defaultFlow()). */
     defaultFlow?: string;
 }
+/** Options for {@link ProcessBuilder.build}. */
+export interface BuildOptions {
+    /**
+     * Refuse to infer join gateways, so converging branches must be declared.
+     *
+     * Generated code should set this: the builder's inference is a help to someone
+     * reading the chain they just wrote, and a silent topology change to a model
+     * that cannot see what it did not emit.
+     */
+    explicitJoins?: boolean;
+    /**
+     * The former name for {@link BuildOptions.explicitJoins}, still honoured.
+     *
+     * Renamed because "strict" says nothing about what it is strict *about*, and
+     * because `applyBpmnOperations` takes a `strict` that means something else
+     * entirely — whether to throw or report problems.
+     *
+     * @deprecated Use `explicitJoins`.
+     */
+    strict?: boolean;
+}
+/** Options for a collaboration participant (a pool). */
+export interface ParticipantOptions {
+    /** Pool label. */
+    name?: string;
+    /** Id of the process this pool executes. Omit for a black box. */
+    processId?: string;
+}
+/** Options for a root-level message declared on a diagram. */
+export interface DiagramMessageOptions {
+    /** Message name, which is what Camunda 8 publishes against. */
+    name?: string;
+    /** FEEL expression Camunda 8 correlates published messages on (`zeebe:subscription`). */
+    correlationKey?: string;
+}
+/** Options for a message flow between two pools. */
+export interface MessageFlowOptions {
+    /** Id of the participant, or of a flow node inside one, the message leaves. */
+    source: string;
+    /** Id of the participant, or of a flow node inside one, the message reaches. */
+    target: string;
+    /** Flow label. */
+    name?: string;
+    /** Id of a message declared with `.message()`. */
+    messageRef?: string;
+}
 /** Options for an intermediate catch event. */
 export interface IntermediateCatchEventOptions extends ElementOptions {
     /** Timer duration (ISO 8601) — creates a timer catch event. */
@@ -288,6 +334,8 @@ export interface AdHocSubProcessOptions extends ElementOptions {
 export declare class BranchBuilder {
     /** @internal */
     readonly _elements: BpmnFlowElement[];
+    /** Ids in `_elements`, for O(1) duplicate checks. */
+    private readonly _ids;
     /** @internal */
     readonly _flows: BpmnSequenceFlow[];
     /** @internal */
@@ -387,6 +435,8 @@ export declare class BranchBuilder {
 export declare class SubProcessContentBuilder {
     /** @internal */
     readonly _elements: BpmnFlowElement[];
+    /** Ids in `_elements`, for O(1) duplicate checks. */
+    private readonly _ids;
     /** @internal */
     readonly _flows: BpmnSequenceFlow[];
     /** @internal */
@@ -464,8 +514,12 @@ export declare class ProcessBuilder {
     private readonly processId;
     private processName?;
     private _isExecutable;
+    /** Whether `executable()` was called, so continue-mode leaves it alone if not. */
+    private _executableSet;
     private _versionTag?;
     private readonly flowElements;
+    /** Ids in `flowElements`, for O(1) duplicate and existence checks. */
+    private readonly elementIds;
     private readonly sequenceFlows;
     private readonly rootErrors;
     private readonly rootMessages;
@@ -481,7 +535,69 @@ export declare class ProcessBuilder {
     private _executionPlatformVersion;
     private _serviceTaskDefaults;
     private _savedMainFlowId;
+    /** Set by {@link ProcessBuilder.from}; makes `build()` update rather than generate. */
+    private _source?;
+    /** Pre-existing flow endpoints, so `build()` can prove it did not rewire them. */
+    private _sourceFlowTargets;
+    /** An `insertAfter` flow waiting to be reattached to what gets built next. */
+    private _pendingSpliceFlowId;
+    /** Flows the caller deliberately spliced, exempt from the rewiring guard. */
+    private readonly _splicedFlowIds;
     constructor(processId: string);
+    /**
+     * 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: BpmnDefinitions, processId: string): ProcessBuilder;
+    /**
+     * 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: string): 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: string): this;
+    /** Points the cursor at an existing node and forgets any branch state. */
+    private moveCursor;
+    /**
+     * 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.
+     */
+    private resolvePendingSplice;
     /** Enable auto-layout: `build()` will run the layout engine and populate diagram interchange data. */
     withAutoLayout(): this;
     /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.9.0"`. */
@@ -604,10 +720,50 @@ export declare 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?: {
-        strict?: boolean;
-    }): BpmnDefinitions;
+    build(options?: BuildOptions): BpmnDefinitions;
+    /**
+     * 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.
+     */
+    private buildOntoSource;
+    /**
+     * 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.
+     */
+    private assertSourceTopologyIntact;
     private validate;
     private addFlowElement;
 }
@@ -620,11 +776,61 @@ export declare class DiagramBuilder {
     private readonly _processes;
     private readonly _errors;
     private readonly _messages;
+    private readonly _participants;
+    private readonly _messageFlows;
+    private _collaborationId;
     private _executionPlatformVersion;
     constructor(id: string);
     /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.9.0"`. */
     executionPlatformVersion(version: string): this;
     process(id: string, callback: (b: ProcessBuilder) => void): this;
+    /** Renames the collaboration element. Defaults to `"Collaboration_1"`. */
+    collaborationId(id: string): 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: string, options?: ParticipantOptions): 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: string, options?: DiagramMessageOptions): 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: string, options: MessageFlowOptions): 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.
+     */
+    private collaborationProblems;
+    /** Maps every participant id and every flow node id to its owning participant. */
+    private participantIndex;
     build(): BpmnDefinitions;
+    /**
+     * 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.
+     */
+    private buildCollaborations;
 }
 //# sourceMappingURL=bpmn-builder.d.ts.map