@shirudo/ddd-kit 3.0.0-rc.13 → 3.0.0-rc.14

package/dist/chunks/snapshot-store.d.ts

@@ -193,15 +193,16 @@ type ClockFactory = () => Date;
 /**
  * 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.
- * Supply one to {@link createDomainEventFactory} to use UUID v7, ULID,
- * KSUID, or another collision-safe format without mutating module state.
+ * The library ships a default that creates a time-ordered **UUID v7** from
+ * Web Crypto random bits (works on Node 19+, modern browsers in secure
+ * contexts, Deno, Bun, Cloudflare Workers, Vercel Edge, and any runtime that
+ * implements Web Crypto). A B-tree index on the eventId column stays
+ * clustered. The id is no ordering authority: ids from several processes
+ * interleave within one millisecond, and clock skew can invert them. Order
+ * events by aggregate version or stream position. Supply another generator
+ * to {@link createDomainEventFactory} to
+ * use ULID, KSUID, or another collision-safe format without mutating module
+ * state.
  */
 type EventIdFactory = () => string;
 /**
@@ -266,8 +267,8 @@ 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`. Convenience constructors default to
-   * `crypto.randomUUID()`; strict construction requires the caller to supply it.
+   * `metadata.causationId`. Convenience constructors default to a UUID v7;
+   * strict construction requires the caller to supply it.
    */
   readonly eventId: string;
   /**
@@ -291,7 +292,7 @@ interface DomainEvent<T extends string, P = void> {
    */
   readonly payload: P;
   /**
-   * Timestamp when the accepted fact was recorded by the application shell.
+   * Timestamp when the application shell stamped the accepted fact.
    * Put business-relevant time in the payload under a domain name.
    */
   readonly occurredAt: Date;
@@ -355,7 +356,7 @@ 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()`.
+   * factory generate a UUID v7.
    */
   eventId?: string;
   /**
@@ -402,7 +403,7 @@ interface CreateDomainEventStampOptions {
 }
 /** Dependencies captured by one immutable domain-event factory instance. */
 interface DomainEventFactoryOptions {
-  /** Event-id generator. Defaults to Web Crypto `crypto.randomUUID()`. */
+  /** Event-id generator. Defaults to a UUID v7 from Web Crypto random bits. */
   readonly eventIdFactory?: EventIdFactory;
   /** Event-recording clock. Defaults to `() => new Date()`. */
   readonly clock?: ClockFactory;
@@ -442,7 +443,7 @@ interface DomainEventFactory {
  * The supplied functions are read once and captured by value. The returned
  * object is frozen, so another request, test, or library cannot replace its
  * policy. Its {@link DomainEventFactory.createStamp} method is the
- * application-shell bridge that records an accepted aggregate decision.
+ * application-shell bridge that stamps an accepted aggregate decision.
  * Passing the factory through `AggregateConfig`
  * enables the explicitly named convenience methods, whose defaults read time
  * and randomness.
@@ -453,8 +454,7 @@ interface DomainEventFactory {
  *   eventIdFactory: () => uuidv7(),
  *   clock: () => new Date(),
  * });
- * order.confirm();
- * stampPendingEvents(order, domainEvents);
+ * const uow = new UnitOfWork({ ...deps, eventStampFactory: domainEvents });
  * ```
  */
 declare function createDomainEventFactory(options?: DomainEventFactoryOptions): DomainEventFactory;
@@ -937,7 +937,7 @@ type Id<Tag extends string> = string & {
  * 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,
+ * UUIDv7 (the default for events), `crypto.randomUUID()` (UUIDv4), ULID,
  * 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
@@ -1396,6 +1396,43 @@ interface TransactionScope<TCtx> {
   transactional<T>(fn: (ctx: TCtx) => Promise<T>, options?: TransactionalOptions): Promise<T>;
 }
 //#endregion
+//#region src/application/unit-of-work/stamp-pending-events.d.ts
+/** Minimal shell role accepted by {@link stampPendingEvents}. */
+type DomainEventStampFactory = Pick<DomainEventFactory, "createStamp">;
+/** Per-decision stamp provider for metadata that depends on the event. */
+type DomainEventStampProvider<TEvent extends AnyDomainEvent> = (event: UnstampedDomainEventOf<TEvent>, index: number) => DomainEventStamp;
+/**
+ * Stamp options that every decision of one stamping shares: a stamp time
+ * and metadata such as the correlation id of the request. An `eventId` is per
+ * fact, so the factory creates it for each decision.
+ */
+type SharedDomainEventStampOptions = Omit<CreateDomainEventStampOptions, "eventId">;
+/**
+ * Stamps every still-unstamped event accepted by an aggregate.
+ *
+ * The commit stamps every still-unstamped event when it registers the
+ * aggregate, so a use case does not need this function. Call it first when
+ * the metadata depends on the concrete decision, for an import, or for a test
+ * that needs fixed ids. The commit keeps the stamps that this function set.
+ *
+ * The function is a command that also returns the stamped batch, a
+ * deliberate exception to command-query separation: the caller hands the
+ * batch on to persistence and needs no second read of `pendingEvents`.
+ *
+ * Stamping is atomic with respect to the aggregate's pending list: if stamp
+ * creation or validation fails, every decision remains unstamped. A
+ * successful second call returns the same event objects and does not read the
+ * factory again, so an instance that a retried attempt registers again keeps
+ * its event identities.
+ *
+ * Pass a `DomainEventFactory` (only its `createStamp` role is required) for one
+ * uniform stamping policy. Add `stampOptions` for metadata that every
+ * decision of the batch shares, such as the correlation id of the request.
+ * Pass a callback instead when metadata depends on the concrete decision.
+ */
+declare function stampPendingEvents<TId extends Id<string>, TEvent extends AnyDomainEvent>(aggregate: Aggregate<TId, TEvent>, factory: DomainEventStampFactory, stampOptions?: SharedDomainEventStampOptions): ReadonlyArray<TEvent>;
+declare function stampPendingEvents<TId extends Id<string>, TEvent extends AnyDomainEvent>(aggregate: Aggregate<TId, TEvent>, createStamp: DomainEventStampProvider<TEvent>): ReadonlyArray<TEvent>;
+//#endregion
 //#region src/application/cqrs/handler.d.ts
 /** Dependencies for {@link withCommit}. */
 interface WithCommitDeps<Evt extends AnyDomainEvent, TCtx> {
@@ -1459,6 +1496,19 @@ interface WithCommitDeps<Evt extends AnyDomainEvent, TCtx> {
    * unless the scope honors the signal.
    */
   signal?: AbortSignal;
+  /**
+   * Stamps every pending event that is still unstamped when its aggregate is
+   * registered: the event id, the stamp time, and the metadata. Defaults to
+   * `createDomainEventFactory()`, a UUID v7 from Web Crypto random bits and
+   * the system clock. An event that is already stamped, for example by an
+   * explicit `stampPendingEvents` call, keeps its stamp.
+   */
+  eventStampFactory?: DomainEventStampFactory;
+  /**
+   * Stamp options that every event stamped in this commit shares, for
+   * example the correlation id of the request.
+   */
+  stampOptions?: SharedDomainEventStampOptions;
 }
 declare const aggregateCommitTokenBrand: unique symbol;
 /**
@@ -2667,6 +2717,10 @@ interface EventStore<Evt extends AnyDomainEvent> extends EventStreamReader<Evt>
    *     proves the duplicate/gap rejection. The repository then calls
    *     `replayHistory`, whose replay guard rejects any event carrying an
    *     aggregate type or id that contradicts this stream key.
+   *  7. **Stamped events only:** reject an event without an `eventId` with
+   *     a `TypeError`, before any write. A direct `withCommit` callback can
+   *     append before its registration stamps the events; this check makes
+   *     that mistake fail instead of storing ids that the outbox never sees.
    *
    * An empty `events` array is a no-op; implementations resolve without
    * touching the store (an ES repository skips `append` for aggregates
@@ -2825,5 +2879,5 @@ interface SnapshotStore<TState = unknown> {
   delete(identity: AggregateIdentity): Promise<void>;
 }
 //#endregion
-export { Version as $, IdempotentCommitRequest as A, DomainEventFactoryOptions as At, CommitRegistrationOptions as B, createStampedDomainEvent as Bt, IdempotencyClaim as C, AnyUnstampedDomainEvent as Ct, IdempotencyReconciliation as D, CreateUnstampedDomainEventOptions as Dt, IdempotencyOperationErrorContext as E, CreateStampedDomainEventOptions as Et, DeadLetterDeadline as F, UnstampedDomainEvent as Ft, TransactionalOptions as G, Command as Gt, WithCommitWorkResult as H, mergeMetadata as Ht, DeadlineStore as I, UnstampedDomainEventOf as It, OnceOptions as J, JsonObject as Jt, EventBus as K, CommandHandler as Kt, DueDeadline as L, copyMetadata as Lt, IdempotentExecution as M, EventIdFactory as Mt, WithIdempotentCommitDeps as N, EventMetadata as Nt, IdempotencyReconciliationDecision as O, DomainEvent as Ot, withIdempotentCommit as P, PendingDomainEvent as Pt, ReplayableAggregate as Q, AggregateCommitToken as R, createDomainEvent as Rt, isPositionAfter as S, AnyDomainEvent as St, IdempotencyLease as T, CreateDomainEventStampOptions as Tt, withCommit as U, ClockFactory as Ut, WithCommitDeps as V, defaultDomainEventFactory as Vt, TransactionScope as W, AggregateIdentity as Wt, Aggregate as X, JsonValue as Xt, PublishOptions as Y, JsonPrimitive as Yt, AggregateSnapshot as Z, IdentityMap as _, ExecutionContext as _t, EventStoreAppendOptions as a, CommandMessageContent as at, ProjectionCheckpointStore as b, EventCommitCandidate as bt, StreamReadResult as c, CommandOutboxMapper as ct, RepositoryTracking as d, routeEventsToCommandOutbox as dt, sameVersion as et, UnitOfWorkIdentityMap as f, DeadLetterRecord as ft, AggregateClass as g, OutboxWriter as gt, PersistenceModel as h, OutboxRecord as ht, EventStore as i, CommandCommitOriginCandidate as it, IdempotentCommitResult as j, DomainEventStamp as jt, IdempotencyStore as k, DomainEventFactory as kt, AggregatePersistenceWrite as l, CommandOutboxWriter as lt, PersistenceLifecycle as m, Outbox as mt, ReplayableStreamPages as n, Id as nt, EventStreamReader as o, CommandMessageRelationships as ot, PersistenceChanges as p, DispatchTrackingOutbox as pt, EventHandler as q, PublishedCommand as qt, reconstituteAggregateFromStreamPages as r, IdGenerator as rt, ReadStreamOptions as s, CommandOutboxCommitCandidate as st, SnapshotStore as t, toVersion as tt, AggregateWriteIntent as u, DurableCommandMessage as ut, Projection as v, CommitPosition as vt, IdempotencyClaimHandle as w, CreateDomainEventOptions as wt, ProjectionPosition as x, EventCommitCandidatePosition as xt, ProjectionCheckpoint as y, CommittedDomainEvent as yt, CommitRegistration as z, createDomainEventFactory as zt };
+export { PublishOptions as $, JsonPrimitive as $t, IdempotentCommitRequest as A, CreateStampedDomainEventOptions as At, CommitRegistrationOptions as B, UnstampedDomainEventOf as Bt, IdempotencyClaim as C, CommittedDomainEvent as Ct, IdempotencyReconciliation as D, AnyUnstampedDomainEvent as Dt, IdempotencyOperationErrorContext as E, AnyDomainEvent as Et, DeadLetterDeadline as F, DomainEventStamp as Ft, DomainEventStampProvider as G, defaultDomainEventFactory as Gt, WithCommitWorkResult as H, createDomainEvent as Ht, DeadlineStore as I, EventIdFactory as It, TransactionScope as J, AggregateIdentity as Jt, SharedDomainEventStampOptions as K, mergeMetadata as Kt, DueDeadline as L, EventMetadata as Lt, IdempotentExecution as M, DomainEvent as Mt, WithIdempotentCommitDeps as N, DomainEventFactory as Nt, IdempotencyReconciliationDecision as O, CreateDomainEventOptions as Ot, withIdempotentCommit as P, DomainEventFactoryOptions as Pt, OnceOptions as Q, JsonObject as Qt, AggregateCommitToken as R, PendingDomainEvent as Rt, isPositionAfter as S, CommitPosition as St, IdempotencyLease as T, EventCommitCandidatePosition as Tt, withCommit as U, createDomainEventFactory as Ut, WithCommitDeps as V, copyMetadata as Vt, DomainEventStampFactory as W, createStampedDomainEvent as Wt, EventBus as X, CommandHandler as Xt, TransactionalOptions as Y, Command as Yt, EventHandler as Z, PublishedCommand as Zt, IdentityMap as _, DispatchTrackingOutbox as _t, EventStoreAppendOptions as a, toVersion as at, ProjectionCheckpointStore as b, OutboxWriter as bt, StreamReadResult as c, CommandCommitOriginCandidate as ct, RepositoryTracking as d, CommandOutboxCommitCandidate as dt, JsonValue as en, Aggregate as et, UnitOfWorkIdentityMap as f, CommandOutboxMapper as ft, AggregateClass as g, DeadLetterRecord as gt, PersistenceModel as h, routeEventsToCommandOutbox as ht, EventStore as i, sameVersion as it, IdempotentCommitResult as j, CreateUnstampedDomainEventOptions as jt, IdempotencyStore as k, CreateDomainEventStampOptions as kt, AggregatePersistenceWrite as l, CommandMessageContent as lt, PersistenceLifecycle as m, DurableCommandMessage as mt, ReplayableStreamPages as n, ReplayableAggregate as nt, EventStreamReader as o, Id as ot, PersistenceChanges as p, CommandOutboxWriter as pt, stampPendingEvents as q, ClockFactory as qt, reconstituteAggregateFromStreamPages as r, Version as rt, ReadStreamOptions as s, IdGenerator as st, SnapshotStore as t, AggregateSnapshot as tt, AggregateWriteIntent as u, CommandMessageRelationships as ut, Projection as v, Outbox as vt, IdempotencyClaimHandle as w, EventCommitCandidate as wt, ProjectionPosition as x, ExecutionContext as xt, ProjectionCheckpoint as y, OutboxRecord as yt, CommitRegistration as z, UnstampedDomainEvent as zt };
 //# sourceMappingURL=snapshot-store.d.ts.map

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { $ as PendingEventLimitExceededErrorOptions, A as IdempotencyInFlightErrorOptions, B as InvalidEventStreamPageErrorOptions, C as FoldReturnedNoStateError, Ct as UnreplayableAggregateError, D as IdempotencyClaimLostErrorOptions, Dt as isWiringErrorLike, E as IdempotencyClaimLostError, Et as isInfrastructureErrorLike, F as InMemoryCapacityExceededError, G as KitWiringError, H as InvalidVersionError, I as InMemoryCapacityExceededErrorOptions, J as MissingFoldError, K as MisattributedEventError, L as InfrastructureError, M as IdempotencyKeyReuseErrorOptions, N as IdempotencyReconciliationRequiredError, O as IdempotencyCompletionWithoutClaimError, P as IdempotencyReconciliationRequiredErrorOptions, Q as PendingEventLimitExceededError, R as InvalidCommandMessageError, S as EventStreamPageReason, St as UnregisteredHandlerErrorOptions, T as HandBuiltEventError, Tt as isDomainErrorLike, U as KitErrorCode, V as InvalidIntegrationMessageError, W as KitErrorOptions, X as PendingEventBatchMismatchError, Y as MissingHandlerError, Z as PendingEventBatchMismatchErrorOptions, _ as DuplicateHandlerRegistrationError, _t as UnmanagedInstanceError, a as AggregateNotFoundErrorOptions, at as ReentrantEventRecordingError, b as ErrorMapperFailedErrorOptions, bt as UnregisteredChangesErrorOptions, c as ConcurrencyConflictErrorOptions, ct as ReplayRejectedErrorOptions, d as DirectStateMutationErrorOptions, dt as ReplayTargetMismatchReason, et as ProjectionGapError, f as DomainError, ft as SnapshotCorruptedError, g as DuplicateEventIdErrorOptions, gt as SnapshotVersionNotRestoredErrorOptions, h as DuplicateEventIdError, ht as SnapshotVersionNotRestoredError, i as AggregateNotFoundError, it as PrototypePollutionError, j as IdempotencyKeyReuseError, k as IdempotencyInFlightError, l as ConcurrencyConflictReason, lt as ReplayTargetMismatchError, m as DuplicateAggregateErrorOptions, mt as SnapshotSchemaMismatchErrorOptions, n as AggregateDeletedErrorOptions, nt as ProjectionOrderViolationError, o as CapabilityRegistryConflictError, ot as ReentrantEventRecordingErrorOptions, p as DuplicateAggregateError, pt as SnapshotSchemaMismatchError, q as MissingEntityIdError, r as AggregateIdentityMismatchOptions, rt as ProjectionReceiptViolationError, s as ConcurrencyConflictError, st as ReplayRejectedError, t as AggregateDeletedError, tt as ProjectionIdentityViolationError, u as DirectStateMutationError, ut as ReplayTargetMismatchErrorOptions, v as DuplicateHandlerRegistrationErrorOptions, vt as UnprojectableEventError, w as ForeignEventError, wt as UnreplayableAggregateErrorOptions, x as EventCollectionError, xt as UnregisteredHandlerError, y as ErrorMapperFailedError, yt as UnregisteredChangesError, z as InvalidEventStreamPageError } from "./chunks/kit-errors.js";
-import { $ as Version, A as IdempotentCommitRequest, At as DomainEventFactoryOptions, B as CommitRegistrationOptions, Bt as createStampedDomainEvent, C as IdempotencyClaim, Ct as AnyUnstampedDomainEvent, D as IdempotencyReconciliation, Dt as CreateUnstampedDomainEventOptions, E as IdempotencyOperationErrorContext, Et as CreateStampedDomainEventOptions, F as DeadLetterDeadline, Ft as UnstampedDomainEvent, G as TransactionalOptions, Gt as Command, H as WithCommitWorkResult, Ht as mergeMetadata, I as DeadlineStore, It as UnstampedDomainEventOf, J as OnceOptions, Jt as JsonObject, K as EventBus, Kt as CommandHandler, L as DueDeadline, Lt as copyMetadata, M as IdempotentExecution, Mt as EventIdFactory, N as WithIdempotentCommitDeps, Nt as EventMetadata, O as IdempotencyReconciliationDecision, Ot as DomainEvent, P as withIdempotentCommit, Pt as PendingDomainEvent, Q as ReplayableAggregate, R as AggregateCommitToken, Rt as createDomainEvent, S as isPositionAfter, St as AnyDomainEvent, T as IdempotencyLease, Tt as CreateDomainEventStampOptions, U as withCommit, Ut as ClockFactory, V as WithCommitDeps, Vt as defaultDomainEventFactory, W as TransactionScope, Wt as AggregateIdentity, X as Aggregate, Xt as JsonValue, Y as PublishOptions, Yt as JsonPrimitive, Z as AggregateSnapshot, _ as IdentityMap, _t as ExecutionContext, a as EventStoreAppendOptions, at as CommandMessageContent, b as ProjectionCheckpointStore, bt as EventCommitCandidate, c as StreamReadResult, ct as CommandOutboxMapper, d as RepositoryTracking, dt as routeEventsToCommandOutbox, et as sameVersion, f as UnitOfWorkIdentityMap, ft as DeadLetterRecord, g as AggregateClass, gt as OutboxWriter, h as PersistenceModel, ht as OutboxRecord, i as EventStore, it as CommandCommitOriginCandidate, j as IdempotentCommitResult, jt as DomainEventStamp, k as IdempotencyStore, kt as DomainEventFactory, l as AggregatePersistenceWrite, lt as CommandOutboxWriter, m as PersistenceLifecycle, mt as Outbox, n as ReplayableStreamPages, nt as Id, o as EventStreamReader, ot as CommandMessageRelationships, p as PersistenceChanges, pt as DispatchTrackingOutbox, q as EventHandler, qt as PublishedCommand, r as reconstituteAggregateFromStreamPages, rt as IdGenerator, s as ReadStreamOptions, st as CommandOutboxCommitCandidate, t as SnapshotStore, tt as toVersion, u as AggregateWriteIntent, ut as DurableCommandMessage, v as Projection, vt as CommitPosition, w as IdempotencyClaimHandle, wt as CreateDomainEventOptions, x as ProjectionPosition, xt as EventCommitCandidatePosition, y as ProjectionCheckpoint, yt as CommittedDomainEvent, z as CommitRegistration, zt as createDomainEventFactory } from "./chunks/snapshot-store.js";
+import { $ as PublishOptions, $t as JsonPrimitive, A as IdempotentCommitRequest, At as CreateStampedDomainEventOptions, B as CommitRegistrationOptions, Bt as UnstampedDomainEventOf, C as IdempotencyClaim, Ct as CommittedDomainEvent, D as IdempotencyReconciliation, Dt as AnyUnstampedDomainEvent, E as IdempotencyOperationErrorContext, Et as AnyDomainEvent, F as DeadLetterDeadline, Ft as DomainEventStamp, G as DomainEventStampProvider, Gt as defaultDomainEventFactory, H as WithCommitWorkResult, Ht as createDomainEvent, I as DeadlineStore, It as EventIdFactory, J as TransactionScope, Jt as AggregateIdentity, K as SharedDomainEventStampOptions, Kt as mergeMetadata, L as DueDeadline, Lt as EventMetadata, M as IdempotentExecution, Mt as DomainEvent, N as WithIdempotentCommitDeps, Nt as DomainEventFactory, O as IdempotencyReconciliationDecision, Ot as CreateDomainEventOptions, P as withIdempotentCommit, Pt as DomainEventFactoryOptions, Q as OnceOptions, Qt as JsonObject, R as AggregateCommitToken, Rt as PendingDomainEvent, S as isPositionAfter, St as CommitPosition, T as IdempotencyLease, Tt as EventCommitCandidatePosition, U as withCommit, Ut as createDomainEventFactory, V as WithCommitDeps, Vt as copyMetadata, W as DomainEventStampFactory, Wt as createStampedDomainEvent, X as EventBus, Xt as CommandHandler, Y as TransactionalOptions, Yt as Command, Z as EventHandler, Zt as PublishedCommand, _ as IdentityMap, _t as DispatchTrackingOutbox, a as EventStoreAppendOptions, at as toVersion, b as ProjectionCheckpointStore, bt as OutboxWriter, c as StreamReadResult, ct as CommandCommitOriginCandidate, d as RepositoryTracking, dt as CommandOutboxCommitCandidate, en as JsonValue, et as Aggregate, f as UnitOfWorkIdentityMap, ft as CommandOutboxMapper, g as AggregateClass, gt as DeadLetterRecord, h as PersistenceModel, ht as routeEventsToCommandOutbox, i as EventStore, it as sameVersion, j as IdempotentCommitResult, jt as CreateUnstampedDomainEventOptions, k as IdempotencyStore, kt as CreateDomainEventStampOptions, l as AggregatePersistenceWrite, lt as CommandMessageContent, m as PersistenceLifecycle, mt as DurableCommandMessage, n as ReplayableStreamPages, nt as ReplayableAggregate, o as EventStreamReader, ot as Id, p as PersistenceChanges, pt as CommandOutboxWriter, q as stampPendingEvents, qt as ClockFactory, r as reconstituteAggregateFromStreamPages, rt as Version, s as ReadStreamOptions, st as IdGenerator, t as SnapshotStore, tt as AggregateSnapshot, u as AggregateWriteIntent, ut as CommandMessageRelationships, v as Projection, vt as Outbox, w as IdempotencyClaimHandle, wt as EventCommitCandidate, x as ProjectionPosition, xt as ExecutionContext, y as ProjectionCheckpoint, yt as OutboxRecord, z as CommitRegistration, zt as UnstampedDomainEvent } from "./chunks/snapshot-store.js";
 import { Result } from "@shirudo/result";
 import { ValidationError } from "@shirudo/base-error";
 //#region src/application/cqrs/internal/bus-internals.d.ts
@@ -1563,37 +1563,6 @@ declare class RollbackError extends InfrastructureError<"ROLLBACK_FAILED"> {
   constructor(cause: unknown, rollbackCause: unknown);
 }
 //#endregion
-//#region src/application/unit-of-work/stamp-pending-events.d.ts
-/** Minimal shell role accepted by {@link stampPendingEvents}. */
-type DomainEventStampFactory = Pick<DomainEventFactory, "createStamp">;
-/** Per-decision stamp provider for metadata that depends on the event. */
-type DomainEventStampProvider<TEvent extends AnyDomainEvent> = (event: UnstampedDomainEventOf<TEvent>, index: number) => DomainEventStamp;
-/**
- * Stamp options that every decision of one stamping shares: a stamp time
- * and metadata such as the correlation id of the request. An `eventId` is per
- * fact, so the factory creates it for each decision.
- */
-type SharedDomainEventStampOptions = Omit<CreateDomainEventStampOptions, "eventId">;
-/**
- * Records every still-unstamped event accepted by an aggregate.
- *
- * The function is a command that also returns the recorded batch, a
- * deliberate exception to command-query separation: the caller hands the
- * batch on to persistence and needs no second read of `pendingEvents`.
- *
- * Recording is atomic with respect to the aggregate's pending list: if stamp
- * creation or validation fails, every decision remains unstamped. A
- * successful second call returns the same event objects and does not read the
- * factory again, which keeps event identity stable across transaction retries.
- *
- * Pass a `DomainEventFactory` (only its `createStamp` role is required) for one
- * uniform stamping policy. Add `stampOptions` for metadata that every
- * decision of the batch shares, such as the correlation id of the request.
- * Pass a callback instead when metadata depends on the concrete decision.
- */
-declare function stampPendingEvents<TId extends Id<string>, TEvent extends AnyDomainEvent>(aggregate: Aggregate<TId, TEvent>, factory: DomainEventStampFactory, stampOptions?: SharedDomainEventStampOptions): ReadonlyArray<TEvent>;
-declare function stampPendingEvents<TId extends Id<string>, TEvent extends AnyDomainEvent>(aggregate: Aggregate<TId, TEvent>, createStamp: DomainEventStampProvider<TEvent>): ReadonlyArray<TEvent>;
-//#endregion
 //#region src/application/unit-of-work/unit-of-work.d.ts
 /**
  * What the application work callback receives: repositories already bound to
@@ -1624,6 +1593,11 @@ interface RunOptions {
    * `TransactionScope`. Use `AbortSignal.timeout(ms)` for a deadline.
    */
   readonly signal?: AbortSignal;
+  /**
+   * Stamp options that every event stamped in this run shares, for example
+   * the correlation id of the request.
+   */
+  readonly stampOptions?: SharedDomainEventStampOptions;
 }
 declare const repositoryDefinitionBrand: unique symbol;
 /** Adapter wiring accepted by {@link defineRepository}. */
@@ -1832,6 +1806,12 @@ interface UnitOfWorkDeps<Evt extends AnyDomainEvent, TCtx, TDefinitions extends
    * application phase. Default `30000`ms.
    */
   postCommitTimeoutMs?: number;
+  /**
+   * See `withCommit`: stamps every pending event that is still unstamped
+   * when `add`, `update`, or `remove` registers its aggregate. Defaults to
+   * `createDomainEventFactory()`.
+   */
+  eventStampFactory?: DomainEventStampFactory;
   repositories: CompatibleRepositoryDefinitions<Evt, TCtx, TDefinitions>;
 }
 /**
@@ -2388,8 +2368,8 @@ interface AggregateConfig<TState = unknown> extends EntityConfig<TState> {
  * tracking, the kit-internal post-commit acknowledgement capability,
  * the `markReconstituted` post-load marker, and the `createEvent` helper
  * that auto-injects `aggregateId` + `aggregateType` on every event the
- * aggregate emits. The application shell stamps the pending decisions
- * with `stampPendingEvents` before persistence.
+ * aggregate emits. The commit stamps the pending decisions when it
+ * registers the aggregate, before persistence.
  *
  * Consumers do NOT extend this class directly; extend
  * `StateStoredAggregate` for state-stored aggregates or
@@ -2599,8 +2579,8 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
    * Creates the immutable business fact accepted by this aggregate without
    * reading a clock, generating an id, or attaching tracing metadata.
    *
-   * The application shell stamps pending events after the domain operation
-   * and before persistence. Payload schema version stays here, next to the
+   * The commit stamps pending events when it registers the aggregate,
+   * before persistence. Payload schema version stays here, next to the
    * concrete event producer, rather than in shell-owned stamp data.
    */
   protected createEvent<E extends TEvent>(type: E["type"], payload: E["payload"], options?: Omit<CreateUnstampedDomainEventOptions, "aggregateId" | "aggregateType">): UnstampedDomainEventOf<E>;

package/dist/index.js

@@ -404,6 +404,42 @@ function captureObserverFunctions(context, observers, required) {
 	return Object.freeze(captured);
 }
 
+//#endregion
+//#region src/domain/aggregate/pending-event-recording.ts
+const { registry: capabilities$1, require } = createGlobalCapabilityRegistry(Symbol.for("@shirudo/ddd-kit/pending-event-recording-registry/v2"));
+/** Resolves the recording capability or throws `UnmanagedInstanceError`. */
+function requirePendingEventRecordingCapability(aggregate, operation) {
+	return require(aggregate, operation, "aggregate");
+}
+function registerPendingEventRecordingCapability(aggregate, capability) {
+	capabilities$1.set(aggregate, Object.freeze(capability));
+}
+
+//#endregion
+//#region src/application/unit-of-work/stamp-pending-events.ts
+function stampPendingEvents(aggregate, source, stampOptions) {
+	return recordWith(requirePendingEventRecordingCapability(aggregate, "stampPendingEvents"), source, stampOptions);
+}
+/**
+* Stamps the pending events that are still unstamped when the commit
+* registers an aggregate. An aggregate whose pending events all carry a
+* stamp stays untouched: an explicit {@link stampPendingEvents} call keeps
+* its stamps, and an instance without the recording capability passes when
+* it has nothing to stamp.
+*/
+function stampAtRegistration(aggregate, factory, stampOptions, operation) {
+	if (aggregate.pendingEvents.every(isStampedDomainEvent)) return;
+	recordWith(requirePendingEventRecordingCapability(aggregate, operation), factory, stampOptions);
+}
+function recordWith(capability, source, stampOptions) {
+	const shared = {
+		occurredAt: stampOptions?.occurredAt,
+		metadata: stampOptions?.metadata
+	};
+	const createStamp = typeof source === "function" ? source : () => source.createStamp(shared);
+	return capability.record((event, index) => createStamp(event, index));
+}
+
 //#endregion
 //#region src/application/cqrs/handler.ts
 /**
@@ -417,7 +453,7 @@ function registrationDiverged(record) {
 	return record.aggregate.version !== record.version || pending.length !== record.events.length || record.events.some((event, index) => event !== pending[index]);
 }
 /** One token registry per transactional callback attempt. */
-function createCommitTokenScope() {
+function createCommitTokenScope(stamp) {
 	const recordsByToken = /* @__PURE__ */ new WeakMap();
 	const tokensByAggregate = /* @__PURE__ */ new WeakMap();
 	let issuedTokenCount = 0;
@@ -436,8 +472,8 @@ function createCommitTokenScope() {
 		}
 		const eventLifecycle = requirePendingEventLifecycleCapability(aggregate, "withCommit registration");
 		const token = Object.freeze(Object.create(null));
+		stamp(aggregate, "withCommit registration");
 		const events = aggregate.pendingEvents;
-		for (const event of events) if (!isStampedDomainEvent(event)) throw new EventCollectionError(`withCommit: event "${event.type}" has not been stamped. Call stampPendingEvents(aggregate, createStamp) in the application shell before persistence or outbox collection.`, event.type);
 		const persistedVersion = eventLifecycle.persistedVersion();
 		tokensByAggregate.set(aggregate, token);
 		recordsByToken.set(token, {
@@ -609,17 +645,21 @@ async function withCommit(deps, fn) {
 }
 /**
 * {@link withCommit} with a check per attempt before the commit. The scope
-* receives `onAttemptStart` in its transactional options.
+* receives `onAttemptStart` in its transactional options. The callback also
+* receives the stamping step of the registration, so that a caller that
+* records the batch before it registers can stamp first.
 */
 async function withCheckedCommit(deps, fn, onAttemptStart) {
 	const postCommitTimeoutMs = deps.postCommitTimeoutMs ?? 3e4;
 	assertTimerDelay("withCommit", "postCommitTimeoutMs", postCommitTimeoutMs);
 	if (deps.signal?.aborted) throw abortReason(deps.signal, "withCommit aborted before opening a transaction");
+	const eventStampFactory = deps.eventStampFactory ?? defaultDomainEventFactory;
+	const stamp = (aggregate, operation) => stampAtRegistration(aggregate, eventStampFactory, deps.stampOptions, operation);
 	const { result, commitRecords, events } = await deps.scope.transactional(async (ctx) => {
-		const tokenScope = createCommitTokenScope();
+		const tokenScope = createCommitTokenScope(stamp);
 		let fnResult;
 		try {
-			fnResult = await fn(ctx, tokenScope.registration);
+			fnResult = await fn(ctx, tokenScope.registration, stamp);
 		} finally {
 			tokenScope.close();
 		}
@@ -631,24 +671,22 @@ async function withCheckedCommit(deps, fn, onAttemptStart) {
 				const registeredId = registered.aggregateId;
 				const registeredType = registered.aggregateType;
 				return record.events.map((event, index) => {
-					if (!isStampedDomainEvent(event)) throw new EventCollectionError(`withCommit: event "${event.type}" has not been stamped. Call stampPendingEvents(aggregate, createStamp) in the application shell before persistence or outbox collection.`, event.type);
-					const recordedEvent = event;
 					const commitSize = record.events.length;
-					const aggregateId = recordedEvent.aggregateId;
-					const aggregateType = recordedEvent.aggregateType;
+					const aggregateId = event.aggregateId;
+					const aggregateType = event.aggregateType;
 					const missing = [];
 					if (!aggregateId) missing.push("aggregateId");
 					if (!aggregateType) missing.push("aggregateType");
-					if (!aggregateId || !aggregateType) throw new EventCollectionError(`withCommit: event "${recordedEvent.type}" is missing ${missing.join(" and ")}. Use this.createEvent(type, payload) inside aggregate methods instead of createDomainEvent(...); createEvent auto-injects aggregateId and aggregateType. Outbox dispatchers and projection handlers rely on the envelope source.`, recordedEvent.type);
-					if (aggregateId !== registeredId || aggregateType !== registeredType) throw new EventCollectionError(`withCommit: event "${recordedEvent.type}" belongs to ${describeAggregateIdentity({
+					if (!aggregateId || !aggregateType) throw new EventCollectionError(`withCommit: event "${event.type}" is missing ${missing.join(" and ")}. Use this.createEvent(type, payload) inside aggregate methods instead of createDomainEvent(...); createEvent auto-injects aggregateId and aggregateType. Outbox dispatchers and projection handlers rely on the envelope source.`, event.type);
+					if (aggregateId !== registeredId || aggregateType !== registeredType) throw new EventCollectionError(`withCommit: event "${event.type}" belongs to ${describeAggregateIdentity({
 						aggregateType,
 						aggregateId
 					})} but was registered under ${describeAggregateIdentity({
 						aggregateType: registeredType,
 						aggregateId: registeredId
-					})}. The aggregate base classes attribute every event to the aggregate on every recording path; an instance from another package copy must stamp it the same way.`, recordedEvent.type);
+					})}. The aggregate base classes attribute every event to the aggregate on every recording path; an instance from another package copy must stamp it the same way.`, event.type);
 					return Object.freeze({
-						event: recordedEvent,
+						event,
 						source: Object.freeze({
 							aggregateId,
 							aggregateType
@@ -2599,29 +2637,6 @@ function wiringErrorInCauseChain(error) {
 	return findInCauseChain(error, (link) => isWiringErrorLike(link) ? link : void 0);
 }
 
-//#endregion
-//#region src/domain/aggregate/pending-event-recording.ts
-const { registry: capabilities$1, require } = createGlobalCapabilityRegistry(Symbol.for("@shirudo/ddd-kit/pending-event-recording-registry/v2"));
-/** Resolves the recording capability or throws `UnmanagedInstanceError`. */
-function requirePendingEventRecordingCapability(aggregate, operation) {
-	return require(aggregate, operation, "aggregate");
-}
-function registerPendingEventRecordingCapability(aggregate, capability) {
-	capabilities$1.set(aggregate, Object.freeze(capability));
-}
-
-//#endregion
-//#region src/application/unit-of-work/stamp-pending-events.ts
-function stampPendingEvents(aggregate, source, stampOptions) {
-	const capability = requirePendingEventRecordingCapability(aggregate, "stampPendingEvents");
-	const shared = {
-		occurredAt: stampOptions?.occurredAt,
-		metadata: stampOptions?.metadata
-	};
-	const createStamp = typeof source === "function" ? source : () => source.createStamp(shared);
-	return capability.record((event, index) => createStamp(event, index));
-}
-
 //#endregion
 //#region src/application/unit-of-work/repository-facade.ts
 /**
@@ -3078,6 +3093,7 @@ function capabilityFor(baseline, operation) {
 */
 var Session = class {
 	commitRegistration;
+	stamp;
 	_registeredWrites = [];
 	_commitTokens = /* @__PURE__ */ new Set();
 	_identityMap = new IdentityMap();
@@ -3100,8 +3116,9 @@ var Session = class {
 	*/
 	_lateRegistrationsFailAttempt = false;
 	_registrationDuringFlush;
-	constructor(commitRegistration) {
+	constructor(commitRegistration, stamp) {
 		this.commitRegistration = commitRegistration;
+		this.stamp = stamp;
 	}
 	get identityMap() {
 		this.assertOpen("tracking.identityMap");
@@ -3224,6 +3241,7 @@ var Session = class {
 	}
 	/** Registers persistence intent and commit registration as one operation. */
 	registerWrite(entry, intent, definition) {
+		if (entry.registration === void 0) this.stamp(entry.aggregate, `repository.${intent}`);
 		const newlyRegistered = this.registerIntent(entry, intent);
 		try {
 			if (intent === "remove") this.registerRemovedCommit(entry.aggregate, definition, entry.expectedVersion);
@@ -3622,10 +3640,12 @@ var UnitOfWork = class {
 				onPersisted: this.deps.onPersisted,
 				onPersistError: this.deps.onPersistError,
 				postCommitTimeoutMs: this.deps.postCommitTimeoutMs,
-				signal: options?.signal
-			}, async (tx, registration) => {
+				signal: options?.signal,
+				eventStampFactory: this.deps.eventStampFactory,
+				stampOptions: options?.stampOptions
+			}, async (tx, registration, stamp) => {
 				session?.close();
-				const s = new Session(registration);
+				const s = new Session(registration, stamp);
 				session = s;
 				sessions.push(s);
 				const current = startAttempt();
@@ -4449,8 +4469,8 @@ function entityIds(entities) {
 * tracking, the kit-internal post-commit acknowledgement capability,
 * the `markReconstituted` post-load marker, and the `createEvent` helper
 * that auto-injects `aggregateId` + `aggregateType` on every event the
-* aggregate emits. The application shell stamps the pending decisions
-* with `stampPendingEvents` before persistence.
+* aggregate emits. The commit stamps the pending decisions when it
+* registers the aggregate, before persistence.
 *
 * Consumers do NOT extend this class directly; extend
 * `StateStoredAggregate` for state-stored aggregates or
@@ -4768,8 +4788,8 @@ var BaseAggregate = class extends Entity {
 	* Creates the immutable business fact accepted by this aggregate without
 	* reading a clock, generating an id, or attaching tracing metadata.
 	*
-	* The application shell stamps pending events after the domain operation
-	* and before persistence. Payload schema version stays here, next to the
+	* The commit stamps pending events when it registers the aggregate,
+	* before persistence. Payload schema version stays here, next to the
 	* concrete event producer, rather than in shell-owned stamp data.
 	*/
 	createEvent(type, payload, options) {
@@ -6765,7 +6785,10 @@ var OutboxDispatcher = class extends PollLoop {
 function copyForStorage(event, index, stream) {
 	const subject = `InMemoryEventStore.append (stream ${describeAggregateIdentity(stream)}): events[${index}]`;
 	if (event === null || typeof event !== "object") throw new TypeError(`${subject} is not an event object`);
-	return copyFreezableState(event, subject);
+	const copy = copyFreezableState(event, subject);
+	const eventId = copy.eventId;
+	if (typeof eventId !== "string" || eventId === "") throw new TypeError(`${subject} has no eventId. Stamp the event before the append: the commit stamps it when a write registers its aggregate, and stampPendingEvents stamps it before that.`);
+	return copy;
 }
 function assertStreamPosition(name, value) {
 	if (value !== void 0 && (!Number.isSafeInteger(value) || value < 0)) throw new RangeError(`InMemoryEventStore: ${name} must be a non-negative safe integer, got ${String(value)}`);