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

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, m as SyncStatePersistence, n as SyncQuerySubset } from './transport-CZLMdZ0k.cjs';
-export { A as AcknowledgmentMessage, o as AwarenessStateWire, p as AwarenessUpdateMessage, E as EncryptedPayload, q as ErrorMessage, H as HandshakeMessage, r as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, s as SYNC_STATES, t as SYNC_STATUSES, u as ScopeViolationError, v as SyncEncryptionAlgorithm, w as SyncScopeContext, x as SyncStatus, y as dedupeQuerySubsets, z as isAcknowledgmentMessage, C as isAwarenessUpdateMessage, F as isBlobChunkPushMessage, G as isBlobChunkRequestMessage, J as isBlobChunkResponseMessage, K as isErrorMessage, L as isHandshakeMessage, M as isHandshakeResponseMessage, N as isOperationBatchMessage, P as isSyncMessage, R as isYjsDocUpdateMessage, U as operationMatchesQuerySubsets } from './transport-CZLMdZ0k.cjs';
+import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, R as RejectedOperationStorage, m as SyncStatePersistence, n as SyncQuerySubset, o as RejectedOperation } from './transport-BGr-_eH8.cjs';
+export { A as AcknowledgmentMessage, p as AwarenessStateWire, q as AwarenessUpdateMessage, E as EncryptedPayload, r as ErrorMessage, H as HandshakeMessage, s as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, t as OperationRejectedMessage, u as SYNC_STATES, v as SYNC_STATUSES, w as ScopeViolationError, x as SyncEncryptionAlgorithm, y as SyncScopeContext, z as SyncStatus, C as dedupeQuerySubsets, F as isAcknowledgmentMessage, G as isAwarenessUpdateMessage, J as isBlobChunkPushMessage, K as isBlobChunkRequestMessage, L as isBlobChunkResponseMessage, N as isErrorMessage, P as isHandshakeMessage, U as isHandshakeResponseMessage, X as isOperationBatchMessage, Z as isOperationRejectedMessage, _ as isSyncMessage, $ as isYjsDocUpdateMessage, a0 as operationMatchesQuerySubsets } from './transport-BGr-_eH8.cjs';
 import * as _korajs_core from '@korajs/core';
 import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
 export { ApplyFailureReason, ApplyResult } from '@korajs/core';
@@ -844,6 +844,14 @@ declare class OutboundQueue {
      * Whether initialize() has been called.
      */
     get isInitialized(): boolean;
+    /**
+     * 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).
+     */
+    reject(opId: string): Promise<Operation | null>;
     /**
      * Remove operations by id from queue and persistent storage.
      * Used when ops were already sent during handshake delta exchange.
@@ -867,6 +875,11 @@ interface SyncEngineOptions {
     emitter?: KoraEventEmitter;
     /** Queue storage for persistent outbound queue. Defaults to in-memory. */
     queueStorage?: QueueStorage;
+    /**
+     * Durable storage for operations the server rejected. Defaults to in-memory.
+     * Provide a store-backed implementation so rejections survive a page refresh.
+     */
+    rejectedStorage?: RejectedOperationStorage;
     /**
      * Optional encryptor for end-to-end encryption.
      * When provided, `data` and `previousData` fields of operations are encrypted
@@ -911,6 +924,7 @@ declare class SyncEngine {
     private readonly serializer;
     private readonly emitter;
     private readonly outboundQueue;
+    private readonly rejectedStorage;
     private readonly batchSize;
     private readonly encryptor;
     private readonly awarenessManager;
@@ -1107,6 +1121,25 @@ declare class SyncEngine {
     private handleOperationBatch;
     private handleAcknowledgment;
     private handleError;
+    /**
+     * 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.
+     */
+    private handleOperationRejected;
+    /**
+     * 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(): Promise<RejectedOperation[]>;
+    /**
+     * Forget rejected operations by id once the app has reconciled them (rolled the
+     * optimistic write back or resubmitted a corrected op).
+     */
+    clearRejectedOperations(operationIds: string[]): Promise<void>;
     private checkDeltaComplete;
     /**
      * Effective server vector: persisted last-ack merged with live handshake remote vector.
@@ -1375,4 +1408,4 @@ declare function getRemoteAwarenessStates(awareness: AwarenessManager): Awarenes
  */
 declare function subscribeRemoteAwarenessStates(awareness: AwarenessManager, listener: (states: AwarenessState[]) => void): () => void;
 
-export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, BlobChunkChannel, type BlobChunkChannelMessage, type BlobChunkChannelOptions, BlobChunkPushMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, BlobChunkChannel, type BlobChunkChannelMessage, type BlobChunkChannelOptions, BlobChunkPushMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RejectedOperation, RejectedOperationStorage, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, m as SyncStatePersistence, n as SyncQuerySubset } from './transport-CZLMdZ0k.js';
-export { A as AcknowledgmentMessage, o as AwarenessStateWire, p as AwarenessUpdateMessage, E as EncryptedPayload, q as ErrorMessage, H as HandshakeMessage, r as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, s as SYNC_STATES, t as SYNC_STATUSES, u as ScopeViolationError, v as SyncEncryptionAlgorithm, w as SyncScopeContext, x as SyncStatus, y as dedupeQuerySubsets, z as isAcknowledgmentMessage, C as isAwarenessUpdateMessage, F as isBlobChunkPushMessage, G as isBlobChunkRequestMessage, J as isBlobChunkResponseMessage, K as isErrorMessage, L as isHandshakeMessage, M as isHandshakeResponseMessage, N as isOperationBatchMessage, P as isSyncMessage, R as isYjsDocUpdateMessage, U as operationMatchesQuerySubsets } from './transport-CZLMdZ0k.js';
+import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, R as RejectedOperationStorage, m as SyncStatePersistence, n as SyncQuerySubset, o as RejectedOperation } from './transport-BGr-_eH8.js';
+export { A as AcknowledgmentMessage, p as AwarenessStateWire, q as AwarenessUpdateMessage, E as EncryptedPayload, r as ErrorMessage, H as HandshakeMessage, s as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, t as OperationRejectedMessage, u as SYNC_STATES, v as SYNC_STATUSES, w as ScopeViolationError, x as SyncEncryptionAlgorithm, y as SyncScopeContext, z as SyncStatus, C as dedupeQuerySubsets, F as isAcknowledgmentMessage, G as isAwarenessUpdateMessage, J as isBlobChunkPushMessage, K as isBlobChunkRequestMessage, L as isBlobChunkResponseMessage, N as isErrorMessage, P as isHandshakeMessage, U as isHandshakeResponseMessage, X as isOperationBatchMessage, Z as isOperationRejectedMessage, _ as isSyncMessage, $ as isYjsDocUpdateMessage, a0 as operationMatchesQuerySubsets } from './transport-BGr-_eH8.js';
 import * as _korajs_core from '@korajs/core';
 import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
 export { ApplyFailureReason, ApplyResult } from '@korajs/core';
@@ -844,6 +844,14 @@ declare class OutboundQueue {
      * Whether initialize() has been called.
      */
     get isInitialized(): boolean;
+    /**
+     * 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).
+     */
+    reject(opId: string): Promise<Operation | null>;
     /**
      * Remove operations by id from queue and persistent storage.
      * Used when ops were already sent during handshake delta exchange.
@@ -867,6 +875,11 @@ interface SyncEngineOptions {
     emitter?: KoraEventEmitter;
     /** Queue storage for persistent outbound queue. Defaults to in-memory. */
     queueStorage?: QueueStorage;
+    /**
+     * Durable storage for operations the server rejected. Defaults to in-memory.
+     * Provide a store-backed implementation so rejections survive a page refresh.
+     */
+    rejectedStorage?: RejectedOperationStorage;
     /**
      * Optional encryptor for end-to-end encryption.
      * When provided, `data` and `previousData` fields of operations are encrypted
@@ -911,6 +924,7 @@ declare class SyncEngine {
     private readonly serializer;
     private readonly emitter;
     private readonly outboundQueue;
+    private readonly rejectedStorage;
     private readonly batchSize;
     private readonly encryptor;
     private readonly awarenessManager;
@@ -1107,6 +1121,25 @@ declare class SyncEngine {
     private handleOperationBatch;
     private handleAcknowledgment;
     private handleError;
+    /**
+     * 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.
+     */
+    private handleOperationRejected;
+    /**
+     * 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(): Promise<RejectedOperation[]>;
+    /**
+     * Forget rejected operations by id once the app has reconciled them (rolled the
+     * optimistic write back or resubmitted a corrected op).
+     */
+    clearRejectedOperations(operationIds: string[]): Promise<void>;
     private checkDeltaComplete;
     /**
      * Effective server vector: persisted last-ack merged with live handshake remote vector.
@@ -1375,4 +1408,4 @@ declare function getRemoteAwarenessStates(awareness: AwarenessManager): Awarenes
  */
 declare function subscribeRemoteAwarenessStates(awareness: AwarenessManager, listener: (states: AwarenessState[]) => void): () => void;
 
-export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, BlobChunkChannel, type BlobChunkChannelMessage, type BlobChunkChannelOptions, BlobChunkPushMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, BlobChunkChannel, type BlobChunkChannelMessage, type BlobChunkChannelOptions, BlobChunkPushMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RejectedOperation, RejectedOperationStorage, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };

package/dist/index.js

@@ -21,6 +21,20 @@ var SYNC_STATUSES = [
   "error",
   "schema-mismatch"
 ];
+var MemoryRejectedOperationStorage = class {
+  rejected = /* @__PURE__ */ new Map();
+  async record(rejected) {
+    this.rejected.set(rejected.operationId, rejected);
+  }
+  async list() {
+    return [...this.rejected.values()];
+  }
+  async remove(operationIds) {
+    for (const id of operationIds) {
+      this.rejected.delete(id);
+    }
+  }
+};
 var ScopeViolationError = class extends KoraError {
   constructor(operationId, collection, scope, message) {
     super(
@@ -218,6 +232,8 @@ function isSyncMessage(value) {
       return isAcknowledgmentMessage(value);
     case "error":
       return isErrorMessage(value);
+    case "operation-rejected":
+      return isOperationRejectedMessage(value);
     case "awareness-update":
       return isAwarenessUpdateMessage(value);
     case "yjs-doc-update":
@@ -257,6 +273,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;
@@ -548,6 +569,17 @@ function toProtoEnvelope(message) {
         errorMessage: message.message,
         retriable: message.retriable
       };
+    case "operation-rejected":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        operationId: message.operationId,
+        collection: message.collection,
+        recordId: message.recordId,
+        errorCode: message.code,
+        errorMessage: message.message,
+        retriable: message.retriable
+      };
     case "awareness-update":
     case "yjs-doc-update":
       return {
@@ -634,6 +666,17 @@ function fromProtoEnvelope(envelope) {
         message: envelope.errorMessage ?? "Unknown error",
         retriable: envelope.retriable ?? false
       };
+    case "operation-rejected":
+      return {
+        type: "operation-rejected",
+        messageId: envelope.messageId,
+        operationId: envelope.operationId ?? "",
+        collection: envelope.collection ?? "",
+        recordId: envelope.recordId ?? "",
+        code: envelope.errorCode ?? "REJECTED",
+        message: envelope.errorMessage ?? "",
+        retriable: envelope.retriable ?? false
+      };
     case "blob-chunk-request":
       return {
         type: "blob-chunk-request",
@@ -808,6 +851,12 @@ function encodeEnvelope(envelope) {
   if (envelope.hasBytes !== void 0) writer.uint32(184).bool(envelope.hasBytes);
   if (envelope.blobStorageEnabled !== void 0)
     writer.uint32(200).bool(envelope.blobStorageEnabled);
+  if (envelope.operationId && envelope.operationId.length > 0)
+    writer.uint32(210).string(envelope.operationId);
+  if (envelope.collection && envelope.collection.length > 0)
+    writer.uint32(218).string(envelope.collection);
+  if (envelope.recordId && envelope.recordId.length > 0)
+    writer.uint32(226).string(envelope.recordId);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -894,6 +943,15 @@ function decodeEnvelope(bytes) {
       case 25:
         envelope.blobStorageEnabled = reader.bool();
         break;
+      case 26:
+        envelope.operationId = reader.string();
+        break;
+      case 27:
+        envelope.collection = reader.string();
+        break;
+      case 28:
+        envelope.recordId = reader.string();
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -2482,6 +2540,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.
@@ -2521,6 +2610,7 @@ var SyncEngine = class {
   serializer;
   emitter;
   outboundQueue;
+  rejectedStorage;
   batchSize;
   encryptor;
   awarenessManager;
@@ -2573,6 +2663,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);
@@ -2954,6 +3045,9 @@ var SyncEngine = class {
       case "error":
         this.handleError(message);
         break;
+      case "operation-rejected":
+        await this.handleOperationRejected(message);
+        break;
       case "awareness-update":
         this.handleAwarenessUpdate(message);
         break;
@@ -3291,6 +3385,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;
@@ -4355,6 +4493,7 @@ export {
   InvalidScopeError,
   JsonMessageSerializer,
   KeyDerivationError,
+  MemoryRejectedOperationStorage,
   NegotiatedMessageSerializer,
   OFFLINE_SYNC_STATUS,
   OutboundQueue,
@@ -4393,6 +4532,7 @@ export {
   isHandshakeMessage,
   isHandshakeResponseMessage,
   isOperationBatchMessage,
+  isOperationRejectedMessage,
   isSchemaMismatchReject,
   isSyncMessage,
   isYjsDocUpdateMessage,