@vytches/ddd-messaging 0.27.0 → 0.28.0

package/README.md

@@ -1,1113 +1,154 @@
 # @vytches/ddd-messaging
 
-<!-- LLM-METADATA
-Package: @vytches/ddd-messaging
-Category: Integration
-Purpose: Outbox pattern and Saga orchestration for reliable message delivery and long-running business processes
-Dependencies: @vytches/ddd-core, @vytches/ddd-events, @vytches/ddd-logging
-Complexity: High
-DDD Patterns: Outbox Pattern, Saga Pattern, Message Passing, Event-Driven Architecture
-Integration Points: @vytches/ddd-events, @vytches/ddd-repositories, @vytches/ddd-logging, @vytches/ddd-di
--->
-
 [![npm version](https://badge.fury.io/js/%40vytches%2Fddd-messaging.svg)](https://badge.fury.io/js/%40vytches%2Fddd-messaging)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Enterprise-grade messaging patterns with outbox pattern and saga
-> orchestration for reliable message delivery**
-
-Complete messaging solution with outbox pattern for reliable message delivery,
-saga orchestration for long-running business processes, and comprehensive
-middleware support. Designed for distributed systems requiring guaranteed
-message delivery and complex workflow orchestration.
-
-## 📋 Table of Contents
+> **Transactional Outbox pattern for reliable domain event delivery**
 
-- [Installation](#installation)
-- [Key Features](#key-features)
-- [Core Concepts](#core-concepts)
-- [Quick Start](#quick-start)
-- [Outbox Pattern](#outbox-pattern)
-- [Saga Pattern](#saga-pattern)
-- [Message Processing](#message-processing)
-- [Middleware](#middleware)
-- [Error Handling](#error-handling)
-- [Monitoring](#monitoring)
-- [Integration Patterns](#integration-patterns)
-- [Testing](#testing)
-- [Best Practices](#best-practices)
-- [Contributing](#contributing)
+Provides the Outbox pattern — store-then-publish guarantee for domain events.
+This package contains **only Outbox** infrastructure. There is no Saga support.
 
-## 🚀 Installation
+## Installation
 
 ```bash
-# npm
-npm install @vytches/ddd-messaging
-
-# yarn
-yarn add @vytches/ddd-messaging
-
-# pnpm
 pnpm add @vytches/ddd-messaging
 ```
 
-### Peer Dependencies
-
-```bash
-# Required for full functionality
-npm install @vytches/ddd-core @vytches/ddd-events @vytches/ddd-logging
-```
-
-## ✨ Key Features
-
-### Outbox Pattern
-
-- **Reliable Delivery**: Guaranteed message delivery with transactional outbox
-- **Priority Processing**: Configurable message priorities
-  (LOW/NORMAL/HIGH/CRITICAL)
-- **Delayed Messages**: Support for scheduled message processing
-- **Batch Operations**: Efficient bulk message handling
-
-### Saga Orchestration
-
-- **Long-running Processes**: Complete saga orchestration for complex business
-  workflows
-- **Compensation Logic**: Automatic compensation for failed transactions
-- **State Management**: Persistent saga state with optimistic concurrency
-  control
-- **Correlation Support**: Event correlation for distributed process tracking
-
-### Enterprise Features
-
-- **Middleware Pipeline**: Extensible message processing pipeline
-- **Retry Logic**: Configurable retry policies with exponential backoff
-- **Circuit Breaker**: Fault tolerance with circuit breaker pattern
-- **Monitoring**: Comprehensive metrics and observability
-
-## 🎯 Core Concepts
-
-### Outbox Pattern
-
-The outbox pattern ensures reliable message delivery by storing messages in a
-transactional outbox:
-
-```typescript
-// Message interface
-interface IOutboxMessage<T = unknown> {
-  id: string;
-  messageType: string;
-  payload: T;
-  metadata: Record<string, unknown>;
-  status: MessageStatus;
-  attempts: number;
-  createdAt: Date;
-  processAfter?: Date;
-  priority?: MessagePriority;
-  lastError?: string;
-}
-
-// Message statuses
-enum MessageStatus {
-  PENDING = 'PENDING',
-  PROCESSING = 'PROCESSING',
-  PROCESSED = 'PROCESSED',
-  FAILED = 'FAILED',
-}
-
-// Priority levels
-enum MessagePriority {
-  LOW = 'low',
-  NORMAL = 'normal',
-  HIGH = 'high',
-  CRITICAL = 'critical',
-}
-```
-
-### Saga Pattern
+## What's included
 
-Sagas orchestrate long-running business processes with compensation support:
+| Export                   | Kind           | Description                                                     |
+| ------------------------ | -------------- | --------------------------------------------------------------- |
+| `MessageStatus`          | enum           | `PENDING \| PROCESSING \| PROCESSED \| FAILED`                  |
+| `MessagePriority`        | enum           | `LOW \| NORMAL \| HIGH \| CRITICAL`                             |
+| `OutboxMessageFactory`   | class          | Creates `IOutboxMessage` instances                              |
+| `OutboxProcessor`        | class          | Polls the repository and dispatches messages                    |
+| `EventBusOutboxHandler`  | class          | `IOutboxMessageHandler` that publishes to an `IEventBus`        |
+| `OutboxService`          | class          | High-level facade: store, schedule, and coordinate processing   |
+| `IOutboxRepository`      | abstract class | Base repository contract — extend this for your storage backend |
+| `IOutboxMessage`         | interface      | Message shape with id, payload, status, priority, timestamps    |
+| `IOutboxMessageHandler`  | interface      | Single-method handler: `handle(message): Promise<void>`         |
+| `OutboxMiddleware`       | type           | Middleware signature for the processor pipeline                 |
+| `OutboxProcessorOptions` | interface      | Processor configuration (interval, batch size, retries…)        |
+| `OutboxServiceOptions`   | interface      | Service configuration                                           |
+| `OutboxMessageOptions`   | interface      | Per-message options (priority, processAfter…)                   |
+| `RetryBackoffConfig`     | interface      | Exponential backoff configuration for the processor             |
 
-```typescript
-// Saga interface
-interface ISaga {
-  readonly sagaId: string;
-  readonly sagaType: string;
-  readonly status: SagaStatus;
-  readonly state: ISagaState;
-
-  handleEvent(
-    event: IDomainEvent,
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult>;
-  compensate(
-    stepName: string,
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult>;
-  canHandle(event: IDomainEvent): boolean;
-  getCorrelationData(): Record<string, unknown>;
-}
-
-// Saga statuses
-enum SagaStatus {
-  STARTED = 'STARTED',
-  EXECUTING = 'EXECUTING',
-  WAITING = 'WAITING',
-  COMPLETED = 'COMPLETED',
-  FAILED = 'FAILED',
-  COMPENSATING = 'COMPENSATING',
-  COMPENSATED = 'COMPENSATED',
-  CANCELLED = 'CANCELLED',
-  TIMED_OUT = 'TIMED_OUT',
-}
-```
-
-## 🚀 Quick Start
-
-### Basic Outbox Usage
+## Quick start
 
 ```typescript
 import {
   OutboxService,
   OutboxProcessor,
   OutboxMessageFactory,
+  EventBusOutboxHandler,
   MessagePriority,
 } from '@vytches/ddd-messaging';
+import { UnifiedEventBus } from '@vytches/ddd-events';
 
-// Create outbox service
-const outboxService = new OutboxService({
-  maxRetries: 3,
-  retryDelay: 1000,
-  batchSize: 100,
-});
-
-// Create and store a message
-const messageFactory = new OutboxMessageFactory();
-const message = messageFactory.createMessage({
-  messageType: 'OrderCreated',
-  payload: { orderId: '123', customerId: '456' },
-  priority: MessagePriority.HIGH,
-  metadata: { source: 'OrderService' },
-});
-
-await outboxService.storeMessage(message);
-
-// Process messages
-const processor = new OutboxProcessor(outboxService, {
-  processingInterval: 5000,
-  maxConcurrency: 10,
-});
-
-await processor.start();
-```
-
-### Basic Saga Usage
-
-```typescript
-import {
-  BaseSaga,
-  SagaOrchestrator,
-  InMemorySagaRepository,
-  Saga,
-  SagaEventHandler,
-} from '@vytches/ddd-messaging';
-
-// Define a saga
-@Saga('OrderProcessingSaga')
-class OrderProcessingSaga extends BaseSaga {
-  constructor(sagaId: string, correlationId: string) {
-    super(
-      {
-        sagaId,
-        sagaType: 'OrderProcessingSaga',
-        status: SagaStatus.STARTED,
-        currentStep: 'ProcessPayment',
-        stepData: {},
-        compensationData: {},
-        correlationId,
-        metadata: {},
-        createdAt: new Date(),
-        updatedAt: new Date(),
-        timeoutAt: undefined,
-        version: 1,
-      },
-      'OrderProcessingSaga'
-    );
-  }
-
-  @SagaEventHandler('OrderCreated')
-  async handleOrderCreated(
-    event: IDomainEvent,
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult> {
-    // Process order creation
-    this.updateState({
-      currentStep: 'ProcessPayment',
-      stepData: { orderId: event.payload.orderId },
-    });
-
-    return {
-      success: true,
-      commands: [{ type: 'ProcessPayment', payload: event.payload }],
-      events: [{ eventType: 'PaymentRequested', payload: event.payload }],
-    };
-  }
-
-  @SagaEventHandler('PaymentProcessed')
-  async handlePaymentProcessed(
-    event: IDomainEvent,
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult> {
-    // Process payment completion
-    this.updateState({
-      currentStep: 'ReserveInventory',
-      stepData: { ...this.state.stepData, paymentId: event.payload.paymentId },
-    });
-
-    return {
-      success: true,
-      commands: [{ type: 'ReserveInventory', payload: event.payload }],
-      completesSaga: false,
-    };
-  }
-
-  async compensate(
-    stepName: string,
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult> {
-    switch (stepName) {
-      case 'ProcessPayment':
-        return await this.refundPayment(context);
-      case 'ReserveInventory':
-        return await this.releaseInventory(context);
-      default:
-        return { success: true };
-    }
+// Implement IOutboxRepository for your storage (e.g. PostgreSQL)
+class PostgresOutboxRepository extends IOutboxRepository {
+  async save(message) {
+    /* ... */
   }
-
-  canHandle(event: IDomainEvent): boolean {
-    return ['OrderCreated', 'PaymentProcessed', 'InventoryReserved'].includes(
-      event.eventType
-    );
+  async findPending(limit) {
+    /* ... */
   }
-
-  private async refundPayment(
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult> {
-    // Implement refund logic
-    return { success: true };
+  async markProcessed(id) {
+    /* ... */
   }
-
-  private async releaseInventory(
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult> {
-    // Implement inventory release logic
-    return { success: true };
+  async markFailed(id, error) {
+    /* ... */
   }
 }
-```
 
-### Saga Orchestration
-
-```typescript
-import {
-  SagaOrchestrator,
-  InMemorySagaRepository,
-} from '@vytches/ddd-messaging';
+const repository = new PostgresOutboxRepository();
+const eventBus = new UnifiedEventBus();
 
-// Setup saga infrastructure
-const sagaRepository = new InMemorySagaRepository();
-const orchestrator = new SagaOrchestrator(sagaRepository, {
-  maxConcurrentExecutions: 50,
-  enableMetrics: true,
-  enableAutoRetry: true,
+// Service stores messages, processor dispatches them
+const service = new OutboxService(repository);
+const handler = new EventBusOutboxHandler(eventBus);
+const processor = new OutboxProcessor(repository, handler, {
+  processingInterval: 5_000,
+  batchSize: 50,
+  maxRetries: 3,
 });
 
-// Register saga definition
-const orderSagaDefinition = {
-  sagaType: 'OrderProcessingSaga',
-  displayName: 'Order Processing Workflow',
-  description: 'Handles complete order processing with compensation',
-  startEvents: ['OrderCreated'],
-  defaultTimeout: 3600000, // 1 hour
-  maxInstances: 100,
-  steps: [],
-  createInstance: async (event, context) =>
-    new OrderProcessingSaga(generateId(), event.correlationId || generateId()),
-  getCorrelationData: event => ({ orderId: event.payload.orderId }),
-  validate: () => [],
-};
-
-orchestrator.registerSagaDefinition(orderSagaDefinition);
-
-// Process events
-const event = createOrderCreatedEvent();
-const context = {
-  correlationId: 'order-123',
-  userId: 'user-456',
-  metadata: {},
-  timestamp: new Date(),
-};
-
-const results = await orchestrator.processEvent(event, context);
-```
-
-## 📦 Outbox Pattern
-
-### Message Creation
-
-```typescript
-import { OutboxMessageFactory, MessagePriority } from '@vytches/ddd-messaging';
-
+// Store a message (call this inside your aggregate save transaction)
 const factory = new OutboxMessageFactory();
-
-// Create immediate message
-const message = factory.createMessage({
-  messageType: 'UserRegistered',
-  payload: { userId: '123', email: 'user@example.com' },
+const message = factory.create({
+  messageType: 'OrderCreated',
+  payload: { orderId: '123' },
   priority: MessagePriority.HIGH,
-  metadata: { source: 'UserService' },
-});
-
-// Create delayed message
-const delayedMessage = factory.createMessage({
-  messageType: 'SendWelcomeEmail',
-  payload: { userId: '123' },
-  processAfter: new Date(Date.now() + 60000), // 1 minute delay
-});
-
-// Create batch of messages
-const messages = factory.createBatch([
-  { messageType: 'Event1', payload: { data: 'test1' } },
-  { messageType: 'Event2', payload: { data: 'test2' } },
-  { messageType: 'Event3', payload: { data: 'test3' } },
-]);
-```
-
-### Custom Message Handler
-
-```typescript
-import { IOutboxMessageHandler, IOutboxMessage } from '@vytches/ddd-messaging';
-
-class EmailMessageHandler implements IOutboxMessageHandler {
-  async handle(message: IOutboxMessage): Promise<void> {
-    switch (message.messageType) {
-      case 'SendWelcomeEmail':
-        await this.sendWelcomeEmail(message.payload);
-        break;
-      case 'SendPasswordResetEmail':
-        await this.sendPasswordResetEmail(message.payload);
-        break;
-      default:
-        throw new Error(`Unknown message type: ${message.messageType}`);
-    }
-  }
-
-  private async sendWelcomeEmail(payload: any): Promise<void> {
-    // Email sending logic
-    console.log('Sending welcome email to:', payload.email);
-  }
-
-  private async sendPasswordResetEmail(payload: any): Promise<void> {
-    // Password reset email logic
-    console.log('Sending password reset email to:', payload.email);
-  }
-}
-```
-
-### Processing Configuration
-
-```typescript
-import { OutboxProcessor, OutboxService } from '@vytches/ddd-messaging';
-
-const processor = new OutboxProcessor(outboxService, {
-  processingInterval: 5000, // Process every 5 seconds
-  maxConcurrency: 10, // Process up to 10 messages concurrently
-  maxRetries: 3, // Retry failed messages up to 3 times
-  retryDelay: 1000, // Wait 1 second between retries
-  batchSize: 100, // Process 100 messages per batch
-  enableMetrics: true, // Enable performance metrics
-  errorHandler: (error, message) => {
-    console.error('Message processing failed:', error);
-  },
 });
+await service.store(message);
 
+// Start polling
 await processor.start();
 ```
 
-## 🎭 Saga Pattern
-
-### Saga Definition
+## Custom message handler
 
-```typescript
-import {
-  BaseSaga,
-  SagaDefinition,
-  SagaStep,
-  SagaStatus,
-} from '@vytches/ddd-messaging';
-
-const orderProcessingDefinition = new SagaDefinition({
-  sagaType: 'OrderProcessingSaga',
-  displayName: 'Order Processing Workflow',
-  description:
-    'Comprehensive order processing with payment, inventory, and shipping',
-  startEvents: ['OrderCreated'],
-  defaultTimeout: 3600000,
-  maxInstances: 1000,
-  steps: [
-    new SagaStep({
-      name: 'ProcessPayment',
-      displayName: 'Process Payment',
-      compensatable: true,
-      timeout: 30000,
-      triggerEvents: ['OrderCreated'],
-      completionEvents: ['PaymentProcessed', 'PaymentFailed'],
-    }),
-    new SagaStep({
-      name: 'ReserveInventory',
-      displayName: 'Reserve Inventory',
-      compensatable: true,
-      timeout: 15000,
-      triggerEvents: ['PaymentProcessed'],
-      completionEvents: ['InventoryReserved', 'InventoryNotAvailable'],
-    }),
-    new SagaStep({
-      name: 'ArrangeShipping',
-      displayName: 'Arrange Shipping',
-      compensatable: true,
-      timeout: 60000,
-      triggerEvents: ['InventoryReserved'],
-      completionEvents: ['ShippingArranged', 'ShippingFailed'],
-    }),
-  ],
-});
-```
-
-### Saga State Management
+Implement `IOutboxMessageHandler` to route messages any way you like:
 
 ```typescript
-class OrderProcessingSaga extends BaseSaga {
-  protected updateState(updates: Partial<ISagaState>): void {
-    this._state = {
-      ...this._state,
-      ...updates,
-      updatedAt: new Date(),
-      version: this._state.version + 1,
-    };
-  }
-
-  protected addCompensationData(
-    stepName: string,
-    data: Record<string, unknown>
-  ): void {
-    this._state.compensationData[stepName] = data;
-  }
-
-  protected getCompensationData(
-    stepName: string
-  ): Record<string, unknown> | undefined {
-    return this._state.compensationData[stepName];
-  }
-
-  protected markCompleted(): void {
-    this.updateState({
-      status: SagaStatus.COMPLETED,
-      currentStep: 'COMPLETED',
-    });
-  }
+import { IOutboxMessageHandler, IOutboxMessage } from '@vytches/ddd-messaging';
 
-  protected markFailed(error: string, step: string): void {
-    this.updateState({
-      status: SagaStatus.FAILED,
-      error: {
-        message: error,
-        step,
-        timestamp: new Date(),
-      },
+class KafkaMessageHandler implements IOutboxMessageHandler {
+  async handle(message: IOutboxMessage): Promise<void> {
+    await kafkaProducer.send({
+      topic: message.messageType,
+      messages: [{ value: JSON.stringify(message.payload) }],
     });
   }
 }
 ```
 
-### Saga Repository
-
-```typescript
-import { InMemorySagaRepository } from '@vytches/ddd-messaging';
-
-// Create repository with configuration
-const repository = new InMemorySagaRepository({
-  enableOptimisticLocking: true,
-  enableAuditLog: true,
-  retentionPolicy: {
-    completedAfterDays: 30,
-    compensatedAfterDays: 60,
-    failedAfterDays: 90,
-  },
-});
-
-// Save saga state
-await repository.save(sagaInstance);
-
-// Find sagas by correlation
-const relatedSagas = await repository.findByCorrelation({
-  orderId: 'order-123',
-});
-
-// Find timed out sagas
-const timedOutSagas = await repository.findTimedOut(new Date());
-
-// Query sagas with criteria
-const queryResult = await repository.query({
-  sagaType: 'OrderProcessingSaga',
-  status: [SagaStatus.STARTED, SagaStatus.EXECUTING],
-  createdBetween: { start: yesterday, end: today },
-  limit: 50,
-  sortBy: 'createdAt',
-  sortOrder: 'desc',
-});
-```
-
-## 🔧 Middleware
+## Implement your repository
 
-### Built-in Middleware
+Extend `IOutboxRepository` and provide persistence:
 
 ```typescript
 import {
-  RetryMiddleware,
-  CircuitBreakerMiddleware,
-  PerformanceMonitoringMiddleware,
-  SecurityMiddleware,
+  IOutboxRepository,
+  IOutboxMessage,
+  MessageStatus,
 } from '@vytches/ddd-messaging';
 
-// Retry middleware
-const retryMiddleware = new RetryMiddleware({
-  maxAttempts: 3,
-  baseDelay: 1000,
-  maxDelay: 30000,
-  retryCondition: error => error.code === 'TRANSIENT_ERROR',
-});
-
-// Circuit breaker middleware
-const circuitBreakerMiddleware = new CircuitBreakerMiddleware({
-  failureThreshold: 5,
-  resetTimeout: 60000,
-  monitoredServices: ['payment-service', 'inventory-service'],
-});
-
-// Performance monitoring
-const performanceMiddleware = new PerformanceMonitoringMiddleware({
-  enableMetrics: true,
-  slowExecutionThreshold: 5000,
-  memoryUsageTracking: true,
-});
-
-// Security middleware
-const securityMiddleware = new SecurityMiddleware({
-  validateCorrelationId: true,
-  requireAuthentication: true,
-  allowedOrigins: ['order-service', 'payment-service'],
-});
-```
-
-### Custom Middleware
-
-```typescript
-import { BaseSagaMiddleware } from '@vytches/ddd-messaging';
-
-class AuditMiddleware extends BaseSagaMiddleware {
-  async execute(
-    saga: ISaga,
-    event: IDomainEvent,
-    context: ISagaExecutionContext,
-    next: () => Promise<ISagaActionResult>
-  ): Promise<ISagaActionResult> {
-    // Pre-execution audit
-    await this.auditService.logSagaExecution({
-      sagaId: saga.sagaId,
-      sagaType: saga.sagaType,
-      eventType: event.eventType,
-      correlationId: context.correlationId,
-      timestamp: new Date(),
-    });
-
-    try {
-      const result = await next();
-
-      // Post-execution audit
-      await this.auditService.logSagaResult({
-        sagaId: saga.sagaId,
-        success: result.success,
-        timestamp: new Date(),
-      });
-
-      return result;
-    } catch (error) {
-      // Error audit
-      await this.auditService.logSagaError({
-        sagaId: saga.sagaId,
-        error: error.message,
-        timestamp: new Date(),
-      });
-
-      throw error;
-    }
+class MyOutboxRepository extends IOutboxRepository {
+  async save(message: IOutboxMessage): Promise<void> {
+    await db.outbox.insert(message);
   }
-}
-```
-
-## 🏥 Error Handling
-
-### Saga Error Handling
-
-```typescript
-import {
-  SagaError,
-  SagaExecutionError,
-  SagaCompensationError,
-} from '@vytches/ddd-messaging';
-
-class OrderProcessingSaga extends BaseSaga {
-  async handleEvent(
-    event: IDomainEvent,
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult> {
-    try {
-      return await this.processEvent(event, context);
-    } catch (error) {
-      if (error instanceof SagaExecutionError) {
-        // Handle execution errors
-        this.markFailed(error.message, this.state.currentStep);
-
-        if (error.requiresCompensation) {
-          return await this.startCompensation(context);
-        }
-      }
 
-      throw error;
-    }
+  async findPendingMessages(limit: number): Promise<IOutboxMessage[]> {
+    return db.outbox.findWhere({ status: MessageStatus.PENDING }, limit);
   }
 
-  private async startCompensation(
-    context: ISagaExecutionContext
-  ): Promise<ISagaActionResult> {
-    this.updateState({ status: SagaStatus.COMPENSATING });
-
-    // Execute compensation in reverse order
-    const completedSteps = this.getCompletedSteps();
-
-    for (const step of completedSteps.reverse()) {
-      try {
-        await this.compensateStep(step, context);
-      } catch (compensationError) {
-        throw new SagaCompensationError(
-          `Compensation failed for step ${step}`,
-          { step, originalError: compensationError }
-        );
-      }
-    }
-
-    this.updateState({ status: SagaStatus.COMPENSATED });
-
-    return { success: true };
+  async markAsProcessed(id: string): Promise<void> {
+    await db.outbox.update(id, { status: MessageStatus.PROCESSED });
   }
-}
-```
 
-### Outbox Error Handling
-
-```typescript
-import { OutboxProcessor } from '@vytches/ddd-messaging';
-
-const processor = new OutboxProcessor(outboxService, {
-  errorHandler: async (error, message) => {
-    console.error(`Failed to process message ${message.id}:`, error);
-
-    // Custom error handling logic
-    if (error.code === 'RATE_LIMIT_EXCEEDED') {
-      // Reschedule message for later
-      message.processAfter = new Date(Date.now() + 60000);
-      await outboxService.updateMessage(message);
-    } else if (error.code === 'PERMANENT_FAILURE') {
-      // Move to dead letter queue
-      await deadLetterService.store(message, error);
-    }
-  },
-  deadLetterHandler: async (message, error) => {
-    // Handle messages that exceed retry limit
-    await deadLetterService.store(message, error);
-    await notificationService.notifyAdmins({
-      type: 'DEAD_LETTER_MESSAGE',
-      messageId: message.id,
-      error: error.message,
+  async markAsFailed(id: string, error: string): Promise<void> {
+    await db.outbox.update(id, {
+      status: MessageStatus.FAILED,
+      lastError: error,
     });
-  },
-});
-```
-
-## 📊 Monitoring
-
-### Saga Metrics
-
-```typescript
-import { SagaOrchestrator } from '@vytches/ddd-messaging';
-
-const orchestrator = new SagaOrchestrator(repository, {
-  enableMetrics: true,
-  metricsConfig: {
-    collectExecutionTimes: true,
-    collectMemoryUsage: true,
-    collectCorrelationStats: true,
-  },
-});
-
-// Get comprehensive statistics
-const stats = await orchestrator.getStatistics();
-console.log('Saga Statistics:', {
-  totalInstances: stats.totalInstances,
-  activeInstances: stats.activeInstances,
-  completedInstances: stats.completedInstances,
-  failedInstances: stats.failedInstances,
-  averageExecutionTime: stats.averageExecutionTime,
-  memoryUsage: stats.memoryUsage,
-});
-
-// Get metrics by saga type
-const typeMetrics = await orchestrator.getMetricsBySagaType(
-  'OrderProcessingSaga'
-);
-console.log('Order Processing Metrics:', {
-  instanceCount: typeMetrics.instanceCount,
-  successRate: typeMetrics.successRate,
-  averageSteps: typeMetrics.averageSteps,
-  compensationRate: typeMetrics.compensationRate,
-});
-```
-
-### Performance Monitoring
-
-```typescript
-import { PerformanceMonitoringMiddleware } from '@vytches/ddd-messaging';
-
-const performanceMiddleware = new PerformanceMonitoringMiddleware({
-  enableMetrics: true,
-  slowExecutionThreshold: 5000,
-  memoryUsageTracking: true,
-  customMetrics: {
-    trackCorrelationCounts: true,
-    trackEventProcessingTimes: true,
-    trackCompensationRates: true,
-  },
-});
-
-// Get performance metrics
-const metrics = performanceMiddleware.getMetrics();
-console.log('Performance Metrics:', {
-  totalExecutions: metrics.totalExecutions,
-  averageExecutionTime: metrics.averageExecutionTime,
-  slowExecutions: metrics.slowExecutions,
-  memoryUsage: metrics.memoryUsage,
-  errorRate: metrics.errorRate,
-});
-```
-
-## 🔗 Integration Patterns
-
-### Event-Driven Integration
-
-```typescript
-import { EventBusOutboxHandler } from '@vytches/ddd-messaging';
-import { UnifiedEventBus } from '@vytches/ddd-events';
-
-// Integrate outbox with event bus
-const eventBus = new UnifiedEventBus();
-const outboxHandler = new EventBusOutboxHandler(eventBus);
-
-// Register handler for specific message types
-outboxHandler.registerHandler('DomainEvent', async message => {
-  const domainEvent = message.payload;
-  await eventBus.publish(domainEvent);
-});
-
-// Process outbox messages through event bus
-const processor = new OutboxProcessor(outboxService, {
-  messageHandler: outboxHandler,
-});
-```
-
-### Repository Integration
-
-```typescript
-import { OutboxService } from '@vytches/ddd-messaging';
-import { IBaseRepository } from '@vytches/ddd-repositories';
-
-class OrderRepository extends IBaseRepository<OrderAggregate> {
-  constructor(
-    private outboxService: OutboxService,
-    eventDispatcher: IEventDispatcher
-  ) {
-    super(eventDispatcher);
-  }
-
-  async save(order: OrderAggregate): Promise<void> {
-    // Save aggregate
-    await super.save(order);
-
-    // Store events in outbox for reliable delivery
-    const events = order.getUncommittedEvents();
-
-    for (const event of events) {
-      const message = OutboxMessageFactory.fromDomainEvent(event);
-      await this.outboxService.storeMessage(message);
-    }
   }
 }
 ```
 
-### CQRS Integration
+## Package boundaries
 
-```typescript
-import { CommandHandler, QueryHandler } from '@vytches/ddd-cqrs';
-import { SagaOrchestrator } from '@vytches/ddd-messaging';
-
-@CommandHandler(ProcessOrderCommand)
-class ProcessOrderHandler {
-  constructor(private sagaOrchestrator: SagaOrchestrator) {}
-
-  async execute(command: ProcessOrderCommand): Promise<void> {
-    // Create order processing saga
-    const event = new OrderCreatedEvent(command.orderData);
-    const context = {
-      correlationId: command.correlationId,
-      userId: command.userId,
-      metadata: { source: 'OrderService' },
-      timestamp: new Date(),
-    };
-
-    await this.sagaOrchestrator.processEvent(event, context);
-  }
-}
-```
-
-## 🧪 Testing
-
-### Saga Testing
-
-```typescript
-import { describe, it, expect, beforeEach } from 'vitest';
-import { safeRun } from '@vytches/ddd-utils';
-import { OrderProcessingSaga } from '../src/order-processing-saga';
-import { SagaStatus } from '@vytches/ddd-messaging';
-
-describe('OrderProcessingSaga', () => {
-  let saga: OrderProcessingSaga;
-  let context: ISagaExecutionContext;
-
-  beforeEach(() => {
-    saga = new OrderProcessingSaga('saga-123', 'correlation-456');
-    context = {
-      correlationId: 'correlation-456',
-      userId: 'user-123',
-      metadata: {},
-      timestamp: new Date(),
-    };
-  });
-
-  describe('handleOrderCreated', () => {
-    it('should transition to payment processing', async () => {
-      const event = createOrderCreatedEvent();
-
-      const [error, result] = await safeRun(
-        async () => await saga.handleEvent(event, context)
-      );
-
-      expect(error).toBeUndefined();
-      expect(result.success).toBe(true);
-      expect(saga.state.currentStep).toBe('ProcessPayment');
-      expect(result.commands).toHaveLength(1);
-      expect(result.commands[0].type).toBe('ProcessPayment');
-    });
-
-    it('should handle invalid event gracefully', async () => {
-      const invalidEvent = createInvalidEvent();
-
-      const [error] = await safeRun(
-        async () => await saga.handleEvent(invalidEvent, context)
-      );
-
-      expect(error).toBeInstanceOf(SagaEventProcessingError);
-      expect(error?.message).toContain('Cannot handle event');
-    });
-  });
-
-  describe('compensation', () => {
-    it('should execute compensation for completed steps', async () => {
-      // Setup saga with completed payment step
-      saga.updateState({
-        currentStep: 'ReserveInventory',
-        stepData: { paymentId: 'payment-123' },
-        compensationData: {
-          ProcessPayment: { paymentId: 'payment-123' },
-        },
-      });
-
-      const [error, result] = await safeRun(
-        async () => await saga.compensate('ProcessPayment', context)
-      );
-
-      expect(error).toBeUndefined();
-      expect(result.success).toBe(true);
-    });
-  });
-});
-```
-
-### Outbox Testing
-
-```typescript
-import { describe, it, expect, beforeEach } from 'vitest';
-import { safeRun } from '@vytches/ddd-utils';
-import {
-  OutboxService,
-  OutboxMessageFactory,
-  MessageStatus,
-} from '@vytches/ddd-messaging';
-
-describe('OutboxService', () => {
-  let service: OutboxService;
-  let factory: OutboxMessageFactory;
-
-  beforeEach(() => {
-    service = new OutboxService();
-    factory = new OutboxMessageFactory();
-  });
-
-  describe('storeMessage', () => {
-    it('should store message successfully', async () => {
-      const message = factory.createMessage({
-        messageType: 'TestEvent',
-        payload: { data: 'test' },
-      });
-
-      const [error] = await safeRun(
-        async () => await service.storeMessage(message)
-      );
-
-      expect(error).toBeUndefined();
-
-      const stored = await service.getMessageById(message.id);
-      expect(stored).toBeDefined();
-      expect(stored?.status).toBe(MessageStatus.PENDING);
-    });
-
-    it('should handle duplicate message IDs', async () => {
-      const message = factory.createMessage({
-        messageType: 'TestEvent',
-        payload: { data: 'test' },
-      });
-
-      await service.storeMessage(message);
-
-      const [duplicateError] = await safeRun(
-        async () => await service.storeMessage(message)
-      );
-
-      expect(duplicateError).toBeInstanceOf(OutboxError);
-      expect(duplicateError?.message).toContain('already exists');
-    });
-  });
-
-  describe('processMessages', () => {
-    it('should process pending messages', async () => {
-      const messages = [
-        factory.createMessage({
-          messageType: 'Event1',
-          payload: { data: '1' },
-        }),
-        factory.createMessage({
-          messageType: 'Event2',
-          payload: { data: '2' },
-        }),
-      ];
-
-      for (const message of messages) {
-        await service.storeMessage(message);
-      }
-
-      const processed = await service.processPendingMessages();
-      expect(processed).toBe(2);
-    });
-  });
-});
-```
-
-## 🎯 Best Practices
-
-### Saga Design
-
-1. **Keep Sagas Focused**: Each saga should handle a single business process
-2. **Design for Compensation**: Always plan compensation logic during design
-3. **Use Correlation IDs**: Properly correlate events and commands
-4. **Handle Timeouts**: Set appropriate timeouts for long-running processes
-5. **Monitor Saga Health**: Implement comprehensive monitoring and alerting
-
-### Message Design
-
-1. **Idempotent Operations**: Design message handlers to be idempotent
-2. **Small Message Payloads**: Keep message payloads small and focused
-3. **Structured Metadata**: Use consistent metadata structure
-4. **Priority Classification**: Properly classify message priorities
-5. **Error Context**: Include sufficient context for error handling
-
-### Performance Optimization
-
-1. **Batch Processing**: Process messages in batches when possible
-2. **Connection Pooling**: Use connection pooling for database operations
-3. **Async Processing**: Leverage async processing for better throughput
-4. **Resource Management**: Properly manage resources and connections
-5. **Monitoring**: Continuously monitor performance metrics
-
-### Error Handling
-
-1. **Graceful Degradation**: Design for graceful failure handling
-2. **Retry Logic**: Implement appropriate retry strategies
-3. **Dead Letter Queues**: Use dead letter queues for failed messages
-4. **Compensation Patterns**: Implement proper compensation patterns
-5. **Alerting**: Set up proper alerting for critical failures
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our
-[Contributing Guide](../../CONTRIBUTING.md) for details.
-
-### Development Setup
-
-```bash
-# Clone repository
-git clone https://github.com/vytches/ddd.git
-cd ddd
-
-# Install dependencies
-pnpm install
-
-# Run tests
-pnpm test
-
-# Build package
-pnpm build
-
-# Run messaging-specific tests
-pnpm test:packages:messaging
-```
+`@vytches/ddd-messaging` depends on:
 
-## 📄 License
+- `@vytches/ddd-contracts` — `IDomainEvent`, `IEventBus`
+- `@vytches/ddd-logging` — internal structured logging
 
-This project is licensed under the MIT License - see the
-[LICENSE](../../LICENSE) file for details.
+## Note on Sagas
 
----
+This package has **no Saga support**. For long-running process orchestration,
+use a dedicated library (e.g. Temporal, Conductor).
 
-**Part of the VytchesDDD Enterprise Suite**
+## License
 
-For more information about the complete VytchesDDD ecosystem, visit our
-[main documentation](../../README.md).
+MIT