@syncular/server 0.43.0 → 0.45.0

package/dist/postgres-storage.js

@@ -5,7 +5,7 @@ import { serveNotReadyError } from './readiness.js';
 import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
-import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, LATEST_SCOPED_CHANGE_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, tableColumnNames, retiredTableNames, rewritePlan, columnSqlType, rewriteValues, SCHEMA_META_DDL_POSTGRES, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowBatchSql, scanRowPageSql, indexSignature, schemaDdl, serverIndexDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, LATEST_SCOPED_CHANGE_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, tableColumnNames, retiredTableNames, rewritePlan, columnSqlType, rewriteValues, SCHEMA_META_DDL_POSTGRES, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowBatchSql, scanRowPageSql, indexSignature, schemaDdl, serverIndexDdl, selectRowScopesSql, selectRowSql, prefetchRowsBatchSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective, sha256Hex } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -225,16 +225,17 @@ async function readIndexSignatures(client, tableNames) {
     const { rows } = await client.query(`SELECT ${indexesSubquery('$1')} AS indexes`, [JSON.stringify(tableNames)]);
     return parseIndexSignatures(rows[0]?.indexes ?? '[]');
 }
-/** RFC 0007 serve gate on either the pool or a transaction's client. */
-async function readServeGateOn(client, partition, runningSchemaVersion) {
-    // One statement: every request reads the gate twice (entry and verify),
-    // so its parts share one round trip and one snapshot.
-    const { rows } = await client.query(`SELECT (SELECT schema_version FROM sync_schema_meta WHERE id=1) AS schema_version,
+/**
+ * The serve-gate projection shared by every read: the entry/verify gate and
+ * the push admission statement select exactly these columns. Params:
+ * [partition, running schema version].
+ */
+const SERVE_GATE_PROJECTION = `(SELECT schema_version FROM sync_schema_meta WHERE id=1) AS schema_version,
             (SELECT log_epoch FROM sync_partition_registry WHERE partition=$1) AS log_epoch,
             (SELECT json_agg(json_build_object('partition', partition, 'name', name))
                FROM sync_backfill_checkpoints
-              WHERE schema_version=$2 AND state<>'activated') AS pending`, [partition, runningSchemaVersion]);
-    const row = rows[0];
+              WHERE schema_version=$2 AND state<>'activated') AS pending`;
+function toServeGate(row) {
     return {
         // asNumber maps the NULL of a missing marker row to 0.
         storedSchemaVersion: asNumber(row?.schema_version),
@@ -244,6 +245,63 @@ async function readServeGateOn(client, partition, runningSchemaVersion) {
             : asJson(row.pending),
     };
 }
+/** RFC 0007 serve gate on either the pool or a transaction's client. */
+async function readServeGateOn(client, partition, runningSchemaVersion) {
+    // One statement: every request reads the gate twice (entry and verify),
+    // so its parts share one round trip and one snapshot.
+    const { rows } = await client.query(`SELECT ${SERVE_GATE_PROJECTION}`, [partition, runningSchemaVersion]);
+    return toServeGate(rows[0]);
+}
+/**
+ * The push admission read: the RFC 0007 serve gate, the §2.3 idempotency
+ * record, and (when the caller already knows the commit's row targets) the
+ * read-ahead rows, in one statement with one snapshot. The caller takes the
+ * partition lock first: under READ COMMITTED a statement's snapshot is fixed
+ * at its start, so the read must be the statement *after* the lock to observe
+ * a duplicate that committed while this transaction waited for it.
+ */
+async function readAdmissionOn(client, partition, clientId, clientCommitId, runningSchemaVersion, prefetch) {
+    const params = [
+        partition,
+        runningSchemaVersion,
+        clientId,
+        clientCommitId,
+    ];
+    let statement = `SELECT ${SERVE_GATE_PROJECTION},
+            (SELECT result FROM sync_push_results
+              WHERE partition=$1 AND client_id=$3 AND client_commit_id=$4) AS result`;
+    if (prefetch !== undefined && prefetch.specs.length > 0) {
+        params.push(JSON.stringify(prefetch.specs));
+        // The gate row pads the read-ahead columns with typed NULLs so both
+        // branches share one result shape; `tbl` is NULL only for the gate row.
+        statement += `,
+            NULL::text AS tbl, NULL::text AS lookup_id, NULL::text AS row_id,
+            NULL::bigint AS server_version, NULL::jsonb AS scopes,
+            NULL::bytea AS payload, NULL::bytea AS column_versions,
+            NULL::bigint AS tombstone_seq
+       UNION ALL
+       SELECT NULL::bigint, NULL::text, NULL::json, NULL::jsonb,
+              p.tbl, p.lookup_id, p.row_id, p.server_version, p.scopes,
+              p.payload, p.column_versions, p.tombstone_seq
+         FROM (${prefetchRowsBatchSql(prefetch.tables, {
+            partition: '$1',
+            specs: `$${params.length}`,
+        })}) p`;
+    }
+    const { rows } = await client.query(statement, params);
+    const gateRow = rows.find((row) => row.tbl === null) ?? rows[0];
+    return {
+        gate: toServeGate(gateRow),
+        persisted: toPersistedPushResult(gateRow?.result),
+        prefetched: rows.filter((row) => row.tbl !== null && row.tbl !== undefined),
+    };
+}
+/**
+ * Insert the `declared` row and raise the fence, on the caller's open
+ * transaction. Shared by `declareCheckpoint` and the `ensureSchema`
+ * migration so the schema bump and the fence commit together. Never lowers a
+ * fence and never re-declares an existing row.
+ */
 async function hasSourceChangesAboveOn(client, partition, tables, seq) {
     // Read the horizon before the window scan: a horizon past `seq` means the
     // history that would answer the question is gone, so an empty scan proves
@@ -488,24 +546,36 @@ async function scanRowsByIndexOn(q, compiled, partition, query) {
     return rows.map(toStoredRow);
 }
 /**
- * Write rows of one table in one statement per chunk: the upsert, and the
- * scope index synced to each row's scope map (entries outside it deleted,
- * missing ones inserted). Row ids are distinct, so no index entry is touched
- * twice and the writable CTEs cannot conflict. The scopes bind as text
- * before the JSONB cast (see `appendCommit`). Every chunk is handed to `q`
- * before the first one settles, so a statement issued after this call
- * queues behind all of them on the transaction FIFO.
+ * Write rows of one table in one statement per chunk: the upsert, the scope
+ * index synced to each row's scope map (entries outside it deleted, missing
+ * ones inserted), and the §5.9.4 blob-reference index synced to the ids the
+ * row now references (entries outside the new set deleted, missing ones
+ * inserted). Row ids are distinct, so no index entry is touched twice and the
+ * writable CTEs cannot conflict. The scopes and blob ids bind as text before
+ * the JSONB cast (see `appendCommit`); the refs set is part of the same
+ * statement, so a blob-referencing commit costs no extra round trip per row.
+ * Every chunk is handed to `q` before the first one settles, so a statement
+ * issued after this call queues behind all of them on the transaction FIFO.
  */
-function writeRowsOn(q, compiled, partition, rows) {
+function writeRowsOn(q, compiled, partition, rows, blobRefs = []) {
     const width = tableColumnNames(compiled).length;
     // PGlite corrupts its state above 32,767 bound parameters (see
     // PG_CHANGES_PER_STATEMENT).
     const chunk = Math.max(1, Math.floor(30_000 / width));
+    const pendingRefs = new Map(blobRefs.map((entry) => [entry.rowId, entry.blobIds]));
     const writes = [];
     for (let first = 0; first < rows.length; first += chunk) {
         const slice = rows.slice(first, first + chunk);
         const params = slice.flatMap((entry) => entry.values);
         const n = params.length;
+        const refs = [];
+        for (const entry of slice) {
+            const blobIds = pendingRefs.get(entry.row.rowId);
+            if (blobIds === undefined)
+                continue;
+            pendingRefs.delete(entry.row.rowId);
+            refs.push({ row_id: entry.row.rowId, blob_ids: blobIds });
+        }
         writes.push(q.query(`WITH upserted AS (${upsertSql(compiled, 'postgres', slice.length)}),
          batch AS (
            SELECT row_id, scopes
@@ -521,6 +591,28 @@ function writeRowsOn(q, compiled, partition, rows) {
             WHERE existing.partition=$${n + 2} AND existing.tbl=$${n + 3}
               AND existing.row_id=batch.row_id
               AND batch.scopes->>existing.var IS DISTINCT FROM existing.value
+         ),
+         changed_refs AS (
+           SELECT DISTINCT row_id
+             FROM jsonb_to_recordset($${n + 4}::text::jsonb) AS r(row_id text, blob_ids jsonb)
+         ),
+         removed_refs AS (
+           DELETE FROM sync_blob_refs existing
+            USING changed_refs
+            WHERE existing.partition=$${n + 2} AND existing.tbl=$${n + 3}
+              AND existing.row_id=changed_refs.row_id
+              AND NOT EXISTS (
+                SELECT 1
+                  FROM jsonb_to_recordset($${n + 4}::text::jsonb) AS r(row_id text, blob_ids jsonb)
+                  CROSS JOIN LATERAL jsonb_array_elements_text(r.blob_ids) AS entry(value)
+                 WHERE r.row_id=existing.row_id AND entry.value=existing.blob_id)
+         ),
+         inserted_refs AS (
+           INSERT INTO sync_blob_refs(partition, tbl, row_id, blob_id)
+           SELECT $${n + 2}, $${n + 3}, r.row_id, entry.value
+             FROM jsonb_to_recordset($${n + 4}::text::jsonb) AS r(row_id text, blob_ids jsonb)
+             CROSS JOIN LATERAL jsonb_array_elements_text(r.blob_ids) AS entry(value)
+           ON CONFLICT DO NOTHING
          )
          INSERT INTO sync_row_scopes(partition, tbl, var, value, row_id)
          SELECT $${n + 2}, $${n + 3}, key, value, row_id FROM scope
@@ -529,16 +621,52 @@ function writeRowsOn(q, compiled, partition, rows) {
             JSON.stringify(slice.map(({ row }) => ({ row_id: row.rowId, scopes: row.scopes }))),
             partition,
             compiled.name,
+            JSON.stringify(refs),
+        ]));
+    }
+    if (pendingRefs.size > 0) {
+        // Refs staged for a row this call did not carry (the row was written by an
+        // earlier flush): replace the reference set in one statement of its own.
+        writes.push(q.query(`WITH changed_refs AS (
+           SELECT DISTINCT row_id
+             FROM jsonb_to_recordset($3::text::jsonb) AS r(row_id text, blob_ids jsonb)
+         ),
+         removed_refs AS (
+           DELETE FROM sync_blob_refs existing
+            USING changed_refs
+            WHERE existing.partition=$1 AND existing.tbl=$2
+              AND existing.row_id=changed_refs.row_id
+              AND NOT EXISTS (
+                SELECT 1
+                  FROM jsonb_to_recordset($3::text::jsonb) AS r(row_id text, blob_ids jsonb)
+                  CROSS JOIN LATERAL jsonb_array_elements_text(r.blob_ids) AS entry(value)
+                 WHERE r.row_id=existing.row_id AND entry.value=existing.blob_id)
+         )
+         INSERT INTO sync_blob_refs(partition, tbl, row_id, blob_id)
+         SELECT $1, $2, r.row_id, entry.value
+           FROM jsonb_to_recordset($3::text::jsonb) AS r(row_id text, blob_ids jsonb)
+           CROSS JOIN LATERAL jsonb_array_elements_text(r.blob_ids) AS entry(value)
+         ON CONFLICT DO NOTHING`, [
+            partition,
+            compiled.name,
+            JSON.stringify([...pendingRefs].map(([row_id, blob_ids]) => ({
+                row_id,
+                blob_ids,
+            }))),
         ]));
     }
     return Promise.all(writes);
 }
 async function getPushResultOn(q, partition, clientId, clientCommitId) {
     const { rows } = await q.query('SELECT result FROM sync_push_results WHERE partition=$1 AND client_id=$2 AND client_commit_id=$3', [partition, clientId, clientCommitId]);
-    if (rows[0] === undefined)
+    return toPersistedPushResult(rows[0]?.result);
+}
+/** Decode a persisted §2.3 outcome; an unreadable record is a cache miss. */
+function toPersistedPushResult(value) {
+    if (value === null || value === undefined)
         return undefined;
     try {
-        return deserializePushResult(asJson(rows[0].result));
+        return deserializePushResult(asJson(value));
     }
     catch {
         throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
@@ -583,6 +711,20 @@ class PostgresTransaction {
      * operation.
      */
     #staged = new Map();
+    /**
+     * §5.9.4 reference sets staged per table (row id → blob ids). They flush
+     * with the table's row statement, so a blob-referencing row costs no extra
+     * round trip; a ref set staged for an already-written row flushes on the
+     * next statement of its table.
+     */
+    #stagedBlobRefs = new Map();
+    /**
+     * The partition cursor (`max_commit_seq`) read by the first registered
+     * query in this transaction. The partition lock freezes it, so later
+     * registered queries in the same transaction reuse the value instead of
+     * paying a round trip each.
+     */
+    #cursorSeq;
     /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
     #resolve;
     #reject;
@@ -631,21 +773,53 @@ class PostgresTransaction {
             throw new Error('transaction already finished');
     }
     #writeStaged() {
-        if (this.#staged.size === 0)
+        if (this.#staged.size === 0 && this.#stagedBlobRefs.size === 0) {
             return Promise.resolve();
-        const staged = [...this.#staged];
-        this.#staged.clear();
-        return Promise.all(staged.map(([table, rows]) => {
-            const entries = [...rows.values()];
-            return writeRowsOn(this.#serial, table, this.#partition, entries).catch((error) => {
+        }
+        const tables = new Set([
+            ...[...this.#staged.keys()].map((table) => table.name),
+            ...this.#stagedBlobRefs.keys(),
+        ]);
+        const batches = [...tables].map((table) => {
+            const compiled = this.#resolveTable(table);
+            const rows = [...(this.#staged.get(compiled)?.values() ?? [])];
+            const blobRefs = [
+                ...(this.#stagedBlobRefs.get(table)?.entries() ?? []),
+            ].map(([rowId, blobIds]) => ({ rowId, blobIds }));
+            this.#staged.delete(compiled);
+            this.#stagedBlobRefs.delete(table);
+            return { table, compiled, rows, blobRefs };
+        });
+        const writes = [];
+        // The candidate savepoint lands before the first candidate write, and
+        // only when a write actually reaches the database: a commit refused
+        // before its first write has no candidate rows to roll back, so its
+        // rejection finalization skips the savepoint round trips.
+        const savepoint = this.#ensurePushSavepoint();
+        if (savepoint !== undefined)
+            writes.push(savepoint);
+        for (const { compiled, rows, blobRefs } of batches) {
+            writes.push(writeRowsOn(this.#serial, compiled, this.#partition, rows, blobRefs).catch((error) => {
                 // Staged tables have no unique index, so a violation is a column
                 // constraint; it names the first staged operation of the table.
                 if (isPostgresConstraintError(error)) {
-                    throw new StorageConstraintError(error, entries[0]?.opIndex);
+                    throw new StorageConstraintError(error, rows[0]?.opIndex);
                 }
                 throw error;
-            });
-        }));
+            }));
+        }
+        return Promise.all(writes);
+    }
+    /**
+     * The candidate savepoint, taken before the transaction's first write.
+     * Every candidate write must be undoable by `commitRejectedPushResult`, and
+     * a refused commit that wrote nothing must not pay to create one.
+     */
+    #ensurePushSavepoint() {
+        if (this.#pushApplySavepoint)
+            return undefined;
+        this.#pushApplySavepoint = true;
+        return this.#serial.query('SAVEPOINT syncular_push_candidate');
     }
     getRow(table, rowId) {
         this.#assertOpen();
@@ -655,19 +829,27 @@ class PostgresTransaction {
         }
         return getRowOn(this.#client, this.#resolveTable(table), this.#partition, rowId);
     }
-    async prefetchRows(table, rowIds) {
+    async prefetchRows(targets) {
         this.#assertOpen();
-        const ids = [...new Set(rowIds)].filter((rowId) => !this.#prefetchedRows.has(`${table}\u0000${rowId}`));
-        if (ids.length === 0)
+        const tables = [];
+        const specs = [];
+        for (const target of targets) {
+            const ids = [...new Set(target.rowIds)].filter((rowId) => !this.#prefetchedRows.has(`${target.table}\u0000${rowId}`));
+            if (ids.length === 0)
+                continue;
+            tables.push(this.#resolveTable(target.table));
+            specs.push({ tbl: target.table, ids });
+        }
+        if (specs.length === 0)
             return;
-        const { rows } = await this.#client.query(prefetchRowsSql(this.#resolveTable(table)), [
-            this.#partition,
-            JSON.stringify(ids),
-            table,
-        ]);
-        for (const record of rows) {
-            const key = `${table}\u0000${record.lookup_id}`;
-            this.#prefetchedRows.set(key, record.row_id === null
+        const { rows } = await this.#client.query(prefetchRowsBatchSql(tables), [this.#partition, JSON.stringify(specs)]);
+        this.#recordPrefetched(rows);
+    }
+    /** Answer the following `getRow`/`getTombstoneSeq` calls from a read snapshot. */
+    #recordPrefetched(records) {
+        for (const record of records) {
+            const key = `${record.tbl}\u0000${record.lookup_id}`;
+            this.#prefetchedRows.set(key, record.row_id === null || record.row_id === undefined
                 ? null
                 : toStoredRow({ ...record, row_id: record.row_id }));
             this.#prefetchedTombstones.set(key, record.tombstone_seq === null || record.tombstone_seq === undefined
@@ -687,15 +869,9 @@ class PostgresTransaction {
     async clearTombstone(table, rowId) {
         this.#assertOpen();
         this.#prefetchedTombstones.delete(`${table}\u0000${rowId}`);
+        await this.#ensurePushSavepoint();
         await this.#client.query('DELETE FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3', [this.#partition, table, rowId]);
     }
-    getPushResult(clientId, clientCommitId) {
-        this.#assertOpen();
-        // Runs on this transaction's pinned client: the push layer's duplicate
-        // re-check happens while the partition lock is held, and a pool-level
-        // read there would wait for a second connection.
-        return getPushResultOn(this.#client, this.#partition, clientId, clientCommitId);
-    }
     async scanRows(query) {
         this.#assertOpen();
         const firstVariable = assertScopeIndexedScan(query);
@@ -737,20 +913,49 @@ class PostgresTransaction {
         this.#assertOpen();
         return scanRowsByIndexOn(this.#client, this.#resolveTable(query.table), this.#partition, query);
     }
-    queryAuthoritative(query) {
+    async queryAuthoritative(query) {
         this.#assertOpen();
         // Runs on this transaction's pinned client, so the read observes every
         // staged row and never waits for a second pool connection.
-        return queryAuthoritativeOn(this.#client, this.#partition, this.#prepareQuery(query));
+        const prepared = this.#prepareQuery(query);
+        const result = await this.#client.query(postgresPlaceholders(prepared.sql), prepared.params);
+        // The partition lock freezes `max_commit_seq` for the whole transaction,
+        // so one read answers every registered query in it.
+        if (this.#cursorSeq === undefined) {
+            const cursor = await this.#client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [this.#partition]);
+            this.#cursorSeq =
+                cursor.rows[0] === undefined
+                    ? 0
+                    : asNumber(cursor.rows[0].max_commit_seq);
+        }
+        return { rows: result.rows, maxCommitSeq: this.#cursorSeq };
     }
-    async lockPartitionForPush() {
+    async preparePushApply(clientId, clientCommitId, runningSchemaVersion, targets = []) {
         this.#assertOpen();
+        // The lock is its own statement: a READ COMMITTED statement's snapshot is
+        // fixed at its start, so the admission read must run *after* a duplicate's
+        // commit has released the partition lock to observe it. Folding the lock
+        // and the read into one statement would miss a duplicate that committed
+        // while this transaction waited.
         await lockPartitionOn(this.#client, this.#partition);
-        await this.#client.query('SAVEPOINT syncular_push_candidate');
-        this.#pushApplySavepoint = true;
+        const tables = [];
+        const specs = [];
+        for (const target of targets) {
+            const ids = [...new Set(target.rowIds)].filter((rowId) => !this.#prefetchedRows.has(`${target.table}\u0000${rowId}`));
+            if (ids.length === 0)
+                continue;
+            tables.push(this.#resolveTable(target.table));
+            specs.push({ tbl: target.table, ids });
+        }
+        // One statement: the serve gate, the idempotency record, and the commit's
+        // read-ahead (when the caller already knows its targets).
+        const admission = await readAdmissionOn(this.#client, this.#partition, clientId, clientCommitId, runningSchemaVersion, specs.length === 0 ? undefined : { tables, specs });
+        this.#recordPrefetched(admission.prefetched);
+        return { gate: admission.gate, persisted: admission.persisted };
     }
     async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
         this.#assertOpen();
+        await this.#ensurePushSavepoint();
         // `RETURNING`: the affected-row check must not depend on a driver's
         // `rowCount` for a statement with no result rows. Bun.sql's canonical
         // adapter derives `rowCount` from the returned rows, so a bare UPDATE
@@ -769,15 +974,40 @@ class PostgresTransaction {
     }
     async commitRejectedPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
-        if (!this.#pushApplySavepoint) {
-            throw new Error('push rejection requires its apply savepoint');
-        }
+        // Candidate rows that never reached the database are discarded with the
+        // staging map; a savepoint exists only when one did.
         this.#staged.clear();
-        await this.#client.query('ROLLBACK TO SAVEPOINT syncular_push_candidate');
-        await this.#client.query('RELEASE SAVEPOINT syncular_push_candidate');
-        this.#pushApplySavepoint = false;
-        await this.putPushResult(clientId, clientCommitId, result);
+        this.#stagedBlobRefs.clear();
+        if (this.#pushApplySavepoint) {
+            await this.#client.query('ROLLBACK TO SAVEPOINT syncular_push_candidate');
+            await this.#client.query('RELEASE SAVEPOINT syncular_push_candidate');
+            this.#pushApplySavepoint = false;
+        }
+        const canonical = await this.#insertPushResult(clientId, clientCommitId, result);
         await this.commit();
+        return canonical;
+    }
+    /** Insert the §2.3 outcome and return the canonical persisted value. */
+    async #insertPushResult(clientId, clientCommitId, result) {
+        const { rows } = await this.#client.query(`INSERT INTO sync_push_results(partition, client_id, client_commit_id, result)
+       VALUES ($1,$2,$3,$4)
+       ON CONFLICT (partition, client_id, client_commit_id) DO NOTHING
+       RETURNING result`, [
+            this.#partition,
+            clientId,
+            clientCommitId,
+            JSON.stringify(serializePushResult(result)),
+        ]);
+        if (rows[0] !== undefined) {
+            return toPersistedPushResult(rows[0].result) ?? result;
+        }
+        // `ON CONFLICT DO NOTHING` means a previously committed outcome won; read
+        // it rather than claiming this caller's candidate.
+        const existing = await getPushResultOn(this.#client, this.#partition, clientId, clientCommitId);
+        if (existing === undefined) {
+            throw new Error('push result insert did not persist an outcome');
+        }
+        return existing;
     }
     async upsertRow(table, row, context) {
         this.#assertOpen();
@@ -800,10 +1030,16 @@ class PostgresTransaction {
             });
             return;
         }
+        const refs = this.#stagedBlobRefs.get(table);
+        const blobIds = refs?.get(row.rowId);
+        if (blobIds !== undefined && refs !== undefined) {
+            refs.delete(row.rowId);
+            if (refs.size === 0)
+                this.#stagedBlobRefs.delete(table);
+        }
+        await this.#ensurePushSavepoint();
         try {
-            await writeRowsOn(this.#client, compiled, this.#partition, [
-                { row, values },
-            ]);
+            await writeRowsOn(this.#client, compiled, this.#partition, [{ row, values }], blobIds === undefined ? [] : [{ rowId: row.rowId, blobIds }]);
         }
         catch (error) {
             if (isPostgresConstraintError(error)) {
@@ -815,6 +1051,11 @@ class PostgresTransaction {
     async deleteRow(table, rowId) {
         this.#assertOpen();
         this.#prefetchedRows.delete(`${table}\u0000${rowId}`);
+        const refs = this.#stagedBlobRefs.get(table);
+        refs?.delete(rowId);
+        if (refs?.size === 0)
+            this.#stagedBlobRefs.delete(table);
+        await this.#ensurePushSavepoint();
         // One statement: the row, its scope-index entries, and (§5.9.4: a
         // deleted row references no blobs) its blob references.
         await this.#client.query(`WITH deleted AS (${deleteRowSql(this.#resolveTable(table), 'postgres')}),
@@ -823,93 +1064,118 @@ class PostgresTransaction {
        )
        DELETE FROM sync_blob_refs WHERE partition=$1 AND tbl=$3 AND row_id=$2`, [this.#partition, rowId, table]);
     }
-    async setBlobRefs(table, rowId, blobIds) {
+    setBlobRefs(table, rowId, blobIds) {
         this.#assertOpen();
-        // Replace the row's reference set atomically inside the commit tx (§5.9.4).
-        await this.#client.query('DELETE FROM sync_blob_refs WHERE partition=$1 AND tbl=$2 AND row_id=$3', [this.#partition, table, rowId]);
-        for (const blobId of blobIds) {
-            await this.#client.query(`INSERT INTO sync_blob_refs(partition, tbl, row_id, blob_id)
-         VALUES ($1,$2,$3,$4) ON CONFLICT DO NOTHING`, [this.#partition, table, rowId, blobId]);
+        // Staged with the row: the reference set is replaced in the same
+        // statement that writes the row (§5.9.4), inside the commit tx.
+        let rows = this.#stagedBlobRefs.get(table);
+        if (rows === undefined) {
+            rows = new Map();
+            this.#stagedBlobRefs.set(table, rows);
         }
+        rows.set(rowId, blobIds);
+        return Promise.resolve();
     }
     async appendCommit(commit) {
         this.#assertOpen();
         // The commit writes its delete tombstones below.
         this.#prefetchedTombstones.clear();
+        // The append advances the partition cursor; a registered query that runs
+        // after it must read the new value.
+        this.#cursorSeq = undefined;
         const q = this.#client;
         const p = this.#partition;
         // Allocate the next dense commitSeq under a per-partition row lock: the
         // UPDATE … RETURNING serializes concurrent pushes to this partition and
         // never leaves a gap on rollback (see the file header).
-        const { rows } = await q.query(`WITH allocated AS (
-         INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 1)
+        const allocate = `INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 1)
          ON CONFLICT (partition) DO UPDATE
            SET max_commit_seq = sync_partitions.max_commit_seq + 1
-         RETURNING max_commit_seq
-       )
-       INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version)
-       SELECT $1, max_commit_seq, $2, $3, $4, $5, $6 FROM allocated
-       RETURNING commit_seq`, [
+         RETURNING max_commit_seq`;
+        const commitRow = `INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version)
+         SELECT $1, allocated.max_commit_seq, $2, $3, $4, $5, $6 FROM allocated
+         RETURNING commit_seq`;
+        const head = [
             p,
             commit.clientId,
             commit.clientCommitId,
             commit.actorId,
             commit.createdAtMs,
             this.#writerVersion,
-        ]);
-        const commitSeq = asNumber(rows[0]?.commit_seq);
-        if (commit.changes.length === 0)
-            return commitSeq;
+        ];
+        if (commit.changes.length === 0) {
+            const { rows } = await q.query(`WITH allocated AS (${allocate}) ${commitRow}`, head);
+            return asNumber(rows[0]?.commit_seq);
+        }
+        // §2.2: a delete whose commit follows it with an upsert is a scope move.
+        // The row is live, so the tombstone insert below skips it.
+        const moved = JSON.stringify([...rowsLiveAfterDelete(commit.changes)].map((key) => {
+            const at = key.indexOf('\u0000');
+            return { tbl: key.slice(0, at), row_id: key.slice(at + 1) };
+        }));
         // One writable-CTE chain per chunk of changes: the changes, their
         // inverted scope entries, and the §5 delete tombstones. A statement binds
         // at most a 16-bit count of parameters, so a chunk carries
-        // PG_CHANGES_PER_STATEMENT changes; every chunk runs in the
-        // commit's transaction under the same commit_seq with its global idx.
-        // Serialized scopes bind as text before parsing JSONB; drivers that
-        // encode JSONB parameters would otherwise store the string as a scalar.
-        // A commit can delete one row twice, so a chunk's tombstone insert keeps
-        // one row per key and a later chunk updates it to the same commit_seq.
-        for (let first = 0; first < commit.changes.length; first += PG_CHANGES_PER_STATEMENT) {
-            const params = [p, commitSeq];
-            const values = commit.changes
-                .slice(first, first + PG_CHANGES_PER_STATEMENT)
-                .map((change, offset) => {
-                const base = params.length;
-                params.push(first + offset, change.table, change.rowId, change.op === 'upsert' ? 1 : 2, change.rowVersion ?? null, JSON.stringify(change.scopes), change.payload ?? null);
-                return `($1,$2::bigint,$${base + 1}::int,$${base + 2},$${base + 3},$${base + 4}::smallint,$${base + 5}::bigint,$${base + 6}::text::jsonb,$${base + 7}::bytea)`;
-            });
-            await q.query(`WITH inserted AS (
-           INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
-           VALUES ${values.join(',')}
-           RETURNING partition, tbl, row_id, op, commit_seq, scopes
-         ),
-         scoped AS (
+        // PG_CHANGES_PER_STATEMENT changes. The first chunk folds the allocation,
+        // the commit row, and the change-log write into one statement; later
+        // chunks run under the same commitSeq with their global idx. Serialized
+        // scopes bind as text before parsing JSONB; drivers that encode JSONB
+        // parameters would otherwise store the string as a scalar. A commit can
+        // delete one row twice, so a chunk's tombstone insert keeps one row per
+        // key and a later chunk updates it to the same commit_seq.
+        const valuesOf = (params, slice, firstIdx) => slice.map((change, offset) => {
+            const base = params.length;
+            params.push(firstIdx + offset, change.table, change.rowId, change.op === 'upsert' ? 1 : 2, change.rowVersion ?? null, JSON.stringify(change.scopes), change.payload ?? null);
+            return `($${base + 1}::int,$${base + 2}::text,$${base + 3}::text,$${base + 4}::smallint,$${base + 5}::bigint,$${base + 6}::text::jsonb,$${base + 7}::bytea)`;
+        });
+        const scopesCte = `scoped AS (
            INSERT INTO sync_change_scopes(partition, tbl, var, value, commit_seq)
            SELECT inserted.partition, inserted.tbl, scope.key, scope.value, inserted.commit_seq
            FROM inserted CROSS JOIN LATERAL jsonb_each_text(inserted.scopes) AS scope
            ON CONFLICT DO NOTHING
-         )
-         INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq)
+         )`;
+        const tombstones = (movedParam) => `INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq)
          SELECT DISTINCT ON (tbl, row_id) partition, tbl, row_id, commit_seq
-           FROM inserted WHERE op = 2
+           FROM inserted
+          WHERE op = 2
+            AND NOT EXISTS (
+              SELECT 1
+                FROM jsonb_to_recordset(${movedParam}::text::jsonb) AS moved(tbl text, row_id text)
+               WHERE moved.tbl = inserted.tbl AND moved.row_id = inserted.row_id)
          ON CONFLICT (partition, tbl, row_id)
-         DO UPDATE SET commit_seq = excluded.commit_seq`, params);
-        }
-        // §2.2: a delete whose commit follows it with an upsert is a scope move.
-        // The row is live, so no tombstone may remain for it.
-        const liveAfterDelete = rowsLiveAfterDelete(commit.changes);
-        if (liveAfterDelete.size > 0) {
-            await q.query(`DELETE FROM sync_tombstones existing
-          USING jsonb_to_recordset($2::text::jsonb) AS moved(tbl text, row_id text)
-          WHERE existing.partition=$1
-            AND existing.tbl=moved.tbl
-            AND existing.row_id=moved.row_id`, [
-                p,
-                JSON.stringify([...liveAfterDelete].map((key) => {
-                    const at = key.indexOf('\u0000');
-                    return { tbl: key.slice(0, at), row_id: key.slice(at + 1) };
-                })),
-            ]);
+         DO UPDATE SET commit_seq = excluded.commit_seq`;
+        const firstSlice = commit.changes.slice(0, PG_CHANGES_PER_STATEMENT);
+        const params = [...head];
+        const values = valuesOf(params, firstSlice, 0);
+        params.push(moved);
+        const movedParam = `$${params.length}`;
+        const { rows } = await q.query(`WITH allocated AS (${allocate}),
+       allocated_commit AS (${commitRow}),
+       inserted AS (
+         INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
+         SELECT $1, allocated.max_commit_seq, v.idx, v.tbl, v.row_id, v.op, v.row_version, v.scopes, v.payload
+           FROM allocated
+           CROSS JOIN (VALUES ${values.join(',')}) AS v(idx, tbl, row_id, op, row_version, scopes, payload)
+         RETURNING partition, tbl, row_id, op, commit_seq, scopes
+       ),
+       ${scopesCte},
+       tombstoned AS (${tombstones(movedParam)})
+       SELECT max_commit_seq FROM allocated`, params);
+        const commitSeq = asNumber(rows[0]?.max_commit_seq);
+        for (let first = PG_CHANGES_PER_STATEMENT; first < commit.changes.length; first += PG_CHANGES_PER_STATEMENT) {
+            const chunkParams = [p, commitSeq];
+            const chunkValues = valuesOf(chunkParams, commit.changes.slice(first, first + PG_CHANGES_PER_STATEMENT), first);
+            chunkParams.push(moved);
+            const chunkMovedParam = `$${chunkParams.length}`;
+            await q.query(`WITH inserted AS (
+           INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
+           SELECT $1, $2, v.idx, v.tbl, v.row_id, v.op, v.row_version, v.scopes, v.payload
+             FROM (VALUES ${chunkValues.join(',')}) AS v(idx, tbl, row_id, op, row_version, scopes, payload)
+           RETURNING partition, tbl, row_id, op, commit_seq, scopes
+         ),
+         ${scopesCte},
+         tombstoned AS (${tombstones(chunkMovedParam)})
+         SELECT 1`, chunkParams);
         }
         return commitSeq;
     }
@@ -1484,7 +1750,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
     async activateCheckpoint(partition, name, ownerEpoch, watermark, sources, nowMs) {
         return this.#exec.transaction(async (client) => {
             // The same `SELECT … FOR UPDATE` partition row lock that
-            // `lockPartitionForPush` takes; a bare `BEGIN` would race a push.
+            // `preparePushApply` takes; a bare `BEGIN` would race a push.
             await lockPartitionOn(client, partition);
             const fence = await client.query('SELECT required_writer_version FROM sync_writer_fence WHERE partition=$1', [partition]);
             const checkpoint = await client.query('SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=$1 AND name=$2', [partition, name]);