@korajs/sync 0.6.1 → 1.0.0-beta.1

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AwarenessManager: () => AwarenessManager,
+  BlobChunkChannel: () => BlobChunkChannel,
   ChaosTransport: () => ChaosTransport,
   ConnectionMonitor: () => ConnectionMonitor,
   DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD: () => DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
@@ -55,11 +56,13 @@ __export(index_exports, {
   WebSocketTransport: () => WebSocketTransport,
   createDeltaCursorFromBatch: () => createDeltaCursorFromBatch,
   createSyncStatusController: () => createSyncStatusController,
+  decodeBlobChunkBytes: () => decodeBlobChunkBytes,
   decodeDeltaCursor: () => decodeDeltaCursor,
   decodeYjsUpdate: () => decodeYjsUpdate,
   dedupeQuerySubsets: () => dedupeQuerySubsets,
   deriveKey: () => deriveKey,
   deriveVersionedKey: () => deriveVersionedKey,
+  encodeBlobChunkBytes: () => encodeBlobChunkBytes,
   encodeDeltaCursor: () => encodeDeltaCursor,
   encodeYjsUpdate: () => encodeYjsUpdate,
   filterOperationsByScope: () => filterOperationsByScope,
@@ -67,6 +70,9 @@ __export(index_exports, {
   getRemoteAwarenessStates: () => getRemoteAwarenessStates,
   isAcknowledgmentMessage: () => isAcknowledgmentMessage,
   isAwarenessUpdateMessage: () => isAwarenessUpdateMessage,
+  isBlobChunkPushMessage: () => isBlobChunkPushMessage,
+  isBlobChunkRequestMessage: () => isBlobChunkRequestMessage,
+  isBlobChunkResponseMessage: () => isBlobChunkResponseMessage,
   isClientSchemaVersionSupported: () => isClientSchemaVersionSupported,
   isEncryptedPayload: () => isEncryptedPayload,
   isErrorMessage: () => isErrorMessage,
@@ -101,6 +107,7 @@ var SYNC_STATUSES = [
   "syncing",
   "synced",
   "offline",
+  "clock-error",
   "error",
   "schema-mismatch"
 ];
@@ -305,6 +312,12 @@ function isSyncMessage(value) {
       return isAwarenessUpdateMessage(value);
     case "yjs-doc-update":
       return isYjsDocUpdateMessage(value);
+    case "blob-chunk-request":
+      return isBlobChunkRequestMessage(value);
+    case "blob-chunk-response":
+      return isBlobChunkResponseMessage(value);
+    case "blob-chunk-push":
+      return isBlobChunkPushMessage(value);
     default:
       return false;
   }
@@ -344,6 +357,21 @@ function isYjsDocUpdateMessage(value) {
   const msg = value;
   return msg.type === "yjs-doc-update" && typeof msg.messageId === "string" && typeof msg.collection === "string" && typeof msg.recordId === "string" && typeof msg.field === "string" && typeof msg.update === "string";
 }
+function isBlobChunkRequestMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-request" && typeof msg.messageId === "string" && typeof msg.requestId === "string" && typeof msg.hash === "string";
+}
+function isBlobChunkResponseMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-response" && typeof msg.messageId === "string" && typeof msg.requestId === "string" && (typeof msg.bytes === "string" || msg.bytes === null);
+}
+function isBlobChunkPushMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-push" && typeof msg.messageId === "string" && typeof msg.hash === "string" && typeof msg.bytes === "string";
+}
 
 // src/protocol/serializer.ts
 var import_core2 = require("@korajs/core");
@@ -583,7 +611,9 @@ function toProtoEnvelope(message) {
         schemaVersion: message.schemaVersion,
         accepted: message.accepted,
         rejectReason: message.rejectReason,
-        selectedWireFormat: message.selectedWireFormat
+        selectedWireFormat: message.selectedWireFormat,
+        serverTime: message.serverTime,
+        blobStorageEnabled: message.blobStorageEnabled
       };
     case "operation-batch":
       return {
@@ -614,6 +644,28 @@ function toProtoEnvelope(message) {
         type: message.type,
         messageId: message.messageId
       };
+    case "blob-chunk-request":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        requestId: message.requestId,
+        hash: message.hash
+      };
+    case "blob-chunk-response":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        requestId: message.requestId,
+        hasBytes: message.bytes !== null,
+        ...message.bytes !== null ? { chunkBytes: message.bytes } : {}
+      };
+    case "blob-chunk-push":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        hash: message.hash,
+        chunkBytes: message.bytes
+      };
   }
 }
 function fromProtoEnvelope(envelope) {
@@ -643,7 +695,11 @@ function fromProtoEnvelope(envelope) {
         schemaVersion: envelope.schemaVersion ?? 0,
         accepted: envelope.accepted ?? false,
         rejectReason: envelope.rejectReason,
-        selectedWireFormat: envelope.selectedWireFormat === "json" || envelope.selectedWireFormat === "protobuf" ? envelope.selectedWireFormat : void 0
+        selectedWireFormat: envelope.selectedWireFormat === "json" || envelope.selectedWireFormat === "protobuf" ? envelope.selectedWireFormat : void 0,
+        // 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 } : {}
       };
     case "operation-batch":
       return {
@@ -668,6 +724,27 @@ function fromProtoEnvelope(envelope) {
         message: envelope.errorMessage ?? "Unknown error",
         retriable: envelope.retriable ?? false
       };
+    case "blob-chunk-request":
+      return {
+        type: "blob-chunk-request",
+        messageId: envelope.messageId,
+        requestId: envelope.requestId ?? "",
+        hash: envelope.hash ?? ""
+      };
+    case "blob-chunk-response":
+      return {
+        type: "blob-chunk-response",
+        messageId: envelope.messageId,
+        requestId: envelope.requestId ?? "",
+        bytes: envelope.hasBytes ? envelope.chunkBytes ?? "" : null
+      };
+    case "blob-chunk-push":
+      return {
+        type: "blob-chunk-push",
+        messageId: envelope.messageId,
+        hash: envelope.hash ?? "",
+        bytes: envelope.chunkBytes ?? ""
+      };
     default:
       throw new import_core2.SyncError("Failed to decode sync message: unknown protobuf type", {
         type: envelope.type
@@ -812,6 +889,15 @@ function encodeEnvelope(envelope) {
     writer.uint32(138).string(envelope.errorMessage);
   }
   if (envelope.retriable !== void 0) writer.uint32(144).bool(envelope.retriable);
+  if (envelope.serverTime !== void 0) writer.uint32(152).int64(envelope.serverTime);
+  if (envelope.requestId && envelope.requestId.length > 0)
+    writer.uint32(162).string(envelope.requestId);
+  if (envelope.hash && envelope.hash.length > 0) writer.uint32(170).string(envelope.hash);
+  if (envelope.chunkBytes && envelope.chunkBytes.length > 0)
+    writer.uint32(178).string(envelope.chunkBytes);
+  if (envelope.hasBytes !== void 0) writer.uint32(184).bool(envelope.hasBytes);
+  if (envelope.blobStorageEnabled !== void 0)
+    writer.uint32(200).bool(envelope.blobStorageEnabled);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -880,6 +966,24 @@ function decodeEnvelope(bytes) {
       case 18:
         envelope.retriable = reader.bool();
         break;
+      case 19:
+        envelope.serverTime = longToNumber(reader.int64());
+        break;
+      case 20:
+        envelope.requestId = reader.string();
+        break;
+      case 21:
+        envelope.hash = reader.string();
+        break;
+      case 22:
+        envelope.chunkBytes = reader.string();
+        break;
+      case 23:
+        envelope.hasBytes = reader.bool();
+        break;
+      case 25:
+        envelope.blobStorageEnabled = reader.bool();
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -1381,7 +1485,7 @@ var ChaosTransport = class {
   random;
   messageHandler = null;
   reorderBuffer = [];
-  timers = [];
+  pending = [];
   constructor(inner, config) {
     this.inner = inner;
     this.dropRate = config?.dropRate ?? 0;
@@ -1396,10 +1500,14 @@ var ChaosTransport = class {
   }
   async disconnect() {
     this.flushReorderBuffer();
-    for (const timer of this.timers) {
+    const flushed = this.pending;
+    this.pending = [];
+    for (const { timer } of flushed) {
       clearTimeout(timer);
     }
-    this.timers = [];
+    for (const { message } of flushed) {
+      this.deliverIncoming(message);
+    }
     return this.inner.disconnect();
   }
   send(message) {
@@ -1436,9 +1544,10 @@ var ChaosTransport = class {
     if (this.maxLatency > 0) {
       const delay = Math.floor(this.random() * this.maxLatency);
       const timer = setTimeout(() => {
+        this.pending = this.pending.filter((p) => p.timer !== timer);
         this.deliverIncoming(message);
       }, delay);
-      this.timers.push(timer);
+      this.pending.push({ timer, message });
       return;
     }
     this.deliverIncoming(message);
@@ -1466,7 +1575,7 @@ var ChaosTransport = class {
 };
 
 // src/engine/sync-engine.ts
-var import_core6 = require("@korajs/core");
+var import_core7 = require("@korajs/core");
 var import_internal2 = require("@korajs/core/internal");
 
 // src/awareness/awareness-manager.ts
@@ -1675,6 +1784,95 @@ var AwarenessManager = class {
   }
 };
 
+// src/blob/blob-chunk-channel.ts
+var import_core5 = require("@korajs/core");
+function encodeBlobChunkBytes(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function decodeBlobChunkBytes(encoded) {
+  const binary = atob(encoded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}
+var BlobChunkChannel = class {
+  onSend;
+  handlers = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.onSend = options?.onSend ?? null;
+  }
+  /**
+   * Send a blob-chunk message to the peer. Response bytes are base64-encoded
+   * onto the wire here; callers pass a `Uint8Array`.
+   */
+  send(message) {
+    if (!this.onSend) {
+      return;
+    }
+    if (message.type === "blob-chunk-request") {
+      this.onSend({
+        type: "blob-chunk-request",
+        messageId: (0, import_core5.generateUUIDv7)(),
+        requestId: message.requestId,
+        hash: message.hash
+      });
+      return;
+    }
+    if (message.type === "blob-chunk-push") {
+      this.onSend({
+        type: "blob-chunk-push",
+        messageId: (0, import_core5.generateUUIDv7)(),
+        hash: message.hash,
+        bytes: encodeBlobChunkBytes(message.bytes)
+      });
+      return;
+    }
+    this.onSend({
+      type: "blob-chunk-response",
+      messageId: (0, import_core5.generateUUIDv7)(),
+      requestId: message.requestId,
+      bytes: message.bytes === null ? null : encodeBlobChunkBytes(message.bytes)
+    });
+  }
+  /**
+   * Register a handler for inbound blob-chunk messages. Multiple handlers are
+   * allowed; each receives every delivered message.
+   */
+  onMessage(handler) {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+  /**
+   * Deliver an inbound wire message to registered handlers, decoding response
+   * bytes from base64 back to a `Uint8Array` first.
+   */
+  deliver(message) {
+    if (this.handlers.size === 0) {
+      return;
+    }
+    const decoded = message.type === "blob-chunk-request" ? { type: "blob-chunk-request", requestId: message.requestId, hash: message.hash } : message.type === "blob-chunk-push" ? {
+      type: "blob-chunk-push",
+      hash: message.hash,
+      bytes: decodeBlobChunkBytes(message.bytes)
+    } : {
+      type: "blob-chunk-response",
+      requestId: message.requestId,
+      bytes: message.bytes === null ? null : decodeBlobChunkBytes(message.bytes)
+    };
+    for (const handler of this.handlers) {
+      handler(decoded);
+    }
+  }
+};
+
 // src/diagnostics/bandwidth-estimator.ts
 var BandwidthEstimator = class {
   maxSamples;
@@ -2118,7 +2316,7 @@ var SyncMetricsCollector = class {
 };
 
 // src/richtext/richtext-doc-channel.ts
-var import_core5 = require("@korajs/core");
+var import_core6 = require("@korajs/core");
 
 // src/richtext/doc-channel-wire.ts
 function encodeYjsUpdate(update) {
@@ -2197,7 +2395,7 @@ var RichtextDocChannel = class {
     }
     this.onSend({
       type: "yjs-doc-update",
-      messageId: (0, import_core5.generateUUIDv7)(),
+      messageId: (0, import_core6.generateUUIDv7)(),
       collection,
       recordId,
       field,
@@ -2345,6 +2543,41 @@ var OutboundQueue = class {
   peek(count) {
     return this.queue.slice(0, count);
   }
+  /**
+   * All queued operations (not counting in-flight), in causal order.
+   */
+  getAll() {
+    return [...this.queue];
+  }
+  /**
+   * Atomically replace the entire queue with a new set of operations.
+   *
+   * Used after a timestamp rebase rewrote the queued operations under new
+   * content-addressed ids: the old entries must vanish from memory AND from
+   * persistent storage in one step, or a page refresh could resurrect
+   * stale-stamped ops the server would reject. Resets the seen set to exactly
+   * the new ids so the rewritten ops are not treated as duplicates.
+   */
+  async replaceAll(ops) {
+    const removeIds = this.queue.map((op) => op.id);
+    for (const batch of this.inFlight.values()) {
+      for (const op of batch) {
+        removeIds.push(op.id);
+      }
+    }
+    this.inFlight.clear();
+    this.queue = ops.length > 1 ? (0, import_internal.topologicalSort)([...ops]) : [...ops];
+    this.seen.clear();
+    for (const op of this.queue) {
+      this.seen.add(op.id);
+    }
+    if (removeIds.length > 0) {
+      await this.storage.dequeue(removeIds);
+    }
+    for (const op of this.queue) {
+      await this.storage.enqueue(op);
+    }
+  }
   /**
    * Whether initialize() has been called.
    */
@@ -2394,6 +2627,7 @@ var SyncEngine = class {
   encryptor;
   awarenessManager;
   richtextDocChannel;
+  blobChunkChannel;
   metricsCollector;
   syncState;
   remoteVector = /* @__PURE__ */ new Map();
@@ -2406,6 +2640,9 @@ var SyncEngine = class {
   currentBatch = null;
   reconnecting = false;
   schemaBlocked = false;
+  clockBlocked = false;
+  clockSkewMs = null;
+  blobStorageEnabled = false;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
@@ -2454,6 +2691,14 @@ var SyncEngine = class {
         this.transport.send(message);
       }
     });
+    this.blobChunkChannel = new BlobChunkChannel({
+      onSend: (message) => {
+        if (this.state !== "streaming") {
+          return;
+        }
+        this.transport.send(message);
+      }
+    });
     this.awarenessManager.onSend((message) => {
       if (this.state !== "streaming") return;
       const wireMessage = {
@@ -2470,7 +2715,7 @@ var SyncEngine = class {
    */
   async start() {
     if (this.state !== "disconnected") {
-      throw new import_core6.SyncError("Cannot start sync engine: not in disconnected state", {
+      throw new import_core7.SyncError("Cannot start sync engine: not in disconnected state", {
         currentState: this.state
       });
     }
@@ -2487,7 +2732,7 @@ var SyncEngine = class {
     this.transport.onClose((reason) => this.handleTransportClose(reason));
     this.transport.onError((err) => this.handleTransportError(err));
     if (this.schemaBlocked) {
-      throw new import_core6.SyncError(
+      throw new import_core7.SyncError(
         "Sync is blocked due to schema version mismatch. Upgrade the app schema or align sync.schemaVersion with the server.",
         { code: "SCHEMA_MISMATCH_BLOCKED" }
       );
@@ -2579,10 +2824,17 @@ var SyncEngine = class {
       lastSyncedAt: this.lastSyncedAt,
       lastSuccessfulPush: this.lastSuccessfulPush,
       lastSuccessfulPull: this.lastSuccessfulPull,
-      conflicts: this.conflictCount
+      conflicts: this.conflictCount,
+      clockSkewMs: this.clockSkewMs
     };
     switch (this.state) {
       case "disconnected":
+        if (this.clockBlocked) {
+          return { ...base, status: "clock-error" };
+        }
+        if (this.schemaBlocked) {
+          return { ...base, status: "schema-mismatch" };
+        }
         return { ...base, status: "offline" };
       case "connecting":
       case "handshaking":
@@ -2591,6 +2843,9 @@ var SyncEngine = class {
       case "streaming":
         return { ...base, status: pendingOperations > 0 ? "syncing" : "synced" };
       case "error":
+        if (this.clockBlocked) {
+          return { ...base, status: "clock-error" };
+        }
         return { ...base, status: this.schemaBlocked ? "schema-mismatch" : "error" };
     }
   }
@@ -2601,6 +2856,27 @@ var SyncEngine = class {
   isSchemaBlocked() {
     return this.schemaBlocked;
   }
+  /**
+   * True when sync is blocked because this device's clock is too far ahead.
+   * Local writes continue to work and queue; only sync is paused.
+   */
+  isClockBlocked() {
+    return this.clockBlocked;
+  }
+  /** serverTime - localTime measured at the last handshake, or null before first connect. */
+  getClockSkewMs() {
+    return this.clockSkewMs;
+  }
+  /**
+   * Clears the clock block after the user corrects the device clock.
+   * Moves the engine back to `disconnected` so `start()` can run again.
+   */
+  clearClockBlock() {
+    this.clockBlocked = false;
+    if (this.state === "error") {
+      this.transitionTo("disconnected");
+    }
+  }
   /**
    * Clears schema-mismatch block after upgrading the local schema / sync config.
    * Moves the engine back to `disconnected` so `start()` can run again.
@@ -2626,7 +2902,7 @@ var SyncEngine = class {
     return this.getStatus().pendingOperations;
   }
   emitApplyFailure(op, result, overrides) {
-    const reason = (0, import_core6.defaultApplyFailureReason)(result, overrides);
+    const reason = (0, import_core7.defaultApplyFailureReason)(result, overrides);
     this.emitter?.emit({
       type: "sync:apply-failed",
       operationId: op.id,
@@ -2736,6 +3012,31 @@ var SyncEngine = class {
   getRichtextDocChannel() {
     return this.richtextDocChannel;
   }
+  /**
+   * Side channel for out-of-band blob chunk transfer over the sync connection.
+   * The app layer bridges this to a `ChunkMessagePort` to pull/serve blob bytes.
+   */
+  getBlobChunkChannel() {
+    return this.blobChunkChannel;
+  }
+  /**
+   * Whether the connected server persists blob bytes centrally (learned from the
+   * handshake response). When true, the app uploads the bytes behind `blob`
+   * fields so they stay available after the authoring device goes offline.
+   */
+  isBlobStorageEnabled() {
+    return this.blobStorageEnabled;
+  }
+  /**
+   * Upload a blob chunk (or manifest) to the server for central persistence.
+   * A no-op unless connected and the server advertised blob storage.
+   */
+  uploadBlobChunk(hash, bytes) {
+    if (this.state !== "streaming" || !this.blobStorageEnabled) {
+      return;
+    }
+    this.blobChunkChannel.send({ type: "blob-chunk-push", hash, bytes });
+  }
   // --- Private methods ---
   messageChain = Promise.resolve();
   enqueueMessage(message) {
@@ -2744,7 +3045,7 @@ var SyncEngine = class {
   async handleMessageAsync(message) {
     switch (message.type) {
       case "handshake-response":
-        this.handleHandshakeResponse(message);
+        await this.handleHandshakeResponse(message);
         break;
       case "operation-batch":
         await this.handleOperationBatch(message);
@@ -2761,14 +3062,53 @@ var SyncEngine = class {
       case "yjs-doc-update":
         this.richtextDocChannel.deliver(message);
         break;
+      case "blob-chunk-request":
+      case "blob-chunk-response":
+      case "blob-chunk-push":
+        this.blobChunkChannel.deliver(message);
+        break;
     }
   }
   handleMessageFailure(error) {
     const reason = error instanceof Error ? error.message : "Message handling failed";
     this.handleTransportClose(reason);
   }
-  handleHandshakeResponse(msg) {
+  /**
+   * Compares server wall-clock time from the handshake with local time.
+   * Negative skew = this device's clock is fast (dangerous for LWW and rejected
+   * by server ingest beyond 60s). Positive skew = slow (accepted but surfaced).
+   * Zero developer work required: the result flows into sync status and events.
+   */
+  evaluateClockSkew(serverTime) {
+    const skewMs = serverTime - Date.now();
+    this.clockSkewMs = skewMs;
+    const FAST_BLOCK_MS = 6e4;
+    const SLOW_WARN_MS = 10 * 6e4;
+    let severity = "info";
+    if (skewMs < -FAST_BLOCK_MS) {
+      severity = "fast-blocked";
+    } else if (skewMs > SLOW_WARN_MS) {
+      severity = "slow-warning";
+    }
+    this.emitter?.emit({ type: "sync:clock-skew", skewMs, severity, source: "handshake" });
+    if (severity === "fast-blocked") {
+      this.clockBlocked = true;
+    } else {
+      this.clockBlocked = false;
+    }
+  }
+  async handleHandshakeResponse(msg) {
     if (this.state !== "handshaking") return;
+    this.blobStorageEnabled = msg.blobStorageEnabled === true;
+    if (typeof msg.serverTime === "number") {
+      this.evaluateClockSkew(msg.serverTime);
+      if (this.clockBlocked) {
+        this.metricsCollector.updateStatus("error");
+        this.transitionTo("error");
+        void this.transport.disconnect();
+        return;
+      }
+    }
     if (!msg.accepted) {
       const reason = msg.rejectReason ?? "Handshake rejected";
       if (isSchemaMismatchReject(msg.rejectReason)) {
@@ -2815,8 +3155,51 @@ var SyncEngine = class {
     this.deltaSentOpIds = [];
     this.pendingDeltaBatchAcks.clear();
     this.initialSyncTotalBatches = 0;
+    if (typeof msg.serverTime === "number") {
+      await this.maybeRebaseQueuedOperations(msg.serverTime);
+    }
     this.sendDelta();
   }
+  /**
+   * Re-stamps queued (never-acknowledged) operations whose timestamps are far
+   * enough in the future that the server would reject them, using the server's
+   * own handshake time as the trusted "now". This is the automatic recovery
+   * path after a user corrects a fast device clock: the queue drains
+   * immediately instead of waiting for real time to catch up.
+   */
+  async maybeRebaseQueuedOperations(serverTime) {
+    const rebase = this.store.rebaseUnsyncedOperations?.bind(this.store);
+    if (!rebase) return;
+    const queued = this.outboundQueue.getAll();
+    if (queued.length === 0) return;
+    let maxQueuedWallTime = Number.NEGATIVE_INFINITY;
+    for (const op of queued) {
+      if (op.timestamp.wallTime > maxQueuedWallTime) {
+        maxQueuedWallTime = op.timestamp.wallTime;
+      }
+    }
+    const SERVER_FUTURE_TOLERANCE_MS = 6e4;
+    if (maxQueuedWallTime <= serverTime + SERVER_FUTURE_TOLERANCE_MS) return;
+    try {
+      const result = await rebase(
+        queued.map((op) => op.id),
+        serverTime
+      );
+      await this.outboundQueue.replaceAll(result.operations);
+      this.emitter?.emit({
+        type: "sync:clock-rebase",
+        rebasedCount: result.rebasedCount,
+        maxSkewMs: maxQueuedWallTime - serverTime
+      });
+    } catch (error) {
+      this.emitter?.emit({
+        type: "store:persistence-error",
+        dbName: "kora-oplog",
+        message: error instanceof Error ? error.message : "Timestamp rebase failed",
+        code: "CLOCK_REBASE_FAILED"
+      });
+    }
+  }
   async sendDelta() {
     const localVector = this.store.getVersionVector();
     const allMissingOps = await this.collectDelta(localVector, this.remoteVector);
@@ -2901,7 +3284,7 @@ var SyncEngine = class {
     const targetSchemaVersion = this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
     const transforms = this.config.operationTransforms ?? [];
     for (const op of inScopeOps) {
-      const transformed = transforms.length > 0 ? (0, import_core6.applyOperationTransforms)(op, targetSchemaVersion, transforms) : op;
+      const transformed = transforms.length > 0 ? (0, import_core7.applyOperationTransforms)(op, targetSchemaVersion, transforms) : op;
       if (transformed === null) {
         continue;
       }
@@ -2911,20 +3294,20 @@ var SyncEngine = class {
           this.emitApplyFailure(transformed, result);
         }
       } catch (error) {
-        if (error instanceof import_core6.ClockDriftError) {
+        if (error instanceof import_core7.ClockDriftError) {
           this.emitApplyFailure(transformed, "rejected", {
-            code: import_core6.APPLY_FAILURE_CODES.CLOCK_DRIFT,
+            code: import_core7.APPLY_FAILURE_CODES.CLOCK_DRIFT,
             message: error.message,
             retriable: false
           });
           continue;
         }
         const message = error instanceof Error ? error.message : "Apply failed";
-        const code = error instanceof import_core6.SyncError ? error.code : error instanceof import_core6.KoraError ? error.code : error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : import_core6.APPLY_FAILURE_CODES.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;
         this.emitApplyFailure(transformed, "rejected", {
           code,
           message,
-          retriable: code !== import_core6.APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY
+          retriable: code !== import_core7.APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY
         });
       }
     }
@@ -2996,6 +3379,17 @@ var SyncEngine = class {
     if (msg.code === "AUTH_FAILED") {
       this.emitter?.emit({ type: "sync:auth-failed", reason: msg.message });
     }
+    if (msg.code === "INVALID_TIMESTAMP") {
+      this.clockBlocked = true;
+      this.emitter?.emit({
+        type: "sync:clock-skew",
+        skewMs: this.clockSkewMs ?? Number.NaN,
+        severity: "fast-blocked",
+        source: "server-reject"
+      });
+      this.emitter?.emit({ type: "sync:disconnected", reason: msg.message });
+      return;
+    }
     this.emitter?.emit({ type: "sync:disconnected", reason: msg.message });
     this.transitionTo("disconnected");
   }
@@ -3183,7 +3577,7 @@ var SyncEngine = class {
   transitionTo(newState) {
     const validTargets = VALID_TRANSITIONS[this.state];
     if (!validTargets.includes(newState)) {
-      throw new import_core6.SyncError(`Invalid sync state transition: ${this.state} \u2192 ${newState}`, {
+      throw new import_core7.SyncError(`Invalid sync state transition: ${this.state} \u2192 ${newState}`, {
         from: this.state,
         to: newState
       });
@@ -3465,18 +3859,18 @@ var ReconnectionManager = class {
 };
 
 // src/encryption/sync-encryptor.ts
-var import_core8 = require("@korajs/core");
+var import_core9 = require("@korajs/core");
 
 // src/encryption/key-derivation.ts
-var import_core7 = require("@korajs/core");
-var KeyDerivationError = class extends import_core7.SyncError {
+var import_core8 = require("@korajs/core");
+var KeyDerivationError = class extends import_core8.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "KEY_DERIVATION_ERROR" });
     this.name = "KeyDerivationError";
   }
 };
 var SALT_LENGTH = 32;
-var PBKDF2_ITERATIONS = 6e5;
+var DEFAULT_PBKDF2_ITERATIONS = 6e5;
 var DERIVED_KEY_LENGTH = 256;
 function assertCryptoAvailable() {
   if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
@@ -3493,13 +3887,19 @@ function generateSalt() {
   }
   return globalThis.crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
 }
-async function deriveKey(passphrase, salt) {
+async function deriveKey(passphrase, salt, iterations = DEFAULT_PBKDF2_ITERATIONS) {
   assertCryptoAvailable();
   if (passphrase.length === 0) {
     throw new KeyDerivationError(
       "Passphrase must not be empty. Provide a non-empty string for encryption key derivation."
     );
   }
+  if (!Number.isInteger(iterations) || iterations < 1) {
+    throw new KeyDerivationError(
+      `PBKDF2 iteration count must be a positive integer, received: ${iterations}`,
+      { iterations }
+    );
+  }
   const usedSalt = salt ?? generateSalt();
   try {
     const passphraseBytes = new TextEncoder().encode(passphrase);
@@ -3514,7 +3914,7 @@ async function deriveKey(passphrase, salt) {
       {
         name: "PBKDF2",
         salt: usedSalt,
-        iterations: PBKDF2_ITERATIONS,
+        iterations,
         hash: "SHA-256"
       },
       baseKey,
@@ -3534,24 +3934,24 @@ async function deriveKey(passphrase, salt) {
     );
   }
 }
-async function deriveVersionedKey(passphrase, version, salt) {
+async function deriveVersionedKey(passphrase, version, salt, iterations = DEFAULT_PBKDF2_ITERATIONS) {
   if (!Number.isInteger(version) || version < 1) {
     throw new KeyDerivationError(`Key version must be a positive integer, received: ${version}`, {
       version
     });
   }
-  const { key, salt: usedSalt } = await deriveKey(passphrase, salt);
+  const { key, salt: usedSalt } = await deriveKey(passphrase, salt, iterations);
   return { version, key, salt: usedSalt };
 }
 
 // src/encryption/sync-encryptor.ts
-var EncryptionError = class extends import_core8.SyncError {
+var EncryptionError = class extends import_core9.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "ENCRYPTION_ERROR" });
     this.name = "EncryptionError";
   }
 };
-var DecryptionError = class extends import_core8.SyncError {
+var DecryptionError = class extends import_core9.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "DECRYPTION_ERROR" });
     this.name = "DecryptionError";
@@ -3580,11 +3980,13 @@ var SyncEncryptor = class _SyncEncryptor {
    * @param config - Encryption configuration with passphrase
    * @param salt - Optional salt for deterministic key derivation (mainly for testing).
    *              If omitted, a random salt is generated.
+   * @param iterations - Optional PBKDF2 iteration count. Defaults to the
+   *              production-strength value. Lower it only in tests.
    * @returns A configured SyncEncryptor instance
    * @throws {EncryptionError} If configuration is invalid
    * @throws {KeyDerivationError} If key derivation fails
    */
-  static async create(config, salt) {
+  static async create(config, salt, iterations) {
     if (!config.enabled) {
       throw new EncryptionError(
         "Cannot create SyncEncryptor with encryption disabled. Set enabled: true in the encryption config."
@@ -3596,7 +3998,7 @@ var SyncEncryptor = class _SyncEncryptor {
         "Encryption key/passphrase must not be empty. Provide a non-empty string or key provider function."
       );
     }
-    const versionedKey = await deriveVersionedKey(passphrase, 1, salt);
+    const versionedKey = await deriveVersionedKey(passphrase, 1, salt, iterations);
     const keys = /* @__PURE__ */ new Map();
     keys.set(1, versionedKey);
     return new _SyncEncryptor(keys, 1);
@@ -3897,10 +4299,12 @@ var OFFLINE_SYNC_STATUS = Object.freeze({
   lastSyncedAt: null,
   lastSuccessfulPush: null,
   lastSuccessfulPull: null,
-  conflicts: 0
+  conflicts: 0,
+  clockSkewMs: null
 });
 var SYNC_STATUS_EVENT_TYPES = [
   "sync:connected",
+  "sync:clock-skew",
   "sync:disconnected",
   "sync:schema-mismatch",
   "sync:auth-failed",
@@ -4044,6 +4448,7 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AwarenessManager,
+  BlobChunkChannel,
   ChaosTransport,
   ConnectionMonitor,
   DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
@@ -4068,11 +4473,13 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   WebSocketTransport,
   createDeltaCursorFromBatch,
   createSyncStatusController,
+  decodeBlobChunkBytes,
   decodeDeltaCursor,
   decodeYjsUpdate,
   dedupeQuerySubsets,
   deriveKey,
   deriveVersionedKey,
+  encodeBlobChunkBytes,
   encodeDeltaCursor,
   encodeYjsUpdate,
   filterOperationsByScope,
@@ -4080,6 +4487,9 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   getRemoteAwarenessStates,
   isAcknowledgmentMessage,
   isAwarenessUpdateMessage,
+  isBlobChunkPushMessage,
+  isBlobChunkRequestMessage,
+  isBlobChunkResponseMessage,
   isClientSchemaVersionSupported,
   isEncryptedPayload,
   isErrorMessage,