actor-ts 0.9.0

package/dist/persistence/journals/CassandraJournal.js

@@ -0,0 +1,247 @@
+import { JournalConcurrencyError, JournalError, } from '../JournalTypes.js';
+import { createCassandraClient, keyspaceDdl, } from './CassandraClient.js';
+/**
+ * Journal backed by Apache Cassandra or ScyllaDB — same CQL protocol, one
+ * plug-in serves both.  Schema:
+ *   - composite partition key `(persistence_id, partition_nr)` — keeps
+ *     individual partitions bounded even for long-lived event streams;
+ *   - clustering column `sequence_nr` for in-stream ordering;
+ *   - a small metadata row per persistence_id tracking `max_sequence_nr`.
+ *
+ * The journal relies on a *single writer per persistence id* — the
+ * standard PersistentActor contract, one instance per id at a time.
+ * Under that assumption the "read max-seq → append → write max-seq"
+ * sequence is safe without server-side LWT.  If you need multi-writer
+ * safety, wrap the metadata update in an LWT (`IF max_sequence_nr = ?`).
+ */
+export class CassandraJournal {
+    options;
+    client;
+    /** True once `ensureStarted()` has run keyspace + table DDL. */
+    started = false;
+    /** Toggle so shutdown only happens once. */
+    stopped = false;
+    /** Only shut down the client if WE created it — don't close someone else's. */
+    ownsClient;
+    constructor(options) {
+        this.options = options;
+        this.client = options.client ?? undefined;
+        this.ownsClient = !options.client;
+    }
+    /** Explicitly connect + ensure schema.  Called lazily on first use. */
+    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 append(pid, events, expectedSeq, tags) {
+        if (events.length === 0)
+            return [];
+        await this.ensureStarted();
+        // 1) Read current max-seq from metadata; throw on mismatch.
+        const actualSeq = await this.readHighestSeq(pid);
+        if (actualSeq !== expectedSeq) {
+            throw new JournalConcurrencyError(pid, expectedSeq, actualSeq);
+        }
+        const now = Date.now();
+        const partitionSize = this.options.partitionSize ?? 500_000;
+        const tagList = tags ? Array.from(tags) : null;
+        const written = [];
+        // 2) Batch INSERT events.  We use a logged batch only if every insert
+        //    lands in the same partition — otherwise Cassandra logs a warning.
+        //    To keep it simple we build one batch per partition.
+        let batchPartition = null;
+        let batchOps = [];
+        const flush = async () => {
+            if (batchOps.length === 0)
+                return;
+            try {
+                await this.client.batch(batchOps, { prepare: true, logged: false });
+            }
+            catch (e) {
+                throw new JournalError(`CassandraJournal.append: batch failed: ${e.message}`, e);
+            }
+            batchOps = [];
+            batchPartition = null;
+        };
+        let seq = actualSeq;
+        for (const ev of events) {
+            seq++;
+            const partition = Math.floor((seq - 1) / partitionSize);
+            if (batchPartition !== null && partition !== batchPartition)
+                await flush();
+            batchPartition = partition;
+            const payload = JSON.stringify(ev);
+            batchOps.push({
+                query: `INSERT INTO ${this.qualified(this.eventsTable)} (persistence_id, partition_nr, sequence_nr, timestamp, payload, tags) VALUES (?, ?, ?, ?, ?, ?)`,
+                params: [pid, partition, seq, now, payload, tagList],
+            });
+            // Tag-index side-table dual-write (#44).  One row per (event, tag)
+            // pair so a tag-query walks a single (tag) partition.  Each row
+            // also carries the full tag set, letting `CassandraQuery` JS-
+            // refine multi-tag filters without a follow-up read.
+            if (this.options.useTagIndex && tagList && tagList.length > 0) {
+                for (const tag of tagList) {
+                    batchOps.push({
+                        query: `INSERT INTO ${this.qualified(this.tagIndexTable)} (tag, timestamp, persistence_id, sequence_nr, payload, tags) VALUES (?, ?, ?, ?, ?, ?)`,
+                        params: [tag, now, pid, seq, payload, tagList],
+                    });
+                }
+            }
+            written.push({
+                persistenceId: pid,
+                sequenceNr: seq,
+                event: ev,
+                timestamp: now,
+                tags: tagList ? [...tagList] : undefined,
+            });
+        }
+        await flush();
+        // 3) Upsert the metadata row with the new max-seq.
+        try {
+            await this.client.execute(`INSERT INTO ${this.qualified(this.metadataTable)} (persistence_id, max_sequence_nr, updated_at) VALUES (?, ?, ?)`, [pid, seq, now], { prepare: true });
+        }
+        catch (e) {
+            throw new JournalError(`CassandraJournal.append: metadata update failed: ${e.message}`, e);
+        }
+        // 4) Index the persistence id so `persistenceIds()` can enumerate them.
+        //    Skipped on re-inserts thanks to the PK — no-ops are free.
+        if (actualSeq === 0) {
+            try {
+                await this.client.execute(`INSERT INTO ${this.qualified(this.allIdsTable)} (tag, persistence_id) VALUES (?, ?)`, ['_all', pid], { prepare: true });
+            }
+            catch { /* non-fatal — listing is best-effort */ }
+        }
+        return written;
+    }
+    async read(pid, fromSeq, toSeq) {
+        await this.ensureStarted();
+        const partitionSize = this.options.partitionSize ?? 500_000;
+        const highest = await this.readHighestSeq(pid);
+        const hi = toSeq !== undefined ? Math.min(toSeq, highest) : highest;
+        if (hi < fromSeq)
+            return [];
+        const firstPartition = Math.floor(Math.max(fromSeq - 1, 0) / partitionSize);
+        const lastPartition = Math.floor(Math.max(hi - 1, 0) / partitionSize);
+        const out = [];
+        for (let p = firstPartition; p <= lastPartition; p++) {
+            const res = await this.client.execute(`SELECT persistence_id, partition_nr, sequence_nr, timestamp, payload, tags FROM ${this.qualified(this.eventsTable)} WHERE persistence_id = ? AND partition_nr = ? AND sequence_nr >= ? AND sequence_nr <= ?`, [pid, p, fromSeq, hi], { prepare: true });
+            for (const row of res.rows) {
+                out.push({
+                    persistenceId: row.persistence_id,
+                    sequenceNr: Number(row.sequence_nr),
+                    event: JSON.parse(row.payload),
+                    timestamp: Number(row.timestamp),
+                    tags: row.tags && row.tags.length > 0 ? row.tags : undefined,
+                });
+            }
+        }
+        // Partition reads come back sorted by clustering order; stitching is cheap.
+        out.sort((a, b) => a.sequenceNr - b.sequenceNr);
+        return out;
+    }
+    async highestSeq(pid) {
+        await this.ensureStarted();
+        return this.readHighestSeq(pid);
+    }
+    async delete(pid, toSeq) {
+        await this.ensureStarted();
+        const partitionSize = this.options.partitionSize ?? 500_000;
+        const lastPartition = Math.floor(Math.max(toSeq - 1, 0) / partitionSize);
+        for (let p = 0; p <= lastPartition; p++) {
+            try {
+                await this.client.execute(`DELETE FROM ${this.qualified(this.eventsTable)} WHERE persistence_id = ? AND partition_nr = ? AND sequence_nr <= ?`, [pid, p, toSeq], { prepare: true });
+            }
+            catch (e) {
+                throw new JournalError(`CassandraJournal.delete failed: ${e.message}`, e);
+            }
+        }
+    }
+    async persistenceIds() {
+        await this.ensureStarted();
+        const res = await this.client.execute(`SELECT persistence_id FROM ${this.qualified(this.allIdsTable)} WHERE tag = ?`, ['_all'], { prepare: true });
+        return res.rows.map(r => r.persistence_id);
+    }
+    async close() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.ownsClient && this.started) {
+            try {
+                await this.client.shutdown();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /* ========================== internal ========================== */
+    get eventsTable() { return this.options.eventsTable ?? 'events'; }
+    get metadataTable() { return this.options.metadataTable ?? 'metadata'; }
+    get allIdsTable() { return this.options.allIdsTable ?? 'all_persistence_ids'; }
+    /** Side-table name used when `useTagIndex` is set — visible so
+     *  `CassandraQuery` can target it directly. */
+    get tagIndexTable() { return this.options.tagIndexTable ?? 'events_by_tag'; }
+    /** Whether dual-writes to the tag-index side table are enabled. */
+    get useTagIndex() { return this.options.useTagIndex === true; }
+    qualified(table) {
+        return `${this.options.keyspace}.${table}`;
+    }
+    async readHighestSeq(pid) {
+        const res = await this.client.execute(`SELECT max_sequence_nr FROM ${this.qualified(this.metadataTable)} WHERE persistence_id = ?`, [pid], { prepare: true });
+        const row = res.rows[0];
+        return row?.max_sequence_nr !== undefined ? Number(row.max_sequence_nr) : 0;
+    }
+    async ensureStarted() {
+        if (this.started)
+            return;
+        await this.start();
+    }
+    async ensureTables() {
+        await this.client.execute(`CREATE TABLE IF NOT EXISTS ${this.qualified(this.eventsTable)} (`
+            + ` persistence_id text,`
+            + ` partition_nr bigint,`
+            + ` sequence_nr bigint,`
+            + ` timestamp bigint,`
+            + ` payload text,`
+            + ` tags set<text>,`
+            + ` PRIMARY KEY ((persistence_id, partition_nr), sequence_nr)`
+            + ` ) WITH CLUSTERING ORDER BY (sequence_nr ASC)`);
+        await this.client.execute(`CREATE TABLE IF NOT EXISTS ${this.qualified(this.metadataTable)} (`
+            + ` persistence_id text PRIMARY KEY,`
+            + ` max_sequence_nr bigint,`
+            + ` updated_at bigint`
+            + ` )`);
+        await this.client.execute(`CREATE TABLE IF NOT EXISTS ${this.qualified(this.allIdsTable)} (`
+            + ` tag text,`
+            + ` persistence_id text,`
+            + ` PRIMARY KEY (tag, persistence_id)`
+            + ` )`);
+        if (this.useTagIndex) {
+            // Side table for indexed `eventsByTag` queries (#44).  Each row
+            // is one (event, tag) pair; a tag-query walks a single (tag)
+            // partition ordered by `(timestamp, persistence_id, sequence_nr)`
+            // — bounded scan cost regardless of total journal size.  Carrying
+            // the full `tags` set on every row lets the query layer JS-refine
+            // multi-tag filters without an extra read of `events`.
+            await this.client.execute(`CREATE TABLE IF NOT EXISTS ${this.qualified(this.tagIndexTable)} (`
+                + ` tag text,`
+                + ` timestamp bigint,`
+                + ` persistence_id text,`
+                + ` sequence_nr bigint,`
+                + ` payload text,`
+                + ` tags set<text>,`
+                + ` PRIMARY KEY ((tag), timestamp, persistence_id, sequence_nr)`
+                + ` ) WITH CLUSTERING ORDER BY (timestamp ASC, persistence_id ASC, sequence_nr ASC)`);
+        }
+    }
+}
+//# sourceMappingURL=CassandraJournal.js.map

package/dist/persistence/journals/CassandraJournal.js.map

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

package/dist/persistence/journals/CassandraPlugin.d.ts

@@ -0,0 +1,30 @@
+import type { PersistenceExtension } from '../PersistenceExtension.js';
+import { type CassandraJournalOptions } from './CassandraJournal.js';
+import { type CassandraSnapshotStoreOptions } from '../snapshot-stores/CassandraSnapshotStore.js';
+import type { CassandraClientLike } from './CassandraClient.js';
+/** Canonical plug-in IDs for the Cassandra journal and snapshot store. */
+export declare const CASSANDRA_JOURNAL_PLUGIN_ID = "actor-ts.persistence.journal.cassandra";
+export declare const CASSANDRA_SNAPSHOT_PLUGIN_ID = "actor-ts.persistence.snapshot-store.cassandra";
+export interface RegisterCassandraPluginsOptions {
+    /**
+     * Shared CQL client used by the journal AND the snapshot store.  When
+     * provided, both plug-ins reuse the same connection pool (one TCP
+     * connection tree per cluster node).  When omitted, each plug-in
+     * constructs its own client.
+     */
+    readonly client?: CassandraClientLike;
+    /** Journal-specific overrides. */
+    readonly journal: Omit<CassandraJournalOptions, 'client'>;
+    /** Snapshot-store-specific overrides.  Usually shares keyspace with the journal. */
+    readonly snapshotStore: Omit<CassandraSnapshotStoreOptions, 'client'>;
+}
+/**
+ * One-shot registration of both the Cassandra/Scylla journal and the
+ * matching snapshot store against the running `PersistenceExtension`.
+ * After this call set
+ *   `actor-ts.persistence.journal.plugin = "actor-ts.persistence.journal.cassandra"`
+ *   `actor-ts.persistence.snapshot-store.plugin = "actor-ts.persistence.snapshot-store.cassandra"`
+ * either via HOCON or a `{ config: { ... } }` override to make them active.
+ */
+export declare function registerCassandraPlugins(ext: PersistenceExtension, options: RegisterCassandraPluginsOptions): void;
+//# sourceMappingURL=CassandraPlugin.d.ts.map

package/dist/persistence/journals/CassandraPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CassandraPlugin.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/CassandraPlugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,8CAA8C,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,0EAA0E;AAC1E,eAAO,MAAM,2BAA2B,2CAA2C,CAAC;AACpF,eAAO,MAAM,4BAA4B,kDAAkD,CAAC;AAE5F,MAAM,WAAW,+BAA+B;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,CAAC;IAC1D,oFAAoF;IACpF,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,6BAA6B,EAAE,QAAQ,CAAC,CAAC;CACvE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,+BAA+B,GACvC,IAAI,CASN"}

package/dist/persistence/journals/CassandraPlugin.js

@@ -0,0 +1,18 @@
+import { CassandraJournal, } from './CassandraJournal.js';
+import { CassandraSnapshotStore, } from '../snapshot-stores/CassandraSnapshotStore.js';
+/** Canonical plug-in IDs for the Cassandra journal and snapshot store. */
+export const CASSANDRA_JOURNAL_PLUGIN_ID = 'actor-ts.persistence.journal.cassandra';
+export const CASSANDRA_SNAPSHOT_PLUGIN_ID = 'actor-ts.persistence.snapshot-store.cassandra';
+/**
+ * One-shot registration of both the Cassandra/Scylla journal and the
+ * matching snapshot store against the running `PersistenceExtension`.
+ * After this call set
+ *   `actor-ts.persistence.journal.plugin = "actor-ts.persistence.journal.cassandra"`
+ *   `actor-ts.persistence.snapshot-store.plugin = "actor-ts.persistence.snapshot-store.cassandra"`
+ * either via HOCON or a `{ config: { ... } }` override to make them active.
+ */
+export function registerCassandraPlugins(ext, options) {
+    ext.registerJournal(CASSANDRA_JOURNAL_PLUGIN_ID, (_system) => new CassandraJournal({ ...options.journal, client: options.client }));
+    ext.registerSnapshotStore(CASSANDRA_SNAPSHOT_PLUGIN_ID, (_system) => new CassandraSnapshotStore({ ...options.snapshotStore, client: options.client }));
+}
+//# sourceMappingURL=CassandraPlugin.js.map

package/dist/persistence/journals/CassandraPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CassandraPlugin.js","sourceRoot":"","sources":["../../../src/persistence/journals/CassandraPlugin.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,gBAAgB,GAEjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,sBAAsB,GAEvB,MAAM,8CAA8C,CAAC;AAGtD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,2BAA2B,GAAG,wCAAwC,CAAC;AACpF,MAAM,CAAC,MAAM,4BAA4B,GAAG,+CAA+C,CAAC;AAgB5F;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,GAAyB,EACzB,OAAwC;IAExC,GAAG,CAAC,eAAe,CACjB,2BAA2B,EAC3B,CAAC,OAAoB,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAC/F,CAAC;IACF,GAAG,CAAC,qBAAqB,CACvB,4BAA4B,EAC5B,CAAC,OAAoB,EAAE,EAAE,CAAC,IAAI,sBAAsB,CAAC,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAC3G,CAAC;AACJ,CAAC"}

package/dist/persistence/journals/InMemoryJournal.d.ts

@@ -0,0 +1,35 @@
+import { type JournalEventBus } from '../JournalEventBus.js';
+import type { Journal } from '../Journal.js';
+import { type PersistentEvent } from '../JournalTypes.js';
+/**
+ * In-process journal backed by plain arrays.  The default plug-in used by
+ * tests and dev-mode; data lives only as long as the process and is NOT
+ * shared across ActorSystem instances.  Serves as reference semantics for
+ * all other Journal implementations.
+ *
+ * Exposes an in-process `JournalEventBus` so the query layer can do
+ * sub-poll-interval push delivery (see #42).
+ */
+export declare class InMemoryJournal implements Journal {
+    private readonly streams;
+    readonly events: JournalEventBus;
+    append<E>(pid: string, events: ReadonlyArray<E>, expectedSeq: number, tags?: ReadonlyArray<string>): Promise<PersistentEvent<E>[]>;
+    read<E>(pid: string, fromSeq: number, toSeq?: number): Promise<PersistentEvent<E>[]>;
+    highestSeq(pid: string): Promise<number>;
+    delete(pid: string, toSeq: number): Promise<void>;
+    persistenceIds(): Promise<string[]>;
+    close(): Promise<void>;
+    /**
+     * Migration hook (#9).  Applies `transform` to every persisted
+     * event's payload under `pid`, rewriting in place — sequence numbers,
+     * timestamps, tags are preserved.  Used by `migrateInMemoryJournal`
+     * to wrap legacy raw events into the `_v/_t/_e` envelope when an
+     * actor is retro-fitted with an `EventAdapter`.
+     *
+     * **Internal API.**  Callers should reach for the documented
+     * `migrateInMemoryJournal` helper instead of calling this directly;
+     * the underscored prefix marks it as a migration-only escape hatch.
+     */
+    _remapForMigration<E, F>(pid: string, transform: (e: E) => F): Promise<void>;
+}
+//# sourceMappingURL=InMemoryJournal.d.ts.map

package/dist/persistence/journals/InMemoryJournal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryJournal.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/InMemoryJournal.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;GAQG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiD;IACzE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAkC;IAE5D,MAAM,CAAC,CAAC,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAC3B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IA6B1B,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IASpF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMxC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjD,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAInC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE5B;;;;;;;;;;OAUG;IACG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAcnF"}

package/dist/persistence/journals/InMemoryJournal.js

@@ -0,0 +1,97 @@
+import { InProcessJournalEventBus } from '../JournalEventBus.js';
+import { JournalConcurrencyError, } from '../JournalTypes.js';
+/**
+ * In-process journal backed by plain arrays.  The default plug-in used by
+ * tests and dev-mode; data lives only as long as the process and is NOT
+ * shared across ActorSystem instances.  Serves as reference semantics for
+ * all other Journal implementations.
+ *
+ * Exposes an in-process `JournalEventBus` so the query layer can do
+ * sub-poll-interval push delivery (see #42).
+ */
+export class InMemoryJournal {
+    streams = new Map();
+    events = new InProcessJournalEventBus();
+    async append(pid, events, expectedSeq, tags) {
+        const stream = this.streams.get(pid) ?? [];
+        const actualSeq = stream.length === 0 ? 0 : stream[stream.length - 1].sequenceNr;
+        if (actualSeq !== expectedSeq) {
+            throw new JournalConcurrencyError(pid, expectedSeq, actualSeq);
+        }
+        const now = Date.now();
+        const appended = [];
+        let seq = actualSeq;
+        for (const ev of events) {
+            seq++;
+            const pe = {
+                persistenceId: pid,
+                sequenceNr: seq,
+                event: ev,
+                timestamp: now,
+                tags: tags ? [...tags] : undefined,
+            };
+            appended.push(pe);
+            stream.push(pe);
+        }
+        this.streams.set(pid, stream);
+        // Publish AFTER the in-memory state is updated so subscribers
+        // that immediately re-read see the events they were notified
+        // about.
+        for (const pe of appended)
+            this.events.publish(pe);
+        return appended;
+    }
+    async read(pid, fromSeq, toSeq) {
+        const stream = this.streams.get(pid);
+        if (!stream)
+            return [];
+        const to = toSeq ?? (stream.length === 0 ? 0 : stream[stream.length - 1].sequenceNr);
+        return stream
+            .filter(e => e.sequenceNr >= fromSeq && e.sequenceNr <= to)
+            .map(e => e);
+    }
+    async highestSeq(pid) {
+        const stream = this.streams.get(pid);
+        if (!stream || stream.length === 0)
+            return 0;
+        return stream[stream.length - 1].sequenceNr;
+    }
+    async delete(pid, toSeq) {
+        const stream = this.streams.get(pid);
+        if (!stream)
+            return;
+        const next = stream.filter(e => e.sequenceNr > toSeq);
+        this.streams.set(pid, next);
+    }
+    async persistenceIds() {
+        return Array.from(this.streams.keys());
+    }
+    async close() { this.streams.clear(); }
+    /**
+     * Migration hook (#9).  Applies `transform` to every persisted
+     * event's payload under `pid`, rewriting in place — sequence numbers,
+     * timestamps, tags are preserved.  Used by `migrateInMemoryJournal`
+     * to wrap legacy raw events into the `_v/_t/_e` envelope when an
+     * actor is retro-fitted with an `EventAdapter`.
+     *
+     * **Internal API.**  Callers should reach for the documented
+     * `migrateInMemoryJournal` helper instead of calling this directly;
+     * the underscored prefix marks it as a migration-only escape hatch.
+     */
+    async _remapForMigration(pid, transform) {
+        const stream = this.streams.get(pid);
+        if (!stream)
+            return;
+        for (let i = 0; i < stream.length; i++) {
+            const pe = stream[i];
+            stream[i] = {
+                persistenceId: pe.persistenceId,
+                sequenceNr: pe.sequenceNr,
+                event: transform(pe.event),
+                timestamp: pe.timestamp,
+                tags: pe.tags,
+            };
+        }
+    }
+}
+//# sourceMappingURL=InMemoryJournal.js.map

package/dist/persistence/journals/InMemoryJournal.js.map

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

package/dist/persistence/journals/SqliteJournal.d.ts

@@ -0,0 +1,68 @@
+import { type SqliteDriver } from '../../runtime/sqlite/index.js';
+import { type JournalEventBus } from '../JournalEventBus.js';
+import type { Journal } from '../Journal.js';
+import { type PersistentEvent } from '../JournalTypes.js';
+export interface SqliteJournalOptions {
+    /** File path (absolute or relative) or ":memory:" for an ephemeral DB. */
+    readonly path?: string;
+    /** Table name for events.  Default: `events`. */
+    readonly eventsTable?: string;
+    /** If true, opens the DB with WAL mode enabled. */
+    readonly wal?: boolean;
+    /**
+     * Explicit driver — useful for tests or when you want to pin a
+     * specific SQLite backend.  Default: auto-detect via `getSqliteDriver()`
+     * (Bun → `bun:sqlite`, Node → `better-sqlite3`).
+     */
+    readonly driver?: SqliteDriver;
+}
+/**
+ * Journal backed by SQLite — zero-dependency, single-file persistence.
+ *
+ * Works on Bun (`bun:sqlite`) and Node.js (`better-sqlite3`) via the
+ * `SqliteDriver` abstraction in `src/runtime/sqlite/`.  Both backends
+ * share the same prepared-statement + transaction shape, so the journal
+ * code itself is unchanged across runtimes.
+ *
+ * Construction is lazy: the native DB is opened on the first `append` /
+ * `read` / `highestSeq` / `delete` / `persistenceIds` call.  This keeps
+ * `new SqliteJournal({ path })` sync-friendly (matches the pre-abstraction
+ * shape) while still supporting the async driver-resolution flow Node
+ * requires.
+ */
+export declare class SqliteJournal implements Journal {
+    private readonly options;
+    private readonly table;
+    private readonly closed;
+    /**
+     * In-process event bus — published-to inside `append` so the query
+     * layer can do sub-poll-interval push delivery in the same process.
+     * Cross-process subscribers (separate Bun/Node instance reading
+     * the same SQLite file) still need to poll; that's the inherent
+     * limit of in-process notifications.
+     */
+    readonly events: JournalEventBus;
+    private db;
+    private stmts;
+    private initPromise;
+    constructor(options?: SqliteJournalOptions);
+    append<E>(pid: string, events: ReadonlyArray<E>, expectedSeq: number, tags?: ReadonlyArray<string>): Promise<PersistentEvent<E>[]>;
+    read<E>(pid: string, fromSeq: number, toSeq?: number): Promise<PersistentEvent<E>[]>;
+    highestSeq(pid: string): Promise<number>;
+    delete(pid: string, toSeq: number): Promise<void>;
+    persistenceIds(): Promise<string[]>;
+    close(): Promise<void>;
+    private ensureOpen;
+    private init;
+    /**
+     * One-shot backfill of the tags join table from the legacy CSV
+     * `tags` column.  Runs at most once per init — when `event_tags`
+     * is empty AND the `events` table still has tagged rows we'd
+     * otherwise leave un-indexed.  Re-running is a no-op (the count
+     * check skips it) and the underlying inserts use `INSERT OR
+     * IGNORE` as a defence-in-depth so a partial backfill that gets
+     * interrupted can be resumed without duplicate-key errors.
+     */
+    private backfillTagsTableIfNeeded;
+}
+//# sourceMappingURL=SqliteJournal.d.ts.map

package/dist/persistence/journals/SqliteJournal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteJournal.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/SqliteJournal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,YAAY,EAAwB,MAAM,+BAA+B,CAAC;AACxH,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAiBD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAkC;IAElE,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,WAAW,CAA8B;gBAErC,OAAO,GAAE,oBAAyB;IAKxC,MAAM,CAAC,CAAC,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAC3B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IAoD1B,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IA+BpF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMxC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjD,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAQd,UAAU;YAOV,IAAI;IAmElB;;;;;;;;OAQG;IACH,OAAO,CAAC,yBAAyB;CAwBlC"}