@syncular/client 0.15.44 → 0.15.46

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.46",
   "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.46"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -100,7 +100,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.44",
+    "@syncular/server": "0.15.46",
     "@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,13 +2,15 @@
  * 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';
 import { ClientSyncError } from './errors';
 import type {
   RealtimeConnector,
+  RemoteOperationTransport,
+  RemoteOperationRealtimeConnector,
   SegmentDownloader,
   SyncTransport,
 } from './transport';
@@ -57,6 +59,78 @@ export function httpSyncTransport(
   };
 }
 
+/** POST one registered authoritative operation to `<mount>/operations`. */
+export function httpRemoteOperationTransport(
+  operationsUrl: string,
+  options?: HttpTransportOptions,
+): RemoteOperationTransport {
+  const doFetch = options?.fetch ?? fetch;
+  return async (request) => {
+    const response = await doFetch(operationsUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/vnd.syncular.operations.v1+json',
+        ...options?.headers,
+      },
+      body: request.slice().buffer as ArrayBuffer,
+    });
+    if (!response.ok) await throwHttpError(response);
+    return new Uint8Array(await response.arrayBuffer());
+  };
+}
+
+/** WebSocket connector for registered query snapshots. */
+export function webSocketRemoteOperationConnector(
+  realtimeUrl: string,
+): RemoteOperationRealtimeConnector {
+  return (handlers) =>
+    new Promise((resolve, reject) => {
+      const socket = new WebSocket(realtimeUrl);
+      let opened = false;
+      socket.binaryType = 'arraybuffer';
+      socket.onopen = () => {
+        opened = true;
+        resolve({
+          send: (bytes) => socket.send(bytes.slice().buffer as ArrayBuffer),
+          close: () => socket.close(),
+        });
+      };
+      socket.onmessage = (event) => {
+        if (event.data instanceof ArrayBuffer) {
+          handlers.onMessage(new Uint8Array(event.data));
+        }
+      };
+      socket.onerror = () => {
+        if (!opened) {
+          reject(
+            new ClientSyncError(
+              'sync.transport_failed',
+              'remote operation realtime socket failed to connect',
+              true,
+            ),
+          );
+        }
+        try {
+          socket.close();
+        } catch {
+          handlers.onClose?.();
+        }
+      };
+      socket.onclose = () => {
+        if (!opened) {
+          reject(
+            new ClientSyncError(
+              'sync.transport_failed',
+              'remote operation realtime socket closed while connecting',
+              true,
+            ),
+          );
+        }
+        handlers.onClose?.();
+      };
+    });
+}
+
 /**
  * §5.5 direct endpoint with the `X-Syncular-Scopes` re-authorization
  * header, plus the §5.4 `fetchUrl` capability (advertises accept bit 3).
@@ -224,8 +298,10 @@ export function webSocketRealtimeConnector(
   return (handlers) =>
     new Promise((resolve, reject) => {
       const socket = new WebSocket(realtimeUrl);
+      let opened = false;
       socket.binaryType = 'arraybuffer';
       socket.onopen = () => {
+        opened = true;
         resolve({
           send: (text) => socket.send(text),
           sendBytes: (bytes) => {
@@ -239,15 +315,31 @@ export function webSocketRealtimeConnector(
         else handlers.onBinary(new Uint8Array(event.data as ArrayBuffer));
       };
       socket.onerror = () => {
-        reject(
-          new ClientSyncError(
-            'sync.transport_failed',
-            'realtime socket failed to connect',
-            true,
-          ),
-        );
+        if (!opened) {
+          reject(
+            new ClientSyncError(
+              'sync.transport_failed',
+              'realtime socket failed to connect',
+              true,
+            ),
+          );
+        }
+        try {
+          socket.close();
+        } catch {
+          handlers.onClose?.();
+        }
       };
       socket.onclose = () => {
+        if (!opened) {
+          reject(
+            new ClientSyncError(
+              'sync.transport_failed',
+              'realtime socket closed while connecting',
+              true,
+            ),
+          );
+        }
         handlers.onClose?.();
       };
     });

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';
@@ -29,6 +30,7 @@ export * from './outbox';
 export * from './outcomes';
 export * from './query-guard';
 export * from './reactive-store';
+export * from './remote';
 export * from './realtime-supervisor';
 export * from './schema';
 export * from './sql-tag';

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