@korajs/sync 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/index.js

@@ -14,6 +14,7 @@ var SYNC_STATES = [
 ];
 var SYNC_STATUSES = [
   "connected",
+  "reconnecting",
   "syncing",
   "synced",
   "offline",
@@ -21,6 +22,20 @@ var SYNC_STATUSES = [
   "error",
   "schema-mismatch"
 ];
+var MemoryRejectedOperationStorage = class {
+  rejected = /* @__PURE__ */ new Map();
+  async record(rejected) {
+    this.rejected.set(rejected.operationId, rejected);
+  }
+  async list() {
+    return [...this.rejected.values()];
+  }
+  async remove(operationIds) {
+    for (const id of operationIds) {
+      this.rejected.delete(id);
+    }
+  }
+};
 var ScopeViolationError = class extends KoraError {
   constructor(operationId, collection, scope, message) {
     super(
@@ -218,6 +233,8 @@ function isSyncMessage(value) {
       return isAcknowledgmentMessage(value);
     case "error":
       return isErrorMessage(value);
+    case "operation-rejected":
+      return isOperationRejectedMessage(value);
     case "awareness-update":
       return isAwarenessUpdateMessage(value);
     case "yjs-doc-update":
@@ -257,6 +274,11 @@ function isErrorMessage(value) {
   const msg = value;
   return msg.type === "error" && typeof msg.messageId === "string" && typeof msg.code === "string" && typeof msg.message === "string" && typeof msg.retriable === "boolean";
 }
+function isOperationRejectedMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "operation-rejected" && typeof msg.messageId === "string" && typeof msg.operationId === "string" && typeof msg.collection === "string" && typeof msg.recordId === "string" && typeof msg.code === "string" && typeof msg.message === "string" && typeof msg.retriable === "boolean";
+}
 function isAwarenessUpdateMessage(value) {
   if (typeof value !== "object" || value === null) return false;
   const msg = value;
@@ -507,7 +529,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 {
@@ -523,7 +546,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 {
@@ -531,14 +555,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 {
@@ -548,6 +575,17 @@ function toProtoEnvelope(message) {
         errorMessage: message.message,
         retriable: message.retriable
       };
+    case "operation-rejected":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        operationId: message.operationId,
+        collection: message.collection,
+        recordId: message.recordId,
+        errorCode: message.code,
+        errorMessage: message.message,
+        retriable: message.retriable
+      };
     case "awareness-update":
     case "yjs-doc-update":
       return {
@@ -592,7 +630,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 {
@@ -609,7 +648,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 {
@@ -617,14 +657,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 {
@@ -634,6 +677,17 @@ function fromProtoEnvelope(envelope) {
         message: envelope.errorMessage ?? "Unknown error",
         retriable: envelope.retriable ?? false
       };
+    case "operation-rejected":
+      return {
+        type: "operation-rejected",
+        messageId: envelope.messageId,
+        operationId: envelope.operationId ?? "",
+        collection: envelope.collection ?? "",
+        recordId: envelope.recordId ?? "",
+        code: envelope.errorCode ?? "REJECTED",
+        message: envelope.errorMessage ?? "",
+        retriable: envelope.retriable ?? false
+      };
     case "blob-chunk-request":
       return {
         type: "blob-chunk-request",
@@ -808,6 +862,21 @@ function encodeEnvelope(envelope) {
   if (envelope.hasBytes !== void 0) writer.uint32(184).bool(envelope.hasBytes);
   if (envelope.blobStorageEnabled !== void 0)
     writer.uint32(200).bool(envelope.blobStorageEnabled);
+  if (envelope.operationId && envelope.operationId.length > 0)
+    writer.uint32(210).string(envelope.operationId);
+  if (envelope.collection && envelope.collection.length > 0)
+    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) {
@@ -894,6 +963,30 @@ function decodeEnvelope(bytes) {
       case 25:
         envelope.blobStorageEnabled = reader.bool();
         break;
+      case 26:
+        envelope.operationId = reader.string();
+        break;
+      case 27:
+        envelope.collection = reader.string();
+        break;
+      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);
     }
@@ -1393,6 +1486,7 @@ var ChaosTransport = class {
   reorderRate;
   maxLatency;
   random;
+  dropPredicate;
   messageHandler = null;
   reorderBuffer = [];
   pending = [];
@@ -1403,6 +1497,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));
@@ -1421,6 +1516,9 @@ var ChaosTransport = class {
     return this.inner.disconnect();
   }
   send(message) {
+    if (this.dropPredicate?.(message, "outgoing")) {
+      return;
+    }
     if (this.random() < this.dropRate) {
       return;
     }
@@ -1448,6 +1546,9 @@ var ChaosTransport = class {
   }
   handleIncoming(message) {
     if (!this.messageHandler) return;
+    if (this.dropPredicate?.(message, "incoming")) {
+      return;
+    }
     if (this.random() < this.dropRate) {
       return;
     }
@@ -2400,6 +2501,32 @@ var OutboundQueue = class {
     const ids = ops.map((op) => op.id);
     await this.storage.dequeue(ids);
   }
+  /**
+   * Acknowledge only operations in an in-flight batch whose local sequence number is
+   * covered by the server's ack. Any later operations return to the front of the
+   * queue for retry. This is required when the server accepts a prefix but rejects a
+   * later operation retriably (for example a stale-scope push after auth changed).
+   */
+  async acknowledgeThrough(batchId, lastSequenceNumber) {
+    const ops = this.inFlight.get(batchId);
+    if (!ops) return;
+    this.inFlight.delete(batchId);
+    const acknowledged = ops.filter((op) => op.sequenceNumber <= lastSequenceNumber);
+    const retry = ops.filter((op) => op.sequenceNumber > lastSequenceNumber);
+    if (retry.length > 0) {
+      this.queue.unshift(...retry);
+      if (this.queue.length > 1) {
+        this.queue = topologicalSort(this.queue);
+      }
+    }
+    if (acknowledged.length > 0) {
+      const ids = acknowledged.map((op) => op.id);
+      for (const id of ids) {
+        this.seen.delete(id);
+      }
+      await this.storage.dequeue(ids);
+    }
+  }
   /**
    * Return a failed batch to the front of the queue for retry.
    * Prepends the operations to maintain priority.
@@ -2482,6 +2609,37 @@ var OutboundQueue = class {
   get isInitialized() {
     return this.initialized;
   }
+  /**
+   * Remove a single operation the server permanently rejected — from the queue,
+   * from any in-flight batch, and from durable storage — so a later batch ack or
+   * a reconnect `returnBatch` can never resend or resurrect it. Returns the
+   * removed operation so the caller can record it in a durable rejected store,
+   * or null if it was not present (already acknowledged and removed).
+   */
+  async reject(opId) {
+    let removed = null;
+    for (const [batchId, ops] of this.inFlight) {
+      const idx = ops.findIndex((op) => op.id === opId);
+      if (idx !== -1) {
+        removed = ops[idx] ?? null;
+        ops.splice(idx, 1);
+        if (ops.length === 0) {
+          this.inFlight.delete(batchId);
+        }
+        break;
+      }
+    }
+    if (!removed) {
+      const idx = this.queue.findIndex((op) => op.id === opId);
+      if (idx !== -1) {
+        removed = this.queue[idx] ?? null;
+        this.queue.splice(idx, 1);
+      }
+    }
+    this.seen.delete(opId);
+    await this.storage.dequeue([opId]);
+    return removed;
+  }
   /**
    * Remove operations by id from queue and persistent storage.
    * Used when ops were already sent during handshake delta exchange.
@@ -2500,6 +2658,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"],
@@ -2513,6 +2672,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;
@@ -2521,7 +2691,9 @@ var SyncEngine = class {
   serializer;
   emitter;
   outboundQueue;
+  rejectedStorage;
   batchSize;
+  outboundAckTimeoutMs;
   encryptor;
   awarenessManager;
   richtextDocChannel;
@@ -2536,11 +2708,16 @@ var SyncEngine = class {
   lastSuccessfulPull = null;
   conflictCount = 0;
   currentBatch = null;
+  currentBatchRequiresPartialAck = false;
   reconnecting = false;
   schemaBlocked = false;
   clockBlocked = false;
   clockSkewMs = null;
   blobStorageEnabled = false;
+  outboundAckTimer = null;
+  startPromise = null;
+  stopPromise = null;
+  reconnectPromise = null;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
@@ -2561,6 +2738,27 @@ 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();
+  deliveryGapRepeatCount = 0;
+  lastDeliveryGapKey = null;
   constructor(options) {
     this.transport = options.transport;
     this.store = options.store;
@@ -2568,11 +2766,13 @@ 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;
     const queueStorage = options.queueStorage ?? new MemoryQueueStorage();
     this.outboundQueue = new OutboundQueue(queueStorage);
+    this.rejectedStorage = options.rejectedStorage ?? new MemoryRejectedOperationStorage();
     this.metricsCollector = new SyncMetricsCollector(options.metricsConfig);
     if (this.emitter) {
       this.metricsCollector.attachEmitter(this.emitter);
@@ -2612,10 +2812,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) {
@@ -2623,6 +2833,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();
@@ -2638,7 +2858,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();
@@ -2652,7 +2877,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) {
@@ -2664,11 +2893,20 @@ 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);
       this.currentBatch = null;
+      this.currentBatchRequiresPartialAck = false;
     }
     try {
       await this.transport.disconnect();
@@ -2689,7 +2927,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) {
@@ -2718,6 +2956,7 @@ var SyncEngine = class {
   getStatus() {
     const pendingOperations = this.syncState ? this.cachedUnsyncedCount : this.outboundQueue.totalPending;
     const base = {
+      reconnecting: this.reconnecting,
       pendingOperations,
       lastSyncedAt: this.lastSyncedAt,
       lastSuccessfulPush: this.lastSuccessfulPush,
@@ -2737,7 +2976,7 @@ var SyncEngine = class {
       case "connecting":
       case "handshaking":
       case "syncing":
-        return { ...base, status: this.reconnecting ? "offline" : "syncing" };
+        return { ...base, status: this.reconnecting ? "reconnecting" : "syncing" };
       case "streaming":
         return { ...base, status: pendingOperations > 0 ? "syncing" : "synced" };
       case "error":
@@ -2822,6 +3061,24 @@ var SyncEngine = class {
       await this.start();
     }
   }
+  /**
+   * Atomically refresh the transport session. Overlapping callers share one
+   * reconnect, in-flight outbound batches are returned to the queue by stop(), and the
+   * next start handshakes with the latest auth token, sync scope, and query subsets.
+   */
+  async reconnect() {
+    if (this.schemaBlocked) return;
+    if (this.reconnectPromise) return this.reconnectPromise;
+    this.reconnecting = false;
+    this.reconnectPromise = this.reconnectInternal().finally(() => {
+      this.reconnectPromise = null;
+    });
+    return this.reconnectPromise;
+  }
+  async reconnectInternal() {
+    await this.stop();
+    await this.start();
+  }
   /**
    * Export a diagnostics snapshot for debugging and support tickets.
    * Contains connection state, timing info, and queue metrics.
@@ -2840,6 +3097,8 @@ var SyncEngine = class {
       pendingOperations: this.outboundQueue.totalPending,
       hasInFlightBatch: this.currentBatch !== null,
       reconnecting: this.reconnecting,
+      deliveryWatermark: this.deliveryWatermark,
+      deliveryGapRepeatCount: this.deliveryGapRepeatCount,
       timestamp: Date.now()
     };
   }
@@ -2868,8 +3127,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.
@@ -2883,10 +3218,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();
     };
   }
@@ -2949,11 +3288,14 @@ var SyncEngine = class {
         await this.handleOperationBatch(message);
         break;
       case "acknowledgment":
-        this.handleAcknowledgment(message);
+        await this.handleAcknowledgment(message);
         break;
       case "error":
         this.handleError(message);
         break;
+      case "operation-rejected":
+        await this.handleOperationRejected(message);
+        break;
       case "awareness-update":
         this.handleAwarenessUpdate(message);
         break;
@@ -3036,6 +3378,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);
     }
@@ -3101,7 +3448,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();
@@ -3176,11 +3523,34 @@ 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) {
+        const gapKey = `${this.deliveryWatermark}:${base}`;
+        this.deliveryGapRepeatCount = this.lastDeliveryGapKey === gapKey ? this.deliveryGapRepeatCount + 1 : 1;
+        this.lastDeliveryGapKey = gapKey;
+        this.emitter?.emit({
+          type: "sync:delivery-gap",
+          expectedBase: this.deliveryWatermark,
+          receivedBase: base,
+          currentWatermark: this.deliveryWatermark,
+          messageId: msg.messageId,
+          repeatCount: this.deliveryGapRepeatCount
+        });
+        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) {
@@ -3192,6 +3562,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,
@@ -3202,11 +3573,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) {
@@ -3217,18 +3585,29 @@ 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.deliveryGapRepeatCount = 0;
+      this.lastDeliveryGapKey = null;
+      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;
@@ -3236,15 +3615,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);
@@ -3253,26 +3634,51 @@ var SyncEngine = class {
       }
     }
   }
-  handleAcknowledgment(msg) {
+  /** 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);
+  }
+  async handleAcknowledgment(msg) {
+    this.clearOutboundAckTimer();
     if (this.state === "syncing" && this.config.strictHandshake) {
       this.pendingDeltaBatchAcks.delete(msg.acknowledgedMessageId);
       this.markDeltaSendCompleteIfReady();
     }
     if (this.currentBatch) {
-      this.outboundQueue.acknowledge(this.currentBatch.batchId);
+      if (this.currentBatchRequiresPartialAck) {
+        await this.outboundQueue.acknowledgeThrough(
+          this.currentBatch.batchId,
+          msg.lastSequenceNumber
+        );
+      } else {
+        await this.outboundQueue.acknowledge(this.currentBatch.batchId);
+      }
       this.currentBatch = null;
+      this.currentBatchRequiresPartialAck = false;
       const now = Date.now();
       this.lastSyncedAt = now;
       this.lastSuccessfulPush = now;
     }
-    void this.advanceLastAckedForLocalNode(msg.lastSequenceNumber).then(
-      () => this.refreshPendingCount()
-    );
+    await this.advanceLastAckedForLocalNode(msg.lastSequenceNumber);
+    await this.refreshPendingCount();
     if (this.state === "streaming" && this.outboundQueue.hasOperations) {
       this.flushQueue();
     }
   }
   handleError(msg) {
+    this.clearOutboundAckTimer();
+    if (this.currentBatch) {
+      this.outboundQueue.returnBatch(this.currentBatch.batchId);
+      this.currentBatch = null;
+      this.currentBatchRequiresPartialAck = false;
+    }
     this.transitionTo("error");
     if (msg.code === "AUTH_FAILED") {
       this.emitter?.emit({ type: "sync:auth-failed", reason: msg.message });
@@ -3291,6 +3697,64 @@ var SyncEngine = class {
     this.emitter?.emit({ type: "sync:disconnected", reason: msg.message });
     this.transitionTo("disconnected");
   }
+  /**
+   * Handle a per-operation rejection: divert the op out of the pending outbound
+   * queue (so it is never retried or resurrected on reconnect), record it in the
+   * durable rejected store (so it is kept and explainable), and emit an event so
+   * the app can reconcile. Unlike {@link handleError}, this is a normal per-op
+   * signal, so the connection stays up.
+   */
+  async handleOperationRejected(msg) {
+    if (msg.retriable) {
+      this.currentBatchRequiresPartialAck = true;
+      await this.refreshPendingCount();
+      this.emitter?.emit({
+        type: "sync:operation-rejected",
+        operationId: msg.operationId,
+        collection: msg.collection,
+        recordId: msg.recordId,
+        code: msg.code,
+        message: msg.message,
+        retriable: true
+      });
+      return;
+    }
+    await this.outboundQueue.reject(msg.operationId);
+    await this.rejectedStorage.record({
+      operationId: msg.operationId,
+      collection: msg.collection,
+      recordId: msg.recordId,
+      code: msg.code,
+      message: msg.message,
+      retriable: msg.retriable,
+      rejectedAt: Date.now()
+    });
+    await this.refreshPendingCount();
+    this.emitter?.emit({
+      type: "sync:operation-rejected",
+      operationId: msg.operationId,
+      collection: msg.collection,
+      recordId: msg.recordId,
+      code: msg.code,
+      message: msg.message,
+      retriable: msg.retriable
+    });
+  }
+  /**
+   * Every operation the server rejected that has not yet been reconciled. The app
+   * uses this (alongside the `sync:operation-rejected` event) to surface failed
+   * submissions and decide whether to roll back or resubmit.
+   */
+  getRejectedOperations() {
+    return this.rejectedStorage.list();
+  }
+  /**
+   * Forget rejected operations by id once the app has reconciled them (rolled the
+   * optimistic write back or resubmitted a corrected op).
+   */
+  clearRejectedOperations(operationIds) {
+    return this.rejectedStorage.remove(operationIds);
+  }
   async checkDeltaComplete() {
     if (!this.deltaSendComplete || !this.deltaReceiveComplete) {
       return;
@@ -3389,7 +3853,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);
     }
@@ -3400,6 +3864,7 @@ var SyncEngine = class {
     const batch = this.outboundQueue.takeBatch(this.batchSize);
     if (!batch) return;
     this.currentBatch = batch;
+    this.currentBatchRequiresPartialAck = false;
     if (this.encryptor) {
       this.encryptor.encryptBatch(batch.operations).then(
         (encrypted) => {
@@ -3412,6 +3877,7 @@ var SyncEngine = class {
             batchIndex: 0
           };
           this.transport.send(batchMsg);
+          this.startOutboundAckTimer(batch.batchId);
           this.emitter?.emit({
             type: "sync:sent",
             operations: batch.operations,
@@ -3421,6 +3887,7 @@ var SyncEngine = class {
         (err) => {
           this.outboundQueue.returnBatch(batch.batchId);
           this.currentBatch = null;
+          this.currentBatchRequiresPartialAck = false;
           this.emitter?.emit({
             type: "sync:disconnected",
             reason: err instanceof Error ? err.message : "Encryption failed"
@@ -3437,6 +3904,7 @@ var SyncEngine = class {
         batchIndex: 0
       };
       this.transport.send(batchMsg);
+      this.startOutboundAckTimer(batch.batchId);
       this.emitter?.emit({
         type: "sync:sent",
         operations: batch.operations,
@@ -3444,6 +3912,34 @@ 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.currentBatchRequiresPartialAck = false;
+    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",
@@ -3453,9 +3949,11 @@ var SyncEngine = class {
     this.awarenessManager.handleRemoteMessage(awarenessMessage);
   }
   handleTransportClose(reason) {
+    this.clearOutboundAckTimer();
     if (this.currentBatch) {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
       this.currentBatch = null;
+      this.currentBatchRequiresPartialAck = false;
     }
     if (this.schemaBlocked) {
       return;
@@ -3487,11 +3985,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 this.matchesScopeAndSubsets(op, fullRecord);
+  }
+  matchesScopeAndSubsets(op, fullRecord) {
+    if (!operationMatchesScope(op, this.activeScope, fullRecord)) {
       return false;
     }
-    return operationMatchesQuerySubsets(op, this.getActiveQuerySubsets());
+    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) {
@@ -3499,6 +4026,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);
@@ -3511,8 +4044,7 @@ var SyncEngine = class {
     }, 500);
   }
   async reconnectForQuerySubsets() {
-    await this.stop();
-    await this.start();
+    await this.reconnect();
   }
 };
 function awarenessStatesToWire(states) {
@@ -4193,6 +4725,7 @@ function fromBase642(str) {
 // src/reactivity/sync-status-controller.ts
 var OFFLINE_SYNC_STATUS = Object.freeze({
   status: "offline",
+  reconnecting: false,
   pendingOperations: 0,
   lastSyncedAt: null,
   lastSuccessfulPush: null,
@@ -4210,6 +4743,7 @@ var SYNC_STATUS_EVENT_TYPES = [
   "sync:received",
   "sync:acknowledged",
   "sync:apply-failed",
+  "sync:delivery-gap",
   "sync:diagnostics",
   "sync:initial-sync-progress"
 ];
@@ -4355,6 +4889,7 @@ export {
   InvalidScopeError,
   JsonMessageSerializer,
   KeyDerivationError,
+  MemoryRejectedOperationStorage,
   NegotiatedMessageSerializer,
   OFFLINE_SYNC_STATUS,
   OutboundQueue,
@@ -4393,6 +4928,7 @@ export {
   isHandshakeMessage,
   isHandshakeResponseMessage,
   isOperationBatchMessage,
+  isOperationRejectedMessage,
   isSchemaMismatchReject,
   isSyncMessage,
   isYjsDocUpdateMessage,