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

package/dist/testing.js

@@ -1,12 +1,7 @@
-import { N as deepEqual, _ as isRecordedDomainEvent, i as runBoundedExecution, t as isDispatchTrackingOutbox } from "./chunks/ports.js";
+import { I as deepFreeze, U as deepEqual, a as isDispatchTrackingOutbox, c as runBoundedExecution, f as assertPositiveSafeInteger, n as readStreamPages, w as isRecordedDomainEvent } from "./chunks/read-stream-pages.js";
 
 //#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
@@ -281,6 +276,25 @@ function assertChainContainsKitError(rejection, codes, message) {
 	throw new Error(`Contract violated: ${message}`);
 }
 /**
+* Asserts that the first `CONCURRENCY_CONFLICT` in the cause chain names the
+* write that failed. The unit of work sets the intent on every conflict that
+* leaves a flush, so an adapter that wraps the conflict keeps it.
+*/
+function assertChainConflictNamesIntent(rejection, intent, message) {
+	let observed = "no CONCURRENCY_CONFLICT";
+	walkCauseChain(rejection, (node) => {
+		if (!errorMatchesName(node, "CONCURRENCY_CONFLICT")) return false;
+		try {
+			observed = node.intent;
+		} catch {
+			observed = "an intent that cannot be read";
+		}
+		return true;
+	});
+	if (observed === intent) return;
+	throw new Error(`Contract violated: ${message}; got ${typeof observed === "string" ? observed : String(observed)}`);
+}
+/**
 * 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
@@ -353,13 +367,14 @@ function causeChainNames(error) {
 //#region src/testing/command-outbox-contract.ts
 function createCommandOutboxContractTests(harness) {
 	const inEnv = bindContractEnvironment(harness.createEnvironment);
-	const commit = (seed, commandSeeds = [seed]) => ({
+	const processSource = {
+		aggregateType: "CheckoutProcess",
+		aggregateId: "order-1"
+	};
+	const commit = (seed, commandSeeds = [seed], source = processSource) => ({
 		origin: {
 			eventId: `process-event-${seed}`,
-			source: {
-				aggregateType: "CheckoutProcess",
-				aggregateId: "order-1"
-			},
+			source,
 			position: {
 				aggregateVersion: seed,
 				commitSequence: 0,
@@ -551,6 +566,55 @@ function createCommandOutboxContractTests(harness) {
 				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");
 			})
+		},
+		{
+			name: "rejects a new commit of an ended source",
+			run: inEnv(async (env) => {
+				const otherProcess = {
+					aggregateType: "CheckoutProcess",
+					aggregateId: "order-2"
+				};
+				const otherType = {
+					aggregateType: "ShippingProcess",
+					aggregateId: "order-1"
+				};
+				await env.addCommitted([commit(1)]);
+				await env.addCommitted([commit(4, [4], otherType)]);
+				await env.endEventSourcesCommitted([processSource]);
+				const secondEnd = await captureRejection(env.endEventSourcesCommitted([processSource]));
+				assert(secondEnd === void 0, `ending a source twice must not be an error. Got: ${describeError(secondEnd)}`);
+				const rejection = await captureRejection(env.addCommitted([commit(2)]));
+				assert(rejection !== void 0, "a new commit of an ended source must reject");
+				for (const [seed, source] of [[3, otherProcess], [5, otherType]]) {
+					const siblingRejection = await captureRejection(env.addCommitted([commit(seed, [seed], source)]));
+					assert(siblingRejection === void 0, `ending one source must not end another with the same id or the same type. Got: ${describeError(siblingRejection)}`);
+				}
+				assert(deepEqual((await env.readAll()).map(({ origin }) => origin.eventId).sort(), [
+					"process-event-1",
+					"process-event-3",
+					"process-event-4",
+					"process-event-5"
+				]), "the rejected commit must leave no receipt");
+			})
+		},
+		{
+			name: "deduplicates an exact retry of a commit of an ended source",
+			run: inEnv(async (env) => {
+				const original = commit(1);
+				await env.addCommitted([original]);
+				await env.endEventSourcesCommitted([processSource]);
+				const rejection = await captureRejection(env.addCommitted([original]));
+				assert(rejection === void 0, `an exact retry must stay idempotent after its source ended. Got: ${describeError(rejection)}`);
+				assertEqual((await env.readAll()).length, 1, "the retry must not append another receipt");
+			})
+		},
+		{
+			name: "ending a source without a cursor leaves it open for its first commit",
+			run: inEnv(async (env) => {
+				await env.endEventSourcesCommitted([processSource]);
+				await env.addCommitted([commit(1)]);
+				assertEqual((await env.readAll()).length, 1, "a source without a cursor has nothing to protect, so its first commit is accepted");
+			})
 		}
 	];
 	tests.push(gatedContractTest({
@@ -563,6 +627,18 @@ function createCommandOutboxContractTests(harness) {
 			await env.addRolledBack([commit(1)]);
 			assertEqual((await env.readAll()).length, 0, "a rolled-back transaction must persist no command receipt");
 		})
+	}), gatedContractTest({
+		capability: "providesRolledBackEnds",
+		satisfiedBy: harness.providesRolledBackEnds === true
+	}, {
+		name: "a rolled-back end leaves the source open",
+		run: inEnv(async (env) => {
+			if (!env.endEventSourcesRolledBack) throw new Error("Contract violated: harness declared providesRolledBackEnds but the environment lacks endEventSourcesRolledBack");
+			await env.addCommitted([commit(1)]);
+			await env.endEventSourcesRolledBack([processSource]);
+			await env.addCommitted([commit(2)]);
+			assertEqual((await env.readAll()).length, 2, "an end in a rolled-back transaction must not end the source");
+		})
 	}));
 	return tests;
 }
@@ -882,6 +958,7 @@ function createDeadlineStoreContractTests(harness) {
 					dueAt: at(T0),
 					payload: { kind: "ghost" }
 				})).catch(() => {});
+				await env.run(async () => {});
 				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");
 			})
 		}),
@@ -899,6 +976,7 @@ function createDeadlineStoreContractTests(harness) {
 					payload: { kind: "x" }
 				}));
 				await env.runRolledBack(() => env.store.cancel("s", "k")).catch(() => {});
+				await env.run(async () => {});
 				assertEqual((await env.store.due(at(T1), 10)).length, 1, "a cancel from a rolled-back transaction must not have removed the deadline");
 			})
 		})
@@ -975,6 +1053,7 @@ function createEsRepositoryContractTests(harness) {
 				writerB.release();
 				const rejection = await captureRejection(writerB.call);
 				assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale append must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
+				assertChainConflictNamesIntent(rejection, "update", "the stale append conflict must name the update in its intent");
 				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));
@@ -1545,11 +1624,11 @@ function createEventStoreContractTests(harness) {
 	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",
+			name: "absent 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");
+				const absent = await store.readStream({ ...firstKey }, fixtureRead);
+				assert(!absent.exists && absent.lastVersion === 0 && absent.events.length === 0, "an absent qualified stream must return the explicit absent state");
 			})
 		},
 		{
@@ -1576,7 +1655,7 @@ function createEventStoreContractTests(harness) {
 				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(firstStream.exists && firstStream.events.length === 1 && firstStream.events[0]?.eventId === firstEvent.eventId, "the first aggregate type must retain only its own event; key objects compare by value, not by object reference");
 				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");
 			})
 		},
@@ -1638,6 +1717,111 @@ function createEventStoreContractTests(harness) {
 				assert(atEnd.exists && atEnd.events.length === 0, "continuing at the pinned head must return an existing empty page");
 			})
 		},
+		{
+			name: "readStreamPages: the pages walk the pinned prefix and stop before a later append",
+			run: inEnv(async ({ store }) => {
+				const [firstKey, secondKey] = harness.createCollidingStreamKeys();
+				const events = [
+					1,
+					2,
+					3,
+					4,
+					5
+				].map((sequence) => harness.createEvent(firstKey, sequence));
+				await store.append(firstKey, events, { expectedVersion: 0 });
+				const absent = await readStreamPages(store, { ...secondKey }, { limit: 2 });
+				assert(!absent.exists, "readStreamPages must report an absent stream as absent");
+				const read = await readStreamPages(store, { ...firstKey }, { limit: 2 });
+				assert(read.reachable, "a full read of an existing stream must be reachable");
+				assert(read.targetVersion === events.length, "the first page must pin the actual stream head");
+				const collected = [];
+				for await (const page of read.pages) {
+					assert(page.length > 0 && page.length <= 2, "every page must hold at least one event and at most the limit");
+					collected.push(...page);
+					if (collected.length === page.length) await store.append(firstKey, [harness.createEvent(firstKey, 6)], { expectedVersion: events.length });
+				}
+				assert(hasSameEventIds(collected, events), "the pages must reproduce the pinned prefix in append order and leave the later append out");
+			})
+		},
+		{
+			name: "readStreamPages: toVersion below the head is the target version and the pages end there",
+			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 pointInTime = await readStreamPages(store, { ...firstKey }, {
+					toVersion: 3,
+					limit: 2
+				});
+				assert(pointInTime.reachable, "a target below the head must be reachable");
+				assert(pointInTime.targetVersion === 3, "the read must pin toVersion as the target version");
+				const collected = [];
+				for await (const page of pointInTime.pages) collected.push(...page);
+				assert(hasSameEventIds(collected, events.slice(0, 3)), "the pages must stop at toVersion");
+			})
+		},
+		{
+			name: "readStreamPages: toVersion beyond the head is unreachable and names the head",
+			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 beyondHead = await readStreamPages(store, { ...firstKey }, {
+					toVersion: 9,
+					limit: 2
+				});
+				assert(beyondHead.exists && !beyondHead.reachable && beyondHead.lastVersion === events.length, "a target beyond the head must be unreachable and name the actual head");
+			})
+		},
+		{
+			name: "readStreamPages: a cursor inside the stream reads only the events after it",
+			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 afterTwo = await readStreamPages(store, { ...firstKey }, {
+					fromVersion: 2,
+					limit: 2
+				});
+				assert(afterTwo.reachable && afterTwo.fromVersion === 2 && afterTwo.targetVersion === events.length, "a cursor inside the stream must be reachable and pin the head as the target version");
+				const collected = [];
+				for await (const page of afterTwo.pages) collected.push(...page);
+				assert(hasSameEventIds(collected, events.slice(2)), "the pages must hold only the events after the cursor");
+			})
+		},
+		{
+			name: "readStreamPages: a cursor beyond the head is unreachable and names the head",
+			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 beyondHead = await readStreamPages(store, { ...firstKey }, {
+					fromVersion: 9,
+					limit: 2
+				});
+				assert(beyondHead.exists && !beyondHead.reachable && beyondHead.fromVersion === 9 && beyondHead.lastVersion === events.length, "a cursor beyond the head must be unreachable and name the actual head");
+			})
+		},
 		{
 			name: "read options: invalid limits and stream positions fail loudly",
 			run: inEnv(async ({ store }) => {
@@ -1746,6 +1930,53 @@ function createEventStoreContractTests(harness) {
 				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: "page bounds: an existing stream reports a head of at least 1 and no page holds more events than its window",
+			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 });
+				for (const window of [
+					{ limit: 100 },
+					{ limit: 2 },
+					{
+						fromVersion: 2,
+						limit: 100
+					},
+					{
+						fromVersion: 3,
+						toVersion: 4,
+						limit: 100
+					},
+					{
+						fromVersion: 4,
+						toVersion: 99,
+						limit: 100
+					},
+					{
+						fromVersion: 99,
+						limit: 100
+					},
+					{
+						fromVersion: 3,
+						toVersion: 1,
+						limit: 100
+					}
+				]) {
+					const page = await store.readStream({ ...firstKey }, window);
+					assert(page.exists && page.lastVersion >= 1, "an existing stream must report a head of at least 1; report a stream without events as absent");
+					const windowEnd = Math.min(window.toVersion ?? page.lastVersion, page.lastVersion);
+					const room = Math.max(0, windowEnd - (window.fromVersion ?? 0));
+					assert(page.events.length <= room && page.events.length <= window.limit, `a page must hold at most the ${room} events of its window (${window.fromVersion ?? 0}, ${windowEnd}] and at most the limit ${window.limit}; got ${page.events.length}`);
+				}
+			})
+		},
 		{
 			name: "qualified fromVersion: slicing one type cannot observe a colliding raw id",
 			run: inEnv(async ({ store }) => {
@@ -1795,7 +2026,7 @@ function createEventStoreContractTests(harness) {
 			})
 		},
 		{
-			name: "OCC: an expectedVersion ahead of an unknown stream conflicts without creating it",
+			name: "OCC: an expectedVersion ahead of an absent stream conflicts without creating it",
 			run: inEnv(async ({ store }) => {
 				const [firstKey] = harness.createCollidingStreamKeys();
 				const rejection = await captureRejection(store.append(firstKey, [harness.createEvent(firstKey, 60)], { expectedVersion: 3 }));
@@ -2177,6 +2408,57 @@ function createOutboxContractTests(harness) {
 				assert(records.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: "rejects a new event of an ended event source",
+			run: inEnv(async (env) => {
+				const removed = {
+					aggregateType: "Order",
+					aggregateId: "1"
+				};
+				const sibling = {
+					aggregateType: "Payment",
+					aggregateId: "1"
+				};
+				const sameType = {
+					aggregateType: "Order",
+					aggregateId: "2"
+				};
+				const first = harness.createEvent(1);
+				const siblingFirst = harness.createEvent(2);
+				const siblingNext = harness.createEvent(4);
+				const sameTypeFirst = harness.createEvent(5);
+				const sameTypeNext = harness.createEvent(6);
+				await env.addCommitted(commit([first], 1, removed));
+				await env.addCommitted(commit([siblingFirst], 1, sibling));
+				await env.addCommitted(commit([sameTypeFirst], 1, sameType));
+				await env.endEventSourcesCommitted([removed]);
+				const secondEnd = await captureRejection(env.endEventSourcesCommitted([removed]));
+				assert(secondEnd === void 0, `ending an event source twice must not be an error. Got: ${describeError(secondEnd)}`);
+				const rejection = await captureRejection(env.addCommitted(commit([harness.createEvent(3)], 5, removed)));
+				assert(rejection !== void 0, "a new event of an ended event source must reject, also above its head");
+				for (const [event, source] of [[siblingNext, sibling], [sameTypeNext, sameType]]) {
+					const siblingRejection = await captureRejection(env.addCommitted(commit([event], 2, source)));
+					assert(siblingRejection === void 0, `ending one source must not end another with the same id or the same type. Got: ${describeError(siblingRejection)}`);
+				}
+				const records = await takeAndAck(env, 5);
+				assert(deepEqual(records.map(({ event }) => event.eventId), [
+					first.eventId,
+					siblingFirst.eventId,
+					sameTypeFirst.eventId,
+					siblingNext.eventId,
+					sameTypeNext.eventId
+				]), "the rejected event must leave no record, and ending one source must not end another with the same id or the same type");
+			})
+		},
+		{
+			name: "ending an event source without events leaves it open for its first event",
+			run: inEnv(async (env) => {
+				await env.endEventSourcesCommitted([defaultSource]);
+				await env.addCommitted(commit([harness.createEvent(1)], 1));
+				const [record] = await takeAndAck(env, 1);
+				assertEqual(record?.position.previousEventfulAggregateVersion, null, "a source without a head has no events to protect, so its first event starts a genesis head");
+			})
+		},
 		{
 			name: "getPending returns records in commit order, across separate committed adds",
 			run: inEnv(async (env) => {
@@ -2268,6 +2550,20 @@ function createOutboxContractTests(harness) {
 				const pending = await env.outbox.getPending(10);
 				assertEqual(pending.length, 1, "the same eventId must yield one record (unique-key dedupe)");
 			})
+		}),
+		gatedContractTest({
+			capability: "dedupesOnEventId",
+			satisfiedBy: harness.dedupesOnEventId === true
+		}, {
+			name: "an exact retry of a stored event of an ended source is deduped, not rejected",
+			run: inEnv(async (env) => {
+				const original = commit([harness.createEvent(1)]);
+				await env.addCommitted(original);
+				await env.endEventSourcesCommitted([defaultSource]);
+				const rejection = await captureRejection(env.addCommitted(original));
+				assert(rejection === void 0, `an exact retry of a stored event must stay idempotent after its source ended. Got: ${describeError(rejection)}`);
+				assertEqual((await env.outbox.getPending(10)).length, 1, "the retry must not add a second record");
+			})
 		})
 	];
 	tests.push(gatedContractTest({
@@ -2281,7 +2577,24 @@ function createOutboxContractTests(harness) {
 			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?.event.eventId, harness.createEvent(2).eventId, "the only pending record after a rolled-back add must be the committed event");
 			assertEqual(afterRollback?.position.previousEventfulAggregateVersion, null, "a rolled-back add must not advance the event-source head");
+			assertEqual((await env.outbox.getPending(10)).length, 0, "a rolled-back add must leave no record behind");
+		})
+	}));
+	tests.push(gatedContractTest({
+		capability: "providesRolledBackEnds",
+		satisfiedBy: harness.providesRolledBackEnds === true
+	}, {
+		name: "a rolled-back end leaves the event source open (transactional participation)",
+		run: inEnv(async (env) => {
+			if (!env.endEventSourcesRolledBack) throw new Error("Contract violated: harness declared providesRolledBackEnds but the environment lacks endEventSourcesRolledBack");
+			await env.addCommitted(commit([harness.createEvent(1)], 1));
+			await env.endEventSourcesRolledBack([defaultSource]);
+			const rejection = await captureRejection(env.addCommitted(commit([harness.createEvent(2)], 2)));
+			assert(rejection === void 0, `an end in a rolled-back transaction must not end the event source, but the next event of the source was rejected: ${describeError(rejection)}`);
+			const [, next] = await takeAndAck(env, 2);
+			assertEqual(next?.position.previousEventfulAggregateVersion, 1, "an end in a rolled-back transaction must not end the event source");
 		})
 	}));
 	const trackingEnabled = harness.failuresToDeadLetter !== void 0;
@@ -2415,32 +2728,32 @@ function createProjectionCheckpointStoreContractTests(harness) {
 				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 identity = 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);
+					return (await runConcurrently(Array.from({ length: contenders }, () => (ctx) => env.store.withCheckpointLocks(ctx, "order-list", [identity], async () => {
+						const stored = await env.store.load(ctx, "order-list", identity);
 						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}`));
+						await env.store.save(ctx, "order-list", identity, 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");
-				const stored = await env.run((ctx) => env.store.load(ctx, "order-list", address));
+				const stored = await env.run((ctx) => env.store.load(ctx, "order-list", identity));
 				assert(stored?.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");
-				const rejection = await captureRejection(env.run((ctx) => env.store.withCheckpointLocks(ctx, "order-list", [address], async () => {
+				const identity = order("o-rejected-lock");
+				const rejection = await captureRejection(env.run((ctx) => env.store.withCheckpointLocks(ctx, "order-list", [identity], async () => {
 					throw new Error("projection failed");
 				})));
 				assert(rejection !== 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 () => {
+				await env.run((ctx) => env.store.withCheckpointLocks(ctx, "order-list", [identity], async () => {
 					retried = true;
 				}));
 				assert(retried, "a rejected callback must release its key so redelivery can enter");
@@ -2516,7 +2829,7 @@ function createProjectionCheckpointStoreContractTests(harness) {
 			})
 		},
 		{
-			name: "address encoding is collision-free even with separator-like characters in either half",
+			name: "aggregate identity encoding is collision-free even with separator-like characters in either half",
 			run: inEnv(async (env) => {
 				const inType = {
 					aggregateType: "A\0B",
@@ -2531,7 +2844,7 @@ function createProjectionCheckpointStoreContractTests(harness) {
 					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");
+				assert(first?.position.aggregateVersion === 10 && second?.position.aggregateVersion === 1, "two aggregate identities that differ only in where a hostile separator sits must not share a watermark");
 			})
 		},
 		{
@@ -2574,6 +2887,185 @@ function createProjectionCheckpointStoreContractTests(harness) {
 	];
 }
 
+//#endregion
+//#region src/testing/replayable-stream-pages.ts
+/**
+* Builds a replayable stream read from an in-memory tail, for a test of the
+* code that consumes a read: a repository, or the replay over a fixed window.
+* It stands in for `readStreamPages` or an adapter that pages on its own,
+* and it tests neither. The tail is copied once and frozen deeply, and it
+* comes back in the same pages on every iteration. So a consumer that
+* changes an event in place fails at the write in its own test. An empty
+* tail yields no page, as `readStreamPages` does.
+*/
+function createReplayableStreamPages(stream, options) {
+	const limit = options.limit ?? Math.max(options.tail.length, 1);
+	assertPositiveSafeInteger("createReplayableStreamPages", "limit", limit);
+	const pages = sliceIntoPages(deepFreeze(structuredClone([...options.tail])), limit);
+	return {
+		stream,
+		fromVersion: options.fromVersion,
+		targetVersion: options.targetVersion,
+		pages: { [Symbol.asyncIterator]: () => yieldEachPage(pages) }
+	};
+}
+function sliceIntoPages(tail, limit) {
+	const pages = [];
+	for (let start = 0; start < tail.length; start += limit) pages.push(Object.freeze(tail.slice(start, start + limit)));
+	return pages;
+}
+async function* yieldEachPage(pages) {
+	yield* pages;
+}
+
+//#endregion
+//#region src/testing/replayable-stream-pages-contract.ts
+/**
+* Reusable proof of code that builds `ReplayableStreamPages` values:
+* `readStreamPages`, or an adapter that pages on its own.
+* The suite proves that the pages hold the events after the cursor
+* through the target version in append order, that no page is empty or
+* larger than the limit, that every iteration yields the same prefix, and
+* that an append during the iteration stays out. It also proves that an
+* absent stream and a window outside the stream give no replayable read.
+*/
+function createReplayableStreamPagesContractTests(harness) {
+	const inEnv = bindContractEnvironment(() => harness.createEnvironment());
+	const seed = async (env, count) => {
+		const stream = harness.createStream();
+		const events = Array.from({ length: count }, (_, index) => harness.createEvent(stream, index + 1));
+		await env.append(stream, events);
+		return {
+			stream,
+			events
+		};
+	};
+	const readOrFail = async (env, stream, window) => {
+		const read = await env.read({ ...stream }, window);
+		assert(read !== void 0, `a window (${window.fromVersion}, ${window.toVersion ?? "head"}] inside the stream must give a replayable read`);
+		return read;
+	};
+	const collectPages = async (read, limit) => {
+		const collected = [];
+		for await (const page of read.pages) {
+			assert(page.length > 0 && page.length <= limit, `every page must hold at least one event and at most the limit ${limit}; got ${page.length}`);
+			collected.push(...page);
+		}
+		return collected;
+	};
+	const sameEventIds = (actual, expected) => actual.length === expected.length && actual.every((event, index) => event.eventId === expected[index]?.eventId);
+	return [
+		{
+			name: "full read: the pages hold every event through the head in append order",
+			run: inEnv(async (env) => {
+				const { stream, events } = await seed(env, 5);
+				const read = await readOrFail(env, stream, {
+					fromVersion: 0,
+					limit: 2
+				});
+				assert(read.stream.aggregateType === stream.aggregateType && read.stream.aggregateId === stream.aggregateId, "the read must name the stream it reads");
+				assert(read.fromVersion === 0 && read.targetVersion === events.length, `a full read must run from 0 to the head ${events.length}; got (${read.fromVersion}, ${read.targetVersion}]`);
+				assert(sameEventIds(await collectPages(read, 2), events), "the pages must hold every event of the stream in append order");
+			})
+		},
+		{
+			name: "catch-up read: the pages start after fromVersion",
+			run: inEnv(async (env) => {
+				const { stream, events } = await seed(env, 5);
+				const read = await readOrFail(env, stream, {
+					fromVersion: 2,
+					limit: 2
+				});
+				assert(read.fromVersion === 2 && read.targetVersion === events.length, `a catch-up read must run from 2 to the head ${events.length}; got (${read.fromVersion}, ${read.targetVersion}]`);
+				assert(sameEventIds(await collectPages(read, 2), events.slice(2)), "the pages must hold only the events after fromVersion");
+			})
+		},
+		{
+			name: "point-in-time read: toVersion is the target version and the pages end there",
+			run: inEnv(async (env) => {
+				const { stream, events } = await seed(env, 5);
+				const read = await readOrFail(env, stream, {
+					fromVersion: 0,
+					toVersion: 3,
+					limit: 2
+				});
+				assert(read.targetVersion === 3, `a read to version 3 must pin 3 as the target version; got ${read.targetVersion}`);
+				assert(sameEventIds(await collectPages(read, 2), events.slice(0, 3)), "the pages must end at the target version");
+			})
+		},
+		{
+			name: "empty window: a read at the head yields no page",
+			run: inEnv(async (env) => {
+				const { stream, events } = await seed(env, 3);
+				const read = await readOrFail(env, stream, {
+					fromVersion: events.length,
+					limit: 2
+				});
+				assert(read.targetVersion === events.length, `a read at the head must pin the head ${events.length}; got ${read.targetVersion}`);
+				assert((await collectPages(read, 2)).length === 0, "a read at the head must yield no page, not an empty one");
+			})
+		},
+		{
+			name: "re-iteration: every iteration yields the same prefix",
+			run: inEnv(async (env) => {
+				const { stream, events } = await seed(env, 5);
+				const read = await readOrFail(env, stream, {
+					fromVersion: 0,
+					limit: 2
+				});
+				const first = await collectPages(read, 2);
+				const second = await collectPages(read, 2);
+				assert(sameEventIds(first, events) && sameEventIds(second, events), "a second iteration must start again from the first page and yield the same events");
+			})
+		},
+		{
+			name: "target as upper bound: an append during the iteration stays out of the pages",
+			run: inEnv(async (env) => {
+				const { stream, events } = await seed(env, 5);
+				const read = await readOrFail(env, stream, {
+					fromVersion: 0,
+					limit: 2
+				});
+				const collected = [];
+				for await (const page of read.pages) {
+					if (collected.length === 0) await env.append(stream, [harness.createEvent(stream, 6)]);
+					collected.push(...page);
+				}
+				assert(read.targetVersion === events.length, "an append after the read must not move the target version");
+				assert(sameEventIds(collected, events), "the pages must end at the target version and leave the later append out");
+			})
+		},
+		{
+			name: "no replayable read: an absent stream and a window outside the stream",
+			run: inEnv(async (env) => {
+				const { stream, events } = await seed(env, 3);
+				const absent = harness.createStream();
+				const outside = [
+					{
+						fromVersion: 0,
+						toVersion: events.length + 1,
+						limit: 2
+					},
+					{
+						fromVersion: events.length + 1,
+						limit: 2
+					},
+					{
+						fromVersion: 3,
+						toVersion: 2,
+						limit: 2
+					}
+				];
+				assert(await env.read({ ...absent }, {
+					fromVersion: 0,
+					limit: 2
+				}) === void 0, "an absent stream must give no replayable read");
+				for (const window of outside) assert(await env.read({ ...stream }, window) === void 0, `the window (${window.fromVersion}, ${window.toVersion ?? "head"}] lies outside a stream at ${events.length} and must give no replayable read`);
+			})
+		}
+	];
+}
+
 //#endregion
 //#region src/testing/repository-contract.ts
 /**
@@ -2679,6 +3171,7 @@ function createRepositoryContractTests(harness) {
 				writerB.release();
 				const rejection = await captureRejection(writerB.call);
 				assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale update must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
+				assertChainConflictNamesIntent(rejection, "update", "the stale update conflict must name the update in its intent");
 				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");
@@ -2835,6 +3328,7 @@ function createRepositoryContractTests(harness) {
 			staleRemove.release();
 			const rejection = await captureRejection(staleRemove.call);
 			assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale remove must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
+			assertChainConflictNamesIntent(rejection, "remove", "the stale remove conflict must name the remove in its intent");
 			assert(await reload(environment, seeded.id) !== void 0, "stale remove must not delete the concurrent winner");
 		})
 	})));
@@ -2853,7 +3347,7 @@ function snapshot(version, state, schemaVersion) {
 	};
 }
 const id = (value) => value;
-const address = (aggregateType, aggregateId) => ({
+const identity = (aggregateType, aggregateId) => ({
 	aggregateType,
 	aggregateId: id(aggregateId)
 });
@@ -2873,7 +3367,7 @@ function createSnapshotStoreContractTests(harness) {
 		{
 			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");
+				assertEqual(await env.store.load(identity("Order", "o-1")), void 0, "a fresh store must report no snapshot; the repository falls back to full replay");
 			})
 		},
 		{
@@ -2887,8 +3381,8 @@ function createSnapshotStoreContractTests(harness) {
 					}],
 					note: "hi"
 				}, 3);
-				await env.store.save(address("Order", "o-1"), stored);
-				const loaded = await env.store.load(address("Order", "o-1"));
+				await env.store.save(identity("Order", "o-1"), stored);
+				const loaded = await env.store.load(identity("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");
@@ -2900,67 +3394,67 @@ function createSnapshotStoreContractTests(harness) {
 		{
 			name: "an absent schemaVersion round-trips as absent",
 			run: inEnv(async (env) => {
-				await env.store.save(address("Order", "o-1"), snapshot(1, {
+				await env.store.save(identity("Order", "o-1"), snapshot(1, {
 					total: 0,
 					items: []
 				}));
-				const loaded = await env.store.load(address("Order", "o-1"));
+				const loaded = await env.store.load(identity("Order", "o-1"));
 				assertEqual(loaded?.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, {
+				await env.store.save(identity("Order", "o-1"), snapshot(10, {
 					total: 1,
 					items: []
 				}));
-				await env.store.save(address("Order", "o-1"), snapshot(20, {
+				await env.store.save(identity("Order", "o-1"), snapshot(20, {
 					total: 2,
 					items: []
 				}));
-				const loaded = await env.store.load(address("Order", "o-1"));
+				const loaded = await env.store.load(identity("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, {
+				await env.store.save(identity("Order", "x-1"), snapshot(1, {
 					total: 1,
 					items: []
 				}));
-				await env.store.save(address("Invoice", "x-1"), snapshot(2, {
+				await env.store.save(identity("Invoice", "x-1"), snapshot(2, {
 					total: 2,
 					items: []
 				}));
-				await env.store.save(address("Order", "x-2"), snapshot(3, {
+				await env.store.save(identity("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"))
+					env.store.load(identity("Order", "x-1")),
+					env.store.load(identity("Invoice", "x-1")),
+					env.store.load(identity("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",
+			name: "delete removes exactly the snapshot of the given aggregate identity and tolerates unknown keys",
 			run: inEnv(async (env) => {
-				await env.store.save(address("Order", "o-1"), snapshot(1, {
+				await env.store.save(identity("Order", "o-1"), snapshot(1, {
 					total: 1,
 					items: []
 				}));
-				await env.store.save(address("Order", "o-2"), snapshot(2, {
+				await env.store.save(identity("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");
+				await env.store.delete(identity("Order", "o-1"));
+				await env.store.delete(identity("Order", "never-saved"));
+				assertEqual(await env.store.load(identity("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(identity("Order", "o-2")))?.version, 2, "a sibling snapshot must survive the delete");
 			})
 		},
 		{
@@ -2973,16 +3467,16 @@ function createSnapshotStoreContractTests(harness) {
 						qty: 1
 					}]
 				});
-				await env.store.save(address("Order", "o-1"), input);
+				await env.store.save(identity("Order", "o-1"), input);
 				input.state.items.push({
 					sku: "hacked",
 					qty: 99
 				});
-				const loaded = await env.store.load(address("Order", "o-1"));
+				const loaded = await env.store.load(identity("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;
-				const reloaded = await env.store.load(address("Order", "o-1"));
+				const reloaded = await env.store.load(identity("Order", "o-1"));
 				assertEqual(reloaded?.state.total, 5, "load must hand out a detached copy, never live internal state");
 			})
 		}
@@ -2990,5 +3484,5 @@ function createSnapshotStoreContractTests(harness) {
 }
 
 //#endregion
-export { createCommandOutboxContractTests, createDeadlineStoreContractTests, createEsRepositoryContractTests, createEventBusContractTests, createEventStoreContractTests, createIdempotencyStoreContractTests, createOutboxContractTests, createProjectionCheckpointStoreContractTests, createRepositoryContractTests, createSnapshotStoreContractTests };
+export { createCommandOutboxContractTests, createDeadlineStoreContractTests, createEsRepositoryContractTests, createEventBusContractTests, createEventStoreContractTests, createIdempotencyStoreContractTests, createOutboxContractTests, createProjectionCheckpointStoreContractTests, createReplayableStreamPages, createReplayableStreamPagesContractTests, createRepositoryContractTests, createSnapshotStoreContractTests };
 //# sourceMappingURL=testing.js.map