@syncular/server 0.42.2 → 0.44.0

package/dist/storage.d.ts

@@ -67,6 +67,17 @@ export interface ServeGate {
         readonly name: string;
     }[];
 }
+/**
+ * The push apply's admission token: the partition lock, the serve gate, and
+ * the idempotency record read in one round trip. A storage with per-statement
+ * network cost answers all three with one statement (see
+ * `PostgresServerStorage`); the lock is held from this call through commit.
+ */
+export interface PreparedPushApply {
+    readonly gate: ServeGate;
+    /** The already-persisted outcome for this key, or `undefined` on a miss. */
+    readonly persisted: StoredPushResult | undefined;
+}
 /** Why `serveGate` refuses, or `undefined` when this request may serve. */
 export type ServeGateRefusal = {
     readonly kind: 'schema';
@@ -128,6 +139,13 @@ export interface NewCommit {
     readonly createdAtMs: number;
     readonly changes: readonly NewChange[];
 }
+/**
+ * §2.2: rows whose final change in this commit is an upsert that followed a
+ * delete. That delete is one half of a scope move, so it MUST NOT leave a
+ * tombstone behind the live row. A row whose final change is a delete keeps
+ * its tombstone.
+ */
+export declare function rowsLiveAfterDelete(changes: readonly NewChange[]): Set<string>;
 export interface StoredChange {
     readonly table: string;
     readonly rowId: string;
@@ -409,12 +427,15 @@ export interface StorageTransaction {
     getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
     /**
      * Optional read-ahead: the push layer names every row a commit's
-     * operations target, per table, before it applies them. A storage with
-     * per-statement network cost reads them in one statement and answers the
-     * following `getRow` calls from that snapshot until the row is written in
-     * this transaction.
+     * operations target, across every table, before it applies them. A storage
+     * with per-statement network cost reads them in one statement (one branch
+     * per table) and answers the following `getRow` calls from that snapshot
+     * until the row is written in this transaction.
      */
-    prefetchRows?(table: string, rowIds: readonly string[]): Promise<void>;
+    prefetchRows?(targets: readonly {
+        readonly table: string;
+        readonly rowIds: readonly string[];
+    }[]): Promise<void>;
     /**
      * §5 delete-precedence tombstone read: the `commit_seq` of the newest
      * applied delete of this row still within the pruning horizon, or
@@ -429,17 +450,6 @@ export interface StorageTransaction {
      * over an absent row; a no-op when no tombstone exists.
      */
     clearTombstone(table: string, rowId: string): Promise<void>;
-    /**
-     * Optional transaction-scoped idempotency lookup (§2.3) with the same
-     * semantics as `ServerStorage.getPushResult`, including the
-     * `sync.idempotency_cache_miss` throw. The push layer prefers it for the
-     * post-serialization duplicate re-check so the read runs on the
-     * transaction's own connection — a pooled Postgres client that holds the
-     * partition lock must never wait for a second pool slot mid-push. In-tree
-     * SQLite/Postgres/D1 adapters implement it; a custom adapter that omits it
-     * keeps the pool-level read.
-     */
-    getPushResult?(clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
     /**
      * Optional candidate-state scan used only by whole-commit validation.
      * In-tree SQLite/Postgres/D1 backends implement it with read-your-own-writes
@@ -467,24 +477,28 @@ export interface StorageTransaction {
     queryAuthoritative?(query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
     /**
      * Serialize every push apply for this partition before any operation read,
-     * validation, merge, or write. The push layer re-checks idempotency only
-     * after this resolves and retains the lock through terminal-result commit.
+     * validation, merge, or write, and read the admission token in the same
+     * round trip: the RFC 0007 serve gate and the §2.3 idempotency record for
+     * `clientCommitId`. The lock is retained through terminal-result commit,
+     * so the idempotency read is exact and a racing duplicate cannot rerun.
+     * `targets` are the rows the commit is known to touch before its operations
+     * are built; a storage with per-statement network cost folds that read-ahead
+     * into the admission read and answers the following `getRow` calls from it.
      * Missing support fails closed before an app-row mutation.
      */
-    lockPartitionForPush?(): Promise<void>;
-    /**
-     * @deprecated Implement `lockPartitionForPush`. Kept as a compatibility
-     * bridge for custom adapters whose existing implementation already locks
-     * the complete partition from before candidate reads through commit.
-     */
-    lockPartitionForCommitValidation?(): Promise<void>;
+    preparePushApply(clientId: string, clientCommitId: string, runningSchemaVersion: number, targets?: readonly {
+        readonly table: string;
+        readonly rowIds: readonly string[];
+    }[]): Promise<PreparedPushApply>;
     /**
      * Rejection finalization while the push-apply serialization lock is still
      * held: discard every candidate write, persist the rejected idempotency
-     * result, and finish the transaction atomically. Required for every push so
-     * a concurrent duplicate cannot rerun operations, validators, or merges.
+     * result, and finish the transaction atomically. Returns the persisted
+     * canonical outcome, so the caller never re-reads it. Required for every
+     * push so a concurrent duplicate cannot rerun operations, validators, or
+     * merges.
      */
-    commitRejectedPushResult?(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
+    commitRejectedPushResult(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<StoredPushResult>;
     upsertRow(table: string, row: StoredRow, context?: {
         readonly opIndex: number;
     }): Promise<void>;
@@ -566,10 +580,10 @@ export interface ServerStorage {
      * same command races a push on Postgres and a SQLite-only test conceals it.
      *
      * A trusted command must therefore run through `registerRemoteCommand`,
-     * which builds after `lockPartitionForPush` and the idempotency recheck and
-     * shares the committed transaction, or call `lockPartitionForPush` before
-     * its first authority, version, or replay read. SSP2 request handling does
-     * this for you; only host-authored commands choose.
+     * which builds after `preparePushApply` and shares the committed
+     * transaction, or call `preparePushApply` before its first authority,
+     * version, or replay read. SSP2 request handling does this for you; only
+     * host-authored commands choose.
      */
     begin(partition: string): Promise<StorageTransaction>;
     getMaxCommitSeq(partition: string): Promise<number>;

package/dist/storage.js

@@ -38,6 +38,32 @@ export function serveGateTokenChanged(before, after) {
     }
     return undefined;
 }
+/**
+ * §2.2: rows whose final change in this commit is an upsert that followed a
+ * delete. That delete is one half of a scope move, so it MUST NOT leave a
+ * tombstone behind the live row. A row whose final change is a delete keeps
+ * its tombstone.
+ */
+export function rowsLiveAfterDelete(changes) {
+    const last = new Map();
+    const deleted = new Set();
+    const live = new Set();
+    for (const change of changes) {
+        const key = `${change.table}\u0000${change.rowId}`;
+        if (change.op === 'delete') {
+            deleted.add(key);
+        }
+        else if (deleted.has(key)) {
+            live.add(key);
+        }
+        last.set(key, change.op);
+    }
+    for (const key of live) {
+        if (last.get(key) !== 'upsert')
+            live.delete(key);
+    }
+    return live;
+}
 /** The round-state fields of a stored `sync_clients` row. */
 export function clientRoundState(lastRoundAtMs, lastErrorCode, consecutiveFailures) {
     return {

package/package.json

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

package/src/d1-storage.ts

@@ -1,7 +1,11 @@
 import { validateCommitPruneQuery } from './prune';
 import { StorageQueryError } from './storage-errors';
 import type { CommitPruneQuery, CommitPruneResult } from './storage';
-import { clientRoundState, PARTITION_TOUCH_INTERVAL_MS } from './storage';
+import {
+  clientRoundState,
+  PARTITION_TOUCH_INTERVAL_MS,
+  rowsLiveAfterDelete,
+} from './storage';
 /**
  * Cloudflare D1 server storage for Workers deployments.
  *
@@ -127,6 +131,7 @@ import type {
   IndexRowScanQuery,
   NewCommit,
   NewReaction,
+  PreparedPushApply,
   PartitionRegistryEntry,
   PrunedReactionCounts,
   ReactionClaimQuery,
@@ -546,7 +551,15 @@ class D1Transaction implements StorageTransaction {
     );
   }
 
-  async lockPartitionForPush(): Promise<void> {
+  async preparePushApply(
+    clientId: string,
+    clientCommitId: string,
+    runningSchemaVersion: number,
+    _targets: readonly {
+      readonly table: string;
+      readonly rowIds: readonly string[];
+    }[] = [],
+  ): Promise<PreparedPushApply> {
     this.#assertOpen();
     if (!this.#pushApplySerialized) {
       throw new Error(
@@ -556,6 +569,10 @@ class D1Transaction implements StorageTransaction {
     // D1 has no interactive lock. The caller explicitly asserted that every
     // write for this partition is already serialized (normally by its DO).
     this.#pushApplyCheckpoint = this.#buffer.length;
+    return {
+      gate: await this.readServeGate(runningSchemaVersion),
+      persisted: await this.getPushResult(clientId, clientCommitId),
+    };
   }
 
   advanceCheckpoint(
@@ -587,7 +604,7 @@ class D1Transaction implements StorageTransaction {
     clientId: string,
     clientCommitId: string,
     result: StoredPushResult,
-  ): Promise<void> {
+  ): Promise<StoredPushResult> {
     this.#assertOpen();
     const checkpoint = this.#pushApplyCheckpoint;
     if (checkpoint === undefined) {
@@ -600,6 +617,9 @@ class D1Transaction implements StorageTransaction {
     this.#applicationOpIndexes.clear();
     await this.putPushResult(clientId, clientCommitId, result);
     await this.commit();
+    // The idempotency re-check found no record under the serialized apply, so
+    // the insert above is the canonical outcome.
+    return result;
   }
 
   async #assertNoUniqueCollision(
@@ -790,6 +810,7 @@ class D1Transaction implements StorageTransaction {
         commit.createdAtMs,
       ],
     );
+    const liveAfterDelete = rowsLiveAfterDelete(commit.changes);
     commit.changes.forEach((change, idx) => {
       this.#buffer_(
         'INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)',
@@ -805,9 +826,13 @@ class D1Transaction implements StorageTransaction {
           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.
         this.#buffer_(
           `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`,

package/src/operations.ts

@@ -7,7 +7,6 @@ import {
   decodeRemoteOperationRequest,
   encodeRemoteOperationResponse,
   encodeSparseRow,
-  type PushOperation,
   type RemoteOperationRequest,
   type RemoteOperationResponse,
   type RowValue,
@@ -20,7 +19,7 @@ import {
   touchAuthenticatedPartition,
 } from './context';
 import { reportError, SyncError, syncError } from './errors';
-import { processPushOperationsWithTrace } from './push';
+import { processPushOperationsWithTrace, type ApplyOperation } from './push';
 import { compileSchema } from './schema';
 import {
   authorizeWrite,
@@ -108,6 +107,12 @@ export type CommandMutation =
       readonly op: 'upsert';
       readonly values: Readonly<Record<string, RowValue>>;
     }
+  | {
+      readonly table: string;
+      readonly op: 'rescope';
+      /** Full row; only its scope columns may differ from the stored row. */
+      readonly values: Readonly<Record<string, RowValue>>;
+    }
   | {
       readonly table: string;
       readonly op: 'delete';
@@ -501,7 +506,7 @@ export function remoteCommand<Input = undefined>(
 function commandOperations(
   mutations: readonly CommandMutation[],
   schema: ReturnType<typeof compileSchema>,
-): PushOperation[] {
+): ApplyOperation[] {
   if (mutations.length === 0) {
     throw syncError(
       'operation.invalid_request',
@@ -530,7 +535,7 @@ function commandOperations(
       if (!table.columnIndex.has(name)) {
         throw syncError(
           'operation.invalid_request',
-          'command upsert has an unknown column',
+          'command upsert or rescope has an unknown column',
         );
       }
     }
@@ -538,7 +543,7 @@ function commandOperations(
       if (!supplied.has(column.name)) {
         throw syncError(
           'operation.invalid_request',
-          'command upsert must provide a full row',
+          'command upsert or rescope must provide a full row',
         );
       }
       return mutation.values[column.name] ?? null;
@@ -547,13 +552,13 @@ function commandOperations(
     if (rowId === undefined) {
       throw syncError(
         'operation.invalid_request',
-        'command upsert requires a non-empty primary key',
+        'command upsert or rescope requires a non-empty primary key',
       );
     }
     return {
       table: table.name,
       rowId,
-      op: 'upsert',
+      op: mutation.op,
       payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
     };
   });