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

package/dist/testing.js

@@ -1,1212 +1,2424 @@
-var __defProp = Object.defineProperty;
-var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+import { r as deepEqual } from "./chunks/deep-equal-except.js";
+import { t as isDispatchTrackingOutbox, u as isMintedEvent } from "./chunks/ports.js";
 
-// src/utils/array/is-built-in.ts
-var BUILT_IN_TAGS = /* @__PURE__ */ new Set([
-  "[object Date]",
-  "[object RegExp]",
-  "[object Map]",
-  "[object Set]",
-  "[object WeakMap]",
-  "[object WeakSet]",
-  "[object Promise]",
-  "[object Error]",
-  "[object Boolean]",
-  "[object Number]",
-  "[object String]",
-  "[object BigInt]",
-  "[object ArrayBuffer]",
-  "[object SharedArrayBuffer]",
-  "[object DataView]"
-]);
-function intrinsicGetter(proto, prop) {
-  const get = Object.getOwnPropertyDescriptor(proto, prop)?.get;
-  if (!get) throw new Error(`missing intrinsic getter for ${prop}`);
-  return get;
-}
-__name(intrinsicGetter, "intrinsicGetter");
-var dateGetTime = Date.prototype.getTime;
-var mapSizeGet = intrinsicGetter(Map.prototype, "size");
-var setSizeGet = intrinsicGetter(Set.prototype, "size");
-var weakMapHas = WeakMap.prototype.has;
-var weakSetHas = WeakSet.prototype.has;
-var dataViewByteLengthGet = intrinsicGetter(DataView.prototype, "byteLength");
-var arrayBufferByteLengthGet = intrinsicGetter(
-  ArrayBuffer.prototype,
-  "byteLength"
-);
-var sharedArrayBufferByteLengthGet = typeof SharedArrayBuffer === "undefined" ? void 0 : intrinsicGetter(SharedArrayBuffer.prototype, "byteLength");
-var regExpSourceGet = intrinsicGetter(RegExp.prototype, "source");
-var booleanValueOf = Boolean.prototype.valueOf;
-var numberValueOf = Number.prototype.valueOf;
-var stringValueOf = String.prototype.valueOf;
-var bigIntValueOf = BigInt.prototype.valueOf;
-var functionToString = Function.prototype.toString;
-var PROBE_KEY = {};
-var INTRINSIC_CONSTRUCTOR_NAMES = [
-  "Object",
-  "Array",
-  "Date",
-  "RegExp",
-  "Map",
-  "Set",
-  "WeakMap",
-  "WeakSet",
-  "Promise",
-  "Error",
-  "EvalError",
-  "RangeError",
-  "ReferenceError",
-  "SyntaxError",
-  "TypeError",
-  "URIError",
-  "AggregateError",
-  "Boolean",
-  "Number",
-  "String",
-  "BigInt",
-  "ArrayBuffer",
-  "SharedArrayBuffer",
-  "DataView",
-  "Int8Array",
-  "Uint8Array",
-  "Uint8ClampedArray",
-  "Int16Array",
-  "Uint16Array",
-  "Int32Array",
-  "Uint32Array",
-  "Float32Array",
-  "Float64Array",
-  "BigInt64Array",
-  "BigUint64Array"
-];
-var intrinsicConstructorSources = new Map(
-  INTRINSIC_CONSTRUCTOR_NAMES.flatMap((name) => {
-    const descriptor = Object.getOwnPropertyDescriptor(globalThis, name);
-    const intrinsic = descriptor?.value;
-    return typeof intrinsic === "function" ? [[name, functionToString.call(intrinsic)]] : [];
-  })
-);
-var intrinsicConstructorSourceSet = new Set(
-  intrinsicConstructorSources.values()
-);
-var ERROR_INTRINSIC_NAMES = [
-  "Error",
-  "EvalError",
-  "RangeError",
-  "ReferenceError",
-  "SyntaxError",
-  "TypeError",
-  "URIError",
-  "AggregateError"
-];
-function isIntrinsicConstructorPrototype(prototype, expectedName) {
-  const constructorDescriptor = Object.getOwnPropertyDescriptor(
-    prototype,
-    "constructor"
-  );
-  const candidateConstructor = constructorDescriptor?.value;
-  if (constructorDescriptor === void 0 || !("value" in constructorDescriptor) || typeof candidateConstructor !== "function") {
-    return false;
-  }
-  let candidateSource;
-  try {
-    candidateSource = functionToString.call(candidateConstructor);
-  } catch {
-    return false;
-  }
-  const expectedSource = expectedName === void 0 ? void 0 : intrinsicConstructorSources.get(expectedName);
-  if (expectedSource !== void 0 && candidateSource !== expectedSource || expectedSource === void 0 && !intrinsicConstructorSourceSet.has(candidateSource)) {
-    return false;
-  }
-  const nameDescriptor = Object.getOwnPropertyDescriptor(
-    candidateConstructor,
-    "name"
-  );
-  const candidateName = nameDescriptor !== void 0 && "value" in nameDescriptor && typeof nameDescriptor.value === "string" ? nameDescriptor.value : void 0;
-  const intrinsicName = expectedName ?? candidateName;
-  const intrinsicSource = intrinsicName === void 0 ? void 0 : intrinsicConstructorSources.get(intrinsicName);
-  return candidateName === intrinsicName && intrinsicSource !== void 0 && candidateSource === intrinsicSource && Object.getOwnPropertyDescriptor(candidateConstructor, "prototype")?.value === prototype;
-}
-__name(isIntrinsicConstructorPrototype, "isIntrinsicConstructorPrototype");
-function hasNativePrototype(value, expectedName) {
-  const visited = /* @__PURE__ */ new WeakSet();
-  let prototype = Object.getPrototypeOf(value);
-  while (prototype !== null && !visited.has(prototype)) {
-    visited.add(prototype);
-    if (isIntrinsicConstructorPrototype(prototype, expectedName)) {
-      return true;
-    }
-    prototype = Object.getPrototypeOf(prototype);
-  }
-  return false;
-}
-__name(hasNativePrototype, "hasNativePrototype");
-function hasBrand(obj, tag) {
-  try {
-    switch (tag) {
-      case "[object Date]":
-        dateGetTime.call(obj);
-        return true;
-      case "[object RegExp]":
-        regExpSourceGet.call(obj);
-        return true;
-      case "[object Map]":
-        mapSizeGet.call(obj);
-        return true;
-      case "[object Set]":
-        setSizeGet.call(obj);
-        return true;
-      case "[object WeakMap]":
-        weakMapHas.call(obj, PROBE_KEY);
-        return true;
-      case "[object WeakSet]":
-        weakSetHas.call(obj, PROBE_KEY);
-        return true;
-      case "[object DataView]":
-        dataViewByteLengthGet.call(obj);
-        return true;
-      case "[object ArrayBuffer]":
-        arrayBufferByteLengthGet.call(obj);
-        return true;
-      case "[object SharedArrayBuffer]":
-        if (!sharedArrayBufferByteLengthGet) return false;
-        sharedArrayBufferByteLengthGet.call(obj);
-        return true;
-      case "[object Boolean]":
-        booleanValueOf.call(obj);
-        return true;
-      case "[object Number]":
-        numberValueOf.call(obj);
-        return true;
-      case "[object String]":
-        stringValueOf.call(obj);
-        return true;
-      case "[object BigInt]":
-        bigIntValueOf.call(obj);
-        return true;
-      case "[object Promise]":
-        return hasNativePrototype(obj, "Promise");
-      case "[object Error]":
-        return ERROR_INTRINSIC_NAMES.some(
-          (name) => hasNativePrototype(obj, name)
-        );
-      default:
-        return false;
-    }
-  } catch {
-    return false;
-  }
-}
-__name(hasBrand, "hasBrand");
-function isBuiltInObject(obj, tag) {
-  if (ArrayBuffer.isView(obj)) return true;
-  if (tag.endsWith("Array]")) return false;
-  return BUILT_IN_TAGS.has(tag) && hasBrand(obj, tag);
-}
-__name(isBuiltInObject, "isBuiltInObject");
-
-// src/utils/array/deep-equal.ts
-var objProto = Object.prototype;
-var objToString = objProto.toString;
-var objHasOwn = objProto.hasOwnProperty;
-function sameValueZero(a, b) {
-  return a === b || Number.isNaN(a) && Number.isNaN(b);
-}
-__name(sameValueZero, "sameValueZero");
-function deepEqual(a, b) {
-  return deepEqualInner(a, b, /* @__PURE__ */ new WeakMap());
-}
-__name(deepEqual, "deepEqual");
-function deepEqualInner(a, b, visited) {
-  if (a === b) return true;
-  const typeA = typeof a;
-  const typeB = typeof b;
-  if (typeA !== "object" || a === null || typeB !== "object" || b === null) {
-    if (typeA === "number" && typeB === "number") {
-      return Number.isNaN(a) && Number.isNaN(b);
-    }
-    return false;
-  }
-  const objA = a;
-  const objB = b;
-  let cachedBs = visited.get(objA);
-  if (cachedBs?.has(objB)) {
-    return true;
-  }
-  if (!cachedBs) {
-    cachedBs = /* @__PURE__ */ new WeakSet();
-    visited.set(objA, cachedBs);
-  }
-  cachedBs.add(objB);
-  if (ArrayBuffer.isView(objA) || ArrayBuffer.isView(objB)) {
-    if (!ArrayBuffer.isView(objA) || !ArrayBuffer.isView(objB)) return false;
-    const tagA2 = objToString.call(objA);
-    const tagB2 = objToString.call(objB);
-    if (tagA2 !== tagB2) return false;
-    if (tagA2 === "[object DataView]") {
-      const viewA = objA;
-      const viewB = objB;
-      if (viewA.byteLength !== viewB.byteLength) return false;
-      const len2 = viewA.byteLength;
-      for (let i = 0; i < len2; i++) {
-        if (viewA.getUint8(i) !== viewB.getUint8(i)) return false;
-      }
-      return true;
-    }
-    const arrA = objA;
-    const arrB = objB;
-    const len = arrA.length;
-    if (len !== arrB.length) return false;
-    for (let i = 0; i < len; i++) {
-      if (!sameValueZero(arrA[i], arrB[i])) return false;
-    }
-    return true;
-  }
-  if (Array.isArray(objA) || Array.isArray(objB)) {
-    if (!Array.isArray(objA) || !Array.isArray(objB)) return false;
-    if (objA.length !== objB.length) return false;
-    const keysA = Reflect.ownKeys(objA).filter((key) => key !== "length");
-    const keysB = Reflect.ownKeys(objB).filter((key) => key !== "length");
-    if (keysA.length !== keysB.length) return false;
-    const arrA = objA;
-    const arrB = objB;
-    for (const key of keysA) {
-      if (!objHasOwn.call(objB, key)) return false;
-      if (!deepEqualInner(arrA[key], arrB[key], visited)) {
-        return false;
-      }
-    }
-    return true;
-  }
-  const tagA = objToString.call(objA);
-  const tagB = objToString.call(objB);
-  if (tagA !== tagB) return false;
-  const builtInA = isBuiltInObject(objA, tagA);
-  const builtInB = isBuiltInObject(objB, tagB);
-  if (builtInA !== builtInB) return false;
-  if (!builtInA) {
-    return comparePlainObjects(objA, objB, visited);
-  }
-  switch (tagA) {
-    case "[object Map]": {
-      const mapA = objA;
-      const mapB = objB;
-      if (mapA.size !== mapB.size) return false;
-      for (const [key, valA] of mapA) {
-        if (!mapB.has(key)) return false;
-        const valB = mapB.get(key);
-        if (!deepEqualInner(valA, valB, visited)) return false;
-      }
-      return true;
-    }
-    case "[object Set]": {
-      const setA = objA;
-      const setB = objB;
-      if (setA.size !== setB.size) return false;
-      for (const value of setA) {
-        if (!setB.has(value)) return false;
-      }
-      return true;
-    }
-    case "[object Date]": {
-      return sameValueZero(objA.getTime(), objB.getTime());
-    }
-    case "[object RegExp]": {
-      const regA = objA;
-      const regB = objB;
-      return regA.source === regB.source && regA.flags === regB.flags;
-    }
-    case "[object Boolean]":
-    case "[object Number]":
-    case "[object String]":
-    case "[object BigInt]": {
-      return sameValueZero(
-        objA.valueOf(),
-        objB.valueOf()
-      );
-    }
-    default: {
-      return objA === objB;
-    }
-  }
-}
-__name(deepEqualInner, "deepEqualInner");
-function comparePlainObjects(objA, objB, visited) {
-  const recA = objA;
-  const recB = objB;
-  const stringKeysA = Object.getOwnPropertyNames(objA);
-  const stringKeysB = Object.getOwnPropertyNames(objB);
-  if (stringKeysA.length !== stringKeysB.length) return false;
-  const symbolKeysA = Object.getOwnPropertySymbols(objA);
-  const symbolKeysB = Object.getOwnPropertySymbols(objB);
-  if (symbolKeysA.length !== symbolKeysB.length) return false;
-  const symbolKeysBSet = new Set(symbolKeysB);
-  for (const key of stringKeysA) {
-    if (!objHasOwn.call(objB, key)) return false;
-  }
-  for (const key of symbolKeysA) {
-    if (!symbolKeysBSet.has(key)) return false;
-  }
-  for (const key of stringKeysA) {
-    if (!deepEqualInner(recA[key], recB[key], visited)) {
-      return false;
-    }
-  }
-  for (const key of symbolKeysA) {
-    if (!deepEqualInner(recA[key], recB[key], visited)) {
-      return false;
-    }
-  }
-  return true;
-}
-__name(comparePlainObjects, "comparePlainObjects");
-
-// src/testing/contract-assertions.ts
+//#region src/testing/contract-assertions.ts
+/**
+* Assertion, error-matching, and suite-runner helpers shared by the
+* repository contract suites (state-stored and event-sourced). Internal
+* to the testing entry: not re-exported from `@shirudo/ddd-kit/testing`.
+*/
+/**
+* Runs one contract-test body against a fresh environment and tears it
+* down in a finally-like discipline with one subtle, load-bearing rule:
+* a teardown failure (dropping a schema on an aborted pool) must never
+* REPLACE the contract-violation diagnostic that is the suite's entire
+* value. It only surfaces when the body itself succeeded.
+*/
 async function runInContractEnvironment(createEnvironment, body) {
-  const env = await createEnvironment();
-  let bodyFailed = false;
-  let bodyError;
-  try {
-    await body(env);
-  } catch (error) {
-    bodyFailed = true;
-    bodyError = error;
-  }
-  try {
-    await env.teardown?.();
-  } catch (teardownError) {
-    if (!bodyFailed) {
-      throw teardownError;
-    }
-  }
-  if (bodyFailed) {
-    throw bodyError;
-  }
+	const env = await createEnvironment();
+	let bodyFailed = false;
+	let bodyError;
+	try {
+		await body(env);
+	} catch (error) {
+		bodyFailed = true;
+		bodyError = error;
+	}
+	try {
+		await env.teardown?.();
+	} catch (teardownError) {
+		if (!bodyFailed) throw teardownError;
+	}
+	if (bodyFailed) throw bodyError;
+}
+/**
+* Binds a harness's environment factory into the per-test wrapper the
+* suites build their entries from: `inEnv(body)` yields a test `run`
+* that creates a fresh environment, runs the body, and tears down via
+* {@link runInContractEnvironment}.
+*/
+function bindContractEnvironment(createEnvironment) {
+	return (body) => () => runInContractEnvironment(createEnvironment, body);
 }
-__name(runInContractEnvironment, "runInContractEnvironment");
+/** Resolves to the rejection reason, or `undefined` when the promise resolved. */
 function captureRejection(promise) {
-  return promise.then(
-    () => void 0,
-    (error) => error
-  );
+	return promise.then(() => void 0, (error) => error);
 }
-__name(captureRejection, "captureRejection");
+/**
+* Load with a contract diagnostic instead of a bare TypeError downstream.
+* `suspectHint` names the suite-specific likely cause (broken hydration
+* vs broken replay read).
+*/
 async function loadAggregateOrFail(repository, id, suspectHint) {
-  const loaded = await repository.getById(id);
-  assert(
-    loaded !== null,
-    `getById(${String(id)}) returned null for an aggregate that must exist: ${suspectHint}`
-  );
-  return loaded;
+	const loaded = await repository.findById(id);
+	assert(loaded !== null && loaded !== void 0, `findById(${String(id)}) returned no aggregate for an identity that must exist: ${suspectHint}`);
+	return loaded;
 }
-__name(loadAggregateOrFail, "loadAggregateOrFail");
+/**
+* A capability-gated test entry whose `run()` rejects loudly, so a naive
+* binding that ignores `skipped` fails instead of green-no-op'ing.
+* Structurally assignable to both suites' test-entry types.
+*/
 function skippedContractTest(name, capability) {
-  return {
-    name,
-    skipped: { capability },
-    run: /* @__PURE__ */ __name(async () => {
-      throw new Error(
-        `Repository contract test skipped: harness capability '${capability}' is not provided. Bind skipped tests with it.skip ((test.skipped ? it.skip : it)(test.name, test.run)) or provide the capability; each one closes a real OCC hole.`
-      );
-    }, "run")
-  };
+	return {
+		name,
+		skipped: { capability },
+		run: async () => {
+			throw new Error(`Contract test skipped: harness capability '${capability}' is not provided. Bind skipped tests with it.skip ((test.skipped ? it.skip : it)(test.name, test.run)) or provide the capability; each skipped capability is an unproven guarantee.`);
+		}
+	};
+}
+/**
+* Capability gate that keeps a test's NAME single-sourced: a harness
+* that satisfies the gate gets the real test, everyone else gets the
+* loud skipped entry under the same name (see
+* {@link skippedContractTest}). Nests for tests behind several gates;
+* the outermost failing gate's capability wins the skip report.
+*/
+function gatedContractTest(gate, test) {
+	return gate.satisfiedBy ? test : skippedContractTest(test.name, gate.capability);
+}
+/**
+* Identities of an in-memory pending batch, with the shared precondition
+* that every event is recorded (minted). The `requirement` names the
+* suite-specific rule the harness violated when an event is unminted.
+*/
+function mintedPendingEventIds(events, requirement) {
+	return events.map((event) => {
+		assert(typeof event === "object" && event !== null && isMintedEvent(event), requirement);
+		return event.eventId;
+	});
+}
+/**
+* Sorted identities of committed outbox envelopes. Shared by both
+* repository suites so the projection cannot drift between them.
+*/
+function sortedCommittedEventIds(committed) {
+	return committed.map(({ event }) => event.eventId).sort();
 }
-__name(skippedContractTest, "skippedContractTest");
 function assert(condition, message) {
-  if (!condition) {
-    throw new Error(`Repository contract violated: ${message}`);
-  }
+	if (!condition) throw new Error(`Contract violated: ${message}`);
 }
-__name(assert, "assert");
 function assertEqual(actual, expected, message) {
-  if (actual !== expected) {
-    throw new Error(
-      `Repository contract violated: ${message} (expected ${String(expected)}, got ${String(actual)})`
-    );
-  }
+	if (actual !== expected) throw new Error(`Contract violated: ${message} (expected ${String(expected)}, got ${String(actual)})`);
 }
-__name(assertEqual, "assertEqual");
+/**
+* Walks the standard `cause` chain (cycle-safe, hostile-getter-safe)
+* looking for an Error that matches the given name. Matching is
+* deliberately by NAME, not `instanceof`: the suite ships in its own
+* bundle entry, and the adapter's errors come from the main entry's
+* copy of the kit (or even a second installed kit version) -
+* cross-copy `instanceof` is always false, name identity is the stable
+* contract. Since v3 the kit's errors are StructuredErrors whose
+* runtime `name` IS their SCREAMING_SNAKE code, minification-stable by
+* construction and inherited by subclasses (a `PgConflictError extends
+* ConcurrencyConflictError` keeps the code as its name). The suites
+* match ONLY the v3 codes. Failure diagnostics render the rejection's
+* cause-chain names ({@link describeError}), so an unexpected error,
+* including one from a different kit copy in the dependency graph, is
+* identifiable from the message without version-specific knowledge in
+* the suite.
+*/
 function chainContainsErrorNamed(error, name) {
-  const seen = /* @__PURE__ */ new Set();
-  let current = error;
-  while (current !== null && current !== void 0 && !seen.has(current)) {
-    if (typeof current !== "object") {
-      return false;
-    }
-    if (errorMatchesName(current, name)) {
-      return true;
-    }
-    seen.add(current);
-    try {
-      current = current.cause;
-    } catch {
-      return false;
-    }
-  }
-  return false;
+	let found = false;
+	walkCauseChain(error, (node) => {
+		found = errorMatchesName(node, name);
+		return found;
+	});
+	return found;
 }
-__name(chainContainsErrorNamed, "chainContainsErrorNamed");
-function chainContainsErrorNamedAnyOf(error, names) {
-  return names.some((name) => chainContainsErrorNamed(error, name));
+/**
+* The one cause-chain walk every chain-inspecting helper in this file
+* is expressed through (cycle-safe, hostile-cause-getter-safe): visits
+* each object node until `visit` asks to stop by returning `true`, the
+* chain ends, repeats, or advancing turns hostile. Single-sourced on
+* purpose: a hardening fix (a depth cap, a new hostile shape) must land
+* in ALL walkers at once, or the suites judge the same adapter
+* rejection inconsistently. Per-node property reads stay the visitor's
+* responsibility; only the `cause` advance is guarded here.
+*/
+function walkCauseChain(error, visit) {
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	while (current !== null && current !== void 0 && typeof current === "object" && !seen.has(current)) {
+		seen.add(current);
+		if (visit(current)) return;
+		try {
+			current = current.cause;
+		} catch {
+			return;
+		}
+	}
+}
+/**
+* Asserts that the cause chain carries a kit error with one of the given
+* codes (since v3, `error.name === error.code`; the codes are the ONLY
+* accepted identity). Failure messages built with {@link describeError}
+* render the rejection's cause-chain names, so an unexpected error, e.g.
+* one from a different `@shirudo/ddd-kit` copy in the dependency graph,
+* is identifiable from the diagnostic without the suite carrying any
+* version-specific knowledge.
+*/
+function assertChainContainsKitError(rejection, codes, message) {
+	if (codes.some((code) => chainContainsErrorNamed(rejection, code))) return;
+	throw new Error(`Contract violated: ${message}`);
+}
+/**
+* Walks the `cause` chain (cycle-safe, hostile-getter-safe) looking for
+* `retryable === true`: the same loose, property-based contract the
+* kit's retry classifier (`someChainRetryable`) applies. Suites assert
+* retryability with this instead of reading the top-level rejection, so
+* an adapter that wraps a kit error in its own error chain, which
+* {@link assertChainContainsKitError} deliberately tolerates, is judged
+* exactly the way a consumer's retry loop will judge it.
+*
+* Deliberately NOT a call to `someChainRetryable` itself: that
+* classifier throws on a circular cause chain (its callers handle
+* that), while a hardened suite must survive whatever error shape an
+* adapter rejects with and answer with a contract diagnostic, never a
+* helper crash. Same hardening discipline as
+* {@link chainContainsErrorNamed}.
+*/
+function chainContainsRetryable(error) {
+	let found = false;
+	walkCauseChain(error, (node) => {
+		try {
+			found = node.retryable === true;
+		} catch {
+			return true;
+		}
+		return found;
+	});
+	return found;
 }
-__name(chainContainsErrorNamedAnyOf, "chainContainsErrorNamedAnyOf");
 function errorMatchesName(candidate, name) {
-  try {
-    if (candidate.name === name) {
-      return true;
-    }
-  } catch {
-  }
-  try {
-    let proto = Object.getPrototypeOf(candidate);
-    for (let depth = 0; proto !== null && depth < 20; depth++) {
-      if (proto.constructor?.name === name) {
-        return true;
-      }
-      proto = Object.getPrototypeOf(proto);
-    }
-  } catch {
-  }
-  return false;
+	try {
+		if (candidate.name === name) return true;
+	} catch {}
+	try {
+		let proto = Object.getPrototypeOf(candidate);
+		for (let depth = 0; proto !== null && depth < 20; depth++) {
+			if (proto.constructor?.name === name) return true;
+			proto = Object.getPrototypeOf(proto);
+		}
+	} catch {}
+	return false;
 }
-__name(errorMatchesName, "errorMatchesName");
 function describeError(error) {
-  if (error instanceof Error) {
-    return `${error.name}: ${error.message}`;
-  }
-  return String(error);
+	if (error instanceof Error) {
+		const chain = causeChainNames(error);
+		const suffix = chain.length > 1 ? ` (cause chain: ${chain.join(" -> ")})` : "";
+		return `${error.name}: ${error.message}${suffix}`;
+	}
+	return String(error);
+}
+/**
+* Names along the `cause` chain (cycle-safe, hostile-getter-safe), for
+* failure diagnostics: a wrapped rejection shows WHAT it wraps, so an
+* unexpected error deep in the chain (a raw driver error, or an error
+* from a different kit copy) is identifiable from the message alone.
+*/
+function causeChainNames(error) {
+	const names = [];
+	walkCauseChain(error, (node) => {
+		try {
+			const { name } = node;
+			names.push(typeof name === "string" ? name : "(unnamed)");
+		} catch {
+			return true;
+		}
+		return false;
+	});
+	return names;
 }
-__name(describeError, "describeError");
 
-// src/testing/es-repository-contract.ts
+//#endregion
+//#region src/testing/command-outbox-contract.ts
+function createCommandOutboxContractTests(harness) {
+	const inEnv = bindContractEnvironment(harness.createEnvironment);
+	const commit = (seed, commandSeeds = [seed]) => ({
+		origin: {
+			eventId: `process-event-${seed}`,
+			source: {
+				aggregateType: "CheckoutProcess",
+				aggregateId: "order-1"
+			},
+			position: {
+				aggregateVersion: seed,
+				commitSequence: 0,
+				commitSize: 1
+			}
+		},
+		messages: commandSeeds.map((commandSeed, index) => message(seed, index, harness.createCommand(commandSeed)))
+	});
+	const tests = [
+		{
+			name: "deduplicates an exact retry by origin event id",
+			run: inEnv(async (env) => {
+				const original = commit(1);
+				await env.addCommitted([original]);
+				await env.addCommitted([original]);
+				const stored = await env.readAll();
+				assertEqual(stored.length, 1, "an exact retry must retain one receipt, not append a duplicate");
+				assert(deepEqual(stored[0], original), "an exact retry must preserve the original receipt and commands");
+			})
+		},
+		{
+			name: "rejects conflicting reuse of an origin event id",
+			run: inEnv(async (env) => {
+				const original = commit(1);
+				await env.addCommitted([original]);
+				const conflict = {
+					...commit(1, [99]),
+					origin: {
+						...commit(1, [99]).origin,
+						eventId: original.origin.eventId
+					}
+				};
+				assert(!deepEqual(conflict.messages, original.messages), "harness contract: createCommand must return distinct content per seed, or the manufactured conflict is an exact retry");
+				assert(await captureRejection(env.addCommitted([conflict])) !== void 0, "a reused origin event id with different messages must reject");
+				const stored = await env.readAll();
+				assertEqual(stored.length, 1, "a conflicting retry must not append another receipt");
+				assert(deepEqual(stored[0], original), "a conflicting retry must not replace the original receipt");
+			})
+		},
+		{
+			name: "rejects an origin event id reused with a different source",
+			run: inEnv(async (env) => {
+				const original = commit(1);
+				await env.addCommitted([original]);
+				const conflicts = [{
+					fact: "aggregateId",
+					candidate: {
+						...original,
+						origin: {
+							...original.origin,
+							source: {
+								...original.origin.source,
+								aggregateId: "order-2"
+							}
+						}
+					}
+				}, {
+					fact: "aggregateType",
+					candidate: {
+						...original,
+						origin: {
+							...original.origin,
+							source: {
+								...original.origin.source,
+								aggregateType: "Order"
+							}
+						}
+					}
+				}];
+				for (const { fact, candidate } of conflicts) {
+					assert(await captureRejection(env.addCommitted([candidate])) !== void 0, `a reused origin event id with a different source.${fact} must reject`);
+					assert(deepEqual(await env.readAll(), [original]), `a source.${fact} conflict must leave the original receipt unchanged`);
+				}
+			})
+		},
+		{
+			name: "rejects an origin event id reused with a different position",
+			run: inEnv(async (env) => {
+				const original = commit(1);
+				await env.addCommitted([original]);
+				for (const { fact, change } of [
+					{
+						fact: "aggregateVersion",
+						change: { aggregateVersion: 2 }
+					},
+					{
+						fact: "commitSequence",
+						change: { commitSequence: 1 }
+					},
+					{
+						fact: "commitSize",
+						change: { commitSize: 2 }
+					}
+				]) {
+					const conflict = {
+						...original,
+						origin: {
+							...original.origin,
+							position: {
+								...original.origin.position,
+								...change
+							}
+						}
+					};
+					assert(await captureRejection(env.addCommitted([conflict])) !== void 0, `a reused origin event id with a different position.${fact} must reject`);
+					assert(deepEqual(await env.readAll(), [original]), `a position.${fact} conflict must leave the original receipt unchanged`);
+				}
+			})
+		},
+		{
+			name: "rejects a conflicting batch atomically",
+			run: inEnv(async (env) => {
+				const original = commit(1);
+				await env.addCommitted([original]);
+				const newCommit = commit(2);
+				const conflictingOriginal = {
+					...commit(1, [77]),
+					origin: {
+						...commit(1, [77]).origin,
+						eventId: original.origin.eventId
+					}
+				};
+				assert(!deepEqual(conflictingOriginal.messages, original.messages), "harness contract: createCommand must return distinct content per seed, or the manufactured conflict is an exact retry");
+				assert(await captureRejection(env.addCommitted([newCommit, conflictingOriginal])) !== void 0, "a batch containing a conflicting origin must reject");
+				const stored = await env.readAll();
+				assertEqual(stored.length, 1, "a rejected batch must not leave its earlier new receipt behind");
+				assert(deepEqual(stored[0], original), "a rejected batch must preserve the pre-existing receipt");
+			})
+		},
+		{
+			name: "retains command and commit input order",
+			run: inEnv(async (env) => {
+				const first = commit(1, [10, 11]);
+				const second = commit(2, [20, 21]);
+				await env.addCommitted([first, second]);
+				const stored = await env.readAll();
+				assert(deepEqual(stored.map(({ origin }) => origin.eventId), [first.origin.eventId, second.origin.eventId]), "commit receipts must retain input order");
+				assert(deepEqual(stored.map(({ messages }) => messages.map(({ command }) => command)), [first.messages.map(({ command }) => command), second.messages.map(({ command }) => command)]), "commands inside each receipt must retain mapper order");
+			})
+		},
+		{
+			name: "retains every position in a multi-event aggregate commit",
+			run: inEnv(async (env) => {
+				const first = commit(10);
+				const second = commit(11);
+				const commitSize = 2;
+				const aggregateVersion = 7;
+				const multiEventCommit = [{
+					...first,
+					origin: {
+						...first.origin,
+						position: {
+							aggregateVersion,
+							commitSequence: 0,
+							commitSize
+						}
+					}
+				}, {
+					...second,
+					origin: {
+						...second.origin,
+						position: {
+							aggregateVersion,
+							commitSequence: 1,
+							commitSize
+						}
+					}
+				}];
+				await env.addCommitted(multiEventCommit);
+				assert(deepEqual(await env.readAll(), multiEventCommit), "a multi-event commit must retain its shared version, sequence, and size for every receipt");
+			})
+		},
+		{
+			name: "retains an empty command receipt and advances the source cursor",
+			run: inEnv(async (env) => {
+				const empty = commit(1, []);
+				const next = commit(2);
+				await env.addCommitted([empty]);
+				await env.addCommitted([next]);
+				const stored = await env.readAll();
+				assertEqual(stored.length, 2, "an empty command batch must retain its source receipt");
+				assertEqual(stored[0]?.messages.length, 0, "the retained empty receipt must contain no invented command");
+				assert(deepEqual(stored.map(({ origin }) => origin.position.aggregateVersion), [1, 2]), "the source cursor must advance through the empty receipt");
+			})
+		}
+	];
+	tests.push(gatedContractTest({
+		capability: "providesRolledBackAdds",
+		satisfiedBy: harness.providesRolledBackAdds === true
+	}, {
+		name: "a rolled-back add leaves no receipt or command behind",
+		run: inEnv(async (env) => {
+			if (!env.addRolledBack) throw new Error("Contract violated: harness declared providesRolledBackAdds but the environment lacks addRolledBack");
+			await env.addRolledBack([commit(1)]);
+			assertEqual((await env.readAll()).length, 0, "a rolled-back transaction must persist no command receipt");
+		})
+	}));
+	return tests;
+}
+function message(commitSeed, index, command) {
+	return {
+		messageId: `process-event-${commitSeed}:command:${index}`,
+		recordedAt: "2027-04-05T06:07:08.000Z",
+		destination: "participant.commands",
+		command,
+		conversationId: "checkout-order-1",
+		causationId: `process-event-${commitSeed}`
+	};
+}
+
+//#endregion
+//#region src/testing/deadline-store-contract.ts
+const at = (iso) => new Date(iso);
+const T0 = "2026-03-01T10:00:00.000Z";
+const T1 = "2026-03-01T10:05:00.000Z";
+const T2 = "2026-03-01T10:10:00.000Z";
+/**
+* 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)`.
+*/
+function createDeadlineStoreContractTests(harness) {
+	const inEnv = bindContractEnvironment(() => harness.createEnvironment());
+	const ceiling = harness.failuresToDeadLetter;
+	if (!Number.isInteger(ceiling) || ceiling < 2) throw new Error("Contract violated: failuresToDeadLetter must be an integer >= 2; observing attempts on a pending deadline needs one that survives a failure");
+	return [
+		{
+			name: "a deadline is invisible before its due time and delivered from it onward",
+			run: inEnv(async (env) => {
+				await env.run(() => env.store.schedule({
+					scope: "checkout-saga",
+					key: "order-1",
+					dueAt: at(T1),
+					payload: { kind: "payment-timeout" }
+				}));
+				assertEqual((await env.store.due(at(T0), 10)).length, 0, "a deadline must not fire early");
+				const dueExactly = await env.store.due(at(T1), 10);
+				assertEqual(dueExactly.length, 1, "a deadline is due AT its due time (dueAt <= now)");
+				const record = dueExactly[0];
+				assert(record !== void 0, "expected the due deadline");
+				assertEqual(record.scope, "checkout-saga", "scope must round-trip");
+				assertEqual(record.key, "order-1", "key must round-trip");
+				assertEqual(record.dueAt.getTime(), at(T1).getTime(), "dueAt must round-trip with millisecond fidelity");
+				assert(deepEqual(record.payload, { kind: "payment-timeout" }), "the payload must round-trip as plain data");
+				assertEqual(record.attempts, 0, "a fresh deadline has no attempts");
+			})
+		},
+		{
+			name: "due returns earliest first and respects the limit",
+			run: inEnv(async (env) => {
+				await env.run(async () => {
+					await env.store.schedule({
+						scope: "s",
+						key: "late",
+						dueAt: at(T2),
+						payload: { kind: "late" }
+					});
+					await env.store.schedule({
+						scope: "s",
+						key: "early",
+						dueAt: at(T0),
+						payload: { kind: "early" }
+					});
+					await env.store.schedule({
+						scope: "s",
+						key: "middle",
+						dueAt: at(T1),
+						payload: { kind: "middle" }
+					});
+				});
+				const firstPage = await env.store.due(at(T2), 2);
+				assert(firstPage.length >= 1 && firstPage.length <= 2, "limit must bound the page: up to limit records, at least one while deadlines are due");
+				assertEqual(firstPage[0]?.key, "early", "the earliest due deadline comes first");
+			})
+		},
+		{
+			name: "markDelivered consumes the deadline and is idempotent on unknown and repeated ids",
+			run: inEnv(async (env) => {
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T0),
+					payload: { kind: "x" }
+				}));
+				const [record] = await env.store.due(at(T1), 10);
+				assert(record !== void 0, "expected a due deadline");
+				await env.store.markDelivered([record.deliveryId]);
+				await env.store.markDelivered([record.deliveryId]);
+				await env.store.markDelivered(["no-such-delivery-id"]);
+				assert(!(await env.store.due(at(T2), 10)).some((d) => d.deliveryId === record.deliveryId), "a delivered deadline must never come back");
+			})
+		},
+		{
+			name: "cancel removes exactly the addressed deadline and tolerates unknown addresses",
+			run: inEnv(async (env) => {
+				await env.run(async () => {
+					await env.store.schedule({
+						scope: "s",
+						key: "keep",
+						dueAt: at(T0),
+						payload: { kind: "keep" }
+					});
+					await env.store.schedule({
+						scope: "s",
+						key: "drop",
+						dueAt: at(T0),
+						payload: { kind: "drop" }
+					});
+					await env.store.cancel("s", "drop");
+					await env.store.cancel("s", "never-scheduled");
+				});
+				assert(deepEqual((await env.store.due(at(T1), 10)).map((d) => d.key), ["keep"]), "cancel must remove the addressed deadline and nothing else");
+			})
+		},
+		{
+			name: "addresses are isolated per scope",
+			run: inEnv(async (env) => {
+				await env.run(async () => {
+					await env.store.schedule({
+						scope: "reservation-hold",
+						key: "id-1",
+						dueAt: at(T0),
+						payload: { kind: "hold" }
+					});
+					await env.store.schedule({
+						scope: "checkout-saga",
+						key: "id-1",
+						dueAt: at(T0),
+						payload: { kind: "timeout" }
+					});
+					await env.store.cancel("reservation-hold", "id-1");
+				});
+				const due = await env.store.due(at(T1), 10);
+				assert(due.length === 1 && due[0]?.scope === "checkout-saga", "the same key under another scope is a different deadline");
+			})
+		},
+		gatedContractTest({
+			capability: "non-claiming due",
+			satisfiedBy: !harness.claimsOnDue
+		}, {
+			name: "schedule on an occupied address replaces it, and a stale ack cannot consume the successor",
+			run: inEnv(async (env) => {
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T0),
+					payload: {
+						kind: "first",
+						step: 1
+					}
+				}));
+				const [first] = await env.store.due(at(T1), 10);
+				assert(first !== void 0, "expected the first incarnation");
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T1),
+					payload: {
+						kind: "second",
+						step: 2
+					}
+				}));
+				await env.store.markDelivered([first.deliveryId]);
+				const due = await env.store.due(at(T2), 10);
+				assertEqual(due.length, 1, "exactly one pending deadline exists per address");
+				const successor = due[0];
+				assert(successor !== void 0, "expected the successor");
+				assert(deepEqual(successor.payload, {
+					kind: "second",
+					step: 2
+				}), "the successor carries the rescheduled payload");
+				assert(successor.deliveryId !== first.deliveryId, "a reschedule is a fresh incarnation with a fresh deliveryId");
+			})
+		}),
+		{
+			name: "after delivery the address is free again for a fresh schedule",
+			run: inEnv(async (env) => {
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T0),
+					payload: { kind: "first" }
+				}));
+				const [first] = await env.store.due(at(T1), 10);
+				assert(first !== void 0, "expected a due deadline");
+				await env.store.markDelivered([first.deliveryId]);
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T1),
+					payload: { kind: "again" }
+				}));
+				const due = await env.store.due(at(T2), 10);
+				assert(due.length === 1 && deepEqual(due[0]?.payload, { kind: "again" }), "a consumed address must accept a new deadline");
+			})
+		},
+		{
+			name: "the attempt ceiling dead-letters the deadline, visible in deadLetters with its attempt count",
+			run: inEnv(async (env) => {
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "poison",
+					dueAt: at(T0),
+					payload: { kind: "poison" }
+				}));
+				const [poison] = await env.store.due(at(T1), 1);
+				assert(poison !== void 0, "expected the due deadline");
+				let transition;
+				for (let i = 0; i < ceiling; i++) {
+					const current = await env.store.markFailed(poison.deliveryId, /* @__PURE__ */ new Error("boom"));
+					if (i < ceiling - 1) assertEqual(current, void 0, "markFailed must not report a dead-letter transition below the ceiling");
+					transition = current;
+				}
+				assertEqual(transition?.deliveryId, poison.deliveryId, "the ceiling-crossing markFailed call must return the exact dead-letter transition");
+				assertEqual(transition?.attempts, ceiling, "the returned transition must carry the final attempt count");
+				assertEqual(await env.store.markFailed(poison.deliveryId, /* @__PURE__ */ new Error("late")), void 0, "a late failure report must not repeat the dead-letter transition");
+				assert(!(await env.store.due(at(T2), 10)).some((d) => d.deliveryId === poison.deliveryId), "a dead-lettered deadline must stop coming back");
+				const dead = await env.store.deadLetters();
+				assert(dead.length === 1 && dead[0]?.attempts === ceiling, "the dead-lettered deadline must appear in deadLetters() with its attempt count");
+			})
+		},
+		gatedContractTest({
+			capability: "non-claiming due",
+			satisfiedBy: !harness.claimsOnDue
+		}, {
+			name: "attempts surface on redelivery, and a poison deadline does not block its neighbors",
+			run: inEnv(async (env) => {
+				await env.run(async () => {
+					await env.store.schedule({
+						scope: "s",
+						key: "poison",
+						dueAt: at(T0),
+						payload: { kind: "poison" }
+					});
+					await env.store.schedule({
+						scope: "s",
+						key: "healthy",
+						dueAt: at(T0),
+						payload: { kind: "healthy" }
+					});
+				});
+				const [poison] = await env.store.due(at(T1), 1);
+				assert(poison !== void 0, "expected the earliest due deadline");
+				await env.store.markFailed(poison.deliveryId, /* @__PURE__ */ new Error("boom"));
+				assertEqual((await env.store.due(at(T1), 10)).find((d) => d.deliveryId === poison.deliveryId)?.attempts, 1, "attempts must be surfaced on the record after markFailed");
+				for (let i = 1; i < ceiling; i++) await env.store.markFailed(poison.deliveryId, /* @__PURE__ */ new Error("boom"));
+				assert((await env.store.due(at(T1), 10)).some((d) => d.key === "healthy"), "deadlines carry no cross-address ordering; a dead-lettered neighbor must not block delivery");
+			})
+		}),
+		{
+			name: "two dead-lettered incarnations of one address are both kept and individually clearable",
+			run: inEnv(async (env) => {
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T0),
+					payload: { kind: "first" }
+				}));
+				const [first] = await env.store.due(at(T1), 10);
+				assert(first !== void 0, "expected the first incarnation");
+				for (let i = 0; i < ceiling; i++) await env.store.markFailed(first.deliveryId, /* @__PURE__ */ new Error("boom"));
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T1),
+					payload: { kind: "second" }
+				}));
+				const [second] = await env.store.due(at(T2), 10);
+				assert(second !== void 0, "expected the second incarnation");
+				for (let i = 0; i < ceiling; i++) await env.store.markFailed(second.deliveryId, /* @__PURE__ */ new Error("boom"));
+				const dead = await env.store.deadLetters();
+				assert(dead.length === 2 && dead.some((d) => d.deliveryId === first.deliveryId) && dead.some((d) => d.deliveryId === second.deliveryId), "dead letters are kept per incarnation; a later dead letter of the same address must not overwrite an earlier un-acked one");
+				await env.store.markDelivered([first.deliveryId]);
+				const remaining = await env.store.deadLetters();
+				assert(remaining.length === 1 && remaining[0]?.deliveryId === second.deliveryId, "acknowledging one dead-lettered incarnation must not clear its sibling");
+			})
+		},
+		{
+			name: "late failure reports never resurrect or advance anything, and acking a dead letter clears it",
+			run: inEnv(async (env) => {
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T0),
+					payload: { kind: "x" }
+				}));
+				const [record] = await env.store.due(at(T1), 10);
+				assert(record !== void 0, "expected a due deadline");
+				for (let i = 0; i < ceiling; i++) await env.store.markFailed(record.deliveryId, /* @__PURE__ */ new Error("boom"));
+				await env.store.markFailed(record.deliveryId, /* @__PURE__ */ new Error("late"));
+				await env.store.markFailed("no-such-id", /* @__PURE__ */ new Error("unknown"));
+				assertEqual((await env.store.deadLetters()).length, 1, "late or unknown failure reports must not change the dead-letter set");
+				await env.store.markDelivered([record.deliveryId]);
+				assertEqual((await env.store.deadLetters()).length, 0, "acking a dead-lettered deadline must clear it");
+			})
+		},
+		gatedContractTest({
+			capability: "providesRolledBackRuns",
+			satisfiedBy: harness.providesRolledBackRuns === true
+		}, {
+			name: "a rolled-back schedule leaves no deadline behind",
+			run: inEnv(async (env) => {
+				if (!env.runRolledBack) throw new Error("Contract violated: harness declared providesRolledBackRuns but the environment lacks runRolledBack");
+				await env.runRolledBack(() => env.store.schedule({
+					scope: "s",
+					key: "ghost",
+					dueAt: at(T0),
+					payload: { kind: "ghost" }
+				})).catch(() => {});
+				assertEqual((await env.store.due(at(T2), 10)).length, 0, "a deadline from a rolled-back transaction is a ghost input and must not exist");
+			})
+		}),
+		gatedContractTest({
+			capability: "providesRolledBackRuns",
+			satisfiedBy: harness.providesRolledBackRuns === true
+		}, {
+			name: "a rolled-back cancel leaves the deadline in place",
+			run: inEnv(async (env) => {
+				if (!env.runRolledBack) throw new Error("Contract violated: harness declared providesRolledBackRuns but the environment lacks runRolledBack");
+				await env.run(() => env.store.schedule({
+					scope: "s",
+					key: "k",
+					dueAt: at(T0),
+					payload: { kind: "x" }
+				}));
+				await env.runRolledBack(() => env.store.cancel("s", "k")).catch(() => {});
+				assertEqual((await env.store.due(at(T1), 10)).length, 1, "a cancel from a rolled-back transaction must not have removed the deadline");
+			})
+		})
+	];
+}
+
+//#endregion
+//#region src/testing/es-repository-contract.ts
+/**
+* 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.
+*/
 function createEsRepositoryContractTests(harness) {
-  const withEnvironment = /* @__PURE__ */ __name((body) => runInContractEnvironment(() => harness.createEnvironment(), body), "withEnvironment");
-  const loadOrFail = /* @__PURE__ */ __name((repository, id) => loadAggregateOrFail(
-    repository,
-    id,
-    "broken replay read or a write that did not commit"
-  ), "loadOrFail");
-  async function seed(env) {
-    const aggregate = harness.createAggregate();
-    await env.run(async ({ repository }) => {
-      await repository.save(aggregate);
-    });
-    return aggregate;
-  }
-  __name(seed, "seed");
-  async function reload(env, id) {
-    return env.run(({ repository }) => loadOrFail(repository, id));
-  }
-  __name(reload, "reload");
-  const orderedIds = /* @__PURE__ */ __name((events) => events.map((event) => event.eventId), "orderedIds");
-  const sortedIds = /* @__PURE__ */ __name((events) => orderedIds(events).sort(), "sortedIds");
-  const snapshotState = harness.snapshotState;
-  const createAggregateWithId = harness.createAggregateWithId;
-  const skippedTest = /* @__PURE__ */ __name((name, capability) => skippedContractTest(name, capability), "skippedTest");
-  const tests = [
-    {
-      name: "MANDATORY two-writer conflict: the stale writer's append throws ConcurrencyConflictError and the stream is untouched",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const seedStream = await env.committedStreamEvents(seeded.id);
-        assert(
-          seedStream.length > 0,
-          "seeding must have appended the creation event to the stream"
-        );
-        const staleB = await reload(env, seeded.id);
-        const committedA = await env.run(async ({ repository }) => {
-          const a = await loadOrFail(repository, seeded.id);
-          harness.mutate(a);
-          await repository.save(a);
-          return a;
-        });
-        const streamAfterA = await env.committedStreamEvents(seeded.id);
-        assert(
-          streamAfterA.length === seedStream.length + 1,
-          "writer A's event must reach the stream on commit"
-        );
-        harness.mutate(staleB);
-        harness.mutate(staleB);
-        const rejection = await captureRejection(
-          env.run(async ({ repository }) => {
-            await repository.save(staleB);
-          })
-        );
-        assert(
-          rejection !== void 0,
-          "the second writer's commit must reject; it appended on a stale expectedVersion instead (append guard missing?)"
-        );
-        assert(
-          chainContainsErrorNamed(rejection, "ConcurrencyConflictError"),
-          `the second writer's rejection must be (or wrap, via the cause chain) ConcurrencyConflictError; got: ${describeError(rejection)}`
-        );
-        const finalStream = await env.committedStreamEvents(seeded.id);
-        assert(
-          deepEqual(orderedIds(finalStream), orderedIds(streamAfterA)),
-          "the stream must contain exactly the winning writer's events in order: a rejected append must leave the stream untouched"
-        );
-        const final = await reload(env, seeded.id);
-        assertEqual(
-          final.version,
-          committedA.version,
-          "the reloaded version must equal writer A's committed version (version IS the event count)"
-        );
-        if (snapshotState) {
-          assert(
-            deepEqual(
-              snapshotState.call(harness, final),
-              snapshotState.call(harness, committedA)
-            ),
-            "the reloaded state must fold to writer A's state. Suspects: a partial append survived the rejection, or your snapshotState projection is not roundtrip-stable"
-          );
-        }
-        const outbox = await env.committedOutboxEvents();
-        assert(
-          deepEqual(sortedIds(outbox), sortedIds(streamAfterA)),
-          "the outbox must contain exactly the committed events (compared by eventId); nothing from the stale writer"
-        );
-      }), "run")
-    },
-    {
-      name: "replay equality: a reloaded aggregate folds the committed stream in emission order",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const aggregate = harness.createAggregate();
-        harness.mutate(aggregate);
-        harness.mutate(aggregate);
-        const emittedIds = orderedIds(aggregate.pendingEvents);
-        assertEqual(
-          emittedIds.length,
-          3,
-          "harness contract: createAggregate applies ONE creation event and mutate applies ONE event each"
-        );
-        await env.run(async ({ repository }) => {
-          await repository.save(aggregate);
-        });
-        const stream = await env.committedStreamEvents(aggregate.id);
-        assert(
-          deepEqual(orderedIds(stream), emittedIds),
-          "the committed stream must contain exactly the emitted events in emission order; reordering breaks every consumer's fold"
-        );
-        assertEqual(
-          aggregate.pendingEvents.length,
-          0,
-          "pending events must be cleared after a successful commit (markPersisted ran)"
-        );
-        assertEqual(
-          aggregate.persistedVersion,
-          aggregate.version,
-          "after a successful commit, persistedVersion must equal version"
-        );
-        const reloaded = await reload(env, aggregate.id);
-        assertEqual(
-          reloaded.version,
-          aggregate.version,
-          "the reloaded version must equal the event count"
-        );
-        assertEqual(
-          reloaded.persistedVersion,
-          reloaded.version,
-          "a reloaded aggregate's persistedVersion must equal its version"
-        );
-        assertEqual(
-          reloaded.pendingEvents.length,
-          0,
-          "a reloaded aggregate must not carry pending events (replay is not re-recording)"
-        );
-        if (snapshotState) {
-          assert(
-            deepEqual(
-              snapshotState.call(harness, reloaded),
-              snapshotState.call(harness, aggregate)
-            ),
-            "the reloaded aggregate must fold to the same state as the in-memory instance. Suspects: fold order (readStream must return emission order), or a snapshotState projection that is not roundtrip-stable"
-          );
-        }
-      }), "run")
-    },
-    {
-      name: "getById returns null for a stream that does not exist",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const never = harness.createAggregate();
-        const probe = await env.run(
-          ({ repository }) => repository.getById(never.id)
-        );
-        assert(
-          probe === null,
-          "getById of a never-persisted id must return null (empty stream = no aggregate)"
-        );
-      }), "run")
-    },
-    {
-      name: "identity map: two getById calls in one unit of work return the same instance",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        await env.run(async ({ repository }) => {
-          const first = await repository.getById(seeded.id);
-          const second = await repository.getById(seeded.id);
-          assert(
-            first !== null && first === second,
-            "repeated loads within one unit of work must return the SAME instance (identity map); distinct instances double-harvest events"
-          );
-        });
-      }), "run")
-    },
-    {
-      name: "rollback persists nothing: stream and outbox untouched, pending events survive, first save can be retried",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const aggregate = harness.createAggregate();
-        harness.mutate(aggregate);
-        const pendingBefore = aggregate.pendingEvents.length;
-        await captureRejection(
-          env.run(async ({ repository }) => {
-            await repository.save(aggregate);
-            throw new Error("contract rollback probe");
-          })
-        );
-        assertEqual(
-          (await env.committedStreamEvents(aggregate.id)).length,
-          0,
-          "a rolled-back transaction must not leave events in the stream"
-        );
-        assertEqual(
-          (await env.committedOutboxEvents()).length,
-          0,
-          "a rolled-back transaction must not leave events in the outbox"
-        );
-        assertEqual(
-          aggregate.pendingEvents.length,
-          pendingBefore,
-          "pending events must survive a rollback (so the first save can be retried)"
-        );
-        assert(
-          aggregate.persistedVersion === void 0,
-          "a rolled-back first save must leave persistedVersion undefined (the stream does not exist)"
-        );
-        await env.run(async ({ repository }) => {
-          await repository.save(aggregate);
-        });
-        assertEqual(
-          (await env.committedStreamEvents(aggregate.id)).length,
-          pendingBefore,
-          "the retried first save must append the full pending history"
-        );
-        assertEqual(
-          aggregate.persistedVersion,
-          aggregate.version,
-          "after the successful retry, persistedVersion must equal version"
-        );
-      }), "run")
-    },
-    {
-      name: "readStream honors fromVersion: the snapshot catch-up read returns exactly the events after the position",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const aggregate = harness.createAggregate();
-        harness.mutate(aggregate);
-        harness.mutate(aggregate);
-        await env.run(async ({ repository }) => {
-          await repository.save(aggregate);
-        });
-        const full = await env.committedStreamEvents(aggregate.id);
-        assertEqual(full.length, 3, "seeding must have committed 3 events");
-        const afterOne = await env.committedStreamEvents(aggregate.id, 1);
-        assert(
-          deepEqual(orderedIds(afterOne), orderedIds(full.slice(1))),
-          "fromVersion=1 must return exactly the events after stream position 1, in order; restoreFromSnapshotWithEvents replays exactly this window"
-        );
-        const afterAll = await env.committedStreamEvents(
-          aggregate.id,
-          full.length
-        );
-        assertEqual(
-          afterAll.length,
-          0,
-          "fromVersion at the stream head must return no events"
-        );
-      }), "run")
-    }
-  ];
-  tests.push(
-    createAggregateWithId ? {
-      name: "duplicate create: two creators racing on one stream; the second append conflicts and the stream is untouched",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const seedStream = await env.committedStreamEvents(seeded.id);
-        const duplicate = createAggregateWithId.call(
-          harness,
-          seeded.id
-        );
-        const rejection = await captureRejection(
-          env.run(async ({ repository }) => {
-            await repository.save(duplicate);
-          })
-        );
-        assert(
-          chainContainsErrorNamedAnyOf(rejection, [
-            "ConcurrencyConflictError",
-            "DuplicateAggregateError"
-          ]),
-          `the duplicate creator's append (expectedVersion 0 on an existing stream) must reject with (or wrap) ConcurrencyConflictError or DuplicateAggregateError; got: ${describeError(rejection)}`
-        );
-        const finalStream = await env.committedStreamEvents(seeded.id);
-        assert(
-          deepEqual(orderedIds(finalStream), orderedIds(seedStream)),
-          "the existing stream must be untouched by the rejected duplicate create"
-        );
-      }), "run")
-    } : skippedTest(
-      "duplicate create: two creators racing on one stream; the second append conflicts and the stream is untouched",
-      "createAggregateWithId"
-    )
-  );
-  return tests;
+	const inEnvironment = bindContractEnvironment(() => harness.createEnvironment());
+	const readAll = { limit: 100 };
+	const createAggregateWithId = harness.createAggregateWithId;
+	const snapshotState = harness.snapshotState;
+	const load = (repository, id) => loadAggregateOrFail(repository, id, "the stream was not appended or replayed correctly");
+	const streamFor = (id) => harness.streamKeyFor(id);
+	const recordedIds = (events) => mintedPendingEventIds(events, "pending events must be recorded before flush");
+	const ids = (events) => events.map((event) => {
+		assert(typeof event.eventId === "string" && event.eventId.length > 0, "committed events must carry their persisted eventId");
+		return event.eventId;
+	});
+	const outboxIds = (events) => sortedCommittedEventIds(events);
+	async function seed(environment) {
+		const aggregate = harness.createAggregate();
+		await environment.run(async ({ repository }) => {
+			repository.add(aggregate);
+		});
+		return aggregate;
+	}
+	const tests = [
+		{
+			name: "add appends the exact creation batch to stream and outbox",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				const expectedIds = recordedIds(aggregate.pendingEvents);
+				assertEqual(expectedIds.length, 1, "createAggregate must record exactly one creation event");
+				await environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+				});
+				const stream = await environment.committedStreamEvents(streamFor(aggregate.id), readAll);
+				assert(stream.exists && deepEqual(ids(stream.events), expectedIds), "the stream must contain exactly the registered creation batch");
+				assert(deepEqual(outboxIds(await environment.committedOutboxEvents()), [...expectedIds].sort()), "the outbox must contain the same exact creation batch");
+				assertEqual(aggregate.pendingEvents.length, 0, "successful commit must acknowledge the creation batch");
+			})
+		},
+		{
+			name: "MANDATORY stale append: writer B conflicts after writer A commits and appends no prefix",
+			run: inEnvironment(async (environment) => {
+				const seeded = await seed(environment);
+				let loaded;
+				const bLoaded = new Promise((resolve) => {
+					loaded = resolve;
+				});
+				let release;
+				const mayAppend = new Promise((resolve) => {
+					release = resolve;
+				});
+				const writerB = environment.run(async ({ repository }) => {
+					const stale = await load(repository, seeded.id);
+					loaded();
+					await mayAppend;
+					harness.mutate(stale);
+					harness.mutate(stale);
+					repository.update(stale);
+				});
+				await bLoaded;
+				const winner = await environment.run(async ({ repository }) => {
+					const current = await load(repository, seeded.id);
+					harness.mutate(current);
+					repository.update(current);
+					return current;
+				});
+				const streamAfterWinner = await environment.committedStreamEvents(streamFor(seeded.id), readAll);
+				release();
+				const rejection = await captureRejection(writerB);
+				assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale append must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
+				const finalStream = await environment.committedStreamEvents(streamFor(seeded.id), readAll);
+				assert(finalStream.exists && deepEqual(ids(finalStream.events), ids(streamAfterWinner.events)), "a rejected multi-event append must leave no prefix in the stream");
+				const reloaded = await environment.run(({ repository }) => load(repository, seeded.id));
+				assertEqual(reloaded.version, winner.version, "replay must end at the winning stream version");
+				if (snapshotState) assert(deepEqual(snapshotState.call(harness, reloaded), snapshotState.call(harness, winner)), "replay must fold to writer A's state");
+			})
+		},
+		{
+			name: "replay preserves emission order and returns no pending events",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				harness.mutate(aggregate);
+				harness.mutate(aggregate);
+				const expectedIds = recordedIds(aggregate.pendingEvents);
+				await environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+				});
+				const reloaded = await environment.run(({ repository }) => load(repository, aggregate.id));
+				assertEqual(reloaded.version, expectedIds.length, "event-sourced version must equal the folded event count");
+				assertEqual(reloaded.pendingEvents.length, 0, "replay must not re-record historical events");
+				if (snapshotState) assert(deepEqual(snapshotState.call(harness, reloaded), snapshotState.call(harness, aggregate)), "replay must fold to the same state in emission order");
+				const stream = await environment.committedStreamEvents(streamFor(aggregate.id), readAll);
+				assert(stream.exists && deepEqual(ids(stream.events), expectedIds), "the committed stream must preserve emission order");
+			})
+		},
+		{
+			name: "rollback leaves stream and outbox absent and acknowledges nothing",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				harness.mutate(aggregate);
+				const pending = [...aggregate.pendingEvents];
+				await captureRejection(environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+					throw new Error("rollback probe");
+				}));
+				assert(!(await environment.committedStreamEvents(streamFor(aggregate.id), readAll)).exists, "rollback must leave the stream absent");
+				assertEqual((await environment.committedOutboxEvents()).length, 0, "rollback must leave the outbox empty");
+				assert(deepEqual(aggregate.pendingEvents, pending), "rollback must retain the exact pending batch");
+			})
+		},
+		{
+			name: "retrying the same never-persisted instance after rollback creates the full stream",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				harness.mutate(aggregate);
+				const expectedIds = recordedIds(aggregate.pendingEvents);
+				await captureRejection(environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+					throw new Error("rollback probe");
+				}));
+				await environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+				});
+				const stream = await environment.committedStreamEvents(streamFor(aggregate.id), readAll);
+				assert(stream.exists && deepEqual(ids(stream.events), expectedIds), "the retried add must create the stream with the full pending history");
+				assertEqual(aggregate.pendingEvents.length, 0, "the successful retry must acknowledge the whole batch");
+			})
+		},
+		{
+			name: "outbox failure rolls the already-appended stream batch back",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				const pending = [...aggregate.pendingEvents];
+				environment.failNextOutboxWrite(/* @__PURE__ */ new Error("outbox failure probe"));
+				assert(await captureRejection(environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+				})) !== void 0, "the outbox failure must reject");
+				assert(!(await environment.committedStreamEvents(streamFor(aggregate.id), readAll)).exists, "stream append must roll back with the outbox");
+				assertEqual((await environment.committedOutboxEvents()).length, 0, "failed outbox write must commit no envelope");
+				assert(deepEqual(aggregate.pendingEvents, pending), "failed commit must acknowledge none of the event batch");
+			})
+		},
+		{
+			name: "read windows preserve absence, actual head, and point-in-time bounds",
+			run: inEnvironment(async (environment) => {
+				const missingAggregate = harness.createAggregate();
+				const missing = await environment.committedStreamEvents(streamFor(missingAggregate.id), readAll);
+				assert(!missing.exists && missing.lastVersion === 0, "a missing stream must report exists=false and head 0");
+				const aggregate = harness.createAggregate();
+				harness.mutate(aggregate);
+				harness.mutate(aggregate);
+				await environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+				});
+				const afterOne = await environment.committedStreamEvents(streamFor(aggregate.id), {
+					limit: 100,
+					fromVersion: 1
+				});
+				const asOfTwo = await environment.committedStreamEvents(streamFor(aggregate.id), {
+					limit: 100,
+					toVersion: 2
+				});
+				assert(afterOne.exists && afterOne.lastVersion === 3 && afterOne.events.length === 2, "fromVersion is exclusive and preserves the actual stream head");
+				assert(asOfTwo.exists && asOfTwo.lastVersion === 3 && asOfTwo.events.length === 2, "toVersion is inclusive and preserves the actual stream head");
+			})
+		},
+		{
+			name: "identity map returns one replayed instance per Unit of Work",
+			run: inEnvironment(async (environment) => {
+				const seeded = await seed(environment);
+				await environment.run(async ({ repository }) => {
+					const first = await repository.findById(seeded.id);
+					const second = await repository.findById(seeded.id);
+					assert(first !== void 0 && first === second, "repeated stream loads must return the same tracked instance");
+				});
+			})
+		}
+	];
+	tests.push(gatedContractTest({
+		capability: "createAggregateWithId",
+		satisfiedBy: Boolean(createAggregateWithId)
+	}, {
+		name: "duplicate add conflicts and leaves the existing stream untouched",
+		run: inEnvironment(async (environment) => {
+			assert(createAggregateWithId !== void 0, "capability gate");
+			const seeded = await seed(environment);
+			const before = await environment.committedStreamEvents(streamFor(seeded.id), readAll);
+			const duplicate = createAggregateWithId.call(harness, seeded.id);
+			const rejection = await captureRejection(environment.run(async ({ repository }) => {
+				repository.add(duplicate);
+			}));
+			assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT", "DUPLICATE_AGGREGATE"], `duplicate stream creation must reject with a mapped kit error; got ${describeError(rejection)}`);
+			const after = await environment.committedStreamEvents(streamFor(seeded.id), readAll);
+			assert(deepEqual(ids(after.events), ids(before.events)), "duplicate add must not modify the existing stream");
+		})
+	}));
+	return tests;
+}
+
+//#endregion
+//#region src/testing/event-store-contract.ts
+/**
+* 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.
+*/
+function createEventStoreContractTests(harness) {
+	const inEnv = bindContractEnvironment(() => harness.createEnvironment());
+	const fixtureRead = { limit: 100 };
+	const hasSameEventIds = (actual, expected) => actual.length === expected.length && actual.every((event, index) => event.eventId === expected[index]?.eventId);
+	return [
+		{
+			name: "unknown stream: read reports explicit absence at version zero",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const missing = await store.readStream({ ...firstKey }, fixtureRead);
+				assert(!missing.exists && missing.lastVersion === 0 && missing.events.length === 0, "an unknown qualified stream must return the explicit missing state");
+			})
+		},
+		{
+			name: "empty append: no version check and no stream creation",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				await store.append(firstKey, [], { expectedVersion: 999 });
+				const event = harness.createEvent(firstKey, 1);
+				await store.append({ ...firstKey }, [event], { expectedVersion: 0 });
+				const stored = await store.readStream(firstKey, fixtureRead);
+				assert(stored.exists && stored.lastVersion === 1 && stored.events.length === 1 && stored.events[0]?.eventId === event.eventId, "an empty append must not check OCC or create an empty stream");
+			})
+		},
+		{
+			name: "qualified stream key: equal aggregate ids remain isolated by aggregate type",
+			run: inEnv(async ({ store }) => {
+				const [firstKey, secondKey] = harness.createCollidingStreamKeys();
+				assert(firstKey.aggregateId === secondKey.aggregateId, "createCollidingStreamKeys must return equal raw aggregate ids");
+				assert(firstKey.aggregateType !== secondKey.aggregateType, "createCollidingStreamKeys must return different aggregate types");
+				const firstEvent = harness.createEvent(firstKey, 1);
+				const secondEvent = harness.createEvent(secondKey, 2);
+				assert(firstEvent.eventId !== secondEvent.eventId, "createEvent must produce different event ids for different sequence values");
+				await store.append(firstKey, [firstEvent], { expectedVersion: 0 });
+				await store.append(secondKey, [secondEvent], { expectedVersion: 0 });
+				const firstStream = await store.readStream({ ...firstKey }, fixtureRead);
+				const secondStream = await store.readStream({ ...secondKey }, fixtureRead);
+				assert(firstStream.exists && firstStream.events.length === 1 && firstStream.events[0]?.eventId === firstEvent.eventId, "the first aggregate type must retain only its own event; key objects are value addresses, not identity tokens");
+				assert(secondStream.exists && secondStream.events.length === 1 && secondStream.events[0]?.eventId === secondEvent.eventId, "the second aggregate type must retain only its own event when the raw id collides");
+			})
+		},
+		{
+			name: "append/read: event order and fromVersion slicing are preserved",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const events = [
+					1,
+					2,
+					3
+				].map((sequence) => harness.createEvent(firstKey, sequence));
+				await store.append(firstKey, events, { expectedVersion: 0 });
+				const whole = await store.readStream({ ...firstKey }, fixtureRead);
+				const afterTwo = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					fromVersion: 2
+				});
+				assert(whole.exists && whole.lastVersion === 3 && hasSameEventIds(whole.events, events), "reads must preserve append order");
+				assert(afterTwo.exists && afterTwo.lastVersion === 3 && afterTwo.events.length === 1 && afterTwo.events[0]?.eventId === events[2]?.eventId, "fromVersion 2 must return exactly the events after the first two positions");
+			})
+		},
+		{
+			name: "paged read: limit bounds every page and fromVersion continues without gaps or duplicates",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const events = [
+					1,
+					2,
+					3,
+					4,
+					5
+				].map((sequence) => harness.createEvent(firstKey, sequence));
+				await store.append(firstKey, events, { expectedVersion: 0 });
+				const collected = [];
+				let cursor = 0;
+				let targetHead;
+				for (let attempt = 0; attempt < events.length; attempt += 1) {
+					const page = await store.readStream({ ...firstKey }, {
+						fromVersion: cursor,
+						limit: 2,
+						...targetHead === void 0 ? {} : { toVersion: targetHead }
+					});
+					assert(page.exists, "a paged read of an existing stream must retain existence");
+					targetHead ??= page.lastVersion;
+					assert(page.lastVersion >= targetHead, "lastVersion must keep reporting at least the head pinned by the first page");
+					assert(page.events.length > 0 && page.events.length <= 2, "an unread page must make progress without exceeding the requested limit");
+					collected.push(...page.events);
+					cursor += page.events.length;
+					if (cursor >= targetHead) break;
+				}
+				assert(targetHead === events.length && cursor === targetHead, "following fromVersion by each actual page length must reach the pinned head");
+				assert(hasSameEventIds(collected, events), "paged continuation must reproduce append order without gaps or duplicates");
+				const atEnd = await store.readStream({ ...firstKey }, {
+					fromVersion: cursor,
+					toVersion: targetHead,
+					limit: 2
+				});
+				assert(atEnd.exists && atEnd.events.length === 0, "continuing at the pinned head must return an existing empty page");
+			})
+		},
+		{
+			name: "read options: invalid limits and stream positions fail loudly",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const invalidOptions = [
+					{},
+					{ limit: 0 },
+					{ limit: 1.5 },
+					{ limit: Number.MAX_SAFE_INTEGER + 1 },
+					{
+						limit: 1,
+						fromVersion: -1
+					},
+					{
+						limit: 1,
+						fromVersion: 1.5
+					},
+					{
+						limit: 1,
+						fromVersion: Number.MAX_SAFE_INTEGER + 1
+					},
+					{
+						limit: 1,
+						toVersion: -1
+					},
+					{
+						limit: 1,
+						toVersion: 1.5
+					},
+					{
+						limit: 1,
+						toVersion: Number.MAX_SAFE_INTEGER + 1
+					}
+				];
+				for (const options of invalidOptions) assert(await captureRejection(store.readStream(firstKey, options)) instanceof RangeError, "invalid read bounds must reject with RangeError before querying the stream");
+			})
+		},
+		{
+			name: "bounded read: toVersion is inclusive while lastVersion remains the actual head",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const events = [
+					1,
+					2,
+					3,
+					4
+				].map((sequence) => harness.createEvent(firstKey, sequence));
+				await store.append(firstKey, events, { expectedVersion: 0 });
+				const bounded = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					fromVersion: 1,
+					toVersion: 3
+				});
+				assert(bounded.exists && bounded.lastVersion === 4 && hasSameEventIds(bounded.events, events.slice(1, 3)), "(fromVersion, toVersion] must include positions 2 and 3 while lastVersion reports the actual head at 4");
+			})
+		},
+		{
+			name: "bounded read edges: zero, beyond-head, and inverted ranges are empty or clamped",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const events = [
+					1,
+					2,
+					3
+				].map((sequence) => harness.createEvent(firstKey, sequence));
+				await store.append(firstKey, events, { expectedVersion: 0 });
+				const atZero = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					toVersion: 0
+				});
+				const beyondHead = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					toVersion: 99
+				});
+				const inverted = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					fromVersion: 2,
+					toVersion: 1
+				});
+				const equalBounds = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					fromVersion: 2,
+					toVersion: 2
+				});
+				assert(atZero.exists && atZero.lastVersion === 3 && atZero.events.length === 0, "toVersion=0 must return an existing empty window with the actual head");
+				assert(beyondHead.exists && beyondHead.lastVersion === 3 && hasSameEventIds(beyondHead.events, events), "toVersion beyond the head must clamp to the actual stream head");
+				assert(inverted.exists && inverted.lastVersion === 3 && inverted.events.length === 0 && equalBounds.exists && equalBounds.lastVersion === 3 && equalBounds.events.length === 0, "fromVersion >= toVersion describes an empty interval and must not throw");
+			})
+		},
+		{
+			name: "read state: empty and beyond-head windows retain existence and the actual stream head",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				await store.append(firstKey, [harness.createEvent(firstKey, 4), harness.createEvent(firstKey, 5)], { expectedVersion: 0 });
+				const atHead = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					fromVersion: 2
+				});
+				const beyondHead = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					fromVersion: 99
+				});
+				for (const result of [atHead, beyondHead]) assert(result.exists && result.lastVersion === 2 && result.events.length === 0, "an empty read window must retain stream existence and report the actual head, even when fromVersion is beyond it");
+			})
+		},
+		{
+			name: "qualified fromVersion: slicing one type cannot observe a colliding raw id",
+			run: inEnv(async ({ store }) => {
+				const [firstKey, secondKey] = harness.createCollidingStreamKeys();
+				const firstEvents = [
+					10,
+					11,
+					12
+				].map((sequence) => harness.createEvent(firstKey, sequence));
+				const secondEvents = [20, 21].map((sequence) => harness.createEvent(secondKey, sequence));
+				await store.append(firstKey, firstEvents, { expectedVersion: 0 });
+				await store.append(secondKey, secondEvents, { expectedVersion: 0 });
+				const firstTail = await store.readStream({ ...firstKey }, {
+					...fixtureRead,
+					fromVersion: 1
+				});
+				const secondTail = await store.readStream({ ...secondKey }, {
+					...fixtureRead,
+					fromVersion: 1
+				});
+				assert(firstTail.exists && firstTail.lastVersion === 3 && firstTail.events.length === 2 && firstTail.events[0]?.eventId === firstEvents[1]?.eventId && firstTail.events[1]?.eventId === firstEvents[2]?.eventId, "fromVersion must slice only the requested aggregate type's stream");
+				assert(secondTail.exists && secondTail.lastVersion === 2 && secondTail.events.length === 1 && secondTail.events[0]?.eventId === secondEvents[1]?.eventId, "a colliding raw id under another type must retain its independent version window");
+			})
+		},
+		{
+			name: "OCC: a rejected multi-event append is atomic and maps to ConcurrencyConflictError",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const seeded = [harness.createEvent(firstKey, 30), harness.createEvent(firstKey, 31)];
+				await store.append(firstKey, seeded, { expectedVersion: 0 });
+				assertChainContainsKitError(await captureRejection(store.append({ ...firstKey }, [harness.createEvent(firstKey, 32), harness.createEvent(firstKey, 33)], { expectedVersion: 1 })), ["CONCURRENCY_CONFLICT"], "a stale append must map the adapter conflict to ConcurrencyConflictError");
+				const stored = await store.readStream(firstKey, fixtureRead);
+				assert(stored.exists && stored.lastVersion === 2 && stored.events.length === 2 && stored.events[0]?.eventId === seeded[0]?.eventId && stored.events[1]?.eventId === seeded[1]?.eventId, "a rejected multi-event append must leave the stream untouched");
+			})
+		},
+		{
+			name: "OCC: duplicate create is rejected atomically with a sanctioned kit error",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const seeded = harness.createEvent(firstKey, 50);
+				await store.append(firstKey, [seeded], { expectedVersion: 0 });
+				assertChainContainsKitError(await captureRejection(store.append({ ...firstKey }, [harness.createEvent(firstKey, 51), harness.createEvent(firstKey, 52)], { expectedVersion: 0 })), ["CONCURRENCY_CONFLICT", "DUPLICATE_AGGREGATE"], "a duplicate create must map to ConcurrencyConflictError or the sanctioned DuplicateAggregateError");
+				const stored = await store.readStream(firstKey, fixtureRead);
+				assert(stored.exists && stored.lastVersion === 1 && stored.events.length === 1 && stored.events[0]?.eventId === seeded.eventId, "a rejected duplicate-create batch must leave the existing stream untouched");
+			})
+		},
+		{
+			name: "OCC: an expectedVersion ahead of an unknown stream conflicts without creating it",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				assertChainContainsKitError(await captureRejection(store.append(firstKey, [harness.createEvent(firstKey, 60)], { expectedVersion: 3 })), ["CONCURRENCY_CONFLICT"], "an expectedVersion ahead of the stream must map to ConcurrencyConflictError");
+				const first = harness.createEvent(firstKey, 61);
+				await store.append({ ...firstKey }, [first], { expectedVersion: 0 });
+				const stored = await store.readStream(firstKey, fixtureRead);
+				assert(stored.exists && stored.lastVersion === 1 && stored.events.length === 1 && stored.events[0]?.eventId === first.eventId, "the rejected append must not leave an empty stream or partial events behind");
+			})
+		},
+		{
+			name: "read ownership: a mutation attempt cannot mutate the stream",
+			run: inEnv(async ({ store }) => {
+				const [firstKey] = harness.createCollidingStreamKeys();
+				const seeded = harness.createEvent(firstKey, 40);
+				await store.append(firstKey, [seeded], { expectedVersion: 0 });
+				const callerOwned = (await store.readStream(firstKey, fixtureRead)).events;
+				try {
+					callerOwned.push(harness.createEvent(firstKey, 41));
+				} catch {}
+				const stored = await store.readStream({ ...firstKey }, fixtureRead);
+				assert(stored.exists && stored.events.length === 1 && stored.events[0]?.eventId === seeded.eventId, "readStream must return an owned array, never live internal state");
+			})
+		}
+	];
+}
+
+//#endregion
+//#region src/testing/idempotency-store-contract.ts
+function claimedHandle(claim, message) {
+	assert(claim.status === "claimed", message);
+	return claim.claim;
+}
+async function expireLease(env, claim) {
+	if (!env.expireLease) throw new Error("Contract violated: the non-transactional family requires expireLease on the environment");
+	await env.expireLease(claim);
+}
+async function advanceTimeTo(env, instant) {
+	if (!env.advanceTimeTo) throw new Error("Contract violated: the non-transactional family requires advanceTimeTo on the environment");
+	await env.advanceTimeTo(instant);
+}
+/**
+* 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)`.
+*/
+function createIdempotencyStoreContractTests(harness) {
+	const inEnv = bindContractEnvironment(() => harness.createEnvironment());
+	const tests = [
+		{
+			name: "a fresh key is claimed; the full lifecycle replays the outcome",
+			run: inEnv(async (env) => {
+				const claim = claimedHandle(await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1")), "a fresh key must be claimed by this execution");
+				await env.run((ctx) => env.store.complete(ctx, claim, { total: 42 }));
+				await env.store.confirm(claim);
+				const replay = await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"));
+				assert(replay.status === "completed", "a completed and confirmed key must replay as completed");
+				assert(deepEqual(replay.outcome, { total: 42 }), "the replayed outcome must round-trip the stored value");
+			})
+		},
+		{
+			name: "the same key with a different fingerprint throws IdempotencyKeyReuseError",
+			run: inEnv(async (env) => {
+				const first = await env.run(async (ctx) => {
+					const claim = claimedHandle(await env.store.claim(ctx, "key-1", "fp-1"), "a fresh key must be claimed");
+					await env.store.complete(ctx, claim, "done");
+					return claim;
+				});
+				await env.store.confirm(first);
+				assertChainContainsKitError(await captureRejection(env.run((ctx) => env.store.claim(ctx, "key-1", "fp-OTHER"))), ["IDEMPOTENCY_KEY_REUSE"], "a different fingerprint must throw IdempotencyKeyReuseError, never replay another command's outcome");
+			})
+		},
+		{
+			name: "abandon never destroys a completed, confirmed outcome",
+			run: inEnv(async (env) => {
+				const first = await env.run(async (ctx) => {
+					const claim = claimedHandle(await env.store.claim(ctx, "key-1", "fp-1"), "a fresh key must be claimed");
+					await env.store.complete(ctx, claim, "done");
+					return claim;
+				});
+				await env.store.confirm(first);
+				await env.store.abandon(first);
+				const claim = await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"));
+				assert(claim.status === "completed", "abandon must not release a completed, confirmed record");
+				assertEqual(claim.outcome, "done", "the outcome survives");
+			})
+		},
+		{
+			name: "confirm is idempotent, and confirming a missing key is a no-op",
+			run: inEnv(async (env) => {
+				const first = await env.run(async (ctx) => {
+					const claim = claimedHandle(await env.store.claim(ctx, "key-1", "fp-1"), "a fresh key must be claimed");
+					await env.store.complete(ctx, claim, "done");
+					return claim;
+				});
+				await env.store.confirm(first);
+				await env.store.confirm(first);
+				await env.store.confirm({
+					key: "never-claimed",
+					token: "missing"
+				});
+				const claim = await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"));
+				assert(claim.status === "completed" && claim.outcome === "done", "re-confirms and unknown-key confirms must change nothing");
+			})
+		},
+		{
+			name: "complete without a pending claim throws the wiring error",
+			run: inEnv(async (env) => {
+				assertChainContainsKitError(await captureRejection(env.run((ctx) => env.store.complete(ctx, {
+					key: "key-1",
+					token: "missing"
+				}, "x"))), ["IDEMPOTENCY_COMPLETED_WITHOUT_CLAIM"], "complete() without claim() must throw IdempotencyCompletionWithoutClaimError");
+			})
+		}
+	];
+	const nonTransactional = harness.family === "non-transactional";
+	if (!nonTransactional) tests.push({
+		name: "a committed complete replays even without confirm (commit is the finalize)",
+		run: inEnv(async (env) => {
+			await env.run(async (ctx) => {
+				const claim = claimedHandle(await env.store.claim(ctx, "key-1", "fp-1"), "a fresh key must be claimed");
+				await env.store.complete(ctx, claim, "done");
+			});
+			const claim = await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"));
+			assert(claim.status === "completed" && claim.outcome === "done", "a committed complete must replay without a confirm call");
+		})
+	});
+	tests.push(gatedContractTest({
+		capability: "family: non-transactional",
+		satisfiedBy: nonTransactional
+	}, {
+		name: "a pending claim is in-flight for concurrent claimers, and the error is retryable",
+		run: inEnv(async (env) => {
+			await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"));
+			const rejection = await captureRejection(env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1")));
+			assertChainContainsKitError(rejection, ["IDEMPOTENCY_IN_FLIGHT"], "claiming a pending key must throw IdempotencyInFlightError");
+			assert(chainContainsRetryable(rejection), "the in-flight error must be retryable (on the rejection or its cause chain)");
+		})
+	}), gatedContractTest({
+		capability: "family: non-transactional",
+		satisfiedBy: nonTransactional
+	}, {
+		name: "renew extends ownership beyond the original lease expiry",
+		run: inEnv(async (env) => {
+			const claim = claimedHandle(await env.run((ctx) => env.store.claim(ctx, "key-renew", "fp")), "a fresh key must be claimed");
+			assert(claim.lease !== void 0, "a non-transactional claim must carry lease timing");
+			const originalExpiry = new Date(claim.lease.expiresAt).getTime();
+			assert(Number.isFinite(originalExpiry) && new Date(originalExpiry).toISOString() === claim.lease.expiresAt && Number.isSafeInteger(claim.lease.renewAfterMs) && claim.lease.renewAfterMs > 0, "lease timing must carry a valid expiry and positive safe renewal delay");
+			await advanceTimeTo(env, /* @__PURE__ */ new Date(originalExpiry - 1));
+			const renewed = await env.store.renew(claim);
+			assert(renewed !== void 0 && new Date(renewed.expiresAt).getTime() > originalExpiry, "renew must extend the lease beyond its previous expiry");
+			await advanceTimeTo(env, new Date(originalExpiry + 1));
+			assertChainContainsKitError(await captureRejection(env.run((ctx) => env.store.claim(ctx, "key-renew", "fp"))), ["IDEMPOTENCY_IN_FLIGHT"], "the renewed owner must still hold the key after the original expiry");
+		})
+	}), gatedContractTest({
+		capability: "family: non-transactional",
+		satisfiedBy: nonTransactional
+	}, {
+		name: "an expired pending lease is reclaimed under a new token and fences its stale owner",
+		run: inEnv(async (env) => {
+			const first = claimedHandle(await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1")), "a fresh key must be claimed");
+			assert(first.lease !== void 0, "a non-transactional claim must carry lease timing");
+			await expireLease(env, first);
+			assert(claimedHandle(await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1")), "an expired pending claim must be reclaimed").token !== first.token, "each ownership generation must have a different token");
+			assertChainContainsKitError(await captureRejection(env.run((ctx) => env.store.complete(ctx, first, "stale"))), ["IDEMPOTENCY_CLAIM_LOST"], "a stale owner must fail before it can complete after takeover");
+		})
+	}), gatedContractTest({
+		capability: "family: non-transactional",
+		satisfiedBy: nonTransactional
+	}, {
+		name: "an expired staged outcome requires reconciliation and never auto-replays",
+		run: inEnv(async (env) => {
+			const first = await env.run(async (ctx) => {
+				const claim = claimedHandle(await env.store.claim(ctx, "key-1", "fp-1"), "a fresh key must be claimed");
+				await env.store.complete(ctx, claim, "uncertain");
+				return claim;
+			});
+			await expireLease(env, first);
+			const claim = await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"));
+			assert(claim.status === "reconciliation-required", "an expired staged outcome must require authoritative reconciliation");
+			assertEqual(claim.reconciliation.token, first.token, "the reconciliation receipt identifies the staged owner");
+		})
+	}), gatedContractTest({
+		capability: "family: non-transactional",
+		satisfiedBy: nonTransactional
+	}, {
+		name: "reconciliation confirms committed work or releases proven rollback",
+		run: inEnv(async (env) => {
+			await expireLease(env, await env.run(async (ctx) => {
+				const claim = claimedHandle(await env.store.claim(ctx, "committed", "fp"), "a fresh key must be claimed");
+				await env.store.complete(ctx, claim, "winner");
+				return claim;
+			}));
+			const committed = await env.run((ctx) => env.store.claim(ctx, "committed", "fp"));
+			assert(committed.status === "reconciliation-required", "the staged outcome must expose its reconciliation receipt");
+			await env.store.reconcile(committed.reconciliation, "committed");
+			const replay = await env.run((ctx) => env.store.claim(ctx, "committed", "fp"));
+			assert(replay.status === "completed" && replay.outcome === "winner", "committed evidence must make the staged outcome replayable");
+			await expireLease(env, await env.run(async (ctx) => {
+				const claim = claimedHandle(await env.store.claim(ctx, "rolled-back", "fp"), "a fresh key must be claimed");
+				await env.store.complete(ctx, claim, "must disappear");
+				return claim;
+			}));
+			const rolledBack = await env.run((ctx) => env.store.claim(ctx, "rolled-back", "fp"));
+			assert(rolledBack.status === "reconciliation-required", "the staged outcome must expose its reconciliation receipt");
+			await env.store.reconcile(rolledBack.reconciliation, "not-committed");
+			assertEqual((await env.run((ctx) => env.store.claim(ctx, "rolled-back", "fp"))).status, "claimed", "not-committed evidence must release the staged outcome");
+		})
+	}), gatedContractTest({
+		capability: "family: non-transactional",
+		satisfiedBy: nonTransactional
+	}, {
+		name: "a staged, unconfirmed outcome is in-flight, never replayed",
+		run: inEnv(async (env) => {
+			await env.run(async (ctx) => {
+				const claim = claimedHandle(await env.store.claim(ctx, "key-1", "fp-1"), "a fresh key must be claimed");
+				await env.store.complete(ctx, claim, "uncommitted");
+			});
+			assertChainContainsKitError(await captureRejection(env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"))), ["IDEMPOTENCY_IN_FLIGHT"], "a staged outcome must never replay; it is in-flight until confirmed");
+		})
+	}), gatedContractTest({
+		capability: "family: non-transactional",
+		satisfiedBy: nonTransactional
+	}, {
+		name: "abandon releases a pending claim so the next attempt claims fresh",
+		run: inEnv(async (env) => {
+			const first = claimedHandle(await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1")), "a fresh key must be claimed");
+			await env.store.abandon(first);
+			assertEqual((await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"))).status, "claimed", "an abandoned pending claim must be claimable again");
+		})
+	}), gatedContractTest({
+		capability: "family: non-transactional",
+		satisfiedBy: nonTransactional
+	}, {
+		name: "abandon releases a staged outcome so the next attempt claims fresh",
+		run: inEnv(async (env) => {
+			const first = await env.run(async (ctx) => {
+				const claim = claimedHandle(await env.store.claim(ctx, "key-1", "fp-1"), "a fresh key must be claimed");
+				await env.store.complete(ctx, claim, "uncommitted");
+				return claim;
+			});
+			await env.store.abandon(first);
+			assertEqual((await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"))).status, "claimed", "an abandoned staged outcome must be claimable again");
+		})
+	}), gatedContractTest({
+		capability: "family: transactional",
+		satisfiedBy: !nonTransactional
+	}, {
+		name: "a rolled-back transaction releases the claim (single-transaction pattern)",
+		run: inEnv(async (env) => {
+			if (!env.runRolledBack) throw new Error("Contract violated: the transactional family requires runRolledBack on the environment");
+			await env.runRolledBack(async (ctx) => {
+				const claim = claimedHandle(await env.store.claim(ctx, "key-1", "fp-1"), "a fresh key must be claimed");
+				await env.store.complete(ctx, claim, "rolled back");
+			}).catch(() => {});
+			assertEqual((await env.run((ctx) => env.store.claim(ctx, "key-1", "fp-1"))).status, "claimed", "a rolled-back claim/complete must leave the key claimable");
+		})
+	}));
+	return tests;
 }
-__name(createEsRepositoryContractTests, "createEsRepositoryContractTests");
 
-// src/testing/repository-contract.ts
+//#endregion
+//#region src/testing/outbox-contract.ts
+/**
+* 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)`.
+*/
+function createOutboxContractTests(harness) {
+	const inEnv = bindContractEnvironment(() => harness.createEnvironment());
+	const defaultSource = {
+		aggregateType: "ContractAggregate",
+		aggregateId: "contract-aggregate"
+	};
+	const commit = (events, aggregateVersion = 1, source = defaultSource) => events.map((event, commitSequence) => ({
+		event,
+		source,
+		position: {
+			aggregateVersion,
+			commitSequence,
+			commitSize: events.length
+		}
+	}));
+	const takeAndAck = async (env, count) => {
+		const records = [];
+		for (let index = 0; index < count; index += 1) {
+			const [record] = await env.outbox.getPending(1);
+			assert(record !== void 0, `expected committed outbox record ${index + 1} of ${count}`);
+			records.push(record);
+			await env.outbox.markDispatched([record.dispatchId]);
+		}
+		return records;
+	};
+	const tests = [
+		{
+			name: "finalizes complete commit receipts and links the next eventful commit",
+			run: inEnv(async (env) => {
+				await env.addCommitted(commit([harness.createEvent(1), harness.createEvent(2)], 1));
+				await env.addCommitted(commit([harness.createEvent(3)], 3));
+				assert(deepEqual((await takeAndAck(env, 3)).map(({ position }) => position), [
+					{
+						aggregateVersion: 1,
+						commitSequence: 0,
+						commitSize: 2,
+						previousEventfulAggregateVersion: null
+					},
+					{
+						aggregateVersion: 1,
+						commitSequence: 1,
+						commitSize: 2,
+						previousEventfulAggregateVersion: null
+					},
+					{
+						aggregateVersion: 3,
+						commitSequence: 0,
+						commitSize: 1,
+						previousEventfulAggregateVersion: 1
+					}
+				]), "the source must preserve zero-based commit completeness and link the next eventful commit to version 1");
+			})
+		},
+		{
+			name: "rejects different event identities at one qualified source position",
+			run: inEnv(async (env) => {
+				const original = commit([harness.createEvent(1)], 1);
+				const collision = commit([harness.createEvent(2)], 1);
+				await env.addCommitted(original);
+				assert(await captureRejection(env.addCommitted(collision)) !== void 0, "a different eventId at one qualified source position must reject");
+				const [record] = await takeAndAck(env, 1);
+				assertEqual(record?.event.eventId, original[0]?.event.eventId, "the rejected collision must not replace the original record");
+				await env.addCommitted(commit([harness.createEvent(3)], 2));
+				const [next] = await takeAndAck(env, 1);
+				assertEqual(next?.position.previousEventfulAggregateVersion, 1, "the rejected collision must not change the source head");
+			})
+		},
+		{
+			name: "keeps event-source heads isolated by aggregate type and id",
+			run: inEnv(async (env) => {
+				const sources = [
+					{
+						aggregateType: "Order",
+						aggregateId: "1"
+					},
+					{
+						aggregateType: "Payment",
+						aggregateId: "1"
+					},
+					{
+						aggregateType: "Order",
+						aggregateId: "2"
+					}
+				];
+				for (const [index, source] of sources.entries()) await env.addCommitted(commit([harness.createEvent(index + 1)], 1, source));
+				assert((await takeAndAck(env, sources.length)).every((record, index) => record.source.aggregateType === sources[index]?.aggregateType && record.source.aggregateId === sources[index]?.aggregateId && record.position.previousEventfulAggregateVersion === null), "colliding raw ids or aggregate types must each retain an independent genesis head");
+			})
+		},
+		{
+			name: "getPending returns records in commit order, across separate committed adds",
+			run: inEnv(async (env) => {
+				await env.addCommitted(commit([harness.createEvent(1), harness.createEvent(2)], 1));
+				await env.addCommitted(commit([harness.createEvent(3)], 2));
+				const pending = await env.outbox.getPending(10);
+				const expectedIds = [
+					1,
+					2,
+					3
+				].map((seed) => harness.createEvent(seed).eventId);
+				assert(pending.length >= 1, "a non-empty backlog must surface at least one record");
+				assert(deepEqual(pending.map((record) => record.event.eventId), expectedIds.slice(0, pending.length)), "records must come back in the order add() persisted them");
+			})
+		},
+		{
+			name: "getPending respects the limit",
+			run: inEnv(async (env) => {
+				await env.addCommitted(commit([
+					1,
+					2,
+					3,
+					4
+				].map((s) => harness.createEvent(s))));
+				const firstPage = await env.outbox.getPending(2);
+				assert(firstPage.length >= 1 && firstPage.length <= 2, "limit must bound the page: up to `limit` records, at least one while the backlog is non-empty");
+			})
+		},
+		gatedContractTest({
+			capability: "non-claiming getPending",
+			satisfiedBy: !harness.claimsOnGetPending
+		}, {
+			name: "an un-acked head comes back on the next poll (no silent skipping)",
+			run: inEnv(async (env) => {
+				await env.addCommitted(commit([
+					1,
+					2,
+					3,
+					4
+				].map((s) => harness.createEvent(s))));
+				const firstPage = await env.outbox.getPending(2);
+				const again = await env.outbox.getPending(2);
+				const overlap = Math.min(firstPage.length, again.length);
+				assert(overlap >= 1, "a non-empty backlog must surface at least one record on every poll");
+				assert(deepEqual(again.slice(0, overlap).map((r) => r.dispatchId), firstPage.slice(0, overlap).map((r) => r.dispatchId)), "an un-acked head must come back on the next poll (no silent skipping)");
+			})
+		}),
+		{
+			name: "markDispatched removes records; re-acks and unknown acks are accepted",
+			run: inEnv(async (env) => {
+				await env.addCommitted(commit([harness.createEvent(1), harness.createEvent(2)]));
+				const [first] = await env.outbox.getPending(1);
+				assert(first !== void 0, "expected a pending record");
+				await env.outbox.markDispatched([first.dispatchId]);
+				await env.outbox.markDispatched([first.dispatchId]);
+				await env.outbox.markDispatched(["no-such-dispatch-id"]);
+				assert(!(await env.outbox.getPending(10)).some((r) => r.dispatchId === first.dispatchId), "a dispatched record must never come back");
+			})
+		},
+		gatedContractTest({
+			capability: "non-claiming getPending",
+			satisfiedBy: !harness.claimsOnGetPending
+		}, {
+			name: "idempotent re-acks do not disturb other pending records",
+			run: inEnv(async (env) => {
+				await env.addCommitted(commit([harness.createEvent(1), harness.createEvent(2)]));
+				const [first] = await env.outbox.getPending(1);
+				assert(first !== void 0, "expected a pending record");
+				await env.outbox.markDispatched([first.dispatchId]);
+				await env.outbox.markDispatched([first.dispatchId]);
+				await env.outbox.markDispatched(["no-such-dispatch-id"]);
+				assertEqual((await env.outbox.getPending(10)).length, 1, "idempotent re-acks must not disturb other records");
+			})
+		}),
+		gatedContractTest({
+			capability: "dedupesOnEventId",
+			satisfiedBy: harness.dedupesOnEventId === true
+		}, {
+			name: "re-adding an event with the same eventId is deduped, not duplicated",
+			run: inEnv(async (env) => {
+				const original = commit([harness.createEvent(1)]);
+				await env.addCommitted(original);
+				try {
+					await env.addCommitted(original);
+				} catch (error) {
+					throw new Error(`Contract violated: add() must swallow a duplicate eventId, not throw. Dedupe means an idempotent add (INSERT ... ON CONFLICT DO NOTHING or equivalent), not a raised unique violation. Got: ${describeError(error)}`);
+				}
+				assertEqual((await env.outbox.getPending(10)).length, 1, "the same eventId must yield one record (unique-key dedupe)");
+			})
+		})
+	];
+	tests.push(gatedContractTest({
+		capability: "providesRolledBackAdds",
+		satisfiedBy: harness.providesRolledBackAdds === true
+	}, {
+		name: "a rolled-back add leaves nothing behind (transactional participation)",
+		run: inEnv(async (env) => {
+			if (!env.addRolledBack) throw new Error("Contract violated: harness declared providesRolledBackAdds but the environment lacks addRolledBack");
+			await env.addRolledBack(commit([harness.createEvent(1)], 1));
+			assertEqual((await env.outbox.getPending(10)).length, 0, "events added in a rolled-back transaction must not appear");
+			await env.addCommitted(commit([harness.createEvent(2)], 2));
+			const [afterRollback] = await takeAndAck(env, 1);
+			assertEqual(afterRollback?.position.previousEventfulAggregateVersion, null, "a rolled-back add must not advance the event-source head");
+		})
+	}));
+	const trackingEnabled = harness.failuresToDeadLetter !== void 0;
+	const attemptCeiling = harness.failuresToDeadLetter ?? 0;
+	const trackingGate = (test) => gatedContractTest({
+		capability: "failuresToDeadLetter (DispatchTrackingOutbox)",
+		satisfiedBy: trackingEnabled
+	}, test);
+	tests.push(trackingGate(gatedContractTest({
+		capability: "non-claiming getPending",
+		satisfiedBy: !harness.claimsOnGetPending
+	}, gatedContractTest({
+		capability: "failuresToDeadLetter >= 2",
+		satisfiedBy: attemptCeiling >= 2
+	}, {
+		name: "markFailed increments attempts surfaced on pending records",
+		run: inEnv(async (env) => {
+			const outbox = env.outbox;
+			assert(isDispatchTrackingOutbox(outbox), "harness declared a tracking outbox");
+			await env.addCommitted(commit([harness.createEvent(1)]));
+			const [record] = await outbox.getPending(1);
+			assert(record !== void 0, "expected a pending record");
+			await outbox.markFailed(record.dispatchId, /* @__PURE__ */ new Error("boom"));
+			const [after] = await outbox.getPending(1);
+			assertEqual(after?.attempts, 1, "attempts must be surfaced on the record after markFailed");
+		})
+	}))), trackingGate({
+		name: "reaching the attempt ceiling dead-letters the record and unblocks getPending",
+		run: inEnv(async (env) => {
+			const outbox = env.outbox;
+			assert(isDispatchTrackingOutbox(outbox), "harness declared a tracking outbox");
+			await env.addCommitted(commit([harness.createEvent(1), harness.createEvent(2)]));
+			const [poison] = await outbox.getPending(1);
+			assert(poison !== void 0, "expected a pending record");
+			let transition;
+			for (let i = 0; i < attemptCeiling; i++) {
+				const current = await outbox.markFailed(poison.dispatchId, /* @__PURE__ */ new Error("poison"));
+				if (i < attemptCeiling - 1) assertEqual(current, void 0, "markFailed must not report a dead-letter transition below the ceiling");
+				transition = current;
+			}
+			assertEqual(transition?.dispatchId, poison.dispatchId, "the ceiling-crossing markFailed call must return the exact dead-letter transition");
+			assertEqual(transition?.attempts, attemptCeiling, "the returned transition must carry the final attempt count");
+			assertEqual(await outbox.markFailed(poison.dispatchId, /* @__PURE__ */ new Error("late")), void 0, "a late failure report must not repeat the dead-letter transition");
+			const pending = await outbox.getPending(10);
+			assertEqual(pending.length, 1, "the dead-lettered record must stop coming back; successors must flow");
+			assert(pending[0]?.dispatchId !== poison.dispatchId, "the surviving record must be the successor, not the poison one");
+			const dead = await outbox.deadLetters();
+			assertEqual(dead.length, 1, "the record must appear in deadLetters()");
+			assertEqual(dead[0]?.attempts, attemptCeiling, "the dead-letter record must carry its attempt count");
+		})
+	}), trackingGate({
+		name: "markFailed on unknown or dispatched ids never resurrects a record",
+		run: inEnv(async (env) => {
+			const outbox = env.outbox;
+			assert(isDispatchTrackingOutbox(outbox), "harness declared a tracking outbox");
+			await env.addCommitted(commit([harness.createEvent(1)]));
+			const [record] = await outbox.getPending(1);
+			assert(record !== void 0, "expected a pending record");
+			await outbox.markDispatched([record.dispatchId]);
+			await outbox.markFailed(record.dispatchId, /* @__PURE__ */ new Error("late report"));
+			await outbox.markFailed("no-such-id", /* @__PURE__ */ new Error("unknown"));
+			assertEqual((await outbox.getPending(10)).length, 0, "late or unknown failure reports must not resurrect records");
+			assertEqual((await outbox.deadLetters()).length, 0, "late or unknown failure reports must not dead-letter anything");
+		})
+	}), trackingGate({
+		name: "markDispatched clears a dead-lettered record (manual redelivery then ack)",
+		run: inEnv(async (env) => {
+			const outbox = env.outbox;
+			assert(isDispatchTrackingOutbox(outbox), "harness declared a tracking outbox");
+			await env.addCommitted(commit([harness.createEvent(1)]));
+			const [record] = await outbox.getPending(1);
+			assert(record !== void 0, "expected a pending record");
+			for (let i = 0; i < attemptCeiling; i++) await outbox.markFailed(record.dispatchId, /* @__PURE__ */ new Error("poison"));
+			await outbox.markDispatched([record.dispatchId]);
+			assertEqual((await outbox.deadLetters()).length, 0, "acking a dead-lettered record must clear it");
+		})
+	}));
+	return tests;
+}
+
+//#endregion
+//#region src/testing/projection-checkpoint-contract.ts
+const pos = (aggregateVersion, commitSequence, commitSize = commitSequence + 1, previousEventfulAggregateVersion = null) => ({
+	aggregateVersion,
+	commitSequence,
+	commitSize,
+	previousEventfulAggregateVersion
+});
+const order = (aggregateId) => ({
+	aggregateType: "Order",
+	aggregateId
+});
+const checkpoint = (position, lastAppliedEventId = "evt-at-watermark") => ({
+	position,
+	lastAppliedEventId
+});
+/**
+* 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)`.
+*/
+function createProjectionCheckpointStoreContractTests(harness) {
+	const inEnv = bindContractEnvironment(() => harness.createEnvironment());
+	return [
+		{
+			name: "a never-seen (projection, aggregate) pair loads undefined",
+			run: inEnv(async (env) => {
+				assertEqual(await env.run((ctx) => env.store.load(ctx, "order-list", order("o-1"))), void 0, "a fresh store must report no watermark");
+			})
+		},
+		gatedContractTest({
+			capability: "providesConcurrentRuns",
+			satisfiedBy: harness.providesConcurrentRuns === true
+		}, {
+			name: "checkpoint locks serialize competing critical sections for absent and existing rows",
+			run: inEnv(async (env) => {
+				const runConcurrently = env.runConcurrently;
+				if (!runConcurrently) throw new Error("Contract violated: harness declared providesConcurrentRuns but the environment lacks runConcurrently");
+				const contenders = 8;
+				const address = order("o-locked");
+				const advanceOnce = async (expectedVersion, nextVersion) => {
+					return (await runConcurrently(Array.from({ length: contenders }, () => (ctx) => env.store.withCheckpointLocks(ctx, "order-list", [address], async () => {
+						const stored = await env.store.load(ctx, "order-list", address);
+						if (expectedVersion === void 0 ? stored !== void 0 : stored?.position.aggregateVersion !== expectedVersion) return false;
+						await Promise.resolve();
+						await env.store.save(ctx, "order-list", address, checkpoint(pos(nextVersion, 0), `evt-v${nextVersion}`));
+						return true;
+					})))).filter((advanced) => advanced).length;
+				};
+				assertEqual(await advanceOnce(void 0, 1), 1, "exactly one competing callback may advance a missing checkpoint key; genesis has no row that SELECT FOR UPDATE could lock");
+				assertEqual(await advanceOnce(1, 2), 1, "exactly one competing callback may advance an existing checkpoint key from the observed watermark");
+				assert((await env.run((ctx) => env.store.load(ctx, "order-list", address)))?.position.aggregateVersion === 2, "serialized genesis and existing-row advances must leave the final watermark visible");
+			})
+		}),
+		{
+			name: "checkpoint locks release after a rejected critical section",
+			run: inEnv(async (env) => {
+				const address = order("o-rejected-lock");
+				assert(await captureRejection(env.run((ctx) => env.store.withCheckpointLocks(ctx, "order-list", [address], async () => {
+					throw new Error("projection failed");
+				}))) !== void 0, "the store must propagate a rejected critical section");
+				let retried = false;
+				await env.run((ctx) => env.store.withCheckpointLocks(ctx, "order-list", [address], async () => {
+					retried = true;
+				}));
+				assert(retried, "a rejected callback must release its key so redelivery can enter");
+			})
+		},
+		{
+			name: "save/load round-trips the complete checkpoint receipt",
+			run: inEnv(async (env) => {
+				await env.run((ctx) => env.store.save(ctx, "order-list", order("o-1"), checkpoint(pos(5, 2, 3, 3), "evt-o-1-5-2")));
+				const loaded = await env.run((ctx) => env.store.load(ctx, "order-list", order("o-1")));
+				assert(loaded?.position.aggregateVersion === 5 && loaded.position.commitSequence === 2 && loaded.position.commitSize === 3 && loaded.position.previousEventfulAggregateVersion === 3 && loaded.lastAppliedEventId === "evt-o-1-5-2", "the stored checkpoint must round-trip every cursor field and the watermark event identity");
+			})
+		},
+		{
+			name: "save overwrites the previous watermark (last write wins; monotonicity is the projector's job)",
+			run: inEnv(async (env) => {
+				await env.run(async (ctx) => {
+					await env.store.save(ctx, "order-list", order("o-1"), checkpoint(pos(5, 0), "evt-first"));
+					await env.store.save(ctx, "order-list", order("o-1"), checkpoint(pos(5, 1), "evt-second"));
+				});
+				const loaded = await env.run((ctx) => env.store.load(ctx, "order-list", order("o-1")));
+				assert(loaded?.position.aggregateVersion === 5 && loaded.position.commitSequence === 1 && loaded.lastAppliedEventId === "evt-second", "a later save must replace the stored watermark verbatim");
+			})
+		},
+		{
+			name: "a loaded position is a detached copy; mutating it must not move the watermark",
+			run: inEnv(async (env) => {
+				await env.run((ctx) => env.store.save(ctx, "order-list", order("o-1"), checkpoint(pos(2, 0))));
+				const loaded = await env.run((ctx) => env.store.load(ctx, "order-list", order("o-1")));
+				assert(loaded !== void 0, "expected a stored watermark");
+				loaded.position.aggregateVersion = 99;
+				assert((await env.run((ctx) => env.store.load(ctx, "order-list", order("o-1"))))?.position.aggregateVersion === 2, "the stored watermark must be immune to mutation of a previously loaded copy");
+			})
+		},
+		{
+			name: "watermarks are isolated per projection and per aggregate",
+			run: inEnv(async (env) => {
+				await env.run(async (ctx) => {
+					await env.store.save(ctx, "order-list", order("o-1"), checkpoint(pos(3, 0)));
+					await env.store.save(ctx, "order-detail", order("o-1"), checkpoint(pos(1, 0)));
+					await env.store.save(ctx, "order-list", order("o-2"), checkpoint(pos(7, 0)));
+				});
+				const [listO1, detailO1, listO2] = await env.run((ctx) => Promise.all([
+					env.store.load(ctx, "order-list", order("o-1")),
+					env.store.load(ctx, "order-detail", order("o-1")),
+					env.store.load(ctx, "order-list", order("o-2"))
+				]));
+				assert(listO1?.position.aggregateVersion === 3 && detailO1?.position.aggregateVersion === 1 && listO2?.position.aggregateVersion === 7, "the watermark key is the (projection, aggregateType, aggregateId) triple; no part may bleed into another");
+			})
+		},
+		{
+			name: "watermarks are isolated per aggregate TYPE: colliding raw ids do not share a checkpoint",
+			run: inEnv(async (env) => {
+				await env.run(async (ctx) => {
+					await env.store.save(ctx, "order-list", {
+						aggregateType: "Order",
+						aggregateId: "1"
+					}, checkpoint(pos(10, 0)));
+					await env.store.save(ctx, "order-list", {
+						aggregateType: "Payment",
+						aggregateId: "1"
+					}, checkpoint(pos(1, 0)));
+				});
+				const [orderMark, paymentMark] = await env.run((ctx) => Promise.all([env.store.load(ctx, "order-list", {
+					aggregateType: "Order",
+					aggregateId: "1"
+				}), env.store.load(ctx, "order-list", {
+					aggregateType: "Payment",
+					aggregateId: "1"
+				})]));
+				assert(orderMark?.position.aggregateVersion === 10 && paymentMark?.position.aggregateVersion === 1, "identities are type-scoped: Order 1 at version 10 must not make Payment 1 look processed");
+			})
+		},
+		{
+			name: "address encoding is collision-free even with separator-like characters in either half",
+			run: inEnv(async (env) => {
+				const inType = {
+					aggregateType: "A\0B",
+					aggregateId: "C"
+				};
+				const inId = {
+					aggregateType: "A",
+					aggregateId: "B\0C"
+				};
+				await env.run(async (ctx) => {
+					await env.store.save(ctx, "order-list", inType, checkpoint(pos(10, 0)));
+					await env.store.save(ctx, "order-list", inId, checkpoint(pos(1, 0)));
+				});
+				const [first, second] = await env.run((ctx) => Promise.all([env.store.load(ctx, "order-list", inType), env.store.load(ctx, "order-list", inId)]));
+				assert(first?.position.aggregateVersion === 10 && second?.position.aggregateVersion === 1, "two addresses that differ only in where a hostile separator sits must not share a watermark");
+			})
+		},
+		{
+			name: "hasReached compares the full pair: unseen is false, behind is false, at and past are true",
+			run: inEnv(async (env) => {
+				await env.run((ctx) => env.store.save(ctx, "order-list", order("o-1"), checkpoint(pos(5, 0))));
+				assertEqual(await env.store.hasReached("order-list", order("o-2"), pos(1, 0)), false, "an unseen aggregate has reached nothing");
+				assertEqual(await env.store.hasReached("order-list", order("o-1"), pos(5, 1)), false, "a later commitSequence of the SAME version is not yet reached; comparing on the version alone would lie mid-commit");
+				assertEqual(await env.store.hasReached("order-list", order("o-1"), pos(6, 0)), false, "a later version is not yet reached");
+				assertEqual(await env.store.hasReached("order-list", order("o-1"), pos(5, 0)), true, "the stored position itself is reached");
+				assertEqual(await env.store.hasReached("order-list", order("o-1"), pos(4, 7)), true, "any earlier version is reached regardless of its commitSequence");
+			})
+		},
+		{
+			name: "reset clears only the named projection's checkpoints",
+			run: inEnv(async (env) => {
+				await env.run(async (ctx) => {
+					await env.store.save(ctx, "order-list", order("o-1"), checkpoint(pos(3, 0)));
+					await env.store.save(ctx, "order-detail", order("o-1"), checkpoint(pos(2, 0)));
+				});
+				await env.run((ctx) => env.store.reset(ctx, "order-list"));
+				const [cleared, untouched] = await env.run((ctx) => Promise.all([env.store.load(ctx, "order-list", order("o-1")), env.store.load(ctx, "order-detail", order("o-1"))]));
+				assertEqual(cleared, void 0, "the reset projection must start from zero (rebuild entry point)");
+				assert(untouched?.position.aggregateVersion === 2, "a sibling projection's checkpoints must survive the reset");
+				assertEqual(await env.store.hasReached("order-list", order("o-1"), pos(1, 0)), false, "hasReached must report false after a reset");
+			})
+		},
+		gatedContractTest({
+			capability: "providesRolledBackRuns",
+			satisfiedBy: harness.providesRolledBackRuns === true
+		}, {
+			name: "a rolled-back save leaves no checkpoint behind (atomic update+checkpoint)",
+			run: inEnv(async (env) => {
+				if (!env.runRolledBack) throw new Error("Contract violated: harness declared providesRolledBackRuns but the environment lacks runRolledBack");
+				await env.runRolledBack((ctx) => env.store.save(ctx, "order-list", order("o-1"), checkpoint(pos(1, 0)))).catch(() => {});
+				assertEqual(await env.run((ctx) => env.store.load(ctx, "order-list", order("o-1"))), void 0, "a checkpoint from a rolled-back transaction must not exist; otherwise events are lost while marked processed");
+			})
+		})
+	];
+}
+
+//#endregion
+//#region src/testing/repository-contract.ts
+/**
+* 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.
+*/
 function createRepositoryContractTests(harness) {
-  const withEnvironment = /* @__PURE__ */ __name((body) => runInContractEnvironment(() => harness.createEnvironment(), body), "withEnvironment");
-  const loadOrFail = /* @__PURE__ */ __name((repository, id) => loadAggregateOrFail(
-    repository,
-    id,
-    "broken hydration or a write that did not commit"
-  ), "loadOrFail");
-  async function seed(env) {
-    const aggregate = harness.createAggregate();
-    harness.mutate(aggregate);
-    await env.run(async ({ repository }) => {
-      await repository.save(aggregate);
-    });
-    return aggregate;
-  }
-  __name(seed, "seed");
-  async function reload(env, id) {
-    return env.run(({ repository }) => loadOrFail(repository, id));
-  }
-  __name(reload, "reload");
-  const eventIds = /* @__PURE__ */ __name((events) => events.map((event) => event.eventId).sort(), "eventIds");
-  const snapshotState = harness.snapshotState;
-  const mutateVersionOnly = harness.mutateVersionOnly;
-  const mutateChildCollection = harness.mutateChildCollection;
-  const createAggregateWithId = harness.createAggregateWithId;
-  const deletesAreVersionChecked = harness.deletesAreVersionChecked === true;
-  const insertsAreDuplicateChecked = harness.insertsAreDuplicateChecked !== false;
-  const skippedTest = /* @__PURE__ */ __name((name, capability) => skippedContractTest(name, capability), "skippedTest");
-  const tests = [
-    {
-      name: "MANDATORY two-writer conflict: the stale writer throws ConcurrencyConflictError and persists nothing",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const seedEvents = await env.committedOutboxEvents();
-        const seedEventIds = new Set(seedEvents.map((e) => e.eventId));
-        const staleB = await reload(env, seeded.id);
-        const committedA = await env.run(async ({ repository }) => {
-          const a = await loadOrFail(repository, seeded.id);
-          harness.mutate(a);
-          await repository.save(a);
-          return a;
-        });
-        const outboxAfterA = await env.committedOutboxEvents();
-        assert(
-          outboxAfterA.length > seedEvents.length,
-          "writer A's events must reach the outbox on commit"
-        );
-        const newSinceSeed = outboxAfterA.filter(
-          (event) => !seedEventIds.has(event.eventId)
-        );
-        assert(
-          newSinceSeed.length > 0 && newSinceSeed.every(
-            (event) => event.aggregateVersion === committedA.version
-          ),
-          `writer A's committed outbox events must carry aggregateVersion === ${committedA.version} (A's commit version). Suspect #1: your outbox read-back (committedOutboxEvents) reconstructs events from an explicit column list and drops or string-types the aggregateVersion field. Suspect #2: a hand-rolled orchestration that does not stamp aggregateVersion = aggregate.version at harvest (withCommit does this automatically).`
-        );
-        harness.mutate(staleB);
-        const rejection = await captureRejection(
-          env.run(async ({ repository }) => {
-            await repository.save(staleB);
-          })
-        );
-        assert(
-          rejection !== void 0,
-          "the second writer's commit must reject - it committed on a stale version instead (OCC predicate missing?)"
-        );
-        assert(
-          chainContainsErrorNamed(rejection, "ConcurrencyConflictError"),
-          `the second writer's rejection must be (or wrap, via the cause chain) ConcurrencyConflictError; got: ${describeError(rejection)}`
-        );
-        const final = await reload(env, seeded.id);
-        assertEqual(
-          final.version,
-          committedA.version,
-          "the persisted version must equal writer A's committed version"
-        );
-        if (snapshotState) {
-          assert(
-            deepEqual(
-              snapshotState.call(harness, final),
-              snapshotState.call(harness, committedA)
-            ),
-            "the persisted STATE must equal writer A's. Two suspects: (a) a predicate that guards only the version write lets the stale writer's state survive; (b) your snapshotState projection is not roundtrip-stable (date precision, undefined-valued keys, decimal representation) - see its JSDoc"
-          );
-        }
-        const outboxFinal = await env.committedOutboxEvents();
-        assert(
-          deepEqual(eventIds(outboxFinal), eventIds(outboxAfterA)),
-          "the outbox must contain exactly the winning writer's events (compared by eventId) - nothing from the stale writer, nothing replaced"
-        );
-      }), "run")
-    },
-    {
-      name: "insert routing: a never-persisted aggregate INSERTs even after pre-save mutations",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const aggregate = harness.createAggregate();
-        assert(
-          aggregate.persistedVersion === void 0,
-          "harness contract: createAggregate() must return a never-persisted aggregate (persistedVersion === undefined)"
-        );
-        harness.mutate(aggregate);
-        harness.mutate(aggregate);
-        await env.run(async ({ repository }) => {
-          await repository.save(aggregate);
-        });
-        const loaded = await reload(env, aggregate.id);
-        assertEqual(
-          loaded.version,
-          aggregate.version,
-          "the INSERT must persist the in-memory version (route on persistedVersion === undefined, not version === 0)"
-        );
-      }), "run")
-    },
-    {
-      name: "update writes the in-memory version and predicates on persistedVersion",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const baseline = seeded.version;
-        await env.run(async ({ repository }) => {
-          const loaded = await loadOrFail(repository, seeded.id);
-          harness.mutate(loaded);
-          harness.mutate(loaded);
-          await repository.save(loaded);
-        });
-        const final = await reload(env, seeded.id);
-        assertEqual(
-          final.version,
-          baseline + 2,
-          "two mutations must persist as baseline + 2 (version is a mutation sequence)"
-        );
-        assertEqual(
-          final.persistedVersion,
-          final.version,
-          "a reloaded aggregate's persistedVersion must equal its version"
-        );
-      }), "run")
-    },
-    {
-      name: "rollback persists nothing: state, version, and outbox untouched",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const versionBefore = seeded.version;
-        const outboxBefore = (await env.committedOutboxEvents()).length;
-        const probe = new Error("contract rollback probe");
-        const rejection = await captureRejection(
-          env.run(async ({ repository }) => {
-            const loaded = await loadOrFail(repository, seeded.id);
-            harness.mutate(loaded);
-            await repository.save(loaded);
-            throw probe;
-          })
-        );
-        assert(
-          rejection !== void 0,
-          "a throwing unit of work must reject"
-        );
-        const final = await reload(env, seeded.id);
-        assertEqual(
-          final.version,
-          versionBefore,
-          "a rolled-back write must not change the persisted version"
-        );
-        assertEqual(
-          (await env.committedOutboxEvents()).length,
-          outboxBefore,
-          "a rolled-back transaction must not leave events in the outbox"
-        );
-      }), "run")
-    },
-    {
-      name: "identity map: two getById calls in one unit of work return the same instance",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        await env.run(async ({ repository }) => {
-          const first = await repository.getById(seeded.id);
-          const second = await repository.getById(seeded.id);
-          assert(
-            first !== null && first === second,
-            "repeated loads within one unit of work must return the SAME instance (identity map) - distinct instances double-harvest events"
-          );
-        });
-      }), "run")
-    },
-    {
-      name: "delete: getById returns null in the same unit of work and after the commit",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        await env.run(async ({ repository }) => {
-          const loaded = await loadOrFail(repository, seeded.id);
-          await repository.delete(loaded);
-          const probe = await repository.getById(seeded.id);
-          assert(
-            probe === null,
-            "after delete, getById in the SAME unit of work must return null (isDeleted check), even if the physical delete is deferred"
-          );
-        });
-        await env.run(async ({ repository }) => {
-          const probe = await repository.getById(seeded.id);
-          assert(
-            probe === null,
-            "after the deleting unit of work committed, the aggregate must be gone"
-          );
-        });
-      }), "run")
-    },
-    {
-      name: "deletion is final: saving the deleted aggregate in the same unit of work throws AggregateDeletedError",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const rejection = await captureRejection(
-          env.run(async ({ repository }) => {
-            const loaded = await loadOrFail(repository, seeded.id);
-            harness.mutate(loaded);
-            await repository.delete(loaded);
-            await repository.save(loaded);
-          })
-        );
-        assert(
-          chainContainsErrorNamed(rejection, "AggregateDeletedError"),
-          `save-after-delete must reject with (or wrap) AggregateDeletedError; got: ${describeError(rejection)}. If you see ConcurrencyConflictError here instead, your save() probably enrolls AFTER the row write - enroll first.`
-        );
-      }), "run")
-    },
-    {
-      name: "events are cleared after a committed unit of work and kept after a rollback",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const committed = harness.createAggregate();
-        harness.mutate(committed);
-        assert(
-          committed.pendingEvents.length > 0,
-          "harness contract: mutate() must record at least one domain event"
-        );
-        await env.run(async ({ repository }) => {
-          await repository.save(committed);
-        });
-        assertEqual(
-          committed.pendingEvents.length,
-          0,
-          "pending events must be cleared after a successful commit"
-        );
-        const rolledBack = harness.createAggregate();
-        harness.mutate(rolledBack);
-        const pendingBefore = rolledBack.pendingEvents.length;
-        await captureRejection(
-          env.run(async ({ repository }) => {
-            await repository.save(rolledBack);
-            throw new Error("contract rollback probe");
-          })
-        );
-        assertEqual(
-          rolledBack.pendingEvents.length,
-          pendingBefore,
-          "pending events must survive a rollback (so a fresh load + retry can re-emit them)"
-        );
-      }), "run")
-    },
-    {
-      name: "persistedVersion syncs only after a successful commit",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const aggregate = harness.createAggregate();
-        harness.mutate(aggregate);
-        await captureRejection(
-          env.run(async ({ repository }) => {
-            await repository.save(aggregate);
-            throw new Error("contract rollback probe");
-          })
-        );
-        assert(
-          aggregate.persistedVersion === void 0,
-          "a rolled-back first save must leave persistedVersion undefined (the aggregate is still unpersisted)"
-        );
-        await env.run(async ({ repository }) => {
-          await repository.save(aggregate);
-        });
-        assertEqual(
-          aggregate.persistedVersion,
-          aggregate.version,
-          "after a successful commit, persistedVersion must equal version (markPersisted ran)"
-        );
-      }), "run")
-    }
-  ];
-  tests.push(
-    mutateVersionOnly ? {
-      name: "version-only change still persists (skip-save must not desync the OCC baseline)",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const baseline = seeded.version;
-        await env.run(async ({ repository }) => {
-          const loaded = await loadOrFail(repository, seeded.id);
-          mutateVersionOnly.call(harness, loaded);
-          await repository.save(loaded);
-        });
-        const final = await reload(env, seeded.id);
-        assertEqual(
-          final.version,
-          baseline + 1,
-          "a version-only change (empty changedKeys, bumped version) must still be persisted - skipping it desyncs persistedVersion and produces false ConcurrencyConflictErrors later"
-        );
-      }), "run")
-    } : skippedTest(
-      "version-only change still persists (skip-save must not desync the OCC baseline)",
-      "mutateVersionOnly"
-    )
-  );
-  tests.push(
-    mutateChildCollection ? {
-      name: "a child-collection-only change bumps the persisted root version",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const baseline = seeded.version;
-        await env.run(async ({ repository }) => {
-          const loaded = await loadOrFail(repository, seeded.id);
-          mutateChildCollection.call(harness, loaded);
-          await repository.save(loaded);
-        });
-        const final = await reload(env, seeded.id);
-        assert(
-          final.version > baseline,
-          "a child-collection-only change must advance the persisted ROOT version - otherwise concurrent writers interleave with collection writes undetected"
-        );
-      }), "run")
-    } : skippedTest(
-      "a child-collection-only change bumps the persisted root version",
-      "mutateChildCollection"
-    )
-  );
-  tests.push(
-    createAggregateWithId ? {
-      name: "deletion is final across instances: a re-created aggregate with the same id cannot be saved",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const rejection = await captureRejection(
-          env.run(async ({ repository }) => {
-            const loaded = await loadOrFail(repository, seeded.id);
-            await repository.delete(loaded);
-            const resurrected = createAggregateWithId.call(
-              harness,
-              seeded.id
-            );
-            harness.mutate(resurrected);
-            await repository.save(resurrected);
-          })
-        );
-        assert(
-          chainContainsErrorNamed(rejection, "AggregateDeletedError"),
-          `saving a re-created instance of a deleted aggregate must reject with (or wrap) AggregateDeletedError; got: ${describeError(rejection)}`
-        );
-      }), "run")
-    } : skippedTest(
-      "deletion is final across instances: a re-created aggregate with the same id cannot be saved",
-      "createAggregateWithId"
-    )
-  );
-  tests.push(
-    createAggregateWithId && insertsAreDuplicateChecked ? {
-      name: "duplicate insert: a second never-persisted aggregate with an existing id throws DuplicateAggregateError",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const duplicate = createAggregateWithId.call(
-          harness,
-          seeded.id
-        );
-        harness.mutate(duplicate);
-        harness.mutate(duplicate);
-        const rejection = await captureRejection(
-          env.run(async ({ repository }) => {
-            await repository.save(duplicate);
-          })
-        );
-        assert(
-          chainContainsErrorNamed(rejection, "DuplicateAggregateError"),
-          `inserting a second aggregate with an existing id must reject with (or wrap) DuplicateAggregateError - map your driver's unique-violation signal (Postgres 23505, MySQL 1062, SQLite SQLITE_CONSTRAINT_UNIQUE) instead of letting the raw driver error escape; got: ${describeError(rejection)}`
-        );
-        const final = await reload(env, seeded.id);
-        assertEqual(
-          final.version,
-          seeded.version,
-          "the existing row must be untouched by the rejected duplicate insert - a duplicate check that fires AFTER the write (or outside the transaction) clobbers the existing row"
-        );
-        if (snapshotState) {
-          assert(
-            deepEqual(
-              snapshotState.call(harness, final),
-              snapshotState.call(harness, seeded)
-            ),
-            "the existing row's STATE must be untouched by the rejected duplicate insert"
-          );
-        }
-      }), "run")
-    } : skippedTest(
-      "duplicate insert: a second never-persisted aggregate with an existing id throws DuplicateAggregateError",
-      // Name the capability that is actually missing: the
-      // mechanical one (cannot build the duplicate) or the
-      // semantic opt-out (deliberately upserting adapter).
-      createAggregateWithId ? "insertsAreDuplicateChecked" : "createAggregateWithId"
-    )
-  );
-  tests.push(
-    deletesAreVersionChecked ? {
-      name: "stale delete conflicts: deleting from a stale instance throws ConcurrencyConflictError",
-      run: /* @__PURE__ */ __name(() => withEnvironment(async (env) => {
-        const seeded = await seed(env);
-        const staleB = await reload(env, seeded.id);
-        const versionAfterA = await env.run(
-          async ({ repository }) => {
-            const a = await loadOrFail(repository, seeded.id);
-            harness.mutate(a);
-            await repository.save(a);
-            return a.version;
-          }
-        );
-        const rejection = await captureRejection(
-          env.run(async ({ repository }) => {
-            await repository.delete(staleB);
-          })
-        );
-        assert(
-          chainContainsErrorNamed(rejection, "ConcurrencyConflictError"),
-          `a stale delete must reject with (or wrap) ConcurrencyConflictError; got: ${describeError(rejection)} - an unpredicated DELETE silently destroys the concurrent writer's update`
-        );
-        const final = await env.run(
-          ({ repository }) => repository.getById(seeded.id)
-        );
-        assert(
-          final !== null,
-          "the row must still exist after the stale delete was rejected - the predicate must PREVENT the destructive delete, not merely report it"
-        );
-        assertEqual(
-          final.version,
-          versionAfterA,
-          "the surviving row must carry writer A's version"
-        );
-      }), "run")
-    } : skippedTest(
-      "stale delete conflicts: deleting from a stale instance throws ConcurrencyConflictError",
-      "deletesAreVersionChecked"
-    )
-  );
-  return tests;
+	const inEnvironment = bindContractEnvironment(() => harness.createEnvironment());
+	const snapshotState = harness.snapshotState;
+	const createAggregateWithId = harness.createAggregateWithId;
+	const mutateVersionOnly = harness.mutateVersionOnly;
+	const mutateChildCollection = harness.mutateChildCollection;
+	const insertsAreDuplicateChecked = harness.insertsAreDuplicateChecked !== false;
+	const removesAreSupported = harness.removesAreSupported === true;
+	const removesAreVersionChecked = removesAreSupported && harness.removesAreVersionChecked === true;
+	const load = (repository, id) => loadAggregateOrFail(repository, id, "the adapter did not commit or reconstitute the aggregate");
+	async function seed(environment) {
+		const aggregate = harness.createAggregate();
+		harness.mutate(aggregate);
+		await environment.run(async ({ repository }) => {
+			repository.add(aggregate);
+		});
+		return aggregate;
+	}
+	const reload = (environment, id) => environment.run(({ repository }) => load(repository, id));
+	const eventIds = (events) => sortedCommittedEventIds(events);
+	const pendingEventIds = (events) => mintedPendingEventIds(events, "the harness must record pending events before persistence");
+	const tests = [
+		{
+			name: "add flushes a new aggregate and its exact event batch atomically",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				harness.mutate(aggregate);
+				const registeredEvents = [...aggregate.pendingEvents];
+				await environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+				});
+				const reloaded = await reload(environment, aggregate.id);
+				assertEqual(reloaded.version, aggregate.version, "add must store the version registered by the Unit of Work");
+				if (snapshotState) assert(deepEqual(snapshotState.call(harness, reloaded), snapshotState.call(harness, aggregate)), "add must store the adapter's complete persistence projection");
+				const outbox = await environment.committedOutboxEvents();
+				assert(deepEqual(eventIds(outbox), pendingEventIds(registeredEvents).sort()), "the outbox must contain exactly the batch registered by add");
+				assertEqual(aggregate.pendingEvents.length, 0, "only a committed add acknowledges its registered event batch");
+			})
+		},
+		{
+			name: "committed outbox envelopes carry exact position facts",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				harness.mutate(aggregate);
+				harness.mutate(aggregate);
+				const batchSize = aggregate.pendingEvents.length;
+				const committedVersion = aggregate.version;
+				await environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+				});
+				const positions = (await environment.committedOutboxEvents()).map(({ position }) => position).sort((a, b) => a.commitSequence - b.commitSequence);
+				assertEqual(positions.length, batchSize, "every registered event must commit exactly one envelope");
+				positions.forEach((position, index) => {
+					assertEqual(position.aggregateVersion, committedVersion, "every envelope must carry the version the commit persisted");
+					assertEqual(position.commitSequence, index, "commitSequence must be gapless and zero-based over the batch");
+					assertEqual(position.commitSize, batchSize, "commitSize must equal the exact batch length");
+				});
+			})
+		},
+		{
+			name: "MANDATORY stale update: writer B conflicts after writer A commits and persists nothing",
+			run: inEnvironment(async (environment) => {
+				const seeded = await seed(environment);
+				let loadedB;
+				const bLoaded = new Promise((resolve) => {
+					loadedB = resolve;
+				});
+				let releaseB;
+				const bMayFlush = new Promise((resolve) => {
+					releaseB = resolve;
+				});
+				const writerB = environment.run(async ({ repository }) => {
+					const stale = await load(repository, seeded.id);
+					loadedB();
+					await bMayFlush;
+					harness.mutate(stale);
+					repository.update(stale);
+				});
+				await bLoaded;
+				const committedA = await environment.run(async ({ repository }) => {
+					const current = await load(repository, seeded.id);
+					harness.mutate(current);
+					repository.update(current);
+					return current;
+				});
+				const outboxAfterA = await environment.committedOutboxEvents();
+				releaseB();
+				const rejection = await captureRejection(writerB);
+				assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale update must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
+				const final = await reload(environment, seeded.id);
+				assertEqual(final.version, committedA.version, "the stale writer must not replace writer A's version");
+				if (snapshotState) assert(deepEqual(snapshotState.call(harness, final), snapshotState.call(harness, committedA)), "the stale writer must not replace writer A's state");
+				assert(deepEqual(eventIds(await environment.committedOutboxEvents()), eventIds(outboxAfterA)), "a rejected stale flush must add no outbox records");
+			})
+		},
+		{
+			name: "rollback acknowledges nothing and commits neither state nor outbox",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				harness.mutate(aggregate);
+				const pending = [...aggregate.pendingEvents];
+				await captureRejection(environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+					throw new Error("rollback probe");
+				}));
+				assert(await environment.run(({ repository }) => repository.findById(aggregate.id)) === void 0, "a rolled-back add must leave no row");
+				assertEqual((await environment.committedOutboxEvents()).length, 0, "a rolled-back add must leave no outbox record");
+				assert(deepEqual(aggregate.pendingEvents, pending), "rollback must acknowledge none of the registered event batch");
+			})
+		},
+		{
+			name: "outbox failure rolls the already-flushed aggregate write back",
+			run: inEnvironment(async (environment) => {
+				const aggregate = harness.createAggregate();
+				harness.mutate(aggregate);
+				const pending = [...aggregate.pendingEvents];
+				environment.failNextOutboxWrite(/* @__PURE__ */ new Error("outbox failure probe"));
+				assert(await captureRejection(environment.run(async ({ repository }) => {
+					repository.add(aggregate);
+				})) !== void 0, "the outbox failure must reject");
+				assert(await environment.run(({ repository }) => repository.findById(aggregate.id)) === void 0, "state flush must roll back when the outbox write fails");
+				assertEqual((await environment.committedOutboxEvents()).length, 0, "failed outbox write must commit no envelope");
+				assert(deepEqual(aggregate.pendingEvents, pending), "failed commit must acknowledge none of the event batch");
+			})
+		},
+		{
+			name: "identity map returns one instance for repeated loads in one Unit of Work",
+			run: inEnvironment(async (environment) => {
+				const seeded = await seed(environment);
+				await environment.run(async ({ repository }) => {
+					const first = await repository.findById(seeded.id);
+					const second = await repository.findById(seeded.id);
+					assert(first !== void 0 && first === second, "repeated reads must return the same tracked aggregate instance");
+				});
+			})
+		},
+		{
+			name: "an unchanged explicit update is safe and emits no event",
+			run: inEnvironment(async (environment) => {
+				const seeded = await seed(environment);
+				const before = await environment.committedOutboxEvents();
+				await environment.run(async ({ repository }) => {
+					const aggregate = await load(repository, seeded.id);
+					repository.update(aggregate);
+				});
+				assert(deepEqual(eventIds(await environment.committedOutboxEvents()), eventIds(before)), "an unchanged update must not manufacture an outbox event");
+			})
+		}
+	];
+	tests.push(gatedContractTest({
+		capability: createAggregateWithId ? "insertsAreDuplicateChecked" : "createAggregateWithId",
+		satisfiedBy: Boolean(createAggregateWithId) && insertsAreDuplicateChecked
+	}, {
+		name: "duplicate add rejects and preserves the existing aggregate",
+		run: inEnvironment(async (environment) => {
+			assert(createAggregateWithId !== void 0, "capability gate");
+			const seeded = await seed(environment);
+			const duplicate = createAggregateWithId.call(harness, seeded.id);
+			harness.mutate(duplicate);
+			harness.mutate(duplicate);
+			const rejection = await captureRejection(environment.run(async ({ repository }) => {
+				repository.add(duplicate);
+			}));
+			assertChainContainsKitError(rejection, ["DUPLICATE_AGGREGATE"], `duplicate add must reject with (or wrap) DuplicateAggregateError; map your driver's unique-violation signal instead of a retryable conflict; got ${describeError(rejection)}`);
+			const final = await reload(environment, seeded.id);
+			assertEqual(final.version, seeded.version, "the existing row must be untouched by the rejected duplicate add; a duplicate check firing after the write clobbers it");
+			if (snapshotState) assert(deepEqual(snapshotState.call(harness, final), snapshotState.call(harness, seeded)), "the existing row's state must be untouched by the rejected duplicate add");
+		})
+	}));
+	tests.push(gatedContractTest({
+		capability: "mutateVersionOnly",
+		satisfiedBy: Boolean(mutateVersionOnly)
+	}, {
+		name: "version-only change still persists (skip-save must not desync the OCC baseline)",
+		run: inEnvironment(async (environment) => {
+			assert(mutateVersionOnly !== void 0, "capability gate");
+			const seeded = await seed(environment);
+			const outboxBefore = await environment.committedOutboxEvents();
+			await environment.run(async ({ repository }) => {
+				const aggregate = await load(repository, seeded.id);
+				mutateVersionOnly.call(harness, aggregate);
+				repository.update(aggregate);
+			});
+			assertEqual((await reload(environment, seeded.id)).version, seeded.version + 1, "a version-only change (empty change set, bumped version) must still be persisted; skipping it desyncs the persisted version and produces false concurrency conflicts later");
+			assert(deepEqual(eventIds(await environment.committedOutboxEvents()), eventIds(outboxBefore)), "state-only update must not create an outbox event");
+		})
+	}));
+	tests.push(gatedContractTest({
+		capability: "mutateChildCollection",
+		satisfiedBy: Boolean(mutateChildCollection)
+	}, {
+		name: "nested collection changes survive the adapter change-set projection",
+		run: inEnvironment(async (environment) => {
+			assert(mutateChildCollection !== void 0, "capability gate");
+			const seeded = await seed(environment);
+			await environment.run(async ({ repository }) => {
+				const aggregate = await load(repository, seeded.id);
+				mutateChildCollection.call(harness, aggregate);
+				repository.update(aggregate);
+			});
+			assertEqual((await reload(environment, seeded.id)).version, seeded.version + 1, "nested collection update must advance the persisted root version");
+		})
+	}));
+	tests.push(gatedContractTest({
+		capability: "removesAreSupported",
+		satisfiedBy: removesAreSupported
+	}, {
+		name: "remove tombstones the identity and physically removes at commit",
+		run: inEnvironment(async (environment) => {
+			const seeded = await seed(environment);
+			await environment.run(async ({ repository }) => {
+				assert(repository.remove !== void 0, "remove capability gate");
+				const aggregate = await load(repository, seeded.id);
+				repository.remove(aggregate);
+				assert(await repository.findById(seeded.id) === void 0, "a removed aggregate is immediately absent from the Unit of Work");
+			});
+			assert(await environment.run(({ repository }) => repository.findById(seeded.id)) === void 0, "remove must physically remove the aggregate after commit");
+		})
+	}));
+	tests.push(gatedContractTest({
+		capability: "removesAreVersionChecked",
+		satisfiedBy: removesAreVersionChecked
+	}, {
+		name: "stale remove conflicts and cannot delete a concurrent update",
+		run: inEnvironment(async (environment) => {
+			const seeded = await seed(environment);
+			let loaded;
+			const staleLoaded = new Promise((resolve) => {
+				loaded = resolve;
+			});
+			let release;
+			const mayRemove = new Promise((resolve) => {
+				release = resolve;
+			});
+			const staleRemove = environment.run(async ({ repository }) => {
+				assert(repository.remove !== void 0, "remove capability gate");
+				const stale = await load(repository, seeded.id);
+				loaded();
+				await mayRemove;
+				repository.remove(stale);
+			});
+			await staleLoaded;
+			await environment.run(async ({ repository }) => {
+				const current = await load(repository, seeded.id);
+				harness.mutate(current);
+				repository.update(current);
+			});
+			release();
+			const rejection = await captureRejection(staleRemove);
+			assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale remove must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
+			assert(await reload(environment, seeded.id) !== void 0, "stale remove must not delete the concurrent winner");
+		})
+	}));
+	return tests;
+}
+
+//#endregion
+//#region src/testing/snapshot-store-contract.ts
+const AT = /* @__PURE__ */ new Date("2026-01-05T10:20:30.456Z");
+function snapshot(version, state, schemaVersion) {
+	return {
+		state,
+		version,
+		snapshotAt: new Date(AT),
+		...schemaVersion === void 0 ? {} : { schemaVersion }
+	};
+}
+const id = (value) => value;
+const address = (aggregateType, aggregateId) => ({
+	aggregateType,
+	aggregateId: id(aggregateId)
+});
+/**
+* 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)`.
+*/
+function createSnapshotStoreContractTests(harness) {
+	const inEnv = bindContractEnvironment(() => harness.createEnvironment());
+	return [
+		{
+			name: "an aggregate without a snapshot loads undefined",
+			run: inEnv(async (env) => {
+				assertEqual(await env.store.load(address("Order", "o-1")), void 0, "a fresh store must report no snapshot; the repository falls back to full replay");
+			})
+		},
+		{
+			name: "save/load round-trips state, version, snapshotAt (millisecond fidelity), and schemaVersion",
+			run: inEnv(async (env) => {
+				const stored = snapshot(42, {
+					total: 7,
+					items: [{
+						sku: "a",
+						qty: 2
+					}],
+					note: "hi"
+				}, 3);
+				await env.store.save(address("Order", "o-1"), stored);
+				const loaded = await env.store.load(address("Order", "o-1"));
+				assert(loaded !== void 0, "the saved snapshot must load");
+				assert(deepEqual(loaded.state, stored.state), "the state must round-trip deep-equal as plain data");
+				assertEqual(loaded.version, 42, "the aggregate version must round-trip");
+				assert(loaded.snapshotAt instanceof Date, "snapshotAt must round-trip as a Date; rehydrate your storage format (ISO-8601 text, epoch ms) on load");
+				assertEqual(loaded.snapshotAt.getTime(), AT.getTime(), "snapshotAt must survive with millisecond precision (store ISO-8601 text or epoch ms)");
+				assertEqual(loaded.schemaVersion, 3, "schemaVersion must round-trip verbatim; the restore path compares it against the aggregate's declared schema");
+			})
+		},
+		{
+			name: "an absent schemaVersion round-trips as absent",
+			run: inEnv(async (env) => {
+				await env.store.save(address("Order", "o-1"), snapshot(1, {
+					total: 0,
+					items: []
+				}));
+				assertEqual((await env.store.load(address("Order", "o-1")))?.schemaVersion, void 0, "a snapshot stored without schemaVersion must not come back with a fabricated one; restore treats absence as schema 1");
+			})
+		},
+		{
+			name: "save replaces the previous snapshot: latest wins, no history",
+			run: inEnv(async (env) => {
+				await env.store.save(address("Order", "o-1"), snapshot(10, {
+					total: 1,
+					items: []
+				}));
+				await env.store.save(address("Order", "o-1"), snapshot(20, {
+					total: 2,
+					items: []
+				}));
+				const loaded = await env.store.load(address("Order", "o-1"));
+				assert(loaded?.version === 20 && loaded.state.total === 2, "load must return the latest snapshot only");
+			})
+		},
+		{
+			name: "snapshots are isolated per aggregate type AND per aggregate id",
+			run: inEnv(async (env) => {
+				await env.store.save(address("Order", "x-1"), snapshot(1, {
+					total: 1,
+					items: []
+				}));
+				await env.store.save(address("Invoice", "x-1"), snapshot(2, {
+					total: 2,
+					items: []
+				}));
+				await env.store.save(address("Order", "x-2"), snapshot(3, {
+					total: 3,
+					items: []
+				}));
+				const [orderX1, invoiceX1, orderX2] = await Promise.all([
+					env.store.load(address("Order", "x-1")),
+					env.store.load(address("Invoice", "x-1")),
+					env.store.load(address("Order", "x-2"))
+				]);
+				assert(orderX1?.version === 1 && invoiceX1?.version === 2 && orderX2?.version === 3, "the key is the (aggregateType, aggregateId) pair; neither half may bleed into the other");
+			})
+		},
+		{
+			name: "delete removes exactly the addressed snapshot and tolerates unknown keys",
+			run: inEnv(async (env) => {
+				await env.store.save(address("Order", "o-1"), snapshot(1, {
+					total: 1,
+					items: []
+				}));
+				await env.store.save(address("Order", "o-2"), snapshot(2, {
+					total: 2,
+					items: []
+				}));
+				await env.store.delete(address("Order", "o-1"));
+				await env.store.delete(address("Order", "never-saved"));
+				assertEqual(await env.store.load(address("Order", "o-1")), void 0, "the deleted snapshot must be gone (schema-migration fallback and erasure both rely on it)");
+				assertEqual((await env.store.load(address("Order", "o-2")))?.version, 2, "a sibling snapshot must survive the delete");
+			})
+		},
+		{
+			name: "loads are detached copies and saves capture the input: later mutations touch nothing",
+			run: inEnv(async (env) => {
+				const input = snapshot(5, {
+					total: 5,
+					items: [{
+						sku: "a",
+						qty: 1
+					}]
+				});
+				await env.store.save(address("Order", "o-1"), input);
+				input.state.items.push({
+					sku: "hacked",
+					qty: 99
+				});
+				const loaded = await env.store.load(address("Order", "o-1"));
+				assert(loaded !== void 0, "expected the saved snapshot");
+				assertEqual(loaded.state.items.length, 1, "save must capture the snapshot by value, not hold the caller's reference");
+				loaded.state.total = 999;
+				assertEqual((await env.store.load(address("Order", "o-1")))?.state.total, 5, "load must hand out a detached copy, never live internal state");
+			})
+		}
+	];
 }
-__name(createRepositoryContractTests, "createRepositoryContractTests");
 
-export { createEsRepositoryContractTests, createRepositoryContractTests };
-//# sourceMappingURL=testing.js.map
+//#endregion
+export { createCommandOutboxContractTests, createDeadlineStoreContractTests, createEsRepositoryContractTests, createEventStoreContractTests, createIdempotencyStoreContractTests, createOutboxContractTests, createProjectionCheckpointStoreContractTests, createRepositoryContractTests, createSnapshotStoreContractTests };
 //# sourceMappingURL=testing.js.map