@shirudo/ddd-kit 1.0.0-rc.1 → 1.0.0-rc.4

package/dist/index.js

@@ -1,85 +1,30 @@
+import { err, ok } from '@shirudo/result';
+import { BaseError } from '@shirudo/base-error';
+
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
-// src/aggregate/domain-event.ts
-function createDomainEvent(type, payload, options) {
-  return {
-    type,
-    payload,
-    occurredAt: options?.occurredAt ?? /* @__PURE__ */ new Date(),
-    version: options?.version ?? 1,
-    metadata: options?.metadata
-  };
-}
-__name(createDomainEvent, "createDomainEvent");
-function createDomainEventWithMetadata(type, payload, metadata, options) {
-  return createDomainEvent(type, payload, {
-    ...options,
-    metadata
-  });
-}
-__name(createDomainEventWithMetadata, "createDomainEventWithMetadata");
-function copyMetadata(sourceEvent, additionalMetadata) {
-  return {
-    ...sourceEvent.metadata ?? {},
-    ...additionalMetadata ?? {}
-  };
-}
-__name(copyMetadata, "copyMetadata");
-function mergeMetadata(...metadataObjects) {
-  return Object.assign({}, ...metadataObjects.filter(Boolean));
-}
-__name(mergeMetadata, "mergeMetadata");
-
-// src/aggregate/aggregate.ts
-function aggregate(state, version = 0) {
-  return { state, version };
-}
-__name(aggregate, "aggregate");
-function bump(agg) {
-  return { ...agg, version: agg.version + 1 };
-}
-__name(bump, "bump");
-function sameVersion(a, b) {
-  return a.id === b.id && a.version === b.version;
-}
-__name(sameVersion, "sameVersion");
-
 // src/utils/array/is-built-in.ts
+var BUILT_IN_TAGS = /* @__PURE__ */ new Set([
+  "[object Date]",
+  "[object RegExp]",
+  "[object Map]",
+  "[object Set]",
+  "[object WeakMap]",
+  "[object WeakSet]",
+  "[object Promise]",
+  "[object Error]",
+  "[object Boolean]",
+  "[object Number]",
+  "[object String]",
+  "[object ArrayBuffer]",
+  "[object SharedArrayBuffer]",
+  "[object DataView]"
+]);
 function isBuiltInObject(obj, tag) {
-  if (tag.endsWith("Array]")) {
-    return true;
-  }
-  if (ArrayBuffer.isView(obj)) {
-    return true;
-  }
-  if (tag === "[object ArrayBuffer]" || tag === "[object SharedArrayBuffer]") {
-    return true;
-  }
-  const objConstructor = obj.constructor;
-  if (objConstructor && typeof objConstructor === "function") {
-    const constructorName = objConstructor.name;
-    if (constructorName && typeof globalThis !== "undefined" && constructorName in globalThis && globalThis[constructorName] === objConstructor) {
-      const proto = Object.getPrototypeOf(obj);
-      if (proto !== Object.prototype && proto !== null) {
-        return true;
-      }
-    }
-  }
-  const knownBuiltInTags = /* @__PURE__ */ new Set([
-    "[object Date]",
-    "[object RegExp]",
-    "[object Map]",
-    "[object Set]",
-    "[object WeakMap]",
-    "[object WeakSet]",
-    "[object Promise]",
-    "[object Error]",
-    "[object Boolean]",
-    "[object Number]",
-    "[object String]"
-  ]);
-  return knownBuiltInTags.has(tag);
+  if (tag.endsWith("Array]")) return true;
+  if (ArrayBuffer.isView(obj)) return true;
+  return BUILT_IN_TAGS.has(tag);
 }
 __name(isBuiltInObject, "isBuiltInObject");
 
@@ -103,11 +48,15 @@ function deepEqualInner(a, b, visited) {
   }
   const objA = a;
   const objB = b;
-  const cached = visited.get(objA);
-  if (cached !== void 0) {
-    return cached === objB;
+  let cachedBs = visited.get(objA);
+  if (cachedBs?.has(objB)) {
+    return true;
+  }
+  if (!cachedBs) {
+    cachedBs = /* @__PURE__ */ new WeakSet();
+    visited.set(objA, cachedBs);
   }
-  visited.set(objA, objB);
+  cachedBs.add(objB);
   if (ArrayBuffer.isView(objA) || ArrayBuffer.isView(objB)) {
     if (!ArrayBuffer.isView(objA) || !ArrayBuffer.isView(objB)) return false;
     const tagA2 = objToString.call(objA);
@@ -185,25 +134,28 @@ function deepEqualInner(a, b, visited) {
       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 (stringKeysA.length !== stringKeysB.length) return false;
       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 (!Object.getOwnPropertySymbols(objB).includes(key)) return false;
+        if (!symbolKeysBSet.has(key)) return false;
       }
       for (const key of stringKeysA) {
-        if (!deepEqualInner(objA[key], objB[key], visited)) {
+        if (!deepEqualInner(recA[key], recB[key], visited)) {
           return false;
         }
       }
       for (const key of symbolKeysA) {
-        if (!deepEqualInner(objA[key], objB[key], visited)) {
+        if (!deepEqualInner(recA[key], recB[key], visited)) {
           return false;
         }
       }
@@ -213,6 +165,293 @@ function deepEqualInner(a, b, visited) {
 }
 __name(deepEqualInner, "deepEqualInner");
 
+// 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);
+}
+__name(deepOmit, "deepOmit");
+function omitInternal(value, options, ignoreKeys, path, visited) {
+  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]") {
+    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);
+      path.pop();
+    }
+    return clone2;
+  }
+  if (isBuiltInObject(obj, tag)) {
+    const builtInClone = cloneBuiltIn(obj, tag);
+    visited.set(obj, builtInClone);
+    return builtInClone;
+  }
+  const clone = Object.create(Object.getPrototypeOf(obj));
+  visited.set(obj, clone);
+  const stringKeys = Object.keys(obj);
+  const symbolKeys = Object.getOwnPropertySymbols(obj);
+  for (const key of stringKeys) {
+    if (shouldIgnoreKey(key, path, ignoreKeys, options)) continue;
+    path.push(key);
+    assignOwn(
+      clone,
+      key,
+      omitInternal(
+        obj[key],
+        options,
+        ignoreKeys,
+        path,
+        visited
+      )
+    );
+    path.pop();
+  }
+  for (const key of symbolKeys) {
+    if (shouldIgnoreKey(key, path, ignoreKeys, options)) continue;
+    path.push(key);
+    assignOwn(
+      clone,
+      key,
+      omitInternal(
+        obj[key],
+        options,
+        ignoreKeys,
+        path,
+        visited
+      )
+    );
+    path.pop();
+  }
+  return clone;
+}
+__name(omitInternal, "omitInternal");
+function assignOwn(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  });
+}
+__name(assignOwn, "assignOwn");
+function cloneBuiltIn(obj, tag) {
+  switch (tag) {
+    case "[object Date]":
+      return new Date(obj.getTime());
+    case "[object RegExp]": {
+      const re = obj;
+      const copy = new RegExp(re.source, re.flags);
+      copy.lastIndex = re.lastIndex;
+      return copy;
+    }
+    case "[object Map]": {
+      const m = obj;
+      return new Map(m);
+    }
+    case "[object Set]": {
+      const s = obj;
+      return new Set(s);
+    }
+    default:
+      return structuredClone(obj);
+  }
+}
+__name(cloneBuiltIn, "cloneBuiltIn");
+function shouldIgnoreKey(key, path, ignoreKeys, options) {
+  if (ignoreKeys?.has(key)) return true;
+  if (options.ignoreKeyPredicate?.(key, path)) return true;
+  return false;
+}
+__name(shouldIgnoreKey, "shouldIgnoreKey");
+
+// src/utils/array/deep-equal-except.ts
+function deepEqualExcept(a, b, options) {
+  const prunedA = deepOmit(a, options);
+  const prunedB = deepOmit(b, options);
+  return deepEqual(prunedA, prunedB);
+}
+__name(deepEqualExcept, "deepEqualExcept");
+function deepFreeze(obj, visited = /* @__PURE__ */ new WeakSet()) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (visited.has(obj)) {
+    return obj;
+  }
+  visited.add(obj);
+  const keys = Reflect.ownKeys(obj);
+  for (const key of keys) {
+    const value = obj[key];
+    if (value !== null && typeof value === "object") {
+      deepFreeze(value, visited);
+    }
+  }
+  return Object.freeze(obj);
+}
+__name(deepFreeze, "deepFreeze");
+function vo(t) {
+  return deepFreeze(structuredClone(t));
+}
+__name(vo, "vo");
+function voEquals(a, b) {
+  return deepEqual(a, b);
+}
+__name(voEquals, "voEquals");
+function voEqualsExcept(a, b, options) {
+  return deepEqualExcept(a, b, options);
+}
+__name(voEqualsExcept, "voEqualsExcept");
+function voWithValidation(t, validate, errorMessage) {
+  if (!validate(t)) {
+    return err(
+      errorMessage ?? `Validation failed for value object: ${JSON.stringify(t)}`
+    );
+  }
+  return ok(vo(t));
+}
+__name(voWithValidation, "voWithValidation");
+var ValueObject = class {
+  static {
+    __name(this, "ValueObject");
+  }
+  props;
+  /**
+   * Creates a new ValueObject.
+   * The properties are deeply frozen to ensure immutability.
+   *
+   * @param props - The properties of the value object
+   * @example
+   * ```ts
+   * class Money extends ValueObject<{ amount: number; currency: string }> {
+   *   constructor(props: { amount: number; currency: string }) {
+   *     super(props);
+   *   }
+   *
+   *   protected validate(props: { amount: number; currency: string }): void {
+   *     if (props.amount < 0) throw new Error("Amount cannot be negative");
+   *   }
+   * }
+   * ```
+   */
+  constructor(props) {
+    this.validate(props);
+    this.props = deepFreeze({ ...props });
+  }
+  /**
+   * Optional validation hook that can be overridden by subclasses.
+   * Should throw an error if validation fails.
+   *
+   * @param props - The properties to validate
+   * @throws Error if validation fails
+   */
+  validate(props) {
+  }
+  /**
+   * Checks if this value object is equal to another.
+   * Uses deep equality comparison on the properties and checks for constructor equality.
+   *
+   * @param other - The other value object to compare
+   * @returns true if the properties are deeply equal and constructors match
+   */
+  equals(other) {
+    if (other === null || other === void 0) {
+      return false;
+    }
+    if (this.constructor !== other.constructor) {
+      return false;
+    }
+    return deepEqual(this.props, other.props);
+  }
+  /**
+   * Creates a clone of the value object with optional property overrides.
+   *
+   * @param props - Optional properties to override
+   * @returns A new instance of the value object
+   */
+  clone(props) {
+    const Constructor = this.constructor;
+    return new Constructor({ ...this.props, ...props || {} });
+  }
+  /**
+   * Serializes the value object to its raw properties for JSON operations.
+   *
+   * @returns The raw properties object
+   */
+  toJSON() {
+    return this.props;
+  }
+};
+
+// src/aggregate/domain-event.ts
+var defaultEventIdFactory = /* @__PURE__ */ __name(() => crypto.randomUUID(), "defaultEventIdFactory");
+var currentEventIdFactory = defaultEventIdFactory;
+function setEventIdFactory(factory) {
+  currentEventIdFactory = factory;
+}
+__name(setEventIdFactory, "setEventIdFactory");
+function resetEventIdFactory() {
+  currentEventIdFactory = defaultEventIdFactory;
+}
+__name(resetEventIdFactory, "resetEventIdFactory");
+var defaultClockFactory = /* @__PURE__ */ __name(() => /* @__PURE__ */ new Date(), "defaultClockFactory");
+var currentClockFactory = defaultClockFactory;
+function setClockFactory(factory) {
+  currentClockFactory = factory;
+}
+__name(setClockFactory, "setClockFactory");
+function resetClockFactory() {
+  currentClockFactory = defaultClockFactory;
+}
+__name(resetClockFactory, "resetClockFactory");
+function createDomainEvent(type, payload, options) {
+  const event = {
+    eventId: options?.eventId ?? currentEventIdFactory(),
+    type,
+    aggregateId: options?.aggregateId,
+    aggregateType: options?.aggregateType,
+    payload,
+    occurredAt: options?.occurredAt ?? currentClockFactory(),
+    version: options?.version ?? 1,
+    metadata: options?.metadata
+  };
+  return deepFreeze(event);
+}
+__name(createDomainEvent, "createDomainEvent");
+function createDomainEventWithMetadata(type, payload, metadata, options) {
+  return createDomainEvent(type, payload, {
+    ...options,
+    metadata
+  });
+}
+__name(createDomainEventWithMetadata, "createDomainEventWithMetadata");
+function copyMetadata(sourceEvent, additionalMetadata) {
+  return {
+    ...sourceEvent.metadata ?? {},
+    ...additionalMetadata ?? {}
+  };
+}
+__name(copyMetadata, "copyMetadata");
+function mergeMetadata(...metadataObjects) {
+  return Object.assign({}, ...metadataObjects.filter(Boolean));
+}
+__name(mergeMetadata, "mergeMetadata");
+
+// src/aggregate/aggregate.ts
+function sameVersion(a, b) {
+  return a.id === b.id && a.version === b.version;
+}
+__name(sameVersion, "sameVersion");
+
 // src/entity/entity.ts
 var Entity = class {
   static {
@@ -221,7 +460,15 @@ var Entity = class {
   id;
   /**
    * Returns the current state of the entity.
-   * State is readonly from outside to enforce encapsulation.
+   *
+   * 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
+   * deeply) or reach for a structural-sharing library like Immer at the
+   * App layer. The shallow contract is intentional: deep freezing on
+   * every state write is too expensive for hot paths, and DDD aggregates
+   * normally treat their own state as private (`Tell, Don't Ask`).
    */
   get state() {
     return this._state;
@@ -236,16 +483,29 @@ var Entity = class {
       throw new Error("Entity ID cannot be null or undefined");
     }
     this.id = id;
-    this._state = initialState;
+    this._state = freezeShallow(initialState);
     this.validateState(this._state);
   }
   /**
-   * Optional validation hook to ensure state invariants.
-   * Called during construction and whenever helpful.
-   * Override this method to implement validation logic.
+   * Optional validation hook to ensure state invariants. Called during
+   * construction (from `Entity`'s constructor) and again on every
+   * `setState()` call. Throw to reject invalid state.
+   *
+   * **⚠️ 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.
+   * The `state` argument is the single source of truth; treat the method
+   * as pure with respect to `this`.
+   *
+   * If your invariants genuinely depend on per-instance configuration
+   * that isn't part of the state, pass that configuration into the state
+   * itself (DDD-canonical: the aggregate's state contains everything it
+   * needs) or perform the additional check after construction in a
+   * dedicated factory method.
    *
    * @param state - The state to validate
-   * @throws Error if validation fails
+   * @throws Error (or `DomainError` subclass) if validation fails
    */
   validateState(_state) {
   }
@@ -258,31 +518,38 @@ var Entity = class {
    */
   setState(newState) {
     this.validateState(newState);
-    this._state = newState;
+    this._state = freezeShallow(newState);
   }
 };
+function freezeShallow(value) {
+  if (value !== null && typeof value === "object") {
+    return Object.freeze(value);
+  }
+  return value;
+}
+__name(freezeShallow, "freezeShallow");
 function sameEntity(a, b) {
-  return deepEqual(a.id, b.id);
+  return a.id === b.id;
 }
 __name(sameEntity, "sameEntity");
 function findEntityById(entities, id) {
-  return entities.find((entity) => deepEqual(entity.id, id));
+  return entities.find((entity) => entity.id === id);
 }
 __name(findEntityById, "findEntityById");
 function hasEntityId(entities, id) {
-  return entities.some((entity) => deepEqual(entity.id, id));
+  return entities.some((entity) => entity.id === id);
 }
 __name(hasEntityId, "hasEntityId");
 function removeEntityById(entities, id) {
-  return entities.filter((entity) => !deepEqual(entity.id, id));
+  return entities.filter((entity) => entity.id !== id);
 }
 __name(removeEntityById, "removeEntityById");
 function updateEntityById(entities, id, updater) {
-  return entities.map((entity) => deepEqual(entity.id, id) ? updater(entity) : entity);
+  return entities.map((entity) => entity.id === id ? updater(entity) : entity);
 }
 __name(updateEntityById, "updateEntityById");
 function replaceEntityById(entities, id, replacement) {
-  return entities.map((entity) => deepEqual(entity.id, id) ? replacement : entity);
+  return entities.map((entity) => entity.id === id ? replacement : entity);
 }
 __name(replaceEntityById, "replaceEntityById");
 function entityIds(entities) {
@@ -310,7 +577,7 @@ var AggregateRoot = class extends Entity {
    * These events are side-effects of state changes.
    */
   get domainEvents() {
-    return this._domainEvents;
+    return Object.freeze(this._domainEvents.slice());
   }
   /**
    * Clears the list of recorded domain events.
@@ -319,16 +586,105 @@ var AggregateRoot = class extends Entity {
   clearDomainEvents() {
     this._domainEvents = [];
   }
+  /**
+   * Post-save hook called by a `Repository.save()` implementation to push
+   * the persisted version back into the in-memory aggregate and clear the
+   * recorded domain events (they are now safely on the write side / in
+   * the outbox).
+   *
+   * Use this so `save()` can keep its `Promise<void>` return type: the
+   * caller holds the aggregate reference, which is up to date after this
+   * call.
+   */
+  markPersisted(version) {
+    this.setVersion(version);
+    this._domainEvents = [];
+  }
+  /**
+   * Mutates state and records the resulting domain events in the
+   * **canonical record-after-mutation order**. Use this instead of calling
+   * `setState` + `addDomainEvent` separately and you cannot trip the
+   * "event for a fact that never happened" footgun.
+   *
+   * Order of operations:
+   *  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`.
+   *
+   * `commit()` **always bumps the version**, regardless of the aggregate's
+   * `autoVersionBump` config. Recording a domain event implies "something
+   * happened that the outside world cares about", and optimistic-
+   * concurrency callers must see a fresh version every time. The config
+   * still governs the un-coupled `setState` path. If you need to mutate
+   * state without bumping (e.g. cosmetic caches), call `setState(newState,
+   * false)` and skip `commit` entirely.
+   *
+   * `events` accepts a single event or an array. Omit it (or pass `[]`)
+   * for state-only mutations.
+   *
+   * @example
+   * ```ts
+   * confirm(): void {
+   *   if (this.state.status === "confirmed") {
+   *     throw new OrderAlreadyConfirmedError(this.id);
+   *   }
+   *   this.commit(
+   *     { ...this.state, status: "confirmed" },
+   *     { type: "OrderConfirmed", orderId: this.id },
+   *   );
+   * }
+   * ```
+   *
+   * `EventSourcedAggregate.apply()` enforces the same ordering
+   * structurally; `commit()` is the opt-in equivalent on `AggregateRoot`,
+   * where `setState` and `addDomainEvent` are otherwise decoupled and the
+   * ordering is convention-only.
+   *
+   * @param newState - The new state (validated by `validateState`)
+   * @param events - One event, an array of events, or none (default)
+   */
+  commit(newState, events = []) {
+    this.setState(newState, true);
+    const list = Array.isArray(events) ? events : [events];
+    for (const ev of list) {
+      this.addDomainEvent(ev);
+    }
+  }
   constructor(id, initialState, config) {
     super(id, initialState);
     this._config = config ?? {};
     this._autoVersionBump = this._config.autoVersionBump ?? false;
   }
   /**
-   * Adds a domain event to the aggregate's list of changes.
-   * Use this to record side-effects that should be published.
+   * Records a domain event for later publication.
+   *
+   * **Ordering: record AFTER state mutation.** Vernon (IDDD §8) is
+   * explicit: a domain event describes something that has just happened
+   * to the aggregate — its existence implies the state change already
+   * occurred. Concretely:
+   *
+   * ```ts
+   * confirm(): void {
+   *   if (this.state.status === "confirmed") {
+   *     throw new OrderAlreadyConfirmedError(this.id);
+   *   }
+   *   this.setState({ ...this.state, status: "confirmed" }, true);
+   *   this.addDomainEvent({ type: "OrderConfirmed", orderId: this.id });
+   *   // ↑ post-mutation. The event represents the committed fact.
+   * }
+   * ```
+   *
+   * Recording before mutation is a footgun: if a subsequent invariant
+   * check throws, the event has already been queued but the state never
+   * actually changed — consumers see an event for a fact that did not
+   * happen.
    *
-   * @param event - The domain event to add
+   * `EventSourcedAggregate.apply()` enforces this ordering structurally;
+   * `AggregateRoot` leaves it as a convention because the state-mutation
+   * path (`setState`) is decoupled from event recording.
+   *
+   * @param event - The domain event to record
    */
   addDomainEvent(event) {
     this._domainEvents.push(event);
@@ -394,20 +750,65 @@ var AggregateRoot = class extends Entity {
    */
   restoreFromSnapshot(snapshot) {
     this.validateState(snapshot.state);
-    this._state = snapshot.state;
+    this._state = freezeShallow(snapshot.state);
     this.setVersion(snapshot.version);
   }
 };
-
-// src/core/result/result.ts
-function ok(value) {
-  return { ok: true, value };
-}
-__name(ok, "ok");
-function err(error) {
-  return { ok: false, error };
-}
-__name(err, "err");
+var DomainError = class extends BaseError {
+  static {
+    __name(this, "DomainError");
+  }
+};
+var InfrastructureError = class extends BaseError {
+  static {
+    __name(this, "InfrastructureError");
+  }
+};
+var MissingHandlerError = class extends BaseError {
+  constructor(eventType) {
+    super(`Missing handler for event type: ${eventType}`);
+    this.eventType = eventType;
+  }
+  static {
+    __name(this, "MissingHandlerError");
+  }
+};
+var AggregateNotFoundError = class extends InfrastructureError {
+  constructor(aggregateType, id) {
+    super(`Aggregate not found: ${aggregateType}(${id})`);
+    this.aggregateType = aggregateType;
+    this.id = id;
+    this.withUserMessage(
+      `The requested ${aggregateType.toLowerCase()} could not be found.`
+    );
+  }
+  static {
+    __name(this, "AggregateNotFoundError");
+  }
+};
+var ConcurrencyConflictError = class extends InfrastructureError {
+  constructor(aggregateType, aggregateId, expectedVersion, actualVersion) {
+    super(
+      `Concurrency conflict on ${aggregateType}(${aggregateId}): expected version ${expectedVersion}, actual ${actualVersion}`
+    );
+    this.aggregateType = aggregateType;
+    this.aggregateId = aggregateId;
+    this.expectedVersion = expectedVersion;
+    this.actualVersion = actualVersion;
+    this.withUserMessage(
+      "This resource was updated by another request. Please reload and try again."
+    );
+  }
+  static {
+    __name(this, "ConcurrencyConflictError");
+  }
+  /**
+   * Marks this error as retryable so `isRetryable(err)` returns
+   * true. The canonical OCC pattern is to reload the aggregate, re-apply
+   * the use case, and retry on this exception.
+   */
+  retryable = true;
+};
 
 // src/aggregate/event-sourced-aggregate.ts
 var EventSourcedAggregate = class extends Entity {
@@ -426,73 +827,69 @@ var EventSourcedAggregate = class extends Entity {
   _pendingEvents = [];
   _autoVersionBump;
   get pendingEvents() {
-    return this._pendingEvents;
+    return Object.freeze(this._pendingEvents.slice());
   }
   clearPendingEvents() {
     this._pendingEvents = [];
   }
+  /**
+   * Post-save hook called by a `Repository.save()` implementation to push
+   * the persisted version back into the in-memory aggregate and clear the
+   * pending events (they are now in the event store / outbox). Lets
+   * `save()` keep its `Promise<void>` return type.
+   */
+  markPersisted(version) {
+    this.setVersion(version);
+    this._pendingEvents = [];
+  }
   constructor(id, initialState, config) {
     super(id, initialState);
     this._autoVersionBump = config?.autoVersionBump ?? true;
   }
   // --- Event application ---
   /**
-   * Validates an event before it is applied.
-   * Override this method to add custom validation logic.
-   * Return `ok(true)` if the event is valid, `err(message)` otherwise.
+   * Validates an event before it is applied. Default is no-op.
+   * Subclasses override to throw a concrete `DomainError` subclass when
+   * the event violates an invariant in the current state.
    */
   validateEvent(_event) {
-    return ok(true);
   }
   /**
-   * Applies an event to change the state and adds it to pending events.
-   * Returns a Result type instead of throwing an error.
+   * Applies an event: validates, locates the handler, computes the next
+   * state, then commits state + pending event + version bump atomically.
+   *
+   * 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
+   * 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.
    *
    * @param event - The domain event to apply
-   * @param isNew - Whether the event is new (needs persisting) or from history replay
+   * @param isNew - Whether the event is new (needs persisting) or replayed from history
    */
   apply(event, isNew = true) {
-    const validation = this.validateEvent(event);
-    if (!validation.ok) {
-      return err(
-        `Event validation failed for ${event.type}: ${validation.error}`
-      );
-    }
-    const handler = this.handlers[event.type];
-    if (!handler) {
-      return err(`Missing handler for event type: ${event.type}`);
-    }
-    this._state = handler(
-      this._state,
-      event
-    );
-    if (isNew) {
-      this._pendingEvents.push(event);
-      if (this._autoVersionBump) {
-        this.setVersion(this._version + 1);
-      }
-    }
-    return ok();
+    this.dispatchAndCommit(event, isNew);
   }
   /**
-   * Applies an event to change the state and adds it to pending events.
-   * Throws an error if validation fails or handler is missing.
+   * Internal dispatch path used by `apply()` and the replay methods
+   * (`loadFromHistory`, `restoreFromSnapshotWithEvents`). The replay loop
+   * iterates over `TEvent[]` and therefore cannot supply a narrowed `K`
+   * generic, so this helper accepts `TEvent` and the discriminator is
+   * resolved via the (statically-sound) `handlers` map.
    */
-  applyUnsafe(event, isNew = true) {
-    const validation = this.validateEvent(event);
-    if (!validation.ok) {
-      throw new Error(
-        `Event validation failed for ${event.type}: ${validation.error}`
-      );
-    }
+  dispatchAndCommit(event, isNew) {
+    this.validateEvent(event);
     const handler = this.handlers[event.type];
     if (!handler) {
-      throw new Error(`Missing handler for event type: ${event.type}`);
+      throw new MissingHandlerError(event.type);
     }
-    this._state = handler(
-      this._state,
-      event
-    );
+    const nextState = handler(this._state, event);
+    this._state = freezeShallow(nextState);
     if (isNew) {
       this._pendingEvents.push(event);
       if (this._autoVersionBump) {
@@ -509,17 +906,27 @@ var EventSourcedAggregate = class extends Entity {
   }
   // --- History & Snapshots ---
   /**
-   * Reconstitutes the aggregate from an event history.
-   * Sets the version to the number of events in the history.
+   * Reconstitutes the aggregate from an event history. Catches `DomainError`
+   * 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.
+   *
+   * 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) {
+    const startVersion = this._version;
     for (const event of history) {
-      const result = this.apply(event, false);
-      if (!result.ok) {
-        return result;
+      try {
+        this.dispatchAndCommit(event, false);
+      } catch (e) {
+        if (e instanceof DomainError) return err(e);
+        throw e;
       }
     }
-    this.setVersion(history.length);
+    this.setVersion(startVersion + history.length);
     return ok();
   }
   hasPendingEvents() {
@@ -542,23 +949,34 @@ var EventSourcedAggregate = class extends Entity {
     };
   }
   /**
-   * Restores the aggregate from a snapshot and applies events that occurred after.
+   * Restores the aggregate from a snapshot and applies events that occurred
+   * after. Same infrastructure-boundary semantics as `loadFromHistory`:
+   * catches `DomainError` and returns it as an `Err`; non-domain throws
+   * propagate.
+   *
+   * All-or-nothing: if any event mid-stream throws a `DomainError`, the
+   * aggregate is rolled back to its pre-call state + version. Partial
+   * restoration is never observable to the caller.
    */
   restoreFromSnapshotWithEvents(snapshot, eventsAfterSnapshot) {
-    this._state = snapshot.state;
+    const previousState = this._state;
+    const previousVersion = this._version;
+    this._state = freezeShallow(snapshot.state);
     this.setVersion(snapshot.version);
     for (const event of eventsAfterSnapshot) {
-      const result = this.apply(event, false);
-      if (!result.ok) {
-        return result;
+      try {
+        this.dispatchAndCommit(event, false);
+      } catch (e) {
+        this._state = previousState;
+        this.setVersion(previousVersion);
+        if (e instanceof DomainError) return err(e);
+        throw e;
       }
     }
     this.setVersion(snapshot.version + eventsAfterSnapshot.length);
     return ok();
   }
 };
-
-// src/app/command-bus.ts
 var CommandBus = class {
   static {
     __name(this, "CommandBus");
@@ -584,17 +1002,18 @@ var CommandBus = class {
 };
 
 // src/app/handler.ts
-function withCommit(deps, fn) {
-  return deps.uow.transactional(async () => {
-    const { result, events } = await fn();
-    await deps.outbox.add(events);
-    if (deps.bus) await deps.bus.publish(events);
-    return result;
+async function withCommit(deps, fn) {
+  const { result, events } = await deps.scope.transactional(async () => {
+    const fnResult = await fn();
+    await deps.outbox.add(fnResult.events);
+    return fnResult;
   });
+  if (deps.bus) {
+    await deps.bus.publish(events);
+  }
+  return result;
 }
 __name(withCommit, "withCommit");
-
-// src/app/query-bus.ts
 var QueryBus = class {
   static {
     __name(this, "QueryBus");
@@ -627,12 +1046,6 @@ var QueryBus = class {
   }
 };
 
-// src/core/guard.ts
-function guard(cond, error) {
-  return cond ? ok(true) : err(error);
-}
-__name(guard, "guard");
-
 // src/events/event-bus.ts
 var EventBusImpl = class {
   static {
@@ -643,32 +1056,82 @@ var EventBusImpl = class {
   subscribe(eventType, handler) {
     const type = eventType;
     if (!this.handlers.has(type)) {
-      this.handlers.set(type, /* @__PURE__ */ new Set());
+      this.handlers.set(type, []);
     }
     const handlersForType = this.handlers.get(type);
-    handlersForType.add(handler);
+    const casted = handler;
+    handlersForType.push(casted);
+    let removed = false;
     return () => {
-      handlersForType.delete(handler);
-      if (handlersForType.size === 0) {
+      if (removed) return;
+      const idx = handlersForType.indexOf(casted);
+      if (idx !== -1) {
+        handlersForType.splice(idx, 1);
+        removed = true;
+      }
+      if (handlersForType.length === 0) {
         this.handlers.delete(type);
       }
     };
   }
-  once(eventType) {
-    return new Promise((resolve) => {
-      const unsubscribe = this.subscribe(eventType, (event) => {
+  once(eventType, options) {
+    return new Promise((resolve, reject) => {
+      if (options?.signal?.aborted) {
+        reject(options.signal.reason ?? new Error("EventBus.once aborted"));
+        return;
+      }
+      let timer;
+      let settled = false;
+      let abortListener;
+      const cleanup = /* @__PURE__ */ __name(() => {
+        if (settled) return;
+        settled = true;
         unsubscribe();
+        if (timer !== void 0) clearTimeout(timer);
+        if (abortListener && options?.signal) {
+          options.signal.removeEventListener("abort", abortListener);
+        }
+      }, "cleanup");
+      const unsubscribe = this.subscribe(eventType, (event) => {
+        cleanup();
         resolve(event);
       });
+      if (options?.signal) {
+        abortListener = /* @__PURE__ */ __name(() => {
+          cleanup();
+          reject(
+            options.signal.reason ?? new Error("EventBus.once aborted")
+          );
+        }, "abortListener");
+        options.signal.addEventListener("abort", abortListener);
+      }
+      if (typeof options?.timeoutMs === "number") {
+        timer = setTimeout(() => {
+          cleanup();
+          reject(
+            new Error(
+              `EventBus.once timed out after ${options.timeoutMs}ms waiting for "${eventType}"`
+            )
+          );
+        }, options.timeoutMs);
+      }
     });
   }
+  /**
+   * See {@link EventBus.publish} for the full ordering / parallelism /
+   * error-aggregation contract this implementation realises:
+   *  - events in input order, sequentially;
+   *  - handlers within one event in parallel via `Promise.allSettled`;
+   *  - errors collected and thrown after the batch (single Error, or
+   *    `AggregateError` for multiple failures).
+   */
   async publish(events) {
     const errors = [];
     for (const event of events) {
       const handlersForType = this.handlers.get(event.type);
       if (handlersForType) {
         const results = await Promise.allSettled(
-          Array.from(handlersForType).map((handler) => handler(event))
+          handlersForType.slice().map((handler) => handler(event))
         );
         for (const result of results) {
           if (result.status === "rejected") {
@@ -688,195 +1151,6 @@ var EventBusImpl = class {
   }
 };
 
-// src/utils/array/deep-omit.ts
-function deepOmit(value, options) {
-  const visited = /* @__PURE__ */ new WeakMap();
-  return omitInternal(value, options, [], visited);
-}
-__name(deepOmit, "deepOmit");
-function omitInternal(value, options, path, visited) {
-  if (value === null) return value;
-  const type = typeof value;
-  if (type !== "object") return value;
-  const obj = value;
-  const cached = visited.get(obj);
-  if (cached !== void 0) {
-    return cached;
-  }
-  const tag = Object.prototype.toString.call(obj);
-  if (tag === "[object Array]") {
-    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, path, visited);
-      path.pop();
-    }
-    return clone2;
-  }
-  if (isBuiltInObject(obj, tag)) {
-    return value;
-  }
-  const clone = Object.create(Object.getPrototypeOf(obj));
-  visited.set(obj, clone);
-  const stringKeys = Object.keys(obj);
-  const symbolKeys = Object.getOwnPropertySymbols(obj);
-  const keys = [...stringKeys, ...symbolKeys];
-  for (const key of keys) {
-    if (shouldIgnoreKey(key, path, options)) continue;
-    path.push(key);
-    clone[key] = omitInternal(
-      obj[key],
-      options,
-      path,
-      visited
-    );
-    path.pop();
-  }
-  return clone;
-}
-__name(omitInternal, "omitInternal");
-function shouldIgnoreKey(key, path, options) {
-  if (options.ignoreKeys?.includes(key)) {
-    return true;
-  }
-  if (options.ignoreKeyPredicate?.(key, path)) {
-    return true;
-  }
-  return false;
-}
-__name(shouldIgnoreKey, "shouldIgnoreKey");
-
-// src/utils/array/deep-equal-except.ts
-function deepEqualExcept(a, b, options) {
-  const prunedA = deepOmit(a, options);
-  const prunedB = deepOmit(b, options);
-  return deepEqual(prunedA, prunedB);
-}
-__name(deepEqualExcept, "deepEqualExcept");
-
-// src/value-object/value-object.ts
-function deepFreeze(obj, visited = /* @__PURE__ */ new WeakSet()) {
-  if (obj === null || typeof obj !== "object") {
-    return obj;
-  }
-  if (visited.has(obj)) {
-    return obj;
-  }
-  visited.add(obj);
-  const propNames = Object.getOwnPropertyNames(obj);
-  for (const name of propNames) {
-    const value = obj[name];
-    if (value && (typeof value === "object" || Array.isArray(value))) {
-      deepFreeze(value, visited);
-    }
-  }
-  return Object.freeze(obj);
-}
-__name(deepFreeze, "deepFreeze");
-function vo(t) {
-  return deepFreeze({ ...t });
-}
-__name(vo, "vo");
-function voEquals(a, b) {
-  return deepEqual(a, b);
-}
-__name(voEquals, "voEquals");
-function voEqualsExcept(a, b, options) {
-  return deepEqualExcept(a, b, options);
-}
-__name(voEqualsExcept, "voEqualsExcept");
-function voWithValidation(t, validate, errorMessage) {
-  if (!validate(t)) {
-    return err(
-      errorMessage ?? `Validation failed for value object: ${JSON.stringify(t)}`
-    );
-  }
-  return ok(vo(t));
-}
-__name(voWithValidation, "voWithValidation");
-function voWithValidationUnsafe(t, validate, errorMessage) {
-  if (!validate(t)) {
-    throw new Error(
-      errorMessage ?? `Validation failed for value object: ${JSON.stringify(t)}`
-    );
-  }
-  return vo(t);
-}
-__name(voWithValidationUnsafe, "voWithValidationUnsafe");
-var ValueObject = class {
-  static {
-    __name(this, "ValueObject");
-  }
-  props;
-  /**
-   * Creates a new ValueObject.
-   * The properties are deeply frozen to ensure immutability.
-   *
-   * @param props - The properties of the value object
-   * @example
-   * ```ts
-   * class Money extends ValueObject<{ amount: number; currency: string }> {
-   *   constructor(props: { amount: number; currency: string }) {
-   *     super(props);
-   *   }
-   *
-   *   protected validate(props: { amount: number; currency: string }): void {
-   *     if (props.amount < 0) throw new Error("Amount cannot be negative");
-   *   }
-   * }
-   * ```
-   */
-  constructor(props) {
-    this.validate(props);
-    this.props = deepFreeze({ ...props });
-  }
-  /**
-   * Optional validation hook that can be overridden by subclasses.
-   * Should throw an error if validation fails.
-   *
-   * @param props - The properties to validate
-   * @throws Error if validation fails
-   */
-  validate(props) {
-  }
-  /**
-   * Checks if this value object is equal to another.
-   * Uses deep equality comparison on the properties and checks for constructor equality.
-   *
-   * @param other - The other value object to compare
-   * @returns true if the properties are deeply equal and constructors match
-   */
-  equals(other) {
-    if (other === null || other === void 0) {
-      return false;
-    }
-    if (this.constructor !== other.constructor) {
-      return false;
-    }
-    return deepEqual(this.props, other.props);
-  }
-  /**
-   * Creates a clone of the value object with optional property overrides.
-   *
-   * @param props - Optional properties to override
-   * @returns A new instance of the value object
-   */
-  clone(props) {
-    const Constructor = this.constructor;
-    return new Constructor({ ...this.props, ...props || {} });
-  }
-  /**
-   * Serializes the value object to its raw properties for JSON operations.
-   *
-   * @returns The raw properties object
-   */
-  toJSON() {
-    return this.props;
-  }
-};
-
-export { AggregateRoot, CommandBus, Entity, EventBusImpl, EventSourcedAggregate, QueryBus, ValueObject, aggregate, bump, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepFreeze, entityIds, findEntityById, guard, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, sameEntity, sameVersion, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, voWithValidationUnsafe, withCommit };
+export { AggregateNotFoundError, AggregateRoot, CommandBus, ConcurrencyConflictError, DomainError, Entity, EventBusImpl, EventSourcedAggregate, 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, voWithValidation, withCommit };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map