@syncular/client 0.30.7 → 0.30.10

package/dist/client.js

@@ -1,3 +1,4 @@
+import { dropFailedRows, failedOverlayCommits, retainFailedRows, restoreFailedBases, } from './failed-overlay.js';
 import { ProgressEmitter, } from './progress.js';
 /**
  * SyncClient implements the client side of SPEC.md §§3–8.
@@ -14,7 +15,7 @@ import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow,
 import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
 import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
-import { ClientSyncError, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, } from './errors.js';
+import { ClientSyncError, invalidRequest, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
 import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
@@ -85,7 +86,7 @@ function boundedBudget(value, fallback, name) {
     if (value === undefined)
         return fallback;
     if (!Number.isSafeInteger(value) || value < 1) {
-        throw new ClientSyncError('sync.invalid_request', `previousVersionContext.${name} must be a positive safe integer`);
+        throw invalidRequest(`previousVersionContext.${name} must be a positive safe integer`);
     }
     return value;
 }
@@ -107,7 +108,7 @@ function resolvePreviousVersionLimit(limit) {
     if (limit === undefined)
         return 50;
     if (!Number.isFinite(limit) || limit < 1) {
-        throw new ClientSyncError('sync.invalid_request', 'previousVersionSnapshot limit must be a positive number');
+        throw invalidRequest('previousVersionSnapshot limit must be a positive number');
     }
     return Math.min(PREVIOUS_VERSION_MAX_LIMIT, Math.trunc(limit));
 }
@@ -133,6 +134,7 @@ export class SyncClient {
     #securityLifecycle;
     #now;
     #outcomeRetentionMaxEntries;
+    #retainFailedCommits;
     #started = false;
     #lease;
     #clientId = '';
@@ -219,18 +221,19 @@ export class SyncClient {
     #preflightBarrier;
     constructor(config) {
         if (config.securityPreflight === true && config.encryption !== undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight');
+            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';
         if (realtimePolicy !== 'required' &&
             realtimePolicy !== 'optional' &&
             realtimePolicy !== 'off') {
-            throw new ClientSyncError('sync.invalid_request', "realtimePolicy must be 'required', 'optional', or 'off'");
+            throw invalidRequest("realtimePolicy must be 'required', 'optional', or 'off'");
         }
         if (realtimePolicy === 'required' && config.realtime === undefined) {
-            throw new ClientSyncError('sync.invalid_request', "realtimePolicy 'required' needs a realtime connector");
+            throw invalidRequest("realtimePolicy 'required' needs a realtime connector");
         }
         this.#config = config;
         this.#realtimePolicy = realtimePolicy;
@@ -247,7 +250,7 @@ export class SyncClient {
         const outcomeRetentionMaxEntries = config.limits?.outcomeRetentionMaxEntries ?? 1_000;
         if (!Number.isSafeInteger(outcomeRetentionMaxEntries) ||
             outcomeRetentionMaxEntries < 1) {
-            throw new ClientSyncError('sync.invalid_request', 'outcomeRetentionMaxEntries must be a positive safe integer');
+            throw invalidRequest('outcomeRetentionMaxEntries must be a positive safe integer');
         }
         this.#outcomeRetentionMaxEntries = outcomeRetentionMaxEntries;
         // RFC 0005: the container needs a sibling database file. A host without
@@ -596,7 +599,7 @@ export class SyncClient {
     async activateSecurity(options = {}) {
         this.#requireStarted();
         if (this.#securityLifecycle === 'active') {
-            throw new ClientSyncError('sync.invalid_request', 'activateSecurity requires the client to be in security preflight');
+            throw invalidRequest('activateSecurity requires the client to be in security preflight');
         }
         await (this.#preflightBarrier ?? this.#opChain);
         this.#encryption = options.encryption;
@@ -767,7 +770,7 @@ export class SyncClient {
         }
         const table = record.tables.find((entry) => entry.name === spec.table);
         if (table === undefined) {
-            throw new ClientSyncError('sync.invalid_request', `previousVersionSnapshot names unknown previous table ${JSON.stringify(spec.table)}`);
+            throw invalidRequest(`previousVersionSnapshot names unknown previous table ${JSON.stringify(spec.table)}`);
         }
         const read = withPreviousVersionContainer(this.#db, (container) => readPreviousVersionRows(container, table, spec.rowIds?.map(String) ?? [], resolvePreviousVersionLimit(spec.limit)));
         if (read === undefined) {
@@ -960,7 +963,7 @@ export class SyncClient {
         this.#requireActive();
         const expected = request.expectedSubscriptions ?? [];
         if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
-            throw new ClientSyncError('sync.invalid_request', `diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`);
+            throw invalidRequest(`diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`);
         }
         const registered = loadSubscriptions(this.#db);
         const subscriptions = new Map();
@@ -993,7 +996,7 @@ export class SyncClient {
                 item.id.length === 0 ||
                 typeof item.table !== 'string' ||
                 item.table.length === 0) {
-                throw new ClientSyncError('sync.invalid_request', 'diagnosticsSnapshot expected subscriptions require non-empty id and table strings');
+                throw invalidRequest('diagnosticsSnapshot expected subscriptions require non-empty id and table strings');
             }
             const registeredSubscription = subscriptions.get(item.id);
             if (registeredSubscription !== undefined &&
@@ -1181,6 +1184,10 @@ 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) {
@@ -1258,7 +1265,7 @@ export class SyncClient {
     }
     async #uploadBlob(bytes, options) {
         if (this.#config.blobs === undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
+            throw invalidRequest('uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
         }
         const blobId = await computeBlobId(bytes);
         const nowMs = this.#now();
@@ -1298,7 +1305,7 @@ export class SyncClient {
             return cached;
         const transport = this.#config.blobs;
         if (transport === undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'fetchBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
+            throw invalidRequest('fetchBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
         }
         // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
         // presign configured) a signed url the client fetches directly. On a url
@@ -1308,7 +1315,7 @@ export class SyncClient {
         let bytes;
         if (response.kind === 'url') {
             if (transport.fetchUrl === undefined) {
-                throw new ClientSyncError('sync.invalid_request', 'blob download returned a url but the transport cannot fetch urls (§5.9.5)');
+                throw invalidRequest('blob download returned a url but the transport cannot fetch urls (§5.9.5)');
             }
             if (response.urlExpiresAtMs !== undefined &&
                 response.urlExpiresAtMs <= this.#now()) {
@@ -1325,14 +1332,14 @@ 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', `blob content address mismatch for ${blobId} (§5.9.5)`);
+            throw invalidRequest(`blob content address mismatch for ${blobId} (§5.9.5)`);
         }
         putCachedBlob(this.#db, blobId, bytes, this.#now());
         this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
         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;
     }
@@ -1416,7 +1423,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) {
@@ -1432,22 +1439,30 @@ export class SyncClient {
             if (replacement === undefined ||
                 replacement.length === 0 ||
                 replacement === input.clientCommitId) {
-                throw new ClientSyncError('sync.invalid_request', 'superseded outcomes require a distinct replacementClientCommitId');
+                throw invalidRequest('superseded outcomes require a distinct replacementClientCommitId');
             }
         }
         else if (replacement !== undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'replacementClientCommitId is valid only for superseded outcomes');
+            throw invalidRequest('replacementClientCommitId is valid only for superseded outcomes');
         }
         const allowed = (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', `resolution ${input.resolution} is invalid for ${current.status} outcome`);
+            throw invalidRequest(`resolution ${input.resolution} is invalid for ${current.status} outcome`);
         }
+        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());
             if (resolved === undefined) {
                 throw new ClientSyncError('sync.outcome_not_found', `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`);
@@ -1455,12 +1470,19 @@ export class SyncClient {
             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
@@ -1511,7 +1533,7 @@ export class SyncClient {
         this.#requireActive();
         const socket = this.#socket;
         if (socket === undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'setPresence requires a connected realtime socket (§8.6)');
+            throw invalidRequest('setPresence requires a connected realtime socket (§8.6)');
         }
         socket.send(encodePresencePublish(scopeKey, doc));
     }
@@ -1600,7 +1622,7 @@ export class SyncClient {
         this.#requireActive();
         const table = this.#table(base.table);
         if (!table.scopeColumnByVariable.has(base.variable)) {
-            throw new ClientSyncError('sync.invalid_request', `setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`);
+            throw invalidRequest(`setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`);
         }
         // Serialize the whole window edit: it spans an `await deriveSubId` between
         // db transactions, so without the chain a delta apply (or a concurrent
@@ -1761,7 +1783,10 @@ export class SyncClient {
      */
     #pinnedRowIds(table) {
         const pinned = new Set();
-        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);
@@ -1778,7 +1803,7 @@ export class SyncClient {
     mutate(mutations) {
         return this.#recordMutations(mutations);
     }
-    #recordMutations(mutations, partial = false) {
+    #recordMutations(mutations) {
         this.#requireActive();
         const clientCommitId = crypto.randomUUID();
         const operations = mutations.map((mutation) => {
@@ -1793,7 +1818,8 @@ export class SyncClient {
                         : {}),
                 };
             }
-            if (partial) {
+            const json = {};
+            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
@@ -1801,7 +1827,10 @@ export class SyncClient {
                 const normalized = normalizeRecordKeys(table, mutation.values);
                 const scopeColumns = new Set(table.scopeColumnByVariable.values());
                 const pkColumn = table.columns[table.primaryKeyIndex];
-                const json = {};
+                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;
@@ -1816,49 +1845,29 @@ 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)), rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
-                            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`);
+                        if (!Object.is(rowValueToJson(fromSqlValue(column, local[column.name] ?? null)), rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
+                            throw invalidRequest(`table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`);
                         }
                         continue;
                     }
                     const value = normalized.get(column.name);
                     if (value === undefined || value === null) {
                         if (!column.nullable) {
-                            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1)`);
+                            throw invalidRequest(`table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1)`);
                         }
                         json[column.name] = null;
                         continue;
                     }
                     json[column.name] = rowValueToJson(coerceSqlRepresentation(column, value));
                 }
-                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 = {};
-            table.columns.forEach((column, index) => {
-                json[column.name] = rowValueToJson(values[index] ?? null);
-            });
+            const pkValue = requireRowId(json[table.primaryKey]);
             return {
                 table: mutation.table,
                 rowId: pkValue,
@@ -1940,12 +1949,12 @@ 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', `table ${compiled.name}: patch cannot change the primary key`);
+            throw invalidRequest(`table ${compiled.name}: patch cannot change the primary key`);
         }
         return this.#recordMutations([
             {
                 table,
-                op: 'upsert',
+                op: 'patch',
                 values: {
                     ...Object.fromEntries(normalized),
                     [pkColumn.name]: rowId,
@@ -1954,7 +1963,7 @@ export class SyncClient {
                     ? { baseVersion: options.baseVersion }
                     : {}),
             },
-        ], true);
+        ]);
     }
     /**
      * Apply one host-authorized local security purge. The host must stop/gate
@@ -1973,7 +1982,7 @@ export class SyncClient {
         const appliedPlan = getMeta(this.#db, metaKey);
         if (appliedPlan !== undefined) {
             if (appliedPlan !== purge.canonicalPlan) {
-                throw new ClientSyncError('sync.invalid_request', `local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`);
+                throw invalidRequest(`local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`);
             }
             return { alreadyApplied: true, purgedRows: 0, droppedCommits: 0 };
         }
@@ -1985,6 +1994,13 @@ 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
@@ -2067,6 +2083,7 @@ export class SyncClient {
                     batch.rejections();
                     batch.outcomes();
                 }
+                this.#replayOutbox();
                 this.#deleteUnreferencedBlobs();
                 setMeta(this.#db, metaKey, purge.canonicalPlan);
                 return {
@@ -2107,7 +2124,7 @@ export class SyncClient {
             };
         }
         if (this.#schemaFloor !== undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'local rebootstrap cannot bypass an active schema-floor stop; update the application first');
+            throw invalidRequest('local rebootstrap cannot bypass an active schema-floor stop; update the application first');
         }
         const pending = listOutbox(this.#db);
         const resetSubscriptions = loadSubscriptions(this.#db).length;
@@ -2272,7 +2289,10 @@ export class SyncClient {
      */
     #dropIncompatibleCommit(commit, message, code = OUTBOX_INCOMPATIBLE_CODE) {
         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 = {
                 clientCommitId: commit.clientCommitId,
                 opIndex: 0,
@@ -2310,7 +2330,7 @@ export class SyncClient {
     sync() {
         this.#requireActive();
         if (this.#syncOutstanding) {
-            return Promise.reject(new ClientSyncError('sync.invalid_request', 'sync() is already running — the core owns one loop (coalesce wake-ups)'));
+            return Promise.reject(invalidRequest('sync() is already running — the core owns one loop (coalesce wake-ups)'));
         }
         this.#syncOutstanding = true;
         this.#beginDiagnosticsDeferral();
@@ -2465,7 +2485,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, outbox, subs, 'pull', resetEpoch);
             // §4.8 E1: the push half may have drained commits that pinned rows of
@@ -2553,7 +2573,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');
     }
     /**
      * One request/response round trip (§8.7): over the socket whenever it
@@ -2636,7 +2656,7 @@ export class SyncClient {
     connectRealtime() {
         this.#requireActive();
         if (this.#realtimePolicy === 'off') {
-            return Promise.reject(new ClientSyncError('sync.invalid_request', "realtimePolicy is 'off'; realtime connect is refused"));
+            return Promise.reject(invalidRequest("realtimePolicy is 'off'; realtime connect is refused"));
         }
         if (this.#socket !== undefined)
             return Promise.resolve();
@@ -2662,7 +2682,7 @@ export class SyncClient {
     async #connectRealtime(generation) {
         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;
         try {
@@ -2743,14 +2763,14 @@ export class SyncClient {
             }
             catch (error) {
                 this.#pendingRound = undefined;
-                round.reject(new ClientSyncError('sync.invalid_request', `malformed round response stream (§8.7): ${error instanceof Error ? error.message : String(error)}`));
+                round.reject(invalidRequest(`malformed round response stream (§8.7): ${error instanceof Error ? error.message : String(error)}`));
                 return;
             }
             if (done === undefined)
                 return;
             this.#pendingRound = undefined;
             if (done.excess > 0) {
-                round.reject(new ClientSyncError('sync.invalid_request', 'response bytes past END of the round stream (§8.7)'));
+                round.reject(invalidRequest('response bytes past END of the round stream (§8.7)'));
                 return;
             }
             round.resolve(done.message.slice());
@@ -2890,7 +2910,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 ||
             header.logEpoch === undefined ||
@@ -3057,7 +3077,7 @@ export class SyncClient {
                         // broken server — fail loud, never skip or guess.
                         if (frame.mediaType === 'sqlite' &&
                             (this.#acceptMask() & ACCEPT_SQLITE) === 0) {
-                            throw new ClientSyncError('sync.invalid_request', 'SEGMENT_REF mediaType sqlite was not advertised in accept (§4.2)');
+                            throw invalidRequest('SEGMENT_REF mediaType sqlite was not advertised in accept (§4.2)');
                         }
                         const bytes = await this.#downloadSegment(frame, section.sub);
                         this.#progress.update({ phase: 'import' });
@@ -3066,7 +3086,7 @@ export class SyncClient {
                             // invalid, and the image is always its table's first page.
                             if (frame.rowCursor !== undefined ||
                                 frame.nextRowCursor !== undefined) {
-                                throw new ClientSyncError('sync.invalid_request', 'sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
+                                throw invalidRequest('sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
                             }
                             await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applySqliteSegment(this.#db, this.#schema, table, bytes, {
                                 table: frame.table,
@@ -3273,6 +3293,8 @@ 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();
@@ -3423,7 +3445,7 @@ export class SyncClient {
     async #downloadSegment(frame, sub) {
         const downloader = this.#config.segments;
         if (downloader === undefined) {
-            throw new ClientSyncError('sync.invalid_request', 'received SEGMENT_REF but no segment downloader is configured');
+            throw invalidRequest('received SEGMENT_REF but no segment downloader is configured');
         }
         this.#progress.update({
             phase: 'download',
@@ -3447,7 +3469,7 @@ export class SyncClient {
             const fetchUrl = downloader.fetchUrl;
             if (fetchUrl === undefined ||
                 (this.#acceptMask() & ACCEPT_SIGNED_URLS) === 0) {
-                throw new ClientSyncError('sync.invalid_request', 'SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)');
+                throw invalidRequest('SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)');
             }
             if (frame.urlExpiresAtMs !== undefined &&
                 frame.urlExpiresAtMs <= this.#now()) {
@@ -3470,7 +3492,7 @@ export class SyncClient {
         onProgress(bytes.byteLength);
         const hash = await sha256Hex(bytes);
         if (`sha256:${hash}` !== frame.segmentId) {
-            throw new ClientSyncError('sync.invalid_request', `segment ${frame.segmentId} failed content-address verification (§5.1)`, true);
+            throw invalidRequest(`segment ${frame.segmentId} failed content-address verification (§5.1)`, true);
         }
         return bytes;
     }
@@ -3537,6 +3559,14 @@ export class SyncClient {
             if (lastEffective !== undefined &&
                 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(listOutbox(this.#db).map((commit) => [
@@ -3647,7 +3677,7 @@ export class SyncClient {
             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);
+        upsertLocalRow(this.#db, table, values, image.syncVersion, false);
     }
     #legacyUndoOptimisticRows(commit, batch) {
         for (const operation of commit.operations) {
@@ -3707,7 +3737,7 @@ export class SyncClient {
             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
@@ -3747,19 +3777,23 @@ export class SyncClient {
             const version = local === undefined
                 ? OPTIMISTIC_VERSION
                 : local[SYNC_VERSION_COLUMN];
-            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() {
-        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);
-                }
             });
         });
     }
@@ -3778,7 +3812,7 @@ export class SyncClient {
     }
     #requireStarted() {
         if (!this.#started) {
-            throw new ClientSyncError('sync.invalid_request', 'SyncClient.start() has not completed');
+            throw invalidRequest('SyncClient.start() has not completed');
         }
     }
     #requireActive() {
@@ -3788,3 +3822,8 @@ export class SyncClient {
         }
     }
 }
+function requireRowId(value) {
+    if (typeof value !== 'string' || !value.length)
+        throw invalidRequest('a mutation requires a non-empty string primary key');
+    return value;
+}

package/dist/errors.d.ts

@@ -25,6 +25,8 @@ export declare class ClientSyncError extends Error {
     readonly details: Readonly<Record<string, unknown>> | undefined;
     constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>);
 }
+/** Shared invalid-request construction for client validators and transport guards. */
+export declare function invalidRequest(message: string, retryable?: boolean): ClientSyncError;
 /**
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
  * for its required coverage. `code` is the attempt's static progress error

package/dist/errors.js

@@ -29,6 +29,10 @@ export class ClientSyncError extends Error {
         this.details = details;
     }
 }
+/** Shared invalid-request construction for client validators and transport guards. */
+export function invalidRequest(message, retryable = false) {
+    return new ClientSyncError('sync.invalid_request', message, retryable);
+}
 /**
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
  * for its required coverage. `code` is the attempt's static progress error

package/dist/failed-overlay.d.ts

@@ -0,0 +1,10 @@
+import type { ClientDatabase } from './database.js';
+import type { CompiledClientSchema, JsonRowValue } from './schema.js';
+import type { OutboxCommit, OutboxBeforeImage } from './outbox.js';
+/** Protected failure state. The server base advances independently of intent. */
+export declare function ensureFailedOverlaySchema(db: ClientDatabase): void;
+export declare function retainedBaseWrite(db: ClientDatabase, table: string, rowId: string, values?: Readonly<Record<string, JsonRowValue>>, version?: number): void;
+export declare function retainFailedRows(db: ClientDatabase, commit: OutboxCommit, images: readonly OutboxBeforeImage[]): void;
+export declare function restoreFailedBases(db: ClientDatabase, schema: CompiledClientSchema, absentIntent?: boolean): void;
+export declare function failedOverlayCommits(db: ClientDatabase): OutboxCommit[];
+export declare function dropFailedRows(db: ClientDatabase, matches: (table: string, values: Readonly<Record<string, JsonRowValue>>) => boolean): OutboxCommit[];