@korajs/store 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, d as SubscriptionCallback, W as WhereClause, e as OrderByDirection, L as LocalMutationHandler, f as StoreConfig, A as ApplyRemoteOptions, g as MaterializedRowSnapshot, h as RowVersionState } from './types-BslDOTk0.js';
-export { M as MigrationPlan, i as OrderByClause, j as StorageFallbackReason, a as StorageOpenState, k as StoreIsolation, T as Transaction, l as TransactionBufferedEntry, m as TransactionCommitBatch, n as TransactionCommitResult, o as WhereOperators } from './types-BslDOTk0.js';
-import { Operation, KoraError, VersionVector, SchemaDefinition, HLCTimestamp, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraBytesValue, KoraEvent, BlobRefMetadata, BlobRef } from '@korajs/core';
+import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, d as QuerySubscriptionError, e as SubscriptionCallback, f as SubscribeOptions, W as WhereClause, g as OrderByDirection, h as StoreConfig, A as ApplyRemoteOptions, L as LocalMutationHandler, i as MaterializedRowSnapshot, j as RowVersionState } from './types-Dh-xyUjP.js';
+export { M as MigrationPlan, k as OrderByClause, l as QueryErrorPhase, m as StorageFallbackReason, a as StorageOpenState, n as StoreIsolation, T as Transaction, o as WhereOperators } from './types-Dh-xyUjP.js';
+import { Operation, KoraError, VersionVector, SchemaDefinition, HLCTimestamp, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, SecretKeyProvider, OperationLog, OperationTransform, ApplyResult, FoldState, KoraEventEmitter, StateMachineDefinition, KoraBytesValue, KoraEvent, BlobRefMetadata, BlobRef } from '@korajs/core';
 export { ApplyResult } from '@korajs/core';
-import { R as RelationEnforcer, L as LocalMutationContext } from './types-BOO9EPt1.js';
-export { C as Collection } from './types-BOO9EPt1.js';
+import { R as RelationEnforcer, j as LocalDeleteHook, k as RecordFolder, L as LocalMutationContext, A as AdoptionSchedule, T as TerminalRejection, l as LocalNodeRecord } from './sql-builder-D5UMzHEo.js';
+export { C as Collection, P as ParkedAdoption, V as VIRTUAL_TIMESTAMP_FIELDS, m as VIRTUAL_TIMESTAMP_FIELD_NAMES, n as VirtualTimestampField, o as mergeYjsUpdates } from './sql-builder-D5UMzHEo.js';
 import * as yjs from 'yjs';
 import { C as ContentAddressedBlobStore, M as MemoryBlobStore } from './content-addressed-blob-store-Dcj3SB9r.js';
 export { B as BlobIntegrityError } from './content-addressed-blob-store-Dcj3SB9r.js';
@@ -53,6 +53,34 @@ declare class OptimisticLockError extends KoraError {
 declare class AdapterError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
+/**
+ * Thrown when a write reaches a storage adapter that could not obtain durable
+ * storage (it opened, or was promoted to leader, on a non-persistent in-memory
+ * database). Kora refuses such writes instead of accepting data that would be
+ * lost on reload. Reads still work.
+ *
+ * Fix: close other tabs or apps using the same origin's OPFS storage and reopen,
+ * or opt in explicitly with `allowNonDurable: true` if in-memory storage is
+ * acceptable for this app.
+ */
+declare class StorageDurabilityError extends KoraError {
+    constructor(dbName: string, phase: 'open' | 'promotion', reason: string);
+}
+/**
+ * Thrown when the store opens a database a NEWER build of the app already migrated: its
+ * stored schema version is above this code's `schema.version` (RT-109). Running older
+ * code against it would write operations of the old schema into the new one, or fail
+ * part-way, so the store refuses before changing anything and emits `store:schema-ahead`.
+ *
+ * Fix: run the newer build (reload while online, or accept the app's update prompt).
+ * Never lower `schema.version` in a deployed app.
+ */
+declare class SchemaVersionAheadError extends KoraError {
+    readonly dbName: string;
+    readonly storedVersion: number;
+    readonly codeVersion: number;
+    constructor(dbName: string, storedVersion: number, codeVersion: number);
+}
 /**
  * Thrown when an operation is attempted on a store that has not been opened.
  */
@@ -78,7 +106,50 @@ declare class WorkerTimeoutError extends KoraError {
  * leader instead of waiting out the full RPC timeout.
  */
 declare class NoLeaderError extends KoraError {
-    constructor(operation: string);
+    constructor(operation: string, message?: string, code?: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown to a follower tab's pending storage requests when the leader tab that
+ * was answering stopped sending heartbeats (hung, frozen, or suspended). The
+ * request may or may not have been applied: retry it with the same `requestId`
+ * (in the error context) and the leader de-duplicates it. Retriable.
+ */
+declare class LeaderUnresponsiveError extends NoLeaderError {
+    constructor(operation: string, silentMs: number, requestId: string);
+}
+/**
+ * Thrown to pending storage requests when their bridge was torn down, typically
+ * because this tab was just promoted to leader or the leader handed over.
+ * Retriable: the next attempt goes to the new leader.
+ */
+declare class BridgeTerminatedError extends KoraError {
+    constructor(operation: string, reason: string);
+}
+/** Thrown when a storage request is cancelled through its `AbortSignal`. */
+declare class RequestAbortedError extends KoraError {
+    constructor(operation: string, requestId: string);
+}
+/**
+ * Thrown by `deleteDatabase()` when the database is open in some tab or worker
+ * on this origin. Close it everywhere (or call `app.close()`) and retry.
+ */
+declare class StorageInUseError extends KoraError {
+    constructor(dbName: string);
+}
+/**
+ * Thrown by `deleteDatabase()` when the database still holds operations that
+ * never reached the server. Sync first, or pass `{ force: true }` to discard them.
+ */
+declare class UnsyncedDataError extends KoraError {
+    constructor(dbName: string);
+}
+/**
+ * Thrown when a database's data lives in a storage backend this runtime cannot
+ * read (for example it was written to OPFS, and OPFS is unavailable now). Kora
+ * refuses to start an empty, disjoint copy rather than hide the existing data.
+ */
+declare class StorageBackendMismatchError extends KoraError {
+    constructor(dbName: string, recorded: string, requested: string, reason: string);
 }
 /**
  * Thrown when IndexedDB persistence operations fail (serialize/deserialize).
@@ -86,6 +157,14 @@ declare class NoLeaderError extends KoraError {
 declare class PersistenceError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
+/**
+ * Thrown by a local write while the store's pinned node id (an auth device id) belongs
+ * to another user than the one signed in (F9): a browser two users shared. The write
+ * could only be stored under the owner's node and would later upload as the owner's.
+ */
+declare class NodeOwnedByAnotherUserError extends KoraError {
+    constructor(nodeId: string, principal: string | null);
+}
 
 /**
  * How the local operation log may be compacted.
@@ -124,6 +203,27 @@ declare function computeAckCompactionWatermark(serverVector: VersionVector): Ver
  */
 declare function compactOperationLog(adapter: StorageAdapter, schema: SchemaDefinition, strategy: CompactionStrategy, serverVector: VersionVector): Promise<CompactionResult>;
 
+/**
+ * How a database is re-materialized on its first open with the W7 fold:
+ *
+ * - `'log'`: the log is clean (W8 integrity scan): every record is rebuilt with the
+ *   fold from its operations. This also repairs replicas that diverged under the
+ *   pairwise merge of beta.12/13.
+ * - `'snapshot+log'`: the log is not complete (it was compacted, or has sequence
+ *   gaps): each existing row becomes the record's row snapshot (its values at
+ *   their `_field_versions`, exact where a stored fold state still has them), and
+ *   the remaining operations are folded on top.
+ * - `'kept'`: the log has quarantined rows (W8). Only the records that own a
+ *   quarantined row are kept exactly as they are (their row becomes their snapshot,
+ *   nothing is rebuilt from their log); every other record is rebuilt as in `'log'`
+ *   or `'snapshot+log'` (RT-68).
+ *
+ * Row snapshots are approximate (see `createSnapshotState`); records that fold
+ * against one are listed in `_kora_fold_snapshot` until their history is complete
+ * again (a scope entry with the server's fold state, or a full resync).
+ */
+type RematerializationMode = 'log' | 'snapshot+log' | 'kept';
+
 /**
  * Result of re-stamping unsynced operations after a clock correction.
  */
@@ -138,23 +238,39 @@ interface ClockRebaseResult {
     newMaxTimestamp: HLCTimestamp | null;
 }
 
-declare const LAST_ACKED_SERVER_VECTOR_META_KEY = "last_acked_server_vector";
-/**
- * Serialize a version vector for `_kora_meta` storage.
- */
-declare function serializeVersionVectorToMeta(vector: VersionVector): string;
-/**
- * Deserialize a version vector from `_kora_meta`.
- */
-declare function deserializeVersionVectorFromMeta(value: string): VersionVector;
-/**
- * Merge two version vectors, keeping the maximum sequence per node.
- */
-declare function mergeVersionVectors(a: VersionVector, b: VersionVector): VersionVector;
-/**
- * Operations present locally but not yet on the server (per server version vector).
- */
-declare function collectOperationsAheadOfServer(localVector: VersionVector, serverVector: VersionVector, fetchRange: (nodeId: string, fromSeq: number, toSeq: number) => Promise<Operation[]>): Promise<Operation[]>;
+/** Result of {@link rotateUnsyncedOperationsInLog}. */
+interface NodeRotationResult {
+    /** The node id the device uses from now on. */
+    nodeId: string;
+    /** The rewritten operations under the new node id, in their original causal order. */
+    operations: Operation[];
+    /** Maps each old operation id to its new content-addressed id. */
+    idMapping: Record<string, string>;
+}
+
+/** Result of `Store.resequenceOperation` (RT-35 renumbering). */
+interface ResequenceResult {
+    /** The renumbered operation (a version-2 one under a new id). */
+    operation: Operation;
+    /** Never-sent dependents rewritten to name the new id (re-hashed), in sequence order. */
+    dependents: Operation[];
+    /** Old id -> new id, for the operation and every re-hashed dependent. */
+    idMapping: Record<string, string>;
+}
+
+/** A delivered operation the client did not apply, as stored in `_kora_unapplied_ops`. */
+interface UnappliedOperation {
+    /** The operation as delivered (still encrypted when decryption failed). */
+    operation: Operation;
+    /** Delivery sequence of the batch that carried it, or null for a legacy batch. */
+    deliverySequence: number | null;
+    /** Machine-readable reason. */
+    code: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Wall-clock time (ms) it was quarantined. Display only. */
+    quarantinedAt: number;
+}
 
 /**
  * A merge or constraint decision persisted for enterprise audit export.
@@ -233,11 +349,14 @@ interface AuditTraceQuery {
  * Manifest embedded in every backup file.
  */
 interface BackupManifest {
-    /** Backup format version */
-    version: 1;
+    /** Backup format version (2 since STORE-5; version 1 files need `convertBackupV1`) */
+    version: number;
     /** When the backup was created (epoch ms) */
     createdAt: number;
-    /** Node ID of the originating device */
+    /**
+     * Node ID of the originating device. Informational only: a restore never copies a
+     * device identity into the importing database.
+     */
     nodeId: string;
     /** Schema version at backup time */
     schemaVersion: number;
@@ -247,6 +366,20 @@ interface BackupManifest {
     collections: string[];
     /** Whether materialized records are included */
     includesRecords: boolean;
+    /** Whether the records include deleted rows (tombstones). False for converted v1 files. */
+    includesTombstones?: boolean;
+    /** Set on a file produced by `convertBackupV1`. */
+    convertedFrom?: number;
+    /**
+     * The file carries the W7 fold's per-record base states (`fold_base`), row
+     * snapshots (`fold_snapshot`) and the compacted prefixes (`compacted_through`), so
+     * a compacted device's history survives a restore on another device (RT-66).
+     * Absent on files from earlier releases: their log may be incomplete (compacted),
+     * so a restore rebuilds their records on top of the backup's rows.
+     */
+    includesFoldState?: boolean;
+    /** The exporting database had compacted its log (it then needs `fold_base`). */
+    compacted?: boolean;
     /** SHA-256 hex checksum of all content sections */
     checksum: string;
 }
@@ -271,6 +404,24 @@ interface RestoreResult {
     success: boolean;
     /** Error message if failed */
     error?: string;
+    /** Error code if failed (`BACKUP_CHECKSUM_MISMATCH`, `BACKUP_OPERATION_INVALID`, ...) */
+    errorCode?: string;
+    /**
+     * Set when the file was a version-1 backup (Kora 1.0.0-beta.12 and earlier) that the
+     * import converted first, as `convertBackupV1` does.
+     */
+    convertedFromVersion?: 1;
+    /**
+     * Replace mode: this device's own writes the sync server had not acknowledged,
+     * re-applied on top of the restored data (see `RestoreOptions.keepUnsyncedWrites`).
+     */
+    unsyncedWritesKept?: number;
+    /**
+     * Merge mode: operations of server-authority nodes (`kora:` nodes and the explicit
+     * server authorities this device learned) the file held and the import left out.
+     * Server decisions reach a device only from the sync server.
+     */
+    serverOperationsSkipped?: number;
     /** Duration in ms */
     duration: number;
 }
@@ -294,12 +445,118 @@ interface RestoreOptions {
     /** Progress callback */
     onProgress?: (progress: BackupProgress) => void;
     /**
-     * If true, merge operations with existing data (replay through applyRemoteOperation).
-     * If false, clear and replace all data (default: false).
+     * If true, merge the backup into the existing data: every operation is applied like
+     * one received from sync (deduplicated by id, merged per field), the version vector
+     * advances by MAX, and nothing of the exporting device's identity or sync state is
+     * imported. If false (default), replace the local data with the backup's.
      */
     merge?: boolean;
+    /**
+     * Replace mode only: keep this device's own writes that the sync server has not
+     * acknowledged, re-applied on top of the backup, so a restore never discards writes
+     * that exist nowhere else. Writes of a node the server has accepted are always kept
+     * (they are in flight). Default: true for `store.importBackup`; `app.importBackup`
+     * defaults it to whether sync is configured, so a local-only app gets an exact
+     * replace.
+     */
+    keepUnsyncedWrites?: boolean;
 }
 
+/**
+ * Log-integrity scan (W8 step 0).
+ *
+ * Every later fold of the operation log (W7 re-materialization, replay, compaction)
+ * trusts that each stored row is a canonical operation. Two earlier releases could
+ * break that:
+ *
+ * - beta.12's backup restore wrote `JSON.stringify(timestamp)` into the timestamp
+ *   column, which `HybridLogicalClock.deserialize` reads as `wallTime: NaN` (a `null`
+ *   once re-exported), and a second restore of such a backup nested the damage;
+ * - compaction deletes acknowledged operations, leaving holes in a node's sequence.
+ *
+ * The scan detects rows that do not round-trip through `deserializeOperation` /
+ * `serializeOperation`, repairs the ones whose original value is recoverable from the
+ * row itself (the JSON-encoded timestamp), and moves the rest to
+ * {@link LOG_QUARANTINE_TABLE} (never deleted), so no fold ever reads them. It also
+ * reports sequence gaps in this database's own nodes. Remote nodes' gaps are normal
+ * (scoped sync only delivers part of another device's log) and are not reported.
+ */
+/** Rows that could not be repaired, kept verbatim. Never cleared automatically. */
+declare const LOG_QUARANTINE_TABLE = "_kora_log_quarantine";
+/** What is wrong with an operation row. */
+type LogRowProblem = 
+/** The timestamp is a JSON-encoded HLC (beta.12 backup restore). Repairable. */
+'timestamp-json'
+/** The timestamp cannot be read as an HLC and is not recoverable. */
+ | 'timestamp-malformed'
+/** `id`, `node_id` or `record_id` is missing. */
+ | 'identity-malformed'
+/** `type` is not insert, update or delete. */
+ | 'type-invalid'
+/** `sequence_number` is not a positive integer. */
+ | 'sequence-invalid'
+/** `data` or `previous_data` is not a JSON object. */
+ | 'data-malformed'
+/** `causal_deps` is not a JSON array of operation ids. */
+ | 'causal-deps-malformed'
+/** The row cannot be turned into an operation and back. */
+ | 'round-trip-failed';
+/** One operation row the scan repaired or quarantined. */
+interface LogIntegrityRow {
+    collection: string;
+    operationId: string;
+    nodeId: string | null;
+    sequenceNumber: number | null;
+    problem: LogRowProblem;
+    /** Human-readable detail: the bad value, or how it was repaired. */
+    detail: string;
+}
+/** Sequence numbers missing from one of this database's own nodes. */
+interface LogSequenceGap {
+    nodeId: string;
+    /** First missing sequence number (inclusive). */
+    from: number;
+    /** Last missing sequence number (inclusive). */
+    to: number;
+}
+/**
+ * Result of {@link scanLogIntegrity} / `Store.verifyLogIntegrity()`.
+ *
+ * `clean` is the precondition for rebuilding state from the log (W7): every row is
+ * canonical, nothing is quarantined, and this database's own nodes have no holes
+ * below their highest stored sequence number.
+ */
+interface LogIntegrityReport {
+    /** True when the log can be folded as-is (no quarantined rows, no own-node gaps). */
+    clean: boolean;
+    /** `full`: every row was checked in JS. `quick`: SQL prefilter, suspects checked in JS. */
+    mode: 'full' | 'quick';
+    /** Rows checked in JS (all rows in full mode, suspects in quick mode). */
+    checkedRows: number;
+    /** Rows this scan repaired in place. */
+    repaired: LogIntegrityRow[];
+    /** Rows this scan moved to the quarantine table. */
+    newlyQuarantined: LogIntegrityRow[];
+    /** Every row in the quarantine table (this scan's and earlier ones'). */
+    quarantined: LogIntegrityRow[];
+    /** Holes in this database's own nodes' sequences (compaction, a lost tail). */
+    gaps: LogSequenceGap[];
+    /** When the log was last compacted (epoch ms), or null when never. */
+    compactedAt: number | null;
+    /** False when the scan only reported (`repair: false`). */
+    repairApplied: boolean;
+}
+
+/** Compares two query result sets; true means subscribers need not be notified. */
+type ResultsEqual = (prev: readonly CollectionRecord[], next: readonly CollectionRecord[]) => boolean;
+
+/**
+ * Per-subscription options accepted by `register` / `registerAndFetch`.
+ */
+interface RegisterOptions extends SubscribeOptions {
+    /** Result-set comparator; defaults to structural comparison of every value. */
+    resultsEqual?: ResultsEqual;
+}
 /**
  * Configuration options for the SubscriptionManager.
  */
@@ -323,7 +580,29 @@ interface SubscriptionManagerOptions {
     bloomFalsePositiveRate?: number;
     /** Called when a query subscription is registered (e.g. to register sync query subsets). */
     onQuerySubscribed?: (descriptor: QueryDescriptor) => () => void;
+    /**
+     * Called for every subscription failure (the store emits `query:error`), in
+     * addition to the subscriber's own `onError`.
+     */
+    onQueryError?: (failure: QuerySubscriptionError) => void;
+}
+/**
+ * A committed change to the rows of one collection that can affect query results
+ * (RT-98). Every invalidation the store makes produces one: local writes and remote
+ * applies (with the operation), and changes made without a new operation (rejection
+ * re-folds, scope retraction, cascade settling, rematerialization, backup restore,
+ * held/discarded writes).
+ */
+interface RecordsChange {
+    /** Collection whose rows changed */
+    readonly collection: string;
+    /** Changed record ids, or null when unknown (treat the whole collection as changed) */
+    readonly ids: readonly string[] | null;
+    /** The operation that caused the change, when there is one */
+    readonly operation?: Operation;
 }
+/** Listener for {@link RecordsChange}s made by this runtime (not those relayed from peers). */
+type RecordsChangeListener = (change: RecordsChange) => void;
 /**
  * Performance statistics for monitoring subscription checking efficiency.
  */
@@ -364,6 +643,14 @@ declare class SubscriptionManager {
     private pendingCollections;
     private flushScheduled;
     private readonly onQuerySubscribed?;
+    private readonly onQueryError?;
+    private readonly changeListeners;
+    /**
+     * Collections changed before the first change listener attached (a store's open:
+     * rematerialization, migration backfills). Replayed to that listener, so other tabs
+     * hear about changes made while this tab was still opening. Bounded by the schema.
+     */
+    private unheardCollections;
     private bloomFilter;
     private bloomDirty;
     private readonly bloomThreshold;
@@ -383,22 +670,55 @@ declare class SubscriptionManager {
      * @param executeFn - Function to re-execute the query and get current results
      * @returns An unsubscribe function
      */
-    register(descriptor: QueryDescriptor, callback: SubscriptionCallback<CollectionRecord>, executeFn: () => Promise<CollectionRecord[]>): () => void;
+    register(descriptor: QueryDescriptor, callback: SubscriptionCallback<CollectionRecord>, executeFn: () => Promise<CollectionRecord[]>, options?: RegisterOptions): () => void;
     /**
      * Register a subscription and immediately execute the query.
      * The initial results are stored as lastResults so subsequent flushes
-     * correctly diff against the initial state.
+     * correctly diff against the initial state. A failing initial run is reported
+     * through `options.onError` and the `query:error` hook, never as an unhandled
+     * rejection (STORE-12).
      *
      * @returns An unsubscribe function
      */
-    registerAndFetch(descriptor: QueryDescriptor, callback: SubscriptionCallback<CollectionRecord>, executeFn: () => Promise<CollectionRecord[]>): () => void;
+    registerAndFetch(descriptor: QueryDescriptor, callback: SubscriptionCallback<CollectionRecord>, executeFn: () => Promise<CollectionRecord[]>, options?: RegisterOptions): () => void;
+    private createSubscription;
+    private track;
+    /**
+     * Run a subscription's query and deliver the result when it changed. Never
+     * throws: failures go to the error channel. Runs are numbered so a slow,
+     * older run never overwrites the result of a newer one.
+     */
+    private run;
+    private isCurrent;
+    private reportError;
     /**
      * Notify the manager that a mutation occurred on a collection.
      * Schedules a microtask flush to batch multiple mutations in the same tick.
      */
-    notify(collection: string, _operation: Operation): void;
-    /** Invalidate a collection after a local-view change that has no domain operation. */
-    invalidate(collection: string): void;
+    notify(collection: string, operation: Operation): void;
+    /**
+     * Invalidate a collection after a local-view change that has no domain operation
+     * (a re-fold, a retraction, a restore). Pass the record ids when known.
+     */
+    invalidate(collection: string, ids?: readonly string[] | null): void;
+    /**
+     * The single entry point for a committed change made by this runtime (RT-98): it
+     * schedules the affected queries and tells every change listener (the cross-tab
+     * bus), so no invalidation path can reach this tab's queries without reaching the
+     * other tabs' too.
+     */
+    recordsChanged(change: RecordsChange): void;
+    /**
+     * Invalidate a collection for a change another runtime made to the shared
+     * database. Not relayed to change listeners (the peer already broadcast it).
+     */
+    invalidateFromPeer(collection: string): void;
+    /**
+     * Listen to every committed change this runtime makes.
+     *
+     * @returns An unsubscribe function
+     */
+    onRecordsChanged(listener: RecordsChangeListener): () => void;
     /**
      * Immediately flush all pending notifications.
      * Useful for testing. In production, flushing happens via microtask.
@@ -438,12 +758,6 @@ declare class SubscriptionManager {
      */
     private rebuildBloomFilter;
     private scheduleFlush;
-    /**
-     * Compare two result sets. Uses ID-based comparison first (same length, same IDs),
-     * then deep comparison of remaining fields when IDs match.
-     * Avoids JSON.stringify which is O(n) and fragile to field ordering differences.
-     */
-    private resultsEqual;
 }
 
 /**
@@ -472,6 +786,10 @@ declare class QueryBuilder<T = CollectionRecord> {
     constructor(collectionName: string, definition: CollectionDefinition, adapter: StorageAdapter, subscriptionManager: SubscriptionManager, initialWhere?: WhereClause, schema?: SchemaDefinition | undefined);
     /**
      * Add WHERE conditions (AND semantics, merged with existing conditions).
+     *
+     * A field whose value is `undefined` adds no condition (it does not remove an
+     * earlier one); `null` matches missing values (`IS NULL`). Non-finite numbers are
+     * refused. See {@link normalizeWhere} (RT-102).
      */
     where(conditions: WhereClause): QueryBuilder<T>;
     /**
@@ -516,7 +834,9 @@ declare class QueryBuilder<T = CollectionRecord> {
      *
      * @returns An unsubscribe function
      */
-    subscribe(callback: SubscriptionCallback<T>): () => void;
+    subscribe(callback: SubscriptionCallback<T>, options?: SubscribeOptions): () => void;
+    /** Comparator built once per collection definition and shared by its queries. */
+    private getResultsEqual;
     /** Get the internal descriptor (for testing/debugging) */
     getDescriptor(): QueryDescriptor;
     private clone;
@@ -595,20 +915,6 @@ declare class SequenceManager {
     }): Promise<void>;
 }
 
-/**
- * Allocates monotonic sequence numbers for a single open transaction.
- * Loads the current DB watermark once, then increments in memory until commit.
- */
-declare class TransactionSequenceAllocator {
-    private readonly adapter;
-    private readonly nodeId;
-    private loaded;
-    private watermark;
-    constructor(adapter: StorageAdapter, nodeId: string);
-    allocate(): Promise<number>;
-    getHighWaterMark(): number;
-}
-
 /**
  * Internal configuration for creating a TransactionContext.
  * Passed from Store to avoid exposing Store internals publicly.
@@ -618,10 +924,23 @@ interface TransactionContextConfig {
     adapter: StorageAdapter;
     clock: HybridLogicalClock;
     nodeId: string;
-    sequenceAllocator: TransactionSequenceAllocator;
     relationEnforcer: RelationEnforcer | null;
     causalTracker: CausalTracker | null;
-    localMutationHandler: LocalMutationHandler | null;
+    /**
+     * Key provider for `t.secret()` encrypted fields. Transaction writes transform
+     * secret fields through the same helper as single-record writes (STORE-4).
+     */
+    secretKeyProvider?: SecretKeyProvider;
+    /** Referential hook run for every local delete inside the commit (see {@link LocalDeleteHook}). */
+    beforeLocalDelete?: LocalDeleteHook;
+    /** Called when the commit's storage transaction fails, before the error propagates. */
+    onStorageError?: (error: unknown) => void;
+    /** The W7 record fold (see `WriteEnv.fold`). */
+    fold?: RecordFolder;
+    /** See `WriteEnv.maxOperationBytes`. */
+    maxOperationBytes?: number;
+    /** See `WriteEnv.assertLocalWriteAllowed`. */
+    assertLocalWriteAllowed?: () => void;
 }
 /**
  * A collection accessor within a transaction.
@@ -636,8 +955,10 @@ interface TransactionCollectionAccessor {
 /**
  * TransactionContext provides atomic multi-collection operations.
  *
- * All mutations are buffered and committed in a single StorageAdapter.transaction()
- * call. All operations share the same transactionId (UUID v7).
+ * Mutations are validated and buffered when called (so errors surface at the
+ * call site and `insert` returns the new id immediately), then written in a
+ * single `StorageAdapter.transaction()` at commit. All operations share the
+ * same transactionId (UUID v7) and one contiguous block of sequence numbers.
  *
  * Subscription notifications are deferred until after commit.
  *
@@ -672,7 +993,13 @@ declare class TransactionContext {
      */
     collection(name: string): TransactionCollectionAccessor;
     /**
-     * Commit all buffered operations atomically.
+     * Commit all buffered mutations atomically.
+     *
+     * Every entry is written, in call order, inside ONE storage transaction through
+     * the single local write path: sequence numbers are reserved inside the
+     * transaction (one contiguous block covering referential side effects too) and
+     * each operation is built only after its number is reserved.
+     *
      * Returns the list of operations and affected collections for subscription notification.
      */
     commit(): Promise<{
@@ -687,32 +1014,35 @@ declare class TransactionContext {
      * Get the transaction ID shared by all operations in this transaction.
      */
     getTransactionId(): string;
+    private writeEnv;
     private ensureActive;
     private insert;
     private update;
     private deleteRecord;
-    private findById;
     /**
-     * Get the effective state of a record, considering both the database and buffered operations.
-     * Buffered inserts/updates take precedence over the database state.
+     * The values an update will write, resolved against `current` (the effective
+     * record) for read-your-writes inside the transaction. Secret fields are shown
+     * in their at-rest form, like the record a committed update returns.
+     */
+    private previewUpdate;
+    /**
+     * The effective state of a record: the committed row overlaid with this
+     * transaction's buffered mutations, in call order.
      */
     private getEffectiveRecord;
 }
 
-/**
- * Store is the main orchestrator. It owns a schema, a storage adapter,
- * a clock, and a subscription manager. It creates Collection instances
- * for each schema collection, and provides the sync contract via
- * applyRemoteOperation and getOperationRange.
- *
- * @example
- * ```typescript
- * const store = new Store({ schema, adapter })
- * await store.open()
- * const todo = await store.collection('todos').insert({ title: 'Hello' })
- * await store.close()
- * ```
- */
+/** Result of {@link Store.bindPrincipal} (RT-42). */
+interface PrincipalBinding {
+    /** The node id local writes use from now on. */
+    nodeId: string;
+    /** The node id in use before the call. */
+    previousNodeId: string;
+    /** The store moved to another node id. */
+    switched: boolean;
+    /** The node id is pinned and belongs to another user: nothing may upload it now. */
+    conflict: boolean;
+}
 declare class Store implements OperationLog {
     private opened;
     private nodeId;
@@ -725,6 +1055,12 @@ declare class Store implements OperationLog {
     private readonly schema;
     private readonly adapter;
     private readonly configNodeId;
+    /** The owner of the pinned node while it belongs to another user than the signed-in one (F9). */
+    private pinnedNodeOwnedBy;
+    /** The sync server refused the pinned node as another user's (F9). */
+    private pinnedNodeRefusedByServer;
+    /** The user of the last {@link bindPrincipal}. */
+    private signedInPrincipal;
     private readonly dbName;
     private readonly isolation;
     private readonly emitter;
@@ -732,6 +1068,18 @@ declare class Store implements OperationLog {
     private relationEnforcer;
     private causalTracker;
     private readonly secretKeyProvider;
+    /** Releases the per-tab node lock (RT-40); null when none is held. */
+    private releaseNodeLock;
+    /** How rows are materialized ({@link StoreConfig.materialization}). */
+    private readonly materialization;
+    /** The W7 record fold; null under legacy materialization. */
+    private readonly folder;
+    /** True once every row of the database is a materialization of its fold state. */
+    private foldActive;
+    /** Schema transforms applied at fold time (RT-84); never to stored operations. */
+    private readonly operationTransforms;
+    /** Largest operation a local write may produce (RT-86); default in the write path. */
+    private readonly maxOperationBytes;
     constructor(config: StoreConfig);
     /**
      * Open the store: initialize the database, load or generate a node ID,
@@ -742,6 +1090,25 @@ declare class Store implements OperationLog {
      * Close the store: clear subscriptions and close the adapter.
      */
     close(): Promise<void>;
+    /**
+     * Check the operation log (W8 step 0): every row must round-trip through the
+     * canonical operation serializer. Rows an earlier release damaged in a recoverable
+     * way (a JSON-encoded timestamp written by a beta.12 backup restore) are repaired;
+     * unrecoverable rows move to the quarantine table, where no fold reads them. Also
+     * reports sequence gaps in this database's own nodes (compaction, a lost tail).
+     *
+     * The store runs a quick variant (SQL prefilter) on every open. Rebuilding state from
+     * the log must only run on a `clean` report.
+     *
+     * @param options - `repair: false` only reports; `mode: 'quick'` checks only the rows
+     *   a SQL prefilter flags (default `'full'`: every row)
+     * @returns The integrity report; emits `store:log-integrity` when rows changed
+     */
+    verifyLogIntegrity(options?: {
+        repair?: boolean;
+        mode?: 'full' | 'quick';
+    }): Promise<LogIntegrityReport>;
+    private scanLog;
     /**
      * Get a Collection instance for CRUD operations.
      * @throws {StoreNotOpenError} If the store is not open
@@ -762,12 +1129,143 @@ declare class Store implements OperationLog {
      */
     setClockReferenceOffset(offsetMs: number): void;
     getNodeId(): string;
+    /** The schema transforms the fold applies (transforms at fold time, RT-84). */
+    getOperationTransforms(): readonly OperationTransform[];
     /**
      * Apply a remote operation received from sync.
      * Checks for duplicates, applies to the data table, persists the operation,
      * and updates the version vector.
      */
-    applyRemoteOperation(op: Operation, options?: ApplyRemoteOptions): Promise<ApplyResult>;
+    applyRemoteOperation(stored: Operation, options?: ApplyRemoteOptions): Promise<ApplyResult>;
+    /**
+     * W7 remote apply: append the operation, then merge it into its record's fold
+     * state, which re-materializes the row, all in one write transaction. There is no
+     * read-decide-write race to guard: the state is read and written inside the
+     * transaction, and the merge does not depend on the order operations arrive in.
+     */
+    private applyRemoteFolded;
+    /** DevTools: every fold decision that was a conflict, plus one completion per merge. */
+    private emitMergeTraces;
+    /** The record fold, once the database's rows are fold materializations. */
+    private activeFold;
+    /**
+     * The record's W7 fold state (null under legacy materialization or when the
+     * record has none). For DevTools, tests and the server-comparison harness.
+     */
+    getFoldState(collection: string, recordId: string): Promise<FoldState | null>;
+    /** Whether rows are materialized by the W7 fold (false under `materialization: 'legacy'`). */
+    isFoldMaterialized(): boolean;
+    private readMeta;
+    private writeMeta;
+    /**
+     * Write every genuine beta.12 clear of the op log into its logged body, once per
+     * database (RT-83, RT-85): the fold folds bodies as written, so the clear must be in
+     * the body. Records already materialized by the fold are re-folded.
+     */
+    private ensureLegacyBodiesCanonical;
+    /**
+     * Make every row a materialization of its record's fold state (W7), once per
+     * database and fold-state version. Runs after the W8 log-integrity scan: a
+     * clean log is rebuilt with the fold; an incomplete (compacted) log rebuilds on
+     * top of the rows as base snapshots; a log with quarantined rows is never
+     * rebuilt from (rows are kept and become base snapshots), and
+     * `store:rematerialized` reports which happened.
+     */
+    private ensureMaterialization;
+    /**
+     * Refuse to open when a schema version in the local operation log has no transform
+     * path to the current schema (RT-103). Operations of a NEWER schema (authored by an
+     * upgraded peer) are not checked: they are kept aside until this device upgrades.
+     */
+    private assertTransformCoverage;
+    /**
+     * Re-fold the records of every collection whose fold plan changed since the rows
+     * were materialized (RT-63): a field that became `merge('counter')`, an array that
+     * became append-only, a new or edited resolver. Their stored states hold fields of
+     * the old kind, which the fold refuses (`FoldStateError`). Each record is rebuilt
+     * from its log with the new plan; compacted bases and row snapshots are adapted
+     * (a re-planned field restarts from its materialized value at its version). The
+     * client's equivalent of the server stores' `fold_plan_fingerprint`.
+     */
+    private ensureFoldPlan;
+    /**
+     * Row snapshots were created (RT-68): ask the sync server for a full resync (the
+     * delivery watermarks restart at 0, as after a restore), so each such record gets
+     * its complete history back; {@link settleSnapshotRecords} then drops the
+     * snapshots once the resync has caught up.
+     */
+    private requestSnapshotResync;
+    /**
+     * Records whose state still folds against a row snapshot (approximate: a late
+     * concurrent write older than a field's version is not folded, RT-68).
+     */
+    getSnapshotRecords(): Promise<Array<{
+        collection: string;
+        recordId: string;
+    }>>;
+    /**
+     * Called by sync when a delivery stream has caught up (its final batch fully
+     * applied). After the full resync {@link requestSnapshotResync} asked for, every
+     * row-snapshot record whose insert is back in the log is re-folded from its
+     * complete history and stops being approximate (RT-68). Also retires the
+     * provisional cascades of remote deletes (RT-69): the server's own copies were
+     * delivered by now, and any it did not derive must not stay applied locally.
+     *
+     * With `provisionalOnly` only the provisional cascades are retired (RT-93: a stream
+     * batch from a server that derives no cascades, which is not the end of a resync).
+     *
+     * @param options - `provisionalOnly`: leave row snapshots for the next catch-up
+     * @returns How many snapshots were dropped
+     */
+    settleAfterCatchUp(options?: {
+        provisionalOnly?: boolean;
+    }): Promise<number>;
+    /**
+     * Apply the cascades / set-nulls of a REMOTE delete as local-only provisional
+     * effects (RT-69): folded into the children like operations, but never logged,
+     * sequenced or queued for upload. The server derives and relays its own copy;
+     * when it arrives (same parent, same record) the provisional effect is retired.
+     *
+     * @param parent - The remote delete
+     * @param effects - Its side effects, as the referential check derived them
+     */
+    applyProvisionalSideEffects(parent: Operation, effects: ReadonlyArray<{
+        type: 'delete' | 'update';
+        collection: string;
+        recordId: string;
+        data: Record<string, unknown> | null;
+        previousData: Record<string, unknown> | null;
+        ruleId: string;
+    }>): Promise<number>;
+    /**
+     * Node ids whose writes win `merge('server-authoritative')` fields (the server's,
+     * from the sync handshake). Every `kora:server:` id is authoritative by prefix, so
+     * only explicit ids (legacy server node ids, configured extras) are kept: the device
+     * persists the UNION of every explicit id it has learned and never drops one (RT-75).
+     * Handshakes differ per server instance (each lists what it knows), so a list that
+     * omits an id is not a revocation.
+     *
+     * Revocation is explicit (RT-81): ids a handshake lists in `revokedAuthoritativeNodeIds`
+     * are removed from the union, persisted as revoked, and never learned again. Records
+     * of collections with such fields are re-folded only when the explicit set changes
+     * (grows, or loses a revoked id).
+     *
+     * @param nodeIds - The server's authoritative node ids (one handshake's list)
+     * @param revokedNodeIds - Explicit ids the server revoked (one handshake's list)
+     */
+    setAuthoritativeNodeIds(nodeIds: readonly string[], revokedNodeIds?: readonly string[]): Promise<void>;
+    /**
+     * Re-fold the records of these operations from base + log (W7 exclusion: an
+     * operation with a terminal-rejection marker is left out).
+     */
+    private refoldRecordsOf;
+    /**
+     * Append a remote operation to the log. If another operation of the same node
+     * already holds its sequence number (a beta.12 device could produce such
+     * pairs), the log keeps the existing row and this one is recorded in the
+     * sequence-conflicts table, where dedup and record folds still see it.
+     */
+    private appendRemoteOperationRow;
     /**
      * Hide a record from this client's authorized materialized view. This writes no
      * replicated operation and therefore cannot be mistaken for a domain deletion.
@@ -779,6 +1277,26 @@ declare class Store implements OperationLog {
         collection: string;
         recordId: string;
     }>>;
+    /**
+     * Materialize a server scope-entry insert (RT-19) whose fields each carry their
+     * own version (RT-27). The entry restates the record's current server values; a
+     * single whole-row stamp would let a field the server last wrote long ago
+     * overwrite this device's newer unsynced edit of it, after which the device's own
+     * operation uploads and wins on the server (divergence). So every field is resolved
+     * on its own, by last-write-wins against this row's `_field_versions`:
+     *
+     * - no row: inserted with each field stamped at its own version, `_created_at`
+     *   at the record's creation (the entry's `timestamp`), then any orphaned
+     *   updates/deletes are folded in as for any insert;
+     * - live row, or a row hidden by a scope retraction: per-field LWW (a retracted
+     *   row is shown again; `_created_at` is kept);
+     * - domain tombstone: revived only when the entry's newest field version is
+     *   newer than the tombstone, then per-field LWW.
+     *
+     * Deterministic and idempotent: the outcome depends only on the stored and
+     * incoming per-field versions, and a re-applied entry wins no field.
+     */
+    private applyFieldVersionedInsert;
     /**
      * Materialize update/delete operations that were logged for a record BEFORE
      * its insert arrived (reordered delivery). Runs inside the insert's write
@@ -842,11 +1360,34 @@ declare class Store implements OperationLog {
      */
     notifyExternalOperation(operation: Operation): void;
     /**
-     * Build mutation context for a collection (used by ApplyPipeline side effects).
+     * Notify this store that another same-origin runtime changed rows of a collection
+     * in the shared local database without an operation this tab can see (a re-fold,
+     * a scope retraction, a restore; RT-98). Only re-runs the affected live queries.
+     *
+     * @param collection - The collection whose rows changed
+     */
+    notifyExternalChange(collection: string): void;
+    /**
+     * Listen to every committed change this store makes to collection rows: local
+     * writes, remote applies, and changes without a new operation (re-folds, scope
+     * retraction, cascade settling, rematerialization, restore). The cross-tab bus
+     * relays these to other tabs on the same database (RT-98).
+     *
+     * @returns An unsubscribe function
+     */
+    onRecordsChanged(listener: RecordsChangeListener): () => void;
+    /**
+     * Build the local write context for a collection: everything the single local
+     * write path needs (used by Collection writes and by ApplyPipeline).
      */
     createMutationContext(collection: string, options?: {
-        inTransaction?: boolean;
         extraCausalDeps?: string[];
+        /**
+         * Stamp the writes with this clock instead of the store's (it must be this
+         * node's). Used for the side effects of a remote delete, stamped right after
+         * the delete like the server's copy (seam 5), never with the device's "now".
+         */
+        clock?: HybridLogicalClock;
     }): LocalMutationContext;
     /**
      * Load a materialized row by ID, including soft-deleted tombstones.
@@ -871,6 +1412,25 @@ declare class Store implements OperationLog {
      * Persist the last server version vector this client believes the server has applied.
      */
     saveLastAckedServerVector(vector: VersionVector): Promise<void>;
+    /**
+     * Load the per-device node token the sync server issued for this node id (RT-12).
+     */
+    loadNodeToken(nodeId?: string): Promise<string | null>;
+    /**
+     * Persist the per-device node token under its node id (the current one by default).
+     */
+    saveNodeToken(token: string, nodeId?: string): Promise<void>;
+    /**
+     * Load the node ids the sync server named authoritative (protocol v2), or null when
+     * no protocol-2 server ever answered.
+     */
+    loadAuthoritativeNodeIds(): Promise<string[] | null>;
+    /**
+     * Persist the node ids the sync server named authoritative (protocol v2). Same as
+     * {@link setAuthoritativeNodeIds}: merged into the union of learned explicit ids,
+     * and the fold re-folds affected records only when that set grows.
+     */
+    saveAuthoritativeNodeIds(nodeIds: string[]): Promise<void>;
     /**
      * Load persisted delta cursor for resuming paginated initial sync.
      */
@@ -896,6 +1456,31 @@ declare class Store implements OperationLog {
      * Delete a persisted view watermark (safe: the view back-fills from 0 when next visited).
      */
     deleteDeliveryWatermark(signature: string): Promise<void>;
+    /**
+     * Record delivered operations the sync engine deliberately did not apply (inbound
+     * quarantine, W4) and, when given, advance a view's delivery watermark in the same
+     * transaction, so the watermark never passes an operation that is neither applied nor
+     * recorded.
+     */
+    saveInboundQuarantine(entries: UnappliedOperation[], watermark?: {
+        signature: string;
+        watermark: number;
+    }): Promise<void>;
+    /** Every quarantined inbound operation, oldest delivery first. */
+    loadInboundQuarantine(): Promise<UnappliedOperation[]>;
+    /** Remove quarantined inbound operations (applied on replay, or reconciled). */
+    removeInboundQuarantine(operationIds: string[]): Promise<void>;
+    /**
+     * The contiguous acknowledged prefix of this device's own operations for a node id,
+     * or null when none was recorded under that contract (W3).
+     */
+    loadOwnAckedThrough(nodeId: string): Promise<number | null>;
+    /** Persist the contiguous acknowledged own-operation prefix for a node id. */
+    saveOwnAckedThrough(nodeId: string, sequence: number): Promise<void>;
+    /** The downlink scope the sync server last accepted (null when none). */
+    loadAcceptedDownlinkScope(): Promise<Record<string, Record<string, unknown>> | null>;
+    /** Persist (or clear) the downlink scope the sync server last accepted. */
+    saveAcceptedDownlinkScope(scope: Record<string, Record<string, unknown>> | null): Promise<void>;
     /**
      * Local operations not yet reflected on the server version vector.
      */
@@ -911,14 +1496,185 @@ declare class Store implements OperationLog {
      * No data-change notifications are emitted: materialized values are
      * unchanged, only version stamps move.
      */
+    /**
+     * Move this device to a fresh node id, re-authoring its never-acknowledged
+     * operations under it (RT-21). Used when the sync server refuses the current node
+     * id (`NODE_ID_CLAIMED`): the device keeps every local write and uploads it under
+     * the new id. Acknowledged history stays under the old id. Persisted atomically;
+     * later writes use the new id.
+     *
+     * @param unsyncedOpIds - Ids of this node's operations the server never acknowledged
+     * @returns The new node id and the rewritten operations (for the outbound queue)
+     * @throws {KoraError} When the node id is pinned (`StoreConfig.nodeId`, or per-tab isolation)
+     */
+    rotateNodeId(unsyncedOpIds: string[]): Promise<NodeRotationResult>;
+    /**
+     * Re-author another local node's never-acknowledged operations under a fresh node id
+     * bound to `principal` (the user they belong to). Used when the sync server refuses an
+     * adopted node whose writes belong to the signed-in user (the app assigned them, or
+     * the node was created for them) but which no claims-aware server ever accepted: a
+     * beta.12 database's node with history the server recorded no owner for. The store's
+     * own node id, clock and counters are untouched; the fresh node is registered, so the
+     * sync engine adopts it like any other local node.
+     *
+     * @param fromNodeId - The refused local node (never the store's own)
+     * @param unsyncedOpIds - Ids of its operations the server never acknowledged
+     * @param principal - The user the writes belong to (the fresh node's binding)
+     * @returns The fresh node id and the rewritten operations (for the outbound queue)
+     * @throws {KoraError} `NODE_ID_UNKNOWN` when `fromNodeId` is the store's own node or
+     *   not a local node
+     */
+    reauthorLocalNode(fromNodeId: string, unsyncedOpIds: string[], principal: string): Promise<NodeRotationResult>;
+    /**
+     * Move this database back to a node id it authored under before (RT-38): after the
+     * sync server refused the current node, the device tries a node a returning user
+     * owns. Nothing is rewritten; later writes use `nodeId`.
+     *
+     * @throws {KoraError} When the node id is pinned, or `nodeId` is not a local node
+     */
+    switchNodeId(nodeId: string): Promise<void>;
+    /** Point the clock, sequence counter and collections at `nodeId` (already persisted). */
+    private rebindToNode;
+    /**
+     * Bind this database's writes to the signed-in user (RT-42). Call it whenever the
+     * signed-in user is known or changes, BEFORE the next local write (`createApp` does
+     * so at start and on every auth change of `sync.authClient`).
+     *
+     * - The current node belongs to `principal`: nothing changes.
+     * - The current node is unbound and has no history (no write, never synced): it is
+     *   bound to `principal` (every write under it from now on is theirs).
+     * - The current node is unbound but has history (a database from before RT-42, or
+     *   writes made while nobody was signed in): its owner is NOT guessed (RT-50). The
+     *   store moves to `principal`'s own node, and the old node's owner is learned from
+     *   the sync server (the first accepted handshake as it binds it; a refusal rules
+     *   that user out). A node that never synced cannot be attributed by anyone: its
+     *   unsynced writes are held for the app to assign or discard (`app.sync.assignHeld`,
+     *   `app.sync.discardHeld`).
+     * - It belongs to another user: the store moves to `principal`'s own local node (the
+     *   most recent one, not held), or to a fresh node bound to `principal`. Nothing is
+     *   rewritten: the other user's unsynced writes stay under their node, and sync never
+     *   uploads them on this user's session (they count as `heldOperations`).
+     *
+     * A pinned node id (`StoreConfig.nodeId`, such as an auth device id) cannot move:
+     * `conflict` is then true when it belongs to another user, and sync refuses to
+     * upload it under `principal`; an unbound pinned node with history stays unbound
+     * until the server accepts it for a user. Under `per-tab` isolation the tab moves to
+     * a fresh per-tab node.
+     *
+     * @param principal - The signed-in user id
+     * @returns The node now in use and whether it changed
+     */
+    bindPrincipal(principal: string): Promise<PrincipalBinding>;
+    /**
+     * The sync server refused this store's pinned node id because another user owns it
+     * (`owned: true`), or later accepted it (`false`). A pinned node cannot move to a fresh
+     * id, so writes made under it could only ever upload as its owner: while the server
+     * says so, local writes are refused (F9). A no-op for a store whose node is not pinned
+     * (it moves to a fresh node instead).
+     *
+     * @param owned - Whether the server reported the node owned by another user
+     */
+    setPinnedNodeOwnedElsewhere(owned: boolean): void;
+    /** Refuse a local write while the pinned node belongs to another user (F9). */
+    private assertLocalWriteAllowed;
+    private bindPrincipalToNode;
+    /**
+     * A sync handshake as `nodeId` was accepted for `principal` (RT-50): bind an unbound
+     * node (or replace a guessed binding) from the server's answer.
+     */
+    confirmNodePrincipal(nodeId: string, principal: string): Promise<void>;
+    /**
+     * The sync server refused `nodeId` for `principal` (RT-50): clear a guessed binding,
+     * and remember that an unbound node is not theirs.
+     */
+    recordNodeRefusedFor(nodeId: string, principal: string): Promise<void>;
+    /**
+     * Assign a held, unbound local node's writes to `principal` (RT-50): an explicit app
+     * decision for writes nobody can attribute (a database that never synced).
+     *
+     * @returns false when the node is unknown, the store's own, already bound, or was
+     *   refused for `principal` by the server
+     */
+    assignNodePrincipal(nodeId: string, principal: string): Promise<boolean>;
+    /**
+     * Forget a local node other than the store's own whatever it still holds (RT-50: the
+     * app discarded its held writes, which were marked never to upload first).
+     */
+    dropLocalNode(nodeId: string): Promise<void>;
+    /** The adoption schedule of this database's local nodes (RT-46). */
+    loadAdoptionSchedule(): Promise<AdoptionSchedule>;
+    /** Persist the adoption schedule (RT-46). */
+    saveAdoptionSchedule(schedule: AdoptionSchedule): Promise<void>;
+    /**
+     * Raise a local node's sequence counter to at least `floor`, in a transaction (the
+     * same MAX every reservation uses, W6), so the next write never reuses a number the
+     * server already holds (RT-35: the device lost the tail of its log, for example on a
+     * reload inside the IndexedDB snapshot window or after restoring an older copy).
+     *
+     * @returns Whether the counter moved
+     */
+    raiseSequenceFloor(nodeId: string, floor: number): Promise<boolean>;
+    /**
+     * Give one of a local node's operations a fresh sequence number above `floor`
+     * (RT-35): the server refused it with `SEQUENCE_CONFLICT` because it holds another
+     * operation of this node under that number (one this device lost). A version-1
+     * operation keeps its id (its hash does not cover the sequence number), exactly like
+     * the W6 sequence repair; a version-2 operation (protocol v2) is re-hashed under the
+     * new number, so it carries a new id. The old identity is recorded in
+     * `_kora_seq_conflicts` (`reemitted_as`).
+     *
+     * A new id would leave later operations naming the old one in `causalDeps`: those in
+     * `rewritableDependents` (operations the server never stored: never sent) are
+     * rewritten to name the new id, and re-hashed, transitively, in the same
+     * transaction. Dependents already sent keep their ids (the server may hold them);
+     * their dep resolves through the `_kora_seq_conflicts` record. Every touched record
+     * is re-folded (fold stamps carry operation ids).
+     *
+     * @param rewritableDependents - Ids of this node's operations that were never sent
+     * @returns The renumbered operation and the rewritten dependents, or null when the
+     *   operation is not in the log
+     */
+    resequenceOperation(operationId: string, nodeId: string, floor: number, rewritableDependents?: readonly string[]): Promise<ResequenceResult | null>;
+    /**
+     * Durability barrier (RT-35): resolves once every write committed so far is durable
+     * on this device. Sync awaits it before an operation leaves the device.
+     */
+    ensureDurable(): Promise<void>;
+    /** Record operations the server refused for good (RT-36). Never cleared. */
+    recordTerminalRejections(entries: TerminalRejection[]): Promise<void>;
+    /** Which of these operation ids the server refused for good (RT-36). */
+    findTerminalRejections(operationIds: string[]): Promise<Set<string>>;
+    /** Every node id this database authored operations under (RT-38, RT-40). */
+    listLocalNodes(): Promise<LocalNodeRecord[]>;
+    /** Forget a drained local node other than this store's own (RT-40). */
+    forgetLocalNode(nodeId: string): Promise<void>;
+    /** The current refusal cycle: the count of accepted sync handshakes (RT-38). */
+    loadAcceptedCycle(): Promise<number>;
+    /** Record an accepted sync handshake as `nodeId` (RT-38). */
+    markLocalNodeAccepted(nodeId: string): Promise<void>;
+    /** Record that the sync server refused `nodeId`; `held` holds its writes (RT-38). */
+    markLocalNodeRefused(nodeId: string, held: boolean): Promise<void>;
+    /**
+     * Take over another local node's unsynced writes (RT-40): resolves to a release
+     * function when no live tab uses `nodeId` (its lock is free), or null when one does.
+     * Without Web Locks (Node, old browsers) the node is assumed free.
+     */
+    claimLocalNode(nodeId: string): Promise<(() => void) | null>;
+    /** Whether a live tab holds `nodeId` (per-tab isolation, RT-40). */
+    isLocalNodeLive(nodeId: string): Promise<boolean>;
     rebaseUnsyncedOperations(unsyncedOpIds: string[], correctedNowMs: number): Promise<ClockRebaseResult>;
     /**
      * Count of local operations ahead of the server version vector.
      */
     countUnsyncedOperations(serverVector: VersionVector): Promise<number>;
     /**
-     * Compact the local operation log using materialized rows as the baseline.
-     * Only removes ops the server has acknowledged (per {@link CompactionStrategy}).
+     * Compact the local operation log. Only removes ops the server has acknowledged
+     * (per {@link CompactionStrategy}). With the W7 fold (STORE-14), the effect of the
+     * removed operations is first joined into each record's base fold state, so a
+     * re-fold (rejection exclusion, a later re-materialization) and the merge of a
+     * late operation stay exact; delete, atomic and custom-resolver operations are
+     * kept, and a re-delivered compacted id is a duplicate by its node's compacted
+     * prefix.
      */
     compact(strategy: CompactionStrategy): Promise<CompactionResult>;
     /**
@@ -971,13 +1727,47 @@ declare class Store implements OperationLog {
      */
     exportBackup(options?: BackupOptions): Promise<Uint8Array>;
     /**
-     * Restore data from a backup binary.
+     * Restore data from a backup binary (format version 2, STORE-5).
+     *
+     * - `merge: true`: every backup operation is applied through the remote-apply path
+     *   (deduplicated by id, merged per field), the version vector advances by MAX, and
+     *   nothing of the exporting device's identity or sync state is imported.
+     * - Replace (default): the data is replaced by the backup's while this device keeps
+     *   its node id, local nodes and principal bindings, its own sequence counters never
+     *   move backwards, and unsynced own writes are kept (see
+     *   `RestoreOptions.keepUnsyncedWrites`). Then {@link reloadFromDisk} runs.
+     *
+     * A version-1 file (Kora 1.0.0-beta.12 and earlier) is converted first, exactly as
+     * `convertBackupV1` does (`result.convertedFromVersion: 1`); one holding an operation
+     * whose timestamp cannot be recovered is refused (`BACKUP_OPERATION_INVALID`).
      *
      * @param data - The backup data
-     * @param options - Restore options (merge, collections, onProgress)
+     * @param options - Restore options (merge, collections, keepUnsyncedWrites, onProgress)
+     * @param internal - `applyOperation`: the app's remote-apply path (defaults to
+     *   {@link applyRemoteOperation}); `createApp` passes the merge-aware pipeline sync uses
      * @returns Result of the restore operation
      */
-    importBackup(data: Uint8Array, options?: RestoreOptions): Promise<RestoreResult>;
+    importBackup(data: Uint8Array, options?: RestoreOptions, internal?: {
+        applyOperation?: (operation: Operation) => Promise<ApplyResult>;
+    }): Promise<RestoreResult>;
+    /**
+     * Merge mode (RT-66): join the backup's compacted base states and row snapshots
+     * into this database's, and re-fold those records, before the backup's operations
+     * are applied. The join is the fold's state-based merge, so the result equals
+     * folding both devices' histories together. Compacted prefixes advance by MAX
+     * (unfiltered restores only: the prefix is per node, across collections).
+     */
+    private mergeBackupFoldState;
+    /**
+     * Re-read this store's state from the database after it changed underneath it (a
+     * backup restore): the node id, version vector and own sequence counter, the clock
+     * (advanced past every timestamp in the log), and a fresh causal tracker. Every live
+     * query re-runs. The local node registry and terminal rejections are always read
+     * from the database, so they need no reload.
+     */
+    reloadFromDisk(): Promise<void>;
+    /** The greatest HLC timestamp in the operation log (canonical strings sort by HLC). */
+    private loadNewestLogTimestamp;
     /**
      * Read backup manifest without loading the entire backup.
      *
@@ -986,21 +1776,35 @@ declare class Store implements OperationLog {
      */
     static readBackupManifest(data: Uint8Array): BackupManifest;
     private recordOperationSequence;
-    private allocateSequenceNumber;
-    /**
-     * Check the stored schema version and run any pending migrations.
-     * Migrations are applied in version order within a transaction.
-     */
-    private runMigrationsIfNeeded;
+    /** Post-commit publication of a committed local operation. */
+    private publishLocalOperation;
     /**
-     * Get the stored schema version from _kora_meta. Returns 0 if not set.
+     * Map an out-of-space storage failure to `store:quota-exceeded` (STORE-15).
+     * The error itself still propagates to the caller; this only makes the
+     * condition observable on every adapter, not just IndexedDB.
      */
-    private getStoredSchemaVersion;
+    private reportStorageError;
+    /** Report a database a newer build migrated (`store:schema-ahead`) and build the error. */
+    private schemaAhead;
     /**
-     * Run a backfill transform on all records in a collection.
-     * Reads all rows, applies the transform, and updates changed fields.
+     * Run pending schema migrations (STORE-13, NEW-STORE-1): one transaction per version
+     * (DDL, backfills, `schema_version`); backfills write operations through the local
+     * write path so they sync, unless declared `localOnly`.
      */
-    private runBackfill;
+    private runMigrationsIfNeeded;
+    /** The node id the database persisted before this open, if any. */
+    private readPersistedNodeId;
+    /**
+     * Register node ids this database authored under that the registry does not know
+     * yet: the node id a pinned `nodeId` (the auth device id) just replaced, and the
+     * authors of queued operations. A beta.12 database had no registry, and a template
+     * app created before its user signed in authored under a random node; once the
+     * store is pinned to the device id, that node's queued writes would otherwise sit in
+     * the queue forever, neither uploaded nor reported. Registered, they are adopted or
+     * held (`status.heldNodes`) like any other local node's writes. Only the outbound
+     * queue is read: received operations never enter it.
+     */
+    private registerUnregisteredAuthors;
     private loadOrGenerateNodeId;
     private loadSequenceNumber;
     private loadVersionVector;
@@ -1017,6 +1821,147 @@ interface CollectionAccessor {
     where(conditions: Record<string, unknown>): QueryBuilder;
 }
 
+declare const LAST_ACKED_SERVER_VECTOR_META_KEY = "last_acked_server_vector";
+/**
+ * Serialize a version vector for `_kora_meta` storage.
+ */
+declare function serializeVersionVectorToMeta(vector: VersionVector): string;
+/**
+ * Deserialize a version vector from `_kora_meta`.
+ */
+declare function deserializeVersionVectorFromMeta(value: string): VersionVector;
+/**
+ * Merge two version vectors, keeping the maximum sequence per node.
+ */
+declare function mergeVersionVectors(a: VersionVector, b: VersionVector): VersionVector;
+/**
+ * Operations present locally but not yet on the server (per server version vector).
+ */
+declare function collectOperationsAheadOfServer(localVector: VersionVector, serverVector: VersionVector, fetchRange: (nodeId: string, fromSeq: number, toSeq: number) => Promise<Operation[]>): Promise<Operation[]>;
+
+/**
+ * Normalise a `where` clause to its canonical form (RT-102). This is the ONE place that
+ * decides what a where value means, so the SQL the store runs, the descriptor and the
+ * query key (store cache, React/Vue/Svelte bindings) always agree:
+ *
+ * - `undefined` means "no condition": `where({ projectId: undefined })` is `where({})`
+ *   (the usual "nothing selected yet" pattern), and an operator whose operand is
+ *   `undefined` (`{ $gt: undefined }`) is dropped; a field left with no operator is
+ *   dropped. A later `.where({ x: undefined })` therefore does not remove an earlier
+ *   condition on `x`.
+ * - `null` means SQL `IS NULL` (`$ne: null` means `IS NOT NULL`).
+ * - Non-finite numbers (`NaN`, `Infinity`) have no stored representation: refused.
+ * - `undefined` inside a `$in` list is refused (ambiguous: no condition cannot be one
+ *   element of a list).
+ *
+ * @param where - The clause as the developer wrote it
+ * @returns A new clause with the rules above applied
+ * @throws {QueryError} For a non-finite number or an `undefined` `$in` element
+ */
+declare function normalizeWhere(where: WhereClause): WhereClause;
+/**
+ * The canonical identity of a query: equal keys if and only if the descriptors run the
+ * same query (RT-102). Used by the store's query-store cache and by every framework
+ * binding to decide when to share a store or re-subscribe.
+ *
+ * Unlike `JSON.stringify`, nothing is dropped or conflated: `where` keys are sorted
+ * (their order does not change the query), `undefined` is dropped exactly as
+ * {@link normalizeWhere} drops it, and `NaN`, `Date` and byte values keep distinct,
+ * typed encodings.
+ *
+ * @param descriptor - The query descriptor (`queryBuilder.getDescriptor()`)
+ * @returns A string key
+ */
+declare function queryKey(descriptor: QueryDescriptor): string;
+
+/**
+ * Durable-storage state of this origin, as far as Kora knows (NEW-STORE-4).
+ * - `unknown`: not checked yet (the boot check runs in the background).
+ * - `persisted`: the browser granted persistent storage; it will not evict this
+ *   origin's data under storage pressure.
+ * - `best-effort`: storage may be evicted under pressure (the browser default).
+ * - `unsupported`: the runtime has no StorageManager persistence API (Node,
+ *   older browsers, some WebViews).
+ * - `error`: the check or request threw; `lastError` says why.
+ */
+type StoragePersistenceState = 'unknown' | 'persisted' | 'best-effort' | 'unsupported' | 'error';
+/** Snapshot returned by `app.storage.persistence.status()`. */
+interface StoragePersistenceStatus {
+    state: StoragePersistenceState;
+    /** True only when the browser reported persistent storage. */
+    persisted: boolean;
+    /** True once `persist()` was asked for (explicitly or by an automatic trigger). */
+    requested: boolean;
+    /** Message of the last failure, when `state` is `error`. */
+    lastError?: string;
+}
+/** Why an automatic (background) persistence request was made. */
+type PersistenceRequestReason = 'explicit' | 'sign-in' | 'first-write' | 'installed-app';
+/** The subset of `navigator.storage` used here. */
+interface PersistenceStorageManager {
+    persist?: () => Promise<boolean>;
+    persisted?: () => Promise<boolean>;
+}
+/** Options for {@link StoragePersistence}. */
+interface StoragePersistenceOptions {
+    /** Receives `storage:persistence` events. */
+    emitter?: KoraEventEmitter | null;
+    /**
+     * The StorageManager to use. Defaults to `globalThis.navigator.storage`,
+     * resolved on each call so tests and late polyfills are honoured.
+     */
+    storage?: PersistenceStorageManager | null;
+}
+/**
+ * Tracks and requests durable storage (`navigator.storage.persist()`) without ever
+ * putting it on the startup path (NEW-STORE-4).
+ *
+ * In Firefox `persist()` opens a permission prompt and its promise stays pending
+ * until the user answers, so awaiting it inside startup could hang `app.ready`
+ * forever. Kora therefore:
+ * - checks `persisted()` at boot, which never prompts, in the background;
+ * - requests persistence only on an explicit `request()` or, without awaiting,
+ *   after a meaningful moment (sign-in, the first local write, running as an
+ *   installed app);
+ * - surfaces every result through `status()` and the `storage:persistence` event,
+ *   never by blocking.
+ */
+declare class StoragePersistence {
+    private current;
+    private inFlightRequest;
+    private readonly emitter;
+    private readonly storageOverride;
+    constructor(options?: StoragePersistenceOptions);
+    /** Synchronous snapshot of the last known state. Never prompts. */
+    status(): StoragePersistenceStatus;
+    /**
+     * Read whether storage is already persistent (`navigator.storage.persisted()`).
+     * Never prompts and never throws: a failure becomes `state: 'error'`.
+     */
+    check(): Promise<StoragePersistenceStatus>;
+    /**
+     * Ask the browser for persistent storage (`navigator.storage.persist()`).
+     * May show a permission prompt (Firefox), so call it from a user gesture or a
+     * meaningful moment, and do not block rendering on it. Concurrent calls share
+     * one request. Never throws: a failure becomes `state: 'error'`.
+     *
+     * @returns The state after the browser answered
+     */
+    request(): Promise<StoragePersistenceStatus>;
+    /**
+     * Fire-and-forget `request()` for an automatic trigger. Never awaited by Kora,
+     * so a pending prompt cannot block anything; the outcome arrives as a
+     * `storage:persistence` event. Skipped when storage is already persistent or a
+     * request was already made this session.
+     *
+     * @param _reason - Which trigger fired (kept for tracing at call sites)
+     */
+    requestInBackground(_reason: PersistenceRequestReason): void;
+    private storage;
+    private update;
+    private emit;
+}
+
 /**
  * Bridges the async QueryBuilder.subscribe() API with synchronous snapshot reads
  * required by React useSyncExternalStore, Vue composables, and Svelte stores.
@@ -1030,6 +1975,7 @@ declare class QueryStore<T = CollectionRecord> {
     private unsubscribeQuery;
     private active;
     private hasEmittedSnapshot;
+    private error;
     private readonly queryBuilder;
     constructor(queryBuilder: QueryBuilder<T>);
     /**
@@ -1045,6 +1991,12 @@ declare class QueryStore<T = CollectionRecord> {
      * authoritative result for the current subscription lifecycle.
      */
     hasSnapshot: () => boolean;
+    /**
+     * The latest query failure, or null. Set when the query (or a re-run after a
+     * write) fails; cleared by the next successful delivery. Listeners are notified
+     * on both transitions, so bindings read it next to `getSnapshot()`.
+     */
+    getError: () => Error | null;
     /** Tear down listeners and the underlying query subscription. */
     destroy(): void;
     private startSubscription;
@@ -1282,6 +2234,12 @@ interface RichTextControllerSnapshot {
     canUndo: boolean;
     canRedo: boolean;
     cursors: readonly RichTextCursorInfo[];
+    /**
+     * True while local edits are not in a successful save: a save is pending, in
+     * flight, or was refused (see `error`). The edits stay in the live document and
+     * are saved by the next edit or `retrySave()`.
+     */
+    hasUnsavedChanges: boolean;
 }
 interface RichTextController {
     readonly doc: yjs.Doc;
@@ -1293,12 +2251,29 @@ interface RichTextController {
     setCursor(anchor: number, head: number): void;
     clearCursor(): void;
     setUser(user: RichTextAwarenessUser | undefined): void;
+    /**
+     * Save the live document now (for example after a refused save, once the cause
+     * is fixed). Resolves when the save settled; its outcome is in the snapshot.
+     */
+    retrySave(): Promise<void>;
+    /**
+     * The full document state (a Yjs update) while local edits are unsaved, else
+     * null. Keep it as a recovery copy when saves keep failing.
+     */
+    getUnsavedState(): Uint8Array | null;
+    /** Stop syncing; edits still waiting for the debounced save are saved first. */
     destroy(): void;
 }
 
 /**
  * Framework-agnostic richtext binding: Yjs document lifecycle, persistence,
  * incremental doc channel, and awareness cursors.
+ *
+ * Every save writes the full state of the live Y.Doc, which holds every local edit
+ * and every merged remote change, so a stored change arriving while a save waits
+ * cannot drop local typing. A refused save keeps the edits unsaved
+ * (`hasUnsavedChanges`, `getUnsavedState()`) and the next edit or `retrySave()`
+ * saves them again; the first successful save clears `error`.
  */
 declare function createRichTextController(options: CreateRichTextControllerOptions): RichTextController;
 
@@ -1360,14 +2335,22 @@ declare function pluralize(word: string): string;
  */
 declare function singularize(word: string): string;
 
+/** Current backup format version. */
+declare const BACKUP_VERSION = 2;
+/** A backup file this release cannot restore as-is. */
+declare class BackupFormatError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
 /**
- * Export a backup from a store.
+ * Export a backup (format version 2) from an opened database.
  *
- * Reads all data via the adapter and produces a portable binary backup.
+ * Everything is read inside one transaction, so the backup is a consistent snapshot.
+ * Operations are exported in canonical form (exactly what `deserializeOperation` reads
+ * back), including tombstones, so a restore rebuilds the same log.
  *
  * @param adapter - The storage adapter
  * @param schema - The schema definition
- * @param nodeId - Current node ID
+ * @param nodeId - Node id of the exporting device (informational only; never imported)
  * @param schemaVersion - Schema version
  * @param options - Backup options
  * @returns Backup as a Uint8Array
@@ -1375,7 +2358,6 @@ declare function singularize(word: string): string;
 declare function exportBackup(adapter: StorageAdapter, schema: SchemaDefinition, nodeId: string, schemaVersion: number, options?: BackupOptions): Promise<Uint8Array>;
 /**
  * Read backup manifest without loading the entire backup.
- * Parses only the first section (which is always the manifest).
  *
  * @param data - The raw backup data
  * @returns The backup manifest
@@ -1388,14 +2370,41 @@ declare function readBackupManifest(data: Uint8Array): BackupManifest;
  * @returns True if the checksum is valid
  */
 declare function verifyBackupChecksum(data: Uint8Array): Promise<boolean>;
+/** Options for {@link convertBackupV1}. */
+interface ConvertBackupV1Options {
+    /**
+     * Drop operations whose timestamp cannot be recovered instead of refusing the file.
+     * Default false.
+     */
+    dropUnrecoverable?: boolean;
+}
 /**
- * Restore a backup into a store.
+ * Convert a version-1 backup (Kora 1.0.0-beta.12 and earlier) to version 2.
  *
- * @param adapter - The storage adapter
+ * - Operations: a v1 file exported from a database that a v1 restore had damaged holds
+ *   misread timestamps (`wallTime: null`); they are recovered from the misread values
+ *   (the same rule as the log-integrity scan). An unrecoverable one refuses the file
+ *   unless `dropUnrecoverable` is set.
+ * - The `meta` section (the exporting device's node id, node tokens, sync state) is
+ *   dropped: it must never be imported into another database.
+ * - Record rows are kept; v1 exported live rows only, so the manifest records
+ *   `includesTombstones: false`. Bytes that v1 serialized as `{"0":..,"1":..}` objects
+ *   are decoded on restore.
+ *
+ * @throws {BackupFormatError} When the input is not a valid version-1 backup
+ */
+declare function convertBackupV1(data: Uint8Array, options?: ConvertBackupV1Options): Promise<Uint8Array>;
+/**
+ * Restore a backup into the database behind `adapter`.
+ *
+ * @deprecated Use `store.importBackup()` / `app.importBackup()`: restoring needs the
+ *   store (the device's identity, version vector, clock and live queries). This entry
+ *   point opens a temporary `Store` on `adapter`, imports, and CLOSES the adapter.
+ *
+ * @param adapter - A storage adapter no store is using
  * @param schema - The schema definition
  * @param data - The backup data
  * @param options - Restore options
- * @returns Result of the restore operation
  */
 declare function restoreBackup(adapter: StorageAdapter, schema: SchemaDefinition, data: Uint8Array, options?: RestoreOptions): Promise<RestoreResult>;
 
@@ -1471,8 +2480,8 @@ declare class OpfsBlobStore implements ContentAddressedBlobStore {
 }
 /**
  * Create an {@link OpfsBlobDirectory} backed by the browser's Origin Private
- * File System, rooted at a named subdirectory. Best-effort requests persistent
- * storage so the browser is less likely to evict blobs under storage pressure.
+ * File System, rooted at a named subdirectory. It does not request persistent
+ * storage: that is `app.storage.persistence`, kept off the startup path.
  *
  * @param rootDirName - The OPFS subdirectory to store blobs under (default `kora-blobs`)
  * @throws {Error} If OPFS is unavailable (e.g. called outside a browser)
@@ -1759,6 +2768,13 @@ interface ChunkResponseMessage {
     requestId: string;
     /** The chunk bytes, or null when the responder does not hold that hash. */
     bytes: Uint8Array | null;
+    /**
+     * The server refused the request for rate, not because the chunk is missing
+     * (RT-24). The requester retries after `retryAfterMs` instead of failing.
+     */
+    throttled?: boolean;
+    /** With `throttled`: how long to wait before retrying, in ms. */
+    retryAfterMs?: number;
 }
 type ChunkMessage = ChunkRequestMessage | ChunkResponseMessage;
 /**
@@ -1776,18 +2792,35 @@ interface RemoteChunkProvider extends ChunkProvider {
     /** Number of requests still awaiting a response (for diagnostics/tests). */
     pendingCount(): number;
 }
+/** Options for {@link createRemoteChunkProvider}. */
+interface RemoteChunkProviderOptions {
+    /** Per-attempt timeout in ms (default 30s). */
+    timeoutMs?: number;
+    /**
+     * Longest total time one chunk may spend waiting on "throttled" answers before
+     * the request fails (default 10 minutes). The transfer is resumable, so a failed
+     * request can simply be retried later.
+     */
+    maxThrottleWaitMs?: number;
+    /** Smallest back-off after a throttled answer, in ms (default 250). */
+    minThrottleDelayMs?: number;
+    /** Largest single back-off after a throttled answer, in ms (default 30s). */
+    maxThrottleDelayMs?: number;
+}
 /**
  * Create a {@link ChunkProvider} that requests chunks over a message port,
  * correlating each answer to its request and timing out a stalled request so a
  * dropped response cannot hang a transfer forever (the transfer is resumable, so
  * a timed-out request can simply be retried).
  *
+ * A "throttled" answer (the server's blob request budget is spent, RT-24) is not a
+ * failure: the request is re-sent after the server's `retryAfterMs` (bounded, with
+ * exponential back-off when absent), until `maxThrottleWaitMs` has elapsed.
+ *
  * @param port - The message port to the peer that holds the blob
- * @param options.timeoutMs - Per-request timeout (default 30s)
+ * @param options - Timeouts and throttle back-off bounds
  */
-declare function createRemoteChunkProvider(port: ChunkMessagePort, options?: {
-    timeoutMs?: number;
-}): RemoteChunkProvider;
+declare function createRemoteChunkProvider(port: ChunkMessagePort, options?: RemoteChunkProviderOptions): RemoteChunkProvider;
 /**
  * Serve blob chunk requests arriving on a message port from a blob store. Answers
  * each `blob-chunk-request` with the bytes for that hash, or null when the store
@@ -1807,4 +2840,4 @@ declare function createChunkPortPair(): {
     b: ChunkMessagePort;
 };
 
-export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, type BlobGcOptions, type BlobGcResult, type BlobManifest, type BlobManifestMetadata, COMPACTION_BASELINE_META_KEY, type ChunkMessage, type ChunkMessagePort, type ChunkProvider, type ChunkRequestMessage, type ChunkResponseMessage, type ClockRebaseResult, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, ContentAddressedBlobStore, type CreateRichTextControllerOptions, DEFAULT_CHUNK_SIZE, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, MemoryBlobStore, NoLeaderError, type OpfsBlobDirectory, OpfsBlobStore, OptimisticLockError, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, type ReceiveBlobResult, type ReceiveBlobStores, RecordNotFoundError, type RemoteChunkProvider, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, RowVersionState, SequenceManager, type ServerBlobCallbacks, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, chunkBlob, collectBlobGarbage, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createChunkPortPair, createMemoryServerBlobStore, createOpfsBlobDirectory, createOpfsBlobStore, createRemoteChunkProvider, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, extractBlobRefs, fetchBlobManifest, getSharedQueryStoreCache, mergeVersionVectors, parseBlobManifest, persistedAuditTraceFromEvent, pluralize, prepareBlobForSend, putBlobForTransfer, readAuditExportManifest, readBackupManifest, reassembleBlob, receiveBlob, resolveBlobManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeBlobManifest, serializeVersionVectorToMeta, serveBlobChunks, singularize, toServerBlobCallbacks, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };
+export { AdapterError, AdoptionSchedule, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, BACKUP_VERSION, BackupFormatError, type BackupManifest, type BackupOptions, type BackupProgress, type BlobGcOptions, type BlobGcResult, type BlobManifest, type BlobManifestMetadata, BridgeTerminatedError, COMPACTION_BASELINE_META_KEY, type ChunkMessage, type ChunkMessagePort, type ChunkProvider, type ChunkRequestMessage, type ChunkResponseMessage, type ClockRebaseResult, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, ContentAddressedBlobStore, type ConvertBackupV1Options, type CreateRichTextControllerOptions, DEFAULT_CHUNK_SIZE, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LOG_QUARANTINE_TABLE, LeaderUnresponsiveError, LocalMutationHandler, LocalNodeRecord, type LogIntegrityReport, type LogIntegrityRow, type LogRowProblem, type LogSequenceGap, MaterializedRowSnapshot, MemoryBlobStore, NoLeaderError, NodeOwnedByAnotherUserError, type NodeRotationResult, type OpfsBlobDirectory, OpfsBlobStore, OptimisticLockError, OrderByDirection, type PersistedAuditTrace, PersistenceError, type PersistenceRequestReason, type PersistenceStorageManager, type PrincipalBinding, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, QuerySubscriptionError, type ReceiveBlobResult, type ReceiveBlobStores, RecordNotFoundError, type RecordsChange, type RecordsChangeListener, type RegisterOptions, type RematerializationMode, type RemoteChunkProvider, type RemoteChunkProviderOptions, type ReplaySnapshot, RequestAbortedError, type ResequenceResult, type RestoreOptions, type RestoreResult, type ResultsEqual, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, RowVersionState, SchemaVersionAheadError, SequenceManager, type ServerBlobCallbacks, StorageAdapter, StorageBackendMismatchError, StorageDurabilityError, StorageInUseError, StoragePersistence, type StoragePersistenceOptions, type StoragePersistenceState, type StoragePersistenceStatus, Store, StoreConfig, StoreNotOpenError, SubscribeOptions, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, TerminalRejection, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, type UnappliedOperation, UnsyncedDataError, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, chunkBlob, collectBlobGarbage, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, convertBackupV1, createChunkPortPair, createMemoryServerBlobStore, createOpfsBlobDirectory, createOpfsBlobStore, createRemoteChunkProvider, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, extractBlobRefs, fetchBlobManifest, getSharedQueryStoreCache, mergeVersionVectors, normalizeWhere, parseBlobManifest, persistedAuditTraceFromEvent, pluralize, prepareBlobForSend, putBlobForTransfer, queryKey, readAuditExportManifest, readBackupManifest, reassembleBlob, receiveBlob, resolveBlobManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeBlobManifest, serializeVersionVectorToMeta, serveBlobChunks, singularize, toServerBlobCallbacks, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };