@syncular/client 0.30.11 → 0.30.13

package/dist/client.js

@@ -1,3 +1,4 @@
+import { RETAINED_ROWS } from './failed-overlay.js';
 import { dropFailedRows, failedOverlayCommits, retainFailedRows, restoreFailedBases, uniqueConflicts, } from './failed-overlay.js';
 import { ProgressEmitter, } from './progress.js';
 /**
@@ -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,7 +26,7 @@ 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 { 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. */
@@ -132,6 +133,7 @@ export class SyncClient {
     /** RFC 0005 resolved capture budgets; undefined ⇒ feature off. */
     #previousVersion;
     #securityLifecycle;
+    #transportEnabled;
     #now;
     #outcomeRetentionMaxEntries;
     #retainFailedCommits;
@@ -220,8 +222,13 @@ export class SyncClient {
     #protectedAsync = new Set();
     #preflightBarrier;
     constructor(config) {
+        if (config.transportEnabled !== undefined &&
+            typeof config.transportEnabled !== 'boolean') {
+            throw invalidRequest('transportEnabled must be a boolean');
+        }
+        this.#transportEnabled = config.transportEnabled !== false;
         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 +294,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) {
@@ -319,6 +326,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') {
@@ -396,6 +404,7 @@ export class SyncClient {
                     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));
@@ -477,6 +486,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);
@@ -533,6 +543,8 @@ export class SyncClient {
         this.#syncIntentListeners.clear();
     }
     #emitSyncNeeded(reason) {
+        if (!this.#transportEnabled)
+            return;
         try {
             this.#config.onSyncNeeded?.(reason);
         }
@@ -549,6 +561,8 @@ export class SyncClient {
         }
     }
     #emitSyncIntent(intent) {
+        if (!this.#transportEnabled && intent.kind !== 'none')
+            return;
         try {
             this.#config.onSyncIntent?.(intent);
         }
@@ -564,6 +578,25 @@ export class SyncClient {
             }
         }
     }
+    /** Host-owned transport policy; the local replica remains available. */
+    setTransportEnabled(enabled) {
+        this.#requireStarted();
+        if (typeof enabled !== 'boolean')
+            throw invalidRequest('transportEnabled must be a boolean');
+        if (this.#transportEnabled === enabled)
+            return;
+        this.#transportEnabled = enabled;
+        if (!enabled && !this.#syncOutstanding)
+            this.disconnectRealtime();
+        this.#emitSyncIntent(enabled && this.#securityLifecycle === 'active'
+            ? { kind: 'interactive' }
+            : { kind: 'none' });
+        this.#emitDiagnostics();
+    }
+    #requireTransport() {
+        if (!this.#transportEnabled)
+            throw new ClientSyncError('sync.offline', 'transport gate is closed');
+    }
     /** Current fail-closed local-replica security state. */
     securityLifecycle() {
         return this.#securityLifecycle;
@@ -1024,12 +1057,14 @@ export class SyncClient {
         }
         const capturedAtMs = this.#now();
         const leaseState = this.#diagnosticLease(capturedAtMs);
-        const connectivity = this.#lastRound?.status === 'succeeded'
-            ? 'online'
-            : this.#lastRound?.status === 'failed' &&
-                this.#transportFailureCode(this.#lastRound.errorCode)
-                ? 'offline'
-                : 'unknown';
+        const connectivity = !this.#transportEnabled
+            ? 'offline'
+            : this.#lastRound?.status === 'succeeded'
+                ? 'online'
+                : this.#lastRound?.status === 'failed' &&
+                    this.#transportFailureCode(this.#lastRound.errorCode)
+                    ? 'offline'
+                    : 'unknown';
         const expectedOrder = new Map(expected.map((item, index) => [item.id, index]));
         const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
             const aExpected = expectedOrder.get(a.id);
@@ -1053,16 +1088,12 @@ export class SyncClient {
                 realtimeRetryDelayMs: this.#realtimeRetryDelayMs,
             }),
             securityLifecycle: this.#securityLifecycle,
-            schema: {
+            schema: definedObject({
                 currentVersion: this.#config.schema.version,
                 upgrading: this.#upgrading,
-                ...(this.#schemaFloor?.requiredSchemaVersion !== undefined
-                    ? { requiredVersion: this.#schemaFloor.requiredSchemaVersion }
-                    : {}),
-                ...(this.#schemaFloor?.latestSchemaVersion !== undefined
-                    ? { latestVersion: this.#schemaFloor.latestSchemaVersion }
-                    : {}),
-            },
+                requiredVersion: this.#schemaFloor?.requiredSchemaVersion,
+                latestVersion: this.#schemaFloor?.latestSchemaVersion,
+            }),
             replica: {
                 localRevision: getLocalRevision(this.#db).toString(),
                 syncNeeded: this.#needsPull,
@@ -1179,7 +1210,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) {
@@ -1242,7 +1273,11 @@ export class SyncClient {
         this.#requireActive();
         const task = Promise.resolve().then(fn);
         this.#protectedAsync.add(task);
-        void task.then(() => this.#protectedAsync.delete(task), () => this.#protectedAsync.delete(task));
+        const settled = () => {
+            if (this.#realtimeConnectPromise === task)
+                this.#realtimeConnectPromise = undefined;
+        };
+        void task.then(settled, settled);
         return task;
     }
     // -- blobs (§5.9) ---------------------------------------------------------
@@ -1268,14 +1303,12 @@ export class SyncClient {
             recordPendingUpload(this.#db, blobId, nowMs, options?.mediaType);
         });
         this.#enforceBlobCacheCap();
-        return {
+        return definedObject({
             blobId,
             byteLength: bytes.length,
-            ...(options?.mediaType !== undefined
-                ? { mediaType: options.mediaType }
-                : {}),
-            ...(options?.name !== undefined ? { name: options.name } : {}),
-        };
+            mediaType: options?.mediaType,
+            name: options?.name,
+        });
     }
     /** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
     blobRefString(ref) {
@@ -1305,6 +1338,7 @@ export class SyncClient {
         // presign configured) a signed url the client fetches directly. On a url
         // arm the client MUST NOT attach host auth and MUST NOT fall through:
         // failure => re-request, the caller's next fetchBlob mints a fresh url.
+        this.#requireTransport();
         const response = await transport.download(blobId);
         let bytes;
         if (response.kind === 'url') {
@@ -1346,6 +1380,7 @@ export class SyncClient {
     }
     /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
     flushBlobUploads() {
+        this.#requireTransport();
         return this.#runProtectedAsync(() => this.#flushBlobUploads());
     }
     async #flushBlobUploads() {
@@ -1439,12 +1474,9 @@ export class SyncClient {
         else if (replacement !== undefined) {
             throw invalidRequest('replacementClientCommitId is valid only for superseded outcomes');
         }
-        const allowed = (current.status === 'conflict' &&
+        const allowed = ((current.status === 'conflict' || current.status === 'rejected') &&
             (input.resolution === 'resolved_keep_server' ||
                 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) {
@@ -1454,7 +1486,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());
@@ -1525,6 +1557,7 @@ export class SyncClient {
      */
     setPresence(scopeKey, doc) {
         this.#requireActive();
+        this.#requireTransport();
         const socket = this.#socket;
         if (socket === undefined) {
             throw invalidRequest('setPresence requires a connected realtime socket (§8.6)');
@@ -1569,7 +1602,7 @@ 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;
         }
@@ -1616,7 +1649,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
@@ -1663,7 +1696,9 @@ export class SyncClient {
             }
         });
         const effects = {
-            sync: changed || widened ? { kind: 'interactive' } : { kind: 'none' },
+            sync: this.#transportEnabled && (changed || widened)
+                ? { kind: 'interactive' }
+                : { kind: 'none' },
         };
         if (effects.sync.kind === 'interactive') {
             this.#emitSyncIntent(effects.sync);
@@ -1918,7 +1953,9 @@ export class SyncClient {
     mutateCommand(mutations) {
         return {
             value: this.mutate(mutations),
-            effects: { sync: { kind: 'interactive' } },
+            effects: {
+                sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
+            },
         };
     }
     /**
@@ -1939,17 +1976,15 @@ export class SyncClient {
             throw invalidRequest(`table ${compiled.name}: patch cannot change the primary key`);
         }
         return this.#recordMutations([
-            {
+            definedObject({
                 table,
                 op: 'patch',
                 values: {
                     ...Object.fromEntries(normalized),
                     [pkColumn.name]: rowId,
                 },
-                ...(options?.baseVersion !== undefined
-                    ? { baseVersion: options.baseVersion }
-                    : {}),
-            },
+                baseVersion: options?.baseVersion,
+            }),
         ]);
     }
     /**
@@ -1983,16 +2018,7 @@ export class SyncClient {
             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) {
-                    batch.conflicts();
-                    batch.rejections();
-                    this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== commit.clientCommitId);
-                    this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== commit.clientCommitId);
-                    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
@@ -2128,6 +2154,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()) {
@@ -2191,7 +2218,9 @@ export class SyncClient {
     patchCommand(table, rowId, partial, options) {
         return {
             value: this.patch(table, rowId, partial, options),
-            effects: { sync: { kind: 'interactive' } },
+            effects: {
+                sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
+            },
         };
     }
     // -- lease state (§7.3.5) ---------------------------------------------------
@@ -2286,16 +2315,14 @@ export class SyncClient {
                 retainFailedRows(this.#db, commit, listOutboxBeforeImages(this.#db, commit.clientCommitId));
             this.#rollbackFailedCommit(commit, batch);
             this.#replayOutbox();
-            const rejection = {
+            const rejection = definedObject({
                 clientCommitId: commit.clientCommitId,
                 opIndex: 0,
                 code,
                 message,
                 retryable: false,
-                ...(commit.operations[0] !== undefined
-                    ? { operation: commit.operations[0] }
-                    : {}),
-            };
+                operation: commit.operations[0],
+            });
             this.#rejections.push(rejection);
             recordCommitOutcome(this.#db, {
                 clientCommitId: commit.clientCommitId,
@@ -2323,7 +2350,7 @@ export class SyncClient {
     sync() {
         this.#requireActive();
         if (this.#syncOutstanding) {
-            return Promise.reject(invalidRequest('sync() is already running — the core owns one loop (coalesce wake-ups)'));
+            return Promise.reject(invalidRequest('sync() is already running; coalesce wake-ups'));
         }
         this.#syncOutstanding = true;
         this.#beginDiagnosticsDeferral();
@@ -2365,6 +2392,8 @@ export class SyncClient {
         })
             .finally(() => {
             this.#syncOutstanding = false;
+            if (!this.#transportEnabled)
+                this.disconnectRealtime();
             this.#endDiagnosticsDeferral();
         });
     }
@@ -2397,6 +2426,7 @@ export class SyncClient {
             : 'client.unknown_failure';
     }
     async #runSync() {
+        this.#requireTransport();
         this.#roundRetryDelayMs = undefined;
         this.#progress.emit({
             attempt: ++this.#progressAttempt,
@@ -2426,7 +2456,7 @@ export class SyncClient {
             if (logEpoch !== undefined &&
                 this.#hasBlobs &&
                 this.#config.blobs !== undefined) {
-                await this.flushBlobUploads();
+                await this.#flushBlobUploads();
             }
             // §7.4.4: encode the outbox with the CURRENT codec; a commit that
             // cannot express itself under the new schema (a dropped column/table)
@@ -2542,6 +2572,8 @@ export class SyncClient {
         for (let round = 0; round < budget; round++) {
             const before = JSON.stringify(loadSubscriptions(this.#db).map((sub) => [sub.id, sub.bootstrapState]));
             last = await this.sync();
+            if (!this.#transportEnabled || last.schemaFloor !== undefined)
+                return last;
             if (maxRounds === undefined &&
                 last.segmentRowsApplied > 0 &&
                 last.bootstrapping.length > 0 &&
@@ -2551,8 +2583,6 @@ export class SyncClient {
                         sub.bootstrapState,
                     ])))
                 round = -1;
-            if (last.schemaFloor !== undefined)
-                return last;
             if (last.commitsApplied === 0 &&
                 last.segmentRowsApplied === 0 &&
                 last.bootstrapping.length === 0 &&
@@ -2644,6 +2674,7 @@ export class SyncClient {
     }
     connectRealtime() {
         this.#requireActive();
+        this.#requireTransport();
         if (this.#realtimePolicy === 'off') {
             return Promise.reject(invalidRequest("realtimePolicy is 'off'; realtime connect is refused"));
         }
@@ -2699,9 +2730,13 @@ export class SyncClient {
                 },
             });
             openedSocket = socket;
+            if (!this.#transportEnabled) {
+                socket.close();
+                this.#requireTransport();
+            }
             if (this.#securityLifecycle === 'preflight') {
                 socket.close();
-                throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
+                this.#requireActive();
             }
             if (generation !== this.#realtimeGeneration || !this.#started) {
                 socket.close();
@@ -2838,6 +2873,8 @@ export class SyncClient {
         }
     }
     async #handleRealtimeBinary(bytes) {
+        if (!this.#transportEnabled)
+            return;
         if (this.#syncing) {
             // Fast path: a pull is mid-flight; let it win and recover the gap
             // itself — re-pulling is idempotent, interleaved application is not
@@ -2866,7 +2903,8 @@ export class SyncClient {
         });
     }
     #sendAck(cursor) {
-        this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
+        if (this.#transportEnabled)
+            this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
     }
     /** Ack the highest cursor that is contiguously applied for every sub. */
     #ackAfterPull() {
@@ -2972,6 +3010,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);
@@ -2988,9 +3027,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;
                         });
@@ -3019,58 +3059,24 @@ export class SyncClient {
                             await this.#applyCommit(frame, summary);
                         }
                         break;
-                    case 'SEGMENT_INLINE': {
-                        if (section === undefined ||
-                            section.skip ||
-                            section.sub === undefined) {
-                            break;
-                        }
-                        const segment = decodeRowsSegment(frame.payload);
-                        this.#progress.update({
-                            phase: 'import',
-                            subscriptionId: section.sub.id,
-                            table: section.sub.table,
-                            segmentId: undefined,
-                            bytesReceived: frame.payload.byteLength,
-                            bytesTotal: frame.payload.byteLength,
-                            rowsProcessed: 0,
-                            rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
-                        });
-                        await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
-                            clearFirst,
-                            isCurrent: () => this.#localResetEpoch === resetEpoch,
-                            onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
-                            effective,
-                            transaction: (fn) => this.#applyBatch((batch) => {
-                                if (segment.blocks.some((block) => block.length > 0) ||
-                                    (clearFirst &&
-                                        this.#scopedRowsExist(table, effective))) {
-                                    batch.table(table.name);
-                                }
-                                const result = fn();
-                                this.#replayOutbox();
-                                return result;
-                            }),
-                        }, this.#encryption), section.fresh && !section.cleared);
-                        break;
-                    }
+                    case 'SEGMENT_INLINE':
                     case 'SEGMENT_REF': {
                         if (section === undefined ||
                             section.skip ||
-                            section.sub === undefined) {
+                            section.sub === undefined)
                             break;
-                        }
-                        // §4.2: a descriptor whose mediaType was not advertised is a
-                        // broken server — fail loud, never skip or guess.
-                        if (frame.mediaType === 'sqlite' &&
+                        if (frame.type === 'SEGMENT_REF' &&
+                            frame.mediaType === 'sqlite' &&
                             (this.#acceptMask() & ACCEPT_SQLITE) === 0) {
                             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' });
-                        if (frame.mediaType === 'sqlite') {
-                            // §5.3: images are whole-table — a paged descriptor is
-                            // invalid, and the image is always its table's first page.
+                        const bytes = frame.type === 'SEGMENT_REF'
+                            ? await this.#downloadSegment(frame, section.sub)
+                            : frame.payload;
+                        if (frame.type === 'SEGMENT_REF')
+                            this.#progress.update({ phase: 'import' });
+                        if (frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite') {
+                            // Images are whole-table; paged image descriptors are invalid.
                             if (frame.rowCursor !== undefined ||
                                 frame.nextRowCursor !== undefined) {
                                 throw invalidRequest('sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
@@ -3080,43 +3086,26 @@ export class SyncClient {
                                 rowCount: frame.rowCount,
                                 asOfCommitSeq: frame.asOfCommitSeq,
                                 scopeDigest: frame.scopeDigest,
-                            }, {
-                                clearFirst,
-                                isCurrent: () => this.#localResetEpoch === resetEpoch,
-                                onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
-                                effective,
-                                transaction: (fn) => this.#applyBatch((batch) => {
-                                    if (frame.rowCount > 0 ||
-                                        (clearFirst &&
-                                            this.#scopedRowsExist(table, effective))) {
-                                        batch.table(table.name);
-                                    }
-                                    const result = fn();
-                                    this.#replayOutbox();
-                                    return result;
-                                }),
-                            }), section.fresh && !section.cleared);
+                            }, this.#segmentApplyOptions(table, clearFirst, effective, frame.rowCount > 0, resetEpoch)), section.fresh && !section.cleared);
                         }
                         else {
                             const segment = decodeRowsSegment(bytes);
-                            await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
-                                clearFirst,
-                                isCurrent: () => this.#localResetEpoch === resetEpoch,
-                                onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
-                                effective,
-                                transaction: (fn) => this.#applyBatch((batch) => {
-                                    if (segment.blocks.some((block) => block.length > 0) ||
-                                        (clearFirst &&
-                                            this.#scopedRowsExist(table, effective))) {
-                                        batch.table(table.name);
-                                    }
-                                    const result = fn();
-                                    this.#replayOutbox();
-                                    return result;
-                                }),
-                            }, this.#encryption), section.fresh &&
+                            if (frame.type === 'SEGMENT_INLINE') {
+                                this.#progress.update({
+                                    phase: 'import',
+                                    subscriptionId: section.sub.id,
+                                    table: section.sub.table,
+                                    segmentId: undefined,
+                                    bytesReceived: bytes.byteLength,
+                                    bytesTotal: bytes.byteLength,
+                                    rowsProcessed: 0,
+                                    rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
+                                });
+                            }
+                            await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, this.#segmentApplyOptions(table, clearFirst, effective, segment.blocks.some((block) => block.length > 0), resetEpoch), this.#encryption), section.fresh &&
                                 !section.cleared &&
-                                frame.rowCursor === undefined);
+                                (frame.type === 'SEGMENT_INLINE' ||
+                                    frame.rowCursor === undefined));
                         }
                         break;
                     }
@@ -3201,6 +3190,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,
@@ -3327,10 +3320,7 @@ export class SyncClient {
         await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
             this.#recordCommitChanges(batch, frame);
             const result = fn();
-            if (this.#retainFailedCommits &&
-                this.#db.query('SELECT 1 FROM _syncular_failed_rows LIMIT 1')
-                    .length > 0)
-                this.#replayOutbox();
+            this.#replayOutbox(result);
             return result;
         }));
         summary.commitsApplied += 1;
@@ -3375,19 +3365,26 @@ 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);
+    }
+    /** Shared transaction, reset fence and progress for both segment formats. */
+    #segmentApplyOptions(table, clearFirst, effective, hasRows, resetEpoch) {
+        return {
+            clearFirst,
+            effective,
+            isCurrent: () => this.#localResetEpoch === resetEpoch,
+            onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
+            transaction: (fn) => this.#applyBatch((batch) => {
+                if (hasRows ||
+                    (clearFirst && this.#scopedRowsExist(table, effective)))
+                    batch.table(table.name);
+                const result = fn();
+                this.#replayOutbox();
+                return result;
+            }),
+        };
     }
     /**
      * Apply a segment (rows or sqlite image); a §5.6/§3.3 fail-closed error
@@ -3461,7 +3458,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);
         }
@@ -3504,6 +3501,25 @@ export class SyncClient {
                     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).
@@ -3545,17 +3561,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) {
-                        batch.conflicts();
-                        batch.rejections();
-                        this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== commit.clientCommitId);
-                        this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== commit.clientCommitId);
-                        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) => [
@@ -3775,19 +3782,36 @@ export class SyncClient {
         }
     }
     /** 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, true);
+                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);
             });
         });
     }
@@ -3800,19 +3824,19 @@ 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');
         }
     }
 }