@syncular/server 0.26.4 → 0.26.5

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, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowBatchSql, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowBatchSql, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -403,12 +403,28 @@ async function scanRowsByIndexOn(q, compiled, partition, query) {
     return rows.map(toStoredRow);
 }
 async function writeRowOn(q, compiled, partition, row) {
-    await q.query(upsertSql(compiled, 'postgres'), upsertValues(compiled, partition, row, 'postgres'));
-    await q.query('DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$2 AND row_id=$3', [partition, compiled.name, row.rowId]);
-    for (const [variable, value] of Object.entries(row.scopes)) {
-        await q.query(`INSERT INTO sync_row_scopes(partition, tbl, var, value, row_id)
-       VALUES ($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`, [partition, compiled.name, variable, value, row.rowId]);
-    }
+    // One statement per row write: the upsert, and the scope index synced to
+    // the row's scope map (entries outside it deleted, missing ones inserted).
+    // No index entry is touched twice, so the writable CTEs cannot conflict.
+    // The scopes bind as text before the JSONB cast (see `appendCommit`).
+    const params = upsertValues(compiled, partition, row, 'postgres');
+    const n = params.length;
+    await q.query(`WITH upserted AS (${upsertSql(compiled, 'postgres')}),
+     scope AS (SELECT key, value FROM jsonb_each_text($${n + 1}::text::jsonb)),
+     removed AS (
+       DELETE FROM sync_row_scopes
+        WHERE partition=$${n + 2} AND tbl=$${n + 3} AND row_id=$${n + 4}
+          AND (var, value) NOT IN (SELECT key, value FROM scope)
+     )
+     INSERT INTO sync_row_scopes(partition, tbl, var, value, row_id)
+     SELECT $${n + 2}, $${n + 3}, key, value, $${n + 4} FROM scope
+     ON CONFLICT DO NOTHING`, [
+        ...params,
+        JSON.stringify(row.scopes),
+        partition,
+        compiled.name,
+        row.rowId,
+    ]);
 }
 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]);
@@ -442,6 +458,13 @@ class PostgresTransaction {
     #resolveTable;
     #open = true;
     #pushApplySavepoint = false;
+    /**
+     * `prefetchRows` results keyed `table\u0000rowId`; `null` records a row
+     * (or tombstone) read as absent. A write in this transaction drops the
+     * key, so the next read goes to the database again.
+     */
+    #prefetchedRows = new Map();
+    #prefetchedTombstones = new Map();
     /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
     #resolve;
     #reject;
@@ -473,16 +496,44 @@ class PostgresTransaction {
     }
     getRow(table, rowId) {
         this.#assertOpen();
+        const prefetched = this.#prefetchedRows.get(`${table}\u0000${rowId}`);
+        if (prefetched !== undefined) {
+            return Promise.resolve(prefetched ?? undefined);
+        }
         return getRowOn(this.#client, this.#resolveTable(table), this.#partition, rowId);
     }
+    async prefetchRows(table, rowIds) {
+        this.#assertOpen();
+        const ids = [...new Set(rowIds)].filter((rowId) => !this.#prefetchedRows.has(`${table}\u0000${rowId}`));
+        if (ids.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
+                ? null
+                : toStoredRow({ ...record, row_id: record.row_id }));
+            this.#prefetchedTombstones.set(key, record.tombstone_seq === null || record.tombstone_seq === undefined
+                ? null
+                : asNumber(record.tombstone_seq));
+        }
+    }
     async getTombstoneSeq(table, rowId) {
         this.#assertOpen();
+        const prefetched = this.#prefetchedTombstones.get(`${table}\u0000${rowId}`);
+        if (prefetched !== undefined)
+            return prefetched ?? undefined;
         const { rows } = await this.#client.query('SELECT commit_seq FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3', [this.#partition, table, rowId]);
         const seq = rows[0]?.commit_seq;
         return seq === null || seq === undefined ? undefined : asNumber(seq);
     }
     async clearTombstone(table, rowId) {
         this.#assertOpen();
+        this.#prefetchedTombstones.delete(`${table}\u0000${rowId}`);
         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) {
@@ -576,6 +627,7 @@ class PostgresTransaction {
     }
     async upsertRow(table, row, context) {
         this.#assertOpen();
+        this.#prefetchedRows.delete(`${table}\u0000${row.rowId}`);
         try {
             await writeRowOn(this.#client, this.#resolveTable(table), this.#partition, row);
         }
@@ -588,10 +640,14 @@ class PostgresTransaction {
     }
     async deleteRow(table, rowId) {
         this.#assertOpen();
-        await this.#client.query(deleteRowSql(this.#resolveTable(table), 'postgres'), [this.#partition, rowId]);
-        await this.#client.query('DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$2 AND row_id=$3', [this.#partition, table, rowId]);
-        // §5.9.4: a deleted row references no blobs.
-        await this.#client.query('DELETE FROM sync_blob_refs WHERE partition=$1 AND tbl=$2 AND row_id=$3', [this.#partition, table, rowId]);
+        this.#prefetchedRows.delete(`${table}\u0000${rowId}`);
+        // 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')}),
+       unscoped AS (
+         DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$3 AND row_id=$2
+       )
+       DELETE FROM sync_blob_refs WHERE partition=$1 AND tbl=$3 AND row_id=$2`, [this.#partition, rowId, table]);
     }
     async setBlobRefs(table, rowId, blobIds) {
         this.#assertOpen();
@@ -604,6 +660,8 @@ class PostgresTransaction {
     }
     async appendCommit(commit) {
         this.#assertOpen();
+        // The commit writes its delete tombstones below.
+        this.#prefetchedTombstones.clear();
         const q = this.#client;
         const p = this.#partition;
         // Allocate the next dense commitSeq under a per-partition row lock: the
@@ -626,40 +684,36 @@ class PostgresTransaction {
             this.#writerVersion,
         ]);
         const commitSeq = asNumber(rows[0]?.commit_seq);
-        for (let idx = 0; idx < commit.changes.length; idx++) {
-            const change = commit.changes[idx];
-            if (change === undefined)
-                continue;
-            // Bind serialized scopes as text before parsing JSONB. Drivers that
-            // encode JSONB parameters would otherwise store this string as a scalar.
-            // One statement per change: scopes AND the §5 delete tombstone ride the
-            // same writable-CTE chain.
-            await q.query(`WITH inserted AS (
-           INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
-           VALUES ($1,$2,$3,$4,$5,$6,$7,$8::text::jsonb,$9)
-           RETURNING partition, tbl, row_id, op, commit_seq, scopes
-         ),
-         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)
-         SELECT partition, tbl, row_id, commit_seq FROM inserted WHERE op = 2
-         ON CONFLICT (partition, tbl, row_id)
-         DO UPDATE SET commit_seq = excluded.commit_seq`, [
-                p,
-                commitSeq,
-                idx,
-                change.table,
-                change.rowId,
-                change.op === 'upsert' ? 1 : 2,
-                change.rowVersion ?? null,
-                JSON.stringify(change.scopes),
-                change.payload ?? null,
-            ]);
-        }
+        if (commit.changes.length === 0)
+            return commitSeq;
+        // One statement for the whole commit: its changes, their inverted scope
+        // entries, and the §5 delete tombstones ride one writable-CTE chain.
+        // 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 the tombstone insert keeps one
+        // row per key (every candidate carries the same commit_seq).
+        const params = [p, commitSeq];
+        const values = commit.changes.map((change, idx) => {
+            const base = params.length;
+            params.push(idx, 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 (
+         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)
+       SELECT DISTINCT ON (tbl, row_id) partition, tbl, row_id, commit_seq
+         FROM inserted WHERE op = 2
+       ON CONFLICT (partition, tbl, row_id)
+       DO UPDATE SET commit_seq = excluded.commit_seq`, params);
         return commitSeq;
     }
     async putPushResult(clientId, clientCommitId, result) {

package/dist/push.js

@@ -420,8 +420,12 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
     const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, tx, partition, actorId);
     if (insertReject !== undefined)
         return insertReject;
-    // §5.2: an explicit insert recreates — the tombstone goes with it.
-    await tx.clearTombstone(op.table, op.rowId);
+    // §5.2: an explicit insert recreates — the tombstone goes with it. An
+    // unversioned insert already proved above, under the partition lock, that
+    // no tombstone exists (this commit writes its own only in `appendCommit`).
+    if (op.baseVersion !== undefined) {
+        await tx.clearTombstone(op.table, op.rowId);
+    }
     const newRow = {
         rowId: op.rowId,
         serverVersion: 1,
@@ -915,6 +919,19 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
         const stagedWrites = [];
         let terminated;
         const operations = await buildOperations(tx);
+        if (tx.prefetchRows !== undefined) {
+            const targets = new Map();
+            for (const op of operations) {
+                if (!schema.tables.has(op.table))
+                    continue;
+                const ids = targets.get(op.table) ?? [];
+                ids.push(op.rowId);
+                targets.set(op.table, ids);
+            }
+            for (const [table, rowIds] of targets) {
+                await tx.prefetchRows(table, rowIds);
+            }
+        }
         for (let opIndex = 0; opIndex < operations.length; opIndex++) {
             const op = operations[opIndex];
             if (op === undefined)

package/dist/relational-rows.d.ts

@@ -249,6 +249,12 @@ export declare function scanRowBatchSql(table: CompiledTable): string;
  * `scanRowBatchSql`.
  */
 export declare const COMMIT_WINDOW_BATCH_SQL = "SELECT s.i AS sub, c.commit_seq AS commit_seq, m.actor_id AS actor_id, m.created_at_ms AS created_at_ms,\n       ch.tbl AS tbl, ch.row_id AS row_id, ch.op AS op, ch.row_version AS row_version, ch.scopes AS scopes, ch.payload AS payload\n     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals text[], after bigint, through bigint, lim int)\n     CROSS JOIN LATERAL (SELECT DISTINCT commit_seq FROM sync_change_scopes\n       WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=ANY(s.vals)\n         AND commit_seq>s.after AND commit_seq<=s.through\n       ORDER BY commit_seq LIMIT s.lim) c\n     LEFT JOIN sync_commits m\n       ON m.partition=$1 AND m.commit_seq=c.commit_seq\n     LEFT JOIN sync_changes ch\n       ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=$3\n     ORDER BY s.i, c.commit_seq, ch.idx";
+/**
+ * PostgreSQL push read-ahead: every requested row id with its stored row
+ * (NULL columns when absent, `selectRowSql` shape) and its §5 delete
+ * tombstone. Params: [partition, rowIds as JSON array text, tbl].
+ */
+export declare function prefetchRowsSql(table: CompiledTable): string;
 /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
 export declare function selectRowScopesSql(table: CompiledTable, dialect: RelationalDialect): string;
 /** DELETE one stored row. Params: [partition, rowId]. */

package/dist/relational-rows.js

@@ -593,6 +593,19 @@ export const COMMIT_WINDOW_BATCH_SQL = `SELECT s.i AS sub, c.commit_seq AS commi
      LEFT JOIN sync_changes ch
        ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=$3
      ORDER BY s.i, c.commit_seq, ch.idx`;
+/**
+ * PostgreSQL push read-ahead: every requested row id with its stored row
+ * (NULL columns when absent, `selectRowSql` shape) and its §5 delete
+ * tombstone. Params: [partition, rowIds as JSON array text, tbl].
+ */
+export function prefetchRowsSql(table) {
+    return `SELECT ids.id AS lookup_id, r.${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions, t.commit_seq AS tombstone_seq
+     FROM jsonb_array_elements_text($2::text::jsonb) AS ids(id)
+     LEFT JOIN ${quoteIdent(table.name)} r
+       ON r.${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND r.${quoteIdent(SYNC_ROW_ID_COLUMN)}=ids.id
+     LEFT JOIN sync_tombstones t
+       ON t.partition=$1 AND t.tbl=$3 AND t.row_id=ids.id`;
+}
 /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
 export function selectRowScopesSql(table, dialect) {
     const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];

package/dist/storage.d.ts

@@ -344,6 +344,14 @@ export interface AuthoritativeQueryResult {
  */
 export interface StorageTransaction {
     getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+    /**
+     * Optional read-ahead: the push layer names every row a commit's
+     * operations target, per table, before it applies them. A storage with
+     * per-statement network cost reads them in one statement and answers the
+     * following `getRow` calls from that snapshot until the row is written in
+     * this transaction.
+     */
+    prefetchRows?(table: string, rowIds: readonly string[]): Promise<void>;
     /**
      * §5 delete-precedence tombstone read: the `commit_seq` of the newest
      * applied delete of this row still within the pruning horizon, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.26.4",
+  "version": "0.26.5",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.26.4"
+    "@syncular/core": "0.26.5"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/postgres-storage.ts

@@ -76,6 +76,7 @@ import {
   schemaDdl,
   selectRowScopesSql,
   selectRowSql,
+  prefetchRowsSql,
   selectRowsForRewriteSql,
   upsertSql,
   upsertValues,
@@ -697,21 +698,31 @@ async function writeRowOn(
   partition: string,
   row: StoredRow,
 ): Promise<void> {
+  // One statement per row write: the upsert, and the scope index synced to
+  // the row's scope map (entries outside it deleted, missing ones inserted).
+  // No index entry is touched twice, so the writable CTEs cannot conflict.
+  // The scopes bind as text before the JSONB cast (see `appendCommit`).
+  const params = upsertValues(compiled, partition, row, 'postgres');
+  const n = params.length;
   await q.query(
-    upsertSql(compiled, 'postgres'),
-    upsertValues(compiled, partition, row, 'postgres'),
-  );
-  await q.query(
-    'DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$2 AND row_id=$3',
-    [partition, compiled.name, row.rowId],
+    `WITH upserted AS (${upsertSql(compiled, 'postgres')}),
+     scope AS (SELECT key, value FROM jsonb_each_text($${n + 1}::text::jsonb)),
+     removed AS (
+       DELETE FROM sync_row_scopes
+        WHERE partition=$${n + 2} AND tbl=$${n + 3} AND row_id=$${n + 4}
+          AND (var, value) NOT IN (SELECT key, value FROM scope)
+     )
+     INSERT INTO sync_row_scopes(partition, tbl, var, value, row_id)
+     SELECT $${n + 2}, $${n + 3}, key, value, $${n + 4} FROM scope
+     ON CONFLICT DO NOTHING`,
+    [
+      ...params,
+      JSON.stringify(row.scopes),
+      partition,
+      compiled.name,
+      row.rowId,
+    ],
   );
-  for (const [variable, value] of Object.entries(row.scopes)) {
-    await q.query(
-      `INSERT INTO sync_row_scopes(partition, tbl, var, value, row_id)
-       VALUES ($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`,
-      [partition, compiled.name, variable, value, row.rowId],
-    );
-  }
 }
 
 async function getPushResultOn(
@@ -770,6 +781,13 @@ class PostgresTransaction implements StorageTransaction {
   #resolveTable: (name: string) => CompiledTable;
   #open = true;
   #pushApplySavepoint = false;
+  /**
+   * `prefetchRows` results keyed `table\u0000rowId`; `null` records a row
+   * (or tombstone) read as absent. A write in this transaction drops the
+   * key, so the next read goes to the database again.
+   */
+  readonly #prefetchedRows = new Map<string, StoredRow | null>();
+  readonly #prefetchedTombstones = new Map<string, number | null>();
   /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
   #resolve: () => void;
   #reject: (error: unknown) => void;
@@ -814,6 +832,10 @@ class PostgresTransaction implements StorageTransaction {
 
   getRow(table: string, rowId: string): Promise<StoredRow | undefined> {
     this.#assertOpen();
+    const prefetched = this.#prefetchedRows.get(`${table}\u0000${rowId}`);
+    if (prefetched !== undefined) {
+      return Promise.resolve(prefetched ?? undefined);
+    }
     return getRowOn(
       this.#client,
       this.#resolveTable(table),
@@ -822,11 +844,47 @@ class PostgresTransaction implements StorageTransaction {
     );
   }
 
+  async prefetchRows(table: string, rowIds: readonly string[]): Promise<void> {
+    this.#assertOpen();
+    const ids = [...new Set(rowIds)].filter(
+      (rowId) => !this.#prefetchedRows.has(`${table}\u0000${rowId}`),
+    );
+    if (ids.length === 0) return;
+    const { rows } = await this.#client.query<
+      Omit<RowRecord, 'row_id'> & {
+        lookup_id: string;
+        row_id: string | null;
+        tombstone_seq: unknown;
+      }
+    >(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
+          ? null
+          : toStoredRow({ ...record, row_id: record.row_id }),
+      );
+      this.#prefetchedTombstones.set(
+        key,
+        record.tombstone_seq === null || record.tombstone_seq === undefined
+          ? null
+          : asNumber(record.tombstone_seq),
+      );
+    }
+  }
+
   async getTombstoneSeq(
     table: string,
     rowId: string,
   ): Promise<number | undefined> {
     this.#assertOpen();
+    const prefetched = this.#prefetchedTombstones.get(`${table}\u0000${rowId}`);
+    if (prefetched !== undefined) return prefetched ?? undefined;
     const { rows } = await this.#client.query<{ commit_seq: unknown }>(
       'SELECT commit_seq FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3',
       [this.#partition, table, rowId],
@@ -837,6 +895,7 @@ class PostgresTransaction implements StorageTransaction {
 
   async clearTombstone(table: string, rowId: string): Promise<void> {
     this.#assertOpen();
+    this.#prefetchedTombstones.delete(`${table}\u0000${rowId}`);
     await this.#client.query(
       'DELETE FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3',
       [this.#partition, table, rowId],
@@ -976,6 +1035,7 @@ class PostgresTransaction implements StorageTransaction {
     context?: { readonly opIndex: number },
   ): Promise<void> {
     this.#assertOpen();
+    this.#prefetchedRows.delete(`${table}\u0000${row.rowId}`);
     try {
       await writeRowOn(
         this.#client,
@@ -993,18 +1053,16 @@ class PostgresTransaction implements StorageTransaction {
 
   async deleteRow(table: string, rowId: string): Promise<void> {
     this.#assertOpen();
+    this.#prefetchedRows.delete(`${table}\u0000${rowId}`);
+    // 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(
-      deleteRowSql(this.#resolveTable(table), 'postgres'),
-      [this.#partition, rowId],
-    );
-    await this.#client.query(
-      'DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$2 AND row_id=$3',
-      [this.#partition, table, rowId],
-    );
-    // §5.9.4: a deleted row references no blobs.
-    await this.#client.query(
-      'DELETE FROM sync_blob_refs WHERE partition=$1 AND tbl=$2 AND row_id=$3',
-      [this.#partition, table, rowId],
+      `WITH deleted AS (${deleteRowSql(this.#resolveTable(table), 'postgres')}),
+       unscoped AS (
+         DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$3 AND row_id=$2
+       )
+       DELETE FROM sync_blob_refs WHERE partition=$1 AND tbl=$3 AND row_id=$2`,
+      [this.#partition, rowId, table],
     );
   }
 
@@ -1030,6 +1088,8 @@ class PostgresTransaction implements StorageTransaction {
 
   async appendCommit(commit: NewCommit): Promise<number> {
     this.#assertOpen();
+    // The commit writes its delete tombstones below.
+    this.#prefetchedTombstones.clear();
     const q = this.#client;
     const p = this.#partition;
     // Allocate the next dense commitSeq under a per-partition row lock: the
@@ -1055,42 +1115,46 @@ class PostgresTransaction implements StorageTransaction {
       ],
     );
     const commitSeq = asNumber(rows[0]?.commit_seq);
-    for (let idx = 0; idx < commit.changes.length; idx++) {
-      const change = commit.changes[idx];
-      if (change === undefined) continue;
-      // Bind serialized scopes as text before parsing JSONB. Drivers that
-      // encode JSONB parameters would otherwise store this string as a scalar.
-      // One statement per change: scopes AND the §5 delete tombstone ride the
-      // same writable-CTE chain.
-      await q.query(
-        `WITH inserted AS (
-           INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
-           VALUES ($1,$2,$3,$4,$5,$6,$7,$8::text::jsonb,$9)
-           RETURNING partition, tbl, row_id, op, commit_seq, scopes
-         ),
-         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)
-         SELECT partition, tbl, row_id, commit_seq FROM inserted WHERE op = 2
-         ON CONFLICT (partition, tbl, row_id)
-         DO UPDATE SET commit_seq = excluded.commit_seq`,
-        [
-          p,
-          commitSeq,
-          idx,
-          change.table,
-          change.rowId,
-          change.op === 'upsert' ? 1 : 2,
-          change.rowVersion ?? null,
-          JSON.stringify(change.scopes),
-          change.payload ?? null,
-        ],
+    if (commit.changes.length === 0) return commitSeq;
+    // One statement for the whole commit: its changes, their inverted scope
+    // entries, and the §5 delete tombstones ride one writable-CTE chain.
+    // 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 the tombstone insert keeps one
+    // row per key (every candidate carries the same commit_seq).
+    const params: unknown[] = [p, commitSeq];
+    const values = commit.changes.map((change, idx) => {
+      const base = params.length;
+      params.push(
+        idx,
+        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 (
+         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)
+       SELECT DISTINCT ON (tbl, row_id) partition, tbl, row_id, commit_seq
+         FROM inserted WHERE op = 2
+       ON CONFLICT (partition, tbl, row_id)
+       DO UPDATE SET commit_seq = excluded.commit_seq`,
+      params,
+    );
     return commitSeq;
   }
 

package/src/push.ts

@@ -696,8 +696,12 @@ async function applyOperation(
     actorId,
   );
   if (insertReject !== undefined) return insertReject;
-  // §5.2: an explicit insert recreates — the tombstone goes with it.
-  await tx.clearTombstone(op.table, op.rowId);
+  // §5.2: an explicit insert recreates — the tombstone goes with it. An
+  // unversioned insert already proved above, under the partition lock, that
+  // no tombstone exists (this commit writes its own only in `appendCommit`).
+  if (op.baseVersion !== undefined) {
+    await tx.clearTombstone(op.table, op.rowId);
+  }
   const newRow = {
     rowId: op.rowId,
     serverVersion: 1,
@@ -1415,6 +1419,18 @@ export async function processPushOperationsWithTrace(
     const stagedWrites: StagedWrite[] = [];
     let terminated: PushOperationResult | undefined;
     const operations = await buildOperations(tx);
+    if (tx.prefetchRows !== undefined) {
+      const targets = new Map<string, string[]>();
+      for (const op of operations) {
+        if (!schema.tables.has(op.table)) continue;
+        const ids = targets.get(op.table) ?? [];
+        ids.push(op.rowId);
+        targets.set(op.table, ids);
+      }
+      for (const [table, rowIds] of targets) {
+        await tx.prefetchRows(table, rowIds);
+      }
+    }
     for (let opIndex = 0; opIndex < operations.length; opIndex++) {
       const op = operations[opIndex];
       if (op === undefined) continue;

package/src/relational-rows.ts

@@ -691,6 +691,20 @@ export const COMMIT_WINDOW_BATCH_SQL = `SELECT s.i AS sub, c.commit_seq AS commi
        ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=$3
      ORDER BY s.i, c.commit_seq, ch.idx`;
 
+/**
+ * PostgreSQL push read-ahead: every requested row id with its stored row
+ * (NULL columns when absent, `selectRowSql` shape) and its §5 delete
+ * tombstone. Params: [partition, rowIds as JSON array text, tbl].
+ */
+export function prefetchRowsSql(table: CompiledTable): string {
+  return `SELECT ids.id AS lookup_id, r.${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions, t.commit_seq AS tombstone_seq
+     FROM jsonb_array_elements_text($2::text::jsonb) AS ids(id)
+     LEFT JOIN ${quoteIdent(table.name)} r
+       ON r.${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND r.${quoteIdent(SYNC_ROW_ID_COLUMN)}=ids.id
+     LEFT JOIN sync_tombstones t
+       ON t.partition=$1 AND t.tbl=$3 AND t.row_id=ids.id`;
+}
+
 /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
 export function selectRowScopesSql(
   table: CompiledTable,

package/src/storage.ts

@@ -433,6 +433,14 @@ export interface AuthoritativeQueryResult {
  */
 export interface StorageTransaction {
   getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+  /**
+   * Optional read-ahead: the push layer names every row a commit's
+   * operations target, per table, before it applies them. A storage with
+   * per-statement network cost reads them in one statement and answers the
+   * following `getRow` calls from that snapshot until the row is written in
+   * this transaction.
+   */
+  prefetchRows?(table: string, rowIds: readonly string[]): Promise<void>;
   /**
    * §5 delete-precedence tombstone read: the `commit_seq` of the newest
    * applied delete of this row still within the pruning horizon, or