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

package/dist/index.d.ts

@@ -1,13 +1,113 @@
-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>;
 }
 
+/**
+ * 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 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.
@@ -45,13 +145,31 @@ interface EventMetadata {
  * @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;
     /**
-     * The event payload containing the domain data.
-     * Omitted when P is void (events without payload).
+     * 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;
     /**
@@ -70,6 +188,37 @@ interface DomainEvent<T extends string, P = void> {
      */
     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.
@@ -84,16 +233,8 @@ interface DomainEvent<T extends string, P = void> {
  * 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>;
+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.
@@ -107,10 +248,7 @@ declare function createDomainEvent<T extends string, P>(type: T, payload: P, opt
  * );
  * ```
  */
-declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: {
-    occurredAt?: Date;
-    version?: number;
-}): DomainEvent<T, P>;
+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.
@@ -141,10 +279,72 @@ declare function copyMetadata(sourceEvent: DomainEvent<string, unknown>, additio
 declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
 
 /**
- * Functional definition of an Entity via its capability.
- * An object is identifiable if it has an id.
+ * 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
+ * }
+ * ```
  */
-type Identifiable<TId> = {
+
+/**
+ * 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;
 };
 /**
@@ -204,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;
     /**
@@ -214,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;
     /**
@@ -231,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.
@@ -248,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.
@@ -268,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.
  *
@@ -286,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.
@@ -306,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.
@@ -330,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.
@@ -354,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.
  *
@@ -372,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.
@@ -412,14 +645,36 @@ 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;
 }
@@ -461,7 +716,7 @@ interface AggregateConfig {
  * }
  * ```
  */
-declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = unknown> extends Entity<TState, TId> implements IAggregateRoot<TId> {
+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;
@@ -478,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.
      *
-     * @param event - The domain event to add
+     * **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.
+     *
+     * `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;
     /**
@@ -534,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.
@@ -547,11 +930,13 @@ interface IEventSourcedAggregate<TId extends Id<string>, TEvent extends DomainEv
      */
     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.
      */
@@ -575,8 +960,18 @@ type Handler<TState, TEvent> = (state: TState, event: TEvent) => TState;
  */
 interface EventSourcedAggregateConfig {
     /**
-     * Whether to automatically bump the version when applying new events.
-     * Defaults to true. Set to false to manually control versioning.
+     * 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;
 }
@@ -591,17 +986,35 @@ interface EventSourcedAggregateConfig {
  * `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.
  *
+ * `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
+ * 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", {}));
  *   }
  *
+ *   protected validateEvent(event: OrderEvent): void {
+ *     if (event.type === "OrderConfirmed" && this.state.status === "confirmed") {
+ *       throw new OrderAlreadyConfirmedError(this.id);
+ *     }
+ *   }
+ *
  *   protected readonly handlers = {
  *     OrderConfirmed: (state: OrderState): OrderState => ({
  *       ...state,
@@ -619,36 +1032,66 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<
     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.
-     * Override this method to add custom validation logic.
-     * Return `ok(true)` if the event is valid, `err(message)` otherwise.
+     * 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): Result<true, string>;
+    protected validateEvent(_event: TEvent): void;
     /**
-     * Applies an event to change the state and adds it to pending events.
-     * Returns a Result type instead of throwing an error.
+     * 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 from history replay
+     * @param isNew - Whether the event is new (needs persisting) or replayed from history
      */
-    protected apply(event: TEvent, isNew?: boolean): Result<void, string>;
+    protected apply<K extends TEvent["type"]>(event: Extract<TEvent, {
+        type: K;
+    }>, isNew?: boolean): void;
     /**
-     * Applies an event to change the state and adds it to pending events.
-     * Throws an error if validation fails or handler is missing.
+     * 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.
      */
-    protected applyUnsafe(event: TEvent, isNew?: boolean): void;
+    private dispatchAndCommit;
     /**
      * 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.
+     * 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, string>;
+    loadFromHistory(history: TEvent[]): Result<void, DomainError>;
     hasPendingEvents(): boolean;
     getEventCount(): number;
     getLatestEvent(): TEvent | undefined;
@@ -657,9 +1100,16 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<
      */
     createSnapshot(): AggregateSnapshot<TState>;
     /**
-     * Restores the aggregate from a snapshot and applies events that occurred after.
+     * 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, string>;
+    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: TEvent[]): Result<void, DomainError>;
     /**
      * A map of event types to their corresponding handlers.
      * Subclasses MUST implement this property.
@@ -674,33 +1124,6 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<
 type Version = number & {
     readonly __v: true;
 };
-/**
- * Lightweight functional aggregate state — state + version, no event sourcing.
- * This is a data projection, not a full Aggregate (which requires identity via IAggregateRoot).
- *
- * For event sourcing, use the class-based `EventSourcedAggregate` which enforces
- * that state changes happen through event handlers.
- *
- * @template State - The type of the aggregate state
- */
-interface AggregateState<State> {
-    state: Readonly<State>;
-    version: Version;
-}
-/**
- * Creates a lightweight functional aggregate state.
- *
- * @example
- * ```typescript
- * const order = aggregate<OrderState>({ status: "draft", items: [] });
- * ```
- */
-declare function aggregate<State>(state: State, version?: Version): AggregateState<State>;
-/**
- * Bumps the version of a functional aggregate state.
- * Returns a new aggregate state with incremented version.
- */
-declare function bump<S>(agg: AggregateState<S>): AggregateState<S>;
 /**
  * Snapshot of an aggregate state at a specific point in time.
  * Used for optimizing event replay by starting from a snapshot
@@ -892,10 +1315,20 @@ interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
     /**
      * 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.
@@ -935,7 +1368,11 @@ interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
  */
 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>>;
@@ -976,7 +1413,28 @@ interface EventBus<Evt extends {
 }> {
     /**
      * 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
      */
@@ -999,7 +1457,9 @@ interface EventBus<Evt extends {
      * unsubscribe();
      * ```
      */
-    subscribe: <T extends Evt>(eventType: Evt["type"], 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.
@@ -1014,24 +1474,125 @@ interface EventBus<Evt extends {
      * console.log("Order created:", event.payload.orderId);
      * ```
      */
-    once: <T extends Evt>(eventType: Evt["type"]) => 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>;
+    /**
+     * 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
@@ -1040,10 +1601,7 @@ 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 };
  *   }
  * );
  * ```
@@ -1053,7 +1611,7 @@ declare function withCommit<Evt extends {
 }, R>(deps: {
     outbox: Outbox<Evt>;
     bus?: EventBus<Evt>;
-    uow: UnitOfWork;
+    scope: TransactionScope;
 }, fn: () => Promise<{
     result: R;
     events: ReadonlyArray<Evt>;
@@ -1201,10 +1759,20 @@ interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
     /**
      * 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;
 }
 /**
  * Simple in-memory query bus implementation.
@@ -1244,7 +1812,11 @@ interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
  */
 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 & string;
     }>(query: Q): Promise<Result<TMap[Q["type"]], string>>;
@@ -1255,24 +1827,6 @@ declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQue
     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).
@@ -1297,70 +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: Evt["type"], handler: EventHandler<T>): () => void;
-    once<T extends Evt>(eventType: Evt["type"]): 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>;
 }
 
-declare const __specBrand: unique symbol;
-/**
- * A Specification is a named, standalone object that represents a business rule for a query.
- * It is "translatable" into a concrete database query.
- *
- * Uses a branded type to carry the generic parameter without requiring
- * implementors to add a runtime field.
- */
-interface ISpecification<T> {
-    readonly [__specBrand]?: T;
-}
-
 /**
- * Repository interface for Aggregate Roots (Entities).
- *
- * 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.
+ * Core repository contract for Aggregate Roots.
  *
- * 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.
+ * 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.
  *
- * Child entities cannot be loaded or saved independently - they exist only
- * within the aggregate boundary and are managed through the Aggregate Root.
+ * 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
+ * @template TId  - The type of the aggregate root identifier
  */
 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>;
-    findOne(spec: ISpecification<TAgg>): Promise<TAgg | null>;
-    find(spec: ISpecification<TAgg>): Promise<TAgg[]>;
+    /**
+     * 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 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.
+ *
+ * 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.
+ *
+ * Aggregates that are only ever accessed by id should implement
+ * `IRepository` directly and skip this extension.
+ *
+ * @template TAgg    - The aggregate root type
+ * @template TId     - The aggregate root identifier type
+ * @template TFilter - The filter shape understood by this repository
+ *
+ * @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 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>;
@@ -1459,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.
@@ -1570,4 +2192,4 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
     toJSON(): Readonly<T>;
 }
 
-export { type AggregateConfig, AggregateRoot, type AggregateSnapshot, type AggregateState, type Command, CommandBus, type CommandHandler, type DomainEvent, Entity, type EventBus, EventBusImpl, type EventHandler, type EventMetadata, EventSourcedAggregate, type EventSourcedAggregateConfig, type IAggregateRoot, type ICommandBus, type IEntity, type IEventSourcedAggregate, 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, sameEntity, sameVersion, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, voWithValidationUnsafe, withCommit };
+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 };