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

package/dist/index.cjs

@@ -86,6 +86,7 @@ __export(index_exports, {
   isYjsDocUpdateMessage: () => isYjsDocUpdateMessage,
   operationMatchesQuerySubsets: () => operationMatchesQuerySubsets,
   operationMatchesScope: () => operationMatchesScope,
+  querySubsetContains: () => querySubsetContains,
   richtextDocKey: () => richtextDocKey,
   sliceOperationsAfterCursor: () => sliceOperationsAfterCursor,
   subscribeRemoteAwarenessStates: () => subscribeRemoteAwarenessStates,
@@ -112,7 +113,8 @@ var SYNC_STATUSES = [
   "offline",
   "clock-error",
   "error",
-  "schema-mismatch"
+  "schema-mismatch",
+  "auth-required"
 ];
 var MemoryRejectedOperationStorage = class {
   rejected = /* @__PURE__ */ new Map();
@@ -160,12 +162,19 @@ function operationMatchesScope(op, scopeMap, fullRecord) {
   const snapshot = buildSnapshot(op, fullRecord ?? void 0);
   if (!snapshot) return false;
   for (const [field, expected] of Object.entries(collectionScope)) {
-    if (snapshot[field] !== expected) {
+    if (!matchesPredicate(snapshot[field], expected)) {
       return false;
     }
   }
   return true;
 }
+function matchesPredicate(actual, expected) {
+  if (expected && typeof expected === "object" && !Array.isArray(expected) && "$in" in expected) {
+    const values = expected.$in;
+    return Array.isArray(values) && values.some((value) => Object.is(actual, value));
+  }
+  return Object.is(actual, expected);
+}
 function filterOperationsByScope(operations, scopeMap) {
   if (!scopeMap) return operations;
   return operations.filter((op) => operationMatchesScope(op, scopeMap));
@@ -222,24 +231,77 @@ function operationMatchesQuerySubsets(op, subsets, fullRecord) {
   if (collectionSubsets.length === 0) {
     return true;
   }
+  if (collectionSubsets.some((subset) => Object.keys(subset.where).length === 0)) {
+    return true;
+  }
   const snapshot = buildSnapshot2(op, fullRecord);
   if (!snapshot) {
     return false;
   }
   return collectionSubsets.some((subset) => recordMatchesWhere(snapshot, subset.where));
 }
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, stableValue(entry)])
+    );
+  }
+  return value;
+}
+function whereContains(broad, narrow) {
+  return Object.entries(broad).every(
+    ([field, expected]) => JSON.stringify(stableValue(narrow[field])) === JSON.stringify(stableValue(expected))
+  );
+}
 function dedupeQuerySubsets(subsets) {
-  const seen = /* @__PURE__ */ new Set();
+  const normalized = subsets.map((subset) => ({
+    collection: subset.collection,
+    where: stableValue(subset.where)
+  }));
   const result = [];
-  for (const subset of subsets) {
-    const key = `${subset.collection}:${JSON.stringify(subset.where)}`;
-    if (seen.has(key)) {
+  for (const candidate of normalized) {
+    if (normalized.some(
+      (other) => other !== candidate && other.collection === candidate.collection && whereContains(other.where, candidate.where) && (Object.keys(other.where).length < Object.keys(candidate.where).length || JSON.stringify(other.where) === JSON.stringify(candidate.where))
+    )) {
+      const duplicateAlreadyKept = result.some(
+        (item) => item.collection === candidate.collection && JSON.stringify(item.where) === JSON.stringify(candidate.where)
+      );
+      if (duplicateAlreadyKept || normalized.some(
+        (other) => other !== candidate && other.collection === candidate.collection && Object.keys(other.where).length < Object.keys(candidate.where).length && whereContains(other.where, candidate.where)
+      ))
+        continue;
+    }
+    if (!result.some(
+      (item) => item.collection === candidate.collection && JSON.stringify(item.where) === JSON.stringify(candidate.where)
+    ))
+      result.push(candidate);
+  }
+  return result.sort(
+    (a, b) => `${a.collection}:${JSON.stringify(a.where)}`.localeCompare(
+      `${b.collection}:${JSON.stringify(b.where)}`
+    )
+  );
+}
+function querySubsetContains(broad, narrow) {
+  const collections = /* @__PURE__ */ new Set([
+    ...broad.map((subset) => subset.collection),
+    ...narrow.map((subset) => subset.collection)
+  ]);
+  for (const collection of collections) {
+    const broadForCollection = broad.filter((subset) => subset.collection === collection);
+    const narrowForCollection = narrow.filter((subset) => subset.collection === collection);
+    if (narrowForCollection.length === 0) {
+      if (broadForCollection.length > 0) return false;
       continue;
     }
-    seen.add(key);
-    result.push(subset);
+    if (broadForCollection.length === 0) continue;
+    if (!narrowForCollection.every(
+      (candidate) => broadForCollection.some((other) => whereContains(other.where, candidate.where))
+    ))
+      return false;
   }
-  return result;
+  return true;
 }
 
 // src/delta/delta-cursor.ts
@@ -622,7 +684,8 @@ function toProtoEnvelope(message) {
         schemaVersion: message.schemaVersion,
         authToken: message.authToken,
         supportedWireFormats: message.supportedWireFormats,
-        ...message.lastDeliverySequence !== void 0 ? { lastDeliverySequence: message.lastDeliverySequence } : {}
+        ...message.lastDeliverySequence !== void 0 ? { lastDeliverySequence: message.lastDeliverySequence } : {},
+        scopeExitPolicy: message.scopeExitPolicy
       };
     case "handshake-response":
       return {
@@ -639,7 +702,10 @@ function toProtoEnvelope(message) {
         selectedWireFormat: message.selectedWireFormat,
         serverTime: message.serverTime,
         blobStorageEnabled: message.blobStorageEnabled,
-        ...message.serverMaxDeliverySequence !== void 0 ? { serverMaxDeliverySequence: message.serverMaxDeliverySequence } : {}
+        ...message.serverMaxDeliverySequence !== void 0 ? { serverMaxDeliverySequence: message.serverMaxDeliverySequence } : {},
+        acceptedScopeJson: message.acceptedScope ? JSON.stringify(message.acceptedScope) : void 0,
+        acceptedDownlinkScopesJson: message.acceptedDownlinkScopes ? JSON.stringify(message.acceptedDownlinkScopes) : void 0,
+        acceptedUplinkScopesJson: message.acceptedUplinkScopes ? JSON.stringify(message.acceptedUplinkScopes) : void 0
       };
     case "operation-batch":
       return {
@@ -649,7 +715,8 @@ function toProtoEnvelope(message) {
         isFinal: message.isFinal,
         batchIndex: message.batchIndex,
         ...message.baseDeliverySequence !== void 0 ? { baseDeliverySequence: message.baseDeliverySequence } : {},
-        ...message.maxDeliverySequence !== void 0 ? { maxDeliverySequence: message.maxDeliverySequence } : {}
+        ...message.maxDeliverySequence !== void 0 ? { maxDeliverySequence: message.maxDeliverySequence } : {},
+        retractionsJson: message.retractions ? JSON.stringify(message.retractions) : void 0
       };
     case "acknowledgment":
       return {
@@ -723,7 +790,8 @@ function fromProtoEnvelope(envelope) {
         supportedWireFormats: envelope.supportedWireFormats?.filter(
           (format) => format === "json" || format === "protobuf"
         ),
-        ...envelope.lastDeliverySequence !== void 0 ? { lastDeliverySequence: envelope.lastDeliverySequence } : {}
+        ...envelope.lastDeliverySequence !== void 0 ? { lastDeliverySequence: envelope.lastDeliverySequence } : {},
+        ...envelope.scopeExitPolicy === "retain" || envelope.scopeExitPolicy === "retract" ? { scopeExitPolicy: envelope.scopeExitPolicy } : {}
       };
     case "handshake-response":
       return {
@@ -741,7 +809,10 @@ function fromProtoEnvelope(envelope) {
         // 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.serverMaxDeliverySequence !== void 0 ? { serverMaxDeliverySequence: envelope.serverMaxDeliverySequence } : {}
+        ...envelope.serverMaxDeliverySequence !== void 0 ? { serverMaxDeliverySequence: envelope.serverMaxDeliverySequence } : {},
+        ...envelope.acceptedScopeJson ? { acceptedScope: JSON.parse(envelope.acceptedScopeJson) } : {},
+        ...envelope.acceptedDownlinkScopesJson ? { acceptedDownlinkScopes: JSON.parse(envelope.acceptedDownlinkScopesJson) } : {},
+        ...envelope.acceptedUplinkScopesJson ? { acceptedUplinkScopes: JSON.parse(envelope.acceptedUplinkScopesJson) } : {}
       };
     case "operation-batch":
       return {
@@ -751,7 +822,8 @@ function fromProtoEnvelope(envelope) {
         isFinal: envelope.isFinal ?? false,
         batchIndex: envelope.batchIndex ?? 0,
         ...envelope.baseDeliverySequence !== void 0 ? { baseDeliverySequence: envelope.baseDeliverySequence } : {},
-        ...envelope.maxDeliverySequence !== void 0 ? { maxDeliverySequence: envelope.maxDeliverySequence } : {}
+        ...envelope.maxDeliverySequence !== void 0 ? { maxDeliverySequence: envelope.maxDeliverySequence } : {},
+        ...envelope.retractionsJson ? { retractions: JSON.parse(envelope.retractionsJson) } : {}
       };
     case "acknowledgment":
       return {
@@ -969,6 +1041,13 @@ function encodeEnvelope(envelope) {
   if (envelope.deliverySequence !== void 0) writer.uint32(256).int64(envelope.deliverySequence);
   if (envelope.serverMaxDeliverySequence !== void 0)
     writer.uint32(264).int64(envelope.serverMaxDeliverySequence);
+  if (envelope.acceptedScopeJson) writer.uint32(274).string(envelope.acceptedScopeJson);
+  if (envelope.acceptedDownlinkScopesJson)
+    writer.uint32(282).string(envelope.acceptedDownlinkScopesJson);
+  if (envelope.acceptedUplinkScopesJson)
+    writer.uint32(290).string(envelope.acceptedUplinkScopesJson);
+  if (envelope.retractionsJson) writer.uint32(298).string(envelope.retractionsJson);
+  if (envelope.scopeExitPolicy) writer.uint32(306).string(envelope.scopeExitPolicy);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -1079,6 +1158,21 @@ function decodeEnvelope(bytes) {
       case 33:
         envelope.serverMaxDeliverySequence = longToNumber(reader.int64());
         break;
+      case 34:
+        envelope.acceptedScopeJson = reader.string();
+        break;
+      case 35:
+        envelope.acceptedDownlinkScopesJson = reader.string();
+        break;
+      case 36:
+        envelope.acceptedUplinkScopesJson = reader.string();
+        break;
+      case 37:
+        envelope.retractionsJson = reader.string();
+        break;
+      case 38:
+        envelope.scopeExitPolicy = reader.string();
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -2744,6 +2838,18 @@ var OutboundQueue = class {
     await this.storage.dequeue([opId]);
     return removed;
   }
+  /** Remove every pending/in-flight operation for a record so authorization loss cannot upload it. */
+  async rejectRecord(collection, recordId) {
+    const matching = [...this.queue, ...[...this.inFlight.values()].flat()].filter(
+      (op) => op.collection === collection && op.recordId === recordId
+    );
+    const removed = [];
+    for (const operation of matching) {
+      const rejected = await this.reject(operation.id);
+      if (rejected) removed.push(rejected);
+    }
+    return removed;
+  }
   /**
    * Remove operations by id from queue and persistent storage.
    * Used when ops were already sent during handshake delta exchange.
@@ -2763,6 +2869,8 @@ var OutboundQueue = class {
 var DEFAULT_BATCH_SIZE = 100;
 var DEFAULT_SCHEMA_VERSION = 1;
 var DEFAULT_OUTBOUND_ACK_TIMEOUT_MS = 3e4;
+var DEFAULT_OUTBOUND_RETRY_BASE_DELAY_MS = 250;
+var DEFAULT_OUTBOUND_RETRY_MAX_DELAY_MS = 3e4;
 var VALID_TRANSITIONS = {
   disconnected: ["connecting"],
   connecting: ["handshaking", "error", "disconnected"],
@@ -2798,6 +2906,8 @@ var SyncEngine = class {
   rejectedStorage;
   batchSize;
   outboundAckTimeoutMs;
+  outboundRetryBaseDelayMs;
+  outboundRetryMaxDelayMs;
   encryptor;
   awarenessManager;
   richtextDocChannel;
@@ -2813,11 +2923,19 @@ var SyncEngine = class {
   conflictCount = 0;
   currentBatch = null;
   currentBatchRequiresPartialAck = false;
+  currentBatchRequiresRetryBackoff = false;
+  outboundRetryAttempt = 0;
+  outboundRetryTimer = null;
   reconnecting = false;
   schemaBlocked = false;
   clockBlocked = false;
   clockSkewMs = null;
   blobStorageEnabled = false;
+  suspensionReason = null;
+  authRejected = false;
+  serverFrontier = null;
+  hasInFlightDeliveryBatch = false;
+  blockedFailure = null;
   outboundAckTimer = null;
   startPromise = null;
   stopPromise = null;
@@ -2836,8 +2954,12 @@ var SyncEngine = class {
    * with the server-accepted scope (server is authoritative).
    */
   activeScope;
+  /** Server-authoritative upload authorization, separate from the downloaded view. */
+  activeUplinkScope;
+  hasDirectionalScopes = false;
   /** Live query subsets registered from reactive subscriptions */
   querySubsets = /* @__PURE__ */ new Map();
+  staticQuerySubsets = [];
   querySubsetReconnectTimer = null;
   /** Resume cursor for paginated initial sync (persisted across reconnects) */
   resumeDeltaCursor = null;
@@ -2871,9 +2993,18 @@ var SyncEngine = class {
     this.emitter = options.emitter ?? null;
     this.batchSize = options.config.batchSize ?? DEFAULT_BATCH_SIZE;
     this.outboundAckTimeoutMs = options.config.outboundAckTimeoutMs ?? DEFAULT_OUTBOUND_ACK_TIMEOUT_MS;
+    this.outboundRetryBaseDelayMs = Math.max(
+      0,
+      options.config.outboundRetryBaseDelayMs ?? DEFAULT_OUTBOUND_RETRY_BASE_DELAY_MS
+    );
+    this.outboundRetryMaxDelayMs = Math.max(
+      this.outboundRetryBaseDelayMs,
+      options.config.outboundRetryMaxDelayMs ?? DEFAULT_OUTBOUND_RETRY_MAX_DELAY_MS
+    );
     this.encryptor = options.encryptor ?? null;
     this.syncState = options.syncState ?? null;
     this.activeScope = options.config.scopeMap;
+    this.activeUplinkScope = options.config.scopeMap;
     const queueStorage = options.queueStorage ?? new MemoryQueueStorage();
     this.outboundQueue = new OutboundQueue(queueStorage);
     this.rejectedStorage = options.rejectedStorage ?? new MemoryRejectedOperationStorage();
@@ -2931,6 +3062,22 @@ var SyncEngine = class {
     if (this.state !== "disconnected") {
       await this.stop();
     }
+    if (this.authRejected) {
+      this.emitter?.emit({
+        type: "sync:suspended",
+        reason: this.suspensionReason ?? "auth-rejected"
+      });
+      return;
+    }
+    if (this.config.authState) {
+      const authState = await this.config.authState();
+      if (authState.state === "loading" || authState.state === "signed-out") {
+        this.suspensionReason = authState.state === "loading" ? "auth-loading" : "auth-required";
+        this.emitter?.emit({ type: "sync:suspended", reason: this.suspensionReason });
+        return;
+      }
+    }
+    this.suspensionReason = null;
     await this.outboundQueue.initialize();
     if (this.syncState) {
       this.lastAckedServerVector = await this.syncState.loadLastAckedServerVector();
@@ -2980,6 +3127,7 @@ var SyncEngine = class {
         authToken,
         supportedWireFormats: ["json", "protobuf"],
         ...this.config.scopeMap ? { syncScope: this.config.scopeMap } : {},
+        ...this.config.scopeExit ? { scopeExitPolicy: this.config.scopeExit } : {},
         ...activeQuerySubsets.length > 0 ? { syncQueries: activeQuerySubsets } : {},
         ...this.resumeDeltaCursor ? { deltaCursor: encodeDeltaCursor(this.resumeDeltaCursor) } : {},
         // Resume the server's gap-free delivery stream from our watermark. A server
@@ -3004,13 +3152,15 @@ var SyncEngine = class {
     return this.stopPromise;
   }
   async stopInternal() {
-    if (this.state === "disconnected") return;
     this.clearOutboundAckTimer();
+    this.clearOutboundRetryTimer();
+    if (this.state === "disconnected") return;
     this.awarenessManager.stopCleanupTimer();
     if (this.currentBatch) {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
       this.currentBatch = null;
       this.currentBatchRequiresPartialAck = false;
+      this.currentBatchRequiresRetryBackoff = false;
     }
     try {
       await this.transport.disconnect();
@@ -3060,14 +3210,30 @@ var SyncEngine = class {
   getStatus() {
     const pendingOperations = this.syncState ? this.cachedUnsyncedCount : this.outboundQueue.totalPending;
     const base = {
+      phase: this.resolvePhase(),
+      ...this.suspensionReason ? { reason: this.suspensionReason } : {},
       reconnecting: this.reconnecting,
       pendingOperations,
       lastSyncedAt: this.lastSyncedAt,
       lastSuccessfulPush: this.lastSuccessfulPush,
       lastSuccessfulPull: this.lastSuccessfulPull,
       conflicts: this.conflictCount,
-      clockSkewMs: this.clockSkewMs
+      clockSkewMs: this.clockSkewMs,
+      inFlightUploadOperations: this.currentBatch?.operations.length ?? 0,
+      hasInFlightDeliveryBatch: this.hasInFlightDeliveryBatch,
+      activeViewId: this.deliverySignature(),
+      activeViewComplete: this.state === "streaming" && !this.hasInFlightDeliveryBatch && this.blockedFailure === null && (this.serverFrontier === null || this.deliveryWatermark >= this.serverFrontier),
+      initialSync: {
+        complete: this.deltaReceiveComplete && this.deltaSendComplete,
+        receivedBatches: this.deltaBatchesReceived,
+        totalBatches: this.initialSyncTotalBatches || null,
+        progress: this.initialSyncTotalBatches > 0 ? Math.min(1, this.deltaBatchesReceived / this.initialSyncTotalBatches) : null
+      },
+      deliveryWatermark: this.deliveryWatermark,
+      serverFrontier: this.serverFrontier,
+      blockedFailure: this.blockedFailure
     };
+    if (this.suspensionReason) return { ...base, status: "auth-required" };
     switch (this.state) {
       case "disconnected":
         if (this.clockBlocked) {
@@ -3090,6 +3256,26 @@ var SyncEngine = class {
         return { ...base, status: this.schemaBlocked ? "schema-mismatch" : "error" };
     }
   }
+  resolvePhase() {
+    if (this.suspensionReason) return "suspended";
+    if (this.blockedFailure || this.schemaBlocked || this.clockBlocked) return "blocked";
+    if (this.hasInFlightDeliveryBatch) return "applying";
+    if (this.currentBatch) return "uploading";
+    switch (this.state) {
+      case "disconnected":
+        return "offline";
+      case "connecting":
+        return "connecting";
+      case "handshaking":
+        return "handshaking";
+      case "syncing":
+        return "receiving";
+      case "streaming":
+        return "streaming";
+      case "error":
+        return "blocked";
+    }
+  }
   /**
    * True when the server rejected the client's schema version at handshake.
    * Sync stays blocked until the app schema is upgraded or sync config changes.
@@ -3142,8 +3328,25 @@ var SyncEngine = class {
     await this.refreshPendingCount();
     return this.getStatus().pendingOperations;
   }
-  emitApplyFailure(op, result, overrides) {
+  emitApplyFailure(op, result, overrides, blocking = false) {
     const reason = (0, import_core7.defaultApplyFailureReason)(result, overrides);
+    if (blocking || reason.retriable) {
+      const prior = this.blockedFailure;
+      this.blockedFailure = {
+        operationId: op.id,
+        collection: op.collection,
+        recordId: op.recordId,
+        code: reason.code,
+        message: reason.message,
+        retriable: reason.retriable,
+        firstSeenAt: prior?.operationId === op.id ? prior.firstSeenAt : Date.now(),
+        retryCount: prior?.operationId === op.id ? prior.retryCount + 1 : 0
+      };
+      this.emitter?.emit({
+        type: prior?.operationId === op.id ? "sync:apply-retrying" : "sync:apply-blocked",
+        failure: this.blockedFailure
+      });
+    }
     this.emitter?.emit({
       type: "sync:apply-failed",
       operationId: op.id,
@@ -3160,11 +3363,18 @@ var SyncEngine = class {
    */
   async retryNow() {
     if (this.schemaBlocked) return;
+    this.authRejected = false;
+    this.suspensionReason = null;
     if (this.state === "disconnected" || this.state === "error") {
       this.reconnecting = false;
       await this.start();
     }
   }
+  /** Wake a permanent auth suspension after the binding reports a new auth state. */
+  notifyAuthChanged() {
+    this.authRejected = false;
+    this.suspensionReason = null;
+  }
   /**
    * Atomically refresh the transport session. Overlapping callers share one
    * reconnect, in-flight outbound batches are returned to the queue by stop(), and the
@@ -3233,6 +3443,8 @@ var SyncEngine = class {
   updateScope(scopeMap) {
     const previousSignature = this.deliverySignature();
     this.activeScope = scopeMap;
+    this.activeUplinkScope = scopeMap;
+    this.hasDirectionalScopes = false;
     this.config.scopeMap = scopeMap;
     this.switchDeliveryView(previousSignature);
   }
@@ -3316,28 +3528,58 @@ var SyncEngine = class {
   getActiveScope() {
     return this.activeScope;
   }
+  /** Get the server-accepted upload authorization scope. */
+  getActiveUplinkScope() {
+    return this.activeUplinkScope;
+  }
   /**
    * Register a live query subset that narrows synced data for a collection.
    * Takes effect on the next connection; reconnects when already connected.
    */
   registerQuerySubset(subset) {
+    if ((this.config.querySubsets?.mode ?? "reactive") !== "reactive") return () => {
+    };
     const id = `query-${nextQuerySubsetId++}`;
     const previousSignature = this.deliverySignature();
+    const previousEffective = this.getActiveQuerySubsets();
     this.querySubsets.set(id, subset);
-    this.switchDeliveryView(previousSignature);
-    this.scheduleQuerySubsetReconnect();
+    this.switchDeliveryViewWithInheritance(previousSignature, previousEffective);
+    if (this.deliverySignature() !== previousSignature) this.scheduleQuerySubsetReconnect();
     return () => {
       const sigBeforeRemove = this.deliverySignature();
+      const effectiveBeforeRemove = this.getActiveQuerySubsets();
       this.querySubsets.delete(id);
-      this.switchDeliveryView(sigBeforeRemove);
-      this.scheduleQuerySubsetReconnect();
+      this.switchDeliveryViewWithInheritance(sigBeforeRemove, effectiveBeforeRemove);
+      if (this.deliverySignature() !== sigBeforeRemove) this.scheduleQuerySubsetReconnect();
     };
   }
+  switchDeliveryViewWithInheritance(previousSignature, previousSubsets) {
+    const nextSubsets = this.getActiveQuerySubsets();
+    const previousWatermark = this.deliveryWatermark;
+    this.switchDeliveryView(previousSignature);
+    if (this.deliveryWatermark === 0 && querySubsetContains(previousSubsets, nextSubsets)) {
+      this.deliveryWatermark = previousWatermark;
+      this.setViewWatermark(this.deliverySignature(), previousWatermark);
+      void this.persistDeliveryWatermark(previousWatermark);
+    }
+  }
+  /** Atomically replace the manifest used by static query-subset mode. */
+  setQuerySubsets(subsets) {
+    if ((this.config.querySubsets?.mode ?? "reactive") !== "static")
+      throw new Error('setQuerySubsets() requires sync.querySubsets.mode = "static"');
+    const previousSignature = this.deliverySignature();
+    const previousEffective = this.getActiveQuerySubsets();
+    this.staticQuerySubsets = dedupeQuerySubsets(subsets);
+    this.switchDeliveryViewWithInheritance(previousSignature, previousEffective);
+    if (this.deliverySignature() !== previousSignature) this.scheduleQuerySubsetReconnect();
+  }
   /**
    * Returns deduplicated active query subsets from registered subscriptions.
    */
   getActiveQuerySubsets() {
-    return dedupeQuerySubsets([...this.querySubsets.values()]);
+    const mode = this.config.querySubsets?.mode ?? "reactive";
+    if (mode === "disabled") return [];
+    return mode === "static" ? this.staticQuerySubsets : dedupeQuerySubsets([...this.querySubsets.values()]);
   }
   /**
    * Get the awareness manager for collaborative presence.
@@ -3414,6 +3656,7 @@ var SyncEngine = class {
     }
   }
   handleMessageFailure(error) {
+    this.hasInFlightDeliveryBatch = false;
     const reason = error instanceof Error ? error.message : "Message handling failed";
     this.handleTransportClose(reason);
   }
@@ -3487,11 +3730,21 @@ var SyncEngine = class {
       this.setViewWatermark(this.deliverySignature(), 0);
       await this.persistDeliveryWatermark(0);
     }
+    this.serverFrontier = msg.serverMaxDeliverySequence ?? null;
     if (msg.selectedWireFormat) {
       this.setSerializerWireFormat(msg.selectedWireFormat);
     }
-    if (msg.acceptedScope) {
-      this.activeScope = msg.acceptedScope;
+    if (msg.acceptedDownlinkScopes ?? msg.acceptedScope) {
+      this.activeScope = msg.acceptedDownlinkScopes ?? msg.acceptedScope;
+    }
+    this.hasDirectionalScopes = msg.acceptedUplinkScopes !== void 0;
+    this.activeUplinkScope = msg.acceptedUplinkScopes ?? msg.acceptedScope ?? this.activeScope;
+    if (this.config.scopeExit === "retract" && this.activeScope && this.store.applyScopeNarrowing) {
+      const narrowed = await this.store.applyScopeNarrowing(this.activeScope);
+      for (const retraction of narrowed) {
+        await this.applyScopeRetraction(retraction, false);
+      }
+      await this.refreshPendingCount();
     }
     this.emitter?.emit({ type: "sync:connected", nodeId: this.store.getNodeId() });
     this.metricsCollector.recordConnected();
@@ -3648,6 +3901,7 @@ var SyncEngine = class {
         this.sendDeliveryAck(msg.messageId, this.deliveryWatermark);
         return;
       }
+      this.hasInFlightDeliveryBatch = true;
     }
     const deserialized = msg.operations.map((s) => this.serializer.decodeOperation(s));
     const operations = this.encryptor ? await this.encryptor.decryptBatch(deserialized) : deserialized;
@@ -3655,6 +3909,14 @@ var SyncEngine = class {
     const targetSchemaVersion = this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
     const transforms = this.config.operationTransforms ?? [];
     let fullyApplied = true;
+    for (const retraction of msg.retractions ?? []) {
+      try {
+        await this.applyScopeRetraction(retraction, true);
+      } catch {
+        fullyApplied = false;
+      }
+    }
+    await this.refreshPendingCount();
     for (const op of inScopeOps) {
       const transformed = transforms.length > 0 ? (0, import_core7.applyOperationTransforms)(op, targetSchemaVersion, transforms) : op;
       if (transformed === null) {
@@ -3668,17 +3930,22 @@ var SyncEngine = class {
       } catch (error) {
         fullyApplied = false;
         if (error instanceof import_core7.ClockDriftError) {
-          this.emitApplyFailure(transformed, "rejected", {
-            code: import_core7.APPLY_FAILURE_CODES.CLOCK_DRIFT,
-            message: error.message,
-            retriable: false
-          });
+          this.emitApplyFailure(
+            transformed,
+            "rejected",
+            {
+              code: import_core7.APPLY_FAILURE_CODES.CLOCK_DRIFT,
+              message: error.message,
+              retriable: false
+            },
+            true
+          );
           continue;
         }
         const message = error instanceof Error ? error.message : "Apply failed";
         const code = error instanceof import_core7.SyncError ? error.code : error instanceof import_core7.KoraError ? error.code : error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : import_core7.APPLY_FAILURE_CODES.APPLY_FAILED;
         const retriable = code !== import_core7.APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY;
-        this.emitApplyFailure(transformed, "rejected", { code, message, retriable });
+        this.emitApplyFailure(transformed, "rejected", { code, message, retriable }, true);
       }
     }
     if (inScopeOps.length > 0) {
@@ -3711,7 +3978,13 @@ var SyncEngine = class {
       this.deliveryWatermark = msg.maxDeliverySequence;
       this.setViewWatermark(this.deliverySignature(), this.deliveryWatermark);
       await this.persistDeliveryWatermark(this.deliveryWatermark);
+      if (this.blockedFailure && inScopeOps.some((op) => op.id === this.blockedFailure?.operationId)) {
+        const recovered = this.blockedFailure;
+        this.blockedFailure = null;
+        this.emitter?.emit({ type: "sync:apply-recovered", failure: recovered });
+      }
     }
+    this.hasInFlightDeliveryBatch = false;
     if (this.state === "syncing") {
       this.deltaBatchesReceived++;
       const totalBatches = msg.totalBatches ?? this.initialSyncTotalBatches;
@@ -3751,6 +4024,7 @@ var SyncEngine = class {
   }
   async handleAcknowledgment(msg) {
     this.clearOutboundAckTimer();
+    const requiresRetryBackoff = this.currentBatchRequiresRetryBackoff;
     if (this.state === "syncing" && this.config.strictHandshake) {
       this.pendingDeltaBatchAcks.delete(msg.acknowledgedMessageId);
       this.markDeltaSendCompleteIfReady();
@@ -3766,6 +4040,7 @@ var SyncEngine = class {
       }
       this.currentBatch = null;
       this.currentBatchRequiresPartialAck = false;
+      this.currentBatchRequiresRetryBackoff = false;
       const now = Date.now();
       this.lastSyncedAt = now;
       this.lastSuccessfulPush = now;
@@ -3773,7 +4048,14 @@ var SyncEngine = class {
     await this.advanceLastAckedForLocalNode(msg.lastSequenceNumber);
     await this.refreshPendingCount();
     if (this.state === "streaming" && this.outboundQueue.hasOperations) {
-      this.flushQueue();
+      if (requiresRetryBackoff) {
+        this.scheduleOutboundRetry();
+      } else {
+        this.outboundRetryAttempt = 0;
+        this.flushQueue();
+      }
+    } else if (!requiresRetryBackoff) {
+      this.outboundRetryAttempt = 0;
     }
   }
   handleError(msg) {
@@ -3782,10 +4064,14 @@ var SyncEngine = class {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
       this.currentBatch = null;
       this.currentBatchRequiresPartialAck = false;
+      this.currentBatchRequiresRetryBackoff = false;
     }
     this.transitionTo("error");
-    if (msg.code === "AUTH_FAILED") {
+    if (msg.code === "AUTH_FAILED" || msg.code === "DEVICE_REVOKED") {
+      this.authRejected = true;
+      this.suspensionReason = msg.code === "DEVICE_REVOKED" ? "device-revoked" : "auth-rejected";
       this.emitter?.emit({ type: "sync:auth-failed", reason: msg.message });
+      this.emitter?.emit({ type: "sync:suspended", reason: this.suspensionReason });
     }
     if (msg.code === "INVALID_TIMESTAMP") {
       this.clockBlocked = true;
@@ -3808,9 +4094,39 @@ var SyncEngine = class {
    * the app can reconcile. Unlike {@link handleError}, this is a normal per-op
    * signal, so the connection stays up.
    */
+  async applyScopeRetraction(retraction, applyToStore) {
+    if (applyToStore) {
+      if (!this.store.applyScopeRetraction) {
+        throw new Error("The configured sync store does not support scope retractions");
+      }
+      await this.store.applyScopeRetraction(retraction.collection, retraction.recordId);
+    }
+    const quarantined = await this.outboundQueue.rejectRecord(
+      retraction.collection,
+      retraction.recordId
+    );
+    for (const operation of quarantined) {
+      await this.rejectedStorage.record({
+        operationId: operation.id,
+        collection: operation.collection,
+        recordId: operation.recordId,
+        code: "SCOPE_RETRACTED",
+        message: "Authorization changed before this operation could be uploaded.",
+        retriable: false,
+        rejectedAt: Date.now()
+      });
+    }
+    this.emitter?.emit({
+      type: "sync:scope-retracted",
+      collection: retraction.collection,
+      recordId: retraction.recordId,
+      quarantinedOperationIds: quarantined.map((operation) => operation.id)
+    });
+  }
   async handleOperationRejected(msg) {
     if (msg.retriable) {
       this.currentBatchRequiresPartialAck = true;
+      this.currentBatchRequiresRetryBackoff = true;
       await this.refreshPendingCount();
       this.emitter?.emit({
         type: "sync:operation-rejected",
@@ -3964,11 +4280,13 @@ var SyncEngine = class {
   }
   flushQueue() {
     if (this.currentBatch) return;
+    if (this.outboundRetryTimer) return;
     if (!this.outboundQueue.hasOperations) return;
     const batch = this.outboundQueue.takeBatch(this.batchSize);
     if (!batch) return;
     this.currentBatch = batch;
     this.currentBatchRequiresPartialAck = false;
+    this.currentBatchRequiresRetryBackoff = false;
     if (this.encryptor) {
       this.encryptor.encryptBatch(batch.operations).then(
         (encrypted) => {
@@ -3992,6 +4310,7 @@ var SyncEngine = class {
           this.outboundQueue.returnBatch(batch.batchId);
           this.currentBatch = null;
           this.currentBatchRequiresPartialAck = false;
+          this.currentBatchRequiresRetryBackoff = false;
           this.emitter?.emit({
             type: "sync:disconnected",
             reason: err instanceof Error ? err.message : "Encryption failed"
@@ -4028,11 +4347,29 @@ var SyncEngine = class {
     clearTimeout(this.outboundAckTimer);
     this.outboundAckTimer = null;
   }
+  scheduleOutboundRetry() {
+    if (this.outboundRetryTimer || !this.outboundQueue.hasOperations) return;
+    const delay = Math.min(
+      this.outboundRetryMaxDelayMs,
+      this.outboundRetryBaseDelayMs * 2 ** this.outboundRetryAttempt
+    );
+    this.outboundRetryAttempt += 1;
+    this.outboundRetryTimer = setTimeout(() => {
+      this.outboundRetryTimer = null;
+      if (this.state === "streaming") this.flushQueue();
+    }, delay);
+  }
+  clearOutboundRetryTimer() {
+    if (!this.outboundRetryTimer) return;
+    clearTimeout(this.outboundRetryTimer);
+    this.outboundRetryTimer = null;
+  }
   async handleOutboundAckTimeout(batchId) {
     if (!this.currentBatch || this.currentBatch.batchId !== batchId) return;
     this.outboundQueue.returnBatch(batchId);
     this.currentBatch = null;
     this.currentBatchRequiresPartialAck = false;
+    this.currentBatchRequiresRetryBackoff = false;
     this.clearOutboundAckTimer();
     await this.refreshPendingCount();
     if (this.state === "disconnected") return;
@@ -4054,10 +4391,12 @@ var SyncEngine = class {
   }
   handleTransportClose(reason) {
     this.clearOutboundAckTimer();
+    this.clearOutboundRetryTimer();
     if (this.currentBatch) {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
       this.currentBatch = null;
       this.currentBatchRequiresPartialAck = false;
+      this.currentBatchRequiresRetryBackoff = false;
     }
     if (this.schemaBlocked) {
       return;
@@ -4100,10 +4439,10 @@ var SyncEngine = class {
     return this.matchesScopeAndSubsets(op, fullRecord);
   }
   matchesScopeAndSubsets(op, fullRecord) {
-    if (!operationMatchesScope(op, this.activeScope, fullRecord)) {
+    if (!operationMatchesScope(op, this.activeUplinkScope, fullRecord)) {
       return false;
     }
-    return operationMatchesQuerySubsets(op, this.getActiveQuerySubsets(), fullRecord);
+    return this.hasDirectionalScopes || operationMatchesQuerySubsets(op, this.getActiveQuerySubsets(), fullRecord);
   }
   async readRecordForBackfill(op) {
     if (!this.store.readRecordFields) {
@@ -4829,13 +5168,22 @@ function fromBase642(str) {
 // src/reactivity/sync-status-controller.ts
 var OFFLINE_SYNC_STATUS = Object.freeze({
   status: "offline",
+  phase: "offline",
   reconnecting: false,
   pendingOperations: 0,
   lastSyncedAt: null,
   lastSuccessfulPush: null,
   lastSuccessfulPull: null,
   conflicts: 0,
-  clockSkewMs: null
+  clockSkewMs: null,
+  inFlightUploadOperations: 0,
+  hasInFlightDeliveryBatch: false,
+  activeViewId: "",
+  activeViewComplete: false,
+  initialSync: { complete: false, receivedBatches: 0, totalBatches: null, progress: null },
+  deliveryWatermark: 0,
+  serverFrontier: null,
+  blockedFailure: null
 });
 var SYNC_STATUS_EVENT_TYPES = [
   "sync:connected",
@@ -4847,6 +5195,10 @@ var SYNC_STATUS_EVENT_TYPES = [
   "sync:received",
   "sync:acknowledged",
   "sync:apply-failed",
+  "sync:suspended",
+  "sync:apply-blocked",
+  "sync:apply-retrying",
+  "sync:apply-recovered",
   "sync:delivery-gap",
   "sync:diagnostics",
   "sync:initial-sync-progress"
@@ -5039,6 +5391,7 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   isYjsDocUpdateMessage,
   operationMatchesQuerySubsets,
   operationMatchesScope,
+  querySubsetContains,
   richtextDocKey,
   sliceOperationsAfterCursor,
   subscribeRemoteAwarenessStates,