@shirudo/ddd-kit 1.2.0 → 2.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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-DclYgG_D.js';
-export { p as AggregateDeletedError, q as AggregateNotFoundError, f as ClockFactory, u as ConcurrencyConflictError, k as DomainEvent, t as DuplicateAggregateError, E as EventIdFactory, j as EventMetadata, v as IdGenerator, M as MissingHandlerError, 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-DclYgG_D.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-CePTINEt.js';
+export { p as AggregateDeletedError, t as AggregateNotFoundError, q as AggregateNotFoundErrorOptions, f as ClockFactory, y as ConcurrencyConflictError, x as ConcurrencyConflictErrorOptions, k as DomainEvent, v as DuplicateAggregateError, u as DuplicateAggregateErrorOptions, o as EventHarvestError, E as EventIdFactory, j as EventMetadata, z as IdGenerator, M as MissingHandlerError, U as UnenrolledChangesError, m as copyMetadata, l as createDomainEvent, n 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-CePTINEt.js';
 import { Result } from '@shirudo/result';
 import { BaseError, ValidationError } from '@shirudo/base-error';
 import { DeepEqualExceptOptions } from './utils.js';
@@ -446,7 +446,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * `changedKeys`/`hasChanges`. An override that skips `super` leaves
      * that baseline uncaptured: `changedKeys` permanently reports ALL
      * keys and `hasChanges` never returns `false`, so a partial-write
-     * repository silently degrades to full writes on every save — on top
+     * repository silently degrades to full writes on every save, on top
      * of the broken version sync.
      *
      * @param version - The version the row currently holds in the DB
@@ -694,7 +694,7 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      * If you override this, call `super.markRestored(version)` FIRST:
      * skipping it leaves the baseline uncaptured, so `changedKeys`
      * permanently reports ALL keys and `hasChanges` never returns `false`
-     * — partial-write repositories silently degrade to full writes — on
+     * (partial-write repositories silently degrade to full writes), on
      * top of breaking version sync.
      */
     protected markRestored(version: Version): void;
@@ -713,7 +713,7 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      * **How it works.** `setState()` replaces state immutably and the
      * state object is shallow-frozen, so unchanged top-level sub-objects
      * keep reference identity across mutations. The diff is therefore a
-     * shallow per-key `!==` against the baseline reference — O(top-level
+     * shallow per-key `!==` against the baseline reference: O(top-level
      * keys), no proxies, no deep diff. A key also counts as dirty when its
      * *presence* differs (added or removed, even with an `undefined`
      * value). Computed fresh on every access (a new `Set` each time), so
@@ -726,12 +726,12 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      * class-instance `TState` mutated through its own methods defeats
      * tracking entirely (the reference never changes). A keyless `TState`
      * (primitive, bare `Date`) has no keys to report, so `changedKeys`
-     * stays empty for it — use {@link hasChanges}, whose reference
+     * stays empty for it; use {@link hasChanges}, whose reference
      * fallback covers keyless states. A deep-equal but newly-referenced
      * value reports a false POSITIVE (harmless extra write); under the
      * contract above there are no false negatives.
      *
-     * Granularity is per top-level key — table-granular, not row-granular:
+     * Granularity is per top-level key, table-granular, not row-granular:
      * a dirty collection key means "this child table changed", not which
      * rows. `EventSourcedAggregate` deliberately has no `changedKeys`;
      * its `pendingEvents` are the change record.
@@ -741,16 +741,16 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      * Safe skip signal: `false` only when there is genuinely nothing to
      * persist or flush. `true` when the aggregate has never been
      * persisted, the version moved past `persistedVersion`, there are
-     * unflushed {@link pendingEvents}, any state key is dirty, or — for
+     * unflushed {@link pendingEvents}, any state key is dirty, or, for
      * keyless states the per-key diff cannot see (primitive `TState`,
-     * zero-own-key objects like a bare `Date`) — the state reference
+     * zero-own-key objects like a bare `Date`), the state reference
      * changed since the baseline.
      *
      * The version clause is deliberate: `setState({...state}, true)` with
      * identical per-key values yields empty {@link changedKeys} but a
      * bumped version. If a repository skipped `save()` on a state-only
      * check, `withCommit` would still call `markPersisted(version)` after
-     * commit, desyncing `persistedVersion` from the DB row — and the next
+     * commit, desyncing `persistedVersion` from the DB row; and the next
      * uncontended save would throw a false `ConcurrencyConflictError`.
      *
      * The pending-events clause covers the sanctioned decoupled
@@ -1006,6 +1006,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 +1042,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 +1061,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 +1109,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 +1137,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 +1175,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>>;
 }
 
 /**
@@ -1386,8 +1414,22 @@ interface Outbox<Evt extends AnyDomainEvent> {
  * (constructor injection, factory functions, `withTx` chains); pick one
  * and keep it consistent.
  */
+/** Options passed to {@link TransactionScope.transactional}. */
+interface TransactionalOptions {
+    /**
+     * Cooperative-cancellation signal forwarded from `withCommit` /
+     * `UnitOfWork.run`. The kit does not interrupt an in-flight query
+     * itself: it pre-checks `aborted` before opening the transaction and
+     * exposes the signal for the work callback to poll. A scope whose
+     * driver supports cancellation (passing the signal to the query, an
+     * interactive-transaction timeout) SHOULD honor it to abort work
+     * already in progress; scopes that ignore it stay correct, just not
+     * eagerly cancellable.
+     */
+    readonly signal?: AbortSignal;
+}
 interface TransactionScope<TCtx> {
-    transactional<T>(fn: (ctx: TCtx) => Promise<T>): Promise<T>;
+    transactional<T>(fn: (ctx: TCtx) => Promise<T>, options?: TransactionalOptions): Promise<T>;
 }
 
 /**
@@ -1469,12 +1511,12 @@ interface TransactionScope<TCtx> {
  * version and (on `AggregateRoot`) re-baselines dirty tracking against
  * the CURRENT state. A mutation between `save` and the callback's return
  * therefore desyncs OCC (next save throws a false
- * `ConcurrencyConflictError`) — and under a partial-write repository
+ * `ConcurrencyConflictError`); and under a partial-write repository
  * using `changedKeys`, an un-bumped mutation is silently marked clean
  * and never written. The `aggregateVersion` stamp widens the blast
  * radius further: harvested events would publicly claim a version the
  * committed row does not carry, poisoning every consumer's ordering
- * and idempotency watermarks — a cross-service inconsistency, not just
+ * and idempotency watermarks: a cross-service inconsistency, not just
  * a local one. Mutate first, save last.
  *
  * **Duplicate aggregates are deduped by reference.** If the returned
@@ -1511,6 +1553,15 @@ 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;
+    /**
+     * Cooperative-cancellation signal. If already aborted, `withCommit`
+     * rejects with the signal's `reason` BEFORE opening the transaction.
+     * Otherwise the signal is forwarded to `scope.transactional`, where a
+     * cancellation-aware scope can abort an in-flight query. The kit does
+     * not race the work promise: aborting does not kill a running query
+     * unless the scope honors the signal.
+     */
+    signal?: AbortSignal;
 }, fn: (ctx: TCtx) => Promise<{
     result: R;
     aggregates: ReadonlyArray<IAggregateRoot<Id<string>, Evt>>;
@@ -1518,7 +1569,7 @@ declare function withCommit<Evt extends AnyDomainEvent, R, TCtx>(deps: {
      * Optional marker: which of `aggregates` were DELETED in this unit
      * of work. Their pending events are harvested like any other
      * (deletion events must reach the outbox), but the post-commit
-     * lifecycle differs: `markPersisted` is NOT called on them — it
+     * lifecycle differs: `markPersisted` is NOT called on them. It
      * would fire the user-overridable `onPersisted` hook, whose
      * post-save semantics (cache fill, read-model warm-up) are a lie
      * for a row that was just deleted. Their pending events are
@@ -1630,7 +1681,7 @@ type AggregateClass<TAgg> = (abstract new (...args: any[]) => TAgg) | (Function
  * `markPersisted`) is keyed on JavaScript object identity.
  *
  * Storage is two-level (per-type stores created lazily), so
- * `Restaurant:123` and `Booking:123` can never collide — the type key
+ * `Restaurant:123` and `Booking:123` can never collide: the type key
  * is the aggregate CLASS, not the id alone and not a name string.
  *
  * Repository read-path contract:
@@ -1653,7 +1704,7 @@ type AggregateClass<TAgg> = (abstract new (...args: any[]) => TAgg) | (Function
  *
  * Deletion is final within an operation: {@link delete} removes the
  * entry AND records a tombstone, so a later {@link set} of the same
- * type+id throws `AggregateDeletedError` — a second instance of a
+ * type+id throws `AggregateDeletedError`: a second instance of a
  * deleted aggregate can never sneak back into the unit of work, even
  * through a repository whose row delete is deferred.
  *
@@ -1664,6 +1715,7 @@ type AggregateClass<TAgg> = (abstract new (...args: any[]) => TAgg) | (Function
 declare class IdentityMap {
     private readonly _stores;
     private readonly _deleted;
+    private readonly _pendingAtRegistration;
     /** The cached instance for type+id, or `undefined` (also after {@link delete}). */
     get<TAgg>(type: AggregateClass<TAgg>, id: Id<string>): TAgg | undefined;
     /** Whether an instance is registered for type+id (false after {@link delete}). */
@@ -1671,7 +1723,7 @@ declare class IdentityMap {
     /**
      * Whether type+id was {@link delete}d in this unit of work. The
      * read path checks this BEFORE hydrating and returns `null`, so
-     * "deleted in this operation" reads uniformly as not-found —
+     * "deleted in this operation" reads uniformly as not-found,
      * regardless of whether the repository's physical delete already
      * removed the row or is deferred within the transaction. Without
      * the check, a read-only probe of a deleted aggregate would crash
@@ -1693,6 +1745,15 @@ declare class IdentityMap {
      *   the operation.
      */
     set<TAgg>(type: AggregateClass<TAgg>, id: Id<string>, aggregate: TAgg): void;
+    /**
+     * Registered instances that have recorded MORE pending events than they
+     * carried when first registered (loaded). Used by the unit of work's
+     * end-of-run guard: an aggregate that gained events after load but was
+     * never enrolled would silently drop them. A read-only load, or a
+     * reconstitution that already carried events, shows no increase and is
+     * not reported.
+     */
+    instancesWithNewPendingEvents(): unknown[];
     /**
      * Removes the entry for type+id and records a tombstone: subsequent
      * {@link get} / {@link has} report absence, and a subsequent
@@ -1748,20 +1809,23 @@ declare class TransactionClosedError extends BaseError<"TransactionClosedError">
 }
 /**
  * The unit of work failed AFTER the work callback completed
- * successfully: during the event harvest, the outbox write, or the
- * transaction commit itself. The kit cannot see inside
- * `TransactionScope.transactional`, so these three are deliberately
- * one error class - the underlying failure is attached as `cause`.
+ * successfully, at the persistence boundary: the outbox write or the
+ * transaction commit itself rejected. The kit cannot see inside
+ * `TransactionScope.transactional`, so these are deliberately one error
+ * class; the underlying failure is attached as `cause`.
  *
  * `InfrastructureError`: the business logic ran to completion; the
  * persistence boundary failed. The transaction rolled back (or never
  * committed), no aggregate was marked persisted, and pending events
- * survive on the aggregates — the operation left no partial state
- * behind. **Whether a retry helps depends on the cause**: a commit-
- * time serialization failure is transient, but `withCommit`'s harvest
- * guard (an event missing `aggregateId` / `aggregateType` — a
- * programming bug) also lands here and will fail deterministically on
- * every retry. Inspect the `cause` before routing into retry logic.
+ * survive on the aggregates; the operation left no partial state behind.
+ * A `CommitError` is the **potentially transient** post-completion
+ * failure (a commit-time serialization failure is the classic case), so
+ * it is the one a retrying caller should consider re-running. The
+ * deterministic post-completion failure, a harvest-guard violation (an
+ * event missing `aggregateId` / `aggregateType`, or an `aggregateVersion`
+ * ahead of the commit version), is a programming bug and surfaces as
+ * {@link EventHarvestError} instead, which does NOT extend
+ * `InfrastructureError`, so it stays out of retry paths by construction.
  */
 declare class CommitError extends InfrastructureError<"CommitError"> {
     constructor(cause: unknown);
@@ -1836,8 +1900,8 @@ interface UnitOfWorkSession<Evt extends AnyDomainEvent = AnyDomainEvent> {
 }
 /**
  * What the work callback receives: repositories already bound to the
- * live transaction, the enrollment session, and — deliberately named to
- * look like the escape hatch it is — the raw transaction handle.
+ * live transaction, the enrollment session, and, deliberately named to
+ * look like the escape hatch it is, the raw transaction handle.
  *
  * All members throw {@link TransactionClosedError} once `run()` has
  * settled; do not let the context escape the callback.
@@ -1845,17 +1909,36 @@ interface UnitOfWorkSession<Evt extends AnyDomainEvent = AnyDomainEvent> {
 interface UnitOfWorkContext<TCtx, TRepos, Evt extends AnyDomainEvent = AnyDomainEvent> {
     readonly repositories: TRepos;
     /**
-     * **Escape hatch — you are leaving the unit of work's guarantees.**
+     * **Escape hatch: you are leaving the unit of work's guarantees.**
      * A write issued on the raw handle bypasses the repository contract,
      * enrollment (its aggregate's events are NOT harvested unless you
      * also call `session.enrollSaved`), and the identity map (a later
-     * `getById` of the same aggregate hydrates a SECOND instance —
+     * `getById` of the same aggregate hydrates a SECOND instance:
      * double harvest, double `markPersisted`). Use it only for writes no
      * repository covers, pair it with manual enrollment, and prefer
      * adding a repository method whenever one could exist.
      */
     readonly rawTransaction: TCtx;
     readonly session: UnitOfWorkSession<Evt>;
+    /**
+     * The cooperative-cancellation signal passed to {@link UnitOfWork.run},
+     * or `undefined` if none was given. Poll `signal?.aborted` between
+     * steps of a long operation and throw `signal.reason` to bail out; the
+     * throw rolls the unit of work back like any other callback error. The
+     * kit does not interrupt an in-flight query for you: actual query
+     * cancellation depends on the `TransactionScope` honoring the signal.
+     */
+    readonly signal?: AbortSignal;
+}
+/** Options for a single {@link UnitOfWork.run} call. */
+interface RunOptions {
+    /**
+     * Cooperative-cancellation signal. If already aborted, `run()` rejects
+     * with the signal's `reason` before opening a transaction. Otherwise it
+     * is exposed on the context (poll `context.signal`) and forwarded to the
+     * `TransactionScope`. Use `AbortSignal.timeout(ms)` for a deadline.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * Per-repository factory map: for each key of `TRepos`, a function
@@ -1958,7 +2041,7 @@ declare class UnitOfWork<Evt extends AnyDomainEvent, TCtx, TRepos extends Record
      * run the post-commit lifecycle (markPersisted, publish) for every
      * enrolled aggregate. Returns the callback's result.
      */
-    run<R>(work: (context: UnitOfWorkContext<TCtx, TRepos, Evt>) => Promise<R>): Promise<R>;
+    run<R>(work: (context: UnitOfWorkContext<TCtx, TRepos, Evt>) => Promise<R>, options?: RunOptions): Promise<R>;
     private buildRepositories;
 }
 
@@ -1979,6 +2062,30 @@ declare class UnitOfWork<Evt extends AnyDomainEvent, TCtx, TRepos extends Record
  * ```
  */
 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.
@@ -2002,7 +2109,7 @@ type QueryTypeMap = Record<string, unknown>;
  * // result: Result<unknown, string>
  * ```
  */
-interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
+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.
@@ -2012,8 +2119,8 @@ interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
      */
     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>>;
+    }>(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.
@@ -2080,8 +2187,10 @@ interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
  * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
  * ```
  */
-declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQueryBus<TMap> {
+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 & {
@@ -2089,8 +2198,8 @@ declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQue
     }>(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>>;
+    }>(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"]]>;
@@ -2151,7 +2260,7 @@ declare class EventBusImpl<Evt extends AnyDomainEvent> implements EventBus<Evt>
  * For production, back the outbox with a transactional store so the
  * outbox row participates in the same transaction as the aggregate
  * write (see `TransactionScope` + `withCommit`). This class lives in
- * memory only: events are lost on process restart — and, sharper:
+ * memory only: events are lost on process restart. Sharper still:
  * events `add()`ed inside a transaction that later rolls back are NOT
  * removed (the Map knows nothing about your scope's rollback). Tests
  * that assert rollback purity need an outbox that participates in the
@@ -2190,8 +2299,8 @@ declare class InMemoryOutbox<Evt extends AnyDomainEvent> implements Outbox<Evt>
  * the deleted-cannot-be-resaved gate. Ids stay branded (`TId extends
  * Id<string>`) end-to-end.
  *
- * Implementing this interface is optional — the `UnitOfWork` registry
- * is structurally typed — but it is the single source of truth the
+ * Implementing this interface is optional (the `UnitOfWork` registry
+ * is structurally typed), but it is the single source of truth the
  * guide's examples and the repository contract test suite
  * (`@shirudo/ddd-kit/testing`, whose `ContractRepository` is the
  * minimal structural subset of this shape) are written against.
@@ -2377,6 +2486,94 @@ interface IQueryableRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<
     find(filter: TFilter): Promise<TAgg[]>;
 }
 
+/**
+ * Tuning for {@link RetryingTransactionScope}. All fields are optional;
+ * the defaults suit optimistic-concurrency retries (a handful of writers
+ * racing one aggregate), not high-fan-out hot-row contention.
+ */
+interface RetryPolicy {
+    /** Total tries, including the first. Default `3` (1 initial + 2 retries). */
+    maxAttempts?: number;
+    /** First backoff delay; doubles each retry. Default `50`ms. */
+    baseDelayMs?: number;
+    /** Ceiling for the backoff delay. Default `1000`ms. */
+    maxDelayMs?: number;
+    /**
+     * Classifier deciding whether an error is worth retrying. Default
+     * {@link someChainRetryable} (walks the cause chain for the loose
+     * `retryable === true` marker, so `ConcurrencyConflictError` matches
+     * even when an adapter wraps it). Override to add driver-specific
+     * serialization codes (Postgres 40001, MySQL 1213, SQLite SQLITE_BUSY)
+     * that your adapter has not mapped to a retryable kit error.
+     */
+    isRetryable?: (error: unknown) => boolean;
+    /** Observer fired before each backoff wait (logging / metrics). */
+    onRetry?: (info: {
+        attempt: number;
+        error: unknown;
+        delayMs: number;
+    }) => void;
+    /** Backoff wait. Default an abortable `setTimeout`. Injectable for tests. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Jitter source in `[0, 1)`. Default `Math.random`. Injectable for tests. */
+    random?: () => number;
+}
+/**
+ * Backoff delay for the attempt that just failed (1-based): exponential
+ * (`baseDelayMs * 2^(attempt-1)`), capped at `maxDelayMs`, then a +/-20%
+ * jitter band (`* random(0.8, 1.2)`) applied and re-clamped to the cap.
+ * Pure and deterministic given `random`. Result is never negative.
+ *
+ * @internal Exported only so it can be unit-tested directly; not part of
+ * the supported public API and may change without a major version.
+ */
+declare function computeBackoffDelay(attempt: number, opts: {
+    baseDelayMs: number;
+    maxDelayMs: number;
+    random: () => number;
+}): number;
+/**
+ * A {@link TransactionScope} that retries its inner scope on transient
+ * failures with exponential backoff and jitter. Compose it transparently:
+ *
+ * ```ts
+ * const scope = new RetryingTransactionScope(drizzleScope, { maxAttempts: 5 });
+ * const uow = new UnitOfWork({ scope, outbox, repositories });
+ * ```
+ *
+ * **Retries the transaction only.** Each attempt re-invokes the inner
+ * `transactional` with a fresh transaction, so the work callback must be
+ * reload-safe (load aggregates via `getById` inside it, never capture an
+ * aggregate from a previous attempt) and free of non-transactional side
+ * effects before commit. `withCommit` publishes AFTER the commit, so the
+ * in-process publish is outside the retried region and never duplicated;
+ * publish failures are handled by `onPublishError`, not retried here.
+ *
+ * **Classification is by error, not by guesswork.** Only errors the
+ * `isRetryable` predicate accepts are retried; everything else (a
+ * `DomainError`, `EventHarvestError`, `UnenrolledChangesError`,
+ * `DuplicateAggregateError`, a non-Error throw) surfaces immediately.
+ * After `maxAttempts` the last error is rethrown unchanged, so a caller
+ * can still match `ConcurrencyConflictError` and map it to HTTP 409.
+ *
+ * **Cancellation.** The `AbortSignal` from `transactional` options is
+ * checked before each attempt and aborts the backoff wait, so an
+ * `AbortSignal.timeout(ms)` bounds total elapsed time (there is
+ * deliberately no separate max-elapsed knob).
+ */
+declare class RetryingTransactionScope<TCtx> implements TransactionScope<TCtx> {
+    private readonly inner;
+    private readonly maxAttempts;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly isRetryable;
+    private readonly sleep;
+    private readonly random;
+    private readonly onRetry?;
+    constructor(inner: TransactionScope<TCtx>, policy?: RetryPolicy);
+    transactional<T>(fn: (ctx: TCtx) => Promise<T>, options?: TransactionalOptions): Promise<T>;
+}
+
 type VO<T> = Readonly<T>;
 /**
  * Deep freezes an object and all its nested properties recursively, then
@@ -2649,4 +2846,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, RollbackError, TransactionClosedError, type TransactionScope, UnitOfWork, type UnitOfWorkContext, type UnitOfWorkDeps, type UnitOfWorkSession, type VO, ValueObject, Version, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, removeEntityById, replaceEntityById, sameEntity, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withCommit };
+export { type AggregateClass, type AggregateConfig, AggregateRoot, AggregateSnapshot, AnyDomainEvent, type Command, CommandBus, type CommandBusOptions, 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 QueryBusOptions, 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 };