@syncular/client 0.15.46 → 0.15.48

package/src/client.ts

@@ -513,6 +513,8 @@ function emptySummary(pushed: number): MutableSummary {
   };
 }
 
+const LOG_EPOCH_META_KEY = 'logEpoch';
+
 function isFinalPushResult(frame: PushResultFrame): boolean {
   return (
     frame.status !== 'rejected' ||
@@ -579,6 +581,10 @@ export class SyncClient {
   readonly #invalidation = new InvalidationEmitter();
   /** §8.6: subscribable presence-change listeners (twin of onPresence). */
   readonly #presenceListeners = new Set<(scopeKey: string) => void>();
+  readonly #syncNeededListeners = new Set<
+    (reason: 'startup' | 'hello' | WakeReason) => void
+  >();
+  readonly #syncIntentListeners = new Set<(intent: SyncIntent) => void>();
   readonly #diagnostics = new ClientDiagnosticsEmitter();
   #diagnosticsDeferralDepth = 0;
   #diagnosticsPending = false;
@@ -705,8 +711,8 @@ export class SyncClient {
         subscriptions.some((sub) => sub.status === 'active'));
     if (startupWork && this.#securityLifecycle === 'active') {
       this.#needsPull = true;
-      this.#config.onSyncNeeded?.('startup');
-      this.#config.onSyncIntent?.({ kind: 'interactive' });
+      this.#emitSyncNeeded('startup');
+      this.#emitSyncIntent({ kind: 'interactive' });
     }
     // Console introspection is a no-op outside a dev page.
     this.#devtoolsUnregister = registerDevtools({
@@ -776,6 +782,29 @@ export class SyncClient {
     this.#replayOutbox();
   }
 
+  /** §2.1 reset after the server reports a different log continuity. */
+  #runLogEpochReset(logEpoch: string): string[] {
+    const subscriptions = loadSubscriptions(this.#db);
+    const pending = listOutbox(this.#db);
+    this.#setUpgrading(true);
+    this.#applyBatch((batch) => {
+      this.#db.transaction(() => {
+        dropAndRecreateSyncedTables(this.#db, this.#schema);
+        resetSubscriptionsForBump(this.#db);
+        setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
+        for (const commit of pending) {
+          this.#applyOperationsLocally(commit.operations, batch);
+        }
+      });
+      for (const table of this.#schema.tables.values()) batch.table(table.name);
+    });
+    this.#localResetEpoch += 1;
+    this.#setSyncNeeded(true);
+    this.#emitSyncNeeded('startup');
+    this.#emitSyncIntent({ kind: 'interactive' });
+    return subscriptions.map((subscription) => subscription.id);
+  }
+
   #setUpgrading(upgrading: boolean): void {
     if (this.#upgrading === upgrading) return;
     this.#applyBatch((batch) => {
@@ -803,6 +832,7 @@ export class SyncClient {
   }
 
   async close(): Promise<void> {
+    this.#emitSyncIntent({ kind: 'none' });
     this.#devtoolsUnregister?.();
     this.#devtoolsUnregister = undefined;
     this.disconnectRealtime();
@@ -810,6 +840,38 @@ export class SyncClient {
     await this.#lease?.release();
     this.#lease = undefined;
     this.#started = false;
+    this.#syncNeededListeners.clear();
+    this.#syncIntentListeners.clear();
+  }
+
+  #emitSyncNeeded(reason: 'startup' | 'hello' | WakeReason): void {
+    try {
+      this.#config.onSyncNeeded?.(reason);
+    } catch {
+      // An observer cannot alter sync correctness.
+    }
+    for (const listener of this.#syncNeededListeners) {
+      try {
+        listener(reason);
+      } catch {
+        // An observer cannot alter sync correctness.
+      }
+    }
+  }
+
+  #emitSyncIntent(intent: SyncIntent): void {
+    try {
+      this.#config.onSyncIntent?.(intent);
+    } catch {
+      // An observer cannot alter sync correctness.
+    }
+    for (const listener of this.#syncIntentListeners) {
+      try {
+        listener(intent);
+      } catch {
+        // An observer cannot alter sync correctness.
+      }
+    }
   }
 
   /** Current fail-closed local-replica security state. */
@@ -869,8 +931,8 @@ export class SyncClient {
         loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
     if (startupWork) {
       this.#setSyncNeeded(true);
-      this.#config.onSyncNeeded?.('startup');
-      this.#config.onSyncIntent?.({ kind: 'interactive' });
+      this.#emitSyncNeeded('startup');
+      this.#emitSyncIntent({ kind: 'interactive' });
     }
     this.#emitDiagnostics();
   }
@@ -982,6 +1044,24 @@ export class SyncClient {
     return this.#changes.on(listener);
   }
 
+  /** Subscribe to host wake signals raised by startup and realtime. */
+  onSyncNeeded(
+    listener: (reason: 'startup' | 'hello' | WakeReason) => void,
+  ): () => void {
+    this.#syncNeededListeners.add(listener);
+    return () => {
+      this.#syncNeededListeners.delete(listener);
+    };
+  }
+
+  /** Subscribe to exact core-owned scheduling instructions. */
+  onSyncIntent(listener: (intent: SyncIntent) => void): () => void {
+    this.#syncIntentListeners.add(listener);
+    return () => {
+      this.#syncIntentListeners.delete(listener);
+    };
+  }
+
   /** Subscribe to complete, privacy-safe diagnostic snapshots. */
   onDiagnostics(listener: ClientDiagnosticsListener): () => void {
     return this.#diagnostics.on(listener);
@@ -1781,12 +1861,17 @@ export class SyncClient {
       cursor: -1,
       status: 'active',
     });
+    this.#setSyncNeeded(true);
+    this.#emitSyncIntent({ kind: 'interactive' });
     this.#emitDiagnostics();
   }
 
   unsubscribe(id: string): void {
     this.#requireActive();
+    if (getSubscription(this.#db, id) === undefined) return;
     deleteSubscription(this.#db, id);
+    this.#setSyncNeeded(true);
+    this.#emitSyncIntent({ kind: 'interactive' });
     this.#emitDiagnostics();
   }
 
@@ -1851,7 +1936,9 @@ export class SyncClient {
               status: 'active',
             });
           });
+          this.#needsPull = true;
           batch.window(baseKey, base.table, unit);
+          batch.status();
         });
         changed = true;
         widened = true;
@@ -1867,6 +1954,9 @@ export class SyncClient {
     const effects: CommandEffects = {
       sync: changed || widened ? { kind: 'interactive' } : { kind: 'none' },
     };
+    if (effects.sync.kind === 'interactive') {
+      this.#emitSyncIntent(effects.sync);
+    }
     return { value: undefined, effects };
   }
 
@@ -1934,6 +2024,8 @@ export class SyncClient {
       });
       batch.scopeMap(table, effective);
       batch.window(baseKey, table.name, unit);
+      this.#needsPull = true;
+      batch.status();
     });
   }
 
@@ -2043,7 +2135,9 @@ export class SyncClient {
         this.#applyOperationsLocally(operations, batch);
         batch.status();
       });
+      this.#needsPull = true;
     });
+    this.#emitSyncIntent({ kind: 'interactive' });
     return clientCommitId;
   }
 
@@ -2320,8 +2414,8 @@ export class SyncClient {
     this.#localResetEpoch += 1;
 
     if (!priorUpgrading) this.#config.onUpgrading?.(true);
-    this.#config.onSyncNeeded?.('startup');
-    this.#config.onSyncIntent?.({ kind: 'interactive' });
+    this.#emitSyncNeeded('startup');
+    this.#emitSyncIntent({ kind: 'interactive' });
     return {
       alreadyApplied: false,
       retainedCommits: pending.length,
@@ -2585,9 +2679,14 @@ export class SyncClient {
     // survive it — the reference server keeps no replay buffer (§8.2).
     this.#setSyncNeeded(false);
     try {
+      const logEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
       // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
       // them, so the server-side existence check (§6.6) passes.
-      if (this.#hasBlobs && this.#config.blobs !== undefined) {
+      if (
+        logEpoch !== undefined &&
+        this.#hasBlobs &&
+        this.#config.blobs !== undefined
+      ) {
         await this.flushBlobUploads();
       }
       // §7.4.4: encode the outbox with the CURRENT codec; a commit that
@@ -2596,7 +2695,9 @@ export class SyncClient {
       // the queue. `pushFrames` and `outbox` stay index-aligned for result
       // mapping.
       const { pushFrames, outbox, deferred } =
-        await this.#encodeOutboxForPush();
+        logEpoch === undefined
+          ? { pushFrames: [], outbox: [], deferred: 0 }
+          : await this.#encodeOutboxForPush();
       // Captured together with the subscription state below: the response
       // apply persists SUB_END cursors only while this epoch is current.
       const resetEpoch = this.#localResetEpoch;
@@ -2609,6 +2710,7 @@ export class SyncClient {
           type: 'REQ_HEADER',
           clientId: this.#clientId,
           schemaVersion: this.#schema.version,
+          ...(logEpoch !== undefined ? { logEpoch } : {}),
         },
         ...pushFrames,
         {
@@ -2686,11 +2788,7 @@ export class SyncClient {
           delayMs: this.#retryDelayMs,
         };
         this.#retryDelayMs = Math.min(this.#retryDelayMs * 2, 30_000);
-        try {
-          this.#config.onSyncIntent?.(intent);
-        } catch {
-          // An observer cannot alter sync correctness.
-        }
+        this.#emitSyncIntent(intent);
       }
       throw error;
     } finally {
@@ -2916,14 +3014,14 @@ export class SyncClient {
     if (event.event === 'hello') {
       if (event.data.requiresSync) {
         this.#setSyncNeeded(true);
-        this.#config.onSyncNeeded?.('hello');
+        this.#emitSyncNeeded('hello');
       }
       return;
     }
     if (event.event === 'sync') {
       // §8.3: any wake-up means "run a pull soon", never data.
       this.#setSyncNeeded(true);
-      this.#config.onSyncNeeded?.(event.data.reason);
+      this.#emitSyncNeeded(event.data.reason);
       return;
     }
     if (event.event === 'presence') {
@@ -2995,7 +3093,7 @@ export class SyncClient {
       } catch {
         // A delta that cannot be applied is recovered by a pull (§8.3).
         this.#setSyncNeeded(true);
-        this.#config.onSyncNeeded?.('catchup-required');
+        this.#emitSyncNeeded('catchup-required');
       }
     });
   }
@@ -3057,6 +3155,16 @@ export class SyncClient {
     if (header?.type !== 'RESP_HEADER') {
       throw new ClientSyncError('sync.invalid_request', 'missing RESP_HEADER');
     }
+    if (
+      message.wireVersion < 2 ||
+      header.logEpoch === undefined ||
+      header.resetRequired === undefined
+    ) {
+      throw new ClientSyncError(
+        'client.invalid_host_response',
+        'the server response does not carry wire version 2 log-epoch state',
+      );
+    }
     if (header.requiredSchemaVersion !== undefined) {
       // §1.6 schema floor: nothing else was processed — stop syncing and
       // surface the upgrade requirement. A live-round floor always stops:
@@ -3078,6 +3186,26 @@ export class SyncClient {
         schemaFloor,
       };
     }
+    const currentLogEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
+    if (header.resetRequired) {
+      if (mode !== 'pull' || message.frames.length !== 1) {
+        throw new ClientSyncError(
+          'client.invalid_host_response',
+          'a log-epoch reset response must contain only RESP_HEADER',
+        );
+      }
+      return {
+        ...summary,
+        resets: this.#runLogEpochReset(header.logEpoch),
+        bootstrapping: [],
+      };
+    }
+    if (currentLogEpoch === undefined || currentLogEpoch !== header.logEpoch) {
+      throw new ClientSyncError(
+        'client.invalid_host_response',
+        'the server changed logEpoch without requiring a reset',
+      );
+    }
 
     let section: OpenSection | undefined;
     let errorFrame: ClientSyncError | undefined;

package/src/index.ts

@@ -3,7 +3,7 @@
  * SPEC.md is normative.
  *
  * Browser-safe root: database backends live behind subpath exports
- * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
+ * (`./sqlite` for Node or Bun, `./wasm` for sqlite-wasm + OPFS); the
  * worker-side bootstrap lives behind `./worker`. The main-thread handle
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
@@ -35,6 +35,7 @@ export * from './realtime-supervisor';
 export * from './schema';
 export * from './sql-tag';
 export * from './state';
+export * from './sync-scheduler';
 export * from './transport';
 export * from './window';
 export * from './worker-host';

package/src/node-database.ts

@@ -1,23 +1,9 @@
 /**
- * `ClientDatabase` on better-sqlite3 — the Electron-main / plain-Node
- * backend. Semantics mirror `./bun-database`
- * exactly (synchronous exec/query/transaction with the shared savepoint
- * helper, and the same §5.3 sqlite-image ATTACH path), so the core behaves
- * identically whether it runs on bun:sqlite (tests), sqlite-wasm (browser)
- * or better-sqlite3 (Node/Electron-main).
- *
- * better-sqlite3 is an OPTIONAL peer dependency, not a hard one: the package
- * installs cleanly without it and this module errors helpfully only when a
- * host actually calls `openNodeDatabase()` without having installed the peer.
- * Not exported from the package root, so browser/bun entries never resolve
- * the native module. Subpath export: `@syncular/client/node`.
- *
- * bun CANNOT dlopen better-sqlite3 (ERR_DLOPEN_FAILED, oven-sh/bun#4290), so
- * this adapter is verified under real Node — see the README "Electron-main /
- * plain-Node" section for the one-command recipe and `test/node-database`.
+ * `ClientDatabase` on Node's built-in `node:sqlite`. Semantics mirror the Bun
+ * adapter: synchronous queries, nested transactions, and SQLite image attach.
  */
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -28,54 +14,19 @@ import {
   type SqlValue,
 } from './database';
 
-/**
- * Structural view of the tiny better-sqlite3 surface this binding uses. We
- * type it locally (rather than importing `better-sqlite3`'s types) so the
- * package typechecks without the optional peer installed.
- */
-interface BetterSqliteStatement {
-  run(...params: NodeParam[]): unknown;
-  all(...params: NodeParam[]): unknown[];
-}
-interface BetterSqliteDatabase {
-  readonly inTransaction: boolean;
-  prepare(sql: string): BetterSqliteStatement;
-  exec(sql: string): unknown;
-  close(): void;
-}
-type BetterSqliteConstructor = new (
-  path: string,
-  options?: { readonly?: boolean; fileMustExist?: boolean },
-) => BetterSqliteDatabase;
-
-/**
- * better-sqlite3 accepts string / number / bigint / null / Buffer|Uint8Array
- * bind values, but NOT booleans (it throws "TypeError: can only bind …"). We
- * coerce booleans to 0/1 exactly like the bun adapter so callers see one
- * uniform bind contract across every backend.
- */
-type NodeParam = string | number | bigint | Uint8Array | null;
-
-function coerceParams(params: readonly SqlValue[]): NodeParam[] {
-  return params.map((value): NodeParam => {
+function coerceParams(params: readonly SqlValue[]): SQLInputValue[] {
+  return params.map((value): SQLInputValue => {
     if (typeof value === 'boolean') return value ? 1 : 0;
     return value;
   });
 }
 
-/**
- * better-sqlite3 returns BLOB columns as Node `Buffer`s. A Buffer IS a
- * Uint8Array subclass, but it can be a view onto a shared pool buffer, so we
- * normalize to a standalone Uint8Array — matching what bun:sqlite hands back
- * and keeping the buffer-ownership assumptions elsewhere (worker transfer,
- * structured clone) honest.
- */
 function normalizeRow(row: Record<string, unknown>): SqlRow {
   const out: SqlRow = {};
   for (const key in row) {
     const value = row[key];
-    if (Buffer.isBuffer(value)) {
-      out[key] = new Uint8Array(value); // copies out of the pool
+    if (value instanceof Uint8Array) {
+      out[key] = new Uint8Array(value);
     } else {
       out[key] = value as SqlValue;
     }
@@ -83,55 +34,12 @@ function normalizeRow(row: Record<string, unknown>): SqlRow {
   return out;
 }
 
-/**
- * Load the optional peer AND open the database in one guarded step, so BOTH
- * failure modes are turned into a clear, actionable error rather than a raw
- * one:
- *
- *  - `require('better-sqlite3')` throwing MODULE_NOT_FOUND — the peer is not
- *    installed (the common browser-only-host case), and
- *  - `new Database()` throwing ERR_DLOPEN_FAILED — the module resolves but the
- *    native addon cannot load, which is exactly what bun does for
- *    better-sqlite3 (oven-sh/bun#4290); the addon only dlopens at construction.
- */
-function openBetterSqlite(path: string): BetterSqliteDatabase {
-  const require = createRequire(import.meta.url);
-  try {
-    const mod = require('better-sqlite3') as
-      | BetterSqliteConstructor
-      | { default: BetterSqliteConstructor };
-    const Database =
-      (mod as { default?: BetterSqliteConstructor }).default ??
-      (mod as BetterSqliteConstructor);
-    return new Database(path);
-  } catch (error) {
-    const code = (error as { code?: string })?.code;
-    if (code === 'ERR_DLOPEN_FAILED') {
-      throw new Error(
-        "openNodeDatabase() requires the 'better-sqlite3' native module, but " +
-          'it failed to load. This most commonly means you are running under ' +
-          'bun, which cannot dlopen better-sqlite3 (oven-sh/bun#4290) — use ' +
-          "the bun:sqlite backend ('@syncular/client/bun') under bun, " +
-          "and reserve '@syncular/client/node' for Node/Electron-main. " +
-          `Underlying error: ${String(error)}`,
-      );
-    }
-    throw new Error(
-      'openNodeDatabase() requires the optional peer dependency ' +
-        "'better-sqlite3', which is not installed. Add it to your app " +
-        '(`npm install better-sqlite3` / `bun add better-sqlite3`) — it is ' +
-        'kept optional so @syncular/client installs without a native ' +
-        `build for browser-only hosts. Underlying error: ${String(error)}`,
-    );
-  }
-}
-
 export class NodeClientDatabase implements ClientDatabase {
-  readonly db: BetterSqliteDatabase;
+  readonly db: DatabaseSync;
   #tx = { depth: 0 };
 
   constructor(path = ':memory:') {
-    this.db = openBetterSqlite(path);
+    this.db = new DatabaseSync(path);
   }
 
   exec(sql: string, params: readonly SqlValue[] = []): void {
@@ -140,19 +48,14 @@ export class NodeClientDatabase implements ClientDatabase {
 
   query(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
     const rows = this.db.prepare(sql).all(...coerceParams(params));
-    return (rows as Record<string, unknown>[]).map(normalizeRow);
+    return rows.map(normalizeRow);
   }
 
   transaction<T>(fn: () => T): T {
     return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
   }
 
-  /**
-   * §5.3 image import: better-sqlite3 (like bun:sqlite) attaches files, not
-   * buffers, so the image lands in a private temp file for the duration of
-   * the ATTACH. Must be called outside any open transaction (SQLite cannot
-   * ATTACH inside one).
-   */
+  /** §5.3 image import through a private file attached for one callback. */
   withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T {
     assertImageAlias(alias);
     const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));

package/src/query-guard.ts

@@ -10,8 +10,8 @@
  *      bypasses the outbox (SPEC §7.1) and silently diverges from the
  *      server — writes MUST go through `client.mutate([...])`.
  *   2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
- *      multi-statement string (`SELECT 1; DROP TABLE t`), while bun:sqlite /
- *      better-sqlite3 prepare only the first. We unify on the strict
+ *      multi-statement string (`SELECT 1; DROP TABLE t`), while the native
+ *      SQLite adapters prepare only the first. We unify on the strict
  *      behaviour: exactly one statement per `query()`.
  *
  * The guard only fronts the PUBLIC `client.query()` — engine-internal reads

package/src/remote.ts

@@ -10,7 +10,6 @@ import {
   encodeRemoteOperationRequest,
   encodeRemoteOperationRealtimeMessage,
   encodeRow,
-  PROTOCOL_WIRE_VERSION,
   type PushOperation,
   type PushOperationResult,
   type PushResultDetailsFrame,
@@ -42,6 +41,8 @@ export interface SyncRemoteClientConfig {
   readonly operations?: RemoteOperationTransport;
   readonly operationRealtime?: RemoteOperationRealtimeConnector;
   readonly encryption?: EncryptionConfig;
+  /** Acquired partition log epoch for restore-safe ordinary commits (§2.1). */
+  readonly logEpoch?: string;
 }
 
 export interface RemoteCommitInput {
@@ -203,11 +204,15 @@ export class SyncRemoteClient {
     }
   >();
   readonly #encryption: EncryptionConfig | undefined;
+  readonly #logEpoch: string | undefined;
 
   constructor(config: SyncRemoteClientConfig) {
     if (config.clientId.length === 0) {
       throw invalid('SyncRemoteClient clientId must be non-empty');
     }
+    if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
+      throw invalid('SyncRemoteClient logEpoch must be non-empty');
+    }
     this.#schema =
       config.schema === undefined
         ? undefined
@@ -217,6 +222,7 @@ export class SyncRemoteClient {
     this.#operations = config.operations;
     this.#operationRealtime = config.operationRealtime;
     this.#encryption = config.encryption;
+    this.#logEpoch = config.logEpoch;
   }
 
   async prepareCommit(input: RemoteCommitInput): Promise<PreparedRemoteCommit> {
@@ -277,13 +283,16 @@ export class SyncRemoteClient {
     return {
       requestId: input.requestId,
       bytes: encodeMessage({
-        wireVersion: PROTOCOL_WIRE_VERSION,
+        wireVersion: this.#logEpoch === undefined ? 1 : 2,
         msgKind: 'request',
         frames: [
           {
             type: 'REQ_HEADER',
             clientId: this.#clientId,
             schemaVersion: schema.version,
+            ...(this.#logEpoch !== undefined
+              ? { logEpoch: this.#logEpoch }
+              : {}),
           },
           {
             type: 'PUSH_COMMIT',

package/src/sqlite-bun.ts

@@ -0,0 +1,6 @@
+import { openBunDatabase } from './bun-database';
+import type { ClientDatabase } from './database';
+
+export function openSqliteDatabase(path = ':memory:'): ClientDatabase {
+  return openBunDatabase(path);
+}

package/src/sqlite-node.ts

@@ -0,0 +1,6 @@
+import type { ClientDatabase } from './database';
+import { openNodeDatabase } from './node-database';
+
+export function openSqliteDatabase(path = ':memory:'): ClientDatabase {
+  return openNodeDatabase(path);
+}