@syncular/server 0.38.0 → 0.39.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, retiredTableNames, rewritePlan, rewriteRowSql, 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, 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, selectRowScopesSql, selectRowSql, prefetchRowsSql, 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';
@@ -22,7 +22,7 @@ import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js'
  * their table.
  *
  * `sync_row_scopes_by_row (partition, tbl, row_id)` is the one secondary
- * scope index: `writeRowOn` and `deleteRow` replace a row's scope entries
+ * scope index: `writeRowsOn` and `deleteRow` replace a row's scope entries
  * with a `(partition, tbl, row_id)` predicate, and `row_id` is the LAST
  * column of the inverted PRIMARY KEY, so without this index that predicate
  * scans the table's whole scope range on every row written (a bulk import
@@ -368,23 +368,52 @@ function toStoredChange(record) {
  */
 async function rewriteRowsOn(q, table, oldLayout) {
     const select = selectRowsForRewriteSql(table, 'postgres');
-    const update = rewriteRowSql(table, 'postgres');
-    const BATCH = 500;
+    // One UPDATE per page: behind a network hop (Hyperdrive, a managed
+    // database) every statement is a round trip, and the bump holds the
+    // migration lock for its whole duration. The page's rows bind as one
+    // VALUES list with typed placeholders (`rewriteValues` order: projection
+    // columns, payload, partition, row id).
+    const types = [
+        ...(table.materialize
+            ? table.columns.map((column) => columnSqlType(column, 'postgres'))
+            : []),
+        'BYTEA',
+        'TEXT',
+        'TEXT',
+    ];
+    const projected = table.materialize ? table.columns : [];
+    const sets = [
+        ...projected.map((column, i) => `${quoteIdent(column.name)}=v.c${i}`),
+        `${quoteIdent(SYNC_PAYLOAD_COLUMN)}=v.c${projected.length}`,
+    ].join(', ');
+    const aliases = types.map((_, i) => `c${i}`).join(', ');
+    const partitionAlias = `c${projected.length + 1}`;
+    const rowIdAlias = `c${projected.length + 2}`;
+    // A page binds types.length parameters per row; PGlite corrupts its state
+    // above 32,767 bound parameters (see PG_CHANGES_PER_STATEMENT).
+    const batch = Math.max(1, Math.min(500, Math.floor(30_000 / types.length)));
     let afterPartition = '';
     let afterRowId = '';
     for (;;) {
-        const { rows } = await q.query(select, [afterPartition, afterRowId, BATCH]);
+        const { rows } = await q.query(select, [afterPartition, afterRowId, batch]);
         if (rows.length === 0)
             break;
-        for (const row of rows) {
+        const params = [];
+        const values = rows.map((row) => {
             const bytes = asBytes(row.payload);
             const payload = oldLayout !== undefined
                 ? migratePayload(oldLayout, table, bytes)
                 : bytes;
-            await q.query(update, rewriteValues(table, row.partition, row.row_id, payload, 'postgres'));
-        }
+            const base = params.length;
+            params.push(...rewriteValues(table, row.partition, row.row_id, payload, 'postgres'));
+            return `(${types.map((type, i) => `$${base + i + 1}::${type}`).join(',')})`;
+        });
+        await q.query(`UPDATE ${quoteIdent(table.name)} AS t SET ${sets}
+         FROM (VALUES ${values.join(',')}) AS v(${aliases})
+        WHERE t.${quoteIdent(SYNC_PARTITION_COLUMN)}=v.${partitionAlias}
+          AND t.${quoteIdent(SYNC_ROW_ID_COLUMN)}=v.${rowIdAlias}`, params);
         const last = rows[rows.length - 1];
-        if (last === undefined || rows.length < BATCH)
+        if (last === undefined || rows.length < batch)
             break;
         afterPartition = last.partition;
         afterRowId = last.row_id;
@@ -402,29 +431,54 @@ async function scanRowsByIndexOn(q, compiled, partition, query) {
     const { rows } = await q.query(statement.sql, statement.params);
     return rows.map(toStoredRow);
 }
-async function writeRowOn(q, compiled, partition, row) {
-    // 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,
-    ]);
+/**
+ * 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.
+ */
+function writeRowsOn(q, compiled, partition, rows) {
+    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 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;
+        writes.push(q.query(`WITH upserted AS (${upsertSql(compiled, 'postgres', slice.length)}),
+         batch AS (
+           SELECT row_id, scopes
+             FROM jsonb_to_recordset($${n + 1}::text::jsonb) AS r(row_id text, scopes jsonb)
+         ),
+         scope AS (
+           SELECT batch.row_id, entry.key, entry.value
+             FROM batch CROSS JOIN LATERAL jsonb_each_text(batch.scopes) AS entry
+         ),
+         removed AS (
+           DELETE FROM sync_row_scopes existing
+            USING batch
+            WHERE existing.partition=$${n + 2} AND existing.tbl=$${n + 3}
+              AND existing.row_id=batch.row_id
+              AND NOT EXISTS (
+                SELECT 1 FROM scope
+                 WHERE scope.row_id=existing.row_id
+                   AND scope.key=existing.var AND scope.value=existing.value)
+         )
+         INSERT INTO sync_row_scopes(partition, tbl, var, value, row_id)
+         SELECT $${n + 2}, $${n + 3}, key, value, row_id FROM scope
+         ON CONFLICT DO NOTHING`, [
+            ...params,
+            JSON.stringify(slice.map(({ row }) => ({ row_id: row.rowId, scopes: row.scopes }))),
+            partition,
+            compiled.name,
+        ]));
+    }
+    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]);
@@ -450,6 +504,8 @@ async function queryAuthoritativeOn(client, partition, prepared) {
 }
 class PostgresTransaction {
     #client;
+    /** The FIFO without the staged-write prelude (see the constructor). */
+    #serial;
     #partition;
     /** Storage-owned relation rewrite, bound to this transaction's partition. */
     #prepareQuery;
@@ -465,6 +521,15 @@ class PostgresTransaction {
      */
     #prefetchedRows = new Map();
     #prefetchedTombstones = new Map();
+    /**
+     * Upserts staged per table (row id → row and its push operation index).
+     * Every statement of this transaction writes them first (see the
+     * constructor), so reads and later writes observe them; a commit's rows
+     * reach the database as one statement per table instead of one per row.
+     * Tables with a unique index write immediately: a violation must name its
+     * operation.
+     */
+    #staged = new Map();
     /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
     #resolve;
     #reject;
@@ -476,13 +541,31 @@ class PostgresTransaction {
         // issued through this transaction is chained on one FIFO — the same
         // shape as `SqliteServerStorage.queryAuthoritative`.
         let tail = Promise.resolve();
-        this.#client = {
+        const serial = {
             query: (text, params) => {
                 const run = tail.then(() => client.query(text, params));
                 tail = run.then(() => undefined, () => undefined);
                 return run;
             },
         };
+        this.#serial = serial;
+        this.#client = {
+            query: async (text, params) => {
+                // Queue the staged writes ahead of this statement synchronously, so
+                // a concurrently issued statement cannot overtake them.
+                const staged = this.#writeStaged();
+                const run = serial.query(text, params);
+                try {
+                    await staged;
+                }
+                catch (error) {
+                    // The aborted transaction fails the queued statement too.
+                    run.catch(() => undefined);
+                    throw error;
+                }
+                return run;
+            },
+        };
         this.#partition = partition;
         this.#writerVersion = writerVersion;
         this.#resolveTable = resolveTable;
@@ -494,6 +577,23 @@ class PostgresTransaction {
         if (!this.#open)
             throw new Error('transaction already finished');
     }
+    #writeStaged() {
+        if (this.#staged.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) => {
+                // 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 error;
+            });
+        }));
+    }
     getRow(table, rowId) {
         this.#assertOpen();
         const prefetched = this.#prefetchedRows.get(`${table}\u0000${rowId}`);
@@ -619,6 +719,7 @@ class PostgresTransaction {
         if (!this.#pushApplySavepoint) {
             throw new Error('push rejection requires its apply savepoint');
         }
+        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;
@@ -628,8 +729,28 @@ class PostgresTransaction {
     async upsertRow(table, row, context) {
         this.#assertOpen();
         this.#prefetchedRows.delete(`${table}\u0000${row.rowId}`);
+        const compiled = this.#resolveTable(table);
+        // Decodes the payload: an undecodable row fails here, at its operation.
+        const values = upsertValues(compiled, this.#partition, row, 'postgres');
+        if (!compiled.indexes.some((index) => index.unique === true)) {
+            let rows = this.#staged.get(compiled);
+            if (rows === undefined) {
+                rows = new Map();
+                this.#staged.set(compiled, rows);
+            }
+            // A later upsert of the same row in this transaction replaces it.
+            rows.delete(row.rowId);
+            rows.set(row.rowId, {
+                row,
+                values,
+                ...(context === undefined ? {} : { opIndex: context.opIndex }),
+            });
+            return;
+        }
         try {
-            await writeRowOn(this.#client, this.#resolveTable(table), this.#partition, row);
+            await writeRowsOn(this.#client, compiled, this.#partition, [
+                { row, values },
+            ]);
         }
         catch (error) {
             if (isPostgresConstraintError(error)) {
@@ -757,6 +878,7 @@ class PostgresTransaction {
     }
     async commit() {
         this.#assertOpen();
+        await this.#writeStaged();
         this.#open = false;
         // Signal the transaction wrapper to COMMIT; wait for it to actually land.
         this.#resolve();
@@ -765,6 +887,7 @@ class PostgresTransaction {
     async rollback() {
         if (!this.#open)
             return;
+        this.#staged.clear();
         this.#open = false;
         this.#reject(new RollbackSignal());
         // Swallow — a rollback is a normal outcome, not an error to the caller.
@@ -794,33 +917,39 @@ export class PostgresServerStorage {
     #schemaVersion;
     /**
      * Page reads waiting for the end of the current microtask turn, keyed by
-     * statement and partition. A pull starts the window read (or first
+     * batch stream and partition. A pull starts the window read (or first
      * snapshot page) of every subscription before awaiting any of them, so the
-     * window reads of all tables leave as ONE set-based statement (snapshot
-     * pages as one per table, whose SQL names the table) instead of one round
-     * trip per subscription or table (SYNCULAR-PULL-ROUNDTRIPS-001).
+     * reads of all tables leave as ONE set-based statement per stream instead
+     * of one round trip per subscription or table
+     * (SYNCULAR-PULL-ROUNDTRIPS-001).
      */
     #pageBatches = new Map();
     constructor(exec) {
         this.#exec = exec;
     }
     /**
-     * Queue one page read into the batch for (`sql`, `partition`). The batch
-     * runs as a single statement with the queued specs bound as a JSON array
-     * (`$2`); each spec gets its position as `i`, and the result rows are
-     * split back by their `sub` column.
+     * Queue one page read into the batch for (`key`, `partition`). `sql` is the
+     * statement every batch of that stream shares, or a builder over the queued
+     * specs when the statement names what the batch contains (the snapshot scan
+     * joins one branch per table present). The batch runs as a single statement
+     * with the queued specs bound as a JSON array (`$2`); each spec gets its
+     * position as `i`, and the result rows are split back by their `sub`
+     * column.
      */
-    #batchedPage(sql, partition, spec) {
-        const key = `${sql}\u0000${partition}`;
-        let batch = this.#pageBatches.get(key);
+    #batchedPage(key, sql, partition, spec) {
+        const batchKey = `${key}\u0000${partition}`;
+        let batch = this.#pageBatches.get(batchKey);
         if (batch === undefined) {
             const queued = [];
             batch = queued;
-            this.#pageBatches.set(key, queued);
+            this.#pageBatches.set(batchKey, queued);
             queueMicrotask(() => {
-                this.#pageBatches.delete(key);
-                const specs = JSON.stringify(queued.map((entry, i) => ({ ...entry.spec, i })));
-                this.#exec.query(sql, [partition, specs]).then(({ rows }) => {
+                this.#pageBatches.delete(batchKey);
+                const specs = queued.map((entry, i) => ({ ...entry.spec, i }));
+                const statement = typeof sql === 'string' ? sql : sql(specs);
+                this.#exec
+                    .query(statement, [partition, JSON.stringify(specs)])
+                    .then(({ rows }) => {
                     const grouped = queued.map(() => []);
                     for (const row of rows)
                         grouped[asNumber(row.sub)]?.push(row);
@@ -987,8 +1116,6 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
             // backfill for flipped-on materialization) — all inside one
             // transaction (Postgres DDL is transactional — a failed bump leaves
             // no half-state).
-            const layouts = parseLayouts(typeof marker.layouts === 'string' ? marker.layouts : undefined);
-            const retiredTables = retiredTableNames(schema, layouts);
             await this.#exec.transaction(async (client) => {
                 // RFC 0007 migration barrier: `LOCK TABLE ... EXCLUSIVE` is the FIRST
                 // statement, before any read, DDL, rewrite, marker or checkpoint
@@ -1001,6 +1128,24 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
                 // when it takes this lock, so a writer already inside completes while
                 // the migration waits.
                 await client.query('LOCK TABLE sync_partitions IN EXCLUSIVE MODE');
+                // The probe ran before the lock. A concurrent `ensureSchema` (another
+                // isolate, the Durable Object's first request) may have bumped while
+                // this one waited; re-running the rewrite would decode its new-layout
+                // payloads with the old layout. The locked marker decides.
+                const { rows: lockedMarker } = await client.query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1');
+                const lockedVersion = lockedMarker[0]?.schema_version === null ||
+                    lockedMarker[0]?.schema_version === undefined
+                    ? undefined
+                    : asNumber(lockedMarker[0].schema_version);
+                if (lockedVersion !== undefined && lockedVersion > schema.version) {
+                    throw new Error(`stored schema version ${lockedVersion} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
+                }
+                if (lockedVersion === schema.version)
+                    return;
+                const layouts = parseLayouts(typeof lockedMarker[0]?.layouts === 'string'
+                    ? lockedMarker[0].layouts
+                    : undefined);
+                const retiredTables = retiredTableNames(schema, layouts);
                 const existing = new Map();
                 const existingIndexes = new Map();
                 for (const table of schema.tables.values()) {
@@ -1047,13 +1192,15 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
                         ])));
                     }
                 }
+                if (retiredTables.length > 0) {
+                    // Neither index leads with `tbl`: one scan per table, not one per
+                    // retired table.
+                    await client.query(`DELETE FROM sync_row_scopes
+              WHERE tbl IN (SELECT jsonb_array_elements_text($1::text::jsonb))`, [JSON.stringify(retiredTables)]);
+                    await client.query(`DELETE FROM sync_blob_refs
+              WHERE tbl IN (SELECT jsonb_array_elements_text($1::text::jsonb))`, [JSON.stringify(retiredTables)]);
+                }
                 for (const tableName of retiredTables) {
-                    await client.query('DELETE FROM sync_row_scopes WHERE tbl=$1', [
-                        tableName,
-                    ]);
-                    await client.query('DELETE FROM sync_blob_refs WHERE tbl=$1', [
-                        tableName,
-                    ]);
                     await client.query(dropTableDdl(tableName));
                 }
                 for (const statement of schemaDdl(schema, existing, 'postgres', existingIndexes)) {
@@ -1496,7 +1643,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
         if (firstVariable === undefined || values.length === 0)
             return 0;
         // Concurrent reads of a pull share one statement across tables.
-        const [row] = await this.#batchedPage(LATEST_SCOPED_CHANGE_BATCH_SQL, partition, { tbl: query.table, var: firstVariable, vals: values });
+        const [row] = await this.#batchedPage('latestScopedChange', LATEST_SCOPED_CHANGE_BATCH_SQL, partition, { tbl: query.table, var: firstVariable, vals: values });
         return row === undefined ? 0 : asNumber(row.seq);
     }
     async readCommitWindow(partition, query) {
@@ -1519,7 +1666,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
         let afterSeq = query.afterSeq;
         const batchSize = Math.max(64, query.limitChanges);
         while (deliveredChanges < query.limitChanges) {
-            const records = await this.#batchedPage(COMMIT_WINDOW_BATCH_SQL, partition, {
+            const records = await this.#batchedPage('commitWindow', COMMIT_WINDOW_BATCH_SQL, partition, {
                 tbl: query.table,
                 var: firstVariable,
                 vals: firstValues,
@@ -1592,15 +1739,14 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
             return [];
         // Candidates via the inverted index (ordered + LIMITed at the covering
         // PK) LEFT JOINed to the row table — one round trip per page, never one
-        // per row, and pages of concurrent scans on the same table share one
-        // statement (see `scanRowBatchSql`). Exact multi-variable verification
-        // against the stored scope map happens below.
-        const sql = scanRowBatchSql(this.table(query.table));
+        // per row, and concurrent scans across tables share one statement (see
+        // `scanRowBatchSql`). Exact multi-variable verification against the
+        // stored scope map happens below.
         const rows = [];
         let afterRowId = query.afterRowId ?? '';
         const batchSize = Math.max(64, query.limit);
         while (rows.length < query.limit) {
-            const records = await this.#batchedPage(sql, partition, {
+            const records = await this.#batchedPage('scanRows', (specs) => scanRowBatchSql([...new Set(specs.map((spec) => String(spec.tbl)))].map((table) => this.table(table))), partition, {
                 tbl: query.table,
                 var: firstVariable,
                 vals: firstValues,

package/dist/pull.d.ts

@@ -42,8 +42,8 @@ export interface PullSectionTrace {
 /**
  * The storage reads a section needs before its first frame. A pull starts
  * them for every subscription before awaiting any, so a storage that batches
- * concurrent page reads (PostgreSQL, D1) answers all subscriptions of one
- * table with one statement, and the horizon re-check runs once per pull.
+ * concurrent page reads (PostgreSQL, D1) answers the first pages of every
+ * subscription in one statement, and the horizon re-check runs once per pull.
  */
 export interface PreparedSection {
     /** §4.5 window read for an incremental cursor; empty when none was read. */
@@ -57,7 +57,11 @@ export interface PreparedSection {
     readonly firstPage: StoredRow[] | undefined;
     /** §4.7 pin of a fresh bootstrap; absent ⇒ `maxCommitSeq`. */
     readonly pin: number | undefined;
-    /** §5.3 stored image for a sqlite-lane bootstrap's reuse key, if any. */
+    /**
+     * §5.3 stored image for a sqlite-lane bootstrap's reuse key. Read only when
+     * the eligibility probe shows a snapshot larger than one rows page, since a
+     * smaller table can never match a stored image.
+     */
     readonly image: SegmentRecord | undefined;
 }
 /** Run the pre-frame storage reads of every subscription concurrently. */

package/dist/pull.js

@@ -375,18 +375,27 @@ export async function prepareSections(ctx, schema, limits, plans, maxSeq, horizo
                 const pin = Math.min(maxSeq, Math.max(latest, horizonSeq));
                 return { asOf: pin, pin };
             });
-        const lane = pinned.then(async ({ asOf, pin }) => ({
-            pin,
-            image: await ctx.segments.find({
-                partition: ctx.partition,
-                logEpoch,
-                table: plan.table.name,
-                schemaVersion: schema.version,
-                mediaType: 'sqlite',
-                scopeDigest: await scopeDigest(plan.effective),
-                asOfCommitSeq: asOf,
-            }, clockOf(ctx)()),
-        }));
+        const lane = pinned.then(async ({ asOf, pin }) => {
+            // §5.3 eligibility: a stored image only matches a snapshot larger than
+            // one rows page, so the probe decides before the reuse lookup; a remote
+            // `find` on a small table would be a wasted round trip.
+            const probe = await firstPage;
+            if (probe.length <= limits.limitSnapshotRows) {
+                return { pin, image: undefined };
+            }
+            return {
+                pin,
+                image: await ctx.segments.find({
+                    partition: ctx.partition,
+                    logEpoch,
+                    table: plan.table.name,
+                    schemaVersion: schema.version,
+                    mediaType: 'sqlite',
+                    scopeDigest: await scopeDigest(plan.effective),
+                    asOfCommitSeq: asOf,
+                }, clockOf(ctx)()),
+            };
+        });
         return { firstPage, lane };
     });
     const settled = await Promise.all(reads.map(async (read) => ({

package/dist/relational-rows.d.ts

@@ -176,8 +176,12 @@ export declare function toSqlValue(column: RowColumn, value: RowValue, dialect:
  * statement, so they cannot drift.
  */
 export declare function upsertValues(table: CompiledTable, partition: string, row: StoredRow, dialect: RelationalDialect): unknown[];
-/** Upsert statement text (bind with `upsertValues`). */
-export declare function upsertSql(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * Upsert statement text (bind with `upsertValues`). PostgreSQL takes `rows`
+ * rows in one statement, bound as consecutive `upsertValues` lists; their
+ * row ids must be distinct.
+ */
+export declare function upsertSql(table: CompiledTable, dialect: RelationalDialect, rows?: number): string;
 /**
  * SELECT one stored row. Aliased to the legacy record shape
  * (`row_id`/`server_version`/`scopes`/`payload`) so the existing
@@ -246,17 +250,19 @@ export declare function scanRowPageSql(table: CompiledTable, valueCount: number,
 export declare function commitWindowPageSql(valueCount: number, dialect: RelationalDialect): string;
 /**
  * PostgreSQL set-based form of `scanRowPageSql`: one statement answers the
- * page of every subscription scanning `table` in a pull. `$2` is a JSON array
- * of `{i, tbl, var, vals, after, lim}` records; each record runs the same
- * index-first candidate subquery through a LATERAL join, so every
- * subscription keeps its own keyset cursor and LIMIT. Rows arrive ordered
- * by (i, row_id).
+ * page of every subscription scanning any table in a pull. `$2` is a JSON
+ * array of `{i, tbl, var, vals, after, lim}` records; each record runs the
+ * same index-first candidate subquery through a LATERAL join, so every
+ * subscription keeps its own keyset cursor and LIMIT. The candidate side is
+ * table-agnostic (a spec names its table), so the statement joins the row
+ * table once per table present in the batch through a UNION ALL branch that
+ * keeps only its own candidates. Rows arrive ordered by (i, row_id).
  *
  * Params: [partition, specs (JSON text)]. The specs bind as text before
  * the JSONB cast, so a driver that JSON-encodes a string bound to a `jsonb`
  * parameter (Bun.sql) cannot turn the array into a JSON string.
  */
-export declare function scanRowBatchSql(table: CompiledTable): string;
+export declare function scanRowBatchSql(tables: readonly CompiledTable[]): string;
 /**
  * PostgreSQL set-based form of `commitWindowPageSql`: one statement answers
  * the window page of every subscription in a pull, across all tables. `$2`
@@ -363,10 +369,10 @@ export declare function migratePayload(oldLayout: readonly StoredColumnLayout[],
  */
 export declare function selectRowsForRewriteSql(table: CompiledTable, dialect: RelationalDialect): string;
 /**
- * Rewrite one row during a migration: refresh the projection columns (when
+ * SQLite/D1: rewrite one row during a migration: refresh the projection columns (when
  * materialized) and the payload. Bind with `rewriteValues`.
  */
-export declare function rewriteRowSql(table: CompiledTable, dialect: RelationalDialect): string;
+export declare function rewriteRowSql(table: CompiledTable): string;
 /** Bind values for `rewriteRowSql` from the (already migrated) payload. */
 export declare function rewriteValues(table: CompiledTable, partition: string, rowId: string, payload: Uint8Array, dialect: RelationalDialect): unknown[];
 /**