actor-ts 0.9.0

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

@@ -0,0 +1,172 @@
+import { JournalError } from '../JournalTypes.js';
+import { encodeBody, decodeBody } from '../object-storage/BodyCodec.js';
+import { activeEncryptKey, isVersionedKeyShape, resolveDecryptSubkey, } from '../object-storage/Encryption.js';
+import { resolveCompression, resolveEncryption } from '../object-storage/PluginConfig.js';
+import { none, some } from '../../util/Option.js';
+/** Sequence-number padding — matches `Number.MAX_SAFE_INTEGER`'s 16 digits with headroom. */
+const SEQ_PADDING = 20;
+const utf8 = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+/**
+ * SnapshotStore backed by any `ObjectStorageBackend`.  Each snapshot
+ * lands at `<prefix><pid>/<seq.padStart(20,'0')>.json` — the padding
+ * scheme is what makes `loadLatest` cheap (single LIST with `limit:1`
+ * and reverse iteration over the sorted result).
+ *
+ * `keepN`-based pruning runs after every successful save; older
+ * snapshots are deleted in a best-effort post-pass.  A failed prune
+ * does not fail the save — the next save retries.
+ */
+export class ObjectStorageSnapshotStore {
+    backend;
+    prefix;
+    keepN;
+    compression;
+    encryption;
+    constructor(opts) {
+        this.backend = opts.backend;
+        this.prefix = opts.prefix ?? '';
+        this.keepN = opts.keepN ?? 3;
+        this.compression = opts.compression;
+        this.encryption = opts.encryption;
+    }
+    async save(pid, seq, state, options) {
+        if (!Number.isFinite(seq) || seq < 0) {
+            throw new JournalError(`SnapshotStore.save: invalid sequence ${seq}`);
+        }
+        // Per-call options (from the actor) take precedence over the
+        // plugin-level resolver / default.  An actor that sets nothing falls
+        // through to the plugin config; an actor that sets compression but
+        // not encryption only overrides compression.
+        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 json = JSON.stringify({ persistenceId: pid, sequenceNr: seq, state, timestamp: now });
+        let body;
+        try {
+            const active = await activeEncryptKey(encryption, pid);
+            // Only stamp a key version on the wire when the user opted into
+            // the keyring shape; the legacy single-key path stays backwards-
+            // compatible with bodies written before #8 landed.
+            const stampVersion = active && isVersionedKeyShape(encryption);
+            body = await encodeBody(utf8.encode(json), {
+                compression: compression.algorithm,
+                encryption: active
+                    ? {
+                        subKey: active.subKey,
+                        ...(stampVersion ? { keyVersion: active.keyVersion } : {}),
+                    }
+                    : undefined,
+            });
+        }
+        catch (e) {
+            throw new JournalError(`ObjectStorageSnapshotStore.save: encode failed for ${pid}@${seq}: ${e.message}`, e);
+        }
+        const key = this.snapshotKey(pid, seq);
+        try {
+            await this.backend.put(key, body, {
+                contentType: 'application/json',
+                contentEncoding: compression.algorithm === 'none' ? undefined : compression.algorithm,
+                sse: encryption.mode === 'sse-s3' ? 'AES256'
+                    : encryption.mode === 'sse-kms' ? { kmsKeyId: encryption.kmsKeyId }
+                        : undefined,
+            });
+        }
+        catch (e) {
+            throw new JournalError(`ObjectStorageSnapshotStore.save: backend put failed for ${pid}@${seq}: ${e.message}`, e);
+        }
+        // Best-effort prune.  Failures here MUST NOT fail the save.
+        if (this.keepN > 0) {
+            try {
+                await this.pruneToKeepN(pid);
+            }
+            catch { /* swallow */ }
+        }
+        return { persistenceId: pid, sequenceNr: seq, state, timestamp: now };
+    }
+    async loadLatest(pid, options) {
+        const items = await this.backend.list({ prefix: this.pidPrefix(pid) });
+        if (items.length === 0)
+            return none;
+        // Keys are sorted ascending; we want the highest seq.
+        const latest = items[items.length - 1];
+        return this.fetchSnapshot(pid, latest.key, options);
+    }
+    async loadBefore(pid, seq, options) {
+        const items = await this.backend.list({ prefix: this.pidPrefix(pid) });
+        // Find the highest seq strictly less than the requested one.
+        let chosen = null;
+        for (const it of items) {
+            const s = parseSeqFromKey(it.key);
+            if (s !== null && s < seq)
+                chosen = it.key;
+            else if (s !== null && s >= seq)
+                break;
+        }
+        if (!chosen)
+            return none;
+        return this.fetchSnapshot(pid, chosen, options);
+    }
+    async delete(pid, toSeq) {
+        const items = await this.backend.list({ prefix: this.pidPrefix(pid) });
+        for (const it of items) {
+            const s = parseSeqFromKey(it.key);
+            if (s !== null && s <= toSeq)
+                await this.backend.delete(it.key);
+        }
+    }
+    async close() {
+        await this.backend.close?.();
+    }
+    /* ----------------------------- internals ------------------------------ */
+    snapshotKey(pid, seq) {
+        return `${this.pidPrefix(pid)}${String(seq).padStart(SEQ_PADDING, '0')}.json`;
+    }
+    pidPrefix(pid) {
+        return `${this.prefix}${pid}/`;
+    }
+    async fetchSnapshot(pid, key, options) {
+        const fetched = await this.backend.get(key);
+        if (fetched.isNone())
+            return none;
+        // Per-call encryption (from the actor) wins over plugin defaults — same
+        // precedence order as the write path.
+        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);
+        const json = utf8Decoder.decode(decoded.payload);
+        let parsed;
+        try {
+            parsed = JSON.parse(json);
+        }
+        catch (e) {
+            throw new JournalError(`ObjectStorageSnapshotStore: malformed JSON at key ${key}`, e);
+        }
+        return some({
+            persistenceId: parsed.persistenceId,
+            sequenceNr: parsed.sequenceNr,
+            state: parsed.state,
+            timestamp: parsed.timestamp,
+        });
+    }
+    async pruneToKeepN(pid) {
+        const items = await this.backend.list({ prefix: this.pidPrefix(pid) });
+        if (items.length <= this.keepN)
+            return;
+        const toDelete = items.slice(0, items.length - this.keepN);
+        for (const it of toDelete)
+            await this.backend.delete(it.key);
+    }
+}
+function parseSeqFromKey(key) {
+    // Expected suffix: '<seq.padStart(20,'0')>.json'
+    const m = /(\d{1,20})\.json$/.exec(key);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return Number.isFinite(n) ? n : null;
+}
+//# sourceMappingURL=ObjectStorageSnapshotStore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectStorageSnapshotStore.js","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/ObjectStorageSnapshotStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAiB,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AAOzC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAI1F,OAAO,EAAE,IAAI,EAAE,IAAI,EAAe,MAAM,sBAAsB,CAAC;AAE/D,6FAA6F;AAC7F,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAC/B,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAetC;;;;;;;;;GASG;AACH,MAAM,OAAO,0BAA0B;IACpB,OAAO,CAAuB;IAC9B,MAAM,CAAS;IACf,KAAK,CAAS;IACd,WAAW,CAAsD;IACjE,UAAU,CAAoD;IAE/E,YAAY,IAAuC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,IAAI,CACR,GAAW,EACX,GAAW,EACX,KAAQ,EACR,OAA4B;QAE5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,YAAY,CAAC,wCAAwC,GAAG,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,6DAA6D;QAC7D,qEAAqE;QACrE,mEAAmE;QACnE,6CAA6C;QAC7C,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW;eACnC,kBAAkB,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QACtE,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU;eACjC,iBAAiB,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAE/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;QAC5F,IAAI,IAAgB,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;YACvD,gEAAgE;YAChE,iEAAiE;YACjE,mDAAmD;YACnD,MAAM,YAAY,GAAG,MAAM,IAAI,mBAAmB,CAAC,UAAU,CAAC,CAAC;YAC/D,IAAI,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;gBACzC,WAAW,EAAE,WAAW,CAAC,SAAS;gBAClC,UAAU,EAAE,MAAM;oBAChB,CAAC,CAAC;wBACE,MAAM,EAAE,MAAM,CAAC,MAAM;wBACrB,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBAC3D;oBACH,CAAC,CAAC,SAAS;aACd,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,YAAY,CAAC,sDAAsD,GAAG,IAAI,GAAG,KAAM,CAAW,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QACzH,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE;gBAChC,WAAW,EAAE,kBAAkB;gBAC/B,eAAe,EAAE,WAAW,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS;gBACrF,GAAG,EAAE,UAAU,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ;oBACzC,CAAC,CAAC,UAAU,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE;wBACnE,CAAC,CAAC,SAAS;aACf,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,YAAY,CAAC,2DAA2D,GAAG,IAAI,GAAG,KAAM,CAAW,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QAC9H,CAAC;QAED,4DAA4D;QAC5D,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YACnB,IAAI,CAAC;gBAAC,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC;QAC/D,CAAC;QAED,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,GAAW,EAAE,OAA4B;QAC3D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,sDAAsD;QACtD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QACxC,OAAO,IAAI,CAAC,aAAa,CAAI,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,GAAW,EAAE,GAAW,EAAE,OAA4B;QACxE,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvE,6DAA6D;QAC7D,IAAI,MAAM,GAAkB,IAAI,CAAC;QACjC,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;YACvB,MAAM,CAAC,GAAG,eAAe,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,GAAG;gBAAE,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC;iBACtC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,GAAG;gBAAE,MAAM;QACzC,CAAC;QACD,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,OAAO,IAAI,CAAC,aAAa,CAAI,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,KAAa;QACrC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvE,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;YACvB,MAAM,CAAC,GAAG,eAAe,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK;gBAAE,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;IAC/B,CAAC;IAED,4EAA4E;IAEpE,WAAW,CAAC,GAAW,EAAE,GAAW;QAC1C,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC;IAChF,CAAC;IAEO,SAAS,CAAC,GAAW;QAC3B,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,GAAG,CAAC;IACjC,CAAC;IAEO,KAAK,CAAC,aAAa,CACzB,GAAW,EACX,GAAW,EACX,OAA4B;QAE5B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,OAAO,CAAC,MAAM,EAAE;YAAE,OAAO,IAAI,CAAC;QAClC,wEAAwE;QACxE,sCAAsC;QACtC,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU;eACjC,iBAAiB,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/D,MAAM,SAAS,GAAG,oBAAoB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,MAAM,UAAU,CAC9B,OAAO,CAAC,KAAK,CAAC,IAAI,EAClB,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CACtD,CAAC;QACF,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,MAAkF,CAAC;QACvF,IAAI,CAAC;YAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC;QAClC,OAAO,CAAC,EAAE,CAAC;YACT,MAAM,IAAI,YAAY,CAAC,qDAAqD,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;QACxF,CAAC;QACD,OAAO,IAAI,CAAC;YACV,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,GAAW;QACpC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvE,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3D,KAAK,MAAM,EAAE,IAAI,QAAQ;YAAE,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAC/D,CAAC;CACF;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,iDAAiD;IACjD,MAAM,CAAC,GAAG,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC"}

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

@@ -0,0 +1,42 @@
+import { type SqliteDriver } from '../../runtime/sqlite/index.js';
+import { type Snapshot } from '../JournalTypes.js';
+import type { PersistenceOptions } from '../PersistenceOptions.js';
+import type { SnapshotStore } from '../SnapshotStore.js';
+import { type Option } from '../../util/Option.js';
+export interface SqliteSnapshotStoreOptions {
+    /** Path or ":memory:". Defaults to ":memory:". */
+    readonly path?: string;
+    /** Table name; default `snapshots`. */
+    readonly snapshotsTable?: string;
+    /** Maximum snapshots retained per persistenceId.  Older ones are pruned on save. */
+    readonly keepN?: number;
+    /**
+     * Explicit driver — useful for tests or when you want to pin a
+     * specific SQLite backend.  Default: auto-detect via `getSqliteDriver()`.
+     */
+    readonly driver?: SqliteDriver;
+}
+/**
+ * SQLite-backed SnapshotStore — JSON payloads, single table, prune-on-save.
+ * Works on Bun (`bun:sqlite`) and Node.js (`better-sqlite3`) via the
+ * `SqliteDriver` abstraction.  Construction is lazy (same pattern as
+ * `SqliteJournal`): the DB is opened on the first save / load call.
+ */
+export declare class SqliteSnapshotStore implements SnapshotStore {
+    private readonly options;
+    private readonly table;
+    private readonly keepN;
+    private closed;
+    private db;
+    private stmts;
+    private initPromise;
+    constructor(options?: SqliteSnapshotStoreOptions);
+    save<S>(pid: string, seq: number, state: S, _options?: PersistenceOptions): Promise<Snapshot<S>>;
+    loadLatest<S>(pid: string, _options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    loadBefore<S>(pid: string, seq: number, _options?: PersistenceOptions): Promise<Option<Snapshot<S>>>;
+    delete(pid: string, toSeq: number): Promise<void>;
+    close(): Promise<void>;
+    private ensureOpen;
+    private init;
+}
+//# sourceMappingURL=SqliteSnapshotStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteSnapshotStore.d.ts","sourceRoot":"","sources":["../../../src/persistence/snapshot-stores/SqliteSnapshotStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,YAAY,EAAwB,MAAM,+BAA+B,CAAC;AACxH,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,0BAA0B;IACzC,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAUD;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,WAAW,CAA8B;gBAErC,OAAO,GAAE,0BAA+B;IAM9C,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAgBhG,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAiBvF,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAiBpG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAQd,UAAU;YAOV,IAAI;CA+BnB"}

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

@@ -0,0 +1,108 @@
+import { getSqliteDriver } from '../../runtime/sqlite/index.js';
+import { JournalError } from '../JournalTypes.js';
+import { none, some } from '../../util/Option.js';
+/**
+ * SQLite-backed SnapshotStore — JSON payloads, single table, prune-on-save.
+ * Works on Bun (`bun:sqlite`) and Node.js (`better-sqlite3`) via the
+ * `SqliteDriver` abstraction.  Construction is lazy (same pattern as
+ * `SqliteJournal`): the DB is opened on the first save / load call.
+ */
+export class SqliteSnapshotStore {
+    options;
+    table;
+    keepN;
+    closed = false;
+    db = null;
+    stmts = null;
+    initPromise = null;
+    constructor(options = {}) {
+        this.options = options;
+        this.table = options.snapshotsTable ?? 'snapshots';
+        this.keepN = options.keepN ?? 3;
+    }
+    async save(pid, seq, state, _options) {
+        // SQLite store has no compression / encryption — options ignored.
+        await this.ensureOpen();
+        const stmts = this.stmts;
+        const now = Date.now();
+        try {
+            stmts.insert.run(pid, seq, JSON.stringify(state), now);
+            if (this.keepN > 0) {
+                stmts.deleteOlderThan.run(pid, pid, this.keepN);
+            }
+            return { persistenceId: pid, sequenceNr: seq, state, timestamp: now };
+        }
+        catch (e) {
+            throw new JournalError(`SqliteSnapshotStore.save failed: ${e.message}`, e);
+        }
+    }
+    async loadLatest(pid, _options) {
+        await this.ensureOpen();
+        const row = this.stmts.latest.get(pid);
+        if (!row)
+            return none;
+        return some({
+            persistenceId: row.persistence_id,
+            sequenceNr: row.sequence_nr,
+            state: JSON.parse(row.payload),
+            timestamp: row.timestamp,
+        });
+    }
+    async loadBefore(pid, seq, _options) {
+        await this.ensureOpen();
+        const row = this.stmts.before.get(pid, seq);
+        if (!row)
+            return none;
+        return some({
+            persistenceId: row.persistence_id,
+            sequenceNr: row.sequence_nr,
+            state: JSON.parse(row.payload),
+            timestamp: row.timestamp,
+        });
+    }
+    async delete(pid, toSeq) {
+        await this.ensureOpen();
+        this.stmts.deleteUpTo.run(pid, toSeq);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.db?.close();
+        }
+        catch { /* ignore */ }
+    }
+    /* --------------------------- internals -------------------------------- */
+    async ensureOpen() {
+        if (this.closed)
+            throw new JournalError('SqliteSnapshotStore is closed');
+        if (this.db && this.stmts)
+            return;
+        if (!this.initPromise)
+            this.initPromise = this.init();
+        await this.initPromise;
+    }
+    async init() {
+        const driver = this.options.driver ?? await getSqliteDriver();
+        const db = driver.open(this.options.path ?? ':memory:');
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.table} (
+        persistence_id TEXT NOT NULL,
+        sequence_nr    INTEGER NOT NULL,
+        payload        TEXT NOT NULL,
+        timestamp      INTEGER NOT NULL,
+        PRIMARY KEY (persistence_id, sequence_nr)
+      );
+    `);
+        this.stmts = {
+            insert: db.prepare(`INSERT OR REPLACE INTO ${this.table}(persistence_id, sequence_nr, payload, timestamp) VALUES (?, ?, ?, ?)`),
+            latest: db.prepare(`SELECT persistence_id, sequence_nr, payload, timestamp FROM ${this.table} WHERE persistence_id = ? ORDER BY sequence_nr DESC LIMIT 1`),
+            before: db.prepare(`SELECT persistence_id, sequence_nr, payload, timestamp FROM ${this.table} WHERE persistence_id = ? AND sequence_nr < ? ORDER BY sequence_nr DESC LIMIT 1`),
+            deleteUpTo: db.prepare(`DELETE FROM ${this.table} WHERE persistence_id = ? AND sequence_nr <= ?`),
+            deleteOlderThan: db.prepare(`DELETE FROM ${this.table} WHERE persistence_id = ? AND sequence_nr NOT IN (SELECT sequence_nr FROM ${this.table} WHERE persistence_id = ? ORDER BY sequence_nr DESC LIMIT ?)`),
+        };
+        this.db = db;
+    }
+}
+//# sourceMappingURL=SqliteSnapshotStore.js.map

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

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

package/dist/persistence/storage/KeyValidator.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared factory for backend-specific key-validation functions.
+ *
+ * Storage and cache backends each have slightly different rules for
+ * what makes a "safe" key — Memcached forbids whitespace because of
+ * its text protocol, the filesystem forbids `..` segments because of
+ * path traversal, S3 has its own constraints, and so on.  Before
+ * this module existed, each backend had a hand-rolled
+ * `assertSafeXxxKey` function with subtle drift between sites.
+ *
+ * `makeKeyValidator(rules)` materialises a `(key: string) => void`
+ * validator from a declarative `KeyValidationRules` object.  The
+ * rules cover the union of all checks any current backend cares
+ * about; individual backends select the rules that apply to them
+ * via the pre-defined `*KeyRules` constants below.
+ *
+ * Adding a new backend (S3, GCS, …): create a new `XxxKeyRules`
+ * constant, instantiate the validator via `makeKeyValidator`, call
+ * it on every key the backend touches.  No bespoke validator code
+ * needed.
+ *
+ * **Security-critical**: this module is the front-line for path-
+ * traversal and protocol-injection defences.  Changes to the rules
+ * must preserve every rejected-input the pre-refactor validators
+ * caught.  Adversarial test cases live alongside each backend.
+ */
+export interface KeyValidationRules {
+    /** Error constructor used for every thrown rejection. */
+    readonly errorClass: new (msg: string) => Error;
+    /**
+     * Phrase prepended to every rejection message — typically the
+     * backend name ('memcached key', 'invalid key' for FS, etc.).
+     */
+    readonly errorPrefix: string;
+    /** Minimum key length.  Default: 1 (non-empty). */
+    readonly minLength?: number;
+    /** Maximum key length.  Default: unbounded. */
+    readonly maxLength?: number;
+    /**
+     * Reject NUL bytes (`\0`).  C-level APIs treat NUL as terminator;
+     * letting it pass would let an attacker truncate keys.  Default: true.
+     */
+    readonly rejectNul?: boolean;
+    /**
+     * Reject all ASCII control characters (0x00–0x1F, 0x7F).
+     * Memcached's text protocol uses these as command separators —
+     * passing one through is a protocol-injection vector.  Default: false.
+     * (Implies `rejectNul` if set.)
+     */
+    readonly rejectControlChars?: boolean;
+    /**
+     * Reject the ASCII space character (0x20).  Memcached treats space
+     * as a command delimiter.  Default: false.
+     */
+    readonly rejectSpace?: boolean;
+    /**
+     * Reject keys that look like absolute paths.  POSIX leading `/`,
+     * Windows leading `\\` or drive-letter (`C:\` / `C:/`).  Required
+     * for filesystem keys — `path.join('/safe', '/etc/passwd')` returns
+     * `'/etc/passwd'`, defeating any root check.  Default: false.
+     */
+    readonly rejectAbsolutePaths?: boolean;
+    /**
+     * Reject keys containing a `..` segment when split on path
+     * separators.  Required for filesystem keys — `..` collapses up
+     * the tree on `path.resolve()`.  Default: false.
+     */
+    readonly rejectRelativeTraversal?: boolean;
+}
+/**
+ * Build a key-validator function from a rule set.  Returns
+ * `(key: string) => void` that throws on rejected input.
+ *
+ * Validator semantics: short-circuits on the first failed rule.
+ * Order of checks: type/length → NUL → control chars → space →
+ * absolute path → traversal segments.  Per-rule comments below
+ * document the precedence rationale.
+ */
+export declare function makeKeyValidator(rules: KeyValidationRules): (key: string) => void;
+//# sourceMappingURL=KeyValidator.d.ts.map

package/dist/persistence/storage/KeyValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyValidator.d.ts","sourceRoot":"","sources":["../../../src/persistence/storage/KeyValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,EAAE,MAAM,KAAK,KAAK,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAoEjF"}

package/dist/persistence/storage/KeyValidator.js

@@ -0,0 +1,88 @@
+/**
+ * Shared factory for backend-specific key-validation functions.
+ *
+ * Storage and cache backends each have slightly different rules for
+ * what makes a "safe" key — Memcached forbids whitespace because of
+ * its text protocol, the filesystem forbids `..` segments because of
+ * path traversal, S3 has its own constraints, and so on.  Before
+ * this module existed, each backend had a hand-rolled
+ * `assertSafeXxxKey` function with subtle drift between sites.
+ *
+ * `makeKeyValidator(rules)` materialises a `(key: string) => void`
+ * validator from a declarative `KeyValidationRules` object.  The
+ * rules cover the union of all checks any current backend cares
+ * about; individual backends select the rules that apply to them
+ * via the pre-defined `*KeyRules` constants below.
+ *
+ * Adding a new backend (S3, GCS, …): create a new `XxxKeyRules`
+ * constant, instantiate the validator via `makeKeyValidator`, call
+ * it on every key the backend touches.  No bespoke validator code
+ * needed.
+ *
+ * **Security-critical**: this module is the front-line for path-
+ * traversal and protocol-injection defences.  Changes to the rules
+ * must preserve every rejected-input the pre-refactor validators
+ * caught.  Adversarial test cases live alongside each backend.
+ */
+/**
+ * Build a key-validator function from a rule set.  Returns
+ * `(key: string) => void` that throws on rejected input.
+ *
+ * Validator semantics: short-circuits on the first failed rule.
+ * Order of checks: type/length → NUL → control chars → space →
+ * absolute path → traversal segments.  Per-rule comments below
+ * document the precedence rationale.
+ */
+export function makeKeyValidator(rules) {
+    const { errorClass, errorPrefix, minLength = 1, maxLength, rejectNul = true, rejectControlChars = false, rejectSpace = false, rejectAbsolutePaths = false, rejectRelativeTraversal = false, } = rules;
+    return (key) => {
+        // Type + length first — every subsequent check assumes a non-empty
+        // string of the right type.
+        if (typeof key !== 'string' || key.length < minLength) {
+            throw new errorClass(`${errorPrefix}: must be a non-empty string`);
+        }
+        if (maxLength !== undefined && key.length > maxLength) {
+            throw new errorClass(`${errorPrefix}: exceeds ${maxLength}-byte limit (got ${key.length})`);
+        }
+        // Control chars cover NUL and more — Memcached protocol injection
+        // vector.  Checked BEFORE the NUL-only check so the sharper
+        // "control character (charCode=N)" message wins when both rules
+        // are on (matches the pre-refactor MemcachedCache behaviour).
+        if (rejectControlChars) {
+            for (let i = 0; i < key.length; i++) {
+                const c = key.charCodeAt(i);
+                if (c <= 0x1F || c === 0x7F) {
+                    throw new errorClass(`${errorPrefix}: contains control character at index ${i} ` +
+                        `(charCode=${c}) — would allow protocol injection`);
+                }
+            }
+        }
+        // NUL byte — handled when `rejectControlChars` is OFF (e.g. for
+        // filesystem keys, where we want to reject \0 but allow other
+        // control chars in legitimate filenames if any user code ever
+        // does that).  Sharper error message than the generic
+        // control-char rule.
+        if (rejectNul && !rejectControlChars && key.includes('\0')) {
+            throw new errorClass(`${errorPrefix}: NUL byte not allowed`);
+        }
+        if (rejectSpace) {
+            const spaceIdx = key.indexOf(' ');
+            if (spaceIdx >= 0) {
+                throw new errorClass(`${errorPrefix}: contains space at index ${spaceIdx} — would allow protocol injection`);
+            }
+        }
+        // Absolute-path rejection — POSIX `/foo`, Windows `\foo`, drive-letter.
+        if (rejectAbsolutePaths && (key.startsWith('/') || key.startsWith('\\') || /^[a-zA-Z]:[\\/]/.test(key))) {
+            throw new errorClass(`${errorPrefix}: absolute paths not allowed (got ${key})`);
+        }
+        // Relative-traversal: split on either separator since FS code uses
+        // path.join which is platform-aware.
+        if (rejectRelativeTraversal) {
+            const segs = key.split(/[/\\]/);
+            if (segs.some((s) => s === '..')) {
+                throw new errorClass(`${errorPrefix}: path-traversal segments ("..") not allowed (got ${key})`);
+            }
+        }
+    };
+}
+//# sourceMappingURL=KeyValidator.js.map

package/dist/persistence/storage/KeyValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyValidator.js","sourceRoot":"","sources":["../../../src/persistence/storage/KeyValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA8CH;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAyB;IACxD,MAAM,EACJ,UAAU,EACV,WAAW,EACX,SAAS,GAAG,CAAC,EACb,SAAS,EACT,SAAS,GAAG,IAAI,EAChB,kBAAkB,GAAG,KAAK,EAC1B,WAAW,GAAG,KAAK,EACnB,mBAAmB,GAAG,KAAK,EAC3B,uBAAuB,GAAG,KAAK,GAChC,GAAG,KAAK,CAAC;IAEV,OAAO,CAAC,GAAW,EAAQ,EAAE;QAC3B,mEAAmE;QACnE,4BAA4B;QAC5B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;YACtD,MAAM,IAAI,UAAU,CAAC,GAAG,WAAW,8BAA8B,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,SAAS,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;YACtD,MAAM,IAAI,UAAU,CAAC,GAAG,WAAW,aAAa,SAAS,oBAAoB,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QAC9F,CAAC;QACD,kEAAkE;QAClE,4DAA4D;QAC5D,gEAAgE;QAChE,8DAA8D;QAC9D,IAAI,kBAAkB,EAAE,CAAC;YACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACpC,MAAM,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;gBAC5B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;oBAC5B,MAAM,IAAI,UAAU,CAClB,GAAG,WAAW,yCAAyC,CAAC,GAAG;wBAC3D,aAAa,CAAC,oCAAoC,CACnD,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QACD,gEAAgE;QAChE,8DAA8D;QAC9D,8DAA8D;QAC9D,sDAAsD;QACtD,qBAAqB;QACrB,IAAI,SAAS,IAAI,CAAC,kBAAkB,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,UAAU,CAAC,GAAG,WAAW,wBAAwB,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;gBAClB,MAAM,IAAI,UAAU,CAClB,GAAG,WAAW,6BAA6B,QAAQ,mCAAmC,CACvF,CAAC;YACJ,CAAC;QACH,CAAC;QACD,wEAAwE;QACxE,IAAI,mBAAmB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACxG,MAAM,IAAI,UAAU,CAAC,GAAG,WAAW,qCAAqC,GAAG,GAAG,CAAC,CAAC;QAClF,CAAC;QACD,mEAAmE;QACnE,qCAAqC;QACrC,IAAI,uBAAuB,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAChC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;gBACjC,MAAM,IAAI,UAAU,CAClB,GAAG,WAAW,qDAAqD,GAAG,GAAG,CAC1E,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/runtime/detect.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Runtime detection for actor-ts.
+ *
+ * The framework runs on three JS runtimes — Bun, Node.js, and Deno.  Most of
+ * the codebase is runtime-neutral TypeScript that uses `node:*` modules or
+ * standard Web APIs, but a few capabilities (TCP sockets, HTTP-server-from-
+ * fetch-handler, Web Workers, SQLite) need a per-runtime backend.  This
+ * module is the shared place where those backends ask "what am I running
+ * under?" so the answer is cached, consistent, and overridable in tests.
+ *
+ * The module has no dependencies and no side effects beyond the memoised
+ * cache — it is safe to import from any layer.
+ */
+export type RuntimeKind = 'bun' | 'node' | 'deno';
+/** Returns the current runtime.  Cached after first call. */
+export declare function detectRuntime(): RuntimeKind;
+/** True iff `globalThis.Bun` is present. */
+export declare function hasBun(): boolean;
+/** True iff `globalThis.Deno` is present. */
+export declare function hasDeno(): boolean;
+/**
+ * High-resolution timestamp in nanoseconds.  Uses `Bun.nanoseconds()` when
+ * available (it is truly ns-resolution); otherwise falls back to
+ * `performance.now() * 1e6` which is ms-resolution × 1_000_000 — ~µs
+ * precision on Node 20+ and Deno, still good enough for benchmark harness
+ * purposes (individual iteration jitter swamps any sub-µs accuracy).
+ */
+export declare function highResNow(): number;
+/**
+ * Test-only hook: force `detectRuntime()` to return a specific value.  Pass
+ * `null` to restore real detection.  Intentionally NOT re-exported from
+ * `src/index.ts` — it is an internal seam.
+ */
+export declare function setRuntimeOverride(r: RuntimeKind | null): void;
+//# sourceMappingURL=detect.d.ts.map

package/dist/runtime/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/runtime/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAwBlD,6DAA6D;AAC7D,wBAAgB,aAAa,IAAI,WAAW,CAA8B;AAE1E,4CAA4C;AAC5C,wBAAgB,MAAM,IAAI,OAAO,CAAyC;AAE1E,6CAA6C;AAC7C,wBAAgB,OAAO,IAAI,OAAO,CAA0C;AAE5E;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAQnC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAE9D"}

package/dist/runtime/detect.js

@@ -0,0 +1,60 @@
+/**
+ * Runtime detection for actor-ts.
+ *
+ * The framework runs on three JS runtimes — Bun, Node.js, and Deno.  Most of
+ * the codebase is runtime-neutral TypeScript that uses `node:*` modules or
+ * standard Web APIs, but a few capabilities (TCP sockets, HTTP-server-from-
+ * fetch-handler, Web Workers, SQLite) need a per-runtime backend.  This
+ * module is the shared place where those backends ask "what am I running
+ * under?" so the answer is cached, consistent, and overridable in tests.
+ *
+ * The module has no dependencies and no side effects beyond the memoised
+ * cache — it is safe to import from any layer.
+ */
+const g = globalThis;
+import { Lazy } from '../util/Lazy.js';
+/**
+ * The detected runtime.  `Lazy.of(...)` runs the detection once and then
+ * memoises.  Test overrides go through `setOverride` (below) which uses
+ * `Lazy.setOverride` under the hood — no explicit cache bookkeeping.
+ */
+const runtimeLazy = Lazy.of(() => {
+    if (typeof g.Bun !== 'undefined')
+        return 'bun';
+    if (typeof g.Deno !== 'undefined')
+        return 'deno';
+    return 'node';
+});
+/** Returns the current runtime.  Cached after first call. */
+export function detectRuntime() { return runtimeLazy.get(); }
+/** True iff `globalThis.Bun` is present. */
+export function hasBun() { return typeof g.Bun !== 'undefined'; }
+/** True iff `globalThis.Deno` is present. */
+export function hasDeno() { return typeof g.Deno !== 'undefined'; }
+/**
+ * High-resolution timestamp in nanoseconds.  Uses `Bun.nanoseconds()` when
+ * available (it is truly ns-resolution); otherwise falls back to
+ * `performance.now() * 1e6` which is ms-resolution × 1_000_000 — ~µs
+ * precision on Node 20+ and Deno, still good enough for benchmark harness
+ * purposes (individual iteration jitter swamps any sub-µs accuracy).
+ */
+export function highResNow() {
+    const bunNs = g.Bun?.nanoseconds;
+    if (typeof bunNs === 'function')
+        return bunNs();
+    const perf = g.performance;
+    if (perf && typeof perf.now === 'function')
+        return perf.now() * 1_000_000;
+    // Last-resort: Date.now() has ms resolution.  Any benchmark running in
+    // such a degraded environment deserves what it gets.
+    return Date.now() * 1_000_000;
+}
+/**
+ * Test-only hook: force `detectRuntime()` to return a specific value.  Pass
+ * `null` to restore real detection.  Intentionally NOT re-exported from
+ * `src/index.ts` — it is an internal seam.
+ */
+export function setRuntimeOverride(r) {
+    runtimeLazy.setOverride(r);
+}
+//# sourceMappingURL=detect.js.map

package/dist/runtime/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/runtime/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,MAAM,CAAC,GAAgB,UAAoC,CAAC;AAE5D,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC;;;;GAIG;AACH,MAAM,WAAW,GAAsB,IAAI,CAAC,EAAE,CAAc,GAAG,EAAE;IAC/D,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IACjD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC,CAAC;AAEH,6DAA6D;AAC7D,MAAM,UAAU,aAAa,KAAkB,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AAE1E,4CAA4C;AAC5C,MAAM,UAAU,MAAM,KAAc,OAAO,OAAO,CAAC,CAAC,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC;AAE1E,6CAA6C;AAC7C,MAAM,UAAU,OAAO,KAAc,OAAO,OAAO,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,EAAE,WAAW,CAAC;IACjC,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,KAAK,EAAE,CAAC;IAChD,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC;IAC3B,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAC1E,uEAAuE;IACvE,qDAAqD;IACrD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAqB;IACtD,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/runtime/http/BunHonoRunner.d.ts

@@ -0,0 +1,16 @@
+import type { FetchHandler, HonoServerHandle, HonoServerRunner } from './HonoServerRunner.js';
+/**
+ * Bun implementation — `Bun.serve({ hostname, port, fetch })`.
+ *
+ * Graceful stop calls `server.stop(false)` which lets in-flight requests
+ * finish.  Non-graceful calls `server.stop(true)` which kicks active
+ * connections immediately.
+ */
+export declare class BunHonoRunner implements HonoServerRunner {
+    serve(opts: {
+        host: string;
+        port: number;
+        fetch: FetchHandler;
+    }): Promise<HonoServerHandle>;
+}
+//# sourceMappingURL=BunHonoRunner.d.ts.map