@syncular/client 0.15.44 → 0.15.45

package/README.md

@@ -5,7 +5,7 @@ browser platform bindings.
 
 ## Client-local FTS5 projections
 
-Generated schemas may attach `ftsIndexes` to a synced table (RFC 0005). The
+Generated schemas may attach `ftsIndexes` to a synced table. The
 client materializes each as a contentful local FTS5 table with a private stable
 source identity and insert/update/delete triggers. Existing visible rows are
 bulk-indexed on first creation; schema reset recreates the projection. The FTS
@@ -16,8 +16,7 @@ strings.
 
 ## Browser modes — there are exactly two
 
-**Persistent worker mode is THE mode** (REVISE Direction decision 2,
-2026-07-03). The whole client core — `SyncClient`, the fetch/WebSocket
+**Persistent worker mode is THE mode.** The whole client core — `SyncClient`, the fetch/WebSocket
 transports, and SQLite on the `opfs-sahpool` VFS — runs inside a Web
 Worker. The UI thread talks to it through a thin postMessage RPC:
 
@@ -34,7 +33,7 @@ import { createSyncClientHandle } from '@syncular/client';
 const handle = await createSyncClientHandle({
   worker: () => new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }),
   schema,
-  database: { mode: 'persistent', name: 'app' }, // OPFS, survives reloads
+  database: { mode: 'persistent', name: 'app' }, // OPFS, survives reloads while the origin remains stored
   endpoints: {
     syncUrl: '/sync',
     segmentsUrl: '/segments',
@@ -58,6 +57,25 @@ SPEC §8.4); the supported page-level realtime supervisor owns reconnect and
 resume policy. The main thread gets `onSyncNeeded` / `onConflict` / `onSynced`
 events for rendering.
 
+OPFS is best effort until the browser grants origin persistence. The page owns
+that decision because `StorageManager.persist()` is a Window API and should be
+requested from a user action:
+
+```ts
+import {
+  checkBrowserStoragePersistence,
+  requestBrowserStoragePersistence,
+} from '@syncular/client';
+
+const current = await checkBrowserStoragePersistence();
+const requested = await requestBrowserStoragePersistence(); // user action
+```
+
+Each call returns `persistent` or a structured `best-effort` reason. Keep the
+client usable after denial, display the state, and warn whenever best-effort
+storage contains pending outbox commits. Origin eviction removes OPFS and its
+outbox together; persistence does not prevent a user from clearing site data.
+
 **Ephemeral in-memory mode is EXPLICIT.** `openWasmDatabase()` returns an
 in-memory sqlite-wasm database for tests, demos and SSR. Nothing
 persists, on purpose, and that is the only main-thread mode.
@@ -103,7 +121,7 @@ HTTP rounds still work with no socket, but do not imply continuous convergence:
 a host trigger must actually run them. See the complete
 [realtime lifecycle guide](https://syncular.dev/concepts-realtime/).
 
-## Multi-tab followers (TODO 3.2, REVISE B3)
+## Multi-tab followers
 
 By default, every tab of the same origin shares ONE core:
 one sync loop, one WebSocket, one OPFS database, N tabs.
@@ -393,6 +411,9 @@ successful history may be dismissed. See SPEC §7.2.1.
   `FileSystemSyncAccessHandle`, unlike the Atomics-based `opfs` VFS).
 - Browsers without OPFS (~pre-2023) are **unsupported**:
   `openPersistentWasmDatabase` fails loud instead of degrading.
+- OPFS is reload-persistent but begins as best-effort origin storage. The root
+  package exports `checkBrowserStoragePersistence()` and
+  `requestBrowserStoragePersistence()` for the page-level persistence policy.
 - **Never IndexedDB.** There is no wa-sqlite/absurd-sql style fallback
   and none is planned.
 - `openPersistentWasmDatabase` refuses to run on the main thread — not a

package/dist/browser-storage-persistence.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Browser storage durability for the origin that owns Syncular's OPFS
+ * database. Persistence is requested by the page because `persist()` is a
+ * Window-only API and browsers may evaluate the request against user
+ * engagement.
+ */
+export type BrowserStoragePersistence = {
+    readonly state: 'persistent';
+} | {
+    readonly state: 'best-effort';
+    readonly reason: 'not-granted' | 'unavailable' | 'check-failed' | 'request-failed';
+};
+/** Check whether the current origin is protected from automatic eviction. */
+export declare function checkBrowserStoragePersistence(): Promise<BrowserStoragePersistence>;
+/**
+ * Request eviction-resistant storage for the current origin. Call this from a
+ * user action near the first important offline write. A best-effort result is
+ * an explicit durability state; the OPFS database remains usable.
+ */
+export declare function requestBrowserStoragePersistence(): Promise<BrowserStoragePersistence>;

package/dist/browser-storage-persistence.js

@@ -0,0 +1,34 @@
+/** Check whether the current origin is protected from automatic eviction. */
+export async function checkBrowserStoragePersistence() {
+    const storage = typeof navigator === 'undefined' ? undefined : navigator.storage;
+    if (storage === undefined || typeof storage.persisted !== 'function') {
+        return { state: 'best-effort', reason: 'unavailable' };
+    }
+    try {
+        return (await storage.persisted())
+            ? { state: 'persistent' }
+            : { state: 'best-effort', reason: 'not-granted' };
+    }
+    catch {
+        return { state: 'best-effort', reason: 'check-failed' };
+    }
+}
+/**
+ * Request eviction-resistant storage for the current origin. Call this from a
+ * user action near the first important offline write. A best-effort result is
+ * an explicit durability state; the OPFS database remains usable.
+ */
+export async function requestBrowserStoragePersistence() {
+    const storage = typeof navigator === 'undefined' ? undefined : navigator.storage;
+    if (storage === undefined || typeof storage.persist !== 'function') {
+        return { state: 'best-effort', reason: 'unavailable' };
+    }
+    try {
+        return (await storage.persist())
+            ? { state: 'persistent' }
+            : { state: 'best-effort', reason: 'not-granted' };
+    }
+    catch {
+        return { state: 'best-effort', reason: 'request-failed' };
+    }
+}

package/dist/bun-database.d.ts

@@ -1,5 +1,5 @@
 /**
- * `ClientDatabase` on bun:sqlite — the test backend (REVISE B3: the core
+ * `ClientDatabase` on bun:sqlite is the test backend. The core
  * must run without a browser). Not exported from the package root so the
  * browser entry never touches `bun:sqlite`.
  */

package/dist/bun-database.js

@@ -1,5 +1,5 @@
 /**
- * `ClientDatabase` on bun:sqlite — the test backend (REVISE B3: the core
+ * `ClientDatabase` on bun:sqlite is the test backend. The core
  * must run without a browser). Not exported from the package root so the
  * browser entry never touches `bun:sqlite`.
  */

package/dist/client.d.ts

@@ -1,8 +1,8 @@
 /**
- * SyncClient — the B3 client protocol core (SPEC.md §§3–8 client side).
+ * SyncClient implements the client side of SPEC.md §§3–8.
  *
  * A plain library running on whatever thread it is constructed on
- * (worker-OPTIONAL, REVISE B3): storage behind `ClientDatabase`, network
+ * Storage is behind `ClientDatabase`, network
  * behind `SyncTransport`/`SegmentDownloader`/`RealtimeConnector`, multi-tab
  * ownership behind `LeaderLock`. One combined push+pull request per
  * `sync()` round (§7.2); local reads go straight to the database.
@@ -252,7 +252,7 @@ export declare class SyncClient {
      */
     activateSecurity(options?: SecurityActivation): Promise<void>;
     get clientId(): string;
-    /** The underlying database — raw SQL is the local query API (B3). */
+    /** The underlying database: raw SQL is the local query API. */
     get database(): ClientDatabase;
     /**
      * The raw-SQL read tier. Guarded (query-guard.ts): a single read-only

package/dist/client.js

@@ -1,8 +1,8 @@
 /**
- * SyncClient — the B3 client protocol core (SPEC.md §§3–8 client side).
+ * SyncClient implements the client side of SPEC.md §§3–8.
  *
  * A plain library running on whatever thread it is constructed on
- * (worker-OPTIONAL, REVISE B3): storage behind `ClientDatabase`, network
+ * Storage is behind `ClientDatabase`, network
  * behind `SyncTransport`/`SegmentDownloader`/`RealtimeConnector`, multi-tab
  * ownership behind `LeaderLock`. One combined push+pull request per
  * `sync()` round (§7.2); local reads go straight to the database.
@@ -236,7 +236,7 @@ export class SyncClient {
             this.#config.onSyncNeeded?.('startup');
             this.#config.onSyncIntent?.({ kind: 'interactive' });
         }
-        // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
+        // Console introspection is a no-op outside a dev page.
         this.#devtoolsUnregister = registerDevtools({
             kind: 'client',
             ref: this,
@@ -391,7 +391,7 @@ export class SyncClient {
     get clientId() {
         return this.#clientId;
     }
-    /** The underlying database — raw SQL is the local query API (B3). */
+    /** The underlying database: raw SQL is the local query API. */
     get database() {
         this.#requireActive();
         return this.#db;
@@ -460,7 +460,7 @@ export class SyncClient {
             };
         });
     }
-    // -- live-query invalidation (TODO 3.1 / DESIGN-eviction I1–I4) -----------
+    // -- live-query invalidation ----------------------------------------------
     /**
      * Subscribe to fine-grained invalidation. The callback fires ONCE per
      * apply batch (never per row, I1) with the `{tables, scopeKeys}` touched
@@ -1920,7 +1920,7 @@ export class SyncClient {
     }
     /**
      * One request/response round trip (§8.7): over the socket whenever it
-     * is connected (Direction decision 1 — the socket IS the sync-round
+     * is connected (the socket IS the sync-round
      * transport, not a fallback pair), otherwise through the configured
      * `SyncTransport` seam (loopback/conformance hosts, HTTP-only
      * producers).

package/dist/database.d.ts

@@ -1,5 +1,5 @@
 /**
- * Storage abstraction (REVISE B3): the client core runs on any SQLite that
+ * Storage abstraction: the client core runs on any SQLite that
  * implements this minimal synchronous surface. Tests use bun:sqlite
  * (`./bun-database`); browsers use sqlite-wasm + OPFS (`./wasm-database`).
  * Methods are synchronous because both backends execute synchronously once

package/dist/devtools.d.ts

@@ -1,5 +1,5 @@
 /**
- * The client-side introspection registry (RFC 0002 §3.2): every live
+ * The client-side introspection registry: every live
  * `SyncClient` / `SyncClientHandle` on a page registers itself on
  * `globalThis.__SYNCULAR__`, so a first integration debugs from the console
  * instead of hand-exposing the client:

package/dist/http.d.ts

@@ -2,7 +2,7 @@
  * Browser transport bindings (§1.1, §5.4/§5.5, §8.1): fetch-based sync
  * transport, segment download with signed-URL preference and direct-serve
  * fallback, and a WebSocket realtime connector. Core tests never use these
- * (the loopback doctrine); B6 exercises them in a real browser.
+ * (the loopback doctrine); the browser fixture exercises them in a real browser.
  */
 import type { BlobTransport } from './blob.js';
 import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
- * @syncular/client — the B3 TypeScript client protocol core
- * (SPEC.md is normative; REVISE.md B3 is the architectural mandate).
+ * @syncular/client is the TypeScript client protocol core.
+ * SPEC.md is normative.
  *
  * Browser-safe root: database backends live behind subpath exports
  * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
@@ -11,6 +11,7 @@
 export * from './apply.js';
 export * from './availability.js';
 export * from './blob.js';
+export * from './browser-storage-persistence.js';
 export * from './client.js';
 export * from './content-type.js';
 export * from './database.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
- * @syncular/client — the B3 TypeScript client protocol core
- * (SPEC.md is normative; REVISE.md B3 is the architectural mandate).
+ * @syncular/client is the TypeScript client protocol core.
+ * SPEC.md is normative.
  *
  * Browser-safe root: database backends live behind subpath exports
  * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
@@ -11,6 +11,7 @@
 export * from './apply.js';
 export * from './availability.js';
 export * from './blob.js';
+export * from './browser-storage-persistence.js';
 export * from './client.js';
 export * from './content-type.js';
 export * from './database.js';

package/dist/invalidation.d.ts

@@ -1,5 +1,5 @@
 /**
- * Revisioned client-local observation events (SPEC §7.5 / RFC 0003).
+ * Revisioned client-local observation events (SPEC §7.5).
  *
  * The core records observer domains while it owns the SQLite transaction,
  * increments the persisted local revision in that same transaction, and emits

package/dist/leader-lock.d.ts

@@ -1,5 +1,5 @@
 /**
- * Multi-tab ownership seam (REVISE B3): exactly one core instance owns the
+ * Multi-tab ownership seam: exactly one core instance owns the
  * local database. The interface is the whole B3 deliverable — cross-tab
  * follower fanout is post-gate. Browsers use Web Locks; tests use the
  * no-op single-owner lock.
@@ -14,7 +14,7 @@ export interface LeaderLock {
      * Resolves immediately: the lease when leadership was free, `undefined`
      * when another owner holds it. The worker handle uses this so a second
      * tab gets a clear not-leader state instead of blocking forever
-     * (followers are post-gate, TODO 3.2).
+     * (followers are post-gate).
      */
     tryAcquire?(name: string): Promise<LeaderLease | undefined>;
 }

package/dist/multi-tab.js

@@ -1,5 +1,5 @@
 /**
- * Multi-tab followers (TODO 3.2, REVISE B3): one core per origin, N tabs.
+ * Multi-tab followers: one core per origin, N tabs.
  *
  * The leader tab holds the Web Locks lease and runs the worker core (the
  * existing worker-host path, unchanged). Every OTHER tab is a FOLLOWER: it

package/dist/naming.d.ts

@@ -1,5 +1,5 @@
 /**
- * The pinned snake→camel naming map (DESIGN-queries.md §5, §12) — the
+ * The pinned snake→camel naming map. The
  * client-side copy of the typegen algorithm (kept in lockstep by shared
  * test vectors; the Rust core carries the same function). Used by `mutate`
  * to accept BOTH casings for value keys: the canonical camelCase the

package/dist/naming.js

@@ -1,5 +1,5 @@
 /**
- * The pinned snake→camel naming map (DESIGN-queries.md §5, §12) — the
+ * The pinned snake→camel naming map. The
  * client-side copy of the typegen algorithm (kept in lockstep by shared
  * test vectors; the Rust core carries the same function). Used by `mutate`
  * to accept BOTH casings for value keys: the canonical camelCase the

package/dist/node-database.js

@@ -1,6 +1,6 @@
 /**
  * `ClientDatabase` on better-sqlite3 — the Electron-main / plain-Node
- * backend (TODO 2: Node ClientDatabase). Semantics mirror `./bun-database`
+ * backend. Semantics mirror `./bun-database`
  * exactly (synchronous exec/query/transaction with the shared savepoint
  * helper, and the same §5.3 sqlite-image ATTACH path), so the core behaves
  * identically whether it runs on bun:sqlite (tests), sqlite-wasm (browser)

package/dist/query-guard.d.ts

@@ -1,5 +1,5 @@
 /**
- * The raw-query guard (DESIGN-queries.md I3). `client.query()` / the React
+ * The raw-query guard. `client.query()` and the React
  * `useRawSql` hook are the untrusted raw-SQL tier: an app hands us a SQL
  * string and we run it against the local database. Two rules make that safe
  * to expose, enforced HERE in the core (previously they lived in the

package/dist/query-guard.js

@@ -1,5 +1,5 @@
 /**
- * The raw-query guard (DESIGN-queries.md I3). `client.query()` / the React
+ * The raw-query guard. `client.query()` and the React
  * `useRawSql` hook are the untrusted raw-SQL tier: an app hands us a SQL
  * string and we run it against the local database. Two rules make that safe
  * to expose, enforced HERE in the core (previously they lived in the

package/dist/schema.d.ts

@@ -1,6 +1,6 @@
 /**
  * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
- * compiles, hand-written until codegen (B5) emits it. Drives local table
+ * compiles and is emitted by codegen. Drives local table
  * DDL, the generated row codec, mutation helpers, and the §3.3 purge
  * mapping (scope variable → local column).
  */
@@ -17,7 +17,7 @@ export interface ClientIndexSpec {
     readonly columns: readonly string[];
     readonly unique: boolean;
 }
-/** One client-local contentful FTS5 projection (RFC 0005). */
+/** One client-local contentful FTS5 projection. */
 export interface ClientFtsIndexSpec {
     readonly name: string;
     readonly columns: readonly string[];
@@ -58,7 +58,7 @@ export interface CompiledClientTable {
     /**
      * Scope variable → the pattern's literal prefix (§3.1). A stored-scope
      * value `v` for this variable has scope key `prefix:v` — the invalidation
-     * vocabulary (TODO 3.1 / DESIGN-eviction I2) and the delta-routing key.
+     * vocabulary and the delta-routing key.
      */
     readonly scopePrefixByVariable: ReadonlyMap<string, string>;
     /** Local secondary indexes to create on the mirror table (declaration

package/dist/sql-tag.d.ts

@@ -1,6 +1,6 @@
 /**
  * The `sql` tagged template — the raw tier's composition helper
- * (DESIGN-queries.md I4). Structural injection safety: an interpolated
+ * Structural injection safety: an interpolated
  * value can only ever become a `?` bind parameter; SQL text can only enter
  * through the literal template, `sql.ident()` (allowlist-gated) or a loud
  * `sql.raw()`. This helper is deliberately dumb plumbing and stays that

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 /**
- * Transport seams (REVISE B3): request/response bytes, segment download,
+ * Transport seams: request/response bytes, segment download,
  * and the realtime attach surface matching §8's client side. Tests use
  * loopback implementations that call the server library directly — the
  * loopback doctrine; HTTP/WebSocket bindings live in `./http`.

package/dist/transport.js

@@ -1,5 +1,5 @@
 /**
- * Transport seams (REVISE B3): request/response bytes, segment download,
+ * Transport seams: request/response bytes, segment download,
  * and the realtime attach surface matching §8's client side. Tests use
  * loopback implementations that call the server library directly — the
  * loopback doctrine; HTTP/WebSocket bindings live in `./http`.

package/dist/wasm-database.d.ts

@@ -3,7 +3,7 @@ import { type ClientDatabase } from './database.js';
  * EXPLICIT ephemeral mode: an in-memory sqlite-wasm database. For tests,
  * demos and SSR only — nothing persists. The persistent mode is
  * `openPersistentWasmDatabase` inside a worker; there is no fallback from
- * one to the other (Direction decision 2).
+ * one to the other.
  */
 export declare function openWasmDatabase(): Promise<ClientDatabase>;
 export interface PersistentWasmDatabaseOptions {
@@ -18,13 +18,15 @@ export interface PersistentWasmDatabaseOptions {
     readonly initialCapacity?: number;
 }
 /**
- * THE persistent browser mode: a named database on OPFS via the
+ * THE reload-persistent browser mode: a named database on OPFS via the
  * `opfs-sahpool` VFS. Worker-context only — not because SAHPool requires
  * it (it uses `FileSystemSyncAccessHandle`, no `Atomics.wait`, and could
  * technically run on the main thread), but because the persistent mode IS
- * whole-core-in-a-worker (REVISE Direction decision 2, 2026-07-03) and
+ * whole-core-in-a-worker and
  * this factory enforces that decision. No COOP/COEP headers required.
  *
- * Support floor: no OPFS → a loud `ClientSyncError`, never a fallback.
+ * Support floor: no OPFS → a loud `ClientSyncError`, never a fallback. This
+ * factory cannot request eviction-resistant origin storage because that API
+ * belongs to the page's Window context.
  */
 export declare function openPersistentWasmDatabase(name: string, options?: PersistentWasmDatabaseOptions): Promise<ClientDatabase>;

package/dist/wasm-database.js

@@ -1,8 +1,8 @@
 /**
- * `ClientDatabase` on @sqlite.org/sqlite-wasm (Direction decision 2,
- * 2026-07-03). Two modes, no ladder between them:
+ * `ClientDatabase` on @sqlite.org/sqlite-wasm. Two modes, no ladder between
+ * them:
  *
- * - `openPersistentWasmDatabase(name)` — THE persistent browser mode:
+ * - `openPersistentWasmDatabase(name)` — THE reload-persistent browser mode:
  *   OPFS via the `opfs-sahpool` VFS, restricted to Web Worker contexts
  *   because the whole client core runs in a worker by design. SAHPool
  *   needs **no COOP/COEP headers and no SharedArrayBuffer** (it is built
@@ -10,7 +10,10 @@
  *   proxy — the COOP/COEP requirement documented by sqlite-wasm applies
  *   only to `oo1.OpfsDb`, which this binding no longer uses). Browsers
  *   without OPFS are unsupported (support floor ~2023+): the factory
- *   fails loud. Never IndexedDB, never a silent in-memory fallback.
+ *   fails loud. Never IndexedDB, never a silent in-memory fallback. The
+ *   browser's separate origin-eviction policy is exposed from the root package
+ *   by `checkBrowserStoragePersistence` and
+ *   `requestBrowserStoragePersistence`.
  * - `openWasmDatabase()` — EXPLICIT ephemeral: an in-memory database for
  *   tests, demos and SSR. Nothing survives a reload, on purpose.
  *
@@ -106,7 +109,7 @@ function initSqlite3() {
  * EXPLICIT ephemeral mode: an in-memory sqlite-wasm database. For tests,
  * demos and SSR only — nothing persists. The persistent mode is
  * `openPersistentWasmDatabase` inside a worker; there is no fallback from
- * one to the other (Direction decision 2).
+ * one to the other.
  */
 export async function openWasmDatabase() {
     const sqlite3 = await initSqlite3();
@@ -133,14 +136,16 @@ function opfsSahPoolError(error, directory) {
         `or rename the directory. Underlying error: ${detail}`, true);
 }
 /**
- * THE persistent browser mode: a named database on OPFS via the
+ * THE reload-persistent browser mode: a named database on OPFS via the
  * `opfs-sahpool` VFS. Worker-context only — not because SAHPool requires
  * it (it uses `FileSystemSyncAccessHandle`, no `Atomics.wait`, and could
  * technically run on the main thread), but because the persistent mode IS
- * whole-core-in-a-worker (REVISE Direction decision 2, 2026-07-03) and
+ * whole-core-in-a-worker and
  * this factory enforces that decision. No COOP/COEP headers required.
  *
- * Support floor: no OPFS → a loud `ClientSyncError`, never a fallback.
+ * Support floor: no OPFS → a loud `ClientSyncError`, never a fallback. This
+ * factory cannot request eviction-resistant origin storage because that API
+ * belongs to the page's Window context.
  */
 export async function openPersistentWasmDatabase(name, options) {
     if (!/^[A-Za-z0-9._-]+$/.test(name)) {

package/dist/window.d.ts

@@ -1,5 +1,5 @@
 /**
- * Windowed subscriptions (SPEC.md §4.8 / DESIGN-eviction.md W1).
+ * Windowed subscriptions (SPEC.md §4.8).
  *
  * A window is a partial local replica keyed by scope VALUES: the client
  * holds rows for a chosen set of units (one scope value each) of a window

package/dist/window.js

@@ -1,5 +1,5 @@
 /**
- * Windowed subscriptions (SPEC.md §4.8 / DESIGN-eviction.md W1).
+ * Windowed subscriptions (SPEC.md §4.8).
  *
  * A window is a partial local replica keyed by scope VALUES: the client
  * holds rows for a chosen set of units (one scope value each) of a window

package/dist/worker-entry.js

@@ -1,5 +1,5 @@
 /**
- * Worker-side bootstrap (Direction decision 2): constructs the WHOLE
+ * Worker-side bootstrap: constructs the WHOLE
  * client core — SyncClient + transports + realtime + SQLite — inside the
  * worker and serves the `worker-protocol` RPC over postMessage.
  *

package/dist/worker-host.d.ts

@@ -1,6 +1,6 @@
 /**
- * Main-thread side of the worker mode (Direction decision 2) and the
- * multi-tab topology (TODO 3.2, REVISE B3).
+ * Main-thread side of the worker mode and the
+ * multi-tab topology.
  *
  * `createSyncClientHandle` acquires the Web Locks leader lock and, when it
  * wins, spawns the worker running the WHOLE core — so exactly one core runs
@@ -8,7 +8,7 @@
  * holding the lock). The returned {@link SyncClientHandle} is a thin, fully
  * async proxy over the `worker-protocol` RPC.
  *
- * Multi-tab is the DEFAULT (RFC 0002 §2.4 — the follower path is
+ * Multi-tab is the DEFAULT. The follower path is
  * conformance-covered): a tab that LOSES the election becomes a FOLLOWER
  * (`role === 'follower'`) that proxies every call to the leader tab over a
  * BroadcastChannel (see `multi-tab.ts`). When the leader tab closes, its
@@ -86,7 +86,7 @@ export interface SyncClientHandleConfig {
     /** Shared by default; isolated derives the database/lock/channel tuple. */
     readonly replica?: BrowserReplicaMode;
     /**
-     * Multi-tab followers (TODO 3.2). On by default: a tab that loses the
+     * Multi-tab followers. On by default: a tab that loses the
      * leader election becomes a FOLLOWER that proxies to the leader over a
      * BroadcastChannel, and contests + promotes when the leader closes. Set
      * false for the single-tab contract — the loser is a dead
@@ -172,7 +172,7 @@ export declare class SyncClientHandle {
     /** @internal — dispatch a worker/relayed event to handle-local listeners. */
     __dispatchEvent(event: SyncWorkerEvent): void;
     /**
-     * TODO 3.1 / I1: subscribe to fine-grained invalidation — the identical
+     * Subscribe to fine-grained invalidation. The identical
      * surface as `SyncClient.onInvalidate`, so React bindings target one
      * interface across direct, worker-leader, and follower modes. Returns an
      * unsubscribe function.

package/dist/worker-host.js

@@ -98,7 +98,7 @@ export class SyncClientHandle {
         this.#diagnostics = internals.diagnostics;
         this.#roleListeners = internals.roleListeners ?? new Set();
         this.#leadershipListeners = internals.leadershipListeners ?? new Set();
-        // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
+        // Console introspection is a no-op outside a dev page.
         this.#devtoolsUnregister = registerDevtools({
             kind: 'handle',
             ref: this,
@@ -181,7 +181,7 @@ export class SyncClientHandle {
         }
     }
     /**
-     * TODO 3.1 / I1: subscribe to fine-grained invalidation — the identical
+     * Subscribe to fine-grained invalidation. The identical
      * surface as `SyncClient.onInvalidate`, so React bindings target one
      * interface across direct, worker-leader, and follower modes. Returns an
      * unsubscribe function.

package/dist/worker-protocol.d.ts

@@ -1,5 +1,5 @@
 /**
- * The worker RPC protocol (Direction decision 2, 2026-07-03): the whole
+ * The worker RPC protocol: the whole
  * client core runs in a Web Worker; the UI thread talks to it through
  * this thin, multiplexed postMessage protocol. Exactly SIX message types
  * (`init`, `call`, `ready`, `result`, `error`, `event`) — every logical
@@ -30,14 +30,14 @@ import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } fro
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
-/** The handle exists but this tab lost the leader election (TODO 3.2). */
+/** The handle exists but this tab lost the leader election. */
 export declare const NOT_LEADER_CODE = "client.not_leader";
 /** The worker (or its RPC channel) failed outside protocol semantics. */
 export declare const WORKER_FAILED_CODE = "client.worker_failed";
 /** A page/worker bundle identity changed and a full host reload is required. */
 export declare const WORKER_RESTART_REQUIRED_CODE = "client.worker_restart_required";
 export type WorkerDatabaseInit = {
-    /** THE persistent mode: opfs-sahpool, named database. */
+    /** Reload-persistent OPFS mode; origin eviction policy stays page-owned. */
     readonly mode: 'persistent';
     readonly name: string;
     /** Optional pool directory override (default `.syncular/<name>`). */

package/dist/worker-protocol.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // Client-local error codes (never wire codes; §10 stays server-owned)
 // ---------------------------------------------------------------------------
-/** The handle exists but this tab lost the leader election (TODO 3.2). */
+/** The handle exists but this tab lost the leader election. */
 export const NOT_LEADER_CODE = 'client.not_leader';
 /** The worker (or its RPC channel) failed outside protocol semantics. */
 export const WORKER_FAILED_CODE = 'client.worker_failed';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.44",
+  "version": "0.15.45",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,7 +89,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.44"
+    "@syncular/core": "0.15.45"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -100,7 +100,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.44",
+    "@syncular/server": "0.15.45",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/browser-storage-persistence.ts

@@ -0,0 +1,52 @@
+/**
+ * Browser storage durability for the origin that owns Syncular's OPFS
+ * database. Persistence is requested by the page because `persist()` is a
+ * Window-only API and browsers may evaluate the request against user
+ * engagement.
+ */
+export type BrowserStoragePersistence =
+  | { readonly state: 'persistent' }
+  | {
+      readonly state: 'best-effort';
+      readonly reason:
+        | 'not-granted'
+        | 'unavailable'
+        | 'check-failed'
+        | 'request-failed';
+    };
+
+/** Check whether the current origin is protected from automatic eviction. */
+export async function checkBrowserStoragePersistence(): Promise<BrowserStoragePersistence> {
+  const storage =
+    typeof navigator === 'undefined' ? undefined : navigator.storage;
+  if (storage === undefined || typeof storage.persisted !== 'function') {
+    return { state: 'best-effort', reason: 'unavailable' };
+  }
+  try {
+    return (await storage.persisted())
+      ? { state: 'persistent' }
+      : { state: 'best-effort', reason: 'not-granted' };
+  } catch {
+    return { state: 'best-effort', reason: 'check-failed' };
+  }
+}
+
+/**
+ * Request eviction-resistant storage for the current origin. Call this from a
+ * user action near the first important offline write. A best-effort result is
+ * an explicit durability state; the OPFS database remains usable.
+ */
+export async function requestBrowserStoragePersistence(): Promise<BrowserStoragePersistence> {
+  const storage =
+    typeof navigator === 'undefined' ? undefined : navigator.storage;
+  if (storage === undefined || typeof storage.persist !== 'function') {
+    return { state: 'best-effort', reason: 'unavailable' };
+  }
+  try {
+    return (await storage.persist())
+      ? { state: 'persistent' }
+      : { state: 'best-effort', reason: 'not-granted' };
+  } catch {
+    return { state: 'best-effort', reason: 'request-failed' };
+  }
+}

package/src/bun-database.ts

@@ -1,5 +1,5 @@
 /**
- * `ClientDatabase` on bun:sqlite — the test backend (REVISE B3: the core
+ * `ClientDatabase` on bun:sqlite is the test backend. The core
  * must run without a browser). Not exported from the package root so the
  * browser entry never touches `bun:sqlite`.
  */

package/src/client.ts

@@ -1,8 +1,8 @@
 /**
- * SyncClient — the B3 client protocol core (SPEC.md §§3–8 client side).
+ * SyncClient implements the client side of SPEC.md §§3–8.
  *
  * A plain library running on whatever thread it is constructed on
- * (worker-OPTIONAL, REVISE B3): storage behind `ClientDatabase`, network
+ * Storage is behind `ClientDatabase`, network
  * behind `SyncTransport`/`SegmentDownloader`/`RealtimeConnector`, multi-tab
  * ownership behind `LeaderLock`. One combined push+pull request per
  * `sync()` round (§7.2); local reads go straight to the database.
@@ -708,7 +708,7 @@ export class SyncClient {
       this.#config.onSyncNeeded?.('startup');
       this.#config.onSyncIntent?.({ kind: 'interactive' });
     }
-    // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
+    // Console introspection is a no-op outside a dev page.
     this.#devtoolsUnregister = registerDevtools({
       kind: 'client',
       ref: this,
@@ -881,7 +881,7 @@ export class SyncClient {
     return this.#clientId;
   }
 
-  /** The underlying database — raw SQL is the local query API (B3). */
+  /** The underlying database: raw SQL is the local query API. */
   get database(): ClientDatabase {
     this.#requireActive();
     return this.#db;
@@ -960,7 +960,7 @@ export class SyncClient {
     });
   }
 
-  // -- live-query invalidation (TODO 3.1 / DESIGN-eviction I1–I4) -----------
+  // -- live-query invalidation ----------------------------------------------
 
   /**
    * Subscribe to fine-grained invalidation. The callback fires ONCE per
@@ -2725,7 +2725,7 @@ export class SyncClient {
 
   /**
    * One request/response round trip (§8.7): over the socket whenever it
-   * is connected (Direction decision 1 — the socket IS the sync-round
+   * is connected (the socket IS the sync-round
    * transport, not a fallback pair), otherwise through the configured
    * `SyncTransport` seam (loopback/conformance hosts, HTTP-only
    * producers).

package/src/database.ts

@@ -1,5 +1,5 @@
 /**
- * Storage abstraction (REVISE B3): the client core runs on any SQLite that
+ * Storage abstraction: the client core runs on any SQLite that
  * implements this minimal synchronous surface. Tests use bun:sqlite
  * (`./bun-database`); browsers use sqlite-wasm + OPFS (`./wasm-database`).
  * Methods are synchronous because both backends execute synchronously once

package/src/devtools.ts

@@ -1,5 +1,5 @@
 /**
- * The client-side introspection registry (RFC 0002 §3.2): every live
+ * The client-side introspection registry: every live
  * `SyncClient` / `SyncClientHandle` on a page registers itself on
  * `globalThis.__SYNCULAR__`, so a first integration debugs from the console
  * instead of hand-exposing the client:

package/src/http.ts

@@ -2,7 +2,7 @@
  * Browser transport bindings (§1.1, §5.4/§5.5, §8.1): fetch-based sync
  * transport, segment download with signed-URL preference and direct-serve
  * fallback, and a WebSocket realtime connector. Core tests never use these
- * (the loopback doctrine); B6 exercises them in a real browser.
+ * (the loopback doctrine); the browser fixture exercises them in a real browser.
  */
 import type { BlobTransport } from './blob';
 import { SSP2_CONTENT_TYPE } from './content-type';

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
- * @syncular/client — the B3 TypeScript client protocol core
- * (SPEC.md is normative; REVISE.md B3 is the architectural mandate).
+ * @syncular/client is the TypeScript client protocol core.
+ * SPEC.md is normative.
  *
  * Browser-safe root: database backends live behind subpath exports
  * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
@@ -11,6 +11,7 @@
 export * from './apply';
 export * from './availability';
 export * from './blob';
+export * from './browser-storage-persistence';
 export * from './client';
 export * from './content-type';
 export * from './database';

package/src/invalidation.ts

@@ -1,5 +1,5 @@
 /**
- * Revisioned client-local observation events (SPEC §7.5 / RFC 0003).
+ * Revisioned client-local observation events (SPEC §7.5).
  *
  * The core records observer domains while it owns the SQLite transaction,
  * increments the persisted local revision in that same transaction, and emits

package/src/leader-lock.ts

@@ -1,5 +1,5 @@
 /**
- * Multi-tab ownership seam (REVISE B3): exactly one core instance owns the
+ * Multi-tab ownership seam: exactly one core instance owns the
  * local database. The interface is the whole B3 deliverable — cross-tab
  * follower fanout is post-gate. Browsers use Web Locks; tests use the
  * no-op single-owner lock.
@@ -15,7 +15,7 @@ export interface LeaderLock {
    * Resolves immediately: the lease when leadership was free, `undefined`
    * when another owner holds it. The worker handle uses this so a second
    * tab gets a clear not-leader state instead of blocking forever
-   * (followers are post-gate, TODO 3.2).
+   * (followers are post-gate).
    */
   tryAcquire?(name: string): Promise<LeaderLease | undefined>;
 }

package/src/multi-tab.ts

@@ -1,5 +1,5 @@
 /**
- * Multi-tab followers (TODO 3.2, REVISE B3): one core per origin, N tabs.
+ * Multi-tab followers: one core per origin, N tabs.
  *
  * The leader tab holds the Web Locks lease and runs the worker core (the
  * existing worker-host path, unchanged). Every OTHER tab is a FOLLOWER: it

package/src/naming.ts

@@ -1,5 +1,5 @@
 /**
- * The pinned snake→camel naming map (DESIGN-queries.md §5, §12) — the
+ * The pinned snake→camel naming map. The
  * client-side copy of the typegen algorithm (kept in lockstep by shared
  * test vectors; the Rust core carries the same function). Used by `mutate`
  * to accept BOTH casings for value keys: the canonical camelCase the

package/src/node-database.ts

@@ -1,6 +1,6 @@
 /**
  * `ClientDatabase` on better-sqlite3 — the Electron-main / plain-Node
- * backend (TODO 2: Node ClientDatabase). Semantics mirror `./bun-database`
+ * backend. Semantics mirror `./bun-database`
  * exactly (synchronous exec/query/transaction with the shared savepoint
  * helper, and the same §5.3 sqlite-image ATTACH path), so the core behaves
  * identically whether it runs on bun:sqlite (tests), sqlite-wasm (browser)

package/src/query-guard.ts

@@ -1,5 +1,5 @@
 /**
- * The raw-query guard (DESIGN-queries.md I3). `client.query()` / the React
+ * The raw-query guard. `client.query()` and the React
  * `useRawSql` hook are the untrusted raw-SQL tier: an app hands us a SQL
  * string and we run it against the local database. Two rules make that safe
  * to expose, enforced HERE in the core (previously they lived in the

package/src/schema.ts

@@ -1,6 +1,6 @@
 /**
  * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
- * compiles, hand-written until codegen (B5) emits it. Drives local table
+ * compiles and is emitted by codegen. Drives local table
  * DDL, the generated row codec, mutation helpers, and the §3.3 purge
  * mapping (scope variable → local column).
  */
@@ -19,7 +19,7 @@ export interface ClientIndexSpec {
   readonly unique: boolean;
 }
 
-/** One client-local contentful FTS5 projection (RFC 0005). */
+/** One client-local contentful FTS5 projection. */
 export interface ClientFtsIndexSpec {
   readonly name: string;
   readonly columns: readonly string[];
@@ -63,7 +63,7 @@ export interface CompiledClientTable {
   /**
    * Scope variable → the pattern's literal prefix (§3.1). A stored-scope
    * value `v` for this variable has scope key `prefix:v` — the invalidation
-   * vocabulary (TODO 3.1 / DESIGN-eviction I2) and the delta-routing key.
+   * vocabulary and the delta-routing key.
    */
   readonly scopePrefixByVariable: ReadonlyMap<string, string>;
   /** Local secondary indexes to create on the mirror table (declaration

package/src/sql-tag.ts

@@ -1,6 +1,6 @@
 /**
  * The `sql` tagged template — the raw tier's composition helper
- * (DESIGN-queries.md I4). Structural injection safety: an interpolated
+ * Structural injection safety: an interpolated
  * value can only ever become a `?` bind parameter; SQL text can only enter
  * through the literal template, `sql.ident()` (allowlist-gated) or a loud
  * `sql.raw()`. This helper is deliberately dumb plumbing and stays that

package/src/transport.ts

@@ -1,5 +1,5 @@
 /**
- * Transport seams (REVISE B3): request/response bytes, segment download,
+ * Transport seams: request/response bytes, segment download,
  * and the realtime attach surface matching §8's client side. Tests use
  * loopback implementations that call the server library directly — the
  * loopback doctrine; HTTP/WebSocket bindings live in `./http`.

package/src/wasm-database.ts

@@ -1,8 +1,8 @@
 /**
- * `ClientDatabase` on @sqlite.org/sqlite-wasm (Direction decision 2,
- * 2026-07-03). Two modes, no ladder between them:
+ * `ClientDatabase` on @sqlite.org/sqlite-wasm. Two modes, no ladder between
+ * them:
  *
- * - `openPersistentWasmDatabase(name)` — THE persistent browser mode:
+ * - `openPersistentWasmDatabase(name)` — THE reload-persistent browser mode:
  *   OPFS via the `opfs-sahpool` VFS, restricted to Web Worker contexts
  *   because the whole client core runs in a worker by design. SAHPool
  *   needs **no COOP/COEP headers and no SharedArrayBuffer** (it is built
@@ -10,7 +10,10 @@
  *   proxy — the COOP/COEP requirement documented by sqlite-wasm applies
  *   only to `oo1.OpfsDb`, which this binding no longer uses). Browsers
  *   without OPFS are unsupported (support floor ~2023+): the factory
- *   fails loud. Never IndexedDB, never a silent in-memory fallback.
+ *   fails loud. Never IndexedDB, never a silent in-memory fallback. The
+ *   browser's separate origin-eviction policy is exposed from the root package
+ *   by `checkBrowserStoragePersistence` and
+ *   `requestBrowserStoragePersistence`.
  * - `openWasmDatabase()` — EXPLICIT ephemeral: an in-memory database for
  *   tests, demos and SSR. Nothing survives a reload, on purpose.
  *
@@ -184,7 +187,7 @@ function initSqlite3(): Promise<Sqlite3Static> {
  * EXPLICIT ephemeral mode: an in-memory sqlite-wasm database. For tests,
  * demos and SSR only — nothing persists. The persistent mode is
  * `openPersistentWasmDatabase` inside a worker; there is no fallback from
- * one to the other (Direction decision 2).
+ * one to the other.
  */
 export async function openWasmDatabase(): Promise<ClientDatabase> {
   const sqlite3 = await initSqlite3();
@@ -238,14 +241,16 @@ function opfsSahPoolError(error: unknown, directory: string): ClientSyncError {
 }
 
 /**
- * THE persistent browser mode: a named database on OPFS via the
+ * THE reload-persistent browser mode: a named database on OPFS via the
  * `opfs-sahpool` VFS. Worker-context only — not because SAHPool requires
  * it (it uses `FileSystemSyncAccessHandle`, no `Atomics.wait`, and could
  * technically run on the main thread), but because the persistent mode IS
- * whole-core-in-a-worker (REVISE Direction decision 2, 2026-07-03) and
+ * whole-core-in-a-worker and
  * this factory enforces that decision. No COOP/COEP headers required.
  *
- * Support floor: no OPFS → a loud `ClientSyncError`, never a fallback.
+ * Support floor: no OPFS → a loud `ClientSyncError`, never a fallback. This
+ * factory cannot request eviction-resistant origin storage because that API
+ * belongs to the page's Window context.
  */
 export async function openPersistentWasmDatabase(
   name: string,

package/src/window.ts

@@ -1,5 +1,5 @@
 /**
- * Windowed subscriptions (SPEC.md §4.8 / DESIGN-eviction.md W1).
+ * Windowed subscriptions (SPEC.md §4.8).
  *
  * A window is a partial local replica keyed by scope VALUES: the client
  * holds rows for a chosen set of units (one scope value each) of a window

package/src/worker-entry.ts

@@ -1,5 +1,5 @@
 /**
- * Worker-side bootstrap (Direction decision 2): constructs the WHOLE
+ * Worker-side bootstrap: constructs the WHOLE
  * client core — SyncClient + transports + realtime + SQLite — inside the
  * worker and serves the `worker-protocol` RPC over postMessage.
  *

package/src/worker-host.ts

@@ -1,6 +1,6 @@
 /**
- * Main-thread side of the worker mode (Direction decision 2) and the
- * multi-tab topology (TODO 3.2, REVISE B3).
+ * Main-thread side of the worker mode and the
+ * multi-tab topology.
  *
  * `createSyncClientHandle` acquires the Web Locks leader lock and, when it
  * wins, spawns the worker running the WHOLE core — so exactly one core runs
@@ -8,7 +8,7 @@
  * holding the lock). The returned {@link SyncClientHandle} is a thin, fully
  * async proxy over the `worker-protocol` RPC.
  *
- * Multi-tab is the DEFAULT (RFC 0002 §2.4 — the follower path is
+ * Multi-tab is the DEFAULT. The follower path is
  * conformance-covered): a tab that LOSES the election becomes a FOLLOWER
  * (`role === 'follower'`) that proxies every call to the leader tab over a
  * BroadcastChannel (see `multi-tab.ts`). When the leader tab closes, its
@@ -181,7 +181,7 @@ export interface SyncClientHandleConfig {
   /** Shared by default; isolated derives the database/lock/channel tuple. */
   readonly replica?: BrowserReplicaMode;
   /**
-   * Multi-tab followers (TODO 3.2). On by default: a tab that loses the
+   * Multi-tab followers. On by default: a tab that loses the
    * leader election becomes a FOLLOWER that proxies to the leader over a
    * BroadcastChannel, and contests + promotes when the leader closes. Set
    * false for the single-tab contract — the loser is a dead
@@ -318,7 +318,7 @@ export class SyncClientHandle {
     this.#diagnostics = internals.diagnostics;
     this.#roleListeners = internals.roleListeners ?? new Set();
     this.#leadershipListeners = internals.leadershipListeners ?? new Set();
-    // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
+    // Console introspection is a no-op outside a dev page.
     this.#devtoolsUnregister = registerDevtools({
       kind: 'handle',
       ref: this,
@@ -401,7 +401,7 @@ export class SyncClientHandle {
   }
 
   /**
-   * TODO 3.1 / I1: subscribe to fine-grained invalidation — the identical
+   * Subscribe to fine-grained invalidation. The identical
    * surface as `SyncClient.onInvalidate`, so React bindings target one
    * interface across direct, worker-leader, and follower modes. Returns an
    * unsubscribe function.

package/src/worker-protocol.ts

@@ -1,5 +1,5 @@
 /**
- * The worker RPC protocol (Direction decision 2, 2026-07-03): the whole
+ * The worker RPC protocol: the whole
  * client core runs in a Web Worker; the UI thread talks to it through
  * this thin, multiplexed postMessage protocol. Exactly SIX message types
  * (`init`, `call`, `ready`, `result`, `error`, `event`) — every logical
@@ -63,7 +63,7 @@ import type { WindowBase } from './window';
 // Client-local error codes (never wire codes; §10 stays server-owned)
 // ---------------------------------------------------------------------------
 
-/** The handle exists but this tab lost the leader election (TODO 3.2). */
+/** The handle exists but this tab lost the leader election. */
 export const NOT_LEADER_CODE = 'client.not_leader';
 /** The worker (or its RPC channel) failed outside protocol semantics. */
 export const WORKER_FAILED_CODE = 'client.worker_failed';
@@ -76,7 +76,7 @@ export const WORKER_RESTART_REQUIRED_CODE = 'client.worker_restart_required';
 
 export type WorkerDatabaseInit =
   | {
-      /** THE persistent mode: opfs-sahpool, named database. */
+      /** Reload-persistent OPFS mode; origin eviction policy stays page-owned. */
       readonly mode: 'persistent';
       readonly name: string;
       /** Optional pool directory override (default `.syncular/<name>`). */