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

package/dist/chunks/{ports.js → read-stream-pages.js}

@@ -1,4 +1,4 @@
-import { J as assertNoHostileOwnProtoKey } from "./kit-errors.js";
+import { C as InvalidEventStreamPageError, Y as assertNoHostileOwnProtoKey } from "./kit-errors.js";
 import { err, ok } from "@shirudo/result";
 
 //#region src/internal/structural/is-built-in.ts
@@ -91,9 +91,9 @@ const intrinsicConstructorSources = new Map([
 	"BigUint64Array"
 ].flatMap((name) => {
 	const intrinsic = Object.getOwnPropertyDescriptor(globalThis, name)?.value;
-	return typeof intrinsic === "function" ? [[name, functionToString.call(intrinsic)]] : [];
+	return typeof intrinsic === "function" ? [[name, /* @__PURE__ */ new Set([functionToString.call(intrinsic), `function ${name}() { [native code] }`])]] : [];
 }));
-const intrinsicConstructorSourceSet = new Set(intrinsicConstructorSources.values());
+const intrinsicConstructorSourceSet = new Set([...intrinsicConstructorSources.values()].flatMap((sources) => [...sources]));
 const ERROR_INTRINSIC_NAMES = [
 	"Error",
 	"EvalError",
@@ -114,13 +114,13 @@ function isIntrinsicConstructorPrototype(prototype, expectedName) {
 	} 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 expectedSources = expectedName === void 0 ? void 0 : intrinsicConstructorSources.get(expectedName);
+	if (expectedSources !== void 0 && !expectedSources.has(candidateSource) || expectedSources === 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;
+	const intrinsicSources = intrinsicName === void 0 ? void 0 : intrinsicConstructorSources.get(intrinsicName);
+	return candidateName === intrinsicName && intrinsicSources !== void 0 && intrinsicSources.has(candidateSource) && Object.getOwnPropertyDescriptor(candidateConstructor, "prototype")?.value === prototype;
 }
 /**
 * Accepts an intrinsic prototype, optionally behind transparent
@@ -675,8 +675,8 @@ const DATE_MUTATORS = [
 	"setYear"
 ];
 const mutationThrowers = /* @__PURE__ */ new Map();
-const mapEntries = Map.prototype.entries;
-const setValues = Set.prototype.values;
+const mapEntries$1 = Map.prototype.entries;
+const setValues$1 = Set.prototype.values;
 function mutationThrower(typeName, method) {
 	const key = `${typeName}.${method}`;
 	let thrower = mutationThrowers.get(key);
@@ -880,7 +880,7 @@ function cloneForVo(value, visited) {
 		if (tag === "[object Map]") {
 			const clone = /* @__PURE__ */ new Map();
 			visited.set(obj, clone);
-			for (const [key, entry] of mapEntries.call(obj)) {
+			for (const [key, entry] of mapEntries$1.call(obj)) {
 				if (!isPrimitiveValue(key)) throw new TypeError("vo() Map keys must be primitive values to preserve value equality");
 				clone.set(key, cloneForVo(entry, visited));
 			}
@@ -889,7 +889,7 @@ function cloneForVo(value, visited) {
 		if (tag === "[object Set]") {
 			const clone = /* @__PURE__ */ new Set();
 			visited.set(obj, clone);
-			for (const member of setValues.call(obj)) {
+			for (const member of setValues$1.call(obj)) {
 				if (!isPrimitiveValue(member)) throw new TypeError("vo() Set members must be primitive values to preserve value equality");
 				clone.add(member);
 			}
@@ -1247,6 +1247,202 @@ function hasCooperativeBrand(value, brand) {
 	}
 }
 
+//#endregion
+//#region src/internal/structural/detach-state.ts
+/**
+* Returns a copy of `state` that shares no object with the original.
+* Throws a `TypeError` that names the path when the graph carries a value
+* a structured clone would lose or silently degrade. A class instance, a
+* subclass of a built-in included, loses the methods on its prototype. A
+* symbol-keyed, non-enumerable, or accessor property and an expando on a
+* built-in are dropped. A function or a symbol value throws a raw
+* `DataCloneError`. An Error, a Promise, a WeakMap, or a WeakSet cannot be
+* detached at all. A SharedArrayBuffer and a view over one keep sharing
+* their memory. A Proxy fails in the walk or in the clone; a failure in
+* the clone is rethrown as a `TypeError` with the cause.
+*
+* The walk reads the graph through property descriptors and walks a Map
+* or a Set with the built-in iteration, so no accessor and no own iterator
+* of the state runs. A Proxy runs its traps during the walk. A trap can
+* change the graph, and an accessor that a trap adds runs during the
+* clone. A second walk checks the clone, so a value that a trap swapped in
+* and the content of a built-in whose prototype was replaced are rejected
+* too. The walks also count the data properties of records and arrays. A
+* copy with another count throws, because a built-in whose prototype was
+* replaced loses its own properties in the copy. `subject` names the state
+* in the messages.
+*
+* Plain objects (from any realm), arrays, Dates, Maps, Sets, bigints, and
+* typed arrays pass. A RegExp passes: pattern and flags survive the clone,
+* and `lastIndex` restores as 0. The scan state of a global or sticky
+* pattern is not domain data. A non-enumerable property on a built-in
+* passes: it is the built-in's own machinery (`lastIndex`), not data. A
+* non-enumerable symbol key passes anywhere: it is metadata by convention.
+*
+* The concrete entity uses it for a detached read DTO of a plain-data
+* state. The snapshot model uses it for the captured DTO and the restored
+* state. A state that carries a class-based child is mapped to plain data
+* first, in the entity or in the model.
+*/
+function detachState(state, subject = "detachState: state") {
+	return detach(state, subject, "clone");
+}
+/**
+* {@link detachState} that also rejects what `deepFreeze` cannot make
+* immutable: binary data (a typed array, a DataView, an ArrayBuffer, or a
+* SharedArrayBuffer) and a RegExp. The walk rejects such a value at its
+* tag, before it reads the indices of a typed array. Kit modules only.
+*/
+function detachFreezableState(state, subject) {
+	return detach(state, subject, "freeze");
+}
+/**
+* Throws the `TypeError` of {@link detachFreezableState} and copies
+* nothing. A caller that has a clone already checks it with this, so the
+* rule is the same. Kit modules only.
+*/
+function assertFreezableState(state, subject) {
+	assertDetachable(state, "", {
+		seen: /* @__PURE__ */ new WeakSet(),
+		subject,
+		rule: "freeze",
+		dataProperties: 0
+	});
+}
+function detach(state, subject, rule) {
+	const original = {
+		seen: /* @__PURE__ */ new WeakSet(),
+		subject,
+		rule,
+		dataProperties: 0
+	};
+	assertDetachable(state, "", original);
+	let copy;
+	try {
+		copy = structuredClone(state);
+	} catch (cause) {
+		throw new TypeError(`${subject} holds a Proxy or a host object that cannot be cloned; map it to plain data`, { cause });
+	}
+	const copied = {
+		seen: /* @__PURE__ */ new WeakSet(),
+		subject,
+		rule,
+		dataProperties: 0
+	};
+	assertDetachable(copy, "", copied);
+	if (copied.dataProperties !== original.dataProperties) throw new TypeError(`${subject} changed in the copy: the state has ${original.dataProperties} data properties and the copy has ${copied.dataProperties}; a built-in whose prototype was replaced loses its own properties in the copy, and a Proxy trap can change the graph; map it to plain data`);
+	return copy;
+}
+const INDEX_KEY = /^(0|[1-9]\d*)$/;
+const BINARY_DATA_TAGS = /* @__PURE__ */ new Set([
+	"[object TypedArray]",
+	"[object DataView]",
+	"[object ArrayBuffer]",
+	"[object SharedArrayBuffer]"
+]);
+const REGEXP_TAG = "[object RegExp]";
+const mapEntries = Map.prototype.entries;
+const setValues = Set.prototype.values;
+function assertDetachable(value, path, walk) {
+	if (typeof value === "function") throw new TypeError(`${walk.subject}${path} is a function; map it to plain data`);
+	if (typeof value === "symbol") throw new TypeError(`${walk.subject}${path} is a symbol; map it to plain data`);
+	if (value === null || typeof value !== "object") return;
+	const object = value;
+	if (walk.seen.has(object)) return;
+	walk.seen.add(object);
+	if (Array.isArray(object)) {
+		if (!hasIntrinsicPrototypeChain(object, "Array")) throwClassInstance(object, path, walk.subject);
+		assertOwnPropertiesDetachable(object, path, walk, "array");
+		return;
+	}
+	const tag = builtInTagWithoutInvokingAccessors(object);
+	if (tag !== void 0) {
+		if (walk.rule === "freeze") assertFreezable(tag, path, walk.subject);
+		if (!hasIntrinsicPrototypeChain(object)) throwClassInstance(object, path, walk.subject);
+		if (tag === "[object Map]") {
+			let index = 0;
+			for (const [key, entry] of mapEntries.call(object)) {
+				assertDetachable(key, `${path}<map key #${index}>`, walk);
+				assertDetachable(entry, `${path}<map value #${index}>`, walk);
+				index++;
+			}
+		} else if (tag === "[object Set]") {
+			let index = 0;
+			for (const member of setValues.call(object)) {
+				assertDetachable(member, `${path}<set member #${index}>`, walk);
+				index++;
+			}
+		} else if (tag === "[object Promise]" || tag === "[object WeakMap]" || tag === "[object WeakSet]") throw new TypeError(`${walk.subject}${path} is a ${tag.slice(8, -1)} and cannot be detached`);
+		else if (tag === "[object Error]") throw new TypeError(`${walk.subject}${path} is an Error; map it to plain data`);
+		else if (sharesMemory(object, tag)) throw new TypeError(`${walk.subject}${path} is backed by a SharedArrayBuffer and the copy would share its memory; map it to plain data`);
+		assertOwnPropertiesDetachable(object, path, walk, "built-in");
+		return;
+	}
+	const prototype = Object.getPrototypeOf(object);
+	if (!(prototype === null || isIntrinsicConstructorPrototype(prototype, "Object") && Object.getPrototypeOf(prototype) === null)) throwClassInstance(object, path, walk.subject);
+	assertOwnPropertiesDetachable(object, path, walk, "record");
+}
+/**
+* Audits the own properties the clone would copy or drop. The clone keeps
+* the enumerable own keys of a record and of an array, expandos included,
+* and drops every own key of another built-in. `length` on an array and
+* the non-enumerable keys of a built-in (`lastIndex`) are its own
+* machinery, not data. Index keys of a typed array or a boxed String are
+* its content and pass as such.
+*/
+function assertOwnPropertiesDetachable(object, path, walk, kind) {
+	for (const key of Reflect.ownKeys(object)) {
+		const descriptor = Object.getOwnPropertyDescriptor(object, key);
+		if (descriptor === void 0) continue;
+		if (typeof key === "symbol") {
+			if (!descriptor.enumerable) continue;
+			throw new TypeError(`${walk.subject}${path} has a symbol-keyed property; map it to plain data`);
+		}
+		if (kind === "array" && key === "length") continue;
+		const isIndex = INDEX_KEY.test(key);
+		if (!descriptor.enumerable) {
+			if (kind === "built-in") continue;
+			throw new TypeError(`${walk.subject}${path}.${key} is not enumerable and the clone would drop it; map it to plain data`);
+		}
+		if (kind === "built-in" && isIndex) continue;
+		const memberPath = isIndex ? `${path}[${key}]` : `${path}.${key}`;
+		if (!("value" in descriptor)) throw new TypeError(`${walk.subject}${memberPath} is an accessor property; map it to plain data`);
+		if (kind === "built-in") throw new TypeError(`${walk.subject}${memberPath} is an expando on a ${constructorName(Object.getPrototypeOf(object)) ?? "built-in"} and the clone would drop it; map it to plain data`);
+		walk.dataProperties += 1;
+		assertDetachable(descriptor.value, memberPath, walk);
+	}
+}
+const typedArrayBuffer = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "buffer")?.get;
+const dataViewBuffer = Object.getOwnPropertyDescriptor(DataView.prototype, "buffer")?.get;
+function sharesMemory(object, tag) {
+	if (tag === "[object SharedArrayBuffer]") return true;
+	if (tag === "[object TypedArray]") return isSharedArrayBuffer(typedArrayBuffer.call(object));
+	if (tag === "[object DataView]") return isSharedArrayBuffer(dataViewBuffer.call(object));
+	return false;
+}
+function isSharedArrayBuffer(buffer) {
+	return builtInTagWithoutInvokingAccessors(buffer) === "[object SharedArrayBuffer]";
+}
+function assertFreezable(tag, path, subject) {
+	if (BINARY_DATA_TAGS.has(tag)) throw new TypeError(`${subject}${path} is binary data; binary buffers (a typed array, a DataView, an ArrayBuffer, or a SharedArrayBuffer) stay mutable under freezing and JSON does not keep them; encode the data as a string, for example base64`);
+	if (tag === REGEXP_TAG) throw new TypeError(`${subject}${path} is a RegExp; a freeze cannot make it immutable, because compile() changes the pattern of a frozen RegExp before it throws, and a frozen global or sticky pattern throws on a match; keep its source and flags as strings`);
+}
+function throwClassInstance(object, path, subject) {
+	const name = constructorName(Object.getPrototypeOf(object)) ?? "anonymous class";
+	throw new TypeError(`${subject}${path} is a class instance (${name}); map it to plain data`);
+}
+/**
+* The name of the constructor of `prototype`, read through property
+* descriptors, so that no accessor runs.
+*/
+function constructorName(prototype) {
+	if (prototype === null) return void 0;
+	const owner = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
+	if (typeof owner !== "function") return void 0;
+	const name = Object.getOwnPropertyDescriptor(owner, "name")?.value;
+	return typeof name === "string" && name !== "" ? name : void 0;
+}
+
 //#endregion
 //#region src/domain/event/clock.ts
 /** Immutable library default captured by the default domain-event factory. */
@@ -1313,28 +1509,15 @@ const defaultEventIdFactory = () => crypto.randomUUID();
 * recordPendingEvents(order, domainEvents);
 * ```
 */
-/**
-* Fills the origin of a factory into options that name none.
-*
-* A call site that states its own source keeps it: an explicit fact about one
-* event outranks the default of the factory that mints it.
-*/
-function withFactorySource(options, source) {
-	const given = options ?? {};
-	if (source === void 0 || given.metadata?.source !== void 0) return given;
-	return {
-		...given,
-		metadata: {
-			...given.metadata,
-			source
-		}
-	};
-}
 function createDomainEventFactory(options = {}) {
+	return buildDomainEventFactory(options, "DomainEventFactory.create");
+}
+/** `createOperation` is the name that the errors of `create` give. */
+function buildDomainEventFactory(options, createOperation) {
 	const eventIdFactory = options.eventIdFactory ?? defaultEventIdFactory;
 	const clock = options.clock ?? defaultClockFactory;
 	const { source } = options;
-	const create = ((type, payload, createOptions) => mintDomainEvent(type, payload, withFactorySource(createOptions, source), eventIdFactory, clock));
+	const create = ((type, payload, createOptions) => mintDomainEvent(type, payload, createOptions, eventIdFactory, clock, createOperation, source));
 	const createStamp = (stampOptions = {}) => {
 		const explicitOccurredAt = stampOptions.occurredAt === void 0 ? void 0 : copyValidEventDate(stampOptions.occurredAt);
 		if (stampOptions.eventId !== void 0) assertNonBlankEventField(stampOptions.eventId, "eventId", "EVENT_ID_INVALID");
@@ -1343,7 +1526,7 @@ function createDomainEventFactory(options = {}) {
 		const stamp = {
 			eventId,
 			occurredAt: explicitOccurredAt ?? readEventClock(clock),
-			metadata: cloneOwnedEventData(withFactorySource(stampOptions, source).metadata, "metadata")
+			metadata: ownedEventMetadata(stampOptions.metadata, "DomainEventFactory.createStamp", source)
 		};
 		const owned = deepFreeze(stamp);
 		FACTORY_OWNED_EVENT_STAMPS.add(owned);
@@ -1360,7 +1543,7 @@ function createDomainEventFactory(options = {}) {
 * {@link createDomainEvent}. It cannot be reconfigured; construct an instance
 * with {@link createDomainEventFactory} for custom policy.
 */
-const defaultDomainEventFactory = createDomainEventFactory();
+const defaultDomainEventFactory = buildDomainEventFactory({}, "createDomainEvent");
 /**
 * Creates a domain event with default values.
 * Sets occurredAt to current date and schemaVersion to 1 if not provided.
@@ -1371,7 +1554,10 @@ const defaultDomainEventFactory = createDomainEventFactory();
 * event (same contract as `vo()`). The clone follows the plain-data event
 * contract via `structuredClone`: functions, Promise, and WeakMap/WeakSet
 * values throw a `TypeError`; symbol-keyed properties are not carried
-* over.
+* over. The clone is then checked with the rule of the in-memory event
+* store: an `Error`, a host object such as a `File`, a binary buffer, and
+* shared memory throw a `TypeError`. A class instance or an accessor becomes
+* plain data in the clone.
 *
 * **For aggregate-internal events, prefer `this.createEvent(...)` on
 * `StateStoredAggregate` / `EventSourcedAggregate`.** That helper auto-injects
@@ -1435,12 +1621,20 @@ function isUncommittedDomainEvent(event) {
 	return UNCOMMITTED_EVENTS.has(event) || hasCooperativeBrand(event, UNCOMMITTED_BRAND);
 }
 function createUncommittedDomainEvent(type, payload, options) {
+	return mintUncommittedDomainEvent(type, payload, options, "createUncommittedDomainEvent");
+}
+/**
+* {@link createUncommittedDomainEvent} whose errors name `operation`, the
+* function that the caller called. Module-internal export; not part of the
+* package entries.
+*/
+function mintUncommittedDomainEvent(type, payload, options, operation) {
 	assertProducerOwnedEventFields(type, options);
 	const event = {
 		type,
 		aggregateId: options?.aggregateId,
 		aggregateType: options?.aggregateType,
-		payload: cloneOwnedEventData(payload, "payload"),
+		payload: cloneOwnedEventData(payload, "payload", operation),
 		schemaVersion: options?.schemaVersion ?? 1
 	};
 	stampUncommittedBrand(event);
@@ -1458,16 +1652,16 @@ function adoptUncommittedDomainEvent(copy) {
 /**
 * Attaches shell-owned recording data to an accepted aggregate decision.
 *
-* The decision supplies the domain type, payload, source address, and payload
-* schema version. The stamp supplies only event identity, recording time, and
-* trace metadata.
+* The decision supplies the domain type, payload, source aggregate
+* identity, and payload schema version. The stamp supplies only event
+* identity, recording time, and trace metadata.
 */
 function recordDomainEvent(event, stamp) {
 	if (!isUncommittedDomainEvent(event)) throw new TypeError("recordDomainEvent requires an event created by createUncommittedDomainEvent");
 	if (isFactoryOwnedDomainEventStamp(stamp)) return mintRecordedEvent(event, stamp.eventId, stamp.occurredAt, stamp.metadata);
 	assertNonBlankEventField(stamp.eventId, "eventId", "EVENT_ID_INVALID");
 	const occurredAt = deepFreeze(copyValidEventDate(stamp.occurredAt));
-	const metadata = cloneOwnedEventData(stamp.metadata, "metadata");
+	const metadata = ownedEventMetadata(stamp.metadata, "recordDomainEvent");
 	return mintRecordedEvent(event, stamp.eventId, occurredAt, metadata === void 0 ? void 0 : deepFreeze(metadata));
 }
 /**
@@ -1496,7 +1690,8 @@ function mintRecordedEvent(event, eventId, occurredAt, metadata) {
 }
 /**
 * Brands, freezes, and registers a kit-derived copy of a recorded event
-* (e.g. the address-stamped copy `apply()` creates) as recorded itself.
+* (e.g. the copy `apply()` stamps with the aggregate identity) as recorded
+* itself.
 * The copy shares the already-frozen payload/metadata of its source,
 * so the mint guarantee carries over. Stamping the cooperative brand
 * before freezing keeps the copy recognizable by another loaded kit
@@ -1515,7 +1710,7 @@ function createDomainEvent(type, payload, options) {
 function createDomainEventFromFacts(type, payload, options) {
 	if (options?.eventId === void 0) missingExplicitEventId();
 	if (options.occurredAt === void 0) missingExplicitOccurredAt();
-	return mintDomainEvent(type, payload, options, missingExplicitEventId, missingExplicitOccurredAt);
+	return mintDomainEvent(type, payload, options, missingExplicitEventId, missingExplicitOccurredAt, "createDomainEventFromFacts");
 }
 function missingExplicitEventId() {
 	throw new DomainEventValidationError("EVENT_ID_REQUIRED", "eventId", "createDomainEventFromFacts requires an explicit eventId");
@@ -1523,7 +1718,7 @@ function missingExplicitEventId() {
 function missingExplicitOccurredAt() {
 	throw new DomainEventValidationError("EVENT_OCCURRED_AT_REQUIRED", "occurredAt", "createDomainEventFromFacts requires an explicit occurredAt");
 }
-function mintDomainEvent(type, payload, options, eventIdFactory, clock) {
+function mintDomainEvent(type, payload, options, eventIdFactory, clock, operation, factorySource) {
 	assertProducerOwnedEventFields(type, options);
 	const eventId = options?.eventId ?? eventIdFactory();
 	assertNonBlankEventField(eventId, "eventId", "EVENT_ID_INVALID");
@@ -1534,10 +1729,10 @@ function mintDomainEvent(type, payload, options, eventIdFactory, clock) {
 		type,
 		aggregateId: options?.aggregateId,
 		aggregateType: options?.aggregateType,
-		payload: cloneOwnedEventData(payload, "payload"),
+		payload: cloneOwnedEventData(payload, "payload", operation),
 		occurredAt,
 		schemaVersion,
-		metadata: cloneOwnedEventData(options?.metadata, "metadata")
+		metadata: ownedEventMetadata(options?.metadata, operation, factorySource)
 	};
 	stampRecordedBrand(event);
 	const minted = deepFreeze(event);
@@ -1548,8 +1743,8 @@ function assertProducerOwnedEventFields(type, options) {
 	assertNonBlankEventField(type, "type", "EVENT_TYPE_INVALID");
 	const schemaVersion = options?.schemaVersion ?? 1;
 	if (!Number.isSafeInteger(schemaVersion) || typeof schemaVersion !== "number" || schemaVersion < 1) throw new DomainEventValidationError("EVENT_SCHEMA_VERSION_INVALID", "schemaVersion", "domain-event schemaVersion must be a safe integer greater than or equal to 1");
-	if (options?.aggregateId !== void 0) assertNonBlankEventField(options.aggregateId, "aggregateId", "EVENT_ADDRESS_INVALID");
-	if (options?.aggregateType !== void 0) assertNonBlankEventField(options.aggregateType, "aggregateType", "EVENT_ADDRESS_INVALID");
+	if (options?.aggregateId !== void 0) assertNonBlankEventField(options.aggregateId, "aggregateId", "EVENT_AGGREGATE_IDENTITY_INVALID");
+	if (options?.aggregateType !== void 0) assertNonBlankEventField(options.aggregateType, "aggregateType", "EVENT_AGGREGATE_IDENTITY_INVALID");
 }
 function assertNonBlankEventField(value, field, code) {
 	if (typeof value !== "string" || value.trim().length === 0) throw new DomainEventValidationError(code, field, `domain-event ${field} must be a non-blank string`);
@@ -1562,59 +1757,60 @@ function readEventClock(clock) {
 	return copyValidEventDate(clock());
 }
 /**
-* Deep-clones caller-supplied event data (payload, metadata) before the
-* event is frozen, so `createDomainEvent` never freezes or aliases the
-* caller's own object graph. Primitives pass through unchanged.
-*
-* Uses `structuredClone`, which matches the documented plain-data event
-* contract: functions, Promise, and WeakMap/WeakSet values throw a
-* descriptive `TypeError` (they are not data); symbol-keyed properties
-* are not carried over; a class instance would silently lose its
-* prototype, which the plain-data contract already rules out.
+* Copies the caller's metadata and checks the copy. Metadata is a plain
+* record or absent; a null from a JSON envelope would mint and then fail
+* every metadata read far from the producer. A factory origin fills
+* `source` only after the check, and a call site that names its own source
+* keeps it: an explicit fact about one event outranks the default of the
+* factory that mints it.
 */
-function cloneOwnedEventData(value, field) {
-	if (typeof value === "function") throw new TypeError(`createDomainEvent: ${field} must not be a function: domain events are plain data`);
-	if (value === null && field === "metadata") throw new TypeError("createDomainEvent: metadata must be an object or undefined; received null");
-	if (value === null || typeof value !== "object") return value;
-	assertNoHostileOwnProtoKey(value, field === "payload" ? "Event payload" : "Event metadata");
-	assertNoBinaryData(value, field);
-	try {
-		return structuredClone(value);
-	} catch (cause) {
-		throw new TypeError(`createDomainEvent: ${field} must be plain, structured-cloneable data (no functions, Promises, or WeakMap/WeakSet values): domain events are plain data`, { cause });
+function ownedEventMetadata(metadata, operation, factorySource) {
+	if (metadata === void 0) return factorySource === void 0 ? void 0 : { source: factorySource };
+	const owned = cloneOwnedEventData(metadata, "metadata", operation);
+	if (!isPlainRecordCopy(owned)) {
+		const received = typeof owned === "object" ? owned === null ? "null" : Object.prototype.toString.call(owned) : `a ${typeof owned}`;
+		throw new TypeError(`${operation}: metadata must be an object or undefined, and a plain record; received ${received}`);
 	}
+	const record = owned;
+	if (factorySource === void 0 || record.source !== void 0) return record;
+	return {
+		...record,
+		source: factorySource
+	};
 }
-function isBinaryData(value) {
-	return ArrayBuffer.isView(value) || value instanceof ArrayBuffer || typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
+/**
+* True for a structured-clone copy of a plain record. A runtime such as
+* Vercel Edge returns the copy with the `Object.prototype` of another realm,
+* so the check compares the source text of the constructor, not the
+* prototype object.
+*/
+function isPlainRecordCopy(copy) {
+	if (typeof copy !== "object" || copy === null) return false;
+	const prototype = Object.getPrototypeOf(copy);
+	return prototype !== null && isIntrinsicConstructorPrototype(prototype, "Object") && Object.getPrototypeOf(prototype) === null;
 }
 /**
-* Walks caller-supplied event data and rejects binary buffers anywhere
-* in the graph (TypedArray, DataView, ArrayBuffer, SharedArrayBuffer):
-* they are mutable by construction, so the deep-freeze that backs the
-* mint guarantee cannot cover them. Runs before the structured clone,
-* on the small plain-data graphs events are documented to carry.
+* Deep-clones caller-supplied event data (payload, metadata) before the
+* event is frozen, so a constructor never freezes or aliases the caller's
+* own object graph, and checks the clone with {@link assertFreezableState}.
+* A primitive needs no copy, but the check rejects a symbol. A class
+* instance or an accessor becomes plain data in the clone.
 */
-function assertNoBinaryData(value, field, visited = /* @__PURE__ */ new WeakSet()) {
-	if (value === null || typeof value !== "object") return;
-	if (isBinaryData(value)) throw new TypeError(`createDomainEvent: ${field} must not contain binary buffers (TypedArray, DataView, ArrayBuffer, SharedArrayBuffer): they stay mutable under freezing and do not survive JSON. Encode binary as a string (base64/hex) or store it outside the event.`);
-	if (visited.has(value)) return;
-	visited.add(value);
-	if (value instanceof Map) {
-		for (const [k, v] of value) {
-			assertNoBinaryData(k, field, visited);
-			assertNoBinaryData(v, field, visited);
-		}
-		return;
+function cloneOwnedEventData(value, field, operation) {
+	if (typeof value === "function") throw new TypeError(`${operation}: ${field} must not be a function: domain events are plain data`);
+	if (value === null || typeof value !== "object") {
+		assertFreezableState(value, `${operation}: ${field}`);
+		return value;
 	}
-	if (value instanceof Set) {
-		for (const v of value) assertNoBinaryData(v, field, visited);
-		return;
-	}
-	if (Array.isArray(value)) {
-		for (const v of value) assertNoBinaryData(v, field, visited);
-		return;
+	let clone;
+	try {
+		clone = structuredClone(value);
+	} catch (cause) {
+		throw new TypeError(`${operation}: ${field} cannot be copied, because structuredClone failed (the cause names the value); domain events are plain data`, { cause });
 	}
-	for (const key of Object.keys(value)) assertNoBinaryData(value[key], field, visited);
+	assertNoHostileOwnProtoKey(clone, `Event ${field} of ${operation}`);
+	assertFreezableState(clone, `${operation}: ${field}`);
+	return clone;
 }
 /**
 * Copies metadata from a source event to a new event.
@@ -1687,6 +1883,29 @@ function mergeMetadata(...metadataObjects) {
 function abortReason(signal, fallbackMessage) {
 	return signal.reason ?? new Error(fallbackMessage);
 }
+/**
+* Waits for `promise`, but REJECTS with the signal's reason as soon as the
+* signal fires. The promise keeps running; only the wait ends. The abort
+* listener goes away when the promise settles.
+*/
+function waitRejectingOnAbort(promise, signal, abortMessage) {
+	if (signal === void 0) return promise;
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) {
+			reject(abortReason(signal, abortMessage));
+			return;
+		}
+		const onAbort = () => reject(abortReason(signal, abortMessage));
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
 
 //#endregion
 //#region src/internal/validate.ts
@@ -1699,6 +1918,15 @@ function abortReason(signal, fallbackMessage) {
 function assertNonNegativeFinite(context, field, value) {
 	if (!Number.isFinite(value) || value < 0) throw new Error(`${context}: ${field} must be a non-negative finite number, got ${value}`);
 }
+/**
+* The largest delay that `setTimeout` honors. A larger delay does not wait
+* longer: the runtime fires the timer after about 1 ms.
+*/
+const MAX_TIMER_DELAY_MS = 2147483647;
+/** Guard for time options that a timer waits for, in milliseconds. */
+function assertTimerDelay(context, field, value) {
+	if (!Number.isFinite(value) || value < 0 || value > 2147483647) throw new RangeError(`${context}: ${field} must be a finite number of milliseconds from 0 to ${MAX_TIMER_DELAY_MS}, got ${value}`);
+}
 /** Guard for count options that must be a whole number of at least 1. */
 function assertPositiveInteger(context, field, value) {
 	if (!Number.isInteger(value) || value < 1) throw new Error(`${context}: ${field} must be an integer >= 1, got ${value}`);
@@ -1707,6 +1935,10 @@ function assertPositiveInteger(context, field, value) {
 function assertPositiveSafeInteger(context, field, value) {
 	if (!Number.isSafeInteger(value) || value < 1) throw new RangeError(`${context}: ${field} must be a positive safe integer, got ${value}`);
 }
+/** Guard for stream positions that must fit exact JS integers. */
+function assertNonNegativeSafeInteger(context, field, value) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${context}: ${field} must be a non-negative safe integer, got ${value}`);
+}
 
 //#endregion
 //#region src/internal/async/execution.ts
@@ -1741,11 +1973,12 @@ function ownerSignalOf(signal) {
 * enforce a native timeout no later than `context.deadlineAt`.
 */
 function runBoundedExecution(label, options, operation) {
-	if (options.deadlineAt === void 0) assertNonNegativeFinite(label, "timeoutMs", options.timeoutMs);
+	if (options.deadlineAt === void 0) assertTimerDelay(label, "timeoutMs", options.timeoutMs);
 	else assertNonNegativeFinite(label, "deadlineAt", options.deadlineAt);
 	const startedAt = Date.now();
 	const deadlineAt = options.deadlineAt ?? startedAt + options.timeoutMs;
 	const timeoutMs = Math.max(0, deadlineAt - startedAt);
+	if (options.deadlineAt !== void 0) assertTimerDelay(label, "the time until deadlineAt", timeoutMs);
 	const timeoutError = () => new DOMException(`${label} timed out after ${timeoutMs}ms`, "TimeoutError");
 	const controller = new AbortController();
 	const context = Object.freeze({
@@ -1811,5 +2044,211 @@ function isDispatchTrackingOutbox(outbox) {
 }
 
 //#endregion
-export { voWithValidation as A, hasCooperativeBrand as C, vo as D, deepFreeze as E, findPropertyDescriptor as F, hasIntrinsicPrototypeChain as I, isBuiltInObject as L, deepOmit as M, deepEqual as N, voEquals as O, builtInTagWithoutInvokingAccessors as P, isIntrinsicConstructorPrototype as R, SnapshotTimeValidationError as S, ValueObject as T, isRecordedDomainEvent as _, assertNonNegativeFinite as a, recordDomainEvent as b, abortReason as c, copyMetadata as d, createDomainEvent as f, defaultDomainEventFactory as g, createUncommittedDomainEvent as h, runBoundedExecution as i, deepEqualExcept as j, voEqualsExcept as k, adoptRecordedDomainEvent as l, createDomainEventFromFacts as m, DEFAULT_EXECUTION_TIMEOUT_MS as n, assertPositiveInteger as o, createDomainEventFactory as p, ownerSignalOf as r, assertPositiveSafeInteger as s, isDispatchTrackingOutbox as t, adoptUncommittedDomainEvent as u, isUncommittedDomainEvent as v, stampCooperativeBrand as w, DomainEventValidationError as x, mergeMetadata as y, isWeakMap as z };
-//# sourceMappingURL=ports.js.map
+//#region src/persistence/event-store/event-stream-page-guards.ts
+function assertValidHead(stream, lastVersion, fromVersion, targetVersion) {
+	if (Number.isSafeInteger(lastVersion) && lastVersion >= 1) return;
+	throw new InvalidEventStreamPageError({
+		identity: stream,
+		reason: "invalid_head",
+		fromVersion,
+		targetVersion,
+		lastVersion
+	});
+}
+function assertHeadNotBehindFirstPage(stream, lastVersion, firstPageLastVersion, fromVersion, targetVersion) {
+	if (lastVersion >= firstPageLastVersion) return;
+	throw new InvalidEventStreamPageError({
+		identity: stream,
+		reason: "head_regressed",
+		fromVersion,
+		targetVersion,
+		lastVersion,
+		firstPageLastVersion
+	});
+}
+function assertPageNotEmpty(stream, eventCount, fromVersion, targetVersion) {
+	if (eventCount > 0) return;
+	throw new InvalidEventStreamPageError({
+		identity: stream,
+		reason: "empty_page",
+		fromVersion,
+		targetVersion
+	});
+}
+function assertPageWithinWindow(stream, eventCount, fromVersion, targetVersion) {
+	if (eventCount <= targetVersion - fromVersion) return;
+	throw new InvalidEventStreamPageError({
+		identity: stream,
+		reason: "page_past_target",
+		fromVersion,
+		targetVersion,
+		eventCount
+	});
+}
+function assertPageWithinLimit(stream, eventCount, limit, fromVersion, targetVersion) {
+	if (eventCount <= limit) return;
+	throw new InvalidEventStreamPageError({
+		identity: stream,
+		reason: "page_over_limit",
+		fromVersion,
+		targetVersion,
+		eventCount,
+		limit
+	});
+}
+
+//#endregion
+//#region src/persistence/event-store/read-stream-pages.ts
+/**
+* Pins the target version of a replay window on an existing stream, or
+* reports the window as unreachable.
+*
+* The target version is `toVersion` when given, else `lastVersion`. The
+* window is unreachable when `fromVersion` lies beyond the target version,
+* or the target version lies beyond `lastVersion`. The call never clamps
+* such a window to the head, so a request for version 10 of a stream that
+* ends at 7 never loads the latest state by accident.
+*
+* This is the decision `readStreamPages` makes on its first page. An
+* adapter that pages on its own makes it with this call, then hands its
+* pages to `reconstituteAggregateFromStreamPages`. Values that are not safe
+* integers, a negative `fromVersion`, and a `toVersion` or `lastVersion`
+* below 1 reject with `RangeError`: an existing stream holds at least one
+* event, and no replay can end at version 0.
+*/
+function pinTargetVersion(options) {
+	assertNonNegativeSafeInteger("pinTargetVersion", "fromVersion", options.fromVersion);
+	if (options.toVersion !== void 0) assertPositiveSafeInteger("pinTargetVersion", "toVersion", options.toVersion);
+	assertPositiveSafeInteger("pinTargetVersion", "lastVersion", options.lastVersion);
+	return decideTargetVersion(options);
+}
+function decideTargetVersion(window) {
+	const targetVersion = window.toVersion ?? window.lastVersion;
+	if (window.fromVersion > targetVersion || targetVersion > window.lastVersion) return { reachable: false };
+	return {
+		reachable: true,
+		targetVersion
+	};
+}
+/**
+* Reads one stream in bounded pages up to a pinned target version.
+*
+* The call reads the first page. That page decides existence and reports
+* the head. The call then makes the window decision of
+* {@link pinTargetVersion}: the target version is `toVersion` when given,
+* else the head, and a window outside the stream is unreachable.
+*
+* The first iteration of `pages` yields the first page that the call read
+* and then reads the continuation pages, one page at a time. Every later
+* iteration reads all pages from the store again, so no two iterations
+* share an event object. Each of these reads passes the target version as
+* `toVersion` and starts after the events that the earlier pages
+* returned. Streams are append-only, so an iteration yields one stable
+* prefix even when another writer appends during the replay.
+*
+* The call checks every page against the `readStream` contract and throws
+* {@link InvalidEventStreamPageError} for a page that breaks it: a head
+* that is not a safe integer of at least 1, an empty page while events
+* remain in the window, a page with more events than its window has left
+* or than `limit`, and a continuation page that reports the stream absent
+* or a head below the head of the first page.
+*
+* Invalid options reject with `RangeError` before any page is read:
+* `limit` and `toVersion` must be positive safe integers, `fromVersion` a
+* non-negative one. The call passes `signal` to every page read, and it
+* checks the signal before each page read as well. An aborted signal
+* rejects with its `reason`.
+*/
+async function readStreamPages(reader, stream, options) {
+	assertPositiveSafeInteger("readStreamPages", "limit", options.limit);
+	const fromVersion = options.fromVersion ?? 0;
+	assertNonNegativeSafeInteger("readStreamPages", "fromVersion", fromVersion);
+	if (options.toVersion !== void 0) assertPositiveSafeInteger("readStreamPages", "toVersion", options.toVersion);
+	throwIfAborted(options.signal);
+	const identity = {
+		aggregateType: stream.aggregateType,
+		aggregateId: stream.aggregateId
+	};
+	const first = await reader.readStream(identity, {
+		fromVersion,
+		limit: options.limit,
+		...options.toVersion === void 0 ? {} : { toVersion: options.toVersion },
+		...options.signal === void 0 ? {} : { signal: options.signal }
+	});
+	if (!first.exists) return {
+		exists: false,
+		reachable: false
+	};
+	assertValidHead(identity, first.lastVersion, fromVersion);
+	const pinned = decideTargetVersion({
+		fromVersion,
+		toVersion: options.toVersion,
+		lastVersion: first.lastVersion
+	});
+	if (!pinned.reachable) return {
+		exists: true,
+		reachable: false,
+		fromVersion,
+		lastVersion: first.lastVersion
+	};
+	if (fromVersion < pinned.targetVersion) assertPageNotEmpty(identity, first.events.length, fromVersion, pinned.targetVersion);
+	assertPageWithinWindow(identity, first.events.length, fromVersion, pinned.targetVersion);
+	assertPageWithinLimit(identity, first.events.length, options.limit, fromVersion, pinned.targetVersion);
+	const window = {
+		stream: identity,
+		fromVersion,
+		firstPageLastVersion: first.lastVersion,
+		targetVersion: pinned.targetVersion,
+		limit: options.limit,
+		signal: options.signal
+	};
+	let unreadFirstPage = first.events;
+	return {
+		exists: true,
+		reachable: true,
+		stream: identity,
+		fromVersion,
+		targetVersion: pinned.targetVersion,
+		pages: { [Symbol.asyncIterator]: () => {
+			const firstPage = unreadFirstPage;
+			unreadFirstPage = void 0;
+			return readPinnedPages(reader, window, firstPage);
+		} }
+	};
+}
+async function* readPinnedPages(reader, window, firstPage) {
+	let cursor = window.fromVersion;
+	if (firstPage !== void 0) {
+		if (firstPage.length > 0) yield firstPage;
+		cursor += firstPage.length;
+	}
+	while (cursor < window.targetVersion) {
+		throwIfAborted(window.signal);
+		const page = await reader.readStream(window.stream, {
+			fromVersion: cursor,
+			toVersion: window.targetVersion,
+			limit: window.limit,
+			...window.signal === void 0 ? {} : { signal: window.signal }
+		});
+		if (!page.exists) throw new InvalidEventStreamPageError({
+			identity: window.stream,
+			reason: "stream_vanished",
+			fromVersion: cursor,
+			targetVersion: window.targetVersion
+		});
+		assertValidHead(window.stream, page.lastVersion, cursor, window.targetVersion);
+		assertHeadNotBehindFirstPage(window.stream, page.lastVersion, window.firstPageLastVersion, cursor, window.targetVersion);
+		assertPageNotEmpty(window.stream, page.events.length, cursor, window.targetVersion);
+		assertPageWithinWindow(window.stream, page.events.length, cursor, window.targetVersion);
+		assertPageWithinLimit(window.stream, page.events.length, window.limit, cursor, window.targetVersion);
+		yield page.events;
+		cursor += page.events.length;
+	}
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw abortReason(signal, "readStreamPages aborted");
+}
+
+//#endregion
+export { SnapshotTimeValidationError as A, voWithValidation as B, defaultDomainEventFactory as C, mintUncommittedDomainEvent as D, mergeMetadata as E, ValueObject as F, isBuiltInObject as G, deepOmit as H, deepFreeze as I, isIntrinsicConstructorPrototype as K, vo as L, detachState as M, hasCooperativeBrand as N, recordDomainEvent as O, stampCooperativeBrand as P, voEquals as R, createUncommittedDomainEvent as S, isUncommittedDomainEvent as T, deepEqual as U, deepEqualExcept as V, findPropertyDescriptor as W, adoptUncommittedDomainEvent as _, isDispatchTrackingOutbox as a, createDomainEventFactory as b, runBoundedExecution as c, assertPositiveInteger as d, assertPositiveSafeInteger as f, adoptRecordedDomainEvent as g, waitRejectingOnAbort as h, assertPageWithinWindow as i, detachFreezableState as j, DomainEventValidationError as k, MAX_TIMER_DELAY_MS as l, abortReason as m, readStreamPages as n, DEFAULT_EXECUTION_TIMEOUT_MS as o, assertTimerDelay as p, isWeakMap as q, assertPageNotEmpty as r, ownerSignalOf as s, pinTargetVersion as t, assertNonNegativeSafeInteger as u, copyMetadata as v, isRecordedDomainEvent as w, createDomainEventFromFacts as x, createDomainEvent as y, voEqualsExcept as z };
+//# sourceMappingURL=read-stream-pages.js.map