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

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-iXX0KA_W.cjs';
+export { A as AcknowledgmentMessage, p as ActiveApplyFailure, q as AwarenessStateWire, r as AwarenessUpdateMessage, E as EncryptedPayload, s as ErrorMessage, H as HandshakeMessage, t as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, u as OperationRejectedMessage, v as SYNC_STATES, w as SYNC_STATUSES, x as ScopeViolationError, y as SyncEncryptionAlgorithm, z as SyncPhase, C as SyncScopeContext, F as SyncSettlementOptions, G as SyncSettlementResult, J as SyncStatus, K as dedupeQuerySubsets, L as isAcknowledgmentMessage, N as isAwarenessUpdateMessage, P as isBlobChunkPushMessage, U as isBlobChunkRequestMessage, X as isBlobChunkResponseMessage, Z as isErrorMessage, _ as isHandshakeMessage, $ as isHandshakeResponseMessage, a0 as isOperationBatchMessage, a1 as isOperationRejectedMessage, a2 as isSyncMessage, a3 as isYjsDocUpdateMessage, a4 as operationMatchesQuerySubsets, a5 as querySubsetContains } from './transport-iXX0KA_W.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';
@@ -95,6 +95,17 @@ interface SyncStore {
         idMapping: Record<string, string>;
         rebasedCount: number;
     }>;
+    /**
+     * Optional: read a record's current materialized field values, used to backfill
+     * scope / query-subset fields that a partial update (or a delete) does not carry
+     * in its own data. Without it, such an operation would be judged out of scope by
+     * its changed fields alone and wrongly dropped from sync. Optional so hand-rolled
+     * SyncStore implementations keep working; when absent, the engine falls back to
+     * judging visibility from the operation's own data.
+     *
+     * @returns the record's fields, or null when it cannot be read.
+     */
+    readRecordFields?(collection: string, recordId: string): Promise<Record<string, unknown> | null>;
 }
 
 /** Prefix for handshake rejection when client schema version is unsupported. */
@@ -272,6 +283,14 @@ interface ChaosConfig {
     maxLatency?: number;
     /** Injectable random source for deterministic testing. Returns value in [0, 1). */
     randomSource?: () => number;
+    /**
+     * Deterministic targeted drop. When it returns true for a message and direction,
+     * that message is dropped unconditionally (independent of `dropRate`). Enables
+     * reproducing an exact gap (e.g. drop one specific operation) instead of relying
+     * on probabilistic drops. `direction` is 'outgoing' for `send` and 'incoming' for
+     * messages arriving from the inner transport.
+     */
+    dropPredicate?: (message: SyncMessage, direction: 'outgoing' | 'incoming') => boolean;
 }
 /**
  * Chaos transport that wraps another transport and injects faults.
@@ -287,6 +306,7 @@ declare class ChaosTransport implements SyncTransport {
     private readonly reorderRate;
     private readonly maxLatency;
     private readonly random;
+    private readonly dropPredicate;
     private messageHandler;
     private reorderBuffer;
     private pending;
@@ -805,6 +825,13 @@ declare class OutboundQueue {
      * Acknowledge a batch, removing its operations permanently.
      */
     acknowledge(batchId: string): Promise<void>;
+    /**
+     * Acknowledge only operations in an in-flight batch whose local sequence number is
+     * covered by the server's ack. Any later operations return to the front of the
+     * queue for retry. This is required when the server accepts a prefix but rejects a
+     * later operation retriably (for example a stale-scope push after auth changed).
+     */
+    acknowledgeThrough(batchId: string, lastSequenceNumber: number): Promise<void>;
     /**
      * Return a failed batch to the front of the queue for retry.
      * Prepends the operations to maintain priority.
@@ -844,6 +871,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 +902,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
@@ -894,6 +934,8 @@ interface SyncDiagnostics {
     pendingOperations: number;
     hasInFlightBatch: boolean;
     reconnecting: boolean;
+    deliveryWatermark: number;
+    deliveryGapRepeatCount: number;
     timestamp: number;
 }
 /**
@@ -911,7 +953,9 @@ declare class SyncEngine {
     private readonly serializer;
     private readonly emitter;
     private readonly outboundQueue;
+    private readonly rejectedStorage;
     private readonly batchSize;
+    private readonly outboundAckTimeoutMs;
     private readonly encryptor;
     private readonly awarenessManager;
     private readonly richtextDocChannel;
@@ -926,11 +970,21 @@ declare class SyncEngine {
     private lastSuccessfulPull;
     private conflictCount;
     private currentBatch;
+    private currentBatchRequiresPartialAck;
     private reconnecting;
     private schemaBlocked;
     private clockBlocked;
     private clockSkewMs;
     private blobStorageEnabled;
+    private suspensionReason;
+    private authRejected;
+    private serverFrontier;
+    private hasInFlightDeliveryBatch;
+    private blockedFailure;
+    private outboundAckTimer;
+    private startPromise;
+    private stopPromise;
+    private reconnectPromise;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -946,19 +1000,43 @@ declare class SyncEngine {
     private activeScope;
     /** Live query subsets registered from reactive subscriptions */
     private querySubsets;
+    private staticQuerySubsets;
     private querySubsetReconnectTimer;
     /** Resume cursor for paginated initial sync (persisted across reconnects) */
     private resumeDeltaCursor;
     private initialSyncTotalBatches;
+    /**
+     * The delivery watermark for the CURRENT sync view: the highest server delivery
+     * sequence up to which every operation in the current view (scope + active query
+     * subscriptions) has been contiguously applied. Advanced only through the server's
+     * gap-free delivery stream (never through live relay), so it is a durable lower bound
+     * on what this client holds for this view. Reported at handshake to resume the stream.
+     *
+     * The watermark is keyed by view: switching views (a scope or subscription change)
+     * saves the current view's watermark and loads the target view's, so returning to a
+     * previously-synced view resumes exactly where it left off instead of re-syncing. This
+     * is correct because a view's watermark is a lower bound specific to that view's
+     * filter; a widened view is simply a different (initially unsynced) view.
+     */
+    private deliveryWatermark;
+    /**
+     * In-memory cache of watermark per view signature, preloaded from persistence at start
+     * so a view switch resolves synchronously (no race with the reconnect it triggers).
+     */
+    private readonly deliverySignatureWatermarks;
+    private deliveryGapRepeatCount;
+    private lastDeliveryGapKey;
     constructor(options: SyncEngineOptions);
     /**
      * Start the sync engine: connect → handshake → delta exchange → streaming.
      */
     start(): Promise<void>;
+    private startInternal;
     /**
      * Stop the sync engine. Disconnects the transport.
      */
     stop(): Promise<void>;
+    private stopInternal;
     private ensureDisconnected;
     /**
      * Push a local operation to the outbound queue.
@@ -979,6 +1057,7 @@ declare class SyncEngine {
      * Get the current developer-facing sync status.
      */
     getStatus(): SyncStatusInfo;
+    private resolvePhase;
     /**
      * 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.
@@ -1016,6 +1095,15 @@ declare class SyncEngine {
      * or in error state, restarts the sync. If already connected, no-op.
      */
     retryNow(): Promise<void>;
+    /** Wake a permanent auth suspension after the binding reports a new auth state. */
+    notifyAuthChanged(): void;
+    /**
+     * Atomically refresh the transport session. Overlapping callers share one
+     * reconnect, in-flight outbound batches are returned to the queue by stop(), and the
+     * next start handshakes with the latest auth token, sync scope, and query subsets.
+     */
+    reconnect(): Promise<void>;
+    private reconnectInternal;
     /**
      * Export a diagnostics snapshot for debugging and support tickets.
      * Contains connection state, timing info, and queue metrics.
@@ -1042,6 +1130,41 @@ declare class SyncEngine {
      * @param scopeMap - New per-collection scope filters, or undefined to remove scope
      */
     updateScope(scopeMap: SyncScopeMap | undefined): void;
+    /**
+     * A stable identifier for the current sync view: the auth/tenant scope plus the set of
+     * active query subscriptions, canonicalized so the same view always produces the same
+     * string. The delivery watermark is keyed by this, so each distinct view resumes from
+     * its own last position.
+     */
+    private deliverySignature;
+    /**
+     * Switch the active delivery watermark to the current view after a scope or subscription
+     * change. The prior view's watermark is saved so returning to it resumes; the new view's
+     * watermark is restored from the in-memory cache (0 for a never-synced view, which then
+     * does a one-time resync under that view). No data is lost: a view's watermark is a lower
+     * bound for that specific view's filter.
+     */
+    private switchDeliveryView;
+    /**
+     * Record a view's watermark in the in-memory cache as the most-recently-used entry (the
+     * Map preserves insertion order, so re-inserting moves it to the tail), then evict cold
+     * views past the retention cap. This is the single place the cache is written, so LRU
+     * order and the size bound are always maintained together.
+     */
+    private setViewWatermark;
+    /**
+     * Trim the per-view watermark cache to `MAX_DELIVERY_VIEW_WATERMARKS`, evicting the
+     * least-recently-used views. The default view ('') and the live view are never evicted
+     * (evicting the live view would force an immediate re-scan of what we are actively
+     * syncing). Each eviction also removes the persisted row, bounding storage. Safe by
+     * construction: an evicted view simply back-fills from 0 (deduplicated) when next seen.
+     */
+    private evictColdViewWatermarks;
+    /**
+     * Remove a view's persisted watermark row (best-effort; a persistence layer that omits
+     * the delete simply keeps the row, which is harmless).
+     */
+    private deleteDeliveryWatermark;
     /**
      * Get the currently active scope map. Returns undefined if no scope is configured.
      */
@@ -1051,6 +1174,9 @@ declare class SyncEngine {
      * Takes effect on the next connection; reconnects when already connected.
      */
     registerQuerySubset(subset: SyncQuerySubset): () => void;
+    private switchDeliveryViewWithInheritance;
+    /** Atomically replace the manifest used by static query-subset mode. */
+    setQuerySubsets(subsets: SyncQuerySubset[]): void;
     /**
      * Returns deduplicated active query subsets from registered subscriptions.
      */
@@ -1105,8 +1231,29 @@ declare class SyncEngine {
     private markDeltaSendCompleteIfReady;
     private collectDelta;
     private handleOperationBatch;
+    /** Acknowledge a delivery batch (used for duplicates) without re-applying it. */
+    private sendDeliveryAck;
     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.
@@ -1127,13 +1274,20 @@ declare class SyncEngine {
      */
     private reconcileOutboundFromOpLog;
     private flushQueue;
+    private startOutboundAckTimer;
+    private clearOutboundAckTimer;
+    private handleOutboundAckTimeout;
     private handleAwarenessUpdate;
     private handleTransportClose;
     private handleTransportError;
     private transitionTo;
     private setSerializerWireFormat;
     private operationAllowedForSync;
+    private matchesScopeAndSubsets;
+    private readRecordForBackfill;
+    private filterAllowedForSync;
     private persistDeltaCursor;
+    private persistDeliveryWatermark;
     private scheduleQuerySubsetReconnect;
     private reconnectForQuerySubsets;
 }
@@ -1375,4 +1529,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-iXX0KA_W.js';
+export { A as AcknowledgmentMessage, p as ActiveApplyFailure, q as AwarenessStateWire, r as AwarenessUpdateMessage, E as EncryptedPayload, s as ErrorMessage, H as HandshakeMessage, t as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, u as OperationRejectedMessage, v as SYNC_STATES, w as SYNC_STATUSES, x as ScopeViolationError, y as SyncEncryptionAlgorithm, z as SyncPhase, C as SyncScopeContext, F as SyncSettlementOptions, G as SyncSettlementResult, J as SyncStatus, K as dedupeQuerySubsets, L as isAcknowledgmentMessage, N as isAwarenessUpdateMessage, P as isBlobChunkPushMessage, U as isBlobChunkRequestMessage, X as isBlobChunkResponseMessage, Z as isErrorMessage, _ as isHandshakeMessage, $ as isHandshakeResponseMessage, a0 as isOperationBatchMessage, a1 as isOperationRejectedMessage, a2 as isSyncMessage, a3 as isYjsDocUpdateMessage, a4 as operationMatchesQuerySubsets, a5 as querySubsetContains } from './transport-iXX0KA_W.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';
@@ -95,6 +95,17 @@ interface SyncStore {
         idMapping: Record<string, string>;
         rebasedCount: number;
     }>;
+    /**
+     * Optional: read a record's current materialized field values, used to backfill
+     * scope / query-subset fields that a partial update (or a delete) does not carry
+     * in its own data. Without it, such an operation would be judged out of scope by
+     * its changed fields alone and wrongly dropped from sync. Optional so hand-rolled
+     * SyncStore implementations keep working; when absent, the engine falls back to
+     * judging visibility from the operation's own data.
+     *
+     * @returns the record's fields, or null when it cannot be read.
+     */
+    readRecordFields?(collection: string, recordId: string): Promise<Record<string, unknown> | null>;
 }
 
 /** Prefix for handshake rejection when client schema version is unsupported. */
@@ -272,6 +283,14 @@ interface ChaosConfig {
     maxLatency?: number;
     /** Injectable random source for deterministic testing. Returns value in [0, 1). */
     randomSource?: () => number;
+    /**
+     * Deterministic targeted drop. When it returns true for a message and direction,
+     * that message is dropped unconditionally (independent of `dropRate`). Enables
+     * reproducing an exact gap (e.g. drop one specific operation) instead of relying
+     * on probabilistic drops. `direction` is 'outgoing' for `send` and 'incoming' for
+     * messages arriving from the inner transport.
+     */
+    dropPredicate?: (message: SyncMessage, direction: 'outgoing' | 'incoming') => boolean;
 }
 /**
  * Chaos transport that wraps another transport and injects faults.
@@ -287,6 +306,7 @@ declare class ChaosTransport implements SyncTransport {
     private readonly reorderRate;
     private readonly maxLatency;
     private readonly random;
+    private readonly dropPredicate;
     private messageHandler;
     private reorderBuffer;
     private pending;
@@ -805,6 +825,13 @@ declare class OutboundQueue {
      * Acknowledge a batch, removing its operations permanently.
      */
     acknowledge(batchId: string): Promise<void>;
+    /**
+     * Acknowledge only operations in an in-flight batch whose local sequence number is
+     * covered by the server's ack. Any later operations return to the front of the
+     * queue for retry. This is required when the server accepts a prefix but rejects a
+     * later operation retriably (for example a stale-scope push after auth changed).
+     */
+    acknowledgeThrough(batchId: string, lastSequenceNumber: number): Promise<void>;
     /**
      * Return a failed batch to the front of the queue for retry.
      * Prepends the operations to maintain priority.
@@ -844,6 +871,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 +902,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
@@ -894,6 +934,8 @@ interface SyncDiagnostics {
     pendingOperations: number;
     hasInFlightBatch: boolean;
     reconnecting: boolean;
+    deliveryWatermark: number;
+    deliveryGapRepeatCount: number;
     timestamp: number;
 }
 /**
@@ -911,7 +953,9 @@ declare class SyncEngine {
     private readonly serializer;
     private readonly emitter;
     private readonly outboundQueue;
+    private readonly rejectedStorage;
     private readonly batchSize;
+    private readonly outboundAckTimeoutMs;
     private readonly encryptor;
     private readonly awarenessManager;
     private readonly richtextDocChannel;
@@ -926,11 +970,21 @@ declare class SyncEngine {
     private lastSuccessfulPull;
     private conflictCount;
     private currentBatch;
+    private currentBatchRequiresPartialAck;
     private reconnecting;
     private schemaBlocked;
     private clockBlocked;
     private clockSkewMs;
     private blobStorageEnabled;
+    private suspensionReason;
+    private authRejected;
+    private serverFrontier;
+    private hasInFlightDeliveryBatch;
+    private blockedFailure;
+    private outboundAckTimer;
+    private startPromise;
+    private stopPromise;
+    private reconnectPromise;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -946,19 +1000,43 @@ declare class SyncEngine {
     private activeScope;
     /** Live query subsets registered from reactive subscriptions */
     private querySubsets;
+    private staticQuerySubsets;
     private querySubsetReconnectTimer;
     /** Resume cursor for paginated initial sync (persisted across reconnects) */
     private resumeDeltaCursor;
     private initialSyncTotalBatches;
+    /**
+     * The delivery watermark for the CURRENT sync view: the highest server delivery
+     * sequence up to which every operation in the current view (scope + active query
+     * subscriptions) has been contiguously applied. Advanced only through the server's
+     * gap-free delivery stream (never through live relay), so it is a durable lower bound
+     * on what this client holds for this view. Reported at handshake to resume the stream.
+     *
+     * The watermark is keyed by view: switching views (a scope or subscription change)
+     * saves the current view's watermark and loads the target view's, so returning to a
+     * previously-synced view resumes exactly where it left off instead of re-syncing. This
+     * is correct because a view's watermark is a lower bound specific to that view's
+     * filter; a widened view is simply a different (initially unsynced) view.
+     */
+    private deliveryWatermark;
+    /**
+     * In-memory cache of watermark per view signature, preloaded from persistence at start
+     * so a view switch resolves synchronously (no race with the reconnect it triggers).
+     */
+    private readonly deliverySignatureWatermarks;
+    private deliveryGapRepeatCount;
+    private lastDeliveryGapKey;
     constructor(options: SyncEngineOptions);
     /**
      * Start the sync engine: connect → handshake → delta exchange → streaming.
      */
     start(): Promise<void>;
+    private startInternal;
     /**
      * Stop the sync engine. Disconnects the transport.
      */
     stop(): Promise<void>;
+    private stopInternal;
     private ensureDisconnected;
     /**
      * Push a local operation to the outbound queue.
@@ -979,6 +1057,7 @@ declare class SyncEngine {
      * Get the current developer-facing sync status.
      */
     getStatus(): SyncStatusInfo;
+    private resolvePhase;
     /**
      * 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.
@@ -1016,6 +1095,15 @@ declare class SyncEngine {
      * or in error state, restarts the sync. If already connected, no-op.
      */
     retryNow(): Promise<void>;
+    /** Wake a permanent auth suspension after the binding reports a new auth state. */
+    notifyAuthChanged(): void;
+    /**
+     * Atomically refresh the transport session. Overlapping callers share one
+     * reconnect, in-flight outbound batches are returned to the queue by stop(), and the
+     * next start handshakes with the latest auth token, sync scope, and query subsets.
+     */
+    reconnect(): Promise<void>;
+    private reconnectInternal;
     /**
      * Export a diagnostics snapshot for debugging and support tickets.
      * Contains connection state, timing info, and queue metrics.
@@ -1042,6 +1130,41 @@ declare class SyncEngine {
      * @param scopeMap - New per-collection scope filters, or undefined to remove scope
      */
     updateScope(scopeMap: SyncScopeMap | undefined): void;
+    /**
+     * A stable identifier for the current sync view: the auth/tenant scope plus the set of
+     * active query subscriptions, canonicalized so the same view always produces the same
+     * string. The delivery watermark is keyed by this, so each distinct view resumes from
+     * its own last position.
+     */
+    private deliverySignature;
+    /**
+     * Switch the active delivery watermark to the current view after a scope or subscription
+     * change. The prior view's watermark is saved so returning to it resumes; the new view's
+     * watermark is restored from the in-memory cache (0 for a never-synced view, which then
+     * does a one-time resync under that view). No data is lost: a view's watermark is a lower
+     * bound for that specific view's filter.
+     */
+    private switchDeliveryView;
+    /**
+     * Record a view's watermark in the in-memory cache as the most-recently-used entry (the
+     * Map preserves insertion order, so re-inserting moves it to the tail), then evict cold
+     * views past the retention cap. This is the single place the cache is written, so LRU
+     * order and the size bound are always maintained together.
+     */
+    private setViewWatermark;
+    /**
+     * Trim the per-view watermark cache to `MAX_DELIVERY_VIEW_WATERMARKS`, evicting the
+     * least-recently-used views. The default view ('') and the live view are never evicted
+     * (evicting the live view would force an immediate re-scan of what we are actively
+     * syncing). Each eviction also removes the persisted row, bounding storage. Safe by
+     * construction: an evicted view simply back-fills from 0 (deduplicated) when next seen.
+     */
+    private evictColdViewWatermarks;
+    /**
+     * Remove a view's persisted watermark row (best-effort; a persistence layer that omits
+     * the delete simply keeps the row, which is harmless).
+     */
+    private deleteDeliveryWatermark;
     /**
      * Get the currently active scope map. Returns undefined if no scope is configured.
      */
@@ -1051,6 +1174,9 @@ declare class SyncEngine {
      * Takes effect on the next connection; reconnects when already connected.
      */
     registerQuerySubset(subset: SyncQuerySubset): () => void;
+    private switchDeliveryViewWithInheritance;
+    /** Atomically replace the manifest used by static query-subset mode. */
+    setQuerySubsets(subsets: SyncQuerySubset[]): void;
     /**
      * Returns deduplicated active query subsets from registered subscriptions.
      */
@@ -1105,8 +1231,29 @@ declare class SyncEngine {
     private markDeltaSendCompleteIfReady;
     private collectDelta;
     private handleOperationBatch;
+    /** Acknowledge a delivery batch (used for duplicates) without re-applying it. */
+    private sendDeliveryAck;
     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.
@@ -1127,13 +1274,20 @@ declare class SyncEngine {
      */
     private reconcileOutboundFromOpLog;
     private flushQueue;
+    private startOutboundAckTimer;
+    private clearOutboundAckTimer;
+    private handleOutboundAckTimeout;
     private handleAwarenessUpdate;
     private handleTransportClose;
     private handleTransportError;
     private transitionTo;
     private setSerializerWireFormat;
     private operationAllowedForSync;
+    private matchesScopeAndSubsets;
+    private readRecordForBackfill;
+    private filterAllowedForSync;
     private persistDeltaCursor;
+    private persistDeliveryWatermark;
     private scheduleQuerySubsetReconnect;
     private reconnectForQuerySubsets;
 }
@@ -1375,4 +1529,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 };