@syncular/client 0.30.10 → 0.30.12

package/dist/client.js

@@ -1,4 +1,5 @@
-import { dropFailedRows, failedOverlayCommits, retainFailedRows, restoreFailedBases, } from './failed-overlay.js';
+import { RETAINED_ROWS } from './failed-overlay.js';
+import { dropFailedRows, failedOverlayCommits, retainFailedRows, restoreFailedBases, uniqueConflicts, } from './failed-overlay.js';
 import { ProgressEmitter, } from './progress.js';
 /**
  * SyncClient implements the client side of SPEC.md §§3–8.
@@ -11,7 +12,7 @@ import { ProgressEmitter, } from './progress.js';
  */
 import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encodeMessage, encodePresencePublish, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
 import { EncryptError } from '@syncular/core';
-import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
+import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
 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';
@@ -25,8 +26,8 @@ import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encod
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
 import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
-import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
-import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
+import { compileClientSchema, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
+import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, saveSubscriptionScopeSchema, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
 /** Stable client-local error while protected operations are preflight-gated. */
 export const SECURITY_PREFLIGHT_REQUIRED_CODE = 'client.security_preflight_required';
@@ -221,7 +222,7 @@ export class SyncClient {
     #preflightBarrier;
     constructor(config) {
         if (config.securityPreflight === true && config.encryption !== undefined) {
-            throw invalidRequest('securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight');
+            throw invalidRequest('securityPreflight and encryption are mutually exclusive; activateSecurity installs keys');
         }
         this.#retainFailedCommits = config.retainFailedCommits === true;
         this.#db = config.database;
@@ -287,7 +288,7 @@ export class SyncClient {
             persisted !== this.#config.clientId) {
             await this.#lease.release();
             this.#lease = undefined;
-            throw new ClientSyncError('client.identity_mismatch', `this client database belongs to ${JSON.stringify(persisted)}; refusing to rebind it to ${JSON.stringify(this.#config.clientId)}`);
+            throw new ClientSyncError('client.identity_mismatch', `database clientId ${JSON.stringify(persisted)} differs from ${JSON.stringify(this.#config.clientId)}`);
         }
         this.#clientId = persisted ?? this.#config.clientId ?? crypto.randomUUID();
         if (persisted === undefined) {
@@ -309,7 +310,7 @@ export class SyncClient {
         this.#reconcilePreviousVersionAtBoot();
         // A registration remains app intent only while its table exists in the
         // running schema. Removed-table registrations would poison every pull.
-        const subscriptions = pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), new Set(this.#schema.tables.keys()));
+        const subscriptions = pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), this.#schema);
         this.#started = true;
         // A persisted active subscription needs one catch-up round on every open:
         // realtime only covers changes after the socket connects, and an
@@ -319,6 +320,7 @@ export class SyncClient {
         // an application-issued sync() call.
         const startupWork = this.#schemaFloor === undefined &&
             (countOutbox(this.#db) > 0 ||
+                this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
                 loadPendingEvictions(this.#db).length > 0 ||
                 subscriptions.some((sub) => sub.status === 'active'));
         if (startupWork && this.#securityLifecycle === 'active') {
@@ -355,6 +357,7 @@ export class SyncClient {
                 ensureLocalSyncedSchema(this.#db, this.#schema);
                 setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
                 setLocalSchemaDescriptor(this.#db, this.#schema);
+                saveSubscriptionScopeSchema(this.#db, this.#schema);
             });
             return;
         }
@@ -366,6 +369,7 @@ export class SyncClient {
             this.#db.transaction(() => {
                 ensureLocalSyncedSchema(this.#db, this.#schema);
                 setLocalSchemaDescriptor(this.#db, this.#schema);
+                saveSubscriptionScopeSchema(this.#db, this.#schema);
             });
             return;
         }
@@ -393,10 +397,13 @@ export class SyncClient {
                 if (this.#previousVersion !== undefined) {
                     writePreviousVersionAudit(this.#db, buildPreviousVersionAudit(this.#schema, listOutbox(this.#db), previousVersion, this.#schema.version, this.#now()));
                 }
+                pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), this.#schema, true);
+                this.#discardAcknowledgedRows();
                 dropAndRecreateSyncedTables(this.#db, this.#schema);
                 resetSubscriptionsForBump(this.#db);
                 setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
                 setLocalSchemaDescriptor(this.#db, this.#schema);
+                saveSubscriptionScopeSchema(this.#db, this.#schema);
             });
             // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
             for (const table of this.#schema.tables.values())
@@ -473,6 +480,7 @@ export class SyncClient {
         this.#sweepPreviousVersionContainer();
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
+                this.#discardAcknowledgedRows();
                 dropAndRecreateSyncedTables(this.#db, this.#schema);
                 resetSubscriptionsForBump(this.#db);
                 setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
@@ -709,13 +717,13 @@ export class SyncClient {
                     previous.sqliteCode !== sqliteCode ||
                     previous.tables.join('\0') !== tables.join('\0')) {
                     this.#queryFailures.delete(owner.id);
-                    this.#queryFailures.set(owner.id, {
+                    this.#queryFailures.set(owner.id, definedObject({
                         id: owner.id,
                         tables,
                         code,
-                        ...(sqliteCode !== undefined ? { sqliteCode } : {}),
+                        sqliteCode: sqliteCode,
                         atMs: this.#now(),
-                    });
+                    }));
                     for (const id of this.#queryFailures.keys()) {
                         if (this.#queryFailures.size <= MAX_DIAGNOSTIC_QUERY_FAILURES)
                             break;
@@ -1036,22 +1044,18 @@ export class SyncClient {
             }
             return a.id.localeCompare(b.id);
         });
-        return {
+        return definedObject({
             version: CLIENT_DIAGNOSTICS_VERSION,
             capturedAtMs,
-            host: {
+            host: definedObject({
                 kind: 'direct',
                 role: 'single',
                 connectivity,
                 realtime: this.#realtimeState,
                 realtimePolicy: this.#realtimePolicy,
-                ...(this.#realtimeReasonCode !== undefined
-                    ? { realtimeReasonCode: this.#realtimeReasonCode }
-                    : {}),
-                ...(this.#realtimeRetryDelayMs !== undefined
-                    ? { realtimeRetryDelayMs: this.#realtimeRetryDelayMs }
-                    : {}),
-            },
+                realtimeReasonCode: this.#realtimeReasonCode,
+                realtimeRetryDelayMs: this.#realtimeRetryDelayMs,
+            }),
             securityLifecycle: this.#securityLifecycle,
             schema: {
                 currentVersion: this.#config.schema.version,
@@ -1071,24 +1075,20 @@ export class SyncClient {
             lease: leaseState,
             subscriptions: allSubscriptions.slice(0, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS),
             subscriptionsTruncated: allSubscriptions.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
-            ...(this.#lastRound !== undefined ? { lastRound: this.#lastRound } : {}),
-            ...(this.#lastChange !== undefined
-                ? { lastChange: this.#lastChange }
-                : {}),
+            lastRound: this.#lastRound,
+            lastChange: this.#lastChange,
             storage: this.#diagnosticStorage(),
             queryFailures: [...this.#queryFailures.values()],
-        };
+        });
     }
     #diagnosticLease(nowMs) {
         const lease = this.#leaseState;
         if (lease?.errorCode !== undefined) {
-            return {
+            return definedObject({
                 state: 'stopped',
                 errorCode: this.#diagnosticCode(lease.errorCode),
-                ...(lease.expiresAtMs !== undefined
-                    ? { expiresAtMs: lease.expiresAtMs }
-                    : {}),
-            };
+                expiresAtMs: lease.expiresAtMs,
+            });
         }
         if (lease?.expiresAtMs === undefined)
             return { state: 'none' };
@@ -1101,12 +1101,10 @@ export class SyncClient {
         try {
             const pageCount = Number(this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0);
             const pageSize = Number(this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0);
-            const outboxBytes = Number(this.#db.query('SELECT COALESCE(SUM(LENGTH(operations)), 0) AS bytes FROM _syncular_outbox')[0]?.bytes ?? 0);
-            const outcome = this.#db.query(`SELECT COUNT(*) AS entries,
-                COALESCE(SUM(LENGTH(results) + COALESCE(LENGTH(operations), 0)), 0) AS bytes
-           FROM _syncular_commit_outcomes`)[0];
+            const outboxBytes = Number(this.#db.query('SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM _syncular_outbox')[0]?.bytes ?? 0);
+            const outcome = this.#db.query('SELECT COUNT(*)AS entries,COALESCE(SUM(LENGTH(results)+ COALESCE(LENGTH(operations),0)),0)AS bytes FROM _syncular_commit_outcomes')[0];
             const blobBytes = this.#hasBlobs
-                ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length), 0) AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
+                ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length),0)AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
                 : 0;
             const pressure = this.#config.blobCacheMaxBytes !== undefined &&
                 blobBytes > this.#config.blobCacheMaxBytes;
@@ -1185,7 +1183,7 @@ export class SyncClient {
                 try {
                     result = fn(batch);
                     if (this.#db
-                        .query('SELECT DISTINCT tbl FROM _syncular_failed_rows')
+                        .query(`SELECT DISTINCT tbl FROM ${RETAINED_ROWS} WHERE commit_seq IS NULL`)
                         .some((row) => batch.hasTable(String(row.tbl))))
                         batch.outcomes();
                     if (batch.touched) {
@@ -1460,7 +1458,7 @@ export class SyncClient {
         const priorRejections = this.#rejections;
         return this.#applyBatch((batch) => {
             restoreFailedBases(this.#db, this.#schema);
-            this.#db.exec('DELETE FROM _syncular_failed_rows WHERE commit_id = ?', [
+            this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [
                 input.clientCommitId,
             ]);
             const resolved = persistCommitOutcomeResolution(this.#db, input, this.#now());
@@ -1575,18 +1573,18 @@ export class SyncClient {
                     canonicalScopeJson(input.scopes) &&
                 existing.params === input.params;
             if (!sameIntent) {
-                throw new ClientSyncError('client.subscription_intent_mismatch', 'subscribe: the subscription id is already registered for a different table, scopes, or params');
+                throw new ClientSyncError('client.subscription_intent_mismatch', 'subscription id already names different table, scopes, or params');
             }
             return;
         }
-        saveSubscription(this.#db, {
+        saveSubscription(this.#db, definedObject({
             id: input.id,
             table: input.table,
             scopes: input.scopes,
-            ...(input.params !== undefined ? { params: input.params } : {}),
+            params: input.params,
             cursor: -1,
             status: 'active',
-        });
+        }));
         this.#setSyncNeeded(true);
         this.#emitSyncIntent({ kind: 'interactive' });
         this.#emitDiagnostics();
@@ -1622,7 +1620,7 @@ export class SyncClient {
         this.#requireActive();
         const table = this.#table(base.table);
         if (!table.scopeColumnByVariable.has(base.variable)) {
-            throw invalidRequest(`setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`);
+            throw invalidRequest(`${base.table}: unknown scope variable ${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
@@ -1644,14 +1642,14 @@ export class SyncClient {
                         // Re-entry cancels any deferred eviction for this sub id.
                         deletePendingEviction(this.#db, subId);
                         insertWindowUnit(this.#db, baseKey, unit, subId);
-                        saveSubscription(this.#db, {
+                        saveSubscription(this.#db, definedObject({
                             id: subId,
                             table: base.table,
                             scopes: unitScopes(base, unit),
-                            ...(base.params !== undefined ? { params: base.params } : {}),
+                            params: base.params,
                             cursor: -1,
                             status: 'active',
-                        });
+                        }));
                     });
                     this.#needsPull = true;
                     batch.window(baseKey, base.table, unit);
@@ -1809,14 +1807,12 @@ export class SyncClient {
         const operations = mutations.map((mutation) => {
             const table = this.#table(mutation.table);
             if (mutation.op === 'delete') {
-                return {
+                return definedObject({
                     table: mutation.table,
                     rowId: mutation.rowId,
                     op: 'delete',
-                    ...(mutation.baseVersion !== undefined
-                        ? { baseVersion: mutation.baseVersion }
-                        : {}),
-                };
+                    baseVersion: mutation.baseVersion,
+                });
             }
             const json = {};
             if (mutation.op === 'patch') {
@@ -1828,7 +1824,7 @@ export class SyncClient {
                 const scopeColumns = new Set(table.scopeColumnByVariable.values());
                 const pkColumn = table.columns[table.primaryKeyIndex];
                 const pkValue = requireRowId(normalized.get(pkColumn.name));
-                const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [pkValue])[0];
+                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) {
@@ -1868,15 +1864,13 @@ export class SyncClient {
                 });
             }
             const pkValue = requireRowId(json[table.primaryKey]);
-            return {
+            return definedObject({
                 table: mutation.table,
                 rowId: pkValue,
                 op: 'upsert',
-                ...(mutation.baseVersion !== undefined
-                    ? { baseVersion: mutation.baseVersion }
-                    : {}),
+                baseVersion: mutation.baseVersion,
                 values: json,
-            };
+            });
         });
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
@@ -1900,10 +1894,7 @@ export class SyncClient {
                         catch {
                             continue;
                         }
-                        this.#db.exec(`INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id, blob_id)
-               SELECT ?, ? WHERE EXISTS (
-                 SELECT 1 FROM _syncular_blobs WHERE blob_id = ?
-               )`, [clientCommitId, blobId, blobId]);
+                        this.#db.exec('INSERT OR IGNORE INTO _syncular_blob_commit_refs(commit_id,blob_id)SELECT ?,? WHERE EXISTS(SELECT 1 FROM _syncular_blobs WHERE blob_id=?)', [clientCommitId, blobId, blobId]);
                     }
                 }
                 try {
@@ -1990,17 +1981,13 @@ export class SyncClient {
         // in the running schema), so purge drops it as a fixed step, before any
         // mirror row is touched and unconditionally.
         this.#dropPreviousVersion();
-        const rejectionCount = this.#rejections.length;
+        const priorRejections = [...this.#rejections];
+        const priorConflicts = [...this.#conflicts];
         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();
-                }
+                this.#dropRetainedRows(batch, (table, values) => (targetsByTable.get(table) ?? []).some((target) => target.selectors.every((selector) => selector.values.includes(String(values[selector.column])))));
                 // 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
@@ -2053,7 +2040,7 @@ export class SyncClient {
                     batch.table(tableName);
                     for (let offset = 0; offset < values.length; offset += 400) {
                         const chunk = values.slice(offset, offset + 400);
-                        this.#db.exec(`DELETE FROM ${quoteIdent(tableName)} WHERE ${quoteIdent(table.primaryKey)} IN (${chunk.map(() => '?').join(', ')})`, chunk);
+                        this.#db.exec(`DELETE FROM ${quoteIdent(tableName)} WHERE ${quoteIdent(table.primaryKey)} IN(${chunk.map(() => '?').join(', ')})`, chunk);
                     }
                 }
                 if (doomed.length > 0) {
@@ -2096,7 +2083,8 @@ export class SyncClient {
         catch (error) {
             // SQLite rolls back through #applyBatch; mirror that rollback for the
             // in-memory rejection cache before surfacing the storage failure.
-            this.#rejections.length = rejectionCount;
+            this.#rejections = priorRejections;
+            this.#conflicts = priorConflicts;
             throw error;
         }
     }
@@ -2135,6 +2123,7 @@ export class SyncClient {
                 this.#upgrading = true;
                 this.#needsPull = true;
                 batch.status();
+                this.#discardAcknowledgedRows();
                 dropAndRecreateSyncedTables(this.#db, this.#schema);
                 resetSubscriptionsForBump(this.#db);
                 for (const table of this.#schema.tables.values()) {
@@ -2186,7 +2175,7 @@ export class SyncClient {
                 clauses.push(`${quoteIdent(selector.column)} IN (${selector.values.map(() => '?').join(', ')})`);
                 params.push(...selector.values);
             }
-            for (const row of this.#db.query(`SELECT CAST(${quoteIdent(target.table.primaryKey)} AS TEXT) AS id FROM ${quoteIdent(target.table.name)} WHERE ${clauses.join(' AND ')}`, params)) {
+            for (const row of this.#db.query(`SELECT CAST(${quoteIdent(target.table.primaryKey)} AS TEXT)AS id FROM ${quoteIdent(target.table.name)} WHERE ${clauses.join(' AND ')}`, params)) {
                 if (typeof row.id === 'string')
                     ids.add(row.id);
             }
@@ -2228,7 +2217,7 @@ export class SyncClient {
     async #encodeOutboxForPush() {
         // Pin before the first encryption await: mutations can append while a
         // round is encoding, and belong to the next request.
-        const bounds = this.#db.query('SELECT COUNT(*) AS count, MAX(seq) AS last_seq FROM _syncular_outbox')[0];
+        const bounds = this.#db.query('SELECT COUNT(*)AS count,MAX(seq)AS last_seq FROM _syncular_outbox')[0];
         const pendingCount = bounds.count;
         const throughSeq = bounds.last_seq ?? 0;
         const pushFrames = [];
@@ -2258,7 +2247,7 @@ export class SyncClient {
                     const selector = this.#encryption?.keyIdColumns?.[table.name];
                     if (selector === undefined)
                         return undefined;
-                    const row = this.#db.query(`SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [rowId])[0];
+                    const row = this.#db.query(`SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [rowId])[0];
                     const value = row?.value;
                     return typeof value === 'string' && value.length > 0
                         ? value
@@ -2351,15 +2340,13 @@ export class SyncClient {
             const error = classifySqliteFailure(caught).error;
             const completedAtMs = this.#now();
             const code = error.code;
-            this.#progress.update({
+            this.#progress.update(definedObject({
                 state: 'failed',
                 errorCode: typeof code === 'string'
                     ? this.#diagnosticCode(code)
                     : 'client.unknown_failure',
-                ...(this.#roundRetryDelayMs !== undefined
-                    ? { retryDelayMs: this.#roundRetryDelayMs }
-                    : {}),
-            });
+                retryDelayMs: this.#roundRetryDelayMs,
+            }));
             this.#lastRound = {
                 status: 'failed',
                 startedAtMs,
@@ -2451,12 +2438,12 @@ export class SyncClient {
             const subs = loadSubscriptions(this.#db).filter((sub) => sub.status === 'active');
             const limits = this.#config.limits;
             const frames = [
-                {
+                definedObject({
                     type: 'REQ_HEADER',
                     clientId: this.#clientId,
                     schemaVersion: this.#schema.version,
-                    ...(logEpoch !== undefined ? { logEpoch } : {}),
-                },
+                    logEpoch: logEpoch,
+                }),
                 ...pushFrames,
                 {
                     type: 'PULL_HEADER',
@@ -2465,16 +2452,14 @@ export class SyncClient {
                     maxSnapshotPages: limits?.maxSnapshotPages ?? 0,
                     accept: this.#acceptMask(),
                 },
-                ...subs.map((sub) => ({
+                ...subs.map((sub) => definedObject({
                     type: 'SUBSCRIPTION',
                     id: sub.id,
                     table: sub.table,
                     scopes: sub.scopes,
-                    ...(sub.params !== undefined ? { params: sub.params } : {}),
+                    params: sub.params,
                     cursor: sub.cursor,
-                    ...(sub.bootstrapState !== undefined
-                        ? { bootstrapState: sub.bootstrapState }
-                        : {}),
+                    bootstrapState: sub.bootstrapState,
                 })),
             ];
             const requestBytes = encodeMessage({
@@ -2925,12 +2910,10 @@ export class SyncClient {
             // version this client sends. The §7.4.2 trigger-2 convergence runs
             // when the APP updates (recreating the client with a new generated
             // schema), which fires the boot-time §7.4.1 marker check instead.
-            const schemaFloor = {
+            const schemaFloor = definedObject({
                 requiredSchemaVersion: header.requiredSchemaVersion,
-                ...(header.latestSchemaVersion !== undefined
-                    ? { latestSchemaVersion: header.latestSchemaVersion }
-                    : {}),
-            };
+                latestSchemaVersion: header.latestSchemaVersion,
+            });
             this.#setSchemaFloor(schemaFloor);
             return {
                 ...summary,
@@ -2985,6 +2968,7 @@ export class SyncClient {
                                 index += 1;
                             }
                         }
+                        const previousNeedsPull = this.#needsPull;
                         const conflictCount = this.#conflicts.length;
                         const rejectionCount = this.#rejections.length;
                         let outboxCount = countOutbox(this.#db);
@@ -3001,9 +2985,10 @@ export class SyncClient {
                                 pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
                             }
                         }, () => this.#statusSnapshot(outboxCount), (cause) => {
+                            this.#needsPull = previousNeedsPull;
                             this.#conflicts.length = conflictCount;
                             this.#rejections.length = rejectionCount;
-                            const error = new ClientSyncError('client.outcome_persistence_failed', 'local commit outcome could not be persisted');
+                            const error = new ClientSyncError('client.outcome_persistence_failed', 'outcome persistence failed');
                             error.cause = cause;
                             throw error;
                         });
@@ -3214,6 +3199,10 @@ export class SyncClient {
         if (frame.status === 'applied' || frame.status === 'cached') {
             // §6.3: applied and cached both drain the outbox — cached means
             // "already applied, you may have missed the ack".
+            if (frame.commitSeq === undefined)
+                throw new ClientSyncError('client.invalid_host_response', 'ACK lacks a commit sequence');
+            retainFailedRows(this.#db, commit, listOutboxBeforeImages(this.#db, commit.clientCommitId), frame.commitSeq);
+            this.#setSyncNeeded(true);
             recordCommitOutcome(this.#db, {
                 clientCommitId: frame.clientCommitId,
                 status: frame.status,
@@ -3243,7 +3232,7 @@ export class SyncClient {
         for (const result of frame.results) {
             const operation = commit.operations[result.opIndex];
             if (result.status === 'conflict') {
-                const conflict = {
+                const conflict = definedObject({
                     clientCommitId: frame.clientCommitId,
                     opIndex: result.opIndex,
                     table: operation?.table ?? '',
@@ -3253,8 +3242,8 @@ export class SyncClient {
                     serverVersion: result.serverVersion,
                     serverRow: this.#decodeServerRow(operation?.table, result.serverRow),
                     conflictColumns: this.#decodeConflictColumns(operation?.table, result.conflictColumns),
-                    ...(operation !== undefined ? { operation } : {}),
-                };
+                    operation: operation,
+                });
                 this.#conflicts.push(conflict);
                 outcomeResults.push({ status: 'conflict', conflict });
                 batch.conflicts();
@@ -3262,15 +3251,15 @@ export class SyncClient {
             }
             else if (result.status === 'error') {
                 const details = rejectionDetails?.get(result.opIndex);
-                const rejection = {
+                const rejection = definedObject({
                     clientCommitId: frame.clientCommitId,
                     opIndex: result.opIndex,
                     code: result.code,
                     message: result.message,
                     retryable: result.retryable,
-                    ...(details !== undefined ? { details } : {}),
-                    ...(operation !== undefined ? { operation } : {}),
-                };
+                    details: details,
+                    operation: operation,
+                });
                 this.#rejections.push(rejection);
                 outcomeResults.push({ status: 'error', rejection });
                 batch.rejections();
@@ -3302,7 +3291,7 @@ export class SyncClient {
         return true;
     }
     #outboxCommitExists(clientCommitId) {
-        return (this.#db.query('SELECT 1 FROM _syncular_outbox WHERE client_commit_id = ? LIMIT 1', [clientCommitId]).length > 0);
+        return (this.#db.query('SELECT 1 FROM _syncular_outbox WHERE client_commit_id=? LIMIT 1', [clientCommitId]).length > 0);
     }
     #decodeServerRow(tableName, payload) {
         if (tableName === undefined)
@@ -3339,7 +3328,9 @@ export class SyncClient {
     async #applyCommit(frame, summary) {
         await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
             this.#recordCommitChanges(batch, frame);
-            return fn();
+            const result = fn();
+            this.#replayOutbox(result);
+            return result;
         }));
         summary.commitsApplied += 1;
     }
@@ -3367,9 +3358,7 @@ export class SyncClient {
         const mappings = [...table.scopeColumnByVariable].filter(([variable]) => table.scopePrefixByVariable.has(variable));
         if (mappings.length === 0)
             return false;
-        const row = this.#db.query(`SELECT ${mappings.map(([, column]) => quoteIdent(column)).join(', ')}
-         FROM ${quoteIdent(table.name)}
-        WHERE ${quoteIdent(table.primaryKey)} = ?`, [rowId])[0];
+        const row = this.#db.query(`SELECT ${mappings.map(([, column]) => quoteIdent(column)).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [rowId])[0];
         if (row === undefined)
             return false;
         let recorded = false;
@@ -3385,20 +3374,9 @@ export class SyncClient {
     }
     /** Whether a fresh-bootstrap clear would remove at least one local row. */
     #scopedRowsExist(table, effective) {
-        const entries = Object.entries(effective);
-        if (entries.length === 0)
-            return false;
-        const clauses = [];
-        const params = [];
-        for (const [variable, values] of entries) {
-            const column = table.scopeColumnByVariable.get(variable);
-            if (column === undefined || values.length === 0)
-                return false;
-            clauses.push(`${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`);
-            params.push(...values);
-        }
-        return (this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)}
-          WHERE ${clauses.join(' AND ')} LIMIT 1`, params).length > 0);
+        const scope = localScopePredicate(table, effective);
+        return (scope !== undefined &&
+            this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${scope.sql} LIMIT 1`, scope.params).length > 0);
     }
     /**
      * Apply a segment (rows or sqlite image); a §5.6/§3.3 fail-closed error
@@ -3419,18 +3397,16 @@ export class SyncClient {
                 error.code === 'sync.scope_revoked') {
                 const registered = getWindowUnitBySubId(this.#db, sub.id);
                 this.#applyBatch((batch) => {
-                    saveSubscription(this.#db, {
+                    saveSubscription(this.#db, definedObject({
                         id: sub.id,
                         table: sub.table,
                         scopes: sub.scopes,
-                        ...(sub.params !== undefined ? { params: sub.params } : {}),
+                        params: sub.params,
                         cursor: sub.cursor,
-                        ...(sub.effectiveScopes !== undefined
-                            ? { effectiveScopes: sub.effectiveScopes }
-                            : {}),
+                        effectiveScopes: sub.effectiveScopes,
                         status: 'failed',
                         reasonCode: 'sync.scope_revoked',
-                    });
+                    }));
                     if (registered !== undefined) {
                         batch.window(registered.baseKey, sub.table, registered.unit);
                     }
@@ -3474,7 +3450,7 @@ export class SyncClient {
             if (frame.urlExpiresAtMs !== undefined &&
                 frame.urlExpiresAtMs <= this.#now()) {
                 // §5.4: MUST NOT start a fetch at/past expiry.
-                throw new ClientSyncError('sync.segment_expired', `signed URL for segment ${frame.segmentId} expired before fetch — re-pull mints fresh descriptors (§5.4)`, true);
+                throw new ClientSyncError('sync.segment_expired', `segment download grant expired; pull again (§5.4)`, true);
             }
             bytes = await fetchUrl(frame.url, onProgress);
         }
@@ -3507,16 +3483,35 @@ export class SyncClient {
             const completed = wasPending && nextCursor >= 0 && bootstrapState === undefined;
             const registered = getWindowUnitBySubId(this.#db, sub.id);
             this.#applyBatch((batch) => {
-                saveSubscription(this.#db, {
+                saveSubscription(this.#db, definedObject({
                     id: sub.id,
                     table: sub.table,
                     scopes: sub.scopes,
-                    ...(sub.params !== undefined ? { params: sub.params } : {}),
+                    params: sub.params,
                     cursor: nextCursor,
-                    ...(bootstrapState !== undefined ? { bootstrapState } : {}),
+                    bootstrapState: bootstrapState,
                     effectiveScopes: start.effectiveScopes,
                     status: 'active',
-                });
+                }));
+                if (completed) {
+                    const table = this.#table(sub.table);
+                    const effective = start.effectiveScopes;
+                    const covered = this.#db
+                        .query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`, [sub.table, nextCursor])
+                        .filter((row) => [row.intent, row.base].some((json) => {
+                        if (json === null)
+                            return false;
+                        const values = JSON.parse(String(json));
+                        return matchesLocalScopes(table, effective, values);
+                    }));
+                    if (covered.length) {
+                        restoreFailedBases(this.#db, this.#schema);
+                        for (const row of covered)
+                            this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [sub.table, String(row.id), nextCursor]);
+                        batch.table(sub.table);
+                        this.#replayOutbox();
+                    }
+                }
                 if (completed && registered !== undefined) {
                     // A zero-row bootstrap is a window-domain transition, not a fake
                     // row/table change (SPEC §4.8 / §7.5).
@@ -3530,18 +3525,16 @@ export class SyncClient {
             // with cursor = -1 on the next pull. Staleness, not a purge.
             const registered = getWindowUnitBySubId(this.#db, sub.id);
             this.#applyBatch((batch) => {
-                saveSubscription(this.#db, {
+                saveSubscription(this.#db, definedObject({
                     id: sub.id,
                     table: sub.table,
                     scopes: sub.scopes,
-                    ...(sub.params !== undefined ? { params: sub.params } : {}),
+                    params: sub.params,
                     cursor: -1,
-                    ...(sub.effectiveScopes !== undefined
-                        ? { effectiveScopes: sub.effectiveScopes }
-                        : {}),
+                    effectiveScopes: sub.effectiveScopes,
                     status: 'active',
                     reasonCode: start.reasonCode,
-                });
+                }));
                 if (registered !== undefined) {
                     batch.window(registered.baseKey, sub.table, registered.unit);
                 }
@@ -3560,13 +3553,8 @@ 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();
-                    }
+                    this.#dropRetainedRows(batch, (name, values) => name === table.name &&
+                        matchesLocalScopes(table, lastEffective, values));
                     deleteScopedRows(this.#db, table, lastEffective);
                     batch.scopeMap(table, lastEffective);
                     const pendingById = new Map(listOutbox(this.#db).map((commit) => [
@@ -3616,18 +3604,16 @@ export class SyncClient {
                     }
                 }
             }
-            saveSubscription(this.#db, {
+            saveSubscription(this.#db, definedObject({
                 id: sub.id,
                 table: sub.table,
                 scopes: sub.scopes,
-                ...(sub.params !== undefined ? { params: sub.params } : {}),
+                params: sub.params,
                 cursor: nextCursor,
-                ...(lastEffective !== undefined
-                    ? { effectiveScopes: lastEffective }
-                    : {}),
+                effectiveScopes: lastEffective,
                 status: failed ? 'failed' : 'revoked',
                 reasonCode: start.reasonCode,
-            });
+            }));
             if (registered !== undefined) {
                 batch.window(registered.baseKey, sub.table, registered.unit);
             }
@@ -3646,7 +3632,7 @@ export class SyncClient {
             ...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];
+        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 = {};
@@ -3686,7 +3672,7 @@ export class SyncClient {
             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];
+            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);
@@ -3728,7 +3714,7 @@ export class SyncClient {
             this.#applyOperationsLocally(affectedOperations, batch);
         }
     }
-    #applyOperationsLocally(operations, batch) {
+    #applyOperationsLocally(operations, batch, replay = false) {
         for (const op of operations) {
             const table = this.#table(op.table);
             let precise = batch === undefined
@@ -3746,7 +3732,7 @@ export class SyncClient {
             // sync.row_missing, and the local mirror never invents a base.
             const opValues = op.values ?? {};
             const full = table.columns.every((column) => column.name in opValues);
-            const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [op.rowId])[0];
+            const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [op.rowId])[0];
             if (local === undefined && !full) {
                 if (batch !== undefined && !precise)
                     batch.table(op.table);
@@ -3777,23 +3763,47 @@ export class SyncClient {
             const version = local === undefined
                 ? OPTIMISTIC_VERSION
                 : local[SYNC_VERSION_COLUMN];
+            if (replay &&
+                table.indexes.some((index) => index.unique) &&
+                uniqueConflicts(this.#db, table, Object.fromEntries(table.columns.map((column, index) => [
+                    column.name,
+                    values[index] ?? null,
+                ]))).length)
+                continue;
             upsertLocalRow(this.#db, table, values, version, false);
         }
     }
     /** Re-apply every pending outbox commit on top of server state (§7.1). */
-    #replayOutbox() {
+    #discardAcknowledgedRows() {
+        this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
+    }
+    #dropRetainedRows(batch, matches) {
+        for (const commit of dropFailedRows(this.#db, matches)) {
+            batch.conflicts();
+            batch.rejections();
+            batch.outcomes();
+            this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== commit.clientCommitId);
+            this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== commit.clientCommitId);
+            for (const op of commit.operations)
+                batch.table(op.table);
+        }
+    }
+    #replayOutbox(rowKeys) {
+        const acknowledged = failedOverlayCommits(this.#db, true, rowKeys);
         const pending = [
-            ...failedOverlayCommits(this.#db),
-            ...listOutbox(this.#db),
+            ...failedOverlayCommits(this.#db, false, rowKeys),
+            ...listOutbox(this.#db, rowKeys),
         ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
-        if (pending.length === 0)
+        if (pending.length === 0 && acknowledged.length === 0)
             return;
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
-                restoreFailedBases(this.#db, this.#schema);
-                restoreFailedBases(this.#db, this.#schema, true);
-                for (const commit of pending)
-                    this.#applyOperationsLocally(commit.operations, batch);
+                restoreFailedBases(this.#db, this.#schema, false, rowKeys);
+                restoreFailedBases(this.#db, this.#schema, true, rowKeys);
+                for (const commit of [...acknowledged, ...pending])
+                    this.#applyOperationsLocally(rowKeys === undefined
+                        ? commit.operations
+                        : commit.operations.filter((op) => rowKeys.includes(JSON.stringify([op.table, op.rowId]))), batch, true);
             });
         });
     }
@@ -3806,22 +3816,29 @@ export class SyncClient {
     #table(name) {
         const table = this.#schema.tables.get(name);
         if (table === undefined) {
-            throw new ClientSyncError('sync.unknown_table', `unknown local table ${JSON.stringify(name)}`);
+            throw new ClientSyncError('sync.unknown_table', `unknown table ${name}`);
         }
         return table;
     }
     #requireStarted() {
         if (!this.#started) {
-            throw invalidRequest('SyncClient.start() has not completed');
+            throw invalidRequest('call SyncClient.start() first');
         }
     }
     #requireActive() {
         this.#requireStarted();
         if (this.#securityLifecycle === 'preflight') {
-            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data');
+            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'security preflight must complete before accessing protected data; call activateSecurity');
         }
     }
 }
+function definedObject(record) {
+    for (const key of Object.keys(record)) {
+        if (record[key] === undefined)
+            delete record[key];
+    }
+    return record;
+}
 function requireRowId(value) {
     if (typeof value !== 'string' || !value.length)
         throw invalidRequest('a mutation requires a non-empty string primary key');