actor-ts 0.9.0

package/dist/persistence/object-storage/reEncryptionSweep.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Operator tool for master-key rotation (#70).
+ *
+ * Background: client-side encryption stamps a 1-byte key version into the
+ * body manifest (#8).  When a deployment rotates the master key, the new
+ * key becomes `active`, the old one moves to `retired`, and historical
+ * bodies stay readable because the decoder dispatches on the version.
+ * That's fine forever — until the operator wants to **drop** the retired
+ * key from the config (e.g. to revoke the leaked one, or to clear the
+ * way for the next rotation).  That requires every historical body to
+ * be re-encrypted under the active key first.
+ *
+ * `reEncryptObjectStorage` is the sweep: it walks every key under a
+ * prefix in the underlying `ObjectStorageBackend`, decrypts each body
+ * via the keyring (any retired version still works), and re-encrypts
+ * under the active key.  Bodies already at the active version are
+ * skipped on the fast path (one GET, no PUT), so the sweep is idempotent
+ * — re-running it after a successful run is a no-op.
+ *
+ * The helper operates one level below `ObjectStorageSnapshotStore` /
+ * `ObjectStorageDurableStateStore` because per-pid HKDF salting means
+ * the pid must be known at decrypt + re-encrypt time.  The default
+ * `pidFromKey` extractor matches the layout both built-in stores use
+ * (`<prefix><pid>/...`).
+ */
+import type { MasterKeyRing } from '../PersistenceOptions.js';
+import type { ObjectStorageBackend } from './ObjectStorageBackend.js';
+export interface ReEncryptOptions {
+    /** Common key prefix to sweep (e.g. `'snapshots/'` or `'state/'`). */
+    readonly keyPrefix: string;
+    /**
+     * Keyring containing the currently active key plus every retired
+     * version the corpus may have been encrypted under.  Without a
+     * retired entry for a version, that body's decrypt will fail.
+     */
+    readonly keyring: MasterKeyRing;
+    /**
+     * HKDF `info` string — must match the one the encrypting store used
+     * (defaults to `actor-ts/snapshot/v1`, identical to {@link deriveSubkey}'s
+     * default).  Override if you customised it at the original encrypt
+     * site.
+     */
+    readonly info?: string;
+    /**
+     * Extracts the `persistenceId` from a backend key.  HKDF uses the
+     * pid as a per-pid salt, so the sweep needs to recover it from the
+     * key in order to derive the same subkey the original encrypter did.
+     *
+     * Default: `<keyPrefix><pid>/<rest>` — picks the next path segment
+     * after the prefix.  Works for the layouts both built-in object-
+     * storage stores use; override for custom layouts.
+     */
+    readonly pidFromKey?: (key: string, keyPrefix: string) => string;
+    /**
+     * Optional progress hook called after each object is processed.  Use
+     * it to log to stderr / write a progress file / surface to an
+     * operator dashboard for long-running sweeps.
+     */
+    readonly onProgress?: (event: ReEncryptProgress) => void;
+    /**
+     * When set, skip objects whose key matches this predicate.  Useful
+     * for excluding manifest files or other non-body objects that share
+     * the prefix.  Default: process every key.
+     */
+    readonly skip?: (key: string) => boolean;
+}
+export interface ReEncryptProgress {
+    readonly key: string;
+    readonly idx: number;
+    readonly total: number;
+    readonly action: 'rewrote' | 'skipped-current' | 'skipped-unencrypted' | 'skipped-non-ats1';
+}
+export interface ReEncryptResult {
+    /** Total objects examined. */
+    readonly scanned: number;
+    /** Objects that were re-encrypted to the active key. */
+    readonly rewrote: number;
+    /**
+     * Objects skipped because they were already at the active version
+     * (the idempotent fast-path).
+     */
+    readonly skippedCurrent: number;
+    /** Objects skipped because they were never encrypted. */
+    readonly skippedUnencrypted: number;
+    /** Objects skipped because they aren't `ATS1`-framed (e.g. raw user blobs). */
+    readonly skippedNonAts1: number;
+}
+/**
+ * Re-encrypt every body under `keyPrefix` to the active key in `keyring`.
+ *
+ * Idempotent: a body already at the active version is skipped without a
+ * PUT.  Safe to interrupt and resume — there's no progress state on
+ * disk; a resumed sweep simply re-checks every key and re-skips the
+ * ones already at the active version.
+ *
+ * Per-object failures (decrypt errors, backend faults) are NOT swallowed
+ * — they bubble up immediately and stop the sweep.  Run the sweep again
+ * after fixing the underlying issue; already-rewritten objects are
+ * idempotent on the next pass.
+ *
+ *   const result = await reEncryptObjectStorage(backend, {
+ *     keyPrefix: 'snapshots/',
+ *     keyring: { active: { version: 2, key: newKey },
+ *                retired: [{ version: 1, key: oldKey }] },
+ *     onProgress: (e) => process.stderr.write(`${e.idx}/${e.total} ${e.key}\n`),
+ *   });
+ *   console.log(`re-encrypted ${result.rewrote} of ${result.scanned}`);
+ */
+export declare function reEncryptObjectStorage(backend: ObjectStorageBackend, opts: ReEncryptOptions): Promise<ReEncryptResult>;
+//# sourceMappingURL=reEncryptionSweep.d.ts.map

package/dist/persistence/object-storage/reEncryptionSweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reEncryptionSweep.d.ts","sourceRoot":"","sources":["../../../src/persistence/object-storage/reEncryptionSweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAQ9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAItE,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACzD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,GAAG,qBAAqB,GAAG,kBAAkB,CAAC;CAC7F;AAED,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,eAAe,CAAC,CA2F1B"}

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

@@ -0,0 +1,157 @@
+/**
+ * Operator tool for master-key rotation (#70).
+ *
+ * Background: client-side encryption stamps a 1-byte key version into the
+ * body manifest (#8).  When a deployment rotates the master key, the new
+ * key becomes `active`, the old one moves to `retired`, and historical
+ * bodies stay readable because the decoder dispatches on the version.
+ * That's fine forever — until the operator wants to **drop** the retired
+ * key from the config (e.g. to revoke the leaked one, or to clear the
+ * way for the next rotation).  That requires every historical body to
+ * be re-encrypted under the active key first.
+ *
+ * `reEncryptObjectStorage` is the sweep: it walks every key under a
+ * prefix in the underlying `ObjectStorageBackend`, decrypts each body
+ * via the keyring (any retired version still works), and re-encrypts
+ * under the active key.  Bodies already at the active version are
+ * skipped on the fast path (one GET, no PUT), so the sweep is idempotent
+ * — re-running it after a successful run is a no-op.
+ *
+ * The helper operates one level below `ObjectStorageSnapshotStore` /
+ * `ObjectStorageDurableStateStore` because per-pid HKDF salting means
+ * the pid must be known at decrypt + re-encrypt time.  The default
+ * `pidFromKey` extractor matches the layout both built-in stores use
+ * (`<prefix><pid>/...`).
+ */
+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"
+/**
+ * Re-encrypt every body under `keyPrefix` to the active key in `keyring`.
+ *
+ * Idempotent: a body already at the active version is skipped without a
+ * PUT.  Safe to interrupt and resume — there's no progress state on
+ * disk; a resumed sweep simply re-checks every key and re-skips the
+ * ones already at the active version.
+ *
+ * Per-object failures (decrypt errors, backend faults) are NOT swallowed
+ * — they bubble up immediately and stop the sweep.  Run the sweep again
+ * after fixing the underlying issue; already-rewritten objects are
+ * idempotent on the next pass.
+ *
+ *   const result = await reEncryptObjectStorage(backend, {
+ *     keyPrefix: 'snapshots/',
+ *     keyring: { active: { version: 2, key: newKey },
+ *                retired: [{ version: 1, key: oldKey }] },
+ *     onProgress: (e) => process.stderr.write(`${e.idx}/${e.total} ${e.key}\n`),
+ *   });
+ *   console.log(`re-encrypted ${result.rewrote} of ${result.scanned}`);
+ */
+export async function reEncryptObjectStorage(backend, opts) {
+    const items = await backend.list({ prefix: opts.keyPrefix });
+    const pidFromKey = opts.pidFromKey ?? defaultPidFromKey;
+    const result = {
+        scanned: 0,
+        rewrote: 0,
+        skippedCurrent: 0,
+        skippedUnencrypted: 0,
+        skippedNonAts1: 0,
+    };
+    const activeVersion = opts.keyring.active.version;
+    if (!Number.isInteger(activeVersion) || activeVersion < 0 || activeVersion > 255) {
+        throw new Error(`reEncryptObjectStorage: keyring.active.version must be an integer in [0, 255], got ${activeVersion}`);
+    }
+    const total = items.length;
+    for (let idx = 0; idx < total; idx++) {
+        const item = items[idx];
+        if (opts.skip?.(item.key))
+            continue;
+        result.scanned += 1;
+        const fetched = await backend.get(item.key);
+        if (fetched.isNone()) {
+            // List/get race — object was deleted under us.  Treat as
+            // skipped and move on.
+            continue;
+        }
+        const framed = fetched.value.body;
+        if (!startsWithAts1(framed)) {
+            result.skippedNonAts1 += 1;
+            opts.onProgress?.({ key: item.key, idx, total, action: 'skipped-non-ats1' });
+            continue;
+        }
+        const flags = framed[4];
+        const encrypted = (flags & FLAG_ENCRYPTED) !== 0;
+        if (!encrypted) {
+            result.skippedUnencrypted += 1;
+            opts.onProgress?.({ key: item.key, idx, total, action: 'skipped-unencrypted' });
+            continue;
+        }
+        const versioned = (flags & FLAG_KEY_VERSIONED) !== 0;
+        const bodyVersion = versioned ? framed[5] : 0;
+        if (bodyVersion === activeVersion && versioned) {
+            // Already at the active version with the new framing — nothing
+            // to do.  Bodies in the legacy unversioned format are NOT
+            // considered "at version 0" for skip purposes — we still rewrite
+            // them so the corpus ends up uniformly versioned.
+            result.skippedCurrent += 1;
+            opts.onProgress?.({ key: item.key, idx, total, action: 'skipped-current' });
+            continue;
+        }
+        const pid = pidFromKey(item.key, opts.keyPrefix);
+        const info = opts.info ?? 'actor-ts/snapshot/v1';
+        // Decrypt with whatever retired/active key matches the body's version.
+        const decoded = await decodeBody(framed, {
+            encryption: {
+                subKeyFor: async (v) => {
+                    if (opts.keyring.active.version === v) {
+                        return deriveSubkey(opts.keyring.active.key, pid, info);
+                    }
+                    const retired = opts.keyring.retired?.find((r) => r.version === v);
+                    return retired ? deriveSubkey(retired.key, pid, info) : null;
+                },
+            },
+        });
+        // Re-encrypt with the active key + active version stamp.
+        const activeSubkey = await deriveSubkey(opts.keyring.active.key, pid, info);
+        const rewritten = await encodeBody(decoded.payload, {
+            compression: decoded.compression,
+            encryption: { subKey: activeSubkey, keyVersion: activeVersion },
+        });
+        // Use If-Match to detect a concurrent writer — if someone else
+        // updated this key while we were re-encrypting, our rewrite would
+        // clobber their newer content.  Bubble the conflict up so the
+        // operator can decide (typically: re-run the sweep, the new write
+        // will already be at the active version).
+        await backend.put(item.key, rewritten, {
+            ...(fetched.value.contentType ? { contentType: fetched.value.contentType } : {}),
+            ...(fetched.value.contentEncoding ? { contentEncoding: fetched.value.contentEncoding } : {}),
+            ifMatch: fetched.value.etag,
+        });
+        result.rewrote += 1;
+        opts.onProgress?.({ key: item.key, idx, total, action: 'rewrote' });
+    }
+    return result;
+}
+/* ----------------------------- internals --------------------------------- */
+function startsWithAts1(buf) {
+    return buf.length >= 5
+        && buf[0] === ATS1_MAGIC_PREFIX[0]
+        && buf[1] === ATS1_MAGIC_PREFIX[1]
+        && buf[2] === ATS1_MAGIC_PREFIX[2]
+        && buf[3] === ATS1_MAGIC_PREFIX[3];
+}
+/**
+ * Default pid extractor for the layouts the built-in object-storage
+ * stores use: `<keyPrefix><pid>/<rest>`.  Returns the substring
+ * between the prefix and the next `/`.  Used as the HKDF salt at
+ * decrypt + re-encrypt time, so it MUST match what the original
+ * write site used.
+ */
+function defaultPidFromKey(key, keyPrefix) {
+    let start = 0;
+    if (key.startsWith(keyPrefix))
+        start = keyPrefix.length;
+    const slash = key.indexOf('/', start);
+    return slash < 0 ? key.slice(start) : key.slice(start, slash);
+}
+//# sourceMappingURL=reEncryptionSweep.js.map

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

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

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

@@ -0,0 +1,69 @@
+import type { DurableStateStore } from '../DurableStateStore.js';
+import { type Offset } from '../query/PersistenceQuery.js';
+/**
+ * Per-projection persistent cursor.  The {@link ProjectionActor}
+ * loads the offset on `preStart` and writes it back after every
+ * successfully-handled event.  The pair of (load → handle event →
+ * save) gives at-least-once delivery: the same event can be re-handled
+ * if the projection crashes between handle and save, which is exactly
+ * why projection handlers must be idempotent.
+ *
+ * Two flavours of cursor are stored: a simple integer
+ * (sequence-based, used by `eventsByPersistenceId`) and the composite
+ * {@link Offset} (timestamp-based, used by `eventsByTag`).  The store
+ * persists both as plain JSON so the underlying backend doesn't need
+ * to know about the difference.
+ */
+export interface OffsetStore {
+    loadSequence(projectionName: string, persistenceId: string): Promise<number>;
+    saveSequence(projectionName: string, persistenceId: string, seqNr: number): Promise<void>;
+    loadOffset(projectionName: string, tag: string): Promise<Offset>;
+    saveOffset(projectionName: string, tag: string, offset: Offset): Promise<void>;
+    /** Forget every cursor for `projectionName`.  Used by tests + reset tooling. */
+    clear(projectionName: string): Promise<void>;
+}
+/**
+ * Reference offset store — keeps cursors in a process-local Map.  Use
+ * this for tests or for projections whose offsets you're happy to
+ * lose on restart (i.e. the projection always replays the full
+ * stream).  Not thread-safe across processes.
+ */
+export declare class InMemoryOffsetStore implements OffsetStore {
+    private readonly seq;
+    private readonly off;
+    loadSequence(projection: string, pid: string): Promise<number>;
+    saveSequence(projection: string, pid: string, seqNr: number): Promise<void>;
+    loadOffset(projection: string, tag: string): Promise<Offset>;
+    saveOffset(projection: string, tag: string, offset: Offset): Promise<void>;
+    clear(projection: string): Promise<void>;
+}
+/**
+ * Persists offsets via any {@link DurableStateStore} — meaning
+ * SQLite, Cassandra, S3, filesystem, all become valid offset stores
+ * for free, just by reusing the existing plug-in.  Each projection's
+ * offsets land under a single durable-state record per
+ * (projection, kind) combination, encoded as plain JSON.
+ *
+ * The revision-based optimistic-concurrency on `DurableStateStore`
+ * ensures two concurrent projection instances don't race their
+ * cursor writes — the store rejects any save that doesn't carry the
+ * caller's expected revision.  The {@link ProjectionActor} itself is
+ * single-instance per projection name (or per (projection, shard) in
+ * the cluster-wide variant), so contention is the exception, not the
+ * rule.
+ */
+export declare class DurableStateOffsetStore implements OffsetStore {
+    private readonly store;
+    private readonly cache;
+    constructor(store: DurableStateStore);
+    loadSequence(projection: string, pid: string): Promise<number>;
+    saveSequence(projection: string, pid: string, seqNr: number): Promise<void>;
+    loadOffset(projection: string, tag: string): Promise<Offset>;
+    saveOffset(projection: string, tag: string, offset: Offset): Promise<void>;
+    clear(projection: string): Promise<void>;
+    private seqKey;
+    private offKey;
+    private load;
+    private save;
+}
+//# sourceMappingURL=OffsetStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OffsetStore.d.ts","sourceRoot":"","sources":["../../../src/persistence/projection/OffsetStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAe,KAAK,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAExE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1F,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/E,gFAAgF;IAChF,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAID;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0C;IAC9D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0C;IAExD,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAG9D,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3E,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAG5D,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1E,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAI/C;AAID;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAwB,YAAW,WAAW;IAG7C,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2C;gBAEpC,KAAK,EAAE,iBAAiB;IAE/C,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3E,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5D,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1E,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9C,OAAO,CAAC,MAAM;IAGd,OAAO,CAAC,MAAM;YAIA,IAAI;YAOJ,IAAI;CAKnB"}

package/dist/persistence/projection/OffsetStore.js

@@ -0,0 +1,103 @@
+import { offsetStart } from '../query/PersistenceQuery.js';
+/* ============================ in-memory ============================== */
+/**
+ * Reference offset store — keeps cursors in a process-local Map.  Use
+ * this for tests or for projections whose offsets you're happy to
+ * lose on restart (i.e. the projection always replays the full
+ * stream).  Not thread-safe across processes.
+ */
+export class InMemoryOffsetStore {
+    seq = new Map();
+    off = new Map();
+    async loadSequence(projection, pid) {
+        return this.seq.get(projection)?.get(pid) ?? 0;
+    }
+    async saveSequence(projection, pid, seqNr) {
+        let inner = this.seq.get(projection);
+        if (!inner) {
+            inner = new Map();
+            this.seq.set(projection, inner);
+        }
+        inner.set(pid, seqNr);
+    }
+    async loadOffset(projection, tag) {
+        return this.off.get(projection)?.get(tag) ?? offsetStart;
+    }
+    async saveOffset(projection, tag, offset) {
+        let inner = this.off.get(projection);
+        if (!inner) {
+            inner = new Map();
+            this.off.set(projection, inner);
+        }
+        inner.set(tag, offset);
+    }
+    async clear(projection) {
+        this.seq.delete(projection);
+        this.off.delete(projection);
+    }
+}
+/* =========================== durable-state =========================== */
+/**
+ * Persists offsets via any {@link DurableStateStore} — meaning
+ * SQLite, Cassandra, S3, filesystem, all become valid offset stores
+ * for free, just by reusing the existing plug-in.  Each projection's
+ * offsets land under a single durable-state record per
+ * (projection, kind) combination, encoded as plain JSON.
+ *
+ * The revision-based optimistic-concurrency on `DurableStateStore`
+ * ensures two concurrent projection instances don't race their
+ * cursor writes — the store rejects any save that doesn't carry the
+ * caller's expected revision.  The {@link ProjectionActor} itself is
+ * single-instance per projection name (or per (projection, shard) in
+ * the cluster-wide variant), so contention is the exception, not the
+ * rule.
+ */
+export class DurableStateOffsetStore {
+    store;
+    cache = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    async loadSequence(projection, pid) {
+        const rec = await this.load(this.seqKey(projection, pid));
+        return rec?.value ?? 0;
+    }
+    async saveSequence(projection, pid, seqNr) {
+        await this.save(this.seqKey(projection, pid), { value: seqNr });
+    }
+    async loadOffset(projection, tag) {
+        const rec = await this.load(this.offKey(projection, tag));
+        return rec ?? offsetStart;
+    }
+    async saveOffset(projection, tag, offset) {
+        await this.save(this.offKey(projection, tag), offset);
+    }
+    async clear(projection) {
+        for (const key of Array.from(this.cache.keys())) {
+            if (key.startsWith(`${projection}|`)) {
+                await this.store.delete(key);
+                this.cache.delete(key);
+            }
+        }
+    }
+    /* ------------------------------ internals ----------------------------- */
+    seqKey(projection, pid) {
+        return `${projection}|seq|${pid}`;
+    }
+    offKey(projection, tag) {
+        return `${projection}|tag|${tag}`;
+    }
+    async load(key) {
+        const opt = await this.store.load(key);
+        if (opt.isNone())
+            return null;
+        this.cache.set(key, { revision: opt.value.revision });
+        return opt.value.state;
+    }
+    async save(key, state) {
+        const expected = this.cache.get(key)?.revision ?? 0;
+        const next = await this.store.upsert(key, expected, state);
+        this.cache.set(key, { revision: next.revision });
+    }
+}
+//# sourceMappingURL=OffsetStore.js.map

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

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

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

@@ -0,0 +1,62 @@
+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';
+/**
+ * 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 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>;
+    /** Spawn a per-tag projection.  Returns the actor ref. */
+    static byTag<E>(system: ActorSystem, settings: ByTagSettings<E>): ActorRef<unknown>;
+}
+//# sourceMappingURL=ProjectionActor.d.ts.map

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

@@ -0,0 +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"}

package/dist/persistence/projection/ProjectionActor.js

@@ -0,0 +1,120 @@
+import { Actor } from '../../Actor.js';
+import { offsetStart, } from '../query/PersistenceQuery.js';
+import { InMemoryOffsetStore } from './OffsetStore.js';
+const TICK = { _: 'projection-tick' };
+class BaseProjectionActor extends Actor {
+    settings;
+    offsetStore;
+    pollTimer = null;
+    stopped = false;
+    /** Resolves when the in-flight handler completes — preserved across stop. */
+    currentHandle = Promise.resolve();
+    constructor(settings) {
+        super();
+        this.settings = settings;
+        this.offsetStore = settings.offsetStore ?? new InMemoryOffsetStore();
+    }
+    async preStart() {
+        await this.loadCursor();
+        // Kick the loop off immediately — we don't want to wait
+        // pollIntervalMs to deliver the *first* batch of historic events.
+        this.self.tell(TICK);
+    }
+    async postStop() {
+        this.stopped = true;
+        this.pollTimer?.cancel();
+        // Make sure any in-flight handler call finishes before the
+        // mailbox shuts down — otherwise we'd lose the just-saved cursor.
+        await this.currentHandle;
+    }
+    async onReceive(_msg) {
+        if (this.stopped)
+            return;
+        try {
+            await this.runOnce();
+        }
+        catch (err) {
+            this.log.error(`projection ${this.settings.name} tick failed`, err);
+        }
+        finally {
+            if (!this.stopped)
+                this.scheduleNextTick();
+        }
+    }
+    scheduleNextTick() {
+        const delay = this.settings.liveOptions?.pollIntervalMs ?? 1_000;
+        this.pollTimer?.cancel();
+        this.pollTimer = this.system.scheduler.scheduleOnceFn(delay, () => {
+            this.self.tell(TICK);
+        });
+    }
+}
+/* ------------------------------ by pid -------------------------------- */
+class ByPidProjectionActor extends BaseProjectionActor {
+    cfg;
+    cursor = 0;
+    constructor(cfg) {
+        super(cfg);
+        this.cfg = cfg;
+    }
+    async loadCursor() {
+        this.cursor = await this.offsetStore.loadSequence(this.cfg.name, this.cfg.persistenceId);
+    }
+    async runOnce() {
+        const events = await this.cfg.query.currentEventsByPersistenceId(this.cfg.persistenceId, this.cursor + 1);
+        for (const ev of events) {
+            this.currentHandle = Promise.resolve(this.cfg.handle(ev));
+            await this.currentHandle;
+            this.cursor = ev.sequenceNr;
+            await this.offsetStore.saveSequence(this.cfg.name, this.cfg.persistenceId, this.cursor);
+            if (this.stopped)
+                return;
+        }
+    }
+}
+/* ------------------------------ by tag -------------------------------- */
+class ByTagProjectionActor extends BaseProjectionActor {
+    cfg;
+    cursor = offsetStart;
+    constructor(cfg) {
+        super(cfg);
+        this.cfg = cfg;
+    }
+    async loadCursor() {
+        this.cursor = await this.offsetStore.loadOffset(this.cfg.name, this.cfg.tag);
+    }
+    async runOnce() {
+        const events = await this.cfg.query.currentEventsByTag(this.cfg.tag, this.cursor);
+        for (const te of events) {
+            // Skip the event we already committed last round (the cursor
+            // is inclusive on load to support fresh-start replay, but on
+            // subsequent rounds we want strictly-after).
+            if (te.offset.timestamp === this.cursor.timestamp
+                && te.offset.persistenceId === this.cursor.persistenceId
+                && te.offset.sequenceNr === this.cursor.sequenceNr)
+                continue;
+            this.currentHandle = Promise.resolve(this.cfg.handle(te.event));
+            await this.currentHandle;
+            this.cursor = te.offset;
+            await this.offsetStore.saveOffset(this.cfg.name, this.cfg.tag, this.cursor);
+            if (this.stopped)
+                return;
+        }
+    }
+}
+/* ============================ public API ============================== */
+import { Props } from '../../Props.js';
+export class ProjectionActor {
+    /** Spawn a per-persistenceId projection.  Returns the actor ref. */
+    static byPersistenceId(system, settings) {
+        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) {
+        return system.spawn(Props.create(() => new ByTagProjectionActor(settings)), `projection-${settings.name}-tag-${sanitize(settings.tag)}`);
+    }
+}
+function sanitize(name) {
+    return name.replace(/[^A-Za-z0-9_\-]/g, '_').slice(0, 64);
+}
+//# sourceMappingURL=ProjectionActor.js.map