@korajs/sync 1.0.0-beta.0 → 1.0.0-beta.2

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,
@@ -40,6 +41,7 @@ __export(index_exports, {
   InvalidScopeError: () => InvalidScopeError,
   JsonMessageSerializer: () => JsonMessageSerializer,
   KeyDerivationError: () => KeyDerivationError,
+  MemoryRejectedOperationStorage: () => MemoryRejectedOperationStorage,
   NegotiatedMessageSerializer: () => NegotiatedMessageSerializer,
   OFFLINE_SYNC_STATUS: () => OFFLINE_SYNC_STATUS,
   OutboundQueue: () => OutboundQueue,
@@ -55,11 +57,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,12 +71,16 @@ __export(index_exports, {
   getRemoteAwarenessStates: () => getRemoteAwarenessStates,
   isAcknowledgmentMessage: () => isAcknowledgmentMessage,
   isAwarenessUpdateMessage: () => isAwarenessUpdateMessage,
+  isBlobChunkPushMessage: () => isBlobChunkPushMessage,
+  isBlobChunkRequestMessage: () => isBlobChunkRequestMessage,
+  isBlobChunkResponseMessage: () => isBlobChunkResponseMessage,
   isClientSchemaVersionSupported: () => isClientSchemaVersionSupported,
   isEncryptedPayload: () => isEncryptedPayload,
   isErrorMessage: () => isErrorMessage,
   isHandshakeMessage: () => isHandshakeMessage,
   isHandshakeResponseMessage: () => isHandshakeResponseMessage,
   isOperationBatchMessage: () => isOperationBatchMessage,
+  isOperationRejectedMessage: () => isOperationRejectedMessage,
   isSchemaMismatchReject: () => isSchemaMismatchReject,
   isSyncMessage: () => isSyncMessage,
   isYjsDocUpdateMessage: () => isYjsDocUpdateMessage,
@@ -105,6 +113,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 import_core.KoraError {
   constructor(operationId, collection, scope, message) {
     super(
@@ -302,10 +324,18 @@ 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":
       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;
   }
@@ -335,6 +365,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;
@@ -345,6 +380,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");
@@ -585,7 +635,8 @@ function toProtoEnvelope(message) {
         accepted: message.accepted,
         rejectReason: message.rejectReason,
         selectedWireFormat: message.selectedWireFormat,
-        serverTime: message.serverTime
+        serverTime: message.serverTime,
+        blobStorageEnabled: message.blobStorageEnabled
       };
     case "operation-batch":
       return {
@@ -610,12 +661,45 @@ 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 {
         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) {
@@ -648,7 +732,8 @@ function fromProtoEnvelope(envelope) {
         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.serverTime !== void 0 ? { serverTime: envelope.serverTime } : {},
+        ...envelope.blobStorageEnabled !== void 0 ? { blobStorageEnabled: envelope.blobStorageEnabled } : {}
       };
     case "operation-batch":
       return {
@@ -673,6 +758,38 @@ 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",
+        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
@@ -818,6 +935,20 @@ function encodeEnvelope(envelope) {
   }
   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);
+  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);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -889,6 +1020,30 @@ function decodeEnvelope(bytes) {
       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;
+      case 26:
+        envelope.operationId = reader.string();
+        break;
+      case 27:
+        envelope.collection = reader.string();
+        break;
+      case 28:
+        envelope.recordId = reader.string();
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -1480,7 +1635,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
@@ -1689,6 +1844,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;
@@ -2132,7 +2376,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) {
@@ -2211,7 +2455,7 @@ var RichtextDocChannel = class {
     }
     this.onSend({
       type: "yjs-doc-update",
-      messageId: (0, import_core5.generateUUIDv7)(),
+      messageId: (0, import_core6.generateUUIDv7)(),
       collection,
       recordId,
       field,
@@ -2400,6 +2644,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.
@@ -2439,10 +2714,12 @@ var SyncEngine = class {
   serializer;
   emitter;
   outboundQueue;
+  rejectedStorage;
   batchSize;
   encryptor;
   awarenessManager;
   richtextDocChannel;
+  blobChunkChannel;
   metricsCollector;
   syncState;
   remoteVector = /* @__PURE__ */ new Map();
@@ -2457,6 +2734,7 @@ var SyncEngine = class {
   schemaBlocked = false;
   clockBlocked = false;
   clockSkewMs = null;
+  blobStorageEnabled = false;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
@@ -2489,6 +2767,7 @@ var SyncEngine = class {
     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);
@@ -2505,6 +2784,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 = {
@@ -2521,7 +2808,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
       });
     }
@@ -2538,7 +2825,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" }
       );
@@ -2708,7 +2995,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,
@@ -2818,6 +3105,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) {
@@ -2837,12 +3149,20 @@ var SyncEngine = class {
       case "error":
         this.handleError(message);
         break;
+      case "operation-rejected":
+        await this.handleOperationRejected(message);
+        break;
       case "awareness-update":
         this.handleAwarenessUpdate(message);
         break;
       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) {
@@ -2875,6 +3195,7 @@ var SyncEngine = class {
   }
   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) {
@@ -3059,7 +3380,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;
       }
@@ -3069,20 +3390,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
         });
       }
     }
@@ -3168,6 +3489,50 @@ 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) {
+    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;
@@ -3352,7 +3717,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
       });
@@ -3634,11 +3999,11 @@ 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";
@@ -3720,13 +4085,13 @@ async function deriveVersionedKey(passphrase, version, salt, iterations = DEFAUL
 }
 
 // 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";
@@ -4223,6 +4588,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,
@@ -4232,6 +4598,7 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   InvalidScopeError,
   JsonMessageSerializer,
   KeyDerivationError,
+  MemoryRejectedOperationStorage,
   NegotiatedMessageSerializer,
   OFFLINE_SYNC_STATUS,
   OutboundQueue,
@@ -4247,11 +4614,13 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   WebSocketTransport,
   createDeltaCursorFromBatch,
   createSyncStatusController,
+  decodeBlobChunkBytes,
   decodeDeltaCursor,
   decodeYjsUpdate,
   dedupeQuerySubsets,
   deriveKey,
   deriveVersionedKey,
+  encodeBlobChunkBytes,
   encodeDeltaCursor,
   encodeYjsUpdate,
   filterOperationsByScope,
@@ -4259,12 +4628,16 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
   getRemoteAwarenessStates,
   isAcknowledgmentMessage,
   isAwarenessUpdateMessage,
+  isBlobChunkPushMessage,
+  isBlobChunkRequestMessage,
+  isBlobChunkResponseMessage,
   isClientSchemaVersionSupported,
   isEncryptedPayload,
   isErrorMessage,
   isHandshakeMessage,
   isHandshakeResponseMessage,
   isOperationBatchMessage,
+  isOperationRejectedMessage,
   isSchemaMismatchReject,
   isSyncMessage,
   isYjsDocUpdateMessage,