@korajs/sync 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/index.js

@@ -528,7 +528,8 @@ function toProtoEnvelope(message) {
         })),
         schemaVersion: message.schemaVersion,
         authToken: message.authToken,
-        supportedWireFormats: message.supportedWireFormats
+        supportedWireFormats: message.supportedWireFormats,
+        ...message.lastDeliverySequence !== void 0 ? { lastDeliverySequence: message.lastDeliverySequence } : {}
       };
     case "handshake-response":
       return {
@@ -544,7 +545,8 @@ function toProtoEnvelope(message) {
         rejectReason: message.rejectReason,
         selectedWireFormat: message.selectedWireFormat,
         serverTime: message.serverTime,
-        blobStorageEnabled: message.blobStorageEnabled
+        blobStorageEnabled: message.blobStorageEnabled,
+        ...message.serverMaxDeliverySequence !== void 0 ? { serverMaxDeliverySequence: message.serverMaxDeliverySequence } : {}
       };
     case "operation-batch":
       return {
@@ -552,14 +554,17 @@ function toProtoEnvelope(message) {
         messageId: message.messageId,
         operations: message.operations.map(serializeProtoOperation),
         isFinal: message.isFinal,
-        batchIndex: message.batchIndex
+        batchIndex: message.batchIndex,
+        ...message.baseDeliverySequence !== void 0 ? { baseDeliverySequence: message.baseDeliverySequence } : {},
+        ...message.maxDeliverySequence !== void 0 ? { maxDeliverySequence: message.maxDeliverySequence } : {}
       };
     case "acknowledgment":
       return {
         type: message.type,
         messageId: message.messageId,
         acknowledgedMessageId: message.acknowledgedMessageId,
-        lastSequenceNumber: message.lastSequenceNumber
+        lastSequenceNumber: message.lastSequenceNumber,
+        ...message.deliverySequence !== void 0 ? { deliverySequence: message.deliverySequence } : {}
       };
     case "error":
       return {
@@ -624,7 +629,8 @@ function fromProtoEnvelope(envelope) {
         authToken: envelope.authToken,
         supportedWireFormats: envelope.supportedWireFormats?.filter(
           (format) => format === "json" || format === "protobuf"
-        )
+        ),
+        ...envelope.lastDeliverySequence !== void 0 ? { lastDeliverySequence: envelope.lastDeliverySequence } : {}
       };
     case "handshake-response":
       return {
@@ -641,7 +647,8 @@ function fromProtoEnvelope(envelope) {
         // Preserve the server's wall-clock time so clock-skew detection and
         // automatic timestamp rebase work over the protobuf wire, not just JSON.
         ...envelope.serverTime !== void 0 ? { serverTime: envelope.serverTime } : {},
-        ...envelope.blobStorageEnabled !== void 0 ? { blobStorageEnabled: envelope.blobStorageEnabled } : {}
+        ...envelope.blobStorageEnabled !== void 0 ? { blobStorageEnabled: envelope.blobStorageEnabled } : {},
+        ...envelope.serverMaxDeliverySequence !== void 0 ? { serverMaxDeliverySequence: envelope.serverMaxDeliverySequence } : {}
       };
     case "operation-batch":
       return {
@@ -649,14 +656,17 @@ function fromProtoEnvelope(envelope) {
         messageId: envelope.messageId,
         operations: (envelope.operations ?? []).map(deserializeProtoOperation),
         isFinal: envelope.isFinal ?? false,
-        batchIndex: envelope.batchIndex ?? 0
+        batchIndex: envelope.batchIndex ?? 0,
+        ...envelope.baseDeliverySequence !== void 0 ? { baseDeliverySequence: envelope.baseDeliverySequence } : {},
+        ...envelope.maxDeliverySequence !== void 0 ? { maxDeliverySequence: envelope.maxDeliverySequence } : {}
       };
     case "acknowledgment":
       return {
         type: "acknowledgment",
         messageId: envelope.messageId,
         acknowledgedMessageId: envelope.acknowledgedMessageId ?? "",
-        lastSequenceNumber: envelope.lastSequenceNumber ?? 0
+        lastSequenceNumber: envelope.lastSequenceNumber ?? 0,
+        ...envelope.deliverySequence !== void 0 ? { deliverySequence: envelope.deliverySequence } : {}
       };
     case "error":
       return {
@@ -857,6 +867,15 @@ function encodeEnvelope(envelope) {
     writer.uint32(218).string(envelope.collection);
   if (envelope.recordId && envelope.recordId.length > 0)
     writer.uint32(226).string(envelope.recordId);
+  if (envelope.lastDeliverySequence !== void 0)
+    writer.uint32(232).int64(envelope.lastDeliverySequence);
+  if (envelope.baseDeliverySequence !== void 0)
+    writer.uint32(240).int64(envelope.baseDeliverySequence);
+  if (envelope.maxDeliverySequence !== void 0)
+    writer.uint32(248).int64(envelope.maxDeliverySequence);
+  if (envelope.deliverySequence !== void 0) writer.uint32(256).int64(envelope.deliverySequence);
+  if (envelope.serverMaxDeliverySequence !== void 0)
+    writer.uint32(264).int64(envelope.serverMaxDeliverySequence);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -952,6 +971,21 @@ function decodeEnvelope(bytes) {
       case 28:
         envelope.recordId = reader.string();
         break;
+      case 29:
+        envelope.lastDeliverySequence = longToNumber(reader.int64());
+        break;
+      case 30:
+        envelope.baseDeliverySequence = longToNumber(reader.int64());
+        break;
+      case 31:
+        envelope.maxDeliverySequence = longToNumber(reader.int64());
+        break;
+      case 32:
+        envelope.deliverySequence = longToNumber(reader.int64());
+        break;
+      case 33:
+        envelope.serverMaxDeliverySequence = longToNumber(reader.int64());
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -1451,6 +1485,7 @@ var ChaosTransport = class {
   reorderRate;
   maxLatency;
   random;
+  dropPredicate;
   messageHandler = null;
   reorderBuffer = [];
   pending = [];
@@ -1461,6 +1496,7 @@ var ChaosTransport = class {
     this.reorderRate = config?.reorderRate ?? 0;
     this.maxLatency = config?.maxLatency ?? 0;
     this.random = config?.randomSource ?? Math.random;
+    this.dropPredicate = config?.dropPredicate ?? null;
   }
   async connect(url, options) {
     this.inner.onMessage((msg) => this.handleIncoming(msg));
@@ -1479,6 +1515,9 @@ var ChaosTransport = class {
     return this.inner.disconnect();
   }
   send(message) {
+    if (this.dropPredicate?.(message, "outgoing")) {
+      return;
+    }
     if (this.random() < this.dropRate) {
       return;
     }
@@ -1506,6 +1545,9 @@ var ChaosTransport = class {
   }
   handleIncoming(message) {
     if (!this.messageHandler) return;
+    if (this.dropPredicate?.(message, "incoming")) {
+      return;
+    }
     if (this.random() < this.dropRate) {
       return;
     }
@@ -2589,6 +2631,7 @@ var OutboundQueue = class {
 // src/engine/sync-engine.ts
 var DEFAULT_BATCH_SIZE = 100;
 var DEFAULT_SCHEMA_VERSION = 1;
+var DEFAULT_OUTBOUND_ACK_TIMEOUT_MS = 3e4;
 var VALID_TRANSITIONS = {
   disconnected: ["connecting"],
   connecting: ["handshaking", "error", "disconnected"],
@@ -2602,6 +2645,17 @@ var nextQuerySubsetId = 0;
 function generateMessageId() {
   return `msg-${Date.now()}-${nextMessageId++}`;
 }
+var MAX_DELIVERY_VIEW_WATERMARKS = 64;
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+  return `{${entries.join(",")}}`;
+}
 var SyncEngine = class {
   state = "disconnected";
   transport;
@@ -2612,6 +2666,7 @@ var SyncEngine = class {
   outboundQueue;
   rejectedStorage;
   batchSize;
+  outboundAckTimeoutMs;
   encryptor;
   awarenessManager;
   richtextDocChannel;
@@ -2631,6 +2686,9 @@ var SyncEngine = class {
   clockBlocked = false;
   clockSkewMs = null;
   blobStorageEnabled = false;
+  outboundAckTimer = null;
+  startPromise = null;
+  stopPromise = null;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
@@ -2651,6 +2709,25 @@ var SyncEngine = class {
   /** Resume cursor for paginated initial sync (persisted across reconnects) */
   resumeDeltaCursor = null;
   initialSyncTotalBatches = 0;
+  /**
+   * The delivery watermark for the CURRENT sync view: the highest server delivery
+   * sequence up to which every operation in the current view (scope + active query
+   * subscriptions) has been contiguously applied. Advanced only through the server's
+   * gap-free delivery stream (never through live relay), so it is a durable lower bound
+   * on what this client holds for this view. Reported at handshake to resume the stream.
+   *
+   * The watermark is keyed by view: switching views (a scope or subscription change)
+   * saves the current view's watermark and loads the target view's, so returning to a
+   * previously-synced view resumes exactly where it left off instead of re-syncing. This
+   * is correct because a view's watermark is a lower bound specific to that view's
+   * filter; a widened view is simply a different (initially unsynced) view.
+   */
+  deliveryWatermark = 0;
+  /**
+   * In-memory cache of watermark per view signature, preloaded from persistence at start
+   * so a view switch resolves synchronously (no race with the reconnect it triggers).
+   */
+  deliverySignatureWatermarks = /* @__PURE__ */ new Map();
   constructor(options) {
     this.transport = options.transport;
     this.store = options.store;
@@ -2658,6 +2735,7 @@ var SyncEngine = class {
     this.serializer = options.serializer ?? new NegotiatedMessageSerializer("json");
     this.emitter = options.emitter ?? null;
     this.batchSize = options.config.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.outboundAckTimeoutMs = options.config.outboundAckTimeoutMs ?? DEFAULT_OUTBOUND_ACK_TIMEOUT_MS;
     this.encryptor = options.encryptor ?? null;
     this.syncState = options.syncState ?? null;
     this.activeScope = options.config.scopeMap;
@@ -2703,10 +2781,20 @@ var SyncEngine = class {
    * Start the sync engine: connect → handshake → delta exchange → streaming.
    */
   async start() {
+    if (this.state === "streaming") return;
+    if (this.startPromise) return this.startPromise;
+    this.startPromise = this.startInternal().finally(() => {
+      this.startPromise = null;
+    });
+    return this.startPromise;
+  }
+  async startInternal() {
+    if (this.stopPromise) {
+      await this.stopPromise;
+    }
+    if (this.state === "streaming") return;
     if (this.state !== "disconnected") {
-      throw new SyncError4("Cannot start sync engine: not in disconnected state", {
-        currentState: this.state
-      });
+      await this.stop();
     }
     await this.outboundQueue.initialize();
     if (this.syncState) {
@@ -2714,6 +2802,16 @@ var SyncEngine = class {
       if (this.syncState.loadDeltaCursor) {
         this.resumeDeltaCursor = await this.syncState.loadDeltaCursor();
       }
+      if (this.syncState.loadAllDeliveryWatermarks) {
+        const all = await this.syncState.loadAllDeliveryWatermarks();
+        for (const [signature, watermark] of Object.entries(all)) {
+          this.deliverySignatureWatermarks.set(signature, watermark);
+        }
+      } else if (this.syncState.loadDeliveryWatermark) {
+        this.deliverySignatureWatermarks.set("", await this.syncState.loadDeliveryWatermark(""));
+      }
+      this.deliveryWatermark = this.deliverySignatureWatermarks.get(this.deliverySignature()) ?? 0;
+      this.evictColdViewWatermarks();
     }
     await this.reconcileOutboundFromOpLog();
     await this.refreshPendingCount();
@@ -2729,7 +2827,12 @@ var SyncEngine = class {
     this.transitionTo("connecting");
     try {
       const authToken = this.config.auth ? (await this.config.auth()).token : void 0;
+      if (this.state !== "connecting") return;
       await this.transport.connect(this.config.url, { authToken });
+      if (this.state !== "connecting") {
+        await this.transport.disconnect();
+        return;
+      }
       this.transitionTo("handshaking");
       const localVector = this.store.getVersionVector();
       const activeQuerySubsets = this.getActiveQuerySubsets();
@@ -2743,7 +2846,11 @@ var SyncEngine = class {
         supportedWireFormats: ["json", "protobuf"],
         ...this.config.scopeMap ? { syncScope: this.config.scopeMap } : {},
         ...activeQuerySubsets.length > 0 ? { syncQueries: activeQuerySubsets } : {},
-        ...this.resumeDeltaCursor ? { deltaCursor: encodeDeltaCursor(this.resumeDeltaCursor) } : {}
+        ...this.resumeDeltaCursor ? { deltaCursor: encodeDeltaCursor(this.resumeDeltaCursor) } : {},
+        // Resume the server's gap-free delivery stream from our watermark. A server
+        // that understands it drives server->client sync from delivery sequences; an
+        // older server ignores it and falls back to the version-vector delta.
+        lastDeliverySequence: this.deliveryWatermark
       };
       this.transport.send(handshake);
     } catch (err) {
@@ -2755,7 +2862,15 @@ var SyncEngine = class {
    * Stop the sync engine. Disconnects the transport.
    */
   async stop() {
+    if (this.stopPromise) return this.stopPromise;
+    this.stopPromise = this.stopInternal().finally(() => {
+      this.stopPromise = null;
+    });
+    return this.stopPromise;
+  }
+  async stopInternal() {
     if (this.state === "disconnected") return;
+    this.clearOutboundAckTimer();
     this.awarenessManager.stopCleanupTimer();
     if (this.currentBatch) {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
@@ -2780,7 +2895,7 @@ var SyncEngine = class {
    * because they should remain local-only and not be sent to the server.
    */
   async pushOperation(op) {
-    if (!this.operationAllowedForSync(op)) {
+    if (!await this.operationAllowedForSync(op)) {
       return;
     }
     if (this.syncState) {
@@ -2959,8 +3074,84 @@ var SyncEngine = class {
    * @param scopeMap - New per-collection scope filters, or undefined to remove scope
    */
   updateScope(scopeMap) {
+    const previousSignature = this.deliverySignature();
     this.activeScope = scopeMap;
     this.config.scopeMap = scopeMap;
+    this.switchDeliveryView(previousSignature);
+  }
+  /**
+   * A stable identifier for the current sync view: the auth/tenant scope plus the set of
+   * active query subscriptions, canonicalized so the same view always produces the same
+   * string. The delivery watermark is keyed by this, so each distinct view resumes from
+   * its own last position.
+   */
+  deliverySignature() {
+    const subsets = this.getActiveQuerySubsets();
+    if (!this.activeScope && subsets.length === 0) {
+      return "";
+    }
+    const normalizedSubsets = subsets.map((s) => `${s.collection}:${stableStringify(s.where)}`).sort();
+    return stableStringify({ scope: this.activeScope ?? null, subsets: normalizedSubsets });
+  }
+  /**
+   * Switch the active delivery watermark to the current view after a scope or subscription
+   * change. The prior view's watermark is saved so returning to it resumes; the new view's
+   * watermark is restored from the in-memory cache (0 for a never-synced view, which then
+   * does a one-time resync under that view). No data is lost: a view's watermark is a lower
+   * bound for that specific view's filter.
+   */
+  switchDeliveryView(previousSignature) {
+    const nextSignature = this.deliverySignature();
+    if (nextSignature === previousSignature) {
+      return;
+    }
+    this.setViewWatermark(previousSignature, this.deliveryWatermark);
+    void this.persistDeliveryWatermark(this.deliveryWatermark, previousSignature);
+    this.deliveryWatermark = this.deliverySignatureWatermarks.get(nextSignature) ?? 0;
+  }
+  /**
+   * Record a view's watermark in the in-memory cache as the most-recently-used entry (the
+   * Map preserves insertion order, so re-inserting moves it to the tail), then evict cold
+   * views past the retention cap. This is the single place the cache is written, so LRU
+   * order and the size bound are always maintained together.
+   */
+  setViewWatermark(signature, watermark) {
+    this.deliverySignatureWatermarks.delete(signature);
+    this.deliverySignatureWatermarks.set(signature, watermark);
+    this.evictColdViewWatermarks();
+  }
+  /**
+   * Trim the per-view watermark cache to `MAX_DELIVERY_VIEW_WATERMARKS`, evicting the
+   * least-recently-used views. The default view ('') and the live view are never evicted
+   * (evicting the live view would force an immediate re-scan of what we are actively
+   * syncing). Each eviction also removes the persisted row, bounding storage. Safe by
+   * construction: an evicted view simply back-fills from 0 (deduplicated) when next seen.
+   */
+  evictColdViewWatermarks() {
+    if (this.deliverySignatureWatermarks.size <= MAX_DELIVERY_VIEW_WATERMARKS) {
+      return;
+    }
+    const liveSignature = this.deliverySignature();
+    for (const signature of this.deliverySignatureWatermarks.keys()) {
+      if (this.deliverySignatureWatermarks.size <= MAX_DELIVERY_VIEW_WATERMARKS) {
+        break;
+      }
+      if (signature === "" || signature === liveSignature) {
+        continue;
+      }
+      this.deliverySignatureWatermarks.delete(signature);
+      void this.deleteDeliveryWatermark(signature);
+    }
+  }
+  /**
+   * Remove a view's persisted watermark row (best-effort; a persistence layer that omits
+   * the delete simply keeps the row, which is harmless).
+   */
+  async deleteDeliveryWatermark(signature) {
+    if (!this.syncState?.deleteDeliveryWatermark) {
+      return;
+    }
+    await this.syncState.deleteDeliveryWatermark(signature);
   }
   /**
    * Get the currently active scope map. Returns undefined if no scope is configured.
@@ -2974,10 +3165,14 @@ var SyncEngine = class {
    */
   registerQuerySubset(subset) {
     const id = `query-${nextQuerySubsetId++}`;
+    const previousSignature = this.deliverySignature();
     this.querySubsets.set(id, subset);
+    this.switchDeliveryView(previousSignature);
     this.scheduleQuerySubsetReconnect();
     return () => {
+      const sigBeforeRemove = this.deliverySignature();
       this.querySubsets.delete(id);
+      this.switchDeliveryView(sigBeforeRemove);
       this.scheduleQuerySubsetReconnect();
     };
   }
@@ -3130,6 +3325,11 @@ var SyncEngine = class {
     }
     this.remoteVector = wireToVersionVector(msg.versionVector);
     void this.persistLastAckedServerVector(this.remoteVector);
+    if (typeof msg.serverMaxDeliverySequence === "number" && this.deliveryWatermark > msg.serverMaxDeliverySequence) {
+      this.deliveryWatermark = 0;
+      this.setViewWatermark(this.deliverySignature(), 0);
+      await this.persistDeliveryWatermark(0);
+    }
     if (msg.selectedWireFormat) {
       this.setSerializerWireFormat(msg.selectedWireFormat);
     }
@@ -3195,7 +3395,7 @@ var SyncEngine = class {
   async sendDelta() {
     const localVector = this.store.getVersionVector();
     const allMissingOps = await this.collectDelta(localVector, this.remoteVector);
-    const missingOps = allMissingOps.filter((op) => this.operationAllowedForSync(op));
+    const missingOps = await this.filterAllowedForSync(allMissingOps);
     this.deltaSentOpIds = missingOps.map((op) => op.id);
     if (missingOps.length === 0) {
       const messageId = generateMessageId();
@@ -3270,11 +3470,23 @@ var SyncEngine = class {
     return missing;
   }
   async handleOperationBatch(msg) {
+    const isDeliveryBatch = msg.maxDeliverySequence !== void 0;
+    if (isDeliveryBatch) {
+      const base = msg.baseDeliverySequence ?? 0;
+      if (base > this.deliveryWatermark) {
+        return;
+      }
+      if (base < this.deliveryWatermark) {
+        this.sendDeliveryAck(msg.messageId, this.deliveryWatermark);
+        return;
+      }
+    }
     const deserialized = msg.operations.map((s) => this.serializer.decodeOperation(s));
     const operations = this.encryptor ? await this.encryptor.decryptBatch(deserialized) : deserialized;
-    const inScopeOps = operations.filter((op) => this.operationAllowedForSync(op));
+    const inScopeOps = await this.filterAllowedForSync(operations);
     const targetSchemaVersion = this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
     const transforms = this.config.operationTransforms ?? [];
+    let fullyApplied = true;
     for (const op of inScopeOps) {
       const transformed = transforms.length > 0 ? applyOperationTransforms(op, targetSchemaVersion, transforms) : op;
       if (transformed === null) {
@@ -3286,6 +3498,7 @@ var SyncEngine = class {
           this.emitApplyFailure(transformed, result);
         }
       } catch (error) {
+        fullyApplied = false;
         if (error instanceof ClockDriftError) {
           this.emitApplyFailure(transformed, "rejected", {
             code: APPLY_FAILURE_CODES.CLOCK_DRIFT,
@@ -3296,11 +3509,8 @@ var SyncEngine = class {
         }
         const message = error instanceof Error ? error.message : "Apply failed";
         const code = error instanceof SyncError4 ? error.code : error instanceof KoraError2 ? error.code : error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : APPLY_FAILURE_CODES.APPLY_FAILED;
-        this.emitApplyFailure(transformed, "rejected", {
-          code,
-          message,
-          retriable: code !== APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY
-        });
+        const retriable = code !== APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY;
+        this.emitApplyFailure(transformed, "rejected", { code, message, retriable });
       }
     }
     if (inScopeOps.length > 0) {
@@ -3311,18 +3521,27 @@ var SyncEngine = class {
         batchSize: inScopeOps.length
       });
     }
-    const lastOp = operations[operations.length - 1];
-    const ack = {
-      type: "acknowledgment",
-      messageId: generateMessageId(),
-      acknowledgedMessageId: msg.messageId,
-      lastSequenceNumber: lastOp ? lastOp.sequenceNumber : 0
-    };
-    this.transport.send(ack);
-    this.emitter?.emit({
-      type: "sync:acknowledged",
-      sequenceNumber: lastOp ? lastOp.sequenceNumber : 0
-    });
+    const deliveryFullyApplied = isDeliveryBatch && fullyApplied;
+    if (!isDeliveryBatch || deliveryFullyApplied) {
+      const lastOp = operations[operations.length - 1];
+      const ack = {
+        type: "acknowledgment",
+        messageId: generateMessageId(),
+        acknowledgedMessageId: msg.messageId,
+        lastSequenceNumber: lastOp ? lastOp.sequenceNumber : 0,
+        ...deliveryFullyApplied && msg.maxDeliverySequence !== void 0 ? { deliverySequence: msg.maxDeliverySequence } : {}
+      };
+      this.transport.send(ack);
+      this.emitter?.emit({
+        type: "sync:acknowledged",
+        sequenceNumber: lastOp ? lastOp.sequenceNumber : 0
+      });
+    }
+    if (isDeliveryBatch && fullyApplied && msg.maxDeliverySequence !== void 0) {
+      this.deliveryWatermark = msg.maxDeliverySequence;
+      this.setViewWatermark(this.deliverySignature(), this.deliveryWatermark);
+      await this.persistDeliveryWatermark(this.deliveryWatermark);
+    }
     if (this.state === "syncing") {
       this.deltaBatchesReceived++;
       const totalBatches = msg.totalBatches ?? this.initialSyncTotalBatches;
@@ -3330,15 +3549,17 @@ var SyncEngine = class {
         this.initialSyncTotalBatches = msg.totalBatches;
       }
       this.metricsCollector.updateInitialSyncProgress(this.deltaBatchesReceived, totalBatches);
-      const cursorFromBatch = msg.cursor !== void 0 ? decodeDeltaCursor(msg.cursor) : createDeltaCursorFromBatch(
-        inScopeOps.length > 0 ? inScopeOps : operations,
-        msg.batchIndex
-      );
-      if (cursorFromBatch) {
-        this.resumeDeltaCursor = cursorFromBatch;
-        await this.persistDeltaCursor(cursorFromBatch);
+      if (!isDeliveryBatch) {
+        const cursorFromBatch = msg.cursor !== void 0 ? decodeDeltaCursor(msg.cursor) : createDeltaCursorFromBatch(
+          inScopeOps.length > 0 ? inScopeOps : operations,
+          msg.batchIndex
+        );
+        if (cursorFromBatch) {
+          this.resumeDeltaCursor = cursorFromBatch;
+          await this.persistDeltaCursor(cursorFromBatch);
+        }
       }
-      if (msg.isFinal) {
+      if (msg.isFinal && (!isDeliveryBatch || fullyApplied)) {
         this.deltaReceiveComplete = true;
         this.resumeDeltaCursor = null;
         await this.persistDeltaCursor(null);
@@ -3347,7 +3568,19 @@ var SyncEngine = class {
       }
     }
   }
+  /** Acknowledge a delivery batch (used for duplicates) without re-applying it. */
+  sendDeliveryAck(acknowledgedMessageId, deliverySequence) {
+    const ack = {
+      type: "acknowledgment",
+      messageId: generateMessageId(),
+      acknowledgedMessageId,
+      lastSequenceNumber: 0,
+      deliverySequence
+    };
+    this.transport.send(ack);
+  }
   handleAcknowledgment(msg) {
+    this.clearOutboundAckTimer();
     if (this.state === "syncing" && this.config.strictHandshake) {
       this.pendingDeltaBatchAcks.delete(msg.acknowledgedMessageId);
       this.markDeltaSendCompleteIfReady();
@@ -3367,6 +3600,11 @@ var SyncEngine = class {
     }
   }
   handleError(msg) {
+    this.clearOutboundAckTimer();
+    if (this.currentBatch) {
+      this.outboundQueue.returnBatch(this.currentBatch.batchId);
+      this.currentBatch = null;
+    }
     this.transitionTo("error");
     if (msg.code === "AUTH_FAILED") {
       this.emitter?.emit({ type: "sync:auth-failed", reason: msg.message });
@@ -3527,7 +3765,7 @@ var SyncEngine = class {
       return;
     }
     const ops = await this.store.getOperationRange(localNodeId, 1, localSeq);
-    const inScope = ops.filter((op) => this.operationAllowedForSync(op));
+    const inScope = await this.filterAllowedForSync(ops);
     for (const op of inScope) {
       await this.outboundQueue.enqueue(op);
     }
@@ -3550,6 +3788,7 @@ var SyncEngine = class {
             batchIndex: 0
           };
           this.transport.send(batchMsg);
+          this.startOutboundAckTimer(batch.batchId);
           this.emitter?.emit({
             type: "sync:sent",
             operations: batch.operations,
@@ -3575,6 +3814,7 @@ var SyncEngine = class {
         batchIndex: 0
       };
       this.transport.send(batchMsg);
+      this.startOutboundAckTimer(batch.batchId);
       this.emitter?.emit({
         type: "sync:sent",
         operations: batch.operations,
@@ -3582,6 +3822,33 @@ var SyncEngine = class {
       });
     }
   }
+  startOutboundAckTimer(batchId) {
+    this.clearOutboundAckTimer();
+    if (this.outboundAckTimeoutMs <= 0) return;
+    this.outboundAckTimer = setTimeout(() => {
+      void this.handleOutboundAckTimeout(batchId);
+    }, this.outboundAckTimeoutMs);
+  }
+  clearOutboundAckTimer() {
+    if (!this.outboundAckTimer) return;
+    clearTimeout(this.outboundAckTimer);
+    this.outboundAckTimer = null;
+  }
+  async handleOutboundAckTimeout(batchId) {
+    if (!this.currentBatch || this.currentBatch.batchId !== batchId) return;
+    this.outboundQueue.returnBatch(batchId);
+    this.currentBatch = null;
+    this.clearOutboundAckTimer();
+    await this.refreshPendingCount();
+    if (this.state === "disconnected") return;
+    const reason = `Timed out waiting for acknowledgment of outbound batch ${batchId}`;
+    try {
+      await this.transport.disconnect();
+    } finally {
+      this.ensureDisconnected();
+      this.emitter?.emit({ type: "sync:disconnected", reason });
+    }
+  }
   handleAwarenessUpdate(msg) {
     const awarenessMessage = {
       type: "awareness",
@@ -3591,6 +3858,7 @@ var SyncEngine = class {
     this.awarenessManager.handleRemoteMessage(awarenessMessage);
   }
   handleTransportClose(reason) {
+    this.clearOutboundAckTimer();
     if (this.currentBatch) {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
       this.currentBatch = null;
@@ -3625,11 +3893,40 @@ var SyncEngine = class {
       this.serializer.setWireFormat(format);
     }
   }
-  operationAllowedForSync(op) {
-    if (!operationMatchesScope(op, this.activeScope)) {
+  async operationAllowedForSync(op) {
+    if (this.matchesScopeAndSubsets(op)) {
+      return true;
+    }
+    const fullRecord = await this.readRecordForBackfill(op);
+    if (!fullRecord) {
       return false;
     }
-    return operationMatchesQuerySubsets(op, this.getActiveQuerySubsets());
+    return this.matchesScopeAndSubsets(op, fullRecord);
+  }
+  matchesScopeAndSubsets(op, fullRecord) {
+    if (!operationMatchesScope(op, this.activeScope, fullRecord)) {
+      return false;
+    }
+    return operationMatchesQuerySubsets(op, this.getActiveQuerySubsets(), fullRecord);
+  }
+  async readRecordForBackfill(op) {
+    if (!this.store.readRecordFields) {
+      return null;
+    }
+    try {
+      return await this.store.readRecordFields(op.collection, op.recordId);
+    } catch {
+      return null;
+    }
+  }
+  async filterAllowedForSync(ops) {
+    const allowed = [];
+    for (const op of ops) {
+      if (await this.operationAllowedForSync(op)) {
+        allowed.push(op);
+      }
+    }
+    return allowed;
   }
   async persistDeltaCursor(cursor) {
     if (!this.syncState?.saveDeltaCursor) {
@@ -3637,6 +3934,12 @@ var SyncEngine = class {
     }
     await this.syncState.saveDeltaCursor(cursor);
   }
+  async persistDeliveryWatermark(watermark, signature = this.deliverySignature()) {
+    if (!this.syncState?.saveDeliveryWatermark) {
+      return;
+    }
+    await this.syncState.saveDeliveryWatermark(signature, watermark);
+  }
   scheduleQuerySubsetReconnect() {
     if (this.querySubsetReconnectTimer) {
       clearTimeout(this.querySubsetReconnectTimer);