actor-ts 0.9.0 → 0.10.0

package/dist/persistence/object-storage/reEncryptionSweep.js

@@ -26,6 +26,17 @@
 import { decodeBody, encodeBody, FLAG_ENCRYPTED, FLAG_KEY_VERSIONED, } from './BodyCodec.js';
 import { deriveSubkey } from './Encryption.js';
 const ATS1_MAGIC_PREFIX = new Uint8Array([0x41, 0x54, 0x53, 0x31]); // "ATS1"
+/**
+ * In-process default.  Useful for tests and short-lived runs.  For
+ * long-running sweeps that must survive a process crash, plug a
+ * file-backed or backend-backed implementation in instead.
+ */
+export class InMemoryReEncryptProgressStore {
+    state = { lastKey: null, processedCount: 0 };
+    async load() { return { ...this.state }; }
+    async save(state) { this.state = { ...state }; }
+    async clear() { this.state = { lastKey: null, processedCount: 0 }; }
+}
 /**
  * Re-encrypt every body under `keyPrefix` to the active key in `keyring`.
  *
@@ -48,7 +59,11 @@ const ATS1_MAGIC_PREFIX = new Uint8Array([0x41, 0x54, 0x53, 0x31]); // "ATS1"
  *   console.log(`re-encrypted ${result.rewrote} of ${result.scanned}`);
  */
 export async function reEncryptObjectStorage(backend, opts) {
-    const items = await backend.list({ prefix: opts.keyPrefix });
+    const rawItems = await backend.list({ prefix: opts.keyPrefix });
+    // Sort lexicographically so that resume by `lastKey` is deterministic
+    // across backends (FS-backend lists in disk order, S3 lists alphabetic
+    // — sorting normalises).
+    const items = [...rawItems].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
     const pidFromKey = opts.pidFromKey ?? defaultPidFromKey;
     const result = {
         scanned: 0,
@@ -61,8 +76,60 @@ export async function reEncryptObjectStorage(backend, opts) {
     if (!Number.isInteger(activeVersion) || activeVersion < 0 || activeVersion > 255) {
         throw new Error(`reEncryptObjectStorage: keyring.active.version must be an integer in [0, 255], got ${activeVersion}`);
     }
+    // Pre-sweep keyring-completeness check (#109).  Sample some bodies,
+    // gather their key versions, fail fast if any version isn't in the
+    // keyring.  Better to refuse before touching the corpus than to
+    // half-rewrite and then crash on a missing retired key.
+    if (opts.verifyKeyringCompleteness !== false) {
+        const sampleSize = opts.sampleSize ?? Math.min(100, items.length);
+        const haveVersions = new Set([
+            opts.keyring.active.version,
+            ...(opts.keyring.retired?.map((r) => r.version) ?? []),
+        ]);
+        const missing = new Set();
+        for (let i = 0; i < sampleSize; i++) {
+            const item = items[i];
+            if (opts.skip?.(item.key))
+                continue;
+            const fetched = await backend.get(item.key);
+            if (fetched.isNone())
+                continue;
+            const framed = fetched.value.body;
+            if (!startsWithAts1(framed))
+                continue;
+            const flags = framed[4];
+            const encrypted = (flags & FLAG_ENCRYPTED) !== 0;
+            if (!encrypted)
+                continue;
+            const versioned = (flags & FLAG_KEY_VERSIONED) !== 0;
+            const bodyVersion = versioned ? framed[5] : 0;
+            if (!haveVersions.has(bodyVersion))
+                missing.add(bodyVersion);
+        }
+        if (missing.size > 0) {
+            throw new Error(`reEncryptObjectStorage: keyring is incomplete — bodies in the prefix `
+                + `reference master-key version(s) [${[...missing].sort((a, b) => a - b).join(', ')}] `
+                + `which are absent from the keyring's 'active' and 'retired' lists.  `
+                + `Restore those keys before sweeping, or the sweep will fail mid-corpus.`);
+        }
+    }
+    // Resume from saved progress (#109).
+    let resumeStartIdx = 0;
+    let processedCountBase = 0;
+    if (opts.progress) {
+        const saved = await opts.progress.load();
+        if (saved.lastKey !== null) {
+            // First index where key > lastKey.  Lower-bound scan since items
+            // are sorted.
+            while (resumeStartIdx < items.length && items[resumeStartIdx].key <= saved.lastKey) {
+                resumeStartIdx += 1;
+            }
+            processedCountBase = saved.processedCount;
+        }
+    }
+    const saveEveryN = opts.saveProgressEveryN ?? 50;
     const total = items.length;
-    for (let idx = 0; idx < total; idx++) {
+    for (let idx = resumeStartIdx; idx < total; idx++) {
         const item = items[idx];
         if (opts.skip?.(item.key))
             continue;
@@ -129,7 +196,20 @@ export async function reEncryptObjectStorage(backend, opts) {
         });
         result.rewrote += 1;
         opts.onProgress?.({ key: item.key, idx, total, action: 'rewrote' });
+        // Persist progress every Nth REWRITE (skips don't count — they're
+        // cheap to redo).
+        if (opts.progress && result.rewrote % saveEveryN === 0) {
+            await opts.progress.save({
+                lastKey: item.key,
+                processedCount: processedCountBase + result.rewrote,
+            });
+        }
     }
+    // Successful end → clear progress so a fresh re-run starts from the
+    // beginning.  If we crashed instead, the saved progress stays on
+    // disk and the next call resumes.
+    if (opts.progress)
+        await opts.progress.clear();
     return result;
 }
 /* ----------------------------- internals --------------------------------- */

package/dist/persistence/object-storage/reEncryptionSweep.js.map

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

package/dist/persistence/projection/ProjectionActor.d.ts

@@ -1,7 +1,6 @@
 import type { ActorRef } from '../../ActorRef.js';
-import type { PersistentEvent } from '../JournalTypes.js';
-import { type LiveQueryOptions, type PersistenceQuery } from '../query/PersistenceQuery.js';
-import { type OffsetStore } from './OffsetStore.js';
+import type { ByPidProjectionOptions, ByTagProjectionOptions } from './ProjectionOptions.js';
+import type { ActorSystem } from '../../ActorSystem.js';
 /**
  * Actor wrapper around a projection.  Owns the polling loop, the
  * offset cursor, and the at-least-once delivery contract:
@@ -34,29 +33,10 @@ import { type OffsetStore } from './OffsetStore.js';
  * which cancels the polling timer; the in-flight handler call (if
  * any) is awaited before the actor exits.
  */
-export interface ProjectionSettings<E> {
-    /** Logical name — used as the offset-store key prefix. */
-    readonly name: string;
-    /** The query layer (one of `InMemoryQuery`, `SqliteQuery`, …). */
-    readonly query: PersistenceQuery;
-    /** Where to persist the cursor.  Default: in-memory (lost on restart). */
-    readonly offsetStore?: OffsetStore;
-    /** User handler — runs once per event.  Must be idempotent. */
-    readonly handle: (event: PersistentEvent<E>) => void | Promise<void>;
-    /** Tunables passed to the underlying live query. */
-    readonly liveOptions?: LiveQueryOptions;
-}
-export interface ByPidSettings<E> extends ProjectionSettings<E> {
-    readonly persistenceId: string;
-}
-export interface ByTagSettings<E> extends ProjectionSettings<E> {
-    readonly tag: string;
-}
-import type { ActorSystem } from '../../ActorSystem.js';
 export declare class ProjectionActor {
     /** Spawn a per-persistenceId projection.  Returns the actor ref. */
-    static byPersistenceId<E>(system: ActorSystem, settings: ByPidSettings<E>): ActorRef<unknown>;
+    static byPersistenceId<E>(system: ActorSystem, options: ByPidProjectionOptions<E>): ActorRef<unknown>;
     /** Spawn a per-tag projection.  Returns the actor ref. */
-    static byTag<E>(system: ActorSystem, settings: ByTagSettings<E>): ActorRef<unknown>;
+    static byTag<E>(system: ActorSystem, options: ByTagProjectionOptions<E>): ActorRef<unknown>;
 }
 //# sourceMappingURL=ProjectionActor.d.ts.map

package/dist/persistence/projection/ProjectionActor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectionActor.d.ts","sourceRoot":"","sources":["../../../src/persistence/projection/ProjectionActor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,KAAK,gBAAgB,EAErB,KAAK,gBAAgB,EAGtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;CACzC;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,kBAAkB,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,kBAAkB,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAoHD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,qBAAa,eAAe;IAC1B,oEAAoE;IACpE,MAAM,CAAC,eAAe,CAAC,CAAC,EACtB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GACzB,QAAQ,CAAC,OAAO,CAAC;IAOpB,0DAA0D;IAC1D,MAAM,CAAC,KAAK,CAAC,CAAC,EACZ,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GACzB,QAAQ,CAAC,OAAO,CAAC;CAMrB"}
+{"version":3,"file":"ProjectionActor.d.ts","sourceRoot":"","sources":["../../../src/persistence/projection/ProjectionActor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AASlD,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EAIvB,MAAM,wBAAwB,CAAC;AAoHhC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,eAAe;IAC1B,oEAAoE;IACpE,MAAM,CAAC,eAAe,CAAC,CAAC,EACtB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACjC,QAAQ,CAAC,OAAO,CAAC;IAQpB,0DAA0D;IAC1D,MAAM,CAAC,KAAK,CAAC,CAAC,EACZ,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACjC,QAAQ,CAAC,OAAO,CAAC;CAOrB"}

package/dist/persistence/projection/ProjectionActor.js

@@ -104,13 +104,47 @@ class ByTagProjectionActor extends BaseProjectionActor {
 }
 /* ============================ public API ============================== */
 import { Props } from '../../Props.js';
+/**
+ * Actor wrapper around a projection.  Owns the polling loop, the
+ * offset cursor, and the at-least-once delivery contract:
+ *
+ *   1. **preStart** — load the cursor from {@link OffsetStore}.
+ *   2. **loop** — poll the {@link PersistenceQuery} for new events
+ *      from the cursor onwards.
+ *   3. **handle** — call the user `handler` on each event.  The
+ *      handler MUST be idempotent — see at-least-once below.
+ *   4. **commit** — save the cursor to the offset store.
+ *   5. **repeat**.
+ *
+ * **At-least-once.**  If the projection crashes between step 3 and
+ * step 4, the next start replays from the saved cursor and the
+ * just-handled event will be re-handled.  Handlers must therefore
+ * either:
+ *   - be idempotent (e.g. UPSERT into the read model);
+ *   - or do their own dedup via some unique key on the event.
+ *
+ * **Two query shapes are supported via the static factories:**
+ *
+ *   - `ProjectionActor.byPersistenceId(...)` — one cursor per pid.
+ *     Use this for "give me everything an entity ever did".  The
+ *     cursor is the entity's `sequenceNr`.
+ *   - `ProjectionActor.byTag(...)` — one cursor per tag.  Use this
+ *     for "give me every event labelled X across the whole journal".
+ *     The cursor is an `Offset` (timestamp + tiebreakers).
+ *
+ * **Stopping**: the standard `actorRef.stop()` triggers `postStop`
+ * which cancels the polling timer; the in-flight handler call (if
+ * any) is awaited before the actor exits.
+ */
 export class ProjectionActor {
     /** Spawn a per-persistenceId projection.  Returns the actor ref. */
-    static byPersistenceId(system, settings) {
+    static byPersistenceId(system, options) {
+        const settings = options;
         return system.spawn(Props.create(() => new ByPidProjectionActor(settings)), `projection-${settings.name}-${sanitize(settings.persistenceId)}`);
     }
     /** Spawn a per-tag projection.  Returns the actor ref. */
-    static byTag(system, settings) {
+    static byTag(system, options) {
+        const settings = options;
         return system.spawn(Props.create(() => new ByTagProjectionActor(settings)), `projection-${settings.name}-tag-${sanitize(settings.tag)}`);
     }
 }

package/dist/persistence/projection/ProjectionActor.js.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectionActor.js","sourceRoot":"","sources":["../../../src/persistence/projection/ProjectionActor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAIvC,OAAO,EAKL,WAAW,GACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAoB,MAAM,kBAAkB,CAAC;AA0DzE,MAAM,IAAI,GAAoB,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC;AAEvD,MAAe,mBAAuB,SAAQ,KAAsB;IAOnC;IANZ,WAAW,CAAc;IAClC,SAAS,GAAuB,IAAI,CAAC;IACrC,OAAO,GAAG,KAAK,CAAC;IAC1B,6EAA6E;IACnE,aAAa,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAE3D,YAA+B,QAA+B;QAC5D,KAAK,EAAE,CAAC;QADqB,aAAQ,GAAR,QAAQ,CAAuB;QAE5D,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,IAAI,IAAI,mBAAmB,EAAE,CAAC;IACvE,CAAC;IAEQ,KAAK,CAAC,QAAQ;QACrB,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACxB,wDAAwD;QACxD,kEAAkE;QAClE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAEQ,KAAK,CAAC,QAAQ;QACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QACzB,2DAA2D;QAC3D,kEAAkE;QAClE,MAAM,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;IAEQ,KAAK,CAAC,SAAS,CAAC,IAAqB;QAC5C,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,cAAc,IAAI,CAAC,QAAQ,CAAC,IAAI,cAAc,EAAE,GAAG,CAAC,CAAC;QACtE,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC7C,CAAC;IACH,CAAC;IAES,gBAAgB;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,cAAc,IAAI,KAAK,CAAC;QACjE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,GAAG,EAAE;YAChE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC;CAMF;AAED,4EAA4E;AAE5E,MAAM,oBAAwB,SAAQ,mBAAsB;IAE7B;IADrB,MAAM,GAAG,CAAC,CAAC;IACnB,YAA6B,GAAqB;QAAI,KAAK,CAAC,GAAG,CAAC,CAAC;QAApC,QAAG,GAAH,GAAG,CAAkB;IAAgB,CAAC;IAEzD,KAAK,CAAC,UAAU;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC3F,CAAC;IAES,KAAK,CAAC,OAAO;QACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,4BAA4B,CAC9D,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CACxC,CAAC;QACF,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1D,MAAM,IAAI,CAAC,aAAa,CAAC;YACzB,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC;YAC5B,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACxF,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;QAC3B,CAAC;IACH,CAAC;CACF;AAED,4EAA4E;AAE5E,MAAM,oBAAwB,SAAQ,mBAAsB;IAE7B;IADrB,MAAM,GAAW,WAAW,CAAC;IACrC,YAA6B,GAAqB;QAAI,KAAK,CAAC,GAAG,CAAC,CAAC;QAApC,QAAG,GAAH,GAAG,CAAkB;IAAgB,CAAC;IAEzD,KAAK,CAAC,UAAU;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/E,CAAC;IAES,KAAK,CAAC,OAAO;QACrB,MAAM,MAAM,GAAqB,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,kBAAkB,CACtE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAC1B,CAAC;QACF,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,6DAA6D;YAC7D,6DAA6D;YAC7D,6CAA6C;YAC7C,IAAI,EAAE,CAAC,MAAM,CAAC,SAAS,KAAK,IAAI,CAAC,MAAM,CAAC,SAAS;mBAC5C,EAAE,CAAC,MAAM,CAAC,aAAa,KAAK,IAAI,CAAC,MAAM,CAAC,aAAa;mBACrD,EAAE,CAAC,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC,MAAM,CAAC,UAAU;gBAAE,SAAS;YAC/D,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YAChE,MAAM,IAAI,CAAC,aAAa,CAAC;YACzB,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;YACxB,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC5E,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;QAC3B,CAAC;IACH,CAAC;CACF;AAED,4EAA4E;AAE5E,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,MAAM,OAAO,eAAe;IAC1B,oEAAoE;IACpE,MAAM,CAAC,eAAe,CACpB,MAAmB,EACnB,QAA0B;QAE1B,OAAO,MAAM,CAAC,KAAK,CACjB,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,oBAAoB,CAAI,QAAQ,CAA8B,CAAC,EACtF,cAAc,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAClE,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,MAAM,CAAC,KAAK,CACV,MAAmB,EACnB,QAA0B;QAE1B,OAAO,MAAM,CAAC,KAAK,CACjB,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,oBAAoB,CAAI,QAAQ,CAA8B,CAAC,EACtF,cAAc,QAAQ,CAAC,IAAI,QAAQ,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAC5D,CAAC;IACJ,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"ProjectionActor.js","sourceRoot":"","sources":["../../../src/persistence/projection/ProjectionActor.ts"],"names":[],"mappings":"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"}

package/dist/persistence/projection/ProjectionOptions.d.ts

@@ -0,0 +1,109 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import type { PersistentEvent } from '../JournalTypes.js';
+import type { LiveQueryOptions, PersistenceQuery } from '../query/PersistenceQuery.js';
+import type { OffsetStore } from './OffsetStore.js';
+/** Plain settings-object shape shared by every projection. */
+export interface ProjectionOptionsType<E> {
+    /** Logical name — used as the offset-store key prefix. */
+    readonly name: string;
+    /** The query layer (one of `InMemoryQuery`, `SqliteQuery`, …). */
+    readonly query: PersistenceQuery;
+    /** Where to persist the cursor.  Default: in-memory (lost on restart). */
+    readonly offsetStore?: OffsetStore;
+    /** User handler — runs once per event.  Must be idempotent. */
+    readonly handle: (event: PersistentEvent<E>) => void | Promise<void>;
+    /** Tunables passed to the underlying live query. */
+    readonly liveOptions?: LiveQueryOptions;
+}
+/** Settings for a per-persistenceId projection.  One cursor per pid. */
+export interface ByPidProjectionOptionsType<E> extends ProjectionOptionsType<E> {
+    readonly persistenceId: string;
+}
+/** Settings for a per-tag projection.  One cursor per tag. */
+export interface ByTagProjectionOptionsType<E> extends ProjectionOptionsType<E> {
+    readonly tag: string;
+}
+/**
+ * Fluent builder for the fields shared by every projection.  The
+ * concrete {@link ByPidProjectionOptions} / {@link ByTagProjectionOptions}
+ * subclasses add the discriminating cursor field (`persistenceId` / `tag`)
+ * on top of these.
+ */
+export declare class ProjectionOptionsBuilder<E> extends OptionsBuilder<ProjectionOptionsType<E>> {
+    /** Start a fresh builder.  Equivalent to `new ProjectionOptionsBuilder<E>()`. */
+    static create<E>(): ProjectionOptionsBuilder<E>;
+    /** Logical name — used as the offset-store key prefix. */
+    withName(name: string): this;
+    /** The query layer (one of `InMemoryQuery`, `SqliteQuery`, …). */
+    withQuery(query: PersistenceQuery): this;
+    /** Where to persist the cursor.  Default: in-memory (lost on restart). */
+    withOffsetStore(offsetStore: OffsetStore): this;
+    /** User handler — runs once per event.  Must be idempotent. */
+    withHandle(handle: (event: PersistentEvent<E>) => void | Promise<void>): this;
+    /** Tunables passed to the underlying live query. */
+    withLiveOptions(liveOptions: LiveQueryOptions): this;
+}
+/**
+ * Accepted input for a shared projection: the fluent
+ * {@link ProjectionOptionsBuilder} OR a plain {@link ProjectionOptionsType} object.
+ */
+export type ProjectionOptions<E> = ProjectionOptionsBuilder<E> | Partial<ProjectionOptionsType<E>>;
+/** Value alias so `ProjectionOptions.create()` / `new ProjectionOptions()` resolve to the builder. */
+export declare const ProjectionOptions: typeof ProjectionOptionsBuilder;
+/**
+ * Fluent builder for {@link ByPidProjectionOptionsType} — a per-persistenceId
+ * projection.  Adds `withPersistenceId` to the shared projection fields.
+ */
+export declare class ByPidProjectionOptionsBuilder<E> extends OptionsBuilder<ByPidProjectionOptionsType<E>> {
+    /** Start a fresh builder.  Equivalent to `new ByPidProjectionOptionsBuilder<E>()`. */
+    static create<E>(): ByPidProjectionOptionsBuilder<E>;
+    /** Logical name — used as the offset-store key prefix. */
+    withName(name: string): this;
+    /** The query layer (one of `InMemoryQuery`, `SqliteQuery`, …). */
+    withQuery(query: PersistenceQuery): this;
+    /** Where to persist the cursor.  Default: in-memory (lost on restart). */
+    withOffsetStore(offsetStore: OffsetStore): this;
+    /** User handler — runs once per event.  Must be idempotent. */
+    withHandle(handle: (event: PersistentEvent<E>) => void | Promise<void>): this;
+    /** Tunables passed to the underlying live query. */
+    withLiveOptions(liveOptions: LiveQueryOptions): this;
+    /** The entity whose event log this projection follows.  One cursor per pid. */
+    withPersistenceId(persistenceId: string): this;
+}
+/**
+ * Accepted input for a by-persistenceId projection: the fluent
+ * {@link ByPidProjectionOptionsBuilder} OR a plain
+ * {@link ByPidProjectionOptionsType} object.
+ */
+export type ByPidProjectionOptions<E> = ByPidProjectionOptionsBuilder<E> | Partial<ByPidProjectionOptionsType<E>>;
+/** Value alias so `ByPidProjectionOptions.create()` / `new ByPidProjectionOptions()` resolve to the builder. */
+export declare const ByPidProjectionOptions: typeof ByPidProjectionOptionsBuilder;
+/**
+ * Fluent builder for {@link ByTagProjectionOptionsType} — a per-tag projection.
+ * Adds `withTag` to the shared projection fields.
+ */
+export declare class ByTagProjectionOptionsBuilder<E> extends OptionsBuilder<ByTagProjectionOptionsType<E>> {
+    /** Start a fresh builder.  Equivalent to `new ByTagProjectionOptionsBuilder<E>()`. */
+    static create<E>(): ByTagProjectionOptionsBuilder<E>;
+    /** Logical name — used as the offset-store key prefix. */
+    withName(name: string): this;
+    /** The query layer (one of `InMemoryQuery`, `SqliteQuery`, …). */
+    withQuery(query: PersistenceQuery): this;
+    /** Where to persist the cursor.  Default: in-memory (lost on restart). */
+    withOffsetStore(offsetStore: OffsetStore): this;
+    /** User handler — runs once per event.  Must be idempotent. */
+    withHandle(handle: (event: PersistentEvent<E>) => void | Promise<void>): this;
+    /** Tunables passed to the underlying live query. */
+    withLiveOptions(liveOptions: LiveQueryOptions): this;
+    /** The tag this projection follows across the whole journal.  One cursor per tag. */
+    withTag(tag: string): this;
+}
+/**
+ * Accepted input for a by-tag projection: the fluent
+ * {@link ByTagProjectionOptionsBuilder} OR a plain
+ * {@link ByTagProjectionOptionsType} object.
+ */
+export type ByTagProjectionOptions<E> = ByTagProjectionOptionsBuilder<E> | Partial<ByTagProjectionOptionsType<E>>;
+/** Value alias so `ByTagProjectionOptions.create()` / `new ByTagProjectionOptions()` resolve to the builder. */
+export declare const ByTagProjectionOptions: typeof ByTagProjectionOptionsBuilder;
+//# sourceMappingURL=ProjectionOptions.d.ts.map

package/dist/persistence/projection/ProjectionOptions.d.ts.map

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

package/dist/persistence/projection/ProjectionOptions.js

@@ -0,0 +1,108 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/**
+ * Fluent builder for the fields shared by every projection.  The
+ * concrete {@link ByPidProjectionOptions} / {@link ByTagProjectionOptions}
+ * subclasses add the discriminating cursor field (`persistenceId` / `tag`)
+ * on top of these.
+ */
+export class ProjectionOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new ProjectionOptionsBuilder<E>()`. */
+    static create() {
+        return new ProjectionOptionsBuilder();
+    }
+    /** Logical name — used as the offset-store key prefix. */
+    withName(name) {
+        return this.set('name', name);
+    }
+    /** The query layer (one of `InMemoryQuery`, `SqliteQuery`, …). */
+    withQuery(query) {
+        return this.set('query', query);
+    }
+    /** Where to persist the cursor.  Default: in-memory (lost on restart). */
+    withOffsetStore(offsetStore) {
+        return this.set('offsetStore', offsetStore);
+    }
+    /** User handler — runs once per event.  Must be idempotent. */
+    withHandle(handle) {
+        return this.set('handle', handle);
+    }
+    /** Tunables passed to the underlying live query. */
+    withLiveOptions(liveOptions) {
+        return this.set('liveOptions', liveOptions);
+    }
+}
+/** Value alias so `ProjectionOptions.create()` / `new ProjectionOptions()` resolve to the builder. */
+export const ProjectionOptions = ProjectionOptionsBuilder;
+/**
+ * Fluent builder for {@link ByPidProjectionOptionsType} — a per-persistenceId
+ * projection.  Adds `withPersistenceId` to the shared projection fields.
+ */
+export class ByPidProjectionOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new ByPidProjectionOptionsBuilder<E>()`. */
+    static create() {
+        return new ByPidProjectionOptionsBuilder();
+    }
+    /** Logical name — used as the offset-store key prefix. */
+    withName(name) {
+        return this.set('name', name);
+    }
+    /** The query layer (one of `InMemoryQuery`, `SqliteQuery`, …). */
+    withQuery(query) {
+        return this.set('query', query);
+    }
+    /** Where to persist the cursor.  Default: in-memory (lost on restart). */
+    withOffsetStore(offsetStore) {
+        return this.set('offsetStore', offsetStore);
+    }
+    /** User handler — runs once per event.  Must be idempotent. */
+    withHandle(handle) {
+        return this.set('handle', handle);
+    }
+    /** Tunables passed to the underlying live query. */
+    withLiveOptions(liveOptions) {
+        return this.set('liveOptions', liveOptions);
+    }
+    /** The entity whose event log this projection follows.  One cursor per pid. */
+    withPersistenceId(persistenceId) {
+        return this.set('persistenceId', persistenceId);
+    }
+}
+/** Value alias so `ByPidProjectionOptions.create()` / `new ByPidProjectionOptions()` resolve to the builder. */
+export const ByPidProjectionOptions = ByPidProjectionOptionsBuilder;
+/**
+ * Fluent builder for {@link ByTagProjectionOptionsType} — a per-tag projection.
+ * Adds `withTag` to the shared projection fields.
+ */
+export class ByTagProjectionOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new ByTagProjectionOptionsBuilder<E>()`. */
+    static create() {
+        return new ByTagProjectionOptionsBuilder();
+    }
+    /** Logical name — used as the offset-store key prefix. */
+    withName(name) {
+        return this.set('name', name);
+    }
+    /** The query layer (one of `InMemoryQuery`, `SqliteQuery`, …). */
+    withQuery(query) {
+        return this.set('query', query);
+    }
+    /** Where to persist the cursor.  Default: in-memory (lost on restart). */
+    withOffsetStore(offsetStore) {
+        return this.set('offsetStore', offsetStore);
+    }
+    /** User handler — runs once per event.  Must be idempotent. */
+    withHandle(handle) {
+        return this.set('handle', handle);
+    }
+    /** Tunables passed to the underlying live query. */
+    withLiveOptions(liveOptions) {
+        return this.set('liveOptions', liveOptions);
+    }
+    /** The tag this projection follows across the whole journal.  One cursor per tag. */
+    withTag(tag) {
+        return this.set('tag', tag);
+    }
+}
+/** Value alias so `ByTagProjectionOptions.create()` / `new ByTagProjectionOptions()` resolve to the builder. */
+export const ByTagProjectionOptions = ByTagProjectionOptionsBuilder;
+//# sourceMappingURL=ProjectionOptions.js.map

package/dist/persistence/projection/ProjectionOptions.js.map

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

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

@@ -1,22 +1,14 @@
-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;
-}
+import type { CachedSnapshotStoreOptions } from './CachedSnapshotStoreOptions.js';
 export declare class CachedSnapshotStore implements SnapshotStore {
     private readonly underlying;
     private readonly cache;
     private readonly ttlMs;
     private readonly keyPrefix;
-    constructor(underlying: SnapshotStore, opts: CachedSnapshotStoreOptions);
+    constructor(underlying: SnapshotStore, options: 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>>>;

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

@@ -1 +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"}
+{"version":3,"file":"CachedSnapshotStore.d.ts","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/CachedSnapshotStore.ts"],"names":[],"mappings":"AACA,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;AAC/D,OAAO,KAAK,EAAE,0BAA0B,EAAkC,MAAM,iCAAiC,CAAC;AA8ClH,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,OAAO,EAAE,0BAA0B;IAY/B,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

@@ -26,8 +26,11 @@ import { none, some } from '../../util/Option.js';
  * 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 });
+ *   const cassandra = new CassandraSnapshotStore(...);
+ *   const cached    = new CachedSnapshotStore(
+ *     cassandra,
+ *     CachedSnapshotStoreOptions.create().withCache(cache).withTtlMs(5 * 60_000),
+ *   );
  *   ext.setSnapshotStore(cached);
  */
 const DEFAULT_TTL_MS = 5 * 60_000;
@@ -36,14 +39,17 @@ export class CachedSnapshotStore {
     cache;
     ttlMs;
     keyPrefix;
-    constructor(underlying, opts) {
+    constructor(underlying, options) {
         this.underlying = underlying;
-        this.cache = opts.cache;
-        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        const s = options;
+        if (s.cache === undefined)
+            throw new Error('CachedSnapshotStore: cache is required (call withCache()).');
+        this.cache = s.cache;
+        this.ttlMs = s.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:';
+        this.keyPrefix = s.keyPrefix ?? 'snap:';
     }
     async save(pid, seq, state, options) {
         const written = await this.underlying.save(pid, seq, state, options);

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

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

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

@@ -0,0 +1,37 @@
+import type { Cache } from '../../cache/Cache.js';
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+export interface CachedSnapshotStoreOptionsType {
+    /** 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;
+}
+/**
+ * Fluent builder for {@link CachedSnapshotStoreOptionsType}.  The `cache` is
+ * required:
+ *
+ *     new CachedSnapshotStore(
+ *       underlying,
+ *       CachedSnapshotStoreOptions.create().withCache(cache).withTtlMs(5 * 60_000),
+ *     )
+ */
+export declare class CachedSnapshotStoreOptionsBuilder extends OptionsBuilder<CachedSnapshotStoreOptionsType> {
+    /** Start a fresh builder.  Equivalent to `new CachedSnapshotStoreOptionsBuilder()`. */
+    static create(): CachedSnapshotStoreOptionsBuilder;
+    /** Backing cache — typically Redis in production. */
+    withCache(cache: Cache): this;
+    /** Cache TTL in milliseconds.  Default: 5 minutes. */
+    withTtlMs(ttlMs: number): this;
+    /** Key prefix (default: `'snap:'`) — prevents collisions in shared caches. */
+    withKeyPrefix(keyPrefix: string): this;
+}
+/**
+ * Accepted input for the cached snapshot-store constructor: the fluent
+ * {@link CachedSnapshotStoreOptionsBuilder} OR a plain {@link CachedSnapshotStoreOptionsType} object.
+ */
+export type CachedSnapshotStoreOptions = CachedSnapshotStoreOptionsBuilder | Partial<CachedSnapshotStoreOptionsType>;
+/** Value alias so `CachedSnapshotStoreOptions.create()` / `new CachedSnapshotStoreOptions()` resolve to the builder. */
+export declare const CachedSnapshotStoreOptions: typeof CachedSnapshotStoreOptionsBuilder;
+//# sourceMappingURL=CachedSnapshotStoreOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CachedSnapshotStoreOptions.d.ts","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/CachedSnapshotStoreOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,MAAM,WAAW,8BAA8B;IAC7C,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;AAED;;;;;;;;GAQG;AACH,qBAAa,iCAAkC,SAAQ,cAAc,CAAC,8BAA8B,CAAC;IACnG,uFAAuF;IACvF,MAAM,CAAC,MAAM,IAAI,iCAAiC;IAIlD,qDAAqD;IACrD,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAI7B,sDAAsD;IACtD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9B,8EAA8E;IAC9E,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAGvC;AAED;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,iCAAiC,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAAC;AACrH,wHAAwH;AACxH,eAAO,MAAM,0BAA0B,0CAAoC,CAAC"}