@fluojs/cqrs 1.1.2 → 2.0.0

package/dist/buses/publish-drain-tracker.d.ts

@@ -0,0 +1,38 @@
+import type { ApplicationLogger } from '@fluojs/runtime';
+/** Tracks active CQRS publish pipelines and their shutdown-drain capabilities. */
+export declare class CqrsPublishDrainTracker {
+    private readonly logger;
+    private readonly activePipelines;
+    private readonly activeTokens;
+    private drainTimeouts;
+    constructor(logger: ApplicationLogger);
+    /** Current count of bounded shutdown-drain timeouts. */
+    get shutdownDrainTimeouts(): number;
+    /** Whether at least one publish pipeline remains active. */
+    get hasActivePipelines(): boolean;
+    /**
+     * Returns whether a private publish capability belongs to active work.
+     *
+     * @param token Private publish-drain token from an opaque context.
+     * @returns `true` while at least one associated pipeline is active.
+     */
+    isActive(token: symbol): boolean;
+    /**
+     * Tracks one publish pipeline and releases its private capability on settlement.
+     *
+     * @param pipeline Publish work to track.
+     * @param token Private drain token associated with the pipeline.
+     * @returns A promise that mirrors the tracked pipeline.
+     */
+    track(pipeline: Promise<void>, token: symbol): Promise<void>;
+    /**
+     * Waits for publish quiescence within the configured shutdown bound.
+     *
+     * @param timeoutMs Maximum drain duration in milliseconds.
+     * @returns A promise that resolves after quiescence or timeout reporting.
+     */
+    drain(timeoutMs: number): Promise<void>;
+    private awaitDrain;
+    private waitForQuiescence;
+}
+//# sourceMappingURL=publish-drain-tracker.d.ts.map

package/dist/buses/publish-drain-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-drain-tracker.d.ts","sourceRoot":"","sources":["../../src/buses/publish-drain-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,kFAAkF;AAClF,qBAAa,uBAAuB;IAKtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4B;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,aAAa,CAAK;gBAEG,MAAM,EAAE,iBAAiB;IAEtD,wDAAwD;IACxD,IAAI,qBAAqB,IAAI,MAAM,CAElC;IAED,4DAA4D;IAC5D,IAAI,kBAAkB,IAAI,OAAO,CAEhC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;;OAMG;IACG,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBlE;;;;;OAKG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAc/B,UAAU;YAgBV,iBAAiB;CAKhC"}

package/dist/buses/publish-drain-tracker.js

@@ -0,0 +1,86 @@
+/** Tracks active CQRS publish pipelines and their shutdown-drain capabilities. */
+export class CqrsPublishDrainTracker {
+  activePipelines = new Set();
+  activeTokens = new Map();
+  drainTimeouts = 0;
+  constructor(logger) {
+    this.logger = logger;
+  }
+
+  /** Current count of bounded shutdown-drain timeouts. */
+  get shutdownDrainTimeouts() {
+    return this.drainTimeouts;
+  }
+
+  /** Whether at least one publish pipeline remains active. */
+  get hasActivePipelines() {
+    return this.activePipelines.size > 0;
+  }
+
+  /**
+   * Returns whether a private publish capability belongs to active work.
+   *
+   * @param token Private publish-drain token from an opaque context.
+   * @returns `true` while at least one associated pipeline is active.
+   */
+  isActive(token) {
+    return (this.activeTokens.get(token) ?? 0) > 0;
+  }
+
+  /**
+   * Tracks one publish pipeline and releases its private capability on settlement.
+   *
+   * @param pipeline Publish work to track.
+   * @param token Private drain token associated with the pipeline.
+   * @returns A promise that mirrors the tracked pipeline.
+   */
+  async track(pipeline, token) {
+    this.activePipelines.add(pipeline);
+    this.activeTokens.set(token, (this.activeTokens.get(token) ?? 0) + 1);
+    try {
+      await pipeline;
+    } finally {
+      this.activePipelines.delete(pipeline);
+      const activeCount = this.activeTokens.get(token) ?? 0;
+      if (activeCount <= 1) {
+        this.activeTokens.delete(token);
+      } else {
+        this.activeTokens.set(token, activeCount - 1);
+      }
+    }
+  }
+
+  /**
+   * Waits for publish quiescence within the configured shutdown bound.
+   *
+   * @param timeoutMs Maximum drain duration in milliseconds.
+   * @returns A promise that resolves after quiescence or timeout reporting.
+   */
+  async drain(timeoutMs) {
+    const drained = await this.awaitDrain(timeoutMs);
+    if (drained) {
+      return;
+    }
+    this.drainTimeouts += 1;
+    this.logger.warn(`CQRS event shutdown drain exceeded ${String(timeoutMs)}ms with ${String(this.activePipelines.size)} active publish pipeline(s); continuing shutdown.`, 'CqrsEventBusService');
+  }
+  async awaitDrain(timeoutMs) {
+    let timeoutId;
+    const timeout = new Promise(resolve => {
+      timeoutId = setTimeout(() => resolve(false), timeoutMs);
+    });
+    const drain = this.waitForQuiescence().then(() => true);
+    try {
+      return await Promise.race([drain, timeout]);
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+  async waitForQuiescence() {
+    while (this.activePipelines.size > 0) {
+      await Promise.allSettled([...this.activePipelines]);
+    }
+  }
+}

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

@@ -1,4 +1,5 @@
-import type { OnApplicationBootstrap } from '@fluojs/runtime';
+import type { Container } from '@fluojs/di';
+import type { ApplicationLogger, CompiledModule, OnApplicationBootstrap, OnApplicationShutdown, RuntimeCleanupRegistration } from '@fluojs/runtime';
 import { CqrsBusBase } from '../discovery.js';
 import type { CqrsDispatchContext, IQuery, QueryBus } from '../types.js';
 /**
@@ -7,11 +8,15 @@ import type { CqrsDispatchContext, IQuery, QueryBus } from '../types.js';
  * The query bus resolves singleton handlers only, warns on unsupported scopes,
  * and preserves the one-query-to-one-handler contract used by the CQRS surface.
  */
-export declare class QueryBusLifecycleService extends CqrsBusBase implements QueryBus, OnApplicationBootstrap {
+export declare class QueryBusLifecycleService extends CqrsBusBase implements QueryBus, OnApplicationBootstrap, OnApplicationShutdown {
     private descriptors;
     private discoveryPromise;
     private discovered;
+    private lifecycleState;
+    private unregisterShutdownStartCleanup;
+    constructor(runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, registerRuntimeCleanup?: RuntimeCleanupRegistration);
     onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
     /**
      * Executes one query by dispatching it to the discovered handler for its constructor.
      *
@@ -23,6 +28,8 @@ export declare class QueryBusLifecycleService extends CqrsBusBase implements Que
      * @throws {InvariantError} When the resolved provider does not implement `execute(query)`.
      */
     execute<TQuery extends IQuery<TResult>, TResult = unknown>(query: TQuery, context?: CqrsDispatchContext): Promise<TResult>;
+    private assertAcceptingNewWork;
+    private markApplicationShutdownStarted;
     private ensureDiscovered;
     private discoverHandlers;
     private discoverQueryDescriptors;

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

@@ -1 +1 @@
-{"version":3,"file":"query-bus.d.ts","sourceRoot":"","sources":["../../src/buses/query-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAiC,MAAM,iBAAiB,CAAC;AAG7E,OAAO,KAAK,EACV,mBAAmB,EACnB,MAAM,EAEN,QAAQ,EAGT,MAAM,aAAa,CAAC;AAUrB;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,QAAQ,EAAE,sBAAsB;IACnG,OAAO,CAAC,WAAW,CAAgD;IACnE,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAErB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;;;;OASG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;YAmBlH,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CAmDjC"}
+{"version":3,"file":"query-bus.d.ts","sourceRoot":"","sources":["../../src/buses/query-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAA4D,MAAM,iBAAiB,CAAC;AAGxG,OAAO,KAAK,EACV,mBAAmB,EACnB,MAAM,EAEN,QAAQ,EAGT,MAAM,aAAa,CAAC;AAUrB;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,QAAQ,EAAE,sBAAsB,EAAE,qBAAqB;IAC1H,OAAO,CAAC,WAAW,CAAgD;IACnE,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAsF;IAC5G,OAAO,CAAC,8BAA8B,CAA2B;gBAG/D,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,sBAAsB,GAAE,0BAAkD;IAStE,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5C;;;;;;;;;OASG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBhI,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,8BAA8B;YAMxB,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CA2CjC"}

package/dist/buses/query-bus.js

@@ -5,8 +5,8 @@ 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 { Inject, InvariantError } from '@fluojs/core';
-import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
-import { CqrsBusBase, createDuplicateHandlerMessage } from '../discovery.js';
+import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CLEANUP_REGISTRATION, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { CqrsBusBase, createDuplicateHandlerMessage, isSameHandlerRegistration } from '../discovery.js';
 import { DuplicateQueryHandlerError, QueryHandlerNotFoundException } from '../errors.js';
 import { getQueryHandlerMetadata } from '../metadata.js';
 function isQueryHandler(value) {
@@ -25,13 +25,38 @@ function isQueryHandler(value) {
 let _QueryBusLifecycleSer;
 class QueryBusLifecycleService extends CqrsBusBase {
   static {
-    [_QueryBusLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER)], [], 0, void 0, CqrsBusBase).c;
+    [_QueryBusLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, RUNTIME_CLEANUP_REGISTRATION)], [], 0, void 0, CqrsBusBase).c;
   }
   descriptors = new Map();
   discoveryPromise;
   discovered = false;
+  lifecycleState = 'created';
+  unregisterShutdownStartCleanup;
+  constructor(runtimeContainer, compiledModules, logger, registerRuntimeCleanup = () => () => undefined) {
+    super(runtimeContainer, compiledModules, logger);
+    this.unregisterShutdownStartCleanup = registerRuntimeCleanup(() => {
+      this.markApplicationShutdownStarted();
+    });
+  }
   async onApplicationBootstrap() {
-    await this.ensureDiscovered();
+    this.lifecycleState = 'discovering';
+    try {
+      await this.ensureDiscovered();
+      this.lifecycleState = 'ready';
+    } catch (error) {
+      this.lifecycleState = 'failed';
+      throw error;
+    }
+  }
+  async onApplicationShutdown() {
+    this.markApplicationShutdownStarted();
+    this.unregisterShutdownStartCleanup?.();
+    this.unregisterShutdownStartCleanup = undefined;
+    this.descriptors.clear();
+    this.handlerInstances.clear();
+    this.discovered = false;
+    this.discoveryPromise = undefined;
+    this.lifecycleState = 'stopped';
   }
 
   /**
@@ -45,6 +70,7 @@ class QueryBusLifecycleService extends CqrsBusBase {
    * @throws {InvariantError} When the resolved provider does not implement `execute(query)`.
    */
   async execute(query, context) {
+    this.assertAcceptingNewWork('execute');
     await this.ensureDiscovered();
     const queryType = query.constructor;
     const descriptor = this.descriptors.get(queryType);
@@ -57,6 +83,16 @@ class QueryBusLifecycleService extends CqrsBusBase {
     }
     return await instance.execute(query, context);
   }
+  assertAcceptingNewWork(operation) {
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+      throw new InvariantError(`CQRS query bus cannot ${operation} after shutdown has started.`);
+    }
+  }
+  markApplicationShutdownStarted() {
+    if (this.lifecycleState !== 'stopped') {
+      this.lifecycleState = 'stopping';
+    }
+  }
   async ensureDiscovered() {
     if (this.discovered) {
       return;
@@ -82,7 +118,6 @@ class QueryBusLifecycleService extends CqrsBusBase {
   }
   discoverQueryDescriptors() {
     const descriptors = new Map();
-    const seenByTarget = new WeakMap();
     for (const candidate of this.discoveryCandidates()) {
       const metadata = getQueryHandlerMetadata(candidate.targetType);
       if (!metadata) {
@@ -92,27 +127,22 @@ class QueryBusLifecycleService extends CqrsBusBase {
         this.logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @QueryHandler() but is registered with ${candidate.scope} scope. Query handlers are registered only for singleton providers.`, 'QueryBusLifecycleService');
         continue;
       }
-      const seenQueryTypes = seenByTarget.get(candidate.targetType) ?? new Set();
-      if (seenQueryTypes.has(metadata.queryType)) {
-        continue;
-      }
-      seenQueryTypes.add(metadata.queryType);
-      seenByTarget.set(candidate.targetType, seenQueryTypes);
       const existing = descriptors.get(metadata.queryType);
-      if (existing && existing.targetType !== candidate.targetType) {
-        throw new DuplicateQueryHandlerError(createDuplicateHandlerMessage('query', metadata.queryType, existing, {
-          moduleName: candidate.moduleName,
-          targetType: candidate.targetType
-        }));
-      }
-      if (!existing) {
-        descriptors.set(metadata.queryType, {
-          moduleName: candidate.moduleName,
-          queryType: metadata.queryType,
-          targetType: candidate.targetType,
-          token: candidate.token
-        });
+      const nextDescriptor = {
+        moduleName: candidate.moduleName,
+        targetType: candidate.targetType,
+        token: candidate.token
+      };
+      if (existing) {
+        if (isSameHandlerRegistration(existing, nextDescriptor)) {
+          continue;
+        }
+        throw new DuplicateQueryHandlerError(createDuplicateHandlerMessage('query', metadata.queryType, existing, nextDescriptor));
       }
+      descriptors.set(metadata.queryType, {
+        queryType: metadata.queryType,
+        ...nextDescriptor
+      });
     }
     return descriptors;
   }

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

@@ -1,10 +1,9 @@
-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;
-}
+/** 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.
  *
@@ -20,7 +19,8 @@ export declare class CqrsSagaLifecycleService extends CqrsBusBase implements OnA
     private lifecycleState;
     private readonly pendingDispatches;
     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);
     onApplicationBootstrap(): Promise<void>;
     onApplicationShutdown(): Promise<void>;
     /**
@@ -41,18 +41,17 @@ 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, drainAuthorization?: typeof CQRS_SAGA_DRAIN_AUTHORIZATION): Promise<void>;
     private assertAcceptingNewWork;
+    private markApplicationShutdownStarted;
     private matchSagaDescriptors;
     private dispatchWithOrdering;
     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;AAOrG,yFAAyF;AACzF,eAAO,MAAM,6BAA6B,EAAE,OAAO,MAAmD,CAAC;AAkBvG;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,sBAAsB,EAAE,qBAAqB;IAc9G,OAAO,CAAC,QAAQ,CAAC,aAAa;IAbhC,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;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;IAStE,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5C;;;;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,EAClC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,mBAAmB,EAC7B,kBAAkB,CAAC,EAAE,OAAO,6BAA6B,GACxD,OAAO,CAAC,IAAI,CAAC;IAahB,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,8BAA8B;IAMtC,OAAO,CAAC,oBAAoB;YAYd,oBAAoB;YAuBpB,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,18 @@ 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 { discoverSagaDescriptors } from './saga-discovery.js';
+import { drainPendingSagaDispatches } from './saga-drain.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 +29,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 +39,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)], [], 0, void 0, CqrsBusBase).c;
   }
   descriptorsByEvent = new Map();
   discoveryPromise;
@@ -51,9 +48,13 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
   lifecycleState = 'created';
   pendingDispatches = new Set();
   shutdownDrainTimeouts = 0;
-  constructor(runtimeContainer, compiledModules, logger, moduleOptions = {}) {
+  unregisterShutdownStartCleanup;
+  constructor(runtimeContainer, compiledModules, logger, moduleOptions = {}, registerRuntimeCleanup = () => () => undefined) {
     super(runtimeContainer, compiledModules, logger);
     this.moduleOptions = moduleOptions;
+    this.unregisterShutdownStartCleanup = registerRuntimeCleanup(() => {
+      this.markApplicationShutdownStarted();
+    });
   }
   async onApplicationBootstrap() {
     this.lifecycleState = 'discovering';
@@ -66,7 +67,9 @@ 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();
@@ -97,8 +100,8 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
    * @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.
    */
-  async dispatch(event, context, options = {}) {
-    this.assertAcceptingNewWork(options);
+  async dispatch(event, context, drainAuthorization) {
+    this.assertAcceptingNewWork(drainAuthorization);
     await this.ensureDiscovered();
     const descriptors = this.matchSagaDescriptors(event);
     if (descriptors.length === 0) {
@@ -106,14 +109,16 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     }
     await Promise.all(descriptors.map(descriptor => this.dispatchWithOrdering(descriptor, event, context)));
   }
-  assertAcceptingNewWork(options) {
-    if (options.allowDuringShutdown) {
-      return;
-    }
-    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+  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() {
+    if (this.lifecycleState !== 'stopped') {
+      this.lifecycleState = 'stopping';
+    }
+  }
   matchSagaDescriptors(event) {
     const descriptors = [];
     for (const [eventType, eventDescriptors] of this.descriptorsByEvent.entries()) {
@@ -124,23 +129,14 @@ 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));
+    const topology = enterSagaTopology(activeContext, descriptor);
+    if (topology.reentrantToken) {
+      await this.invokeSaga(descriptor, event, topology.context);
       return;
     }
     const previous = this.executionChains.get(descriptor.token) ?? Promise.resolve();
     const current = previous.then(async () => {
-      await this.invokeSaga(descriptor, event, this.createDispatchContext(activeState, descriptor, routeLabel));
+      await this.invokeSaga(descriptor, event, topology.context);
     });
     this.executionChains.set(descriptor.token, current.catch(() => undefined));
     this.pendingDispatches.add(current);
@@ -151,30 +147,16 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     }
   }
   async drainActiveSagaWork() {
-    const activeWork = [...this.pendingDispatches, ...this.executionChains.values()];
-    if (activeWork.length === 0) {
-      return;
-    }
     const timeoutMs = this.resolveShutdownDrainTimeoutMs();
-    const drained = await this.awaitShutdownDrain(activeWork, timeoutMs);
+    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 +165,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 +205,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-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"}