@syncular/client 0.22.0 → 0.23.0

package/src/query-guard.ts

@@ -17,6 +17,11 @@
  * The guard only fronts the PUBLIC `client.query()` — engine-internal reads
  * call the `ClientDatabase` directly and are trusted, so they are never
  * routed through here.
+ *
+ * RFC 0005 previously added a third rule here, denying reads of its container
+ * table by root page. That table now lives in its own database file and is not
+ * on the connection `query()` uses, so there is nothing left to guard and the
+ * rule was removed with its EXPLAIN plumbing.
  */
 
 /** Verbs a read-only query may begin with (lowercased). */

package/src/schema.ts

@@ -620,8 +620,10 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
  * generated schema created — discovered from `sqlite_master`, since a
  * bump may add/remove tables) and recreate the synced tables from the
  * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
- * subscriptions, blob cache) are preserved. Caller owns the surrounding
- * transaction and the subscription-state reset (state.ts).
+ * subscriptions, blob cache) are preserved. RFC 0005's container is not
+ * reachable from here: it lives in its own database file, so this reset cannot
+ * see or destroy it. Caller owns the surrounding transaction and the
+ * subscription-state reset (state.ts).
  */
 export function dropAndRecreateSyncedTables(
   db: ClientDatabase,

package/src/wasm-database.ts

@@ -27,6 +27,7 @@ import {
   assertImageAlias,
   type ClientDatabase,
   runTransaction,
+  type SiblingDatabase,
   type SqlRow,
   type SqlValue,
 } from './database';
@@ -51,6 +52,9 @@ interface Oo1Database {
 
 interface SahPoolUtil {
   OpfsSAHPoolDb: new (filename: string) => Oo1Database;
+  /** RFC 0005: the runtime exposes naming and removal on the pool util. */
+  getFileNames(): string[];
+  unlink(filename: string): boolean;
 }
 
 interface SqliteIoMethods {
@@ -116,11 +120,18 @@ function coerceParams(params: readonly SqlValue[]): unknown[] {
 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;
   #tx = { depth: 0 };
 
-  constructor(db: Oo1Database, sqlite3: Sqlite3Static) {
+  constructor(
+    db: Oo1Database,
+    sqlite3: Sqlite3Static,
+    sah?: { readonly util: SahPoolUtil },
+  ) {
     this.#db = db;
     this.#sqlite3 = sqlite3;
+    this.#sah = sah;
   }
 
   exec(sql: string, params: readonly SqlValue[] = []): void {
@@ -147,6 +158,39 @@ class WasmClientDatabase implements ClientDatabase {
     return runTransaction(this.#tx, (sql) => this.exec(sql), fn);
   }
 
+  /**
+   * RFC 0005: a second named file on the same SAH pool directory. The pool
+   * forbids two live instances per directory and charges two slots per
+   * writable database (`.db` plus its transient `-journal`), which is why the
+   * pool's initial capacity must cover three. Removal is the pool's `unlink`,
+   * never OPFS `removeEntry` (the pool stores an opaque entry).
+   */
+  openSibling(name: string): SiblingDatabase | undefined {
+    const sah = this.#sah;
+    if (sah === undefined) return undefined;
+    const fileName = `/${name}.db`;
+    const db = new sah.util.OpfsSAHPoolDb(fileName);
+    try {
+      configureSahCrashRecovery(db, this.#sqlite3);
+    } catch (error) {
+      db.close();
+      throw error;
+    }
+    return {
+      database: new WasmClientDatabase(db, this.#sqlite3),
+      close: () => db.close(),
+      removeFile: () => {
+        sah.util.unlink(fileName);
+      },
+    };
+  }
+
+  siblingExists(name: string): boolean {
+    const sah = this.#sah;
+    if (sah === undefined) return false;
+    return sah.util.getFileNames().includes(`/${name}.db`);
+  }
+
   /**
    * §5.3 image import at near-file-copy speed: attach an empty in-memory
    * schema, then `sqlite3_deserialize` the image bytes into it (the
@@ -274,6 +318,69 @@ function opfsSahPoolError(error: unknown, directory: string): ClientSyncError {
   );
 }
 
+/** sqlite-wasm's default SAH pool capacity. */
+const SAH_POOL_DEFAULT_CAPACITY = 6;
+/**
+ * RFC 0005: each writable database consumes two slots (`.db` plus its
+ * transient `-journal`), so a replica plus one container file needs three.
+ * Exhaustion is a loud `SQLITE_CANTOPEN` ("SAH pool is full") that names the
+ * missing journal, not corruption — raise the floor rather than discover it.
+ */
+const SAH_POOL_MIN_CAPACITY = 3;
+
+/**
+ * Do this before the first SQL statement, when SQLite checks for a hot
+ * journal. The SAH-pool callback in sqlite-wasm 3.53 reports a reserved lock
+ * unconditionally, which suppresses crash rollback. The pool already excludes
+ * other owners; report no competing writer, as the other OPFS VFS does. Keep
+ * DELETE/FULL and the existing database/journal files. Shared by the replica
+ * and every RFC 0005 sibling file.
+ */
+function configureSahCrashRecovery(
+  db: Oo1Database,
+  sqlite3: Sqlite3Static,
+): void {
+  const { capi, wasm } = sqlite3;
+  const stack = wasm.pstack.pointer;
+  try {
+    const output = wasm.pstack.allocPtr();
+    if (
+      db.pointer === undefined ||
+      capi.sqlite3_file_control(
+        db.pointer,
+        'main',
+        capi.SQLITE_FCNTL_FILE_POINTER,
+        output,
+      ) !== 0 ||
+      !wasm.peekPtr(output)
+    ) {
+      throw new ClientSyncError(
+        STORAGE_UNAVAILABLE_CODE,
+        'Could not configure OPFS crash recovery',
+      );
+    }
+    const file = new capi.sqlite3_file(wasm.peekPtr(output));
+    const methodsPointer = file.$pMethods;
+    file.dispose(); // Borrowed struct view; SQLite still owns the file.
+    if (!methodsPointer) {
+      throw new ClientSyncError(
+        STORAGE_UNAVAILABLE_CODE,
+        'Could not configure OPFS crash recovery',
+      );
+    }
+    if (!sahIoMethods.has(methodsPointer)) {
+      const methods = new capi.sqlite3_io_methods(methodsPointer);
+      methods.installMethod('xCheckReservedLock', (_file, reserved) => {
+        wasm.poke32(reserved, 0);
+        return 0;
+      });
+      sahIoMethods.set(methodsPointer, methods);
+    }
+  } finally {
+    wasm.pstack.restore(stack);
+  }
+}
+
 /**
  * THE reload-persistent browser mode: a named database on OPFS via the
  * `opfs-sahpool` VFS. Worker-context only — not because SAHPool requires
@@ -329,9 +436,10 @@ export async function openPersistentWasmDatabase(
         // 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 }
-          : {}),
+        initialCapacity: Math.max(
+          options?.initialCapacity ?? SAH_POOL_DEFAULT_CAPACITY,
+          SAH_POOL_MIN_CAPACITY,
+        ),
       })
       .catch((error: unknown) => {
         sahPools.delete(directory);
@@ -341,52 +449,11 @@ export async function openPersistentWasmDatabase(
   }
   const util = await pool;
   const db = new util.OpfsSAHPoolDb(`/${name}.db`);
-  const { capi, wasm } = sqlite3;
-  const stack = wasm.pstack.pointer;
   try {
-    // Do this before the first SQL statement, when SQLite checks for a hot
-    // journal. The SAH-pool callback in sqlite-wasm 3.53 reports a reserved
-    // lock unconditionally, which suppresses crash rollback. The pool already
-    // excludes other owners; report no competing writer, as the other OPFS
-    // VFS does. Keep DELETE/FULL and the existing database/journal files.
-    const output = wasm.pstack.allocPtr();
-    if (
-      db.pointer === undefined ||
-      capi.sqlite3_file_control(
-        db.pointer,
-        'main',
-        capi.SQLITE_FCNTL_FILE_POINTER,
-        output,
-      ) !== 0 ||
-      !wasm.peekPtr(output)
-    ) {
-      throw new ClientSyncError(
-        STORAGE_UNAVAILABLE_CODE,
-        'Could not configure OPFS crash recovery',
-      );
-    }
-    const file = new capi.sqlite3_file(wasm.peekPtr(output));
-    const methodsPointer = file.$pMethods;
-    file.dispose(); // Borrowed struct view; SQLite still owns the file.
-    if (!methodsPointer) {
-      throw new ClientSyncError(
-        STORAGE_UNAVAILABLE_CODE,
-        'Could not configure OPFS crash recovery',
-      );
-    }
-    if (!sahIoMethods.has(methodsPointer)) {
-      const methods = new capi.sqlite3_io_methods(methodsPointer);
-      methods.installMethod('xCheckReservedLock', (_file, reserved) => {
-        wasm.poke32(reserved, 0);
-        return 0;
-      });
-      sahIoMethods.set(methodsPointer, methods);
-    }
-    return new WasmClientDatabase(db, sqlite3);
+    configureSahCrashRecovery(db, sqlite3);
+    return new WasmClientDatabase(db, sqlite3, { util });
   } catch (error) {
     db.close();
     throw error;
-  } finally {
-    wasm.pstack.restore(stack);
   }
 }

package/src/worker-entry.ts

@@ -347,6 +347,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       ...(config.securityPreflight !== undefined
         ? { securityPreflight: config.securityPreflight }
         : {}),
+      ...(config.previousVersionContext !== undefined
+        ? { previousVersionContext: config.previousVersionContext }
+        : {}),
       onSyncNeeded: (reason) => {
         post({ t: 'event', event: { kind: 'sync-needed', reason } });
         consumeSyncIntent({ kind: 'interactive' });
@@ -446,6 +449,10 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     purgeLocalData: (input) => requireClient().purgeLocalData(input),
     rebootstrapLocalData: (input) =>
       requireClient().rebootstrapLocalData(input),
+    previousVersionSnapshot: (spec) =>
+      requireClient().previousVersionSnapshot(spec),
+    previousVersionAudit: () => requireClient().previousVersionAudit(),
+    previousVersionDiscard: () => requireClient().previousVersionDiscard(),
     sync: () => {
       const running = requireClient();
       return serializedSync(() => running.sync());
@@ -512,13 +519,18 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     },
   };
 
-  // Local purge/rebootstrap rewrite the same durable state an in-flight
-  // sync round captured at send time; running their RPCs on the sync chain
-  // orders them against RPC- and auto-driven rounds (the client core's
-  // reset fence covers hosts that call the core directly).
+  // Local purge/rebootstrap/discard rewrite the same durable state an
+  // in-flight sync round captured at send time, and the RFC 0005 reads observe
+  // (and can themselves trigger the discard of) that same previous-version
+  // container. Running all of them on the sync chain orders them against RPC-
+  // and auto-driven rounds (the client core's reset fence covers hosts that
+  // call the core directly).
   const syncChainMethods: ReadonlySet<WorkerMethod> = new Set<WorkerMethod>([
     'purgeLocalData',
     'rebootstrapLocalData',
+    'previousVersionSnapshot',
+    'previousVersionAudit',
+    'previousVersionDiscard',
   ]);
 
   async function dispatch(message: WorkerCallMessage): Promise<unknown> {

package/src/worker-host.ts

@@ -38,6 +38,7 @@ import type {
   RejectionRecord,
   SecurityLifecycle,
   SubscribeInput,
+  SyncClientConfig,
   SyncClientLimits,
   SyncSummary,
   WindowState,
@@ -89,6 +90,14 @@ import type {
   CommitOutcomeQuery,
   ResolveCommitOutcomeInput,
 } from './outcomes';
+import {
+  decodePreviousVersionAuditResult,
+  decodePreviousVersionDiscardResult,
+  decodePreviousVersionSnapshot,
+  type PreviousVersionAudit,
+  type PreviousVersionReadSpec,
+  type PreviousVersionSnapshot,
+} from './previous-version';
 import type { ClientSchema } from './schema';
 import type { SubscriptionRecord } from './state';
 import type { WindowBase } from './window';
@@ -177,6 +186,11 @@ export interface SyncClientHandleConfig {
   readonly securityPreflight?: boolean;
   readonly clientId?: string;
   readonly limits?: SyncClientLimits;
+  /**
+   * RFC 0005 previous-version context, forwarded into the worker's
+   * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
+   */
+  readonly previousVersionContext?: SyncClientConfig['previousVersionContext'];
   /** Worker-side host loop (§8.4); default true. */
   readonly autoSync?: boolean;
   /** Default: Web Locks when available, else single-owner. */
@@ -546,6 +560,29 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     );
   }
 
+  async previousVersionSnapshot(
+    spec: PreviousVersionReadSpec,
+  ): Promise<PreviousVersionSnapshot> {
+    return decodePreviousVersionSnapshot(
+      await this.#call('previousVersionSnapshot', [spec]),
+    );
+  }
+
+  async previousVersionAudit(): Promise<PreviousVersionAudit | undefined> {
+    return decodePreviousVersionAuditResult(
+      await this.#call('previousVersionAudit', []),
+    );
+  }
+
+  async previousVersionDiscard(): Promise<{
+    present: boolean;
+    discarded: boolean;
+  }> {
+    return decodePreviousVersionDiscardResult(
+      await this.#call('previousVersionDiscard', []),
+    );
+  }
+
   sync(): Promise<SyncSummary> {
     return this.#call('sync', []);
   }
@@ -815,6 +852,9 @@ function buildInitConfig(config: SyncClientHandleConfig): WorkerInitConfig {
       : {}),
     ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
     ...(config.limits !== undefined ? { limits: config.limits } : {}),
+    ...(config.previousVersionContext !== undefined
+      ? { previousVersionContext: config.previousVersionContext }
+      : {}),
     ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
   };
 }

package/src/worker-protocol.ts

@@ -28,6 +28,7 @@ import type {
   QuerySnapshot,
   SecurityLifecycle,
   SubscribeInput,
+  SyncClientConfig,
   SyncClientLimits,
   SyncSummary,
   WindowState,
@@ -42,6 +43,11 @@ import type {
   LocalDataRebootstrapResult,
 } from './local-rebootstrap';
 import type { OutboxCommit } from './outbox';
+import type {
+  PreviousVersionAudit,
+  PreviousVersionReadSpec,
+  PreviousVersionSnapshot,
+} from './previous-version';
 import type { ClientSchema } from './schema';
 import type { SubscriptionRecord } from './state';
 import type { WindowBase } from './window';
@@ -102,6 +108,11 @@ export interface WorkerInitConfig {
   readonly securityPreflight?: boolean;
   readonly clientId?: string;
   readonly limits?: SyncClientLimits;
+  /**
+   * RFC 0005 previous-version context, forwarded verbatim into the worker's
+   * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
+   */
+  readonly previousVersionContext?: SyncClientConfig['previousVersionContext'];
   /**
    * Worker-side host loop (§8.4): coalesce interactive work immediately and
    * honor explicit background retry deadlines
@@ -151,6 +162,14 @@ export interface WorkerApi extends Omit<
   rebootstrapLocalData(
     input: LocalDataRebootstrapInput,
   ): LocalDataRebootstrapResult;
+  /** RFC 0005 D7: read the captured previous-schema rows for one table. */
+  previousVersionSnapshot(
+    spec: PreviousVersionReadSpec,
+  ): PreviousVersionSnapshot;
+  /** RFC 0005 D6: the advisory pre-reset compatibility audit, if recorded. */
+  previousVersionAudit(): PreviousVersionAudit | undefined;
+  /** RFC 0005 D9: the executable rollback step — drop the container. */
+  previousVersionDiscard(): { present: boolean; discarded: boolean };
   sync(): Promise<SyncSummary>;
   syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
   query(sql: string, params?: readonly SqlValue[]): SqlRow[];