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

package/dist/chunks/ports.js

@@ -0,0 +1,891 @@
+import { L as assertNoHostileOwnProtoKey } from "./errors.js";
+import { c as isIntrinsicConstructorPrototype, i as builtInTagWithoutInvokingAccessors, l as mutableBuiltInTagWithoutInvokingAccessors, o as hasIntrinsicPrototypeChain, r as deepEqual, t as deepEqualExcept } from "./deep-equal-except.js";
+import { err, ok } from "@shirudo/result";
+
+//#region src/value-object/value-object.ts
+/**
+* `Object.freeze` does not protect internal slots: a frozen Date still
+* accepts `setTime`, a frozen Map still accepts `set`. To make the
+* "deeply immutable" guarantee real, the mutator methods are shadowed
+* with own throwing functions BEFORE the freeze. The shadows are
+* non-enumerable, so they are invisible to `Object.keys`/spread (deep
+* equality is unaffected) and `structuredClone` drops them (a `vo()`
+* round-trip never sees them).
+*/
+const DATE_MUTATORS = [
+	"setTime",
+	"setMilliseconds",
+	"setUTCMilliseconds",
+	"setSeconds",
+	"setUTCSeconds",
+	"setMinutes",
+	"setUTCMinutes",
+	"setHours",
+	"setUTCHours",
+	"setDate",
+	"setUTCDate",
+	"setMonth",
+	"setUTCMonth",
+	"setFullYear",
+	"setUTCFullYear",
+	"setYear"
+];
+const mutationThrowers = /* @__PURE__ */ new Map();
+const mapEntries = Map.prototype.entries;
+const setValues = Set.prototype.values;
+function mutationThrower(typeName, method) {
+	const key = `${typeName}.${method}`;
+	let thrower = mutationThrowers.get(key);
+	if (!thrower) {
+		thrower = function throwFrozenMutation() {
+			throw new TypeError(`Cannot call ${method}() on a ${typeName} inside a deeply frozen value`);
+		};
+		mutationThrowers.set(key, thrower);
+	}
+	return thrower;
+}
+const shadowDescriptor = {
+	value: void 0,
+	writable: false,
+	enumerable: false,
+	configurable: false
+};
+function shadowMutators(obj, typeName, methods) {
+	if (!Object.isExtensible(obj)) return;
+	for (const method of methods) {
+		shadowDescriptor.value = mutationThrower(typeName, method);
+		Object.defineProperty(obj, method, shadowDescriptor);
+	}
+}
+/**
+* Deep freezes an object and all its nested properties recursively, then
+* returns it. Iterates both string-keyed and symbol-keyed own properties
+* so the freeze symmetry matches `deepEqual` (which also considers symbol
+* keys). Handles circular references by tracking visited objects.
+*
+* Note: `deepFreeze` mutates its argument in place; it sets `[[Frozen]]`
+* on the object you pass in. Callers that need to avoid touching the
+* input (e.g. `vo()`) should deep-clone first.
+*
+* Date/Map/Set keep internal-slot mutability under `Object.freeze`
+* (`setTime`, `set`, `add`, … still work on frozen instances), so their
+* mutator methods are shadowed with throwing own properties and Map/Set
+* contents are frozen recursively. The shadows are non-enumerable:
+* invisible to `Object.keys`, spread, `deepEqual`, and `structuredClone`.
+*
+* The shadowing is deny-by-enumeration: only the mutators known at
+* release time are blocked. If the runtime grows a NEW mutator (e.g. the
+* stage-3 `Map.prototype.getOrInsert` upsert proposal), it is not blocked
+* until the list is updated. Treat the mutator blocking as a guard rail,
+* not a security boundary.
+*
+* Limitation: ArrayBuffer views (TypedArrays, DataView) are passed through
+* unfrozen, because the spec forbids freezing a view with elements, and
+* freezing cannot protect the underlying buffer. Their contents remain mutable.
+*/
+function deepFreeze(obj, visited = /* @__PURE__ */ new WeakSet()) {
+	if (obj === null || typeof obj !== "object") return obj;
+	if (ArrayBuffer.isView(obj)) return obj;
+	if (visited.has(obj)) return obj;
+	visited.add(obj);
+	const mutableBuiltInTag = mutableBuiltInTagWithoutInvokingAccessors(obj);
+	if (mutableBuiltInTag !== void 0) {
+		if (mutableBuiltInTag === "[object Date]") shadowMutators(obj, "Date", DATE_MUTATORS);
+		else if (mutableBuiltInTag === "[object Map]") {
+			for (const [key, value] of obj) {
+				deepFreeze(key, visited);
+				deepFreeze(value, visited);
+			}
+			shadowMutators(obj, "Map", [
+				"set",
+				"delete",
+				"clear"
+			]);
+		} else if (mutableBuiltInTag === "[object Set]") {
+			for (const member of obj) deepFreeze(member, visited);
+			shadowMutators(obj, "Set", [
+				"add",
+				"delete",
+				"clear"
+			]);
+		}
+	}
+	const keys = Reflect.ownKeys(obj);
+	for (const key of keys) {
+		const value = obj[key];
+		if (value !== null && typeof value === "object") deepFreeze(value, visited);
+	}
+	return Object.freeze(obj);
+}
+/**
+* Deep clone used by `vo()` and the `ValueObject` constructor.
+*
+* Plain objects, arrays, and Map values are walked manually so
+* that symbol-keyed properties survive (which `structuredClone` silently
+* drops; they would otherwise be invisible to `voEquals`, whose
+* `deepEqual` DOES consider symbol keys) and shared references / cycles
+* keep their identity across Map boundaries. Function values throw,
+* preserving `vo()`'s documented data-not-behaviour gate. Built-ins without
+* immutable value semantics throw a descriptive `TypeError`. Custom class
+* instances and subclasses of built-ins are rejected because cloning them
+* without invoking their
+* constructor can silently lose private or non-enumerable state. Map keys
+* and Set members must be primitive because their equality is
+* identity-based and object identity cannot survive defensive cloning.
+* Accessor properties are rejected without invoking them. Admitted atomic
+* built-ins (Date, RegExp and primitive wrappers) delegate to
+* `structuredClone`, brand-verified so a `Symbol.toStringTag` spoofer is
+* walked as the plain object it is. `__proto__` own keys are copied as
+* inert data properties.
+*/
+function cloneForVo(value, visited) {
+	if (typeof value === "function") throw new TypeError("vo() does not accept function values: Value Objects are data, not behaviour");
+	if (value === null || typeof value !== "object") return value;
+	const obj = value;
+	if (ArrayBuffer.isView(obj)) throwUnsupportedValueSemantics(builtInTagWithoutInvokingAccessors(obj) ?? "[object ArrayBuffer view]");
+	if (visited.has(obj)) return visited.get(obj);
+	if (Array.isArray(obj)) {
+		if (!hasIntrinsicPrototypeChain(obj, "Array")) throwUnsupportedClassInstance();
+		const clone = new Array(obj.length);
+		visited.set(obj, clone);
+		for (const key of Reflect.ownKeys(obj)) {
+			if (key === "length") continue;
+			const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+			if (descriptor === void 0) continue;
+			if (!("value" in descriptor)) throwUnsupportedAccessorProperty();
+			if (typeof key === "string" && !descriptor.enumerable) continue;
+			descriptor.value = cloneForVo(descriptor.value, visited);
+			Object.defineProperty(clone, key, descriptor);
+		}
+		return clone;
+	}
+	const tag = builtInTagWithoutInvokingAccessors(obj);
+	if (tag !== void 0) {
+		if (!hasIntrinsicPrototypeChain(obj)) throwUnsupportedClassInstance();
+		if (tag === "[object Map]") {
+			const clone = /* @__PURE__ */ new Map();
+			visited.set(obj, clone);
+			for (const [key, entry] of mapEntries.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));
+			}
+			return clone;
+		}
+		if (tag === "[object Set]") {
+			const clone = /* @__PURE__ */ new Set();
+			visited.set(obj, clone);
+			for (const member of setValues.call(obj)) {
+				if (!isPrimitiveValue(member)) throw new TypeError("vo() Set members must be primitive values to preserve value equality");
+				clone.add(member);
+			}
+			return clone;
+		}
+		if (tag === "[object Promise]" || tag === "[object WeakMap]" || tag === "[object WeakSet]") throw new TypeError(`vo() cannot clone a ${tag.slice(8, -1)}: Value Objects are plain data`);
+		if (tag === "[object Error]" || tag === "[object ArrayBuffer]" || tag === "[object SharedArrayBuffer]") throwUnsupportedValueSemantics(tag);
+		if (tag === "[object RegExp]") {
+			const regExp = obj;
+			if (regExp.global || regExp.sticky) throw new TypeError("vo() cannot accept a global or sticky RegExp: its lastIndex is mutable scan state, not an immutable value");
+		}
+		const builtInClone = structuredClone(obj);
+		visited.set(obj, builtInClone);
+		return builtInClone;
+	}
+	const prototype = Object.getPrototypeOf(obj);
+	if (prototype !== null && (!isIntrinsicConstructorPrototype(prototype, "Object") || Object.getPrototypeOf(prototype) !== null)) throwUnsupportedClassInstance();
+	const clone = Object.create(prototype === null ? null : Object.prototype);
+	visited.set(obj, clone);
+	for (const key of Reflect.ownKeys(obj)) {
+		const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+		if (descriptor === void 0) continue;
+		if (!("value" in descriptor)) throwUnsupportedAccessorProperty();
+		if (typeof key === "string" && !descriptor.enumerable) continue;
+		Object.defineProperty(clone, key, {
+			value: cloneForVo(descriptor.value, visited),
+			writable: true,
+			enumerable: descriptor.enumerable,
+			configurable: true
+		});
+	}
+	return clone;
+}
+function throwUnsupportedClassInstance() {
+	throw new TypeError("vo() cannot clone custom class instances: Value Objects are plain data");
+}
+function throwUnsupportedAccessorProperty() {
+	throw new TypeError("vo() cannot clone accessor properties: Value Objects are plain data");
+}
+function throwUnsupportedValueSemantics(tag) {
+	const name = tag.startsWith("[object ") ? tag.slice(8, -1) : tag;
+	throw new TypeError(`vo() cannot accept ${name} values: Value Objects require immutable value semantics`);
+}
+function isPrimitiveValue(value) {
+	return value === null || typeof value !== "object" && typeof value !== "function";
+}
+/**
+* Creates a deeply immutable value object from the given data.
+*
+* The input is first deep-cloned, then the clone is frozen, so calling
+* `vo(input)` never freezes the caller's own object graph as a
+* side-effect. Mutating the input afterwards does not bleed into the VO.
+* Symbol-keyed properties are preserved (matching `voEquals`); function
+* values and custom class instances are rejected (Value Objects are plain
+* data, not behaviour-bearing object graphs). Inputs must be trusted and
+* Proxy-free: ECMAScript provides no portable way to identify a transparent
+* Proxy without potentially executing its traps, so `vo()` is not a sandbox
+* for hostile in-process objects. Built-ins that cannot provide immutable,
+* value-based semantics are rejected instead of weakening the VO contract.
+*
+* @example
+* ```typescript
+* const nested = { lat: 52.5, lng: 13.4 };
+* const address = vo({ street: "Main St", coordinates: nested });
+* address.coordinates.lat = 99; // ❌ Cannot assign to read-only property
+* nested.lat = 0;               // ✅ caller's input still mutable
+* ```
+*/
+function vo(t) {
+	return deepFreeze(cloneForVo(t, /* @__PURE__ */ new WeakMap()));
+}
+/**
+* Compares two value objects for equality based on their values.
+* Uses deep equality comparison that handles:
+* - Nested objects and arrays
+* - Primitives (including NaN)
+* - Dates, Maps, Sets, RegExp
+* - Symbol keys
+* - Circular references
+*
+* @param a - First value object
+* @param b - Second value object
+* @returns true if both objects have the same values, false otherwise
+*
+* @example
+* ```typescript
+* const money1 = vo({ amount: 100, currency: "USD" });
+* const money2 = vo({ amount: 100, currency: "USD" });
+* voEquals(money1, money2); // true
+*
+* const address1 = vo({
+*   street: "Main St",
+*   coordinates: { lat: 52.5, lng: 13.4 }
+* });
+* const address2 = vo({
+*   street: "Main St",
+*   coordinates: { lat: 52.5, lng: 13.4 }
+* });
+* voEquals(address1, address2); // true
+* ```
+*/
+function voEquals(a, b) {
+	return deepEqual(a, b);
+}
+/**
+* Compares two value objects for equality while ignoring specified keys.
+* Useful for comparing value objects that contain metadata or optional fields
+* that should not affect equality comparison.
+*
+* @param a - First value object
+* @param b - Second value object
+* @param options - Options specifying which keys to ignore during comparison
+* @returns true if both objects have the same values (after ignoring specified keys), false otherwise
+*
+* @example
+* ```typescript
+* // Value object with metadata
+* const address1 = vo({
+*   street: "Main St",
+*   city: "Berlin",
+*   metadata: { createdAt: "2024-01-01", updatedAt: "2024-01-02" }
+* });
+*
+* const address2 = vo({
+*   street: "Main St",
+*   city: "Berlin",
+*   metadata: { createdAt: "2024-01-01", updatedAt: "2024-01-03" }
+* });
+*
+* // Compare ignoring metadata timestamps
+* voEqualsExcept(address1, address2, {
+*   ignoreKeys: ["updatedAt"],
+*   ignoreKeyPredicate: (key, path) => path.includes("metadata")
+* }); // true
+*
+* // Compare ignoring all metadata
+* voEqualsExcept(address1, address2, {
+*   ignoreKeyPredicate: (key, path) => path.includes("metadata")
+* }); // true
+* ```
+*/
+function voEqualsExcept(a, b, options) {
+	return deepEqualExcept(a, b, options);
+}
+/**
+* Creates a value object with optional validation.
+* Returns a Result type instead of throwing an error.
+*
+* Note: the Result covers VALIDATION failures only. Non-data values and
+* built-ins without immutable value semantics still throw a
+* `TypeError` from `vo()`; they cannot occur in parsed JSON and signal
+* a programming error, not a validation failure.
+*
+* @param t - The data to convert into a value object
+* @param validate - Validation function that returns true if valid
+* @param errorMessage - Optional custom error message if validation fails
+* @returns Result containing the value object if valid, or an error message if validation fails
+*
+* @example
+* ```typescript
+* const result = voWithValidation(
+*   { amount: 100, currency: "USD" },
+*   (m) => m.amount >= 0 && m.currency.length === 3,
+*   "Invalid money: amount must be non-negative and currency must be 3 characters"
+* );
+*
+* if (result.ok) {
+*   console.log(result.value); // Use the value object
+* } else {
+*   console.error(result.error); // Handle validation error
+* }
+* ```
+*/
+function voWithValidation(t, validate, errorMessage) {
+	if (!validate(t)) return err(errorMessage ?? `Validation failed for value object: ${describeValue(t)}`);
+	return ok(vo(t));
+}
+/**
+* Best-effort rendering of a value for the default validation-failure
+* message. `JSON.stringify` throws for cyclic and BigInt-bearing values, and
+* the error path of a Result-returning function must never throw itself.
+*/
+function describeValue(value) {
+	try {
+		const json = JSON.stringify(value);
+		if (json !== void 0) return json;
+	} catch {}
+	return String(value);
+}
+/**
+* Abstract base class for creating Value Objects.
+* Value Objects are immutable and defined by their properties.
+*
+* @template T - The shape of the value object's properties
+*/
+var ValueObject = class {
+	props;
+	/**
+	* Creates a new ValueObject.
+	* The plain-data properties are deep-cloned and then deeply
+	* frozen, so the caller's own object graph is never frozen or mutated,
+	* and later mutation of the input does not bleed into the value object.
+	*
+	* @param props - The properties of the value object
+	* @example
+	* ```ts
+	* class Money extends ValueObject<{ amount: number; currency: string }> {
+	*   constructor(props: { amount: number; currency: string }) {
+	*     super(props);
+	*   }
+	*
+	*   protected validate(props: { amount: number; currency: string }): void {
+	*     if (props.amount < 0) throw new Error("Amount cannot be negative");
+	*   }
+	* }
+	* ```
+	*/
+	constructor(props) {
+		this.validate(props);
+		this.props = deepFreeze(cloneForVo(props, /* @__PURE__ */ new WeakMap()));
+	}
+	/**
+	* Optional validation hook that can be overridden by subclasses.
+	* Should throw an error if validation fails.
+	*
+	* @param props - The properties to validate
+	* @throws Error if validation fails
+	*/
+	validate(props) {}
+	/**
+	* Checks if this value object is equal to another.
+	* Uses deep equality comparison on the properties and checks for constructor equality.
+	*
+	* @param other - The other value object to compare
+	* @returns true if the properties are deeply equal and constructors match
+	*/
+	equals(other) {
+		if (other === null || other === void 0) return false;
+		if (this.constructor !== other.constructor) return false;
+		return deepEqual(this.props, other.props);
+	}
+	/**
+	* Creates a clone of the value object with optional property overrides.
+	*
+	* @param props - Optional properties to override
+	* @returns A new instance of the value object
+	*/
+	clone(props) {
+		const Constructor = this.constructor;
+		const merged = {
+			...this.props,
+			...props || {}
+		};
+		for (const key of Reflect.ownKeys(this.props)) {
+			const descriptor = Object.getOwnPropertyDescriptor(this.props, key);
+			if (descriptor === void 0 || descriptor.enumerable) continue;
+			if (props && Object.hasOwn(props, key)) continue;
+			Object.defineProperty(merged, key, {
+				value: this.props[key],
+				writable: true,
+				enumerable: false,
+				configurable: true
+			});
+		}
+		return new Constructor(merged);
+	}
+	/**
+	* Serializes the value object to its raw properties for JSON operations.
+	*
+	* @returns The raw properties object
+	*/
+	toJSON() {
+		return this.props;
+	}
+};
+
+//#endregion
+//#region src/aggregate/clock.ts
+/** Immutable library default captured by the default domain-event factory. */
+const defaultClockFactory = () => /* @__PURE__ */ new Date();
+/** Internal defensive event-clock read. */
+function readClock(factory) {
+	const reading = factory();
+	const value = reading instanceof Date ? reading.getTime() : NaN;
+	if (!Number.isFinite(value)) throw new TypeError("domain-event clock must return a valid Date");
+	return new Date(value);
+}
+
+//#endregion
+//#region src/aggregate/domain-event-errors.ts
+/**
+* Stable contract error for malformed domain-event data.
+*
+* It remains a `TypeError` for JavaScript callers while exposing a code and
+* field that do not depend on the wording of the human-readable message.
+*/
+var DomainEventValidationError = class extends TypeError {
+	code;
+	field;
+	name;
+	constructor(code, field, message) {
+		super(message);
+		this.code = code;
+		this.field = field;
+		this.name = code;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+var SnapshotTimeValidationError = class extends TypeError {
+	name = "SNAPSHOT_TIME_INVALID";
+	code = "SNAPSHOT_TIME_INVALID";
+	field = "snapshotAt";
+	constructor() {
+		super("snapshotAt must be a valid Date");
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+
+//#endregion
+//#region src/aggregate/domain-event.ts
+const defaultEventIdFactory = () => crypto.randomUUID();
+/**
+* Creates an immutable, instance-bound domain-event factory.
+*
+* The supplied functions are read once and captured by value. The returned
+* object is frozen, so another request, test, or library cannot replace its
+* policy. Its {@link DomainEventFactory.createStamp} method is the
+* application-shell bridge that records an accepted aggregate decision.
+* Passing the factory through `AggregateConfig`
+* enables the explicitly named convenience methods, whose defaults read time
+* and randomness.
+*
+* @example
+* ```ts
+* const domainEvents = createDomainEventFactory({
+*   eventIdFactory: () => uuidv7(),
+*   clock: () => new Date(),
+* });
+* order.confirm();
+* recordPendingEvents(order, domainEvents);
+* ```
+*/
+function createDomainEventFactory(options = {}) {
+	const eventIdFactory = options.eventIdFactory ?? defaultEventIdFactory;
+	const clock = options.clock ?? defaultClockFactory;
+	const create = ((type, payload, createOptions) => mintDomainEvent(type, payload, createOptions, eventIdFactory, clock));
+	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");
+		const eventId = stampOptions.eventId ?? eventIdFactory();
+		assertNonBlankEventField(eventId, "eventId", "EVENT_ID_INVALID");
+		const owned = deepFreeze({
+			eventId,
+			occurredAt: explicitOccurredAt ?? readEventClock(clock),
+			metadata: guardedMetadataClone(stampOptions.metadata)
+		});
+		FACTORY_OWNED_EVENT_STAMPS.add(owned);
+		return owned;
+	};
+	return Object.freeze({
+		createStamp,
+		create,
+		now: () => readClock(clock)
+	});
+}
+/**
+* Immutable UUID-v4/platform-clock factory used by the top-level
+* {@link createDomainEvent}. It cannot be reconfigured; construct an instance
+* with {@link createDomainEventFactory} for custom policy.
+*/
+const defaultDomainEventFactory = createDomainEventFactory();
+/**
+* Creates a domain event with default values.
+* Sets occurredAt to current date and version to 1 if not provided.
+*
+* **Input ownership.** The event is deeply frozen, and `payload` and
+* `metadata` are deep-cloned first, so the caller's own objects are never
+* frozen in place and later mutation of them does not bleed into the
+* 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.
+*
+* **For aggregate-internal events, prefer `this.createEvent(...)` on
+* `AggregateRoot` / `EventSourcedAggregate`.** That helper auto-injects
+* `aggregateId` (from `this.id`) and `aggregateType` (from the
+* aggregate's declared `aggregateType` property), which downstream
+* consumers (outbox dispatchers, projection handlers, audit logs)
+* route by. The `withCommit` harvest boundary now validates both fields
+* are present and throws if they're missing, so a direct
+* `createDomainEvent(...)` call inside an aggregate that forgets the
+* options is caught at runtime. Record pending decisions in the application
+* shell before repository persistence or outbox harvest.
+*
+* Use `createDomainEvent(...)` directly for events that don't belong to
+* an aggregate: system events, integration events, configuration events,
+* test fixtures. For those, set `aggregateId` / `aggregateType` in
+* `options` if downstream consumers expect routing metadata.
+*
+* @param type - The event type
+* @param payload - The event payload
+* @param options - Optional event configuration (including `aggregateId`
+*   and `aggregateType` for routing)
+* @returns A domain event
+*
+* @example
+* ```typescript
+* const event = createDomainEvent("OrderCreated", { orderId: "123" });
+* ```
+*/
+const MINTED_EVENTS = /* @__PURE__ */ new WeakSet();
+const UNCOMMITTED_EVENTS = /* @__PURE__ */ new WeakSet();
+const FACTORY_OWNED_EVENT_STAMPS = /* @__PURE__ */ new WeakSet();
+const MINT_BRAND = Symbol.for("@shirudo/ddd-kit.mintedEvent");
+const UNCOMMITTED_BRAND = Symbol.for("@shirudo/ddd-kit.uncommittedEvent");
+function stampMintBrand(event) {
+	Object.defineProperty(event, MINT_BRAND, {
+		value: true,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+}
+function stampUncommittedBrand(event) {
+	Object.defineProperty(event, UNCOMMITTED_BRAND, {
+		value: true,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+}
+function isFactoryOwnedDomainEventStamp(stamp) {
+	return FACTORY_OWNED_EVENT_STAMPS.has(stamp);
+}
+/**
+* Whether `event` came out of {@link createDomainEvent} (or a helper
+* built on it, such as the aggregate `createEvent` helper), i.e. is deeply frozen with
+* defensively copied payload and metadata. Two tiers: events of THIS
+* loaded copy of the kit are verified unforgeably via the module's
+* WeakSet; events minted by ANOTHER copy (duplicate dependency, dual
+* CJS/ESM load) are recognized cooperatively via a global-registry
+* brand. Module-internal export for the aggregate recording paths;
+* not part of the package entries.
+*/
+function isMintedEvent(event) {
+	return MINTED_EVENTS.has(event) || event[MINT_BRAND] === true;
+}
+/** Whether a value was created by {@link createUncommittedDomainEvent}. */
+function isUncommittedDomainEvent(event) {
+	return UNCOMMITTED_EVENTS.has(event) || event[UNCOMMITTED_BRAND] === true;
+}
+function createUncommittedDomainEvent(type, payload, options) {
+	assertProducerOwnedEventFields(type, options);
+	const event = {
+		type,
+		aggregateId: options?.aggregateId,
+		aggregateType: options?.aggregateType,
+		payload: cloneOwnedEventData(payload, "payload"),
+		version: options?.version ?? 1
+	};
+	stampUncommittedBrand(event);
+	const uncommitted = deepFreeze(event);
+	UNCOMMITTED_EVENTS.add(uncommitted);
+	return uncommitted;
+}
+/** Brands and freezes a kit-derived copy of an uncommitted event. */
+function adoptUncommittedDomainEvent(copy) {
+	stampUncommittedBrand(copy);
+	Object.freeze(copy);
+	UNCOMMITTED_EVENTS.add(copy);
+	return 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.
+*/
+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 = guardedMetadataClone(stamp.metadata);
+	return mintRecordedEvent(event, stamp.eventId, occurredAt, metadata === void 0 ? void 0 : deepFreeze(metadata));
+}
+/**
+* Single mint tail for both stamp provenances. The stamp fields arrive
+* pre-validated, copied, and frozen (by `createStamp` for factory-owned
+* stamps, by `recordDomainEvent` for caller-built stamps); the uncommitted
+* event's payload is already defensively cloned and deeply frozen by its
+* constructor and is shared instead of paying a second deep copy per event.
+*/
+function mintRecordedEvent(event, eventId, occurredAt, metadata) {
+	assertProducerOwnedEventFields(event.type, event);
+	const recorded = {
+		eventId,
+		type: event.type,
+		aggregateId: event.aggregateId,
+		aggregateType: event.aggregateType,
+		payload: event.payload,
+		occurredAt,
+		version: event.version,
+		metadata
+	};
+	stampMintBrand(recorded);
+	Object.freeze(recorded);
+	MINTED_EVENTS.add(recorded);
+	return recorded;
+}
+/**
+* Brands, freezes, and registers a kit-derived copy of a minted event
+* (e.g. the address-stamped copy `apply()` creates) as minted 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
+* instance as well as by this instance's WeakSet. Module-internal
+* export; not part of the package entries.
+*/
+function adoptMintedEvent(copy) {
+	stampMintBrand(copy);
+	Object.freeze(copy);
+	MINTED_EVENTS.add(copy);
+	return copy;
+}
+function createDomainEvent(type, payload, options) {
+	return defaultDomainEventFactory.create(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);
+}
+function missingExplicitEventId() {
+	throw new DomainEventValidationError("EVENT_ID_REQUIRED", "eventId", "createDomainEventFromFacts requires an explicit eventId");
+}
+function missingExplicitOccurredAt() {
+	throw new DomainEventValidationError("EVENT_OCCURRED_AT_REQUIRED", "occurredAt", "createDomainEventFromFacts requires an explicit occurredAt");
+}
+function mintDomainEvent(type, payload, options, eventIdFactory, clock) {
+	assertProducerOwnedEventFields(type, options);
+	const eventId = options?.eventId ?? eventIdFactory();
+	assertNonBlankEventField(eventId, "eventId", "EVENT_ID_INVALID");
+	const occurredAt = options?.occurredAt === void 0 ? readEventClock(clock) : copyValidEventDate(options.occurredAt);
+	const version = options?.version ?? 1;
+	const event = {
+		eventId,
+		type,
+		aggregateId: options?.aggregateId,
+		aggregateType: options?.aggregateType,
+		payload: cloneOwnedEventData(payload, "payload"),
+		occurredAt,
+		version,
+		metadata: guardedMetadataClone(options?.metadata)
+	};
+	stampMintBrand(event);
+	const minted = deepFreeze(event);
+	MINTED_EVENTS.add(minted);
+	return minted;
+}
+function assertProducerOwnedEventFields(type, options) {
+	assertNonBlankEventField(type, "type", "EVENT_TYPE_INVALID");
+	const version = options?.version ?? 1;
+	if (!Number.isSafeInteger(version) || typeof version !== "number" || version < 1) throw new DomainEventValidationError("EVENT_SCHEMA_VERSION_INVALID", "version", "domain-event version 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");
+}
+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`);
+}
+function copyValidEventDate(value) {
+	if (!(value instanceof Date) || !Number.isFinite(value.getTime())) throw new DomainEventValidationError("EVENT_OCCURRED_AT_INVALID", "occurredAt", "domain-event occurredAt must be a valid Date");
+	return new Date(value.getTime());
+}
+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.
+*/
+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 || typeof value !== "object") return value;
+	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 isBinaryData(value) {
+	return ArrayBuffer.isView(value) || value instanceof ArrayBuffer || typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
+}
+/**
+* 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.
+*/
+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;
+	}
+	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;
+	}
+	for (const key of Object.keys(value)) assertNoBinaryData(value[key], field, visited);
+}
+/**
+* Copies metadata from a source event to a new event.
+* Useful for maintaining correlation chains in event-driven architectures.
+*
+* @example
+* ```typescript
+* const newEvent = createDomainEvent(
+*   "OrderShipped",
+*   { orderId: "123" },
+*   { metadata: copyMetadata(previousEvent, { causationId: previousEvent.type }) }
+* );
+* ```
+*/
+function copyMetadata(sourceEvent, additionalMetadata) {
+	if (sourceEvent.metadata !== void 0) assertNoHostileOwnProtoKey(sourceEvent.metadata, "Event metadata");
+	if (additionalMetadata !== void 0) assertNoHostileOwnProtoKey(additionalMetadata, "Event metadata");
+	return {
+		...sourceEvent.metadata ?? {},
+		...additionalMetadata ?? {}
+	};
+}
+/**
+* Merges multiple metadata objects into one.
+* Later metadata objects override earlier ones for the same keys.
+*
+* @example
+* ```typescript
+* const metadata = mergeMetadata(
+*   { correlationId: "corr-123" },
+*   { userId: "user-456" },
+*   { source: "order-service" }
+* );
+* ```
+*/
+function mergeMetadata(...metadataObjects) {
+	const merged = {};
+	for (const metadata of metadataObjects) {
+		if (!metadata) continue;
+		assertNoHostileOwnProtoKey(metadata, "Event metadata");
+		for (const key of Reflect.ownKeys(metadata)) {
+			if (!Object.getOwnPropertyDescriptor(metadata, key)?.enumerable) continue;
+			Object.defineProperty(merged, key, {
+				value: metadata[key],
+				writable: true,
+				enumerable: true,
+				configurable: true
+			});
+		}
+	}
+	return merged;
+}
+/**
+* Clones event metadata with the loud `__proto__` rejection applied at
+* the SOURCE: structuredClone preserves an own `__proto__` data key, so
+* without this guard a hostile envelope would ride into the frozen
+* event and re-arm downstream.
+*/
+function guardedMetadataClone(metadata) {
+	if (metadata !== void 0) assertNoHostileOwnProtoKey(metadata, "Event metadata");
+	return cloneOwnedEventData(metadata, "metadata");
+}
+
+//#endregion
+//#region src/events/ports.ts
+/**
+* Discriminates a {@link DispatchTrackingOutbox} from a plain
+* {@link Outbox} at runtime. The single source of truth for the check;
+* the dispatcher and the contract suite both use it, so what counts as
+* a tracking outbox cannot drift between them. Both tracking methods
+* must be present: a plain adapter that happens to expose an unrelated
+* `markFailed` helper must not be mistaken for one that implements the
+* tracking protocol and then be fed `(dispatchId, error)` arguments it
+* never asked for. Internal plumbing, not exported from the package
+* entries.
+*/
+function isDispatchTrackingOutbox(outbox) {
+	const candidate = outbox;
+	return typeof candidate.markFailed === "function" && typeof candidate.deadLetters === "function";
+}
+
+//#endregion
+export { deepFreeze as _, createDomainEvent as a, voEqualsExcept as b, createUncommittedDomainEvent as c, isUncommittedDomainEvent as d, mergeMetadata as f, ValueObject as g, SnapshotTimeValidationError as h, copyMetadata as i, defaultDomainEventFactory as l, DomainEventValidationError as m, adoptMintedEvent as n, createDomainEventFactory as o, recordDomainEvent as p, adoptUncommittedDomainEvent as r, createDomainEventFromFacts as s, isDispatchTrackingOutbox as t, isMintedEvent as u, vo as v, voWithValidation as x, voEquals as y };
+//# sourceMappingURL=ports.js.map