actor-ts 0.9.0

package/dist/persistence/replicated/ReplicatedSnapshot.d.ts

@@ -0,0 +1,43 @@
+import type { ReplicaId } from '../../crdt/Crdt.js';
+import type { ReplicatedEventEnvelope } from '../ReplicatedEventSourcedActor.js';
+import type { VectorClockData } from './VectorClock.js';
+/**
+ * Wire shape for a `ReplicatedEventSourcedActor` snapshot.  Persisted
+ * to the standard `SnapshotStore` and reloaded on `preStart` so a
+ * months-old replica doesn't have to re-fold its entire local journal
+ * to rebuild state.
+ *
+ * Why every field is needed:
+ *
+ *   - `state` — what `onEvent` has produced; the user-visible result.
+ *   - `vc` — the actor's current vector-clock view; required so future
+ *     ticks merge correctly with peer envelopes.
+ *   - `seenIds` — dedupe set keyed by `(replica, seqAtReplica)`.  After
+ *     loading a snapshot we still process the journal's delta, plus
+ *     in-flight pubsub deliveries; without seenIds we could double-
+ *     apply an event that was on disk AND in flight.
+ *   - `events` — canonical sorted history.  Out-of-order remote arrivals
+ *     trigger a refold; the refold reads `events`, so we must persist
+ *     it.  This is the heaviest field — for a 100k-event actor a
+ *     snapshot is 100k envelopes on disk.  Worth it because it
+ *     eliminates the recovery-time cost of re-sorting the whole journal.
+ *   - `localSeq` — `_localSeq` at snapshot time, so a fresh restart
+ *     doesn't issue a `seqAtReplica` that conflicts with previously-
+ *     written events.
+ *   - `journalSeqAtSnapshot` — the journal's sequence number of the
+ *     last event accounted for by `events`.  Recovery reads from
+ *     `journalSeqAtSnapshot + 1` — that's where the I/O win comes from.
+ */
+export interface ReplicatedSnapshot<E, S> {
+    readonly state: S;
+    readonly vc: VectorClockData;
+    readonly seenIds: ReadonlyArray<string>;
+    readonly events: ReadonlyArray<ReplicatedEventEnvelope<E>>;
+    readonly localSeq: number;
+    readonly journalSeqAtSnapshot: number;
+    /** Replica that took the snapshot — informational. */
+    readonly takenBy: ReplicaId;
+    /** Wall-clock time the snapshot was written — informational. */
+    readonly takenAt: number;
+}
+//# sourceMappingURL=ReplicatedSnapshot.d.ts.map

package/dist/persistence/replicated/ReplicatedSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplicatedSnapshot.d.ts","sourceRoot":"","sources":["../../../src/persistence/replicated/ReplicatedSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/persistence/replicated/ReplicatedSnapshot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ReplicatedSnapshot.js.map

package/dist/persistence/replicated/ReplicatedSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplicatedSnapshot.js","sourceRoot":"","sources":["../../../src/persistence/replicated/ReplicatedSnapshot.ts"],"names":[],"mappings":""}

package/dist/persistence/replicated/VectorClock.d.ts

@@ -0,0 +1,57 @@
+import type { ReplicaId } from '../../crdt/Crdt.js';
+/**
+ * Vector clock — a logical timestamp per replica that captures the
+ * "happens-before" relation between events across nodes.
+ *
+ * For each pair of clocks `a`, `b`:
+ *
+ *   - **a < b** ("a happens-before b") iff every component of `a` is
+ *     `<= b`'s and at least one is strictly less.
+ *   - **a == b** iff every component is equal.
+ *   - Otherwise the events are **concurrent** — neither preceded
+ *     the other, and a conflict resolver decides what wins.
+ *
+ * Used by {@link ReplicatedEventSourcedActor} to recognise
+ * concurrent edits to the same persistenceId from different
+ * replicas, and by the {@link ConflictResolver} plug-in to merge
+ * those concurrent events deterministically.
+ *
+ * **Wire shape**: a plain `Record<ReplicaId, number>`.  Empty
+ * components are treated as `0`, so omitting them is fine for
+ * compactness on the wire.
+ */
+export type VectorClockData = Readonly<Record<ReplicaId, number>>;
+export declare class VectorClock {
+    private readonly entries;
+    private constructor();
+    /** All components zero. */
+    static empty(): VectorClock;
+    /** Build from an object literal — omitted entries are treated as 0. */
+    static fromData(data: VectorClockData): VectorClock;
+    /** Get the value for `replica`; missing entries are 0. */
+    get(replica: ReplicaId): number;
+    /** Bump `replica`'s component by 1 — typically called when persisting. */
+    tick(replica: ReplicaId): VectorClock;
+    /** Component-wise max — used after observing a remote event. */
+    merge(other: VectorClock): VectorClock;
+    /**
+     * Compare with another clock.
+     *
+     * Returns:
+     *   - `'before'`     — every component of `this` is `<= other`
+     *                       and at least one is strictly less.
+     *   - `'after'`      — every component of `this` is `>= other`
+     *                       and at least one is strictly greater.
+     *   - `'equal'`      — all components match.
+     *   - `'concurrent'` — neither dominates.
+     */
+    compareTo(other: VectorClock): VectorClockOrder;
+    /** True iff `this` strictly happens-before `other`. */
+    happensBefore(other: VectorClock): boolean;
+    /** True iff `this` and `other` are concurrent (neither dominates). */
+    isConcurrentWith(other: VectorClock): boolean;
+    toJSON(): VectorClockData;
+    toString(): string;
+}
+export type VectorClockOrder = 'before' | 'after' | 'equal' | 'concurrent';
+//# sourceMappingURL=VectorClock.d.ts.map

package/dist/persistence/replicated/VectorClock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorClock.d.ts","sourceRoot":"","sources":["../../../src/persistence/replicated/VectorClock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AAElE,qBAAa,WAAW;IACF,OAAO,CAAC,QAAQ,CAAC,OAAO;IAA5C,OAAO;IAEP,2BAA2B;IAC3B,MAAM,CAAC,KAAK,IAAI,WAAW;IAE3B,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW;IAInD,0DAA0D;IAC1D,GAAG,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM;IAE/B,0EAA0E;IAC1E,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,WAAW;IAMrC,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW;IAStC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,gBAAgB;IAgB/C,uDAAuD;IACvD,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAE1C,sEAAsE;IACtE,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAE7C,MAAM,IAAI,eAAe;IAMzB,QAAQ,IAAI,MAAM;CAMnB;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,CAAC"}

package/dist/persistence/replicated/VectorClock.js

@@ -0,0 +1,79 @@
+export class VectorClock {
+    entries;
+    constructor(entries) {
+        this.entries = entries;
+    }
+    /** All components zero. */
+    static empty() { return new VectorClock(new Map()); }
+    /** Build from an object literal — omitted entries are treated as 0. */
+    static fromData(data) {
+        return new VectorClock(new Map(Object.entries(data)));
+    }
+    /** Get the value for `replica`; missing entries are 0. */
+    get(replica) { return this.entries.get(replica) ?? 0; }
+    /** Bump `replica`'s component by 1 — typically called when persisting. */
+    tick(replica) {
+        const next = new Map(this.entries);
+        next.set(replica, (next.get(replica) ?? 0) + 1);
+        return new VectorClock(next);
+    }
+    /** Component-wise max — used after observing a remote event. */
+    merge(other) {
+        const next = new Map(this.entries);
+        for (const [r, v] of other.entries) {
+            const ours = next.get(r) ?? 0;
+            if (v > ours)
+                next.set(r, v);
+        }
+        return new VectorClock(next);
+    }
+    /**
+     * Compare with another clock.
+     *
+     * Returns:
+     *   - `'before'`     — every component of `this` is `<= other`
+     *                       and at least one is strictly less.
+     *   - `'after'`      — every component of `this` is `>= other`
+     *                       and at least one is strictly greater.
+     *   - `'equal'`      — all components match.
+     *   - `'concurrent'` — neither dominates.
+     */
+    compareTo(other) {
+        const keys = new Set([...this.entries.keys(), ...other.entries.keys()]);
+        let lt = false;
+        let gt = false;
+        for (const k of keys) {
+            const a = this.get(k);
+            const b = other.get(k);
+            if (a < b)
+                lt = true;
+            else if (a > b)
+                gt = true;
+            if (lt && gt)
+                return 'concurrent';
+        }
+        if (lt && !gt)
+            return 'before';
+        if (!lt && gt)
+            return 'after';
+        return 'equal';
+    }
+    /** True iff `this` strictly happens-before `other`. */
+    happensBefore(other) { return this.compareTo(other) === 'before'; }
+    /** True iff `this` and `other` are concurrent (neither dominates). */
+    isConcurrentWith(other) { return this.compareTo(other) === 'concurrent'; }
+    toJSON() {
+        const out = {};
+        for (const [k, v] of this.entries)
+            out[k] = v;
+        return out;
+    }
+    toString() {
+        const pairs = [];
+        const sorted = Array.from(this.entries.keys()).sort();
+        for (const k of sorted)
+            pairs.push(`${k}=${this.entries.get(k)}`);
+        return `VC{${pairs.join(', ')}}`;
+    }
+}
+//# sourceMappingURL=VectorClock.js.map

package/dist/persistence/replicated/VectorClock.js.map

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

package/dist/persistence/snapshot-stores/CachedSnapshotStore.d.ts

@@ -0,0 +1,27 @@
+import type { Cache } from '../../cache/Cache.js';
+import type { Snapshot } from '../JournalTypes.js';
+import type { PersistenceOptions } from '../PersistenceOptions.js';
+import type { SnapshotStore } from '../SnapshotStore.js';
+import { type Option } from '../../util/Option.js';
+export interface CachedSnapshotStoreOptions {
+    /** Backing cache — typically Redis in production. */
+    readonly cache: Cache;
+    /** Cache TTL in milliseconds.  Default: 5 minutes. */
+    readonly ttlMs?: number;
+    /** Key prefix (default: `'snap:'`) prevents collisions in shared caches. */
+    readonly keyPrefix?: string;
+}
+export declare class CachedSnapshotStore implements SnapshotStore {
+    private readonly underlying;
+    private readonly cache;
+    private readonly ttlMs;
+    private readonly keyPrefix;
+    constructor(underlying: SnapshotStore, opts: CachedSnapshotStoreOptions);
+    save<S>(pid: string, seq: number, state: S, options?: PersistenceOptions): Promise<Snapshot<S>>;
+    loadLatest<S>(pid: string, options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    loadBefore<S>(pid: string, seq: number, options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    delete(pid: string, toSeq: number): Promise<void>;
+    close(): Promise<void>;
+    private keyFor;
+}
+//# sourceMappingURL=CachedSnapshotStore.d.ts.map

package/dist/persistence/snapshot-stores/CachedSnapshotStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachedSnapshotStore.d.ts","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/CachedSnapshotStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAoC/D,MAAM,WAAW,0BAA0B;IACzC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AASD,qBAAa,mBAAoB,YAAW,aAAa;IAMrD,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGhB,UAAU,EAAE,aAAa,EAC1C,IAAI,EAAE,0BAA0B;IAU5B,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAO/F,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAUtF,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAKnG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,OAAO,CAAC,MAAM;CAGf"}

package/dist/persistence/snapshot-stores/CachedSnapshotStore.js

@@ -0,0 +1,82 @@
+import { none, some } from '../../util/Option.js';
+/**
+ * Read-through cache decorator for any `SnapshotStore`.  Targets the hot
+ * `loadLatest` path that fires whenever a sharded entity wakes up — at
+ * scale (rebalancing, deploys), thousands of cold-starts hammer the
+ * underlying store (Cassandra, S3, …) with the same query shape.  A
+ * Redis cache in front cuts that to a single round-trip in 99% of cases.
+ *
+ * Cache semantics:
+ *   - `loadLatest` is read-through with TTL.
+ *   - `save` is **write-through-with-invalidate**: we delegate to the
+ *     underlying store, then *delete* the cache entry.  We deliberately
+ *     do NOT write the new snapshot into the cache, because in a
+ *     cluster two nodes might race on save and the local-write would
+ *     leave a stale entry.  Letting the next read repopulate is
+ *     simpler and safe.
+ *   - `loadBefore` is **not cached** — it has too many possible `seq`
+ *     values to cache profitably and it's used much less often (only
+ *     during recovery when seeking past a corrupt snapshot).
+ *   - `delete` invalidates the cache entry.
+ *
+ * **Correctness:**  TTL is the safety net.  Even if a node crashes
+ * between `save` and `cache.delete`, the cache entry expires within
+ * `ttlMs` and the next read fetches the fresh snapshot from the
+ * underlying store.  Pick a TTL on the order of minutes (default: 5
+ * min) — short enough that stale reads after a missed invalidation
+ * never matter, long enough to absorb cold-start storms.
+ *
+ *   const cassandra = new CassandraSnapshotStore({...});
+ *   const cached    = new CachedSnapshotStore(cassandra, { cache, ttlMs: 5 * 60_000 });
+ *   ext.setSnapshotStore(cached);
+ */
+const DEFAULT_TTL_MS = 5 * 60_000;
+export class CachedSnapshotStore {
+    underlying;
+    cache;
+    ttlMs;
+    keyPrefix;
+    constructor(underlying, opts) {
+        this.underlying = underlying;
+        this.cache = opts.cache;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        if (!Number.isFinite(this.ttlMs) || this.ttlMs <= 0) {
+            throw new Error(`CachedSnapshotStore: ttlMs must be a positive finite number, got ${this.ttlMs}`);
+        }
+        this.keyPrefix = opts.keyPrefix ?? 'snap:';
+    }
+    async save(pid, seq, state, options) {
+        const written = await this.underlying.save(pid, seq, state, options);
+        // Invalidate, do NOT write — see class doc for the cluster-race rationale.
+        await this.cache.delete(this.keyFor(pid));
+        return written;
+    }
+    async loadLatest(pid, options) {
+        const key = this.keyFor(pid);
+        const hit = await this.cache.get(key);
+        if (hit.isSome())
+            return some(hit.value);
+        const fetched = await this.underlying.loadLatest(pid, options);
+        if (fetched.isNone())
+            return none;
+        await this.cache.set(key, fetched.value, this.ttlMs);
+        return fetched;
+    }
+    async loadBefore(pid, seq, options) {
+        // Not cached — see class doc.
+        return this.underlying.loadBefore(pid, seq, options);
+    }
+    async delete(pid, toSeq) {
+        await this.underlying.delete(pid, toSeq);
+        await this.cache.delete(this.keyFor(pid));
+    }
+    async close() {
+        await this.underlying.close?.();
+        // We do NOT close the cache — it's owned by the caller (the same
+        // cache typically backs HTTP middleware, etc.).
+    }
+    keyFor(pid) {
+        return `${this.keyPrefix}${pid}`;
+    }
+}
+//# sourceMappingURL=CachedSnapshotStore.js.map

package/dist/persistence/snapshot-stores/CachedSnapshotStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachedSnapshotStore.js","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/CachedSnapshotStore.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAe,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,cAAc,GAAG,CAAC,GAAG,MAAM,CAAC;AAkBlC,MAAM,OAAO,mBAAmB;IAMX;IALF,KAAK,CAAQ;IACb,KAAK,CAAS;IACd,SAAS,CAAS;IAEnC,YACmB,UAAyB,EAC1C,IAAgC;QADf,eAAU,GAAV,UAAU,CAAe;QAG1C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,cAAc,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CAAC,oEAAoE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACpG,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,GAAW,EAAE,GAAW,EAAE,KAAQ,EAAE,OAA4B;QAC5E,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAI,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACxE,2EAA2E;QAC3E,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,GAAW,EAAE,OAA4B;QAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,GAAG,CAAC,CAAC;QACzD,IAAI,GAAG,CAAC,MAAM,EAAE;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,KAAoB,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,UAAU,CAAI,GAAG,EAAE,OAAO,CAAC,CAAC;QAClE,IAAI,OAAO,CAAC,MAAM,EAAE;YAAE,OAAO,IAAI,CAAC;QAClC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,GAAG,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,GAAW,EAAE,GAAW,EAAE,OAA4B;QACxE,8BAA8B;QAC9B,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAI,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,KAAa;QACrC,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;QAChC,iEAAiE;QACjE,gDAAgD;IAClD,CAAC;IAEO,MAAM,CAAC,GAAW;QACxB,OAAO,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;IACnC,CAAC;CACF"}

package/dist/persistence/snapshot-stores/CassandraSnapshotStore.d.ts

@@ -0,0 +1,42 @@
+import { type Snapshot } from '../JournalTypes.js';
+import type { PersistenceOptions } from '../PersistenceOptions.js';
+import type { SnapshotStore } from '../SnapshotStore.js';
+import { type Option } from '../../util/Option.js';
+import { type CassandraClientLike, type CassandraConnection } from '../journals/CassandraClient.js';
+export interface CassandraSnapshotStoreOptions extends CassandraConnection {
+    /** Table name; default `snapshots`. */
+    readonly snapshotsTable?: string;
+    /** Maximum number of snapshots kept per pid.  `<= 0` = keep all.  Default: 3. */
+    readonly keepN?: number;
+    /** Auto-create the snapshots table on first connect. */
+    readonly autoCreateTables?: boolean;
+    /** Pre-built client — bypass internal construction (share with journal). */
+    readonly client?: CassandraClientLike;
+}
+/**
+ * SnapshotStore backed by Cassandra/Scylla.  Schema mirrors the journal:
+ * clustered on `sequence_nr DESC` so `loadLatest` is a single-row read.
+ * When `keepN > 0`, excess snapshots are pruned on each `save`.
+ */
+export declare class CassandraSnapshotStore implements SnapshotStore {
+    private readonly options;
+    private client;
+    private started;
+    private stopped;
+    private readonly ownsClient;
+    private readonly keepN;
+    constructor(options: CassandraSnapshotStoreOptions);
+    start(): Promise<void>;
+    save<S>(pid: string, seq: number, state: S, _options?: PersistenceOptions): Promise<Snapshot<S>>;
+    loadLatest<S>(pid: string, _options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    loadBefore<S>(pid: string, seq: number, _options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    delete(pid: string, toSeq: number): Promise<void>;
+    close(): Promise<void>;
+    private get table();
+    private qualified;
+    private rowToSnapshot;
+    private pruneKeepN;
+    private ensureStarted;
+    private ensureTables;
+}
+//# sourceMappingURL=CassandraSnapshotStore.d.ts.map

package/dist/persistence/snapshot-stores/CassandraSnapshotStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CassandraSnapshotStore.d.ts","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/CassandraSnapshotStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAExC,MAAM,WAAW,6BAA8B,SAAQ,mBAAmB;IACxE,uCAAuC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CACvC;AASD;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,OAAO,EAAE,6BAA6B;IAO5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAetB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAkBhG,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAUvF,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAUpG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAajD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B,OAAO,KAAK,KAAK,GAAiE;IAClF,OAAO,CAAC,SAAS;IAEjB,OAAO,CAAC,aAAa;YAUP,UAAU;YAkBV,aAAa;YAKb,YAAY;CAW3B"}

package/dist/persistence/snapshot-stores/CassandraSnapshotStore.js

@@ -0,0 +1,121 @@
+import { JournalError } from '../JournalTypes.js';
+import { none, some } from '../../util/Option.js';
+import { createCassandraClient, keyspaceDdl, } from '../journals/CassandraClient.js';
+/**
+ * SnapshotStore backed by Cassandra/Scylla.  Schema mirrors the journal:
+ * clustered on `sequence_nr DESC` so `loadLatest` is a single-row read.
+ * When `keepN > 0`, excess snapshots are pruned on each `save`.
+ */
+export class CassandraSnapshotStore {
+    options;
+    client;
+    started = false;
+    stopped = false;
+    ownsClient;
+    keepN;
+    constructor(options) {
+        this.options = options;
+        this.client = options.client ?? undefined;
+        this.ownsClient = !options.client;
+        this.keepN = options.keepN ?? 3;
+    }
+    async start() {
+        if (this.started)
+            return;
+        if (this.ownsClient && !this.client) {
+            this.client = await createCassandraClient(this.options);
+        }
+        await this.client.connect();
+        if (this.options.autoCreateKeyspace) {
+            await this.client.execute(keyspaceDdl(this.options));
+        }
+        if (this.options.autoCreateTables ?? true) {
+            await this.ensureTables();
+        }
+        this.started = true;
+    }
+    async save(pid, seq, state, _options) {
+        // Cassandra store has no compression / encryption — options ignored.
+        await this.ensureStarted();
+        const now = Date.now();
+        const payload = JSON.stringify(state);
+        try {
+            await this.client.execute(`INSERT INTO ${this.qualified()} (persistence_id, sequence_nr, timestamp, payload) VALUES (?, ?, ?, ?)`, [pid, seq, now, payload], { prepare: true });
+            if (this.keepN > 0)
+                await this.pruneKeepN(pid);
+            return { persistenceId: pid, sequenceNr: seq, state, timestamp: now };
+        }
+        catch (e) {
+            throw new JournalError(`CassandraSnapshotStore.save failed: ${e.message}`, e);
+        }
+    }
+    async loadLatest(pid, _options) {
+        await this.ensureStarted();
+        const res = await this.client.execute(`SELECT persistence_id, sequence_nr, timestamp, payload FROM ${this.qualified()} WHERE persistence_id = ? LIMIT 1`, [pid], { prepare: true });
+        return this.rowToSnapshot(res.rows[0]);
+    }
+    async loadBefore(pid, seq, _options) {
+        await this.ensureStarted();
+        const res = await this.client.execute(`SELECT persistence_id, sequence_nr, timestamp, payload FROM ${this.qualified()} WHERE persistence_id = ? AND sequence_nr < ? LIMIT 1`, [pid, seq], { prepare: true });
+        return this.rowToSnapshot(res.rows[0]);
+    }
+    async delete(pid, toSeq) {
+        await this.ensureStarted();
+        try {
+            await this.client.execute(`DELETE FROM ${this.qualified()} WHERE persistence_id = ? AND sequence_nr <= ?`, [pid, toSeq], { prepare: true });
+        }
+        catch (e) {
+            throw new JournalError(`CassandraSnapshotStore.delete failed: ${e.message}`, e);
+        }
+    }
+    async close() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.ownsClient && this.started) {
+            try {
+                await this.client.shutdown();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /* ========================== internal ========================== */
+    get table() { return this.options.snapshotsTable ?? 'snapshots'; }
+    qualified() { return `${this.options.keyspace}.${this.table}`; }
+    rowToSnapshot(row) {
+        if (!row)
+            return none;
+        return some({
+            persistenceId: row.persistence_id,
+            sequenceNr: Number(row.sequence_nr),
+            timestamp: Number(row.timestamp),
+            state: JSON.parse(row.payload),
+        });
+    }
+    async pruneKeepN(pid) {
+        // Read the newest `keepN` sequence numbers and delete everything older.
+        const res = await this.client.execute(`SELECT sequence_nr FROM ${this.qualified()} WHERE persistence_id = ? LIMIT ?`, [pid, this.keepN], { prepare: true });
+        const rows = res.rows;
+        if (rows.length < this.keepN)
+            return; // not yet at the cap
+        const cutoff = Number(rows[rows.length - 1].sequence_nr);
+        if (cutoff <= 0)
+            return;
+        await this.client.execute(`DELETE FROM ${this.qualified()} WHERE persistence_id = ? AND sequence_nr < ?`, [pid, cutoff], { prepare: true });
+    }
+    async ensureStarted() {
+        if (this.started)
+            return;
+        await this.start();
+    }
+    async ensureTables() {
+        await this.client.execute(`CREATE TABLE IF NOT EXISTS ${this.qualified()} (`
+            + ` persistence_id text,`
+            + ` sequence_nr bigint,`
+            + ` timestamp bigint,`
+            + ` payload text,`
+            + ` PRIMARY KEY (persistence_id, sequence_nr)`
+            + ` ) WITH CLUSTERING ORDER BY (sequence_nr DESC)`);
+    }
+}
+//# sourceMappingURL=CassandraSnapshotStore.js.map

package/dist/persistence/snapshot-stores/CassandraSnapshotStore.js.map

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

package/dist/persistence/snapshot-stores/InMemorySnapshotStore.d.ts

@@ -0,0 +1,19 @@
+import type { Snapshot } from '../JournalTypes.js';
+import type { PersistenceOptions } from '../PersistenceOptions.js';
+import type { SnapshotStore } from '../SnapshotStore.js';
+import { type Option } from '../../util/Option.js';
+/**
+ * In-process snapshot store.  Keeps all snapshots per persistenceId;
+ * `loadLatest` picks the newest, `loadBefore` the newest `< seq`.
+ * Plug-in implementations typically keep only the last N snapshots to
+ * save space — the in-memory one doesn't bother.
+ */
+export declare class InMemorySnapshotStore implements SnapshotStore {
+    private readonly store;
+    save<S>(pid: string, seq: number, state: S, _options?: PersistenceOptions): Promise<Snapshot<S>>;
+    loadLatest<S>(pid: string, _options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    loadBefore<S>(pid: string, seq: number, _options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    delete(pid: string, toSeq: number): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=InMemorySnapshotStore.d.ts.map

package/dist/persistence/snapshot-stores/InMemorySnapshotStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemorySnapshotStore.d.ts","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/InMemorySnapshotStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAE1D,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAWhG,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAMvF,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IASpG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAC7B"}

package/dist/persistence/snapshot-stores/InMemorySnapshotStore.js

@@ -0,0 +1,44 @@
+import { none, some } from '../../util/Option.js';
+/**
+ * In-process snapshot store.  Keeps all snapshots per persistenceId;
+ * `loadLatest` picks the newest, `loadBefore` the newest `< seq`.
+ * Plug-in implementations typically keep only the last N snapshots to
+ * save space — the in-memory one doesn't bother.
+ */
+export class InMemorySnapshotStore {
+    store = new Map();
+    async save(pid, seq, state, _options) {
+        // In-memory store ignores compression / encryption options.
+        const list = this.store.get(pid) ?? [];
+        const snap = { persistenceId: pid, sequenceNr: seq, state, timestamp: Date.now() };
+        list.push(snap);
+        // Keep sorted ascending by seq for easy queries.
+        list.sort((a, b) => a.sequenceNr - b.sequenceNr);
+        this.store.set(pid, list);
+        return snap;
+    }
+    async loadLatest(pid, _options) {
+        const list = this.store.get(pid);
+        if (!list || list.length === 0)
+            return none;
+        return some(list[list.length - 1]);
+    }
+    async loadBefore(pid, seq, _options) {
+        const list = this.store.get(pid);
+        if (!list || list.length === 0)
+            return none;
+        for (let i = list.length - 1; i >= 0; i--) {
+            if (list[i].sequenceNr < seq)
+                return some(list[i]);
+        }
+        return none;
+    }
+    async delete(pid, toSeq) {
+        const list = this.store.get(pid);
+        if (!list)
+            return;
+        this.store.set(pid, list.filter(s => s.sequenceNr > toSeq));
+    }
+    async close() { this.store.clear(); }
+}
+//# sourceMappingURL=InMemorySnapshotStore.js.map

package/dist/persistence/snapshot-stores/InMemorySnapshotStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemorySnapshotStore.js","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/InMemorySnapshotStore.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAe,MAAM,sBAAsB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,OAAO,qBAAqB;IACf,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEhE,KAAK,CAAC,IAAI,CAAI,GAAW,EAAE,GAAW,EAAE,KAAQ,EAAE,QAA6B;QAC7E,4DAA4D;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,IAAI,GAAgB,EAAE,aAAa,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QAChG,IAAI,CAAC,IAAI,CAAC,IAAyB,CAAC,CAAC;QACrC,iDAAiD;QACjD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,GAAW,EAAE,QAA6B;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAgB,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,GAAW,EAAE,GAAW,EAAE,QAA6B;QACzE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5C,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,IAAI,IAAI,CAAC,CAAC,CAAE,CAAC,UAAU,GAAG,GAAG;gBAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAgB,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,KAAa;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,KAAK,KAAoB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;CACrD"}

package/dist/persistence/snapshot-stores/ObjectStorageSnapshotStore.d.ts

@@ -0,0 +1,46 @@
+import { type Snapshot } from '../JournalTypes.js';
+import type { CompressionConfig, CompressionResolver, EncryptionConfig, EncryptionResolver } from '../object-storage/PluginConfig.js';
+import type { ObjectStorageBackend } from '../object-storage/ObjectStorageBackend.js';
+import type { PersistenceOptions } from '../PersistenceOptions.js';
+import type { SnapshotStore } from '../SnapshotStore.js';
+import { type Option } from '../../util/Option.js';
+export interface ObjectStorageSnapshotStoreOptions {
+    /** The underlying storage layer (S3 / Filesystem / …). */
+    readonly backend: ObjectStorageBackend;
+    /** Prepended to every key before the persistenceId.  Default: ''. */
+    readonly prefix?: string;
+    /** Keep this many snapshots per persistenceId; older ones are deleted on save.  Default: 3. */
+    readonly keepN?: number;
+    /** Compression — flat config or per-pid resolver.  Default: `{ algorithm: 'gzip' }`. */
+    readonly compression?: CompressionConfig | CompressionResolver;
+    /** Encryption — flat config or per-pid resolver.  Default: `{ mode: 'none' }`. */
+    readonly encryption?: EncryptionConfig | EncryptionResolver;
+}
+/**
+ * SnapshotStore backed by any `ObjectStorageBackend`.  Each snapshot
+ * lands at `<prefix><pid>/<seq.padStart(20,'0')>.json` — the padding
+ * scheme is what makes `loadLatest` cheap (single LIST with `limit:1`
+ * and reverse iteration over the sorted result).
+ *
+ * `keepN`-based pruning runs after every successful save; older
+ * snapshots are deleted in a best-effort post-pass.  A failed prune
+ * does not fail the save — the next save retries.
+ */
+export declare class ObjectStorageSnapshotStore implements SnapshotStore {
+    private readonly backend;
+    private readonly prefix;
+    private readonly keepN;
+    private readonly compression;
+    private readonly encryption;
+    constructor(opts: ObjectStorageSnapshotStoreOptions);
+    save<S>(pid: string, seq: number, state: S, options?: PersistenceOptions): Promise<Snapshot<S>>;
+    loadLatest<S>(pid: string, options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    loadBefore<S>(pid: string, seq: number, options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    delete(pid: string, toSeq: number): Promise<void>;
+    close(): Promise<void>;
+    private snapshotKey;
+    private pidPrefix;
+    private fetchSnapshot;
+    private pruneToKeepN;
+}
+//# sourceMappingURL=ObjectStorageSnapshotStore.d.ts.map

package/dist/persistence/snapshot-stores/ObjectStorageSnapshotStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectStorageSnapshotStore.d.ts","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/ObjectStorageSnapshotStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAOjE,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAQ/D,MAAM,WAAW,iCAAiC;IAChD,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,CAAC;IAC/D,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,GAAG,kBAAkB,CAAC;CAC7D;AAED;;;;;;;;;GASG;AACH,qBAAa,0BAA2B,YAAW,aAAa;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsD;IAClF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoD;gBAEnE,IAAI,EAAE,iCAAiC;IAQ7C,IAAI,CAAC,CAAC,EACV,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAwDjB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAQtF,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAanG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,SAAS;YAIH,aAAa;YA8Bb,YAAY;CAM3B"}