@rapidmx/web-client 0.4.0 → 0.5.0

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

@@ -14,58 +14,234 @@
  * see that file's own doc comment for why this doesn't conflict with `AccessHandlePoolVFS` itself being
  * synchronous underneath it.
  *
+ * **Every operation on a mailbox's connection runs through that mailbox's own serial queue**
+ * (`runExclusive()`). An Asyncify module is not re-entrant: starting a second `sqlite3.*` call while
+ * another is suspended inside an async VFS method corrupts the unwinding state. `postMessage` requests
+ * arrive concurrently (e.g. `searchTier2.ts` issues `search` and `coverage` together, while a build pass
+ * is mid-`indexEntities`), so without the queue they interleaved inside the same module. It also closes
+ * an `init` race where two concurrent `init`s both saw no connection and created two VFS instances over
+ * one OPFS pool. Each mailbox gets its own module instance, so separate mailboxes don't need to share
+ * one queue.
+ *
  * 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).
+ * `destroy`). A Web Lock per mailbox (`navigator.locks`) ensures only one tab holds a given index open;
+ * a second tab's `init` fails with a logged reason and Tier 2 simply contributes nothing there.
  *
- * 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.
+ * `entity_uid` is this module's identifier for a message (the only entity type Tier 2 covers today).
  */
 import SQLiteESMFactory from "@journeyapps/wa-sqlite/dist/wa-sqlite-async.mjs";
 import * as SQLite from "@journeyapps/wa-sqlite";
 import { EncryptingVFS } from "./localIndexVFS.js";
+import { listLocalIndexMailboxUids, poolNameFor, removeLocalIndexDirectory } from "./localIndexStorage.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. */
+/** Keyed by `mailboxUid` - a Worker instance is per-tab, not per-mailbox. */
 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}`;
+/** Per-mailbox promise chains - see this module's doc comment. Each value never rejects. */
+const queues = new Map();
+/** Runs `task` after every previously queued task for `mailboxUid` has settled. Exported for tests. */
+export function runExclusive(mailboxUid, task) {
+    const previous = queues.get(mailboxUid) ?? Promise.resolve();
+    const result = previous.then(task);
+    const tail = result.then(() => undefined, () => undefined);
+    queues.set(mailboxUid, tail);
+    void tail.then(() => {
+        if (queues.get(mailboxUid) === tail) {
+            queues.delete(mailboxUid);
+        }
+    });
+    return result;
+}
+/** Generation of the most recent `destroy` per mailbox, and of the most recent `destroyAll`. */
+const destroyedGenerations = new Map();
+let destroyedAllGeneration = 0;
+/** Rejects a build-pass call issued before its mailbox's index was last destroyed. */
+export class StaleGenerationError extends Error {
+    constructor(mailboxUid) {
+        super(`Local search index for mailbox ${mailboxUid} was destroyed after this build started.`);
+        this.name = "StaleGenerationError";
+    }
+}
+function assertCurrentGeneration(mailboxUid, generation) {
+    if (generation === undefined) {
+        return;
+    }
+    if (generation < Math.max(destroyedGenerations.get(mailboxUid) ?? 0, destroyedAllGeneration)) {
+        throw new StaleGenerationError(mailboxUid);
+    }
+}
+function recordDestroyGeneration(mailboxUid, generation) {
+    if (generation === undefined) {
+        return;
+    }
+    if (mailboxUid === undefined) {
+        destroyedAllGeneration = Math.max(destroyedAllGeneration, generation);
+    }
+    else {
+        destroyedGenerations.set(mailboxUid, Math.max(destroyedGenerations.get(mailboxUid) ?? 0, generation));
+    }
+}
+/** Thrown by `init` when another tab already holds this mailbox's index open. */
+export class LocalIndexBusyError extends Error {
+    constructor(mailboxUid) {
+        super(`Local search index for mailbox ${mailboxUid} is already open in another tab.`);
+        this.name = "LocalIndexBusyError";
+    }
+}
+/**
+ * Takes an exclusive, non-waiting Web Lock for one mailbox's index and holds it until the returned release
+ * function is called. `undefined` when the Web Locks API isn't available - `AccessHandlePoolVFS`'s own
+ * exclusive sync access handles still stop a second tab from opening the pool, just with a less specific
+ * error.
+ */
+async function acquireIndexLock(mailboxUid) {
+    const locks = typeof navigator === "undefined" ? undefined : navigator.locks;
+    if (!locks) {
+        return undefined;
+    }
+    return new Promise((resolve, reject) => {
+        locks
+            .request(`${poolNameFor(mailboxUid)}:lock`, { ifAvailable: true }, (lock) => {
+            if (!lock) {
+                reject(new LocalIndexBusyError(mailboxUid));
+                return undefined;
+            }
+            return new Promise((release) => resolve(release));
+        })
+            .catch(reject);
+    });
 }
-async function openConnection({ mailboxUid, indexKey }) {
+/** Wraps a failure to even open the database because its pages don't decrypt/authenticate. */
+class LocalIndexCorruptedError extends Error {
+    constructor(cause) {
+        super(`Local search index is corrupted: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "LocalIndexCorruptedError";
+    }
+}
+/** SQLite's own exact messages for `SQLITE_CORRUPT`/`SQLITE_NOTADB`, for an error that lost its code. Anchored
+ * on both ends: an FTS5 error echoes the user's query text back (e.g. `no such column: malformed`), and a
+ * loose substring match on that used to wipe the whole index. */
+const CORRUPTION_MESSAGE = /^(database disk image is malformed|file is not a database)$/i;
+/** A real corruption signal (discard and rebuild) versus an ordinary error (e.g. a malformed MATCH). */
+function isCorruptionError(err, connection) {
+    if (err instanceof LocalIndexCorruptedError || connection?.vfs.corruptionDetected) {
+        return true;
+    }
+    const code = err?.code;
+    if (code === SQLite.SQLITE_CORRUPT || code === SQLite.SQLITE_NOTADB) {
+        return true;
+    }
+    return err instanceof Error && CORRUPTION_MESSAGE.test(err.message);
+}
+async function openRawConnection(params) {
+    const { mailboxUid, indexKey } = params;
     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));
+    let db;
+    try {
+        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;");
     }
-    return connection;
+    catch (err) {
+        // Opening reads the header page, so a wrong key or a corrupted first block fails right here.
+        if (db !== undefined) {
+            await sqlite3.close(db).catch(() => undefined);
+        }
+        await vfs.close();
+        throw vfs.corruptionDetected ? new LocalIndexCorruptedError(err) : err;
+    }
+    return { sqlite3, db, vfs, params };
 }
-async function readMeta(connection, key) {
+async function closeRawConnection(connection) {
+    try {
+        await connection.sqlite3.close(connection.db);
+    }
+    finally {
+        await connection.vfs.close();
+    }
+}
+async function queryValue(connection, sql, bindings = []) {
     let value;
-    for await (const stmt of connection.sqlite3.statements(connection.db, "SELECT value FROM meta WHERE key = ?")) {
-        connection.sqlite3.bind_collection(stmt, [key]);
+    for await (const stmt of connection.sqlite3.statements(connection.db, sql)) {
+        if (bindings.length > 0) {
+            connection.sqlite3.bind_collection(stmt, bindings);
+        }
         if ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
-            value = connection.sqlite3.column(stmt, 0);
+            value = connection.sqlite3.column(stmt, 0) ?? undefined;
         }
     }
     return value;
 }
+/** Creates the schema on a brand-new database, or validates an existing one. Resolves `false` when an
+ * existing database was built under a different `SCHEMA_VERSION` and must be discarded (§11
+ * "Invalidation... on schema version change"). */
+async function initializeSchema(connection) {
+    const hasMeta = await queryValue(connection, "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'meta'");
+    if (hasMeta) {
+        return (await readMeta(connection, "schema_version")) === String(SCHEMA_VERSION);
+    }
+    // Both pragmas only take effect before the first table exists, which is why a schema-version bump
+    // recreates the whole file rather than just clearing rows.
+    await connection.sqlite3.exec(connection.db, "PRAGMA page_size=4096; PRAGMA auto_vacuum=INCREMENTAL;");
+    await connection.sqlite3.exec(connection.db, CREATE_SCHEMA_SQL);
+    await writeMeta(connection, "schema_version", String(SCHEMA_VERSION));
+    return true;
+}
+/** Opens a just-discarded (empty) index and creates its schema - closing the connection again if the schema
+ * step fails, so its OPFS access handles aren't leaked for the rest of the Worker's life. */
+async function openFreshConnection(params) {
+    const connection = await openRawConnection(params);
+    try {
+        await initializeSchema(connection);
+    }
+    catch (err) {
+        await closeRawConnection(connection).catch(() => undefined);
+        throw err;
+    }
+    return connection;
+}
+async function openConnection(params) {
+    const releaseLock = await acquireIndexLock(params.mailboxUid);
+    try {
+        let connection;
+        let usable;
+        try {
+            connection = await openRawConnection(params);
+            usable = await initializeSchema(connection);
+        }
+        catch (err) {
+            if (connection) {
+                await closeRawConnection(connection).catch(() => undefined);
+            }
+            if (!isCorruptionError(err, connection)) {
+                throw err;
+            }
+            connection = undefined;
+            usable = false;
+        }
+        if (!usable || !connection) {
+            // Corrupted (GCM auth failure, "malformed"/"not a database") or an old schema version: discard
+            // the whole database and start empty - the builder repopulates it (§11 "discarded and rebuilt").
+            if (connection) {
+                await closeRawConnection(connection).catch(() => undefined);
+            }
+            await removeLocalIndexDirectory(params.mailboxUid);
+            connection = await openFreshConnection(params);
+        }
+        connection.releaseLock = releaseLock;
+        return connection;
+    }
+    catch (err) {
+        releaseLock?.();
+        throw err;
+    }
+}
+async function readMeta(connection, key) {
+    return queryValue(connection, "SELECT value FROM meta WHERE key = ?", [key]);
+}
 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]);
@@ -73,10 +249,30 @@ async function writeMeta(connection, key, value) {
     }
 }
 async function init(params) {
+    assertCurrentGeneration(params.mailboxUid, params.generation);
     if (connections.has(params.mailboxUid)) {
         return;
     }
-    connections.set(params.mailboxUid, await openConnection(params));
+    try {
+        const connection = await openConnection(params);
+        try {
+            // A completion (or an in-progress flag) persisted by an earlier session proves nothing about mail
+            // that arrived since - only a pass that finishes while this connection is open may narrow Tier 3.
+            await clearBuildState(connection);
+        }
+        catch (err) {
+            await closeRawConnection(connection).catch(() => undefined);
+            connection.releaseLock?.();
+            throw err;
+        }
+        connections.set(params.mailboxUid, connection);
+    }
+    catch (err) {
+        // Tier 2 degrades to "contributes nothing" in this tab - say why, once per attempt, rather than
+        // leaving a silently empty local tier.
+        console.warn(`localIndexWorker: local search unavailable for mailbox ${params.mailboxUid}: ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+    }
 }
 function requireConnection(mailboxUid) {
     const connection = connections.get(mailboxUid);
@@ -85,118 +281,225 @@ function requireConnection(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. */
+/** Tears down a mailbox's connection completely: the SQLite connection, the underlying VFS's pooled
+ * access handles (see `EncryptingVFS.close()`), and the cross-tab Web Lock. */
 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);
-        }
+    try {
+        await closeRawConnection(connection);
     }
-    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;
-        }
+    finally {
+        connection.releaseLock?.();
     }
-    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);
+/**
+ * Runs `operation` against a mailbox's open connection. If it fails because the index is corrupted, the
+ * index is destroyed and reopened empty (same key, same lock) so the next build pass repopulates it, and
+ * the original error is rethrown - the caller's own degradation (e.g. `search()` returning no hits) still
+ * applies to this one call.
+ */
+async function withConnection(mailboxUid, operation) {
+    const connection = requireConnection(mailboxUid);
+    try {
+        return await operation(connection);
+    }
+    catch (err) {
+        if (isCorruptionError(err, connection) && connections.get(mailboxUid) === connection) {
+            await resetCorruptedConnection(mailboxUid, connection);
         }
+        throw err;
     }
-    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;
+/** `withConnection()` for a build-pass call - rejected first if the call's generation is stale. */
+async function withCurrentConnection(params, operation) {
+    assertCurrentGeneration(params.mailboxUid, params.generation);
+    return withConnection(params.mailboxUid, operation);
+}
+/** Discards a corrupted index and reopens it empty under the same key and Web Lock. If reopening fails,
+ * the mailbox is left uninitialized (lock released) - the next `init()` tries again from scratch. */
+async function resetCorruptedConnection(mailboxUid, connection) {
+    console.warn(`localIndexWorker: local search index for mailbox ${mailboxUid} is corrupted; discarding and rebuilding.`);
+    connections.delete(mailboxUid);
+    await closeRawConnection(connection).catch(() => undefined);
+    try {
+        await removeLocalIndexDirectory(mailboxUid);
+        const fresh = await openFreshConnection(connection.params);
+        fresh.releaseLock = connection.releaseLock;
+        connections.set(mailboxUid, fresh);
+    }
+    catch {
+        connection.releaseLock?.();
     }
-    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. */
+/** Bytes actually used by live pages - `page_count` minus free pages, times `page_size`. Counts the FTS5
+ * shadow tables and indexes too, unlike summing a per-row estimate. */
+async function usedBytes(connection) {
+    const pageCount = (await queryValue(connection, "PRAGMA page_count")) ?? 0;
+    const freelist = (await queryValue(connection, "PRAGMA freelist_count")) ?? 0;
+    const pageSize = (await queryValue(connection, "PRAGMA page_size")) ?? 4096;
+    return (pageCount - freelist) * pageSize;
+}
+/** Physical database size (what OPFS actually stores) - exported via `coverage()` for diagnostics/tests. */
+async function fileBytes(connection) {
+    const pageCount = (await queryValue(connection, "PRAGMA page_count")) ?? 0;
+    const pageSize = (await queryValue(connection, "PRAGMA page_size")) ?? 4096;
+    return pageCount * pageSize;
+}
+/** Maximum bulk-eviction rounds per call - each round deletes a whole date range sized from the measured
+ * overshoot, so more than a couple only happens when the per-row weights badly underestimate real size. */
+const MAX_EVICTION_ROUNDS = 8;
+/**
+ * Oldest-first eviction against the configured byte budget (spec §11). Measures the real database size,
+ * then deletes a contiguous oldest date range in one statement, sized by walking rows oldest-first with a
+ * running total of their `byte_size` weights scaled to the measured size - rather than the previous
+ * delete-one-row-then-re-SUM loop, which was O(n²). `incremental_vacuum` then returns freed pages to the
+ * filesystem. A no-op when no budget has been configured yet. Resolves whether anything was evicted.
+ */
 async function applyEviction(connection) {
     const byteBudgetRaw = await readMeta(connection, "byte_budget");
     const byteBudget = byteBudgetRaw ? Number(byteBudgetRaw) : undefined;
     if (!byteBudget) {
-        return;
+        return false;
     }
-    for (;;) {
-        const total = await sumBytes(connection);
-        if (total <= byteBudget) {
-            return;
+    // The newest cutoff actually deleted up to; `undefined` while nothing has been evicted.
+    let watermark;
+    for (let round = 0; round < MAX_EVICTION_ROUNDS; round++) {
+        const used = await usedBytes(connection);
+        if (used <= byteBudget) {
+            break;
         }
-        const deletedOne = await deleteOldestEntity(connection);
-        if (!deletedOne) {
-            return;
+        const totalWeight = (await queryValue(connection, "SELECT COALESCE(SUM(byte_size), 0) FROM entities")) ?? 0;
+        if (totalWeight <= 0) {
+            break;
+        }
+        const overshootWeight = ((used - byteBudget) / used) * totalWeight;
+        let running = 0;
+        let cutoffRowid;
+        let cutoffDate;
+        for await (const stmt of connection.sqlite3.statements(connection.db, "SELECT date_for_sort, rowid, byte_size FROM entities ORDER BY date_for_sort ASC, rowid ASC")) {
+            while ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+                cutoffDate = connection.sqlite3.column(stmt, 0);
+                cutoffRowid = connection.sqlite3.column(stmt, 1);
+                running += connection.sqlite3.column(stmt, 2);
+                if (running >= overshootWeight) {
+                    break;
+                }
+            }
+        }
+        if (cutoffDate === undefined || cutoffRowid === undefined) {
+            break;
+        }
+        for await (const stmt of connection.sqlite3.statements(connection.db, "DELETE FROM entities WHERE date_for_sort < ? OR (date_for_sort = ? AND rowid <= ?)")) {
+            connection.sqlite3.bind_collection(stmt, [cutoffDate, cutoffDate, cutoffRowid]);
+            await connection.sqlite3.step(stmt);
+        }
+        // The cutoff row was just read, so this always deleted at least that row.
+        watermark = cutoffDate;
+    }
+    if (watermark !== undefined) {
+        // Rows at exactly `watermark` may be partly evicted (the rowid tiebreaker), so only strictly older
+        // messages are treated as out of the window. Never moves backwards while at budget.
+        const previous = await readMeta(connection, "evicted_before");
+        if (!previous || watermark > previous) {
+            await writeMeta(connection, "evicted_before", watermark);
         }
+        await connection.sqlite3.exec(connection.db, "PRAGMA incremental_vacuum;");
     }
+    return watermark !== undefined;
 }
-async function indexEntities({ mailboxUid, entities }) {
-    const connection = requireConnection(mailboxUid);
+async function indexEntities(connection, entities) {
     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);
+    const budgetReached = await applyEviction(connection);
+    return { budgetReached, ...(await readWindowState(connection)) };
 }
-async function removeEntity({ mailboxUid, entityUid }) {
-    const connection = requireConnection(mailboxUid);
+async function removeEntity(connection, entityUid) {
     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);
+/** Re-points an indexed message at a new folder in place (archive, cancel-scheduled-send). Clears
+ * `entity_version` so the next build pass re-validates the row against the server. */
+async function moveEntity(connection, entityUid, folderUid) {
+    for await (const stmt of connection.sqlite3.statements(connection.db, "UPDATE entities SET folder_uid = ?, entity_version = NULL WHERE entity_uid = ?")) {
+        connection.sqlite3.bind_collection(stmt, [folderUid, entityUid]);
+        await connection.sqlite3.step(stmt);
+    }
+}
+/** `entity_version` for whichever of `entityUids` are already indexed - one batched query per builder page,
+ * so a rebuild can skip re-fetching/decrypting unchanged messages. */
+async function indexedVersions(connection, entityUids) {
+    const versions = {};
+    if (entityUids.length === 0) {
+        return versions;
+    }
+    const placeholders = entityUids.map(() => "?").join(", ");
+    for await (const stmt of connection.sqlite3.statements(connection.db, `SELECT entity_uid, entity_version FROM entities WHERE entity_uid IN (${placeholders})`)) {
+        connection.sqlite3.bind_collection(stmt, entityUids);
+        while ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+            const version = connection.sqlite3.column(stmt, 1);
+            if (version !== null) {
+                versions[connection.sqlite3.column(stmt, 0)] = version;
+            }
+        }
+    }
+    return versions;
+}
+/** Deletes rows a complete build pass didn't see (deleted, or moved out of every mail folder, on any
+ * client) within the pass's own time floor. Resolves how many rows were removed. */
+async function pruneEntities(connection, { keepEntityUids, since, folderUids }) {
+    const keep = new Set(keepEntityUids);
+    const folders = folderUids ? new Set(folderUids) : undefined;
+    const stale = [];
+    for await (const stmt of connection.sqlite3.statements(connection.db, since ? "SELECT entity_uid, folder_uid FROM entities WHERE date_for_sort >= ?" : "SELECT entity_uid, folder_uid FROM entities")) {
+        if (since) {
+            connection.sqlite3.bind_collection(stmt, [since]);
+        }
+        while ((await connection.sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+            const uid = connection.sqlite3.column(stmt, 0);
+            const folderUid = connection.sqlite3.column(stmt, 1);
+            if (!keep.has(uid) && (!folders || folders.has(folderUid))) {
+                stale.push(uid);
+            }
+        }
+    }
+    for (const uid of stale) {
+        await removeEntity(connection, uid);
+    }
+    if (stale.length > 0) {
+        await connection.sqlite3.exec(connection.db, "PRAGMA incremental_vacuum;");
+    }
+    return stale.length;
+}
+async function search(connection, { mailboxUid, parsed, limit, offset = 0 }) {
     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.
+    // A malformed MATCH string is a real, reachable case (FTS5's query syntax rejects some inputs the
+    // server's more lenient parser accepts) - fails soft to "this tier found nothing". Corruption is the
+    // one failure rethrown, so `withConnection()` can discard and rebuild the index.
     try {
-        // Fetches one extra row beyond `limit` so `hasMore` below can be determined without a second,
-        // separate COUNT(*) query - trimmed back off before returning.
+        // Fetches one extra row beyond `limit` so `hasMore` can be determined without a COUNT(*). The
+        // `entity_uid` tiebreaker makes the ordering total, so OFFSET pages never overlap or skip rows
+        // that share a rank/date.
         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 ?`
+               ORDER BY rank, e.entity_uid 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 ?`;
+               ORDER BY e.date_for_sort DESC, e.entity_uid 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);
@@ -209,7 +512,10 @@ async function search({ mailboxUid, parsed, limit, offset = 0 }) {
             }
         }
     }
-    catch {
+    catch (err) {
+        if (isCorruptionError(err, connection)) {
+            throw err;
+        }
         return { hits: [], hasMore: false };
     }
     const hasMore = hits.length > limit;
@@ -218,43 +524,71 @@ async function search({ mailboxUid, parsed, limit, offset = 0 }) {
     }
     return { hits, hasMore };
 }
-async function coverage(mailboxUid) {
-    const connection = requireConnection(mailboxUid);
+async function coverage(connection) {
+    const oldest = await queryValue(connection, "SELECT MIN(date_for_sort) FROM entities");
+    const complete = (await readMeta(connection, "build_complete")) === "1";
+    const coveredFrom = await readMeta(connection, "covered_from");
+    // A complete pass walked every folder back to its time floor, but a folder's last page can reach
+    // further back than another folder's did - so the guaranteed frontier is the later of the two.
+    const indexedFrom = complete && oldest && coveredFrom && coveredFrom > oldest ? coveredFrom : oldest;
+    const coveredUntil = await readMeta(connection, "covered_until");
     return {
-        indexedFrom: await oldestDateForSort(connection),
-        indexedCount: await entityCount(connection),
+        indexedFrom,
+        indexedCount: (await queryValue(connection, "SELECT COUNT(*) FROM entities")) ?? 0,
         building: (await readMeta(connection, "building")) === "1",
+        complete,
+        indexedUntil: complete && coveredUntil ? coveredUntil : undefined,
+        fileBytes: await fileBytes(connection),
     };
 }
-async function setWindow({ mailboxUid, timeFloorMonths, byteBudgetBytes }) {
-    const connection = requireConnection(mailboxUid);
+/** Below this fraction of the budget, the eviction watermark is dropped so older mail can come back in -
+ * the gap between it and 1.0 keeps a pass from evicting and re-fetching the same boundary every time. */
+const WATERMARK_RESET_FRACTION = 0.9;
+async function readWindowState(connection) {
+    return { evictedBefore: (await readMeta(connection, "evicted_before")) || undefined };
+}
+async function setWindow(connection, { timeFloorMonths, byteBudgetBytes }) {
     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);
+    const evicted = await applyEviction(connection);
+    if (!evicted && (!byteBudgetBytes || (await usedBytes(connection)) <= byteBudgetBytes * WATERMARK_RESET_FRACTION)) {
+        await writeMeta(connection, "evicted_before", "");
+    }
+    return readWindowState(connection);
 }
-async function setBuilding(mailboxUid, building) {
-    const connection = requireConnection(mailboxUid);
+async function setBuilding(connection, { building, complete, coveredFrom, coveredUntil }) {
+    const done = !building && !!complete;
     await writeMeta(connection, "building", building ? "1" : "0");
+    // Starting a pass invalidates the previous pass's completeness until this one finishes.
+    await writeMeta(connection, "build_complete", done ? "1" : "0");
+    await writeMeta(connection, "covered_from", done && coveredFrom ? coveredFrom : "");
+    await writeMeta(connection, "covered_until", done && coveredUntil ? coveredUntil : "");
+}
+async function clearBuildState(connection) {
+    await setBuilding(connection, { mailboxUid: connection.params.mailboxUid, building: false, complete: false });
 }
 /** 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. */
+ * destroyed on the same events that destroy private keys" (§11). Rejects if the directory couldn't be
+ * removed (e.g. another tab still has it open), so the caller can report it. */
 async function destroy(mailboxUid) {
     await closeConnection(mailboxUid);
-    const root = await navigator.storage.getDirectory();
-    await root.removeEntry(poolNameFor(mailboxUid), { recursive: true }).catch(() => undefined);
+    await removeLocalIndexDirectory(mailboxUid);
+}
+/** Destroys every local index on this origin, including ones this Worker never opened. Each mailbox's close
+ * and directory removal runs inside that mailbox's own queue, so an `init` already queued can't recreate a
+ * directory after it was removed (a stale build's queued `init` is rejected by its generation instead). */
+async function destroyAll() {
+    const mailboxUids = new Set([...connections.keys(), ...(await listLocalIndexMailboxUids())]);
+    const failed = [];
+    await Promise.all([...mailboxUids].map((mailboxUid) => runExclusive(mailboxUid, () => destroy(mailboxUid)).catch(() => failed.push(mailboxUid))));
+    return { failed: failed.sort() };
 }
 /**
- * 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.
+ * Proves the full encrypted round trip, not just a single write-then-read within one open connection:
+ * writes a row, closes the connection, re-`init()`s the same mailbox from scratch, 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);
@@ -283,59 +617,71 @@ async function selfTest(params) {
     }
     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);
+/** Routes one request to its handler, inside the owning mailbox's serial queue. Exported for tests. */
+export async function handleRequest(method, params) {
+    switch (method) {
+        case "ping":
+            return "pong";
+        case "init": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => init(p));
         }
-        catch (err) {
-            const response = { id, ok: false, error: err instanceof Error ? err.message : String(err) };
-            self.postMessage(response);
+        case "indexEntities": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => withCurrentConnection(p, (c) => indexEntities(c, p.entities)));
+        }
+        case "removeEntity": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => withConnection(p.mailboxUid, (c) => removeEntity(c, p.entityUid)));
+        }
+        case "moveEntity": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => withConnection(p.mailboxUid, (c) => moveEntity(c, p.entityUid, p.folderUid)));
+        }
+        case "indexedVersions": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => withConnection(p.mailboxUid, (c) => indexedVersions(c, p.entityUids)));
+        }
+        case "pruneEntities": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => withCurrentConnection(p, (c) => pruneEntities(c, p)));
+        }
+        case "search": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => withConnection(p.mailboxUid, (c) => search(c, p)));
+        }
+        case "coverage": {
+            const mailboxUid = params;
+            return runExclusive(mailboxUid, () => withConnection(mailboxUid, (c) => coverage(c)));
         }
-    })();
+        case "setWindow": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => withCurrentConnection(p, (c) => setWindow(c, p)));
+        }
+        case "setBuilding": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => withCurrentConnection(p, (c) => setBuilding(c, p)));
+        }
+        case "destroy": {
+            const p = params;
+            // Recorded synchronously, before queueing - any build call issued earlier but still queued behind
+            // this one is rejected once it runs.
+            recordDestroyGeneration(p.mailboxUid, p.generation);
+            return runExclusive(p.mailboxUid, () => destroy(p.mailboxUid));
+        }
+        case "destroyAll": {
+            recordDestroyGeneration(undefined, params?.generation);
+            return destroyAll();
+        }
+        case "selfTest": {
+            const p = params;
+            return runExclusive(p.mailboxUid, () => selfTest(p));
+        }
+        default:
+            throw new Error(`Unknown localIndexWorker method: ${method}`);
+    }
+}
+self.addEventListener("message", (event) => {
+    const { id, method, params } = event.data;
+    handleRequest(method, params).then((result) => self.postMessage({ id, ok: true, result }), (err) => self.postMessage({ id, ok: false, error: err instanceof Error ? err.message : String(err) }));
 });