@shirudo/ddd-kit 2.0.0 → 3.0.0-rc.10

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

@@ -0,0 +1,2397 @@
+import { u as DomainError } 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-address.d.ts
+/**
+ * Stable value address of one aggregate instance.
+ *
+ * Aggregate ids are type-scoped, so the raw id alone is not globally unique:
+ * `SalesOrder 1` and `FulfillmentOrder 1` are different aggregates. Event
+ * streams, snapshots, committed-event sources, and projection checkpoints
+ * therefore carry both fields instead of defining boundary-specific variants.
+ *
+ * `aggregateType` is a stable technical stream category. Renaming it changes
+ * persistence keys and orphans checkpoints unless the stored addresses are
+ * migrated. When bounded contexts share infrastructure and reuse a domain
+ * name, qualify it at the source (`sales.order`, `fulfillment.order`). The kit
+ * deliberately adds no separate `boundedContext` field: qualification remains
+ * the consumer's naming decision.
+ */
+interface AggregateAddress<TAggregateId extends string = string> {
+  readonly aggregateType: string;
+  readonly aggregateId: TAggregateId;
+}
+//#endregion
+//#region src/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 address, and payload
+ * schema version because those values describe the business fact it produced.
+ * The application shell later turns this value into a {@link DomainEvent}.
+ */
+interface UncommittedDomainEvent<T extends string, P = void> {
+  readonly type: T;
+  readonly aggregateId?: string;
+  readonly aggregateType?: string;
+  readonly payload: P;
+  readonly 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;
+}
+declare function createDomainEventFactory(options?: DomainEventFactoryOptions): DomainEventFactory;
+/**
+ * Immutable UUID-v4/platform-clock factory used by the top-level
+ * {@link createDomainEvent}. It cannot be reconfigured; construct an instance
+ * with {@link createDomainEventFactory} for custom policy.
+ */
+declare const defaultDomainEventFactory: DomainEventFactory;
+declare function createUncommittedDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateUncommittedDomainEventOptions): UncommittedDomainEvent<T, void>;
+declare function createUncommittedDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateUncommittedDomainEventOptions): UncommittedDomainEvent<T, P>;
+/**
+ * Attaches shell-owned recording data to an accepted aggregate decision.
+ *
+ * The decision supplies the domain type, payload, source address, and payload
+ * schema version. The stamp supplies only event identity, recording time, and
+ * trace metadata.
+ */
+declare function recordDomainEvent<T extends string, P>(event: UncommittedDomainEvent<T, P>, stamp: DomainEventStamp): DomainEvent<T, P>;
+declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateDomainEventOptions): DomainEvent<T, void>;
+declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateDomainEventOptions): DomainEvent<T, P>;
+/**
+ * Creates an already minted domain event exclusively from explicit envelope
+ * facts. Unlike {@link createDomainEvent}, it has no clock or event-id fallback
+ * and is useful when replay, migration, or a caller-owned boundary already has
+ * the final identity and occurrence time.
+ *
+ * Aggregate behavior normally creates an {@link UncommittedDomainEvent} through
+ * its protected `createEvent` helper. The application shell later records that
+ * pending fact with caller-owned time and identity.
+ */
+declare function createDomainEventFromFacts<T extends string>(type: T, payload: undefined, options: CreateDomainEventFromFactsOptions): DomainEvent<T, void>;
+declare function createDomainEventFromFacts<T extends string, P>(type: T, payload: P, options: CreateDomainEventFromFactsOptions): DomainEvent<T, P>;
+/**
+ * Copies metadata from a source event to a new event.
+ * Useful for maintaining correlation chains in event-driven architectures.
+ *
+ * @example
+ * ```typescript
+ * const newEvent = createDomainEvent(
+ *   "OrderShipped",
+ *   { orderId: "123" },
+ *   { metadata: copyMetadata(previousEvent, { causationId: previousEvent.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: AggregateAddress;
+  readonly position: EventCommitCandidatePosition;
+}
+/**
+ * A domain event enriched after persistence has established its source and
+ * commit position. Outboxes and projectors consume this envelope; in-process
+ * domain handlers continue to consume the bare {@link DomainEvent} value.
+ */
+interface CommittedDomainEvent<Evt extends AnyDomainEvent> {
+  readonly event: Evt;
+  readonly source: AggregateAddress;
+  readonly position: CommitPosition;
+}
+//#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>;
+}
+/**
+ * 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: AggregateAddress;
+  readonly position: EventCommitCandidatePosition;
+}
+/**
+ * One private process-event commit and the exact commands it requested.
+ * `messages` may be empty: the receipt still advances the originating source
+ * and makes an exact retry distinguishable from a missing commit.
+ */
+interface CommandOutboxCommitCandidate<C extends PublishedCommand> {
+  readonly origin: CommandCommitOriginCandidate;
+  readonly messages: ReadonlyArray<DurableCommandMessage<C>>;
+}
+/**
+ * Write port for a dedicated transactional command outbox.
+ *
+ * The adapter is bound to the same ambient transaction as the aggregate or
+ * event-stream repository. It must persist the complete input atomically,
+ * retain input order, deduplicate exact retries by `origin.eventId`, and reject
+ * a reused origin id whose source, position, or messages differ. It also owns
+ * the durable source cursor represented by `origin.position`; an empty command
+ * batch still advances that cursor.
+ *
+ * Delivery is out of band and at least once. A consumer therefore uses
+ * `message.messageId` as its idempotency key and acknowledges only after the
+ * command result has been stored.
+ */
+interface CommandOutboxWriter<C extends PublishedCommand> {
+  add(commits: ReadonlyArray<CommandOutboxCommitCandidate<C>>): Promise<void>;
+}
+/** Maps one private accepted event to zero or more addressed commands. */
+type CommandOutboxMapper<Evt extends AnyDomainEvent, C extends PublishedCommand> = (event: Evt) => ReadonlyArray<CommandMessageContent<C>>;
+/**
+ * Adapts a dedicated command outbox to the event-candidate write port consumed
+ * by `withCommit`.
+ *
+ * Mapping happens inside the transaction, before the command outbox write.
+ * The private event is used only at this boundary and is reduced to an origin
+ * receipt. The helper never publishes it or copies its payload implicitly; the
+ * application mapper selects and translates the data that belongs in the
+ * versioned Published Language. The route rejects values JSON would lose or
+ * change before it calls the adapter.
+ * Every command gets a stable id derived from the event id and its zero-based
+ * order, so an exact transaction retry produces the same rows.
+ *
+ * Omit `withCommit`'s in-process `bus` for private process events. Participants
+ * consume the durable command messages from their explicitly named
+ * destinations, while event-stream replay only rebuilds process state.
+ */
+declare function routeEventsToCommandOutbox<C extends PublishedCommand, Evt extends AnyDomainEvent = AnyDomainEvent>(outbox: CommandOutboxWriter<C>, mapper: CommandOutboxMapper<Evt, C>): OutboxWriter<Evt>;
+//#endregion
+//#region src/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;
+  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.
+   *
+   * @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;
+}
+/**
+ * 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, 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, addresses: ReadonlyArray<AggregateAddress>, work: () => Promise<R>): Promise<R>;
+  /**
+   * The stored watermark receipt for `(projection, address)`, or `undefined`
+   * when this projection has never applied an event of that
+   * aggregate. Called inside the projector's transaction.
+   */
+  load(ctx: TCtx, projection: string, address: AggregateAddress): Promise<ProjectionCheckpoint | undefined>;
+  /**
+   * Persists the watermark receipt, overwriting a previous one (last write
+   * wins; the projector only calls this with advancing checkpoints).
+   * Called inside the projector's transaction, after the read-model
+   * update it accounts for.
+   */
+  save(ctx: TCtx, projection: string, address: AggregateAddress, checkpoint: ProjectionCheckpoint): Promise<void>;
+  /**
+   * The wait-for-version building block: `true` when the stored
+   * watermark for `(projection, address)` is at or past
+   * `position`. Runs OUTSIDE any transaction (a query-side poll).
+   *
+   * Pass the position of the LAST event your commit emitted: all
+   * events of one commit share the `aggregateVersion`, so comparing
+   * on the version alone would report "reached" while later events
+   * of the same commit are still unapplied.
+   */
+  hasReached(projection: string, address: AggregateAddress, position: ProjectionPosition): Promise<boolean>;
+  /**
+   * Deletes every checkpoint of `projection` (other projections'
+   * checkpoints are untouched): the rebuild entry point. Called
+   * inside the rebuild transaction, together with the projection's
+   * `truncate`, so a rebuild starts from a consistent zero.
+   */
+  reset(ctx: TCtx, projection: string): Promise<void>;
+}
+/**
+ * One projection: the consumer-owned mapping from events to ONE read
+ * model (one table/view per projection; run several `Projector`s for
+ * several read shapes). The kit owns the mechanics around it
+ * (cursor skip, atomic checkpointing, rebuild); the handler owns the
+ * read-model writes.
+ *
+ * The projector feed MUST contain every committed envelope for each aggregate
+ * address it carries, including event types this read model does not use.
+ * Handle those events as explicit no-ops in `apply`: the projector still
+ * advances their cursor. Filtering a broker subscription by event type drops
+ * positions from the source chain and turns the next commit into a real gap.
+ * For correctness-critical read models, use `projectionFromHandlers` to make
+ * every event in the declared union a compile-time handler-or-ignore decision;
+ * implement this interface directly when intentionally partial routing is the
+ * better fit.
+ */
+interface Projection<Evt extends AnyDomainEvent, TCtx = unknown> {
+  /**
+   * Stable unique name; keys the checkpoints. Renaming it orphans the
+   * old checkpoints and replays everything under the new name.
+   */
+  name: string;
+  /**
+   * Applies ONE event's read-model change inside the ambient
+   * transaction. The projector's cursor already filtered duplicates
+   * and stale events, so plain writes are safe; route on
+   * `event.type` and handle creates, updates, deletes, corrections,
+   * and tombstones explicitly (an upsert-only handler silently
+   * retains stale rows). For a known event type this projection does not use,
+   * return without writing; that explicit no-op still consumes and checkpoints
+   * the envelope's source position.
+   *
+   * MUST be side-effect-free beyond the read model: no mails, no
+   * external calls, no commands. A rebuild replays every event; side
+   * effects would fire again.
+   */
+  apply(ctx: TCtx, event: Evt): Promise<void>;
+  /**
+   * Optional: clears the read model, called by `Projector.reset()`
+   * in the same transaction as the checkpoint reset, so a rebuild
+   * never observes a half-cleared state. Without it, truncating the
+   * read model before a rebuild is the caller's responsibility.
+   */
+  truncate?(ctx: TCtx): Promise<void>;
+}
+//#endregion
+//#region src/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, but must return at least
+   * one while unread events remain inside the requested window.
+   */
+  readonly limit: number;
+  /**
+   * Return only events AFTER this stream position (1-based event count),
+   * the snapshot catch-up read: `readStream(stream, { fromVersion:
+   * snapshot.version, limit: 256 })` yields the next page passed to
+   * `aggregate.replayHistory`; the caller checks that the aggregate
+   * ends at the pinned head ({@link ReplayHeadMismatchError}). Defaults
+   * to `0` (the first stream page).
+   * Must be a non-negative safe integer when present.
+   */
+  readonly fromVersion?: number;
+  /**
+   * Return events only THROUGH this stream position (inclusive, 1-based
+   * event count). Together with `fromVersion`, this describes the interval
+   * `(fromVersion, toVersion]`. Defaults to the actual stream head.
+   * `0` therefore returns an empty window; a value beyond the head clamps
+   * to the head; and `fromVersion >= toVersion` is an empty interval, not
+   * an error.
+   * Must be a non-negative safe integer when present.
+   */
+  readonly toVersion?: number;
+}
+/**
+ * State returned by {@link EventStore.readStream}.
+ *
+ * `lastVersion` is always the actual stream head (the event count), independent
+ * of the requested read window and page limit. `exists: true` implies
+ * `lastVersion >= 1`: an
+ * existing stream has at least one event, while metadata or tombstones without
+ * events must be reported as `exists: false`. A missing stream is therefore
+ * distinguishable from an existing stream whose requested window is empty.
+ * Snapshot-backed repositories use that distinction to reject a snapshot whose
+ * version lies beyond the current authoritative stream head.
+ */
+type StreamReadResult<Evt extends AnyDomainEvent> = {
+  readonly exists: false;
+  readonly lastVersion: 0;
+  readonly events: readonly [];
+} | {
+  readonly exists: true;
+  readonly lastVersion: number;
+  readonly events: ReadonlyArray<Evt>;
+};
+/**
+ * Driven port for event-sourced aggregate persistence: an append-only
+ * store with one stream per aggregate. Each stream is addressed by the
+ * qualified tuple `(aggregateType, aggregateId)`, because aggregate ids
+ * are type-scoped rather than globally unique.
+ *
+ * The kit ships the port, the OCC error contract, `InMemoryEventStore`
+ * as the reference implementation, and the event-sourced repository
+ * contract suites (`createEventStoreContractTests` and
+ * `createEsRepositoryContractTests` from `@shirudo/ddd-kit/testing`).
+ * Your adapter implements this port against a real store and must pass
+ * those suites. Like the state-stored repository contract, its optimistic
+ * concurrency and key isolation are testable adapter contracts, not kit
+ * guarantees.
+ *
+ * Repository usage (see the event-sourcing guide):
+ *
+ * ```ts
+ * private stream(id: OrderId): AggregateAddress<OrderId> {
+ *   return { aggregateType: "Order", aggregateId: id };
+ * }
+ *
+ * async findById(id: OrderId): Promise<Order | undefined> {
+ *   const cached = this.tracking.identityMap.get(Order, id);
+ *   if (cached) return cached;
+ *   const address = this.stream(id);
+ *   const first = await this.eventStore.readStream(address, { limit: 256 });
+ *   if (!first.exists) return undefined;
+ *   const targetVersion = first.lastVersion; // pin the first observed head
+ *   const reconstituted = reconstituteAggregateFromHistory(
+ *     () => Order.reconstitute(id), // bare instance, no events
+ *     first.events,
+ *   );
+ *   if (reconstituted.isErr()) throw reconstituted.error; // corrupt stream
+ *   const order = reconstituted.value;
+ *   let fromVersion = first.events.length;
+ *   while (fromVersion < targetVersion) {
+ *     const page = await this.eventStore.readStream(address, {
+ *       fromVersion,
+ *       toVersion: targetVersion,
+ *       limit: 256,
+ *     });
+ *     if (!page.exists || page.events.length === 0) {
+ *       throw new NonProgressingEventStreamPageError({
+ *         ...address,
+ *         fromVersion,
+ *         targetVersion,
+ *       });
+ *     }
+ *     const catchUp = order.replayHistory(page.events);
+ *     if (catchUp.isErr()) throw catchUp.error; // corrupt stream
+ *     fromVersion += page.events.length;
+ *   }
+ *   if (order.version !== targetVersion) {
+ *     throw new ReplayHeadMismatchError({
+ *       ...address,
+ *       targetVersion,
+ *       actualVersion: order.version,
+ *     });
+ *   }
+ *   return this.tracking.trackLoaded(order);
+ * }
+ *
+ * flush(write: AggregatePersistenceWrite<Order, number | undefined>) {
+ *   return this.eventStore.append(this.stream(write.aggregateId), write.events, {
+ *     expectedVersion: write.expectedVersion ?? 0,
+ *   });
+ * }
+ * ```
+ *
+ * `flush` appends the exact event batch registered by `add` or `update`;
+ * `withCommit`
+ * separately composes them into outbox envelopes. The event store's own
+ * stream position remains the ordering authority for replay.
+ *
+ * The exact appended event batch is acknowledged only after the surrounding
+ * transaction commits. Rollback leaves it pending.
+ */
+interface EventStore<Evt extends AnyDomainEvent> {
+  /**
+   * Atomically appends `events` to the stream, guarded by optimistic
+   * concurrency: the append succeeds only when the stream currently
+   * holds exactly `options.expectedVersion` events.
+   *
+   * Contract for implementations:
+   *
+   *  1. **OCC:** on a version mismatch (stale writer, duplicate create
+   *     racing on `expectedVersion: 0`, or an expectedVersion ahead of
+   *     the stream), throw `ConcurrencyConflictError` from
+   *     `@shirudo/ddd-kit` carrying the expected and actual stream
+   *     versions; map your store's native conflict signal to it instead
+   *     of letting a raw driver error escape. One sanctioned exception:
+   *     an adapter that can DISTINGUISH the duplicate-create race
+   *     (`expectedVersion: 0` against a stream that already exists,
+   *     typically a unique violation on the first position) may throw
+   *     `DuplicateAggregateError` for that case instead, matching the
+   *     state-stored insert path. It is deliberately NOT retryable:
+   *     replaying the same append cannot succeed; the use case resolves
+   *     the create race (load the existing aggregate, or surface HTTP
+   *     409). The contract suite accepts both errors for this race.
+   *  2. **Atomicity:** all events land or none do; a rejected append
+   *     leaves the stream untouched.
+   *  3. **Qualified identity:** `(aggregateType, aggregateId)` is the
+   *     storage key. Equal raw ids under different aggregate types are
+   *     independent streams. Use both columns in every primary/unique
+   *     key, OCC predicate, and read predicate.
+   *  4. **Order:** events are stored in the given array order, appended
+   *     after the existing stream tail.
+   *  5. **Append-only:** stored events are never edited or deleted;
+   *     corrections are new (compensating) events.
+   *  6. **Replay integrity:** reads order by the persisted stream position
+   *     and reject duplicate or non-contiguous positions where the backing
+   *     store exposes them. The portable contract suite proves observable
+   *     append order and slicing; because the port cannot inject malformed
+   *     physical rows, adapters add a store-specific corruption fixture that
+   *     proves the duplicate/gap rejection. The repository then calls
+   *     `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).
+   *
+   * Treat `aggregateType` as a stable technical stream category. If two
+   * bounded contexts share one physical store and reuse a domain name,
+   * qualify it at the source (`sales.order`, `fulfillment.order`). Renaming
+   * it changes the stream key and therefore requires a data migration.
+   */
+  append(stream: AggregateAddress, events: ReadonlyArray<Evt>, options: EventStoreAppendOptions): Promise<void>;
+  /**
+   * Reads one bounded page of the qualified stream in append order. An unknown stream returns
+   * `{ exists: false, lastVersion: 0, events: [] }`; an existing stream keeps
+   * `exists: true` even when its requested window is empty. An existing stream
+   * has at least one event, so `exists: true` implies `lastVersion >= 1`;
+   * metadata or tombstones without events must be reported as absent.
+   * `lastVersion` is always the actual stream head. `options.limit` is
+   * mandatory and caps the returned array. An adapter may return fewer than
+   * the requested limit, but if the requested window still contains unread
+   * events it must return a non-empty contiguous prefix so callers can make
+   * progress. `options.fromVersion`
+   * excludes positions at or below its 1-based event count;
+   * `options.toVersion` includes positions through its count, so both bounds
+   * describe `(fromVersion, toVersion]`. `toVersion: 0` and inverted ranges
+   * return an empty existing window, while a bound beyond the head clamps to
+   * the head. This distinction is load-bearing for snapshot catch-up and
+   * point-in-time reconstruction: a repository can verify the requested
+   * historical window against the authoritative head. `limit` must be a
+   * positive safe integer; present bounds must be non-negative safe integers.
+   * Invalid options reject with `RangeError` before querying storage.
+   *
+   * Each page's `exists`, `lastVersion`, and `events` must describe one
+   * consistent view of the stream. Multiple page reads are not one database
+   * snapshot: pin the first page's `lastVersion` as `toVersion` on every
+   * continuation, then advance `fromVersion` by the number of events actually
+   * returned. Because streams are append-only, that yields a stable prefix
+   * even if new events arrive while replay is in progress. The returned
+   * event array is owned by the caller; implementations must not hand out
+   * mutable live internal state.
+   */
+  readStream(stream: AggregateAddress, options: ReadStreamOptions): Promise<StreamReadResult<Evt>>;
+}
+//#endregion
+//#region src/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(address: AggregateAddress): Promise<AggregateSnapshot<TState> | undefined>;
+  /**
+   * Persists `snapshot` as the new latest for the aggregate,
+   * replacing any previous one. Called AFTER the write transaction
+   * committed (see the port docs); a single-row upsert is the
+   * standard implementation.
+   */
+  save(address: AggregateAddress, snapshot: AggregateSnapshot<TState>): Promise<void>;
+  /**
+   * Removes the aggregate's snapshot; a no-op when none exists. The
+   * two callers: the schema-migration fallback (a
+   * `SnapshotSchemaMismatchError` or corrupt snapshot during adapter
+   * reconstitution discards the snapshot and refolds from the full stream)
+   * and erasure (a snapshot duplicates aggregate state and follows
+   * the same retention rules). When erasing, delete the snapshot
+   * BEFORE the event stream: the reverse order has a crash window in
+   * which a stale snapshot resurrects the erased aggregate on the
+   * snapshot load path; snapshot-first degrades to a full replay.
+   */
+  delete(address: AggregateAddress): Promise<void>;
+}
+//#endregion
+export { routeEventsToCommandOutbox as $, WithCommitWorkResult as A, defaultDomainEventFactory as At, ReplayableAggregate as B, JsonValue as Bt, DeadLetterDeadline as C, UncommittedDomainEvent as Ct, CommitEnrollment as D, createDomainEventFactory as Dt, AggregateCommitToken as E, createDomainEvent as Et, EventHandler as F, Command as Ft, IdGenerator as G, sameVersion as H, OnceOptions as I, CommandHandler as It, CommandMessageRelationships as J, CommandCommitOriginCandidate as K, PublishOptions as L, PublishedCommand as Lt, TransactionScope as M, recordDomainEvent as Mt, TransactionalOptions as N, ClockFactory as Nt, CommitEnrollmentOptions as O, createDomainEventFromFacts as Ot, EventBus as P, AggregateAddress as Pt, DurableCommandMessage as Q, Aggregate as R, JsonObject as Rt, withIdempotentCommit as S, PendingDomainEvent as St, DueDeadline as T, copyMetadata as Tt, toVersion as U, Version as V, Id as W, CommandOutboxMapper as X, CommandOutboxCommitCandidate as Y, CommandOutboxWriter as Z, IdempotencyStore as _, DomainEventFactory as _t, StreamReadResult as a, ExecutionContext as at, IdempotentExecution as b, EventIdFactory as bt, ProjectionCheckpointStore as c, EventCommitCandidate as ct, IdempotencyClaim as d, AnyUncommittedDomainEvent as dt, DeadLetterRecord as et, IdempotencyClaimHandle as f, CreateDomainEventFromFactsOptions as ft, IdempotencyReconciliationDecision as g, DomainEvent as gt, IdempotencyReconciliation as h, CreateUncommittedDomainEventOptions as ht, ReadStreamOptions as i, OutboxWriter as it, withCommit as j, mergeMetadata as jt, WithCommitDeps as k, createUncommittedDomainEvent as kt, ProjectionPosition as l, EventCommitCandidatePosition as lt, IdempotencyOperationErrorContext as m, CreateDomainEventStampOptions as mt, EventStore as n, Outbox as nt, Projection as o, CommitPosition as ot, IdempotencyLease as p, CreateDomainEventOptions as pt, CommandMessageContent as q, EventStoreAppendOptions as r, OutboxRecord as rt, ProjectionCheckpoint as s, CommittedDomainEvent as st, SnapshotStore as t, DispatchTrackingOutbox as tt, isPositionAfter as u, AnyDomainEvent as ut, IdempotentCommitRequest as v, DomainEventFactoryOptions as vt, DeadlineStore as w, UncommittedDomainEventOf as wt, WithIdempotentCommitDeps as x, EventMetadata as xt, IdempotentCommitResult as y, DomainEventStamp as yt, AggregateSnapshot as z, JsonPrimitive as zt };
+//# sourceMappingURL=snapshot-store.d.ts.map