@fluojs/cqrs 1.1.2 → 3.0.0

package/dist/buses/event-bus.js

@@ -5,14 +5,19 @@ 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 { EVENT_BUS as FLUO_EVENT_BUS } from '@fluojs/event-bus';
-import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { EventBusLifecycleService, EVENT_BUS as FLUO_EVENT_BUS } from '@fluojs/event-bus';
+import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CLEANUP_REGISTRATION, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
 import { CqrsBusBase } from '../discovery.js';
+import { createInternalCqrsDispatchContext, getInternalCqrsDispatchContextState } from '../dispatch-context.js';
 import { createIsolatedEvent } from '../event-clone.js';
-import { getEventHandlerMetadata } from '../metadata.js';
 import { createCqrsPlatformStatusSnapshot } from '../status.js';
 import { CQRS_MODULE_OPTIONS } from '../tokens.js';
-import { CqrsSagaLifecycleService } from './saga-bus.js';
+import { discoverEventHandlerDescriptors } from './event-handler-discovery.js';
+import { CqrsPublishDrainTracker } from './publish-drain-tracker.js';
+import { CQRS_SAGA_DRAIN_AUTHORIZATION, CqrsSagaLifecycleService } from './saga-bus.js';
+import { CqrsShutdownDeadline } from './shutdown-deadline.js';
+import { CommandBusLifecycleService } from './command-bus.js';
+import { QueryBusLifecycleService } from './query-bus.js';
 const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
 function isEventHandler(value) {
   if (typeof value !== 'object' || value === null) {
@@ -30,19 +35,27 @@ function isEventHandler(value) {
 let _CqrsEventBusService;
 class CqrsEventBusService extends CqrsBusBase {
   static {
-    [_CqrsEventBusService, _initClass] = _applyDecs(this, [Inject(FLUO_EVENT_BUS, CqrsSagaLifecycleService, RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, CQRS_MODULE_OPTIONS)], [], 0, void 0, CqrsBusBase).c;
+    [_CqrsEventBusService, _initClass] = _applyDecs(this, [Inject(FLUO_EVENT_BUS, CqrsSagaLifecycleService, RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, CQRS_MODULE_OPTIONS, RUNTIME_CLEANUP_REGISTRATION, EventBusLifecycleService, CqrsShutdownDeadline, CommandBusLifecycleService, QueryBusLifecycleService)], [], 0, void 0, CqrsBusBase).c;
   }
   descriptors = [];
   discoveryPromise;
   discovered = false;
-  activePublishPipelines = new Set();
-  shutdownDrainTimeouts = 0;
+  publishDrainTracker;
   lifecycleState = 'created';
-  constructor(eventBus, sagaService, runtimeContainer, compiledModules, logger, moduleOptions = {}) {
+  unregisterShutdownStartCleanup;
+  constructor(eventBus, sagaService, runtimeContainer, compiledModules, logger, moduleOptions = {}, registerRuntimeCleanup = () => () => undefined, delegatedEventBus = undefined, shutdownDeadline = new CqrsShutdownDeadline(), commandService = undefined, queryService = undefined) {
     super(runtimeContainer, compiledModules, logger);
     this.eventBus = eventBus;
     this.sagaService = sagaService;
     this.moduleOptions = moduleOptions;
+    this.delegatedEventBus = delegatedEventBus;
+    this.shutdownDeadline = shutdownDeadline;
+    this.commandService = commandService;
+    this.queryService = queryService;
+    this.publishDrainTracker = new CqrsPublishDrainTracker(logger);
+    this.unregisterShutdownStartCleanup = registerRuntimeCleanup(() => {
+      this.markApplicationShutdownStarted();
+    });
   }
   async onApplicationBootstrap() {
     this.lifecycleState = 'discovering';
@@ -55,9 +68,11 @@ class CqrsEventBusService extends CqrsBusBase {
     }
   }
   async onApplicationShutdown() {
-    this.lifecycleState = 'stopping';
-    if (this.activePublishPipelines.size > 0) {
-      await this.drainActivePublishPipelines();
+    this.markApplicationShutdownStarted();
+    this.unregisterShutdownStartCleanup?.();
+    this.unregisterShutdownStartCleanup = undefined;
+    if (this.publishDrainTracker.hasActivePipelines) {
+      await this.publishDrainTracker.drain(this.resolveRemainingShutdownDrainTimeoutMs());
     }
     this.lifecycleState = 'stopped';
   }
@@ -68,16 +83,22 @@ class CqrsEventBusService extends CqrsBusBase {
    * @returns A structured snapshot describing CQRS event-handler discovery and saga lifecycle state.
    */
   createPlatformStatusSnapshot() {
+    const commandSnapshot = this.commandService?.getRuntimeSnapshot();
+    const querySnapshot = this.queryService?.getRuntimeSnapshot();
     const sagaSnapshot = this.sagaService.getRuntimeSnapshot();
     return createCqrsPlatformStatusSnapshot({
+      commandHandlersDiscovered: commandSnapshot?.commandHandlersDiscovered,
+      commandLifecycleState: commandSnapshot?.lifecycleState,
       eventHandlersDiscovered: this.descriptors.length,
       inFlightSagaExecutions: sagaSnapshot.inFlightSagaExecutions,
       lifecycleState: this.lifecycleState,
+      queryHandlersDiscovered: querySnapshot?.queryHandlersDiscovered,
+      queryLifecycleState: querySnapshot?.lifecycleState,
       sagaLifecycleState: sagaSnapshot.lifecycleState,
       sagaShutdownDrainTimeouts: sagaSnapshot.shutdownDrainTimeouts,
       sagasDiscovered: sagaSnapshot.sagasDiscovered,
       shutdownDrainTimeoutMs: this.resolveShutdownDrainTimeoutMs(),
-      shutdownDrainTimeouts: this.shutdownDrainTimeouts
+      shutdownDrainTimeouts: this.publishDrainTracker.shutdownDrainTimeouts
     });
   }
 
@@ -91,8 +112,9 @@ class CqrsEventBusService extends CqrsBusBase {
    * @throws {InvariantError} When a discovered provider does not implement `handle(event)`.
    */
   async publish(event, context) {
-    this.assertAcceptingNewWork('publish');
-    await this.trackPublishPipeline(this.runPublishPipeline(event, context));
+    this.assertAcceptingNewWork('publish', context);
+    const publishContext = this.createPublishContext(context);
+    await this.trackPublishPipeline(publishContext, this.runPublishPipeline(event, publishContext.context));
   }
 
   /**
@@ -103,8 +125,9 @@ class CqrsEventBusService extends CqrsBusBase {
    * @returns A promise that resolves once all events are published.
    */
   async publishAll(events, context) {
-    this.assertAcceptingNewWork('publishAll');
-    await this.trackPublishPipeline(this.runPublishAllPipeline(events, context));
+    this.assertAcceptingNewWork('publishAll', context);
+    const publishContext = this.createPublishContext(context);
+    await this.trackPublishPipeline(publishContext, this.runPublishAllPipeline(events, publishContext.context));
   }
   async runPublishPipeline(event, context) {
     await this.ensureDiscovered();
@@ -116,51 +139,62 @@ class CqrsEventBusService extends CqrsBusBase {
       await instance.handle(createIsolatedEvent(descriptor.eventType, event), context);
     }
     await this.sagaService.dispatch(event, context, {
-      allowDuringShutdown: true
+      afterSagas: async () => this.eventBus.publish(event),
+      drainAuthorization: CQRS_SAGA_DRAIN_AUTHORIZATION
     });
-    await this.eventBus.publish(event);
   }
   async runPublishAllPipeline(events, context) {
     for (const event of events) {
       await this.runPublishPipeline(event, context);
     }
   }
-  assertAcceptingNewWork(operation) {
-    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
-      throw new InvariantError(`CQRS event bus cannot ${operation} after shutdown has started.`);
-    }
-  }
-  async trackPublishPipeline(pipeline) {
-    this.activePublishPipelines.add(pipeline);
+  async trackPublishPipeline(publishContext, pipeline) {
+    const releaseSagaGraph = this.sagaService.acquireAuthorizedPipelineLease();
     try {
-      await pipeline;
+      await this.publishDrainTracker.track(pipeline, publishContext.drainToken);
     } finally {
-      this.activePublishPipelines.delete(pipeline);
+      releaseSagaGraph();
     }
   }
-  async drainActivePublishPipelines() {
-    const activePipelines = Array.from(this.activePublishPipelines);
-    const timeoutMs = this.resolveShutdownDrainTimeoutMs();
-    const drained = await this.awaitShutdownDrain(activePipelines, timeoutMs);
-    if (!drained) {
-      this.shutdownDrainTimeouts += 1;
-      this.logger.warn(`CQRS event shutdown drain exceeded ${String(timeoutMs)}ms with ${String(activePipelines.length)} active publish pipeline(s); continuing shutdown.`, 'CqrsEventBusService');
+  assertAcceptingNewWork(operation, context) {
+    if (this.lifecycleState === 'stopped') {
+      throw new InvariantError(`CQRS event bus cannot ${operation} after shutdown has started.`);
     }
-  }
-  async awaitShutdownDrain(activePipelines, timeoutMs) {
-    let timeoutId;
-    const timeout = new Promise(resolve => {
-      timeoutId = setTimeout(() => resolve(false), timeoutMs);
-    });
-    const drain = Promise.allSettled(activePipelines).then(() => true);
-    try {
-      return await Promise.race([drain, timeout]);
-    } finally {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
+    if (this.lifecycleState === 'stopping') {
+      const drainToken = getInternalCqrsDispatchContextState(context)?.publishDrainToken;
+      if (!drainToken || !this.publishDrainTracker.isActive(drainToken)) {
+        throw new InvariantError(`CQRS event bus cannot ${operation} after shutdown has started.`);
       }
     }
   }
+  markApplicationShutdownStarted() {
+    this.shutdownDeadline.start(this.resolveShutdownDrainTimeoutMs());
+    const deadlineAtMs = this.shutdownDeadline.deadlineAtMs();
+    if (deadlineAtMs !== undefined && this.delegatedEventBus) {
+      this.delegatedEventBus.adoptShutdownDeadline(deadlineAtMs);
+    }
+    if (this.lifecycleState !== 'stopped') {
+      this.lifecycleState = 'stopping';
+    }
+  }
+  createPublishContext(context) {
+    const internalState = getInternalCqrsDispatchContextState(context);
+    const drainToken = internalState?.publishDrainToken ?? Symbol('fluo.cqrs.activePublishDrain');
+    if (context && internalState?.publishDrainToken) {
+      return {
+        context,
+        drainToken
+      };
+    }
+    return {
+      context: createInternalCqrsDispatchContext({
+        publishDrainToken: drainToken,
+        sagaContinuationScope: internalState?.sagaContinuationScope,
+        sagaTopology: internalState?.sagaTopology
+      }),
+      drainToken
+    };
+  }
   resolveShutdownDrainTimeoutMs() {
     const timeoutMs = this.moduleOptions.shutdown?.drainTimeoutMs;
     if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
@@ -168,6 +202,9 @@ class CqrsEventBusService extends CqrsBusBase {
     }
     return Math.floor(timeoutMs);
   }
+  resolveRemainingShutdownDrainTimeoutMs() {
+    return this.shutdownDeadline.remainingTimeoutMs() ?? this.resolveShutdownDrainTimeoutMs();
+  }
   matchEventDescriptors(event) {
     return this.descriptors.filter(descriptor => event instanceof descriptor.eventType);
   }
@@ -195,34 +232,7 @@ class CqrsEventBusService extends CqrsBusBase {
     }
   }
   discoverEventDescriptors() {
-    const descriptors = [];
-    const seenByTarget = new WeakMap();
-    for (const candidate of this.discoveryCandidates()) {
-      const metadata = getEventHandlerMetadata(candidate.targetType);
-      if (!metadata) {
-        continue;
-      }
-      if (candidate.scope !== 'singleton') {
-        this.logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @EventHandler() but is registered with ${candidate.scope} scope. Event handlers are registered only for singleton providers.`, 'CqrsEventBusService');
-        continue;
-      }
-      const seenEventTypes = seenByTarget.get(candidate.targetType) ?? new Set();
-      if (seenEventTypes.has(metadata.eventType)) {
-        continue;
-      }
-      seenEventTypes.add(metadata.eventType);
-      seenByTarget.set(candidate.targetType, seenEventTypes);
-      const alreadyRegistered = descriptors.some(descriptor => descriptor.eventType === metadata.eventType && descriptor.targetType === candidate.targetType);
-      if (!alreadyRegistered) {
-        descriptors.push({
-          eventType: metadata.eventType,
-          moduleName: candidate.moduleName,
-          targetType: candidate.targetType,
-          token: candidate.token
-        });
-      }
-    }
-    return descriptors;
+    return discoverEventHandlerDescriptors(this.discoveryCandidates(), this.logger);
   }
   static {
     _initClass();

package/dist/buses/event-handler-discovery.d.ts

@@ -0,0 +1,12 @@
+import type { ApplicationLogger } from '@fluojs/runtime';
+import type { DiscoveryCandidate } from '../discovery.js';
+import type { EventHandlerDescriptor } from '../types.js';
+/**
+ * Discovers singleton event-handler 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 Event-handler descriptors in discovery order.
+ */
+export declare function discoverEventHandlerDescriptors(candidates: readonly DiscoveryCandidate[], logger: ApplicationLogger): EventHandlerDescriptor[];
+//# sourceMappingURL=event-handler-discovery.d.ts.map

package/dist/buses/event-handler-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-handler-discovery.d.ts","sourceRoot":"","sources":["../../src/buses/event-handler-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,EAAiB,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,MAAM,EAAE,iBAAiB,GACxB,sBAAsB,EAAE,CAoC1B"}

package/dist/buses/event-handler-discovery.js

@@ -0,0 +1,35 @@
+import { getEventHandlerMetadata } from '../metadata.js';
+/**
+ * Discovers singleton event-handler 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 Event-handler descriptors in discovery order.
+ */
+export function discoverEventHandlerDescriptors(candidates, logger) {
+  const descriptors = [];
+  const seenEventTypesByToken = new Map();
+  for (const candidate of candidates) {
+    const metadata = getEventHandlerMetadata(candidate.targetType);
+    if (!metadata) {
+      continue;
+    }
+    if (candidate.scope !== 'singleton') {
+      logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @EventHandler() but is registered with ${candidate.scope} scope. Event handlers are registered only for singleton providers.`, 'CqrsEventBusService');
+      continue;
+    }
+    const seenEventTypes = seenEventTypesByToken.get(candidate.token) ?? new Set();
+    if (seenEventTypes.has(metadata.eventType)) {
+      continue;
+    }
+    seenEventTypes.add(metadata.eventType);
+    seenEventTypesByToken.set(candidate.token, seenEventTypes);
+    descriptors.push({
+      eventType: metadata.eventType,
+      moduleName: candidate.moduleName,
+      targetType: candidate.targetType,
+      token: candidate.token
+    });
+  }
+  return descriptors;
+}

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;YAoBV,iBAAiB;CAKhC"}

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

@@ -0,0 +1,89 @@
+/** 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) {
+    if (timeoutMs <= 0) {
+      return false;
+    }
+    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,25 @@ 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>;
+    /**
+     * Returns query-handler discovery and lifecycle state for CQRS diagnostics.
+     *
+     * @returns Current discovery state, lifecycle state, and discovered query-handler count.
+     */
+    getRuntimeSnapshot(): {
+        discovered: boolean;
+        lifecycleState: 'created' | 'discovering' | 'ready' | 'stopping' | 'stopped' | 'failed';
+        queryHandlersDiscovered: number;
+    };
     /**
      * Executes one query by dispatching it to the discovered handler for its constructor.
      *
@@ -23,6 +38,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;;;;OAIG;IACH,kBAAkB,IAAI;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,cAAc,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;QACxF,uBAAuB,EAAE,MAAM,CAAC;KACjC;IAUD;;;;;;;;;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,52 @@ 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';
+  }
+
+  /**
+   * Returns query-handler discovery and lifecycle state for CQRS diagnostics.
+   *
+   * @returns Current discovery state, lifecycle state, and discovered query-handler count.
+   */
+  getRuntimeSnapshot() {
+    const stopped = this.lifecycleState === 'stopped';
+    return {
+      discovered: stopped ? false : this.discovered,
+      lifecycleState: this.lifecycleState,
+      queryHandlersDiscovered: stopped ? 0 : this.descriptors.size
+    };
   }
 
   /**
@@ -45,6 +84,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 +97,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 +132,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 +141,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;
   }