@syncular/server 0.26.4 → 0.26.6

package/dist/content-encoding.d.ts

@@ -25,3 +25,20 @@ export interface EncodedSegmentBody {
  * tiny, or the runtime has no codec.
  */
 export declare function encodeSegmentBody(bytes: Uint8Array, acceptEncoding: string | undefined): EncodedSegmentBody;
+/**
+ * Segments above this size are relayed as a stream instead of being
+ * buffered and compressed in memory: a sqlite image can exceed the memory of
+ * a Workers isolate (128 MB).
+ */
+export declare const SEGMENT_STREAM_THRESHOLD_BYTES: number;
+export interface EncodedSegmentStream {
+    readonly body: ReadableStream<Uint8Array<ArrayBuffer>>;
+    /** Absent ⇒ identity (no `Content-Encoding` header). */
+    readonly contentEncoding?: 'gzip';
+}
+/**
+ * Compress a streamed segment body per §5.8 with the runtime's
+ * `CompressionStream`: gzip when the client accepts it, identity otherwise
+ * (zstd has no standard streaming codec).
+ */
+export declare function encodeSegmentStream(body: ReadableStream<Uint8Array<ArrayBuffer>>, acceptEncoding: string | undefined): EncodedSegmentStream;

package/dist/content-encoding.js

@@ -67,3 +67,25 @@ export function encodeSegmentBody(bytes, acceptEncoding) {
     }
     return { bytes };
 }
+/**
+ * Segments above this size are relayed as a stream instead of being
+ * buffered and compressed in memory: a sqlite image can exceed the memory of
+ * a Workers isolate (128 MB).
+ */
+export const SEGMENT_STREAM_THRESHOLD_BYTES = 16 * 1024 * 1024;
+/**
+ * Compress a streamed segment body per §5.8 with the runtime's
+ * `CompressionStream`: gzip when the client accepts it, identity otherwise
+ * (zstd has no standard streaming codec).
+ */
+export function encodeSegmentStream(body, acceptEncoding) {
+    if (acceptEncoding === undefined ||
+        !accepts(acceptEncoding, 'gzip') ||
+        typeof CompressionStream !== 'function') {
+        return { body };
+    }
+    return {
+        body: body.pipeThrough(new CompressionStream('gzip')),
+        contentEncoding: 'gzip',
+    };
+}

package/dist/context.d.ts

@@ -7,6 +7,7 @@
 import type { ScopeMap } from '@syncular/core';
 import type { BlobStore } from './blob-store.js';
 import type { CrdtMergerRegistry } from './crdt-merger.js';
+import type { SyncularErrorHandler } from './errors.js';
 import type { SyncularServerEvents } from './events.js';
 import type { LeaseStore } from './lease-store.js';
 import type { AnyReactionPlanner } from './reactions.js';
@@ -167,6 +168,14 @@ export interface SyncServerConfig {
      * event objects are built. A throwing sink never affects processing.
      */
     readonly events?: SyncularServerEvents;
+    /**
+     * Host error reporting (§10.2 `sync.internal_error`). Receives the original
+     * exception whenever a request, socket round, segment or blob download,
+     * or remote operation fails with something other than a `SyncError`; the
+     * client sees only the catalog code. Like the events sink, a throwing
+     * handler never changes the response.
+     */
+    readonly onError?: SyncularErrorHandler;
 }
 /** Per-request context: the config plus host-authenticated identity. */
 export interface SyncRequestContext extends SyncServerConfig {

package/dist/d1-storage.d.ts

@@ -1,4 +1,46 @@
 import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
+/**
+ * Cloudflare D1 server storage for Workers deployments.
+ *
+ * D1 *is* SQLite exposed over an async, statement-at-a-time API
+ * (`prepare(sql).bind(...).all()` / `.first()` / `.run()`, plus `batch([…])`
+ * for atomic multi-statement writes). So this storage shares the schema and
+ * value codecs with `SqliteServerStorage` via `sqlite-dialect.ts` — same
+ * DDL, same `?` placeholders, same JSON-scope / base64-push-result
+ * serialization — and differs only in the execution shape (async, no
+ * interactive transaction).
+ *
+ * ## Transaction model (the one real divergence)
+ *
+ * D1 has **no interactive transaction**: you cannot `BEGIN`, run
+ * conditional reads and writes on a pinned connection, then `COMMIT`. The
+ * only atomic primitive is `db.batch([stmt, …])` — a set of statements
+ * applied in one implicit transaction, all-or-nothing.
+ *
+ * The push handler (§6) reads first (conflict detection via `getRow`) and
+ * only then writes (`upsertRow`/`deleteRow`/`appendCommit`/
+ * `putPushResult`). `D1Transaction` exploits exactly that ordering:
+ *
+ *   - reads (`getRow`) execute immediately against D1 (autocommit);
+ *   - writes are **buffered** as prepared statements;
+ *   - `commit()` flushes the whole buffer as one `db.batch(...)` — the same
+ *     atomicity §6.4 requires (a rejected op rolls back by simply never
+ *     flushing);
+ *   - `rollback()` drops the buffer unsent.
+ *
+ * `appendCommit` allocates the dense per-partition `commitSeq` (§2.1) by
+ * reading `max_commit_seq` live and buffering the `+1` write. Under a single
+ * Worker request this is exact. Two concurrent pushes to one partition need an
+ * external serialization point (normally a per-partition Durable Object); a
+ * realtime notifier alone does not serialize HTTP writes. Every deployment
+ * that accepts D1 pushes MUST front same-partition sync rounds with a
+ * coordinating primitive (a DO or a Queue). The adapter fails closed unless
+ * that coordinator explicitly sets `pushApplySerialized`, because D1 cannot
+ * provide the required pre-operation lock.
+ * This mirrors PostgreSQL's per-partition row lock, achieved by placement
+ * rather than a lock D1 does not expose.
+ */
+import { type ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export interface D1PreparedStatement {
@@ -73,6 +115,10 @@ export declare class D1ServerStorage implements ServerStorage {
     getReaction(partition: string, idempotencyKey: string): Promise<StoredReaction | undefined>;
     listReactions(partition: string, query: ReactionListQuery): Promise<StoredReaction[]>;
     pruneReactions(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
+    latestScopedChangeSeq(partition: string, query: {
+        readonly table: string;
+        readonly scopeFilter: ScopeMap;
+    }): Promise<number>;
     readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;

package/dist/d1-storage.js

@@ -45,7 +45,7 @@ import { StorageQueryError } from './storage-errors.js';
 import { decodeRow } from '@syncular/core';
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, serializePushResult, sqliteDdlStatements, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
@@ -1439,6 +1439,17 @@ export class D1ServerStorage {
             deadLetter: results.filter((row) => row.status === 'dead-letter').length,
         };
     }
+    async latestScopedChangeSeq(partition, query) {
+        const firstVariable = Object.keys(query.scopeFilter).sort()[0];
+        const values = firstVariable === undefined
+            ? []
+            : (query.scopeFilter[firstVariable] ?? []);
+        if (firstVariable === undefined || values.length === 0)
+            return 0;
+        // Concurrent reads of a pull share one `db.batch` round trip.
+        const [row] = await this.#batchedAll(latestScopedChangeSeqSql(values.length), values.flatMap((value) => [partition, query.table, firstVariable, value]));
+        return row?.seq ?? 0;
+    }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];

package/dist/errors.d.ts

@@ -34,3 +34,22 @@ export declare function errorBody(error: SyncError): {
     message: string;
     details?: unknown;
 };
+/** The adapter surface that caught an exception reported through `onError`. */
+export type SyncularErrorRoute = 'sync' | 'operations' | 'segments' | 'blobs' | 'admin' | 'realtime';
+/**
+ * Host error reporting: receives every exception that is not a `SyncError`
+ * before the adapter answers `sync.internal_error` (or the remote-operation
+ * `operation.*` failure code), with the surface that caught it.
+ */
+export type SyncularErrorHandler = (error: unknown, context: {
+    readonly route: SyncularErrorRoute;
+}) => void;
+/**
+ * The protocol error for an exception an adapter caught. A `SyncError`
+ * passes through unchanged. Anything else goes to `onError` and becomes
+ * `sync.internal_error` (§10.2), whose message never carries the exception
+ * text.
+ */
+export declare function adapterSyncError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute): SyncError;
+/** Hand `error` to the host's `onError`; a throwing handler is contained. */
+export declare function reportError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute): void;

package/dist/errors.js

@@ -163,6 +163,14 @@ export const ERROR_CATALOG = {
     // checkpoint is incomplete or the database is newer than the running build.
     // Formerly host-only; promoted to the §10.2 catalogue so an in-flight
     // request can be refused with a distinguishable identity.
+    // An exception outside this catalog (host code, storage, network) reached
+    // an adapter; the original goes to `onError`, never onto the wire.
+    'sync.internal_error': {
+        category: 'internal',
+        retryable: true,
+        recommendedAction: 'retryLater',
+        httpStatus: 500,
+    },
     'sync.schema_not_ready': {
         category: 'internal',
         retryable: true,
@@ -288,3 +296,24 @@ export function errorBody(error) {
             : {}),
     };
 }
+/**
+ * The protocol error for an exception an adapter caught. A `SyncError`
+ * passes through unchanged. Anything else goes to `onError` and becomes
+ * `sync.internal_error` (§10.2), whose message never carries the exception
+ * text.
+ */
+export function adapterSyncError(error, onError, route) {
+    if (error instanceof SyncError)
+        return error;
+    reportError(error, onError, route);
+    return new SyncError('sync.internal_error', 'internal server error');
+}
+/** Hand `error` to the host's `onError`; a throwing handler is contained. */
+export function reportError(error, onError, route) {
+    try {
+        onError?.(error, { route });
+    }
+    catch {
+        // The report is best effort; the response stays the catalog error.
+    }
+}

package/dist/handler.js

@@ -353,7 +353,7 @@ async function* streamResponse(plan, ctx, schema, report) {
             const limits = clampPullLimits(plan.pull);
             const maxSeq = await ctx.storage.getMaxCommitSeq(ctx.partition);
             const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
-            const prepared = await prepareSections(ctx, limits, plan.subscriptions, maxSeq, horizonSeq);
+            const prepared = await prepareSections(ctx, schema, limits, plan.subscriptions, maxSeq, horizonSeq, plan.logEpoch);
             for (const [index, subscription] of plan.subscriptions.entries()) {
                 const trace = summaries !== undefined ? { segments: [] } : undefined;
                 const reads = prepared[index];

package/dist/index.d.ts

@@ -44,7 +44,7 @@ export * from './segment-store.js';
 export * from './signed-url.js';
 export * from './sqlite-dialect.js';
 export * from './sqlite-driver.js';
-export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, type SqliteImageBuilder, type SqliteImageInput, } from './sqlite-image.js';
+export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, type SqliteImageBuilder, type SqliteImageInput, writeSqliteImage, } from './sqlite-image.js';
 export * from './sqlite-blob-store.js';
 export * from './sqlite-lease-store.js';
 export * from './sqlite-segment-store.js';

package/dist/index.js

@@ -48,7 +48,7 @@ export * from './segment-store.js';
 export * from './signed-url.js';
 export * from './sqlite-dialect.js';
 export * from './sqlite-driver.js';
-export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, } from './sqlite-image.js';
+export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, writeSqliteImage, } from './sqlite-image.js';
 export * from './sqlite-blob-store.js';
 export * from './sqlite-lease-store.js';
 export * from './sqlite-segment-store.js';

package/dist/operations-realtime.js

@@ -1,6 +1,6 @@
 import { decodeRemoteOperationRealtimeMessage, encodeRemoteOperationRealtimeMessage, } from '@syncular/core';
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX } from './context.js';
-import { SyncError, syncError } from './errors.js';
+import { reportError, SyncError, syncError } from './errors.js';
 class WatchSession {
     #ctx;
     #registry;
@@ -122,6 +122,9 @@ class WatchSession {
                     if (this.#isClosed || this.#watches.get(state.watchId) !== state) {
                         return;
                     }
+                    if (!(error instanceof SyncError)) {
+                        reportError(error, this.#ctx.onError, 'operations');
+                    }
                     this.#sendError(state.watchId, error instanceof SyncError
                         ? error
                         : syncError('operation.query_failed'));

package/dist/operations.js

@@ -1,7 +1,7 @@
 import { validateAuthoritativeRelationPlan, } from './authoritative-query.js';
 import { decodeRow, decodeRemoteOperationRequest, encodeRemoteOperationResponse, encodeSparseRow, } from '@syncular/core';
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
-import { SyncError, syncError } from './errors.js';
+import { reportError, SyncError, syncError } from './errors.js';
 import { processPushOperationsWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
 import { authorizeWrite } from './scopes.js';
@@ -206,6 +206,7 @@ export function registerRemoteQuery(descriptor, options) {
             catch (error) {
                 if (error instanceof SyncError)
                     throw error;
+                reportError(error, ctx.onError, 'operations');
                 throw syncError('operation.query_failed', 'registered query execution failed');
             }
             if (result.rows.length > options.maxRows) {
@@ -218,6 +219,7 @@ export function registerRemoteQuery(descriptor, options) {
             catch (error) {
                 if (error instanceof SyncError)
                     throw error;
+                reportError(error, ctx.onError, 'operations');
                 throw syncError('operation.query_failed', 'registered query result decoding failed');
             }
             return {
@@ -409,6 +411,9 @@ export async function handleRemoteOperation(bytes, ctx, registry) {
         return encodeRemoteOperationResponse(await operation.run(ctx, request.clientId, request.requestId, request.params));
     }
     catch (error) {
+        if (!(error instanceof SyncError)) {
+            reportError(error, ctx.onError, 'operations');
+        }
         return encodeRemoteOperationError(error, 'operation.execution_failed');
     }
 }

package/dist/postgres-storage.d.ts

@@ -1,4 +1,42 @@
 import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
+/**
+ * Postgres server storage: the production database path.
+ *
+ * Semantics mirror `SqliteServerStorage` exactly (both run the shared
+ * storage contract in `test/storage-contract.ts`); the difference is that
+ * scope fanout MUST survive contact with Postgres — no scan-before-LIMIT,
+ * ever (performance-by-construction):
+ *
+ *   - both the commit log and the current-row table carry a (table, var,
+ *     value) inverted scope index;
+ *   - `readCommitWindow`/`scanRows` select candidates through that index
+ *     (`sync_change_scopes` / `sync_row_scopes`), ordered + LIMITed at the
+ *     index, then verify the full multi-variable match against the stored
+ *     scope map — never a log or table scan;
+ *   - the candidate indexes are *covering* for their selection: the ordered
+ *     column (`commit_seq` / `row_id`) sits in the index key after
+ *     (tbl, var, value), so the planner does an index range scan and returns
+ *     already-ordered candidates without a heap sort. `test/postgres-explain
+ *     .test.ts` asserts an `Index` node (never `Seq Scan`) so the regression
+ *     cannot silently return.
+ *
+ * Storage is written against the `PgExecutor` seam (zero runtime deps); the
+ * production driver (Bun.sql / node-postgres) and the test driver (pglite)
+ * are wired by the host. See `pg-executor.ts` and the server README.
+ *
+ * ## commitSeq allocation under concurrency
+ *
+ * Per-partition `commitSeq` is a dense, gap-free counter (§2.1), allocated
+ * inside the push transaction by `UPDATE sync_partitions SET
+ * max_commit_seq = max_commit_seq + 1 … RETURNING`. The `UPDATE` takes a
+ * row-level write lock on the partition row for the duration of the
+ * transaction, so two concurrent pushes to the same partition serialize on
+ * that row: the second blocks until the first commits, then reads the
+ * advanced counter. This keeps the sequence dense (a Postgres `SEQUENCE`
+ * would leave gaps on rollback, which the pull-window arithmetic in §4.5
+ * does not tolerate). Cross-partition pushes never contend.
+ */
+import type { ScopeMap } from '@syncular/core';
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
@@ -77,6 +115,10 @@ export declare class PostgresServerStorage implements ServerStorage {
     getReaction(partition: string, idempotencyKey: string): Promise<StoredReaction | undefined>;
     listReactions(partition: string, query: ReactionListQuery): Promise<StoredReaction[]>;
     pruneReactions(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
+    latestScopedChangeSeq(partition: string, query: {
+        readonly table: string;
+        readonly scopeFilter: ScopeMap;
+    }): Promise<number>;
     readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;

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, LATEST_SCOPED_CHANGE_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) {
@@ -1348,6 +1402,17 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
             deadLetter: rows.filter((row) => row.status === 'dead-letter').length,
         };
     }
+    async latestScopedChangeSeq(partition, query) {
+        const firstVariable = Object.keys(query.scopeFilter).sort()[0];
+        const values = firstVariable === undefined
+            ? []
+            : (query.scopeFilter[firstVariable] ?? []);
+        if (firstVariable === undefined || values.length === 0)
+            return 0;
+        // Concurrent reads of one table in a pull share one statement.
+        const [row] = await this.#batchedPage(LATEST_SCOPED_CHANGE_BATCH_SQL, partition, query.table, { var: firstVariable, vals: values });
+        return row === undefined ? 0 : asNumber(row.seq);
+    }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];