@rapidmx/web-client 0.3.0 → 0.4.0

package/dist/apps/shared/mail/findWellKnownFolderUid.js

@@ -0,0 +1,12 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
+/** The uid of a mailbox's well-known folder of `type` (e.g. its Contacts or Tasks folder), for creating an
+ * item in a mailbox other than the one an app currently has loaded. Resolves `undefined` if the mailbox has
+ * no such folder; rejects if the folder list can't be fetched. */
+export async function findWellKnownFolderUid(mailboxUid, type) {
+    const folders = await listFolders(mailboxUid);
+    return folders.find((folder) => folder.type === type)?.uid;
+}

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

@@ -0,0 +1,76 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Mounts the Tier 2 local index's lifecycle for one mailbox: starts the background build once it's
+ * unlocked, and destroys the index on the same events that destroy the unlocked keys themselves (spec
+ * §11 "MUST be destroyed on the same events that destroy private keys: explicit logout, session
+ * revocation, and the configurable idle timeout").
+ *
+ * **Why polling, not hooking the existing destroy call sites directly**: `destroyUnlockedKeys()`
+ * (`react-shared/src/crypto/keySession.ts`) has no observer/callback hook, and its own two real call
+ * sites are `useIdleKeyTimeout.ts` (in `react-shared`, not this repo) and the manual "Destroy keys now"
+ * button in Settings - editing the former would mean a react-shared source change that (per this
+ * session's own earlier finding) doesn't reach `web-client` without a package republish + patch refresh
+ * cycle, which is out of scope for wiring up a destroy signal. Watching `getUnlockedKeys()` for a
+ * present-to-absent transition instead catches *every* destroy path uniformly - idle timeout, the manual
+ * button, or anything else that calls it - without needing to know which one fired.
+ *
+ * **Explicit logout is the one gap this polling doesn't reliably cover**: `AppShell.tsx`'s sign-out
+ * navigates away immediately, which may not leave time for a poll tick to fire first. That case is
+ * handled separately, directly in `AppShell.tsx`, via `destroyAllLocalIndexes()` - see that call site's
+ * own comment.
+ */
+import { useEffect, useRef } from "react";
+import { getUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import { buildLocalIndex } from "./localIndexBuilder.js";
+import { destroyLocalIndex } from "./localIndexRpcClient.js";
+const POLL_INTERVAL_MS = 5000;
+/** Renders nothing - pure side-effect component, mounted by `MailShell.tsx` (which is where a
+ * `mailboxUid` is actually known; `AppShell.tsx` itself is mailbox-agnostic, shared by every app). Each
+ * `buildLocalIndex()` call below omits its `windowConfig` argument deliberately - that leaves the byte
+ * budget to its own default, which already resolves per-device (Web vs. Electron) and per-user
+ * preference (Settings > Encryption) on its own; see `localIndexBuilder.ts`/`localIndexSizePreference.ts`
+ * for how. */
+export default function LocalIndexLifecycle({ mailboxUid, folders }) {
+    // Guards against re-triggering a build every time this component re-renders (e.g. on an unrelated
+    // folders-list refresh) for a mailbox already built/building this session.
+    const buildStartedForRef = useRef(undefined);
+    const wasUnlockedRef = useRef(false);
+    useEffect(() => {
+        if (!mailboxUid || folders.length === 0) {
+            return;
+        }
+        const unlocked = getUnlockedKeys(mailboxUid);
+        wasUnlockedRef.current = !!unlocked;
+        if (unlocked && buildStartedForRef.current !== mailboxUid) {
+            buildStartedForRef.current = mailboxUid;
+            // Never an unhandled rejection - a broken local index (Worker/WASM/OPFS unsupported or
+            // unavailable, a corrupted store) is best-effort infrastructure, not a build the rest of the
+            // app depends on. searchTier2.ts's own callers already degrade gracefully independent of
+            // whether a build ever completed at all.
+            buildLocalIndex(mailboxUid, unlocked, folders).catch(() => undefined);
+        }
+        const interval = setInterval(() => {
+            const stillUnlocked = !!getUnlockedKeys(mailboxUid);
+            if (wasUnlockedRef.current && !stillUnlocked) {
+                // A present-to-absent transition: something just destroyed this mailbox's unlocked keys
+                // (idle timeout or the manual "Destroy keys now" button - see this module's own doc
+                // comment on why this is observed rather than hooked directly).
+                void destroyLocalIndex(mailboxUid);
+                buildStartedForRef.current = undefined;
+            }
+            else if (!wasUnlockedRef.current && stillUnlocked && buildStartedForRef.current !== mailboxUid) {
+                // The mailbox was re-unlocked this session (e.g. via ComposeWindow's or
+                // MessageDetailPane's own on-demand unlock prompt) - start the build it missed the first
+                // time around.
+                buildStartedForRef.current = mailboxUid;
+                buildLocalIndex(mailboxUid, getUnlockedKeys(mailboxUid), folders).catch(() => undefined);
+            }
+            wasUnlockedRef.current = stillUnlocked;
+        }, POLL_INTERVAL_MS);
+        return () => clearInterval(interval);
+    }, [mailboxUid, folders]);
+    return null;
+}

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

@@ -0,0 +1,63 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The actual AES-256-GCM block cipher `localIndexVFS.ts`'s `EncryptingVFS` uses to encrypt/decrypt one
+ * physical storage block - deliberately split out from that file so it can be exercised with real
+ * WebCrypto in a plain unit test, with no OPFS/Worker/wa-sqlite involved at all (none of those are
+ * available under Vitest's jsdom environment, matching the same "node" test environment convention
+ * `react-shared`'s other crypto modules already use for exactly this reason).
+ *
+ * See `localIndexVFS.ts`'s own doc comment for the full design rationale (page layout, why a fresh
+ * random nonce per write, why AAD binds to filename+block index). This module is pure mechanism; that
+ * one is where the design is explained.
+ */
+/** The logical SQLite page size `EncryptingVFS` is designed for - MUST match the `PRAGMA page_size` the
+ * database was created with (`localIndexWorker.ts` sets this before the first write). */
+export const LOGICAL_BLOCK_SIZE = 4096;
+const NONCE_LENGTH = 12;
+const TAG_LENGTH = 16;
+/** One physical block on disk: `nonce || ciphertext || tag`. */
+export const PHYSICAL_BLOCK_SIZE = LOGICAL_BLOCK_SIZE + NONCE_LENGTH + TAG_LENGTH;
+/** Thrown when a stored block fails AES-GCM authentication - a wrong/rotated key, on-disk corruption, or
+ * a block moved to the wrong position (see `localIndexVFS.ts`'s doc comment on why AAD binds position).
+ * The worker's caller treats this identically to a schema-version mismatch: discard the whole index and
+ * rebuild (spec §11 "Invalidation"). */
+export class PageCorruptedError extends Error {
+    constructor(filename, blockIndex, cause) {
+        super(`Local search index block ${blockIndex} of '${filename}' failed to decrypt.`);
+        this.cause = cause;
+    }
+}
+export async function importAesGcmKey(rawKey) {
+    return crypto.subtle.importKey("raw", rawKey, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+function buildBlockAad(filename, blockIndex) {
+    return new TextEncoder().encode(`rapidmx-local-index-block:${filename}:${blockIndex}`);
+}
+/** Encrypts one logical block (`plaintext`, exactly `LOGICAL_BLOCK_SIZE` bytes) into its physical,
+ * on-disk representation (`PHYSICAL_BLOCK_SIZE` bytes: a fresh random nonce followed by
+ * ciphertext+tag). */
+export async function encryptBlock(key, filename, blockIndex, plaintext) {
+    const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LENGTH));
+    const ciphertextAndTag = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce, additionalData: buildBlockAad(filename, blockIndex) }, key, plaintext));
+    const physical = new Uint8Array(PHYSICAL_BLOCK_SIZE);
+    physical.set(nonce, 0);
+    physical.set(ciphertextAndTag, NONCE_LENGTH);
+    return physical;
+}
+/** Inverse of `encryptBlock()`. Throws `PageCorruptedError` (never a raw `DOMException`) on auth
+ * failure - a wrong key, tampered ciphertext, or a block swapped into the wrong position (caught by the
+ * position-bound AAD not matching). */
+export async function decryptBlock(key, filename, blockIndex, physical) {
+    const nonce = physical.subarray(0, NONCE_LENGTH);
+    const ciphertextAndTag = physical.subarray(NONCE_LENGTH, PHYSICAL_BLOCK_SIZE);
+    try {
+        const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce, additionalData: buildBlockAad(filename, blockIndex) }, key, ciphertextAndTag);
+        return new Uint8Array(plaintext);
+    }
+    catch (err) {
+        throw new PageCorruptedError(filename, blockIndex, err);
+    }
+}

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

@@ -0,0 +1,153 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The Tier 2 local index's background builder (`specs/search.md` §11 "Initial build... incrementally,
+ * newest-first"). Runs on the main thread - the actual storage I/O and encryption happen in
+ * `localIndexWorker.ts` (off the UI thread, per that file's own doc comment); this module's own work is
+ * orchestration (deciding what to fetch) plus already-async fetch/decrypt calls, not CPU-heavy work that
+ * would itself need to move off-thread.
+ *
+ * **Known scoping simplification**: walks the mailbox's real mail folders one at a time (a fixed,
+ * reasonable priority order - Inbox and Sent first), each already newest-first via `listMessages()`'s own
+ * default sort, rather than a true interleaved k-way merge producing one single globally-newest-first
+ * stream across folders. A message in, say, Sent slightly older than the *oldest-processed-so-far*
+ * message in Inbox can therefore be indexed slightly out of true global date order relative to it. Given
+ * the byte-budget eviction below is itself date-based (oldest `date_for_sort` first, enforced by
+ * `localIndexWorker.ts`'s own `applyEviction()` after every insert - see that file), a small amount of
+ * cross-folder interleaving imprecision here does not affect *what* ultimately survives the window, only
+ * the exact order entities are inserted (and therefore briefly evicted-and-reinserted) in.
+ *
+ * Only encrypted messages (`subject === "[...]"`) are indexed - see `ENCRYPTED_SUBJECT_PLACEHOLDER`'s
+ * own precedent in `apps/www/index.tsx`'s inbox-list decrypt work. An unencrypted message is already
+ * fully searchable via Tier 1; indexing it here too would spend this index's bounded byte budget on
+ * content that didn't need it.
+ */
+import { getMessageRawContent, listMessages } from "@rapidmx/react-shared/mail/mailApi.js";
+import { evaluateMessageSecurity } from "@rapidmx/react-shared/crypto/messageSecurity.js";
+import { indexLocalEntities, initLocalIndex, setLocalIndexBuilding, setLocalIndexWindow } from "./localIndexRpcClient.js";
+import { deriveLocalIndexKey } from "./localIndexKey.js";
+import { getLocalIndexByteBudget } from "./localIndexSizePreference.js";
+/** The RFC 9788 placeholder subject every encrypted message's outer envelope carries server-side - see
+ * `apps/www/index.tsx`'s identical constant and its own doc comment for the full citation. */
+const ENCRYPTED_SUBJECT_PLACEHOLDER = "[...]";
+/** §11's Window Sizing table's time-floor column - explicitly unvalidated starting-point default per the
+ * spec's own §16 "Measurement Task" ("cannot be supplied by design work... MUST NOT be treated as
+ * validated"). Used as-is rather than invented/adjusted here. Not user-adjustable today (unlike the byte
+ * budget - see `localIndexSizePreference.ts`) - nothing in this codebase has asked for that yet. */
+export const WEB_TIME_FLOOR_MONTHS = 12;
+/** Folder types that actually hold messages - excludes `calendar`/`contacts`/other non-mail folder types
+ * `FolderType` also covers. Inbox and Sent first: the two folders a "did I find that email" search is
+ * overwhelmingly likely to land in, so they're covered soonest if the build is interrupted (tab closed,
+ * idle timeout) partway through. */
+const MESSAGE_FOLDER_TYPES = new Set(["inbox", "sent_items", "drafts", "deleted_items", "outbox", "junk"]);
+const FOLDER_PRIORITY = { inbox: 0, sent_items: 1 };
+const PAGE_SIZE = 100;
+const MAX_APPROX_BYTES_PER_MESSAGE_PADDING = 512; // subject/participants/flags overhead beyond raw text length
+/** `cutoff === undefined` means no time floor at all (an unbounded `windowConfig`) - every message is
+ * "within" it, so the caller's own end-of-folder check (`messages.length < PAGE_SIZE`) becomes the only
+ * stopping condition. */
+function isWithinTimeFloor(receivedDate, cutoff) {
+    return !cutoff || new Date(receivedDate).getTime() >= cutoff.getTime();
+}
+function estimateByteSize(entity) {
+    const textLength = (entity.subject?.length ?? 0) + (entity.body?.length ?? 0) + (entity.attachmentText?.length ?? 0) + entity.participants.length;
+    return textLength + MAX_APPROX_BYTES_PER_MESSAGE_PADDING;
+}
+/** Decrypts one message and shapes it into a `LocalIndexEntity`, or `undefined` when nothing usable was
+ * recovered (a decrypt failure, or a message that turns out not to actually be encrypted despite the
+ * placeholder subject) - mirrors `searchTier3.ts`'s own `!security.html && !security.subject` discard
+ * rule exactly, for the same reason. */
+async function buildEntity(message, unlocked) {
+    try {
+        const rawMime = await getMessageRawContent(message.uid);
+        const security = await evaluateMessageSecurity(rawMime, unlocked);
+        if (!security.subject && !security.html) {
+            return undefined;
+        }
+        const participants = [message.from.address, message.from.displayName, ...message.recipients.map((r) => r.address)]
+            .filter(Boolean)
+            .join(" ");
+        const setFlags = Object.entries(message.flags)
+            .filter(([, value]) => value)
+            .map(([key]) => key);
+        // Leading/trailing comma so `flags LIKE '%,x,%'` (localIndexSchema.ts's buildSearchPredicates())
+        // matches correctly even for the first/last flag in the list.
+        const flags = `,${setFlags.join(",")},`;
+        const entity = {
+            entityType: "message",
+            entityUid: message.uid,
+            mailboxUid: message.mailboxUid,
+            folderUid: message.folderUid,
+            dateForSort: message.receivedDate,
+            participants,
+            flags,
+            hasAttachments: message.hasAttachments,
+            subject: security.subject,
+            body: security.html,
+            byteSize: 0, // filled in below, after the fields above are known
+        };
+        entity.byteSize = estimateByteSize(entity);
+        return entity;
+    }
+    catch {
+        // Best-effort, matching searchTier3.ts's own Promise.allSettled-per-candidate posture - one
+        // message's fetch/decrypt failure never aborts the rest of the build.
+        return undefined;
+    }
+}
+/** Runs one full incremental build pass for `mailboxUid`: sets the window, walks mail folders newest-first
+ * (per this module's own doc comment on the folder-order simplification), decrypts and indexes only
+ * `"[...]"`-subject messages until each folder's own coverage passes the time floor, then clears the
+ * `building` flag. Never throws - a failure partway through leaves whatever was indexed so far in place
+ * (spec §11's "incomplete-index UX... MUST indicate that coverage is partial" is served by `coverage()`
+ * truthfully reporting whatever `indexedFrom` this run actually reached, not by this function needing to
+ * succeed completely).
+ *
+ * `windowConfig` defaults to this device's own configured byte budget (`getLocalIndexByteBudget()` -
+ * 500 MB in a browser tab, 1 GB in Electron, or whatever the user has since set in Settings > Encryption)
+ * alongside the fixed time floor above. Evaluated fresh on every call with no explicit override, so a
+ * preference change in Settings takes effect starting with this mailbox's next build pass (its next
+ * unlock), without requiring a reload.
+ */
+export async function buildLocalIndex(mailboxUid, unlocked, folders, windowConfig = { timeFloorMonths: WEB_TIME_FLOOR_MONTHS, byteBudgetBytes: getLocalIndexByteBudget() }) {
+    const indexKey = await deriveLocalIndexKey(unlocked.masterKey, mailboxUid);
+    await initLocalIndex({ mailboxUid, indexKey });
+    await setLocalIndexWindow(mailboxUid, windowConfig.timeFloorMonths, windowConfig.byteBudgetBytes);
+    await setLocalIndexBuilding(mailboxUid, true);
+    try {
+        let cutoff;
+        if (windowConfig.timeFloorMonths > 0) {
+            cutoff = new Date();
+            cutoff.setMonth(cutoff.getMonth() - windowConfig.timeFloorMonths);
+        }
+        const mailFolders = folders
+            .filter((f) => MESSAGE_FOLDER_TYPES.has(f.type))
+            .sort((a, b) => (FOLDER_PRIORITY[a.type] ?? 99) - (FOLDER_PRIORITY[b.type] ?? 99));
+        for (const folder of mailFolders) {
+            let page = 0;
+            for (;;) {
+                const messages = await listMessages(folder.uid, { page, limit: PAGE_SIZE }).catch(() => []);
+                if (messages.length === 0) {
+                    break;
+                }
+                const encrypted = messages.filter((m) => m.subject === ENCRYPTED_SUBJECT_PLACEHOLDER);
+                if (encrypted.length > 0) {
+                    const entities = (await Promise.all(encrypted.map((m) => buildEntity(m, unlocked)))).filter((e) => e !== undefined);
+                    if (entities.length > 0) {
+                        await indexLocalEntities(mailboxUid, entities);
+                    }
+                }
+                const oldestOnPage = messages[messages.length - 1];
+                if (!isWithinTimeFloor(oldestOnPage.receivedDate, cutoff) || messages.length < PAGE_SIZE) {
+                    break;
+                }
+                page += 1;
+            }
+        }
+    }
+    finally {
+        await setLocalIndexBuilding(mailboxUid, false);
+    }
+}

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

@@ -0,0 +1,25 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Derives the page-encryption key for one mailbox's Tier 2 local index (`specs/search.md` §11
+ * "Persistence and protection... MUST be encrypted at rest under the mailbox master key (MK)... using
+ * the same AEAD construction"). Reuses `crypto/masterKey.ts`'s existing `hkdfDerive()` - the same HKDF
+ * primitive every other MK-derived key in this codebase already goes through.
+ *
+ * No persisted per-install salt: MK is already 32 bytes of uniform random key material (see
+ * `masterKey.ts`'s own `generateMasterKey()`), so a fixed, non-secret salt is standard HKDF practice
+ * here (RFC 5869 - a salt matters for stretching low-entropy input, not for re-randomizing input that's
+ * already uniformly random) and avoids needing to persist, transmit, or ever lose a random salt just to
+ * re-derive the same key on the next unlock.
+ */
+import { hkdfDerive } from "@rapidmx/react-shared/crypto/masterKey.js";
+/** Fixed, non-secret HKDF salt - see this module's own doc comment for why a fixed salt is fine here. */
+const FIXED_SALT = new TextEncoder().encode("rapidmx-local-search-index-v1");
+/** Derives this mailbox's local-index page-encryption key from its already-unlocked master key. Every
+ * call with the same `(masterKey, mailboxUid)` pair returns the identical key - callers never need to
+ * persist it themselves. */
+export async function deriveLocalIndexKey(masterKey, mailboxUid) {
+    return hkdfDerive(masterKey, FIXED_SALT, `local-search-index:${mailboxUid}`);
+}

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

@@ -0,0 +1,78 @@
+let worker;
+let nextRequestId = 1;
+const pending = new Map();
+/** Every mailboxUid `initLocalIndex()` has opened this session, not yet `destroyLocalIndex()`-ed - lets
+ * `destroyAllLocalIndexes()` (called from `AppShell.tsx`'s sign-out, which has no mailboxUid of its own
+ * to pass - see that call site's own comment) destroy every open index without needing one threaded
+ * through. Mirrors `keySession.ts`'s own module-level `sessions` map in spirit - session-scoped,
+ * intentionally never persisted. */
+const initializedMailboxes = new Set();
+function getWorker() {
+    if (!worker) {
+        worker = new Worker(new URL("./localIndexWorker.ts", import.meta.url), { type: "module" });
+        worker.addEventListener("message", (event) => {
+            const entry = pending.get(event.data.id);
+            if (!entry) {
+                return;
+            }
+            pending.delete(event.data.id);
+            if (event.data.ok) {
+                entry.resolve(event.data.result);
+            }
+            else {
+                entry.reject(new Error(event.data.error));
+            }
+        });
+    }
+    return worker;
+}
+function call(method, params) {
+    const id = nextRequestId++;
+    return new Promise((resolve, reject) => {
+        pending.set(id, { resolve: resolve, reject });
+        getWorker().postMessage({ id, method, params });
+    });
+}
+export async function initLocalIndex(params) {
+    await call("init", params);
+    initializedMailboxes.add(params.mailboxUid);
+}
+export function indexLocalEntities(mailboxUid, entities) {
+    return call("indexEntities", { mailboxUid, entities });
+}
+export function removeLocalEntity(mailboxUid, entityUid) {
+    return call("removeEntity", { mailboxUid, entityUid });
+}
+export function searchLocal(mailboxUid, parsed, limit, offset = 0) {
+    return call("search", { mailboxUid, parsed, limit, offset });
+}
+export function getLocalCoverage(mailboxUid) {
+    return call("coverage", mailboxUid);
+}
+export function setLocalIndexWindow(mailboxUid, timeFloorMonths, byteBudgetBytes) {
+    return call("setWindow", { mailboxUid, timeFloorMonths, byteBudgetBytes });
+}
+export function setLocalIndexBuilding(mailboxUid, building) {
+    return call("setBuilding", { mailboxUid, building });
+}
+/** Destroys one mailbox's local index (both the SQLite connection and its on-disk OPFS storage) - spec
+ * §11 "MUST be destroyed on the same events that destroy private keys." Never throws: called from
+ * lifecycle hooks (idle timeout, logout, the manual "destroy keys now" button) where a destroy failure
+ * shouldn't block the key-destruction it's piggybacking on. */
+export async function destroyLocalIndex(mailboxUid) {
+    try {
+        await call("destroy", mailboxUid);
+    }
+    catch {
+        // Best-effort - see this function's own doc comment.
+    }
+    finally {
+        initializedMailboxes.delete(mailboxUid);
+    }
+}
+/** Destroys every mailbox's local index this session has opened - for a caller (`AppShell.tsx`'s
+ * sign-out) that has no specific mailboxUid of its own, the same "clear everything" shape
+ * `destroyUnlockedKeys()` itself offers when called with no argument. */
+export async function destroyAllLocalIndexes() {
+    await Promise.all([...initializedMailboxes].map((mailboxUid) => destroyLocalIndex(mailboxUid)));
+}

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

@@ -0,0 +1,179 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The Tier 2 local index's SQLite schema (`specs/search.md` §13). One database per mailbox (see
+ * `localIndexWorker.ts`), holding both the FTS5 index and the metadata cache in the same store - the
+ * spec's own rationale for choosing SQLite over an in-memory JS index in the first place ("the index
+ * database also holds the decrypted metadata cache... so there is one local store rather than two").
+ *
+ * Bumping `SCHEMA_VERSION` is how a schema change invalidates every existing local index (§11
+ * "Invalidation... on schema version change") - `localIndexWorker.ts` compares it against `meta`'s
+ * stored value on open and discards+rebuilds on a mismatch, the same path a corruption/GCM-auth-failure
+ * takes.
+ */
+/** Bump whenever `CREATE_SCHEMA_SQL` changes in a way existing on-disk databases can't be reconciled
+ * with in place. */
+export const SCHEMA_VERSION = 1;
+/**
+ * `entities` is the real row store (metadata + the plaintext content fields), `entities_fts` is an FTS5
+ * *external content* table over it (`content='entities'`) - the standard SQLite pattern for keeping one
+ * copy of the text instead of duplicating it into the FTS5 shadow tables, kept in sync via the three
+ * triggers below (SQLite's own documented pattern for external-content FTS5 tables; there is no
+ * "ON CONFLICT UPDATE re-index" primitive, so update is modeled as delete-then-reinsert into the FTS
+ * index specifically, not into `entities` itself).
+ *
+ * Column order in `entities_fts` (`subject, participants, body, attachment_text`) is load-bearing: every
+ * `bm25(entities_fts, 3.0, 2.0, 1.0, 1.0)` call elsewhere in this module family assumes that exact
+ * positional order, matching `searchScoring.ts`'s `SEARCH_FIELD_WEIGHTS` (`subject: 3, participants: 2,
+ * body: 1, attachmentText: 1`) so Tier 2's local ranking agrees with the Tier 1/Tier 3 re-scoring the
+ * spec requires for one consistent ordering across tiers (§7).
+ */
+export const CREATE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS meta (
+    key TEXT PRIMARY KEY,
+    value TEXT
+);
+
+CREATE TABLE IF NOT EXISTS entities (
+    rowid INTEGER PRIMARY KEY,
+    entity_type TEXT NOT NULL,
+    entity_uid TEXT NOT NULL UNIQUE,
+    mailbox_uid TEXT NOT NULL,
+    folder_uid TEXT,
+    date_for_sort TEXT NOT NULL,
+    participants TEXT,
+    flags TEXT,
+    has_attachments INTEGER NOT NULL DEFAULT 0,
+    subject TEXT,
+    body TEXT,
+    attachment_text TEXT,
+    byte_size INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_entities_date ON entities(date_for_sort);
+CREATE INDEX IF NOT EXISTS idx_entities_mailbox ON entities(mailbox_uid);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
+    subject, participants, body, attachment_text,
+    content='entities', content_rowid='rowid', tokenize='unicode61'
+);
+
+CREATE TRIGGER IF NOT EXISTS entities_ai AFTER INSERT ON entities BEGIN
+    INSERT INTO entities_fts(rowid, subject, participants, body, attachment_text)
+    VALUES (new.rowid, new.subject, new.participants, new.body, new.attachment_text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS entities_ad AFTER DELETE ON entities BEGIN
+    INSERT INTO entities_fts(entities_fts, rowid, subject, participants, body, attachment_text)
+    VALUES ('delete', old.rowid, old.subject, old.participants, old.body, old.attachment_text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS entities_au AFTER UPDATE ON entities BEGIN
+    INSERT INTO entities_fts(entities_fts, rowid, subject, participants, body, attachment_text)
+    VALUES ('delete', old.rowid, old.subject, old.participants, old.body, old.attachment_text);
+    INSERT INTO entities_fts(rowid, subject, participants, body, attachment_text)
+    VALUES (new.rowid, new.subject, new.participants, new.body, new.attachment_text);
+END;
+`;
+/** The exact `bm25()` weight arguments every ranked query against `entities_fts` MUST pass, in column
+ * order - see this module's own doc comment on why the order is load-bearing. Centralized here so a
+ * future column reorder can't silently desync a query building its own literal weight list. */
+export const BM25_WEIGHTS_SQL = "3.0, 2.0, 1.0, 1.0";
+/** `entity_uid` upsert - `ON CONFLICT` (SQLite's UPSERT syntax) rather than a separate delete-then-insert,
+ * so re-indexing an already-present message (a flag changed, a folder move) updates it in place and the
+ * `entities_au` trigger keeps `entities_fts` in sync automatically. */
+export const UPSERT_ENTITY_SQL = `
+INSERT INTO entities (entity_type, entity_uid, mailbox_uid, folder_uid, date_for_sort, participants, flags, has_attachments, subject, body, attachment_text, byte_size)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(entity_uid) DO UPDATE SET
+    folder_uid = excluded.folder_uid, date_for_sort = excluded.date_for_sort, participants = excluded.participants,
+    flags = excluded.flags, has_attachments = excluded.has_attachments, subject = excluded.subject,
+    body = excluded.body, attachment_text = excluded.attachment_text, byte_size = excluded.byte_size
+`;
+/** Bind values for `UPSERT_ENTITY_SQL`, in column order - kept alongside it so the two can never drift
+ * out of sync with each other. */
+export function entityBindValues(entity) {
+    return [
+        entity.entityType,
+        entity.entityUid,
+        entity.mailboxUid,
+        entity.folderUid ?? null,
+        entity.dateForSort,
+        entity.participants,
+        entity.flags,
+        entity.hasAttachments ? 1 : 0,
+        entity.subject ?? null,
+        entity.body ?? null,
+        entity.attachmentText ?? null,
+        entity.byteSize,
+    ];
+}
+/**
+ * Builds the SQL `WHERE` predicate (and its bind params) for every *structured* operator this local
+ * index can actually evaluate. **Known simplification**: unlike Tier 1's server-side `SearchDocument`
+ * (which splits `from`/`to`/`cc` into distinct fields - confirmed already implemented server-side), this
+ * local schema keeps only the combined `participants` field (see `CREATE_SCHEMA_SQL`'s own doc comment) -
+ * `from:`/`to:`/`cc:` are therefore evaluated here as a substring match against that combined field
+ * rather than a precise per-role match. Reasonable for a bounded, best-effort recent-window cache
+ * (Tier 1 already serves the precise version for anything it indexes), but a real gap if Tier 2 is later
+ * extended to distinguish them - flagged here rather than left silently approximate.
+ */
+export function buildSearchPredicates(parsed, mailboxUid) {
+    const clauses = ["e.mailbox_uid = ?"];
+    const params = [mailboxUid];
+    if (parsed.folderUid) {
+        clauses.push("e.folder_uid = ?");
+        params.push(parsed.folderUid);
+    }
+    if (parsed.before) {
+        clauses.push("e.date_for_sort < ?");
+        params.push(parsed.before.toISOString());
+    }
+    if (parsed.after) {
+        clauses.push("e.date_for_sort > ?");
+        params.push(parsed.after.toISOString());
+    }
+    if (parsed.hasAttachment !== undefined) {
+        clauses.push("e.has_attachments = ?");
+        params.push(parsed.hasAttachment ? 1 : 0);
+    }
+    for (const flag of parsed.flags ?? []) {
+        clauses.push("e.flags LIKE ?");
+        params.push(`%,${flag},%`);
+    }
+    for (const participant of [parsed.from, parsed.to, parsed.cc]) {
+        if (participant) {
+            clauses.push("e.participants LIKE ?");
+            params.push(`%${participant}%`);
+        }
+    }
+    return { where: clauses.join(" AND "), params };
+}
+/** Escapes a free-text fragment for safe embedding inside an FTS5 `MATCH` phrase - FTS5's own quoting
+ * rule for a `"..."` phrase is doubling an embedded `"`, mirroring SQL string-literal escaping. */
+function escapeFtsPhrase(value) {
+    return value.replace(/"/g, '""');
+}
+/**
+ * Builds the FTS5 `MATCH` expression for a parsed query's free-text and `subject:` portions, or
+ * `undefined` when there's nothing to match on text at all (a pure operator/structured-filter query -
+ * `buildSearchPredicates()`'s `WHERE` clause alone already narrows that case correctly, no `MATCH`
+ * needed). `parsed.text` is passed through close to verbatim (quoted phrases, `OR`, `-` negation - FTS5's
+ * own query syntax supports the same shape `queryGrammar.ts`'s own doc comment says every provider's
+ * free-text engine is expected to), wrapped only enough to combine it with a `subject:`-scoped clause
+ * when both are present.
+ */
+export function buildMatchExpression(parsed) {
+    const parts = [];
+    if (parsed.subject) {
+        parts.push(`subject:"${escapeFtsPhrase(parsed.subject)}"`);
+    }
+    if (parsed.text.trim()) {
+        parts.push(parsed.subject ? `(${parsed.text})` : parsed.text);
+    }
+    if (parts.length === 0) {
+        return undefined;
+    }
+    return parts.join(" AND ");
+}