@shirudo/ddd-kit 1.0.0 → 1.1.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { err, ok } from '@shirudo/result';
+import { ok, err } from '@shirudo/result';
 import { BaseError, ValidationError } from '@shirudo/base-error';
 
 var __defProp = Object.defineProperty;
@@ -21,10 +21,83 @@ var BUILT_IN_TAGS = /* @__PURE__ */ new Set([
   "[object SharedArrayBuffer]",
   "[object DataView]"
 ]);
+function intrinsicGetter(proto, prop) {
+  const get = Object.getOwnPropertyDescriptor(proto, prop)?.get;
+  if (!get) throw new Error(`missing intrinsic getter for ${prop}`);
+  return get;
+}
+__name(intrinsicGetter, "intrinsicGetter");
+var dateGetTime = Date.prototype.getTime;
+var mapSizeGet = intrinsicGetter(Map.prototype, "size");
+var setSizeGet = intrinsicGetter(Set.prototype, "size");
+var weakMapHas = WeakMap.prototype.has;
+var weakSetHas = WeakSet.prototype.has;
+var dataViewByteLengthGet = intrinsicGetter(DataView.prototype, "byteLength");
+var arrayBufferByteLengthGet = intrinsicGetter(
+  ArrayBuffer.prototype,
+  "byteLength"
+);
+var regExpSourceGet = intrinsicGetter(RegExp.prototype, "source");
+var booleanValueOf = Boolean.prototype.valueOf;
+var numberValueOf = Number.prototype.valueOf;
+var stringValueOf = String.prototype.valueOf;
+var PROBE_KEY = {};
+var REFERENCE_COMPARED_TAGS = /* @__PURE__ */ new Set([
+  "[object Error]",
+  "[object ArrayBuffer]",
+  "[object SharedArrayBuffer]",
+  "[object Promise]",
+  "[object WeakMap]",
+  "[object WeakSet]"
+]);
+function hasBrand(obj, tag) {
+  try {
+    switch (tag) {
+      case "[object Date]":
+        dateGetTime.call(obj);
+        return true;
+      case "[object RegExp]":
+        regExpSourceGet.call(obj);
+        return true;
+      case "[object Map]":
+        mapSizeGet.call(obj);
+        return true;
+      case "[object Set]":
+        setSizeGet.call(obj);
+        return true;
+      case "[object WeakMap]":
+        weakMapHas.call(obj, PROBE_KEY);
+        return true;
+      case "[object WeakSet]":
+        weakSetHas.call(obj, PROBE_KEY);
+        return true;
+      case "[object DataView]":
+        dataViewByteLengthGet.call(obj);
+        return true;
+      case "[object ArrayBuffer]":
+        arrayBufferByteLengthGet.call(obj);
+        return true;
+      case "[object Boolean]":
+        booleanValueOf.call(obj);
+        return true;
+      case "[object Number]":
+        numberValueOf.call(obj);
+        return true;
+      case "[object String]":
+        stringValueOf.call(obj);
+        return true;
+      default:
+        return true;
+    }
+  } catch {
+    return false;
+  }
+}
+__name(hasBrand, "hasBrand");
 function isBuiltInObject(obj, tag) {
-  if (tag.endsWith("Array]")) return true;
   if (ArrayBuffer.isView(obj)) return true;
-  return BUILT_IN_TAGS.has(tag);
+  if (tag.endsWith("Array]")) return false;
+  return BUILT_IN_TAGS.has(tag) && hasBrand(obj, tag);
 }
 __name(isBuiltInObject, "isBuiltInObject");
 
@@ -32,6 +105,10 @@ __name(isBuiltInObject, "isBuiltInObject");
 var objProto = Object.prototype;
 var objToString = objProto.toString;
 var objHasOwn = objProto.hasOwnProperty;
+function sameValueZero(a, b) {
+  return a === b || Number.isNaN(a) && Number.isNaN(b);
+}
+__name(sameValueZero, "sameValueZero");
 function deepEqual(a, b) {
   return deepEqualInner(a, b, /* @__PURE__ */ new WeakMap());
 }
@@ -77,24 +154,31 @@ function deepEqualInner(a, b, visited) {
     const len = arrA.length;
     if (len !== arrB.length) return false;
     for (let i = 0; i < len; i++) {
-      if (arrA[i] !== arrB[i]) return false;
+      if (!sameValueZero(arrA[i], arrB[i])) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(objA) || Array.isArray(objB)) {
+    if (!Array.isArray(objA) || !Array.isArray(objB)) return false;
+    const arrA = objA;
+    const arrB = objB;
+    const len = arrA.length;
+    if (len !== arrB.length) return false;
+    for (let i = 0; i < len; i++) {
+      if (!deepEqualInner(arrA[i], arrB[i], visited)) return false;
     }
     return true;
   }
   const tagA = objToString.call(objA);
   const tagB = objToString.call(objB);
   if (tagA !== tagB) return false;
+  const builtInA = isBuiltInObject(objA, tagA);
+  const builtInB = isBuiltInObject(objB, tagB);
+  if (builtInA !== builtInB) return false;
+  if (!builtInA) {
+    return comparePlainObjects(objA, objB, visited);
+  }
   switch (tagA) {
-    case "[object Array]": {
-      const arrA = objA;
-      const arrB = objB;
-      const len = arrA.length;
-      if (len !== arrB.length) return false;
-      for (let i = 0; i < len; i++) {
-        if (!deepEqualInner(arrA[i], arrB[i], visited)) return false;
-      }
-      return true;
-    }
     case "[object Map]": {
       const mapA = objA;
       const mapB = objB;
@@ -116,9 +200,7 @@ function deepEqualInner(a, b, visited) {
       return true;
     }
     case "[object Date]": {
-      const timeA = objA.getTime();
-      const timeB = objB.getTime();
-      return timeA === timeB;
+      return sameValueZero(objA.getTime(), objB.getTime());
     }
     case "[object RegExp]": {
       const regA = objA;
@@ -128,69 +210,88 @@ function deepEqualInner(a, b, visited) {
     case "[object Boolean]":
     case "[object Number]":
     case "[object String]": {
-      return objA.valueOf() === objB.valueOf();
+      return sameValueZero(
+        objA.valueOf(),
+        objB.valueOf()
+      );
     }
     default: {
-      if (isBuiltInObject(objA, tagA) && isBuiltInObject(objB, tagB)) {
-        return objA === objB;
-      }
-      const recA = objA;
-      const recB = objB;
-      const stringKeysA = Object.keys(objA);
-      const stringKeysB = Object.keys(objB);
-      if (stringKeysA.length !== stringKeysB.length) return false;
-      const symbolKeysA = Object.getOwnPropertySymbols(objA);
-      const symbolKeysB = Object.getOwnPropertySymbols(objB);
-      if (symbolKeysA.length !== symbolKeysB.length) return false;
-      const symbolKeysBSet = new Set(symbolKeysB);
-      for (const key of stringKeysA) {
-        if (!objHasOwn.call(objB, key)) return false;
-      }
-      for (const key of symbolKeysA) {
-        if (!symbolKeysBSet.has(key)) return false;
-      }
-      for (const key of stringKeysA) {
-        if (!deepEqualInner(recA[key], recB[key], visited)) {
-          return false;
-        }
-      }
-      for (const key of symbolKeysA) {
-        if (!deepEqualInner(recA[key], recB[key], visited)) {
-          return false;
-        }
-      }
-      return true;
+      return objA === objB;
     }
   }
 }
 __name(deepEqualInner, "deepEqualInner");
+function comparePlainObjects(objA, objB, visited) {
+  const recA = objA;
+  const recB = objB;
+  const stringKeysA = Object.keys(objA);
+  const stringKeysB = Object.keys(objB);
+  if (stringKeysA.length !== stringKeysB.length) return false;
+  const symbolKeysA = Object.getOwnPropertySymbols(objA);
+  const symbolKeysB = Object.getOwnPropertySymbols(objB);
+  if (symbolKeysA.length !== symbolKeysB.length) return false;
+  const symbolKeysBSet = new Set(symbolKeysB);
+  for (const key of stringKeysA) {
+    if (!objHasOwn.call(objB, key)) return false;
+  }
+  for (const key of symbolKeysA) {
+    if (!symbolKeysBSet.has(key)) return false;
+  }
+  for (const key of stringKeysA) {
+    if (!deepEqualInner(recA[key], recB[key], visited)) {
+      return false;
+    }
+  }
+  for (const key of symbolKeysA) {
+    if (!deepEqualInner(recA[key], recB[key], visited)) {
+      return false;
+    }
+  }
+  return true;
+}
+__name(comparePlainObjects, "comparePlainObjects");
 
 // src/utils/array/deep-omit.ts
 function deepOmit(value, options) {
   const visited = /* @__PURE__ */ new WeakMap();
   const ignoreKeys = options.ignoreKeys ? new Set(options.ignoreKeys) : void 0;
-  return omitInternal(value, options, ignoreKeys, [], visited);
+  const budget = options.ignoreKeyPredicate ? { visits: 0 } : void 0;
+  return omitInternal(value, options, ignoreKeys, [], visited, budget);
 }
 __name(deepOmit, "deepOmit");
-function omitInternal(value, options, ignoreKeys, path, visited) {
+var PATH_SENSITIVE_VISIT_BUDGET = 1e6;
+function omitInternal(value, options, ignoreKeys, path, visited, budget) {
   if (value === null) return value;
   if (typeof value !== "object") return value;
   const obj = value;
   if (visited.has(obj)) {
     return visited.get(obj);
   }
-  const tag = Object.prototype.toString.call(obj);
-  if (tag === "[object Array]") {
+  if (budget && ++budget.visits > PATH_SENSITIVE_VISIT_BUDGET) {
+    throw new Error(
+      `deepOmit: exceeded ${PATH_SENSITIVE_VISIT_BUDGET} node visits. With ignoreKeyPredicate, objects reached via shared references are cloned once per path (the predicate may decide differently per path), which expands exponentially on diamond-shaped sharing. Restructure the input to a tree, or use ignoreKeys for path-independent filtering.`
+    );
+  }
+  if (Array.isArray(obj)) {
     const arr = obj;
     const clone2 = new Array(arr.length);
     visited.set(obj, clone2);
     for (let i = 0; i < arr.length; i++) {
       path.push(i);
-      clone2[i] = omitInternal(arr[i], options, ignoreKeys, path, visited);
+      clone2[i] = omitInternal(
+        arr[i],
+        options,
+        ignoreKeys,
+        path,
+        visited,
+        budget
+      );
       path.pop();
     }
+    if (budget) visited.delete(obj);
     return clone2;
   }
+  const tag = Object.prototype.toString.call(obj);
   if (isBuiltInObject(obj, tag)) {
     const builtInClone = cloneBuiltIn(obj, tag);
     visited.set(obj, builtInClone);
@@ -211,7 +312,8 @@ function omitInternal(value, options, ignoreKeys, path, visited) {
         options,
         ignoreKeys,
         path,
-        visited
+        visited,
+        budget
       )
     );
     path.pop();
@@ -227,11 +329,13 @@ function omitInternal(value, options, ignoreKeys, path, visited) {
         options,
         ignoreKeys,
         path,
-        visited
+        visited,
+        budget
       )
     );
     path.pop();
   }
+  if (budget) visited.delete(obj);
   return clone;
 }
 __name(omitInternal, "omitInternal");
@@ -245,6 +349,7 @@ function assignOwn(target, key, value) {
 }
 __name(assignOwn, "assignOwn");
 function cloneBuiltIn(obj, tag) {
+  if (REFERENCE_COMPARED_TAGS.has(tag)) return obj;
   switch (tag) {
     case "[object Date]":
       return new Date(obj.getTime());
@@ -281,14 +386,81 @@ function deepEqualExcept(a, b, options) {
   return deepEqual(prunedA, prunedB);
 }
 __name(deepEqualExcept, "deepEqualExcept");
+var DATE_MUTATORS = [
+  "setTime",
+  "setMilliseconds",
+  "setUTCMilliseconds",
+  "setSeconds",
+  "setUTCSeconds",
+  "setMinutes",
+  "setUTCMinutes",
+  "setHours",
+  "setUTCHours",
+  "setDate",
+  "setUTCDate",
+  "setMonth",
+  "setUTCMonth",
+  "setFullYear",
+  "setUTCFullYear",
+  "setYear"
+];
+var mutationThrowers = /* @__PURE__ */ new Map();
+function mutationThrower(typeName, method) {
+  const key = `${typeName}.${method}`;
+  let thrower = mutationThrowers.get(key);
+  if (!thrower) {
+    thrower = /* @__PURE__ */ __name(function throwFrozenMutation() {
+      throw new TypeError(
+        `Cannot call ${method}() on a ${typeName} inside a deeply frozen value`
+      );
+    }, "throwFrozenMutation");
+    mutationThrowers.set(key, thrower);
+  }
+  return thrower;
+}
+__name(mutationThrower, "mutationThrower");
+var 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);
+  }
+}
+__name(shadowMutators, "shadowMutators");
 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 tag = Object.prototype.toString.call(obj);
+  if (isBuiltInObject(obj, tag)) {
+    if (tag === "[object Date]") {
+      shadowMutators(obj, "Date", DATE_MUTATORS);
+    } else if (tag === "[object Map]") {
+      for (const [key, value] of obj) {
+        deepFreeze(key, visited);
+        deepFreeze(value, visited);
+      }
+      shadowMutators(obj, "Map", ["set", "delete", "clear"]);
+    } else if (tag === "[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];
@@ -299,8 +471,74 @@ function deepFreeze(obj, visited = /* @__PURE__ */ new WeakSet()) {
   return Object.freeze(obj);
 }
 __name(deepFreeze, "deepFreeze");
+function cloneForVo(value, visited) {
+  if (typeof value === "function") {
+    throw new TypeError(
+      "vo() does not accept function values \u2014 Value Objects are data, not behaviour"
+    );
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  const obj = value;
+  if (visited.has(obj)) {
+    return visited.get(obj);
+  }
+  if (Array.isArray(obj)) {
+    const clone2 = new Array(obj.length);
+    visited.set(obj, clone2);
+    for (let i = 0; i < obj.length; i++) {
+      clone2[i] = cloneForVo(obj[i], visited);
+    }
+    return clone2;
+  }
+  const tag = Object.prototype.toString.call(obj);
+  if (isBuiltInObject(obj, tag)) {
+    if (tag === "[object Map]") {
+      const clone2 = /* @__PURE__ */ new Map();
+      visited.set(obj, clone2);
+      for (const [key, entry] of obj) {
+        clone2.set(cloneForVo(key, visited), cloneForVo(entry, visited));
+      }
+      return clone2;
+    }
+    if (tag === "[object Set]") {
+      const clone2 = /* @__PURE__ */ new Set();
+      visited.set(obj, clone2);
+      for (const member of obj) {
+        clone2.add(cloneForVo(member, visited));
+      }
+      return clone2;
+    }
+    if (tag === "[object Promise]" || tag === "[object WeakMap]" || tag === "[object WeakSet]") {
+      throw new TypeError(
+        `vo() cannot clone a ${tag.slice(8, -1)} \u2014 Value Objects are plain data`
+      );
+    }
+    const builtInClone = structuredClone(obj);
+    visited.set(obj, builtInClone);
+    return builtInClone;
+  }
+  const clone = Object.create(Object.getPrototypeOf(obj));
+  visited.set(obj, clone);
+  for (const key of Reflect.ownKeys(obj)) {
+    const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+    if (!descriptor?.enumerable) continue;
+    Object.defineProperty(clone, key, {
+      value: cloneForVo(
+        obj[key],
+        visited
+      ),
+      writable: true,
+      enumerable: true,
+      configurable: true
+    });
+  }
+  return clone;
+}
+__name(cloneForVo, "cloneForVo");
 function vo(t) {
-  return deepFreeze(structuredClone(t));
+  return deepFreeze(cloneForVo(t, /* @__PURE__ */ new WeakMap()));
 }
 __name(vo, "vo");
 function voEquals(a, b) {
@@ -314,12 +552,21 @@ __name(voEqualsExcept, "voEqualsExcept");
 function voWithValidation(t, validate, errorMessage) {
   if (!validate(t)) {
     return err(
-      errorMessage ?? `Validation failed for value object: ${JSON.stringify(t)}`
+      errorMessage ?? `Validation failed for value object: ${describeValue(t)}`
     );
   }
   return ok(vo(t));
 }
 __name(voWithValidation, "voWithValidation");
+function describeValue(value) {
+  try {
+    const json = JSON.stringify(value);
+    if (json !== void 0) return json;
+  } catch {
+  }
+  return String(value);
+}
+__name(describeValue, "describeValue");
 var ValueObject = class {
   static {
     __name(this, "ValueObject");
@@ -327,7 +574,9 @@ var ValueObject = class {
   props;
   /**
    * Creates a new ValueObject.
-   * The properties are deeply frozen to ensure immutability.
+   * The properties are deep-cloned (prototype-preserving) and then deeply
+   * frozen — 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
@@ -345,7 +594,7 @@ var ValueObject = class {
    */
   constructor(props) {
     this.validate(props);
-    this.props = deepFreeze({ ...props });
+    this.props = deepFreeze(cloneForVo(props, /* @__PURE__ */ new WeakMap()));
   }
   /**
    * Optional validation hook that can be overridden by subclasses.
@@ -452,7 +701,9 @@ function createDomainEvent(type, payload, options) {
     aggregateId: options?.aggregateId,
     aggregateType: options?.aggregateType,
     payload,
-    occurredAt: options?.occurredAt ?? currentClockFactory(),
+    // Defensive copy — the event must not share the caller's live Date
+    // instance, or a later mutation of it would bleed into the event.
+    occurredAt: options?.occurredAt ? new Date(options.occurredAt.getTime()) : currentClockFactory(),
     version: options?.version ?? 1,
     metadata: options?.metadata
   };
@@ -474,7 +725,21 @@ function copyMetadata(sourceEvent, additionalMetadata) {
 }
 __name(copyMetadata, "copyMetadata");
 function mergeMetadata(...metadataObjects) {
-  return Object.assign({}, ...metadataObjects.filter(Boolean));
+  const merged = {};
+  for (const metadata of metadataObjects) {
+    if (!metadata) continue;
+    for (const key of Reflect.ownKeys(metadata)) {
+      const descriptor = Object.getOwnPropertyDescriptor(metadata, key);
+      if (!descriptor?.enumerable) continue;
+      Object.defineProperty(merged, key, {
+        value: metadata[key],
+        writable: true,
+        enumerable: true,
+        configurable: true
+      });
+    }
+  }
+  return merged;
 }
 __name(mergeMetadata, "mergeMetadata");
 
@@ -510,12 +775,20 @@ var Entity = class {
    * Subclasses can mutate this directly or use helper methods.
    */
   _state;
+  /**
+   * **State ownership.** Plain-object and array states are shallow-copied
+   * before the freeze, so the caller's own object stays mutable. A CLASS
+   * INSTANCE passed as state is an ownership transfer: it is frozen
+   * in place (a copy would strip its prototype) — do not keep mutating
+   * the instance after handing it to the entity. The same contract
+   * applies to {@link setState}.
+   */
   constructor(id, initialState) {
     if (id === null || id === void 0) {
       throw new Error("Entity ID cannot be null or undefined");
     }
     this.id = id;
-    this._state = freezeShallow(initialState);
+    this._state = freezeShallow(shallowCopyOwned(initialState));
     this.validateState(this._state);
   }
   /**
@@ -546,11 +819,15 @@ var Entity = class {
    * This is a convenience method for state mutations.
    * Automatically validates the newState using `validateState()`.
    *
+   * Plain-object and array states are shallow-copied before the freeze
+   * (the caller's object stays mutable); a class-instance state is an
+   * ownership transfer and is frozen in place — see the constructor.
+   *
    * @param newState - The new state
    */
   setState(newState) {
     this.validateState(newState);
-    this._state = freezeShallow(newState);
+    this._state = freezeShallow(shallowCopyOwned(newState));
   }
 };
 function freezeShallow(value) {
@@ -560,6 +837,14 @@ function freezeShallow(value) {
   return value;
 }
 __name(freezeShallow, "freezeShallow");
+function shallowCopyOwned(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return [...value];
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+  return Object.assign(Object.create(proto), value);
+}
+__name(shallowCopyOwned, "shallowCopyOwned");
 function sameEntity(a, b) {
   return a.id === b.id;
 }
@@ -701,6 +986,12 @@ var BaseAggregate = class extends Entity {
    * call `super.onPersisted(version)` — there is nothing in the parent
    * implementation to preserve.
    *
+   * **Observer contract: errors are swallowed.** `withCommit` invokes
+   * `markPersisted` after the transaction has committed; a throwing hook
+   * must neither abort the loop for peer aggregates nor make the
+   * committed write look failed, so `withCommit` catches and discards
+   * hook errors. Handle failures inside the hook if you need them.
+   *
    * **`onPersisted` deliberately receives only the version, not the
    * drained events.** Event-driven post-persist logic (aggregate-level
    * audit logging, per-event-type side effects) belongs in `EventBus`
@@ -739,14 +1030,46 @@ var BaseAggregate = class extends Entity {
    * Creates a snapshot of the current aggregate state — the state at
    * this moment plus the version. Useful for ES snapshot policies and
    * for state-stored backup / restore.
+   *
+   * The state is converted via {@link toSnapshotState}; the default
+   * requires plain, serialisable data and fails fast otherwise.
    */
   createSnapshot() {
     return {
-      state: structuredClone(this._state),
+      state: this.toSnapshotState(this._state),
       version: this.version,
       snapshotAt: /* @__PURE__ */ new Date()
     };
   }
+  /**
+   * Converts live aggregate state into the plain-data shape stored in a
+   * snapshot. The default validates that the state graph is plain,
+   * serialisable data (no class instances, functions, Promise/WeakMap/
+   * WeakSet) and then `structuredClone`s it — class instances would
+   * silently lose their prototype here AND on every snapshot-store
+   * round-trip, so the default fails fast with the offending path
+   * instead of producing a snapshot that breaks on first method call
+   * after restore.
+   *
+   * Override this together with {@link fromSnapshotState} (and the
+   * `TSnapshotState` generic) when the state carries class-based child
+   * entities. The override owns isolation: return fresh objects, not
+   * references into live state.
+   */
+  toSnapshotState(state) {
+    assertSnapshotSafe(state, "", /* @__PURE__ */ new WeakSet());
+    return structuredClone(state);
+  }
+  /**
+   * Converts the plain-data snapshot shape back into live aggregate
+   * state. The default `structuredClone`s the stored state so the
+   * restored aggregate never aliases the snapshot object. Override
+   * together with {@link toSnapshotState} to reconstruct class-based
+   * child entities.
+   */
+  fromSnapshotState(stored) {
+    return structuredClone(stored);
+  }
   /**
    * Sugar for `createDomainEvent` that auto-injects `aggregateId`
    * (from `this.id`) and `aggregateType` (from {@link aggregateType})
@@ -789,6 +1112,77 @@ var BaseAggregate = class extends Entity {
     });
   }
 };
+function assertSnapshotSafe(value, path, seen) {
+  if (typeof value === "function") {
+    throw new Error(
+      `createSnapshot: state${path} is a function \u2014 snapshot state must be plain, serialisable data. Override toSnapshotState()/fromSnapshotState() to map it.`
+    );
+  }
+  if (value === null || typeof value !== "object") return;
+  const obj = value;
+  if (seen.has(obj)) return;
+  seen.add(obj);
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      assertSnapshotSafe(obj[i], `${path}[${i}]`, seen);
+    }
+    return;
+  }
+  const tag = Object.prototype.toString.call(obj);
+  if (isBuiltInObject(obj, tag)) {
+    if (tag === "[object Map]") {
+      let i = 0;
+      for (const [key, entryValue] of obj) {
+        assertSnapshotSafe(key, `${path}<map key #${i}>`, seen);
+        assertSnapshotSafe(entryValue, `${path}<map value #${i}>`, seen);
+        i++;
+      }
+      return;
+    }
+    if (tag === "[object Set]") {
+      let i = 0;
+      for (const member of obj) {
+        assertSnapshotSafe(member, `${path}<set member #${i}>`, seen);
+        i++;
+      }
+      return;
+    }
+    if (tag === "[object Promise]" || tag === "[object WeakMap]" || tag === "[object WeakSet]") {
+      throw new Error(
+        `createSnapshot: state${path} is a ${tag.slice(8, -1)} \u2014 it cannot be cloned or persisted. Override toSnapshotState()/fromSnapshotState() to map it.`
+      );
+    }
+    if (tag === "[object Error]") {
+      throw new Error(
+        `createSnapshot: state${path} is an Error \u2014 structuredClone downgrades Error subclasses to plain Error and silently drops custom fields, so the restored value would not round-trip. Override toSnapshotState()/fromSnapshotState() to map it to plain data.`
+      );
+    }
+    return;
+  }
+  const proto = Object.getPrototypeOf(obj);
+  if (proto === Object.prototype || proto === null) {
+    for (const key of Reflect.ownKeys(obj)) {
+      const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+      if (!descriptor?.enumerable) continue;
+      if (typeof key === "symbol") {
+        throw new Error(
+          `createSnapshot: state${path} has a symbol-keyed property (${String(key)}) \u2014 structuredClone silently drops symbol keys, so the snapshot would lose state. Override toSnapshotState()/fromSnapshotState() to map it.`
+        );
+      }
+      assertSnapshotSafe(
+        obj[key],
+        `${path}.${key}`,
+        seen
+      );
+    }
+    return;
+  }
+  const name = proto.constructor?.name || "anonymous class";
+  throw new Error(
+    `createSnapshot: state${path} is a class instance (${name}) \u2014 structuredClone would strip its prototype and methods, producing a snapshot that breaks on the first method call after restore. Override toSnapshotState()/fromSnapshotState() to map child entities to plain data.`
+  );
+}
+__name(assertSnapshotSafe, "assertSnapshotSafe");
 
 // src/aggregate/aggregate-root.ts
 var AggregateRoot = class extends BaseAggregate {
@@ -873,9 +1267,9 @@ var AggregateRoot = class extends BaseAggregate {
    * @param snapshot - The snapshot to restore from
    */
   restoreFromSnapshot(snapshot) {
-    const cloned = structuredClone(snapshot.state);
-    this.validateState(cloned);
-    this._state = freezeShallow(cloned);
+    const restored = this.fromSnapshotState(snapshot.state);
+    this.validateState(restored);
+    this._state = freezeShallow(restored);
     this.markRestored(snapshot.version);
   }
 };
@@ -978,7 +1372,7 @@ var EventSourcedAggregate = class extends BaseAggregate {
    */
   dispatchAndCommit(event, isNew) {
     this.validateEvent(event);
-    const handler = this.handlers[event.type];
+    const handler = Object.hasOwn(this.handlers, event.type) ? this.handlers[event.type] : void 0;
     if (!handler) {
       throw new MissingHandlerError(event.type);
     }
@@ -995,17 +1389,26 @@ var EventSourcedAggregate = class extends BaseAggregate {
    * infrastructure boundary, where event-stream corruption is an expected
    * recoverable failure. Unexpected (non-DomainError) throws propagate.
    *
+   * All-or-nothing: if any event mid-stream throws, the aggregate's state
+   * is rolled back to its pre-call value — same contract as
+   * `restoreFromSnapshotWithEvents`. Partial replay is never observable.
+   * (Version needs no rollback: replay dispatches with `isNew = false`,
+   * which never bumps it; only the final `markRestored` advances it.)
+   *
    * Version advances additively: the aggregate's pre-existing version plus
    * `history.length`. A fresh aggregate (v=0) loading 3 events ends at v=3;
    * an aggregate already at v=1 (e.g. after a creation event) loading
    * 2 events ends at v=3, not v=2.
    */
   loadFromHistory(history) {
+    if (history.length === 0) return ok();
+    const previousState = this._state;
     const startVersion = this.version;
     for (const event of history) {
       try {
         this.dispatchAndCommit(event, false);
       } catch (e) {
+        this._state = previousState;
         if (e instanceof DomainError) return err(e);
         throw e;
       }
@@ -1026,7 +1429,7 @@ var EventSourcedAggregate = class extends BaseAggregate {
   restoreFromSnapshotWithEvents(snapshot, eventsAfterSnapshot) {
     const previousState = this._state;
     const previousVersion = this.version;
-    this._state = freezeShallow(structuredClone(snapshot.state));
+    this._state = freezeShallow(this.fromSnapshotState(snapshot.state));
     this.setVersion(snapshot.version);
     for (const event of eventsAfterSnapshot) {
       try {
@@ -1044,12 +1447,31 @@ var EventSourcedAggregate = class extends BaseAggregate {
     return ok();
   }
 };
+
+// src/app/describe-thrown.ts
+function describeThrown(error) {
+  if (error instanceof Error) return error.message;
+  try {
+    const json = JSON.stringify(error);
+    if (json !== void 0) return json;
+  } catch {
+  }
+  return String(error);
+}
+__name(describeThrown, "describeThrown");
+
+// src/app/command-bus.ts
 var CommandBus = class {
   static {
     __name(this, "CommandBus");
   }
   handlers = /* @__PURE__ */ new Map();
   register(commandType, handler) {
+    if (this.handlers.has(commandType)) {
+      throw new Error(
+        `CommandBus: a handler for command type "${commandType}" is already registered`
+      );
+    }
     this.handlers.set(commandType, (cmd) => handler(cmd));
   }
   async execute(command) {
@@ -1060,9 +1482,7 @@ var CommandBus = class {
     try {
       return await handler(command);
     } catch (error) {
-      return err(
-        error instanceof Error ? error.message : String(error)
-      );
+      return err(describeThrown(error));
     }
   }
 };
@@ -1095,10 +1515,20 @@ async function withCommit(deps, fn) {
     }
   );
   for (const agg of aggregates) {
-    agg.markPersisted(agg.version);
+    try {
+      agg.markPersisted(agg.version);
+    } catch {
+    }
   }
   if (deps.bus && events.length > 0) {
-    await deps.bus.publish(events);
+    try {
+      await deps.bus.publish(events);
+    } catch (error) {
+      try {
+        deps.onPublishError?.(error, events);
+      } catch {
+      }
+    }
   }
   return result;
 }
@@ -1109,6 +1539,11 @@ var QueryBus = class {
   }
   handlers = /* @__PURE__ */ new Map();
   register(queryType, handler) {
+    if (this.handlers.has(queryType)) {
+      throw new Error(
+        `QueryBus: a handler for query type "${queryType}" is already registered`
+      );
+    }
     this.handlers.set(queryType, (query) => handler(query));
   }
   async execute(query) {
@@ -1120,9 +1555,7 @@ var QueryBus = class {
       const result = await handler(query);
       return ok(result);
     } catch (error) {
-      return err(
-        error instanceof Error ? error.message : String(error)
-      );
+      return err(describeThrown(error));
     }
   }
   async executeUnsafe(query) {
@@ -1218,12 +1651,19 @@ var EventBusImpl = class {
       const handlersForType = this.handlers.get(event.type);
       if (handlersForType) {
         const results = await Promise.allSettled(
-          handlersForType.slice().map((handler) => handler(event))
+          handlersForType.slice().map(async (handler) => handler(event))
         );
         for (const result of results) {
           if (result.status === "rejected") {
             errors.push(
-              result.reason instanceof Error ? result.reason : new Error(String(result.reason))
+              result.reason instanceof Error ? result.reason : (
+                // Attach the raw reason as cause — a handler
+                // rejecting with a structured payload must stay
+                // diagnosable, not collapse to '[object Object]'.
+                new Error(String(result.reason), {
+                  cause: result.reason
+                })
+              )
             );
           }
         }
@@ -1254,7 +1694,8 @@ var InMemoryOutbox = class {
   }
   async getPending(limit) {
     const all = [...this.pending.values()];
-    return typeof limit === "number" ? all.slice(0, limit) : all;
+    if (typeof limit !== "number") return all;
+    return all.slice(0, Math.max(0, limit));
   }
   async markDispatched(dispatchIds) {
     for (const id of dispatchIds) this.pending.delete(id);