@syncular/client 0.30.7 → 0.30.10

package/src/client.ts

@@ -1,3 +1,9 @@
+import {
+  dropFailedRows,
+  failedOverlayCommits,
+  retainFailedRows,
+  restoreFailedBases,
+} from './failed-overlay';
 import {
   ProgressEmitter,
   type SyncProgress,
@@ -88,6 +94,7 @@ import {
 import type { EncryptionConfig } from './encryption';
 import {
   ClientSyncError,
+  invalidRequest,
   classifySqliteFailure,
   REALTIME_LOST_CODE,
   RealtimeUnavailableError,
@@ -244,8 +251,8 @@ import {
 export type MutationInput =
   | {
       readonly table: string;
-      readonly op: 'upsert';
-      /** Full-row values keyed by column name (§6.1: full row payloads). */
+      readonly op: 'upsert' | 'patch';
+      /** Column-keyed full row for upsert, or primary key plus present columns for patch. */
       readonly values: Readonly<Record<string, unknown>>;
       readonly baseVersion?: number;
     }
@@ -260,6 +267,7 @@ export type {
   CommitOperationOutcome,
   CommitOutcome,
   CommitOutcomeQuery,
+  RetainedCommitRow,
   ConflictRecord,
   RejectionRecord,
   ResolveCommitOutcomeInput,
@@ -336,6 +344,8 @@ export interface SyncClientLimits {
 }
 
 export interface SyncClientConfig {
+  /** Keep rejected/conflicting local intent visible until explicit resolution. */
+  readonly retainFailedCommits?: boolean;
   readonly database: ClientDatabase;
   readonly schema: ClientSchema;
   readonly transport: SyncTransport;
@@ -618,8 +628,7 @@ function boundedBudget(
 ): number {
   if (value === undefined) return fallback;
   if (!Number.isSafeInteger(value) || value < 1) {
-    throw new ClientSyncError(
-      'sync.invalid_request',
+    throw invalidRequest(
       `previousVersionContext.${name} must be a positive safe integer`,
     );
   }
@@ -668,8 +677,7 @@ function previousVersionMaxAgeMs(
 function resolvePreviousVersionLimit(limit: number | undefined): number {
   if (limit === undefined) return 50;
   if (!Number.isFinite(limit) || limit < 1) {
-    throw new ClientSyncError(
-      'sync.invalid_request',
+    throw invalidRequest(
       'previousVersionSnapshot limit must be a positive number',
     );
   }
@@ -736,6 +744,7 @@ export class SyncClient {
   #securityLifecycle: SecurityLifecycle;
   readonly #now: () => number;
   readonly #outcomeRetentionMaxEntries: number;
+  readonly #retainFailedCommits: boolean;
   #started = false;
   #lease: LeaderLease | undefined;
   #clientId = '';
@@ -825,11 +834,11 @@ export class SyncClient {
 
   constructor(config: SyncClientConfig) {
     if (config.securityPreflight === true && config.encryption !== undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight',
       );
     }
+    this.#retainFailedCommits = config.retainFailedCommits === true;
     this.#db = config.database;
     this.#schema = compileClientSchema(config.schema);
     const realtimePolicy = config.realtimePolicy ?? 'optional';
@@ -838,14 +847,12 @@ export class SyncClient {
       realtimePolicy !== 'optional' &&
       realtimePolicy !== 'off'
     ) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         "realtimePolicy must be 'required', 'optional', or 'off'",
       );
     }
     if (realtimePolicy === 'required' && config.realtime === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         "realtimePolicy 'required' needs a realtime connector",
       );
     }
@@ -867,8 +874,7 @@ export class SyncClient {
       !Number.isSafeInteger(outcomeRetentionMaxEntries) ||
       outcomeRetentionMaxEntries < 1
     ) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'outcomeRetentionMaxEntries must be a positive safe integer',
       );
     }
@@ -1272,8 +1278,7 @@ export class SyncClient {
   async activateSecurity(options: SecurityActivation = {}): Promise<void> {
     this.#requireStarted();
     if (this.#securityLifecycle === 'active') {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'activateSecurity requires the client to be in security preflight',
       );
     }
@@ -1471,8 +1476,7 @@ export class SyncClient {
     }
     const table = record.tables.find((entry) => entry.name === spec.table);
     if (table === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         `previousVersionSnapshot names unknown previous table ${JSON.stringify(spec.table)}`,
       );
     }
@@ -1707,8 +1711,7 @@ export class SyncClient {
     this.#requireActive();
     const expected = request.expectedSubscriptions ?? [];
     if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         `diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`,
       );
     }
@@ -1747,8 +1750,7 @@ export class SyncClient {
         typeof item.table !== 'string' ||
         item.table.length === 0
       ) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
+        throw invalidRequest(
           'diagnosticsSnapshot expected subscriptions require non-empty id and table strings',
         );
       }
@@ -1973,6 +1975,12 @@ export class SyncClient {
         this.#batch = batch;
         try {
           result = fn(batch);
+          if (
+            this.#db
+              .query('SELECT DISTINCT tbl FROM _syncular_failed_rows')
+              .some((row) => batch.hasTable(String(row.tbl)))
+          )
+            batch.outcomes();
           if (batch.touched) {
             revision = bumpLocalRevision(this.#db);
             if (batch.statusChanged) {
@@ -2065,8 +2073,7 @@ export class SyncClient {
     options?: { readonly mediaType?: string; readonly name?: string },
   ): Promise<BlobRef> {
     if (this.#config.blobs === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)',
       );
     }
@@ -2110,8 +2117,7 @@ export class SyncClient {
     if (cached !== undefined) return cached;
     const transport = this.#config.blobs;
     if (transport === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'fetchBlob requires a blob transport (SyncClientConfig.blobs, §5.9)',
       );
     }
@@ -2123,8 +2129,7 @@ export class SyncClient {
     let bytes: Uint8Array;
     if (response.kind === 'url') {
       if (transport.fetchUrl === undefined) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
+        throw invalidRequest(
           'blob download returned a url but the transport cannot fetch urls (§5.9.5)',
         );
       }
@@ -2148,8 +2153,7 @@ export class SyncClient {
       // §5.9.5 inherits §5.1: verify the content address, reject on mismatch.
       // On the url path this invalidates the fetch (no fall-through) — the
       // next fetchBlob re-requests the authorized endpoint (§5.9.5 recovery).
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         `blob content address mismatch for ${blobId} (§5.9.5)`,
       );
     }
@@ -2158,10 +2162,7 @@ export class SyncClient {
     this.#enforceBlobCacheCap();
     const stored = getCachedBlob(this.#db, blobId);
     if (stored === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
-        'blob cache write failed',
-      );
+      throw invalidRequest('blob cache write failed');
     }
     return stored;
   }
@@ -2273,7 +2274,7 @@ export class SyncClient {
   /**
    * Mark a durable failure handled without deleting its evidence. Conflicts
    * may keep the server row or link to a replacement commit; rejections may
-   * only be superseded by a named replacement. Applied/cached history may be
+   * also keep the server row or link to a named replacement. Applied/cached history may be
    * dismissed. The transition is one-way and survives restart.
    */
   resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome {
@@ -2293,14 +2294,12 @@ export class SyncClient {
         replacement.length === 0 ||
         replacement === input.clientCommitId
       ) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
+        throw invalidRequest(
           'superseded outcomes require a distinct replacementClientCommitId',
         );
       }
     } else if (replacement !== undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'replacementClientCommitId is valid only for superseded outcomes',
       );
     }
@@ -2308,40 +2307,58 @@ export class SyncClient {
       (current.status === 'conflict' &&
         (input.resolution === 'resolved_keep_server' ||
           input.resolution === 'superseded')) ||
-      (current.status === 'rejected' && input.resolution === 'superseded') ||
+      (current.status === 'rejected' &&
+        (input.resolution === 'superseded' ||
+          input.resolution === 'resolved_keep_server')) ||
       ((current.status === 'applied' || current.status === 'cached') &&
         input.resolution === 'dismissed');
     if (!allowed) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         `resolution ${input.resolution} is invalid for ${current.status} outcome`,
       );
     }
 
-    return this.#applyBatch((batch) => {
-      const resolved = persistCommitOutcomeResolution(
-        this.#db,
-        input,
-        this.#now(),
-      );
-      if (resolved === undefined) {
-        throw new ClientSyncError(
-          'sync.outcome_not_found',
-          `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`,
+    const priorConflicts = this.#conflicts;
+    const priorRejections = this.#rejections;
+    return this.#applyBatch(
+      (batch) => {
+        restoreFailedBases(this.#db, this.#schema);
+        this.#db.exec('DELETE FROM _syncular_failed_rows WHERE commit_id = ?', [
+          input.clientCommitId,
+        ]);
+        const resolved = persistCommitOutcomeResolution(
+          this.#db,
+          input,
+          this.#now(),
         );
-      }
-      this.#conflicts = this.#conflicts.filter(
-        (record) => record.clientCommitId !== input.clientCommitId,
-      );
-      this.#rejections = this.#rejections.filter(
-        (record) => record.clientCommitId !== input.clientCommitId,
-      );
-      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
-      batch.outcomes();
-      if (current.status === 'conflict') batch.conflicts();
-      if (current.status === 'rejected') batch.rejections();
-      return resolved;
-    });
+        if (resolved === undefined) {
+          throw new ClientSyncError(
+            'sync.outcome_not_found',
+            `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`,
+          );
+        }
+        this.#conflicts = this.#conflicts.filter(
+          (record) => record.clientCommitId !== input.clientCommitId,
+        );
+        this.#rejections = this.#rejections.filter(
+          (record) => record.clientCommitId !== input.clientCommitId,
+        );
+        pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+        this.#replayOutbox();
+        for (const operation of current.operations ?? [])
+          batch.table(operation.table);
+        batch.outcomes();
+        if (current.status === 'conflict') batch.conflicts();
+        if (current.status === 'rejected') batch.rejections();
+        return resolved;
+      },
+      undefined,
+      (error) => {
+        this.#conflicts = priorConflicts;
+        this.#rejections = priorRejections;
+        throw error;
+      },
+    );
   }
 
   /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
@@ -2397,8 +2414,7 @@ export class SyncClient {
     this.#requireActive();
     const socket = this.#socket;
     if (socket === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'setPresence requires a connected realtime socket (§8.6)',
       );
     }
@@ -2509,8 +2525,7 @@ export class SyncClient {
     this.#requireActive();
     const table = this.#table(base.table);
     if (!table.scopeColumnByVariable.has(base.variable)) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         `setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`,
       );
     }
@@ -2689,7 +2704,10 @@ export class SyncClient {
    */
   #pinnedRowIds(table: string): Set<string> {
     const pinned = new Set<string>();
-    for (const commit of listOutbox(this.#db)) {
+    for (const commit of [
+      ...failedOverlayCommits(this.#db),
+      ...listOutbox(this.#db),
+    ]) {
       for (const op of commit.operations) {
         if (op.table === table) pinned.add(op.rowId);
       }
@@ -2708,10 +2726,7 @@ export class SyncClient {
     return this.#recordMutations(mutations);
   }
 
-  #recordMutations(
-    mutations: readonly MutationInput[],
-    partial = false,
-  ): string {
+  #recordMutations(mutations: readonly MutationInput[]): string {
     this.#requireActive();
     const clientCommitId = crypto.randomUUID();
     const operations: OutboxOperation[] = mutations.map((mutation) => {
@@ -2726,7 +2741,8 @@ export class SyncClient {
             : {}),
         };
       }
-      if (partial) {
+      const json: Record<string, JsonRowValue> = {};
+      if (mutation.op === 'patch') {
         // §6.7 patch: the values map IS the presence set — the primary key
         // plus the supplied non-scope columns. Absent columns keep their
         // stored value; the overlay and the server both apply only the
@@ -2734,7 +2750,16 @@ export class SyncClient {
         const normalized = normalizeRecordKeys(table, mutation.values);
         const scopeColumns = new Set(table.scopeColumnByVariable.values());
         const pkColumn = table.columns[table.primaryKeyIndex] as RowColumn;
-        const json: Record<string, JsonRowValue> = {};
+        const pkValue = requireRowId(normalized.get(pkColumn.name));
+        const local = this.#db.query(
+          `SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
+          [pkValue],
+        )[0];
+        if (!local)
+          throw new ClientSyncError(
+            'sync.row_missing',
+            'a sparse patch requires a local row',
+          );
         for (const column of table.columns) {
           if (!normalized.has(column.name)) continue;
           // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
@@ -2748,16 +2773,7 @@ export class SyncClient {
           // by construction the row id being patched (§6.1), so its value is
           // proven equal already.
           if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
-            const pkValue = normalized.get(pkColumn.name);
-            const local =
-              typeof pkValue === 'string' && pkValue.length > 0
-                ? this.#db.query(
-                    `SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
-                    [pkValue],
-                  )[0]
-                : undefined;
             if (
-              local === undefined ||
               !Object.is(
                 rowValueToJson(
                   fromSqlValue(column, local[column.name] ?? null),
@@ -2770,8 +2786,7 @@ export class SyncClient {
                 ),
               )
             ) {
-              throw new ClientSyncError(
-                'sync.invalid_request',
+              throw invalidRequest(
                 `table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`,
               );
             }
@@ -2780,8 +2795,7 @@ export class SyncClient {
           const value = normalized.get(column.name);
           if (value === undefined || value === null) {
             if (!column.nullable) {
-              throw new ClientSyncError(
-                'sync.invalid_request',
+              throw invalidRequest(
                 `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1)`,
               );
             }
@@ -2792,35 +2806,13 @@ export class SyncClient {
             coerceSqlRepresentation(column, value) as RowValue,
           );
         }
-        const pkValue = json[pkColumn.name];
-        if (typeof pkValue !== 'string' || pkValue.length === 0) {
-          throw new ClientSyncError(
-            'sync.invalid_request',
-            `table ${table.name}: upsert requires a non-empty string primary key`,
-          );
-        }
-        return {
-          table: mutation.table,
-          rowId: pkValue,
-          op: 'upsert',
-          ...(mutation.baseVersion !== undefined
-            ? { baseVersion: mutation.baseVersion }
-            : {}),
-          values: json,
-        };
-      }
-      const values = recordToRowValues(table, mutation.values);
-      const pkValue = values[table.primaryKeyIndex];
-      if (typeof pkValue !== 'string' || pkValue.length === 0) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
-          `table ${table.name}: upsert requires a non-empty string primary key`,
-        );
+      } else {
+        const values = recordToRowValues(table, mutation.values);
+        table.columns.forEach((column, index) => {
+          json[column.name] = rowValueToJson(values[index] ?? null);
+        });
       }
-      const json: Record<string, ReturnType<typeof rowValueToJson>> = {};
-      table.columns.forEach((column, index) => {
-        json[column.name] = rowValueToJson(values[index] ?? null);
-      });
+      const pkValue = requireRowId(json[table.primaryKey]);
       return {
         table: mutation.table,
         rowId: pkValue,
@@ -2917,27 +2909,23 @@ export class SyncClient {
     const normalized = normalizeRecordKeys(compiled, partial);
     const pkOverride = normalized.get(pkColumn.name);
     if (pkOverride !== undefined && pkOverride !== rowId) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         `table ${compiled.name}: patch cannot change the primary key`,
       );
     }
-    return this.#recordMutations(
-      [
-        {
-          table,
-          op: 'upsert',
-          values: {
-            ...Object.fromEntries(normalized),
-            [pkColumn.name]: rowId,
-          },
-          ...(options?.baseVersion !== undefined
-            ? { baseVersion: options.baseVersion }
-            : {}),
+    return this.#recordMutations([
+      {
+        table,
+        op: 'patch',
+        values: {
+          ...Object.fromEntries(normalized),
+          [pkColumn.name]: rowId,
         },
-      ],
-      true,
-    );
+        ...(options?.baseVersion !== undefined
+          ? { baseVersion: options.baseVersion }
+          : {}),
+      },
+    ]);
   }
 
   /**
@@ -2957,8 +2945,7 @@ export class SyncClient {
     const appliedPlan = getMeta(this.#db, metaKey);
     if (appliedPlan !== undefined) {
       if (appliedPlan !== purge.canonicalPlan) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
+        throw invalidRequest(
           `local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`,
         );
       }
@@ -2973,6 +2960,19 @@ export class SyncClient {
     try {
       return this.#applyBatch((batch) => {
         const targetsByTable = this.#localPurgeTargetsByTable(purge);
+        restoreFailedBases(this.#db, this.#schema);
+        const droppedRetained = dropFailedRows(this.#db, (table, values) =>
+          (targetsByTable.get(table) ?? []).some((target) =>
+            target.selectors.every((selector) =>
+              selector.values.includes(String(values[selector.column])),
+            ),
+          ),
+        );
+        for (const commit of droppedRetained) {
+          for (const operation of commit.operations)
+            batch.table(operation.table);
+          batch.outcomes();
+        }
         // Doomed detection runs to fixpoint, matching the Rust core's rule:
         // a commit is doomed when any of its ops touches a base-matching
         // row. Base values only become visible here as rollbacks restore
@@ -3074,6 +3074,7 @@ export class SyncClient {
           batch.rejections();
           batch.outcomes();
         }
+        this.#replayOutbox();
         this.#deleteUnreferencedBlobs();
         setMeta(this.#db, metaKey, purge.canonicalPlan);
         return {
@@ -3116,8 +3117,7 @@ export class SyncClient {
       };
     }
     if (this.#schemaFloor !== undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'local rebootstrap cannot bypass an active schema-floor stop; update the application first',
       );
     }
@@ -3327,7 +3327,14 @@ export class SyncClient {
     code: string = OUTBOX_INCOMPATIBLE_CODE,
   ): void {
     this.#applyBatch((batch) => {
+      if (this.#retainFailedCommits && code === 'client.encrypt_failed')
+        retainFailedRows(
+          this.#db,
+          commit,
+          listOutboxBeforeImages(this.#db, commit.clientCommitId),
+        );
       this.#rollbackFailedCommit(commit, batch);
+      this.#replayOutbox();
       const rejection: RejectionRecord = {
         clientCommitId: commit.clientCommitId,
         opIndex: 0,
@@ -3368,8 +3375,7 @@ export class SyncClient {
     this.#requireActive();
     if (this.#syncOutstanding) {
       return Promise.reject(
-        new ClientSyncError(
-          'sync.invalid_request',
+        invalidRequest(
           'sync() is already running — the core owns one loop (coalesce wake-ups)',
         ),
       );
@@ -3545,10 +3551,7 @@ export class SyncClient {
       const responseBytes = await this.#roundTrip(requestBytes);
       const message = decodeMessage(responseBytes);
       if (message.msgKind !== 'response') {
-        throw new ClientSyncError(
-          'sync.invalid_request',
-          'transport returned a non-response message',
-        );
+        throw invalidRequest('transport returned a non-response message');
       }
       const summary = await this.#processResponse(
         message,
@@ -3653,10 +3656,7 @@ export class SyncClient {
         return last;
       }
     }
-    throw new ClientSyncError(
-      'sync.invalid_request',
-      'sync did not reach idle within the round budget',
-    );
+    throw invalidRequest('sync did not reach idle within the round budget');
   }
 
   /**
@@ -3762,10 +3762,7 @@ export class SyncClient {
     this.#requireActive();
     if (this.#realtimePolicy === 'off') {
       return Promise.reject(
-        new ClientSyncError(
-          'sync.invalid_request',
-          "realtimePolicy is 'off'; realtime connect is refused",
-        ),
+        invalidRequest("realtimePolicy is 'off'; realtime connect is refused"),
       );
     }
     if (this.#socket !== undefined) return Promise.resolve();
@@ -3797,10 +3794,7 @@ export class SyncClient {
   async #connectRealtime(generation: number): Promise<void> {
     const connector = this.#config.realtime;
     if (connector === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
-        'no realtime connector configured',
-      );
+      throw invalidRequest('no realtime connector configured');
     }
     let openedSocket: RealtimeSocket | undefined;
     try {
@@ -3886,8 +3880,7 @@ export class SyncClient {
       } catch (error) {
         this.#pendingRound = undefined;
         round.reject(
-          new ClientSyncError(
-            'sync.invalid_request',
+          invalidRequest(
             `malformed round response stream (§8.7): ${error instanceof Error ? error.message : String(error)}`,
           ),
         );
@@ -3897,10 +3890,7 @@ export class SyncClient {
       this.#pendingRound = undefined;
       if (done.excess > 0) {
         round.reject(
-          new ClientSyncError(
-            'sync.invalid_request',
-            'response bytes past END of the round stream (§8.7)',
-          ),
+          invalidRequest('response bytes past END of the round stream (§8.7)'),
         );
         return;
       }
@@ -4064,7 +4054,7 @@ export class SyncClient {
 
     const header = message.frames[0];
     if (header?.type !== 'RESP_HEADER') {
-      throw new ClientSyncError('sync.invalid_request', 'missing RESP_HEADER');
+      throw invalidRequest('missing RESP_HEADER');
     }
     if (
       message.wireVersion < 2 ||
@@ -4291,8 +4281,7 @@ export class SyncClient {
               frame.mediaType === 'sqlite' &&
               (this.#acceptMask() & ACCEPT_SQLITE) === 0
             ) {
-              throw new ClientSyncError(
-                'sync.invalid_request',
+              throw invalidRequest(
                 'SEGMENT_REF mediaType sqlite was not advertised in accept (§4.2)',
               );
             }
@@ -4305,8 +4294,7 @@ export class SyncClient {
                 frame.rowCursor !== undefined ||
                 frame.nextRowCursor !== undefined
               ) {
-                throw new ClientSyncError(
-                  'sync.invalid_request',
+                throw invalidRequest(
                   'sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)',
                 );
               }
@@ -4570,6 +4558,12 @@ export class SyncClient {
     // validator-rejected updates even when the server emitted no new COMMIT;
     // later pending overlays are then replayed with rebased before-images.
     this.#db.transaction(() => {
+      if (this.#retainFailedCommits)
+        retainFailedRows(
+          this.#db,
+          commit,
+          listOutboxBeforeImages(this.#db, commit.clientCommitId),
+        );
       this.#rollbackFailedCommit(commit, batch);
     });
     batch.status();
@@ -4769,8 +4763,7 @@ export class SyncClient {
   ): Promise<Uint8Array> {
     const downloader = this.#config.segments;
     if (downloader === undefined) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         'received SEGMENT_REF but no segment downloader is configured',
       );
     }
@@ -4798,8 +4791,7 @@ export class SyncClient {
         fetchUrl === undefined ||
         (this.#acceptMask() & ACCEPT_SIGNED_URLS) === 0
       ) {
-        throw new ClientSyncError(
-          'sync.invalid_request',
+        throw invalidRequest(
           'SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)',
         );
       }
@@ -4829,8 +4821,7 @@ export class SyncClient {
     onProgress(bytes.byteLength);
     const hash = await sha256Hex(bytes);
     if (`sha256:${hash}` !== frame.segmentId) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
+      throw invalidRequest(
         `segment ${frame.segmentId} failed content-address verification (§5.1)`,
         true,
       );
@@ -4912,6 +4903,22 @@ export class SyncClient {
         Object.keys(lastEffective).length > 0
       ) {
         try {
+          restoreFailedBases(this.#db, this.#schema);
+          const droppedRetained = dropFailedRows(
+            this.#db,
+            (name, values) =>
+              name === table.name &&
+              Object.entries(lastEffective).every(([variable, allowed]) =>
+                allowed.includes(
+                  String(values[table.scopeColumnByVariable.get(variable)!]),
+                ),
+              ),
+          );
+          for (const commit of droppedRetained) {
+            for (const operation of commit.operations)
+              batch.table(operation.table);
+            batch.outcomes();
+          }
           deleteScopedRows(this.#db, table, lastEffective);
           batch.scopeMap(table, lastEffective);
           const pendingById = new Map(
@@ -5055,7 +5062,7 @@ export class SyncClient {
     const values = table.columns.map((column) =>
       jsonToRowValue(image.values?.[column.name] ?? null),
     );
-    upsertLocalRow(this.#db, table, values, image.syncVersion);
+    upsertLocalRow(this.#db, table, values, image.syncVersion, false);
   }
 
   #legacyUndoOptimisticRows(
@@ -5132,7 +5139,7 @@ export class SyncClient {
           : this.#recordStoredRowScopes(batch, table, op.rowId);
       if (op.op === 'delete') {
         if (batch !== undefined && !precise) batch.table(op.table);
-        deleteLocalRow(this.#db, table, op.rowId);
+        deleteLocalRow(this.#db, table, op.rowId, false);
         continue;
       }
       // §7.1 overlay: apply the operation's PRESENT columns over the current
@@ -5173,19 +5180,23 @@ export class SyncClient {
         local === undefined
           ? OPTIMISTIC_VERSION
           : (local[SYNC_VERSION_COLUMN] as number);
-      upsertLocalRow(this.#db, table, values, version);
+      upsertLocalRow(this.#db, table, values, version, false);
     }
   }
 
   /** Re-apply every pending outbox commit on top of server state (§7.1). */
   #replayOutbox(): void {
-    const pending = listOutbox(this.#db);
+    const pending = [
+      ...failedOverlayCommits(this.#db),
+      ...listOutbox(this.#db),
+    ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
     if (pending.length === 0) return;
     this.#applyBatch((batch) => {
       this.#db.transaction(() => {
-        for (const commit of pending) {
+        restoreFailedBases(this.#db, this.#schema);
+        restoreFailedBases(this.#db, this.#schema, true);
+        for (const commit of pending)
           this.#applyOperationsLocally(commit.operations, batch);
-        }
       });
     });
   }
@@ -5210,10 +5221,7 @@ export class SyncClient {
 
   #requireStarted(): void {
     if (!this.#started) {
-      throw new ClientSyncError(
-        'sync.invalid_request',
-        'SyncClient.start() has not completed',
-      );
+      throw invalidRequest('SyncClient.start() has not completed');
     }
   }
 
@@ -5227,3 +5235,9 @@ export class SyncClient {
     }
   }
 }
+
+function requireRowId(value: unknown): string {
+  if (typeof value !== 'string' || !value.length)
+    throw invalidRequest('a mutation requires a non-empty string primary key');
+  return value;
+}