@fluojs/cqrs 1.1.2 → 2.0.0

package/README.ko.md

@@ -139,7 +139,7 @@ class GetOrderSummaryHandler
 }
 ```
 
-`CqrsModule.forRoot(...)`를 import하는 애플리케이션 모듈에 projection handler, query handler, projection store를 singleton provider로 등록하세요. `CqrsEventBusService.publish(new OrderPlacedEvent(...))`는 일치하는 `@EventHandler(...)` provider를 saga와 위임 `@fluojs/event-bus` 발행보다 먼저 실행하므로, read model은 문서화된 CQRS event pipeline을 통해 write-side fact를 관찰합니다. Event replay, retry, 외부 transport가 같은 business fact를 두 번 이상 전달할 수 있으므로 projection handler는 idempotent하게 유지하세요.
+`CqrsModule.forRoot(...)`를 import하는 애플리케이션 모듈에 projection handler, query handler, projection store를 singleton provider로 등록하세요. CQRS handler discovery는 provider registration만 검사합니다. HTTP controller는 request boundary에 남으며 controller class가 실수로 CQRS handler decorator를 가지고 있어도 무시됩니다. `CqrsModule.forRoot(...)`는 기본적으로 bus를 global로 export하며, `CqrsModule.forRoot({ global: false })`는 `eventBus.global`을 명시적으로 override하지 않는 한 해당 CQRS module을 import한 module을 통해서만 bus provider와 위임 `@fluojs/event-bus` provider가 보이도록 유지합니다. `CqrsEventBusService.publish(new OrderPlacedEvent(...))`는 일치하는 `@EventHandler(...)` provider를 saga와 위임 `@fluojs/event-bus` 발행보다 먼저 실행하므로, read model은 문서화된 CQRS event pipeline을 통해 write-side fact를 관찰합니다. Fan-out identity는 singleton provider token을 따릅니다. Decorated handler class 하나를 서로 다른 두 token으로 등록하면 두 registration이 모두 의도적으로 호출되고, 같은 token과 event route가 반복 discovery될 때만 deduplicate됩니다. Event replay, retry, 외부 transport가 같은 business fact를 두 번 이상 전달할 수 있으므로 projection handler는 idempotent하게 유지하세요.
 
 ### Saga 프로세스 매니저
 
@@ -168,19 +168,19 @@ class UserSaga implements ISaga<UserCreatedEvent> {
 }
 ```
 
-Saga 실행은 같은 프로세스 안에서 동일 saga route로 순환 재진입하거나 중첩 hop 수가 32를 넘으면 `SagaTopologyError`로 즉시 실패합니다. 서로 다른 이벤트 단계를 순차 처리하는 multi-stage saga는 계속 허용되지만, in-process saga graph 전체는 비순환(acyclic) 구조를 유지해야 하며, 의도적인 순환/피드백 루프나 더 긴 체인은 외부 transport, scheduler, 또는 다른 bounded boundary 뒤로 이동해야 합니다.
+Saga 실행은 같은 프로세스 안에서 동일 provider-token/event route로 순환 재진입하거나 중첩 hop 수가 32를 넘으면 `SagaTopologyError`로 즉시 실패합니다. 같은 decorated saga class를 사용하는 서로 다른 singleton token은 별도의 fan-out route로 유지됩니다. 서로 다른 이벤트 단계를 순차 처리하는 multi-stage saga는 계속 허용되지만, in-process saga graph 전체는 비순환(acyclic) 구조를 유지해야 하며, 의도적인 순환/피드백 루프나 더 긴 체인은 외부 transport, scheduler, 또는 다른 bounded boundary 뒤로 이동해야 합니다.
 
-Saga, command handler, query handler, event handler 안에서 다시 CQRS `execute(...)`, `publish(...)`, `publishAll(...)`를 호출할 때는 optional `CqrsDispatchContext` 인자를 그대로 전달하세요. CQRS는 이 명시적인 runtime-agnostic context로 Node.js async-local API에 의존하지 않고 nested dispatch 전반의 saga topology check를 유지합니다. 이 context는 opaque입니다. 직접 생성하거나 검사하거나 topology field에 의존하지 마세요. 해당 field는 내부 runtime state입니다.
+Saga, command handler, query handler, event handler 안에서 다시 CQRS `execute(...)`, `publish(...)`, `publishAll(...)`를 호출할 때는 optional `CqrsDispatchContext` 인자를 그대로 전달하세요. CQRS는 이 명시적인 runtime-agnostic context로 Node.js async-local API에 의존하지 않고 nested dispatch 전반의 saga topology check를 유지합니다. 이 context는 opaque, frozen fieldless pass-through value이며, 신뢰하는 topology와 shutdown-drain state는 CQRS 내부에 비공개로 유지됩니다. Caller-shaped object와 복사된 값은 신뢰된 runtime state를 운반하지 않으므로 context를 직접 생성, 복제, 검사, mutate하지 마세요.
 
 ### Event 발행 계약
 
-`CqrsEventBusService.publish(event)`는 CQRS event pipeline을 고정된 순서로 실행합니다. 먼저 일치하는 `@EventHandler(...)` provider를 실행하고, 그다음 일치하는 `@Saga(...)` provider를 실행한 뒤, 마지막으로 `@fluojs/event-bus`로 위임 발행합니다. `publishAll(events)`는 각 event의 CQRS handler, saga, 위임 발행 호출을 기다린 뒤 다음 event를 발행하므로 입력 순서를 보존합니다. 애플리케이션 shutdown 중에는 CQRS event bus가 진행 중인 `publish(...)` pipeline, `publishAll(...)` sequence, saga execution chain이 settle될 때까지 기다린 뒤 stopped 상태로 전환합니다. Shutdown이 시작되면 새로운 `publish(...)`, `publishAll(...)`, direct saga dispatch 호출은 거부됩니다. 이미 진행 중인 publish와 saga 작업은 bounded shutdown window 안에서 계속 drain됩니다. Shutdown drain은 기본값이 5000ms인 `CqrsModule.forRoot({ shutdown: { drainTimeoutMs } })`로 제한됩니다. CQRS handler, saga 또는 위임 publish chain이 이 bound 이후에도 멈춰 있으면 CQRS는 degraded status diagnostic을 기록하고 경고를 남긴 뒤 애플리케이션 close를 무기한 hang시키지 않고 계속 진행합니다. `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })`로 설정한 경우 위임 발행 호출은 일치하는 `@OnEvent(...)` subscriber가 완료되기 전에 resolve될 수 있으므로, 이 모드에서 `publish(...)`, `publishAll(...)`, shutdown drain 완료는 subscriber 완료를 의미하지 않습니다.
+`CqrsEventBusService.publish(event)`는 CQRS event pipeline을 고정된 순서로 실행합니다. 먼저 일치하는 `@EventHandler(...)` provider를 실행하고, 그다음 일치하는 `@Saga(...)` provider를 실행한 뒤, 마지막으로 `@fluojs/event-bus`로 위임 발행합니다. `publishAll(events)`는 각 event의 CQRS handler, saga, 위임 발행 호출을 기다린 뒤 다음 event를 발행하므로 입력 순서를 보존합니다. 애플리케이션 shutdown 중에는 CQRS event bus가 진행 중인 `publish(...)` pipeline, `publishAll(...)` sequence, saga execution chain이 settle될 때까지 기다린 뒤 stopped 상태로 전환합니다. Command bus와 query bus는 shutdown이 시작되면 새로운 `execute(...)` 호출을 거부하고 shutdown 중 preload된 handler cache를 정리하므로, close 이후 dispatch가 오래된 provider instance를 재사용할 수 없습니다. Shutdown이 시작되면 brand-new external `publish(...)`, `publishAll(...)`, direct saga dispatch 호출은 거부됩니다. 이미 활성화된 handler나 saga에서 호출되는 nested `publish(...)` 또는 `publishAll(...)`은 CQRS가 제공한 `CqrsDispatchContext`를 그대로 전달할 때만 계속 진행할 수 있습니다. 이렇게 하면 drain 작업은 활성 pipeline 안에 머무르고 관련 없는 caller는 계속 거부됩니다. 이미 진행 중인 publish와 saga 작업은 bounded shutdown window 안에서 계속 drain됩니다. Shutdown drain은 기본값이 5000ms인 `CqrsModule.forRoot({ shutdown: { drainTimeoutMs } })`로 제한됩니다. CQRS handler, saga 또는 위임 publish chain이 이 bound 이후에도 멈춰 있으면 CQRS는 degraded status diagnostic을 기록하고 경고를 남긴 뒤 애플리케이션 close를 무기한 hang시키지 않고 계속 진행합니다. `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })`로 설정한 경우 위임 발행 호출은 일치하는 `@OnEvent(...)` subscriber가 완료되기 전에 resolve될 수 있으므로, 이 모드에서 `publish(...)`, `publishAll(...)`, shutdown drain 완료는 subscriber 완료를 의미하지 않습니다.
 
 각 CQRS event handler와 saga는 매칭된 event prototype이 복원된 격리 event 복사본을 받습니다. 이 복사본을 mutate해도 변경은 현재 handler 또는 saga route 안에만 머물며, 다른 CQRS handler, saga, 원본 event 객체, 또는 위임된 `@fluojs/event-bus` subscriber에는 보이지 않습니다. 위임된 event-bus 발행은 CQRS side effect가 끝난 뒤 원본 event를 받으므로, `@OnEvent(...)` projection과 transport는 CQRS handler가 mutate한 복사본이 아니라 호출자가 소유한 payload를 관찰합니다.
 
 Event class는 payload state를 clone 가능하고 enumerable하게 유지해야 합니다. 문자열 key와 symbol key를 가진 enumerable payload field는 shared core clone fallback으로 보존되지만, 열린 socket, function, process-local handle처럼 의도적으로 clone할 수 없는 resource는 발행 전에 ID나 다른 serializable boundary로 표현해야 합니다.
 
-CQRS handler, event handler, saga는 singleton provider에서만 discovery됩니다. Non-singleton registration은 경고와 함께 건너뜁니다.
+CQRS handler, event handler, saga는 singleton provider에서만 discovery됩니다. Non-singleton registration은 경고와 함께 건너뜁니다. Event handler와 saga fan-out은 singleton provider token으로 구분되므로 같은 decorated class를 사용해도 서로 다른 token은 별도 route로 유지됩니다.
 
 ### 심볼 토큰
 
@@ -199,7 +199,7 @@ class TokenInjectedService {
 ## 공개 API 개요
 
 ### 모듈 및 프로바이더
-- `CqrsModule.forRoot(options)`: 메인 진입점입니다. 버스를 등록하고 탐색을 시작합니다.
+- `CqrsModule.forRoot(options)`: 메인 진입점입니다. 버스를 등록하고 provider-only discovery를 시작합니다. Bus provider는 기본적으로 global이며 module-local visibility가 필요하면 `global: false`를 전달합니다.
 - Module option은 명시적인 `commandHandlers`, `queryHandlers`, `eventHandlers`, `sagas`, 위임 `eventBus` option을 받을 수 있습니다.
 - `CommandBusLifecycleService`: Command 실행을 위한 기본 서비스입니다.
 - `QueryBusLifecycleService`: Query 실행을 위한 기본 서비스입니다.
@@ -219,7 +219,7 @@ class TokenInjectedService {
 ### 오류
 - `CommandHandlerNotFoundException`, `QueryHandlerNotFoundException`: bus에 일치하는 handler가 없을 때 발생합니다.
 - `DuplicateCommandHandlerError`, `DuplicateQueryHandlerError`: 서로 다른 singleton provider가 같은 command 또는 query type을 claim할 때 발생합니다.
-- `DuplicateEventHandlerError`: 충돌하는 event-handler discovery 실패를 위해 export됩니다. 일반적으로 같은 event에 여러 `@EventHandler(...)` provider를 등록하는 것은 유효하며 discovery 순서대로 fan-out됩니다.
+- `DuplicateEventHandlerError`: 호환성을 위해서만 export가 유지되며, event-handler discovery는 이 오류를 throw하거나 중복 registration을 failure로 취급하지 않습니다. 같은 provider token과 event route가 반복 discovery되면 조용히 deduplicate하고, 서로 다른 singleton provider token은 discovery 순서대로 fan-out되는 유효한 route로 유지합니다.
 - `SagaExecutionError`: 예상하지 못한 non-Fluo saga 실패를 감쌉니다.
 - `SagaTopologyError`: 자기 트리거, 순환, 또는 과도하게 깊은 in-process saga graph를 감지했을 때 발생합니다.
 

package/README.md

@@ -139,7 +139,7 @@ class GetOrderSummaryHandler
 }
 ```
 
-Register the projection handler, query handler, and projection store as singleton providers in the same application module that imports `CqrsModule.forRoot(...)`. `CqrsEventBusService.publish(new OrderPlacedEvent(...))` runs matching `@EventHandler(...)` providers before sagas and delegated `@fluojs/event-bus` publication, so the read model observes the write-side fact through the documented CQRS event pipeline. Keep projection handlers idempotent because event replay, retries, or external transports can deliver the same business fact more than once.
+Register the projection handler, query handler, and projection store as singleton providers in the same application module that imports `CqrsModule.forRoot(...)`. CQRS handler discovery inspects provider registrations only; HTTP controllers stay on the request boundary and are ignored even when a controller class accidentally carries a CQRS handler decorator. `CqrsModule.forRoot(...)` exports the buses globally by default, and `CqrsModule.forRoot({ global: false })` keeps those bus providers and the delegated `@fluojs/event-bus` providers visible only through modules that import the CQRS module unless `eventBus.global` is explicitly overridden. `CqrsEventBusService.publish(new OrderPlacedEvent(...))` runs matching `@EventHandler(...)` providers before sagas and delegated `@fluojs/event-bus` publication, so the read model observes the write-side fact through the documented CQRS event pipeline. Fan-out identity follows the singleton provider token: registering one decorated handler class under two distinct tokens intentionally invokes both registrations, while repeated discovery of the same token and event route is deduplicated. Keep projection handlers idempotent because event replay, retries, or external transports can deliver the same business fact more than once.
 
 ### Saga Process Managers
 
@@ -168,19 +168,19 @@ class UserSaga implements ISaga<UserCreatedEvent> {
 }
 ```
 
-Saga execution fails fast with `SagaTopologyError` when an in-process publish chain re-enters the same saga route cyclically or exceeds 32 nested saga hops. Multi-stage sagas may still react to different event types in sequence, but in-process saga graphs must stay acyclic overall; move intentionally cyclic or long-running feedback loops behind an external transport, scheduler, or other bounded boundary.
+Saga execution fails fast with `SagaTopologyError` when an in-process publish chain re-enters the same provider-token/event route cyclically or exceeds 32 nested saga hops. Distinct singleton tokens that use the same decorated saga class remain distinct fan-out routes. Multi-stage sagas may still react to different event types in sequence, but in-process saga graphs must stay acyclic overall; move intentionally cyclic or long-running feedback loops behind an external transport, scheduler, or other bounded boundary.
 
-When a saga, command handler, query handler, or event handler performs another CQRS `execute(...)`, `publish(...)`, or `publishAll(...)` call, pass the optional `CqrsDispatchContext` argument through unchanged. CQRS uses this explicit runtime-agnostic context to keep saga topology checks intact across nested dispatch without relying on Node.js async-local APIs. The context is opaque: do not construct it, inspect it, or depend on topology fields because those fields are internal runtime state.
+When a saga, command handler, query handler, or event handler performs another CQRS `execute(...)`, `publish(...)`, or `publishAll(...)` call, pass the optional `CqrsDispatchContext` argument through unchanged. CQRS uses this explicit runtime-agnostic context to keep saga topology checks intact across nested dispatch without relying on Node.js async-local APIs. The context is an opaque, frozen fieldless pass-through value; trusted topology and shutdown-drain state remains private to CQRS. Do not construct, clone, inspect, or mutate it because caller-shaped objects and copied values do not carry trusted runtime state.
 
 ### Event Publishing Contracts
 
-`CqrsEventBusService.publish(event)` runs the CQRS event pipeline in a fixed order: matching `@EventHandler(...)` providers first, matching `@Saga(...)` providers second, and delegated `@fluojs/event-bus` publication last. `publishAll(events)` preserves the input order by awaiting each event's CQRS handlers, sagas, and delegated publication call before publishing the next event. During application shutdown, the CQRS event bus waits for active `publish(...)` pipelines, `publishAll(...)` sequences, and saga execution chains to settle before marking itself stopped. Once shutdown starts, new `publish(...)`, `publishAll(...)`, and direct saga dispatch calls are rejected; already active publish and saga work continues draining inside the bounded shutdown window. Shutdown drain is bounded by `CqrsModule.forRoot({ shutdown: { drainTimeoutMs } })`, which defaults to 5000ms; if a CQRS handler, saga, or delegated publish chain is still stuck after the bound, CQRS records degraded status diagnostics, logs a warning, and lets application close continue instead of hanging indefinitely. When `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })` is configured, the delegated publication call can resolve before matching `@OnEvent(...)` subscribers finish, so `publish(...)`, `publishAll(...)`, and shutdown drain completion do not imply subscriber completion in that mode.
+`CqrsEventBusService.publish(event)` runs the CQRS event pipeline in a fixed order: matching `@EventHandler(...)` providers first, matching `@Saga(...)` providers second, and delegated `@fluojs/event-bus` publication last. `publishAll(events)` preserves the input order by awaiting each event's CQRS handlers, sagas, and delegated publication call before publishing the next event. During application shutdown, the CQRS event bus waits for active `publish(...)` pipelines, `publishAll(...)` sequences, and saga execution chains to settle before marking itself stopped. Command and query buses reject new `execute(...)` calls once shutdown starts and clear their preloaded handler caches during shutdown, so post-close dispatch cannot reuse stale provider instances. Once shutdown starts, brand-new external `publish(...)`, `publishAll(...)`, and direct saga dispatch calls are rejected. A nested `publish(...)` or `publishAll(...)` invoked from an already active handler or saga may continue only when it passes through the CQRS-provided `CqrsDispatchContext`; this keeps drain work inside the active pipeline while still rejecting unrelated callers. Already active publish and saga work continues draining inside the bounded shutdown window. Shutdown drain is bounded by `CqrsModule.forRoot({ shutdown: { drainTimeoutMs } })`, which defaults to 5000ms; if a CQRS handler, saga, or delegated publish chain is still stuck after the bound, CQRS records degraded status diagnostics, logs a warning, and lets application close continue instead of hanging indefinitely. When `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })` is configured, the delegated publication call can resolve before matching `@OnEvent(...)` subscribers finish, so `publish(...)`, `publishAll(...)`, and shutdown drain completion do not imply subscriber completion in that mode.
 
 Each CQRS event handler and saga receives an isolated event copy with the matched event prototype restored. Mutating that copy is local to the current handler or saga route; those mutations are not visible to other CQRS handlers, sagas, the original event object, or delegated `@fluojs/event-bus` subscribers. The delegated event-bus publication receives the original event after CQRS side effects complete, so `@OnEvent(...)` projections and transports observe the caller-owned payload rather than a CQRS handler's mutated copy.
 
 Event classes should keep their payload state cloneable and enumerable. String-keyed and symbol-keyed enumerable payload fields are preserved by the shared core clone fallback, while intentionally non-cloneable resources such as open sockets, functions, or process-local handles should be represented by IDs or other serializable boundaries before publishing.
 
-CQRS handlers, event handlers, and sagas are discovered only on singleton providers. Non-singleton registrations are skipped with warnings.
+CQRS handlers, event handlers, and sagas are discovered only on singleton providers. Non-singleton registrations are skipped with warnings. Event-handler and saga fan-out is keyed by singleton provider token, so distinct tokens remain distinct routes even when they use the same decorated class.
 
 ### Symbol Tokens
 
@@ -199,7 +199,7 @@ class TokenInjectedService {
 ## Public API Overview
 
 ### Modules & Providers
-- `CqrsModule.forRoot(options)`: Main entry point. Registers buses and starts discovery.
+- `CqrsModule.forRoot(options)`: Main entry point. Registers buses and starts provider-only discovery. Bus providers are global by default; pass `global: false` for module-local visibility.
 - Module options can provide explicit `commandHandlers`, `queryHandlers`, `eventHandlers`, `sagas`, and delegated `eventBus` options.
 - `CommandBusLifecycleService`: Primary service for executing commands.
 - `QueryBusLifecycleService`: Primary service for executing queries.
@@ -219,7 +219,7 @@ class TokenInjectedService {
 ### Errors
 - `CommandHandlerNotFoundException`, `QueryHandlerNotFoundException`: Raised when a bus has no matching handler.
 - `DuplicateCommandHandlerError`, `DuplicateQueryHandlerError`: Raised when different singleton providers claim the same command or query type.
-- `DuplicateEventHandlerError`: Exported for conflicting event-handler discovery failures; ordinary multiple `@EventHandler(...)` providers for the same event are valid and fan out in discovery order.
+- `DuplicateEventHandlerError`: Retained only as a compatibility export; event-handler discovery does not throw it or treat duplicate registrations as failures. Repeated discovery of the same provider token and event route is silently deduplicated, while distinct singleton provider tokens remain valid fan-out routes in discovery order.
 - `SagaExecutionError`: Wraps unexpected non-Fluo saga failures.
 - `SagaTopologyError`: Raised when saga orchestration detects a self-triggering, cyclic, or over-deep in-process saga graph.
 

package/dist/buses/command-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 { CommandBus, CqrsDispatchContext, ICommand } from '../types.js';
 /**
@@ -7,11 +8,15 @@ import type { CommandBus, CqrsDispatchContext, ICommand } from '../types.js';
  * The command bus resolves singleton handlers only, warns on unsupported scopes,
  * and throws explicit contract errors when no handler or multiple handlers exist.
  */
-export declare class CommandBusLifecycleService extends CqrsBusBase implements CommandBus, OnApplicationBootstrap {
+export declare class CommandBusLifecycleService extends CqrsBusBase implements CommandBus, 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 command by dispatching it to the discovered handler for its constructor.
      *
@@ -23,6 +28,8 @@ export declare class CommandBusLifecycleService extends CqrsBusBase implements C
      * @throws {InvariantError} When the resolved provider does not implement `execute(command)`.
      */
     execute<TCommand extends ICommand, TResult = void>(command: TCommand, context?: CqrsDispatchContext): Promise<TResult>;
+    private assertAcceptingNewWork;
+    private markApplicationShutdownStarted;
     private ensureDiscovered;
     private discoverHandlers;
     private discoverCommandDescriptors;

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

@@ -1 +1 @@
-{"version":3,"file":"command-bus.d.ts","sourceRoot":"","sources":["../../src/buses/command-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAiC,MAAM,iBAAiB,CAAC;AAG7E,OAAO,KAAK,EACV,UAAU,EAGV,mBAAmB,EACnB,QAAQ,EAET,MAAM,aAAa,CAAC;AAUrB;;;;;GAKG;AACH,qBACa,0BAA2B,SAAQ,WAAY,YAAW,UAAU,EAAE,sBAAsB;IACvG,OAAO,CAAC,WAAW,CAAoD;IACvE,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAErB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;;;;OASG;IACG,OAAO,CAAC,QAAQ,SAAS,QAAQ,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;YAmB9G,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,0BAA0B;CAmDnC"}
+{"version":3,"file":"command-bus.d.ts","sourceRoot":"","sources":["../../src/buses/command-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAEpJ,OAAO,EAAE,WAAW,EAA4D,MAAM,iBAAiB,CAAC;AAGxG,OAAO,KAAK,EACV,UAAU,EAGV,mBAAmB,EACnB,QAAQ,EAET,MAAM,aAAa,CAAC;AAUrB;;;;;GAKG;AACH,qBACa,0BAA2B,SAAQ,WAAY,YAAW,UAAU,EAAE,sBAAsB,EAAE,qBAAqB;IAC9H,OAAO,CAAC,WAAW,CAAoD;IACvE,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,QAAQ,SAAS,QAAQ,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB5H,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,8BAA8B;YAMxB,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,0BAA0B;CA2CnC"}

package/dist/buses/command-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 { CommandHandlerNotFoundException, DuplicateCommandHandlerError } from '../errors.js';
 import { getCommandHandlerMetadata } from '../metadata.js';
 function isCommandHandler(value) {
@@ -25,13 +25,38 @@ function isCommandHandler(value) {
 let _CommandBusLifecycleS;
 class CommandBusLifecycleService extends CqrsBusBase {
   static {
-    [_CommandBusLifecycleS, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER)], [], 0, void 0, CqrsBusBase).c;
+    [_CommandBusLifecycleS, _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 CommandBusLifecycleService extends CqrsBusBase {
    * @throws {InvariantError} When the resolved provider does not implement `execute(command)`.
    */
   async execute(command, context) {
+    this.assertAcceptingNewWork('execute');
     await this.ensureDiscovered();
     const commandType = command.constructor;
     const descriptor = this.descriptors.get(commandType);
@@ -57,6 +83,16 @@ class CommandBusLifecycleService extends CqrsBusBase {
     }
     return await instance.execute(command, context);
   }
+  assertAcceptingNewWork(operation) {
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+      throw new InvariantError(`CQRS command 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 CommandBusLifecycleService extends CqrsBusBase {
   }
   discoverCommandDescriptors() {
     const descriptors = new Map();
-    const seenByTarget = new WeakMap();
     for (const candidate of this.discoveryCandidates()) {
       const metadata = getCommandHandlerMetadata(candidate.targetType);
       if (!metadata) {
@@ -92,27 +127,22 @@ class CommandBusLifecycleService extends CqrsBusBase {
         this.logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @CommandHandler() but is registered with ${candidate.scope} scope. Command handlers are registered only for singleton providers.`, 'CommandBusLifecycleService');
         continue;
       }
-      const seenCommandTypes = seenByTarget.get(candidate.targetType) ?? new Set();
-      if (seenCommandTypes.has(metadata.commandType)) {
-        continue;
-      }
-      seenCommandTypes.add(metadata.commandType);
-      seenByTarget.set(candidate.targetType, seenCommandTypes);
       const existing = descriptors.get(metadata.commandType);
-      if (existing && existing.targetType !== candidate.targetType) {
-        throw new DuplicateCommandHandlerError(createDuplicateHandlerMessage('command', metadata.commandType, existing, {
-          moduleName: candidate.moduleName,
-          targetType: candidate.targetType
-        }));
-      }
-      if (!existing) {
-        descriptors.set(metadata.commandType, {
-          commandType: metadata.commandType,
-          moduleName: candidate.moduleName,
-          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 DuplicateCommandHandlerError(createDuplicateHandlerMessage('command', metadata.commandType, existing, nextDescriptor));
       }
+      descriptors.set(metadata.commandType, {
+        commandType: metadata.commandType,
+        ...nextDescriptor
+      });
     }
     return descriptors;
   }

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

@@ -1,5 +1,5 @@
 import { type EventBus } from '@fluojs/event-bus';
-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, CqrsEventBus, IEvent } from '../types.js';
@@ -17,10 +17,10 @@ export declare class CqrsEventBusService extends CqrsBusBase implements CqrsEven
     private descriptors;
     private discoveryPromise;
     private discovered;
-    private readonly activePublishPipelines;
-    private shutdownDrainTimeouts;
+    private readonly publishDrainTracker;
     private lifecycleState;
-    constructor(eventBus: EventBus, sagaService: CqrsSagaLifecycleService, runtimeContainer: ConstructorParameters<typeof CqrsBusBase>[0], compiledModules: ConstructorParameters<typeof CqrsBusBase>[1], logger: ConstructorParameters<typeof CqrsBusBase>[2], moduleOptions?: CqrsModuleOptions);
+    private unregisterShutdownStartCleanup;
+    constructor(eventBus: EventBus, sagaService: CqrsSagaLifecycleService, 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>;
     /**
@@ -50,9 +50,8 @@ export declare class CqrsEventBusService extends CqrsBusBase implements CqrsEven
     private runPublishPipeline;
     private runPublishAllPipeline;
     private assertAcceptingNewWork;
-    private trackPublishPipeline;
-    private drainActivePublishPipelines;
-    private awaitShutdownDrain;
+    private markApplicationShutdownStarted;
+    private createPublishContext;
     private resolveShutdownDrainTimeoutMs;
     private matchEventDescriptors;
     private ensureDiscovered;

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

@@ -1 +1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/buses/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAA+B,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAyC,MAAM,EAAiB,MAAM,aAAa,CAAC;AACnI,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAYzD;;;;;GAKG;AACH,qBACa,mBAAoB,SAAQ,WAAY,YAAW,YAAY,EAAE,sBAAsB,EAAE,qBAAqB;IASvH,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAI5B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAbhC,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA4B;IACnE,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,cAAc,CAAsF;gBAGzF,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,wBAAwB,EACtD,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;IAU5C;;;;OAIG;IACH,4BAA4B;IAe5B;;;;;;;;OAQG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjG;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;YAKlG,kBAAkB;YAiBlB,qBAAqB;IAMnC,OAAO,CAAC,sBAAsB;YAMhB,oBAAoB;YAUpB,2BAA2B;YAc3B,kBAAkB;IAiBhC,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,qBAAqB;YAIf,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CA4CjC"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/buses/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAA+B,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAGjH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAM9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAyC,MAAM,EAAiB,MAAM,aAAa,CAAC;AAGnI,OAAO,EAAiC,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAiBxF;;;;;GAKG;AACH,qBASa,mBAAoB,SAAQ,WAAY,YAAW,YAAY,EAAE,sBAAsB,EAAE,qBAAqB;IASvH,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAI5B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAbhC,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA0B;IAC9D,OAAO,CAAC,cAAc,CAAsF;IAC5G,OAAO,CAAC,8BAA8B,CAA2B;gBAG9C,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,wBAAwB,EACtD,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;IAUtE,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5C;;;;OAIG;IACH,4BAA4B;IAe5B;;;;;;;;OAQG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IASjG;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;YASlG,kBAAkB;YAiBlB,qBAAqB;IAMnC,OAAO,CAAC,sBAAsB;IAc9B,OAAO,CAAC,8BAA8B;IAMtC,OAAO,CAAC,oBAAoB;IAiB5B,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,qBAAqB;YAIf,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CAGjC"}

package/dist/buses/event-bus.js

@@ -6,13 +6,15 @@ function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.descrip
 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 { 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';
 const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
 function isEventHandler(value) {
   if (typeof value !== 'object' || value === null) {
@@ -30,19 +32,23 @@ 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)], [], 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) {
     super(runtimeContainer, compiledModules, logger);
     this.eventBus = eventBus;
     this.sagaService = sagaService;
     this.moduleOptions = moduleOptions;
+    this.publishDrainTracker = new CqrsPublishDrainTracker(logger);
+    this.unregisterShutdownStartCleanup = registerRuntimeCleanup(() => {
+      this.markApplicationShutdownStarted();
+    });
   }
   async onApplicationBootstrap() {
     this.lifecycleState = 'discovering';
@@ -55,9 +61,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.resolveShutdownDrainTimeoutMs());
     }
     this.lifecycleState = 'stopped';
   }
@@ -77,7 +85,7 @@ class CqrsEventBusService extends CqrsBusBase {
       sagaShutdownDrainTimeouts: sagaSnapshot.shutdownDrainTimeouts,
       sagasDiscovered: sagaSnapshot.sagasDiscovered,
       shutdownDrainTimeoutMs: this.resolveShutdownDrainTimeoutMs(),
-      shutdownDrainTimeouts: this.shutdownDrainTimeouts
+      shutdownDrainTimeouts: this.publishDrainTracker.shutdownDrainTimeouts
     });
   }
 
@@ -91,8 +99,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.publishDrainTracker.track(this.runPublishPipeline(event, publishContext.context), publishContext.drainToken);
   }
 
   /**
@@ -103,8 +112,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.publishDrainTracker.track(this.runPublishAllPipeline(events, publishContext.context), publishContext.drainToken);
   }
   async runPublishPipeline(event, context) {
     await this.ensureDiscovered();
@@ -115,9 +125,7 @@ class CqrsEventBusService extends CqrsBusBase {
       }
       await instance.handle(createIsolatedEvent(descriptor.eventType, event), context);
     }
-    await this.sagaService.dispatch(event, context, {
-      allowDuringShutdown: true
-    });
+    await this.sagaService.dispatch(event, context, CQRS_SAGA_DRAIN_AUTHORIZATION);
     await this.eventBus.publish(event);
   }
   async runPublishAllPipeline(events, context) {
@@ -125,41 +133,38 @@ class CqrsEventBusService extends CqrsBusBase {
       await this.runPublishPipeline(event, context);
     }
   }
-  assertAcceptingNewWork(operation) {
-    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+  assertAcceptingNewWork(operation, context) {
+    if (this.lifecycleState === 'stopped') {
       throw new InvariantError(`CQRS event bus cannot ${operation} after shutdown has started.`);
     }
-  }
-  async trackPublishPipeline(pipeline) {
-    this.activePublishPipelines.add(pipeline);
-    try {
-      await pipeline;
-    } finally {
-      this.activePublishPipelines.delete(pipeline);
+    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.`);
+      }
     }
   }
-  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');
+  markApplicationShutdownStarted() {
+    if (this.lifecycleState !== 'stopped') {
+      this.lifecycleState = 'stopping';
     }
   }
-  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);
-      }
+  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,
+        sagaTopology: internalState?.sagaTopology
+      }),
+      drainToken
+    };
   }
   resolveShutdownDrainTimeoutMs() {
     const timeoutMs = this.moduleOptions.shutdown?.drainTimeoutMs;
@@ -195,34 +200,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;
+}