@shirudo/ddd-kit 1.0.1 → 1.2.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: 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)}: 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, 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
@@ -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,8 +701,11 @@ 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,
+    aggregateVersion: options?.aggregateVersion,
     metadata: options?.metadata
   };
   return deepFreeze(event);
@@ -474,7 +726,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");
 
@@ -493,7 +759,7 @@ var Entity = class {
   /**
    * Returns the current state of the entity.
    *
-   * The state object is **shallowly frozen** — direct property writes
+   * The state object is **shallowly frozen**: direct property writes
    * (`entity.state.foo = …`) throw in strict mode, but writes to nested
    * objects (`entity.state.address.zip = …`) bypass the freeze. For deep
    * immutability either model nested data with `vo()` (which freezes
@@ -510,12 +776,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);
   }
   /**
@@ -526,7 +800,7 @@ var Entity = class {
    * **⚠️ Must not read subclass instance fields via `this`.** The
    * constructor calls `validateState(initialState)` BEFORE the subclass's
    * field initializers run, so `this.someField` is `undefined` at that
-   * point — a classic TypeScript/JavaScript constructor-ordering footgun.
+   * point, a classic TypeScript/JavaScript constructor-ordering footgun.
    * The `state` argument is the single source of truth; treat the method
    * as pure with respect to `this`.
    *
@@ -546,11 +820,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 +838,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;
 }
@@ -603,7 +889,7 @@ var BaseAggregate = class extends Entity {
    *
    * Distinct from {@link version}, which is the in-memory
    * post-mutation value. Mutations bump `_version` but never touch
-   * `_persistedVersion` — that field only moves on {@link markRestored}
+   * `_persistedVersion`; that field only moves on {@link markRestored}
    * (Post-Load) and {@link markPersisted} (Post-Save).
    */
   _persistedVersion = void 0;
@@ -623,7 +909,7 @@ var BaseAggregate = class extends Entity {
   }
   /**
    * Clears the pending-event list. Called by `markPersisted` after a
-   * successful write — the events have been handed off to the outbox
+   * successful write: the events have been handed off to the outbox
    * / event store and are no longer the aggregate's responsibility.
    */
   clearPendingEvents() {
@@ -641,16 +927,26 @@ var BaseAggregate = class extends Entity {
     this.setVersion(this._version + 1);
   }
   /**
-   * **Lifecycle marker — Post-Load.** Syncs both `_version` and
+   * **Lifecycle marker, Post-Load.** Syncs both `_version` and
    * `_persistedVersion` to the DB-stored version. Used by
    * `reconstitute(...)` factories to assemble an in-memory aggregate
    * from a persisted row.
    *
-   * Does NOT fire {@link onPersisted} — that hook has post-save
+   * Does NOT fire {@link onPersisted}; that hook has post-save
    * semantics (metrics, audit, cache eviction), not post-load. The
    * Factory-vs-Reconstitution distinction (Vernon §11) is honoured
    * structurally: two separate markers, one for each transition.
    *
+   * **If you override this, call `super.markRestored(version)` FIRST**,
+   * same discipline as {@link markPersisted}. The marker is load-bearing
+   * twice over: it syncs `version`/`persistedVersion`, and on
+   * `AggregateRoot` it also captures the dirty-tracking baseline for
+   * `changedKeys`/`hasChanges`. An override that skips `super` leaves
+   * that baseline uncaptured: `changedKeys` permanently reports ALL
+   * keys and `hasChanges` never returns `false`, so a partial-write
+   * repository silently degrades to full writes on every save — on top
+   * of the broken version sync.
+   *
    * @param version - The version the row currently holds in the DB
    *
    * @example
@@ -667,14 +963,14 @@ var BaseAggregate = class extends Entity {
     this._persistedVersion = version;
   }
   /**
-   * **Framework lifecycle method — `@sealed`.** Called by `withCommit`
+   * **Framework lifecycle method (`@sealed`).** Called by `withCommit`
    * (or by your own orchestration code, after harvesting `pendingEvents`)
    * to push the persisted version back into the in-memory aggregate and
    * clear `pendingEvents`. TypeScript has no `final` keyword, but
    * subclasses **should not** override this method directly.
    *
    * Overriding without calling `super.markPersisted(version)` silently
-   * leaks `pendingEvents` — the next `withCommit` will re-dispatch them
+   * leaks `pendingEvents`: the next `withCommit` will re-dispatch them
    * through the outbox, double-emitting events. This bug has been hit
    * in production by consumers; the {@link onPersisted} hook below is
    * the safer extension point.
@@ -684,7 +980,7 @@ var BaseAggregate = class extends Entity {
    * runs, then add your logic afterwards.
    *
    * @param version - The version assigned by the persistence layer
-   * @see onPersisted — the safe extension point for subclasses
+   * @see onPersisted, the safe extension point for subclasses
    */
   markPersisted(version) {
     this.markRestored(version);
@@ -692,19 +988,25 @@ var BaseAggregate = class extends Entity {
     this.onPersisted(version);
   }
   /**
-   * Subclass extension point — fires AFTER {@link markPersisted} has
+   * Subclass extension point: fires AFTER {@link markPersisted} has
    * updated the version and cleared `pendingEvents`. Override this for
    * post-persist logging, metrics, or cache-eviction without risk of
    * breaking the framework's pendingEvents cleanup.
    *
    * The default implementation is a no-op. Subclasses do NOT need to
-   * call `super.onPersisted(version)` — there is nothing in the parent
+   * 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`
-   * subscribers or the outbox dispatcher — that is the proper
+   * subscribers or the outbox dispatcher; that is the proper
    * Aggregate-Boundary separation. Building event-aware logic into
    * `onPersisted` couples aggregate lifecycle to event processing and
    * recreates the boundary problems Vernon's aggregate discipline is
@@ -713,7 +1015,7 @@ var BaseAggregate = class extends Entity {
    * **The hook must return synchronously.** `markPersisted` is `void`-
    * typed and calls `onPersisted` without `await`. TypeScript's
    * permissive `void` will accept an `async`-override returning
-   * `Promise<void>`, but the returned promise is fire-and-forget —
+   * `Promise<void>`, but the returned promise is fire-and-forget:
    * any rejection becomes an unhandled rejection and `withCommit`
    * proceeds without waiting. For asynchronous work, subscribe to the
    * relevant domain event on the `EventBus` instead; that is the
@@ -726,7 +1028,7 @@ var BaseAggregate = class extends Entity {
   /**
    * Appends a domain event to the pending list. Prefer the higher-level
    * `AggregateRoot.commit()` (state-stored) or `EventSourcedAggregate.apply()`
-   * (event-sourced) call sites — both wrap `addDomainEvent` in the
+   * (event-sourced) call sites, both of which wrap `addDomainEvent` in the
    * canonical record-AFTER-mutation order (Vernon §8). Calling
    * `addDomainEvent` directly is appropriate only when state and event
    * recording have already been decoupled deliberately (e.g. a
@@ -736,25 +1038,57 @@ var BaseAggregate = class extends Entity {
     this._pendingEvents.push(event);
   }
   /**
-   * Creates a snapshot of the current aggregate state — the state at
+   * 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})
    * into the event's metadata fields. This is the canonical path for
    * recording events from inside aggregate domain methods.
    *
-   * Downstream consumers — outbox dispatchers, projection handlers,
-   * audit logs — route by these two fields. Calling
+   * Downstream consumers (outbox dispatchers, projection handlers,
+   * audit logs) route by these two fields. Calling
    * `createDomainEvent(...)` directly inside an aggregate method
    * leaves them unset and is caught at the `withCommit` harvest
    * boundary, but `this.recordEvent(...)` makes the right thing
@@ -778,8 +1112,8 @@ var BaseAggregate = class extends Entity {
    * @param payload - payload for that event subtype
    * @param options - any remaining `createDomainEvent` options
    *   (`eventId`, `occurredAt`, `metadata`, `version`); `aggregateId`
-   *   and `aggregateType` are deliberately omitted — the helper sets
-   *   them.
+   *   and `aggregateType` are deliberately omitted, because the helper
+   *   sets them.
    */
   recordEvent(type, payload, options) {
     return createDomainEvent(type, payload, {
@@ -789,6 +1123,77 @@ var BaseAggregate = class extends Entity {
     });
   }
 };
+function assertSnapshotSafe(value, path, seen) {
+  if (typeof value === "function") {
+    throw new Error(
+      `createSnapshot: state${path} is a function: 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)}: 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: 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)}): 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}): 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 {
@@ -796,10 +1201,125 @@ var AggregateRoot = class extends BaseAggregate {
     __name(this, "AggregateRoot");
   }
   _autoVersionBump;
+  /**
+   * The state reference as of the last {@link markRestored} /
+   * `markPersisted` (the persistence-lifecycle markers). Only
+   * meaningful while {@link _hasBaseline} is `true`; tracked by a
+   * separate flag rather than an `undefined` sentinel so a `TState`
+   * that itself admits `undefined` cannot be confused with the
+   * never-persisted insert path.
+   *
+   * Held by reference, never copied: `_state` is shallow-frozen and only
+   * ever *replaced* (via `setState` / restore), so the captured reference
+   * stays an exact image of the state at baseline time.
+   */
+  _baselineState = void 0;
+  /**
+   * `false` until the aggregate has been persisted or restored at least
+   * once: the insert path, where every key counts as changed.
+   */
+  _hasBaseline = false;
   constructor(id, initialState, config) {
     super(id, initialState);
     this._autoVersionBump = config?.autoVersionBump ?? false;
   }
+  /**
+   * **Lifecycle marker, Post-Load (see `BaseAggregate.markRestored`).**
+   * Additionally captures the current state reference as the dirty-
+   * tracking baseline for {@link changedKeys} / {@link hasChanges}.
+   *
+   * Covers all three baseline-capture paths through a single override:
+   * `reconstitute(...)` factories, {@link restoreFromSnapshot} (which
+   * assigns the restored state *before* calling this), and
+   * `markPersisted` (which delegates here, so a successful save
+   * re-baselines the diff).
+   *
+   * If you override this, call `super.markRestored(version)` FIRST:
+   * skipping it leaves the baseline uncaptured, so `changedKeys`
+   * permanently reports ALL keys and `hasChanges` never returns `false`
+   * — partial-write repositories silently degrade to full writes — on
+   * top of breaking version sync.
+   */
+  markRestored(version) {
+    super.markRestored(version);
+    this._baselineState = this._state;
+    this._hasBaseline = true;
+  }
+  /**
+   * Top-level state keys whose value (or presence) changed since the
+   * last {@link markRestored} / `markPersisted`. Never-persisted
+   * aggregates report ALL current keys (the insert path).
+   *
+   * This is the write-scoping signal for **partial writes in multi-table
+   * repositories**: a `save()` for an aggregate whose state spans a root
+   * row plus N child-collection tables can write only the collections
+   * whose key is dirty, while the root-row OCC version write rides every
+   * save. See `docs/guide/repository.md` → "Partial writes for
+   * multi-table aggregates".
+   *
+   * **How it works.** `setState()` replaces state immutably and the
+   * state object is shallow-frozen, so unchanged top-level sub-objects
+   * keep reference identity across mutations. The diff is therefore a
+   * shallow per-key `!==` against the baseline reference — O(top-level
+   * keys), no proxies, no deep diff. A key also counts as dirty when its
+   * *presence* differs (added or removed, even with an `undefined`
+   * value). Computed fresh on every access (a new `Set` each time), so
+   * callers cannot poison later reads.
+   *
+   * **Soundness contract (same one `freezeShallow` already makes):**
+   * the per-key diff is exact only for plain-record `TState` mutated via
+   * `setState` / `commit` (whole-state replacement). In-place mutation
+   * of NESTED objects bypasses the shallow freeze AND this diff; a
+   * class-instance `TState` mutated through its own methods defeats
+   * tracking entirely (the reference never changes). A keyless `TState`
+   * (primitive, bare `Date`) has no keys to report, so `changedKeys`
+   * stays empty for it — use {@link hasChanges}, whose reference
+   * fallback covers keyless states. A deep-equal but newly-referenced
+   * value reports a false POSITIVE (harmless extra write); under the
+   * contract above there are no false negatives.
+   *
+   * Granularity is per top-level key — table-granular, not row-granular:
+   * a dirty collection key means "this child table changed", not which
+   * rows. `EventSourcedAggregate` deliberately has no `changedKeys`;
+   * its `pendingEvents` are the change record.
+   */
+  get changedKeys() {
+    if (!this._hasBaseline) {
+      return new Set(ownKeys(this._state));
+    }
+    return computeChangedKeys(this._baselineState, this._state);
+  }
+  /**
+   * Safe skip signal: `false` only when there is genuinely nothing to
+   * persist or flush. `true` when the aggregate has never been
+   * persisted, the version moved past `persistedVersion`, there are
+   * unflushed {@link pendingEvents}, any state key is dirty, or — for
+   * keyless states the per-key diff cannot see (primitive `TState`,
+   * zero-own-key objects like a bare `Date`) — the state reference
+   * changed since the baseline.
+   *
+   * The version clause is deliberate: `setState({...state}, true)` with
+   * identical per-key values yields empty {@link changedKeys} but a
+   * bumped version. If a repository skipped `save()` on a state-only
+   * check, `withCommit` would still call `markPersisted(version)` after
+   * commit, desyncing `persistedVersion` from the DB row — and the next
+   * uncontended save would throw a false `ConcurrencyConflictError`.
+   *
+   * The pending-events clause covers the sanctioned decoupled
+   * `addDomainEvent` path (an event recorded without a state change,
+   * e.g. a deletion event before a hard delete): the aggregate still
+   * needs its trip through `withCommit` so the event reaches the
+   * outbox. With all clauses included, `hasChanges === false` genuinely
+   * means "skipping save is safe".
+   */
+  get hasChanges() {
+    if (!this._hasBaseline) return true;
+    if (this.version !== this.persistedVersion) return true;
+    if (this.pendingEvents.length > 0) return true;
+    if (this.changedKeys.size > 0) return true;
+    const baseline = this._baselineState;
+    return baseline !== this._state && ownKeys(baseline).length === 0 && ownKeys(this._state).length === 0;
+  }
   /**
    * Mutates state and records the resulting domain events in the
    * **canonical record-after-mutation order**. Use this instead of calling
@@ -807,7 +1327,7 @@ var AggregateRoot = class extends BaseAggregate {
    * "event for a fact that never happened" footgun.
    *
    * Order of operations:
-   *  1. `setState(newState, true)` — runs `validateState` first.
+   *  1. `setState(newState, true)`: runs `validateState` first.
    *     If it throws, the method propagates and **no event is recorded
    *     and no version is bumped**.
    *  2. Each event in `events` is appended via `addDomainEvent`.
@@ -866,19 +1386,46 @@ var AggregateRoot = class extends BaseAggregate {
     }
   }
   /**
-   * Restores the aggregate from a snapshot — loads state and aligns
+   * Restores the aggregate from a snapshot: loads state and aligns
    * `version` + `persistedVersion` to the snapshot version. Validates
    * the restored state.
    *
    * @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);
   }
 };
+function ownKeys(value) {
+  return value !== null && typeof value === "object" ? Object.keys(value) : [];
+}
+__name(ownKeys, "ownKeys");
+function computeChangedKeys(baseline, current) {
+  const baselineKeys = new Set(ownKeys(baseline));
+  const currentKeys = new Set(ownKeys(current));
+  const dirty = /* @__PURE__ */ new Set();
+  for (const key of currentKeys) {
+    if (!baselineKeys.has(key)) {
+      dirty.add(key);
+      continue;
+    }
+    const before = baseline[key];
+    const after = current[key];
+    if (before !== after) {
+      dirty.add(key);
+    }
+  }
+  for (const key of baselineKeys) {
+    if (!currentKeys.has(key)) {
+      dirty.add(key);
+    }
+  }
+  return dirty;
+}
+__name(computeChangedKeys, "computeChangedKeys");
 var DomainError = class extends BaseError {
   static {
     __name(this, "DomainError");
@@ -891,16 +1438,33 @@ var InfrastructureError = class extends BaseError {
 };
 var MissingHandlerError = class extends BaseError {
   constructor(eventType, cause) {
-    super(`Missing handler for event type: ${eventType}`, cause);
+    super(`Missing handler for event type: ${eventType}`, cause, {
+      name: "MissingHandlerError"
+    });
     this.eventType = eventType;
   }
   static {
     __name(this, "MissingHandlerError");
   }
 };
+var AggregateDeletedError = class extends BaseError {
+  constructor(aggregateId) {
+    super(
+      `Aggregate ${aggregateId} was deleted in this unit of work and cannot be saved or registered again. Deletion is final within an operation; if the aggregate must live, do not delete it.`,
+      void 0,
+      { name: "AggregateDeletedError" }
+    );
+    this.aggregateId = aggregateId;
+  }
+  static {
+    __name(this, "AggregateDeletedError");
+  }
+};
 var AggregateNotFoundError = class extends InfrastructureError {
   constructor(aggregateType, id, cause) {
-    super(`Aggregate not found: ${aggregateType}(${id})`, cause);
+    super(`Aggregate not found: ${aggregateType}(${id})`, cause, {
+      name: "AggregateNotFoundError"
+    });
     this.aggregateType = aggregateType;
     this.id = id;
     this.withUserMessage(
@@ -911,11 +1475,29 @@ var AggregateNotFoundError = class extends InfrastructureError {
     __name(this, "AggregateNotFoundError");
   }
 };
+var DuplicateAggregateError = class extends InfrastructureError {
+  constructor(aggregateType, aggregateId, cause) {
+    super(
+      `Duplicate aggregate: ${aggregateType}(${aggregateId}) already exists`,
+      cause,
+      { name: "DuplicateAggregateError" }
+    );
+    this.aggregateType = aggregateType;
+    this.aggregateId = aggregateId;
+    this.withUserMessage(
+      `This ${aggregateType} already exists. It may have been created by a concurrent request.`
+    );
+  }
+  static {
+    __name(this, "DuplicateAggregateError");
+  }
+};
 var ConcurrencyConflictError = class extends InfrastructureError {
   constructor(aggregateType, aggregateId, expectedVersion, actualVersion, cause) {
     super(
       `Concurrency conflict on ${aggregateType}(${aggregateId}): expected version ${expectedVersion}, actual ${actualVersion}`,
-      cause
+      cause,
+      { name: "ConcurrencyConflictError" }
     );
     this.aggregateType = aggregateType;
     this.aggregateId = aggregateId;
@@ -955,13 +1537,13 @@ var EventSourcedAggregate = class extends BaseAggregate {
    * Throws `DomainError` (or a subclass) on validation failure.
    * Throws `MissingHandlerError` if no handler is registered for `event.type`.
    *
-   * State is not mutated if any step throws — the handler is invoked into
+   * State is not mutated if any step throws: the handler is invoked into
    * a local and only assigned to `_state` once all checks pass.
    *
    * The method is generic in the event tag `K`, so concrete callers
    * (`this.apply(orderCreated)`) narrow to the literal tag and the
-   * dispatched handler is typed as `Handler<TState, Extract<TEvent, { type: K }>>`
-   * — no `as` cast required at the call site.
+   * dispatched handler is typed as `Handler<TState, Extract<TEvent, { type: K }>>`,
+   * with no `as` cast required at the call site.
    *
    * @param event - The domain event to apply
    * @param isNew - Whether the event is new (needs persisting) or replayed from history
@@ -978,7 +1560,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);
     }
@@ -991,21 +1573,30 @@ var EventSourcedAggregate = class extends BaseAggregate {
   }
   /**
    * Reconstitutes the aggregate from an event history. Catches `DomainError`
-   * thrown during replay and returns it as an `Err` — this is the
+   * thrown during replay and returns it as an `Err`: this is the
    * 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, the 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 +1617,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 +1635,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,21 +1670,32 @@ var CommandBus = class {
     try {
       return await handler(command);
     } catch (error) {
-      return err(
-        error instanceof Error ? error.message : String(error)
-      );
+      return err(describeThrown(error));
     }
   }
 };
 
 // src/app/handler.ts
 async function withCommit(deps, fn) {
-  const { result, aggregates, events } = await deps.scope.transactional(
+  const { result, aggregates, deleted, events } = await deps.scope.transactional(
     async (ctx) => {
       const fnResult = await fn(ctx);
       const uniqueAggregates = Array.from(new Set(fnResult.aggregates));
       const harvested = uniqueAggregates.flatMap(
-        (agg) => agg.pendingEvents
+        (agg) => agg.pendingEvents.map((event) => {
+          if (event.aggregateVersion === void 0) {
+            return Object.freeze({
+              ...event,
+              aggregateVersion: agg.version
+            });
+          }
+          if (event.aggregateVersion > agg.version) {
+            throw new Error(
+              `withCommit: event "${event.type}" carries a pre-set aggregateVersion (${event.aggregateVersion}) AHEAD of its aggregate's commit version (${agg.version}). A stale-or-copied pre-set would advance consumer idempotency watermarks past real history; remove the manual aggregateVersion or correct it.`
+            );
+          }
+          return event;
+        })
       );
       for (const event of harvested) {
         const missing = [];
@@ -1084,31 +1705,351 @@ async function withCommit(deps, fn) {
           throw new Error(
             `withCommit: event "${event.type}" is missing ${missing.join(
               " and "
-            )}. Use this.recordEvent(type, payload) inside aggregate methods instead of createDomainEvent(...) \u2014 recordEvent auto-injects aggregateId and aggregateType. Outbox dispatchers and projection handlers rely on these fields for routing.`
+            )}. Use this.recordEvent(type, payload) inside aggregate methods instead of createDomainEvent(...); recordEvent auto-injects aggregateId and aggregateType. Outbox dispatchers and projection handlers rely on these fields for routing.`
           );
         }
       }
       if (harvested.length > 0) {
         await deps.outbox.add(harvested);
       }
-      return { ...fnResult, aggregates: uniqueAggregates, events: harvested };
+      return {
+        ...fnResult,
+        aggregates: uniqueAggregates,
+        deleted: new Set(fnResult.deleted ?? []),
+        events: harvested
+      };
     }
   );
   for (const agg of aggregates) {
-    agg.markPersisted(agg.version);
+    try {
+      if (deleted.has(agg)) {
+        agg.clearPendingEvents();
+      } else {
+        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;
 }
 __name(withCommit, "withCommit");
+
+// src/repo/identity-map.ts
+var IdentityMap = class {
+  static {
+    __name(this, "IdentityMap");
+  }
+  _stores = /* @__PURE__ */ new Map();
+  _deleted = /* @__PURE__ */ new Map();
+  /** The cached instance for type+id, or `undefined` (also after {@link delete}). */
+  get(type, id) {
+    return this._stores.get(type)?.get(id);
+  }
+  /** Whether an instance is registered for type+id (false after {@link delete}). */
+  has(type, id) {
+    return this._stores.get(type)?.has(id) ?? false;
+  }
+  /**
+   * Whether type+id was {@link delete}d in this unit of work. The
+   * read path checks this BEFORE hydrating and returns `null`, so
+   * "deleted in this operation" reads uniformly as not-found —
+   * regardless of whether the repository's physical delete already
+   * removed the row or is deferred within the transaction. Without
+   * the check, a read-only probe of a deleted aggregate would crash
+   * in {@link set} for deferred-write repositories and return `null`
+   * for immediate-write ones.
+   */
+  isDeleted(type, id) {
+    return this._deleted.get(type)?.has(id) ?? false;
+  }
+  /**
+   * Registers the hydrated instance for type+id.
+   *
+   * - Re-registering the SAME instance is a no-op (idempotent).
+   * - Registering a DIFFERENT instance for an occupied type+id throws:
+   *   that is precisely the identity-map violation this class exists
+   *   to prevent (the repository hydrated twice instead of checking
+   *   {@link get} first), and letting it pass would double-harvest
+   *   events downstream.
+   * - Registering a type+id that was {@link delete}d in this unit of
+   *   work throws `AggregateDeletedError`: deletion is final within
+   *   the operation.
+   */
+  set(type, id, aggregate) {
+    if (this._deleted.get(type)?.has(id)) {
+      throw new AggregateDeletedError(String(id));
+    }
+    let store = this._stores.get(type);
+    if (store === void 0) {
+      store = /* @__PURE__ */ new Map();
+      this._stores.set(type, store);
+    }
+    const existing = store.get(id);
+    if (existing !== void 0 && existing !== aggregate) {
+      throw new Error(
+        `IdentityMap: a different instance is already registered for ${type.name}(${String(id)}). Check get() before hydrating - two live instances of one aggregate break the one-instance-per-unit-of-work contract that exactly-once event harvest relies on.`
+      );
+    }
+    store.set(id, aggregate);
+  }
+  /**
+   * Removes the entry for type+id and records a tombstone: subsequent
+   * {@link get} / {@link has} report absence, and a subsequent
+   * {@link set} of the same type+id throws `AggregateDeletedError`.
+   * Called by a repository's `delete(aggregate)` alongside
+   * `session.enrollDeleted(aggregate)`.
+   */
+  delete(type, id) {
+    this._stores.get(type)?.delete(id);
+    let tombstones = this._deleted.get(type);
+    if (tombstones === void 0) {
+      tombstones = /* @__PURE__ */ new Set();
+      this._deleted.set(type, tombstones);
+    }
+    tombstones.add(id);
+  }
+  /** Empties all stores and tombstones. Called by the unit of work on close. */
+  clear() {
+    this._stores.clear();
+    this._deleted.clear();
+  }
+};
+
+// src/app/unit-of-work.ts
+var NestedUnitOfWorkError = class extends BaseError {
+  static {
+    __name(this, "NestedUnitOfWorkError");
+  }
+  constructor() {
+    super(
+      "UnitOfWork.run() was called while this instance is already running. A nested run() would open an independent transaction, not join the outer one - merge the work into a single run() callback. For concurrent operations, construct one UnitOfWork per operation.",
+      void 0,
+      { name: "NestedUnitOfWorkError" }
+    );
+  }
+};
+var TransactionClosedError = class extends BaseError {
+  constructor(operation) {
+    super(
+      `Unit of work is closed: ${operation} was called after the transaction committed or rolled back. Do not use the context or session outside the run() callback.`,
+      void 0,
+      { name: "TransactionClosedError" }
+    );
+    this.operation = operation;
+  }
+  static {
+    __name(this, "TransactionClosedError");
+  }
+};
+var CommitError = class extends InfrastructureError {
+  static {
+    __name(this, "CommitError");
+  }
+  constructor(cause) {
+    super(
+      "Unit of work failed after the work callback completed: the event harvest, outbox write, or transaction commit rejected. The transaction did not commit; see cause.",
+      cause,
+      { name: "CommitError" }
+    );
+  }
+};
+var RollbackError = class extends InfrastructureError {
+  constructor(cause, rollbackCause) {
+    super(
+      "The work callback failed and the transaction scope rejected with a different error (possible rollback failure). The callback's error is the cause; the scope's error is in rollbackCause.",
+      cause,
+      { name: "RollbackError" }
+    );
+    this.rollbackCause = rollbackCause;
+  }
+  static {
+    __name(this, "RollbackError");
+  }
+};
+var UnitOfWork = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  static {
+    __name(this, "UnitOfWork");
+  }
+  _active = false;
+  /**
+   * Execute one unit of work: open the transaction, hand the callback
+   * tx-bound repositories, commit on resolve, roll back on throw,
+   * run the post-commit lifecycle (markPersisted, publish) for every
+   * enrolled aggregate. Returns the callback's result.
+   */
+  async run(work) {
+    if (this._active) {
+      throw new NestedUnitOfWorkError();
+    }
+    this._active = true;
+    let session;
+    let workCompleted = false;
+    let workThrew = false;
+    let workError;
+    try {
+      return await withCommit(
+        {
+          outbox: this.deps.outbox,
+          bus: this.deps.bus,
+          scope: this.deps.scope,
+          onPublishError: this.deps.onPublishError
+        },
+        async (tx) => {
+          session?.close();
+          const s = new Session();
+          session = s;
+          workCompleted = false;
+          workThrew = false;
+          workError = void 0;
+          const repositories = this.buildRepositories(tx, s);
+          const context = makeContext(repositories, tx, s);
+          try {
+            const result = await work(context);
+            workCompleted = true;
+            const aggregates = s.enrolledAggregates;
+            const deleted = s.deletedAggregates;
+            s.close();
+            return { result, aggregates, deleted };
+          } catch (error) {
+            workThrew = true;
+            workError = error;
+            throw error;
+          }
+        }
+      );
+    } catch (error) {
+      if (workThrew) {
+        if (error === workError || causeChainContains(error, workError)) {
+          throw error;
+        }
+        throw new RollbackError(workError, error);
+      }
+      if (workCompleted) {
+        throw new CommitError(error);
+      }
+      throw error;
+    } finally {
+      session?.close();
+      this._active = false;
+    }
+  }
+  buildRepositories(tx, session) {
+    const repositories = {};
+    for (const key of Object.keys(this.deps.repositories)) {
+      repositories[key] = this.deps.repositories[key](tx, session);
+    }
+    return repositories;
+  }
+};
+var Session = class {
+  static {
+    __name(this, "Session");
+  }
+  // Insertion-ordered: harvest order = enrollment order (withCommit
+  // then preserves per-aggregate emission order).
+  _enrolled = /* @__PURE__ */ new Set();
+  _deleted = /* @__PURE__ */ new Set();
+  _identityMap = new IdentityMap();
+  _closed = false;
+  get identityMap() {
+    this.assertOpen("session.identityMap");
+    return this._identityMap;
+  }
+  enrollSaved(aggregate) {
+    this.assertOpen("session.enrollSaved");
+    if (this._deleted.has(aggregate) || this._identityMap.isDeleted(
+      aggregate.constructor,
+      aggregate.id
+    )) {
+      throw new AggregateDeletedError(String(aggregate.id));
+    }
+    this._enrolled.add(aggregate);
+  }
+  enrollDeleted(aggregate) {
+    this.assertOpen("session.enrollDeleted");
+    this._deleted.add(aggregate);
+    this._identityMap.delete(
+      aggregate.constructor,
+      aggregate.id
+    );
+    this._enrolled.add(aggregate);
+  }
+  get enrolledAggregates() {
+    return [...this._enrolled];
+  }
+  get deletedAggregates() {
+    return [...this._deleted];
+  }
+  close() {
+    this._closed = true;
+    this._identityMap.clear();
+  }
+  assertOpen(operation) {
+    if (this._closed) {
+      throw new TransactionClosedError(operation);
+    }
+  }
+};
+function makeContext(repositories, transaction, session) {
+  return {
+    get repositories() {
+      session.assertOpen("context.repositories");
+      return repositories;
+    },
+    get rawTransaction() {
+      session.assertOpen("context.rawTransaction");
+      return transaction;
+    },
+    session
+  };
+}
+__name(makeContext, "makeContext");
+function causeChainContains(error, target) {
+  if (target === void 0 || target === null) {
+    return false;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current !== null && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    let next;
+    try {
+      next = current.cause;
+    } catch {
+      return false;
+    }
+    if (next === target) {
+      return true;
+    }
+    current = next;
+  }
+  return false;
+}
+__name(causeChainContains, "causeChainContains");
 var QueryBus = class {
   static {
     __name(this, "QueryBus");
   }
   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 +2061,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 +2157,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 +2200,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);
@@ -1267,6 +2214,6 @@ function voValidated(t, validate, message = "Validation failed") {
 }
 __name(voValidated, "voValidated");
 
-export { AggregateNotFoundError, AggregateRoot, CommandBus, ConcurrencyConflictError, DomainError, Entity, EventBusImpl, EventSourcedAggregate, InMemoryOutbox, InfrastructureError, MissingHandlerError, QueryBus, ValueObject, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepEqual, deepEqualExcept, deepFreeze, deepOmit, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
+export { AggregateDeletedError, AggregateNotFoundError, AggregateRoot, CommandBus, CommitError, ConcurrencyConflictError, DomainError, DuplicateAggregateError, Entity, EventBusImpl, EventSourcedAggregate, IdentityMap, InMemoryOutbox, InfrastructureError, MissingHandlerError, NestedUnitOfWorkError, QueryBus, RollbackError, TransactionClosedError, UnitOfWork, ValueObject, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepEqual, deepEqualExcept, deepFreeze, deepOmit, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map