enforce mutually exclusive start events on recover

Author: paed01

AGENTS.md

@@ -6,6 +6,7 @@ This file provides guidance to coding agents (Claude Code, and any tool that rea
 
 - **TDD is the default.** Red → green → refactor: write or adjust a failing test before changing implementation. Don't delete or weaken existing assertions to land a change — extend them.
 - **Performance and coverage are the project's USP.** Avoid regressions in either. On hot paths (broker dispatch, flow traversal, activity activation, joins, multi-instance loops), prefer existing `Context` Maps/refs over rebuilt scans, and avoid per-message allocations/closures where they can be hoisted.
+- **JSDoc is concise.** Short intent descriptions are fine; never describe internal implementation.
 - Before declaring done: `npm test` (full suite + lint + `dist` rebuild). For coverage-sensitive work, also `npm run cov:html`.
 
 ## Commands
@@ -46,6 +47,8 @@ An element type like `ServiceTask` is not a class. It is a factory function that
 
 When an activity is activated, `ActivityExecution` instantiates the Behaviour and calls its `execute`. To replace an element type entirely, supply a new Behaviour — see `docs/Extend.md`.
 
+To identify an element's kind at runtime, compare its `Behaviour` (`entity.Behaviour === StartEvent`) rather than the `type` string — type strings can be customized via the `types` extension.
+
 ### `Context` and `Environment`
 
 - `src/Context.js` is a per-execution **registry and lazy factory**. It stores activities, flows, and processes in `refs` Maps and instantiates them on first access via `upsertActivity` / `upsertSequenceFlow` / `upsertProcess`. It bridges the parsed moddle context (from `bpmn-moddle` via `moddle-context-serializer`) to runtime instances and wires extensions through `ExtensionsMapper`. Contexts are cheap to clone and are isolated per execution scope.
@@ -62,10 +65,17 @@ Documented in `docs/Extend.md` and `docs/Extension.md`:
 1. **Replace a Behaviour** by passing `{ types: { 'bpmn:StartEvent': MyStartEvent } }` to `Definition`. Use when you need full control over an element's execution.
 2. **Non-invasive extension hooks** via `{ extensions: { myExt(activity, context) { … } } }`. Each extension runs once per activity after instantiation and typically attaches listeners or publishes format messages — used for cross-cutting concerns (forms, logging, output capture).
 
+### State & behavioral invariants
+
+- **No flow discards.** Outbound sequence flows are never discarded; flow and activity `discarded` counters stay `0`. There is no `skipDiscard` setting. Parallel joins rely on cached gateway peers, not on discarded flows.
+- **Multiple start events are mutually exclusive entry points.** The first start event to fire discards the others still armed, so two start branches can never both run.
+- **`stateVersion`.** `Definition.getState()` stamps `stateVersion` (the package major, hardcoded in `src/constants.js`); recovering an older major triggers migrations (e.g. start event reconciliation on resume). Unstamped legacy states are treated as version `0`. Bump the constant on each major release.
+
 ## Testing patterns
 
 - Framework: mocha + `mocha-cakes-2` BDD UI. `Feature` / `Scenario` / `Given` / `When` / `Then` / `And` / `But` are globals in test files (declared in `eslint.config.js`). Chai `expect` is registered globally via `test/helpers/setup.js`.
 - Layout: scenario-style coverage in `test/feature/*.js`; unit tests mirror the `src/` directory tree (`test/activity`, `test/process`, `test/gateways`, `test/tasks`, `test/eventDefinitions`, `test/flows`, …).
 - BPMN sources: raw XML templates in `test/helpers/factory.js` (helpers like `factory.valid()`, `factory.userTask()`, `factory.resource('name')`) plus `.bpmn` files under `test/resources/`.
 - Primary helper: `test/helpers/testHelpers.js` — `context(source, options)` parses BPMN via `bpmn-moddle`, serializes via `moddle-context-serializer`, and returns a runtime `Context`. Also exposes `Logger`, `emptyContext`, and `AssertMessage` for asserting broker message sequences.
 - `test/helpers/JavaScripts.js` is a mock Scripts engine for isolating ScriptTask tests.
+- Don't assert on logging — captured `logger.warn`/`debug` output is not part of the tested contract.

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v18.0.1 - 2026-06-13
+
+### Fixes
+
+- enforce mutually exclusive start events on recover: a recovered state where one entry point already won, or a legacy state serialized before the `isStartEvent` flag existed, now correctly discards the start events still left armed instead of resuming them as live entry points
+
+### Additions
+
+- serialized definition state is stamped with a `stateVersion` tracking the package major; recovering an older major (legacy unstamped states are treated as version `0`) triggers migrations such as the start event reconciliation above
+
 ## v18.0.0 - 2026-06-11
 
 Refactor parallel converging and forking gateways, and treat multiple start events as mutually exclusive entry points. As a result of the parallel gateway keeping track of peers there is no need for discarding a sequence flows.

dist/constants.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.K_TARGETS = exports.K_STOPPED = exports.K_STATUS = exports.K_STATE_MESSAGE = exports.K_REFERENCE_INFO = exports.K_REFERENCE_ELEMENT = exports.K_MESSAGE_Q = exports.K_MESSAGE_HANDLERS = exports.K_EXTENSIONS = exports.K_EXECUTION = exports.K_EXECUTE_MESSAGE = exports.K_COUNTERS = exports.K_CONSUMING = exports.K_COMPLETED = exports.K_ACTIVATED = void 0;
+exports.STATE_VERSION = exports.K_TARGETS = exports.K_STOPPED = exports.K_STATUS = exports.K_STATE_MESSAGE = exports.K_REFERENCE_INFO = exports.K_REFERENCE_ELEMENT = exports.K_MESSAGE_Q = exports.K_MESSAGE_HANDLERS = exports.K_EXTENSIONS = exports.K_EXECUTION = exports.K_EXECUTE_MESSAGE = exports.K_COUNTERS = exports.K_CONSUMING = exports.K_COMPLETED = exports.K_ACTIVATED = void 0;
 const K_ACTIVATED = exports.K_ACTIVATED = Symbol.for('activated');
 const K_COMPLETED = exports.K_COMPLETED = Symbol.for('completed');
 const K_CONSUMING = exports.K_CONSUMING = Symbol.for('consuming');
@@ -18,4 +18,10 @@ const K_REFERENCE_INFO = exports.K_REFERENCE_INFO = Symbol.for('referenceInfo');
 const K_STATE_MESSAGE = exports.K_STATE_MESSAGE = Symbol.for('stateMessage');
 const K_STATUS = exports.K_STATUS = Symbol.for('status');
 const K_STOPPED = exports.K_STOPPED = Symbol.for('stopped');
-const K_TARGETS = exports.K_TARGETS = Symbol.for('targets');
+const K_TARGETS = exports.K_TARGETS = Symbol.for('targets');
+
+/**
+ * State version. Tracks the package major; bump on each major. Recovering an older major triggers
+ * migrations. Unstamped legacy states are treated as version 0.
+ */
+const STATE_VERSION = exports.STATE_VERSION = 18;

dist/definition/Definition.js

@@ -176,6 +176,7 @@ Definition.prototype.resume = function resume(callback) {
  */
 Definition.prototype.getState = function getState() {
   return this._createMessage({
+    stateVersion: _constants.STATE_VERSION,
     status: this.status,
     stopped: this.stopped,
     counters: this.counters,
@@ -194,6 +195,10 @@ Definition.prototype.getState = function getState() {
 Definition.prototype.recover = function recover(state) {
   if (this.isRunning) throw new Error('cannot recover running definition');
   if (!state) return this;
+  const recoveredVersion = state.stateVersion || 0;
+  if (recoveredVersion !== _constants.STATE_VERSION) {
+    this.logger.debug(`<${this.id}> recover state version ${recoveredVersion} into runtime state version ${_constants.STATE_VERSION}`);
+  }
   this[_constants.K_STOPPED] = !!state.stopped;
   this[_constants.K_STATUS] = state.status;
   const exec = this[_constants.K_EXECUTION];
@@ -206,7 +211,7 @@ Definition.prototype.recover = function recover(state) {
   }
   this.environment.recover(state.environment);
   if (state.execution) {
-    exec.set('execution', new _DefinitionExecution.DefinitionExecution(this, this.context).recover(state.execution));
+    exec.set('execution', new _DefinitionExecution.DefinitionExecution(this, this.context).recover(state.execution, recoveredVersion));
   }
   this.broker.recover(state.broker);
   return this;

dist/definition/DefinitionExecution.js

@@ -186,9 +186,10 @@ DefinitionExecution.prototype.resume = function resume() {
 /**
  * Restore execution state captured by getState. Reinstates running processes from the snapshot.
  * @param {import('#types').DefinitionExecutionState} [state]
+ * @param {number} [recoveredVersion] State version
  * @returns {this}
  */
-DefinitionExecution.prototype.recover = function recover(state) {
+DefinitionExecution.prototype.recover = function recover(state, recoveredVersion) {
   if (!state) return this;
   this.executionId = state.executionId;
   this[_constants.K_STOPPED] = state.stopped;
@@ -208,7 +209,7 @@ DefinitionExecution.prototype.recover = function recover(state) {
     }
     if (!bp) continue;
     ids.add(bpid);
-    bp.recover(bpState);
+    bp.recover(bpState, recoveredVersion);
     running.add(bp);
   }
   return this;

dist/gateways/ParallelGateway.js

@@ -37,7 +37,8 @@ function ParallelGateway(activityDef, context) {
   const cachedPeers = context.getShakenPeers(id);
   if (cachedPeers) {
     for (const [flowId, sourceIds] of cachedPeers) {
-      const peer = peers.get(flowId);
+      let peer = peers.get(flowId);
+      if (!peer) peers.set(flowId, peer = new Set());
       for (const sourceId of sourceIds) peer.add(sourceId);
     }
     activity[K_PEERS_DISCOVERED] = true;

dist/process/Process.js

@@ -191,10 +191,11 @@ Process.prototype.getState = function getState() {
 /**
  * Restore process state captured by getState.
  * @param {import('#types').ProcessState} [state]
+ * @param {number} [recoveredVersion] State version
  * @returns {this}
  * @throws {Error} when called on a running process
  */
-Process.prototype.recover = function recover(state) {
+Process.prototype.recover = function recover(state, recoveredVersion) {
   if (this.isRunning) throw new Error(`cannot recover running process <${this.id}>`);
   if (!state) return this;
   this[_constants.K_STOPPED] = !!state.stopped;
@@ -207,7 +208,7 @@ Process.prototype.recover = function recover(state) {
   };
   this.environment.recover(state.environment);
   if (state.execution) {
-    exec.set('execution', new _ProcessExecution.ProcessExecution(this, this.context).recover(state.execution));
+    exec.set('execution', new _ProcessExecution.ProcessExecution(this, this.context).recover(state.execution, recoveredVersion));
   }
   this.broker.recover(state.broker);
   return this;

dist/process/ProcessExecution.js

@@ -14,6 +14,7 @@ const K_ELEMENTS = Symbol.for('elements');
 const K_PARENT = Symbol.for('parent');
 const K_TRACKER = Symbol.for('activity tracker');
 const K_PEERS_DISCOVERED = Symbol.for('peers discovered');
+const K_RECOVERED_VERSION = Symbol.for('recovered version');
 
 /**
  * Drives the execution of a single process or sub-process: activates children, routes activity
@@ -163,6 +164,8 @@ ProcessExecution.prototype.resume = function resume() {
     activity.resume();
   }
   if (this[_constants.K_COMPLETED]) return;
+  this._reconcileStartEvents();
+  if (this[_constants.K_COMPLETED]) return;
   if (!postponed.size && status === 'executing') return this._complete('completed');
 };
 
@@ -208,11 +211,13 @@ ProcessExecution.prototype.getState = function getState() {
 /**
  * Restore execution state captured by getState.
  * @param {import('#types').ProcessExecutionState} [state]
+ * @param {number} [recoveredVersion] State version
  * @returns {this}
  */
-ProcessExecution.prototype.recover = function recover(state) {
+ProcessExecution.prototype.recover = function recover(state, recoveredVersion) {
   if (!state) return this;
   this.executionId = state.executionId;
+  this[K_RECOVERED_VERSION] = recoveredVersion;
   this[_constants.K_STOPPED] = state.stopped;
   this[_constants.K_COMPLETED] = state.completed;
   this[_constants.K_STATUS] = state.status;
@@ -740,16 +745,9 @@ ProcessExecution.prototype._onChildMessage = function onChildMessage(routingKey,
       }
     case 'activity.end':
       {
-        if (!content.isStartEvent) break;
-        const elements = this[K_ELEMENTS];
-        if (elements.startEventCount <= 1) break;
-        const startPeers = new Set();
-        for (const msg of elements.postponed) {
-          const peerId = msg.content.id;
-          if (peerId !== content.id && msg.content.isStartEvent) startPeers.add(msg);
-        }
-        elements.startEventCount = 0;
-        for (const msg of startPeers) this._getChildApi(msg).discard();
+        if (!(content.isStartEvent || this.getActivityById(content.id)?.isStartEvent)) break;
+        if (this[K_ELEMENTS].startEventCount <= 1) break;
+        this._discardArmedStartEvents(content.id);
         break;
       }
     case 'activity.error':
@@ -1041,6 +1039,42 @@ ProcessExecution.prototype._getChildById = function getChildById(childId) {
   return this.getActivityById(childId) || this._getFlowById(childId);
 };
 
+/**
+ * Discard the other armed start events once one mutually exclusive entry point wins.
+ * Resolves the start-event flag from the live activity so recovered pre-flag state is handled.
+ * @internal
+ */
+ProcessExecution.prototype._discardArmedStartEvents = function discardArmedStartEvents(winnerId) {
+  const elements = this[K_ELEMENTS];
+  const startPeers = [];
+  for (const msg of elements.postponed) {
+    const peerId = msg.content.id;
+    if (peerId === winnerId) continue;
+    if (this.getActivityById(peerId)?.isStartEvent) startPeers.push(msg);
+  }
+  if (!startPeers.length) return;
+  elements.startEventCount = 0;
+  for (const msg of startPeers) this._getChildApi(msg).discard();
+};
+
+/**
+ * On resume of a state from an older major, discard start events left armed when another entry
+ * point already won before recovery. The winning start event's `activity.end` cannot replay, so
+ * the live discard trigger never fires.
+ * @internal
+ */
+ProcessExecution.prototype._reconcileStartEvents = function reconcileStartEvents() {
+  const elements = this[K_ELEMENTS];
+  if (elements.startEventCount <= 1) return;
+  if (!(this[K_RECOVERED_VERSION] < _constants.STATE_VERSION)) return;
+  for (const child of elements.children) {
+    if (child.isStartEvent && child.counters.taken) {
+      this._discardArmedStartEvents();
+      return;
+    }
+  }
+};
+
 /** @internal */
 ProcessExecution.prototype._getChildApi = function getChildApi(message) {
   const content = message.content;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bpmn-elements",
-  "version": "18.0.0",
+  "version": "18.0.1",
   "description": "Executable workflow elements based on BPMN 2.0",
   "type": "module",
   "main": "./dist/index.js",

src/constants.js

@@ -13,3 +13,9 @@ export const K_STATE_MESSAGE = Symbol.for('stateMessage');
 export const K_STATUS = Symbol.for('status');
 export const K_STOPPED = Symbol.for('stopped');
 export const K_TARGETS = Symbol.for('targets');
+
+/**
+ * State version. Tracks the package major; bump on each major. Recovering an older major triggers
+ * migrations. Unstamped legacy states are treated as version 0.
+ */
+export const STATE_VERSION = 18;