@photon-grove/evt 0.0.0-stage → 0.1.0

package/dist/retry.js

@@ -0,0 +1,50 @@
+// Retry policy: how many times a command runs and how long to wait between attempts, with the
+// defaults the compat fixtures pin (outcomes.json, retry).
+import { EvtError } from './errors.js';
+/** Five attempts, waiting from 25 ms up to at most 1 s, as Go and Rust do. */
+export const DEFAULT_RETRY_POLICY = Object.freeze({
+    maxAttempts: 5,
+    baseDelayMs: 25,
+    maxDelayMs: 1000,
+});
+/** Refuses a policy with fewer than one attempt or a delay that isn't a whole, finite number. */
+export function checkRetryPolicy(policy) {
+    const valid = Number.isSafeInteger(policy.maxAttempts) &&
+        policy.maxAttempts >= 1 &&
+        Number.isSafeInteger(policy.baseDelayMs) &&
+        policy.baseDelayMs >= 0 &&
+        Number.isSafeInteger(policy.maxDelayMs) &&
+        policy.maxDelayMs >= 0;
+    if (!valid) {
+        throw new EvtError('invalidArgument', 'a retry policy needs at least one attempt and whole, non-negative delays: ' +
+            `${policy.maxAttempts}, ${policy.baseDelayMs}, ${policy.maxDelayMs}`);
+    }
+}
+/**
+ * The jittered delay in milliseconds before retry `retry` (0 for the first retry). `random`
+ * returns a number in [0, 1), as `Math.random` does.
+ */
+export function retryDelay(policy, retry, random = Math.random) {
+    const ceiling = Math.min(policy.baseDelayMs * 2 ** retry, policy.maxDelayMs);
+    const floor = Math.floor(ceiling / 2);
+    return floor + Math.floor(random() * (ceiling - floor + 1));
+}
+/** Waits `ms` milliseconds, or rejects with the signal's reason when it aborts first. */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', aborted);
+            resolve();
+        }, ms);
+        const aborted = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', aborted, { once: true });
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,2DAA2D;AAE3D,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAA;AAgBpC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAgB,MAAM,CAAC,MAAM,CAAC;IAC7D,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,EAAE;IACf,UAAU,EAAE,IAAI;CACjB,CAAC,CAAA;AAEF,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,CAAC,MAAmB;IAClD,MAAM,KAAK,GACT,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC;QACxC,MAAM,CAAC,WAAW,IAAI,CAAC;QACvB,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC;QACxC,MAAM,CAAC,WAAW,IAAI,CAAC;QACvB,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC;QACvC,MAAM,CAAC,UAAU,IAAI,CAAC,CAAA;IACxB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,QAAQ,CAChB,iBAAiB,EACjB,4EAA4E;YAC1E,GAAG,MAAM,CAAC,WAAW,KAAK,MAAM,CAAC,WAAW,KAAK,MAAM,CAAC,UAAU,EAAE,CACvE,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAmB,EAAE,KAAa,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM;IACjF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,GAAG,CAAC,IAAI,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAA;IAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAA;IAErC,OAAO,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAA;AAC7D,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YACrB,OAAM;QACR,CAAC;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;YAC7C,OAAO,EAAE,CAAA;QACX,CAAC,EAAE,EAAE,CAAC,CAAA;QACN,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACxB,CAAC,CAAA;QACD,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAC,IAAI,EAAE,IAAI,EAAC,CAAC,CAAA;IAC1D,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/snapshots.d.ts

@@ -0,0 +1,21 @@
+import type { SerializedSnapshot } from './event.js';
+/**
+ * The most bytes one action of a commit may carry: 95% of DynamoDB's 400 KB item limit. A commit
+ * with a larger item fails on every backend.
+ */
+export declare const MAX_COMMIT_ITEM_BYTES = 380000;
+/**
+ * Whether a commit takes a snapshot, given the stream's current sequence, the events in the
+ * commit and the snapshot interval: 0 for no snapshot, otherwise the events it folds in, which is
+ * always the whole commit. A commit snapshots when it reaches or crosses the next multiple of the
+ * interval, and an interval of 0 (or less, as in Go) disables snapshots.
+ */
+export declare function snapshotEventsDue(current: bigint, events: number, interval: number): number;
+/**
+ * The bytes the commit budget counts for a snapshot's item, with a `ttl` at its widest whether or
+ * not the entity type is retained. A store leaves out a snapshot over
+ * {@link MAX_COMMIT_ITEM_BYTES}, so an aggregate whose state outgrows the budget doesn't make
+ * every commit that reaches the interval fail.
+ */
+export declare function snapshotCommitSize(snapshot: SerializedSnapshot): number;
+//# sourceMappingURL=snapshots.d.ts.map

package/dist/snapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../src/snapshots.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,YAAY,CAAA;AAGlD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,SAAU,CAAA;AAK5C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU3F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAEvE"}

package/dist/snapshots.js

@@ -0,0 +1,35 @@
+// The snapshot policy and the per-item budget a snapshot must fit, the same on every backend.
+import { snapshotItem, itemSize } from './dynamodb/item.js';
+import { safeIntegerArgument } from './fields.js';
+/**
+ * The most bytes one action of a commit may carry: 95% of DynamoDB's 400 KB item limit. A commit
+ * with a larger item fails on every backend.
+ */
+export const MAX_COMMIT_ITEM_BYTES = 380_000;
+// A ttl attribute at its widest: the name and the 19 digits of the largest int64.
+const WIDEST_TTL = { N: (2n ** 63n - 1n).toString() };
+/**
+ * Whether a commit takes a snapshot, given the stream's current sequence, the events in the
+ * commit and the snapshot interval: 0 for no snapshot, otherwise the events it folds in, which is
+ * always the whole commit. A commit snapshots when it reaches or crosses the next multiple of the
+ * interval, and an interval of 0 (or less, as in Go) disables snapshots.
+ */
+export function snapshotEventsDue(current, events, interval) {
+    safeIntegerArgument(events, 'events');
+    if (safeIntegerArgument(interval, 'interval') <= 0) {
+        return 0;
+    }
+    const divisor = BigInt(interval);
+    const nextSnapshotAt = interval - Number(((current % divisor) + divisor) % divisor);
+    return events < nextSnapshotAt ? 0 : events;
+}
+/**
+ * The bytes the commit budget counts for a snapshot's item, with a `ttl` at its widest whether or
+ * not the entity type is retained. A store leaves out a snapshot over
+ * {@link MAX_COMMIT_ITEM_BYTES}, so an aggregate whose state outgrows the budget doesn't make
+ * every commit that reaches the interval fail.
+ */
+export function snapshotCommitSize(snapshot) {
+    return itemSize({ ...snapshotItem(snapshot), ttl: WIDEST_TTL });
+}
+//# sourceMappingURL=snapshots.js.map

package/dist/snapshots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshots.js","sourceRoot":"","sources":["../src/snapshots.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAE9F,OAAO,EAAC,YAAY,EAAE,QAAQ,EAAC,MAAM,oBAAoB,CAAA;AAEzD,OAAO,EAAC,mBAAmB,EAAC,MAAM,aAAa,CAAA;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAA;AAE5C,kFAAkF;AAClF,MAAM,UAAU,GAAG,EAAC,CAAC,EAAE,CAAC,EAAE,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAC,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,MAAc,EAAE,QAAgB;IACjF,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IACrC,IAAI,mBAAmB,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,CAAA;IACV,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;IAChC,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,CAAA;IAEnF,OAAO,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAA4B;IAC7D,OAAO,QAAQ,CAAC,EAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,UAAU,EAAC,CAAC,CAAA;AAC/D,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,103 @@
+import { type Aggregate, type EventDefinitions, type Rejection } from './aggregate.js';
+import { type SerializedEvent } from './event.js';
+import { type Metadata } from './metadata.js';
+import type { CallOptions, Repository } from './repository.js';
+import { type RetryPolicy } from './retry.js';
+/** The default number of events between snapshots, as in Go and Rust. */
+export declare const DEFAULT_SNAPSHOT_INTERVAL = 5;
+/** How a {@link Store} fills in what commands leave out. */
+export interface StoreOptions {
+    /** The region metadata gets when a command's metadata has none. */
+    region?: string | undefined;
+    /** The clock, in Unix milliseconds, that stamps metadata timestamps. `Date.now` by default. */
+    clock?: (() => number) | undefined;
+    /** The number of events between snapshots (default 5). 0 disables them. */
+    snapshotInterval?: number | undefined;
+    /**
+     * Makes the commit ID of a commit whose metadata has neither a command ID nor a commit ID. ULID
+     * format by default.
+     */
+    commitId?: (() => string) | undefined;
+}
+/** An aggregate loaded from its stream, with the position it was loaded at. */
+export interface Loaded<S> {
+    readonly entityId: string;
+    readonly state: S;
+    /** The sequence of the last event folded into the state, 0 for a new entity. */
+    readonly sequence: bigint;
+    /** The sequence of the snapshot the load started from, or the commit wrote, 0 with none. */
+    readonly snapshotSequence: bigint;
+    /** The command IDs of the events folded in since the snapshot: the dedupe window. */
+    readonly seenCommandIds: ReadonlySet<string>;
+}
+/** Options for {@link Store.execute}. */
+export interface ExecuteOptions extends CallOptions {
+    /**
+     * The command's metadata. What it leaves out is empty, except the region and the timestamp,
+     * which the store fills in.
+     */
+    metadata?: Partial<Metadata> | undefined;
+}
+/** Options for {@link Store.executeWithRetry}. */
+export interface RetryOptions extends ExecuteOptions {
+    /** {@link DEFAULT_RETRY_POLICY} by default. */
+    policy?: RetryPolicy | undefined;
+    /** Waits between attempts. A timer by default; inject one in tests. */
+    sleep?: ((ms: number, signal?: AbortSignal) => Promise<void>) | undefined;
+}
+/**
+ * What a command did:
+ *
+ * - `committed`: it was accepted, and its events (possibly none) are stored.
+ * - `duplicate`: an event since the latest snapshot already carries its command ID, so it didn't
+ *   run.
+ * - `rejected`: the handler refused it. Nothing was written.
+ */
+export type ExecuteResult<S> = {
+    kind: 'committed';
+    state: Loaded<S>;
+    events: SerializedEvent[];
+} | {
+    kind: 'duplicate';
+    commandId: string;
+} | {
+    kind: 'rejected';
+    rejection: Rejection;
+    state: Loaded<S>;
+};
+export declare class Store {
+    #private;
+    readonly repository: Repository;
+    constructor(repository: Repository, options?: StoreOptions);
+    /** The number of events between snapshots of `aggregate`: its own interval, or the store's. */
+    snapshotInterval(aggregate: {
+        readonly snapshotInterval?: number | undefined;
+    }): number;
+    /**
+     * Loads an aggregate from its snapshot and the events after it, or from every event when it has
+     * no snapshot. An entity with no events loads as the initial state at sequence 0.
+     *
+     * The events must continue the sequence. A gap means another writer snapshotted and compacted
+     * the stream between the two reads, so the load starts over, up to three times, and then fails
+     * with a {@link SequenceGapError}. When no events follow, the snapshot is read again to rule out
+     * a compaction that left no gap to see.
+     */
+    load<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string, options?: CallOptions): Promise<Loaded<S>>;
+    /**
+     * Loads the aggregate, runs the command, and commits its events, with a snapshot when the
+     * commit reaches the snapshot interval. A snapshot whose item is over the per-item commit budget
+     * is left out, so the commit still succeeds and later loads replay from the one before.
+     *
+     * A command ID already carried by an event folded in since the latest snapshot makes the
+     * command a `duplicate`, and the handler doesn't run. A conflict with another writer throws;
+     * {@link executeWithRetry} runs the command again.
+     */
+    execute<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string, command: C, options?: ExecuteOptions): Promise<ExecuteResult<S>>;
+    /**
+     * Like {@link execute}, but loads and runs the command again after a retryable error (a
+     * conflict), waiting {@link retryDelay} between attempts. When the attempts run out, the last
+     * error is thrown. A rejection or a duplicate is a result, never retried.
+     */
+    executeWithRetry<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string, command: C, options?: RetryOptions): Promise<ExecuteResult<S>>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/store.js

@@ -0,0 +1,246 @@
+// The Store: loads aggregates, runs commands, and commits their events with the snapshots the
+// snapshot policy calls for.
+import { encodeEventData, replayEvent, } from './aggregate.js';
+import { commitIds } from './commit-id.js';
+import { EvtError, SequenceGapError, SnapshotError, isConflict, isRetryable } from './errors.js';
+import { eventId } from './event.js';
+import { emptyMetadata } from './metadata.js';
+import { DEFAULT_RETRY_POLICY, checkRetryPolicy, retryDelay, sleep, } from './retry.js';
+import { MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue } from './snapshots.js';
+/** The default number of events between snapshots, as in Go and Rust. */
+export const DEFAULT_SNAPSHOT_INTERVAL = 5;
+// How many times a load reads the stream when it finds a sequence gap.
+const LOAD_ATTEMPTS = 3;
+const INT64_MAX = 2n ** 63n - 1n;
+export class Store {
+    repository;
+    #region;
+    #clock;
+    #snapshotInterval;
+    #commitId;
+    constructor(repository, options = {}) {
+        const interval = options.snapshotInterval ?? DEFAULT_SNAPSHOT_INTERVAL;
+        if (!Number.isSafeInteger(interval) || interval < 0) {
+            throw new EvtError('invalidArgument', `the snapshot interval must be a whole number of events: ${interval}`);
+        }
+        this.repository = repository;
+        this.#region = options.region ?? '';
+        this.#clock = options.clock ?? Date.now;
+        this.#snapshotInterval = interval;
+        this.#commitId = options.commitId ?? commitIds(this.#clock);
+    }
+    /** The number of events between snapshots of `aggregate`: its own interval, or the store's. */
+    snapshotInterval(aggregate) {
+        return aggregate.snapshotInterval ?? this.#snapshotInterval;
+    }
+    /**
+     * Loads an aggregate from its snapshot and the events after it, or from every event when it has
+     * no snapshot. An entity with no events loads as the initial state at sequence 0.
+     *
+     * The events must continue the sequence. A gap means another writer snapshotted and compacted
+     * the stream between the two reads, so the load starts over, up to three times, and then fails
+     * with a {@link SequenceGapError}. When no events follow, the snapshot is read again to rule out
+     * a compaction that left no gap to see.
+     */
+    async load(aggregate, entityId, options = {}) {
+        // Each attempt waits for the one before it.
+        /* oxlint-disable no-await-in-loop */
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await this.#loadOnce(aggregate, entityId, options);
+            }
+            catch (error) {
+                if (!isConflict(error) || attempt >= LOAD_ATTEMPTS) {
+                    throw error;
+                }
+            }
+        }
+        /* oxlint-enable no-await-in-loop */
+    }
+    /**
+     * Loads the aggregate, runs the command, and commits its events, with a snapshot when the
+     * commit reaches the snapshot interval. A snapshot whose item is over the per-item commit budget
+     * is left out, so the commit still succeeds and later loads replay from the one before.
+     *
+     * A command ID already carried by an event folded in since the latest snapshot makes the
+     * command a `duplicate`, and the handler doesn't run. A conflict with another writer throws;
+     * {@link executeWithRetry} runs the command again.
+     */
+    async execute(aggregate, entityId, command, options = {}) {
+        const metadata = this.#metadata(options.metadata);
+        const loaded = await this.load(aggregate, entityId, options);
+        const commandId = metadata.commandId;
+        if (commandId !== null && commandId !== '' && loaded.seenCommandIds.has(commandId)) {
+            return { kind: 'duplicate', commandId };
+        }
+        const decision = await aggregate.handle(loaded.state, command);
+        if (decision.kind === 'reject') {
+            return { kind: 'rejected', rejection: decision.rejection, state: loaded };
+        }
+        if (decision.events.length === 0) {
+            return { kind: 'committed', state: loaded, events: [] };
+        }
+        const { state, events, snapshot } = this.#stage(aggregate, loaded, decision.events, metadata);
+        await this.repository.commit({ entityId, events, snapshot }, options);
+        return { kind: 'committed', state, events };
+    }
+    /**
+     * Like {@link execute}, but loads and runs the command again after a retryable error (a
+     * conflict), waiting {@link retryDelay} between attempts. When the attempts run out, the last
+     * error is thrown. A rejection or a duplicate is a result, never retried.
+     */
+    async executeWithRetry(aggregate, entityId, command, options = {}) {
+        const policy = options.policy ?? DEFAULT_RETRY_POLICY;
+        checkRetryPolicy(policy);
+        const wait = options.sleep ?? sleep;
+        // Each attempt waits for the one before it.
+        /* oxlint-disable no-await-in-loop */
+        for (let retry = 0;; retry++) {
+            try {
+                return await this.execute(aggregate, entityId, command, options);
+            }
+            catch (error) {
+                if (!isRetryable(error) || retry + 1 >= policy.maxAttempts) {
+                    throw error;
+                }
+            }
+            await wait(retryDelay(policy, retry), options.signal);
+        }
+        /* oxlint-enable no-await-in-loop */
+    }
+    async #loadOnce(aggregate, entityId, options) {
+        const snapshot = await this.repository.snapshot(entityId, options);
+        let state = aggregate.initial();
+        let sequence = 0n;
+        let snapshotSequence = 0n;
+        if (snapshot) {
+            try {
+                state = aggregate.state.decode(snapshot.payload ?? new Uint8Array());
+            }
+            catch (error) {
+                throw new SnapshotError(entityId, error);
+            }
+            sequence = snapshot.eventSequence;
+            snapshotSequence = snapshot.sequence;
+        }
+        const events = snapshot
+            ? await this.repository.eventsAfter(entityId, sequence, options)
+            : await this.repository.events(entityId, options);
+        // With no events after it, a snapshot and a compaction between the two reads would leave no
+        // gap to see, so the snapshot is read again: a newer one means the stream moved past it.
+        if (events.length === 0) {
+            const covered = (await this.repository.snapshot(entityId, options))?.eventSequence ?? 0n;
+            if (covered > sequence) {
+                throw new SequenceGapError(entityId, sequence, covered + 1n);
+            }
+        }
+        const seenCommandIds = new Set();
+        for (const stored of events) {
+            if (stored.sequence !== sequence + 1n) {
+                throw new SequenceGapError(entityId, sequence, stored.sequence);
+            }
+            state = aggregate.apply(state, replayEvent(aggregate.events, stored));
+            sequence = stored.sequence;
+            const commandId = stored.metadata.commandId;
+            if (commandId !== null && commandId !== '') {
+                seenCommandIds.add(commandId);
+            }
+        }
+        return { entityId, state, sequence, snapshotSequence, seenCommandIds };
+    }
+    // Applies the decided events, and builds the stored events and the snapshot the policy calls
+    // for. The state is only used once the commit succeeds.
+    #stage(aggregate, loaded, decided, metadata) {
+        const entityId = loaded.entityId;
+        let sequence = loaded.sequence;
+        let state = loaded.state;
+        const events = [];
+        for (const event of decided) {
+            if (sequence >= INT64_MAX) {
+                throw new EvtError('invalidCommit', `invalid commit: entity ${entityId} is at the maximum event sequence`);
+            }
+            sequence++;
+            const { version, payload } = encodeEventData(aggregate.events, event);
+            events.push({
+                id: eventId(entityId, sequence),
+                sequence,
+                type: event.type,
+                version,
+                entityId,
+                entityType: aggregate.type,
+                payload,
+                metadata: copyMetadata(metadata),
+            });
+            state = aggregate.apply(state, event);
+        }
+        const interval = this.snapshotInterval(aggregate);
+        let snapshot = null;
+        if (snapshotEventsDue(loaded.sequence, decided.length, interval) > 0) {
+            snapshot = {
+                entityType: aggregate.type,
+                sequence: loaded.snapshotSequence + 1n,
+                payload: aggregate.state.encode(state),
+            };
+            // A snapshot over the per-item budget would fail every commit that carries it.
+            const size = snapshotCommitSize({ ...snapshot, entityId, eventSequence: sequence });
+            if (size > MAX_COMMIT_ITEM_BYTES) {
+                snapshot = null;
+            }
+        }
+        const seenCommandIds = new Set(loaded.seenCommandIds);
+        if (metadata.commandId !== null && metadata.commandId !== '') {
+            seenCommandIds.add(metadata.commandId);
+        }
+        return {
+            state: {
+                entityId,
+                state,
+                sequence,
+                snapshotSequence: snapshot ? snapshot.sequence : loaded.snapshotSequence,
+                seenCommandIds,
+            },
+            events,
+            snapshot,
+        };
+    }
+    // The command's metadata with the store's region and the clock's timestamp where it has none,
+    // and the commit ID the engine stamps: the command ID, else the caller's, else a generated one.
+    // Field by field, so a field an untyped caller set to undefined is empty too, and every key is
+    // written.
+    #metadata(partial = {}) {
+        const empty = emptyMetadata();
+        const metadata = {
+            commandId: partial.commandId ?? empty.commandId,
+            trace: partial.trace ? new Map(partial.trace) : empty.trace,
+            origin: partial.origin ? { ...partial.origin } : empty.origin,
+            address: partial.address ?? empty.address,
+            region: partial.region || this.#region,
+            timestamp: partial.timestamp || rfc3339Seconds(this.#clock()),
+            principalId: partial.principalId ?? empty.principalId,
+            causationId: partial.causationId ?? empty.causationId,
+            extensions: partial.extensions ? new Map(partial.extensions) : empty.extensions,
+            commitId: partial.commitId ?? empty.commitId,
+        };
+        if (metadata.commandId !== null && metadata.commandId !== '') {
+            metadata.commitId = metadata.commandId;
+        }
+        else if (metadata.commitId === '') {
+            metadata.commitId = this.#commitId();
+        }
+        return metadata;
+    }
+}
+// Each stored event gets its own metadata, so changing one changes no other.
+function copyMetadata(metadata) {
+    return {
+        ...metadata,
+        trace: metadata.trace && new Map(metadata.trace),
+        origin: metadata.origin && { ...metadata.origin },
+        extensions: new Map(metadata.extensions),
+    };
+}
+// RFC 3339 in UTC, to the second, as Go's time.RFC3339 formats a UTC time.
+function rfc3339Seconds(ms) {
+    return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/testing/equal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A failed assertion. It carries `actual` and `expected` the way Node's `assert` does, so runners
+ * such as Vitest and Jest show a diff, and `node:test` prints both.
+ */
+export declare class AssertionError extends Error {
+    readonly name = "AssertionError";
+    readonly actual: unknown;
+    readonly expected: unknown;
+    constructor(message: string, actual?: unknown, expected?: unknown);
+}
+/**
+ * Whether two values have the same structure: objects of the same prototype by their own
+ * enumerable string and symbol keys (a key whose value is `undefined` counts as absent), arrays by
+ * their elements, holes included, `Map`s by their entries and `Set`s by their members, buffers and
+ * typed arrays by their bytes, dates by their time, regular expressions by their source and flags,
+ * and everything else with `Object.is`. `Map` keys and `Set` members match by identity, and
+ * `#private` fields aren't seen.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** Prints a value for an assertion message, with `bigint`s, `Map`s and byte arrays legible. */
+export declare function show(value: unknown): string;
+//# sourceMappingURL=equal.d.ts.map

package/dist/testing/equal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equal.d.ts","sourceRoot":"","sources":["../../src/testing/equal.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAkB,IAAI,oBAAmB;IACzC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAE1B,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAIhE;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CA2DzD;AAqBD,+FAA+F;AAC/F,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsC3C"}

package/dist/testing/equal.js

@@ -0,0 +1,121 @@
+// Structural equality and printing for test assertions, so /testing depends on no test framework.
+/**
+ * A failed assertion. It carries `actual` and `expected` the way Node's `assert` does, so runners
+ * such as Vitest and Jest show a diff, and `node:test` prints both.
+ */
+export class AssertionError extends Error {
+    name = 'AssertionError';
+    actual;
+    expected;
+    constructor(message, actual, expected) {
+        super(message);
+        this.actual = actual;
+        this.expected = expected;
+    }
+}
+/**
+ * Whether two values have the same structure: objects of the same prototype by their own
+ * enumerable string and symbol keys (a key whose value is `undefined` counts as absent), arrays by
+ * their elements, holes included, `Map`s by their entries and `Set`s by their members, buffers and
+ * typed arrays by their bytes, dates by their time, regular expressions by their source and flags,
+ * and everything else with `Object.is`. `Map` keys and `Set` members match by identity, and
+ * `#private` fields aren't seen.
+ */
+export function deepEqual(a, b) {
+    if (Object.is(a, b)) {
+        return true;
+    }
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) {
+        return false;
+    }
+    if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) {
+        return false;
+    }
+    if (Array.isArray(a)) {
+        const other = b;
+        if (a.length !== other.length) {
+            return false;
+        }
+        // An index loop, since every() skips holes.
+        for (let i = 0; i < a.length; i++) {
+            if (i in a !== i in other || !deepEqual(a[i], other[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (a instanceof ArrayBuffer || ArrayBuffer.isView(a)) {
+        const left = bytes(a);
+        const right = bytes(b);
+        return left.length === right.length && left.every((byte, i) => byte === right[i]);
+    }
+    if (a instanceof Map) {
+        const other = b;
+        return (a.size === other.size &&
+            [...a].every(([key, entry]) => other.has(key) && deepEqual(entry, other.get(key))));
+    }
+    if (a instanceof Set) {
+        const other = b;
+        return a.size === other.size && [...a].every((entry) => other.has(entry));
+    }
+    if (a instanceof Date) {
+        return Object.is(a.getTime(), b.getTime());
+    }
+    if (a instanceof RegExp) {
+        return a.source === b.source && a.flags === b.flags;
+    }
+    const left = definedKeys(a);
+    const right = definedKeys(b);
+    return (left.length === right.length &&
+        left.every((key) => Object.hasOwn(b, key) && deepEqual(field(a, key), field(b, key))));
+}
+function bytes(value) {
+    return value instanceof ArrayBuffer
+        ? new Uint8Array(value)
+        : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+// The own enumerable keys, symbols included, whose values aren't undefined.
+function definedKeys(value) {
+    const symbols = Object.getOwnPropertySymbols(value).filter((key) => Object.prototype.propertyIsEnumerable.call(value, key));
+    return [...Object.keys(value), ...symbols].filter((key) => field(value, key) !== undefined);
+}
+function field(value, key) {
+    return value[key];
+}
+/** Prints a value for an assertion message, with `bigint`s, `Map`s and byte arrays legible. */
+export function show(value) {
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'bigint') {
+        return `${value}n`;
+    }
+    if (Object.is(value, -0)) {
+        return '-0';
+    }
+    if (typeof value !== 'object' || value === null) {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(show).join(', ')}]`;
+    }
+    if (value instanceof Uint8Array) {
+        return `Uint8Array [${value.join(', ')}]`;
+    }
+    if (value instanceof Map) {
+        const entries = [...value].map(([key, entry]) => `${show(key)} => ${show(entry)}`);
+        return `Map {${entries.join(', ')}}`;
+    }
+    if (value instanceof Set) {
+        return `Set {${[...value].map(show).join(', ')}}`;
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? 'Invalid Date' : `Date ${value.toISOString()}`;
+    }
+    if (value instanceof Error) {
+        return `${value.name}: ${value.message}`;
+    }
+    const entries = Object.entries(value).map(([key, entry]) => `${show(key)}: ${show(entry)}`);
+    return `{${entries.join(', ')}}`;
+}
+//# sourceMappingURL=equal.js.map