@syncular/client 0.15.3 → 0.15.5

package/README.md

@@ -42,10 +42,8 @@ const handle = await createSyncClientHandle({
   },
 });
 if (handle.role === 'follower') {
-  // Another tab owns the core for this origin. With `multiTab: true`
-  // (below) this handle transparently proxies to that leader; without it,
-  // every call rejects with `client.not_leader` (a clear state, not a
-  // broken client).
+  // Another tab owns the core for this origin. The default multi-tab mode
+  // transparently proxies this handle to that leader.
 }
 await handle.subscribe({ id: 'todos', table: 'todos', scopes: { list_id: ['l1'] } });
 await handle.syncUntilIdle();
@@ -66,14 +64,13 @@ persists, on purpose, and that is the only main-thread mode.
 
 ## Multi-tab followers (TODO 3.2, REVISE B3)
 
-Pass `multiTab: true` and every tab of the same origin shares ONE core:
+By default, every tab of the same origin shares ONE core:
 one sync loop, one WebSocket, one OPFS database, N tabs.
 
 ```ts
 const handle = await createSyncClientHandle({
   worker: () => new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }),
   schema, database: { mode: 'persistent', name: 'app' }, endpoints,
-  multiTab: true,
   onRoleChange: (role) => console.log('now', role), // 'follower' → 'leader'
 });
 // handle.role is 'leader' or 'follower'; the API is identical either way.
@@ -115,9 +112,8 @@ forwards to the leader's single publisher; there is no per-tab presence
 peer. This is the honest model — the wire only ever sees one connection per
 device.
 
-With `multiTab` off (the default) the single-tab contract is unchanged: a
-losing tab is an `isLeader === false` handle whose calls reject with
-`client.not_leader`.
+Set `multiTab: false` to opt out. A losing tab then becomes an
+`isLeader === false` handle whose calls reject with `client.not_leader`.
 
 ## Durable commit outcomes
 
@@ -169,6 +165,30 @@ successful history may be dismissed. See SPEC §7.2.1.
 - `openPersistentWasmDatabase` refuses to run on the main thread — not a
   sahpool limitation, an enforcement of whole-core-in-a-worker.
 
+### OPFS ownership and startup recovery
+
+An OPFS SAH pool has exactly one live owner per storage directory. Syncular's
+default multi-tab mode prevents ordinary same-origin tabs from opening a second
+pool: followers proxy the one leader over `BroadcastChannel`. A collision can
+still happen during rapid hot-module replacement, or in an embedded/test host
+that shares OPFS data without sharing the same Web Locks and BroadcastChannel
+coordination domain.
+
+Pool acquisition failures surface as `ClientSyncError` with code
+`client.storage_busy` and `retryable === true`. Treat that as a startup state:
+close the competing instance or let it finish shutting down, then create the
+handle again. **Do not delete, rename, or silently replace the database with an
+in-memory one**; the local database and pending outbox may be perfectly healthy.
+Missing or obsolete OPFS APIs instead use the non-retryable
+`client.storage_unavailable` code.
+
+When using `@syncular/react`, `createSyncClientResource()` exposes `retry()` and
+passes the same action as the second argument to `SyncProvider.renderError`.
+Applications may use a small bounded backoff for errors whose `retryable` flag
+is true, followed by a visible manual retry. Preserve the resource across HMR
+or dispose the previous resource before replacing it so development reloads do
+not manufacture a second owner.
+
 ## Blob attachments (§5.9) — the client storage model
 
 File attachments (`blob_ref` columns) ride the `uploadBlob` / `fetchBlob` API

package/dist/errors.d.ts

@@ -1,6 +1,11 @@
+/** A persistent local store is temporarily owned by another live engine. */
+export declare const STORAGE_BUSY_CODE = "client.storage_busy";
+/** The browser cannot provide the persistent storage APIs Syncular requires. */
+export declare const STORAGE_UNAVAILABLE_CODE = "client.storage_unavailable";
 /**
- * Client-side errors. Protocol codes come from the SPEC.md §10 catalog;
- * the client never invents wire codes, it surfaces them.
+ * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
+ * unchanged. Host/runtime-only conditions may use the separate `client.*`
+ * namespace and never travel on the wire.
  */
 export declare class ClientSyncError extends Error {
     readonly name = "ClientSyncError";

package/dist/errors.js

@@ -1,6 +1,11 @@
+/** A persistent local store is temporarily owned by another live engine. */
+export const STORAGE_BUSY_CODE = 'client.storage_busy';
+/** The browser cannot provide the persistent storage APIs Syncular requires. */
+export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
 /**
- * Client-side errors. Protocol codes come from the SPEC.md §10 catalog;
- * the client never invents wire codes, it surfaces them.
+ * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
+ * unchanged. Host/runtime-only conditions may use the separate `client.*`
+ * namespace and never travel on the wire.
  */
 export class ClientSyncError extends Error {
     name = 'ClientSyncError';

package/dist/wasm-database.js

@@ -21,7 +21,7 @@
  */
 import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
 import { assertImageAlias, runTransaction, } from './database.js';
-import { ClientSyncError } from './errors.js';
+import { ClientSyncError, STORAGE_BUSY_CODE, STORAGE_UNAVAILABLE_CODE, } from './errors.js';
 function coerceParams(params) {
     return params.map((value) => {
         if (typeof value === 'boolean')
@@ -119,6 +119,19 @@ function inWorkerContext() {
 }
 /** One registered VFS per pool directory, reused across opens. */
 const sahPools = new Map();
+function opfsSahPoolError(error, directory) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const normalized = detail.toLowerCase();
+    if (normalized.includes('missing required opfs apis') ||
+        normalized.includes('opfs api is too old')) {
+        return new ClientSyncError(STORAGE_UNAVAILABLE_CODE, `Persistent OPFS storage is unavailable: ${detail}`);
+    }
+    return new ClientSyncError(STORAGE_BUSY_CODE, 'Could not acquire the persistent OPFS storage directory ' +
+        `${JSON.stringify(directory)}. Another live engine may still own its ` +
+        'SAH pool, or the browser may still be releasing it after a reload. ' +
+        'Close the other instance or retry after a short delay; do not delete ' +
+        `or rename the directory. Underlying error: ${detail}`, true);
+}
 /**
  * THE persistent browser mode: a named database on OPFS via the
  * `opfs-sahpool` VFS. Worker-context only — not because SAHPool requires
@@ -141,7 +154,7 @@ export async function openPersistentWasmDatabase(name, options) {
     }
     const storage = globalThis.navigator?.storage;
     if (typeof storage?.getDirectory !== 'function') {
-        throw new ClientSyncError('sync.invalid_request', 'OPFS is unavailable in this browser — the syncular support floor ' +
+        throw new ClientSyncError(STORAGE_UNAVAILABLE_CODE, 'OPFS is unavailable in this browser — the syncular support floor ' +
             'requires OPFS (~2023+ browsers). There is no IndexedDB or ' +
             'in-memory fallback for persistent mode.');
     }
@@ -154,14 +167,17 @@ export async function openPersistentWasmDatabase(name, options) {
             // VFS registration names must be unique per directory.
             name: `syncular-sahpool-${directory.replace(/[^A-Za-z0-9]+/g, '-')}`,
             directory,
+            // sqlite-wasm caches a rejected initialization promise by VFS name.
+            // Syncular removes its own rejected entry below, so allow a later
+            // open in the same worker to make a real attempt as well.
+            forceReinitIfPreviouslyFailed: true,
             ...(options?.initialCapacity !== undefined
                 ? { initialCapacity: options.initialCapacity }
                 : {}),
         })
             .catch((error) => {
             sahPools.delete(directory);
-            throw new ClientSyncError('sync.invalid_request', 'opfs-sahpool VFS failed to initialize (is OPFS available, and ' +
-                `is another live instance using directory ${JSON.stringify(directory)}?): ${String(error)}`);
+            throw opfsSahPoolError(error, directory);
         });
         sahPools.set(directory, pool);
     }

package/package.json

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

package/src/errors.ts

@@ -1,6 +1,13 @@
+/** A persistent local store is temporarily owned by another live engine. */
+export const STORAGE_BUSY_CODE = 'client.storage_busy';
+
+/** The browser cannot provide the persistent storage APIs Syncular requires. */
+export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
+
 /**
- * Client-side errors. Protocol codes come from the SPEC.md §10 catalog;
- * the client never invents wire codes, it surfaces them.
+ * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
+ * unchanged. Host/runtime-only conditions may use the separate `client.*`
+ * namespace and never travel on the wire.
  */
 export class ClientSyncError extends Error {
   override readonly name = 'ClientSyncError';

package/src/wasm-database.ts

@@ -27,7 +27,11 @@ import {
   type SqlRow,
   type SqlValue,
 } from './database';
-import { ClientSyncError } from './errors';
+import {
+  ClientSyncError,
+  STORAGE_BUSY_CODE,
+  STORAGE_UNAVAILABLE_CODE,
+} from './errors';
 
 /** Structural view of the sqlite3 oo1 surface this binding uses. */
 interface Oo1Database {
@@ -69,6 +73,7 @@ interface Sqlite3Static {
     name?: string;
     directory?: string;
     initialCapacity?: number;
+    forceReinitIfPreviouslyFailed?: boolean;
   }): Promise<SahPoolUtil>;
 }
 
@@ -209,6 +214,29 @@ function inWorkerContext(): boolean {
 /** One registered VFS per pool directory, reused across opens. */
 const sahPools = new Map<string, Promise<SahPoolUtil>>();
 
+function opfsSahPoolError(error: unknown, directory: string): ClientSyncError {
+  const detail = error instanceof Error ? error.message : String(error);
+  const normalized = detail.toLowerCase();
+  if (
+    normalized.includes('missing required opfs apis') ||
+    normalized.includes('opfs api is too old')
+  ) {
+    return new ClientSyncError(
+      STORAGE_UNAVAILABLE_CODE,
+      `Persistent OPFS storage is unavailable: ${detail}`,
+    );
+  }
+  return new ClientSyncError(
+    STORAGE_BUSY_CODE,
+    'Could not acquire the persistent OPFS storage directory ' +
+      `${JSON.stringify(directory)}. Another live engine may still own its ` +
+      'SAH pool, or the browser may still be releasing it after a reload. ' +
+      'Close the other instance or retry after a short delay; do not delete ' +
+      `or rename the directory. Underlying error: ${detail}`,
+    true,
+  );
+}
+
 /**
  * THE persistent browser mode: a named database on OPFS via the
  * `opfs-sahpool` VFS. Worker-context only — not because SAHPool requires
@@ -243,7 +271,7 @@ export async function openPersistentWasmDatabase(
   ).navigator?.storage;
   if (typeof storage?.getDirectory !== 'function') {
     throw new ClientSyncError(
-      'sync.invalid_request',
+      STORAGE_UNAVAILABLE_CODE,
       'OPFS is unavailable in this browser — the syncular support floor ' +
         'requires OPFS (~2023+ browsers). There is no IndexedDB or ' +
         'in-memory fallback for persistent mode.',
@@ -258,19 +286,17 @@ export async function openPersistentWasmDatabase(
         // VFS registration names must be unique per directory.
         name: `syncular-sahpool-${directory.replace(/[^A-Za-z0-9]+/g, '-')}`,
         directory,
+        // sqlite-wasm caches a rejected initialization promise by VFS name.
+        // Syncular removes its own rejected entry below, so allow a later
+        // open in the same worker to make a real attempt as well.
+        forceReinitIfPreviouslyFailed: true,
         ...(options?.initialCapacity !== undefined
           ? { initialCapacity: options.initialCapacity }
           : {}),
       })
       .catch((error: unknown) => {
         sahPools.delete(directory);
-        throw new ClientSyncError(
-          'sync.invalid_request',
-          'opfs-sahpool VFS failed to initialize (is OPFS available, and ' +
-            `is another live instance using directory ${JSON.stringify(
-              directory,
-            )}?): ${String(error)}`,
-        );
+        throw opfsSahPoolError(error, directory);
       });
     sahPools.set(directory, pool);
   }