@shirudo/ddd-kit 1.0.0-rc.6 → 1.0.0-rc.7

package/dist/index.d.ts

@@ -25,6 +25,16 @@ type Id<Tag extends string> = string & {
  * generator type — `IdGenerator<"UserId">.next()` returns `Id<"UserId">`
  * with no caller-side generic to abuse.
  *
+ * **Your factory must produce unique ids under concurrent calls.**
+ * The kit makes no attempt to dedupe or detect collisions — a collision
+ * silently overwrites earlier rows (under unique-key constraints) or
+ * silently aliases two different entities (without them). Safe choices:
+ * `crypto.randomUUID()` (UUIDv4, the default for events), ULID, UUIDv7,
+ * KSUID — all collision-resistant by design. Unsafe choices: `Date.now()`
+ * alone (duplicates within the same millisecond), a process-local
+ * counter without persistence (resets to 1 on restart, collides with
+ * prior runs), a sequential id derived from non-atomic state.
+ *
  * @example
  * ```ts
  * import { ulid } from "ulid";
@@ -71,12 +81,56 @@ type EventIdFactory = () => string;
  *
  * **Module-scoped — last setter wins.** The factory lives as a single
  * module variable; importing two libraries that both call this races on
- * load order. For multi-tenant request isolation (e.g. one factory per
- * tenant in a single Worker invocation) **prefer the per-call
- * `options.eventId`** instead of mutating the global. Same caveat applies
- * to `setClockFactory`.
+ * load order, and parallel test workers will see each other's factory.
+ * For test isolation and short-lived contexts prefer
+ * {@link withEventIdFactory}; for multi-tenant request isolation
+ * (e.g. one factory per tenant in a single Worker invocation) **prefer
+ * the per-call `options.eventId`** instead of mutating the global. Same
+ * caveat applies to `setClockFactory`.
  */
 declare function setEventIdFactory(factory: EventIdFactory): void;
+/**
+ * Scoped variant of {@link setEventIdFactory}: installs `factory`,
+ * runs `fn`, then restores the previous factory in a `finally` block —
+ * so the restoration happens even if `fn` throws. Safe for parallel
+ * tests and for synchronous request handlers that need a tenant-
+ * specific factory without polluting the global.
+ *
+ * **Synchronous-only — enforced at runtime.** If `fn` returns a
+ * thenable (a `Promise` or any object with a `then` method), the
+ * helper throws *before* returning the value to the caller. This
+ * catches the async-misuse footgun where the factory would be
+ * restored before the awaited body of `fn` runs, leaving the awaited
+ * code reading the previous factory. For async scoping across `await`
+ * boundaries, use `AsyncLocalStorage` — out of scope for this helper;
+ * build it on top if you need it.
+ *
+ * Composes by nesting: an inner `withEventIdFactory` restores back to
+ * the outer's factory; the outer restores to the original.
+ *
+ * **When to prefer the per-call `options.eventId` instead.** If you're
+ * constructing a single event and want full control over its id,
+ * passing `{ eventId: "..." }` to `createDomainEvent` is the strongest
+ * isolation — it bypasses the factory mechanism entirely, no global
+ * mutation, no scope to manage. Reach for `withEventIdFactory` when
+ * the events are constructed deep inside domain methods you can't
+ * thread an explicit id through (typical test scenario), or when many
+ * events in a scope should share the same factory.
+ *
+ * @example
+ * ```ts
+ * // In a vitest test:
+ * it("emits deterministic ids", () => {
+ *   withEventIdFactory(() => "evt-fixed", () => {
+ *     const e = createDomainEvent("X", { v: 1 });
+ *     expect(e.eventId).toBe("evt-fixed");
+ *   });
+ *   // Outside the callback the default crypto.randomUUID is restored,
+ *   // even if the body had thrown.
+ * });
+ * ```
+ */
+declare function withEventIdFactory<T>(factory: EventIdFactory, fn: () => T): T;
 /**
  * Restores the default event-id factory (`crypto.randomUUID()`).
  * Intended for use in test `afterEach` hooks.
@@ -102,8 +156,37 @@ type ClockFactory = () => Date;
  *
  * The per-call `options.occurredAt` override always wins over this
  * factory. Symmetric to `setEventIdFactory`.
+ *
+ * Module-scoped — see {@link setEventIdFactory} for the global-state
+ * caveats. For test isolation prefer {@link withClockFactory}; for
+ * multi-tenant request isolation prefer the per-call
+ * `options.occurredAt`.
  */
 declare function setClockFactory(factory: ClockFactory): void;
+/**
+ * Scoped variant of {@link setClockFactory}: installs `factory`, runs
+ * `fn`, then restores the previous factory in a `finally` block.
+ * Synchronous-only — same constraints (and same runtime thenable
+ * guard) as {@link withEventIdFactory}.
+ *
+ * **When to prefer the per-call `options.occurredAt` instead.** Same
+ * trade-off as {@link withEventIdFactory}: passing `{ occurredAt }`
+ * to `createDomainEvent` is the strongest isolation for single-event
+ * cases. The scoped helper is for events constructed deep inside
+ * domain methods where threading an explicit timestamp is awkward.
+ *
+ * @example
+ * ```ts
+ * it("stamps events with a fixed clock", () => {
+ *   const fixed = new Date("2026-01-01T00:00:00Z");
+ *   withClockFactory(() => fixed, () => {
+ *     const e = createDomainEvent("X", { v: 1 });
+ *     expect(e.occurredAt).toEqual(fixed);
+ *   });
+ * });
+ * ```
+ */
+declare function withClockFactory<T>(factory: ClockFactory, fn: () => T): T;
 /**
  * Restores the default clock factory (`() => new Date()`).
  * Intended for use in test `afterEach` hooks.
@@ -753,16 +836,57 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = ne
      */
     clearPendingEvents(): void;
     /**
-     * Post-save hook called by a `Repository.save()` implementation to push
-     * the persisted version back into the in-memory aggregate and clear
-     * pendingEvents (they are now safely on the write side / in the
-     * outbox).
+     * **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
+     * 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.
      *
-     * 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.
+     * If you must override (legitimate cases are very rare), call
+     * `super.markPersisted(version)` FIRST so the framework's cleanup
+     * runs, then add your logic afterwards.
+     *
+     * @param version - The version assigned by the persistence layer
+     * @see onPersisted — the safe extension point for subclasses
      */
     markPersisted(version: Version): void;
+    /**
+     * 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
+     * implementation to preserve.
+     *
+     * **`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
+     * 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
+     * meant to prevent.
+     *
+     * **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 —
+     * 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
+     * properly awaited extension point.
+     *
+     * @param version - The version that was just persisted
+     */
+    protected onPersisted(_version: Version): void;
     /**
      * Mutates state and records the resulting domain events in the
      * **canonical record-after-mutation order**. Use this instead of calling
@@ -1058,12 +1182,57 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
     get pendingEvents(): ReadonlyArray<TEvent>;
     clearPendingEvents(): void;
     /**
-     * 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.
+     * **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
+     * 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.
+     *
+     * If you must override (legitimate cases are very rare), call
+     * `super.markPersisted(version)` FIRST so the framework's cleanup
+     * runs, then add your logic afterwards.
+     *
+     * @param version - The version assigned by the persistence layer
+     * @see onPersisted — the safe extension point for subclasses
      */
     markPersisted(version: Version): void;
+    /**
+     * 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
+     * implementation to preserve.
+     *
+     * **`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
+     * 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
+     * meant to prevent.
+     *
+     * **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 —
+     * 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
+     * properly awaited extension point.
+     *
+     * @param version - The version that was just persisted
+     */
+    protected onPersisted(_version: Version): void;
     protected constructor(id: TId, initialState: TState);
     /**
      * Validates an event before it is applied. Default is no-op.
@@ -1638,6 +1807,29 @@ interface TransactionScope<TCtx> {
  *     aggregate's `pendingEvents` and writes them via `outbox.add` (so
  *     events persist atomically with the state change). Skipped when no
  *     events were recorded.
+ *
+ *     **Harvest order.** Events are concatenated in the order
+ *     aggregates appear in the returned `aggregates` array, then in
+ *     each aggregate's `pendingEvents` order (insertion order via
+ *     `apply` / `commit` / `addDomainEvent`). So `aggregates: [a, b]`
+ *     with `a` emitting `[e1, e2]` and `b` emitting `[e3]` produces
+ *     `outbox.add([e1, e2, e3])` and `bus.publish([e1, e2, e3])` in
+ *     that exact order.
+ *
+ *     **Two ordering guarantees, not one.** Within a single aggregate
+ *     the order is *causal* — events are recorded in the order the
+ *     domain methods ran, and subscribers (handlers, projections,
+ *     replay) MUST process them in that order. Across aggregates the
+ *     order in this batch is deterministic but *not* a domain
+ *     guarantee. Greg Young / Vernon IDDD §10: aggregates are
+ *     independent consistency boundaries; events across them are
+ *     eventually consistent. Subscribers should NOT engineer
+ *     dependencies on cross-aggregate ordering — use
+ *     `EventMetadata.causationId` to express true causation, or a
+ *     process manager to coordinate. The in-process EventBus delivers
+ *     this batch in order, sequential outbox-dispatchers preserve it
+ *     too, but parallel dispatchers or message brokers may reorder
+ *     across aggregates at delivery time.
  *  3. The transaction commits.
  *  4. **After** the commit, `aggregate.markPersisted(aggregate.version)`
  *     fires on each returned aggregate — only now are pending events
@@ -1654,6 +1846,19 @@ interface TransactionScope<TCtx> {
  * If the transaction rolls back, `markPersisted` is **not** called — the
  * aggregate keeps its pending events, so the caller can retry or discard.
  *
+ * **Duplicate aggregates are deduped by reference.** If the returned
+ * `aggregates` array contains the same instance twice — e.g. a use
+ * case touches an order via two repository references that happen to
+ * resolve to the same identity-map entry — `withCommit` dedupes by
+ * JavaScript object identity before harvesting. Each event lands in
+ * the outbox exactly once and `markPersisted` fires exactly once. Two
+ * *different* instances with the same logical id cannot be detected
+ * at this layer; that is a Repository contract violation (failure to
+ * maintain Fowler's Identity Map per Unit of Work). See
+ * `docs/guide/repository.md` → "Identity Map: one instance per
+ * aggregate per Unit of Work" for the requirement on `IRepository`
+ * implementations that makes this dedupe sound.
+ *
  * @example Tx-bound repos (Drizzle, Prisma, Mongo, …)
  * ```typescript
  * const result = await withCommit({ outbox, bus, scope }, async (tx) => {
@@ -2008,6 +2213,27 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      *     stored (optimistic concurrency).
      *  2. Write the aggregate to durable storage.
      *
+     * **Insert vs update — library convention.** A fresh aggregate begins
+     * at `version === 0` (the `Version` brand defaults to `0` in both
+     * `AggregateRoot` and `EventSourcedAggregate`). After the first
+     * versioned mutation (`setState(_, true)`, `apply()`, `commit()`) the
+     * version is `> 0`. Implementations distinguish the two paths by the
+     * incoming `aggregate.version`:
+     *
+     *  - `aggregate.version === 0` → **INSERT** (no existing row to lock
+     *    against; the write succeeds unconditionally or fails the unique
+     *    constraint on `id`).
+     *  - `aggregate.version  >  0` → **UPDATE** with the OCC predicate
+     *    `WHERE id = ? AND version = expected`. If the row count is `0`,
+     *    another writer raced you — throw `ConcurrencyConflictError`.
+     *
+     * The library does not formalise this in the type system because
+     * version-bump semantics differ across the two aggregate flavours
+     * (state-stored aggregates bump on the user's call to `setState(_,
+     * true)`; event-sourced aggregates bump on every `apply()` by
+     * definition). The `version === 0` invariant for "never persisted" is
+     * the common contract.
+     *
      * Do **not** call `aggregate.markPersisted(...)` here. The library's
      * `withCommit` orchestrator handles the post-save lifecycle (harvest
      * pending events into the outbox, then mark persisted after commit).
@@ -2021,7 +2247,45 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      */
     save(aggregate: TAgg): Promise<void>;
     /**
-     * Removes the aggregate by id.
+     * Removes the aggregate's row by id. Pure persistence — does NOT
+     * harvest pending events from the aggregate (the contract takes
+     * only the id, so there is no aggregate to harvest from).
+     *
+     * Before reaching for `delete`, ask whether the user-facing "delete"
+     * is the right domain verb. Most are actually state transitions
+     * (*cancel*, *archive*, *close*, *deactivate*, *terminate*) with
+     * proper domain names that should be modelled as state changes plus
+     * a recorded event — not as row removal.
+     *
+     * `delete(id)` belongs in the toolkit for three distinct cases, in
+     * decreasing order of common occurrence (see
+     * `docs/guide/repository.md` → "Deletion and Domain Events" for
+     * worked examples):
+     *
+     * 1. **State transition that records an event.** The user-facing
+     *    "delete" maps to a real domain operation (e.g. `order.cancel()`,
+     *    `order.archive()`). Call `save(aggregate)`; the row stays with
+     *    a status column. `delete(id)` is never called by the use case.
+     *
+     * 2. **Hard-delete with event harvest.** The row genuinely must
+     *    vanish (regulatory purge, retention-window expiry, true
+     *    termination) *and* the disappearance is a domain fact
+     *    subscribers care about. Inside `withCommit`'s transactional
+     *    callback, record the deletion event on the aggregate, then
+     *    call `delete(id)`. Return the aggregate in the `aggregates`
+     *    array so `withCommit` harvests its pending events into the
+     *    outbox before the row is gone.
+     *
+     * 3. **Hard-delete without event.** Deletion is invisible to the
+     *    domain (abandoned-cart cleanup, expired session rows). No
+     *    subscriber cares. If the entity has identity in the ubiquitous
+     *    language, you probably want path 1 or 2 instead.
+     *
+     * In pure event-sourced systems `delete` is rarely meaningful —
+     * end-of-lifecycle there is a `Closed` / `Terminated` event in the
+     * stream, and identity persists in the event log. `delete` applies
+     * primarily to state-stored aggregates and snapshot / projection
+     * tables.
      */
     delete(id: TId): Promise<void>;
 }
@@ -2295,4 +2559,4 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
     toJSON(): Readonly<T>;
 }
 
-export { type AggregateConfig, AggregateNotFoundError, AggregateRoot, type AggregateSnapshot, type AnyDomainEvent, type ClockFactory, type Command, CommandBus, type CommandHandler, ConcurrencyConflictError, type CreateDomainEventOptions, DeepEqualExceptOptions, DomainError, type DomainEvent, Entity, type EventBus, EventBusImpl, type EventHandler, type EventIdFactory, type EventMetadata, EventSourcedAggregate, type IAggregateRoot, type ICommandBus, type IEntity, type IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IValueObject, type Id, type IdGenerator, type Identifiable, InMemoryOutbox, InfrastructureError, MissingHandlerError, type OnceOptions, type Outbox, type OutboxRecord, type Query, QueryBus, type QueryHandler, type TransactionScope, type VO, ValueObject, type Version, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, withCommit };
+export { type AggregateConfig, AggregateNotFoundError, AggregateRoot, type AggregateSnapshot, type AnyDomainEvent, type ClockFactory, type Command, CommandBus, type CommandHandler, ConcurrencyConflictError, type CreateDomainEventOptions, DeepEqualExceptOptions, DomainError, type DomainEvent, Entity, type EventBus, EventBusImpl, type EventHandler, type EventIdFactory, type EventMetadata, EventSourcedAggregate, type IAggregateRoot, type ICommandBus, type IEntity, type IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IValueObject, type Id, type IdGenerator, type Identifiable, InMemoryOutbox, InfrastructureError, MissingHandlerError, type OnceOptions, type Outbox, type OutboxRecord, type Query, QueryBus, type QueryHandler, type TransactionScope, type VO, ValueObject, type Version, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, withClockFactory, withCommit, withEventIdFactory };

package/dist/index.js

@@ -399,6 +399,26 @@ function setEventIdFactory(factory) {
   currentEventIdFactory = factory;
 }
 __name(setEventIdFactory, "setEventIdFactory");
+function assertNotThenable(result, helperName) {
+  if (result !== null && (typeof result === "object" || typeof result === "function") && typeof result.then === "function") {
+    throw new Error(
+      `${helperName}: fn returned a thenable. The factory is only installed for the synchronous portion of fn; awaited continuations would see the previous factory. For async-scoped factories use AsyncLocalStorage.`
+    );
+  }
+}
+__name(assertNotThenable, "assertNotThenable");
+function withEventIdFactory(factory, fn) {
+  const previous = currentEventIdFactory;
+  currentEventIdFactory = factory;
+  try {
+    const result = fn();
+    assertNotThenable(result, "withEventIdFactory");
+    return result;
+  } finally {
+    currentEventIdFactory = previous;
+  }
+}
+__name(withEventIdFactory, "withEventIdFactory");
 function resetEventIdFactory() {
   currentEventIdFactory = defaultEventIdFactory;
 }
@@ -409,6 +429,18 @@ function setClockFactory(factory) {
   currentClockFactory = factory;
 }
 __name(setClockFactory, "setClockFactory");
+function withClockFactory(factory, fn) {
+  const previous = currentClockFactory;
+  currentClockFactory = factory;
+  try {
+    const result = fn();
+    assertNotThenable(result, "withClockFactory");
+    return result;
+  } finally {
+    currentClockFactory = previous;
+  }
+}
+__name(withClockFactory, "withClockFactory");
 function resetClockFactory() {
   currentClockFactory = defaultClockFactory;
 }
@@ -587,18 +619,61 @@ var AggregateRoot = class extends Entity {
     this._pendingEvents = [];
   }
   /**
-   * Post-save hook called by a `Repository.save()` implementation to push
-   * the persisted version back into the in-memory aggregate and clear
-   * pendingEvents (they are now safely on the write side / in the
-   * outbox).
+   * **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
+   * 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.
+   *
+   * If you must override (legitimate cases are very rare), call
+   * `super.markPersisted(version)` FIRST so the framework's cleanup
+   * runs, then add your logic afterwards.
    *
-   * 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.
+   * @param version - The version assigned by the persistence layer
+   * @see onPersisted — the safe extension point for subclasses
    */
   markPersisted(version) {
     this.setVersion(version);
     this._pendingEvents = [];
+    this.onPersisted(version);
+  }
+  /**
+   * 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
+   * implementation to preserve.
+   *
+   * **`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
+   * 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
+   * meant to prevent.
+   *
+   * **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 —
+   * 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
+   * properly awaited extension point.
+   *
+   * @param version - The version that was just persisted
+   */
+  onPersisted(_version) {
   }
   /**
    * Mutates state and records the resulting domain events in the
@@ -834,14 +909,61 @@ var EventSourcedAggregate = class extends Entity {
     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.
+   * **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
+   * 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.
+   *
+   * If you must override (legitimate cases are very rare), call
+   * `super.markPersisted(version)` FIRST so the framework's cleanup
+   * runs, then add your logic afterwards.
+   *
+   * @param version - The version assigned by the persistence layer
+   * @see onPersisted — the safe extension point for subclasses
    */
   markPersisted(version) {
     this.setVersion(version);
     this._pendingEvents = [];
+    this.onPersisted(version);
+  }
+  /**
+   * 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
+   * implementation to preserve.
+   *
+   * **`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
+   * 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
+   * meant to prevent.
+   *
+   * **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 —
+   * 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
+   * properly awaited extension point.
+   *
+   * @param version - The version that was just persisted
+   */
+  onPersisted(_version) {
   }
   constructor(id, initialState) {
     super(id, initialState);
@@ -987,13 +1109,14 @@ async function withCommit(deps, fn) {
   const { result, aggregates, events } = await deps.scope.transactional(
     async (ctx) => {
       const fnResult = await fn(ctx);
-      const harvested = fnResult.aggregates.flatMap(
+      const uniqueAggregates = Array.from(new Set(fnResult.aggregates));
+      const harvested = uniqueAggregates.flatMap(
         (agg) => agg.pendingEvents
       );
       if (harvested.length > 0) {
         await deps.outbox.add(harvested);
       }
-      return { ...fnResult, events: harvested };
+      return { ...fnResult, aggregates: uniqueAggregates, events: harvested };
     }
   );
   for (const agg of aggregates) {
@@ -1163,6 +1286,6 @@ var InMemoryOutbox = class {
   }
 };
 
-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, voWithValidation, withCommit };
+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, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map