@syncular/client 0.22.0 → 0.23.0

package/dist/query-guard.d.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.
  */
 /** Raised when `client.query()` is handed SQL it will not run. */
 export declare class RawSqlError extends Error {

package/dist/query-guard.js

@@ -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). */
 const READ_ONLY_VERBS = new Set([

package/dist/schema.d.ts

@@ -122,8 +122,10 @@ export declare function ensureLocalSchema(db: ClientDatabase, schema: CompiledCl
  * 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 declare function dropAndRecreateSyncedTables(db: ClientDatabase, schema: CompiledClientSchema): void;
 /** RowValue → SQL bind value for the local mirror tables. */

package/dist/schema.js

@@ -438,8 +438,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, schema) {
     // Drop virtual tables first. SQLite then removes their shadow tables as one

package/dist/wasm-database.js

@@ -35,10 +35,13 @@ function coerceParams(params) {
 class WasmClientDatabase {
     #db;
     #sqlite3;
+    /** RFC 0005: present only for a persistent OPFS database. */
+    #sah;
     #tx = { depth: 0 };
-    constructor(db, sqlite3) {
+    constructor(db, sqlite3, sah) {
         this.#db = db;
         this.#sqlite3 = sqlite3;
+        this.#sah = sah;
     }
     exec(sql, params = []) {
         this.#db.exec({
@@ -61,6 +64,40 @@ class WasmClientDatabase {
     transaction(fn) {
         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) {
+        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) {
+        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
@@ -138,6 +175,52 @@ function opfsSahPoolError(error, directory) {
         'Close the other instance or retry after a short delay; do not delete ' +
         `or rename the directory. Underlying error: ${detail}`, true);
 }
+/** 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, sqlite3) {
+    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
@@ -179,9 +262,7 @@ export async function openPersistentWasmDatabase(name, options) {
             // 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) => {
             sahPools.delete(directory);
@@ -191,41 +272,12 @@ export async function openPersistentWasmDatabase(name, options) {
     }
     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/dist/worker-entry.js

@@ -251,6 +251,9 @@ export function startSyncWorker(overrides = {}) {
             ...(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' });
@@ -342,6 +345,9 @@ export function startSyncWorker(overrides = {}) {
         },
         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());
@@ -407,13 +413,18 @@ export function startSyncWorker(overrides = {}) {
             database = undefined;
         },
     };
-    // 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 = new Set([
         'purgeLocalData',
         'rebootstrapLocalData',
+        'previousVersionSnapshot',
+        'previousVersionAudit',
+        'previousVersionDiscard',
     ]);
     async function dispatch(message) {
         const method = api[message.method];

package/dist/worker-host.d.ts

@@ -25,7 +25,7 @@ import type { PromiseMethods } from './client.js';
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
@@ -37,6 +37,7 @@ import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from
 import { type CrossTabChannel, FollowerLink, LeaderBridge, type LeadershipState } from './multi-tab.js';
 import type { OutboxCommit } from './outbox.js';
 import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
+import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
@@ -80,6 +81,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. */
@@ -206,6 +212,12 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
     }): Promise<string>;
     purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
     rebootstrapLocalData(input: LocalDataRebootstrapInput): Promise<LocalDataRebootstrapResult>;
+    previousVersionSnapshot(spec: PreviousVersionReadSpec): Promise<PreviousVersionSnapshot>;
+    previousVersionAudit(): Promise<PreviousVersionAudit | undefined>;
+    previousVersionDiscard(): Promise<{
+        present: boolean;
+        discarded: boolean;
+    }>;
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;

package/dist/worker-host.js

@@ -6,6 +6,7 @@ import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './i
 import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
 import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
 import { broadcastChannelFactory, FollowerLink, LeaderBridge, multiTabChannelName, newTabId, } from './multi-tab.js';
+import { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, } from './previous-version.js';
 import { NOT_LEADER_CODE, WORKER_FAILED_CODE, WORKER_RESTART_REQUIRED_CODE, } from './worker-protocol.js';
 const WORKER_BUNDLE_LOAD_FAILURE = /(?:failed to fetch dynamically imported module|error loading dynamically imported module|importing a module script failed|failed to load module script)/iu;
 /** Classify startup without echoing a chunk URL or bundler text to UI/logs. */
@@ -280,6 +281,15 @@ export class SyncClientHandle {
     async rebootstrapLocalData(input) {
         return decodeLocalDataRebootstrapResult(await this.#call('rebootstrapLocalData', [input]));
     }
+    async previousVersionSnapshot(spec) {
+        return decodePreviousVersionSnapshot(await this.#call('previousVersionSnapshot', [spec]));
+    }
+    async previousVersionAudit() {
+        return decodePreviousVersionAuditResult(await this.#call('previousVersionAudit', []));
+    }
+    async previousVersionDiscard() {
+        return decodePreviousVersionDiscardResult(await this.#call('previousVersionDiscard', []));
+    }
     sync() {
         return this.#call('sync', []);
     }
@@ -490,6 +500,9 @@ function buildInitConfig(config) {
             : {}),
         ...(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/dist/worker-protocol.d.ts

@@ -19,7 +19,7 @@ import type { SyncProgress } from './progress.js';
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import type { ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
@@ -27,6 +27,7 @@ import type { ClientChangeBatch, LocalRevision } from './invalidation.js';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
 import type { LocalDataRebootstrapInput, LocalDataRebootstrapResult } from './local-rebootstrap.js';
 import type { OutboxCommit } from './outbox.js';
+import type { PreviousVersionAudit, PreviousVersionReadSpec, PreviousVersionSnapshot } from './previous-version.js';
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
@@ -73,6 +74,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
@@ -107,6 +113,15 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
     purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult;
     /** Application-authorized, outbox-preserving projection recovery. */
     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[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.22.0"
+    "@syncular/core": "0.23.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.22.0",
+    "@syncular/server": "0.23.0",
     "playwright": "1.63.0"
   }
 }

package/src/bun-database.ts

@@ -4,13 +4,14 @@
  * browser entry never touches `bun:sqlite`.
  */
 import { Database } from 'bun:sqlite';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
   assertImageAlias,
   type ClientDatabase,
   runTransaction,
+  type SiblingDatabase,
   type SqlRow,
   type SqlValue,
 } from './database';
@@ -32,9 +33,11 @@ function coerceParams(params: readonly SqlValue[]): BunParam[] {
 
 export class BunClientDatabase implements ClientDatabase {
   readonly db: Database;
+  readonly #path: string;
   #tx = { depth: 0 };
 
   constructor(path = ':memory:') {
+    this.#path = path;
     this.db = new Database(path);
     // Match native Rust persistence: append durable commits to the WAL
     // instead of creating and syncing a rollback journal per transaction.
@@ -61,6 +64,28 @@ export class BunClientDatabase implements ClientDatabase {
     return this.db.query(sql).all(...coerceParams(params)) as SqlRow[];
   }
 
+  /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
+  openSibling(name: string): SiblingDatabase {
+    const siblingPath =
+      this.#path === ':memory:' ? ':memory:' : `${this.#path}.${name}`;
+    const database = new BunClientDatabase(siblingPath);
+    return {
+      database,
+      close: () => database.close(),
+      removeFile: () => {
+        if (siblingPath === ':memory:') return;
+        rmSync(siblingPath, { force: true });
+        rmSync(`${siblingPath}-wal`, { force: true });
+        rmSync(`${siblingPath}-shm`, { force: true });
+      },
+    };
+  }
+
+  siblingExists(name: string): boolean {
+    if (this.#path === ':memory:') return false;
+    return existsSync(`${this.#path}.${name}`);
+  }
+
   transaction<T>(fn: () => T): T {
     return runTransaction(this.#tx, (sql) => this.db.run(sql), fn);
   }