@rocicorp/zero 0.6.2024112102 → 0.7.2024120100

package/out/zero-cache/src/services/view-syncer/cvr-store.js

@@ -3,25 +3,96 @@ import { assert } from '../../../../shared/src/asserts.js';
 import { CustomKeyMap } from '../../../../shared/src/custom-key-map.js';
 import { deepEqual, } from '../../../../shared/src/json.js';
 import { must } from '../../../../shared/src/must.js';
+import { promiseVoid } from '../../../../shared/src/resolved-promises.js';
+import { sleep } from '../../../../shared/src/sleep.js';
 import { astSchema } from '../../../../zero-protocol/src/ast.js';
-import { versionToLexi } from '../../types/lexi-version.js';
-import { rowIDHash } from '../../types/row-key.js';
+import { ErrorKind } from '../../../../zero-protocol/src/error.js';
+import { ErrorForClient } from '../../types/error-for-client.js';
+import { rowIDString } from '../../types/row-key.js';
 import { rowRecordToRowsRow, rowsRowToRowRecord, } from './schema/cvr.js';
-import { cmpVersions, versionFromString, versionString, } from './schema/types.js';
+import { cmpVersions, EMPTY_CVR_VERSION, versionFromString, versionString, versionToNullableCookie, } from './schema/types.js';
+/**
+ * The RowRecordCache is an in-memory cache of the `cvr.rows` tables that
+ * operates as both a write-through and write-back cache.
+ *
+ * For "small" CVR updates (i.e. zero or small numbers of rows) the
+ * RowRecordCache operates as write-through, executing commits in
+ * {@link executeRowUpdates()} before they are {@link apply}-ed to the
+ * in-memory state.
+ *
+ * For "large" CVR updates (i.e. with many rows), the cache switches to a
+ * write-back mode of operation, in which {@link executeRowUpdates()} is a
+ * no-op, and {@link apply()} initiates a background task to flush the pending
+ * row changes to the store. This allows the client poke to be completed and
+ * committed on the client without waiting for the heavyweight operation of
+ * committing the row records to the CVR store.
+ *
+ * Note that when the cache is in write-back mode, all updates become
+ * write-back (i.e. asynchronously flushed) until the pending update queue is
+ * fully flushed. This is required because updates must be applied in version
+ * order. As with all pending work systems in zero-cache, multiple pending
+ * updates are coalesced to reduce buildup of work.
+ *
+ * ### High level consistency
+ *
+ * Note that the above caching scheme only applies to the row data in `cvr.rows`
+ * and corresponding `cvr.rowsVersion` tables. CVR metadata and query
+ * information, on the other hand, are always committed before completing the
+ * client poke. In this manner, the difference between the `version` column in
+ * `cvr.instances` and the analogous column in `cvr.rowsVersion` determines
+ * whether the data in the store is consistent, or whether it is awaiting a
+ * pending update.
+ *
+ * The logic in {@link CVRStore.load()} takes this into account by loading both
+ * the `cvr.instances` version and the `cvr.rowsVersion` version and checking
+ * if they are in sync, waiting for a configurable delay until they are.
+ *
+ * ### Eventual conversion
+ *
+ * In the event of a continual stream of mutations (e.g. an animation-style
+ * app), it is conceivable that the row record data be continually behind
+ * the CVR metadata. In order to effect eventual convergence, a new view-syncer
+ * signals the current view-syncer to stop updating by writing new `owner`
+ * information to the `cvr.instances` row. This effectively stops the mutation
+ * processing (in {@link CVRStore.#checkVersionAndOwnership}) so that the row
+ * data can eventually catch up, allowing the new view-syncer to take over.
+ *
+ * Of course, there is the pathological situation in which a view-syncer
+ * process crashes before the pending row updates are flushed. In this case,
+ * the wait timeout will elapse and the CVR considered invalid.
+ */
 class RowRecordCache {
+    // The state in the #cache is always in sync with the CVR metadata
+    // (i.e. cvr.instances). It may contain information that has not yet
+    // been flushed to cvr.rows.
     #cache;
+    #lc;
     #db;
     #cvrID;
-    constructor(db, cvrID) {
+    #failService;
+    #deferredRowFlushThreshold;
+    #setTimeout;
+    // Write-back cache state.
+    #pending = new CustomKeyMap(rowIDString);
+    #pendingRowsVersion = null;
+    #flushing = null;
+    constructor(lc, db, cvrID, failService, deferredRowFlushThreshold = 100, setTimeoutFn = setTimeout) {
+        this.#lc = lc;
         this.#db = db;
         this.#cvrID = cvrID;
+        this.#failService = failService;
+        this.#deferredRowFlushThreshold = deferredRowFlushThreshold;
+        this.#setTimeout = setTimeoutFn;
     }
     async #ensureLoaded() {
         if (this.#cache) {
             return this.#cache;
         }
         const r = resolver();
-        const cache = new CustomKeyMap(rowIDHash);
+        // Set this.#cache immediately (before await) so that only one db
+        // query is made even if there are multiple callers.
+        this.#cache = r.promise;
+        const cache = new CustomKeyMap(rowIDString);
         for await (const rows of this.#db `SELECT * FROM cvr.rows WHERE "clientGroupID" = ${this.#cvrID} AND "refCounts" IS NOT NULL`
             // TODO(arv): Arbitrary page size
             .cursor(5000)) {
@@ -31,13 +102,27 @@ class RowRecordCache {
             }
         }
         r.resolve(cache);
-        this.#cache = r.promise;
         return this.#cache;
     }
     getRowRecords() {
         return this.#ensureLoaded();
     }
-    async flush(rowRecords) {
+    /**
+     * Applies the `rowRecords` corresponding to the `rowsVersion`
+     * to the cache, indicating whether the corresponding updates
+     * (generated by {@link executeRowUpdates}) were `flushed`.
+     *
+     * If `flushed` is false, the RowRecordCache will flush the records
+     * asynchronously.
+     *
+     * Note that `apply()` indicates that the CVR metadata associated with
+     * the `rowRecords` was successfully committed, which essentially means
+     * that this process has the unconditional right (and responsibility) of
+     * following up with a flush of the `rowRecords`. In particular, the
+     * commit of row records are not conditioned on the version or ownership
+     * columns of the `cvr.instances` row.
+     */
+    async apply(rowRecords, rowsVersion, flushed) {
         const cache = await this.#ensureLoaded();
         for (const row of rowRecords) {
             if (row.refCounts === null) {
@@ -46,11 +131,114 @@ class RowRecordCache {
             else {
                 cache.set(row.id, row);
             }
+            if (!flushed) {
+                this.#pending.set(row.id, row);
+            }
+        }
+        this.#pendingRowsVersion = rowsVersion;
+        // Initiate a flush if not already flushing.
+        if (!flushed && this.#flushing === null) {
+            this.#flushing = resolver();
+            this.#setTimeout(() => this.#flush(), 0);
         }
     }
+    async #flush() {
+        const flushing = must(this.#flushing);
+        try {
+            while (this.#pending.size) {
+                const start = Date.now();
+                const { rows, rowsVersion } = await this.#db.begin(tx => {
+                    // Note: This code block is synchronous, guaranteeing that the
+                    // #pendingRowsVersion is consistent with the #pending rows.
+                    const rows = this.#pending.size;
+                    const rowsVersion = must(this.#pendingRowsVersion);
+                    this.executeRowUpdates(tx, rowsVersion, [...this.#pending.values()], 'force');
+                    this.#pending.clear();
+                    return { rows, rowsVersion };
+                });
+                this.#lc.debug?.(`flushed ${rows} rows to ${versionString(rowsVersion)} (${Date.now() - start} ms)`);
+                // Note: apply() may have called while the transaction was committing,
+                //       which will result in looping to commit the next #pending batch.
+            }
+            this.#lc.debug?.(`pending rows flushed to ${versionToNullableCookie(this.#pendingRowsVersion)}`);
+            flushing.resolve();
+            this.#flushing = null;
+        }
+        catch (e) {
+            flushing.reject(e);
+            this.#failService(e);
+        }
+    }
+    /**
+     * Returns a promise that resolves when all outstanding row-records
+     * have been committed.
+     */
+    flushed() {
+        return this.#flushing ? this.#flushing.promise : promiseVoid;
+    }
     clear() {
+        // Note: Only the #cache is cleared. #pending updates, on the other hand,
+        // comprise canonical (i.e. already flushed) data and must be flushed
+        // even if the snapshot of the present state (the #cache) is cleared.
         this.#cache = undefined;
     }
+    async *catchupRowPatches(lc, afterVersion, upToCVR, excludeQueryHashes = []) {
+        if (cmpVersions(afterVersion, upToCVR.version) >= 0) {
+            return;
+        }
+        const startMs = Date.now();
+        const sql = this.#db;
+        const start = afterVersion ? versionString(afterVersion) : '';
+        const end = versionString(upToCVR.version);
+        lc.debug?.(`scanning row patches for clients from ${start}`);
+        // Before accessing the CVR db, pending row records must be flushed.
+        // Note that because catchupRowPatches() is called from within the
+        // view syncer lock, this flush is guaranteed to complete since no
+        // new CVR updates can happen while the lock is held.
+        await this.flushed();
+        const flushMs = Date.now() - startMs;
+        const query = excludeQueryHashes.length === 0
+            ? sql `SELECT * FROM cvr.rows
+        WHERE "clientGroupID" = ${this.#cvrID}
+          AND "patchVersion" > ${start}
+          AND "patchVersion" <= ${end}`
+            : // Exclude rows that were already sent as part of query hydration.
+                sql `SELECT * FROM cvr.rows
+        WHERE "clientGroupID" = ${this.#cvrID}
+          AND "patchVersion" > ${start}
+          AND "patchVersion" <= ${end}
+          AND ("refCounts" IS NULL OR NOT "refCounts" ?| ${excludeQueryHashes})`;
+        yield* query.cursor(10000);
+        const totalMs = Date.now() - startMs;
+        lc.debug?.(`finished row catchup (flush: ${flushMs} ms, total: ${totalMs} ms)`);
+    }
+    executeRowUpdates(tx, version, rowRecordsToFlush, mode) {
+        if (mode === 'allow-defer' && // defer if there are pending updates or
+            (this.#pending.size > 0 || // the new batch is above the limit.
+                rowRecordsToFlush.length > this.#deferredRowFlushThreshold)) {
+            return [];
+        }
+        const rowRecordRows = rowRecordsToFlush.map(r => rowRecordToRowsRow(this.#cvrID, r));
+        const rowsVersion = {
+            clientGroupID: this.#cvrID,
+            version: versionString(version),
+        };
+        const pending = [
+            tx `INSERT INTO cvr."rowsVersion" ${tx(rowsVersion)}
+           ON CONFLICT ("clientGroupID") 
+           DO UPDATE SET ${tx(rowsVersion)}`.execute(),
+        ];
+        let i = 0;
+        while (i < rowRecordRows.length) {
+            pending.push(tx `INSERT INTO cvr.rows ${tx(rowRecordRows.slice(i, i + ROW_RECORD_UPSERT_BATCH_SIZE))} 
+          ON CONFLICT ("clientGroupID", "schema", "table", "rowKey")
+          DO UPDATE SET "rowVersion" = excluded."rowVersion",
+            "patchVersion" = excluded."patchVersion",
+            "refCounts" = excluded."refCounts"`.execute());
+            i += ROW_RECORD_UPSERT_BATCH_SIZE;
+        }
+        return pending;
+    }
 }
 function asQuery(row) {
     const ast = astSchema.parse(row.clientAST);
@@ -72,56 +260,120 @@ function asQuery(row) {
             transformationVersion: maybeVersion(row.transformationVersion),
         };
 }
+// The time to wait between load attempts.
+const LOAD_ATTEMPT_INTERVAL_MS = 500;
+// The maximum number of load() attempts if the rowsVersion is behind.
+// This currently results in a maximum catchup time of ~5 seconds, after
+// which we give up and consider the CVR invalid.
+//
+// TODO: Make this configurable with something like --max-catchup-wait-ms,
+//       as it is technically application specific.
+const MAX_LOAD_ATTEMPTS = 10;
 export class CVRStore {
     #lc;
+    #taskID;
     #id;
     #db;
     #writes = new Set();
-    #pendingRowRecordPuts = new CustomKeyMap(rowIDHash);
+    #pendingRowRecordPuts = new CustomKeyMap(rowIDString);
     #rowCache;
-    constructor(lc, db, cvrID) {
+    #loadAttemptIntervalMs;
+    #maxLoadAttempts;
+    constructor(lc, db, taskID, cvrID, failService, loadAttemptIntervalMs = LOAD_ATTEMPT_INTERVAL_MS, maxLoadAttempts = MAX_LOAD_ATTEMPTS, deferredRowFlushThreshold = 100, // somewhat arbitrary
+    setTimeoutFn = setTimeout) {
         this.#lc = lc;
         this.#db = db;
+        this.#taskID = taskID;
         this.#id = cvrID;
-        this.#rowCache = new RowRecordCache(db, cvrID);
+        this.#rowCache = new RowRecordCache(lc, db, cvrID, failService, deferredRowFlushThreshold, setTimeoutFn);
+        this.#loadAttemptIntervalMs = loadAttemptIntervalMs;
+        this.#maxLoadAttempts = maxLoadAttempts;
     }
-    async load() {
+    async load(lastConnectTime) {
+        let err;
+        for (let i = 0; i < this.#maxLoadAttempts; i++) {
+            if (i > 0) {
+                await sleep(this.#loadAttemptIntervalMs);
+            }
+            const result = await this.#load(lastConnectTime);
+            if (result instanceof RowsVersionBehindError) {
+                this.#lc.info?.(`attempt ${i + 1}: ${String(result)}`);
+                err = result;
+                continue;
+            }
+            return result;
+        }
+        assert(err);
+        throw new ErrorForClient([
+            'error',
+            ErrorKind.ClientNotFound,
+            `max attempts exceeded waiting for CVR@${err.cvrVersion} to catch up from ${err.rowsVersion}`,
+        ]);
+    }
+    async #load(lastConnectTime) {
         const start = Date.now();
         const id = this.#id;
         const cvr = {
             id,
-            version: { stateVersion: versionToLexi(0) },
+            version: EMPTY_CVR_VERSION,
             lastActive: 0,
             replicaVersion: null,
             clients: {},
             queries: {},
         };
         const [instance, clientsRows, queryRows, desiresRows] = await this.#db.begin(tx => [
-            tx `SELECT "version", "lastActive", "replicaVersion" FROM cvr.instances WHERE "clientGroupID" = ${id}`,
+            tx `SELECT cvr."version", 
+                 "lastActive", 
+                 "replicaVersion", 
+                 "owner", 
+                 "grantedAt", 
+                 rows."version" as "rowsVersion"
+            FROM cvr.instances AS cvr
+            LEFT JOIN cvr."rowsVersion" AS rows 
+            ON cvr."clientGroupID" = rows."clientGroupID"
+            WHERE cvr."clientGroupID" = ${id}`,
             tx `SELECT "clientID", "patchVersion" FROM cvr.clients WHERE "clientGroupID" = ${id}`,
             tx `SELECT * FROM cvr.queries WHERE "clientGroupID" = ${id} AND (deleted IS NULL OR deleted = FALSE)`,
             tx `SELECT * FROM cvr.desires WHERE "clientGroupID" = ${id} AND (deleted IS NULL OR deleted = FALSE)`,
         ]);
-        if (instance.length !== 0) {
-            assert(instance.length === 1);
-            const { version, lastActive, replicaVersion } = instance[0];
-            cvr.version = versionFromString(version);
-            cvr.lastActive = lastActive;
-            cvr.replicaVersion = replicaVersion;
-        }
-        else {
+        if (instance.length === 0) {
             // This is the first time we see this CVR.
-            const change = {
-                clientGroupID: id,
-                version: versionString(cvr.version),
+            this.putInstance({
+                version: cvr.version,
                 lastActive: 0,
                 replicaVersion: null,
-            };
-            this.#writes.add({
-                stats: { instances: 1 },
-                write: tx => tx `INSERT INTO cvr.instances ${tx(change)}`,
             });
         }
+        else {
+            assert(instance.length === 1);
+            const { version, lastActive, replicaVersion, owner, grantedAt, rowsVersion, } = instance[0];
+            if (owner !== this.#taskID) {
+                if ((grantedAt ?? 0) > lastConnectTime) {
+                    throw new OwnershipError(owner, grantedAt);
+                }
+                else {
+                    // Fire-and-forget an ownership change to signal the current owner.
+                    // Note that the query is structured such that it only succeeds in the
+                    // correct conditions (i.e. gated on `grantedAt`).
+                    void this.#db `
+            UPDATE cvr.instances SET "owner"     = ${this.#taskID}, 
+                                     "grantedAt" = ${lastConnectTime}
+              WHERE "clientGroupID" = ${this.#id} AND
+                    ("grantedAt" IS NULL OR
+                     "grantedAt" <= to_timestamp(${lastConnectTime / 1000}))
+        `.execute();
+                }
+            }
+            if (version !== (rowsVersion ?? EMPTY_CVR_VERSION.stateVersion)) {
+                // This will cause the load() method to wait for row catchup and retry.
+                // Assuming the ownership signal succeeds, the current owner will stop
+                // modifying the CVR and flush its pending row changes.
+                return new RowsVersionBehindError(version, rowsVersion);
+            }
+            cvr.version = versionFromString(version);
+            cvr.lastActive = lastActive;
+            cvr.replicaVersion = replicaVersion;
+        }
         for (const row of clientsRows) {
             const version = versionFromString(row.patchVersion);
             cvr.clients[row.clientID] = {
@@ -156,15 +408,21 @@ export class CVRStore {
         this.#pendingRowRecordPuts.set(row.id, row);
     }
     putInstance({ version, replicaVersion, lastActive, }) {
-        const change = {
-            clientGroupID: this.#id,
-            version: versionString(version),
-            lastActive,
-            replicaVersion,
-        };
         this.#writes.add({
             stats: { instances: 1 },
-            write: tx => tx `INSERT INTO cvr.instances ${tx(change)} ON CONFLICT ("clientGroupID") DO UPDATE SET ${tx(change)}`,
+            write: (tx, lastConnectTime) => {
+                const change = {
+                    clientGroupID: this.#id,
+                    version: versionString(version),
+                    lastActive,
+                    replicaVersion,
+                    owner: this.#taskID,
+                    grantedAt: lastConnectTime,
+                };
+                return tx `
+        INSERT INTO cvr.instances ${tx(change)} 
+          ON CONFLICT ("clientGroupID") DO UPDATE SET ${tx(change)}`;
+            },
         });
     }
     markQueryAsDeleted(version, queryPatch) {
@@ -263,45 +521,18 @@ export class CVRStore {
       `,
         });
     }
-    delDesiredQuery(oldPutVersion, query, client) {
-        this.#writes.add({
-            stats: { desires: 1 },
-            write: tx => tx `DELETE FROM cvr.desires WHERE "clientGroupID" = ${this.#id} AND "clientID" = ${client.id} AND "queryHash" = ${query.id} AND "patchVersion" = ${versionString(oldPutVersion)}`,
-        });
-    }
-    async *catchupRowPatches(lc, afterVersion, upToCVR, excludeQueryHashes = []) {
-        if (cmpVersions(afterVersion, upToCVR.version) >= 0) {
-            lc.debug?.('all clients up to date. no config catchup.');
-            return;
-        }
-        const startMs = Date.now();
-        const sql = this.#db;
-        const start = afterVersion ? versionString(afterVersion) : '';
-        const end = versionString(upToCVR.version);
-        lc.debug?.(`catching up clients from ${start}`);
-        const query = excludeQueryHashes.length === 0
-            ? sql `SELECT * FROM cvr.rows
-        WHERE "clientGroupID" = ${this.#id}
-          AND "patchVersion" > ${start}
-          AND "patchVersion" <= ${end}`
-            : // Exclude rows that were already sent as part of query hydration.
-                sql `SELECT * FROM cvr.rows
-        WHERE "clientGroupID" = ${this.#id}
-          AND "patchVersion" > ${start}
-          AND "patchVersion" <= ${end}
-          AND ("refCounts" IS NULL OR NOT "refCounts" ?| ${excludeQueryHashes})`;
-        yield* query.cursor(10000);
-        lc.debug?.(`finished row catchup (${Date.now() - startMs} ms)`);
+    catchupRowPatches(lc, afterVersion, upToCVR, excludeQueryHashes = []) {
+        return this.#rowCache.catchupRowPatches(lc, afterVersion, upToCVR, excludeQueryHashes);
     }
     async catchupConfigPatches(lc, afterVersion, upToCVR) {
         if (cmpVersions(afterVersion, upToCVR.version) >= 0) {
-            lc.debug?.('all clients up to date. no config catchup.');
             return [];
         }
         const startMs = Date.now();
         const sql = this.#db;
         const start = afterVersion ? versionString(afterVersion) : '';
         const end = versionString(upToCVR.version);
+        lc.debug?.(`scanning config patches for clients from ${start}`);
         const [allDesires, clientRows, queryRows] = await Promise.all([
             sql `SELECT * FROM cvr.desires
        WHERE "clientGroupID" = ${this.#id}
@@ -345,21 +576,33 @@ export class CVRStore {
         lc.debug?.(`${patches.length} config patches (${Date.now() - startMs} ms)`);
         return patches;
     }
-    async #abortIfNotVersion(tx, expectedCurrentVersion) {
+    async #checkVersionAndOwnership(tx, expectedCurrentVersion, lastConnectTime) {
         const expected = versionString(expectedCurrentVersion);
-        const result = await tx `SELECT version FROM cvr.instances WHERE "clientGroupID" = ${this.#id}`.execute(); // Note: execute() immediately to send the query before others.
-        const currVersion = result.length === 0 ? versionToLexi(0) : result[0].version;
-        if (currVersion !== expected) {
-            throw new ConcurrentModificationException(expected, currVersion);
+        const result = await tx `SELECT "version", "owner", "grantedAt" FROM cvr.instances 
+        WHERE "clientGroupID" = ${this.#id}
+        FOR UPDATE`.execute(); // Note: execute() immediately to send the query before others.
+        const { version, owner, grantedAt } = result.length > 0
+            ? result[0]
+            : {
+                version: EMPTY_CVR_VERSION.stateVersion,
+                owner: null,
+                grantedAt: null,
+            };
+        if (version !== expected) {
+            throw new ConcurrentModificationException(expected, version);
+        }
+        if (owner !== this.#taskID && (grantedAt ?? 0) > lastConnectTime) {
+            throw new OwnershipError(owner, grantedAt);
         }
     }
-    async #flush(expectedCurrentVersion) {
+    async #flush(expectedCurrentVersion, newVersion, lastConnectTime) {
         const stats = {
             instances: 0,
             queries: 0,
             desires: 0,
             clients: 0,
             rows: 0,
+            rowsDeferred: 0,
             statements: 0,
         };
         const existingRowRecords = await this.getRowRecords();
@@ -368,44 +611,44 @@ export class CVRStore {
             return ((existing !== undefined || row.refCounts !== null) &&
                 !deepEqual(row, existing));
         });
-        stats.rows = rowRecordsToFlush.length;
-        await this.#db.begin(tx => {
+        const rowsFlushed = await this.#db.begin(async (tx) => {
             const pipelined = [
-                // Test-and-set the version to guard against concurrent writes.
-                // TODO: Add homing logic.
-                this.#abortIfNotVersion(tx, expectedCurrentVersion),
+                // #checkVersionAndOwnership() executes a `SELECT ... FOR UPDATE`
+                // query to acquire a row-level lock so that version-updating
+                // transactions are effectively serialized per cvr.instance.
+                //
+                // Note that `rowsVersion` updates, on the other hand, are not subject
+                // to this lock and can thus commit / be-committed independently of
+                // cvr.instances.
+                this.#checkVersionAndOwnership(tx, expectedCurrentVersion, lastConnectTime),
             ];
-            if (this.#pendingRowRecordPuts.size > 0) {
-                const rowRecordRows = rowRecordsToFlush.map(r => rowRecordToRowsRow(this.#id, r));
-                let i = 0;
-                while (i < rowRecordRows.length) {
-                    pipelined.push(tx `INSERT INTO cvr.rows ${tx(rowRecordRows.slice(i, i + ROW_RECORD_UPSERT_BATCH_SIZE))} 
-            ON CONFLICT ("clientGroupID", "schema", "table", "rowKey")
-            DO UPDATE SET "rowVersion" = excluded."rowVersion",
-              "patchVersion" = excluded."patchVersion",
-              "refCounts" = excluded."refCounts"`.execute());
-                    i += ROW_RECORD_UPSERT_BATCH_SIZE;
-                    stats.statements++;
-                }
-            }
             for (const write of this.#writes) {
                 stats.instances += write.stats.instances ?? 0;
                 stats.queries += write.stats.queries ?? 0;
                 stats.desires += write.stats.desires ?? 0;
                 stats.clients += write.stats.clients ?? 0;
-                pipelined.push(write.write(tx).execute());
+                pipelined.push(write.write(tx, lastConnectTime).execute());
                 stats.statements++;
             }
+            const rowUpdates = this.#rowCache.executeRowUpdates(tx, newVersion, rowRecordsToFlush, 'allow-defer');
+            pipelined.push(...rowUpdates);
+            stats.statements += rowUpdates.length;
             // Make sure Errors thrown by pipelined statements
             // are propagated up the stack.
-            return Promise.all(pipelined);
+            await Promise.all(pipelined);
+            if (rowUpdates.length === 0) {
+                stats.rowsDeferred = rowRecordsToFlush.length;
+                return false;
+            }
+            stats.rows = rowRecordsToFlush.length;
+            return true;
         });
-        await this.#rowCache.flush(rowRecordsToFlush);
+        await this.#rowCache.apply(rowRecordsToFlush, newVersion, rowsFlushed);
         return stats;
     }
-    async flush(expectedCurrentVersion) {
+    async flush(expectedCurrentVersion, newVersion, lastConnectTime) {
         try {
-            return await this.#flush(expectedCurrentVersion);
+            return await this.#flush(expectedCurrentVersion, newVersion, lastConnectTime);
         }
         catch (e) {
             // Clear cached state if an error (e.g. ConcurrentModificationException) is encountered.
@@ -417,6 +660,10 @@ export class CVRStore {
             this.#pendingRowRecordPuts.clear();
         }
     }
+    /** Resolves when all pending updates are flushed. */
+    flushed() {
+        return this.#rowCache.flushed();
+    }
 }
 // Max number of parameters for our sqlite build is 65534.
 // Each row record has 7 parameters (1 per column).
@@ -428,4 +675,20 @@ export class ConcurrentModificationException extends Error {
         super(`CVR has been concurrently modified. Expected ${expectedVersion}, got ${actualVersion}`);
     }
 }
+export class OwnershipError extends Error {
+    name = 'OwnershipError';
+    constructor(owner, grantedAt) {
+        super(`CVR ownership was transferred to ${owner} at ${new Date(grantedAt ?? 0).toISOString()}`);
+    }
+}
+export class RowsVersionBehindError extends Error {
+    name = 'RowsVersionBehindError';
+    cvrVersion;
+    rowsVersion;
+    constructor(cvrVersion, rowsVersion) {
+        super(`rowsVersion (${rowsVersion}) is behind CVR ${cvrVersion}`);
+        this.cvrVersion = cvrVersion;
+        this.rowsVersion = rowsVersion;
+    }
+}
 //# sourceMappingURL=cvr-store.js.map