@syncular/client 0.15.44 → 0.15.46

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`.
@@ -8,6 +8,25 @@
 /** One combined push+pull round trip: SSP2 request bytes → response bytes. */
 export type SyncTransport = (request: Uint8Array) => Promise<Uint8Array>;
 
+/** One registered authoritative query or command request. */
+export type RemoteOperationTransport = (
+  request: Uint8Array,
+) => Promise<Uint8Array>;
+
+export interface RemoteOperationRealtimeHandlers {
+  onMessage(bytes: Uint8Array): void;
+  onClose?(): void;
+}
+
+export interface RemoteOperationRealtimeSocket {
+  send(bytes: Uint8Array): void;
+  close(): void;
+}
+
+export type RemoteOperationRealtimeConnector = (
+  handlers: RemoteOperationRealtimeHandlers,
+) => RemoteOperationRealtimeSocket | Promise<RemoteOperationRealtimeSocket>;
+
 export interface SegmentFetchRequest {
   readonly segmentId: string;
   readonly table: string;

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>`). */