@vytches/ddd-aggregates 0.26.0 → 0.28.0

package/README.md

@@ -1,1393 +1,206 @@
 # @vytches/ddd-aggregates
 
+> Aggregate root implementation with event sourcing, optimistic concurrency, and
+> opt-in capabilities.
+
 [![npm version](https://badge.fury.io/js/%40vytches%2Fddd-aggregates.svg)](https://badge.fury.io/js/%40vytches%2Fddd-aggregates)
 [![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 aggregate root implementations for Domain-Driven Design**
-
-Complete aggregate root implementation with built-in event sourcing, capability
-system, and automatic event management. Designed for complex domain models with
-strong consistency boundaries.
-
-## 📚 Detailed Documentation
-
-**NEW**: Enhanced Metadata System V2 with YAML Front Matter for AI-optimized
-documentation:
-
-- 🎯 **Generated JSDoc**: Full API documentation with hierarchical metadata
-  system
-- 📊 **Live Documentation**: View at `/docs/api/aggregates/index.html` after
-  running `pnpm jsdoc:publish`
-- 🧠 **AI-Optimized**: Structured metadata for LLM consumption and code
-  generation
-- ⚡ **Performance**: ~12s initial build, ~2s incremental, ~0.5s no changes
-
-**Core Documentation:**
-
-- 📖 **AggregateRoot Class** - Base aggregate implementation with event sourcing
-- 🔧 **AggregateBuilder Class** - Fluent builder for aggregates with
-  capabilities
-- 🛠️ **Utility Functions** - Type-safe capability management and utilities
-- 📋 **Error Classes** - Comprehensive aggregate-specific error handling
-
-> **Enhanced Metadata System V2** provides hierarchical documentation (Global →
-> Package → Class → Method) with format-specific content, custom tags, and
-> automatic example injection.
-
-## 📋 Table of Contents
-
-- [Installation](#installation)
-- [Key Features](#key-features)
-- [Core Concepts](#core-concepts)
-- [Quick Start](#quick-start)
-- [Advanced Features](#advanced-features)
-- [API Reference](#api-reference)
-- [Patterns & Best Practices](#patterns--best-practices)
-- [Event Sourcing](#event-sourcing)
-- [Capabilities](#capabilities)
-- [Testing](#testing)
-- [Performance](#performance)
-- [Contributing](#contributing)
-
-## 🚀 Installation
+## Installation
 
 ```bash
-# npm
-npm install @vytches/ddd-aggregates
-
-# yarn
-yarn add @vytches/ddd-aggregates
-
-# pnpm
 pnpm add @vytches/ddd-aggregates
 ```
 
-### Peer Dependencies
-
-```bash
-# Required for full functionality
-npm install @vytches/ddd-domain-primitives @vytches/ddd-events @vytches/ddd-utils
-```
-
-## ✨ Key Features
-
-### Aggregate Root Foundation
-
-- **Event Sourcing**: Built-in event sourcing with automatic event management
-- **Capability System**: Extensible capabilities for cross-cutting concerns
-- **Concurrency Control**: Optimistic concurrency with version management
-- **Snapshot Support**: Automatic snapshots for performance optimization
-
-### Enterprise Features
-
-- **Strong Consistency**: Aggregate consistency boundary enforcement
-- **Event Management**: Automatic event collection and publishing
-- **State Validation**: Built-in invariant validation
-- **Audit Trail**: Complete audit trail with event history
-
-### Developer Experience
-
-- **Type Safety**: Full TypeScript support with generic typing
-- **Fluent API**: Intuitive API for domain modeling
-- **Testing Support**: Built-in testing utilities and builders
-- **Documentation**: Comprehensive documentation and examples
+## What's included
 
-## 🎯 Core Concepts
+- **`AggregateRoot`** — base class for aggregate roots with identity,
+  versioning, and domain events
+- **`Entity`** — base class for non-root domain entities (identity-based
+  equality, no event machinery)
+- **`AggregateBuilder` / `aggregateBuilder`** — fluent builder for constructing
+  aggregates with capabilities
+- **Capabilities** — `AuditCapability`, `EventSourcingCapability`,
+  `SnapshotCapability`, `VersioningCapability`
+- **Utility functions** — type-safe capability casting and introspection
+- **`AggregateError`** — error class for aggregate-specific failures
 
-### Aggregate Root
-
-An aggregate root is the only member of an aggregate that outside objects are
-allowed to hold references to. It's the gatekeeper for the aggregate, ensuring
-consistency and managing the lifecycle of the aggregate.
-
-```typescript
-// Base aggregate root interface
-interface IAggregateRoot {
-  readonly id: EntityId;
-  readonly version: number;
-
-  // Event management
-  addDomainEvent(event: IDomainEvent): void;
-  getUncommittedEvents(): IDomainEvent[];
-  markEventsAsCommitted(): void;
-
-  // Capability system
-  addCapability<T extends IAggregateCapability>(capability: T): void;
-  getCapability<T extends IAggregateCapability>(type: new () => T): T | null;
-  hasCapability<T extends IAggregateCapability>(type: new () => T): boolean;
-
-  // Lifecycle
-  toSnapshot(): AggregateSnapshot;
-  fromSnapshot(snapshot: AggregateSnapshot): void;
-}
-```
-
-### Event Sourcing
-
-Event sourcing is a pattern where state changes are stored as a sequence of
-events. The current state is derived by replaying these events.
-
-```typescript
-// Event sourced aggregate
-abstract class EventSourcedAggregate extends AggregateRoot {
-  // Apply event to current state
-  protected apply(event: IDomainEvent): void;
-
-  // Replay events to rebuild state
-  static fromEventStream<T extends EventSourcedAggregate>(
-    events: IDomainEvent[]
-  ): T;
-
-  // Event handlers (implemented by subclasses)
-  protected abstract getEventHandlers(): EventHandlerMap;
-}
-```
-
-### Capabilities
-
-Capabilities are modular extensions that can be added to aggregates to provide
-cross-cutting concerns like auditing, caching, or validation.
+## Usage
 
 ```typescript
-// Capability interface
-interface IAggregateCapability {
-  readonly name: string;
-
-  // Lifecycle hooks
-  onEventApplied?(event: IDomainEvent): void;
-  onSnapshotCreated?(snapshot: AggregateSnapshot): void;
-  beforeSave?(): void;
-  afterSave?(): void;
-}
-```
+import { AggregateRoot } from '@vytches/ddd-aggregates';
+import type { IAggregateConstructorParams } from '@vytches/ddd-aggregates';
+import { EntityId } from '@vytches/ddd-contracts';
 
-## 🚀 Quick Start
+class Order extends AggregateRoot<string> {
+  private customerId = '';
+  private status: 'pending' | 'confirmed' = 'pending';
 
-### 1. Basic Aggregate Root
-
-```typescript
-import { AggregateRoot, EntityId } from '@vytches/ddd-aggregates';
-import { DomainEvent } from '@vytches/ddd-events';
-import { Result } from '@vytches/ddd-utils';
-
-// Domain events
-class OrderCreatedEvent extends DomainEvent<{
-  orderId: string;
-  customerId: string;
-  totalAmount: number;
-  currency: string;
-}> {
-  constructor(payload: OrderCreatedData) {
-    super(payload, undefined, 'OrderCreated');
-  }
-}
-
-class OrderItemAddedEvent extends DomainEvent<{
-  orderId: string;
-  productId: string;
-  quantity: number;
-  price: number;
-}> {
-  constructor(payload: OrderItemAddedData) {
-    super(payload, undefined, 'OrderItemAdded');
-  }
-}
-
-// Value objects
-class OrderStatus {
-  static readonly PENDING = new OrderStatus('PENDING');
-  static readonly CONFIRMED = new OrderStatus('CONFIRMED');
-  static readonly SHIPPED = new OrderStatus('SHIPPED');
-  static readonly DELIVERED = new OrderStatus('DELIVERED');
-  static readonly CANCELLED = new OrderStatus('CANCELLED');
-
-  private constructor(private readonly value: string) {}
-
-  equals(other: OrderStatus): boolean {
-    return this.value === other.value;
-  }
-
-  toString(): string {
-    return this.value;
-  }
-}
-
-// Aggregate root implementation
-class OrderAggregate extends AggregateRoot {
-  private customerId: EntityId;
-  private items: OrderItem[] = [];
-  private status: OrderStatus = OrderStatus.PENDING;
-  private totalAmount: number = 0;
-  private currency: string = 'USD';
-
-  private constructor(id: EntityId, customerId: EntityId) {
-    super(id);
-    this.customerId = customerId;
-  }
-
-  // Factory method
-  static create(customerId: EntityId): OrderAggregate {
-    const order = new OrderAggregate(EntityId.create(), customerId);
-
-    // Add creation event
-    order.addDomainEvent(
-      new OrderCreatedEvent({
-        orderId: order.id.value,
-        customerId: customerId.value,
-        totalAmount: 0,
-        currency: 'USD',
-      })
+  constructor(params: IAggregateConstructorParams<string>) {
+    super(params);
+    this.registerEventHandler<{ customerId: string }>(
+      'OrderCreated',
+      payload => {
+        this.customerId = payload!.customerId;
+      }
     );
-
-    return order;
+    this.registerEventHandler<void>('OrderConfirmed', () => {
+      this.status = 'confirmed';
+    });
   }
 
-  // Business methods
-  addItem(
-    productId: EntityId,
-    quantity: number,
-    price: number
-  ): Result<void, Error> {
-    // Validate business rules
-    if (quantity <= 0) {
-      return Result.fail(new Error('Quantity must be positive'));
-    }
-
-    if (price < 0) {
-      return Result.fail(new Error('Price cannot be negative'));
-    }
-
-    if (!this.status.equals(OrderStatus.PENDING)) {
-      return Result.fail(new Error('Cannot add items to non-pending order'));
-    }
-
-    // Apply changes
-    const item = new OrderItem(productId, quantity, price);
-    this.items.push(item);
-    this.totalAmount += quantity * price;
-
-    // Add domain event
-    this.addDomainEvent(
-      new OrderItemAddedEvent({
-        orderId: this.id.value,
-        productId: productId.value,
-        quantity,
-        price,
-      })
-    );
-
-    return Result.ok();
+  static create(customerId: string): Order {
+    const order = new Order({ id: EntityId.create(), version: 0 });
+    order.apply('OrderCreated', { customerId });
+    return order;
   }
 
-  confirm(): Result<void, Error> {
-    if (!this.status.equals(OrderStatus.PENDING)) {
-      return Result.fail(new Error('Order must be pending to confirm'));
-    }
-
-    if (this.items.length === 0) {
-      return Result.fail(new Error('Cannot confirm empty order'));
-    }
-
-    this.status = OrderStatus.CONFIRMED;
-
-    this.addDomainEvent(
-      new OrderConfirmedEvent({
-        orderId: this.id.value,
-        confirmedAt: new Date(),
-        totalAmount: this.totalAmount,
-      })
-    );
-
-    return Result.ok();
+  confirm(): void {
+    if (this.status !== 'pending') throw new Error('Order is not pending');
+    this.apply('OrderConfirmed', undefined);
   }
 
-  // Getters
-  getCustomerId(): EntityId {
+  getCustomerId(): string {
     return this.customerId;
   }
-
-  getItems(): ReadonlyArray<OrderItem> {
-    return this.items;
-  }
-
-  getStatus(): OrderStatus {
+  getStatus(): string {
     return this.status;
   }
-
-  getTotalAmount(): number {
-    return this.totalAmount;
-  }
-
-  getCurrency(): string {
-    return this.currency;
-  }
 }
 
-// Usage
-const order = OrderAggregate.create(EntityId.from('customer-123'));
-
-const addResult = order.addItem(EntityId.from('product-456'), 2, 29.99);
+// Create an order
+const order = Order.create('customer-123');
+order.confirm();
 
-if (addResult.isSuccess()) {
-  const confirmResult = order.confirm();
-
-  if (confirmResult.isSuccess()) {
-    console.log('Order confirmed:', order.id.value);
-    console.log('Events:', order.getUncommittedEvents());
-  }
-}
+// Domain events are collected until committed
+const events = order.getDomainEvents(); // [OrderCreated, OrderConfirmed]
+order.commit(); // clears collected events
 ```
 
-### 2. Event-Sourced Aggregate
+### With capabilities
 
 ```typescript
 import {
-  EventSourcedAggregate,
-  EventHandlerMap,
+  aggregateBuilder,
+  AuditCapability,
+  SnapshotCapability,
 } from '@vytches/ddd-aggregates';
 
-class BankAccountAggregate extends EventSourcedAggregate {
-  private balance: number = 0;
-  private status: AccountStatus = AccountStatus.ACTIVE;
-  private overdraftLimit: number = 0;
-
-  private constructor() {
-    super();
-  }
-
-  // Factory method
-  static create(
-    accountId: EntityId,
-    initialDeposit: number,
-    overdraftLimit: number = 0
-  ): BankAccountAggregate {
-    const account = new BankAccountAggregate();
-
-    // Apply creation event
-    account.apply(
-      new AccountOpenedEvent({
-        accountId: accountId.value,
-        initialDeposit,
-        overdraftLimit,
-        openedAt: new Date(),
-      })
-    );
-
-    return account;
-  }
-
-  // Business methods
-  deposit(amount: number): Result<void, Error> {
-    if (amount <= 0) {
-      return Result.fail(new Error('Deposit amount must be positive'));
-    }
-
-    if (this.status !== AccountStatus.ACTIVE) {
-      return Result.fail(new Error('Account is not active'));
-    }
-
-    this.apply(
-      new MoneyDepositedEvent({
-        accountId: this.id.value,
-        amount,
-        balance: this.balance + amount,
-        depositedAt: new Date(),
-      })
-    );
-
-    return Result.ok();
-  }
-
-  withdraw(amount: number): Result<void, Error> {
-    if (amount <= 0) {
-      return Result.fail(new Error('Withdrawal amount must be positive'));
-    }
-
-    if (this.status !== AccountStatus.ACTIVE) {
-      return Result.fail(new Error('Account is not active'));
-    }
-
-    const newBalance = this.balance - amount;
-    if (newBalance < -this.overdraftLimit) {
-      return Result.fail(new Error('Insufficient funds'));
-    }
-
-    this.apply(
-      new MoneyWithdrawnEvent({
-        accountId: this.id.value,
-        amount,
-        balance: newBalance,
-        withdrawnAt: new Date(),
-      })
-    );
-
-    return Result.ok();
-  }
-
-  // Event handlers
-  protected getEventHandlers(): EventHandlerMap {
-    return {
-      AccountOpened: this.onAccountOpened.bind(this),
-      MoneyDeposited: this.onMoneyDeposited.bind(this),
-      MoneyWithdrawn: this.onMoneyWithdrawn.bind(this),
-    };
-  }
-
-  private onAccountOpened(event: AccountOpenedEvent): void {
-    this.id = EntityId.from(event.payload.accountId);
-    this.balance = event.payload.initialDeposit;
-    this.overdraftLimit = event.payload.overdraftLimit;
-    this.status = AccountStatus.ACTIVE;
-  }
-
-  private onMoneyDeposited(event: MoneyDepositedEvent): void {
-    this.balance = event.payload.balance;
-  }
-
-  private onMoneyWithdrawn(event: MoneyWithdrawnEvent): void {
-    this.balance = event.payload.balance;
-  }
-
-  // Getters
-  getBalance(): number {
-    return this.balance;
-  }
-
-  getStatus(): AccountStatus {
-    return this.status;
-  }
-
-  getOverdraftLimit(): number {
-    return this.overdraftLimit;
-  }
-}
-
-// Reconstitute from event stream
-const events = await eventStore.getEventStream('account-123');
-const account = BankAccountAggregate.fromEventStream(events);
-
-console.log('Current balance:', account.getBalance());
+const order = aggregateBuilder(Order)
+  .withCapability(AuditCapability)
+  .withCapability(SnapshotCapability)
+  .build({ id: EntityId.create(), version: 0 });
 ```
 
-### 3. Aggregate with Capabilities
+### Utility functions
 
 ```typescript
 import {
-  AggregateRoot,
-  AuditCapability,
-  CacheCapability,
-  ValidationCapability,
+  asSnapshotAggregate,
+  tryAsSnapshotAggregate,
+  hasAllCapabilities,
+  getAggregateCapabilities,
 } from '@vytches/ddd-aggregates';
+import { SnapshotCapability, AuditCapability } from '@vytches/ddd-aggregates';
 
-class ProductAggregate extends AggregateRoot {
-  private name: string;
-  private price: number;
-  private stock: number;
-  private category: string;
+// Type-safe capability access
+const snapshotable = asSnapshotAggregate(order); // throws if missing
+const maybeSnapshot = tryAsSnapshotAggregate(order); // returns null if missing
 
-  private constructor(
-    id: EntityId,
-    name: string,
-    price: number,
-    stock: number,
-    category: string
-  ) {
-    super(id);
-    this.name = name;
-    this.price = price;
-    this.stock = stock;
-    this.category = category;
-  }
-
-  static create(
-    name: string,
-    price: number,
-    initialStock: number,
-    category: string
-  ): ProductAggregate {
-    const product = new ProductAggregate(
-      EntityId.create(),
-      name,
-      price,
-      initialStock,
-      category
-    );
-
-    // Add capabilities
-    product.addCapability(new AuditCapability());
-    product.addCapability(new CacheCapability({ ttl: 300 })); // 5 minutes
-    product.addCapability(new ValidationCapability());
-
-    product.addDomainEvent(
-      new ProductCreatedEvent({
-        productId: product.id.value,
-        name,
-        price,
-        stock: initialStock,
-        category,
-      })
-    );
-
-    return product;
-  }
-
-  updatePrice(newPrice: number): Result<void, Error> {
-    // Validation capability automatically validates
-    if (newPrice < 0) {
-      return Result.fail(new Error('Price cannot be negative'));
-    }
-
-    const oldPrice = this.price;
-    this.price = newPrice;
-
-    // Audit capability automatically logs changes
-    this.addDomainEvent(
-      new ProductPriceUpdatedEvent({
-        productId: this.id.value,
-        oldPrice,
-        newPrice,
-        updatedAt: new Date(),
-      })
-    );
-
-    return Result.ok();
-  }
-
-  adjustStock(quantity: number): Result<void, Error> {
-    const newStock = this.stock + quantity;
-
-    if (newStock < 0) {
-      return Result.fail(new Error('Insufficient stock'));
-    }
-
-    this.stock = newStock;
-
-    this.addDomainEvent(
-      new ProductStockAdjustedEvent({
-        productId: this.id.value,
-        adjustment: quantity,
-        newStock,
-        adjustedAt: new Date(),
-      })
-    );
-
-    return Result.ok();
-  }
-
-  // Getters
-  getName(): string {
-    return this.name;
-  }
-
-  getPrice(): number {
-    return this.price;
-  }
-
-  getStock(): number {
-    return this.stock;
-  }
-
-  getCategory(): string {
-    return this.category;
-  }
-}
-
-// Usage with capabilities
-const product = ProductAggregate.create(
-  'Gaming Laptop',
-  1299.99,
-  50,
-  'Electronics'
-);
-
-// Audit capability tracks all changes
-product.updatePrice(1199.99);
-product.adjustStock(-5);
-
-// Cache capability optimizes repeated access
-const auditCapability = product.getCapability(AuditCapability);
-console.log('Audit trail:', auditCapability.getAuditTrail());
-
-// Validation capability ensures data integrity
-const validationCapability = product.getCapability(ValidationCapability);
-console.log('Validation rules:', validationCapability.getValidationRules());
+// Introspection
+const hasAll = hasAllCapabilities(order, [SnapshotCapability, AuditCapability]);
+const capabilities = getAggregateCapabilities(order);
 ```
 
-## 🔧 Advanced Features
-
-### Optimistic Concurrency Control
+### Non-root entities
 
 ```typescript
-class OrderAggregate extends AggregateRoot {
-  // Version is automatically managed by base class
-
-  updateShippingAddress(newAddress: Address): Result<void, Error> {
-    // Check if aggregate is in correct state
-    if (this.status !== OrderStatus.CONFIRMED) {
-      return Result.fail(new Error('Cannot update shipping address'));
-    }
-
-    // Apply change
-    this.shippingAddress = newAddress;
+import { Entity } from '@vytches/ddd-aggregates';
+import { EntityId } from '@vytches/ddd-contracts';
 
-    // Version is automatically incremented
-    this.addDomainEvent(
-      new OrderShippingAddressUpdatedEvent({
-        orderId: this.id.value,
-        newAddress: newAddress.toJSON(),
-        version: this.version + 1,
-      })
-    );
-
-    return Result.ok();
-  }
-}
-
-// Repository handles concurrency conflicts
-class OrderRepository {
-  async save(order: OrderAggregate): Promise<void> {
-    try {
-      await this.db.orders.update({
-        where: {
-          id: order.id.value,
-          version: order.version - 1, // Expected version
-        },
-        data: {
-          ...order.toSnapshot(),
-          version: order.version,
-        },
-      });
-    } catch (error) {
-      if (error.code === 'P2025') {
-        // Prisma: Record not found
-        throw new OptimisticConcurrencyError(
-          `Order ${order.id.value} was modified by another process`
-        );
-      }
-      throw error;
-    }
-  }
-}
-```
-
-### Snapshot Support
-
-```typescript
-class OrderAggregate extends AggregateRoot {
-  // Snapshot creation
-  toSnapshot(): AggregateSnapshot {
-    return {
-      id: this.id.value,
-      version: this.version,
-      data: {
-        customerId: this.customerId.value,
-        items: this.items.map(item => item.toJSON()),
-        status: this.status.toString(),
-        totalAmount: this.totalAmount,
-        currency: this.currency,
-        createdAt: this.createdAt.toISOString(),
-        updatedAt: new Date().toISOString(),
-      },
-    };
-  }
-
-  // Snapshot restoration
-  fromSnapshot(snapshot: AggregateSnapshot): void {
-    this.id = EntityId.from(snapshot.id);
-    this.version = snapshot.version;
-    this.customerId = EntityId.from(snapshot.data.customerId);
-    this.items = snapshot.data.items.map(item => OrderItem.fromJSON(item));
-    this.status = OrderStatus.fromString(snapshot.data.status);
-    this.totalAmount = snapshot.data.totalAmount;
-    this.currency = snapshot.data.currency;
-    this.createdAt = new Date(snapshot.data.createdAt);
-    this.updatedAt = new Date(snapshot.data.updatedAt);
-  }
-}
-
-// Automatic snapshot creation
-class OrderRepository {
-  async save(order: OrderAggregate): Promise<void> {
-    // Save aggregate snapshot
-    await this.db.orders.upsert({
-      where: { id: order.id.value },
-      update: order.toSnapshot(),
-      create: order.toSnapshot(),
-    });
-
-    // Save events
-    const events = order.getUncommittedEvents();
-    await this.eventStore.append(order.id.value, events);
-
-    // Create snapshot if threshold reached
-    if (events.length >= this.snapshotThreshold) {
-      await this.snapshotStore.createSnapshot(
-        order.id.value,
-        order.toSnapshot()
-      );
-    }
-  }
-}
-```
-
-### Invariant Validation
-
-```typescript
-class OrderAggregate extends AggregateRoot {
-  // Invariant validation
-  private validateInvariants(): void {
-    // Business rules that must always be true
-    if (this.totalAmount < 0) {
-      throw new InvariantViolationError('Total amount cannot be negative');
-    }
-
-    if (this.items.length === 0 && this.status !== OrderStatus.PENDING) {
-      throw new InvariantViolationError('Non-pending orders must have items');
-    }
-
-    if (this.status === OrderStatus.CONFIRMED && this.totalAmount === 0) {
-      throw new InvariantViolationError(
-        'Confirmed orders must have positive total'
-      );
-    }
-
-    // Validate item consistency
-    const calculatedTotal = this.items.reduce(
-      (sum, item) => sum + item.quantity * item.price,
-      0
-    );
-
-    if (Math.abs(calculatedTotal - this.totalAmount) > 0.01) {
-      throw new InvariantViolationError('Total amount does not match items');
-    }
-  }
-
-  // Called automatically before events are applied
-  protected beforeApplyEvent(event: IDomainEvent): void {
-    this.validateInvariants();
-  }
-
-  // Called automatically after events are applied
-  protected afterApplyEvent(event: IDomainEvent): void {
-    this.validateInvariants();
-  }
-}
-```
-
-## 📚 API Reference
-
-### AggregateRoot
-
-**Base Class:**
-
-```typescript
-abstract class AggregateRoot {
-  protected readonly id: EntityId;
-  protected version: number;
-
-  // Event management
-  addDomainEvent(event: IDomainEvent): void;
-  getUncommittedEvents(): IDomainEvent[];
-  markEventsAsCommitted(): void;
-  clearEvents(): void;
-
-  // Capability system
-  addCapability<T extends IAggregateCapability>(capability: T): void;
-  getCapability<T extends IAggregateCapability>(type: new () => T): T | null;
-  hasCapability<T extends IAggregateCapability>(type: new () => T): boolean;
-  removeCapability<T extends IAggregateCapability>(type: new () => T): void;
-
-  // Snapshot support
-  toSnapshot(): AggregateSnapshot;
-  fromSnapshot(snapshot: AggregateSnapshot): void;
-
-  // Lifecycle hooks
-  protected beforeApplyEvent?(event: IDomainEvent): void;
-  protected afterApplyEvent?(event: IDomainEvent): void;
-  protected beforeSave?(): void;
-  protected afterSave?(): void;
-}
-```
-
-### EventSourcedAggregate
-
-**Event Sourcing Support:**
-
-```typescript
-abstract class EventSourcedAggregate extends AggregateRoot {
-  // Event application
-  protected apply(event: IDomainEvent): void;
-
-  // Event stream reconstruction
-  static fromEventStream<T extends EventSourcedAggregate>(
-    events: IDomainEvent[]
-  ): T;
-
-  // Event handlers (must be implemented)
-  protected abstract getEventHandlers(): EventHandlerMap;
-
-  // Replay events
-  protected replayEvents(events: IDomainEvent[]): void;
-
-  // Get aggregate version from events
-  protected getVersionFromEvents(events: IDomainEvent[]): number;
-}
-```
-
-### Built-in Capabilities
-
-**Audit Capability:**
-
-```typescript
-class AuditCapability implements IAggregateCapability {
-  readonly name = 'audit';
-
-  // Configuration
-  constructor(config?: AuditConfig) {}
-
-  // Audit trail
-  getAuditTrail(): AuditEntry[];
-  clearAuditTrail(): void;
-
-  // Hooks
-  onEventApplied(event: IDomainEvent): void;
-  onSnapshotCreated(snapshot: AggregateSnapshot): void;
-}
-```
-
-**Cache Capability:**
-
-```typescript
-class CacheCapability implements IAggregateCapability {
-  readonly name = 'cache';
-
-  // Configuration
-  constructor(config: CacheConfig) {}
-
-  // Cache management
-  get<T>(key: string): T | undefined;
-  set<T>(key: string, value: T): void;
-  remove(key: string): void;
-  clear(): void;
-
-  // Statistics
-  getStats(): CacheStats;
-}
-```
-
-**Validation Capability:**
-
-```typescript
-class ValidationCapability implements IAggregateCapability {
-  readonly name = 'validation';
-
-  // Configuration
-  constructor(config?: ValidationConfig) {}
-
-  // Validation rules
-  addRule(rule: ValidationRule): void;
-  removeRule(ruleName: string): void;
-  getValidationRules(): ValidationRule[];
-
-  // Validation
-  validate(aggregate: AggregateRoot): ValidationResult;
-
-  // Hooks
-  beforeApplyEvent(event: IDomainEvent): void;
-}
-```
-
-## 🎯 Patterns & Best Practices
-
-### Aggregate Design Principles
-
-1. **Keep Aggregates Small**
-
-   ```typescript
-   // Good: Small, focused aggregate
-   class OrderAggregate extends AggregateRoot {
-     private items: OrderItem[] = [];
-     private status: OrderStatus;
-
-     // Only essential order operations
-     addItem(item: OrderItem): Result<void, Error> {
-       /* ... */
-     }
-     removeItem(itemId: string): Result<void, Error> {
-       /* ... */
-     }
-     confirm(): Result<void, Error> {
-       /* ... */
-     }
-   }
-
-   // Avoid: Large, complex aggregates
-   class OrderAggregate extends AggregateRoot {
-     private items: OrderItem[] = [];
-     private customer: Customer; // Should be separate aggregate
-     private inventory: Inventory; // Should be separate aggregate
-     private payments: Payment[]; // Should be separate aggregate
-   }
-   ```
-
-2. **Use Eventual Consistency Between Aggregates**
-
-   ```typescript
-   // Good: Eventual consistency via domain events
-   class OrderAggregate extends AggregateRoot {
-     confirm(): Result<void, Error> {
-       this.status = OrderStatus.CONFIRMED;
-
-       // Notify other aggregates via events
-       this.addDomainEvent(
-         new OrderConfirmedEvent({
-           orderId: this.id.value,
-           customerId: this.customerId.value,
-           items: this.items.map(item => item.toJSON()),
-         })
-       );
-
-       return Result.ok();
-     }
-   }
-
-   // Handler in inventory context
-   @EventHandler(OrderConfirmedEvent)
-   class InventoryHandler {
-     async handle(event: OrderConfirmedEvent): Promise<void> {
-       await this.inventoryService.reserveItems(event.payload.items);
-     }
-   }
-   ```
-
-3. **Enforce Invariants at Aggregate Boundaries**
-
-   ```typescript
-   class OrderAggregate extends AggregateRoot {
-     private static readonly MAX_ITEMS = 100;
-     private static readonly MIN_TOTAL = 10.0;
-
-     addItem(item: OrderItem): Result<void, Error> {
-       // Validate aggregate invariants
-       if (this.items.length >= OrderAggregate.MAX_ITEMS) {
-         return Result.fail(
-           new Error(
-             `Order cannot have more than ${OrderAggregate.MAX_ITEMS} items`
-           )
-         );
-       }
-
-       const newTotal = this.calculateTotalWithItem(item);
-       if (
-         this.status === OrderStatus.PENDING &&
-         newTotal < OrderAggregate.MIN_TOTAL
-       ) {
-         return Result.fail(
-           new Error(`Order total must be at least ${OrderAggregate.MIN_TOTAL}`)
-         );
-       }
-
-       // Apply change
-       this.items.push(item);
-       this.recalculateTotal();
-
-       return Result.ok();
-     }
-   }
-   ```
-
-### Event Design Guidelines
-
-1. **Use Past Tense for Domain Events**
-
-   ```typescript
-   // Good: Past tense, describes what happened
-   class OrderCreatedEvent extends DomainEvent<OrderCreatedData> {}
-   class OrderConfirmedEvent extends DomainEvent<OrderConfirmedData> {}
-   class OrderCancelledEvent extends DomainEvent<OrderCancelledData> {}
-
-   // Avoid: Present tense or imperative
-   class CreateOrderEvent extends DomainEvent<OrderData> {}
-   class ConfirmOrderEvent extends DomainEvent<OrderData> {}
-   ```
-
-2. **Include Sufficient Data in Events**
-
-   ```typescript
-   // Good: Rich event data
-   class OrderCreatedEvent extends DomainEvent<{
-     orderId: string;
-     customerId: string;
-     items: Array<{
-       productId: string;
-       quantity: number;
-       price: number;
-     }>;
-     totalAmount: number;
-     currency: string;
-     createdAt: Date;
-     metadata: {
-       channel: string;
-       promotionCode?: string;
-     };
-   }> {}
-
-   // Avoid: Minimal event data
-   class OrderCreatedEvent extends DomainEvent<{
-     orderId: string;
-   }> {}
-   ```
-
-3. **Version Events for Schema Evolution**
-
-   ```typescript
-   // Event versioning
-   class OrderCreatedEvent extends DomainEvent<OrderCreatedData> {
-     static readonly VERSION = 2;
-
-     constructor(payload: OrderCreatedData) {
-       super('OrderCreated', payload);
-       this.version = OrderCreatedEvent.VERSION;
-     }
-   }
-
-   // Event upcasting for version compatibility
-   class OrderCreatedEventUpcaster {
-     upcast(event: IDomainEvent): IDomainEvent {
-       if (event.version === 1) {
-         return this.upcastV1ToV2(event);
-       }
-       return event;
-     }
-
-     private upcastV1ToV2(event: IDomainEvent): IDomainEvent {
-       // Convert v1 to v2 format
-       return new OrderCreatedEvent({
-         ...event.payload,
-         currency: event.payload.currency || 'USD', // Default currency
-       });
-     }
-   }
-   ```
-
-### Testing Strategies
-
-1. **Unit Test Aggregate Behavior**
-
-   ```typescript
-   describe('OrderAggregate', () => {
-     it('should create order with items', () => {
-       // Arrange
-       const customerId = EntityId.create();
-       const item = new OrderItem(EntityId.create(), 2, 29.99);
-
-       // Act
-       const order = OrderAggregate.create(customerId);
-       const result = order.addItem(item);
-
-       // Assert
-       expect(result.isSuccess()).toBe(true);
-       expect(order.getItems()).toHaveLength(1);
-       expect(order.getTotalAmount()).toBe(59.98);
-
-       // Verify events
-       const events = order.getUncommittedEvents();
-       expect(events).toHaveLength(2);
-       expect(events[0]).toBeInstanceOf(OrderCreatedEvent);
-       expect(events[1]).toBeInstanceOf(OrderItemAddedEvent);
-     });
-
-     it('should fail to add item with negative quantity', () => {
-       // Arrange
-       const order = OrderAggregate.create(EntityId.create());
-       const item = new OrderItem(EntityId.create(), -1, 29.99);
-
-       // Act
-       const result = order.addItem(item);
-
-       // Assert
-       expect(result.isFailure()).toBe(true);
-       expect(result.error?.message).toBe('Quantity must be positive');
-       expect(order.getItems()).toHaveLength(0);
-     });
-   });
-   ```
-
-2. **Test Event Sourcing**
-
-   ```typescript
-   describe('BankAccountAggregate Event Sourcing', () => {
-     it('should reconstitute from event stream', () => {
-       // Arrange
-       const events = [
-         new AccountOpenedEvent({
-           accountId: 'account-123',
-           initialDeposit: 1000,
-           overdraftLimit: 500,
-         }),
-         new MoneyDepositedEvent({
-           accountId: 'account-123',
-           amount: 250,
-           balance: 1250,
-         }),
-         new MoneyWithdrawnEvent({
-           accountId: 'account-123',
-           amount: 100,
-           balance: 1150,
-         }),
-       ];
-
-       // Act
-       const account = BankAccountAggregate.fromEventStream(events);
-
-       // Assert
-       expect(account.getBalance()).toBe(1150);
-       expect(account.getOverdraftLimit()).toBe(500);
-       expect(account.getStatus()).toBe(AccountStatus.ACTIVE);
-     });
-   });
-   ```
-
-3. **Integration Testing with Repository**
-
-   ```typescript
-   describe('OrderRepository Integration', () => {
-     it('should save and retrieve aggregate', async () => {
-       // Arrange
-       const order = OrderAggregate.create(EntityId.create());
-       order.addItem(new OrderItem(EntityId.create(), 1, 99.99));
-
-       // Act
-       await orderRepository.save(order);
-       const retrievedOrder = await orderRepository.findById(order.id);
-
-       // Assert
-       expect(retrievedOrder).toBeDefined();
-       expect(retrievedOrder?.getTotalAmount()).toBe(99.99);
-       expect(retrievedOrder?.getItems()).toHaveLength(1);
-     });
-   });
-   ```
-
-## ⚡ Performance
-
-### Optimization Strategies
-
-1. **Snapshot Strategy**
-
-   ```typescript
-   class OrderRepository {
-     private readonly snapshotThreshold = 20;
-
-     async save(order: OrderAggregate): Promise<void> {
-       // Always save current state
-       await this.saveSnapshot(order);
-
-       // Save events
-       const events = order.getUncommittedEvents();
-       await this.eventStore.append(order.id.value, events);
-
-       // Create snapshot if threshold reached
-       const eventCount = await this.eventStore.getEventCount(order.id.value);
-       if (eventCount >= this.snapshotThreshold) {
-         await this.snapshotStore.createSnapshot(
-           order.id.value,
-           order.toSnapshot()
-         );
-
-         // Optional: Archive old events
-         await this.eventStore.archiveEvents(order.id.value, eventCount - 10);
-       }
-     }
-   }
-   ```
-
-2. **Lazy Loading**
-
-   ```typescript
-   class OrderAggregate extends AggregateRoot {
-     private _items: OrderItem[] | null = null;
-
-     getItems(): OrderItem[] {
-       if (this._items === null) {
-         this._items = this.loadItemsFromSnapshot();
-       }
-       return this._items;
-     }
-
-     private loadItemsFromSnapshot(): OrderItem[] {
-       // Load from snapshot or reconstruct from events
-       return this.snapshotData.items.map(item => OrderItem.fromJSON(item));
-     }
-   }
-   ```
-
-3. **Batching Operations**
-
-   ```typescript
-   class OrderAggregate extends AggregateRoot {
-     addItems(items: OrderItem[]): Result<void, Error> {
-       // Validate all items first
-       for (const item of items) {
-         const validation = this.validateItem(item);
-         if (validation.isFailure()) {
-           return validation;
-         }
-       }
-
-       // Apply all items in batch
-       for (const item of items) {
-         this.items.push(item);
-         this.totalAmount += item.quantity * item.price;
-       }
-
-       // Single event for batch operation
-       this.addDomainEvent(
-         new OrderItemsBatchAddedEvent({
-           orderId: this.id.value,
-           items: items.map(item => item.toJSON()),
-           newTotal: this.totalAmount,
-         })
-       );
-
-       return Result.ok();
-     }
-   }
-   ```
-
-### Memory Management
-
-```typescript
-class AggregateRoot {
-  private eventCache: Map<string, IDomainEvent> = new Map();
-  private readonly maxCacheSize = 1000;
-
-  addDomainEvent(event: IDomainEvent): void {
-    // Manage cache size
-    if (this.eventCache.size >= this.maxCacheSize) {
-      // Remove oldest events
-      const oldestKey = this.eventCache.keys().next().value;
-      this.eventCache.delete(oldestKey);
-    }
-
-    this.eventCache.set(event.id, event);
+// Use Entity for inner aggregate objects like OrderLine, Address
+class OrderLine extends Entity<string> {
+  constructor(
+    id: EntityId<string>,
+    private sku: string,
+    private quantity: number
+  ) {
+    super({ id });
   }
-
-  getUncommittedEvents(): IDomainEvent[] {
-    return Array.from(this.eventCache.values());
+  getSku(): string {
+    return this.sku;
   }
-
-  markEventsAsCommitted(): void {
-    this.eventCache.clear();
+  getQuantity(): number {
+    return this.quantity;
   }
 }
 ```
 
-## 🧪 Testing
-
-### Aggregate Testing Utilities
-
-```typescript
-import { AggregateTestBuilder } from '@vytches/ddd-aggregates/testing';
-
-// Aggregate builder for tests
-const orderBuilder = new AggregateTestBuilder(OrderAggregate)
-  .withCustomer('customer-123')
-  .withItems([
-    { productId: 'product-1', quantity: 2, price: 29.99 },
-    { productId: 'product-2', quantity: 1, price: 49.99 },
-  ])
-  .withStatus(OrderStatus.PENDING)
-  .build();
-
-// Event stream testing
-const account = new AggregateTestBuilder(BankAccountAggregate)
-  .fromEventStream([
-    new AccountOpenedEvent({ accountId: 'account-123', initialDeposit: 1000 }),
-    new MoneyDepositedEvent({
-      accountId: 'account-123',
-      amount: 500,
-      balance: 1500,
-    }),
-  ])
-  .build();
-
-// Snapshot testing
-const order = new AggregateTestBuilder(OrderAggregate)
-  .fromSnapshot({
-    id: 'order-123',
-    version: 5,
-    data: {
-      /* snapshot data */
-    },
-  })
-  .build();
-```
-
-### Event Testing
-
-```typescript
-import { EventTestHarness } from '@vytches/ddd-aggregates/testing';
-
-describe('Order Events', () => {
-  let eventHarness: EventTestHarness;
-
-  beforeEach(() => {
-    eventHarness = new EventTestHarness();
-  });
-
-  it('should emit correct events when adding item', () => {
-    // Arrange
-    const order = OrderAggregate.create(EntityId.create());
-    const item = new OrderItem(EntityId.create(), 1, 99.99);
-
-    // Act
-    order.addItem(item);
-
-    // Assert
-    eventHarness.assertEventEmitted(order, OrderItemAddedEvent, {
-      orderId: order.id.value,
-      productId: item.productId.value,
-      quantity: 1,
-      price: 99.99,
-    });
-  });
-});
-```
-
-## 🤝 Contributing
+## API Reference
 
-We welcome contributions! Please see our
-[Contributing Guide](../../CONTRIBUTING.md) for details.
+### Core Classes
 
-### Development Setup
+| Export               | Kind     | Description                                                                                            |
+| -------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `AggregateRoot<TId>` | class    | Base aggregate root; provides identity, versioning, event collection and event sourcing reconstitution |
+| `Entity<TId>`        | class    | Base class for non-root domain entities; identity-based equality, no events                            |
+| `AggregateBuilder`   | class    | Fluent builder for aggregates with capabilities                                                        |
+| `aggregateBuilder`   | function | Factory function shorthand for `AggregateBuilder`                                                      |
+| `AggregateError`     | class    | Error thrown for aggregate-specific failures                                                           |
 
-```bash
-# Clone repository
-git clone https://github.com/vytches/ddd.git
-cd ddd
-
-# Install dependencies
-pnpm install
-
-# Build aggregates package
-pnpm build --filter=@vytches/ddd-aggregates
-
-# Run tests
-pnpm test --filter=@vytches/ddd-aggregates
-
-# Run in development mode
-pnpm dev --filter=@vytches/ddd-aggregates
-```
-
-## 📄 License
-
-This project is licensed under the MIT License - see the
-[LICENSE](../../LICENSE) file for details.
-
----
-
-**Part of the [@vytches/ddd-core](https://github.com/vytches/ddd) ecosystem**
+### Capabilities
 
-For more information, visit the [main documentation](../../README.md).
+| Export                    | Kind  | Description                                              |
+| ------------------------- | ----- | -------------------------------------------------------- |
+| `AuditCapability`         | class | Records who created/modified the aggregate and when      |
+| `EventSourcingCapability` | class | Enables event sourcing reconstitution from stored events |
+| `SnapshotCapability`      | class | Enables taking and restoring state snapshots             |
+| `VersioningCapability`    | class | Manages optimistic concurrency version tracking          |
+
+### Capability Utilities
+
+| Export                             | Kind     | Description                                                   |
+| ---------------------------------- | -------- | ------------------------------------------------------------- |
+| `asSnapshotAggregate(agg)`         | function | Cast to snapshot-capable aggregate; throws if missing         |
+| `tryAsSnapshotAggregate(agg)`      | function | Cast to snapshot-capable aggregate; returns `null` if missing |
+| `asVersioningAggregate(agg)`       | function | Cast to versioning-capable aggregate; throws if missing       |
+| `tryAsVersioningAggregate(agg)`    | function | Returns `null` if versioning capability absent                |
+| `asAuditAggregate(agg)`            | function | Cast to audit-capable aggregate; throws if missing            |
+| `tryAsAuditAggregate(agg)`         | function | Returns `null` if audit capability absent                     |
+| `asEventSourcingAggregate(agg)`    | function | Cast to event-sourcing aggregate; throws if missing           |
+| `tryAsEventSourcingAggregate(agg)` | function | Returns `null` if event sourcing capability absent            |
+| `getAggregateCapabilities(agg)`    | function | Returns all capabilities attached to an aggregate             |
+| `hasAllCapabilities(agg, caps)`    | function | Returns `true` if aggregate has all listed capabilities       |
+
+### Interfaces
+
+| Export                             | Kind      | Description                                |
+| ---------------------------------- | --------- | ------------------------------------------ |
+| `IAggregateRoot`                   | interface | Full contract for aggregate roots          |
+| `IAggregateCapability`             | interface | Base capability contract                   |
+| `IAggregateConstructorParams<TId>` | interface | Constructor parameter shape for aggregates |
+| `IAggregateEventHandler`           | interface | Event handler registration contract        |
+| `IAggregateBuilder`                | interface | Builder contract                           |
+
+### Utility Types
+
+| Export                                 | Kind | Description                                    |
+| -------------------------------------- | ---- | ---------------------------------------------- |
+| `AggregateWithSnapshotCapability`      | type | Aggregate narrowed to snapshot-capable shape   |
+| `AggregateWithVersioningCapability`    | type | Aggregate narrowed to versioning-capable shape |
+| `AggregateWithAuditCapability`         | type | Aggregate narrowed to audit-capable shape      |
+| `AggregateWithEventSourcingCapability` | type | Aggregate narrowed to event-sourcing shape     |
+
+## Package boundaries
+
+`@vytches/ddd-aggregates` depends on:
+
+- `@vytches/ddd-contracts` — base interfaces and `EntityId`
+- `@vytches/ddd-domain-primitives` — error types
+- `@vytches/ddd-value-objects` — enhanced `EntityId`
+- `@vytches/ddd-logging` — internal logging
+
+## License
+
+MIT