@syncular/client 0.30.11 → 0.30.13

package/src/client.ts

@@ -1,3 +1,4 @@
+import { RETAINED_ROWS } from './failed-overlay';
 import {
   dropFailedRows,
   failedOverlayCommits,
@@ -51,6 +52,7 @@ import {
   applySqliteSegment,
   deleteLocalRow,
   deleteScopedRows,
+  localScopePredicate,
   evictScopedRows,
   yieldToHost,
   upsertLocalRow,
@@ -196,6 +198,7 @@ import {
   type CompiledClientSchema,
   type CompiledClientTable,
   compileClientSchema,
+  matchesLocalScopes,
   dropAndRecreateSyncedTables,
   ensureLocalBookkeepingSchema,
   ensureLocalSyncedSchema,
@@ -346,6 +349,7 @@ export interface SyncClientLimits {
 }
 
 export interface SyncClientConfig {
+  readonly transportEnabled?: boolean;
   /** Keep rejected/conflicting local intent visible until explicit resolution. */
   readonly retainFailedCommits?: boolean;
   readonly database: ClientDatabase;
@@ -744,6 +748,7 @@ export class SyncClient {
   /** RFC 0005 resolved capture budgets; undefined ⇒ feature off. */
   readonly #previousVersion: PreviousVersionCaptureConfig | undefined;
   #securityLifecycle: SecurityLifecycle;
+  #transportEnabled: boolean;
   readonly #now: () => number;
   readonly #outcomeRetentionMaxEntries: number;
   readonly #retainFailedCommits: boolean;
@@ -835,9 +840,16 @@ export class SyncClient {
   #preflightBarrier: Promise<void> | undefined;
 
   constructor(config: SyncClientConfig) {
+    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',
+        'securityPreflight and encryption are mutually exclusive; activateSecurity installs keys',
       );
     }
     this.#retainFailedCommits = config.retainFailedCommits === true;
@@ -923,7 +935,7 @@ export class SyncClient {
       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)}`,
+        `database clientId ${JSON.stringify(persisted)} differs from ${JSON.stringify(this.#config.clientId)}`,
       );
     }
     this.#clientId = persisted ?? this.#config.clientId ?? crypto.randomUUID();
@@ -961,6 +973,9 @@ export class SyncClient {
     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') {
@@ -1060,6 +1075,7 @@ export class SyncClient {
           this.#schema,
           true,
         );
+        this.#discardAcknowledgedRows();
         dropAndRecreateSyncedTables(this.#db, this.#schema);
         resetSubscriptionsForBump(this.#db);
         setMeta(
@@ -1160,6 +1176,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);
@@ -1217,6 +1234,7 @@ export class SyncClient {
   }
 
   #emitSyncNeeded(reason: 'startup' | 'hello' | WakeReason): void {
+    if (!this.#transportEnabled) return;
     try {
       this.#config.onSyncNeeded?.(reason);
     } catch {
@@ -1232,6 +1250,7 @@ export class SyncClient {
   }
 
   #emitSyncIntent(intent: SyncIntent): void {
+    if (!this.#transportEnabled && intent.kind !== 'none') return;
     try {
       this.#config.onSyncIntent?.(intent);
     } catch {
@@ -1246,6 +1265,27 @@ export class SyncClient {
     }
   }
 
+  /** Host-owned transport policy; the local replica remains available. */
+  setTransportEnabled(enabled: boolean): void {
+    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(): void {
+    if (!this.#transportEnabled)
+      throw new ClientSyncError('sync.offline', 'transport gate is closed');
+  }
+
   /** Current fail-closed local-replica security state. */
   securityLifecycle(): SecurityLifecycle {
     return this.#securityLifecycle;
@@ -1791,8 +1831,9 @@ export class SyncClient {
     }
     const capturedAtMs = this.#now();
     const leaseState = this.#diagnosticLease(capturedAtMs);
-    const connectivity =
-      this.#lastRound?.status === 'succeeded'
+    const connectivity = !this.#transportEnabled
+      ? 'offline'
+      : this.#lastRound?.status === 'succeeded'
         ? 'online'
         : this.#lastRound?.status === 'failed' &&
             this.#transportFailureCode(this.#lastRound.errorCode)
@@ -1825,16 +1866,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,
@@ -1981,7 +2018,9 @@ export class SyncClient {
           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();
@@ -2048,10 +2087,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;
   }
 
@@ -2088,14 +2128,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. */
@@ -2129,6 +2167,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: Uint8Array;
     if (response.kind === 'url') {
@@ -2180,6 +2219,7 @@ export class SyncClient {
 
   /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
   flushBlobUploads(): Promise<void> {
+    this.#requireTransport();
     return this.#runProtectedAsync(() => this.#flushBlobUploads());
   }
 
@@ -2308,12 +2348,9 @@ export class SyncClient {
       );
     }
     const allowed =
-      (current.status === 'conflict' &&
+      ((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) {
@@ -2327,7 +2364,7 @@ export class SyncClient {
     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(
@@ -2416,6 +2453,7 @@ export class SyncClient {
    */
   setPresence(scopeKey: string, doc: Record<string, unknown> | null): void {
     this.#requireActive();
+    this.#requireTransport();
     const socket = this.#socket;
     if (socket === undefined) {
       throw invalidRequest(
@@ -2475,7 +2513,7 @@ export class SyncClient {
       if (!sameIntent) {
         throw new ClientSyncError(
           'client.subscription_intent_mismatch',
-          'subscribe: the subscription id is already registered for a different table, scopes, or params',
+          'subscription id already names different table, scopes, or params',
         );
       }
       return;
@@ -2533,7 +2571,7 @@ export class SyncClient {
     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)`,
+        `${base.table}: unknown scope variable ${base.variable} (§4.8)`,
       );
     }
     // Serialize the whole window edit: it spans an `await deriveSubId` between
@@ -2584,7 +2622,10 @@ export class SyncClient {
       }
     });
     const effects: CommandEffects = {
-      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);
@@ -2888,7 +2929,9 @@ export class SyncClient {
   mutateCommand(mutations: readonly MutationInput[]): CommandResult<string> {
     return {
       value: this.mutate(mutations),
-      effects: { sync: { kind: 'interactive' } },
+      effects: {
+        sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
+      },
     };
   }
 
@@ -2917,17 +2960,15 @@ export class SyncClient {
       );
     }
     return this.#recordMutations([
-      {
+      definedObject({
         table,
         op: 'patch',
         values: {
           ...Object.fromEntries(normalized),
           [pkColumn.name]: rowId,
         },
-        ...(options?.baseVersion !== undefined
-          ? { baseVersion: options.baseVersion }
-          : {}),
-      },
+        baseVersion: options?.baseVersion,
+      }),
     ]);
   }
 
@@ -2965,26 +3006,13 @@ export class SyncClient {
       return this.#applyBatch((batch) => {
         const targetsByTable = this.#localPurgeTargetsByTable(purge);
         restoreFailedBases(this.#db, this.#schema);
-        const droppedRetained = dropFailedRows(this.#db, (table, values) =>
+        this.#dropRetainedRows(batch, (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();
-        }
         // 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
@@ -3144,6 +3172,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()) {
@@ -3224,7 +3253,9 @@ export class SyncClient {
   ): CommandResult<string> {
     return {
       value: this.patch(table, rowId, partial, options),
-      effects: { sync: { kind: 'interactive' } },
+      effects: {
+        sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
+      },
     };
   }
 
@@ -3348,16 +3379,14 @@ export class SyncClient {
         );
       this.#rollbackFailedCommit(commit, batch);
       this.#replayOutbox();
-      const rejection: RejectionRecord = {
+      const rejection: RejectionRecord = 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,
@@ -3388,9 +3417,7 @@ export class SyncClient {
     this.#requireActive();
     if (this.#syncOutstanding) {
       return Promise.reject(
-        invalidRequest(
-          'sync() is already running — the core owns one loop (coalesce wake-ups)',
-        ),
+        invalidRequest('sync() is already running; coalesce wake-ups'),
       );
     }
     this.#syncOutstanding = true;
@@ -3440,6 +3467,7 @@ export class SyncClient {
       )
       .finally(() => {
         this.#syncOutstanding = false;
+        if (!this.#transportEnabled) this.disconnectRealtime();
         this.#endDiagnosticsDeferral();
       });
   }
@@ -3478,6 +3506,7 @@ export class SyncClient {
   }
 
   async #runSync(): Promise<SyncSummary> {
+    this.#requireTransport();
     this.#roundRetryDelayMs = undefined;
     this.#progress.emit({
       attempt: ++this.#progressAttempt,
@@ -3509,7 +3538,7 @@ export class SyncClient {
         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)
@@ -3643,6 +3672,8 @@ export class SyncClient {
         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 &&
@@ -3656,7 +3687,6 @@ export class SyncClient {
           )
       )
         round = -1;
-      if (last.schemaFloor !== undefined) return last;
       if (
         last.commitsApplied === 0 &&
         last.segmentRowsApplied === 0 &&
@@ -3772,6 +3802,7 @@ export class SyncClient {
 
   connectRealtime(): Promise<void> {
     this.#requireActive();
+    this.#requireTransport();
     if (this.#realtimePolicy === 'off') {
       return Promise.reject(
         invalidRequest("realtimePolicy is 'off'; realtime connect is refused"),
@@ -3832,12 +3863,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();
@@ -3985,6 +4017,7 @@ export class SyncClient {
   }
 
   async #handleRealtimeBinary(bytes: Uint8Array): Promise<void> {
+    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
@@ -4012,7 +4045,8 @@ export class SyncClient {
   }
 
   #sendAck(cursor: number): void {
-    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. */
@@ -4151,6 +4185,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);
@@ -4183,11 +4218,12 @@ export class SyncClient {
               },
               () => 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',
+                  'outcome persistence failed',
                 );
                 error.cause = cause;
                 throw error;
@@ -4220,74 +4256,16 @@ 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
-            ) {
+            )
               break;
-            }
-            // §4.2: a descriptor whose mediaType was not advertised is a
-            // broken server — fail loud, never skip or guess.
             if (
+              frame.type === 'SEGMENT_REF' &&
               frame.mediaType === 'sqlite' &&
               (this.#acceptMask() & ACCEPT_SQLITE) === 0
             ) {
@@ -4295,11 +4273,14 @@ export class SyncClient {
                 '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
@@ -4323,31 +4304,33 @@ export class SyncClient {
                       asOfCommitSeq: frame.asOfCommitSeq,
                       scopeDigest: frame.scopeDigest,
                     },
-                    {
+                    this.#segmentApplyOptions(
+                      table,
                       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;
-                        }),
-                    },
+                      frame.rowCount > 0,
+                      resetEpoch,
+                    ),
                   ),
                 section.fresh && !section.cleared,
               );
             } else {
               const segment = decodeRowsSegment(bytes);
+              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,
@@ -4357,31 +4340,19 @@ export class SyncClient {
                     this.#schema,
                     table,
                     segment,
-                    {
+                    this.#segmentApplyOptions(
+                      table,
                       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;
-                        }),
-                    },
+                      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;
@@ -4485,6 +4456,18 @@ 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,
@@ -4638,12 +4621,7 @@ export class SyncClient {
         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;
         }),
     );
@@ -4695,26 +4673,43 @@ export class SyncClient {
 
   /** Whether a fresh-bootstrap clear would remove at least one local row. */
   #scopedRowsExist(table: CompiledClientTable, effective: ScopeMap): boolean {
-    const entries = Object.entries(effective);
-    if (entries.length === 0) return false;
-    const clauses: string[] = [];
-    const params: string[] = [];
-    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);
-    }
+    const scope = localScopePredicate(table, effective);
     return (
+      scope !== undefined &&
       this.#db.query(
-        `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')} LIMIT 1`,
-        params,
+        `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: CompiledClientTable,
+    clearFirst: boolean,
+    effective: ScopeMap,
+    hasRows: boolean,
+    resetEpoch: number,
+  ): Parameters<typeof applyRowsSegment>[4] {
+    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
    * (no local scope-column mapping) marks the subscription `failed` and
@@ -4817,7 +4812,7 @@ export class SyncClient {
         // §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)`,
+          `segment download grant expired; pull again (§5.4)`,
           true,
         );
       }
@@ -4875,6 +4870,34 @@ export class SyncClient {
             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: Record<string, JsonRowValue> = 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).
@@ -4923,29 +4946,12 @@ export class SyncClient {
       ) {
         try {
           restoreFailedBases(this.#db, this.#schema);
-          const droppedRetained = dropFailedRows(
-            this.#db,
+          this.#dropRetainedRows(
+            batch,
             (name, values) =>
               name === table.name &&
-              Object.entries(lastEffective).every(([variable, allowed]) =>
-                allowed.includes(
-                  String(values[table.scopeColumnByVariable.get(variable)!]),
-                ),
-              ),
+              matchesLocalScopes(table, lastEffective, values),
           );
-          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();
-          }
           deleteScopedRows(this.#db, table, lastEffective);
           batch.scopeMap(table, lastEffective);
           const pendingById = new Map(
@@ -5229,18 +5235,52 @@ export class SyncClient {
   }
 
   /** Re-apply every pending outbox commit on top of server state (§7.1). */
-  #replayOutbox(): void {
+  #discardAcknowledgedRows(): void {
+    this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL`);
+  }
+
+  #dropRetainedRows(
+    batch: ChangeAccumulator,
+    matches: (
+      table: string,
+      values: Readonly<Record<string, JsonRowValue>>,
+    ) => boolean,
+  ): void {
+    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?: readonly string[]): void {
+    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) return;
+    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,
+          );
       });
     });
   }
@@ -5255,17 +5295,14 @@ export class SyncClient {
   #table(name: string): CompiledClientTable {
     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(): void {
     if (!this.#started) {
-      throw invalidRequest('SyncClient.start() has not completed');
+      throw invalidRequest('call SyncClient.start() first');
     }
   }
 
@@ -5274,7 +5311,7 @@ export class SyncClient {
     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',
+        'security preflight must complete before accessing protected data; call activateSecurity',
       );
     }
   }