@shirudo/ddd-kit 2.2.0 → 3.0.0-rc.3

package/dist/chunks/errors.d.ts

@@ -0,0 +1,785 @@
+import { StructuredError } from "@shirudo/base-error";
+
+//#region src/core/errors.d.ts
+/**
+ * **The kit's error identity model (since v3).** Every kit error is a
+ * structured error carrying exactly ONE identifier: `code`, a stable
+ * SCREAMING_SNAKE string, and `error.name === error.code` by design, so
+ * there is no name/code drift and nothing to keep in sync. `category`
+ * follows the class hierarchy mechanically (`"DOMAIN"`,
+ * `"INFRASTRUCTURE"`, or `"WIRING"` for the crash-loud family) and
+ * `retryable` is a plain boolean field.
+ *
+ * **No base-error adoption required.** Consumers branch with a plain
+ * `switch (error.code)`, catch via `instanceof DomainError` /
+ * `instanceof InfrastructureError` (exported from this kit), and read
+ * `retryable` / `cause` as ordinary properties. base-error's toolbox
+ * (`matchError` exhaustive dispatch, `isStructuredError`, the
+ * public-error catalog and `toProblem`) works on every kit error as an
+ * OPT-IN benefit on top, never as a prerequisite.
+ */
+/**
+ * Options for consumer subclasses of {@link DomainError} and
+ * {@link InfrastructureError}: the `code` (which also becomes
+ * `error.name`) and the technical `message` are the only obligations;
+ * `retryable` defaults to `false` and the category is fixed by the base.
+ */
+interface KitErrorOptions<TCode extends string> {
+  /** Stable SCREAMING_SNAKE identifier; also becomes `error.name`. */
+  code: TCode;
+  /** Technical message for logs and debugging, never for clients. */
+  message: string;
+  /** Optional underlying error preserved in the cause chain. */
+  cause?: unknown;
+  /** Whether retrying the failed operation can succeed. Default `false`. */
+  retryable?: boolean;
+}
+/**
+ * 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<"ORDER_ALREADY_SHIPPED">`)
+ * for `instanceof`-style catching at the App-Service boundary, where
+ * they typically map to HTTP 400 / business-rule responses.
+ *
+ * The library itself ships no business-rule `DomainError` subclass: the
+ * kit can't know your invariants. (The domain-state-machine module's
+ * transition errors are the structural exception.)
+ *
+ * The `category` is fixed to `"DOMAIN"` and `retryable` defaults to
+ * `false`, so a subclass supplies only its `code` and `message`:
+ *
+ * ```ts
+ * class OrderAlreadyShippedError extends DomainError<"ORDER_ALREADY_SHIPPED"> {
+ *   constructor(orderId: string) {
+ *     super({
+ *       code: "ORDER_ALREADY_SHIPPED",
+ *       message: `Order ${orderId} has already been shipped`,
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class DomainError<TCode extends string = string> extends StructuredError<TCode, "DOMAIN"> {
+  protected constructor(options: KitErrorOptions<TCode>);
+}
+/**
+ * Internal base for the kit's crash-loud **WIRING** family: deterministic
+ * programming/configuration bugs that must fail the operation loudly and
+ * never be absorbed by generic domain or infrastructure handlers. One
+ * implementation of the `{ category: "WIRING", retryable: false }` shape
+ * so the family cannot drift. Exported for the kit's own modules only;
+ * not part of the package entries.
+ */
+declare abstract class KitWiringError<TCode extends string> extends StructuredError<TCode, "WIRING"> {
+  protected constructor(code: TCode, message: string, cause?: unknown);
+}
+/**
+ * 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.
+ *
+ * The `category` is fixed to `"INFRASTRUCTURE"`; `retryable` defaults
+ * to `false` (opt in per subclass, see {@link ConcurrencyConflictError}).
+ *
+ * Library-internal concrete subclasses: {@link AggregateNotFoundError},
+ * {@link ConcurrencyConflictError}, {@link DuplicateAggregateError},
+ * plus the unit-of-work lifecycle wrappers `CommitError` and
+ * `RollbackError` (in `src/app/unit-of-work.ts`).
+ */
+declare abstract class InfrastructureError<TCode extends string = string> extends StructuredError<TCode, "INFRASTRUCTURE"> {
+  protected constructor(options: KitErrorOptions<TCode>);
+}
+/**
+ * Copy-safe membership check for the kit's domain-error family.
+ *
+ * `instanceof` is false for an error constructed by another loaded copy of
+ * the kit (a separately installed adapter package, a CJS/ESM dual load), so
+ * kit boundaries that route by error family fall back to the structural
+ * `category` field, the stable cross-copy contract.
+ */
+declare function isDomainErrorLike(value: unknown): value is DomainError;
+/**
+ * Copy-safe membership check for the kit's infrastructure-error family.
+ * Same rationale as {@link isDomainErrorLike}.
+ */
+declare function isInfrastructureErrorLike(value: unknown): value is InfrastructureError;
+/** Options bag for {@link InMemoryCapacityExceededError}. */
+interface InMemoryCapacityExceededErrorOptions {
+  /** Concrete reference adapter whose configured capacity was exhausted. */
+  readonly store: string;
+  /** Bounded collection or logical resource, such as `events` or `sources`. */
+  readonly resource: string;
+  /** Configured maximum number of retained records. */
+  readonly limit: number;
+  /** Records retained before the rejected operation. */
+  readonly current: number;
+  /** New records the rejected operation would have retained. */
+  readonly attempted: number;
+}
+/**
+ * A finite-capacity in-memory reference adapter rejected new state before
+ * mutation. Existing records remain usable; callers must release explicit
+ * lifecycle state, increase the configured limit, or switch to a durable
+ * adapter. The error is not retryable without one of those external changes.
+ */
+declare class InMemoryCapacityExceededError extends InfrastructureError<"IN_MEMORY_CAPACITY_EXCEEDED"> {
+  readonly store: string;
+  readonly resource: string;
+  readonly limit: number;
+  readonly current: number;
+  readonly attempted: number;
+  constructor(options: InMemoryCapacityExceededErrorOptions);
+}
+/**
+ * Thrown when event dispatch reaches a type with no own handler registration.
+ * This covers `EventSourcedAggregate.apply()` and the exhaustive
+ * `projectionFromHandlers` helper: the declared event union and its handler map
+ * disagree at runtime, which is a programming / configuration bug rather than
+ * 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 through `loadFromHistory` also lets 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 KitWiringError<"MISSING_HANDLER"> {
+  readonly eventType: string;
+  constructor(eventType: string, cause?: unknown);
+}
+/**
+ * Thrown by `Projector.project` when an event cannot be projected
+ * safely because its cursor is missing or malformed, or its aggregate
+ * address is absent. Applying such an event would break idempotency, so
+ * the batch fails. Events written by `withCommit` carry the complete
+ * cursor automatically; other sources compose a gap-proof committed-event
+ * envelope. A well-formed cursor that does not continue the stored chain
+ * instead throws {@link ProjectionGapError}.
+ *
+ * A wiring error, not a `DomainError`: see {@link MissingHandlerError}
+ * for the rationale of crashing loud at the App layer.
+ */
+declare class UnprojectableEventError extends KitWiringError<"UNPROJECTABLE_EVENT"> {
+  readonly projection: string;
+  readonly eventId: string;
+  constructor(projection: string, eventId: string, reason: string, cause?: unknown);
+}
+/**
+ * Thrown when a valid projection cursor does not continue the stored
+ * per-aggregate chain. This is an infrastructure/delivery failure: an
+ * event or commit is missing, commonly because a partition reordered or
+ * dead-lettered it. The projector does not apply the later event and the
+ * checkpoint stays put until the missing history is replayed or the
+ * projection is rebuilt.
+ */
+declare class ProjectionGapError extends InfrastructureError<"PROJECTION_GAP"> {
+  readonly projection: string;
+  readonly eventId: string;
+  readonly previousPosition: string;
+  readonly receivedPosition: string;
+  constructor(projection: string, eventId: string, previousPosition: string, receivedPosition: string);
+}
+/**
+ * Thrown when one batch delivers previously unseen positions of the same
+ * aggregate in descending order. Unlike {@link ProjectionGapError}, this is
+ * direct proof that the feed violated its per-aggregate ordering contract;
+ * no missing-history inference is needed. Positions already covered by the
+ * checkpoint at batch start and exact receipts repeated inside the batch
+ * remain valid redeliveries and do not trip this diagnostic guard.
+ */
+declare class ProjectionOrderViolationError extends InfrastructureError<"PROJECTION_ORDER_VIOLATION"> {
+  readonly projection: string;
+  readonly eventId: string;
+  readonly previousReceivedPosition: string;
+  readonly receivedPosition: string;
+  constructor(projection: string, eventId: string, previousReceivedPosition: string, receivedPosition: string);
+}
+/**
+ * Thrown when a source maps different event identities to one position, either
+ * inside the current batch or at the position stored as the projection's
+ * watermark. The checkpoint retains the identity of that one last-applied
+ * event, so the durable collision is provable without keeping an unbounded
+ * processed-event ledger. Positions behind the watermark remain governed by
+ * the source's one-logical-event-per-position contract.
+ */
+declare class ProjectionIdentityViolationError extends InfrastructureError<"PROJECTION_IDENTITY_VIOLATION"> {
+  readonly projection: string;
+  readonly eventId: string;
+  readonly recordedEventId: string;
+  readonly position: string;
+  constructor(projection: string, eventId: string, recordedEventId: string, position: string);
+}
+/**
+ * Thrown when one logical projection position keeps its event identity but its
+ * commit-boundary receipt changes. `commitSize` and
+ * `previousEventfulAggregateVersion` are part of the continuity proof, so a
+ * source must keep them immutable just like the eventId. Accepting a
+ * contradictory redelivery could hide an incomplete commit or predecessor.
+ */
+declare class ProjectionReceiptViolationError extends InfrastructureError<"PROJECTION_RECEIPT_VIOLATION"> {
+  readonly projection: string;
+  readonly eventId: string;
+  readonly recordedReceipt: string;
+  readonly receivedReceipt: string;
+  constructor(projection: string, eventId: string, recordedReceipt: string, receivedReceipt: string);
+}
+/** A malformed or non-JSON-safe message at an integration boundary. */
+declare class InvalidIntegrationMessageError extends InfrastructureError<"INVALID_INTEGRATION_MESSAGE"> {
+  readonly path: string;
+  readonly reason: string;
+  constructor(path: string, reason: string, cause?: unknown);
+}
+/** A malformed or non-JSON-safe command selected for durable delivery. */
+declare class InvalidCommandMessageError extends InfrastructureError<"INVALID_COMMAND_MESSAGE"> {
+  readonly path: string;
+  readonly reason: string;
+  constructor(path: string, reason: string, cause?: unknown);
+}
+/**
+ * Thrown by `Entity` (constructor and `setState`) and by the event
+ * metadata helpers (`createDomainEvent`'s `options.metadata`,
+ * `mergeMetadata`, `copyMetadata`) when the value carries an own
+ * `"__proto__"` data key:
+ * the shape `JSON.parse` produces for hostile DB rows or request bodies
+ * handed to reconstitute factories. Such a key can never be legitimate
+ * domain state; accepting it would hand a prototype-pollution payload to
+ * every downstream consumer that copies the state through `[[Set]]`
+ * (`Object.assign`, for-in assignment loops), and dropping it would be
+ * silent data mutation.
+ *
+ * Deliberately **not** a `DomainError` or `InfrastructureError` (same
+ * posture as {@link MissingHandlerError}): untrusted input reaching the
+ * domain layer unvalidated is a boundary bug, and a generic
+ * business-rule handler must not absorb it. Validate and strip untrusted
+ * input at the application edge; model genuinely arbitrary keys with a
+ * `Map`, not a plain object.
+ */
+declare class HostileStateKeyError extends KitWiringError<"HOSTILE_STATE_KEY"> {
+  readonly key: string;
+  constructor(key: string, subject?: string);
+}
+/**
+ * Thrown by `EventSourcedAggregate.loadFromHistory` when the replay target
+ * carries unflushed `pendingEvents`. Replaying persisted facts onto that
+ * instance would advance the version underneath decisions made against an
+ * older state and could later claim history the stream does not carry.
+ *
+ * Deliberately **not** a `DomainError` or `InfrastructureError` (same
+ * posture as {@link MissingHandlerError}): a deterministic programming
+ * bug in how the aggregate was constructed before the restore. It
+ * propagates as a throw instead of riding the replay methods' `Result`
+ * channel, so a generic corrupted-stream handler cannot absorb it.
+ * Reconstitution belongs on a bare instance: construct the aggregate
+ * without factory-recorded events or prior mutations, then restore.
+ *
+ * Each throw site carries the safe remedy in its `reason`. Persistence
+ * lifecycle state is intentionally not mutable through the aggregate API:
+ * commit an actually saved instance through application orchestration, or
+ * discard a dirty instance and replay into a fresh one.
+ */
+declare class UnreplayableAggregateError extends KitWiringError<"UNREPLAYABLE_AGGREGATE"> {
+  readonly aggregateId: string;
+  constructor(aggregateId: string, reason: string);
+}
+/**
+ * Thrown by `EventSourcedAggregate.apply()` when a NEW event carries an
+ * `aggregateId` or `aggregateType` naming a different aggregate: a
+ * deterministic programming bug at the call site (a hand-built or
+ * copied event addressed elsewhere), caught before the event can be
+ * recorded and poison the own stream. Events with MISSING address
+ * fields do not trip this: `apply()` stamps them from the aggregate,
+ * the same guarantee `createEvent` gives. A wiring error, distinct
+ * from {@link ForeignEventError} on purpose: a wrong new event is a
+ * bug in today's code, a wrong PERSISTED row is corrupted or miswired
+ * infrastructure, and handlers for one must not absorb the other.
+ */
+declare class MisaddressedEventError extends KitWiringError<"MISADDRESSED_EVENT"> {
+  readonly expectedAggregateId: string;
+  readonly expectedAggregateType: string;
+  readonly eventType: string;
+  readonly actualAggregateId?: string | undefined;
+  readonly actualAggregateType?: string | undefined;
+  constructor(expectedAggregateId: string, expectedAggregateType: string, eventType: string, actualAggregateId?: string | undefined, actualAggregateType?: string | undefined);
+}
+/**
+ * The structural-integrity rejection for a stored snapshot. A consumer's
+ * adapter-owned `SnapshotModel` may throw it from migration or reconstitution
+ * when the blob could not have been produced by any version of the model
+ * (missing fields, impossible types, truncated data). An
+ * `InfrastructureError`, because corrupted persistence is a storage
+ * problem, never a business rejection; it is nevertheless RECOVERABLE
+ * by design: the repository catches it, discards the derived snapshot, and
+ * refolds from the authoritative event stream.
+ */
+declare class SnapshotCorruptedError extends InfrastructureError<"SNAPSHOT_CORRUPTED"> {
+  constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when an event reaches the aggregate's recording paths
+ * (`apply`, `commit`, `addDomainEvent`) without having been minted by
+ * the kit's constructors: `createDomainEvent`,
+ * `createDomainEventFromFacts`, `createUncommittedDomainEvent`, or aggregate
+ * event helpers
+ * deep-freeze the event and defensively copy payload and metadata,
+ * and register the result in an internal, unforgeable mint marker.
+ * Anything else (a hand-rolled literal, a shallow-frozen copy with
+ * mutable nested data) is rejected: a mutable event recorded next to
+ * a state change can silently diverge from it afterwards. A wiring
+ * error: deterministic bug at the call site, the remedy is minting
+ * through the constructors.
+ */
+declare class UnmintedEventError extends KitWiringError<"UNMINTED_EVENT"> {
+  constructor(eventType: string);
+}
+/**
+ * Thrown by `recordPendingEvents` when the aggregate's pending-event list
+ * changes while its events are being stamped: a stamp provider that
+ * directly or transitively triggers a new decision on the same aggregate
+ * would otherwise have that decision silently discarded when recording
+ * replaces the pending list. Recording is atomic: when this guard fires,
+ * every decision (including the re-entrant one) remains unrecorded. A
+ * wiring error: deterministic bug at the call site, the remedy is keeping
+ * stamp providers free of domain decisions.
+ */
+declare class ReentrantEventRecordingError extends KitWiringError<"REENTRANT_EVENT_RECORDING"> {
+  constructor(aggregateId: string);
+}
+/**
+ * Thrown by `recordPendingEvents` when two events in one aggregate's pending
+ * batch carry the same `eventId`: a stamp provider that returns one reused
+ * stamp (or repeats an explicit id) would otherwise mint two distinct facts
+ * sharing one identity, and downstream idempotent consumers keyed on
+ * `eventId` silently drop one of them. A wiring error: deterministic bug in
+ * the stamp provider, the remedy is one fresh identity per decision.
+ */
+declare class DuplicateEventIdError extends KitWiringError<"DUPLICATE_EVENT_ID"> {
+  /** The identity two pending events would have shared. */
+  readonly eventId: string;
+  constructor(aggregateId: string, /** The identity two pending events would have shared. */eventId: string);
+}
+/**
+ * Thrown by persisted-event consumers (including `loadFromHistory` and
+ * `Projector`) when an event carries an
+ * `aggregateId` or `aggregateType` that names a different aggregate:
+ * the persisted row belongs to someone else (a miswired stream read,
+ * ids colliding across aggregate types, a corrupted store). An
+ * `InfrastructureError`, NOT a `DomainError` (same posture as
+ * {@link SnapshotSchemaMismatchError}): a wrong address is data
+ * corruption or wiring, never an expected business rejection, so it
+ * must not be absorbed by generic domain error handling or presented
+ * as a 4xx. It therefore PROPAGATES as a throw through the replay
+ * methods' `Result` contract (which reserves `Err` for `DomainError`),
+ * after the usual all-or-nothing rollback. History events without the
+ * optional address fields pass unchecked (the fields are optional on
+ * the event shape); new events are covered by
+ * {@link MisaddressedEventError}.
+ */
+declare class ForeignEventError extends InfrastructureError<"FOREIGN_EVENT"> {
+  readonly expectedAggregateId: string;
+  readonly expectedAggregateType: string;
+  readonly eventType: string;
+  readonly actualAggregateId?: string | undefined;
+  readonly actualAggregateType?: string | undefined;
+  constructor(expectedAggregateId: string, expectedAggregateType: string, eventType: string, actualAggregateId?: string | undefined, actualAggregateType?: string | undefined);
+}
+/** Constructor options for {@link NonProgressingEventStreamPageError}. */
+interface NonProgressingEventStreamPageErrorOptions {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  /** Exclusive continuation cursor supplied to `EventStore.readStream`. */
+  readonly fromVersion: number;
+  /** Pinned inclusive stream version the replay still has to reach. */
+  readonly targetVersion: number;
+}
+/**
+ * Thrown by a paged EventStore consumer when `readStream` returns no events
+ * even though its continuation cursor has not reached the pinned target.
+ * Such a page cannot advance and violates the EventStore port contract; a
+ * replay loop that merely continued would spin forever.
+ *
+ * This is a non-retryable infrastructure error: the persistence adapter
+ * deterministically contradicted its port contract, so retrying the same read
+ * is not a recovery policy. Run `createEventStoreContractTests` against the
+ * adapter and fix its windowing/continuation implementation.
+ */
+declare class NonProgressingEventStreamPageError extends InfrastructureError<"NON_PROGRESSING_EVENT_STREAM_PAGE"> {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly fromVersion: number;
+  readonly targetVersion: number;
+  constructor(options: NonProgressingEventStreamPageErrorOptions);
+}
+/**
+ * Thrown when an event harvested from an aggregate cannot be safely composed
+ * into a commit envelope, or when an outbox can prove that accepting a
+ * candidate would violate its event identity/source chain. Harvest failures
+ * include missing `aggregateId` / `aggregateType` (downstream routing would
+ * break), or an
+ * eventful persisted aggregate did not advance its version (two commits
+ * would receive the same source position). These programming bugs are
+ * deterministic and fail identically on every retry.
+ *
+ * Deliberately **not** an {@link InfrastructureError} (same reasoning as
+ * {@link MissingHandlerError}): this is a deterministic programming error,
+ * not a transient storage failure. A `catch (e instanceof InfrastructureError)`
+ * retry handler, or a retrying `TransactionScope`, must NOT mask it or loop on
+ * it forever; it should crash loud so the caller misuse surfaces in
+ * development. This is why `withCommit` throws it directly and
+ * `UnitOfWork.run` passes it through unchanged instead of wrapping it in
+ * `CommitError`.
+ */
+declare class EventHarvestError extends KitWiringError<"EVENT_HARVEST_FAILED"> {
+  /** The `type` of the offending event, for programmatic routing. */
+  readonly eventType?: string | undefined;
+  constructor(message: string, /** The `type` of the offending event, for programmatic routing. */eventType?: string | undefined);
+}
+/** Constructor options for {@link UnregisteredHandlerError}. */
+interface UnregisteredHandlerErrorOptions {
+  /** Which bus rejected the dispatch. */
+  readonly busKind: "command" | "query";
+  /** The message type no handler was registered for. */
+  readonly messageType: string;
+}
+/**
+ * Produced by the in-memory `CommandBus` / `QueryBus` when a message is
+ * dispatched for a type no handler was registered under: a wiring bug
+ * (typo in the type string, missing `register` call at bootstrap), not
+ * a domain or infrastructure failure.
+ *
+ * Carries the `WIRING` category (same crash-loud family as
+ * {@link MissingHandlerError}), and since v3 it is THROWN by `execute`
+ * and `executeUnsafe` alike, never delivered through the error channel:
+ * the channel carries expected failures a registered handler produced,
+ * and a generic err-branch must not absorb a mis-wired bus. Catch it
+ * only at a boundary that turns bugs into 500s.
+ */
+declare class UnregisteredHandlerError extends KitWiringError<"UNREGISTERED_HANDLER"> {
+  readonly busKind: "command" | "query";
+  readonly messageType: string;
+  constructor(options: UnregisteredHandlerErrorOptions);
+}
+/** Constructor options for {@link DuplicateHandlerRegistrationError}. */
+interface DuplicateHandlerRegistrationErrorOptions {
+  /** Which bus rejected the registration. */
+  readonly busKind: "command" | "query";
+  /** The message type a handler was already registered for. */
+  readonly messageType: string;
+}
+/**
+ * Produced by `CommandBus.register` / `QueryBus.register` when a handler
+ * is registered for a type that already has one: silent replacement would
+ * turn the first handler into dead code with no signal, so the wiring bug
+ * surfaces at registration time. Same crash-loud family as
+ * {@link UnregisteredHandlerError}; catch it only at a boundary that
+ * turns bugs into 500s.
+ */
+declare class DuplicateHandlerRegistrationError extends KitWiringError<"DUPLICATE_HANDLER_REGISTRATION"> {
+  readonly busKind: "command" | "query";
+  readonly messageType: string;
+  constructor(options: DuplicateHandlerRegistrationErrorOptions);
+}
+/** Constructor options for {@link ErrorMapperFailedError}. */
+interface ErrorMapperFailedErrorOptions {
+  /** Which bus was mapping the failure. */
+  readonly busKind: "command" | "query";
+  /** The registered handler's ORIGINAL failure (also set as `cause`). */
+  readonly handlerError: unknown;
+  /** The mapper failure or invalid-decision diagnostic. */
+  readonly mapperError: unknown;
+}
+/**
+ * Produced by the in-memory `CommandBus` / `QueryBus` when the configured
+ * `mapExpectedError` policy fails while classifying a registered handler's
+ * failure, either by throwing or by returning an invalid decision. A broken
+ * mapper is a wiring bug: letting its failure propagate bare would
+ * replace the handler's original failure entirely, and the rest of the
+ * kit is fastidious about never letting a secondary failure mask the
+ * primary one (`RollbackError.rollbackCause`, the neutralized observers).
+ *
+ * The handler's original failure is preserved as `cause` (so cause-chain
+ * walks, retryability checks, and error-type mapping keep working) and
+ * the mapper's own failure rides along as {@link mapperCause}.
+ *
+ * Carries the `WIRING` category (same crash-loud family as
+ * {@link MissingHandlerError} and {@link UnregisteredHandlerError}): it is
+ * thrown, never delivered through the error channel.
+ */
+declare class ErrorMapperFailedError extends KitWiringError<"ERROR_MAPPER_FAILED"> {
+  readonly busKind: "command" | "query";
+  /** The mapper failure or invalid-decision diagnostic. */
+  readonly mapperCause: unknown;
+  constructor(options: ErrorMapperFailedErrorOptions);
+}
+/**
+ * Thrown at the end of a `UnitOfWork.run` when an aggregate that was
+ * loaded into the identity map changed but no `update` intent was registered.
+ * Without this guard the changed state or pending events would be silently
+ * dropped.
+ *
+ * Deliberately **not** an `InfrastructureError` (same posture as
+ * {@link MissingHandlerError}): a programming bug that must crash loud,
+ * not be absorbed by a generic infrastructure-error handler. The throw
+ * happens inside the transaction, so the unit of work rolls back and
+ * leaves no partial state.
+ *
+ * **Scope of the guard.** A best-effort runtime safety net, not a proof.
+ * It sees aggregates that repository adapters register through
+ * `tracking.trackLoaded` and detects ordinary state changes through the version
+ * captured at load. The pending-event count remains a second guard for an
+ * invalid event-only mutation that did not advance the version. A freshly
+ * created aggregate that is never passed to `add` is invisible to the kit.
+ */
+declare class UnenrolledChangesError extends KitWiringError<"UNENROLLED_CHANGES"> {
+  readonly aggregateId: string;
+  constructor(aggregateId: string);
+}
+/**
+ * Thrown when an aggregate removed within the current unit of work is added,
+ * updated, or tracked again in the same operation. Removal is final within an
+ * operation; writing afterwards would resurrect the row, which is always a
+ * use-case bug.
+ *
+ * Carries the `WIRING` category (same reasoning as
+ * {@link MissingHandlerError}): a programming bug that should crash
+ * loud, not be absorbed by a generic infrastructure-error handler.
+ */
+declare class AggregateDeletedError extends KitWiringError<"AGGREGATE_DELETED"> {
+  readonly aggregateId: string;
+  constructor(aggregateId: string);
+}
+/**
+ * Thrown by `AggregatePersistence.getById()` 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 `findById()` if "not found" is a valid outcome.
+ *
+ * Accepts an optional `cause` so a repository adapter can wrap a lower-level
+ * "row not found" or 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.
+ */
+interface AggregateNotFoundErrorOptions {
+  readonly aggregateType: string;
+  readonly id: string;
+  /** Optional lower-level error to preserve in the cause chain. */
+  readonly cause?: unknown;
+}
+declare class AggregateNotFoundError extends InfrastructureError<"AGGREGATE_NOT_FOUND"> {
+  readonly aggregateType: string;
+  readonly id: string;
+  constructor(options: AggregateNotFoundErrorOptions);
+}
+/**
+ * Thrown by a repository's `add()` flush when a row with the
+ * aggregate's id already exists (unique-constraint violation): two
+ * concurrent creators raced on the same business-derived id, or the
+ * id generator collided. Same delegation model as
+ * {@link ConcurrencyConflictError}: the kit ships the class, the
+ * consumer repository maps its driver's unique-violation signal to it
+ * instead of letting a raw driver error escape -
+ *
+ * - Postgres: SQLSTATE `23505` (`unique_violation`)
+ * - MySQL/MariaDB: errno `1062` (`ER_DUP_ENTRY`)
+ * - SQLite: `SQLITE_CONSTRAINT_UNIQUE` (extended code 2067)
+ *
+ * `InfrastructureError` because the storage boundary detects the
+ * collision. NOT retryable: re-running the same INSERT cannot succeed.
+ * The right reactions are domain decisions - map to HTTP 409, or for
+ * idempotency-key flows load the existing aggregate and treat the
+ * request as already-applied.
+ */
+interface DuplicateAggregateErrorOptions {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  /** Optional driver-level error to preserve in the cause chain. */
+  readonly cause?: unknown;
+}
+declare class DuplicateAggregateError extends InfrastructureError<"DUPLICATE_AGGREGATE"> {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  constructor(options: DuplicateAggregateErrorOptions);
+}
+/**
+ * Thrown by `reconstituteAggregateFromSnapshot` when the stored snapshot
+ * carries a different schema version than its adapter-owned `SnapshotModel`
+ * and the model declares no `migrate` function. Without the check, a snapshot
+ * written against an older DTO shape would surface as an undefined-field crash on
+ * the first method call after a much later restore.
+ *
+ * `InfrastructureError` because the storage boundary served outdated
+ * data; the schema evolving past stored snapshots is an expected
+ * lifecycle event, not a programming bug. NOT retryable: the recovery
+ * is a code path, not a repeat. Add `migrate` to the snapshot model (upgrade
+ * old DTOs in place), or catch this error in the repository, discard the
+ * snapshot, and refold from the full event stream / reload from the source of
+ * truth.
+ */
+interface SnapshotSchemaMismatchErrorOptions {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly expectedSchemaVersion: number;
+  readonly actualSchemaVersion: number;
+}
+declare class SnapshotSchemaMismatchError extends InfrastructureError<"SNAPSHOT_SCHEMA_MISMATCH"> {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly expectedSchemaVersion: number;
+  readonly actualSchemaVersion: number;
+  constructor(options: SnapshotSchemaMismatchErrorOptions);
+}
+/**
+ * Surfaced by a Unit-of-Work flush 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.
+ *
+ * **Retry means a FRESH unit of work** (a new `UnitOfWork.run()` /
+ * `withCommit` invocation): reload, re-apply, and register `update` again. Do NOT catch this
+ * inside the same `run()` callback and continue: the failed aggregate
+ * is already enrolled (its events would be committed for a write that
+ * never happened) and the identity map still serves the same stale
+ * instance to any in-place "reload".
+ *
+ * `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.
+ */
+interface ConcurrencyConflictErrorOptions {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly expectedVersion: number;
+  readonly actualVersion: number;
+  /** Optional driver-level error to preserve in the cause chain. */
+  readonly cause?: unknown;
+}
+declare class ConcurrencyConflictError extends InfrastructureError<"CONCURRENCY_CONFLICT"> {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly expectedVersion: number;
+  readonly actualVersion: number;
+  constructor(options: ConcurrencyConflictErrorOptions);
+}
+/**
+ * Options bag for {@link IdempotencyKeyReuseError}.
+ */
+interface IdempotencyKeyReuseErrorOptions {
+  readonly key: string;
+  readonly storedFingerprint: string;
+  readonly receivedFingerprint: string;
+  /** Optional driver-level error to preserve in the cause chain. */
+  readonly cause?: unknown;
+}
+/**
+ * Thrown by `IdempotencyStore.claim()` when the same idempotency key
+ * arrives with a DIFFERENT command fingerprint than the one it was
+ * first claimed with: the caller is reusing a key for a different
+ * command. Replaying the stored outcome would answer a question that
+ * was never asked; rejecting is the only safe reaction.
+ *
+ * `InfrastructureError` because the store detects the collision, same
+ * delegation model as {@link DuplicateAggregateError}. NOT retryable:
+ * re-sending the same mismatched pair cannot succeed. Map it to an
+ * unprocessable/conflict application outcome.
+ */
+declare class IdempotencyKeyReuseError extends InfrastructureError<"IDEMPOTENCY_KEY_REUSE"> {
+  readonly key: string;
+  readonly storedFingerprint: string;
+  readonly receivedFingerprint: string;
+  constructor(options: IdempotencyKeyReuseErrorOptions);
+}
+/** Options bag for {@link IdempotencyClaimLostError}. */
+interface IdempotencyClaimLostErrorOptions {
+  readonly key: string;
+  readonly token: string;
+  /** Optional driver-level error to preserve in the cause chain. */
+  readonly cause?: unknown;
+}
+/**
+ * Thrown when a leased idempotency owner tries to renew, complete, or
+ * reconcile through a claim token that no longer owns the key. The usual
+ * cause is lease expiry followed by a successful takeover. The stale
+ * execution must abort before its transaction commits; retrying starts from
+ * a fresh claim or replays the winner.
+ */
+declare class IdempotencyClaimLostError extends InfrastructureError<"IDEMPOTENCY_CLAIM_LOST"> {
+  readonly key: string;
+  readonly token: string;
+  constructor(options: IdempotencyClaimLostErrorOptions);
+}
+/**
+ * Options bag for {@link IdempotencyInFlightError}.
+ */
+interface IdempotencyInFlightErrorOptions {
+  readonly key: string;
+  /** Optional driver-level error to preserve in the cause chain. */
+  readonly cause?: unknown;
+}
+/**
+ * Thrown by `IdempotencyStore.claim()` when the key is already claimed
+ * by an execution that has not completed yet: the first delivery of the
+ * command is still running (or crashed mid-flight on a
+ * non-transactional store). Retryable by design: a later retry either
+ * finds the completed outcome and replays it, or finds the claim
+ * released (rolled back) and executes fresh. `RetryingTransactionScope`
+ * picks this up through the `retryable` flag without extra wiring.
+ */
+declare class IdempotencyInFlightError extends InfrastructureError<"IDEMPOTENCY_IN_FLIGHT"> {
+  readonly key: string;
+  constructor(options: IdempotencyInFlightErrorOptions);
+}
+/** Options bag for {@link IdempotencyReconciliationRequiredError}. */
+interface IdempotencyReconciliationRequiredErrorOptions {
+  readonly key: string;
+  readonly fingerprint: string;
+  readonly token: string;
+  readonly expiredAt: string;
+}
+/**
+ * An expired staged outcome cannot be replayed or discarded until the
+ * application checks the authoritative write model. Immediate retry without
+ * that evidence cannot make progress, so this error is deliberately not
+ * marked retryable.
+ */
+declare class IdempotencyReconciliationRequiredError extends InfrastructureError<"IDEMPOTENCY_RECONCILIATION_REQUIRED"> {
+  readonly key: string;
+  readonly fingerprint: string;
+  readonly token: string;
+  readonly expiredAt: string;
+  constructor(options: IdempotencyReconciliationRequiredErrorOptions);
+}
+/**
+ * Thrown by `IdempotencyStore.complete()` when no pending claim exists
+ * for the key: `complete` ran without a preceding successful `claim`
+ * in the same execution, or against a key whose claim was already
+ * completed or abandoned. Always a wiring bug in hand-rolled
+ * orchestration (`withIdempotentCommit` cannot produce it), hence the
+ * crash-loud category.
+ */
+declare class IdempotencyCompletionWithoutClaimError extends KitWiringError<"IDEMPOTENCY_COMPLETED_WITHOUT_CLAIM"> {
+  readonly key: string;
+  constructor(key: string);
+}
+/**
+ * The closed union of every error code the kit itself can produce
+ * (consumer subclasses of {@link DomainError} / {@link InfrastructureError}
+ * add their own on top). Useful for building `switch` tables or
+ * base-error `matchError` cases that cover kit and consumer codes
+ * together, without importing anything from base-error.
+ */
+type KitErrorCode = "AGGREGATE_DELETED" | "AGGREGATE_NOT_FOUND" | "AGGREGATE_TRACKING" | "COMMIT_FAILED" | "CONCURRENCY_CONFLICT" | "DOMAIN_TRANSITION_GUARD_REJECTED" | "DUPLICATE_AGGREGATE" | "DUPLICATE_EVENT_ID" | "DUPLICATE_HANDLER_REGISTRATION" | "ERROR_MAPPER_FAILED" | "EVENT_ADDRESS_INVALID" | "EVENT_HARVEST_FAILED" | "EVENT_ID_INVALID" | "EVENT_ID_REQUIRED" | "EVENT_OCCURRED_AT_INVALID" | "EVENT_OCCURRED_AT_REQUIRED" | "EVENT_SCHEMA_VERSION_INVALID" | "EVENT_TYPE_INVALID" | "FOREIGN_EVENT" | "HOSTILE_STATE_KEY" | "IDEMPOTENCY_CLAIM_LOST" | "IDEMPOTENCY_COMPLETED_WITHOUT_CLAIM" | "IDEMPOTENCY_IN_FLIGHT" | "IDEMPOTENCY_KEY_REUSE" | "IDEMPOTENCY_RECONCILIATION_REQUIRED" | "IN_MEMORY_CAPACITY_EXCEEDED" | "INVALID_DOMAIN_MACHINE_CONTEXT" | "INVALID_DOMAIN_MACHINE_DEFINITION" | "INVALID_DOMAIN_MACHINE_INPUT" | "INVALID_DOMAIN_MACHINE_SNAPSHOT" | "INVALID_DOMAIN_TRANSITION" | "INVALID_DOMAIN_TRANSITION_GUARD_RESULT" | "INVALID_DOMAIN_TRANSITION_RESULT" | "INVALID_COMMAND_MESSAGE" | "INVALID_INTEGRATION_MESSAGE" | "INVALID_MONEY" | "INVALID_REPOSITORY_ADAPTER" | "INVALID_REPOSITORY_DEFINITION" | "MISADDRESSED_EVENT" | "MISSING_HANDLER" | "MONEY_CURRENCY_MISMATCH" | "MONEY_PRECISION_LOSS" | "MONEY_SCALE_MISMATCH" | "NESTED_UNIT_OF_WORK" | "NON_PROGRESSING_EVENT_STREAM_PAGE" | "PROJECTION_GAP" | "PROJECTION_IDENTITY_VIOLATION" | "PROJECTION_ORDER_VIOLATION" | "PROJECTION_RECEIPT_VIOLATION" | "REENTRANT_DOMAIN_STATE_MACHINE_EVALUATION" | "REENTRANT_EVENT_RECORDING" | "REPOSITORY_ERROR_MAPPING_FAILED" | "ROLLBACK_FAILED" | "SNAPSHOT_CORRUPTED" | "SNAPSHOT_SCHEMA_MISMATCH" | "SNAPSHOT_TIME_INVALID" | "TRANSACTION_CLOSED" | "UNENROLLED_CHANGES" | "UNKNOWN_CURRENCY" | "UNMINTED_EVENT" | "UNPROJECTABLE_EVENT" | "UNREGISTERED_HANDLER" | "UNREPLAYABLE_AGGREGATE";
+//#endregion
+export { isInfrastructureErrorLike as $, InvalidIntegrationMessageError as A, ProjectionOrderViolationError as B, IdempotencyKeyReuseErrorOptions as C, InMemoryCapacityExceededErrorOptions as D, InMemoryCapacityExceededError as E, MissingHandlerError as F, SnapshotSchemaMismatchErrorOptions as G, ReentrantEventRecordingError as H, NonProgressingEventStreamPageError as I, UnprojectableEventError as J, UnenrolledChangesError as K, NonProgressingEventStreamPageErrorOptions as L, KitErrorOptions as M, KitWiringError as N, InfrastructureError as O, MisaddressedEventError as P, isDomainErrorLike as Q, ProjectionGapError as R, IdempotencyKeyReuseError as S, IdempotencyReconciliationRequiredErrorOptions as T, SnapshotCorruptedError as U, ProjectionReceiptViolationError as V, SnapshotSchemaMismatchError as W, UnregisteredHandlerErrorOptions as X, UnregisteredHandlerError as Y, UnreplayableAggregateError as Z, IdempotencyClaimLostError as _, ConcurrencyConflictErrorOptions as a, IdempotencyInFlightError as b, DuplicateAggregateErrorOptions as c, DuplicateHandlerRegistrationErrorOptions as d, ErrorMapperFailedError as f, HostileStateKeyError as g, ForeignEventError as h, ConcurrencyConflictError as i, KitErrorCode as j, InvalidCommandMessageError as k, DuplicateEventIdError as l, EventHarvestError as m, AggregateNotFoundError as n, DomainError as o, ErrorMapperFailedErrorOptions as p, UnmintedEventError as q, AggregateNotFoundErrorOptions as r, DuplicateAggregateError as s, AggregateDeletedError as t, DuplicateHandlerRegistrationError as u, IdempotencyClaimLostErrorOptions as v, IdempotencyReconciliationRequiredError as w, IdempotencyInFlightErrorOptions as x, IdempotencyCompletionWithoutClaimError as y, ProjectionIdentityViolationError as z };
+//# sourceMappingURL=errors.d.ts.map