@korajs/sync 0.0.0-canary-20261008174129

package/dist/index.d.ts

@@ -0,0 +1,3089 @@
+import { S as SyncScopeMap, a as ScopeSnapshotOptions, D as DeltaCursor, b as SyncMessage, c as SerializedOperation, W as WireFormat, d as SyncTransport, T as TransportOptions, e as TransportMessageHandler, f as TransportCloseHandler, g as TransportErrorHandler, B as BlobChunkRequestMessage, h as BlobChunkResponseMessage, i as BlobChunkPushMessage, j as WrappedKeyRecord, k as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, l as SyncState, m as SyncStatusInfo, n as SyncConfig, R as RejectedOperationStorage, o as SyncStatePersistence, p as SyncQuerySubset, q as QuarantinedOperation, H as HeldNodeInfo, r as RejectedOperation } from './transport-CoPFFarn.js';
+export { A as AcknowledgmentMessage, s as ActiveApplyFailure, t as AdoptionScheduleInfo, u as AwarenessStateWire, v as AwarenessUpdateMessage, w as DEFAULT_KEYRING, E as EncryptedPayload, x as EncryptionKeyMessage, y as EncryptionKeyPutMessage, z as EncryptionKeyRequestMessage, C as EncryptionKeyResponseMessage, F as EncryptionKeyResponseStatus, G as ErrorMessage, I as HandshakeMessage, J as HandshakeResponseMessage, K as HeartbeatMessage, L as HeldReason, M as INVALID_OPERATION_ID, N as InvalidScopeError, O as KEY_RECORD_FORMAT, P as KeyRecordKdf, U as KeyRecordRecovery, X as KeyRecordValidation, Z as LEGACY_SYNC_PROTOCOL_VERSION, _ as LocalNodeInfo, $ as MAX_KDF_ITERATIONS, a0 as MAX_KEY_RECORD_BYTES, a1 as MemoryRejectedOperationStorage, a2 as OperationBatchMessage, a3 as OperationRejectedMessage, a4 as PLAINTEXT_REJECTED, a5 as PROTOCOL_V1_DEPRECATED, a6 as SYNC_PROTOCOL_VERSION, a7 as SYNC_STATES, a8 as SYNC_STATUSES, a9 as ScopeViolationError, aa as SyncAuthRequest, ab as SyncEncryptionAlgorithm, ac as SyncPhase, ad as SyncScopeContext, ae as SyncSettlementOptions, af as SyncSettlementResult, ag as SyncStatus, ah as TerminalRejectionRecord, ai as WrappedDataKey, aj as WrappedMasterKey, ak as declaredProtocolVersion, al as dedupeQuerySubsets, am as isAcknowledgmentMessage, an as isAwarenessUpdateMessage, ao as isBlobChunkPushMessage, ap as isBlobChunkRequestMessage, aq as isBlobChunkResponseMessage, ar as isEncryptionKeyMessage, as as isErrorMessage, at as isHandshakeMessage, au as isHandshakeResponseMessage, av as isKeyId, aw as isKeyRecordSuccessor, ax as isOperationBatchMessage, ay as isOperationRejectedMessage, az as isSyncMessage, aA as isValidKeyringName, aB as isYjsDocUpdateMessage, aC as operationMatchesQuerySubsets, aD as querySubsetContains, aE as validateKeyRecord } from './transport-CoPFFarn.js';
+import * as _korajs_core from '@korajs/core';
+import { Operation, VersionVector, ApplyResult, OperationTransform, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality, KoraError, SchemaDefinition } from '@korajs/core';
+export { ApplyFailureReason, ApplyResult } from '@korajs/core';
+
+/**
+ * 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.
+ *
+ * The snapshot is the operation's `data` (layered over `previousData` only with
+ * `options.includePreviousData`), with `id` always taken from `op.recordId`,
+ * 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
+ * @param options - Snapshot options; `includePreviousData` trusts the writer's
+ *   `previousData`, which is only safe for a client judging its own local view
+ * @returns true if the operation is within scope
+ */
+declare function operationMatchesScope(op: Operation, scopeMap: SyncScopeMap | undefined, fullRecord?: Record<string, unknown> | null, options?: ScopeSnapshotOptions): 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.
+ */
+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.
+ *
+ * @korajs/store's Store class already implements these methods:
+ * - getVersionVector() — returns the current version vector
+ * - getNodeId() — returns this instance's nodeId
+ * - applyRemoteOperation(op) — applies a remote op with dedup and merge
+ * - getOperationRange(nodeId, fromSeq, toSeq) — fetches operations from the log
+ */
+interface SyncStore {
+    /** Get the current version vector for this store */
+    getVersionVector(): VersionVector;
+    /** Get the node ID for this store instance */
+    getNodeId(): string;
+    /**
+     * Apply a remote operation to the local store.
+     * Must handle deduplication (content-addressed) and merge resolution.
+     * @returns 'applied' if the operation was new, 'duplicate' if already seen, 'skipped' if filtered
+     */
+    applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    /**
+     * Optional: the schema transforms the store folds with (transforms at fold time,
+     * RT-84). The engine hands the store every operation exactly as delivered; the store
+     * folds its view. When present, it must match the engine's `operationTransforms`.
+     */
+    getOperationTransforms?(): readonly OperationTransform[];
+    /**
+     * Get operations from a specific node within a sequence range.
+     * Used for computing deltas during sync.
+     * @param nodeId - The originating node
+     * @param fromSeq - Start sequence number (inclusive)
+     * @param toSeq - End sequence number (inclusive)
+     */
+    getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    /**
+     * Optional: re-stamp never-acknowledged local operations after a fast device
+     * clock was corrected (timestamp rebase). Optional so hand-rolled SyncStore
+     * implementations keep working; when absent the engine simply skips the
+     * rebase and falls back to the clock-block behavior.
+     *
+     * @param ids - Operation ids that are candidates for re-stamping
+     * @param correctedNowMs - Trusted "now" (server time at handshake) in ms
+     */
+    /**
+     * Optional: move the device to a fresh node id, re-authoring the given unsynced
+     * operations under it (RT-21). Called after the server refused the node id
+     * (`NODE_ID_CLAIMED`). Returns the new node id and the rewritten operations.
+     */
+    rotateNodeId?(ids: string[]): Promise<{
+        nodeId: string;
+        operations: Operation[];
+    }>;
+    /**
+     * Optional: the server refused the store's pinned node id as another user's (`true`),
+     * or accepted it again (`false`). A pinned store refuses local writes meanwhile (F9).
+     */
+    setPinnedNodeOwnedElsewhere?(owned: boolean): void;
+    /**
+     * Optional: re-author another local node's given unsynced operations under a fresh
+     * node id bound to `principal`, without moving the store's own node. Called when the
+     * server refused an adopted node whose writes belong to the signed-in user but that
+     * no claims-aware server ever accepted (a beta.12 node with unowned history).
+     */
+    reauthorLocalNode?(fromNodeId: string, ids: string[], principal: string): Promise<{
+        nodeId: string;
+        operations: Operation[];
+    }>;
+    /**
+     * Optional: move the device back to a node id this database authored under before
+     * (RT-38), without rewriting anything. Used after the server refused the current node
+     * (another principal owns it) to try a node the signed-in principal owns.
+     */
+    switchNodeId?(nodeId: string): Promise<void>;
+    /**
+     * Optional: bind local writes to the signed-in user (RT-42). Moves the store to the
+     * user's own node (or a fresh one) when the current node belongs to another user.
+     * `conflict`: the node id is pinned and belongs to another user.
+     */
+    bindPrincipal?(principal: string): Promise<{
+        nodeId: string;
+        previousNodeId: string;
+        switched: boolean;
+        conflict: boolean;
+    }>;
+    /**
+     * Optional durability barrier (RT-35): resolve once every write committed so far is
+     * durable on this device; reject when it cannot be made durable. The engine awaits it
+     * before any operation leaves the device, so the server never holds an operation the
+     * device could lose on reload.
+     */
+    ensureDurable?(): Promise<void>;
+    /**
+     * Optional: raise a local node's sequence counter to at least `floor`, in a
+     * transaction (RT-35: the server holds operations of this node the device lost).
+     * @returns Whether the counter moved
+     */
+    raiseSequenceFloor?(nodeId: string, floor: number): Promise<boolean>;
+    /**
+     * Optional: give a local operation a fresh sequence number above `floor` (RT-35: the
+     * server refused it with `SEQUENCE_CONFLICT` because it holds another operation of
+     * this node, lost locally, under that number). A version-2 operation is re-hashed
+     * under a new id; its never-sent dependents (`rewritableDependents`) are rewritten
+     * to name the new id, transitively.
+     * @returns The renumbered operation, the rewritten dependents and the id mapping,
+     *   or null when it is not in the log
+     */
+    resequenceOperation?(operationId: string, nodeId: string, floor: number, rewritableDependents?: readonly string[]): Promise<{
+        operation: Operation;
+        dependents: Operation[];
+        idMapping: Record<string, string>;
+    } | null>;
+    /**
+     * Optional: take over another local node id's unsynced writes (RT-40). Resolves to a
+     * release function when no live tab uses it, or null when one does.
+     */
+    claimLocalNode?(nodeId: string): Promise<(() => void) | null>;
+    rebaseUnsyncedOperations?(ids: string[], correctedNowMs: number): Promise<{
+        operations: Operation[];
+        idMapping: Record<string, string>;
+        rebasedCount: number;
+    }>;
+    /**
+     * Optional (W7): the server's node ids whose writes win `merge('server-
+     * authoritative')` fields, from the handshake response. The store persists them
+     * and folds with them (re-folding affected records when the set changes).
+     */
+    setAuthoritativeNodeIds?(nodeIds: readonly string[], revokedNodeIds?: readonly string[]): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Optional: whether the local schema defines this collection. Lets the engine tell a
+     * merge-decided `'skipped'` (the record is settled, nothing to keep) from a skip
+     * because the collection is unknown (the operation must be quarantined and replayed
+     * after a schema upgrade). Without it every `'skipped'` result is quarantined.
+     */
+    hasCollection?(collection: string): boolean;
+    /**
+     * Remove a record from this client's materialized authorization view without
+     * writing a domain delete to the replicated operation log.
+     */
+    applyScopeRetraction?(collection: string, recordId: string): Promise<void>;
+    /** Retract every currently materialized row outside a newly accepted scope. */
+    applyScopeNarrowing?(scopes: Record<string, Record<string, unknown>>): Promise<Array<{
+        collection: string;
+        recordId: string;
+    }>>;
+    /**
+     * Optional (W7): the delivery stream caught up (its final batch fully applied).
+     * The store retires local-only provisional cascades of remote deletes (RT-69) and
+     * drops row snapshots whose history a full resync brought back (RT-68). With
+     * `provisionalOnly` it only retires the provisional cascades: a stream batch that is
+     * not the end of a resync must not settle row snapshots (RT-93).
+     *
+     * @returns How many row snapshots were dropped
+     */
+    settleAfterCatchUp?(options?: {
+        provisionalOnly?: boolean;
+    }): Promise<number>;
+}
+
+/** 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.
+ */
+interface MessageSerializer {
+    encode(message: SyncMessage): EncodedMessage;
+    decode(data: string | Uint8Array | ArrayBuffer): SyncMessage;
+    encodeOperation(op: Operation): SerializedOperation;
+    decodeOperation(serialized: SerializedOperation): Operation;
+    setWireFormat?(format: WireFormat): void;
+    getWireFormat?(): WireFormat;
+}
+/**
+ * Convert a VersionVector (Map) to a plain object for wire transmission.
+ */
+declare function versionVectorToWire(vector: VersionVector): Record<string, number>;
+/**
+ * Convert a wire-format version vector (plain object) back to a VersionVector (Map).
+ */
+declare function wireToVersionVector(wire: Record<string, number>): VersionVector;
+/**
+ * JSON-based message serializer.
+ */
+declare class JsonMessageSerializer implements MessageSerializer {
+    encode(message: SyncMessage): string;
+    decode(data: string | Uint8Array | ArrayBuffer): SyncMessage;
+    encodeOperation(op: Operation): SerializedOperation;
+    decodeOperation(serialized: SerializedOperation): Operation;
+}
+/**
+ * Protobuf-based serializer for sync messages.
+ */
+/**
+ * Protobuf message serializer.
+ *
+ * Lossless by construction (SYNC-9): fields with a native protobuf slot are written there;
+ * every other top-level member of the message (fields added after the native mapping,
+ * and the bodies of the JSON-shaped awareness and Yjs messages) travels in the `extJson`
+ * envelope field (49). Decoding therefore yields exactly what the JSON wire would, for
+ * every message type, which a property test over every message type pins.
+ *
+ * It is not negotiated: the sync engine advertises `['json']` only and the server
+ * reports the format its transport actually frames with. Use it explicitly, on both
+ * ends of a transport, or not at all.
+ */
+declare class ProtobufMessageSerializer implements MessageSerializer {
+    encode(message: SyncMessage): Uint8Array;
+    decode(data: string | Uint8Array | ArrayBuffer): SyncMessage;
+    encodeOperation(op: Operation): SerializedOperation;
+    decodeOperation(serialized: SerializedOperation): Operation;
+}
+/**
+ * Negotiated serializer that supports runtime wire-format switching.
+ */
+declare class NegotiatedMessageSerializer implements MessageSerializer {
+    private readonly json;
+    private readonly protobuf;
+    private wireFormat;
+    constructor(initialWireFormat?: WireFormat);
+    encode(message: SyncMessage): EncodedMessage;
+    decode(data: string | Uint8Array | ArrayBuffer): SyncMessage;
+    encodeOperation(op: Operation): SerializedOperation;
+    decodeOperation(serialized: SerializedOperation): Operation;
+    setWireFormat(format: WireFormat): void;
+    getWireFormat(): WireFormat;
+}
+
+/**
+ * WebSocket event interface for dependency injection.
+ * Matches the subset of the browser WebSocket API that we need.
+ */
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        reason: string;
+        code: number;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+/**
+ * Constructor for WebSocket-like objects. Allows injection of mock WebSocket for testing.
+ */
+type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+/**
+ * Options for the WebSocket transport.
+ */
+interface WebSocketTransportOptions {
+    /** Custom serializer. Defaults to JSON. */
+    serializer?: MessageSerializer;
+    /** Injectable WebSocket constructor for testing. Defaults to globalThis.WebSocket. */
+    WebSocketImpl?: WebSocketConstructor;
+    /** Connection timeout in ms. Defaults to 10000 (10s). */
+    connectTimeout?: number;
+    /**
+     * Also append the auth token to the connection URL as `?token=`. Off by
+     * default: the token already travels in the handshake message, and URLs are
+     * recorded by reverse proxies, load balancers and access logs. Enable only for an
+     * intermediary that authenticates the WebSocket upgrade by query parameter.
+     */
+    tokenInUrl?: boolean;
+    /**
+     * Detect dead connections with the server's application-level heartbeat (LMS #12).
+     * The transport advertises support in the handshake; a server that sends
+     * heartbeats states their interval, and a connection that then receives nothing
+     * for `heartbeatTimeoutFactor` intervals is closed as dead, which starts a
+     * reconnect. Browsers cannot observe WebSocket pings, so without this a half-open
+     * connection (a phone that changed networks) looks alive until TCP gives up, often
+     * minutes later. Defaults to true.
+     */
+    heartbeat?: boolean;
+    /** Silent intervals tolerated before the connection is declared dead. Defaults to 2.5. */
+    heartbeatTimeoutFactor?: number;
+}
+/**
+ * WebSocket-based sync transport implementation.
+ *
+ * Every socket is bound to a generation (SYNC-5): `connect()` closes and detaches the
+ * previous socket first, and callbacks of a superseded socket are ignored, so a stale
+ * socket closing late can never sever (or feed messages into) the live session.
+ */
+declare class WebSocketTransport implements SyncTransport {
+    private ws;
+    /** Incremented for every socket; callbacks check theirs is still current. */
+    private generation;
+    private messageHandler;
+    private closeHandler;
+    private errorHandler;
+    private readonly serializer;
+    private readonly WebSocketImpl;
+    private readonly connectTimeout;
+    private readonly tokenInUrl;
+    private readonly heartbeat;
+    private readonly heartbeatTimeoutFactor;
+    /** Silence (ms) after which the current connection is declared dead; 0 = unarmed. */
+    private livenessTimeoutMs;
+    private livenessTimer;
+    constructor(options?: WebSocketTransportOptions);
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    send(message: SyncMessage): void;
+    onMessage(handler: TransportMessageHandler): void;
+    onClose(handler: TransportCloseHandler): void;
+    onError(handler: TransportErrorHandler): void;
+    isConnected(): boolean;
+    /** Close and detach the current socket, if any, without firing the close handler. */
+    private releaseSocket;
+    /** Start watching for silence once the server stated its heartbeat interval. */
+    private armLiveness;
+    private touchLiveness;
+    private clearLiveness;
+}
+
+/**
+ * Header carrying the server-issued HTTP sync session id. The server returns it on
+ * the response to the first POST (the handshake); the client sends it on every
+ * later request, together with its bearer credential.
+ */
+declare const HTTP_SYNC_SESSION_HEADER = "x-kora-session";
+interface HttpLongPollingTransportOptions {
+    serializer?: MessageSerializer;
+    fetchImpl?: typeof fetch;
+    retryDelayMs?: number;
+    preferWebSocket?: boolean;
+    webSocketFactory?: () => SyncTransport;
+}
+/**
+ * HTTP long-polling transport with optional WebSocket upgrade.
+ *
+ * The first POST (the handshake) opens a server-side session; the server answers
+ * with a high-entropy session id in the `x-kora-session` header. Every later
+ * request carries that id and the bearer credential, and the long-poll loop starts
+ * only once the id is known. POSTs are sent one at a time, in order. A 401, 403,
+ * 404 or 410 means the server-side session is gone: the transport closes so the
+ * sync engine reconnects (and re-authenticates) from scratch.
+ */
+declare class HttpLongPollingTransport implements SyncTransport {
+    private readonly serializer;
+    private readonly fetchImpl;
+    private readonly retryDelayMs;
+    private readonly preferWebSocket;
+    private readonly webSocketFactory;
+    private messageHandler;
+    private closeHandler;
+    private errorHandler;
+    private connected;
+    private polling;
+    private url;
+    private authToken;
+    private pollAbort;
+    private upgradedTransport;
+    /** Server-issued session id; null until the handshake POST is answered. */
+    private sessionId;
+    /** Serializes POSTs so the server receives messages in send order. */
+    private postChain;
+    constructor(options?: HttpLongPollingTransportOptions);
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    send(message: SyncMessage): void;
+    onMessage(handler: TransportMessageHandler): void;
+    onClose(handler: TransportCloseHandler): void;
+    onError(handler: TransportErrorHandler): void;
+    isConnected(): boolean;
+    private tryUpgradeToWebSocket;
+    private postMessage;
+    private startPolling;
+    /** The server-side session is gone: stop and report a close so the engine reconnects. */
+    private endSession;
+    private runPollLoop;
+    /** Accept, bearer credential and (once issued) the session id: sent on every request. */
+    private makeHeaders;
+}
+
+/**
+ * Configuration for the chaos transport.
+ */
+interface ChaosConfig {
+    /** Probability of dropping a message (0-1). Defaults to 0. */
+    dropRate?: number;
+    /** Probability of duplicating a message (0-1). Defaults to 0. */
+    duplicateRate?: number;
+    /** Probability of reordering messages (0-1). Defaults to 0. */
+    reorderRate?: number;
+    /** Maximum latency in ms for delayed messages. Defaults to 0. */
+    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.
+ * Used for testing sync convergence under unreliable network conditions.
+ *
+ * Supports message dropping, duplication, reordering, and latency injection.
+ * All random behavior is injectable for deterministic, reproducible tests.
+ */
+declare class ChaosTransport implements SyncTransport {
+    private readonly inner;
+    private readonly dropRate;
+    private readonly duplicateRate;
+    private readonly reorderRate;
+    private readonly maxLatency;
+    private readonly random;
+    private readonly dropPredicate;
+    private messageHandler;
+    private reorderBuffer;
+    private pending;
+    constructor(inner: SyncTransport, config?: ChaosConfig);
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    send(message: SyncMessage): void;
+    onMessage(handler: TransportMessageHandler): void;
+    onClose(handler: TransportCloseHandler): void;
+    onError(handler: TransportErrorHandler): void;
+    isConnected(): boolean;
+    private handleIncoming;
+    private deliverIncoming;
+    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;
+}
+
+/**
+ * A blob-chunk message in decoded form (chunk bytes as a `Uint8Array` rather
+ * than the base64 wire string). This is the shape callers of the channel work
+ * with; the channel handles base64 encode/decode at the wire boundary.
+ *
+ * The shape mirrors `@korajs/store`'s `ChunkMessage` so an app-layer adapter can
+ * bridge the two with no field translation.
+ */
+type BlobChunkChannelMessage = {
+    type: 'blob-chunk-request';
+    requestId: string;
+    hash: string;
+} | {
+    type: 'blob-chunk-response';
+    requestId: string;
+    bytes: Uint8Array | null;
+    /** The server refused the request for rate; retry after `retryAfterMs` (RT-24). */
+    throttled?: boolean;
+    retryAfterMs?: number;
+} | {
+    type: 'blob-chunk-push';
+    hash: string;
+    bytes: Uint8Array;
+};
+/** Encode chunk bytes to a base64 string for the JSON wire. */
+declare function encodeBlobChunkBytes(bytes: Uint8Array): string;
+/** Decode base64 chunk bytes from the wire back to a `Uint8Array`. */
+declare function decodeBlobChunkBytes(encoded: string): Uint8Array;
+interface BlobChunkChannelOptions {
+    /**
+     * Called when a local blob-chunk message should go out on the wire. The
+     * caller (the sync engine) decides whether the connection is ready to send.
+     */
+    onSend?: (message: BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage) => void;
+}
+/**
+ * Ephemeral side channel for out-of-band blob chunk transfer over the sync
+ * connection. Symmetric: a peer can both request chunks it needs and answer
+ * requests for chunks it holds. Never persisted in the operation log — durable
+ * state is the `BlobRef` inside a record's fields; this channel only moves the
+ * referenced bytes.
+ *
+ * The channel owns the base64 wire encoding so callers work purely in
+ * `Uint8Array`, and its {@link BlobChunkChannelMessage} shape mirrors
+ * `@korajs/store`'s `ChunkMessage` so the app layer can expose it as a
+ * `ChunkMessagePort` without translating fields.
+ */
+declare class BlobChunkChannel {
+    private readonly onSend;
+    private readonly handlers;
+    constructor(options?: BlobChunkChannelOptions);
+    /**
+     * Send a blob-chunk message to the peer. Response bytes are base64-encoded
+     * onto the wire here; callers pass a `Uint8Array`.
+     */
+    send(message: BlobChunkChannelMessage): void;
+    /**
+     * Register a handler for inbound blob-chunk messages. Multiple handlers are
+     * allowed; each receives every delivered message.
+     */
+    onMessage(handler: (message: BlobChunkChannelMessage) => void): () => void;
+    /**
+     * Deliver an inbound wire message to registered handlers, decoding response
+     * bytes from base64 back to a `Uint8Array` first.
+     */
+    deliver(message: BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage): void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * WebCrypto primitives of the key hierarchy (ENC-1, D4b, record format 2):
+ *
+ *   passphrase --PBKDF2-SHA256(salt, iterations)--> KEK (AES-256-GCM, non-extractable)
+ *   KEK --AES-GCM (AAD: keyring, ring)--> master key (32 random bytes)
+ *   recovery public key --ECDH P-256, HKDF-SHA256, AES-GCM--> master key (optional)
+ *   master key --HKDF-SHA256 "data-key-wrap"--> wrapping key (AES-256-GCM)
+ *   master key --HKDF-SHA256 "record-mac"--> MAC key (HMAC-SHA256)
+ *   wrapping key --AES-GCM wrap (AAD: keyring, version, keyId)--> data key v1, v2, ...
+ *   master key --HKDF-SHA256 "master-id"--> master id (names a master a passphrase change retires)
+ *   recovery anchor key (a data key created WITH the recovery key) --HMAC-SHA256 over
+ *     (keyring, ring id, key id, recovery public key)--> anchor (16 bytes, in the recovery key)
+ *
+ * Raw master-key bytes exist only inside the calls that create, re-wrap or open the
+ * master key, and are zeroed afterwards. What a device keeps is the two derived keys
+ * ({@link MasterKeys}), both non-extractable. Data keys are extractable only for the
+ * moment they are wrapped; the copy a device encrypts with is non-extractable.
+ */
+/** Thrown when a key record cannot be opened with the given passphrase or recovery key. */
+declare class KeyUnwrapError extends SyncError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/** The keys a device derives from (and keeps instead of) a ring's master key. */
+interface MasterKeys {
+    /** Wraps and unwraps the ring's data keys. */
+    wrapKey: CryptoKey;
+    /** Authenticates the whole key record. */
+    macKey: CryptoKey;
+    /**
+     * Public name of the master key (`m-` and 32 hex digits, an HKDF output of the master
+     * key): what a record's `retiredMasters` lists after a passphrase change. Reveals
+     * nothing about the key; only a holder of the master key can compute it.
+     */
+    id: string;
+}
+
+/**
+ * What a device keeps of an unlocked keyring: the last key record it authenticated and
+ * accepted (also the pin: its ring id and revision are the floor for every later
+ * record), the passphrase KEK when known, the keys derived from the ring's master key
+ * (to authenticate later records and wrap new data keys), and every data key it
+ * opened. Keys are NON-EXTRACTABLE CryptoKeys: script on the page can use them while it
+ * runs, but cannot read their bytes. A locked keyring keeps the record (the pin) and
+ * nothing else.
+ */
+interface CachedKeyring {
+    record: WrappedKeyRecord;
+    kek: CryptoKey | null;
+    /** Derived from the ring's master key; null while locked. */
+    master?: MasterKeys | null;
+    keys: Array<{
+        keyVersion: number;
+        keyId: string;
+        key: CryptoKey;
+    }>;
+    /**
+     * Ids of master keys a passphrase change retired, from every record this device
+     * authenticated (RT-107). Kept when locked: records authenticated only by one of them
+     * stay refused across restarts.
+     */
+    retiredMasters?: string[];
+    /**
+     * Ids of master keys this device held when the server served a NEWER revision of the
+     * same ring that they do not authenticate (a passphrase change this device could not
+     * read yet). Records authenticated only by one of them are not adopted automatically;
+     * an explicit `unlock(passphrase)` decides (RT-107).
+     */
+    supersededMasters?: string[];
+}
+/** Where a device keeps unlocked keyrings between app starts. */
+interface KeyCache {
+    /** Which kind of cache this is (for status and docs). */
+    readonly kind: 'indexeddb' | 'memory' | 'none';
+    load(id: string): Promise<CachedKeyring | null>;
+    save(id: string, entry: CachedKeyring): Promise<void>;
+    clear(id: string): Promise<void>;
+}
+/** Keeps unlocked keyrings for the lifetime of the process only. */
+declare class MemoryKeyCache implements KeyCache {
+    readonly kind: "memory";
+    private readonly entries;
+    load(id: string): Promise<CachedKeyring | null>;
+    save(id: string, entry: CachedKeyring): Promise<void>;
+    clear(id: string): Promise<void>;
+}
+/** Keeps nothing: the device asks for the passphrase on every start. */
+declare class NoKeyCache implements KeyCache {
+    readonly kind: "none";
+    load(): Promise<CachedKeyring | null>;
+    save(): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Keeps unlocked keyrings in IndexedDB (structured clone keeps a CryptoKey
+ * non-extractable). Survives reloads, so a device unlocks once and then works offline.
+ */
+declare class IndexedDbKeyCache implements KeyCache {
+    private readonly databaseName;
+    readonly kind: "indexeddb";
+    private db;
+    /** @param databaseName - IndexedDB database name (one per app database) */
+    constructor(databaseName: string);
+    load(id: string): Promise<CachedKeyring | null>;
+    save(id: string, entry: CachedKeyring): Promise<void>;
+    clear(id: string): Promise<void>;
+    private open;
+}
+/**
+ * The default cache: IndexedDB where it exists (browsers), memory otherwise (Node,
+ * tests). See the encryption guide for what each means for offline unlock.
+ *
+ * @param mode - 'auto' (default), 'indexeddb', 'memory' or 'none'
+ * @param databaseName - IndexedDB database name
+ */
+declare function createKeyCache(mode?: 'auto' | 'indexeddb' | 'memory' | 'none', databaseName?: string): KeyCache;
+
+/**
+ * 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>);
+}
+/**
+ * End-to-end encryption of operations, envelope v2 (protocol v2; ENC-3, NEW-ENC-1).
+ *
+ * **Envelope.** The plaintext `data`, `previousData` and `atomicOps` move into
+ * `op.encrypted` ({@link EncryptedOperationEnvelope}: alg, keyId, keyVersion and one
+ * AES-256-GCM ciphertext per member). On the wire `data` is null, or holds only the
+ * collection's documented cleartext scope fields (`cleartextFields`), so a schema-aware
+ * server stores the operation opaquely and can still evaluate scopes. Metadata (id,
+ * nodeId, collection, recordId, timestamp, sequence, causalDeps, schemaVersion) stays in
+ * cleartext so the server can route, deduplicate and order.
+ *
+ * **Binding (ENC-3).** Every ciphertext is authenticated with AES-GCM additional data
+ * canonical(nodeId, collection, recordId, type, timestamp, sequenceNumber, field,
+ * keyVersion, hashVersion): a ciphertext moved to another operation, record or member,
+ * or an envelope whose metadata was rewritten, fails authentication. `data` and
+ * `previousData` are always encrypted, even when null, so a delete is authenticated too.
+ * The operation id (the version-2 content hash of the PLAINTEXT) is verified after
+ * decryption by the sync engine (`verify-inbound.ts`).
+ *
+ * **Plaintext.** With encryption enabled an operation without an envelope is refused
+ * (a server must not be able to inject unauthenticated writes), unless the config opens
+ * a migration window (`allowPlaintextMigration`). Protocol-1 payloads (ciphertext inside
+ * `data`, no binding) are refused the same way.
+ *
+ * **Key id.** The envelope names its key material (`keyId`: the keyring's random key
+ * id, ENC-1), so a device holding different material reports a diagnosable
+ * `KEY_ID_MISMATCH` rather than a bare authentication failure.
+ *
+ * @example
+ * ```typescript
+ * const encryptor = SyncEncryptor.fromKeys([{ version: 1, key: dataKey, keyId }])
+ * const sealed = await encryptor.encryptOperation(operation)
+ * const opened = await encryptor.decryptOperation(sealed)
+ * ```
+ */
+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;
+    /** Fingerprint of each key version's material (cached). */
+    private readonly keyIds;
+    private readonly cleartextFields;
+    private readonly allowPlaintextMigration;
+    private constructor();
+    /**
+     * Creates a SyncEncryptor from a passphrase and an explicit, shared salt.
+     *
+     * Low-level: apps use the keyring (`createApp` with `sync.encryption`), which
+     * distributes random data keys wrapped by the passphrase. This derives the data key
+     * directly from the passphrase, so every device must pass the same salt; there is
+     * no random-salt default any more (ENC-1: a per-process random salt made every
+     * device derive a different key).
+     *
+     * @param config - Encryption configuration with the passphrase in `key`
+     * @param salt - The key-derivation salt, shared by every device (16 bytes or more)
+     * @param iterations - Optional PBKDF2 iteration count. Lower it only in tests.
+     * @returns A configured SyncEncryptor instance
+     * @throws {EncryptionError} If configuration is invalid or the salt is missing
+     * @throws {KeyDerivationError} If key derivation fails
+     */
+    static create(config: SyncEncryptionConfig, salt: Uint8Array, iterations?: number): 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.
+     * @param options - Cleartext scope fields and the plaintext migration window
+     * @returns A configured SyncEncryptor instance
+     * @throws {EncryptionError} If no keys are provided
+     */
+    static fromKeys(versionedKeys: VersionedKey[], options?: EncryptorOptions): 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;
+    /** The key registered under an explicit key id (keyring keys), if any. */
+    private keyById;
+    /**
+     * Get the current encryption key version number.
+     */
+    getCurrentKeyVersion(): number;
+    /**
+     * The key id written into envelopes for a key version: the keyring's random key id,
+     * or for a passphrase-derived key a fingerprint of its salt (never the key itself).
+     *
+     * @param version - Key version (defaults to the current one)
+     */
+    getKeyId(version?: number): Promise<string>;
+    /**
+     * Seal an operation into an envelope v2.
+     *
+     * Returns a new operation (operations are immutable): `encrypted` holds the
+     * ciphertexts, `data` is null or the collection's cleartext scope fields, and
+     * `previousData`/`atomicOps` are removed. An operation that already carries an
+     * envelope is returned unchanged.
+     *
+     * @param operation - The plaintext operation
+     * @returns The sealed operation
+     * @throws {EncryptionError} If encryption fails
+     */
+    encryptOperation(operation: Operation): Promise<Operation>;
+    /**
+     * Open an envelope v2 and restore the plaintext `data`, `previousData` and
+     * `atomicOps`. The returned operation has no `encrypted` member.
+     *
+     * @param operation - The sealed operation
+     * @returns The plaintext operation (its id is NOT verified here; the caller does)
+     * @throws {DecryptionError} On a plaintext operation (unless the migration window
+     *   is open), a protocol-1 payload, an unknown key, a key-id mismatch, or a
+     *   ciphertext that fails authentication (tampered, transplanted, wrong key)
+     */
+    decryptOperation(operation: Operation): Promise<Operation>;
+    /**
+     * Same as {@link encryptOperation} for the wire form.
+     *
+     * @param serialized - The serialized operation to encrypt
+     * @returns The sealed serialized operation
+     */
+    encryptSerializedOperation(serialized: SerializedOperation): Promise<SerializedOperation>;
+    /**
+     * Same as {@link decryptOperation} for the wire form.
+     *
+     * @param serialized - The serialized operation to decrypt
+     * @returns The plaintext serialized operation
+     */
+    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 an operation `data` field holds a protocol-1 encrypted payload (the
+     * pre-envelope format, refused since protocol v2).
+     *
+     * @param field - An operation's `data` or `previousData` field
+     */
+    static isEncryptedPayload(field: Record<string, unknown> | null): boolean;
+    /**
+     * Whether a plaintext operation touches only data the server can already read: its
+     * `data` (and, except for a delete, its `previousData`) names only the collection's
+     * cleartext scope fields, and it has no atomic ops. The sync engine accepts such an
+     * operation from a server-authored node (a cascade, a set-null of a cleartext
+     * reference, a constraint correction of a cleartext field) under end-to-end
+     * encryption: the server cannot seal it (it has no key), and it reveals or forges
+     * nothing the server does not already hold in cleartext. Any sealed field makes it
+     * false, so the operation is refused as plaintext.
+     *
+     * @param operation - A delivered operation without an envelope
+     */
+    isCleartextOnly(operation: Operation): boolean;
+    /** Whether an operation carries an envelope v2. */
+    static isEncryptedOperation(operation: {
+        encrypted?: unknown;
+    }): boolean;
+    private seal;
+    private open;
+    /** The collection's documented cleartext scope fields, or null when none. */
+    private cleartextScope;
+    private encryptMember;
+    private decryptMember;
+}
+/** Options of {@link SyncEncryptor.fromKeys}. */
+interface EncryptorOptions {
+    /** Per collection, the data fields kept in cleartext beside the envelope (for scopes). */
+    cleartextFields?: Readonly<Record<string, readonly string[]>>;
+    /** Accept plaintext (envelope-less) inbound operations during a migration window. */
+    allowPlaintextMigration?: boolean;
+}
+/**
+ * Check if a field value contains a protocol-1 encrypted payload (ciphertext inside
+ * `data`). Protocol v2 refuses such payloads; the envelope lives in `op.encrypted`.
+ *
+ * @param field - An operation's `data` or `previousData` field
+ * @returns true if the field contains a protocol-1 encrypted payload
+ */
+declare function isEncryptedPayload(field: Record<string, unknown> | null): boolean;
+
+/** Lock state of an encryption keyring. */
+type EncryptionLockState = 'locked' | 'unlocking' | 'unlocked' | 'error';
+/** Why a keyring is locked or in error (or, while unlocked, what needs attention). */
+type EncryptionStatusCode = 'NO_PASSPHRASE' | 'AWAITING_SERVER' | 'LOCKED_BY_APP' | 'WRONG_PASSPHRASE' | 'PASSPHRASE_REQUIRED' | 'KEY_RECORD_INVALID' | 'KEY_RECORD_ROLLBACK' | 'KEY_RECORD_MISSING' | 'KEY_RING_FORK' | 'KEY_SERVICE_FORBIDDEN' | 'KEY_SERVICE_UNSUPPORTED' | 'RECOVERY_FAILED';
+/** Status of an encryption keyring, as `app.encryption.getStatus()` reports it. */
+interface EncryptionStatus {
+    state: EncryptionLockState;
+    keyring: string;
+    /** Key version new operations are encrypted with, or null while locked. */
+    keyVersion: number | null;
+    /** Key id of that version, or null while locked. */
+    keyId: string | null;
+    /** Every key version this device can decrypt. */
+    availableVersions: number[];
+    /** Where unlocked keys are kept between starts. */
+    cache: KeyCache['kind'];
+    /**
+     * Set while locked or in error. While `unlocked`, `PASSPHRASE_REQUIRED` means the
+     * passphrase changed on another device: this device keeps working with the keys it
+     * holds, and needs the current passphrase for key management.
+     */
+    code?: EncryptionStatusCode;
+    message?: string;
+}
+/** The server's answer to a key-record fetch or write. */
+interface KeyServiceReply {
+    /** 'conflict': the write lost a compare-and-set; `record` is the current one. */
+    status: 'ok' | 'conflict';
+    record: WrappedKeyRecord | null;
+    /**
+     * With no record: key ids the server's stored operations of this owner are encrypted
+     * with (a sample). Non-empty means encrypted history exists, so the record was lost
+     * and a device that holds the ring must re-upload it; nobody may start a new ring.
+     */
+    knownKeyIds?: string[];
+}
+/** How a keyring reaches the server's key service (the sync connection). */
+interface KeyServiceChannel {
+    fetch(keyring: string): Promise<KeyServiceReply>;
+    put(keyring: string, record: WrappedKeyRecord, expectedRevision: number): Promise<KeyServiceReply>;
+}
+/** Options of {@link EncryptionKeyring}. */
+interface EncryptionKeyringOptions {
+    /** Keyring name (one per user by default). */
+    keyring?: string;
+    /** Passphrase source; without one the keyring starts locked until `unlock()`. */
+    passphrase?: string | (() => Promise<string>);
+    /** Where unlocked keys are kept. Defaults to memory (the app picks IndexedDB in browsers). */
+    cache?: KeyCache;
+    /**
+     * PBKDF2 iterations for new records, and the minimum accepted from the server
+     * (a server cannot downgrade the KDF). Defaults to 600,000. Lower only in tests.
+     */
+    kdfIterations?: number;
+    /** Encryptor options (cleartext scope fields, plaintext migration window). */
+    encryptor?: EncryptorOptions;
+}
+/** Thrown by keyring management calls. `context.code` names the reason. */
+declare class EncryptionKeyError extends SyncError {
+    constructor(message: string, context: Record<string, unknown> & {
+        code: string;
+    });
+    /** The reason code (`context.code`), e.g. WRONG_PASSPHRASE. */
+    get keyCode(): string;
+}
+/**
+ * A device's view of one encryption keyring (ENC-1, decision D4b; record format 2): the
+ * server-stored, passphrase-wrapped ring, opened and authenticated locally.
+ *
+ * - **Shared key material.** Every device of a user opens the same record, so every
+ *   device holds the same data keys and decrypts everything.
+ * - **Authenticated record.** The record carries an HMAC under a key derived from the
+ *   ring's master key; a device acts only on records it verified (RT-95). The server
+ *   can store, withhold or replay records, nothing more.
+ * - **Forward only.** A device pins the ring id and highest revision it accepted and
+ *   refuses a lower revision (`KEY_RECORD_ROLLBACK`, RT-96), keeping its keys and
+ *   re-uploading its newer record when connected.
+ * - **Writes re-read.** Every compare-and-set retry adopts the server's current record
+ *   first and wraps under that record's master key only (RT-97).
+ * - **Lost records.** A device holding the ring re-uploads it unchanged; a new device
+ *   that finds no record but encrypted history waits (`KEY_RECORD_MISSING`); two rings
+ *   that exist anyway are merged by the first device holding both (RT-104).
+ * - **Offline.** Once unlocked, keys are cached (non-extractable) and the keyring needs
+ *   no server; a cached record also lets `unlock()` work offline.
+ */
+declare class EncryptionKeyring {
+    readonly name: string;
+    private passphraseSource;
+    private readonly cache;
+    private readonly kdfIterations;
+    private readonly encryptorOptions;
+    private loadedPrincipal;
+    /** The last record this device authenticated and accepted: the pin. */
+    private record;
+    /** Keys derived from the pinned record's master key. */
+    private master;
+    private kek;
+    /** Salt (base64) the KEK was derived with. */
+    private kekSalt;
+    /** Held data keys by key id. Invariant: every held key id is in `record`. */
+    private readonly dataKeys;
+    /**
+     * Ids of master keys a passphrase change retired, from every record this device
+     * authenticated (persisted with the cache): a record authenticated only by one of
+     * them is refused (RT-107).
+     */
+    private readonly retiredMasters;
+    /**
+     * Ids of master keys this device held when the server served a newer revision of the
+     * same ring that they do not authenticate (most likely a passphrase change made
+     * elsewhere). A record authenticated only by one of them is not adopted without an
+     * explicit `unlock(passphrase)`: after a genuine change, no later genuine record is
+     * authenticated by the old master key (RT-107).
+     */
+    private readonly supersededMasters;
+    private encryptor;
+    private status;
+    private readonly listeners;
+    private lockedByApp;
+    private pendingPassphrase;
+    /** A recovery requested while offline, run at the next handshake. */
+    private pendingRecovery;
+    /** The configured passphrase that failed for a salt (not retried for that salt). */
+    private failedSource;
+    /** The current lock is a server-side condition a later session can clear (no user action). */
+    private retryable;
+    /** startNewKeyring() was called: a missing record with encrypted history may be replaced. */
+    private allowNewRing;
+    private failedUnlocks;
+    private nextUnlockAt;
+    private mutex;
+    constructor(options?: EncryptionKeyringOptions);
+    /** The encryptor of the unlocked keyring, or null while locked. */
+    getEncryptor(): SyncEncryptor | null;
+    /** Current status. */
+    getStatus(): EncryptionStatus;
+    /** Whether this device holds the data key with this key id. */
+    holdsKeyId(keyId: string): boolean;
+    /**
+     * Whether the current lock is a server-side condition (a rolled-back, missing,
+     * malformed or forked record) that a later sync session can clear without the user:
+     * sync should reconnect with backoff rather than wait for `unlock()`.
+     */
+    isRetryableLock(): boolean;
+    /** Subscribe to status changes. Returns an unsubscribe function. */
+    onStatusChange(listener: (status: EncryptionStatus) => void): () => void;
+    /**
+     * Whether sync may connect: the keyring is unlocked, or a passphrase is available to
+     * open (or create) the server record during the handshake.
+     */
+    canConnect(): boolean;
+    /**
+     * Load the cached keyring of a principal (the signed-in user, or null). A principal
+     * change drops everything held for the previous one first, so one user's keys never
+     * encrypt another user's operations.
+     */
+    load(principal: string | null): Promise<EncryptionStatus>;
+    /**
+     * Open the keyring against the server's record during a sync handshake: fetch it,
+     * create it on a user's first device, adopt a newer revision, re-upload a lost or
+     * rolled-back one, or merge a forked ring.
+     *
+     * @returns 'ready' when unlocked, 'locked' when a passphrase is needed (or wrong), or
+     *   when the server's record must change first ({@link isRetryableLock})
+     * @throws When the key service fails (the session is retried later)
+     */
+    synchronize(channel: KeyServiceChannel, principal: string | null): Promise<'ready' | 'locked'>;
+    /**
+     * Adopt a record the server pushed (another device rotated keys, changed the
+     * passphrase or set up recovery). Without a connection to write to, a rollback or a
+     * fork is reported and resolved at the next handshake.
+     *
+     * @returns 'ready' when still unlocked, 'locked' when the passphrase is needed or the
+     *   record was refused
+     */
+    adoptPushed(record: WrappedKeyRecord): Promise<'ready' | 'locked'>;
+    /**
+     * Unlock with a passphrase. With a cached record this works offline; otherwise the
+     * passphrase is kept until the next handshake opens (or creates) the server record,
+     * and the returned promise settles then (pass `channel` when connected).
+     *
+     * Repeated wrong passphrases are slowed down on the device (backoff after three).
+     * This is a usability guard, not a security boundary: whoever holds the record can
+     * try passphrases offline, so passphrase strength and PBKDF2 are the protection.
+     *
+     * @throws {EncryptionKeyError} WRONG_PASSPHRASE, UNLOCK_THROTTLED, KEY_RECORD_MISSING
+     */
+    unlock(passphrase: string, channel: KeyServiceChannel | null): Promise<EncryptionStatus>;
+    /**
+     * Lock: forget the data keys, the master keys and the KEK on this device (cache
+     * included). Sync stops until `unlock()`; local data stays readable (it is not
+     * encrypted at rest by this layer). The pinned record is kept (it is the rollback
+     * floor). The configured passphrase is not used again until `unlock()`.
+     */
+    lock(): Promise<EncryptionStatus>;
+    /**
+     * Rotate: create a new data key version. New operations use it; old versions stay
+     * in the record so history decrypts. Needs the server (compare-and-set). Each retry
+     * adopts the server's current record first and wraps under ITS master key only.
+     */
+    rotate(channel: KeyServiceChannel): Promise<EncryptionStatus>;
+    /**
+     * Change the passphrase: a NEW master key, sealed under a KEK derived from the new
+     * passphrase and a new salt, re-wraps every data key version (and the recovery wrap,
+     * if any). No operation is re-encrypted. The record lists the old master key as
+     * retired (`retiredMasters`): a device that authenticated this record (or a later
+     * one) refuses every record authenticated only by the old master key, however it is
+     * opened. Other devices keep working with their cached data keys (status
+     * `PASSPHRASE_REQUIRED` while unlocked); they need the new passphrase for a key they
+     * do not hold and for key management. A device that was served the new record but
+     * could not read it no longer adopts, without an explicit `unlock()`, a record that
+     * only its old master key authenticates.
+     *
+     * **A passphrase change alone does not contain a leaked passphrase.** The ring is a
+     * shared secret: a device that still holds only the OLD master key cannot tell a
+     * record the server forged under it (with a data key of the attacker's) from a
+     * genuine one, and the server decides which records it forwards. After a suspected
+     * leak: change the passphrase, `rotate()`, call `enableRecovery()` again (a recovery
+     * key made before the change can be steered to a ring the old passphrase built) and
+     * re-unlock EVERY other device with the new passphrase (`lock()`, then
+     * `unlock(newPassphrase)`, and update any configured `key`; never type the old
+     * passphrase again: an explicit unlock with it is the user's decision). A device that
+     * is not re-unlocked, or an old recovery key that is still used, remains exposed.
+     *
+     * @param newPassphrase - The new passphrase
+     * @param channel - The key service
+     * @param currentPassphrase - Optional: verified against the record first
+     */
+    changePassphrase(newPassphrase: string, channel: KeyServiceChannel, currentPassphrase?: string): Promise<EncryptionStatus>;
+    /**
+     * Set up (or replace) the recovery key: the ring's master key is also wrapped to a
+     * new recovery public key, and the private half is returned ONCE. Store it offline;
+     * it recovers the data after a lost passphrase. Without it, a lost passphrase means
+     * the encrypted data is unrecoverable. Needs the passphrase key of the CURRENT
+     * record (the recovery block is authenticated with the record, so only a holder of
+     * the master key can add or replace it).
+     *
+     * The same write adds a new data key version (a rotation) that anchors the recovery
+     * key to this ring: `recover()` accepts only a ring holding that key, which no older
+     * passphrase ever opened (RT-107). After a suspected passphrase leak, call this again
+     * once the passphrase was changed, and destroy the previous recovery key.
+     *
+     * @returns The recovery key (`kora-rk3-<key>.<anchor>`)
+     */
+    enableRecovery(channel: KeyServiceChannel): Promise<string>;
+    /**
+     * Recover after a lost passphrase: open the ring's master key with the recovery key,
+     * verify the whole record with it, and seal the master key under a new passphrase.
+     * Unlocks this device. Without a channel (sync not connected) the recovery runs at
+     * the next handshake. Devices that hold the ring keep working without a prompt (the
+     * master key is unchanged).
+     */
+    recover(recoveryKey: string, newPassphrase: string, channel: KeyServiceChannel | null): Promise<EncryptionStatus>;
+    /**
+     * Last resort after the server lost the key record and no device that holds the ring
+     * will come back (`KEY_RECORD_MISSING`): allow this device to create a new ring.
+     * Operations encrypted under the lost ring stay unreadable on this device. If a device
+     * holding the old ring reconnects later, it merges both rings and the history becomes
+     * readable again. Without a channel (sync is not connected: a missing record ends the
+     * session) the ring is created at the next handshake.
+     *
+     * @throws {EncryptionKeyError} KEY_RECORD_EXISTS when the server has a record (unlock it)
+     */
+    startNewKeyring(channel: KeyServiceChannel | null): Promise<EncryptionStatus>;
+    private recoverLocked;
+    private loadLocked;
+    /**
+     * No record on the server. A device that holds a ring re-uploads it unchanged (same
+     * revision and MAC, so every device's pin still accepts it). A device without one
+     * creates the first ring, unless the server reports encrypted history: then the
+     * record was lost, and it waits for a device that holds the ring.
+     */
+    private createOrRestoreLocked;
+    /** Create a brand-new ring (the user's first device). */
+    private createRingLocked;
+    /**
+     * Accept a server record, after authenticating it.
+     *
+     * - Lower revision of the pinned ring: refused (rollback); re-upload the pin.
+     * - Authenticated by the held master key, or by the passphrase (explicit, else the
+     *   configured one): forward when it keeps every key this device holds, else merge.
+     * - Not authenticated: nothing is adopted. A device that holds every key of a newer
+     *   revision of its ring keeps working (the passphrase changed elsewhere); otherwise
+     *   it needs the passphrase.
+     */
+    private adoptLocked;
+    /** An authenticated record: move forward to it, or merge it with the held ring. */
+    private acceptLocked;
+    /** A lower revision of the pinned ring: refuse it, keep the keys, re-upload the pin. */
+    private rollbackLocked;
+    /**
+     * A record authenticated only by a master key a passphrase change retired: whoever
+     * wrote it knew an OLD passphrase (or master key), not the current one (RT-107).
+     */
+    private refuseRetired;
+    /**
+     * A record authenticated only by a master key this device held when the server served
+     * a newer revision of the ring that the key does not authenticate (RT-107).
+     */
+    private refuseSuperseded;
+    /**
+     * Whether `master` was superseded on this device. An explicit `unlock(passphrase)` is
+     * the user's decision and clears the mark (a server that served a junk revision can
+     * delay, never lock out, a device).
+     */
+    private isSupersededMaster;
+    /** A record this device cannot authenticate: adopt nothing. */
+    private unverifiableLocked;
+    /**
+     * Merge the held ring into `base` (the server's current record, which survives: the
+     * server only accepts append-only successors of what it stores). Keys this device
+     * holds that `base` lacks are appended as new versions; operations keep naming them
+     * by key id. The result has a higher revision than both and is written with
+     * compare-and-set; a lost race adopts (or merges) the winner.
+     */
+    private mergeLocked;
+    /**
+     * Re-wrap the held data keys `base` lacks under `target` (appended after base's
+     * highest version). They are extracted from the pinned record with the held master.
+     */
+    private absorbHeldKeys;
+    /** Open every data key of `record` this device does not hold yet. */
+    private openDataKeys;
+    /**
+     * Whether `record` holds the anchor key of a recovery key: data keys are never removed
+     * or re-keyed (a passphrase change, recovery or merge re-wraps them under the same key
+     * id), so the anchor stays valid for the ring.
+     */
+    private holdsAnchor;
+    /**
+     * Whether `master` (which authenticated `record`) is a master key a passphrase change
+     * retired: listed in `record` itself or in any record this device authenticated.
+     */
+    private isRetiredMaster;
+    /** The next revision after `base`, above the pinned one when it is the same ring. */
+    private nextRevision;
+    /** Authenticate a record with the held master key (no passphrase needed). */
+    private authenticateHeld;
+    /**
+     * Open and authenticate a record with a passphrase.
+     *
+     * @throws {EncryptionKeyError} WRONG_PASSPHRASE, or KEY_RECORD_INVALID when the master
+     *   key opens but the record does not authenticate under it (tampered)
+     */
+    private openWithPassphrase;
+    /** The configured or pending passphrase, unless it already failed for this salt. */
+    private sourcePassphraseFor;
+    private followConflictLocked;
+    private commitLocked;
+    /** Persist the pinned record, the held keys and the master marks (RT-107). */
+    private saveCacheLocked;
+    private rebuildEncryptor;
+    private availablePassphrase;
+    private requireMaster;
+    /** The KEK of `record`'s own salt (never one derived for another record's salt). */
+    private requireKek;
+    private requireRecord;
+    private noteFailedUnlock;
+    private dropKeys;
+    /** A record refused for what the server sent: the held keys stay, nothing is adopted. */
+    private refuseRecord;
+    /** A server-side condition: keys kept, a later session (or a push) can clear it. */
+    private holdFor;
+    private lockWith;
+    /** Locks that need the user stop encrypting; records refused keep held keys. */
+    private dropKeysIfUnusable;
+    private statusError;
+    private cacheId;
+    private makeStatus;
+    private setStatus;
+    private exclusive;
+}
+
+/** 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.
+ */
+interface OutboundBatch {
+    /** Unique identifier for this batch */
+    batchId: string;
+    /** Operations in this batch, in causal order */
+    operations: Operation[];
+}
+/**
+ * Outbound operation queue with pluggable persistence.
+ * Manages operations waiting to be sent to the sync server.
+ *
+ * Operations are deduplicated by ID (content-addressed) and maintained
+ * in causal order via topological sort.
+ */
+declare class OutboundQueue {
+    private readonly storage;
+    private queue;
+    private readonly seen;
+    private readonly inFlight;
+    /**
+     * Ids of queued operations that were put on the wire at least once. Such an op may
+     * already be stored on the server (its ack can be lost), so a clock rebase must never
+     * re-stamp it (W3 step 4). Persisted through the storage when it supports it.
+     */
+    private readonly sent;
+    private nextBatchId;
+    private initialized;
+    constructor(storage: QueueStorage);
+    /**
+     * Load persisted operations from storage.
+     * Must be called before using the queue.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Add an operation to the outbound queue.
+     * Deduplicates by operation ID. Persists to storage.
+     */
+    enqueue(op: Operation): Promise<void>;
+    /**
+     * Add several operations at once: deduplicated by id, persisted, and causally
+     * re-sorted once (rather than once per operation).
+     */
+    enqueueMany(ops: Operation[]): Promise<void>;
+    /**
+     * Take a batch of operations from the front of the queue.
+     * Moves them to in-flight status. Returns null if queue is empty.
+     *
+     * @param batchSize - Maximum number of operations in the batch
+     * @param accept - Only operations it accepts are taken (in queue order); the others
+     *   stay queued. The engine passes "authored under this session's node id": a session
+     *   may only upload its own node's operations (RT-38, RT-40).
+     */
+    takeBatch(batchSize: number, accept?: (op: Operation) => boolean): OutboundBatch | null;
+    /** Whether any queued (not in-flight) operation satisfies `accept`. */
+    hasOperationsMatching(accept: (op: Operation) => boolean): boolean;
+    /** Number of queued (not in-flight) operations that satisfy `accept`. */
+    countMatching(accept: (op: Operation) => boolean): number;
+    /**
+     * 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<{
+        acknowledged: Operation[];
+        returned: Operation[];
+    }>;
+    /**
+     * Record that a taken batch was put on the wire. Its operations may now be stored on
+     * the server even if no ack ever arrives, so they are excluded from clock rebases.
+     */
+    markSent(batchId: string): Promise<void>;
+    /** Whether this queued operation was ever put on the wire. */
+    wasSent(opId: string): boolean;
+    /**
+     * Forget the sent flag of operations the server explicitly refused without storing
+     * (for example a batch refused with INVALID_TIMESTAMP), so a clock rebase may re-stamp
+     * them. In memory only: after a restart they are conservatively treated as sent.
+     */
+    clearSent(opIds: string[]): void;
+    /** Whether the queue owns this operation (queued or in flight). */
+    has(opId: string): boolean;
+    /** Every operation currently in flight, across batches. */
+    getInFlight(): Operation[];
+    /**
+     * Replace some queued (not in-flight) operations by rewritten ones, for example after
+     * a clock rebase re-stamped never-sent operations under new content-addressed ids.
+     * Operations not named in `oldIds` are untouched.
+     */
+    replace(oldIds: string[], newOps: Operation[]): Promise<void>;
+    /**
+     * Return a failed batch to the front of the queue for retry.
+     * Prepends the operations to maintain priority.
+     */
+    returnBatch(batchId: string): void;
+    /**
+     * Number of operations waiting in the queue (not counting in-flight).
+     */
+    get size(): number;
+    /**
+     * Total operations including in-flight.
+     */
+    get totalPending(): number;
+    /**
+     * Whether the queue has any operations to send.
+     */
+    get hasOperations(): boolean;
+    /**
+     * Peek at the first `count` operations without removing them.
+     */
+    peek(count: number): Operation[];
+    /**
+     * All queued operations (not counting in-flight), in causal order.
+     */
+    getAll(): Operation[];
+    /**
+     * Atomically replace the entire queue with a new set of operations.
+     *
+     * Used after a timestamp rebase rewrote the queued operations under new
+     * content-addressed ids: the old entries must vanish from memory AND from
+     * persistent storage in one step, or a page refresh could resurrect
+     * stale-stamped ops the server would reject. Resets the seen set to exactly
+     * the new ids so the rewritten ops are not treated as duplicates.
+     */
+    replaceAll(ops: Operation[]): Promise<void>;
+    /**
+     * 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 every pending/in-flight operation for a record so authorization loss cannot upload it. */
+    rejectRecord(collection: string, recordId: string): Promise<Operation[]>;
+    /**
+     * Remove operations by id from queue and persistent storage.
+     * Used when ops were already sent during handshake delta exchange.
+     */
+    removeByIds(ids: string[]): Promise<void>;
+}
+
+/**
+ * Options for creating a SyncEngine.
+ */
+interface SyncEngineOptions {
+    /** Transport implementation (WebSocket, memory, etc.) */
+    transport: SyncTransport;
+    /** Local store implementing SyncStore */
+    store: SyncStore;
+    /** Sync configuration */
+    config: SyncConfig;
+    /** Message serializer. Defaults to JSON. */
+    serializer?: MessageSerializer;
+    /** Event emitter for DevTools integration */
+    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
+     * before sending and decrypted after receiving. The server never sees plaintext data.
+     */
+    encryptor?: SyncEncryptor;
+    /**
+     * End-to-end encryption keyring (ENC-1): the server-stored, passphrase-wrapped data
+     * keys, opened during each handshake before any operation is exchanged. Takes the
+     * place of `encryptor`. While it is locked, sync does not connect.
+     */
+    keyring?: EncryptionKeyring;
+    /** How long a key-service request may take before the session is retried (ms). */
+    keyServiceTimeoutMs?: number;
+    /** 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;
+    deliveryWatermark: number;
+    deliveryGapRepeatCount: number;
+    timestamp: number;
+}
+/**
+ * Core sync orchestrator. Manages the sync lifecycle:
+ * disconnected → connecting → handshaking → syncing → streaming
+ *
+ * Coordinates handshake, delta exchange, and real-time streaming
+ * between a local store and a remote sync server.
+ */
+declare class SyncEngine {
+    private state;
+    /** Listeners registered through {@link onStateChange}. */
+    private readonly stateListeners;
+    private readonly transport;
+    private readonly store;
+    private readonly config;
+    private readonly serializer;
+    private readonly emitter;
+    private readonly outboundQueue;
+    private readonly rejectedStorage;
+    private readonly batchSize;
+    private readonly outboundAckTimeoutMs;
+    private readonly outboundRetryBaseDelayMs;
+    private readonly outboundRetryMaxDelayMs;
+    private readonly encryptor;
+    private readonly keyring;
+    private readonly keyServiceTimeoutMs;
+    /** Key-service requests awaiting their response, by request id. */
+    private readonly keyRequests;
+    /** Sync is paused because the encryption keyring is locked (ENC-1). */
+    private encryptionLocked;
+    /** A key-record refresh for an unknown key version is running. */
+    private keyRefreshInFlight;
+    private readonly awarenessManager;
+    private readonly richtextDocChannel;
+    private readonly blobChunkChannel;
+    private readonly metricsCollector;
+    private readonly syncState;
+    private remoteVector;
+    /** Runs before each outbound operation batch is sent (see setOutboundPreparer). */
+    private outboundPreparer;
+    /**
+     * Per-device node token the server issued at this node id's first anonymous claim
+     * (RT-12). Presented in every handshake; persisted next to the node id when the
+     * sync-state persistence supports it, otherwise kept for this engine's lifetime.
+     */
+    private nodeToken;
+    /**
+     * Node ids the server named authoritative in its last accepted handshake response
+     * (protocol v2). Null until a protocol-2 server answered in this engine's lifetime;
+     * loaded from persistence on start. See {@link SyncEngine.getAuthoritativeNodeIds}.
+     */
+    private authoritativeNodeIds;
+    /** Protocol version of the server in the current session (1 for a beta.12-era server). */
+    private serverProtocolVersion;
+    /** Whether any server answered a handshake (serverProtocolVersion is then real). */
+    private serverProtocolKnown;
+    private lastAckedServerVector;
+    private cachedUnsyncedCount;
+    private lastSyncedAt;
+    private lastSuccessfulPush;
+    private lastSuccessfulPull;
+    private conflictCount;
+    /**
+     * Every outbound batch taken from the queue and not yet resolved, keyed by queue batch
+     * id: handshake-delta and streaming batches alike. An ack resolves only the batch it
+     * names (SYNC-4); a close returns all of them to the queue.
+     */
+    private readonly inFlightUploads;
+    /** Wire message id -> queue batch id, for ack and rejection correlation. */
+    private readonly uploadByMessageId;
+    /** Incremented on every connect and every disconnect; stale async sends check it. */
+    private sessionEpoch;
+    /** Set by destroy(): the engine never connects or arms a timer again. */
+    private destroyed;
+    private readonly statusListeners;
+    /**
+     * Contiguous acknowledged prefix of this device's own operations (W3 step 2): every
+     * own op with sequence <= this is stored on the server, terminally rejected and
+     * recorded, or not upload-eligible. Never advanced by a server-advertised vector.
+     */
+    private ownAckedThrough;
+    /** Node id the prefix belongs to (a rotation starts a new prefix at 0). */
+    private ownTrackingNodeId;
+    /** Highest own sequence read from the op log this session (above the prefix). */
+    private ownScannedThrough;
+    /**
+     * Own sequences above the prefix that this session knows about, mapped to the ids of
+     * their operations that are still unresolved. An empty set marks a sequence resolved.
+     */
+    private readonly ownUnresolved;
+    /** Ids resolved at sequences the log scan has not reached yet (skip on scan). */
+    private readonly ownResolvedAhead;
+    private ownTrackingChain;
+    /** Inbound quarantine kept in memory when the engine has no sync-state persistence. */
+    private readonly memoryQuarantine;
+    private outboundRetryAttempt;
+    private outboundRetryTimer;
+    /** {@link pushOperation} calls not yet enqueued; the streaming flush waits for 0. */
+    private pendingPushes;
+    private reconnecting;
+    private schemaBlocked;
+    private clockBlocked;
+    private clockSkewMs;
+    private blobStorageEnabled;
+    private blobPossessionProof;
+    private suspensionReason;
+    private authRejected;
+    /**
+     * Set when the server ended the session with AUTH_EXPIRED or AUTH_REVOKED. The
+     * next connect asks the auth callback for a refreshed token (never the cached
+     * one the server just refused) and is cleared by an accepted handshake.
+     */
+    private credentialRefreshRequired;
+    private serverFrontier;
+    private hasInFlightDeliveryBatch;
+    private blockedFailure;
+    private outboundAckTimer;
+    private startPromise;
+    private stopPromise;
+    private reconnectPromise;
+    /** A node-id rotation started by NODE_ID_CLAIMED; the next connect waits for it (RT-21). */
+    private nodeRotation;
+    /**
+     * Node id of the current (or last) session. Usually the store's node id; while the
+     * engine adopts the unsynced writes of a node no live tab uses (RT-40) it is that
+     * node. A session uploads only operations authored under its node id.
+     */
+    private sessionNodeId;
+    /** Node id the in-memory node token belongs to. */
+    private nodeTokenNodeId;
+    /** Releases the lock held on an adopted node (RT-40); null when not adopting. */
+    private releaseAdoption;
+    /**
+     * Ids of operations the server refused for good (RT-36). Cache of the durable markers,
+     * and the only record when the persistence layer has none (engine lifetime).
+     */
+    private readonly terminalRejected;
+    /** Nodes accepted at a handshake, when the persistence layer keeps no registry. */
+    private readonly memoryAcceptedNodes;
+    /** Every node id this database authored operations under (loaded at start). */
+    private localNodeIds;
+    /** Local nodes whose unsynced writes are held for another principal (RT-38). */
+    private heldNodeIds;
+    /** Unsynced, unqueued operations of other uploadable local nodes (RT-40), counted pending. */
+    private otherNodesPending;
+    /** Unsynced, unqueued operations of held nodes (RT-38), reported separately. */
+    private heldPending;
+    /** Held local nodes as of the last session start (RT-50), for status.heldNodes. */
+    private heldNodeInfos;
+    /**
+     * The server holds operations of this node that the device lost (RT-35): the delivery
+     * watermark was reset so the next session resyncs from 0, which fetches them back.
+     * The session ends once its in-flight uploads are resolved.
+     */
+    private ownRecoveryPending;
+    /**
+     * The signed-in user as resolved for the current session (RT-42): a user id, null
+     * (nobody signed in) or undefined (the app does not tell the engine).
+     */
+    private principal;
+    /**
+     * The user whose credential the current session's handshake carried (RT-50, RT-52):
+     * re-read after the credential fetch, so an accepted handshake binds a node to the
+     * user the server accepted it for, never to a user who signed out meanwhile.
+     */
+    private sessionPrincipal;
+    /** Serializes store bindings to the signed-in user (RT-52). */
+    private principalChain;
+    /** Adoption schedule kept in memory when the persistence layer has none (RT-46). */
+    private memorySchedule;
+    /** The schedule had parked adoptions when last read or written (RT-46). */
+    private scheduleHasParked;
+    /**
+     * Local nodes with unsynced writes this session did not adopt (RT-46): parked (no
+     * progress last time) or waiting for another local node's unsynced parent.
+     */
+    private deferredAdoptions;
+    /** Operations acknowledged in this session (RT-46: a yield needs progress). */
+    private sessionAcked;
+    /** An upload of the adopted node came back unprocessed in this session (RT-46). */
+    private adoptionStalled;
+    /**
+     * The session node's entry in this session's handshake vector (RT-44). The server held
+     * nothing of the node above it then; a SEQUENCE_CONFLICT above it was caused by an
+     * operation stored during this session by another live copy of this database.
+     */
+    private handshakeOwnEntry;
+    /** When this engine last reset delivery for a SEQUENCE_CONFLICT recovery (RT-44). */
+    private lastFullResyncAt;
+    /** A recovery full resync was rate-limited; the next session start after the interval runs it. */
+    private fullResyncDeferred;
+    /** Consecutive failed durability barriers before an upload (RT-49). */
+    private durabilityFailures;
+    /** Uploads proceed without local durability: the barrier failed persistently (RT-49). */
+    private durabilityDegraded;
+    private deltaBatchesReceived;
+    private deltaReceiveComplete;
+    private deltaSendComplete;
+    /** 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;
+    /** Server-authoritative upload authorization, separate from the downloaded view. */
+    private activeUplinkScope;
+    /**
+     * The downlink scope the server accepted at the last handshake that named one
+     * (SYNC-11), persisted. The next handshake reports its key and that view's watermark
+     * so the server can resume the stream of an unchanged grant. Never sent as the
+     * requested scope: a later-widened grant must not be narrowed to it.
+     */
+    private lastAcceptedScope;
+    /** Live query subsets registered from reactive subscriptions */
+    private querySubsets;
+    private staticQuerySubsets;
+    private querySubsetReconnectTimer;
+    /**
+     * Fires when the earliest parked adoption's backoff runs out (RT-53): an idle session of
+     * this tab's own node then hands over to it, so a closed tab's deferred writes are
+     * retried even if this tab never writes or reconnects.
+     */
+    private adoptionRetryTimer;
+    /** 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;
+    /** Schema transforms: the engine checks views, the store folds them (RT-84). */
+    private readonly operationTransforms;
+    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;
+    /**
+     * Stop for good (`app.close()`): disconnect, clear every timer and listener, and refuse
+     * any later start. Unlike stop(), nothing the engine scheduled can run afterwards.
+     */
+    destroy(): Promise<void>;
+    /** Clear every timer the engine owns. */
+    private clearAllTimers;
+    private clearAdoptionRetryTimer;
+    /** Close the transport, logging nothing: it may already be closed. */
+    private closeTransportQuietly;
+    /**
+     * The engine gave up on this session (a message it could not process, a transport
+     * error, a server error): move to disconnected and close the transport (SYNC-5). The
+     * close starts synchronously in this same frame, so the socket is released before
+     * auto-reconnect (which is asynchronous) can open another one.
+     */
+    private abandonSession;
+    /**
+     * Subscribe to status changes that no event announces (an upload ack lowering the
+     * pending count, reaching streaming). Status bridges refresh on it, so a waiter such
+     * as `waitForSettled` sees the change immediately (RT-28).
+     */
+    onStatusChange(listener: () => void): () => void;
+    private notifyStatusChange;
+    private ensureDisconnected;
+    /**
+     * Push a local operation to the outbound queue.
+     * If streaming, flushes immediately.
+     *
+     * Uploads are judged against the UPLINK scope only. Query subsets narrow what
+     * this client downloads, never what it uploads: an edit that moves a record out
+     * of a reactive query's view must still reach the server (SYNC-1).
+     *
+     * Operations on collections that do not sync at all stay local-only by design.
+     * An operation on a synced collection that falls outside the uplink scope would
+     * be refused by the server, so it is recorded in the rejected store and
+     * surfaced as `sync:operation-rejected` (code `OUT_OF_UPLINK_SCOPE`) rather than
+     * kept as a silent local fork.
+     */
+    pushOperation(op: Operation): Promise<void>;
+    /**
+     * Mark the engine as being in a reconnection loop. When reconnecting,
+     * `getStatus()` returns 'offline' instead of 'syncing' for intermediate
+     * states (connecting, handshaking, syncing), since the user is effectively
+     * disconnected until reconnection succeeds.
+     */
+    setReconnecting(value: boolean): void;
+    /**
+     * Get the current developer-facing sync status.
+     */
+    /**
+     * Node ids the sync server named authoritative (protocol v2): operations from these
+     * nodes are server-authored and are the only ones that may carry `fieldVersions` or
+     * `foldState`. Null until a protocol-2 server answered (or one answered in an earlier
+     * session and the list was persisted).
+     */
+    getAuthoritativeNodeIds(): readonly string[] | null;
+    /** Protocol version of the server in the current (or last) session; 1 before any. */
+    getServerProtocolVersion(): number;
+    getStatus(): SyncStatusInfo;
+    /**
+     * Sync is paused on a locked keyring (ENC-1): no session runs until the app unlocks
+     * it. Reported as a suspension (`phase: 'suspended'`, `reason: 'encryption-locked'`,
+     * `status: 'encryption-locked'`) rather than as plain offline, so the UI can ask for
+     * the passphrase and `waitForSettled` reports why it cannot settle.
+     */
+    private isLockedSuspension;
+    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.
+     */
+    isSchemaBlocked(): boolean;
+    /**
+     * True when sync is blocked because this device's clock is too far ahead.
+     * Local writes continue to work and queue; only sync is paused.
+     */
+    isClockBlocked(): boolean;
+    /**
+     * True when sync is paused because the end-to-end encryption keyring is locked (no
+     * passphrase, a wrong one, or a key record that must not be used). Local writes go
+     * on and queue; `retryNow()` after an unlock resumes sync.
+     */
+    isEncryptionLocked(): boolean;
+    /**
+     * The key service over the live sync session, for keyring management (rotation,
+     * passphrase change, recovery). Null while not connected: those calls need the
+     * server.
+     */
+    getKeyServiceChannel(): KeyServiceChannel | null;
+    /** serverTime - localTime measured at the last handshake, or null before first connect. */
+    getClockSkewMs(): number | null;
+    /**
+     * Clears the clock block after the user corrects the device clock.
+     * Moves the engine back to `disconnected` so `start()` can run again.
+     */
+    clearClockBlock(): void;
+    /**
+     * 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 this device's own operations not yet stored on the server (or terminally
+     * rejected and recorded): queued, in flight, or above the acknowledged prefix.
+     */
+    getUnsyncedOperationCount(): Promise<number>;
+    /**
+     * Surface an inbound apply failure. `blocking` marks the stream as stalled on this op
+     * (the watermark does not pass it); `quarantined` means the op is durably recorded and
+     * the stream moves on, so it never marks the stream blocked, whatever `retriable` says
+     * (retriable there means the quarantine replays it later).
+     */
+    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>;
+    /** Wake a permanent auth suspension after the binding reports a new auth state. */
+    notifyAuthChanged(): void;
+    /**
+     * The signed-in user may have changed (RT-42): end the live session (it belongs to the
+     * previous user), then bind the store to the user `config.principal` reports, so the
+     * next local write is authored under that user's own node. Call it before the next
+     * write after an auth change; `createApp` does so for `sync.authClient`. The next
+     * `start()` connects as that user's node.
+     */
+    refreshPrincipal(): Promise<void>;
+    /**
+     * Bind the store to the user the app reports NOW (RT-52), without ending or waiting
+     * for any session: call it on every auth event, before queueing the reconnect that
+     * follows. Writes made from then on are authored under that user's node, even while
+     * an earlier reconnect is still fetching a credential or connecting; that attempt
+     * notices the change before its handshake and starts over. A live session keeps
+     * running as the previous user's node and uploads only that node's writes, until the
+     * queued reconnect replaces it.
+     */
+    bindSignedInUser(): Promise<void>;
+    /** The signed-in user as `config.principal` reports it (undefined when it throws). */
+    private resolvePrincipal;
+    /** Run `fn` after every earlier principal binding (one store binding at a time). */
+    private withPrincipalLock;
+    /**
+     * Resolve the signed-in user and bind the store's node to them (RT-42).
+     *
+     * @returns false when sync must stay suspended: the store's node id is pinned and
+     *   belongs to another user, so nothing on this database may upload as this user.
+     */
+    private applyPrincipal;
+    /**
+     * 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.
+     */
+    exportDiagnostics(): SyncDiagnostics;
+    /**
+     * Get the current internal state (for testing).
+     */
+    getState(): SyncState;
+    /**
+     * Subscribe to internal state changes (SYNC-8). The reconnection loop uses it to
+     * count an attempt as successful only once the session reaches `streaming`, not
+     * when the handshake is merely sent.
+     *
+     * @param listener - Called with the new state after every transition
+     * @returns Unsubscribe function
+     */
+    onStateChange(listener: (state: SyncState) => void): () => void;
+    /**
+     * Get the outbound queue (for testing).
+     */
+    getOutboundQueue(): OutboundQueue;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** The view signature {@link deliverySignature} gives under `scope` and today's subsets. */
+    private deliverySignatureFor;
+    /**
+     * Handshake fields naming the accepted view this client last streamed under (SYNC-11):
+     * its canonical scope key and its delivery watermark. Omitted when no scope was ever
+     * accepted, or when it equals the requested scope (the requested watermark covers it).
+     */
+    private acceptedViewHandshakeFields;
+    /** Persist the downlink scope the server accepted at this handshake (null: none). */
+    private rememberAcceptedScope;
+    /**
+     * 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.
+     */
+    getActiveScope(): SyncScopeMap | undefined;
+    /** Get the server-accepted upload authorization scope. */
+    getActiveUplinkScope(): 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;
+    private switchDeliveryViewWithInheritance;
+    /** Atomically replace the manifest used by static query-subset mode. */
+    setQuerySubsets(subsets: 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;
+    /**
+     * Side channel for out-of-band blob chunk transfer over the sync connection.
+     * The app layer bridges this to a `ChunkMessagePort` to pull/serve blob bytes.
+     */
+    getBlobChunkChannel(): BlobChunkChannel;
+    /**
+     * Whether the connected server persists blob bytes centrally (learned from the
+     * handshake response). When true, the app uploads the bytes behind `blob`
+     * fields so they stay available after the authoring device goes offline.
+     */
+    isBlobStorageEnabled(): boolean;
+    /**
+     * Whether the connected server (peer-relay mode, no central storage) asks for the
+     * bytes behind blob references as proof of possession (RT-23). The server verifies
+     * and drops them; the app uploads exactly as for central storage.
+     */
+    isBlobPossessionProofRequested(): boolean;
+    /**
+     * Upload a blob chunk (or manifest) to the server, for central persistence or as
+     * proof of possession. A no-op unless the handshake was accepted (syncing or
+     * streaming) and the server advertised blob storage or asked for proofs.
+     */
+    uploadBlobChunk(hash: string, bytes: Uint8Array): void;
+    /**
+     * Register work that must reach the server before each outbound operation batch,
+     * on the same connection (messages are processed in order). Used to upload the
+     * bytes behind blob references first: the server only accepts a reference to
+     * content the writer can read or has uploaded (RT-11). Errors are ignored; the
+     * batch is sent regardless.
+     *
+     * @param preparer - Called with the operations about to be sent; null to remove
+     * @returns A function that removes this preparer
+     */
+    setOutboundPreparer(preparer: ((operations: Operation[]) => Promise<void>) | null): () => void;
+    private messageChain;
+    private enqueueMessage;
+    private handleMessageAsync;
+    /** Adopt a key record the server pushed; stop the session if it locks the keyring. */
+    private handlePushedKeyRecord;
+    /**
+     * An operation sealed under a key version newer than any this device holds: another
+     * device rotated keys and the server's push did not reach this session (another
+     * server instance). Fetch the record once, then replay the quarantine in the chain.
+     */
+    private maybeRefreshKeyring;
+    /**
+     * End the session because the keyring is locked; no reconnect until unlocked. A lock
+     * caused by the server's record (rolled back, lost, malformed, forked: RT-96, RT-104)
+     * needs no user action, so the session ends without pausing and the reconnection
+     * loop retries with backoff; the next handshake re-uploads, merges or opens it.
+     */
+    private pauseForLockedKeyring;
+    /** One key-service round trip over the live session. */
+    private keyServiceRequest;
+    /** Fail every pending key-service request (the session ended). */
+    private rejectKeyRequests;
+    private handleMessageFailure;
+    /**
+     * Compares server wall-clock time from the handshake with local time.
+     * Negative skew = this device's clock is fast (dangerous for LWW and rejected
+     * by server ingest beyond 60s). Positive skew = slow (accepted but surfaced).
+     * Zero developer work required: the result flows into sync status and events.
+     */
+    private evaluateClockSkew;
+    private handleHandshakeResponse;
+    /**
+     * The server refused this session's node id (`NODE_ID_CLAIMED`). What happens to the
+     * node's unsynced writes depends on whether this database was ever accepted as it:
+     *
+     * - Never accepted (RT-21: the claim's token was lost before the device saw it, or
+     *   another device took the id first): no principal ever received these writes under
+     *   this node, so the never-sent ones are re-authored under a fresh node id and
+     *   uploaded. An operation flagged sent is never re-authored (RT-38): it may already
+     *   be stored, and a copy under a new id would store the change twice.
+     * - Accepted before (RT-38: another user signed in on a database shared between
+     *   users): the node belongs to the principal that used it, so its unsynced writes
+     *   are held for that principal, never re-authored or uploaded under another one. The
+     *   device moves to a node the signed-in principal may own (a held node not yet tried
+     *   in this refusal cycle, typically that user's own earlier node) or to a fresh one.
+     * - An adopted node (RT-40) is held; the store's own node is left as it is.
+     */
+    private rotateNodeIdentity;
+    /**
+     * The server refused an adopted node that belongs to the signed-in user (the app
+     * assigned its held writes, or it was created for them) but that no claims-aware
+     * server ever accepted: typically a beta.12 node whose history the server recorded no
+     * owner for, and whose id is not this device's verified id, so no handover applies.
+     * Holding it would hold the user's own writes forever. Like the store's own node
+     * (RT-21), its never-sent writes are re-authored under a fresh node of the user's,
+     * which a later session adopts and uploads; what a beta.12 server acknowledged under
+     * the node is not re-authored (it is stored there already).
+     *
+     * @returns Whether the node's writes were re-authored (false: the caller holds it)
+     */
+    private reauthorRefusedAdoption;
+    /** RT-38: hold a refused, previously accepted node's writes and move to another node. */
+    private holdNodeAndSwitch;
+    /** RT-21: re-author a never-accepted node's never-sent writes under a fresh node. */
+    private reauthorUnsentAndRotate;
+    /**
+     * Move `nodeId`'s never-sent unsynced operations to a fresh node id (re-authored, so
+     * they upload under it) and start using it. An operation flagged sent stays: it may
+     * already be stored under `nodeId` (RT-38).
+     *
+     * @returns How many unsynced operations stayed under `nodeId` (sent, unacknowledged)
+     */
+    private rotateUnsent;
+    /** A fresh node id belongs to the signed-in user, when the app says who that is (RT-42). */
+    private bindFreshNode;
+    /** The store moved to another node id: the next session starts from it. */
+    private afterIdentityChange;
+    /** Whether a handshake as `nodeId` was ever accepted on this database. */
+    private wasNodeAccepted;
+    /**
+     * Re-stamps queued (never-acknowledged) operations whose timestamps are far
+     * enough in the future that the server would reject them, using the server's
+     * own handshake time as the trusted "now". This is the automatic recovery
+     * path after a user corrects a fast device clock: the queue drains
+     * immediately instead of waiting for real time to catch up.
+     */
+    private maybeRebaseQueuedOperations;
+    /**
+     * Upload this device's unsynced operations as the handshake delta. The delta is the
+     * outbound queue itself (rebuilt from the op log above the acknowledged prefix), sent
+     * as tracked batches: nothing leaves the queue until the server acknowledges the batch
+     * that carried it (SYNC-4).
+     */
+    private sendDelta;
+    private markDeltaSendCompleteIfReady;
+    /** Take the next batch from the queue and track it until it is resolved. */
+    private takeUpload;
+    /** Whether a taken batch still belongs to the live session (SYNC-10). */
+    private isUploadCurrent;
+    /** Return one taken batch to the queue and forget its tracking. */
+    private returnUpload;
+    /** Return every taken batch to the queue (the session ended; nothing was resolved). */
+    private returnAllInFlightUploads;
+    /**
+     * The oldest batch taken from the queue and not yet resolved (diagnostics and
+     * tests); null when nothing is in flight.
+     */
+    private get currentBatch();
+    private inFlightUploadCount;
+    /**
+     * Prepare, encrypt and send one taken batch, then register its message id so the ack
+     * that names it resolves exactly this batch. Every await is followed by a check that
+     * the batch still belongs to the live session; a send that throws returns the batch
+     * to the queue instead of rejecting unhandled (SYNC-10).
+     *
+     * @returns The wire message id, or null when the batch was not sent.
+     */
+    private sendUpload;
+    /**
+     * The durability barrier before an upload (RT-35), with a bounded number of failures
+     * (RT-49). Throws while the failures may be transient; after
+     * {@link DURABILITY_FAILURES_BEFORE_DEGRADED} consecutive failures it returns anyway
+     * (degraded mode, `localDurability: 'degraded'`, `sync:durability-degraded`) so the
+     * server keeps a durable copy. The barrier is still attempted every time: the first
+     * success leaves degraded mode (`sync:durability-restored`).
+     */
+    private awaitUploadDurability;
+    private handleOperationBatch;
+    /**
+     * Initial-sync bookkeeping for a received batch: progress, the legacy resume cursor,
+     * and completion on the final batch. Runs for duplicate batches too (NEW-SYNC-1).
+     */
+    private recordReceivedBatch;
+    /**
+     * Apply one delivered operation. Outcomes:
+     * - `applied`: applied, a duplicate, or a merge-decided skip (the record is settled);
+     * - `quarantine`: deliberately not applied and to be recorded durably (unknown
+     *   collection, transform unavailable, rejected or deferred apply, far-future
+     *   timestamp, undecryptable payload, referential failure), with `sync:apply-failed`;
+     * - `stall`: a retriable failure; the watermark must not pass it (or the engine
+     *   cannot record a quarantine durably), so the server re-sends it.
+     */
+    private applyInbound;
+    /**
+     * The delivery stream caught up: let the store retire provisional cascades of
+     * remote deletes (RT-69) and settle row-snapshot records after a full resync
+     * (RT-68). A failure is reported, never fatal: both are retried on the next
+     * catch-up.
+     */
+    private settleAfterCatchUp;
+    /**
+     * Whether a not-applied operation can be recorded so the watermark may pass it: with
+     * a durable quarantine, or when nothing is durable (no persisted watermark either, so
+     * a restart re-delivers everything anyway).
+     */
+    private canQuarantine;
+    /**
+     * Record quarantined operations and (for a delivery batch) the watermark advance in
+     * one durable step.
+     */
+    private commitDeliveryProgress;
+    /** Every inbound operation held in quarantine (durable when persistence supports it). */
+    getQuarantinedOperations(): Promise<QuarantinedOperation[]>;
+    /**
+     * Try to apply every quarantined operation again, oldest delivery first and in HLC
+     * order within a delivery. Runs on start (after a schema upgrade the unknown
+     * collection now exists; after time catches up a far-future op is acceptable) and on
+     * demand. Applied operations leave the quarantine; the rest stay.
+     *
+     * @returns How many operations left the quarantine.
+     */
+    retryQuarantinedOperations(): Promise<number>;
+    private replayQuarantine;
+    /**
+     * Under end-to-end encryption, a plaintext operation authored by the server (a node
+     * the handshake named authoritative: cascades, set-nulls, constraint corrections,
+     * route writes) that touches only the collection's cleartext fields is accepted
+     * without an envelope: the server holds no key, so it cannot seal its own writes, and
+     * such an operation carries nothing the server cannot already read. Any sealed field
+     * (or an operation from any other node) still has to arrive sealed.
+     */
+    private isServerAuthoredCleartext;
+    /** Whether end-to-end encryption is configured (a keyring or a fixed encryptor). */
+    private encryptionConfigured;
+    /** The encryptor in force: the unlocked keyring's, or the fixed one; null when locked. */
+    private activeEncryptor;
+    /**
+     * The encryptor in force. With encryption configured and the keyring locked this
+     * throws: an operation is never sent or applied unencrypted because a key is missing.
+     */
+    private requireEncryptor;
+    /** The key service over this session (the handshake has been accepted). */
+    private liveKeyServiceChannel;
+    /** Re-apply a quarantined operation; true when it no longer needs to be kept. */
+    private applyInboundQuietly;
+    /** Acknowledge a delivery batch (used for duplicates) without re-applying it. */
+    private sendDeliveryAck;
+    /**
+     * An acknowledgment resolves exactly the upload batch it names (SYNC-4): operations
+     * the server processed (sequence <= `lastSequenceNumber`) leave the queue and count
+     * toward the acknowledged prefix; the rest return to the queue for retry. An ack that
+     * names no tracked batch (a node-token confirmation echo, a batch from an older
+     * session) resolves nothing.
+     */
+    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 applyScopeRetraction;
+    /**
+     * The local nodes whose unsynced writes are held now (RT-38, RT-50), for the user the
+     * app reports as signed in. See {@link SyncStatusInfo.heldNodes}.
+     */
+    getHeldNodes(): Promise<HeldNodeInfo[]>;
+    /**
+     * Assign the `unassigned` held writes of `nodeId` to the signed-in user (RT-50): writes
+     * made on this device before the app knew who was signed in, on a node that never
+     * synced. Only the app can know whose they are (for example, a single-user device).
+     * They upload on the user's next session (the server then binds the node to them).
+     *
+     * @throws {SyncError} `HELD_ASSIGN_NO_USER` when nobody is signed in;
+     *   `HELD_NODE_NOT_ASSIGNABLE` when `nodeId` is not an unassigned held node (it belongs
+     *   to a user, or the server refused it for this one)
+     */
+    assignHeld(nodeId: string): Promise<void>;
+    /**
+     * Discard the `unassigned` held writes of `nodeId` from sync (RT-50): they are never
+     * uploaded. They are NOT rolled back: they stay in this device's local database, and
+     * count as synced from now on (`deleteDatabase` no longer protects them). Writes held
+     * for another user (`other-user`) cannot be discarded by this user.
+     *
+     * @returns How many writes were discarded
+     * @throws {SyncError} `HELD_NODE_NOT_DISCARDABLE` when `nodeId` is not an unassigned
+     *   held node
+     */
+    discardHeld(nodeId: string): Promise<number>;
+    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;
+    /**
+     * In a session of this tab's own node, arm a timer for the earliest parked adoption's
+     * backoff expiry (RT-53). Without it a parked node is retried only at a session start
+     * or after this tab's own uploads made progress, so an idle tab (a dashboard, a kiosk)
+     * would never retry a closed tab's deferred writes while its connection holds.
+     */
+    private armAdoptionRetryTimer;
+    /**
+     * A parked adoption's backoff ran out during this session (RT-53). An idle own-node
+     * session hands over now: it reconnects, and the next session adopts the node (one
+     * retry per backoff; a node deferred again is parked again for longer). A busy session
+     * hands over when its uploads drain (maybeYieldToDeferredNode sees the expiry).
+     */
+    private onAdoptionRetryTimer;
+    /** Serialize every read-modify-write of the own-operation tracking. */
+    private withOwnTracking;
+    private loadOwnTracking;
+    /**
+     * Load the acknowledged prefix for the current node id, once per node id (an engine
+     * restart keeps its in-memory progress). A persistence layer that has never stored a
+     * prefix under this contract means an upgrade from a release that persisted a MAX:
+     * that value can hide a lost op below it, so the prefix restarts at 0 and the device
+     * re-uploads its own history once, chunk by chunk (the server dedups by id). The
+     * prefix is persisted as it advances, so the re-upload resumes where it stopped.
+     */
+    private loadOwnTrackingLocked;
+    /**
+     * Register an own operation. `unresolved` ops are queued for upload; the others are
+     * already resolved (not upload-eligible). An op at or below the prefix (a sequence
+     * that was a gap when the prefix passed it) lowers the prefix: re-uploading is safe,
+     * skipping is not.
+     */
+    private trackOwnOperation;
+    /** Mark an own operation resolved (stored, terminally rejected, or not eligible). */
+    private markOwnResolved;
+    private isOwnOperationResolved;
+    /**
+     * Lower the prefix (the server holds fewer of this device's operations than it
+     * believed) and forget what this session knew above it: the next advance rescans the
+     * log from there and re-enqueues what is missing.
+     */
+    private lowerOwnPrefixLocked;
+    /**
+     * Advance the prefix over every resolved own sequence, reading the next chunk of the
+     * op log whenever it reaches a sequence this session has not examined yet. Reading a
+     * chunk enqueues its upload-eligible operations (and flushes when streaming), so the
+     * one-time upgrade re-upload proceeds chunk by chunk as acks arrive.
+     */
+    private advanceOwnPrefixLocked;
+    /**
+     * Read own operations [from, to] from the op log and register each sequence: an
+     * upload-eligible op not yet queued is enqueued; an ineligible one is recorded and
+     * resolved; a sequence with no op is resolved. Every sequence in the range ends up
+     * registered, which guarantees the advance loop makes progress.
+     */
+    private scanOwnLog;
+    private persistOwnPrefix;
+    private persistLastAckedServerVector;
+    /**
+     * Refresh the pending count: own operations not yet stored on the server (queued or
+     * in flight), plus the own operations above the prefix not read from the log yet.
+     * Computed from the client's own acknowledgments only, so it drops the moment the
+     * server acknowledges, without waiting for a later handshake (RT-28).
+     */
+    refreshPendingCount(): Promise<void>;
+    /** Synchronous pending count (see {@link refreshPendingCount}). */
+    private computePendingCount;
+    /** Unsynced operations held for a principal that is not signed in (RT-38). */
+    private computeHeldCount;
+    /**
+     * This device's operations not yet stored on the server (queued or in flight).
+     */
+    getPendingSyncOperations(): Promise<Operation[]>;
+    /**
+     * Rebuild the upload set from the op log: every own operation above the acknowledged
+     * prefix that is upload-eligible is queued (first chunk now, the rest as acks move
+     * the prefix). Persisted queue entries that are already resolved are dropped.
+     */
+    private reconcileOutboundFromOpLog;
+    /** Node id of the current session: the store's own, or an adopted node's (RT-40). */
+    private currentNodeId;
+    /** A session uploads only operations authored under its own node id (RT-38, RT-40). */
+    private readonly isSessionOperation;
+    /** Whether the queue holds an operation this session may upload. */
+    private hasUploadable;
+    /** A queued or in-flight operation by id. */
+    private findQueuedOperation;
+    /**
+     * Pick the node this session runs as (RT-40, RT-46). A session uploads under one node
+     * id (the server confines uploads to the session's node), so the database's local
+     * nodes take turns, each for one session:
+     *
+     * - A local node other than the store's own that still has unsynced writes, is not
+     *   held for another principal (RT-38) or bound to another user (RT-42), was not
+     *   refused in this refusal cycle, and is used by no live tab (its lock is free) may
+     *   be adopted: the session runs as that node and uploads its writes with their
+     *   original identity, then ends; the next session picks again.
+     * - Never one whose writes depend causally on another local node's unsynced writes:
+     *   the parent's node goes first (a child is never uploaded before its parent).
+     * - Never a parked one (its last adoption made no progress, for example the server
+     *   kept deferring a write) until something else uploaded or its backoff ran out, so
+     *   one stuck node never blocks the others or this tab's own writes.
+     * - Otherwise the session runs as the store's own node; it yields to a deferred node
+     *   once its own uploads made that node worth retrying (see maybeEndSessionForNodeWork).
+     *
+     * Also counts the other local nodes' unsynced writes, so they are reported (pending,
+     * or held).
+     */
+    private chooseSessionNode;
+    /**
+     * Why a local node other than the store's own must not upload on this session, or
+     * null when it may (RT-38, RT-42, RT-50):
+     *
+     * - Bound to another user than the signed-in one (or refused after acceptance,
+     *   RT-38): `other-user`.
+     * - Unbound (its owner was never recorded, RT-50) while a user is signed in: its
+     *   owner is learned from the server, never guessed. If it was accepted before, the
+     *   server holds a claim on it: it is tried (adopted) on this user's session unless
+     *   the server already refused it for them, and an accepted handshake binds it to
+     *   them. If it never synced nobody can tell whose its writes are: `unassigned`,
+     *   held until the app assigns or discards them.
+     */
+    private holdReason;
+    /** A node bound to another user than the signed-in one (RT-42). */
+    private belongsToAnotherPrincipal;
+    /**
+     * A local node's own operations above its acknowledged prefix that are not
+     * terminally rejected: `count` all of them, `notQueued` those not in the queue, their
+     * `ids`, and the causal parents they name outside this set (`deps`).
+     */
+    private countUnsyncedOfNode;
+    /** The adoption schedule (RT-46), from persistence when it keeps one. */
+    private loadSchedule;
+    private saveSchedule;
+    /**
+     * Operations of `nodeId` were stored (RT-46): a parked adoption may have waited for
+     * them, so the progress counter moves; the node itself is no longer parked.
+     */
+    private recordUploadProgress;
+    /** Park the adopted node: it made no progress in this session (RT-46). */
+    private parkAdoption;
+    /** Forget a drained, non-held local node no live tab uses (bounds the registry). */
+    private forgetDrainedNode;
+    /** Release the lock on an adopted node (RT-40). */
+    private endAdoption;
+    /**
+     * Record an accepted handshake as `nodeId` (RT-38), durably when supported. The server
+     * accepted it for the session's user, so an unbound node is now theirs (RT-50).
+     */
+    private recordNodeAccepted;
+    /** Which of these operation ids the server refused for good (RT-36). */
+    private findTerminalRejections;
+    /** Record durable terminal-rejection markers (RT-36). */
+    private recordTerminalRejections;
+    /**
+     * Restart server->client delivery from 0 at the next session, for the requested and the
+     * accepted views. A full resync includes this client's own operations (a resumed one
+     * does not), which is how operations the device lost come back (RT-35).
+     */
+    private resetDeliveryForFullResync;
+    /**
+     * The server refused an upload with `SEQUENCE_CONFLICT`: it holds another operation of
+     * this node under that number, one this device lost (RT-35: a reload inside the
+     * IndexedDB snapshot window, a restored older copy). Not a refusal of the write: it
+     * gets a fresh number above everything the server holds (same id and content) and is
+     * uploaded again, and the session ends once its uploads are resolved so the next one
+     * resyncs from 0 and fetches the lost operation back.
+     *
+     * @returns Whether the conflict was recovered (false: treat as a plain rejection)
+     */
+    private recoverSequenceConflict;
+    /**
+     * A SEQUENCE_CONFLICT above this session's handshake entry (RT-44): the server held
+     * nothing of this node above that entry when the session began, so the operation now
+     * holding the number was stored during this session, and not by this session. Another
+     * live copy of this database uses the same node id (app data copied to a new machine,
+     * a restored image used alongside the original). Renumbering would only collide again,
+     * and each copy's writes count as the other's own operations (never delivered on a
+     * resumed stream), so this copy moves to a fresh node id: the refused write (refused,
+     * so certainly not stored) and every never-sent one are re-authored under it, the
+     * session ends, and the next one resyncs from 0 to fetch what the other copy wrote.
+     */
+    private recoverFromClone;
+    /**
+     * End the session when it has done its node work and nothing is in flight:
+     * - an own-history recovery is pending (RT-35: reconnect to resync from 0);
+     * - an adopted node's writes are all stored (RT-40: reconnect as the next node, or
+     *   this tab's own);
+     * - an adopted node stalled (RT-46: the server deferred part of it): it is parked and
+     *   the next session serves another node;
+     * - this tab's own uploads are drained, made progress, and a deferred node is now
+     *   worth retrying (RT-46: its parent was among them, or its park has expired).
+     *
+     * @returns Whether the session was ended
+     */
+    private maybeEndSessionForNodeWork;
+    /**
+     * This tab's own session: once its uploads are drained and it stored something, end
+     * it when a node deferred at session start is worth retrying now (RT-46), so other
+     * nodes' writes do not wait for an unrelated reconnect. Bounded: each yield needs new
+     * own progress, and a parked node at most once per {@link ADOPTION_YIELD_MIN_MS}.
+     */
+    private maybeYieldToDeferredNode;
+    private flushQueue;
+    private startOutboundAckTimer;
+    private clearOutboundAckTimer;
+    private scheduleOutboundRetry;
+    private clearOutboundRetryTimer;
+    /** No ack arrived in time: return every batch in flight and reconnect. */
+    private handleOutboundAckTimeout;
+    private handleAwarenessUpdate;
+    private handleTransportClose;
+    private handleTransportError;
+    private transitionTo;
+    private setSerializerWireFormat;
+    /**
+     * Upload predicate: the UPLINK scope only, never query subsets (SYNC-1). Query
+     * subsets describe what this client wants to download; the server authorizes
+     * uploads independently of the client's downloaded view.
+     */
+    private operationAllowedForUpload;
+    /**
+     * Record a local operation that the uplink scope refuses, so it is visible to
+     * the app instead of silently diverging from the server. Operations on
+     * collections that are not synced in either direction are local-only by design
+     * and are not recorded.
+     *
+     * Such an operation counts as resolved for the contiguous acknowledged prefix: it is
+     * recorded here and never uploaded (W3 step 2).
+     */
+    private recordOutOfUplinkScope;
+    /**
+     * Whether an operation falls inside the uplink scope. Query subsets never apply to
+     * uploads (SYNC-1), and nothing applies to inbound operations: the client applies
+     * what the server delivered (SYNC-2).
+     */
+    private matchesUplinkScope;
+    private readRecordForBackfill;
+    private persistDeltaCursor;
+    private persistDeliveryWatermark;
+    private scheduleQuerySubsetReconnect;
+    private reconnectForQuerySubsets;
+}
+
+/**
+ * Configuration for the connection monitor.
+ */
+interface ConnectionMonitorConfig {
+    /** Number of latency samples to keep in the rolling window. Defaults to 20. */
+    windowSize?: number;
+    /** Time in ms after which the connection is considered stale. Defaults to 30000. */
+    staleThreshold?: number;
+    /** Injectable time source for deterministic testing */
+    timeSource?: TimeSource;
+}
+/**
+ * Monitors connection quality based on RTT latency samples,
+ * missed acknowledgments, and activity timestamps.
+ */
+declare class ConnectionMonitor {
+    private readonly windowSize;
+    private readonly staleThreshold;
+    private readonly timeSource;
+    private latencies;
+    private missedAcks;
+    private lastActivityTime;
+    constructor(config?: ConnectionMonitorConfig);
+    /**
+     * Record a round-trip time sample.
+     */
+    recordLatency(ms: number): void;
+    /**
+     * Record a missed acknowledgment (message sent but no response received).
+     */
+    recordMissedAck(): void;
+    /**
+     * Record any activity (message sent or received).
+     */
+    recordActivity(): void;
+    /**
+     * Assess current connection quality based on collected metrics.
+     *
+     * Quality thresholds (average RTT):
+     * - excellent: < 100ms, 0 missed acks
+     * - good: < 300ms, ≤ 1 missed ack
+     * - fair: < 1000ms, ≤ 3 missed acks
+     * - poor: < 5000ms or > 3 missed acks
+     * - offline: no activity for staleThreshold ms
+     */
+    getQuality(): ConnectionQuality;
+    /**
+     * Reset all metrics. Call on disconnect.
+     */
+    reset(): void;
+    /**
+     * Get the current average latency in ms. Returns null if no samples.
+     */
+    getAverageLatency(): number | null;
+    /**
+     * Get the number of missed acks.
+     */
+    getMissedAcks(): number;
+}
+
+/**
+ * Configuration for the reconnection manager.
+ */
+interface ReconnectionConfig {
+    /** Initial delay in ms before first reconnection attempt. Defaults to 1000. */
+    initialDelay?: number;
+    /** Maximum delay in ms between attempts. Defaults to 30000. */
+    maxDelay?: number;
+    /** Multiplier for exponential backoff. Defaults to 2. */
+    multiplier?: number;
+    /** Maximum number of reconnection attempts. 0 means unlimited. Defaults to 0. */
+    maxAttempts?: number;
+    /** Jitter factor (0-1). Random variation applied to delay. Defaults to 0.25. */
+    jitter?: number;
+    /**
+     * How long a connection must stay up (see {@link ReconnectionManager.reportConnected})
+     * before the backoff resets to the initial delay, in ms (SYNC-8). A server that
+     * accepts sessions and drops them right away therefore keeps backing off instead of
+     * being retried at the initial interval forever. Defaults to 10000.
+     */
+    stableAfterMs?: number;
+    /** Injectable time source for deterministic testing. */
+    timeSource?: TimeSource;
+    /** Injectable random source for deterministic jitter. Returns value in [0, 1). */
+    randomSource?: () => number;
+}
+/**
+ * Manages reconnection attempts with exponential backoff and jitter.
+ *
+ * Formula: min(initialDelay * multiplier^attempt, maxDelay) * (1 + jitter * (random - 0.5) * 2)
+ *
+ * The attempt counter belongs to the manager, not to one `start()` run (SYNC-8): it
+ * keeps growing across runs and resets only once a connection stayed up for
+ * `stableAfterMs` ({@link reportConnected}), or on an explicit {@link reset}.
+ */
+declare class ReconnectionManager {
+    private readonly initialDelay;
+    private readonly maxDelay;
+    private readonly multiplier;
+    private readonly maxAttempts;
+    private readonly jitter;
+    private readonly stableAfterMs;
+    private readonly random;
+    private attempt;
+    private timer;
+    private stableTimer;
+    private stopped;
+    private running;
+    /** A disconnect was reported while an attempt was in flight (NEW-SYNC-2). */
+    private pendingRetry;
+    private waitResolve;
+    constructor(config?: ReconnectionConfig);
+    /**
+     * Start reconnection attempts. Calls `onReconnect` with exponential backoff.
+     *
+     * An attempt counts as successful only when `onReconnect` returns true AND no
+     * disconnect was reported ({@link requestRetry}) while it ran: a session that
+     * drops before the attempt returns is retried, never silently lost (NEW-SYNC-2).
+     *
+     * @param onReconnect - Called on each attempt. Return `true` if reconnection succeeded
+     *   (the caller decides what success means; Kora waits for the `streaming` state).
+     * @returns Promise that resolves when reconnection succeeds or maxAttempts reached.
+     */
+    start(onReconnect: () => Promise<boolean>): Promise<boolean>;
+    /**
+     * Report a disconnect. While a run is in flight it makes the current attempt count
+     * as failed, so the loop retries (with backoff) instead of exiting on a session
+     * that already dropped. Returns true when a running loop took the request; false
+     * means the caller should start a new run.
+     */
+    requestRetry(): boolean;
+    /**
+     * Report that a connection is up (it reached streaming). If it is still up after
+     * `stableAfterMs`, the backoff resets to the initial delay. A disconnect reported
+     * before then ({@link requestRetry} or {@link reportDisconnected}) cancels the reset.
+     */
+    reportConnected(): void;
+    /** Report that the connection dropped: a pending backoff reset is cancelled. */
+    reportDisconnected(): void;
+    /**
+     * 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.
+     */
+    stop(): void;
+    /**
+     * Reset the attempt counter to the initial delay. Call after a deliberate
+     * (user-initiated) reconnection. It never clears a {@link stop}: a stopped loop
+     * stays stopped, so a stop racing a reset cannot resurrect it (SYNC-8).
+     */
+    reset(): void;
+    /**
+     * Compute the next delay for the current attempt.
+     * Exposed for testing purposes.
+     */
+    getNextDelay(): number;
+    /**
+     * Whether the reconnection loop is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Current attempt number (for testing).
+     */
+    getAttemptCount(): number;
+    private clearStableTimer;
+    private wait;
+}
+
+/**
+ * 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;
+
+/** The part of the sync encryption config that decides what the server can read. */
+interface EncryptedRelationConfig {
+    enabled?: boolean;
+    cleartextFields?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Thrown at app initialization when end-to-end encryption would seal the foreign-key
+ * field of a relation with a referential `onDelete` policy.
+ */
+declare class SealedRelationFieldError extends KoraError {
+    readonly relation: string;
+    readonly collection: string;
+    readonly field: string;
+    constructor(message: string, relation: string, collection: string, field: string);
+}
+/**
+ * Refuse a configuration where end-to-end encryption seals the foreign key of a
+ * relation whose `onDelete` is `cascade`, `set-null` or `restrict`.
+ *
+ * Referential policies are enforced by the sync server, the one replica that sees every
+ * child: it cascades (or nulls, or refuses) for children no single device knows about,
+ * and relays the result. It can only do so when it can read the foreign key. With the
+ * key sealed, no replica can enforce the policy for everyone, and every device-side
+ * substitute either loses a cascade or deletes a child another device moved away
+ * (RT-74, RT-78, RT-82). So the foreign key of such a relation must travel in cleartext:
+ * it reveals which parent a child belongs to, never the child's other fields.
+ *
+ * Relations with `onDelete: 'no-action'` (or none) are not affected: nothing is
+ * enforced on delete, so their foreign key may stay sealed.
+ *
+ * @param schema - The app schema
+ * @param encryption - The sync encryption config (none, or disabled: nothing to check)
+ * @throws {SealedRelationFieldError} Naming the relation, the field and the fix
+ */
+declare function validateEncryptedRelations(schema: SchemaDefinition, encryption: EncryptedRelationConfig | null | undefined): void;
+
+/**
+ * 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.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests; production must
+ *   keep the default so derived keys stay brute-force resistant.
+ * @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, iterations?: number): 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.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests.
+ * @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, iterations?: number): Promise<VersionedKey>;
+
+/** Default status when sync is not configured or the engine is unavailable. */
+declare const OFFLINE_SYNC_STATUS: SyncStatusInfo;
+interface SyncStatusControllerOptions {
+    syncEngine?: {
+        getStatus(): SyncStatusInfo;
+    } | null;
+    getSyncEngine?: () => {
+        getStatus(): SyncStatusInfo;
+    } | null;
+    subscribeSyncStatus: ((listener: (status: SyncStatusInfo) => void) => () => void) | null;
+    events: KoraEventEmitter | null;
+}
+interface SyncStatusController {
+    getSnapshot(): SyncStatusInfo;
+    subscribe(listener: () => void): () => void;
+    refresh(): void;
+    destroy(): void;
+}
+/**
+ * Framework-agnostic sync status subscription with live reads when no bridge exists.
+ */
+declare function createSyncStatusController(options: SyncStatusControllerOptions): SyncStatusController;
+
+/**
+ * Returns remote collaborators' awareness states (excludes the local client).
+ */
+declare function getRemoteAwarenessStates(awareness: AwarenessManager): AwarenessState[];
+/**
+ * Subscribes to awareness changes and invokes `listener` only when the remote
+ * collaborator set changes.
+ */
+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 CachedKeyring, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, type EncryptedRelationConfig, EncryptionError, EncryptionKeyError, EncryptionKeyring, type EncryptionKeyringOptions, type EncryptionLockState, type EncryptionStatus, type EncryptionStatusCode, HTTP_SYNC_SESSION_HEADER, HeldNodeInfo, HttpLongPollingTransport, type HttpLongPollingTransportOptions, IndexedDbKeyCache, JsonMessageSerializer, type KeyCache, KeyDerivationError, type KeyServiceChannel, type KeyServiceReply, KeyUnwrapError, MemoryKeyCache, type MessageSerializer, NegotiatedMessageSerializer, NoKeyCache, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QuarantinedOperation, QueueStorage, type ReconnectionConfig, ReconnectionManager, RejectedOperation, RejectedOperationStorage, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, ScopeSnapshotOptions, SealedRelationFieldError, 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, WrappedKeyRecord, YjsDocUpdateMessage, createDeltaCursorFromBatch, createKeyCache, createSyncStatusController, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, validateEncryptedRelations, versionVectorToWire, wireToVersionVector };