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

package/dist/index.d.cts

@@ -2,8 +2,8 @@ import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, d as
 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.cjs';
 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, j as LocalDeleteHook, k as RecordFolder, L as LocalMutationContext, A as AdoptionSchedule, T as TerminalRejection, l as LocalNodeRecord } from './sql-builder-C4u55jKW.cjs';
-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-C4u55jKW.cjs';
+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-D0tC3sv9.cjs';
+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-D0tC3sv9.cjs';
 import * as yjs from 'yjs';
 import { C as ContentAddressedBlobStore, M as MemoryBlobStore } from './content-addressed-blob-store-Dcj3SB9r.cjs';
 export { B as BlobIntegrityError } from './content-addressed-blob-store-Dcj3SB9r.cjs';
@@ -157,6 +157,14 @@ declare class StorageBackendMismatchError 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.
@@ -396,8 +404,13 @@ interface RestoreResult {
     success: boolean;
     /** Error message if failed */
     error?: string;
-    /** Error code if failed (`BACKUP_FORMAT_OUTDATED`, `BACKUP_CHECKSUM_MISMATCH`, ...) */
+    /** 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`).
@@ -924,6 +937,10 @@ interface TransactionContextConfig {
     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.
@@ -1038,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;
@@ -1485,6 +1508,23 @@ declare class Store implements OperationLog {
      * @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
@@ -1525,6 +1565,19 @@ declare class Store implements OperationLog {
      * @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.
@@ -1684,8 +1737,9 @@ declare class Store implements OperationLog {
      *   move backwards, and unsynced own writes are kept (see
      *   `RestoreOptions.keepUnsyncedWrites`). Then {@link reloadFromDisk} runs.
      *
-     * A version-1 file is refused (`errorCode: 'BACKUP_FORMAT_OUTDATED'`); convert it with
-     * `convertBackupV1`.
+     * 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, keepUnsyncedWrites, onProgress)
@@ -1738,6 +1792,19 @@ declare class Store implements OperationLog {
      * write path so they sync, unless declared `localOnly`.
      */
     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;
@@ -2167,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;
@@ -2178,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;
 
@@ -2750,4 +2840,4 @@ declare function createChunkPortPair(): {
     b: ChunkMessagePort;
 };
 
-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, 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 };
+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 };

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, d as
 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, j as LocalDeleteHook, k as RecordFolder, L as LocalMutationContext, A as AdoptionSchedule, T as TerminalRejection, l as LocalNodeRecord } from './sql-builder-CGckdBDL.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-CGckdBDL.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';
@@ -157,6 +157,14 @@ declare class StorageBackendMismatchError 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.
@@ -396,8 +404,13 @@ interface RestoreResult {
     success: boolean;
     /** Error message if failed */
     error?: string;
-    /** Error code if failed (`BACKUP_FORMAT_OUTDATED`, `BACKUP_CHECKSUM_MISMATCH`, ...) */
+    /** 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`).
@@ -924,6 +937,10 @@ interface TransactionContextConfig {
     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.
@@ -1038,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;
@@ -1485,6 +1508,23 @@ declare class Store implements OperationLog {
      * @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
@@ -1525,6 +1565,19 @@ declare class Store implements OperationLog {
      * @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.
@@ -1684,8 +1737,9 @@ declare class Store implements OperationLog {
      *   move backwards, and unsynced own writes are kept (see
      *   `RestoreOptions.keepUnsyncedWrites`). Then {@link reloadFromDisk} runs.
      *
-     * A version-1 file is refused (`errorCode: 'BACKUP_FORMAT_OUTDATED'`); convert it with
-     * `convertBackupV1`.
+     * 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, keepUnsyncedWrites, onProgress)
@@ -1738,6 +1792,19 @@ declare class Store implements OperationLog {
      * write path so they sync, unless declared `localOnly`.
      */
     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;
@@ -2167,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;
@@ -2178,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;
 
@@ -2750,4 +2840,4 @@ declare function createChunkPortPair(): {
     b: ChunkMessagePort;
 };
 
-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, 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 };
+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 };

package/dist/index.js

@@ -20,7 +20,7 @@ import {
   pluralize,
   queryKey,
   singularize
-} from "./chunk-Y5LRH7KI.js";
+} from "./chunk-5AQSGMJV.js";
 import {
   BlobIntegrityError,
   MemoryBlobStore
@@ -29,7 +29,7 @@ import {
   InvalidStateTransitionError,
   validateStateTransition,
   validateUpdateStateMachine
-} from "./chunk-HZTDBLDB.js";
+} from "./chunk-BILSA6XZ.js";
 import "./chunk-A6GFH5IG.js";
 import {
   BACKUP_VERSION,
@@ -41,10 +41,10 @@ import {
   readBackupManifest,
   restoreBackup,
   verifyBackupChecksum
-} from "./chunk-P4V375FY.js";
+} from "./chunk-UC2LGFPV.js";
 import {
   mergeYjsUpdates
-} from "./chunk-32EDKWMI.js";
+} from "./chunk-KTVNANUH.js";
 import {
   LAST_ACKED_SERVER_VECTOR_META_KEY,
   VIRTUAL_TIMESTAMP_FIELDS,
@@ -53,7 +53,7 @@ import {
   deserializeVersionVectorFromMeta,
   mergeVersionVectors,
   serializeVersionVectorToMeta
-} from "./chunk-SJP2HTYZ.js";
+} from "./chunk-QW4UU7NG.js";
 import {
   decodeRichtext,
   encodeRichtext,
@@ -65,6 +65,7 @@ import {
   BridgeTerminatedError,
   LeaderUnresponsiveError,
   NoLeaderError,
+  NodeOwnedByAnotherUserError,
   OptimisticLockError,
   PersistenceError,
   QueryError,
@@ -78,7 +79,7 @@ import {
   UnsyncedDataError,
   WorkerInitError,
   WorkerTimeoutError
-} from "./chunk-DUKTWVZW.js";
+} from "./chunk-SRHDJF5B.js";
 
 // src/persistence/storage-persistence.ts
 function defaultStorageManager() {
@@ -355,7 +356,6 @@ var LOAD_ORIGIN = "kora-load";
 var REMOTE_ORIGIN = "kora-remote";
 var DOC_CHANNEL_ORIGIN = "kora-doc-channel";
 var TEXT_KEY = "content";
-var COMPACT_AFTER_DELTAS = 20;
 var PERSIST_DEBOUNCE_MS = 400;
 function createRichTextController(options) {
   const {
@@ -377,16 +377,19 @@ function createRichTextController(options) {
   let canUndo = false;
   let canRedo = false;
   let cursors = [];
+  let editGeneration = 0;
+  let savedGeneration = 0;
+  let saving = null;
+  let saveAgain = false;
   const listeners = /* @__PURE__ */ new Set();
   let snapshot = {
     ready: false,
     error: null,
     canUndo: false,
     canRedo: false,
-    cursors: []
+    cursors: [],
+    hasUnsavedChanges: false
   };
-  const baseUpdateRef = { current: null };
-  const pendingDeltasRef = { current: [] };
   const docChannelActiveRef = { current: false };
   let persistTimer = null;
   let recordUnsubscribe = null;
@@ -398,7 +401,8 @@ function createRichTextController(options) {
       error,
       canUndo,
       canRedo,
-      cursors: [...cursors]
+      cursors: [...cursors],
+      hasUnsavedChanges: editGeneration > savedGeneration
     };
   };
   const notify = () => {
@@ -469,26 +473,38 @@ function createRichTextController(options) {
       return;
     }
     Y.applyUpdate(doc, encoded, REMOTE_ORIGIN);
-    baseUpdateRef.current = encoded;
-    pendingDeltasRef.current = [];
     syncHistoryState();
   };
-  const flushPersist = async () => {
-    const snapshot2 = composeRichtextSnapshot(baseUpdateRef.current, pendingDeltasRef.current);
-    if (pendingDeltasRef.current.length >= COMPACT_AFTER_DELTAS) {
-      baseUpdateRef.current = snapshot2;
-      pendingDeltasRef.current = [];
-    }
+  const persistOnce = async () => {
+    const generation = editGeneration;
+    const state = Y.encodeStateAsUpdate(doc);
     try {
       await collection.update(recordId, {
-        [fieldName]: snapshot2
+        [fieldName]: state
       });
+      if (generation > savedGeneration) savedGeneration = generation;
+      error = null;
     } catch (cause) {
-      if (!disposed) {
-        error = cause instanceof Error ? cause : new Error(String(cause));
-        notify();
-      }
+      error = cause instanceof Error ? cause : new Error(String(cause));
     }
+    if (!disposed) notify();
+  };
+  const flushPersist = () => {
+    if (saving) {
+      saveAgain = true;
+      return saving;
+    }
+    const run = (async () => {
+      do {
+        saveAgain = false;
+        await persistOnce();
+      } while (saveAgain);
+    })();
+    saving = run;
+    void run.finally(() => {
+      if (saving === run) saving = null;
+    });
+    return run;
   };
   const schedulePersist = () => {
     if (persistTimer) {
@@ -504,7 +520,7 @@ function createRichTextController(options) {
     if (origin === LOAD_ORIGIN || origin === REMOTE_ORIGIN || origin === DOC_CHANNEL_ORIGIN) {
       return;
     }
-    pendingDeltasRef.current.push(update);
+    editGeneration += 1;
     if (docChannelActiveRef.current && syncEngine) {
       syncEngine.getRichtextDocChannel?.().send(collectionName, recordId, fieldName, update);
       schedulePersist();
@@ -588,8 +604,6 @@ function createRichTextController(options) {
         target.delete(0, target.length);
       }, LOAD_ORIGIN);
       const encoded = encodeRichtextInput(record?.[fieldName]);
-      baseUpdateRef.current = encoded;
-      pendingDeltasRef.current = [];
       if (encoded) {
         Y.applyUpdate(doc, encoded, LOAD_ORIGIN);
       }
@@ -632,6 +646,16 @@ function createRichTextController(options) {
     setUser(nextUser) {
       user = nextUser;
     },
+    retrySave() {
+      if (persistTimer) {
+        clearTimeout(persistTimer);
+        persistTimer = null;
+      }
+      return flushPersist();
+    },
+    getUnsavedState() {
+      return editGeneration > savedGeneration ? Y.encodeStateAsUpdate(doc) : null;
+    },
     destroy() {
       if (disposed) {
         return;
@@ -641,14 +665,15 @@ function createRichTextController(options) {
         clearTimeout(persistTimer);
         persistTimer = null;
       }
+      if (editGeneration > savedGeneration) {
+        void flushPersist();
+      }
       doc.off("update", onDocUpdate);
       recordUnsubscribe?.();
       docChannelUnsubscribe?.();
       awarenessUnsubscribe?.();
       clearCursor();
       undoManager.destroy();
-      baseUpdateRef.current = null;
-      pendingDeltasRef.current = [];
       docChannelActiveRef.current = false;
       listeners.clear();
     }
@@ -669,16 +694,6 @@ function encodeRichtextInput(value) {
     throw new Error("Richtext record value must be a string, Uint8Array, ArrayBuffer, or null.");
   }
 }
-function composeRichtextSnapshot(base, deltas) {
-  const mergedDoc = new Y.Doc();
-  if (base) {
-    Y.applyUpdate(mergedDoc, base);
-  }
-  for (const delta of deltas) {
-    Y.applyUpdate(mergedDoc, delta);
-  }
-  return Y.encodeStateAsUpdate(mergedDoc);
-}
 function updatesEqual(left, right) {
   if (left.length !== right.length) {
     return false;
@@ -1241,6 +1256,7 @@ export {
   LeaderUnresponsiveError,
   MemoryBlobStore,
   NoLeaderError,
+  NodeOwnedByAnotherUserError,
   OpfsBlobStore,
   OptimisticLockError,
   PersistenceError,