hexcore 2.2.0__tar.gz → 2.4.0__tar.gz

{hexcore-2.2.0/hexcore.egg-info → hexcore-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 2.2.0
+Version: 2.4.0
 Summary: Núcleo reutilizable para proyectos Python con arquitectura hexagonal y event handling. Provee abstracciones, utilidades y contratos para DDD, eventos y desacoplamiento de infraestructura.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT
@@ -22,6 +22,8 @@ Provides-Extra: procrastinate
 Requires-Dist: procrastinate>=3.0.0; extra == "procrastinate"
 Provides-Extra: rabbitmq
 Requires-Dist: aio-pika>=9.4.0; extra == "rabbitmq"
+Provides-Extra: celery
+Requires-Dist: celery>=5.4.0; extra == "celery"
 Dynamic: license-file
 
 # HexCore [![PyPI Downloads](https://static.pepy.tech/personalized-badge/hexcore?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/hexcore)
@@ -456,6 +458,132 @@ En ambos casos, es tu **EventBus** (o un consumidor como Procrastinate) el encar
 
 ---
 
+### Integración con Task Queues (Smart Routing)
+
+HexCore v2 hace que la delegación de tareas a **Celery**, **Procrastinate** o **ARQ** sea increíblemente sencilla y mágica a través del patrón de **Smart Routing**.
+
+Ya no necesitas instanciar buses separados para código síncrono y asíncrono. HexCore enruta automáticamente tus comandos y eventos hacia las colas de background usando simples decoradores.
+
+#### 1. Decoradores de Background
+
+HexCore ofrece 3 decoradores esenciales en `hexcore.domain.cqrs.decorators` para cubrir todos los casos de uso:
+
+1. **`@background_command(queue="...")`**: Aplícalo sobre una clase `Command`. Todo el comando y su handler se ejecutarán asíncronamente en el Worker. Ideal para operaciones pesadas iniciadas por el usuario (ej. Generar un reporte PDF masivo).
+2. **`@background_handler(queue="...")`**: Aplícalo sobre una función que maneje un evento (`DomainEvent`). Permite que un solo evento dispare algunas acciones síncronas rápidas y otras asíncronas lentas (ej. Enviar emails).
+3. **`@background_task(queue="...")`**: Aplícalo sobre funciones o utilidades genéricas que no pertenecen al modelo estricto de CQRS (ej. Limpiar base de datos, tareas tipo CRON).
+
+**Ejemplos de uso:**
+
+```python
+from hexcore.domain.cqrs.decorators import background_command, background_handler, background_task
+from hexcore.domain.cqrs.commands import Command
+
+# 1. Comando de ejecución asíncrona obligatoria
+@background_command(queue="high_priority")
+class SendEmailCommand(Command):
+    user_id: str
+    template: str
+
+# 2. Handler de evento asíncrono
+@background_handler(queue="analytics")
+async def send_analytics_on_user_created(event: UserCreatedEvent):
+    # Lógica costosa...
+    pass
+
+# 3. Tarea genérica (Non-CQRS)
+@background_task(queue="maintenance")
+async def clean_old_records_task(days_retention: int):
+    # Limpieza de base de datos...
+    pass
+```
+
+#### 2. Crear el Enqueuer (Adaptador)
+
+Implementa la interfaz genérica `ITaskEnqueuer` usando la SDK de tu Task Queue favorito:
+
+```python
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+
+class ProcrastinateEnqueuer(ITaskEnqueuer):
+    async def enqueue_command(self, command_name: str, payload: dict, queue: str) -> None:
+        await process_cqrs_command.defer_async(payload=payload)
+        
+    async def enqueue_handler(self, handler_name: str, payload: dict, queue: str) -> None:
+        await process_cqrs_handler.defer_async(handler_name=handler_name, payload=payload)
+    
+    async def enqueue_event(self, event_name: str, payload: dict, queue: str) -> None:
+        pass # Usualmente no se usa directamente si utilizas @background_handler
+        
+    async def enqueue_task(self, task_name: str, payload: dict, queue: str) -> None:
+        await process_generic_task.defer_async(task_name=task_name, payload=payload)
+```
+
+#### 2. Configurar tus Buses con un Adaptador Oficial
+
+HexCore provee adaptadores *plug & play* para **Celery** y **Procrastinate**. Simplemente importa el enqueuer, pásale tu app y configúralo en los buses de memoria.
+
+Si además deseas persistencia o distribución de Eventos entre múltiples workers/servidores (Pub/Sub), puedes cambiar el `InMemoryEventBus` por `RedisEventBus`, `PostgresEventBus` o `RabbitMQEventBus`:
+
+```python
+from hexcore.application.cqrs.in_memory_buses import InMemoryCommandBus
+from hexcore.infrastructure.task_queues.celery_adapter import CeleryEnqueuer
+from hexcore.infrastructure.cqrs.redis_bus import RedisEventBus
+from celery import Celery
+import redis.asyncio as redis
+
+# 1. Adaptador de Task Queue (Para Comandos asíncronos y Event Handlers asíncronos)
+app = Celery("my_app", broker="redis://localhost:6379/0")
+enqueuer = CeleryEnqueuer(app)
+serializer = PydanticSerializer()
+
+command_bus = InMemoryCommandBus(registry=registry, enqueuer=enqueuer, serializer=serializer)
+
+# 2. Event Bus (Para enviar los Eventos por la red)
+redis_client = redis.from_url("redis://localhost:6379/0")
+event_bus = RedisEventBus(
+    redis_client=redis_client,
+    serializer=serializer,
+    stream_name="hexcore:events",
+    group_name="api_workers",
+    enqueuer=enqueuer  # <-- Importante para inyectarle la habilidad de Smart Routing
+)
+```
+
+> **Tip:** También dispones de `PostgresEventBus(pool, serializer, channel_name)` que usa `LISTEN/NOTIFY` nativo si quieres 0 dependencias externas aparte de tu BD de siempre.
+
+#### 4. Ejecutar tareas genéricas
+
+Para encolar la tarea genérica (`@background_task`), la llamas indirectamente pasándola por el enqueuer:
+
+```python
+# Así se encola una tarea genérica sin CQRS:
+await enqueuer.enqueue_task(
+    task_name=clean_old_records_task.__cqrs_task_name__, 
+    payload={"days_retention": 30},
+    queue=clean_old_records_task.__cqrs_queue__
+)
+```
+
+#### 5. Levantar el Worker (Consumidor Universal)
+
+En el entrypoint de tu worker, usa la función utilitaria `register_hexcore_celery_tasks` para autoconfigurar las rutas en una sola línea:
+
+```python
+from hexcore.infrastructure.workers.consumer import CQRSConsumer
+from hexcore.infrastructure.task_queues.celery_adapter import register_hexcore_celery_tasks
+
+consumer = CQRSConsumer(
+    command_bus=command_bus, # Tu CommandBus configurado
+    event_bus=event_bus, 
+    serializer=serializer
+)
+
+# ¡Magia! Registra las tareas 'hexcore.process_command', 'hexcore.process_handler', etc.
+register_hexcore_celery_tasks(app, consumer)
+```
+
+---
+
 ## Referencias
 
 - [CONTRIBUTING.md](./CONTRIBUTING.md): Pautas de colaboración.

{hexcore-2.2.0 → hexcore-2.4.0}/README.md

@@ -430,6 +430,132 @@ En ambos casos, es tu **EventBus** (o un consumidor como Procrastinate) el encar
 
 ---
 
+### Integración con Task Queues (Smart Routing)
+
+HexCore v2 hace que la delegación de tareas a **Celery**, **Procrastinate** o **ARQ** sea increíblemente sencilla y mágica a través del patrón de **Smart Routing**.
+
+Ya no necesitas instanciar buses separados para código síncrono y asíncrono. HexCore enruta automáticamente tus comandos y eventos hacia las colas de background usando simples decoradores.
+
+#### 1. Decoradores de Background
+
+HexCore ofrece 3 decoradores esenciales en `hexcore.domain.cqrs.decorators` para cubrir todos los casos de uso:
+
+1. **`@background_command(queue="...")`**: Aplícalo sobre una clase `Command`. Todo el comando y su handler se ejecutarán asíncronamente en el Worker. Ideal para operaciones pesadas iniciadas por el usuario (ej. Generar un reporte PDF masivo).
+2. **`@background_handler(queue="...")`**: Aplícalo sobre una función que maneje un evento (`DomainEvent`). Permite que un solo evento dispare algunas acciones síncronas rápidas y otras asíncronas lentas (ej. Enviar emails).
+3. **`@background_task(queue="...")`**: Aplícalo sobre funciones o utilidades genéricas que no pertenecen al modelo estricto de CQRS (ej. Limpiar base de datos, tareas tipo CRON).
+
+**Ejemplos de uso:**
+
+```python
+from hexcore.domain.cqrs.decorators import background_command, background_handler, background_task
+from hexcore.domain.cqrs.commands import Command
+
+# 1. Comando de ejecución asíncrona obligatoria
+@background_command(queue="high_priority")
+class SendEmailCommand(Command):
+    user_id: str
+    template: str
+
+# 2. Handler de evento asíncrono
+@background_handler(queue="analytics")
+async def send_analytics_on_user_created(event: UserCreatedEvent):
+    # Lógica costosa...
+    pass
+
+# 3. Tarea genérica (Non-CQRS)
+@background_task(queue="maintenance")
+async def clean_old_records_task(days_retention: int):
+    # Limpieza de base de datos...
+    pass
+```
+
+#### 2. Crear el Enqueuer (Adaptador)
+
+Implementa la interfaz genérica `ITaskEnqueuer` usando la SDK de tu Task Queue favorito:
+
+```python
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+
+class ProcrastinateEnqueuer(ITaskEnqueuer):
+    async def enqueue_command(self, command_name: str, payload: dict, queue: str) -> None:
+        await process_cqrs_command.defer_async(payload=payload)
+        
+    async def enqueue_handler(self, handler_name: str, payload: dict, queue: str) -> None:
+        await process_cqrs_handler.defer_async(handler_name=handler_name, payload=payload)
+    
+    async def enqueue_event(self, event_name: str, payload: dict, queue: str) -> None:
+        pass # Usualmente no se usa directamente si utilizas @background_handler
+        
+    async def enqueue_task(self, task_name: str, payload: dict, queue: str) -> None:
+        await process_generic_task.defer_async(task_name=task_name, payload=payload)
+```
+
+#### 2. Configurar tus Buses con un Adaptador Oficial
+
+HexCore provee adaptadores *plug & play* para **Celery** y **Procrastinate**. Simplemente importa el enqueuer, pásale tu app y configúralo en los buses de memoria.
+
+Si además deseas persistencia o distribución de Eventos entre múltiples workers/servidores (Pub/Sub), puedes cambiar el `InMemoryEventBus` por `RedisEventBus`, `PostgresEventBus` o `RabbitMQEventBus`:
+
+```python
+from hexcore.application.cqrs.in_memory_buses import InMemoryCommandBus
+from hexcore.infrastructure.task_queues.celery_adapter import CeleryEnqueuer
+from hexcore.infrastructure.cqrs.redis_bus import RedisEventBus
+from celery import Celery
+import redis.asyncio as redis
+
+# 1. Adaptador de Task Queue (Para Comandos asíncronos y Event Handlers asíncronos)
+app = Celery("my_app", broker="redis://localhost:6379/0")
+enqueuer = CeleryEnqueuer(app)
+serializer = PydanticSerializer()
+
+command_bus = InMemoryCommandBus(registry=registry, enqueuer=enqueuer, serializer=serializer)
+
+# 2. Event Bus (Para enviar los Eventos por la red)
+redis_client = redis.from_url("redis://localhost:6379/0")
+event_bus = RedisEventBus(
+    redis_client=redis_client,
+    serializer=serializer,
+    stream_name="hexcore:events",
+    group_name="api_workers",
+    enqueuer=enqueuer  # <-- Importante para inyectarle la habilidad de Smart Routing
+)
+```
+
+> **Tip:** También dispones de `PostgresEventBus(pool, serializer, channel_name)` que usa `LISTEN/NOTIFY` nativo si quieres 0 dependencias externas aparte de tu BD de siempre.
+
+#### 4. Ejecutar tareas genéricas
+
+Para encolar la tarea genérica (`@background_task`), la llamas indirectamente pasándola por el enqueuer:
+
+```python
+# Así se encola una tarea genérica sin CQRS:
+await enqueuer.enqueue_task(
+    task_name=clean_old_records_task.__cqrs_task_name__, 
+    payload={"days_retention": 30},
+    queue=clean_old_records_task.__cqrs_queue__
+)
+```
+
+#### 5. Levantar el Worker (Consumidor Universal)
+
+En el entrypoint de tu worker, usa la función utilitaria `register_hexcore_celery_tasks` para autoconfigurar las rutas en una sola línea:
+
+```python
+from hexcore.infrastructure.workers.consumer import CQRSConsumer
+from hexcore.infrastructure.task_queues.celery_adapter import register_hexcore_celery_tasks
+
+consumer = CQRSConsumer(
+    command_bus=command_bus, # Tu CommandBus configurado
+    event_bus=event_bus, 
+    serializer=serializer
+)
+
+# ¡Magia! Registra las tareas 'hexcore.process_command', 'hexcore.process_handler', etc.
+register_hexcore_celery_tasks(app, consumer)
+```
+
+---
+
 ## Referencias
 
 - [CONTRIBUTING.md](./CONTRIBUTING.md): Pautas de colaboración.

hexcore-2.4.0/hexcore/application/cqrs/in_memory_buses.py

@@ -0,0 +1,164 @@
+"""
+Implementaciones In-Memory de los buses CQRS con soporte para Enrutamiento Inteligente (Smart Routing).
+"""
+from __future__ import annotations
+
+import typing as t
+import logging
+
+from hexcore.domain.cqrs.buses import ICommandBus, IQueryBus, IEventBus
+from hexcore.domain.cqrs.commands import Command
+from hexcore.domain.cqrs.queries import Query
+from hexcore.domain.events import DomainEvent
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+from hexcore.domain.cqrs.serializer import ISerializer
+
+from .registry import HandlerRegistry
+from .pipeline import MiddlewarePipeline
+
+logger = logging.getLogger("hexcore.cqrs.buses")
+
+
+class InMemoryCommandBus(ICommandBus):
+    """
+    Bus de commands síncrono en memoria con Smart Routing.
+    Resuelve el handler desde el registry, ejecuta el pipeline de middlewares
+    y retorna el resultado.
+    
+    Si el comando está decorado con `@background_command` y se provee un `enqueuer`,
+    el comando es automáticamente encolado para su ejecución en segundo plano
+    sin bloquear el proceso actual (retornando None).
+    """
+
+    def __init__(
+        self,
+        registry: HandlerRegistry,
+        pipeline: MiddlewarePipeline | None = None,
+        enqueuer: ITaskEnqueuer | None = None,
+        serializer: ISerializer | None = None,
+    ) -> None:
+        self._registry = registry
+        self._pipeline = pipeline or MiddlewarePipeline()
+        self._enqueuer = enqueuer
+        self._serializer = serializer
+
+    async def dispatch(self, command: Command) -> t.Any:
+        cmd_type = type(command)
+        
+        # 1. Smart Routing: ¿Debe irse a background?
+        is_background = getattr(cmd_type, "__cqrs_background__", False)
+        
+        if is_background:
+            if not self._enqueuer or not self._serializer:
+                raise RuntimeError(
+                    f"El comando '{cmd_type.__name__}' requiere ejecución en background, "
+                    "pero el InMemoryCommandBus no tiene configurado un 'enqueuer' o 'serializer'."
+                )
+            
+            async def background_dispatcher(cmd: Command) -> None:
+                queue_name = getattr(cmd_type, "__cqrs_queue__", "default")
+                payload = self._serializer.serialize(cmd) # type: ignore
+                await self._enqueuer.enqueue_command(cmd_type.__name__, payload, queue=queue_name) # type: ignore
+                logger.debug("[SmartRouting] Comando %s enrutado a background (queue=%s)", cmd_type.__name__, queue_name)
+
+            await self._pipeline.execute(command, background_dispatcher)
+            return None
+
+        # 2. Ejecución Local Estándar
+        handler = self._registry.resolve_command_handler(cmd_type)
+
+        async def final_handler(cmd: t.Any) -> t.Any:
+            return await handler.handle(cmd)
+
+        return await self._pipeline.execute(command, final_handler)
+
+
+class InMemoryQueryBus(IQueryBus):
+    """
+    Bus de queries síncrono en memoria.
+    Las queries NUNCA pasan por buses asíncronos
+    (principio CQRS: las lecturas son siempre síncronas).
+    """
+
+    def __init__(
+        self,
+        registry: HandlerRegistry,
+        pipeline: MiddlewarePipeline | None = None,
+    ) -> None:
+        self._registry = registry
+        self._pipeline = pipeline or MiddlewarePipeline()
+
+    async def ask(self, query: Query[t.Any]) -> t.Any:
+        handler = self._registry.resolve_query_handler(type(query))
+
+        async def final_handler(q: t.Any) -> t.Any:
+            return await handler.handle(q)
+
+        return await self._pipeline.execute(query, final_handler)
+
+
+class InMemoryEventBus(IEventBus):
+    """
+    Bus de eventos en memoria con Smart Routing para Handlers Asíncronos.
+    
+    Permite publicar eventos a todos los suscriptores. Si un suscriptor
+    fue decorado con `@background_handler`, se enviará un mensaje al Task Queue
+    para que *solo* ese handler se ejecute en background para este evento.
+    """
+
+    def __init__(
+        self,
+        pipeline: MiddlewarePipeline | None = None,
+        enqueuer: ITaskEnqueuer | None = None,
+        serializer: ISerializer | None = None,
+    ) -> None:
+        self._handlers: dict[
+            type[DomainEvent],
+            list[t.Callable[[DomainEvent], t.Awaitable[None]]],
+        ] = {}
+        self._pipeline = pipeline or MiddlewarePipeline()
+        self._enqueuer = enqueuer
+        self._serializer = serializer
+
+    def subscribe(
+        self,
+        event_type: type[DomainEvent],
+        handler: t.Callable[[DomainEvent], t.Awaitable[None]],
+    ) -> None:
+        self._handlers.setdefault(event_type, []).append(handler)
+
+    async def publish(self, event: DomainEvent) -> None:
+        handlers = self._handlers.get(type(event), [])
+
+        for event_handler in handlers:
+            is_background = getattr(event_handler, "__cqrs_background_handler__", False)
+
+            if is_background:
+                # Enrutamiento hacia background
+                if not self._enqueuer or not self._serializer:
+                    raise RuntimeError(
+                        f"El handler de eventos '{event_handler.__name__}' requiere ejecución en background, "
+                        "pero el InMemoryEventBus no tiene configurado un 'enqueuer' o 'serializer'."
+                    )
+                
+                async def background_dispatcher(
+                    evt: t.Any,
+                    _h: t.Callable[..., t.Awaitable[None]] = event_handler,
+                ) -> None:
+                    handler_name = getattr(_h, "__cqrs_handler_name__")
+                    queue_name = getattr(_h, "__cqrs_queue__", "default")
+                    payload = self._serializer.serialize(evt) # type: ignore
+                    await self._enqueuer.enqueue_handler(handler_name, payload, queue=queue_name) # type: ignore
+                    logger.debug("[SmartRouting] EventHandler %s enrutado a background (queue=%s)", handler_name, queue_name)
+                    
+                await self._pipeline.execute(event, background_dispatcher)
+                
+            else:
+                # Ejecución local síncrona
+                async def final_handler(
+                    evt: t.Any,
+                    _h: t.Callable[..., t.Awaitable[None]] = event_handler,
+                ) -> None:
+                    await _h(evt)
+
+                await self._pipeline.execute(event, final_handler)

hexcore-2.4.0/hexcore/domain/cqrs/decorators.py

@@ -0,0 +1,78 @@
+"""
+Decoradores para habilitar el enrutamiento inteligente (Smart Routing) de tareas, comandos
+y manejadores de eventos hacia Task Queues (Celery, Procrastinate, etc.) de forma transparente.
+"""
+from __future__ import annotations
+
+import typing as t
+
+
+def background_command(queue: str = "default") -> t.Callable[[t.Type[t.Any]], t.Type[t.Any]]:
+    """
+    Decora una clase `Command` para indicar que su ejecución debe enviarse siempre
+    a un procesador en segundo plano (Task Queue).
+    
+    Cuando el CommandBus detecta este decorador, no ejecutará el comando localmente,
+    sino que llamará a `ITaskEnqueuer.enqueue_command()`.
+    
+    Ejemplo:
+        @background_command(queue="emails")
+        class SendEmailCommand(Command):
+            ...
+    """
+    def wrapper(cls: t.Type[t.Any]) -> t.Type[t.Any]:
+        cls.__cqrs_background__ = True
+        cls.__cqrs_queue__ = queue
+        return cls
+
+    return wrapper
+
+
+def background_handler(queue: str = "default") -> t.Callable[[t.Callable[..., t.Any]], t.Callable[..., t.Any]]:
+    """
+    Decora un manejador de eventos (Event Handler) para indicar que su ejecución
+    debe ocurrir de forma asíncrona en un Worker de background.
+    
+    Cuando el EventBus detecta este decorador en un handler suscrito, en lugar de
+    ejecutarlo directamente, delegará la tarea a `ITaskEnqueuer.enqueue_handler()`.
+    
+    Ejemplo:
+        @background_handler(queue="analytics")
+        async def on_user_created(event: UserCreatedEvent):
+            ...
+    """
+    def wrapper(func: t.Callable[..., t.Any]) -> t.Callable[..., t.Any]:
+        func.__cqrs_background_handler__ = True
+        func.__cqrs_queue__ = queue
+        
+        # Guardamos el nombre calificado del handler para poder resolverlo luego en el Worker
+        if not hasattr(func, "__qualname__"):
+            func.__cqrs_handler_name__ = func.__name__
+        else:
+            func.__cqrs_handler_name__ = f"{func.__module__}.{func.__qualname__}"
+            
+        return func
+
+    return wrapper
+
+
+def background_task(queue: str = "default") -> t.Callable[[t.Callable[..., t.Any]], t.Callable[..., t.Any]]:
+    """
+    Decora una función genérica para convertirla en una Tarea de Background
+    (independiente de CQRS).
+    
+    La función original queda marcada, y puede ser registrada en el
+    `TaskManager` de HexCore o ejecutada directamente usando el `ITaskEnqueuer`.
+    """
+    def wrapper(func: t.Callable[..., t.Any]) -> t.Callable[..., t.Any]:
+        func.__cqrs_background_task__ = True
+        func.__cqrs_queue__ = queue
+        
+        if not hasattr(func, "__qualname__"):
+            func.__cqrs_task_name__ = func.__name__
+        else:
+            func.__cqrs_task_name__ = f"{func.__module__}.{func.__qualname__}"
+            
+        return func
+
+    return wrapper

hexcore-2.4.0/hexcore/domain/cqrs/task_queues.py

@@ -0,0 +1,64 @@
+"""
+Interfaces fundamentales para delegar mensajes a Task Queues (Celery, Procrastinate, RQ, ARQ).
+"""
+from __future__ import annotations
+
+import abc
+import typing as t
+
+if t.TYPE_CHECKING:
+    pass
+
+
+class ITaskEnqueuer(abc.ABC):
+    """
+    Puerto (Puerto de Salida) genérico para encolar tareas asíncronas
+    o en paralelo hacia un backend de colas de mensajes (Task Queue).
+    
+    Un adaptador concreto (ej. `CeleryTaskEnqueuer`) usará la SDK
+    nativa del worker para empujar el `payload`.
+    """
+
+    @abc.abstractmethod
+    async def enqueue_command(self, command_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        """
+        Encola un comando de dominio serializado para ser ejecutado en background.
+        
+        Args:
+            command_name: Nombre calificado del comando (e.g. 'CreateUserCommand').
+            payload: Payload pre-serializado.
+            queue: Nombre de la cola de destino.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def enqueue_event(self, event_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        """
+        Encola un evento de dominio serializado para ser distribuido genéricamente.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def enqueue_handler(self, handler_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        """
+        Encola la ejecución de un *Event Handler Específico* para un evento.
+        Esto permite que un Evento dispare handlers asíncronos individuales.
+        
+        Args:
+            handler_name: Nombre calificado del handler (func.__cqrs_handler_name__).
+            payload: Payload pre-serializado del evento.
+            queue: Nombre de la cola.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def enqueue_task(self, task_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        """
+        Encola una tarea genérica de background (independiente de CQRS).
+        
+        Args:
+            task_name: Nombre calificado de la tarea (func.__cqrs_task_name__).
+            payload: Argumentos serializados para la tarea.
+            queue: Nombre de la cola.
+        """
+        raise NotImplementedError