@shirudo/ddd-kit 1.3.0 → 2.2.0

package/dist/index.d.ts

@@ -1,10 +1,76 @@
-import { a as Id, A as AnyDomainEvent, I as IAggregateRoot, V as Version, b as AggregateSnapshot, C as CreateDomainEventOptions, c as IEventSourcedAggregate, D as DomainError, d as InfrastructureError } from './aggregate-BGdgvqKh.js';
-export { q as AggregateDeletedError, t as AggregateNotFoundError, f as ClockFactory, v as ConcurrencyConflictError, k as DomainEvent, u as DuplicateAggregateError, p as EventHarvestError, E as EventIdFactory, j as EventMetadata, x as IdGenerator, M as MissingHandlerError, U as UnenrolledChangesError, n as copyMetadata, l as createDomainEvent, m as createDomainEventWithMetadata, o as mergeMetadata, i as resetClockFactory, r as resetEventIdFactory, s as sameVersion, g as setClockFactory, e as setEventIdFactory, h as withClockFactory, w as withEventIdFactory } from './aggregate-BGdgvqKh.js';
+import { a as Id, A as AnyDomainEvent, I as IAggregateRoot, V as Version, b as AggregateSnapshot, C as CreateDomainEventOptions, c as IEventSourcedAggregate, D as DomainError, d as InfrastructureError } from './aggregate-DFi6HlEh.js';
+export { j as AggregateDeletedError, k as AggregateNotFoundError, l as AggregateNotFoundErrorOptions, n as ConcurrencyConflictError, o as ConcurrencyConflictErrorOptions, g as DomainEvent, p as DuplicateAggregateError, q as DuplicateAggregateErrorOptions, t as EventHarvestError, E as EventIdFactory, h as EventMetadata, z as IdGenerator, M as MissingHandlerError, S as SnapshotSchemaMismatchError, u as SnapshotSchemaMismatchErrorOptions, U as UnenrolledChangesError, v as UnregisteredHandlerError, x as UnregisteredHandlerErrorOptions, y as UnreplayableAggregateError, e as copyMetadata, f as createDomainEvent, m as mergeMetadata, r as resetEventIdFactory, s as sameVersion, i as setEventIdFactory, w as withEventIdFactory } from './aggregate-DFi6HlEh.js';
 import { Result } from '@shirudo/result';
 import { BaseError, ValidationError } from '@shirudo/base-error';
 import { DeepEqualExceptOptions } from './utils.js';
 export { DeepOmitOptions, Key, PathSegment, deepEqual, deepEqualExcept, deepOmit } from './utils.js';
 
+/**
+ * Module-internal home of the kit's swappable clock. The public surface
+ * (`ClockFactory`, `setClockFactory`, `withClockFactory`,
+ * `resetClockFactory`) is re-exported through `domain-event.ts`; the
+ * `now()` accessor stays internal so the barrel files never ship it.
+ * Living in its own module lets `createDomainEvent` (occurredAt) and
+ * `BaseAggregate.createSnapshot` (snapshotAt) read the same clock
+ * without an import cycle between those files.
+ */
+/**
+ * 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` / `snapshotAt` must be reproducible.
+ */
+type ClockFactory = () => Date;
+/**
+ * Replaces the global clock factory used by `createDomainEvent` and
+ * `createSnapshot`. 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`.
+ *
+ * Module-scoped: see `setEventIdFactory` for the global-state
+ * caveats. For test isolation prefer {@link withClockFactory}; for
+ * multi-tenant request isolation prefer the per-call
+ * `options.occurredAt`.
+ */
+declare function setClockFactory(factory: ClockFactory): void;
+/**
+ * Scoped variant of {@link setClockFactory}: installs `factory`, runs
+ * `fn`, then restores the previous factory in a `finally` block.
+ * Synchronous-only, with the same constraints (and same runtime thenable
+ * guard) as `withEventIdFactory`.
+ *
+ * **When to prefer the per-call `options.occurredAt` instead.** Same
+ * trade-off as `withEventIdFactory`: passing `{ occurredAt }`
+ * to `createDomainEvent` is the strongest isolation for single-event
+ * cases. The scoped helper is for events constructed deep inside
+ * domain methods where threading an explicit timestamp is awkward.
+ *
+ * @example
+ * ```ts
+ * it("stamps events with a fixed clock", () => {
+ *   const fixed = new Date("2026-01-01T00:00:00Z");
+ *   withClockFactory(() => fixed, () => {
+ *     const e = createDomainEvent("X", { v: 1 });
+ *     expect(e.occurredAt).toEqual(fixed);
+ *   });
+ * });
+ * ```
+ */
+declare function withClockFactory<T>(factory: ClockFactory, fn: () => T): T;
+/**
+ * Restores the default clock factory (`() => new Date()`).
+ * Intended for use in test `afterEach` hooks.
+ */
+declare function resetClockFactory(): void;
+
 /**
  * Entity utilities and interfaces for Domain-Driven Design.
  *
@@ -18,32 +84,34 @@ export { DeepOmitOptions, Key, PathSegment, deepEqual, deepEqualExcept, deepOmit
  *
  * 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
+ *    - Can extend `Entity<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
+ * - `Entity<TState, TId>` - Base class for entities with state
+ * - `EntityConfig` - Construction options (opt-in deep freeze)
  * - `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> {
+ * class OrderItem extends Entity<OrderItemState, ItemId> {
  *   constructor(id: ItemId, initialState: OrderItemState) {
  *     super(id, initialState);
  *   }
  *
  *   updateQuantity(quantity: number): void {
- *     this._state = { ...this._state, quantity };
+ *     // setState runs validateState and re-freezes; a direct
+ *     // `this._state = ...` assignment would skip both.
+ *     this.setState({ ...this.state, quantity });
  *   }
  *
  *   calculateSubtotal(): number {
- *     return this._state.price * this._state.quantity;
+ *     return this.state.price * this.state.quantity;
  *   }
  * }
  *
@@ -62,6 +130,31 @@ export { DeepOmitOptions, Key, PathSegment, deepEqual, deepEqualExcept, deepOmit
  * ```
  */
 
+/**
+ * Construction options shared by `Entity` and (via `AggregateConfig`) the
+ * aggregate base classes.
+ */
+interface EntityConfig {
+    /**
+     * Opt-in: freeze the WHOLE state graph (via `deepFreeze`) instead of
+     * the default shallow freeze, so nested outside writes
+     * (`entity.state.items.push(x)`) throw instead of silently bypassing
+     * `validateState`, the version bump, and the `changedKeys` dirty diff.
+     *
+     * Defaults to `false` (the documented shallow contract): deep freezing
+     * costs a full state-graph walk on every state write, which is why it
+     * is not the default on hot paths.
+     *
+     * **Only for plain-data states.** The deep freeze walks the entire
+     * graph: a class-based child entity inside the state would be frozen
+     * too, and its own mutation methods would start throwing. States
+     * carrying class-based children must keep the default shallow freeze.
+     * Note that the ownership transfer widens accordingly: nested objects
+     * passed into the constructor or `setState` are frozen IN PLACE (the
+     * shallow copy protects only the top-level input object).
+     */
+    deepFreezeState?: boolean;
+}
 /**
  * Functional definition of an Entity via its capability: an object is
  * identifiable if it has an `id`.
@@ -122,7 +215,9 @@ interface IEntity<TId extends Id<string>, TState> extends Identifiable<TId> {
  *   }
  *
  *   updateQuantity(quantity: number): void {
- *     this._state = { ...this._state, quantity };
+ *     // setState runs validateState and re-freezes; a direct
+ *     // `this._state = ...` assignment would skip both.
+ *     this.setState({ ...this.state, quantity });
  *   }
  * }
  * ```
@@ -132,30 +227,46 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
     /**
      * Returns the current state of the entity.
      *
-     * 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`).
+     * By default 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 enable the opt-in
+     * {@link EntityConfig.deepFreezeState} (plain-data states only), model
+     * nested data with `vo()` (which freezes deeply), or reach for a
+     * structural-sharing library like Immer at the App layer. The shallow
+     * default 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;
     /**
      * The state is 'protected' so that only the subclass can modify it.
-     * Subclasses can mutate this directly or use helper methods.
+     * Subclasses can mutate this directly or use helper methods; direct
+     * assignments should freeze through {@link freezeState} so the
+     * configured freeze mode is honored.
      */
     protected _state: TState;
+    private readonly _deepFreezeState;
     /**
      * **State ownership.** Plain-object and array states are shallow-copied
      * before the freeze, so the caller's own object stays mutable. A CLASS
      * INSTANCE passed as state is an ownership transfer: it is frozen
      * in place (a copy would strip its prototype). Do not keep mutating
      * the instance after handing it to the entity. The same contract
-     * applies to {@link setState}.
+     * applies to {@link setState}. With
+     * {@link EntityConfig.deepFreezeState} enabled, the ownership transfer
+     * widens to the whole graph: NESTED objects are frozen in place too.
+     */
+    protected constructor(id: TId, initialState: TState, config?: EntityConfig);
+    /**
+     * Freezes a state value according to this entity's configured freeze
+     * mode: the default shallow freeze, or `deepFreeze` when
+     * {@link EntityConfig.deepFreezeState} was enabled at construction.
+     * Subclass code that assigns `this._state` directly (bypassing
+     * `setState`) must freeze through this method, not `freezeShallow`,
+     * or the opt-in silently degrades to shallow for that path.
      */
-    protected constructor(id: TId, initialState: TState);
+    protected freezeState(value: TState): TState;
     /**
      * Optional validation hook to ensure state invariants. Called during
      * construction (from `Entity`'s constructor) and again on every
@@ -194,13 +305,15 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
 /**
  * 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.
+ * primitives. Used internally by `Entity` (via `freezeState`, which picks
+ * shallow or deep per the `deepFreezeState` config) to prevent outside
+ * mutation of state read through the `state` getter without paying the
+ * cost of a deep clone on every read.
+ *
+ * Subclass code that assigns `this._state` directly should freeze through
+ * the protected `freezeState(value)` method rather than calling this
+ * helper, so the configured freeze mode is honored. The export remains
+ * for consumers using it as a standalone utility.
  */
 declare function freezeShallow<T>(value: T): T;
 /**
@@ -536,8 +649,46 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      *
      * The state is converted via {@link toSnapshotState}; the default
      * requires plain, serialisable data and fails fast otherwise.
+     *
+     * `snapshotAt` is read from the kit's swappable clock, the same one
+     * `createDomainEvent` stamps `occurredAt` from, so
+     * `setClockFactory` / `withClockFactory` pin snapshot timestamps in
+     * deterministic tests too. `schemaVersion` is stamped from
+     * {@link snapshotSchemaVersion} so a later restore can detect
+     * snapshots written against an older `TSnapshotState` shape.
      */
     createSnapshot(): AggregateSnapshot<TSnapshotState>;
+    /**
+     * Schema version of the shape {@link toSnapshotState} produces.
+     * Defaults to `1`. Bump it whenever `TSnapshotState` changes
+     * incompatibly (renamed or removed fields, changed representations):
+     * `createSnapshot` stamps it onto every snapshot, and the restore
+     * paths compare it, so an outdated stored snapshot surfaces as a
+     * `SnapshotSchemaMismatchError` at restore time (or is upgraded via
+     * {@link migrateSnapshotState}) instead of crashing on the first
+     * method call much later.
+     */
+    protected readonly snapshotSchemaVersion: number;
+    /**
+     * Resolves a stored snapshot's state against the aggregate's current
+     * snapshot schema: pass-through when the versions match (a missing
+     * `schemaVersion` counts as `1`, the pre-versioning era), otherwise
+     * routed through {@link migrateSnapshotState}. Called by both restore
+     * paths BEFORE anything is assigned, so a rejected snapshot leaves
+     * the aggregate untouched.
+     */
+    protected resolveSnapshotState(snapshot: AggregateSnapshot<TSnapshotState>): TSnapshotState;
+    /**
+     * Upgrade hook for snapshots written against an older
+     * `TSnapshotState` shape. Receives the stored state as `unknown`
+     * (its shape is, by definition, not the current `TSnapshotState`)
+     * plus the schema version it was written with, and returns the
+     * current shape. The default rejects with
+     * `SnapshotSchemaMismatchError`: discard-and-refold from the full
+     * event stream is the safe default strategy; override this only when
+     * upgrading in place is cheaper than refolding.
+     */
+    protected migrateSnapshotState(_stored: unknown, storedSchemaVersion: number): TSnapshotState;
     /**
      * Converts live aggregate state into the plain-data shape stored in a
      * snapshot. The default validates that the state graph is plain,
@@ -600,18 +751,33 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
 }
 
 /**
- * Configuration options for AggregateRoot behavior.
+ * Configuration options for AggregateRoot behavior. Inherits
+ * `deepFreezeState` from {@link EntityConfig} (opt-in deep freeze for
+ * plain-data states).
  */
-interface AggregateConfig {
+interface AggregateConfig extends EntityConfig {
     /**
      * Whether `setState()` should bump the version automatically when the
      * caller omits the per-call `bumpVersion` argument.
      *
      * Defaults to **`false`**: `setState()` already takes an explicit
      * `bumpVersion` argument per call, so the config is just the default
-     * the per-call argument falls back to. Set to `true` only if you have
-     * a subclass that never passes `bumpVersion` and you want every state
-     * change to advance the version anyway.
+     * the per-call argument falls back to.
+     *
+     * **OCC warning: an un-bumped mutation can be silently overwritten.**
+     * A save whose version did not move writes `WHERE version = v SET
+     * version = v`; a concurrent writer that loaded the same `v` then
+     * commits `WHERE version = v` successfully and replaces the state
+     * without any `ConcurrencyConflictError`. Skip the bump only for data
+     * whose loss under a concurrent write is acceptable (cosmetic caches,
+     * denormalized display fields), never for domain state.
+     *
+     * **Deprecation notice.** Relying on the implicit default (calling
+     * `setState(newState)` without a per-call `bumpVersion` and without
+     * setting this config) is deprecated. v3 makes the per-call argument
+     * required, so every mutation states its OCC intent explicitly at the
+     * call site; code that already passes `bumpVersion` or uses `commit()`
+     * is unaffected.
      */
     autoVersionBump?: boolean;
 }
@@ -810,6 +976,14 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      * Sets the state and optionally bumps the version automatically.
      * Validates `newState` via `validateState()`.
      *
+     * **State the OCC intent explicitly.** With neither the per-call
+     * `bumpVersion` argument nor an `autoVersionBump` config, the version
+     * does not move, and an un-bumped mutation can be silently overwritten
+     * by a concurrent writer (see the {@link AggregateConfig.autoVersionBump}
+     * warning for the mechanics). Prefer `commit()` for domain mutations,
+     * or pass `bumpVersion` explicitly; relying on the implicit default is
+     * deprecated and v3 makes the argument required.
+     *
      * @param newState - The new state
      * @param bumpVersion - Whether to bump the version (defaults to autoVersionBump config)
      */
@@ -927,9 +1101,21 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
      * which never bumps it; only the final `markRestored` advances it.)
      *
      * 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.
+     * `history.length`. A fresh aggregate (v=0) loading 3 events ends at
+     * v=3; a PERSISTED aggregate at v=P (`persistedVersion === P`) catching
+     * up on M newer events ends at v=P+M.
+     *
+     * **The replay target must be fresh or persisted.** An aggregate with
+     * unflushed `pendingEvents`, or with an in-memory version that was
+     * never persisted (a factory-created instance), throws
+     * {@link UnreplayableAggregateError} BEFORE anything moves: replaying
+     * onto it would `markRestored` a `persistedVersion` that counts
+     * unpersisted history, flipping repository routing from INSERT to
+     * UPDATE (or appending with a wrong expected version). The throw is
+     * deliberate (crash-loud programming bug), never a `Result` `Err`, and
+     * runs before the empty-history fast path so the misuse is caught
+     * deterministically rather than only when the stream happens to be
+     * non-empty.
      */
     loadFromHistory(history: ReadonlyArray<TEvent>): Result<void, DomainError>;
     /**
@@ -941,8 +1127,26 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
      * 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.
+     *
+     * **The restore target must not carry pending events.** Events recorded
+     * before the restore are unrelated to the restored stream; harvesting
+     * them after `markRestored` would emit them with a version baseline
+     * they were never part of. Such a target throws
+     * {@link UnreplayableAggregateError} before anything moves (crash-loud
+     * programming bug, never a `Result` `Err`). Unlike `loadFromHistory`,
+     * a never-persisted in-memory version is fine here: the snapshot
+     * overwrites state and version entirely instead of adding to them.
      */
     restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TSnapshotState>, eventsAfterSnapshot: ReadonlyArray<TEvent>): Result<void, DomainError>;
+    /**
+     * Replay-target freshness guard shared by `loadFromHistory` and
+     * `restoreFromSnapshotWithEvents`. See {@link UnreplayableAggregateError}
+     * for the desync both conditions prevent. `checkUnpersistedVersion` is
+     * `true` for the additive `loadFromHistory` path only: the snapshot
+     * restore overwrites version wholesale, so a never-persisted in-memory
+     * version is harmless there.
+     */
+    private assertReplayTargetFresh;
     /**
      * A map of event types to their corresponding handlers.
      * Subclasses MUST implement this property.
@@ -1006,6 +1210,8 @@ interface Command {
  *
  * @template C - The command type (must extend Command)
  * @template R - The result type
+ * @template E - The error channel type. Defaults to `string`; widen it (e.g.
+ *   to a `DomainError` union) to carry typed failures through the bus.
  *
  * @example
  * ```typescript
@@ -1040,7 +1246,7 @@ interface Command {
  * });
  * ```
  */
-type CommandHandler<C extends Command, R> = (cmd: C) => Promise<Result<R, string>>;
+type CommandHandler<C extends Command, R, E = string> = (cmd: C) => Promise<Result<R, E>>;
 
 /**
  * Type map for command types to their return types.
@@ -1059,6 +1265,30 @@ type CommandHandler<C extends Command, R> = (cmd: C) => Promise<Result<R, string
  * ```
  */
 type CommandTypeMap = Record<string, unknown>;
+/**
+ * Construction options for {@link CommandBus}.
+ *
+ * @template E - The error channel type of the bus.
+ */
+interface CommandBusOptions<E = string> {
+    /**
+     * Maps a thrown value (a handler that throws, or dispatch to an
+     * unregistered command type) into the bus's error channel `E`. Defaults to
+     * {@link describeThrown}, which renders any thrown value as a `string`.
+     * base-error's `toStructuredError` fits this slot directly when `E` is a
+     * `StructuredError`.
+     */
+    errorMapper?: (thrown: unknown) => E;
+}
+/**
+ * Constructor arguments for {@link CommandBus}. When `E` is the default
+ * `string`, options are optional (the built-in {@link describeThrown} mapper
+ * applies). When `E` is widened, an `errorMapper` is required, so a typed
+ * channel can never silently fall back to string values.
+ */
+type CommandBusArgs<E> = [E] extends [string] ? [options?: CommandBusOptions<E>] : [options: CommandBusOptions<E> & {
+    errorMapper: (thrown: unknown) => E;
+}];
 /**
  * Command Bus interface for dispatching commands to their handlers.
  * Provides a centralized way to execute commands with handler registration.
@@ -1083,18 +1313,18 @@ type CommandTypeMap = Record<string, unknown>;
  * // result: Result<unknown, string>
  * ```
  */
-interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
+interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap, E = string> {
     /**
      * 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
+     * @returns Result containing the success value or an error of type `E`
      */
     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>>;
+    }>(command: C): Promise<Result<TMap[C["type"]], E>>;
+    execute<C extends Command, R>(command: C): Promise<Result<R, E>>;
     /**
      * Registers a handler for a specific command type.
      *
@@ -1111,7 +1341,7 @@ interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
         type: K;
     } = Command & {
         type: K;
-    }>(commandType: K, handler: CommandHandler<C, TMap[K]>): void;
+    }>(commandType: K, handler: CommandHandler<C, TMap[K], E>): void;
 }
 /**
  * Simple in-memory command bus implementation.
@@ -1149,17 +1379,19 @@ interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
  * const result = await bus.execute({ type: "CreateOrder", ... });
  * ```
  */
-declare class CommandBus<TMap extends CommandTypeMap = CommandTypeMap> implements ICommandBus<TMap> {
+declare class CommandBus<TMap extends CommandTypeMap = CommandTypeMap, E = string> implements ICommandBus<TMap, E> {
     private readonly handlers;
+    private readonly errorMapper;
+    constructor(...args: CommandBusArgs<E>);
     register<K extends keyof TMap & string, C extends Command & {
         type: K;
     } = Command & {
         type: K;
-    }>(commandType: K, handler: CommandHandler<C, TMap[K]>): void;
+    }>(commandType: K, handler: CommandHandler<C, TMap[K], E>): 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>>;
+    }>(command: C): Promise<Result<TMap[C["type"]], E>>;
+    execute<C extends Command, R>(command: C): Promise<Result<R, E>>;
 }
 
 /**
@@ -1287,6 +1519,21 @@ interface OnceOptions {
 interface OutboxRecord<Evt extends AnyDomainEvent> {
     dispatchId: string;
     event: Evt;
+    /**
+     * Failed delivery attempts so far. Populated by implementations that
+     * track dispatch failures (see {@link DispatchTrackingOutbox});
+     * plain `Outbox` implementations may omit it.
+     */
+    attempts?: number;
+}
+/** A record that exhausted its delivery attempts; see {@link DispatchTrackingOutbox.deadLetters}. */
+interface DeadLetterRecord<Evt extends AnyDomainEvent> {
+    dispatchId: string;
+    event: Evt;
+    /** Failed delivery attempts when the record was dead-lettered. */
+    attempts: number;
+    /** Human-readable rendering of the last delivery error, if recorded. */
+    lastError?: string;
 }
 /**
  * Transactional outbox port: the bridge between the write-side
@@ -1319,8 +1566,15 @@ interface Outbox<Evt extends AnyDomainEvent> {
     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.
+     * dispatched, **in the order `add()` persisted them** (commit order).
+     * The ordering is part of the port contract: `withCommit` promises
+     * subscribers per-aggregate causal order, and a sequential dispatcher
+     * can only honor that promise when this read is ordered. SQL-backed
+     * implementations need a monotonic position column (an auto-increment
+     * primary key works) and an `ORDER BY` on it; a bare `SELECT` returns
+     * rows in storage order, not insertion order. 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>>>;
     /**
@@ -1330,6 +1584,39 @@ interface Outbox<Evt extends AnyDomainEvent> {
      */
     markDispatched: (dispatchIds: ReadonlyArray<string>) => Promise<void>;
 }
+/**
+ * Optional extension of {@link Outbox} for dispatchers that track
+ * delivery failures. Without failure tracking, a poison message (an
+ * event whose delivery always throws) is redelivered forever: it comes
+ * back from every `getPending` poll, blocks per-aggregate ordering
+ * behind it, and burns the dispatcher's cycles. This extension gives
+ * the dispatcher a bounded-retry story: report each failed delivery via
+ * {@link markFailed}; the implementation moves records past its
+ * attempt ceiling to a dead-letter set that `getPending` no longer
+ * returns, and {@link deadLetters} exposes them for alerting, manual
+ * inspection, and redelivery (deliver by hand, then ack via
+ * `markDispatched`, which also clears dead-lettered records).
+ *
+ * See the outbox guide's dispatcher recipe for the retry-then-dead-letter
+ * loop this port shape supports.
+ */
+interface DispatchTrackingOutbox<Evt extends AnyDomainEvent> extends Outbox<Evt> {
+    /**
+     * Records one failed delivery attempt for the given record:
+     * increments its attempt count (surfaced as
+     * {@link OutboxRecord.attempts}) and, once the implementation's
+     * ceiling is reached, moves the record to the dead-letter set.
+     * A no-op for unknown or already-dispatched ids (a late failure
+     * report after a successful retry must not resurrect the record).
+     */
+    markFailed: (dispatchId: string, error?: unknown) => Promise<void>;
+    /**
+     * Records that exhausted their delivery attempts. They no longer
+     * come back from `getPending`; wire this to alerting so poison
+     * messages surface instead of rotting silently.
+     */
+    deadLetters: () => Promise<ReadonlyArray<DeadLetterRecord<Evt>>>;
+}
 
 /**
  * Transaction-scope abstraction.
@@ -1424,7 +1711,9 @@ interface TransactionScope<TCtx> {
  *     events were recorded. Each harvested event is stamped with
  *     `aggregateVersion` = the aggregate's commit version (onto a frozen
  *     copy; a pre-set value wins) - consumers get the OCC version the
- *     row was written with, for ordering and idempotency watermarks.
+ *     row was written with, for cross-commit ordering and debugging.
+ *     All events of one commit share the stamp, so per-event dedup
+ *     belongs on `eventId`, not on this value (see the outbox guide).
  *
  *     **Harvest order.** Events are concatenated in the order
  *     aggregates appear in the returned `aggregates` array, then in
@@ -1525,6 +1814,18 @@ declare function withCommit<Evt extends AnyDomainEvent, R, TCtx>(deps: {
      * for delivery: the outbox dispatcher is the reliable path.
      */
     onPublishError?: (error: unknown, events: ReadonlyArray<Evt>) => void;
+    /**
+     * Observer for post-commit persistence-cleanup failures: a throw from
+     * `markPersisted`, the user-overridable `onPersisted` hook, or
+     * `clearPendingEvents`. Called once per failing aggregate with the
+     * error and that aggregate. Symmetric with {@link onPublishError}: the
+     * transaction has already committed, so the failure must NOT reject the
+     * write; without this observer it would otherwise vanish silently. The
+     * hook is an observer only: if it throws, its error is swallowed so the
+     * post-commit invariant holds, and the loop continues marking the
+     * remaining aggregates.
+     */
+    onPersistError?: (error: unknown, aggregate: IAggregateRoot<Id<string>, Evt>) => void;
     /**
      * Cooperative-cancellation signal. If already aborted, `withCommit`
      * rejects with the signal's `reason` BEFORE opening the transaction.
@@ -1625,6 +1926,167 @@ 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>;
+/**
+ * Construction options for {@link QueryBus}.
+ *
+ * @template E - The error channel type of the bus.
+ */
+interface QueryBusOptions<E = string> {
+    /**
+     * Maps a thrown value (a handler that throws, or dispatch to an
+     * unregistered query type) into the bus's error channel `E`. Defaults to
+     * {@link describeThrown}, which renders any thrown value as a `string`.
+     * base-error's `toStructuredError` fits this slot directly when `E` is a
+     * `StructuredError`.
+     */
+    errorMapper?: (thrown: unknown) => E;
+}
+/**
+ * Constructor arguments for {@link QueryBus}. When `E` is the default `string`,
+ * options are optional (the built-in {@link describeThrown} mapper applies).
+ * When `E` is widened, an `errorMapper` is required, so a typed channel can
+ * never silently fall back to string values.
+ */
+type QueryBusArgs<E> = [E] extends [string] ? [options?: QueryBusOptions<E>] : [options: QueryBusOptions<E> & {
+    errorMapper: (thrown: unknown) => E;
+}];
+/**
+ * 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
+ * // 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>
+ *
+ * // 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<TMap extends QueryTypeMap = QueryTypeMap, E = string> {
+    /**
+     * Executes a query by dispatching it to the registered handler.
+     * 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
+     */
+    execute<Q extends Query & {
+        type: keyof TMap & string;
+    }>(query: Q): Promise<Result<TMap[Q["type"]], E>>;
+    execute<Q extends Query, R>(query: Q): Promise<Result<R, E>>;
+    /**
+     * Executes a query by dispatching it to the registered handler.
+     * Throws an error if no handler is registered.
+     *
+     * @param query - The query to execute
+     * @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<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.
+ * 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)
+ * - Error handling
+ * - Timeout handling
+ * - Metrics and observability
+ * - Query result caching
+ * - Rate limiting
+ *
+ * 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
+ * // 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>
+ *
+ * // 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, E = string> implements IQueryBus<TMap, E> {
+    private readonly handlers;
+    private readonly errorMapper;
+    constructor(...args: QueryBusArgs<E>);
+    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"]], E>>;
+    execute<Q extends Query, R>(query: Q): Promise<Result<R, E>>;
+    executeUnsafe<Q extends Query & {
+        type: keyof TMap & string;
+    }>(query: Q): Promise<TMap[Q["type"]]>;
+    executeUnsafe<Q extends Query, R>(query: Q): Promise<R>;
+}
+
 /**
  * A class reference used as the type key of the identity map. Keying
  * on the CLASS (not a name string) makes collisions impossible by
@@ -1935,6 +2397,13 @@ interface UnitOfWorkDeps<Evt extends AnyDomainEvent, TCtx, TRepos> {
     bus?: EventBus<Evt>;
     /** See `withCommit`: observer for post-commit `bus.publish` failures. */
     onPublishError?: (error: unknown, events: ReadonlyArray<Evt>) => void;
+    /**
+     * See `withCommit`: observer for post-commit persistence-cleanup failures
+     * (a throw from `markPersisted`, the `onPersisted` hook, or
+     * `clearPendingEvents`). Called once per failing aggregate; observer only,
+     * never rejects the committed write.
+     */
+    onPersistError?: (error: unknown, aggregate: IAggregateRoot<Id<string>, Evt>) => void;
     repositories: RepositoryFactories<TCtx, TRepos, Evt>;
 }
 /**
@@ -2017,139 +2486,230 @@ declare class UnitOfWork<Evt extends AnyDomainEvent, TCtx, TRepos extends Record
     private buildRepositories;
 }
 
+/** Base shape for every input accepted by a domain state machine. */
+type DomainMachineInput = {
+    readonly type: string;
+};
+/** Recursively readonly view of data accepted by the domain state machine. */
+type DomainMachineReadonly<TValue> = TValue extends bigint | boolean | null | number | string | symbol | undefined ? TValue : TValue extends (...args: never[]) => unknown ? TValue : TValue extends readonly unknown[] ? {
+    readonly [TKey in keyof TValue]: DomainMachineReadonly<TValue[TKey]>;
+} : TValue extends object ? {
+    readonly [TKey in keyof TValue]: DomainMachineReadonly<TValue[TKey]>;
+} : TValue;
+/** Immutable state and context value suitable for persistence. */
+type DomainMachineSnapshot<TState extends string, TContext> = {
+    readonly state: TState;
+    readonly context: DomainMachineReadonly<TContext>;
+};
+/** Optional context replacement and requested external work from a reducer. */
+type DomainTransitionResult<TContext, TOutput> = {
+    readonly context?: TContext;
+    readonly outputs?: readonly TOutput[];
+};
+/** A guard either allows, generically rejects, or returns a domain-specific rejection. */
+type DomainTransitionGuardResult = boolean | DomainError;
+/** A guarded state change and its optional pure context reducer. */
+type DomainTransition<TState extends string, TContext, TInput extends DomainMachineInput, TOutput, TSource extends TState = TState> = {
+    readonly target: TState;
+    /**
+     * Must be synchronous, deterministic, and side-effect-free. Return a
+     * `DomainError` to provide a typed rejection that `can()` treats as false and
+     * `dispatch()` throws unchanged.
+     */
+    readonly guard?: (input: {
+        readonly state: TSource;
+        readonly context: DomainMachineReadonly<TContext>;
+        readonly input: DomainMachineReadonly<TInput>;
+    }) => DomainTransitionGuardResult;
+    /** Must be synchronous, deterministic, and side-effect-free. */
+    readonly reduce?: (input: {
+        readonly state: TSource;
+        readonly context: DomainMachineReadonly<TContext>;
+        readonly input: DomainMachineReadonly<TInput>;
+    }) => DomainTransitionResult<TContext, TOutput> | undefined;
+};
+/** Configuration for one named control state. */
+type DomainStateNode<TState extends string, TContext, TInput extends DomainMachineInput, TOutput, TName extends TState = TState> = {
+    readonly terminal?: boolean;
+    /** State-specific context invariant. Must be synchronous, deterministic, and side-effect-free. */
+    readonly validateContext?: (input: {
+        readonly state: TName;
+        readonly context: DomainMachineReadonly<TContext>;
+    }) => boolean;
+    readonly on?: {
+        readonly [TType in TInput["type"]]?: DomainTransition<TState, TContext, Extract<TInput, {
+            readonly type: TType;
+        }>, TOutput, TName>;
+    };
+};
+/** Complete, finite domain lifecycle definition. */
+type DomainMachineDefinition<TState extends string, TContext, TInput extends DomainMachineInput, TOutput = never> = {
+    readonly initial: TState;
+    readonly initialContext: () => TContext;
+    /** Must be synchronous, deterministic, and side-effect-free. */
+    readonly validateSnapshot?: (snapshot: DomainMachineSnapshot<TState, TContext>) => boolean;
+    readonly states: {
+        readonly [TName in TState]: DomainStateNode<TState, TContext, TInput, TOutput, TName>;
+    };
+};
+/** Result of a successful transition. */
+type DomainTransitionOutcome<TState extends string, TContext, TOutput> = {
+    readonly from: TState;
+    readonly to: TState;
+    readonly snapshot: DomainMachineSnapshot<TState, TContext>;
+    readonly outputs: readonly DomainMachineReadonly<TOutput>[];
+};
+
+type DomainMachineDefinitionDiagnostic<TState extends string> = {
+    readonly code: "unreachable-state";
+    readonly state: TState;
+} | {
+    readonly code: "structural-dead-end";
+    readonly state: TState;
+} | {
+    readonly code: "no-terminal-path";
+    readonly state: TState;
+};
+type DomainMachineTransitionDescription<TState extends string, TInputType extends string> = {
+    readonly state: TState;
+    readonly inputType: TInputType;
+    readonly target: TState;
+    readonly guarded: boolean;
+};
+type DomainMachineDefinitionAnalysis<TState extends string, TInputType extends string> = {
+    readonly diagnostics: readonly DomainMachineDefinitionDiagnostic<TState>[];
+    readonly transitions: readonly DomainMachineTransitionDescription<TState, TInputType>[];
+    /** States reachable when every guard is assumed to allow its transition. */
+    readonly structurallyReachableStates: readonly TState[];
+    /** States with a graph path to a terminal state when every guard is assumed to allow it. */
+    readonly statesWithTerminalPath: readonly TState[];
+};
 /**
- * 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
- * ```
+ * Inspects the declarative transition graph without executing definition callbacks.
+ * Guarded edges are treated as possible edges, so diagnostics never claim more
+ * runtime reachability than the static graph can prove.
  */
-type QueryTypeMap = Record<string, unknown>;
+declare function analyzeDomainMachineDefinition<TState extends string, TContext, TInput extends DomainMachineInput, TOutput>(definition: DomainMachineDefinition<TState, TContext, TInput, TOutput>): DomainMachineDefinitionAnalysis<TState, TInput["type"]>;
+
+declare const preparedDefinitionBrand: unique symbol;
 /**
- * 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
- * // 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>
+ * A machine definition that `prepareDomainMachineDefinition` has
+ * validated, defensively copied, and deeply frozen. Assignable wherever
+ * a plain `DomainMachineDefinition` is accepted; the reverse does NOT
+ * hold (the brand is required), so an API that demands a prepared
+ * definition rejects raw ones at compile time. The pure functions and
+ * the `DomainStateMachine` constructor recognize prepared definitions
+ * at runtime and skip their per-call validate-and-copy.
+ */
+type PreparedDomainMachineDefinition<TState extends string, TContext, TInput extends DomainMachineInput, TOutput = never> = DomainMachineDefinition<TState, TContext, TInput, TOutput> & {
+    readonly [preparedDefinitionBrand]: true;
+};
+/**
+ * Validates and stabilizes a machine definition ONCE, for repeated use
+ * with the pure functions. Without it, `transitionDomainState` and
+ * `canTransitionDomainState` re-validate and defensively re-copy the
+ * WHOLE definition on every call (the documented safety of the raw
+ * path); on a hot dispatch path that is avoidable O(definition) work.
+ * The `DomainStateMachine` class does the equivalent once in its
+ * constructor; this export brings the same amortization to pure-API
+ * users:
  *
- * // Without type map – works like before
- * const bus = new QueryBus();
- * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
- * // result: Result<unknown, string>
+ * ```ts
+ * const prepared = prepareDomainMachineDefinition(orderLifecycle);
+ * // per dispatch: no re-validation, no definition copy
+ * const outcome = transitionDomainState(prepared, snapshot, input);
  * ```
+ *
+ * The returned definition is a deeply frozen copy, isolated from later
+ * mutation of the input object. Preparing an already-prepared
+ * definition returns it unchanged.
  */
-interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
-    /**
-     * Executes a query by dispatching it to the registered handler.
-     * 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
-     */
-    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.
-     * Throws an error if no handler is registered.
-     *
-     * @param query - The query to execute
-     * @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<K extends keyof TMap & string, Q extends Query & {
-        type: K;
-    } = Query & {
-        type: K;
-    }>(queryType: K, handler: QueryHandler<Q, TMap[K]>): void;
+declare function prepareDomainMachineDefinition<TState extends string, TContext, TInput extends DomainMachineInput, TOutput>(definition: DomainMachineDefinition<TState, TContext, TInput, TOutput>): PreparedDomainMachineDefinition<TState, TContext, TInput, TOutput>;
+
+/** No transition is defined for the input in the current state. */
+declare class InvalidDomainTransitionError extends DomainError<"InvalidDomainTransitionError"> {
+    readonly state: string;
+    readonly inputType: string;
+    constructor(state: string, inputType: string);
+}
+/** A defined transition was rejected by its domain guard. */
+declare class DomainTransitionGuardRejectedError extends DomainError<"DomainTransitionGuardRejectedError"> {
+    readonly state: string;
+    readonly inputType: string;
+    constructor(state: string, inputType: string);
+}
+/** The machine definition violates its runtime contract. */
+declare class InvalidDomainMachineDefinitionError extends BaseError<"InvalidDomainMachineDefinitionError"> {
+    constructor(message: string, cause?: unknown);
+}
+/** Context contains unsupported or unsafe runtime data. */
+declare class InvalidDomainMachineContextError extends BaseError<"InvalidDomainMachineContextError"> {
+    constructor(message: string, cause?: unknown);
+}
+/** A supplied or produced snapshot is malformed or violates invariants. */
+declare class InvalidDomainMachineSnapshotError extends BaseError<"InvalidDomainMachineSnapshotError"> {
+    constructor(message: string, cause?: unknown);
 }
+/** An input is malformed or contains unsupported runtime data. */
+declare class InvalidDomainMachineInputError extends BaseError<"InvalidDomainMachineInputError"> {
+    constructor(message: string, cause?: unknown);
+}
+/** A guard returned a value other than `boolean` or `DomainError`. */
+declare class InvalidDomainTransitionGuardResultError extends BaseError<"InvalidDomainTransitionGuardResultError"> {
+    constructor(message: string, cause?: unknown);
+}
+/** A reducer returned a malformed result or unsupported output data. */
+declare class InvalidDomainTransitionResultError extends BaseError<"InvalidDomainTransitionResultError"> {
+    constructor(message: string, cause?: unknown);
+}
+/** A callback attempted to evaluate the same stateful machine recursively. */
+declare class ReentrantDomainStateMachineEvaluationError extends BaseError<"ReentrantDomainStateMachineEvaluationError"> {
+    constructor();
+}
+
+/** Creates and validates a fresh initial snapshot from a machine definition. */
+declare function createInitialDomainMachineSnapshot<TState extends string, TContext, TInput extends DomainMachineInput, TOutput>(definition: DomainMachineDefinition<TState, TContext, TInput, TOutput>): DomainMachineSnapshot<TState, TContext>;
 /**
- * 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).
+ * Checks whether an input currently has an allowed transition.
  *
- * **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)
- * - Error handling
- * - Timeout handling
- * - Metrics and observability
- * - Query result caching
- * - Rate limiting
- *
- * 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
+ * Returns `false` for missing transitions, terminal states, rejected guards,
+ * and inputs without an own string `type` property. Invalid payload data for a
+ * matching transition and broken guard code still throw structured errors.
+ */
+declare function canTransitionDomainState<TState extends string, TContext, TInput extends DomainMachineInput, TOutput>(definition: DomainMachineDefinition<TState, TContext, TInput, TOutput>, snapshot: DomainMachineSnapshot<TState, TContext>, input: TInput): boolean;
+/**
+ * Applies one input without mutating the input definition or snapshot.
  *
- * @example
- * ```typescript
- * // 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>
+ * @throws {@link InvalidDomainTransitionError} when no transition is defined.
+ * @throws {@link DomainTransitionGuardRejectedError} when its guard rejects.
+ * @throws A concrete `DomainError` returned by a rejecting guard.
+ */
+declare function transitionDomainState<TState extends string, TContext, TInput extends DomainMachineInput, TOutput>(definition: DomainMachineDefinition<TState, TContext, TInput, TOutput>, snapshot: DomainMachineSnapshot<TState, TContext>, input: TInput): DomainTransitionOutcome<TState, TContext, TOutput>;
+
+/**
+ * Stateful convenience wrapper around the pure domain transition functions.
  *
- * // 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" });
- * ```
+ * Persist {@link snapshot}, not the machine instance. Pass a restored snapshot
+ * to the second constructor overload to validate and reconstitute a machine.
  */
-declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQueryBus<TMap> {
-    private readonly handlers;
-    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>>;
-    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>;
+declare class DomainStateMachine<TState extends string, TContext, TInput extends DomainMachineInput, TOutput = never> {
+    #private;
+    private readonly definition;
+    constructor(definition: DomainMachineDefinition<TState, TContext, TInput, TOutput>);
+    constructor(definition: DomainMachineDefinition<TState, TContext, TInput, TOutput>, snapshot: DomainMachineSnapshot<TState, TContext> | undefined);
+    /** Returns a defensive, deeply frozen copy of the current snapshot. */
+    get snapshot(): DomainMachineSnapshot<TState, TContext>;
+    /** Current named control state. */
+    get state(): TState;
+    /** Current deeply readonly context. */
+    get context(): DomainMachineReadonly<TContext>;
+    /** Whether the current state permanently forbids outgoing transitions. */
+    isTerminal(): boolean;
+    /** Checks a transition without changing the current snapshot. */
+    can(input: TInput): boolean;
+    /** Applies an input and advances the current snapshot on success. */
+    dispatch(input: TInput): DomainTransitionOutcome<TState, TContext, TOutput>;
+    private evaluate;
 }
 
 /**
@@ -2193,15 +2753,35 @@ declare class EventBusImpl<Evt extends AnyDomainEvent> implements EventBus<Evt>
     publish(events: ReadonlyArray<Evt>): Promise<void>;
 }
 
+/** Construction options for {@link InMemoryOutbox}. */
+interface InMemoryOutboxOptions {
+    /**
+     * Failed-delivery ceiling: once `markFailed` has been reported this
+     * many times for a record, it moves to {@link InMemoryOutbox.deadLetters}
+     * and stops coming back from `getPending`. Default `5`.
+     */
+    maxDeliveryAttempts?: number;
+}
 /**
- * In-memory reference implementation of `Outbox<Evt>`.
+ * In-memory reference implementation of `DispatchTrackingOutbox<Evt>`
+ * (and therefore of the plain `Outbox<Evt>` port).
  *
  * Intended for tests, single-process workers, and quick-start demos.
  * Uses the event's own `eventId` as the dispatch id: the common, clean
- * choice. Storage is a `Map<string, OutboxRecord<Evt>>` keyed by
- * `eventId`, so re-adding the same event is naturally idempotent (the
- * duplicate entry overwrites itself; `getPending` returns each event at
- * most once).
+ * choice. Storage is a `Map` keyed by `eventId`, so re-adding the same
+ * event is naturally idempotent (`getPending` returns each event at
+ * most once; a re-add refreshes the stored copy, e.g. a retried
+ * commit's freshly stamped `aggregateVersion`, while the delivery
+ * attempt count survives), and insertion order is preserved:
+ * `getPending` returns records in commit order, as the port contract
+ * requires.
+ *
+ * Dispatch tracking: `markFailed` increments the record's attempt count
+ * and, at `maxDeliveryAttempts`, moves it to the dead-letter set
+ * exposed by `deadLetters()`. Re-`add`ing a dead-lettered event
+ * requeues it with a fresh attempts budget (the operator-facing
+ * inverse of `deadLetters()`); `markDispatched` acks pending AND
+ * dead-lettered records (manual redelivery then ack).
  *
  * For production, back the outbox with a transactional store so the
  * outbox row participates in the same transaction as the aggregate
@@ -2230,11 +2810,156 @@ declare class EventBusImpl<Evt extends AnyDomainEvent> implements EventBus<Evt>
  * });
  * ```
  */
-declare class InMemoryOutbox<Evt extends AnyDomainEvent> implements Outbox<Evt> {
+declare class InMemoryOutbox<Evt extends AnyDomainEvent> implements DispatchTrackingOutbox<Evt> {
     private readonly pending;
+    private readonly dead;
+    private readonly maxDeliveryAttempts;
+    constructor(options?: InMemoryOutboxOptions);
     add(events: ReadonlyArray<Evt>): Promise<void>;
     getPending(limit?: number): Promise<ReadonlyArray<OutboxRecord<Evt>>>;
     markDispatched(dispatchIds: ReadonlyArray<string>): Promise<void>;
+    markFailed(dispatchId: string, error?: unknown): Promise<void>;
+    deadLetters(): Promise<ReadonlyArray<DeadLetterRecord<Evt>>>;
+}
+
+/** Options for {@link EventStore.append}. */
+interface EventStoreAppendOptions {
+    /**
+     * The stream version the writer loaded (its optimistic-concurrency
+     * baseline): the number of events the stream held when the aggregate
+     * was reconstituted. `0` for a brand-new stream. For kit aggregates
+     * this is `aggregate.persistedVersion ?? 0`; the aggregate version IS
+     * the event count, so stream version and aggregate version align.
+     */
+    readonly expectedVersion: number;
+}
+/** Options for {@link EventStore.readStream}. */
+interface ReadStreamOptions {
+    /**
+     * Return only events AFTER this stream position (1-based event count),
+     * the snapshot catch-up read: `readStream(id, { fromVersion:
+     * snapshot.version })` yields exactly the events
+     * `restoreFromSnapshotWithEvents` needs. Defaults to `0` (the whole
+     * stream).
+     */
+    readonly fromVersion?: number;
+}
+/**
+ * Driven port for event-sourced aggregate persistence: an append-only
+ * store with one stream per aggregate (the stream id IS the aggregate
+ * id, Greg Young's stream-per-aggregate default).
+ *
+ * The kit ships the port, the OCC error contract, `InMemoryEventStore`
+ * as the reference implementation, and the event-sourced repository
+ * contract suite (`@shirudo/ddd-kit/testing`). Your adapter implements
+ * this port against a real store and must pass that suite: like the
+ * state-stored `IRepository`, optimistic concurrency is a testable
+ * adapter contract, not a kit guarantee.
+ *
+ * Repository usage (see the event-sourcing guide):
+ *
+ * ```ts
+ * async getById(id: OrderId): Promise<Order | null> {
+ *   const cached = this.session.identityMap.get(Order, id);
+ *   if (cached) return cached;
+ *   const history = await this.eventStore.readStream(id);
+ *   if (history.length === 0) return null;
+ *   const order = Order.reconstitute(id); // bare instance, no events
+ *   const result = order.loadFromHistory(history);
+ *   if (result.isErr()) throw result.error; // corrupt stream
+ *   this.session.identityMap.set(Order, id, order);
+ *   return order;
+ * }
+ *
+ * async save(order: Order): Promise<void> {
+ *   if (order.pendingEvents.length === 0) return;
+ *   this.session.enrollSaved(order);
+ *   await this.eventStore.append(order.id, order.pendingEvents, {
+ *     expectedVersion: order.persistedVersion ?? 0,
+ *   });
+ * }
+ * ```
+ *
+ * `save` appends the UNSTAMPED `pendingEvents` originals; `withCommit`
+ * separately hands the outbox stamped copies. The store's own position
+ * is the ordering authority for replay (see the event-sourcing guide's
+ * note on `aggregateVersion`).
+ *
+ * **One save per aggregate per unit of work, after all mutations.**
+ * `pendingEvents` are cleared and `persistedVersion` advances only AFTER
+ * the commit (`markPersisted`), so a second `save` of the same instance
+ * inside one unit of work would re-append the already-appended events
+ * with a stale `expectedVersion` and deterministically conflict, with no
+ * concurrent writer in sight. This is the same rule the state-stored
+ * path documents as "mutate first, save last" on `withCommit`; it is
+ * not specific to event sourcing.
+ */
+interface EventStore<Evt extends AnyDomainEvent> {
+    /**
+     * Atomically appends `events` to the stream, guarded by optimistic
+     * concurrency: the append succeeds only when the stream currently
+     * holds exactly `options.expectedVersion` events.
+     *
+     * Contract for implementations:
+     *
+     *  1. **OCC:** on a version mismatch (stale writer, duplicate create
+     *     racing on `expectedVersion: 0`, or an expectedVersion ahead of
+     *     the stream), throw `ConcurrencyConflictError` from
+     *     `@shirudo/ddd-kit` carrying the expected and actual stream
+     *     versions; map your store's native conflict signal to it instead
+     *     of letting a raw driver error escape. One sanctioned exception:
+     *     an adapter that can DISTINGUISH the duplicate-create race
+     *     (`expectedVersion: 0` against a stream that already exists,
+     *     typically a unique violation on the first position) may throw
+     *     `DuplicateAggregateError` for that case instead, matching the
+     *     state-stored insert path. It is deliberately NOT retryable:
+     *     replaying the same append cannot succeed; the use case resolves
+     *     the create race (load the existing aggregate, or surface HTTP
+     *     409). The contract suite accepts both errors for this race.
+     *  2. **Atomicity:** all events land or none do; a rejected append
+     *     leaves the stream untouched.
+     *  3. **Order:** events are stored in the given array order, appended
+     *     after the existing stream tail.
+     *  4. **Append-only:** stored events are never edited or deleted;
+     *     corrections are new (compensating) events.
+     *
+     * An empty `events` array is a no-op; implementations resolve without
+     * touching the store (an ES repository skips `save` for aggregates
+     * without pending events anyway).
+     */
+    append(streamId: Id<string>, events: ReadonlyArray<Evt>, options: EventStoreAppendOptions): Promise<void>;
+    /**
+     * Reads the stream in append order. Returns an empty array for an
+     * unknown stream (the repository maps that to `null`). With
+     * `options.fromVersion`, returns only the events after that stream
+     * position (snapshot catch-up). The returned array is owned by the
+     * caller; implementations must not hand out live internal state.
+     */
+    readStream(streamId: Id<string>, options?: ReadStreamOptions): Promise<ReadonlyArray<Evt>>;
+}
+
+/**
+ * In-memory reference implementation of `EventStore<Evt>`.
+ *
+ * Intended for tests, single-process workers, and quick-start demos.
+ * Implements the full port contract: expectedVersion-guarded appends
+ * (throwing `ConcurrencyConflictError` on mismatch), atomic rejected
+ * appends, append-order reads, and `fromVersion` slicing.
+ *
+ * For production, back the port with a durable store whose append and
+ * the aggregate transaction share atomicity (a table with a
+ * `(stream_id, position)` unique key inside the same transaction, or a
+ * dedicated event store). Same caveat as `InMemoryOutbox`: this class
+ * lives in memory only and knows nothing about your `TransactionScope`
+ * rollbacks; events appended inside a transaction that later rolls back
+ * are NOT removed. The event-sourced repository contract suite's
+ * reference environment shows the snapshot/restore pattern for
+ * rollback-pure in-memory testing.
+ */
+declare class InMemoryEventStore<Evt extends AnyDomainEvent> implements EventStore<Evt> {
+    private readonly streams;
+    append(streamId: Id<string>, events: ReadonlyArray<Evt>, options: EventStoreAppendOptions): Promise<void>;
+    readStream(streamId: Id<string>, options?: ReadStreamOptions): Promise<ReadonlyArray<Evt>>;
 }
 
 /**
@@ -2453,7 +3178,12 @@ interface RetryPolicy {
      * that your adapter has not mapped to a retryable kit error.
      */
     isRetryable?: (error: unknown) => boolean;
-    /** Observer fired before each backoff wait (logging / metrics). */
+    /**
+     * Observer fired before each backoff wait (logging / metrics).
+     * Neutralised like the `withCommit` observers: a synchronous throw or
+     * an async rejection is swallowed, so a buggy observer can neither
+     * abort the retry loop nor mask the original retryable error.
+     */
     onRetry?: (info: {
         attempt: number;
         error: unknown;
@@ -2555,7 +3285,12 @@ declare function deepFreeze<T>(obj: T, visited?: WeakSet<object>): Readonly<T>;
  * `vo(input)` never freezes the caller's own object graph as a
  * side-effect. Mutating the input afterwards does not bleed into the VO.
  * Symbol-keyed properties are preserved (matching `voEquals`); function
- * values are rejected (Value Objects are data, not behaviour).
+ * values and custom class instances are rejected (Value Objects are plain
+ * data, not behaviour-bearing object graphs). Inputs must be trusted and
+ * Proxy-free: ECMAScript provides no portable way to identify a transparent
+ * Proxy without potentially executing its traps, so `vo()` is not a sandbox
+ * for hostile in-process objects. Built-ins that cannot provide immutable,
+ * value-based semantics are rejected instead of weakening the VO contract.
  *
  * @example
  * ```typescript
@@ -2572,7 +3307,6 @@ declare function vo<T>(t: T): VO<T>;
  * - Nested objects and arrays
  * - Primitives (including NaN)
  * - Dates, Maps, Sets, RegExp
- * - TypedArrays and DataView
  * - Symbol keys
  * - Circular references
  *
@@ -2640,8 +3374,8 @@ declare function voEqualsExcept<T>(a: VO<T>, b: VO<T>, options: DeepEqualExceptO
  * Creates a value object with optional validation.
  * Returns a Result type instead of throwing an error.
  *
- * Note: the Result covers VALIDATION failures only. Non-data values in
- * the input (functions, Promise/WeakMap/WeakSet) still throw a
+ * Note: the Result covers VALIDATION failures only. Non-data values and
+ * built-ins without immutable value semantics still throw a
  * `TypeError` from `vo()`; they cannot occur in parsed JSON and signal
  * a programming error, not a validation failure.
  *
@@ -2709,7 +3443,7 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
     readonly props: Readonly<T>;
     /**
      * Creates a new ValueObject.
-     * The properties are deep-cloned (prototype-preserving) and then deeply
+     * The plain-data properties are deep-cloned and then deeply
      * frozen, so the caller's own object graph is never frozen or mutated,
      * and later mutation of the input does not bleed into the value object.
      *
@@ -2792,4 +3526,4 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
  */
 declare function voValidated<T>(t: T, validate: (issues: ValidationError, value: T) => void, message?: string): Result<VO<T>, ValidationError>;
 
-export { type AggregateClass, type AggregateConfig, AggregateRoot, AggregateSnapshot, AnyDomainEvent, type Command, CommandBus, type CommandHandler, CommitError, CreateDomainEventOptions, DeepEqualExceptOptions, DomainError, Entity, type EventBus, EventBusImpl, type EventHandler, EventSourcedAggregate, IAggregateRoot, type ICommandBus, type IEntity, IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IUnitOfWorkRepository, type IValueObject, Id, type Identifiable, IdentityMap, InMemoryOutbox, InfrastructureError, NestedUnitOfWorkError, type OnceOptions, type Outbox, type OutboxRecord, type Query, QueryBus, type QueryHandler, type RepositoryFactories, type RetryPolicy, RetryingTransactionScope, RollbackError, type RunOptions, TransactionClosedError, type TransactionScope, type TransactionalOptions, UnitOfWork, type UnitOfWorkContext, type UnitOfWorkDeps, type UnitOfWorkSession, type VO, ValueObject, Version, computeBackoffDelay, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, removeEntityById, replaceEntityById, sameEntity, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withCommit };
+export { type AggregateClass, type AggregateConfig, AggregateRoot, AggregateSnapshot, AnyDomainEvent, type ClockFactory, type Command, CommandBus, type CommandBusOptions, type CommandHandler, CommitError, CreateDomainEventOptions, type DeadLetterRecord, DeepEqualExceptOptions, type DispatchTrackingOutbox, DomainError, type DomainMachineDefinition, type DomainMachineDefinitionAnalysis, type DomainMachineDefinitionDiagnostic, type DomainMachineInput, type DomainMachineReadonly, type DomainMachineSnapshot, type DomainMachineTransitionDescription, DomainStateMachine, type DomainStateNode, type DomainTransition, DomainTransitionGuardRejectedError, type DomainTransitionGuardResult, type DomainTransitionOutcome, type DomainTransitionResult, Entity, type EntityConfig, type EventBus, EventBusImpl, type EventHandler, EventSourcedAggregate, type EventStore, type EventStoreAppendOptions, IAggregateRoot, type ICommandBus, type IEntity, IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IUnitOfWorkRepository, type IValueObject, Id, type Identifiable, IdentityMap, InMemoryEventStore, InMemoryOutbox, type InMemoryOutboxOptions, InfrastructureError, InvalidDomainMachineContextError, InvalidDomainMachineDefinitionError, InvalidDomainMachineInputError, InvalidDomainMachineSnapshotError, InvalidDomainTransitionError, InvalidDomainTransitionGuardResultError, InvalidDomainTransitionResultError, NestedUnitOfWorkError, type OnceOptions, type Outbox, type OutboxRecord, type PreparedDomainMachineDefinition, type Query, QueryBus, type QueryBusOptions, type QueryHandler, type ReadStreamOptions, ReentrantDomainStateMachineEvaluationError, type RepositoryFactories, type RetryPolicy, RetryingTransactionScope, RollbackError, type RunOptions, TransactionClosedError, type TransactionScope, type TransactionalOptions, UnitOfWork, type UnitOfWorkContext, type UnitOfWorkDeps, type UnitOfWorkSession, type VO, ValueObject, Version, analyzeDomainMachineDefinition, canTransitionDomainState, computeBackoffDelay, createInitialDomainMachineSnapshot, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, prepareDomainMachineDefinition, removeEntityById, replaceEntityById, resetClockFactory, sameEntity, setClockFactory, transitionDomainState, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withClockFactory, withCommit };