actor-ts 0.9.0

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

@@ -0,0 +1,31 @@
+/**
+ * Per-snapshot compression.  Three modes:
+ *   - `none` — store raw bytes.  Right choice for already-compressed payloads
+ *     or very small ones where overhead beats savings.
+ *   - `gzip` — `node:zlib` everywhere (Bun, Node, Deno).  No extra deps.
+ *   - `zstd` — preferred for large state blobs.  Tries native runtime
+ *     support first (Node ≥22.15 or Bun); falls back to the optional
+ *     `fzstd` peer dependency.  If neither is available and the user
+ *     selected `zstd`, the very first compress / decompress call throws
+ *     a clear "install fzstd" error.
+ */
+export type CompressionAlgo = 'none' | 'gzip' | 'zstd';
+export interface Compressor {
+    compress(input: Uint8Array): Promise<Uint8Array>;
+    decompress(input: Uint8Array): Promise<Uint8Array>;
+}
+/** Get a `Compressor` for the requested algorithm.  Cached per-algorithm. */
+export declare function compressorFor(algo: CompressionAlgo): Compressor;
+/**
+ * Probe whether the runtime / peer-dep needed by `algo` is loadable.
+ * Resolves on success, throws with a clear "install X" message on
+ * failure.  Idempotent — under the hood this just kicks the same lazy
+ * `compressorFor()` would use, so the result is cached.
+ *
+ * Used by `registerObjectStoragePlugins` to surface peer-dep failures
+ * at plugin-init time rather than on the first persist call (#18, #59).
+ */
+export declare function probeCompressionAvailability(algo: CompressionAlgo): Promise<void>;
+/** Test hook — clear cached lazy implementations. */
+export declare function resetCompressionCache(): void;
+//# sourceMappingURL=Compression.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Compression.d.ts","sourceRoot":"","sources":["../../../src/persistence/object-storage/Compression.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjD,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACpD;AAoGD,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,CAO/D;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED,qDAAqD;AACrD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C"}

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

@@ -0,0 +1,99 @@
+import { match } from 'ts-pattern';
+import { Lazy } from '../../util/Lazy.js';
+/* ------------------------------- gzip ----------------------------------- */
+const gzipLazy = Lazy.of(async () => {
+    const name = 'node:zlib';
+    const zlib = (await import(name));
+    return {
+        gzip: async (input) => zlib.gzipSync(input),
+        gunzip: async (input) => zlib.gunzipSync(input),
+    };
+});
+const gzipCompressor = {
+    async compress(input) { return (await gzipLazy.get()).gzip(input); },
+    async decompress(input) { return (await gzipLazy.get()).gunzip(input); },
+};
+const zstdLazy = Lazy.of(async () => {
+    // 1. Bun: `Bun.zstdCompressSync` / `zstdDecompressSync` (added in Bun 1.1).
+    const bun = globalThis.Bun;
+    if (bun?.zstdCompressSync && bun.zstdDecompressSync) {
+        const compressFn = bun.zstdCompressSync;
+        const decompressFn = bun.zstdDecompressSync;
+        return {
+            compress: async (i) => compressFn(i),
+            decompress: async (i) => decompressFn(i),
+            source: 'bun-native',
+        };
+    }
+    // 2. Node 22.15+: `zlib.zstdCompressSync` / `zstdDecompressSync`.
+    try {
+        const zlibName = 'node:zlib';
+        const zlib = (await import(zlibName));
+        if (zlib.zstdCompressSync && zlib.zstdDecompressSync) {
+            const compressFn = zlib.zstdCompressSync;
+            const decompressFn = zlib.zstdDecompressSync;
+            return {
+                compress: async (i) => compressFn(i),
+                decompress: async (i) => decompressFn(i),
+                source: 'node-zlib',
+            };
+        }
+    }
+    catch { /* node:zlib unavailable — fall through to fzstd */ }
+    // 3. fzstd peer-dep — pure JS, cross-runtime, ~14 KB.
+    try {
+        const fzstdName = 'fzstd';
+        const fzstd = (await import(fzstdName));
+        return {
+            compress: async (i) => fzstd.compress(i),
+            decompress: async (i) => fzstd.decompress(i),
+            source: 'fzstd',
+        };
+    }
+    catch (e) {
+        throw new Error('No zstd implementation available.  Either upgrade to Bun 1.1+ / '
+            + 'Node 22.15+, or install the `fzstd` peer dependency: '
+            + '`npm install fzstd`.\nOriginal error: '
+            + (e instanceof Error ? e.message : String(e)));
+    }
+});
+const zstdCompressor = {
+    async compress(input) { return (await zstdLazy.get()).compress(input); },
+    async decompress(input) { return (await zstdLazy.get()).decompress(input); },
+};
+/* ------------------------------- public --------------------------------- */
+const noneCompressor = {
+    async compress(input) { return input; },
+    async decompress(input) { return input; },
+};
+/** Get a `Compressor` for the requested algorithm.  Cached per-algorithm. */
+export function compressorFor(algo) {
+    // Exhaustive — adding a new CompressionAlgo variant forces this site.
+    return match(algo)
+        .with('none', () => noneCompressor)
+        .with('gzip', () => gzipCompressor)
+        .with('zstd', () => zstdCompressor)
+        .exhaustive();
+}
+/**
+ * Probe whether the runtime / peer-dep needed by `algo` is loadable.
+ * Resolves on success, throws with a clear "install X" message on
+ * failure.  Idempotent — under the hood this just kicks the same lazy
+ * `compressorFor()` would use, so the result is cached.
+ *
+ * Used by `registerObjectStoragePlugins` to surface peer-dep failures
+ * at plugin-init time rather than on the first persist call (#18, #59).
+ */
+export async function probeCompressionAvailability(algo) {
+    await match(algo)
+        .with('none', async () => undefined)
+        .with('gzip', async () => { await gzipLazy.get(); })
+        .with('zstd', async () => { await zstdLazy.get(); })
+        .exhaustive();
+}
+/** Test hook — clear cached lazy implementations. */
+export function resetCompressionCache() {
+    gzipLazy.reset();
+    zstdLazy.reset();
+}
+//# sourceMappingURL=Compression.js.map

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

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

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

@@ -0,0 +1,73 @@
+/**
+ * Client-side encryption helpers for snapshots / durable-state bodies.
+ *
+ * Uses WebCrypto (`globalThis.crypto.subtle`) — present on Bun, Node 20+,
+ * and Deno without any extra import.  AES-256-GCM is the standard
+ * authenticated-encryption mode; the IV is per-message (12 bytes) and
+ * the auth tag is appended to the ciphertext by the algorithm.
+ *
+ * Subkeys per `persistenceId` are derived via HKDF-SHA256 from a single
+ * master key.  The user provides the master key once (via env var,
+ * Secrets Manager, …); we derive a unique subkey per pid so a leaked
+ * subkey only compromises one pid's snapshots, not the entire bucket.
+ */
+/**
+ * Probe whether WebCrypto is available.  Resolves on success, throws
+ * the same clear error `getSubtle` would throw on failure.  Called
+ * eagerly by `registerObjectStoragePlugins` when an encryption config
+ * is supplied so the failure surfaces at plugin-init rather than the
+ * first save call.
+ */
+export declare function probeEncryptionAvailability(): Promise<void>;
+/** Length of the AES-GCM IV we use, in bytes. */
+export declare const IV_LENGTH = 12;
+/** Length of the AES-256 key we derive, in bytes. */
+export declare const KEY_LENGTH = 32;
+/**
+ * Derive a 32-byte subkey from `masterKey` using HKDF-SHA256.  The
+ * `persistenceId` is used as the HKDF `salt` so two different pids
+ * produce two different subkeys; `info` is a domain-separator string.
+ */
+export declare function deriveSubkey(masterKey: Uint8Array, persistenceId: string, info?: string): Promise<Uint8Array>;
+/**
+ * AES-256-GCM encrypt — returns the ciphertext (with appended auth tag,
+ * the standard WebCrypto layout).  The IV is supplied by the caller so
+ * `BodyCodec` can put it in the manifest header.
+ */
+export declare function aesGcmEncrypt(subkey: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
+/** AES-256-GCM decrypt — throws if the auth tag doesn't validate. */
+export declare function aesGcmDecrypt(subkey: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
+/** Generate a fresh random IV. */
+export declare function randomIv(): Uint8Array;
+import type { EncryptionConfig } from '../PersistenceOptions.js';
+import type { SubKeyResolver } from './BodyCodec.js';
+/**
+ * Resolve the encrypt-side parameters for a `client-aes256-gcm`
+ * config: the per-pid subkey derived from the ACTIVE master key plus
+ * the version byte to embed in the body manifest (#8 — master-key
+ * rotation).  Returns `undefined` for non-encrypting modes so callers
+ * can pass-through to the no-encryption path.
+ */
+export declare function activeEncryptKey(encryption: EncryptionConfig, pid: string): Promise<{
+    subKey: Uint8Array;
+    keyVersion: number;
+} | undefined>;
+/**
+ * Build a {@link SubKeyResolver} for decryption that dispatches on the
+ * key version byte from the manifest.  For the legacy single-key
+ * shape, the resolver always returns the single subkey regardless of
+ * version (which means the legacy `masterKey` is treated as
+ * "version 0" — backwards-compatible with bodies written before
+ * versioning landed).  For the keyring shape, walks `active +
+ * retired` looking for a matching version.
+ */
+export declare function resolveDecryptSubkey(encryption: EncryptionConfig, pid: string): SubKeyResolver | undefined;
+/**
+ * Decide whether the encode path should use the new versioned-key
+ * wire format.  Bodies written under the legacy single-key shape
+ * stay unversioned (FLAG_KEY_VERSIONED unset) so they can still be
+ * read by code from before #8 landed.  The keyring shape always
+ * writes versioned bodies.
+ */
+export declare function isVersionedKeyShape(encryption: EncryptionConfig): boolean;
+//# sourceMappingURL=Encryption.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Encryption.d.ts","sourceRoot":"","sources":["../../../src/persistence/object-storage/Encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsBH;;;;;;GAMG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjE;AAED,iDAAiD;AACjD,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,qDAAqD;AACrD,eAAO,MAAM,UAAU,KAAK,CAAC;AAI7B;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,UAAU,EACrB,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,MAA+B,GACpC,OAAO,CAAC,UAAU,CAAC,CAiBrB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,UAAU,EACd,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,UAAU,CAAC,CAiBrB;AAED,qEAAqE;AACrE,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,UAAU,CAAC,CAerB;AAED,kCAAkC;AAClC,wBAAgB,QAAQ,IAAI,UAAU,CAIrC;AAID,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GACxC,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAgBjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GACxC,cAAc,GAAG,SAAS,CAkB5B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAEzE"}

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

@@ -0,0 +1,167 @@
+/**
+ * Client-side encryption helpers for snapshots / durable-state bodies.
+ *
+ * Uses WebCrypto (`globalThis.crypto.subtle`) — present on Bun, Node 20+,
+ * and Deno without any extra import.  AES-256-GCM is the standard
+ * authenticated-encryption mode; the IV is per-message (12 bytes) and
+ * the auth tag is appended to the ciphertext by the algorithm.
+ *
+ * Subkeys per `persistenceId` are derived via HKDF-SHA256 from a single
+ * master key.  The user provides the master key once (via env var,
+ * Secrets Manager, …); we derive a unique subkey per pid so a leaked
+ * subkey only compromises one pid's snapshots, not the entire bucket.
+ */
+/**
+ * Lazily resolve `SubtleCrypto`.  Capturing it at module load (the old
+ * approach) crashed the import itself on runtimes without WebCrypto;
+ * deferring the lookup lets `probeEncryptionAvailability` surface a
+ * clear "WebCrypto not available" error at registration time instead
+ * (#18, #59).
+ */
+function getSubtle() {
+    const s = globalThis.crypto?.subtle;
+    if (!s) {
+        throw new Error('SubtleCrypto is not available in this runtime.  Client-side '
+            + 'encryption requires WebCrypto support — Node 20+, Bun, or '
+            + 'Deno.  In bundled/edge environments, ensure the bundler '
+            + 'includes a WebCrypto polyfill.');
+    }
+    return s;
+}
+/**
+ * Probe whether WebCrypto is available.  Resolves on success, throws
+ * the same clear error `getSubtle` would throw on failure.  Called
+ * eagerly by `registerObjectStoragePlugins` when an encryption config
+ * is supplied so the failure surfaces at plugin-init rather than the
+ * first save call.
+ */
+export async function probeEncryptionAvailability() {
+    getSubtle();
+}
+/** Length of the AES-GCM IV we use, in bytes. */
+export const IV_LENGTH = 12;
+/** Length of the AES-256 key we derive, in bytes. */
+export const KEY_LENGTH = 32;
+const utf8 = new TextEncoder();
+/**
+ * Derive a 32-byte subkey from `masterKey` using HKDF-SHA256.  The
+ * `persistenceId` is used as the HKDF `salt` so two different pids
+ * produce two different subkeys; `info` is a domain-separator string.
+ */
+export async function deriveSubkey(masterKey, persistenceId, info = 'actor-ts/snapshot/v1') {
+    if (masterKey.byteLength !== KEY_LENGTH) {
+        throw new Error(`encryption masterKey must be ${KEY_LENGTH} bytes, got ${masterKey.byteLength}`);
+    }
+    const subtle = getSubtle();
+    const baseKey = await subtle.importKey('raw', masterKey, 'HKDF', false, ['deriveBits']);
+    const derived = await subtle.deriveBits({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: utf8.encode(persistenceId),
+        info: utf8.encode(info),
+    }, baseKey, KEY_LENGTH * 8);
+    return new Uint8Array(derived);
+}
+/**
+ * AES-256-GCM encrypt — returns the ciphertext (with appended auth tag,
+ * the standard WebCrypto layout).  The IV is supplied by the caller so
+ * `BodyCodec` can put it in the manifest header.
+ */
+export async function aesGcmEncrypt(subkey, iv, plaintext) {
+    if (subkey.byteLength !== KEY_LENGTH) {
+        throw new Error(`subkey must be ${KEY_LENGTH} bytes`);
+    }
+    if (iv.byteLength !== IV_LENGTH) {
+        throw new Error(`iv must be ${IV_LENGTH} bytes`);
+    }
+    // The casts work around TypeScript 5.7+'s overly-strict DOM typings, where
+    // `Uint8Array<ArrayBufferLike>` doesn't subtype `BufferSource` cleanly.
+    const subtle = getSubtle();
+    const key = await subtle.importKey('raw', subkey, { name: 'AES-GCM' }, false, ['encrypt']);
+    const ciphertext = await subtle.encrypt({ name: 'AES-GCM', iv: iv }, key, plaintext);
+    return new Uint8Array(ciphertext);
+}
+/** AES-256-GCM decrypt — throws if the auth tag doesn't validate. */
+export async function aesGcmDecrypt(subkey, iv, ciphertext) {
+    if (subkey.byteLength !== KEY_LENGTH) {
+        throw new Error(`subkey must be ${KEY_LENGTH} bytes`);
+    }
+    if (iv.byteLength !== IV_LENGTH) {
+        throw new Error(`iv must be ${IV_LENGTH} bytes`);
+    }
+    const subtle = getSubtle();
+    const key = await subtle.importKey('raw', subkey, { name: 'AES-GCM' }, false, ['decrypt']);
+    const plaintext = await subtle.decrypt({ name: 'AES-GCM', iv: iv }, key, ciphertext);
+    return new Uint8Array(plaintext);
+}
+/** Generate a fresh random IV. */
+export function randomIv() {
+    const iv = new Uint8Array(IV_LENGTH);
+    globalThis.crypto.getRandomValues(iv);
+    return iv;
+}
+/**
+ * Resolve the encrypt-side parameters for a `client-aes256-gcm`
+ * config: the per-pid subkey derived from the ACTIVE master key plus
+ * the version byte to embed in the body manifest (#8 — master-key
+ * rotation).  Returns `undefined` for non-encrypting modes so callers
+ * can pass-through to the no-encryption path.
+ */
+export async function activeEncryptKey(encryption, pid) {
+    if (encryption.mode !== 'client-aes256-gcm')
+        return undefined;
+    if ('masterKeys' in encryption) {
+        const active = encryption.masterKeys.active;
+        return {
+            subKey: await deriveSubkey(active.key, pid, encryption.info),
+            keyVersion: active.version,
+        };
+    }
+    // Legacy single-key shape — implicit version 0.  We deliberately do
+    // NOT set FLAG_KEY_VERSIONED at the codec layer for this path so old
+    // readers (pre-#8) keep working unchanged.
+    return {
+        subKey: await deriveSubkey(encryption.masterKey, pid, encryption.info),
+        keyVersion: 0,
+    };
+}
+/**
+ * Build a {@link SubKeyResolver} for decryption that dispatches on the
+ * key version byte from the manifest.  For the legacy single-key
+ * shape, the resolver always returns the single subkey regardless of
+ * version (which means the legacy `masterKey` is treated as
+ * "version 0" — backwards-compatible with bodies written before
+ * versioning landed).  For the keyring shape, walks `active +
+ * retired` looking for a matching version.
+ */
+export function resolveDecryptSubkey(encryption, pid) {
+    if (encryption.mode !== 'client-aes256-gcm')
+        return undefined;
+    if ('masterKeys' in encryption) {
+        const ring = encryption.masterKeys;
+        return async (version) => {
+            if (ring.active.version === version) {
+                return deriveSubkey(ring.active.key, pid, encryption.info);
+            }
+            const retired = ring.retired?.find((r) => r.version === version);
+            if (retired)
+                return deriveSubkey(retired.key, pid, encryption.info);
+            return null;
+        };
+    }
+    // Legacy single-key — the version byte is informational only.
+    // Derive once and return the same subkey for any version request.
+    const masterKey = encryption.masterKey;
+    return async (_version) => deriveSubkey(masterKey, pid, encryption.info);
+}
+/**
+ * Decide whether the encode path should use the new versioned-key
+ * wire format.  Bodies written under the legacy single-key shape
+ * stay unversioned (FLAG_KEY_VERSIONED unset) so they can still be
+ * read by code from before #8 landed.  The keyring shape always
+ * writes versioned bodies.
+ */
+export function isVersionedKeyShape(encryption) {
+    return encryption.mode === 'client-aes256-gcm' && 'masterKeys' in encryption;
+}
+//# sourceMappingURL=Encryption.js.map

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

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

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

@@ -0,0 +1,79 @@
+import { type Option } from '../../util/Option.js';
+import { type ObjectFetched, type ObjectInfo, type ObjectStorageBackend, type PutOptions } from './ObjectStorageBackend.js';
+/**
+ * Filesystem-backed `ObjectStorageBackend` — stores each object as a file
+ * under a root directory, with the storage key mapped 1:1 to a relative
+ * path.  Suitable for unit tests, local development, and "S3-API parity
+ * without the cloud", and **safe for concurrent multi-process writers**:
+ * every `put` / `delete` acquires a per-key advisory file lock (atomic
+ * `O_EXCL` create) so the CAS check + write block is serialized at the
+ * filesystem layer, and writes use a temp-file + rename so concurrent
+ * readers never observe a half-written object.
+ *
+ * The backend lazy-imports `node:fs/promises` and `node:path` so this
+ * module is harmless to include on Bun / Deno where those built-ins
+ * already exist (Node-compat layer) — only the actual operations touch
+ * them.
+ *
+ * Implementation notes:
+ *
+ *  - **Disk is canonical.**  Etags are content-derived
+ *    ({@link computeEtag} — deterministic FNV-1a + length).  No in-memory
+ *    map; the file content alone determines the etag, so a fresh process
+ *    sees the exact same etags every other process does.  Same key, same
+ *    bytes → same etag, regardless of who wrote them or when.
+ *  - **Per-key advisory lock.**  The lock file lives next to the target
+ *    file as `<key>.lock`.  Acquisition uses
+ *    `fs.writeFile(lockPath, ..., { flag: 'wx' })`, which is
+ *    atomic-create-only on every POSIX and NTFS filesystem the framework
+ *    targets.
+ *  - **Stale-lock recovery.**  Lock files older than {@link staleLockMs}
+ *    (default 30 s) are assumed to be left behind by a crashed writer
+ *    and forcibly removed; one final acquisition retry is then made.
+ *    This keeps the pathological "process died holding a lock" case from
+ *    blocking the directory forever, at the cost of being technically
+ *    incorrect if a real writer is taking longer than `staleLockMs` for a
+ *    single `put` — which shouldn't happen for the small payloads this
+ *    backend targets.
+ *  - **Atomic body writes.**  `put` writes to a per-process tmp file
+ *    (`<key>.tmp.<pid>.<ts>.<rand>`), then renames over the target.  On
+ *    POSIX `rename(2)` is atomic on the same filesystem; on Windows
+ *    `MoveFileEx(MOVEFILE_REPLACE_EXISTING)` provides equivalent
+ *    behaviour.  Concurrent readers always see either the old body or
+ *    the new body, never a truncated buffer.
+ */
+export interface FilesystemObjectStorageOptions {
+    /** Root directory.  Will be created (recursively) if it doesn't exist. */
+    readonly dir: string;
+    /**
+     * How long to wait when contending for a per-key write lock before
+     * giving up with `ObjectStorageBackendError`.  Default 5_000 ms — long
+     * enough that legitimate contenders complete first, short enough that
+     * a stuck holder gets surfaced quickly.
+     */
+    readonly lockTimeoutMs?: number;
+    /**
+     * Lock files older than this are assumed stale (left behind by a
+     * crashed writer) and forcibly removed.  Default 30_000 ms — well
+     * above the expected duration of any single `put`, so legitimate
+     * writers never get their lock yanked.
+     */
+    readonly staleLockMs?: number;
+}
+export declare class FilesystemObjectStorageBackend implements ObjectStorageBackend {
+    private readonly options;
+    private readonly lockTimeoutMs;
+    private readonly staleLockMs;
+    constructor(options: FilesystemObjectStorageOptions);
+    put(key: string, body: Uint8Array, opts?: PutOptions): Promise<{
+        etag: string;
+    }>;
+    get(key: string): Promise<Option<ObjectFetched>>;
+    delete(key: string): Promise<void>;
+    list(opts: {
+        prefix: string;
+        limit?: number;
+    }): Promise<ObjectInfo[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=FilesystemObjectStorageBackend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FilesystemObjectStorageBackend.d.ts","sourceRoot":"","sources":["../../../src/persistence/object-storage/FilesystemObjectStorageBackend.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,KAAK,UAAU,EAChB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,MAAM,WAAW,8BAA8B;IAC7C,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAyDD,qBAAa,8BAA+B,YAAW,oBAAoB;IAI7D,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAER,OAAO,EAAE,8BAA8B;IAK9D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAyEpF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IA+BhD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBlC,IAAI,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAoCrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}