@gonvex/client 0.5.2-staging.13 → 0.5.2-staging.14

package/dist/index.js

@@ -1,10 +1,11 @@
-import { replicaHashesDigest, replicaRowsHashes } from "./replica-integrity.js";
+import { readIsCovered, primaryReadKeys } from "@gonvex/local-runtime/read-view";
+import { applyReplicaHashDelta, replicaHashesDigest, replicaRowsHashes } from "./replica-integrity.js";
 import { GonvexErrorReporter } from "./error-reporter.js";
 export { GonvexErrorReporter } from "./error-reporter.js";
 import { optimisticPatchesFromReference, } from "./optimistic.js";
 import { createReducerOutbox, } from "./outbox.js";
 import { LocalReplica, } from "./local-replica.js";
-import { runOfflineLiveQuery } from "./query-expression.js";
+import { runOfflineLiveQuery, liveScopeCoverage } from "./query-expression.js";
 export * from "./error-reporter.js";
 export * from "./optimistic.js";
 export * from "./outbox.js";
@@ -12,6 +13,8 @@ export * from "./kv-stores.js";
 export * from "./client-upgrades.js";
 export * from "./browser-upgrades.js";
 export * from "./signals.js";
+export * from "./paged-read-view.js";
+export { mergeReplicaRecord } from './replica-record.js';
 export * from "./external-auth.js";
 // Keep the mutable LocalReplica implementation private to GonvexClient. The
 // public package exposes only the read-only view plus storage/value types.
@@ -41,6 +44,7 @@ function createLocalReplicaView(replica) {
         cursor: () => replica.cursor(),
         freshness: () => replica.freshness(),
         version: () => replica.version(),
+        entityVersion: (entity, id) => replica.entityVersion(entity, id),
         subscribe: (listener) => replica.subscribe(listener),
         hasPendingCommand: (commandId) => replica.hasPendingCommand(commandId),
         getWindow: (signature) => replica.getWindow(signature),
@@ -51,6 +55,7 @@ function createLocalReplicaView(replica) {
         entityRows: (entity) => replica.entityRows(entity),
         entityCompleteness: (entity) => replica.entityCompleteness(entity),
         liveQuery: (signature) => replica.liveQuery(signature),
+        liveQuerySnapshot: (signature) => replica.liveQuerySnapshot(signature),
         collectionState: (signature) => replica.collectionState(signature),
         hasLiveQuery: (signature) => replica.hasLiveQuery(signature),
         snapshot: () => replica.snapshot(),
@@ -117,20 +122,26 @@ const maxReplicaBatchOpens = 256;
 // normally settle in a few milliseconds.
 export class GonvexClient {
     url;
+    localTableBindings = new Map();
     localBinding;
     localExecutor;
     localStorage;
     localIdentity;
     localLane = Promise.resolve();
+    preparationLane = Promise.resolve();
     localReplayScheduled = false;
+    waitingLocalEdits = 0;
     replacingLocal = false;
     unsubscribeLocal;
     localCollectionClosers = [];
+    localCollectionKeys = new Set();
+    localExecutionTables = new Map();
     reducerRejectionHandlers = new Set();
     socket;
     handlers = new Map();
     querySubscriptions = new Map();
     replicaSubscriptions = new Map();
+    replicaMetadataListeners = new WeakSet();
     oneShotQueries = new Map();
     telemetryHandlers = new Set();
     pendingMessages = [];
@@ -179,6 +190,11 @@ export class GonvexClient {
     processedReplicaWatermarkRevision = 0;
     pendingReplicaTransactions = [];
     unsubscribeOutbox;
+    sharedOutboxStore;
+    unsubscribePeerOutbox;
+    unsubscribePeerReplica;
+    peerRefreshScheduled = false;
+    peerRefreshDirty = false;
     unsubscribeBrowserOnline;
     drainingOutbox = false;
     outboxDrainTimer;
@@ -206,17 +222,37 @@ export class GonvexClient {
         this.clientContract = options.clientContract ?? options.localRuntime?.clientContract;
         this.updateRequiredHandler = options.onUpdateRequired;
         this.localBinding = options.localRuntime;
-        this.localExecutor = options.localRuntime?.create();
+        for (const table of this.localBinding?.tables ?? []) {
+            const references = (this.localBinding?.collections ?? []).filter(ref => ref.replica?.table === table
+                && !Object.keys(ref.replica.equalFilters ?? {}).length && !(ref.replica.excludeWhenSet?.length));
+            this.localTableBindings.set(table, { signatures: references.map(ref => querySubscriptionKey(ref, {})),
+                columns: [...new Set(references.flatMap(ref => ref.replica?.columns ?? []))] });
+        }
+        this.localExecutor = options.localRuntime ? deferredLocalExecutor(() => options.localRuntime.create()) : undefined;
         this.localStorage = options.localReplica?.storage;
         this.auth = authFromOptions(options);
         this.telemetryEnabled = options.telemetry === true;
         this.querySubscriptionRetentionMs = normalizeQuerySubscriptionRetentionMs(options.querySubscriptionRetentionMs);
         this.replicaSubscriptionRetentionMs = normalizeQuerySubscriptionRetentionMs(options.replicaSubscriptionRetentionMs);
+        this.sharedOutboxStore = options.outbox?.store?.shared ? options.outbox.store : undefined;
         this.reducerOutbox = createReducerOutbox(options.outbox);
-        this.replica = new LocalReplica(options.localReplica?.storage);
+        this.replica = new LocalReplica(options.localReplica?.storage, { maxResidentRows: options.localReplica?.maxResidentRows, maxResidentBytes: options.localReplica?.maxResidentBytes });
         this.replicaView = createLocalReplicaView(this.replica);
-        if (this.localExecutor)
-            this.unsubscribeLocal = this.replica.subscribe(() => this.scheduleLocalReplay());
+        if (this.localExecutor) {
+            let executionVersion = this.replica.executionVersion();
+            this.unsubscribeLocal = this.replica.subscribe(() => {
+                const next = this.replica.executionVersion();
+                if (next === executionVersion)
+                    return;
+                executionVersion = next;
+                this.scheduleLocalReplay();
+            });
+        }
+        this.unsubscribePeerOutbox = this.sharedOutboxStore?.subscribePeer?.(() => this.refreshPeerOutbox());
+        this.unsubscribePeerReplica = this.localStorage?.subscribePeer?.(scope => {
+            if (scope === this.replicaScope)
+                this.refreshPeerOutbox();
+        });
         this.unsubscribeOutbox = this.reducerOutbox.subscribe(() => {
             void this.drainOutbox();
         });
@@ -269,38 +305,162 @@ export class GonvexClient {
             return;
         this.lastOnlineAtMs = saved.lastOnlineAtMs ?? 0;
         this.localIdentity = saved.identity;
+        void this.localExecutor?.ready.catch(() => undefined);
         await this.activateReplicaDirective(saved.directive);
         this.replica.setFreshness("offline");
     }
-    ensureLocalCollections() {
-        if (!this.localBinding || this.localCollectionClosers.length)
+    ensureLocalCollections(tables) {
+        if (!this.localBinding)
             return;
+        const needed = new Set(tables);
         for (const reference of this.localBinding.collections ?? []) {
-            this.localCollectionClosers.push(this.subscribeReplicaTransport(reference, {}, () => undefined));
+            if (!reference.replica || !needed.has(reference.replica.table))
+                continue;
+            const key = querySubscriptionKey(reference, {});
+            if (this.localCollectionKeys.has(key))
+                continue;
+            this.localCollectionKeys.add(key);
+            this.localCollectionClosers.push(this.subscribeReplicaTransport(reference, {}, () => undefined, true));
         }
     }
+    hydrateMissingLocalTable(error) {
+        if (!(error instanceof Error) || error.name !== "IncompleteReplicaError")
+            return;
+        // Worker errors preserve the public runtime name/message contract.
+        const table = /^Local replica for (.+?) is incomplete;/.exec(error.message)?.[1];
+        if (table)
+            this.ensureLocalCollections([table]);
+    }
     localSnapshot(includePending) {
-        const snapshot = this.replica.snapshot();
+        const rows = this.replica.captureExecutionRows(includePending);
         const tables = {};
-        for (const table of this.localBinding?.tables ?? []) {
-            const references = (this.localBinding?.collections ?? []).filter((ref) => ref.replica?.table === table
-                && !Object.keys(ref.replica.equalFilters ?? {}).length && !(ref.replica.excludeWhenSet?.length));
-            const complete = references.some((ref) => {
-                const window = snapshot.liveQueries[querySubscriptionKey(ref, {})];
-                return window?.completeness === "complete" && window.truncated !== true;
-            });
-            tables[table] = { complete, columns: [...new Set(references.flatMap(ref => ref.replica?.columns ?? []))], rows: includePending ? this.replica.entityRows(table) : Object.values(snapshot.entities[table] ?? {}) };
+        for (const [table, binding] of this.localTableBindings) {
+            const complete = binding.signatures.some(signature => this.replica.windowIsComplete(signature));
+            tables[table] = { complete, columns: binding.columns, get rows() { return rows(table); } };
         }
         return { scope: this.replicaScope, tables };
     }
+    localReadCoverage() {
+        return this.replica.captureReadCoverage(Object.fromEntries([...this.localTableBindings].map(([table, binding]) => [table, {
+                key: this.localBinding.collections?.find(ref => ref.replica?.table === table)?.replica?.key ?? '_id',
+                complete: binding.signatures.some(signature => this.replica.windowIsComplete(signature)), columns: binding.columns,
+            }])));
+    }
+    isUncoveredLocalRead(error) {
+        if (!(error instanceof Error) || error.name !== 'IncompleteReplicaError')
+            return false;
+        const read = error.read;
+        if (!read || read.limit === 0)
+            return false;
+        const known = this.localReadCoverage()[read.table];
+        // Disk can recover evicted primary keys or a complete registered slice.
+        // It cannot prove a scan over data that has never been delivered. Queue
+        // that intent for replay instead of waiting for unrelated cache writes.
+        return !readIsCovered(known, read) && primaryReadKeys(read, known?.key ?? '_id') === undefined;
+    }
+    async executeLocal(path, args, snapshot, execution, pending = true, residentOnly = false) {
+        if (this.localBinding?.mode === 'portable') {
+            try {
+                const run = (source) => this.localExecutor.executeRead(path, args, source, execution);
+                let transaction;
+                try {
+                    transaction = await this.replica.withReadView(() => this.localReadCoverage(), pending, run, true);
+                }
+                catch (error) {
+                    if (residentOnly || !(error instanceof Error) || error.name !== 'IncompleteReplicaError' || this.isUncoveredLocalRead(error))
+                        throw error;
+                    transaction = await this.replica.withReadView(() => this.localReadCoverage(), pending, run);
+                }
+                // The read view already proved every read from the available replica
+                // windows or cached primary keys. Do not promote those bounded reads
+                // to whole-table subscriptions after a successful user edit. Missing
+                // coverage still opens its generated collection in the error path.
+                return transaction;
+            }
+            catch (error) {
+                // A speculative memory-only read may simply need IndexedDB. Its
+                // coordinated retry checks disk before deciding to request more data.
+                if (!residentOnly)
+                    this.hydrateMissingLocalTable(error);
+                throw error;
+            }
+        }
+        if (!snapshot)
+            throw new Error('Legacy local executor requires a snapshot');
+        const known = this.localExecutionTables.get(path);
+        const input = known ? { ...snapshot, tables: Object.fromEntries(Object.entries(snapshot.tables).filter(([table]) => known.has(table))) } : snapshot;
+        let transaction;
+        try {
+            transaction = await this.localExecutor.execute(path, args, input, execution);
+        }
+        catch (error) {
+            this.hydrateMissingLocalTable(error);
+            if (!known || !(error instanceof Error) || error.name !== "IncompleteReplicaError")
+                throw error;
+            // A different argument, tenant or workflow can read different tables.
+            // Retry against the SAME captured snapshot, never newer mixed-version rows.
+            try {
+                transaction = await this.localExecutor.execute(path, args, snapshot, execution);
+            }
+            catch (retryError) {
+                this.hydrateMissingLocalTable(retryError);
+                throw retryError;
+            }
+        }
+        this.ensureLocalCollections(transaction.readTables);
+        this.localExecutionTables.set(path, new Set([
+            ...(known ?? []), ...transaction.readTables, ...transaction.patches.map(patch => patch.entity),
+        ]));
+        return transaction;
+    }
     inLocalLane(run) {
         const job = this.localLane.then(run);
         this.localLane = job.catch(() => undefined);
         return job;
     }
+    replaceLocalPredictions(commands) {
+        this.replica.replaceOptimistic(commands);
+    }
+    coordinateOutbox(lane, run) {
+        return this.sharedOutboxStore?.coordinate?.(this.outboxScope, lane, run) ?? run();
+    }
+    refreshPeerOutbox() {
+        if (this.manuallyClosed)
+            return;
+        this.peerRefreshDirty = true;
+        if (this.peerRefreshScheduled)
+            return;
+        this.peerRefreshScheduled = true;
+        void (async () => {
+            await this.outboxReady;
+            do {
+                this.peerRefreshDirty = false;
+                await this.inLocalLane(() => this.coordinateOutbox("intent", async () => {
+                    const scope = this.outboxScope;
+                    await this.replica.synchronizeStorage();
+                    const entries = await this.reducerOutbox.list(scope);
+                    if (this.manuallyClosed || scope !== this.outboxScope)
+                        return;
+                    this.replaceLocalPredictions(entries.filter(entry => entry.state !== "committed").map(entry => ({ commandId: entry.idempotencyKey, patches: entry.patches ?? [] })));
+                    this.optimisticReducerIds.clear();
+                    this.optimisticOutboxEntryIds.clear();
+                    for (const entry of entries) {
+                        this.optimisticOutboxEntryIds.set(entry.idempotencyKey, entry.id);
+                        if (entry.patches?.length)
+                            this.optimisticReducerIds.add(entry.idempotencyKey);
+                    }
+                }));
+            } while (this.peerRefreshDirty && !this.manuallyClosed);
+            void this.drainOutbox();
+        })().catch(() => undefined).finally(() => { this.peerRefreshScheduled = false; });
+    }
     scheduleLocalReplay() {
         if (!this.localExecutor || this.replacingLocal || this.localReplayScheduled || this.manuallyClosed || !this.localIdentity)
             return;
+        // Restore and peer notifications discover durable intents explicitly. A
+        // table arriving at startup cannot invalidate a prediction that does not exist.
+        if (this.optimisticOutboxEntryIds.size === 0)
+            return;
         this.localReplayScheduled = true;
         queueMicrotask(() => {
             void (async () => {
@@ -314,21 +474,52 @@ export class GonvexClient {
         for (const listener of this.reducerRejectionHandlers)
             listener({ reducerId, path, error: message });
     }
-    async rebaseLocalEntries() {
+    rebaseLocalEntries(afterRejection = false) {
+        return this.coordinateOutbox("intent", () => this.rebaseLocalEntriesLocked(afterRejection));
+    }
+    async rebaseLocalEntriesLocked(afterRejection = false) {
         if (!this.localExecutor || !this.localBinding || !this.localIdentity || !this.hasAuthoritativeReplicaScope)
             return;
+        // The authoritative drain validates the pending chain in order. Keep its
+        // predictions while it progresses, then rebase once it settles or loses
+        // connectivity instead of replaying N + (N-1) + ... local transactions.
+        if (!afterRejection && this.drainingOutbox && this.canSendReducerNow())
+            return;
+        await this.replica.synchronizeStorage();
         const scope = this.outboxScope;
         const replicaScope = this.replicaScope;
         const entries = await this.reducerOutbox.list(scope);
-        const baseVersion = this.replica.version();
-        const snapshot = this.localSnapshot(false);
+        if (scope !== this.outboxScope || replicaScope !== this.replicaScope)
+            return;
+        if (entries.length === 0) {
+            this.replacingLocal = true;
+            try {
+                this.replaceLocalPredictions([]);
+            }
+            finally {
+                this.replacingLocal = false;
+            }
+            this.optimisticReducerIds.clear();
+            this.optimisticOutboxEntryIds.clear();
+            return;
+        }
+        const baseVersion = this.replica.executionVersion();
+        const needsExecution = entries.some(entry => entry.localExecution && entry.state !== "inflight" && entry.state !== "committed");
+        const snapshot = needsExecution && this.localBinding.mode !== 'portable' ? this.localSnapshot(false) : undefined;
+        const replayPatches = [];
         const commands = [];
         for (const entry of entries) {
+            // Predictions can wait; a fresh user intent must not sit behind the
+            // entire durable backlog. Publish only a complete, coherent rebase.
+            if (this.waitingLocalEdits > 0) {
+                setTimeout(() => this.scheduleLocalReplay(), 0);
+                return;
+            }
             let patches = entry.patches ?? [];
             if (entry.localExecution && entry.state !== "inflight" && entry.state !== "committed") {
                 const execution = { ...entry.localExecution, scope: replicaScope, identity: this.localIdentity, artifactHash: this.localBinding.artifactHash };
                 try {
-                    const transaction = await this.localExecutor.execute(entry.path, entry.args, snapshot, execution);
+                    const transaction = await this.executeLocal(entry.path, entry.args, snapshot, execution, replayPatches);
                     patches = transaction.patches;
                     if (scope !== this.outboxScope || replicaScope !== this.replicaScope)
                         return;
@@ -344,16 +535,25 @@ export class GonvexClient {
                 // Storage failures must abort rebasing, never masquerade as rejection.
                 await this.reducerOutbox.updateLocal(entry.id, patches, execution);
             }
-            applyLocalPatches(snapshot, patches);
+            if (snapshot)
+                applyLocalPatches(snapshot, patches);
+            for (const patch of patches)
+                replayPatches.push(patch.op === 'delete'
+                    ? { entity: patch.entity ?? patch.collection, rowId: patch.rowId, op: 'delete' }
+                    : { entity: patch.entity ?? patch.collection, rowId: patch.rowId, op: patch.op === 'upsert' ? 'insert' : patch.op, fields: patch.fields });
             commands.push({ commandId: entry.idempotencyKey, patches });
         }
         if (scope !== this.outboxScope || replicaScope !== this.replicaScope)
             return;
-        if (baseVersion !== this.replica.version())
-            return this.rebaseLocalEntries();
+        if (baseVersion !== this.replica.executionVersion()) {
+            // A changing server base must not recursively occupy the local lane.
+            // Release it so user intents already queued can run before the retry.
+            setTimeout(() => this.scheduleLocalReplay(), 0);
+            return;
+        }
         this.replacingLocal = true;
         try {
-            this.replica.replaceOptimistic(commands);
+            this.replaceLocalPredictions(commands);
         }
         finally {
             this.replacingLocal = false;
@@ -362,9 +562,10 @@ export class GonvexClient {
         this.optimisticOutboxEntryIds.clear();
         for (const entry of entries) {
             this.optimisticOutboxEntryIds.set(entry.idempotencyKey, entry.id);
-            if (commands.find((command) => command.commandId === entry.idempotencyKey)?.patches.length)
-                this.optimisticReducerIds.add(entry.idempotencyKey);
         }
+        for (const command of commands)
+            if (command.patches.length)
+                this.optimisticReducerIds.add(command.commandId);
     }
     async runLocalReducer(ref, args) {
         args = structuredClone(args);
@@ -373,7 +574,38 @@ export class GonvexClient {
         await this.replicaReady;
         if (!this.localExecutor || !this.localBinding)
             throw new Error("This reducer requires the generated Gonvex client with local execution enabled");
-        return this.inLocalLane(async () => {
+        const reducerId = randomID();
+        const execution = this.localIdentity ? {
+            scope: this.replicaScope, commandId: reducerId, now: Date.now(),
+            intentEntropy: Array.from(crypto.getRandomValues(new Uint8Array(32)), byte => byte.toString(16).padStart(2, '0')).join(''),
+            artifactHash: this.localBinding.artifactHash, identity: structuredClone(this.localIdentity),
+        } : undefined;
+        let preparedResult;
+        let preparedFailure;
+        const prepared = this.preparationLane.then(async () => {
+            if (!execution || this.localBinding?.mode !== 'portable' || !this.hasAuthoritativeReplicaScope || this.manuallyClosed || this.updateRequired || admittedGeneration !== this.outboxScopeGeneration)
+                return;
+            if (this.clientContract && this.clientContract.offlineMaxAgeMs !== null && !this.canSendReducerNow() && (Date.now() - this.lastOnlineAtMs > this.clientContract.offlineMaxAgeMs || Date.now() < this.lastOnlineAtMs))
+                return;
+            const base = this.replica.executionVersion();
+            const pending = this.replica.pendingReducerPatches();
+            try {
+                const transaction = await this.executeLocal(ref.path, args, undefined, execution, pending, true);
+                if (base !== this.replica.executionVersion() || admittedGeneration !== this.outboxScopeGeneration || this.manuallyClosed)
+                    return;
+                preparedResult = { transaction, base, pending: JSON.stringify(pending) };
+            }
+            catch (error) {
+                preparedFailure = error; /* Recheck coverage under coordinated admission. */
+            }
+        });
+        this.preparationLane = prepared.catch(() => undefined);
+        this.waitingLocalEdits += 1;
+        let entered = false;
+        return this.inLocalLane(() => this.coordinateOutbox("intent", async () => {
+            entered = true;
+            this.waitingLocalEdits -= 1;
+            await prepared;
             if (admittedGeneration !== this.outboxScopeGeneration)
                 throw new GonvexClientError("Session changed before local reducer execution", { code: "superseded" });
             if (!this.localIdentity || !this.hasAuthoritativeReplicaScope)
@@ -385,15 +617,51 @@ export class GonvexClient {
             if (this.clientContract && this.clientContract.offlineMaxAgeMs !== null && !this.canSendReducerNow() && (Date.now() - this.lastOnlineAtMs > this.clientContract.offlineMaxAgeMs || Date.now() < this.lastOnlineAtMs))
                 throw new Error("Offline editing window expired. Reconnect before making more changes.");
             const scope = this.outboxScope;
-            const reducerId = randomID();
-            const execution = {
-                scope: this.replicaScope, commandId: reducerId, now: Date.now(),
-                intentEntropy: Array.from(crypto.getRandomValues(new Uint8Array(32)), byte => byte.toString(16).padStart(2, "0")).join(""),
-                artifactHash: this.localBinding.artifactHash, identity: structuredClone(this.localIdentity),
-            };
+            if (!execution || execution.scope !== this.replicaScope)
+                throw new GonvexClientError("Session changed before local reducer execution", { code: 'superseded' });
+            const sharedEntries = await this.reducerOutbox.list(scope);
+            const sharedPatches = sharedEntries?.filter(entry => entry.state !== "committed").flatMap(entry => (entry.patches ?? []).map(patch => patch.op === "delete"
+                ? { entity: patch.entity ?? patch.collection, rowId: patch.rowId, op: "delete" }
+                : { entity: patch.entity ?? patch.collection, rowId: patch.rowId, op: patch.op === "upsert" ? "insert" : patch.op, fields: patch.fields }));
+            // A fully resident prediction reads the already published atomic replica.
+            // Unrelated snapshots may still be persisting; waiting for those here
+            // makes a small edit inherit their disk latency. The shared intent lock
+            // and journal still order every edit, and known peer changes must be
+            // reconciled before a resident prediction can be reused.
+            const reuseResident = preparedResult
+                && preparedResult.base === this.replica.executionVersion()
+                && preparedResult.pending === JSON.stringify(sharedPatches)
+                && !this.peerRefreshDirty && !this.peerRefreshScheduled
+                && !sharedEntries.some(entry => entry.state === "committed");
+            const uncoveredRead = this.isUncoveredLocalRead(preparedFailure)
+                && !this.peerRefreshDirty && !this.peerRefreshScheduled
+                && !sharedEntries.some(entry => entry.state === "committed");
+            if (!reuseResident && !uncoveredRead)
+                await this.replica.synchronizeStorage();
+            if (sharedEntries)
+                this.replaceLocalPredictions(sharedEntries.filter(entry => entry.state !== "committed").map(entry => ({ commandId: entry.idempotencyKey, patches: entry.patches ?? [] })));
+            const executionBaseVersion = this.replica.executionVersion();
             let transaction;
             try {
-                transaction = await this.localExecutor.execute(ref.path, args, this.localSnapshot(true), execution);
+                if (preparedResult && preparedResult.base === executionBaseVersion && preparedResult.pending === JSON.stringify(sharedPatches)) {
+                    transaction = preparedResult.transaction;
+                }
+                else if (this.localBinding.mode === 'portable') {
+                    // A commit may invalidate preparation while the intent lock is being
+                    // acquired. Read the newly published atomic replica again before
+                    // joining disk work that arrived after synchronizeStorage completed.
+                    try {
+                        transaction = await this.executeLocal(ref.path, args, undefined, execution, sharedPatches ?? true, true);
+                    }
+                    catch (error) {
+                        if (!(error instanceof Error) || error.name !== 'IncompleteReplicaError')
+                            throw error;
+                        transaction = await this.executeLocal(ref.path, args, undefined, execution, sharedPatches ?? true);
+                    }
+                }
+                else {
+                    transaction = await this.executeLocal(ref.path, args, this.localSnapshot(true), execution, sharedPatches ?? true);
+                }
             }
             catch (error) {
                 if (!(error instanceof Error) || error.name !== "IncompleteReplicaError")
@@ -404,6 +672,10 @@ export class GonvexClient {
             const patches = transaction?.patches ?? [];
             this.directOutboxReducerIds.add(reducerId);
             try {
+                // A visible prediction must already have a durable intent. Otherwise a
+                // reload immediately after paint can lose an offline edit. Local
+                // execution still avoids a server round trip; disk admission is bounded
+                // to this intent, rather than persisting the whole replica.
                 const entry = await this.reducerOutbox.enqueue({
                     scope, path: ref.path, args, idempotencyKey: reducerId, state: "pending",
                     // All local intents form one causal chain, including reads of rows
@@ -423,13 +695,37 @@ export class GonvexClient {
                 }
                 return transaction ? transaction.result : { status: "queued", reducerId };
             }
+            catch (error) {
+                this.optimisticReducerIds.delete(reducerId);
+                this.replica.rejectCommand(reducerId);
+                throw error;
+            }
             finally {
                 this.directOutboxReducerIds.delete(reducerId);
-                this.scheduleLocalReplay();
+                // This transaction already executed against all earlier predictions.
+                // Appending it does not invalidate those predictions. Rebase only if
+                // the authoritative execution snapshot changed during execution.
+                // An uncovered read has no new data to replay against yet. Its
+                // hydration subscription schedules replay when coverage arrives;
+                // immediately retrying here only locks edits behind the same disk work.
+                if (this.replica.executionVersion() !== executionBaseVersion)
+                    this.scheduleLocalReplay();
                 void this.drainOutbox();
             }
+        })).catch(error => {
+            if (!entered)
+                this.waitingLocalEdits -= 1;
+            this.optimisticReducerIds.delete(reducerId);
+            this.replica.rejectCommand(reducerId);
+            throw error;
         });
     }
+    /** Preload code for a mounted control without reading data or executing an intent. */
+    prepareReducer(ref) {
+        if (ref.localExecution !== 1 || this.manuallyClosed)
+            return Promise.resolve();
+        return this.localExecutor?.prepare?.(ref.path) ?? Promise.resolve();
+    }
     /** The single normalized authoritative + optimistic application data store. */
     get localReplica() {
         return this.replicaView;
@@ -445,17 +741,31 @@ export class GonvexClient {
     replicaEntities(entity, ids) {
         return this.replica.entityBatch(entity, ids);
     }
+    /** Retain only the data an active view observes; cold rows remain on disk. */
+    retainReplicaEntities(entity, ids) { return this.replica.retainRows(entity, ids); }
+    retainReplicaWindow(signature) { return this.replica.retainWindow(signature); }
     /** Read rows and server-owned completeness for a persisted Replica Collection. */
     replicaCollectionState(ref, args = {}) {
         return this.replica.collectionState(this.replicaSignature(ref, args));
     }
     /** Run the generated Live Query plan over the bounded normalized cache. */
-    offlineLiveQuery(ref, args = {}) {
+    offlineLiveQuery(ref, args = {}, options = {}) {
         if (!ref.live?.plan) {
             return { rows: [], completeness: "partial", supported: false, unsupportedOperator: "missingPlan" };
         }
         const queryArgs = isJsonRecord(args) ? args : {};
-        return runOfflineLiveQuery(this.replica.entityRows(ref.live.entity), ref.live.plan, queryArgs, this.replica.entityCompleteness(ref.live.entity));
+        return runOfflineLiveQuery(this.replica.entityRows(ref.live.entity), options.window === false ? { ...ref.live.plan, window: undefined, sort: undefined } : ref.live.plan, queryArgs, this.replica.entityCompleteness(ref.live.entity), (table, id) => this.replica.entity(table, id), {
+            context: {
+                ...(this.localIdentity?.member?.id ? { 'member.id': this.localIdentity.member.id } : {}),
+                ...(this.localIdentity?.auth.account?.id ? { 'account.id': this.localIdentity.auth.account.id } : {}),
+                ...(this.localIdentity?.tenant?.id ? { 'tenant.id': this.localIdentity.tenant.id } : {}),
+            },
+            relationRows: (table, where) => {
+                const coverage = this.replica.captureReadCoverage({ [table]: { key: '_id', complete: false } });
+                return { rows: this.replica.entityRows(table), completeness: this.replica.entityCompleteness(table) === 'complete'
+                        && readIsCovered(coverage[table], { table, where: liveScopeCoverage(where, queryArgs) }) ? 'complete' : 'partial' };
+            },
+        });
     }
     /** Number of reducers waiting for a definitive server result. */
     async outboxCount() {
@@ -803,8 +1113,10 @@ export class GonvexClient {
                     this.authRetriedAfterError = false;
                     const directive = replicaDirectiveFromAuthResult(message.result);
                     const localIdentity = localIdentityFromAuthResult(message.result);
-                    if (localIdentity)
+                    if (localIdentity) {
                         this.localIdentity = localIdentity;
+                        void this.localExecutor?.ready.catch(() => undefined);
+                    }
                     if (!directive) {
                         this.authInFlight = false;
                         if (!this.auth.tenant) {
@@ -946,6 +1258,7 @@ export class GonvexClient {
         this.unsubscribeLocal?.();
         for (const close of this.localCollectionClosers.splice(0))
             close();
+        this.localCollectionKeys.clear();
         this.localExecutor?.close();
         this.cancelManagedAuthAttempt("Gonvex client was closed during authentication.");
         if (isEphemeralOutboxScope(this.outboxScope)) {
@@ -982,6 +1295,8 @@ export class GonvexClient {
             this.outboxDrainTimer = undefined;
         }
         this.unsubscribeOutbox();
+        this.unsubscribePeerOutbox?.();
+        this.unsubscribePeerReplica?.();
         this.unsubscribeBrowserOnline?.();
         this.handlers.clear();
         this.querySubscriptions.clear();
@@ -999,6 +1314,7 @@ export class GonvexClient {
         this.notifyConnectionState();
         this.connectionStateHandlers.clear();
         this.supportCommandHandlers.clear();
+        this.replica.dispose();
         const closedError = new Error("Gonvex client is closed");
         for (const pending of this.pendingNativeErrors.splice(0))
             pending.reject(closedError);
@@ -1335,7 +1651,9 @@ export class GonvexClient {
         // could overwrite a result already accepted on the same connection.
         return subscription.revisionSocketGeneration !== this.socketGeneration;
     }
-    subscribeReplicaTransport(ref, args = {}, onMessage) {
+    subscribeReplicaTransport(ref, args = {}, onMessage, metadataOnly = false) {
+        if (metadataOnly)
+            this.replicaMetadataListeners.add(onMessage);
         this.connect();
         const key = querySubscriptionKey(ref, args);
         const existing = this.replicaSubscriptions.get(key);
@@ -1345,10 +1663,14 @@ export class GonvexClient {
                 existing.unsubscribeTimer = undefined;
             }
             existing.listeners.add(onMessage);
+            // A reset may arrive during the retention grace period with no listeners.
+            // Its reopen was correctly deferred; the next subscriber must resume it.
+            if (!existing.isUpToDate && !existing.opening)
+                this.sendReplicaOpen(existing);
             if (existing.lastMessage) {
                 queueMicrotask(() => {
                     if (existing.listeners.has(onMessage) && existing.lastMessage) {
-                        onMessage(this.materializeReplicaMessage(existing, existing.lastMessage));
+                        onMessage(metadataOnly ? existing.lastMessage : this.materializeReplicaMessage(existing, existing.lastMessage));
                     }
                 });
             }
@@ -1386,12 +1708,16 @@ export class GonvexClient {
         return this.subscribeReplicaTransport(ref, args, onMessage);
     }
     /** Watch a bounded Replica Collection through the normalized Local Replica. */
-    watchReplica(ref, args = {}) {
+    watchReplica(ref, args = {}, options = {}) {
         const key = querySubscriptionKey(ref, args);
         const updateHandlers = new Set();
         let latestError;
         let snapshotVersion = -1;
         let snapshotRows;
+        const readRows = () => {
+            const next = this.replica.liveQuerySnapshot(key).rows;
+            return snapshotRows?.length === next.length && next.every((row, index) => row === snapshotRows[index]) ? snapshotRows : next;
+        };
         let stateVersion = -1;
         let stateFreshness;
         let stateIsUpToDate;
@@ -1403,45 +1729,57 @@ export class GonvexClient {
         };
         // Keep the ReplicaSubscription as transport/reconciliation state only. The
         // value returned by this watch always comes from normalized LocalReplica.
-        const unsubscribeTransport = this.subscribeReplicaTransport(ref, args, (message) => {
-            if (message.type === "replica.error") {
-                latestError = new Error(message.error);
-                notify();
-            }
-            else if (message.type === "replica.syncing" || message.type === "replica.reset") {
-                latestError = undefined;
-                notify();
-            }
-            else if (message.type === "replica.ready") {
-                latestError = undefined;
-                notify();
-            }
-            else if (message.type === "replica.snapshot") {
-                latestError = undefined;
-            }
-        });
-        const unsubscribeReplica = this.replica.subscribe(notify);
-        const unsubscribeScope = this.onSessionScopeChange(() => {
-            latestError = undefined;
+        let stop;
+        const start = () => {
+            if (stop)
+                return;
             snapshotVersion = -1;
-            snapshotRows = undefined;
             stateVersion = -1;
-            stateFreshness = undefined;
-            stateIsUpToDate = undefined;
-            snapshotState = undefined;
-            notify();
-        });
+            const releaseRows = this.replica.retainWindow(key);
+            const unsubscribeTransport = this.subscribeReplicaTransport(ref, args, (message) => {
+                if (message.type === "replica.error") {
+                    latestError = new Error(message.error);
+                    notify();
+                }
+                else if (message.type === "replica.syncing" || message.type === "replica.reset") {
+                    latestError = undefined;
+                    notify();
+                }
+                else if (message.type === "replica.ready") {
+                    latestError = undefined;
+                    notify();
+                }
+                else if (message.type === "replica.snapshot") {
+                    latestError = undefined;
+                }
+            }, true);
+            const unsubscribeReplica = this.replica.subscribe(notify);
+            const unsubscribeScope = this.onSessionScopeChange(() => {
+                latestError = undefined;
+                snapshotVersion = -1;
+                snapshotRows = undefined;
+                stateVersion = -1;
+                stateFreshness = undefined;
+                stateIsUpToDate = undefined;
+                snapshotState = undefined;
+                notify();
+            });
+            stop = () => { unsubscribeTransport(); unsubscribeReplica(); unsubscribeScope(); releaseRows(); stop = undefined; };
+        };
+        // React can discard a render before subscribing. Such watches must own no resources.
+        if (!options.deferStart)
+            start();
         return {
             localReplicaResult: () => {
                 if (latestError)
                     throw latestError;
                 if (!this.replica.hasLiveQuery(key))
                     return undefined;
-                const version = this.replica.windowVersion(key);
+                const version = this.replica.windowRowsVersion(key);
                 if (snapshotVersion === version)
                     return snapshotRows;
                 snapshotVersion = version;
-                snapshotRows = this.replica.liveQuery(key).rows;
+                snapshotRows = readRows();
                 return snapshotRows;
             },
             localReplicaState: () => {
@@ -1459,7 +1797,12 @@ export class GonvexClient {
                 stateVersion = version;
                 stateFreshness = freshness;
                 stateIsUpToDate = isUpToDate;
-                const state = this.replica.collectionState(key);
+                const rowsVersion = this.replica.windowRowsVersion(key);
+                if (snapshotVersion !== rowsVersion) {
+                    snapshotVersion = rowsVersion;
+                    snapshotRows = readRows();
+                }
+                const state = this.replica.collectionState(key, snapshotRows);
                 snapshotState = {
                     ...state,
                     isUpToDate,
@@ -1475,6 +1818,7 @@ export class GonvexClient {
                 isUpToDate: this.replicaSubscriptions.get(key)?.isUpToDate === true,
             }),
             onUpdate(handler) {
+                start();
                 if (releaseTimer) {
                     clearTimeout(releaseTimer);
                     releaseTimer = undefined;
@@ -1492,9 +1836,7 @@ export class GonvexClient {
                         releaseTimer = undefined;
                         if (updateHandlers.size > 0)
                             return;
-                        unsubscribeTransport();
-                        unsubscribeReplica();
-                        unsubscribeScope();
+                        stop?.();
                     }, 0);
                 };
             },
@@ -1505,7 +1847,7 @@ export class GonvexClient {
      * latest query result is retained only as the transport-shaped skeleton;
      * its row window is always rebuilt from LocalReplica membership/entities.
      */
-    watchLiveQuery(ref, args = {}) {
+    watchLiveQuery(ref, args = {}, options = {}) {
         const key = querySubscriptionKey(ref, args);
         const updateHandlers = new Set();
         let transportResult;
@@ -1525,39 +1867,51 @@ export class GonvexClient {
                     handler();
             });
         };
-        const unsubscribeQuery = this.subscribeLiveQuery(ref, args, (message) => {
-            if (message.type === "query.result") {
-                transportResult = message.result;
+        let stop;
+        const start = () => {
+            if (stop)
+                return;
+            transportResult = undefined;
+            snapshotToken = "";
+            const releaseRows = this.replica.retainWindow(key);
+            const unsubscribeQuery = this.subscribeLiveQuery(ref, args, (message) => {
+                if (message.type === "query.result") {
+                    transportResult = message.result;
+                    transportGeneration += 1;
+                    latestError = undefined;
+                    // LocalReplica has already published its atomic window swap before
+                    // this callback is emitted, so this is the single initial UI wake-up.
+                    notify();
+                }
+                else if (message.type === "query.error") {
+                    latestError = new GonvexClientError(`Query ${ref.path} failed: ${message.error}`, {
+                        code: "server", path: ref.path, operation: "query",
+                    });
+                    notify();
+                }
+            });
+            // During the initial query result, LocalReplica notifies before the
+            // transport-shaped skeleton is installed above. Suppress that empty
+            // intermediate wake-up; later transactions notify directly from the
+            // normalized store.
+            const unsubscribeReplica = this.replica.subscribe(() => {
+                if (transportResult !== undefined || this.replica.hasLiveQuery(key))
+                    notify();
+            });
+            void this.replicaReady.then(() => notify());
+            const unsubscribeScope = this.onSessionScopeChange(() => {
+                transportResult = undefined;
                 transportGeneration += 1;
+                snapshotToken = "";
+                snapshotResult = undefined;
                 latestError = undefined;
-                // LocalReplica has already published its atomic window swap before
-                // this callback is emitted, so this is the single initial UI wake-up.
-                notify();
-            }
-            else if (message.type === "query.error") {
-                latestError = new GonvexClientError(`Query ${ref.path} failed: ${message.error}`, {
-                    code: "server", path: ref.path, operation: "query",
-                });
-                notify();
-            }
-        });
-        // During the initial query result, LocalReplica notifies before the
-        // transport-shaped skeleton is installed above. Suppress that empty
-        // intermediate wake-up; later transactions notify directly from the
-        // normalized store.
-        const unsubscribeReplica = this.replica.subscribe(() => {
-            if (transportResult !== undefined || this.replica.hasLiveQuery(key))
                 notify();
-        });
-        void this.replicaReady.then(() => notify());
-        const unsubscribeScope = this.onSessionScopeChange(() => {
-            transportResult = undefined;
-            transportGeneration += 1;
-            snapshotToken = "";
-            snapshotResult = undefined;
-            latestError = undefined;
-            notify();
-        });
+            });
+            stop = () => { unsubscribeQuery(); unsubscribeReplica(); unsubscribeScope(); releaseRows(); stop = undefined; };
+        };
+        // React can discard a render before subscribing. Such watches must own no resources.
+        if (!options.deferStart)
+            start();
         return {
             localLiveQueryResult: () => {
                 if (latestError)
@@ -1592,6 +1946,7 @@ export class GonvexClient {
                 return snapshotResult;
             },
             onUpdate(handler) {
+                start();
                 if (releaseTimer) {
                     clearTimeout(releaseTimer);
                     releaseTimer = undefined;
@@ -1609,9 +1964,7 @@ export class GonvexClient {
                         releaseTimer = undefined;
                         if (updateHandlers.size > 0)
                             return;
-                        unsubscribeQuery();
-                        unsubscribeReplica();
-                        unsubscribeScope();
+                        stop?.();
                     }, 0);
                 };
             },
@@ -1656,7 +2009,7 @@ export class GonvexClient {
                 scope,
             };
             await this.replica.replaceWindow(window);
-            const snapshot = { ...message, result: this.replica.windowRows(subscription.key) };
+            const snapshot = { ...message, result: [] };
             subscription.lastMessage = snapshot;
             this.emitReplicaMessage(subscription, snapshot, scope);
             return;
@@ -1667,12 +2020,20 @@ export class GonvexClient {
                 return;
             this.clearReplicaRetry(subscription, true);
             raiseReplicaCursorFloor(subscription, message.cursor);
+            const upserts = (message.upserts ?? []).filter((row) => asReplicaRow(row) !== undefined).map(row => asReplicaRow(row));
+            // Incremental integrity is safe only for full projected row images. Older
+            // partial-row protocols keep the full normalized rehash on replica.ready.
+            const canCarryHashes = prior?.hashes && subscription.columns?.length
+                && upserts.every(row => subscription.columns.every(column => hasOwn(row, column)));
+            const hashes = message.hashes ?? (canCarryHashes
+                ? await applyReplicaHashDelta(prior.hashes, projectReplicaIntegrityRows(upserts, subscription.columns), message.deleted ?? [], prior?.key ?? "id")
+                : undefined);
             await this.replica.applyWindowDelta({
                 signature: subscription.key,
                 kind: "replica",
                 entity: subscription.entity,
                 key: prior?.key ?? "id",
-                upserts: (message.upserts ?? []).filter((row) => asReplicaRow(row) !== undefined).map((row) => asReplicaRow(row)),
+                upserts,
                 deleted: message.deleted ?? [],
                 completeness: prior?.completeness ?? "partial",
                 source: "server",
@@ -1683,13 +2044,11 @@ export class GonvexClient {
                 orderDirection: prior?.orderDirection,
                 maxRows: prior?.maxRows,
                 maxBytes: prior?.maxBytes,
-                // A delta invalidates the prior full integrity map unless the server
-                // supplied a complete replacement map with this frame.
-                hashes: message.hashes,
+                hashes,
             });
             const snapshot = {
                 type: "replica.snapshot", id: subscription.id, path: subscription.path,
-                result: this.replica.windowRows(subscription.key), cursor: message.cursor,
+                result: [], cursor: message.cursor,
                 key: prior?.key ?? "id", mode: prior?.mode, orderBy: prior?.orderBy,
                 orderDirection: prior?.orderDirection, maxRows: prior?.maxRows, maxBytes: prior?.maxBytes,
             };
@@ -1839,9 +2198,15 @@ export class GonvexClient {
     emitReplicaMessage(subscription, message, scope = this.replicaScope) {
         if (scope !== this.replicaScope || subscription.scope !== scope)
             return;
-        const outgoing = this.materializeReplicaMessage(subscription, message);
-        for (const listener of Array.from(subscription.listeners))
-            listener(outgoing);
+        // Hook observers consume metadata only; their rows come from Local Replica.
+        // Materialize a payload only when a public transport consumer needs it.
+        let outgoing;
+        for (const listener of Array.from(subscription.listeners)) {
+            if (this.replicaMetadataListeners.has(listener))
+                listener(message);
+            else
+                listener(outgoing ??= this.materializeReplicaMessage(subscription, message));
+        }
     }
     materializeReplicaMessage(subscription, message) {
         if (message.type !== "replica.snapshot")
@@ -1887,7 +2252,7 @@ export class GonvexClient {
             subscription.isUpToDate = false;
             const message = {
                 type: "replica.snapshot", id: subscription.id, path: subscription.path,
-                result: this.replica.windowRows(subscription.key), cursor: cached.cursor ?? { epoch: "cache", revision: 0 },
+                result: [], cursor: cached.cursor ?? { epoch: "cache", revision: 0 },
                 key: cached.key, mode: cached.mode, orderBy: cached.orderBy,
                 orderDirection: cached.orderDirection, maxRows: cached.maxRows, maxBytes: cached.maxBytes,
             };
@@ -2031,7 +2396,6 @@ export class GonvexClient {
         // and sends a second time with the same command ID.
         this.outboxReady = this.restoreOutbox(this.outboxScope, generation);
         await this.outboxReady;
-        this.ensureLocalCollections();
     }
     quarantineReplicaScope() {
         this.localIdentity = undefined;
@@ -2059,6 +2423,7 @@ export class GonvexClient {
     }
     async restoreOutbox(scope, generation) {
         await this.replicaReady;
+        await this.replica.synchronizeStorage();
         const entries = await this.reducerOutbox.loadAll(scope);
         if (this.manuallyClosed
             || generation !== this.outboxScopeGeneration
@@ -2095,8 +2460,11 @@ export class GonvexClient {
         void this.drainOutbox();
     }
     addOptimisticReducer(reducerId, patches, accepted = false) {
-        if (patches.length === 0 || this.optimisticReducerIds.has(reducerId))
+        if (patches.length === 0) {
+            this.optimisticReducerIds.delete(reducerId);
+            this.replica.rejectCommand(reducerId);
             return;
+        }
         this.optimisticReducerIds.add(reducerId);
         this.replica.applyOptimistic(reducerId, patches);
     }
@@ -2124,83 +2492,90 @@ export class GonvexClient {
         const drainScope = this.outboxScope;
         this.drainingOutbox = true;
         try {
-            while (!this.manuallyClosed && this.socket?.readyState === WebSocket.OPEN) {
-                const scope = this.outboxScope;
-                const entry = await this.inLocalLane(async () => {
-                    const next = await this.reducerOutbox.nextReady(scope, Date.now());
-                    if (next)
-                        await this.reducerOutbox.markInflight(next.id);
-                    return next;
-                });
-                if (!entry)
-                    return;
-                if (scope !== this.outboxScope)
-                    return;
-                if (this.directOutboxReducerIds.has(entry.idempotencyKey)) {
-                    // Scope recovery may observe an inflight row created by this live
-                    // process and reset it to pending under the assumption that a prior
-                    // process crashed. The foreground call still owns that command ID.
-                    // Restore the durable marker and wait for its real result instead of
-                    // registering a second response handler for the same command.
-                    await this.reducerOutbox.markInflight(entry.id);
+            await this.coordinateOutbox("delivery", async () => {
+                if (this.manuallyClosed || drainScope !== this.outboxScope || !this.canSendReducerNow())
                     return;
-                }
-                if (!this.canSendReducerNow()) {
-                    await this.reducerOutbox.markPending(entry.id);
-                    return;
-                }
-                await this.reducerOutbox.markInflight(entry.id);
-                if (scope !== this.outboxScope)
-                    return;
-                if (!this.canSendReducerNow()) {
-                    await this.reducerOutbox.markPending(entry.id);
-                    return;
-                }
-                try {
-                    await this.call("reducer", { kind: "reducer", path: entry.path, receiptPath: entry.receiptPath, ...(entry.localExecution ? { artifactHash: entry.localExecution.artifactHash, intentEntropy: entry.localExecution.intentEntropy } : {}) }, entry.args, this.timeouts.reducerTimeoutMs, entry.idempotencyKey, entry.idempotencyKey);
-                    await this.reducerOutbox.markCommitted(entry.id);
-                    if (entry.localExecution && this.localExecutor) {
-                        await this.inLocalLane(async () => {
-                            await this.reducerOutbox.ack(entry.id);
-                            if (scope === this.outboxScope)
-                                await this.rebaseLocalEntries();
-                        });
-                    }
-                    else if ((entry.patches?.length ?? 0) > 0) {
-                        await this.settleOptimisticReducer(entry.idempotencyKey);
+                if (this.sharedOutboxStore)
+                    await this.reducerOutbox.recoverInflight?.(drainScope);
+                while (!this.manuallyClosed && this.socket?.readyState === WebSocket.OPEN) {
+                    const scope = this.outboxScope;
+                    const entry = await this.inLocalLane(async () => {
+                        const next = await this.reducerOutbox.nextReady(scope, Date.now());
+                        if (next)
+                            await this.reducerOutbox.markInflight(next.id);
+                        return next;
+                    });
+                    if (!entry)
+                        return;
+                    if (scope !== this.outboxScope)
+                        return;
+                    if (this.directOutboxReducerIds.has(entry.idempotencyKey)) {
+                        // Scope recovery may observe an inflight row created by this live
+                        // process and reset it to pending under the assumption that a prior
+                        // process crashed. The foreground call still owns that command ID.
+                        // Restore the durable marker and wait for its real result instead of
+                        // registering a second response handler for the same command.
+                        await this.reducerOutbox.markInflight(entry.id);
+                        return;
                     }
-                    else {
-                        await this.ackOptimisticReducer(entry.idempotencyKey, entry.id);
+                    if (!this.canSendReducerNow()) {
+                        await this.reducerOutbox.markPending(entry.id);
+                        return;
                     }
-                }
-                catch (error) {
-                    if (error instanceof Error && /STALE_REDUCER_ARTIFACT|CLIENT_UPDATE_REQUIRED/.test(error.message)) {
+                    await this.reducerOutbox.markInflight(entry.id);
+                    if (scope !== this.outboxScope)
+                        return;
+                    if (!this.canSendReducerNow()) {
                         await this.reducerOutbox.markPending(entry.id);
-                        this.requireClientUpdate(error.message);
                         return;
                     }
-                    if (error instanceof GonvexClientError && error.code === "server") {
+                    try {
+                        await this.call("reducer", { kind: "reducer", path: entry.path, receiptPath: entry.receiptPath, ...(entry.localExecution ? { artifactHash: entry.localExecution.artifactHash, intentEntropy: entry.localExecution.intentEntropy } : {}) }, entry.args, this.timeouts.reducerTimeoutMs, entry.idempotencyKey, entry.idempotencyKey);
+                        await this.reducerOutbox.markCommitted(entry.id);
                         if (entry.localExecution && this.localExecutor) {
                             await this.inLocalLane(async () => {
                                 await this.reducerOutbox.ack(entry.id);
-                                if (scope === this.outboxScope) {
+                                if (scope === this.outboxScope)
                                     await this.rebaseLocalEntries();
-                                    this.reportLocalRejection(entry.idempotencyKey, entry.path, error);
-                                }
                             });
                         }
-                        else
-                            await this.rejectOptimisticReducer(entry.idempotencyKey, entry.id);
-                        continue;
+                        else if ((entry.patches?.length ?? 0) > 0) {
+                            await this.settleOptimisticReducer(entry.idempotencyKey);
+                        }
+                        else {
+                            await this.ackOptimisticReducer(entry.idempotencyKey, entry.id);
+                        }
+                    }
+                    catch (error) {
+                        if (error instanceof Error && /STALE_REDUCER_ARTIFACT|CLIENT_UPDATE_REQUIRED/.test(error.message)) {
+                            await this.reducerOutbox.markPending(entry.id);
+                            this.requireClientUpdate(error.message);
+                            return;
+                        }
+                        if (error instanceof GonvexClientError && error.code === "server") {
+                            if (entry.localExecution && this.localExecutor) {
+                                await this.inLocalLane(async () => {
+                                    await this.reducerOutbox.ack(entry.id);
+                                    if (scope === this.outboxScope) {
+                                        await this.rebaseLocalEntries(true);
+                                        this.reportLocalRejection(entry.idempotencyKey, entry.path, error);
+                                    }
+                                });
+                            }
+                            else
+                                await this.rejectOptimisticReducer(entry.idempotencyKey, entry.id);
+                            continue;
+                        }
+                        await this.reducerOutbox.fail(entry.id, reducerErrorMessage(error));
+                        this.scheduleOutboxDrain(Math.min(30_000, 1_000 * (2 ** (entry.attempts + 1))));
+                        return;
                     }
-                    await this.reducerOutbox.fail(entry.id, reducerErrorMessage(error));
-                    this.scheduleOutboxDrain(Math.min(30_000, 1_000 * (2 ** (entry.attempts + 1))));
-                    return;
                 }
-            }
+            });
         }
         finally {
             this.drainingOutbox = false;
+            this.scheduleLocalReplay();
             if (!this.manuallyClosed && drainScope !== this.outboxScope) {
                 void this.drainOutbox();
             }
@@ -2514,8 +2889,11 @@ export class GonvexClient {
                     return;
                 }
                 if (kind === "reducer" && message.type === "reducer.result") {
-                    this.replica.acknowledgeCommand(message.originCommandId, message.committedRevision);
                     const complete = () => {
+                        // A collection frame can advance the shared cursor before another
+                        // collection's rows and membership have arrived. Retire the local
+                        // prediction only after the commit's durable watermark barrier.
+                        this.replica.acknowledgeCommand(message.originCommandId, message.committedRevision);
                         settle();
                         this.emitTelemetryFromCall(kind, id, ref.path, "ok", clientSentAtMs, message.trace);
                         resolve(message.result);
@@ -3160,15 +3538,33 @@ function replaceOfflineLiveQueryMetadata(result, path, offline) {
     const current = result[head];
     return { ...result, [head]: replaceOfflineLiveQueryMetadata(current ?? null, tail, offline) };
 }
+// Generated references and their plans are immutable module metadata. Retain
+// one canonical contract per reference, not a fresh sorted serialization for
+// every React watch/read. Weak keys do not retain replaced modules or callers.
+const subscriptionContracts = new WeakMap();
 function querySubscriptionKey(ref, args) {
-    const contract = {
-        scope: ref.scope ?? "tenant",
-        delivery: ref.delivery ?? "oneShot",
-        live: ref.live
-            ? { entity: ref.live.entity, key: ref.live.key, resultPath: [...(ref.live.resultPath ?? [])], plan: ref.live.plan ?? null }
-            : null,
-    };
-    return `${ref.path}\u0000${stableStringify(args)}\u0000${stableStringify(contract)}`;
+    let cached = subscriptionContracts.get(ref);
+    if (!cached || cached.scope !== ref.scope || cached.delivery !== ref.delivery || cached.live !== ref.live) {
+        const contract = {
+            scope: ref.scope ?? "tenant",
+            delivery: ref.delivery ?? "oneShot",
+            live: ref.live
+                ? { entity: ref.live.entity, key: ref.live.key, resultPath: [...(ref.live.resultPath ?? [])], plan: ref.live.plan ?? null }
+                : null,
+        };
+        cached = { scope: ref.scope, delivery: ref.delivery, live: ref.live, value: stableStringify(contract), keys: new Map() };
+        subscriptionContracts.set(ref, cached);
+    }
+    const argumentsKey = `${ref.path}\u0000${stableStringify(args)}`;
+    const previous = cached.keys.get(argumentsKey);
+    if (previous !== undefined)
+        return previous;
+    const key = `${argumentsKey}\u0000${cached.value}`;
+    // Search text and pagination may produce unbounded argument combinations.
+    if (cached.keys.size >= 16)
+        cached.keys.delete(cached.keys.keys().next().value);
+    cached.keys.set(argumentsKey, key);
+    return key;
 }
 function countPendingCalls(calls, kind) {
     let count = 0;
@@ -3202,6 +3598,9 @@ function stableStringify(value) {
         .join(",")}}`;
 }
 function utf8KeyCompare(left, right) {
+    // ASCII keys have identical UTF-8 and JavaScript lexical ordering.
+    if (!/[^\x00-\x7f]/.test(left) && !/[^\x00-\x7f]/.test(right))
+        return left < right ? -1 : left > right ? 1 : 0;
     const leftBytes = new TextEncoder().encode(left);
     const rightBytes = new TextEncoder().encode(right);
     const length = Math.min(leftBytes.length, rightBytes.length);
@@ -3222,9 +3621,9 @@ function boundReplicaRows(rows, keyField, maxRows, maxBytes, orderBy, orderDirec
         const key = replicaRowKeyValue(row, keyField);
         if (!key || seen.has(key))
             continue;
-        const size = replicaJSONSize(row);
         if (maxRows && kept.length >= maxRows)
             break;
+        const size = maxBytes ? replicaJSONSize(row) : 0;
         if (maxBytes && bytes + size > maxBytes)
             break;
         kept.push(row);
@@ -3271,7 +3670,10 @@ function replicaRowKeyValue(value, keyField) {
     return key === null || key === undefined ? "" : String(key);
 }
 function replicaJSONSize(value) {
-    return new TextEncoder().encode(stableStringify(value)).byteLength;
+    // Property ordering cannot change the encoded length. Native serialization
+    // avoids recursively allocating sorted key arrays and intermediate strings.
+    const json = JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+    return new TextEncoder().encode(json).byteLength;
 }
 function applyKeyedPatch(previous, patch) {
     const rows = new Map();
@@ -3535,4 +3937,34 @@ function detectDeviceType(userAgent) {
         return "mobile";
     return "desktop";
 }
+/** Sign-in and account-only pages do not need reducer code loaded. */
+function deferredLocalExecutor(create) {
+    let executor;
+    let closed = false;
+    const start = () => {
+        if (closed)
+            throw new Error("Local reducer executor is closed");
+        return executor ??= create();
+    };
+    return {
+        get ready() {
+            try {
+                return start().ready;
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        },
+        prepare: async (path) => start().prepare?.(path),
+        execute: async (...args) => start().execute(...args),
+        executeRead: async (...args) => {
+            const instance = start();
+            if (!instance.executeRead)
+                throw new Error('Local executor does not support indexed reads');
+            return instance.executeRead(...args);
+        },
+        replay: async (...args) => start().replay(...args),
+        close: () => { closed = true; executor?.close(); },
+    };
+}
 //# sourceMappingURL=index.js.map