@korajs/store 0.5.0 → 1.0.0-beta.0

package/dist/index.d.cts

@@ -1,9 +1,10 @@
-import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, c as SubscriptionCallback, W as WhereClause, d as OrderByDirection, L as LocalMutationHandler, e as StoreConfig, A as ApplyRemoteOptions, f as MaterializedRowSnapshot } from './types-DepnRDk_.cjs';
-export { M as MigrationPlan, g as OrderByClause, h as StoreIsolation, T as Transaction, i as TransactionBufferedEntry, j as TransactionCommitBatch, k as TransactionCommitResult, l as WhereOperators } from './types-DepnRDk_.cjs';
-import { Operation, KoraError, VersionVector, SchemaDefinition, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraEvent } from '@korajs/core';
+import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, c as SubscriptionCallback, W as WhereClause, d as OrderByDirection, L as LocalMutationHandler, e as StoreConfig, A as ApplyRemoteOptions, f as MaterializedRowSnapshot, g as RowVersionState } from './types-CJOVKxLw.cjs';
+export { M as MigrationPlan, h as OrderByClause, i as StoreIsolation, T as Transaction, j as TransactionBufferedEntry, k as TransactionCommitBatch, l as TransactionCommitResult, m as WhereOperators } from './types-CJOVKxLw.cjs';
+import { Operation, KoraError, VersionVector, SchemaDefinition, HLCTimestamp, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraBytesValue, KoraEvent } from '@korajs/core';
 export { ApplyResult } from '@korajs/core';
-import { R as RelationEnforcer, L as LocalMutationContext } from './types-CTr00g_d.cjs';
-export { C as Collection } from './types-CTr00g_d.cjs';
+import { R as RelationEnforcer, L as LocalMutationContext } from './types-CyjXwrjW.cjs';
+export { C as Collection } from './types-CyjXwrjW.cjs';
+import * as yjs from 'yjs';
 
 /**
  * In-memory materialized state at a causal cut in the operation log.
@@ -32,6 +33,18 @@ declare class QueryError extends KoraError {
 declare class RecordNotFoundError extends KoraError {
     constructor(collection: string, recordId: string);
 }
+/**
+ * Thrown inside `applyRemoteOperation` when the row's version state changed
+ * between the caller's snapshot read and the guarded write (a concurrent local
+ * mutation landed in the window). The transaction is rolled back with nothing
+ * written; the caller re-reads fresh state, recomputes its merge, and retries.
+ * This is the optimistic-concurrency guard that keeps merge-engine results
+ * (richtext, add-wins arrays, constraint resolutions) from clobbering newer
+ * local edits they never saw.
+ */
+declare class OptimisticLockError extends KoraError {
+    constructor(collection: string, recordId: string);
+}
 /**
  * Thrown when a storage adapter operation fails.
  */
@@ -100,6 +113,20 @@ declare function computeAckCompactionWatermark(serverVector: VersionVector): Ver
  */
 declare function compactOperationLog(adapter: StorageAdapter, schema: SchemaDefinition, strategy: CompactionStrategy, serverVector: VersionVector): Promise<CompactionResult>;
 
+/**
+ * Result of re-stamping unsynced operations after a clock correction.
+ */
+interface ClockRebaseResult {
+    /** The rewritten operations, in causal order (original HLC total order preserved). */
+    operations: Operation[];
+    /** Maps each old (pre-rebase) operation id to its new content-addressed id. */
+    idMapping: Record<string, string>;
+    /** Number of operations that were re-stamped. */
+    rebasedCount: number;
+    /** Highest timestamp assigned during the rebase, or null when nothing was rebased. */
+    newMaxTimestamp: HLCTimestamp | null;
+}
+
 declare const LAST_ACKED_SERVER_VECTOR_META_KEY = "last_acked_server_vector";
 /**
  * Serialize a version vector for `_kora_meta` storage.
@@ -714,6 +741,12 @@ declare class Store implements OperationLog {
     /**
      * Get the node ID for this store instance.
      */
+    /**
+     * Records the offset between server time and this device's clock
+     * (serverTime - localTime), learned at sync handshake. Lets the store's HLC
+     * validate remote timestamps correctly even when the local clock is wrong.
+     */
+    setClockReferenceOffset(offsetMs: number): void;
     getNodeId(): string;
     /**
      * Apply a remote operation received from sync.
@@ -721,6 +754,18 @@ declare class Store implements OperationLog {
      * and updates the version vector.
      */
     applyRemoteOperation(op: Operation, options?: ApplyRemoteOptions): Promise<ApplyResult>;
+    /**
+     * Materialize update/delete operations that were logged for a record BEFORE
+     * its insert arrived (reordered delivery). Runs inside the insert's write
+     * transaction, folding each orphan in timestamp order through the exact
+     * per-field LWW / LWW-delete rules the normal apply paths use, so the final
+     * row state equals what a device that received the operations in causal
+     * order computed. Called only when the insert created a previously-absent
+     * row — in that case every logged update/delete for the record is
+     * necessarily an orphan (rows are soft-deleted, never removed, so a row
+     * that is absent now was never materialized).
+     */
+    private foldOrphanedOperations;
     /**
      * Get operations from a node within a sequence number range.
      * Implements the OperationLog interface for computeDelta.
@@ -774,6 +819,14 @@ declare class Store implements OperationLog {
      * Load a materialized row by ID, including soft-deleted tombstones.
      */
     findMaterializedRow(collection: string, recordId: string): Promise<MaterializedRowSnapshot | null>;
+    /**
+     * Raw version state of a materialized row, for optimistic-concurrency guarded
+     * applies: capture this snapshot before computing a merge, pass it as
+     * `guardRowState`, and the apply refuses to write if the row changed since.
+     * Returns null when no row exists (which is itself a valid guard state — the
+     * apply then requires the row to still be absent).
+     */
+    getRowVersionState(collection: string, recordId: string): Promise<RowVersionState | null>;
     /**
      * Latest operation from this device for a record (used for delete-vs-update merge on sync).
      */
@@ -797,6 +850,18 @@ declare class Store implements OperationLog {
      * Local operations not yet reflected on the server version vector.
      */
     getUnsyncedOperations(serverVector: VersionVector): Promise<Operation[]>;
+    /**
+     * Re-stamp never-acknowledged local operations after a fast device clock was
+     * corrected, so sync can resume immediately. Safe because unacknowledged
+     * operations are private to this device (like unpushed git commits);
+     * acknowledged/shared operations are immutable and never touched.
+     *
+     * After the rewrite the store's HLC is advanced past the highest new
+     * timestamp so subsequent local writes keep sorting after the rebased ops.
+     * No data-change notifications are emitted: materialized values are
+     * unchanged, only version stamps move.
+     */
+    rebaseUnsyncedOperations(unsyncedOpIds: string[], correctedNowMs: number): Promise<ClockRebaseResult>;
     /**
      * Count of local operations ahead of the server version vector.
      */
@@ -896,6 +961,62 @@ interface CollectionAccessor {
     where(conditions: Record<string, unknown>): QueryBuilder;
 }
 
+/**
+ * Bridges the async QueryBuilder.subscribe() API with synchronous snapshot reads
+ * required by React useSyncExternalStore, Vue composables, and Svelte stores.
+ *
+ * Uses lazy subscription: the underlying query subscription starts when the first
+ * listener attaches and stops when the last listener detaches.
+ */
+declare class QueryStore<T = CollectionRecord> {
+    private snapshot;
+    private listeners;
+    private unsubscribeQuery;
+    private active;
+    private readonly queryBuilder;
+    constructor(queryBuilder: QueryBuilder<T>);
+    /**
+     * Subscribe to snapshot changes.
+     *
+     * @returns Unsubscribe function
+     */
+    subscribe: (onStoreChange: () => void) => (() => void);
+    /** Synchronous read of the latest query results. */
+    getSnapshot: () => readonly T[];
+    /** Tear down listeners and the underlying query subscription. */
+    destroy(): void;
+    private startSubscription;
+    private stopSubscription;
+    private notifyListeners;
+}
+
+/**
+ * Ensures a query builder is backed by an open store (not a legacy pending placeholder).
+ */
+declare function assertQueryReady(query: QueryBuilder<unknown>): void;
+
+/**
+ * Reference-counted cache of {@link QueryStore} instances keyed by query descriptor.
+ * Identical queries from different components share one underlying subscription.
+ */
+declare class QueryStoreCache {
+    private readonly scopeKey;
+    private entries;
+    constructor(scopeKey?: string);
+    getOrCreate<T>(queryBuilder: QueryBuilder<T>): QueryStore<T>;
+    release(queryBuilder: QueryBuilder<unknown>): void;
+    clear(): void;
+    get size(): number;
+    private getKey;
+}
+/**
+ * Process-wide shared query store cache for framework bindings.
+ *
+ * @deprecated Prefer {@link KoraApp.getQueryStoreCache} via `KoraProvider` context
+ * so each app instance owns an isolated cache.
+ */
+declare function getSharedQueryStoreCache(): QueryStoreCache;
+
 /**
  * Bloom filter for subscription dependency tracking.
  *
@@ -1040,11 +1161,102 @@ declare function validateStateTransition(collectionName: string, recordId: strin
  */
 declare function validateUpdateStateMachine(collectionName: string, recordId: string, collectionDef: CollectionDefinition, currentRecord: Record<string, unknown>, updateData: Record<string, unknown>): Record<string, unknown>;
 
+/** User identity for collaborative cursor presence. */
+interface RichTextAwarenessUser {
+    name: string;
+    color: string;
+    avatar?: string;
+}
+/** Remote collaborator cursor for a richtext field. */
+interface RichTextCursorInfo {
+    clientId: number;
+    userName: string;
+    color: string;
+    anchor: number;
+    head: number;
+}
+/** Minimal sync surface required for richtext collaboration. */
+interface RichTextSyncEngine {
+    getRichtextDocChannel?(): RichTextDocChannel;
+    getAwarenessManager(): RichTextAwarenessManager;
+}
+interface RichTextDocChannel {
+    shouldUseChannel(snapshotBytes: number, useDocChannel?: boolean): boolean;
+    send(collection: string, recordId: string, field: string, update: Uint8Array): void;
+    subscribe(collection: string, recordId: string, field: string, listener: (update: Uint8Array) => void): () => void;
+}
+interface RichTextAwarenessManager {
+    clientId: number;
+    getLocalState(): RichTextAwarenessState | null;
+    setLocalState(state: RichTextAwarenessState): void;
+    getStates(): Map<number, RichTextAwarenessState>;
+    on(event: 'change', listener: () => void): () => void;
+}
+interface RichTextAwarenessState {
+    user: RichTextAwarenessUser;
+    cursor?: {
+        collection: string;
+        recordId: string;
+        field: string;
+        anchor: number;
+        head: number;
+    };
+}
+interface CreateRichTextControllerOptions {
+    collection: CollectionAccessor;
+    collectionName: string;
+    recordId: string;
+    fieldName: string;
+    store: {
+        collection(name: string): CollectionAccessor;
+    };
+    syncEngine?: RichTextSyncEngine | null;
+    useDocChannel?: boolean;
+    user?: RichTextAwarenessUser;
+}
+interface RichTextControllerSnapshot {
+    ready: boolean;
+    error: Error | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    cursors: readonly RichTextCursorInfo[];
+}
+interface RichTextController {
+    readonly doc: yjs.Doc;
+    readonly text: yjs.Text;
+    getSnapshot(): RichTextControllerSnapshot;
+    subscribe(listener: () => void): () => void;
+    undo(): void;
+    redo(): void;
+    setCursor(anchor: number, head: number): void;
+    clearCursor(): void;
+    setUser(user: RichTextAwarenessUser | undefined): void;
+    destroy(): void;
+}
+
+/**
+ * Framework-agnostic richtext binding: Yjs document lifecycle, persistence,
+ * incremental doc channel, and awareness cursors.
+ */
+declare function createRichTextController(options: CreateRichTextControllerOptions): RichTextController;
+
+/**
+ * Narrows a sync engine reference to the richtext controller surface.
+ * SyncEngine satisfies this interface at runtime; types live in different packages.
+ */
+declare function asRichTextSyncEngine(engine: unknown): RichTextSyncEngine | null;
+
 type RichtextInput = string | Uint8Array | ArrayBuffer | null | undefined;
 /**
  * Encodes richtext values into Yjs document updates.
+ *
+ * Also accepts the tagged `{ $koraBytes }` form that binary richtext values
+ * take inside `op.data` (and, for old dev databases, the pre-fix numeric-key
+ * object shape), so every consumer that writes op-data values to columns
+ * inherits the decoding. Plain strings keep their exact historical behavior:
+ * encoded as a fresh Yjs document containing the string.
  */
-declare function encodeRichtext(value: RichtextInput): Uint8Array | null;
+declare function encodeRichtext(value: RichtextInput | KoraBytesValue): Uint8Array | null;
 /**
  * Decodes driver-provided richtext values into Uint8Array.
  */
@@ -1145,4 +1357,4 @@ declare function readAuditExportManifest(data: Uint8Array): AuditExportManifest;
  */
 declare function verifyAuditExportChecksum(data: Uint8Array): Promise<boolean>;
 
-export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };
+export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type ClockRebaseResult, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OptimisticLockError, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, RowVersionState, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, getSharedQueryStoreCache, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, c as SubscriptionCallback, W as WhereClause, d as OrderByDirection, L as LocalMutationHandler, e as StoreConfig, A as ApplyRemoteOptions, f as MaterializedRowSnapshot } from './types-DepnRDk_.js';
-export { M as MigrationPlan, g as OrderByClause, h as StoreIsolation, T as Transaction, i as TransactionBufferedEntry, j as TransactionCommitBatch, k as TransactionCommitResult, l as WhereOperators } from './types-DepnRDk_.js';
-import { Operation, KoraError, VersionVector, SchemaDefinition, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraEvent } from '@korajs/core';
+import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, c as SubscriptionCallback, W as WhereClause, d as OrderByDirection, L as LocalMutationHandler, e as StoreConfig, A as ApplyRemoteOptions, f as MaterializedRowSnapshot, g as RowVersionState } from './types-CJOVKxLw.js';
+export { M as MigrationPlan, h as OrderByClause, i as StoreIsolation, T as Transaction, j as TransactionBufferedEntry, k as TransactionCommitBatch, l as TransactionCommitResult, m as WhereOperators } from './types-CJOVKxLw.js';
+import { Operation, KoraError, VersionVector, SchemaDefinition, HLCTimestamp, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraBytesValue, KoraEvent } from '@korajs/core';
 export { ApplyResult } from '@korajs/core';
-import { R as RelationEnforcer, L as LocalMutationContext } from './types-BMyHmwvn.js';
-export { C as Collection } from './types-BMyHmwvn.js';
+import { R as RelationEnforcer, L as LocalMutationContext } from './types-DAxCladl.js';
+export { C as Collection } from './types-DAxCladl.js';
+import * as yjs from 'yjs';
 
 /**
  * In-memory materialized state at a causal cut in the operation log.
@@ -32,6 +33,18 @@ declare class QueryError extends KoraError {
 declare class RecordNotFoundError extends KoraError {
     constructor(collection: string, recordId: string);
 }
+/**
+ * Thrown inside `applyRemoteOperation` when the row's version state changed
+ * between the caller's snapshot read and the guarded write (a concurrent local
+ * mutation landed in the window). The transaction is rolled back with nothing
+ * written; the caller re-reads fresh state, recomputes its merge, and retries.
+ * This is the optimistic-concurrency guard that keeps merge-engine results
+ * (richtext, add-wins arrays, constraint resolutions) from clobbering newer
+ * local edits they never saw.
+ */
+declare class OptimisticLockError extends KoraError {
+    constructor(collection: string, recordId: string);
+}
 /**
  * Thrown when a storage adapter operation fails.
  */
@@ -100,6 +113,20 @@ declare function computeAckCompactionWatermark(serverVector: VersionVector): Ver
  */
 declare function compactOperationLog(adapter: StorageAdapter, schema: SchemaDefinition, strategy: CompactionStrategy, serverVector: VersionVector): Promise<CompactionResult>;
 
+/**
+ * Result of re-stamping unsynced operations after a clock correction.
+ */
+interface ClockRebaseResult {
+    /** The rewritten operations, in causal order (original HLC total order preserved). */
+    operations: Operation[];
+    /** Maps each old (pre-rebase) operation id to its new content-addressed id. */
+    idMapping: Record<string, string>;
+    /** Number of operations that were re-stamped. */
+    rebasedCount: number;
+    /** Highest timestamp assigned during the rebase, or null when nothing was rebased. */
+    newMaxTimestamp: HLCTimestamp | null;
+}
+
 declare const LAST_ACKED_SERVER_VECTOR_META_KEY = "last_acked_server_vector";
 /**
  * Serialize a version vector for `_kora_meta` storage.
@@ -714,6 +741,12 @@ declare class Store implements OperationLog {
     /**
      * Get the node ID for this store instance.
      */
+    /**
+     * Records the offset between server time and this device's clock
+     * (serverTime - localTime), learned at sync handshake. Lets the store's HLC
+     * validate remote timestamps correctly even when the local clock is wrong.
+     */
+    setClockReferenceOffset(offsetMs: number): void;
     getNodeId(): string;
     /**
      * Apply a remote operation received from sync.
@@ -721,6 +754,18 @@ declare class Store implements OperationLog {
      * and updates the version vector.
      */
     applyRemoteOperation(op: Operation, options?: ApplyRemoteOptions): Promise<ApplyResult>;
+    /**
+     * Materialize update/delete operations that were logged for a record BEFORE
+     * its insert arrived (reordered delivery). Runs inside the insert's write
+     * transaction, folding each orphan in timestamp order through the exact
+     * per-field LWW / LWW-delete rules the normal apply paths use, so the final
+     * row state equals what a device that received the operations in causal
+     * order computed. Called only when the insert created a previously-absent
+     * row — in that case every logged update/delete for the record is
+     * necessarily an orphan (rows are soft-deleted, never removed, so a row
+     * that is absent now was never materialized).
+     */
+    private foldOrphanedOperations;
     /**
      * Get operations from a node within a sequence number range.
      * Implements the OperationLog interface for computeDelta.
@@ -774,6 +819,14 @@ declare class Store implements OperationLog {
      * Load a materialized row by ID, including soft-deleted tombstones.
      */
     findMaterializedRow(collection: string, recordId: string): Promise<MaterializedRowSnapshot | null>;
+    /**
+     * Raw version state of a materialized row, for optimistic-concurrency guarded
+     * applies: capture this snapshot before computing a merge, pass it as
+     * `guardRowState`, and the apply refuses to write if the row changed since.
+     * Returns null when no row exists (which is itself a valid guard state — the
+     * apply then requires the row to still be absent).
+     */
+    getRowVersionState(collection: string, recordId: string): Promise<RowVersionState | null>;
     /**
      * Latest operation from this device for a record (used for delete-vs-update merge on sync).
      */
@@ -797,6 +850,18 @@ declare class Store implements OperationLog {
      * Local operations not yet reflected on the server version vector.
      */
     getUnsyncedOperations(serverVector: VersionVector): Promise<Operation[]>;
+    /**
+     * Re-stamp never-acknowledged local operations after a fast device clock was
+     * corrected, so sync can resume immediately. Safe because unacknowledged
+     * operations are private to this device (like unpushed git commits);
+     * acknowledged/shared operations are immutable and never touched.
+     *
+     * After the rewrite the store's HLC is advanced past the highest new
+     * timestamp so subsequent local writes keep sorting after the rebased ops.
+     * No data-change notifications are emitted: materialized values are
+     * unchanged, only version stamps move.
+     */
+    rebaseUnsyncedOperations(unsyncedOpIds: string[], correctedNowMs: number): Promise<ClockRebaseResult>;
     /**
      * Count of local operations ahead of the server version vector.
      */
@@ -896,6 +961,62 @@ interface CollectionAccessor {
     where(conditions: Record<string, unknown>): QueryBuilder;
 }
 
+/**
+ * Bridges the async QueryBuilder.subscribe() API with synchronous snapshot reads
+ * required by React useSyncExternalStore, Vue composables, and Svelte stores.
+ *
+ * Uses lazy subscription: the underlying query subscription starts when the first
+ * listener attaches and stops when the last listener detaches.
+ */
+declare class QueryStore<T = CollectionRecord> {
+    private snapshot;
+    private listeners;
+    private unsubscribeQuery;
+    private active;
+    private readonly queryBuilder;
+    constructor(queryBuilder: QueryBuilder<T>);
+    /**
+     * Subscribe to snapshot changes.
+     *
+     * @returns Unsubscribe function
+     */
+    subscribe: (onStoreChange: () => void) => (() => void);
+    /** Synchronous read of the latest query results. */
+    getSnapshot: () => readonly T[];
+    /** Tear down listeners and the underlying query subscription. */
+    destroy(): void;
+    private startSubscription;
+    private stopSubscription;
+    private notifyListeners;
+}
+
+/**
+ * Ensures a query builder is backed by an open store (not a legacy pending placeholder).
+ */
+declare function assertQueryReady(query: QueryBuilder<unknown>): void;
+
+/**
+ * Reference-counted cache of {@link QueryStore} instances keyed by query descriptor.
+ * Identical queries from different components share one underlying subscription.
+ */
+declare class QueryStoreCache {
+    private readonly scopeKey;
+    private entries;
+    constructor(scopeKey?: string);
+    getOrCreate<T>(queryBuilder: QueryBuilder<T>): QueryStore<T>;
+    release(queryBuilder: QueryBuilder<unknown>): void;
+    clear(): void;
+    get size(): number;
+    private getKey;
+}
+/**
+ * Process-wide shared query store cache for framework bindings.
+ *
+ * @deprecated Prefer {@link KoraApp.getQueryStoreCache} via `KoraProvider` context
+ * so each app instance owns an isolated cache.
+ */
+declare function getSharedQueryStoreCache(): QueryStoreCache;
+
 /**
  * Bloom filter for subscription dependency tracking.
  *
@@ -1040,11 +1161,102 @@ declare function validateStateTransition(collectionName: string, recordId: strin
  */
 declare function validateUpdateStateMachine(collectionName: string, recordId: string, collectionDef: CollectionDefinition, currentRecord: Record<string, unknown>, updateData: Record<string, unknown>): Record<string, unknown>;
 
+/** User identity for collaborative cursor presence. */
+interface RichTextAwarenessUser {
+    name: string;
+    color: string;
+    avatar?: string;
+}
+/** Remote collaborator cursor for a richtext field. */
+interface RichTextCursorInfo {
+    clientId: number;
+    userName: string;
+    color: string;
+    anchor: number;
+    head: number;
+}
+/** Minimal sync surface required for richtext collaboration. */
+interface RichTextSyncEngine {
+    getRichtextDocChannel?(): RichTextDocChannel;
+    getAwarenessManager(): RichTextAwarenessManager;
+}
+interface RichTextDocChannel {
+    shouldUseChannel(snapshotBytes: number, useDocChannel?: boolean): boolean;
+    send(collection: string, recordId: string, field: string, update: Uint8Array): void;
+    subscribe(collection: string, recordId: string, field: string, listener: (update: Uint8Array) => void): () => void;
+}
+interface RichTextAwarenessManager {
+    clientId: number;
+    getLocalState(): RichTextAwarenessState | null;
+    setLocalState(state: RichTextAwarenessState): void;
+    getStates(): Map<number, RichTextAwarenessState>;
+    on(event: 'change', listener: () => void): () => void;
+}
+interface RichTextAwarenessState {
+    user: RichTextAwarenessUser;
+    cursor?: {
+        collection: string;
+        recordId: string;
+        field: string;
+        anchor: number;
+        head: number;
+    };
+}
+interface CreateRichTextControllerOptions {
+    collection: CollectionAccessor;
+    collectionName: string;
+    recordId: string;
+    fieldName: string;
+    store: {
+        collection(name: string): CollectionAccessor;
+    };
+    syncEngine?: RichTextSyncEngine | null;
+    useDocChannel?: boolean;
+    user?: RichTextAwarenessUser;
+}
+interface RichTextControllerSnapshot {
+    ready: boolean;
+    error: Error | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    cursors: readonly RichTextCursorInfo[];
+}
+interface RichTextController {
+    readonly doc: yjs.Doc;
+    readonly text: yjs.Text;
+    getSnapshot(): RichTextControllerSnapshot;
+    subscribe(listener: () => void): () => void;
+    undo(): void;
+    redo(): void;
+    setCursor(anchor: number, head: number): void;
+    clearCursor(): void;
+    setUser(user: RichTextAwarenessUser | undefined): void;
+    destroy(): void;
+}
+
+/**
+ * Framework-agnostic richtext binding: Yjs document lifecycle, persistence,
+ * incremental doc channel, and awareness cursors.
+ */
+declare function createRichTextController(options: CreateRichTextControllerOptions): RichTextController;
+
+/**
+ * Narrows a sync engine reference to the richtext controller surface.
+ * SyncEngine satisfies this interface at runtime; types live in different packages.
+ */
+declare function asRichTextSyncEngine(engine: unknown): RichTextSyncEngine | null;
+
 type RichtextInput = string | Uint8Array | ArrayBuffer | null | undefined;
 /**
  * Encodes richtext values into Yjs document updates.
+ *
+ * Also accepts the tagged `{ $koraBytes }` form that binary richtext values
+ * take inside `op.data` (and, for old dev databases, the pre-fix numeric-key
+ * object shape), so every consumer that writes op-data values to columns
+ * inherits the decoding. Plain strings keep their exact historical behavior:
+ * encoded as a fresh Yjs document containing the string.
  */
-declare function encodeRichtext(value: RichtextInput): Uint8Array | null;
+declare function encodeRichtext(value: RichtextInput | KoraBytesValue): Uint8Array | null;
 /**
  * Decodes driver-provided richtext values into Uint8Array.
  */
@@ -1145,4 +1357,4 @@ declare function readAuditExportManifest(data: Uint8Array): AuditExportManifest;
  */
 declare function verifyAuditExportChecksum(data: Uint8Array): Promise<boolean>;
 
-export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };
+export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type ClockRebaseResult, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OptimisticLockError, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, RowVersionState, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, getSharedQueryStoreCache, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };