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

package/README.md

@@ -103,9 +103,9 @@ The Aggregate Root is an Entity (the parent Entity of the aggregate) that repres
 
 The library provides:
 
-- **`IAggregateRoot<TId>`** - Marker interface for Aggregate Root Entities. The Aggregate Root is an Entity with identity (id) and version for optimistic concurrency control. It represents the aggregate externally and is the only object that can be loaded/saved through repositories.
+- **`IAggregateRoot<TId, TEvent?>`** - Interface for Aggregate Root Entities. The Aggregate Root is an Entity with identity (id), version for optimistic concurrency control, and a `pendingEvents` list of domain events recorded but not yet flushed. Both aggregate flavours (state-stored and event-sourced) expose `pendingEvents` under the same name, so a generic Repository.save() can harvest them uniformly.
 
-- **`AggregateRoot<TState, TId, TEvent?>`** - Base class for creating Aggregate Root Entities without Event Sourcing. Implements `IAggregateRoot<TId>`. The optional `TEvent` parameter (defaults to `unknown`) enables type-safe domain events — only aggregates that specify it get compile-time event validation. Provides ID and version management, state management, domain event tracking, and snapshot support. Use this when you don't need Event Sourcing but still want aggregate patterns with versioning and state management.
+- **`AggregateRoot<TState, TId, TEvent?>`** - Base class for creating Aggregate Root Entities without Event Sourcing. Implements `IAggregateRoot<TId, TEvent>`. The optional `TEvent` parameter (defaults to `never`) enables type-safe domain events — only aggregates that specify it can record events at all. Provides ID and version management, state management, pending-event tracking, and snapshot support.
 
 - **`EventSourcedAggregate<TState, TEvent, TId>`** - Base class for Event-Sourced Aggregate Roots. Extends `Entity` directly (not `AggregateRoot`) so that state changes can only happen through event handlers via `apply()`. Provides event tracking, event validation, history replay, and snapshot support.
 
@@ -301,7 +301,7 @@ class Order extends AggregateRoot<OrderState, OrderId, OrderDomainEvent> {
   }
 }
 
-// order.domainEvents is ReadonlyArray<OrderDomainEvent> — no cast needed
+// order.pendingEvents is ReadonlyArray<OrderDomainEvent> — no cast needed
 // order.addDomainEvent({ type: "WrongEvent" }) → compile error
 ```
 
@@ -431,13 +431,10 @@ order.confirm();
 order.ship("TRACK-789");
 
 // Access pending events
-console.log(order.pendingEvents); // Array of events not yet persisted
-
-// Helper methods
-console.log(order.hasPendingEvents()); // true
-console.log(order.getEventCount()); // 3
-console.log(order.getLatestEvent()?.type); // "OrderShipped"
-console.log(order.version); // 3 (automatically bumped)
+console.log(order.pendingEvents);          // Array of events not yet persisted
+console.log(order.pendingEvents.length);   // 3
+console.log(order.pendingEvents.at(-1)?.type); // "OrderShipped"
+console.log(order.version);                // 3 (automatically bumped)
 ```
 
 ### Aggregate Features: Snapshots and Configuration
@@ -675,7 +672,7 @@ const createOrderHandler: CommandHandler<CreateOrderCommand, string> = async (
 
       return {
         result: order.id,
-        events: order.pendingEvents,
+        aggregates: [order],
       };
     }
   );
@@ -1139,9 +1136,9 @@ This package is written in TypeScript and provides full type definitions. All ty
 Key exports include:
 - `vo()`, `voEquals()`, `voEqualsExcept()`, `voWithValidation()` - Value Object utilities (`voWithValidation` is for the App-Service boundary; Domain construction goes through the `ValueObject` base class which throws via `validate()`)
 - `IAggregateRoot<TId>` - Marker interface for Aggregate Root Entities
-- `AggregateRoot<TState, TId, TEvent?>` - Base class for creating Aggregate Root Entities without Event Sourcing (extends `Entity`, implements `IAggregateRoot<TId>`). Optional `TEvent` parameter enables type-safe domain events
+- `AggregateRoot<TState, TId, TEvent?>` - Base class for creating Aggregate Root Entities without Event Sourcing (extends `Entity`, implements `IAggregateRoot<TId, TEvent>`). Optional `TEvent` parameter enables type-safe domain events
 - `EventSourcedAggregate<TState, TEvent, TId>` - Base class for Event-Sourced Aggregate Roots (extends `Entity`, implements `IEventSourcedAggregate<TId, TEvent>`)
-- `AggregateConfig`, `EventSourcedAggregateConfig` - Configuration interfaces
+- `AggregateConfig` - Configuration interface for `AggregateRoot` (controls per-call `setState` version-bump behavior)
 - `AggregateSnapshot<TState>` - Snapshot interface for performance optimization
 - `sameVersion()` - Optimistic concurrency check (same ID and version)
 - `Entity<TState, TId>` - Base class for entities with state and business logic
@@ -1286,7 +1283,7 @@ class CreateOrderHandler implements CommandHandler<CreateOrderCommand, OrderId>
 
     // 3. Save
     await this.repository.save(order);
-    await this.eventBus.publish(order.domainEvents);
+    await this.eventBus.publish(order.pendingEvents);
 
     return ok(order.id);
     // 4. Aggregate is garbage collected when method returns
@@ -1432,7 +1429,7 @@ async function createOrderCommand(cmd: CreateOrderCommand) {
 
     return {
       result: order.id,
-      events: order.pendingEvents // Published atomically
+      aggregates: [order], // withCommit harvests pendingEvents and dispatches
     };
   }); // Commits or rollbacks everything
 }
@@ -1493,7 +1490,7 @@ class OrderService {
     }
 
     await this.repository.save(order);
-    await this.eventBus.publish(order.domainEvents);
+    await this.eventBus.publish(order.pendingEvents);
 
     return ok(order.id);
     // order is garbage collected here

package/dist/index.d.ts

@@ -189,6 +189,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 +270,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 +509,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 +527,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 +547,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 +571,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 +595,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 +613,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 +642,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 +653,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 +686,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 +719,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,28 +735,28 @@ 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).
+     * the persisted version back into the in-memory aggregate and clear
+     * pendingEvents (they are now safely on the write side / in the
+     * outbox).
      *
      * Use this so `save()` can keep its `Promise<void>` return type: the
      * caller holds the aggregate reference, which is up to date after this
@@ -972,11 +990,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 +998,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,12 +1050,11 @@ 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;
     /**
@@ -1087,7 +1064,7 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<
      * `save()` keep its `Promise<void>` return type.
      */
     markPersisted(version: Version): void;
-    protected constructor(id: TId, initialState: TState, config?: EventSourcedAggregateConfig);
+    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 +1100,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 +1111,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 +1126,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 +1425,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 +1518,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 +1538,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 +1574,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 +1602,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 +1616,62 @@ 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.
  *  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.
  *
  * @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 +1906,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 +1925,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,17 +1999,25 @@ 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.
+     *  2. Write the aggregate to durable storage.
+     *
+     * 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.
      *
-     * Return type stays `void` — the caller already holds the aggregate
-     * reference, which is now up to date.
+     * 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>;
     /**
@@ -2276,4 +2295,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, withCommit };