@gonvex/client 0.1.19 → 0.1.20

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createQueryCacheStore, defaultQueryCacheReadTimeoutMs, } from "./query-cache.js";
-import { createSyncStore } from "./sync-store.js";
+import { createSyncStore, syncHashesDigest, syncRowsHashes, } from "./sync-store.js";
 import { GonvexErrorReporter } from "./error-reporter.js";
 export * from "./cache.js";
 export * from "./cache-coordinator.js";
@@ -39,6 +39,14 @@ export class GonvexClientError extends Error {
 export const DEFAULT_QUERY_TIMEOUT_MS = 20_000;
 export const DEFAULT_MUTATION_TIMEOUT_MS = 20_000;
 export const DEFAULT_ACTION_TIMEOUT_MS = 60_000;
+// Small collections can send their row hashes immediately and repair in one
+// round trip. Larger collections resume with one 64-byte digest and only send
+// the hash map when the server proves that something actually differs.
+const compactSyncIntegrityThreshold = 256;
+// Must match the runtime's per-frame sync.openMany admission limit. Keeping
+// this client-side prevents one oversized page from stranding every sync in a
+// batch behind a frame-level rejection.
+const maxSyncBatchOpens = 256;
 export class GonvexClient {
     url;
     socket;
@@ -49,7 +57,10 @@ export class GonvexClient {
     telemetryHandlers = new Set();
     pendingMessages = [];
     pendingSyncOpens = new Set();
+    pendingQuerySubscribes = new Set();
+    syncPersistence = new Map();
     syncOpenFlushTimer;
+    querySubscribeFlushTimer;
     serverCapabilities = {};
     auth = {};
     authInFlight = false;
@@ -59,9 +70,13 @@ export class GonvexClient {
     queryCacheWaitForScope;
     queryCacheReadTimeoutMs;
     querySubscriptionRetentionMs;
+    syncSubscriptionRetentionMs;
     syncStore;
     queryCacheDirective;
     queryCacheGeneration = 0;
+    // Sync collections live under a visibility-only scope that survives query
+    // cache rotations (deploys); their warm reads are guarded separately.
+    syncScopeGeneration = 0;
     queryCacheNegotiatedSocketGeneration;
     syncIdentityGeneration = 0;
     sessionScopeHandlers = new Set();
@@ -84,6 +99,7 @@ export class GonvexClient {
         this.queryCacheWaitForScope = options.queryCache !== undefined && options.queryCache !== false;
         this.queryCacheReadTimeoutMs = queryCacheReadTimeout(options.queryCache === false ? undefined : options.queryCache?.readTimeoutMs);
         this.querySubscriptionRetentionMs = normalizeQuerySubscriptionRetentionMs(options.querySubscriptionRetentionMs);
+        this.syncSubscriptionRetentionMs = normalizeQuerySubscriptionRetentionMs(options.syncSubscriptionRetentionMs);
         this.syncStore = createSyncStore(options.sync);
         this.timeouts = {
             queryTimeoutMs: options.timeouts?.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
@@ -110,6 +126,10 @@ export class GonvexClient {
             inflightOneShotQueries,
         };
     }
+    /** Metadata advertised by the runtime in its latest session.ready frame. */
+    serverInfo() {
+        return { ...this.serverCapabilities };
+    }
     subscribeToConnectionState(handler) {
         this.connectionStateHandlers.add(handler);
         return () => {
@@ -177,6 +197,7 @@ export class GonvexClient {
             if (this.socket !== socket || this.manuallyClosed)
                 return;
             this.isWebSocketConnected = false;
+            this.markSyncSubscriptionsOutOfDate();
             this.authInFlight = false;
             if (this.authWatchdogTimer) {
                 clearTimeout(this.authWatchdogTimer);
@@ -260,12 +281,19 @@ export class GonvexClient {
         this.rejectPendingCalls((call) => new GonvexClientError(`Gonvex client was closed while waiting for ${call.kind} ${call.path}`, { code: "closed", path: call.path, operation: call.kind }));
         for (const subscription of this.syncSubscriptions.values()) {
             this.clearSyncRetry(subscription);
+            if (subscription.unsubscribeTimer)
+                clearTimeout(subscription.unsubscribeTimer);
         }
         if (this.syncOpenFlushTimer) {
             clearTimeout(this.syncOpenFlushTimer);
             this.syncOpenFlushTimer = undefined;
         }
         this.pendingSyncOpens.clear();
+        if (this.querySubscribeFlushTimer) {
+            clearTimeout(this.querySubscribeFlushTimer);
+            this.querySubscribeFlushTimer = undefined;
+        }
+        this.pendingQuerySubscribes.clear();
         for (const subscription of this.querySubscriptions.values()) {
             if (subscription.cacheReadFallbackTimer)
                 clearTimeout(subscription.cacheReadFallbackTimer);
@@ -420,6 +448,13 @@ export class GonvexClient {
     }
     normalizeSubscriptionMessage(subscription, message) {
         if (message.type === "query.progress") {
+            if (subscription.lastMessage?.type !== "query.result") {
+                // A progress frame only confirms that an advertised cache revision is
+                // current. If the in-memory snapshot is gone, accepting it would leave
+                // listeners permanently without a value.
+                this.requestSubscriptionSnapshot(subscription);
+                return undefined;
+            }
             if (!this.acceptRevision(subscription, message.throughRevision))
                 return undefined;
             subscription.lastRevision = message.throughRevision;
@@ -526,6 +561,10 @@ export class GonvexClient {
         const key = querySubscriptionKey(ref, args);
         const existing = this.syncSubscriptions.get(key);
         if (existing) {
+            if (existing.unsubscribeTimer) {
+                clearTimeout(existing.unsubscribeTimer);
+                existing.unsubscribeTimer = undefined;
+            }
             existing.listeners.add(onMessage);
             if (existing.lastMessage) {
                 queueMicrotask(() => {
@@ -546,6 +585,10 @@ export class GonvexClient {
             opening: false,
             persistence: Promise.resolve(),
             retryAttempt: 0,
+            isUpToDate: false,
+            hashes: {},
+            forceFullIntegrity: false,
+            verificationGeneration: 0,
         };
         this.syncSubscriptions.set(key, subscription);
         this.handlers.set(subscription.id, (message) => this.handleSyncMessage(subscription, message));
@@ -555,7 +598,8 @@ export class GonvexClient {
     watchSync(ref, args = {}) {
         let latest;
         let latestError;
-        let isUpToDate = false;
+        const thisClient = this;
+        const key = querySubscriptionKey(ref, args);
         const updateHandlers = new Set();
         const notify = () => {
             for (const handler of updateHandlers)
@@ -568,7 +612,10 @@ export class GonvexClient {
                 notify();
             }
             else if (message.type === "sync.ready") {
-                isUpToDate = true;
+                latestError = undefined;
+                notify();
+            }
+            else if (message.type === "sync.syncing" || message.type === "sync.reset") {
                 notify();
             }
             else if (message.type === "sync.error") {
@@ -579,7 +626,6 @@ export class GonvexClient {
         const unsubscribeScope = this.onSessionScopeChange(() => {
             latest = undefined;
             latestError = undefined;
-            isUpToDate = false;
             notify();
         });
         return {
@@ -589,7 +635,10 @@ export class GonvexClient {
                 return latest;
             },
             status() {
-                return { isLoading: latest === undefined, isUpToDate };
+                return {
+                    isLoading: latest === undefined,
+                    isUpToDate: thisClient.syncSubscriptions.get(key)?.isUpToDate === true,
+                };
             },
             onUpdate(handler) {
                 updateHandlers.add(handler);
@@ -605,7 +654,18 @@ export class GonvexClient {
     }
     handleSyncMessage(subscription, message) {
         if (message.type === "sync.snapshot") {
+            // Snapshots are only valid responses to an outstanding sync.open. Live
+            // subscriptions advance through deltas; accepting an unsolicited or
+            // delayed snapshot could roll a verified collection back to old rows.
+            if (!subscription.opening)
+                return;
+            if (subscription.cursor
+                && message.cursor.epoch === subscription.cursor.epoch
+                && message.cursor.revision < subscription.cursor.revision)
+                return;
             this.clearSyncRetry(subscription, true);
+            subscription.verificationGeneration += 1;
+            subscription.isUpToDate = false;
             subscription.opening = false;
             subscription.cursor = message.cursor;
             subscription.keyField = message.key;
@@ -615,6 +675,9 @@ export class GonvexClient {
             subscription.maxRows = message.maxRows;
             subscription.maxBytes = message.maxBytes;
             subscription.rows = boundSyncRows(message.result, message.key, message.maxRows, message.maxBytes, message.orderBy, message.orderDirection);
+            subscription.hashes = { ...(message.hashes ?? {}) };
+            subscription.integrityDigest = undefined;
+            subscription.integrityRows = undefined;
             const snapshot = { ...message, result: subscription.rows };
             subscription.lastMessage = snapshot;
             this.emitSyncMessage(subscription, snapshot);
@@ -623,11 +686,20 @@ export class GonvexClient {
         }
         if (message.type === "sync.delta") {
             if (subscription.cursor && (message.cursor.epoch !== subscription.cursor.epoch
-                || message.cursor.revision <= subscription.cursor.revision))
+                || message.cursor.revision < subscription.cursor.revision
+                || (message.cursor.revision === subscription.cursor.revision
+                    && !message.digest)))
                 return;
             this.clearSyncRetry(subscription, true);
+            subscription.verificationGeneration += 1;
+            subscription.isUpToDate = false;
             subscription.cursor = message.cursor;
             subscription.rows = applySyncDelta(subscription.rows, subscription.keyField, message.upserts ?? [], message.deleted ?? [], subscription.maxRows, subscription.maxBytes, subscription.orderBy, subscription.orderDirection);
+            for (const key of message.deleted ?? [])
+                delete subscription.hashes[key];
+            Object.assign(subscription.hashes, message.hashes ?? {});
+            subscription.integrityDigest = undefined;
+            subscription.integrityRows = undefined;
             const snapshot = {
                 type: "sync.snapshot",
                 id: subscription.id,
@@ -648,35 +720,128 @@ export class GonvexClient {
         }
         if (message.type === "sync.reset") {
             this.clearSyncRetry(subscription, true);
+            subscription.verificationGeneration += 1;
+            subscription.isUpToDate = false;
             subscription.cursor = undefined;
             subscription.rows = [];
+            subscription.hashes = {};
+            subscription.integrityDigest = undefined;
+            subscription.integrityRows = undefined;
+            subscription.forceFullIntegrity = false;
             subscription.lastMessage = undefined;
             subscription.opening = false;
             const directive = this.queryCacheDirective;
             const store = this.syncStore;
             if (directive && store) {
-                this.enqueueSyncPersistence(subscription, () => store.delete(directive.scope, subscription.path, subscription.args));
+                const scope = syncPersistenceScope(directive);
+                this.enqueueSyncPersistence(subscription, scope, () => store.delete(scope, subscription.path, subscription.args));
             }
+            this.emitSyncMessage(subscription, message);
             queueMicrotask(() => this.sendSyncOpen(subscription));
             return;
         }
-        if (message.type === "sync.ready") {
-            this.clearSyncRetry(subscription, true);
+        if (message.type === "sync.syncing") {
+            subscription.verificationGeneration += 1;
+            subscription.isUpToDate = false;
+            this.emitSyncMessage(subscription, message);
+            return;
+        }
+        if (message.type === "sync.needHashes") {
+            subscription.verificationGeneration += 1;
+            subscription.isUpToDate = false;
             subscription.opening = false;
-            subscription.cursor = message.cursor;
-            subscription.mode = message.mode ?? subscription.mode;
-            this.persistSyncSnapshot(subscription);
+            subscription.forceFullIntegrity = true;
+            this.emitSyncMessage(subscription, {
+                type: "sync.syncing",
+                id: subscription.id,
+                path: subscription.path,
+                reason: "integrity-reconciling",
+            });
+            queueMicrotask(() => this.sendSyncOpen(subscription));
+            return;
+        }
+        if (message.type === "sync.ready") {
+            if (!subscription.cursor || (message.cursor.epoch !== subscription.cursor.epoch
+                || message.cursor.revision < subscription.cursor.revision))
+                return;
+            const generation = ++subscription.verificationGeneration;
+            if (!message.digest && this.serverCapabilities.syncIntegrity === 1) {
+                this.handleSyncMessage(subscription, {
+                    type: "sync.reset",
+                    id: subscription.id,
+                    path: subscription.path,
+                    reason: "integrity-missing",
+                });
+                return;
+            }
+            void syncRowsHashes(subscription.rows, subscription.keyField).then((hashes) => (syncHashesDigest(hashes).then((digest) => ({ digest, hashes })))).then(({ digest, hashes }) => {
+                if (generation !== subscription.verificationGeneration
+                    || this.syncSubscriptions.get(subscription.key) !== subscription)
+                    return;
+                if (message.digest && digest !== message.digest) {
+                    this.handleSyncMessage(subscription, {
+                        type: "sync.reset",
+                        id: subscription.id,
+                        path: subscription.path,
+                        reason: "integrity-mismatch",
+                    });
+                    return;
+                }
+                subscription.hashes = hashes;
+                subscription.integrityDigest = digest;
+                subscription.integrityRows = subscription.rows;
+                this.acceptSyncReady(subscription, message, digest);
+            }).catch(() => {
+                if (generation !== subscription.verificationGeneration)
+                    return;
+                this.handleSyncMessage(subscription, {
+                    type: "sync.reset",
+                    id: subscription.id,
+                    path: subscription.path,
+                    reason: "integrity-mismatch",
+                });
+            });
+            return;
         }
         if (message.type === "sync.error") {
+            subscription.verificationGeneration += 1;
+            subscription.isUpToDate = false;
             subscription.opening = false;
             this.scheduleSyncRetry(subscription);
         }
         this.emitSyncMessage(subscription, message);
     }
+    acceptSyncReady(subscription, message, verifiedDigest = message.digest) {
+        this.clearSyncRetry(subscription, true);
+        subscription.isUpToDate = true;
+        subscription.opening = false;
+        subscription.cursor = message.cursor;
+        subscription.mode = message.mode ?? subscription.mode;
+        subscription.integrityDigest = verifiedDigest;
+        subscription.integrityRows = subscription.rows;
+        subscription.forceFullIntegrity = false;
+        this.persistSyncSnapshot(subscription);
+        this.emitSyncMessage(subscription, message);
+    }
     emitSyncMessage(subscription, message) {
         for (const listener of Array.from(subscription.listeners))
             listener(message);
     }
+    markSyncSubscriptionsOutOfDate() {
+        for (const subscription of this.syncSubscriptions.values()) {
+            const wasUpToDate = subscription.isUpToDate;
+            subscription.verificationGeneration += 1;
+            subscription.isUpToDate = false;
+            if (!wasUpToDate)
+                continue;
+            this.emitSyncMessage(subscription, {
+                type: "sync.syncing",
+                id: subscription.id,
+                path: subscription.path,
+                reason: "disconnected",
+            });
+        }
+    }
     startSync(subscription) {
         const directive = this.queryCacheDirective;
         const store = this.syncStore;
@@ -686,16 +851,20 @@ export class GonvexClient {
             this.sendSyncOpen(subscription);
             return;
         }
-        const generation = this.queryCacheGeneration;
+        const scope = syncPersistenceScope(directive);
+        const generation = this.syncScopeGeneration;
         if (subscription.cacheReadGeneration === generation)
             return;
         subscription.cacheReadGeneration = generation;
-        void store.load(directive.scope, subscription.path, subscription.args).then((cached) => {
+        void store.load(scope, subscription.path, subscription.args).then((cached) => {
+            const currentDirective = this.queryCacheDirective;
             if (this.syncSubscriptions.get(subscription.key) !== subscription
-                || this.queryCacheGeneration !== generation
-                || this.queryCacheDirective?.scope !== directive.scope)
+                || this.syncScopeGeneration !== generation
+                || !currentDirective
+                || syncPersistenceScope(currentDirective) !== scope)
                 return;
             if (cached) {
+                subscription.isUpToDate = false;
                 subscription.rows = cached.rows;
                 subscription.cursor = cached.cursor;
                 subscription.keyField = cached.keyField;
@@ -704,6 +873,12 @@ export class GonvexClient {
                 subscription.orderDirection = cached.orderDirection;
                 subscription.maxRows = cached.maxRows;
                 subscription.maxBytes = cached.maxBytes;
+                // Stored hash metadata is never trusted. sendSyncOpen hashes these
+                // actual materialized rows before advertising a cursor, which allows a
+                // corrupt row to be repaired by delta without a full cache reset.
+                subscription.hashes = {};
+                subscription.integrityDigest = undefined;
+                subscription.integrityRows = undefined;
                 const message = {
                     type: "sync.snapshot",
                     id: subscription.id,
@@ -726,6 +901,38 @@ export class GonvexClient {
     sendSyncOpen(subscription) {
         if (subscription.listeners.size === 0 || subscription.opening)
             return;
+        if (subscription.cursor && subscription.integrityRows !== subscription.rows) {
+            subscription.opening = true;
+            const rows = subscription.rows;
+            const keyField = subscription.keyField;
+            const socketGeneration = this.socketGeneration;
+            void syncRowsHashes(rows, keyField).then((hashes) => (syncHashesDigest(hashes).then((digest) => ({ hashes, digest })))).then(({ hashes, digest }) => {
+                if (this.socketGeneration !== socketGeneration
+                    || this.syncSubscriptions.get(subscription.key) !== subscription
+                    || subscription.listeners.size === 0
+                    || subscription.rows !== rows
+                    || subscription.keyField !== keyField)
+                    return;
+                subscription.hashes = hashes;
+                subscription.integrityDigest = digest;
+                subscription.integrityRows = rows;
+                subscription.opening = false;
+                this.sendSyncOpen(subscription);
+            }).catch(() => {
+                if (this.socketGeneration !== socketGeneration
+                    || this.syncSubscriptions.get(subscription.key) !== subscription
+                    || subscription.rows !== rows)
+                    return;
+                subscription.opening = false;
+                this.handleSyncMessage(subscription, {
+                    type: "sync.reset",
+                    id: subscription.id,
+                    path: subscription.path,
+                    reason: "integrity-mismatch",
+                });
+            });
+            return;
+        }
         subscription.opening = true;
         subscription.socketGeneration = this.socketGeneration;
         const open = this.syncOpenRequest(subscription);
@@ -739,15 +946,23 @@ export class GonvexClient {
         this.send({ type: "sync.open", ...open });
     }
     syncOpenRequest(subscription) {
-        const keys = subscription.mode === "eager"
-            ? undefined
-            : subscription.rows.map((row) => syncRowKey(row, subscription.keyField)).filter(Boolean);
+        const fullIntegrity = subscription.cursor !== undefined && (subscription.forceFullIntegrity
+            || !subscription.integrityDigest
+            || subscription.rows.length <= compactSyncIntegrityThreshold);
+        const keys = fullIntegrity
+            ? subscription.rows.map((row) => syncRowKey(row, subscription.keyField)).filter(Boolean)
+            : undefined;
         return {
             id: subscription.id,
             path: subscription.path,
             args: subscription.args,
             cursor: subscription.cursor,
             keys,
+            hashes: fullIntegrity && Object.keys(subscription.hashes).length > 0
+                ? subscription.hashes
+                : undefined,
+            digest: subscription.cursor ? subscription.integrityDigest : undefined,
+            fullIntegrity: fullIntegrity || undefined,
         };
     }
     flushSyncOpens() {
@@ -759,28 +974,35 @@ export class GonvexClient {
             && subscription.listeners.size > 0
             && this.syncSubscriptions.get(subscription.key) === subscription))
             .map((subscription) => this.syncOpenRequest(subscription));
-        if (opens.length === 0)
-            return;
-        this.send({ type: "sync.openMany", opens });
+        for (let offset = 0; offset < opens.length; offset += maxSyncBatchOpens) {
+            this.send({ type: "sync.openMany", opens: opens.slice(offset, offset + maxSyncBatchOpens) });
+        }
     }
     unsubscribeSyncListener(key, listener) {
         const subscription = this.syncSubscriptions.get(key);
         if (!subscription)
             return;
         subscription.listeners.delete(listener);
-        if (subscription.listeners.size > 0)
+        if (subscription.listeners.size > 0 || subscription.unsubscribeTimer)
             return;
-        this.clearSyncRetry(subscription);
-        this.pendingSyncOpens.delete(subscription);
-        this.syncSubscriptions.delete(key);
-        this.handlers.delete(subscription.id);
-        this.send({ type: "sync.close", id: subscription.id });
+        subscription.unsubscribeTimer = setTimeout(() => {
+            const latest = this.syncSubscriptions.get(key);
+            if (!latest || latest.listeners.size > 0)
+                return;
+            latest.unsubscribeTimer = undefined;
+            this.clearSyncRetry(latest);
+            this.pendingSyncOpens.delete(latest);
+            this.syncSubscriptions.delete(key);
+            this.handlers.delete(latest.id);
+            this.send({ type: "sync.close", id: latest.id });
+        }, this.syncSubscriptionRetentionMs);
     }
     persistSyncSnapshot(subscription) {
         const directive = this.queryCacheDirective;
         const store = this.syncStore;
         if (!directive || !store || !subscription.cursor)
             return;
+        const scope = syncPersistenceScope(directive);
         const value = {
             rows: subscription.rows,
             cursor: subscription.cursor,
@@ -790,14 +1012,16 @@ export class GonvexClient {
             orderDirection: subscription.orderDirection,
             maxRows: subscription.maxRows,
             maxBytes: subscription.maxBytes,
+            hashes: { ...subscription.hashes },
         };
-        this.enqueueSyncPersistence(subscription, () => store.replace(directive.scope, subscription.path, subscription.args, value));
+        this.enqueueSyncPersistence(subscription, scope, () => store.replace(scope, subscription.path, subscription.args, value));
     }
     persistSyncDelta(subscription, upserts, deleted) {
         const directive = this.queryCacheDirective;
         const store = this.syncStore;
         if (!directive || !store || !subscription.cursor)
             return;
+        const scope = syncPersistenceScope(directive);
         const value = {
             cursor: subscription.cursor,
             keyField: subscription.keyField,
@@ -808,8 +1032,9 @@ export class GonvexClient {
             deleted,
             maxRows: subscription.maxRows,
             maxBytes: subscription.maxBytes,
+            hashes: { ...subscription.hashes },
         };
-        this.enqueueSyncPersistence(subscription, () => store.applyDelta(directive.scope, subscription.path, subscription.args, value));
+        this.enqueueSyncPersistence(subscription, scope, () => store.applyDelta(scope, subscription.path, subscription.args, value));
     }
     mutation(ref, args = {}, options = {}) {
         return this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs);
@@ -885,11 +1110,73 @@ export class GonvexClient {
         this.connect();
         this.sendSubscription(subscription);
     }
+    /**
+     * Flush a queue of mutations in one `mutation.callMany` frame (queue order,
+     * one websocket round trip). Each entry settles independently — a failed
+     * call does not reject the batch — so offline queues can apply per-row
+     * outcomes. Falls back to sequential `mutation` calls on runtimes that do
+     * not advertise the `mutationBatch` capability.
+     */
+    async mutationMany(calls, options = {}) {
+        if (calls.length === 0)
+            return [];
+        this.connect();
+        const timeoutMs = options.timeoutMs ?? this.timeouts.mutationTimeoutMs;
+        const settle = (promise, path) => promise
+            .then((result) => ({ status: "ok", result }))
+            .catch((error) => ({
+            status: "error",
+            error: error instanceof GonvexClientError
+                ? error
+                : new GonvexClientError(String(error), { code: "server", path, operation: "mutation" }),
+        }));
+        if (this.serverCapabilities.mutationBatch !== 1) {
+            const outcomes = [];
+            for (const call of calls) {
+                outcomes.push(await settle(this.mutation(call.ref, call.args ?? {}, options), call.ref.path));
+            }
+            return outcomes;
+        }
+        const registered = calls.map((call) => {
+            const entry = this.registerCall("mutation", call.ref, call.args ?? {}, timeoutMs);
+            return { ...entry, path: call.ref.path, args: call.args ?? {} };
+        });
+        for (let offset = 0; offset < registered.length; offset += maxSyncBatchOpens) {
+            this.send({
+                type: "mutation.callMany",
+                calls: registered.slice(offset, offset + maxSyncBatchOpens).map((entry) => ({
+                    id: entry.id,
+                    path: entry.path,
+                    args: entry.args,
+                    trace: { clientSentAtMs: entry.clientSentAtMs },
+                })),
+            });
+        }
+        this.notifyConnectionState();
+        return Promise.all(registered.map((entry) => settle(entry.promise, entry.path)));
+    }
     call(kind, ref, args, timeoutMs) {
         this.connect();
+        const entry = this.registerCall(kind, ref, args, timeoutMs);
+        if (kind === "mutation") {
+            try {
+                const w = globalThis;
+                if (w && w.__wsTapLog)
+                    w.__wsTapLog.push({ dir: "mut-args", type: "mutation.call", path: ref.path, argTenant: (args && args.tenantId) || null, authTenant: this.auth?.tenant || null, authProject: this.auth?.project || null, href: (w.location && w.location.href) || null });
+            }
+            catch (e) { }
+            this.send({ type: "mutation.call", id: entry.id, path: ref.path, args, trace: { clientSentAtMs: entry.clientSentAtMs } });
+        }
+        else {
+            this.send({ type: "action.call", id: entry.id, path: ref.path, args, trace: { clientSentAtMs: entry.clientSentAtMs } });
+        }
+        this.notifyConnectionState();
+        return entry.promise;
+    }
+    registerCall(kind, ref, args, timeoutMs) {
         const id = randomID();
         const clientSentAtMs = nowMs();
-        return new Promise((resolve, reject) => {
+        const promise = new Promise((resolve, reject) => {
             const pending = { id, kind, path: ref.path, reject };
             const settle = () => {
                 if (pending.timeoutTimer)
@@ -927,14 +1214,8 @@ export class GonvexClient {
                     reject(new GonvexClientError(message.error, { code: "server", path: ref.path, operation: kind }));
                 }
             });
-            if (kind === "mutation") {
-                this.send({ type: "mutation.call", id, path: ref.path, args, trace: { clientSentAtMs } });
-            }
-            else {
-                this.send({ type: "action.call", id, path: ref.path, args, trace: { clientSentAtMs } });
-            }
-            this.notifyConnectionState();
         });
+        return { id, clientSentAtMs, promise };
     }
     unsubscribeQueryListener(key, listener) {
         const subscription = this.querySubscriptions.get(key);
@@ -975,6 +1256,15 @@ export class GonvexClient {
             }
         }
         subscription.socketGeneration = this.socketGeneration;
+        // Route reloads register dozens of live queries at once. Collapse the
+        // burst into one batched frame per tick instead of one frame per query.
+        if (this.serverCapabilities.queryBatch === 1) {
+            this.pendingQuerySubscribes.add(subscription);
+            if (!this.querySubscribeFlushTimer) {
+                this.querySubscribeFlushTimer = setTimeout(() => this.flushQuerySubscribes(), 0);
+            }
+            return;
+        }
         this.send({
             type: "query.subscribe",
             id: subscription.id,
@@ -983,6 +1273,24 @@ export class GonvexClient {
             cacheRevision: subscription.cachedRevision,
         });
     }
+    flushQuerySubscribes() {
+        this.querySubscribeFlushTimer = undefined;
+        const subscriptions = Array.from(this.pendingQuerySubscribes);
+        this.pendingQuerySubscribes.clear();
+        const subscribes = subscriptions
+            .filter((subscription) => (subscription.listeners.size > 0
+            && subscription.socketGeneration === this.socketGeneration
+            && this.querySubscriptions.get(subscription.key) === subscription))
+            .map((subscription) => ({
+            id: subscription.id,
+            path: subscription.path,
+            args: subscription.args,
+            cacheRevision: subscription.cachedRevision,
+        }));
+        for (let offset = 0; offset < subscribes.length; offset += maxSyncBatchOpens) {
+            this.send({ type: "query.subscribeMany", subscribes: subscribes.slice(offset, offset + maxSyncBatchOpens) });
+        }
+    }
     resumeQuerySubscriptions() {
         for (const subscription of this.querySubscriptions.values()) {
             if (subscription.listeners.size === 0)
@@ -990,11 +1298,19 @@ export class GonvexClient {
             this.sendSubscription(subscription);
         }
     }
-    enqueueSyncPersistence(subscription, operation) {
-        subscription.persistence = subscription.persistence
+    enqueueSyncPersistence(subscription, scope, operation) {
+        const key = `${scope}\u0000${subscription.key}`;
+        const previous = this.syncPersistence.get(key) ?? Promise.resolve();
+        const pending = previous
             .catch(() => undefined)
             .then(operation)
             .catch(() => undefined);
+        this.syncPersistence.set(key, pending);
+        subscription.persistence = pending;
+        void pending.finally(() => {
+            if (this.syncPersistence.get(key) === pending)
+                this.syncPersistence.delete(key);
+        });
     }
     scheduleSyncRetry(subscription) {
         if (this.manuallyClosed
@@ -1024,6 +1340,10 @@ export class GonvexClient {
             subscription.retryAttempt = 0;
     }
     requestSubscriptionSnapshot(subscription) {
+        // Do not advertise the cache revision while recovering. Otherwise the
+        // runtime can answer with another progress frame instead of a snapshot.
+        subscription.cachedRevision = undefined;
+        subscription.serverSettled = false;
         subscription.socketGeneration = undefined;
         this.sendSubscription(subscription);
     }
@@ -1073,12 +1393,21 @@ export class GonvexClient {
                 this.resetQueryCacheScope();
             return;
         }
-        if (this.queryCacheDirective?.scope === value.scope) {
+        const previous = this.queryCacheDirective;
+        const syncScopeChanged = previous !== undefined
+            && syncPersistenceScope(previous) !== syncPersistenceScope(value);
+        if (previous?.scope === value.scope && !syncScopeChanged) {
             this.queryCacheDirective = value;
             return;
         }
-        if (this.queryCacheDirective) {
-            this.resetQueryCacheScope();
+        if (previous) {
+            // A deploy rotates the query-result scope (results depend on code), but
+            // sync collections are keyed by visibility and survive it: their rows,
+            // cursors, and in-flight warm reads stay valid and are verified by the
+            // server's reconcile on the next open.
+            this.resetQueryResultCacheState();
+            if (syncScopeChanged)
+                this.resetSyncCacheState();
         }
         this.queryCacheDirective = value;
         const identity = authIdentityKey(this.auth);
@@ -1108,8 +1437,16 @@ export class GonvexClient {
     }
     resetQueryCacheScope() {
         const hadScope = this.queryCacheDirective !== undefined;
-        this.queryCacheGeneration += 1;
         this.queryCacheDirective = undefined;
+        this.resetQueryResultCacheState();
+        this.resetSyncCacheState();
+        if (hadScope || this.querySubscriptions.size > 0 || this.syncSubscriptions.size > 0) {
+            for (const handler of this.sessionScopeHandlers)
+                handler();
+        }
+    }
+    resetQueryResultCacheState() {
+        this.queryCacheGeneration += 1;
         this.queryCacheNegotiatedSocketGeneration = undefined;
         for (const subscription of this.querySubscriptions.values()) {
             subscription.lastMessage = undefined;
@@ -1121,17 +1458,22 @@ export class GonvexClient {
             subscription.cacheReadFallbackTimer = undefined;
             subscription.cachedRevision = undefined;
         }
+    }
+    resetSyncCacheState() {
+        this.syncScopeGeneration += 1;
         for (const subscription of this.syncSubscriptions.values()) {
             this.clearSyncRetry(subscription, true);
+            subscription.isUpToDate = false;
             subscription.rows = [];
+            subscription.hashes = {};
+            subscription.integrityDigest = undefined;
+            subscription.integrityRows = undefined;
+            subscription.forceFullIntegrity = false;
             subscription.cursor = undefined;
             subscription.lastMessage = undefined;
             subscription.cacheReadGeneration = undefined;
             subscription.opening = false;
-        }
-        if (hadScope || this.querySubscriptions.size > 0 || this.syncSubscriptions.size > 0) {
-            for (const handler of this.sessionScopeHandlers)
-                handler();
+            subscription.verificationGeneration += 1;
         }
     }
     startQueryCacheRead(subscription) {
@@ -1275,7 +1617,14 @@ export class GonvexClient {
             return;
         this.authInFlight = true;
         this.armAuthWatchdog();
-        this.sendNow({ type: "auth", id: randomID(), token: this.auth.token, project: this.auth.project, tenant: this.auth.tenant });
+        this.sendNow({
+            type: "auth",
+            id: randomID(),
+            token: this.auth.token,
+            project: this.auth.project,
+            tenant: this.auth.tenant,
+            device: browserTelemetryInfo(),
+        });
     }
     // A lost auth reply (e.g. the server swapped its app plugin and dropped
     // in-flight responses while the socket stayed up) used to leave
@@ -1350,16 +1699,31 @@ function countPendingCalls(calls, kind) {
     return count;
 }
 function stableStringify(value) {
+    if (typeof value === "string") {
+        return JSON.stringify(value)
+            .replace(/\u2028/g, "\\u2028")
+            .replace(/\u2029/g, "\\u2029");
+    }
     if (value === null || typeof value !== "object")
         return JSON.stringify(value);
     if (Array.isArray(value))
         return `[${value.map(stableStringify).join(",")}]`;
     const record = value;
     return `{${Object.keys(record)
-        .sort()
-        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .sort(utf8KeyCompare)
+        .map((key) => `${stableStringify(key)}:${stableStringify(record[key])}`)
         .join(",")}}`;
 }
+function utf8KeyCompare(left, right) {
+    const leftBytes = new TextEncoder().encode(left);
+    const rightBytes = new TextEncoder().encode(right);
+    const length = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < length; index += 1) {
+        if (leftBytes[index] !== rightBytes[index])
+            return leftBytes[index] - rightBytes[index];
+    }
+    return leftBytes.length - rightBytes.length;
+}
 function sameRevision(left, right) {
     return !!right && left.epoch === right.epoch && left.sequence === right.sequence;
 }
@@ -1420,7 +1784,7 @@ function syncRowKey(value, keyField) {
     return key === null || key === undefined ? "" : String(key);
 }
 function syncJSONSize(value) {
-    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+    return new TextEncoder().encode(stableStringify(value)).byteLength;
 }
 function applyKeyedPatch(previous, patch) {
     const rows = new Map();
@@ -1511,12 +1875,25 @@ function validQueryCacheDirective(value) {
     return value.protocolVersion === 1
         && typeof value.scope === "string"
         && value.scope.length >= 16
+        && (value.syncScope === undefined
+            || (typeof value.syncScope === "string" && value.syncScope.length >= 16))
         && typeof value.epoch === "string"
         && value.epoch.length >= 16
         && typeof value.maxAgeMs === "number"
         && Number.isFinite(value.maxAgeMs)
         && value.maxAgeMs > 0;
 }
+/**
+ * The scope under which sync collections are persisted and resumed. Newer
+ * runtimes send a visibility-only `syncScope` that survives deploys (the
+ * authoritative reconcile on resume guarantees correctness across code
+ * changes); older runtimes only send the bundle-epoch `scope`.
+ */
+function syncPersistenceScope(directive) {
+    return typeof directive.syncScope === "string" && directive.syncScope.length >= 16
+        ? directive.syncScope
+        : directive.scope;
+}
 function isJsonRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }