@gonvex/client 0.1.30 → 0.1.32

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createQueryCacheStore, defaultQueryCacheReadTimeoutMs, } from "./query-cache.js";
 import { createSyncStore, syncHashesDigest, syncRowsHashes, } from "./sync-store.js";
 import { GonvexErrorReporter } from "./error-reporter.js";
-import { OptimisticOverlay } from "./optimistic.js";
+import { OptimisticOverlay, optimisticPatchesFromReference, } from "./optimistic.js";
 import { createMutationOutbox, } from "./outbox.js";
 export * from "./cache.js";
 export * from "./cache-coordinator.js";
@@ -15,7 +15,24 @@ export * from "./sync-store.js";
 export * from "./error-reporter.js";
 export * from "./optimistic.js";
 export * from "./outbox.js";
+export * from "./kv-stores.js";
 export * from "./signals.js";
+function syncCursorIsStale(subscription, cursor) {
+    if (subscription.retiredEpochs.has(cursor.epoch))
+        return true;
+    const floor = subscription.cursorFloor;
+    return floor?.epoch === cursor.epoch && cursor.revision < floor.revision;
+}
+function raiseSyncCursorFloor(subscription, cursor) {
+    if (subscription.cursorFloor && subscription.cursorFloor.epoch !== cursor.epoch) {
+        subscription.retiredEpochs.add(subscription.cursorFloor.epoch);
+    }
+    if (!subscription.cursorFloor
+        || subscription.cursorFloor.epoch !== cursor.epoch
+        || cursor.revision > subscription.cursorFloor.revision) {
+        subscription.cursorFloor = cursor;
+    }
+}
 /**
  * Typed error for every rejected Gonvex operation. `code` distinguishes
  * server-side failures from transport-level ones so apps can decide whether
@@ -98,7 +115,11 @@ export class GonvexClient {
     mutationOutbox;
     overlay = new OptimisticOverlay();
     optimisticMutationIds = new Set();
+    optimisticOutboxEntryIds = new Map();
     outboxReady;
+    outboxScope = "";
+    outboxScopeGeneration = 0;
+    outboxEphemeralScope = randomID();
     unsubscribeOutbox;
     unsubscribeOverlay;
     drainingOutbox = false;
@@ -136,10 +157,14 @@ export class GonvexClient {
         this.unsubscribeOutbox = this.mutationOutbox.subscribe(() => {
             void this.drainOutbox();
         });
-        this.unsubscribeOverlay = this.overlay.subscribe((collection) => {
-            this.emitOptimisticCollection(collection);
+        this.unsubscribeOverlay = this.overlay.subscribe((entity) => {
+            this.emitOptimisticEntity(entity);
         });
-        this.outboxReady = this.restoreOutbox();
+        // Defer the first restore by one microtask. Apps commonly construct the
+        // client and immediately install a cached token/identity; waiting lets the
+        // durable queue select that authenticated scope instead of briefly
+        // restoring an anonymous user's entries.
+        this.outboxReady = Promise.resolve().then(() => this.activateOutboxScope());
         this.timeouts = {
             queryTimeoutMs: options.timeouts?.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
             mutationTimeoutMs: options.timeouts?.mutationTimeoutMs ?? DEFAULT_MUTATION_TIMEOUT_MS,
@@ -157,7 +182,7 @@ export class GonvexClient {
     /** Number of mutations waiting for a definitive server result. */
     async outboxCount() {
         await this.outboxReady;
-        return this.mutationOutbox.count();
+        return this.mutationOutbox.count(this.outboxScope);
     }
     connectionState() {
         const inflightMutations = countPendingCalls(this.pendingCalls, "mutation");
@@ -231,8 +256,10 @@ export class GonvexClient {
             this.resetQueryCacheScope();
         }
         this.auth = nextAuth;
-        if (scopeMayChange)
+        if (scopeMayChange) {
+            void this.activateOutboxScope();
             this.recoverWarmSyncDirective();
+        }
         if (auth.tenant !== undefined)
             this.errorReporter?.setTenant(auth.tenant);
         if (auth.project !== undefined)
@@ -385,6 +412,9 @@ export class GonvexClient {
     }
     close() {
         this.manuallyClosed = true;
+        if (isEphemeralOutboxScope(this.outboxScope)) {
+            void this.mutationOutbox.clear(this.outboxScope);
+        }
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = undefined;
@@ -517,7 +547,7 @@ export class GonvexClient {
             else if (cached) {
                 queueMicrotask(() => {
                     if (existing.listeners.has(onMessage))
-                        onMessage(cached);
+                        onMessage(this.materializeQueryMessage(existing, cached));
                 });
             }
             return () => this.unsubscribeQueryListener(key, onMessage);
@@ -526,10 +556,14 @@ export class GonvexClient {
             id: randomID(),
             key,
             path: ref.path,
+            projection: ref.optimistic?.projection,
             args,
             listeners: new Set([onMessage]),
             serverSettled: false,
         };
+        if (subscription.projection) {
+            this.overlay.expectSource(subscription.key, subscription.projection.entity);
+        }
         this.querySubscriptions.set(key, subscription);
         this.handlers.set(subscription.id, (message) => {
             const normalized = this.normalizeSubscriptionMessage(subscription, message);
@@ -564,8 +598,13 @@ export class GonvexClient {
                     clientReceivedAtMs: nowMs(),
                 });
             }
+            const outgoing = this.materializeQueryMessage(subscription, message);
             for (const listener of Array.from(subscription.listeners)) {
-                listener(message);
+                listener(outgoing);
+            }
+            if (message.type === "query.result") {
+                this.acknowledgeOptimisticSource(subscription.key, message.mutationIds);
+                this.acknowledgeOptimisticQuerySnapshot(subscription, message.result);
             }
             if (message.type === "query.result") {
                 this.persistQueryResult(subscription, message);
@@ -592,6 +631,7 @@ export class GonvexClient {
             subscription.lastRevision = message.throughRevision;
             subscription.revisionSocketGeneration = this.socketGeneration;
             subscription.serverSettled = true;
+            this.acknowledgeOptimisticSource(subscription.key, message.mutationIds);
             // Progress advances freshness without waking React/query listeners.
             return undefined;
         }
@@ -626,6 +666,7 @@ export class GonvexClient {
                 cacheScope: message.cacheScope,
                 cacheRevision: message.cacheRevision,
                 subscriptionRevision: message.subscriptionRevision,
+                mutationIds: message.mutationIds,
             };
         }
         if (message.type === "query.pagePatch") {
@@ -648,7 +689,7 @@ export class GonvexClient {
             const metadata = isJsonRecord(message.result) ? message.result : {};
             subscription.lastRevision = message.subscriptionRevision;
             subscription.revisionSocketGeneration = this.socketGeneration;
-            return { ...message, type: "query.result", result: { ...previous.result, ...metadata, page } };
+            return { ...message, type: "query.result", result: { ...previous.result, ...metadata, page }, mutationIds: message.mutationIds };
         }
         if (message.type === "query.objectPatch") {
             if (!sameRevision(message.baseRevision, subscription.lastRevision)) {
@@ -678,7 +719,7 @@ export class GonvexClient {
             }
             subscription.lastRevision = message.subscriptionRevision;
             subscription.revisionSocketGeneration = this.socketGeneration;
-            return { ...message, type: "query.result", result };
+            return { ...message, type: "query.result", result, mutationIds: message.mutationIds };
         }
         if (message.type === "query.result" && message.subscriptionRevision) {
             if (!this.acceptRevision(subscription, message.subscriptionRevision))
@@ -763,6 +804,7 @@ export class GonvexClient {
             id: randomID(),
             key,
             path: ref.path,
+            entity: ref.optimistic?.projection?.entity ?? ref.path,
             args,
             listeners: new Set([onMessage]),
             rows: [],
@@ -774,7 +816,9 @@ export class GonvexClient {
             hashes: {},
             forceFullIntegrity: false,
             verificationGeneration: 0,
+            retiredEpochs: new Set(),
         };
+        this.overlay.expectSource(subscription.key, subscription.entity);
         this.syncSubscriptions.set(key, subscription);
         this.handlers.set(subscription.id, (message) => this.handleSyncMessage(subscription, message));
         this.startSync(subscription);
@@ -844,6 +888,8 @@ export class GonvexClient {
             // delayed snapshot could roll a verified collection back to old rows.
             if (!subscription.opening)
                 return;
+            if (syncCursorIsStale(subscription, message.cursor))
+                return;
             if (subscription.cursor
                 && message.cursor.epoch === subscription.cursor.epoch
                 && message.cursor.revision < subscription.cursor.revision)
@@ -853,6 +899,7 @@ export class GonvexClient {
             subscription.isUpToDate = false;
             subscription.opening = false;
             subscription.cursor = message.cursor;
+            raiseSyncCursorFloor(subscription, message.cursor);
             subscription.keyField = message.key;
             subscription.mode = message.mode;
             subscription.truncated = undefined;
@@ -872,6 +919,8 @@ export class GonvexClient {
             return;
         }
         if (message.type === "sync.delta") {
+            if (syncCursorIsStale(subscription, message.cursor))
+                return;
             if (subscription.cursor && (message.cursor.epoch !== subscription.cursor.epoch
                 || message.cursor.revision < subscription.cursor.revision
                 || (message.cursor.revision === subscription.cursor.revision
@@ -881,6 +930,7 @@ export class GonvexClient {
             subscription.verificationGeneration += 1;
             subscription.isUpToDate = false;
             subscription.cursor = message.cursor;
+            raiseSyncCursorFloor(subscription, 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];
@@ -903,6 +953,7 @@ export class GonvexClient {
             };
             subscription.lastMessage = snapshot;
             this.emitSyncMessage(subscription, snapshot);
+            this.acknowledgeOptimisticSource(subscription.key, message.mutationIds);
             this.persistSyncDelta(subscription, message.upserts ?? [], message.deleted ?? []);
             return;
         }
@@ -957,7 +1008,8 @@ export class GonvexClient {
         }
         if (message.type === "sync.ready") {
             if (!subscription.cursor || (message.cursor.epoch !== subscription.cursor.epoch
-                || message.cursor.revision < subscription.cursor.revision))
+                || message.cursor.revision < subscription.cursor.revision
+                || syncCursorIsStale(subscription, message.cursor)))
                 return;
             const generation = ++subscription.verificationGeneration;
             if (!message.digest && this.serverCapabilities.syncIntegrity === 1) {
@@ -1025,6 +1077,7 @@ export class GonvexClient {
         subscription.isUpToDate = true;
         subscription.opening = false;
         subscription.cursor = message.cursor;
+        raiseSyncCursorFloor(subscription, message.cursor);
         subscription.mode = message.mode ?? subscription.mode;
         subscription.truncated = message.truncated;
         subscription.integrityDigest = verifiedDigest;
@@ -1052,6 +1105,7 @@ export class GonvexClient {
                 || subscription.integrityEpoch !== cursor.epoch)
                 continue;
             subscription.cursor = { ...cursor, revision };
+            raiseSyncCursorFloor(subscription, subscription.cursor);
             this.scheduleSyncWatermarkPersistence(subscription);
         }
     }
@@ -1069,21 +1123,69 @@ export class GonvexClient {
         const outgoing = this.materializeSyncMessage(subscription, message);
         for (const listener of Array.from(subscription.listeners))
             listener(outgoing);
+        if (message.type === "sync.snapshot") {
+            const settled = this.overlay.acknowledgeMatching(subscription.key, subscription.entity, message.result, message.key);
+            for (const mutationId of settled)
+                void this.ackOptimisticMutation(mutationId);
+        }
     }
     materializeSyncMessage(subscription, message) {
         if (message.type !== "sync.snapshot")
             return message;
         return {
             ...message,
-            result: this.overlay.apply(subscription.path, message.result, message.key),
+            result: this.overlay.apply(subscription.key, subscription.entity, message.result, message.key),
         };
     }
-    emitOptimisticCollection(collection) {
+    materializeQueryMessage(subscription, message) {
+        const projection = subscription.projection;
+        if (!projection || message.type !== "query.result")
+            return message;
+        const projected = rowsAtPath(message.result, projection.resultPath);
+        if (!projected)
+            return message;
+        const materialized = this.overlay.apply(subscription.key, projection.entity, projected.rows, projection.key);
+        return {
+            ...message,
+            result: replaceRowsAtPath(message.result, projection.resultPath, materialized, projected.scalar),
+        };
+    }
+    emitOptimisticEntity(entity) {
         for (const subscription of this.syncSubscriptions.values()) {
-            if (subscription.path !== collection || subscription.lastMessage?.type !== "sync.snapshot")
+            if (subscription.entity !== entity)
+                continue;
+            this.overlay.expectSource(subscription.key, entity);
+            if (subscription.lastMessage?.type !== "sync.snapshot")
                 continue;
             this.emitSyncMessage(subscription, subscription.lastMessage);
         }
+        for (const subscription of this.querySubscriptions.values()) {
+            if (subscription.projection?.entity !== entity)
+                continue;
+            this.overlay.expectSource(subscription.key, entity);
+            if (subscription.lastMessage?.type !== "query.result")
+                continue;
+            const outgoing = this.materializeQueryMessage(subscription, subscription.lastMessage);
+            for (const listener of Array.from(subscription.listeners))
+                listener(outgoing);
+            this.acknowledgeOptimisticQuerySnapshot(subscription, subscription.lastMessage.result);
+        }
+    }
+    acknowledgeOptimisticSource(source, mutationIds) {
+        const settled = this.overlay.acknowledge(source, mutationIds);
+        for (const mutationId of settled)
+            void this.ackOptimisticMutation(mutationId);
+    }
+    acknowledgeOptimisticQuerySnapshot(subscription, result) {
+        const projection = subscription.projection;
+        if (!projection)
+            return;
+        const projected = rowsAtPath(result, projection.resultPath);
+        if (!projected)
+            return;
+        const settled = this.overlay.acknowledgeMatching(subscription.key, projection.entity, projected.rows, projection.key);
+        for (const mutationId of settled)
+            void this.ackOptimisticMutation(mutationId);
     }
     markSyncSubscriptionsOutOfDate() {
         for (const subscription of this.syncSubscriptions.values()) {
@@ -1146,6 +1248,7 @@ export class GonvexClient {
                 // the ready that follows this resume must not rewrite them.
                 subscription.persistedRows = cached.rows;
                 subscription.cursor = cached.cursor;
+                raiseSyncCursorFloor(subscription, cached.cursor);
                 subscription.keyField = cached.keyField;
                 subscription.mode = cached.mode;
                 subscription.truncated = cached.truncated;
@@ -1281,6 +1384,8 @@ export class GonvexClient {
             this.clearSyncRetry(latest);
             this.pendingSyncOpens.delete(latest);
             this.syncSubscriptions.delete(key);
+            for (const mutationId of this.overlay.removeSource(key))
+                void this.ackOptimisticMutation(mutationId);
             this.handlers.delete(latest.id);
             this.send({ type: "sync.close", id: latest.id });
         }, this.syncSubscriptionRetentionMs);
@@ -1343,12 +1448,40 @@ export class GonvexClient {
         subscription.persistedRows = subscription.rows;
         this.enqueueSyncPersistence(subscription, scope, () => store.applyDelta(scope, subscription.path, subscription.args, value));
     }
-    async restoreOutbox() {
-        const entries = await this.mutationOutbox.loadAll();
-        if (this.manuallyClosed)
+    activateOutboxScope() {
+        const scope = mutationOutboxScope(this.url, this.auth, this.outboxEphemeralScope);
+        if (scope === this.outboxScope)
+            return this.outboxReady ?? Promise.resolve();
+        const previousScope = this.outboxScope;
+        const generation = ++this.outboxScopeGeneration;
+        // Pending state from the previous authenticated identity must disappear
+        // from every live projection immediately. Its durable rows remain scoped
+        // in IndexedDB and can be resumed only if that identity returns.
+        for (const mutationId of this.optimisticMutationIds)
+            this.overlay.reject(mutationId);
+        this.optimisticMutationIds.clear();
+        this.optimisticOutboxEntryIds.clear();
+        if (isEphemeralOutboxScope(previousScope)) {
+            void this.mutationOutbox.clear(previousScope);
+        }
+        this.outboxScope = scope;
+        const ready = this.restoreOutbox(scope, generation);
+        this.outboxReady = ready;
+        return ready;
+    }
+    async restoreOutbox(scope, generation) {
+        const entries = await this.mutationOutbox.loadAll(scope);
+        if (this.manuallyClosed
+            || generation !== this.outboxScopeGeneration
+            || scope !== this.outboxScope)
             return;
         for (const entry of entries) {
-            this.addOptimisticMutation(entry.idempotencyKey, entry.patches ?? []);
+            if (entry.state === "committed" && (entry.patches?.length ?? 0) === 0) {
+                await this.mutationOutbox.ack(entry.id);
+                continue;
+            }
+            this.optimisticOutboxEntryIds.set(entry.idempotencyKey, entry.id);
+            this.addOptimisticMutation(entry.idempotencyKey, entry.patches ?? [], entry.state === "committed");
         }
         const nextAttemptAt = Math.min(...entries
             .filter((entry) => entry.state === "pending")
@@ -1356,20 +1489,31 @@ export class GonvexClient {
         if (Number.isFinite(nextAttemptAt) && nextAttemptAt > Date.now()) {
             this.scheduleOutboxDrain(nextAttemptAt - Date.now());
         }
+        // If this scope was installed after the socket authenticated, no reconnect
+        // or new enqueue may occur to wake the queue. The await inside drainOutbox
+        // yields until this restore promise resolves, then safely resumes it.
+        void this.drainOutbox();
     }
-    addOptimisticMutation(mutationId, patches) {
+    addOptimisticMutation(mutationId, patches, accepted = false) {
         if (patches.length === 0 || this.optimisticMutationIds.has(mutationId))
             return;
         this.optimisticMutationIds.add(mutationId);
-        this.overlay.add(mutationId, patches);
+        this.overlay.add(mutationId, patches, { accepted });
     }
-    settleOptimisticMutation(mutationId) {
-        this.optimisticMutationIds.delete(mutationId);
-        this.overlay.settle(mutationId);
+    async settleOptimisticMutation(mutationId) {
+        await Promise.all(this.overlay.accept(mutationId).map((settledId) => this.ackOptimisticMutation(settledId)));
     }
-    rejectOptimisticMutation(mutationId) {
+    async rejectOptimisticMutation(mutationId, knownEntryId) {
         this.optimisticMutationIds.delete(mutationId);
         this.overlay.reject(mutationId);
+        await this.ackOptimisticMutation(mutationId, knownEntryId);
+    }
+    async ackOptimisticMutation(mutationId, knownEntryId) {
+        const entryId = knownEntryId ?? this.optimisticOutboxEntryIds.get(mutationId);
+        this.optimisticOutboxEntryIds.delete(mutationId);
+        this.optimisticMutationIds.delete(mutationId);
+        if (entryId !== undefined)
+            await this.mutationOutbox.ack(entryId);
     }
     async drainOutbox() {
         await this.outboxReady;
@@ -1378,22 +1522,32 @@ export class GonvexClient {
             || !this.socket
             || this.socket.readyState !== WebSocket.OPEN)
             return;
+        const drainScope = this.outboxScope;
         this.drainingOutbox = true;
         try {
             while (!this.manuallyClosed && this.socket?.readyState === WebSocket.OPEN) {
-                const entry = await this.mutationOutbox.nextReady(Date.now());
+                const scope = this.outboxScope;
+                const entry = await this.mutationOutbox.nextReady(scope, Date.now());
                 if (!entry)
                     return;
+                if (scope !== this.outboxScope)
+                    return;
                 await this.mutationOutbox.markInflight(entry.id);
+                if (scope !== this.outboxScope)
+                    return;
                 try {
-                    await this.call("mutation", { kind: "mutation", path: entry.path }, entry.args, this.timeouts.mutationTimeoutMs, entry.idempotencyKey);
-                    await this.mutationOutbox.ack(entry.id);
-                    this.settleOptimisticMutation(entry.idempotencyKey);
+                    await this.call("mutation", { kind: "mutation", path: entry.path }, entry.args, this.timeouts.mutationTimeoutMs, entry.idempotencyKey, entry.idempotencyKey);
+                    await this.mutationOutbox.markCommitted(entry.id);
+                    if ((entry.patches?.length ?? 0) > 0) {
+                        await this.settleOptimisticMutation(entry.idempotencyKey);
+                    }
+                    else {
+                        await this.ackOptimisticMutation(entry.idempotencyKey, entry.id);
+                    }
                 }
                 catch (error) {
                     if (error instanceof GonvexClientError && error.code === "server") {
-                        await this.mutationOutbox.ack(entry.id);
-                        this.rejectOptimisticMutation(entry.idempotencyKey);
+                        await this.rejectOptimisticMutation(entry.idempotencyKey, entry.id);
                         continue;
                     }
                     await this.mutationOutbox.fail(entry.id, mutationErrorMessage(error));
@@ -1404,6 +1558,9 @@ export class GonvexClient {
         }
         finally {
             this.drainingOutbox = false;
+            if (!this.manuallyClosed && drainScope !== this.outboxScope) {
+                void this.drainOutbox();
+            }
         }
     }
     scheduleOutboxDrain(delay) {
@@ -1418,25 +1575,63 @@ export class GonvexClient {
     }
     mutation(ref, args = {}, options = {}) {
         const mutationId = randomID();
-        const patches = options.optimistic ?? [];
+        const patches = options.optimistic
+            ?? optimisticPatchesFromReference(ref.optimistic?.mutation, args);
+        if (patches.length === 0 && options.offline !== "queue") {
+            return this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs, mutationId);
+        }
+        return this.runOptimisticMutation(ref, args, options, mutationId, patches);
+    }
+    async runOptimisticMutation(ref, args, options, mutationId, patches) {
+        // The startup recovery transaction converts abandoned inflight entries to
+        // pending. Finish it before inserting a brand-new direct send, otherwise
+        // recovery can mistake that live entry for a crashed mutation and race the
+        // direct call through the background drain.
+        await this.outboxReady;
+        if (this.manuallyClosed) {
+            throw new GonvexClientError(`Gonvex client was closed before mutation ${ref.path} could be sent.`, { code: "closed", path: ref.path, operation: "mutation" });
+        }
+        const scope = this.outboxScope;
+        const entry = await this.mutationOutbox.enqueue({
+            scope,
+            path: ref.path,
+            args,
+            idempotencyKey: mutationId,
+            entityKeys: patches.map((patch) => `${patch.entity ?? patch.collection ?? ""}:${patch.rowId}`),
+            patches,
+            state: "inflight",
+        });
+        if (this.manuallyClosed) {
+            await this.mutationOutbox.ack(entry.id);
+            throw new GonvexClientError(`Gonvex client was closed before mutation ${ref.path} could be sent.`, { code: "closed", path: ref.path, operation: "mutation" });
+        }
+        if (scope !== this.outboxScope) {
+            await this.mutationOutbox.ack(entry.id);
+            throw new GonvexClientError(`Authentication changed before mutation ${ref.path} could be sent.`, { code: "disconnected", path: ref.path, operation: "mutation" });
+        }
+        this.optimisticOutboxEntryIds.set(mutationId, entry.id);
         this.addOptimisticMutation(mutationId, patches);
-        return this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs, mutationId).then((result) => {
-            this.settleOptimisticMutation(mutationId);
+        try {
+            // The direct send is outbox-managed: a crash here replays the entry
+            // with the same idempotency key, so the server must dedupe it.
+            const result = await this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs, mutationId, mutationId);
+            await this.mutationOutbox.markCommitted(entry.id);
+            if (patches.length > 0) {
+                await this.settleOptimisticMutation(mutationId);
+            }
+            else {
+                await this.ackOptimisticMutation(mutationId, entry.id);
+            }
             return result;
-        }).catch(async (error) => {
+        }
+        catch (error) {
             if (isQueueableMutationError(error) && options.offline === "queue") {
-                await this.mutationOutbox.enqueue({
-                    path: ref.path,
-                    args,
-                    idempotencyKey: mutationId,
-                    entityKeys: patches.map((patch) => patch.rowId),
-                    patches,
-                });
+                await this.mutationOutbox.fail(entry.id, mutationErrorMessage(error));
                 return { status: "queued", mutationId };
             }
-            this.rejectOptimisticMutation(mutationId);
+            await this.rejectOptimisticMutation(mutationId, entry.id);
             throw error;
-        });
+        }
     }
     action(ref, args = {}, options = {}) {
         return this.call("action", ref, args, options.timeoutMs ?? this.timeouts.actionTimeoutMs);
@@ -1513,8 +1708,9 @@ export class GonvexClient {
      * 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.
+     * outcomes. Falls back to the standard per-mutation path when the runtime
+     * lacks batching or when a call needs generated/explicit optimism or durable
+     * offline queuing, so there is never a second mutation-state implementation.
      */
     async mutationMany(calls, options = {}) {
         if (calls.length === 0)
@@ -1529,7 +1725,10 @@ export class GonvexClient {
                 ? error
                 : new GonvexClientError(String(error), { code: "server", path, operation: "mutation" }),
         }));
-        if (this.serverCapabilities.mutationBatch !== 1) {
+        const requiresStandardMutationPath = options.offline === "queue"
+            || options.optimistic !== undefined
+            || calls.some((call) => call.ref.optimistic?.mutation !== undefined);
+        if (this.serverCapabilities.mutationBatch !== 1 || requiresStandardMutationPath) {
             const outcomes = [];
             for (const call of calls) {
                 outcomes.push(await settle(this.mutation(call.ref, call.args ?? {}, options), call.ref.path));
@@ -1554,7 +1753,7 @@ export class GonvexClient {
         this.notifyConnectionState();
         return Promise.all(registered.map((entry) => settle(entry.promise, entry.path)));
     }
-    call(kind, ref, args, timeoutMs, id) {
+    call(kind, ref, args, timeoutMs, id, idempotencyKey) {
         this.connect();
         const entry = this.registerCall(kind, ref, args, timeoutMs, id);
         if (kind === "mutation") {
@@ -1564,7 +1763,14 @@ export class GonvexClient {
                     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 } });
+            this.send({
+                type: "mutation.call",
+                id: entry.id,
+                path: ref.path,
+                args,
+                trace: { clientSentAtMs: entry.clientSentAtMs },
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+            });
         }
         else {
             this.send({ type: "action.call", id: entry.id, path: ref.path, args, trace: { clientSentAtMs: entry.clientSentAtMs } });
@@ -1632,6 +1838,8 @@ export class GonvexClient {
             if (!latest || latest.listeners.size > 0)
                 return;
             this.querySubscriptions.delete(key);
+            for (const mutationId of this.overlay.removeSource(key))
+                void this.ackOptimisticMutation(mutationId);
             this.send({ type: "query.unsubscribe", id: latest.id });
             setTimeout(() => this.handlers.delete(latest.id), 500);
         }, this.querySubscriptionRetentionMs);
@@ -1886,6 +2094,8 @@ export class GonvexClient {
             subscription.integrityEpoch = undefined;
             subscription.forceFullIntegrity = false;
             subscription.cursor = undefined;
+            subscription.cursorFloor = undefined;
+            subscription.retiredEpochs.clear();
             subscription.lastMessage = undefined;
             subscription.cacheReadGeneration = undefined;
             subscription.opening = false;
@@ -1923,9 +2133,11 @@ export class GonvexClient {
                 cacheRevision: cached.revision,
             };
             subscription.lastMessage = message;
+            const outgoing = this.materializeQueryMessage(subscription, message);
             for (const listener of Array.from(subscription.listeners)) {
-                listener(message);
+                listener(outgoing);
             }
+            this.acknowledgeOptimisticQuerySnapshot(subscription, message.result);
         }).catch(() => {
             // Persistent cache failures never affect the server query path.
         }).finally(() => {
@@ -2181,6 +2393,28 @@ export class GonvexClient {
         }
     }
 }
+function rowsAtPath(result, path) {
+    let current = result;
+    for (const segment of path) {
+        if (!isJsonRecord(current))
+            return undefined;
+        current = current[segment];
+    }
+    if (Array.isArray(current))
+        return { rows: current, scalar: false };
+    if (isJsonRecord(current))
+        return { rows: [current], scalar: true };
+    return undefined;
+}
+function replaceRowsAtPath(result, path, rows, scalar) {
+    if (path.length === 0)
+        return scalar ? (rows[0] ?? null) : rows;
+    if (!isJsonRecord(result))
+        return result;
+    const [head, ...tail] = path;
+    const current = result[head];
+    return { ...result, [head]: replaceRowsAtPath(current ?? null, tail, rows, scalar) };
+}
 function querySubscriptionKey(ref, args) {
     return `${ref.path}\u0000${stableStringify(args)}`;
 }
@@ -2415,6 +2649,25 @@ function sameAuthTokenIdentity(left, right) {
     const rightIdentity = authIdentityKey(right);
     return leftIdentity !== "" && leftIdentity === rightIdentity;
 }
+function mutationOutboxScope(url, auth, ephemeralScope) {
+    const identity = authIdentityKey(auth);
+    if (identity)
+        return ["identity", url, identity].join("\u0000");
+    if (auth.token || auth.identity || auth.fetchToken) {
+        // Opaque tokens (or credentials installed before tenant selection) do not
+        // expose a stable user key. A per-client scope preserves current-session
+        // queue semantics without ever restoring those rows under another user.
+        return ["ephemeral-auth", url, ephemeralScope].join("\u0000");
+    }
+    // Anonymous/dev-auth clients still need a stable namespace, but it must be
+    // isolated by deployment and tenant. Once an authenticated identity is
+    // installed, applyAuth switches away from this scope before restoring or
+    // sending its durable mutations.
+    return ["anonymous", url, auth.project ?? "", auth.tenant ?? ""].join("\u0000");
+}
+function isEphemeralOutboxScope(scope) {
+    return scope.startsWith("ephemeral-auth\u0000");
+}
 function queryCacheDirectiveFromAuthResult(result) {
     if (!isJsonRecord(result))
         return undefined;