@rapidmx/web-client 0.35.0 → 0.37.0

package/dist/apps/shared/search/localIndexRpcClient.d.ts

@@ -1,39 +1,3 @@
-/**
- * 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`.
- *
- * **A crashed Worker never leaves a caller hanging**: the `error` listener registered in `getWorker()` rejects
- * every pending request and drops the module-level `worker` reference so the next `call()` spawns a
- * replacement. `searchTier2.ts` additionally races its own calls against a timeout, since a Worker that's
- * merely stuck (not crashed) posts no `error` event at all.
- *
- * **Swappable transport**: everything above is specific to this one implementation - the Worker/OPFS-backed
- * default. Every function this module exports below (`initLocalIndex`, `searchLocal`, `destroyLocalIndex`, ...)
- * is a thin delegator to whichever `LocalIndexTransport` (`localIndexTransport.ts`) is "current," which defaults
- * to `workerLocalIndexTransport` - this file's own implementation, wrapped - and can be swapped once, at startup,
- * via `setLocalIndexTransport()`. A host app with a different storage backend (no Worker, no OPFS, no WASM at
- * all - `tauri-client`'s native SQLCipher/`rusqlite` index) installs its own transport there; every call site
- * that already goes through this file's exports (`searchTier2.ts`, `LocalIndexLifecycle.tsx`,
- * `localIndexBuilder.ts`, and the rest) then runs against that backend instead, unmodified. The three
- * module-level constants below (`SIGN_OUT_CHANNEL`, `PENDING_DELETIONS_KEY`, `DESTROY_ALL_TIMEOUT_MS`) remain
- * plain exports, not part of the swappable interface - they name this one transport's own cross-tab/localStorage
- * mechanics, which a different transport has no reason to share.
- */
 import type { ParsedSearchQuery } from "../../../lib/search/queryGrammar.js";
 import type { Coverage, IndexEntitiesResult, InitParams, LocalSearchPage, WindowState } from "./localIndexWorker.js";
 import type { LocalIndexEntity } from "./localIndexSchema.js";
@@ -65,8 +29,9 @@ export declare function indexLocalEntities(mailboxUid: string, entities: LocalIn
  * this tab - a later build pass prunes it instead. Never rejects: best-effort housekeeping. */
 export declare function removeLocalEntity(mailboxUid: string, entityUid: string): Promise<void>;
 /** 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 declare function moveLocalEntity(mailboxUid: string, entityUid: string, folderUid: string): Promise<void>;
+ * local searches stay correct. Same no-op/never-rejects rules as `removeLocalEntity()`. `flags` (`,flag,flag,`) sets the row's flags
+ * too - a zero-access row's, which nothing else records. */
+export declare function moveLocalEntity(mailboxUid: string, entityUid: string, folderUid: string, entityVersion?: string, flags?: string): Promise<void>;
 export declare function getIndexedVersions(mailboxUid: string, entityUids: string[]): Promise<Record<string, string>>;
 export declare function pruneLocalEntities(mailboxUid: string, keepEntityUids: string[], since: string | undefined, options?: PruneLocalEntitiesOptions): Promise<number>;
 export declare function searchLocal(mailboxUid: string, parsed: ParsedSearchQuery, limit: number, offset?: number): Promise<LocalSearchPage>;
@@ -82,7 +47,8 @@ export declare function destroyLocalIndex(mailboxUid: string): Promise<boolean>;
  * on sign-out. Never rejects. Resolves `true` only if everything was removed within `timeoutMs`. */
 export declare function destroyAllLocalIndexes(timeoutMs?: number): Promise<boolean>;
 /** 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. */
+ * user who signed in on this device without signing out. The transport decides what goes, zero-access sync state included (the
+ * Worker transport forgets it with the index; a host wrapper that skips the prune keeps both). Never rejects. */
 export declare function pruneInaccessibleLocalIndexes(accessibleMailboxUids: Iterable<string>): Promise<void>;
 /** Retries every deletion an earlier session couldn't finish. Never rejects. */
 export declare function retryPendingLocalIndexDeletions(): Promise<void>;

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

@@ -1,4 +1,51 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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`.
+ *
+ * **A crashed Worker never leaves a caller hanging**: the `error` listener registered in `getWorker()` rejects
+ * every pending request and drops the module-level `worker` reference so the next `call()` spawns a
+ * replacement. `searchTier2.ts` additionally races its own calls against a timeout, since a Worker that's
+ * merely stuck (not crashed) posts no `error` event at all.
+ *
+ * **A lock destroys the index**: `initLocalIndex()` subscribes once to the key session (`subscribeKeySession()`); when the keys of
+ * a mailbox whose index it opened are destroyed (an idle lock, a manual lock, a sign-out), that mailbox's build is cancelled and its
+ * index destroyed (spec section 11), whether or not a mail view (`LocalIndexLifecycle`) is still mounted to notice - after leaving Mail
+ * for Calendar, or in a host whose account switch unmounted the shell that opened it (`tauri-client`).
+ *
+ * **Swappable transport**: everything above is specific to this one implementation - the Worker/OPFS-backed
+ * default. Every function this module exports below (`initLocalIndex`, `searchLocal`, `destroyLocalIndex`, ...)
+ * is a thin delegator to whichever `LocalIndexTransport` (`localIndexTransport.ts`) is "current," which defaults
+ * to `workerLocalIndexTransport` - this file's own implementation, wrapped - and can be swapped once, at startup,
+ * via `setLocalIndexTransport()`. A host app with a different storage backend (no Worker, no OPFS, no WASM at
+ * all - `tauri-client`'s native SQLCipher/`rusqlite` index) installs its own transport there; every call site
+ * that already goes through this file's exports (`searchTier2.ts`, `LocalIndexLifecycle.tsx`,
+ * `localIndexBuilder.ts`, and the rest) then runs against that backend instead, unmodified. The three
+ * module-level constants below (`SIGN_OUT_CHANNEL`, `PENDING_DELETIONS_KEY`, `DESTROY_ALL_TIMEOUT_MS`) remain
+ * plain exports, not part of the swappable interface - they name this one transport's own cross-tab/localStorage
+ * mechanics, which a different transport has no reason to share.
+ */
+import { subscribeKeySession } from "../../../lib/crypto/keySession.js";
 import { removeLocalIndexDirectories, removeLocalIndexDirectory } from "./localIndexStorage.js";
+import { forgetAllZeroAccessSync, forgetZeroAccessSync, forgetZeroAccessSyncExcept } from "./zeroAccessSyncState.js";
 let worker;
 let nextRequestId = 1;
 const pending = new Map();
@@ -26,6 +73,11 @@ function getWorker() {
         const created = new Worker(new URL("./localIndexWorker.js", import.meta.url), { type: "module" });
         worker = created;
         created.addEventListener("message", (event) => {
+            if ("type" in event.data) {
+                // The Worker discarded a corrupted index: what sync passes remembered of it goes too, or a rebuilt one would skip it.
+                forgetZeroAccessSync(event.data.mailboxUid);
+                return;
+            }
             const entry = pending.get(event.data.id);
             if (!entry) {
                 return;
@@ -174,11 +226,17 @@ async function removeLocalEntityImpl(mailboxUid, entityUid) {
 }
 /** 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 `removeLocalEntityImpl()`. */
-async function moveLocalEntityImpl(mailboxUid, entityUid, folderUid) {
+async function moveLocalEntityImpl(mailboxUid, entityUid, folderUid, entityVersion, flags) {
     if (!initializedMailboxes.has(mailboxUid)) {
         return;
     }
-    await call("moveEntity", { mailboxUid, entityUid, folderUid }).catch(() => undefined);
+    await call("moveEntity", {
+        mailboxUid,
+        entityUid,
+        folderUid,
+        ...(entityVersion !== undefined ? { entityVersion } : {}),
+        ...(flags !== undefined ? { flags } : {}),
+    }).catch(() => undefined);
 }
 function getIndexedVersionsImpl(mailboxUid, entityUids) {
     return call("indexedVersions", { mailboxUid, entityUids });
@@ -204,6 +262,9 @@ function setLocalIndexBuildingImpl(mailboxUid, building, completion) {
  * 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. */
 async function destroyLocalIndexImpl(mailboxUid) {
+    // What zero-access sync passes remembered of it goes with it, here too, so a host wrapper destroying mailboxes one by one through this
+    // transport (`tauri-client`'s scoped sign-out) forgets theirs.
+    forgetZeroAccessSync(mailboxUid);
     updatePendingDeletions((current) => current.add(mailboxUid));
     try {
         await call("destroy", { mailboxUid, generation: nextLocalIndexGenerationImpl() });
@@ -231,6 +292,9 @@ export const DESTROY_ALL_TIMEOUT_MS = 3000;
  */
 async function destroyAllLocalIndexesImpl(timeoutMs) {
     signedOut = true;
+    // Here, in the transport, as for prune: a host wrapper that destroys only some accounts' indexes (`tauri-client`, several accounts in
+    // one origin) keeps the other accounts' sync state too.
+    forgetAllZeroAccessSync();
     writePendingDeletions([ALL_INDEXES]);
     try {
         getChannel()?.postMessage({ type: "sign-out" });
@@ -263,9 +327,13 @@ async function destroyAllLocalIndexesImpl(timeoutMs) {
     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. */
+ * user who signed in on this device without signing out - and what zero-access sync passes remembered of them, as on a destroy. Both
+ * here, in the transport, so a host's wrapper that keeps other indexes (`tauri-client`, several accounts in one origin) keeps their sync
+ * state too. Never rejects. */
 async function pruneInaccessibleLocalIndexesImpl(accessibleMailboxUids) {
-    await removeLocalIndexDirectories(new Set(accessibleMailboxUids)).catch(() => undefined);
+    const accessible = new Set(accessibleMailboxUids);
+    forgetZeroAccessSyncExcept(accessible);
+    await removeLocalIndexDirectories(accessible).catch(() => undefined);
 }
 /**
  * This file's own Worker/OPFS-backed implementation, wrapping the functions above - see this module's own doc
@@ -305,8 +373,46 @@ export function setLocalIndexTransport(transport) {
 export function nextLocalIndexGeneration() {
     return currentTransport.nextGeneration();
 }
-export function initLocalIndex(params) {
-    return currentTransport.init(params);
+/** Every mailbox whose index `initLocalIndex()` opened, through whichever transport, and that wasn't destroyed since. */
+const openedMailboxes = new Set();
+/** How many times each mailbox's keys were destroyed this page load - an `initLocalIndex()` that a lock overtook destroys what it opened. */
+const lockCounts = new Map();
+let watchingLocks = false;
+/** Cancels `mailboxUid`'s build and destroys its index, as `LocalIndexLifecycle` does on a lock. Never rejects. */
+function destroyOnLock(mailboxUid) {
+    // Stop a build pass still running with the destroyed keys; the destroy also makes the Worker reject anything that pass still sends.
+    // Loaded lazily (it imports this module, and carries the message security code).
+    import("./localIndexBuilder.js")
+        .then(({ cancelLocalIndexBuild }) => cancelLocalIndexBuild(mailboxUid))
+        .catch(() => undefined);
+    void destroyLocalIndex(mailboxUid);
+}
+/** Subscribes, once, to key destruction: see this module's doc comment ("A lock destroys the index"). */
+function watchKeyLocks() {
+    if (watchingLocks) {
+        return;
+    }
+    watchingLocks = true;
+    subscribeKeySession(({ mailboxUid, state }) => {
+        if (state !== "locked") {
+            return;
+        }
+        lockCounts.set(mailboxUid, (lockCounts.get(mailboxUid) ?? 0) + 1);
+        if (openedMailboxes.has(mailboxUid)) {
+            destroyOnLock(mailboxUid);
+        }
+    });
+}
+export async function initLocalIndex(params) {
+    watchKeyLocks();
+    const locks = lockCounts.get(params.mailboxUid) ?? 0;
+    await currentTransport.init(params);
+    if ((lockCounts.get(params.mailboxUid) ?? 0) !== locks) {
+        // Its keys were destroyed while it opened: it never counted as open, so the lock's own destroy didn't reach it.
+        destroyOnLock(params.mailboxUid);
+        return;
+    }
+    openedMailboxes.add(params.mailboxUid);
 }
 export function indexLocalEntities(mailboxUid, entities, generation) {
     return currentTransport.indexEntities(mailboxUid, entities, generation);
@@ -317,9 +423,15 @@ export function removeLocalEntity(mailboxUid, entityUid) {
     return currentTransport.removeEntity(mailboxUid, entityUid);
 }
 /** 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 function moveLocalEntity(mailboxUid, entityUid, folderUid) {
-    return currentTransport.moveEntity(mailboxUid, entityUid, folderUid);
+ * local searches stay correct. Same no-op/never-rejects rules as `removeLocalEntity()`. `flags` (`,flag,flag,`) sets the row's flags
+ * too - a zero-access row's, which nothing else records. */
+export function moveLocalEntity(mailboxUid, entityUid, folderUid, entityVersion, flags) {
+    if (flags !== undefined) {
+        return currentTransport.moveEntity(mailboxUid, entityUid, folderUid, entityVersion, flags);
+    }
+    return entityVersion !== undefined
+        ? currentTransport.moveEntity(mailboxUid, entityUid, folderUid, entityVersion)
+        : currentTransport.moveEntity(mailboxUid, entityUid, folderUid);
 }
 export function getIndexedVersions(mailboxUid, entityUids) {
     return currentTransport.indexedVersions(mailboxUid, entityUids);
@@ -344,17 +456,23 @@ export function setLocalIndexBuilding(mailboxUid, building, completion = { compl
  * resolves `false` when the index could not be removed - see the current transport's own doc comment for what
  * that means for it (the Worker transport also logs why, and retries on the next page load). */
 export function destroyLocalIndex(mailboxUid) {
+    openedMailboxes.delete(mailboxUid);
+    // What zero-access sync passes remembered importing into it goes with it, whatever the transport.
+    forgetZeroAccessSync(mailboxUid);
     return currentTransport.destroy(mailboxUid);
 }
 /** Destroys **every** local index this transport knows of - not just the mailboxes this session opened - e.g.
  * on sign-out. Never rejects. Resolves `true` only if everything was removed within `timeoutMs`. */
 export function destroyAllLocalIndexes(timeoutMs = DESTROY_ALL_TIMEOUT_MS) {
+    // `openedMailboxes` is left as it is: a host transport may keep other accounts' indexes open (`tauri-client`), and a lock of one
+    // already destroyed finds nothing to close.
     return currentTransport.destroyAll(timeoutMs);
 }
 /** 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. */
+ * user who signed in on this device without signing out. The transport decides what goes, zero-access sync state included (the
+ * Worker transport forgets it with the index; a host wrapper that skips the prune keeps both). Never rejects. */
 export function pruneInaccessibleLocalIndexes(accessibleMailboxUids) {
-    return currentTransport.pruneInaccessible(accessibleMailboxUids);
+    return currentTransport.pruneInaccessible(new Set(accessibleMailboxUids));
 }
 /** Retries every deletion an earlier session couldn't finish. Never rejects. */
 export function retryPendingLocalIndexDeletions() {

package/dist/apps/shared/search/localIndexSchema.d.ts

@@ -59,10 +59,22 @@ export interface LocalIndexEntity {
      * folder) - lets a rebuild skip re-fetching/decrypting anything already indexed unchanged. */
     entityVersion?: string;
 }
+/** The change marker a message's row stores (`LocalIndexEntity.entityVersion`): a new server `version` (flags, content) or a folder move
+ * both invalidate the indexed copy. */
+export declare function messageRowVersion(message: {
+    version: number;
+    folderUid: string;
+}): string;
+/** A message's set flags as a row stores them. Leading/trailing comma so `flags LIKE '%,x,%'` (`buildSearchPredicates()`) matches
+ * correctly even for the first/last flag in the list. */
+export declare function messageRowFlags(message: {
+    flags: object;
+}): 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 declare const UPSERT_ENTITY_SQL = "\nINSERT 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)\nVALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\nON CONFLICT(entity_uid) DO UPDATE SET\n    folder_uid = excluded.folder_uid, date_for_sort = excluded.date_for_sort, participants = excluded.participants,\n    flags = excluded.flags, has_attachments = excluded.has_attachments, subject = excluded.subject,\n    body = excluded.body, attachment_text = excluded.attachment_text, byte_size = excluded.byte_size,\n    entity_version = excluded.entity_version\n";
+ * `entities_au` trigger keeps `entities_fts` in sync automatically. A row written without a folder, flags or version (a zero-access
+ * document, which carries none) keeps the ones recorded: re-importing it must not make it look unrecorded again. */
+export declare const UPSERT_ENTITY_SQL = "\nINSERT 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)\nVALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\nON CONFLICT(entity_uid) DO UPDATE SET\n    folder_uid = COALESCE(excluded.folder_uid, entities.folder_uid), date_for_sort = excluded.date_for_sort, participants = excluded.participants,\n    flags = CASE WHEN excluded.flags = '' THEN entities.flags ELSE excluded.flags END, has_attachments = excluded.has_attachments, subject = excluded.subject,\n    body = excluded.body, attachment_text = excluded.attachment_text, byte_size = excluded.byte_size,\n    entity_version = COALESCE(excluded.entity_version, entities.entity_version)\n";
 /** 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 declare function entityBindValues(entity: LocalIndexEntity): (string | number)[];

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

@@ -84,17 +84,31 @@ END;
  * 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";
+/** The change marker a message's row stores (`LocalIndexEntity.entityVersion`): a new server `version` (flags, content) or a folder move
+ * both invalidate the indexed copy. */
+export function messageRowVersion(message) {
+    return `${message.version}:${message.folderUid}`;
+}
+/** A message's set flags as a row stores them. Leading/trailing comma so `flags LIKE '%,x,%'` (`buildSearchPredicates()`) matches
+ * correctly even for the first/last flag in the list. */
+export function messageRowFlags(message) {
+    const set = Object.entries(message.flags)
+        .filter(([, value]) => value)
+        .map(([key]) => key);
+    return `,${set.join(",")},`;
+}
 /** `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. */
+ * `entities_au` trigger keeps `entities_fts` in sync automatically. A row written without a folder, flags or version (a zero-access
+ * document, which carries none) keeps the ones recorded: re-importing it must not make it look unrecorded again. */
 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,
+    folder_uid = COALESCE(excluded.folder_uid, entities.folder_uid), date_for_sort = excluded.date_for_sort, participants = excluded.participants,
+    flags = CASE WHEN excluded.flags = '' THEN entities.flags ELSE excluded.flags END, 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
+    entity_version = COALESCE(excluded.entity_version, entities.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. */

package/dist/apps/shared/search/localIndexTransport.d.ts

@@ -52,7 +52,9 @@ export interface LocalIndexTransport {
     /** Drops one indexed entity. */
     removeEntity(mailboxUid: string, entityUid: string): Promise<void>;
     /** Re-points one indexed entity at its new folder. */
-    moveEntity(mailboxUid: string, entityUid: string, folderUid: string): Promise<void>;
+    /** `entityVersion`, when given, is recorded with the folder (a transport that can't record it leaves the row's version cleared), and
+     * `flags` replaces the row's flags (a transport that can't record them leaves them as they are). */
+    moveEntity(mailboxUid: string, entityUid: string, folderUid: string, entityVersion?: string, flags?: string): Promise<void>;
     /** The indexed version marker (`Message.version` + folder) currently stored for each of the given entity uids. */
     indexedVersions(mailboxUid: string, entityUids: string[]): Promise<Record<string, string>>;
     /** Removes indexed rows outside `keepEntityUids` (and `since`/`options.folderUids`'s own scope). Returns how many rows were pruned. */
@@ -70,7 +72,9 @@ export interface LocalIndexTransport {
     /** Destroys every index this transport knows of, e.g. on sign-out. Never rejects; resolves `true` only if
      * everything was removed within `timeoutMs`. */
     destroyAll(timeoutMs: number): Promise<boolean>;
-    /** Removes indexes for mailboxes outside `accessibleMailboxUids`. Never rejects. */
+    /** Removes indexes for mailboxes outside `accessibleMailboxUids`, and what zero-access sync remembered of each one it removes
+     * (`forgetZeroAccessSyncExcept()`; `pruneInaccessibleLocalIndexes()` leaves that to the transport, so a host can keep both). Never
+     * rejects. */
     pruneInaccessible(accessibleMailboxUids: Iterable<string>): Promise<void>;
     /** Retries any deletion an earlier session couldn't finish. Never rejects. */
     retryPendingDeletions(): Promise<void>;

package/dist/apps/shared/search/localIndexWorker.d.ts

@@ -17,6 +17,11 @@ export type LocalIndexResponse = {
     ok: false;
     error: string;
 };
+/** Posted unprompted when a corrupted index was discarded (`resetCorruptedConnection()`), so the main thread forgets what it remembered of it. */
+export interface LocalIndexResetNotice {
+    type: "reset";
+    mailboxUid: string;
+}
 /**
  * Carried by every call a build pass makes (`init`, `setWindow`, `setBuilding`, `indexEntities`,
  * `pruneEntities`). Generations come from one monotonic counter on the main thread
@@ -62,6 +67,10 @@ export interface MoveEntityParams {
     mailboxUid: string;
     entityUid: string;
     folderUid: string;
+    /** Recorded as the row's `entity_version`; cleared (the row then counts as changed) when absent. */
+    entityVersion?: string;
+    /** The row's flags (`,flag,flag,`), set too when given - a zero-access row, whose imported document carries none. */
+    flags?: string;
 }
 export interface IndexedVersionsParams {
     mailboxUid: string;
@@ -141,5 +150,7 @@ export declare class StaleGenerationError extends Error {
 export declare class LocalIndexBusyError extends Error {
     constructor(mailboxUid: string);
 }
+/** How many uids one `indexedVersions()` statement binds. */
+export declare const INDEXED_VERSIONS_BATCH = 500;
 /** Routes one request to its handler, inside the owning mailbox's serial queue. Exported for tests. */
 export declare function handleRequest(method: LocalIndexRequest["method"], params: unknown): Promise<unknown>;

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

@@ -324,6 +324,7 @@ async function withCurrentConnection(params, operation) {
 async function resetCorruptedConnection(mailboxUid, connection) {
     console.warn(`localIndexWorker: local search index for mailbox ${mailboxUid} is corrupted; discarding and rebuilding.`);
     connections.delete(mailboxUid);
+    self.postMessage({ type: "reset", mailboxUid });
     await closeRawConnection(connection).catch(() => undefined);
     try {
         await removeLocalIndexDirectory(mailboxUid);
@@ -428,27 +429,33 @@ async function removeEntity(connection, entityUid) {
     }
 }
 /** 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]);
+ * `entity_version` so the next build pass re-validates the row against the server. Sets its flags too when `flags` is given. */
+async function moveEntity(connection, entityUid, folderUid, entityVersion, flags) {
+    const [sql, values] = flags === undefined
+        ? ["UPDATE entities SET folder_uid = ?, entity_version = ? WHERE entity_uid = ?", [folderUid, entityVersion ?? null, entityUid]]
+        : ["UPDATE entities SET folder_uid = ?, entity_version = ?, flags = ? WHERE entity_uid = ?", [folderUid, entityVersion ?? null, flags, entityUid]];
+    for await (const stmt of connection.sqlite3.statements(connection.db, sql)) {
+        connection.sqlite3.bind_collection(stmt, values);
         await connection.sqlite3.step(stmt);
     }
 }
+/** How many uids one `indexedVersions()` statement binds. */
+export const INDEXED_VERSIONS_BATCH = 500;
 /** `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;
+    // In statements of at most `INDEXED_VERSIONS_BATCH` uids: SQLite refuses one binding more than its variable limit (32766 here).
+    for (let i = 0; i < entityUids.length; i += INDEXED_VERSIONS_BATCH) {
+        const batch = entityUids.slice(i, i + INDEXED_VERSIONS_BATCH);
+        const placeholders = batch.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, batch);
+            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;
+                }
             }
         }
     }
@@ -636,7 +643,7 @@ export async function handleRequest(method, params) {
         }
         case "moveEntity": {
             const p = params;
-            return runExclusive(p.mailboxUid, () => withConnection(p.mailboxUid, (c) => moveEntity(c, p.entityUid, p.folderUid)));
+            return runExclusive(p.mailboxUid, () => withConnection(p.mailboxUid, (c) => moveEntity(c, p.entityUid, p.folderUid, p.entityVersion, p.flags)));
         }
         case "indexedVersions": {
             const p = params;

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

@@ -1,3 +1,4 @@
+import { KeysLockedError } from "../../../lib/crypto/masterKey.js";
 import { deriveLocalIndexKey } from "./localIndexKey.js";
 import { getLocalCoverage, initLocalIndex, searchLocal } from "./localIndexRpcClient.js";
 /** Ensures this mailbox's local index connection is open before it's queried - idempotent
@@ -6,6 +7,10 @@ import { getLocalCoverage, initLocalIndex, searchLocal } from "./localIndexRpcCl
  * wins, and the other is a cheap no-op. */
 async function ensureInitialized(mailboxUid, unlocked) {
     const indexKey = await deriveLocalIndexKey(unlocked.masterKey, mailboxUid);
+    // Locked during the derive, which still succeeds: open nothing with the destroyed keys (the lock's own destroy found nothing open).
+    if (unlocked.destroyed) {
+        throw new KeysLockedError();
+    }
     await initLocalIndex({ mailboxUid, indexKey });
 }
 /** How long a Tier 2 search may run before this function gives up on it and degrades to "no local results" -

package/dist/apps/shared/search/zeroAccessIndexSync.d.ts

@@ -0,0 +1,102 @@
+import type { UnlockedKeys } from "../../../lib/crypto/keySession.js";
+import { type IndexWeekEntries, type SegmentManifest, type ZeroAccessIndexDocument } from "../../../lib/search/zeroAccessIndexApi.js";
+import { type ApiClient } from "../../../lib/util/api.js";
+import { type ClientPlatform } from "../../../lib/util/clientPlatform.js";
+import { type LocalIndexEntity } from "./localIndexSchema.js";
+import { forgetZeroAccessSync } from "./zeroAccessSyncState.js";
+export { forgetZeroAccessSync };
+/** The segment format this client writes and reads. */
+export declare const SEGMENT_SCHEMA_VERSION = 1;
+/** How far before its last pass the live tail asks again, so an entry committed late is never skipped. */
+export declare const TAIL_OVERLAP_MS: number;
+/** At most this many weeks are compacted per pass, so a large backlog is worked through over several passes. */
+export declare const MAX_COMPACTIONS_PER_PASS = 4;
+/** How long after a week's `compactableAt` each platform takes it (restapi `specs/search.md` §8 *Who compacts*): a computer first,
+ * a phone only when nothing else has for a day. */
+export declare const COMPACTION_DELAY_MS: Record<ClientPlatform, number>;
+/** A mobile client declines a week whose pending entries and current segment together are larger than this. */
+export declare const MOBILE_COMPACTION_MAX_BYTES: number;
+/**
+ * Whether this client should compact `week` now: it is compactable, has pending entries, and this platform's delay after its
+ * `compactableAt` has passed. A mobile client also declines on a cellular or data-saver connection, and a week larger than
+ * `MOBILE_COMPACTION_MAX_BYTES` with `segmentBytes` (its current segment's size) - or of unknown size, or from a server that
+ * doesn't say when it became compactable.
+ */
+export declare function shouldCompact(week: IndexWeekEntries, segmentBytes: number, platform?: ClientPlatform, now?: number, constrained?: boolean): boolean;
+/** How many times `uploadClientDocuments()` re-reads a week's client segment after another device replaced it first. */
+export declare const CLIENT_UPLOAD_ATTEMPTS = 3;
+/** What a pass did, for the caller's logging and tests. */
+export interface ZeroAccessSyncResult {
+    segmentsImported: number;
+    /** Client segments (end-to-end mail other devices indexed) imported. */
+    clientSegmentsImported: number;
+    entriesImported: number;
+    weeksCompacted: number;
+    /** Entries or segments that wouldn't decrypt with this device's keys (a key it doesn't have) - left as they are. */
+    unreadable: number;
+}
+/** What the builder (`localIndexBuilder.ts`) knows of a zero-access message from the message list - none of it is in its document. */
+export interface ZeroAccessRowMetadata {
+    folderUid: string;
+    entityVersion: string;
+    /** `,flag,flag,` */
+    flags: string;
+}
+/** At most this many messages' metadata are kept per mailbox for rows not imported yet; the oldest go first. */
+export declare const MAX_REMEMBERED_METADATA = 50000;
+/**
+ * Remembers zero-access message `messageUid`'s folder, version and flags for when its row is imported: the builder records them on the row
+ * as it walks, which does nothing for a row that isn't there yet (the index started empty - a new device, or after a lock - and this sync
+ * imports the rows after the build).
+ */
+export declare function rememberZeroAccessMetadata(mailboxUid: string, messageUid: string, metadata: ZeroAccessRowMetadata): void;
+/** At most this many live-tail rows a pass looks up (`recordTailMetadata()`); the rest get theirs from the next build pass. */
+export declare const MAX_TAIL_LOOKUPS = 500;
+/** A document as a row of the local index. Folder and flags aren't in the document - the builder records them (`localIndexBuilder.ts`,
+ * here through `rememberZeroAccessMetadata()` when the row came later; a live-tail row nothing recorded is looked up,
+ * `recordTailMetadata()`), and the upsert keeps what is already there. */
+export declare function documentEntity(mailboxUid: string, doc: ZeroAccessIndexDocument): LocalIndexEntity;
+/** One document of a client segment: a local index row of an end-to-end message, as the device that decrypted it built it. */
+export interface ClientIndexDocument {
+    v: 1;
+    messageUid: string;
+    folderUid?: string;
+    /** ISO 8601. */
+    dateForSort: string;
+    participants: string;
+    flags: string;
+    hasAttachments: boolean;
+    subject?: string;
+    body?: string;
+    attachmentText?: string;
+    /** The message's version when it was decrypted (`localIndexBuilder.ts`'s `versionOf()`). */
+    entityVersion?: string;
+}
+/** A local index row as a client segment document. */
+export declare function clientDocument(entity: LocalIndexEntity): ClientIndexDocument;
+/** A client segment document as a row of the local index. */
+export declare function clientDocumentEntity(mailboxUid: string, doc: ClientIndexDocument): LocalIndexEntity;
+/** The ISO 8601 week (UTC) of `date`, as `YYYY-Www` - the week a message's segment is filed under (restapi's `isoWeekId()`). */
+export declare function isoWeekId(date: Date): string;
+/**
+ * Imports the client segments of `mailboxUid` (end-to-end mail indexed by another device - see this module's comment) not yet imported in
+ * their current generation, newest week first: how many. `manifest` saves reading it again; `generation` is the calling build pass's (see
+ * `GenerationParams`). Segments this device can't open are skipped.
+ */
+export declare function importClientSegments(mailboxUid: string, unlocked: UnlockedKeys, client?: ApiClient, { manifest, generation }?: {
+    manifest?: SegmentManifest;
+    generation?: number;
+}): Promise<number>;
+/**
+ * Uploads end-to-end messages this device just decrypted and indexed (`entities`) to `mailboxUid`'s client segments, one per ISO week of
+ * `dateForSort`, each merged by message into the week's current segment and sealed to the active zero-access key: how many weeks were
+ * written. A week whose current segment this device can't read is left alone (merging would drop what is in it), as is one that already
+ * holds every document at the same version. Another device replacing a week first (`409`) is retried with its generation, up to
+ * `CLIENT_UPLOAD_ATTEMPTS` times. Does nothing without unlocked zero-access keys.
+ */
+export declare function uploadClientDocuments(mailboxUid: string, unlocked: UnlockedKeys, entities: LocalIndexEntity[], client?: ApiClient): Promise<number>;
+/**
+ * One sync pass for `mailboxUid` (see this module's comment). Does nothing without unlocked zero-access keys. Rejects when the manifest
+ * can't be read; any later failure ends the pass early with what it had done so far remembered.
+ */
+export declare function syncZeroAccessIndex(mailboxUid: string, unlocked: UnlockedKeys, client?: ApiClient): Promise<ZeroAccessSyncResult>;