@weaveprotocol/core 0.1.0

package/dist/storage/folder-adapter.js

@@ -0,0 +1,280 @@
+/**
+ * @module folder-adapter
+ * A StorageAdapter over a directory the user picked on their own disk.
+ *
+ * This is the store that escapes the origin sandbox. IndexedDB, localStorage and
+ * OPFS ("Origin Private File System" — the name is the specification) are all
+ * keyed by origin, so two deployments of the same app can never see each other's
+ * data. A directory handle is not: each origin asks the user for permission once
+ * and both end up reading the same files. That is what makes an app a *view* on
+ * the user's data rather than an owner of a private copy of it.
+ *
+ * The layout is meant to be legible, because the point is that the folder
+ * belongs to the user:
+ *
+ * ```
+ * <folder>/
+ *   accounts.json                    who has an account here
+ *   accounts/<id>/account.json       that account's keys, locked
+ *   accounts/<id>/stores/<name>/
+ *     kv/<key>                       MST nodes, the root pointer, space records
+ *     expressions/<cid>.json
+ * ```
+ *
+ * **Expressions are the truth; the MST is an index over them.** That inversion
+ * is what lets two origins share one folder with no locking. Every expression
+ * file is immutable and named by its own content hash, so concurrent writers can
+ * only ever add files that agree — the one genuinely mutable thing, the MST root
+ * pointer, is derived state that either side can rebuild. {@link reconcileFolder}
+ * is what rebuilds it.
+ */
+import { utf8Encode, utf8Decode } from '../utils/encoding.js';
+const EXPRESSION_SUFFIX = '.json';
+/**
+ * Percent-encodes a storage key into a filename.
+ *
+ * Only lowercase is left unescaped, which looks excessive until you remember
+ * that macOS and Windows filesystems are case-insensitive by default: without
+ * this, the keys `space:Abc` and `space:abc` would quietly become one file and
+ * one of the two values would be lost.
+ *
+ * @param key A storage key
+ * @returns A filename safe on every filesystem, and reversible
+ */
+function encodeKey(key) {
+    let out = '';
+    for (const byte of utf8Encode(key)) {
+        const char = String.fromCharCode(byte);
+        out += /[a-z0-9._-]/.test(char) ? char : `%${byte.toString(16).padStart(2, '0').toUpperCase()}`;
+    }
+    return out;
+}
+/**
+ * Reverses {@link encodeKey}.
+ * @param name A filename written by this adapter
+ * @returns The storage key it stands for
+ */
+function decodeKey(name) {
+    const bytes = [];
+    for (let i = 0; i < name.length; i++) {
+        if (name[i] === '%') {
+            bytes.push(Number.parseInt(name.slice(i + 1, i + 3), 16));
+            i += 2;
+        }
+        else {
+            bytes.push(name.charCodeAt(i));
+        }
+    }
+    return utf8Decode(new Uint8Array(bytes));
+}
+/** Whether a rejection means "that file isn't there", which is usually not an error. */
+function isNotFound(error) {
+    return error instanceof Error && error.name === 'NotFoundError';
+}
+/**
+ * Walks — and creates — a chain of subdirectories.
+ * @param root The directory to start from
+ * @param segments Path segments, already safe for a filename
+ * @returns The directory at the end of the path
+ */
+async function resolvePath(root, segments) {
+    let current = root;
+    for (const segment of segments) {
+        current = await current.getDirectoryHandle(segment, { create: true });
+    }
+    return current;
+}
+/**
+ * Reads a file, treating absence as null rather than as a failure.
+ * @param dir The directory holding it
+ * @param name The filename
+ * @returns Its bytes, or null when there is no such file
+ */
+export async function readFolderFile(dir, name) {
+    try {
+        const handle = await dir.getFileHandle(name);
+        const file = await handle.getFile();
+        return new Uint8Array(await file.arrayBuffer());
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+}
+/**
+ * Writes a file, replacing whatever was there.
+ * @param dir The directory to write into
+ * @param name The filename
+ * @param bytes The contents
+ */
+export async function writeFolderFile(dir, name, bytes) {
+    const handle = await dir.getFileHandle(name, { create: true });
+    const writable = await handle.createWritable();
+    await writable.write(bytes);
+    await writable.close();
+}
+/**
+ * Deletes a file, ignoring one that is already gone.
+ * @param dir The directory holding it
+ * @param name The filename
+ */
+async function removeFile(dir, name) {
+    try {
+        await dir.removeEntry(name);
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+}
+/**
+ * Opens a storage adapter backed by a directory on the user's disk.
+ *
+ * Expressions are held in memory as well as on disk — a query would otherwise
+ * mean one file read per record, and the example app re-lists on every render.
+ * The cost is that the working set has to fit in memory.
+ *
+ * @param root The directory the user picked
+ * @param path Where to keep these files inside it, `/` separating
+ *   subdirectories. The full path from the folder root, so that several
+ *   accounts can each have a subtree of their own.
+ * @returns An adapter over that directory, already populated
+ */
+export async function createFolderAdapter(root, path) {
+    const segments = path.split('/').filter(Boolean).map(encodeKey);
+    if (segments.length === 0) {
+        throw new Error('A folder adapter needs a path to live in.');
+    }
+    const base = await resolvePath(root, segments);
+    const kvDir = await base.getDirectoryHandle('kv', { create: true });
+    const expressionsDir = await base.getDirectoryHandle('expressions', { create: true });
+    const expressions = new Map();
+    // Content-addressed nodes never change, so caching them is free. The root
+    // pointer does change, which is why `reload` throws the whole cache away
+    // rather than trying to be clever about which entries are still good.
+    const kvCache = new Map();
+    async function readExpressionFile(name) {
+        const bytes = await readFolderFile(expressionsDir, name);
+        if (!bytes)
+            return null;
+        try {
+            return JSON.parse(utf8Decode(bytes));
+        }
+        catch {
+            // A half-written file from a writer that died mid-flush. It will either be
+            // rewritten or stay unreadable; either way it is not ours to repair.
+            return null;
+        }
+    }
+    async function reload() {
+        const seen = new Set();
+        const added = [];
+        for await (const name of expressionsDir.keys()) {
+            if (!name.endsWith(EXPRESSION_SUFFIX))
+                continue;
+            const id = decodeKey(name.slice(0, -EXPRESSION_SUFFIX.length));
+            seen.add(id);
+            if (expressions.has(id))
+                continue;
+            const expression = await readExpressionFile(name);
+            if (!expression)
+                continue;
+            expressions.set(id, expression);
+            added.push(id);
+        }
+        const removed = [...expressions.keys()].filter((id) => !seen.has(id));
+        for (const id of removed)
+            expressions.delete(id);
+        kvCache.clear();
+        return { added, removed };
+    }
+    await reload();
+    return Object.freeze({
+        namespace: path,
+        reload,
+        async listExpressionIds() {
+            return [...expressions.keys()];
+        },
+        async get(key) {
+            const cached = kvCache.get(key);
+            if (cached !== undefined)
+                return cached;
+            const bytes = await readFolderFile(kvDir, encodeKey(key));
+            kvCache.set(key, bytes);
+            return bytes;
+        },
+        async put(key, value) {
+            await writeFolderFile(kvDir, encodeKey(key), value);
+            kvCache.set(key, value);
+        },
+        async delete(key) {
+            await removeFile(kvDir, encodeKey(key));
+            kvCache.set(key, null);
+        },
+        async has(key) {
+            const cached = kvCache.get(key);
+            if (cached !== undefined)
+                return cached !== null;
+            return (await readFolderFile(kvDir, encodeKey(key))) !== null;
+        },
+        async list(prefix = '') {
+            const keys = [];
+            for await (const name of kvDir.keys()) {
+                const key = decodeKey(name);
+                if (!key.startsWith(prefix))
+                    continue;
+                keys.push(key);
+                // Another writer created it after this process looked and found
+                // nothing. The file is on disk now, so the remembered miss is stale.
+                if (kvCache.get(key) === null)
+                    kvCache.delete(key);
+            }
+            return keys;
+        },
+        async queryExpressions(collection, limit = 50, cursor) {
+            // Ordered so a cursor means the same thing on every device, which a
+            // directory listing on its own would not guarantee.
+            const ordered = [...expressions.values()]
+                .filter((expression) => expression.collection === collection)
+                .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+            const start = cursor ? ordered.findIndex((expression) => expression.id === cursor) + 1 : 0;
+            return ordered.slice(start, start + limit);
+        },
+        async putExpression(expression) {
+            await writeFolderFile(expressionsDir, encodeKey(expression.id) + EXPRESSION_SUFFIX, utf8Encode(JSON.stringify(expression)));
+            expressions.set(expression.id, expression);
+        },
+        async getExpression(id) {
+            const known = expressions.get(id);
+            if (known)
+                return known;
+            // Not in memory: another origin may have written it since the last reload.
+            const expression = await readExpressionFile(encodeKey(id) + EXPRESSION_SUFFIX);
+            if (expression)
+                expressions.set(id, expression);
+            return expression;
+        },
+        async deleteExpression(id) {
+            await removeFile(expressionsDir, encodeKey(id) + EXPRESSION_SUFFIX);
+            expressions.delete(id);
+        },
+        async batch(ops) {
+            for (const op of ops) {
+                if (op.type === 'put') {
+                    await writeFolderFile(kvDir, encodeKey(op.key), op.value);
+                    kvCache.set(op.key, op.value);
+                }
+                else {
+                    await removeFile(kvDir, encodeKey(op.key));
+                    kvCache.set(op.key, null);
+                }
+            }
+        },
+        async close() {
+            expressions.clear();
+            kvCache.clear();
+        },
+    });
+}
+//# sourceMappingURL=folder-adapter.js.map

package/dist/storage/folder-adapter.js.map

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

package/dist/storage/folder-reconcile.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module folder-reconcile
+ * Making a shared folder converge, without anybody having to take a lock.
+ *
+ * Two origins — or two devices behind Dropbox, iCloud or Syncthing — can write
+ * into one folder at the same time. Almost nothing there can actually conflict:
+ * expression files are named by their own content hash, so two writers either
+ * produce different files or produce byte-identical ones. The single mutable
+ * thing is the MST root pointer, and a lost write to it costs nothing, because
+ * the tree is derived state.
+ *
+ * So the rule is: **the set of expression files wins.** Reconciling means
+ * rebuilding the tree until it agrees with the directory — adding what turned up
+ * and dropping what went away. That is the whole concurrency story.
+ */
+import type { StorageProvider } from './storage-provider.js';
+import type { FolderAdapter } from './folder-adapter.js';
+import type { Expression } from '../types.js';
+/** What a pass over the folder found */
+export interface FolderReconciliation {
+    /** Expression files that appeared since the last pass — another origin's writes */
+    readonly added: ReadonlyArray<string>;
+    /** Expression files that are gone */
+    readonly removed: ReadonlyArray<string>;
+    /**
+     * Tree entries that had to be fixed to match the directory.
+     *
+     * Usually empty, and that is the expected case rather than a lucky one: both
+     * origins read and write the same root pointer, so the tree one of them built
+     * is normally already right for the other. This fills in when a pointer write
+     * was lost — two writers racing, or a folder that came back from Dropbox with
+     * files the pointer never saw.
+     */
+    readonly repaired: ReadonlyArray<string>;
+    /** Whether anything moved at all — worth a re-render when true */
+    readonly changed: boolean;
+}
+/**
+ * Re-reads the folder and brings the Merkle tree back in line with it.
+ *
+ * Safe to call as often as you like: with nothing new on disk it is two
+ * directory listings and no writes.
+ *
+ * @param storage The provider whose tree should be brought up to date
+ * @param adapter The folder adapter underneath it
+ * @param accept Whether a version found on disk may be placed. Anyone who can
+ *   write the folder can drop a file in it — another site given the folder, a
+ *   sync service — so what turns up there is checked like anything arriving
+ *   from a peer. A version refused now stays on disk and is asked about again.
+ * @returns What moved
+ */
+export declare function reconcileFolder(storage: StorageProvider, adapter: FolderAdapter, accept?: (expression: Expression) => Promise<boolean>): Promise<FolderReconciliation>;
+//# sourceMappingURL=folder-reconcile.d.ts.map

package/dist/storage/folder-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-reconcile.d.ts","sourceRoot":"","sources":["../../src/storage/folder-reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,aAAa,EACtB,MAAM,GAAE,CAAC,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAoB,GACtE,OAAO,CAAC,oBAAoB,CAAC,CAoC/B"}

package/dist/storage/folder-reconcile.js

@@ -0,0 +1,65 @@
+/**
+ * @module folder-reconcile
+ * Making a shared folder converge, without anybody having to take a lock.
+ *
+ * Two origins — or two devices behind Dropbox, iCloud or Syncthing — can write
+ * into one folder at the same time. Almost nothing there can actually conflict:
+ * expression files are named by their own content hash, so two writers either
+ * produce different files or produce byte-identical ones. The single mutable
+ * thing is the MST root pointer, and a lost write to it costs nothing, because
+ * the tree is derived state.
+ *
+ * So the rule is: **the set of expression files wins.** Reconciling means
+ * rebuilding the tree until it agrees with the directory — adding what turned up
+ * and dropping what went away. That is the whole concurrency story.
+ */
+/**
+ * Re-reads the folder and brings the Merkle tree back in line with it.
+ *
+ * Safe to call as often as you like: with nothing new on disk it is two
+ * directory listings and no writes.
+ *
+ * @param storage The provider whose tree should be brought up to date
+ * @param adapter The folder adapter underneath it
+ * @param accept Whether a version found on disk may be placed. Anyone who can
+ *   write the folder can drop a file in it — another site given the folder, a
+ *   sync service — so what turns up there is checked like anything arriving
+ *   from a peer. A version refused now stays on disk and is asked about again.
+ * @returns What moved
+ */
+export async function reconcileFolder(storage, adapter, accept = async () => true) {
+    const disk = await adapter.reload();
+    const onDisk = new Set(await adapter.listExpressionIds());
+    // Versions another writer put on disk that this tree has not placed. Each
+    // goes through the ordering rule like anything else: it becomes current,
+    // is kept as history, or loses and is dropped — the same decision the other
+    // writer reached, so both converge on the same tree.
+    const indexed = new Set((await storage.entries()).map((entry) => entry.value));
+    const missing = [...onDisk].filter((id) => !indexed.has(id));
+    const placed = [];
+    for (const id of missing) {
+        const expression = await adapter.getExpression(id);
+        // A file can vanish between the listing and the read — another writer
+        // dropping a superseded version. Nothing to add, and the next pass agrees.
+        if (expression && (await accept(expression))) {
+            await storage.addExpression(expression);
+            placed.push(id);
+        }
+    }
+    // Entries whose file is gone: another writer superseded and dropped it, and
+    // its replacement was placed above.
+    const stale = [...new Set((await storage.entries()).map((entry) => entry.value))].filter((id) => !onDisk.has(id) && !missing.includes(id));
+    for (const id of stale) {
+        if (!(await adapter.getExpression(id)))
+            await storage.removeExpression(id);
+    }
+    // A refused file is not a change: it would otherwise redraw every pass.
+    const repaired = [...placed, ...stale];
+    return {
+        added: disk.added,
+        removed: disk.removed,
+        repaired,
+        changed: disk.added.length > 0 || disk.removed.length > 0 || repaired.length > 0,
+    };
+}
+//# sourceMappingURL=folder-reconcile.js.map

package/dist/storage/folder-reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-reconcile.js","sourceRoot":"","sources":["../../src/storage/folder-reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA0BH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAwB,EACxB,OAAsB,EACtB,SAAuD,KAAK,IAAI,EAAE,CAAC,IAAI;IAEvE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAE1D,0EAA0E;IAC1E,yEAAyE;IACzE,4EAA4E;IAC5E,qDAAqD;IACrD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;QACnD,sEAAsE;QACtE,2EAA2E;QAC3E,IAAI,UAAU,IAAI,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;YAC7C,MAAM,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YACxC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,oCAAoC;IACpC,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3I,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;YAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,wEAAwE;IACxE,MAAM,QAAQ,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC;IACvC,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ;QACR,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;KACjF,CAAC;AACJ,CAAC"}

package/dist/storage/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module storage
+ * Exports all storage related functionality.
+ */
+export * from './indexeddb-adapter.js';
+export * from './mst.js';
+export * from './storage-provider.js';
+export * from './directory-access.js';
+export type { DirectoryHandleLike } from './folder-adapter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/storage/index.js

@@ -0,0 +1,9 @@
+/**
+ * @module storage
+ * Exports all storage related functionality.
+ */
+export * from './indexeddb-adapter.js';
+export * from './mst.js';
+export * from './storage-provider.js';
+export * from './directory-access.js';
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC"}

package/dist/storage/indexeddb-adapter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module indexeddb-adapter
+ * IndexedDB implementation of StorageAdapter for P2P network.
+ */
+import type { StorageAdapter } from '../types.js';
+/**
+ * Creates an IndexedDB backed storage adapter.
+ * @param dbName The name of the database (defaults to 'weave-storage')
+ * @returns A promise resolving to the StorageAdapter
+ */
+export declare function createIndexedDBAdapter(dbName?: string): Promise<StorageAdapter>;
+//# sourceMappingURL=indexeddb-adapter.d.ts.map

package/dist/storage/indexeddb-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb-adapter.d.ts","sourceRoot":"","sources":["../../src/storage/indexeddb-adapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,aAAa,CAAC;AAyCvE;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,CAuKtG"}

package/dist/storage/indexeddb-adapter.js

@@ -0,0 +1,190 @@
+/**
+ * @module indexeddb-adapter
+ * IndexedDB implementation of StorageAdapter for P2P network.
+ */
+/**
+ * Bumped to 2 when MST nodes gained a `height` field. Opening an older
+ * database wipes it rather than reading nodes the tree can no longer parse.
+ */
+const DB_VERSION = 2;
+/**
+ * Promisify an IDBRequest.
+ * @param request The IDBRequest to promisify
+ * @returns A promise that resolves with the request result
+ */
+function idbRequest(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+/**
+ * Helper to manage IDBTransactions.
+ * @param db The IDB database instance
+ * @param stores The stores to include in the transaction
+ * @param mode The transaction mode ('readonly' | 'readwrite')
+ * @returns The transaction and a promise that resolves when it completes
+ */
+function idbTransaction(db, stores, mode) {
+    const tx = db.transaction(stores, mode);
+    const complete = new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+        tx.onabort = () => reject(new Error('Transaction aborted'));
+    });
+    return { tx, complete };
+}
+/**
+ * Creates an IndexedDB backed storage adapter.
+ * @param dbName The name of the database (defaults to 'weave-storage')
+ * @returns A promise resolving to the StorageAdapter
+ */
+export async function createIndexedDBAdapter(dbName = 'weave-storage') {
+    const db = await new Promise((resolve, reject) => {
+        const request = globalThis.indexedDB.open(dbName, DB_VERSION);
+        request.onupgradeneeded = (event) => {
+            const db = request.result;
+            const previousVersion = event.oldVersion;
+            // v1 stored MST nodes without a height, which the current tree cannot
+            // read. There is no way to migrate them — the old structure was a single
+            // flat node with no tree to recover — so the local cache is dropped and
+            // rebuilt by syncing with peers.
+            if (previousVersion > 0 && previousVersion < 2) {
+                for (const name of ['kv', 'expressions']) {
+                    if (db.objectStoreNames.contains(name))
+                        db.deleteObjectStore(name);
+                }
+            }
+            // Store for key-value (MST nodes, root cid, etc)
+            if (!db.objectStoreNames.contains('kv')) {
+                db.createObjectStore('kv');
+            }
+            // Store for expressions
+            if (!db.objectStoreNames.contains('expressions')) {
+                const expStore = db.createObjectStore('expressions', { keyPath: 'id' });
+                expStore.createIndex('collection', 'collection', { unique: false });
+                expStore.createIndex('author', 'author', { unique: false });
+                expStore.createIndex('createdAt', 'createdAt', { unique: false });
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+    return Object.freeze({
+        async get(key) {
+            const { tx } = idbTransaction(db, ['kv'], 'readonly');
+            const store = tx.objectStore('kv');
+            const result = await idbRequest(store.get(key));
+            return result ? new Uint8Array(result) : null;
+        },
+        async put(key, value) {
+            const { tx, complete } = idbTransaction(db, ['kv'], 'readwrite');
+            const store = tx.objectStore('kv');
+            store.put(value.buffer, key);
+            await complete;
+        },
+        async delete(key) {
+            const { tx, complete } = idbTransaction(db, ['kv'], 'readwrite');
+            const store = tx.objectStore('kv');
+            store.delete(key);
+            await complete;
+        },
+        async has(key) {
+            const { tx } = idbTransaction(db, ['kv'], 'readonly');
+            const store = tx.objectStore('kv');
+            const count = await idbRequest(store.count(key));
+            return count > 0;
+        },
+        async list(prefix = '') {
+            const { tx } = idbTransaction(db, ['kv'], 'readonly');
+            const store = tx.objectStore('kv');
+            const keys = [];
+            let request;
+            if (prefix) {
+                const bound = prefix + '\uFFFF';
+                request = store.openCursor(IDBKeyRange.bound(prefix, bound, false, false));
+            }
+            else {
+                request = store.openCursor();
+            }
+            await new Promise((resolve, reject) => {
+                request.onsuccess = (event) => {
+                    const cursor = event.target.result;
+                    if (cursor) {
+                        keys.push(cursor.key);
+                        cursor.continue();
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+                request.onerror = () => reject(request.error);
+            });
+            return keys;
+        },
+        async queryExpressions(collection, limit = 50, cursor) {
+            const { tx } = idbTransaction(db, ['expressions'], 'readonly');
+            const store = tx.objectStore('expressions');
+            const index = store.index('collection');
+            const range = IDBKeyRange.only(collection);
+            const request = index.openCursor(range);
+            const results = [];
+            let advanced = !cursor;
+            await new Promise((resolve, reject) => {
+                request.onsuccess = (event) => {
+                    const idbCursor = event.target.result;
+                    if (!idbCursor || results.length >= limit) {
+                        resolve();
+                        return;
+                    }
+                    if (!advanced && cursor && idbCursor.primaryKey === cursor) {
+                        advanced = true;
+                        idbCursor.continue();
+                        return;
+                    }
+                    if (advanced) {
+                        results.push(idbCursor.value);
+                    }
+                    idbCursor.continue();
+                };
+                request.onerror = () => reject(request.error);
+            });
+            return results;
+        },
+        async putExpression(expression) {
+            const { tx, complete } = idbTransaction(db, ['expressions'], 'readwrite');
+            const store = tx.objectStore('expressions');
+            store.put(expression);
+            await complete;
+        },
+        async getExpression(id) {
+            const { tx } = idbTransaction(db, ['expressions'], 'readonly');
+            const store = tx.objectStore('expressions');
+            const result = await idbRequest(store.get(id));
+            return result || null;
+        },
+        async deleteExpression(id) {
+            const { tx, complete } = idbTransaction(db, ['expressions'], 'readwrite');
+            const store = tx.objectStore('expressions');
+            store.delete(id);
+            await complete;
+        },
+        async batch(ops) {
+            const { tx, complete } = idbTransaction(db, ['kv'], 'readwrite');
+            const store = tx.objectStore('kv');
+            for (const op of ops) {
+                if (op.type === 'put') {
+                    store.put(op.value.buffer, op.key);
+                }
+                else if (op.type === 'delete') {
+                    store.delete(op.key);
+                }
+            }
+            await complete;
+        },
+        async close() {
+            db.close();
+        }
+    });
+}
+//# sourceMappingURL=indexeddb-adapter.js.map