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

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, R as RejectedOperationStorage, m as SyncStatePersistence, n as SyncQuerySubset, o as RejectedOperation } from './transport-iXX0KA_W.js';
-export { A as AcknowledgmentMessage, p as ActiveApplyFailure, q as AwarenessStateWire, r as AwarenessUpdateMessage, E as EncryptedPayload, s as ErrorMessage, H as HandshakeMessage, t as HandshakeResponseMessage, I as InvalidScopeError, M as MemoryRejectedOperationStorage, O as OperationBatchMessage, u as OperationRejectedMessage, v as SYNC_STATES, w as SYNC_STATUSES, x as ScopeViolationError, y as SyncEncryptionAlgorithm, z as SyncPhase, C as SyncScopeContext, F as SyncSettlementOptions, G as SyncSettlementResult, J as SyncStatus, K as dedupeQuerySubsets, L as isAcknowledgmentMessage, N as isAwarenessUpdateMessage, P as isBlobChunkPushMessage, U as isBlobChunkRequestMessage, X as isBlobChunkResponseMessage, Z as isErrorMessage, _ as isHandshakeMessage, $ as isHandshakeResponseMessage, a0 as isOperationBatchMessage, a1 as isOperationRejectedMessage, a2 as isSyncMessage, a3 as isYjsDocUpdateMessage, a4 as operationMatchesQuerySubsets, a5 as querySubsetContains } from './transport-iXX0KA_W.js';
+import { 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-Bemtqwep.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-Bemtqwep.js';
 import * as _korajs_core from '@korajs/core';
-import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
+import { Operation, VersionVector, ApplyResult, OperationTransform, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality, KoraError, SchemaDefinition } from '@korajs/core';
 export { ApplyFailureReason, ApplyResult } from '@korajs/core';
 
 /**
@@ -13,7 +13,8 @@ export { ApplyFailureReason, ApplyResult } from '@korajs/core';
  * - Empty scope for a collection `{}`: no field restrictions, operation is in scope.
  * - Scope has field/value pairs: all must match in the operation's data snapshot.
  *
- * For updates, the snapshot is built by merging `previousData` and `data` (data wins),
+ * 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
@@ -23,9 +24,11 @@ export { ApplyFailureReason, ApplyResult } from '@korajs/core';
  * @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): boolean;
+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.
  *
@@ -73,6 +76,12 @@ interface SyncStore {
      * @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.
@@ -90,11 +99,75 @@ interface SyncStore {
      * @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: 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
@@ -106,6 +179,35 @@ interface SyncStore {
      * @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. */
@@ -154,6 +256,19 @@ declare class JsonMessageSerializer implements MessageSerializer {
 /**
  * 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;
@@ -208,18 +323,49 @@ interface WebSocketTransportOptions {
     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>;
@@ -228,8 +374,20 @@ declare class WebSocketTransport implements SyncTransport {
     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;
@@ -239,6 +397,13 @@ interface HttpLongPollingTransportOptions {
 }
 /**
  * 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;
@@ -255,6 +420,10 @@ declare class HttpLongPollingTransport implements SyncTransport {
     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>;
@@ -265,8 +434,12 @@ declare class HttpLongPollingTransport implements SyncTransport {
     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;
-    private makePollHeaders;
+    /** Accept, bearer credential and (once issued) the session id: sent on every request. */
+    private makeHeaders;
 }
 
 /**
@@ -506,6 +679,9 @@ type BlobChunkChannelMessage = {
     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;
@@ -569,6 +745,122 @@ interface MetricsCollectorConfig {
     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.
  */
@@ -583,31 +875,38 @@ declare class DecryptionError extends SyncError {
     constructor(message: string, context?: Record<string, unknown>);
 }
 /**
- * Encrypts and decrypts operation `data` and `previousData` fields for
- * end-to-end encryption in the sync layer.
+ * End-to-end encryption of operations, envelope v2 (protocol v2; ENC-3, NEW-ENC-1).
  *
- * **Design principles:**
- * - Only `data` and `previousData` are encrypted. Metadata (id, nodeId,
- *   collection, timestamps, causalDeps, etc.) stays in cleartext so the
- *   server can route, deduplicate, and order operations.
- * - Each field encryption uses a unique random IV (12 bytes for AES-GCM),
- *   ensuring that encrypting the same data twice produces different ciphertext.
- * - Key rotation is supported via versioned keys. The key version is embedded
- *   in the {@link EncryptedPayload} so the decryptor can select the correct key.
- * - Unencrypted fields pass through during decryption (backward compatibility).
+ * **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.
  *
- * @example
- * ```typescript
- * const encryptor = await SyncEncryptor.create({
- *   enabled: true,
- *   key: 'user-passphrase'
- * })
+ * **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.
  *
- * // Encrypt before sending
- * const encrypted = await encryptor.encryptOperation(operation)
+ * **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.
  *
- * // Decrypt after receiving
- * const decrypted = await encryptor.decryptOperation(encrypted)
+ * @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 {
@@ -618,23 +917,28 @@ declare class SyncEncryptor {
     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 {@link SyncEncryptionConfig}.
+     * Creates a SyncEncryptor from a passphrase and an explicit, shared salt.
      *
-     * Derives the encryption key from the passphrase using PBKDF2. The key
-     * derivation is async because it uses the Web Crypto API.
+     * 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 passphrase
-     * @param salt - Optional salt for deterministic key derivation (mainly for testing).
-     *              If omitted, a random salt is generated.
-     * @param iterations - Optional PBKDF2 iteration count. Defaults to the
-     *              production-strength value. Lower it only in tests.
+     * @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
+     * @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>;
+    static create(config: SyncEncryptionConfig, salt: Uint8Array, iterations?: number): Promise<SyncEncryptor>;
     /**
      * Creates a SyncEncryptor from pre-derived versioned keys.
      *
@@ -642,10 +946,11 @@ declare class SyncEncryptor {
      * 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[]): SyncEncryptor;
+    static fromKeys(versionedKeys: VersionedKey[], options?: EncryptorOptions): SyncEncryptor;
     /**
      * Add a new key version for key rotation.
      *
@@ -657,57 +962,55 @@ declare class SyncEncryptor {
      * @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;
     /**
-     * Encrypt an operation's `data` and `previousData` fields.
+     * 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).
      *
-     * Returns a new Operation with encrypted field values. The original
-     * operation is not mutated (operations are immutable).
+     * @param version - Key version (defaults to the current one)
+     */
+    getKeyId(version?: number): Promise<string>;
+    /**
+     * Seal an operation into an envelope v2.
      *
-     * Fields that are null (e.g., delete operations) remain null.
+     * 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 operation to encrypt
-     * @returns A new operation with encrypted data fields
+     * @param operation - The plaintext operation
+     * @returns The sealed operation
      * @throws {EncryptionError} If encryption fails
      */
     encryptOperation(operation: Operation): Promise<Operation>;
     /**
-     * Decrypt an operation's `data` and `previousData` fields.
-     *
-     * Returns a new Operation with the original field values restored.
-     * The original operation is not mutated.
+     * Open an envelope v2 and restore the plaintext `data`, `previousData` and
+     * `atomicOps`. The returned operation has no `encrypted` member.
      *
-     * If a field is null or not encrypted (no marker), it passes through unchanged.
-     * This enables mixed plaintext/encrypted operations during migration.
-     *
-     * @param operation - The operation to decrypt
-     * @returns A new operation with decrypted data fields
-     * @throws {DecryptionError} If decryption fails (wrong key, tampered data, unsupported version)
+     * @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>;
     /**
-     * Encrypt a serialized operation's `data` and `previousData` fields.
-     *
-     * Same as {@link encryptOperation} but works with the wire-format
-     * {@link SerializedOperation} type used by the serializer.
+     * Same as {@link encryptOperation} for the wire form.
      *
      * @param serialized - The serialized operation to encrypt
-     * @returns A new serialized operation with encrypted data fields
-     * @throws {EncryptionError} If encryption fails
+     * @returns The sealed serialized operation
      */
     encryptSerializedOperation(serialized: SerializedOperation): Promise<SerializedOperation>;
     /**
-     * Decrypt a serialized operation's `data` and `previousData` fields.
-     *
-     * Same as {@link decryptOperation} but works with the wire-format
-     * {@link SerializedOperation} type used by the serializer.
+     * Same as {@link decryptOperation} for the wire form.
      *
      * @param serialized - The serialized operation to decrypt
-     * @returns A new serialized operation with decrypted data fields
-     * @throws {DecryptionError} If decryption fails
+     * @returns The plaintext serialized operation
      */
     decryptSerializedOperation(serialized: SerializedOperation): Promise<SerializedOperation>;
     /**
@@ -725,23 +1028,425 @@ declare class SyncEncryptor {
      */
     decryptBatch(operations: Operation[]): Promise<Operation[]>;
     /**
-     * Check if a field value contains an encrypted payload.
+     * 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
-     * @returns true if the field contains an encrypted payload
      */
     static isEncryptedPayload(field: Record<string, unknown> | null): boolean;
-    private encryptField;
-    private decryptField;
+    /**
+     * 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 an encrypted payload.
+ * 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 an encrypted payload
+ * @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;
@@ -801,6 +1506,12 @@ declare class OutboundQueue {
     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);
@@ -814,13 +1525,25 @@ declare class OutboundQueue {
      * 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): OutboundBatch | null;
+    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.
      */
@@ -831,7 +1554,33 @@ declare class OutboundQueue {
      * queue for retry. This is required when the server accepts a prefix but rejects a
      * later operation retriably (for example a stale-scope push after auth changed).
      */
-    acknowledgeThrough(batchId: string, lastSequenceNumber: number): Promise<void>;
+    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.
@@ -879,6 +1628,8 @@ declare class OutboundQueue {
      * 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.
@@ -913,6 +1664,14 @@ interface SyncEngineOptions {
      * 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). */
@@ -947,6 +1706,8 @@ interface SyncDiagnostics {
  */
 declare class SyncEngine {
     private state;
+    /** Listeners registered through {@link onStateChange}. */
+    private readonly stateListeners;
     private readonly transport;
     private readonly store;
     private readonly config;
@@ -956,28 +1717,98 @@ declare class SyncEngine {
     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;
-    private currentBatch;
-    private currentBatchRequiresPartialAck;
+    /**
+     * 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;
@@ -985,11 +1816,84 @@ declare class SyncEngine {
     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;
-    /** Op ids sent during handshake delta — removed from outbound queue to avoid duplicate send */
-    private deltaSentOpIds;
     /** Outbound delta batch message IDs awaiting ACK when strictHandshake is enabled */
     private pendingDeltaBatchAcks;
     /**
@@ -998,10 +1902,25 @@ declare class SyncEngine {
      * 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;
@@ -1024,6 +1943,8 @@ declare class SyncEngine {
      * 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);
@@ -1037,13 +1958,44 @@ declare class SyncEngine {
      */
     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.
      *
-     * Operations outside the configured sync scope are silently skipped
-     * because they should remain local-only and not be sent to the server.
+     * 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>;
     /**
@@ -1056,7 +2008,23 @@ declare class SyncEngine {
     /**
      * 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.
@@ -1068,6 +2036,18 @@ declare class SyncEngine {
      * 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;
     /**
@@ -1086,9 +2066,16 @@ declare class SyncEngine {
      */
     recordConflict(): void;
     /**
-     * Count of local operations not yet covered by the last acked server vector (op-log source of truth).
+     * 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
@@ -1097,6 +2084,35 @@ declare class SyncEngine {
     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
@@ -1113,6 +2129,15 @@ declare class SyncEngine {
      * 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).
      */
@@ -1137,6 +2162,16 @@ declare class SyncEngine {
      * 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
@@ -1169,6 +2204,8 @@ declare class SyncEngine {
      * 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.
@@ -1203,13 +2240,50 @@ declare class SyncEngine {
      */
     isBlobStorageEnabled(): boolean;
     /**
-     * Upload a blob chunk (or manifest) to the server for central persistence.
-     * A no-op unless connected and the server advertised blob storage.
+     * 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.
@@ -1219,6 +2293,41 @@ declare class SyncEngine {
      */
     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;
+    /** 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
@@ -1227,12 +2336,123 @@ declare class SyncEngine {
      * 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;
-    private collectDelta;
+    /** 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;
     /**
@@ -1242,6 +2462,34 @@ declare class SyncEngine {
      * 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
@@ -1256,36 +2504,243 @@ declare class SyncEngine {
     clearRejectedOperations(operationIds: string[]): Promise<void>;
     private checkDeltaComplete;
     /**
-     * Effective server vector: persisted last-ack merged with live handshake remote vector.
+     * 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 getEffectiveServerVector;
+    private scanOwnLog;
+    private persistOwnPrefix;
     private persistLastAckedServerVector;
-    private advanceLastAckedForLocalNode;
     /**
-     * Refresh cached unsynced count from op log vs effective server vector.
+     * 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;
     /**
-     * Returns operations the server has not yet acknowledged (op-log source of truth).
+     * This device's operations not yet stored on the server (queued or in flight).
      */
     getPendingSyncOperations(): Promise<Operation[]>;
     /**
-     * Hydrate the outbound queue from unsynced ops in the op log (deduped by operation id).
+     * 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;
-    private operationAllowedForSync;
-    private matchesScopeAndSubsets;
+    /**
+     * 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 filterAllowedForSync;
     private persistDeltaCursor;
     private persistDeliveryWatermark;
     private scheduleQuerySubsetReconnect;
@@ -1366,6 +2821,13 @@ interface ReconnectionConfig {
     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). */
@@ -1375,6 +2837,10 @@ interface ReconnectionConfig {
  * 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;
@@ -1382,20 +2848,44 @@ declare class ReconnectionManager {
     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.
      *
-     * @param onReconnect - Called on each attempt. Return `true` if reconnection succeeded.
+     * 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.
@@ -1406,7 +2896,9 @@ declare class ReconnectionManager {
      */
     stop(): void;
     /**
-     * Reset the attempt counter. Call after a successful manual reconnection.
+     * 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;
     /**
@@ -1422,6 +2914,7 @@ declare class ReconnectionManager {
      * Current attempt number (for testing).
      */
     getAttemptCount(): number;
+    private clearStableTimer;
     private wait;
 }
 
@@ -1438,6 +2931,42 @@ declare function decodeYjsUpdate(encoded: string): Uint8Array;
  */
 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.
  */
@@ -1529,4 +3058,4 @@ declare function getRemoteAwarenessStates(awareness: AwarenessManager): Awarenes
  */
 declare function subscribeRemoteAwarenessStates(awareness: AwarenessManager, listener: (states: AwarenessState[]) => void): () => void;
 
-export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, BlobChunkChannel, type BlobChunkChannelMessage, type BlobChunkChannelOptions, BlobChunkPushMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RejectedOperation, RejectedOperationStorage, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };
+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 };