@syncular/server 0.42.2 → 0.44.0

package/dist/push.d.ts

@@ -28,6 +28,20 @@ import type { StorageTransaction, StoredCommit } from './storage.js';
  * row-codec decode (§5.9.1), so `parseBlobRef` here is total.
  */
 export declare function blobIdsInRow(table: CompiledTable, values: readonly RowValue[]): string[];
+/**
+ * A server-authoritative scope move (§2.2). Commands emit it through
+ * `CommandMutation`; it is not an SSP2 wire operation, so a client cannot
+ * request one. Apply rewrites the stored row in place under the new scopes
+ * and emits the delete/upsert change pair in one commit.
+ */
+export interface RescopeOperation {
+    readonly table: string;
+    readonly rowId: string;
+    readonly op: 'rescope';
+    /** Full-row payload (the row's values under the new scopes). */
+    readonly payload: Uint8Array;
+}
+export type ApplyOperation = PushOperation | RescopeOperation;
 export interface ProcessedPushCommit {
     readonly frame: PushResultFrame;
     /** True when this request observed an already-recorded idempotency outcome. */
@@ -54,4 +68,7 @@ export declare function processPushCommitWithTrace(ctx: SyncRequestContext, sche
  * The builder runs after the partition lock and idempotency re-check, so its
  * reads and the returned operations share the transaction that is committed.
  */
-export declare function processPushOperationsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, clientCommitId: string, buildOperations: (tx: StorageTransaction) => Promise<readonly PushOperation[]>, wireSchema?: CompiledSchema): Promise<ProcessedPushCommit>;
+export declare function processPushOperationsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, clientCommitId: string, buildOperations: (tx: StorageTransaction) => Promise<readonly ApplyOperation[]>, wireSchema?: CompiledSchema, prefetchTargets?: readonly {
+    readonly table: string;
+    readonly rowIds: readonly string[];
+}[]): Promise<ProcessedPushCommit>;

package/dist/push.js

@@ -172,20 +172,149 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
         return errorRecord(opIndex, 'sync.forbidden', 'scope resolution failed (§3.4 step 4)');
     }
     const stored = await tx.getRow(op.table, op.rowId);
-    if (op.op === 'delete') {
+    if (op.op === 'rescope') {
+        // §2.2 explicit scope move. One stored row changes its scope values;
+        // apply rewrites it in place, keeps `server_version`, and emits the
+        // delete under the old scopes plus the upsert under the new ones.
         if (stored === undefined) {
-            // Deleting an absent row is applied (idempotent, §6.2); no change.
-            return {
-                kind: 'applied',
-                change: undefined,
-                operation: {
+            return errorRecord(opIndex, 'sync.row_missing', 'rescope targets an absent row (§2.2)');
+        }
+        if (!authorizeWrite(table, stored.scopes, resolved)) {
+            return errorRecord(opIndex, 'sync.forbidden', 'rescope denied by scope authorization (§3.4)');
+        }
+        const missing = missingScopeVariable(table, stored.scopes);
+        if (missing !== undefined) {
+            return errorRecord(opIndex, 'sync.missing_scopes', `stored row lacks scope variable ${JSON.stringify(missing)} (§3.1)`);
+        }
+        let sparse;
+        try {
+            sparse = decodeSparseRow(wireTable.columns, wireTable.primaryKeyIndex, op.payload);
+        }
+        catch (error) {
+            return errorRecord(opIndex, 'sync.invalid_request', `rescope payload failed row-codec decode (§1.7): ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (sparse.length < table.columns.length ||
+            sparse.some((value) => value === undefined)) {
+            return errorRecord(opIndex, 'sync.invalid_request', 'rescope requires a full-row payload (§2.2)');
+        }
+        const values = sparse.map((value) => value ?? null);
+        const pkValue = renderScopeValue(values[table.primaryKeyIndex] ?? null);
+        if (pkValue !== op.rowId) {
+            return errorRecord(opIndex, 'sync.invalid_request', 'payload primary key does not match rowId');
+        }
+        const storedValues = decodeRow(table.columns, stored.payload);
+        const scopeIndexes = new Set(table.scopePatterns.map((pattern) => pattern.columnIndex));
+        const sameValue = (left, right) => {
+            if (left instanceof Uint8Array || right instanceof Uint8Array) {
+                return (left instanceof Uint8Array &&
+                    right instanceof Uint8Array &&
+                    left.length === right.length &&
+                    left.every((byte, index) => byte === right[index]));
+            }
+            return left === right;
+        };
+        for (let index = 0; index < table.columns.length; index++) {
+            if (index === table.primaryKeyIndex || scopeIndexes.has(index))
+                continue;
+            if (!sameValue(values[index] ?? null, storedValues[index] ?? null)) {
+                return errorRecord(opIndex, 'sync.invalid_request', 'rescope may change only scope columns (§2.2)');
+            }
+        }
+        const extracted = storedScopesForRow(table, values);
+        if ('missing' in extracted) {
+            return errorRecord(opIndex, 'sync.forbidden', `rescope missing scope column value for ${JSON.stringify(extracted.missing)} (§3.4)`);
+        }
+        if (!authorizeWrite(table, extracted.scopes, resolved)) {
+            return errorRecord(opIndex, 'sync.forbidden', 'rescope denied by scope authorization of the new scopes (§3.4)');
+        }
+        const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, tx, partition, actorId);
+        if (deleteReject !== undefined)
+            return deleteReject;
+        const upsertReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, tx, partition, actorId);
+        if (upsertReject !== undefined)
+            return upsertReject;
+        const blobCheck = await checkAndRecordBlobs(tx, table, op.rowId, values, opIndex, blobCtx);
+        if (blobCheck !== undefined)
+            return blobCheck;
+        const payload = encodeRow(table.columns, values);
+        // The move clears any tombstone from an earlier incarnation: the row is
+        // live at the end of this commit, so the next move must not hit §5.2.
+        await tx.clearTombstone(op.table, op.rowId);
+        await tx.upsertRow(op.table, {
+            rowId: op.rowId,
+            serverVersion: stored.serverVersion,
+            scopes: extracted.scopes,
+            payload,
+            ...(stored.columnVersions !== undefined
+                ? { columnVersions: stored.columnVersions }
+                : {}),
+        }, { opIndex });
+        const storedRow = toValidateRow(table.columns, storedValues);
+        return {
+            kind: 'applied',
+            changes: [
+                {
+                    table: op.table,
+                    rowId: op.rowId,
+                    op: 'delete',
+                    scopes: stored.scopes,
+                },
+                {
+                    table: op.table,
+                    rowId: op.rowId,
+                    op: 'upsert',
+                    rowVersion: stored.serverVersion,
+                    scopes: extracted.scopes,
+                    payload,
+                },
+            ],
+            operations: [
+                {
                     opIndex,
                     op: 'delete',
                     table: table.name,
                     rowId: op.rowId,
                     row: undefined,
-                    stored: undefined,
+                    stored: storedRow,
+                    storedServerVersion: stored.serverVersion,
+                },
+                {
+                    opIndex,
+                    op: 'upsert',
+                    table: table.name,
+                    rowId: op.rowId,
+                    row: toValidateRow(table.columns, values),
+                    stored: storedRow,
+                    storedServerVersion: stored.serverVersion,
+                    nextServerVersion: stored.serverVersion,
                 },
+            ],
+            staged: {
+                table,
+                op: 'upsert',
+                rowId: op.rowId,
+                opIndex,
+                values,
+                stored,
+            },
+        };
+    }
+    if (op.op === 'delete') {
+        if (stored === undefined) {
+            // Deleting an absent row is applied (idempotent, §6.2); no change.
+            return {
+                kind: 'applied',
+                changes: [],
+                operations: [
+                    {
+                        opIndex,
+                        op: 'delete',
+                        table: table.name,
+                        rowId: op.rowId,
+                        row: undefined,
+                        stored: undefined,
+                    },
+                ],
                 staged: {
                     table,
                     op: 'delete',
@@ -212,21 +341,25 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
         await tx.deleteRow(op.table, op.rowId);
         return {
             kind: 'applied',
-            change: {
-                table: op.table,
-                rowId: op.rowId,
-                op: 'delete',
-                scopes: stored.scopes,
-            },
-            operation: {
-                opIndex,
-                op: 'delete',
-                table: table.name,
-                rowId: op.rowId,
-                row: undefined,
-                stored: toValidateRow(table.columns, storedValues),
-                storedServerVersion: stored.serverVersion,
-            },
+            changes: [
+                {
+                    table: op.table,
+                    rowId: op.rowId,
+                    op: 'delete',
+                    scopes: stored.scopes,
+                },
+            ],
+            operations: [
+                {
+                    opIndex,
+                    op: 'delete',
+                    table: table.name,
+                    rowId: op.rowId,
+                    row: undefined,
+                    stored: toValidateRow(table.columns, storedValues),
+                    storedServerVersion: stored.serverVersion,
+                },
+            ],
             staged: { table, op: 'delete', rowId: op.rowId, opIndex, stored },
         };
     }
@@ -354,24 +487,28 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
         await tx.upsertRow(op.table, newRow, { opIndex });
         return {
             kind: 'applied',
-            change: {
-                table: op.table,
-                rowId: op.rowId,
-                op: 'upsert',
-                rowVersion: newVersion,
-                scopes: stored.scopes,
-                payload: newPayload,
-            },
-            operation: {
-                opIndex,
-                op: 'upsert',
-                table: table.name,
-                rowId: op.rowId,
-                row: toValidateRow(table.columns, values),
-                stored: toValidateRow(table.columns, storedValues),
-                storedServerVersion: stored.serverVersion,
-                nextServerVersion: newVersion,
-            },
+            changes: [
+                {
+                    table: op.table,
+                    rowId: op.rowId,
+                    op: 'upsert',
+                    rowVersion: newVersion,
+                    scopes: stored.scopes,
+                    payload: newPayload,
+                },
+            ],
+            operations: [
+                {
+                    opIndex,
+                    op: 'upsert',
+                    table: table.name,
+                    rowId: op.rowId,
+                    row: toValidateRow(table.columns, values),
+                    stored: toValidateRow(table.columns, storedValues),
+                    storedServerVersion: stored.serverVersion,
+                    nextServerVersion: newVersion,
+                },
+            ],
             staged: { table, op: 'upsert', rowId: op.rowId, opIndex, values, stored },
         };
     }
@@ -440,23 +577,27 @@ async function applyOperation(tx, schema, wireSchema, resolved, op, opIndex, blo
     await tx.upsertRow(op.table, newRow, { opIndex });
     return {
         kind: 'applied',
-        change: {
-            table: op.table,
-            rowId: op.rowId,
-            op: 'upsert',
-            rowVersion: 1,
-            scopes: extracted.scopes,
-            payload: insertPayload,
-        },
-        operation: {
-            opIndex,
-            op: 'upsert',
-            table: table.name,
-            rowId: op.rowId,
-            row: toValidateRow(table.columns, values),
-            stored: undefined,
-            nextServerVersion: 1,
-        },
+        changes: [
+            {
+                table: op.table,
+                rowId: op.rowId,
+                op: 'upsert',
+                rowVersion: 1,
+                scopes: extracted.scopes,
+                payload: insertPayload,
+            },
+        ],
+        operations: [
+            {
+                opIndex,
+                op: 'upsert',
+                table: table.name,
+                rowId: op.rowId,
+                row: toValidateRow(table.columns, values),
+                stored: undefined,
+                nextServerVersion: 1,
+            },
+        ],
         staged: {
             table,
             op: 'upsert',
@@ -856,80 +997,54 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
  * cache provenance needed by structured events and server helpers.
  */
 export async function processPushCommitWithTrace(ctx, schema, resolved, clientId, frame, wireSchema = schema) {
-    return processPushOperationsWithTrace(ctx, schema, resolved, clientId, frame.clientCommitId, async () => frame.operations, wireSchema);
+    // The frame names its rows before the transaction opens, so the admission
+    // read carries the commit's read-ahead and the apply issues no separate
+    // prefetch statement.
+    const targets = new Map();
+    for (const op of frame.operations) {
+        if (!schema.tables.has(op.table))
+            continue;
+        const ids = targets.get(op.table) ?? [];
+        ids.push(op.rowId);
+        targets.set(op.table, ids);
+    }
+    return processPushOperationsWithTrace(ctx, schema, resolved, clientId, frame.clientCommitId, async () => frame.operations, wireSchema, targets.size === 0
+        ? undefined
+        : [...targets].map(([table, rowIds]) => ({ table, rowIds })));
 }
 /**
  * Shared serialized apply path for SSP2 commits and authoritative commands.
  * The builder runs after the partition lock and idempotency re-check, so its
  * reads and the returned operations share the transaction that is committed.
  */
-export async function processPushOperationsWithTrace(ctx, schema, resolved, clientId, clientCommitId, buildOperations, wireSchema = schema) {
-    const { storage, partition } = ctx;
-    let persisted;
-    try {
-        persisted = await storage.getPushResult(partition, clientId, clientCommitId);
-    }
-    catch (error) {
-        if (error instanceof SyncError &&
-            error.code === 'sync.idempotency_cache_miss') {
-            // §6.3: answer the retryable cache-miss for this commit rather than
-            // re-applying. Not persisted — a retry may find a readable record.
-            return {
-                frame: idempotencyCacheMissFrame(clientCommitId, error),
-                replayed: false,
-            };
-        }
-        throw error;
-    }
-    if (persisted !== undefined) {
-        return processedPushCommit(clientCommitId, persisted, true);
-    }
+export async function processPushOperationsWithTrace(ctx, schema, resolved, clientId, clientCommitId, buildOperations, wireSchema = schema, prefetchTargets) {
+    const { partition } = ctx;
     const createdAtMs = clockOf(ctx)();
     const blobCtx = { store: ctx.blobs, partition };
     const crdtMergers = ctx.crdtMergers;
     const validators = ctx.validators;
     const commitValidator = ctx.commitValidator;
     const reactionPlanner = ctx.reactionPlanner;
-    const tx = await storage.begin(partition);
-    const lockPartitionForPush = tx.lockPartitionForPush?.bind(tx) ??
-        tx.lockPartitionForCommitValidation?.bind(tx);
-    const commitRejectedPushResult = tx.commitRejectedPushResult?.bind(tx);
+    const tx = await ctx.storage.begin(partition);
     try {
-        if (lockPartitionForPush === undefined ||
-            commitRejectedPushResult === undefined ||
-            (reactionPlanner !== undefined && tx.enqueueReactions === undefined)) {
-            throw new Error('storage transaction does not support serialized push apply, atomic rejection finalization, and configured durable reactions');
+        if (reactionPlanner !== undefined && tx.enqueueReactions === undefined) {
+            throw new Error('storage transaction does not support configured durable reactions');
         }
-        await lockPartitionForPush();
-        // RFC 0007: evaluate the gate on this transaction's own connection while
-        // the partition lock is held, so the migration check and the write share
-        // one transaction and no migration can interleave in between.
-        const gate = await tx.readServeGate(schema.version);
-        const refusal = serveGateRefusal(gate, schema.version, ctx.checkpoints);
-        if (refusal !== undefined) {
-            await tx.rollback();
-            throw serveNotReadyError(refusal);
-        }
-        // The optimistic lookup above may have raced another delivery. Re-check
-        // only after acquiring partition serialization and before any operation
-        // read, validation, merge, or staged write. The re-check runs on the
-        // transaction's own connection when the backend provides one: a pooled
-        // Postgres client holding the partition lock would otherwise wait for a
-        // second pool slot and deadlock against pushes waiting on the lock. A
-        // racing duplicate's result commits before the lock releases, so the
-        // transaction-scoped read observes it.
+        // The storage takes the partition lock and then reads the admission token
+        // on the transaction's own connection: the RFC 0007 serve gate and the
+        // §2.3 idempotency record, plus any read-ahead the caller already knows.
+        // A racing duplicate's result commits before the lock releases, so the
+        // later read is exact and a duplicate never reruns an operation,
+        // validator, or merge.
+        let prepared;
         try {
-            const serializedPersisted = tx.getPushResult !== undefined
-                ? await tx.getPushResult(clientId, clientCommitId)
-                : await storage.getPushResult(partition, clientId, clientCommitId);
-            if (serializedPersisted !== undefined) {
-                await tx.rollback();
-                return processedPushCommit(clientCommitId, serializedPersisted, true);
-            }
+            prepared = await tx.preparePushApply(clientId, clientCommitId, schema.version, prefetchTargets);
         }
         catch (error) {
             if (error instanceof SyncError &&
                 error.code === 'sync.idempotency_cache_miss') {
+                // §6.3: answer the retryable cache-miss for this commit rather than
+                // re-applying. Not persisted — a retry may find a readable record.
                 await tx.rollback();
                 return {
                     frame: idempotencyCacheMissFrame(clientCommitId, error),
@@ -938,6 +1053,18 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
             }
             throw error;
         }
+        // RFC 0007: the gate is evaluated while the partition lock is held, so
+        // the migration check and the write share one transaction and no
+        // migration can interleave in between.
+        const refusal = serveGateRefusal(prepared.gate, schema.version, ctx.checkpoints);
+        if (refusal !== undefined) {
+            await tx.rollback();
+            throw serveNotReadyError(refusal);
+        }
+        if (prepared.persisted !== undefined) {
+            await tx.rollback();
+            return processedPushCommit(clientCommitId, prepared.persisted, true);
+        }
         const results = [];
         const changes = [];
         const validatedOperations = [];
@@ -953,8 +1080,8 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
                 ids.push(op.rowId);
                 targets.set(op.table, ids);
             }
-            for (const [table, rowIds] of targets) {
-                await tx.prefetchRows(table, rowIds);
+            if (targets.size > 0) {
+                await tx.prefetchRows([...targets].map(([table, rowIds]) => ({ table, rowIds })));
             }
         }
         for (let opIndex = 0; opIndex < operations.length; opIndex++) {
@@ -967,10 +1094,9 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
                 break;
             }
             results.push({ opIndex, status: 'applied' });
-            validatedOperations.push(outcome.operation);
+            validatedOperations.push(...outcome.operations);
             stagedWrites.push(outcome.staged);
-            if (outcome.change !== undefined)
-                changes.push(outcome.change);
+            changes.push(...outcome.changes);
         }
         // §6.11: reference enforcement runs after every client operation is
         // staged (so the candidate state is final for the client's own writes)
@@ -1021,12 +1147,9 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
                 results: [terminated],
             });
             // Discard candidates and persist the rejection while retaining the same
-            // partition lock. There is no unlock gap in which a duplicate can rerun.
-            await commitRejectedPushResult(clientId, clientCommitId, stored);
-            const canonical = await storage.getPushResult(partition, clientId, clientCommitId);
-            if (canonical === undefined) {
-                throw new Error('push rejection finalization did not persist an outcome');
-            }
+            // partition lock. There is no unlock gap in which a duplicate can rerun,
+            // and the finalization returns the canonical outcome it persisted.
+            const canonical = await tx.commitRejectedPushResult(clientId, clientCommitId, stored);
             return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
         }
         const commitSeq = await tx.appendCommit({
@@ -1104,16 +1227,8 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
                     },
                 ],
             });
-            if (commitRejectedPushResult === undefined) {
-                await tx.rollback();
-                throw new Error('storage transaction lost atomic push rejection finalization support');
-            }
             try {
-                await commitRejectedPushResult(clientId, clientCommitId, stored);
-                const canonical = await storage.getPushResult(partition, clientId, clientCommitId);
-                if (canonical === undefined) {
-                    throw new Error('push rejection finalization did not persist an outcome');
-                }
+                const canonical = await tx.commitRejectedPushResult(clientId, clientCommitId, stored);
                 return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
             }
             catch (finalizationError) {

package/dist/relational-rows.d.ts

@@ -275,11 +275,15 @@ export declare function scanRowBatchSql(tables: readonly CompiledTable[]): strin
  */
 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, tbl text, 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=s.tbl 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=s.tbl\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;
+ * PostgreSQL push read-ahead across every table a commit targets, in one
+ * statement: each requested row id with its stored row (NULL columns when
+ * absent, `selectRowSql` shape) and its §5 delete tombstone. Params:
+ * [partition, specs as JSON text], `specs` = `{tbl, ids: string[]}` records.
+ */
+export declare function prefetchRowsBatchSql(tables: readonly CompiledTable[], params?: {
+    readonly partition: string;
+    readonly specs: string;
+}): string;
 /**
  * SQLite/D1: the newest `commit_seq` in the inverted change-scope index for
  * one variable's values, as one index-only max per value (a `(partition,

package/dist/relational-rows.js

@@ -667,17 +667,35 @@ 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=s.tbl
      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`;
+ * PostgreSQL push read-ahead across every table a commit targets, in one
+ * statement: each requested row id with its stored row (NULL columns when
+ * absent, `selectRowSql` shape) and its §5 delete tombstone. Params:
+ * [partition, specs as JSON text], `specs` = `{tbl, ids: string[]}` records.
+ */
+export function prefetchRowsBatchSql(tables, params = {
+    partition: '$1',
+    specs: '$2',
+}) {
+    // One branch per table: a lateral join cannot switch its relation per
+    // record, and the union keeps the whole read-ahead one round trip.
+    const projection = tables
+        .map((table) => {
+        const quoted = quoteIdent(table.name);
+        return `SELECT ids.tbl AS tbl, 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 ids
+       LEFT JOIN ${quoted} r
+         ON r.${quoteIdent(SYNC_PARTITION_COLUMN)}=${params.partition} AND r.${quoteIdent(SYNC_ROW_ID_COLUMN)}=ids.id
+       LEFT JOIN sync_tombstones t
+         ON t.partition=${params.partition} AND t.tbl=ids.tbl AND t.row_id=ids.id
+      WHERE ids.tbl='${table.name.replaceAll("'", "''")}'`;
+    })
+        .join('\n     UNION ALL ');
+    return `WITH ids AS (
+       SELECT spec.tbl AS tbl, entry.id AS id
+         FROM jsonb_to_recordset(${params.specs}::text::jsonb) AS spec(tbl text, ids jsonb)
+         CROSS JOIN LATERAL jsonb_array_elements_text(spec.ids) AS entry(id)
+     )
+     ${projection}`;
 }
 /**
  * SQLite/D1: the newest `commit_seq` in the inverted change-scope index for

package/dist/sqlite-storage.js

@@ -1,7 +1,7 @@
 import { retainRollbackFailure, rollbackAfterError } from './storage-errors.js';
 import { validateCommitPruneQuery } from './prune.js';
 import { StorageQueryError } from './storage-errors.js';
-import { clientRoundState, PARTITION_TOUCH_INTERVAL_MS, serveGateRefusal, } from './storage.js';
+import { clientRoundState, PARTITION_TOUCH_INTERVAL_MS, rowsLiveAfterDelete, serveGateRefusal, } from './storage.js';
 import { serveNotReadyError } from './readiness.js';
 /**
  * SQLite server storage over the shared synchronous driver.
@@ -93,12 +93,6 @@ class SqliteTransaction {
             .query('DELETE FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?')
             .run(this.#partition, table, rowId);
     }
-    getPushResult(clientId, clientCommitId) {
-        this.#assertOpen();
-        // One shared SQLite connection: this read runs inside this
-        // transaction's BEGIN IMMEDIATE.
-        return this.#storage.getPushResult(this.#partition, clientId, clientCommitId);
-    }
     scanRows(query) {
         this.#assertOpen();
         return this.#storage.scanRows(this.#partition, query);
@@ -113,11 +107,15 @@ class SqliteTransaction {
         // BEGIN IMMEDIATE and observes every row staged so far.
         return this.#storage.runAuthoritativeQuery(this.#partition, query);
     }
-    async lockPartitionForPush() {
+    async preparePushApply(clientId, clientCommitId, runningSchemaVersion, _targets = []) {
         this.#assertOpen();
         // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
         this.#storage.db.exec('SAVEPOINT syncular_push_candidate');
         this.#pushApplySavepoint = true;
+        return {
+            gate: await this.#storage.readServeGate(this.#partition, runningSchemaVersion),
+            persisted: await this.#storage.getPushResult(this.#partition, clientId, clientCommitId),
+        };
     }
     async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
         this.#assertOpen();
@@ -144,6 +142,9 @@ class SqliteTransaction {
         this.#pushApplySavepoint = false;
         await this.putPushResult(clientId, clientCommitId, result);
         await this.commit();
+        // The idempotency re-check found no record under the writer lock, so the
+        // insert above is the canonical outcome.
+        return result;
     }
     async upsertRow(table, row, context) {
         this.#assertOpen();
@@ -186,11 +187,14 @@ class SqliteTransaction {
         const commitSeq = (row?.max_commit_seq ?? 0) + 1;
         db.query('UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?').run(commitSeq, p);
         db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs, this.#writerVersion);
+        const liveAfterDelete = rowsLiveAfterDelete(commit.changes);
         commit.changes.forEach((change, idx) => {
             db.query('INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)').run(p, commitSeq, idx, change.table, change.rowId, change.op === 'upsert' ? 1 : 2, change.rowVersion ?? null, JSON.stringify(change.scopes), change.payload ?? null);
-            if (change.op === 'delete') {
+            if (change.op === 'delete' &&
+                !liveAfterDelete.has(`${change.table}\u0000${change.rowId}`)) {
                 // §5 delete precedence: every applied delete leaves a tombstone,
-                // pruned with the commit log (§4.6).
+                // pruned with the commit log (§4.6). A delete that the same commit
+                // follows with an upsert is a §2.2 scope move, not a deletion.
                 db.query(`INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq) VALUES (?,?,?,?)
            ON CONFLICT(partition, tbl, row_id) DO UPDATE SET commit_seq=excluded.commit_seq`).run(p, change.table, change.rowId, commitSeq);
             }