@shirudo/ddd-kit 1.0.0-rc.8 → 1.0.0-rc.9

package/dist/index.d.ts

@@ -52,6 +52,101 @@ interface IdGenerator<Tag extends string> {
     next: () => Id<Tag>;
 }
 
+/**
+ * Abstract base for **domain-invariant violations**. Domain methods
+ * (aggregates, entity validation hooks, value-object constructors)
+ * throw `DomainError`-derived exceptions when a business rule is
+ * violated. Consumers derive their own concrete errors — e.g.
+ * `class OrderAlreadyShippedError extends DomainError<"OrderAlreadyShippedError"> {}` —
+ * for `instanceof`-style catching at the App-Service boundary, where
+ * 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.
+ *
+ * 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> {
+}
+/**
+ * Abstract base for **infrastructure / persistence failures** that the
+ * App-Service can recover from — typically by retrying, by returning
+ * HTTP 404 / 409, or by surfacing a "please try again" UX. These are
+ * not domain-invariant violations (the business rules were not
+ * broken); they describe race conditions and missing rows at the
+ * storage boundary.
+ *
+ * Library-internal concrete subclasses: {@link AggregateNotFoundError},
+ * {@link ConcurrencyConflictError}.
+ */
+declare abstract class InfrastructureError<Name extends string = string> extends BaseError<Name> {
+}
+/**
+ * Thrown by `EventSourcedAggregate.apply()` when no handler is
+ * registered for the event's type. This means the aggregate's subclass
+ * forgot to add an entry to its `handlers` map — a programming /
+ * configuration bug, not a domain or infrastructure failure.
+ *
+ * Deliberately **not** on `DomainError` or `InfrastructureError` —
+ * a generic `catch (e instanceof DomainError)` handler at the App
+ * layer must not mask a forgotten handler; this should crash loud and
+ * fail the calling Use Case so the bug surfaces in development. The
+ * replay methods (`loadFromHistory`, `restoreFromSnapshotWithEvents`)
+ * also let it propagate uncaught instead of wrapping it in `Result.Err`.
+ *
+ * Use `isBaseError(e)` from `@shirudo/base-error` to detect
+ * "any structured error from the kit or any other BaseError-using
+ * library" at the App boundary.
+ */
+declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
+    readonly eventType: string;
+    constructor(eventType: string, cause?: unknown);
+}
+/**
+ * Thrown by `IRepository.getByIdOrFail()` when an aggregate with the
+ * given id does not exist. `InfrastructureError` because the storage
+ * boundary, not a business rule, decided the row is absent. Use the
+ * nullable variant `getById()` if "not found" is a valid outcome.
+ *
+ * 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, cause?: unknown);
+}
+/**
+ * Thrown by `IRepository.save()` when the aggregate's expected version
+ * does not match the version currently persisted — i.e. another writer
+ * updated the aggregate concurrently. The canonical optimistic-
+ * concurrency signal; the App-Service typically reloads, re-applies
+ * the use case, and retries, or surfaces HTTP 409 to the caller.
+ *
+ * `InfrastructureError` because the persistence layer (not a domain
+ * rule) detects the race. Marks itself as `retryable: true` so the
+ * `isRetryable` predicate from `@shirudo/base-error` picks it up.
+ */
+declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyConflictError"> {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    /**
+     * Marks this error as retryable so `isRetryable(err)` returns
+     * true. The canonical OCC pattern is to reload the aggregate, re-apply
+     * the use case, and retry on this exception.
+     */
+    readonly retryable: true;
+    constructor(aggregateType: string, aggregateId: string, expectedVersion: number, actualVersion: number, cause?: unknown);
+}
+
 /**
  * Factory function producing a fresh, unique event identifier for each call.
  *
@@ -385,6 +480,93 @@ declare function copyMetadata(sourceEvent: AnyDomainEvent, additionalMetadata?:
  */
 declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
 
+type Version = number & {
+    readonly __v: true;
+};
+/**
+ * Snapshot of an aggregate state at a specific point in time.
+ * Used for optimizing event replay by starting from a snapshot
+ * instead of replaying all events from the beginning.
+ *
+ * @template TState - The type of the aggregate state
+ */
+interface AggregateSnapshot<TState> {
+    /**
+     * The state of the aggregate at the time of the snapshot.
+     */
+    state: TState;
+    /**
+     * The version of the aggregate when the snapshot was taken.
+     */
+    version: Version;
+    /**
+     * Timestamp when the snapshot was created.
+     */
+    snapshotAt: Date;
+}
+/**
+ * Public contract every Aggregate Root satisfies. Implemented by
+ * `BaseAggregate` and inherited by both `AggregateRoot` and
+ * `EventSourcedAggregate`. Repository implementations type their
+ * `save(aggregate)` parameter against this interface rather than the
+ * concrete classes, so the repo layer does not take a compile-time
+ * dependency on the aggregate hierarchy.
+ *
+ * Full per-member documentation lives on the concrete `BaseAggregate`
+ * class; the interface is intentionally terse to avoid drift.
+ *
+ * @template TId    - The aggregate root identifier (branded via `Id<Tag>`)
+ * @template TEvent - The domain-event union, defaults to `never`
+ */
+interface IAggregateRoot<TId extends Id<string>, TEvent = never> {
+    readonly id: TId;
+    readonly version: Version;
+    readonly persistedVersion: Version | undefined;
+    readonly pendingEvents: ReadonlyArray<TEvent>;
+    clearPendingEvents(): void;
+    markPersisted(version: Version): void;
+}
+/**
+ * Public contract for Event-Sourced Aggregate Roots. Extends
+ * `IAggregateRoot` with the replay-from-history boundary.
+ *
+ * @template TId    - The aggregate root identifier
+ * @template TEvent - The union type of all domain events
+ */
+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 at the infrastructure boundary.
+     */
+    loadFromHistory(history: ReadonlyArray<TEvent>): Result<void, DomainError>;
+}
+/**
+ * Checks if two aggregates are at the same version (same ID and version).
+ * Useful for optimistic concurrency control checks.
+ *
+ * Note: Two aggregates with the same ID ARE the same aggregate (identity).
+ * This function checks if they are at the same version — i.e., no concurrent modification.
+ *
+ * @example
+ * ```typescript
+ * const before = await repository.getById(id);
+ * // ... some operations ...
+ * const after = await repository.getById(id);
+ *
+ * if (!sameVersion(before, after)) {
+ *   throw new Error("Aggregate was modified by another process");
+ * }
+ * ```
+ */
+declare function sameVersion<TId extends Id<string>>(a: {
+    id: TId;
+    version: Version;
+}, b: {
+    id: TId;
+    version: Version;
+}): boolean;
+
 /**
  * Entity utilities and interfaces for Domain-Driven Design.
  *
@@ -715,126 +897,28 @@ declare function replaceEntityById<TId extends Id<string>, T extends Identifiabl
 declare function entityIds<TId extends Id<string>, T extends Identifiable<TId>>(entities: ReadonlyArray<T>): TId[];
 
 /**
- * Marker interface for Aggregate Roots.
- *
- * In Domain-Driven Design, an Aggregate Root is an Entity (the parent Entity of the aggregate).
- * It represents the aggregate externally and is the only object that external code
- * is allowed to hold references to. All access to child entities within the aggregate
- * must go through the Aggregate Root.
- *
- * An Aggregate consists of:
- * - One Aggregate Root (Entity with id + version)
- * - Optional child entities (Entities with id + state, but no own version)
- * - Optional value objects
- *
- * The Aggregate Root has identity (id), state, and version for optimistic concurrency control.
- * Child entities exist only within the aggregate boundary and are versioned through
- * the Aggregate Root.
- *
- * @template TId - The type of the aggregate root identifier
- *
- * @example
- * ```typescript
- * class Order extends AggregateRoot<OrderState, OrderId> implements IAggregateRoot<OrderId> {
- *   // Order is an Aggregate Root (an Entity with version)
- *   // OrderState contains child entities (e.g., OrderItem) and value objects
- * }
- * ```
- */
-interface IAggregateRoot<TId extends Id<string>, TEvent = never> {
-    /**
-     * Unique identifier of the aggregate root entity.
-     */
-    readonly id: TId;
-    /**
-     * Version number for optimistic concurrency control.
-     * Incremented on each state change to detect concurrent modifications.
-     * 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 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
-     * abstract class as a compile-time dependency.
-     *
-     * @param version - The version assigned by the persistence layer
-     */
-    markPersisted(version: Version): void;
-}
-/**
- * Configuration options for AggregateRoot behavior.
- */
-interface AggregateConfig {
-    /**
-     * Whether `setState()` should bump the version automatically when the
-     * caller omits the per-call `bumpVersion` argument.
-     *
-     * 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;
-}
-/**
- * Base class for Aggregate Roots without Event Sourcing.
- *
- * In DDD (Evans), an Aggregate is a cluster of objects — root entity, child entities,
- * and value objects — treated as a unit for consistency. The **Aggregate Root** is the
- * root entity that represents the aggregate externally and is the only entry point
- * for external code. This class serves as both: it IS the root entity and it contains
- * the aggregate state (`TState`) which holds child entities and value objects.
- *
- * Provides:
- * - Identity (id) and state management (via `Entity`)
- * - Version management for optimistic concurrency control
- * - Domain event tracking for side-effects
- * - Snapshot support for performance optimization
- *
- * All changes to child entities within `TState` are versioned through this root.
- * Use `setState()` for state mutations to ensure invariant validation.
- *
- * For event sourcing, use `EventSourcedAggregate` instead.
- *
- * @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 `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
- * // Order is an Aggregate Root (an Entity with version)
- * class Order extends AggregateRoot<OrderState, OrderId> {
- *   constructor(id: OrderId, initialState: OrderState) {
- *     super(id, initialState);
- *   }
+ * Shared base for both `AggregateRoot` (state-stored) and
+ * `EventSourcedAggregate`. Carries the lifecycle machinery that's
+ * identical across the two flavours: version + persistedVersion
+ * tracking, pending events buffer, the `markRestored` (Post-Load) /
+ * `markPersisted` (Post-Save) lifecycle markers, and the
+ * `recordEvent` helper that auto-injects `aggregateId` +
+ * `aggregateType` on every event the aggregate emits.
+ *
+ * Consumers do NOT extend this class directly — extend
+ * `AggregateRoot` for state-stored aggregates or
+ * `EventSourcedAggregate` for event-sourced ones. The split between
+ * those two reflects the canonical Vernon §8 (state-stored) /
+ * Vernon §11 + Greg Young (event-sourced) distinction in how state
+ * is represented; the lifecycle machinery is the same for both.
  *
- *   confirm(): void {
- *     this.setState({ ...this.state, status: "confirmed" }, true);
- *   }
- * }
- * ```
+ * @template TState - The type of the aggregate state
+ * @template TId    - The aggregate root identifier
+ * @template TEvent - The domain-event union. Defaults to `never` so
+ *   aggregates without a declared event type cannot emit events
+ *   (emitting any event becomes a compile error).
  */
-declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never> extends Entity<TState, TId> implements IAggregateRoot<TId, TEvent> {
+declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never> extends Entity<TState, TId> implements IAggregateRoot<TId, TEvent> {
     /**
      * The aggregate's domain type as a string, used to populate
      * `aggregateType` on events recorded via {@link recordEvent}.
@@ -857,421 +941,62 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      */
     protected abstract readonly aggregateType: string;
     private _version;
-    get version(): Version;
-    protected setVersion(version: Version): void;
-    private readonly _config;
-    private readonly _autoVersionBump;
-    private _pendingEvents;
-    /**
-     * Read-only list of domain events recorded on this aggregate that have
-     * not yet been flushed to the outbox / persistence layer.
-     */
-    get pendingEvents(): ReadonlyArray<TEvent>;
     /**
-     * Clears the pending-event list. Call this after the events have been
-     * dispatched (typically `markPersisted` handles it for you).
-     */
-    clearPendingEvents(): void;
-    /**
-     * **Framework lifecycle method — `@sealed`.** Called by `withCommit`
-     * (or by your own orchestration code, after harvesting `pendingEvents`)
-     * to push the persisted version back into the in-memory aggregate and
-     * clear `pendingEvents`. TypeScript has no `final` keyword, but
-     * subclasses **should not** override this method directly.
-     *
-     * Overriding without calling `super.markPersisted(version)` silently
-     * leaks `pendingEvents` — the next `withCommit` will re-dispatch them
-     * through the outbox, double-emitting events. This bug has been hit
-     * in production by consumers; the {@link onPersisted} hook below is
-     * the safer extension point.
-     *
-     * If you must override (legitimate cases are very rare), call
-     * `super.markPersisted(version)` FIRST so the framework's cleanup
-     * runs, then add your logic afterwards.
-     *
-     * @param version - The version assigned by the persistence layer
-     * @see onPersisted — the safe extension point for subclasses
-     */
-    markPersisted(version: Version): void;
-    /**
-     * Subclass extension point — fires AFTER {@link markPersisted} has
-     * updated the version and cleared `pendingEvents`. Override this for
-     * post-persist logging, metrics, or cache-eviction without risk of
-     * breaking the framework's pendingEvents cleanup.
-     *
-     * The default implementation is a no-op. Subclasses do NOT need to
-     * call `super.onPersisted(version)` — there is nothing in the parent
-     * implementation to preserve.
-     *
-     * **`onPersisted` deliberately receives only the version, not the
-     * drained events.** Event-driven post-persist logic (aggregate-level
-     * audit logging, per-event-type side effects) belongs in `EventBus`
-     * subscribers or the outbox dispatcher — that is the proper
-     * Aggregate-Boundary separation. Building event-aware logic into
-     * `onPersisted` couples aggregate lifecycle to event processing and
-     * recreates the boundary problems Vernon's aggregate discipline is
-     * meant to prevent.
-     *
-     * **The hook must return synchronously.** `markPersisted` is `void`-
-     * typed and calls `onPersisted` without `await`. TypeScript's
-     * permissive `void` will accept an `async`-override returning
-     * `Promise<void>`, but the returned promise is fire-and-forget —
-     * any rejection becomes an unhandled rejection and `withCommit`
-     * proceeds without waiting. For asynchronous work, subscribe to the
-     * relevant domain event on the `EventBus` instead; that is the
-     * properly awaited extension point.
-     *
-     * @param version - The version that was just persisted
-     */
-    protected onPersisted(_version: Version): void;
-    /**
-     * Mutates state and records the resulting domain events in the
-     * **canonical record-after-mutation order**. Use this instead of calling
-     * `setState` + `addDomainEvent` separately and you cannot trip the
-     * "event for a fact that never happened" footgun.
-     *
-     * Order of operations:
-     *  1. `setState(newState, true)` — runs `validateState` first.
-     *     If it throws, the method propagates and **no event is recorded
-     *     and no version is bumped**.
-     *  2. Each event in `events` is appended via `addDomainEvent`.
-     *
-     * `commit()` **always bumps the version**, regardless of the aggregate's
-     * `autoVersionBump` config. Recording a domain event implies "something
-     * happened that the outside world cares about", and optimistic-
-     * concurrency callers must see a fresh version every time. The config
-     * still governs the un-coupled `setState` path. If you need to mutate
-     * state without bumping (e.g. cosmetic caches), call `setState(newState,
-     * false)` and skip `commit` entirely.
-     *
-     * `events` accepts a single event or an array. Omit it (or pass `[]`)
-     * for state-only mutations.
-     *
-     * @example
-     * ```ts
-     * confirm(): void {
-     *   if (this.state.status === "confirmed") {
-     *     throw new OrderAlreadyConfirmedError(this.id);
-     *   }
-     *   this.commit(
-     *     { ...this.state, status: "confirmed" },
-     *     { type: "OrderConfirmed", orderId: this.id },
-     *   );
-     * }
-     * ```
-     *
-     * `EventSourcedAggregate.apply()` enforces the same ordering
-     * structurally; `commit()` is the opt-in equivalent on `AggregateRoot`,
-     * where `setState` and `addDomainEvent` are otherwise decoupled and the
-     * ordering is convention-only.
-     *
-     * @param newState - The new state (validated by `validateState`)
-     * @param events - One event, an array of events, or none (default)
-     */
-    protected commit(newState: TState, events?: TEvent | readonly TEvent[]): void;
-    protected constructor(id: TId, initialState: TState, config?: AggregateConfig);
-    /**
-     * Records a domain event for later publication.
-     *
-     * **Ordering: record AFTER state mutation.** Vernon (IDDD §8) is
-     * explicit: a domain event describes something that has just happened
-     * to the aggregate — its existence implies the state change already
-     * occurred. Concretely:
-     *
-     * ```ts
-     * confirm(): void {
-     *   if (this.state.status === "confirmed") {
-     *     throw new OrderAlreadyConfirmedError(this.id);
-     *   }
-     *   this.setState({ ...this.state, status: "confirmed" }, true);
-     *   this.addDomainEvent({ type: "OrderConfirmed", orderId: this.id });
-     *   // ↑ post-mutation. The event represents the committed fact.
-     * }
-     * ```
-     *
-     * Recording before mutation is a footgun: if a subsequent invariant
-     * check throws, the event has already been queued but the state never
-     * actually changed — consumers see an event for a fact that did not
-     * happen.
-     *
-     * `EventSourcedAggregate.apply()` enforces this ordering structurally;
-     * `AggregateRoot` leaves it as a convention because the state-mutation
-     * path (`setState`) is decoupled from event recording.
-     *
-     * @param event - The domain event to record
-     */
-    protected addDomainEvent(event: TEvent): void;
-    /**
-     * Sugar for `createDomainEvent` that auto-injects `aggregateId`
-     * (from `this.id`) and `aggregateType` (from {@link aggregateType})
-     * into the event's metadata fields. This is the canonical path for
-     * recording events from inside aggregate domain methods.
-     *
-     * Downstream consumers — outbox dispatchers, projection handlers,
-     * audit logs — route by these two fields. Calling
-     * `createDomainEvent(...)` directly inside an aggregate method
-     * leaves them unset and is caught at the `withCommit` harvest
-     * boundary, but `this.recordEvent(...)` makes the right thing
-     * impossible to forget.
-     *
-     * @example
-     * ```ts
-     * class Order extends AggregateRoot<OrderState, OrderId, OrderEvent> {
-     *   protected readonly aggregateType = "Order";
-     *
-     *   confirm(): void {
-     *     this.commit(
-     *       { ...this.state, status: "confirmed" },
-     *       this.recordEvent("OrderConfirmed", { orderId: this.id }),
-     *     );
-     *   }
-     * }
-     * ```
-     *
-     * @param type    - event type discriminator (must be one of `TEvent`'s tags)
-     * @param payload - payload for that event subtype
-     * @param options - any remaining `createDomainEvent` options
-     *   (`eventId`, `occurredAt`, `metadata`, `version`); `aggregateId`
-     *   and `aggregateType` are deliberately omitted — the helper sets
-     *   them.
-     */
-    protected recordEvent<E extends TEvent>(type: E["type"], payload: E["payload"], options?: Omit<CreateDomainEventOptions, "aggregateId" | "aggregateType">): E;
-    /**
-     * Manually bumps the aggregate version.
-     * Call this after state changes for Optimistic Concurrency Control.
-     *
-     * If `autoVersionBump` is enabled, this is called automatically
-     * when using `setState()`.
-     */
-    protected bumpVersion(): void;
-    /**
-     * Sets the state and optionally bumps the version automatically.
-     * This is a convenience method for state mutations.
-     * Automatically validates the newState using `validateState()`.
-     * Overrides Entity.setState to add version bumping.
-     *
-     * @param newState - The new state
-     * @param bumpVersion - Whether to bump the version (defaults to autoVersionBump config)
-     */
-    protected setState(newState: TState, bumpVersion?: boolean): void;
-    /**
-     * Creates a snapshot of the current aggregate state.
-     * Useful for performance optimization, backup/restore, and audit trails.
-     *
-     * @returns A snapshot containing the current state and version
+     * DB-baseline version. `undefined` until the aggregate has been
+     * persisted or restored at least once. Repository implementations
+     * route INSERT vs UPDATE on this field and use it as the OCC
+     * baseline. See `IRepository.save` JSDoc.
      *
-     * @example
-     * ```typescript
-     * const snapshot = aggregate.createSnapshot();
-     * await snapshotRepository.save(aggregate.id, snapshot);
-     * ```
-     */
-    createSnapshot(): AggregateSnapshot<TState>;
-    /**
-     * Restores the aggregate from a snapshot.
-     * This is useful for loading aggregates from snapshots instead of
-     * rebuilding them from scratch.
-     * Validates the restored state.
-     *
-     * @param snapshot - The snapshot to restore from
-     *
-     * @example
-     * ```typescript
-     * const snapshot = await snapshotRepository.getLatest(aggregateId);
-     * aggregate.restoreFromSnapshot(snapshot);
-     * ```
-     */
-    restoreFromSnapshot(snapshot: AggregateSnapshot<TState>): void;
-}
-
-/**
- * Abstract base for **domain-invariant violations**. Domain methods
- * (aggregates, entity validation hooks, value-object constructors)
- * throw `DomainError`-derived exceptions when a business rule is
- * violated. Consumers derive their own concrete errors — e.g.
- * `class OrderAlreadyShippedError extends DomainError<"OrderAlreadyShippedError"> {}` —
- * for `instanceof`-style catching at the App-Service boundary, where
- * 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.
- *
- * 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> {
-}
-/**
- * Abstract base for **infrastructure / persistence failures** that the
- * App-Service can recover from — typically by retrying, by returning
- * HTTP 404 / 409, or by surfacing a "please try again" UX. These are
- * not domain-invariant violations (the business rules were not
- * broken); they describe race conditions and missing rows at the
- * storage boundary.
- *
- * Library-internal concrete subclasses: {@link AggregateNotFoundError},
- * {@link ConcurrencyConflictError}.
- */
-declare abstract class InfrastructureError<Name extends string = string> extends BaseError<Name> {
-}
-/**
- * Thrown by `EventSourcedAggregate.apply()` when no handler is
- * registered for the event's type. This means the aggregate's subclass
- * forgot to add an entry to its `handlers` map — a programming /
- * configuration bug, not a domain or infrastructure failure.
- *
- * Deliberately **not** on `DomainError` or `InfrastructureError` —
- * a generic `catch (e instanceof DomainError)` handler at the App
- * layer must not mask a forgotten handler; this should crash loud and
- * fail the calling Use Case so the bug surfaces in development. The
- * replay methods (`loadFromHistory`, `restoreFromSnapshotWithEvents`)
- * also let it propagate uncaught instead of wrapping it in `Result.Err`.
- *
- * Use `isBaseError(e)` from `@shirudo/base-error` to detect
- * "any structured error from the kit or any other BaseError-using
- * library" at the App boundary.
- */
-declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
-    readonly eventType: string;
-    constructor(eventType: string, cause?: unknown);
-}
-/**
- * Thrown by `IRepository.getByIdOrFail()` when an aggregate with the
- * given id does not exist. `InfrastructureError` because the storage
- * boundary, not a business rule, decided the row is absent. Use the
- * nullable variant `getById()` if "not found" is a valid outcome.
- *
- * 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, cause?: unknown);
-}
-/**
- * Thrown by `IRepository.save()` when the aggregate's expected version
- * does not match the version currently persisted — i.e. another writer
- * updated the aggregate concurrently. The canonical optimistic-
- * concurrency signal; the App-Service typically reloads, re-applies
- * the use case, and retries, or surfaces HTTP 409 to the caller.
- *
- * `InfrastructureError` because the persistence layer (not a domain
- * rule) detects the race. Marks itself as `retryable: true` so the
- * `isRetryable` predicate from `@shirudo/base-error` picks it up.
- */
-declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyConflictError"> {
-    readonly aggregateType: string;
-    readonly aggregateId: string;
-    readonly expectedVersion: number;
-    readonly actualVersion: number;
-    /**
-     * Marks this error as retryable so `isRetryable(err)` returns
-     * true. The canonical OCC pattern is to reload the aggregate, re-apply
-     * the use case, and retry on this exception.
-     */
-    readonly retryable: true;
-    constructor(aggregateType: string, aggregateId: string, expectedVersion: number, actualVersion: number, cause?: unknown);
-}
-
-/**
- * Interface for Event-Sourced Aggregate Roots.
- * Defines the contract for aggregates that manage state changes via event sourcing.
- *
- * @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 AnyDomainEvent> extends IAggregateRoot<TId, TEvent> {
-    /**
-     * Reconstitutes the aggregate from an event history. Returns `Result`
-     * because event-stream corruption is an expected recoverable failure
-     * at the infrastructure boundary.
-     *
-     * @param history - An ordered list of past events
-     */
-    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).
- *
- * Like `AggregateRoot`, this is both the root entity and the aggregate boundary.
- * The difference is persistence: state is derived from events, not stored directly.
- * Events are the single source of truth — all state changes go through `apply()` → handler.
- *
- * Extends `Entity` directly (not `AggregateRoot`) so that `setState()` and
- * `addDomainEvent()` are not available. This enforces the event sourcing pattern
- * at the type level — there is no way to mutate state without going through an event handler.
- *
- * `apply()` and `validateEvent()` throw `DomainError`-derived exceptions on
- * invariant violations. Subclasses override `validateEvent()` to throw their
- * own concrete subclasses (e.g. `OrderAlreadyConfirmedError`). Only the
- * infrastructure-boundary methods (`loadFromHistory`,
- * `restoreFromSnapshotWithEvents`) return `Result` — they catch `DomainError`
- * during replay so callers can react to corrupted event streams without
- * try/catch.
- *
- * @template TState - The type of the aggregate state (contains child entities and value objects)
- * @template TEvent - The union type of all domain events
- * @template TId - The type of the aggregate root identifier
- *
- * @example
- * ```typescript
- * class OrderAlreadyConfirmedError extends DomainError {
- *   constructor(id: OrderId) { super(`Order ${id} is already confirmed`); }
- * }
- *
- * class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
- *   confirm(): void {
- *     this.apply(createDomainEvent("OrderConfirmed", {}));
- *   }
- *
- *   protected validateEvent(event: OrderEvent): void {
- *     if (event.type === "OrderConfirmed" && this.state.status === "confirmed") {
- *       throw new OrderAlreadyConfirmedError(this.id);
- *     }
- *   }
- *
- *   protected readonly handlers = {
- *     OrderConfirmed: (state: OrderState): OrderState => ({
- *       ...state,
- *       status: "confirmed",
- *     }),
- *   };
- * }
- * ```
- */
-declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEvent, TId extends Id<string>> extends Entity<TState, TId> implements IEventSourcedAggregate<TId, TEvent> {
+     * Distinct from {@link version}, which is the in-memory
+     * post-mutation value. Mutations bump `_version` but never touch
+     * `_persistedVersion` — that field only moves on {@link markRestored}
+     * (Post-Load) and {@link markPersisted} (Post-Save).
+     */
+    private _persistedVersion;
+    private _pendingEvents;
+    get version(): Version;
+    get persistedVersion(): Version | undefined;
     /**
-     * The aggregate's domain type as a string, used to populate
-     * `aggregateType` on events recorded via {@link recordEvent}.
+     * Read-only list of domain events recorded on this aggregate that
+     * have not yet been flushed to the outbox / persistence layer.
+     */
+    get 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;
+    protected setVersion(version: Version): void;
+    /**
+     * Manually bumps the aggregate version. Used by state-stored
+     * aggregates' `setState(_, true)` / `commit()` paths and by the
+     * event-sourced replay path after each applied event.
+     */
+    protected bumpVersion(): void;
+    /**
+     * **Lifecycle marker — Post-Load.** Syncs both `_version` and
+     * `_persistedVersion` to the DB-stored version. Used by
+     * `reconstitute(...)` factories to assemble an in-memory aggregate
+     * from a persisted row.
      *
-     * Subclasses MUST declare this as a string literal:
+     * Does NOT fire {@link onPersisted} — that hook has post-save
+     * semantics (metrics, audit, cache eviction), not post-load. The
+     * Factory-vs-Reconstitution distinction (Vernon §11) is honoured
+     * structurally: two separate markers, one for each transition.
+     *
+     * @param version - The version the row currently holds in the DB
      *
+     * @example
      * ```ts
-     * class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
-     *   protected readonly aggregateType = "Order";
+     * static reconstitute(id: OrderId, state: OrderState, version: Version): Order {
+     *   const order = new Order(id, state);
+     *   order.markRestored(version);
+     *   return order;
      * }
      * ```
-     *
-     * Downstream consumers (outbox dispatchers, projection handlers,
-     * audit logs) route by this. Use the canonical aggregate name
-     * consistently across your bounded context. The value comes from
-     * this explicit declaration, not `constructor.name` (fragile under
-     * minification + bundler transforms).
      */
-    protected abstract readonly aggregateType: string;
-    private _version;
-    get version(): Version;
-    private setVersion;
-    private _pendingEvents;
-    get pendingEvents(): ReadonlyArray<TEvent>;
-    clearPendingEvents(): void;
+    protected markRestored(version: Version): void;
     /**
      * **Framework lifecycle method — `@sealed`.** Called by `withCommit`
      * (or by your own orchestration code, after harvesting `pendingEvents`)
@@ -1324,32 +1049,240 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
      * @param version - The version that was just persisted
      */
     protected onPersisted(_version: Version): void;
-    protected constructor(id: TId, initialState: TState);
+    /**
+     * Appends a domain event to the pending list. Prefer the higher-level
+     * `AggregateRoot.commit()` (state-stored) or `EventSourcedAggregate.apply()`
+     * (event-sourced) call sites — both wrap `addDomainEvent` in the
+     * canonical record-AFTER-mutation order (Vernon §8). Calling
+     * `addDomainEvent` directly is appropriate only when state and event
+     * recording have already been decoupled deliberately (e.g. a
+     * deletion event before a hard-delete; see `docs/guide/repository.md`).
+     */
+    protected addDomainEvent(event: TEvent): void;
+    /**
+     * Creates a snapshot of the current aggregate state — the state at
+     * this moment plus the version. Useful for ES snapshot policies and
+     * for state-stored backup / restore.
+     */
+    createSnapshot(): AggregateSnapshot<TState>;
     /**
      * Sugar for `createDomainEvent` that auto-injects `aggregateId`
      * (from `this.id`) and `aggregateType` (from {@link aggregateType})
-     * into the event's metadata fields. The canonical path for
-     * constructing events to feed into `apply()` from inside aggregate
-     * domain methods.
+     * into the event's metadata fields. This is the canonical path for
+     * recording events from inside aggregate domain methods.
+     *
+     * Downstream consumers — outbox dispatchers, projection handlers,
+     * audit logs — route by these two fields. Calling
+     * `createDomainEvent(...)` directly inside an aggregate method
+     * leaves them unset and is caught at the `withCommit` harvest
+     * boundary, but `this.recordEvent(...)` makes the right thing
+     * impossible to forget.
      *
      * @example
      * ```ts
-     * class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
+     * class Order extends AggregateRoot<OrderState, OrderId, OrderEvent> {
      *   protected readonly aggregateType = "Order";
      *
      *   confirm(): void {
-     *     this.apply(this.recordEvent("OrderConfirmed", { orderId: this.id }));
+     *     this.commit(
+     *       { ...this.state, status: "confirmed" },
+     *       this.recordEvent("OrderConfirmed", { orderId: this.id }),
+     *     );
      *   }
      * }
      * ```
      *
-     * Calling `createDomainEvent(...)` directly inside an aggregate
-     * method leaves `aggregateId` and `aggregateType` unset; the
-     * `withCommit` harvest boundary catches it at runtime, but
-     * `this.recordEvent(...)` makes the right thing impossible to
-     * forget.
+     * @param type    - event type discriminator (must be one of `TEvent`'s tags)
+     * @param payload - payload for that event subtype
+     * @param options - any remaining `createDomainEvent` options
+     *   (`eventId`, `occurredAt`, `metadata`, `version`); `aggregateId`
+     *   and `aggregateType` are deliberately omitted — the helper sets
+     *   them.
      */
     protected recordEvent<E extends TEvent>(type: E["type"], payload: E["payload"], options?: Omit<CreateDomainEventOptions, "aggregateId" | "aggregateType">): E;
+}
+
+/**
+ * Configuration options for AggregateRoot behavior.
+ */
+interface AggregateConfig {
+    /**
+     * Whether `setState()` should bump the version automatically when the
+     * caller omits the per-call `bumpVersion` argument.
+     *
+     * 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;
+}
+/**
+ * Base class for Aggregate Roots without Event Sourcing.
+ *
+ * In DDD (Evans), an Aggregate is a cluster of objects — root entity, child entities,
+ * and value objects — treated as a unit for consistency. The **Aggregate Root** is the
+ * root entity that represents the aggregate externally and is the only entry point
+ * for external code. This class serves as both: it IS the root entity and it contains
+ * the aggregate state (`TState`) which holds child entities and value objects.
+ *
+ * Provides:
+ * - Identity (id) and state management (via `Entity`)
+ * - Version + persistedVersion + pending-event tracking (via `BaseAggregate`)
+ * - `setState`-based mutation with optional version bumping
+ * - `commit()` record-after-mutation helper
+ * - Snapshot support for performance optimization
+ *
+ * All changes to child entities within `TState` are versioned through this root.
+ * Use `setState()` for state mutations to ensure invariant validation.
+ *
+ * For event sourcing, use `EventSourcedAggregate` instead.
+ *
+ * @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 `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
+ * // Order is an Aggregate Root (an Entity with version)
+ * class Order extends AggregateRoot<OrderState, OrderId> {
+ *   protected readonly aggregateType = "Order";
+ *
+ *   constructor(id: OrderId, initialState: OrderState) {
+ *     super(id, initialState);
+ *   }
+ *
+ *   confirm(): void {
+ *     this.commit(
+ *       { ...this.state, status: "confirmed" },
+ *       this.recordEvent("OrderConfirmed", { orderId: this.id }),
+ *     );
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never> extends BaseAggregate<TState, TId, TEvent> {
+    private readonly _autoVersionBump;
+    protected constructor(id: TId, initialState: TState, config?: AggregateConfig);
+    /**
+     * Mutates state and records the resulting domain events in the
+     * **canonical record-after-mutation order**. Use this instead of calling
+     * `setState` + `addDomainEvent` separately and you cannot trip the
+     * "event for a fact that never happened" footgun.
+     *
+     * Order of operations:
+     *  1. `setState(newState, true)` — runs `validateState` first.
+     *     If it throws, the method propagates and **no event is recorded
+     *     and no version is bumped**.
+     *  2. Each event in `events` is appended via `addDomainEvent`.
+     *
+     * `commit()` **always bumps the version**, regardless of the aggregate's
+     * `autoVersionBump` config. Recording a domain event implies "something
+     * happened that the outside world cares about", and optimistic-
+     * concurrency callers must see a fresh version every time. The config
+     * still governs the un-coupled `setState` path. If you need to mutate
+     * state without bumping (e.g. cosmetic caches), call `setState(newState,
+     * false)` and skip `commit` entirely.
+     *
+     * `events` accepts a single event or an array. Omit it (or pass `[]`)
+     * for state-only mutations.
+     *
+     * @example
+     * ```ts
+     * confirm(): void {
+     *   if (this.state.status === "confirmed") {
+     *     throw new OrderAlreadyConfirmedError(this.id);
+     *   }
+     *   this.commit(
+     *     { ...this.state, status: "confirmed" },
+     *     this.recordEvent("OrderConfirmed", { orderId: this.id }),
+     *   );
+     * }
+     * ```
+     *
+     * `EventSourcedAggregate.apply()` enforces the same ordering
+     * structurally; `commit()` is the opt-in equivalent on `AggregateRoot`,
+     * where `setState` and `addDomainEvent` are otherwise decoupled and the
+     * ordering is convention-only.
+     *
+     * @param newState - The new state (validated by `validateState`)
+     * @param events - One event, an array of events, or none (default)
+     */
+    protected commit(newState: TState, events?: TEvent | readonly TEvent[]): void;
+    /**
+     * Sets the state and optionally bumps the version automatically.
+     * Validates `newState` via `validateState()`.
+     *
+     * @param newState - The new state
+     * @param bumpVersion - Whether to bump the version (defaults to autoVersionBump config)
+     */
+    protected setState(newState: TState, bumpVersion?: boolean): void;
+    /**
+     * Restores the aggregate from a snapshot — loads state and aligns
+     * `version` + `persistedVersion` to the snapshot version. Validates
+     * the restored state.
+     *
+     * @param snapshot - The snapshot to restore from
+     */
+    restoreFromSnapshot(snapshot: AggregateSnapshot<TState>): void;
+}
+
+type Handler<TState, TEvent extends AnyDomainEvent> = (state: TState, event: TEvent) => TState;
+/**
+ * Base class for Event-Sourced Aggregate Roots (Vernon, IDDD Chapter 8).
+ *
+ * Like `AggregateRoot`, this is both the root entity and the aggregate
+ * boundary. The difference is persistence: state is derived from events,
+ * not stored directly. Events are the single source of truth — all state
+ * changes go through `apply()` → handler.
+ *
+ * Extends `BaseAggregate` (the shared lifecycle machinery) but does NOT
+ * expose `setState()` or `commit()` from `AggregateRoot`. This enforces
+ * the event sourcing pattern at the type level — there is no way to
+ * mutate state without going through an event handler.
+ *
+ * `apply()` and `validateEvent()` throw `DomainError`-derived exceptions
+ * on invariant violations. Subclasses override `validateEvent()` to
+ * throw their own concrete subclasses (e.g. `OrderAlreadyConfirmedError`).
+ * Only the infrastructure-boundary methods (`loadFromHistory`,
+ * `restoreFromSnapshotWithEvents`) return `Result` — they catch
+ * `DomainError` during replay so callers can react to corrupted event
+ * streams without try/catch.
+ *
+ * @template TState - The aggregate state (contains child entities and value objects)
+ * @template TEvent - The union type of all domain events
+ * @template TId    - The aggregate root identifier
+ *
+ * @example
+ * ```typescript
+ * class OrderAlreadyConfirmedError extends DomainError {
+ *   constructor(id: OrderId) { super(`Order ${id} is already confirmed`); }
+ * }
+ *
+ * class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
+ *   protected readonly aggregateType = "Order";
+ *
+ *   confirm(): void {
+ *     this.apply(this.recordEvent("OrderConfirmed", { orderId: this.id }));
+ *   }
+ *
+ *   protected validateEvent(event: OrderEvent): void {
+ *     if (event.type === "OrderConfirmed" && this.state.status === "confirmed") {
+ *       throw new OrderAlreadyConfirmedError(this.id);
+ *     }
+ *   }
+ *
+ *   protected readonly handlers = {
+ *     OrderConfirmed: (state: OrderState): OrderState => ({
+ *       ...state,
+ *       status: "confirmed",
+ *     }),
+ *   };
+ * }
+ * ```
+ */
+declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEvent, TId extends Id<string>> extends BaseAggregate<TState, TId, TEvent> implements IEventSourcedAggregate<TId, TEvent> {
     /**
      * Validates an event before it is applied. Default is no-op.
      * Subclasses override to throw a concrete `DomainError` subclass when
@@ -1397,10 +1330,6 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
      * 2 events ends at v=3, not v=2.
      */
     loadFromHistory(history: ReadonlyArray<TEvent>): Result<void, DomainError>;
-    /**
-     * Creates a snapshot of the current aggregate state.
-     */
-    createSnapshot(): AggregateSnapshot<TState>;
     /**
      * Restores the aggregate from a snapshot and applies events that occurred
      * after. Same infrastructure-boundary semantics as `loadFromHistory`:
@@ -1423,56 +1352,6 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
     };
 }
 
-type Version = number & {
-    readonly __v: true;
-};
-/**
- * Snapshot of an aggregate state at a specific point in time.
- * Used for optimizing event replay by starting from a snapshot
- * instead of replaying all events from the beginning.
- *
- * @template TState - The type of the aggregate state
- */
-interface AggregateSnapshot<TState> {
-    /**
-     * The state of the aggregate at the time of the snapshot.
-     */
-    state: TState;
-    /**
-     * The version of the aggregate when the snapshot was taken.
-     */
-    version: Version;
-    /**
-     * Timestamp when the snapshot was created.
-     */
-    snapshotAt: Date;
-}
-/**
- * Checks if two aggregates are at the same version (same ID and version).
- * Useful for optimistic concurrency control checks.
- *
- * Note: Two aggregates with the same ID ARE the same aggregate (identity).
- * This function checks if they are at the same version — i.e., no concurrent modification.
- *
- * @example
- * ```typescript
- * const before = await repository.getById(id);
- * // ... some operations ...
- * const after = await repository.getById(id);
- *
- * if (!sameVersion(before, after)) {
- *   throw new Error("Aggregate was modified by another process");
- * }
- * ```
- */
-declare function sameVersion<TId extends Id<string>>(a: {
-    id: TId;
-    version: Version;
-}, b: {
-    id: TId;
-    version: Version;
-}): boolean;
-
 /**
  * Marker interface for Commands.
  * Commands represent write operations that change system state.
@@ -2329,26 +2208,25 @@ interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>>
      *     stored (optimistic concurrency).
      *  2. Write the aggregate to durable storage.
      *
-     * **Insert vs update — library convention.** A fresh aggregate begins
-     * at `version === 0` (the `Version` brand defaults to `0` in both
-     * `AggregateRoot` and `EventSourcedAggregate`). After the first
-     * versioned mutation (`setState(_, true)`, `apply()`, `commit()`) the
-     * version is `> 0`. Implementations distinguish the two paths by the
-     * incoming `aggregate.version`:
+     * **Insert vs update — `persistedVersion` convention.** Every aggregate
+     * exposes two version fields with distinct roles:
+     *
+     *  - `aggregate.version` — in-memory post-mutation value, bumped by
+     *    `setState(_, true)` / `commit()` / `apply()`. NOT the right
+     *    routing key, because mutations can advance it past zero while
+     *    the DB row still does not exist.
+     *  - `aggregate.persistedVersion` — what the persistence layer holds.
+     *    `undefined` until the aggregate has been persisted or restored
+     *    at least once. This is the routing key.
      *
-     *  - `aggregate.version === 0` → **INSERT** (no existing row to lock
-     *    against; the write succeeds unconditionally or fails the unique
+     *  - `aggregate.persistedVersion === undefined` → **INSERT** (never
+     *    persisted; 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.
+     *  - otherwise → **UPDATE** with the OCC predicate
+     *    `WHERE id = ? AND version = aggregate.persistedVersion` (the
+     *    load-time / last-save baseline, not the post-mutation in-memory
+     *    value). If the row count is `0`, another writer raced you —
+     *    throw `ConcurrencyConflictError`.
      *
      * Do **not** call `aggregate.markPersisted(...)` here. The library's
      * `withCommit` orchestrator handles the post-save lifecycle (harvest