@syncular/client 0.15.4 → 0.15.6

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/client.js

@@ -17,7 +17,7 @@ import { singleOwnerLock, } from './leader-lock.js';
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
-import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
+import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
 import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
 /**
@@ -144,7 +144,10 @@ export class SyncClient {
             return;
         const lock = this.#config.leaderLock ?? singleOwnerLock();
         this.#lease = await lock.acquire(this.#config.lockName ?? 'syncular-leader');
-        ensureLocalSchema(this.#db, this.#schema);
+        // Bookkeeping must exist before we inspect the persisted schema marker.
+        // Do not materialize new app indexes/FTS projections yet: on a version
+        // bump they may reference columns that only exist after the reset.
+        ensureLocalBookkeepingSchema(this.#db);
         if (this.#hasBlobs)
             ensureBlobSchema(this.#db);
         this.#db.transaction(() => {
@@ -214,12 +217,16 @@ export class SyncClient {
         const markerJson = getMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY);
         if (markerJson === undefined) {
             // Fresh install: the tables just created match the running code.
+            ensureLocalSyncedSchema(this.#db, this.#schema);
             setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
             return;
         }
         const marker = Number(markerJson);
-        if (marker === this.#schema.version)
+        if (marker === this.#schema.version) {
+            // Same-version opens remain self-healing for absent tables/indexes.
+            ensureLocalSyncedSchema(this.#db, this.#schema);
             return;
+        }
         this.#runSchemaReset();
     }
     /**

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/schema.d.ts

@@ -103,9 +103,19 @@ export declare function localColumnType(column: RowColumn): RowColumn['type'];
 /** §7.4.1 persisted local schema-version marker (`_syncular_meta` key). */
 export declare const LOCAL_SCHEMA_VERSION_KEY = "localSchemaVersion";
 /**
- * Create the synced tables plus client bookkeeping tables (outbox,
- * subscription state, meta). Idempotent.
+ * Create only the application-owned synced tables, indexes, and FTS
+ * projections. Callers opening an existing database must compare the
+ * persisted schema version before invoking this: a new index may reference a
+ * column that does not exist until the schema-bump reset recreates the table.
  */
+export declare function ensureLocalSyncedSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
+/**
+ * Create the protected Syncular bookkeeping tables without touching the
+ * application schema. This makes the persisted schema-version marker
+ * readable before any new application index or FTS projection is applied.
+ */
+export declare function ensureLocalBookkeepingSchema(db: ClientDatabase): void;
+/** Create both application and protected bookkeeping tables. */
 export declare function ensureLocalSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
 /**
  * §7.4.3 reset: drop every synced local table (whatever the *previous*

package/dist/schema.js

@@ -241,10 +241,12 @@ function createFtsProjection(db, table, index) {
     }
 }
 /**
- * Create the synced tables plus client bookkeeping tables (outbox,
- * subscription state, meta). Idempotent.
+ * Create only the application-owned synced tables, indexes, and FTS
+ * projections. Callers opening an existing database must compare the
+ * persisted schema version before invoking this: a new index may reference a
+ * column that does not exist until the schema-bump reset recreates the table.
  */
-export function ensureLocalSchema(db, schema) {
+export function ensureLocalSyncedSchema(db, schema) {
     db.transaction(() => {
         for (const table of schema.tables.values()) {
             createSyncedTable(db, table);
@@ -254,6 +256,15 @@ export function ensureLocalSchema(db, schema) {
                 createFtsProjection(db, table, index);
             }
         }
+    });
+}
+/**
+ * Create the protected Syncular bookkeeping tables without touching the
+ * application schema. This makes the persisted schema-version marker
+ * readable before any new application index or FTS projection is applied.
+ */
+export function ensureLocalBookkeepingSchema(db) {
+    db.transaction(() => {
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
         db.exec(`INSERT OR IGNORE INTO _syncular_meta(key, value) VALUES ('localRevision', '0')`);
@@ -316,6 +327,11 @@ export function ensureLocalSchema(db, schema) {
       effective_scopes TEXT NOT NULL)`);
     });
 }
+/** Create both application and protected bookkeeping tables. */
+export function ensureLocalSchema(db, schema) {
+    ensureLocalBookkeepingSchema(db);
+    ensureLocalSyncedSchema(db, schema);
+}
 /** Bookkeeping tables the schema-bump reset (§7.4.3) MUST NOT drop. */
 const RESERVED_TABLE_PREFIX = '_syncular_';
 /**

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.4",
+  "version": "0.15.6",
   "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.4"
+    "@syncular/core": "0.15.6"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.4",
+    "@syncular/server": "0.15.6",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -114,7 +114,8 @@ import {
   type CompiledClientTable,
   compileClientSchema,
   dropAndRecreateSyncedTables,
-  ensureLocalSchema,
+  ensureLocalBookkeepingSchema,
+  ensureLocalSyncedSchema,
   fromSqlValue,
   jsonToRowValue,
   LOCAL_SCHEMA_VERSION_KEY,
@@ -544,7 +545,10 @@ export class SyncClient {
     this.#lease = await lock.acquire(
       this.#config.lockName ?? 'syncular-leader',
     );
-    ensureLocalSchema(this.#db, this.#schema);
+    // Bookkeeping must exist before we inspect the persisted schema marker.
+    // Do not materialize new app indexes/FTS projections yet: on a version
+    // bump they may reference columns that only exist after the reset.
+    ensureLocalBookkeepingSchema(this.#db);
     if (this.#hasBlobs) ensureBlobSchema(this.#db);
     this.#db.transaction(() => {
       pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
@@ -622,11 +626,16 @@ export class SyncClient {
     const markerJson = getMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY);
     if (markerJson === undefined) {
       // Fresh install: the tables just created match the running code.
+      ensureLocalSyncedSchema(this.#db, this.#schema);
       setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
       return;
     }
     const marker = Number(markerJson);
-    if (marker === this.#schema.version) return;
+    if (marker === this.#schema.version) {
+      // Same-version opens remain self-healing for absent tables/indexes.
+      ensureLocalSyncedSchema(this.#db, this.#schema);
+      return;
+    }
     this.#runSchemaReset();
   }
 

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/schema.ts

@@ -395,10 +395,12 @@ function createFtsProjection(
 }
 
 /**
- * Create the synced tables plus client bookkeeping tables (outbox,
- * subscription state, meta). Idempotent.
+ * Create only the application-owned synced tables, indexes, and FTS
+ * projections. Callers opening an existing database must compare the
+ * persisted schema version before invoking this: a new index may reference a
+ * column that does not exist until the schema-bump reset recreates the table.
  */
-export function ensureLocalSchema(
+export function ensureLocalSyncedSchema(
   db: ClientDatabase,
   schema: CompiledClientSchema,
 ): void {
@@ -411,6 +413,16 @@ export function ensureLocalSchema(
         createFtsProjection(db, table, index);
       }
     }
+  });
+}
+
+/**
+ * Create the protected Syncular bookkeeping tables without touching the
+ * application schema. This makes the persisted schema-version marker
+ * readable before any new application index or FTS projection is applied.
+ */
+export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
+  db.transaction(() => {
     db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
     db.exec(
@@ -477,6 +489,15 @@ export function ensureLocalSchema(
   });
 }
 
+/** Create both application and protected bookkeeping tables. */
+export function ensureLocalSchema(
+  db: ClientDatabase,
+  schema: CompiledClientSchema,
+): void {
+  ensureLocalBookkeepingSchema(db);
+  ensureLocalSyncedSchema(db, schema);
+}
+
 /** Bookkeeping tables the schema-bump reset (§7.4.3) MUST NOT drop. */
 const RESERVED_TABLE_PREFIX = '_syncular_';
 

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);
   }