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

package/dist/local-replica.js

@@ -1,6 +1,13 @@
+import { memoryReadView, overlayReadView } from '@gonvex/local-runtime/read-view';
 const defaultReplicaScope = "default";
 export class LocalReplica {
     storage;
+    retainedWindows = new Map();
+    retainedRows = new Map();
+    residentPartialTables = new Set();
+    rowSizes = new WeakMap();
+    visibleRowCopies = new WeakMap();
+    residencyBudget = { maxRows: 20_000, maxBytes: 16 * 1024 * 1024 };
     cursorValue;
     entities = new Map();
     liveQueries = new Map();
@@ -10,12 +17,55 @@ export class LocalReplica {
     pendingCommands = new Map();
     listeners = new Set();
     persistence = Promise.resolve();
+    storageSequence = 0;
     application = Promise.resolve();
+    applicationRunning = false;
+    disposed = false;
+    applicationJobs = [];
+    enqueueApplication(run, urgent = false) {
+        if (this.disposed)
+            return Promise.reject(new Error("Local replica is closed"));
+        let resolve;
+        let reject;
+        const result = new Promise((done, failed) => { resolve = done; reject = failed; });
+        this.applicationJobs.push({ urgent, cancel: () => reject(new Error("Local replica is closed")), run: async () => { try {
+                resolve(await run());
+            }
+            catch (error) {
+                reject(error);
+            }
+            finally {
+                if (this.disposed)
+                    this.releaseMemory();
+            } } });
+        this.application = Promise.all([this.application, result]).then(() => undefined, () => undefined);
+        if (!this.applicationRunning) {
+            this.applicationRunning = true;
+            queueMicrotask(() => { void this.drainApplicationJobs(); });
+        }
+        return result;
+    }
+    async drainApplicationJobs() {
+        while (this.applicationJobs.length) {
+            // Finish the active transaction atomically. Between transactions, a user
+            // read can precede queued hydration without reordering server writes.
+            const urgent = this.applicationJobs.findIndex(job => job.urgent);
+            const [job] = this.applicationJobs.splice(urgent < 0 ? 0 : urgent, 1);
+            await job.run();
+        }
+        this.applicationRunning = false;
+    }
     hydration;
     freshnessValue = "verifying";
     versionValue = 0;
+    executionVersionValue = 0;
+    entityVersionClock = 0;
+    entityVersionFloor = 0;
+    entityVersions = new Map();
     windowVersionClock = 0;
     windowVersions = new Map();
+    rowVersions = new Map();
+    windowRowsVersions = new Map();
     scopeValue = defaultReplicaScope;
     // The default scope starts as an immediately usable empty in-memory store.
     // Persistence is restored only by hydrate()/activateScope(), so direct
@@ -24,8 +74,38 @@ export class LocalReplica {
     scopeActivation;
     scopeActivationName;
     scopeActivationGeneration = 0;
-    constructor(storage) {
+    constructor(storage, options = {}) {
         this.storage = storage;
+        for (const [name, value] of Object.entries(options))
+            if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0))
+                throw new Error(`Invalid replica residency budget: ${name}`);
+        this.residencyBudget.maxRows = options.maxResidentRows ?? this.residencyBudget.maxRows;
+        this.residencyBudget.maxBytes = options.maxResidentBytes ?? this.residencyBudget.maxBytes;
+    }
+    /** Release a discarded client's in-memory state without deleting durable data. */
+    dispose() {
+        this.disposed = true;
+        this.scopeLoaded = false;
+        this.scopeActivationGeneration++;
+        for (const job of this.applicationJobs.splice(0))
+            job.cancel();
+        this.releaseMemory();
+    }
+    releaseMemory() {
+        this.entities.clear();
+        this.liveQueries.clear();
+        this.pendingCommands.clear();
+        this.listeners.clear();
+        this.retainedWindows.clear();
+        this.retainedRows.clear();
+        this.residentPartialTables.clear();
+        this.windowOwned.clear();
+        this.replicaPlans.clear();
+        this.readSnapshots.clear();
+        this.entityVersions.clear();
+        this.rowVersions.clear();
+        this.windowVersions.clear();
+        this.windowRowsVersions.clear();
     }
     hydrate() {
         if (this.hydration)
@@ -48,19 +128,28 @@ export class LocalReplica {
         // synchronous auth change from exposing the prior identity's rows.
         const wasLoaded = this.scopeLoaded;
         this.scopeLoaded = false;
-        if (wasLoaded)
-            this.notify();
+        if (wasLoaded) {
+            this.invalidateEntityVersions();
+            this.notify(true);
+        }
         const generation = ++this.scopeActivationGeneration;
-        const activation = this.application.then(async () => {
+        const activation = this.enqueueApplication(async () => {
             // A prior transaction may still be in the storage queue. Wait for it so
             // a same-scope activation cannot load a snapshot from before its commit.
             await this.persistence;
-            const snapshot = await this.storage?.load(nextScope);
+            const snapshot = this.storage?.loadWorkingSet
+                ? await this.storage.loadWorkingSet(nextScope, this.residencyBudget)
+                : await this.storage?.load(nextScope);
             if (generation !== this.scopeActivationGeneration)
                 return;
             this.scopeValue = nextScope;
+            this.storageSequence = snapshot?.storageSequence ?? 0;
             this.scopeLoaded = true;
             this.entities = snapshot ? entitiesFromSnapshot(snapshot.entities) : new Map();
+            this.residentPartialTables.clear();
+            for (const entity of snapshot?.residentPartialTables ?? [])
+                this.residentPartialTables.add(entity);
+            this.invalidateEntityVersions();
             this.liveQueries = snapshot
                 ? new Map(Object.entries(snapshot.liveQueries).map(([key, value]) => [key, normalizeWindow(value)]))
                 : new Map();
@@ -72,22 +161,280 @@ export class LocalReplica {
             // projected while the newly restored scope is becoming authoritative.
             this.pendingCommands.clear();
             this.freshnessValue = "verifying";
-            this.notify();
+            this.notify(true);
+            queueMicrotask(() => {
+                if (generation !== this.scopeActivationGeneration)
+                    return;
+                for (const signature of this.retainedWindows.keys())
+                    this.retainWindow(signature)();
+                for (const [entity, ids] of this.retainedRows)
+                    this.retainRows(entity, [...ids.keys()])();
+            });
         });
-        this.application = activation.catch(() => undefined);
         this.scopeActivation = activation;
         this.scopeActivationName = nextScope;
         return activation;
     }
+    /** Active views retain their rows. Cold collections stay durable on disk and
+     * reducer reads can use the indexed adapter without hydrating the table. */
+    retainWindow(signature) {
+        this.retainedWindows.set(signature, (this.retainedWindows.get(signature) ?? 0) + 1);
+        const scopeGeneration = this.scopeActivationGeneration;
+        const operation = this.enqueueApplication(async () => {
+            if (!this.scopeLoaded || !this.retainedWindows.has(signature) || scopeGeneration !== this.scopeActivationGeneration || !this.storage?.loadWindowRows)
+                return;
+            const existing = this.liveQueries.get(signature);
+            if (existing?.ids.every(id => this.entities.get(existing.entity)?.has(id)))
+                return;
+            const loaded = await this.storage.loadWindowRows(this.scopeValue, signature);
+            if (!loaded || !this.retainedWindows.has(signature) || scopeGeneration !== this.scopeActivationGeneration)
+                return;
+            const table = new Map(this.entities.get(loaded.window.entity));
+            for (const row of loaded.rows)
+                table.set(String(row[loaded.window.key]), row);
+            this.entities = new Map(this.entities).set(loaded.window.entity, table);
+            this.liveQueries.set(signature, normalizeWindow(loaded.window));
+            if (loaded.window.kind === 'replica' && loaded.window.completeness === 'complete' && !loaded.window.truncated && loaded.rows.length === loaded.window.ids.length)
+                this.residentPartialTables.delete(loaded.window.entity);
+            this.markEntityChanged(loaded.window.entity, loaded.window.ids);
+            this.markWindowChanged(signature);
+            this.notify(true);
+        }, true);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const count = this.retainedWindows.get(signature) ?? 0;
+            if (count > 1)
+                this.retainedWindows.set(signature, count - 1);
+            else {
+                this.retainedWindows.delete(signature);
+                this.readSnapshots.delete(signature);
+                this.trimResidentRows();
+            }
+        };
+    }
+    residentCoverage(coverage) {
+        if (!this.residentPartialTables.size)
+            return coverage;
+        return Object.fromEntries(Object.entries(coverage).map(([table, value]) => [table, this.residentPartialTables.has(table) ? { ...value, complete: false, completeWhere: undefined } : value]));
+    }
+    retainRows(entity, ids) {
+        const scopeGeneration = this.scopeActivationGeneration;
+        let retained = this.retainedRows.get(entity);
+        if (!retained) {
+            retained = new Map();
+            this.retainedRows.set(entity, retained);
+        }
+        for (const id of ids)
+            retained.set(id, (retained.get(id) ?? 0) + 1);
+        const operation = this.enqueueApplication(async () => {
+            if (!this.scopeLoaded || !this.storage?.loadEntityRows || scopeGeneration !== this.scopeActivationGeneration)
+                return;
+            const missing = ids.filter(id => !this.entities.get(entity)?.has(id) && this.retainedRows.get(entity)?.has(id));
+            if (!missing.length)
+                return;
+            const rows = await this.storage.loadEntityRows(this.scopeValue, entity, missing);
+            if (scopeGeneration !== this.scopeActivationGeneration)
+                return;
+            const next = new Map(this.entities.get(entity));
+            for (const { id, row } of rows)
+                if (this.retainedRows.get(entity)?.has(id))
+                    next.set(id, row);
+            this.entities = new Map(this.entities).set(entity, next);
+            this.markEntityChanged(entity, missing);
+            this.notify(true);
+        }, true);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const current = this.retainedRows.get(entity);
+            for (const id of ids) {
+                const count = current?.get(id) ?? 0;
+                if (count > 1)
+                    current.set(id, count - 1);
+                else
+                    current?.delete(id);
+            }
+            if (!current?.size)
+                this.retainedRows.delete(entity);
+            this.trimResidentRows();
+        };
+    }
+    trimResidentRows() {
+        // Without indexed persistence, eviction would lose the only readable copy.
+        if (!this.storage?.withReadView || !this.storage?.loadWindowRows)
+            return;
+        let bytes = 0, count = 0;
+        for (const rows of this.entities.values())
+            for (const row of rows.values()) {
+                let size = this.rowSizes.get(row);
+                if (size === undefined) {
+                    size = JSON.stringify(row).length * 2 + 256;
+                    this.rowSizes.set(row, size);
+                }
+                bytes += size;
+                count++;
+            }
+        if (bytes <= this.residencyBudget.maxBytes && count <= this.residencyBudget.maxRows)
+            return;
+        const pinned = new Map();
+        const pin = (entity, id) => { let ids = pinned.get(entity); if (!ids) {
+            ids = new Set();
+            pinned.set(entity, ids);
+        } ids.add(id); };
+        for (const signature of this.retainedWindows.keys()) {
+            const window = this.liveQueries.get(signature);
+            if (window)
+                for (const id of window.ids)
+                    pin(window.entity, id);
+        }
+        for (const [entity, ids] of this.retainedRows)
+            for (const id of ids.keys())
+                pin(entity, id);
+        for (const command of this.pendingCommands.values())
+            for (const patch of command.patches)
+                pin(patch.entity ?? patch.collection, patch.rowId);
+        const next = new Map(this.entities);
+        let evicted = false;
+        for (const [entity, rows] of this.entities) {
+            let copied;
+            for (const [id, row] of rows) {
+                if (bytes <= this.residencyBudget.maxBytes && count <= this.residencyBudget.maxRows)
+                    break;
+                if (pinned.get(entity)?.has(id))
+                    continue;
+                copied ??= new Map(rows);
+                copied.delete(id);
+                count--;
+                bytes -= this.rowSizes.get(row);
+                this.rowVersions.delete(`${entity}\0${id}`);
+                this.residentPartialTables.add(entity);
+                evicted = true;
+            }
+            if (copied)
+                next.set(entity, copied);
+        }
+        if (evicted) {
+            this.entities = next;
+            this.readSnapshots.clear();
+        }
+    }
     cursor() {
         return this.scopeLoaded && this.cursorValue ? { ...this.cursorValue } : undefined;
     }
+    /** Consume the durable replica, including commits delivered by another tab.
+     * Predictions remain a separate overlay; peers never advance our socket's
+     * acknowledged cursor or publish a half-applied transaction. */
+    synchronizeStorage() {
+        if (!this.storage?.readChanges)
+            return Promise.resolve();
+        const scope = this.scopeValue;
+        const application = this.enqueueApplication(async () => {
+            if (!this.scopeLoaded || scope !== this.scopeValue || !this.storage?.readChanges)
+                return;
+            await this.persistence;
+            const entities = new Map(this.entities);
+            const windows = new Map(this.liveQueries);
+            if (!await this.mergeStoredChanges(entities, windows))
+                return;
+            this.entities = entities;
+            this.liveQueries = windows;
+            this.notify(true);
+        }, true);
+        return application;
+    }
+    async mergeStoredChanges(entities, windows) {
+        if (!this.storage?.readChanges)
+            return false;
+        const residentIds = Object.fromEntries([...entities].map(([table, rows]) => [table, [...rows.keys()]]));
+        let residentBytes = 0, residentCount = 0;
+        for (const rows of entities.values())
+            for (const row of rows.values()) {
+                let size = this.rowSizes.get(row);
+                if (size === undefined) {
+                    size = JSON.stringify(row).length * 2 + 256;
+                    this.rowSizes.set(row, size);
+                }
+                residentBytes += size;
+                residentCount++;
+            }
+        for (const command of this.pendingCommands.values())
+            for (const patch of command.patches) {
+                const entity = patch.entity ?? patch.collection;
+                (residentIds[entity] ??= []).push(patch.rowId);
+            }
+        const changes = await this.storage.readChanges(this.scopeValue, this.storageSequence, this.storage.loadWorkingSet ? {
+            rows: residentIds,
+            windows: [...this.retainedWindows.keys()],
+            availableRows: Math.max(0, this.residencyBudget.maxRows - residentCount),
+            availableBytes: Math.max(0, this.residencyBudget.maxBytes - residentBytes),
+            ...this.residencyBudget,
+        } : undefined);
+        if (changes.sequence === this.storageSequence)
+            return false;
+        if (changes.reset) {
+            entities.clear();
+            windows.clear();
+            this.windowOwned.clear();
+            this.invalidateEntityVersions();
+        }
+        for (const [entity, values] of Object.entries(changes.entities)) {
+            const rows = new Map(entities.get(entity));
+            const changedIDs = new Set();
+            for (const [id, row] of Object.entries(values)) {
+                if (row === null) {
+                    if (rows.delete(id))
+                        changedIDs.add(id);
+                }
+                else if (!sameReplicaValue(rows.get(id), row)) {
+                    rows.set(id, row);
+                    changedIDs.add(id);
+                }
+            }
+            if (!changedIDs.size)
+                continue;
+            entities.set(entity, rows);
+            this.markEntityChanged(entity, changedIDs);
+            for (const window of windows.values()) {
+                if (window.entity === entity && window.ids.some(id => changedIDs.has(id)))
+                    this.markWindowChanged(window.signature);
+            }
+        }
+        for (const [signature, window] of Object.entries(changes.windows)) {
+            const previous = windows.get(signature);
+            if (window === null) {
+                if (windows.delete(signature))
+                    this.markWindowChanged(signature);
+                continue;
+            }
+            if (sameReplicaValue(previous, window))
+                continue;
+            const membershipChanged = !sameWindowRowDefinition(previous, window);
+            windows.set(signature, normalizeWindow(window));
+            if (window.ids.some(id => !entities.get(window.entity)?.has(id)))
+                this.residentPartialTables.add(window.entity);
+            // Row changes have already invalidated their windows above. A storage
+            // watermark changes metadata, not membership or the visible row array.
+            this.markWindowChanged(signature, membershipChanged);
+        }
+        this.storageSequence = changes.sequence;
+        return true;
+    }
     freshness() {
         return this.freshnessValue;
     }
     version() { return this.versionValue; }
+    /** Changes to the authoritative execution snapshot, excluding UI metadata and predictions. */
+    executionVersion() { return this.executionVersionValue; }
+    entityVersion(entity, id) { return id === undefined ? this.entityVersions.get(entity) ?? this.entityVersionFloor : this.rowVersion(entity, id); }
+    rowVersion(entity, id) { return this.rowVersions.get(`${entity}\0${id}`) ?? this.entityVersionFloor; }
     /** Monotonic version for one materialized window and its referenced rows. */
     windowVersion(signature) { return this.windowVersions.get(signature) ?? 0; }
+    windowRowsVersion(signature) { return this.windowRowsVersions.get(signature) ?? 0; }
     setFreshness(freshness) {
         if (freshness === this.freshnessValue)
             return;
@@ -103,10 +450,34 @@ export class LocalReplica {
         if (!commandId)
             throw new Error("optimistic commandId is required");
         const clonedPatches = patches.map(cloneOptimisticPatch);
+        const previous = this.pendingCommands.get(commandId);
+        if (previous && sameReplicaValue(previous.patches, clonedPatches))
+            return;
+        if (previous)
+            this.markWindowsForPatches(previous.patches);
         this.pendingCommands.set(commandId, { commandId, patches: clonedPatches });
         this.markWindowsForPatches(clonedPatches);
         this.notify();
     }
+    /** SDK-only atomic replacement after ordered local reducer replay. */
+    replaceOptimistic(commands) {
+        // Rebase is also triggered by unrelated authoritative updates. An identical
+        // overlay must not dirty every selector or schedule another application render.
+        const previous = [...this.pendingCommands.values()];
+        if (previous.length === commands.length && commands.every((command, index) => command.commandId === previous[index].commandId &&
+            JSON.stringify(command.patches) === JSON.stringify(previous[index].patches)))
+            return;
+        for (const command of this.pendingCommands.values())
+            this.markWindowsForPatches(command.patches);
+        const previousCommands = new Map(this.pendingCommands);
+        this.pendingCommands.clear();
+        for (const command of commands) {
+            const patches = command.patches.map(cloneOptimisticPatch);
+            this.pendingCommands.set(command.commandId, { commandId: command.commandId, patches, committedRevision: previousCommands.get(command.commandId)?.committedRevision });
+            this.markWindowsForPatches(patches);
+        }
+        this.notify();
+    }
     /** Register generated Replica metadata without persisting it with the window. */
     registerReplicaCollection(signature, definition, args = {}) {
         this.replicaPlans.set(signature, {
@@ -140,13 +511,11 @@ export class LocalReplica {
     }
     applyTransaction(transaction, scope) {
         const requestedScope = scope === undefined ? undefined : normalizeReplicaScope(scope);
-        const application = this.application.then(() => this.applyTransactionNow(transaction, requestedScope));
-        this.application = application.catch(() => undefined);
+        const application = this.enqueueApplication(() => this.applyTransactionNow(transaction, requestedScope));
         return application;
     }
     materializeWindow(input) {
-        const application = this.application.then(() => this.materializeWindowNow(input));
-        this.application = application.catch(() => undefined);
+        const application = this.enqueueApplication(() => this.materializeWindowNow(input));
         return application;
     }
     /** Replace one server/cache window while retaining shared normalized entities. */
@@ -155,7 +524,7 @@ export class LocalReplica {
     }
     /** Apply a bounded window delta and persist it in the same transaction. */
     applyWindowDelta(input) {
-        const application = this.application.then(async () => {
+        const application = this.enqueueApplication(async () => {
             const existing = this.liveQueries.get(input.signature);
             const deleted = new Set(input.deleted.map(String));
             const ids = (existing?.ids ?? []).filter((id) => !deleted.has(id));
@@ -165,19 +534,24 @@ export class LocalReplica {
                 if (id && !ids.includes(id))
                     ids.push(id);
             }
+            const upserts = new Map(input.upserts.map(row => [String(row[input.key]), row]));
             const rows = ids
-                .map((id) => input.upserts.find((row) => String(row[input.key]) === id) ?? this.entities.get(input.entity)?.get(id))
-                .filter((row) => row !== undefined)
-                .map(cloneRow);
+                .map((id) => upserts.has(id) ? { ...this.entities.get(input.entity)?.get(id), ...upserts.get(id) } : this.entities.get(input.entity)?.get(id))
+                .filter((row) => row !== undefined);
+            const plan = this.replicaPlans.get(input.signature)?.definition;
+            const orderBy = input.orderBy ?? existing?.orderBy ?? plan?.orderBy;
+            const orderDirection = input.orderDirection ?? existing?.orderDirection ?? plan?.orderDirection;
+            if ((input.kind ?? existing?.kind) === 'replica' && orderBy) {
+                rows.sort((a, b) => compareReplicaMembershipRows(a, b, input.key, orderBy, orderDirection));
+            }
             await this.materializeWindowNow({
                 ...input,
                 rows,
                 completeness: input.completeness ?? existing?.completeness ?? "partial",
                 source: input.source ?? existing?.source ?? "server",
                 removedIDs: [...deleted],
-            });
+            }, { upserts: input.upserts, deleted: [...deleted] });
         });
-        this.application = application.catch(() => undefined);
         return application;
     }
     /**
@@ -188,21 +562,22 @@ export class LocalReplica {
      */
     advanceWatermark(revision, signatures = [], scope) {
         const requestedScope = scope === undefined ? undefined : normalizeReplicaScope(scope);
-        const application = this.application.then(async () => {
+        const application = this.enqueueApplication(async () => {
             if (requestedScope !== undefined && requestedScope !== this.scopeValue)
                 return;
             if (!Number.isSafeInteger(revision) || revision < 0 || signatures.length === 0)
                 return;
             const eligible = new Set(signatures);
-            const nextQueries = new Map([...this.liveQueries.entries()].map(([signature, window]) => [signature, cloneWindow(window)]));
+            const nextQueries = new Map(this.liveQueries);
             const changedWindows = [];
             for (const [signature, window] of nextQueries) {
                 if (!eligible.has(signature) || window.kind !== "replica" || !window.cursor)
                     continue;
                 if (window.cursor.revision >= revision)
                     continue;
-                window.cursor = { ...window.cursor, revision };
-                changedWindows.push(window);
+                const advanced = { ...window, cursor: { ...window.cursor, revision } };
+                nextQueries.set(signature, advanced);
+                changedWindows.push(advanced);
             }
             if (changedWindows.length === 0)
                 return;
@@ -216,7 +591,7 @@ export class LocalReplica {
             else if (this.storage?.replaceSnapshot) {
                 // Compatibility for older/custom storage adapters. Current IndexedDB
                 // and SQLite adapters implement the metadata-only operation above.
-                const snapshot = snapshotFrom(nextCursor, this.entities, nextQueries);
+                const snapshot = storageSnapshotFrom(nextCursor, this.entities, nextQueries);
                 await this.persist(() => this.storage.replaceSnapshot(snapshot, writeScope));
             }
             else if (this.storage?.replaceWindow) {
@@ -224,18 +599,17 @@ export class LocalReplica {
                 // durability for those adapters by reusing one computed snapshot;
                 // this path is intentionally serial and is not used by the bundled
                 // normalized adapters.
-                const snapshot = snapshotFrom(nextCursor, this.entities, nextQueries);
+                const snapshot = storageSnapshotFrom(nextCursor, this.entities, nextQueries);
                 for (const window of changedWindows) {
                     await this.persist(() => this.storage.replaceWindow(window, snapshot, writeScope));
                 }
             }
             this.liveQueries = nextQueries;
             for (const window of changedWindows)
-                this.markWindowChanged(window.signature);
+                this.markWindowChanged(window.signature, false);
             this.cursorValue = nextCursor;
             this.notify();
         });
-        this.application = application.catch(() => undefined);
         return application;
     }
     getWindow(signature) {
@@ -265,14 +639,15 @@ export class LocalReplica {
             .map(cloneRow);
     }
     removeWindow(signature, scope) {
-        const application = this.application.then(async () => {
+        const application = this.enqueueApplication(async () => {
             if (scope !== undefined && normalizeReplicaScope(scope) !== this.scopeValue)
                 return;
             if (!this.liveQueries.has(signature))
                 return;
             const nextQueries = new Map(this.liveQueries);
+            const removed = nextQueries.get(signature);
             nextQueries.delete(signature);
-            const snapshot = snapshotFrom(this.cursorValue, this.entities, nextQueries);
+            const snapshot = storageSnapshotFrom(this.cursorValue, this.entities, nextQueries);
             if (this.storage?.removeWindow) {
                 await this.persist(() => this.storage.removeWindow(signature, snapshot, this.scopeValue));
             }
@@ -282,59 +657,67 @@ export class LocalReplica {
             this.liveQueries = nextQueries;
             this.markWindowChanged(signature);
             this.pruneOwnedEntitiesAfterRemoval(signature, nextQueries);
-            this.notify();
+            this.markEntityChanged(removed.entity);
+            this.notify(true);
         });
-        this.application = application.catch(() => undefined);
         return application;
     }
     clear(scope) {
-        const application = this.application.then(async () => {
+        const application = this.enqueueApplication(async () => {
             if (scope !== undefined && normalizeReplicaScope(scope) !== this.scopeValue)
                 return;
             if (this.storage?.clear)
                 await this.persist(() => this.storage.clear(this.scopeValue));
             this.cursorValue = undefined;
             this.entities.clear();
+            this.invalidateEntityVersions();
             for (const signature of this.liveQueries.keys())
                 this.markWindowChanged(signature);
             this.liveQueries.clear();
             this.windowOwned.clear();
             this.pendingCommands.clear();
             this.freshnessValue = "verifying";
-            this.notify();
+            this.notify(true);
         });
-        this.application = application.catch(() => undefined);
         return application;
     }
-    async materializeWindowNow(input) {
+    async materializeWindowNow(input, delta) {
         if (input.scope !== undefined && normalizeReplicaScope(input.scope) !== this.scopeValue)
             return;
         if (!input.signature.trim() || !input.entity.trim() || !input.key.trim()) {
             throw new Error("replica materialization requires signature, entity, and key");
         }
-        const nextEntities = cloneEntities(this.entities);
-        // Clone memberships before changing them. Persistence may be asynchronous,
-        // and readers must continue to observe the prior complete version until the
-        // transaction commits locally and the single state swap below runs.
-        const nextQueries = new Map([...this.liveQueries.entries()].map(([signature, window]) => [signature, cloneWindow(window)]));
-        if (input.cursor && this.cursorValue && input.cursor.epoch !== this.cursorValue.epoch) {
+        // This materialization changes one entity map and one membership. Other
+        // published maps/windows stay immutable and can be shared during persistence.
+        const nextEntities = new Map(this.entities);
+        const nextQueries = new Map(this.liveQueries);
+        const epochChanged = Boolean(input.cursor && this.cursorValue && input.cursor.epoch !== this.cursorValue.epoch);
+        if (epochChanged) {
             nextEntities.clear();
             nextQueries.clear();
         }
-        const entityRows = nextEntities.get(input.entity) ?? new Map();
+        const entityRows = new Map(nextEntities.get(input.entity));
         nextEntities.set(input.entity, entityRows);
         const ids = [];
+        const changedRowIDs = new Set();
+        const changedIDs = delta && !epochChanged ? new Set(delta.upserts.map(row => String(row[input.key]))) : undefined;
         for (const row of input.rows) {
             const rawID = row[input.key];
             const id = typeof rawID === "string" || typeof rawID === "number" ? String(rawID) : "";
             if (!id)
                 continue;
             ids.push(id);
+            if (changedIDs && !changedIDs.has(id))
+                continue;
             // Different Replica Collections may project different columns from the
             // same table. They all hydrate one normalized entity, so a narrow
             // projection must update the fields it owns without erasing fields
             // supplied by another collection.
-            entityRows.set(id, { ...(entityRows.get(id) ?? {}), ...cloneRow(row) });
+            const priorRow = entityRows.get(id);
+            if (priorRow && Object.keys(row).every(key => Object.prototype.hasOwnProperty.call(priorRow, key) && sameReplicaValue(priorRow[key], row[key])))
+                continue;
+            entityRows.set(id, { ...(priorRow ?? {}), ...cloneRow(row) });
+            changedRowIDs.add(id);
         }
         const previous = nextQueries.get(input.signature);
         const window = {
@@ -362,8 +745,8 @@ export class LocalReplica {
         nextQueries.set(input.signature, window);
         for (const id of input.removedIDs ?? []) {
             const stillReferenced = [...nextQueries.values()].some((candidate) => candidate.ids.includes(id));
-            if (!stillReferenced)
-                nextEntities.get(input.entity)?.delete(id);
+            if (!stillReferenced && nextEntities.get(input.entity)?.delete(id))
+                changedRowIDs.add(id);
         }
         this.trackWindowOwnership(window, input.rows, previous);
         // A collection cursor proves only that collection's materialized rows.
@@ -372,22 +755,41 @@ export class LocalReplica {
         // collection. The only revision proven by snapshots alone is the minimum
         // cursor shared by every materialized Replica window in the epoch.
         const nextCursor = replicaTransactionFloor(this.cursorValue, nextQueries);
-        const snapshot = snapshotFrom(nextCursor, nextEntities, nextQueries);
+        const snapshot = storageSnapshotFrom(nextCursor, nextEntities, nextQueries);
+        const membershipChanged = !sameWindowRowDefinition(previous, window);
+        const rowsChanged = membershipChanged || changedRowIDs.size > 0;
         const writeScope = this.scopeValue;
-        if (this.storage?.replaceWindow) {
-            await this.persist(() => this.storage.replaceWindow(window, snapshot, writeScope));
+        if (!epochChanged && this.storage?.applyWindowDelta && (delta || !rowsChanged)) {
+            const writeDelta = delta ? { upserts: delta.upserts.filter(row => changedRowIDs.has(String(row[input.key]))), deleted: delta.deleted } : { upserts: [], deleted: [] };
+            await this.persist(() => this.storage.applyWindowDelta(window, writeDelta, snapshot, writeScope));
+        }
+        else if (this.storage?.replaceWindow) {
+            await this.persist(() => this.storage.replaceWindow(window, snapshot, writeScope, input.rows));
         }
         else if (this.storage?.replaceSnapshot) {
             await this.persist(() => this.storage.replaceSnapshot(snapshot, writeScope));
         }
+        if (epochChanged)
+            this.invalidateEntityVersions();
+        if (this.storage?.readChanges)
+            await this.mergeStoredChanges(nextEntities, nextQueries);
         this.entities = nextEntities;
         this.liveQueries = nextQueries;
-        this.markWindowChanged(input.signature);
+        if (window.kind === 'replica' && window.completeness === 'complete' && !window.truncated && window.ids.every(id => nextEntities.get(window.entity)?.has(id)))
+            this.residentPartialTables.delete(window.entity);
+        if (changedRowIDs.size) {
+            this.markEntityChanged(input.entity, changedRowIDs);
+            for (const candidate of this.liveQueries.values()) {
+                if (candidate.signature !== input.signature && candidate.entity === input.entity && candidate.ids.some(id => changedRowIDs.has(id)))
+                    this.markWindowChanged(candidate.signature);
+            }
+        }
+        this.markWindowChanged(input.signature, rowsChanged);
         this.pruneOwnedEntities(input.signature);
         this.cursorValue = nextCursor;
         if (input.source === "server")
             this.freshnessValue = "current";
-        this.notify();
+        this.notify(true);
     }
     async applyTransactionNow(transaction, scope) {
         if (scope !== undefined && scope !== this.scopeValue)
@@ -396,47 +798,60 @@ export class LocalReplica {
         if (this.cursorValue?.epoch === transaction.cursor.epoch && transaction.cursor.revision <= this.cursorValue.revision) {
             return;
         }
-        const nextEntities = cloneEntities(this.entities);
-        // A transaction is invisible until its storage write succeeds. Deep-clone
-        // memberships because row deletion edits their ordered ID arrays.
-        const nextQueries = new Map([...this.liveQueries.entries()].map(([signature, window]) => [signature, cloneWindow(window)]));
+        const nextEntities = new Map(this.entities);
+        const copiedEntities = new Set();
+        // Copy only changed memberships; untouched immutable windows stay shared.
+        const nextQueries = new Map(this.liveQueries);
         const changedWindows = new Set();
-        if (this.cursorValue && this.cursorValue.epoch !== transaction.cursor.epoch) {
+        const epochChanged = Boolean(this.cursorValue && this.cursorValue.epoch !== transaction.cursor.epoch);
+        if (epochChanged) {
             for (const signature of nextQueries.keys())
                 changedWindows.add(signature);
             nextEntities.clear();
             nextQueries.clear();
-            this.windowOwned.clear();
         }
         for (const change of transaction.changes) {
             for (const [signature, window] of nextQueries) {
                 if (window.entity === change.entity && window.ids.includes(change.id))
                     changedWindows.add(signature);
             }
-            const rows = nextEntities.get(change.entity) ?? new Map();
-            nextEntities.set(change.entity, rows);
+            if (!copiedEntities.has(change.entity)) {
+                nextEntities.set(change.entity, new Map(nextEntities.get(change.entity)));
+                copiedEntities.add(change.entity);
+            }
+            const rows = nextEntities.get(change.entity);
             if (change.operation === "delete") {
                 rows.delete(change.id);
                 for (const window of nextQueries.values()) {
                     if (window.entity === change.entity && window.ids.includes(change.id)) {
-                        window.ids = window.ids.filter((id) => id !== change.id);
+                        nextQueries.set(window.signature, { ...window, ids: window.ids.filter((id) => id !== change.id) });
                     }
                 }
             }
+            // Change-feed rows are projections, just like collection snapshots.
+            // A narrow subscription must not erase fields supplied by another one.
             else if (change.newValue)
-                rows.set(change.id, cloneRow(change.newValue));
+                rows.set(change.id, { ...rows.get(change.id), ...cloneRow(change.newValue) });
         }
         for (const membership of transaction.memberships ?? []) {
             nextQueries.set(membership.signature, normalizeWindow(membership));
             changedWindows.add(membership.signature);
         }
-        const snapshot = snapshotFrom(transaction.cursor, nextEntities, nextQueries);
+        const snapshot = storageSnapshotFrom(transaction.cursor, nextEntities, nextQueries);
         const writeScope = this.scopeValue;
         await this.persist(() => this.storage?.applyTransaction(transaction, snapshot, writeScope));
+        if (this.storage?.readChanges)
+            await this.mergeStoredChanges(nextEntities, nextQueries);
+        if (epochChanged) {
+            this.invalidateEntityVersions();
+            this.windowOwned.clear();
+        }
         // Publish the whole committed transaction in one state swap and notify UI
         // exactly once. No subscriber can observe a partial entity/query update.
         this.entities = nextEntities;
         this.liveQueries = nextQueries;
+        for (const change of transaction.changes)
+            this.markEntityChanged(change.entity, [change.id]);
         for (const signature of changedWindows)
             this.markWindowChanged(signature);
         this.cursorValue = { ...transaction.cursor };
@@ -447,7 +862,7 @@ export class LocalReplica {
         // created row can disappear from a complete Replica Collection between
         // the transaction and its membership delta.
         this.reconcileCommands(false);
-        this.notify();
+        this.notify(true);
     }
     entity(entity, id) {
         if (!this.scopeLoaded)
@@ -472,33 +887,274 @@ export class LocalReplica {
     }
     /** Resolve several IDs from one atomic Local Replica version. */
     entityBatch(entity, ids) {
-        return ids.map((id) => this.entity(entity, id));
+        if (!this.scopeLoaded)
+            return ids.map(() => undefined);
+        const base = this.entities.get(entity);
+        if (this.pendingCommands.size === 0)
+            return ids.map(id => {
+                const row = base?.get(id);
+                return row === undefined ? undefined : cloneRow(row);
+            });
+        const rows = new Map();
+        for (const id of ids)
+            rows.set(id, base?.get(id));
+        if (rows.size)
+            for (const command of this.pendingCommands.values()) {
+                for (const patch of command.patches) {
+                    if ((patch.entity ?? patch.collection) !== entity || !rows.has(patch.rowId))
+                        continue;
+                    if (patch.op === 'delete')
+                        rows.set(patch.rowId, undefined);
+                    else if (patch.op === 'insert' || patch.op === 'upsert')
+                        rows.set(patch.rowId, patch.fields);
+                    else if (patch.op === 'patch')
+                        rows.set(patch.rowId, { ...(rows.get(patch.rowId) ?? {}), ...patch.fields });
+                }
+            }
+        // Preserve caller order and return independent values for duplicate IDs.
+        return ids.map(id => {
+            const row = rows.get(id);
+            return row === undefined ? undefined : cloneRow(row);
+        });
     }
     /** All cached rows for one normalized entity, including optimistic overlays. */
     entityRows(entity) {
         if (!this.scopeLoaded)
             return [];
-        const ids = new Set(this.entities.get(entity)?.keys() ?? []);
+        if (this.pendingCommands.size === 0) {
+            return Array.from(this.entities.get(entity)?.values() ?? [], row => cloneRow(row));
+        }
+        // Apply the journal once for the table, not once per row. Keep deleted
+        // entries as tombstones until projection so delete/reinsert retains the
+        // established ID order. Base rows and journal fields stay untouched.
+        const rows = new Map(this.entities.get(entity));
         for (const command of this.pendingCommands.values()) {
             for (const patch of command.patches) {
-                if ((patch.entity ?? patch.collection) === entity)
+                if ((patch.entity ?? patch.collection) !== entity)
+                    continue;
+                if (patch.op === "delete")
+                    rows.set(patch.rowId, undefined);
+                else if (patch.op === "insert" || patch.op === "upsert")
+                    rows.set(patch.rowId, patch.fields);
+                else if (patch.op === "patch")
+                    rows.set(patch.rowId, { ...(rows.get(patch.rowId) ?? {}), ...patch.fields });
+            }
+        }
+        const result = [];
+        // Clone only the final values, including nested patch fields. Callers must
+        // not be able to mutate either authoritative rows or the pending journal.
+        for (const row of rows.values())
+            if (row !== undefined)
+                result.push(cloneRow(row));
+        return result;
+    }
+    /** Serialize against confirmed publications, then capture just the pending journal.
+     * IndexedDB keeps the base transaction consistent without copying any tables.
+     */
+    pendingReducerPatches() {
+        return [...this.pendingCommands.values()].flatMap(command => command.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: structuredClone(patch.fields) }));
+    }
+    withReadView(coverage, pending, run, residentOnly = false) {
+        if (residentOnly) {
+            if (!this.scopeLoaded)
+                return Promise.reject(new Error('Local replica scope is not ready'));
+            const known = coverage();
+            const patches = typeof pending !== 'boolean' ? [...pending] : pending ? [...this.pendingCommands.values()].flatMap(command => command.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 short speculative read never waits for disk. Its publication is
+            // checked against the captured execution version, and durable admission
+            // re-executes against the coordinated journal before sending anything.
+            return run(overlayReadView(memoryReadView(this.entities, this.residentCoverage(known)), known, patches));
+        }
+        const operation = this.enqueueApplication(async () => {
+            if (!this.scopeLoaded)
+                throw new Error('Local replica scope is not ready');
+            await this.persistence;
+            const known = coverage();
+            const patches = typeof pending !== 'boolean' ? [...pending] : pending ? [...this.pendingCommands.values()].flatMap(command => command.patches.map(patch => {
+                const entity = patch.entity ?? patch.collection;
+                return patch.op === 'delete' ? { entity, rowId: patch.rowId, op: 'delete' } : { entity, rowId: patch.rowId, op: patch.op === 'upsert' ? 'insert' : patch.op, fields: patch.fields };
+            })) : [];
+            const apply = (base) => run(overlayReadView(base, known, patches));
+            // The visible working set is already resident. Execute against that
+            // consistent view first instead of sending hot row reads back to disk.
+            // A missing row/field retries the whole prediction in one disk read
+            // transaction, never mixes rows from two different snapshots.
+            try {
+                return await apply(memoryReadView(this.entities, this.residentCoverage(known)));
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.name !== 'IncompleteReplicaError' || !this.storage?.withReadView)
+                    throw error;
+                return this.storage.withReadView(this.scopeValue, known, apply);
+            }
+        }, true);
+        return operation;
+    }
+    /** SDK execution snapshot: capture immutable row references now, copy a table only when used. */
+    captureExecutionRows(includePending) {
+        const captured = new Map([...this.entities].map(([entity, rows]) => [entity, [...rows.entries()]]));
+        const patches = includePending ? [...this.pendingCommands.values()].flatMap(command => command.patches) : [];
+        const loaded = this.scopeLoaded;
+        const materialized = new Map();
+        return entity => {
+            const prior = materialized.get(entity);
+            if (prior)
+                return prior;
+            const rows = new Map(loaded ? captured.get(entity) ?? [] : []);
+            const ids = new Set(rows.keys());
+            if (loaded)
+                for (const patch of patches) {
+                    if ((patch.entity ?? patch.collection) !== entity)
+                        continue;
                     ids.add(patch.rowId);
+                    if (patch.op === "delete")
+                        rows.delete(patch.rowId);
+                    else if (patch.op === "patch")
+                        rows.set(patch.rowId, { ...rows.get(patch.rowId), ...patch.fields });
+                    else
+                        rows.set(patch.rowId, patch.fields);
+                }
+            const result = [...ids].flatMap(id => { const row = rows.get(id); return row ? [cloneRow(row)] : []; });
+            materialized.set(entity, result);
+            return result;
+        };
+    }
+    /** Complete registered slices prove narrower reads without another subscription. */
+    captureReadCoverage(base) {
+        const coverage = { ...base };
+        for (const [signature, { definition, args }] of this.replicaPlans) {
+            const known = coverage[definition.table];
+            if (!known || !this.windowIsComplete(signature))
+                continue;
+            const terms = [];
+            let valid = true;
+            for (const [argument, column] of Object.entries(definition.equalFilters ?? {})) {
+                const value = args[argument];
+                if (value === undefined || value !== null && !['string', 'number', 'boolean'].includes(typeof value)) {
+                    valid = false;
+                    break;
+                }
+                terms.push({ column, op: 'eq', value: value });
             }
+            if (!valid)
+                continue;
+            for (const column of definition.excludeWhenSet ?? [])
+                terms.push({ column, op: 'isNull' });
+            coverage[definition.table] = {
+                ...known,
+                complete: known.complete || terms.length === 0,
+                completeWhere: terms.length ? [...(known.completeWhere ?? []), { and: terms }] : known.completeWhere,
+            };
         }
-        return [...ids]
-            .map((id) => this.entity(entity, id))
-            .filter((row) => row !== undefined);
+        return coverage;
+    }
+    /** Read execution eligibility without copying a window's ordered IDs and hashes. */
+    windowIsComplete(signature) {
+        const window = this.liveQueries.get(signature);
+        return this.scopeLoaded && window?.completeness === "complete" && window.truncated !== true;
+    }
+    /** A watermark reads only cursor/integrity presence, never copied IDs or hashes. */
+    windowCanAdvance(signature, revision) {
+        const window = this.liveQueries.get(signature);
+        return Boolean(window?.cursor && window.cursor.revision < revision && window.hashes);
+    }
+    /** SDK watch snapshots: unchanged rows are not cloned again on every notification. */
+    watchRows(signature, cache) {
+        const window = this.scopeLoaded ? this.liveQueries.get(signature) : undefined;
+        if (!window) {
+            cache.clear();
+            return [];
+        }
+        // A pending write to a different row must not disable shared immutable
+        // snapshots for every newly mounted view in the application.
+        let pendingRows;
+        for (const command of this.pendingCommands.values()) {
+            for (const patch of command.patches) {
+                if ((patch.entity ?? patch.collection) === window.entity)
+                    (pendingRows ??= new Set()).add(patch.rowId);
+            }
+        }
+        const read = (id) => {
+            const version = this.rowVersion(window.entity, id);
+            const prior = cache.get(id);
+            if (prior?.version === version)
+                return prior.row;
+            const base = !pendingRows?.has(id) ? this.entities.get(window.entity)?.get(id) : undefined;
+            let next;
+            if (base) {
+                let copy = this.visibleRowCopies.get(base);
+                if (!copy) {
+                    copy = cloneRow(base);
+                    this.visibleRowCopies.set(base, copy);
+                }
+                next = copy;
+            }
+            else
+                next = this.entity(window.entity, id);
+            // A matching server echo or removal of its prediction changes protocol
+            // versions without changing the row the component sees.
+            const row = prior && sameReplicaValue(prior.row, next) ? prior.row : next;
+            cache.set(id, { version, row });
+            return row;
+        };
+        const ids = this.effectiveMembership(window, read);
+        const retained = new Set(ids);
+        for (const id of cache.keys())
+            if (!retained.has(id))
+                cache.delete(id);
+        return ids.map(read).filter((row) => row !== undefined);
     }
     /** Exact only when an authoritative, non-truncated Replica Collection covers the entity. */
     entityCompleteness(entity) {
-        if (!this.scopeLoaded)
+        if (!this.scopeLoaded || this.residentPartialTables.has(entity))
             return "partial";
         return [...this.liveQueries.values()].some((window) => (window.kind === "replica"
             && window.entity === entity
             && window.completeness === "complete"
             && window.truncated !== true)) ? "complete" : "partial";
     }
-    liveQuery(signature) {
+    // Bounded derived snapshots, containing only rows in recently read windows.
+    readSnapshots = new Map();
+    liveQuerySnapshot(signature) {
+        let snapshot = this.readSnapshots.get(signature);
+        if (!snapshot) {
+            if (this.readSnapshots.size >= 64) {
+                const cold = [...this.readSnapshots.keys()].find(key => !this.retainedWindows.has(key));
+                if (cold !== undefined)
+                    this.readSnapshots.delete(cold);
+            }
+            snapshot = { version: -1, rowsVersion: -1, rows: [], cache: new Map() };
+        }
+        // Mounted windows cannot be evicted. Reordering them on every store read
+        // only allocates Map tombstones; LRU order matters for cold windows alone.
+        if (!this.retainedWindows.has(signature))
+            this.readSnapshots.delete(signature);
+        this.readSnapshots.set(signature, snapshot);
+        if (snapshot.version !== this.windowVersion(signature) || snapshot.freshness !== this.freshnessValue) {
+            const rowsVersion = this.windowRowsVersion(signature);
+            if (snapshot.rowsVersion !== rowsVersion) {
+                const rows = this.watchRows(signature, snapshot.cache);
+                if (rows.length !== snapshot.rows.length || rows.some((row, index) => row !== snapshot.rows[index]))
+                    snapshot.rows = rows;
+                snapshot.rowsVersion = rowsVersion;
+            }
+            const next = this.liveQuery(signature, snapshot.rows);
+            const previous = snapshot.result;
+            if (!previous || previous.rows !== next.rows || !sameReplicaValue({ ...previous, rows: undefined }, { ...next, rows: undefined }))
+                snapshot.result = next;
+            snapshot.version = this.windowVersion(signature);
+            snapshot.freshness = this.freshnessValue;
+        }
+        return snapshot.result;
+    }
+    liveQuery(signature, cachedRows) {
+        return this.windowResult(signature, cachedRows);
+    }
+    windowResult(signature, cachedRows) {
         if (!this.scopeLoaded) {
             return { rows: [], ids: [], source: "cache", completeness: "partial", freshness: this.freshnessValue };
         }
@@ -506,8 +1162,8 @@ export class LocalReplica {
         if (!membership) {
             return { rows: [], ids: [], source: "cache", completeness: "partial", freshness: this.freshnessValue };
         }
-        const ids = this.effectiveMembership(membership);
-        const rows = ids
+        const ids = cachedRows ? cachedRows.map(row => String(row[membership.key])) : this.effectiveMembership(membership);
+        const rows = cachedRows ?? ids
             .map((id) => this.entity(membership.entity, id))
             .filter((row) => row !== undefined);
         const metadata = windowResultMetadata(membership.resultSkeleton, membership.resultPath);
@@ -516,13 +1172,13 @@ export class LocalReplica {
             ids,
             ...metadata,
             source: this.freshnessValue === "current" ? membership.source : "cache",
-            completeness: membership.completeness,
+            completeness: membership.ids.every(id => this.entities.get(membership.entity)?.has(id)) ? membership.completeness : 'partial',
             freshness: this.freshnessValue,
         };
     }
     /** Rows and protocol-owned completeness for one Replica Collection window. */
-    collectionState(signature) {
-        const result = this.liveQuery(signature);
+    collectionState(signature, cachedRows) {
+        const result = this.windowResult(signature, cachedRows);
         const window = this.scopeLoaded ? this.liveQueries.get(signature) : undefined;
         return {
             ...result,
@@ -556,24 +1212,45 @@ export class LocalReplica {
         this.persistence = attempt.catch(() => undefined);
         return attempt;
     }
-    notify() {
+    notify(executionChanged = false) {
+        if (this.disposed)
+            return;
+        if (executionChanged)
+            this.trimResidentRows();
+        if (executionChanged)
+            this.executionVersionValue += 1;
         this.versionValue += 1;
         for (const listener of [...this.listeners])
             listener();
     }
-    markWindowChanged(signature) {
+    markEntityChanged(entity, ids) {
+        const version = ++this.entityVersionClock;
+        this.entityVersions.set(entity, version);
+        for (const id of ids ?? this.entities.get(entity)?.keys() ?? [])
+            this.rowVersions.set(`${entity}\0${id}`, version);
+    }
+    invalidateEntityVersions() {
+        this.entityVersionFloor = ++this.entityVersionClock;
+        this.entityVersions.clear();
+        this.rowVersions.clear();
+        this.readSnapshots.clear();
+    }
+    markWindowChanged(signature, rowsChanged = true) {
         this.windowVersionClock += 1;
         this.windowVersions.set(signature, this.windowVersionClock);
+        if (rowsChanged)
+            this.windowRowsVersions.set(signature, this.windowVersionClock);
     }
     markWindowsForPatches(patches) {
         const affected = new Set();
         for (const patch of patches) {
             const entity = patch.entity ?? patch.collection;
+            if (entity)
+                this.markEntityChanged(entity, [patch.rowId]);
             for (const [signature, window] of this.liveQueries) {
                 if (window.entity !== entity)
                     continue;
-                const currentIDs = this.effectiveMembership(window);
-                if (window.ids.includes(patch.rowId) || currentIDs.includes(patch.rowId)) {
+                if (window.ids.includes(patch.rowId)) {
                     affected.add(signature);
                     continue;
                 }
@@ -593,7 +1270,7 @@ export class LocalReplica {
      * the committed server membership, so rejection and reconciliation are
      * reversible and never write optimistic IDs to storage.
      */
-    effectiveMembership(window) {
+    effectiveMembership(window, read = id => this.entity(window.entity, id)) {
         const plan = this.replicaPlans.get(window.signature);
         const patches = [...this.pendingCommands.values()]
             .flatMap((command) => command.patches)
@@ -609,7 +1286,7 @@ export class LocalReplica {
         const ids = new Set(window.ids);
         const touched = new Set(patches.map((patch) => patch.rowId));
         for (const id of touched) {
-            const row = this.entity(window.entity, id);
+            const row = read(id);
             if (row && replicaRowMatchesPlan(row, plan.definition, plan.args))
                 ids.add(id);
             else
@@ -625,7 +1302,9 @@ export class LocalReplica {
         const orderBy = plan.definition.orderBy;
         if (!orderBy)
             return [...retained, ...additions.sort(compareReplicaKeys)];
-        return effectiveIDs.sort((left, right) => compareReplicaMembershipRows(this.entity(window.entity, left), this.entity(window.entity, right), window.key, orderBy, plan.definition.orderDirection));
+        // The comparator may run O(n log n) times. Resolve each immutable row once.
+        const rows = new Map(effectiveIDs.map(id => [id, read(id)]));
+        return effectiveIDs.sort((left, right) => compareReplicaMembershipRows(rows.get(left), rows.get(right), window.key, orderBy, plan.definition.orderDirection));
     }
     trackWindowOwnership(window, rows, previous) {
         const owned = this.windowOwned.get(window.signature) ?? new Map();
@@ -651,9 +1330,14 @@ export class LocalReplica {
         if (!owned)
             return;
         const sourceWindow = this.liveQueries.get(signature);
+        const referenced = new Set();
+        for (const window of this.liveQueries.values()) {
+            if (window.entity === sourceWindow?.entity)
+                for (const id of window.ids)
+                    referenced.add(id);
+        }
         for (const [id] of owned) {
-            const stillReferenced = [...this.liveQueries.values()].some((window) => (window.entity === sourceWindow?.entity && window.ids.includes(id)));
-            if (!stillReferenced && sourceWindow) {
+            if (!referenced.has(id) && sourceWindow) {
                 this.entities.get(sourceWindow.entity)?.delete(id);
             }
         }
@@ -675,6 +1359,13 @@ export class LocalReplica {
         this.windowOwned.delete(signature);
     }
 }
+function sameWindowRowDefinition(previous, next) {
+    return previous !== undefined && previous.entity === next.entity && previous.key === next.key
+        && previous.kind === next.kind && previous.completeness === next.completeness
+        && previous.truncated === next.truncated && previous.orderBy === next.orderBy
+        && previous.orderDirection === next.orderDirection && previous.ids.length === next.ids.length
+        && previous.ids.every((id, index) => id === next.ids[index]);
+}
 function replicaRowMatchesPlan(row, definition, args) {
     // The module manifest encodes equalFilters as argument name -> row column
     // (for example `{ id: "_id" }`). Keep this aligned with artifact parsing.
@@ -710,6 +1401,14 @@ function replicaOrderValue(value) {
     return typeof value === "string" || typeof value === "number" ? value : null;
 }
 export class MemoryLocalReplicaStorage {
+    sessions = new Map();
+    async loadSession(scope) { const value = this.sessions.get(scope); return value ? structuredClone(value) : undefined; }
+    async saveSession(scope, value) {
+        if (value)
+            this.sessions.set(scope, structuredClone(value));
+        else
+            this.sessions.delete(scope);
+    }
     values = new Map();
     async load(scope = defaultReplicaScope) {
         const value = this.values.get(normalizeReplicaScope(scope));
@@ -763,6 +1462,19 @@ function cloneOptimisticPatch(patch) {
         return { ...patch, fields: structuredClone(patch.fields) };
     return { ...patch, fields: structuredClone(patch.fields) };
 }
+function sameReplicaValue(left, right) {
+    if (left === right)
+        return true;
+    if (!left || !right || typeof left !== "object" || typeof right !== "object")
+        return false;
+    if (Array.isArray(left))
+        return Array.isArray(right) && left.length === right.length && left.every((value, index) => sameReplicaValue(value, right[index]));
+    if (Array.isArray(right))
+        return false;
+    const a = left, b = right;
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every(key => Object.prototype.hasOwnProperty.call(b, key) && sameReplicaValue(a[key], b[key]));
+}
 function cloneRow(row) { return structuredClone(row); }
 function windowResultMetadata(result, resultPath) {
     if (!result || typeof result !== "object" || Array.isArray(result) || !resultPath?.length)
@@ -833,9 +1545,6 @@ function hydratedTransactionFloor(persisted, windows) {
     // unsafe floor across a browser restart.
     return { epoch, revision: Math.min(persisted.revision, provenRevision) };
 }
-function cloneEntities(source) {
-    return new Map([...source].map(([entity, rows]) => [entity, new Map([...rows].map(([id, row]) => [id, cloneRow(row)]))]));
-}
 function entitiesFromSnapshot(source) {
     return new Map(Object.entries(source).map(([entity, rows]) => [entity, new Map(Object.entries(rows).map(([id, row]) => [id, cloneRow(row)]))]));
 }
@@ -854,4 +1563,46 @@ function normalizeReplicaScope(scope) {
         return defaultReplicaScope;
     return scope;
 }
+/** Build snapshot accessors only if an adapter needs them. Metadata-only writes
+ * never enumerate tables/windows; delta adapters clone values on first access. */
+function storageSnapshotFrom(cursor, source, windows) {
+    // Capture membership now even if an adapter reads its snapshot after the
+    // persistence promise resolves and reconciliation replaces map entries.
+    const capturedSource = new Map(source);
+    const capturedWindows = new Map(windows);
+    const snapshot = { cursor: cursor ? { ...cursor } : undefined };
+    Object.defineProperty(snapshot, "entities", { enumerable: true, configurable: true, get() {
+            const entities = {};
+            for (const [entity, rows] of capturedSource) {
+                // Committed maps and rows are immutable. Retain that version without
+                // allocating entries for unrelated tables; clone values on first access.
+                const captured = rows;
+                Object.defineProperty(entities, entity, { enumerable: true, configurable: true, get() {
+                        const value = {};
+                        for (const [id, row] of captured)
+                            Object.defineProperty(value, id, { enumerable: true, configurable: true, get() {
+                                    const copy = cloneRow(row);
+                                    Object.defineProperty(value, id, { enumerable: true, configurable: true, writable: true, value: copy });
+                                    return copy;
+                                } });
+                        Object.defineProperty(entities, entity, { enumerable: true, configurable: true, writable: true, value });
+                        return value;
+                    } });
+            }
+            Object.defineProperty(snapshot, "entities", { enumerable: true, configurable: true, writable: true, value: entities });
+            return entities;
+        } });
+    Object.defineProperty(snapshot, "liveQueries", { enumerable: true, configurable: true, get() {
+            const liveQueries = {};
+            for (const [key, window] of capturedWindows)
+                Object.defineProperty(liveQueries, key, { enumerable: true, configurable: true, get() {
+                        const copy = cloneWindow(window);
+                        Object.defineProperty(liveQueries, key, { enumerable: true, configurable: true, writable: true, value: copy });
+                        return copy;
+                    } });
+            Object.defineProperty(snapshot, "liveQueries", { enumerable: true, configurable: true, writable: true, value: liveQueries });
+            return liveQueries;
+        } });
+    return snapshot;
+}
 //# sourceMappingURL=local-replica.js.map