@shirudo/ddd-kit 1.0.0-rc.5 → 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.
@@ -189,6 +272,13 @@ interface DomainEvent<T extends string, P = void> {
      */
     metadata?: EventMetadata;
 }
+/**
+ * Upper-bound alias for "any `DomainEvent` shape". Use as a generic
+ * constraint when a type parameter should accept any concrete event
+ * union. The `unknown` payload is the upper bound — concrete unions
+ * still narrow via `Extract<Evt, { type: K }>` at the use-site.
+ */
+type AnyDomainEvent = DomainEvent<string, unknown>;
 /**
  * Shared option bag for the `createDomainEvent*` factories.
  */
@@ -263,7 +353,7 @@ declare function createDomainEventWithMetadata<T extends string, P>(type: T, pay
  * );
  * ```
  */
-declare function copyMetadata(sourceEvent: DomainEvent<string, unknown>, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
+declare function copyMetadata(sourceEvent: AnyDomainEvent, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
 /**
  * Merges multiple metadata objects into one.
  * Later metadata objects override earlier ones for the same keys.
@@ -502,7 +592,7 @@ declare function sameEntity<TId extends Id<string>>(a: Identifiable<TId>, b: Ide
  * // item is { id: itemId1, productId: "prod-1", quantity: 2 }
  * ```
  */
-declare function findEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId): T | undefined;
+declare function findEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId): T | undefined;
 /**
  * Checks if an entity with the given ID exists in the collection.
  *
@@ -520,7 +610,7 @@ declare function findEntityById<TId extends Id<string>, T extends Identifiable<T
  * hasEntityId(items, itemId2); // false
  * ```
  */
-declare function hasEntityId<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId): boolean;
+declare function hasEntityId<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId): boolean;
 /**
  * Removes an entity with the given ID from the collection.
  * Returns a new array without the entity.
@@ -540,7 +630,7 @@ declare function hasEntityId<TId extends Id<string>, T extends Identifiable<TId>
  * // updated is [{ id: itemId2, productId: "prod-2", quantity: 1 }]
  * ```
  */
-declare function removeEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId): T[];
+declare function removeEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId): T[];
 /**
  * Updates an entity with the given ID in the collection.
  * Returns a new array with the updated entity.
@@ -564,7 +654,7 @@ declare function removeEntityById<TId extends Id<string>, T extends Identifiable
  * // updated is [{ id: itemId1, productId: "prod-1", quantity: 3 }]
  * ```
  */
-declare function updateEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId, updater: (entity: T) => T): T[];
+declare function updateEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId, updater: (entity: T) => T): T[];
 /**
  * Replaces an entity with the given ID in the collection.
  * Returns a new array with the replaced entity.
@@ -588,7 +678,7 @@ declare function updateEntityById<TId extends Id<string>, T extends Identifiable
  * });
  * ```
  */
-declare function replaceEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[], id: TId, replacement: T): T[];
+declare function replaceEntityById<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>, id: TId, replacement: T): T[];
 /**
  * Extracts all IDs from a collection of entities.
  *
@@ -606,7 +696,7 @@ declare function replaceEntityById<TId extends Id<string>, T extends Identifiabl
  * // ids is [itemId1, itemId2]
  * ```
  */
-declare function entityIds<TId extends Id<string>, T extends Identifiable<TId>>(entities: T[]): TId[];
+declare function entityIds<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>): TId[];
 
 /**
  * Marker interface for Aggregate Roots.
@@ -635,7 +725,7 @@ declare function entityIds<TId extends Id<string>, T extends Identifiable<TId>>(
  * }
  * ```
  */
-interface IAggregateRoot<TId extends Id<string>> {
+interface IAggregateRoot<TId extends Id<string>, TEvent = never> {
     /**
      * Unique identifier of the aggregate root entity.
      */
@@ -646,11 +736,25 @@ interface IAggregateRoot<TId extends Id<string>> {
      * This version applies to the entire aggregate, including all child entities.
      */
     readonly version: Version;
+    /**
+     * Read-only list of domain events recorded on this aggregate that have
+     * not yet been flushed to the outbox / persistence layer. Both state-
+     * stored (`AggregateRoot`) and event-sourced (`EventSourcedAggregate`)
+     * aggregates expose them under the same name, so Repository.save() can
+     * harvest them uniformly without branching on the aggregate flavour.
+     */
+    readonly pendingEvents: ReadonlyArray<TEvent>;
+    /**
+     * Clears the pending-event list. Called by `markPersisted` after a
+     * successful write — the events have been handed off to the outbox
+     * / event store and are no longer the aggregate's responsibility.
+     */
+    clearPendingEvents(): void;
     /**
      * Post-save hook: a `Repository.save()` implementation calls this with
      * the persisted version after a successful write to push the new
-     * version back into the aggregate and clear any recorded domain events
-     * (they are now safely on the write side / in the outbox).
+     * version back into the aggregate and clear pendingEvents (they are
+     * now safely on the write side / in the outbox).
      *
      * Required by the interface so a Repository implementation can call it
      * via the published `IAggregateRoot` contract without taking the
@@ -665,17 +769,14 @@ interface IAggregateRoot<TId extends Id<string>> {
  */
 interface AggregateConfig {
     /**
-     * Whether `setState()` should bump the version automatically.
+     * Whether `setState()` should bump the version automatically when the
+     * caller omits the per-call `bumpVersion` argument.
      *
-     * Defaults to **`false`** for `AggregateRoot` — because `setState()`
-     * already takes an explicit `bumpVersion` argument per call, so adding
-     * an "always bump" config on top would be redundant. Keep it `false`
-     * unless you have a subclass that never passes `bumpVersion` and you
-     * want every state change to advance the version anyway.
-     *
-     * (Contrast with `EventSourcedAggregate`, which defaults this to
-     * `true` because every event-sourced state change is per definition a
-     * versioned commit.)
+     * Defaults to **`false`** — `setState()` already takes an explicit
+     * `bumpVersion` argument per call, so the config is just the default
+     * the per-call argument falls back to. Set to `true` only if you have
+     * a subclass that never passes `bumpVersion` and you want every state
+     * change to advance the version anyway.
      */
     autoVersionBump?: boolean;
 }
@@ -701,7 +802,7 @@ interface AggregateConfig {
  *
  * @template TState - The type of the aggregate state (contains child entities and value objects)
  * @template TId - The type of the aggregate root identifier
- * @template TEvent - The type of domain events recorded by this aggregate (defaults to unknown)
+ * @template TEvent - The type of domain events recorded by this aggregate. Defaults to `never` — aggregates without a declared event type cannot emit events (emitting any event becomes a compile error). Supply a concrete event union to opt in.
  *
  * @example
  * ```typescript
@@ -717,34 +818,75 @@ interface AggregateConfig {
  * }
  * ```
  */
-declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = never> extends Entity<TState, TId> implements IAggregateRoot<TId> {
+declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = never> extends Entity<TState, TId> implements IAggregateRoot<TId, TEvent> {
     private _version;
     get version(): Version;
     protected setVersion(version: Version): void;
     private readonly _config;
     private readonly _autoVersionBump;
-    private _domainEvents;
+    private _pendingEvents;
     /**
-     * Returns a read-only list of domain events recorded by this aggregate.
-     * These events are side-effects of state changes.
+     * Read-only list of domain events recorded on this aggregate that have
+     * not yet been flushed to the outbox / persistence layer.
      */
-    get domainEvents(): ReadonlyArray<TEvent>;
+    get pendingEvents(): ReadonlyArray<TEvent>;
     /**
-     * Clears the list of recorded domain events.
-     * Call this after dispatching the events.
+     * Clears the pending-event list. Call this after the events have been
+     * dispatched (typically `markPersisted` handles it for you).
      */
-    clearDomainEvents(): void;
+    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
-     * recorded domain events (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: 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
@@ -972,11 +1114,7 @@ declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyC
  * @template TId - The type of the aggregate root identifier
  * @template TEvent - The union type of all domain events
  */
-interface IEventSourcedAggregate<TId extends Id<string>, TEvent extends DomainEvent<string, unknown>> extends IAggregateRoot<TId> {
-    /**
-     * Returns a read-only list of new, not-yet-persisted events.
-     */
-    readonly pendingEvents: ReadonlyArray<TEvent>;
+interface IEventSourcedAggregate<TId extends Id<string>, TEvent extends AnyDomainEvent> extends IAggregateRoot<TId, TEvent> {
     /**
      * Reconstitutes the aggregate from an event history. Returns `Result`
      * because event-stream corruption is an expected recoverable failure
@@ -984,45 +1122,9 @@ interface IEventSourcedAggregate<TId extends Id<string>, TEvent extends DomainEv
      *
      * @param history - An ordered list of past events
      */
-    loadFromHistory(history: TEvent[]): Result<void, DomainError>;
-    /**
-     * Clears the list of pending events.
-     */
-    clearPendingEvents(): void;
-    /**
-     * Checks if the aggregate has any pending events.
-     */
-    hasPendingEvents(): boolean;
-    /**
-     * Returns the number of pending events.
-     */
-    getEventCount(): number;
-    /**
-     * Returns the latest pending event, if any.
-     */
-    getLatestEvent(): TEvent | undefined;
-}
-type Handler<TState, TEvent> = (state: TState, event: TEvent) => TState;
-/**
- * Configuration options for EventSourcedAggregate behavior.
- */
-interface EventSourcedAggregateConfig {
-    /**
-     * Whether `apply()` should bump the version per event.
-     *
-     * Defaults to **`true`** for `EventSourcedAggregate` — each applied
-     * event is by definition a versioned state change, so the canonical
-     * event-sourcing pattern is "one event = one version bump". Set to
-     * `false` only if your event store assigns version numbers itself
-     * and you want the aggregate to track them via `bumpVersion()` /
-     * `setVersion()` calls instead.
-     *
-     * (Contrast with `AggregateRoot`, which defaults this to `false`
-     * because its `setState()` already takes a per-call `bumpVersion`
-     * argument.)
-     */
-    autoVersionBump?: boolean;
+    loadFromHistory(history: ReadonlyArray<TEvent>): Result<void, DomainError>;
 }
+type Handler<TState, TEvent extends AnyDomainEvent> = (state: TState, event: TEvent) => TState;
 /**
  * Base class for Event-Sourced Aggregate Roots (Vernon, IDDD Chapter 8).
  *
@@ -1072,22 +1174,66 @@ interface EventSourcedAggregateConfig {
  * }
  * ```
  */
-declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<string, unknown>, TId extends Id<string>> extends Entity<TState, TId> implements IEventSourcedAggregate<TId, TEvent> {
+declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEvent, TId extends Id<string>> extends Entity<TState, TId> implements IEventSourcedAggregate<TId, TEvent> {
     private _version;
     get version(): Version;
     private setVersion;
     private _pendingEvents;
-    private readonly _autoVersionBump;
     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;
-    protected constructor(id: TId, initialState: TState, config?: EventSourcedAggregateConfig);
+    /**
+     * 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.
      * Subclasses override to throw a concrete `DomainError` subclass when
@@ -1123,11 +1269,6 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<
      * resolved via the (statically-sound) `handlers` map.
      */
     private dispatchAndCommit;
-    /**
-     * Manually bumps the aggregate version.
-     * Only needed if `autoVersionBump` is disabled.
-     */
-    protected bumpVersion(): void;
     /**
      * Reconstitutes the aggregate from an event history. Catches `DomainError`
      * thrown during replay and returns it as an `Err` — this is the
@@ -1139,10 +1280,7 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<
      * an aggregate already at v=1 (e.g. after a creation event) loading
      * 2 events ends at v=3, not v=2.
      */
-    loadFromHistory(history: TEvent[]): Result<void, DomainError>;
-    hasPendingEvents(): boolean;
-    getEventCount(): number;
-    getLatestEvent(): TEvent | undefined;
+    loadFromHistory(history: ReadonlyArray<TEvent>): Result<void, DomainError>;
     /**
      * Creates a snapshot of the current aggregate state.
      */
@@ -1157,7 +1295,7 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<
      * aggregate is rolled back to its pre-call state + version. Partial
      * restoration is never observable to the caller.
      */
-    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: TEvent[]): Result<void, DomainError>;
+    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: ReadonlyArray<TEvent>): Result<void, DomainError>;
     /**
      * A map of event types to their corresponding handlers.
      * Subclasses MUST implement this property.
@@ -1456,9 +1594,7 @@ type EventHandler<Evt> = (event: Evt) => Promise<void> | void;
  * await bus.publish([orderCreatedEvent, orderShippedEvent]);
  * ```
  */
-interface EventBus<Evt extends {
-    type: string;
-}> {
+interface EventBus<Evt extends AnyDomainEvent> {
     /**
      * Publishes events to all subscribed handlers.
      *
@@ -1551,7 +1687,7 @@ interface OnceOptions {
  * own `eventId`, generate its own UUID, use the row's auto-increment
  * primary key, or whatever the storage layer prefers.
  */
-interface OutboxRecord<Evt> {
+interface OutboxRecord<Evt extends AnyDomainEvent> {
     dispatchId: string;
     event: Evt;
 }
@@ -1571,7 +1707,7 @@ interface OutboxRecord<Evt> {
  * that's already marked is a no-op, not an error. This lets the
  * dispatcher safely retry on partial-failure.
  */
-interface Outbox<Evt> {
+interface Outbox<Evt extends AnyDomainEvent> {
     /**
      * Persists events. Called from inside `withCommit`'s transactional
      * callback, atomically with the aggregate write.
@@ -1607,11 +1743,15 @@ interface Outbox<Evt> {
  * and rolls back if it throws.
  *
  * `TCtx` is the persistence layer's transaction handle — Drizzle's `tx`,
- * Prisma's `tx`, Mongo's session, or `unknown` for the no-context path.
- * The scope opens the transaction and passes the handle to `fn`; the
- * use case binds its repositories to that handle (typically by
- * constructing a tx-scoped repo from the ctx). Default `TCtx = unknown`
- * keeps the no-context callers compiling.
+ * Prisma's `tx`, Mongo's session, etc. The scope opens the transaction
+ * and passes the handle to `fn`; the use case binds its repositories to
+ * that handle (typically by constructing a tx-scoped repo from the ctx).
+ *
+ * No default for `TCtx`: every implementor names their context type
+ * explicitly. For genuinely context-free scopes (in-memory tests, naive
+ * no-tx scopes) use `TransactionScope<undefined>` — that's a conscious
+ * "there is nothing meaningful here" statement, not an accidental
+ * `unknown` fallback.
  *
  * Intentionally **not** Fowler's full Unit of Work (no change tracking,
  * no `registerDirty` / `registerNew` / `registerDeleted`, no commit-time
@@ -1631,11 +1771,11 @@ interface Outbox<Evt> {
  * ```typescript
  * await scope.transactional(async (tx) => {
  *   // Construct tx-bound repos from ctx (your factory / DI of choice)
- *   const orders = makeOrderRepo(tx);
+ *   const orderRepository = makeOrderRepository(tx);
  *
- *   const order = await orders.getByIdOrFail(orderId);
+ *   const order = await orderRepository.getByIdOrFail(orderId);
  *   order.confirm();
- *   await orders.save(order);
+ *   await orderRepository.save(order);
  * });
  * ```
  *
@@ -1645,60 +1785,98 @@ interface Outbox<Evt> {
  * (constructor injection, factory functions, `withTx` chains); pick one
  * and keep it consistent.
  */
-interface TransactionScope<TCtx = unknown> {
+interface TransactionScope<TCtx> {
     transactional<T>(fn: (ctx: TCtx) => Promise<T>): Promise<T>;
 }
 
 /**
  * Helper for executing a write Use Case inside a transaction scope.
  *
+ * The use-case callback returns the aggregates it touched; `withCommit`
+ * owns the post-save lifecycle (harvest, outbox, mark-persisted, publish).
+ * This matches the Vernon / Axon / EventFlow unit-of-work pattern:
+ * `Repository.save` is pure persistence; "this aggregate has been
+ * committed" is the orchestrator's call to make, not the repo's.
+ *
  * Order of operations:
  *  1. `fn(ctx)` runs inside `scope.transactional(...)` — domain mutations
  *     + repo writes happen here. `ctx` is whatever transaction handle the
  *     `scope` exposes (Drizzle `tx`, Prisma `tx`, Mongo session, or
- *     `unknown` for the no-context path).
- *  2. `outbox.add(events)` is also inside the transaction (skipped when
- *     the use case emits no events), so events persist atomically with
- *     the state change.
+ *     `undefined` for context-free scopes).
+ *  2. **Still inside the transaction**, `withCommit` harvests every
+ *     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, `bus.publish(events)` fires for the
- *     in-process fast path (also skipped when the event list is empty).
+ *  4. **After** the commit, `aggregate.markPersisted(aggregate.version)`
+ *     fires on each returned aggregate — only now are pending events
+ *     considered flushed.
+ *  5. `bus.publish(events)` fires for the in-process fast path (skipped
+ *     when no events or no `bus` is wired).
  *
  * Publishing AFTER commit prevents the classic "publish before commit"
  * footgun: in-process subscribers can never react to events from a
- * transaction that later rolled back. If `bus.publish` itself fails, the
+ * transaction that later rolled back. If `bus.publish` itself throws, the
  * outbox still holds the events and an outbox-dispatcher will deliver
  * them (eventual consistency).
  *
- * @example No-context (tests / single-store flows)
- * ```typescript
- * const result = await withCommit({ outbox, bus, scope }, async () => {
- *   order.confirm();
- *   await orderRepo.save(order);
- *   return { result: order.id, events: order.domainEvents };
- * });
- * ```
+ * 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) => {
- *   const orders = makeOrderRepo(tx); // your factory binds tx to the repo
- *   const order = await orders.getByIdOrFail(orderId);
+ *   const orderRepository = makeOrderRepository(tx); // your factory binds tx to the repo
+ *   const order = await orderRepository.getByIdOrFail(orderId);
  *   order.confirm();
- *   await orders.save(order);
- *   return { result: order.id, events: order.domainEvents };
+ *   await orderRepository.save(order);             // pure persistence — does NOT call markPersisted
+ *   return { result: order.id, aggregates: [order] };
  * });
  * ```
  */
-declare function withCommit<Evt extends {
-    type: string;
-}, R, TCtx = unknown>(deps: {
+declare function withCommit<Evt extends AnyDomainEvent, R, TCtx>(deps: {
     outbox: Outbox<Evt>;
     bus?: EventBus<Evt>;
     scope: TransactionScope<TCtx>;
 }, fn: (ctx: TCtx) => Promise<{
     result: R;
-    events: ReadonlyArray<Evt>;
+    aggregates: ReadonlyArray<IAggregateRoot<Id<string>, Evt>>;
 }>): Promise<R>;
 
 /**
@@ -1933,7 +2111,7 @@ declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQue
  * // Both handlers will be called
  * ```
  */
-declare class EventBusImpl<Evt extends DomainEvent<string, unknown>> implements EventBus<Evt> {
+declare class EventBusImpl<Evt extends AnyDomainEvent> implements EventBus<Evt> {
     private readonly handlers;
     subscribe<K extends Evt["type"]>(eventType: K, handler: EventHandler<Extract<Evt, {
         type: K;
@@ -1952,6 +2130,44 @@ declare class EventBusImpl<Evt extends DomainEvent<string, unknown>> implements
     publish(events: ReadonlyArray<Evt>): Promise<void>;
 }
 
+/**
+ * In-memory reference implementation of `Outbox<Evt>`.
+ *
+ * Intended for tests, single-process workers, and quick-start demos.
+ * Uses the event's own `eventId` as the dispatch id — the common, clean
+ * choice. Storage is a `Map<string, OutboxRecord<Evt>>` keyed by
+ * `eventId`, so re-adding the same event is naturally idempotent (the
+ * duplicate entry overwrites itself; `getPending` returns each event at
+ * most once).
+ *
+ * For production, back the outbox with a transactional store so the
+ * outbox row participates in the same transaction as the aggregate
+ * write (see `TransactionScope` + `withCommit`). This class lives in
+ * memory only — events are lost on process restart.
+ *
+ * @example
+ * ```ts
+ * import { InMemoryOutbox, EventBusImpl, withCommit } from "@shirudo/ddd-kit";
+ *
+ * const outbox = new InMemoryOutbox<OrderEvent>();
+ * const bus = new EventBusImpl<OrderEvent>();
+ *
+ * await withCommit({ scope, outbox, bus }, async (tx) => {
+ *   const orderRepository = makeOrderRepository(tx);
+ *   const order = await orderRepository.getByIdOrFail(id);
+ *   order.confirm();
+ *   await orderRepository.save(order);
+ *   return { result: order.id, aggregates: [order] };
+ * });
+ * ```
+ */
+declare class InMemoryOutbox<Evt extends AnyDomainEvent> implements Outbox<Evt> {
+    private readonly pending;
+    add(events: ReadonlyArray<Evt>): Promise<void>;
+    getPending(limit?: number): Promise<ReadonlyArray<OutboxRecord<Evt>>>;
+    markDispatched(dispatchIds: ReadonlyArray<string>): Promise<void>;
+}
+
 /**
  * Core repository contract for Aggregate Roots.
  *
@@ -1988,21 +2204,88 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      */
     exists(id: TId): Promise<boolean>;
     /**
-     * Persists the aggregate (insert or update). Implementations should:
+     * Persists the aggregate (insert or update). Implementations are
+     * responsible for **persistence only** — they must NOT touch the
+     * aggregate's in-memory state:
      *
      *  1. Throw `ConcurrencyConflictError` from `@shirudo/ddd-kit` when the
      *     aggregate's expected version does not match the version currently
      *     stored (optimistic concurrency).
-     *  2. After a successful write, call `aggregate.markPersisted(newVersion)`
-     *     so the in-memory aggregate reflects the new version and clears its
-     *     pending/domain events.
-     *
-     * Return type stays `void` — the caller already holds the aggregate
-     * reference, which is now up to date.
+     *  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).
+     * Calling `markPersisted` inside `save` clears pending events too early
+     * and breaks the harvest path — and is also why the Vernon/Axon/
+     * EventFlow pattern separates persistence from commit-events.
+     *
+     * If you are not using `withCommit` (custom orchestration), call
+     * `aggregate.markPersisted(aggregate.version)` yourself **after** you
+     * have harvested `aggregate.pendingEvents` for downstream dispatch.
      */
     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>;
 }
@@ -2276,4 +2559,4 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
     toJSON(): Readonly<T>;
 }
 
-export { type AggregateConfig, AggregateNotFoundError, AggregateRoot, type AggregateSnapshot, 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 EventSourcedAggregateConfig, type IAggregateRoot, type ICommandBus, type IEntity, type IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IValueObject, type Id, type IdGenerator, type Identifiable, 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 };