@rapidmx/web-client 0.3.1 → 0.5.0

package/apps/shared/search/localIndexRpcClient.ts

@@ -0,0 +1,316 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Main-thread Promise-based RPC wrapper around `localIndexWorker.ts`. One Worker per tab (spawned
+ * lazily, on first use, not at module load - a page that never touches search shouldn't pay for booting
+ * the WASM module at all), shared across every mailbox `init()`-ed this session - the Worker itself keeps
+ * a per-mailbox connection map (see that file's own doc comment).
+ *
+ * `postMessage` has no native request/response pairing, so every call generates its own numeric `id` and
+ * this module correlates the eventual matching response via a pending-request map.
+ *
+ * **Generations**: `nextLocalIndexGeneration()` hands out one monotonic counter shared by build passes and
+ * destroys, so the Worker can reject a build call issued before the index was destroyed (see
+ * `GenerationParams`).
+ *
+ * **Sign-out reaches every tab**: `destroyAllLocalIndexes()` broadcasts on a `BroadcastChannel`; any other
+ * tab running a Worker closes its connections and refuses further `init`s.
+ *
+ * **Failed deletions are retried**: a destroy that couldn't remove a directory (another tab held it, the page
+ * navigated away first) is recorded in `localStorage` and retried before this tab's first `init`.
+ */
+import type { ParsedSearchQuery } from "@rapidmx/react-shared/search/queryGrammar.js";
+import type {
+    Coverage,
+    DestroyParams,
+    GenerationParams,
+    IndexEntitiesParams,
+    IndexEntitiesResult,
+    IndexedVersionsParams,
+    InitParams,
+    LocalIndexRequest,
+    LocalIndexResponse,
+    LocalSearchPage,
+    MoveEntityParams,
+    PruneEntitiesParams,
+    RemoveEntityParams,
+    SearchParams,
+    SetBuildingParams,
+    SetWindowParams,
+    WindowState,
+} from "./localIndexWorker.js";
+import type { LocalIndexEntity } from "./localIndexSchema.js";
+import { removeLocalIndexDirectories, removeLocalIndexDirectory } from "./localIndexStorage.js";
+
+let worker: Worker | undefined;
+let nextRequestId = 1;
+const pending = new Map<number, { resolve: (value: unknown) => void; reject: (err: Error) => void }>();
+
+/** Every mailboxUid `initLocalIndex()` has opened this session, not yet `destroyLocalIndex()`-ed. Gates
+ * the in-session mutation helpers (`removeLocalEntity()`/`moveLocalEntity()`) so a delete/move in a
+ * mailbox this tab never indexed doesn't spin up the Worker just to no-op. */
+const initializedMailboxes = new Set<string>();
+
+let generationCounter = 0;
+
+/** A fresh generation - see this module's doc comment. */
+export function nextLocalIndexGeneration(): number {
+    generationCounter += 1;
+    return generationCounter;
+}
+
+/** Set once this tab (or another one) signed out - no index may be opened again in this page load. */
+let signedOut = false;
+
+export const SIGN_OUT_CHANNEL = "rapidmx-localsearch";
+let channel: BroadcastChannel | undefined;
+
+function getWorker(): Worker {
+    if (!worker) {
+        worker = new Worker(new URL("./localIndexWorker.ts", import.meta.url), { type: "module" });
+        worker.addEventListener("message", (event: MessageEvent<LocalIndexResponse>) => {
+            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));
+            }
+        });
+        // Only a tab with a Worker has connections to close when another tab signs out.
+        listenForSignOut();
+    }
+    return worker;
+}
+
+function getChannel(): BroadcastChannel | undefined {
+    if (!channel && typeof BroadcastChannel !== "undefined") {
+        channel = new BroadcastChannel(SIGN_OUT_CHANNEL);
+    }
+    return channel;
+}
+
+function listenForSignOut(): void {
+    getChannel()?.addEventListener("message", (event: MessageEvent<{ type?: string }>) => {
+        if (event.data?.type === "sign-out") {
+            void closeEverythingInThisTab();
+        }
+    });
+}
+
+/** Another tab signed out: stop every build here and close this tab's connections (which also removes their
+ * directories, now that nothing holds them open). Never rejects. */
+async function closeEverythingInThisTab(): Promise<void> {
+    signedOut = true;
+    initializedMailboxes.clear();
+    await call("destroyAll", { generation: nextLocalIndexGeneration() } satisfies GenerationParams).catch(() => undefined);
+}
+
+function call<T>(method: LocalIndexRequest["method"], params?: unknown): Promise<T> {
+    const id = nextRequestId++;
+    return new Promise<T>((resolve, reject) => {
+        pending.set(id, { resolve: resolve as (value: unknown) => void, reject });
+        try {
+            getWorker().postMessage({ id, method, params } satisfies LocalIndexRequest);
+        } catch (err) {
+            pending.delete(id);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+}
+
+export const PENDING_DELETIONS_KEY = "rapidmx-localsearch-pending-deletions";
+/** Stands for "every index on this device" in the pending-deletions list - recorded before a sign-out starts,
+ * so a navigation that kills it midway still gets finished on the next load. */
+const ALL_INDEXES = "*";
+
+function readPendingDeletions(): string[] {
+    try {
+        const parsed: unknown = JSON.parse(localStorage.getItem(PENDING_DELETIONS_KEY) ?? "[]");
+        return Array.isArray(parsed) ? parsed.filter((uid): uid is string => typeof uid === "string") : [];
+    } catch {
+        return [];
+    }
+}
+
+function writePendingDeletions(uids: Iterable<string>): void {
+    try {
+        const list = [...new Set(uids)];
+        if (list.length === 0) {
+            localStorage.removeItem(PENDING_DELETIONS_KEY);
+        } else {
+            localStorage.setItem(PENDING_DELETIONS_KEY, JSON.stringify(list));
+        }
+    } catch {
+        // Storage blocked - nothing to retry from, the same as before this existed.
+    }
+}
+
+function updatePendingDeletions(update: (current: Set<string>) => void): void {
+    const current = new Set(readPendingDeletions());
+    update(current);
+    writePendingDeletions(current);
+}
+
+let pendingRetry: Promise<void> | undefined;
+
+/** Retries every deletion an earlier page load couldn't finish. Runs once per page load (memoized), before
+ * this tab's first `init` - so it never races an index this tab itself opens. Never rejects. */
+export function retryPendingLocalIndexDeletions(): Promise<void> {
+    pendingRetry ??= (async () => {
+        const uids = readPendingDeletions();
+        if (uids.length === 0) {
+            return;
+        }
+        const failed: string[] = [];
+        if (uids.includes(ALL_INDEXES)) {
+            const result = await removeLocalIndexDirectories().catch(() => ({ failed: [ALL_INDEXES] }));
+            failed.push(...result.failed);
+        } else {
+            for (const uid of uids) {
+                await removeLocalIndexDirectory(uid).catch(() => failed.push(uid));
+            }
+        }
+        writePendingDeletions(failed);
+    })();
+    return pendingRetry;
+}
+
+export async function initLocalIndex(params: InitParams): Promise<void> {
+    await retryPendingLocalIndexDeletions();
+    if (signedOut) {
+        throw new Error("Signed out - the local search index is unavailable in this tab.");
+    }
+    await call("init", params);
+    initializedMailboxes.add(params.mailboxUid);
+}
+
+export function indexLocalEntities(mailboxUid: string, entities: LocalIndexEntity[], generation?: number): Promise<IndexEntitiesResult> {
+    return call("indexEntities", { mailboxUid, entities, generation } satisfies IndexEntitiesParams);
+}
+
+/** Drops one message from this session's local index (a delete). A no-op for a mailbox not indexed in
+ * this tab - a later build pass prunes it instead. Never rejects: best-effort housekeeping. */
+export async function removeLocalEntity(mailboxUid: string, entityUid: string): Promise<void> {
+    if (!initializedMailboxes.has(mailboxUid)) {
+        return;
+    }
+    await call("removeEntity", { mailboxUid, entityUid } satisfies RemoveEntityParams).catch(() => undefined);
+}
+
+/** Re-points one indexed message at its new folder (archive, cancel-scheduled-send) so `folder:`-scoped
+ * local searches stay correct. Same no-op/never-rejects rules as `removeLocalEntity()`. */
+export async function moveLocalEntity(mailboxUid: string, entityUid: string, folderUid: string): Promise<void> {
+    if (!initializedMailboxes.has(mailboxUid)) {
+        return;
+    }
+    await call("moveEntity", { mailboxUid, entityUid, folderUid } satisfies MoveEntityParams).catch(() => undefined);
+}
+
+export function getIndexedVersions(mailboxUid: string, entityUids: string[]): Promise<Record<string, string>> {
+    return call("indexedVersions", { mailboxUid, entityUids } satisfies IndexedVersionsParams);
+}
+
+export function pruneLocalEntities(
+    mailboxUid: string,
+    keepEntityUids: string[],
+    since: string | undefined,
+    options: { folderUids?: string[]; generation?: number } = {},
+): Promise<number> {
+    return call("pruneEntities", { mailboxUid, keepEntityUids, since, ...options } satisfies PruneEntitiesParams);
+}
+
+export function searchLocal(mailboxUid: string, parsed: ParsedSearchQuery, limit: number, offset = 0): Promise<LocalSearchPage> {
+    return call("search", { mailboxUid, parsed, limit, offset } satisfies SearchParams);
+}
+
+export function getLocalCoverage(mailboxUid: string): Promise<Coverage> {
+    return call("coverage", mailboxUid);
+}
+
+export function setLocalIndexWindow(mailboxUid: string, timeFloorMonths: number, byteBudgetBytes: number, generation?: number): Promise<WindowState> {
+    return call("setWindow", { mailboxUid, timeFloorMonths, byteBudgetBytes, generation } satisfies SetWindowParams);
+}
+
+export function setLocalIndexBuilding(
+    mailboxUid: string,
+    building: boolean,
+    completion: { complete: boolean; coveredFrom?: string; coveredUntil?: string; generation?: number } = { complete: false },
+): Promise<void> {
+    return call("setBuilding", { mailboxUid, building, ...completion } satisfies SetBuildingParams);
+}
+
+/** 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 rejects (it's called from
+ * lifecycle hooks where a failure mustn't block key destruction) but resolves `false` - and logs why -
+ * when the index could not be removed, e.g. because another tab still has it open; the deletion is then
+ * retried on the next page load. */
+export async function destroyLocalIndex(mailboxUid: string): Promise<boolean> {
+    updatePendingDeletions((current) => current.add(mailboxUid));
+    try {
+        await call("destroy", { mailboxUid, generation: nextLocalIndexGeneration() } satisfies DestroyParams);
+        updatePendingDeletions((current) => current.delete(mailboxUid));
+        return true;
+    } catch (err) {
+        // `call()` only ever rejects with an Error.
+        console.warn(`Could not destroy the local search index for mailbox ${mailboxUid}: ${(err as Error).message}`);
+        return false;
+    } finally {
+        initializedMailboxes.delete(mailboxUid);
+    }
+}
+
+/** How long sign-out waits for local index destruction before navigating anyway. */
+export const DESTROY_ALL_TIMEOUT_MS = 3_000;
+
+/**
+ * Destroys **every** local index on this device - not just the mailboxes this page load opened (sign-out
+ * from Calendar, say, never opened any), by enumerating OPFS for the index directory prefix - and tells every
+ * other tab to close its own connections. Closes this tab's own open connections through the Worker first
+ * (only if one was ever spawned - there's nothing to close otherwise, and booting one just to delete files
+ * would be waste), then removes the directories. Anything left behind is retried on the next load. Resolves
+ * `true` when everything was removed within `timeoutMs`; never rejects.
+ */
+export async function destroyAllLocalIndexes(timeoutMs = DESTROY_ALL_TIMEOUT_MS): Promise<boolean> {
+    signedOut = true;
+    writePendingDeletions([ALL_INDEXES]);
+    try {
+        getChannel()?.postMessage({ type: "sign-out" });
+    } catch {
+        // A closed/unsupported channel only loses the cross-tab notification.
+    }
+    const work = (async () => {
+        let ok = true;
+        if (worker) {
+            const { failed } = await call<{ failed: string[] }>("destroyAll", { generation: nextLocalIndexGeneration() } satisfies GenerationParams).catch(() => ({
+                failed: ["(worker)"],
+            }));
+            ok = failed.length === 0;
+        }
+        initializedMailboxes.clear();
+        const { failed } = await removeLocalIndexDirectories();
+        writePendingDeletions(failed);
+        return ok && failed.length === 0;
+    })().catch(() => false);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<boolean>((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+    });
+    const result = await Promise.race([work, timeout]);
+    clearTimeout(timer);
+    if (!result) {
+        console.warn("Could not destroy every local search index before signing out.");
+    }
+    return result;
+}
+
+/** Removes local indexes for mailboxes outside `accessibleMailboxUids` - e.g. left behind by a different
+ * user who signed in on this device without signing out. Never rejects. */
+export async function pruneInaccessibleLocalIndexes(accessibleMailboxUids: Iterable<string>): Promise<void> {
+    await removeLocalIndexDirectories(new Set(accessibleMailboxUids)).catch(() => undefined);
+}

package/apps/shared/search/localIndexSchema.ts

@@ -0,0 +1,236 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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. A mismatch deletes and recreates the whole database file (not just its rows), so
+ * creation-time-only settings like `auto_vacuum` also apply to upgraded indexes.
+ *
+ * 2 - added `entities.entity_version` (incremental rebuild skip) and `auto_vacuum=INCREMENTAL`. */
+export const SCHEMA_VERSION = 2;
+
+/**
+ * `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,
+    entity_version TEXT
+);
+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";
+
+/** One message's decrypted content, ready to index - `localIndexBuilder.ts`'s own output shape, built
+ * from `Message` + the recovered `MessageSecurityResult` fields the same way `searchTier3.ts` already
+ * derives them for its own per-candidate matching. */
+export interface LocalIndexEntity {
+    entityType: "message";
+    entityUid: string;
+    mailboxUid: string;
+    folderUid?: string;
+    /** ISO 8601 - compares correctly as plain text since every value here is UTC. */
+    dateForSort: string;
+    participants: string;
+    /** Comma-delimited, leading/trailing commas included (`,read,flagged,`) - simplest possible substring
+     * match (`flags LIKE '%,read,%'`) without needing SQLite's JSON1 extension compiled in. */
+    flags: string;
+    hasAttachments: boolean;
+    subject?: string;
+    body?: string;
+    attachmentText?: string;
+    /** Rough on-disk cost of this entity's own content, in bytes - what `localIndexBuilder.ts`'s
+     * byte-budget accounting (spec §11) sums against the configured budget. */
+    byteSize: number;
+    /** Opaque change marker for the source entity (the builder uses the message's `version` plus its
+     * folder) - lets a rebuild skip re-fetching/decrypting anything already indexed unchanged. */
+    entityVersion?: string;
+}
+
+/** `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, entity_version)
+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,
+    entity_version = excluded.entity_version
+`;
+
+/** 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: LocalIndexEntity): (string | number)[] {
+    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,
+        entity.entityVersion ?? null!,
+    ];
+}
+
+/** A parsed query's structured (non-free-text) fields - the subset of `ParsedSearchQuery`
+ * (`react-shared`'s `queryGrammar.ts`) this module's predicate builder reads. Typed locally rather than
+ * importing `ParsedSearchQuery` itself so this Worker-bundled module has no dependency on `@rapidmx/
+ * react-shared` beyond what it actually uses - `localIndexBuilder.ts`/`searchTier2.ts` (main-thread side)
+ * pass the real `ParsedSearchQuery` in, which structurally satisfies this. */
+export interface LocalSearchPredicateFields {
+    from?: string;
+    to?: string;
+    cc?: string;
+    subject?: string;
+    hasAttachment?: boolean;
+    before?: Date;
+    after?: Date;
+    folderUid?: string;
+    flags?: string[];
+}
+
+/**
+ * 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: LocalSearchPredicateFields, mailboxUid: string): { where: string; params: (string | number)[] } {
+    const clauses: string[] = ["e.mailbox_uid = ?"];
+    const params: (string | number)[] = [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: string): string {
+    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: { text: string; subject?: string }): string | undefined {
+    const parts: string[] = [];
+    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 ");
+}

package/apps/shared/search/localIndexSizePreference.ts

@@ -0,0 +1,88 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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;
+
+export interface LocalIndexSizeOption {
+    bytes: number;
+    label: string;
+}
+
+/** 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: LocalIndexSizeOption[] = [
+    { 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(): boolean {
+    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(): number {
+    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(): number {
+    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: number): void {
+    try {
+        localStorage.setItem(STORAGE_KEY, String(bytes));
+    } catch {
+        // Best-effort - see this function's own doc comment.
+    }
+}