@shirudo/ddd-kit 2.0.0 → 3.0.0-rc.10

package/dist/chunks/kit-errors.d.ts

@@ -0,0 +1,1081 @@
+import { StructuredError } from "@shirudo/base-error";
+//#region src/errors/kit-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>);
+  /** Carries the fields the concrete error declares into the log object. */
+  protected buildLogObject(): Record<string, unknown>;
+}
+/**
+ * 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);
+  /** Carries the fields the concrete error declares into the log object. */
+  protected buildLogObject(): Record<string, 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/application/unit-of-work/errors.ts`).
+ */
+declare abstract class InfrastructureError<TCode extends string = string> extends StructuredError<TCode, "INFRASTRUCTURE"> {
+  protected constructor(options: KitErrorOptions<TCode>);
+  /** Carries the fields the concrete error declares into the log object. */
+  protected buildLogObject(): Record<string, unknown>;
+}
+/**
+ * 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;
+/**
+ * Copy-safe membership check for the kit's wiring-error family.
+ * Same rationale as {@link isDomainErrorLike}.
+ *
+ * A wiring error states a deterministic programming or configuration defect.
+ * A kit boundary that translates failures uses this check to pass such an
+ * error through untouched, instead of relabelling it as a store failure.
+ *
+ * The check narrows to the structural shape, not to a class: the family's
+ * base stays kit-internal, and an error from another kit copy carries the
+ * shape without being an instance of this copy's class.
+ */
+declare function isWiringErrorLike(value: unknown): value is Error & {
+  readonly code: string;
+  readonly category: "WIRING";
+  readonly retryable: false;
+};
+/** 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 a projection built with `projectionFromHandlers` receives an
+ * event type with no own handler entry: the declared event union and the
+ * 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.
+ *
+ * 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 an event-sourced aggregate when `apply()` or replay reaches an
+ * event type with no own entry in the `folds` map: the declared event union
+ * and the map disagree at runtime. Same posture as
+ * {@link MissingHandlerError}: a deterministic bug, never a domain
+ * rejection, so it propagates through `replayHistory` instead of riding its
+ * `Result`.
+ */
+declare class MissingFoldError extends KitWiringError<"MISSING_FOLD"> {
+  readonly eventType: string;
+  constructor(eventType: string, cause?: unknown);
+}
+/**
+ * Thrown by an event-sourced aggregate when a fold returns `undefined`
+ * for an event, which is almost always a fold without a `return` statement.
+ * Storing that result would set the aggregate state to `undefined`, record
+ * the fact anyway on the apply path, and leave every later fold working on
+ * nothing. Same posture as {@link MissingFoldError}: a deterministic bug
+ * in the folds map, never a domain rejection, so it propagates through
+ * `replayHistory` instead of riding its `Result`.
+ */
+declare class FoldReturnedNoStateError extends KitWiringError<"FOLD_RETURNED_NO_STATE"> {
+  readonly eventType: string;
+  constructor(eventType: string);
+}
+/**
+ * Thrown by `EventSourcedAggregate.setState`: on an event-sourced aggregate
+ * the state changes only through `apply()`, where the fact is recorded and
+ * the version advances with it. A direct state write would leave the
+ * instance ahead of its stream with nothing to replay. A wiring error: a
+ * deterministic bug in the aggregate's own code, the remedy is an event
+ * and a handler.
+ */
+declare class DirectStateMutationError extends KitWiringError<"DIRECT_STATE_MUTATION"> {
+  readonly aggregateId: string;
+  constructor(aggregateId: string);
+}
+/**
+ * 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`), by the event-sourced
+ * fold (`apply` and replay), by the event constructors for the payload,
+ * 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. The check looks at the root object only; nested
+ * objects are not walked, and a class instance is an ownership transfer
+ * that passes.
+ *
+ * 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 the `Entity` constructor when the id is not a non-blank
+ * string. That covers `null`, `undefined`, a blank string, and a
+ * non-string value that reached the constructor through a cast. An
+ * entity without a usable identity cannot be tracked, compared, or
+ * persisted, so the construction fails before any state is stored. A
+ * wiring error: a deterministic bug at the call site, never a domain
+ * rejection.
+ */
+declare class MissingEntityIdError extends KitWiringError<"MISSING_ENTITY_ID"> {
+  constructor(
+  /** The rejected value, for the message only; never a usable id. */
+  received: unknown);
+}
+/**
+ * Thrown when a number that is not a valid aggregate version reaches the
+ * kit: `toVersion`, `markReconstituted`, `setVersion`, and the post-commit
+ * acknowledgement all reject it. A version is a safe integer of at least
+ * zero, and a restore never moves below the current version. A wiring
+ * error: an adapter passed a corrupt row value or a wrong number, and
+ * the optimistic-concurrency cursor must not carry it. Not retryable.
+ */
+declare class InvalidVersionError extends KitWiringError<"INVALID_VERSION"> {
+  readonly value: unknown;
+  /** Why the value was rejected, for example "is not a safe integer". */
+  readonly reason: string;
+  constructor(value: unknown,
+  /** Why the value was rejected, for example "is not a safe integer". */
+  reason: string);
+}
+/**
+ * Thrown by `EventSourcedAggregate.replayHistory` 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);
+}
+/**
+ * Constructor options for {@link MisaddressedEventError} and
+ * {@link ForeignEventError}: the address of the aggregate that received the
+ * event, and the address fields the event carries. A missing field on the
+ * event matches by default, so `actual` names only what the event states.
+ */
+interface AggregateAddressMismatchOptions {
+  readonly expected: {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+  };
+  readonly actual: {
+    readonly aggregateType?: string;
+    readonly aggregateId?: string;
+  };
+  readonly eventType: 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"> {
+  /** Address of the aggregate that received the event. */
+  readonly expected: AggregateAddressMismatchOptions["expected"];
+  /** Address fields the event carries. */
+  readonly actual: AggregateAddressMismatchOptions["actual"];
+  readonly eventType: string;
+  constructor(options: AggregateAddressMismatchOptions);
+}
+/** Constructor options for {@link SnapshotVersionNotRestoredError}. */
+interface SnapshotVersionNotRestoredErrorOptions {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  /** The version the snapshot carries. */
+  readonly snapshotVersion: number;
+  /** The version the factory's aggregate reports. */
+  readonly restoredVersion: number;
+}
+/**
+ * Thrown by `reconstituteAggregateFromSnapshot` when the `reconstitute`
+ * factory returns an aggregate at a version other than the snapshot
+ * version. The factory ignored the version parameter, usually a forgotten
+ * `markReconstituted(version)`. A wiring error in the snapshot model,
+ * never snapshot corruption: routing it into the discard-and-refold
+ * channel would mask it as perpetual silent refolding.
+ */
+declare class SnapshotVersionNotRestoredError extends KitWiringError<"SNAPSHOT_VERSION_NOT_RESTORED"> {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly snapshotVersion: number;
+  readonly restoredVersion: number;
+  constructor(options: SnapshotVersionNotRestoredErrorOptions);
+}
+/**
+ * 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`, `setState`, `addDomainEvent`) without having been minted by
+ * the kit's constructors: `createDomainEvent`,
+ * `createDomainEventFromFacts`, `createUncommittedDomainEvent`, or the
+ * aggregate `createEvent` helper. Those constructors deep-freeze the
+ * event, defensively copy payload and metadata, and mark the result as
+ * minted. The mark has two tiers: a
+ * module-private one for events of this loaded copy of the kit, and a
+ * cooperative `Symbol.for` brand that a second loaded copy stamps and
+ * recognizes. 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. The gate catches accidents, not
+ * adversaries: code in the same process can fake the brand.
+ */
+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 when two facts of one aggregate would carry the same `eventId`.
+ * Two causes, two sites: the aggregate rejects a recorded event that is
+ * already pending at the append, before the state moves; and
+ * `recordPendingEvents` rejects a stamp provider that returns one reused
+ * stamp (or repeats an explicit id). Either would mint two distinct facts
+ * sharing one identity, and downstream idempotent consumers keyed on
+ * `eventId` silently drop one of them. A wiring error: deterministic bug at
+ * the append site or in the stamp provider, the remedy is one fresh
+ * identity per fact.
+ */
+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);
+}
+/** Constructor options for {@link PendingEventLimitExceededError}. */
+interface PendingEventLimitExceededErrorOptions {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  /** The configured `maxPendingEvents`. */
+  readonly limit: number;
+  /** Events pending before the rejected recording. */
+  readonly pending: number;
+  /** Events the rejected recording would have added. */
+  readonly added: number;
+}
+/**
+ * Thrown when a recording would grow the pending list of an aggregate past
+ * `AggregateConfig.maxPendingEvents`. The check runs before the state
+ * moves, so the rejected decision records nothing and moves nothing. The
+ * limit is a modelling signal, not a runtime budget: a decision that emits
+ * hundreds of facts points at a missing aggregate boundary, and a retry
+ * repeats it. A wiring error: split the aggregate, or emit fewer facts
+ * per decision.
+ */
+declare class PendingEventLimitExceededError extends KitWiringError<"PENDING_EVENT_LIMIT_EXCEEDED"> {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly limit: number;
+  readonly pending: number;
+  readonly added: number;
+  constructor(options: PendingEventLimitExceededErrorOptions);
+}
+/**
+ * Thrown by the post-commit acknowledgement of an aggregate when the
+ * committed batch is not the prefix of its pending events any more. The
+ * batch is longer than the pending list, or an event in it is not the
+ * pending event at the same position. Acknowledging such a batch would
+ * drop decisions the commit never persisted or keep events it did. The
+ * pending list stays untouched. A wiring error in application commit
+ * orchestration: acknowledge exactly the batch that was enrolled, once.
+ */
+declare class PendingEventBatchMismatchError extends KitWiringError<"PENDING_EVENT_BATCH_MISMATCH"> {
+  readonly aggregateId: string;
+  readonly batchLength: number;
+  readonly pendingLength: number;
+  constructor(aggregateId: string, batchLength: number, pendingLength: number);
+}
+/**
+ * Thrown by persisted-event consumers (including `replayHistory` 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"> {
+  /** Address of the aggregate that received the event. */
+  readonly expected: AggregateAddressMismatchOptions["expected"];
+  /** Address fields the event carries. */
+  readonly actual: AggregateAddressMismatchOptions["actual"];
+  readonly eventType: string;
+  constructor(options: AggregateAddressMismatchOptions);
+}
+/** 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);
+}
+/** Constructor options for {@link ReplayHeadMismatchError}. */
+interface ReplayHeadMismatchErrorOptions {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  /** Pinned inclusive stream head the replay had to reach. */
+  readonly targetVersion: number;
+  /** Version the aggregate holds after the replay. */
+  readonly actualVersion: number;
+}
+/**
+ * Thrown by a load recipe when the replayed aggregate does not end at the
+ * pinned stream head. Events carry no stream position, so the aggregate
+ * cannot detect a tail that overlaps the restored version or a page that
+ * lies outside the requested window; only the caller, which pinned the
+ * head, can compare. A snapshot catch-up passes only the events after the
+ * restored version, and the final version must equal the head.
+ *
+ * This is a non-retryable infrastructure error: the persistence adapter
+ * contradicted its port contract. Run `createEventStoreContractTests` and
+ * `createEsRepositoryContractTests` against the adapter and fix its
+ * windowing.
+ */
+declare class ReplayHeadMismatchError extends InfrastructureError<"REPLAY_HEAD_MISMATCH"> {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly targetVersion: number;
+  readonly actualVersion: number;
+  constructor(options: ReplayHeadMismatchErrorOptions);
+}
+/**
+ * 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);
+}
+/**
+ * Thrown at bootstrap when the global key of a kit capability registry
+ * already holds a value that is not a registry: another module claimed
+ * the key. The kit neither shares that value nor overwrites it, because a
+ * silent replacement would break whichever module owned the key first. A
+ * wiring error in the host process; the remedy is one owner per key.
+ */
+declare class CapabilityRegistryConflictError extends KitWiringError<"CAPABILITY_REGISTRY_CONFLICT"> {
+  readonly key: symbol;
+  constructor(key: symbol);
+}
+/**
+ * Thrown when a kit operation receives an instance that this package did
+ * not construct: a structural lookalike, a repository DTO, or an instance
+ * from an incompatible copy of the package. Such an instance carries none
+ * of the kit-managed capabilities the operation needs. A wiring error:
+ * extend the kit's base classes and run one compatible package copy.
+ */
+declare class UnmanagedInstanceError extends KitWiringError<"UNMANAGED_INSTANCE"> {
+  /** The kit operation that rejected the instance. */
+  readonly operation: string;
+  /** What was rejected: "aggregate", "entity", "the persistence baseline". */
+  readonly subject: string;
+  /** The rejected instance's id, when it has one. */
+  readonly instanceId?: unknown | undefined;
+  constructor(
+  /** The kit operation that rejected the instance. */
+  operation: string,
+  /** What was rejected: "aggregate", "entity", "the persistence baseline". */
+  subject: string,
+  /** The rejected instance's id, when it has one. */
+  instanceId?: unknown | undefined,
+  /** One extra sentence about the registry state, when it explains the rejection. */
+  detail?: string);
+}
+/** 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.
+ *
+ * An append-only repository installs no `update`, so for its aggregate the
+ * message names the rule instead: a loaded append-only aggregate must not
+ * change.
+ */
+declare class UnenrolledChangesError extends KitWiringError<"UNENROLLED_CHANGES"> {
+  readonly aggregateId: string;
+  constructor(aggregateId: string, options?: {
+    readonly appendOnly?: boolean;
+  });
+}
+/**
+ * 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);
+}
+/**
+ * Why the version check failed, and whether a stored version exists to name.
+ *
+ * The reason is diagnostic. Callers branch on the code and on `retryable`,
+ * never on the reason.
+ */
+type ConcurrencyConflictReason =
+/** The aggregate is stored at another version. `actualVersion` carries it. */
+"stale_version" |
+/**
+ * The write matched nothing although the stored version equals the
+ * expected one. Either the write statement carries a condition beyond the
+ * version, for example a tenant id. Or its version read answered from a
+ * transaction snapshot instead of the current row. Both are defects of the
+ * adapter, so this reason is the one that is not retryable: a predicate
+ * defect fires on every write, and retrying it multiplies the load of a
+ * broken deployment instead of surfacing it.
+ *
+ * One occurrence does not tell the two causes apart; their rates do. A
+ * predicate defect fires at a flat rate whatever the load, a snapshot read
+ * only when writes race. An adapter whose version read is a snapshot read
+ * can opt this reason back into retrying through the `isRetryable` of its
+ * retry policy.
+ */
+"version_unchanged" |
+/**
+ * The aggregate no longer exists. Only a store that can lose a persisted
+ * record reports this. An append-only event stream cannot: a stream that
+ * was never created is at version 0, which is `stale_version`.
+ */
+"aggregate_absent" |
+/** The version read failed. The failure travels as the cause. */
+"version_unknown";
+type ConcurrencyConflictErrorOptions = {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly expectedVersion: number;
+  /** Optional driver-level error to preserve in the cause chain. */
+  readonly cause?: unknown;
+} & ({
+  readonly reason: "stale_version" | "version_unchanged";
+  /** The version the store holds. */
+  readonly actualVersion: number;
+} | {
+  readonly reason: "aggregate_absent" | "version_unknown";
+  /** No stored version exists to name. */
+  readonly actualVersion?: null;
+});
+/**
+ * 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. Its `retryable` follows the reason, so the
+ * `isRetryable` predicate from `@shirudo/base-error` picks up every reason
+ * but `version_unchanged`, which names a defect of the adapter.
+ */
+declare class ConcurrencyConflictError extends InfrastructureError<"CONCURRENCY_CONFLICT"> {
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+  readonly expectedVersion: number;
+  /** The stored version, or `null` when none exists to name. */
+  readonly actualVersion: number | null;
+  readonly reason: ConcurrencyConflictReason;
+  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" | "CAPABILITY_REGISTRY_CONFLICT" | "COMMIT_FAILED" | "CONCURRENCY_CONFLICT" | "DIRECT_STATE_MUTATION" | "DOMAIN_TRANSITION_GUARD_REJECTED" | "DUPLICATE_AGGREGATE" | "DUPLICATE_EVENT_ID" | "DUPLICATE_HANDLER_REGISTRATION" | "ERROR_MAPPER_FAILED" | "EVENT_ADDRESS_INVALID" | "EVENT_BUS_CLOSED" | "EVENT_HARVEST_FAILED" | "EVENT_ID_INVALID" | "EVENT_ID_REQUIRED" | "EVENT_OCCURRED_AT_INVALID" | "EVENT_OCCURRED_AT_REQUIRED" | "EVENT_SCHEMA_VERSION_INVALID" | "EVENT_TYPE_INVALID" | "FOLD_RETURNED_NO_STATE" | "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_FLUSH_STATEMENT" | "INVALID_INTEGRATION_MESSAGE" | "INVALID_MONEY" | "INVALID_REPOSITORY_ADAPTER" | "INVALID_REPOSITORY_DEFINITION" | "INVALID_VERSION" | "MISADDRESSED_EVENT" | "MISSING_ENTITY_ID" | "MISSING_FOLD" | "MISSING_HANDLER" | "MONEY_CURRENCY_MISMATCH" | "MONEY_PRECISION_LOSS" | "MONEY_SCALE_MISMATCH" | "NESTED_UNIT_OF_WORK" | "NON_PROGRESSING_EVENT_STREAM_PAGE" | "PENDING_EVENT_BATCH_MISMATCH" | "PENDING_EVENT_LIMIT_EXCEEDED" | "PROJECTION_GAP" | "PROJECTION_IDENTITY_VIOLATION" | "PROJECTION_ORDER_VIOLATION" | "PROJECTION_RECEIPT_VIOLATION" | "PUBLISH_DEPTH_EXCEEDED" | "REENTRANT_DOMAIN_STATE_MACHINE_EVALUATION" | "REENTRANT_EVENT_RECORDING" | "REPLAY_HEAD_MISMATCH" | "REPOSITORY_ERROR_MAPPING_FAILED" | "ROLLBACK_FAILED" | "SNAPSHOT_CORRUPTED" | "SNAPSHOT_SCHEMA_MISMATCH" | "SNAPSHOT_TIME_INVALID" | "SNAPSHOT_VERSION_NOT_RESTORED" | "TRANSACTION_CLOSED" | "UNENROLLED_CHANGES" | "UNKNOWN_CURRENCY" | "UNMANAGED_INSTANCE" | "UNMINTED_EVENT" | "UNPROJECTABLE_EVENT" | "UNREGISTERED_HANDLER" | "UNREPLAYABLE_AGGREGATE";
+//#endregion
+export { ReentrantEventRecordingError as $, IdempotencyReconciliationRequiredErrorOptions as A, MisaddressedEventError as B, IdempotencyClaimLostErrorOptions as C, IdempotencyKeyReuseError as D, IdempotencyInFlightErrorOptions as E, InvalidIntegrationMessageError as F, NonProgressingEventStreamPageErrorOptions as G, MissingFoldError as H, InvalidVersionError as I, PendingEventLimitExceededErrorOptions as J, PendingEventBatchMismatchError as K, KitErrorCode as L, InMemoryCapacityExceededErrorOptions as M, InfrastructureError as N, IdempotencyKeyReuseErrorOptions as O, InvalidCommandMessageError as P, ProjectionReceiptViolationError as Q, KitErrorOptions as R, IdempotencyClaimLostError as S, IdempotencyInFlightError as T, MissingHandlerError as U, MissingEntityIdError as V, NonProgressingEventStreamPageError as W, ProjectionIdentityViolationError as X, ProjectionGapError as Y, ProjectionOrderViolationError as Z, ErrorMapperFailedErrorOptions as _, CapabilityRegistryConflictError as a, SnapshotVersionNotRestoredError as at, ForeignEventError as b, ConcurrencyConflictReason as c, UnmanagedInstanceError as ct, DuplicateAggregateError as d, UnregisteredHandlerError as dt, ReplayHeadMismatchError as et, DuplicateAggregateErrorOptions as f, UnregisteredHandlerErrorOptions as ft, ErrorMapperFailedError as g, isWiringErrorLike as gt, DuplicateHandlerRegistrationErrorOptions as h, isInfrastructureErrorLike as ht, AggregateNotFoundErrorOptions as i, SnapshotSchemaMismatchErrorOptions as it, InMemoryCapacityExceededError as j, IdempotencyReconciliationRequiredError as k, DirectStateMutationError as l, UnmintedEventError as lt, DuplicateHandlerRegistrationError as m, isDomainErrorLike as mt, AggregateDeletedError as n, SnapshotCorruptedError as nt, ConcurrencyConflictError as o, SnapshotVersionNotRestoredErrorOptions as ot, DuplicateEventIdError as p, UnreplayableAggregateError as pt, PendingEventLimitExceededError as q, AggregateNotFoundError as r, SnapshotSchemaMismatchError as rt, ConcurrencyConflictErrorOptions as s, UnenrolledChangesError as st, AggregateAddressMismatchOptions as t, ReplayHeadMismatchErrorOptions as tt, DomainError as u, UnprojectableEventError as ut, EventHarvestError as v, IdempotencyCompletionWithoutClaimError as w, HostileStateKeyError as x, FoldReturnedNoStateError as y, KitWiringError as z };
+//# sourceMappingURL=kit-errors.d.ts.map