@syncular/server 0.45.1 → 0.46.3

package/README.md

@@ -255,7 +255,8 @@ const config: SyncServerConfig = {
 };
 ```
 
-The callback also receives `read.getRow()`, bounded `read.scanRows()`, and
+The callback also receives `read.getRow()` and its batch form
+`read.getRows(table, rowIds)`, bounded `read.scanRows()`, and
 `read.queryAuthoritative()` APIs. Those reads see the final candidate state, including staged sibling upserts and
 deletes. Syncular serializes the partition before any operation read so two
 aggregate validators cannot both accept mutually invalid candidates. It also

package/dist/d1-storage.js

@@ -175,6 +175,18 @@ class D1Transaction {
             .first();
         return record === null ? undefined : toStoredRow(record);
     }
+    async getRows(table, rowIds) {
+        this.#assertOpen();
+        // One lookup per id: `getRow` owns the buffered-write overlay, and a
+        // mutable id list cannot share one bound statement across D1's limit.
+        const rows = new Map();
+        for (const rowId of new Set(rowIds)) {
+            const row = await this.getRow(table, rowId);
+            if (row !== undefined)
+                rows.set(rowId, row);
+        }
+        return rows;
+    }
     async getTombstoneSeq(table, rowId) {
         this.#assertOpen();
         if (this.#clearedTombstones.has(_a.#key(table, rowId))) {

package/dist/operations.d.ts

@@ -68,6 +68,14 @@ export interface RemoteCommandContext {
     readonly operationId: string;
     readonly requestId: string;
     getRow(table: string, rowId: string): Promise<ValidateRow | undefined>;
+    /**
+     * Batch form of `getRow` with the same scope authorization: a row outside
+     * the actor's resolved scopes is missing from the map, exactly as `getRow`
+     * returns `undefined` for it. Reads observe this commit's staged writes and
+     * deletes. Postgres answers any number of ids in one statement; SQLite and
+     * D1 issue one lookup per id.
+     */
+    getRows(table: string, rowIds: readonly string[]): Promise<ReadonlyMap<string, ValidateRow>>;
     /**
      * Run a generated registered query on the command's push transaction
      * (§6.7). The storage binds every relation to the partition; unlike

package/dist/operations.js

@@ -5,6 +5,7 @@ import { reportError, SyncError, syncError } from './errors.js';
 import { processPushOperationsWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
 import { authorizeWrite, renderScopeValue, } from './scopes.js';
+import { readCandidateRows } from './storage.js';
 import { transactionQuery } from './storage-query.js';
 import { toValidateRow, ValidationRejection, } from './validate.js';
 function scopeAllowed(allowed, variable, value) {
@@ -296,6 +297,23 @@ function commandContext(ctx, tx, resolved, schema, clientId, operationId, reques
             }
             return toValidateRow(table.columns, decodeRow(table.columns, stored.payload));
         },
+        getRows: async (tableName, rowIds) => {
+            const table = schema.tables.get(tableName);
+            if (table === undefined) {
+                throw syncError('operation.invalid_request', 'command read targets an unknown table');
+            }
+            const storedRows = await readCandidateRows(tx, tableName, rowIds);
+            const rows = new Map();
+            for (const rowId of rowIds) {
+                const stored = storedRows.get(rowId);
+                if (stored === undefined ||
+                    !authorizeWrite(table, stored.scopes, resolved)) {
+                    continue;
+                }
+                rows.set(rowId, toValidateRow(table.columns, decodeRow(table.columns, stored.payload)));
+            }
+            return rows;
+        },
         queryAuthoritative: (query) => transactionQuery(tx, query),
     };
 }

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, prefetchRowsBatchSql, 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, selectRowsSql, 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';
@@ -829,6 +829,27 @@ class PostgresTransaction {
         }
         return getRowOn(this.#client, this.#resolveTable(table), this.#partition, rowId);
     }
+    async getRows(table, rowIds) {
+        this.#assertOpen();
+        const rows = new Map();
+        const missing = [];
+        for (const rowId of new Set(rowIds)) {
+            const prefetched = this.#prefetchedRows.get(`${table}\u0000${rowId}`);
+            if (prefetched === undefined)
+                missing.push(rowId);
+            else if (prefetched !== null)
+                rows.set(rowId, prefetched);
+        }
+        if (missing.length === 0)
+            return rows;
+        // One statement for every id the admission read did not already answer.
+        // `#client` flushes this transaction's staged upserts first, so the rows
+        // are the final candidate state.
+        const { rows: records } = await this.#client.query(selectRowsSql(this.#resolveTable(table)), [this.#partition, missing]);
+        for (const record of records)
+            rows.set(record.row_id, toStoredRow(record));
+        return rows;
+    }
     async prefetchRows(targets) {
         this.#assertOpen();
         const tables = [];

package/dist/push.js

@@ -25,7 +25,7 @@ import { emitEvent } from './events.js';
 import { prepareReactions, toNewReactions, } from './reactions.js';
 import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.js';
 import { decodeColumnVersions, encodeColumnVersions } from './relational-rows.js';
-import { serveGateRefusal } from './storage.js';
+import { readCandidateRows, serveGateRefusal } from './storage.js';
 import { StorageConstraintError } from './storage-errors.js';
 import { transactionQuery } from './storage-query.js';
 import { serveNotReadyError } from './readiness.js';
@@ -662,6 +662,21 @@ function commitValidationReader(tx, schema) {
                 serverVersion: stored.serverVersion,
             };
         },
+        getRows: async (tableName, rowIds) => {
+            const table = tableFor(tableName);
+            const storedRows = await readCandidateRows(tx, tableName, rowIds);
+            const rows = new Map();
+            for (const rowId of rowIds) {
+                const stored = storedRows.get(rowId);
+                if (stored === undefined)
+                    continue;
+                rows.set(rowId, {
+                    row: toValidateRow(table.columns, decodeRow(table.columns, stored.payload)),
+                    serverVersion: stored.serverVersion,
+                });
+            }
+            return rows;
+        },
         scanRows: async ({ table: tableName, scopeFilter, afterRowId = null, limit = 100, }) => {
             const table = tableFor(tableName);
             if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1_000) {

package/dist/relational-rows.d.ts

@@ -188,6 +188,13 @@ export declare function upsertSql(table: CompiledTable, dialect: RelationalDiale
  * `toStoredRow` converters keep working. Params: [partition, rowId].
  */
 export declare function selectRowSql(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * SELECT many stored rows of one table by primary key in one statement.
+ * Postgres binds the ids as one `text[]` (`row_id = ANY($2)`), so the
+ * statement count does not grow with the id count. Params: [partition,
+ * rowIds]; absent ids contribute no row.
+ */
+export declare function selectRowsSql(table: CompiledTable): string;
 export interface IndexRowPageStatement {
     readonly sql: string;
     readonly params: readonly unknown[];

package/dist/relational-rows.js

@@ -491,6 +491,15 @@ export function selectRowSql(table, dialect) {
     const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];
     return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
 }
+/**
+ * SELECT many stored rows of one table by primary key in one statement.
+ * Postgres binds the ids as one `text[]` (`row_id = ANY($2)`), so the
+ * statement count does not grow with the id count. Params: [partition,
+ * rowIds]; absent ids contribute no row.
+ */
+export function selectRowsSql(table) {
+    return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=ANY($2::text[])`;
+}
 /**
  * Bounded exact lookup through one declared relational index. Unlike
  * `scanRowPageSql`, this is a trusted server-host query: it never reads or

package/dist/sqlite-storage.js

@@ -80,6 +80,17 @@ class SqliteTransaction {
         this.#assertOpen();
         return this.#storage.getRow(this.#partition, table, rowId);
     }
+    async getRows(table, rowIds) {
+        this.#assertOpen();
+        // SQLite is in-process: one indexed lookup per id costs no round trip.
+        const rows = new Map();
+        for (const rowId of new Set(rowIds)) {
+            const row = await this.#storage.getRow(this.#partition, table, rowId);
+            if (row !== undefined)
+                rows.set(rowId, row);
+        }
+        return rows;
+    }
     async getTombstoneSeq(table, rowId) {
         this.#assertOpen();
         const row = this.#storage.db

package/dist/storage.d.ts

@@ -425,6 +425,16 @@ export interface AuthoritativeQueryResult {
  */
 export interface StorageTransaction {
     getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+    /**
+     * Optional candidate-state batch read by primary key. A storage with
+     * per-statement network cost answers any number of ids in one statement
+     * (Postgres binds the ids as one array); SQLite and D1 issue one lookup per
+     * id. Absent ids are missing from the map and repeated ids read once. The
+     * result observes this transaction's staged writes and deletes, exactly as
+     * `getRow` does. Both commit readers fall back to one `getRow` per id when
+     * a custom transaction omits the capability.
+     */
+    getRows?(table: string, rowIds: readonly string[]): Promise<ReadonlyMap<string, StoredRow>>;
     /**
      * Optional read-ahead: the push layer names every row a commit's
      * operations target, across every table, before it applies them. A storage
@@ -542,6 +552,12 @@ export interface StorageTransaction {
     commit(): Promise<void>;
     rollback(): Promise<void>;
 }
+/**
+ * The commit readers' batch read: delegate to the transaction's `getRows`
+ * when it implements the capability, otherwise issue one `getRow` per id.
+ * Both paths read the same candidate state; only the statement count differs.
+ */
+export declare function readCandidateRows(tx: StorageTransaction, table: string, rowIds: readonly string[]): Promise<ReadonlyMap<string, StoredRow>>;
 export interface ServerStorage {
     /**
      * Create/migrate the relational per-app row tables for `schema`

package/dist/storage.js

@@ -75,3 +75,22 @@ export function clientRoundState(lastRoundAtMs, lastErrorCode, consecutiveFailur
 /** Durable partition identity refreshed after host authentication (§2.1). */
 /** Longest age of `lastAuthenticatedAtMs` that `touchPartition` leaves unwritten. */
 export const PARTITION_TOUCH_INTERVAL_MS = 60_000;
+/**
+ * The commit readers' batch read: delegate to the transaction's `getRows`
+ * when it implements the capability, otherwise issue one `getRow` per id.
+ * Both paths read the same candidate state; only the statement count differs.
+ */
+export async function readCandidateRows(tx, table, rowIds) {
+    const ids = [...new Set(rowIds)];
+    if (ids.length === 0)
+        return new Map();
+    if (tx.getRows !== undefined)
+        return tx.getRows(table, ids);
+    const rows = new Map();
+    for (const rowId of ids) {
+        const row = await tx.getRow(table, rowId);
+        if (row !== undefined)
+            rows.set(rowId, row);
+    }
+    return rows;
+}

package/dist/validate.d.ts

@@ -81,6 +81,15 @@ export interface CommitValidationScanInput {
  */
 export interface CommitValidationReader {
     getRow(table: string, rowId: string): Promise<CommitValidationRow | undefined>;
+    /**
+     * Batch candidate-state read by primary key, with the same read-your-own-
+     * writes guarantee as `getRow`: staged sibling upserts are present and
+     * staged deletes are absent. An absent id is missing from the map and a
+     * repeated id reads once. There is no scope declaration and no paging: the
+     * caller already holds partition authority. Postgres answers any number of
+     * ids in one statement; SQLite and D1 issue one lookup per id.
+     */
+    getRows(table: string, rowIds: readonly string[]): Promise<ReadonlyMap<string, CommitValidationRow>>;
     scanRows(input: CommitValidationScanInput): Promise<CommitValidationRow[]>;
     /**
      * Run a generated registered query on the commit transaction (§6.8). The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.45.1",
+  "version": "0.46.3",
   "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.45.1"
+    "@syncular/core": "0.46.3"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/d1-storage.ts

@@ -360,6 +360,21 @@ class D1Transaction implements StorageTransaction {
     return record === null ? undefined : toStoredRow(record);
   }
 
+  async getRows(
+    table: string,
+    rowIds: readonly string[],
+  ): Promise<ReadonlyMap<string, StoredRow>> {
+    this.#assertOpen();
+    // One lookup per id: `getRow` owns the buffered-write overlay, and a
+    // mutable id list cannot share one bound statement across D1's limit.
+    const rows = new Map<string, StoredRow>();
+    for (const rowId of new Set(rowIds)) {
+      const row = await this.getRow(table, rowId);
+      if (row !== undefined) rows.set(rowId, row);
+    }
+    return rows;
+  }
+
   async getTombstoneSeq(
     table: string,
     rowId: string,

package/src/operations.ts

@@ -32,6 +32,7 @@ import type {
   AuthoritativeQueryValue,
 } from './storage';
 import type { StorageTransaction } from './storage';
+import { readCandidateRows } from './storage';
 import { transactionQuery } from './storage-query';
 import {
   toValidateRow,
@@ -126,6 +127,17 @@ export interface RemoteCommandContext {
   readonly operationId: string;
   readonly requestId: string;
   getRow(table: string, rowId: string): Promise<ValidateRow | undefined>;
+  /**
+   * Batch form of `getRow` with the same scope authorization: a row outside
+   * the actor's resolved scopes is missing from the map, exactly as `getRow`
+   * returns `undefined` for it. Reads observe this commit's staged writes and
+   * deletes. Postgres answers any number of ids in one statement; SQLite and
+   * D1 issue one lookup per id.
+   */
+  getRows(
+    table: string,
+    rowIds: readonly string[],
+  ): Promise<ReadonlyMap<string, ValidateRow>>;
   /**
    * Run a generated registered query on the command's push transaction
    * (§6.7). The storage binds every relation to the partition; unlike
@@ -599,6 +611,34 @@ function commandContext(
         decodeRow(table.columns, stored.payload),
       );
     },
+    getRows: async (tableName, rowIds) => {
+      const table = schema.tables.get(tableName);
+      if (table === undefined) {
+        throw syncError(
+          'operation.invalid_request',
+          'command read targets an unknown table',
+        );
+      }
+      const storedRows = await readCandidateRows(tx, tableName, rowIds);
+      const rows = new Map<string, ValidateRow>();
+      for (const rowId of rowIds) {
+        const stored = storedRows.get(rowId);
+        if (
+          stored === undefined ||
+          !authorizeWrite(table, stored.scopes, resolved)
+        ) {
+          continue;
+        }
+        rows.set(
+          rowId,
+          toValidateRow(
+            table.columns,
+            decodeRow(table.columns, stored.payload),
+          ),
+        );
+      }
+      return rows;
+    },
     queryAuthoritative: (query) => transactionQuery(tx, query),
   };
 }

package/src/postgres-storage.ts

@@ -92,6 +92,7 @@ import {
   serverIndexDdl,
   selectRowScopesSql,
   selectRowSql,
+  selectRowsSql,
   prefetchRowsBatchSql,
   selectRowsForRewriteSql,
   upsertSql,
@@ -1300,6 +1301,30 @@ class PostgresTransaction implements StorageTransaction {
     );
   }
 
+  async getRows(
+    table: string,
+    rowIds: readonly string[],
+  ): Promise<ReadonlyMap<string, StoredRow>> {
+    this.#assertOpen();
+    const rows = new Map<string, StoredRow>();
+    const missing: string[] = [];
+    for (const rowId of new Set(rowIds)) {
+      const prefetched = this.#prefetchedRows.get(`${table}\u0000${rowId}`);
+      if (prefetched === undefined) missing.push(rowId);
+      else if (prefetched !== null) rows.set(rowId, prefetched);
+    }
+    if (missing.length === 0) return rows;
+    // One statement for every id the admission read did not already answer.
+    // `#client` flushes this transaction's staged upserts first, so the rows
+    // are the final candidate state.
+    const { rows: records } = await this.#client.query<RowRecord>(
+      selectRowsSql(this.#resolveTable(table)),
+      [this.#partition, missing],
+    );
+    for (const record of records) rows.set(record.row_id, toStoredRow(record));
+    return rows;
+  }
+
   async prefetchRows(
     targets: readonly {
       readonly table: string;

package/src/push.ts

@@ -54,12 +54,13 @@ import type {
   StoredPushResult,
   StoredRow,
 } from './storage';
-import { serveGateRefusal } from './storage';
+import { readCandidateRows, serveGateRefusal } from './storage';
 import { StorageConstraintError } from './storage-errors';
 import { transactionQuery } from './storage-query';
 import { serveNotReadyError } from './readiness';
 import type {
   CommitValidationReader,
+  CommitValidationRow,
   CommitValidator,
   ValidateCommitOperation,
   ValidateOpKind,
@@ -1061,6 +1062,23 @@ function commitValidationReader(
         serverVersion: stored.serverVersion,
       };
     },
+    getRows: async (tableName, rowIds) => {
+      const table = tableFor(tableName);
+      const storedRows = await readCandidateRows(tx, tableName, rowIds);
+      const rows = new Map<string, CommitValidationRow>();
+      for (const rowId of rowIds) {
+        const stored = storedRows.get(rowId);
+        if (stored === undefined) continue;
+        rows.set(rowId, {
+          row: toValidateRow(
+            table.columns,
+            decodeRow(table.columns, stored.payload),
+          ),
+          serverVersion: stored.serverVersion,
+        });
+      }
+      return rows;
+    },
     scanRows: async ({
       table: tableName,
       scopeFilter,

package/src/relational-rows.ts

@@ -607,6 +607,16 @@ export function selectRowSql(
   return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
 }
 
+/**
+ * SELECT many stored rows of one table by primary key in one statement.
+ * Postgres binds the ids as one `text[]` (`row_id = ANY($2)`), so the
+ * statement count does not grow with the id count. Params: [partition,
+ * rowIds]; absent ids contribute no row.
+ */
+export function selectRowsSql(table: CompiledTable): string {
+  return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=ANY($2::text[])`;
+}
+
 export interface IndexRowPageStatement {
   readonly sql: string;
   readonly params: readonly unknown[];

package/src/sqlite-storage.ts

@@ -234,6 +234,20 @@ class SqliteTransaction implements StorageTransaction {
     return this.#storage.getRow(this.#partition, table, rowId);
   }
 
+  async getRows(
+    table: string,
+    rowIds: readonly string[],
+  ): Promise<ReadonlyMap<string, StoredRow>> {
+    this.#assertOpen();
+    // SQLite is in-process: one indexed lookup per id costs no round trip.
+    const rows = new Map<string, StoredRow>();
+    for (const rowId of new Set(rowIds)) {
+      const row = await this.#storage.getRow(this.#partition, table, rowId);
+      if (row !== undefined) rows.set(rowId, row);
+    }
+    return rows;
+  }
+
   async getTombstoneSeq(
     table: string,
     rowId: string,

package/src/storage.ts

@@ -557,6 +557,19 @@ export interface AuthoritativeQueryResult {
  */
 export interface StorageTransaction {
   getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+  /**
+   * Optional candidate-state batch read by primary key. A storage with
+   * per-statement network cost answers any number of ids in one statement
+   * (Postgres binds the ids as one array); SQLite and D1 issue one lookup per
+   * id. Absent ids are missing from the map and repeated ids read once. The
+   * result observes this transaction's staged writes and deletes, exactly as
+   * `getRow` does. Both commit readers fall back to one `getRow` per id when
+   * a custom transaction omits the capability.
+   */
+  getRows?(
+    table: string,
+    rowIds: readonly string[],
+  ): Promise<ReadonlyMap<string, StoredRow>>;
   /**
    * Optional read-ahead: the push layer names every row a commit's
    * operations target, across every table, before it applies them. A storage
@@ -704,6 +717,27 @@ export interface StorageTransaction {
   rollback(): Promise<void>;
 }
 
+/**
+ * The commit readers' batch read: delegate to the transaction's `getRows`
+ * when it implements the capability, otherwise issue one `getRow` per id.
+ * Both paths read the same candidate state; only the statement count differs.
+ */
+export async function readCandidateRows(
+  tx: StorageTransaction,
+  table: string,
+  rowIds: readonly string[],
+): Promise<ReadonlyMap<string, StoredRow>> {
+  const ids = [...new Set(rowIds)];
+  if (ids.length === 0) return new Map();
+  if (tx.getRows !== undefined) return tx.getRows(table, ids);
+  const rows = new Map<string, StoredRow>();
+  for (const rowId of ids) {
+    const row = await tx.getRow(table, rowId);
+    if (row !== undefined) rows.set(rowId, row);
+  }
+  return rows;
+}
+
 export interface ServerStorage {
   /**
    * Create/migrate the relational per-app row tables for `schema`

package/src/validate.ts

@@ -107,6 +107,18 @@ export interface CommitValidationReader {
     table: string,
     rowId: string,
   ): Promise<CommitValidationRow | undefined>;
+  /**
+   * Batch candidate-state read by primary key, with the same read-your-own-
+   * writes guarantee as `getRow`: staged sibling upserts are present and
+   * staged deletes are absent. An absent id is missing from the map and a
+   * repeated id reads once. There is no scope declaration and no paging: the
+   * caller already holds partition authority. Postgres answers any number of
+   * ids in one statement; SQLite and D1 issue one lookup per id.
+   */
+  getRows(
+    table: string,
+    rowIds: readonly string[],
+  ): Promise<ReadonlyMap<string, CommitValidationRow>>;
   scanRows(input: CommitValidationScanInput): Promise<CommitValidationRow[]>;
   /**
    * Run a generated registered query on the commit transaction (§6.8). The