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

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.
-     *
-     * 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.
+     * Whether `setState()` should bump the version automatically when the
+     * caller omits the per-call `bumpVersion` argument.
      *
-     * (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
@@ -880,14 +898,11 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = ne
  * they typically map to HTTP 400 / business-rule responses.
  *
  * The library itself does **not** ship any concrete `DomainError`
- * subclass — the kit can't know your invariants. {@link MissingHandlerError},
- * {@link AggregateNotFoundError}, and {@link ConcurrencyConflictError}
- * deliberately sit on other branches of the hierarchy (see below) because
- * they are not invariant violations.
+ * subclass — the kit can't know your invariants.
  *
- * Extends `BaseError<Name>` from `@shirudo/base-error`, so derived
- * classes get timestamps, `error.cause` traversal, `toJSON()`, i18n-
- * aware `getUserMessage()`, and the `isRetryable` predicate for free.
+ * Extends `BaseError<Name>`; see `@shirudo/base-error` for the inherited
+ * surface (timestamps, cause chains, `toJSON()`, `getUserMessage()`,
+ * `isRetryable`, …).
  */
 declare abstract class DomainError<Name extends string = string> extends BaseError<Name> {
 }
@@ -899,11 +914,8 @@ declare abstract class DomainError<Name extends string = string> extends BaseErr
  * broken); they describe race conditions and missing rows at the
  * storage boundary.
  *
- * Library-internal concrete subclasses:
- *  - {@link AggregateNotFoundError}
- *  - {@link ConcurrencyConflictError}
- *
- * Extends `BaseError<Name>` from `@shirudo/base-error`.
+ * Library-internal concrete subclasses: {@link AggregateNotFoundError},
+ * {@link ConcurrencyConflictError}.
  */
 declare abstract class InfrastructureError<Name extends string = string> extends BaseError<Name> {
 }
@@ -926,7 +938,7 @@ declare abstract class InfrastructureError<Name extends string = string> extends
  */
 declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
     readonly eventType: string;
-    constructor(eventType: string);
+    constructor(eventType: string, cause?: unknown);
 }
 /**
  * Thrown by `IRepository.getByIdOrFail()` when an aggregate with the
@@ -934,13 +946,17 @@ declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
  * boundary, not a business rule, decided the row is absent. Use the
  * nullable variant `getById()` if "not found" is a valid outcome.
  *
- * Ships with a user-safe message via `withUserMessage`. Not retryable —
- * retrying won't make the row appear.
+ * Accepts an optional `cause` so a `Repository.save()` implementation
+ * can wrap a lower-level "row not found" / driver-level error without
+ * losing context. Cause-chain helpers (`getRootCause`,
+ * `findInCauseChain`) from `@shirudo/base-error` traverse the chain.
+ *
+ * Not retryable — retrying won't make the row appear.
  */
 declare class AggregateNotFoundError extends InfrastructureError<"AggregateNotFoundError"> {
     readonly aggregateType: string;
     readonly id: string;
-    constructor(aggregateType: string, id: string);
+    constructor(aggregateType: string, id: string, cause?: unknown);
 }
 /**
  * Thrown by `IRepository.save()` when the aggregate's expected version
@@ -964,7 +980,7 @@ declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyC
      * the use case, and retry on this exception.
      */
     readonly retryable: true;
-    constructor(aggregateType: string, aggregateId: string, expectedVersion: number, actualVersion: number);
+    constructor(aggregateType: string, aggregateId: string, expectedVersion: number, actualVersion: number, cause?: unknown);
 }
 
 /**
@@ -974,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
@@ -986,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).
  *
@@ -1074,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;
     /**
@@ -1089,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
@@ -1125,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
@@ -1141,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.
      */
@@ -1159,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.
@@ -1458,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.
      *
@@ -1553,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;
 }
@@ -1573,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.
@@ -1604,67 +1569,109 @@ interface Outbox<Evt> {
  * Transaction-scope abstraction.
  *
  * Wraps a block of work so it runs inside the persistence layer's native
- * transaction (Postgres `BEGIN`/`COMMIT`, Mongo session, etc.). The block
- * commits when the callback resolves and rolls back if it throws.
- *
- * This is **not** Fowler's full Unit of Work (no change tracking, no
- * registerDirty/registerNew/registerDeleted, no commit-time flush). It is
- * intentionally minimal — change tracking is the ORM's job; the library
- * stays out of it. The name `TransactionScope` is therefore more honest
- * than `UnitOfWork`.
+ * transaction (Postgres `BEGIN`/`COMMIT`, Mongo session, Drizzle / Prisma
+ * `$transaction`, etc.). The block commits when the callback resolves
+ * and rolls back if it throws.
+ *
+ * `TCtx` is the persistence layer's transaction handle — Drizzle's `tx`,
+ * 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
+ * flush). Change tracking is the ORM's job.
+ *
+ * @example Drizzle implementation
+ * ```typescript
+ * class DrizzleScope implements TransactionScope<DrizzleTx> {
+ *   constructor(private db: DrizzleDb) {}
+ *   async transactional<T>(fn: (tx: DrizzleTx) => Promise<T>): Promise<T> {
+ *     return this.db.transaction((tx) => fn(tx));
+ *   }
+ * }
+ * ```
  *
- * @example
+ * @example Use site — bind repos to the live transaction
  * ```typescript
- * await scope.transactional(async () => {
- *   const order = await repo.getByIdOrFail(orderId);
+ * await scope.transactional(async (tx) => {
+ *   // Construct tx-bound repos from ctx (your factory / DI of choice)
+ *   const orderRepository = makeOrderRepository(tx);
+ *
+ *   const order = await orderRepository.getByIdOrFail(orderId);
  *   order.confirm();
- *   await repo.save(order);
+ *   await orderRepository.save(order);
  * });
  * ```
+ *
+ * `IRepository`'s contract takes the id / aggregate only — the tx handle
+ * is wired into a concrete repository at construction time, not threaded
+ * through every call. Different ORMs have different idioms for that
+ * (constructor injection, factory functions, `withTx` chains); pick one
+ * and keep it consistent.
  */
-interface TransactionScope {
-    transactional<T>(fn: () => Promise<T>): Promise<T>;
+interface TransactionScope<TCtx> {
+    transactional<T>(fn: (ctx: TCtx) => Promise<T>): Promise<T>;
 }
 
 /**
- * Helper for executing a write Use Case inside a Unit of Work.
+ * 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()` runs inside `uow.transactional(...)` — domain mutations + repo
- *     writes happen here.
- *  2. `outbox.add(events)` is also inside the transaction, so events
- *     persist atomically with the state change (outbox pattern).
+ *  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
+ *     `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.
+ *  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
- * outbox still holds the events and an outbox-dispatcher will deliver them
- * (eventual consistency).
+ * 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
+ * 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, uow },
- *   async () => {
- *     const order = Order.create(customerId, items);
- *     await repository.save(order);
- *     return { result: order.id, events: order.domainEvents };
- *   }
- * );
+ * const result = await withCommit({ outbox, bus, scope }, async (tx) => {
+ *   const orderRepository = makeOrderRepository(tx); // your factory binds tx to the repo
+ *   const order = await orderRepository.getByIdOrFail(orderId);
+ *   order.confirm();
+ *   await orderRepository.save(order);             // pure persistence — does NOT call markPersisted
+ *   return { result: order.id, aggregates: [order] };
+ * });
  * ```
  */
-declare function withCommit<Evt extends {
-    type: string;
-}, R>(deps: {
+declare function withCommit<Evt extends AnyDomainEvent, R, TCtx>(deps: {
     outbox: Outbox<Evt>;
     bus?: EventBus<Evt>;
-    scope: TransactionScope;
-}, fn: () => Promise<{
+    scope: TransactionScope<TCtx>;
+}, fn: (ctx: TCtx) => Promise<{
     result: R;
-    events: ReadonlyArray<Evt>;
+    aggregates: ReadonlyArray<IAggregateRoot<Id<string>, Evt>>;
 }>): Promise<R>;
 
 /**
@@ -1899,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;
@@ -1918,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.
  *
@@ -1954,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>;
     /**
@@ -2242,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 };