bpmn-elements 18.0.0 → 18.0.1

package/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;

package/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;

package/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;

package/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;

package/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/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",

package/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;

package/src/definition/Definition.js

@@ -13,6 +13,7 @@ import {
   K_STATE_MESSAGE,
   K_STATUS,
   K_STOPPED,
+  STATE_VERSION,
 } from '../constants.js';
 
 /**
@@ -181,6 +182,7 @@ Definition.prototype.resume = function resume(callback) {
  */
 Definition.prototype.getState = function getState() {
   return this._createMessage({
+    stateVersion: STATE_VERSION,
     status: this.status,
     stopped: this.stopped,
     counters: this.counters,
@@ -200,6 +202,11 @@ 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 !== STATE_VERSION) {
+    this.logger.debug(`<${this.id}> recover state version ${recoveredVersion} into runtime state version ${STATE_VERSION}`);
+  }
+
   this[K_STOPPED] = !!state.stopped;
   this[K_STATUS] = state.status;
 
@@ -212,7 +219,7 @@ Definition.prototype.recover = function recover(state) {
   this.environment.recover(state.environment);
 
   if (state.execution) {
-    exec.set('execution', new DefinitionExecution(this, this.context).recover(state.execution));
+    exec.set('execution', new DefinitionExecution(this, this.context).recover(state.execution, recoveredVersion));
   }
 
   this.broker.recover(state.broker);

package/src/definition/DefinitionExecution.js

@@ -189,9 +189,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;
 
@@ -216,7 +217,7 @@ DefinitionExecution.prototype.recover = function recover(state) {
     if (!bp) continue;
 
     ids.add(bpid);
-    bp.recover(bpState);
+    bp.recover(bpState, recoveredVersion);
     running.add(bp);
   }
 

package/src/process/Process.js

@@ -190,10 +190,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;
 
@@ -205,7 +206,7 @@ Process.prototype.recover = function recover(state) {
   this.environment.recover(state.environment);
 
   if (state.execution) {
-    exec.set('execution', new ProcessExecution(this, this.context).recover(state.execution));
+    exec.set('execution', new ProcessExecution(this, this.context).recover(state.execution, recoveredVersion));
   }
 
   this.broker.recover(state.broker);

package/src/process/ProcessExecution.js

@@ -2,13 +2,14 @@ import { ProcessApi } from '../Api.js';
 import { cloneContent, cloneMessage, pushParent } from '../messageHelper.js';
 import { getUniqueId } from '../shared.js';
 import { ActivityTracker } from '../Tracker.js';
-import { K_ACTIVATED, K_COMPLETED, K_EXECUTE_MESSAGE, K_MESSAGE_HANDLERS, K_STATUS, K_STOPPED } from '../constants.js';
+import { K_ACTIVATED, K_COMPLETED, K_EXECUTE_MESSAGE, K_MESSAGE_HANDLERS, K_STATUS, K_STOPPED, STATE_VERSION } from '../constants.js';
 
 const K_ACTIVITY_Q = Symbol.for('activityQ');
 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
@@ -166,6 +167,10 @@ ProcessExecution.prototype.resume = function resume() {
 
   if (this[K_COMPLETED]) return;
 
+  this._reconcileStartEvents();
+
+  if (this[K_COMPLETED]) return;
+
   if (!postponed.size && status === 'executing') return this._complete('completed');
 };
 
@@ -204,11 +209,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[K_STOPPED] = state.stopped;
   this[K_COMPLETED] = state.completed;
@@ -738,17 +745,9 @@ ProcessExecution.prototype._onChildMessage = function onChildMessage(routingKey,
       break;
     }
     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': {
@@ -1055,6 +1054,43 @@ 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] < 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/types/index.d.ts

@@ -407,6 +407,8 @@ declare module 'bpmn-elements' {
   }
 
   export interface DefinitionState extends ElementState {
+	/** State version. Absent on states saved before versioning. */
+	stateVersion?: number;
 	status: DefinitionStatus;
 	stopped: boolean;
 	executionId?: string;
@@ -1046,8 +1048,9 @@ declare module 'bpmn-elements' {
 		resume(): number | undefined;
 		/**
 		 * Restore execution state captured by getState. Reinstates running processes from the snapshot.
+		 * @param recoveredVersion State version
 		 * */
-		recover(state?: DefinitionExecutionState): this;
+		recover(state?: DefinitionExecutionState, recoveredVersion?: number): this;
 		/**
 		 * Stop the running execution via the api.
 		 */
@@ -1472,9 +1475,10 @@ declare module 'bpmn-elements' {
 		getState(): ProcessState;
 		/**
 		 * Restore process state captured by getState.
+		 * @param recoveredVersion State version
 		 * @throws {Error} when called on a running process
 		 */
-		recover(state?: ProcessState): this;
+		recover(state?: ProcessState, recoveredVersion?: number): this;
 		/**
 		 * Walk activity graph from the given start id, or every start activity when omitted.
 		 * */
@@ -1660,8 +1664,9 @@ declare module 'bpmn-elements' {
 		getState(): ProcessExecutionState;
 		/**
 		 * Restore execution state captured by getState.
+		 * @param recoveredVersion State version
 		 * */
-		recover(state?: ProcessExecutionState): this;
+		recover(state?: ProcessExecutionState, recoveredVersion?: number): this;
 		/**
 		 * Walk activity graph from the given start id, or every start activity when omitted.
 		 * */

package/types/interfaces.d.ts

@@ -505,6 +505,8 @@ export interface DefinitionExecutionState {
 }
 
 export interface DefinitionState extends ElementState {
+  /** State version. Absent on states saved before versioning. */
+  stateVersion?: number;
   status: DefinitionStatus;
   stopped: boolean;
   executionId?: string;