@rapidmx/web-client 0.3.0 → 0.4.0

package/dist/apps/shared/search/localIndexSizePreference.js

@@ -0,0 +1,78 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The user-adjustable byte budget behind the Tier 2 local index's window (`localIndexBuilder.ts`'s
+ * `buildLocalIndex()`). Stored in `localStorage`, not synced to the server - a per-device preference
+ * about *this device's* own local OPFS storage, the same posture `idleTimeout.ts`
+ * (`@rapidmx/react-shared`) already takes for its own per-device setting, which this file mirrors.
+ *
+ * `specs/search.md` §10/§11 distinguish "Web" (quota-limited) from "Native desktop" (disk-limited) as
+ * different rows of the same Window Sizing table, not different storage engines - Electron's renderer is
+ * Chromium, so it runs this exact same OPFS/wa-sqlite/`EncryptingVFS` code, just with more disk headroom
+ * to spend. `isElectronRuntime()` reads `window.rapidmx` - the `contextBridge` global
+ * `electron-client/src/main/preload.ts` exposes only inside that renderer (see its own `global.d.ts`) -
+ * as a runtime duck-type signal, so this file (which `electron-client` consumes unmodified via its
+ * `link:../web-client` dependency - see `localIndexBuilder.ts`'s own doc comment on that) never needs an
+ * explicit "which platform am I" value threaded down from anywhere.
+ */
+const STORAGE_KEY = "rapidmx:local-index-byte-budget";
+const MB = 1024 * 1024;
+const GB = 1024 * MB;
+/** §11's Window Sizing table, Web row. */
+export const WEB_DEFAULT_BYTE_BUDGET_BYTES = 500 * MB;
+/** §11's Window Sizing table, Native desktop row - still a real, user-adjustable ceiling (not
+ * `UNBOUNDED`), just a roomier default given Electron's storage is disk-limited rather than
+ * browser-quota-limited. */
+export const ELECTRON_DEFAULT_BYTE_BUDGET_BYTES = 1 * GB;
+/** Selectable presets for the Settings UI. `0` means "unlimited" - `applyEviction()`
+ * (`localIndexWorker.ts`) already treats a falsy byte budget as unconfigured/unenforced. */
+export const LOCAL_INDEX_SIZE_OPTIONS = [
+    { bytes: 100 * MB, label: "100 MB" },
+    { bytes: 250 * MB, label: "250 MB" },
+    { bytes: WEB_DEFAULT_BYTE_BUDGET_BYTES, label: "500 MB" },
+    { bytes: ELECTRON_DEFAULT_BYTE_BUDGET_BYTES, label: "1 GB" },
+    { bytes: 2 * GB, label: "2 GB" },
+    { bytes: 5 * GB, label: "5 GB" },
+    { bytes: 10 * GB, label: "10 GB" },
+    { bytes: 0, label: "Unlimited (disk space only)" },
+];
+function isElectronRuntime() {
+    return typeof window !== "undefined" && "rapidmx" in window;
+}
+/** This device's default byte budget before any explicit preference is saved - `500 MB` in a browser
+ * tab, `1 GB` in the Electron shell. */
+export function getDefaultLocalIndexByteBudget() {
+    return isElectronRuntime() ? ELECTRON_DEFAULT_BYTE_BUDGET_BYTES : WEB_DEFAULT_BYTE_BUDGET_BYTES;
+}
+/**
+ * Reads this device's configured local-index byte budget. Falls back to
+ * `getDefaultLocalIndexByteBudget()` for a never-configured device, a corrupted/non-numeric stored
+ * value, or a `localStorage` access that throws (private-browsing/storage-blocked contexts) - never
+ * throws itself, matching `getIdleTimeoutMinutes()`'s identical fallback posture.
+ */
+export function getLocalIndexByteBudget() {
+    try {
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (stored === null) {
+            return getDefaultLocalIndexByteBudget();
+        }
+        const parsed = Number(stored);
+        return Number.isFinite(parsed) && parsed >= 0 ? parsed : getDefaultLocalIndexByteBudget();
+    }
+    catch {
+        return getDefaultLocalIndexByteBudget();
+    }
+}
+/** Persists this device's local-index byte-budget preference. A `localStorage` write failure is
+ * swallowed, not thrown - the setting just doesn't survive a reload in that case, same fallback-to-default
+ * behavior `getLocalIndexByteBudget()` already has for a storage-blocked context. */
+export function setLocalIndexByteBudget(bytes) {
+    try {
+        localStorage.setItem(STORAGE_KEY, String(bytes));
+    }
+    catch {
+        // Best-effort - see this function's own doc comment.
+    }
+}

package/dist/apps/shared/search/localIndexVFS.js

@@ -0,0 +1,230 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _EncryptingVFS_instances, _EncryptingVFS_inner, _EncryptingVFS_key, _EncryptingVFS_filenamesByFileId, _EncryptingVFS_readBlock, _EncryptingVFS_writeBlock;
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * `EncryptingVFS` - the Tier 2 local index's at-rest encryption layer (`specs/search.md` §11
+ * "Persistence and protection", §13 "Encryption at Rest": "no official SQLCipher WASM build exists...
+ * encryption at rest requires a custom VFS that encrypts pages before they reach OPFS").
+ *
+ * Wraps (composes, does not subclass - `AccessHandlePoolVFS`'s own file-table state is private `#`
+ * fields) an `AccessHandlePoolVFS` instance and delegates every `FacadeVFS` method straight through
+ * except `jRead`/`jWrite`, which it intercepts to decrypt/encrypt pages.
+ *
+ * ## Page layout
+ *
+ * SQLite is opened with a fixed 4096-byte page size (`PRAGMA page_size=4096` - set by
+ * `localIndexWorker.ts` before the first write, since SQLite fixes a database's page size on creation).
+ * Each *logical* 4096-byte page is stored *physically* as `nonce(12) || AES-256-GCM(ciphertext(4096) ||
+ * tag(16))` = 4124 bytes, at a remapped offset (`physicalOffset(page) = page * 4124`). This block size
+ * is this class's own fixed constant, independent of whatever byte range a given `jRead`/`jWrite` call
+ * actually requests - reads/writes are handled generically over whichever physical blocks the requested
+ * logical range overlaps (including a read-modify-write for a sub-block write), not by assuming SQLite
+ * only ever issues page-aligned, page-sized I/O. That assumption holds for the *main database file* once
+ * its page size is fixed, but handling the general case costs little and removes the need to rely on it.
+ *
+ * **A fresh random nonce is generated on every write, never reused or derived from a counter** - the
+ * simplest way to make an AES-GCM (key, nonce) pair never repeat across different plaintexts, which is
+ * the one hard requirement GCM has. The nonce travels with its block, so decryption never needs any
+ * external state (a lost/corrupted counter, a persisted salt) to reconstruct it.
+ *
+ * **AAD binds each block to its logical filename and page index** (not just its own ciphertext) - GCM
+ * authenticates a block's own content but not its *position*; without this, an attacker able to write
+ * directly into this origin's OPFS storage (outside this codebase's own threat model per spec §4, which
+ * excludes a compromised client, but cheap to close off anyway) could silently swap two blocks and each
+ * would still decrypt "successfully" on its own, corrupting data instead of failing loudly. Binding to
+ * position turns a swap into a caught decryption failure - see `PageCorruptedError` below - the same
+ * "invalidate and rebuild" path a schema-version mismatch already takes (spec §11 "Invalidation").
+ *
+ * **No WAL, no rollback journal.** `localIndexWorker.ts` opens the database with `journal_mode=OFF`. A
+ * page cipher for the main database file is one encryption surface; WAL frames (their own header +
+ * checksum format) and rollback-journal records (their own, different record format) would each be a
+ * *second* one. This index has no durability requirement to justify that cost - spec §11 already
+ * requires discarding and rebuilding it on corruption, schema change, key rotation, or platform storage
+ * eviction, and eviction "MUST NOT block search" - so an interrupted write in the worst case is just
+ * caught by the same GCM-auth-failure -> rebuild path as any other corruption, never partial/torn state
+ * silently trusted.
+ *
+ * Every `jRead`/`jWrite` here is `async` (declared `async` specifically so `FacadeVFS.hasAsyncMethod()`
+ * detects it via `instanceof AsyncFunction` and awaits it) because `crypto.subtle.encrypt`/`decrypt` has
+ * no synchronous form in a browser - this is *why* `localIndexWorker.ts` boots the Asyncify SQLite build
+ * (`dist/wa-sqlite-async.mjs`), not the plain synchronous one `AccessHandlePoolVFS`'s own doc comment
+ * says it's designed for: that claim is about `AccessHandlePoolVFS`'s *own* methods (real synchronous
+ * OPFS access-handle calls), which stay synchronous and work fine wrapped underneath an async outer VFS
+ * on an Asyncify build - the build choice is driven by this class's needs, not the inner VFS's.
+ */
+import { FacadeVFS } from "@journeyapps/wa-sqlite/src/FacadeVFS.js";
+import { AccessHandlePoolVFS } from "@journeyapps/wa-sqlite/src/examples/AccessHandlePoolVFS.js";
+import * as VFS from "@journeyapps/wa-sqlite/src/VFS.js";
+import { LOGICAL_BLOCK_SIZE, PHYSICAL_BLOCK_SIZE, PageCorruptedError, decryptBlock, encryptBlock, importAesGcmKey, } from "./localIndexBlockCipher.js";
+export { PageCorruptedError } from "./localIndexBlockCipher.js";
+export class EncryptingVFS extends FacadeVFS {
+    constructor(name, module, inner) {
+        super(name, module);
+        _EncryptingVFS_instances.add(this);
+        _EncryptingVFS_inner.set(this, void 0);
+        _EncryptingVFS_key.set(this, void 0);
+        /** `jOpen`'s `filename` is stable across the life of a fileId; `fileId` itself is only valid for one
+         * open handle, never persisted - this map lets `jRead`/`jWrite` recover the stable filename an AAD
+         * needs to bind to, from the ephemeral fileId SQLite actually passes them. */
+        _EncryptingVFS_filenamesByFileId.set(this, new Map());
+        __classPrivateFieldSet(this, _EncryptingVFS_inner, inner, "f");
+    }
+    /** `rawKey` MUST be exactly 32 bytes (AES-256) - see `localIndexKey.ts`'s `deriveLocalIndexKey()`,
+     * the only intended source of this value. */
+    static async create(name, module, rawKey) {
+        const inner = await AccessHandlePoolVFS.create(name, module);
+        const vfs = new EncryptingVFS(name, module, inner);
+        __classPrivateFieldSet(vfs, _EncryptingVFS_key, await importAesGcmKey(rawKey), "f");
+        return vfs;
+    }
+    /**
+     * Releases every pooled OPFS sync access handle `AccessHandlePoolVFS` opened and holds open for its
+     * entire lifetime (not per SQLite-file-open/close - `jOpen`/`jClose` above only associate/disassociate
+     * a SQLite fileId with an already-open handle, they never open or close the handles themselves). MUST
+     * be called before creating another VFS instance against the same OPFS pool `name` - confirmed by
+     * direct reproduction: skipping this and calling `create()` again with the same `name` throws
+     * "Access Handles cannot be created if there is another open Access Handle," since the previous
+     * instance's handles are still live. `localIndexWorker.ts` calls this alongside `sqlite3.close(db)`
+     * (which closes the SQLite *connection*, a separate, shorter-lived thing from the VFS itself) whenever
+     * it tears down a mailbox's connection - on `destroy()` and in `selfTest()`'s own close/reopen check.
+     */
+    close() {
+        return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").close();
+    }
+    // Every method below except jRead/jWrite is a pure passthrough to the inner (real storage) VFS -
+    // this class's only job is to sit in the read/write path.
+    jOpen(filename, pFile, flags, pOutFlags) {
+        const result = __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jOpen(filename, pFile, flags, pOutFlags);
+        __classPrivateFieldGet(this, _EncryptingVFS_filenamesByFileId, "f").set(pFile, filename ?? `(anon:${pFile})`);
+        return result;
+    }
+    jClose(pFile) {
+        __classPrivateFieldGet(this, _EncryptingVFS_filenamesByFileId, "f").delete(pFile);
+        return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jClose(pFile);
+    }
+    jDelete(filename, syncDir) {
+        return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jDelete(filename, syncDir);
+    }
+    jAccess(filename, flags, pResOut) {
+        return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jAccess(filename, flags, pResOut);
+    }
+    jFullPathname(filename, zOut) {
+        return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jFullPathname(filename, zOut);
+    }
+    jSync(pFile, flags) {
+        return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jSync(pFile, flags);
+    }
+    jSectorSize(pFile) {
+        return LOGICAL_BLOCK_SIZE;
+    }
+    jDeviceCharacteristics(pFile) {
+        return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jDeviceCharacteristics(pFile);
+    }
+    /** Logical file size = physical size scaled back down to the logical block size - the inner VFS's
+     * own `jFileSize` reports the *physical* (post-remap) byte count, which is always an exact multiple
+     * of `PHYSICAL_BLOCK_SIZE` since every write here always fills whole physical blocks. */
+    async jFileSize(pFile, pSize64) {
+        const buf = new DataView(new ArrayBuffer(8));
+        const rc = await __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jFileSize(pFile, buf);
+        if (rc !== VFS.SQLITE_OK)
+            return rc;
+        const physicalSize = Number(buf.getBigInt64(0, true));
+        const logicalSize = Math.floor(physicalSize / PHYSICAL_BLOCK_SIZE) * LOGICAL_BLOCK_SIZE;
+        pSize64.setBigInt64(0, BigInt(logicalSize), true);
+        return VFS.SQLITE_OK;
+    }
+    /** `iSize` is a logical byte size - truncates to the smallest whole number of *physical* blocks that
+     * still covers it, so a partially-truncated trailing block is never left half-written. */
+    async jTruncate(pFile, iSize) {
+        const blocks = Math.ceil(iSize / LOGICAL_BLOCK_SIZE);
+        return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jTruncate(pFile, blocks * PHYSICAL_BLOCK_SIZE);
+    }
+    async jRead(pFile, pData, iOffset) {
+        const filename = __classPrivateFieldGet(this, _EncryptingVFS_filenamesByFileId, "f").get(pFile) ?? `(unknown:${pFile})`;
+        const startBlock = Math.floor(iOffset / LOGICAL_BLOCK_SIZE);
+        const endBlock = Math.floor((iOffset + pData.length - 1) / LOGICAL_BLOCK_SIZE);
+        let anyAbsent = false;
+        for (let block = startBlock; block <= endBlock; block++) {
+            const { plaintext, absent } = await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_readBlock).call(this, pFile, filename, block);
+            const blockStart = block * LOGICAL_BLOCK_SIZE;
+            const copyStart = Math.max(iOffset, blockStart);
+            const copyEnd = Math.min(iOffset + pData.length, blockStart + LOGICAL_BLOCK_SIZE);
+            pData.set(plaintext.subarray(copyStart - blockStart, copyEnd - blockStart), copyStart - iOffset);
+            // SQLITE_IOERR_SHORT_READ is how SQLite distinguishes "nothing here yet" from "here is real
+            // (possibly zero-filled) data," e.g. when probing whether a file exists at all - see
+            // #readBlock's own doc comment on why this is tracked explicitly, not inferred from content.
+            if (absent) {
+                anyAbsent = true;
+            }
+        }
+        return anyAbsent ? VFS.SQLITE_IOERR_SHORT_READ : VFS.SQLITE_OK;
+    }
+    async jWrite(pFile, pData, iOffset) {
+        const filename = __classPrivateFieldGet(this, _EncryptingVFS_filenamesByFileId, "f").get(pFile) ?? `(unknown:${pFile})`;
+        const startBlock = Math.floor(iOffset / LOGICAL_BLOCK_SIZE);
+        const endBlock = Math.floor((iOffset + pData.length - 1) / LOGICAL_BLOCK_SIZE);
+        for (let block = startBlock; block <= endBlock; block++) {
+            const blockStart = block * LOGICAL_BLOCK_SIZE;
+            const writeStart = Math.max(iOffset, blockStart);
+            const writeEnd = Math.min(iOffset + pData.length, blockStart + LOGICAL_BLOCK_SIZE);
+            // Whole-block write (the common case once SQLite's page size is fixed): no need to read the
+            // old block first. Anything narrower (a sub-page write, or this block only partially
+            // overlaps the requested range) needs the existing content as a base - a real
+            // read-modify-write - since the physical block is re-encrypted as a single AEAD unit.
+            const plaintext = writeStart === blockStart && writeEnd === blockStart + LOGICAL_BLOCK_SIZE
+                ? pData.subarray(writeStart - iOffset, writeEnd - iOffset)
+                : await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_readBlock).call(this, pFile, filename, block).then(({ plaintext: existing }) => {
+                    const merged = existing.slice();
+                    merged.set(pData.subarray(writeStart - iOffset, writeEnd - iOffset), writeStart - blockStart);
+                    return merged;
+                });
+            const rc = await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_writeBlock).call(this, pFile, filename, block, plaintext);
+            if (rc !== VFS.SQLITE_OK)
+                return rc;
+        }
+        return VFS.SQLITE_OK;
+    }
+}
+_EncryptingVFS_inner = new WeakMap(), _EncryptingVFS_key = new WeakMap(), _EncryptingVFS_filenamesByFileId = new WeakMap(), _EncryptingVFS_instances = new WeakSet(), _EncryptingVFS_readBlock = 
+/**
+ * Reads one physical block and decrypts it. `absent: true` means nothing has ever been written at
+ * this block (the inner VFS's own read came back short) - `plaintext` is a zero-filled logical block
+ * in that case, matching what SQLite expects for a region it has never written, and it is
+ * deliberately never handed to `crypto.subtle.decrypt()` at all (there aren't enough physical bytes
+ * present to contain a real nonce+tag).
+ *
+ * `absent` is determined *only* from the inner VFS's own return code, never inferred from whether the
+ * decrypted plaintext happens to be all-zero - a real, fully-written SQLite page is routinely
+ * all-zero (an unused/freelist page, or a page beyond a freshly created database's real content), so
+ * that content shape means nothing about whether the block is actually present.
+ */
+async function _EncryptingVFS_readBlock(pFile, filename, blockIndex) {
+    const physical = new Uint8Array(PHYSICAL_BLOCK_SIZE);
+    const rc = await __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jRead(pFile, physical, blockIndex * PHYSICAL_BLOCK_SIZE);
+    if (rc === VFS.SQLITE_IOERR_SHORT_READ) {
+        // #writeBlock() never writes fewer than PHYSICAL_BLOCK_SIZE bytes at a time, so a short read
+        // here only ever means "this block was never written," not "partially written."
+        return { plaintext: new Uint8Array(LOGICAL_BLOCK_SIZE), absent: true };
+    }
+    if (rc !== VFS.SQLITE_OK) {
+        throw new PageCorruptedError(filename, blockIndex, new Error(`inner VFS read failed: rc=${rc}`));
+    }
+    const plaintext = await decryptBlock(__classPrivateFieldGet(this, _EncryptingVFS_key, "f"), filename, blockIndex, physical);
+    return { plaintext, absent: false };
+}, _EncryptingVFS_writeBlock = async function _EncryptingVFS_writeBlock(pFile, filename, blockIndex, plaintext) {
+    const physical = await encryptBlock(__classPrivateFieldGet(this, _EncryptingVFS_key, "f"), filename, blockIndex, plaintext);
+    return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jWrite(pFile, physical, blockIndex * PHYSICAL_BLOCK_SIZE);
+};

package/dist/apps/shared/search/localIndexWorker.js

@@ -0,0 +1,341 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The Tier 2 local search index's Worker entry point (`specs/search.md` §13) - runs a WASM SQLite build
+ * (`@journeyapps/wa-sqlite`) over `EncryptingVFS` (`localIndexVFS.ts`), an OPFS-backed, AES-256-GCM
+ * page-encrypting VFS. Must live in a Worker: OPFS synchronous access handles (what the inner
+ * `AccessHandlePoolVFS` - the "SAH Pool VFS" the spec names - uses) are only available off the UI
+ * thread, which also satisfies the spec's "indexing MUST NOT run on the UI thread" requirement for free.
+ *
+ * Boots the **Asyncify** build (`dist/wa-sqlite-async.mjs`), not the plain synchronous one - required
+ * because `EncryptingVFS`'s `jRead`/`jWrite` are genuinely async (WebCrypto has no synchronous form) -
+ * see that file's own doc comment for why this doesn't conflict with `AccessHandlePoolVFS` itself being
+ * synchronous underneath it.
+ *
+ * One SQLite connection per mailbox, opened on `init` and kept for the Worker's lifetime (or until
+ * `destroy`). `entity_uid` is this module's identifier for a message (the only entity type Tier 2 covers
+ * today - see the doc comment on `searchTier3.ts`'s identical scope decision, which this mirrors).
+ *
+ * Real index/search/lifecycle RPC methods are all implemented below; `selfTest` stays alongside them as
+ * an internal diagnostic (proves the encrypted round trip end to end: write through `EncryptingVFS`,
+ * close the connection, reopen, read back) rather than being removed once the real surface existed.
+ */
+import SQLiteESMFactory from "@journeyapps/wa-sqlite/dist/wa-sqlite-async.mjs";
+import * as SQLite from "@journeyapps/wa-sqlite";
+import { EncryptingVFS } from "./localIndexVFS.js";
+import { BM25_WEIGHTS_SQL, CREATE_SCHEMA_SQL, SCHEMA_VERSION, UPSERT_ENTITY_SQL, buildMatchExpression, buildSearchPredicates, entityBindValues, } from "./localIndexSchema.js";
+/** Keyed by `mailboxUid` - a Worker instance is per-tab, not per-mailbox, so this stays a map even
+ * though only one mailbox is ever unlocked in this app's UI at a time today. */
+const connections = new Map();
+/** The OPFS directory name (and `EncryptingVFS` name) a mailbox's index lives under - scoped per
+ * mailbox so two mailboxes' indexes never collide and `destroy(mailboxUid)` (added in the next pass) can
+ * remove exactly one without touching the others. */
+function poolNameFor(mailboxUid) {
+    return `rapidmx-localsearch-${mailboxUid}`;
+}
+async function openConnection({ mailboxUid, indexKey }) {
+    const module = await SQLiteESMFactory();
+    const sqlite3 = SQLite.Factory(module);
+    const vfs = await EncryptingVFS.create(poolNameFor(mailboxUid), module, indexKey);
+    sqlite3.vfs_register(vfs, true);
+    const db = await sqlite3.open_v2("index.db");
+    // No WAL, no rollback journal - see localIndexVFS.ts's own doc comment on why this index's lack of
+    // a durability requirement makes that an acceptable, deliberate simplification here.
+    await sqlite3.exec(db, "PRAGMA journal_mode=OFF; PRAGMA page_size=4096;");
+    await sqlite3.exec(db, CREATE_SCHEMA_SQL);
+    const connection = { sqlite3, db, vfs };
+    const storedVersion = await readMeta(connection, "schema_version");
+    if (storedVersion !== String(SCHEMA_VERSION)) {
+        // §11 "Invalidation... discarded and rebuilt... on schema version change" - drop every table's
+        // rows (the DDL itself is `CREATE ... IF NOT EXISTS`, already current) and start fresh, rather
+        // than attempting to migrate content built under an incompatible schema.
+        await sqlite3.exec(connection.db, "DELETE FROM entities; DELETE FROM entities_fts;");
+        await writeMeta(connection, "schema_version", String(SCHEMA_VERSION));
+    }
+    return connection;
+}
+async function readMeta(connection, key) {
+    let value;
+    for await (const stmt of connection.sqlite3.statements(connection.db, "SELECT value FROM meta WHERE key = ?")) {
+        connection.sqlite3.bind_collection(stmt, [key]);
+        if ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+            value = connection.sqlite3.column(stmt, 0);
+        }
+    }
+    return value;
+}
+async function writeMeta(connection, key, value) {
+    for await (const stmt of connection.sqlite3.statements(connection.db, "INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)")) {
+        connection.sqlite3.bind_collection(stmt, [key, value]);
+        await connection.sqlite3.step(stmt);
+    }
+}
+async function init(params) {
+    if (connections.has(params.mailboxUid)) {
+        return;
+    }
+    connections.set(params.mailboxUid, await openConnection(params));
+}
+function requireConnection(mailboxUid) {
+    const connection = connections.get(mailboxUid);
+    if (!connection) {
+        throw new Error(`localIndexWorker: init() was never called for mailbox ${mailboxUid}`);
+    }
+    return connection;
+}
+/** Tears down a mailbox's connection completely: the SQLite connection itself (`sqlite3.close(db)`) AND
+ * the underlying `EncryptingVFS`/`AccessHandlePoolVFS` instance (`vfs.close()`) - two separate lifecycles
+ * (see `EncryptingVFS.close()`'s own doc comment on why skipping the second one breaks re-`init()`ing the
+ * same mailbox). Removes the entry from `connections` either way. */
+async function closeConnection(mailboxUid) {
+    const connection = connections.get(mailboxUid);
+    if (!connection) {
+        return;
+    }
+    connections.delete(mailboxUid);
+    await connection.sqlite3.close(connection.db);
+    await connection.vfs.close();
+}
+async function sumBytes(connection) {
+    let total = 0;
+    for await (const stmt of connection.sqlite3.statements(connection.db, "SELECT COALESCE(SUM(byte_size), 0) FROM entities")) {
+        if ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+            total = connection.sqlite3.column(stmt, 0);
+        }
+    }
+    return total;
+}
+async function oldestDateForSort(connection) {
+    let oldest;
+    for await (const stmt of connection.sqlite3.statements(connection.db, "SELECT MIN(date_for_sort) FROM entities")) {
+        if ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+            oldest = connection.sqlite3.column(stmt, 0) ?? undefined;
+        }
+    }
+    return oldest;
+}
+async function entityCount(connection) {
+    let count = 0;
+    for await (const stmt of connection.sqlite3.statements(connection.db, "SELECT COUNT(*) FROM entities")) {
+        if ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+            count = connection.sqlite3.column(stmt, 0);
+        }
+    }
+    return count;
+}
+/** Deletes the single oldest entity (by `date_for_sort`) and returns whether one existed to delete -
+ * `entities_ad` (see `localIndexSchema.ts`) keeps `entities_fts` in sync automatically. One row per call
+ * (not a batch `DELETE ... LIMIT`, which SQLite's default build doesn't compile in) so
+ * `#applyEviction()`'s own loop can re-check the byte total after each deletion rather than
+ * over-evicting. */
+async function deleteOldestEntity(connection) {
+    let deleted = false;
+    for await (const stmt of connection.sqlite3.statements(connection.db, "DELETE FROM entities WHERE rowid = (SELECT rowid FROM entities ORDER BY date_for_sort ASC LIMIT 1)")) {
+        await connection.sqlite3.step(stmt);
+        deleted = connection.sqlite3.changes(connection.db) > 0;
+    }
+    return deleted;
+}
+/** Oldest-first eviction against the configured byte budget (spec §11 "Eviction... MUST NOT block
+ * search" - this runs to completion as part of `indexEntities()`, which is already off the UI thread by
+ * virtue of running in this Worker, so there's no separate scheduling concern here). A no-op when no
+ * budget has been configured yet (`setWindow()` was never called) - nothing to enforce. */
+async function applyEviction(connection) {
+    const byteBudgetRaw = await readMeta(connection, "byte_budget");
+    const byteBudget = byteBudgetRaw ? Number(byteBudgetRaw) : undefined;
+    if (!byteBudget) {
+        return;
+    }
+    for (;;) {
+        const total = await sumBytes(connection);
+        if (total <= byteBudget) {
+            return;
+        }
+        const deletedOne = await deleteOldestEntity(connection);
+        if (!deletedOne) {
+            return;
+        }
+    }
+}
+async function indexEntities({ mailboxUid, entities }) {
+    const connection = requireConnection(mailboxUid);
+    for (const entity of entities) {
+        for await (const stmt of connection.sqlite3.statements(connection.db, UPSERT_ENTITY_SQL)) {
+            connection.sqlite3.bind_collection(stmt, entityBindValues(entity));
+            await connection.sqlite3.step(stmt);
+        }
+    }
+    await applyEviction(connection);
+}
+async function removeEntity({ mailboxUid, entityUid }) {
+    const connection = requireConnection(mailboxUid);
+    for await (const stmt of connection.sqlite3.statements(connection.db, "DELETE FROM entities WHERE entity_uid = ?")) {
+        connection.sqlite3.bind_collection(stmt, [entityUid]);
+        await connection.sqlite3.step(stmt);
+    }
+}
+async function search({ mailboxUid, parsed, limit, offset = 0 }) {
+    const connection = requireConnection(mailboxUid);
+    const { where, params } = buildSearchPredicates(parsed, mailboxUid);
+    const matchExpr = buildMatchExpression(parsed);
+    const hits = [];
+    // A malformed MATCH string is a real, reachable case (FTS5's query syntax rejects some inputs
+    // `queryGrammar.ts` otherwise leaves untouched for the *server's* more lenient `websearch_to_tsquery`
+    // to handle) - fails soft to "this tier found nothing," matching how every other tier already
+    // degrades on its own per-candidate/per-provider failures, rather than breaking the whole search.
+    try {
+        // Fetches one extra row beyond `limit` so `hasMore` below can be determined without a second,
+        // separate COUNT(*) query - trimmed back off before returning.
+        const fetchLimit = limit + 1;
+        const sql = matchExpr
+            ? `SELECT e.entity_uid, bm25(entities_fts, ${BM25_WEIGHTS_SQL}) AS rank,
+                      snippet(entities_fts, 2, '', '', '…', 24) AS snip
+               FROM entities_fts f JOIN entities e ON e.rowid = f.rowid
+               WHERE entities_fts MATCH ? AND ${where}
+               ORDER BY rank LIMIT ? OFFSET ?`
+            : `SELECT e.entity_uid, 0 AS rank, NULL AS snip FROM entities e WHERE ${where}
+               ORDER BY e.date_for_sort DESC LIMIT ? OFFSET ?`;
+        const bindings = matchExpr ? [matchExpr, ...params, fetchLimit, offset] : [...params, fetchLimit, offset];
+        for await (const stmt of connection.sqlite3.statements(connection.db, sql)) {
+            connection.sqlite3.bind_collection(stmt, bindings);
+            while ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+                hits.push({
+                    entityUid: connection.sqlite3.column(stmt, 0),
+                    score: connection.sqlite3.column(stmt, 1),
+                    snippet: connection.sqlite3.column(stmt, 2) ?? undefined,
+                });
+            }
+        }
+    }
+    catch {
+        return { hits: [], hasMore: false };
+    }
+    const hasMore = hits.length > limit;
+    if (hasMore) {
+        hits.length = limit;
+    }
+    return { hits, hasMore };
+}
+async function coverage(mailboxUid) {
+    const connection = requireConnection(mailboxUid);
+    return {
+        indexedFrom: await oldestDateForSort(connection),
+        indexedCount: await entityCount(connection),
+        building: (await readMeta(connection, "building")) === "1",
+    };
+}
+async function setWindow({ mailboxUid, timeFloorMonths, byteBudgetBytes }) {
+    const connection = requireConnection(mailboxUid);
+    await writeMeta(connection, "time_floor_months", String(timeFloorMonths));
+    await writeMeta(connection, "byte_budget", String(byteBudgetBytes));
+    // A lowered budget must shrink the window immediately, not just gate future inserts (spec §11 "the
+    // client MUST reduce the window rather than fail writes when the budget is reached").
+    await applyEviction(connection);
+}
+async function setBuilding(mailboxUid, building) {
+    const connection = requireConnection(mailboxUid);
+    await writeMeta(connection, "building", building ? "1" : "0");
+}
+/** Closes the connection (if open) and deletes the mailbox's entire OPFS directory - the spec's "MUST be
+ * destroyed on the same events that destroy private keys" (§11), and also the discard side of
+ * "discarded and rebuilt" on corruption/schema-version invalidation. Goes around SQLite/the VFS entirely
+ * for the deletion itself (there's no VFS-level "delete everything" primitive) - safe only because the
+ * connection is already closed at this point, so nothing else holds these files open. */
+async function destroy(mailboxUid) {
+    await closeConnection(mailboxUid);
+    const root = await navigator.storage.getDirectory();
+    await root.removeEntry(poolNameFor(mailboxUid), { recursive: true }).catch(() => undefined);
+}
+/**
+ * Proves the full encrypted round trip, not just a single write-then-read within one open connection
+ * (which could pass even if encryption/decryption were silently no-ops): writes a row, **closes the
+ * SQLite connection and drops it from `connections`**, then re-`init()`s the same mailbox from scratch -
+ * a real close/reopen through `EncryptingVFS`, `AccessHandlePoolVFS`, and OPFS, not merely reading back
+ * from an in-memory cache - and confirms the row (and a `bm25()`-ranked `MATCH` query against it) both
+ * still work after that reopen.
+ */
+async function selfTest(params) {
+    await init(params);
+    const before = requireConnection(params.mailboxUid);
+    await before.sqlite3.exec(before.db, "DELETE FROM entities");
+    for await (const stmt of before.sqlite3.statements(before.db, "INSERT INTO entities (entity_type, entity_uid, mailbox_uid, date_for_sort, subject, body) VALUES (?, ?, ?, ?, ?, ?)")) {
+        before.sqlite3.bind_collection(stmt, [
+            "message",
+            "spike-1",
+            params.mailboxUid,
+            new Date().toISOString(),
+            "Quarterly budget review",
+            "This round-trips through EncryptingVFS: written before a close, read back after a reopen.",
+        ]);
+        await before.sqlite3.step(stmt);
+    }
+    await closeConnection(params.mailboxUid);
+    await init(params);
+    const after = requireConnection(params.mailboxUid);
+    const matchedAfterReopen = [];
+    for await (const stmt of after.sqlite3.statements(after.db, `SELECT e.entity_uid FROM entities_fts f JOIN entities e ON e.rowid = f.rowid
+         WHERE entities_fts MATCH 'budget' ORDER BY bm25(entities_fts, ${BM25_WEIGHTS_SQL})`)) {
+        while ((await after.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+            matchedAfterReopen.push(after.sqlite3.column(stmt, 0));
+        }
+    }
+    return { matchedAfterReopen };
+}
+self.addEventListener("message", (event) => {
+    const { id, method, params } = event.data;
+    void (async () => {
+        try {
+            let result;
+            switch (method) {
+                case "ping":
+                    result = "pong";
+                    break;
+                case "init":
+                    await init(params);
+                    result = undefined;
+                    break;
+                case "indexEntities":
+                    await indexEntities(params);
+                    result = undefined;
+                    break;
+                case "removeEntity":
+                    await removeEntity(params);
+                    result = undefined;
+                    break;
+                case "search":
+                    result = await search(params);
+                    break;
+                case "coverage":
+                    result = await coverage(params);
+                    break;
+                case "setWindow":
+                    await setWindow(params);
+                    result = undefined;
+                    break;
+                case "setBuilding": {
+                    const { mailboxUid, building } = params;
+                    await setBuilding(mailboxUid, building);
+                    result = undefined;
+                    break;
+                }
+                case "destroy":
+                    await destroy(params);
+                    result = undefined;
+                    break;
+                case "selfTest":
+                    result = await selfTest(params);
+                    break;
+                default:
+                    throw new Error(`Unknown localIndexWorker method: ${method}`);
+            }
+            const response = { id, ok: true, result };
+            self.postMessage(response);
+        }
+        catch (err) {
+            const response = { id, ok: false, error: err instanceof Error ? err.message : String(err) };
+            self.postMessage(response);
+        }
+    })();
+});