@fluojs/cqrs 1.1.1 → 2.0.0

package/dist/buses/saga-bus.js

@@ -5,14 +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;
+
+/** 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;
@@ -29,13 +33,13 @@ function toErrorMessage(error) {
 /**
  * Runtime saga coordinator that discovers `@Saga()` providers and serializes execution per saga token.
  *
- * The service prevents re-entrant dispatch loops within the same async context and waits for
+ * The service prevents re-entrant dispatch loops within the same explicit dispatch context and waits for
  * in-flight saga chains during shutdown so lifecycle guarantees remain predictable.
  */
 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;
@@ -44,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';
@@ -59,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();
@@ -90,7 +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) {
+  async dispatch(event, context, drainAuthorization) {
+    this.assertAcceptingNewWork(drainAuthorization);
     await this.ensureDiscovered();
     const descriptors = this.matchSagaDescriptors(event);
     if (descriptors.length === 0) {
@@ -98,6 +109,16 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     }
     await Promise.all(descriptors.map(descriptor => this.dispatchWithOrdering(descriptor, event, context)));
   }
+  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()) {
@@ -108,22 +129,14 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     return descriptors;
   }
   async dispatchWithOrdering(descriptor, event, activeContext) {
-    const routeLabel = `${descriptor.targetType.name}(${descriptor.eventType.name})`;
-    const isActiveRoute = activeContext?.activeRoutes.some(route => route.token === descriptor.token && route.eventType === descriptor.eventType);
-    const isActiveToken = activeContext?.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: ${[...(activeContext?.path ?? []), routeLabel].join(' -> ')}.`);
-    }
-    if ((activeContext?.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(activeContext, 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(activeContext, descriptor, routeLabel));
+      await this.invokeSaga(descriptor, event, topology.context);
     });
     this.executionChains.set(descriptor.token, current.catch(() => undefined));
     this.pendingDispatches.add(current);
@@ -134,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;
@@ -166,16 +165,6 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
     }
     return Math.floor(timeoutMs);
   }
-  createDispatchContext(activeContext, descriptor, routeLabel) {
-    return {
-      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)) {
@@ -216,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"}

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,15 @@
+import type { CqrsDispatchContext, SagaDescriptor } from '../types.js';
+/** Result of entering one guarded saga route. */
+export interface SagaTopologyEntry {
+    readonly context: CqrsDispatchContext;
+    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 and whether the same provider token is already active.
+ */
+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;AAIvE,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,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,CAiCnB"}

package/dist/buses/saga-topology.js

@@ -0,0 +1,39 @@
+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 and whether the same provider token is already active.
+ */
+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);
+  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.');
+  }
+  return {
+    context: createInternalCqrsDispatchContext({
+      publishDrainToken: internalState?.publishDrainToken,
+      sagaTopology: {
+        activeRoutes: [...(activeTopology?.activeRoutes ?? []), {
+          eventType: descriptor.eventType,
+          token: descriptor.token
+        }],
+        depth: (activeTopology?.depth ?? 0) + 1,
+        path: [...(activeTopology?.path ?? []), routeLabel]
+      }
+    }),
+    reentrantToken: activeTopology?.activeRoutes.some(route => route.token === descriptor.token) ?? false
+  };
+}

package/dist/discovery.d.ts

@@ -22,10 +22,26 @@ export interface DiscoveryCandidate {
 export declare function createDuplicateHandlerMessage(kind: 'command' | 'query' | 'event', messageType: Function, first: {
     moduleName: string;
     targetType: Function;
+    token: Token;
 }, second: {
     moduleName: string;
     targetType: Function;
+    token: Token;
 }): string;
+/**
+ * Checks whether two discovered handler candidates refer to the same provider registration.
+ *
+ * @param first The first handler registration.
+ * @param second The second handler registration.
+ * @returns Whether both target type and provider token match.
+ */
+export declare function isSameHandlerRegistration(first: {
+    targetType: Function;
+    token: Token;
+}, second: {
+    targetType: Function;
+    token: Token;
+}): boolean;
 /**
  * Represents the cqrs bus base.
  */

package/dist/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;IAC7C,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;CACd;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,EACnC,WAAW,EAAE,QAAQ,EACrB,KAAK,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,QAAQ,CAAA;CAAE,EACnD,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,QAAQ,CAAA;CAAE,GACnD,MAAM,CAER;AAED;;GAEG;AACH,8BAAsB,WAAW;IAI7B,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS;IAC9C,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE;IAC7D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB;IAL9C,SAAS,CAAC,QAAQ,CAAC,gBAAgB,+BAAsC;gBAGpD,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB;IAG9C,SAAS,CAAC,mBAAmB,IAAI,kBAAkB,EAAE;cAsCrC,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;cAgBnD,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;CAiBvE"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;IAC7C,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;CACd;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,EACnC,WAAW,EAAE,QAAQ,EACrB,KAAK,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,EACjE,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACjE,MAAM,CAER;AAMD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE;IAAE,UAAU,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,EAC7C,MAAM,EAAE;IAAE,UAAU,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC7C,OAAO,CAET;AAED;;GAEG;AACH,8BAAsB,WAAW;IAI7B,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS;IAC9C,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE;IAC7D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB;IAL9C,SAAS,CAAC,QAAQ,CAAC,gBAAgB,+BAAsC;gBAGpD,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB;IAG9C,SAAS,CAAC,mBAAmB,IAAI,kBAAkB,EAAE;cA6BrC,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;cAgBnD,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;CAiBvE"}

package/dist/discovery.js

@@ -1,3 +1,4 @@
+import { formatTokenName } from '@fluojs/core';
 import { getClassDiMetadata } from '@fluojs/core/internal';
 
 /**
@@ -27,7 +28,21 @@ function isClassProvider(provider) {
  * @returns The create duplicate handler message result.
  */
 export function createDuplicateHandlerMessage(kind, messageType, first, second) {
-  return `Duplicate ${kind} handler for ${messageType.name} was discovered in ${first.moduleName}.${first.targetType.name} and ${second.moduleName}.${second.targetType.name}.`;
+  return `Duplicate ${kind} handler for ${messageType.name} was discovered in ${describeHandlerRegistration(first)} and ${describeHandlerRegistration(second)}.`;
+}
+function describeHandlerRegistration(registration) {
+  return `${registration.moduleName}.${registration.targetType.name} [token: ${formatTokenName(registration.token)}]`;
+}
+
+/**
+ * Checks whether two discovered handler candidates refer to the same provider registration.
+ *
+ * @param first The first handler registration.
+ * @param second The second handler registration.
+ * @returns Whether both target type and provider token match.
+ */
+export function isSameHandlerRegistration(first, second) {
+  return first.targetType === second.targetType && first.token === second.token;
 }
 
 /**
@@ -62,14 +77,6 @@ export class CqrsBusBase {
           });
         }
       }
-      for (const controller of compiledModule.definition.controllers ?? []) {
-        candidates.push({
-          moduleName: compiledModule.type.name,
-          scope: scopeFromProvider(controller),
-          targetType: controller,
-          token: controller
-        });
-      }
     }
     return candidates;
   }

package/dist/dispatch-context.d.ts

@@ -0,0 +1,33 @@
+import type { Token } from '@fluojs/core';
+import type { CqrsDispatchContext, CqrsEventType } from './types.js';
+/** One active saga route retained in private CQRS dispatch state. */
+export interface CqrsDispatchRoute {
+    readonly eventType: CqrsEventType;
+    readonly token: Token;
+}
+/** Private saga topology state associated with an opaque dispatch context. */
+export interface CqrsSagaTopologyState {
+    readonly activeRoutes: readonly CqrsDispatchRoute[];
+    readonly depth: number;
+    readonly path: readonly string[];
+}
+/** Private state carried by an internally created dispatch context. */
+export interface InternalCqrsDispatchContextState {
+    readonly publishDrainToken: symbol | undefined;
+    readonly sagaTopology: CqrsSagaTopologyState | undefined;
+}
+/**
+ * Creates an opaque immutable dispatch context and retains its state in a private weak map.
+ *
+ * @param state Internal publish-drain and saga-topology state.
+ * @returns A frozen fieldless context safe to pass through application handlers.
+ */
+export declare function createInternalCqrsDispatchContext(state: InternalCqrsDispatchContextState): CqrsDispatchContext;
+/**
+ * Reads private state only for context values created by CQRS internals.
+ *
+ * @param context Optional public dispatch context received from a handler or saga.
+ * @returns The immutable internal state, or `undefined` for caller-created values.
+ */
+export declare function getInternalCqrsDispatchContextState(context: CqrsDispatchContext | undefined): InternalCqrsDispatchContextState | undefined;
+//# sourceMappingURL=dispatch-context.d.ts.map

package/dist/dispatch-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-context.d.ts","sourceRoot":"","sources":["../src/dispatch-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAErE,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,uEAAuE;AACvE,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,YAAY,EAAE,qBAAqB,GAAG,SAAS,CAAC;CAC1D;AAcD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,gCAAgC,GAAG,mBAAmB,CAU9G;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,mBAAmB,GAAG,SAAS,GACvC,gCAAgC,GAAG,SAAS,CAE9C"}

package/dist/dispatch-context.js

@@ -0,0 +1,42 @@
+/** One active saga route retained in private CQRS dispatch state. */
+
+/** Private saga topology state associated with an opaque dispatch context. */
+
+/** Private state carried by an internally created dispatch context. */
+
+const internalContextStates = new WeakMap();
+function freezeSagaTopology(state) {
+  return Object.freeze({
+    activeRoutes: Object.freeze(state.activeRoutes.map(route => Object.freeze({
+      eventType: route.eventType,
+      token: route.token
+    }))),
+    depth: state.depth,
+    path: Object.freeze([...state.path])
+  });
+}
+
+/**
+ * Creates an opaque immutable dispatch context and retains its state in a private weak map.
+ *
+ * @param state Internal publish-drain and saga-topology state.
+ * @returns A frozen fieldless context safe to pass through application handlers.
+ */
+export function createInternalCqrsDispatchContext(state) {
+  const context = Object.freeze({});
+  internalContextStates.set(context, Object.freeze({
+    publishDrainToken: state.publishDrainToken,
+    sagaTopology: state.sagaTopology ? freezeSagaTopology(state.sagaTopology) : undefined
+  }));
+  return context;
+}
+
+/**
+ * Reads private state only for context values created by CQRS internals.
+ *
+ * @param context Optional public dispatch context received from a handler or saga.
+ * @returns The immutable internal state, or `undefined` for caller-created values.
+ */
+export function getInternalCqrsDispatchContextState(context) {
+  return context ? internalContextStates.get(context) : undefined;
+}

package/dist/module.d.ts

@@ -1,4 +1,3 @@
-import type { Provider } from '@fluojs/di';
 import { type EventBusModuleOptions } from '@fluojs/event-bus';
 import { type ModuleType } from '@fluojs/runtime';
 import type { CommandHandlerClass, EventHandlerClass, QueryHandlerClass, SagaClass } from './types.js';
@@ -16,13 +15,6 @@ export interface CqrsModuleOptions {
         drainTimeoutMs?: number;
     };
 }
-/**
- * Creates the providers required for CQRS buses, compatibility aliases, and optional handler registration.
- *
- * @param options CQRS module options including eager handler classes and event-bus configuration.
- * @returns Providers for the command, query, event, and saga runtimes plus compatibility tokens.
- */
-export declare function createCqrsProviders(options?: CqrsModuleOptions): Provider[];
 /** Runtime module entrypoint for CQRS bus registration and handler discovery. */
 export declare class CqrsModule {
     /**

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAOhE,OAAO,KAAK,EACV,mBAAmB,EAEnB,iBAAiB,EAIjB,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B,8GAA8G;IAC9G,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AA0CD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,iBAAsB,GAAG,QAAQ,EAAE,CA8C/E;AAED,iFAAiF;AACjF,qBAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU;CAiB5D"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAOhE,OAAO,KAAK,EACV,mBAAmB,EAEnB,iBAAiB,EAIjB,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B,8GAA8G;IAC9G,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAyGD,iFAAiF;AACjF,qBAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU;CAiB5D"}

package/dist/module.js

@@ -24,6 +24,13 @@ function collectOptionHandlerProviders(options) {
   }
   return providers;
 }
+function resolveDelegatedEventBusOptions(options) {
+  const eventBusOptions = options.eventBus ?? {};
+  return {
+    ...eventBusOptions,
+    global: eventBusOptions.global ?? options.global ?? true
+  };
+}
 function assertCommandBusService(service) {
   if (!(service instanceof CommandBusLifecycleService)) {
     throw new TypeError('CQRS command bus alias expected CommandBusLifecycleService.');
@@ -46,7 +53,7 @@ function assertCqrsEventBusService(service) {
  * @param options CQRS module options including eager handler classes and event-bus configuration.
  * @returns Providers for the command, query, event, and saga runtimes plus compatibility tokens.
  */
-export function createCqrsProviders(options = {}) {
+function createCqrsProviders(options = {}) {
   return [{
     provide: CQRS_MODULE_OPTIONS,
     useValue: options
@@ -94,7 +101,7 @@ export class CqrsModule {
     return defineModule(CqrsModuleDefinition, {
       exports: [CommandBusLifecycleService, QueryBusLifecycleService, CqrsEventBusService, COMMAND_BUS, QUERY_BUS, EVENT_BUS],
       global: options.global ?? true,
-      imports: [EventBusModule.forRoot(options.eventBus)],
+      imports: [EventBusModule.forRoot(resolveDelegatedEventBusOptions(options))],
       providers: createCqrsProviders(options)
     });
   }

package/dist/test-setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=test-setup.d.ts.map

package/dist/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":""}

package/dist/test-setup.js

@@ -0,0 +1,4 @@
+import { afterEach, vi } from 'vitest';
+afterEach(() => {
+  vi.useRealTimers();
+});

package/dist/types.d.ts

@@ -56,19 +56,12 @@ export interface ISaga<TEvent extends IEvent = IEvent> {
 /**
  * Opaque dispatch context used to preserve saga topology guards across nested CQRS calls.
  *
- * Pass this value unchanged from handlers and sagas into nested `execute(...)`, `publish(...)`,
- * or `publishAll(...)` calls. Application code should not inspect or construct it directly.
+ * CQRS passes this value to command handlers, query handlers, event handlers, and sagas when a
+ * nested dispatch chain is active. Application code should pass the value through unchanged to
+ * nested `execute(...)`, `publish(...)`, or `publishAll(...)` calls. The context intentionally
+ * exposes no public topology fields, and caller-shaped objects cannot supply trusted runtime state.
  */
 export interface CqrsDispatchContext {
-    /** Saga routes currently active in the in-process CQRS dispatch chain. */
-    readonly activeRoutes: readonly Readonly<{
-        eventType: CqrsEventType;
-        token: Token;
-    }>[];
-    /** Current nested saga depth for in-process topology guarding. */
-    readonly depth: number;
-    /** Human-readable saga route labels used when reporting topology failures. */
-    readonly path: readonly string[];
 }
 /** Constructor type used to identify a command message class. */
 export interface CommandType<TCommand extends ICommand = ICommand> {