@syncular/client 0.15.47 → 0.16.1

package/README.md

@@ -14,6 +14,9 @@ server-authoritative commands, and live query watches through the remote
 operation transport. See [remote server operations](https://syncular.dev/guide-remote-operations/).
 Its schema and sync transport are optional for query-only or command-only
 processes.
+Ordinary commits use wire version 1 until the caller supplies an acquired
+partition `logEpoch`. Set `logEpoch` after a restore rotation requires epoch
+validation.
 
 ## Client-local FTS5 projections
 
@@ -69,6 +72,20 @@ SPEC §8.4); the supported page-level realtime supervisor owns reconnect and
 resume policy. The main thread gets `onSyncNeeded` / `onConflict` / `onSynced`
 events for rendering.
 
+A direct `SyncClient` used by a long-running service exposes
+`onSyncNeeded()` and `onSyncIntent()`. Install the shared single-flight loop
+instead of maintaining host timers:
+
+```ts
+const scheduler = installSyncScheduler(client, { onError: reportSyncError });
+// During shutdown:
+scheduler.stop();
+```
+
+Creation-time window helpers produce immutable UTC month scope values.
+`creationTimeBucket(createdAtMs, 'month')` returns `YYYY-MM`, and
+`last(3, 'month')` returns the current and preceding two buckets oldest first.
+
 OPFS is best effort until the browser grants origin persistence. The page owns
 that decision because `StorageManager.persist()` is a Window API and should be
 requested from a user action:
@@ -563,3 +580,45 @@ Tests drive the real worker entry in a bun `Worker` with bun:sqlite
 injected through the bootstrap's database-factory override
 (`test/worker-rpc.test.ts`); the OPFS path itself is browser-only and is
 exercised by `apps/demo`.
+
+## Snapshot API migration
+
+This source-breaking revision uses methods for application reads across the
+direct client, worker leaders and followers, Tauri, and React Native. Replace
+`client.conflicts`, `client.rejections`, and `client.securityLifecycle` on the
+direct client with method calls. Replace `schemaFloor`, `leaseState`,
+`upgrading`, and `syncNeeded` getters or bridge methods with fields from one
+`statusSnapshot()` call:
+
+```ts
+const status = await client.statusSnapshot();
+if (status.schemaFloor) showUpgradeRequired(status.schemaFloor);
+const conflicts = await client.conflicts();
+const outcome = await client.commitOutcome(commitId);
+```
+
+The direct client returns snapshots synchronously. Worker and native bridges
+return promises; `await` works with both. `querySnapshot` returns rows, coverage,
+and revision from one read. `diagnosticsSnapshot`, `commitOutcome`,
+`commitOutcomes`, and `resolveCommitOutcome` retain their existing arguments.
+The shared `ClientSnapshotMethods` and `PromiseMethods` types describe these
+contracts. Key-bearing security activation stays on each concrete host type.
+
+React uses the supplied client directly; `useSyncClient()` preserves its
+identity. Remove imports of `normalizeClient` and the
+`@syncular/client/realtime-supervisor-observation` forwarding utility. Pass the
+client to `SyncProvider` and use `realtimeSupervisorSnapshot(client)` to inspect
+an attached supervisor. Custom React clients must implement the snapshot
+methods and method-form collection reads. See the [React migration](https://syncular.dev/platform-react/)
+for the `onEnqueued` callback rename.
+
+## Outbox read costs
+
+Request encoding pins the pending count and highest local sequence before its
+first asynchronous step. It reads keyset pages of 32 raw records, decodes only
+the consumed prefix, and stops at the first whole commit that exceeds the
+remaining operation budget. Mutations appended during encoding enter the next
+request. Status and diagnostics use `COUNT(*)` without parsing pending bodies.
+Optimistic replay still reads the remaining outbox after each response. The
+100/1,000/10,000-commit workload and measured limits are recorded in
+[the reliability RFC](../../docs/RFC-RELIABILITY-DX.md#9-implementation-evidence-2026-09-05).

package/dist/bun-database.d.ts

@@ -5,6 +5,11 @@
  */
 import { Database } from 'bun:sqlite';
 import { type ClientDatabase, type SqlRow, type SqlValue } from './database.js';
+declare module 'bun:sqlite' {
+    interface Database {
+        clearQueryCache(): void;
+    }
+}
 export declare class BunClientDatabase implements ClientDatabase {
     #private;
     readonly db: Database;

package/dist/bun-database.js

@@ -23,6 +23,11 @@ export class BunClientDatabase {
     }
     exec(sql, params = []) {
         this.db.query(sql).run(...coerceParams(params));
+        // `Database.query()` caches prepared statements. Clear that cache after
+        // schema DDL so a reset does not reprepare every later row upsert.
+        if (/^\s*(?:CREATE|DROP|ALTER)\b/i.test(sql)) {
+            this.db.clearQueryCache();
+        }
     }
     query(sql, params = []) {
         return this.db.query(sql).all(...coerceParams(params));

package/dist/client.d.ts

@@ -231,6 +231,16 @@ export interface QuerySnapshot<Row = SqlRow> {
  * complete once its bootstrap round finishes — emptiness ≠ pendency.
  */
 export declare function windowComplete(state: WindowState, unit: string): boolean;
+/** Canonical client reads, shared by synchronous cores and promise hosts. */
+export type ClientSnapshotMethods = Pick<SyncClient, 'querySnapshot' | 'statusSnapshot' | 'diagnosticsSnapshot' | 'conflicts' | 'rejections' | 'commitOutcome' | 'commitOutcomes' | 'resolveCommitOutcome'>;
+/** Project a method contract across an asynchronous host boundary. */
+export type PromiseMethods<Methods> = {
+    [Key in keyof Methods]: Methods[Key] extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<Awaited<Result>> : never;
+};
+/** A reader can execute locally or cross a worker/native boundary. */
+export type ClientSnapshotReader = {
+    [Key in keyof ClientSnapshotMethods]: (...args: Parameters<ClientSnapshotMethods[Key]>) => ReturnType<ClientSnapshotMethods[Key]> | Promise<ReturnType<ClientSnapshotMethods[Key]>>;
+};
 export declare class SyncClient {
     #private;
     constructor(config: SyncClientConfig);
@@ -238,7 +248,7 @@ export declare class SyncClient {
     start(): Promise<void>;
     close(): Promise<void>;
     /** Current fail-closed local-replica security state. */
-    get securityLifecycle(): SecurityLifecycle;
+    securityLifecycle(): SecurityLifecycle;
     /**
      * Block new protected operations immediately, then wait for every already
      * serialized database/network operation to settle before releasing key
@@ -285,6 +295,10 @@ export declare class SyncClient {
     onInvalidate(listener: InvalidationListener): () => void;
     /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
     onChange(listener: ClientChangeListener): () => void;
+    /** Subscribe to host wake signals raised by startup and realtime. */
+    onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
+    /** Subscribe to exact core-owned scheduling instructions. */
+    onSyncIntent(listener: (intent: SyncIntent) => void): () => void;
     /** Subscribe to complete, privacy-safe diagnostic snapshots. */
     onDiagnostics(listener: ClientDiagnosticsListener): () => void;
     /**
@@ -316,8 +330,8 @@ export declare class SyncClient {
     fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
     /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
     flushBlobUploads(): Promise<void>;
-    get conflicts(): readonly ConflictRecord[];
-    get rejections(): readonly RejectionRecord[];
+    conflicts(): readonly ConflictRecord[];
+    rejections(): readonly RejectionRecord[];
     /** One durable final outcome by the originating client commit id. */
     commitOutcome(clientCommitId: string): CommitOutcome | undefined;
     /** Newest-first durable outcome journal. */
@@ -329,28 +343,11 @@ export declare class SyncClient {
      * dismissed. The transition is one-way and survives restart.
      */
     resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;
-    /** Non-undefined once the server declared a schema floor (§1.6). */
-    get schemaFloor(): SchemaFloor | undefined;
-    /**
-     * §7.4.5: true while a schema-bump reset + first re-bootstrap is in
-     * flight — the app's "upgrading…" cue. Clears when the first post-reset
-     * bootstrap round reaches idle (every subscription past its fresh
-     * bootstrap).
-     */
-    get upgrading(): boolean;
-    /**
-     * §7.3.5: the current auth-lease state (opaque). Undefined until a
-     * `LEASE` frame arrives. `errorCode` is set when a round was rejected
-     * with a request-level lease code — syncing on the lease has stopped.
-     */
-    get leaseState(): LeaseState | undefined;
     /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
      * `undefined` if no lease is held. Negative once expired. */
     leaseRemainingMs(now?: number): number | undefined;
     /** True when syncing is stopped pending a client upgrade. */
     get stopped(): boolean;
-    /** §8: a hello/wake-up asked for a pull that has not run yet. */
-    get syncNeeded(): boolean;
     /**
      * §8.6 presence on a scope key: the current peers present there (a map
      * of `actorId clientId` → peer). Empty for a key with no present peers.

package/dist/client.js

@@ -18,7 +18,7 @@ import { singleOwnerLock, } from './leader-lock.js';
 import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
 import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
 import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
-import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
+import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
 import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
@@ -71,6 +71,7 @@ function emptySummary(pushed) {
         failed: [],
     };
 }
+const LOG_EPOCH_META_KEY = 'logEpoch';
 function isFinalPushResult(frame) {
     return (frame.status !== 'rejected' ||
         !frame.results.some((result) => result.status === 'error' &&
@@ -131,6 +132,8 @@ export class SyncClient {
     #invalidation = new InvalidationEmitter();
     /** §8.6: subscribable presence-change listeners (twin of onPresence). */
     #presenceListeners = new Set();
+    #syncNeededListeners = new Set();
+    #syncIntentListeners = new Set();
     #diagnostics = new ClientDiagnosticsEmitter();
     #diagnosticsDeferralDepth = 0;
     #diagnosticsPending = false;
@@ -229,12 +232,12 @@ export class SyncClient {
         // this as an exact core-owned intent so hosts never need a startup poll or
         // an application-issued sync() call.
         const startupWork = this.#schemaFloor === undefined &&
-            (listOutbox(this.#db).length > 0 ||
+            (countOutbox(this.#db) > 0 ||
                 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({
@@ -244,10 +247,10 @@ export class SyncClient {
             role: () => 'direct',
             outbox: async () => this.pendingCommits().length,
             subscriptions: async () => this.subscriptions(),
-            conflicts: async () => this.conflicts.length,
-            rejections: async () => this.rejections.length,
-            syncNeeded: async () => this.syncNeeded,
-            upgrading: async () => this.upgrading,
+            conflicts: async () => this.conflicts().length,
+            rejections: async () => this.rejections().length,
+            syncNeeded: async () => this.statusSnapshot().syncNeeded,
+            upgrading: async () => this.statusSnapshot().upgrading,
             onInvalidate: (listener) => this.onInvalidate(listener),
         });
         this.#emitDiagnostics();
@@ -298,6 +301,29 @@ export class SyncClient {
         this.#setSchemaFloor(undefined);
         this.#replayOutbox();
     }
+    /** §2.1 reset after the server reports a different log continuity. */
+    #runLogEpochReset(logEpoch) {
+        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) {
         if (this.#upgrading === upgrading)
             return;
@@ -325,6 +351,7 @@ export class SyncClient {
         });
     }
     async close() {
+        this.#emitSyncIntent({ kind: 'none' });
         this.#devtoolsUnregister?.();
         this.#devtoolsUnregister = undefined;
         this.disconnectRealtime();
@@ -332,9 +359,43 @@ export class SyncClient {
         await this.#lease?.release();
         this.#lease = undefined;
         this.#started = false;
+        this.#syncNeededListeners.clear();
+        this.#syncIntentListeners.clear();
+    }
+    #emitSyncNeeded(reason) {
+        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) {
+        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. */
-    get securityLifecycle() {
+    securityLifecycle() {
         return this.#securityLifecycle;
     }
     /**
@@ -378,12 +439,12 @@ export class SyncClient {
         this.#encryption = options.encryption;
         this.#securityLifecycle = 'active';
         const startupWork = this.#schemaFloor === undefined &&
-            (listOutbox(this.#db).length > 0 ||
+            (countOutbox(this.#db) > 0 ||
                 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();
     }
@@ -479,6 +540,20 @@ export class SyncClient {
     onChange(listener) {
         return this.#changes.on(listener);
     }
+    /** Subscribe to host wake signals raised by startup and realtime. */
+    onSyncNeeded(listener) {
+        this.#syncNeededListeners.add(listener);
+        return () => {
+            this.#syncNeededListeners.delete(listener);
+        };
+    }
+    /** Subscribe to exact core-owned scheduling instructions. */
+    onSyncIntent(listener) {
+        this.#syncIntentListeners.add(listener);
+        return () => {
+            this.#syncIntentListeners.delete(listener);
+        };
+    }
     /** Subscribe to complete, privacy-safe diagnostic snapshots. */
     onDiagnostics(listener) {
         return this.#diagnostics.on(listener);
@@ -591,7 +666,7 @@ export class SyncClient {
             replica: {
                 localRevision: getLocalRevision(this.#db).toString(),
                 syncNeeded: this.#needsPull,
-                pendingOutbox: listOutbox(this.#db).length,
+                pendingOutbox: countOutbox(this.#db),
             },
             lease: leaseState,
             subscriptions: allSubscriptions.slice(0, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS),
@@ -682,7 +757,7 @@ export class SyncClient {
     #statusSnapshot(outboxCount) {
         return {
             currentSchemaVersion: this.#config.schema.version,
-            outbox: outboxCount ?? listOutbox(this.#db).length,
+            outbox: outboxCount ?? countOutbox(this.#db),
             upgrading: this.#upgrading,
             leaseState: this.#leaseState,
             schemaFloor: this.#schemaFloor,
@@ -919,11 +994,11 @@ export class SyncClient {
         }
         await transport.upload(blobId, bytes, mediaType);
     }
-    get conflicts() {
+    conflicts() {
         this.#requireActive();
         return this.#conflicts;
     }
-    get rejections() {
+    rejections() {
         this.#requireActive();
         return this.#rejections;
     }
@@ -987,27 +1062,6 @@ export class SyncClient {
             return resolved;
         });
     }
-    /** Non-undefined once the server declared a schema floor (§1.6). */
-    get schemaFloor() {
-        return this.#schemaFloor;
-    }
-    /**
-     * §7.4.5: true while a schema-bump reset + first re-bootstrap is in
-     * flight — the app's "upgrading…" cue. Clears when the first post-reset
-     * bootstrap round reaches idle (every subscription past its fresh
-     * bootstrap).
-     */
-    get upgrading() {
-        return this.#upgrading;
-    }
-    /**
-     * §7.3.5: the current auth-lease state (opaque). Undefined until a
-     * `LEASE` frame arrives. `errorCode` is set when a round was rejected
-     * with a request-level lease code — syncing on the lease has stopped.
-     */
-    get leaseState() {
-        return this.#leaseState;
-    }
     /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
      * `undefined` if no lease is held. Negative once expired. */
     leaseRemainingMs(now = this.#now()) {
@@ -1018,10 +1072,6 @@ export class SyncClient {
     get stopped() {
         return this.#schemaFloor !== undefined;
     }
-    /** §8: a hello/wake-up asked for a pull that has not run yet. */
-    get syncNeeded() {
-        return this.#needsPull;
-    }
     /**
      * §8.6 presence on a scope key: the current peers present there (a map
      * of `actorId clientId` → peer). Empty for a key with no present peers.
@@ -1119,11 +1169,17 @@ export class SyncClient {
             cursor: -1,
             status: 'active',
         });
+        this.#setSyncNeeded(true);
+        this.#emitSyncIntent({ kind: 'interactive' });
         this.#emitDiagnostics();
     }
     unsubscribe(id) {
         this.#requireActive();
+        if (getSubscription(this.#db, id) === undefined)
+            return;
         deleteSubscription(this.#db, id);
+        this.#setSyncNeeded(true);
+        this.#emitSyncIntent({ kind: 'interactive' });
         this.#emitDiagnostics();
     }
     // -- windowed subscriptions (§4.8) ------------------------------------------
@@ -1179,7 +1235,9 @@ export class SyncClient {
                             status: 'active',
                         });
                     });
+                    this.#needsPull = true;
                     batch.window(baseKey, base.table, unit);
+                    batch.status();
                 });
                 changed = true;
                 widened = true;
@@ -1195,6 +1253,9 @@ export class SyncClient {
         const effects = {
             sync: changed || widened ? { kind: 'interactive' } : { kind: 'none' },
         };
+        if (effects.sync.kind === 'interactive') {
+            this.#emitSyncIntent(effects.sync);
+        }
         return { value: undefined, effects };
     }
     /**
@@ -1254,6 +1315,8 @@ export class SyncClient {
             });
             batch.scopeMap(table, effective);
             batch.window(baseKey, table.name, unit);
+            this.#needsPull = true;
+            batch.status();
         });
     }
     /**
@@ -1349,7 +1412,9 @@ export class SyncClient {
                 this.#applyOperationsLocally(operations, batch);
                 batch.status();
             });
+            this.#needsPull = true;
         });
+        this.#emitSyncIntent({ kind: 'interactive' });
         return clientCommitId;
     }
     /** Host-facing mutation result with explicit network work intent (§7.5). */
@@ -1577,8 +1642,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,
@@ -1641,21 +1706,27 @@ export class SyncClient {
      * the encoded push frames index-aligned with the surviving `outbox`.
      */
     async #encodeOutboxForPush() {
-        const pending = listOutbox(this.#db);
+        // Pin before the first encryption await: mutations can append while a
+        // round is encoding, and belong to the next request.
+        const bounds = this.#db.query('SELECT COUNT(*) AS count, MAX(seq) AS last_seq FROM _syncular_outbox')[0];
+        const pendingCount = bounds.count;
+        const throughSeq = bounds.last_seq ?? 0;
         const pushFrames = [];
         const outbox = [];
         let deferred = 0;
         let ops = 0;
-        for (const commit of pending) {
+        let processed = 0;
+        for (const commit of iterateOutbox(this.#db, throughSeq)) {
             // §6.1 splitBatch: whole commits in commit order, stopping before the
             // per-request operation cap. A first commit that alone exceeds the cap
             // is sent alone — the server rejects it loudly rather than the queue
             // wedging silently. Deferred commits stay queued for the next round.
             if (outbox.length > 0 &&
                 ops + commit.operations.length > MAX_OPS_PER_REQUEST) {
-                deferred += 1;
-                continue;
+                deferred = pendingCount - processed;
+                break;
             }
+            processed += 1;
             try {
                 pushFrames.push(
                 // §5.11: encrypted columns are encrypted at this encode-at-send
@@ -1798,9 +1869,12 @@ 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
@@ -1808,7 +1882,9 @@ export class SyncClient {
             // is removed from the push and surfaced as a rejection, never wedging
             // the queue. `pushFrames` and `outbox` stay index-aligned for result
             // mapping.
-            const { pushFrames, outbox, deferred } = await this.#encodeOutboxForPush();
+            const { pushFrames, outbox, deferred } = 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;
@@ -1819,6 +1895,7 @@ export class SyncClient {
                     type: 'REQ_HEADER',
                     clientId: this.#clientId,
                     schemaVersion: this.#schema.version,
+                    ...(logEpoch !== undefined ? { logEpoch } : {}),
                 },
                 ...pushFrames,
                 {
@@ -1885,12 +1962,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;
         }
@@ -1912,7 +1984,8 @@ export class SyncClient {
                 last.segmentRowsApplied === 0 &&
                 last.bootstrapping.length === 0 &&
                 last.resets.length === 0 &&
-                (last.deferredCommits ?? 0) === 0) {
+                (last.deferredCommits ?? 0) === 0 &&
+                !this.#needsPull) {
                 return last;
             }
         }
@@ -2078,14 +2151,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') {
@@ -2155,7 +2228,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');
             }
         });
     }
@@ -2195,6 +2268,11 @@ 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:
@@ -2216,6 +2294,20 @@ 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;
         let errorFrame;
         let deltaCursor = -1;
@@ -2237,7 +2329,7 @@ export class SyncClient {
                         });
                         break;
                     case 'PUSH_RESULT': {
-                        let outboxCount = responseOutboxCount ?? listOutbox(this.#db).length;
+                        let outboxCount = responseOutboxCount ?? countOutbox(this.#db);
                         this.#applyBatch((batch) => {
                             const drained = this.#handlePushResult(frame, commitsById, summary, batch, rejectionDetailsByCommit.get(frame.clientCommitId), frame === lastFinalPushResult);
                             if (drained)

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';
 export * from './state.js';
+export * from './sync-scheduler.js';
 export * from './transport.js';
 export * from './window.js';
 export * from './worker-host.js';

package/dist/index.js

@@ -35,6 +35,7 @@ export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';
 export * from './state.js';
+export * from './sync-scheduler.js';
 export * from './transport.js';
 export * from './window.js';
 export * from './worker-host.js';

package/dist/outbox.d.ts

@@ -38,8 +38,12 @@ export interface OutboxBeforeImage {
     readonly values?: Readonly<Record<string, JsonRowValue>>;
 }
 export declare function appendOutboxCommit(db: ClientDatabase, clientCommitId: string, operations: readonly OutboxOperation[], nowMs: number, beforeImages?: readonly OutboxBeforeImage[]): void;
-/** Pending commits in FIFO creation order (§7.1). */
+/** Pending commits in FIFO creation order (§7.1). Full reads serve replay and the public listing. */
 export declare function listOutbox(db: ClientDatabase): OutboxCommit[];
+/** Keyset pages bound staging; laziness decodes only commits consumed by the encoder. */
+export declare function iterateOutbox(db: ClientDatabase, throughSeq: number): Generator<OutboxCommit>;
+/** Routine status reads never load operation bodies. */
+export declare function countOutbox(db: ClientDatabase): number;
 export declare function deleteOutboxCommit(db: ClientDatabase, clientCommitId: string): void;
 export declare function listOutboxBeforeImages(db: ClientDatabase, clientCommitId: string): OutboxBeforeImage[];
 export declare function replaceOutboxBeforeImages(db: ClientDatabase, clientCommitId: string, replacements: readonly OutboxBeforeImage[]): void;