@syncular/client 0.4.0 → 0.5.0

package/src/state.ts

@@ -6,6 +6,10 @@
  */
 import type { ScopeMap } from '@syncular/core';
 import type { ClientDatabase } from './database';
+import type { LocalRevision } from './invalidation';
+
+export const LOCAL_REVISION_KEY = 'localRevision';
+const MAX_U64 = 18_446_744_073_709_551_615n;
 
 export type SubscriptionStatus = 'active' | 'revoked' | 'failed';
 
@@ -124,3 +128,31 @@ export function setMeta(db: ClientDatabase, key: string, value: string): void {
     value,
   ]);
 }
+
+/** Read the durable client-local observer revision (SPEC §7.5). */
+export function getLocalRevision(db: ClientDatabase): LocalRevision {
+  const raw = getMeta(db, LOCAL_REVISION_KEY);
+  if (raw === undefined) return 0n;
+  if (!/^(0|[1-9][0-9]*)$/.test(raw)) {
+    throw new Error(`invalid persisted local revision ${JSON.stringify(raw)}`);
+  }
+  const revision = BigInt(raw);
+  if (revision > MAX_U64) {
+    throw new Error(`persisted local revision exceeds u64: ${raw}`);
+  }
+  return revision;
+}
+
+/**
+ * Increment the durable revision. The caller MUST own the same transaction as
+ * the observer-visible writes represented by the corresponding change batch.
+ */
+export function bumpLocalRevision(db: ClientDatabase): LocalRevision {
+  const current = getLocalRevision(db);
+  if (current === MAX_U64) {
+    throw new Error('local revision exhausted u64');
+  }
+  const next = current + 1n;
+  setMeta(db, LOCAL_REVISION_KEY, next.toString());
+  return next;
+}

package/src/worker-entry.ts

@@ -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.
  */
@@ -22,6 +22,7 @@ import {
   httpSyncTransport,
   webSocketRealtimeConnector,
 } from './http';
+import type { CommandEffects, SyncIntent } from './invalidation';
 import type {
   RealtimeConnector,
   SegmentDownloader,
@@ -133,36 +134,67 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     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(): void {
+  let backgroundTimer: ReturnType<typeof setTimeout> | undefined;
+  let backgroundDue = Number.POSITIVE_INFINITY;
+
+  function runAutoSync(): void {
+    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: unknown) => {
+        if (!closed) {
+          post({
+            t: 'event',
+            event: { kind: 'synced', error: toErrorShape(error) },
+          });
+        }
+      });
+  }
+
+  function consumeSyncIntent(intent: SyncIntent): void {
+    if (!autoSync || closed || client === undefined || intent.kind === 'none') {
+      return;
+    }
+    if (intent.kind === 'background') {
+      if (autoSyncScheduled) return;
+      const due = Date.now() + Math.max(0, intent.delayMs);
+      if (backgroundTimer !== undefined && due >= backgroundDue) return;
+      if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
+      backgroundDue = due;
+      backgroundTimer = setTimeout(
+        () => {
+          backgroundTimer = undefined;
+          backgroundDue = Number.POSITIVE_INFINITY;
+          if (!autoSyncScheduled) {
+            autoSyncScheduled = true;
+            runAutoSync();
+          }
+        },
+        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;
-    setTimeout(
-      () => {
-        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: unknown) => {
-            if (!closed) {
-              post({
-                t: 'event',
-                event: { kind: 'synced', error: toErrorShape(error) },
-              });
-            }
-          });
-      },
-      Math.floor(Math.random() * wakeJitterMs),
-    );
+    queueMicrotask(runAutoSync);
+  }
+
+  function consumeEffects(effects: CommandEffects): void {
+    consumeSyncIntent(effects.sync);
   }
 
   function requireClient(): SyncClient {
@@ -215,7 +247,6 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       );
     }
     autoSync = config.autoSync ?? true;
-    wakeJitterMs = config.wakeJitterMs ?? 200;
 
     database =
       overrides.openDatabase !== undefined
@@ -270,8 +301,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       ...(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 } });
       },
@@ -284,10 +316,8 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
         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) => {
-      if (!closed) post({ t: 'event', event: { kind: 'invalidate', event } });
+    started.onChange((batch) => {
+      if (!closed) post({ t: 'event', event: { kind: 'change', batch } });
     });
     await started.start();
     realtimeConnector =
@@ -302,6 +332,10 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
             )
           : 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 };
   }
 
@@ -309,35 +343,26 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     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();
@@ -348,6 +373,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       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,
@@ -369,6 +397,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     },
     close: async () => {
       closed = true;
+      if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
       await client?.close();
       database?.close();
       client = undefined;

package/src/worker-host.ts

@@ -28,6 +28,8 @@ import type {
   LeaseState,
   MutationInput,
   PresencePeer,
+  QueryReadSpec,
+  QuerySnapshot,
   RejectionRecord,
   SchemaFloor,
   SubscribeInput,
@@ -38,7 +40,15 @@ import type {
 import type { SqlRow, SqlValue } from './database';
 import { registerDevtools } from './devtools';
 import { ClientSyncError } from './errors';
-import { InvalidationEmitter, type InvalidationListener } from './invalidation';
+import {
+  ChangeEmitter,
+  type ClientChangeListener,
+  InvalidationEmitter,
+  type InvalidationListener,
+  invalidationFromChange,
+  type LocalRevision,
+  type SyncStatusSnapshot,
+} from './invalidation';
 import {
   type LeaderLease,
   type LeaderLock,
@@ -89,7 +99,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;
@@ -107,7 +116,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: {
@@ -171,6 +180,7 @@ export class SyncClientHandle {
   #core: LeaderCore | undefined;
   #follower: FollowerLink | undefined;
   readonly #invalidation: InvalidationEmitter;
+  readonly #changes: ChangeEmitter;
   readonly #presence: Set<(scopeKey: string) => void>;
   readonly #roleListeners: Set<(role: HandleRole) => void>;
   readonly #devtoolsUnregister: () => void;
@@ -183,6 +193,7 @@ export class SyncClientHandle {
     core?: LeaderCore;
     follower?: FollowerLink;
     invalidation: InvalidationEmitter;
+    changes: ChangeEmitter;
     presence: Set<(scopeKey: string) => void>;
     roleListeners?: Set<(role: HandleRole) => void>;
   }) {
@@ -191,6 +202,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.
@@ -235,8 +247,10 @@ export class SyncClientHandle {
           /* a UI listener must never break event dispatch */
         }
       }
-    } 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);
     }
   }
 
@@ -250,6 +264,10 @@ export class SyncClientHandle {
     return this.#invalidation.on(listener);
   }
 
+  onChange(listener: ClientChangeListener): () => void {
+    return this.#changes.on(listener);
+  }
+
   /**
    * §8.6: subscribe to presence changes — the identical surface as
    * `SyncClient.onPresence`. Returns an unsubscribe function.
@@ -345,6 +363,20 @@ export class SyncClientHandle {
     return this.#call('query', [sql, params]);
   }
 
+  querySnapshot<Row = SqlRow>(
+    spec: QueryReadSpec,
+  ): Promise<QuerySnapshot<Row>> {
+    return this.#call('querySnapshot', [spec]) as Promise<QuerySnapshot<Row>>;
+  }
+
+  localRevision(): Promise<LocalRevision> {
+    return this.#call('localRevision', []);
+  }
+
+  statusSnapshot(): Promise<SyncStatusSnapshot> {
+    return this.#call('statusSnapshot', []);
+  }
+
   conflicts(): Promise<readonly ConflictRecord[]> {
     return this.#call('conflicts', []);
   }
@@ -574,9 +606,6 @@ function buildInitConfig(config: SyncClientHandleConfig): WorkerInitConfig {
     ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
     ...(config.limits !== undefined ? { limits: config.limits } : {}),
     ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
-    ...(config.wakeJitterMs !== undefined
-      ? { wakeJitterMs: config.wakeJitterMs }
-      : {}),
   };
 }
 
@@ -614,6 +643,7 @@ export async function createSyncClientHandle(
   const lock = config.leaderLock ?? defaultLeaderLock();
   const lockName = config.lockName ?? 'syncular-leader';
   const invalidation = new InvalidationEmitter();
+  const changes = new ChangeEmitter();
   const presence = new Set<(scopeKey: string) => void>();
   const roleListeners = new Set<(role: HandleRole) => void>();
   if (config.onRoleChange !== undefined) roleListeners.add(config.onRoleChange);
@@ -633,6 +663,7 @@ export async function createSyncClientHandle(
     return await bootLeader(config, lockName, lease, {
       epoch: 0,
       invalidation,
+      changes,
       presence,
       roleListeners,
     });
@@ -645,6 +676,7 @@ export async function createSyncClientHandle(
       role: 'follower',
       clientId: '',
       invalidation,
+      changes,
       presence,
       roleListeners,
     });
@@ -653,6 +685,7 @@ export async function createSyncClientHandle(
   // ---- Follower: proxy to the leader; contest + promote on its close. ----
   return await bootFollower(config, lockName, lock, {
     invalidation,
+    changes,
     presence,
     roleListeners,
   });
@@ -661,6 +694,7 @@ export async function createSyncClientHandle(
 interface HandleParts {
   epoch?: number;
   invalidation: InvalidationEmitter;
+  changes: ChangeEmitter;
   presence: Set<(scopeKey: string) => void>;
   roleListeners: Set<(role: HandleRole) => void>;
 }
@@ -712,6 +746,7 @@ async function bootLeader(
     clientId: core.clientId,
     core,
     invalidation: parts.invalidation,
+    changes: parts.changes,
     presence: parts.presence,
     roleListeners: parts.roleListeners,
   });
@@ -809,6 +844,7 @@ async function bootFollower(
     clientId: '',
     follower,
     invalidation: parts.invalidation,
+    changes: parts.changes,
     presence: parts.presence,
     roleListeners: parts.roleListeners,
   });

package/src/worker-protocol.ts

@@ -12,7 +12,7 @@
  *
  * 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.
  */
@@ -23,6 +23,8 @@ import type {
   LeaseState,
   MutationInput,
   PresencePeer,
+  QueryReadSpec,
+  QuerySnapshot,
   RejectionRecord,
   SchemaFloor,
   SubscribeInput,
@@ -31,7 +33,11 @@ import type {
   WindowState,
 } from './client';
 import type { SqlRow, SqlValue } from './database';
-import type { InvalidationEvent } from './invalidation';
+import type {
+  ClientChangeBatch,
+  LocalRevision,
+  SyncStatusSnapshot,
+} from './invalidation';
 import type { OutboxCommit } from './outbox';
 import type { ClientSchema } from './schema';
 import type { SubscriptionRecord } from './state';
@@ -88,12 +94,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. */
@@ -123,6 +128,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;
@@ -182,7 +190,10 @@ export interface WorkerErrorShape {
 }
 
 export type SyncWorkerEvent =
-  | { readonly kind: 'sync-needed'; readonly reason: 'hello' | WakeReason }
+  | {
+      readonly kind: 'sync-needed';
+      readonly reason: 'startup' | 'hello' | WakeReason;
+    }
   | { readonly kind: 'conflict'; readonly conflict: ConflictRecord }
   | {
       /** An autoSync round finished (or failed) inside the worker. */
@@ -201,13 +212,9 @@ export type SyncWorkerEvent =
       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 =