@freqhole/reliquary 0.0.0

package/dist/automerge/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * minimal interface for a midden BiStream: a QUIC bidirectional stream
+ * exposing automerge-repo's length-delimited message framing, plus raw
+ * (unframed) reads/writes for protocols that terminate a stream without
+ * a length prefix instead.
+ */
+export interface BiStreamLike {
+    peer_node_id(): string;
+    alpn(): string;
+    write_message(data: Uint8Array): Promise<void>;
+    /** resolves to null when the stream is closed. */
+    read_message(): Promise<Uint8Array | null>;
+    close(): void;
+    /** raw framing (no length prefix) - used by protocols layered on top of
+     *  the sync ALPN via `registerAlpnHandler`. optional because not every
+     *  BiStream implementation supports it. */
+    read_to_end?(max_size: number): Promise<Uint8Array>;
+    write_raw_and_finish?(data: Uint8Array): Promise<void>;
+}
+/**
+ * midden node interface exposing the raw bidirectional-stream apis this
+ * adapter needs: dialing a peer (`open_bi`) and accepting inbound streams
+ * (`accept`).
+ */
+export interface MiddenStreamNode {
+    node_id(): string;
+    open_bi(peer_addr: string, alpn: string): Promise<BiStreamLike>;
+    accept(): Promise<BiStreamLike | null>;
+}
+/** the iroh endpoint's lifecycle state, for ui display. */
+export type EndpointState = "off" | "starting" | "online" | "error";
+/** summary of the adapter's connection state, for ui display. */
+export interface ConnectionSummary {
+    /** number of peers we're actively connected to (stream is open). */
+    connected: number;
+    /** number of peers we're trying to reconnect to (in backoff). */
+    reconnecting: number;
+    /** number of peers where reconnection gave up (max attempts exceeded). */
+    failed: number;
+}
+export interface IrohNetworkAdapterOptions {
+    /**
+     * factory that returns (or lazily creates) the midden stream node.
+     * called at most once; the resolved node is cached.
+     */
+    getNode: () => Promise<MiddenStreamNode>;
+    /**
+     * returns the current identity (any truthy value = identity exists).
+     * called once at connect() time to decide whether to start transport
+     * immediately or defer until onIdentityChange fires.
+     */
+    getIdentity: () => Promise<unknown | null>;
+    /**
+     * optional subscription for identity changes. when provided and no
+     * identity exists at connect() time, the adapter subscribes and starts
+     * transport when the first truthy identity arrives. must return an
+     * unsubscribe function.
+     */
+    onIdentityChange?: (cb: (identity: unknown | null) => void) => () => void;
+    /**
+     * ALPN string to use for automerge sync streams. defaults to
+     * SYNC_ALPN ("iroh/automerge-repo/1").
+     */
+    syncAlpn?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/automerge/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/automerge/types.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,IAAI,MAAM,CAAC;IACvB,IAAI,IAAI,MAAM,CAAC;IACf,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,kDAAkD;IAClD,YAAY,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC3C,KAAK,IAAI,IAAI,CAAC;IACd;;+CAE2C;IAC3C,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACpD,oBAAoB,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,IAAI,MAAM,CAAC;IAClB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAChE,MAAM,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACxC;AAED,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEzC;;;;OAIG;IACH,WAAW,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAE1E;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/automerge/types.js

@@ -0,0 +1,10 @@
+// shared shapes for ./automerge: the structural transport surface this
+// subpath needs from a midden-shaped node speaking iroh bidirectional
+// streams, plus the adapter's own construction options and ui-facing
+// state summaries.
+//
+// like ./transfer, this subpath never imports midden at runtime - only
+// structural types matching its snake_case surface, so any node-shaped
+// object (a real wasm node, a worker-backed facade, a test double) works
+// the same way.
+export {};

package/dist/blobs/bytes-backend.d.ts

@@ -0,0 +1,41 @@
+import type { BytesBackendName } from "./types.js";
+export interface BytesBackend {
+    readonly name: BytesBackendName;
+    isAvailable(): Promise<boolean>;
+    /** write returns false (never throws) when the backend could not accept
+     *  the write, so the caller can fall through to the next backend in the
+     *  chain. */
+    write(id: string, data: ArrayBuffer, mime: string): Promise<boolean>;
+    read(id: string): Promise<ArrayBuffer | null>;
+    has(id: string): Promise<boolean>;
+    remove(id: string): Promise<void>;
+    /** remove every stored blob's bytes - used by `clearAll()`. */
+    clear(): Promise<void>;
+}
+/** true when the origin private file system API is available. */
+export declare function isOPFSSupported(): boolean;
+export declare function createOpfsBackend(): BytesBackend;
+export declare function createCacheBackend(): BytesBackend;
+/** the default resolver chain: OPFS first, Cache API fallback. */
+export declare function defaultBytesChain(): BytesBackend[];
+/**
+ * write bytes through the chain, trying each backend in order until one
+ * accepts the write. returns the name of the backend that succeeded, or
+ * null if every backend in the chain refused/failed - callers must treat
+ * that as a hard failure (a record with bytes nowhere is worse than no
+ * record at all).
+ */
+export declare function writeThroughChain(chain: BytesBackend[], id: string, data: ArrayBuffer, mime: string): Promise<BytesBackendName | null>;
+/**
+ * read bytes given a known backend (from `storage_backend` on the
+ * record), or by probing the chain in order when the backend is unknown
+ * (legacy records predating that field).
+ */
+export declare function readThroughChain(chain: BytesBackend[], id: string, knownBackend?: BytesBackendName): Promise<ArrayBuffer | null>;
+/** true if any backend in the chain actually holds bytes for `id`. */
+export declare function hasBytesInChain(chain: BytesBackend[], id: string, knownBackend?: BytesBackendName): Promise<boolean>;
+/** remove bytes for `id` from every backend in the chain (a record may
+ *  have been rewritten across backends over its lifetime; removing from
+ *  all of them avoids leaking orphaned bytes). */
+export declare function removeFromChain(chain: BytesBackend[], id: string): Promise<void>;
+//# sourceMappingURL=bytes-backend.d.ts.map

package/dist/blobs/bytes-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes-backend.d.ts","sourceRoot":"","sources":["../../src/blobs/bytes-backend.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC;;iBAEa;IACb,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC9C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,+DAA+D;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,iEAAiE;AACjE,wBAAgB,eAAe,IAAI,OAAO,CAMzC;AAYD,wBAAgB,iBAAiB,IAAI,YAAY,CAmEhD;AAgBD,wBAAgB,kBAAkB,IAAI,YAAY,CA8DjD;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,IAAI,YAAY,EAAE,CAElD;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,EAAE,EACrB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAMlC;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,YAAY,EAAE,EACrB,EAAE,EAAE,MAAM,EACV,YAAY,CAAC,EAAE,gBAAgB,GAC9B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAa7B;AAED,sEAAsE;AACtE,wBAAsB,eAAe,CACnC,KAAK,EAAE,YAAY,EAAE,EACrB,EAAE,EAAE,MAAM,EACV,YAAY,CAAC,EAAE,gBAAgB,GAC9B,OAAO,CAAC,OAAO,CAAC,CASlB;AAED;;kDAEkD;AAClD,wBAAsB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF"}

package/dist/blobs/bytes-backend.js

@@ -0,0 +1,252 @@
+// the bytes side of the resolver chain: where raw blob bytes actually live.
+//
+// two backends, tried in order: OPFS is primary (bytes are content-addressed
+// by blake3 hex filename), the Cache API is a fallback for origins where
+// OPFS isn't available (webkitgtk historically rejects OPFS writes from the
+// main thread) or where a write to OPFS failed for some other reason. a
+// record remembers which backend it landed in (`storage_backend`) so a
+// later read goes straight there instead of probing every backend on every
+// read; records written before that field existed are assumed to be OPFS
+// (the only backend that existed at the time).
+//
+// OPFS writes are content-addressed and shared across every consumer of
+// this package at the origin (the same blake3 hash is the same bytes no
+// matter which app wrote it), so the OPFS directory name and the cache
+// name are fixed, not parameterized per store instance - only the
+// IndexedDB metadata database name varies per app (see `store.ts`).
+//
+// writes go through the blob worker (`../worker`) for OPFS - it uses a
+// `FileSystemSyncAccessHandle` when available, which is dramatically
+// faster than the async writable-stream API and is only usable off the
+// main thread. reads/existence-checks/removals talk to OPFS directly on
+// the calling thread instead - plain `getFile()` reads don't need a sync
+// access handle, and keeping them off the worker avoids a round trip.
+import { BLOB_OPFS_DIR, writeBlobToOpfs as writeBlobToOpfsViaWorker } from "../worker/index.js";
+import { log } from "../utils/log.js";
+const TAG = "blobs.bytes-backend";
+/** true when the origin private file system API is available. */
+export function isOPFSSupported() {
+    return (typeof navigator !== "undefined" &&
+        "storage" in navigator &&
+        typeof navigator.storage.getDirectory === "function");
+}
+async function getOpfsDir(create) {
+    if (!isOPFSSupported())
+        return null;
+    try {
+        const root = await navigator.storage.getDirectory();
+        return await root.getDirectoryHandle(BLOB_OPFS_DIR, { create });
+    }
+    catch {
+        return null;
+    }
+}
+export function createOpfsBackend() {
+    return {
+        name: "opfs",
+        async isAvailable() {
+            return isOPFSSupported();
+        },
+        async write(id, data) {
+            try {
+                await writeBlobToOpfsViaWorker(id, data);
+                return true;
+            }
+            catch (err) {
+                // the real underlying failure (a browser-level exception from the
+                // worker's OPFS write - e.g. a missing cross-origin-isolation
+                // requirement for FileSystemSyncAccessHandle, or a stale lock on
+                // this file from an interrupted previous write) must not be
+                // silently discarded here - a caller several layers up (storeBlob)
+                // only ever sees a generic "no bytes backend accepted it" once
+                // every backend in the chain has failed, so this is the last place
+                // the real cause is still available to log.
+                log.warn(TAG, `opfs write failed for ${id.slice(0, 16)}...:`, err);
+                return false;
+            }
+        },
+        async read(id) {
+            try {
+                const dir = await getOpfsDir(false);
+                if (!dir)
+                    return null;
+                const fileHandle = await dir.getFileHandle(id);
+                const file = await fileHandle.getFile();
+                return await file.arrayBuffer();
+            }
+            catch {
+                return null;
+            }
+        },
+        async has(id) {
+            try {
+                const dir = await getOpfsDir(false);
+                if (!dir)
+                    return false;
+                await dir.getFileHandle(id, { create: false });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async remove(id) {
+            try {
+                const dir = await getOpfsDir(false);
+                if (dir)
+                    await dir.removeEntry(id);
+            }
+            catch {
+                // missing entry is fine - remove is best-effort
+            }
+        },
+        async clear() {
+            try {
+                const root = await navigator.storage.getDirectory();
+                await root.removeEntry(BLOB_OPFS_DIR, { recursive: true });
+            }
+            catch {
+                // directory may not exist - that's fine
+            }
+        },
+    };
+}
+/** cache name for the Cache API fallback backend. a synthetic https origin
+ *  is used for cache keys (`https://blob.local/<id>`) because webkitgtk
+ *  rejects non-http(s) URLs in the Cache API. */
+const CACHE_NAME = "reliquary-blobs";
+const CACHE_URL_ORIGIN = "https://blob.local";
+function cacheUrlFor(id) {
+    return `${CACHE_URL_ORIGIN}/${id}`;
+}
+function isCacheApiSupported() {
+    return typeof caches !== "undefined";
+}
+export function createCacheBackend() {
+    return {
+        name: "cache",
+        async isAvailable() {
+            return isCacheApiSupported();
+        },
+        async write(id, data, mime) {
+            if (!isCacheApiSupported())
+                return false;
+            try {
+                const cache = await caches.open(CACHE_NAME);
+                const response = new Response(data, { headers: { "Content-Type": mime } });
+                await cache.put(cacheUrlFor(id), response);
+                return true;
+            }
+            catch (err) {
+                log.warn(TAG, `cache-api write failed for ${id.slice(0, 16)}...:`, err);
+                return false;
+            }
+        },
+        async read(id) {
+            if (!isCacheApiSupported())
+                return null;
+            try {
+                const cache = await caches.open(CACHE_NAME);
+                const response = await cache.match(cacheUrlFor(id));
+                if (!response)
+                    return null;
+                return await response.arrayBuffer();
+            }
+            catch {
+                return null;
+            }
+        },
+        async has(id) {
+            if (!isCacheApiSupported())
+                return false;
+            try {
+                const cache = await caches.open(CACHE_NAME);
+                return (await cache.match(cacheUrlFor(id))) !== undefined;
+            }
+            catch {
+                return false;
+            }
+        },
+        async remove(id) {
+            if (!isCacheApiSupported())
+                return;
+            try {
+                const cache = await caches.open(CACHE_NAME);
+                await cache.delete(cacheUrlFor(id));
+            }
+            catch {
+                // missing entry is fine - remove is best-effort
+            }
+        },
+        async clear() {
+            if (!isCacheApiSupported())
+                return;
+            try {
+                await caches.delete(CACHE_NAME);
+            }
+            catch {
+                // cache may not exist - that's fine
+            }
+        },
+    };
+}
+/** the default resolver chain: OPFS first, Cache API fallback. */
+export function defaultBytesChain() {
+    return [createOpfsBackend(), createCacheBackend()];
+}
+/**
+ * write bytes through the chain, trying each backend in order until one
+ * accepts the write. returns the name of the backend that succeeded, or
+ * null if every backend in the chain refused/failed - callers must treat
+ * that as a hard failure (a record with bytes nowhere is worse than no
+ * record at all).
+ */
+export async function writeThroughChain(chain, id, data, mime) {
+    for (const backend of chain) {
+        if (!(await backend.isAvailable()))
+            continue;
+        if (await backend.write(id, data, mime))
+            return backend.name;
+    }
+    return null;
+}
+/**
+ * read bytes given a known backend (from `storage_backend` on the
+ * record), or by probing the chain in order when the backend is unknown
+ * (legacy records predating that field).
+ */
+export async function readThroughChain(chain, id, knownBackend) {
+    if (knownBackend) {
+        const backend = chain.find((b) => b.name === knownBackend);
+        if (backend) {
+            const data = await backend.read(id);
+            if (data)
+                return data;
+        }
+    }
+    for (const backend of chain) {
+        const data = await backend.read(id);
+        if (data)
+            return data;
+    }
+    return null;
+}
+/** true if any backend in the chain actually holds bytes for `id`. */
+export async function hasBytesInChain(chain, id, knownBackend) {
+    if (knownBackend) {
+        const backend = chain.find((b) => b.name === knownBackend);
+        if (backend && (await backend.has(id)))
+            return true;
+    }
+    for (const backend of chain) {
+        if (await backend.has(id))
+            return true;
+    }
+    return false;
+}
+/** remove bytes for `id` from every backend in the chain (a record may
+ *  have been rewritten across backends over its lifetime; removing from
+ *  all of them avoids leaking orphaned bytes). */
+export async function removeFromChain(chain, id) {
+    await Promise.all(chain.map((backend) => backend.remove(id)));
+}

package/dist/blobs/bytes-backend.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bytes-backend.test.d.ts.map

package/dist/blobs/bytes-backend.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes-backend.test.d.ts","sourceRoot":"","sources":["../../src/blobs/bytes-backend.test.ts"],"names":[],"mappings":""}

package/dist/blobs/bytes-backend.test.js

@@ -0,0 +1,241 @@
+// @vitest-environment happy-dom
+//
+// exercises the bytes side of the resolver chain: OPFS backend (fake
+// directory/file handles - sync access handles are worker/chromium-only
+// and not worth faking here, same call as blob-worker-logic.test.ts),
+// Cache API backend (fake CacheStorage), and the chain helpers that tie
+// multiple backends together.
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { log } from "../utils/log.js";
+// ---- fake OPFS (async writable-stream path only, matches
+// blob-worker-logic.test.ts's fake) ----
+class FakeWritable {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    async write(data) {
+        this.file.bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer);
+    }
+    async close() { }
+}
+class FakeFileHandle {
+    bytes = new Uint8Array(0);
+    async getFile() {
+        const bytes = this.bytes;
+        return { arrayBuffer: async () => bytes.buffer };
+    }
+    async createWritable() {
+        return new FakeWritable(this);
+    }
+}
+class FakeDirHandle {
+    files = new Map();
+    async getFileHandle(name, opts) {
+        let handle = this.files.get(name);
+        if (!handle) {
+            if (!opts?.create)
+                throw new Error(`not found: ${name}`);
+            handle = new FakeFileHandle();
+            this.files.set(name, handle);
+        }
+        return handle;
+    }
+    async getDirectoryHandle(_name, opts) {
+        void opts;
+        return this;
+    }
+    async removeEntry(name) {
+        if (!this.files.delete(name))
+            throw new Error(`not found: ${name}`);
+    }
+}
+function installFakeOpfs() {
+    const root = new FakeDirHandle();
+    vi.stubGlobal("navigator", {
+        storage: {
+            getDirectory: async () => root,
+        },
+    });
+    return root;
+}
+// the worker write path is mocked to write through the same fake
+// directory the direct-read path uses, so both sides of a
+// write-then-read round trip agree on where bytes live - exactly like
+// the real worker (sync-access-handle writes) and the real direct OPFS
+// reads share one physical directory.
+vi.mock("../worker/index.js", () => ({
+    BLOB_OPFS_DIR: "reliquary-blobs",
+    writeBlobToOpfs: vi.fn(async (id, data) => {
+        const root = await navigator.storage.getDirectory();
+        const dir = await root.getDirectoryHandle("reliquary-blobs", { create: true });
+        const file = await dir.getFileHandle(id, { create: true });
+        const writable = await file.createWritable();
+        await writable.write(data);
+        await writable.close();
+    }),
+}));
+// ---- fake Cache API ----
+class FakeCache {
+    entries = new Map();
+    async put(url, response) {
+        this.entries.set(url, response);
+    }
+    async match(url) {
+        const found = this.entries.get(url);
+        return found ? found.clone() : undefined;
+    }
+    async delete(url) {
+        return this.entries.delete(url);
+    }
+}
+class FakeCacheStorage {
+    caches = new Map();
+    async open(name) {
+        let cache = this.caches.get(name);
+        if (!cache) {
+            cache = new FakeCache();
+            this.caches.set(name, cache);
+        }
+        return cache;
+    }
+    async delete(name) {
+        return this.caches.delete(name);
+    }
+}
+function installFakeCaches() {
+    const storage = new FakeCacheStorage();
+    vi.stubGlobal("caches", storage);
+    return storage;
+}
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+const { createOpfsBackend, createCacheBackend, isOPFSSupported, defaultBytesChain, writeThroughChain, readThroughChain, hasBytesInChain, removeFromChain, } = await import("./bytes-backend.js");
+describe("isOPFSSupported", () => {
+    it("is false with no navigator.storage.getDirectory", () => {
+        expect(isOPFSSupported()).toBe(false);
+    });
+    it("is true once a fake OPFS is installed", () => {
+        installFakeOpfs();
+        expect(isOPFSSupported()).toBe(true);
+    });
+});
+describe("createOpfsBackend", () => {
+    it("round-trips bytes through write/read/has/remove", async () => {
+        installFakeOpfs();
+        const backend = createOpfsBackend();
+        const data = new TextEncoder().encode("hello opfs").buffer;
+        expect(await backend.write("id-1", data, "text/plain")).toBe(true);
+        expect(await backend.has("id-1")).toBe(true);
+        const readBack = await backend.read("id-1");
+        expect(new TextDecoder().decode(readBack)).toBe("hello opfs");
+        await backend.remove("id-1");
+        expect(await backend.has("id-1")).toBe(false);
+        expect(await backend.read("id-1")).toBeNull();
+    });
+    it("read/has return null/false, write returns false, with no OPFS available", async () => {
+        const backend = createOpfsBackend();
+        expect(await backend.isAvailable()).toBe(false);
+        expect(await backend.write("id-1", new ArrayBuffer(4), "text/plain")).toBe(false);
+        expect(await backend.read("id-1")).toBeNull();
+        expect(await backend.has("id-1")).toBe(false);
+    });
+    it("write returns false (not throw) when OPFS is available but the underlying write rejects - e.g. a real browser where createSyncAccessHandle throws because the page isn't cross-origin isolated, or a stale lock from a crashed session still holds the file - and logs the real underlying error instead of silently discarding it", async () => {
+        installFakeOpfs();
+        const backend = createOpfsBackend();
+        const worker = await import("../worker/index.js");
+        const realError = new Error("NotAllowedError: Access Handles cannot be created");
+        vi.mocked(worker.writeBlobToOpfs).mockRejectedValueOnce(realError);
+        const warnSpy = vi.spyOn(log, "warn");
+        // isAvailable() only checks that the OPFS *api* exists (navigator.
+        // storage.getDirectory is a function) - it says nothing about whether
+        // an actual write will succeed, so a real per-write failure surfaces
+        // here, at write() itself, not at isAvailable().
+        expect(await backend.isAvailable()).toBe(true);
+        expect(await backend.write("id-1", new ArrayBuffer(4), "text/plain")).toBe(false);
+        expect(warnSpy).toHaveBeenCalledWith(expect.anything(), expect.any(String), realError);
+    });
+    it("clear() removes the whole opfs directory", async () => {
+        const root = installFakeOpfs();
+        const backend = createOpfsBackend();
+        await backend.write("id-1", new ArrayBuffer(4), "text/plain");
+        await backend.clear();
+        // the fake directory's removeEntry on the root only throws for a
+        // missing entry - a second clear() should stay a no-op, not throw.
+        await expect(backend.clear()).resolves.toBeUndefined();
+        void root;
+    });
+});
+describe("createCacheBackend", () => {
+    it("round-trips bytes through write/read/has/remove", async () => {
+        installFakeCaches();
+        const backend = createCacheBackend();
+        const data = new TextEncoder().encode("hello cache").buffer;
+        expect(await backend.write("id-2", data, "text/plain")).toBe(true);
+        expect(await backend.has("id-2")).toBe(true);
+        const readBack = await backend.read("id-2");
+        expect(new TextDecoder().decode(readBack)).toBe("hello cache");
+        await backend.remove("id-2");
+        expect(await backend.has("id-2")).toBe(false);
+    });
+    it("read/has/write degrade gracefully with no Cache API available", async () => {
+        const backend = createCacheBackend();
+        expect(await backend.isAvailable()).toBe(false);
+        expect(await backend.write("id-2", new ArrayBuffer(4), "text/plain")).toBe(false);
+        expect(await backend.read("id-2")).toBeNull();
+        expect(await backend.has("id-2")).toBe(false);
+    });
+});
+describe("chain helpers", () => {
+    it("writeThroughChain falls through to the next backend when the first is unavailable", async () => {
+        installFakeCaches(); // opfs unavailable, cache available
+        const chain = defaultBytesChain();
+        const backendName = await writeThroughChain(chain, "id-3", new ArrayBuffer(4), "text/plain");
+        expect(backendName).toBe("cache");
+    });
+    it("writeThroughChain returns null when every backend is unavailable", async () => {
+        const chain = defaultBytesChain();
+        expect(await writeThroughChain(chain, "id-3", new ArrayBuffer(4), "text/plain")).toBeNull();
+    });
+    it("writeThroughChain returns null when OPFS is available but rejects the write and there is no fallback backend in the chain - reproduces the real 'no bytes backend accepted it' failure a caller sees when the cache-api fallback is disabled (allowCacheFallback: false)", async () => {
+        installFakeOpfs();
+        const worker = await import("../worker/index.js");
+        vi.mocked(worker.writeBlobToOpfs).mockRejectedValueOnce(new Error("NotAllowedError"));
+        const opfsOnlyChain = [createOpfsBackend()];
+        expect(await writeThroughChain(opfsOnlyChain, "id-3", new ArrayBuffer(4), "text/plain")).toBeNull();
+    });
+    it("readThroughChain goes straight to the known backend", async () => {
+        installFakeOpfs();
+        installFakeCaches();
+        const chain = defaultBytesChain();
+        const data = new TextEncoder().encode("known backend").buffer;
+        await writeThroughChain(chain, "id-4", data, "text/plain");
+        const readBack = await readThroughChain(chain, "id-4", "opfs");
+        expect(new TextDecoder().decode(readBack)).toBe("known backend");
+    });
+    it("readThroughChain probes every backend when the backend is unknown", async () => {
+        installFakeCaches(); // only cache available - opfs was never installed
+        const chain = defaultBytesChain();
+        const data = new TextEncoder().encode("legacy record").buffer;
+        await writeThroughChain(chain, "id-5", data, "text/plain");
+        // no `knownBackend` passed - simulates a record predating the field
+        const readBack = await readThroughChain(chain, "id-5");
+        expect(new TextDecoder().decode(readBack)).toBe("legacy record");
+    });
+    it("hasBytesInChain checks every backend", async () => {
+        installFakeCaches();
+        const chain = defaultBytesChain();
+        expect(await hasBytesInChain(chain, "missing")).toBe(false);
+        await writeThroughChain(chain, "id-6", new ArrayBuffer(4), "text/plain");
+        expect(await hasBytesInChain(chain, "id-6")).toBe(true);
+    });
+    it("removeFromChain removes from every backend that has the id", async () => {
+        installFakeOpfs();
+        installFakeCaches();
+        const chain = defaultBytesChain();
+        await writeThroughChain(chain, "id-7", new ArrayBuffer(4), "text/plain");
+        await removeFromChain(chain, "id-7");
+        expect(await hasBytesInChain(chain, "id-7")).toBe(false);
+    });
+});

package/dist/blobs/db.d.ts

@@ -0,0 +1,8 @@
+import type { BlobRecord } from "./types.js";
+export declare function putRecord(dbName: string, record: BlobRecord): Promise<void>;
+export declare function getRecord(dbName: string, blobId: string): Promise<BlobRecord | null>;
+export declare function getRecordBySha256(dbName: string, sha256: string): Promise<BlobRecord | null>;
+export declare function getRecordByBlake3(dbName: string, blake3: string): Promise<BlobRecord | null>;
+export declare function deleteRecord(dbName: string, blobId: string): Promise<void>;
+export declare function clearRecords(dbName: string): Promise<void>;
+//# sourceMappingURL=db.d.ts.map

package/dist/blobs/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/blobs/db.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAkE7C,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAcjF;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAS1F;AAkBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAE5F;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAE5F;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAchF;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAchE"}