@bandeira-tech/b3nd-save 0.8.1

package/esm/fs/mod.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Filesystem backend for b3nd.
+ *
+ * Store implementation backed by the local filesystem. Requires an
+ * injected FsExecutor so the package does not depend on a specific
+ * filesystem API. Files hold raw payload bytes — the store is opaque.
+ *
+ * The executor reads via `ReadableStream<Uint8Array>` to avoid forcing
+ * callers (or the executor) to materialize large files in memory.
+ * Writes accept the `StorePayload` union so existing buffered callers
+ * still work without conversion.
+ */
+import type { StorePayload } from "../types.js";
+export interface FsExecutor {
+    readFile: (path: string) => Promise<ReadableStream<Uint8Array>>;
+    writeFile: (path: string, content: StorePayload) => Promise<void>;
+    removeFile: (path: string) => Promise<void>;
+    exists: (path: string) => Promise<boolean>;
+    /**
+     * List the names of *files* that are direct children of `dir`.
+     * Subdirectories and entries deeper than one level MUST NOT be
+     * returned — `ls` / `count` are shallow contracts.
+     */
+    listFiles: (dir: string) => Promise<string[]>;
+    cleanup?: () => Promise<void>;
+}
+export { FsStore } from "./store.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/fs/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/fs/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IAChE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C;;;;OAIG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/esm/fs/mod.js

@@ -0,0 +1,13 @@
+/**
+ * Filesystem backend for b3nd.
+ *
+ * Store implementation backed by the local filesystem. Requires an
+ * injected FsExecutor so the package does not depend on a specific
+ * filesystem API. Files hold raw payload bytes — the store is opaque.
+ *
+ * The executor reads via `ReadableStream<Uint8Array>` to avoid forcing
+ * callers (or the executor) to materialize large files in memory.
+ * Writes accept the `StorePayload` union so existing buffered callers
+ * still work without conversion.
+ */
+export { FsStore } from "./store.js";

package/esm/fs/store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * FsStore — Filesystem implementation of Store.
+ *
+ * Pure mechanical byte storage with no protocol awareness. Writes one
+ * file per entry; the file body is the payload bytes verbatim. The
+ * store is opaque — it does not parse or transform contents.
+ *
+ * `fn=ls` / `fn=count` are shallow direct-leaves only: they list the
+ * `.bin` files directly inside the prefix's mapped directory, never
+ * recursing into subdirectories.
+ */
+import type { DeleteResult, Output, StatusResult } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import { type BytesOnlyEntityMeta } from "../byte-entity-shim.js";
+import type { EntityStore } from "../entity-store.js";
+import type { EntityRecord, EntitySchema } from "../entity.js";
+import type { StoreCapabilities, StoreWriteResult } from "../types.js";
+import type { FsExecutor } from "./mod.js";
+export declare class FsStore implements EntityStore<BytesOnlyEntityMeta> {
+    private readonly rootDir;
+    private readonly executor;
+    constructor(rootDir: string, executor: FsExecutor);
+    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
+    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
+    write(meta: BytesOnlyEntityMeta, entries: {
+        uri: string;
+        record: EntityRecord;
+    }[]): Promise<StoreWriteResult[]>;
+    read<T = EntityRecord | undefined>(meta: BytesOnlyEntityMeta, urls: string[]): Promise<Output<T>[]>;
+    delete(meta: BytesOnlyEntityMeta, uris: string[]): Promise<DeleteResult[]>;
+    private _writeBytes;
+    private _readBytes;
+    private _readOne;
+    /** Resolve the on-disk directory that holds the direct leaves of `prefixUri`. */
+    private _dirForPrefix;
+    /** List direct-child URIs under a prefix (no recursion). */
+    private _listChildUris;
+    private _ls;
+    private _count;
+    private _deleteBytes;
+    status(): Promise<StatusResult>;
+    capabilities(): StoreCapabilities;
+    private _resolvePath;
+}
+//# sourceMappingURL=store.d.ts.map

package/esm/fs/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/fs/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAC3E,OAAO,EAEL,KAAK,mBAAmB,EAIzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAM/D,OAAO,KAAK,EACV,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AA2B3C,qBAAa,OAAQ,YAAW,WAAW,CAAC,mBAAmB,CAAC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;gBAE1B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU;IAUjD,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,mBAAmB;IAIxD,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAI1E,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,KAAK,CACH,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAS9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IASvB,MAAM,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAW5D,WAAW;IAuBzB,OAAO,CAAC,UAAU;YAQJ,QAAQ;IAUtB,iFAAiF;IACjF,OAAO,CAAC,aAAa;IAQrB,4DAA4D;YAC9C,cAAc;YAgBd,GAAG;YA0BH,MAAM;YAON,YAAY;IAmBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAyBrC,YAAY,IAAI,iBAAiB;IAIjC,OAAO,CAAC,YAAY;CAGrB"}

package/esm/fs/store.js

@@ -0,0 +1,194 @@
+/**
+ * FsStore — Filesystem implementation of Store.
+ *
+ * Pure mechanical byte storage with no protocol awareness. Writes one
+ * file per entry; the file body is the payload bytes verbatim. The
+ * store is opaque — it does not parse or transform contents.
+ *
+ * `fn=ls` / `fn=count` are shallow direct-leaves only: they list the
+ * `.bin` files directly inside the prefix's mapped directory, never
+ * recursing into subdirectories.
+ */
+import { bytesOnlyDelete, bytesOnlyEntitySupport, bytesOnlyRead, bytesOnlyWrite, } from "../byte-entity-shim.js";
+import { dispatchRead } from "../dispatch.js";
+import { storageFailure } from "../errors.js";
+import { validateReadParams } from "../read.js";
+const STORE_NAME = "FsStore";
+const EXT = ".bin";
+/**
+ * Convert a URI to a relative filesystem path.
+ * `protocol://host/path` becomes `protocol_host/path.bin`.
+ *
+ * Only the FIRST `://` is rewritten — embedded `://` (rare but legal
+ * in protocol-tunneling uris) stays in the path.
+ */
+function uriToRelPath(uri) {
+    return uri.replace("://", "_") + EXT;
+}
+/**
+ * Convert a relative filesystem path back to a URI.
+ * `protocol_host/path.bin` becomes `protocol://host/path`.
+ */
+function relPathToUri(relPath) {
+    const withoutExt = relPath.endsWith(EXT)
+        ? relPath.slice(0, -EXT.length)
+        : relPath;
+    return withoutExt.replace("_", "://");
+}
+export class FsStore {
+    rootDir;
+    executor;
+    constructor(rootDir, executor) {
+        if (!rootDir)
+            throw new Error("rootDir is required");
+        if (!executor)
+            throw new Error("executor is required");
+        this.rootDir = rootDir.replace(/\/+$/, "");
+        this.executor = executor;
+    }
+    // ── EntityStore surface ──────────────────────────────────────────
+    entitySupport(schema) {
+        return bytesOnlyEntitySupport(schema);
+    }
+    entityStatus(meta) {
+        return Promise.resolve(meta.isBytes ? "live" : "unprovisioned");
+    }
+    provisionEntity(_meta) {
+        return Promise.resolve();
+    }
+    write(meta, entries) {
+        return bytesOnlyWrite(meta, STORE_NAME, entries, (e) => this._writeBytes(e));
+    }
+    read(meta, urls) {
+        return bytesOnlyRead(meta, STORE_NAME, urls, (u) => this._readBytes(u));
+    }
+    delete(meta, uris) {
+        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    }
+    // ── Byte ops (BYTES_ENTITY routing) ──────────────────────────────
+    async _writeBytes(entries) {
+        const results = [];
+        for (const entry of entries) {
+            try {
+                await this.executor.writeFile(this._resolvePath(entry.uri), entry.payload);
+                results.push({ success: true });
+            }
+            catch (err) {
+                results.push({
+                    success: false,
+                    ...storageFailure(err, "Write failed", entry.uri),
+                });
+            }
+        }
+        return results;
+    }
+    _readBytes(urls) {
+        return dispatchRead(urls, STORE_NAME, {
+            read: (p) => this._readOne(p.uri),
+            ls: (p) => this._ls(p),
+            count: (p) => this._count(p),
+        });
+    }
+    async _readOne(uri) {
+        try {
+            return await this.executor.readFile(this._resolvePath(uri));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Resolve the on-disk directory that holds the direct leaves of `prefixUri`. */
+    _dirForPrefix(prefixUri) {
+        const rel = uriToRelPath(prefixUri).slice(0, -EXT.length).replace(/\/+$/, "");
+        return rel ? `${this.rootDir}/${rel}` : this.rootDir;
+    }
+    /** List direct-child URIs under a prefix (no recursion). */
+    async _listChildUris(prefixUri) {
+        let files;
+        try {
+            files = await this.executor.listFiles(this._dirForPrefix(prefixUri));
+        }
+        catch {
+            return [];
+        }
+        const relDir = uriToRelPath(prefixUri).slice(0, -EXT.length).replace(/\/+$/, "");
+        return files
+            .filter((f) => f.endsWith(EXT) && !f.includes("/"))
+            .map((f) => relPathToUri(`${relDir}/${f}`));
+    }
+    async _ls(parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const { params } = parsed;
+        const format = params.format ?? "full";
+        let uris = await this._listChildUris(parsed.uri);
+        if (params.sortBy === "uri") {
+            const dir = params.sortOrder === "desc" ? -1 : 1;
+            uris = [...uris].sort((a, b) => a.localeCompare(b) * dir);
+        }
+        if (params.limit !== undefined) {
+            const page = params.page ?? 1;
+            const start = (page - 1) * params.limit;
+            uris = uris.slice(start, start + params.limit);
+        }
+        if (format === "uris")
+            return uris;
+        const out = [];
+        for (const uri of uris) {
+            out.push([uri, await this._readOne(uri)]);
+        }
+        return out;
+    }
+    async _count(parsed) {
+        if (parsed.params.pattern !== undefined) {
+            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+        }
+        return (await this._listChildUris(parsed.uri)).length;
+    }
+    async _deleteBytes(uris) {
+        const results = [];
+        for (const uri of uris) {
+            try {
+                await this.executor.removeFile(this._resolvePath(uri));
+                results.push({ success: true });
+            }
+            catch {
+                // File may not exist — succeed silently (matches the
+                // miss-is-not-an-error convention)
+                results.push({ success: true });
+            }
+        }
+        return results;
+    }
+    // ── Status ───────────────────────────────────────────────────────
+    async status() {
+        try {
+            const rootExists = await this.executor.exists(this.rootDir);
+            if (!rootExists) {
+                return {
+                    status: "unhealthy",
+                    message: `Root directory not found: ${this.rootDir}`,
+                    fns: ["read", "ls", "count"],
+                };
+            }
+            return {
+                status: "healthy",
+                message: "Filesystem store is operational",
+                fns: ["read", "ls", "count"],
+                details: { rootDir: this.rootDir },
+            };
+        }
+        catch (error) {
+            return {
+                status: "unhealthy",
+                message: error instanceof Error ? error.message : String(error),
+                fns: ["read", "ls", "count"],
+            };
+        }
+    }
+    capabilities() {
+        return { atomicBatch: false };
+    }
+    _resolvePath(uri) {
+        return `${this.rootDir}/${uriToRelPath(uri)}`;
+    }
+}

package/esm/indexeddb/mod.d.ts

@@ -0,0 +1,9 @@
+/**
+ * IndexedDB backend for b3nd.
+ *
+ * Browser IndexedDB Store implementation. Pure mechanical storage
+ * with no protocol awareness — wrap with SaveClient
+ * for NodeProtocolInterface.
+ */
+export { IndexedDBStore } from "./store.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/indexeddb/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/indexeddb/mod.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/esm/indexeddb/mod.js

@@ -0,0 +1,8 @@
+/**
+ * IndexedDB backend for b3nd.
+ *
+ * Browser IndexedDB Store implementation. Pure mechanical storage
+ * with no protocol awareness — wrap with SaveClient
+ * for NodeProtocolInterface.
+ */
+export { IndexedDBStore } from "./store.js";

package/esm/indexeddb/store.d.ts

@@ -0,0 +1,47 @@
+import type { DeleteResult, Output, StatusResult } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import { type BytesOnlyEntityMeta } from "../byte-entity-shim.js";
+import type { EntityStore } from "../entity-store.js";
+import type { EntityRecord, EntitySchema } from "../entity.js";
+import type { StoreCapabilities, StoreWriteResult } from "../types.js";
+export declare class IndexedDBStore implements EntityStore<BytesOnlyEntityMeta> {
+    private readonly databaseName;
+    private readonly storeName;
+    private readonly version;
+    private readonly indexedDB;
+    private readonly keyRange;
+    private db;
+    constructor(config?: {
+        databaseName?: string;
+        storeName?: string;
+        version?: number;
+        indexedDB?: any;
+        IDBKeyRange?: any;
+    });
+    private initDB;
+    private getStore;
+    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
+    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
+    write(meta: BytesOnlyEntityMeta, entries: {
+        uri: string;
+        record: EntityRecord;
+    }[]): Promise<StoreWriteResult[]>;
+    read<T = EntityRecord | undefined>(meta: BytesOnlyEntityMeta, urls: string[]): Promise<Output<T>[]>;
+    delete(meta: BytesOnlyEntityMeta, uris: string[]): Promise<DeleteResult[]>;
+    private _writeBytes;
+    private _readBytes;
+    private _readOne;
+    /**
+     * Open a cursor over the `uri_index` constrained to the prefix.
+     * Returns URIs (and optionally records) that are direct leaves
+     * under `prefixUri` — i.e. `prefixUri + <segment>` with no further
+     * `/`. Honours sortOrder and limit/page via cursor walking.
+     */
+    private _walkLeaves;
+    private _ls;
+    private _count;
+    private _deleteBytes;
+    status(): Promise<StatusResult>;
+    capabilities(): StoreCapabilities;
+}
+//# sourceMappingURL=store.d.ts.map

package/esm/indexeddb/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/indexeddb/store.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAC3E,OAAO,EAEL,KAAK,mBAAmB,EAIzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAO/D,OAAO,KAAK,EACV,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAyErB,qBAAa,cAAe,YAAW,WAAW,CAAC,mBAAmB,CAAC;IACrE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,EAAE,CAA4B;gBAE1B,MAAM,GAAE;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,SAAS,CAAC,EAAE,GAAG,CAAC;QAEhB,WAAW,CAAC,EAAE,GAAG,CAAC;KACd;IAcN,OAAO,CAAC,MAAM;YAuBA,QAAQ;IAStB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,mBAAmB;IAIxD,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAI1E,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,KAAK,CACH,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAS9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IASvB,MAAM,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAW5D,WAAW;IA2DzB,OAAO,CAAC,UAAU;YAQJ,QAAQ;IAgBtB;;;;;OAKG;YACW,WAAW;YAuEX,GAAG;YAcH,MAAM;YAYN,YAAY;IAmCpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAiBrC,YAAY,IAAI,iBAAiB;CAGlC"}

package/esm/indexeddb/store.js

@@ -0,0 +1,299 @@
+/**
+ * IndexedDBStore — browser IndexedDB implementation of Store.
+ *
+ * Pure mechanical byte storage with no protocol awareness. Uses
+ * IndexedDB for large-scale persistent browser storage. IndexedDB's
+ * structured clone preserves `Uint8Array` natively.
+ *
+ * `fn=ls` / `fn=count` are shallow direct-leaves only: cursor over
+ * the `uri_index`, keep records whose URI is `prefix + <segment>`
+ * with no further `/`. The `format=uris` fast path and `count` only
+ * touch the index key — they never load the full record's payload.
+ */
+import * as dntShim from "../_dnt.shims.js";
+import { bytesOnlyDelete, bytesOnlyEntitySupport, bytesOnlyRead, bytesOnlyWrite, } from "../byte-entity-shim.js";
+import { dispatchRead } from "../dispatch.js";
+import { storageFailure } from "../errors.js";
+import { toBytes } from "../payload.js";
+import { validateReadParams } from "../read.js";
+const STORE_NAME = "IndexedDBStore";
+// deno-lint-ignore no-explicit-any
+const idbKeyRange = dntShim.dntGlobalThis.IDBKeyRange;
+export class IndexedDBStore {
+    databaseName;
+    storeName;
+    version;
+    indexedDB;
+    keyRange;
+    db = null;
+    constructor(config = {}) {
+        this.databaseName = config.databaseName || "b3nd";
+        this.storeName = config.storeName || "records";
+        this.version = config.version || 1;
+        this.indexedDB = config.indexedDB ||
+            // deno-lint-ignore no-explicit-any
+            (dntShim.dntGlobalThis.indexedDB ?? null);
+        this.keyRange = config.IDBKeyRange ?? idbKeyRange;
+        if (!this.indexedDB) {
+            throw new Error("IndexedDB is not available in this environment");
+        }
+    }
+    initDB() {
+        if (this.db)
+            return Promise.resolve(this.db);
+        return new Promise((resolve, reject) => {
+            const request = this.indexedDB.open(this.databaseName, this.version);
+            request.onerror = () => reject(new Error(`Failed to open IndexedDB: ${request.error}`));
+            request.onsuccess = () => {
+                this.db = request.result;
+                resolve(request.result);
+            };
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    const store = db.createObjectStore(this.storeName, {
+                        keyPath: "uri",
+                    });
+                    store.createIndex("uri_index", "uri");
+                }
+            };
+        });
+    }
+    async getStore(mode = "readonly") {
+        const db = await this.initDB();
+        return db.transaction([this.storeName], mode).objectStore(this.storeName);
+    }
+    // ── EntityStore surface ──────────────────────────────────────────
+    entitySupport(schema) {
+        return bytesOnlyEntitySupport(schema);
+    }
+    entityStatus(meta) {
+        return Promise.resolve(meta.isBytes ? "live" : "unprovisioned");
+    }
+    provisionEntity(_meta) {
+        return Promise.resolve();
+    }
+    write(meta, entries) {
+        return bytesOnlyWrite(meta, STORE_NAME, entries, (e) => this._writeBytes(e));
+    }
+    read(meta, urls) {
+        return bytesOnlyRead(meta, STORE_NAME, urls, (u) => this._readBytes(u));
+    }
+    delete(meta, uris) {
+        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    }
+    // ── Byte ops (BYTES_ENTITY routing) ──────────────────────────────
+    async _writeBytes(entries) {
+        const results = [];
+        // Collect any streams to bytes BEFORE opening the IDB transaction.
+        // An IDB transaction stays alive only across IDB-callback
+        // microtasks; awaiting a non-IDB promise (like draining a
+        // ReadableStream) yields long enough for the transaction to
+        // auto-commit, after which subsequent put()s either throw
+        // `TransactionInactiveError` or silently no-op depending on the
+        // implementation. fake-indexeddb is permissive about this; real
+        // Chromium is not.
+        let prepared;
+        try {
+            prepared = await Promise.all(entries.map(async (e) => ({
+                uri: e.uri,
+                payload: await toBytes(e.payload),
+            })));
+        }
+        catch (err) {
+            const failure = storageFailure(err, "Write failed");
+            return entries.map(() => ({ success: false, ...failure }));
+        }
+        try {
+            const store = await this.getStore("readwrite");
+            for (const record of prepared) {
+                try {
+                    await new Promise((resolve, reject) => {
+                        const request = store.put(record);
+                        request.onsuccess = () => resolve();
+                        request.onerror = () => reject(new Error(`Failed to write ${record.uri}: ${request.error}`));
+                    });
+                    results.push({ success: true });
+                }
+                catch (err) {
+                    results.push({
+                        success: false,
+                        ...storageFailure(err, "Write failed", record.uri),
+                    });
+                }
+            }
+        }
+        catch (err) {
+            // Outer failure (e.g. db open) — every entry fails with the same
+            // root cause; no per-entry uri since the failure isn't entry-scoped.
+            const failure = storageFailure(err, "Write failed");
+            for (const _ of entries) {
+                results.push({ success: false, ...failure });
+            }
+        }
+        return results;
+    }
+    _readBytes(urls) {
+        return dispatchRead(urls, STORE_NAME, {
+            read: (p) => this._readOne(p.uri),
+            ls: (p) => this._ls(p),
+            count: (p) => this._count(p),
+        });
+    }
+    async _readOne(uri) {
+        try {
+            const store = await this.getStore();
+            return await new Promise((resolve) => {
+                const request = store.get(uri);
+                request.onsuccess = () => {
+                    const record = request.result;
+                    resolve(record ? record.payload : undefined);
+                };
+                request.onerror = () => resolve(undefined);
+            });
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Open a cursor over the `uri_index` constrained to the prefix.
+     * Returns URIs (and optionally records) that are direct leaves
+     * under `prefixUri` — i.e. `prefixUri + <segment>` with no further
+     * `/`. Honours sortOrder and limit/page via cursor walking.
+     */
+    async _walkLeaves(parsed, onlyUris) {
+        const { uri: prefix, params } = parsed;
+        const desc = params.sortBy === "uri" && params.sortOrder === "desc";
+        const direction = desc ? "prev" : "next";
+        const limit = params.limit;
+        const offset = limit !== undefined ? ((params.page ?? 1) - 1) * limit : 0;
+        // Bound the cursor to `[prefix, prefix + ￿)` — both ends
+        // inclusive of the prefix, exclusive of anything past the high
+        // surrogate. Fall back to a full scan if IDBKeyRange isn't
+        // available in this environment.
+        const range = this.keyRange
+            ? this.keyRange.bound(prefix, prefix + "￿", false, false)
+            : undefined;
+        const store = await this.getStore();
+        const index = store.index("uri_index");
+        return await new Promise((resolve, reject) => {
+            const out = [];
+            let skipped = 0;
+            const request = onlyUris
+                ? index.openKeyCursor(range, direction)
+                : index.openCursor(range, direction);
+            request.onsuccess = () => {
+                const cursor = request.result;
+                if (!cursor) {
+                    resolve(out);
+                    return;
+                }
+                const key = (onlyUris ? cursor.key : cursor.value.uri);
+                if (!key.startsWith(prefix)) {
+                    resolve(out);
+                    return;
+                }
+                const tail = key.slice(prefix.length);
+                if (tail === "" || tail.includes("/")) {
+                    cursor.continue();
+                    return;
+                }
+                if (skipped < offset) {
+                    skipped++;
+                    cursor.continue();
+                    return;
+                }
+                if (onlyUris) {
+                    out.push({ uri: key });
+                }
+                else {
+                    out.push({ uri: key, payload: cursor.value.payload });
+                }
+                if (limit !== undefined && out.length >= limit) {
+                    resolve(out);
+                    return;
+                }
+                cursor.continue();
+            };
+            request.onerror = () => reject(request.error ?? new Error("Cursor failed"));
+        });
+    }
+    async _ls(parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const format = parsed.params.format ?? "full";
+        const onlyUris = format === "uris";
+        try {
+            const entries = await this._walkLeaves(parsed, onlyUris);
+            if (onlyUris)
+                return entries.map((e) => e.uri);
+            return entries.map((e) => [e.uri, e.payload]);
+        }
+        catch {
+            return [];
+        }
+    }
+    async _count(parsed) {
+        if (parsed.params.pattern !== undefined) {
+            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+        }
+        try {
+            const entries = await this._walkLeaves(parsed, true);
+            return entries.length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async _deleteBytes(uris) {
+        const results = [];
+        try {
+            const store = await this.getStore("readwrite");
+            for (const uri of uris) {
+                try {
+                    await new Promise((resolve, reject) => {
+                        const request = store.delete(uri);
+                        request.onsuccess = () => resolve();
+                        request.onerror = () => reject(new Error(`Failed to delete ${uri}: ${request.error}`));
+                    });
+                    results.push({ success: true });
+                }
+                catch (err) {
+                    results.push({
+                        success: false,
+                        ...storageFailure(err, "Delete failed", uri),
+                    });
+                }
+            }
+        }
+        catch (err) {
+            // Outer failure — every uri fails with the same root cause.
+            const failure = storageFailure(err, "Delete failed");
+            for (const _ of uris) {
+                results.push({ success: false, ...failure });
+            }
+        }
+        return results;
+    }
+    // ── Status ───────────────────────────────────────────────────────
+    async status() {
+        try {
+            await this.initDB();
+            return {
+                status: "healthy",
+                schema: [],
+                fns: ["read", "ls", "count"],
+            };
+        }
+        catch {
+            return {
+                status: "unhealthy",
+                schema: [],
+                fns: ["read", "ls", "count"],
+            };
+        }
+    }
+    capabilities() {
+        return { atomicBatch: false };
+    }
+}