@syncular/client 0.4.0 → 0.5.0

package/dist/worker-entry.js

@@ -9,7 +9,7 @@
  * same bootstrap, the same RPC, a different SQLite.
  *
  * The §8.4 host loop lives HERE: wake-ups (hello/`sync` events, delta
- * drops) coalesce into one jittered `syncUntilIdle` round in the worker;
+ * drops) coalesce into one intent-driven `syncUntilIdle` round in the worker;
  * RPC-driven and auto-driven sync rounds serialize on one queue because
  * the core owns exactly one loop.
  */
@@ -80,34 +80,66 @@ export function startSyncWorker(overrides = {}) {
         syncChain = next.then(() => undefined, () => undefined);
         return next;
     }
-    // -- §8.4 host loop: coalesced, jittered, inside the worker --------------
+    // -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
     let autoSync = true;
-    let wakeJitterMs = 200;
     let autoSyncScheduled = false;
-    function scheduleAutoSync() {
-        if (!autoSync || autoSyncScheduled || closed || client === undefined) {
+    let backgroundTimer;
+    let backgroundDue = Number.POSITIVE_INFINITY;
+    function runAutoSync() {
+        autoSyncScheduled = false;
+        if (closed || client === undefined)
+            return;
+        const running = client;
+        void serializedSync(() => running.syncUntilIdle())
+            .then((summary) => {
+            if (!closed)
+                post({ t: 'event', event: { kind: 'synced', summary } });
+        })
+            .catch((error) => {
+            if (!closed) {
+                post({
+                    t: 'event',
+                    event: { kind: 'synced', error: toErrorShape(error) },
+                });
+            }
+        });
+    }
+    function consumeSyncIntent(intent) {
+        if (!autoSync || closed || client === undefined || intent.kind === 'none') {
             return;
         }
-        autoSyncScheduled = true;
-        setTimeout(() => {
-            autoSyncScheduled = false;
-            if (closed || client === undefined)
+        if (intent.kind === 'background') {
+            if (autoSyncScheduled)
+                return;
+            const due = Date.now() + Math.max(0, intent.delayMs);
+            if (backgroundTimer !== undefined && due >= backgroundDue)
                 return;
-            const running = client;
-            void serializedSync(() => running.syncUntilIdle())
-                .then((summary) => {
-                if (!closed)
-                    post({ t: 'event', event: { kind: 'synced', summary } });
-            })
-                .catch((error) => {
-                if (!closed) {
-                    post({
-                        t: 'event',
-                        event: { kind: 'synced', error: toErrorShape(error) },
-                    });
+            if (backgroundTimer !== undefined)
+                clearTimeout(backgroundTimer);
+            backgroundDue = due;
+            backgroundTimer = setTimeout(() => {
+                backgroundTimer = undefined;
+                backgroundDue = Number.POSITIVE_INFINITY;
+                if (!autoSyncScheduled) {
+                    autoSyncScheduled = true;
+                    runAutoSync();
                 }
-            });
-        }, Math.floor(Math.random() * wakeJitterMs));
+            }, Math.max(0, due - Date.now()));
+            return;
+        }
+        if (backgroundTimer !== undefined) {
+            clearTimeout(backgroundTimer);
+            backgroundTimer = undefined;
+            backgroundDue = Number.POSITIVE_INFINITY;
+        }
+        if (!autoSync || autoSyncScheduled || closed || client === undefined) {
+            return;
+        }
+        autoSyncScheduled = true;
+        queueMicrotask(runAutoSync);
+    }
+    function consumeEffects(effects) {
+        consumeSyncIntent(effects.sync);
     }
     function requireClient() {
         if (client === undefined) {
@@ -145,7 +177,6 @@ export function startSyncWorker(overrides = {}) {
             throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker is already initialized');
         }
         autoSync = config.autoSync ?? true;
-        wakeJitterMs = config.wakeJitterMs ?? 200;
         database =
             overrides.openDatabase !== undefined
                 ? await overrides.openDatabase(config)
@@ -187,8 +218,9 @@ export function startSyncWorker(overrides = {}) {
             ...(config.limits !== undefined ? { limits: config.limits } : {}),
             onSyncNeeded: (reason) => {
                 post({ t: 'event', event: { kind: 'sync-needed', reason } });
-                scheduleAutoSync();
+                consumeSyncIntent({ kind: 'interactive' });
             },
+            onSyncIntent: consumeSyncIntent,
             onConflict: (conflict) => {
                 post({ t: 'event', event: { kind: 'conflict', conflict } });
             },
@@ -201,11 +233,9 @@ export function startSyncWorker(overrides = {}) {
                 post({ t: 'event', event: { kind: 'presence', scopeKey } });
             },
         });
-        // TODO 3.1 / I1: forward every coalesced apply-batch invalidation to the
-        // UI thread so `SyncClientHandle.onInvalidate` fires with worker parity.
-        started.onInvalidate((event) => {
+        started.onChange((batch) => {
             if (!closed)
-                post({ t: 'event', event: { kind: 'invalidate', event } });
+                post({ t: 'event', event: { kind: 'change', batch } });
         });
         await started.start();
         realtimeConnector =
@@ -215,41 +245,32 @@ export function startSyncWorker(overrides = {}) {
                     ? webSocketRealtimeConnector(config.endpoints.realtimeUrl.replace('{clientId}', encodeURIComponent(started.clientId)))
                     : undefined;
         client = started;
+        // `start()` may discover persisted subscriptions/outbox work. Its callback
+        // fires before this worker publishes the initialized client, so consume
+        // the durable state once here as well; coalescing makes this a single task.
+        if (started.syncNeeded)
+            consumeSyncIntent({ kind: 'interactive' });
         return { clientId: started.clientId };
     }
     const api = {
         subscribe: (input) => requireClient().subscribe(input),
         unsubscribe: (id) => requireClient().unsubscribe(id),
         setWindow: async (base, units) => {
-            await requireClient().setWindow(base, units);
-            // A window change adds/removes value-sharded subscriptions; a widened
-            // unit needs a bootstrap pull to become visible. In autoSync mode the
-            // host loop owns rounds, so schedule one now — otherwise the new unit
-            // waits for an unrelated server wake-up (§8.4). A no-op change still
-            // schedules a harmless idempotent round.
-            scheduleAutoSync();
+            const result = await requireClient().setWindowCommand(base, units);
+            consumeEffects(result.effects);
         },
         windowState: (base) => requireClient().windowState(base),
         mutate: (mutations) => {
-            const id = requireClient().mutate(mutations);
-            // In autoSync mode the host loop owns rounds (§8.4): a local write must
-            // push without the app orchestrating sync, so schedule a jittered round
-            // to drain the outbox promptly. `mutate` is synchronous — its outbox
-            // write has committed before this line — and the round itself serializes
-            // on SyncClient's operation chain, so no ordering hack is needed here;
-            // the §8.4 jitter in `scheduleAutoSync` is the only deferral, and it
-            // coalesces bursts. (Historically this used setTimeout to dodge a
-            // nested-transaction flake; that race is fixed at the source now — the
-            // real cause was cross-operation interleaving, serialized in the core.)
-            scheduleAutoSync();
-            return id;
+            const result = requireClient().mutateCommand(mutations);
+            consumeEffects(result.effects);
+            return result.value;
         },
         patch: (table, rowId, partial, options) => {
             // Same §8.4 rule as `mutate`: a local write must push without the app
-            // orchestrating sync, so schedule a jittered round to drain the outbox.
-            const id = requireClient().patch(table, rowId, partial, options);
-            scheduleAutoSync();
-            return id;
+            // orchestrating sync, so consume the core's immediate intent.
+            const result = requireClient().patchCommand(table, rowId, partial, options);
+            consumeEffects(result.effects);
+            return result.value;
         },
         sync: () => {
             const running = requireClient();
@@ -260,6 +281,9 @@ export function startSyncWorker(overrides = {}) {
             return serializedSync(() => running.syncUntilIdle(maxRounds));
         },
         query: (sql, params) => requireClient().query(sql, params),
+        querySnapshot: (spec) => requireClient().querySnapshot(spec),
+        localRevision: () => requireClient().localRevision,
+        statusSnapshot: () => requireClient().statusSnapshot(),
         conflicts: () => requireClient().conflicts,
         rejections: () => requireClient().rejections,
         schemaFloor: () => requireClient().schemaFloor,
@@ -282,6 +306,8 @@ export function startSyncWorker(overrides = {}) {
         },
         close: async () => {
             closed = true;
+            if (backgroundTimer !== undefined)
+                clearTimeout(backgroundTimer);
             await client?.close();
             database?.close();
             client = undefined;

package/dist/worker-host.d.ts

@@ -23,9 +23,9 @@
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
-import { InvalidationEmitter, type InvalidationListener } from './invalidation.js';
+import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLease, type LeaderLock } from './leader-lock.js';
 import { type CrossTabChannel, FollowerLink, LeaderBridge } from './multi-tab.js';
 import type { OutboxCommit } from './outbox.js';
@@ -49,7 +49,6 @@ export interface SyncClientHandleConfig {
     readonly limits?: SyncClientLimits;
     /** Worker-side host loop (§8.4); default true. */
     readonly autoSync?: boolean;
-    readonly wakeJitterMs?: number;
     /** Default: Web Locks when available, else single-owner. */
     readonly leaderLock?: LeaderLock;
     readonly lockName?: string;
@@ -67,7 +66,7 @@ export interface SyncClientHandleConfig {
     readonly followerCallTimeoutMs?: number;
     /** Fires when this handle's role changes (follower → leader on promotion). */
     readonly onRoleChange?: (role: HandleRole) => void;
-    readonly onSyncNeeded?: (reason: 'hello' | WakeReason) => void;
+    readonly onSyncNeeded?: (reason: 'startup' | 'hello' | WakeReason) => void;
     readonly onConflict?: (conflict: ConflictRecord) => void;
     /** A worker-side autoSync round finished (or failed). */
     readonly onSynced?: (result: {
@@ -110,6 +109,7 @@ export declare class SyncClientHandle {
         core?: LeaderCore;
         follower?: FollowerLink;
         invalidation: InvalidationEmitter;
+        changes: ChangeEmitter;
         presence: Set<(scopeKey: string) => void>;
         roleListeners?: Set<(role: HandleRole) => void>;
     });
@@ -124,6 +124,7 @@ export declare class SyncClientHandle {
      * unsubscribe function.
      */
     onInvalidate(listener: InvalidationListener): () => void;
+    onChange(listener: ClientChangeListener): () => void;
     /**
      * §8.6: subscribe to presence changes — the identical surface as
      * `SyncClient.onPresence`. Returns an unsubscribe function.
@@ -143,6 +144,9 @@ export declare class SyncClientHandle {
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
+    querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
+    localRevision(): Promise<LocalRevision>;
+    statusSnapshot(): Promise<SyncStatusSnapshot>;
     conflicts(): Promise<readonly ConflictRecord[]>;
     rejections(): Promise<readonly RejectionRecord[]>;
     schemaFloor(): Promise<SchemaFloor | undefined>;

package/dist/worker-host.js

@@ -1,6 +1,6 @@
 import { registerDevtools } from './devtools.js';
 import { ClientSyncError } from './errors.js';
-import { InvalidationEmitter } from './invalidation.js';
+import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
 import { broadcastChannelFactory, FollowerLink, LeaderBridge, multiTabChannelName, newTabId, } from './multi-tab.js';
 import { NOT_LEADER_CODE, WORKER_FAILED_CODE, } from './worker-protocol.js';
@@ -32,6 +32,7 @@ export class SyncClientHandle {
     #core;
     #follower;
     #invalidation;
+    #changes;
     #presence;
     #roleListeners;
     #devtoolsUnregister;
@@ -43,6 +44,7 @@ export class SyncClientHandle {
         this.#core = internals.core;
         this.#follower = internals.follower;
         this.#invalidation = internals.invalidation;
+        this.#changes = internals.changes;
         this.#presence = internals.presence;
         this.#roleListeners = internals.roleListeners ?? new Set();
         // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
@@ -88,8 +90,11 @@ export class SyncClientHandle {
                 }
             }
         }
-        else if (event.kind === 'invalidate') {
-            this.#invalidation.emit(event.event);
+        else if (event.kind === 'change') {
+            this.#changes.emit(event.batch);
+            const legacy = invalidationFromChange(event.batch);
+            if (legacy !== undefined)
+                this.#invalidation.emit(legacy);
         }
     }
     /**
@@ -101,6 +106,9 @@ export class SyncClientHandle {
     onInvalidate(listener) {
         return this.#invalidation.on(listener);
     }
+    onChange(listener) {
+        return this.#changes.on(listener);
+    }
     /**
      * §8.6: subscribe to presence changes — the identical surface as
      * `SyncClient.onPresence`. Returns an unsubscribe function.
@@ -163,6 +171,15 @@ export class SyncClientHandle {
     query(sql, params) {
         return this.#call('query', [sql, params]);
     }
+    querySnapshot(spec) {
+        return this.#call('querySnapshot', [spec]);
+    }
+    localRevision() {
+        return this.#call('localRevision', []);
+    }
+    statusSnapshot() {
+        return this.#call('statusSnapshot', []);
+    }
     conflicts() {
         return this.#call('conflicts', []);
     }
@@ -344,9 +361,6 @@ function buildInitConfig(config) {
         ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
         ...(config.limits !== undefined ? { limits: config.limits } : {}),
         ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
-        ...(config.wakeJitterMs !== undefined
-            ? { wakeJitterMs: config.wakeJitterMs }
-            : {}),
     };
 }
 /** Route a worker event to the config-level callbacks (leader visibility). */
@@ -381,6 +395,7 @@ export async function createSyncClientHandle(config) {
     const lock = config.leaderLock ?? defaultLeaderLock();
     const lockName = config.lockName ?? 'syncular-leader';
     const invalidation = new InvalidationEmitter();
+    const changes = new ChangeEmitter();
     const presence = new Set();
     const roleListeners = new Set();
     if (config.onRoleChange !== undefined)
@@ -398,6 +413,7 @@ export async function createSyncClientHandle(config) {
         return await bootLeader(config, lockName, lease, {
             epoch: 0,
             invalidation,
+            changes,
             presence,
             roleListeners,
         });
@@ -409,6 +425,7 @@ export async function createSyncClientHandle(config) {
             role: 'follower',
             clientId: '',
             invalidation,
+            changes,
             presence,
             roleListeners,
         });
@@ -416,6 +433,7 @@ export async function createSyncClientHandle(config) {
     // ---- Follower: proxy to the leader; contest + promote on its close. ----
     return await bootFollower(config, lockName, lock, {
         invalidation,
+        changes,
         presence,
         roleListeners,
     });
@@ -453,6 +471,7 @@ async function bootLeader(config, lockName, lease, parts) {
         clientId: core.clientId,
         core,
         invalidation: parts.invalidation,
+        changes: parts.changes,
         presence: parts.presence,
         roleListeners: parts.roleListeners,
     });
@@ -536,6 +555,7 @@ async function bootFollower(config, lockName, lock, parts) {
         clientId: '',
         follower,
         invalidation: parts.invalidation,
+        changes: parts.changes,
         presence: parts.presence,
         roleListeners: parts.roleListeners,
     });

package/dist/worker-protocol.d.ts

@@ -12,15 +12,15 @@
  *
  * Scheduling note (SPEC §8.4): the sync-needed signal is host-driven,
  * and in worker mode the HOST LOOP LIVES IN THE WORKER — wake-ups
- * coalesce into jittered `syncUntilIdle` rounds there (`autoSync`),
+ * coalesce into intent-driven `syncUntilIdle` rounds there (`autoSync`),
  * so the UI thread never has to react to keep data flowing. Events are
  * still forwarded to the handle for visibility.
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
-import type { InvalidationEvent } from './invalidation.js';
+import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
 import type { OutboxCommit } from './outbox.js';
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
@@ -63,12 +63,11 @@ export interface WorkerInitConfig {
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
     /**
-     * Worker-side host loop (§8.4): coalesce wake-ups into jittered
+     * Worker-side host loop (§8.4): coalesce interactive work immediately and
+     * honor explicit background retry deadlines
      * `syncUntilIdle` rounds inside the worker. Default true.
      */
     readonly autoSync?: boolean;
-    /** Max jitter before a coalesced auto-sync round (default 200 ms). */
-    readonly wakeJitterMs?: number;
 }
 /** Successful init reply. */
 export interface WorkerInitResult {
@@ -89,6 +88,9 @@ export interface WorkerApi {
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    querySnapshot(spec: QueryReadSpec): QuerySnapshot;
+    localRevision(): LocalRevision;
+    statusSnapshot(): SyncStatusSnapshot;
     conflicts(): readonly ConflictRecord[];
     rejections(): readonly RejectionRecord[];
     schemaFloor(): SchemaFloor | undefined;
@@ -138,7 +140,7 @@ export interface WorkerErrorShape {
 }
 export type SyncWorkerEvent = {
     readonly kind: 'sync-needed';
-    readonly reason: 'hello' | WakeReason;
+    readonly reason: 'startup' | 'hello' | WakeReason;
 } | {
     readonly kind: 'conflict';
     readonly conflict: ConflictRecord;
@@ -156,13 +158,9 @@ export type SyncWorkerEvent = {
     readonly kind: 'presence';
     readonly scopeKey: string;
 } | {
-    /**
-     * TODO 3.1 / I1: one coalesced apply-batch invalidation. `Set`s
-     * structured-clone across the worker boundary, so the event crosses
-     * verbatim — the handle re-emits it to `onInvalidate` listeners.
-     */
-    readonly kind: 'invalidate';
-    readonly event: InvalidationEvent;
+    /** Exact revisioned core transaction; Sets and bigint clone directly. */
+    readonly kind: 'change';
+    readonly batch: ClientChangeBatch;
 };
 export type WorkerToMainMessage = {
     readonly t: 'ready';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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.3.1"
+    "@syncular/core": "0.5.0"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.3.1",
+    "@syncular/server": "0.5.0",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/apply.ts

@@ -22,6 +22,9 @@ import {
   toSqlValue,
 } from './schema';
 
+/** Lets the client wrap the physical write in its revision transaction. */
+export type ApplyTransaction = <T>(fn: () => T) => T;
+
 function upsertSql(table: CompiledClientTable): string {
   const names = [
     ...table.columns.map((column) => quoteIdent(column.name)),
@@ -68,6 +71,7 @@ export async function applyCommitFrame(
   schema: CompiledClientSchema,
   frame: CommitFrame,
   encryption?: EncryptionConfig,
+  transaction: ApplyTransaction = (fn) => db.transaction(fn),
 ): Promise<void> {
   type Resolved =
     | { op: 'delete'; table: CompiledClientTable; rowId: string }
@@ -115,7 +119,7 @@ export async function applyCommitFrame(
       rowVersion: change.rowVersion,
     });
   }
-  db.transaction(() => {
+  transaction(() => {
     for (const change of resolved) {
       if (change.op === 'delete') {
         deleteLocalRow(db, change.table, change.rowId);
@@ -290,7 +294,11 @@ export function applySqliteSegment(
   table: CompiledClientTable,
   bytes: Uint8Array,
   descriptor: SqliteSegmentDescriptor,
-  options: { readonly clearFirst: boolean; readonly effective: ScopeMap },
+  options: {
+    readonly clearFirst: boolean;
+    readonly effective: ScopeMap;
+    readonly transaction?: ApplyTransaction;
+  },
 ): number {
   const withImage = db.withSqliteImage?.bind(db);
   if (withImage === undefined) {
@@ -359,7 +367,7 @@ export function applySqliteSegment(
 
     // 3. One transaction: fresh-bootstrap clear, then replace-or-upsert.
     const names = table.columns.map((column) => quoteIdent(column.name));
-    return db.transaction(() => {
+    return (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
       if (options.clearFirst) {
         deleteScopedRows(db, table, options.effective);
       }
@@ -396,7 +404,11 @@ export async function applyRowsSegment(
   schema: CompiledClientSchema,
   table: CompiledClientTable,
   segment: RowsSegment,
-  options: { readonly clearFirst: boolean; readonly effective: ScopeMap },
+  options: {
+    readonly clearFirst: boolean;
+    readonly effective: ScopeMap;
+    readonly transaction?: ApplyTransaction;
+  },
   encryption?: EncryptionConfig,
 ): Promise<number> {
   validateSegmentColumns(schema, table, segment);
@@ -421,7 +433,8 @@ export async function applyRowsSegment(
     }
     const clearThisBlock = first && options.clearFirst;
     first = false;
-    db.transaction(() => {
+    if (!clearThisBlock && rows.length === 0) continue;
+    (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
       if (clearThisBlock) {
         deleteScopedRows(db, table, options.effective);
       }