@shirudo/ddd-kit 1.2.0 → 1.3.0

package/README.md

@@ -17,9 +17,9 @@ Composable TypeScript toolkit for tactical Domain-Driven Design. Ships the canon
 - **Domain Events:** typed, deeply frozen, carry metadata for traceability and schema evolution.
 - **Repositories:** technology-agnostic persistence ports with an Identity-Map contract and OCC.
 - **CQRS:** zero-config in-memory `CommandBus` / `QueryBus`, plus `CommandHandler` / `QueryHandler` types for external brokers.
-- **Unit of Work:** opt-in `UnitOfWork` facade with tx-bound repositories, repository-side enrollment, a per-operation Identity Map, and aggregate-level dirty tracking (`changedKeys` / `hasChanges`) for partial writes — honestly speaking: a transaction coordinator with registration and Identity Map; writes stay explicit by design (no auto-flush).
+- **Unit of Work:** opt-in `UnitOfWork` facade with tx-bound repositories, repository-side enrollment, a per-operation Identity Map, and aggregate-level dirty tracking (`changedKeys` / `hasChanges`) for partial writes. Honestly speaking: a transaction coordinator with registration and Identity Map; writes stay explicit by design (no auto-flush).
 - **Outbox:** `withCommit` harvests pending events inside the transaction, stamps them with the aggregate's commit version, and publishes them atomically.
-- **Repository contract tests:** `@shirudo/ddd-kit/testing` ships the suite every adapter must pass — OCC is a testable contract, not a documented pattern.
+- **Repository contract tests:** `@shirudo/ddd-kit/testing` ships the suite every adapter must pass: OCC is a testable contract, not a documented pattern.
 - **Result-first boundary:** a typed error hierarchy on [`@shirudo/base-error`](https://www.npmjs.com/package/@shirudo/base-error) and `Result` from [`@shirudo/result`](https://www.npmjs.com/package/@shirudo/result); `voValidated` collects field violations and renders RFC 9457 via the opt-in `@shirudo/ddd-kit/http` entry.
 
 ## Installation

package/dist/{aggregate-DclYgG_D.d.ts → aggregate-BGdgvqKh.d.ts}

@@ -104,6 +104,60 @@ declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
     readonly eventType: string;
     constructor(eventType: string, cause?: unknown);
 }
+/**
+ * Thrown by `withCommit` when an event harvested from an aggregate cannot
+ * be safely committed: it is missing `aggregateId` / `aggregateType`
+ * (downstream routing would break), or it carries a pre-set
+ * `aggregateVersion` AHEAD of the aggregate's commit version (a leaked or
+ * copied fixture that would advance consumer idempotency watermarks past
+ * real history). Both are programming bugs in how the aggregate recorded
+ * the event, deterministic, and fail identically on every retry.
+ *
+ * Deliberately **not** an {@link InfrastructureError} (same reasoning as
+ * {@link MissingHandlerError}): the failure happens after the work
+ * callback completed, but it is NOT transient. A `catch (e instanceof
+ * InfrastructureError)` retry handler, or a retrying `TransactionScope`,
+ * must NOT mask it or loop on it forever; it should crash loud so the
+ * recordEvent / createDomainEvent misuse surfaces in development. This is
+ * why `withCommit` throws it directly and `UnitOfWork.run` passes it
+ * through unchanged instead of wrapping it in `CommitError`.
+ */
+declare class EventHarvestError extends BaseError<"EventHarvestError"> {
+    /** The `type` of the offending event, for programmatic routing. */
+    readonly eventType?: string | undefined;
+    constructor(message: string, 
+    /** The `type` of the offending event, for programmatic routing. */
+    eventType?: string | undefined);
+}
+/**
+ * Thrown at the end of a `UnitOfWork.run` when an aggregate that was
+ * loaded into the identity map during the operation carries unflushed
+ * `pendingEvents` but was never enrolled (no `session.enrollSaved`, and
+ * not deleted). The almost-certain cause is a repository `save()` that
+ * forgot to call `enrollSaved`, or a use case that recorded events on a
+ * loaded aggregate and never saved it. Without this guard those events
+ * would be silently dropped: never harvested into the outbox, never
+ * published.
+ *
+ * Deliberately **not** an `InfrastructureError` (same posture as
+ * {@link MissingHandlerError}): a programming bug that must crash loud,
+ * not be absorbed by a generic infrastructure-error handler. The throw
+ * happens inside the transaction, so the unit of work rolls back and
+ * leaves no partial state.
+ *
+ * **Scope of the guard.** A best-effort runtime safety net, not a proof.
+ * It only sees aggregates the identity map knows about (those loaded via
+ * `getById`), and detects new events by comparing the pending-event COUNT
+ * at load against commit, which assumes the kit's append-only event model
+ * (so it cannot see events that were recorded and then cleared within the
+ * same run). A freshly *created* aggregate that was never enrolled is
+ * invisible to the kit. The repository contract test suite remains the
+ * full mitigation. See the Unit of Work guide.
+ */
+declare class UnenrolledChangesError extends BaseError<"UnenrolledChangesError"> {
+    readonly aggregateId: string;
+    constructor(aggregateId: string);
+}
 /**
  * Thrown when an aggregate that was deleted within the current unit of
  * work is saved or re-registered again in the same operation: by
@@ -172,7 +226,7 @@ declare class DuplicateAggregateError extends InfrastructureError<"DuplicateAggr
  *
  * **Retry means a FRESH unit of work** (a new `UnitOfWork.run()` /
  * `withCommit` invocation): reload, re-apply, save. Do NOT catch this
- * inside the same `run()` callback and continue — the failed aggregate
+ * inside the same `run()` callback and continue: the failed aggregate
  * is already enrolled (its events would be committed for a write that
  * never happened) and the identity map still serves the same stale
  * instance to any in-place "reload".
@@ -379,7 +433,7 @@ interface EventMetadata {
  * transport concerns the outbox needs (`aggregateId`, `aggregateType`,
  * `aggregateVersion`, `metadata`). That is the line: further transport
  * fields (partition keys, tenancy, schema URNs, …) belong in an outbox
- * envelope / `metadata`, not on the domain event — the next first-class
+ * envelope / `metadata`, not on the domain event: the next first-class
  * transport field forces an `OutboxMessage` envelope port instead.
  *
  * @template T - The event type name (e.g., "OrderCreated")
@@ -422,7 +476,7 @@ interface DomainEvent<T extends string, P = void> {
      * Required for safe schema migration in event-sourced systems.
      * Use 1 for the initial schema version.
      *
-     * **NOT the aggregate's version** — that is
+     * **NOT the aggregate's version**: that is
      * {@link aggregateVersion}. The two are deliberately distinct
      * fields: this one says "which shape does the payload have"
      * (upcasting), the other says "which state revision of the
@@ -435,7 +489,7 @@ interface DomainEvent<T extends string, P = void> {
      * `withCommit` at the harvest boundary (all events of one aggregate
      * in one commit share it; their relative order within the commit is
      * the harvest order), or set manually via
-     * `CreateDomainEventOptions.aggregateVersion` — a pre-set value is
+     * `CreateDomainEventOptions.aggregateVersion`; a pre-set value is
      * never overwritten.
      *
      * Consumers use it for ordering ("apply projections up to aggregate
@@ -486,8 +540,8 @@ interface CreateDomainEventOptions {
     version?: number;
     /**
      * Pre-set the producing aggregate's version (see
-     * `DomainEvent.aggregateVersion`). Normally left unset — `withCommit`
-     * stamps it at the harvest boundary with the commit version — but
+     * `DomainEvent.aggregateVersion`). Normally left unset (`withCommit`
+     * stamps it at the harvest boundary with the commit version), but
      * useful for replay fixtures and events constructed outside an
      * aggregate. A pre-set value is never overwritten by the harvest.
      */
@@ -659,4 +713,4 @@ declare function sameVersion<TId extends Id<string>>(a: {
     version: Version;
 }): boolean;
 
-export { type AnyDomainEvent as A, type CreateDomainEventOptions as C, DomainError as D, type EventIdFactory as E, type IAggregateRoot as I, MissingHandlerError as M, type Version as V, type Id as a, type AggregateSnapshot as b, type IEventSourcedAggregate as c, InfrastructureError as d, setEventIdFactory as e, type ClockFactory as f, setClockFactory as g, withClockFactory as h, resetClockFactory as i, type EventMetadata as j, type DomainEvent as k, createDomainEvent as l, createDomainEventWithMetadata as m, copyMetadata as n, mergeMetadata as o, AggregateDeletedError as p, AggregateNotFoundError as q, resetEventIdFactory as r, sameVersion as s, DuplicateAggregateError as t, ConcurrencyConflictError as u, type IdGenerator as v, withEventIdFactory as w };
+export { type AnyDomainEvent as A, type CreateDomainEventOptions as C, DomainError as D, type EventIdFactory as E, type IAggregateRoot as I, MissingHandlerError as M, UnenrolledChangesError as U, type Version as V, type Id as a, type AggregateSnapshot as b, type IEventSourcedAggregate as c, InfrastructureError as d, setEventIdFactory as e, type ClockFactory as f, setClockFactory as g, withClockFactory as h, resetClockFactory as i, type EventMetadata as j, type DomainEvent as k, createDomainEvent as l, createDomainEventWithMetadata as m, copyMetadata as n, mergeMetadata as o, EventHarvestError as p, AggregateDeletedError as q, resetEventIdFactory as r, sameVersion as s, AggregateNotFoundError as t, DuplicateAggregateError as u, ConcurrencyConflictError as v, withEventIdFactory as w, type IdGenerator as x };

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-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 { 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
@@ -1386,8 +1386,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 +1483,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 +1525,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 +1541,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 +1653,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 +1676,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 +1687,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 +1695,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 +1717,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 +1781,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 +1872,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 +1881,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 +2013,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;
 }
 
@@ -2151,7 +2206,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 +2245,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 +2432,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 +2792,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 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 };