@shirudo/ddd-kit 1.1.0 → 1.3.0

package/dist/aggregate-BGdgvqKh.d.ts

@@ -0,0 +1,716 @@
+import { Result } from '@shirudo/result';
+import { BaseError } from '@shirudo/base-error';
+
+/**
+ * Branded string ID. `Tag` carries the aggregate / entity name so two ids
+ * with different tags are not assignable to each other even though both
+ * are strings at runtime.
+ *
+ * @example
+ * ```ts
+ * type UserId = Id<"UserId">;
+ * type OrderId = Id<"OrderId">;
+ *
+ * const u = "user-1" as UserId;
+ * const o: OrderId = u; // ❌ compile error
+ * ```
+ */
+type Id<Tag extends string> = string & {
+    readonly __brand: Tag;
+};
+/**
+ * Produces fresh ids of a single, fixed tag. The tag is bound at the
+ * generator type: `IdGenerator<"UserId">.next()` returns `Id<"UserId">`
+ * with no caller-side generic to abuse.
+ *
+ * **Your factory must produce unique ids under concurrent calls.**
+ * The kit makes no attempt to dedupe or detect collisions: a collision
+ * silently overwrites earlier rows (under unique-key constraints) or
+ * silently aliases two different entities (without them). Safe choices:
+ * `crypto.randomUUID()` (UUIDv4, the default for events), ULID, UUIDv7,
+ * KSUID: all collision-resistant by design. Unsafe choices: `Date.now()`
+ * alone (duplicates within the same millisecond), a process-local
+ * counter without persistence (resets to 1 on restart, collides with
+ * prior runs), a sequential id derived from non-atomic state.
+ *
+ * @example
+ * ```ts
+ * import { ulid } from "ulid";
+ *
+ * const userIds: IdGenerator<"UserId"> = { next: () => ulid() as Id<"UserId"> };
+ * const id = userIds.next(); // Id<"UserId">
+ * ```
+ *
+ * The previous shape (`IdGenerator { next<T extends string>(): Id<T> }`)
+ * let callers pick `T` themselves: `gen.next<"AnyTag">()` typechecked
+ * even when the generator produced different-tag ids, silently defeating
+ * the brand.
+ */
+interface IdGenerator<Tag extends string> {
+    next: () => Id<Tag>;
+}
+
+/**
+ * Abstract base for **domain-invariant violations**. Domain methods
+ * (aggregates, entity validation hooks, value-object constructors)
+ * throw `DomainError`-derived exceptions when a business rule is
+ * violated. Consumers derive their own concrete errors (e.g.
+ * `class OrderAlreadyShippedError extends DomainError<"OrderAlreadyShippedError"> {}`)
+ * for `instanceof`-style catching at the App-Service boundary, where
+ * they typically map to HTTP 400 / business-rule responses.
+ *
+ * The library itself does **not** ship any concrete `DomainError`
+ * subclass: the kit can't know your invariants.
+ *
+ * Extends `BaseError<Name>`; see `@shirudo/base-error` for the inherited
+ * surface (timestamps, cause chains, `toJSON()`, `getUserMessage()`,
+ * `isRetryable`, …).
+ */
+declare abstract class DomainError<Name extends string = string> extends BaseError<Name> {
+}
+/**
+ * Abstract base for **infrastructure / persistence failures** that the
+ * App-Service can recover from: typically by retrying, by returning
+ * HTTP 404 / 409, or by surfacing a "please try again" UX. These are
+ * not domain-invariant violations (the business rules were not
+ * broken); they describe race conditions and missing rows at the
+ * storage boundary.
+ *
+ * Library-internal concrete subclasses: {@link AggregateNotFoundError},
+ * {@link ConcurrencyConflictError}, {@link DuplicateAggregateError},
+ * plus the unit-of-work lifecycle wrappers `CommitError` and
+ * `RollbackError` (in `src/app/unit-of-work.ts`).
+ */
+declare abstract class InfrastructureError<Name extends string = string> extends BaseError<Name> {
+}
+/**
+ * Thrown by `EventSourcedAggregate.apply()` when no handler is
+ * registered for the event's type. This means the aggregate's subclass
+ * forgot to add an entry to its `handlers` map: a programming /
+ * configuration bug, not a domain or infrastructure failure.
+ *
+ * Deliberately **not** on `DomainError` or `InfrastructureError`:
+ * a generic `catch (e instanceof DomainError)` handler at the App
+ * layer must not mask a forgotten handler; this should crash loud and
+ * fail the calling Use Case so the bug surfaces in development. The
+ * replay methods (`loadFromHistory`, `restoreFromSnapshotWithEvents`)
+ * also let it propagate uncaught instead of wrapping it in `Result.Err`.
+ *
+ * Use `isBaseError(e)` from `@shirudo/base-error` to detect
+ * "any structured error from the kit or any other BaseError-using
+ * library" at the App boundary.
+ */
+declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
+    readonly eventType: string;
+    constructor(eventType: string, cause?: unknown);
+}
+/**
+ * Thrown by `withCommit` when an event harvested from an aggregate cannot
+ * be safely committed: it is missing `aggregateId` / `aggregateType`
+ * (downstream routing would break), or it carries a pre-set
+ * `aggregateVersion` AHEAD of the aggregate's commit version (a leaked or
+ * copied fixture that would advance consumer idempotency watermarks past
+ * real history). Both are programming bugs in how the aggregate recorded
+ * the event, deterministic, and fail identically on every retry.
+ *
+ * Deliberately **not** an {@link InfrastructureError} (same reasoning as
+ * {@link MissingHandlerError}): the failure happens after the work
+ * callback completed, but it is NOT transient. 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
+ * recordEvent / createDomainEvent 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 BaseError<"EventHarvestError"> {
+    /** 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 the end of a `UnitOfWork.run` when an aggregate that was
+ * loaded into the identity map during the operation carries unflushed
+ * `pendingEvents` but was never enrolled (no `session.enrollSaved`, and
+ * not deleted). The almost-certain cause is a repository `save()` that
+ * forgot to call `enrollSaved`, or a use case that recorded events on a
+ * loaded aggregate and never saved it. Without this guard those events
+ * would be silently dropped: never harvested into the outbox, never
+ * published.
+ *
+ * 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 only sees aggregates the identity map knows about (those loaded via
+ * `getById`), and detects new events by comparing the pending-event COUNT
+ * at load against commit, which assumes the kit's append-only event model
+ * (so it cannot see events that were recorded and then cleared within the
+ * same run). A freshly *created* aggregate that was never enrolled is
+ * invisible to the kit. The repository contract test suite remains the
+ * full mitigation. See the Unit of Work guide.
+ */
+declare class UnenrolledChangesError extends BaseError<"UnenrolledChangesError"> {
+    readonly aggregateId: string;
+    constructor(aggregateId: string);
+}
+/**
+ * Thrown when an aggregate that was deleted within the current unit of
+ * work is saved or re-registered again in the same operation: by
+ * `UnitOfWorkSession.enrollSaved` after `enrollDeleted` of the same
+ * instance, and by `IdentityMap.set` for a type+id that was deleted.
+ * Deletion is final within an operation; saving afterwards would write
+ * a row the delete just removed (or resurrect it), which is always a
+ * use-case bug.
+ *
+ * Extends `BaseError` directly (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 BaseError<"AggregateDeletedError"> {
+    readonly aggregateId: string;
+    constructor(aggregateId: string);
+}
+/**
+ * Thrown by `IRepository.getByIdOrFail()` when an aggregate with the
+ * given id does not exist. `InfrastructureError` because the storage
+ * boundary, not a business rule, decided the row is absent. Use the
+ * nullable variant `getById()` if "not found" is a valid outcome.
+ *
+ * Accepts an optional `cause` so a `Repository.save()` implementation
+ * can wrap a lower-level "row not found" / driver-level error without
+ * losing context. Cause-chain helpers (`getRootCause`,
+ * `findInCauseChain`) from `@shirudo/base-error` traverse the chain.
+ *
+ * Not retryable: retrying won't make the row appear.
+ */
+declare class AggregateNotFoundError extends InfrastructureError<"AggregateNotFoundError"> {
+    readonly aggregateType: string;
+    readonly id: string;
+    constructor(aggregateType: string, id: string, cause?: unknown);
+}
+/**
+ * Thrown by a repository's `save()` INSERT path 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.
+ */
+declare class DuplicateAggregateError extends InfrastructureError<"DuplicateAggregateError"> {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    constructor(aggregateType: string, aggregateId: string, cause?: unknown);
+}
+/**
+ * Thrown by `IRepository.save()` when the aggregate's expected version
+ * does not match the version currently persisted: i.e. another writer
+ * updated the aggregate concurrently. The canonical optimistic-
+ * concurrency signal; the App-Service typically reloads, re-applies
+ * the use case, and retries, or surfaces HTTP 409 to the caller.
+ *
+ * **Retry means a FRESH unit of work** (a new `UnitOfWork.run()` /
+ * `withCommit` invocation): reload, re-apply, save. Do NOT catch this
+ * inside the same `run()` callback and continue: the failed aggregate
+ * is already enrolled (its events would be committed for a write that
+ * never happened) and the identity map still serves the same stale
+ * instance to any in-place "reload".
+ *
+ * `InfrastructureError` because the persistence layer (not a domain
+ * rule) detects the race. Marks itself as `retryable: true` so the
+ * `isRetryable` predicate from `@shirudo/base-error` picks it up.
+ */
+declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyConflictError"> {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    /**
+     * Marks this error as retryable so `isRetryable(err)` returns
+     * true. The canonical OCC pattern is to reload the aggregate, re-apply
+     * the use case, and retry on this exception.
+     */
+    readonly retryable: true;
+    constructor(aggregateType: string, aggregateId: string, expectedVersion: number, actualVersion: number, cause?: unknown);
+}
+
+/**
+ * Factory function producing a fresh, unique event identifier for each call.
+ *
+ * The library ships a default that uses Web Crypto `crypto.randomUUID()`
+ * (works on Node 19+, modern browsers in secure contexts, Deno, Bun,
+ * Cloudflare Workers, Vercel Edge, and any runtime that implements Web
+ * Crypto). Note that `crypto.randomUUID()` returns **UUID v4** (purely
+ * random); for production event stores prefer a **time-ordered** id
+ * format (UUID v7 / ULID / KSUID) so B-tree indexes on the eventId
+ * column stay clustered and `ORDER BY eventId` matches creation order.
+ * Swap one in via `setEventIdFactory(() => uuidv7())` or `() => ulid()`.
+ */
+type EventIdFactory = () => string;
+/**
+ * Replaces the global event-id factory used by `createDomainEvent` and
+ * `createDomainEventWithMetadata`. Call once during application bootstrap,
+ * for example:
+ *
+ * ```ts
+ * import { ulid } from "ulid";
+ * import { setEventIdFactory } from "@shirudo/ddd-kit";
+ *
+ * setEventIdFactory(() => ulid());
+ * ```
+ *
+ * The per-call `options.eventId` override always wins over this factory.
+ *
+ * **Module-scoped: last setter wins.** The factory lives as a single
+ * module variable; importing two libraries that both call this races on
+ * load order, and parallel test workers will see each other's factory.
+ * For test isolation and short-lived contexts prefer
+ * {@link withEventIdFactory}; for multi-tenant request isolation
+ * (e.g. one factory per tenant in a single Worker invocation) **prefer
+ * the per-call `options.eventId`** instead of mutating the global. Same
+ * caveat applies to `setClockFactory`.
+ */
+declare function setEventIdFactory(factory: EventIdFactory): void;
+/**
+ * Scoped variant of {@link setEventIdFactory}: installs `factory`,
+ * runs `fn`, then restores the previous factory in a `finally` block,
+ * so the restoration happens even if `fn` throws. Safe for parallel
+ * tests and for synchronous request handlers that need a tenant-
+ * specific factory without polluting the global.
+ *
+ * **Synchronous-only, enforced at runtime.** If `fn` returns a
+ * thenable (a `Promise` or any object with a `then` method), the
+ * helper throws *before* returning the value to the caller. This
+ * catches the async-misuse footgun where the factory would be
+ * restored before the awaited body of `fn` runs, leaving the awaited
+ * code reading the previous factory. For async scoping across `await`
+ * boundaries, use `AsyncLocalStorage`, which is out of scope for this
+ * helper; build it on top if you need it.
+ *
+ * Composes by nesting: an inner `withEventIdFactory` restores back to
+ * the outer's factory; the outer restores to the original.
+ *
+ * **When to prefer the per-call `options.eventId` instead.** If you're
+ * constructing a single event and want full control over its id,
+ * passing `{ eventId: "..." }` to `createDomainEvent` is the strongest
+ * isolation: it bypasses the factory mechanism entirely, no global
+ * mutation, no scope to manage. Reach for `withEventIdFactory` when
+ * the events are constructed deep inside domain methods you can't
+ * thread an explicit id through (typical test scenario), or when many
+ * events in a scope should share the same factory.
+ *
+ * @example
+ * ```ts
+ * // In a vitest test:
+ * it("emits deterministic ids", () => {
+ *   withEventIdFactory(() => "evt-fixed", () => {
+ *     const e = createDomainEvent("X", { v: 1 });
+ *     expect(e.eventId).toBe("evt-fixed");
+ *   });
+ *   // Outside the callback the default crypto.randomUUID is restored,
+ *   // even if the body had thrown.
+ * });
+ * ```
+ */
+declare function withEventIdFactory<T>(factory: EventIdFactory, fn: () => T): T;
+/**
+ * Restores the default event-id factory (`crypto.randomUUID()`).
+ * Intended for use in test `afterEach` hooks.
+ */
+declare function resetEventIdFactory(): void;
+/**
+ * Clock function producing a fresh `Date` for each call. The library
+ * defaults to `() => new Date()`; override globally via `setClockFactory`
+ * for deterministic event-sourcing tests, time-travel debugging, or any
+ * scenario where `occurredAt` must be reproducible.
+ */
+type ClockFactory = () => Date;
+/**
+ * Replaces the global clock factory used by `createDomainEvent` and
+ * `createDomainEventWithMetadata`. Call once during application bootstrap
+ * (or per-test in deterministic test suites):
+ *
+ * ```ts
+ * import { setClockFactory } from "@shirudo/ddd-kit";
+ *
+ * setClockFactory(() => new Date("2026-01-01T00:00:00Z"));
+ * ```
+ *
+ * The per-call `options.occurredAt` override always wins over this
+ * factory. Symmetric to `setEventIdFactory`.
+ *
+ * Module-scoped: see {@link setEventIdFactory} for the global-state
+ * caveats. For test isolation prefer {@link withClockFactory}; for
+ * multi-tenant request isolation prefer the per-call
+ * `options.occurredAt`.
+ */
+declare function setClockFactory(factory: ClockFactory): void;
+/**
+ * Scoped variant of {@link setClockFactory}: installs `factory`, runs
+ * `fn`, then restores the previous factory in a `finally` block.
+ * Synchronous-only, with the same constraints (and same runtime thenable
+ * guard) as {@link withEventIdFactory}.
+ *
+ * **When to prefer the per-call `options.occurredAt` instead.** Same
+ * trade-off as {@link withEventIdFactory}: passing `{ occurredAt }`
+ * to `createDomainEvent` is the strongest isolation for single-event
+ * cases. The scoped helper is for events constructed deep inside
+ * domain methods where threading an explicit timestamp is awkward.
+ *
+ * @example
+ * ```ts
+ * it("stamps events with a fixed clock", () => {
+ *   const fixed = new Date("2026-01-01T00:00:00Z");
+ *   withClockFactory(() => fixed, () => {
+ *     const e = createDomainEvent("X", { v: 1 });
+ *     expect(e.occurredAt).toEqual(fixed);
+ *   });
+ * });
+ * ```
+ */
+declare function withClockFactory<T>(factory: ClockFactory, fn: () => T): T;
+/**
+ * Restores the default clock factory (`() => new Date()`).
+ * Intended for use in test `afterEach` hooks.
+ */
+declare function resetClockFactory(): void;
+/**
+ * Metadata associated with a domain event for traceability and correlation.
+ * Used in event-driven architectures to track event flow across services.
+ */
+interface EventMetadata {
+    /**
+     * Correlation ID for tracing events across multiple services/components.
+     * Typically used to group related events in a distributed system.
+     */
+    correlationId?: string;
+    /**
+     * Causation ID referencing the event or command that caused this event.
+     * Used to build event chains and understand causality.
+     */
+    causationId?: string;
+    /**
+     * User ID of the person or system that triggered the event.
+     */
+    userId?: string;
+    /**
+     * Source service or component that produced the event.
+     */
+    source?: string;
+    /**
+     * Additional custom metadata fields.
+     * Allows extensibility for domain-specific metadata.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Domain Event represents something meaningful that happened in the domain.
+ * Events are immutable and carry information about what occurred.
+ *
+ * **Events are PLAIN DATA objects**, constructed via `createDomainEvent`
+ * (or the aggregate's `recordEvent` helper) and deeply frozen. Class-based
+ * event objects that satisfy this shape structurally via prototype
+ * members are unsupported: the `withCommit` harvest copies events with a
+ * shallow spread (to stamp `aggregateVersion`), which only carries own
+ * enumerable properties.
+ *
+ * **Field-accretion boundary.** This type already carries the write-side
+ * transport concerns the outbox needs (`aggregateId`, `aggregateType`,
+ * `aggregateVersion`, `metadata`). That is the line: further transport
+ * fields (partition keys, tenancy, schema URNs, …) belong in an outbox
+ * envelope / `metadata`, not on the domain event: the next first-class
+ * transport field forces an `OutboxMessage` envelope port instead.
+ *
+ * @template T - The event type name (e.g., "OrderCreated")
+ * @template P - The event payload type
+ */
+interface DomainEvent<T extends string, P = void> {
+    /**
+     * Unique identifier for this specific event instance. Used by idempotent
+     * consumers, outbox dispatch tracking, and as the target of
+     * `metadata.causationId`. Defaults to `crypto.randomUUID()` if not
+     * supplied.
+     */
+    eventId: string;
+    /**
+     * The type of the event, used for routing and handling.
+     */
+    type: T;
+    /**
+     * Identifier of the aggregate that produced the event. Optional at the
+     * library level; set it whenever the producing aggregate is known so
+     * downstream subscribers, outboxes, and projections can scope by entity.
+     */
+    aggregateId?: string;
+    /**
+     * Name of the aggregate type that produced the event (e.g. "Order").
+     * Pairs with `aggregateId` to fully qualify the source aggregate.
+     */
+    aggregateType?: string;
+    /**
+     * The event payload containing the domain data. The field is always
+     * present; its value is `undefined` when `P` is `void`.
+     */
+    payload: P;
+    /**
+     * Timestamp when the event occurred.
+     */
+    occurredAt: Date;
+    /**
+     * Event schema version for handling schema evolution.
+     * Required for safe schema migration in event-sourced systems.
+     * Use 1 for the initial schema version.
+     *
+     * **NOT the aggregate's version**: that is
+     * {@link aggregateVersion}. The two are deliberately distinct
+     * fields: this one says "which shape does the payload have"
+     * (upcasting), the other says "which state revision of the
+     * aggregate emitted this".
+     */
+    version: number;
+    /**
+     * The version of the producing aggregate at COMMIT time: the same
+     * value the OCC row write carries. Stamped automatically by
+     * `withCommit` at the harvest boundary (all events of one aggregate
+     * in one commit share it; their relative order within the commit is
+     * the harvest order), or set manually via
+     * `CreateDomainEventOptions.aggregateVersion`; a pre-set value is
+     * never overwritten.
+     *
+     * Consumers use it for ordering ("apply projections up to aggregate
+     * version N"), idempotency watermarks, debugging, and integration
+     * logs. Optional at the type level: events created outside an
+     * aggregate (system/integration events) and events from older kit
+     * versions don't carry it.
+     */
+    aggregateVersion?: number;
+    /**
+     * Optional metadata for traceability, correlation, and auditing.
+     * Includes correlationId, causationId, userId, source, and custom fields.
+     */
+    metadata?: EventMetadata;
+}
+/**
+ * Upper-bound alias for "any `DomainEvent` shape". Use as a generic
+ * constraint when a type parameter should accept any concrete event
+ * union. The `unknown` payload is the upper bound; concrete unions
+ * still narrow via `Extract<Evt, { type: K }>` at the use-site.
+ */
+type AnyDomainEvent = DomainEvent<string, unknown>;
+/**
+ * Shared option bag for the `createDomainEvent*` factories.
+ */
+interface CreateDomainEventOptions {
+    /**
+     * Override for the auto-generated `eventId`. Pass an existing id (for
+     * replay, tests, or deterministic event sourcing) instead of letting the
+     * factory call `crypto.randomUUID()`.
+     */
+    eventId?: string;
+    /**
+     * Identifier of the aggregate that produced the event.
+     */
+    aggregateId?: string;
+    /**
+     * Name of the aggregate type that produced the event.
+     */
+    aggregateType?: string;
+    /**
+     * Override for the auto-generated `occurredAt` timestamp.
+     */
+    occurredAt?: Date;
+    /**
+     * Override for the default schema version (1).
+     */
+    version?: number;
+    /**
+     * Pre-set the producing aggregate's version (see
+     * `DomainEvent.aggregateVersion`). Normally left unset (`withCommit`
+     * stamps it at the harvest boundary with the commit version), but
+     * useful for replay fixtures and events constructed outside an
+     * aggregate. A pre-set value is never overwritten by the harvest.
+     */
+    aggregateVersion?: number;
+    /**
+     * Event metadata: correlation, causation, user, source, custom fields.
+     */
+    metadata?: EventMetadata;
+}
+/**
+ * Creates a domain event with default values.
+ * Sets occurredAt to current date and version to 1 if not provided.
+ *
+ * **For aggregate-internal events, prefer `this.recordEvent(...)` on
+ * `AggregateRoot` / `EventSourcedAggregate`.** That helper auto-injects
+ * `aggregateId` (from `this.id`) and `aggregateType` (from the
+ * aggregate's declared `aggregateType` property), which downstream
+ * consumers (outbox dispatchers, projection handlers, audit logs)
+ * route by. The `withCommit` harvest boundary now validates both fields
+ * are present and throws if they're missing, so a direct
+ * `createDomainEvent(...)` call inside an aggregate that forgets the
+ * options is caught at runtime.
+ *
+ * Use `createDomainEvent(...)` directly for events that don't belong to
+ * an aggregate: system events, integration events, configuration events,
+ * test fixtures. For those, set `aggregateId` / `aggregateType` in
+ * `options` if downstream consumers expect routing metadata.
+ *
+ * @param type - The event type
+ * @param payload - The event payload
+ * @param options - Optional event configuration (including `aggregateId`
+ *   and `aggregateType` for routing)
+ * @returns A domain event
+ *
+ * @example
+ * ```typescript
+ * const event = createDomainEvent("OrderCreated", { orderId: "123" });
+ * ```
+ */
+declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateDomainEventOptions): DomainEvent<T, void>;
+declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateDomainEventOptions): DomainEvent<T, P>;
+/**
+ * Creates a domain event with metadata for traceability.
+ * Convenience function for creating events with correlation and causation IDs.
+ *
+ * @example
+ * ```typescript
+ * const event = createDomainEventWithMetadata(
+ *   "OrderCreated",
+ *   { orderId: "123" },
+ *   { correlationId: "corr-123", causationId: "cmd-456", userId: "user-789" }
+ * );
+ * ```
+ */
+declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: Omit<CreateDomainEventOptions, "metadata">): DomainEvent<T, P>;
+/**
+ * Copies metadata from a source event to a new event.
+ * Useful for maintaining correlation chains in event-driven architectures.
+ *
+ * @example
+ * ```typescript
+ * const newEvent = createDomainEvent(
+ *   "OrderShipped",
+ *   { orderId: "123" },
+ *   { metadata: copyMetadata(previousEvent, { causationId: previousEvent.type }) }
+ * );
+ * ```
+ */
+declare function copyMetadata(sourceEvent: AnyDomainEvent, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
+/**
+ * Merges multiple metadata objects into one.
+ * Later metadata objects override earlier ones for the same keys.
+ *
+ * @example
+ * ```typescript
+ * const metadata = mergeMetadata(
+ *   { correlationId: "corr-123" },
+ *   { userId: "user-456" },
+ *   { source: "order-service" }
+ * );
+ * ```
+ */
+declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
+
+type Version = number & {
+    readonly __v: true;
+};
+/**
+ * Snapshot of an aggregate state at a specific point in time.
+ * Used for optimizing event replay by starting from a snapshot
+ * instead of replaying all events from the beginning.
+ *
+ * @template TState - The type of the aggregate state
+ */
+interface AggregateSnapshot<TState> {
+    /**
+     * The state of the aggregate at the time of the snapshot.
+     */
+    state: TState;
+    /**
+     * The version of the aggregate when the snapshot was taken.
+     */
+    version: Version;
+    /**
+     * Timestamp when the snapshot was created.
+     */
+    snapshotAt: Date;
+}
+/**
+ * Public contract every Aggregate Root satisfies. Implemented by
+ * `BaseAggregate` and inherited by both `AggregateRoot` and
+ * `EventSourcedAggregate`. Repository implementations type their
+ * `save(aggregate)` parameter against this interface rather than the
+ * concrete classes, so the repo layer does not take a compile-time
+ * dependency on the aggregate hierarchy.
+ *
+ * Full per-member documentation lives on the concrete `BaseAggregate`
+ * class; the interface is intentionally terse to avoid drift.
+ *
+ * @template TId    - The aggregate root identifier (branded via `Id<Tag>`)
+ * @template TEvent - The domain-event union, defaults to `never`
+ */
+interface IAggregateRoot<TId extends Id<string>, TEvent = never> {
+    readonly id: TId;
+    readonly version: Version;
+    readonly persistedVersion: Version | undefined;
+    readonly pendingEvents: ReadonlyArray<TEvent>;
+    clearPendingEvents(): void;
+    markPersisted(version: Version): void;
+}
+/**
+ * Public contract for Event-Sourced Aggregate Roots. Extends
+ * `IAggregateRoot` with the replay-from-history boundary.
+ *
+ * @template TId    - The aggregate root identifier
+ * @template TEvent - The union type of all domain events
+ */
+interface IEventSourcedAggregate<TId extends Id<string>, TEvent extends AnyDomainEvent> extends IAggregateRoot<TId, TEvent> {
+    /**
+     * Reconstitutes the aggregate from an event history. Returns
+     * `Result` because event-stream corruption is an expected
+     * recoverable failure at the infrastructure boundary.
+     */
+    loadFromHistory(history: ReadonlyArray<TEvent>): Result<void, DomainError>;
+}
+/**
+ * Checks if two aggregates are at the same version (same ID and version).
+ * Useful for optimistic concurrency control checks.
+ *
+ * Note: Two aggregates with the same ID ARE the same aggregate (identity).
+ * This function checks if they are at the same version: i.e., no concurrent modification.
+ *
+ * @example
+ * ```typescript
+ * const before = await repository.getById(id);
+ * // ... some operations ...
+ * const after = await repository.getById(id);
+ *
+ * if (!sameVersion(before, after)) {
+ *   throw new Error("Aggregate was modified by another process");
+ * }
+ * ```
+ */
+declare function sameVersion<TId extends Id<string>>(a: {
+    id: TId;
+    version: Version;
+}, b: {
+    id: TId;
+    version: Version;
+}): boolean;
+
+export { type AnyDomainEvent as A, type CreateDomainEventOptions as C, DomainError as D, type EventIdFactory as E, type IAggregateRoot as I, MissingHandlerError as M, UnenrolledChangesError as U, type Version as V, type Id as a, type AggregateSnapshot as b, type IEventSourcedAggregate as c, InfrastructureError as d, setEventIdFactory as e, type ClockFactory as f, setClockFactory as g, withClockFactory as h, resetClockFactory as i, type EventMetadata as j, type DomainEvent as k, createDomainEvent as l, createDomainEventWithMetadata as m, copyMetadata as n, mergeMetadata as o, EventHarvestError as p, AggregateDeletedError as q, resetEventIdFactory as r, sameVersion as s, AggregateNotFoundError as t, DuplicateAggregateError as u, ConcurrencyConflictError as v, withEventIdFactory as w, type IdGenerator as x };