@syncular/client 0.12.0 → 0.13.0

package/README.md

@@ -123,6 +123,14 @@ that rolled back with the terminating operation. It stays in the protected
 client database and is never added to the wire protocol, preferences, or
 telemetry; successful and historical outcomes may omit it.
 
+Rejected optimistic state is removed immediately, even when a validator emits
+no server row in the pull half. The TypeScript client stores protected,
+restart-safe before-images beside each pending outbox commit, restores the last
+confirmed rows (including rejected deletes and atomic siblings), and then
+replays later pending edits. These before-images are internal rollback state:
+they are never encoded on the wire or exposed through pending commits, outcome
+envelopes, diagnostics, preferences, or telemetry.
+
 Use `patch(table, rowId, partial, { baseVersion? })` for editor-style partial
 updates. The wire still carries a full row, but the durable local operation
 records a sorted `changedFields` list so conflict and rejection UI knows which

package/dist/client.js

@@ -14,7 +14,7 @@ import { registerDevtools } from './devtools.js';
 import { ClientSyncError } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
-import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, OutboxEncodeError, } from './outbox.js';
+import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
 import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
@@ -1004,7 +1004,7 @@ export class SyncClient {
         });
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
-                appendOutboxCommit(this.#db, clientCommitId, operations, this.#now());
+                appendOutboxCommit(this.#db, clientCommitId, operations, this.#now(), this.#captureBeforeImages(operations));
                 this.#applyOperationsLocally(operations, batch);
                 batch.status();
             });
@@ -1123,21 +1123,7 @@ export class SyncClient {
      */
     #dropIncompatibleCommit(commit, message) {
         this.#applyBatch((batch) => {
-            deleteOutboxCommit(this.#db, commit.clientCommitId);
-            for (const operation of commit.operations) {
-                if (operation.op !== 'upsert')
-                    continue;
-                const table = this.#schema.tables.get(operation.table);
-                if (table === undefined)
-                    continue;
-                const row = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [operation.rowId])[0];
-                if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
-                    if (!this.#recordStoredRowScopes(batch, table, operation.rowId)) {
-                        batch.table(table.name);
-                    }
-                    deleteLocalRow(this.#db, table, operation.rowId);
-                }
-            }
+            this.#rollbackFailedCommit(commit, batch);
             const rejection = {
                 clientCommitId: commit.clientCommitId,
                 opIndex: 0,
@@ -1811,26 +1797,11 @@ export class SyncClient {
         });
         pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
         batch.outcomes();
-        // §7.2: stop optimistic display and decide about dependents — the
-        // commit leaves the outbox; rows it created that the server never
-        // confirmed are undone here, rows it overwrote reconcile via the pull
-        // half (the conflict record carries the server row for the app).
+        // §7.2: remove the rejected optimistic layer. Before-images restore
+        // validator-rejected updates even when the server emitted no new COMMIT;
+        // later pending overlays are then replayed with rebased before-images.
         this.#db.transaction(() => {
-            deleteOutboxCommit(this.#db, frame.clientCommitId);
-            for (const operation of commit.operations) {
-                if (operation.op !== 'upsert')
-                    continue;
-                const table = this.#schema.tables.get(operation.table);
-                if (table === undefined)
-                    continue;
-                const row = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [operation.rowId])[0];
-                if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
-                    if (!this.#recordStoredRowScopes(batch, table, operation.rowId)) {
-                        batch.table(table.name);
-                    }
-                    deleteLocalRow(this.#db, table, operation.rowId);
-                }
-            }
+            this.#rollbackFailedCommit(commit, batch);
         });
         batch.status();
         summary.rejected.push(frame.clientCommitId);
@@ -2127,6 +2098,96 @@ export class SyncClient {
         return false;
     }
     // -- optimistic state ----------------------------------------------------------
+    #captureBeforeImage(operation, opIndex) {
+        const table = this.#schema.tables.get(operation.table);
+        if (table === undefined)
+            return { opIndex, existed: false };
+        const columns = [
+            ...table.columns.map((column) => quoteIdent(column.name)),
+            quoteIdent(SYNC_VERSION_COLUMN),
+        ];
+        const row = this.#db.query(`SELECT ${columns.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [operation.rowId])[0];
+        if (row === undefined)
+            return { opIndex, existed: false };
+        const values = {};
+        for (const column of table.columns) {
+            values[column.name] = rowValueToJson(fromSqlValue(column, row[column.name] ?? null));
+        }
+        const syncVersion = row[SYNC_VERSION_COLUMN];
+        if (typeof syncVersion !== 'number') {
+            throw new ClientSyncError('sync.local_corrupt', `local row ${operation.table}/${operation.rowId} has no sync version`);
+        }
+        return { opIndex, existed: true, syncVersion, values };
+    }
+    #captureBeforeImages(operations, onlyKeys) {
+        return operations.flatMap((operation, opIndex) => onlyKeys && !onlyKeys.has(`${operation.table}\u0000${operation.rowId}`)
+            ? []
+            : [this.#captureBeforeImage(operation, opIndex)]);
+    }
+    #restoreBeforeImage(operation, image, batch) {
+        const table = this.#schema.tables.get(operation.table);
+        if (table === undefined)
+            return;
+        batch.table(table.name);
+        if (!image.existed) {
+            deleteLocalRow(this.#db, table, operation.rowId);
+            return;
+        }
+        if (image.values === undefined || image.syncVersion === undefined) {
+            throw new ClientSyncError('sync.local_corrupt', `rollback image for ${operation.table}/${operation.rowId} is incomplete`);
+        }
+        const values = table.columns.map((column) => jsonToRowValue(image.values?.[column.name] ?? null));
+        upsertLocalRow(this.#db, table, values, image.syncVersion);
+    }
+    #legacyUndoOptimisticRows(commit, batch) {
+        for (const operation of commit.operations) {
+            if (operation.op !== 'upsert')
+                continue;
+            const table = this.#schema.tables.get(operation.table);
+            if (table === undefined)
+                continue;
+            const row = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [operation.rowId])[0];
+            if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
+                batch.table(table.name);
+                deleteLocalRow(this.#db, table, operation.rowId);
+            }
+        }
+    }
+    #rollbackFailedCommit(commit, batch) {
+        const images = listOutboxBeforeImages(this.#db, commit.clientCommitId);
+        const imageByIndex = new Map(images.map((image) => [image.opIndex, image]));
+        const complete = commit.operations.every((_, index) => imageByIndex.has(index));
+        const affectedKeys = new Set(commit.operations.map((operation) => `${operation.table}\u0000${operation.rowId}`));
+        if (complete) {
+            const restored = new Set();
+            commit.operations.forEach((operation, index) => {
+                const key = `${operation.table}\u0000${operation.rowId}`;
+                if (restored.has(key))
+                    return;
+                const image = imageByIndex.get(index);
+                if (image)
+                    this.#restoreBeforeImage(operation, image, batch);
+                restored.add(key);
+            });
+        }
+        else {
+            // Pending commits written by older clients have no before-images.
+            // Preserve the old fail-closed behavior rather than guessing a base.
+            this.#legacyUndoOptimisticRows(commit, batch);
+        }
+        deleteOutboxCommit(this.#db, commit.clientCommitId);
+        if (!complete)
+            return;
+        for (const later of listOutbox(this.#db)) {
+            if (later.seq <= commit.seq)
+                continue;
+            const affectedOperations = later.operations.filter((operation) => affectedKeys.has(`${operation.table}\u0000${operation.rowId}`));
+            if (affectedOperations.length === 0)
+                continue;
+            replaceOutboxBeforeImages(this.#db, later.clientCommitId, this.#captureBeforeImages(later.operations, affectedKeys));
+            this.#applyOperationsLocally(affectedOperations, batch);
+        }
+    }
     #applyOperationsLocally(operations, batch) {
         for (const op of operations) {
             const table = this.#table(op.table);

package/dist/outbox.d.ts

@@ -30,10 +30,19 @@ export interface OutboxCommit {
     readonly createdAtMs: number;
     readonly operations: readonly OutboxOperation[];
 }
-export declare function appendOutboxCommit(db: ClientDatabase, clientCommitId: string, operations: readonly OutboxOperation[], nowMs: number): void;
+/** Protected local rollback image; never encoded or exposed in outcomes. */
+export interface OutboxBeforeImage {
+    readonly opIndex: number;
+    readonly existed: boolean;
+    readonly syncVersion?: number;
+    readonly values?: Readonly<Record<string, JsonRowValue>>;
+}
+export declare function appendOutboxCommit(db: ClientDatabase, clientCommitId: string, operations: readonly OutboxOperation[], nowMs: number, beforeImages?: readonly OutboxBeforeImage[]): void;
 /** Pending commits in FIFO creation order (§7.1). */
 export declare function listOutbox(db: ClientDatabase): OutboxCommit[];
 export declare function deleteOutboxCommit(db: ClientDatabase, clientCommitId: string): void;
+export declare function listOutboxBeforeImages(db: ClientDatabase, clientCommitId: string): OutboxBeforeImage[];
+export declare function replaceOutboxBeforeImages(db: ClientDatabase, clientCommitId: string, replacements: readonly OutboxBeforeImage[]): void;
 /**
  * §7.4.4: after a schema bump, a persisted upsert may name a column the new
  * schema no longer has. The value has nowhere to go and there is no

package/dist/outbox.js

@@ -8,12 +8,23 @@
 import { encodeRow, } from '@syncular/core';
 import { ClientSyncError } from './errors.js';
 import { jsonToRowValue, } from './schema.js';
-export function appendOutboxCommit(db, clientCommitId, operations, nowMs) {
+export function appendOutboxCommit(db, clientCommitId, operations, nowMs, beforeImages = []) {
     if (operations.length === 0) {
         throw new ClientSyncError('sync.empty_commit', 'a local commit must carry at least one operation (§6.1)');
     }
     db.exec(`INSERT INTO _syncular_outbox(client_commit_id, created_at_ms, operations)
      VALUES (?, ?, ?)`, [clientCommitId, nowMs, JSON.stringify(operations)]);
+    for (const image of beforeImages) {
+        db.exec(`INSERT INTO _syncular_outbox_before_images(
+         client_commit_id, op_index, existed, sync_version, values_json
+       ) VALUES (?, ?, ?, ?, ?)`, [
+            clientCommitId,
+            image.opIndex,
+            image.existed ? 1 : 0,
+            image.syncVersion ?? null,
+            image.values === undefined ? null : JSON.stringify(image.values),
+        ]);
+    }
 }
 /** Pending commits in FIFO creation order (§7.1). */
 export function listOutbox(db) {
@@ -28,10 +39,44 @@ export function listOutbox(db) {
     }));
 }
 export function deleteOutboxCommit(db, clientCommitId) {
+    db.exec('DELETE FROM _syncular_outbox_before_images WHERE client_commit_id = ?', [clientCommitId]);
     db.exec('DELETE FROM _syncular_outbox WHERE client_commit_id = ?', [
         clientCommitId,
     ]);
 }
+export function listOutboxBeforeImages(db, clientCommitId) {
+    return db
+        .query(`SELECT op_index, existed, sync_version, values_json
+         FROM _syncular_outbox_before_images
+        WHERE client_commit_id = ? ORDER BY op_index`, [clientCommitId])
+        .map((row) => ({
+        opIndex: row.op_index,
+        existed: row.existed === 1,
+        ...(typeof row.sync_version === 'number'
+            ? { syncVersion: row.sync_version }
+            : {}),
+        ...(typeof row.values_json === 'string'
+            ? {
+                values: JSON.parse(row.values_json),
+            }
+            : {}),
+    }));
+}
+export function replaceOutboxBeforeImages(db, clientCommitId, replacements) {
+    for (const image of replacements) {
+        db.exec(`DELETE FROM _syncular_outbox_before_images
+        WHERE client_commit_id = ? AND op_index = ?`, [clientCommitId, image.opIndex]);
+        db.exec(`INSERT INTO _syncular_outbox_before_images(
+         client_commit_id, op_index, existed, sync_version, values_json
+       ) VALUES (?, ?, ?, ?, ?)`, [
+            clientCommitId,
+            image.opIndex,
+            image.existed ? 1 : 0,
+            image.syncVersion ?? null,
+            image.values === undefined ? null : JSON.stringify(image.values),
+        ]);
+    }
+}
 /**
  * §7.4.4: after a schema bump, a persisted upsert may name a column the new
  * schema no longer has. The value has nowhere to go and there is no

package/dist/schema.js

@@ -184,6 +184,13 @@ export function ensureLocalSchema(db, schema) {
       client_commit_id TEXT NOT NULL UNIQUE,
       created_at_ms INTEGER NOT NULL,
       operations TEXT NOT NULL)`);
+        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_outbox_before_images(
+      client_commit_id TEXT NOT NULL,
+      op_index INTEGER NOT NULL,
+      existed INTEGER NOT NULL CHECK(existed IN (0, 1)),
+      sync_version INTEGER,
+      values_json TEXT,
+      PRIMARY KEY(client_commit_id, op_index))`);
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes(
       seq INTEGER PRIMARY KEY AUTOINCREMENT,
       client_commit_id TEXT NOT NULL UNIQUE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.12.0"
+    "@syncular/core": "0.13.0"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.12.0",
+    "@syncular/server": "0.13.0",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -86,9 +86,12 @@ import {
   dropOutboxCommitsInScope,
   encodeOutboxCommit,
   listOutbox,
+  listOutboxBeforeImages,
+  type OutboxBeforeImage,
   type OutboxCommit,
   OutboxEncodeError,
   type OutboxOperation,
+  replaceOutboxBeforeImages,
 } from './outbox';
 import {
   activeFailureRecords,
@@ -1551,7 +1554,13 @@ export class SyncClient {
     });
     this.#applyBatch((batch) => {
       this.#db.transaction(() => {
-        appendOutboxCommit(this.#db, clientCommitId, operations, this.#now());
+        appendOutboxCommit(
+          this.#db,
+          clientCommitId,
+          operations,
+          this.#now(),
+          this.#captureBeforeImages(operations),
+        );
         this.#applyOperationsLocally(operations, batch);
         batch.status();
       });
@@ -1705,22 +1714,7 @@ export class SyncClient {
    */
   #dropIncompatibleCommit(commit: OutboxCommit, message: string): void {
     this.#applyBatch((batch) => {
-      deleteOutboxCommit(this.#db, commit.clientCommitId);
-      for (const operation of commit.operations) {
-        if (operation.op !== 'upsert') continue;
-        const table = this.#schema.tables.get(operation.table);
-        if (table === undefined) continue;
-        const row = this.#db.query(
-          `SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
-          [operation.rowId],
-        )[0];
-        if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
-          if (!this.#recordStoredRowScopes(batch, table, operation.rowId)) {
-            batch.table(table.name);
-          }
-          deleteLocalRow(this.#db, table, operation.rowId);
-        }
-      }
+      this.#rollbackFailedCommit(commit, batch);
       const rejection: RejectionRecord = {
         clientCommitId: commit.clientCommitId,
         opIndex: 0,
@@ -2548,27 +2542,11 @@ export class SyncClient {
     });
     pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
     batch.outcomes();
-    // §7.2: stop optimistic display and decide about dependents — the
-    // commit leaves the outbox; rows it created that the server never
-    // confirmed are undone here, rows it overwrote reconcile via the pull
-    // half (the conflict record carries the server row for the app).
+    // §7.2: remove the rejected optimistic layer. Before-images restore
+    // validator-rejected updates even when the server emitted no new COMMIT;
+    // later pending overlays are then replayed with rebased before-images.
     this.#db.transaction(() => {
-      deleteOutboxCommit(this.#db, frame.clientCommitId);
-      for (const operation of commit.operations) {
-        if (operation.op !== 'upsert') continue;
-        const table = this.#schema.tables.get(operation.table);
-        if (table === undefined) continue;
-        const row = this.#db.query(
-          `SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
-          [operation.rowId],
-        )[0];
-        if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
-          if (!this.#recordStoredRowScopes(batch, table, operation.rowId)) {
-            batch.table(table.name);
-          }
-          deleteLocalRow(this.#db, table, operation.rowId);
-        }
-      }
+      this.#rollbackFailedCommit(commit, batch);
     });
     batch.status();
     summary.rejected.push(frame.clientCommitId);
@@ -2945,6 +2923,134 @@ export class SyncClient {
 
   // -- optimistic state ----------------------------------------------------------
 
+  #captureBeforeImage(
+    operation: OutboxOperation,
+    opIndex: number,
+  ): OutboxBeforeImage {
+    const table = this.#schema.tables.get(operation.table);
+    if (table === undefined) return { opIndex, existed: false };
+    const columns = [
+      ...table.columns.map((column) => quoteIdent(column.name)),
+      quoteIdent(SYNC_VERSION_COLUMN),
+    ];
+    const row = this.#db.query(
+      `SELECT ${columns.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
+      [operation.rowId],
+    )[0];
+    if (row === undefined) return { opIndex, existed: false };
+    const values: Record<string, ReturnType<typeof rowValueToJson>> = {};
+    for (const column of table.columns) {
+      values[column.name] = rowValueToJson(
+        fromSqlValue(column, row[column.name] ?? null),
+      );
+    }
+    const syncVersion = row[SYNC_VERSION_COLUMN];
+    if (typeof syncVersion !== 'number') {
+      throw new ClientSyncError(
+        'sync.local_corrupt',
+        `local row ${operation.table}/${operation.rowId} has no sync version`,
+      );
+    }
+    return { opIndex, existed: true, syncVersion, values };
+  }
+
+  #captureBeforeImages(
+    operations: readonly OutboxOperation[],
+    onlyKeys?: ReadonlySet<string>,
+  ): OutboxBeforeImage[] {
+    return operations.flatMap((operation, opIndex) =>
+      onlyKeys && !onlyKeys.has(`${operation.table}\u0000${operation.rowId}`)
+        ? []
+        : [this.#captureBeforeImage(operation, opIndex)],
+    );
+  }
+
+  #restoreBeforeImage(
+    operation: OutboxOperation,
+    image: OutboxBeforeImage,
+    batch: ChangeAccumulator,
+  ): void {
+    const table = this.#schema.tables.get(operation.table);
+    if (table === undefined) return;
+    batch.table(table.name);
+    if (!image.existed) {
+      deleteLocalRow(this.#db, table, operation.rowId);
+      return;
+    }
+    if (image.values === undefined || image.syncVersion === undefined) {
+      throw new ClientSyncError(
+        'sync.local_corrupt',
+        `rollback image for ${operation.table}/${operation.rowId} is incomplete`,
+      );
+    }
+    const values = table.columns.map((column) =>
+      jsonToRowValue(image.values?.[column.name] ?? null),
+    );
+    upsertLocalRow(this.#db, table, values, image.syncVersion);
+  }
+
+  #legacyUndoOptimisticRows(
+    commit: OutboxCommit,
+    batch: ChangeAccumulator,
+  ): void {
+    for (const operation of commit.operations) {
+      if (operation.op !== 'upsert') continue;
+      const table = this.#schema.tables.get(operation.table);
+      if (table === undefined) continue;
+      const row = this.#db.query(
+        `SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
+        [operation.rowId],
+      )[0];
+      if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
+        batch.table(table.name);
+        deleteLocalRow(this.#db, table, operation.rowId);
+      }
+    }
+  }
+
+  #rollbackFailedCommit(commit: OutboxCommit, batch: ChangeAccumulator): void {
+    const images = listOutboxBeforeImages(this.#db, commit.clientCommitId);
+    const imageByIndex = new Map(images.map((image) => [image.opIndex, image]));
+    const complete = commit.operations.every((_, index) =>
+      imageByIndex.has(index),
+    );
+    const affectedKeys = new Set(
+      commit.operations.map(
+        (operation) => `${operation.table}\u0000${operation.rowId}`,
+      ),
+    );
+    if (complete) {
+      const restored = new Set<string>();
+      commit.operations.forEach((operation, index) => {
+        const key = `${operation.table}\u0000${operation.rowId}`;
+        if (restored.has(key)) return;
+        const image = imageByIndex.get(index);
+        if (image) this.#restoreBeforeImage(operation, image, batch);
+        restored.add(key);
+      });
+    } else {
+      // Pending commits written by older clients have no before-images.
+      // Preserve the old fail-closed behavior rather than guessing a base.
+      this.#legacyUndoOptimisticRows(commit, batch);
+    }
+    deleteOutboxCommit(this.#db, commit.clientCommitId);
+
+    if (!complete) return;
+    for (const later of listOutbox(this.#db)) {
+      if (later.seq <= commit.seq) continue;
+      const affectedOperations = later.operations.filter((operation) =>
+        affectedKeys.has(`${operation.table}\u0000${operation.rowId}`),
+      );
+      if (affectedOperations.length === 0) continue;
+      replaceOutboxBeforeImages(
+        this.#db,
+        later.clientCommitId,
+        this.#captureBeforeImages(later.operations, affectedKeys),
+      );
+      this.#applyOperationsLocally(affectedOperations, batch);
+    }
+  }
+
   #applyOperationsLocally(
     operations: readonly OutboxOperation[],
     batch?: ChangeAccumulator,

package/src/outbox.ts

@@ -43,11 +43,20 @@ export interface OutboxCommit {
   readonly operations: readonly OutboxOperation[];
 }
 
+/** Protected local rollback image; never encoded or exposed in outcomes. */
+export interface OutboxBeforeImage {
+  readonly opIndex: number;
+  readonly existed: boolean;
+  readonly syncVersion?: number;
+  readonly values?: Readonly<Record<string, JsonRowValue>>;
+}
+
 export function appendOutboxCommit(
   db: ClientDatabase,
   clientCommitId: string,
   operations: readonly OutboxOperation[],
   nowMs: number,
+  beforeImages: readonly OutboxBeforeImage[] = [],
 ): void {
   if (operations.length === 0) {
     throw new ClientSyncError(
@@ -60,6 +69,20 @@ export function appendOutboxCommit(
      VALUES (?, ?, ?)`,
     [clientCommitId, nowMs, JSON.stringify(operations)],
   );
+  for (const image of beforeImages) {
+    db.exec(
+      `INSERT INTO _syncular_outbox_before_images(
+         client_commit_id, op_index, existed, sync_version, values_json
+       ) VALUES (?, ?, ?, ?, ?)`,
+      [
+        clientCommitId,
+        image.opIndex,
+        image.existed ? 1 : 0,
+        image.syncVersion ?? null,
+        image.values === undefined ? null : JSON.stringify(image.values),
+      ],
+    );
+  }
 }
 
 /** Pending commits in FIFO creation order (§7.1). */
@@ -81,11 +104,68 @@ export function deleteOutboxCommit(
   db: ClientDatabase,
   clientCommitId: string,
 ): void {
+  db.exec(
+    'DELETE FROM _syncular_outbox_before_images WHERE client_commit_id = ?',
+    [clientCommitId],
+  );
   db.exec('DELETE FROM _syncular_outbox WHERE client_commit_id = ?', [
     clientCommitId,
   ]);
 }
 
+export function listOutboxBeforeImages(
+  db: ClientDatabase,
+  clientCommitId: string,
+): OutboxBeforeImage[] {
+  return db
+    .query(
+      `SELECT op_index, existed, sync_version, values_json
+         FROM _syncular_outbox_before_images
+        WHERE client_commit_id = ? ORDER BY op_index`,
+      [clientCommitId],
+    )
+    .map((row) => ({
+      opIndex: row.op_index as number,
+      existed: row.existed === 1,
+      ...(typeof row.sync_version === 'number'
+        ? { syncVersion: row.sync_version }
+        : {}),
+      ...(typeof row.values_json === 'string'
+        ? {
+            values: JSON.parse(row.values_json) as Readonly<
+              Record<string, JsonRowValue>
+            >,
+          }
+        : {}),
+    }));
+}
+
+export function replaceOutboxBeforeImages(
+  db: ClientDatabase,
+  clientCommitId: string,
+  replacements: readonly OutboxBeforeImage[],
+): void {
+  for (const image of replacements) {
+    db.exec(
+      `DELETE FROM _syncular_outbox_before_images
+        WHERE client_commit_id = ? AND op_index = ?`,
+      [clientCommitId, image.opIndex],
+    );
+    db.exec(
+      `INSERT INTO _syncular_outbox_before_images(
+         client_commit_id, op_index, existed, sync_version, values_json
+       ) VALUES (?, ?, ?, ?, ?)`,
+      [
+        clientCommitId,
+        image.opIndex,
+        image.existed ? 1 : 0,
+        image.syncVersion ?? null,
+        image.values === undefined ? null : JSON.stringify(image.values),
+      ],
+    );
+  }
+}
+
 /**
  * §7.4.4: after a schema bump, a persisted upsert may name a column the new
  * schema no longer has. The value has nowhere to go and there is no

package/src/schema.ts

@@ -288,6 +288,13 @@ export function ensureLocalSchema(
       client_commit_id TEXT NOT NULL UNIQUE,
       created_at_ms INTEGER NOT NULL,
       operations TEXT NOT NULL)`);
+    db.exec(`CREATE TABLE IF NOT EXISTS _syncular_outbox_before_images(
+      client_commit_id TEXT NOT NULL,
+      op_index INTEGER NOT NULL,
+      existed INTEGER NOT NULL CHECK(existed IN (0, 1)),
+      sync_version INTEGER,
+      values_json TEXT,
+      PRIMARY KEY(client_commit_id, op_index))`);
     db.exec(`CREATE TABLE IF NOT EXISTS _syncular_commit_outcomes(
       seq INTEGER PRIMARY KEY AUTOINCREMENT,
       client_commit_id TEXT NOT NULL UNIQUE,