@korajs/sync 0.3.2 → 0.5.0

package/dist/index.d.ts

@@ -1,11 +1,57 @@
-import { S as SyncMessage, a as SerializedOperation, W as WireFormat, b as SyncTransport, T as TransportOptions, c as TransportMessageHandler, d as TransportCloseHandler, e as TransportErrorHandler, Q as QueueStorage, f as SyncConfig, g as SyncStatusInfo, h as SyncState } from './transport-B5EFsr5F.js';
-export { A as AcknowledgmentMessage, E as ErrorMessage, H as HandshakeMessage, i as HandshakeResponseMessage, O as OperationBatchMessage, j as SYNC_STATES, k as SYNC_STATUSES, l as SyncScopeContext, m as SyncStatus, n as isAcknowledgmentMessage, o as isErrorMessage, p as isHandshakeMessage, q as isHandshakeResponseMessage, r as isOperationBatchMessage, s as isSyncMessage } from './transport-B5EFsr5F.js';
-import { VersionVector, Operation, KoraEventEmitter, TimeSource, ConnectionQuality } from '@korajs/core';
+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, g as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig, k as SyncStatePersistence, l as SyncQuerySubset } from './transport-BrdBj7rH.js';
+export { A as AcknowledgmentMessage, m as AwarenessStateWire, n as AwarenessUpdateMessage, E as EncryptedPayload, o as ErrorMessage, H as HandshakeMessage, p as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, q as SYNC_STATES, r as SYNC_STATUSES, s as ScopeViolationError, t as SyncEncryptionAlgorithm, u as SyncScopeContext, v as SyncStatus, w as dedupeQuerySubsets, x as isAcknowledgmentMessage, y as isAwarenessUpdateMessage, z as isErrorMessage, B as isHandshakeMessage, C as isHandshakeResponseMessage, F as isOperationBatchMessage, G as isSyncMessage, J as isYjsDocUpdateMessage, K as operationMatchesQuerySubsets } from './transport-BrdBj7rH.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';
 
 /**
- * Result of applying a remote operation to the store.
+ * Check whether an operation matches the given scope map.
+ *
+ * Rules:
+ * - No scope map configured: operation is always in scope.
+ * - Collection not present in scope map: operation is out of scope.
+ * - Empty scope for a collection `{}`: no field restrictions, operation is in scope.
+ * - Scope has field/value pairs: all must match in the operation's data snapshot.
+ *
+ * For updates, the snapshot is built by merging `previousData` and `data` (data wins),
+ * which represents the record's state after the operation is applied. When an optional
+ * `fullRecord` is provided (e.g., from the local store), its values fill in scope fields
+ * that weren't included in the operation's data (critical for update operations where
+ * `data` only contains changed fields).
+ *
+ * @param op - The operation to check
+ * @param scopeMap - Per-collection scope filters, or undefined for no filtering
+ * @param fullRecord - Optional full record state from the store, used to fill in scope
+ *   fields not present in the operation's partial data
+ * @returns true if the operation is within scope
+ */
+declare function operationMatchesScope(op: Operation, scopeMap: SyncScopeMap | undefined, fullRecord?: Record<string, unknown> | null): boolean;
+/**
+ * Filter operations to only those matching the given scope map.
+ *
+ * @param operations - Array of operations to filter
+ * @param scopeMap - Per-collection scope filters
+ * @returns Operations that match the scope
+ */
+declare function filterOperationsByScope(operations: Operation[], scopeMap: SyncScopeMap | undefined): Operation[];
+
+/**
+ * Encode a delta cursor for wire transfer or `_kora_meta` persistence.
+ */
+declare function encodeDeltaCursor(cursor: DeltaCursor): string;
+/**
+ * Decode a delta cursor string. Returns null when malformed.
+ */
+declare function decodeDeltaCursor(value: string | undefined | null): DeltaCursor | null;
+/**
+ * Slice a causally sorted operation list to resume after a cursor.
+ */
+declare function sliceOperationsAfterCursor(operations: _korajs_core.Operation[], cursor: DeltaCursor | null): _korajs_core.Operation[];
+/**
+ * Build a cursor from the last operation in a delta batch.
  */
-type ApplyResult = 'applied' | 'duplicate' | 'skipped';
+declare function createDeltaCursorFromBatch(operations: _korajs_core.Operation[], batchIndex: number): DeltaCursor | null;
+
 /**
  * Interface that the local store must implement for sync.
  * This decouples @korajs/sync from @korajs/store — the store satisfies this interface.
@@ -37,6 +83,20 @@ interface SyncStore {
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
 }
 
+/** Prefix for handshake rejection when client schema version is unsupported. */
+declare const SCHEMA_MISMATCH_PREFIX = "SCHEMA_MISMATCH";
+/**
+ * Returns true when a handshake `rejectReason` indicates unsupported schema version.
+ */
+declare function isSchemaMismatchReject(rejectReason: string | undefined): boolean;
+/**
+ * Returns true when the client schema version is within the inclusive supported range.
+ */
+declare function isClientSchemaVersionSupported(clientVersion: number, supported: {
+    min: number;
+    max: number;
+}): boolean;
+
 type EncodedMessage = string | Uint8Array;
 /**
  * Interface for encoding/decoding sync protocol messages.
@@ -229,6 +289,396 @@ declare class ChaosTransport implements SyncTransport {
     private flushReorderBuffer;
 }
 
+/**
+ * Cursor position within a richtext field.
+ * Uses Yjs-compatible anchor/head positions for editor interop.
+ */
+interface AwarenessCursor {
+    /** Collection containing the record being edited */
+    collection: string;
+    /** ID of the record being edited */
+    recordId: string;
+    /** Field name of the richtext field */
+    field: string;
+    /** Cursor anchor position in Y.Text (start of selection) */
+    anchor: number;
+    /** Cursor head position in Y.Text (end of selection, same as anchor if no selection) */
+    head: number;
+}
+/**
+ * User identity information for presence display.
+ */
+interface AwarenessUser {
+    /** Display name of the user */
+    name: string;
+    /** Hex color for cursor/selection rendering (e.g. '#ff0000') */
+    color: string;
+    /** Optional avatar URL */
+    avatar?: string;
+}
+/**
+ * Per-client awareness state. Ephemeral -- not persisted, only shared with connected peers.
+ * Compatible with Yjs awareness protocol format for interop with existing editors.
+ */
+interface AwarenessState {
+    /** User identity information */
+    user: AwarenessUser;
+    /** Current cursor position, if any */
+    cursor?: AwarenessCursor;
+}
+/**
+ * Internal awareness message format used between AwarenessManager and transport layer.
+ */
+interface AwarenessMessage {
+    type: 'awareness';
+    /** Client ID of the sender */
+    clientId: number;
+    /** All known awareness states. null value means removal. */
+    states: Record<number, AwarenessState | null>;
+}
+/**
+ * Describes a change in awareness states.
+ * Emitted when remote clients update or remove their presence.
+ */
+interface AwarenessChange {
+    /** Client IDs whose states were added */
+    added: number[];
+    /** Client IDs whose states were updated */
+    updated: number[];
+    /** Client IDs whose states were removed */
+    removed: number[];
+}
+/**
+ * Cursor information for rendering in editors.
+ * This is the developer-facing type -- simplified from internal awareness state.
+ * Editor-agnostic: provides data that can be rendered by TipTap, ProseMirror, Quill, etc.
+ */
+interface CursorInfo {
+    /** Unique client ID */
+    clientId: number;
+    /** User display name */
+    userName: string;
+    /** Hex color for cursor rendering */
+    color: string;
+    /** Cursor anchor position (start of selection) */
+    anchor: number;
+    /** Cursor head position (end of selection) */
+    head: number;
+}
+
+/**
+ * Callback for awareness change events.
+ */
+type AwarenessChangeListener = (change: AwarenessChange) => void;
+/**
+ * Manages collaborative awareness state (cursor positions, user presence).
+ *
+ * Awareness is ephemeral -- states are never persisted, only shared with
+ * currently connected peers via the sync transport. This implements a
+ * lightweight protocol compatible with Yjs awareness semantics.
+ *
+ * Each AwarenessManager has a unique client ID and tracks both its own
+ * local state and all remote clients' states.
+ */
+declare class AwarenessManager {
+    /** Unique client ID for this instance */
+    readonly clientId: number;
+    private localState;
+    private readonly remoteStates;
+    private readonly listeners;
+    private readonly emitter;
+    private readonly timeoutMs;
+    private readonly lastUpdated;
+    private cleanupTimer;
+    private sendHandler;
+    private destroyed;
+    constructor(options?: {
+        clientId?: number;
+        emitter?: KoraEventEmitter;
+        timeoutMs?: number;
+    });
+    /**
+     * Set the local user's awareness state and broadcast to peers.
+     *
+     * @param state - The awareness state to share. Pass null to clear presence.
+     */
+    setLocalState(state: AwarenessState | null): void;
+    /**
+     * Get the local awareness state.
+     */
+    getLocalState(): AwarenessState | null;
+    /**
+     * Get all known awareness states (local + remote).
+     * Returns a new Map on each call.
+     */
+    getStates(): Map<number, AwarenessState>;
+    /**
+     * Handle an incoming awareness message from the transport.
+     * This processes remote state updates and notifies listeners.
+     */
+    handleRemoteMessage(message: AwarenessMessage): void;
+    /**
+     * Remove a specific remote client's awareness state.
+     * Called when the server notifies that a client has disconnected.
+     */
+    removeClient(clientId: number): void;
+    /**
+     * Register a handler for sending awareness messages through the transport.
+     * The sync engine calls this to wire outgoing awareness messages to the transport.
+     */
+    onSend(handler: (message: AwarenessMessage) => void): void;
+    /**
+     * Register a listener for awareness state changes.
+     * Returns an unsubscribe function.
+     */
+    on(_event: 'change', listener: AwarenessChangeListener): () => void;
+    /**
+     * Remove a specific change listener.
+     */
+    off(_event: 'change', listener: AwarenessChangeListener): void;
+    /**
+     * Start the cleanup timer that removes stale remote states.
+     * Called when the sync engine transitions to streaming state.
+     */
+    startCleanupTimer(): void;
+    /**
+     * Stop the cleanup timer.
+     */
+    stopCleanupTimer(): void;
+    /**
+     * Clean up all resources. After calling destroy(), the manager
+     * will no longer send or receive awareness updates.
+     * Broadcasts removal of local state before shutting down.
+     */
+    destroy(): void;
+    private cleanupStaleStates;
+    private notifyListeners;
+    private emitAwarenessEvent;
+}
+
+/**
+ * Configuration for the SyncMetricsCollector.
+ */
+interface MetricsCollectorConfig {
+    /** Number of RTT samples to keep for percentile calculations. Defaults to 100. */
+    rttWindowSize?: number;
+    /** Number of bandwidth samples to keep. Defaults to 20. */
+    bandwidthWindowSize?: number;
+    /** Interval in ms between periodic diagnostics emissions. Defaults to 5000. */
+    diagnosticsInterval?: number;
+    /** Injectable time source for deterministic testing. */
+    timeSource?: TimeSource;
+}
+
+/**
+ * Thrown when encryption of operation data fails.
+ */
+declare class EncryptionError extends SyncError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when decryption of operation data fails.
+ * This typically indicates a wrong key, tampered ciphertext, or corrupted data.
+ */
+declare class DecryptionError extends SyncError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Encrypts and decrypts operation `data` and `previousData` fields for
+ * end-to-end encryption in the sync layer.
+ *
+ * **Design principles:**
+ * - Only `data` and `previousData` are encrypted. Metadata (id, nodeId,
+ *   collection, timestamps, causalDeps, etc.) stays in cleartext so the
+ *   server can route, deduplicate, and order operations.
+ * - Each field encryption uses a unique random IV (12 bytes for AES-GCM),
+ *   ensuring that encrypting the same data twice produces different ciphertext.
+ * - Key rotation is supported via versioned keys. The key version is embedded
+ *   in the {@link EncryptedPayload} so the decryptor can select the correct key.
+ * - Unencrypted fields pass through during decryption (backward compatibility).
+ *
+ * @example
+ * ```typescript
+ * const encryptor = await SyncEncryptor.create({
+ *   enabled: true,
+ *   key: 'user-passphrase'
+ * })
+ *
+ * // Encrypt before sending
+ * const encrypted = await encryptor.encryptOperation(operation)
+ *
+ * // Decrypt after receiving
+ * const decrypted = await encryptor.decryptOperation(encrypted)
+ * ```
+ */
+declare class SyncEncryptor {
+    /**
+     * Map of key version -> VersionedKey. The current (latest) version is used
+     * for encryption. All versions are available for decryption (key rotation).
+     */
+    private readonly keys;
+    /** The current key version used for encryption. */
+    private currentVersion;
+    private constructor();
+    /**
+     * Creates a SyncEncryptor from a {@link SyncEncryptionConfig}.
+     *
+     * Derives the encryption key from the passphrase using PBKDF2. The key
+     * derivation is async because it uses the Web Crypto API.
+     *
+     * @param config - Encryption configuration with passphrase
+     * @param salt - Optional salt for deterministic key derivation (mainly for testing).
+     *              If omitted, a random salt is generated.
+     * @returns A configured SyncEncryptor instance
+     * @throws {EncryptionError} If configuration is invalid
+     * @throws {KeyDerivationError} If key derivation fails
+     */
+    static create(config: SyncEncryptionConfig, salt?: Uint8Array): Promise<SyncEncryptor>;
+    /**
+     * Creates a SyncEncryptor from pre-derived versioned keys.
+     *
+     * Use this when you need to support multiple key versions for key rotation,
+     * or when you have already derived the keys externally.
+     *
+     * @param versionedKeys - Array of versioned keys. The highest version is used for encryption.
+     * @returns A configured SyncEncryptor instance
+     * @throws {EncryptionError} If no keys are provided
+     */
+    static fromKeys(versionedKeys: VersionedKey[]): SyncEncryptor;
+    /**
+     * Add a new key version for key rotation.
+     *
+     * After adding, the new key becomes the current version used for encryption
+     * if its version number is higher than the current version. Previously-versioned
+     * keys remain available for decrypting older operations.
+     *
+     * @param key - The new versioned key to add
+     * @throws {EncryptionError} If the key version already exists
+     */
+    addKey(key: VersionedKey): void;
+    /**
+     * Get the current encryption key version number.
+     */
+    getCurrentKeyVersion(): number;
+    /**
+     * Encrypt an operation's `data` and `previousData` fields.
+     *
+     * Returns a new Operation with encrypted field values. The original
+     * operation is not mutated (operations are immutable).
+     *
+     * Fields that are null (e.g., delete operations) remain null.
+     *
+     * @param operation - The operation to encrypt
+     * @returns A new operation with encrypted data fields
+     * @throws {EncryptionError} If encryption fails
+     */
+    encryptOperation(operation: Operation): Promise<Operation>;
+    /**
+     * Decrypt an operation's `data` and `previousData` fields.
+     *
+     * Returns a new Operation with the original field values restored.
+     * The original operation is not mutated.
+     *
+     * If a field is null or not encrypted (no marker), it passes through unchanged.
+     * This enables mixed plaintext/encrypted operations during migration.
+     *
+     * @param operation - The operation to decrypt
+     * @returns A new operation with decrypted data fields
+     * @throws {DecryptionError} If decryption fails (wrong key, tampered data, unsupported version)
+     */
+    decryptOperation(operation: Operation): Promise<Operation>;
+    /**
+     * Encrypt a serialized operation's `data` and `previousData` fields.
+     *
+     * Same as {@link encryptOperation} but works with the wire-format
+     * {@link SerializedOperation} type used by the serializer.
+     *
+     * @param serialized - The serialized operation to encrypt
+     * @returns A new serialized operation with encrypted data fields
+     * @throws {EncryptionError} If encryption fails
+     */
+    encryptSerializedOperation(serialized: SerializedOperation): Promise<SerializedOperation>;
+    /**
+     * Decrypt a serialized operation's `data` and `previousData` fields.
+     *
+     * Same as {@link decryptOperation} but works with the wire-format
+     * {@link SerializedOperation} type used by the serializer.
+     *
+     * @param serialized - The serialized operation to decrypt
+     * @returns A new serialized operation with decrypted data fields
+     * @throws {DecryptionError} If decryption fails
+     */
+    decryptSerializedOperation(serialized: SerializedOperation): Promise<SerializedOperation>;
+    /**
+     * Encrypt a batch of operations in parallel.
+     *
+     * @param operations - Operations to encrypt
+     * @returns New operations with encrypted data fields
+     */
+    encryptBatch(operations: Operation[]): Promise<Operation[]>;
+    /**
+     * Decrypt a batch of operations in parallel.
+     *
+     * @param operations - Operations to decrypt
+     * @returns New operations with decrypted data fields
+     */
+    decryptBatch(operations: Operation[]): Promise<Operation[]>;
+    /**
+     * Check if a field value contains an encrypted payload.
+     *
+     * @param field - An operation's `data` or `previousData` field
+     * @returns true if the field contains an encrypted payload
+     */
+    static isEncryptedPayload(field: Record<string, unknown> | null): boolean;
+    private encryptField;
+    private decryptField;
+}
+/**
+ * Check if a field value contains an encrypted payload.
+ *
+ * @param field - An operation's `data` or `previousData` field
+ * @returns true if the field contains an encrypted payload
+ */
+declare function isEncryptedPayload(field: Record<string, unknown> | null): boolean;
+
+/** Default snapshot size above which the doc channel is preferred. */
+declare const DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD = 4096;
+type RichtextDocListener = (update: Uint8Array) => void;
+interface RichtextDocChannelOptions {
+    /** Snapshot byte length at which incremental channel sync is recommended. */
+    largeDocThreshold?: number;
+    /** Called when a local update should be sent on the wire. */
+    onSend?: (message: YjsDocUpdateMessage) => void;
+}
+/**
+ * Side channel for incremental Yjs updates on large richtext fields.
+ * Ephemeral — not persisted in the operation log (durable state still flows via ops).
+ */
+declare class RichtextDocChannel {
+    private readonly threshold;
+    private readonly onSend;
+    private readonly listeners;
+    constructor(options?: RichtextDocChannelOptions);
+    /**
+     * Whether the doc channel should be used for a field.
+     * @param preference - `true` forces on, `false` forces off, `undefined` uses size threshold
+     */
+    shouldUseChannel(snapshotByteLength: number, preference?: boolean): boolean;
+    getThreshold(): number;
+    /**
+     * Subscribe to incremental updates for a document key.
+     */
+    subscribe(collection: string, recordId: string, field: string, listener: RichtextDocListener): () => void;
+    /**
+     * Publish a local incremental update to peers.
+     */
+    send(collection: string, recordId: string, field: string, update: Uint8Array): void;
+    /**
+     * Deliver a remote incremental update to local subscribers.
+     */
+    deliver(message: YjsDocUpdateMessage): void;
+}
+
 /**
  * A batch of operations taken from the queue for sending.
  */
@@ -299,6 +749,11 @@ declare class OutboundQueue {
      * Whether initialize() has been called.
      */
     get isInitialized(): boolean;
+    /**
+     * Remove operations by id from queue and persistent storage.
+     * Used when ops were already sent during handshake delta exchange.
+     */
+    removeByIds(ids: string[]): Promise<void>;
 }
 
 /**
@@ -317,6 +772,34 @@ interface SyncEngineOptions {
     emitter?: KoraEventEmitter;
     /** Queue storage for persistent outbound queue. Defaults to in-memory. */
     queueStorage?: QueueStorage;
+    /**
+     * Optional encryptor for end-to-end encryption.
+     * When provided, `data` and `previousData` fields of operations are encrypted
+     * before sending and decrypted after receiving. The server never sees plaintext data.
+     */
+    encryptor?: SyncEncryptor;
+    /** Optional configuration for the metrics collector. */
+    metricsConfig?: MetricsCollectorConfig;
+    /** Op-log backed sync state (last acked server vector, unsynced counts). */
+    syncState?: SyncStatePersistence;
+}
+/**
+ * Diagnostics snapshot for debugging and support.
+ */
+interface SyncDiagnostics {
+    state: SyncState;
+    status: SyncStatusInfo;
+    nodeId: string;
+    url: string;
+    schemaVersion: number;
+    lastSyncedAt: number | null;
+    lastSuccessfulPush: number | null;
+    lastSuccessfulPull: number | null;
+    conflicts: number;
+    pendingOperations: number;
+    hasInFlightBatch: boolean;
+    reconnecting: boolean;
+    timestamp: number;
 }
 /**
  * Core sync orchestrator. Manages the sync lifecycle:
@@ -334,13 +817,40 @@ declare class SyncEngine {
     private readonly emitter;
     private readonly outboundQueue;
     private readonly batchSize;
+    private readonly encryptor;
+    private readonly awarenessManager;
+    private readonly richtextDocChannel;
+    private readonly metricsCollector;
+    private readonly syncState;
     private remoteVector;
+    private lastAckedServerVector;
+    private cachedUnsyncedCount;
     private lastSyncedAt;
+    private lastSuccessfulPush;
+    private lastSuccessfulPull;
+    private conflictCount;
     private currentBatch;
     private reconnecting;
+    private schemaBlocked;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
+    /** Op ids sent during handshake delta — removed from outbound queue to avoid duplicate send */
+    private deltaSentOpIds;
+    /** Outbound delta batch message IDs awaiting ACK when strictHandshake is enabled */
+    private pendingDeltaBatchAcks;
+    /**
+     * The effective scope for this sync session.
+     * Starts as the configured scopeMap. After handshake, may be replaced
+     * with the server-accepted scope (server is authoritative).
+     */
+    private activeScope;
+    /** Live query subsets registered from reactive subscriptions */
+    private querySubsets;
+    private querySubsetReconnectTimer;
+    /** Resume cursor for paginated initial sync (persisted across reconnects) */
+    private resumeDeltaCursor;
+    private initialSyncTotalBatches;
     constructor(options: SyncEngineOptions);
     /**
      * Start the sync engine: connect → handshake → delta exchange → streaming.
@@ -354,6 +864,9 @@ declare class SyncEngine {
     /**
      * Push a local operation to the outbound queue.
      * If streaming, flushes immediately.
+     *
+     * Operations outside the configured sync scope are silently skipped
+     * because they should remain local-only and not be sent to the server.
      */
     pushOperation(op: Operation): Promise<void>;
     /**
@@ -367,6 +880,36 @@ declare class SyncEngine {
      * Get the current developer-facing sync status.
      */
     getStatus(): SyncStatusInfo;
+    /**
+     * 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.
+     */
+    isSchemaBlocked(): boolean;
+    /**
+     * Clears schema-mismatch block after upgrading the local schema / sync config.
+     * Moves the engine back to `disconnected` so `start()` can run again.
+     */
+    clearSchemaBlock(): void;
+    /**
+     * Record a merge conflict. Called by the merge-aware sync store
+     * to increment the conflict counter for status reporting.
+     */
+    recordConflict(): void;
+    /**
+     * Count of local operations not yet covered by the last acked server vector (op-log source of truth).
+     */
+    getUnsyncedOperationCount(): Promise<number>;
+    private emitApplyFailure;
+    /**
+     * Force an immediate reconnection attempt. If the engine is disconnected
+     * or in error state, restarts the sync. If already connected, no-op.
+     */
+    retryNow(): Promise<void>;
+    /**
+     * Export a diagnostics snapshot for debugging and support tickets.
+     * Contains connection state, timing info, and queue metrics.
+     */
+    exportDiagnostics(): SyncDiagnostics;
     /**
      * Get the current internal state (for testing).
      */
@@ -375,19 +918,82 @@ declare class SyncEngine {
      * Get the outbound queue (for testing).
      */
     getOutboundQueue(): OutboundQueue;
-    private handleMessage;
+    /**
+     * Update the sync scope map. Takes effect on the next connection attempt.
+     *
+     * When the scope changes (e.g., user switches organization), call this method
+     * then reconnect. The new scope will be sent in the handshake, and the server
+     * will send back data matching the new scope.
+     *
+     * Data that no longer matches the new scope is NOT deleted locally.
+     * It simply stops being synced.
+     *
+     * @param scopeMap - New per-collection scope filters, or undefined to remove scope
+     */
+    updateScope(scopeMap: SyncScopeMap | undefined): void;
+    /**
+     * Get the currently active scope map. Returns undefined if no scope is configured.
+     */
+    getActiveScope(): SyncScopeMap | undefined;
+    /**
+     * Register a live query subset that narrows synced data for a collection.
+     * Takes effect on the next connection; reconnects when already connected.
+     */
+    registerQuerySubset(subset: SyncQuerySubset): () => void;
+    /**
+     * Returns deduplicated active query subsets from registered subscriptions.
+     */
+    getActiveQuerySubsets(): SyncQuerySubset[];
+    /**
+     * Get the awareness manager for collaborative presence.
+     * Use this to set local presence, observe remote collaborators,
+     * and track cursor positions in richtext fields.
+     */
+    getAwarenessManager(): AwarenessManager;
+    /**
+     * Optional side channel for incremental Yjs updates on large richtext fields.
+     */
+    getRichtextDocChannel(): RichtextDocChannel;
+    private messageChain;
+    private enqueueMessage;
+    private handleMessageAsync;
+    private handleMessageFailure;
     private handleHandshakeResponse;
     private sendDelta;
+    private markDeltaSendCompleteIfReady;
     private collectDelta;
     private handleOperationBatch;
     private handleAcknowledgment;
     private handleError;
     private checkDeltaComplete;
+    /**
+     * Effective server vector: persisted last-ack merged with live handshake remote vector.
+     */
+    private getEffectiveServerVector;
+    private persistLastAckedServerVector;
+    private advanceLastAckedForLocalNode;
+    /**
+     * Refresh cached unsynced count from op log vs effective server vector.
+     */
+    refreshPendingCount(): Promise<void>;
+    /**
+     * Returns operations the server has not yet acknowledged (op-log source of truth).
+     */
+    getPendingSyncOperations(): Promise<Operation[]>;
+    /**
+     * Hydrate the outbound queue from unsynced ops in the op log (deduped by operation id).
+     */
+    private reconcileOutboundFromOpLog;
     private flushQueue;
+    private handleAwarenessUpdate;
     private handleTransportClose;
     private handleTransportError;
     private transitionTo;
     private setSerializerWireFormat;
+    private operationAllowedForSync;
+    private persistDeltaCursor;
+    private scheduleQuerySubsetReconnect;
+    private reconnectForQuerySubsets;
 }
 
 /**
@@ -494,6 +1100,11 @@ declare class ReconnectionManager {
      * @returns Promise that resolves when reconnection succeeds or maxAttempts reached.
      */
     start(onReconnect: () => Promise<boolean>): Promise<boolean>;
+    /**
+     * Cancel the current backoff wait and proceed to the next reconnect attempt immediately.
+     * No-op if not waiting.
+     */
+    wake(): void;
     /**
      * Stop any pending reconnection attempt.
      */
@@ -518,4 +1129,70 @@ declare class ReconnectionManager {
     private wait;
 }
 
-export { type ApplyResult, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, type MessageSerializer, NegotiatedMessageSerializer, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, SerializedOperation, SyncConfig, SyncEngine, type SyncEngineOptions, SyncMessage, SyncState, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, versionVectorToWire, wireToVersionVector };
+/**
+ * Encode a Yjs update for the doc channel wire (base64).
+ */
+declare function encodeYjsUpdate(update: Uint8Array): string;
+/**
+ * Decode a base64 Yjs update from the doc channel wire.
+ */
+declare function decodeYjsUpdate(encoded: string): Uint8Array;
+/**
+ * Build a stable key for a richtext field document.
+ */
+declare function richtextDocKey(collection: string, recordId: string, field: string): string;
+
+/**
+ * Thrown when key derivation fails.
+ */
+declare class KeyDerivationError extends SyncError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Generates a cryptographically random salt for PBKDF2 key derivation.
+ *
+ * @returns A random 32-byte Uint8Array
+ * @throws {KeyDerivationError} If crypto.getRandomValues is unavailable
+ */
+declare function generateSalt(): Uint8Array;
+/**
+ * Derives an AES-256-GCM encryption key from a passphrase using PBKDF2.
+ *
+ * Uses PBKDF2 with SHA-256 and 600,000 iterations (OWASP-recommended minimum)
+ * to derive a 256-bit key. The derived key is deterministic: the same passphrase
+ * and salt always produce the same key.
+ *
+ * @param passphrase - The user's passphrase (must be non-empty)
+ * @param salt - Optional salt bytes. If omitted, a random 32-byte salt is generated.
+ * @returns The derived CryptoKey and the salt used
+ * @throws {KeyDerivationError} If the passphrase is empty, crypto is unavailable, or derivation fails
+ *
+ * @example
+ * ```typescript
+ * // First time: derive key with a new salt
+ * const { key, salt } = await deriveKey('my-secure-passphrase')
+ *
+ * // Later: re-derive the same key using the stored salt
+ * const { key: sameKey } = await deriveKey('my-secure-passphrase', salt)
+ * ```
+ */
+declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
+    key: CryptoKey;
+    salt: Uint8Array;
+}>;
+/**
+ * Derives a versioned encryption key from a passphrase.
+ *
+ * Wraps {@link deriveKey} with a version number for key rotation support.
+ * When the passphrase changes, create a new versioned key with a higher
+ * version number.
+ *
+ * @param passphrase - The user's passphrase
+ * @param version - Key version number (must be a positive integer)
+ * @param salt - Optional salt bytes. If omitted, a random salt is generated.
+ * @returns A {@link VersionedKey} containing the key, version, and salt
+ * @throws {KeyDerivationError} If parameters are invalid or derivation fails
+ */
+declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
+
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, 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, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, versionVectorToWire, wireToVersionVector };