@shirudo/ddd-kit 0.16.0 → 1.0.0-rc.2

package/dist/index.d.ts

@@ -1,18 +1,350 @@
-import { R as Result } from './result-jCwPSjFa.js';
-import { a as DeepEqualExceptOptions } from './deep-equal-except-C8yoSk4L.js';
+import { Result } from '@shirudo/result';
+import { DeepEqualExceptOptions } from './utils.js';
+export { DeepOmitOptions, Key, PathSegment, deepEqual, deepEqualExcept, deepOmit } from './utils.js';
 
+/**
+ * Branded string ID. `Tag` carries the aggregate / entity name so two ids
+ * with different tags are not assignable to each other even though both
+ * are strings at runtime.
+ *
+ * @example
+ * ```ts
+ * type UserId = Id<"UserId">;
+ * type OrderId = Id<"OrderId">;
+ *
+ * const u = "user-1" as UserId;
+ * const o: OrderId = u; // ❌ compile error
+ * ```
+ */
 type Id<Tag extends string> = string & {
     readonly __brand: Tag;
 };
-interface IdGenerator {
-    next: <T extends string>() => Id<T>;
+/**
+ * Produces fresh ids of a single, fixed tag. The tag is bound at the
+ * generator type — `IdGenerator<"UserId">.next()` returns `Id<"UserId">`
+ * with no caller-side generic to abuse.
+ *
+ * @example
+ * ```ts
+ * import { ulid } from "ulid";
+ *
+ * const userIds: IdGenerator<"UserId"> = { next: () => ulid() as Id<"UserId"> };
+ * const id = userIds.next(); // Id<"UserId">
+ * ```
+ *
+ * The previous shape (`IdGenerator { next<T extends string>(): Id<T> }`)
+ * let callers pick `T` themselves — `gen.next<"AnyTag">()` typechecked
+ * even when the generator produced different-tag ids, silently defeating
+ * the brand.
+ */
+interface IdGenerator<Tag extends string> {
+    next: () => Id<Tag>;
 }
 
 /**
- * Functional definition of an Entity via its capability.
- * An object is identifiable if it has an id.
+ * Factory function producing a fresh, unique event identifier for each call.
+ *
+ * The library ships a default that uses Web Crypto `crypto.randomUUID()`
+ * (works on Node 19+, modern browsers in secure contexts, Deno, Bun,
+ * Cloudflare Workers, Vercel Edge, and any runtime that implements Web
+ * Crypto). Note that `crypto.randomUUID()` returns **UUID v4** (purely
+ * random) — for production event stores prefer a **time-ordered** id
+ * format (UUID v7 / ULID / KSUID) so B-tree indexes on the eventId
+ * column stay clustered and `ORDER BY eventId` matches creation order.
+ * Swap one in via `setEventIdFactory(() => uuidv7())` or `() => ulid()`.
+ */
+type EventIdFactory = () => string;
+/**
+ * Replaces the global event-id factory used by `createDomainEvent` and
+ * `createDomainEventWithMetadata`. Call once during application bootstrap,
+ * for example:
+ *
+ * ```ts
+ * import { ulid } from "ulid";
+ * import { setEventIdFactory } from "@shirudo/ddd-kit";
+ *
+ * setEventIdFactory(() => ulid());
+ * ```
+ *
+ * The per-call `options.eventId` override always wins over this factory.
+ *
+ * **Module-scoped — last setter wins.** The factory lives as a single
+ * module variable; importing two libraries that both call this races on
+ * load order. For multi-tenant request isolation (e.g. one factory per
+ * tenant in a single Worker invocation) **prefer the per-call
+ * `options.eventId`** instead of mutating the global. Same caveat applies
+ * to `setClockFactory`.
+ */
+declare function setEventIdFactory(factory: EventIdFactory): void;
+/**
+ * Restores the default event-id factory (`crypto.randomUUID()`).
+ * Intended for use in test `afterEach` hooks.
+ */
+declare function resetEventIdFactory(): void;
+/**
+ * Clock function producing a fresh `Date` for each call. The library
+ * defaults to `() => new Date()`; override globally via `setClockFactory`
+ * for deterministic event-sourcing tests, time-travel debugging, or any
+ * scenario where `occurredAt` must be reproducible.
  */
-type Identifiable<TId> = {
+type ClockFactory = () => Date;
+/**
+ * Replaces the global clock factory used by `createDomainEvent` and
+ * `createDomainEventWithMetadata`. Call once during application bootstrap
+ * (or per-test in deterministic test suites):
+ *
+ * ```ts
+ * import { setClockFactory } from "@shirudo/ddd-kit";
+ *
+ * setClockFactory(() => new Date("2026-01-01T00:00:00Z"));
+ * ```
+ *
+ * The per-call `options.occurredAt` override always wins over this
+ * factory. Symmetric to `setEventIdFactory`.
+ */
+declare function setClockFactory(factory: ClockFactory): void;
+/**
+ * Restores the default clock factory (`() => new Date()`).
+ * Intended for use in test `afterEach` hooks.
+ */
+declare function resetClockFactory(): void;
+/**
+ * Metadata associated with a domain event for traceability and correlation.
+ * Used in event-driven architectures to track event flow across services.
+ */
+interface EventMetadata {
+    /**
+     * Correlation ID for tracing events across multiple services/components.
+     * Typically used to group related events in a distributed system.
+     */
+    correlationId?: string;
+    /**
+     * Causation ID referencing the event or command that caused this event.
+     * Used to build event chains and understand causality.
+     */
+    causationId?: string;
+    /**
+     * User ID of the person or system that triggered the event.
+     */
+    userId?: string;
+    /**
+     * Source service or component that produced the event.
+     */
+    source?: string;
+    /**
+     * Additional custom metadata fields.
+     * Allows extensibility for domain-specific metadata.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Domain Event represents something meaningful that happened in the domain.
+ * Events are immutable and carry information about what occurred.
+ *
+ * @template T - The event type name (e.g., "OrderCreated")
+ * @template P - The event payload type
+ */
+interface DomainEvent<T extends string, P = void> {
+    /**
+     * Unique identifier for this specific event instance. Used by idempotent
+     * consumers, outbox dispatch tracking, and as the target of
+     * `metadata.causationId`. Defaults to `crypto.randomUUID()` if not
+     * supplied.
+     */
+    eventId: string;
+    /**
+     * The type of the event, used for routing and handling.
+     */
+    type: T;
+    /**
+     * Identifier of the aggregate that produced the event. Optional at the
+     * library level — set it whenever the producing aggregate is known so
+     * downstream subscribers, outboxes, and projections can scope by entity.
+     */
+    aggregateId?: string;
+    /**
+     * Name of the aggregate type that produced the event (e.g. "Order").
+     * Pairs with `aggregateId` to fully qualify the source aggregate.
+     */
+    aggregateType?: string;
+    /**
+     * The event payload containing the domain data. The field is always
+     * present; its value is `undefined` when `P` is `void`.
+     */
+    payload: P;
+    /**
+     * Timestamp when the event occurred.
+     */
+    occurredAt: Date;
+    /**
+     * Event schema version for handling schema evolution.
+     * Required for safe schema migration in event-sourced systems.
+     * Use 1 for the initial schema version.
+     */
+    version: number;
+    /**
+     * Optional metadata for traceability, correlation, and auditing.
+     * Includes correlationId, causationId, userId, source, and custom fields.
+     */
+    metadata?: EventMetadata;
+}
+/**
+ * Shared option bag for the `createDomainEvent*` factories.
+ */
+interface CreateDomainEventOptions {
+    /**
+     * Override for the auto-generated `eventId`. Pass an existing id (for
+     * replay, tests, or deterministic event sourcing) instead of letting the
+     * factory call `crypto.randomUUID()`.
+     */
+    eventId?: string;
+    /**
+     * Identifier of the aggregate that produced the event.
+     */
+    aggregateId?: string;
+    /**
+     * Name of the aggregate type that produced the event.
+     */
+    aggregateType?: string;
+    /**
+     * Override for the auto-generated `occurredAt` timestamp.
+     */
+    occurredAt?: Date;
+    /**
+     * Override for the default schema version (1).
+     */
+    version?: number;
+    /**
+     * Event metadata — correlation, causation, user, source, custom fields.
+     */
+    metadata?: EventMetadata;
+}
+/**
+ * Creates a domain event with default values.
+ * Sets occurredAt to current date and version to 1 if not provided.
+ *
+ * @param type - The event type
+ * @param payload - The event payload
+ * @param options - Optional event configuration
+ * @returns A domain event
+ *
+ * @example
+ * ```typescript
+ * const event = createDomainEvent("OrderCreated", { orderId: "123" });
+ * ```
+ */
+declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateDomainEventOptions): DomainEvent<T, void>;
+declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateDomainEventOptions): DomainEvent<T, P>;
+/**
+ * Creates a domain event with metadata for traceability.
+ * Convenience function for creating events with correlation and causation IDs.
+ *
+ * @example
+ * ```typescript
+ * const event = createDomainEventWithMetadata(
+ *   "OrderCreated",
+ *   { orderId: "123" },
+ *   { correlationId: "corr-123", causationId: "cmd-456", userId: "user-789" }
+ * );
+ * ```
+ */
+declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: Omit<CreateDomainEventOptions, "metadata">): DomainEvent<T, P>;
+/**
+ * Copies metadata from a source event to a new event.
+ * Useful for maintaining correlation chains in event-driven architectures.
+ *
+ * @example
+ * ```typescript
+ * const newEvent = createDomainEvent(
+ *   "OrderShipped",
+ *   { orderId: "123" },
+ *   { metadata: copyMetadata(previousEvent, { causationId: previousEvent.type }) }
+ * );
+ * ```
+ */
+declare function copyMetadata(sourceEvent: DomainEvent<string, unknown>, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
+/**
+ * Merges multiple metadata objects into one.
+ * Later metadata objects override earlier ones for the same keys.
+ *
+ * @example
+ * ```typescript
+ * const metadata = mergeMetadata(
+ *   { correlationId: "corr-123" },
+ *   { userId: "user-456" },
+ *   { source: "order-service" }
+ * );
+ * ```
+ */
+declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
+
+/**
+ * Entity utilities and interfaces for Domain-Driven Design.
+ *
+ * In Domain-Driven Design, there are two types of entities:
+ *
+ * 1. **Aggregate Root Entity**: The parent Entity of an aggregate.
+ *    - Has identity (id), state, and version
+ *    - Implemented by classes extending `AggregateRoot` or `EventSourcedAggregate`
+ *    - Represents the aggregate externally
+ *    - Loaded/saved through repositories
+ *
+ * 2. **Child Entities**: Entities within an aggregate.
+ *    - Have identity (id) and state, but no own version
+ *    - Can extend `EntityBase<TState, TId>` for class-based entities
+ *    - Or use functional style with `Identifiable<TId> & TProps`
+ *    - Exist only within the aggregate boundary
+ *    - Versioned through the Aggregate Root
+ *    - Cannot be referenced directly from outside the aggregate
+ *
+ * This module provides:
+ * - `EntityBase<TState, TId>` - Base class for entities with state
+ * - `Entity<TId>` - Simple class for entities without state management
+ * - `Identifiable<TId>` - Minimal interface for objects with id
+ * - Helper functions for working with collections of entities
+ *
+ * @example
+ * ```typescript
+ * // Class-based child entity with logic
+ * class OrderItem extends EntityBase<OrderItemState, ItemId> {
+ *   constructor(id: ItemId, initialState: OrderItemState) {
+ *     super(id, initialState);
+ *   }
+ *
+ *   updateQuantity(quantity: number): void {
+ *     this._state = { ...this._state, quantity };
+ *   }
+ *
+ *   calculateSubtotal(): number {
+ *     return this._state.price * this._state.quantity;
+ *   }
+ * }
+ *
+ * // Functional-style child entity (simpler, no logic)
+ * type OrderItem = Identifiable<ItemId> & {
+ *   productId: string;
+ *   quantity: number;
+ *   price: number;
+ * };
+ *
+ * // Aggregate Root (Entity with version)
+ * class Order extends AggregateRoot<OrderState, OrderId> {
+ *   // Order is an Aggregate Root Entity
+ *   // OrderState contains OrderItem child entities
+ * }
+ * ```
+ */
+
+/**
+ * Functional definition of an Entity via its capability — an object is
+ * identifiable if it has an `id`.
+ *
+ * `TId` is constrained to `Id<string>` so the brand discipline that
+ * `Id<Tag>` enforces is preserved end-to-end: an `Identifiable<UserId>`
+ * cannot accidentally be paired with an `Identifiable<OrderId>` or with
+ * a plain `string`.
+ */
+type Identifiable<TId extends Id<string>> = {
     readonly id: TId;
 };
 /**
@@ -72,7 +404,15 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
     readonly id: TId;
     /**
      * Returns the current state of the entity.
-     * State is readonly from outside to enforce encapsulation.
+     *
+     * The state object is **shallowly frozen** — direct property writes
+     * (`entity.state.foo = …`) throw in strict mode, but writes to nested
+     * objects (`entity.state.address.zip = …`) bypass the freeze. For deep
+     * immutability either model nested data with `vo()` (which freezes
+     * deeply) or reach for a structural-sharing library like Immer at the
+     * App layer. The shallow contract is intentional: deep freezing on
+     * every state write is too expensive for hot paths, and DDD aggregates
+     * normally treat their own state as private (`Tell, Don't Ask`).
      */
     get state(): TState;
     /**
@@ -82,12 +422,25 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
     protected _state: TState;
     protected constructor(id: TId, initialState: TState);
     /**
-     * Optional validation hook to ensure state invariants.
-     * Called during construction and whenever helpful.
-     * Override this method to implement validation logic.
+     * Optional validation hook to ensure state invariants. Called during
+     * construction (from `Entity`'s constructor) and again on every
+     * `setState()` call. Throw to reject invalid state.
+     *
+     * **⚠️ Must not read subclass instance fields via `this`.** The
+     * constructor calls `validateState(initialState)` BEFORE the subclass's
+     * field initializers run, so `this.someField` is `undefined` at that
+     * point — a classic TypeScript/JavaScript constructor-ordering footgun.
+     * The `state` argument is the single source of truth; treat the method
+     * as pure with respect to `this`.
+     *
+     * If your invariants genuinely depend on per-instance configuration
+     * that isn't part of the state, pass that configuration into the state
+     * itself (DDD-canonical: the aggregate's state contains everything it
+     * needs) or perform the additional check after construction in a
+     * dedicated factory method.
      *
      * @param state - The state to validate
-     * @throws Error if validation fails
+     * @throws Error (or `DomainError` subclass) if validation fails
      */
     protected validateState(_state: TState): void;
     /**
@@ -99,6 +452,18 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
      */
     protected setState(newState: TState): void;
 }
+/**
+ * Shallow-freezes `value` when it's a non-null object or array, so that
+ * direct property writes throw in strict mode. Returns the value as-is for
+ * primitives. Used internally by `Entity` and its subclasses to prevent
+ * outside mutation of state read through the `state` getter without paying
+ * the cost of a deep clone on every read.
+ *
+ * Exported so that sibling classes (`EventSourcedAggregate`, `AggregateRoot`)
+ * can apply the same freeze when they bypass `setState` and assign
+ * `this._state` directly.
+ */
+declare function freezeShallow<T>(value: T): T;
 /**
  * Checks if two entities have the same ID.
  * Works with any object that has an 'id' property.
@@ -116,7 +481,7 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
  * sameEntity(item1, item1); // true
  * ```
  */
-declare function sameEntity<TId>(a: Identifiable<TId>, b: Identifiable<TId>): boolean;
+declare function sameEntity<TId extends Id<string>>(a: Identifiable<TId>, b: Identifiable<TId>): boolean;
 /**
  * Finds an entity by ID in a collection.
  * Returns undefined if not found.
@@ -136,7 +501,7 @@ declare function sameEntity<TId>(a: Identifiable<TId>, b: Identifiable<TId>): bo
  * // item is { id: itemId1, productId: "prod-1", quantity: 2 }
  * ```
  */
-declare function findEntityById<TId, T extends Identifiable<TId>>(entities: T[], id: TId): T | undefined;
+declare function findEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId): T | undefined;
 /**
  * Checks if an entity with the given ID exists in the collection.
  *
@@ -154,7 +519,7 @@ declare function findEntityById<TId, T extends Identifiable<TId>>(entities: T[],
  * hasEntityId(items, itemId2); // false
  * ```
  */
-declare function hasEntityId<TId, T extends Identifiable<TId>>(entities: T[], id: TId): boolean;
+declare function hasEntityId<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId): boolean;
 /**
  * Removes an entity with the given ID from the collection.
  * Returns a new array without the entity.
@@ -174,7 +539,7 @@ declare function hasEntityId<TId, T extends Identifiable<TId>>(entities: T[], id
  * // updated is [{ id: itemId2, productId: "prod-2", quantity: 1 }]
  * ```
  */
-declare function removeEntityById<TId, T extends Identifiable<TId>>(entities: T[], id: TId): T[];
+declare function removeEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId): T[];
 /**
  * Updates an entity with the given ID in the collection.
  * Returns a new array with the updated entity.
@@ -198,7 +563,7 @@ declare function removeEntityById<TId, T extends Identifiable<TId>>(entities: T[
  * // updated is [{ id: itemId1, productId: "prod-1", quantity: 3 }]
  * ```
  */
-declare function updateEntityById<TId, T extends Identifiable<TId>>(entities: T[], id: TId, updater: (entity: T) => T): T[];
+declare function updateEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId, updater: (entity: T) => T): T[];
 /**
  * Replaces an entity with the given ID in the collection.
  * Returns a new array with the replaced entity.
@@ -222,7 +587,7 @@ declare function updateEntityById<TId, T extends Identifiable<TId>>(entities: T[
  * });
  * ```
  */
-declare function replaceEntityById<TId, T extends Identifiable<TId>>(entities: T[], id: TId, replacement: T): T[];
+declare function replaceEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId, replacement: T): T[];
 /**
  * Extracts all IDs from a collection of entities.
  *
@@ -240,7 +605,7 @@ declare function replaceEntityById<TId, T extends Identifiable<TId>>(entities: T
  * // ids is [itemId1, itemId2]
  * ```
  */
-declare function entityIds<TId, T extends Identifiable<TId>>(entities: T[]): TId[];
+declare function entityIds<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[]): TId[];
 
 /**
  * Marker interface for Aggregate Roots.
@@ -280,45 +645,58 @@ interface IAggregateRoot<TId extends Id<string>> {
      * This version applies to the entire aggregate, including all child entities.
      */
     readonly version: Version;
+    /**
+     * Post-save hook: a `Repository.save()` implementation calls this with
+     * the persisted version after a successful write to push the new
+     * version back into the aggregate and clear any recorded domain events
+     * (they are now safely on the write side / in the outbox).
+     *
+     * Required by the interface so a Repository implementation can call it
+     * via the published `IAggregateRoot` contract without taking the
+     * abstract class as a compile-time dependency.
+     *
+     * @param version - The version assigned by the persistence layer
+     */
+    markPersisted(version: Version): void;
 }
 /**
  * Configuration options for AggregateRoot behavior.
  */
 interface AggregateConfig {
     /**
-     * Whether to automatically bump the version when state changes.
-     * Defaults to false. Set to true for automatic versioning.
+     * Whether `setState()` should bump the version automatically.
+     *
+     * Defaults to **`false`** for `AggregateRoot` — because `setState()`
+     * already takes an explicit `bumpVersion` argument per call, so adding
+     * an "always bump" config on top would be redundant. Keep it `false`
+     * unless you have a subclass that never passes `bumpVersion` and you
+     * want every state change to advance the version anyway.
+     *
+     * (Contrast with `EventSourcedAggregate`, which defaults this to
+     * `true` because every event-sourced state change is per definition a
+     * versioned commit.)
      */
     autoVersionBump?: boolean;
 }
 /**
- * Base class for creating Aggregate Roots (Entities) without Event Sourcing.
+ * Base class for Aggregate Roots without Event Sourcing.
  *
- * This class creates an Entity that serves as the Aggregate Root. The Aggregate Root
- * is the parent Entity of the aggregate and represents it externally. It has identity
- * (id), state, and version for optimistic concurrency control.
+ * In DDD (Evans), an Aggregate is a cluster of objects — root entity, child entities,
+ * and value objects — treated as a unit for consistency. The **Aggregate Root** is the
+ * root entity that represents the aggregate externally and is the only entry point
+ * for external code. This class serves as both: it IS the root entity and it contains
+ * the aggregate state (`TState`) which holds child entities and value objects.
  *
- * Extends `Entity<TState, TId>` to inherit:
- * - Identity (id)
- * - State management
- * - State validation
- *
- * Adds Aggregate Root specific functionality:
- * - Version management (for Optimistic Concurrency Control)
- * - Domain events tracking
+ * Provides:
+ * - Identity (id) and state management (via `Entity`)
+ * - Version management for optimistic concurrency control
+ * - Domain event tracking for side-effects
  * - Snapshot support for performance optimization
  *
- * The aggregate state (`TState`) contains:
- * - Child entities (Entities with id + state, but no own version)
- * - Value objects (immutable objects)
- *
- * All changes to child entities are versioned through the Aggregate Root. The version
- * applies to the entire aggregate, including all child entities.
+ * All changes to child entities within `TState` are versioned through this root.
+ * Use `setState()` for state mutations to ensure invariant validation.
  *
- * Implements `IAggregateRoot<TId>` to mark this as an Aggregate Root Entity.
- *
- * Use this class when you don't need Event Sourcing but still want
- * aggregate patterns with versioning and state management.
+ * For event sourcing, use `EventSourcedAggregate` instead.
  *
  * @template TState - The type of the aggregate state (contains child entities and value objects)
  * @template TId - The type of the aggregate root identifier
@@ -333,14 +711,15 @@ interface AggregateConfig {
  *   }
  *
  *   confirm(): void {
- *     this._state = { ...this._state, status: "confirmed" };
- *     this.bumpVersion(); // Versions the entire aggregate
+ *     this.setState({ ...this.state, status: "confirmed" }, true);
  *   }
  * }
  * ```
  */
-declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = unknown> extends Entity<TState, TId> implements IAggregateRoot<TId> {
-    version: Version;
+declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = never> extends Entity<TState, TId> implements IAggregateRoot<TId> {
+    private _version;
+    get version(): Version;
+    protected setVersion(version: Version): void;
     private readonly _config;
     private readonly _autoVersionBump;
     private _domainEvents;
@@ -354,12 +733,92 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = un
      * Call this after dispatching the events.
      */
     clearDomainEvents(): void;
+    /**
+     * Post-save hook called by a `Repository.save()` implementation to push
+     * the persisted version back into the in-memory aggregate and clear the
+     * recorded domain events (they are now safely on the write side / in
+     * the outbox).
+     *
+     * Use this so `save()` can keep its `Promise<void>` return type: the
+     * caller holds the aggregate reference, which is up to date after this
+     * call.
+     */
+    markPersisted(version: Version): void;
+    /**
+     * Mutates state and records the resulting domain events in the
+     * **canonical record-after-mutation order**. Use this instead of calling
+     * `setState` + `addDomainEvent` separately and you cannot trip the
+     * "event for a fact that never happened" footgun.
+     *
+     * Order of operations:
+     *  1. `setState(newState, true)` — runs `validateState` first.
+     *     If it throws, the method propagates and **no event is recorded
+     *     and no version is bumped**.
+     *  2. Each event in `events` is appended via `addDomainEvent`.
+     *
+     * `commit()` **always bumps the version**, regardless of the aggregate's
+     * `autoVersionBump` config. Recording a domain event implies "something
+     * happened that the outside world cares about", and optimistic-
+     * concurrency callers must see a fresh version every time. The config
+     * still governs the un-coupled `setState` path. If you need to mutate
+     * state without bumping (e.g. cosmetic caches), call `setState(newState,
+     * false)` and skip `commit` entirely.
+     *
+     * `events` accepts a single event or an array. Omit it (or pass `[]`)
+     * for state-only mutations.
+     *
+     * @example
+     * ```ts
+     * confirm(): void {
+     *   if (this.state.status === "confirmed") {
+     *     throw new OrderAlreadyConfirmedError(this.id);
+     *   }
+     *   this.commit(
+     *     { ...this.state, status: "confirmed" },
+     *     { type: "OrderConfirmed", orderId: this.id },
+     *   );
+     * }
+     * ```
+     *
+     * `EventSourcedAggregate.apply()` enforces the same ordering
+     * structurally; `commit()` is the opt-in equivalent on `AggregateRoot`,
+     * where `setState` and `addDomainEvent` are otherwise decoupled and the
+     * ordering is convention-only.
+     *
+     * @param newState - The new state (validated by `validateState`)
+     * @param events - One event, an array of events, or none (default)
+     */
+    protected commit(newState: TState, events?: TEvent | readonly TEvent[]): void;
     protected constructor(id: TId, initialState: TState, config?: AggregateConfig);
     /**
-     * Adds a domain event to the aggregate's list of changes.
-     * Use this to record side-effects that should be published.
+     * Records a domain event for later publication.
+     *
+     * **Ordering: record AFTER state mutation.** Vernon (IDDD §8) is
+     * explicit: a domain event describes something that has just happened
+     * to the aggregate — its existence implies the state change already
+     * occurred. Concretely:
+     *
+     * ```ts
+     * confirm(): void {
+     *   if (this.state.status === "confirmed") {
+     *     throw new OrderAlreadyConfirmedError(this.id);
+     *   }
+     *   this.setState({ ...this.state, status: "confirmed" }, true);
+     *   this.addDomainEvent({ type: "OrderConfirmed", orderId: this.id });
+     *   // ↑ post-mutation. The event represents the committed fact.
+     * }
+     * ```
+     *
+     * Recording before mutation is a footgun: if a subsequent invariant
+     * check throws, the event has already been queued but the state never
+     * actually changed — consumers see an event for a fact that did not
+     * happen.
      *
-     * @param event - The domain event to add
+     * `EventSourcedAggregate.apply()` enforces this ordering structurally;
+     * `AggregateRoot` leaves it as a convention because the state-mutation
+     * path (`setState`) is decoupled from event recording.
+     *
+     * @param event - The domain event to record
      */
     protected addDomainEvent(event: TEvent): void;
     /**
@@ -410,6 +869,54 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = un
     restoreFromSnapshot(snapshot: AggregateSnapshot<TState>): void;
 }
 
+/**
+ * Abstract base for all domain-layer exceptions in ddd-kit.
+ *
+ * Domain methods throw `DomainError`-derived exceptions when invariants are
+ * violated. Consumers derive their own concrete errors from this base
+ * (e.g. `OrderAlreadyShippedError extends DomainError`) so that domain
+ * failures have sprechende names and can be caught via `instanceof`.
+ *
+ * The library itself uses this base only for its own internal errors
+ * (`MissingHandlerError`, `AggregateNotFoundError`) — everything else
+ * is consumer territory.
+ */
+declare abstract class DomainError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown by `EventSourcedAggregate.apply()` when no handler is registered
+ * for the given event type. Indicates a missing entry in the aggregate's
+ * `handlers` map — a programming error in the aggregate definition.
+ */
+declare class MissingHandlerError extends DomainError {
+    readonly eventType: string;
+    constructor(eventType: string);
+}
+/**
+ * Thrown by `IRepository.getByIdOrFail()` when an aggregate with the given
+ * id does not exist. Use the nullable variant `getById()` if "not found"
+ * is an expected outcome.
+ */
+declare class AggregateNotFoundError extends DomainError {
+    readonly aggregateType: string;
+    readonly id: string;
+    constructor(aggregateType: string, id: string);
+}
+/**
+ * Thrown by `IRepository.save()` when the aggregate's expected version does
+ * not match the version currently persisted — i.e. another writer updated
+ * the aggregate concurrently. The canonical DDD optimistic-concurrency
+ * signal; callers typically reload, re-apply the use case, and retry.
+ */
+declare class ConcurrencyConflictError extends DomainError {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    constructor(aggregateType: string, aggregateId: string, expectedVersion: number, actualVersion: number);
+}
+
 /**
  * Interface for Event-Sourced Aggregate Roots.
  * Defines the contract for aggregates that manage state changes via event sourcing.
@@ -417,17 +924,19 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = un
  * @template TId - The type of the aggregate root identifier
  * @template TEvent - The union type of all domain events
  */
-interface IAggregateEventSourced<TId extends Id<string>, TEvent extends DomainEvent<string, unknown>> extends IAggregateRoot<TId> {
+interface IEventSourcedAggregate<TId extends Id<string>, TEvent extends DomainEvent<string, unknown>> extends IAggregateRoot<TId> {
     /**
      * Returns a read-only list of new, not-yet-persisted events.
      */
     readonly pendingEvents: ReadonlyArray<TEvent>;
     /**
-     * Reconstitutes the aggregate from an event history.
+     * Reconstitutes the aggregate from an event history. Returns `Result`
+     * because event-stream corruption is an expected recoverable failure
+     * at the infrastructure boundary.
      *
      * @param history - An ordered list of past events
      */
-    loadFromHistory(history: TEvent[]): Result<void, string>;
+    loadFromHistory(history: TEvent[]): Result<void, DomainError>;
     /**
      * Clears the list of pending events.
      */
@@ -447,336 +956,174 @@ interface IAggregateEventSourced<TId extends Id<string>, TEvent extends DomainEv
 }
 type Handler<TState, TEvent> = (state: TState, event: TEvent) => TState;
 /**
- * Extended configuration options for AggregateEventSourced behavior.
+ * Configuration options for EventSourcedAggregate behavior.
  */
-interface AggregateEventSourcedConfig extends AggregateConfig {
+interface EventSourcedAggregateConfig {
     /**
-     * Whether to automatically bump the version when applying new events.
-     * Defaults to true. Set to false to manually control versioning.
-     */
-    autoVersionBump?: boolean;
-}
-/**
- * Base class for Event-Sourced Aggregate Roots (Entities).
- *
- * Extends `AggregateRoot` to create an Aggregate Root Entity with Event Sourcing capabilities.
- * The Aggregate Root is the parent Entity of the aggregate and represents it externally.
- *
- * The aggregate state (`TState`) contains:
- * - Child entities (Entities with id, but no own version)
- * - Value objects (immutable objects)
- *
- * All changes to child entities are versioned through the Aggregate Root. The version
- * applies to the entire aggregate, including all child entities.
- *
- * Extends `AggregateRoot` with Event Sourcing capabilities:
- * - Event tracking (pendingEvents)
- * - Event handlers for state transitions
- * - Event validation
- * - History replay
- *
- * Use this class when you want Event Sourcing with full event tracking
- * and replay capabilities.
- *
- * @template TState - The type of the aggregate state (contains child entities and value objects)
- * @template TEvent - The union type of all domain events
- * @template TId - The type of the aggregate root identifier
- *
- * @example
- * ```typescript
- * // Order is an Aggregate Root (an Entity) with Event Sourcing
- * class Order extends AggregateEventSourced<OrderState, OrderEvent, OrderId> {
- *   confirm(): void {
- *     this.apply(createDomainEvent("OrderConfirmed", {}));
- *   }
- *
- *   protected readonly handlers = {
- *     OrderConfirmed: (state: OrderState): OrderState => ({
- *       ...state,
- *       status: "confirmed",
- *     }),
- *   };
- * }
- * ```
- */
-declare abstract class AggregateEventSourced<TState, TEvent extends DomainEvent<string, unknown>, TId extends Id<string>> extends AggregateRoot<TState, TId, TEvent> implements IAggregateEventSourced<TId, TEvent> {
-    private readonly _eventConfig;
-    private readonly _eventAutoVersionBump;
-    protected constructor(id: TId, initialState: TState, config?: AggregateEventSourcedConfig);
-    /**
-     * Returns a read-only list of new, not-yet-persisted events.
-     */
-    get pendingEvents(): ReadonlyArray<TEvent>;
-    /**
-     * Clears the list of pending events.
-     * Typically called after the events have been persisted.
-     */
-    clearPendingEvents(): void;
-    /**
-     * Validates an event before it is applied.
-     * Override this method to add custom validation logic.
-     * Return `ok(true)` if the event is valid, `err(message)` otherwise.
-     *
-     * @param event - The event to validate
-     * @returns Result indicating if the event is valid
-     *
-     * @example
-     * ```typescript
-     * protected validateEvent(event: OrderEvent): Result<true, string> {
-     *   if (event.type === "OrderShipped" && this.state.status !== "confirmed") {
-     *     return err("Order must be confirmed before shipping");
-     *   }
-     *   return ok(true);
-     * }
-     * ```
-     */
-    protected validateEvent(_event: TEvent): Result<true, string>;
-    /**
-     * Applies an event to change the state and adds it
-     * to the list of pending events.
-     * Returns a Result type instead of throwing an error.
-     *
-     * @param event - The domain event to apply
-     * @param isNew - Indicates whether the event is new (and needs to be persisted)
-     *                or if it is being loaded from history
-     * @returns Result<void, string> - ok if successful, err with error message if validation fails or handler is missing
-     */
-    protected apply(event: TEvent, isNew?: boolean): Result<void, string>;
-    /**
-     * Applies an event to change the state and adds it
-     * to the list of pending events.
-     * Throws an error if validation fails or handler is missing.
-     *
-     * @param event - The domain event to apply
-     * @param isNew - Indicates whether the event is new (and needs to be persisted)
-     *                or if it is being loaded from history
-     * @throws Error if event validation fails or handler is missing
-     */
-    protected applyUnsafe(event: TEvent, isNew?: boolean): void;
-    /**
-     * Manually bumps the aggregate version.
-     * Only needed if `autoVersionBump` is disabled.
-     */
-    protected bumpVersion(): void;
-    /**
-     * Reconstitutes the aggregate from an event history.
-     * Sets the version to the number of events in the history.
-     *
-     * @param history - An ordered list of past events
-     */
-    loadFromHistory(history: TEvent[]): Result<void, string>;
-    /**
-     * Checks if the aggregate has any pending events.
-     *
-     * @returns true if there are pending events, false otherwise
-     */
-    hasPendingEvents(): boolean;
-    /**
-     * Returns the number of pending events.
-     *
-     * @returns The count of pending events
-     */
-    getEventCount(): number;
-    /**
-     * Returns the latest pending event, if any.
-     *
-     * @returns The most recent event or undefined if no events exist
-     */
-    getLatestEvent(): TEvent | undefined;
-    /**
-     * Restores the aggregate from a snapshot and applies events that occurred after the snapshot.
-     * This is more efficient than replaying all events from the beginning.
-     *
-     * @param snapshot - The snapshot to restore from
-     * @param eventsAfterSnapshot - Events that occurred after the snapshot was taken
-     *
-     * @example
-     * ```typescript
-     * const snapshot = await snapshotRepository.getLatest(aggregateId);
-     * const eventsAfter = await eventStore.getEventsAfter(aggregateId, snapshot.version);
-     * aggregate.restoreFromSnapshotWithEvents(snapshot, eventsAfter);
-     * ```
-     */
-    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: TEvent[]): Result<void, string>;
-    /**
-     * A map of event types to their corresponding handlers.
-     * Subclasses MUST implement this property.
-     */
-    protected abstract readonly handlers: {
-        [K in TEvent["type"]]: Handler<TState, Extract<TEvent, {
-            type: K;
-        }>>;
-    };
-}
-
-type Version = number & {
-    readonly __v: true;
-};
-/**
- * Metadata associated with a domain event for traceability and correlation.
- * Used in event-driven architectures to track event flow across services.
- */
-interface EventMetadata {
-    /**
-     * Correlation ID for tracing events across multiple services/components.
-     * Typically used to group related events in a distributed system.
-     */
-    correlationId?: string;
-    /**
-     * Causation ID referencing the event or command that caused this event.
-     * Used to build event chains and understand causality.
-     */
-    causationId?: string;
-    /**
-     * User ID of the person or system that triggered the event.
-     */
-    userId?: string;
-    /**
-     * Source service or component that produced the event.
-     */
-    source?: string;
-    /**
-     * Additional custom metadata fields.
-     * Allows extensibility for domain-specific metadata.
-     */
-    [key: string]: unknown;
-}
-/**
- * Domain Event represents something meaningful that happened in the domain.
- * Events are immutable and carry information about what occurred.
- *
- * @template T - The event type name (e.g., "OrderCreated")
- * @template P - The event payload type
- */
-interface DomainEvent<T extends string, P = void> {
-    /**
-     * The type of the event, used for routing and handling.
-     */
-    type: T;
-    /**
-     * The event payload containing the domain data.
-     * Omitted when P is void (events without payload).
-     */
-    payload: P;
-    /**
-     * Timestamp when the event occurred.
-     */
-    occurredAt: Date;
-    /**
-     * Event schema version for handling schema evolution.
-     * Defaults to 1 if not specified. Higher versions indicate schema changes.
-     */
-    version?: number;
-    /**
-     * Optional metadata for traceability, correlation, and auditing.
-     * Includes correlationId, causationId, userId, source, and custom fields.
-     */
-    metadata?: EventMetadata;
-}
-
-/**
- * Structural interface representing an aggregate with state and events.
- * Used for type constraints in repositories and other infrastructure code.
- *
- * @template State - The type of the aggregate state
- * @template Evt - The union type of all domain events
- */
-interface Aggregate<State, Evt extends DomainEvent<string, unknown>> {
-    state: Readonly<State>;
-    version: Version;
-    pendingEvents: ReadonlyArray<Evt>;
-}
-declare function aggregate<State, Evt extends DomainEvent<string, unknown>>(state: State, version?: Version): Aggregate<State, Evt>;
-declare function withEvent<S, E extends DomainEvent<string, unknown>>(agg: Aggregate<S, E>, evt: E): Aggregate<S, E>;
-declare function bump<S, E extends DomainEvent<string, unknown>>(agg: Aggregate<S, E>): Aggregate<S, E>;
-/**
- * Creates a domain event with default values.
- * Sets occurredAt to current date and version to 1 if not provided.
- *
- * @param type - The event type
- * @param payload - The event payload
- * @param options - Optional event configuration
- * @returns A domain event
- *
- * @example
- * ```typescript
- * const event = createDomainEvent("OrderCreated", { orderId: "123" });
- * ```
- */
-declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: {
-    occurredAt?: Date;
-    version?: number;
-    metadata?: EventMetadata;
-}): DomainEvent<T, void>;
-declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: {
-    occurredAt?: Date;
-    version?: number;
-    metadata?: EventMetadata;
-}): DomainEvent<T, P>;
+     * Whether `apply()` should bump the version per event.
+     *
+     * Defaults to **`true`** for `EventSourcedAggregate` — each applied
+     * event is by definition a versioned state change, so the canonical
+     * event-sourcing pattern is "one event = one version bump". Set to
+     * `false` only if your event store assigns version numbers itself
+     * and you want the aggregate to track them via `bumpVersion()` /
+     * `setVersion()` calls instead.
+     *
+     * (Contrast with `AggregateRoot`, which defaults this to `false`
+     * because its `setState()` already takes a per-call `bumpVersion`
+     * argument.)
+     */
+    autoVersionBump?: boolean;
+}
 /**
- * Creates a domain event with metadata for traceability.
- * Convenience function for creating events with correlation and causation IDs.
+ * Base class for Event-Sourced Aggregate Roots (Vernon, IDDD Chapter 8).
  *
- * @param type - The event type
- * @param payload - The event payload
- * @param metadata - Event metadata for traceability
- * @param options - Optional event configuration
- * @returns A domain event with metadata
+ * Like `AggregateRoot`, this is both the root entity and the aggregate boundary.
+ * The difference is persistence: state is derived from events, not stored directly.
+ * Events are the single source of truth — all state changes go through `apply()` → handler.
  *
- * @example
- * ```typescript
- * const event = createDomainEventWithMetadata(
- *   "OrderCreated",
- *   { orderId: "123" },
- *   {
- *     correlationId: "corr-123",
- *     causationId: "cmd-456",
- *     userId: "user-789"
- *   }
- * );
- * ```
- */
-declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: {
-    occurredAt?: Date;
-    version?: number;
-}): DomainEvent<T, P>;
-/**
- * Copies metadata from a source event to a new event.
- * Useful for maintaining correlation chains in event-driven architectures.
+ * Extends `Entity` directly (not `AggregateRoot`) so that `setState()` and
+ * `addDomainEvent()` are not available. This enforces the event sourcing pattern
+ * at the type level — there is no way to mutate state without going through an event handler.
  *
- * @param sourceEvent - The source event to copy metadata from
- * @param additionalMetadata - Additional metadata to merge in
- * @returns Event metadata with copied and merged values
+ * `apply()` and `validateEvent()` throw `DomainError`-derived exceptions on
+ * invariant violations. Subclasses override `validateEvent()` to throw their
+ * own concrete subclasses (e.g. `OrderAlreadyConfirmedError`). Only the
+ * infrastructure-boundary methods (`loadFromHistory`,
+ * `restoreFromSnapshotWithEvents`) return `Result` — they catch `DomainError`
+ * during replay so callers can react to corrupted event streams without
+ * try/catch.
+ *
+ * @template TState - The type of the aggregate state (contains child entities and value objects)
+ * @template TEvent - The union type of all domain events
+ * @template TId - The type of the aggregate root identifier
  *
  * @example
  * ```typescript
- * const newEvent = createDomainEvent(
- *   "OrderShipped",
- *   { orderId: "123" },
- *   {
- *     metadata: copyMetadata(previousEvent, { causationId: previousEvent.type })
+ * class OrderAlreadyConfirmedError extends DomainError {
+ *   constructor(id: OrderId) { super(`Order ${id} is already confirmed`); }
+ * }
+ *
+ * class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
+ *   confirm(): void {
+ *     this.apply(createDomainEvent("OrderConfirmed", {}));
  *   }
- * );
- * ```
- */
-declare function copyMetadata(sourceEvent: DomainEvent<string, unknown>, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
-/**
- * Merges multiple metadata objects into one.
- * Later metadata objects override earlier ones for the same keys.
  *
- * @param metadataObjects - Array of metadata objects to merge
- * @returns Merged event metadata
+ *   protected validateEvent(event: OrderEvent): void {
+ *     if (event.type === "OrderConfirmed" && this.state.status === "confirmed") {
+ *       throw new OrderAlreadyConfirmedError(this.id);
+ *     }
+ *   }
  *
- * @example
- * ```typescript
- * const metadata = mergeMetadata(
- *   { correlationId: "corr-123" },
- *   { userId: "user-456" },
- *   { source: "order-service" }
- * );
+ *   protected readonly handlers = {
+ *     OrderConfirmed: (state: OrderState): OrderState => ({
+ *       ...state,
+ *       status: "confirmed",
+ *     }),
+ *   };
+ * }
  * ```
  */
-declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
+declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<string, unknown>, TId extends Id<string>> extends Entity<TState, TId> implements IEventSourcedAggregate<TId, TEvent> {
+    private _version;
+    get version(): Version;
+    private setVersion;
+    private _pendingEvents;
+    private readonly _autoVersionBump;
+    get pendingEvents(): ReadonlyArray<TEvent>;
+    clearPendingEvents(): void;
+    /**
+     * Post-save hook called by a `Repository.save()` implementation to push
+     * the persisted version back into the in-memory aggregate and clear the
+     * pending events (they are now in the event store / outbox). Lets
+     * `save()` keep its `Promise<void>` return type.
+     */
+    markPersisted(version: Version): void;
+    protected constructor(id: TId, initialState: TState, config?: EventSourcedAggregateConfig);
+    /**
+     * Validates an event before it is applied. Default is no-op.
+     * Subclasses override to throw a concrete `DomainError` subclass when
+     * the event violates an invariant in the current state.
+     */
+    protected validateEvent(_event: TEvent): void;
+    /**
+     * Applies an event: validates, locates the handler, computes the next
+     * state, then commits state + pending event + version bump atomically.
+     *
+     * Throws `DomainError` (or a subclass) on validation failure.
+     * Throws `MissingHandlerError` if no handler is registered for `event.type`.
+     *
+     * State is not mutated if any step throws — the handler is invoked into
+     * a local and only assigned to `_state` once all checks pass.
+     *
+     * The method is generic in the event tag `K`, so concrete callers
+     * (`this.apply(orderCreated)`) narrow to the literal tag and the
+     * dispatched handler is typed as `Handler<TState, Extract<TEvent, { type: K }>>`
+     * — no `as` cast required at the call site.
+     *
+     * @param event - The domain event to apply
+     * @param isNew - Whether the event is new (needs persisting) or replayed from history
+     */
+    protected apply<K extends TEvent["type"]>(event: Extract<TEvent, {
+        type: K;
+    }>, isNew?: boolean): void;
+    /**
+     * Internal dispatch path used by `apply()` and the replay methods
+     * (`loadFromHistory`, `restoreFromSnapshotWithEvents`). The replay loop
+     * iterates over `TEvent[]` and therefore cannot supply a narrowed `K`
+     * generic, so this helper accepts `TEvent` and the discriminator is
+     * resolved via the (statically-sound) `handlers` map.
+     */
+    private dispatchAndCommit;
+    /**
+     * Manually bumps the aggregate version.
+     * Only needed if `autoVersionBump` is disabled.
+     */
+    protected bumpVersion(): void;
+    /**
+     * Reconstitutes the aggregate from an event history. Catches `DomainError`
+     * thrown during replay and returns it as an `Err` — this is the
+     * infrastructure boundary, where event-stream corruption is an expected
+     * recoverable failure. Unexpected (non-DomainError) throws propagate.
+     *
+     * Version advances additively: the aggregate's pre-existing version plus
+     * `history.length`. A fresh aggregate (v=0) loading 3 events ends at v=3;
+     * an aggregate already at v=1 (e.g. after a creation event) loading
+     * 2 events ends at v=3, not v=2.
+     */
+    loadFromHistory(history: TEvent[]): Result<void, DomainError>;
+    hasPendingEvents(): boolean;
+    getEventCount(): number;
+    getLatestEvent(): TEvent | undefined;
+    /**
+     * Creates a snapshot of the current aggregate state.
+     */
+    createSnapshot(): AggregateSnapshot<TState>;
+    /**
+     * Restores the aggregate from a snapshot and applies events that occurred
+     * after. Same infrastructure-boundary semantics as `loadFromHistory`:
+     * catches `DomainError` and returns it as an `Err`; non-domain throws
+     * propagate.
+     *
+     * All-or-nothing: if any event mid-stream throws a `DomainError`, the
+     * aggregate is rolled back to its pre-call state + version. Partial
+     * restoration is never observable to the caller.
+     */
+    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: TEvent[]): Result<void, DomainError>;
+    /**
+     * A map of event types to their corresponding handlers.
+     * Subclasses MUST implement this property.
+     */
+    protected abstract readonly handlers: {
+        [K in TEvent["type"]]: Handler<TState, Extract<TEvent, {
+            type: K;
+        }>>;
+    };
+}
+
+type Version = number & {
+    readonly __v: true;
+};
 /**
  * Snapshot of an aggregate state at a specific point in time.
  * Used for optimizing event replay by starting from a snapshot
@@ -799,25 +1146,24 @@ interface AggregateSnapshot<TState> {
     snapshotAt: Date;
 }
 /**
- * Checks if two aggregates are the same (same ID and version).
+ * Checks if two aggregates are at the same version (same ID and version).
  * Useful for optimistic concurrency control checks.
  *
- * @param a - First aggregate
- * @param b - Second aggregate
- * @returns true if both aggregates have the same ID and version
+ * Note: Two aggregates with the same ID ARE the same aggregate (identity).
+ * This function checks if they are at the same version — i.e., no concurrent modification.
  *
  * @example
  * ```typescript
- * const aggregate1 = await repository.getById(id);
+ * const before = await repository.getById(id);
  * // ... some operations ...
- * const aggregate2 = await repository.getById(id);
+ * const after = await repository.getById(id);
  *
- * if (!sameAggregate(aggregate1, aggregate2)) {
+ * if (!sameVersion(before, after)) {
  *   throw new Error("Aggregate was modified by another process");
  * }
  * ```
  */
-declare function sameAggregate<TId extends Id<string>>(a: {
+declare function sameVersion<TId extends Id<string>>(a: {
     id: TId;
     version: Version;
 }, b: {
@@ -913,42 +1259,85 @@ interface Command {
  */
 type CommandHandler<C extends Command, R> = (cmd: C) => Promise<Result<R, string>>;
 
+/**
+ * Type map for command types to their return types.
+ * Used to improve type inference in CommandBus.
+ *
+ * @example
+ * ```typescript
+ * type MyCommandMap = {
+ *   CreateOrder: OrderId;
+ *   CancelOrder: void;
+ * };
+ *
+ * const bus = new CommandBus<MyCommandMap>();
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * // result: Result<OrderId, string>  ← automatically inferred
+ * ```
+ */
+type CommandTypeMap = Record<string, unknown>;
 /**
  * Command Bus interface for dispatching commands to their handlers.
  * Provides a centralized way to execute commands with handler registration.
  *
+ * Supports an optional type map (`TMap`) for automatic return type inference.
+ * Without a type map, the return type must be specified manually or defaults to `unknown`.
+ *
+ * @template TMap - Optional mapping from command type strings to return types
+ *
  * @example
  * ```typescript
+ * // With type map (recommended) – return type is inferred
+ * type MyCommands = { CreateOrder: OrderId; CancelOrder: void };
+ * const bus = new CommandBus<MyCommands>();
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * // result: Result<OrderId, string>
+ *
+ * // Without type map – works like before
  * const bus = new CommandBus();
  * bus.register("CreateOrder", createOrderHandler);
- *
- * const result = await bus.execute({
- *   type: "CreateOrder",
- *   customerId: "123",
- *   items: [...]
- * });
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * // result: Result<unknown, string>
  * ```
  */
-interface ICommandBus {
+interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
     /**
      * Executes a command by dispatching it to the registered handler.
+     * When a type map is provided, the return type is inferred from the command type.
      *
      * @param command - The command to execute
      * @returns Result containing the success value or error message
      */
+    execute<C extends Command & {
+        type: keyof TMap & string;
+    }>(command: C): Promise<Result<TMap[C["type"]], string>>;
     execute<C extends Command, R>(command: C): Promise<Result<R, string>>;
     /**
      * Registers a handler for a specific command type.
      *
+     * When `TMap` is supplied, the `commandType` argument is restricted to
+     * its keys and the handler signature is forced to match `TMap[K]` for the
+     * return value — typos and wrong-typed handlers are compile errors.
+     * Without `TMap` the registration is loose (any string key, any return
+     * type) so the no-config path keeps working.
+     *
      * @param commandType - The command type to register the handler for
      * @param handler - The handler function for this command type
      */
-    register<C extends Command, R>(commandType: C["type"], handler: CommandHandler<C, R>): void;
+    register<K extends keyof TMap & string, C extends Command & {
+        type: K;
+    } = Command & {
+        type: K;
+    }>(commandType: K, handler: CommandHandler<C, TMap[K]>): void;
 }
 /**
  * Simple in-memory command bus implementation.
  * Handlers are stored in a Map and dispatched based on command type.
  *
+ * Supports an optional type map (`TMap`) for automatic return type inference.
+ * When `TMap` is provided, `execute()` infers the result type from the command type.
+ * Without `TMap`, it works like before (return type defaults to `unknown` or can be specified manually).
+ *
  * **Note:** This is a basic implementation suitable for development and simple use cases.
  * For production environments, consider implementing or using a more feature-rich bus that includes:
  * - Middleware/Pipeline support (logging, validation, authorization)
@@ -961,20 +1350,32 @@ interface ICommandBus {
  * The `CommandHandler` type can still be used with external production-grade buses
  * (e.g., RabbitMQ, AWS SQS) while maintaining type safety.
  *
+ * @template TMap - Optional mapping from command type strings to return types
+ *
  * @example
  * ```typescript
- * const bus = new CommandBus();
- * bus.register("CreateOrder", async (cmd) => {
- *   // ... handler logic
- *   return ok(orderId);
- * });
+ * // With type map – full inference
+ * type Commands = { CreateOrder: OrderId; CancelOrder: void };
+ * const bus = new CommandBus<Commands>();
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * // result: Result<OrderId, string>
  *
+ * // Without type map – same as before
+ * const bus = new CommandBus();
+ * bus.register("CreateOrder", async (cmd) => ok(orderId));
  * const result = await bus.execute({ type: "CreateOrder", ... });
  * ```
  */
-declare class CommandBus implements ICommandBus {
+declare class CommandBus<TMap extends CommandTypeMap = CommandTypeMap> implements ICommandBus<TMap> {
     private readonly handlers;
-    register<C extends Command, R>(commandType: C["type"], handler: CommandHandler<C, R>): void;
+    register<K extends keyof TMap & string, C extends Command & {
+        type: K;
+    } = Command & {
+        type: K;
+    }>(commandType: K, handler: CommandHandler<C, TMap[K]>): void;
+    execute<C extends Command & {
+        type: keyof TMap & string;
+    }>(command: C): Promise<Result<TMap[C["type"]], string>>;
     execute<C extends Command, R>(command: C): Promise<Result<R, string>>;
 }
 
@@ -1007,10 +1408,33 @@ type EventHandler<Evt> = (event: Evt) => Promise<void> | void;
  * await bus.publish([orderCreatedEvent, orderShippedEvent]);
  * ```
  */
-interface EventBus<Evt> {
+interface EventBus<Evt extends {
+    type: string;
+}> {
     /**
      * Publishes events to all subscribed handlers.
-     * All handlers for each event type will be called.
+     *
+     * **Ordering & parallelism contract:**
+     *
+     *  1. **Events run in input order.** `publish([a, b, c])` dispatches `a`,
+     *     awaits all of its handlers, then dispatches `b`, and so on. The
+     *     library never reorders or parallelises across events.
+     *  2. **Handlers within a single event run in parallel.** All handlers
+     *     subscribed to `event.type` are awaited via `Promise.allSettled` —
+     *     none of them sees the others' errors and none is skipped if a
+     *     peer fails.
+     *  3. **Errors are collected and thrown AFTER everything dispatches.**
+     *     If one handler throws, remaining handlers for that event still
+     *     run, and remaining events in the batch still publish. Once
+     *     `publish` reaches the end of the batch it throws — the single
+     *     error directly if there was one, or an `AggregateError`
+     *     ("Multiple event handlers failed") containing every captured
+     *     error otherwise. Callers that need fail-fast semantics should
+     *     publish events one at a time and not rely on batch atomicity.
+     *
+     * The contract is intentionally simple and in-process. For
+     * cross-process delivery (RabbitMQ, Kafka, etc.), use the `Outbox`
+     * port and a dedicated dispatcher.
      *
      * @param events - Array of events to publish
      */
@@ -1033,7 +1457,9 @@ interface EventBus<Evt> {
      * unsubscribe();
      * ```
      */
-    subscribe: <T extends Evt>(eventType: string, handler: EventHandler<T>) => () => void;
+    subscribe: <K extends Evt["type"]>(eventType: K, handler: EventHandler<Extract<Evt, {
+        type: K;
+    }>>) => () => void;
     /**
      * Subscribes to the next occurrence of an event type.
      * Returns a Promise that resolves with the event data.
@@ -1048,27 +1474,125 @@ interface EventBus<Evt> {
      * console.log("Order created:", event.payload.orderId);
      * ```
      */
-    once: <T extends Evt>(eventType: string) => Promise<T>;
+    once: <K extends Evt["type"]>(eventType: K, options?: OnceOptions) => Promise<Extract<Evt, {
+        type: K;
+    }>>;
+}
+/**
+ * Options for `EventBus.once()`. Both fields are optional; without them
+ * `once()` waits forever (the historical behaviour).
+ */
+interface OnceOptions {
+    /**
+     * Aborts the wait. When `signal` fires, `once()` rejects with
+     * `signal.reason` (or a generic abort error if none was supplied) and
+     * the internal subscription is removed.
+     */
+    signal?: AbortSignal;
+    /**
+     * Rejects with a timeout error after this many milliseconds if no event
+     * has arrived. The internal subscription and timer are cleaned up
+     * regardless of which path settles the promise.
+     */
+    timeoutMs?: number;
+}
+/**
+ * One pending event in the outbox plus the opaque id the implementation
+ * needs to ack it via `markDispatched`. The library does not prescribe
+ * what `dispatchId` looks like — an implementation can reuse the event's
+ * own `eventId`, generate its own UUID, use the row's auto-increment
+ * primary key, or whatever the storage layer prefers.
+ */
+interface OutboxRecord<Evt> {
+    dispatchId: string;
+    event: Evt;
 }
+/**
+ * Transactional outbox port — the bridge between the write-side
+ * transaction and the (out-of-band) event dispatcher.
+ *
+ * Lifecycle:
+ *  1. `add()` inside the write transaction (`withCommit` calls this) so
+ *     events persist atomically with the aggregate state.
+ *  2. A separate outbox dispatcher polls `getPending()` and forwards the
+ *     events to subscribers / external brokers.
+ *  3. After successful dispatch, the dispatcher calls `markDispatched()`
+ *     with the records' `dispatchId`s so they don't come back next poll.
+ *
+ * `markDispatched` is required to be idempotent — calling it with an id
+ * that's already marked is a no-op, not an error. This lets the
+ * dispatcher safely retry on partial-failure.
+ */
 interface Outbox<Evt> {
+    /**
+     * Persists events. Called from inside `withCommit`'s transactional
+     * callback, atomically with the aggregate write.
+     *
+     * **Idempotency:** implementations should dedupe on the event's
+     * `eventId`. `withCommit` itself does not retry, but the surrounding
+     * use case (a queue consumer, an HTTP retry, a transactional
+     * outbox-dispatcher loop) may legitimately invoke the same write more
+     * than once. A unique-key constraint on `(eventId)` in the outbox
+     * table is the standard implementation.
+     */
     add: (events: ReadonlyArray<Evt>) => Promise<void>;
-}
-interface Clock {
-    now: () => Date;
+    /**
+     * Returns up to `limit` outbox records that have not yet been
+     * dispatched. The dispatcher polls this on a schedule. When `limit`
+     * is omitted, the implementation decides on a default page size.
+     */
+    getPending: (limit?: number) => Promise<ReadonlyArray<OutboxRecord<Evt>>>;
+    /**
+     * Marks the given dispatch records as delivered so subsequent
+     * `getPending` calls don't return them. Must be idempotent on
+     * already-marked ids.
+     */
+    markDispatched: (dispatchIds: ReadonlyArray<string>) => Promise<void>;
 }
 
-interface UnitOfWork {
+/**
+ * Transaction-scope abstraction.
+ *
+ * Wraps a block of work so it runs inside the persistence layer's native
+ * transaction (Postgres `BEGIN`/`COMMIT`, Mongo session, etc.). The block
+ * commits when the callback resolves and rolls back if it throws.
+ *
+ * This is **not** Fowler's full Unit of Work (no change tracking, no
+ * registerDirty/registerNew/registerDeleted, no commit-time flush). It is
+ * intentionally minimal — change tracking is the ORM's job; the library
+ * stays out of it. The name `TransactionScope` is therefore more honest
+ * than `UnitOfWork`.
+ *
+ * @example
+ * ```typescript
+ * await scope.transactional(async () => {
+ *   const order = await repo.getByIdOrFail(orderId);
+ *   order.confirm();
+ *   await repo.save(order);
+ * });
+ * ```
+ */
+interface TransactionScope {
     transactional<T>(fn: () => Promise<T>): Promise<T>;
 }
-type RepoProvider<R> = (uow: UnitOfWork) => R;
 
 /**
- * Helper function for executing commands within a transaction.
- * Handles event persistence via outbox and optional event bus publishing.
- *
- * @param deps - Dependencies including outbox, optional event bus, and unit of work
- * @param fn - Function that returns result and events
- * @returns The result wrapped in a transaction
+ * Helper for executing a write Use Case inside a Unit of Work.
+ *
+ * Order of operations:
+ *  1. `fn()` runs inside `uow.transactional(...)` — domain mutations + repo
+ *     writes happen here.
+ *  2. `outbox.add(events)` is also inside the transaction, so events
+ *     persist atomically with the state change (outbox pattern).
+ *  3. The transaction commits.
+ *  4. **After** the commit, `bus.publish(events)` fires for the in-process
+ *     fast path.
+ *
+ * Publishing AFTER commit prevents the classic "publish before commit"
+ * footgun: in-process subscribers can never react to events from a
+ * transaction that later rolled back. If `bus.publish` itself fails, the
+ * outbox still holds the events and an outbox-dispatcher will deliver them
+ * (eventual consistency).
  *
  * @example
  * ```typescript
@@ -1077,18 +1601,17 @@ type RepoProvider<R> = (uow: UnitOfWork) => R;
  *   async () => {
  *     const order = Order.create(customerId, items);
  *     await repository.save(order);
- *     return {
- *       result: order.id,
- *       events: order.pendingEvents
- *     };
+ *     return { result: order.id, events: order.domainEvents };
  *   }
  * );
  * ```
  */
-declare function withCommit<Evt, R>(deps: {
+declare function withCommit<Evt extends {
+    type: string;
+}, R>(deps: {
     outbox: Outbox<Evt>;
     bus?: EventBus<Evt>;
-    uow: UnitOfWork;
+    scope: TransactionScope;
 }, fn: () => Promise<{
     result: R;
     events: ReadonlyArray<Evt>;
@@ -1169,29 +1692,57 @@ interface Query {
  */
 type QueryHandler<Q extends Query, R> = (query: Q) => Promise<R>;
 
+/**
+ * Type map for query types to their return types.
+ * Used to improve type inference in QueryBus.
+ *
+ * @example
+ * ```typescript
+ * type MyQueryMap = {
+ *   GetOrder: Order | null;
+ *   ListOrders: Order[];
+ * };
+ *
+ * const bus = new QueryBus<MyQueryMap>();
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // result: Result<Order | null, string>  ← automatically inferred
+ * ```
+ */
+type QueryTypeMap = Record<string, unknown>;
 /**
  * Query Bus interface for dispatching queries to their handlers.
  * Provides a centralized way to execute queries with handler registration.
  *
+ * Supports an optional type map (`TMap`) for automatic return type inference.
+ * Without a type map, the return type must be specified manually or defaults to `unknown`.
+ *
+ * @template TMap - Optional mapping from query type strings to return types
+ *
  * @example
  * ```typescript
- * const bus = new QueryBus();
- * bus.register("GetOrder", getOrderHandler);
+ * // With type map (recommended) – return type is inferred
+ * type MyQueries = { GetOrder: Order | null; ListOrders: Order[] };
+ * const bus = new QueryBus<MyQueries>();
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // result: Result<Order | null, string>
  *
- * const order = await bus.execute({
- *   type: "GetOrder",
- *   orderId: "123"
- * });
+ * // Without type map – works like before
+ * const bus = new QueryBus();
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // result: Result<unknown, string>
  * ```
  */
-interface IQueryBus {
+interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
     /**
      * Executes a query by dispatching it to the registered handler.
-     * Returns a Result type instead of throwing an error.
+     * When a type map is provided, the return type is inferred from the query type.
      *
      * @param query - The query to execute
-     * @returns Result containing the query result if successful, or an error message if no handler is registered
+     * @returns Result containing the query result if successful, or an error message
      */
+    execute<Q extends Query & {
+        type: keyof TMap & string;
+    }>(query: Q): Promise<Result<TMap[Q["type"]], string>>;
     execute<Q extends Query, R>(query: Q): Promise<Result<R, string>>;
     /**
      * Executes a query by dispatching it to the registered handler.
@@ -1201,24 +1752,36 @@ interface IQueryBus {
      * @returns The query result
      * @throws Error if no handler is registered for the query type
      */
+    executeUnsafe<Q extends Query & {
+        type: keyof TMap & string;
+    }>(query: Q): Promise<TMap[Q["type"]]>;
     executeUnsafe<Q extends Query, R>(query: Q): Promise<R>;
     /**
      * Registers a handler for a specific query type.
      *
+     * When `TMap` is supplied, the `queryType` argument is restricted to its
+     * keys and the handler signature is forced to match `TMap[K]` for the
+     * return value — typos and wrong-typed handlers are compile errors.
+     * Without `TMap` the registration is loose (any string key, any return
+     * type) so the no-config path keeps working.
+     *
      * @param queryType - The query type to register the handler for
      * @param handler - The handler function for this query type
      */
-    register<Q extends Query, R>(queryType: Q["type"], handler: QueryHandler<Q, R>): void;
+    register<K extends keyof TMap & string, Q extends Query & {
+        type: K;
+    } = Query & {
+        type: K;
+    }>(queryType: K, handler: QueryHandler<Q, TMap[K]>): void;
 }
-/**
- * Type map for query types to their return types.
- * Used to improve type inference in QueryBus.
- */
-type QueryTypeMap = Record<string, unknown>;
 /**
  * Simple in-memory query bus implementation.
  * Handlers are stored in a Map and dispatched based on query type.
  *
+ * Supports an optional type map (`TMap`) for automatic return type inference.
+ * When `TMap` is provided, `execute()` and `executeUnsafe()` infer the result type from the query type.
+ * Without `TMap`, it works like before (return type defaults to `unknown` or can be specified manually).
+ *
  * **Note:** This is a basic implementation suitable for development and simple use cases.
  * For production environments, consider implementing or using a more feature-rich bus that includes:
  * - Middleware/Pipeline support (logging, caching, rate limiting)
@@ -1231,44 +1794,39 @@ type QueryTypeMap = Record<string, unknown>;
  * The `QueryHandler` type can still be used with external production-grade buses
  * (e.g., RabbitMQ, AWS SQS) while maintaining type safety.
  *
+ * @template TMap - Optional mapping from query type strings to return types
+ *
  * @example
  * ```typescript
- * const bus = new QueryBus();
- * bus.register("GetOrder", async (query) => {
- *   return await repository.getById(query.orderId);
- * });
+ * // With type map – full inference
+ * type Queries = { GetOrder: Order | null; ListOrders: Order[] };
+ * const bus = new QueryBus<Queries>();
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // result: Result<Order | null, string>
  *
- * const order = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // Without type map – same as before
+ * const bus = new QueryBus();
+ * bus.register("GetOrder", async (query) => repository.getById(query.orderId));
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
  * ```
  */
-declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQueryBus {
+declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQueryBus<TMap> {
     private readonly handlers;
-    register<Q extends Query, R>(queryType: Q["type"], handler: QueryHandler<Q, R>): void;
+    register<K extends keyof TMap & string, Q extends Query & {
+        type: K;
+    } = Query & {
+        type: K;
+    }>(queryType: K, handler: QueryHandler<Q, TMap[K]>): void;
     execute<Q extends Query & {
-        type: keyof TMap;
+        type: keyof TMap & string;
     }>(query: Q): Promise<Result<TMap[Q["type"]], string>>;
     execute<Q extends Query, R>(query: Q): Promise<Result<R, string>>;
+    executeUnsafe<Q extends Query & {
+        type: keyof TMap & string;
+    }>(query: Q): Promise<TMap[Q["type"]]>;
     executeUnsafe<Q extends Query, R>(query: Q): Promise<R>;
 }
 
-/**
- * Guard function that validates a condition and returns a Result.
- * Returns `ok(true)` if the condition is met, otherwise `err(error)`.
- *
- * @param cond - The condition to check
- * @param error - Error message if condition fails
- * @returns Result<true, string>
- *
- * @example
- * ```typescript
- * const result = guard(id.length > 0, "ID cannot be empty");
- * if (!result.ok) {
- *   return err(result.error);
- * }
- * ```
- */
-declare function guard(cond: boolean, error: string): Result<true, string>;
-
 /**
  * Simple in-memory event bus implementation.
  * Supports multiple subscribers per event type (pub/sub pattern).
@@ -1293,68 +1851,158 @@ declare function guard(cond: boolean, error: string): Result<true, string>;
  */
 declare class EventBusImpl<Evt extends DomainEvent<string, unknown>> implements EventBus<Evt> {
     private readonly handlers;
-    subscribe<T extends Evt>(eventType: string, handler: EventHandler<T>): () => void;
-    once<T extends Evt>(eventType: string): Promise<T>;
+    subscribe<K extends Evt["type"]>(eventType: K, handler: EventHandler<Extract<Evt, {
+        type: K;
+    }>>): () => void;
+    once<K extends Evt["type"]>(eventType: K, options?: OnceOptions): Promise<Extract<Evt, {
+        type: K;
+    }>>;
+    /**
+     * See {@link EventBus.publish} for the full ordering / parallelism /
+     * error-aggregation contract this implementation realises:
+     *  - events in input order, sequentially;
+     *  - handlers within one event in parallel via `Promise.allSettled`;
+     *  - errors collected and thrown after the batch (single Error, or
+     *    `AggregateError` for multiple failures).
+     */
     publish(events: ReadonlyArray<Evt>): Promise<void>;
 }
 
 /**
- * A Specification is a named, standalone object that represents a business rule for a query.
- * It is "translatable" into a concrete database query.
+ * Core repository contract for Aggregate Roots.
+ *
+ * In DDD a Repository is a "collection illusion" for aggregates: load by
+ * identity, save the whole aggregate, delete by identity. Querying by
+ * arbitrary criteria is a separate concern (CQRS read-side, ad-hoc bulk
+ * operations) and lives on the `IQueryableRepository` extension below — so
+ * write-side repositories don't have to implement query plumbing they
+ * don't need.
+ *
+ * Repositories work exclusively with Aggregate Root Entities. The Aggregate
+ * Root represents the aggregate externally and is the only object that can
+ * be loaded or saved through repositories. When loading, all child entities
+ * and value objects inside the aggregate are loaded too; when saving, the
+ * whole aggregate is persisted as a unit.
+ *
+ * @template TAgg - The aggregate root type (must implement IAggregateRoot)
+ * @template TId  - The type of the aggregate root identifier
  */
-interface ISpecification<T> {
-    readonly _type: T;
+interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>> {
+    /**
+     * Loads an aggregate by id. Returns `null` when not found.
+     */
+    getById(id: TId): Promise<TAgg | null>;
+    /**
+     * Loads an aggregate by id and throws `AggregateNotFoundError` when not
+     * found. Use this when "not found" is a programming/contract error in
+     * the calling Use Case; use `getById` when null is a valid outcome.
+     */
+    getByIdOrFail(id: TId): Promise<TAgg>;
+    /**
+     * Returns whether an aggregate with the given id exists. Cheaper than
+     * `getById !== null` if your storage supports `EXISTS`-style queries.
+     */
+    exists(id: TId): Promise<boolean>;
+    /**
+     * Persists the aggregate (insert or update). Implementations should:
+     *
+     *  1. Throw `ConcurrencyConflictError` from `@shirudo/ddd-kit` when the
+     *     aggregate's expected version does not match the version currently
+     *     stored (optimistic concurrency).
+     *  2. After a successful write, call `aggregate.markPersisted(newVersion)`
+     *     so the in-memory aggregate reflects the new version and clears its
+     *     pending/domain events.
+     *
+     * Return type stays `void` — the caller already holds the aggregate
+     * reference, which is now up to date.
+     */
+    save(aggregate: TAgg): Promise<void>;
+    /**
+     * Removes the aggregate by id.
+     */
+    delete(id: TId): Promise<void>;
 }
-
 /**
- * Repository interface for Aggregate Roots (Entities).
+ * Repository extension that adds filter-based querying. `TFilter` is the
+ * filter shape your persistence layer speaks: a Drizzle `SQL` expression, a
+ * Prisma `WhereInput`, a MongoDB filter document, a plain
+ * `(t: TAgg) => boolean` predicate for in-memory repos, or anything else.
  *
- * Repositories work exclusively with Aggregate Root Entities. The Aggregate Root
- * is the Entity that represents the aggregate externally and is the only object
- * that can be loaded/saved through repositories.
+ * The library does not prescribe a Specification or query DSL — the
+ * Repository implementation owns its query language. This avoids the
+ * phantom-interface trap of a library-level `ISpecification<T>` with no
+ * methods and lets each Repository expose the strongest possible types for
+ * its storage backend.
  *
- * When loading an Aggregate Root, all child entities and value objects within
- * the aggregate state are loaded as well. When saving, the entire aggregate
- * (including all child entities) is persisted as a unit.
+ * Aggregates that are only ever accessed by id should implement
+ * `IRepository` directly and skip this extension.
  *
- * Child entities cannot be loaded or saved independently - they exist only
- * within the aggregate boundary and are managed through the Aggregate Root.
+ * @template TAgg    - The aggregate root type
+ * @template TId     - The aggregate root identifier type
+ * @template TFilter - The filter shape understood by this repository
  *
- * @template TState - The type of the aggregate state (contains child entities and value objects)
- * @template TEvent - The union type of all domain events
- * @template TAgg - The aggregate root type (must be an Aggregate Root Entity)
- * @template TId - The type of the aggregate root identifier
+ * @example
+ * ```typescript
+ * // In-memory repo with a predicate filter
+ * type Predicate<T> = (t: T) => boolean;
+ * class InMemoryOrders implements IQueryableRepository<Order, OrderId, Predicate<Order>> {
+ *   // ...
+ *   async find(filter: Predicate<Order>): Promise<Order[]> { ... }
+ *   async findOne(filter: Predicate<Order>): Promise<Order | null> { ... }
+ * }
+ *
+ * // Drizzle repo with a SQL expression filter
+ * import type { SQL } from "drizzle-orm";
+ * class DrizzleOrders implements IQueryableRepository<Order, OrderId, SQL> {
+ *   // ...
+ * }
+ * ```
  */
-interface IRepository<TState, TEvent extends DomainEvent<string, unknown>, TAgg extends IAggregateRoot<TId> & Aggregate<TState, TEvent>, TId extends Id<string>> {
-    getById(id: TId): Promise<TAgg | null>;
-    findOne(spec: ISpecification<TAgg>): Promise<TAgg | null>;
-    find(spec: ISpecification<TAgg>): Promise<TAgg[]>;
-    save(aggregate: TAgg): Promise<void>;
-    delete(id: TId): Promise<void>;
+interface IQueryableRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>, TFilter> extends IRepository<TAgg, TId> {
+    /**
+     * Returns the first aggregate matching the filter, or `null` if none.
+     */
+    findOne(filter: TFilter): Promise<TAgg | null>;
+    /**
+     * Returns **every** aggregate matching the filter — no pagination,
+     * no cursor. For unbounded result sets, prefer a read-side projection
+     * (CQRS read model) over loading aggregates in bulk; aggregates are
+     * write-side objects and rehydrating thousands of them by id is rarely
+     * what you want. If you need pagination on the write side, declare a
+     * domain-specific paged method on your concrete repository (e.g.
+     * `findPage(filter, cursor)`) — the library does not prescribe a
+     * pagination contract because cursor/offset/keyset semantics vary too
+     * much across storage backends.
+     */
+    find(filter: TFilter): Promise<TAgg[]>;
 }
 
 type VO<T> = Readonly<T>;
 /**
- * Deep freezes an object and all its nested properties recursively.
- * This ensures true immutability for value objects with nested structures.
- * Handles circular references by tracking visited objects.
+ * Deep freezes an object and all its nested properties recursively, then
+ * returns it. Iterates both string-keyed and symbol-keyed own properties
+ * so the freeze symmetry matches `deepEqual` (which also considers symbol
+ * keys). Handles circular references by tracking visited objects.
+ *
+ * Note: `deepFreeze` mutates its argument in place — it sets `[[Frozen]]`
+ * on the object you pass in. Callers that need to avoid touching the
+ * input (e.g. `vo()`) should deep-clone first.
  */
 declare function deepFreeze<T>(obj: T, visited?: WeakSet<object>): Readonly<T>;
 /**
  * Creates a deeply immutable value object from the given data.
- * All nested objects and arrays are frozen recursively.
  *
- * @param t - The data to convert into a value object
- * @returns A deeply frozen, immutable value object
+ * The input is first deep-cloned with `structuredClone`, then the clone
+ * is frozen — so calling `vo(input)` never freezes the caller's own
+ * object graph as a side-effect. Mutating the input afterwards does not
+ * bleed into the VO.
  *
  * @example
  * ```typescript
- * const address = vo({
- *   street: "Main St",
- *   city: "Berlin",
- *   coordinates: { lat: 52.5, lng: 13.4 }
- * });
- * // address.coordinates.lat = 99; // ❌ Error: Cannot assign to read-only property
+ * const nested = { lat: 52.5, lng: 13.4 };
+ * const address = vo({ street: "Main St", coordinates: nested });
+ * address.coordinates.lat = 99; // ❌ Cannot assign to read-only property
+ * nested.lat = 0;               // ✅ caller's input still mutable
  * ```
  */
 declare function vo<T>(t: T): VO<T>;
@@ -1453,26 +2101,6 @@ declare function voEqualsExcept<T>(a: VO<T>, b: VO<T>, options: DeepEqualExceptO
  * ```
  */
 declare function voWithValidation<T>(t: T, validate: (value: T) => boolean, errorMessage?: string): Result<VO<T>, string>;
-/**
- * Creates a value object with optional validation.
- * Throws an error if validation fails.
- *
- * @param t - The data to convert into a value object
- * @param validate - Validation function that returns true if valid
- * @param errorMessage - Optional custom error message if validation fails
- * @returns A deeply frozen, immutable value object
- * @throws Error if validation fails
- *
- * @example
- * ```typescript
- * const money = voWithValidationUnsafe(
- *   { amount: 100, currency: "USD" },
- *   (m) => m.amount >= 0 && m.currency.length === 3,
- *   "Invalid money: amount must be non-negative and currency must be 3 characters"
- * );
- * ```
- */
-declare function voWithValidationUnsafe<T>(t: T, validate: (value: T) => boolean, errorMessage?: string): VO<T>;
 /**
  * Interface for Value Objects.
  * Value Objects are immutable and defined by their properties.
@@ -1564,4 +2192,4 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
     toJSON(): Readonly<T>;
 }
 
-export { type Aggregate, type AggregateConfig, AggregateEventSourced, type AggregateEventSourcedConfig, AggregateRoot, type AggregateSnapshot, type Clock, type Command, CommandBus, type CommandHandler, type DomainEvent, Entity, type EventBus, EventBusImpl, type EventHandler, type EventMetadata, type IAggregateEventSourced, type IAggregateRoot, type ICommandBus, type IEntity, type IQueryBus, type IRepository, type ISpecification, type IValueObject, type Id, type IdGenerator, type Identifiable, type Outbox, type Query, QueryBus, type QueryHandler, type RepoProvider, type UnitOfWork, type VO, ValueObject, type Version, aggregate, bump, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepFreeze, entityIds, findEntityById, guard, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, sameAggregate, sameEntity, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, voWithValidationUnsafe, withCommit, withEvent };
+export { type AggregateConfig, AggregateNotFoundError, AggregateRoot, type AggregateSnapshot, type ClockFactory, type Command, CommandBus, type CommandHandler, ConcurrencyConflictError, type CreateDomainEventOptions, DeepEqualExceptOptions, DomainError, type DomainEvent, Entity, type EventBus, EventBusImpl, type EventHandler, type EventIdFactory, type EventMetadata, EventSourcedAggregate, type EventSourcedAggregateConfig, type IAggregateRoot, type ICommandBus, type IEntity, type IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IValueObject, type Id, type IdGenerator, type Identifiable, MissingHandlerError, type OnceOptions, type Outbox, type OutboxRecord, type Query, QueryBus, type QueryHandler, type TransactionScope, type VO, ValueObject, type Version, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, withCommit };