@shirudo/ddd-kit 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -1,572 +1,10 @@
+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';
 export { DeepOmitOptions, Key, PathSegment, deepEqual, deepEqualExcept, deepOmit } from './utils.js';
 
-/**
- * Branded string ID. `Tag` carries the aggregate / entity name so two ids
- * with different tags are not assignable to each other even though both
- * are strings at runtime.
- *
- * @example
- * ```ts
- * type UserId = Id<"UserId">;
- * type OrderId = Id<"OrderId">;
- *
- * const u = "user-1" as UserId;
- * const o: OrderId = u; // ❌ compile error
- * ```
- */
-type Id<Tag extends string> = string & {
-    readonly __brand: Tag;
-};
-/**
- * Produces fresh ids of a single, fixed tag. The tag is bound at the
- * generator type — `IdGenerator<"UserId">.next()` returns `Id<"UserId">`
- * with no caller-side generic to abuse.
- *
- * **Your factory must produce unique ids under concurrent calls.**
- * The kit makes no attempt to dedupe or detect collisions — a collision
- * silently overwrites earlier rows (under unique-key constraints) or
- * silently aliases two different entities (without them). Safe choices:
- * `crypto.randomUUID()` (UUIDv4, the default for events), ULID, UUIDv7,
- * KSUID — all collision-resistant by design. Unsafe choices: `Date.now()`
- * alone (duplicates within the same millisecond), a process-local
- * counter without persistence (resets to 1 on restart, collides with
- * prior runs), a sequential id derived from non-atomic state.
- *
- * @example
- * ```ts
- * import { ulid } from "ulid";
- *
- * const userIds: IdGenerator<"UserId"> = { next: () => ulid() as Id<"UserId"> };
- * const id = userIds.next(); // Id<"UserId">
- * ```
- *
- * The previous shape (`IdGenerator { next<T extends string>(): Id<T> }`)
- * let callers pick `T` themselves — `gen.next<"AnyTag">()` typechecked
- * even when the generator produced different-tag ids, silently defeating
- * the brand.
- */
-interface IdGenerator<Tag extends string> {
-    next: () => Id<Tag>;
-}
-
-/**
- * Abstract base for **domain-invariant violations**. Domain methods
- * (aggregates, entity validation hooks, value-object constructors)
- * throw `DomainError`-derived exceptions when a business rule is
- * violated. Consumers derive their own concrete errors — e.g.
- * `class OrderAlreadyShippedError extends DomainError<"OrderAlreadyShippedError"> {}` —
- * for `instanceof`-style catching at the App-Service boundary, where
- * they typically map to HTTP 400 / business-rule responses.
- *
- * The library itself does **not** ship any concrete `DomainError`
- * subclass — the kit can't know your invariants.
- *
- * Extends `BaseError<Name>`; see `@shirudo/base-error` for the inherited
- * surface (timestamps, cause chains, `toJSON()`, `getUserMessage()`,
- * `isRetryable`, …).
- */
-declare abstract class DomainError<Name extends string = string> extends BaseError<Name> {
-}
-/**
- * Abstract base for **infrastructure / persistence failures** that the
- * App-Service can recover from — typically by retrying, by returning
- * HTTP 404 / 409, or by surfacing a "please try again" UX. These are
- * not domain-invariant violations (the business rules were not
- * broken); they describe race conditions and missing rows at the
- * storage boundary.
- *
- * Library-internal concrete subclasses: {@link AggregateNotFoundError},
- * {@link ConcurrencyConflictError}.
- */
-declare abstract class InfrastructureError<Name extends string = string> extends BaseError<Name> {
-}
-/**
- * Thrown by `EventSourcedAggregate.apply()` when no handler is
- * registered for the event's type. This means the aggregate's subclass
- * forgot to add an entry to its `handlers` map — a programming /
- * configuration bug, not a domain or infrastructure failure.
- *
- * Deliberately **not** on `DomainError` or `InfrastructureError` —
- * a generic `catch (e instanceof DomainError)` handler at the App
- * layer must not mask a forgotten handler; this should crash loud and
- * fail the calling Use Case so the bug surfaces in development. The
- * replay methods (`loadFromHistory`, `restoreFromSnapshotWithEvents`)
- * also let it propagate uncaught instead of wrapping it in `Result.Err`.
- *
- * Use `isBaseError(e)` from `@shirudo/base-error` to detect
- * "any structured error from the kit or any other BaseError-using
- * library" at the App boundary.
- */
-declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
-    readonly eventType: string;
-    constructor(eventType: string, cause?: unknown);
-}
-/**
- * Thrown by `IRepository.getByIdOrFail()` when an aggregate with the
- * given id does not exist. `InfrastructureError` because the storage
- * boundary, not a business rule, decided the row is absent. Use the
- * nullable variant `getById()` if "not found" is a valid outcome.
- *
- * Accepts an optional `cause` so a `Repository.save()` implementation
- * can wrap a lower-level "row not found" / driver-level error without
- * losing context. Cause-chain helpers (`getRootCause`,
- * `findInCauseChain`) from `@shirudo/base-error` traverse the chain.
- *
- * Not retryable — retrying won't make the row appear.
- */
-declare class AggregateNotFoundError extends InfrastructureError<"AggregateNotFoundError"> {
-    readonly aggregateType: string;
-    readonly id: string;
-    constructor(aggregateType: string, id: string, cause?: unknown);
-}
-/**
- * Thrown by `IRepository.save()` when the aggregate's expected version
- * does not match the version currently persisted — i.e. another writer
- * updated the aggregate concurrently. The canonical optimistic-
- * concurrency signal; the App-Service typically reloads, re-applies
- * the use case, and retries, or surfaces HTTP 409 to the caller.
- *
- * `InfrastructureError` because the persistence layer (not a domain
- * rule) detects the race. Marks itself as `retryable: true` so the
- * `isRetryable` predicate from `@shirudo/base-error` picks it up.
- */
-declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyConflictError"> {
-    readonly aggregateType: string;
-    readonly aggregateId: string;
-    readonly expectedVersion: number;
-    readonly actualVersion: number;
-    /**
-     * Marks this error as retryable so `isRetryable(err)` returns
-     * true. The canonical OCC pattern is to reload the aggregate, re-apply
-     * the use case, and retry on this exception.
-     */
-    readonly retryable: true;
-    constructor(aggregateType: string, aggregateId: string, expectedVersion: number, actualVersion: number, cause?: unknown);
-}
-
-/**
- * Factory function producing a fresh, unique event identifier for each call.
- *
- * The library ships a default that uses Web Crypto `crypto.randomUUID()`
- * (works on Node 19+, modern browsers in secure contexts, Deno, Bun,
- * Cloudflare Workers, Vercel Edge, and any runtime that implements Web
- * Crypto). Note that `crypto.randomUUID()` returns **UUID v4** (purely
- * random) — for production event stores prefer a **time-ordered** id
- * format (UUID v7 / ULID / KSUID) so B-tree indexes on the eventId
- * column stay clustered and `ORDER BY eventId` matches creation order.
- * Swap one in via `setEventIdFactory(() => uuidv7())` or `() => ulid()`.
- */
-type EventIdFactory = () => string;
-/**
- * Replaces the global event-id factory used by `createDomainEvent` and
- * `createDomainEventWithMetadata`. Call once during application bootstrap,
- * for example:
- *
- * ```ts
- * import { ulid } from "ulid";
- * import { setEventIdFactory } from "@shirudo/ddd-kit";
- *
- * setEventIdFactory(() => ulid());
- * ```
- *
- * The per-call `options.eventId` override always wins over this factory.
- *
- * **Module-scoped — last setter wins.** The factory lives as a single
- * module variable; importing two libraries that both call this races on
- * load order, and parallel test workers will see each other's factory.
- * For test isolation and short-lived contexts prefer
- * {@link withEventIdFactory}; for multi-tenant request isolation
- * (e.g. one factory per tenant in a single Worker invocation) **prefer
- * the per-call `options.eventId`** instead of mutating the global. Same
- * caveat applies to `setClockFactory`.
- */
-declare function setEventIdFactory(factory: EventIdFactory): void;
-/**
- * Scoped variant of {@link setEventIdFactory}: installs `factory`,
- * runs `fn`, then restores the previous factory in a `finally` block —
- * so the restoration happens even if `fn` throws. Safe for parallel
- * tests and for synchronous request handlers that need a tenant-
- * specific factory without polluting the global.
- *
- * **Synchronous-only — enforced at runtime.** If `fn` returns a
- * thenable (a `Promise` or any object with a `then` method), the
- * helper throws *before* returning the value to the caller. This
- * catches the async-misuse footgun where the factory would be
- * restored before the awaited body of `fn` runs, leaving the awaited
- * code reading the previous factory. For async scoping across `await`
- * boundaries, use `AsyncLocalStorage` — out of scope for this helper;
- * build it on top if you need it.
- *
- * Composes by nesting: an inner `withEventIdFactory` restores back to
- * the outer's factory; the outer restores to the original.
- *
- * **When to prefer the per-call `options.eventId` instead.** If you're
- * constructing a single event and want full control over its id,
- * passing `{ eventId: "..." }` to `createDomainEvent` is the strongest
- * isolation — it bypasses the factory mechanism entirely, no global
- * mutation, no scope to manage. Reach for `withEventIdFactory` when
- * the events are constructed deep inside domain methods you can't
- * thread an explicit id through (typical test scenario), or when many
- * events in a scope should share the same factory.
- *
- * @example
- * ```ts
- * // In a vitest test:
- * it("emits deterministic ids", () => {
- *   withEventIdFactory(() => "evt-fixed", () => {
- *     const e = createDomainEvent("X", { v: 1 });
- *     expect(e.eventId).toBe("evt-fixed");
- *   });
- *   // Outside the callback the default crypto.randomUUID is restored,
- *   // even if the body had thrown.
- * });
- * ```
- */
-declare function withEventIdFactory<T>(factory: EventIdFactory, fn: () => T): T;
-/**
- * Restores the default event-id factory (`crypto.randomUUID()`).
- * Intended for use in test `afterEach` hooks.
- */
-declare function resetEventIdFactory(): void;
-/**
- * Clock function producing a fresh `Date` for each call. The library
- * defaults to `() => new Date()`; override globally via `setClockFactory`
- * for deterministic event-sourcing tests, time-travel debugging, or any
- * scenario where `occurredAt` must be reproducible.
- */
-type ClockFactory = () => Date;
-/**
- * Replaces the global clock factory used by `createDomainEvent` and
- * `createDomainEventWithMetadata`. Call once during application bootstrap
- * (or per-test in deterministic test suites):
- *
- * ```ts
- * import { setClockFactory } from "@shirudo/ddd-kit";
- *
- * setClockFactory(() => new Date("2026-01-01T00:00:00Z"));
- * ```
- *
- * The per-call `options.occurredAt` override always wins over this
- * factory. Symmetric to `setEventIdFactory`.
- *
- * Module-scoped — see {@link 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 — same constraints (and same runtime thenable
- * guard) as {@link withEventIdFactory}.
- *
- * **When to prefer the per-call `options.occurredAt` instead.** Same
- * trade-off as {@link 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;
-/**
- * Metadata associated with a domain event for traceability and correlation.
- * Used in event-driven architectures to track event flow across services.
- */
-interface EventMetadata {
-    /**
-     * Correlation ID for tracing events across multiple services/components.
-     * Typically used to group related events in a distributed system.
-     */
-    correlationId?: string;
-    /**
-     * Causation ID referencing the event or command that caused this event.
-     * Used to build event chains and understand causality.
-     */
-    causationId?: string;
-    /**
-     * User ID of the person or system that triggered the event.
-     */
-    userId?: string;
-    /**
-     * Source service or component that produced the event.
-     */
-    source?: string;
-    /**
-     * Additional custom metadata fields.
-     * Allows extensibility for domain-specific metadata.
-     */
-    [key: string]: unknown;
-}
-/**
- * Domain Event represents something meaningful that happened in the domain.
- * Events are immutable and carry information about what occurred.
- *
- * @template T - The event type name (e.g., "OrderCreated")
- * @template P - The event payload type
- */
-interface DomainEvent<T extends string, P = void> {
-    /**
-     * Unique identifier for this specific event instance. Used by idempotent
-     * consumers, outbox dispatch tracking, and as the target of
-     * `metadata.causationId`. Defaults to `crypto.randomUUID()` if not
-     * supplied.
-     */
-    eventId: string;
-    /**
-     * The type of the event, used for routing and handling.
-     */
-    type: T;
-    /**
-     * Identifier of the aggregate that produced the event. Optional at the
-     * library level — set it whenever the producing aggregate is known so
-     * downstream subscribers, outboxes, and projections can scope by entity.
-     */
-    aggregateId?: string;
-    /**
-     * Name of the aggregate type that produced the event (e.g. "Order").
-     * Pairs with `aggregateId` to fully qualify the source aggregate.
-     */
-    aggregateType?: string;
-    /**
-     * The event payload containing the domain data. The field is always
-     * present; its value is `undefined` when `P` is `void`.
-     */
-    payload: P;
-    /**
-     * Timestamp when the event occurred.
-     */
-    occurredAt: Date;
-    /**
-     * Event schema version for handling schema evolution.
-     * Required for safe schema migration in event-sourced systems.
-     * Use 1 for the initial schema version.
-     */
-    version: number;
-    /**
-     * Optional metadata for traceability, correlation, and auditing.
-     * Includes correlationId, causationId, userId, source, and custom fields.
-     */
-    metadata?: EventMetadata;
-}
-/**
- * Upper-bound alias for "any `DomainEvent` shape". Use as a generic
- * constraint when a type parameter should accept any concrete event
- * union. The `unknown` payload is the upper bound — concrete unions
- * still narrow via `Extract<Evt, { type: K }>` at the use-site.
- */
-type AnyDomainEvent = DomainEvent<string, unknown>;
-/**
- * Shared option bag for the `createDomainEvent*` factories.
- */
-interface CreateDomainEventOptions {
-    /**
-     * Override for the auto-generated `eventId`. Pass an existing id (for
-     * replay, tests, or deterministic event sourcing) instead of letting the
-     * factory call `crypto.randomUUID()`.
-     */
-    eventId?: string;
-    /**
-     * Identifier of the aggregate that produced the event.
-     */
-    aggregateId?: string;
-    /**
-     * Name of the aggregate type that produced the event.
-     */
-    aggregateType?: string;
-    /**
-     * Override for the auto-generated `occurredAt` timestamp.
-     */
-    occurredAt?: Date;
-    /**
-     * Override for the default schema version (1).
-     */
-    version?: number;
-    /**
-     * Event metadata — correlation, causation, user, source, custom fields.
-     */
-    metadata?: EventMetadata;
-}
-/**
- * Creates a domain event with default values.
- * Sets occurredAt to current date and version to 1 if not provided.
- *
- * **For aggregate-internal events, prefer `this.recordEvent(...)` on
- * `AggregateRoot` / `EventSourcedAggregate`.** That helper auto-injects
- * `aggregateId` (from `this.id`) and `aggregateType` (from the
- * aggregate's declared `aggregateType` property), which downstream
- * consumers — outbox dispatchers, projection handlers, audit logs —
- * route by. The `withCommit` harvest boundary now validates both fields
- * are present and throws if they're missing, so a direct
- * `createDomainEvent(...)` call inside an aggregate that forgets the
- * options is caught at runtime.
- *
- * Use `createDomainEvent(...)` directly for events that don't belong to
- * an aggregate: system events, integration events, configuration events,
- * test fixtures. For those, set `aggregateId` / `aggregateType` in
- * `options` if downstream consumers expect routing metadata.
- *
- * @param type - The event type
- * @param payload - The event payload
- * @param options - Optional event configuration (including `aggregateId`
- *   and `aggregateType` for routing)
- * @returns A domain event
- *
- * @example
- * ```typescript
- * const event = createDomainEvent("OrderCreated", { orderId: "123" });
- * ```
- */
-declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateDomainEventOptions): DomainEvent<T, void>;
-declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateDomainEventOptions): DomainEvent<T, P>;
-/**
- * Creates a domain event with metadata for traceability.
- * Convenience function for creating events with correlation and causation IDs.
- *
- * @example
- * ```typescript
- * const event = createDomainEventWithMetadata(
- *   "OrderCreated",
- *   { orderId: "123" },
- *   { correlationId: "corr-123", causationId: "cmd-456", userId: "user-789" }
- * );
- * ```
- */
-declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: Omit<CreateDomainEventOptions, "metadata">): DomainEvent<T, P>;
-/**
- * Copies metadata from a source event to a new event.
- * Useful for maintaining correlation chains in event-driven architectures.
- *
- * @example
- * ```typescript
- * const newEvent = createDomainEvent(
- *   "OrderShipped",
- *   { orderId: "123" },
- *   { metadata: copyMetadata(previousEvent, { causationId: previousEvent.type }) }
- * );
- * ```
- */
-declare function copyMetadata(sourceEvent: AnyDomainEvent, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
-/**
- * Merges multiple metadata objects into one.
- * Later metadata objects override earlier ones for the same keys.
- *
- * @example
- * ```typescript
- * const metadata = mergeMetadata(
- *   { correlationId: "corr-123" },
- *   { userId: "user-456" },
- *   { source: "order-service" }
- * );
- * ```
- */
-declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
-
-type Version = number & {
-    readonly __v: true;
-};
-/**
- * Snapshot of an aggregate state at a specific point in time.
- * Used for optimizing event replay by starting from a snapshot
- * instead of replaying all events from the beginning.
- *
- * @template TState - The type of the aggregate state
- */
-interface AggregateSnapshot<TState> {
-    /**
-     * The state of the aggregate at the time of the snapshot.
-     */
-    state: TState;
-    /**
-     * The version of the aggregate when the snapshot was taken.
-     */
-    version: Version;
-    /**
-     * Timestamp when the snapshot was created.
-     */
-    snapshotAt: Date;
-}
-/**
- * Public contract every Aggregate Root satisfies. Implemented by
- * `BaseAggregate` and inherited by both `AggregateRoot` and
- * `EventSourcedAggregate`. Repository implementations type their
- * `save(aggregate)` parameter against this interface rather than the
- * concrete classes, so the repo layer does not take a compile-time
- * dependency on the aggregate hierarchy.
- *
- * Full per-member documentation lives on the concrete `BaseAggregate`
- * class; the interface is intentionally terse to avoid drift.
- *
- * @template TId    - The aggregate root identifier (branded via `Id<Tag>`)
- * @template TEvent - The domain-event union, defaults to `never`
- */
-interface IAggregateRoot<TId extends Id<string>, TEvent = never> {
-    readonly id: TId;
-    readonly version: Version;
-    readonly persistedVersion: Version | undefined;
-    readonly pendingEvents: ReadonlyArray<TEvent>;
-    clearPendingEvents(): void;
-    markPersisted(version: Version): void;
-}
-/**
- * Public contract for Event-Sourced Aggregate Roots. Extends
- * `IAggregateRoot` with the replay-from-history boundary.
- *
- * @template TId    - The aggregate root identifier
- * @template TEvent - The union type of all domain events
- */
-interface IEventSourcedAggregate<TId extends Id<string>, TEvent extends AnyDomainEvent> extends IAggregateRoot<TId, TEvent> {
-    /**
-     * Reconstitutes the aggregate from an event history. Returns
-     * `Result` because event-stream corruption is an expected
-     * recoverable failure at the infrastructure boundary.
-     */
-    loadFromHistory(history: ReadonlyArray<TEvent>): Result<void, DomainError>;
-}
-/**
- * Checks if two aggregates are at the same version (same ID and version).
- * Useful for optimistic concurrency control checks.
- *
- * Note: Two aggregates with the same ID ARE the same aggregate (identity).
- * This function checks if they are at the same version — i.e., no concurrent modification.
- *
- * @example
- * ```typescript
- * const before = await repository.getById(id);
- * // ... some operations ...
- * const after = await repository.getById(id);
- *
- * if (!sameVersion(before, after)) {
- *   throw new Error("Aggregate was modified by another process");
- * }
- * ```
- */
-declare function sameVersion<TId extends Id<string>>(a: {
-    id: TId;
-    version: Version;
-}, b: {
-    id: TId;
-    version: Version;
-}): boolean;
-
 /**
  * Entity utilities and interfaces for Domain-Driven Design.
  *
@@ -625,7 +63,7 @@ declare function sameVersion<TId extends Id<string>>(a: {
  */
 
 /**
- * Functional definition of an Entity via its capability — an object is
+ * Functional definition of an Entity via its capability: an object is
  * identifiable if it has an `id`.
  *
  * `TId` is constrained to `Id<string>` so the brand discipline that
@@ -694,7 +132,7 @@ 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
+     * 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
@@ -713,7 +151,7 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
      * **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
+     * 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}.
      */
@@ -726,7 +164,7 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
      * **⚠️ Must not read subclass instance fields via `this`.** The
      * constructor calls `validateState(initialState)` BEFORE the subclass's
      * field initializers run, so `this.someField` is `undefined` at that
-     * point — a classic TypeScript/JavaScript constructor-ordering footgun.
+     * point, a classic TypeScript/JavaScript constructor-ordering footgun.
      * The `state` argument is the single source of truth; treat the method
      * as pure with respect to `this`.
      *
@@ -747,7 +185,7 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
      *
      * Plain-object and array states are shallow-copied before the freeze
      * (the caller's object stays mutable); a class-instance state is an
-     * ownership transfer and is frozen in place — see the constructor.
+     * ownership transfer and is frozen in place; see the constructor.
      *
      * @param newState - The new state
      */
@@ -917,7 +355,7 @@ declare function entityIds<TId extends Id<string>, T extends Identifiable<TId>>(
  * `recordEvent` helper that auto-injects `aggregateId` +
  * `aggregateType` on every event the aggregate emits.
  *
- * Consumers do NOT extend this class directly — extend
+ * Consumers do NOT extend this class directly; extend
  * `AggregateRoot` for state-stored aggregates or
  * `EventSourcedAggregate` for event-sourced ones. The split between
  * those two reflects the canonical Vernon §8 (state-stored) /
@@ -949,7 +387,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      *
      * The string is *the* identifier downstream consumers (outbox
      * dispatchers, projection handlers, audit logs) use to route by
-     * aggregate kind. Use the same canonical name across your system —
+     * aggregate kind. Use the same canonical name across your system;
      * matching the class name is the obvious choice, but the value
      * comes from this explicit declaration, not `constructor.name`
      * (which is fragile under minification, bundler transforms, and
@@ -965,7 +403,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      *
      * Distinct from {@link version}, which is the in-memory
      * post-mutation value. Mutations bump `_version` but never touch
-     * `_persistedVersion` — that field only moves on {@link markRestored}
+     * `_persistedVersion`; that field only moves on {@link markRestored}
      * (Post-Load) and {@link markPersisted} (Post-Save).
      */
     private _persistedVersion;
@@ -979,7 +417,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
     get pendingEvents(): ReadonlyArray<TEvent>;
     /**
      * Clears the pending-event list. Called by `markPersisted` after a
-     * successful write — the events have been handed off to the outbox
+     * successful write: the events have been handed off to the outbox
      * / event store and are no longer the aggregate's responsibility.
      */
     clearPendingEvents(): void;
@@ -991,16 +429,26 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      */
     protected bumpVersion(): void;
     /**
-     * **Lifecycle marker — Post-Load.** Syncs both `_version` and
+     * **Lifecycle marker, Post-Load.** Syncs both `_version` and
      * `_persistedVersion` to the DB-stored version. Used by
      * `reconstitute(...)` factories to assemble an in-memory aggregate
      * from a persisted row.
      *
-     * Does NOT fire {@link onPersisted} — that hook has post-save
+     * Does NOT fire {@link onPersisted}; that hook has post-save
      * semantics (metrics, audit, cache eviction), not post-load. The
      * Factory-vs-Reconstitution distinction (Vernon §11) is honoured
      * structurally: two separate markers, one for each transition.
      *
+     * **If you override this, call `super.markRestored(version)` FIRST**,
+     * same discipline as {@link markPersisted}. The marker is load-bearing
+     * twice over: it syncs `version`/`persistedVersion`, and on
+     * `AggregateRoot` it also captures the dirty-tracking baseline for
+     * `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
+     * of the broken version sync.
+     *
      * @param version - The version the row currently holds in the DB
      *
      * @example
@@ -1014,14 +462,14 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      */
     protected markRestored(version: Version): void;
     /**
-     * **Framework lifecycle method — `@sealed`.** Called by `withCommit`
+     * **Framework lifecycle method (`@sealed`).** Called by `withCommit`
      * (or by your own orchestration code, after harvesting `pendingEvents`)
      * to push the persisted version back into the in-memory aggregate and
      * clear `pendingEvents`. TypeScript has no `final` keyword, but
      * subclasses **should not** override this method directly.
      *
      * Overriding without calling `super.markPersisted(version)` silently
-     * leaks `pendingEvents` — the next `withCommit` will re-dispatch them
+     * leaks `pendingEvents`: the next `withCommit` will re-dispatch them
      * through the outbox, double-emitting events. This bug has been hit
      * in production by consumers; the {@link onPersisted} hook below is
      * the safer extension point.
@@ -1031,17 +479,17 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * runs, then add your logic afterwards.
      *
      * @param version - The version assigned by the persistence layer
-     * @see onPersisted — the safe extension point for subclasses
+     * @see onPersisted, the safe extension point for subclasses
      */
     markPersisted(version: Version): void;
     /**
-     * Subclass extension point — fires AFTER {@link markPersisted} has
+     * Subclass extension point: fires AFTER {@link markPersisted} has
      * updated the version and cleared `pendingEvents`. Override this for
      * post-persist logging, metrics, or cache-eviction without risk of
      * breaking the framework's pendingEvents cleanup.
      *
      * The default implementation is a no-op. Subclasses do NOT need to
-     * call `super.onPersisted(version)` — there is nothing in the parent
+     * call `super.onPersisted(version)`: there is nothing in the parent
      * implementation to preserve.
      *
      * **Observer contract: errors are swallowed.** `withCommit` invokes
@@ -1053,7 +501,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * **`onPersisted` deliberately receives only the version, not the
      * drained events.** Event-driven post-persist logic (aggregate-level
      * audit logging, per-event-type side effects) belongs in `EventBus`
-     * subscribers or the outbox dispatcher — that is the proper
+     * subscribers or the outbox dispatcher; that is the proper
      * Aggregate-Boundary separation. Building event-aware logic into
      * `onPersisted` couples aggregate lifecycle to event processing and
      * recreates the boundary problems Vernon's aggregate discipline is
@@ -1062,7 +510,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * **The hook must return synchronously.** `markPersisted` is `void`-
      * typed and calls `onPersisted` without `await`. TypeScript's
      * permissive `void` will accept an `async`-override returning
-     * `Promise<void>`, but the returned promise is fire-and-forget —
+     * `Promise<void>`, but the returned promise is fire-and-forget:
      * any rejection becomes an unhandled rejection and `withCommit`
      * proceeds without waiting. For asynchronous work, subscribe to the
      * relevant domain event on the `EventBus` instead; that is the
@@ -1074,7 +522,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
     /**
      * Appends a domain event to the pending list. Prefer the higher-level
      * `AggregateRoot.commit()` (state-stored) or `EventSourcedAggregate.apply()`
-     * (event-sourced) call sites — both wrap `addDomainEvent` in the
+     * (event-sourced) call sites, both of which wrap `addDomainEvent` in the
      * canonical record-AFTER-mutation order (Vernon §8). Calling
      * `addDomainEvent` directly is appropriate only when state and event
      * recording have already been decoupled deliberately (e.g. a
@@ -1082,7 +530,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      */
     protected addDomainEvent(event: TEvent): void;
     /**
-     * Creates a snapshot of the current aggregate state — the state at
+     * Creates a snapshot of the current aggregate state: the state at
      * this moment plus the version. Useful for ES snapshot policies and
      * for state-stored backup / restore.
      *
@@ -1094,7 +542,7 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * Converts live aggregate state into the plain-data shape stored in a
      * snapshot. The default validates that the state graph is plain,
      * serialisable data (no class instances, functions, Promise/WeakMap/
-     * WeakSet) and then `structuredClone`s it — class instances would
+     * WeakSet) and then `structuredClone`s it: class instances would
      * silently lose their prototype here AND on every snapshot-store
      * round-trip, so the default fails fast with the offending path
      * instead of producing a snapshot that breaks on first method call
@@ -1120,8 +568,8 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * into the event's metadata fields. This is the canonical path for
      * recording events from inside aggregate domain methods.
      *
-     * Downstream consumers — outbox dispatchers, projection handlers,
-     * audit logs — route by these two fields. Calling
+     * Downstream consumers (outbox dispatchers, projection handlers,
+     * audit logs) route by these two fields. Calling
      * `createDomainEvent(...)` directly inside an aggregate method
      * leaves them unset and is caught at the `withCommit` harvest
      * boundary, but `this.recordEvent(...)` makes the right thing
@@ -1145,8 +593,8 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * @param payload - payload for that event subtype
      * @param options - any remaining `createDomainEvent` options
      *   (`eventId`, `occurredAt`, `metadata`, `version`); `aggregateId`
-     *   and `aggregateType` are deliberately omitted — the helper sets
-     *   them.
+     *   and `aggregateType` are deliberately omitted, because the helper
+     *   sets them.
      */
     protected recordEvent<E extends TEvent>(type: E["type"], payload: E["payload"], options?: Omit<CreateDomainEventOptions, "aggregateId" | "aggregateType">): E;
 }
@@ -1159,7 +607,7 @@ interface AggregateConfig {
      * Whether `setState()` should bump the version automatically when the
      * caller omits the per-call `bumpVersion` argument.
      *
-     * Defaults to **`false`** — `setState()` already takes an explicit
+     * 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
@@ -1170,8 +618,8 @@ interface AggregateConfig {
 /**
  * Base class for Aggregate Roots without Event Sourcing.
  *
- * In DDD (Evans), an Aggregate is a cluster of objects — root entity, child entities,
- * and value objects — treated as a unit for consistency. The **Aggregate Root** is the
+ * In DDD (Evans), an Aggregate is a cluster of objects (root entity, child entities,
+ * and value objects) treated as a unit for consistency. The **Aggregate Root** is the
  * root entity that represents the aggregate externally and is the only entry point
  * for external code. This class serves as both: it IS the root entity and it contains
  * the aggregate state (`TState`) which holds child entities and value objects.
@@ -1190,7 +638,7 @@ interface AggregateConfig {
  *
  * @template TState - The type of the aggregate state (contains child entities and value objects)
  * @template TId - The type of the aggregate root identifier
- * @template TEvent - The type of domain events recorded by this aggregate. Defaults to `never` — aggregates without a declared event type cannot emit events (emitting any event becomes a compile error). Supply a concrete event union to opt in.
+ * @template TEvent - The type of domain events recorded by this aggregate. Defaults to `never`: aggregates without a declared event type cannot emit events (emitting any event becomes a compile error). Supply a concrete event union to opt in.
  *
  * @example
  * ```typescript
@@ -1213,7 +661,106 @@ interface AggregateConfig {
  */
 declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never, TSnapshotState = TState> extends BaseAggregate<TState, TId, TEvent, TSnapshotState> {
     private readonly _autoVersionBump;
+    /**
+     * The state reference as of the last {@link markRestored} /
+     * `markPersisted` (the persistence-lifecycle markers). Only
+     * meaningful while {@link _hasBaseline} is `true`; tracked by a
+     * separate flag rather than an `undefined` sentinel so a `TState`
+     * that itself admits `undefined` cannot be confused with the
+     * never-persisted insert path.
+     *
+     * Held by reference, never copied: `_state` is shallow-frozen and only
+     * ever *replaced* (via `setState` / restore), so the captured reference
+     * stays an exact image of the state at baseline time.
+     */
+    private _baselineState;
+    /**
+     * `false` until the aggregate has been persisted or restored at least
+     * once: the insert path, where every key counts as changed.
+     */
+    private _hasBaseline;
     protected constructor(id: TId, initialState: TState, config?: AggregateConfig);
+    /**
+     * **Lifecycle marker, Post-Load (see `BaseAggregate.markRestored`).**
+     * Additionally captures the current state reference as the dirty-
+     * tracking baseline for {@link changedKeys} / {@link hasChanges}.
+     *
+     * Covers all three baseline-capture paths through a single override:
+     * `reconstitute(...)` factories, {@link restoreFromSnapshot} (which
+     * assigns the restored state *before* calling this), and
+     * `markPersisted` (which delegates here, so a successful save
+     * re-baselines the diff).
+     *
+     * 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
+     * top of breaking version sync.
+     */
+    protected markRestored(version: Version): void;
+    /**
+     * Top-level state keys whose value (or presence) changed since the
+     * last {@link markRestored} / `markPersisted`. Never-persisted
+     * aggregates report ALL current keys (the insert path).
+     *
+     * This is the write-scoping signal for **partial writes in multi-table
+     * repositories**: a `save()` for an aggregate whose state spans a root
+     * row plus N child-collection tables can write only the collections
+     * whose key is dirty, while the root-row OCC version write rides every
+     * save. See `docs/guide/repository.md` → "Partial writes for
+     * multi-table aggregates".
+     *
+     * **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
+     * 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
+     * callers cannot poison later reads.
+     *
+     * **Soundness contract (same one `freezeShallow` already makes):**
+     * the per-key diff is exact only for plain-record `TState` mutated via
+     * `setState` / `commit` (whole-state replacement). In-place mutation
+     * of NESTED objects bypasses the shallow freeze AND this diff; a
+     * 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
+     * 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:
+     * a dirty collection key means "this child table changed", not which
+     * rows. `EventSourcedAggregate` deliberately has no `changedKeys`;
+     * its `pendingEvents` are the change record.
+     */
+    get changedKeys(): ReadonlySet<Extract<keyof TState, string>>;
+    /**
+     * 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
+     * keyless states the per-key diff cannot see (primitive `TState`,
+     * 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
+     * uncontended save would throw a false `ConcurrencyConflictError`.
+     *
+     * The pending-events clause covers the sanctioned decoupled
+     * `addDomainEvent` path (an event recorded without a state change,
+     * e.g. a deletion event before a hard delete): the aggregate still
+     * needs its trip through `withCommit` so the event reaches the
+     * outbox. With all clauses included, `hasChanges === false` genuinely
+     * means "skipping save is safe".
+     */
+    get hasChanges(): boolean;
     /**
      * Mutates state and records the resulting domain events in the
      * **canonical record-after-mutation order**. Use this instead of calling
@@ -1221,7 +768,7 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      * "event for a fact that never happened" footgun.
      *
      * Order of operations:
-     *  1. `setState(newState, true)` — runs `validateState` first.
+     *  1. `setState(newState, true)`: runs `validateState` first.
      *     If it throws, the method propagates and **no event is recorded
      *     and no version is bumped**.
      *  2. Each event in `events` is appended via `addDomainEvent`.
@@ -1268,7 +815,7 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      */
     protected setState(newState: TState, bumpVersion?: boolean): void;
     /**
-     * Restores the aggregate from a snapshot — loads state and aligns
+     * Restores the aggregate from a snapshot: loads state and aligns
      * `version` + `persistedVersion` to the snapshot version. Validates
      * the restored state.
      *
@@ -1283,19 +830,19 @@ type Handler<TState, TEvent extends AnyDomainEvent> = (state: TState, event: TEv
  *
  * Like `AggregateRoot`, this is both the root entity and the aggregate
  * boundary. The difference is persistence: state is derived from events,
- * not stored directly. Events are the single source of truth — all state
+ * not stored directly. Events are the single source of truth: all state
  * changes go through `apply()` → handler.
  *
  * Extends `BaseAggregate` (the shared lifecycle machinery) but does NOT
  * expose `setState()` or `commit()` from `AggregateRoot`. This enforces
- * the event sourcing pattern at the type level — there is no way to
+ * the event sourcing pattern at the type level: there is no way to
  * mutate state without going through an event handler.
  *
  * `apply()` and `validateEvent()` throw `DomainError`-derived exceptions
  * on invariant violations. Subclasses override `validateEvent()` to
  * throw their own concrete subclasses (e.g. `OrderAlreadyConfirmedError`).
  * Only the infrastructure-boundary methods (`loadFromHistory`,
- * `restoreFromSnapshotWithEvents`) return `Result` — they catch
+ * `restoreFromSnapshotWithEvents`) return `Result`: they catch
  * `DomainError` during replay so callers can react to corrupted event
  * streams without try/catch.
  *
@@ -1345,13 +892,13 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
      * Throws `DomainError` (or a subclass) on validation failure.
      * Throws `MissingHandlerError` if no handler is registered for `event.type`.
      *
-     * State is not mutated if any step throws — the handler is invoked into
+     * State is not mutated if any step throws: the handler is invoked into
      * a local and only assigned to `_state` once all checks pass.
      *
      * The method is generic in the event tag `K`, so concrete callers
      * (`this.apply(orderCreated)`) narrow to the literal tag and the
-     * dispatched handler is typed as `Handler<TState, Extract<TEvent, { type: K }>>`
-     * — no `as` cast required at the call site.
+     * dispatched handler is typed as `Handler<TState, Extract<TEvent, { type: K }>>`,
+     * with no `as` cast required at the call site.
      *
      * @param event - The domain event to apply
      * @param isNew - Whether the event is new (needs persisting) or replayed from history
@@ -1369,12 +916,12 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
     private dispatchAndCommit;
     /**
      * Reconstitutes the aggregate from an event history. Catches `DomainError`
-     * thrown during replay and returns it as an `Err` — this is the
+     * thrown during replay and returns it as an `Err`: this is the
      * infrastructure boundary, where event-stream corruption is an expected
      * recoverable failure. Unexpected (non-DomainError) throws propagate.
      *
      * All-or-nothing: if any event mid-stream throws, the aggregate's state
-     * is rolled back to its pre-call value — same contract as
+     * is rolled back to its pre-call value, the same contract as
      * `restoreFromSnapshotWithEvents`. Partial replay is never observable.
      * (Version needs no rollback: replay dispatches with `isNew = false`,
      * which never bumps it; only the final `markRestored` advances it.)
@@ -1553,7 +1100,7 @@ interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
      *
      * When `TMap` is supplied, the `commandType` argument is restricted to
      * its keys and the handler signature is forced to match `TMap[K]` for the
-     * return value — typos and wrong-typed handlers are compile errors.
+     * 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.
      *
@@ -1654,13 +1201,13 @@ interface EventBus<Evt extends AnyDomainEvent> {
      *     awaits all of its handlers, then dispatches `b`, and so on. The
      *     library never reorders or parallelises across events.
      *  2. **Handlers within a single event run in parallel.** All handlers
-     *     subscribed to `event.type` are awaited via `Promise.allSettled` —
+     *     subscribed to `event.type` are awaited via `Promise.allSettled`:
      *     none of them sees the others' errors and none is skipped if a
      *     peer fails.
      *  3. **Errors are collected and thrown AFTER everything dispatches.**
      *     If one handler throws, remaining handlers for that event still
      *     run, and remaining events in the batch still publish. Once
-     *     `publish` reaches the end of the batch it throws — the single
+     *     `publish` reaches the end of the batch it throws: the single
      *     error directly if there was one, or an `AggregateError`
      *     ("Multiple event handlers failed") containing every captured
      *     error otherwise. Callers that need fail-fast semantics should
@@ -1733,7 +1280,7 @@ interface OnceOptions {
 /**
  * One pending event in the outbox plus the opaque id the implementation
  * needs to ack it via `markDispatched`. The library does not prescribe
- * what `dispatchId` looks like — an implementation can reuse the event's
+ * what `dispatchId` looks like: an implementation can reuse the event's
  * own `eventId`, generate its own UUID, use the row's auto-increment
  * primary key, or whatever the storage layer prefers.
  */
@@ -1742,7 +1289,7 @@ interface OutboxRecord<Evt extends AnyDomainEvent> {
     event: Evt;
 }
 /**
- * Transactional outbox port — the bridge between the write-side
+ * Transactional outbox port: the bridge between the write-side
  * transaction and the (out-of-band) event dispatcher.
  *
  * Lifecycle:
@@ -1753,7 +1300,7 @@ interface OutboxRecord<Evt extends AnyDomainEvent> {
  *  3. After successful dispatch, the dispatcher calls `markDispatched()`
  *     with the records' `dispatchId`s so they don't come back next poll.
  *
- * `markDispatched` is required to be idempotent — calling it with an id
+ * `markDispatched` is required to be idempotent: calling it with an id
  * that's already marked is a no-op, not an error. This lets the
  * dispatcher safely retry on partial-failure.
  */
@@ -1792,20 +1339,24 @@ interface Outbox<Evt extends AnyDomainEvent> {
  * `$transaction`, etc.). The block commits when the callback resolves
  * and rolls back if it throws.
  *
- * `TCtx` is the persistence layer's transaction handle — Drizzle's `tx`,
+ * `TCtx` is the persistence layer's transaction handle: Drizzle's `tx`,
  * Prisma's `tx`, Mongo's session, etc. The scope opens the transaction
  * and passes the handle to `fn`; the use case binds its repositories to
  * that handle (typically by constructing a tx-scoped repo from the ctx).
  *
  * No default for `TCtx`: every implementor names their context type
  * explicitly. For genuinely context-free scopes (in-memory tests, naive
- * no-tx scopes) use `TransactionScope<undefined>` — that's a conscious
+ * no-tx scopes) use `TransactionScope<undefined>`: that's a conscious
  * "there is nothing meaningful here" statement, not an accidental
  * `unknown` fallback.
  *
- * Intentionally **not** Fowler's full Unit of Work (no change tracking,
- * no `registerDirty` / `registerNew` / `registerDeleted`, no commit-time
- * flush). Change tracking is the ORM's job.
+ * Intentionally minimal: the scope itself does no change tracking and
+ * no commit-time flush. Those concerns live in the layers above - the
+ * aggregate detects its own changes (`changedKeys` / `hasChanges`),
+ * `withCommit` orchestrates the commit lifecycle, and the opt-in
+ * `UnitOfWork` facade adds tx-bound repositories and enrollment. See
+ * "TransactionScope stays minimal; the Unit of Work lives above it" in
+ * docs/guide/design-decisions.md.
  *
  * @example Drizzle implementation
  * ```typescript
@@ -1817,7 +1368,7 @@ interface Outbox<Evt extends AnyDomainEvent> {
  * }
  * ```
  *
- * @example Use site — bind repos to the live transaction
+ * @example Use site: bind repos to the live transaction
  * ```typescript
  * await scope.transactional(async (tx) => {
  *   // Construct tx-bound repos from ctx (your factory / DI of choice)
@@ -1829,14 +1380,28 @@ interface Outbox<Evt extends AnyDomainEvent> {
  * });
  * ```
  *
- * `IRepository`'s contract takes the id / aggregate only — the tx handle
+ * `IRepository`'s contract takes the id / aggregate only: the tx handle
  * is wired into a concrete repository at construction time, not threaded
  * through every call. Different ORMs have different idioms for that
  * (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>;
 }
 
 /**
@@ -1849,14 +1414,17 @@ interface TransactionScope<TCtx> {
  * committed" is the orchestrator's call to make, not the repo's.
  *
  * Order of operations:
- *  1. `fn(ctx)` runs inside `scope.transactional(...)` — domain mutations
+ *  1. `fn(ctx)` runs inside `scope.transactional(...)`; domain mutations
  *     + repo writes happen here. `ctx` is whatever transaction handle the
  *     `scope` exposes (Drizzle `tx`, Prisma `tx`, Mongo session, or
  *     `undefined` for context-free scopes).
  *  2. **Still inside the transaction**, `withCommit` harvests every
  *     aggregate's `pendingEvents` and writes them via `outbox.add` (so
  *     events persist atomically with the state change). Skipped when no
- *     events were recorded.
+ *     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.
  *
  *     **Harvest order.** Events are concatenated in the order
  *     aggregates appear in the returned `aggregates` array, then in
@@ -1867,14 +1435,14 @@ interface TransactionScope<TCtx> {
  *     that exact order.
  *
  *     **Two ordering guarantees, not one.** Within a single aggregate
- *     the order is *causal* — events are recorded in the order the
+ *     the order is *causal*: events are recorded in the order the
  *     domain methods ran, and subscribers (handlers, projections,
  *     replay) MUST process them in that order. Across aggregates the
  *     order in this batch is deterministic but *not* a domain
  *     guarantee. Greg Young / Vernon IDDD §10: aggregates are
  *     independent consistency boundaries; events across them are
  *     eventually consistent. Subscribers should NOT engineer
- *     dependencies on cross-aggregate ordering — use
+ *     dependencies on cross-aggregate ordering; use
  *     `EventMetadata.causationId` to express true causation, or a
  *     process manager to coordinate. The in-process EventBus delivers
  *     this batch in order, sequential outbox-dispatchers preserve it
@@ -1882,8 +1450,11 @@ interface TransactionScope<TCtx> {
  *     across aggregates at delivery time.
  *  3. The transaction commits.
  *  4. **After** the commit, `aggregate.markPersisted(aggregate.version)`
- *     fires on each returned aggregate — only now are pending events
- *     considered flushed.
+ *     fires on each returned aggregate; only now are pending events
+ *     considered flushed. Aggregates listed in the optional `deleted`
+ *     marker array are the exception: their pending events are cleared
+ *     directly WITHOUT `markPersisted`, so the post-save `onPersisted`
+ *     hook never fires for a row that was just deleted.
  *  5. `bus.publish(events)` fires for the in-process fast path (skipped
  *     when no events or no `bus` is wired).
  *
@@ -1894,22 +1465,36 @@ interface TransactionScope<TCtx> {
  * them (eventual consistency).
  *
  * **A `bus.publish` failure never rejects `withCommit`.** Once the
- * transaction has committed, the write succeeded — surfacing a subscriber
+ * transaction has committed, the write succeeded; surfacing a subscriber
  * failure as a rejection would hand the caller a use-case failure for a
  * committed write (a typical caller retries, double-executing it). The
  * in-process fast path is best-effort by design; the error is reported to
  * the optional `onPublishError(error, events)` hook (wire it to your
- * logger/metrics) and otherwise dropped — delivery is still guaranteed via
+ * logger/metrics) and otherwise dropped; delivery is still guaranteed via
  * the outbox. The hook is an observer: if it throws, its error is
  * swallowed so the post-commit invariant holds.
  *
- * If the transaction rolls back, `markPersisted` is **not** called — the
+ * If the transaction rolls back, `markPersisted` is **not** called: the
  * aggregate keeps its pending events, so the caller can retry or discard.
  *
+ * **Do not mutate an aggregate after `repository.save(...)` inside `fn`.**
+ * `withCommit` cannot see what `save` wrote; the post-commit
+ * `markPersisted` syncs `persistedVersion` to the CURRENT in-memory
+ * 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
+ * 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
+ * a local one. Mutate first, save last.
+ *
  * **Duplicate aggregates are deduped by reference.** If the returned
- * `aggregates` array contains the same instance twice — e.g. a use
+ * `aggregates` array contains the same instance twice (e.g. a use
  * case touches an order via two repository references that happen to
- * resolve to the same identity-map entry — `withCommit` dedupes by
+ * resolve to the same identity-map entry), `withCommit` dedupes by
  * JavaScript object identity before harvesting. Each event lands in
  * the outbox exactly once and `markPersisted` fires exactly once. Two
  * *different* instances with the same logical id cannot be detected
@@ -1925,7 +1510,7 @@ interface TransactionScope<TCtx> {
  *   const orderRepository = makeOrderRepository(tx); // your factory binds tx to the repo
  *   const order = await orderRepository.getByIdOrFail(orderId);
  *   order.confirm();
- *   await orderRepository.save(order);             // pure persistence — does NOT call markPersisted
+ *   await orderRepository.save(order);             // pure persistence; does NOT call markPersisted
  *   return { result: order.id, aggregates: [order] };
  * });
  * ```
@@ -1937,12 +1522,32 @@ declare function withCommit<Evt extends AnyDomainEvent, R, TCtx>(deps: {
     /**
      * Observer for post-commit `bus.publish` failures. Called with the
      * error and the events that were published. Must not be relied on
-     * for delivery — the outbox dispatcher is the reliable path.
+     * 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>>;
+    /**
+     * 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
+     * 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
+     * cleared directly instead, so a later commit cannot re-emit them.
+     */
+    deleted?: ReadonlyArray<IAggregateRoot<Id<string>, Evt>>;
 }>): Promise<R>;
 
 /**
@@ -2020,6 +1625,398 @@ interface Query {
  */
 type QueryHandler<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
+ * construction: `Restaurant` and `Booking` are different keys even if
+ * someone names two aggregates identically across modules, and there
+ * is no string-discipline to maintain.
+ *
+ * The `Function & { prototype: TAgg }` branch is load-bearing: the
+ * kit's aggregate convention is a **protected constructor** plus
+ * static factories, and TypeScript rejects assigning a class with a
+ * protected constructor to a construct-signature type. The prototype
+ * witness accepts those classes while still inferring `TAgg`.
+ */
+type AggregateClass<TAgg> = (abstract new (...args: any[]) => TAgg) | (Function & {
+    prototype: TAgg;
+});
+/**
+ * Per-unit-of-work Identity Map (Fowler, PoEAA): within one operation,
+ * one aggregate type+id maps to exactly ONE in-memory instance.
+ *
+ * This is the shipped implementation of the contract the
+ * [Repository guide](../../docs/guide/repository.md) places on
+ * `IRepository` implementations: two `getById(id)` calls in the same
+ * unit of work MUST return the same instance, because `withCommit`'s
+ * aggregate dedupe (and therefore exactly-once event harvest and
+ * `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
+ * is the aggregate CLASS, not the id alone and not a name string.
+ *
+ * Repository read-path contract:
+ *
+ * ```ts
+ * async getById(id: OrderId): Promise<Order | null> {
+ *   const cached = this.session.identityMap.get(Order, id);
+ *   if (cached) return cached;
+ *   // Deleted in this unit of work = gone, even if the physical
+ *   // delete is deferred and the row is still visible in the tx.
+ *   if (this.session.identityMap.isDeleted(Order, id)) return null;
+ *
+ *   const row = await this.loadRow(id);
+ *   if (!row) return null;
+ *   const order = Order.reconstitute(row.id, row.state, row.version);
+ *   this.session.identityMap.set(Order, id, order);
+ *   return order;
+ * }
+ * ```
+ *
+ * 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
+ * deleted aggregate can never sneak back into the unit of work, even
+ * through a repository whose row delete is deferred.
+ *
+ * Lifetime is ONE unit of work: the `UnitOfWork` creates a fresh map
+ * per `run()` and clears it on close. Never cache across operations;
+ * that would silently bypass optimistic concurrency control.
+ */
+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}). */
+    has<TAgg>(type: AggregateClass<TAgg>, id: Id<string>): boolean;
+    /**
+     * 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,
+     * 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
+     * in {@link set} for deferred-write repositories and return `null`
+     * for immediate-write ones.
+     */
+    isDeleted<TAgg>(type: AggregateClass<TAgg>, id: Id<string>): boolean;
+    /**
+     * Registers the hydrated instance for type+id.
+     *
+     * - Re-registering the SAME instance is a no-op (idempotent).
+     * - Registering a DIFFERENT instance for an occupied type+id throws:
+     *   that is precisely the identity-map violation this class exists
+     *   to prevent (the repository hydrated twice instead of checking
+     *   {@link get} first), and letting it pass would double-harvest
+     *   events downstream.
+     * - Registering a type+id that was {@link delete}d in this unit of
+     *   work throws `AggregateDeletedError`: deletion is final within
+     *   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
+     * {@link set} of the same type+id throws `AggregateDeletedError`.
+     * Called by a repository's `delete(aggregate)` alongside
+     * `session.enrollDeleted(aggregate)`.
+     */
+    delete<TAgg>(type: AggregateClass<TAgg>, id: Id<string>): void;
+    /** Empties all stores and tombstones. Called by the unit of work on close. */
+    clear(): void;
+}
+
+/**
+ * Thrown when `UnitOfWork.run()` is called while the same instance is
+ * already executing a unit of work: either a genuinely nested `run()`
+ * inside the work callback, or two concurrent operations sharing one
+ * instance.
+ *
+ * Both are contract violations, not recoverable infrastructure
+ * failures, so this extends `BaseError` directly (same reasoning as
+ * `MissingHandlerError`): a generic `catch (e instanceof
+ * InfrastructureError)` handler must not mask it.
+ *
+ * A nested `run()` would NOT join the outer transaction; it would open
+ * an independent one, silently breaking the all-or-nothing guarantee.
+ * If two operations must commit together, they are ONE unit of work:
+ * merge them into a single `run()` callback. For concurrent requests,
+ * construct one `UnitOfWork` per operation (construction is trivially
+ * cheap; the dependency object is the thing you share).
+ */
+declare class NestedUnitOfWorkError extends BaseError<"NestedUnitOfWorkError"> {
+    constructor();
+}
+/**
+ * Thrown when the unit-of-work context is used after `run()` has
+ * settled: reading `context.repositories` / `context.transaction`, or
+ * calling `session.enrollSaved` / `session.enrollDeleted`, once the
+ * transaction has committed or rolled back.
+ *
+ * Use-after-close is a programming bug (typically a leaked context
+ * reference or a fire-and-forget promise outliving the callback), so
+ * this extends `BaseError` directly and should crash loud.
+ *
+ * **Honest scope of this guard:** the kit can only invalidate what it
+ * controls - the context getters and the session. A repository or raw
+ * transaction handle captured into a variable BEFORE close keeps
+ * working as far as the kit can see; whether the underlying tx handle
+ * rejects is ORM-specific. Do not let references escape the callback.
+ */
+declare class TransactionClosedError extends BaseError<"TransactionClosedError"> {
+    readonly operation: string;
+    constructor(operation: string);
+}
+/**
+ * The unit of work failed AFTER the work callback completed
+ * 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.
+ * 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);
+}
+/**
+ * The work callback threw AND the transaction scope rejected with a
+ * DIFFERENT error that does not wrap the callback's error in its cause
+ * chain - the strongest available signal that the rollback itself
+ * failed. The callback's (primary) error is preserved as `cause`, so
+ * cause-chain helpers (`someChainRetryable`, `findInCauseChain`) still
+ * see a wrapped `ConcurrencyConflictError` & co.; the scope's error is
+ * carried in {@link rollbackCause}.
+ *
+ * Scopes that rethrow the original error (Drizzle, Prisma do) never
+ * produce this; scopes that WRAP the original are detected via the
+ * cause chain and passed through unchanged instead.
+ */
+declare class RollbackError extends InfrastructureError<"RollbackError"> {
+    readonly rollbackCause: unknown;
+    constructor(cause: unknown, rollbackCause: unknown);
+}
+/**
+ * The enrollment handle a unit of work hands to its repositories.
+ *
+ * Repositories enroll every aggregate they write so the unit of work
+ * can harvest pending events into the outbox (inside the transaction)
+ * and call `markPersisted` after the commit - the same lifecycle
+ * `withCommit` runs for its returned `aggregates` array, minus the
+ * footgun: with enrollment, "forgot to list the aggregate" cannot
+ * happen per call site; each repository implements it once and its
+ * tests pin it once.
+ *
+ * Contract for repository implementations:
+ * - `getById(id)` checks `identityMap.get` BEFORE hydrating, treats
+ *   `identityMap.isDeleted` as not-found (`null`), and registers the
+ *   hydrated instance after - two loads of the same aggregate in one
+ *   unit of work must return the same instance.
+ * - `save(aggregate)` calls {@link enrollSaved} BEFORE the row write:
+ *   the deleted-gate then throws `AggregateDeletedError` before any SQL
+ *   runs (instead of the write surfacing as a confusing
+ *   `ConcurrencyConflictError` against the deleted row). Enrollment is
+ *   idempotent per instance, mirroring `withCommit`'s reference dedupe,
+ *   and a failed write rolls the whole unit of work back anyway.
+ * - `delete(aggregate)` calls {@link enrollDeleted} - ONE call does all
+ *   the deletion bookkeeping: the identity-map entry is removed and
+ *   tombstoned automatically (keyed on the instance's concrete class),
+ *   the recorded deletion events are still harvested into the outbox,
+ *   and saving or re-registering the aggregate (same instance OR a
+ *   re-created one with the same type+id) later in this unit of work
+ *   throws `AggregateDeletedError`.
+ *
+ * The use case can also enroll manually via `context.session` for the
+ * rare write that bypasses a repository.
+ */
+interface UnitOfWorkSession<Evt extends AnyDomainEvent = AnyDomainEvent> {
+    /**
+     * The per-operation Identity Map (Fowler): one aggregate type+id,
+     * one in-memory instance. Created fresh per `run()`, cleared on
+     * close; accessing it after close throws
+     * {@link TransactionClosedError}.
+     */
+    readonly identityMap: IdentityMap;
+    /** Enroll an aggregate that was (or will be) written in this unit of work. */
+    enrollSaved(aggregate: IAggregateRoot<Id<string>, Evt>): void;
+    /**
+     * Enroll an aggregate whose row was (or will be) deleted in this
+     * unit of work. Its pending events (e.g. a recorded deletion event)
+     * are harvested like any other; re-saving the instance afterwards
+     * throws `AggregateDeletedError`.
+     */
+    enrollDeleted(aggregate: IAggregateRoot<Id<string>, Evt>): void;
+}
+/**
+ * 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.
+ *
+ * All members throw {@link TransactionClosedError} once `run()` has
+ * settled; do not let the context escape the callback.
+ */
+interface UnitOfWorkContext<TCtx, TRepos, Evt extends AnyDomainEvent = AnyDomainEvent> {
+    readonly repositories: TRepos;
+    /**
+     * **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:
+     * 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
+ * that constructs the repository bound to the live transaction handle
+ * and the enrollment session. Called once per `run()`, so every
+ * repository of one unit of work shares the same transaction.
+ *
+ * ```ts
+ * const factories = {
+ *   orders: (tx, session) => new DrizzleOrderRepository(tx, session),
+ *   invoices: (tx, session) => new DrizzleInvoiceRepository(tx, session),
+ * };
+ * ```
+ */
+type RepositoryFactories<TCtx, TRepos, Evt extends AnyDomainEvent = AnyDomainEvent> = {
+    [K in keyof TRepos]: (tx: TCtx, session: UnitOfWorkSession<Evt>) => TRepos[K];
+};
+/** Dependencies for {@link UnitOfWork}; the app-level singleton part. */
+interface UnitOfWorkDeps<Evt extends AnyDomainEvent, TCtx, TRepos> {
+    scope: TransactionScope<TCtx>;
+    outbox: Outbox<Evt>;
+    bus?: EventBus<Evt>;
+    /** See `withCommit`: observer for post-commit `bus.publish` failures. */
+    onPublishError?: (error: unknown, events: ReadonlyArray<Evt>) => void;
+    repositories: RepositoryFactories<TCtx, TRepos, Evt>;
+}
+/**
+ * Explicit-save Unit of Work: one `run()` call is one application-level
+ * write operation. All repository writes inside the callback share one
+ * transaction and either persist completely or not at all.
+ *
+ * Built ON TOP of `withCommit` - the commit orchestration (event
+ * harvest into the outbox inside the transaction, `markPersisted`
+ * after the commit, best-effort in-process publish last) is inherited,
+ * not reimplemented. What this layer adds:
+ *
+ * - **Tx-bound repositories via a registry.** The callback receives
+ *   ready-made repositories instead of a raw transaction handle; the
+ *   factory map is wired once at construction.
+ * - **Enrollment instead of a returned aggregates array.** Repositories
+ *   enroll what they write via {@link UnitOfWorkSession}; the use case
+ *   cannot forget to list an aggregate (the `withCommit` footgun).
+ * - **Lifecycle errors.** {@link NestedUnitOfWorkError},
+ *   {@link TransactionClosedError}, {@link CommitError},
+ *   {@link RollbackError}, {@link AggregateDeletedError}.
+ *
+ * - **A per-operation Identity Map** on the session: repositories
+ *   check it before hydrating and register after, so one type+id maps
+ *   to one in-memory instance per unit of work (the contract
+ *   `withCommit`'s reference-dedupe relies on, now shipped instead of
+ *   merely documented).
+ *
+ * What it deliberately does NOT do (v1): no auto-flush (explicit
+ * `save()` only - `hasChanges` makes a redundant save a cheap no-op),
+ * no savepoints, no nested-transaction joining. `withCommit` with
+ * hand-rolled repos remains fully supported; this facade is opt-in.
+ *
+ * **Instance discipline:** one instance owns one logical operation at
+ * a time. `run()` while a run is active throws
+ * {@link NestedUnitOfWorkError} - that covers genuine nesting AND two
+ * concurrent requests sharing one instance, which is the same bug in
+ * different clothes. Construct one `UnitOfWork` per operation
+ * (construction stores one reference; the shareable singleton is the
+ * deps object). Sequential reuse of an instance is fine.
+ *
+ * **Error pass-through:** an error thrown by the work callback (a
+ * repository's `ConcurrencyConflictError`, a `DomainError`, anything)
+ * is rethrown UNCHANGED - the unit of work never converts a concurrency
+ * conflict into a generic error. Only the two failure modes the
+ * callback cannot observe are wrapped: see {@link CommitError} and
+ * {@link RollbackError}.
+ *
+ * @example
+ * ```ts
+ * const deps = {
+ *   scope: drizzleScope,
+ *   outbox: drizzleOutbox,
+ *   bus: eventBus,
+ *   repositories: {
+ *     restaurants: (tx, session) => new DrizzleRestaurantRepository(tx, session),
+ *   },
+ * };
+ *
+ * const uow = new UnitOfWork(deps);
+ * const result = await uow.run(async ({ repositories }) => {
+ *   const restaurant = await repositories.restaurants.getByIdOrFail(id);
+ *   restaurant.changeOpeningHours(openingHours);
+ *   await repositories.restaurants.save(restaurant); // save() enrolls
+ *   return restaurant.id;
+ * });
+ * ```
+ */
+declare class UnitOfWork<Evt extends AnyDomainEvent, TCtx, TRepos extends Record<string, unknown>> {
+    private readonly deps;
+    private _active;
+    constructor(deps: UnitOfWorkDeps<Evt, TCtx, TRepos>);
+    /**
+     * Execute one unit of work: open the transaction, hand the callback
+     * tx-bound repositories, commit on resolve, roll back on throw,
+     * 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>, options?: RunOptions): Promise<R>;
+    private buildRepositories;
+}
+
 /**
  * Type map for query types to their return types.
  * Used to improve type inference in QueryBus.
@@ -2089,7 +2086,7 @@ interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
      *
      * 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.
+     * 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.
      *
@@ -2200,7 +2197,7 @@ declare class EventBusImpl<Evt extends AnyDomainEvent> implements EventBus<Evt>
  * In-memory reference implementation of `Outbox<Evt>`.
  *
  * Intended for tests, single-process workers, and quick-start demos.
- * Uses the event's own `eventId` as the dispatch id — the common, clean
+ * 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
@@ -2209,7 +2206,13 @@ 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.
+ * 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
+ * test store's transactional semantics; see the reference adapter at
+ * https://github.com/shi-rudo/ddd-kit-ts/blob/main/src/testing/repository-contract.test.ts
+ * (repo-only, not shipped to npm).
  *
  * @example
  * ```ts
@@ -2234,13 +2237,33 @@ declare class InMemoryOutbox<Evt extends AnyDomainEvent> implements Outbox<Evt>
     markDispatched(dispatchIds: ReadonlyArray<string>): Promise<void>;
 }
 
+/**
+ * The canonical shape of a unit-of-work-facing repository. Unlike
+ * `IRepository` below (id-canonical CRUD for `withCommit`-style
+ * setups), `delete` takes the AGGREGATE: the unit of work needs the
+ * instance for deletion-event harvest, the identity-map tombstone, and
+ * 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
+ * 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.
+ */
+interface IUnitOfWorkRepository<TAgg extends IAggregateRoot<TId, Evt>, TId extends Id<string>, Evt extends AnyDomainEvent = AnyDomainEvent> {
+    getById(id: TId): Promise<TAgg | null>;
+    getByIdOrFail(id: TId): Promise<TAgg>;
+    save(aggregate: TAgg): Promise<void>;
+    delete(aggregate: TAgg): Promise<void>;
+}
 /**
  * Core repository contract for Aggregate Roots.
  *
  * In DDD a Repository is a "collection illusion" for aggregates: load by
  * identity, save the whole aggregate, delete by identity. Querying by
  * arbitrary criteria is a separate concern (CQRS read-side, ad-hoc bulk
- * operations) and lives on the `IQueryableRepository` extension below — so
+ * operations) and lives on the `IQueryableRepository` extension below, so
  * write-side repositories don't have to implement query plumbing they
  * don't need.
  *
@@ -2271,7 +2294,7 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
     exists(id: TId): Promise<boolean>;
     /**
      * Persists the aggregate (insert or update). Implementations are
-     * responsible for **persistence only** — they must NOT touch the
+     * responsible for **persistence only**; they must NOT touch the
      * aggregate's in-memory state:
      *
      *  1. Throw `ConcurrencyConflictError` from `@shirudo/ddd-kit` when the
@@ -2279,14 +2302,14 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      *     stored (optimistic concurrency).
      *  2. Write the aggregate to durable storage.
      *
-     * **Insert vs update — `persistedVersion` convention.** Every aggregate
+     * **Insert vs update: the `persistedVersion` convention.** Every aggregate
      * exposes two version fields with distinct roles:
      *
-     *  - `aggregate.version` — in-memory post-mutation value, bumped by
+     *  - `aggregate.version`: in-memory post-mutation value, bumped by
      *    `setState(_, true)` / `commit()` / `apply()`. NOT the right
      *    routing key, because mutations can advance it past zero while
      *    the DB row still does not exist.
-     *  - `aggregate.persistedVersion` — what the persistence layer holds.
+     *  - `aggregate.persistedVersion`: what the persistence layer holds.
      *    `undefined` until the aggregate has been persisted or restored
      *    at least once. This is the routing key.
      *
@@ -2296,14 +2319,14 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      *  - otherwise → **UPDATE** with the OCC predicate
      *    `WHERE id = ? AND version = aggregate.persistedVersion` (the
      *    load-time / last-save baseline, not the post-mutation in-memory
-     *    value). If the row count is `0`, another writer raced you —
+     *    value). If the row count is `0`, another writer raced you:
      *    throw `ConcurrencyConflictError`.
      *
      * Do **not** call `aggregate.markPersisted(...)` here. The library's
      * `withCommit` orchestrator handles the post-save lifecycle (harvest
      * pending events into the outbox, then mark persisted after commit).
      * Calling `markPersisted` inside `save` clears pending events too early
-     * and breaks the harvest path — and is also why the Vernon/Axon/
+     * and breaks the harvest path, and is also why the Vernon/Axon/
      * EventFlow pattern separates persistence from commit-events.
      *
      * If you are not using `withCommit` (custom orchestration), call
@@ -2312,7 +2335,7 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      */
     save(aggregate: TAgg): Promise<void>;
     /**
-     * Removes the aggregate's row by id. Pure persistence — does NOT
+     * Removes the aggregate's row by id. Pure persistence: does NOT
      * harvest pending events from the aggregate (the contract takes
      * only the id, so there is no aggregate to harvest from).
      *
@@ -2320,7 +2343,7 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      * is the right domain verb. Most are actually state transitions
      * (*cancel*, *archive*, *close*, *deactivate*, *terminate*) with
      * proper domain names that should be modelled as state changes plus
-     * a recorded event — not as row removal.
+     * a recorded event, not as row removal.
      *
      * `delete(id)` belongs in the toolkit for three distinct cases, in
      * decreasing order of common occurrence (see
@@ -2346,7 +2369,7 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      *    subscriber cares. If the entity has identity in the ubiquitous
      *    language, you probably want path 1 or 2 instead.
      *
-     * In pure event-sourced systems `delete` is rarely meaningful —
+     * In pure event-sourced systems `delete` is rarely meaningful:
      * end-of-lifecycle there is a `Closed` / `Terminated` event in the
      * stream, and identity persists in the event log. `delete` applies
      * primarily to state-stored aggregates and snapshot / projection
@@ -2360,7 +2383,7 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
  * Prisma `WhereInput`, a MongoDB filter document, a plain
  * `(t: TAgg) => boolean` predicate for in-memory repos, or anything else.
  *
- * The library does not prescribe a Specification or query DSL — the
+ * The library does not prescribe a Specification or query DSL: the
  * Repository implementation owns its query language. This avoids the
  * phantom-interface trap of a library-level `ISpecification<T>` with no
  * methods and lets each Repository expose the strongest possible types for
@@ -2396,19 +2419,107 @@ interface IQueryableRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<
      */
     findOne(filter: TFilter): Promise<TAgg | null>;
     /**
-     * Returns **every** aggregate matching the filter — no pagination,
+     * Returns **every** aggregate matching the filter: no pagination,
      * no cursor. For unbounded result sets, prefer a read-side projection
      * (CQRS read model) over loading aggregates in bulk; aggregates are
      * write-side objects and rehydrating thousands of them by id is rarely
      * what you want. If you need pagination on the write side, declare a
      * domain-specific paged method on your concrete repository (e.g.
-     * `findPage(filter, cursor)`) — the library does not prescribe a
+     * `findPage(filter, cursor)`): the library does not prescribe a
      * pagination contract because cursor/offset/keyset semantics vary too
      * much across storage backends.
      */
     find(filter: TFilter): Promise<TAgg[]>;
 }
 
+/**
+ * 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
@@ -2416,31 +2527,31 @@ type VO<T> = Readonly<T>;
  * so the freeze symmetry matches `deepEqual` (which also considers symbol
  * keys). Handles circular references by tracking visited objects.
  *
- * Note: `deepFreeze` mutates its argument in place — it sets `[[Frozen]]`
+ * Note: `deepFreeze` mutates its argument in place; it sets `[[Frozen]]`
  * on the object you pass in. Callers that need to avoid touching the
  * input (e.g. `vo()`) should deep-clone first.
  *
  * Date/Map/Set keep internal-slot mutability under `Object.freeze`
  * (`setTime`, `set`, `add`, … still work on frozen instances), so their
  * mutator methods are shadowed with throwing own properties and Map/Set
- * contents are frozen recursively. The shadows are non-enumerable —
+ * contents are frozen recursively. The shadows are non-enumerable:
  * invisible to `Object.keys`, spread, `deepEqual`, and `structuredClone`.
  *
  * The shadowing is deny-by-enumeration: only the mutators known at
  * release time are blocked. If the runtime grows a NEW mutator (e.g. the
  * stage-3 `Map.prototype.getOrInsert` upsert proposal), it is not blocked
- * until the list is updated — treat the mutator blocking as a guard rail,
+ * until the list is updated. Treat the mutator blocking as a guard rail,
  * not a security boundary.
  *
  * Limitation: ArrayBuffer views (TypedArrays, DataView) are passed through
- * unfrozen — the spec forbids freezing a view with elements, and freezing
- * cannot protect the underlying buffer. Their contents remain mutable.
+ * unfrozen, because the spec forbids freezing a view with elements, and
+ * freezing cannot protect the underlying buffer. Their contents remain mutable.
  */
 declare function deepFreeze<T>(obj: T, visited?: WeakSet<object>): Readonly<T>;
 /**
  * Creates a deeply immutable value object from the given data.
  *
- * The input is first deep-cloned, then the clone is frozen — so calling
+ * The input is first deep-cloned, then the clone is frozen, so calling
  * `vo(input)` never freezes the caller's own object graph as a
  * side-effect. Mutating the input afterwards does not bleed into the VO.
  * Symbol-keyed properties are preserved (matching `voEquals`); function
@@ -2531,7 +2642,7 @@ declare function voEqualsExcept<T>(a: VO<T>, b: VO<T>, options: DeepEqualExceptO
  *
  * Note: the Result covers VALIDATION failures only. Non-data values in
  * the input (functions, Promise/WeakMap/WeakSet) still throw a
- * `TypeError` from `vo()` — they cannot occur in parsed JSON and signal
+ * `TypeError` from `vo()`; they cannot occur in parsed JSON and signal
  * a programming error, not a validation failure.
  *
  * @param t - The data to convert into a value object
@@ -2599,7 +2710,7 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
     /**
      * Creates a new ValueObject.
      * The properties are deep-cloned (prototype-preserving) and then deeply
-     * frozen — the caller's own object graph is never frozen or mutated,
+     * 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.
      *
      * @param props - The properties of the value object
@@ -2659,7 +2770,7 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
  * was recorded the input is frozen into a `VO<T>` and returned as `Ok`;
  * otherwise the populated `ValidationError` is returned as `Err`.
  *
- * `ValidationError` comes from `@shirudo/base-error` — import it from there to
+ * `ValidationError` comes from `@shirudo/base-error`; import it from there to
  * narrow the `Err` branch, exactly as `Result` is imported from
  * `@shirudo/result`. It serializes to RFC 9457 Problem Details; use
  * {@link validationProblemDetails} at the HTTP boundary to surface the issues.
@@ -2681,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 AggregateConfig, AggregateNotFoundError, AggregateRoot, type AggregateSnapshot, type AnyDomainEvent, type ClockFactory, type Command, CommandBus, type CommandHandler, ConcurrencyConflictError, type CreateDomainEventOptions, DeepEqualExceptOptions, DomainError, type DomainEvent, Entity, type EventBus, EventBusImpl, type EventHandler, type EventIdFactory, type EventMetadata, EventSourcedAggregate, type IAggregateRoot, type ICommandBus, type IEntity, type IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IValueObject, type Id, type IdGenerator, type Identifiable, InMemoryOutbox, InfrastructureError, MissingHandlerError, type OnceOptions, type Outbox, type OutboxRecord, type Query, QueryBus, type QueryHandler, type TransactionScope, type VO, ValueObject, type Version, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
+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 };