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

package/dist/chunks/errors.js

@@ -0,0 +1,822 @@
+import { StructuredError } from "@shirudo/base-error";
+
+//#region src/core/errors.ts
+/**
+* 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`,
+*     });
+*   }
+* }
+* ```
+*/
+var DomainError = class extends StructuredError {
+	constructor(options) {
+		super({
+			code: options.code,
+			category: "DOMAIN",
+			retryable: options.retryable ?? false,
+			message: options.message,
+			cause: options.cause
+		});
+	}
+};
+/**
+* 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.
+*/
+var KitWiringError = class extends StructuredError {
+	constructor(code, message, cause) {
+		super({
+			code,
+			category: "WIRING",
+			retryable: false,
+			message,
+			cause
+		});
+	}
+};
+/**
+* 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`).
+*/
+var InfrastructureError = class extends StructuredError {
+	constructor(options) {
+		super({
+			code: options.code,
+			category: "INFRASTRUCTURE",
+			retryable: options.retryable ?? false,
+			message: options.message,
+			cause: options.cause
+		});
+	}
+};
+/**
+* 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.
+*/
+function isDomainErrorLike(value) {
+	return value instanceof DomainError || value instanceof Error && value.category === "DOMAIN";
+}
+/**
+* Copy-safe membership check for the kit's infrastructure-error family.
+* Same rationale as {@link isDomainErrorLike}.
+*/
+function isInfrastructureErrorLike(value) {
+	return value instanceof InfrastructureError || value instanceof Error && value.category === "INFRASTRUCTURE";
+}
+/**
+* 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.
+*/
+var InMemoryCapacityExceededError = class extends InfrastructureError {
+	store;
+	resource;
+	limit;
+	current;
+	attempted;
+	constructor(options) {
+		super({
+			code: "IN_MEMORY_CAPACITY_EXCEEDED",
+			message: `${options.store} cannot retain ${options.attempted} new ${options.resource}: configured limit ${options.limit}, currently retained ${options.current}`
+		});
+		this.store = options.store;
+		this.resource = options.resource;
+		this.limit = options.limit;
+		this.current = options.current;
+		this.attempted = options.attempted;
+	}
+};
+/**
+* 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.
+*/
+var MissingHandlerError = class extends KitWiringError {
+	eventType;
+	constructor(eventType, cause) {
+		super("MISSING_HANDLER", `Missing handler for event type: ${eventType}`, cause);
+		this.eventType = eventType;
+	}
+};
+/**
+* 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.
+*/
+var UnprojectableEventError = class extends KitWiringError {
+	projection;
+	eventId;
+	constructor(projection, eventId, reason, cause) {
+		super("UNPROJECTABLE_EVENT", `Projector(${projection}): event ${eventId} ${reason}`, cause);
+		this.projection = projection;
+		this.eventId = eventId;
+	}
+};
+/**
+* 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.
+*/
+var ProjectionGapError = class extends InfrastructureError {
+	projection;
+	eventId;
+	previousPosition;
+	receivedPosition;
+	constructor(projection, eventId, previousPosition, receivedPosition) {
+		super({
+			code: "PROJECTION_GAP",
+			message: `Projector(${projection}): event ${eventId} creates a projection gap after ${previousPosition}; received ${receivedPosition}. Replay the missing commit before advancing the checkpoint.`
+		});
+		this.projection = projection;
+		this.eventId = eventId;
+		this.previousPosition = previousPosition;
+		this.receivedPosition = receivedPosition;
+	}
+};
+/**
+* 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.
+*/
+var ProjectionOrderViolationError = class extends InfrastructureError {
+	projection;
+	eventId;
+	previousReceivedPosition;
+	receivedPosition;
+	constructor(projection, eventId, previousReceivedPosition, receivedPosition) {
+		super({
+			code: "PROJECTION_ORDER_VIOLATION",
+			message: `Projector(${projection}): event ${eventId} at ${receivedPosition} arrived after the later unprocessed position ${previousReceivedPosition} in the same batch. Partition or serialize the feed by aggregate source.`
+		});
+		this.projection = projection;
+		this.eventId = eventId;
+		this.previousReceivedPosition = previousReceivedPosition;
+		this.receivedPosition = receivedPosition;
+	}
+};
+/**
+* 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.
+*/
+var ProjectionIdentityViolationError = class extends InfrastructureError {
+	projection;
+	eventId;
+	recordedEventId;
+	position;
+	constructor(projection, eventId, recordedEventId, position) {
+		super({
+			code: "PROJECTION_IDENTITY_VIOLATION",
+			message: `Projector(${projection}): position ${position} was already associated with event ${recordedEventId}, but the source supplied event ${eventId} at the same position. A source must map exactly one logical event to each position.`
+		});
+		this.projection = projection;
+		this.eventId = eventId;
+		this.recordedEventId = recordedEventId;
+		this.position = position;
+	}
+};
+/**
+* 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.
+*/
+var ProjectionReceiptViolationError = class extends InfrastructureError {
+	projection;
+	eventId;
+	recordedReceipt;
+	receivedReceipt;
+	constructor(projection, eventId, recordedReceipt, receivedReceipt) {
+		super({
+			code: "PROJECTION_RECEIPT_VIOLATION",
+			message: `Projector(${projection}): event ${eventId} changed its commit receipt at one logical position from ${recordedReceipt} to ${receivedReceipt}. A source must keep commitSize and previousEventfulAggregateVersion immutable.`
+		});
+		this.projection = projection;
+		this.eventId = eventId;
+		this.recordedReceipt = recordedReceipt;
+		this.receivedReceipt = receivedReceipt;
+	}
+};
+/** A malformed or non-JSON-safe message at an integration boundary. */
+var InvalidIntegrationMessageError = class extends InfrastructureError {
+	path;
+	reason;
+	constructor(path, reason, cause) {
+		super({
+			code: "INVALID_INTEGRATION_MESSAGE",
+			message: `Invalid integration message at ${path}: ${reason}`,
+			cause
+		});
+		this.path = path;
+		this.reason = reason;
+	}
+};
+/** A malformed or non-JSON-safe command selected for durable delivery. */
+var InvalidCommandMessageError = class extends InfrastructureError {
+	path;
+	reason;
+	constructor(path, reason, cause) {
+		super({
+			code: "INVALID_COMMAND_MESSAGE",
+			message: `Invalid command message at ${path}: ${reason}`,
+			cause
+		});
+		this.path = path;
+		this.reason = reason;
+	}
+};
+/**
+* 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.
+*/
+var HostileStateKeyError = class extends KitWiringError {
+	key;
+	constructor(key, subject = "Entity state") {
+		super("HOSTILE_STATE_KEY", `${subject} carries a hostile own "${key}" key, which can never be legitimate domain data. Validate and strip untrusted input at the boundary, or model arbitrary keys with a Map.`);
+		this.key = key;
+	}
+};
+/**
+* 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.
+*/
+var UnreplayableAggregateError = class extends KitWiringError {
+	aggregateId;
+	constructor(aggregateId, reason) {
+		super("UNREPLAYABLE_AGGREGATE", `Cannot replay onto aggregate ${aggregateId}: ${reason}. Reconstitute on a fresh instance (no factory-recorded events, no unpersisted mutations).`);
+		this.aggregateId = aggregateId;
+	}
+};
+/**
+* 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.
+*/
+var MisaddressedEventError = class extends KitWiringError {
+	expectedAggregateId;
+	expectedAggregateType;
+	eventType;
+	actualAggregateId;
+	actualAggregateType;
+	constructor(expectedAggregateId, expectedAggregateType, eventType, actualAggregateId, actualAggregateType) {
+		super("MISADDRESSED_EVENT", `New event "${eventType}" is addressed to ${actualAggregateType ?? expectedAggregateType} ${actualAggregateId ?? expectedAggregateId} but was applied on ${expectedAggregateType} ${expectedAggregateId}: fix the call site (createEvent stamps the right address).`);
+		this.expectedAggregateId = expectedAggregateId;
+		this.expectedAggregateType = expectedAggregateType;
+		this.eventType = eventType;
+		this.actualAggregateId = actualAggregateId;
+		this.actualAggregateType = actualAggregateType;
+	}
+};
+/**
+* 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.
+*/
+var SnapshotCorruptedError = class extends InfrastructureError {
+	constructor(message, cause) {
+		super({
+			code: "SNAPSHOT_CORRUPTED",
+			message,
+			cause
+		});
+	}
+};
+/**
+* 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.
+*/
+var UnmintedEventError = class extends KitWiringError {
+	constructor(eventType) {
+		super("UNMINTED_EVENT", `Event "${eventType}" was not minted by a domain-event constructor or aggregate createEvent(...) helper. Those constructors deep-freeze the event and defensively copy payload and metadata; a mutable event could diverge from the state change it records.`);
+	}
+};
+/**
+* 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.
+*/
+var ReentrantEventRecordingError = class extends KitWiringError {
+	constructor(aggregateId) {
+		super("REENTRANT_EVENT_RECORDING", `Pending events of aggregate ${aggregateId} changed while recordPendingEvents was stamping them. A stamp provider must not trigger new decisions on the aggregate being recorded; make every domain decision first, then record.`);
+	}
+};
+/**
+* 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.
+*/
+var DuplicateEventIdError = class extends KitWiringError {
+	eventId;
+	constructor(aggregateId, eventId) {
+		super("DUPLICATE_EVENT_ID", `Two pending events of aggregate ${aggregateId} carry the same eventId "${eventId}". Each decision needs its own identity; return a fresh stamp per event from the stamp provider.`);
+		this.eventId = eventId;
+	}
+};
+/**
+* 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}.
+*/
+var ForeignEventError = class extends InfrastructureError {
+	expectedAggregateId;
+	expectedAggregateType;
+	eventType;
+	actualAggregateId;
+	actualAggregateType;
+	constructor(expectedAggregateId, expectedAggregateType, eventType, actualAggregateId, actualAggregateType) {
+		super({
+			code: "FOREIGN_EVENT",
+			message: `Persisted event "${eventType}" belongs to ${actualAggregateType ?? expectedAggregateType} ${actualAggregateId ?? expectedAggregateId}, not to ${expectedAggregateType} ${expectedAggregateId}: the stream row addresses a different aggregate.`
+		});
+		this.expectedAggregateId = expectedAggregateId;
+		this.expectedAggregateType = expectedAggregateType;
+		this.eventType = eventType;
+		this.actualAggregateId = actualAggregateId;
+		this.actualAggregateType = actualAggregateType;
+	}
+};
+/**
+* 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.
+*/
+var NonProgressingEventStreamPageError = class extends InfrastructureError {
+	aggregateType;
+	aggregateId;
+	fromVersion;
+	targetVersion;
+	constructor(options) {
+		super({
+			code: "NON_PROGRESSING_EVENT_STREAM_PAGE",
+			message: `EventStore returned no events for ${options.aggregateType}(${options.aggregateId}) after version ${options.fromVersion}, before pinned target version ${options.targetVersion}. The page cannot advance; run the EventStore contract suite and fix the adapter's continuation window.`
+		});
+		this.aggregateType = options.aggregateType;
+		this.aggregateId = options.aggregateId;
+		this.fromVersion = options.fromVersion;
+		this.targetVersion = options.targetVersion;
+	}
+};
+/**
+* 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`.
+*/
+var EventHarvestError = class extends KitWiringError {
+	eventType;
+	constructor(message, eventType) {
+		super("EVENT_HARVEST_FAILED", message);
+		this.eventType = eventType;
+	}
+};
+/**
+* Shared guard for the loud-rejection contract on own `__proto__` data
+* keys (the shape `JSON.parse` produces for hostile rows, bodies, or
+* envelopes): used by `Entity` state copies and the event metadata
+* helpers. One implementation so the contract cannot drift.
+* Module-internal export; not part of the package entries.
+*/
+function assertNoHostileOwnProtoKey(value, subject) {
+	if (Object.hasOwn(value, "__proto__")) throw new HostileStateKeyError("__proto__", subject);
+}
+/**
+* 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.
+*/
+var UnregisteredHandlerError = class extends KitWiringError {
+	busKind;
+	messageType;
+	constructor(options) {
+		super("UNREGISTERED_HANDLER", `No handler registered for ${options.busKind} type: ${options.messageType}`);
+		this.busKind = options.busKind;
+		this.messageType = options.messageType;
+	}
+};
+/**
+* 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.
+*/
+var DuplicateHandlerRegistrationError = class extends KitWiringError {
+	busKind;
+	messageType;
+	constructor(options) {
+		super("DUPLICATE_HANDLER_REGISTRATION", `A handler for ${options.busKind} type "${options.messageType}" is already registered; the duplicate would silently shadow the first. Register each type exactly once at bootstrap.`);
+		this.busKind = options.busKind;
+		this.messageType = options.messageType;
+	}
+};
+/**
+* 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.
+*/
+var ErrorMapperFailedError = class extends KitWiringError {
+	busKind;
+	/** The mapper failure or invalid-decision diagnostic. */
+	mapperCause;
+	constructor(options) {
+		super("ERROR_MAPPER_FAILED", `The ${options.busKind} bus mapExpectedError policy failed while classifying a handler failure. The original handler error is preserved as cause; the mapper's own failure as mapperCause.`, options.handlerError);
+		this.busKind = options.busKind;
+		this.mapperCause = options.mapperError;
+	}
+};
+/**
+* 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.
+*/
+var UnenrolledChangesError = class extends KitWiringError {
+	aggregateId;
+	constructor(aggregateId) {
+		super("UNENROLLED_CHANGES", `Aggregate ${aggregateId} was loaded and changed in this unit of work, but no update intent was registered. Call repository.update(aggregate) after the final domain decision so state and events flush together.`);
+		this.aggregateId = aggregateId;
+	}
+};
+/**
+* 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.
+*/
+var AggregateDeletedError = class extends KitWiringError {
+	aggregateId;
+	constructor(aggregateId) {
+		super("AGGREGATE_DELETED", `Aggregate ${aggregateId} was removed in this unit of work and cannot be added, updated, tracked, or removed through another instance again. Removal is final within an operation. A repeated remove of the SAME instance is an accepted no-op; if the aggregate must remain, do not remove it.`);
+		this.aggregateId = aggregateId;
+	}
+};
+var AggregateNotFoundError = class extends InfrastructureError {
+	aggregateType;
+	id;
+	constructor(options) {
+		super({
+			code: "AGGREGATE_NOT_FOUND",
+			message: `Aggregate not found: ${options.aggregateType}(${options.id})`,
+			cause: options.cause
+		});
+		this.aggregateType = options.aggregateType;
+		this.id = options.id;
+	}
+};
+var DuplicateAggregateError = class extends InfrastructureError {
+	aggregateType;
+	aggregateId;
+	constructor(options) {
+		super({
+			code: "DUPLICATE_AGGREGATE",
+			message: `Duplicate aggregate: ${options.aggregateType}(${options.aggregateId}) already exists`,
+			cause: options.cause
+		});
+		this.aggregateType = options.aggregateType;
+		this.aggregateId = options.aggregateId;
+	}
+};
+var SnapshotSchemaMismatchError = class extends InfrastructureError {
+	aggregateType;
+	aggregateId;
+	expectedSchemaVersion;
+	actualSchemaVersion;
+	constructor(options) {
+		super({
+			code: "SNAPSHOT_SCHEMA_MISMATCH",
+			message: `Snapshot schema mismatch on ${options.aggregateType}(${options.aggregateId}): the snapshot model expects schema ${options.expectedSchemaVersion}, the stored snapshot carries ${options.actualSchemaVersion}. Override the model's migrate function to upgrade old snapshots, or discard the snapshot and refold from the full event stream.`
+		});
+		this.aggregateType = options.aggregateType;
+		this.aggregateId = options.aggregateId;
+		this.expectedSchemaVersion = options.expectedSchemaVersion;
+		this.actualSchemaVersion = options.actualSchemaVersion;
+	}
+};
+var ConcurrencyConflictError = class extends InfrastructureError {
+	aggregateType;
+	aggregateId;
+	expectedVersion;
+	actualVersion;
+	constructor(options) {
+		super({
+			code: "CONCURRENCY_CONFLICT",
+			message: `Concurrency conflict on ${options.aggregateType}(${options.aggregateId}): expected version ${options.expectedVersion}, actual ${options.actualVersion}`,
+			cause: options.cause,
+			retryable: true
+		});
+		this.aggregateType = options.aggregateType;
+		this.aggregateId = options.aggregateId;
+		this.expectedVersion = options.expectedVersion;
+		this.actualVersion = options.actualVersion;
+	}
+};
+/**
+* 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.
+*/
+var IdempotencyKeyReuseError = class extends InfrastructureError {
+	key;
+	storedFingerprint;
+	receivedFingerprint;
+	constructor(options) {
+		super({
+			code: "IDEMPOTENCY_KEY_REUSE",
+			message: `Idempotency key reuse on "${options.key}": stored fingerprint ${options.storedFingerprint}, received ${options.receivedFingerprint}`,
+			cause: options.cause
+		});
+		this.key = options.key;
+		this.storedFingerprint = options.storedFingerprint;
+		this.receivedFingerprint = options.receivedFingerprint;
+	}
+};
+/**
+* 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.
+*/
+var IdempotencyClaimLostError = class extends InfrastructureError {
+	key;
+	token;
+	constructor(options) {
+		super({
+			code: "IDEMPOTENCY_CLAIM_LOST",
+			message: `Idempotency claim for key "${options.key}" no longer belongs to token "${options.token}"`,
+			cause: options.cause,
+			retryable: true
+		});
+		this.key = options.key;
+		this.token = options.token;
+	}
+};
+/**
+* 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.
+*/
+var IdempotencyInFlightError = class extends InfrastructureError {
+	key;
+	constructor(options) {
+		super({
+			code: "IDEMPOTENCY_IN_FLIGHT",
+			message: `Idempotency key "${options.key}" is claimed by an execution that has not completed yet`,
+			cause: options.cause,
+			retryable: true
+		});
+		this.key = options.key;
+	}
+};
+/**
+* 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.
+*/
+var IdempotencyReconciliationRequiredError = class extends InfrastructureError {
+	key;
+	fingerprint;
+	token;
+	expiredAt;
+	constructor(options) {
+		super({
+			code: "IDEMPOTENCY_RECONCILIATION_REQUIRED",
+			message: `Idempotency key "${options.key}" has an expired staged outcome; consult the authoritative write model before confirming or releasing it`
+		});
+		this.key = options.key;
+		this.fingerprint = options.fingerprint;
+		this.token = options.token;
+		this.expiredAt = options.expiredAt;
+	}
+};
+/**
+* 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.
+*/
+var IdempotencyCompletionWithoutClaimError = class extends KitWiringError {
+	key;
+	constructor(key) {
+		super("IDEMPOTENCY_COMPLETED_WITHOUT_CLAIM", `IdempotencyStore.complete() called for key "${key}" without a pending claim; call claim() first (or use withIdempotentCommit)`);
+		this.key = key;
+	}
+};
+
+//#endregion
+export { SnapshotCorruptedError as A, MissingHandlerError as C, ProjectionOrderViolationError as D, ProjectionIdentityViolationError as E, UnregisteredHandlerError as F, UnreplayableAggregateError as I, assertNoHostileOwnProtoKey as L, UnenrolledChangesError as M, UnmintedEventError as N, ProjectionReceiptViolationError as O, UnprojectableEventError as P, isDomainErrorLike as R, MisaddressedEventError as S, ProjectionGapError as T, InMemoryCapacityExceededError as _, DuplicateAggregateError as a, InvalidIntegrationMessageError as b, ErrorMapperFailedError as c, HostileStateKeyError as d, IdempotencyClaimLostError as f, IdempotencyReconciliationRequiredError as g, IdempotencyKeyReuseError as h, DomainError as i, SnapshotSchemaMismatchError as j, ReentrantEventRecordingError as k, EventHarvestError as l, IdempotencyInFlightError as m, AggregateNotFoundError as n, DuplicateEventIdError as o, IdempotencyCompletionWithoutClaimError as p, ConcurrencyConflictError as r, DuplicateHandlerRegistrationError as s, AggregateDeletedError as t, ForeignEventError as u, InfrastructureError as v, NonProgressingEventStreamPageError as w, KitWiringError as x, InvalidCommandMessageError as y, isInfrastructureErrorLike as z };
+//# sourceMappingURL=errors.js.map