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

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 { createReducerOutbox, DEFAULT_OUTBOX_MAX_BACKOFF_MS, outboxBackoffMs, outboxEntryIsLive, } 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(),
@@ -91,14 +96,28 @@ export class GonvexClientError extends Error {
     code;
     path;
     operation;
+    /**
+     * For `server` Reducer errors: the runtime's classification, or a legacy
+     * inference when an older runtime sent none. Undefined means a legacy
+     * runtime's unclassified error, which is handled as a rejection.
+     */
+    errorClass;
+    /** True when the same call (same idempotency key) may succeed later. */
+    retryable;
     constructor(message, options) {
         super(message);
         this.name = "GonvexClientError";
         this.code = options.code;
         this.path = options.path;
         this.operation = options.operation;
+        if (options.errorClass)
+            this.errorClass = options.errorClass;
+        if (options.retryable !== undefined)
+            this.retryable = options.retryable;
     }
 }
+export const DEFAULT_OUTBOX_MAX_ATTEMPTS = 10;
+export const DEFAULT_OUTBOX_RETRY_MAX_BACKOFF_MS = 60_000;
 export const DEFAULT_QUERY_TIMEOUT_MS = 20_000;
 export const DEFAULT_REDUCER_TIMEOUT_MS = 20_000;
 export const DEFAULT_ACTION_TIMEOUT_MS = 60_000;
@@ -117,20 +136,32 @@ 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();
+    outboxRetry;
+    unauthenticatedRetries = 0;
+    intentsSnapshotValue = [];
+    intentListeners = new Set();
+    intentsRefreshRunning = false;
+    intentsRefreshDirty = false;
     socket;
     handlers = new Map();
     querySubscriptions = new Map();
     replicaSubscriptions = new Map();
+    replicaMetadataListeners = new WeakSet();
     oneShotQueries = new Map();
     telemetryHandlers = new Set();
     pendingMessages = [];
@@ -179,8 +210,15 @@ export class GonvexClient {
     processedReplicaWatermarkRevision = 0;
     pendingReplicaTransactions = [];
     unsubscribeOutbox;
+    sharedOutboxStore;
+    unsubscribePeerOutbox;
+    unsubscribePeerReplica;
+    peerRefreshScheduled = false;
+    peerRefreshDirty = false;
     unsubscribeBrowserOnline;
     drainingOutbox = false;
+    /** A wake-up (timer, enqueue, reconnect) that arrived while a drain was running. */
+    outboxDrainRequested = false;
     outboxDrainTimer;
     sessionScopeHandlers = new Set();
     errorReporter;
@@ -206,18 +244,43 @@ 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.outboxRetry = {
+            maxAttempts: positiveOr(options.outbox?.retry?.maxAttempts, DEFAULT_OUTBOX_MAX_ATTEMPTS),
+            maxBackoffMs: positiveOr(options.outbox?.retry?.maxBackoffMs, DEFAULT_OUTBOX_RETRY_MAX_BACKOFF_MS),
+        };
+        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(() => {
+            this.refreshIntents();
             void this.drainOutbox();
         });
         if (typeof globalThis.addEventListener === "function") {
@@ -256,11 +319,254 @@ export class GonvexClient {
         if (this.localBinding)
             this.outboxReady = this.restoreLocalSession(initialScope, this.outboxScopeGeneration);
     }
-    /** Authoritative sync failures arrive after an offline call returned locally. */
+    /**
+     * Authoritative sync failures arrive after an offline call returned locally.
+     * The intent also stays in the outbox as `rejected` until it is discarded
+     * or retried, so a UI that mounts later can still show it.
+     */
     onReducerRejection(listener) {
         this.reducerRejectionHandlers.add(listener);
         return () => this.reducerRejectionHandlers.delete(listener);
     }
+    /** Every durable intent of the current identity, oldest first. */
+    async listIntents() {
+        await this.outboxReady;
+        return (await this.reducerOutbox.list(this.outboxScope)).map(outboxIntentFromEntry);
+    }
+    /**
+     * Synchronous snapshot for external stores (React `useSyncExternalStore`).
+     * Kept current while at least one {@link subscribeIntents} listener exists.
+     */
+    intentsSnapshot() {
+        return this.intentsSnapshotValue;
+    }
+    /** Observe intent changes; call {@link intentsSnapshot} for the new value. */
+    subscribeIntents(listener) {
+        this.intentListeners.add(listener);
+        if (this.intentListeners.size === 1)
+            this.refreshIntents();
+        return () => { this.intentListeners.delete(listener); };
+    }
+    /**
+     * Delivery status for one row from the current snapshot: `failed` or
+     * `rejected` when an intent touching it needs attention, `syncing` while one
+     * is still queued, otherwise undefined.
+     */
+    entityIntentStatus(entity, id) {
+        return entityStatusFromIntents(this.intentsSnapshotValue, entity, id);
+    }
+    /**
+     * Re-arm a `failed` or `rejected` intent with a fresh retry budget. The
+     * original idempotency key is reused, so an attempt that had actually
+     * committed is replayed by the server rather than applied twice.
+     */
+    async retryIntent(id) {
+        await this.outboxReady;
+        const retried = await this.inLocalLane(() => this.coordinateOutbox("intent", async () => {
+            const scope = this.outboxScope;
+            const entry = (await this.reducerOutbox.list(scope)).find((candidate) => candidate.idempotencyKey === id);
+            if (!entry || scope !== this.outboxScope)
+                return false;
+            const updated = await this.reducerOutbox.retry(entry.id);
+            if (!updated)
+                return false;
+            this.optimisticOutboxEntryIds.set(id, updated.id);
+            if (!outboxEntryIsLive(entry)) {
+                // A rejection rolled the prediction back; restore it at its original
+                // position in the causal chain.
+                if (updated.localExecution && this.localExecutor)
+                    await this.rebaseLocalEntriesLocked(true);
+                else
+                    this.addOptimisticReducer(id, updated.patches ?? []);
+            }
+            return true;
+        }));
+        if (retried) {
+            this.unauthenticatedRetries = 0;
+            void this.drainOutbox();
+        }
+        return retried;
+    }
+    /**
+     * Drop a `pending`, `failed` or `rejected` intent: it will never be sent,
+     * its optimistic prediction is removed and later local intents are rebased.
+     * Inflight and committed intents cannot be discarded. Discarding an intent
+     * whose earlier attempt timed out does not undo a commit that the server
+     * may already have applied; the replica then shows the server's truth.
+     */
+    async discardIntent(id) {
+        await this.outboxReady;
+        return this.inLocalLane(() => this.coordinateOutbox("intent", async () => {
+            const scope = this.outboxScope;
+            const entry = (await this.reducerOutbox.list(scope)).find((candidate) => candidate.idempotencyKey === id);
+            if (!entry || scope !== this.outboxScope)
+                return false;
+            const removed = await this.reducerOutbox.discard(entry.id, ["pending", "failed", "rejected"]);
+            if (!removed)
+                return false;
+            this.optimisticOutboxEntryIds.delete(id);
+            this.optimisticReducerIds.delete(id);
+            if (outboxEntryIsLive(removed)) {
+                this.replacingLocal = true;
+                try {
+                    this.replica.rejectCommand(id);
+                }
+                finally {
+                    this.replacingLocal = false;
+                }
+                if (removed.localExecution && this.localExecutor)
+                    await this.rebaseLocalEntriesLocked(true);
+            }
+            return true;
+        }));
+    }
+    /**
+     * Discard the persisted Local Replica of the active identity (IndexedDB,
+     * Expo SQLite or any configured storage) and rehydrate it from the server.
+     *
+     * Online only: without an authenticated connection the call rejects with a
+     * `GonvexClientError` (`code: "disconnected"`) and changes nothing, so the
+     * user is never left with an empty cache that cannot be refilled. The saved
+     * offline session (identity and replica directive) is kept.
+     *
+     * By default the outbox is untouched: pending, failed and rejected intents
+     * stay durable, and the predictions of every live intent are re-applied
+     * immediately and recomputed as server data arrives. Active Replica
+     * Collections and Live Queries are re-requested without their old cursors,
+     * so the server sends full snapshots.
+     */
+    async resetLocalReplica(options = {}) {
+        const refuse = (message) => new GonvexClientError(message, { code: "disconnected", operation: "query" });
+        if (this.manuallyClosed)
+            throw new GonvexClientError("Gonvex client is closed", { code: "closed", operation: "query" });
+        await this.outboxReady;
+        await this.replicaReady;
+        if (!this.canSendReducerNow() || !this.hasAuthoritativeReplicaScope) {
+            throw refuse("Cannot reset local data while offline. Reconnect and try again; cached data was kept.");
+        }
+        const keepOutbox = options.keepOutbox !== false;
+        return this.inLocalLane(() => this.coordinateOutbox("intent", async () => {
+            const scope = this.outboxScope;
+            const replicaScope = this.replicaScope;
+            // Re-check under the lock: the connection may have dropped while waiting.
+            if (!this.canSendReducerNow() || !this.hasAuthoritativeReplicaScope) {
+                throw refuse("Cannot reset local data while offline. Reconnect and try again; cached data was kept.");
+            }
+            // Stop the server streaming into subscription ids we are about to retire.
+            for (const subscription of this.replicaSubscriptions.values()) {
+                if (subscription.socketGeneration !== undefined)
+                    this.send({ type: "replica.close", id: subscription.id });
+            }
+            for (const subscription of this.querySubscriptions.values()) {
+                if (subscription.socketGeneration !== undefined)
+                    this.send({ type: "query.unsubscribe", id: subscription.id });
+            }
+            this.pendingReplicaTransactions.length = 0;
+            await this.replica.clear(replicaScope);
+            this.resetReplicaScopeState();
+            this.rotateSubscriptionScopes();
+            let discardedIntents = 0;
+            if (!keepOutbox) {
+                for (const entry of await this.reducerOutbox.list(scope)) {
+                    if (await this.reducerOutbox.discard(entry.id, ["pending", "failed", "rejected"]))
+                        discardedIntents += 1;
+                }
+            }
+            // replica.clear() dropped every overlay. Restore the stored predictions
+            // of live intents now; local intents are re-executed by the replay that
+            // each arriving snapshot schedules.
+            const entries = (await this.reducerOutbox.list(scope)).filter(outboxEntryIsLive);
+            this.replacingLocal = true;
+            try {
+                this.replaceLocalPredictions(entries.filter(entry => entry.state !== "committed").map(entry => ({ commandId: entry.idempotencyKey, patches: entry.patches ?? [] })));
+            }
+            finally {
+                this.replacingLocal = false;
+            }
+            this.optimisticReducerIds.clear();
+            this.optimisticOutboxEntryIds.clear();
+            for (const entry of entries) {
+                this.optimisticOutboxEntryIds.set(entry.idempotencyKey, entry.id);
+                if (entry.state !== "committed" && entry.patches?.length)
+                    this.optimisticReducerIds.add(entry.idempotencyKey);
+            }
+            let resubscribed = 0;
+            if (scope === this.outboxScope && replicaScope === this.replicaScope) {
+                for (const subscription of this.replicaSubscriptions.values())
+                    if (subscription.listeners.size > 0)
+                        resubscribed += 1;
+                for (const subscription of this.querySubscriptions.values())
+                    if (subscription.listeners.size > 0)
+                        resubscribed += 1;
+                this.resumeQuerySubscriptions(true);
+                this.resumeReplicaSubscriptions();
+            }
+            this.refreshIntents();
+            return { discardedIntents, resubscribed };
+        }));
+    }
+    /** Outbox owners with durable entries, including identities that never returned. */
+    async listOutboxScopes() {
+        await this.outboxReady;
+        const current = this.outboxScope;
+        return (await this.reducerOutbox.listScopes()).map((scope) => ({ ...scope, current: scope.scope === current }));
+    }
+    /**
+     * Permanently delete another identity's durable intents. The active scope
+     * cannot be purged this way; use {@link discardIntent} for its entries.
+     */
+    async purgeOutboxScope(scope) {
+        await this.outboxReady;
+        if (scope === this.outboxScope)
+            throw new Error("Cannot purge the active outbox scope");
+        return this.reducerOutbox.purgeScope(scope);
+    }
+    /** Purge every outbox scope except the current identity's. Never runs automatically. */
+    async purgeForeignOutboxScopes() {
+        let removed = 0;
+        for (const scope of await this.listOutboxScopes()) {
+            if (!scope.current)
+                removed += await this.purgeOutboxScope(scope.scope);
+        }
+        return removed;
+    }
+    refreshIntents() {
+        if (this.intentListeners.size === 0 || this.manuallyClosed)
+            return;
+        this.intentsRefreshDirty = true;
+        if (this.intentsRefreshRunning)
+            return;
+        this.intentsRefreshRunning = true;
+        void (async () => {
+            try {
+                while (this.intentsRefreshDirty && !this.manuallyClosed) {
+                    this.intentsRefreshDirty = false;
+                    await this.outboxReady.catch(() => undefined);
+                    const scope = this.outboxScope;
+                    const entries = await this.reducerOutbox.list(scope).catch(() => undefined);
+                    if (!entries || scope !== this.outboxScope) {
+                        this.intentsRefreshDirty ||= scope !== this.outboxScope;
+                        continue;
+                    }
+                    this.publishIntents(entries.map(outboxIntentFromEntry));
+                }
+            }
+            finally {
+                this.intentsRefreshRunning = false;
+            }
+        })();
+    }
+    publishIntents(next) {
+        if (sameIntents(this.intentsSnapshotValue, next))
+            return;
+        this.intentsSnapshotValue = next;
+        for (const listener of this.intentListeners) {
+            try {
+                listener();
+            }
+            catch { /* A listener must not break delivery. */ }
+        }
+    }
     async restoreLocalSession(scope, generation) {
         if (!this.localBinding || !scope.startsWith("identity\u0000"))
             return;
@@ -269,38 +575,163 @@ 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)).filter(outboxEntryIsLive);
+                    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);
+            this.refreshIntents();
+            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 () => {
@@ -311,24 +742,61 @@ export class GonvexClient {
     }
     reportLocalRejection(reducerId, path, error) {
         const message = reducerErrorMessage(error);
-        for (const listener of this.reducerRejectionHandlers)
-            listener({ reducerId, path, error: message });
+        for (const listener of this.reducerRejectionHandlers) {
+            try {
+                listener({ reducerId, path, error: message, errorClass: "rejected" });
+            }
+            catch { /* A listener must not break delivery. */ }
+        }
+    }
+    rebaseLocalEntries(afterRejection = false) {
+        return this.coordinateOutbox("intent", () => this.rebaseLocalEntriesLocked(afterRejection));
     }
-    async rebaseLocalEntries() {
+    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);
+        // Rejected records keep their payload for the UI but are never predicted.
+        // Failed (parked) intents stay predicted until retried or discarded.
+        const entries = (await this.reducerOutbox.list(scope)).filter(outboxEntryIsLive);
+        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 +812,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 +839,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 +851,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 +894,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)).filter(outboxEntryIsLive);
+            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 +949,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 +972,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,19 +1018,33 @@ 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. */
+    /** Number of reducers still queued for delivery (excludes failed and rejected intents). */
     async outboxCount() {
         await this.outboxReady;
         return this.reducerOutbox.count(this.outboxScope);
@@ -803,8 +1390,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 +1535,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 +1572,8 @@ export class GonvexClient {
             this.outboxDrainTimer = undefined;
         }
         this.unsubscribeOutbox();
+        this.unsubscribePeerOutbox?.();
+        this.unsubscribePeerReplica?.();
         this.unsubscribeBrowserOnline?.();
         this.handlers.clear();
         this.querySubscriptions.clear();
@@ -999,6 +1591,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 +1928,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 +1940,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 +1985,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 +2006,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 +2074,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 +2095,7 @@ export class GonvexClient {
                 isUpToDate: this.replicaSubscriptions.get(key)?.isUpToDate === true,
             }),
             onUpdate(handler) {
+                start();
                 if (releaseTimer) {
                     clearTimeout(releaseTimer);
                     releaseTimer = undefined;
@@ -1492,9 +2113,7 @@ export class GonvexClient {
                         releaseTimer = undefined;
                         if (updateHandlers.size > 0)
                             return;
-                        unsubscribeTransport();
-                        unsubscribeReplica();
-                        unsubscribeScope();
+                        stop?.();
                     }, 0);
                 };
             },
@@ -1505,7 +2124,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 +2144,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 +2223,7 @@ export class GonvexClient {
                 return snapshotResult;
             },
             onUpdate(handler) {
+                start();
                 if (releaseTimer) {
                     clearTimeout(releaseTimer);
                     releaseTimer = undefined;
@@ -1609,9 +2241,7 @@ export class GonvexClient {
                         releaseTimer = undefined;
                         if (updateHandlers.size > 0)
                             return;
-                        unsubscribeQuery();
-                        unsubscribeReplica();
-                        unsubscribeScope();
+                        stop?.();
                     }, 0);
                 };
             },
@@ -1656,7 +2286,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 +2297,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 +2321,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 +2475,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 +2529,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,
             };
@@ -1998,6 +2640,9 @@ export class GonvexClient {
             ? this.restoreOutbox(scope, generation)
             : this.restoreLocalSession(scope, generation);
         this.outboxReady = ready;
+        // Never show the previous identity's intents under the new one.
+        this.publishIntents([]);
+        this.refreshIntents();
         return ready;
     }
     async activateReplicaDirective(directive) {
@@ -2031,7 +2676,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 +2703,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
@@ -2076,6 +2721,8 @@ export class GonvexClient {
         for (const entry of entries) {
             if (entry.localExecution && this.localExecutor)
                 continue;
+            if (!outboxEntryIsLive(entry))
+                continue;
             if (entry.state === "committed" && (entry.patches?.length ?? 0) === 0) {
                 await this.reducerOutbox.ack(entry.id);
                 continue;
@@ -2092,11 +2739,15 @@ export class GonvexClient {
         // 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.
+        this.refreshIntents();
         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);
     }
@@ -2117,95 +2768,185 @@ export class GonvexClient {
     }
     async drainOutbox() {
         await this.outboxReady;
-        if (this.drainingOutbox
-            || this.manuallyClosed
-            || !this.canSendReducerNow())
+        if (this.drainingOutbox) {
+            // The running drain may already be past the entry this wake-up is for
+            // (for example a short backoff timer firing before the drain returned).
+            this.outboxDrainRequested = true;
+            return;
+        }
+        if (this.manuallyClosed || !this.canSendReducerNow())
             return;
         const drainScope = this.outboxScope;
         this.drainingOutbox = true;
+        this.outboxDrainRequested = false;
         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);
-                    return;
-                }
-                if (!this.canSendReducerNow()) {
-                    await this.reducerOutbox.markPending(entry.id);
+            await this.coordinateOutbox("delivery", async () => {
+                if (this.manuallyClosed || drainScope !== this.outboxScope || !this.canSendReducerNow())
                     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();
-                        });
+                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());
+                        // A concurrent discard (this or another tab) fences the entry; a
+                        // refused transition means it must not be sent.
+                        if (next && (await this.reducerOutbox.markInflight(next.id)) === false)
+                            return null;
+                        return next;
+                    });
+                    if (entry === null)
+                        continue;
+                    if (!entry) {
+                        await this.scheduleNextOutboxAttempt(scope);
+                        return;
                     }
-                    else if ((entry.patches?.length ?? 0) > 0) {
-                        await this.settleOptimisticReducer(entry.idempotencyKey);
+                    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)) {
+                    if ((await this.reducerOutbox.markInflight(entry.id)) === false)
+                        continue;
+                    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);
+                        this.unauthenticatedRetries = 0;
+                        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) {
+                        const disposition = deliveryErrorClass(error);
+                        if (disposition === "rejected") {
+                            // Keep today's rollback and rebase, but record the rejection
+                            // durably instead of deleting the intent without a trace.
+                            if (entry.localExecution && this.localExecutor) {
+                                await this.inLocalLane(async () => {
+                                    await this.reducerOutbox.reject(entry.id, reducerErrorMessage(error));
+                                    if (scope === this.outboxScope) {
+                                        await this.rebaseLocalEntries(true);
+                                        this.reportLocalRejection(entry.idempotencyKey, entry.path, error);
+                                    }
+                                });
+                            }
+                            else {
+                                this.optimisticReducerIds.delete(entry.idempotencyKey);
+                                this.optimisticOutboxEntryIds.delete(entry.idempotencyKey);
+                                this.replica.rejectCommand(entry.idempotencyKey);
+                                await this.reducerOutbox.reject(entry.id, reducerErrorMessage(error));
+                                if (scope === this.outboxScope)
+                                    this.reportLocalRejection(entry.idempotencyKey, entry.path, error);
+                            }
+                            continue;
+                        }
+                        const outcome = await this.recordDeliveryFailure(entry, error, disposition);
+                        // A parked intent keeps its prediction but no longer blocks the
+                        // chain; later intents proceed and the server validates them.
+                        if (outcome === "parked")
+                            continue;
+                        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;
-            if (!this.manuallyClosed && drainScope !== this.outboxScope) {
+            this.scheduleLocalReplay();
+            const requested = this.outboxDrainRequested;
+            this.outboxDrainRequested = false;
+            if (!this.manuallyClosed && (drainScope !== this.outboxScope || requested)) {
                 void this.drainOutbox();
             }
         }
     }
+    /**
+     * Record a non-rejection delivery failure and arm the next attempt.
+     * - update_required: keep the intent pending and stop for an app update.
+     * - unauthenticated: keep the intent, re-authenticate, retry with backoff
+     *   that never spends the retry budget.
+     * - network: connectivity loss; retried on reconnect without spending budget.
+     * - transient (and timeouts): exponential backoff, parked as `failed` once
+     *   the retry budget is spent.
+     */
+    async recordDeliveryFailure(entry, error, disposition) {
+        const message = reducerErrorMessage(error);
+        if (disposition === "update_required") {
+            await this.reducerOutbox.fail(entry.id, message, { errorClass: disposition, countAttempt: false, delayMs: 0 });
+            this.requireClientUpdate(message);
+            return "update_required";
+        }
+        if (disposition === "unauthenticated") {
+            const delay = outboxBackoffMs(this.unauthenticatedRetries++, this.outboxRetry.maxBackoffMs);
+            await this.reducerOutbox.fail(entry.id, message, { errorClass: disposition, countAttempt: false, delayMs: delay });
+            this.requestReauthentication();
+            this.scheduleOutboxDrain(delay);
+            return "retrying";
+        }
+        const counted = disposition === "transient";
+        const updated = await this.reducerOutbox.fail(entry.id, message, {
+            errorClass: disposition,
+            countAttempt: counted,
+            maxAttempts: this.outboxRetry.maxAttempts,
+            maxBackoffMs: this.outboxRetry.maxBackoffMs,
+            ...(counted ? {} : { delayMs: 1_000 }),
+        });
+        if (updated && updated.state === "failed")
+            return "parked";
+        const delay = updated ? Math.max(0, updated.nextAttemptAt - Date.now()) : DEFAULT_OUTBOX_MAX_BACKOFF_MS;
+        this.scheduleOutboxDrain(delay);
+        return "retrying";
+    }
+    /**
+     * Arm a timer for the earliest backed-off entry. Timer clocks and
+     * `Date.now()` can disagree by a millisecond, so a wake-up may find its
+     * entry not quite due; without this the queue would wait for an unrelated
+     * event to resume.
+     */
+    async scheduleNextOutboxAttempt(scope) {
+        const now = Date.now();
+        let next = Infinity;
+        for (const entry of await this.reducerOutbox.list(scope)) {
+            if (entry.state === "pending" && entry.nextAttemptAt > now)
+                next = Math.min(next, entry.nextAttemptAt);
+        }
+        if (Number.isFinite(next) && scope === this.outboxScope)
+            this.scheduleOutboxDrain(next - now + 1);
+    }
+    /** Re-send auth on the open socket so a lost tenant session is restored. */
+    requestReauthentication() {
+        if (this.manuallyClosed || this.authInFlight || this.socket?.readyState !== WebSocket.OPEN)
+            return;
+        if (!this.auth.project && !this.auth.tenant && !this.auth.token && !this.auth.fetchToken)
+            return;
+        this.sendAuth(false);
+    }
     scheduleOutboxDrain(delay) {
         if (this.manuallyClosed)
             return;
@@ -2245,7 +2986,6 @@ export class GonvexClient {
         }
         this.directOutboxReducerIds.add(reducerId);
         let entryId;
-        let entryAttempts = 0;
         try {
             const scope = this.outboxScope;
             const entry = await this.reducerOutbox.enqueue({
@@ -2258,7 +2998,6 @@ export class GonvexClient {
                 state: "inflight",
             });
             entryId = entry.id;
-            entryAttempts = entry.attempts;
             if (this.manuallyClosed) {
                 await this.reducerOutbox.ack(entry.id);
                 throw new GonvexClientError(`Gonvex client was closed before reducer ${ref.path} could be sent.`, { code: "closed", path: ref.path, operation: "reducer" });
@@ -2286,14 +3025,13 @@ export class GonvexClient {
             return result;
         }
         catch (error) {
-            if (isQueueableReducerError(error) && options.offline === "queue") {
+            const disposition = deliveryErrorClass(error);
+            if (disposition !== "rejected" && options.offline === "queue") {
                 const queuedEntryId = this.optimisticOutboxEntryIds.get(reducerId) ?? entryId;
                 if (queuedEntryId !== undefined) {
-                    await this.reducerOutbox.fail(queuedEntryId, reducerErrorMessage(error));
-                    // `fail` deliberately records backoff, but it does not own the
-                    // client's timer. The foreground queueable path must schedule the
-                    // next deterministic drain just like the background drain path.
-                    this.scheduleOutboxDrain(Math.min(30_000, 1_000 * (2 ** (entryAttempts + 1))));
+                    // Records backoff (or parks the entry) and arms the client's timer,
+                    // exactly like the background drain path.
+                    await this.recordDeliveryFailure({ id: queuedEntryId }, error, disposition);
                 }
                 return { status: "queued", reducerId };
             }
@@ -2514,8 +3252,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);
@@ -2539,7 +3280,11 @@ export class GonvexClient {
                 if (kind === "reducer" && message.type === "reducer.error") {
                     settle();
                     this.emitTelemetryFromCall(kind, id, ref.path, "error", clientSentAtMs, message.trace, message.error);
-                    reject(new GonvexClientError(message.error, { code: "server", path: ref.path, operation: kind }));
+                    const errorClass = reducerErrorClassFromMessage(message);
+                    reject(new GonvexClientError(message.error, {
+                        code: "server", path: ref.path, operation: kind,
+                        ...(errorClass ? { errorClass, retryable: message.retryable ?? (errorClass === "transient" || errorClass === "unauthenticated") } : {}),
+                    }));
                 }
                 if (kind === "action" && message.type === "action.result") {
                     const complete = () => {
@@ -3160,15 +3905,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;
@@ -3178,9 +3941,96 @@ function countPendingCalls(calls, kind) {
     }
     return count;
 }
-function isQueueableReducerError(error) {
-    return error instanceof GonvexClientError
-        && (error.code === "disconnected" || error.code === "timeout");
+/**
+ * How the outbox treats one failed delivery. Runtimes before
+ * 0.5.2-staging.15 send no class: their server errors stay rejections, as
+ * before, except the two cases the legacy runtime could only express in prose.
+ */
+function deliveryErrorClass(error) {
+    if (!(error instanceof GonvexClientError))
+        return "transient";
+    switch (error.code) {
+        case "server": return error.errorClass ?? "rejected";
+        case "timeout": return "transient";
+        default: return "network";
+    }
+}
+const legacyUnauthenticatedReducerError = "authenticate with an active tenant before calling a Reducer";
+function reducerErrorClassFromMessage(message) {
+    if (message.class === "rejected" || message.class === "transient" || message.class === "update_required" || message.class === "unauthenticated") {
+        return message.class;
+    }
+    // Legacy runtimes: the only structured signals were these literal messages.
+    if (/STALE_REDUCER_ARTIFACT|CLIENT_UPDATE_REQUIRED/.test(message.error))
+        return "update_required";
+    if (message.error === legacyUnauthenticatedReducerError)
+        return "unauthenticated";
+    return undefined;
+}
+function positiveOr(value, fallback) {
+    return typeof value === "number" && value > 0 ? value : fallback;
+}
+function summarizeArgs(args) {
+    let text;
+    try {
+        text = JSON.stringify(args) ?? "";
+    }
+    catch {
+        text = String(args);
+    }
+    return text.length > 160 ? `${text.slice(0, 157)}...` : text;
+}
+function outboxIntentFromEntry(entry) {
+    const entities = new Map();
+    for (const patch of entry.patches ?? []) {
+        const entity = patch.entity ?? patch.collection;
+        if (!entity)
+            continue;
+        entities.set(`${entity}\u0000${patch.rowId}`, { entity, id: patch.rowId });
+    }
+    return {
+        id: entry.idempotencyKey,
+        entryId: entry.id,
+        reducer: entry.path,
+        state: entry.state,
+        attempts: entry.attempts,
+        ...(entry.lastError !== undefined ? { lastError: entry.lastError } : {}),
+        ...(entry.lastErrorClass ? { errorClass: entry.lastErrorClass } : {}),
+        createdAt: entry.createdAt,
+        nextAttemptAt: entry.nextAttemptAt,
+        ...(entry.settledAt !== undefined ? { settledAt: entry.settledAt } : {}),
+        args: entry.args,
+        argsSummary: summarizeArgs(entry.args),
+        entities: [...entities.values()],
+    };
+}
+function sameIntents(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        const a = left[index], b = right[index];
+        if (a.id !== b.id || a.entryId !== b.entryId || a.state !== b.state || a.attempts !== b.attempts
+            || a.lastError !== b.lastError || a.errorClass !== b.errorClass || a.nextAttemptAt !== b.nextAttemptAt
+            || a.settledAt !== b.settledAt || a.entities.length !== b.entities.length
+            || a.entities.some((entity, position) => entity.entity !== b.entities[position].entity || entity.id !== b.entities[position].id))
+            return false;
+    }
+    return true;
+}
+/** Row status from a list of intents: failed > rejected > syncing. */
+export function entityStatusFromIntents(intents, entity, id) {
+    let status;
+    for (const intent of intents) {
+        if (!intent.entities.some((candidate) => candidate.entity === entity && candidate.id === id))
+            continue;
+        if (intent.state === "failed")
+            return "failed";
+        if (intent.state === "rejected")
+            status = "rejected";
+        else if (intent.state !== "committed" && status === undefined)
+            status = "syncing";
+    }
+    return status;
 }
 function reducerErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -3202,6 +4052,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 +4075,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 +4124,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 +4391,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