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

package/dist/testing.d.ts

@@ -1,252 +1,631 @@
-import { I as IAggregateRoot, a as Id, A as AnyDomainEvent } from './aggregate-CePTINEt.js';
-import '@shirudo/result';
-import '@shirudo/base-error';
-
-/**
- * The repository surface the contract suite exercises: the minimal
- * structural subset of the canonical `IUnitOfWorkRepository` (exported
- * from the main entry) that the tests need. `getById` is typed over
- * the aggregate's own branded id (`TAgg["id"]`), so concrete adapters,
- * including arrow-function-property style repositories, which are
- * checked contravariantly, match without casts.
- */
-interface ContractRepository<TAgg extends IAggregateRoot<Id<string>, AnyDomainEvent>> {
-    getById(id: TAgg["id"]): Promise<TAgg | null>;
-    save(aggregate: TAgg): Promise<void>;
-    delete(aggregate: TAgg): Promise<void>;
-}
-/**
- * One isolated test environment: fresh storage, fresh outbox. The
- * suite creates one per test via {@link RepositoryContractHarness} and
- * tears it down afterwards (a teardown failure never masks an
- * in-flight contract violation).
- */
-interface RepositoryContractEnvironment<TAgg extends IAggregateRoot<Id<string>, Evt>, Evt extends AnyDomainEvent = AnyDomainEvent> {
-    /**
-     * Execute one unit of work against the adapter under test: open the
-     * transaction, hand the suite a tx-bound repository, commit on
-     * resolve, roll back on throw, and run the post-commit lifecycle
-     * (event harvest into the outbox, `markPersisted`). Wire this
-     * through your real `UnitOfWork` / `withCommit` setup: the commit
-     * boundary IS part of what the suite proves.
-     */
-    run<R>(work: (ctx: {
-        repository: ContractRepository<TAgg>;
-    }) => Promise<R>): Promise<R>;
-    /**
-     * All events currently persisted in the outbox (committed writes
-     * only; a rolled-back transaction's events must not appear here).
-     */
-    committedOutboxEvents(): Promise<ReadonlyArray<Evt>>;
-    /** Release connections, drop schemas, etc. Called in a finally. */
-    teardown?(): Promise<void>;
-}
-/**
- * What an adapter supplies to run the contract suite.
- *
- * The harness MUST provide isolation per environment (fresh
- * tables/keyspace or a truncate); tests assume they see only their
- * own writes. **For SQL/ORM adapters this must run against a real
- * database** (testcontainers or equivalent), not an in-memory fake:
- * the mandatory two-writer test proves YOUR `WHERE version = ?`
- * predicate, and an in-memory stand-in proves only itself.
- *
- * Optional capabilities widen the suite: tests for an absent
- * capability come back **marked `skipped`** with a `run()` that
- * rejects loudly: bind them with `it.skip` so the gap stays visible
- * in every report (see {@link RepositoryContractTest}); a naive
- * binding fails instead of green-no-op'ing. Capabilities are captured
- * once at suite creation. Provide every capability your adapter can
- * support; each one closes a real OCC hole.
- */
-interface RepositoryContractHarness<TAgg extends IAggregateRoot<Id<string>, Evt>, Evt extends AnyDomainEvent = AnyDomainEvent> {
-    createEnvironment(): Promise<RepositoryContractEnvironment<TAgg, Evt>>;
-    /**
-     * A brand-new aggregate (never persisted, unique id,
-     * `persistedVersion === undefined`).
-     */
-    createAggregate(): TAgg;
-    /**
-     * Apply exactly ONE version-bumping domain mutation that records at
-     * least one domain event (a `commit()`-style state change). The
-     * suite relies on the +1-per-call arithmetic and on the event for
-     * its outbox assertions.
-     */
-    mutate(aggregate: TAgg): void;
-    /**
-     * Optional: a version-bumping mutation whose state is deep-equal to
-     * the previous state (`setState({...state}, true)`). Enables the
-     * version-only-change-still-persists test: the skip-save/OCC-desync
-     * trap.
-     */
-    mutateVersionOnly?(aggregate: TAgg): void;
-    /**
-     * Optional: a mutation that changes ONLY a child collection (a
-     * non-root-row `changedKeys` entry). Enables the
-     * child-change-bumps-root-version test for partial-write
-     * repositories.
-     */
-    mutateChildCollection?(aggregate: TAgg): void;
-    /**
-     * Optional: construct a NEW (never-persisted) aggregate instance
-     * carrying a SPECIFIC id. Enables TWO tests: deletion-is-final-
-     * across-instances (resurrection via a factory after delete) and
-     * the duplicate-insert test (see
-     * {@link insertsAreDuplicateChecked} to opt out of the latter
-     * independently).
-     */
-    createAggregateWithId?(id: TAgg["id"]): TAgg;
-    /**
-     * Semantic opt-OUT (default `true`): whether `save()`'s INSERT path
-     * rejects an existing id with `DuplicateAggregateError` (mapping the
-     * driver's unique-violation: Postgres `23505`, MySQL `1062`, SQLite
-     * `SQLITE_CONSTRAINT_UNIQUE`). This is the near-mandatory contract:
-     * `save()` is insert-or-update, never upsert. Create-idempotency
-     * belongs in the USE CASE (load, then decide), not in the save path.
-     * Set `false` ONLY for a deliberately upserting adapter
-     * (idempotent-create design); the duplicate-insert test is then
-     * reported as skipped under this capability name, without costing
-     * the deletion-finality coverage that `createAggregateWithId` also
-     * gates.
-     */
-    insertsAreDuplicateChecked?: boolean;
-    /**
-     * Optional: a plain-data projection of the aggregate's persisted
-     * state, compared with deep equality. Enables the mandatory test's
-     * state assertion (without it, only the version and the outbox are
-     * compared, and an adapter whose predicate guards the version write
-     * but not the state write would slip through).
-     *
-     * **The projection must be roundtrip-stable**: it compares a
-     * DB-reloaded aggregate against an in-memory one, so normalize
-     * anything your store changes in transit: dates to ISO strings at
-     * your store's precision (MySQL DATETIME truncates millis), no
-     * `undefined`-valued keys (JSON columns drop them), decimals/bigints
-     * to one consistent representation. A mismatch here fails the
-     * mandatory test; the message names the projection as a suspect.
-     */
-    snapshotState?(aggregate: TAgg): unknown;
-    /**
-     * Optional flag: declare it when your `delete(aggregate)` runs an
-     * OCC predicate (`DELETE … WHERE id = ? AND version = ?`). Enables
-     * the stale-delete conflict test. Unpredicated deletes are
-     * last-write-wins by construction: acceptable for GC-style
-     * cleanup, rarely for user-initiated deletion of contended
-     * aggregates (see the repository guide).
-     */
-    deletesAreVersionChecked?: boolean;
-}
-/**
- * One named contract test; `run` rejects with a descriptive Error on
- * violation. When the harness lacks the capability a test needs, the
- * entry is still returned with {@link skipped} set and a `run` that
- * REJECTS with an explanatory error: bind it with your runner's skip
- * (`(test.skipped ? it.skip : it)(test.name, test.run)`) so the gap is
- * visible in every test report: a missing capability must never look
- * like green coverage, and a naive binding that ignores `skipped`
- * fails loud instead of passing silently.
- */
-interface RepositoryContractTest {
-    name: string;
-    run: () => Promise<void>;
-    /** Present when the harness lacks the capability this test needs. */
-    skipped?: {
-        capability: string;
-    };
-}
-/**
- * The repository contract test suite: the proof that an adapter
- * actually delivers the guarantees the kit's Unit of Work documents.
- *
- * The kit is ORM-agnostic: the OCC version predicate lives in YOUR
- * repository's SQL. That makes optimistic concurrency a **repository
- * contract, not a kit guarantee**: the kit ships the boundary, the
- * `persistedVersion` baseline, `ConcurrencyConflictError`, and this
- * suite; your adapter must pass it. An adapter that has not passed the
- * suite (against a real database, for SQL adapters) has not
- * demonstrated OCC.
- *
- * Framework-agnostic: assertions throw plain `Error`s, so the suite
- * binds to vitest, jest, or `node:test` the same way:
- *
- * ```ts
- * import { describe, it } from "vitest";
- * import { createRepositoryContractTests } from "@shirudo/ddd-kit/testing";
- *
- * const harness: RepositoryContractHarness<Order, OrderEvent> = {
- *   createEnvironment: async () => {
- *     const schema = await provisionTestSchema(); // testcontainers etc.
- *     const uowDeps = {
- *       scope: schema.scope,
- *       outbox: schema.outbox,
- *       repositories: {
- *         orders: (tx, session) => new DrizzleOrderRepository(tx, session),
- *       },
- *     };
- *     return {
- *       run: (work) =>
- *         new UnitOfWork(uowDeps).run(({ repositories }) =>
- *           work({ repository: repositories.orders })),
- *       committedOutboxEvents: () => schema.readOutboxEvents(),
- *       teardown: () => schema.drop(),
- *     };
- *   },
- *   createAggregate: () => Order.draft(orderIds.next()),
- *   mutate: (order) => order.changeNote(`note-${counter++}`), // ONE bump + event
- *   // provide every optional capability your adapter supports:
- *   createAggregateWithId: (id) => Order.draft(id),
- *   snapshotState: (order) => normalizeForRoundtrip(order.state),
- *   deletesAreVersionChecked: true,
- * };
- *
- * describe("DrizzleOrderRepository: repository contract", () => {
- *   for (const test of createRepositoryContractTests(harness)) {
- *     (test.skipped ? it.skip : it)(test.name, test.run);
- *   }
- * });
- * ```
- *
- * **`env.run` must provide unit-of-work semantics.** Three core tests
- * (identity-map sameness, getById-null-after-delete, deletion
- * finality) exercise the session machinery: `session.identityMap`,
- * the `isDeleted` probe, the deleted-gate. Wiring `run` through the
- * kit's `UnitOfWork` gives you all of it; a hand-rolled `withCommit`
- * wiring must provide equivalents or those tests will fail. A
- * `withCommit`-only setup that deliberately makes no identity-map /
- * deletion-finality claims is outside this suite's scope; the suite
- * is the compliance bar for unit-of-work repositories.
- *
- * **Error matching is by NAME along the `cause` chain, not by
- * `instanceof`.** The suite ships in its own bundle entry; comparing
- * class identity would spuriously fail whenever the adapter's errors
- * come from a different copy of the kit (the main entry's bundle, or a
- * second installed version). `error.name === "ConcurrencyConflictError"`
- * anywhere in the chain is the contract.
- *
- * **What each test proves.** The OCC, routing, rollback, and outbox
- * tests prove YOUR adapter's SQL and transaction wiring. The
- * identity-map, deletion-finality, and event-lifecycle tests prove
- * your READ-PATH and unit-of-work WIRING (they exercise kit-provided
- * machinery, namely `session.identityMap`, the deleted-gate, and
- * `withCommit`'s harvest, and fail when your repository bypasses or
- * mis-wires it).
- * A deletion-finality failure usually means a missing
- * `identityMap.isDeleted` check or an `enrollSaved` placed after the
- * row write, not a broken DELETE statement.
- *
- * **Known limitation: no truly concurrent runs.** The mandatory
- * two-writer test is deliberately sequential-deterministic: writer B
- * loads, writer A loads/mutates/commits, then B commits its stale
- * instance. The stale `persistedVersion` baseline travels with B's
- * instance, so the version predicate is exercised exactly as in a true
- * race, without depending on lock timing, pool sizes, or
- * engine-specific blocking. The flip side: lock interaction is NOT
- * covered. A `SELECT … FOR UPDATE`-style repository that blocks
- * instead of conflicting, or a SERIALIZABLE engine surfacing raw
- * serialization failures (Postgres 40001) your adapter must map to
- * `ConcurrencyConflictError`, needs adapter-specific tests on top of
- * this suite.
- */
-declare function createRepositoryContractTests<TAgg extends IAggregateRoot<Id<string>, Evt>, Evt extends AnyDomainEvent = AnyDomainEvent>(harness: RepositoryContractHarness<TAgg, Evt>): RepositoryContractTest[];
-
-export { type ContractRepository, type RepositoryContractEnvironment, type RepositoryContractHarness, type RepositoryContractTest, createRepositoryContractTests };
+import { Lt as PublishedCommand, P as EventBus, Pt as AggregateAddress, R as Aggregate, W as Id, Y as CommandOutboxCommitCandidate, Z as CommandOutboxWriter, _ as IdempotencyStore, a as StreamReadResult, c as ProjectionCheckpointStore, ct as EventCommitCandidate, f as IdempotencyClaimHandle, i as ReadStreamOptions, n as EventStore, nt as Outbox, st as CommittedDomainEvent, t as SnapshotStore, tt as DispatchTrackingOutbox, ut as AnyDomainEvent, w as DeadlineStore } from "./chunks/snapshot-store.js";
+//#region src/testing/contract-assertions.d.ts
+/**
+ * One entry of a contract test suite. Every suite (repository,
+ * event-sourced repository, outbox, idempotency store) returns a list
+ * of these; bind them with
+ * `(test.skipped ? it.skip : it)(test.name, test.run)`.
+ */
+interface ContractTest {
+  name: string;
+  run: () => Promise<void>;
+  /** Present when the harness lacks the capability this test needs. */
+  skipped?: {
+    capability: string;
+  };
+}
+//#endregion
+//#region src/testing/command-outbox-contract.d.ts
+interface CommandOutboxContractEnvironment<C extends PublishedCommand> {
+  readonly outbox: CommandOutboxWriter<C>;
+  readonly addCommitted: (commits: ReadonlyArray<CommandOutboxCommitCandidate<C>>) => Promise<void>;
+  readonly addRolledBack?: (commits: ReadonlyArray<CommandOutboxCommitCandidate<C>>) => Promise<void>;
+  readonly readAll: () => Promise<ReadonlyArray<CommandOutboxCommitCandidate<C>>>;
+  readonly teardown?: () => Promise<void>;
+}
+interface CommandOutboxContractHarness<C extends PublishedCommand> {
+  readonly createEnvironment: () => Promise<CommandOutboxContractEnvironment<C>>;
+  /**
+   * Builds one command for the given seed. The suite derives conflicting
+   * commits from different seeds, so `createCommand` MUST return distinct
+   * command content per seed (put the seed in the payload). A constant
+   * command makes a manufactured conflict deep-equal to its original, and
+   * the conflict tests then fail a compliant adapter that deduplicates
+   * the exact retry.
+   */
+  readonly createCommand: (seed: number) => C;
+  readonly providesRolledBackAdds?: boolean;
+}
+type CommandOutboxContractTest = ContractTest;
+declare function createCommandOutboxContractTests<C extends PublishedCommand>(harness: CommandOutboxContractHarness<C>): ReadonlyArray<CommandOutboxContractTest>;
+//#endregion
+//#region src/testing/deadline-store-contract.d.ts
+/** One contract test; bind with `(test.skipped ? it.skip : it)(test.name, test.run)`. */
+type DeadlineStoreContractTest = ContractTest;
+/** The plain-data payload shape the suite round-trips. */
+interface SuitePayload {
+  kind: string;
+  step?: number;
+}
+/**
+ * One isolated test environment: a fresh deadline store. The suite
+ * creates one per test and tears it down afterwards.
+ */
+interface DeadlineStoreContractEnvironment {
+  /** The adapter under test. */
+  store: DeadlineStore<SuitePayload>;
+  /**
+   * Runs `work` (schedule/cancel calls) the way production does:
+   * inside a transaction that COMMITS. For a non-transactional store
+   * this simply invokes `work`.
+   */
+  run<R>(work: () => Promise<R>): Promise<R>;
+  /**
+   * Optional capability: runs `work` inside a transaction that ROLLS
+   * BACK. Enables the rollback tests: a rolled-back schedule must not
+   * leave a deadline behind (a ghost input for a state change that
+   * never happened), and a rolled-back cancel must not have removed
+   * one. Transactional adapters should always provide this.
+   */
+  runRolledBack?<R>(work: () => Promise<R>): Promise<R>;
+  /** Release connections, drop schemas, etc. Called in a finally. */
+  teardown?(): Promise<void>;
+}
+/**
+ * What an adapter supplies to run the deadline-store contract suite.
+ * For SQL adapters, run against a real database (testcontainers or
+ * equivalent): the rollback tests prove YOUR transaction wiring, and
+ * schedule/cancel joining the write transaction is the port's central
+ * correctness rule.
+ */
+interface DeadlineStoreContractHarness {
+  createEnvironment(): Promise<DeadlineStoreContractEnvironment>;
+  /**
+   * The adapter's attempt ceiling: how many `markFailed` reports move
+   * a deadline to the dead-letter set. Must be at least 2 so the
+   * attempts-surfacing test can observe a survivor.
+   */
+  failuresToDeadLetter: number;
+  /**
+   * Declare `true` when environments provide {@link
+   * DeadlineStoreContractEnvironment.runRolledBack}. Without it, the
+   * rollback tests are marked skipped: the honest state of an
+   * in-memory fake, and a loud gap for a transactional adapter.
+   */
+  providesRolledBackRuns?: boolean;
+  /**
+   * Declare `true` when the adapter's `due` CLAIMS the returned
+   * records for competing pollers (lease, visibility timeout), as the
+   * port sanctions. Tests that re-poll records an earlier poll
+   * returned without resolving them (attempts surfacing, neighbor
+   * flow after a dead-letter, successor visibility during a
+   * reschedule race) assume a non-claiming read and are marked
+   * skipped for claiming adapters; prove your claim/expiry semantics
+   * in your own suite.
+   */
+  claimsOnDue?: boolean;
+}
+/**
+ * The deadline-store contract test suite: the proof that an adapter
+ * delivers the schedule/cancel/due/acknowledge semantics the port
+ * documents. Store semantics are an **adapter contract, not a kit
+ * guarantee**; this suite is how an adapter demonstrates them.
+ *
+ * Framework-agnostic: bind with
+ * `(test.skipped ? it.skip : it)(test.name, test.run)`.
+ */
+declare function createDeadlineStoreContractTests(harness: DeadlineStoreContractHarness): DeadlineStoreContractTest[];
+//#endregion
+//#region src/testing/es-repository-contract.d.ts
+/** Event-sourced repositories normally expose no physical removal. */
+interface EsContractRepository<TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> {
+  findById(id: TAggregate["id"]): Promise<TAggregate | undefined>;
+  add(aggregate: TAggregate): void;
+  update(aggregate: TAggregate): void;
+}
+interface EsRepositoryContractEnvironment<TAggregate extends Aggregate<Id<string>, TEvent>, TEvent extends AnyDomainEvent = AnyDomainEvent> {
+  run<R>(work: (context: {
+    repository: EsContractRepository<TAggregate>;
+  }) => Promise<R>): Promise<R>;
+  committedOutboxEvents(): Promise<ReadonlyArray<CommittedDomainEvent<TEvent>>>;
+  failNextOutboxWrite(error: Error): void;
+  committedStreamEvents(stream: AggregateAddress<TAggregate["id"]>, options: ReadStreamOptions): Promise<StreamReadResult<TEvent>>;
+  teardown?(): Promise<void>;
+}
+interface EsRepositoryContractHarness<TAggregate extends Aggregate<Id<string>, TEvent>, TEvent extends AnyDomainEvent = AnyDomainEvent> {
+  createEnvironment(): Promise<EsRepositoryContractEnvironment<TAggregate, TEvent>>;
+  /** Fresh aggregate with exactly one recorded creation event. */
+  createAggregate(): TAggregate;
+  createAggregateWithId?(id: TAggregate["id"]): TAggregate;
+  streamKeyFor(id: TAggregate["id"]): AggregateAddress<TAggregate["id"]>;
+  /** Applies exactly one event and advances the aggregate version by one. */
+  mutate(aggregate: TAggregate): void;
+  snapshotState?(aggregate: TAggregate): unknown;
+  /**
+   * Persists a snapshot of the aggregate at its current version in the
+   * environment's snapshot store, so the next load there starts from it.
+   * Enables the snapshot catch-up proof.
+   */
+  captureSnapshot?(aggregate: TAggregate, environment: EsRepositoryContractEnvironment<TAggregate, TEvent>): Promise<void>;
+  /**
+   * Bound for the overlapping `run` calls, in milliseconds: the second call
+   * of the environment preflight, and the committing call of each
+   * stale-writer proof. Raise it only for a second connection that needs
+   * more time to open, or for a slow commit. Keep twice the bound, plus
+   * environment creation and teardown, below the test timeout of the runner.
+   */
+  overlappingCallsBoundMs?: number;
+}
+type EsRepositoryContractTest = ContractTest;
+/**
+ * Contract suite for event-stream adapters using v3 Unit-of-Work receipts.
+ *
+ * `add` and `update` register intent only. At commit, the adapter appends the
+ * receipt's exact event batch with the Unit of Work's expected version, in the
+ * same transaction as the outbox. `run` must support overlapping calls so the
+ * mandatory stale-writer proof exercises a real stream OCC predicate.
+ */
+declare function createEsRepositoryContractTests<TAggregate extends Aggregate<Id<string>, TEvent>, TEvent extends AnyDomainEvent = AnyDomainEvent>(harness: EsRepositoryContractHarness<TAggregate, TEvent>): EsRepositoryContractTest[];
+//#endregion
+//#region src/testing/event-bus-contract.d.ts
+/** One entry of the event-bus contract suite. */
+type EventBusContractTest = ContractTest;
+/**
+ * What the suite runs against. The harness creates one per test and tears
+ * it down afterwards. No transaction wrapper: the port is in-process and
+ * transaction-free by design.
+ */
+interface EventBusContractEnvironment<Evt extends AnyDomainEvent> {
+  /** The implementation under test. */
+  readonly bus: EventBus<Evt>;
+  /** Release connections, drop schemas, etc. Called in a finally. */
+  teardown?(): Promise<void>;
+}
+/**
+ * What an implementation supplies to run the event-bus contract suite.
+ *
+ * The suite mints no events, so it stays free of any event union. The two
+ * factories must produce DIFFERENT `type` values: the suite subscribes to
+ * both to prove that ordering holds across types and that a catch-all
+ * subscription sees every type.
+ */
+interface EventBusContractHarness<Evt extends AnyDomainEvent> {
+  createEnvironment(): Promise<EventBusContractEnvironment<Evt>>;
+  /** An event of the first type. Called repeatedly; each call may differ. */
+  createFirstEvent(): Evt;
+  /** An event of the second type, whose `type` differs from the first. */
+  createSecondEvent(): Evt;
+}
+/**
+ * The event-bus contract test suite: the proof that an implementation
+ * delivers the guarantees the `EventBus` port documents. Ordering,
+ * parallelism within one event, and error collection after the batch are
+ * a **port contract, not a kit guarantee**; this suite is how an
+ * implementation demonstrates them.
+ *
+ * The suite covers the port and nothing else. Construction options of the
+ * kit's own adapter, such as a publish-depth bound or an observer bundle,
+ * are not port behavior and are not pinned here.
+ *
+ * Framework-agnostic: bind with
+ * `(test.skipped ? it.skip : it)(test.name, test.run)`.
+ */
+declare function createEventBusContractTests<Evt extends AnyDomainEvent>(harness: EventBusContractHarness<Evt>): EventBusContractTest[];
+//#endregion
+//#region src/testing/event-store-contract.d.ts
+/** One named contract test for an EventStore adapter. */
+type EventStoreContractTest = ContractTest;
+/** One isolated adapter instance. The suite creates one per test. */
+interface EventStoreContractEnvironment<Evt extends AnyDomainEvent> {
+  readonly store: EventStore<Evt>;
+  teardown?(): Promise<void>;
+}
+/**
+ * Inputs needed to prove the EventStore's observable port contract.
+ *
+ * `createCollidingStreamKeys` must return two valid stream keys with the same
+ * raw aggregate id and different aggregate types. `createEvent` must return an
+ * event addressed to the supplied key; different sequence values must produce
+ * different event ids.
+ */
+interface EventStoreContractHarness<Evt extends AnyDomainEvent> {
+  createEnvironment(): Promise<EventStoreContractEnvironment<Evt>>;
+  createCollidingStreamKeys(): readonly [AggregateAddress, AggregateAddress];
+  createEvent(stream: AggregateAddress, sequence: number): Evt;
+}
+/**
+ * Reusable proof of an EventStore adapter's portable semantics: qualified
+ * value identity, ordered reads and slicing, OCC error mapping and atomicity,
+ * no-op empty appends, and detached return arrays. Physical-position
+ * corruption needs adapter-specific fixture support and is tested there.
+ */
+declare function createEventStoreContractTests<Evt extends AnyDomainEvent>(harness: EventStoreContractHarness<Evt>): EventStoreContractTest[];
+//#endregion
+//#region src/testing/idempotency-store-contract.d.ts
+/** One contract test; bind with `(test.skipped ? it.skip : it)(test.name, test.run)`. */
+type IdempotencyStoreContractTest = ContractTest;
+/**
+ * One isolated test environment: a fresh idempotency store. The suite
+ * creates one per test and tears it down afterwards.
+ */
+interface IdempotencyStoreContractEnvironment<TCtx> {
+  /** The adapter under test. */
+  store: IdempotencyStore<TCtx>;
+  /**
+   * Runs `work` inside a transaction that COMMITS, handing it the
+   * transaction context the store methods expect, the way
+   * `withIdempotentCommit` calls them in production. For a
+   * non-transactional store this simply invokes `work` with a dummy
+   * context.
+   */
+  run<R>(work: (ctx: TCtx) => Promise<R>): Promise<R>;
+  /**
+   * For the `"transactional"` family: runs `work` inside a transaction
+   * that ROLLS BACK. Required there; the rollback-releases-the-claim
+   * test is that family's core proof. Irrelevant for the
+   * `"non-transactional"` family.
+   */
+  runRolledBack?<R>(work: (ctx: TCtx) => Promise<R>): Promise<R>;
+  /**
+   * For the `"non-transactional"` family: advances or edits adapter test
+   * state so this exact claim's CURRENT lease is expired. Required there;
+   * a fake clock or test-only row update keeps the suite deterministic.
+   */
+  expireLease?(claim: IdempotencyClaimHandle): Promise<void>;
+  /**
+   * Moves the adapter's test clock to an exact instant. Required by the
+   * non-transactional family so renewal is proved without wall-clock sleeps.
+   */
+  advanceTimeTo?(instant: Date): Promise<void>;
+  /** Release connections, drop schemas, etc. Called in a finally. */
+  teardown?(): Promise<void>;
+}
+/**
+ * What an adapter supplies to run the idempotency-store contract suite.
+ *
+ * The port (`IdempotencyStore`) deliberately supports two adapter
+ * families with different lifecycle semantics, and the suite follows
+ * the declared family instead of forcing one onto the other:
+ *
+ * - `"transactional"` (the single-transaction pattern): the record
+ *   lives in the same database as the aggregates; a committed
+ *   `complete` is final and replayable, a rollback releases everything,
+ *   and `renew`/`confirm`/`abandon`/`reconcile` are no-ops. The family's core proof is the
+ *   rollback test, so environments MUST provide `runRolledBack`, and
+ *   run against a real database for SQL adapters.
+ * - `"non-transactional"` (the leased two-phase pattern, e.g. the
+ *   in-memory reference): the store cannot see commits, so `complete` only
+ *   STAGES the outcome, `confirm` finalizes it post-commit, `abandon`
+ *   compensates failed attempts, and expired staged records require
+ *   reconciliation. Environments MUST provide deterministic `expireLease` and
+ *   `advanceTimeTo` controls. The rollback test is skipped.
+ */
+interface IdempotencyStoreContractHarness<TCtx> {
+  createEnvironment(): Promise<IdempotencyStoreContractEnvironment<TCtx>>;
+  /** Which lifecycle family the adapter implements; see above. */
+  family: "transactional" | "non-transactional";
+}
+/**
+ * The idempotency-store contract test suite: the proof that an adapter
+ * delivers the claim/renew/complete/confirm/abandon/reconcile lifecycle
+ * `withIdempotentCommit` documents, for its declared family. Store
+ * semantics are an **adapter contract, not a kit guarantee**; this
+ * suite is how an adapter demonstrates them.
+ *
+ * Framework-agnostic: bind with
+ * `(test.skipped ? it.skip : it)(test.name, test.run)`.
+ */
+declare function createIdempotencyStoreContractTests<TCtx>(harness: IdempotencyStoreContractHarness<TCtx>): IdempotencyStoreContractTest[];
+//#endregion
+//#region src/testing/outbox-contract.d.ts
+/** One contract test; bind with `(test.skipped ? it.skip : it)(test.name, test.run)`. */
+type OutboxContractTest = ContractTest;
+/**
+ * One isolated test environment: a fresh outbox store. The suite
+ * creates one per test and tears it down afterwards.
+ */
+interface OutboxContractEnvironment<Evt extends AnyDomainEvent> {
+  /** The adapter under test. */
+  outbox: Outbox<Evt> | DispatchTrackingOutbox<Evt>;
+  /**
+   * Runs `outbox.add(candidates)` inside a transaction that COMMITS, the
+   * way `withCommit` calls it in production. The suite supplies complete
+   * candidates with explicit source, aggregate version, zero-based commit
+   * sequence, and commit size. For a non-transactional store this is simply
+   * `outbox.add(candidates)`.
+   */
+  addCommitted(events: ReadonlyArray<EventCommitCandidate<Evt>>): Promise<void>;
+  /**
+   * Optional capability: runs `outbox.add(candidates)` inside a
+   * transaction that ROLLS BACK. Enables the rollback-purity test: a
+   * rolled-back add must leave nothing behind. Transactional adapters
+   * should always provide this; it is the half of the outbox promise
+   * that in-memory fakes cannot keep.
+   */
+  addRolledBack?(events: ReadonlyArray<EventCommitCandidate<Evt>>): Promise<void>;
+  /** Release connections, drop schemas, etc. Called in a finally. */
+  teardown?(): Promise<void>;
+}
+/**
+ * What an adapter supplies to run the outbox contract suite.
+ *
+ * For SQL adapters, run against a real database (testcontainers or
+ * equivalent): the commit-order and rollback tests prove YOUR schema
+ * and transaction wiring, not the kit's.
+ *
+ * Note on claiming: multi-instance safety (`getPending` claiming via
+ * `FOR UPDATE SKIP LOCKED` or equivalent) is part of the port contract
+ * for competing dispatchers but is not covered here; concurrency
+ * cannot be proven portably by a generic suite. Test it in your
+ * adapter's own suite if you run more than one dispatcher.
+ */
+interface OutboxContractHarness<Evt extends AnyDomainEvent> {
+  createEnvironment(): Promise<OutboxContractEnvironment<Evt>>;
+  /**
+   * Deterministic event factory: the same `seed` yields an event with
+   * the SAME `eventId` (the suite uses this for the dedupe test), and
+   * different seeds yield distinct `eventId`s.
+   */
+  createEvent(seed: number): Evt;
+  /**
+   * For a `DispatchTrackingOutbox` adapter: how many `markFailed`
+   * reports move a record to the dead-letter set (the adapter's
+   * configured attempt ceiling). Omit for plain `Outbox` adapters;
+   * the dispatch-tracking tests are then marked skipped. With a
+   * ceiling of 1 the attempts-surfacing test is marked skipped too:
+   * observing attempts on a PENDING record needs a record that
+   * survives one failure.
+   */
+  failuresToDeadLetter?: number;
+  /**
+   * Declare `true` when environments provide {@link
+   * OutboxContractEnvironment.addRolledBack}. Without it, the
+   * rollback-purity test is marked skipped: the honest state of an
+   * in-memory fake, and a loud gap for a transactional adapter.
+   */
+  providesRolledBackAdds?: boolean;
+  /**
+   * Declare `true` when the adapter's `getPending` CLAIMS the returned
+   * records for competing dispatchers (lease, visibility timeout,
+   * `FOR UPDATE SKIP LOCKED`), as the port sanctions. Every test that
+   * re-polls records a previous poll returned without resolving them
+   * (head stability, re-ack non-disturbance, attempts surfacing)
+   * assumes a non-claiming read and is marked skipped for claiming
+   * adapters; prove your claim/expiry semantics in your own suite.
+   */
+  claimsOnGetPending?: boolean;
+  /**
+   * Declare `true` when `add()` dedupes on `eventId` (the unique-key
+   * constraint the port RECOMMENDS). The dedupe test is gated on this:
+   * an adapter without the constraint satisfies the port's normative
+   * requirements and must not fail the suite, but the skip stays
+   * visible as the unproven recommendation it is.
+   */
+  dedupesOnEventId?: boolean;
+}
+/**
+ * The outbox contract test suite: the proof that an adapter delivers
+ * the guarantees `withCommit` and `OutboxDispatcher` document. The kit
+ * is store-agnostic, so commit-order reads, qualified source-position
+ * identity, eventful-predecessor linkage, idempotent acks, and rollback
+ * purity are an **adapter contract, not a kit guarantee**; this suite is how
+ * an adapter demonstrates them. Its source-law tests also prove that colliding
+ * raw ids stay isolated by aggregate type and aggregate id.
+ *
+ * Framework-agnostic: bind with
+ * `(test.skipped ? it.skip : it)(test.name, test.run)`.
+ */
+declare function createOutboxContractTests<Evt extends AnyDomainEvent>(harness: OutboxContractHarness<Evt>): OutboxContractTest[];
+//#endregion
+//#region src/testing/projection-checkpoint-contract.d.ts
+/** One contract test; bind with `(test.skipped ? it.skip : it)(test.name, test.run)`. */
+type ProjectionCheckpointStoreContractTest = ContractTest;
+/**
+ * One isolated test environment: a fresh checkpoint store. The suite
+ * creates one per test and tears it down afterwards.
+ */
+interface ProjectionCheckpointStoreContractEnvironment<TCtx> {
+  /** The adapter under test. */
+  store: ProjectionCheckpointStore<TCtx>;
+  /**
+   * Runs `work` inside a transaction that COMMITS, handing it the
+   * transaction context the store methods expect, the way the
+   * `Projector` calls them in production. For a non-transactional
+   * store this simply invokes `work` with a dummy context.
+   */
+  run<R>(work: (ctx: TCtx) => Promise<R>): Promise<R>;
+  /**
+   * Optional capability: starts every supplied transaction independently and
+   * concurrently. Each callback must receive its own transaction context for
+   * database adapters (normally a separate pooled connection). Enables the
+   * missing-key/existing-key exclusion test; implementing this as sequential
+   * calls would make that proof meaningless.
+   */
+  runConcurrently?<R>(works: ReadonlyArray<(ctx: TCtx) => Promise<R>>): Promise<R[]>;
+  /**
+   * Optional capability: runs `work` inside a transaction that ROLLS
+   * BACK. Enables the rollback test: a rolled-back save must leave no
+   * checkpoint behind, the half of the atomic update+checkpoint
+   * promise the store contributes. Transactional adapters should
+   * always provide this; in-memory fakes cannot.
+   */
+  runRolledBack?<R>(work: (ctx: TCtx) => Promise<R>): Promise<R>;
+  /** Release connections, drop schemas, etc. Called in a finally. */
+  teardown?(): Promise<void>;
+}
+/**
+ * What an adapter supplies to run the projection-checkpoint-store
+ * contract suite. For SQL adapters, run against a real database
+ * (testcontainers or equivalent): concurrent runs prove missing-key locking,
+ * the rollback test proves YOUR transaction wiring, and the checkpoint table
+ * must live in the same database as the read models it accounts for.
+ */
+interface ProjectionCheckpointStoreContractHarness<TCtx> {
+  createEnvironment(): Promise<ProjectionCheckpointStoreContractEnvironment<TCtx>>;
+  /**
+   * Declare `true` when environments provide {@link
+   * ProjectionCheckpointStoreContractEnvironment.runRolledBack}.
+   * Without it, the rollback test is marked skipped: the honest state
+   * of an in-memory fake, and a loud gap for a transactional adapter.
+   */
+  providesRolledBackRuns?: boolean;
+  /**
+   * Declare `true` when environments provide {@link
+   * ProjectionCheckpointStoreContractEnvironment.runConcurrently}. Without
+   * it, missing-key lock safety is marked skipped and remains an explicitly
+   * unproven adapter guarantee.
+   */
+  providesConcurrentRuns?: boolean;
+}
+/**
+ * The projection-checkpoint-store contract test suite: the proof that
+ * an adapter delivers the watermark semantics the `Projector`
+ * documents. Checkpoint semantics are an **adapter contract, not a
+ * kit guarantee**; this suite is how an adapter demonstrates them. Enable its
+ * concurrent-runs capability to prove genesis-safe exclusion rather than
+ * leaving that guarantee visibly skipped.
+ *
+ * The concurrent test exercises commit visibility, but cannot deterministically
+ * hold an adapter between return from `withCheckpointLocks` and its surrounding
+ * transaction commit. It can therefore expose an early lock release only when
+ * a waiter enters during that window; holding database locks through commit or
+ * rollback remains an explicit adapter responsibility, not a complete proof
+ * supplied by this suite.
+ *
+ * Framework-agnostic: bind with
+ * `(test.skipped ? it.skip : it)(test.name, test.run)`.
+ */
+declare function createProjectionCheckpointStoreContractTests<TCtx>(harness: ProjectionCheckpointStoreContractHarness<TCtx>): ProjectionCheckpointStoreContractTest[];
+//#endregion
+//#region src/testing/repository-contract.d.ts
+/** Application-facing state-stored repository exercised by the suite. */
+interface ContractRepository<TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> {
+  findById(id: TAggregate["id"]): Promise<TAggregate | undefined>;
+  add(aggregate: TAggregate): void;
+  /** An append-only port declares no update. */
+  update?(aggregate: TAggregate): void;
+  /** Physical removal is an optional persistence capability. */
+  remove?(aggregate: TAggregate): void;
+}
+/** One isolated real-adapter environment. `run` must permit overlapping calls. */
+interface RepositoryContractEnvironment<TAggregate extends Aggregate<Id<string>, TEvent>, TEvent extends AnyDomainEvent = AnyDomainEvent> {
+  run<R>(work: (context: {
+    repository: ContractRepository<TAggregate>;
+  }) => Promise<R>): Promise<R>;
+  committedOutboxEvents(): Promise<ReadonlyArray<CommittedDomainEvent<TEvent>>>;
+  /** Makes the next transactional outbox write fail for atomicity proof. */
+  failNextOutboxWrite(error: Error): void;
+  teardown?(): Promise<void>;
+}
+/** Fixtures and observable projections supplied by an adapter package. */
+interface RepositoryContractHarness<TAggregate extends Aggregate<Id<string>, TEvent>, TEvent extends AnyDomainEvent = AnyDomainEvent> {
+  createEnvironment(): Promise<RepositoryContractEnvironment<TAggregate, TEvent>>;
+  /** A fresh aggregate with a unique id. */
+  createAggregate(): TAggregate;
+  /** One version-bumping decision that records at least one event. */
+  mutate(aggregate: TAggregate): void;
+  /** Required for duplicate-add and same-UoW deletion-finality proofs. */
+  createAggregateWithId?(id: TAggregate["id"]): TAggregate;
+  /**
+   * A version-bumping decision with no event whose resulting state is
+   * deep-equal to the previous state (`setState({ ...state })`). The
+   * deep-equal requirement is load-bearing: it forces a diff-based
+   * `PersistenceModel` to derive an EMPTY change set, so the suite proves
+   * that an adapter persists the bumped version even when
+   * `changes.empty` is true. Skipping that write desyncs the persisted
+   * version and produces false concurrency conflicts later.
+   */
+  mutateVersionOnly?(aggregate: TAggregate): void;
+  /** A decision that changes a nested collection. */
+  mutateChildCollection?(aggregate: TAggregate): void;
+  /** Round-trip-stable adapter persistence projection. */
+  snapshotState?(aggregate: TAggregate): unknown;
+  /** Opt out only for an intentionally upserting add implementation. */
+  insertsAreDuplicateChecked?: boolean;
+  /**
+   * Opt out only for an append-only port, one that the definition marks
+   * with `appendOnly: true`. The suite then skips every update proof. The
+   * duplicate-add proof is the concurrency proof that remains, so it is
+   * mandatory. Provide `createAggregateWithId` and keep
+   * `insertsAreDuplicateChecked`, or the proof fails instead of skipping.
+   */
+  updatesAreSupported?: boolean;
+  /** Enables physical-remove behavior and stale-remove OCC tests. */
+  removesAreSupported?: boolean;
+  /** The remove flush predicates on the version captured at load. */
+  removesAreVersionChecked?: boolean;
+  /**
+   * Bound for the overlapping `run` calls, in milliseconds: the second call
+   * of the environment preflight, and the committing call of each
+   * stale-writer proof. Raise it only for a second connection that needs
+   * more time to open, or for a slow commit. Keep twice the bound, plus
+   * environment creation and teardown, below the test timeout of the runner.
+   */
+  overlappingCallsBoundMs?: number;
+}
+type RepositoryContractTest = ContractTest;
+/**
+ * Contract suite for the v3 explicit-intent, commit-time-flush protocol.
+ *
+ * The harness must use the public `UnitOfWork` with a real adapter. In
+ * particular, `run` must create a fresh Unit of Work and transaction for each
+ * call and allow two calls to overlap; the mandatory stale-writer proof keeps
+ * writer B open while writer A commits. SQL/ORM adapters therefore need a
+ * real database and connection pool. An in-memory harness proves only itself.
+ *
+ * Writes are synchronous registrations. Durable adapter I/O happens after the
+ * callback returns, while the transaction is still open. A test that passes
+ * because `add` or `update` writes early is not a conforming implementation.
+ */
+declare function createRepositoryContractTests<TAggregate extends Aggregate<Id<string>, TEvent>, TEvent extends AnyDomainEvent = AnyDomainEvent>(harness: RepositoryContractHarness<TAggregate, TEvent>): RepositoryContractTest[];
+//#endregion
+//#region src/testing/snapshot-store-contract.d.ts
+/** One contract test; bind with `(test.skipped ? it.skip : it)(test.name, test.run)`. */
+type SnapshotStoreContractTest = ContractTest;
+/** The plain-data state shape the suite round-trips. */
+interface SuiteState {
+  total: number;
+  items: Array<{
+    sku: string;
+    qty: number;
+  }>;
+  note?: string;
+}
+/**
+ * One isolated test environment: a fresh snapshot store. The suite
+ * creates one per test and tears it down afterwards. No transaction
+ * wrapper: the port is transaction-free by design (snapshots are
+ * derived data written after the commit; see `SnapshotStore`).
+ */
+interface SnapshotStoreContractEnvironment {
+  /** The adapter under test. */
+  store: SnapshotStore<SuiteState>;
+  /** Release connections, drop schemas, etc. Called in a finally. */
+  teardown?(): Promise<void>;
+}
+/**
+ * What an adapter supplies to run the snapshot-store contract suite.
+ * For SQL adapters, run against a real database (testcontainers or
+ * equivalent). Note the fidelity demands the suite enforces:
+ * `snapshotAt` must survive with millisecond precision (store it as
+ * ISO-8601 text or epoch milliseconds; MySQL `DATETIME` without
+ * fractional seconds truncates), and an ABSENT `schemaVersion` must
+ * come back absent, not as `0` or `null`-coerced.
+ */
+interface SnapshotStoreContractHarness {
+  createEnvironment(): Promise<SnapshotStoreContractEnvironment>;
+}
+/**
+ * The snapshot-store contract test suite: the proof that an adapter
+ * delivers the round-trip and isolation semantics the
+ * snapshot-plus-recent-events load path relies on. Store semantics are
+ * an **adapter contract, not a kit guarantee**; this suite is how an
+ * adapter demonstrates them.
+ *
+ * Framework-agnostic: bind with
+ * `(test.skipped ? it.skip : it)(test.name, test.run)`.
+ */
+declare function createSnapshotStoreContractTests(harness: SnapshotStoreContractHarness): SnapshotStoreContractTest[];
+//#endregion
+export { type CommandOutboxContractEnvironment, type CommandOutboxContractHarness, type CommandOutboxContractTest, type ContractRepository, type DeadlineStoreContractEnvironment, type DeadlineStoreContractHarness, type DeadlineStoreContractTest, type EsContractRepository, type EsRepositoryContractEnvironment, type EsRepositoryContractHarness, type EsRepositoryContractTest, type EventBusContractEnvironment, type EventBusContractHarness, type EventBusContractTest, type EventStoreContractEnvironment, type EventStoreContractHarness, type EventStoreContractTest, type IdempotencyStoreContractEnvironment, type IdempotencyStoreContractHarness, type IdempotencyStoreContractTest, type OutboxContractEnvironment, type OutboxContractHarness, type OutboxContractTest, type ProjectionCheckpointStoreContractEnvironment, type ProjectionCheckpointStoreContractHarness, type ProjectionCheckpointStoreContractTest, type RepositoryContractEnvironment, type RepositoryContractHarness, type RepositoryContractTest, type SnapshotStoreContractEnvironment, type SnapshotStoreContractHarness, type SnapshotStoreContractTest, createCommandOutboxContractTests, createDeadlineStoreContractTests, createEsRepositoryContractTests, createEventBusContractTests, createEventStoreContractTests, createIdempotencyStoreContractTests, createOutboxContractTests, createProjectionCheckpointStoreContractTests, createRepositoryContractTests, createSnapshotStoreContractTests };
+//# sourceMappingURL=testing.d.ts.map