@gonvex/client 0.5.2-staging.2 → 0.5.2-staging.21

package/dist/index.js

@@ -1,15 +1,20 @@
-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";
 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.
@@ -39,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),
@@ -49,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(),
@@ -89,14 +96,30 @@ 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;
     }
 }
+/** Default row bound of `localDependencyResidency: "bounded"`. */
+export const DEFAULT_LOCAL_DEPENDENCY_RESIDENT_MAX_ROWS = 1000;
+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;
@@ -115,10 +138,34 @@ 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();
+    localFallbackHandlers = new Set();
+    residentDependencyTables;
+    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 = [];
@@ -128,6 +175,7 @@ export class GonvexClient {
     querySubscribeFlushTimer;
     serverCapabilities = {};
     activeArtifactHashValue = "";
+    publicTenant;
     auth = {};
     authInFlight = false;
     // Only the newest auth frame may change socket authorization. The runtime
@@ -145,6 +193,7 @@ export class GonvexClient {
     // or a fresh send cycle starts, so a bad token can't refresh-loop forever.
     authRetriedAfterError = false;
     authErrorHandlers = new Set();
+    developerCredentialHandlers = new Set();
     managedAuthAttempt;
     telemetryEnabled = false;
     querySubscriptionRetentionMs;
@@ -164,11 +213,19 @@ export class GonvexClient {
     hasAuthoritativeReplicaScope = false;
     replicaReady = Promise.resolve();
     replicaFrames = Promise.resolve();
+    queuedReplicaWatermark;
     processedReplicaWatermarkRevision = 0;
-    pendingReplicaTransactions = [];
+    pendingReplicaFrames = [];
     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;
@@ -180,20 +237,68 @@ export class GonvexClient {
     pendingCalls = new Map();
     connectionStateHandlers = new Set();
     supportCommandHandlers = new Set();
+    pendingNativeErrors = [];
     isWebSocketConnected = false;
     hasEverConnected = false;
     connectionCount = 0;
     timeouts;
+    clientContract;
+    updateRequiredHandler;
+    updateRequired = false;
+    lastOnlineAtMs = 0;
     constructor(url, options = {}) {
         this.url = url;
+        if (options.public) {
+            if (!options.public.tenant.trim() || !options.project?.trim())
+                throw new Error("Public connections require project and tenant");
+            if (options.token || options.fetchToken || options.identity || options.tenant)
+                throw new Error("Public connections cannot include session credentials or a separate tenant");
+            this.publicTenant = options.public.tenant.trim();
+            options = { ...options, clientContract: options.clientContract ?? options.localRuntime?.clientContract, tenant: this.publicTenant, localRuntime: undefined, localReplica: undefined, outbox: { enabled: false }, telemetry: false };
+        }
+        this.clientContract = options.clientContract ?? options.localRuntime?.clientContract;
+        this.updateRequiredHandler = options.onUpdateRequired;
+        this.localBinding = options.localRuntime;
+        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.residentDependencyTables = residentLocalDependencyTables(options.localRuntime, options.localDependencyResidency);
+        if (options.onLocalExecutionFallback)
+            this.localFallbackHandlers.add(options.onLocalExecutionFallback);
+        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) {
+            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") {
@@ -214,7 +319,7 @@ export class GonvexClient {
         this.outboxScope = initialScope;
         this.replicaScope = ["awaiting-server-scope", this.url, this.outboxEphemeralScope].join("\u0000");
         this.outboxScopeGeneration += 1;
-        this.replicaReady = this.replica.activateScope(this.replicaScope, true);
+        this.setReplicaReady(this.replica.activateScope(this.replicaScope, true));
         this.outboxReady = Promise.resolve();
         this.timeouts = {
             queryTimeoutMs: options.timeouts?.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
@@ -229,6 +334,730 @@ export class GonvexClient {
                 transport: (type, payload) => this.sendNativeError(type, payload),
             });
         }
+        if (this.localBinding)
+            this.setOutboxReady(this.restoreLocalSession(initialScope, this.outboxScopeGeneration));
+    }
+    /**
+     * 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);
+    }
+    /**
+     * Observe every point where a locally executing Reducer degrades to a
+     * queued-only intent (no local result). The intent is still durable and is
+     * delivered to the server; this exists so apps can log and fix the missing
+     * local data. Returns an unsubscribe function.
+     */
+    onLocalExecutionFallback(listener) {
+        this.localFallbackHandlers.add(listener);
+        return () => { this.localFallbackHandlers.delete(listener); };
+    }
+    reportLocalFallback(path, intentId, phase, error) {
+        if (!this.localFallbackHandlers.size)
+            return;
+        const incomplete = error instanceof Error && error.name === "IncompleteReplicaError";
+        const table = incomplete
+            ? error.read?.table ?? /^Local replica for (.+?) is incomplete;/.exec(error.message)?.[1]
+            : undefined;
+        const event = {
+            path, intentId, phase, reason: incomplete ? "incompleteReplica" : "localError",
+            ...(table ? { table } : {}),
+            error: error instanceof Error ? error.message : String(error),
+        };
+        for (const listener of this.localFallbackHandlers) {
+            try {
+                listener(event);
+            }
+            catch { /* A listener must not break delivery. */ }
+        }
+    }
+    /** 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.pendingReplicaFrames.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;
+        const saved = await this.localStorage?.loadSession?.(scope);
+        if (!saved || generation !== this.outboxScopeGeneration || scope !== this.outboxScope || this.hasAuthoritativeReplicaScope)
+            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(tables) {
+        if (!this.localBinding)
+            return;
+        const needed = new Set(tables);
+        for (const reference of this.localBinding.collections ?? []) {
+            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 rows = this.replica.captureExecutionRows(includePending);
+        const tables = {};
+        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 () => {
+                await this.outboxReady;
+                await this.inLocalLane(() => this.rebaseLocalEntries());
+            })().catch(() => undefined).finally(() => { this.localReplayScheduled = false; });
+        });
+    }
+    reportLocalRejection(reducerId, path, error) {
+        const message = reducerErrorMessage(error);
+        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 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;
+        // 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.executeLocal(entry.path, entry.args, snapshot, execution, replayPatches);
+                    patches = transaction.patches;
+                    if (scope !== this.outboxScope || replicaScope !== this.replicaScope)
+                        return;
+                }
+                catch (error) {
+                    // Re-execution is a prediction. Only an authoritative server rejection
+                    // removes a durable intent; missing data or local validation can make
+                    // its predicted transaction unavailable without rejecting the intent.
+                    if (patches.length && scope === this.outboxScope && replicaScope === this.replicaScope)
+                        this.reportLocalFallback(entry.path, entry.idempotencyKey, "replay", error);
+                    patches = [];
+                }
+                if (scope !== this.outboxScope || replicaScope !== this.replicaScope)
+                    return;
+                // Storage failures must abort rebasing, never masquerade as rejection.
+                await this.reducerOutbox.updateLocal(entry.id, patches, execution);
+            }
+            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.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.replaceLocalPredictions(commands);
+        }
+        finally {
+            this.replacingLocal = false;
+        }
+        this.optimisticReducerIds.clear();
+        this.optimisticOutboxEntryIds.clear();
+        for (const entry of entries) {
+            this.optimisticOutboxEntryIds.set(entry.idempotencyKey, entry.id);
+        }
+        for (const command of commands)
+            if (command.patches.length)
+                this.optimisticReducerIds.add(command.commandId);
+    }
+    async runLocalReducer(ref, args) {
+        args = structuredClone(args);
+        const admittedGeneration = this.outboxScopeGeneration;
+        await this.outboxReady;
+        await this.replicaReady;
+        if (!this.localExecutor || !this.localBinding)
+            throw new Error("This reducer requires the generated Gonvex client with local execution enabled");
+        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)
+                throw new Error("Restore an authenticated local session before editing offline");
+            if (this.manuallyClosed)
+                throw new Error("Gonvex client is closed");
+            if (this.updateRequired)
+                throw new Error("Application update required before editing");
+            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;
+            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. Preparation proves resident
+            // coverage, even when a published commit invalidates its result while
+            // acquiring the lock. Re-execute against the latest atomic resident
+            // snapshot below; only known peer changes or committed shared intents
+            // require synchronizing storage first.
+            const canExecuteResident = preparedResult
+                && !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 (!canExecuteResident && !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;
+            let fallback;
+            try {
+                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")
+                    throw error;
+                fallback = error;
+            }
+            if (scope !== this.outboxScope || execution.scope !== this.replicaScope)
+                throw new GonvexClientError("Session changed during local reducer execution", { code: "superseded" });
+            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
+                    // written by a previous intent, not only overlapping write patches.
+                    entityKeys: ["__gonvex_local_intents"], patches, localExecution: execution,
+                });
+                if (scope !== this.outboxScope || execution.scope !== this.replicaScope) {
+                    throw new GonvexClientError("Session changed while persisting local reducer", { code: "superseded" });
+                }
+                this.optimisticOutboxEntryIds.set(reducerId, entry.id);
+                this.replacingLocal = true;
+                try {
+                    this.addOptimisticReducer(reducerId, patches);
+                }
+                finally {
+                    this.replacingLocal = false;
+                }
+                if (!transaction) {
+                    this.reportLocalFallback(ref.path, reducerId, "call", fallback);
+                    return { status: "queued", reducerId };
+                }
+                return transaction.result;
+            }
+            catch (error) {
+                this.optimisticReducerIds.delete(reducerId);
+                this.replica.rejectCommand(reducerId);
+                throw error;
+            }
+            finally {
+                this.directOutboxReducerIds.delete(reducerId);
+                // 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() {
@@ -245,19 +1074,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);
@@ -374,7 +1217,24 @@ export class GonvexClient {
             this.authErrorHandlers.delete(handler);
         };
     }
+    /**
+     * Subscribe to rotated developer-mode reconnect credentials. The runtime
+     * consumes each developer credential when it accepts a connection and
+     * returns a single-use successor; the client already uses that successor
+     * for its own reconnects. Auth providers subscribe so they can keep the
+     * newest credential in tab-scoped storage and resume developer mode after a
+     * page reload. The value is a secret: never log it or put it in a URL.
+     */
+    onDeveloperCredential(handler) {
+        this.developerCredentialHandlers.add(handler);
+        return () => {
+            this.developerCredentialHandlers.delete(handler);
+        };
+    }
     applyAuth(auth) {
+        if (this.publicTenant && (auth.token || auth.fetchToken || auth.identity || auth.tenant !== undefined && auth.tenant !== this.publicTenant || auth.project !== undefined && auth.project !== this.auth.project)) {
+            throw new Error("Public connection scope is fixed; create another client to sign in or change tenants");
+        }
         const nextAuth = { ...this.auth, ...auth };
         const tokenScopeChanged = hasOwn(auth, "token")
             && auth.token !== this.auth.token
@@ -388,7 +1248,7 @@ export class GonvexClient {
             || (hasOwn(auth, "identity") && !sameAuthTokenIdentity(this.auth, nextAuth));
         if (scopeMayChange) {
             this.pendingMessages.length = 0;
-            this.pendingReplicaTransactions.length = 0;
+            this.pendingReplicaFrames.length = 0;
             this.rejectPendingCalls((call) => new GonvexClientError(`Authentication scope changed while waiting for ${call.kind} ${call.path}`, { code: "superseded", path: call.path, operation: call.kind }));
             for (const query of this.oneShotQueries.values()) {
                 if (query.timeoutTimer)
@@ -416,12 +1276,20 @@ export class GonvexClient {
         }
     }
     connect() {
+        if (this.updateRequired)
+            return;
         if (this.socket && this.socket.readyState <= WebSocket.OPEN)
             return;
         const isReconnect = this.socket !== undefined;
         this.manuallyClosed = false;
         const generation = ++this.socketGeneration;
-        const socket = new WebSocket(this.url);
+        let transportUrl = this.url;
+        if (this.publicTenant) {
+            const publicUrl = new URL(this.url);
+            publicUrl.searchParams.set("public", "1");
+            transportUrl = publicUrl.toString();
+        }
+        const socket = new WebSocket(transportUrl);
         this.socket = socket;
         socket.addEventListener("open", () => {
             if (this.socket !== socket)
@@ -461,7 +1329,7 @@ export class GonvexClient {
             // drop them too — flushing them after reconnect would fire writes whose
             // callers already saw a rejection.
             this.pendingMessages.length = 0;
-            this.pendingReplicaTransactions.length = 0;
+            this.pendingReplicaFrames.length = 0;
             // Reducers/actions must fail closed on transport loss: silently
             // replaying a non-idempotent write after reconnect is unsafe, and
             // leaving the promise pending hangs the caller forever.
@@ -504,6 +1372,10 @@ export class GonvexClient {
                 }
                 return;
             }
+            if (message.type === "client.updateRequired") {
+                this.requireClientUpdate(message.reason);
+                return;
+            }
             if (message.type === "system.reload") {
                 if (typeof message.artifactHash === "string") {
                     this.activeArtifactHashValue = message.artifactHash;
@@ -520,7 +1392,7 @@ export class GonvexClient {
                     // subscription. Rotate their routing IDs immediately so delayed
                     // Replica errors from that discarded scope cannot reach current
                     // React listeners.
-                    this.pendingReplicaTransactions.length = 0;
+                    this.pendingReplicaFrames.length = 0;
                     this.quarantineReplicaScope();
                     this.activeAuthFrameId = undefined;
                     // If credentials are already being revalidated, that queued auth
@@ -537,7 +1409,7 @@ export class GonvexClient {
                         this.sendAuth(true, { useFetcher: false });
                         return;
                     }
-                    const fetcher = this.auth.fetchToken;
+                    const fetcher = this.publicTenant ? undefined : this.auth.fetchToken;
                     if (fetcher) {
                         this.authInFlight = true;
                         this.authRetriedAfterError = true;
@@ -577,6 +1449,8 @@ export class GonvexClient {
                     this.activeAuthFrameId = message.id;
                 else
                     this.activeAuthFrameId = undefined;
+                if (message.type === "auth.result")
+                    this.flushPendingNativeErrors();
                 if (this.authWatchdogTimer) {
                     clearTimeout(this.authWatchdogTimer);
                     this.authWatchdogTimer = undefined;
@@ -584,18 +1458,27 @@ export class GonvexClient {
                 if (message.type === "auth.result") {
                     const reauthenticatedSameSocket = this.authenticatedSocketGeneration === this.socketGeneration;
                     this.authenticatedSocketGeneration = this.socketGeneration;
+                    this.lastOnlineAtMs = Date.now();
                     this.activeArtifactHashValue = artifactHashFromAuthResult(message.result) ?? this.activeArtifactHashValue;
                     const developerSessionToken = developerSessionTokenFromAuthResult(message.result);
                     if (developerSessionToken) {
-                        // The activation token is single-use. Keep its rotating successor
-                        // only in process memory and use it for the next reconnect.
+                        // The activation token is single-use. Use its rotating successor
+                        // for the next reconnect, and hand it to the provider that owns
+                        // developer mode so a reload can resume the same grant.
                         this.auth = { ...this.auth, token: developerSessionToken, fetchToken: undefined };
+                        for (const handler of Array.from(this.developerCredentialHandlers))
+                            handler(developerSessionToken);
                     }
                     this.authRetriedAfterError = false;
                     const directive = replicaDirectiveFromAuthResult(message.result);
+                    const localIdentity = localIdentityFromAuthResult(message.result);
+                    if (localIdentity) {
+                        this.localIdentity = localIdentity;
+                        void this.localExecutor?.ready.catch(() => undefined);
+                    }
                     if (!directive) {
                         this.authInFlight = false;
-                        if (!this.auth.tenant) {
+                        if (!this.auth.tenant || this.publicTenant) {
                             this.resumeQuerySubscriptions(reauthenticatedSameSocket);
                             this.settleManagedAuthAttempt(message.id);
                         }
@@ -612,12 +1495,18 @@ export class GonvexClient {
                     }
                     void this.activateReplicaDirective(directive)
                         .then(() => this.activateOutboxScope())
+                        .then(async () => {
+                        if (localIdentity && this.localBinding)
+                            await this.localStorage?.saveSession?.(this.outboxScope, {
+                                directive, identity: localIdentity, artifactHash: this.activeArtifactHashValue ?? this.localBinding.artifactHash, lastOnlineAtMs: this.lastOnlineAtMs,
+                            });
+                    })
                         .then(() => {
                         // The accepted server identity is not usable until its durable
                         // Replica partition has been activated locally. Only now may
                         // tenant calls and subscriptions leave the client.
                         this.authInFlight = false;
-                        this.drainPendingReplicaTransactions();
+                        this.drainPendingReplicaFrames();
                         // Authentication is replaced in-place on the same socket during
                         // normal token rotation. The runtime clears its subscription
                         // maps for every accepted auth frame, so same-generation Live
@@ -632,7 +1521,7 @@ export class GonvexClient {
                     })
                         .catch((error) => {
                         this.authInFlight = false;
-                        this.pendingReplicaTransactions.length = 0;
+                        this.pendingReplicaFrames.length = 0;
                         this.settleManagedAuthAttempt(message.id, error instanceof Error ? error.message : "Runtime returned an invalid Local Replica scope");
                         this.rejectReplicaDirective(error);
                         this.flushPendingMessages();
@@ -641,7 +1530,7 @@ export class GonvexClient {
                 }
                 else {
                     this.authInFlight = false;
-                    this.pendingReplicaTransactions.length = 0;
+                    this.pendingReplicaFrames.length = 0;
                     const fetcher = this.auth.fetchToken;
                     if (fetcher && !this.authRetriedAfterError) {
                         // The installed token was rejected — typically expired while the
@@ -671,7 +1560,7 @@ export class GonvexClient {
                 // Replica frames carry no tenant/scope field. During auth renewal we
                 // cannot safely attribute a late frame to either side of the switch.
                 if (this.authInFlight) {
-                    this.pendingReplicaTransactions.push(message);
+                    this.pendingReplicaFrames.push(message);
                     return;
                 }
                 this.enqueueReplicaTransaction(message);
@@ -683,7 +1572,11 @@ export class GonvexClient {
                     // stream. Keep both on the same client queue so a watermark cannot
                     // advance the cursor past a transaction that was received first but
                     // has not finished applying to durable Local Replica storage yet.
-                    this.enqueueReplicaFrame(() => this.handleReplicaWatermark(message.revision));
+                    if (this.authInFlight) {
+                        this.pendingReplicaFrames.push(message);
+                        return;
+                    }
+                    this.enqueueReplicaWatermark(message.revision);
                 }
                 return;
             }
@@ -725,6 +1618,11 @@ export class GonvexClient {
     }
     close() {
         this.manuallyClosed = true;
+        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)) {
             void this.reducerOutbox.clear(this.outboxScope);
@@ -760,12 +1658,15 @@ export class GonvexClient {
             this.outboxDrainTimer = undefined;
         }
         this.unsubscribeOutbox();
+        this.unsubscribePeerOutbox?.();
+        this.unsubscribePeerReplica?.();
         this.unsubscribeBrowserOnline?.();
         this.handlers.clear();
         this.querySubscriptions.clear();
         this.replicaSubscriptions.clear();
         this.sessionScopeHandlers.clear();
         this.authErrorHandlers.clear();
+        this.developerCredentialHandlers.clear();
         // Invalidate any token fetch still in flight so its resolve can't touch
         // the closed client's caches.
         this.authFetchGeneration += 1;
@@ -777,6 +1678,10 @@ 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);
         if (!socket)
             return;
         socket.close();
@@ -1110,7 +2015,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);
@@ -1120,10 +2027,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));
                     }
                 });
             }
@@ -1161,12 +2072,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;
@@ -1178,45 +2093,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: () => {
@@ -1234,7 +2161,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,
@@ -1250,6 +2182,7 @@ export class GonvexClient {
                 isUpToDate: this.replicaSubscriptions.get(key)?.isUpToDate === true,
             }),
             onUpdate(handler) {
+                start();
                 if (releaseTimer) {
                     clearTimeout(releaseTimer);
                     releaseTimer = undefined;
@@ -1267,9 +2200,7 @@ export class GonvexClient {
                         releaseTimer = undefined;
                         if (updateHandlers.size > 0)
                             return;
-                        unsubscribeTransport();
-                        unsubscribeReplica();
-                        unsubscribeScope();
+                        stop?.();
                     }, 0);
                 };
             },
@@ -1280,7 +2211,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;
@@ -1300,39 +2231,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)
@@ -1367,6 +2310,7 @@ export class GonvexClient {
                 return snapshotResult;
             },
             onUpdate(handler) {
+                start();
                 if (releaseTimer) {
                     clearTimeout(releaseTimer);
                     releaseTimer = undefined;
@@ -1384,9 +2328,7 @@ export class GonvexClient {
                         releaseTimer = undefined;
                         if (updateHandlers.size > 0)
                             return;
-                        unsubscribeQuery();
-                        unsubscribeReplica();
-                        unsubscribeScope();
+                        stop?.();
                     }, 0);
                 };
             },
@@ -1431,7 +2373,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;
@@ -1442,12 +2384,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",
@@ -1458,13 +2408,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,
             };
@@ -1518,12 +2466,34 @@ export class GonvexClient {
         }
         this.emitReplicaMessage(subscription, message, scope);
     }
-    enqueueReplicaFrame(operation) {
+    enqueueReplicaFrame(operation, watermark = false) {
+        // Any entity/window frame seals the adjacent watermark batch. Advancing
+        // across that barrier could make an unapplied transaction look stale.
+        if (!watermark)
+            this.queuedReplicaWatermark = undefined;
         const processing = this.replicaFrames.then(operation);
         this.replicaFrames = processing.catch(() => {
             this.replica.setFreshness("verifying");
         });
     }
+    enqueueReplicaWatermark(revision) {
+        if (!Number.isSafeInteger(revision) || revision < 0)
+            return;
+        const pending = this.queuedReplicaWatermark;
+        if (pending && pending.scope === this.replicaScope) {
+            pending.revision = Math.max(pending.revision, revision);
+            return;
+        }
+        const batch = { revision, scope: this.replicaScope };
+        this.queuedReplicaWatermark = batch;
+        this.enqueueReplicaFrame(async () => {
+            if (this.queuedReplicaWatermark === batch)
+                this.queuedReplicaWatermark = undefined;
+            if (batch.scope !== this.replicaScope)
+                return;
+            await this.handleReplicaWatermark(batch.revision);
+        }, true);
+    }
     enqueueReplicaTransaction(message) {
         const scope = this.replicaScope;
         this.enqueueReplicaFrame(async () => {
@@ -1542,10 +2512,14 @@ export class GonvexClient {
             }
         });
     }
-    drainPendingReplicaTransactions() {
-        const pending = this.pendingReplicaTransactions.splice(0);
-        for (const message of pending)
-            this.enqueueReplicaTransaction(message);
+    drainPendingReplicaFrames() {
+        const pending = this.pendingReplicaFrames.splice(0);
+        for (const message of pending) {
+            if (message.type === "replica.transaction")
+                this.enqueueReplicaTransaction(message);
+            else
+                this.enqueueReplicaWatermark(message.revision);
+        }
     }
     async acceptReplicaReady(subscription, message, hashes, hashesWereStored, scope = this.replicaScope) {
         this.clearReplicaRetry(subscription, true);
@@ -1590,12 +2564,9 @@ export class GonvexClient {
             return;
         const eligibleSignatures = [];
         for (const subscription of this.replicaSubscriptions.values()) {
-            const cursor = this.replica.getWindow(subscription.key)?.cursor;
-            if (!cursor
-                || cursor.revision >= revision
-                || !subscription.isUpToDate
+            if (!subscription.isUpToDate
                 || subscription.opening
-                || !this.replica.getWindow(subscription.key)?.hashes)
+                || !this.replica.windowCanAdvance(subscription.key, revision))
                 continue;
             eligibleSignatures.push(subscription.key);
         }
@@ -1614,9 +2585,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")
@@ -1662,7 +2639,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,
             };
@@ -1771,8 +2748,11 @@ export class GonvexClient {
         this.outboxScope = scope;
         const ready = this.hasAuthoritativeReplicaScope
             ? this.restoreOutbox(scope, generation)
-            : Promise.resolve();
-        this.outboxReady = ready;
+            : this.restoreLocalSession(scope, generation);
+        this.setOutboxReady(ready);
+        // Never show the previous identity's intents under the new one.
+        this.publishIntents([]);
+        this.refreshIntents();
         return ready;
     }
     async activateReplicaDirective(directive) {
@@ -1795,8 +2775,11 @@ export class GonvexClient {
         this.resetReplicaScopeState();
         this.replicaScope = scope;
         this.hasAuthoritativeReplicaScope = true;
-        this.replicaReady = this.replica.activateScope(scope);
+        this.setReplicaReady(this.replica.activateScope(scope));
         this.rotateSubscriptionScopes();
+        // Subscriptions follow scope rotation, so this opens each resident
+        // dependency collection once per client, from cache first when offline.
+        this.ensureLocalCollections(this.residentDependencyTables);
         const generation = this.outboxScopeGeneration;
         // Publish the recovery barrier before yielding to Replica storage. A
         // reducer may be invoked as soon as the auth result arrives, while the
@@ -1804,10 +2787,24 @@ export class GonvexClient {
         // points at the old resolved promise, that reducer can enqueue an inflight
         // row which the concurrent recovery then mistakes for an abandoned call
         // and sends a second time with the same command ID.
-        this.outboxReady = this.restoreOutbox(this.outboxScope, generation);
+        this.setOutboxReady(this.restoreOutbox(this.outboxScope, generation));
         await this.outboxReady;
     }
+    // Scope activation rejects once the replica is disposed (for example when
+    // an auth error quarantines a client that was already closed). Callers that
+    // await replicaReady still see the rejection; the stored promise itself must
+    // not surface as an unhandled rejection that kills Node processes.
+    setReplicaReady(ready) {
+        this.replicaReady = ready;
+        ready.catch(() => undefined);
+    }
+    // Outbox restore awaits replicaReady, so it rejects the same way.
+    setOutboxReady(ready) {
+        this.outboxReady = ready;
+        ready.catch(() => undefined);
+    }
     quarantineReplicaScope() {
+        this.localIdentity = undefined;
         // Keep the durable prior identity scope intact for an authorized future
         // login, but make every synchronous selector fail closed immediately.
         // The random suffix prevents a denied scope from ever restoring rows.
@@ -1819,7 +2816,7 @@ export class GonvexClient {
         this.resetReplicaScopeState();
         this.replicaScope = scope;
         this.hasAuthoritativeReplicaScope = false;
-        this.replicaReady = this.replica.activateScope(scope, true);
+        this.setReplicaReady(this.replica.activateScope(scope, true));
         this.rotateSubscriptionScopes();
     }
     rejectMissingReplicaDirective() {
@@ -1832,12 +2829,26 @@ 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
             || scope !== this.outboxScope)
             return;
         for (const entry of entries) {
+            // markCommitted follows the durable replica watermark barrier. Its
+            // transaction is already in the restored base; never predict it twice.
+            if (entry.localExecution && entry.state === "committed")
+                await this.reducerOutbox.ack(entry.id);
+        }
+        if (entries.some((entry) => entry.localExecution) && this.localExecutor) {
+            await this.inLocalLane(() => this.rebaseLocalEntries());
+        }
+        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;
@@ -1854,11 +2865,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);
     }
@@ -1878,69 +2893,195 @@ export class GonvexClient {
             await this.reducerOutbox.ack(entryId);
     }
     async drainOutbox() {
-        await this.outboxReady;
-        if (this.drainingOutbox
-            || this.manuallyClosed
-            || !this.canSendReducerNow())
+        if (this.publicTenant)
+            return;
+        // A failed restore is reported to whoever awaits the scope transition;
+        // there is nothing to drain from a scope that never became ready.
+        try {
+            await this.outboxReady;
+        }
+        catch {
+            return;
+        }
+        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.reducerOutbox.nextReady(scope, Date.now());
-                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);
-                    return;
-                }
-                await this.reducerOutbox.markInflight(entry.id);
-                if (scope !== this.outboxScope)
+            await this.coordinateOutbox("delivery", async () => {
+                if (this.manuallyClosed || drainScope !== this.outboxScope || !this.canSendReducerNow())
                     return;
-                if (!this.canSendReducerNow()) {
-                    await this.reducerOutbox.markPending(entry.id);
-                    return;
-                }
-                try {
-                    await this.call("reducer", { kind: "reducer", path: entry.path }, entry.args, this.timeouts.reducerTimeoutMs, entry.idempotencyKey, entry.idempotencyKey);
-                    await this.reducerOutbox.markCommitted(entry.id);
-                    if ((entry.patches?.length ?? 0) > 0) {
-                        await this.settleOptimisticReducer(entry.idempotencyKey);
+                if (this.sharedOutboxStore)
+                    await this.reducerOutbox.recoverInflight?.(drainScope);
+                while (!this.manuallyClosed && this.socket?.readyState === WebSocket.OPEN) {
+                    const scope = this.outboxScope;
+                    const entry = await this.inLocalLane(async () => {
+                        const next = await this.reducerOutbox.nextReady(scope, Date.now());
+                        // 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 {
-                        await this.ackOptimisticReducer(entry.idempotencyKey, entry.id);
+                    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;
                     }
-                }
-                catch (error) {
-                    if (error instanceof GonvexClientError && error.code === "server") {
-                        await this.rejectOptimisticReducer(entry.idempotencyKey, entry.id);
+                    if (!this.canSendReducerNow()) {
+                        await this.reducerOutbox.markPending(entry.id);
+                        return;
+                    }
+                    if ((await this.reducerOutbox.markInflight(entry.id)) === false)
                         continue;
+                    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);
+                        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)
+                                    await this.rebaseLocalEntries();
+                            });
+                        }
+                        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;
@@ -1952,6 +3093,13 @@ export class GonvexClient {
         }, delay);
     }
     reducer(ref, args = {}, options = {}) {
+        if (this.publicTenant) {
+            if (options.offline === "queue" || options.optimistic?.length)
+                return Promise.reject(new GonvexClientError("Public reducers are server-only and cannot queue or execute optimistically", { code: "disconnected", path: ref.path, operation: "reducer" }));
+            return this.call("reducer", ref, args, options.timeoutMs ?? this.timeouts.reducerTimeoutMs);
+        }
+        if (ref.localExecution === 1)
+            return this.runLocalReducer(ref, args);
         if (options.offline === "queue" && ref.offline?.mode !== "allowed") {
             return Promise.reject(new GonvexClientError(`Reducer ${ref.path} does not allow offline queueing.`, { code: "disconnected", path: ref.path, operation: "reducer" }));
         }
@@ -1978,7 +3126,6 @@ export class GonvexClient {
         }
         this.directOutboxReducerIds.add(reducerId);
         let entryId;
-        let entryAttempts = 0;
         try {
             const scope = this.outboxScope;
             const entry = await this.reducerOutbox.enqueue({
@@ -1991,7 +3138,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" });
@@ -2019,14 +3165,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 };
             }
@@ -2038,7 +3183,17 @@ export class GonvexClient {
             void this.drainOutbox();
         }
     }
+    requireClientUpdate(reason) {
+        if (this.updateRequired)
+            return;
+        this.updateRequired = true;
+        // Keep durable intents intact. Closing suspends subscriptions and future sends.
+        this.close();
+        this.updateRequiredHandler?.(reason);
+    }
     canSendReducerNow() {
+        if (this.updateRequired)
+            return false;
         if (globalThis.navigator?.onLine === false)
             return false;
         const socket = this.socket;
@@ -2183,6 +3338,10 @@ export class GonvexClient {
                 ...(ref.scope === "control" ? { scope: "control" } : {}),
                 trace: { clientSentAtMs: entry.clientSentAtMs },
                 ...(effectiveIdempotencyKey ? { idempotencyKey: effectiveIdempotencyKey } : {}),
+                ...(ref.artifactHash ? { artifactHash: ref.artifactHash } : {}),
+                ...(this.clientContract ? { clientContract: this.clientContract.version } : {}),
+                ...(ref.receiptPath ? { receiptPath: ref.receiptPath } : {}),
+                ...(ref.intentEntropy ? { intentEntropy: ref.intentEntropy } : {}),
             });
         }
         else {
@@ -2233,8 +3392,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);
@@ -2258,7 +3420,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 = () => {
@@ -2485,6 +3651,9 @@ export class GonvexClient {
         this.send(message);
     }
     hasControlPlaneWork() {
+        for (const query of this.querySubscriptions.values())
+            if (query.executionScope === "control")
+                return true;
         for (const query of this.oneShotQueries.values())
             if (query.scope === "control")
                 return true;
@@ -2615,6 +3784,21 @@ export class GonvexClient {
         if (this.manuallyClosed)
             return Promise.reject(new Error("Gonvex client is closed"));
         this.connect();
+        if (!this.activeAuthFrameId) {
+            return new Promise((resolve, reject) => {
+                this.pendingNativeErrors.push({ type, payload, resolve, reject });
+            });
+        }
+        return this.sendNativeErrorFrame(type, payload);
+    }
+    flushPendingNativeErrors() {
+        if (!this.activeAuthFrameId || this.pendingNativeErrors.length === 0)
+            return;
+        for (const pending of this.pendingNativeErrors.splice(0)) {
+            void this.sendNativeErrorFrame(pending.type, pending.payload).then(pending.resolve, pending.reject);
+        }
+    }
+    sendNativeErrorFrame(type, payload) {
         const id = randomID();
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -2663,11 +3847,13 @@ export class GonvexClient {
         this.managedAuthAttempt?.ids.add(id);
         this.sendNow({
             type: "auth",
+            ...(this.clientContract ? { clientContract: this.clientContract.version } : {}),
             id,
             token: this.auth.token,
             project: this.auth.project,
             tenant: this.auth.tenant,
             controlOnly: !this.auth.tenant,
+            ...(this.publicTenant ? { public: true } : {}),
             device: browserTelemetryInfo(),
             capabilities: { replicaReadyMany: 1, replicaWatermark: 1, queryPagePatch: 1, queryObjectPatch: 1, queryOrderDelta: 1, queryFanout: 1, queryResultBatch: 1 },
         });
@@ -2805,7 +3991,19 @@ export class GonvexClient {
                     socket.send(JSON.stringify(message));
                     return;
                 }
-                this.send(message);
+                // A replaced socket re-sends its own work; don't route this message
+                // onto the newer connection a second time.
+                if (this.socket !== socket)
+                    return;
+                // Public control calls (such as the token exchange) renew the
+                // session that the pending auth is waiting for. Queueing them behind
+                // that auth deadlocks the connection, so keep their auth bypass.
+                const id = "id" in message ? message.id : undefined;
+                const pending = id ? this.pendingCalls.get(id) ?? this.oneShotQueries.get(id) : undefined;
+                if ("scope" in message && message.scope === "control" && pending?.authorization === "public")
+                    this.sendNow(message);
+                else
+                    this.send(message);
             }, { once: true });
             return;
         }
@@ -2860,15 +4058,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;
@@ -2878,9 +4094,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);
@@ -2902,6 +4205,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);
@@ -2922,9 +4228,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);
@@ -2971,7 +4277,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();
@@ -3038,6 +4347,31 @@ function queryPatchRowKey(value) {
     const candidate = value._id ?? value.id;
     return typeof candidate === "string" || typeof candidate === "number" ? String(candidate) : "";
 }
+function applyLocalPatches(snapshot, patches) {
+    for (const patch of patches) {
+        const entity = patch.entity ?? patch.collection;
+        if (!entity)
+            continue;
+        const table = snapshot.tables[entity] ??= { complete: false, rows: [] };
+        const index = table.rows.findIndex((row) => String(row._id ?? row.id) === patch.rowId);
+        if (patch.op === "delete") {
+            if (index >= 0)
+                table.rows.splice(index, 1);
+        }
+        else if (index >= 0)
+            table.rows[index] = { ...table.rows[index], ...structuredClone(patch.fields) };
+        else if (patch.op !== "patch")
+            table.rows.push(structuredClone(patch.fields));
+    }
+}
+function localIdentityFromAuthResult(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        return;
+    const identity = result.localIdentity;
+    if (!identity?.auth?.account?.id || !identity.tenant?.id || !identity.member?.id)
+        return;
+    return structuredClone(identity);
+}
 function authFromOptions(options) {
     return {
         project: options.project,
@@ -3056,8 +4390,6 @@ function normalizeQuerySubscriptionRetentionMs(value) {
     return Math.max(0, Math.min(5 * 60_000, Math.floor(value)));
 }
 function authIdentityKey(auth) {
-    if (!auth.tenant)
-        return "";
     if (auth.token) {
         const tokenIdentity = authIdentityKeyFromToken(auth);
         if (tokenIdentity)
@@ -3067,12 +4399,12 @@ function authIdentityKey(auth) {
     // token would supply, so both paths derive the same key for the same Account.
     const hint = auth.identity;
     if (hint && typeof hint.sub === "string" && hint.sub.trim()) {
-        return [auth.project ?? "", auth.tenant, hint.iss ?? "", hint.sub].join("\u0000");
+        return [auth.project ?? "", auth.tenant ?? "", hint.iss ?? "", hint.sub].join("\u0000");
     }
     return "";
 }
 function authIdentityKeyFromToken(auth) {
-    if (!auth.token || !auth.tenant)
+    if (!auth.token)
         return "";
     const parts = auth.token.split(".");
     if (parts.length < 2)
@@ -3085,7 +4417,7 @@ function authIdentityKeyFromToken(auth) {
             return "";
         return [
             auth.project ?? "",
-            auth.tenant,
+            auth.tenant ?? "",
             typeof payload.iss === "string" ? payload.iss : "",
             payload.sub,
         ].join("\u0000");
@@ -3212,4 +4544,56 @@ function detectDeviceType(userAgent) {
         return "mobile";
     return "desktop";
 }
+/**
+ * Dependency tables of locally executing Reducers that stay resident. A
+ * table qualifies when its unfiltered generated collection declares a small
+ * enough `maxRows` (and `maxBytes`, when bounded). Collections without a
+ * declared bound are never resident: their size is unknown.
+ */
+export function residentLocalDependencyTables(binding, policy = "bounded") {
+    if (!binding?.localDependencies || policy === "off")
+        return [];
+    const bounds = policy === "bounded" ? {} : policy;
+    const maxRows = bounds.maxRows ?? DEFAULT_LOCAL_DEPENDENCY_RESIDENT_MAX_ROWS;
+    const maxBytes = bounds.maxBytes;
+    const tables = new Set(Object.values(binding.localDependencies).flat());
+    return [...tables].filter((table) => (binding.collections ?? []).some((reference) => {
+        const replica = reference.replica;
+        if (replica?.table !== table || Object.keys(replica.equalFilters ?? {}).length || replica.excludeWhenSet?.length)
+            return false;
+        if (!replica.maxRows || replica.maxRows > maxRows)
+            return false;
+        return maxBytes === undefined || (!!replica.maxBytes && replica.maxBytes <= maxBytes);
+    })).sort();
+}
+/** 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