@fluojs/cqrs 1.1.2 → 3.0.0

package/dist/buses/saga-bus.d.ts

@@ -1,10 +1,11 @@
-import type { OnApplicationBootstrap, OnApplicationShutdown } from '@fluojs/runtime';
+import type { OnApplicationBootstrap, OnApplicationShutdown, RuntimeCleanupRegistration } from '@fluojs/runtime';
 import { CqrsBusBase } from '../discovery.js';
 import type { CqrsModuleOptions } from '../module.js';
 import type { CqrsDispatchContext, IEvent } from '../types.js';
-interface SagaDispatchOptions {
-    readonly allowDuringShutdown?: boolean;
-}
+import { type SagaDispatchOptions } from './saga-continuation.js';
+import { CqrsShutdownDeadline } from './shutdown-deadline.js';
+/** Private capability authorizing saga dispatch from an already active publish drain. */
+export declare const CQRS_SAGA_DRAIN_AUTHORIZATION: unique symbol;
 /**
  * Runtime saga coordinator that discovers `@Saga()` providers and serializes execution per saga token.
  *
@@ -13,14 +14,17 @@ interface SagaDispatchOptions {
  */
 export declare class CqrsSagaLifecycleService extends CqrsBusBase implements OnApplicationBootstrap, OnApplicationShutdown {
     private readonly moduleOptions;
+    private readonly shutdownDeadline;
     private descriptorsByEvent;
     private discoveryPromise;
     private discovered;
     private readonly executionChains;
     private lifecycleState;
     private readonly pendingDispatches;
+    private authorizedPipelineLeaseCount;
     private shutdownDrainTimeouts;
-    constructor(runtimeContainer: ConstructorParameters<typeof CqrsBusBase>[0], compiledModules: ConstructorParameters<typeof CqrsBusBase>[1], logger: ConstructorParameters<typeof CqrsBusBase>[2], moduleOptions?: CqrsModuleOptions);
+    private unregisterShutdownStartCleanup;
+    constructor(runtimeContainer: ConstructorParameters<typeof CqrsBusBase>[0], compiledModules: ConstructorParameters<typeof CqrsBusBase>[1], logger: ConstructorParameters<typeof CqrsBusBase>[2], moduleOptions?: CqrsModuleOptions, registerRuntimeCleanup?: RuntimeCleanupRegistration, shutdownDeadline?: CqrsShutdownDeadline);
     onApplicationBootstrap(): Promise<void>;
     onApplicationShutdown(): Promise<void>;
     /**
@@ -41,18 +45,26 @@ export declare class CqrsSagaLifecycleService extends CqrsBusBase implements OnA
      * @param event Event instance that may trigger one or more sagas.
      * @returns A promise that resolves once all matching saga chains for the event complete.
      */
-    dispatch<TEvent extends IEvent>(event: TEvent, context?: CqrsDispatchContext, options?: SagaDispatchOptions): Promise<void>;
+    dispatch<TEvent extends IEvent>(event: TEvent, context?: CqrsDispatchContext, options?: SagaDispatchOptions<typeof CQRS_SAGA_DRAIN_AUTHORIZATION>): Promise<void>;
+    /**
+     * Retains the discovered saga graph for one active CQRS publish pipeline.
+     *
+     * @returns A release function that must run after the authorized pipeline settles.
+     */
+    acquireAuthorizedPipelineLease(): () => void;
+    private runDispatch;
     private assertAcceptingNewWork;
+    private markApplicationShutdownStarted;
     private matchSagaDescriptors;
     private dispatchWithOrdering;
+    private trackPendingDispatch;
+    private clearStoppedSagaGraphIfQuiescent;
     private drainActiveSagaWork;
-    private awaitShutdownDrain;
+    private reportShutdownDrainTimeout;
     private resolveShutdownDrainTimeoutMs;
-    private createDispatchContext;
     private invokeSaga;
     private ensureDiscovered;
     private discoverHandlers;
     private discoverSagaDescriptors;
 }
-export {};
 //# sourceMappingURL=saga-bus.d.ts.map

package/dist/buses/saga-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"saga-bus.d.ts","sourceRoot":"","sources":["../../src/buses/saga-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAI9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,EAAyB,MAAM,aAAa,CAAC;AAMrG,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAsCD;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,sBAAsB,EAAE,qBAAqB;IAa9G,OAAO,CAAC,QAAQ,CAAC,aAAa;IAZhC,OAAO,CAAC,kBAAkB,CAA8C;IACxE,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,cAAc,CAAsF;IAC5G,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,qBAAqB,CAAK;gBAGhC,gBAAgB,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC9D,eAAe,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC7D,MAAM,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EACnC,aAAa,GAAE,iBAAsB;IAKlD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5C;;;;OAIG;IACH,kBAAkB,IAAI;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,cAAc,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;QACxF,eAAe,EAAE,MAAM,CAAC;QACxB,qBAAqB,EAAE,MAAM,CAAC;KAC/B;IAUD;;;;;OAKG;IACG,QAAQ,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAarI,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,oBAAoB;YAYd,oBAAoB;YA0CpB,mBAAmB;YAmBnB,kBAAkB;IAiBhC,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,qBAAqB;YAaf,UAAU;YAoBV,gBAAgB;YAchB,gBAAgB;IAiB9B,OAAO,CAAC,uBAAuB;CA+ChC"}
+{"version":3,"file":"saga-bus.d.ts","sourceRoot":"","sources":["../../src/buses/saga-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAGjH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,EAAyB,MAAM,aAAa,CAAC;AACrG,OAAO,EAA8D,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG9H,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAK9D,yFAAyF;AACzF,eAAO,MAAM,6BAA6B,EAAE,OAAO,MAAmD,CAAC;AAkBvG;;;;;GAKG;AACH,qBAQa,wBAAyB,SAAQ,WAAY,YAAW,sBAAsB,EAAE,qBAAqB;IAe9G,OAAO,CAAC,QAAQ,CAAC,aAAa;IAE9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAhBnC,OAAO,CAAC,kBAAkB,CAA8C;IACxE,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,cAAc,CAAsF;IAC5G,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,4BAA4B,CAAK;IACzC,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,8BAA8B,CAA2B;gBAG/D,gBAAgB,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC9D,eAAe,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC7D,MAAM,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EACnC,aAAa,GAAE,iBAAsB,EACtD,sBAAsB,GAAE,0BAAkD,EACzD,gBAAgB,GAAE,oBAAiD;IAShF,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5C;;;;OAIG;IACH,kBAAkB,IAAI;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,cAAc,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;QACxF,eAAe,EAAE,MAAM,CAAC;QACxB,qBAAqB,EAAE,MAAM,CAAC;KAC/B;IAcD;;;;;OAKG;IACG,QAAQ,CAAC,MAAM,SAAS,MAAM,EAClC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,mBAAmB,EAC7B,OAAO,GAAE,mBAAmB,CAAC,OAAO,6BAA6B,CAAM,GACtE,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;OAIG;IACH,8BAA8B,IAAI,MAAM,IAAI;YAe9B,WAAW;IA2CzB,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,8BAA8B;IAQtC,OAAO,CAAC,oBAAoB;YAYd,oBAAoB;YAwBpB,oBAAoB;IAWlC,OAAO,CAAC,gCAAgC;YAgB1B,mBAAmB;IAUjC,OAAO,CAAC,0BAA0B;IAQlC,OAAO,CAAC,6BAA6B;YAUvB,UAAU;YAoBV,gBAAgB;YAchB,gBAAgB;IAiB9B,OAAO,CAAC,uBAAuB;CAGhC"}

package/dist/buses/saga-bus.js

@@ -5,15 +5,20 @@ function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e =
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { FluoError, Inject, InvariantError } from '@fluojs/core';
-import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CLEANUP_REGISTRATION, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
 import { CqrsBusBase } from '../discovery.js';
-import { SagaExecutionError, SagaTopologyError } from '../errors.js';
+import { SagaExecutionError } from '../errors.js';
 import { createIsolatedEvent } from '../event-clone.js';
-import { getSagaMetadata } from '../metadata.js';
 import { CQRS_MODULE_OPTIONS } from '../tokens.js';
-const MAX_NESTED_SAGA_DEPTH = 32;
+import { drainSagaContinuations, runSerializedSagaContinuationTasks } from './saga-continuation.js';
+import { discoverSagaDescriptors } from './saga-discovery.js';
+import { drainPendingSagaDispatches } from './saga-drain.js';
+import { CqrsShutdownDeadline } from './shutdown-deadline.js';
+import { enterSagaTopology } from './saga-topology.js';
 const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
-const cqrsDispatchContextStateBrand = Symbol('fluo.cqrs.dispatchContextState');
+
+/** Private capability authorizing saga dispatch from an already active publish drain. */
+export const CQRS_SAGA_DRAIN_AUTHORIZATION = Symbol('fluo.cqrs.sagaDrainAuthorization');
 function isSaga(value) {
   if (typeof value !== 'object' || value === null) {
     return false;
@@ -26,12 +31,6 @@ function toErrorMessage(error) {
   }
   return String(error);
 }
-function isCqrsDispatchContextState(context) {
-  if (typeof context !== 'object' || context === null) {
-    return false;
-  }
-  return context[cqrsDispatchContextStateBrand] === true;
-}
 
 /**
  * Runtime saga coordinator that discovers `@Saga()` providers and serializes execution per saga token.
@@ -42,7 +41,7 @@ function isCqrsDispatchContextState(context) {
 let _CqrsSagaLifecycleSer;
 class CqrsSagaLifecycleService extends CqrsBusBase {
   static {
-    [_CqrsSagaLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, CQRS_MODULE_OPTIONS)], [], 0, void 0, CqrsBusBase).c;
+    [_CqrsSagaLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, CQRS_MODULE_OPTIONS, RUNTIME_CLEANUP_REGISTRATION, CqrsShutdownDeadline)], [], 0, void 0, CqrsBusBase).c;
   }
   descriptorsByEvent = new Map();
   discoveryPromise;
@@ -50,10 +49,16 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
   executionChains = new Map();
   lifecycleState = 'created';
   pendingDispatches = new Set();
+  authorizedPipelineLeaseCount = 0;
   shutdownDrainTimeouts = 0;
-  constructor(runtimeContainer, compiledModules, logger, moduleOptions = {}) {
+  unregisterShutdownStartCleanup;
+  constructor(runtimeContainer, compiledModules, logger, moduleOptions = {}, registerRuntimeCleanup = () => () => undefined, shutdownDeadline = new CqrsShutdownDeadline()) {
     super(runtimeContainer, compiledModules, logger);
     this.moduleOptions = moduleOptions;
+    this.shutdownDeadline = shutdownDeadline;
+    this.unregisterShutdownStartCleanup = registerRuntimeCleanup(() => {
+      this.markApplicationShutdownStarted();
+    });
   }
   async onApplicationBootstrap() {
     this.lifecycleState = 'discovering';
@@ -66,14 +71,12 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     }
   }
   async onApplicationShutdown() {
-    this.lifecycleState = 'stopping';
+    this.markApplicationShutdownStarted();
+    this.unregisterShutdownStartCleanup?.();
+    this.unregisterShutdownStartCleanup = undefined;
     await this.drainActiveSagaWork();
-    this.executionChains.clear();
-    this.handlerInstances.clear();
-    this.descriptorsByEvent.clear();
-    this.discovered = false;
-    this.discoveryPromise = undefined;
     this.lifecycleState = 'stopped';
+    this.clearStoppedSagaGraphIfQuiescent();
   }
 
   /**
@@ -82,11 +85,12 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
    * @returns Current discovery state, in-flight execution count, lifecycle state, and discovered saga count.
    */
   getRuntimeSnapshot() {
+    const stopped = this.lifecycleState === 'stopped';
     return {
-      discovered: this.discovered,
+      discovered: stopped ? false : this.discovered,
       inFlightSagaExecutions: this.pendingDispatches.size,
       lifecycleState: this.lifecycleState,
-      sagasDiscovered: new Set(Array.from(this.descriptorsByEvent.values()).flatMap(descriptors => descriptors.map(d => d.token))).size,
+      sagasDiscovered: stopped ? 0 : new Set(Array.from(this.descriptorsByEvent.values()).flatMap(descriptors => descriptors.map(d => d.token))).size,
       shutdownDrainTimeouts: this.shutdownDrainTimeouts
     };
   }
@@ -98,22 +102,66 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
    * @returns A promise that resolves once all matching saga chains for the event complete.
    */
   async dispatch(event, context, options = {}) {
-    this.assertAcceptingNewWork(options);
+    this.assertAcceptingNewWork(options.drainAuthorization);
+    return this.trackPendingDispatch(this.runDispatch(event, context, options));
+  }
+
+  /**
+   * Retains the discovered saga graph for one active CQRS publish pipeline.
+   *
+   * @returns A release function that must run after the authorized pipeline settles.
+   */
+  acquireAuthorizedPipelineLease() {
+    this.authorizedPipelineLeaseCount += 1;
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      this.authorizedPipelineLeaseCount -= 1;
+      this.clearStoppedSagaGraphIfQuiescent();
+    };
+  }
+  async runDispatch(event, context, options) {
     await this.ensureDiscovered();
-    const descriptors = this.matchSagaDescriptors(event);
-    if (descriptors.length === 0) {
+    const entries = this.matchSagaDescriptors(event).map(descriptor => ({
+      descriptor,
+      topology: enterSagaTopology(context, descriptor)
+    }));
+    if (entries.length === 0) {
+      await options.afterSagas?.();
       return;
     }
-    await Promise.all(descriptors.map(descriptor => this.dispatchWithOrdering(descriptor, event, context)));
-  }
-  assertAcceptingNewWork(options) {
-    if (options.allowDuringShutdown) {
+    const continuationEntry = entries.find(entry => entry.topology.reentrantToken);
+    if (continuationEntry) {
+      const continuationTasks = entries.map(entry => {
+        const scheduledDispatch = entry.topology.reentrantToken ? this.dispatchWithOrdering(entry.descriptor, event, entry.topology) : undefined;
+        return {
+          run: () => scheduledDispatch ?? this.dispatchWithOrdering(entry.descriptor, event, entry.topology),
+          token: entry.descriptor.token
+        };
+      });
+      continuationEntry.topology.continuationScope.queue.push(async () => {
+        await runSerializedSagaContinuationTasks(continuationTasks);
+        await options.afterSagas?.();
+      });
       return;
     }
-    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+    await Promise.all(entries.map(entry => this.dispatchWithOrdering(entry.descriptor, event, entry.topology)));
+    await options.afterSagas?.();
+  }
+  assertAcceptingNewWork(drainAuthorization) {
+    if ((this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') && drainAuthorization !== CQRS_SAGA_DRAIN_AUTHORIZATION) {
       throw new InvariantError('CQRS saga bus cannot dispatch after shutdown has started.');
     }
   }
+  markApplicationShutdownStarted() {
+    this.shutdownDeadline.start(this.resolveShutdownDrainTimeoutMs());
+    if (this.lifecycleState !== 'stopped') {
+      this.lifecycleState = 'stopping';
+    }
+  }
   matchSagaDescriptors(event) {
     const descriptors = [];
     for (const [eventType, eventDescriptors] of this.descriptorsByEvent.entries()) {
@@ -123,58 +171,52 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     }
     return descriptors;
   }
-  async dispatchWithOrdering(descriptor, event, activeContext) {
-    const activeState = isCqrsDispatchContextState(activeContext) ? activeContext : undefined;
-    const routeLabel = `${descriptor.targetType.name}(${descriptor.eventType.name})`;
-    const isActiveRoute = activeState?.activeRoutes.some(route => route.token === descriptor.token && route.eventType === descriptor.eventType);
-    const isActiveToken = activeState?.activeRoutes.some(route => route.token === descriptor.token) ?? false;
-    if (isActiveRoute) {
-      throw new SagaTopologyError(`Saga ${descriptor.targetType.name} re-entered an unsafe cycle while handling ${descriptor.eventType.name}. ` + `Active saga path: ${[...(activeState?.path ?? []), routeLabel].join(' -> ')}.`);
-    }
-    if ((activeState?.depth ?? 0) >= MAX_NESTED_SAGA_DEPTH) {
-      throw new SagaTopologyError(`Saga ${descriptor.targetType.name} exceeded the maximum nested saga depth of ${MAX_NESTED_SAGA_DEPTH} while handling ${descriptor.eventType.name}. ` + 'Keep in-process saga graphs acyclic and externally bounded.');
-    }
-    if (isActiveToken) {
-      await this.invokeSaga(descriptor, event, this.createDispatchContext(activeState, descriptor, routeLabel));
-      return;
-    }
+  async dispatchWithOrdering(descriptor, event, topology) {
     const previous = this.executionChains.get(descriptor.token) ?? Promise.resolve();
-    const current = previous.then(async () => {
-      await this.invokeSaga(descriptor, event, this.createDispatchContext(activeState, descriptor, routeLabel));
-    });
-    this.executionChains.set(descriptor.token, current.catch(() => undefined));
-    this.pendingDispatches.add(current);
+    const current = previous.then(async () => this.invokeSaga(descriptor, event, topology.context));
+    const settled = current.catch(() => undefined);
+    this.executionChains.set(descriptor.token, settled);
     try {
       await current;
+      if (topology.ownsContinuationScope) {
+        await drainSagaContinuations(topology.continuationScope);
+      }
     } finally {
-      this.pendingDispatches.delete(current);
+      if (this.executionChains.get(descriptor.token) === settled) {
+        this.executionChains.delete(descriptor.token);
+      }
     }
   }
-  async drainActiveSagaWork() {
-    const activeWork = [...this.pendingDispatches, ...this.executionChains.values()];
-    if (activeWork.length === 0) {
+  async trackPendingDispatch(dispatch) {
+    this.pendingDispatches.add(dispatch);
+    try {
+      await dispatch;
+    } finally {
+      this.pendingDispatches.delete(dispatch);
+      this.clearStoppedSagaGraphIfQuiescent();
+    }
+  }
+  clearStoppedSagaGraphIfQuiescent() {
+    if (this.lifecycleState !== 'stopped' || this.pendingDispatches.size > 0 || this.authorizedPipelineLeaseCount > 0) {
       return;
     }
-    const timeoutMs = this.resolveShutdownDrainTimeoutMs();
-    const drained = await this.awaitShutdownDrain(activeWork, timeoutMs);
+    this.executionChains.clear();
+    this.handlerInstances.clear();
+    this.descriptorsByEvent.clear();
+    this.discovered = false;
+    this.discoveryPromise = undefined;
+  }
+  async drainActiveSagaWork() {
+    const timeoutMs = this.shutdownDeadline.remainingTimeoutMs() ?? this.resolveShutdownDrainTimeoutMs();
+    const activeWorkCount = this.pendingDispatches.size;
+    const drained = await drainPendingSagaDispatches(this.pendingDispatches, timeoutMs);
     if (!drained) {
-      this.shutdownDrainTimeouts += 1;
-      this.logger.warn(`CQRS saga shutdown drain exceeded ${String(timeoutMs)}ms with ${String(activeWork.length)} active saga task(s); continuing shutdown.`, 'CqrsSagaLifecycleService');
+      this.reportShutdownDrainTimeout(timeoutMs, activeWorkCount);
     }
   }
-  async awaitShutdownDrain(activeWork, timeoutMs) {
-    let timeoutId;
-    const timeout = new Promise(resolve => {
-      timeoutId = setTimeout(() => resolve(false), timeoutMs);
-    });
-    const drain = Promise.allSettled(activeWork).then(() => true);
-    try {
-      return await Promise.race([drain, timeout]);
-    } finally {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-      }
-    }
+  reportShutdownDrainTimeout(timeoutMs, activeWorkCount) {
+    this.shutdownDrainTimeouts += 1;
+    this.logger.warn(`CQRS saga shutdown drain exceeded ${String(timeoutMs)}ms with ${String(activeWorkCount)} active saga task(s); continuing shutdown.`, 'CqrsSagaLifecycleService');
   }
   resolveShutdownDrainTimeoutMs() {
     const timeoutMs = this.moduleOptions.shutdown?.drainTimeoutMs;
@@ -183,17 +225,6 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     }
     return Math.floor(timeoutMs);
   }
-  createDispatchContext(activeContext, descriptor, routeLabel) {
-    return {
-      [cqrsDispatchContextStateBrand]: true,
-      activeRoutes: [...(activeContext?.activeRoutes ?? []), {
-        eventType: descriptor.eventType,
-        token: descriptor.token
-      }],
-      depth: (activeContext?.depth ?? 0) + 1,
-      path: [...(activeContext?.path ?? []), routeLabel]
-    };
-  }
   async invokeSaga(descriptor, event, context) {
     const instance = await this.resolveHandlerInstance(descriptor.token);
     if (!isSaga(instance)) {
@@ -234,37 +265,7 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     }
   }
   discoverSagaDescriptors() {
-    const descriptorsByEvent = new Map();
-    const seenByTarget = new WeakMap();
-    for (const candidate of this.discoveryCandidates()) {
-      const metadata = getSagaMetadata(candidate.targetType);
-      if (!metadata) {
-        continue;
-      }
-      if (candidate.scope !== 'singleton') {
-        this.logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @Saga() but is registered with ${candidate.scope} scope. Sagas are registered only for singleton providers.`, 'CqrsSagaLifecycleService');
-        continue;
-      }
-      const seenEventTypes = seenByTarget.get(candidate.targetType) ?? new Set();
-      for (const eventType of metadata.eventTypes) {
-        if (seenEventTypes.has(eventType)) {
-          continue;
-        }
-        seenEventTypes.add(eventType);
-        const descriptors = descriptorsByEvent.get(eventType) ?? [];
-        if (!descriptors.some(descriptor => descriptor.targetType === candidate.targetType)) {
-          descriptors.push({
-            eventType,
-            moduleName: candidate.moduleName,
-            targetType: candidate.targetType,
-            token: candidate.token
-          });
-          descriptorsByEvent.set(eventType, descriptors);
-        }
-      }
-      seenByTarget.set(candidate.targetType, seenEventTypes);
-    }
-    return descriptorsByEvent;
+    return discoverSagaDescriptors(this.discoveryCandidates(), this.logger);
   }
   static {
     _initClass();

package/dist/buses/saga-continuation.d.ts

@@ -0,0 +1,14 @@
+export interface SagaContinuationScope {
+    readonly queue: Array<() => Promise<void>>;
+}
+export interface SagaDispatchOptions<TDrainAuthorization extends symbol> {
+    readonly afterSagas?: () => Promise<void>;
+    readonly drainAuthorization?: TDrainAuthorization;
+}
+export interface SagaContinuationTask<TToken> {
+    readonly run: () => Promise<void>;
+    readonly token: TToken;
+}
+export declare function runSerializedSagaContinuationTasks<TToken>(tasks: readonly SagaContinuationTask<TToken>[]): Promise<void>;
+export declare function drainSagaContinuations(scope: SagaContinuationScope): Promise<void>;
+//# sourceMappingURL=saga-continuation.d.ts.map

package/dist/buses/saga-continuation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga-continuation.d.ts","sourceRoot":"","sources":["../../src/buses/saga-continuation.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB,CAAC,mBAAmB,SAAS,MAAM;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,mBAAmB,CAAC;CACnD;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,wBAAsB,kCAAkC,CAAC,MAAM,EAC7D,KAAK,EAAE,SAAS,oBAAoB,CAAC,MAAM,CAAC,EAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CAcf;AAED,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxF"}

package/dist/buses/saga-continuation.js

@@ -0,0 +1,24 @@
+export async function runSerializedSagaContinuationTasks(tasks) {
+  const completions = [];
+  const settledChains = new Map();
+  for (const task of tasks) {
+    const previous = settledChains.get(task.token) ?? Promise.resolve();
+    const current = previous.then(task.run);
+    completions.push(current);
+    settledChains.set(task.token, current.catch(() => undefined));
+  }
+  await Promise.all(settledChains.values());
+  await Promise.all(completions);
+}
+export async function drainSagaContinuations(scope) {
+  try {
+    while (scope.queue.length > 0) {
+      const continuation = scope.queue.shift();
+      if (continuation) {
+        await continuation();
+      }
+    }
+  } finally {
+    scope.queue.length = 0;
+  }
+}

package/dist/buses/saga-discovery.d.ts

@@ -0,0 +1,12 @@
+import type { ApplicationLogger } from '@fluojs/runtime';
+import type { DiscoveryCandidate } from '../discovery.js';
+import type { CqrsEventType, SagaDescriptor } from '../types.js';
+/**
+ * Discovers singleton saga registrations by provider-token identity.
+ *
+ * @param candidates Provider registrations compiled from the application module graph.
+ * @param logger Application logger used for non-singleton discovery warnings.
+ * @returns Saga descriptors grouped by event type in discovery order.
+ */
+export declare function discoverSagaDescriptors(candidates: readonly DiscoveryCandidate[], logger: ApplicationLogger): Map<CqrsEventType, SagaDescriptor[]>;
+//# sourceMappingURL=saga-discovery.d.ts.map

package/dist/buses/saga-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga-discovery.d.ts","sourceRoot":"","sources":["../../src/buses/saga-discovery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,MAAM,EAAE,iBAAiB,GACxB,GAAG,CAAC,aAAa,EAAE,cAAc,EAAE,CAAC,CAyCtC"}

package/dist/buses/saga-discovery.js

@@ -0,0 +1,39 @@
+import { getSagaMetadata } from '../metadata.js';
+/**
+ * Discovers singleton saga registrations by provider-token identity.
+ *
+ * @param candidates Provider registrations compiled from the application module graph.
+ * @param logger Application logger used for non-singleton discovery warnings.
+ * @returns Saga descriptors grouped by event type in discovery order.
+ */
+export function discoverSagaDescriptors(candidates, logger) {
+  const descriptorsByEvent = new Map();
+  const seenEventTypesByToken = new Map();
+  for (const candidate of candidates) {
+    const metadata = getSagaMetadata(candidate.targetType);
+    if (!metadata) {
+      continue;
+    }
+    if (candidate.scope !== 'singleton') {
+      logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @Saga() but is registered with ${candidate.scope} scope. Sagas are registered only for singleton providers.`, 'CqrsSagaLifecycleService');
+      continue;
+    }
+    const seenEventTypes = seenEventTypesByToken.get(candidate.token) ?? new Set();
+    for (const eventType of metadata.eventTypes) {
+      if (seenEventTypes.has(eventType)) {
+        continue;
+      }
+      seenEventTypes.add(eventType);
+      const descriptors = descriptorsByEvent.get(eventType) ?? [];
+      descriptors.push({
+        eventType,
+        moduleName: candidate.moduleName,
+        targetType: candidate.targetType,
+        token: candidate.token
+      });
+      descriptorsByEvent.set(eventType, descriptors);
+    }
+    seenEventTypesByToken.set(candidate.token, seenEventTypes);
+  }
+  return descriptorsByEvent;
+}

package/dist/buses/saga-drain.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Waits until a mutable set of saga tasks becomes quiescent within one deadline.
+ *
+ * @param pendingDispatches Live saga task set owned by the lifecycle service.
+ * @param timeoutMs Maximum drain duration in milliseconds.
+ * @returns `true` when all current and late-added tasks settle before the deadline.
+ */
+export declare function drainPendingSagaDispatches(pendingDispatches: ReadonlySet<Promise<void>>, timeoutMs: number): Promise<boolean>;
+//# sourceMappingURL=saga-drain.d.ts.map

package/dist/buses/saga-drain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga-drain.d.ts","sourceRoot":"","sources":["../../src/buses/saga-drain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,iBAAiB,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAC7C,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAgBlB"}

package/dist/buses/saga-drain.js

@@ -0,0 +1,34 @@
+/**
+ * Waits until a mutable set of saga tasks becomes quiescent within one deadline.
+ *
+ * @param pendingDispatches Live saga task set owned by the lifecycle service.
+ * @param timeoutMs Maximum drain duration in milliseconds.
+ * @returns `true` when all current and late-added tasks settle before the deadline.
+ */
+export async function drainPendingSagaDispatches(pendingDispatches, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (pendingDispatches.size > 0) {
+    const remainingTimeoutMs = deadline - Date.now();
+    if (remainingTimeoutMs <= 0) {
+      return false;
+    }
+    if (!(await awaitSagaTasks([...pendingDispatches], remainingTimeoutMs))) {
+      return false;
+    }
+  }
+  return true;
+}
+async function awaitSagaTasks(activeWork, timeoutMs) {
+  let timeoutId;
+  const timeout = new Promise(resolve => {
+    timeoutId = setTimeout(() => resolve(false), timeoutMs);
+  });
+  const drain = Promise.allSettled(activeWork).then(() => true);
+  try {
+    return await Promise.race([drain, timeout]);
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+}

package/dist/buses/saga-topology.d.ts

@@ -0,0 +1,18 @@
+import type { CqrsDispatchContext, SagaDescriptor } from '../types.js';
+import type { SagaContinuationScope } from './saga-continuation.js';
+/** Result of entering one guarded saga route. */
+export interface SagaTopologyEntry {
+    readonly continuationScope: SagaContinuationScope;
+    readonly context: CqrsDispatchContext;
+    readonly ownsContinuationScope: boolean;
+    readonly reentrantToken: boolean;
+}
+/**
+ * Validates and enters one saga route using private immutable context state.
+ *
+ * @param context Opaque context passed through the active CQRS pipeline.
+ * @param descriptor Saga route selected for the current event.
+ * @returns The next opaque context.
+ */
+export declare function enterSagaTopology(context: CqrsDispatchContext | undefined, descriptor: SagaDescriptor): SagaTopologyEntry;
+//# sourceMappingURL=saga-topology.d.ts.map

package/dist/buses/saga-topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga-topology.d.ts","sourceRoot":"","sources":["../../src/buses/saga-topology.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAIpE,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,iBAAiB,EAAE,qBAAqB,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,GAAG,SAAS,EACxC,UAAU,EAAE,cAAc,GACzB,iBAAiB,CAuCnB"}

package/dist/buses/saga-topology.js

@@ -0,0 +1,46 @@
+import { createInternalCqrsDispatchContext, getInternalCqrsDispatchContextState } from '../dispatch-context.js';
+import { SagaTopologyError } from '../errors.js';
+const MAX_NESTED_SAGA_DEPTH = 32;
+
+/** Result of entering one guarded saga route. */
+
+/**
+ * Validates and enters one saga route using private immutable context state.
+ *
+ * @param context Opaque context passed through the active CQRS pipeline.
+ * @param descriptor Saga route selected for the current event.
+ * @returns The next opaque context.
+ */
+export function enterSagaTopology(context, descriptor) {
+  const internalState = getInternalCqrsDispatchContextState(context);
+  const activeTopology = internalState?.sagaTopology;
+  const routeLabel = `${descriptor.targetType.name}(${descriptor.eventType.name})`;
+  const reenteredRoute = activeTopology?.activeRoutes.some(route => route.token === descriptor.token && route.eventType === descriptor.eventType);
+  const reentrantToken = activeTopology?.activeRoutes.some(route => route.token === descriptor.token) ?? false;
+  if (reenteredRoute) {
+    throw new SagaTopologyError(`Saga ${descriptor.targetType.name} re-entered an unsafe cycle while handling ${descriptor.eventType.name}. ` + `Active saga path: ${[...(activeTopology?.path ?? []), routeLabel].join(' -> ')}.`);
+  }
+  if ((activeTopology?.depth ?? 0) >= MAX_NESTED_SAGA_DEPTH) {
+    throw new SagaTopologyError(`Saga ${descriptor.targetType.name} exceeded the maximum nested saga depth of ${MAX_NESTED_SAGA_DEPTH} while handling ${descriptor.eventType.name}. ` + 'Keep in-process saga graphs acyclic and externally bounded.');
+  }
+  const continuationScope = internalState?.sagaContinuationScope ?? {
+    queue: []
+  };
+  return {
+    continuationScope,
+    context: createInternalCqrsDispatchContext({
+      publishDrainToken: internalState?.publishDrainToken,
+      sagaContinuationScope: continuationScope,
+      sagaTopology: {
+        activeRoutes: [...(activeTopology?.activeRoutes ?? []), {
+          eventType: descriptor.eventType,
+          token: descriptor.token
+        }],
+        depth: (activeTopology?.depth ?? 0) + 1,
+        path: [...(activeTopology?.path ?? []), routeLabel]
+      }
+    }),
+    ownsContinuationScope: internalState?.sagaContinuationScope === undefined,
+    reentrantToken
+  };
+}

package/dist/buses/shutdown-deadline.d.ts

@@ -0,0 +1,23 @@
+/** Coordinates one absolute CQRS shutdown deadline across lifecycle drain hooks. */
+export declare class CqrsShutdownDeadline {
+    private deadlineMs;
+    /**
+     * Starts the shared deadline once.
+     *
+     * @param timeoutMs Configured CQRS shutdown drain duration.
+     */
+    start(timeoutMs: number): void;
+    /**
+     * Returns the remaining duration from the shared deadline.
+     *
+     * @returns Remaining duration in milliseconds, or `undefined` before shutdown starts.
+     */
+    remainingTimeoutMs(): number | undefined;
+    /**
+     * Returns the absolute timestamp for the shared deadline.
+     *
+     * @returns Absolute deadline in milliseconds, or `undefined` before shutdown starts.
+     */
+    deadlineAtMs(): number | undefined;
+}
+//# sourceMappingURL=shutdown-deadline.d.ts.map

package/dist/buses/shutdown-deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown-deadline.d.ts","sourceRoot":"","sources":["../../src/buses/shutdown-deadline.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,UAAU,CAAqB;IAEvC;;;;OAIG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B;;;;OAIG;IACH,kBAAkB,IAAI,MAAM,GAAG,SAAS;IAIxC;;;;OAIG;IACH,YAAY,IAAI,MAAM,GAAG,SAAS;CAGnC"}