hexastack-cqrs 0.0.0__tar.gz

hexastack_cqrs-0.0.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.3
+Name: hexastack-cqrs
+Version: 0.0.0
+Summary: CQRS commands, queries, events, buses, and execution pipeline for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: hexastack-core
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: huey>=3.3.4 ; extra == 'huey'
+Requires-Python: >=3.13
+Provides-Extra: huey
+Description-Content-Type: text/markdown
+
+# hexastack-cqrs
+
+> Command Query Responsibility Segregation (CQRS) buses, execution pipelines, and middleware for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-cqrs` powers the application logic layer of Hexastack applications, enforcing a strict separation between write operations (Commands) and read projections (Queries):
+
+- **Synchronous & Asynchronous Buses**: `SynchronousCommandBus`, `SynchronousQueryBus`, `SynchronousEventBus`, and async/distributed buses.
+- **Composable Middleware Pipeline**: Pluggable middlewares executed sequentially before and after command/query handling:
+  - `CorrelationMiddleware`: Propagates correlation IDs across requests and async tasks.
+  - `TimingMiddleware`: Measures and records execution latency.
+  - `LoggingMiddleware`: Logs execution lifecycles and errors via `LoggerPort` (dynamically gated via `features.cqrs.logging`).
+  - `TenacityRetryMiddleware`: Exponential backoff and retry policies powered by `tenacity` (dynamically gated via `features.cqrs.retry`).
+  - `UnitOfWorkMiddleware`: Automatic transaction scoping (`commit()` on success, `rollback()` on failure).
+  - `ConditionalFeatureFlagMiddleware`: Evaluates dynamic feature flags before dispatching commands/queries.
+- **Declarative Decorators & Scanning**: `@command_handler`, `@query_handler`, `@event_handler`, and `@feature_flag` registered via reflective module scanning.
+- **Presenter & Response Mapping**: Integration with `PresenterPort` for formatting outputs across CLI and REST adapters.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_cqrs/
+├── domain/          # Command, Query, Event, Handler protocols, CQRS exceptions
+├── ports/           # CommandBusPort, QueryBusPort, EventBusPort, MiddlewarePort
+├── adapters/        # Buses (Synchronous & Asynchronous with Huey)
+└── infra/           # CqrsBootstrapper (order=20), Middleware pipeline, Registries, @feature_flag
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Adapters** | `SynchronousCommandBus`, `SynchronousQueryBus`, `SynchronousEventBus`, `HueyCommandBus`, `HueyEventBus` |
+| **Bootstrap** | `CqrsBootstrapper` (order=20), `CqrsConfig` |
+| **Decorators** | `@command_handler`, `@query_handler`, `@event_handler`, `@feature_flag`, `@presenter` |
+| **Domain** | `Command`, `Query`, `Event`, `CommandHandler`, `QueryHandler`, `EventHandler` |
+| **Middlewares** | `CorrelationMiddleware`, `TimingMiddleware`, `LoggingMiddleware`, `TenacityRetryMiddleware`, `UnitOfWorkMiddleware`, `ConditionalFeatureFlagMiddleware`, `ExecutionPipeline` |
+| **Ports** | `CommandBusPort`, `QueryBusPort`, `EventBusPort`, `MiddlewarePort` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph DrivingAdapters ["Inbound Driving Adapters"]
+        FASTAPI["hexastack-fastapi"]
+        GRAPHQL["hexastack-graphql"]
+        MCP["hexastack-mcp"]
+        GRPC["hexastack-grpc"]
+        CLI["hexastack-cli"]
+    end
+
+    subgraph CQRS ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+        EBUS["EventBusPort"]
+        PIPE["Middleware Pipeline"]
+    end
+
+    subgraph DrivenDependencies ["Driven Subsystems & Kernel"]
+        CORE["hexastack-core (DI & Kernel)"]
+        DB["hexastack-db (UnitOfWorkPort)"]
+        LOG["hexastack-logging (LoggerPort)"]
+    end
+
+    FASTAPI -->|dispatches to| CBUS
+    FASTAPI -->|dispatches to| QBUS
+    GRAPHQL -->|dispatches to| CBUS
+    GRAPHQL -->|dispatches to| QBUS
+    MCP -->|dispatches to| CBUS
+    MCP -->|dispatches to| QBUS
+    GRPC -->|dispatches to| CBUS
+    GRPC -->|dispatches to| QBUS
+    CLI -->|dispatches to| CBUS
+    CLI -->|dispatches to| QBUS
+
+    CBUS --> PIPE
+    QBUS --> PIPE
+    EBUS --> PIPE
+
+    PIPE -->|managed by| CORE
+    PIPE -. consumes from DI .-> DB
+    PIPE -. consumes from DI .-> LOG
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: Core kernel, DI container, base exceptions, and ports.
+- `tenacity>=9.0.0`: Resilient retry policies with exponential backoff.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **UnitOfWork Scoping**: `UnitOfWorkMiddleware` dynamically resolves `UnitOfWorkPort` from the DI container (injected by `hexastack-db`) to manage transactions.
+- **Telemetry Integration**: `LoggingMiddleware` dynamically resolves `LoggerPort` from the DI container (injected by `hexastack-logging`).
+- **Driving Adapters**: Consumed by `hexastack-fastapi` and `hexastack-cli` to route incoming user actions to business handlers.
+
+### Optional Integrations (Extras)
+- `[huey]`: Enables asynchronous, distributed task queue execution using `HueyCommandBus` and `HueyEventBus`.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone installation
+pip install hexastack-cqrs
+
+# With asynchronous distributed background worker (Huey)
+pip install "hexastack-cqrs[huey]"
+
+# Via umbrella package
+pip install hexastack
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.cqrs]
+enable_correlation = true
+enable_timing = true
+enable_logging = true
+enable_uow = true
+retry_attempts = 3
+retry_backoff_base = 0.5
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.command import Command
+from hexastack_cqrs.infra.decorators import command_handler
+from hexastack_cqrs.ports.buses import CommandBusPort
+
+
+@dataclass(frozen=True)
+class CreateOrderCommand(Command):
+    order_id: str
+    amount: float
+
+
+@command_handler(CreateOrderCommand)
+class CreateOrderHandler:
+    def __call__(self, cmd: CreateOrderCommand) -> str:
+        return f"Order {cmd.order_id} created for ${cmd.amount:.2f}"
+
+
+runtime = bootstrap(packages_to_scan=[__name__])
+bus = runtime.container.get(CommandBusPort)
+
+result = bus.dispatch(CreateOrderCommand(order_id="ord-99", amount=49.99))
+print(result)  # "Order ord-99 created for $49.99"
+```

hexastack_cqrs-0.0.0/README.md

@@ -0,0 +1,164 @@
+# hexastack-cqrs
+
+> Command Query Responsibility Segregation (CQRS) buses, execution pipelines, and middleware for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-cqrs` powers the application logic layer of Hexastack applications, enforcing a strict separation between write operations (Commands) and read projections (Queries):
+
+- **Synchronous & Asynchronous Buses**: `SynchronousCommandBus`, `SynchronousQueryBus`, `SynchronousEventBus`, and async/distributed buses.
+- **Composable Middleware Pipeline**: Pluggable middlewares executed sequentially before and after command/query handling:
+  - `CorrelationMiddleware`: Propagates correlation IDs across requests and async tasks.
+  - `TimingMiddleware`: Measures and records execution latency.
+  - `LoggingMiddleware`: Logs execution lifecycles and errors via `LoggerPort` (dynamically gated via `features.cqrs.logging`).
+  - `TenacityRetryMiddleware`: Exponential backoff and retry policies powered by `tenacity` (dynamically gated via `features.cqrs.retry`).
+  - `UnitOfWorkMiddleware`: Automatic transaction scoping (`commit()` on success, `rollback()` on failure).
+  - `ConditionalFeatureFlagMiddleware`: Evaluates dynamic feature flags before dispatching commands/queries.
+- **Declarative Decorators & Scanning**: `@command_handler`, `@query_handler`, `@event_handler`, and `@feature_flag` registered via reflective module scanning.
+- **Presenter & Response Mapping**: Integration with `PresenterPort` for formatting outputs across CLI and REST adapters.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_cqrs/
+├── domain/          # Command, Query, Event, Handler protocols, CQRS exceptions
+├── ports/           # CommandBusPort, QueryBusPort, EventBusPort, MiddlewarePort
+├── adapters/        # Buses (Synchronous & Asynchronous with Huey)
+└── infra/           # CqrsBootstrapper (order=20), Middleware pipeline, Registries, @feature_flag
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Adapters** | `SynchronousCommandBus`, `SynchronousQueryBus`, `SynchronousEventBus`, `HueyCommandBus`, `HueyEventBus` |
+| **Bootstrap** | `CqrsBootstrapper` (order=20), `CqrsConfig` |
+| **Decorators** | `@command_handler`, `@query_handler`, `@event_handler`, `@feature_flag`, `@presenter` |
+| **Domain** | `Command`, `Query`, `Event`, `CommandHandler`, `QueryHandler`, `EventHandler` |
+| **Middlewares** | `CorrelationMiddleware`, `TimingMiddleware`, `LoggingMiddleware`, `TenacityRetryMiddleware`, `UnitOfWorkMiddleware`, `ConditionalFeatureFlagMiddleware`, `ExecutionPipeline` |
+| **Ports** | `CommandBusPort`, `QueryBusPort`, `EventBusPort`, `MiddlewarePort` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph DrivingAdapters ["Inbound Driving Adapters"]
+        FASTAPI["hexastack-fastapi"]
+        GRAPHQL["hexastack-graphql"]
+        MCP["hexastack-mcp"]
+        GRPC["hexastack-grpc"]
+        CLI["hexastack-cli"]
+    end
+
+    subgraph CQRS ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+        EBUS["EventBusPort"]
+        PIPE["Middleware Pipeline"]
+    end
+
+    subgraph DrivenDependencies ["Driven Subsystems & Kernel"]
+        CORE["hexastack-core (DI & Kernel)"]
+        DB["hexastack-db (UnitOfWorkPort)"]
+        LOG["hexastack-logging (LoggerPort)"]
+    end
+
+    FASTAPI -->|dispatches to| CBUS
+    FASTAPI -->|dispatches to| QBUS
+    GRAPHQL -->|dispatches to| CBUS
+    GRAPHQL -->|dispatches to| QBUS
+    MCP -->|dispatches to| CBUS
+    MCP -->|dispatches to| QBUS
+    GRPC -->|dispatches to| CBUS
+    GRPC -->|dispatches to| QBUS
+    CLI -->|dispatches to| CBUS
+    CLI -->|dispatches to| QBUS
+
+    CBUS --> PIPE
+    QBUS --> PIPE
+    EBUS --> PIPE
+
+    PIPE -->|managed by| CORE
+    PIPE -. consumes from DI .-> DB
+    PIPE -. consumes from DI .-> LOG
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: Core kernel, DI container, base exceptions, and ports.
+- `tenacity>=9.0.0`: Resilient retry policies with exponential backoff.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **UnitOfWork Scoping**: `UnitOfWorkMiddleware` dynamically resolves `UnitOfWorkPort` from the DI container (injected by `hexastack-db`) to manage transactions.
+- **Telemetry Integration**: `LoggingMiddleware` dynamically resolves `LoggerPort` from the DI container (injected by `hexastack-logging`).
+- **Driving Adapters**: Consumed by `hexastack-fastapi` and `hexastack-cli` to route incoming user actions to business handlers.
+
+### Optional Integrations (Extras)
+- `[huey]`: Enables asynchronous, distributed task queue execution using `HueyCommandBus` and `HueyEventBus`.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone installation
+pip install hexastack-cqrs
+
+# With asynchronous distributed background worker (Huey)
+pip install "hexastack-cqrs[huey]"
+
+# Via umbrella package
+pip install hexastack
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.cqrs]
+enable_correlation = true
+enable_timing = true
+enable_logging = true
+enable_uow = true
+retry_attempts = 3
+retry_backoff_base = 0.5
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.command import Command
+from hexastack_cqrs.infra.decorators import command_handler
+from hexastack_cqrs.ports.buses import CommandBusPort
+
+
+@dataclass(frozen=True)
+class CreateOrderCommand(Command):
+    order_id: str
+    amount: float
+
+
+@command_handler(CreateOrderCommand)
+class CreateOrderHandler:
+    def __call__(self, cmd: CreateOrderCommand) -> str:
+        return f"Order {cmd.order_id} created for ${cmd.amount:.2f}"
+
+
+runtime = bootstrap(packages_to_scan=[__name__])
+bus = runtime.container.get(CommandBusPort)
+
+result = bus.dispatch(CreateOrderCommand(order_id="ord-99", amount=49.99))
+print(result)  # "Order ord-99 created for $49.99"
+```

hexastack_cqrs-0.0.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "hexastack-cqrs"
+version = "0.0.0"
+description = "CQRS commands, queries, events, buses, and execution pipeline for Hexastack"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "tenacity>=9.0.0",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+huey = ["huey>=3.3.4"]
+
+[project.entry-points."hexastack.bootstrappers"]
+cqrs = "hexastack_cqrs.infra.bootstrap:CqrsBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_cqrs"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_cqrs"]
+layers = [
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_cqrs.domain"]
+forbidden_modules = [
+    "hexastack_cqrs.ports",
+    "hexastack_cqrs.adapters",
+    "hexastack_cqrs.infra",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for ports"
+type = "forbidden"
+source_modules = ["hexastack_cqrs.ports"]
+forbidden_modules = [
+    "hexastack_cqrs.adapters",
+    "hexastack_cqrs.infra",
+]

hexastack_cqrs-0.0.0/pyproject.toml.orig

@@ -0,0 +1,60 @@
+[project]
+name = "hexastack-cqrs"
+version = "0.0.0"
+description = "CQRS commands, queries, events, buses, and execution pipeline for Hexastack"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "tenacity>=9.0.0",
+]
+
+[project.optional-dependencies]
+huey = [
+    "huey>=3.3.4",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+cqrs = "hexastack_cqrs.infra.bootstrap:CqrsBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_cqrs"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_cqrs"]
+layers = [
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_cqrs.domain"]
+forbidden_modules = [
+    "hexastack_cqrs.ports",
+    "hexastack_cqrs.adapters",
+    "hexastack_cqrs.infra",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for ports"
+type = "forbidden"
+source_modules = ["hexastack_cqrs.ports"]
+forbidden_modules = [
+    "hexastack_cqrs.adapters",
+    "hexastack_cqrs.infra",
+]

hexastack_cqrs-0.0.0/src/hexastack_cqrs/__init__.py

@@ -0,0 +1,8 @@
+from hexastack_cqrs import adapters, domain, infra, ports
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+    "ports",
+]

hexastack_cqrs-0.0.0/src/hexastack_cqrs/adapters/__init__.py

@@ -0,0 +1,19 @@
+from hexastack_cqrs.adapters.buses import (
+    AsyncNativeCommandBus,
+    AsyncNativeEventBus,
+    HueyCommandBus,
+    HueyEventBus,
+    SynchronousCommandBus,
+    SynchronousEventBus,
+    SynchronousQueryBus,
+)
+
+__all__ = [
+    "AsyncNativeCommandBus",
+    "AsyncNativeEventBus",
+    "HueyCommandBus",
+    "HueyEventBus",
+    "SynchronousCommandBus",
+    "SynchronousEventBus",
+    "SynchronousQueryBus",
+]

hexastack_cqrs-0.0.0/src/hexastack_cqrs/adapters/buses/__init__.py

@@ -0,0 +1,23 @@
+from hexastack_cqrs.adapters.buses.command import (
+    AsyncNativeCommandBus,
+    HueyCommandBus,
+    SynchronousCommandBus,
+)
+from hexastack_cqrs.adapters.buses.event import (
+    AsyncNativeEventBus,
+    HueyEventBus,
+    RecordingEventBus,
+    SynchronousEventBus,
+)
+from hexastack_cqrs.adapters.buses.query import SynchronousQueryBus
+
+__all__ = [
+    "AsyncNativeCommandBus",
+    "AsyncNativeEventBus",
+    "HueyCommandBus",
+    "HueyEventBus",
+    "RecordingEventBus",
+    "SynchronousCommandBus",
+    "SynchronousEventBus",
+    "SynchronousQueryBus",
+]

hexastack_cqrs-0.0.0/src/hexastack_cqrs/adapters/buses/command/__init__.py

@@ -0,0 +1,13 @@
+from hexastack_cqrs.adapters.buses.command.asynchronous import (
+    AsyncNativeCommandBus,
+    HueyCommandBus,
+)
+from hexastack_cqrs.adapters.buses.command.synchronous import (
+    SynchronousCommandBus,
+)
+
+__all__ = [
+    "AsyncNativeCommandBus",
+    "HueyCommandBus",
+    "SynchronousCommandBus",
+]

hexastack_cqrs-0.0.0/src/hexastack_cqrs/adapters/buses/command/asynchronous.py

@@ -0,0 +1,131 @@
+import importlib.util
+from collections.abc import Callable
+from concurrent.futures import Future, ThreadPoolExecutor
+from typing import TYPE_CHECKING, Any
+
+from hexastack_core.domain import Command, Generic
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_cqrs.infra.middleware.generic import GenericMiddleware
+from hexastack_cqrs.infra.registries.handler import HandlerRegistry
+from hexastack_cqrs.ports.buses import CommandBusPort
+
+if TYPE_CHECKING:
+    from huey import Huey
+
+
+class HueyCommandBus(CommandBusPort):
+    """Asynchronous CommandBus adapter dispatching commands via Huey task queue.
+
+    Notes/Architectural Intent:
+        Delegates command execution to background worker processes via Huey,
+        enabling distributed, durable asynchronous background processing.
+        Requires hexastack-cqrs[huey].
+    """
+
+    def __init__(
+        self,
+        huey: "Huey",
+        handler_registry: HandlerRegistry,
+        middleware: list[GenericMiddleware] | None = None,
+    ) -> None:
+        """Initialize Huey command bus with Huey instance and handler registry.
+
+        Args:
+            huey: Initialized Huey task queue instance.
+            handler_registry: HandlerRegistry containing registered command handlers.
+            middleware: Optional ordered list of GenericMiddleware interceptors.
+
+        Raises:
+            MissingDependencyError: If huey package is not installed.
+        """
+        if importlib.util.find_spec("huey") is None:
+            raise MissingDependencyError(
+                "huey is required to use HueyCommandBus. "
+                "Install via 'pip install hexastack-cqrs[huey]'."
+            )
+
+        self._huey = huey
+        self._registry = handler_registry
+        self._middleware = list(middleware) if middleware is not None else []
+
+        @self._huey.task()
+        def _execute_command_task(cmd: Command) -> Any:
+            pipeline: Callable[[Generic], Any] = lambda inst: self._registry.handle(
+                inst, reraise=True
+            )
+            for mw in reversed(self._middleware):
+                next_fn = pipeline
+                pipeline = lambda inst, m=mw, n=next_fn: m(inst, n)
+            return pipeline(cmd)
+
+        self._task_fn = _execute_command_task
+
+    def dispatch(self, command: Command) -> Any:
+        """Enqueue command to Huey background queue for execution.
+
+        Args:
+            command: The command instance to enqueue.
+
+        Returns:
+            Huey Task object representing the background job.
+
+        Raises:
+            Exception: If enqueuing to Huey queue fails.
+        """
+        return self._task_fn(command)
+
+
+class AsyncNativeCommandBus(CommandBusPort):
+    """Asynchronous in-process CommandBus using thread pool execution.
+
+    Notes/Architectural Intent:
+        Provides non-blocking in-process command execution without requiring external
+        queue backends, returning a standard concurrent.futures.Future.
+    """
+
+    def __init__(
+        self,
+        handler_registry: HandlerRegistry,
+        middleware: list[GenericMiddleware] | None = None,
+        executor: ThreadPoolExecutor | None = None,
+    ) -> None:
+        """Initialize native async command bus.
+
+        Args:
+            handler_registry: HandlerRegistry containing registered command handlers.
+            middleware: Optional ordered list of GenericMiddleware interceptors.
+            executor: Optional ThreadPoolExecutor for managing worker threads.
+        """
+        self._registry = handler_registry
+        self._middleware = list(middleware) if middleware is not None else []
+        self._executor = executor or ThreadPoolExecutor(thread_name_prefix="cqrs-async")
+
+    def dispatch(self, command: Command) -> Future[Any]:
+        """Submit command for asynchronous background execution on thread pool.
+
+        Args:
+            command: The command instance to dispatch.
+
+        Returns:
+            Future resolving to the handler execution result.
+
+        Raises:
+            Exception: If submitting task to thread pool executor fails.
+        """
+
+        def _run() -> Any:
+            pipeline: Callable[[Generic], Any] = lambda inst: self._registry.handle(
+                inst, reraise=True
+            )
+            for mw in reversed(self._middleware):
+                next_fn = pipeline
+                pipeline = lambda inst, m=mw, n=next_fn: m(inst, n)
+            return pipeline(command)
+
+        return self._executor.submit(_run)
+
+
+__all__ = [
+    "AsyncNativeCommandBus",
+    "HueyCommandBus",
+]