@freqhole/reliquary 0.0.0

package/dist/blobs/db.js

@@ -0,0 +1,141 @@
+// the metadata side of the resolver chain: an IndexedDB-backed record
+// store keyed by blob_id (the blake3 hex digest), with secondary indexes
+// so a record can also be found by its legacy sha256, by blake3 alone
+// (covering a record whose primary key is a legacy sha256), by blob_type,
+// or by parent_blob_id.
+//
+// follows a "open fresh, close when done" pattern for every operation
+// rather than holding one long-lived connection open - simple, and avoids
+// a version-change block from another tab ever having anything to wait on.
+const STORE_NAME = "blobs";
+const DB_VERSION = 1;
+function openVersioned(dbName, version) {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.open(dbName, version);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(STORE_NAME)) {
+                const store = db.createObjectStore(STORE_NAME, { keyPath: "blob_id" });
+                store.createIndex("sha256", "sha256", { unique: false });
+                store.createIndex("blake3", "blake3", { unique: false });
+                store.createIndex("blob_type", "blob_type", { unique: false });
+                store.createIndex("parent_blob_id", "parent_blob_id", { unique: false });
+            }
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+// a dbName passed to `createBlobStore` is often an app's pre-existing
+// database (that's the whole point of making it a constructor parameter -
+// see store.ts) - it may already sit at a version higher than
+// `DB_VERSION`, and `indexedDB.open(name, version)` fails with a
+// VersionError when asked for a version lower than the database's actual
+// one. resolved versions are cached per dbName so the common case (a
+// fresh database, or one already at `DB_VERSION`) only ever pays for one
+// open per operation, matching the "open fresh, close when done" pattern
+// used throughout this module.
+const resolvedVersions = new Map();
+async function openDb(dbName) {
+    const cachedVersion = resolvedVersions.get(dbName);
+    if (cachedVersion !== undefined) {
+        return openVersioned(dbName, cachedVersion);
+    }
+    try {
+        const db = await openVersioned(dbName, DB_VERSION);
+        resolvedVersions.set(dbName, DB_VERSION);
+        return db;
+    }
+    catch (err) {
+        if (!(err instanceof DOMException) || err.name !== "VersionError")
+            throw err;
+        // the database already exists at some higher version - open it
+        // version-less to discover what that is, then reopen at that exact
+        // version (creating the store if a pre-existing database somehow
+        // never had one).
+        const probe = await new Promise((resolve, reject) => {
+            const req = indexedDB.open(dbName);
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+        const currentVersion = probe.version;
+        const hasStore = probe.objectStoreNames.contains(STORE_NAME);
+        probe.close();
+        const targetVersion = hasStore ? currentVersion : currentVersion + 1;
+        resolvedVersions.set(dbName, targetVersion);
+        return openVersioned(dbName, targetVersion);
+    }
+}
+export async function putRecord(dbName, record) {
+    const db = await openDb(dbName);
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(STORE_NAME, "readwrite");
+        tx.objectStore(STORE_NAME).put(record);
+        tx.oncomplete = () => {
+            db.close();
+            resolve();
+        };
+        tx.onerror = () => {
+            db.close();
+            reject(tx.error);
+        };
+    });
+}
+export async function getRecord(dbName, blobId) {
+    const db = await openDb(dbName);
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(STORE_NAME, "readonly");
+        const req = tx.objectStore(STORE_NAME).get(blobId);
+        req.onsuccess = () => resolve(req.result ?? null);
+        req.onerror = () => reject(req.error);
+        tx.oncomplete = () => db.close();
+    });
+}
+async function getByIndex(dbName, indexName, value) {
+    if (!value)
+        return null;
+    const db = await openDb(dbName);
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(STORE_NAME, "readonly");
+        const req = tx.objectStore(STORE_NAME).index(indexName).get(value);
+        req.onsuccess = () => resolve(req.result ?? null);
+        req.onerror = () => reject(req.error);
+        tx.oncomplete = () => db.close();
+    });
+}
+export function getRecordBySha256(dbName, sha256) {
+    return getByIndex(dbName, "sha256", sha256);
+}
+export function getRecordByBlake3(dbName, blake3) {
+    return getByIndex(dbName, "blake3", blake3);
+}
+export async function deleteRecord(dbName, blobId) {
+    const db = await openDb(dbName);
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(STORE_NAME, "readwrite");
+        tx.objectStore(STORE_NAME).delete(blobId);
+        tx.oncomplete = () => {
+            db.close();
+            resolve();
+        };
+        tx.onerror = () => {
+            db.close();
+            reject(tx.error);
+        };
+    });
+}
+export async function clearRecords(dbName) {
+    const db = await openDb(dbName);
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(STORE_NAME, "readwrite");
+        tx.objectStore(STORE_NAME).clear();
+        tx.oncomplete = () => {
+            db.close();
+            resolve();
+        };
+        tx.onerror = () => {
+            db.close();
+            reject(tx.error);
+        };
+    });
+}

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

@@ -0,0 +1,2 @@
+import "fake-indexeddb/auto";
+//# sourceMappingURL=db.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"db.test.d.ts","sourceRoot":"","sources":["../../src/blobs/db.test.ts"],"names":[],"mappings":"AAGA,OAAO,qBAAqB,CAAC"}

package/dist/blobs/db.test.js

@@ -0,0 +1,120 @@
+// exercises the metadata layer directly: CRUD + secondary indexes
+// (sha256, blake3) that make the record resolver chain possible.
+import "fake-indexeddb/auto";
+import { IDBFactory } from "fake-indexeddb";
+import { beforeEach, describe, expect, it } from "vitest";
+import { clearRecords, deleteRecord, getRecord, getRecordByBlake3, getRecordBySha256, putRecord, } from "./db.js";
+const DB_NAME = "blobs-db-test";
+beforeEach(() => {
+    globalThis.indexedDB = new IDBFactory();
+});
+function makeRecord(overrides = {}) {
+    return {
+        blob_id: "blake3-aaa",
+        blake3: "blake3-aaa",
+        sha256: "sha256-aaa",
+        filename: "song.mp3",
+        mime: "audio/mpeg",
+        size: 1234,
+        blob_type: "original",
+        parent_blob_id: null,
+        created_at: 1_000,
+        storage_backend: "opfs",
+        ...overrides,
+    };
+}
+describe("putRecord / getRecord", () => {
+    it("round-trips a record by its primary key", async () => {
+        const record = makeRecord();
+        await putRecord(DB_NAME, record);
+        expect(await getRecord(DB_NAME, record.blob_id)).toEqual(record);
+    });
+    it("returns null for a record that was never stored", async () => {
+        expect(await getRecord(DB_NAME, "nope")).toBeNull();
+    });
+    it("overwrites a record stored under the same blob_id", async () => {
+        await putRecord(DB_NAME, makeRecord({ filename: "first.mp3" }));
+        await putRecord(DB_NAME, makeRecord({ filename: "second.mp3" }));
+        const record = await getRecord(DB_NAME, "blake3-aaa");
+        expect(record?.filename).toBe("second.mp3");
+    });
+});
+describe("getRecordBySha256 / getRecordByBlake3", () => {
+    it("finds a record by its sha256 index", async () => {
+        const record = makeRecord();
+        await putRecord(DB_NAME, record);
+        expect(await getRecordBySha256(DB_NAME, "sha256-aaa")).toEqual(record);
+    });
+    it("finds a record by its blake3 index", async () => {
+        const record = makeRecord();
+        await putRecord(DB_NAME, record);
+        expect(await getRecordByBlake3(DB_NAME, "blake3-aaa")).toEqual(record);
+    });
+    it("finds a legacy record whose primary key is a sha256, not its blake3", async () => {
+        // simulates a record created before blake3 became canonical: blob_id
+        // is the legacy sha256, but blake3 is known and indexed separately.
+        const legacy = makeRecord({
+            blob_id: "sha256-legacy",
+            blake3: "blake3-discovered-later",
+            sha256: "sha256-legacy",
+        });
+        await putRecord(DB_NAME, legacy);
+        expect(await getRecordByBlake3(DB_NAME, "blake3-discovered-later")).toEqual(legacy);
+        expect(await getRecord(DB_NAME, "sha256-legacy")).toEqual(legacy);
+    });
+    it("returns null for an empty hash rather than matching everything", async () => {
+        await putRecord(DB_NAME, makeRecord());
+        expect(await getRecordBySha256(DB_NAME, "")).toBeNull();
+        expect(await getRecordByBlake3(DB_NAME, "")).toBeNull();
+    });
+});
+describe("deleteRecord", () => {
+    it("removes a record so subsequent lookups miss", async () => {
+        await putRecord(DB_NAME, makeRecord());
+        await deleteRecord(DB_NAME, "blake3-aaa");
+        expect(await getRecord(DB_NAME, "blake3-aaa")).toBeNull();
+    });
+});
+describe("clearRecords", () => {
+    it("empties every record in the store", async () => {
+        await putRecord(DB_NAME, makeRecord({ blob_id: "a", blake3: "a" }));
+        await putRecord(DB_NAME, makeRecord({ blob_id: "b", blake3: "b" }));
+        await clearRecords(DB_NAME);
+        expect(await getRecord(DB_NAME, "a")).toBeNull();
+        expect(await getRecord(DB_NAME, "b")).toBeNull();
+    });
+});
+describe("db name isolation", () => {
+    it("keeps records in different-named databases from colliding", async () => {
+        await putRecord("db-one", makeRecord());
+        expect(await getRecord("db-two", "blake3-aaa")).toBeNull();
+        expect(await getRecord("db-one", "blake3-aaa")).not.toBeNull();
+    });
+});
+describe("pre-existing database at a higher version", () => {
+    it("still reads and writes when dbName already exists at a version above DB_VERSION", async () => {
+        // simulates an app's pre-existing database (this module's whole
+        // reason for taking dbName as a parameter) that was already upgraded
+        // to a later version by that app's own code before this store ever
+        // touched it - indexedDB.open(name, 1) would otherwise fail with a
+        // VersionError since 1 is lower than the database's actual version.
+        const dbName = "pre-existing-higher-version-db";
+        await new Promise((resolve, reject) => {
+            const req = indexedDB.open(dbName, 3);
+            req.onupgradeneeded = () => {
+                const store = req.result.createObjectStore("blobs", { keyPath: "blob_id" });
+                store.createIndex("sha256", "sha256", { unique: false });
+                store.createIndex("blake3", "blake3", { unique: false });
+            };
+            req.onsuccess = () => {
+                req.result.close();
+                resolve();
+            };
+            req.onerror = () => reject(req.error);
+        });
+        const record = makeRecord();
+        await putRecord(dbName, record);
+        expect(await getRecord(dbName, record.blob_id)).toEqual(record);
+        expect(await getRecordByBlake3(dbName, record.blake3)).toEqual(record);
+    });
+});

package/dist/blobs/index.d.ts

@@ -0,0 +1,5 @@
+export { createBlobStore, isOPFSSupported, DEFAULT_DB_NAME, writeThroughChain, readThroughChain, hasBytesInChain, removeFromChain, } from "./store.js";
+export type { BlobStore, BlobStoreOptions, StoreBlobFromFileOptions, BytesBackend, } from "./store.js";
+export type { BlobLocalityInfo, BlobLocalityMetadata, BlobRecord, BlobType, BytesBackendName, NewBlobMeta, } from "./types.js";
+export { createOpfsBackend, createCacheBackend, defaultBytesChain } from "./bytes-backend.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/blobs/index.js

@@ -0,0 +1,2 @@
+export { createBlobStore, isOPFSSupported, DEFAULT_DB_NAME, writeThroughChain, readThroughChain, hasBytesInChain, removeFromChain, } from "./store.js";
+export { createOpfsBackend, createCacheBackend, defaultBytesChain } from "./bytes-backend.js";

package/dist/blobs/store.d.ts

@@ -0,0 +1,47 @@
+import type { BlobLocalityInfo, BlobRecord, NewBlobMeta } from "./types.js";
+export { isOPFSSupported } from "./bytes-backend.js";
+export type { BlobLocalityInfo, BlobLocalityMetadata, BlobRecord, BlobType, BytesBackendName, NewBlobMeta } from "./types.js";
+/** default IndexedDB database name for apps that don't need to preserve an
+ *  existing one. */
+export declare const DEFAULT_DB_NAME = "reliquary-blobs";
+export interface BlobStoreOptions {
+    /** IndexedDB database name for this store's metadata. defaults to
+     *  `DEFAULT_DB_NAME`; pass an app's existing database name to keep
+     *  reading/writing the same browser data it already has. */
+    dbName?: string;
+    /** when true, a write falls back to the Cache API if OPFS is
+     *  unavailable or refuses the write (e.g. the webkitgtk quirk where
+     *  OPFS writes from the main thread are rejected). defaults to false:
+     *  a write that OPFS refuses throws instead of silently landing in the
+     *  cache, since a record whose bytes silently ended up somewhere the
+     *  caller didn't expect is worse than a loud failure the caller can
+     *  retry or surface. */
+    allowCacheFallback?: boolean;
+}
+export interface StoreBlobFromFileOptions {
+    onProgress?: (fraction: number) => void;
+    signal?: AbortSignal;
+}
+export interface BlobStore {
+    storeBlob(data: ArrayBuffer, meta: NewBlobMeta): Promise<BlobRecord>;
+    storeBlobFromFile(file: File, meta?: Partial<NewBlobMeta>, options?: StoreBlobFromFileOptions): Promise<BlobRecord>;
+    getBlobRecord(blobId: string): Promise<BlobRecord | null>;
+    getBlobRecordByBlake3(blake3: string): Promise<BlobRecord | null>;
+    getBlobRecordBySha256(sha256: string): Promise<BlobRecord | null>;
+    resolveBlob(blobId: string, blake3?: string): Promise<BlobRecord | null>;
+    getBlobMetadata(blobId: string, blake3?: string): Promise<BlobRecord | null>;
+    getBlobData(blobId: string, blake3?: string): Promise<ArrayBuffer | null>;
+    getBlob(blobId: string, blake3?: string): Promise<Blob | null>;
+    getBlobObjectURL(blobId: string, blake3?: string): Promise<string | null>;
+    clearBlobUrlCache(): void;
+    hasBlobBytes(blobId: string): Promise<boolean>;
+    checkBlobLocality(blobId: string, blake3?: string): Promise<BlobLocalityInfo>;
+    deleteBlob(blobId: string): Promise<void>;
+    clearAll(): Promise<void>;
+}
+/** create a blob store instance. each instance owns its own object-url
+ *  cache; construct one per app (not per component/request). */
+export declare function createBlobStore(options?: BlobStoreOptions): BlobStore;
+export { writeThroughChain, readThroughChain, hasBytesInChain, removeFromChain } from "./bytes-backend.js";
+export type { BytesBackend } from "./bytes-backend.js";
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/blobs/store.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9H;oBACoB;AACpB,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAOjD,MAAM,WAAW,gBAAgB;IAC/B;;gEAE4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;4BAMwB;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACrE,iBAAiB,CACf,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAC3B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC1D,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAClE,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAClE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACzE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC7E,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC1E,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAC/D,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1E,iBAAiB,IAAI,IAAI,CAAC;IAC1B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9E,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;gEACgE;AAChE,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAiPzE;AAKD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3G,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/blobs/store.js

@@ -0,0 +1,263 @@
+// the blake3-canonical blob record store: ties the metadata side (db.ts,
+// IndexedDB) to the bytes side (bytes-backend.ts, OPFS + Cache API) behind
+// one API, and implements the resolver chain that lets old sha256-era
+// references keep working alongside new blake3-keyed records.
+//
+// "resolver chain" here means two related lookup chains:
+//   - record resolution (`resolveBlob`): primary key -> blake3 index ->
+//     sha256 index -> blake3 index again with a separately-known hash.
+//     this is what lets a caller pass either a blake3 or a legacy sha256
+//     and get the same record back.
+//   - bytes resolution (`bytes-backend.ts`'s `readThroughChain`): a
+//     record's `storage_backend` field says where its bytes were written;
+//     when that's unknown (a record predating the field) every backend is
+//     probed in order (OPFS, then Cache API).
+//
+// db name is a constructor parameter (`createBlobStore({ dbName })`) so
+// each consuming app can keep its own existing IndexedDB database name -
+// no browser-data migration is forced by adopting this package. bytes
+// storage (OPFS directory, Cache API cache) is content-addressed by
+// blake3 and shared at the origin regardless of which app wrote it, so it
+// is not parameterized per store instance - see `bytes-backend.ts`.
+import { hashBlake3, hashSha256, streamFileToOpfs } from "../worker/index.js";
+import { clearRecords, deleteRecord, getRecord, getRecordByBlake3, getRecordBySha256, putRecord, } from "./db.js";
+import { createOpfsBackend, defaultBytesChain, hasBytesInChain, readThroughChain, removeFromChain, writeThroughChain, } from "./bytes-backend.js";
+export { isOPFSSupported } from "./bytes-backend.js";
+/** default IndexedDB database name for apps that don't need to preserve an
+ *  existing one. */
+export const DEFAULT_DB_NAME = "reliquary-blobs";
+/** files at or above this size stream into OPFS chunk-by-chunk (incremental
+ *  blake3 + sync-access-handle writes via the blob worker) instead of being
+ *  buffered whole for the one-shot hash+write pipeline. */
+const STREAM_UPLOAD_THRESHOLD = 8 * 1024 * 1024;
+/** create a blob store instance. each instance owns its own object-url
+ *  cache; construct one per app (not per component/request). */
+export function createBlobStore(options = {}) {
+    const dbName = options.dbName ?? DEFAULT_DB_NAME;
+    const chain = options.allowCacheFallback ? defaultBytesChain() : [createOpfsBackend()];
+    const blobUrlCache = new Map();
+    let beforeUnloadRegistered = false;
+    function ensureBeforeUnloadListener() {
+        if (beforeUnloadRegistered || typeof window === "undefined")
+            return;
+        window.addEventListener("beforeunload", () => {
+            for (const url of blobUrlCache.values())
+                URL.revokeObjectURL(url);
+            blobUrlCache.clear();
+        });
+        beforeUnloadRegistered = true;
+    }
+    async function storeBlob(data, meta) {
+        // hash before writing anything - both hashers copy their input rather
+        // than transferring it, so `data` is still intact for the write below.
+        const [blake3, sha256] = await Promise.all([hashBlake3(new Uint8Array(data)), hashSha256(data)]);
+        const blobId = blake3;
+        // dedup - content-addressed, so a pre-existing record for this blake3
+        // means the bytes are already stored under it.
+        const existing = await getRecord(dbName, blobId);
+        if (existing)
+            return existing;
+        // opfs primary, cache-api fallback for opfs-less environments. only a
+        // total failure (neither backend accepted the write) throws - a record
+        // with bytes nowhere is worse than no record at all, but a successful
+        // cache-api write is not a failure.
+        const backend = await writeThroughChain(chain, blobId, data, meta.mime);
+        if (!backend) {
+            throw new Error(`blob write failed for ${blobId.slice(0, 16)}... - no bytes backend accepted it`);
+        }
+        const record = {
+            blob_id: blobId,
+            blake3,
+            sha256,
+            filename: meta.filename,
+            mime: meta.mime,
+            size: data.byteLength,
+            blob_type: meta.blob_type ?? "original",
+            parent_blob_id: meta.parent_blob_id ?? null,
+            metadata: meta.metadata,
+            created_at: Date.now(),
+            storage_backend: backend,
+        };
+        await putRecord(dbName, record);
+        return record;
+    }
+    async function storeBlobFromFile(file, meta = {}, options) {
+        const mime = meta.mime ?? file.type ?? "application/octet-stream";
+        const filename = meta.filename ?? file.name;
+        if (file.size >= STREAM_UPLOAD_THRESHOLD) {
+            try {
+                const { blake3, size } = await streamFileToOpfs(file, options);
+                const existing = await getRecord(dbName, blake3);
+                if (existing)
+                    return existing;
+                // sha256 is legacy-only - it's never computed for a streamed
+                // upload, since brand-new content has no old sha256-keyed
+                // reference that would need it.
+                const record = {
+                    blob_id: blake3,
+                    blake3,
+                    filename,
+                    mime,
+                    size,
+                    blob_type: meta.blob_type ?? "original",
+                    parent_blob_id: meta.parent_blob_id ?? null,
+                    metadata: meta.metadata,
+                    created_at: Date.now(),
+                    storage_backend: "opfs",
+                };
+                await putRecord(dbName, record);
+                return record;
+            }
+            catch (err) {
+                // a deliberate cancel must propagate, not silently fall back to
+                // buffering the whole file.
+                if (err instanceof DOMException && err.name === "AbortError")
+                    throw err;
+                // otherwise fall through to the buffered path below (e.g. no
+                // worker, no OPFS sync-access-handle support in this browser).
+            }
+        }
+        if (options?.signal?.aborted) {
+            throw new DOMException("upload cancelled", "AbortError");
+        }
+        const buffer = await file.arrayBuffer();
+        return storeBlob(buffer, { filename, mime, ...meta });
+    }
+    function getBlobRecord(blobId) {
+        return getRecord(dbName, blobId);
+    }
+    function getBlobRecordByBlake3(blake3) {
+        return getRecordByBlake3(dbName, blake3);
+    }
+    function getBlobRecordBySha256(sha256) {
+        return getRecordBySha256(dbName, sha256);
+    }
+    /**
+     * resolve a blobId to a record using multiple lookup strategies: primary
+     * key -> blake3 index (blobId itself) -> sha256 index -> blake3 index
+     * (separately-known hash). handles both id generations - blake3 is
+     * canonical now, sha256-keyed records are legacy but must keep
+     * resolving.
+     */
+    async function resolveBlob(blobId, blake3) {
+        if (!blobId)
+            return null;
+        const byKey = await getRecord(dbName, blobId);
+        if (byKey)
+            return byKey;
+        const byIdAsBlake3 = await getRecordByBlake3(dbName, blobId);
+        if (byIdAsBlake3)
+            return byIdAsBlake3;
+        const bySha = await getRecordBySha256(dbName, blobId);
+        if (bySha)
+            return bySha;
+        if (blake3) {
+            const byBlake3 = await getRecordByBlake3(dbName, blake3);
+            if (byBlake3)
+                return byBlake3;
+        }
+        return null;
+    }
+    async function getBlobData(blobId, blake3) {
+        const record = await resolveBlob(blobId, blake3);
+        if (!record)
+            return null;
+        return readThroughChain(chain, record.blob_id, record.storage_backend);
+    }
+    async function getBlob(blobId, blake3) {
+        const record = await resolveBlob(blobId, blake3);
+        if (!record)
+            return null;
+        const data = await readThroughChain(chain, record.blob_id, record.storage_backend);
+        if (!data)
+            return null;
+        return new Blob([data], { type: record.mime || "application/octet-stream" });
+    }
+    async function getBlobObjectURL(blobId, blake3) {
+        ensureBeforeUnloadListener();
+        const cached = blobUrlCache.get(blobId);
+        if (cached)
+            return cached;
+        const blob = await getBlob(blobId, blake3);
+        if (!blob)
+            return null;
+        const url = URL.createObjectURL(blob);
+        blobUrlCache.set(blobId, url);
+        return url;
+    }
+    function clearBlobUrlCache() {
+        for (const url of blobUrlCache.values())
+            URL.revokeObjectURL(url);
+        blobUrlCache.clear();
+    }
+    async function hasBlobBytes(blobId) {
+        const record = await resolveBlob(blobId);
+        if (!record)
+            return false;
+        return hasBytesInChain(chain, record.blob_id, record.storage_backend);
+    }
+    /**
+     * check whether a blob is available locally. a record without bytes
+     * (e.g. a write whose bytes backend silently failed, or a record synced
+     * in from a peer before its bytes arrived) counts as "remote" rather
+     * than a stuck "local" - that stranded state previously left playback
+     * finding nothing with no re-snatch ever offered.
+     */
+    async function checkBlobLocality(blobId, blake3) {
+        if (!blobId)
+            return { locality: "unknown" };
+        const record = await resolveBlob(blobId, blake3);
+        if (!record)
+            return { locality: "remote" };
+        const bytesPresent = await hasBytesInChain(chain, record.blob_id, record.storage_backend);
+        if (!bytesPresent)
+            return { locality: "remote" };
+        return {
+            locality: "local",
+            metadata: {
+                id: record.blob_id,
+                mime: record.mime || undefined,
+                filename: record.filename || undefined,
+                size: record.size || undefined,
+                blake3: record.blake3 || undefined,
+            },
+        };
+    }
+    async function deleteBlob(blobId) {
+        const record = await getRecord(dbName, blobId);
+        if (record)
+            await removeFromChain(chain, record.blob_id);
+        const cachedUrl = blobUrlCache.get(blobId);
+        if (cachedUrl) {
+            URL.revokeObjectURL(cachedUrl);
+            blobUrlCache.delete(blobId);
+        }
+        await deleteRecord(dbName, blobId);
+    }
+    async function clearAll() {
+        clearBlobUrlCache();
+        await clearRecords(dbName);
+        await Promise.all(chain.map((backend) => backend.clear()));
+    }
+    return {
+        storeBlob,
+        storeBlobFromFile,
+        getBlobRecord,
+        getBlobRecordByBlake3,
+        getBlobRecordBySha256,
+        resolveBlob,
+        getBlobMetadata: resolveBlob,
+        getBlobData,
+        getBlob,
+        getBlobObjectURL,
+        clearBlobUrlCache,
+        hasBlobBytes,
+        checkBlobLocality,
+        deleteBlob,
+        clearAll,
+    };
+}
+// low-level building blocks re-exported for callers that need to compose
+// their own resolver chain (e.g. a future transfer layer writing
+// already-hashed, already-verified bytes without re-hashing them here).
+export { writeThroughChain, readThroughChain, hasBytesInChain, removeFromChain } from "./bytes-backend.js";

package/dist/blobs/store.test.d.ts

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

package/dist/blobs/store.test.d.ts.map

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