@shirudo/ddd-kit 2.2.0 → 3.0.0-rc.3

package/dist/chunks/snapshot-store.d.ts

@@ -0,0 +1,2808 @@
+import { o as DomainError } from "./errors.js";
+import { Result } from "@shirudo/result";
+
+//#region src/core/id.d.ts
+/**
+ * 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>;
+}
+//#endregion
+//#region src/aggregate/clock.d.ts
+/**
+ * Clock function producing a valid `Date` for the current instant.
+ * Event-clock reads throw `TypeError` when the result is invalid.
+ */
+type ClockFactory = () => Date;
+//#endregion
+//#region src/aggregate/domain-event.d.ts
+/**
+ * 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.
+ * Supply one to {@link createDomainEventFactory} to use UUID v7, ULID,
+ * KSUID, or another collision-safe format without mutating module state.
+ */
+type EventIdFactory = () => string;
+/**
+ * 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.
+   */
+  readonly correlationId?: string;
+  /**
+   * Conversation ID shared by every message in one long-running business
+   * interaction, even when that interaction spans several correlations.
+   */
+  readonly conversationId?: string;
+  /**
+   * Causation ID referencing the event or command that caused this event.
+   * Used to build event chains and understand causality.
+   */
+  readonly causationId?: string;
+  /**
+   * W3C Trace Context parent for technical tracing across process boundaries.
+   * This is distinct from business correlation and conversation identifiers.
+   */
+  readonly traceparent?: string;
+  /** Optional W3C vendor trace state associated with `traceparent`. */
+  readonly tracestate?: string;
+  /**
+   * User ID of the person or system that triggered the event.
+   */
+  readonly userId?: string;
+  /**
+   * Source service or component that produced the event.
+   */
+  readonly source?: string;
+  /**
+   * Additional custom metadata fields.
+   * Allows extensibility for domain-specific metadata.
+   */
+  readonly [key: string]: unknown;
+}
+/**
+ * Domain Event represents something meaningful that happened in the domain.
+ * Events are immutable and carry information about what occurred.
+ *
+ * **Events are PLAIN DATA objects**, constructed via `createDomainEvent`
+ * (or the aggregate's `createEvent` plus application-shell recording path)
+ * and deeply frozen. Class-based
+ * event objects that satisfy this shape structurally via prototype
+ * members are unsupported.
+ *
+ * **Field-accretion boundary.** Persistence positions, commit boundaries,
+ * broker offsets, and other delivery concerns belong in an event envelope,
+ * not on the domain event itself.
+ *
+ * @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`. Convenience constructors default to
+   * `crypto.randomUUID()`; strict construction requires the caller to supply it.
+   */
+  readonly eventId: string;
+  /**
+   * The type of the event, used for routing and handling.
+   */
+  readonly 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.
+   */
+  readonly aggregateId?: string;
+  /**
+   * Name of the aggregate type that produced the event (e.g. "Order").
+   * Pairs with `aggregateId` to fully qualify the source aggregate.
+   */
+  readonly aggregateType?: string;
+  /**
+   * The event payload containing the domain data. The field is always
+   * present; its value is `undefined` when `P` is `void`.
+   */
+  readonly payload: P;
+  /**
+   * Timestamp when the accepted fact was recorded by the application shell.
+   * Put business-relevant time in the payload under a domain name.
+   */
+  readonly 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.
+   *
+   * This is the event PAYLOAD schema version, not a persisted aggregate
+   * position. Commit positions live on `CommittedDomainEvent`.
+   */
+  readonly version: number;
+  /**
+   * Optional metadata for traceability, correlation, and auditing.
+   * Includes correlationId, conversationId, causationId, userId, source, and
+   * custom fields.
+   */
+  readonly 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>;
+/**
+ * A domain event accepted by an aggregate but not yet given its recording
+ * identity, recording time, or delivery metadata.
+ *
+ * The aggregate owns the event type, payload, source address, and payload
+ * schema version because those values describe the business fact it produced.
+ * The application shell later turns this value into a {@link DomainEvent}.
+ */
+interface UncommittedDomainEvent<T extends string, P = void> {
+  readonly type: T;
+  readonly aggregateId?: string;
+  readonly aggregateType?: string;
+  readonly payload: P;
+  readonly version: number;
+}
+/** Upper-bound alias for any uncommitted domain-event shape. */
+type AnyUncommittedDomainEvent = UncommittedDomainEvent<string, unknown>;
+/** Derives the uncommitted shape represented by a concrete event or event union. */
+type UncommittedDomainEventOf<TEvent extends AnyDomainEvent> = TEvent extends DomainEvent<infer TType, infer TPayload> ? UncommittedDomainEvent<TType, TPayload> : never;
+/** An aggregate may hold unstamped decisions and already recorded events together. */
+type PendingDomainEvent<TEvent extends AnyDomainEvent> = TEvent | UncommittedDomainEventOf<TEvent>;
+/** Producer-owned options for an uncommitted event. */
+interface CreateUncommittedDomainEventOptions {
+  readonly aggregateId?: string;
+  readonly aggregateType?: string;
+  readonly version?: number;
+}
+/**
+ * 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;
+}
+/** Technical recording data attached by the application shell. */
+interface DomainEventStamp {
+  /** Stable identity for this event instance. */
+  readonly eventId: string;
+  /** Time at which the accepted domain fact was recorded. */
+  readonly occurredAt: Date;
+  /** Optional correlation, causation, actor, and source metadata. */
+  readonly metadata?: EventMetadata;
+}
+/** Full strict-construction options, including producer-owned event fields. */
+interface CreateDomainEventFromFactsOptions extends DomainEventStamp {
+  readonly aggregateId?: string;
+  readonly aggregateType?: string;
+  readonly version?: number;
+}
+/** Overrides accepted when an application-shell factory creates a stamp. */
+interface CreateDomainEventStampOptions {
+  readonly eventId?: string;
+  readonly occurredAt?: Date;
+  readonly metadata?: EventMetadata;
+}
+/** Dependencies captured by one immutable domain-event factory instance. */
+interface DomainEventFactoryOptions {
+  /** Event-id generator. Defaults to Web Crypto `crypto.randomUUID()`. */
+  readonly eventIdFactory?: EventIdFactory;
+  /** Event-recording clock. Defaults to `() => new Date()`. */
+  readonly clock?: ClockFactory;
+}
+/**
+ * Instance-bound event constructor. Each factory permanently captures its
+ * own event-id and clock dependencies, so request and test instances cannot
+ * overwrite one another through module state.
+ */
+interface DomainEventFactory {
+  /**
+   * Creates immutable technical recording data in the application shell.
+   */
+  readonly createStamp: (options?: CreateDomainEventStampOptions) => DomainEventStamp;
+  readonly create: {
+    <T extends string>(type: T, payload?: undefined, options?: CreateDomainEventOptions): DomainEvent<T, void>;
+    <T extends string, P>(type: T, payload: P, options?: CreateDomainEventOptions): DomainEvent<T, P>;
+  };
+  /**
+   * Reads the captured clock and returns a defensive `Date` copy.
+   * Throws `TypeError` when the clock does not return a valid date.
+   */
+  readonly now: () => Date;
+}
+/**
+ * Creates an immutable, instance-bound domain-event factory.
+ *
+ * The supplied functions are read once and captured by value. The returned
+ * object is frozen, so another request, test, or library cannot replace its
+ * policy. Its {@link DomainEventFactory.createStamp} method is the
+ * application-shell bridge that records an accepted aggregate decision.
+ * Passing the factory through `AggregateConfig`
+ * enables the explicitly named convenience methods, whose defaults read time
+ * and randomness.
+ *
+ * @example
+ * ```ts
+ * const domainEvents = createDomainEventFactory({
+ *   eventIdFactory: () => uuidv7(),
+ *   clock: () => new Date(),
+ * });
+ * order.confirm();
+ * recordPendingEvents(order, domainEvents);
+ * ```
+ */
+declare function createDomainEventFactory(options?: DomainEventFactoryOptions): DomainEventFactory;
+/**
+ * Immutable UUID-v4/platform-clock factory used by the top-level
+ * {@link createDomainEvent}. It cannot be reconfigured; construct an instance
+ * with {@link createDomainEventFactory} for custom policy.
+ */
+declare const defaultDomainEventFactory: DomainEventFactory;
+declare function createUncommittedDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateUncommittedDomainEventOptions): UncommittedDomainEvent<T, void>;
+declare function createUncommittedDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateUncommittedDomainEventOptions): UncommittedDomainEvent<T, P>;
+/**
+ * Attaches shell-owned recording data to an accepted aggregate decision.
+ *
+ * The decision supplies the domain type, payload, source address, and payload
+ * schema version. The stamp supplies only event identity, recording time, and
+ * trace metadata.
+ */
+declare function recordDomainEvent<T extends string, P>(event: UncommittedDomainEvent<T, P>, stamp: DomainEventStamp): DomainEvent<T, P>;
+declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateDomainEventOptions): DomainEvent<T, void>;
+declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateDomainEventOptions): DomainEvent<T, P>;
+/**
+ * Creates an already minted domain event exclusively from explicit envelope
+ * facts. Unlike {@link createDomainEvent}, it has no clock or event-id fallback
+ * and is useful when replay, migration, or a caller-owned boundary already has
+ * the final identity and occurrence time.
+ *
+ * Aggregate behavior normally creates an {@link UncommittedDomainEvent} through
+ * its protected `createEvent` helper. The application shell later records that
+ * pending fact with caller-owned time and identity.
+ */
+declare function createDomainEventFromFacts<T extends string>(type: T, payload: undefined, options: CreateDomainEventFromFactsOptions): DomainEvent<T, void>;
+declare function createDomainEventFromFacts<T extends string, P>(type: T, payload: P, options: CreateDomainEventFromFactsOptions): 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;
+//#endregion
+//#region src/aggregate/aggregate.d.ts
+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.
+   */
+  readonly state: TState;
+  /**
+   * The version of the aggregate when the snapshot was taken.
+   */
+  readonly version: Version;
+  /**
+   * Timestamp when the snapshot was created.
+   */
+  readonly snapshotAt: Date;
+  /**
+   * Schema version of the stored `state` shape, declared by its adapter-owned
+   * `SnapshotModel` and stamped by `captureAggregateSnapshot`. Distinct from
+   * {@link version}, which counts mutations: this field says "which
+   * shape does the stored state have", so a restore can detect a
+   * snapshot written against an older DTO shape and migrate or
+   * discard it instead of crashing later. Optional: absent on snapshots
+   * written by older kit versions, which restore treats as schema `1`.
+   */
+  readonly schemaVersion?: number;
+}
+/**
+ * Public contract every Aggregate Root satisfies. Implemented by
+ * `BaseAggregate` and inherited by both `AggregateRoot` and
+ * `EventSourcedAggregate`. Repository ports use this interface as their
+ * aggregate type rather than depending on concrete base classes, so persistence
+ * orchestration 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. Persistence
+ * facts are readable, but acknowledgement and pending-event disposal are not
+ * part of this surface. `withCommit` and `UnitOfWork` hold that authority.
+ *
+ * @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 extends AnyDomainEvent = never> {
+  readonly id: TId;
+  readonly version: Version;
+  readonly pendingEvents: ReadonlyArray<PendingDomainEvent<TEvent>>;
+}
+/**
+ * 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.findById(id);
+ * // ... some operations ...
+ * const after = await repository.findById(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;
+//#endregion
+//#region src/aggregate/aggregate-address.d.ts
+/**
+ * Stable value address of one aggregate instance.
+ *
+ * Aggregate ids are type-scoped, so the raw id alone is not globally unique:
+ * `SalesOrder 1` and `FulfillmentOrder 1` are different aggregates. Event
+ * streams, snapshots, committed-event sources, and projection checkpoints
+ * therefore carry both fields instead of defining boundary-specific variants.
+ *
+ * `aggregateType` is a stable technical stream category. Renaming it changes
+ * persistence keys and orphans checkpoints unless the stored addresses are
+ * migrated. When bounded contexts share infrastructure and reuse a domain
+ * name, qualify it at the source (`sales.order`, `fulfillment.order`). The kit
+ * deliberately adds no separate `boundedContext` field: qualification remains
+ * the consumer's naming decision.
+ */
+interface AggregateAddress<TAggregateId extends string = string> {
+  readonly aggregateType: string;
+  readonly aggregateId: TAggregateId;
+}
+//#endregion
+//#region src/entity/entity.d.ts
+/** A pure invariant check that throws when a candidate state is invalid. */
+type StateValidator<TState> = (state: TState) => void;
+/**
+ * Construction options shared by `Entity` and (via `AggregateConfig`) the
+ * aggregate base classes.
+ */
+interface EntityConfig<TState = unknown> {
+  /**
+   * Pure state-invariant validator captured by the entity instance. It runs
+   * against the exact frozen state stored during construction and every
+   * {@link Entity.setState} call. Throw to reject the candidate state.
+   *
+   * Passing validation as data avoids virtual dispatch from the base
+   * constructor: the function cannot observe partly initialised subclass
+   * fields through `this`. Close over immutable policy supplied to the
+   * concrete constructor when validation needs instance-specific inputs.
+   */
+  readonly validateState?: StateValidator<TState>;
+  /**
+   * Opt-in: freeze the WHOLE state graph (via `deepFreeze`) instead of
+   * the default shallow freeze. This protects against nested aliases
+   * retained by constructor callers and against accidental in-place
+   * writes inside the entity; live state itself is never public.
+   *
+   * Defaults to `false` (the documented shallow contract): deep freezing
+   * costs a full state-graph walk on every state write, which is why it
+   * is not the default on hot paths.
+   *
+   * **Only for plain-data states.** The deep freeze walks the entire
+   * graph: a class-based child entity inside the state would be frozen
+   * too, and its own mutation methods would start throwing. States
+   * carrying class-based children must keep the default shallow freeze.
+   * Note that the ownership transfer widens accordingly: nested objects
+   * passed into the constructor or `setState` are frozen IN PLACE (the
+   * shallow copy protects only the top-level input object).
+   */
+  deepFreezeState?: boolean;
+}
+/**
+ * Functional definition of an Entity via its capability: an object is
+ * identifiable if it has an `id`.
+ *
+ * `TId` is constrained to `Id<string>` so the brand discipline that
+ * `Id<Tag>` enforces is preserved end-to-end: an `Identifiable<UserId>`
+ * cannot accidentally be paired with an `Identifiable<OrderId>` or with
+ * a plain `string`.
+ */
+type Identifiable<TId extends Id<string>> = {
+  readonly id: TId;
+};
+/**
+ * Interface for Entities with state.
+ *
+ * In Domain-Driven Design, Entities have:
+ * - Identity (id): Distinguishes one entity from another
+ * - State: The attributes/properties of the entity
+ *
+ * Unlike Value Objects (which are immutable and compared by value),
+ * Entities are compared by identity and can have mutable state.
+ *
+ * @template TId - The type of the entity identifier
+ */
+interface IEntity<TId extends Id<string>> extends Identifiable<TId> {
+  /**
+   * Unique identifier of the entity.
+   */
+  readonly id: TId;
+}
+/**
+ * Abstract base class for Entities with state.
+ *
+ * Provides:
+ * - Identity management (id)
+ * - State management
+ * - Instance-bound pure state validation
+ * - Protected state access for domain behavior
+ *
+ * This is the foundation for all Entities in DDD:
+ * - Child Entities within aggregates can extend this
+ * - Aggregate Roots extend this and add version + events
+ *
+ * @template TState - The type of the entity state
+ * @template TId - The type of the entity identifier
+ *
+ * @example
+ * ```typescript
+ * // Child Entity within an aggregate
+ * const validateOrderItemState = (state: OrderItemState): void => {
+ *   if (state.quantity < 1) throw new Error("quantity must be positive");
+ * };
+ *
+ * class OrderItem extends Entity<OrderItemState, ItemId> {
+ *   constructor(id: ItemId, initialState: OrderItemState) {
+ *     super(id, initialState, { validateState: validateOrderItemState });
+ *   }
+ *
+ *   updateQuantity(quantity: number): void {
+ *     // setState runs validateState and re-freezes; a direct
+ *     // `this._state = ...` assignment would skip both.
+ *     this.setState({ ...this.state, quantity });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Entity<TState, TId extends Id<string>> implements IEntity<TId> {
+  readonly id: TId;
+  /**
+   * Returns the live state to subclass domain behavior.
+   *
+   * This accessor is deliberately protected: returning the generic
+   * `TState` publicly would expose the aggregate's live object graph and
+   * let nested mutation bypass behavior, validation, versioning, and
+   * dirty tracking. Concrete entities should expose business-meaningful queries or
+   * detached immutable DTOs. Snapshot projection belongs to an adapter-owned
+   * `SnapshotModel`; persistence code captures an aggregate with
+   * `captureAggregateSnapshot(model, aggregate, snapshotAt)` rather than
+   * asking the entity to create its own persistence memento.
+   */
+  protected get state(): TState;
+  /**
+   * The state is `protected` so that only the subclass can modify it.
+   * Ordinary entity behavior must use {@link setState}; direct assignment
+   * skips instance-bound validation. Kit event-sourcing internals use direct
+   * assignment deliberately because historical evolution must not run
+   * today's decision validator.
+   */
+  protected _state: TState;
+  private readonly _deepFreezeState;
+  private readonly validateState;
+  /**
+   * **State ownership.** Plain-object and array states are shallow-copied
+   * before the freeze, so the caller's own object stays mutable. A CLASS
+   * INSTANCE passed as state is an ownership transfer: it is frozen
+   * in place (a copy would strip its prototype). Do not keep mutating
+   * the instance after handing it to the entity. The same contract
+   * applies to {@link setState}. With
+   * {@link EntityConfig.deepFreezeState} enabled, the ownership transfer
+   * widens to the whole graph: NESTED objects are frozen in place too.
+   *
+   * @throws HostileStateKeyError when a plain-object, null-prototype,
+   * or array state carries an own `"__proto__"` data key; validate and
+   * strip untrusted input at the boundary.
+   */
+  protected constructor(id: TId, initialState: TState, config?: EntityConfig<TState>);
+  /**
+   * Freezes a state value according to this entity's configured freeze
+   * mode: the default shallow freeze, or `deepFreeze` when
+   * {@link EntityConfig.deepFreezeState} was enabled at construction.
+   * Infrastructure-style subclass code that deliberately assigns
+   * `this._state` directly must freeze through this method, not
+   * `freezeShallow`, or the opt-in silently degrades to shallow for that
+   * path. Ordinary domain behavior should use {@link setState} instead.
+   */
+  protected freezeState(value: TState): TState;
+  /**
+   * Sets the state of the entity.
+   * This is a convenience method for state mutations.
+   * Automatically validates `newState` with the instance-bound
+   * {@link EntityConfig.validateState} function.
+   *
+   * 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.
+   *
+   * @param newState - The new state
+   * @throws HostileStateKeyError when the state carries an own
+   * `"__proto__"` data key; the previous state is kept.
+   */
+  protected setState(newState: TState): void;
+}
+/**
+ * Shallow-freezes `value` when it's a non-null object or array, so that
+ * direct property writes throw in strict mode. Returns the value as-is for
+ * primitives. Used internally by `Entity` (via `freezeState`, which picks
+ * shallow or deep per the `deepFreezeState` config) to prevent outside
+ * mutation of state read through the `state` getter without paying the
+ * cost of a deep clone on every read.
+ *
+ * Subclass code that assigns `this._state` directly should freeze through
+ * the protected `freezeState(value)` method rather than calling this
+ * helper, so the configured freeze mode is honored. The export remains
+ * for consumers using it as a standalone utility.
+ */
+declare function freezeShallow<T>(value: T): T;
+/**
+ * Checks if two entities have the same ID.
+ * Works with any object that has an 'id' property.
+ *
+ * @param a - First entity
+ * @param b - Second entity
+ * @returns true if both entities have the same ID, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const item1: OrderItem = { id: itemId1, productId: "prod-1", quantity: 2 };
+ * const item2: OrderItem = { id: itemId2, productId: "prod-2", quantity: 1 };
+ *
+ * sameEntity(item1, item2); // false
+ * sameEntity(item1, item1); // true
+ * ```
+ */
+declare function sameEntity<TId extends Id<string>>(a: Identifiable<TId>, b: Identifiable<TId>): boolean;
+/**
+ * Finds an entity by ID in a collection.
+ * Returns undefined if not found.
+ *
+ * @param entities - Array of entities to search
+ * @param id - The ID to search for
+ * @returns The entity if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 },
+ *   { id: itemId2, productId: "prod-2", quantity: 1 }
+ * ];
+ *
+ * const item = findEntityById(items, itemId1);
+ * // item is { id: itemId1, productId: "prod-1", quantity: 2 }
+ * ```
+ */
+declare function findEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId): T | undefined;
+/**
+ * Checks if an entity with the given ID exists in the collection.
+ *
+ * @param entities - Array of entities to search
+ * @param id - The ID to check for
+ * @returns true if an entity with the ID exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 }
+ * ];
+ *
+ * hasEntityId(items, itemId1); // true
+ * hasEntityId(items, itemId2); // false
+ * ```
+ */
+declare function hasEntityId<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId): boolean;
+/**
+ * Removes an entity with the given ID from the collection. Returns the
+ * ORIGINAL array when the id is absent (structural sharing for the
+ * reference-based dirty tracking; see `updateEntityById`), otherwise a
+ * new array without the entity.
+ *
+ * @param entities - Array of entities
+ * @param id - The ID of the entity to remove
+ * @returns A new array without the entity with the given ID
+ *
+ * @example
+ * ```typescript
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 },
+ *   { id: itemId2, productId: "prod-2", quantity: 1 }
+ * ];
+ *
+ * const updated = removeEntityById(items, itemId1);
+ * // updated is [{ id: itemId2, productId: "prod-2", quantity: 1 }]
+ * ```
+ */
+declare function removeEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId): ReadonlyArray<T>;
+/**
+ * Updates an entity with the given ID in the collection.
+ * Returns a new array with the updated entity.
+ * Structural sharing for adapter-owned persistence projections: returns
+ * the ORIGINAL array when nothing changed (no match, or the element kept
+ * its reference), so a partial-write adapter can skip the untouched
+ * collection; a new array only when an
+ * element reference actually changed. The result is `ReadonlyArray<T>`:
+ * it may BE the (possibly frozen) input; spread it if you need a mutable
+ * copy.
+ *
+ * @param entities - Array of entities
+ * @param id - The ID of the entity to update
+ * @param updater - Function that takes the entity and returns the updated entity
+ * @returns A new array with the updated entity
+ *
+ * @example
+ * ```typescript
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 }
+ * ];
+ *
+ * const updated = updateEntityById(items, itemId1, (item) => ({
+ *   ...item,
+ *   quantity: item.quantity + 1
+ * }));
+ * // updated is [{ id: itemId1, productId: "prod-1", quantity: 3 }]
+ * ```
+ */
+declare function updateEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId, updater: (entity: T) => T): ReadonlyArray<T>;
+/**
+ * Replaces an entity with the given ID in the collection.
+ * Returns a new array with the replaced entity.
+ * Structural sharing for adapter-owned persistence projections: returns
+ * the ORIGINAL array when nothing changed (no match, or the element kept
+ * its reference), so a partial-write adapter can skip the untouched
+ * collection; a new array only when an
+ * element reference actually changed. The result is `ReadonlyArray<T>`:
+ * it may BE the (possibly frozen) input; spread it if you need a mutable
+ * copy.
+ *
+ * @param entities - Array of entities
+ * @param id - The ID of the entity to replace
+ * @param replacement - The replacement entity
+ * @returns A new array with the replaced entity
+ *
+ * @example
+ * ```typescript
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 }
+ * ];
+ *
+ * const updated = replaceEntityById(items, itemId1, {
+ *   id: itemId1,
+ *   productId: "prod-1",
+ *   quantity: 5
+ * });
+ * ```
+ */
+declare function replaceEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId, replacement: T): ReadonlyArray<T>;
+/**
+ * Extracts all IDs from a collection of entities.
+ *
+ * @param entities - Array of entities
+ * @returns Array of entity IDs
+ *
+ * @example
+ * ```typescript
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 },
+ *   { id: itemId2, productId: "prod-2", quantity: 1 }
+ * ];
+ *
+ * const ids = entityIds(items);
+ * // ids is [itemId1, itemId2]
+ * ```
+ */
+declare function entityIds<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>): TId[];
+//#endregion
+//#region src/aggregate/base-aggregate.d.ts
+/** Construction options shared by state-stored and event-sourced aggregates. */
+type AggregateConfig<TState = unknown> = EntityConfig<TState>;
+/**
+ * Shared base for both `AggregateRoot` (state-stored) and
+ * `EventSourcedAggregate`. Carries the lifecycle machinery that's
+ * identical across the two flavours: current version, pending-event
+ * tracking, the kit-internal post-commit acknowledgement capability,
+ * the `markRestored` post-load marker, and the `createEvent` helper
+ * that auto-injects `aggregateId` + `aggregateType` on every event the
+ * aggregate emits. The application shell records the pending decisions
+ * with `recordPendingEvents` before persistence.
+ *
+ * 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) /
+ * Vernon §11 + Greg Young (event-sourced) distinction in how state
+ * is represented; the lifecycle machinery is the same for both.
+ *
+ * @template TState - The type of the aggregate state
+ * @template TId    - The aggregate root identifier
+ * @template TEvent - The domain-event union. Defaults to `never` so
+ *   aggregates without a declared event type cannot emit events
+ *   (emitting any event becomes a compile error).
+ */
+declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never> extends Entity<TState, TId> implements IAggregateRoot<TId, TEvent> {
+  /**
+   * The aggregate's domain type as a string, used to populate
+   * `aggregateType` on events created via {@link createEvent}.
+   *
+   * Subclasses MUST declare this as a string literal:
+   *
+   * ```ts
+   * class Order extends AggregateRoot<OrderState, OrderId, OrderEvent> {
+   *   protected readonly aggregateType = "Order";
+   * }
+   * ```
+   *
+   * 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;
+   * 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
+   * subclass renaming).
+   */
+  protected abstract readonly aggregateType: string;
+  private _version;
+  /**
+   * Version the persistence layer last confirmed for this instance:
+   * `undefined` until the aggregate is reconstituted (`markRestored`) or a
+   * commit is acknowledged. Kit-internal via the lifecycle capability; it
+   * grounds the `withCommit` unique-cursor guard so an eventful commit that
+   * did not advance beyond the persisted row is rejected deterministically.
+   */
+  private _persistedVersion;
+  private _pendingEvents;
+  protected constructor(id: TId, initialState: TState, config?: AggregateConfig<TState>);
+  private acknowledgePendingEvents;
+  /**
+   * Post-commit cleanup for the deleted disposition. The row is gone, so
+   * there is no persisted version to advance: stamping the marker from the
+   * live instance would make a later legitimate re-enrollment of this
+   * instance trip the unique-cursor guard for a row that does not exist.
+   */
+  private discardPendingEventsAfterDeletion;
+  private stripAcknowledgedPrefix;
+  get version(): Version;
+  /**
+   * Read-only list of domain events recorded on this aggregate that
+   * have not yet been flushed to the outbox / persistence layer.
+   */
+  get pendingEvents(): ReadonlyArray<PendingDomainEvent<TEvent>>;
+  /**
+   * Count-only accessor for internal aggregate paths: the public
+   * {@link pendingEvents} getter allocates and freezes
+   * a defensive copy per read, which a length check does not need.
+   */
+  protected get pendingEventCount(): number;
+  protected setVersion(version: Version): void;
+  /**
+   * Manually bumps the aggregate version. Used by state-stored
+   * aggregates' `setState()` / `commit()` paths and by the
+   * event-sourced replay path after each applied event.
+   */
+  protected bumpVersion(): void;
+  /**
+   * **Lifecycle marker, Post-Load.** Syncs both `_version` and
+   * the current version to the stored version. Used by
+   * `reconstitute(...)` factories to assemble an in-memory aggregate
+   * from a persisted row.
+   *
+   * The Factory-vs-Reconstitution distinction (Vernon §11) is honoured
+   * structurally: reconstitution stays inside the aggregate factory while
+   * post-commit acknowledgement belongs to application commit orchestration.
+   *
+   * If you override this, call `super.markRestored(version)` so the current
+   * domain version remains aligned with the reconstituted facts.
+   *
+   * @param version - The version the row currently holds in the DB
+   *
+   * @example
+   * ```ts
+   * static reconstitute(id: OrderId, state: OrderState, version: Version): Order {
+   *   const order = new Order(id, state);
+   *   order.markRestored(version);
+   *   return order;
+   * }
+   * ```
+   */
+  protected markRestored(version: Version): void;
+  /**
+   * Appends a domain event to the pending list. Prefer the higher-level
+   * `AggregateRoot.commit()` (state-stored) or `EventSourcedAggregate.apply()`
+   * (event-sourced) call sites, both of which wrap `addDomainEvent` in the
+   * canonical record-AFTER-mutation order (Vernon §8). Calling
+   * `addDomainEvent` directly is appropriate only after a version-advancing
+   * state mutation, or while constructing a never-persisted aggregate.
+   * An event-only commit on an already-persisted aggregate has no unique
+   * cursor and `withCommit` rejects it; use `commit(currentState, event)`.
+   */
+  protected addDomainEvent(event: PendingDomainEvent<TEvent>): void;
+  /**
+   * Immutability gate for every recording path: only events minted by
+   * the kit's constructors (`createDomainEvent`,
+   * `createDomainEventFromFacts`, `createEvent`) pass,
+   * checked against the constructor's internal, unforgeable mint
+   * marker. Minted implies deeply frozen with defensively copied
+   * payload and metadata, a guarantee no frozen-ness probe can
+   * establish (a shallow-frozen literal with mutable nested data
+   * would fool it). O(1): one WeakSet lookup.
+   */
+  protected assertMintedEvent(event: PendingDomainEvent<TEvent>): void;
+  /**
+   * Creates the immutable business fact accepted by this aggregate without
+   * reading a clock, generating an id, or attaching tracing metadata.
+   *
+   * The application shell records pending events after the domain operation
+   * and before persistence. Payload schema version stays here, next to the
+   * concrete event producer, rather than in shell-owned recording data.
+   */
+  protected createEvent<E extends TEvent>(type: E["type"], payload: E["payload"], options?: Omit<CreateUncommittedDomainEventOptions, "aggregateId" | "aggregateType">): UncommittedDomainEventOf<E>;
+}
+//#endregion
+//#region src/aggregate/aggregate-root.d.ts
+/**
+ * OO-first Aggregate Root for state-stored domain models.
+ *
+ * The aggregate owns identity, valid domain state, behavior, its current
+ * domain version, and pending domain events. It deliberately does not own a
+ * database baseline or dirty-key bookkeeping. A repository adapter defines
+ * its persistence projection through `PersistenceModel`; the Unit of Work
+ * retains that opaque baseline and derives the adapter's change set at flush.
+ */
+declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never> extends BaseAggregate<TState, TId, TEvent> {
+  /**
+   * Changes state and records the resulting facts in record-after-mutation
+   * order. Validation and event mint checks run before the transition becomes
+   * observable, so a rejected decision records nothing.
+   */
+  protected commit(newState: TState, events?: PendingDomainEvent<TEvent> | readonly PendingDomainEvent<TEvent>[]): void;
+  /** Every normal domain-state transition advances the OCC version. */
+  protected setState(newState: TState): void;
+  /**
+   * Replaces loss-tolerant derived state without advancing the domain version.
+   *
+   * This is intentionally loud: concurrent writers may overwrite such a
+   * change. Keep business facts on the normal `setState`/`commit` path.
+   */
+  protected setStateWithoutVersionBump(newState: TState): void;
+}
+//#endregion
+//#region src/events/json-value.d.ts
+/** A primitive value represented without loss by JSON. */
+type JsonPrimitive = boolean | null | number | string;
+/** A recursively JSON-safe value. Runtime validation rejects lossy shapes. */
+type JsonValue = JsonPrimitive | ReadonlyArray<JsonValue> | {
+  readonly [key: string]: JsonValue;
+};
+/** A JSON-safe object. */
+type JsonObject = {
+  readonly [key: string]: JsonValue;
+};
+//#endregion
+//#region src/app/command.d.ts
+/**
+ * Marker interface for Commands.
+ * Commands represent write operations that change system state.
+ * They should be immutable and contain all data needed to perform the operation.
+ *
+ * This interface can be used as a type marker even when using external frameworks
+ * (e.g., RabbitMQ, AWS SQS) to ensure type safety across different bus implementations.
+ *
+ * @example
+ * ```typescript
+ * type CreateOrderCommand = Command & {
+ *   type: "CreateOrder";
+ *   customerId: string;
+ *   items: OrderItem[];
+ * };
+ * ```
+ *
+ * @example Using with external frameworks (RabbitMQ, etc.)
+ * ```typescript
+ * // Define command using Command marker
+ * type CreateOrderCommand = Command & {
+ *   type: "CreateOrder";
+ *   customerId: string;
+ * };
+ *
+ * // Handler can be typed with CommandHandler even for external frameworks
+ * const handler: CommandHandler<CreateOrderCommand, OrderId> = async (cmd) => {
+ *   // ... handler logic
+ *   return ok(orderId);
+ * };
+ *
+ * // The consumer owns this runtime decoder. It checks byte and collection
+ * // ceilings, parses to unknown, allow-lists fields, and constructs domain types.
+ * declare function decodeCreateOrderCommand(
+ *   body: Uint8Array,
+ *   principal: AuthenticatedPrincipal,
+ * ): Result<CreateOrderCommand, InvalidCommand>;
+ * declare function decodeMessageId(
+ *   value: unknown,
+ * ): Result<string, InvalidTransportMetadata>;
+ * declare function createOrderDeliveryKey(messageId: string): string;
+ *
+ * // This application service invokes the handler through withIdempotentCommit.
+ * // createOrderDeliveryKey scopes the message id by consumer. The service
+ * // fingerprints the complete CreateOrder intention and commits that claim,
+ * // the aggregate write, outbox entries, and outcome together.
+ * declare function executeIdempotentCreateOrder(
+ *   deliveryKey: string,
+ *   command: CreateOrderCommand,
+ * ): Promise<Result<OrderId, string>>;
+ *
+ * // Register with RabbitMQ or another external bus.
+ * rabbitMQChannel.consume("order.commands", async (message) => {
+ *   const messageId = decodeMessageId(message.properties.messageId);
+ *   if (messageId.isErr()) {
+ *     rabbitMQChannel.reject(message, false); // missing identity: dead-letter
+ *     return;
+ *   }
+ *   const deliveryKey = createOrderDeliveryKey(messageId.value);
+ *   const principal = authenticateProducer(message.properties.headers);
+ *   const decoded = decodeCreateOrderCommand(message.content, principal);
+ *   if (decoded.isErr()) {
+ *     rabbitMQChannel.reject(message, false); // invalid input: dead-letter, do not retry
+ *     return;
+ *   }
+ *   const outcome = await executeIdempotentCreateOrder(
+ *     deliveryKey,
+ *     decoded.value,
+ *   );
+ *   await recordCommandOutcome(deliveryKey, outcome);
+ *   rabbitMQChannel.ack(message);
+ * });
+ * ```
+ */
+interface Command {
+  readonly type: string;
+}
+/**
+ * Versioned Published Language for a command that crosses a process or
+ * Bounded-Context boundary. Unlike a local {@link Command}, its payload is
+ * JSON-safe data rather than a domain object graph. Map value objects to their
+ * wire DTOs at this boundary; for example, use `MoneyDto` instead of `Money`.
+ */
+interface PublishedCommand<TType extends string = string, TPayload extends JsonValue = JsonValue> extends Command {
+  readonly type: TType;
+  readonly version: number;
+  readonly payload: TPayload;
+}
+/**
+ * Handler for executing commands.
+ * Commands return Result for explicit error handling.
+ * Commands may modify system state. When a caller can retry or a broker can
+ * redeliver, the application service must enforce idempotency; this handler
+ * type alone does not provide it.
+ *
+ * This type can be used to mark handlers even when using external frameworks
+ * (e.g., RabbitMQ, AWS SQS, Kafka) to ensure type safety and consistency.
+ *
+ * @template C - The command type (must extend Command)
+ * @template R - The result type
+ * @template E - The error channel type. Defaults to `string`; widen it (e.g.
+ *   to a `DomainError` union) to carry typed failures through the bus.
+ *
+ * @example
+ * ```typescript
+ * const handler: CommandHandler<CreateOrderCommand, OrderId> = async (cmd) => {
+ *   const order = Order.create(cmd.customerId, cmd.items);
+ *   repository.add(order);
+ *   return ok(order.id);
+ * };
+ * ```
+ *
+ * @example Using with external frameworks
+ * ```typescript
+ * // Handler typed with CommandHandler for type safety
+ * const createOrderHandler: CommandHandler<CreateOrderCommand, OrderId> = async (cmd) => {
+ *   // ... handler logic
+ *   return ok(orderId);
+ * };
+ *
+ * // The broker adapter validates before calling the application handler.
+ * rabbitMQChannel.consume("commands", async (msg) => {
+ *   const messageId = decodeMessageId(msg.properties.messageId);
+ *   if (messageId.isErr()) {
+ *     rabbitMQChannel.reject(msg, false);
+ *     return;
+ *   }
+ *   const deliveryKey = createOrderDeliveryKey(messageId.value);
+ *   const principal = authenticateProducer(msg.properties.headers);
+ *   const decoded = decodeCreateOrderCommand(msg.content, principal);
+ *   if (decoded.isErr()) {
+ *     rabbitMQChannel.reject(msg, false); // malformed or over limit
+ *     return;
+ *   }
+ *   // executeIdempotentCreateOrder invokes createOrderHandler through the same
+ *   // atomic withIdempotentCommit boundary described in the first example.
+ *   const outcome = await executeIdempotentCreateOrder(
+ *     deliveryKey,
+ *     decoded.value,
+ *   );
+ *   await recordCommandOutcome(deliveryKey, outcome);
+ *   rabbitMQChannel.ack(msg);
+ * });
+ * ```
+ */
+type CommandHandler<C extends Command, R, E = string> = (cmd: C) => Promise<Result<R, E>>;
+//#endregion
+//#region src/utils/execution.d.ts
+/** Cancellation and deadline controls for one bounded shell operation. */
+interface ExecutionContext {
+  /** Cooperative cancellation for the in-flight operation. */
+  readonly signal: AbortSignal;
+  /** Absolute Unix epoch millisecond at which the shell stops waiting. */
+  readonly deadlineAt: number;
+}
+//#endregion
+//#region src/events/ports.d.ts
+/**
+ * Event handler function type for subscribing to domain events. The execution
+ * context carries the publication's cooperative cancellation and deadline;
+ * those runtime controls belong to the imperative shell, never to the domain
+ * event itself.
+ *
+ * @template Evt - The type of domain event
+ */
+type EventHandler<Evt> = (event: Evt, context: ExecutionContext) => Promise<void> | void;
+/** Controls one bounded in-process event publication. */
+interface PublishOptions {
+  /** Owner/request cancellation propagated to every event handler. */
+  readonly signal?: AbortSignal;
+  /** Maximum time to await the complete publication. Default `30000`ms. */
+  readonly timeoutMs?: number;
+}
+/**
+ * Event Bus interface for publishing and subscribing to domain events.
+ * Supports multiple subscribers per event type (pub/sub pattern).
+ *
+ * @template Evt - The type of domain events
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus<OrderEvent>();
+ *
+ * // Subscribe to specific event types
+ * bus.subscribe("OrderCreated", async (event) => {
+ *   await sendEmail(event.payload.customerId);
+ * });
+ *
+ * bus.subscribe("OrderShipped", async (event) => {
+ *   await updateInventory(event.payload.orderId);
+ * });
+ *
+ * // Publish events
+ * await bus.publish([orderCreatedEvent, orderShippedEvent]);
+ * ```
+ */
+interface EventBus<Evt extends AnyDomainEvent> {
+  /**
+   * Publishes events to all subscribed handlers.
+   *
+   * **Ordering & parallelism contract:**
+   *
+   *  1. **Events run in input order.** `publish([a, b, c])` dispatches `a`,
+   *     awaits all of its handlers, then dispatches `b`, and so on. The
+   *     library never reorders or parallelises across events.
+   *  2. **Handlers within a single event run in parallel.** All handlers
+   *     subscribed to `event.type` are awaited via `Promise.allSettled`:
+   *     none of them sees the others' errors and none is skipped if a
+   *     peer fails.
+   *  3. **Errors are collected and thrown AFTER everything dispatches.**
+   *     If one handler throws, remaining handlers for that event still
+   *     run, and remaining events in the batch still publish. Once
+   *     `publish` reaches the end of the batch it throws: the single
+   *     error directly if there was one, or an `AggregateError`
+   *     ("Multiple event handlers failed") containing every captured
+   *     error otherwise. Callers that need fail-fast semantics should
+   *     publish events one at a time and not rely on batch atomicity.
+   *
+   * The contract is intentionally simple and in-process. For
+   * cross-process delivery (RabbitMQ, Kafka, etc.), use the `Outbox`
+   * port and a dedicated dispatcher.
+   *
+   * @param events - Array of events to publish
+   * @param options - Owner cancellation and publication timeout
+   */
+  publish: (events: ReadonlyArray<Evt>, options?: PublishOptions) => Promise<void>;
+  /**
+   * Subscribes a handler to a specific event type.
+   * Multiple handlers can subscribe to the same event type.
+   *
+   * @param eventType - The event type to subscribe to
+   * @param handler - The handler function to call when events of this type are published
+   * @returns A function to unsubscribe the handler
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = bus.subscribe("OrderCreated", async (event) => {
+   *   console.log("Order created:", event.payload.orderId);
+   * });
+   *
+   * // Later: unsubscribe
+   * unsubscribe();
+   * ```
+   */
+  subscribe: <K extends Evt["type"]>(eventType: K, handler: EventHandler<Extract<Evt, {
+    type: K;
+  }>>) => () => void;
+  /**
+   * Subscribes a handler to EVERY event type: the subscription for
+   * cross-cutting consumers (audit log, metrics, dev logging,
+   * forward-all) that would otherwise have to enumerate the union's
+   * event types and silently miss every type added later.
+   *
+   * Catch-all handlers run in the SAME `Promise.allSettled` batch as
+   * the event's typed handlers, so the publish contract is unchanged:
+   * awaited delivery, no handler skipped when a peer fails, errors
+   * collected and thrown after the batch, events in input order.
+   *
+   * Deliberately minimal: no predicate subscriptions (filter in your
+   * handler; it is one line) and no glob/topic patterns (topic routing
+   * belongs to broker sinks: Kafka topics, JetStream subjects).
+   *
+   * @param handler - Called with every published event, typed as the
+   * full event union; narrow via `event.type` in the handler
+   * @returns A function to unsubscribe the handler
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = bus.subscribeAll(async (event) => {
+   *   await auditLog.append(event.type, event.eventId, event.payload);
+   * });
+   * ```
+   */
+  subscribeAll: (handler: EventHandler<Evt>) => () => void;
+  /**
+   * Subscribes to the next occurrence of an event type.
+   * Returns a Promise that resolves with the event data.
+   * Automatically unsubscribes after the first event.
+   *
+   * @param eventType - The event type to wait for
+   * @returns A Promise that resolves with the event
+   *
+   * @example
+   * ```typescript
+   * const event = await bus.once("OrderCreated");
+   * console.log("Order created:", event.payload.orderId);
+   * ```
+   */
+  once: <K extends Evt["type"]>(eventType: K, options?: OnceOptions) => Promise<Extract<Evt, {
+    type: K;
+  }>>;
+}
+/**
+ * Options for `EventBus.once()`. Both fields are optional; without them
+ * `once()` waits forever (the historical behaviour).
+ */
+interface OnceOptions {
+  /**
+   * Aborts the wait. When `signal` fires, `once()` rejects with
+   * `signal.reason` (or a generic abort error if none was supplied) and
+   * the internal subscription is removed.
+   */
+  signal?: AbortSignal;
+  /**
+   * Rejects with a timeout error after this many milliseconds if no event
+   * has arrived. The internal subscription and timer are cleaned up
+   * regardless of which path settles the promise.
+   */
+  timeoutMs?: number;
+}
+/**
+ * Gap-proof position finalized by the event source at the persistence
+ * boundary. It is deliberately separate from `DomainEvent`: these values
+ * describe a stored commit, not the business fact itself.
+ */
+interface CommitPosition {
+  /** Aggregate OCC version reached by this eventful commit. */
+  readonly aggregateVersion: number;
+  /** Zero-based event index inside this aggregate commit. */
+  readonly commitSequence: number;
+  /** Total number of events emitted by this aggregate commit. */
+  readonly commitSize: number;
+  /**
+   * Aggregate version of the immediately preceding EVENTFUL commit for this
+   * qualified aggregate source, or `null` when this is its first eventful
+   * commit. State-only persistence is intentionally absent from this chain.
+   *
+   * The outbox/event-store adapter owns this value. It must read and advance
+   * the source head atomically with inserting the committed event envelope;
+   * application orchestration cannot derive it from the Unit of Work's OCC
+   * receipt because state-only commits are intentionally absent here.
+   */
+  readonly previousEventfulAggregateVersion: number | null;
+}
+/**
+ * Commit information known by the application transaction before the outbox
+ * source has linked this eventful commit to its predecessor.
+ */
+type EventCommitCandidatePosition = Omit<CommitPosition, "previousEventfulAggregateVersion">;
+/**
+ * A bare domain event prepared for the transactional outbox. The outbox source
+ * owns the predecessor link and turns this candidate into a
+ * {@link CommittedDomainEvent} when it persists the record.
+ */
+interface EventCommitCandidate<Evt extends AnyDomainEvent> {
+  readonly event: Evt;
+  readonly source: AggregateAddress;
+  readonly position: EventCommitCandidatePosition;
+}
+/**
+ * A domain event enriched after persistence has established its source and
+ * commit position. Outboxes and projectors consume this envelope; in-process
+ * domain handlers continue to consume the bare {@link DomainEvent} value.
+ */
+interface CommittedDomainEvent<Evt extends AnyDomainEvent> {
+  readonly event: Evt;
+  readonly source: AggregateAddress;
+  readonly position: CommitPosition;
+}
+/**
+ * One pending event in the outbox plus the opaque id the implementation
+ * needs to ack it via `markDispatched`. The library does not prescribe
+ * what `dispatchId` looks like: an implementation can reuse the event's
+ * own `eventId`, generate its own UUID, use the row's auto-increment
+ * primary key, or whatever the storage layer prefers.
+ */
+interface OutboxRecord<Evt extends AnyDomainEvent> extends CommittedDomainEvent<Evt> {
+  dispatchId: string;
+  /**
+   * Failed delivery attempts so far. Populated by implementations that
+   * track dispatch failures (see {@link DispatchTrackingOutbox});
+   * plain `Outbox` implementations may omit it.
+   */
+  attempts?: number;
+}
+/** A record that exhausted its delivery attempts; see {@link DispatchTrackingOutbox.deadLetters}. */
+interface DeadLetterRecord<Evt extends AnyDomainEvent> extends CommittedDomainEvent<Evt> {
+  dispatchId: string;
+  /** Failed delivery attempts when the record was dead-lettered. */
+  attempts: number;
+  /** Human-readable rendering of the last delivery error, if recorded. */
+  lastError?: string;
+}
+/**
+ * Write half of the transactional outbox: the only outbox capability the
+ * write side (`withCommit`, `UnitOfWork`) depends on. Persisting the
+ * events atomically with the aggregate state is the kit's guarantee;
+ * DELIVERY is a separate, replaceable concern.
+ *
+ * Implement ONLY this interface to plug in an external delivery
+ * solution: `add()` writes into that solution's outbox storage inside
+ * the ambient transaction, and its own listener (polling or
+ * WAL/CDC-based, such as a Debezium-style connector, a delivery
+ * library, or a broker-native outbox) owns delivery entirely. The
+ * kit-side poll surface ({@link Outbox}) is then never involved. See
+ * the outbox guide, "External dispatchers".
+ */
+interface OutboxWriter<Evt extends AnyDomainEvent> {
+  /**
+   * Finalizes and persists event commit candidates. Called from inside
+   * `withCommit`'s transactional callback, atomically with the aggregate
+   * write.
+   *
+   * For every qualified aggregate source, the adapter must serialize source
+   * advancement, read its last eventful aggregate version, write that value as
+   * `previousEventfulAggregateVersion` on every event in the candidate's
+   * commit, and advance the source head to `aggregateVersion` in the SAME
+   * transaction. A state-only aggregate commit does not call `add()` and must
+   * therefore not advance this event-source head.
+   *
+   * A qualified source position `(aggregateType, aggregateId,
+   * aggregateVersion, commitSequence)` MUST identify one immutable event. All
+   * candidates for the same aggregate commit MUST also agree on `commitSize`.
+   * Enforce both constraints before advancing the source head; a conflicting
+   * retry must reject without replacing the stored event or changing the head.
+   *
+   * **Idempotency:** implementations should dedupe on
+   * `candidate.event.eventId`. `withCommit` itself does not retry, but the
+   * surrounding use case (a queue consumer, an HTTP retry, a transactional
+   * outbox-dispatcher loop) may legitimately invoke the same write more than
+   * once. A unique-key constraint on `(eventId)` in the outbox table is the
+   * standard implementation; the source-head update and dedupe decision must
+   * share the transaction. Idempotency applies only to an exact candidate
+   * retry: the same event ID, qualified source, aggregate version, commit
+   * sequence, and commit size. Reusing an `eventId` for another source or
+   * position is a caller bug: adapters that retain the conflicting record
+   * should reject it rather than replace or silently reinterpret it as a retry.
+   */
+  add: (events: ReadonlyArray<EventCommitCandidate<Evt>>) => Promise<void>;
+}
+/**
+ * Transactional outbox port: the bridge between the write-side
+ * transaction and the (out-of-band) event dispatcher.
+ *
+ * Lifecycle:
+ *  1. `add()` inside the write transaction (`withCommit` calls this) so
+ *     events persist atomically with the aggregate state
+ *     ({@link OutboxWriter}, the only part the write side needs).
+ *  2. An outbox dispatcher (the kit's `OutboxDispatcher` or your own)
+ *     polls `getPending()` and forwards the events to subscribers /
+ *     external brokers.
+ *  3. After successful dispatch, the dispatcher calls `markDispatched()`
+ *     with the records' `dispatchId`s so they don't come back next poll.
+ *
+ * `markDispatched` is required to be idempotent: calling it with an id
+ * that's already marked is a no-op, not an error. This lets the
+ * dispatcher safely retry on partial-failure.
+ *
+ * **Competing dispatcher instances** are an adapter contract, not a
+ * dispatcher feature: a transactional implementation that should
+ * support several concurrent pollers must make `getPending` claim the
+ * returned records (`FOR UPDATE SKIP LOCKED` or equivalent). Without
+ * claiming, run one logical dispatcher per outbox.
+ *
+ * The bundled dispatcher supplies an {@link ExecutionContext} to every poll-side
+ * operation. Production adapters MUST pass its signal to native I/O or enforce
+ * a native timeout no later than `deadlineAt`; the shell can bound its wait but
+ * cannot terminate a promise that ignores cancellation. A timed-out write has
+ * an unknown outcome. Acknowledgements must remain idempotent when they complete
+ * late; a late failure update may count its original delivery attempt and must
+ * still no-op after the record was dispatched.
+ */
+interface Outbox<Evt extends AnyDomainEvent> extends OutboxWriter<Evt> {
+  /**
+   * Returns up to `limit` outbox records that have not yet been
+   * dispatched, **in the order `add()` persisted them** (commit order).
+   * The ordering is part of the port contract: `withCommit` promises
+   * subscribers per-aggregate causal order, and a sequential dispatcher
+   * can only honor that promise when this read is ordered. SQL-backed
+   * implementations need a monotonic position column (an auto-increment
+   * primary key works) and an `ORDER BY` on it; a bare `SELECT` returns
+   * rows in storage order, not insertion order. The dispatcher polls
+   * this on a schedule. When `limit` is omitted, the implementation
+   * decides on a default page size. The bundled dispatcher always supplies
+   * `context`; it is optional only so existing adapters remain assignable.
+   */
+  getPending: (limit?: number, context?: ExecutionContext) => Promise<ReadonlyArray<OutboxRecord<Evt>>>;
+  /**
+   * Marks the given dispatch records as delivered so subsequent
+   * `getPending` calls don't return them. Must be idempotent on
+   * already-marked ids, including a late completion after the caller's
+   * storage deadline. The bundled dispatcher always supplies `context`.
+   */
+  markDispatched: (dispatchIds: ReadonlyArray<string>, context?: ExecutionContext) => Promise<void>;
+}
+/**
+ * Optional extension of {@link Outbox} for dispatchers that track
+ * delivery failures. Without failure tracking, a poison message (an
+ * event whose delivery always throws) is redelivered forever: it comes
+ * back from every `getPending` poll, blocks per-aggregate ordering
+ * behind it, and burns the dispatcher's cycles. This extension gives
+ * the dispatcher a bounded-retry story: report each failed delivery via
+ * {@link markFailed}; the implementation moves records past its
+ * attempt ceiling to a dead-letter set that `getPending` no longer
+ * returns, and {@link deadLetters} exposes them for alerting, manual
+ * inspection, and redelivery (deliver by hand, then ack via
+ * `markDispatched`, which also clears dead-lettered records).
+ *
+ * See the outbox guide's dispatcher recipe for the retry-then-dead-letter
+ * loop this port shape supports.
+ */
+interface DispatchTrackingOutbox<Evt extends AnyDomainEvent> extends Outbox<Evt> {
+  /**
+   * Records one failed delivery attempt for the given record:
+   * increments its attempt count (surfaced as
+   * {@link OutboxRecord.attempts}) and, once the implementation's
+   * ceiling is reached, moves the record to the dead-letter set.
+   * A no-op for unknown or already-dispatched ids (a late failure
+   * report after a successful retry must not resurrect the record).
+   * Returns the exact dead-letter record only on the call that performs
+   * that transition; retries below the ceiling and no-ops return
+   * `undefined`. This lets productive pollers emit an immediate signal
+   * without scanning the durable dead-letter set after every failure. A late
+   * completion may count that original delivery attempt; it must still no-op if
+   * the record was dispatched in the meantime. The bundled dispatcher never
+   * reissues the same store call and always supplies `context`.
+   */
+  markFailed: (dispatchId: string, error?: unknown, context?: ExecutionContext) => Promise<DeadLetterRecord<Evt> | undefined>;
+  /**
+   * Records that exhausted their delivery attempts. They no longer
+   * come back from `getPending`; wire this to durable alerting and
+   * reconciliation so poison messages surface even if the poller stops
+   * between this store transition and its immediate observer callback.
+   */
+  deadLetters: () => Promise<ReadonlyArray<DeadLetterRecord<Evt>>>;
+}
+//#endregion
+//#region src/app/command-outbox.d.ts
+/**
+ * Business relationships and technical trace context selected explicitly for
+ * an outgoing command. Correlation/conversation explain the business flow;
+ * W3C Trace Context connects technical spans.
+ */
+interface CommandMessageRelationships {
+  /** Groups messages that belong to one operation or trace. */
+  readonly correlationId?: string;
+  /** Groups every message in one long-running business interaction. */
+  readonly conversationId?: string;
+  /** W3C Trace Context parent for technical distributed tracing. */
+  readonly traceparent?: string;
+  /** Optional vendor trace state associated with `traceparent`. */
+  readonly tracestate?: string;
+}
+/**
+ * Application-owned Published Language produced from one private domain or
+ * process event. `destination` names one receiver contract; it is deliberately
+ * required because a command is an instruction, not a broadcast fact.
+ *
+ * The command carries a stable schema `version` and JSON-safe `payload`.
+ * Domain value objects are translated to wire DTOs by the mapper before this
+ * boundary.
+ */
+interface CommandMessageContent<C extends PublishedCommand> extends CommandMessageRelationships {
+  readonly destination: string;
+  readonly command: C;
+}
+/**
+ * Immutable, JSON-safe command envelope stored for later at-least-once
+ * delivery.
+ *
+ * `causationId` always identifies the private event whose accepted decision
+ * requested this command. The mapper cannot replace it with a weaker
+ * correlation. Consumer-produced events should in turn use `messageId` as
+ * their causation id.
+ */
+interface DurableCommandMessage<C extends PublishedCommand> extends CommandMessageContent<C> {
+  readonly messageId: string;
+  readonly recordedAt: string;
+  readonly causationId: string;
+}
+/**
+ * Receipt for the private event that requested one command batch. It retains
+ * commit identity and ordering without putting the private event or its
+ * payload into the command outbox.
+ */
+interface CommandCommitOriginCandidate {
+  readonly eventId: string;
+  readonly source: AggregateAddress;
+  readonly position: EventCommitCandidatePosition;
+}
+/**
+ * One private process-event commit and the exact commands it requested.
+ * `messages` may be empty: the receipt still advances the originating source
+ * and makes an exact retry distinguishable from a missing commit.
+ */
+interface CommandOutboxCommitCandidate<C extends PublishedCommand> {
+  readonly origin: CommandCommitOriginCandidate;
+  readonly messages: ReadonlyArray<DurableCommandMessage<C>>;
+}
+/**
+ * Write port for a dedicated transactional command outbox.
+ *
+ * The adapter is bound to the same ambient transaction as the aggregate or
+ * event-stream repository. It must persist the complete input atomically,
+ * retain input order, deduplicate exact retries by `origin.eventId`, and reject
+ * a reused origin id whose source, position, or messages differ. It also owns
+ * the durable source cursor represented by `origin.position`; an empty command
+ * batch still advances that cursor.
+ *
+ * Delivery is out of band and at least once. A consumer therefore uses
+ * `message.messageId` as its idempotency key and acknowledges only after the
+ * command result has been stored.
+ */
+interface CommandOutboxWriter<C extends PublishedCommand> {
+  add(commits: ReadonlyArray<CommandOutboxCommitCandidate<C>>): Promise<void>;
+}
+/** Maps one private accepted event to zero or more addressed commands. */
+type CommandOutboxMapper<Evt extends AnyDomainEvent, C extends PublishedCommand> = (event: Evt) => ReadonlyArray<CommandMessageContent<C>>;
+/**
+ * Adapts a dedicated command outbox to the event-candidate write port consumed
+ * by `withCommit`.
+ *
+ * Mapping happens inside the transaction, before the command outbox write.
+ * The private event is used only at this boundary and is reduced to an origin
+ * receipt. The helper never publishes it or copies its payload implicitly; the
+ * application mapper selects and translates the data that belongs in the
+ * versioned Published Language. The route rejects values JSON would lose or
+ * change before it calls the adapter.
+ * Every command gets a stable id derived from the event id and its zero-based
+ * order, so an exact transaction retry produces the same rows.
+ *
+ * Omit `withCommit`'s in-process `bus` for private process events. Participants
+ * consume the durable command messages from their explicitly named
+ * destinations, while event-stream replay only rebuilds process state.
+ */
+declare function routeEventsToCommandOutbox<C extends PublishedCommand, Evt extends AnyDomainEvent = AnyDomainEvent>(outbox: CommandOutboxWriter<C>, mapper: CommandOutboxMapper<Evt, C>): OutboxWriter<Evt>;
+//#endregion
+//#region src/repo/scope.d.ts
+/** 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;
+}
+/**
+ * Transaction-scope abstraction.
+ *
+ * Wraps a block of work so it runs inside the persistence layer's native
+ * transaction (Postgres `BEGIN`/`COMMIT`, Mongo session, Drizzle / Prisma
+ * `$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`,
+ * 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
+ * "there is nothing meaningful here" statement, not an accidental
+ * `unknown` fallback.
+ *
+ * Intentionally minimal: the scope itself does no change tracking and
+ * no commit-time flush. Those concerns live in the layers above: a
+ * repository adapter derives its change set, `withCommit` orchestrates the
+ * event lifecycle, and `UnitOfWork` owns tracking and atomic flush. See
+ * "TransactionScope stays minimal; the Unit of Work lives above it" in
+ * docs/guide/design-decisions.md.
+ *
+ * @example Drizzle implementation
+ * ```typescript
+ * class DrizzleScope implements TransactionScope<DrizzleTx> {
+ *   constructor(private db: DrizzleDb) {}
+ *   async transactional<T>(fn: (tx: DrizzleTx) => Promise<T>): Promise<T> {
+ *     return this.db.transaction((tx) => fn(tx));
+ *   }
+ * }
+ * ```
+ *
+ * @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)
+ *   const orderRepository = makeOrderRepository(tx);
+ *
+ *   const order = await orderRepository.getById(orderId);
+ *   order.confirm();
+ *   orderRepository.update(order);
+ * });
+ * ```
+ *
+ * Repository contracts take the id or 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.
+ */
+interface TransactionScope<TCtx> {
+  transactional<T>(fn: (ctx: TCtx) => Promise<T>, options?: TransactionalOptions): Promise<T>;
+}
+//#endregion
+//#region src/app/handler.d.ts
+/** Dependencies for {@link withCommit}. */
+interface WithCommitDeps<Evt extends AnyDomainEvent, TCtx> {
+  /**
+   * The write half of the outbox: `withCommit` only ever calls `add()`.
+   * Pass a full `Outbox` for the kit's poll-based dispatch, or a bare
+   * `OutboxWriter` backed by an external delivery solution.
+   *
+   * Required on purpose, while `bus` is optional: the bus is the
+   * best-effort in-process fast path, the outbox is the delivery
+   * guarantee. Running without delivery reliability is a decision, not
+   * a default; make it explicit with
+   * `outboxWriterAcceptingEventLoss()`.
+   */
+  outbox: OutboxWriter<Evt>;
+  bus?: EventBus<Evt>;
+  scope: TransactionScope<TCtx>;
+  /**
+   * 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.
+   */
+  onPublishError?: (error: unknown, events: ReadonlyArray<Evt>) => void;
+  /**
+   * Application-shell observer invoked for each successfully acknowledged
+   * saved aggregate, after every commit record has completed its internal
+   * acknowledgement attempt. Deleted aggregates do not trigger it. `version`
+   * is the commit-time value captured before any observer runs. Observer
+   * failures are reported through `onPersistError` and never turn an already
+   * committed write into an apparent failure. The execution context carries
+   * owner cancellation and the configured post-commit deadline.
+   */
+  onPersisted?: (aggregate: IAggregateRoot<Id<string>, Evt>, version: Version, context: ExecutionContext) => void | Promise<void>;
+  /**
+   * Observer for post-commit persistence failures: either the internal
+   * acknowledgement/disposal step or the application-shell `onPersisted`
+   * observer. Called once per failure with the error and affected aggregate.
+   * Symmetric with {@link onPublishError}: the
+   * transaction has already committed, so the failure must NOT reject the
+   * write; without this observer it would otherwise vanish silently. The
+   * hook is an observer only: if it throws, its error is swallowed so the
+   * post-commit invariant holds, and the loop continues the remaining
+   * post-commit work.
+   */
+  onPersistError?: (error: unknown, aggregate: IAggregateRoot<Id<string>, Evt>) => void;
+  /**
+   * Total time allotted to the complete post-commit application phase:
+   * every application observer followed by in-process bus publication shares
+   * one absolute deadline. Callbacks that have not started when the deadline is
+   * reached are skipped and reported as timeouts. Defaults to `30000`ms.
+   * Timing out or aborting these best-effort operations is reported through the
+   * matching error observer and never rejects an already committed write.
+   */
+  postCommitTimeoutMs?: number;
+  /**
+   * 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;
+}
+declare const aggregateCommitTokenBrand: unique symbol;
+/**
+ * Opaque receipt that one aggregate was explicitly enrolled in the current
+ * {@link withCommit} invocation. Tokens are minted only by the invocation's
+ * {@link CommitEnrollment} capability and are bound to that invocation at
+ * runtime; a forged token or one retained from an earlier call is rejected
+ * inside the transaction.
+ */
+interface AggregateCommitToken<Evt extends AnyDomainEvent = AnyDomainEvent> {
+  readonly [aggregateCommitTokenBrand]: Evt;
+}
+/**
+ * Invocation-scoped enrollment capability handed to a {@link withCommit}
+ * callback. Call `enrollSaved` only for an aggregate participating in the
+ * repository write, and return every resulting token in `commits`. Omitting
+ * any token rejects the transaction: an enrolled write may not commit without
+ * its event harvest and post-commit acknowledgement. Enrollable instances
+ * must extend `AggregateRoot` or `EventSourcedAggregate`; structural
+ * `IAggregateRoot` lookalikes have no internal lifecycle capability and fail
+ * before commit.
+ */
+interface CommitEnrollment<Evt extends AnyDomainEvent> {
+  enrollSaved(aggregate: IAggregateRoot<Id<string>, Evt>, options?: CommitEnrollmentOptions): AggregateCommitToken<Evt>;
+  /**
+   * Enroll an aggregate whose row is deleted by the current transaction.
+   * Its events are harvested and discarded after commit, but the saved-only
+   * application `onPersisted` observer is not called.
+   */
+  enrollDeleted(aggregate: IAggregateRoot<Id<string>, Evt>, options?: CommitEnrollmentOptions): AggregateCommitToken<Evt>;
+}
+/** OCC baseline associated with one exact commit enrollment. */
+interface CommitEnrollmentOptions {
+  /** Absent for a new aggregate; captured at load for update or removal. */
+  readonly expectedVersion?: Version;
+}
+/** The resolved value of a {@link withCommit} work callback. */
+interface WithCommitWorkResult<Evt extends AnyDomainEvent, R> {
+  result: R;
+  /**
+   * Commit tokens returned by the invocation's enrollment capability.
+   * Every token minted during the callback must appear at least once.
+   * Naked aggregates are intentionally not accepted: touching an aggregate
+   * does not prove that its repository write participated in the transaction.
+   */
+  commits: ReadonlyArray<AggregateCommitToken<Evt>>;
+}
+/**
+ * Helper for executing a write Use Case inside a transaction scope.
+ *
+ * The use-case callback receives an invocation-scoped enrollment capability
+ * and returns opaque commit tokens for the repository writes that completed
+ * in the transaction. `withCommit` owns the post-commit lifecycle (harvest,
+ * outbox, mark-persisted, publish). A naked aggregate is not commit evidence:
+ * merely touching or constructing one must never make it look persisted.
+ *
+ * **Trust boundary.** A token proves invocation-local enrollment, not that the
+ * kit inspected a database write; a generic transaction helper cannot observe
+ * adapter internals. Repository code must enroll only writes participating in
+ * this transaction. `UnitOfWork` centralizes that rule in repository methods.
+ * The opaque, scoped token prevents accidental aggregate smuggling and stale
+ * reuse; it is not a security boundary against code that deliberately lies to
+ * its own persistence capability.
+ *
+ * Order of operations:
+ *  1. `fn(ctx, enrollment)` runs inside `scope.transactional(...)`; domain
+ *     mutations + repo writes happen here. After a repository write has
+ *     enrolled an aggregate, the callback includes that opaque token in its
+ *     `commits` result. Tokens are invocation-bound: forged or stale tokens
+ *     fail before harvest. `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. Each bare domain event is composed into an
+ *     `EventCommitCandidate` carrying its aggregate source and the commit
+ *     facts known by the application. The outbox source atomically links
+ *     that candidate to the preceding eventful commit and persists the
+ *     resulting `CommittedDomainEvent`. The domain event itself is never
+ *     stamped or copied.
+ *
+ *     **Harvest order.** Events are concatenated in the order
+ *     tokens appear in the returned `commits` array, then in
+ *     each aggregate's `pendingEvents` order (insertion order via
+ *     `apply` / `commit` / `addDomainEvent`). So tokens for `[a, b]`
+ *     with `a` emitting `[e1, e2]` and `b` emitting `[e3]` produces
+ *     `outbox.add([envelope(e1), envelope(e2), envelope(e3)])` and
+ *     `bus.publish([e1, e2, e3])` in that exact order.
+ *
+ *     **Two ordering guarantees, not one.** Within a single aggregate
+ *     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
+ *     `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
+ *     too, but parallel dispatchers or message brokers may reorder
+ *     across aggregates at delivery time.
+ *  3. The transaction commits.
+ *  4. **After** the commit, a non-exported capability acknowledges every
+ *     saved enrollment and discards pending events for deleted enrollments.
+ *     Only after the complete commit set is clean does the optional
+ *     application-shell `onPersisted(aggregate, version, context)` observer run for
+ *     saved aggregates. Deleted rows never trigger that observer.
+ *  5. `bus.publish(events)` fires for the in-process fast path (skipped
+ *     when no events or no `bus` is wired).
+ *
+ * Publishing AFTER commit prevents the classic "publish before commit"
+ * footgun: in-process subscribers can never react to events from a
+ * transaction that later rolled back. If `bus.publish` itself throws, the
+ * outbox still holds the events and an outbox-dispatcher will deliver
+ * them (eventual consistency).
+ *
+ * **A `bus.publish` failure never rejects `withCommit`.** Once the
+ * 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
+ * the outbox. The hook is an observer: if it throws, its error is
+ * swallowed so the post-commit invariant holds.
+ * The complete application-observer and bus-publication phase shares one
+ * absolute `postCommitTimeoutMs` budget (30 seconds by default); later callbacks
+ * are not started once it expires. A timeout or owner abort is reported
+ * through the same observer paths and never changes the committed result.
+ *
+ * If the transaction rolls back, no acknowledgement occurs: the aggregate
+ * keeps its pending events, so the caller can retry or discard the instance.
+ *
+ * Enrollment captures an exact version and event batch. Re-enrolling the same
+ * aggregate after it changes rejects. `UnitOfWork` additionally seals the
+ * adapter persistence projection and rejects later mutation before flush. For
+ * direct `withCommit` use, make domain decisions first, write, and enroll last.
+ *
+ * **Duplicate enrollment is idempotent by reference.** Enrolling the same
+ * instance repeatedly returns the same token, and a repeated token in
+ * `commits` is harvested once. A repeat call that omits `expectedVersion`
+ * makes no OCC assertion; only a supplied value that contradicts the
+ * enrollment-time baseline rejects. Each event lands in the outbox exactly once
+ * and post-commit acknowledgement runs exactly once. Two
+ * *different* instances with the same logical id cannot be detected
+ * at this layer; that is a Repository contract violation (failure to
+ * maintain Fowler's Identity Map per Unit of Work). See
+ * `docs/guide/repository.md` → "Identity Map: one instance per
+ * aggregate per Unit of Work" for the requirement on repository
+ * implementations that makes this dedupe sound.
+ *
+ * @example Tx-bound repos (Drizzle, Prisma, Mongo, …)
+ * ```typescript
+ * const result = await withCommit({ outbox, bus, scope }, async (tx, enrollment) => {
+ *   const orderRepository = makeOrderRepository(tx); // your factory binds tx to the repo
+ *   const order = await orderRepository.getById(orderId);
+ *   order.confirm();
+ *   await persistOrder(tx, order);                 // low-level adapter write
+ *   const commit = enrollment.enrollSaved(order);   // attest the repository write
+ *   return { result: order.id, commits: [commit] };
+ * });
+ * ```
+ */
+declare function withCommit<Evt extends AnyDomainEvent, R, TCtx>(deps: WithCommitDeps<Evt, TCtx>, fn: (ctx: TCtx, enrollment: CommitEnrollment<Evt>) => Promise<WithCommitWorkResult<Evt, R>>): Promise<R>;
+//#endregion
+//#region src/app/idempotency.d.ts
+/**
+ * Result of `IdempotencyStore.claim()`: this execution owns the key and must
+ * run the command (`claimed`), a previous execution completed and its outcome
+ * is replayed (`completed`), or an expired staged outcome needs evidence from
+ * the authoritative write model (`reconciliation-required`).
+ *
+ * The two FAILURE answers are thrown, not returned, following the kit's
+ * error posture: a concurrent unfinished execution throws
+ * `IdempotencyInFlightError` (retryable), and the same key arriving
+ * with a different fingerprint throws `IdempotencyKeyReuseError`
+ * (not retryable).
+ */
+interface IdempotencyLease {
+  /** Adapter-clock expiry as a canonical ISO-8601 timestamp. */
+  readonly expiresAt: string;
+  /** Delay after which the wrapper should renew this lease. */
+  readonly renewAfterMs: number;
+}
+/** Store-minted ownership receipt for one successful claim. */
+interface IdempotencyClaimHandle {
+  readonly key: string;
+  /** Unique across ownership generations for this key; treat as opaque. */
+  readonly token: string;
+  /** Absent for a transactional store; required for a leased store. */
+  readonly lease?: IdempotencyLease;
+}
+/** Receipt for an expired staged outcome that needs authoritative evidence. */
+interface IdempotencyReconciliation {
+  readonly key: string;
+  readonly fingerprint: string;
+  readonly token: string;
+  readonly expiredAt: string;
+}
+type IdempotencyReconciliationDecision = "committed" | "not-committed" | "unknown";
+type IdempotencyClaim = {
+  readonly status: "claimed";
+  readonly claim: IdempotencyClaimHandle;
+} | {
+  readonly status: "completed";
+  readonly outcome: unknown;
+} | {
+  readonly status: "reconciliation-required";
+  readonly reconciliation: IdempotencyReconciliation;
+};
+/**
+ * Driven port for command idempotency and message-inbox deduplication.
+ *
+ * The store keeps one record per idempotency key: the key, a
+ * fingerprint of the command that first claimed it, and, once the
+ * execution completed, the stored outcome. The intended integration is
+ * the SINGLE-TRANSACTION pattern via {@link withIdempotentCommit}: the
+ * record is written in the same transaction as the aggregate and the
+ * outbox, so a rollback releases the claim and there is no crash window
+ * between claim and commit.
+ *
+ * Adapter contract (mirror of the repository/event-store delegation
+ * model): the adapter maps its store's native signals onto the kit's
+ * errors instead of leaking driver errors:
+ *
+ * - unique-constraint conflict from a CONCURRENT uncommitted claim ->
+ *   `IdempotencyInFlightError` (retryable; a retry replays the outcome
+ *   or claims fresh),
+ * - existing COMPLETED record with the same fingerprint -> return
+ *   `{ status: "completed", outcome }`,
+ * - existing record with a DIFFERENT fingerprint ->
+ *   `IdempotencyKeyReuseError`.
+ *
+ * **Transactional vs leased non-transactional stores.** A transactional
+ * adapter (the record lives in the same database as the aggregate)
+ * gets the commit boundary for free: `complete` is atomic with the
+ * command's commit, a rollback releases everything, and `confirm` /
+ * `abandon` / `renew` / `reconcile` are no-ops. This remains the recommended
+ * production pattern and the only family that proves atomic command effect +
+ * idempotency completion without reconciliation.
+ *
+ * A NON-transactional store (the in-memory reference, a separate durable
+ * store) cannot see commits or rollbacks. Every fresh claim therefore returns
+ * a store-minted token and bounded lease. The wrapper renews it while the
+ * transaction runs; `complete`, `renew`, `confirm`, `abandon`, and `reconcile`
+ * compare the token so a stale owner cannot mutate a successor claim. An
+ * expired PENDING claim may be replaced. An expired STAGED outcome is never
+ * replayed or released automatically: `claim` returns
+ * `reconciliation-required`, and the application must consult the source of
+ * truth. `unknown` keeps it blocked.
+ *
+ * A lease is coordination, not a security or exactly-once boundary. To return
+ * `not-committed` safely, the source transaction must persist an idempotency
+ * key or claim token (available as the callback's `execution` argument), or
+ * offer equivalent durable fencing proving the old transaction cannot still
+ * commit. Without that evidence, return `unknown`. A database row merely being
+ * absent while an old transaction may still be in flight is not proof.
+ * A takeover can overlap briefly with the stale worker, so `fn` must keep
+ * irreversible external side effects out of the transaction. Persist an
+ * outbox record and deliver after commit; token fencing can stop the stale
+ * database commit, but it cannot undo an HTTP call already sent.
+ *
+ * The same store doubles as a message INBOX: use the message id as the
+ * key and a constant fingerprint; a duplicate delivery replays the
+ * stored (possibly `undefined`) outcome instead of re-running the
+ * handler.
+ *
+ * The stored outcome must be PLAIN, serialisable data (the same
+ * discipline as snapshots and event payloads): the record round-trips
+ * through the adapter's storage, so class instances would silently lose
+ * their prototype.
+ *
+ * @template TCtx - The transaction context the surrounding scope
+ *   exposes (Drizzle `tx`, Prisma `tx`, `undefined` for context-free
+ *   scopes). `claim` and `complete` run inside that transaction.
+ */
+interface IdempotencyStore<TCtx = unknown> {
+  /**
+   * Claims the key for this execution, atomically with respect to
+   * concurrent claimers (`INSERT ... ON CONFLICT` or equivalent).
+   * Returns `claimed` when this execution owns the key, or
+   * `completed` with the stored outcome when a previous execution
+   * already finished under the same key and fingerprint. Throws
+   * `IdempotencyInFlightError` / `IdempotencyKeyReuseError` for the
+   * failure answers (see the port docs). A live staged outcome is in-flight;
+   * after its lease expires it returns `reconciliation-required`, never a
+   * replay or fresh claim.
+   */
+  claim(ctx: TCtx, key: string, fingerprint: string): Promise<IdempotencyClaim>;
+  /**
+   * Stores the outcome for a key this execution claimed, in the same
+   * transaction as the command's writes. On a transactional store the
+   * commit makes it durable and replayable; on a non-transactional
+   * store the outcome is only STAGED until {@link confirm} runs.
+   * Throws `IdempotencyCompletionWithoutClaimError` when no claim exists, and
+   * `IdempotencyClaimLostError` when the receipt is stale, already settled, or
+   * expired. A stale completion must fail before the source transaction can
+   * commit.
+   */
+  complete(ctx: TCtx, claim: IdempotencyClaimHandle, outcome: unknown): Promise<void>;
+  /**
+   * Extends a non-transactional claim's lease and returns its new timing.
+   * The update is compare-and-set on key + token. A transactional adapter
+   * implements this as a no-op returning `undefined`; the wrapper never calls
+   * it for a claim without a lease.
+   */
+  renew(claim: IdempotencyClaimHandle): Promise<IdempotencyLease | undefined>;
+  /**
+   * Finalizes a staged outcome AFTER the surrounding transaction
+   * committed. Called by {@link withIdempotentCommit} post-commit on
+   * every fresh execution. A transactional adapter implements this as
+   * a no-op (the commit already finalized the record). Idempotent:
+   * confirming an already-confirmed receipt is a no-op. A missing or stale
+   * receipt is also a no-op and must never confirm its successor.
+   */
+  confirm(claim: IdempotencyClaimHandle): Promise<void>;
+  /**
+   * Releases a claim whose attempt did not commit: a pending claim or
+   * a staged, unconfirmed outcome. Called by
+   * {@link withIdempotentCommit} once per failed attempt, best-effort.
+   * A transactional adapter implements this as a no-op: the rollback
+   * already removed the row, and the method must be SAFE to call when
+   * the commit outcome is unknown; it never releases a confirmed
+   * record. A stale receipt is a no-op and must never release its successor.
+   */
+  abandon(claim: IdempotencyClaimHandle): Promise<void>;
+  /**
+   * Resolves an EXPIRED staged outcome after the application consulted its
+   * authoritative write model. `committed` makes the staged result replayable;
+   * `not-committed` releases it for a fresh execution. `unknown` is
+   * intentionally not accepted here: uncertainty must preserve the record.
+   * The receipt is compare-and-set so a stale reconciler cannot settle a newer
+   * owner. Transactional adapters implement this as a no-op because they never
+   * return `reconciliation-required`.
+   */
+  reconcile(reconciliation: IdempotencyReconciliation, decision: Exclude<IdempotencyReconciliationDecision, "unknown">): Promise<void>;
+}
+/** Identifies one logical command execution for {@link withIdempotentCommit}. */
+interface IdempotentCommitRequest {
+  /**
+   * The idempotency key: client-supplied header, message id, or a key
+   * derived from actor + intention. One key names one logical command.
+   */
+  readonly key: string;
+  /**
+   * Fingerprint of the command's content (a hash or canonical string
+   * of the request payload). Detects the same key being reused for a
+   * DIFFERENT command, which is rejected instead of replayed.
+   */
+  readonly fingerprint: string;
+}
+/**
+ * Outcome of {@link withIdempotentCommit}: `replayed: false` carries the
+ * fresh result of this execution; `replayed: true` carries the stored
+ * outcome of the previous execution with the same key and fingerprint.
+ * The replayed value is typed `R` on the strength of the fingerprint
+ * match: the same command was executed, so the stored outcome has the
+ * shape this command produces, provided the adapter round-trips plain
+ * data faithfully.
+ */
+interface IdempotentCommitResult<R> {
+  readonly replayed: boolean;
+  readonly result: R;
+}
+/** Claim identity visible to work that persists a source-of-truth marker. */
+interface IdempotentExecution extends IdempotentCommitRequest {
+  readonly claimToken: string;
+}
+interface IdempotencyOperationErrorContext {
+  readonly operation: "abandon" | "confirm" | "renew";
+  readonly key: string;
+  readonly token: string;
+}
+interface WithIdempotentCommitDeps<Evt extends AnyDomainEvent, TCtx> extends WithCommitDeps<Evt, TCtx> {
+  idempotency: IdempotencyStore<TCtx>;
+  /**
+   * Source-of-truth decision for an expired staged outcome. The callback must
+   * return `committed` only when the command effect is durably visible, and
+   * `not-committed` only when a durable marker proves the attempt cannot still
+   * commit. `unknown` keeps the key blocked.
+   */
+  reconcileIdempotency?: (reconciliation: IdempotencyReconciliation, ctx: TCtx) => Promise<IdempotencyReconciliationDecision>;
+  /**
+   * Observer for best-effort post-commit confirm, rollback abandon, and a
+   * secondary heartbeat failure masked by the primary work error.
+   */
+  onIdempotencyError?: (error: unknown, context: IdempotencyOperationErrorContext) => void;
+}
+/**
+ * {@link withCommit} with command idempotency: the duplicate-safe write
+ * path for retryable deliveries (client retries, at-least-once
+ * messages, scheduler re-runs).
+ *
+ * Order of operations:
+ *  1. Inside the transaction, `store.claim(ctx, key, fingerprint)` runs
+ *     FIRST. A completed execution short-circuits without touching the domain.
+ *     An expired staged outcome invokes `reconcileIdempotency`; `committed`
+ *     replays it, `not-committed` releases and claims fresh, and `unknown` (or
+ *     no callback) throws `IdempotencyReconciliationRequiredError` without
+ *     changing the store.
+ *  2. A fresh claim carries an opaque ownership token. For a leased store the
+ *     wrapper renews it at `renewAfterMs` until the transaction callback is
+ *     ready to commit. A renewal failure rejects before commit and releases
+ *     the claim. `fn(ctx, enrollment, execution)` receives the same token so a
+ *     source-side marker can make later reconciliation conclusive.
+ *  3. `store.complete(ctx, claim, fn's result)` stages or completes the outcome
+ *     in the same transaction as aggregate writes and outbox. The enrollment
+ *     capability is sealed and its token array copied before `complete` can
+ *     yield, so leaked callback state cannot change the harvest receipt.
+ *  4. After commit, `store.confirm(claim)` finalizes a leased store's staged
+ *     outcome; it is a no-op for transactional stores. A failure cannot reject
+ *     an already committed write, so it is sent to `onIdempotencyError` and the
+ *     record later enters reconciliation after lease expiry.
+ *  5. Any pre-commit failure releases that exact token through
+ *     `store.abandon(claim)` before leaving the transactional region. A stale
+ *     abandon cannot release a successor. Secondary abandon/renew failures are
+ *     observable but never mask the primary error.
+ *
+ * Composes with `RetryingTransactionScope`: a retryable failure inside
+ * one attempt releases that attempt's claim, and the retry either
+ * executes fresh or, when a concurrent execution completed meanwhile,
+ * replays its confirmed outcome. A concurrent duplicate while the first
+ * execution is still running surfaces as `IdempotencyInFlightError`
+ * (retryable); unwrapped, map it to a conflict/retry-later application
+ * outcome.
+ *
+ * The stored outcome is `fn`'s `result` value; it must be plain, serialisable
+ * data (see {@link IdempotencyStore}). Transactional storage remains the
+ * production default. Leases make the non-transactional family recoverable;
+ * they do not manufacture an atomic exactly-once boundary across two stores.
+ */
+declare function withIdempotentCommit<Evt extends AnyDomainEvent, R, TCtx>(deps: WithIdempotentCommitDeps<Evt, TCtx>, request: IdempotentCommitRequest, fn: (ctx: TCtx, enrollment: CommitEnrollment<Evt>, execution: IdempotentExecution) => Promise<WithCommitWorkResult<Evt, R>>): Promise<IdempotentCommitResult<R>>;
+//#endregion
+//#region src/deadlines/deadline-store.d.ts
+/**
+ * One deadline due for delivery, as returned by
+ * {@link DeadlineStore.due}. `deliveryId` identifies this scheduled
+ * INCARNATION of the deadline, not the `(scope, key)` address: a
+ * reschedule replaces the incarnation, and acknowledging a stale
+ * incarnation must never consume the new one (see
+ * {@link DeadlineStore.markDelivered}).
+ */
+interface DueDeadline<TPayload = unknown> {
+  /** Opaque per-incarnation id used for `markDelivered`/`markFailed`. */
+  readonly deliveryId: string;
+  /** The namespace half of the address, e.g. a process or policy name. */
+  readonly scope: string;
+  /** The instance half of the address, e.g. a saga or reservation id. */
+  readonly key: string;
+  /** When the deadline was due. */
+  readonly dueAt: Date;
+  /** The payload handed back as the input; plain data only. */
+  readonly payload: TPayload;
+  /** Failed delivery attempts so far (see `markFailed`). */
+  readonly attempts: number;
+}
+/** A deadline that exhausted its delivery attempts; see {@link DeadlineStore.deadLetters}. */
+interface DeadLetterDeadline<TPayload = unknown> extends DueDeadline<TPayload> {
+  /** Human-readable rendering of the last delivery error, if recorded. */
+  readonly lastError?: string;
+}
+/**
+ * Driven port for durable deadlines: timeout-as-input. A process that
+ * waits ("if PaymentReceived has not arrived in 30 minutes,
+ * compensate"; "release the reservation hold after 15 minutes";
+ * "expire the offer at month's end") schedules a deadline, and a poll
+ * loop later DELIVERS it as an input to whatever owns the decision, a
+ * saga aggregate, a use case, a policy. The store never executes
+ * consumer code; firing a deadline means handing back a record.
+ *
+ * Deliberately general-purpose and deliberately small. This is not a
+ * scheduler framework and not a cron abstraction: there is no
+ * recurrence, no execution engine, and the poll loop belongs to the
+ * consumer (the outbox guide's `drainOnce` pattern fits; the deadlines
+ * guide shows the wiring).
+ *
+ * Addressing is the `(scope, key)` pair, so one table serves every
+ * waiting process in an application: `scope` names the policy
+ * ("checkout-saga", "reservation-hold"), `key` the instance. There is
+ * at most ONE pending deadline per address; `schedule` on an existing
+ * address replaces it (that IS the reschedule operation), and each
+ * scheduling gets a fresh `deliveryId`, so acknowledgements of a
+ * replaced incarnation cannot consume its successor.
+ *
+ * Two sides, two transactional postures, the same split as the outbox:
+ *
+ * - **`schedule` and `cancel` are write-side calls** and must join the
+ *   ambient write transaction (use a tx-bound store instance inside
+ *   `withCommit`'s callback, exactly like an outbox adapter). This is
+ *   a correctness rule, not a preference: state that says "waiting for
+ *   payment" committed without its deadline is a process that never
+ *   wakes up, and a deadline scheduled for a rolled-back state change
+ *   is a ghost input.
+ * - **`due`, `markDelivered`, `markFailed`, and `deadLetters` are the
+ *   poll surface** and run out of band, in the consumer's loop.
+ *
+ * Delivery is at-least-once: a crash between processing and
+ * `markDelivered` redelivers, so consumers make deadline handling
+ * idempotent (the idempotency store with the `deliveryId` as key is
+ * the ready-made answer). Deadlines have no cross-key ordering
+ * obligations, so unlike the outbox a poison deadline blocks only
+ * itself; bounded retries still matter, which is why failure tracking
+ * is part of the port rather than an extension: report failed
+ * deliveries via `markFailed`, and the store dead-letters a deadline
+ * past its attempt ceiling.
+ *
+ * Run one logical poller per store unless your adapter's `due` claims
+ * records for competing pollers; the same rule as the outbox
+ * dispatcher.
+ *
+ * The bundled processor supplies an `ExecutionContext` to every poll-side
+ * operation. Production adapters MUST pass its signal to native I/O or enforce
+ * a native timeout no later than `deadlineAt`; the shell can bound its wait but
+ * cannot terminate a promise that ignores cancellation. A timed-out write has
+ * an unknown outcome. Acknowledgements must remain idempotent when they complete
+ * late; a late failure update may count its original delivery attempt and must
+ * still no-op after the incarnation was delivered or replaced.
+ *
+ * Verify an adapter with `createDeadlineStoreContractTests` from
+ * `@shirudo/ddd-kit/testing`; `InMemoryDeadlineStore` is the
+ * reference.
+ *
+ * @template TPayload - The payload shape carried from `schedule` to
+ * delivery; plain, serializable data (the same discipline as event
+ * payloads and snapshots)
+ */
+interface DeadlineStore<TPayload = unknown> {
+  /**
+   * Schedules (or reschedules) the deadline at `(scope, key)`: at most
+   * one pending deadline exists per address, and scheduling an
+   * occupied address replaces its due time, payload, attempt count,
+   * and incarnation. Called inside the write transaction.
+   */
+  schedule(deadline: {
+    scope: string;
+    key: string;
+    dueAt: Date;
+    payload: TPayload;
+  }): Promise<void>;
+  /**
+   * Removes the pending deadline at `(scope, key)`; a no-op when none
+   * exists (the awaited input arrived in time and the wait is over).
+   * Called inside the write transaction.
+   */
+  cancel(scope: string, key: string): Promise<void>;
+  /**
+   * Up to `limit` deadlines with `dueAt <= now` that are neither
+   * delivered nor dead-lettered, ordered by `dueAt` (earliest first;
+   * ties in scheduling order). A `limit` of `0` is legal and yields an
+   * empty page (poll loops computing a remaining capacity may pass
+   * it). `now` is a parameter on purpose: the poll loop owns the
+   * clock, which keeps adapters deterministic and tests free of real
+   * time. The bundled processor always supplies `context`; it is optional only
+   * so existing adapters remain assignable.
+   */
+  due(now: Date, limit: number, context?: ExecutionContext): Promise<ReadonlyArray<DueDeadline<TPayload>>>;
+  /**
+   * Acknowledges delivered incarnations so they stop coming back.
+   * Idempotent on already-acknowledged and unknown ids, and a no-op
+   * for ids of REPLACED incarnations (a late ack after a reschedule
+   * must not consume the successor). Also clears a dead-lettered
+   * incarnation (manual redelivery, then ack). It remains idempotent if the
+   * operation completes after the caller timed out. The bundled processor
+   * always supplies `context`.
+   */
+  markDelivered(deliveryIds: ReadonlyArray<string>, context?: ExecutionContext): Promise<void>;
+  /**
+   * Records one failed delivery attempt for the incarnation:
+   * increments its `attempts` and, once the store's ceiling is
+   * reached, moves it to the dead-letter set that `due` no longer
+   * returns. A no-op for unknown, delivered, or replaced ids.
+   * Returns the exact dead-letter record only on the call that performs
+   * that transition; retries below the ceiling and no-ops return
+   * `undefined`. A late completion may count that original delivery attempt; it
+   * must still no-op if the incarnation was delivered or replaced in the
+   * meantime. The bundled processor never reissues the same store call and
+   * always supplies `context`.
+   */
+  markFailed(deliveryId: string, error?: unknown, context?: ExecutionContext): Promise<DeadLetterDeadline<TPayload> | undefined>;
+  /**
+   * Deadlines that exhausted their delivery attempts. Wire this to durable
+   * alerting and reconciliation: a growing set means processes that stopped
+   * waking up, and the poller can stop between the store transition and its
+   * immediate observer callback.
+   */
+  deadLetters(): Promise<ReadonlyArray<DeadLetterDeadline<TPayload>>>;
+}
+//#endregion
+//#region src/projections/ports.d.ts
+/**
+ * A projection's gap-proof cursor into one aggregate's commit chain.
+ * `aggregateVersion` plus `commitSequence` orders events; `commitSize`
+ * proves the current commit is complete; `previousEventfulAggregateVersion`
+ * links the next commit to the eventful predecessor. `withCommit` supplies
+ * the current commit facts; the event source finalizes the predecessor on the
+ * surrounding `CommittedDomainEvent`.
+ *
+ * A source MUST map exactly one immutable receipt to each qualified position:
+ * one `eventId`, one `commitSize`, and one eventful predecessor. Custom
+ * envelopes may translate another store's cursor into these fields, but
+ * changing any part of an already observed receipt destroys the proof and is
+ * a source-adapter bug.
+ */
+type ProjectionPosition = CommitPosition;
+/**
+ * Durable receipt for the last event one projection applied from an aggregate
+ * stream. The position answers "how far?"; `lastAppliedEventId` identifies the
+ * event at exactly that watermark. Together they let the projector distinguish
+ * a true watermark redelivery from a source changing the event identity,
+ * commit cardinality, or predecessor at the same position. Older positions
+ * still rely on the source's immutable-receipt-per-position contract because a
+ * checkpoint deliberately retains no full history.
+ */
+interface ProjectionCheckpoint {
+  readonly position: ProjectionPosition;
+  readonly lastAppliedEventId: string;
+}
+/**
+ * `true` when `candidate` comes strictly after `reference` in the
+ * per-aggregate tuple order (higher version, or same version and higher
+ * commit sequence). This comparison alone does not prove continuity;
+ * the projector checks the boundary fields before advancing.
+ */
+declare function isPositionAfter(candidate: ProjectionPosition, reference: ProjectionPosition): boolean;
+/**
+ * Driven port for projection checkpoints: the per-`(projection,
+ * aggregateType, aggregateId)` watermark receipt that makes a projection
+ * idempotent and rebuild-safe. The {@link
+ * ProjectionCheckpointStore.withCheckpointLocks} callback and every
+ * {@link ProjectionCheckpointStore.load} / {@link
+ * ProjectionCheckpointStore.save} it contains run inside the SAME transaction
+ * as the read-model update (the `Projector` guarantees the pairing); the store
+ * itself is a dumb last-write-wins record, monotonicity is the projector's job.
+ *
+ * Production adapters put the checkpoint table in the same database
+ * as the read model, so update and checkpoint commit atomically: a
+ * checkpoint without its update loses events, an update without its
+ * checkpoint replays work. Verify an adapter with
+ * `createProjectionCheckpointStoreContractTests` from
+ * `@shirudo/ddd-kit/testing`.
+ *
+ * @template TCtx - The transaction context of the ambient
+ * `TransactionScope` (a knex trx, a drizzle tx, a pg client)
+ */
+interface ProjectionCheckpointStore<TCtx = unknown> {
+  /**
+   * Runs the complete checkpoint read / read-model update / checkpoint save
+   * critical section with exclusive access to every supplied
+   * `(projection, aggregateType, aggregateId)` key.
+   *
+   * Exclusivity MUST cover keys for which no checkpoint row exists yet. A
+   * plain `SELECT ... FOR UPDATE` against the checkpoint table is therefore
+   * insufficient at genesis: use transaction-scoped advisory/key locks, or
+   * first materialize durable lock rows and lock those. Acquire multiple keys
+   * in a deterministic order to avoid deadlocks, and keep database locks until
+   * the surrounding transaction commits or rolls back. On entry, `work` must
+   * observe checkpoint commits made by the preceding lock holder; choose the
+   * transaction isolation level accordingly, or surface and retry a
+   * serialization conflict instead of applying against a stale snapshot.
+   *
+   * Implementations may serialize more than the requested keys, but never
+   * less. The callback is non-reentrant for an overlapping key set.
+   */
+  withCheckpointLocks<R>(ctx: TCtx, projection: string, addresses: ReadonlyArray<AggregateAddress>, work: () => Promise<R>): Promise<R>;
+  /**
+   * The stored watermark receipt for `(projection, address)`, or `undefined`
+   * when this projection has never applied an event of that
+   * aggregate. Called inside the projector's transaction.
+   */
+  load(ctx: TCtx, projection: string, address: AggregateAddress): Promise<ProjectionCheckpoint | undefined>;
+  /**
+   * Persists the watermark receipt, overwriting a previous one (last write
+   * wins; the projector only calls this with advancing checkpoints).
+   * Called inside the projector's transaction, after the read-model
+   * update it accounts for.
+   */
+  save(ctx: TCtx, projection: string, address: AggregateAddress, checkpoint: ProjectionCheckpoint): Promise<void>;
+  /**
+   * The wait-for-version building block: `true` when the stored
+   * watermark for `(projection, address)` is at or past
+   * `position`. Runs OUTSIDE any transaction (a query-side poll).
+   *
+   * Pass the position of the LAST event your commit emitted: all
+   * events of one commit share the `aggregateVersion`, so comparing
+   * on the version alone would report "reached" while later events
+   * of the same commit are still unapplied.
+   */
+  hasReached(projection: string, address: AggregateAddress, position: ProjectionPosition): Promise<boolean>;
+  /**
+   * Deletes every checkpoint of `projection` (other projections'
+   * checkpoints are untouched): the rebuild entry point. Called
+   * inside the rebuild transaction, together with the projection's
+   * `truncate`, so a rebuild starts from a consistent zero.
+   */
+  reset(ctx: TCtx, projection: string): Promise<void>;
+}
+/**
+ * One projection: the consumer-owned mapping from events to ONE read
+ * model (one table/view per projection; run several `Projector`s for
+ * several read shapes). The kit owns the mechanics around it
+ * (cursor skip, atomic checkpointing, rebuild); the handler owns the
+ * read-model writes.
+ *
+ * The projector feed MUST contain every committed envelope for each aggregate
+ * address it carries, including event types this read model does not use.
+ * Handle those events as explicit no-ops in `apply`: the projector still
+ * advances their cursor. Filtering a broker subscription by event type drops
+ * positions from the source chain and turns the next commit into a real gap.
+ * For correctness-critical read models, use `projectionFromHandlers` to make
+ * every event in the declared union a compile-time handler-or-ignore decision;
+ * implement this interface directly when intentionally partial routing is the
+ * better fit.
+ */
+interface Projection<Evt extends AnyDomainEvent, TCtx = unknown> {
+  /**
+   * Stable unique name; keys the checkpoints. Renaming it orphans the
+   * old checkpoints and replays everything under the new name.
+   */
+  name: string;
+  /**
+   * Applies ONE event's read-model change inside the ambient
+   * transaction. The projector's cursor already filtered duplicates
+   * and stale events, so plain writes are safe; route on
+   * `event.type` and handle creates, updates, deletes, corrections,
+   * and tombstones explicitly (an upsert-only handler silently
+   * retains stale rows). For a known event type this projection does not use,
+   * return without writing; that explicit no-op still consumes and checkpoints
+   * the envelope's source position.
+   *
+   * MUST be side-effect-free beyond the read model: no mails, no
+   * external calls, no commands. A rebuild replays every event; side
+   * effects would fire again.
+   */
+  apply(ctx: TCtx, event: Evt): Promise<void>;
+  /**
+   * Optional: clears the read model, called by `Projector.reset()`
+   * in the same transaction as the checkpoint reset, so a rebuild
+   * never observes a half-cleared state. Without it, truncating the
+   * read model before a rebuild is the caller's responsibility.
+   */
+  truncate?(ctx: TCtx): Promise<void>;
+}
+//#endregion
+//#region src/repo/event-store.d.ts
+/** Options for {@link EventStore.append}. */
+interface EventStoreAppendOptions {
+  /**
+   * The stream version the writer loaded (its optimistic-concurrency
+   * baseline): the number of events the stream held when the aggregate
+   * was reconstituted. `0` for a brand-new stream. `UnitOfWork` captures
+   * this value when the adapter returns a loaded aggregate; it is not stored
+   * on the aggregate itself.
+   */
+  readonly expectedVersion: number;
+}
+/** Options for {@link EventStore.readStream}. */
+interface ReadStreamOptions {
+  /**
+   * Maximum number of events returned by this page. Required so callers
+   * cannot accidentally materialize an unbounded stream. Must be a positive
+   * safe integer. An adapter may return fewer events, but must return at least
+   * one while unread events remain inside the requested window.
+   */
+  readonly limit: number;
+  /**
+   * Return only events AFTER this stream position (1-based event count),
+   * the snapshot catch-up read: `readStream(stream, { fromVersion:
+   * snapshot.version, limit: 256 })` yields the next page passed to
+   * `aggregate.loadFromHistory`. Defaults to `0` (the first
+   * stream page).
+   * Must be a non-negative safe integer when present.
+   */
+  readonly fromVersion?: number;
+  /**
+   * Return events only THROUGH this stream position (inclusive, 1-based
+   * event count). Together with `fromVersion`, this describes the interval
+   * `(fromVersion, toVersion]`. Defaults to the actual stream head.
+   * `0` therefore returns an empty window; a value beyond the head clamps
+   * to the head; and `fromVersion >= toVersion` is an empty interval, not
+   * an error.
+   * Must be a non-negative safe integer when present.
+   */
+  readonly toVersion?: number;
+}
+/**
+ * State returned by {@link EventStore.readStream}.
+ *
+ * `lastVersion` is always the actual stream head (the event count), independent
+ * of the requested read window and page limit. `exists: true` implies
+ * `lastVersion >= 1`: an
+ * existing stream has at least one event, while metadata or tombstones without
+ * events must be reported as `exists: false`. A missing stream is therefore
+ * distinguishable from an existing stream whose requested window is empty.
+ * Snapshot-backed repositories use that distinction to reject a snapshot whose
+ * version lies beyond the current authoritative stream head.
+ */
+type StreamReadResult<Evt extends AnyDomainEvent> = {
+  readonly exists: false;
+  readonly lastVersion: 0;
+  readonly events: readonly [];
+} | {
+  readonly exists: true;
+  readonly lastVersion: number;
+  readonly events: ReadonlyArray<Evt>;
+};
+/**
+ * Driven port for event-sourced aggregate persistence: an append-only
+ * store with one stream per aggregate. Each stream is addressed by the
+ * qualified tuple `(aggregateType, aggregateId)`, because aggregate ids
+ * are type-scoped rather than globally unique.
+ *
+ * The kit ships the port, the OCC error contract, `InMemoryEventStore`
+ * as the reference implementation, and the event-sourced repository
+ * contract suites (`createEventStoreContractTests` and
+ * `createEsRepositoryContractTests` from `@shirudo/ddd-kit/testing`).
+ * Your adapter implements this port against a real store and must pass
+ * those suites. Like the state-stored repository contract, its optimistic
+ * concurrency and key isolation are testable adapter contracts, not kit
+ * guarantees.
+ *
+ * Repository usage (see the event-sourcing guide):
+ *
+ * ```ts
+ * private stream(id: OrderId): AggregateAddress<OrderId> {
+ *   return { aggregateType: "Order", aggregateId: id };
+ * }
+ *
+ * async findById(id: OrderId): Promise<Order | undefined> {
+ *   const cached = this.tracking.identityMap.get(Order, id);
+ *   if (cached) return cached;
+ *   const address = this.stream(id);
+ *   const order = Order.reconstitute(id); // bare instance, no events
+ *   let fromVersion = 0;
+ *   let targetVersion: number | undefined;
+ *   for (;;) {
+ *     const page = await this.eventStore.readStream(address, {
+ *       fromVersion,
+ *       toVersion: targetVersion,
+ *       limit: 256,
+ *     });
+ *     if (!page.exists) return undefined;
+ *     targetVersion ??= page.lastVersion; // pin the first observed head
+ *     if (fromVersion === targetVersion) break;
+ *     if (page.events.length === 0) {
+ *       throw new NonProgressingEventStreamPageError({
+ *         ...address,
+ *         fromVersion,
+ *         targetVersion,
+ *       });
+ *     }
+ *     const result = order.loadFromHistory(page.events);
+ *     if (result.isErr()) throw result.error; // corrupt stream
+ *     fromVersion += page.events.length;
+ *   }
+ *   return this.tracking.trackLoaded(order);
+ * }
+ *
+ * flush(write: AggregatePersistenceWrite<Order, number | undefined>) {
+ *   return this.eventStore.append(this.stream(write.aggregateId), write.events, {
+ *     expectedVersion: write.expectedVersion ?? 0,
+ *   });
+ * }
+ * ```
+ *
+ * `flush` appends the exact event batch registered by `add` or `update`;
+ * `withCommit`
+ * separately composes them into outbox envelopes. The event store's own
+ * stream position remains the ordering authority for replay.
+ *
+ * The exact appended event batch is acknowledged only after the surrounding
+ * transaction commits. Rollback leaves it pending.
+ */
+interface EventStore<Evt extends AnyDomainEvent> {
+  /**
+   * Atomically appends `events` to the stream, guarded by optimistic
+   * concurrency: the append succeeds only when the stream currently
+   * holds exactly `options.expectedVersion` events.
+   *
+   * Contract for implementations:
+   *
+   *  1. **OCC:** on a version mismatch (stale writer, duplicate create
+   *     racing on `expectedVersion: 0`, or an expectedVersion ahead of
+   *     the stream), throw `ConcurrencyConflictError` from
+   *     `@shirudo/ddd-kit` carrying the expected and actual stream
+   *     versions; map your store's native conflict signal to it instead
+   *     of letting a raw driver error escape. One sanctioned exception:
+   *     an adapter that can DISTINGUISH the duplicate-create race
+   *     (`expectedVersion: 0` against a stream that already exists,
+   *     typically a unique violation on the first position) may throw
+   *     `DuplicateAggregateError` for that case instead, matching the
+   *     state-stored insert path. It is deliberately NOT retryable:
+   *     replaying the same append cannot succeed; the use case resolves
+   *     the create race (load the existing aggregate, or surface HTTP
+   *     409). The contract suite accepts both errors for this race.
+   *  2. **Atomicity:** all events land or none do; a rejected append
+   *     leaves the stream untouched.
+   *  3. **Qualified identity:** `(aggregateType, aggregateId)` is the
+   *     storage key. Equal raw ids under different aggregate types are
+   *     independent streams. Use both columns in every primary/unique
+   *     key, OCC predicate, and read predicate.
+   *  4. **Order:** events are stored in the given array order, appended
+   *     after the existing stream tail.
+   *  5. **Append-only:** stored events are never edited or deleted;
+   *     corrections are new (compensating) events.
+   *  6. **Replay integrity:** reads order by the persisted stream position
+   *     and reject duplicate or non-contiguous positions where the backing
+   *     store exposes them. The portable contract suite proves observable
+   *     append order and slicing; because the port cannot inject malformed
+   *     physical rows, adapters add a store-specific corruption fixture that
+   *     proves the duplicate/gap rejection. The repository then calls
+   *     `loadFromHistory`, whose replay guard rejects any event carrying an
+   *     aggregate type or id that contradicts this stream key.
+   *
+   * An empty `events` array is a no-op; implementations resolve without
+   * touching the store (an ES repository skips `append` for aggregates
+   * without pending events anyway).
+   *
+   * Treat `aggregateType` as a stable technical stream category. If two
+   * bounded contexts share one physical store and reuse a domain name,
+   * qualify it at the source (`sales.order`, `fulfillment.order`). Renaming
+   * it changes the stream key and therefore requires a data migration.
+   */
+  append(stream: AggregateAddress, events: ReadonlyArray<Evt>, options: EventStoreAppendOptions): Promise<void>;
+  /**
+   * Reads one bounded page of the qualified stream in append order. An unknown stream returns
+   * `{ exists: false, lastVersion: 0, events: [] }`; an existing stream keeps
+   * `exists: true` even when its requested window is empty. An existing stream
+   * has at least one event, so `exists: true` implies `lastVersion >= 1`;
+   * metadata or tombstones without events must be reported as absent.
+   * `lastVersion` is always the actual stream head. `options.limit` is
+   * mandatory and caps the returned array. An adapter may return fewer than
+   * the requested limit, but if the requested window still contains unread
+   * events it must return a non-empty contiguous prefix so callers can make
+   * progress. `options.fromVersion`
+   * excludes positions at or below its 1-based event count;
+   * `options.toVersion` includes positions through its count, so both bounds
+   * describe `(fromVersion, toVersion]`. `toVersion: 0` and inverted ranges
+   * return an empty existing window, while a bound beyond the head clamps to
+   * the head. This distinction is load-bearing for snapshot catch-up and
+   * point-in-time reconstruction: a repository can verify the requested
+   * historical window against the authoritative head. `limit` must be a
+   * positive safe integer; present bounds must be non-negative safe integers.
+   * Invalid options reject with `RangeError` before querying storage.
+   *
+   * Each page's `exists`, `lastVersion`, and `events` must describe one
+   * consistent view of the stream. Multiple page reads are not one database
+   * snapshot: pin the first page's `lastVersion` as `toVersion` on every
+   * continuation, then advance `fromVersion` by the number of events actually
+   * returned. Because streams are append-only, that yields a stable prefix
+   * even if new events arrive while replay is in progress. The returned
+   * event array is owned by the caller; implementations must not hand out
+   * mutable live internal state.
+   */
+  readStream(stream: AggregateAddress, options: ReadStreamOptions): Promise<StreamReadResult<Evt>>;
+}
+//#endregion
+//#region src/repo/snapshot-store.d.ts
+/**
+ * Driven port for aggregate snapshot persistence: the storage half of
+ * the snapshot-plus-recent-events load path for event-sourced aggregates.
+ * `SnapshotModel` owns projection, migration, and reconstitution;
+ * `EventStore.readStream` supplies the catch-up tail to `loadFromHistory`.
+ *
+ * **A snapshot is derived data, never authority.** The stream remains
+ * the source of truth; a snapshot only shortens replay. That shapes
+ * the port:
+ *
+ * - **Transaction-free by design.** Unlike the outbox or the
+ *   idempotency store, saving a snapshot does NOT belong in the write
+ *   transaction: write it after the commit, out of band, on whatever
+ *   cadence your policy picks. A lost save costs replay time, not
+ *   correctness; a stale snapshot is caught up by the event tail.
+ * - **Latest only.** One snapshot per `(aggregateType, aggregateId)`;
+ *   `save` replaces the previous one. Snapshot history has no reader
+ *   in this load path.
+ * - **WHEN to snapshot is policy and stays with the consumer** (every
+ *   N events after commit is the usual shape); the kit ships the port,
+ *   not the policy.
+ *
+ * Contract for implementations (verified by
+ * `createSnapshotStoreContractTests` from `@shirudo/ddd-kit/testing`):
+ * the snapshot round-trips verbatim (`state` as plain data,
+ * `version`, `snapshotAt` with millisecond fidelity, `schemaVersion`
+ * including its absence), loads return detached copies (never live
+ * internal state), and keys are isolated per aggregate type AND id
+ * (one table may serve every aggregate type).
+ *
+ * @template TState - The adapter-owned snapshot DTO shape; a store shared
+ * across aggregate types is a
+ * `SnapshotStore<unknown>` with typed views per repository
+ */
+interface SnapshotStore<TState = unknown> {
+  /**
+   * The latest snapshot for the aggregate, or `undefined` when none
+   * exists. The repository falls back to a full replay then.
+   */
+  load(address: AggregateAddress): Promise<AggregateSnapshot<TState> | undefined>;
+  /**
+   * Persists `snapshot` as the new latest for the aggregate,
+   * replacing any previous one. Called AFTER the write transaction
+   * committed (see the port docs); a single-row upsert is the
+   * standard implementation.
+   */
+  save(address: AggregateAddress, snapshot: AggregateSnapshot<TState>): Promise<void>;
+  /**
+   * Removes the aggregate's snapshot; a no-op when none exists. The
+   * two callers: the schema-migration fallback (a
+   * `SnapshotSchemaMismatchError` or corrupt snapshot during adapter
+   * reconstitution discards the snapshot and refolds from the full stream)
+   * and erasure (a snapshot duplicates aggregate state and follows
+   * the same retention rules). When erasing, delete the snapshot
+   * BEFORE the event stream: the reverse order has a crash window in
+   * which a stale snapshot resurrects the erased aggregate on the
+   * snapshot load path; snapshot-first degrades to a full replay.
+   */
+  delete(address: AggregateAddress): Promise<void>;
+}
+//#endregion
+export { OutboxWriter as $, ClockFactory as $t, WithCommitWorkResult as A, AnyDomainEvent as At, DurableCommandMessage as B, EventIdFactory as Bt, IdempotentExecution as C, updateEntityById as Ct, CommitEnrollment as D, IEventSourcedAggregate as Dt, AggregateCommitToken as E, IAggregateRoot as Et, CommandMessageContent as F, CreateUncommittedDomainEventOptions as Ft, DispatchTrackingOutbox as G, copyMetadata as Gt, CommitPosition as H, PendingDomainEvent as Ht, CommandMessageRelationships as I, DomainEvent as It, EventCommitCandidatePosition as J, createDomainEventFromFacts as Jt, EventBus as K, createDomainEvent as Kt, CommandOutboxCommitCandidate as L, DomainEventFactory as Lt, TransactionScope as M, CreateDomainEventFromFactsOptions as Mt, TransactionalOptions as N, CreateDomainEventOptions as Nt, CommitEnrollmentOptions as O, Version as Ot, CommandCommitOriginCandidate as P, CreateDomainEventStampOptions as Pt, OutboxRecord as Q, recordDomainEvent as Qt, CommandOutboxMapper as R, DomainEventFactoryOptions as Rt, IdempotentCommitResult as S, sameEntity as St, withIdempotentCommit as T, AggregateSnapshot as Tt, CommittedDomainEvent as U, UncommittedDomainEvent as Ut, routeEventsToCommandOutbox as V, EventMetadata as Vt, DeadLetterRecord as W, UncommittedDomainEventOf as Wt, OnceOptions as X, defaultDomainEventFactory as Xt, EventHandler as Y, createUncommittedDomainEvent as Yt, Outbox as Z, mergeMetadata as Zt, IdempotencyOperationErrorContext as _, findEntityById as _t, StreamReadResult as a, JsonObject as at, IdempotencyStore as b, removeEntityById as bt, ProjectionCheckpointStore as c, AggregateRoot as ct, DeadLetterDeadline as d, Entity as dt, Id as en, PublishOptions as et, DeadlineStore as f, EntityConfig as ft, IdempotencyLease as g, entityIds as gt, IdempotencyClaimHandle as h, StateValidator as ht, ReadStreamOptions as i, PublishedCommand as it, withCommit as j, AnyUncommittedDomainEvent as jt, WithCommitDeps as k, sameVersion as kt, ProjectionPosition as l, AggregateConfig as lt, IdempotencyClaim as m, Identifiable as mt, EventStore as n, Command as nt, Projection as o, JsonPrimitive as ot, DueDeadline as p, IEntity as pt, EventCommitCandidate as q, createDomainEventFactory as qt, EventStoreAppendOptions as r, CommandHandler as rt, ProjectionCheckpoint as s, JsonValue as st, SnapshotStore as t, IdGenerator as tn, ExecutionContext as tt, isPositionAfter as u, BaseAggregate as ut, IdempotencyReconciliation as v, freezeShallow as vt, WithIdempotentCommitDeps as w, AggregateAddress as wt, IdempotentCommitRequest as x, replaceEntityById as xt, IdempotencyReconciliationDecision as y, hasEntityId as yt, CommandOutboxWriter as z, DomainEventStamp as zt };
+//# sourceMappingURL=snapshot-store.d.ts.map