@rapidmx/web-client 0.4.0 → 0.6.0

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

@@ -0,0 +1,101 @@
+/**
+ * `EncryptingVFS` - the Tier 2 local index's at-rest encryption layer (`specs/search.md` §11
+ * "Persistence and protection", §13 "Encryption at Rest": "no official SQLCipher WASM build exists...
+ * encryption at rest requires a custom VFS that encrypts pages before they reach OPFS").
+ *
+ * Wraps (composes, does not subclass - `AccessHandlePoolVFS`'s own file-table state is private `#`
+ * fields) an `AccessHandlePoolVFS` instance and delegates every `FacadeVFS` method straight through
+ * except `jRead`/`jWrite`, which it intercepts to decrypt/encrypt pages.
+ *
+ * ## Page layout
+ *
+ * SQLite is opened with a fixed 4096-byte page size (`PRAGMA page_size=4096` - set by
+ * `localIndexWorker.ts` before the first write, since SQLite fixes a database's page size on creation).
+ * Each *logical* 4096-byte page is stored *physically* as `nonce(12) || AES-256-GCM(ciphertext(4096) ||
+ * tag(16))` = 4124 bytes, at a remapped offset (`physicalOffset(page) = page * 4124`). This block size
+ * is this class's own fixed constant, independent of whatever byte range a given `jRead`/`jWrite` call
+ * actually requests - reads/writes are handled generically over whichever physical blocks the requested
+ * logical range overlaps (including a read-modify-write for a sub-block write), not by assuming SQLite
+ * only ever issues page-aligned, page-sized I/O. That assumption holds for the *main database file* once
+ * its page size is fixed, but handling the general case costs little and removes the need to rely on it.
+ *
+ * **A fresh random nonce is generated on every write, never reused or derived from a counter** - the
+ * simplest way to make an AES-GCM (key, nonce) pair never repeat across different plaintexts, which is
+ * the one hard requirement GCM has. The nonce travels with its block, so decryption never needs any
+ * external state (a lost/corrupted counter, a persisted salt) to reconstruct it.
+ *
+ * **AAD binds each block to its logical filename and page index** (not just its own ciphertext) - GCM
+ * authenticates a block's own content but not its *position*; without this, an attacker able to write
+ * directly into this origin's OPFS storage (outside this codebase's own threat model per spec §4, which
+ * excludes a compromised client, but cheap to close off anyway) could silently swap two blocks and each
+ * would still decrypt "successfully" on its own, corrupting data instead of failing loudly. Binding to
+ * position turns a swap into a caught decryption failure - see `PageCorruptedError` below - the same
+ * "invalidate and rebuild" path a schema-version mismatch already takes (spec §11 "Invalidation").
+ *
+ * **No WAL, no rollback journal.** `localIndexWorker.ts` opens the database with `journal_mode=OFF`. A
+ * page cipher for the main database file is one encryption surface; WAL frames (their own header +
+ * checksum format) and rollback-journal records (their own, different record format) would each be a
+ * *second* one. This index has no durability requirement to justify that cost - spec §11 already
+ * requires discarding and rebuilding it on corruption, schema change, key rotation, or platform storage
+ * eviction, and eviction "MUST NOT block search" - so an interrupted write in the worst case is just
+ * caught by the same GCM-auth-failure -> rebuild path as any other corruption, never partial/torn state
+ * silently trusted.
+ *
+ * Every `jRead`/`jWrite` here is `async` (declared `async` specifically so `FacadeVFS.hasAsyncMethod()`
+ * detects it via `instanceof AsyncFunction` and awaits it) because `crypto.subtle.encrypt`/`decrypt` has
+ * no synchronous form in a browser - this is *why* `localIndexWorker.ts` boots the Asyncify SQLite build
+ * (`dist/wa-sqlite-async.mjs`), not the plain synchronous one `AccessHandlePoolVFS`'s own doc comment
+ * says it's designed for: that claim is about `AccessHandlePoolVFS`'s *own* methods (real synchronous
+ * OPFS access-handle calls), which stay synchronous and work fine wrapped underneath an async outer VFS
+ * on an Asyncify build - the build choice is driven by this class's needs, not the inner VFS's.
+ */
+import { FacadeVFS } from "@journeyapps/wa-sqlite/src/FacadeVFS.js";
+export { PageCorruptedError } from "./localIndexBlockCipher.js";
+export declare class EncryptingVFS extends FacadeVFS {
+    #private;
+    private constructor();
+    /** `rawKey` MUST be exactly 32 bytes (AES-256) - see `localIndexKey.ts`'s `deriveLocalIndexKey()`,
+     * the only intended source of this value. */
+    static create(name: string, module: unknown, rawKey: Uint8Array): Promise<EncryptingVFS>;
+    /**
+     * Releases every pooled OPFS sync access handle `AccessHandlePoolVFS` opened and holds open for its
+     * entire lifetime (not per SQLite-file-open/close - `jOpen`/`jClose` above only associate/disassociate
+     * a SQLite fileId with an already-open handle, they never open or close the handles themselves). MUST
+     * be called before creating another VFS instance against the same OPFS pool `name` - confirmed by
+     * direct reproduction: skipping this and calling `create()` again with the same `name` throws
+     * "Access Handles cannot be created if there is another open Access Handle," since the previous
+     * instance's handles are still live. `localIndexWorker.ts` calls this alongside `sqlite3.close(db)`
+     * (which closes the SQLite *connection*, a separate, shorter-lived thing from the VFS itself) whenever
+     * it tears down a mailbox's connection - on `destroy()` and in `selfTest()`'s own close/reopen check.
+     */
+    close(): void | Promise<void>;
+    jOpen(filename: string | null, pFile: number, flags: number, pOutFlags: DataView): number | Promise<number>;
+    jClose(pFile: number): number | Promise<number>;
+    jDelete(filename: string, syncDir: number): number | Promise<number>;
+    jAccess(filename: string, flags: number, pResOut: DataView): number | Promise<number>;
+    jFullPathname(filename: string, zOut: Uint8Array): number | Promise<number>;
+    jSync(pFile: number, flags: number): number | Promise<number>;
+    jSectorSize(pFile: number): number;
+    jDeviceCharacteristics(pFile: number): number;
+    /** Logical file size = physical size scaled back down to the logical block size - the inner VFS's
+     * own `jFileSize` reports the *physical* (post-remap) byte count, which is always an exact multiple
+     * of `PHYSICAL_BLOCK_SIZE` since every write here always fills whole physical blocks. */
+    jFileSize(pFile: number, pSize64: DataView): Promise<number>;
+    /** `iSize` is a logical byte size - truncates to the smallest whole number of *physical* blocks that
+     * still covers it, so a partially-truncated trailing block is never left half-written. */
+    jTruncate(pFile: number, iSize: number): Promise<number>;
+    /** Set once any block has failed to decrypt/authenticate (or the inner VFS failed a read/write outright)
+     * - `localIndexWorker.ts` checks this after a failed SQLite call to tell real corruption (discard and
+     * rebuild, spec §11 "Invalidation") apart from an ordinary error such as a malformed FTS5 query. */
+    corruptionDetected: boolean;
+    /**
+     * `jRead`/`jWrite` MUST NOT throw: with the Asyncify build, an exception escaping an async VFS method
+     * never reaches the awaiting `sqlite3.*` call - it surfaces only as an unhandled rejection and the
+     * SQLite call hangs forever (confirmed by direct reproduction in node against the real wa-sqlite build).
+     * A thrown `PageCorruptedError` therefore used to wedge the whole connection instead of triggering a
+     * rebuild. Errors are converted to an I/O error return code here, which SQLite does propagate as a
+     * normal `SQLiteError`, and recorded on `corruptionDetected`.
+     */
+    jRead(pFile: number, pData: Uint8Array, iOffset: number): Promise<number>;
+    jWrite(pFile: number, pData: Uint8Array, iOffset: number): Promise<number>;
+}

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

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _EncryptingVFS_instances, _EncryptingVFS_inner, _EncryptingVFS_key, _EncryptingVFS_filenamesByFileId, _EncryptingVFS_readBlock, _EncryptingVFS_writeBlock;
+var _EncryptingVFS_instances, _EncryptingVFS_inner, _EncryptingVFS_key, _EncryptingVFS_filenamesByFileId, _EncryptingVFS_readBlock, _EncryptingVFS_writeBlock, _EncryptingVFS_jReadBlocks, _EncryptingVFS_jWriteBlocks;
 ///////////////////////////////////////////////////////////////////////////////
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
@@ -80,6 +80,10 @@ export class EncryptingVFS extends FacadeVFS {
          * open handle, never persisted - this map lets `jRead`/`jWrite` recover the stable filename an AAD
          * needs to bind to, from the ephemeral fileId SQLite actually passes them. */
         _EncryptingVFS_filenamesByFileId.set(this, new Map());
+        /** Set once any block has failed to decrypt/authenticate (or the inner VFS failed a read/write outright)
+         * - `localIndexWorker.ts` checks this after a failed SQLite call to tell real corruption (discard and
+         * rebuild, spec §11 "Invalidation") apart from an ordinary error such as a malformed FTS5 query. */
+        this.corruptionDetected = false;
         __classPrivateFieldSet(this, _EncryptingVFS_inner, inner, "f");
     }
     /** `rawKey` MUST be exactly 32 bytes (AES-256) - see `localIndexKey.ts`'s `deriveLocalIndexKey()`,
@@ -152,50 +156,31 @@ export class EncryptingVFS extends FacadeVFS {
         const blocks = Math.ceil(iSize / LOGICAL_BLOCK_SIZE);
         return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jTruncate(pFile, blocks * PHYSICAL_BLOCK_SIZE);
     }
+    /**
+     * `jRead`/`jWrite` MUST NOT throw: with the Asyncify build, an exception escaping an async VFS method
+     * never reaches the awaiting `sqlite3.*` call - it surfaces only as an unhandled rejection and the
+     * SQLite call hangs forever (confirmed by direct reproduction in node against the real wa-sqlite build).
+     * A thrown `PageCorruptedError` therefore used to wedge the whole connection instead of triggering a
+     * rebuild. Errors are converted to an I/O error return code here, which SQLite does propagate as a
+     * normal `SQLiteError`, and recorded on `corruptionDetected`.
+     */
     async jRead(pFile, pData, iOffset) {
-        const filename = __classPrivateFieldGet(this, _EncryptingVFS_filenamesByFileId, "f").get(pFile) ?? `(unknown:${pFile})`;
-        const startBlock = Math.floor(iOffset / LOGICAL_BLOCK_SIZE);
-        const endBlock = Math.floor((iOffset + pData.length - 1) / LOGICAL_BLOCK_SIZE);
-        let anyAbsent = false;
-        for (let block = startBlock; block <= endBlock; block++) {
-            const { plaintext, absent } = await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_readBlock).call(this, pFile, filename, block);
-            const blockStart = block * LOGICAL_BLOCK_SIZE;
-            const copyStart = Math.max(iOffset, blockStart);
-            const copyEnd = Math.min(iOffset + pData.length, blockStart + LOGICAL_BLOCK_SIZE);
-            pData.set(plaintext.subarray(copyStart - blockStart, copyEnd - blockStart), copyStart - iOffset);
-            // SQLITE_IOERR_SHORT_READ is how SQLite distinguishes "nothing here yet" from "here is real
-            // (possibly zero-filled) data," e.g. when probing whether a file exists at all - see
-            // #readBlock's own doc comment on why this is tracked explicitly, not inferred from content.
-            if (absent) {
-                anyAbsent = true;
-            }
+        try {
+            return await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_jReadBlocks).call(this, pFile, pData, iOffset);
+        }
+        catch {
+            this.corruptionDetected = true;
+            return VFS.SQLITE_IOERR_READ;
         }
-        return anyAbsent ? VFS.SQLITE_IOERR_SHORT_READ : VFS.SQLITE_OK;
     }
     async jWrite(pFile, pData, iOffset) {
-        const filename = __classPrivateFieldGet(this, _EncryptingVFS_filenamesByFileId, "f").get(pFile) ?? `(unknown:${pFile})`;
-        const startBlock = Math.floor(iOffset / LOGICAL_BLOCK_SIZE);
-        const endBlock = Math.floor((iOffset + pData.length - 1) / LOGICAL_BLOCK_SIZE);
-        for (let block = startBlock; block <= endBlock; block++) {
-            const blockStart = block * LOGICAL_BLOCK_SIZE;
-            const writeStart = Math.max(iOffset, blockStart);
-            const writeEnd = Math.min(iOffset + pData.length, blockStart + LOGICAL_BLOCK_SIZE);
-            // Whole-block write (the common case once SQLite's page size is fixed): no need to read the
-            // old block first. Anything narrower (a sub-page write, or this block only partially
-            // overlaps the requested range) needs the existing content as a base - a real
-            // read-modify-write - since the physical block is re-encrypted as a single AEAD unit.
-            const plaintext = writeStart === blockStart && writeEnd === blockStart + LOGICAL_BLOCK_SIZE
-                ? pData.subarray(writeStart - iOffset, writeEnd - iOffset)
-                : await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_readBlock).call(this, pFile, filename, block).then(({ plaintext: existing }) => {
-                    const merged = existing.slice();
-                    merged.set(pData.subarray(writeStart - iOffset, writeEnd - iOffset), writeStart - blockStart);
-                    return merged;
-                });
-            const rc = await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_writeBlock).call(this, pFile, filename, block, plaintext);
-            if (rc !== VFS.SQLITE_OK)
-                return rc;
+        try {
+            return await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_jWriteBlocks).call(this, pFile, pData, iOffset);
+        }
+        catch {
+            this.corruptionDetected = true;
+            return VFS.SQLITE_IOERR_WRITE;
         }
-        return VFS.SQLITE_OK;
     }
 }
 _EncryptingVFS_inner = new WeakMap(), _EncryptingVFS_key = new WeakMap(), _EncryptingVFS_filenamesByFileId = new WeakMap(), _EncryptingVFS_instances = new WeakSet(), _EncryptingVFS_readBlock = 
@@ -227,4 +212,47 @@ async function _EncryptingVFS_readBlock(pFile, filename, blockIndex) {
 }, _EncryptingVFS_writeBlock = async function _EncryptingVFS_writeBlock(pFile, filename, blockIndex, plaintext) {
     const physical = await encryptBlock(__classPrivateFieldGet(this, _EncryptingVFS_key, "f"), filename, blockIndex, plaintext);
     return __classPrivateFieldGet(this, _EncryptingVFS_inner, "f").jWrite(pFile, physical, blockIndex * PHYSICAL_BLOCK_SIZE);
+}, _EncryptingVFS_jReadBlocks = async function _EncryptingVFS_jReadBlocks(pFile, pData, iOffset) {
+    const filename = __classPrivateFieldGet(this, _EncryptingVFS_filenamesByFileId, "f").get(pFile) ?? `(unknown:${pFile})`;
+    const startBlock = Math.floor(iOffset / LOGICAL_BLOCK_SIZE);
+    const endBlock = Math.floor((iOffset + pData.length - 1) / LOGICAL_BLOCK_SIZE);
+    let anyAbsent = false;
+    for (let block = startBlock; block <= endBlock; block++) {
+        const { plaintext, absent } = await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_readBlock).call(this, pFile, filename, block);
+        const blockStart = block * LOGICAL_BLOCK_SIZE;
+        const copyStart = Math.max(iOffset, blockStart);
+        const copyEnd = Math.min(iOffset + pData.length, blockStart + LOGICAL_BLOCK_SIZE);
+        pData.set(plaintext.subarray(copyStart - blockStart, copyEnd - blockStart), copyStart - iOffset);
+        // SQLITE_IOERR_SHORT_READ is how SQLite distinguishes "nothing here yet" from "here is real
+        // (possibly zero-filled) data," e.g. when probing whether a file exists at all - see
+        // #readBlock's own doc comment on why this is tracked explicitly, not inferred from content.
+        if (absent) {
+            anyAbsent = true;
+        }
+    }
+    return anyAbsent ? VFS.SQLITE_IOERR_SHORT_READ : VFS.SQLITE_OK;
+}, _EncryptingVFS_jWriteBlocks = async function _EncryptingVFS_jWriteBlocks(pFile, pData, iOffset) {
+    const filename = __classPrivateFieldGet(this, _EncryptingVFS_filenamesByFileId, "f").get(pFile) ?? `(unknown:${pFile})`;
+    const startBlock = Math.floor(iOffset / LOGICAL_BLOCK_SIZE);
+    const endBlock = Math.floor((iOffset + pData.length - 1) / LOGICAL_BLOCK_SIZE);
+    for (let block = startBlock; block <= endBlock; block++) {
+        const blockStart = block * LOGICAL_BLOCK_SIZE;
+        const writeStart = Math.max(iOffset, blockStart);
+        const writeEnd = Math.min(iOffset + pData.length, blockStart + LOGICAL_BLOCK_SIZE);
+        // Whole-block write (the common case once SQLite's page size is fixed): no need to read the
+        // old block first. Anything narrower (a sub-page write, or this block only partially
+        // overlaps the requested range) needs the existing content as a base - a real
+        // read-modify-write - since the physical block is re-encrypted as a single AEAD unit.
+        const plaintext = writeStart === blockStart && writeEnd === blockStart + LOGICAL_BLOCK_SIZE
+            ? pData.subarray(writeStart - iOffset, writeEnd - iOffset)
+            : await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_readBlock).call(this, pFile, filename, block).then(({ plaintext: existing }) => {
+                const merged = existing.slice();
+                merged.set(pData.subarray(writeStart - iOffset, writeEnd - iOffset), writeStart - blockStart);
+                return merged;
+            });
+        const rc = await __classPrivateFieldGet(this, _EncryptingVFS_instances, "m", _EncryptingVFS_writeBlock).call(this, pFile, filename, block, plaintext);
+        if (rc !== VFS.SQLITE_OK)
+            return rc;
+    }
+    return VFS.SQLITE_OK;
 };

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

@@ -0,0 +1,145 @@
+import type { ParsedSearchQuery } from "@rapidmx/react-shared/search/queryGrammar.js";
+import { LocalIndexEntity } from "./localIndexSchema.js";
+/** One request sent from the main thread. `id` correlates the eventual response - `postMessage` has no
+ * native request/response pairing, so every RPC call carries its own id (see `localIndexRpcClient.ts`,
+ * the main-thread counterpart that generates/awaits these). */
+export interface LocalIndexRequest {
+    id: number;
+    method: "init" | "indexEntities" | "removeEntity" | "moveEntity" | "indexedVersions" | "pruneEntities" | "search" | "coverage" | "setWindow" | "setBuilding" | "destroy" | "destroyAll" | "selfTest" | "ping";
+    params?: unknown;
+}
+export type LocalIndexResponse = {
+    id: number;
+    ok: true;
+    result: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+/**
+ * Carried by every call a build pass makes (`init`, `setWindow`, `setBuilding`, `indexEntities`,
+ * `pruneEntities`). Generations come from one monotonic counter on the main thread
+ * (`localIndexRpcClient.ts`), shared with `destroy`/`destroyAll`: a call whose generation is older than the
+ * last destroy of its mailbox is rejected (`StaleGenerationError`), so a build started before a lock/sign-out
+ * can't recreate the index with its captured keys or write into a rebuild that started after it. Calls
+ * without a generation (search, coverage, in-session moves) are never rejected.
+ */
+export interface GenerationParams {
+    generation?: number;
+}
+export interface InitParams extends GenerationParams {
+    mailboxUid: string;
+    /** The mailbox's already-derived local-index key (`localIndexKey.ts`'s `deriveLocalIndexKey()`) -
+     * this Worker never touches the master key itself, only this one purpose-derived value, matching
+     * every other MK-derived-key boundary already established elsewhere in this codebase. */
+    indexKey: Uint8Array;
+}
+export interface IndexEntitiesParams extends GenerationParams {
+    mailboxUid: string;
+    entities: LocalIndexEntity[];
+}
+export interface IndexEntitiesResult {
+    /** `true` when this call's eviction pass had to delete anything to get back under the byte budget. */
+    budgetReached: boolean;
+    /** The eviction watermark after this call - see `WindowState.evictedBefore`. */
+    evictedBefore?: string;
+}
+export interface WindowState {
+    /** Set once the byte budget has forced an eviction: messages dated strictly before this were evicted (or
+     * would be, on insert), so a build pass neither re-fetches them nor walks past them. Cleared by
+     * `setWindow` once the index has comfortably shrunk back under budget (or the budget was raised). */
+    evictedBefore?: string;
+}
+export interface DestroyParams extends GenerationParams {
+    mailboxUid: string;
+}
+export interface RemoveEntityParams {
+    mailboxUid: string;
+    entityUid: string;
+}
+export interface MoveEntityParams {
+    mailboxUid: string;
+    entityUid: string;
+    folderUid: string;
+}
+export interface IndexedVersionsParams {
+    mailboxUid: string;
+    entityUids: string[];
+}
+export interface PruneEntitiesParams extends GenerationParams {
+    mailboxUid: string;
+    /** Every entity uid a build pass saw on the server. */
+    keepEntityUids: string[];
+    /** Only rows at or after this `date_for_sort` are candidates (the walk's own time floor - anything
+     * older was never re-listed, so its absence proves nothing). `undefined` means no floor. */
+    since?: string;
+    /** Only rows currently filed in one of these folders are candidates - folders whose listing was reliable
+     * for the whole walk. `undefined` means every folder. */
+    folderUids?: string[];
+}
+export interface SearchParams {
+    mailboxUid: string;
+    parsed: ParsedSearchQuery;
+    limit: number;
+    /** How many matches to skip before returning `limit` more - §8's composite pagination cursor's own
+     * "the local index position consumed so far" component, threaded straight through to SQL `OFFSET`.
+     * Defaults to `0` for a first page. */
+    offset?: number;
+}
+export interface LocalSearchHit {
+    entityUid: string;
+    /** Raw `bm25()` score - more negative is a better match, per SQLite's own convention. Normalized by
+     * `searchTier2.ts` (main thread) before merging (spec §7). */
+    score: number;
+    snippet?: string;
+}
+export interface LocalSearchPage {
+    hits: LocalSearchHit[];
+    /** `true` when at least one more match exists beyond this page - detected by fetching `limit + 1`
+     * rows and trimming the extra one, rather than a separate `COUNT(*)` query. */
+    hasMore: boolean;
+}
+export interface Coverage {
+    /** The oldest date the index is known to cover. While `complete`, every indexable message at least
+     * this recent is present; otherwise it is only the oldest row that happens to be present. `undefined`
+     * for an empty index. */
+    indexedFrom?: string;
+    indexedCount: number;
+    building: boolean;
+    /** `true` only once a build pass *in this connection's lifetime* has walked every mail folder all the
+     * way back to its time floor with no errors and no budget cut-off - reset whenever the index is opened,
+     * so a completion persisted by an earlier session never counts. Callers MUST NOT treat `indexedFrom` as
+     * a coverage guarantee (e.g. to narrow Tier 3) unless this is `true` and `building` is `false`. */
+    complete: boolean;
+    /** Only set while `complete`: the guarantee ends here. Nothing indexes mail that arrives after a pass
+     * started, so everything dated after this (ISO) is NOT covered and must still be searched elsewhere. */
+    indexedUntil?: string;
+}
+export interface SetWindowParams extends GenerationParams {
+    mailboxUid: string;
+    timeFloorMonths: number;
+    byteBudgetBytes: number;
+}
+export interface SetBuildingParams extends GenerationParams {
+    mailboxUid: string;
+    building: boolean;
+    /** Only meaningful with `building: false` - whether the pass that just ended walked everything. */
+    complete?: boolean;
+    /** Only meaningful with `complete: true` - the pass's time floor (ISO), or `undefined` for none. */
+    coveredFrom?: string;
+    /** Only meaningful with `complete: true` - when the pass started (ISO, minus a clock-skew margin). */
+    coveredUntil?: string;
+}
+/** Runs `task` after every previously queued task for `mailboxUid` has settled. Exported for tests. */
+export declare function runExclusive<T>(mailboxUid: string, task: () => Promise<T>): Promise<T>;
+/** Rejects a build-pass call issued before its mailbox's index was last destroyed. */
+export declare class StaleGenerationError extends Error {
+    constructor(mailboxUid: string);
+}
+/** Thrown by `init` when another tab already holds this mailbox's index open. */
+export declare class LocalIndexBusyError extends Error {
+    constructor(mailboxUid: string);
+}
+/** 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>;