@rapidmx/web-client 0.3.0 → 0.4.0

package/apps/shared/search/localIndexSchema.ts

@@ -0,0 +1,227 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The Tier 2 local index's SQLite schema (`specs/search.md` §13). One database per mailbox (see
+ * `localIndexWorker.ts`), holding both the FTS5 index and the metadata cache in the same store - the
+ * spec's own rationale for choosing SQLite over an in-memory JS index in the first place ("the index
+ * database also holds the decrypted metadata cache... so there is one local store rather than two").
+ *
+ * Bumping `SCHEMA_VERSION` is how a schema change invalidates every existing local index (§11
+ * "Invalidation... on schema version change") - `localIndexWorker.ts` compares it against `meta`'s
+ * stored value on open and discards+rebuilds on a mismatch, the same path a corruption/GCM-auth-failure
+ * takes.
+ */
+
+/** Bump whenever `CREATE_SCHEMA_SQL` changes in a way existing on-disk databases can't be reconciled
+ * with in place. */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * `entities` is the real row store (metadata + the plaintext content fields), `entities_fts` is an FTS5
+ * *external content* table over it (`content='entities'`) - the standard SQLite pattern for keeping one
+ * copy of the text instead of duplicating it into the FTS5 shadow tables, kept in sync via the three
+ * triggers below (SQLite's own documented pattern for external-content FTS5 tables; there is no
+ * "ON CONFLICT UPDATE re-index" primitive, so update is modeled as delete-then-reinsert into the FTS
+ * index specifically, not into `entities` itself).
+ *
+ * Column order in `entities_fts` (`subject, participants, body, attachment_text`) is load-bearing: every
+ * `bm25(entities_fts, 3.0, 2.0, 1.0, 1.0)` call elsewhere in this module family assumes that exact
+ * positional order, matching `searchScoring.ts`'s `SEARCH_FIELD_WEIGHTS` (`subject: 3, participants: 2,
+ * body: 1, attachmentText: 1`) so Tier 2's local ranking agrees with the Tier 1/Tier 3 re-scoring the
+ * spec requires for one consistent ordering across tiers (§7).
+ */
+export const CREATE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS meta (
+    key TEXT PRIMARY KEY,
+    value TEXT
+);
+
+CREATE TABLE IF NOT EXISTS entities (
+    rowid INTEGER PRIMARY KEY,
+    entity_type TEXT NOT NULL,
+    entity_uid TEXT NOT NULL UNIQUE,
+    mailbox_uid TEXT NOT NULL,
+    folder_uid TEXT,
+    date_for_sort TEXT NOT NULL,
+    participants TEXT,
+    flags TEXT,
+    has_attachments INTEGER NOT NULL DEFAULT 0,
+    subject TEXT,
+    body TEXT,
+    attachment_text TEXT,
+    byte_size INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_entities_date ON entities(date_for_sort);
+CREATE INDEX IF NOT EXISTS idx_entities_mailbox ON entities(mailbox_uid);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
+    subject, participants, body, attachment_text,
+    content='entities', content_rowid='rowid', tokenize='unicode61'
+);
+
+CREATE TRIGGER IF NOT EXISTS entities_ai AFTER INSERT ON entities BEGIN
+    INSERT INTO entities_fts(rowid, subject, participants, body, attachment_text)
+    VALUES (new.rowid, new.subject, new.participants, new.body, new.attachment_text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS entities_ad AFTER DELETE ON entities BEGIN
+    INSERT INTO entities_fts(entities_fts, rowid, subject, participants, body, attachment_text)
+    VALUES ('delete', old.rowid, old.subject, old.participants, old.body, old.attachment_text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS entities_au AFTER UPDATE ON entities BEGIN
+    INSERT INTO entities_fts(entities_fts, rowid, subject, participants, body, attachment_text)
+    VALUES ('delete', old.rowid, old.subject, old.participants, old.body, old.attachment_text);
+    INSERT INTO entities_fts(rowid, subject, participants, body, attachment_text)
+    VALUES (new.rowid, new.subject, new.participants, new.body, new.attachment_text);
+END;
+`;
+
+/** The exact `bm25()` weight arguments every ranked query against `entities_fts` MUST pass, in column
+ * order - see this module's own doc comment on why the order is load-bearing. Centralized here so a
+ * future column reorder can't silently desync a query building its own literal weight list. */
+export const BM25_WEIGHTS_SQL = "3.0, 2.0, 1.0, 1.0";
+
+/** 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;
+}
+
+/** `entity_uid` upsert - `ON CONFLICT` (SQLite's UPSERT syntax) rather than a separate delete-then-insert,
+ * so re-indexing an already-present message (a flag changed, a folder move) updates it in place and the
+ * `entities_au` trigger keeps `entities_fts` in sync automatically. */
+export const UPSERT_ENTITY_SQL = `
+INSERT INTO entities (entity_type, entity_uid, mailbox_uid, folder_uid, date_for_sort, participants, flags, has_attachments, subject, body, attachment_text, byte_size)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(entity_uid) DO UPDATE SET
+    folder_uid = excluded.folder_uid, date_for_sort = excluded.date_for_sort, participants = excluded.participants,
+    flags = excluded.flags, has_attachments = excluded.has_attachments, subject = excluded.subject,
+    body = excluded.body, attachment_text = excluded.attachment_text, byte_size = excluded.byte_size
+`;
+
+/** Bind values for `UPSERT_ENTITY_SQL`, in column order - kept alongside it so the two can never drift
+ * out of sync with each other. */
+export function entityBindValues(entity: 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,
+    ];
+}
+
+/** 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.
+    }
+}

package/apps/shared/search/localIndexVFS.ts

@@ -0,0 +1,235 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * `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";
+import { AccessHandlePoolVFS } from "@journeyapps/wa-sqlite/src/examples/AccessHandlePoolVFS.js";
+import * as VFS from "@journeyapps/wa-sqlite/src/VFS.js";
+import {
+    LOGICAL_BLOCK_SIZE,
+    PHYSICAL_BLOCK_SIZE,
+    PageCorruptedError,
+    decryptBlock,
+    encryptBlock,
+    importAesGcmKey,
+} from "./localIndexBlockCipher.js";
+
+export { PageCorruptedError } from "./localIndexBlockCipher.js";
+
+export class EncryptingVFS extends FacadeVFS {
+    #inner: AccessHandlePoolVFS;
+    #key: CryptoKey | undefined;
+    /** `jOpen`'s `filename` is stable across the life of a fileId; `fileId` itself is only valid for one
+     * 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. */
+    #filenamesByFileId = new Map<number, string>();
+
+    private constructor(name: string, module: unknown, inner: AccessHandlePoolVFS) {
+        super(name, module);
+        this.#inner = inner;
+    }
+
+    /** `rawKey` MUST be exactly 32 bytes (AES-256) - see `localIndexKey.ts`'s `deriveLocalIndexKey()`,
+     * the only intended source of this value. */
+    static async create(name: string, module: unknown, rawKey: Uint8Array): Promise<EncryptingVFS> {
+        const inner = await AccessHandlePoolVFS.create(name, module);
+        const vfs = new EncryptingVFS(name, module, inner);
+        vfs.#key = await importAesGcmKey(rawKey);
+        return vfs;
+    }
+
+    /**
+     * 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> {
+        return this.#inner.close();
+    }
+
+    // Every method below except jRead/jWrite is a pure passthrough to the inner (real storage) VFS -
+    // this class's only job is to sit in the read/write path.
+    jOpen(filename: string | null, pFile: number, flags: number, pOutFlags: DataView): number | Promise<number> {
+        const result = this.#inner.jOpen(filename, pFile, flags, pOutFlags);
+        this.#filenamesByFileId.set(pFile, filename ?? `(anon:${pFile})`);
+        return result;
+    }
+    jClose(pFile: number): number | Promise<number> {
+        this.#filenamesByFileId.delete(pFile);
+        return this.#inner.jClose(pFile);
+    }
+    jDelete(filename: string, syncDir: number): number | Promise<number> {
+        return this.#inner.jDelete(filename, syncDir);
+    }
+    jAccess(filename: string, flags: number, pResOut: DataView): number | Promise<number> {
+        return this.#inner.jAccess(filename, flags, pResOut);
+    }
+    jFullPathname(filename: string, zOut: Uint8Array): number | Promise<number> {
+        return this.#inner.jFullPathname(filename, zOut);
+    }
+    jSync(pFile: number, flags: number): number | Promise<number> {
+        return this.#inner.jSync(pFile, flags);
+    }
+    jSectorSize(pFile: number): number {
+        return LOGICAL_BLOCK_SIZE;
+    }
+    jDeviceCharacteristics(pFile: number): number {
+        return this.#inner.jDeviceCharacteristics(pFile);
+    }
+
+    /** 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. */
+    async jFileSize(pFile: number, pSize64: DataView): Promise<number> {
+        const buf = new DataView(new ArrayBuffer(8));
+        const rc = await this.#inner.jFileSize(pFile, buf);
+        if (rc !== VFS.SQLITE_OK) return rc;
+        const physicalSize = Number(buf.getBigInt64(0, true));
+        const logicalSize = Math.floor(physicalSize / PHYSICAL_BLOCK_SIZE) * LOGICAL_BLOCK_SIZE;
+        pSize64.setBigInt64(0, BigInt(logicalSize), true);
+        return VFS.SQLITE_OK;
+    }
+
+    /** `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. */
+    async jTruncate(pFile: number, iSize: number): Promise<number> {
+        const blocks = Math.ceil(iSize / LOGICAL_BLOCK_SIZE);
+        return this.#inner.jTruncate(pFile, blocks * PHYSICAL_BLOCK_SIZE);
+    }
+
+    /**
+     * Reads one physical block and decrypts it. `absent: true` means nothing has ever been written at
+     * this block (the inner VFS's own read came back short) - `plaintext` is a zero-filled logical block
+     * in that case, matching what SQLite expects for a region it has never written, and it is
+     * deliberately never handed to `crypto.subtle.decrypt()` at all (there aren't enough physical bytes
+     * present to contain a real nonce+tag).
+     *
+     * `absent` is determined *only* from the inner VFS's own return code, never inferred from whether the
+     * decrypted plaintext happens to be all-zero - a real, fully-written SQLite page is routinely
+     * all-zero (an unused/freelist page, or a page beyond a freshly created database's real content), so
+     * that content shape means nothing about whether the block is actually present.
+     */
+    async #readBlock(pFile: number, filename: string, blockIndex: number): Promise<{ plaintext: Uint8Array; absent: boolean }> {
+        const physical = new Uint8Array(PHYSICAL_BLOCK_SIZE);
+        const rc = await this.#inner.jRead(pFile, physical, blockIndex * PHYSICAL_BLOCK_SIZE);
+        if (rc === VFS.SQLITE_IOERR_SHORT_READ) {
+            // #writeBlock() never writes fewer than PHYSICAL_BLOCK_SIZE bytes at a time, so a short read
+            // here only ever means "this block was never written," not "partially written."
+            return { plaintext: new Uint8Array(LOGICAL_BLOCK_SIZE), absent: true };
+        }
+        if (rc !== VFS.SQLITE_OK) {
+            throw new PageCorruptedError(filename, blockIndex, new Error(`inner VFS read failed: rc=${rc}`));
+        }
+        const plaintext = await decryptBlock(this.#key!, filename, blockIndex, physical);
+        return { plaintext, absent: false };
+    }
+
+    async #writeBlock(pFile: number, filename: string, blockIndex: number, plaintext: Uint8Array): Promise<number> {
+        const physical = await encryptBlock(this.#key!, filename, blockIndex, plaintext);
+        return this.#inner.jWrite(pFile, physical, blockIndex * PHYSICAL_BLOCK_SIZE);
+    }
+
+    async jRead(pFile: number, pData: Uint8Array, iOffset: number): Promise<number> {
+        const filename = this.#filenamesByFileId.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 this.#readBlock(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;
+    }
+
+    async jWrite(pFile: number, pData: Uint8Array, iOffset: number): Promise<number> {
+        const filename = this.#filenamesByFileId.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 this.#readBlock(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 this.#writeBlock(pFile, filename, block, plaintext);
+            if (rc !== VFS.SQLITE_OK) return rc;
+        }
+        return VFS.SQLITE_OK;
+    }
+}