@syncular/client 0.30.10 → 0.30.12

package/src/state.ts

@@ -5,6 +5,7 @@
  * exactly for that purpose.
  */
 import type { ScopeMap } from '@syncular/core';
+import type { CompiledClientSchema } from './schema';
 import type { ClientDatabase } from './database';
 import type { LocalRevision } from './invalidation';
 
@@ -65,7 +66,7 @@ export function getSubscription(
   db: ClientDatabase,
   id: string,
 ): SubscriptionRecord | undefined {
-  const row = db.query('SELECT * FROM _syncular_subscriptions WHERE id = ?', [
+  const row = db.query('SELECT * FROM _syncular_subscriptions WHERE id=?', [
     id,
   ])[0];
   return row === undefined ? undefined : rowToRecord(row);
@@ -76,10 +77,7 @@ export function saveSubscription(
   record: SubscriptionRecord,
 ): void {
   db.exec(
-    `INSERT OR REPLACE INTO _syncular_subscriptions(
-       id, tbl, requested_scopes, params, cursor, bootstrap_state,
-       effective_scopes, status, reason_code)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    'INSERT OR REPLACE INTO _syncular_subscriptions(id,tbl,requested_scopes,params,cursor,bootstrap_state,effective_scopes,status,reason_code)VALUES(?,?,?,?,?,?,?,?,?)',
     [
       record.id,
       record.table,
@@ -97,11 +95,11 @@ export function saveSubscription(
 }
 
 export function deleteSubscription(db: ClientDatabase, id: string): void {
-  db.exec('DELETE FROM _syncular_subscriptions WHERE id = ?', [id]);
+  db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
 }
 
 /**
- * §7.4.3 reset: keep every subscription REGISTRATION (id, table,
+ * §7.4.3 reset: keep compatible subscription REGISTRATIONS (id, table,
  * requested scopes, params — the app's declared intent) but discard all
  * synced state (cursor → -1, no resume token, no effective-scope map,
  * status → active), so the next round fresh-bootstraps exactly the
@@ -109,56 +107,115 @@ export function deleteSubscription(db: ClientDatabase, id: string): void {
  */
 export function resetSubscriptionsForBump(db: ClientDatabase): void {
   db.exec(
-    `UPDATE _syncular_subscriptions
-       SET cursor = -1, bootstrap_state = NULL, effective_scopes = NULL,
-           status = 'active', reason_code = NULL`,
+    "UPDATE _syncular_subscriptions SET cursor=-1,bootstrap_state=NULL,effective_scopes=NULL,status='active',reason_code=NULL",
   );
 }
 
-/**
- * Remove registrations whose table no longer exists in the running schema.
- * Keeping one would make every subsequent pull fail with
- * `sync.unknown_table`. Window bookkeeping belongs to the registration and
- * is removed with it. The caller supplies its startup subscription snapshot
- * so pruning and startup-work detection stay a single read.
- */
+type ScopeDeclarations = Record<
+  string,
+  Record<string, readonly [string, string]>
+>;
+
+/** Persist declarations separately from the previous-version row descriptor. */
+export function saveSubscriptionScopeSchema(
+  db: ClientDatabase,
+  schema: CompiledClientSchema,
+): void {
+  const declarations: ScopeDeclarations = {};
+  for (const table of schema.tables.values()) {
+    declarations[table.name] = Object.fromEntries(
+      [...table.scopeColumnByVariable].map(([variable, column]) => [
+        variable,
+        [table.scopePrefixByVariable.get(variable)!, column],
+      ]),
+    );
+  }
+  setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
+}
+
+/** Drop incompatible registrations and their windows; never translate scopes. */
 export function pruneUnknownSubscriptions(
   db: ClientDatabase,
   subscriptions: readonly SubscriptionRecord[],
-  tableNames: ReadonlySet<string>,
+  schema: CompiledClientSchema,
+  bump = false,
 ): SubscriptionRecord[] {
-  const retained = subscriptions.filter((record) =>
-    tableNames.has(record.table),
+  const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
+  const previous =
+    stored === undefined
+      ? undefined
+      : (JSON.parse(stored) as ScopeDeclarations);
+  const compatible = (
+    record: Pick<SubscriptionRecord, 'table' | 'scopes'>,
+  ): boolean => {
+    const table = schema.tables.get(record.table);
+    if (table === undefined) return false;
+    const variables = Object.keys(record.scopes);
+    if (
+      !variables.every((variable) => table.scopeColumnByVariable.has(variable))
+    )
+      return false;
+    if (!bump) return true;
+    // An old binary stored no declaration evidence. Re-registration is required
+    // at a bump: matching names cannot prove unchanged column/prefix meaning.
+    const old = previous?.[record.table];
+    if (old === undefined) return false;
+    const compared =
+      variables.length === 0
+        ? [
+            ...new Set([
+              ...Object.keys(old),
+              ...table.scopeColumnByVariable.keys(),
+            ]),
+          ]
+        : variables;
+    return compared.every(
+      (variable) =>
+        old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
+        old[variable]?.[1] === table.scopeColumnByVariable.get(variable),
+    );
+  };
+  const retained = subscriptions.filter(compatible);
+  const staleIds = new Set(
+    subscriptions
+      .filter((record) => !compatible(record))
+      .map((record) => record.id),
   );
-  const staleIds = subscriptions
-    .filter((record) => !tableNames.has(record.table))
-    .map((record) => record.id);
-  // A redundant subscription scan plus an empty write transaction cut the
-  // fresh-client bootstrap lane by more than half on bun:sqlite. The supplied
-  // snapshot and this branch are synchronous, so no application work can
-  // interleave before a real pruning transaction begins.
-  if (staleIds.length === 0) return retained;
+  // Shrinking a pinned window already removed its registration. Its deferred
+  // eviction still carries the old scope declaration and needs the same fence.
+  for (const row of db.query(
+    'SELECT sub_id,tbl,effective_scopes FROM _syncular_window_pending_evict',
+  )) {
+    if (
+      !compatible({
+        table: String(row.tbl),
+        scopes: JSON.parse(String(row.effective_scopes)) as ScopeMap,
+      })
+    )
+      staleIds.add(String(row.sub_id));
+  }
+  if (staleIds.size === 0) return retained;
   db.transaction(() => {
     for (const id of staleIds) {
-      db.exec('DELETE FROM _syncular_windows WHERE sub_id = ?', [id]);
-      db.exec('DELETE FROM _syncular_window_pending_evict WHERE sub_id = ?', [
+      db.exec('DELETE FROM _syncular_windows WHERE sub_id=?', [id]);
+      db.exec('DELETE FROM _syncular_window_pending_evict WHERE sub_id=?', [
         id,
       ]);
-      db.exec('DELETE FROM _syncular_subscriptions WHERE id = ?', [id]);
+      db.exec('DELETE FROM _syncular_subscriptions WHERE id=?', [id]);
     }
   });
   return retained;
 }
 
 export function getMeta(db: ClientDatabase, key: string): string | undefined {
-  const row = db.query('SELECT value FROM _syncular_meta WHERE key = ?', [
+  const row = db.query('SELECT value FROM _syncular_meta WHERE key=?', [
     key,
   ])[0];
   return row === undefined ? undefined : (row.value as string);
 }
 
 export function setMeta(db: ClientDatabase, key: string, value: string): void {
-  db.exec('INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?, ?)', [
+  db.exec('INSERT OR REPLACE INTO _syncular_meta(key,value)VALUES(?,?)', [
     key,
     value,
   ]);

package/src/wasm-database.ts

@@ -22,6 +22,7 @@
  * `ClientDatabase`. Browser-only — exercised by the demo, never imported
  * by bun tests (subpath export `@syncular/client/wasm`).
  */
+import { webLocksLeaderLock, type LeaderLease } from './leader-lock';
 import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
 import {
   assertImageAlias,
@@ -56,6 +57,8 @@ interface SahPoolUtil {
   /** RFC 0005: the runtime exposes naming and removal on the pool util. */
   getFileNames(): string[];
   unlink(filename: string): boolean;
+  pauseVfs(): unknown;
+  unpauseVfs(): Promise<unknown>;
 }
 
 interface SqliteIoMethods {
@@ -122,13 +125,16 @@ class WasmClientDatabase implements ClientDatabase {
   readonly #db: Oo1Database;
   readonly #sqlite3: Sqlite3Static;
   /** RFC 0005: present only for a persistent OPFS database. */
-  readonly #sah: { readonly util: SahPoolUtil } | undefined;
+  readonly #sah:
+    | { readonly util: SahPoolUtil; readonly lease: LeaderLease }
+    | undefined;
+  #closed = false;
   #tx = { depth: 0 };
 
   constructor(
     db: Oo1Database,
     sqlite3: Sqlite3Static,
-    sah?: { readonly util: SahPoolUtil },
+    sah?: { readonly util: SahPoolUtil; readonly lease: LeaderLease },
   ) {
     this.#db = db;
     this.#sqlite3 = sqlite3;
@@ -236,7 +242,13 @@ class WasmClientDatabase implements ClientDatabase {
   }
 
   close(): void {
+    if (this.#closed) return;
     this.#db.close();
+    // DB.close() leaves the SAH pool live. Close siblings first, then pause the
+    // VFS without deleting files, before releasing this worker's physical lock.
+    this.#sah?.util.pauseVfs();
+    this.#closed = true;
+    void this.#sah?.lease.release();
   }
 }
 
@@ -420,37 +432,52 @@ export async function openPersistentWasmDatabase(
         'in-memory fallback for persistent mode.',
     );
   }
-  const sqlite3 = await initSqlite3();
-  const directory = options?.directory ?? `.syncular/${name}`;
-  let pool = sahPools.get(directory);
-  if (pool === undefined) {
-    pool = sqlite3
-      .installOpfsSAHPoolVfs({
-        // 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,
-        initialCapacity: Math.max(
-          options?.initialCapacity ?? SAH_POOL_DEFAULT_CAPACITY,
-          SAH_POOL_MIN_CAPACITY,
-        ),
-      })
-      .catch((error: unknown) => {
-        sahPools.delete(directory);
-        throw opfsSahPoolError(error, directory);
-      });
-    sahPools.set(directory, pool);
+  if (!navigator.locks) {
+    throw new ClientSyncError(
+      STORAGE_UNAVAILABLE_CODE,
+      'Persistent OPFS storage requires Web Locks',
+    );
   }
-  const util = await pool;
-  const db = new util.OpfsSAHPoolDb(`/${name}.db`);
+  const directory = (options?.directory ?? `.syncular/${name}`).replace(
+    /^\/+|\/+$/g,
+    '',
+  );
+  // The document's leader lease can end before its worker's SAHs close. This
+  // worker-owned lock has exactly the same lifetime as the physical pool.
+  const lease = await webLocksLeaderLock().acquire(
+    `syncular-opfs/${directory}`,
+  );
+  let util: SahPoolUtil | undefined;
+  let db: Oo1Database | undefined;
   try {
+    const sqlite3 = await initSqlite3();
+    let pool = sahPools.get(directory);
+    if (pool === undefined) {
+      pool = sqlite3
+        .installOpfsSAHPoolVfs({
+          name: `syncular-sahpool-${directory.replace(/[^A-Za-z0-9]+/g, '-')}`,
+          directory,
+          forceReinitIfPreviouslyFailed: true,
+          initialCapacity: Math.max(
+            options?.initialCapacity ?? SAH_POOL_DEFAULT_CAPACITY,
+            SAH_POOL_MIN_CAPACITY,
+          ),
+        })
+        .catch((error: unknown) => {
+          sahPools.delete(directory);
+          throw opfsSahPoolError(error, directory);
+        });
+      sahPools.set(directory, pool);
+    }
+    util = await pool;
+    await util.unpauseVfs();
+    db = new util.OpfsSAHPoolDb(`/${name}.db`);
     configureSahCrashRecovery(db, sqlite3);
-    return new WasmClientDatabase(db, sqlite3, { util });
+    return new WasmClientDatabase(db, sqlite3, { util, lease });
   } catch (error) {
-    db.close();
+    db?.close();
+    util?.pauseVfs();
+    await lease.release();
     throw error;
   }
 }

package/src/worker-host.ts

@@ -804,11 +804,33 @@ async function startWorkerCore(options: {
   const worker = config.worker();
   const pending = new Map<number, Pending>();
   const nextId = { value: 1 };
+  let terminated = false;
+  let rejectReady: ((error: Error) => void) | undefined;
+  const closedError = new ClientSyncError(
+    WORKER_FAILED_CODE,
+    'the handle was closed',
+  );
+  const terminate = () => {
+    if (terminated) return;
+    terminated = true;
+    globalThis.removeEventListener?.('pagehide', terminate);
+    bridge?.close();
+    worker.terminate();
+    rejectReady?.(closedError);
+    for (const entry of pending.values()) entry.reject(closedError);
+    pending.clear();
+    void lease.release();
+  };
+  // Installed before bootstrap starts: pagehide must also terminate a worker
+  // whose first open/import is still pending. Termination closes its SAHs and
+  // releases its physical Web Lock; the next document waits for that lock.
+  globalThis.addEventListener?.('pagehide', terminate);
 
   const invoke = (
     method: string,
     args: readonly unknown[],
   ): Promise<unknown> => {
+    if (terminated) return Promise.reject(closedError);
     const id = nextId.value++;
     return new Promise<unknown>((resolve, reject) => {
       pending.set(id, { resolve, reject });
@@ -824,6 +846,7 @@ async function startWorkerCore(options: {
   let bridge: LeaderBridge | undefined;
 
   const ready = new Promise<void>((resolve, reject) => {
+    rejectReady = reject;
     const onMessage = (event: MessageEvent) => {
       const message = event.data as WorkerToMainMessage;
       switch (message.t) {
@@ -889,26 +912,25 @@ async function startWorkerCore(options: {
       invoke,
       bridge,
       lease,
-      close: async (terminate) => {
+      close: async (terminateWorker) => {
+        if (terminated) return;
         bridge?.close();
         try {
           await invoke('close', []);
         } catch {
-          // Closing a wedged worker still terminates it below.
+          // A terminated or failed worker has no further close RPC to service.
+        }
+        if (terminateWorker) terminate();
+        else {
+          globalThis.removeEventListener?.('pagehide', terminate);
+          for (const entry of pending.values()) entry.reject(closedError);
+          pending.clear();
+          await lease.release();
         }
-        if (terminate) worker.terminate();
-        const closedError = new ClientSyncError(
-          WORKER_FAILED_CODE,
-          'the handle was closed',
-        );
-        for (const entry of pending.values()) entry.reject(closedError);
-        pending.clear();
-        await lease.release();
       },
     };
   } catch (error) {
-    worker.terminate();
-    await lease.release();
+    terminate();
     throw error;
   }
 }