@korajs/sync 1.0.0-beta.12 → 1.0.0-beta.13

package/dist/transport-Bemtqwep.d.cts

@@ -0,0 +1,1448 @@
+import * as _korajs_core from '@korajs/core';
+import { KoraError, Operation, VersionVector, OperationType, HLCTimestamp, AtomicOp, EncryptedOperationEnvelope } from '@korajs/core';
+
+/**
+ * Encryption types for the Kora.js sync layer.
+ *
+ * These types define the configuration and wire format for end-to-end
+ * encryption of operation data during sync. Only `data` and `previousData`
+ * fields are encrypted — metadata stays in cleartext for routing and ordering.
+ */
+/**
+ * Supported encryption algorithms. Currently only AES-256-GCM is supported,
+ * but the type is extensible for future algorithms.
+ */
+type SyncEncryptionAlgorithm = 'aes-256-gcm';
+/**
+ * Configuration for sync-layer end-to-end encryption.
+ *
+ * Every user has a keyring of random 256-bit data keys. The sync server stores them
+ * only wrapped by a key derived from the user's passphrase (PBKDF2-SHA256, 600,000
+ * iterations, per-user random salt); it never sees the passphrase or a data key. A
+ * device fetches and opens the record during the sync handshake, caches the opened
+ * keys (non-extractable), and from then on works offline. Every device of the user
+ * that opens the record holds the same keys, so it decrypts everything.
+ *
+ * @example
+ * ```typescript
+ * const app = createApp({
+ *   schema,
+ *   sync: {
+ *     url: 'wss://my-server.com/kora',
+ *     encryption: { enabled: true },   // locked until app.encryption.unlock(passphrase)
+ *   }
+ * })
+ * ```
+ */
+interface SyncEncryptionConfig {
+    /** Whether encryption is enabled. When false, all other fields are ignored. */
+    enabled: boolean;
+    /**
+     * The user's encryption passphrase, or an async provider of it. Optional: without
+     * it the keyring starts locked (sync paused, local data usable) until
+     * `app.encryption.unlock(passphrase)`. With it, the keyring is opened (or, on the
+     * user's first device, created) automatically at the first sync handshake.
+     */
+    key?: string | (() => Promise<string>);
+    /**
+     * Keyring name: one encryption scope of the signed-in user. Defaults to 'default'.
+     * Distinct keyrings have distinct keys and passphrases.
+     */
+    keyring?: string;
+    /**
+     * Where unlocked keys are kept on the device: 'auto' (IndexedDB in browsers, memory
+     * elsewhere), 'indexeddb', 'memory' (until the app closes) or 'none' (ask for the
+     * passphrase at every start). Keys are stored non-extractable.
+     */
+    keyCache?: 'auto' | 'indexeddb' | 'memory' | 'none';
+    /**
+     * PBKDF2 iterations for new key records, and the minimum accepted from the server.
+     * Defaults to 600,000 (OWASP). Lower it only in tests; every device of a user must
+     * use the same value or a lower one.
+     */
+    kdfIterations?: number;
+    /**
+     * Encryption algorithm. Defaults to 'aes-256-gcm'.
+     * Currently only AES-256-GCM is supported.
+     */
+    algorithm?: SyncEncryptionAlgorithm;
+    /**
+     * Per collection, the data fields that travel in cleartext beside the encryption
+     * envelope, so the server can evaluate sync scopes on them (for example
+     * `{ todos: ['ownerId'] }`). Every other field, `previousData` and atomic ops are
+     * ciphertext. Values listed here are visible to the server: list only scope keys.
+     */
+    cleartextFields?: Record<string, string[]>;
+    /**
+     * Accept inbound operations without an encryption envelope during a migration from
+     * plaintext sync. Off by default: with encryption enabled a plaintext operation is
+     * refused (quarantined), because anyone who can reach the sync server could have
+     * written it (ENC-3). Turn it on only for the migration window.
+     */
+    allowPlaintextMigration?: boolean;
+}
+/**
+ * Encrypted payload structure embedded in operation `data` and `previousData`
+ * fields when encryption is enabled.
+ *
+ * This structure replaces the original field values on the wire. The server
+ * stores and relays these opaque payloads without being able to read the
+ * plaintext contents.
+ */
+interface EncryptedPayload {
+    /** Encryption key version. Supports key rotation: older operations may use older key versions. */
+    v: number;
+    /** Base64-encoded initialization vector (12 bytes for AES-GCM). Unique per operation field. */
+    iv: string;
+    /** Base64-encoded ciphertext (AES-256-GCM output including authentication tag). */
+    ct: string;
+    /** Encryption algorithm identifier. */
+    alg: SyncEncryptionAlgorithm;
+}
+/**
+ * A versioned encryption key.
+ *
+ * Key versions enable rotation: operations encrypted with older key versions carry
+ * their version number in the envelope, so the decryptor selects the correct key.
+ */
+interface VersionedKey {
+    /** Key version number (monotonically increasing, starting at 1). */
+    version: number;
+    /** The CryptoKey for AES-256-GCM operations. */
+    key: CryptoKey;
+    /**
+     * The id written into envelopes (`keyId`). Keyring keys carry a random id from the
+     * key record. When absent, the id is a fingerprint of `salt`.
+     */
+    keyId?: string;
+    /** The salt a passphrase-derived key was derived with (names it when `keyId` is absent). */
+    salt?: Uint8Array;
+}
+
+/**
+ * Internal sync engine states. Used for state machine transitions.
+ */
+declare const SYNC_STATES: readonly ["disconnected", "connecting", "handshaking", "syncing", "streaming", "error"];
+type SyncState = (typeof SYNC_STATES)[number];
+/**
+ * Developer-facing sync status. Simplified view of the internal state.
+ */
+declare const SYNC_STATUSES: readonly ["connected", "reconnecting", "syncing", "synced", "offline", "clock-error", "error", "schema-mismatch", "auth-required", "encryption-locked"];
+type SyncStatus = (typeof SYNC_STATUSES)[number];
+type SyncPhase = 'suspended' | 'offline' | 'connecting' | 'authenticating' | 'handshaking' | 'uploading' | 'receiving' | 'applying' | 'streaming' | 'blocked';
+interface ActiveApplyFailure {
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+    firstSeenAt: number;
+    retryCount: number;
+}
+/** Why a local node's unsynced writes are held (RT-38, RT-50). */
+type HeldReason = 'other-user' | 'unassigned';
+/** A local node whose unsynced writes are held (see {@link SyncStatusInfo.heldNodes}). */
+interface HeldNodeInfo {
+    nodeId: string;
+    /** Unsynced writes the node holds. */
+    operationCount: number;
+    reason: HeldReason;
+    /** The user the node is bound to, or null when nobody knows (unassigned). */
+    principal: string | null;
+}
+/**
+ * Sync status information exposed to developers.
+ */
+interface SyncStatusInfo {
+    /** Current developer-facing status */
+    status: SyncStatus;
+    phase?: SyncPhase;
+    reason?: string;
+    /** True when the engine is actively trying to re-establish a transport session. */
+    reconnecting: boolean;
+    /** Number of operations waiting to be sent */
+    pendingOperations: number;
+    /** Timestamp of last successful sync (null if never synced) */
+    lastSyncedAt: number | null;
+    /** Timestamp of last successful push to the server (null if never pushed) */
+    lastSuccessfulPush: number | null;
+    /** Timestamp of last successful pull from the server (null if never pulled) */
+    lastSuccessfulPull: number | null;
+    /** Number of merge conflicts encountered during this session */
+    conflicts: number;
+    /**
+     * Unsynced writes of another user who shared this local database (RT-38): the server
+     * refused their node for the signed-in principal, so they wait, not counted in
+     * `pendingOperations`, until that user signs in again on this device. Use
+     * `store.namespaceByAuthUser` to give each user their own database instead.
+     */
+    heldOperations?: number;
+    /**
+     * The local nodes whose unsynced writes are held (RT-38, RT-50), with how many each
+     * holds and why: `other-user` (they belong to another user, or the server refused
+     * the node for the signed-in one: they upload when their user signs in) or
+     * `unassigned` (written before the app knew who was signed in, on a node that never
+     * synced: nobody can tell whose they are, so the app decides with
+     * `app.sync.assignHeld` or `app.sync.discardHeld`). As of the last session start.
+     */
+    heldNodes?: HeldNodeInfo[];
+    /**
+     * `degraded` when this device's local database could not be made durable several times
+     * in a row (storage quota exceeded, IndexedDB broken; RT-49). Uploads continue so the
+     * server keeps a durable copy, and a later reload recovers its writes from the server;
+     * writes made while offline in this state may be lost if the page closes. Show the user
+     * a warning (free up storage, stay online). `durable` otherwise.
+     */
+    localDurability?: 'durable' | 'degraded';
+    /**
+     * Sync protocol version the server answered with in the current (or last) session,
+     * or null before any server answered.
+     */
+    serverProtocolVersion?: number | null;
+    /**
+     * True when the server speaks an older sync protocol than this client (a pre-beta.13
+     * server). It still syncs, but that protocol is deprecated and a later release
+     * refuses it: upgrade the sync server.
+     */
+    protocolDeprecated?: boolean;
+    /** serverTime - localTime in ms measured at the last handshake, or null before first connect. Negative = this device's clock is fast. */
+    clockSkewMs: number | null;
+    inFlightUploadOperations?: number;
+    hasInFlightDeliveryBatch?: boolean;
+    activeViewId?: string;
+    activeViewComplete?: boolean;
+    initialSync?: {
+        complete: boolean;
+        receivedBatches: number;
+        totalBatches: number | null;
+        progress: number | null;
+    };
+    deliveryWatermark?: number;
+    serverFrontier?: number | null;
+    blockedFailure?: ActiveApplyFailure | null;
+}
+interface SyncSettlementOptions {
+    upload?: boolean;
+    download?: 'active-view' | false;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+type SyncSettlementResult = {
+    outcome: 'settled';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'offline';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'suspended';
+    reason: string;
+    status: SyncStatusInfo;
+} | {
+    outcome: 'blocked';
+    failure: ActiveApplyFailure;
+    status: SyncStatusInfo;
+} | {
+    outcome: 'timeout';
+    status: SyncStatusInfo;
+} | {
+    outcome: 'aborted';
+    status: SyncStatusInfo;
+};
+/**
+ * Per-collection sync scope map. Maps collection names to field-value filters.
+ * Empty filter `{}` means no restriction (all records visible).
+ * Missing collection means hidden (no records visible for that collection).
+ */
+type SyncScopeMap = Record<string, Record<string, unknown>>;
+/** Options passed to {@link SyncConfig.auth}. */
+interface SyncAuthRequest {
+    /**
+     * True when the server ended the previous session because its credential
+     * expired or was revoked. A cached token must not be reused.
+     */
+    forceRefresh?: boolean;
+}
+/**
+ * Sync configuration provided by the developer.
+ */
+interface SyncConfig {
+    /** WebSocket or HTTP URL for the sync server */
+    url: string;
+    /** Transport type to use. Defaults to 'websocket'. */
+    transport?: 'websocket' | 'http';
+    /**
+     * Auth provider function. Called before each connection attempt. After the
+     * server ends a session with `AUTH_EXPIRED` or `AUTH_REVOKED` it is called
+     * with `{ forceRefresh: true }`: return a freshly refreshed token, never the
+     * cached one the server just refused.
+     */
+    auth?: (options?: SyncAuthRequest) => Promise<{
+        token: string;
+    }>;
+    /**
+     * The signed-in user whose writes this device makes (RT-42): a user id, or null /
+     * undefined when nobody is known to be signed in. Called before each session. With
+     * it, the engine binds the store's node to that user (the store moves to the user's
+     * own node when another user's is in use) and never uploads, or adopts, a node that
+     * belongs to another user: those writes wait for their user (`heldOperations`).
+     * `createApp` derives it from `sync.authClient`.
+     */
+    principal?: () => Promise<string | null | undefined>;
+    /** Auth readiness gate. A suspended result prevents transport creation and retries. */
+    authState?: () => Promise<{
+        state: 'loading' | 'signed-out' | 'anonymous' | 'authenticated';
+        mayConnectAnonymously?: boolean;
+    }>;
+    querySubsets?: {
+        mode?: 'reactive' | 'static' | 'disabled';
+    };
+    /** Client-local behavior for records leaving the accepted downlink scope. Defaults to `retain`. */
+    scopeExit?: 'retain' | 'retract';
+    /** Sync scopes per collection. Limits which records sync to this client. */
+    scopes?: Record<string, (ctx: SyncScopeContext) => Record<string, unknown>>;
+    /**
+     * Pre-computed per-collection sync scope map. Sent to the server in the handshake.
+     * Built automatically by createApp from schema scope declarations + flat scope values.
+     */
+    scopeMap?: SyncScopeMap;
+    /**
+     * Collections the app's schema syncs (all of them, or the sync-scoped ones when the
+     * schema declares partial sync rules). Set by createApp. When no `scopeMap` is
+     * configured, a write on one of these that the server's accepted upload scope omits
+     * is surfaced as `sync:operation-rejected` (`OUT_OF_UPLINK_SCOPE`) instead of being
+     * treated as local-only (RT-89). Omitted: such writes stay local without a rejection.
+     */
+    syncedCollections?: readonly string[];
+    /** Number of operations per batch. Defaults to 100. */
+    batchSize?: number;
+    /**
+     * Maximum time to wait for the server to acknowledge an outbound batch before
+     * treating the connection as stalled. The batch is returned to the durable
+     * outbound queue before disconnecting so it can be retried on reconnect.
+     * Defaults to 30000ms. Set to 0 to disable the watchdog.
+     */
+    outboundAckTimeoutMs?: number;
+    /** Initial delay before resending a transiently rejected outbound operation. Defaults to 250ms. */
+    outboundRetryBaseDelayMs?: number;
+    /** Maximum transient-operation retry delay. Defaults to 30000ms. */
+    outboundRetryMaxDelayMs?: number;
+    /** Initial reconnection delay in ms. Defaults to 1000. */
+    reconnectInterval?: number;
+    /** Maximum reconnection delay in ms. Defaults to 30000. */
+    maxReconnectInterval?: number;
+    /** Schema version of this client. */
+    schemaVersion?: number;
+    /** Start sync automatically when the engine is created. Defaults to false. */
+    autoConnect?: boolean;
+    /**
+     * When true, wait for server ACKs on all outbound handshake delta batches before
+     * entering streaming. Improves backpressure for large initial syncs.
+     */
+    strictHandshake?: boolean;
+    /**
+     * Optional schema transforms for cross-schema-version sync. They run at fold time
+     * (RT-84): delivered operations are stored exactly as received and the local store
+     * folds their transformed view, so the store must be given the same list (`createApp`
+     * does). An operation with no transform path to this schema version is kept aside
+     * and replayed after an upgrade.
+     */
+    operationTransforms?: _korajs_core.OperationTransform[];
+    /**
+     * Richtext snapshot size (bytes) at which the optional Yjs doc channel is used.
+     * Defaults to 4096.
+     */
+    richtextDocChannelThreshold?: number;
+    /**
+     * End-to-end encryption configuration.
+     * When enabled, `data` and `previousData` fields are encrypted before sending
+     * over the wire. The server never sees plaintext user data.
+     */
+    encryption?: SyncEncryptionConfig;
+}
+/**
+ * Context passed to sync scope functions.
+ */
+interface SyncScopeContext {
+    userId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Persists last-acked server version vector and computes unsynced operations from the op log.
+ */
+interface DeltaCursor {
+    /** ID of the last fully applied operation in the previous delta stream */
+    lastOperationId: string;
+    /** Zero-based batch index where the cursor was recorded */
+    batchIndex: number;
+}
+interface SyncStatePersistence {
+    loadLastAckedServerVector(): Promise<VersionVector>;
+    saveLastAckedServerVector(vector: VersionVector): Promise<void>;
+    mergeServerVectors(a: VersionVector, b: VersionVector): VersionVector;
+    countUnsyncedOperations(serverVector: VersionVector): Promise<number>;
+    getUnsyncedOperations(serverVector: VersionVector): Promise<Operation[]>;
+    /** Resume position for paginated initial sync (optional). */
+    loadDeltaCursor?(): Promise<DeltaCursor | null>;
+    saveDeltaCursor?(cursor: DeltaCursor | null): Promise<void>;
+    /**
+     * The delivery watermark for a sync view, keyed by an opaque view signature (the auth
+     * scope plus active query subscriptions). Persisted per view so a restarted client
+     * resumes each view's gap-free stream from the right point, and switching views does not
+     * re-sync a view already synced. The empty-string signature is the default, unfiltered
+     * view. Optional: a persistence layer that omits these falls back to re-sync on restart.
+     */
+    loadDeliveryWatermark?(signature: string): Promise<number>;
+    saveDeliveryWatermark?(signature: string, watermark: number): Promise<void>;
+    /** Load every persisted view watermark, keyed by signature. */
+    loadAllDeliveryWatermarks?(): Promise<Record<string, number>>;
+    /**
+     * Delete a persisted view watermark. Used to bound the number of stored view watermarks
+     * (a cold view is evicted from the client's cache and its persisted row removed). Safe:
+     * an evicted view back-fills from 0 (deduplicated) when next visited.
+     */
+    deleteDeliveryWatermark?(signature: string): Promise<void>;
+    /**
+     * The per-device node token the server issued at this node id's first anonymous
+     * claim (RT-12), stored next to the node id so the device can reconnect with it.
+     * Optional: without it the token lives only as long as the sync engine.
+     */
+    loadNodeToken?(nodeId?: string): Promise<string | null>;
+    /**
+     * `nodeId` names the node the token was issued for: a database that authors under
+     * several node ids (a rotated identity, per-tab isolation) keeps one token per node.
+     */
+    saveNodeToken?(token: string, nodeId?: string): Promise<void>;
+    /**
+     * The node ids the server named authoritative in its last accepted handshake response
+     * (`HandshakeResponseMessage.authoritativeNodeIds`, protocol v2): operations from
+     * these nodes are server-authored and may carry `fieldVersions` / `foldState`.
+     * Returns null when no protocol-2 server ever answered. Optional.
+     */
+    loadAuthoritativeNodeIds?(): Promise<string[] | null>;
+    saveAuthoritativeNodeIds?(nodeIds: string[]): Promise<void>;
+    /**
+     * The contiguous acknowledged prefix of this device's own operations (W3): the highest
+     * sequence s such that every own operation with sequence <= s is stored on the server,
+     * terminally rejected and recorded, or was never upload-eligible. Keyed by node id, so
+     * a rotated node starts from 0. Returns null when nothing was ever recorded under this
+     * contract (a device upgrading from a release that persisted a max, not a prefix): the
+     * engine then re-uploads the device's own history once, from 0; the server dedups by id.
+     * Optional: without it the engine trusts the own entry of the last acked server vector.
+     */
+    loadOwnAckedThrough?(nodeId: string): Promise<number | null>;
+    saveOwnAckedThrough?(nodeId: string, sequence: number): Promise<void>;
+    /**
+     * Durable inbound quarantine (W4): delivered operations the client deliberately did
+     * not apply (unknown collection, transform unavailable, deferred or rejected apply,
+     * far-future timestamp, undecryptable payload). When `watermark` is given, the rows and
+     * the delivery watermark advance MUST be written in one transaction, so the watermark
+     * never passes an operation that is neither applied nor recorded here. Optional: a
+     * persistence layer without it keeps the old behaviour (the watermark stalls instead).
+     */
+    saveQuarantine?(entries: QuarantinedOperation[], watermark?: {
+        signature: string;
+        watermark: number;
+    }): Promise<void>;
+    /** Every quarantined operation, oldest delivery first. */
+    loadQuarantine?(): Promise<QuarantinedOperation[]>;
+    /** Remove quarantined operations once applied (replay) or reconciled. */
+    removeQuarantine?(operationIds: string[]): Promise<void>;
+    /**
+     * The downlink scope the server last accepted for this device (SYNC-11). The next
+     * handshake reports its canonical key and that view's delivery watermark next to the
+     * requested view's, so a server that resolves the same scope again resumes the
+     * stream instead of restarting it from 0. Never sent as the requested scope.
+     * Optional; without it every handshake with a server-chosen scope rescans from 0.
+     */
+    loadAcceptedDownlinkScope?(): Promise<SyncScopeMap | null>;
+    saveAcceptedDownlinkScope?(scope: SyncScopeMap | null): Promise<void>;
+    /**
+     * Durable terminal-rejection markers (RT-36): operations the server refused with a
+     * non-retriable rejection. Never cleared (unlike the app's rejected list), so a
+     * rescan of the device's own history never submits a refused operation again.
+     * Optional: without them the engine remembers refusals for its own lifetime only.
+     */
+    recordTerminalRejections?(entries: TerminalRejectionRecord[]): Promise<void>;
+    /** Which of these operation ids carry a terminal-rejection marker. */
+    findTerminalRejections?(operationIds: string[]): Promise<Set<string>>;
+    /**
+     * The node ids this database authored operations under (RT-38, RT-40), with what the
+     * sync server said about each. Optional: without it the engine tracks only the
+     * current node and keeps the pre-Phase-2 behaviour for refused nodes.
+     */
+    listLocalNodes?(): Promise<LocalNodeInfo[]>;
+    /** Record an accepted handshake as `nodeId`; starts a new refusal cycle. */
+    markLocalNodeAccepted?(nodeId: string): Promise<void>;
+    /** Record that the server refused `nodeId`; `held` holds its unsynced writes. */
+    markLocalNodeRefused?(nodeId: string, held: boolean): Promise<void>;
+    /**
+     * A handshake as `nodeId` was accepted for `principal` (RT-50): bind an unbound node
+     * (or replace a guessed binding) from the server's answer.
+     */
+    confirmLocalNodePrincipal?(nodeId: string, principal: string): Promise<void>;
+    /**
+     * The server refused `nodeId` for `principal` (RT-50): clear a guessed binding, and
+     * remember that an unbound node is not theirs.
+     */
+    recordLocalNodeRefusedFor?(nodeId: string, principal: string): Promise<void>;
+    /**
+     * Assign a held, unbound node's writes to `principal` (RT-50, the app's decision).
+     * @returns false when the node is not unbound, or was refused for `principal`
+     */
+    assignLocalNodePrincipal?(nodeId: string, principal: string): Promise<boolean>;
+    /** Forget a non-current local node whatever it holds (its held writes were discarded). */
+    dropLocalNode?(nodeId: string): Promise<void>;
+    /** The current refusal cycle (count of accepted handshakes). */
+    loadAcceptedCycle?(): Promise<number>;
+    /** Forget a non-current local node with nothing left to upload (bounds the registry). */
+    forgetLocalNode?(nodeId: string): Promise<void>;
+    /**
+     * Which adoptions of other local nodes are parked (RT-46), and an upload-progress
+     * counter. Optional: without it the schedule lives for the engine's lifetime.
+     */
+    loadAdoptionSchedule?(): Promise<AdoptionScheduleInfo>;
+    saveAdoptionSchedule?(schedule: AdoptionScheduleInfo): Promise<void>;
+}
+/**
+ * Upload scheduling across a database's local nodes (RT-46). A node whose adoption made
+ * no progress is parked: it is retried once anything else uploaded (`progress` moved past
+ * `progressMark`) or after its backoff (`untilMs`).
+ */
+interface AdoptionScheduleInfo {
+    progress: number;
+    parked: Record<string, {
+        progressMark: number;
+        untilMs: number;
+        count: number;
+        parkedAtMs: number;
+    }>;
+}
+/** A terminally rejected operation, as recorded in the durable markers (RT-36). */
+interface TerminalRejectionRecord {
+    operationId: string;
+    nodeId: string | null;
+    sequenceNumber: number | null;
+    code: string;
+    rejectedAt: number;
+}
+/** A node id this database authored operations under (RT-38, RT-40). */
+interface LocalNodeInfo {
+    nodeId: string;
+    /** A handshake as this node was accepted at least once. */
+    accepted: boolean;
+    /** Refused after acceptance: its unsynced writes belong to a principal not signed in. */
+    held: boolean;
+    /** Refusal cycle in which the server last refused it, or null. */
+    refusedCycle: number | null;
+    /**
+     * The user the node's writes belong to (RT-42), or null when unknown. A node bound to
+     * another user than the signed-in one is never uploaded or adopted.
+     */
+    principal?: string | null;
+    /**
+     * How `principal` was learned (RT-50): `fresh` (bound before its first write),
+     * `server` (an accepted handshake), `app` (assigned by the app: a guess the server can
+     * overrule), or null (unbound, or a guess by an earlier release).
+     */
+    binding?: 'fresh' | 'server' | 'app' | null;
+    /** Users the server refused this unbound node for (RT-50): never tried for them again. */
+    refusedPrincipals?: string[];
+}
+/**
+ * A delivered operation the client deliberately did not apply, kept durably so it is
+ * never silently lost and can be replayed (on start, after a schema upgrade, or on demand).
+ */
+interface QuarantinedOperation {
+    /** The operation as delivered (still encrypted when decryption failed). */
+    operation: Operation;
+    /** Delivery sequence of the batch that carried it, or null for a legacy batch. */
+    deliverySequence: number | null;
+    /** Machine-readable reason (for example `APPLY_SKIPPED`, `REMOTE_CLOCK_DRIFT`). */
+    code: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Wall-clock time (ms) it was quarantined. Display only. */
+    quarantinedAt: number;
+}
+/**
+ * Interface for persisting the outbound operation queue.
+ * Operations must survive page refreshes and be sent when connection is re-established.
+ */
+interface QueueStorage {
+    /** Load all queued operations from persistent storage */
+    load(): Promise<Operation[]>;
+    /** Persist an operation to the queue */
+    enqueue(op: Operation): Promise<void>;
+    /** Remove acknowledged operations by their IDs */
+    dequeue(ids: string[]): Promise<void>;
+    /** Return number of operations in storage */
+    count(): Promise<number>;
+    /**
+     * Record that these queued operations were put on the wire at least once. A sent
+     * operation may already be stored on the server (its ack can be lost), so it must
+     * never be re-stamped by a clock rebase (W3 step 4). Optional: without it the flag
+     * lives for the engine's lifetime only.
+     */
+    markSent?(ops: Operation[]): Promise<void>;
+    /** Ids of queued operations recorded by {@link markSent}. */
+    loadSentIds?(): Promise<string[]>;
+}
+/**
+ * A record of one outbound operation the server permanently refused. Preserved so
+ * a rejected op is explainable and reconcilable rather than silently lost.
+ */
+interface RejectedOperation {
+    /** Content-addressed id of the rejected operation. */
+    operationId: string;
+    /** Collection the operation targeted. */
+    collection: string;
+    /** Record the operation targeted. */
+    recordId: string;
+    /** Stable, machine-readable reason code from the server. */
+    code: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Whether resubmitting the identical operation may later succeed. */
+    retriable: boolean;
+    /** Wall-clock time (ms since epoch) the rejection was recorded. Display only. */
+    rejectedAt: number;
+}
+/**
+ * Interface for durably persisting operations the server rejected, so the record
+ * survives a page refresh. Keyed by operation id (idempotent on re-rejection).
+ */
+interface RejectedOperationStorage {
+    /** Record (or overwrite) a rejected operation. */
+    record(rejected: RejectedOperation): Promise<void>;
+    /** List all recorded rejected operations. */
+    list(): Promise<RejectedOperation[]>;
+    /** Remove rejected operations by their operation ids (after the app reconciles them). */
+    remove(operationIds: string[]): Promise<void>;
+}
+/**
+ * In-memory {@link RejectedOperationStorage}. The default when no durable store is
+ * provided; suitable for tests and ephemeral sessions.
+ */
+declare class MemoryRejectedOperationStorage implements RejectedOperationStorage {
+    private readonly rejected;
+    record(rejected: RejectedOperation): Promise<void>;
+    list(): Promise<RejectedOperation[]>;
+    remove(operationIds: string[]): Promise<void>;
+}
+/**
+ * Thrown when an operation violates sync scope constraints.
+ * This can happen when:
+ * - A client tries to push an operation outside its configured scope
+ * - The server rejects an operation because it falls outside the client's scope
+ */
+declare class ScopeViolationError extends KoraError {
+    readonly operationId: string;
+    readonly collection: string;
+    readonly scope: Record<string, unknown>;
+    constructor(operationId: string, collection: string, scope: Record<string, unknown>, message?: string);
+}
+/**
+ * Thrown when a sync scope configuration is invalid.
+ */
+declare class InvalidScopeError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+
+/** Options for {@link buildScopeSnapshot}. */
+interface ScopeSnapshotOptions {
+    /**
+     * Layer the writer's `previousData` between the stored record and `op.data`.
+     * Off by default: `previousData` is supplied by the writer and is never checked
+     * against the stored row, so a server visibility decision built on it lets one
+     * tenant steer its operations into another tenant's log (RT-3). Opt in only
+     * where the writer is trusted for the decision, such as a client filtering its
+     * own local view.
+     * @default false
+     */
+    includePreviousData?: boolean;
+}
+/**
+ * Build the record snapshot a scope or query-subset predicate is evaluated against
+ * for an operation.
+ *
+ * Layering is `fullRecord < data` (or `fullRecord < previousData < data` with
+ * `includePreviousData`), so the snapshot approximates the record after the
+ * operation. The record identity is NOT taken from any of those
+ * layers: `id` is always `op.recordId`, assigned last. An operation (or a stale
+ * stored row) can therefore never claim to be a different record than the one it
+ * actually targets, which is what made `previousData: { id: '<allowed>' }` a write
+ * bypass under id-scoped predicates.
+ *
+ * This is the single snapshot builder shared by the client scope filter, the client
+ * query-subset filter and the server scope filter. It is used for visibility
+ * decisions only; upload authorization never reads `previousData` (see the server's
+ * `authorizeUplinkWrite`).
+ *
+ * @param op - The operation being judged
+ * @param fullRecord - Optional stored record state used to fill fields the op omits
+ * @param options - Whether to trust the writer's `previousData` (default: no)
+ * @returns The snapshot, always carrying `id === op.recordId`
+ */
+declare function buildScopeSnapshot(op: Operation, fullRecord?: Record<string, unknown> | null, options?: ScopeSnapshotOptions): Record<string, unknown>;
+/**
+ * True when `actual` satisfies a scope predicate value: either an exact value
+ * (compared with `Object.is`) or a bounded `{ $in: [...] }` set. An `undefined` or
+ * `null` predicate value (or `$in` member) never matches.
+ *
+ * @param actual - The record's field value
+ * @param expected - The scope predicate for that field
+ * @returns Whether the value is inside the predicate
+ */
+declare function matchesScopePredicate(actual: unknown, expected: unknown): boolean;
+/**
+ * True when every field predicate in a collection scope matches the record.
+ *
+ * @param record - The record (or snapshot) to test
+ * @param collectionScope - Field predicates for the record's collection
+ * @returns Whether the record is inside the scope
+ */
+declare function recordMatchesScopePredicates(record: Record<string, unknown>, collectionScope: Record<string, unknown>): boolean;
+
+/**
+ * A live query filter that narrows which operations sync for a collection.
+ */
+interface SyncQuerySubset {
+    collection: string;
+    where: Record<string, unknown>;
+}
+/**
+ * Returns true when an operation matches at least one active query subset
+ * for its collection. Collections without query subsets pass through.
+ *
+ * The writer's `previousData` is ignored unless `options.includePreviousData` is
+ * set (see {@link ScopeSnapshotOptions}); the server never sets it.
+ */
+declare function operationMatchesQuerySubsets(op: Operation, subsets: SyncQuerySubset[] | undefined, fullRecord?: Record<string, unknown> | null, options?: ScopeSnapshotOptions): boolean;
+/** Canonicalize equality subsets and remove subsets already covered by a broader one. */
+declare function dedupeQuerySubsets(subsets: SyncQuerySubset[]): SyncQuerySubset[];
+/** True when every record selected by `narrow` is also selected by `broad`. */
+declare function querySubsetContains(broad: SyncQuerySubset[], narrow: SyncQuerySubset[]): boolean;
+
+/**
+ * The server-stored, passphrase-wrapped key record (ENC-1, decision D4b; format 2 since
+ * the final RC red team, RT-95/RT-96/RT-97/RT-104).
+ *
+ * Key hierarchy of one keyring ("ring"):
+ *
+ *   passphrase --PBKDF2-SHA256(salt, iterations)--> KEK
+ *   KEK --AES-GCM--> master key (random 256 bits, the ring's secret)
+ *   recovery public key --ECDH P-256 + HKDF + AES-GCM--> master key (optional)
+ *   master key --HKDF "data-key-wrap"--> wrapping key --AES-GCM--> data key v1, v2, ...
+ *   master key --HKDF "record-mac"--> MAC key --HMAC-SHA256--> `mac` over the whole record
+ *
+ * The MAC covers every field except itself (format, keyring, ring id, revision, current
+ * version, KDF parameters, the master wrap, every data-key wrap, the recovery block), so
+ * a server cannot add or swap a recovery key, relabel or drop a version, or serve
+ * another record under the same revision without the device noticing. Only a holder of
+ * the master key (the passphrase, a device that opened the ring, or the recovery key)
+ * can write a record devices accept. The server stores the record opaquely: it never
+ * sees the passphrase, the KEK, the master key or a data key.
+ *
+ * Shared by the client keyring (which creates, opens and authenticates records) and the
+ * sync server (which validates their structure and stores them with compare-and-set).
+ */
+/** Current record format. Format 1 (beta.13 release candidates only) is not read. */
+declare const KEY_RECORD_FORMAT: 2;
+/** Name of the default keyring (one per user). */
+declare const DEFAULT_KEYRING = "default";
+/** Maximum serialized size of a key record the server accepts. */
+declare const MAX_KEY_RECORD_BYTES: number;
+/**
+ * Maximum PBKDF2 iterations a device accepts. A record above it would make an unlock
+ * never finish (the floor is the app's own `kdfIterations`).
+ */
+declare const MAX_KDF_ITERATIONS = 10000000;
+/** Recovery wrap algorithm of format 2. */
+declare const RECOVERY_ALGORITHM: "ECDH-P256+HKDF-SHA256+AES-GCM";
+/** Key-derivation parameters of a record's passphrase KEK. */
+interface KeyRecordKdf {
+    name: 'PBKDF2';
+    hash: 'SHA-256';
+    /** PBKDF2 iteration count (600,000 by default). */
+    iterations: number;
+    /** Base64 random 32-byte salt, generated per passphrase. */
+    salt: string;
+}
+/** The ring's master key, wrapped by the passphrase KEK (AES-256-GCM). */
+interface WrappedMasterKey {
+    /** Base64 12-byte AES-GCM IV. */
+    iv: string;
+    /** Base64 AES-GCM ciphertext of the 32-byte master key (with tag: 48 bytes). */
+    wrappedKey: string;
+}
+/** One data key version, wrapped by the master key's wrapping key. */
+interface WrappedDataKey {
+    /** Key version (1, 2, ...) in this ring. */
+    keyVersion: number;
+    /** Random key id: the envelope's `keyId`. Never derived from key material. */
+    keyId: string;
+    /** Base64 12-byte AES-GCM IV of the wrap. */
+    iv: string;
+    /** Base64 AES-GCM wrap of the raw 32-byte data key (ciphertext and tag). */
+    wrappedKey: string;
+}
+/**
+ * Optional recovery: the master key, wrapped to a recovery public key (ephemeral-static
+ * ECDH P-256, HKDF-SHA256 over the shared secret and both public keys, AES-256-GCM). The
+ * private half is the user's recovery key; it opens the master key, hence every data key.
+ */
+interface KeyRecordRecovery {
+    alg: typeof RECOVERY_ALGORITHM;
+    /** Recovery public key (JWK x/y, base64url). */
+    publicKey: {
+        x: string;
+        y: string;
+    };
+    /** Ephemeral public key of the wrap (JWK x/y, base64url). */
+    ephemeralPublicKey: {
+        x: string;
+        y: string;
+    };
+    iv: string;
+    wrappedKey: string;
+}
+/**
+ * The record the sync server stores per (user, keyring). Opaque to the server apart
+ * from its structure: it cannot unwrap any key or forge the MAC.
+ */
+interface WrappedKeyRecord {
+    format: typeof KEY_RECORD_FORMAT;
+    keyring: string;
+    /** Random id of this ring (`r-` and 32 hex digits). Two rings of one keyring are a fork. */
+    ringId: string;
+    /** Compare-and-set counter: grows on every write; devices never accept a lower one. */
+    revision: number;
+    /** The key version new operations are encrypted with (the highest one). */
+    currentVersion: number;
+    kdf: KeyRecordKdf;
+    master: WrappedMasterKey;
+    /** Every key version ever created. Never shrinks: old history must stay readable. */
+    keys: WrappedDataKey[];
+    recovery?: KeyRecordRecovery;
+    /**
+     * Ids (`m-` and 32 hex digits) of master keys a passphrase change retired (RT-107).
+     * Append-only. A device that authenticated a record listing them refuses every later
+     * record authenticated only by one of them, however it was opened (held master key,
+     * a stale configured passphrase, the old passphrase typed again). Absent until the
+     * first passphrase change.
+     */
+    retiredMasters?: string[];
+    /** Base64 HMAC-SHA256 of every other field (see {@link keyRecordMacInput}). */
+    mac: string;
+}
+/** Result of a structural validation. */
+type KeyRecordValidation = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Structural validation of a key record (server and client). It does not and cannot
+ * check the MAC or that the wraps open: only a holder of the master key can.
+ *
+ * @param value - A decoded record
+ * @param keyring - The keyring the record must belong to
+ */
+declare function validateKeyRecord(value: unknown, keyring: string): KeyRecordValidation;
+/**
+ * Whether `next` may replace `previous` (the server's write rule): the revision grows,
+ * the ring id stays, and every key version of `previous` is still present under the
+ * same key id, so no history becomes unreadable. Wraps may change (a passphrase change
+ * re-wraps every version). A first record (or one re-uploaded after the server lost
+ * it) may carry any revision: devices pin the highest revision they accepted, so a
+ * restore must keep the revision it had.
+ *
+ * @param previous - The stored record, or null when none exists
+ * @param next - The proposed record
+ */
+declare function isKeyRecordSuccessor(previous: WrappedKeyRecord | null, next: WrappedKeyRecord): KeyRecordValidation;
+/** Whether a keyring name is acceptable. */
+declare function isValidKeyringName(value: unknown): value is string;
+/** Whether a value is a key id (`k2-` and 32 hex digits). */
+declare function isKeyId(value: unknown): value is string;
+
+/**
+ * Key-distribution side channel of the sync protocol (ENC-1, D4b). Accepted only after
+ * a successful handshake. The server answers for the session's own principal: a
+ * message never names a user, so no session can read or write another user's record.
+ * JSON on every wire format (the records are small and rare).
+ */
+/** Client -> server: fetch the session principal's record of one keyring. */
+interface EncryptionKeyRequestMessage {
+    type: 'encryption-key-request';
+    messageId: string;
+    /** Correlates the response. */
+    requestId: string;
+    keyring: string;
+}
+/** Client -> server: write the record with compare-and-set on its revision. */
+interface EncryptionKeyPutMessage {
+    type: 'encryption-key-put';
+    messageId: string;
+    requestId: string;
+    keyring: string;
+    /** The full new record; its revision must be `expectedRevision + 1`. */
+    record: WrappedKeyRecord;
+    /** The revision being replaced (0: create). */
+    expectedRevision: number;
+}
+/** Status of a key-service response. */
+type EncryptionKeyResponseStatus = 'ok' | 'conflict' | 'forbidden' | 'invalid' | 'unsupported' | 'throttled';
+/**
+ * Server -> client: the answer to a request or put (with `requestId`), or an
+ * unsolicited push of a record another device of the same principal wrote (without).
+ */
+interface EncryptionKeyResponseMessage {
+    type: 'encryption-key-response';
+    messageId: string;
+    requestId?: string;
+    keyring: string;
+    status: EncryptionKeyResponseStatus;
+    /** The current record (null when none exists, or on refusal). */
+    record: WrappedKeyRecord | null;
+    /** Human-readable reason for a refusal. */
+    message?: string;
+    /**
+     * With `record: null`: key ids the server's stored operations of this owner are
+     * encrypted with (a sample, RT-104). Non-empty means encrypted history exists, so
+     * the record was lost: a new device waits for one that holds the ring.
+     */
+    knownKeyIds?: string[];
+}
+/** Every key-distribution message. */
+type EncryptionKeyMessage = EncryptionKeyRequestMessage | EncryptionKeyPutMessage | EncryptionKeyResponseMessage;
+/**
+ * Structural guard of the key-distribution messages (records are validated in full
+ * by the receiver).
+ */
+declare function isEncryptionKeyMessage(value: unknown): value is EncryptionKeyMessage;
+
+type WireFormat = 'json' | 'protobuf';
+/**
+ * Wire-format operation. Plain object (no Map) for JSON serialization.
+ * Maps 1:1 with Operation, but uses Record instead of Map for version vectors.
+ */
+interface SerializedOperation {
+    id: string;
+    nodeId: string;
+    type: OperationType;
+    collection: string;
+    recordId: string;
+    data: Record<string, unknown> | null;
+    previousData: Record<string, unknown> | null;
+    timestamp: HLCTimestamp;
+    sequenceNumber: number;
+    causalDeps: string[];
+    schemaVersion: number;
+    /** Atomic operation intents, present only when atomic ops were used. */
+    atomicOps?: Record<string, AtomicOp>;
+    /** Groups this operation with others in an atomic transaction. */
+    transactionId?: string;
+    /** Human-readable name for the mutation group. For DevTools display. */
+    mutationName?: string;
+    /** Per-field versions of a server scope-entry insert (RT-27). Server-authored only. */
+    fieldVersions?: Record<string, HLCTimestamp>;
+    /**
+     * Content-hash version of `id` (CORE-1, protocol v2). Absent means 1. Protobuf
+     * operation field 14.
+     */
+    hashVersion?: 1 | 2;
+    /**
+     * Serialized fold state of a server scope-entry operation (W7). Server-authored
+     * only: the server strips it from device uploads. Protobuf operation field 15.
+     */
+    foldState?: string;
+    /**
+     * End-to-end encryption envelope v2 (W9). `data` is then null or holds only the
+     * documented cleartext scope fields. Protobuf operation field 16 (JSON).
+     */
+    encrypted?: EncryptedOperationEnvelope;
+}
+/**
+ * Handshake message sent by client to initiate sync.
+ */
+interface HandshakeMessage {
+    type: 'handshake';
+    messageId: string;
+    nodeId: string;
+    /** Version vector as plain object (nodeId -> sequence number) */
+    versionVector: Record<string, number>;
+    schemaVersion: number;
+    authToken?: string;
+    supportedWireFormats?: WireFormat[];
+    /** Per-collection sync scope filters. Limits which records are synced to this client. */
+    syncScope?: Record<string, Record<string, unknown>>;
+    /** Base64url-encoded delta cursor for resuming paginated initial sync */
+    deltaCursor?: string;
+    /** Live query filters that further narrow synced data within auth/schema scope */
+    syncQueries?: SyncQuerySubset[];
+    /**
+     * The client's persisted delivery watermark: the highest server delivery sequence
+     * up to which it has contiguously applied every in-scope operation. Omitted (or 0)
+     * on first sync. When present, the server resumes the gap-free server->client
+     * stream from just after it, superseding the version-vector delta and the resume
+     * cursor for the server->client direction. Optional, so old servers ignore it.
+     */
+    lastDeliverySequence?: number;
+    /**
+     * SYNC-11: canonical key (`scopeViewKey`) of the downlink scope the server accepted at
+     * this client's last handshake, when it differs from `syncScope`. A server that
+     * resolves a scope with the same key resumes the delivery stream from
+     * `acceptedScopeWatermark` instead of restarting it from 0. Optional; old servers
+     * ignore it.
+     */
+    acceptedScopeKey?: string;
+    /** The client's delivery watermark for the view named by `acceptedScopeKey`. */
+    acceptedScopeWatermark?: number;
+    /** Opt in to client-local removal when records leave the accepted downlink view. */
+    scopeExitPolicy?: 'retain' | 'retract';
+    /**
+     * The per-device secret the server issued at this node id's first claim
+     * (`HandshakeResponseMessage.nodeToken`). An anonymous principal must present it
+     * to reconnect with its node id, so another anonymous client cannot take the node
+     * over (RT-12). Stored by the client next to its node id; never sent elsewhere.
+     */
+    nodeToken?: string;
+    /**
+     * Set by a client transport that understands `heartbeat` messages (LMS #12). Only
+     * then does the server send them, so an older client never receives a message type
+     * it cannot decode. Old servers ignore it.
+     */
+    supportsHeartbeat?: boolean;
+    /**
+     * Capability (RT-37): this client reserves each operation's sequence number inside
+     * the same local transaction that writes the operation, so it never puts two
+     * different operations under one `(nodeId, sequenceNumber)`. Only for such a client
+     * does the server refuse a second, different operation under a held sequence
+     * (`SEQUENCE_CONFLICT`). A client that omits it (Kora <= beta.12, which could give
+     * two concurrent transactions one number) is served as legacy: such a pair is
+     * stored, both operations are delivered, and a warning is logged. Old servers
+     * ignore it. Protobuf field 45.
+     */
+    sequenceReservation?: boolean;
+    /**
+     * Sync protocol version the client speaks (`SYNC_PROTOCOL_VERSION`). Absent means 1
+     * (Kora <= beta.12). A protocol-2 client sends hash-version-2 operation ids, the
+     * encryption envelope v2 and always `sequenceReservation`. Protobuf field 47.
+     */
+    protocolVersion?: number;
+}
+/**
+ * Application-level liveness message (LMS #12). A server sends it every
+ * `HandshakeResponseMessage.heartbeatIntervalMs` to a client that set
+ * `HandshakeMessage.supportsHeartbeat`. Browsers cannot see WebSocket ping frames, so
+ * this is how a client notices a half-open connection: no inbound traffic for about
+ * two intervals means the connection is dead. Carries no data; never acknowledged.
+ */
+interface HeartbeatMessage {
+    type: 'heartbeat';
+    messageId: string;
+}
+/**
+ * Server response to a handshake.
+ */
+interface HandshakeResponseMessage {
+    type: 'handshake-response';
+    messageId: string;
+    nodeId: string;
+    versionVector: Record<string, number>;
+    schemaVersion: number;
+    accepted: boolean;
+    rejectReason?: string;
+    /** Inclusive minimum schema version the server accepts (present when rejected for schema mismatch). */
+    supportedSchemaMin?: number;
+    /** Inclusive maximum schema version the server accepts (present when rejected for schema mismatch). */
+    supportedSchemaMax?: number;
+    selectedWireFormat?: WireFormat;
+    /** The server-accepted per-collection sync scope. Confirms what data will be synced. */
+    acceptedScope?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative scope for records delivered to this client. */
+    acceptedDownlinkScopes?: Record<string, Record<string, unknown>>;
+    /** Server-authoritative scope for operations uploaded by this client. */
+    acceptedUplinkScopes?: Record<string, Record<string, unknown>>;
+    /** Server wall-clock time (ms since epoch) at response creation. Lets clients measure their own clock skew. */
+    serverTime?: number;
+    /**
+     * Whether the server persists blob bytes centrally. When true, a client
+     * automatically uploads the bytes behind its `blob` fields so they remain
+     * available to other devices even after the authoring device goes offline.
+     */
+    blobStorageEnabled?: boolean;
+    /**
+     * The server's highest delivery sequence at handshake time. A client whose
+     * persisted delivery watermark exceeds this (the server's operation log was rolled
+     * back, for example by a backup restore) resets its watermark to 0 so it resyncs
+     * from the beginning instead of sitting above a frontier that no longer exists.
+     */
+    serverMaxDeliverySequence?: number;
+    /**
+     * A per-device secret issued when this handshake made the first claim of the node
+     * id for an anonymous principal (RT-12). The client stores it next to its node id
+     * and presents it in every later handshake (`HandshakeMessage.nodeToken`).
+     *
+     * The claim stays provisional until the client proves it saved the token, by
+     * presenting it in a later handshake or by echoing it in an acknowledgment of this
+     * response (`AcknowledgmentMessage.nodeToken`) right after persisting it (RT-21).
+     */
+    nodeToken?: string;
+    /**
+     * Peer-relay servers (no central blob storage) set this to ask the client to push
+     * the bytes behind its blob references anyway: the server verifies them against
+     * their hash, records possession, and drops them (RT-23).
+     */
+    blobPossessionProof?: boolean;
+    /**
+     * Interval of the server's `heartbeat` messages, in ms, present when the client set
+     * `supportsHeartbeat` and the server sends them (LMS #12).
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Sync protocol version the server speaks. Absent means 1 (a beta.12-era server).
+     * Protobuf field 47.
+     */
+    protocolVersion?: number;
+    /**
+     * Explicit authoritative node ids (RT-75): legacy server node ids from before protocol
+     * 2 and extras configured on the server store. Every `kora:server:` node id is
+     * authoritative by its prefix and is not listed. Only operations of authoritative
+     * nodes may carry server-authored metadata (`fieldVersions`, `foldState`); the client
+     * keeps the union of every id it learns (`SyncStatePersistence.saveAuthoritativeNodeIds`).
+     * Absent from older servers. Protobuf field 46 (repeated).
+     */
+    authoritativeNodeIds?: string[];
+    /**
+     * Explicit authoritative node ids the deployment revoked (RT-81, server config
+     * `revokedAuthoritativeNodeIds`). A client removes them from the authority union it
+     * keeps, never learns them again, and re-folds the affected records; the server
+     * never accepts them as device node ids. Absent when nothing was revoked, and from
+     * older servers. Protobuf field 48 (repeated).
+     */
+    revokedAuthoritativeNodeIds?: string[];
+}
+/**
+ * Batch of operations sent during delta exchange or streaming.
+ */
+interface OperationBatchMessage {
+    type: 'operation-batch';
+    messageId: string;
+    operations: SerializedOperation[];
+    /** Client-local authorization removals; these are never domain delete operations. */
+    retractions?: ScopeRetraction[];
+    /** True if this is the last batch in the delta exchange phase */
+    isFinal: boolean;
+    /** Index of this batch (0-based) for ordering */
+    batchIndex: number;
+    /** Base64url-encoded cursor marking the last operation in this batch */
+    cursor?: string;
+    /** Total batches in this delta exchange (for progress reporting) */
+    totalBatches?: number;
+    /**
+     * Delivery-watermark chaining (server->client). `baseDeliverySequence` is the
+     * delivery sequence the client must already hold for this batch to apply in order
+     * (it equals the previous batch's `maxDeliverySequence`, or the client's reported
+     * watermark for the first batch after a handshake). `maxDeliverySequence` is the
+     * highest delivery sequence carried by this batch. The client applies the batch
+     * only when its watermark equals `baseDeliverySequence`, then advances the
+     * watermark to `maxDeliverySequence`. A dropped batch breaks the chain and stalls
+     * the watermark, so the reconnect resend recovers it. Present only on batches the
+     * server sends as part of the delivery stream; absent on legacy version-vector
+     * batches.
+     */
+    baseDeliverySequence?: number;
+    maxDeliverySequence?: number;
+}
+interface ScopeRetraction {
+    collection: string;
+    recordId: string;
+}
+/**
+ * Acknowledgment of a received message.
+ */
+interface AcknowledgmentMessage {
+    type: 'acknowledgment';
+    messageId: string;
+    acknowledgedMessageId: string;
+    lastSequenceNumber: number;
+    /**
+     * The acknowledged batch's `maxDeliverySequence`, echoed so the server can advance
+     * this client's durable delivery watermark. Present only when acking a delivery-
+     * stream batch. `lastSequenceNumber` stays for existing per-node behavior.
+     */
+    deliverySequence?: number;
+    /**
+     * Claim confirmation (RT-21): the node token from a handshake response, echoed
+     * once the client has persisted it, so the server makes the provisional claim of
+     * the node id permanent. Sent with `acknowledgedMessageId` set to the response id.
+     */
+    nodeToken?: string;
+}
+/**
+ * Error message from the server or client.
+ */
+interface ErrorMessage {
+    type: 'error';
+    messageId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+}
+/**
+ * Server-to-client rejection of ONE specific operation the client submitted.
+ *
+ * Unlike {@link ErrorMessage}, which is connection-level, this is tied to an
+ * `operationId` so the client can divert exactly that operation out of its
+ * pending outbound queue and into a durable rejected-operations store — kept and
+ * explainable rather than silently retried forever or lost on the batch ack. The
+ * operation never entered the server's authoritative log, so no other replica
+ * ever sees it; the submitter is told so its optimistic local copy can be
+ * reconciled (rolled back or resubmitted) by the app.
+ */
+interface OperationRejectedMessage {
+    type: 'operation-rejected';
+    messageId: string;
+    /** Content-addressed id of the rejected operation. */
+    operationId: string;
+    /** Collection the rejected operation targeted (for app routing / display). */
+    collection: string;
+    /** Record the rejected operation targeted. */
+    recordId: string;
+    /** Stable, machine-readable reason code. */
+    code: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Whether resubmitting the identical operation may later succeed. */
+    retriable: boolean;
+}
+/**
+ * Awareness state for a single client (cursor position, user info).
+ * Wire-format representation for JSON transport.
+ * Ephemeral -- not persisted, only shared with connected peers.
+ */
+interface AwarenessStateWire {
+    user: {
+        name: string;
+        color: string;
+        avatar?: string;
+    };
+    cursor?: {
+        collection: string;
+        recordId: string;
+        field: string;
+        anchor: number;
+        head: number;
+    };
+}
+/**
+ * Awareness update message. Carries ephemeral presence data (cursors, user info).
+ * Processed separately from operation sync -- never persisted.
+ */
+interface AwarenessUpdateMessage {
+    type: 'awareness-update';
+    messageId: string;
+    /** Client ID of the sender */
+    clientId: number;
+    /** Map of clientId -> state (null means removal) */
+    states: Record<string, AwarenessStateWire | null>;
+}
+/**
+ * Incremental Yjs update for a richtext field. Ephemeral side channel for large documents.
+ * JSON transport only; not persisted on the server operation log.
+ */
+interface YjsDocUpdateMessage {
+    type: 'yjs-doc-update';
+    messageId: string;
+    collection: string;
+    recordId: string;
+    field: string;
+    /** Base64-encoded Yjs update binary */
+    update: string;
+}
+/**
+ * Request for a single blob chunk by content hash. Ephemeral side channel for
+ * out-of-band blob transfer over the sync connection; never persisted in the
+ * operation log (durable state is the BlobRef inside a record's fields).
+ *
+ * Knowing a hash is not a capability: the server serves (from its central store)
+ * or forwards a request only when a live record inside the requester's download
+ * scope references the hash (as a blob, a manifest, or a chunk of one), forwards it
+ * only to peers whose own scope references it, accepts the answer only from a peer
+ * it asked and only when the bytes hash to the requested hash. Any other request
+ * is answered `bytes: null`, exactly like an unknown hash.
+ */
+interface BlobChunkRequestMessage {
+    type: 'blob-chunk-request';
+    messageId: string;
+    /** Correlates the response to this request. */
+    requestId: string;
+    /** SHA-256 hash of the requested chunk. */
+    hash: string;
+}
+/**
+ * Response to a {@link BlobChunkRequestMessage}. Carries the chunk bytes, or
+ * null when the responder does not hold that hash.
+ */
+interface BlobChunkResponseMessage {
+    type: 'blob-chunk-response';
+    messageId: string;
+    /** Echoes the request's `requestId` for correlation. */
+    requestId: string;
+    /** Base64-encoded chunk bytes, or null when the responder does not hold the hash. */
+    bytes: string | null;
+    /**
+     * True when the server refused the request for rate (RT-24), not because the
+     * chunk is missing: retry after `retryAfterMs`. Absent (or false) otherwise.
+     */
+    throttled?: boolean;
+    /** With `throttled`: milliseconds until the request may be retried. */
+    retryAfterMs?: number;
+}
+/**
+ * Unsolicited upload of a blob chunk (or a blob manifest) from a client to the
+ * server, so the server can persist it centrally and serve it to other devices
+ * even after the authoring device disconnects. Content-addressed: the receiver
+ * verifies the bytes hash to `hash`.
+ */
+interface BlobChunkPushMessage {
+    type: 'blob-chunk-push';
+    messageId: string;
+    /** SHA-256 hash of the pushed bytes (a chunk hash or a manifest hash). */
+    hash: string;
+    /** Base64-encoded bytes. */
+    bytes: string;
+}
+/**
+ * Union of all sync protocol messages.
+ */
+type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | OperationRejectedMessage | AwarenessUpdateMessage | YjsDocUpdateMessage | BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage | HeartbeatMessage | EncryptionKeyMessage;
+/**
+ * Check if an unknown value is a valid SyncMessage.
+ */
+declare function isSyncMessage(value: unknown): value is SyncMessage;
+/**
+ * Check if a value is a HandshakeMessage.
+ */
+declare function isHandshakeMessage(value: unknown): value is HandshakeMessage;
+/**
+ * Check if a value is a HandshakeResponseMessage.
+ */
+declare function isHandshakeResponseMessage(value: unknown): value is HandshakeResponseMessage;
+/**
+ * Check if a value is an OperationBatchMessage.
+ */
+declare function isOperationBatchMessage(value: unknown): value is OperationBatchMessage;
+/**
+ * Check if a value is an AcknowledgmentMessage.
+ */
+declare function isAcknowledgmentMessage(value: unknown): value is AcknowledgmentMessage;
+/**
+ * Check if a value is an ErrorMessage.
+ */
+declare function isErrorMessage(value: unknown): value is ErrorMessage;
+/**
+ * Check if a value is an OperationRejectedMessage.
+ */
+declare function isOperationRejectedMessage(value: unknown): value is OperationRejectedMessage;
+/**
+ * Check if a value is an AwarenessUpdateMessage.
+ */
+declare function isAwarenessUpdateMessage(value: unknown): value is AwarenessUpdateMessage;
+/**
+ * Check if a value is a YjsDocUpdateMessage.
+ */
+declare function isYjsDocUpdateMessage(value: unknown): value is YjsDocUpdateMessage;
+/**
+ * Check if a value is a BlobChunkRequestMessage.
+ */
+declare function isBlobChunkRequestMessage(value: unknown): value is BlobChunkRequestMessage;
+/**
+ * Check if a value is a BlobChunkResponseMessage.
+ */
+declare function isBlobChunkResponseMessage(value: unknown): value is BlobChunkResponseMessage;
+/**
+ * Check if a value is a BlobChunkPushMessage.
+ */
+declare function isBlobChunkPushMessage(value: unknown): value is BlobChunkPushMessage;
+
+/**
+ * Sync protocol version this build speaks (decision D2: one bump carrying all wire
+ * breaks). Version 2 adds:
+ * - operation ids hashed with content-hash version 2 (CORE-1), with `hashVersion`
+ *   carried on the wire and verified on receive;
+ * - the end-to-end encryption envelope v2 (`op.encrypted`, AES-GCM AAD, ENC-3 and
+ *   NEW-ENC-1);
+ * - the sequence-reservation capability on every handshake (RT-37);
+ * - `authoritativeNodeIds` and server-authored `foldState` (W7).
+ *
+ * A handshake without `protocolVersion` is version 1 (Kora <= beta.12). Servers accept
+ * version-1 clients for one release (beta.13) with a deprecation warning.
+ */
+declare const SYNC_PROTOCOL_VERSION = 2;
+/** Protocol version assumed when a handshake or response does not declare one. */
+declare const LEGACY_SYNC_PROTOCOL_VERSION = 1;
+/** Code of the server's deprecation warning for a version-1 client. */
+declare const PROTOCOL_V1_DEPRECATED = "PROTOCOL_V1_DEPRECATED";
+/** Non-retriable rejection code for an operation whose id is not its content hash. */
+declare const INVALID_OPERATION_ID = "INVALID_OPERATION_ID";
+/**
+ * Non-retriable rejection code for a plaintext operation uploaded to a server that
+ * requires the encryption envelope.
+ */
+declare const PLAINTEXT_REJECTED = "PLAINTEXT_REJECTED";
+/**
+ * The protocol version a handshake (or handshake response) declares.
+ *
+ * @param declared - The message's `protocolVersion`
+ * @returns The declared version, or 1 when absent or malformed
+ */
+declare function declaredProtocolVersion(declared: unknown): number;
+
+/**
+ * Options for transport connection.
+ */
+interface TransportOptions {
+    /** Authentication token sent during connection */
+    authToken?: string;
+    /** Additional headers (for HTTP-based transports) */
+    headers?: Record<string, string>;
+}
+/**
+ * Transport-level error handler.
+ */
+type TransportErrorHandler = (error: Error) => void;
+/**
+ * Transport-level close handler.
+ */
+type TransportCloseHandler = (reason: string) => void;
+/**
+ * Transport-level message handler.
+ */
+type TransportMessageHandler = (message: SyncMessage) => void;
+/**
+ * Abstract transport interface for sync communication.
+ * Implementations can use WebSocket, HTTP, Bluetooth, or any other transport.
+ */
+interface SyncTransport {
+    /** Connect to the sync server at the given URL */
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    /** Disconnect from the server */
+    disconnect(): Promise<void>;
+    /** Send a sync message */
+    send(message: SyncMessage): void;
+    /** Register a handler for incoming messages */
+    onMessage(handler: TransportMessageHandler): void;
+    /** Register a handler for connection close events */
+    onClose(handler: TransportCloseHandler): void;
+    /** Register a handler for transport errors */
+    onError(handler: TransportErrorHandler): void;
+    /** Returns true if the transport is currently connected */
+    isConnected(): boolean;
+}
+
+export { MAX_KDF_ITERATIONS as $, type AcknowledgmentMessage as A, type BlobChunkRequestMessage as B, type EncryptionKeyResponseMessage as C, type DeltaCursor as D, type EncryptedPayload as E, type EncryptionKeyResponseStatus as F, type ErrorMessage as G, type HeldNodeInfo as H, type HandshakeMessage as I, type HandshakeResponseMessage as J, type HeartbeatMessage as K, type HeldReason as L, INVALID_OPERATION_ID as M, InvalidScopeError as N, KEY_RECORD_FORMAT as O, type KeyRecordKdf as P, type QueueStorage as Q, type RejectedOperationStorage as R, type SyncScopeMap as S, type TransportOptions as T, type KeyRecordRecovery as U, type VersionedKey as V, type WireFormat as W, type KeyRecordValidation as X, type YjsDocUpdateMessage as Y, LEGACY_SYNC_PROTOCOL_VERSION as Z, type LocalNodeInfo as _, type ScopeSnapshotOptions as a, MAX_KEY_RECORD_BYTES as a0, MemoryRejectedOperationStorage as a1, type OperationBatchMessage as a2, type OperationRejectedMessage as a3, PLAINTEXT_REJECTED as a4, PROTOCOL_V1_DEPRECATED as a5, SYNC_PROTOCOL_VERSION as a6, SYNC_STATES as a7, SYNC_STATUSES as a8, ScopeViolationError as a9, isValidKeyringName as aA, isYjsDocUpdateMessage as aB, operationMatchesQuerySubsets as aC, querySubsetContains as aD, validateKeyRecord as aE, buildScopeSnapshot as aF, matchesScopePredicate as aG, recordMatchesScopePredicates as aH, type SyncAuthRequest as aa, type SyncEncryptionAlgorithm as ab, type SyncPhase as ac, type SyncScopeContext as ad, type SyncSettlementOptions as ae, type SyncSettlementResult as af, type SyncStatus as ag, type TerminalRejectionRecord as ah, type WrappedDataKey as ai, type WrappedMasterKey as aj, declaredProtocolVersion as ak, dedupeQuerySubsets as al, isAcknowledgmentMessage as am, isAwarenessUpdateMessage as an, isBlobChunkPushMessage as ao, isBlobChunkRequestMessage as ap, isBlobChunkResponseMessage as aq, isEncryptionKeyMessage as ar, isErrorMessage as as, isHandshakeMessage as at, isHandshakeResponseMessage as au, isKeyId as av, isKeyRecordSuccessor as aw, isOperationBatchMessage as ax, isOperationRejectedMessage as ay, isSyncMessage as az, type SyncMessage as b, type SerializedOperation as c, type SyncTransport as d, type TransportMessageHandler as e, type TransportCloseHandler as f, type TransportErrorHandler as g, type BlobChunkResponseMessage as h, type BlobChunkPushMessage as i, type WrappedKeyRecord as j, type SyncEncryptionConfig as k, type SyncState as l, type SyncStatusInfo as m, type SyncConfig as n, type SyncStatePersistence as o, type SyncQuerySubset as p, type QuarantinedOperation as q, type RejectedOperation as r, type ActiveApplyFailure as s, type AdoptionScheduleInfo as t, type AwarenessStateWire as u, type AwarenessUpdateMessage as v, DEFAULT_KEYRING as w, type EncryptionKeyMessage as x, type EncryptionKeyPutMessage as y, type EncryptionKeyRequestMessage as z };