@shirudo/ddd-kit 1.1.0 → 1.2.0

package/dist/index.js

@@ -474,7 +474,7 @@ __name(deepFreeze, "deepFreeze");
 function cloneForVo(value, visited) {
   if (typeof value === "function") {
     throw new TypeError(
-      "vo() does not accept function values \u2014 Value Objects are data, not behaviour"
+      "vo() does not accept function values: Value Objects are data, not behaviour"
     );
   }
   if (value === null || typeof value !== "object") {
@@ -512,7 +512,7 @@ function cloneForVo(value, visited) {
     }
     if (tag === "[object Promise]" || tag === "[object WeakMap]" || tag === "[object WeakSet]") {
       throw new TypeError(
-        `vo() cannot clone a ${tag.slice(8, -1)} \u2014 Value Objects are plain data`
+        `vo() cannot clone a ${tag.slice(8, -1)}: Value Objects are plain data`
       );
     }
     const builtInClone = structuredClone(obj);
@@ -575,7 +575,7 @@ var ValueObject = class {
   /**
    * Creates a new ValueObject.
    * The properties are deep-cloned (prototype-preserving) and then deeply
-   * frozen — the caller's own object graph is never frozen or mutated,
+   * 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
@@ -701,10 +701,11 @@ function createDomainEvent(type, payload, options) {
     aggregateId: options?.aggregateId,
     aggregateType: options?.aggregateType,
     payload,
-    // Defensive copy — the event must not share the caller's live Date
+    // 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);
@@ -758,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
@@ -779,7 +780,7 @@ var Entity = class {
    * **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
+   * 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}.
    */
@@ -799,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`.
    *
@@ -821,7 +822,7 @@ var Entity = class {
    *
    * 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.
+   * ownership transfer and is frozen in place; see the constructor.
    *
    * @param newState - The new state
    */
@@ -888,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;
@@ -908,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() {
@@ -926,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
@@ -952,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.
@@ -969,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);
@@ -977,13 +988,13 @@ 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
@@ -995,7 +1006,7 @@ var BaseAggregate = class extends Entity {
    * **`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
@@ -1004,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
@@ -1017,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
@@ -1027,7 +1038,7 @@ 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.
    *
@@ -1045,7 +1056,7 @@ var BaseAggregate = class extends Entity {
    * 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
+   * 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
@@ -1076,8 +1087,8 @@ var BaseAggregate = class extends Entity {
    * 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
@@ -1101,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, {
@@ -1115,7 +1126,7 @@ var BaseAggregate = class extends Entity {
 function assertSnapshotSafe(value, path, seen) {
   if (typeof value === "function") {
     throw new Error(
-      `createSnapshot: state${path} is a function \u2014 snapshot state must be plain, serialisable data. Override toSnapshotState()/fromSnapshotState() to map it.`
+      `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;
@@ -1149,12 +1160,12 @@ function assertSnapshotSafe(value, path, seen) {
     }
     if (tag === "[object Promise]" || tag === "[object WeakMap]" || tag === "[object WeakSet]") {
       throw new Error(
-        `createSnapshot: state${path} is a ${tag.slice(8, -1)} \u2014 it cannot be cloned or persisted. Override toSnapshotState()/fromSnapshotState() to map it.`
+        `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 \u2014 structuredClone downgrades Error subclasses to plain Error and silently drops custom fields, so the restored value would not round-trip. Override toSnapshotState()/fromSnapshotState() to map it to plain data.`
+        `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;
@@ -1166,7 +1177,7 @@ function assertSnapshotSafe(value, path, seen) {
       if (!descriptor?.enumerable) continue;
       if (typeof key === "symbol") {
         throw new Error(
-          `createSnapshot: state${path} has a symbol-keyed property (${String(key)}) \u2014 structuredClone silently drops symbol keys, so the snapshot would lose state. Override toSnapshotState()/fromSnapshotState() to map it.`
+          `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(
@@ -1179,7 +1190,7 @@ function assertSnapshotSafe(value, path, seen) {
   }
   const name = proto.constructor?.name || "anonymous class";
   throw new Error(
-    `createSnapshot: state${path} is a class instance (${name}) \u2014 structuredClone would strip its prototype and methods, producing a snapshot that breaks on the first method call after restore. Override toSnapshotState()/fromSnapshotState() to map child entities to plain data.`
+    `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");
@@ -1190,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
@@ -1201,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`.
@@ -1260,7 +1386,7 @@ 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.
    *
@@ -1273,6 +1399,33 @@ var AggregateRoot = class extends BaseAggregate {
     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");
@@ -1285,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(
@@ -1305,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;
@@ -1349,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
@@ -1385,12 +1573,12 @@ 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 — same contract as
+   * 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.)
@@ -1489,12 +1677,25 @@ var CommandBus = class {
 
 // 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 = [];
@@ -1504,19 +1705,28 @@ 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) {
     try {
-      agg.markPersisted(agg.version);
+      if (deleted.has(agg)) {
+        agg.clearPendingEvents();
+      } else {
+        agg.markPersisted(agg.version);
+      }
     } catch {
     }
   }
@@ -1533,6 +1743,302 @@ async function withCommit(deps, fn) {
   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");
@@ -1657,7 +2163,7 @@ var EventBusImpl = class {
           if (result.status === "rejected") {
             errors.push(
               result.reason instanceof Error ? result.reason : (
-                // Attach the raw reason as cause — a handler
+                // 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), {
@@ -1708,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