actor-ts 0.9.0

package/dist/persistence/durable-state-stores/ObjectStorageDurableStateStore.js

@@ -0,0 +1,157 @@
+import { JournalError } from '../JournalTypes.js';
+import { encodeBody, decodeBody } from '../object-storage/BodyCodec.js';
+import { activeEncryptKey, isVersionedKeyShape, resolveDecryptSubkey, } from '../object-storage/Encryption.js';
+import { ObjectStorageConcurrencyError, } from '../object-storage/ObjectStorageBackend.js';
+import { resolveCompression, resolveEncryption, } from '../object-storage/PluginConfig.js';
+import { DurableStateConcurrencyError, } from '../DurableStateStore.js';
+import { none, some } from '../../util/Option.js';
+/**
+ * DurableState backed by any `ObjectStorageBackend`.  Each
+ * `persistenceId` lives at the single key
+ * `<prefix><pid>/state.json` and is rewritten in place — there is no
+ * sequence-padded history, and `revision` lives entirely in the body.
+ *
+ * Strict CAS via ETag.  Every successful `load` and `upsert` caches the
+ * server's ETag; the next `upsert(expectedRevision = N)` translates to:
+ *
+ *   - `expectedRevision === 0`  → `If-None-Match: '*'` (refuse if the key already exists)
+ *   - `expectedRevision > 0`    → `If-Match: <cached etag>` (refuse if the bucket diverged)
+ *
+ * Either form, when rejected by the backend, surfaces as
+ * `DurableStateConcurrencyError` with the expected revision.  The
+ * `actual` field defaults to `-1` because the backend doesn't tell us
+ * the colliding revision — caller can `load` to read it.
+ */
+const utf8 = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+export class ObjectStorageDurableStateStore {
+    backend;
+    prefix;
+    compression;
+    encryption;
+    etagCache = new Map();
+    constructor(opts) {
+        this.backend = opts.backend;
+        this.prefix = opts.prefix ?? '';
+        this.compression = opts.compression;
+        this.encryption = opts.encryption;
+    }
+    async load(pid, options) {
+        const fetched = await this.backend.get(this.keyFor(pid));
+        if (fetched.isNone())
+            return none;
+        // Per-call encryption (from the actor) wins over the plugin default.
+        const encryption = options?.encryption
+            ?? resolveEncryption(this.encryption, pid, { mode: 'none' });
+        const subKeyFor = resolveDecryptSubkey(encryption, pid);
+        const decoded = await decodeBody(fetched.value.body, subKeyFor ? { encryption: { subKeyFor } } : undefined);
+        let parsed;
+        try {
+            parsed = JSON.parse(utf8Decoder.decode(decoded.payload));
+        }
+        catch (e) {
+            throw new JournalError(`ObjectStorageDurableStateStore.load: malformed JSON for ${pid}`, e);
+        }
+        this.etagCache.set(pid, { etag: fetched.value.etag, revision: parsed.revision });
+        return some({
+            persistenceId: pid,
+            revision: parsed.revision,
+            state: parsed.state,
+            timestamp: parsed.timestamp,
+        });
+    }
+    async upsert(pid, expectedRevision, state, options) {
+        if (!Number.isInteger(expectedRevision) || expectedRevision < 0) {
+            throw new JournalError(`DurableState.upsert: expectedRevision must be a non-negative integer, got ${expectedRevision}`);
+        }
+        // Per-call options take precedence over plugin defaults / resolver —
+        // matches the SnapshotStore precedence order.
+        const compression = options?.compression
+            ?? resolveCompression(this.compression, pid, { algorithm: 'gzip' });
+        const encryption = options?.encryption
+            ?? resolveEncryption(this.encryption, pid, { mode: 'none' });
+        const now = Date.now();
+        const newRevision = expectedRevision + 1;
+        const json = JSON.stringify({ revision: newRevision, state, timestamp: now });
+        const active = await activeEncryptKey(encryption, pid);
+        const stampVersion = active && isVersionedKeyShape(encryption);
+        const body = await encodeBody(utf8.encode(json), {
+            compression: compression.algorithm,
+            encryption: active
+                ? {
+                    subKey: active.subKey,
+                    ...(stampVersion ? { keyVersion: active.keyVersion } : {}),
+                }
+                : undefined,
+        });
+        const cached = this.etagCache.get(pid);
+        // If we have a cached snapshot and its revision doesn't match what the
+        // caller expects, the caller is stale — surface CAS up-front rather
+        // than overwriting the wrong record.
+        if (cached !== undefined && cached.revision !== expectedRevision) {
+            throw new DurableStateConcurrencyError(pid, expectedRevision, cached.revision);
+        }
+        const ifMatch = expectedRevision === 0 ? undefined : cached?.etag;
+        const ifNoneMatch = expectedRevision === 0 ? '*' : undefined;
+        void ifMatch; // re-read after possible refresh below
+        if (expectedRevision > 0 && cached === undefined) {
+            // We were asked to expect revision N>0 but have no etag in cache.  Two
+            // legitimate paths: caller never `load`ed (operator error) or cache
+            // was wiped (e.g. on actor restart).  Do an extra load to refresh;
+            // if the bucket's revision matches expected, retry with the fresh
+            // etag.  If not, surface the concurrency error so the caller can
+            // recover.
+            // Pass `options` so the cache-refresh load can decrypt with the
+            // caller's encryption preferences.
+            const opt = await this.load(pid, options);
+            if (opt.isNone()) {
+                throw new DurableStateConcurrencyError(pid, expectedRevision, 0);
+            }
+            if (opt.value.revision !== expectedRevision) {
+                throw new DurableStateConcurrencyError(pid, expectedRevision, opt.value.revision);
+            }
+        }
+        const refreshedEtag = this.etagCache.get(pid)?.etag;
+        const effectiveIfMatch = expectedRevision === 0 ? undefined : refreshedEtag;
+        let etag;
+        try {
+            const result = await this.backend.put(this.keyFor(pid), body, {
+                contentType: 'application/json',
+                contentEncoding: compression.algorithm === 'none' ? undefined : compression.algorithm,
+                ifMatch: effectiveIfMatch,
+                ifNoneMatch,
+                sse: encryption.mode === 'sse-s3' ? 'AES256'
+                    : encryption.mode === 'sse-kms' ? { kmsKeyId: encryption.kmsKeyId }
+                        : undefined,
+            });
+            etag = result.etag;
+        }
+        catch (e) {
+            if (e instanceof ObjectStorageConcurrencyError) {
+                // -1 communicates "the backend rejected us, but didn't tell us the
+                // current revision; load() will fetch the truth".
+                throw new DurableStateConcurrencyError(pid, expectedRevision, -1);
+            }
+            throw e;
+        }
+        this.etagCache.set(pid, { etag, revision: newRevision });
+        return { persistenceId: pid, revision: newRevision, state, timestamp: now };
+    }
+    async delete(pid) {
+        await this.backend.delete(this.keyFor(pid));
+        this.etagCache.delete(pid);
+    }
+    async close() {
+        this.etagCache.clear();
+        await this.backend.close?.();
+    }
+    /** Test hook — drop the cached ETag for a pid (simulates actor restart). */
+    forgetEtagForTest(pid) {
+        this.etagCache.delete(pid);
+    }
+    /* ----------------------------- internals ------------------------------ */
+    keyFor(pid) {
+        return `${this.prefix}${pid}/state.json`;
+    }
+}
+//# sourceMappingURL=ObjectStorageDurableStateStore.js.map

package/dist/persistence/durable-state-stores/ObjectStorageDurableStateStore.js.map

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

package/dist/persistence/index.d.ts

@@ -0,0 +1,65 @@
+export { PersistenceExtension, PersistenceExtensionId, } from './PersistenceExtension.js';
+export { PersistentActor, everyNEvents } from './PersistentActor.js';
+export type { SnapshotPolicy } from './PersistentActor.js';
+export { eventDispatcher } from './EventDispatcher.js';
+export type { EventDispatcherBuilder, EventDispatcherIncomplete } from './EventDispatcher.js';
+export type { Journal } from './Journal.js';
+export type { SnapshotStore } from './SnapshotStore.js';
+export type { PersistentEvent, Snapshot } from './JournalTypes.js';
+export { JournalConcurrencyError, JournalError } from './JournalTypes.js';
+export type { CompressionAlgo, CompressionConfig, EncryptionConfig, PersistenceOptions, } from './PersistenceOptions.js';
+export { InMemoryJournal } from './journals/InMemoryJournal.js';
+export { SqliteJournal } from './journals/SqliteJournal.js';
+export type { SqliteJournalOptions } from './journals/SqliteJournal.js';
+export { InMemorySnapshotStore } from './snapshot-stores/InMemorySnapshotStore.js';
+export { SqliteSnapshotStore } from './snapshot-stores/SqliteSnapshotStore.js';
+export type { SqliteSnapshotStoreOptions } from './snapshot-stores/SqliteSnapshotStore.js';
+export { CachedSnapshotStore } from './snapshot-stores/CachedSnapshotStore.js';
+export type { CachedSnapshotStoreOptions } from './snapshot-stores/CachedSnapshotStore.js';
+export { CassandraJournal } from './journals/CassandraJournal.js';
+export type { CassandraJournalOptions } from './journals/CassandraJournal.js';
+export { CassandraSnapshotStore } from './snapshot-stores/CassandraSnapshotStore.js';
+export type { CassandraSnapshotStoreOptions } from './snapshot-stores/CassandraSnapshotStore.js';
+export { createCassandraClient, keyspaceDdl, tagIndexDdl, } from './journals/CassandraClient.js';
+export type { CassandraClientLike, CassandraConnection, CassandraRowResult, CassandraBatchQuery, } from './journals/CassandraClient.js';
+export { registerCassandraPlugins, CASSANDRA_JOURNAL_PLUGIN_ID, CASSANDRA_SNAPSHOT_PLUGIN_ID, } from './journals/CassandraPlugin.js';
+export type { RegisterCassandraPluginsOptions } from './journals/CassandraPlugin.js';
+export { DurableStateActor } from './DurableStateActor.js';
+export type { DurableStateSettings } from './DurableStateActor.js';
+export { DurableStateConcurrencyError, } from './DurableStateStore.js';
+export type { DurableStateStore, DurableStateRecord, } from './DurableStateStore.js';
+export { InMemoryDurableStateStore } from './durable-state-stores/InMemoryDurableStateStore.js';
+export type { EventAdapter, SnapshotAdapter, StateAdapter, JournalEnvelope, StoredFrame, OutboundFrame, MigrationStep, DowncastStep, DefaultsAdapterSpec, MigrationResult, Codec, ParserLike, ValidatedAdapterOptions, SchemaRegistry, SchemaRegistration, SchemaDescriptor, MigrateJournalsOptions, MigrateJournalsResult, MigrateSnapshotStoresOptions, MigrateSnapshotStoresResult, MigrationProgress, MigrationProgressStore, } from './migration/index.js';
+export { MigrationError, MigrationChain, defaultsAdapter, defaultsSnapshotAdapter, migratingAdapter, migratingSnapshotAdapter, isEnvelope, encodeEvent, decodeEvent, encodeState, decodeState, wrapEventAsEnvelope, wrapStateAsEnvelope, migrateInMemoryJournal, migrateSnapshotStore, formatMigrationResult, jsonCodec, zodCodec, composeCodecs, validatedEventAdapter, validatedSnapshotAdapter, InMemorySchemaRegistry, migrateBetweenJournals, migrateBetweenSnapshotStores, InMemoryMigrationProgressStore, } from './migration/index.js';
+export type { PersistenceQuery, LiveQueryOptions, Offset, TaggedEvent, TagFilter, TagFilterSpec, } from './query/PersistenceQuery.js';
+export { offsetStart, offsetCompare, offsetGreater, offsetGreaterOrEqual, offsetOfEvent, normalizeTagFilter, eventMatchesTagFilter, } from './query/PersistenceQuery.js';
+export { InMemoryQuery } from './query/InMemoryQuery.js';
+export { SqliteQuery } from './query/SqliteQuery.js';
+export { CassandraQuery } from './query/CassandraQuery.js';
+export { ReplicatedEventSourcedActor } from './ReplicatedEventSourcedActor.js';
+export type { ReplicatedEventEnvelope } from './ReplicatedEventSourcedActor.js';
+export { VectorClock } from './replicated/VectorClock.js';
+export type { VectorClockData, VectorClockOrder } from './replicated/VectorClock.js';
+export { LastWriterWinsResolver, CustomMergeResolver, } from './replicated/ConflictResolver.js';
+export type { ConflictResolver, ConflictCandidate, } from './replicated/ConflictResolver.js';
+export { ProjectionActor } from './projection/ProjectionActor.js';
+export type { ProjectionSettings, ByPidSettings, ByTagSettings, } from './projection/ProjectionActor.js';
+export type { OffsetStore } from './projection/OffsetStore.js';
+export { InMemoryOffsetStore, DurableStateOffsetStore, } from './projection/OffsetStore.js';
+export { ObjectStorageBackendError, ObjectStorageConcurrencyError, } from './object-storage/ObjectStorageBackend.js';
+export type { ObjectStorageBackend, ObjectFetched, ObjectInfo, PutOptions, } from './object-storage/ObjectStorageBackend.js';
+export { FilesystemObjectStorageBackend } from './object-storage/FilesystemObjectStorageBackend.js';
+export type { FilesystemObjectStorageOptions } from './object-storage/FilesystemObjectStorageBackend.js';
+export { S3ObjectStorageBackend } from './object-storage/S3ObjectStorageBackend.js';
+export type { S3ObjectStorageOptions, S3Credentials, S3ClientLike, } from './object-storage/S3ObjectStorageBackend.js';
+export { ObjectStorageSnapshotStore, } from './snapshot-stores/ObjectStorageSnapshotStore.js';
+export type { ObjectStorageSnapshotStoreOptions, } from './snapshot-stores/ObjectStorageSnapshotStore.js';
+export { ObjectStorageDurableStateStore } from './durable-state-stores/ObjectStorageDurableStateStore.js';
+export type { ObjectStorageDurableStateStoreOptions } from './durable-state-stores/ObjectStorageDurableStateStore.js';
+export { registerObjectStoragePlugins, OBJECT_STORAGE_SNAPSHOT_PLUGIN_ID, OBJECT_STORAGE_DURABLE_STATE_PLUGIN_ID, } from './object-storage/ObjectStoragePlugin.js';
+export type { ObjectStoragePluginOptions, ObjectStoragePluginHandles, ObjectStorageBackendSpec, } from './object-storage/ObjectStoragePlugin.js';
+export { compressionByPrefix, encryptionByPrefix, resolveCompression, resolveEncryption, } from './object-storage/PluginConfig.js';
+export type { CompressionResolver, EncryptionResolver, } from './object-storage/PluginConfig.js';
+export { reEncryptObjectStorage } from './object-storage/reEncryptionSweep.js';
+export type { ReEncryptOptions, ReEncryptResult, ReEncryptProgress, } from './object-storage/reEncryptionSweep.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/persistence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAE9F,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC1E,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,YAAY,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAC/E,YAAY,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAC/E,YAAY,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AAG3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,YAAY,EAAE,6BAA6B,EAAE,MAAM,6CAA6C,CAAC;AACjG,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,WAAW,GACZ,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAGrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EACL,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,yBAAyB,EAAE,MAAM,qDAAqD,CAAC;AAGhG,YAAY,EACV,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,eAAe,EAEf,KAAK,EACL,UAAU,EACV,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAEhB,sBAAsB,EACtB,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,EAC3B,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAChB,wBAAwB,EACxB,UAAU,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EAErB,SAAS,EACT,QAAQ,EACR,aAAa,EACb,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EAEtB,sBAAsB,EACtB,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,EACN,WAAW,EACX,SAAS,EACT,aAAa,GACd,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,WAAW,EACX,aAAa,EACb,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG3D,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAC/E,YAAY,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACrF,OAAO,EACL,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EACV,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EACL,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,0CAA0C,CAAC;AAClD,YAAY,EACV,oBAAoB,EACpB,aAAa,EACb,UAAU,EACV,UAAU,GACX,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,8BAA8B,EAAE,MAAM,oDAAoD,CAAC;AACpG,YAAY,EAAE,8BAA8B,EAAE,MAAM,oDAAoD,CAAC;AACzG,OAAO,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AACpF,YAAY,EACV,sBAAsB,EACtB,aAAa,EACb,YAAY,GACb,MAAM,4CAA4C,CAAC;AACpD,OAAO,EACL,0BAA0B,GAC3B,MAAM,iDAAiD,CAAC;AACzD,YAAY,EACV,iCAAiC,GAClC,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAAE,8BAA8B,EAAE,MAAM,0DAA0D,CAAC;AAC1G,YAAY,EAAE,qCAAqC,EAAE,MAAM,0DAA0D,CAAC;AACtH,OAAO,EACL,4BAA4B,EAC5B,iCAAiC,EACjC,sCAAsC,GACvC,MAAM,yCAAyC,CAAC;AACjD,YAAY,EACV,0BAA0B,EAC1B,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,GAClB,MAAM,uCAAuC,CAAC"}

package/dist/persistence/index.js

@@ -0,0 +1,44 @@
+export { PersistenceExtension, PersistenceExtensionId, } from './PersistenceExtension.js';
+export { PersistentActor, everyNEvents } from './PersistentActor.js';
+export { eventDispatcher } from './EventDispatcher.js';
+export { JournalConcurrencyError, JournalError } from './JournalTypes.js';
+export { InMemoryJournal } from './journals/InMemoryJournal.js';
+export { SqliteJournal } from './journals/SqliteJournal.js';
+export { InMemorySnapshotStore } from './snapshot-stores/InMemorySnapshotStore.js';
+export { SqliteSnapshotStore } from './snapshot-stores/SqliteSnapshotStore.js';
+export { CachedSnapshotStore } from './snapshot-stores/CachedSnapshotStore.js';
+// Cassandra / ScyllaDB plug-in (same CQL protocol — one plug-in).
+export { CassandraJournal } from './journals/CassandraJournal.js';
+export { CassandraSnapshotStore } from './snapshot-stores/CassandraSnapshotStore.js';
+export { createCassandraClient, keyspaceDdl, tagIndexDdl, } from './journals/CassandraClient.js';
+export { registerCassandraPlugins, CASSANDRA_JOURNAL_PLUGIN_ID, CASSANDRA_SNAPSHOT_PLUGIN_ID, } from './journals/CassandraPlugin.js';
+// Durable State (state-oriented alternative to Event Sourcing).
+export { DurableStateActor } from './DurableStateActor.js';
+export { DurableStateConcurrencyError, } from './DurableStateStore.js';
+export { InMemoryDurableStateStore } from './durable-state-stores/InMemoryDurableStateStore.js';
+export { MigrationError, MigrationChain, defaultsAdapter, defaultsSnapshotAdapter, migratingAdapter, migratingSnapshotAdapter, isEnvelope, encodeEvent, decodeEvent, encodeState, decodeState, wrapEventAsEnvelope, wrapStateAsEnvelope, migrateInMemoryJournal, migrateSnapshotStore, formatMigrationResult, 
+// #6 — codec + schema registry runtime.
+jsonCodec, zodCodec, composeCodecs, validatedEventAdapter, validatedSnapshotAdapter, InMemorySchemaRegistry, 
+// #87 — journal-to-journal + snapshot-store-to-snapshot-store copy.
+migrateBetweenJournals, migrateBetweenSnapshotStores, InMemoryMigrationProgressStore, } from './migration/index.js';
+export { offsetStart, offsetCompare, offsetGreater, offsetGreaterOrEqual, offsetOfEvent, normalizeTagFilter, eventMatchesTagFilter, } from './query/PersistenceQuery.js';
+export { InMemoryQuery } from './query/InMemoryQuery.js';
+export { SqliteQuery } from './query/SqliteQuery.js';
+export { CassandraQuery } from './query/CassandraQuery.js';
+// Replicated Event Sourcing — multi-master event-sourced actors.
+export { ReplicatedEventSourcedActor } from './ReplicatedEventSourcedActor.js';
+export { VectorClock } from './replicated/VectorClock.js';
+export { LastWriterWinsResolver, CustomMergeResolver, } from './replicated/ConflictResolver.js';
+// Projections — actor wrapper with at-least-once delivery + offset persistence.
+export { ProjectionActor } from './projection/ProjectionActor.js';
+export { InMemoryOffsetStore, DurableStateOffsetStore, } from './projection/OffsetStore.js';
+// Object-storage plug-in (S3 / filesystem) for snapshots + durable state.
+export { ObjectStorageBackendError, ObjectStorageConcurrencyError, } from './object-storage/ObjectStorageBackend.js';
+export { FilesystemObjectStorageBackend } from './object-storage/FilesystemObjectStorageBackend.js';
+export { S3ObjectStorageBackend } from './object-storage/S3ObjectStorageBackend.js';
+export { ObjectStorageSnapshotStore, } from './snapshot-stores/ObjectStorageSnapshotStore.js';
+export { ObjectStorageDurableStateStore } from './durable-state-stores/ObjectStorageDurableStateStore.js';
+export { registerObjectStoragePlugins, OBJECT_STORAGE_SNAPSHOT_PLUGIN_ID, OBJECT_STORAGE_DURABLE_STATE_PLUGIN_ID, } from './object-storage/ObjectStoragePlugin.js';
+export { compressionByPrefix, encryptionByPrefix, resolveCompression, resolveEncryption, } from './object-storage/PluginConfig.js';
+export { reEncryptObjectStorage } from './object-storage/reEncryptionSweep.js';
+//# sourceMappingURL=index.js.map

package/dist/persistence/index.js.map

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

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

@@ -0,0 +1,81 @@
+/**
+ * Narrow interface over the subset of the DataStax `cassandra-driver` API
+ * that the journal / snapshot-store plug-ins actually use.  Kept separate
+ * so tests can supply an in-memory stand-in without pulling in the real
+ * driver, and so the driver itself stays an *optional* peer dependency.
+ */
+export interface CassandraRowResult {
+    readonly rows: Array<Record<string, unknown>>;
+}
+export interface CassandraBatchQuery {
+    readonly query: string;
+    readonly params?: ReadonlyArray<unknown>;
+}
+export interface CassandraClientLike {
+    connect(): Promise<void>;
+    shutdown(): Promise<void>;
+    execute(query: string, params?: ReadonlyArray<unknown>, options?: {
+        prepare?: boolean;
+        consistency?: number;
+    }): Promise<CassandraRowResult>;
+    batch(queries: ReadonlyArray<CassandraBatchQuery>, options?: {
+        prepare?: boolean;
+        logged?: boolean;
+        consistency?: number;
+    }): Promise<void>;
+}
+export interface CassandraConnection {
+    /** Node(s) to seed the cluster topology from. */
+    readonly contactPoints: ReadonlyArray<string>;
+    /** Local DC — required for DCAwareRoundRobinPolicy.  Defaults to `datacenter1`. */
+    readonly localDataCenter?: string;
+    /** Keyspace to `USE` after connect.  Must already exist, or pass `autoCreateKeyspace: true`. */
+    readonly keyspace: string;
+    /** Optional username/password for PLAIN auth. */
+    readonly credentials?: {
+        username: string;
+        password: string;
+    };
+    /** Port — defaults to 9042. */
+    readonly port?: number;
+    /** If true, create the keyspace on startup (simple strategy, rf=1).  Dev-friendly default. */
+    readonly autoCreateKeyspace?: boolean;
+    /** Replication settings used by autoCreateKeyspace.  Ignored otherwise. */
+    readonly replication?: {
+        readonly class?: 'SimpleStrategy' | 'NetworkTopologyStrategy';
+        readonly replicationFactor?: number;
+        /** For NetworkTopologyStrategy, map of DC → replication factor. */
+        readonly dataCenters?: Readonly<Record<string, number>>;
+    };
+    /**
+     * CQL consistency level to use for all reads and writes.  Default:
+     * `LOCAL_QUORUM` (value 6 in the driver).  Pass the numeric value from
+     * `cassandra-driver`'s `types.consistencies`.
+     */
+    readonly consistency?: number;
+}
+/**
+ * DDL for the `events_by_tag` side table populated by `CassandraJournal`
+ * when `useTagIndex` is set (#44).  Returned as a runnable CQL string
+ * so operators applying the schema by hand (or running migrations on
+ * pre-existing keyspaces) can reuse the journal's exact shape.
+ *
+ * `keyspace` and `tagIndexTable` default to the journal's own defaults
+ * — pass them explicitly if you've customised either.
+ */
+export declare function tagIndexDdl(args: {
+    readonly keyspace: string;
+    readonly tagIndexTable?: string;
+}): string;
+/**
+ * Build the default keyspace-bootstrap statement — used by autoCreateKeyspace.
+ */
+export declare function keyspaceDdl(conn: CassandraConnection): string;
+/**
+ * Dynamically import the official DataStax driver and construct a client.
+ * Kept behind `await` so the import only happens when the user actually
+ * creates a Cassandra journal.  If the user constructs their own client
+ * elsewhere they can bypass this entirely.
+ */
+export declare function createCassandraClient(conn: CassandraConnection): Promise<CassandraClientLike>;
+//# sourceMappingURL=CassandraClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CassandraClient.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/CassandraClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,CACL,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACpD,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC/B,KAAK,CACH,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,EAC3C,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACtE,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,mFAAmF;IACnF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8FAA8F;IAC9F,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,yBAAyB,CAAC;QAC9D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QACpC,mEAAmE;QACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACzD,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,CAWT;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAS7D;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA4BnG"}

package/dist/persistence/journals/CassandraClient.js

@@ -0,0 +1,65 @@
+/**
+ * DDL for the `events_by_tag` side table populated by `CassandraJournal`
+ * when `useTagIndex` is set (#44).  Returned as a runnable CQL string
+ * so operators applying the schema by hand (or running migrations on
+ * pre-existing keyspaces) can reuse the journal's exact shape.
+ *
+ * `keyspace` and `tagIndexTable` default to the journal's own defaults
+ * — pass them explicitly if you've customised either.
+ */
+export function tagIndexDdl(args) {
+    const table = args.tagIndexTable ?? 'events_by_tag';
+    return `CREATE TABLE IF NOT EXISTS ${args.keyspace}.${table} (`
+        + ` 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)`;
+}
+/**
+ * Build the default keyspace-bootstrap statement — used by autoCreateKeyspace.
+ */
+export function keyspaceDdl(conn) {
+    const cls = conn.replication?.class ?? 'SimpleStrategy';
+    if (cls === 'NetworkTopologyStrategy') {
+        const dcs = conn.replication?.dataCenters ?? {};
+        const pairs = Object.entries(dcs).map(([dc, rf]) => `'${dc}': ${rf}`).join(', ');
+        return `CREATE KEYSPACE IF NOT EXISTS ${conn.keyspace} WITH replication = { 'class': 'NetworkTopologyStrategy', ${pairs} }`;
+    }
+    const rf = conn.replication?.replicationFactor ?? 1;
+    return `CREATE KEYSPACE IF NOT EXISTS ${conn.keyspace} WITH replication = { 'class': 'SimpleStrategy', 'replication_factor': ${rf} }`;
+}
+/**
+ * Dynamically import the official DataStax driver and construct a client.
+ * Kept behind `await` so the import only happens when the user actually
+ * creates a Cassandra journal.  If the user constructs their own client
+ * elsewhere they can bypass this entirely.
+ */
+export async function createCassandraClient(conn) {
+    let driver;
+    try {
+        // `cassandra-driver` is an OPTIONAL peer dependency.  We indirect
+        // through a runtime-built specifier to avoid the compile-time
+        // module-not-found error when users haven't installed it.
+        const moduleName = 'cassandra-driver';
+        driver = (await import(moduleName));
+    }
+    catch (e) {
+        throw new Error('CassandraJournal requires the "cassandra-driver" package. Install it with: '
+            + 'bun add cassandra-driver\nOriginal error: ' + (e instanceof Error ? e.message : String(e)));
+    }
+    const options = {
+        contactPoints: conn.contactPoints,
+        localDataCenter: conn.localDataCenter ?? 'datacenter1',
+        protocolOptions: { port: conn.port ?? 9042 },
+    };
+    if (conn.credentials)
+        options.credentials = conn.credentials;
+    // We deliberately don't set `keyspace` here — we may need to CREATE it first.
+    const client = new driver.Client(options);
+    return client;
+}
+//# sourceMappingURL=CassandraClient.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CassandraClient.js","sourceRoot":"","sources":["../../../src/persistence/journals/CassandraClient.ts"],"names":[],"mappings":"AAyDA;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,IAG3B;IACC,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,IAAI,eAAe,CAAC;IACpD,OAAO,8BAA8B,IAAI,CAAC,QAAQ,IAAI,KAAK,IAAI;UAC3D,YAAY;UACZ,oBAAoB;UACpB,uBAAuB;UACvB,sBAAsB;UACtB,gBAAgB;UAChB,kBAAkB;UAClB,8DAA8D;UAC9D,kFAAkF,CAAC;AACzF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAyB;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,gBAAgB,CAAC;IACxD,IAAI,GAAG,KAAK,yBAAyB,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,IAAI,EAAE,CAAC;QAChD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjF,OAAO,iCAAiC,IAAI,CAAC,QAAQ,6DAA6D,KAAK,IAAI,CAAC;IAC9H,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,iBAAiB,IAAI,CAAC,CAAC;IACpD,OAAO,iCAAiC,IAAI,CAAC,QAAQ,0EAA0E,EAAE,IAAI,CAAC;AACxI,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAyB;IAMnE,IAAI,MAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,kEAAkE;QAClE,8DAA8D;QAC9D,0DAA0D;QAC1D,MAAM,UAAU,GAAG,kBAAkB,CAAC;QACtC,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAA+B,CAAC;IACpE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,6EAA6E;cAC3E,4CAA4C,GAAG,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAC9F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAA4B;QACvC,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,aAAa;QACtD,eAAe,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE;KAC7C,CAAC;IACF,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IAC7D,8EAA8E;IAC9E,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,96 @@
+import type { Journal } from '../Journal.js';
+import { type PersistentEvent } from '../JournalTypes.js';
+import { type CassandraClientLike, type CassandraConnection } from './CassandraClient.js';
+export interface CassandraJournalOptions extends CassandraConnection {
+    /** Table name for events.  Default: `events`. */
+    readonly eventsTable?: string;
+    /** Table tracking the highest sequence number per pid.  Default: `metadata`. */
+    readonly metadataTable?: string;
+    /** Lookup table for `persistenceIds()`.  Default: `all_persistence_ids`. */
+    readonly allIdsTable?: string;
+    /** Tag-index side table populated when `useTagIndex` is set.  Default: `events_by_tag`. */
+    readonly tagIndexTable?: string;
+    /**
+     * Rows per partition before rolling over to a new one.  Keeps Cassandra
+     * partitions bounded.  Default: 500_000 — a good balance between write
+     * amplification and read-scan cost for long-lived streams.
+     */
+    readonly partitionSize?: number;
+    /** Auto-create the events/metadata/all-ids tables on first connect. */
+    readonly autoCreateTables?: boolean;
+    /**
+     * Opt in to maintaining an `events_by_tag` side table for indexed
+     * `eventsByTag` queries (#44).  When set, every `append` writes one
+     * extra row per `(event, tag)` pair to the side table inside the same
+     * batch as the primary `events` insert; `CassandraQuery.currentEventsBy
+     * Tag` then walks a single tag-partition instead of scanning the
+     * whole journal client-side.
+     *
+     * Off by default to keep existing schemas compatible — operators
+     * opting in must run the side-table DDL on their cluster (the journal
+     * issues `CREATE TABLE IF NOT EXISTS` when `autoCreateTables` is also
+     * true; otherwise the DDL in {@link CassandraClient.tagIndexDdl} can
+     * be applied manually).
+     *
+     * **Caveat:** `delete(toSeq)` does NOT propagate to the side table —
+     * deleting from `events_by_tag` would require either a secondary
+     * index on `persistence_id` or pre-reading the event's tags (extra
+     * round-trips on the hot path).  Operators with delete-heavy
+     * workloads should rely on Cassandra TTLs or accept stale tag
+     * entries (queries dedupe via the primary key, so they're harmless
+     * — just storage overhead).
+     */
+    readonly useTagIndex?: boolean;
+    /**
+     * Inject a pre-built client instead of letting the journal instantiate
+     * `cassandra-driver` itself — useful for tests and when the host already
+     * owns the client lifecycle.
+     */
+    readonly client?: CassandraClientLike;
+}
+/**
+ * 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 declare class CassandraJournal implements Journal {
+    private readonly options;
+    private client;
+    /** True once `ensureStarted()` has run keyspace + table DDL. */
+    private started;
+    /** Toggle so shutdown only happens once. */
+    private stopped;
+    /** Only shut down the client if WE created it — don't close someone else's. */
+    private ownsClient;
+    constructor(options: CassandraJournalOptions);
+    /** Explicitly connect + ensure schema.  Called lazily on first use. */
+    start(): Promise<void>;
+    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 get eventsTable();
+    private get metadataTable();
+    private get allIdsTable();
+    /** Side-table name used when `useTagIndex` is set — visible so
+     *  `CassandraQuery` can target it directly. */
+    get tagIndexTable(): string;
+    /** Whether dual-writes to the tag-index side table are enabled. */
+    get useTagIndex(): boolean;
+    private qualified;
+    private readHighestSeq;
+    private ensureStarted;
+    private ensureTables;
+}
+//# sourceMappingURL=CassandraJournal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CassandraJournal.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/CassandraJournal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,iDAAiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CACvC;AAWD;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAiB,YAAW,OAAO;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,MAAM,CAAsB;IACpC,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAS;IACxB,4CAA4C;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,+EAA+E;IAC/E,OAAO,CAAC,UAAU,CAAU;gBAEhB,OAAO,EAAE,uBAAuB;IAM5C,uEAAuE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAetB,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;IA4F1B,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;IAgCpF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKxC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBjD,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAUnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B,OAAO,KAAK,WAAW,GAA2D;IAClF,OAAO,KAAK,aAAa,GAA+D;IACxF,OAAO,KAAK,WAAW,GAAwE;IAC/F;mDAC+C;IAC/C,IAAI,aAAa,IAAI,MAAM,CAA0D;IACrF,mEAAmE;IACnE,IAAI,WAAW,IAAI,OAAO,CAA8C;IAExE,OAAO,CAAC,SAAS;YAIH,cAAc;YAUd,aAAa;YAKb,YAAY;CA8C3B"}