@fluojs/cqrs 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,153 @@
+# @fluojs/cqrs
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 애플리케이션을 위한 CQRS 패키지입니다. 부트스트랩 시점 핸들러 탐색, Command/Query 디스패치, 그리고 `@fluojs/event-bus` 위임 기반 이벤트 발행 기능을 제공합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [공통 패턴](#공통-패턴)
+  - [Saga 프로세스 매니저](#saga-프로세스-매니저)
+  - [심볼 토큰](#심볼-토큰)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/cqrs
+```
+
+## 사용 시점
+
+- "의도"(Command/Query)와 "실행"(Handler)을 분리하고 싶을 때 사용합니다.
+- 쓰기 모델과 읽기 모델의 명확한 분리가 필요한 복잡한 비즈니스 로직을 구현할 때 적합합니다.
+- 도메인 이벤트에 의해 트리거되는 다단계 프로세스(Saga)를 오케스트레이션할 때 사용합니다.
+- 단일 애플리케이션 내에서 Command, Query, Event를 위한 중앙 집중식 버스가 필요할 때 사용합니다.
+
+## 빠른 시작
+
+`CqrsModule`을 등록하고 첫 번째 Command와 Handler를 정의합니다.
+
+`CqrsModule.forRoot(...)`를 사용해 CQRS 버스와 핸들러 탐색을 구성합니다.
+
+```typescript
+import { Inject, Module } from '@fluojs/core';
+import {
+  CqrsModule,
+  CommandHandler,
+  ICommand,
+  ICommandHandler,
+  CommandBusLifecycleService,
+} from '@fluojs/cqrs';
+
+// 1. Command 정의
+class CreateUserCommand implements ICommand {
+  constructor(public readonly name: string) {}
+}
+
+// 2. Handler 구현
+@CommandHandler(CreateUserCommand)
+class CreateUserHandler implements ICommandHandler<CreateUserCommand, string> {
+  async execute(command: CreateUserCommand): Promise<string> {
+    console.log(`사용자 생성 중: ${command.name}`);
+    return 'user-id-123';
+  }
+}
+
+// 3. Command Bus 사용
+@Inject(CommandBusLifecycleService)
+class UserService {
+  constructor(private readonly commandBus: CommandBusLifecycleService) {}
+
+  async create(name: string) {
+    return this.commandBus.execute(new CreateUserCommand(name));
+  }
+}
+
+@Module({
+  imports: [CqrsModule.forRoot()],
+  providers: [CreateUserHandler, UserService],
+})
+class AppModule {}
+```
+
+## 공통 패턴
+
+### Saga 프로세스 매니저
+
+Saga를 사용하면 이벤트를 구독하고 새로운 Command를 트리거하여 복잡한 장기 실행 워크플로우를 구성할 수 있습니다.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { Saga, ISaga, IEvent, ICommand, CommandBusLifecycleService } from '@fluojs/cqrs';
+
+class UserCreatedEvent implements IEvent {
+  constructor(public readonly userId: string) {}
+}
+
+class SendWelcomeEmailCommand implements ICommand {
+  constructor(public readonly userId: string) {}
+}
+
+@Inject(CommandBusLifecycleService)
+@Saga(UserCreatedEvent)
+class UserSaga implements ISaga<UserCreatedEvent> {
+  constructor(private readonly commandBus: CommandBusLifecycleService) {}
+
+  async handle(event: UserCreatedEvent): Promise<void> {
+    await this.commandBus.execute(new SendWelcomeEmailCommand(event.userId));
+  }
+}
+```
+
+이제 saga 실행은 같은 프로세스 안에서 동일 saga route로 순환 재진입하거나 중첩 hop 수가 32를 넘으면 `SagaTopologyError`로 즉시 실패합니다. 서로 다른 이벤트 단계를 순차 처리하는 multi-stage saga는 계속 허용되지만, in-process saga graph 전체는 비순환(acyclic) 구조를 유지해야 하며, 의도적인 순환/피드백 루프나 더 긴 체인은 외부 transport, scheduler, 또는 다른 bounded boundary 뒤로 이동해야 합니다.
+
+### 심볼 토큰
+
+CQRS 버스에 명시적인 Symbol 토큰이 필요하면 다음 익스포트를 사용할 수 있습니다.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { COMMAND_BUS, QUERY_BUS, EVENT_BUS } from '@fluojs/cqrs';
+
+@Inject(COMMAND_BUS, QUERY_BUS, EVENT_BUS)
+class TokenInjectedService {
+  constructor(commandBus, queryBus, eventBus) {}
+}
+```
+
+## 공개 API 개요
+
+### 모듈 및 프로바이더
+- `CqrsModule.forRoot(options)`: 메인 진입점입니다. 버스를 등록하고 탐색을 시작합니다.
+- `CommandBusLifecycleService`: Command 실행을 위한 기본 서비스입니다.
+- `QueryBusLifecycleService`: Query 실행을 위한 기본 서비스입니다.
+- `CqrsEventBusService`: Event 발행을 위한 기본 서비스입니다.
+
+### 데코레이터
+- `@CommandHandler(Command)`: 클래스를 특정 Command와 연결합니다.
+- `@QueryHandler(Query)`: 클래스를 특정 Query와 연결합니다.
+- `@EventHandler(Event)`: 클래스를 특정 Event와 연결합니다.
+- `@Saga(Event | Event[])`: 클래스를 Saga 리스너로 표시합니다.
+
+### 인터페이스
+- `ICommand`, `IQuery<T>`, `IEvent`: 메시지 마커 인터페이스입니다.
+- `ICommandHandler<C, R>`, `IQueryHandler<Q, R>`, `IEventHandler<E>`, `ISaga<E>`: 핸들러 계약입니다.
+
+### 오류
+- `SagaTopologyError`: 자기 트리거, 순환, 또는 과도하게 깊은 in-process saga graph를 감지했을 때 발생합니다.
+
+## 관련 패키지
+
+- `@fluojs/event-bus`: `CqrsEventBusService`에서 사용하는 하위 이벤트 분산 패키지입니다.
+- `@fluojs/core`: `@Module` 및 `@Inject` 데코레이터를 위해 필요합니다.
+
+## 예제 소스
+
+- `packages/cqrs/src/module.test.ts`: 모듈 등록 및 기본 버스 사용 예제.
+- `packages/cqrs/src/public-api.test.ts`: 루트 배럴 공개 API 계약 검증 예제.

package/README.md

@@ -0,0 +1,153 @@
+# @fluojs/cqrs
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+CQRS primitives for fluo applications with bootstrap-time handler discovery, command/query dispatch, and event publishing delegation through `@fluojs/event-bus`.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+  - [Saga Process Managers](#saga-process-managers)
+  - [Symbol Tokens](#symbol-tokens)
+- [Public API Overview](#public-api-overview)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/cqrs
+```
+
+## When to Use
+
+- When you want to decouple the "intent" (Commands/Queries) from the "execution" (Handlers).
+- When implementing complex business logic that requires clear separation between write models and read models.
+- When orchestrating multi-step processes (Sagas) triggered by domain events.
+- When you need a centralized bus for commands, queries, and events within a single application.
+
+## Quick Start
+
+Register the `CqrsModule` and define your first command and handler.
+
+Use `CqrsModule.forRoot(...)` to wire CQRS buses and handler discovery.
+
+```typescript
+import { Inject, Module } from '@fluojs/core';
+import {
+  CqrsModule,
+  CommandHandler,
+  ICommand,
+  ICommandHandler,
+  CommandBusLifecycleService,
+} from '@fluojs/cqrs';
+
+// 1. Define a Command
+class CreateUserCommand implements ICommand {
+  constructor(public readonly name: string) {}
+}
+
+// 2. Implement the Handler
+@CommandHandler(CreateUserCommand)
+class CreateUserHandler implements ICommandHandler<CreateUserCommand, string> {
+  async execute(command: CreateUserCommand): Promise<string> {
+    console.log(`Creating user: ${command.name}`);
+    return 'user-id-123';
+  }
+}
+
+// 3. Use the Command Bus
+@Inject(CommandBusLifecycleService)
+class UserService {
+  constructor(private readonly commandBus: CommandBusLifecycleService) {}
+
+  async create(name: string) {
+    return this.commandBus.execute(new CreateUserCommand(name));
+  }
+}
+
+@Module({
+  imports: [CqrsModule.forRoot()],
+  providers: [CreateUserHandler, UserService],
+})
+class AppModule {}
+```
+
+## Common Patterns
+
+### Saga Process Managers
+
+Sagas allow you to listen for events and trigger new commands, enabling complex long-running workflows.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { Saga, ISaga, IEvent, ICommand, CommandBusLifecycleService } from '@fluojs/cqrs';
+
+class UserCreatedEvent implements IEvent {
+  constructor(public readonly userId: string) {}
+}
+
+class SendWelcomeEmailCommand implements ICommand {
+  constructor(public readonly userId: string) {}
+}
+
+@Inject(CommandBusLifecycleService)
+@Saga(UserCreatedEvent)
+class UserSaga implements ISaga<UserCreatedEvent> {
+  constructor(private readonly commandBus: CommandBusLifecycleService) {}
+
+  async handle(event: UserCreatedEvent): Promise<void> {
+    await this.commandBus.execute(new SendWelcomeEmailCommand(event.userId));
+  }
+}
+```
+
+Saga execution now 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.
+
+### Symbol Tokens
+
+Use these exports when you want explicit symbol tokens for the CQRS buses:
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { COMMAND_BUS, QUERY_BUS, EVENT_BUS } from '@fluojs/cqrs';
+
+@Inject(COMMAND_BUS, QUERY_BUS, EVENT_BUS)
+class TokenInjectedService {
+  constructor(commandBus, queryBus, eventBus) {}
+}
+```
+
+## Public API Overview
+
+### Modules & Providers
+- `CqrsModule.forRoot(options)`: Main entry point. Registers buses and starts discovery.
+- `CommandBusLifecycleService`: Primary service for executing commands.
+- `QueryBusLifecycleService`: Primary service for executing queries.
+- `CqrsEventBusService`: Primary service for publishing events.
+
+### Decorators
+- `@CommandHandler(Command)`: Associates a class with a Command.
+- `@QueryHandler(Query)`: Associates a class with a Query.
+- `@EventHandler(Event)`: Associates a class with an Event.
+- `@Saga(Event | Event[])`: Marks a class as a Saga listener.
+
+### Interfaces
+- `ICommand`, `IQuery<T>`, `IEvent`: Marker interfaces for messages.
+- `ICommandHandler<C, R>`, `IQueryHandler<Q, R>`, `IEventHandler<E>`, `ISaga<E>`: Handler contracts.
+
+### Errors
+- `SagaTopologyError`: Raised when saga orchestration detects a self-triggering, cyclic, or over-deep in-process saga graph.
+
+## Related Packages
+
+- `@fluojs/event-bus`: Underlying event distribution used by `CqrsEventBusService`.
+- `@fluojs/core`: Required for `@Module` and `@Inject` decorators.
+
+## Example Sources
+
+- `packages/cqrs/src/module.test.ts`: Module registration and basic bus usage.
+- `packages/cqrs/src/public-api.test.ts`: Root-barrel public API contract coverage.

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

@@ -0,0 +1,29 @@
+import type { OnApplicationBootstrap } from '@fluojs/runtime';
+import { CqrsBusBase } from '../discovery.js';
+import type { CommandBus, ICommand } from '../types.js';
+/**
+ * Discovers and executes command handlers during application bootstrap and runtime dispatch.
+ *
+ * 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 {
+    private descriptors;
+    private discoveryPromise;
+    private discovered;
+    onApplicationBootstrap(): Promise<void>;
+    /**
+     * Executes one command by dispatching it to the discovered handler for its constructor.
+     *
+     * @param command Command instance to execute.
+     * @returns The resolved handler result.
+     *
+     * @throws {CommandHandlerNotFoundException} When no handler is registered for the command type.
+     * @throws {InvariantError} When the resolved provider does not implement `execute(command)`.
+     */
+    execute<TCommand extends ICommand, TResult = void>(command: TCommand): Promise<TResult>;
+    private ensureDiscovered;
+    private discoverHandlers;
+    private discoverCommandDescriptors;
+}
+//# sourceMappingURL=command-bus.d.ts.map

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

@@ -0,0 +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;AAK9D,OAAO,EAAE,WAAW,EAAiC,MAAM,iBAAiB,CAAC;AAC7E,OAAO,KAAK,EACV,UAAU,EAGV,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;;;;;;;;OAQG;IACG,OAAO,CAAC,QAAQ,SAAS,QAAQ,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;YAmB/E,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,0BAA0B;CAmDnC"}

package/dist/buses/command-bus.js

@@ -0,0 +1,122 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+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 { CommandHandlerNotFoundException, DuplicateCommandHandlerError } from '../errors.js';
+import { getCommandHandlerMetadata } from '../metadata.js';
+import { CqrsBusBase, createDuplicateHandlerMessage } from '../discovery.js';
+function isCommandHandler(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return typeof value.execute === 'function';
+}
+
+/**
+ * Discovers and executes command handlers during application bootstrap and runtime dispatch.
+ *
+ * The command bus resolves singleton handlers only, warns on unsupported scopes,
+ * and throws explicit contract errors when no handler or multiple handlers exist.
+ */
+let _CommandBusLifecycleS;
+class CommandBusLifecycleService extends CqrsBusBase {
+  static {
+    [_CommandBusLifecycleS, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER)], [], 0, void 0, CqrsBusBase).c;
+  }
+  descriptors = new Map();
+  discoveryPromise;
+  discovered = false;
+  async onApplicationBootstrap() {
+    await this.ensureDiscovered();
+  }
+
+  /**
+   * Executes one command by dispatching it to the discovered handler for its constructor.
+   *
+   * @param command Command instance to execute.
+   * @returns The resolved handler result.
+   *
+   * @throws {CommandHandlerNotFoundException} When no handler is registered for the command type.
+   * @throws {InvariantError} When the resolved provider does not implement `execute(command)`.
+   */
+  async execute(command) {
+    await this.ensureDiscovered();
+    const commandType = command.constructor;
+    const descriptor = this.descriptors.get(commandType);
+    if (!descriptor) {
+      throw new CommandHandlerNotFoundException(`No command handler registered for ${commandType.name}.`);
+    }
+    const instance = await this.resolveHandlerInstance(descriptor.token);
+    if (!isCommandHandler(instance)) {
+      throw new InvariantError(`Command handler ${descriptor.targetType.name} must implement execute(command).`);
+    }
+    return await instance.execute(command);
+  }
+  async ensureDiscovered() {
+    if (this.discovered) {
+      return;
+    }
+    if (this.discoveryPromise) {
+      await this.discoveryPromise;
+      return;
+    }
+    this.discoveryPromise = this.discoverHandlers();
+    await this.discoveryPromise;
+  }
+  async discoverHandlers() {
+    try {
+      this.descriptors = this.discoverCommandDescriptors();
+      this.handlerInstances.clear();
+      for (const descriptor of this.descriptors.values()) {
+        await this.preloadHandlerInstance(descriptor.token);
+      }
+      this.discovered = true;
+    } finally {
+      this.discoveryPromise = undefined;
+    }
+  }
+  discoverCommandDescriptors() {
+    const descriptors = new Map();
+    const seenByTarget = new WeakMap();
+    for (const candidate of this.discoveryCandidates()) {
+      const metadata = getCommandHandlerMetadata(candidate.targetType);
+      if (!metadata) {
+        continue;
+      }
+      if (candidate.scope !== 'singleton') {
+        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
+        });
+      }
+    }
+    return descriptors;
+  }
+  static {
+    _initClass();
+  }
+}
+export { _CommandBusLifecycleS as CommandBusLifecycleService };

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

@@ -0,0 +1,49 @@
+import { type EventBus } from '@fluojs/event-bus';
+import type { OnApplicationShutdown, OnApplicationBootstrap } from '@fluojs/runtime';
+import { CqrsBusBase } from '../discovery.js';
+import { CqrsSagaLifecycleService } from './saga-bus.js';
+import type { CqrsEventBus, IEvent } from '../types.js';
+/**
+ * CQRS-facing event bus that dispatches local event handlers, sagas, and the shared event transport.
+ *
+ * This service keeps CQRS event handlers singleton-only, fans events into saga orchestration,
+ * and delegates the final publication step to `@fluojs/event-bus`.
+ */
+export declare class CqrsEventBusService extends CqrsBusBase implements CqrsEventBus, OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly eventBus;
+    private readonly sagaService;
+    private descriptors;
+    private discoveryPromise;
+    private discovered;
+    private lifecycleState;
+    constructor(eventBus: EventBus, sagaService: CqrsSagaLifecycleService, runtimeContainer: ConstructorParameters<typeof CqrsBusBase>[0], compiledModules: ConstructorParameters<typeof CqrsBusBase>[1], logger: ConstructorParameters<typeof CqrsBusBase>[2]);
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    /**
+     * Creates a CQRS runtime status snapshot that includes local handler and saga state.
+     *
+     * @returns A structured snapshot describing CQRS event-handler discovery and saga lifecycle state.
+     */
+    createPlatformStatusSnapshot(): import("../status.js").CqrsPlatformStatusSnapshot;
+    /**
+     * Publishes one event to matching CQRS handlers, sagas, and the shared event bus.
+     *
+     * @param event Event instance to publish.
+     * @returns A promise that resolves once all local CQRS side effects and delegated publication complete.
+     *
+     * @throws {InvariantError} When a discovered provider does not implement `handle(event)`.
+     */
+    publish<TEvent extends IEvent>(event: TEvent): Promise<void>;
+    /**
+     * Publishes a batch of events sequentially through the CQRS event pipeline.
+     *
+     * @param events Event instances to publish in order.
+     * @returns A promise that resolves once all events are published.
+     */
+    publishAll<TEvent extends IEvent>(events: readonly TEvent[]): Promise<void>;
+    private matchEventDescriptors;
+    private ensureDiscovered;
+    private discoverHandlers;
+    private discoverEventDescriptors;
+}
+//# sourceMappingURL=event-bus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/buses/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAyC,MAAM,EAAiB,MAAM,aAAa,CAAC;AAU9G;;;;;GAKG;AACH,qBACa,mBAAoB,SAAQ,WAAY,YAAW,YAAY,EAAE,sBAAsB,EAAE,qBAAqB;IAOvH,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAP9B,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,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;IAKhD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5C;;;;OAIG;IACH,4BAA4B;IAY5B;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBlE;;;;;OAKG;IACG,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjF,OAAO,CAAC,qBAAqB;YAIf,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CA4CjC"}