bpmn-elements 18.0.0 → 18.0.2

package/dist/activity/Activity.js

@@ -97,8 +97,9 @@ function Activity(Behaviour, activityDef, context) {
     outboundSequenceFlows,
     outboundEvaluator: new _outboundEvaluator.OutboundEvaluator(this, outboundSequenceFlows)
   };
+  const isThrowingLink = activityDef.isThrowing && activityDef.linkNames?.length;
   this[K_FLAGS] = {
-    isEnd: !outboundSequenceFlows.length,
+    isEnd: !outboundSequenceFlows.length && !isThrowingLink,
     isStart: !hasInboundTrigger && !behaviour.triggeredByEvent && !activityDef.isCatching,
     isSubProcess: activityDef.isSubProcess,
     isMultiInstance: !!behaviour.loopCharacteristics,
@@ -268,7 +269,7 @@ Object.defineProperties(Activity.prototype, {
   },
   initialized: {
     get() {
-      return !!this[K_EXEC]?.get('initExecutionId');
+      return this[K_EXEC].get('initialized') > 0;
     }
   }
 });
@@ -280,7 +281,23 @@ Object.defineProperties(Activity.prototype, {
 Activity.prototype.activate = function activate() {
   if (this[_constants.K_ACTIVATED]) return;
   this[_constants.K_ACTIVATED] = true;
-  return this.addInboundListeners() && this._consumeInbound();
+  this.addInboundListeners();
+  return this.consumeInbound();
+};
+
+/**
+ * Assert the inbound queue consumer when the activity has a trigger or is initialized.
+ * Idempotent: asserting the consumer again while one is active is a no-op.
+ * @returns {void}
+ */
+Activity.prototype.consumeInbound = function consumeInbound() {
+  if (!this[_constants.K_ACTIVATED]) return;
+  if (this.status) return;
+  if (!this._getInboundTriggers().length && !this.initialized) return;
+  const onInbound = this[_constants.K_MESSAGE_HANDLERS].onInbound;
+  return this.broker.getQueue('inbound-q').assertConsumer(onInbound, {
+    consumerTag: '_run-on-inbound'
+  });
 };
 
 /** @internal */
@@ -326,17 +343,28 @@ Activity.prototype.deactivate = function deactivate() {
 /**
  * Initialise activity executionId and emit init event without starting the run.
  * @param {Record<string, any>} [initContent] Optional content merged into the init message
+ * @param {import('smqp').MessageProperties} [properties] Optional message properties merged into the init message properties
  */
-Activity.prototype.init = function init(initContent) {
+Activity.prototype.init = function init(initContent, properties) {
   const id = this.id;
   const exec = this[K_EXEC];
-  const executionId = exec.has('initExecutionId') ? exec.get('initExecutionId') : (0, _shared.getUniqueId)(id);
-  exec.set('initExecutionId', executionId);
+  exec.set('initialized', (exec.get('initialized') || 0) + 1);
+  const executionId = (0, _shared.getUniqueId)(id);
   this.logger.debug(`<${id}> initialized with executionId <${executionId}>`);
   this._publishEvent('init', this._createMessage({
     ...initContent,
     executionId
   }));
+  this.broker.getQueue('inbound-q').queueMessage({
+    routingKey: 'activity.init'
+  }, {
+    ...initContent,
+    id,
+    executionId
+  }, {
+    persistent: false,
+    ...properties
+  });
 };
 
 /**
@@ -347,13 +375,15 @@ Activity.prototype.init = function init(initContent) {
 Activity.prototype.run = function run(runContent) {
   const id = this.id;
   if (this.isRunning) throw new Error(`activity <${id}> is already running`);
-  const exec = this[K_EXEC];
-  const executionId = exec.get('initExecutionId') || (0, _shared.getUniqueId)(id);
-  exec.set('executionId', executionId);
-  exec.delete('initExecutionId');
+  const {
+    initExecutionId,
+    ...runMessage
+  } = runContent || {};
+  const executionId = runMessage?.id === id && initExecutionId ? initExecutionId : (0, _shared.getUniqueId)(id);
+  this[K_EXEC].set('executionId', executionId);
   this._consumeApi();
   const content = this._createMessage({
-    ...runContent,
+    ...runMessage,
     executionId
   });
   const broker = this.broker;
@@ -558,10 +588,8 @@ Activity.prototype.getActivityById = function getActivityById(elementId) {
 
 /** @internal */
 Activity.prototype._runDiscard = function runDiscard(discardContent) {
-  const exec = this[K_EXEC];
-  const executionId = exec.get('initExecutionId') || (0, _shared.getUniqueId)(this.id);
-  exec.set('executionId', executionId);
-  exec.delete('initExecutionId');
+  const executionId = (0, _shared.getUniqueId)(this.id);
+  this[K_EXEC].set('executionId', executionId);
   this._consumeApi();
   const content = this._createMessage({
     ...discardContent,
@@ -613,7 +641,7 @@ Activity.prototype._onShakeMessage = function _onShakeMessage(sourceMessage) {
       id: this.id,
       type: this.type
     });
-    return this.broker.publish('event', 'activity.shake.join', message.content, {
+    return this.broker.publish('event', 'activity.shake.converge', message.content, {
       persistent: false,
       type: 'shake'
     });
@@ -674,43 +702,38 @@ Activity.prototype._shakeOutbound = function shakeOutbound(sourceMessage) {
   for (const t of targets.values()) t.shake(message);
 };
 
-/** @internal */
-Activity.prototype._consumeInbound = function consumeInbound() {
-  if (!this[_constants.K_ACTIVATED]) return;
-  if (this.status || !this._getInboundTriggers().length) return;
-  const inboundQ = this.broker.getQueue('inbound-q');
-  const onInbound = this[_constants.K_MESSAGE_HANDLERS].onInbound;
-  return inboundQ.assertConsumer(onInbound, {
-    consumerTag: '_run-on-inbound'
-  });
-};
-
 /** @internal */
 Activity.prototype._onInbound = function onInbound(routingKey, message) {
   message.ack();
   const broker = this.broker;
   broker.cancel('_run-on-inbound');
   const content = message.content;
-  const inbound = [(0, _messageHelper.cloneContent)(content)];
   switch (routingKey) {
-    case 'activity.relink':
-      if (content.executionId) this[K_EXEC].set('initExecutionId', content.executionId);
-      return this.run({
-        message: content.message,
-        inbound
-      });
+    case 'activity.init':
+      {
+        const exec = this[K_EXEC];
+        exec.set('initialized', (exec.get('initialized') || 0) - 1);
+        return this.run({
+          initExecutionId: content.executionId,
+          id: content.id,
+          message: content.message,
+          ...(content.inbound?.length && {
+            inbound: content.inbound
+          })
+        });
+      }
     case 'association.take':
     case 'flow.take':
     case 'activity.restart':
     case 'activity.enter':
       return this.run({
         message: content.message,
-        inbound
+        inbound: [(0, _messageHelper.cloneContent)(content)]
       });
     case 'activity.discard':
       {
         return this._runDiscard({
-          inbound
+          inbound: [(0, _messageHelper.cloneContent)(content)]
         });
       }
   }
@@ -740,26 +763,9 @@ Activity.prototype._onInboundEvent = function onInboundEvent(routingKey, message
       {
         const linkName = content.message?.linkName;
         if (!this[K_FLAGS].linkNames?.includes(linkName)) break;
-        const executionId = (0, _shared.getUniqueId)(this.id);
-        this.broker.publish('event', 'activity.enter', (0, _messageHelper.cloneContent)(content, {
-          id: this.id,
-          type: this.type,
-          executionId,
-          state: 'enter',
-          message: {
-            ...content.message
-          }
-        }));
-        inboundQ.queueMessage({
-          routingKey: 'activity.relink'
-        }, (0, _messageHelper.cloneContent)(content, {
-          id: this.id,
-          executionId,
-          message: {
-            ...content.message
-          }
-        }), properties);
-        return;
+        return this.init({
+          inbound: [(0, _messageHelper.cloneContent)(content)]
+        });
       }
     case 'association.take':
     case 'flow.take':
@@ -942,7 +948,7 @@ Activity.prototype._continueRunMessage = function continueRunMessage(routingKey,
     case 'run.next':
       message.ack();
       this._pauseRunQ();
-      return this._consumeInbound();
+      return this.consumeInbound();
   }
   if (!step) message.ack();
 };

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/events/BoundaryEvent.js

@@ -44,9 +44,9 @@ Object.defineProperty(BoundaryEventBehaviour.prototype, 'executionId', {
   }
 });
 Object.defineProperty(BoundaryEventBehaviour.prototype, 'cancelActivity', {
+  /** @returns {boolean} */
   get() {
-    const behaviour = this.activity.behaviour || {};
-    return 'cancelActivity' in behaviour ? behaviour.cancelActivity : true;
+    return this.activity.behaviour?.cancelActivity ?? true;
   }
 });
 

package/dist/gateways/ParallelGateway.js

@@ -76,11 +76,15 @@ function ParallelGatewayBehaviour(activity) {
   this.type = activity.type;
   this.activity = activity;
   this.broker = activity.broker;
+  /**
+   * Inbound taken sequence flow sequences
+   * @type {Set<import('#types').ElementMessageContent}
+   */
   this.inbound = new Set();
-  this.isConverging = true;
   this[_constants.K_EXECUTE_MESSAGE] = undefined;
 }
 Object.defineProperty(ParallelGatewayBehaviour.prototype, 'executionId', {
+  /** @returns {string | undefined} */
   get() {
     return this[_constants.K_EXECUTE_MESSAGE]?.content.executionId;
   }
@@ -110,6 +114,12 @@ ParallelGatewayBehaviour.prototype.execute = function execute(executeMessage) {
     }
   }
 };
+
+/**
+ * Setup peer monitor
+ * @param {import('#types').ElementBrokerMessage} executeMessage
+ * @returns {void}
+ */
 ParallelGatewayBehaviour.prototype.setup = function setup(executeMessage) {
   const peerIds = new Set([...this.activity[K_PEERS].values()].map(v => [...v]).flat());
   this[_constants.K_TARGETS] = new Map([...peerIds].map(pid => [pid, this.activity.getActivityById(pid)]));
@@ -142,9 +152,7 @@ ParallelGatewayBehaviour.prototype.setup = function setup(executeMessage) {
     exclusive: true,
     prefetch: 10000
   });
-  if (this.isConverging) {
-    this.broker.publish('event', 'activity.converge', (0, _messageHelper.cloneContent)(executeContent));
-  }
+  this.broker.publish('event', 'activity.converge', (0, _messageHelper.cloneContent)(executeContent));
   return this.broker.publish('execution', 'execute.start', (0, _messageHelper.cloneContent)(executeMessage.content, {
     preventComplete: true,
     state: STATE_SETUP
@@ -179,17 +187,19 @@ ParallelGatewayBehaviour.prototype._stop = function stop() {
   this.broker.cancel('_parallel-execution-peer-enter-tag');
   this.peerMonitor.stop();
 };
+
+/**
+ * Peer monitor
+ * @param {import('#types').Activity} activity parallel gateway activity
+ * @param {Map<string, import('#types').Activity} targets parallel gateway peer target activities
+ */
 function PeerMonitor(activity, targets) {
   this.activity = activity;
   this.id = activity.id;
   this.broker = activity.broker;
-  this.running = 0;
-  this.index = 0;
-  this.discarded = 0;
   this.running = new Map();
   this.watching = new Map();
   this.targets = targets;
-  this.touched = new Set();
   this.inbound = [];
 }
 Object.defineProperty(PeerMonitor.prototype, 'isRunning', {
@@ -197,6 +207,12 @@ Object.defineProperty(PeerMonitor.prototype, 'isRunning', {
     return this.running.size > 0;
   }
 });
+
+/**
+ * Execute peer monitor
+ * @param {import('#types').ElementBrokerMessage} executeMessage
+ * @returns {number} number of running peers
+ */
 PeerMonitor.prototype.execute = function execute(executeMessage) {
   const message = (0, _messageHelper.cloneMessage)(executeMessage);
   const inbound = message.content.inbound.pop();
@@ -208,12 +224,16 @@ PeerMonitor.prototype.execute = function execute(executeMessage) {
     state: STATE_MONTITORING,
     preventComplete: true
   });
-  this.touched.add(inbound.sourceId);
   for (const target of this.targets.values()) {
     this.monitor(target);
   }
   return this.running.size;
 };
+
+/**
+ * Monitor peer activity
+ * @param {import('#types').Activity} peerActivity
+ */
 PeerMonitor.prototype.monitor = function monitor(peerActivity) {
   if (this.watching.has(peerActivity.id)) return;
   this.activity.logger.debug(`<${this.id}> monitor <${peerActivity.id}> with status: ${peerActivity.status}`);

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;
@@ -386,7 +391,7 @@ ProcessExecution.prototype._start = function start() {
   this._shakeOnStart();
   for (const a of startActivities) a.init();
   this[_constants.K_STATUS] = 'executing';
-  for (const a of startActivities) a.run();
+  for (const a of startActivities) a.consumeInbound();
   if (!startActivities.size) {
     for (const a of this[K_ELEMENTS].triggeredByEvent) {
       if (a.isCatching && !a.isRunning) a.run();
@@ -551,7 +556,7 @@ ProcessExecution.prototype._shakeElements = function shakeElements(fromId) {
   }) => {
     if (content.parent.id !== this.id) return;
     switch (routingKey) {
-      case 'activity.shake.join':
+      case 'activity.shake.converge':
         {
           const join = convergingGateways.get(content.join);
           if (!join) {
@@ -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.2",
   "description": "Executable workflow elements based on BPMN 2.0",
   "type": "module",
   "main": "./dist/index.js",

package/src/activity/Activity.js

@@ -91,8 +91,10 @@ export function Activity(Behaviour, activityDef, context) {
     outboundEvaluator: new OutboundEvaluator(this, outboundSequenceFlows),
   };
 
+  const isThrowingLink = activityDef.isThrowing && activityDef.linkNames?.length;
+
   this[K_FLAGS] = {
-    isEnd: !outboundSequenceFlows.length,
+    isEnd: !outboundSequenceFlows.length && !isThrowingLink,
     isStart: !hasInboundTrigger && !behaviour.triggeredByEvent && !activityDef.isCatching,
     isSubProcess: activityDef.isSubProcess,
     isMultiInstance: !!behaviour.loopCharacteristics,
@@ -262,7 +264,7 @@ Object.defineProperties(Activity.prototype, {
   },
   initialized: {
     get() {
-      return !!this[K_EXEC]?.get('initExecutionId');
+      return this[K_EXEC].get('initialized') > 0;
     },
   },
 });
@@ -274,7 +276,25 @@ Object.defineProperties(Activity.prototype, {
 Activity.prototype.activate = function activate() {
   if (this[K_ACTIVATED]) return;
   this[K_ACTIVATED] = true;
-  return this.addInboundListeners() && this._consumeInbound();
+  this.addInboundListeners();
+  return this.consumeInbound();
+};
+
+/**
+ * Assert the inbound queue consumer when the activity has a trigger or is initialized.
+ * Idempotent: asserting the consumer again while one is active is a no-op.
+ * @returns {void}
+ */
+Activity.prototype.consumeInbound = function consumeInbound() {
+  if (!this[K_ACTIVATED]) return;
+
+  if (this.status) return;
+
+  if (!this._getInboundTriggers().length && !this.initialized) return;
+
+  const onInbound = this[K_MESSAGE_HANDLERS].onInbound;
+
+  return this.broker.getQueue('inbound-q').assertConsumer(onInbound, { consumerTag: '_run-on-inbound' });
 };
 
 /** @internal */
@@ -319,14 +339,18 @@ Activity.prototype.deactivate = function deactivate() {
 /**
  * Initialise activity executionId and emit init event without starting the run.
  * @param {Record<string, any>} [initContent] Optional content merged into the init message
+ * @param {import('smqp').MessageProperties} [properties] Optional message properties merged into the init message properties
  */
-Activity.prototype.init = function init(initContent) {
+Activity.prototype.init = function init(initContent, properties) {
   const id = this.id;
   const exec = this[K_EXEC];
-  const executionId = exec.has('initExecutionId') ? exec.get('initExecutionId') : getUniqueId(id);
-  exec.set('initExecutionId', executionId);
+  exec.set('initialized', (exec.get('initialized') || 0) + 1);
+  const executionId = getUniqueId(id);
   this.logger.debug(`<${id}> initialized with executionId <${executionId}>`);
   this._publishEvent('init', this._createMessage({ ...initContent, executionId }));
+  this.broker
+    .getQueue('inbound-q')
+    .queueMessage({ routingKey: 'activity.init' }, { ...initContent, id, executionId }, { persistent: false, ...properties });
 };
 
 /**
@@ -338,14 +362,13 @@ Activity.prototype.run = function run(runContent) {
   const id = this.id;
   if (this.isRunning) throw new Error(`activity <${id}> is already running`);
 
-  const exec = this[K_EXEC];
-  const executionId = exec.get('initExecutionId') || getUniqueId(id);
-  exec.set('executionId', executionId);
-  exec.delete('initExecutionId');
+  const { initExecutionId, ...runMessage } = runContent || {};
+  const executionId = runMessage?.id === id && initExecutionId ? initExecutionId : getUniqueId(id);
+  this[K_EXEC].set('executionId', executionId);
 
   this._consumeApi();
 
-  const content = this._createMessage({ ...runContent, executionId });
+  const content = this._createMessage({ ...runMessage, executionId });
   const broker = this.broker;
 
   broker.publish('run', 'run.enter', content);
@@ -541,10 +564,8 @@ Activity.prototype.getActivityById = function getActivityById(elementId) {
 
 /** @internal */
 Activity.prototype._runDiscard = function runDiscard(discardContent) {
-  const exec = this[K_EXEC];
-  const executionId = exec.get('initExecutionId') || getUniqueId(this.id);
-  exec.set('executionId', executionId);
-  exec.delete('initExecutionId');
+  const executionId = getUniqueId(this.id);
+  this[K_EXEC].set('executionId', executionId);
 
   this._consumeApi();
 
@@ -594,7 +615,7 @@ Activity.prototype._onShakeMessage = function _onShakeMessage(sourceMessage) {
   if (this[K_FLAGS].isParallelGateway) {
     const message = cloneMessage(sourceMessage, { join: this.id });
     message.content.sequence.push({ id: this.id, type: this.type });
-    return this.broker.publish('event', 'activity.shake.join', message.content, {
+    return this.broker.publish('event', 'activity.shake.converge', message.content, {
       persistent: false,
       type: 'shake',
     });
@@ -641,18 +662,6 @@ Activity.prototype._shakeOutbound = function shakeOutbound(sourceMessage) {
   for (const t of targets.values()) t.shake(message);
 };
 
-/** @internal */
-Activity.prototype._consumeInbound = function consumeInbound() {
-  if (!this[K_ACTIVATED]) return;
-
-  if (this.status || !this._getInboundTriggers().length) return;
-
-  const inboundQ = this.broker.getQueue('inbound-q');
-  const onInbound = this[K_MESSAGE_HANDLERS].onInbound;
-
-  return inboundQ.assertConsumer(onInbound, { consumerTag: '_run-on-inbound' });
-};
-
 /** @internal */
 Activity.prototype._onInbound = function onInbound(routingKey, message) {
   message.ack();
@@ -660,25 +669,28 @@ Activity.prototype._onInbound = function onInbound(routingKey, message) {
   broker.cancel('_run-on-inbound');
 
   const content = message.content;
-  const inbound = [cloneContent(content)];
 
   switch (routingKey) {
-    case 'activity.relink':
-      if (content.executionId) this[K_EXEC].set('initExecutionId', content.executionId);
+    case 'activity.init': {
+      const exec = this[K_EXEC];
+      exec.set('initialized', (exec.get('initialized') || 0) - 1);
       return this.run({
+        initExecutionId: content.executionId,
+        id: content.id,
         message: content.message,
-        inbound,
+        ...(content.inbound?.length && { inbound: content.inbound }),
       });
+    }
     case 'association.take':
     case 'flow.take':
     case 'activity.restart':
     case 'activity.enter':
       return this.run({
         message: content.message,
-        inbound,
+        inbound: [cloneContent(content)],
       });
     case 'activity.discard': {
-      return this._runDiscard({ inbound });
+      return this._runDiscard({ inbound: [cloneContent(content)] });
     }
   }
 };
@@ -702,18 +714,7 @@ Activity.prototype._onInboundEvent = function onInboundEvent(routingKey, message
     case 'activity.link': {
       const linkName = content.message?.linkName;
       if (!this[K_FLAGS].linkNames?.includes(linkName)) break;
-      const executionId = getUniqueId(this.id);
-      this.broker.publish(
-        'event',
-        'activity.enter',
-        cloneContent(content, { id: this.id, type: this.type, executionId, state: 'enter', message: { ...content.message } })
-      );
-      inboundQ.queueMessage(
-        { routingKey: 'activity.relink' },
-        cloneContent(content, { id: this.id, executionId, message: { ...content.message } }),
-        properties
-      );
-      return;
+      return this.init({ inbound: [cloneContent(content)] });
     }
     case 'association.take':
     case 'flow.take':
@@ -890,7 +891,7 @@ Activity.prototype._continueRunMessage = function continueRunMessage(routingKey,
     case 'run.next':
       message.ack();
       this._pauseRunQ();
-      return this._consumeInbound();
+      return this.consumeInbound();
   }
 
   if (!step) message.ack();

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/events/BoundaryEvent.js

@@ -41,9 +41,9 @@ Object.defineProperty(BoundaryEventBehaviour.prototype, 'executionId', {
 });
 
 Object.defineProperty(BoundaryEventBehaviour.prototype, 'cancelActivity', {
+  /** @returns {boolean} */
   get() {
-    const behaviour = this.activity.behaviour || {};
-    return 'cancelActivity' in behaviour ? behaviour.cancelActivity : true;
+    return this.activity.behaviour?.cancelActivity ?? true;
   },
 });
 

package/src/gateways/ParallelGateway.js

@@ -74,13 +74,17 @@ export function ParallelGatewayBehaviour(activity) {
   this.type = activity.type;
   this.activity = activity;
   this.broker = activity.broker;
+  /**
+   * Inbound taken sequence flow sequences
+   * @type {Set<import('#types').ElementMessageContent}
+   */
   this.inbound = new Set();
 
-  this.isConverging = true;
   this[K_EXECUTE_MESSAGE] = undefined;
 }
 
 Object.defineProperty(ParallelGatewayBehaviour.prototype, 'executionId', {
+  /** @returns {string | undefined} */
   get() {
     return this[K_EXECUTE_MESSAGE]?.content.executionId;
   },
@@ -112,6 +116,11 @@ ParallelGatewayBehaviour.prototype.execute = function execute(executeMessage) {
   }
 };
 
+/**
+ * Setup peer monitor
+ * @param {import('#types').ElementBrokerMessage} executeMessage
+ * @returns {void}
+ */
 ParallelGatewayBehaviour.prototype.setup = function setup(executeMessage) {
   const peerIds = new Set([...this.activity[K_PEERS].values()].map((v) => [...v]).flat());
   this[K_TARGETS] = new Map([...peerIds].map((pid) => [pid, this.activity.getActivityById(pid)]));
@@ -152,9 +161,7 @@ ParallelGatewayBehaviour.prototype.setup = function setup(executeMessage) {
     { consumerTag: '_converging-inbound', exclusive: true, prefetch: 10000 }
   );
 
-  if (this.isConverging) {
-    this.broker.publish('event', 'activity.converge', cloneContent(executeContent));
-  }
+  this.broker.publish('event', 'activity.converge', cloneContent(executeContent));
 
   return this.broker.publish(
     'execution',
@@ -197,17 +204,18 @@ ParallelGatewayBehaviour.prototype._stop = function stop() {
   this.peerMonitor.stop();
 };
 
+/**
+ * Peer monitor
+ * @param {import('#types').Activity} activity parallel gateway activity
+ * @param {Map<string, import('#types').Activity} targets parallel gateway peer target activities
+ */
 function PeerMonitor(activity, targets) {
   this.activity = activity;
   this.id = activity.id;
   this.broker = activity.broker;
-  this.running = 0;
-  this.index = 0;
-  this.discarded = 0;
   this.running = new Map();
   this.watching = new Map();
   this.targets = targets;
-  this.touched = new Set();
   this.inbound = [];
 }
 
@@ -217,6 +225,11 @@ Object.defineProperty(PeerMonitor.prototype, 'isRunning', {
   },
 });
 
+/**
+ * Execute peer monitor
+ * @param {import('#types').ElementBrokerMessage} executeMessage
+ * @returns {number} number of running peers
+ */
 PeerMonitor.prototype.execute = function execute(executeMessage) {
   const message = cloneMessage(executeMessage);
   const inbound = message.content.inbound.pop();
@@ -231,8 +244,6 @@ PeerMonitor.prototype.execute = function execute(executeMessage) {
     preventComplete: true,
   });
 
-  this.touched.add(inbound.sourceId);
-
   for (const target of this.targets.values()) {
     this.monitor(target);
   }
@@ -240,6 +251,10 @@ PeerMonitor.prototype.execute = function execute(executeMessage) {
   return this.running.size;
 };
 
+/**
+ * Monitor peer activity
+ * @param {import('#types').Activity} peerActivity
+ */
 PeerMonitor.prototype.monitor = function monitor(peerActivity) {
   if (this.watching.has(peerActivity.id)) return;
 

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;
@@ -393,7 +400,7 @@ ProcessExecution.prototype._start = function start() {
 
   for (const a of startActivities) a.init();
   this[K_STATUS] = 'executing';
-  for (const a of startActivities) a.run();
+  for (const a of startActivities) a.consumeInbound();
 
   if (!startActivities.size) {
     for (const a of this[K_ELEMENTS].triggeredByEvent) {
@@ -564,7 +571,7 @@ ProcessExecution.prototype._shakeElements = function shakeElements(fromId) {
       if (content.parent.id !== this.id) return;
 
       switch (routingKey) {
-        case 'activity.shake.join': {
+        case 'activity.shake.converge': {
           const join = convergingGateways.get(content.join);
           if (!join) {
             convergingGateways.set(content.join, content);
@@ -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;
@@ -578,6 +580,11 @@ declare module 'bpmn-elements' {
 		 * Subscribe to inbound flows and start consuming the inbound queue.
 		 * */
 		activate(): void;
+		/**
+		 * Assert the inbound queue consumer when the activity has a trigger or is initialized.
+		 * Idempotent: asserting the consumer again while one is active is a no-op.
+		 * */
+		consumeInbound(): void;
 		/**
 		 * Cancel inbound subscriptions and any pending run/format consumers.
 		 */
@@ -585,8 +592,9 @@ declare module 'bpmn-elements' {
 		/**
 		 * Initialise activity executionId and emit init event without starting the run.
 		 * @param initContent Optional content merged into the init message
+		 * @param properties Optional message properties merged into the init message properties
 		 */
-		init(initContent?: Record<string, any>): void;
+		init(initContent?: Record<string, any>, properties?: import("smqp").MessageProperties): void;
 		/**
 		 * Start running the activity by publishing run.enter and run.start.
 		 * @param runContent Optional content merged into the run message
@@ -1046,8 +1054,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 +1481,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 +1670,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.
 		 * */
@@ -1945,7 +1956,7 @@ declare module 'bpmn-elements' {
 		environment: Environment;
 		broker: ElementBroker<Activity>;
 		get executionId(): string | undefined;
-		get cancelActivity(): any;
+		get cancelActivity(): boolean;
 		
 		execute(executeMessage: ElementBrokerMessage): void;
 	}
@@ -2101,29 +2112,48 @@ declare module 'bpmn-elements' {
 		type: string;
 		activity: Activity;
 		broker: ElementBroker<Activity>;
-		inbound: Set<any>;
-		isConverging: boolean;
-		get executionId(): any;
+		/**
+		 * Inbound taken sequence flow sequences
+		 * */
+		inbound: Set<ElementMessageContent>;
+		get executionId(): string | undefined;
 		
 		execute(executeMessage: ElementBrokerMessage): void;
-		setup(executeMessage: any): number | undefined;
+		/**
+		 * Setup peer monitor
+		 * */
+		setup(executeMessage: ElementBrokerMessage): void;
 		peerMonitor: PeerMonitor | undefined;
 	}
+	/**
+	 * Peer monitor
+	 * @param activity parallel gateway activity
+	 * @param targets parallel gateway peer target activities
+	 */
 		class PeerMonitor {
-		constructor(activity: any, targets: any);
-		activity: any;
-		id: any;
-		broker: any;
+		/**
+		 * Peer monitor
+		 * @param activity parallel gateway activity
+		 * @param targets parallel gateway peer target activities
+		 */
+		constructor(activity: Activity, targets: Map<string, Activity>);
+		activity: Activity;
+		id: string | undefined;
+		broker: ElementBroker<Activity>;
 		running: Map<any, any>;
-		index: number;
-		discarded: number;
 		watching: Map<any, any>;
-		targets: any;
-		touched: Set<any>;
+		targets: Map<string, Activity>;
 		inbound: any[];
 		get isRunning(): boolean;
-		execute(executeMessage: any): number;
-		monitor(peerActivity: any): void;
+		/**
+		 * Execute peer monitor
+		 * @returns number of running peers
+		 */
+		execute(executeMessage: ElementBrokerMessage): number;
+		/**
+		 * Monitor peer activity
+		 * */
+		monitor(peerActivity: Activity): void;
 		stop(): void;
 	}
 	/**

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;