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

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

@@ -0,0 +1,2824 @@
+import { f as DomainError, ot as ReplayRejectedError } from "./kit-errors.js";
+import { Result } from "@shirudo/result";
+//#region src/internal/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/application/cqrs/command/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/domain/aggregate/aggregate-identity.d.ts
+/**
+ * The identity of one aggregate instance, as a value.
+ *
+ * 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 aggregate
+ * identities 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 AggregateIdentity<TAggregateId extends string = string> {
+  readonly aggregateType: string;
+  readonly aggregateId: TAggregateId;
+}
+//#endregion
+//#region src/domain/event/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/domain/event/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`. It is
+   * also not `AggregateSnapshot.schemaVersion`: that field versions the
+   * stored snapshot state shape. The two evolve independently.
+   */
+  readonly schemaVersion: 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 aggregate identity,
+ * 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 schemaVersion: 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 schemaVersion?: 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).
+   */
+  schemaVersion?: 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 schemaVersion?: 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;
+  /**
+   * Origin stamped on every event this factory mints, unless the call site
+   * names one itself.
+   *
+   * A plain value, not a factory like the two above. Those produce a new
+   * value for each event. An origin identifies the system that mints them
+   * and does not change between two of them.
+   */
+  readonly source?: string;
+}
+/**
+ * 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 aggregate
+ * identity, 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.eventId }) }
+ * );
+ * ```
+ */
+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/messaging/committed-event.d.ts
+/**
+ * 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: AggregateIdentity;
+  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: AggregateIdentity;
+  readonly position: CommitPosition;
+}
+//#endregion
+//#region src/internal/async/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/messaging/outbox/ports.d.ts
+/**
+ * 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>;
+  /**
+   * Ends the event sources of removed aggregates. Called from inside
+   * `withCommit`'s transactional callback, after `add()`, atomically with
+   * the removal.
+   *
+   * For every source that has a head, the adapter marks the head as ended
+   * in the SAME transaction. The mark must outlive any retention of heads:
+   * a pruned ended head opens the source again. A source without a head
+   * has no events, so it has no continuity to protect: it stays open, and
+   * its first event starts a new head. After the mark, `add()` must reject
+   * a new event of that source: its aggregate was created again under a
+   * removed identity, which the kit does not support. An exact retry of a
+   * stored event stays idempotent, and ending a source twice is not an
+   * error.
+   */
+  endEventSources: (sources: ReadonlyArray<AggregateIdentity>) => 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/application/cqrs/command/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: AggregateIdentity;
+  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>;
+  /**
+   * Ends the source cursors of removed aggregates, in the same transaction
+   * as the removal. After the mark, `add()` must reject a new commit whose
+   * origin comes from an ended source; an exact retry by `origin.eventId`
+   * stays idempotent. A source without a cursor stays open, and ending a
+   * source twice is not an error. See `OutboxWriter.endEventSources`.
+   */
+  endEventSources(sources: ReadonlyArray<AggregateIdentity>): 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/domain/identity/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/domain/aggregate/aggregate.d.ts
+type Version = number & {
+  readonly __v: true;
+};
+/**
+ * Brands a stored number as an aggregate {@link Version}. A version is a
+ * safe integer of at least zero. Use it in repository adapters instead of
+ * a cast, so a corrupt row value fails here with {@link InvalidVersionError}
+ * and never reaches the optimistic-concurrency cursor.
+ */
+declare function toVersion(value: number): Version;
+/**
+ * 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 and stamped by
+   * the persistence adapter that captures the snapshot. 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: a snapshot without
+   * this field restores as schema `1`. Distinct also from
+   * `DomainEvent.schemaVersion`, which versions one event payload shape.
+   * A payload change and a snapshot state change bump their own field.
+   */
+  readonly schemaVersion?: number;
+}
+/**
+ * Public contract every Aggregate Root satisfies. Implemented by
+ * `BaseAggregate` and inherited by both `StateStoredAggregate` 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. The application shell holds that authority.
+ *
+ * @template TId    - The aggregate root identifier (branded via `Id<Tag>`)
+ * @template TEvent - The domain-event union. Defaults to `AnyDomainEvent`,
+ *   so a bound written as `Aggregate<TId>` admits every aggregate root,
+ *   with or without events.
+ */
+interface Aggregate<TId extends Id<string>, TEvent extends AnyDomainEvent = AnyDomainEvent> {
+  readonly id: TId;
+  /** The aggregate type and the id: the full identity of the aggregate. */
+  readonly aggregateIdentity: AggregateIdentity<TId>;
+  readonly version: Version;
+  readonly pendingEvents: ReadonlyArray<PendingDomainEvent<TEvent>>;
+}
+/**
+ * Public contract for Event-Sourced Aggregate Roots. Extends
+ * `Aggregate` with the replay-from-history boundary.
+ *
+ * @template TId    - The aggregate root identifier
+ * @template TEvent - The union type of all domain events
+ */
+interface ReplayableAggregate<TId extends Id<string>, TEvent extends AnyDomainEvent> extends Aggregate<TId, TEvent> {
+  /**
+   * Reconstitutes the aggregate from an event history. Returns
+   * `Result` because event-stream corruption is an expected
+   * recoverable failure at the infrastructure boundary: a `DomainError`
+   * thrown by a fold arrives as `Err`. Every other failure propagates
+   * after the all-or-nothing rollback. The pending-decisions guard runs
+   * for an empty history as well; an empty history is otherwise a no-op.
+   *
+   * @throws ForeignEventError when a history event names another aggregate
+   * @throws UnreplayableAggregateError when the target carries pending
+   *   decisions, or a fold records one
+   * @throws MissingFoldError when no fold is declared for an event type
+   * @throws FoldReturnedNoStateError when a fold returns `undefined`
+   * @throws HostileStateKeyError when the folded state carries an own
+   *   `__proto__` key
+   */
+  replayHistory(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/messaging/event-bus/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.
+   *
+   * This bounds the WAIT, not the handler. JavaScript cannot terminate a
+   * running promise, so a handler that ignores `context.signal` keeps
+   * running after `publish` rejects, and its side effects still land.
+   * Pass `context.signal` into every I/O call a handler makes.
+   */
+  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`
+   *     and awaits every handler of `a`. Then it dispatches `b`, and so
+   *     on. The bus never changes that order. It never dispatches two
+   *     events at the same time.
+   *  2. **The handlers of one event run in parallel.** The bus awaits
+   *     every handler of `event.type` through `Promise.allSettled`. One
+   *     handler never sees the error of another handler. The bus skips no
+   *     handler when a peer fails. The bus applies no limit here: twenty
+   *     handlers that each open a connection open twenty connections.
+   *     Backpressure belongs to the client that the handler calls.
+   *  3. **The bus collects the errors and throws them after the batch.**
+   *     If one handler throws, the other handlers of that event still
+   *     run, and the remaining events still publish. At the end of the
+   *     batch `publish` throws. One failure throws that error directly.
+   *     Two or more failures throw an `AggregateError` with the message
+   *     "Multiple event handlers failed", which carries every collected
+   *     error. For fail-fast behavior, publish one event for each call.
+   *     A batch is not atomic.
+   *
+   * The contract is intentionally simple and in-process. For delivery
+   * across processes, for example through RabbitMQ or Kafka, use the
+   * `Outbox` port and a dedicated dispatcher.
+   *
+   * **Delivery guarantee.** The port does not promise persistence, retry, or
+   * a dead-letter path. Each implementation states its own guarantee. Work
+   * that must survive a crash belongs behind the `Outbox` port.
+   *
+   * **Handlers must tolerate a second run.** The port never redelivers. A
+   * caller that retries does redeliver, and the handlers of the first
+   * attempt can still run. Make a handler idempotent, or do not retry.
+   *
+   * @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 one handler to a set of event types.
+   *
+   * The returned function releases every subscription it made, so a
+   * consumer that reacts to several types keeps one release instead of
+   * one for each type. Losing one of several releases is how a partial
+   * leak starts.
+   *
+   * A type that appears twice subscribes once: the argument is a set of
+   * types, and delivering the same event twice to one handler would be a
+   * surprise, not a feature. An empty set subscribes nothing and returns
+   * a release that does nothing.
+   *
+   * @param eventTypes - The event types to subscribe to
+   * @param handler - Called with every event of those types, narrowed to
+   * their union
+   * @returns A function that releases all of them, and does nothing when
+   * called again
+   *
+   * @example
+   * ```typescript
+   * const release = bus.subscribeMany(
+   *   ["OrderCreated", "OrderShipped"],
+   *   async (event) => {
+   *     await touchReadModel(event.payload.orderId);
+   *   },
+   * );
+   * ```
+   */
+  subscribeMany: <K extends Evt["type"]>(eventTypes: readonly 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;
+  /**
+   * Releases every subscription and settles every waiter.
+   *
+   * A bus that outlives its scope keeps its handlers alive with it. A
+   * worker that shuts down, a test that tears down, and a request scope
+   * that ends all need one call that leaves the bus holding nothing.
+   *
+   * After this call, `publish`, `subscribe`, `subscribeAll` and `once`
+   * throw. Use after close is a programming bug, and a silent no-op would
+   * look like a delivery that did not happen. A pending `once()` rejects
+   * rather than waiting forever, which is the only waiter the port can
+   * settle: a handler is a callback and learns that no event follows by
+   * not being called again.
+   *
+   * Calling it again does nothing.
+   *
+   * A plain method, not `Symbol.dispose`. A port that declared the symbol
+   * would need `esnext.disposable` in the `lib` of every consumer, only to
+   * typecheck the types of this kit, and that requirement cannot be
+   * declined. Group your own releases instead, as the common mistakes
+   * guide shows.
+   *
+   * This releases the subscriptions. It does not stop a handler that is
+   * already running, because JavaScript cannot terminate a running
+   * promise. Pass `context.signal` into every call a handler makes, and a
+   * publication in flight ends with the handler that honours it.
+   */
+  close: () => 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.
+ */
+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;
+}
+//#endregion
+//#region src/persistence/repository/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;
+  /**
+   * Tells the caller that a new attempt starts. A scope that can open more
+   * than one transaction for one call (a retrying scope) calls it before
+   * each attempt opens its transaction. The caller can then tell a failure
+   * to open the next attempt apart from a failure of the previous one. A
+   * scope that opens one transaction per call can ignore it. A scope that
+   * wraps another scope passes the options on unchanged.
+   */
+  readonly onAttemptStart?: () => void;
+}
+/**
+ * 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/application/cqrs/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: Aggregate<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: Aggregate<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 `StateStoredAggregate` or `EventSourcedAggregate`; structural
+ * `Aggregate` lookalikes have no internal lifecycle capability and fail
+ * before commit.
+ */
+interface CommitEnrollment<Evt extends AnyDomainEvent> {
+  enrollSaved(aggregate: Aggregate<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: Aggregate<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/application/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/application/idempotency/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 on its own, 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/application/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, identities: ReadonlyArray<AggregateIdentity>, work: () => Promise<R>): Promise<R>;
+  /**
+   * The stored watermark receipt for `(projection, identity)`, or `undefined`
+   * when this projection has never applied an event of that
+   * aggregate. Called inside the projector's transaction.
+   */
+  load(ctx: TCtx, projection: string, identity: AggregateIdentity): 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, identity: AggregateIdentity, checkpoint: ProjectionCheckpoint): Promise<void>;
+  /**
+   * The wait-for-version building block: `true` when the stored
+   * watermark for `(projection, identity)` 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, identity: AggregateIdentity, 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
+ * identity 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/persistence/repository/identity-map.d.ts
+/**
+ * A class reference used as the type key of the identity map. Keying
+ * on the CLASS (not a name string) makes collisions impossible by
+ * construction: `Restaurant` and `Booking` are different keys even if
+ * someone names two aggregates identically across modules, and there
+ * is no string-discipline to maintain.
+ *
+ * `Function & { prototype: TAgg }` carries this alone. The kit's aggregate
+ * convention is a **protected constructor** plus static factories, and
+ * TypeScript rejects assigning such a class to a construct-signature type, so
+ * the prototype witness is what accepts them. It infers `TAgg` as well.
+ * Measured: a construct signature beside it changes neither what the type
+ * accepts nor what it infers, and it was the last `any` in the published
+ * types.
+ */
+type AggregateClass<TAgg> = Function & {
+  prototype: TAgg;
+};
+/**
+ * Per-unit-of-work Identity Map (Fowler, PoEAA): within one operation,
+ * one aggregate type+id maps to exactly ONE in-memory instance.
+ *
+ * This is the shipped implementation of the contract the
+ * Repository guide (`docs/guide/repository.md`) places on
+ * `AggregatePersistence` implementations: two `findById(id)` calls in the same
+ * unit of work MUST return the same instance, because commit-token
+ * write registration dedupes by JavaScript object identity. Two instances for
+ * one logical aggregate can otherwise produce two tokens, two harvests,
+ * and two post-commit lifecycle calls.
+ *
+ * Storage is two-level (per-type stores created lazily), so
+ * `Restaurant:123` and `Booking:123` can never collide: the type key
+ * is the aggregate CLASS, not the id alone and not a name string.
+ *
+ * Repository read-path contract:
+ *
+ * ```ts
+ * async findById(id: OrderId): Promise<Order | undefined> {
+ *   const cached = this.tracking.identityMap.get(Order, id);
+ *   if (cached) return cached;
+ *   // Deleted in this unit of work = gone, even if the physical
+ *   // delete is deferred and the row is still visible in the tx.
+ *   if (this.tracking.identityMap.isDeleted(Order, id)) return undefined;
+ *
+ *   const row = await this.loadRow(id);
+ *   if (!row) return undefined;
+ *   const order = Order.reconstitute(row.id, row.state, row.version);
+ *   return this.tracking.trackLoaded(order);
+ * }
+ * ```
+ *
+ * Deletion is final within an operation: {@link delete} removes the
+ * entry AND records a tombstone, so a later {@link set} of the same
+ * type+id throws `AggregateDeletedError`: a second instance of a
+ * deleted aggregate can never sneak back into the unit of work, even
+ * through a repository whose row delete is deferred.
+ *
+ * Lifetime is ONE unit of work: the `UnitOfWork` creates a fresh map
+ * per `run()` and clears it on close. Never cache across operations;
+ * that would silently bypass optimistic concurrency control.
+ */
+declare class IdentityMap {
+  private readonly _stores;
+  private readonly _deleted;
+  private _pendingAtRegistration;
+  /** The cached instance for type+id, or `undefined` (also after {@link delete}). */
+  get<TAgg>(type: AggregateClass<TAgg>, id: Id<string>): TAgg | undefined;
+  /** Whether an instance is registered for type+id (false after {@link delete}). */
+  has<TAgg>(type: AggregateClass<TAgg>, id: Id<string>): boolean;
+  /**
+   * Whether type+id was {@link delete}d in this unit of work. The
+   * read path checks this BEFORE hydrating and returns `null`, so
+   * "deleted in this operation" reads uniformly as not-found,
+   * regardless of whether the repository's physical delete already
+   * removed the row or is deferred within the transaction. Without
+   * the check, a read-only probe of a deleted aggregate would crash
+   * in {@link set} for deferred-write repositories and return `null`
+   * for immediate-write ones.
+   */
+  isDeleted<TAgg>(type: AggregateClass<TAgg>, id: Id<string>): boolean;
+  /**
+   * Registers the hydrated instance under its class and the id of its
+   * `aggregateIdentity`.
+   *
+   * - Re-registering the SAME instance is a no-op (idempotent).
+   * - Registering a DIFFERENT instance for an occupied type+id throws:
+   *   that is precisely the identity-map violation this class exists
+   *   to prevent (the repository hydrated twice instead of checking
+   *   {@link get} first), and letting it pass would double-harvest
+   *   events downstream.
+   * - Registering a type+id that was {@link delete}d in this unit of
+   *   work throws `AggregateDeletedError`: deletion is final within
+   *   the operation.
+   */
+  set<TAgg extends {
+    readonly aggregateIdentity: AggregateIdentity;
+  }>(type: AggregateClass<TAgg>, aggregate: TAgg): void;
+  /**
+   * Registered instances that have recorded MORE pending events than they
+   * carried when first registered (loaded). Used by the unit of work's
+   * end-of-run guard: an aggregate that gained events after load but was
+   * never enrolled would silently drop them. A read-only load, or a
+   * reconstitution that already carried events, shows no increase and is
+   * not reported.
+   */
+  instancesWithNewPendingEvents(): unknown[];
+  /**
+   * Takes back a registration WITHOUT a tombstone: the entry is removed
+   * only when the stored instance IS the given one, and a later
+   * {@link set} of the same type+id stays legal. The Unit of Work calls
+   * this when a registration step fails after {@link set} already ran, so
+   * the failed instance cannot be served by `findById` as a phantom.
+   * This is rollback, not deletion; deletion finality belongs to
+   * {@link delete}.
+   */
+  discard<TAgg>(type: AggregateClass<TAgg>, id: Id<string>, aggregate: TAgg): void;
+  /**
+   * Removes the entry for type+id and records a tombstone: subsequent
+   * {@link get} / {@link has} report absence, and a subsequent
+   * {@link set} of the same type+id throws `AggregateDeletedError`.
+   * The Unit of Work calls this as part of `repository.remove(aggregate)`;
+   * repository adapters receive only the read-only
+   * identity-map view.
+   */
+  delete<TAgg>(type: AggregateClass<TAgg>, id: Id<string>): void;
+  /** Empties all stores and tombstones. Called by the unit of work on close. */
+  clear(): void;
+}
+//#endregion
+//#region src/persistence/repository/persistence-model.d.ts
+/** Whether a baseline represents an existing row or a pending insert. */
+type PersistenceLifecycle = "loaded" | "new";
+/**
+ * Adapter-owned projection and change derivation for one aggregate type.
+ *
+ * The domain model does not implement this contract. A repository adapter
+ * chooses what it persists, how that projection is captured at load, and
+ * whether a change set is a partial diff or a full replacement.
+ */
+interface PersistenceModel<TAggregate, TBaseline, TChangeSet> {
+  /**
+   * Captures the adapter's persistence projection at the current moment.
+   * Return a detached value or an immutable value object: the Unit of Work
+   * retains it as a baseline and cannot make an arbitrary adapter type safe.
+   *
+   * Capture must be deterministic for an unchanged aggregate: the Unit of
+   * Work compares successive captures to detect mutation after write
+   * registration. A capture that embeds ambient values (clock reads,
+   * random ids) would make every commit look mutated. The default
+   * comparison is the package's structural deep equality, which matches
+   * `Set` members and `Map` keys by reference (JS `SameValueZero`
+   * semantics): a capture that re-materializes object Set members or Map
+   * keys on every call must supply {@link captureEquals}.
+   *
+   * A column that the store owns stays out of the capture, for example an
+   * `updatedAt` that the adapter stamps; `flush` writes it. A captured store
+   * column pushes a stale value back on the next write, or it marks every
+   * row as changed.
+   */
+  capture(aggregate: TAggregate): TBaseline;
+  /**
+   * Adapter-owned equality for two captures of the persistence projection.
+   * Optional: the default is the package's structural deep equality (Set
+   * members and Map keys by reference). Supply it when the capture shape
+   * needs domain-specific comparison, for example rebuilt value-object Set
+   * members compared by value.
+   */
+  readonly captureEquals?: (a: TBaseline, b: TBaseline) => boolean;
+  /**
+   * Derives the adapter's write payload from its own baseline.
+   *
+   * `baseline` is absent for a new aggregate. `lifecycle` disambiguates that
+   * case from an adapter whose loaded baseline type itself admits `undefined`.
+   * The returned payload must not share mutable references with the aggregate;
+   * it is the exact value later handed to `flush`.
+   */
+  changes(baseline: TBaseline | undefined, aggregate: TAggregate, lifecycle: PersistenceLifecycle): TChangeSet;
+  /** Tells orchestration whether the derived state write is empty. */
+  isEmpty(changes: TChangeSet): boolean;
+}
+declare const persistenceBaselineBrand: unique symbol;
+/**
+ * Opaque, typed receipt for an adapter-owned persistence baseline.
+ *
+ * It intentionally exposes no data. The Unit of Work may retain the token and
+ * ask the owning adapter capability to derive changes, but cannot branch on or
+ * couple itself to the baseline's shape.
+ */
+interface PersistenceBaseline<TAggregate, TChangeSet> {
+  readonly [persistenceBaselineBrand]: (aggregate: TAggregate) => TChangeSet;
+}
+/** A derived adapter change set plus its adapter-defined emptiness result. */
+interface PersistenceChanges<TChangeSet> {
+  readonly value: TChangeSet;
+  readonly empty: boolean;
+}
+/** Captures a baseline for an aggregate restored by a repository adapter. */
+declare function capturePersistenceBaseline<TAggregate, TBaseline, TChangeSet>(model: PersistenceModel<TAggregate, TBaseline, TChangeSet>, aggregate: TAggregate): PersistenceBaseline<TAggregate, TChangeSet>;
+/** Creates the explicit no-row baseline for a newly added aggregate. */
+declare function insertPersistenceBaseline<TAggregate, TBaseline, TChangeSet>(model: PersistenceModel<TAggregate, TBaseline, TChangeSet>): PersistenceBaseline<TAggregate, TChangeSet>;
+/**
+ * Captures the aggregate's current adapter projection using the capability
+ * carried by an existing baseline. Used to seal persistence-last registration.
+ */
+declare function recapturePersistenceBaseline<TAggregate, TChangeSet>(baseline: PersistenceBaseline<TAggregate, TChangeSet>, aggregate: TAggregate): PersistenceBaseline<TAggregate, TChangeSet>;
+/**
+ * Recaptures the adapter projection and reports whether it drifted from the
+ * baseline's stored capture, using the model's `captureEquals` when supplied
+ * and structural deep equality otherwise.
+ *
+ * This, not `changes()`/`isEmpty()`, is the mutation detector: the
+ * `PersistenceModel` contract explicitly permits a full-replacement change
+ * set whose `isEmpty` is never true, so a non-empty change set proves
+ * nothing about mutation. Comparing capture to capture asks the honest
+ * question independent of the model's diffing strategy. A `"new"` lifecycle
+ * baseline has no stored capture and never reports drift.
+ */
+declare function persistenceProjectionDrifted<TAggregate, TChangeSet>(baseline: PersistenceBaseline<TAggregate, TChangeSet>, aggregate: TAggregate): boolean;
+/** Derives a typed adapter change set without exposing the stored baseline. */
+declare function derivePersistenceChanges<TAggregate, TChangeSet>(baseline: PersistenceBaseline<TAggregate, TChangeSet>, aggregate: TAggregate): PersistenceChanges<TChangeSet>;
+//#endregion
+//#region src/application/unit-of-work/persistence-contract.d.ts
+/** The explicit persistence intent registered for one tracked aggregate. */
+type AggregateWriteIntent = "add" | "update" | "remove";
+/** Read-only Identity Map operations available to repository adapters. */
+type UnitOfWorkIdentityMap = Pick<IdentityMap, "get" | "has" | "isDeleted">;
+/**
+ * Repository-specific tracking capability handed only to its adapter.
+ *
+ * Read paths call {@link RepositoryTracking.trackLoaded} before returning a
+ * restored aggregate.
+ * Write methods exposed to application code are replaced by Unit-of-Work-owned
+ * `add`, `update`, and `remove` registrations, so an adapter implementation of
+ * those methods cannot perform durable I/O early or skip event harvesting.
+ *
+ * Contract for repository implementations:
+ * - `findById(id)` checks `identityMap.get` BEFORE hydrating, treats
+ *   `identityMap.isDeleted` as not-found (`undefined`), and returns
+ *   `tracking.trackLoaded(aggregate)` after hydration. This captures the
+ *   expected version before application code can mutate the instance.
+ * - Adapter objects have no lifecycle methods; the facade installs the
+ *   Unit-of-Work-owned `add`, `update` unless the definition is append-only,
+ *   and `remove` with `physicalRemoval`. An adapter that defines `add`,
+ *   `update`, or `remove` fails with `InvalidRepositoryAdapterError`.
+ * - Other repository methods are reads. A custom method that performs a write
+ *   would bypass the Unit of Work and violates the adapter contract.
+ */
+interface RepositoryTracking<TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> {
+  /**
+   * Registers an aggregate restored by a repository before returning it to
+   * application code. The Unit of Work identity-maps the instance and captures
+   * its current version as the optimistic-concurrency expectation.
+   *
+   * Return the result, not the argument. If the Unit of Work already tracks
+   * an instance with the same identity, the result is that instance: when
+   * two loads of one id overlap, the first tracked instance wins.
+   */
+  trackLoaded(aggregate: TAggregate): TAggregate;
+  /**
+   * Read-only view of the per-operation Identity Map (Fowler): one aggregate type+id,
+   * one in-memory instance. Created fresh per `run()`, cleared on
+   * close; accessing it after close throws
+   * {@link TransactionClosedError}.
+   */
+  readonly identityMap: UnitOfWorkIdentityMap;
+}
+/**
+ * Immutable adapter input for one registered aggregate write.
+ *
+ * `expectedVersion` is captured when a loaded aggregate joins the Unit of
+ * Work and is absent for `add`. `version`, `changes`, and `events` describe
+ * the exact moment at which the application registered its write intent.
+ * Adapters must use the expected/current version pair for their OCC predicate
+ * and must not read mutable write state back from an aggregate reference.
+ *
+ * The predicate itself is adapter code. The compare-and-set must run in the
+ * store's own write statement. The kit does not know the store, so it cannot
+ * write that statement. The kit owns the version pair and
+ * {@link ConcurrencyConflictError}; the repository contract suite proves the
+ * predicate.
+ */
+interface AggregatePersistenceWrite<TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TChangeSet> {
+  readonly intent: AggregateWriteIntent;
+  /** The aggregate type and the id of the written aggregate. */
+  readonly aggregateIdentity: AggregateIdentity<TAggregate["id"]>;
+  readonly expectedVersion: Version | undefined;
+  readonly version: Version;
+  readonly changes: PersistenceChanges<TChangeSet>;
+  readonly events: TAggregate["pendingEvents"];
+}
+//#endregion
+//#region src/persistence/event-store/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, for example when it
+   * clamps `limit` to a maximum of its own. It must return at least one
+   * event while unread events remain inside the requested window.
+   */
+  readonly limit: number;
+  /**
+   * Return only events AFTER this stream position (1-based event count),
+   * for example the version of a snapshot. 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;
+  /**
+   * Cooperative-cancellation signal of the surrounding operation. An
+   * adapter either rejects with the `reason` of an aborted signal, or
+   * bounds each page read with the timeout of its driver. So a page read
+   * that hangs cannot hang its caller.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * 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`. An absent 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>;
+};
+/**
+ * The read half of the store: one bounded page of a stream at a time. A
+ * store implements both halves; a read-only implementation offers this
+ * role alone.
+ */
+interface EventStreamReader<Evt extends AnyDomainEvent> {
+  /**
+   * Reads one bounded page of the qualified stream in append order. An absent 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. Each returned event occupies one stream position, so the
+   * events of a page fill the positions after `fromVersion` without a gap.
+   * `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. A caller that reads a stream in several pages pins a target
+   * version on the first page, passes it as `toVersion` on every
+   * continuation, and advances `fromVersion` by the number of events each
+   * page 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: AggregateIdentity, options: ReadStreamOptions): Promise<StreamReadResult<Evt>>;
+}
+/**
+ * Driven port for event-sourced aggregate persistence: an append-only
+ * store with one stream per aggregate. Each stream is identified 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): AggregateIdentity<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 read = await readStreamPages(this.eventStore, this.stream(id), {
+ *     limit: 256,
+ *   });
+ *   if (!read.reachable) return undefined;
+ *   const loaded = await reconstituteAggregateFromStreamPages(
+ *     () => Order.reconstitute(id), // bare instance, no events
+ *     read,
+ *   );
+ *   if (loaded.isErr()) throw loaded.error; // corrupt stream
+ *   return this.tracking.trackLoaded(loaded.value);
+ * }
+ *
+ * flush(write: AggregatePersistenceWrite<Order, number | undefined>) {
+ *   return this.eventStore.append(write.aggregateIdentity, write.events, {
+ *     expectedVersion: write.expectedVersion ?? 0,
+ *   });
+ * }
+ * ```
+ *
+ * `readStreamPages` pins the head on the first page as the target version
+ * and reads the rest in bounded pages up to it.
+ * `reconstituteAggregateFromStreamPages` replays the pages and checks that
+ * the replay ends at the target version. The long form, for an adapter that
+ * pages on its own, is in the event-sourcing guide.
+ *
+ * `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> extends EventStreamReader<Evt> {
+  /**
+   * 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
+   *     `replayHistory`, 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).
+   *
+   * A load that read its pages through a replica still appends here with
+   * the pinned target as `expectedVersion`. The primary rejects a stale
+   * head, so a lagging replica cannot lose an update.
+   *
+   * 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: AggregateIdentity, events: ReadonlyArray<Evt>, options: EventStoreAppendOptions): Promise<void>;
+}
+//#endregion
+//#region src/persistence/event-store/reconstitute-from-stream-pages.d.ts
+/**
+ * The shape the replay reads: the stream, the window, and the pages.
+ * `readStreamPages` returns it as the reachable branch of a kit read. An
+ * adapter that pages on its own builds it directly, after it pinned the
+ * target version with `pinTargetVersion`.
+ */
+interface ReplayableStreamPages<Evt extends AnyDomainEvent> {
+  /** The qualified stream the pages come from. */
+  readonly stream: AggregateIdentity;
+  /**
+   * The cursor the read started at: `fromVersion`, or `0`. The pages hold
+   * the events after it, so the replay target must stand at this version.
+   */
+  readonly fromVersion: number;
+  /**
+   * The version the replay must end at: the head at read time, or a
+   * `toVersion` at or below it. Never a version taken from a snapshot, and
+   * never below `fromVersion`. Later appends do not move it.
+   */
+  readonly targetVersion: number;
+  /**
+   * The events after the cursor through the target version, in append
+   * order, one bounded page per iteration. Every iteration starts again
+   * from the first page, so a second replay of one read sees the same
+   * prefix. A page holds at least one event, and the pages end at the
+   * target version. The replay rejects an empty page, and a page that
+   * would run past the target version, with
+   * {@link InvalidEventStreamPageError} before any row of it reaches the
+   * aggregate. `createReplayableStreamPagesContractTests` proves these
+   * rules for an adapter.
+   *
+   * The events of a page are stored facts: no consumer, upcaster, or fold
+   * changes one in place. `readStreamPages` reads fresh events on every
+   * later iteration, and `createReplayableStreamPages` hands out frozen
+   * ones, so a consumer that breaks this rule fails in its own tests.
+   */
+  readonly pages: AsyncIterable<ReadonlyArray<Evt>>;
+}
+/**
+ * Reconstitutes an event-sourced aggregate from the pages of a stream read
+ * and yields it only when the replay ends at the target version.
+ *
+ * This is the paged form of `reconstituteAggregateFromHistory`.
+ * `createReplayTarget` builds the replay target: a fresh instance for a
+ * full replay, or an instance reconstituted from a snapshot for a read that
+ * starts at `snapshot.version`. `read` is the reachable branch of a kit
+ * read, or the value that an adapter that pages on its own built.
+ *
+ * The call checks the window first. `targetVersion` must be a positive
+ * safe integer, and `fromVersion` a non-negative one at or below it. A bad
+ * window rejects with `RangeError` before the replay target is built.
+ *
+ * The call then primes the replay target with an empty history, so the
+ * aggregate runs its own guard even when the read holds no page: a replay
+ * target with pending decisions throws `UnreplayableAggregateError`. The
+ * replay target must stand at `read.fromVersion`. A replay target at
+ * another version throws {@link ReplayTargetMismatchError} before the
+ * first page, even when it also rejected the empty history: a wiring
+ * defect wins over a rejection that the data cannot explain.
+ *
+ * Each page goes through `replayHistory` on the replay target, so
+ * allocation stays bounded by the size of a page; `readStreamPages` rejects
+ * a page over its `limit`. An empty page, and a page that would run past
+ * the target version, throw {@link InvalidEventStreamPageError} before any
+ * row of them reaches the aggregate. Events carry no stream position, so
+ * only the call can find pages that end short of the target version. After
+ * the last page it compares the final version with `read.targetVersion` and
+ * throws {@link ReplayTargetMismatchError} on a difference.
+ *
+ * When the aggregate rejects a stored event with a `DomainError`, the call
+ * stops reading and returns {@link ReplayRejectedError} as `Err`. The
+ * error names the stream and the window of the rejected page, and it holds
+ * the `DomainError` as `cause`. The replay target never escapes on that
+ * path. Wiring errors and a foreign row throw, as in `replayHistory`. What
+ * `createReplayTarget` throws propagates.
+ */
+declare function reconstituteAggregateFromStreamPages<TAggregate extends ReplayableAggregate<Id<string>, AnyDomainEvent>>(createReplayTarget: () => TAggregate, read: ReplayableStreamPages<Parameters<TAggregate["replayHistory"]>[0][number]>): Promise<Result<TAggregate, ReplayRejectedError>>;
+//#endregion
+//#region src/persistence/snapshot-store/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 `replayHistory`.
+ *
+ * **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(identity: AggregateIdentity): 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(identity: AggregateIdentity, 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(identity: AggregateIdentity): Promise<void>;
+}
+//#endregion
+export { EventHandler as $, Command as $t, IdempotencyClaimHandle as A, CreateDomainEventFromFactsOptions as At, withIdempotentCommit as B, PendingDomainEvent as Bt, IdentityMap as C, ExecutionContext as Ct, ProjectionPosition as D, EventCommitCandidatePosition as Dt, ProjectionCheckpointStore as E, EventCommitCandidate as Et, IdempotencyStore as F, DomainEventFactory as Ft, CommitEnrollment as G, createDomainEventFactory as Gt, DeadlineStore as H, UncommittedDomainEventOf as Ht, IdempotentCommitRequest as I, DomainEventFactoryOptions as It, WithCommitWorkResult as J, defaultDomainEventFactory as Jt, CommitEnrollmentOptions as K, createDomainEventFromFacts as Kt, IdempotentCommitResult as L, DomainEventStamp as Lt, IdempotencyOperationErrorContext as M, CreateDomainEventStampOptions as Mt, IdempotencyReconciliation as N, CreateUncommittedDomainEventOptions as Nt, isPositionAfter as O, AnyDomainEvent as Ot, IdempotencyReconciliationDecision as P, DomainEvent as Pt, EventBus as Q, AggregateIdentity as Qt, IdempotentExecution as R, EventIdFactory as Rt, AggregateClass as S, OutboxWriter as St, ProjectionCheckpoint as T, CommittedDomainEvent as Tt, DueDeadline as U, copyMetadata as Ut, DeadLetterDeadline as V, UncommittedDomainEvent as Vt, AggregateCommitToken as W, createDomainEvent as Wt, TransactionScope as X, recordDomainEvent as Xt, withCommit as Y, mergeMetadata as Yt, TransactionalOptions as Z, ClockFactory as Zt, capturePersistenceBaseline as _, routeEventsToCommandOutbox as _t, EventStoreAppendOptions as a, Version as at, persistenceProjectionDrifted as b, Outbox as bt, StreamReadResult as c, Id as ct, RepositoryTracking as d, CommandMessageContent as dt, CommandHandler as en, OnceOptions as et, UnitOfWorkIdentityMap as f, CommandMessageRelationships as ft, PersistenceModel as g, DurableCommandMessage as gt, PersistenceLifecycle as h, CommandOutboxWriter as ht, EventStore as i, JsonValue as in, ReplayableAggregate as it, IdempotencyLease as j, CreateDomainEventOptions as jt, IdempotencyClaim as k, AnyUncommittedDomainEvent as kt, AggregatePersistenceWrite as l, IdGenerator as lt, PersistenceChanges as m, CommandOutboxMapper as mt, ReplayableStreamPages as n, JsonObject as nn, Aggregate as nt, EventStreamReader as o, sameVersion as ot, PersistenceBaseline as p, CommandOutboxCommitCandidate as pt, WithCommitDeps as q, createUncommittedDomainEvent as qt, reconstituteAggregateFromStreamPages as r, JsonPrimitive as rn, AggregateSnapshot as rt, ReadStreamOptions as s, toVersion as st, SnapshotStore as t, PublishedCommand as tn, PublishOptions as tt, AggregateWriteIntent as u, CommandCommitOriginCandidate as ut, derivePersistenceChanges as v, DeadLetterRecord as vt, Projection as w, CommitPosition as wt, recapturePersistenceBaseline as x, OutboxRecord as xt, insertPersistenceBaseline as y, DispatchTrackingOutbox as yt, WithIdempotentCommitDeps as z, EventMetadata as zt };
+//# sourceMappingURL=snapshot-store.d.ts.map