@korajs/store 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,25 @@
-import { Q as QueryDescriptor, a as SubscriptionCallback, C as CollectionRecord, S as StorageAdapter, W as WhereClause, O as OrderByDirection, b as StoreConfig, A as ApplyResult, T as Transaction } from './types-DF-KDSK1.js';
-export { M as MigrationPlan, c as OrderByClause, d as WhereOperators } from './types-DF-KDSK1.js';
-import { KoraError, Operation, CollectionDefinition, SchemaDefinition, SequenceConfig, HybridLogicalClock, OperationLog, VersionVector, OnDeleteAction, RelationDefinition, StateMachineDefinition } 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 } 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';
+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 * as yjs from 'yjs';
+
+/**
+ * In-memory materialized state at a causal cut in the operation log.
+ * Read-only — does not mutate the live store.
+ */
+interface ReplaySnapshot {
+    /** The operation whose causal past was replayed (inclusive). */
+    targetOperation: Operation;
+    /** Operations applied in causal order (ancestors + target). */
+    operationsApplied: Operation[];
+    /** Non-deleted records per collection after replay. */
+    collections: Record<string, CollectionRecord[]>;
+    /** Look up a single record at the replay cut. Returns null if deleted or missing. */
+    findRecord(collection: string, recordId: string): CollectionRecord | null;
+}
 
 /**
  * Thrown when a query is invalid (bad field names, invalid operators, etc.).
@@ -45,6 +64,205 @@ declare class PersistenceError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
 
+/**
+ * How the local operation log may be compacted.
+ * Materialized collection rows are always kept as the convergence baseline.
+ */
+type CompactionStrategy = {
+    mode: 'never';
+} | {
+    mode: 'after-ack';
+    /** Server version vector; defaults to persisted last-acked vector on the store. */
+    serverVector?: VersionVector;
+} | {
+    mode: 'after-days';
+    /** Delete only ops older than this many days (still requires ack watermark). */
+    days: number;
+    serverVector?: VersionVector;
+};
+/**
+ * Result of a compaction run.
+ */
+interface CompactionResult {
+    /** Number of operation log rows removed. */
+    deletedCount: number;
+    /** Per-node sequence ceiling used for deletion (from server ack vector). */
+    watermark: VersionVector;
+}
+declare const COMPACTION_BASELINE_META_KEY = "compaction_baseline_at";
+
+/**
+ * Compute per-node sequence watermarks safe to compact (server has acknowledged these ops).
+ */
+declare function computeAckCompactionWatermark(serverVector: VersionVector): VersionVector;
+/**
+ * Remove acknowledged, materialized operation log entries from `_kora_ops_*` tables.
+ * Does not modify collection rows — they are the compaction baseline snapshot.
+ */
+declare function compactOperationLog(adapter: StorageAdapter, schema: SchemaDefinition, strategy: CompactionStrategy, serverVector: VersionVector): Promise<CompactionResult>;
+
+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[]>;
+
+/**
+ * A merge or constraint decision persisted for enterprise audit export.
+ */
+interface PersistedAuditTrace {
+    /** Unique row id (UUID v7). */
+    id: string;
+    /** Wall-clock time when the trace was recorded (epoch ms). */
+    recordedAt: number;
+    /** Source event type from the Kora event bus. */
+    eventType: 'merge:completed' | 'merge:conflict' | 'constraint:violated';
+    /** Constraint name when {@link eventType} is `constraint:violated`. */
+    constraint?: string;
+    /** Full merge trace including conflicting operations and resolution details. */
+    trace: MergeTrace;
+}
+/**
+ * Manifest embedded in audit export files.
+ */
+interface AuditExportManifest {
+    /** Audit export format version */
+    version: 1;
+    /** When the export was created (epoch ms) */
+    exportedAt: number;
+    /** Node ID of the originating device */
+    nodeId: string;
+    /** Schema version at export time */
+    schemaVersion: number;
+    /** Number of operations included */
+    operationCount: number;
+    /** Number of merge traces included */
+    mergeTraceCount: number;
+    /** SHA-256 hex checksum of content sections */
+    checksum: string;
+}
+/**
+ * Decoded audit export payload.
+ */
+interface AuditExportPayload {
+    manifest: AuditExportManifest;
+    operations: Operation[];
+    mergeTraces: PersistedAuditTrace[];
+}
+/**
+ * Progress reported during audit export.
+ */
+interface AuditExportProgress {
+    phase: 'reading' | 'writing' | 'verifying';
+    /** 0-1 progress ratio */
+    progress: number;
+    message: string;
+}
+/**
+ * Options for {@link exportAudit}.
+ */
+interface AuditExportOptions {
+    /** Subset of collections for operations and traces. All if omitted. */
+    collections?: string[];
+    /** Include only traces recorded at or after this timestamp (epoch ms). */
+    since?: number;
+    /** Include only traces recorded at or before this timestamp (epoch ms). */
+    until?: number;
+    /** Progress callback */
+    onProgress?: (progress: AuditExportProgress) => void;
+}
+/**
+ * Query filters for reading persisted audit traces.
+ */
+interface AuditTraceQuery {
+    collections?: string[];
+    since?: number;
+    until?: number;
+}
+
+/**
+ * Manifest embedded in every backup file.
+ */
+interface BackupManifest {
+    /** Backup format version */
+    version: 1;
+    /** When the backup was created (epoch ms) */
+    createdAt: number;
+    /** Node ID of the originating device */
+    nodeId: string;
+    /** Schema version at backup time */
+    schemaVersion: number;
+    /** Total number of operations in the backup */
+    operationCount: number;
+    /** Collection names included in the backup */
+    collections: string[];
+    /** Whether materialized records are included */
+    includesRecords: boolean;
+    /** SHA-256 hex checksum of all content sections */
+    checksum: string;
+}
+/**
+ * Progress reported during backup/restore operations.
+ */
+interface BackupProgress {
+    phase: 'reading' | 'writing' | 'verifying' | 'restoring';
+    /** 0-1 progress ratio */
+    progress: number;
+    message: string;
+}
+/**
+ * Result of a restore operation.
+ */
+interface RestoreResult {
+    /** Number of operations restored */
+    operationsRestored: number;
+    /** Number of records restored */
+    recordsRestored: number;
+    /** Whether the restore completed successfully */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Duration in ms */
+    duration: number;
+}
+/**
+ * Options for exporting a backup.
+ */
+interface BackupOptions {
+    /** Include materialized record snapshots (default: true) */
+    includeRecords?: boolean;
+    /** Subset of collections to backup. All if omitted. */
+    collections?: string[];
+    /** Progress callback */
+    onProgress?: (progress: BackupProgress) => void;
+}
+/**
+ * Options for restoring from a backup.
+ */
+interface RestoreOptions {
+    /** Subset of collections to restore. All if omitted. */
+    collections?: string[];
+    /** 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).
+     */
+    merge?: boolean;
+}
+
 /**
  * Configuration options for the SubscriptionManager.
  */
@@ -66,6 +284,8 @@ interface SubscriptionManagerOptions {
      * @default 0.01
      */
     bloomFalsePositiveRate?: number;
+    /** Called when a query subscription is registered (e.g. to register sync query subsets). */
+    onQuerySubscribed?: (descriptor: QueryDescriptor) => () => void;
 }
 /**
  * Performance statistics for monitoring subscription checking efficiency.
@@ -106,6 +326,7 @@ declare class SubscriptionManager {
     private subscriptions;
     private pendingCollections;
     private flushScheduled;
+    private readonly onQuerySubscribed?;
     private bloomFilter;
     private bloomDirty;
     private readonly bloomThreshold;
@@ -179,8 +400,9 @@ declare class SubscriptionManager {
     private rebuildBloomFilter;
     private scheduleFlush;
     /**
-     * Compare two result sets. Uses length check + JSON comparison as pragmatic approach.
-     * Sufficient for typical query results. Can be optimized to id-based diffing if profiling shows need.
+     * 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;
 }
@@ -334,6 +556,20 @@ 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.
@@ -343,7 +579,10 @@ interface TransactionContextConfig {
     adapter: StorageAdapter;
     clock: HybridLogicalClock;
     nodeId: string;
-    getSequenceNumber: () => number;
+    sequenceAllocator: TransactionSequenceAllocator;
+    relationEnforcer: RelationEnforcer | null;
+    causalTracker: CausalTracker | null;
+    localMutationHandler: LocalMutationHandler | null;
 }
 /**
  * A collection accessor within a transaction.
@@ -447,7 +686,12 @@ declare class Store implements OperationLog {
     private readonly schema;
     private readonly adapter;
     private readonly configNodeId;
+    private readonly dbName;
+    private readonly isolation;
     private readonly emitter;
+    private localMutationHandler;
+    private relationEnforcer;
+    private causalTracker;
     constructor(config: StoreConfig);
     /**
      * Open the store: initialize the database, load or generate a node ID,
@@ -477,20 +721,101 @@ declare class Store implements OperationLog {
      * Checks for duplicates, applies to the data table, persists the operation,
      * and updates the version vector.
      */
-    applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    applyRemoteOperation(op: Operation, options?: ApplyRemoteOptions): Promise<ApplyResult>;
     /**
      * Get operations from a node within a sequence number range.
      * Implements the OperationLog interface for computeDelta.
      */
-    getRange(nodeId: string, fromSeq: number, toSeq: number): Operation[];
+    getRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
     /**
-     * Async version of getRange for use by the sync layer.
+     * Get operations from a node within a sequence number range.
      */
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    /**
+     * Load every operation from the local append-only log across all collections.
+     * Used by sync delta computation, backup export, and time-travel replay.
+     */
+    getAllOperations(): Promise<Operation[]>;
+    /**
+     * Rebuild an in-memory snapshot of materialized state at a causal cut in the op log.
+     * Does not mutate the live store — intended for DevTools time-travel inspection.
+     *
+     * @param operationId - Content-addressed id of the operation to replay through (inclusive)
+     * @throws {OperationError} When the operation id is not present in the local log
+     */
+    replayTo(operationId: string): Promise<ReplaySnapshot>;
+    /**
+     * Persist a merge trace to the durable audit log.
+     */
+    appendAuditTrace(trace: PersistedAuditTrace): Promise<void>;
+    /**
+     * Read persisted audit traces with optional filters.
+     */
+    getAuditTraces(query?: AuditTraceQuery): Promise<PersistedAuditTrace[]>;
+    /**
+     * Export operations and merge traces as a portable audit bundle.
+     */
+    exportAudit(options?: AuditExportOptions): Promise<Uint8Array>;
     /**
      * Get the schema definition.
      */
     getSchema(): SchemaDefinition;
+    /**
+     * Route local CRUD through the unified apply pipeline (korajs ApplyPipeline).
+     */
+    setLocalMutationHandler(handler: LocalMutationHandler | null): void;
+    /**
+     * Build mutation context for a collection (used by ApplyPipeline side effects).
+     */
+    createMutationContext(collection: string, options?: {
+        inTransaction?: boolean;
+        extraCausalDeps?: string[];
+    }): LocalMutationContext;
+    /**
+     * Load a materialized row by ID, including soft-deleted tombstones.
+     */
+    findMaterializedRow(collection: string, recordId: string): Promise<MaterializedRowSnapshot | null>;
+    /**
+     * Latest operation from this device for a record (used for delete-vs-update merge on sync).
+     */
+    /**
+     * Load the last server version vector acknowledged by this client (persisted in `_kora_meta`).
+     */
+    loadLastAckedServerVector(): Promise<VersionVector>;
+    /**
+     * Persist the last server version vector this client believes the server has applied.
+     */
+    saveLastAckedServerVector(vector: VersionVector): Promise<void>;
+    /**
+     * Load persisted delta cursor for resuming paginated initial sync.
+     */
+    loadDeltaCursor(): Promise<string | null>;
+    /**
+     * Persist or clear the delta cursor for paginated initial sync resume.
+     */
+    saveDeltaCursor(cursor: string | null): Promise<void>;
+    /**
+     * Local operations not yet reflected on the server version vector.
+     */
+    getUnsyncedOperations(serverVector: VersionVector): Promise<Operation[]>;
+    /**
+     * 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(strategy: CompactionStrategy): Promise<CompactionResult>;
+    /**
+     * Merge session remote vector with persisted last-acked vector (max per node).
+     */
+    mergeServerVectors(sessionVector: VersionVector, persistedVector: VersionVector): VersionVector;
+    getLatestLocalOperationForRecord(collection: string, recordId: string): Promise<Operation | null>;
+    /**
+     * Latest operation for a record from any node (for 3-way merge when local op log is empty).
+     */
+    getLatestOperationForRecord(collection: string, recordId: string): Promise<Operation | null>;
     /** Expose the subscription manager for direct access (e.g., by QueryBuilder) */
     getSubscriptionManager(): SubscriptionManager;
     /**
@@ -517,7 +842,31 @@ declare class Store implements OperationLog {
      * @returns The operations that were committed
      */
     transaction(fn: (tx: TransactionContext) => Promise<void>): Promise<Operation[]>;
-    private nextSequenceNumber;
+    /**
+     * Export all data as a portable backup binary.
+     * Includes operations, version vector, metadata, and optionally materialized records.
+     *
+     * @param options - Backup options (includeRecords, collections, onProgress)
+     * @returns Backup as a Uint8Array
+     */
+    exportBackup(options?: BackupOptions): Promise<Uint8Array>;
+    /**
+     * Restore data from a backup binary.
+     *
+     * @param data - The backup data
+     * @param options - Restore options (merge, collections, onProgress)
+     * @returns Result of the restore operation
+     */
+    importBackup(data: Uint8Array, options?: RestoreOptions): Promise<RestoreResult>;
+    /**
+     * Read backup manifest without loading the entire backup.
+     *
+     * @param data - The raw backup data
+     * @returns The backup manifest
+     */
+    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.
@@ -548,6 +897,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.
  *
@@ -638,182 +1043,6 @@ declare class SubscriptionBloomFilter {
     private getPositions;
 }
 
-/**
- * A resolved relation reference: describes a relation that points TO a given collection.
- * When a record in `targetCollection` is deleted, we must handle records in
- * `sourceCollection` that reference it via `foreignKeyField`.
- */
-interface IncomingRelation {
-    /** Name of the relation in the schema */
-    relationName: string;
-    /** Collection that holds the foreign key (the "from" side) */
-    sourceCollection: string;
-    /** Field in the source collection that references the target */
-    foreignKeyField: string;
-    /** What to do when the referenced record is deleted */
-    onDelete: OnDeleteAction;
-    /** The full relation definition */
-    relation: RelationDefinition;
-}
-
-/**
- * Configuration for the RelationEnforcer.
- */
-interface RelationEnforcerConfig {
-    schema: SchemaDefinition;
-    adapter: StorageAdapter;
-    clock: HybridLogicalClock;
-    nodeId: string;
-    getSequenceNumber: () => number;
-}
-/**
- * Result of enforcing referential integrity on a delete operation.
- * Contains all additional operations that were created as side effects
- * (cascaded deletes and set-null updates).
- */
-interface EnforcementResult {
-    /** Additional operations created by cascading deletes and set-null updates */
-    operations: Operation[];
-}
-/**
- * Enforces referential integrity constraints during local delete operations.
- *
- * When a record is deleted, this enforcer checks all relations that reference
- * the deleted record's collection and applies the appropriate onDelete policy:
- *
- * - **cascade**: Recursively deletes all referencing records
- * - **set-null**: Sets the foreign key to null on all referencing records
- * - **restrict**: Throws a ReferentialIntegrityError if any references exist
- * - **no-action**: Does nothing (the foreign key is left dangling)
- *
- * The enforcer operates within a provided transaction to ensure atomicity.
- * All generated operations (cascaded deletes, set-null updates) share a
- * causal dependency chain through the original delete operation.
- *
- * @example
- * ```typescript
- * const enforcer = new RelationEnforcer({
- *   schema, adapter, clock, nodeId,
- *   getSequenceNumber: () => ++seq,
- * })
- * const result = await enforcer.enforceDelete(
- *   'projects', 'proj-1', tx, ['delete-op-id']
- * )
- * // result.operations contains any cascaded delete/update ops
- * ```
- */
-declare class RelationEnforcer {
-    private readonly lookup;
-    private readonly schema;
-    private readonly adapter;
-    private readonly clock;
-    private readonly nodeId;
-    private readonly getSequenceNumber;
-    constructor(config: RelationEnforcerConfig);
-    /**
-     * Enforce referential integrity after deleting a record.
-     *
-     * Must be called within a transaction. The transaction handle is used
-     * for all cascaded writes to ensure atomicity.
-     *
-     * @param collection - The collection the deleted record belongs to
-     * @param recordId - The ID of the deleted record
-     * @param tx - The active transaction handle
-     * @param causalDeps - Causal dependencies for generated operations
-     * @returns All additional operations created as side effects
-     * @throws {ReferentialIntegrityError} If a 'restrict' policy is violated
-     */
-    enforceDelete(collection: string, recordId: string, tx: Transaction, causalDeps: string[]): Promise<EnforcementResult>;
-    /**
-     * Enforce a single relation's onDelete policy.
-     */
-    private enforceRelation;
-    /**
-     * Cascade: delete all records in the source collection that reference
-     * the deleted record, then recursively cascade those deletes.
-     */
-    private enforceCascade;
-    /**
-     * Set-null: update all referencing records to set the foreign key to null.
-     */
-    private enforceSetNull;
-    /**
-     * Restrict: refuse the delete if any referencing records exist.
-     */
-    private enforceRestrict;
-    /**
-     * Get the relation lookup map for external use (e.g., by the merge engine).
-     */
-    getRelationLookup(): Map<string, IncomingRelation[]>;
-}
-
-/**
- * Callback invoked after a mutation so the Store can notify subscriptions.
- */
-type MutationCallback = (collection: string, operation: Operation) => void;
-/**
- * Collection provides CRUD operations on a single schema collection.
- * Each mutation creates an Operation and persists both the data and the operation atomically.
- *
- * When a RelationEnforcer is provided, delete operations enforce referential integrity
- * policies (cascade, set-null, restrict) defined in the schema's relations.
- */
-declare class Collection {
-    private readonly name;
-    private readonly definition;
-    private readonly schema;
-    private readonly adapter;
-    private readonly clock;
-    private readonly nodeId;
-    private readonly getSequenceNumber;
-    private readonly onMutation;
-    private readonly relationEnforcer;
-    constructor(name: string, definition: CollectionDefinition, schema: SchemaDefinition, adapter: StorageAdapter, clock: HybridLogicalClock, nodeId: string, getSequenceNumber: () => number, onMutation: MutationCallback, relationEnforcer?: RelationEnforcer);
-    /**
-     * Insert a new record into the collection.
-     * Generates a UUID v7 for the id, validates data, and persists atomically.
-     *
-     * @param data - The record data (auto fields and defaults are applied automatically)
-     * @returns The inserted record with id, createdAt, updatedAt
-     */
-    insert(data: Record<string, unknown>): Promise<CollectionRecord>;
-    /**
-     * Find a record by its ID. Returns null if not found or soft-deleted.
-     */
-    findById(id: string): Promise<CollectionRecord | null>;
-    /**
-     * Update an existing record. Only the provided fields are changed.
-     *
-     * @param id - The record ID to update
-     * @param data - Partial data with only the fields to change
-     * @returns The updated record
-     * @throws {RecordNotFoundError} If the record doesn't exist or is deleted
-     */
-    update(id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
-    /**
-     * Soft-delete a record by its ID.
-     *
-     * When a RelationEnforcer is configured, referential integrity policies
-     * are enforced within the same transaction:
-     * - **cascade**: Recursively deletes all referencing records
-     * - **set-null**: Sets foreign keys to null on referencing records
-     * - **restrict**: Throws ReferentialIntegrityError if references exist
-     * - **no-action**: Does nothing (dangling references are left)
-     *
-     * All cascaded operations are created atomically within the same transaction
-     * and share causal dependencies with the original delete.
-     *
-     * @param id - The record ID to delete
-     * @throws {RecordNotFoundError} If the record doesn't exist or is already deleted
-     * @throws {ReferentialIntegrityError} If a 'restrict' policy is violated
-     */
-    delete(id: string): Promise<void>;
-    /** Get the collection name */
-    getName(): string;
-    /** Get the collection definition */
-    getDefinition(): CollectionDefinition;
-}
-
 /**
  * Error thrown when a local mutation attempts an invalid state transition.
  *
@@ -868,6 +1097,91 @@ 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.
@@ -881,6 +1195,11 @@ declare function decodeRichtext(value: unknown): Uint8Array | null;
  * Reads plain text from a richtext Yjs state update.
  */
 declare function richtextToPlainText(value: RichtextInput): string;
+/**
+ * Compares two richtext values by decoded plain text.
+ * Yjs update bytes are not stable across separate encodes of the same string.
+ */
+declare function richtextStatesEqual(a: unknown, b: unknown): boolean;
 
 /**
  * Minimal pluralization/singularization utilities for relation name resolution.
@@ -909,4 +1228,63 @@ declare function pluralize(word: string): string;
  */
 declare function singularize(word: string): string;
 
-export { AdapterError, ApplyResult, Collection, type CollectionAccessor, CollectionRecord, InvalidStateTransitionError, OrderByDirection, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, RecordNotFoundError, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, Transaction, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, decodeRichtext, encodeRichtext, pluralize, richtextToPlainText, singularize, validateStateTransition, validateUpdateStateMachine };
+/**
+ * Export a backup from a store.
+ *
+ * Reads all data via the adapter and produces a portable binary backup.
+ *
+ * @param adapter - The storage adapter
+ * @param schema - The schema definition
+ * @param nodeId - Current node ID
+ * @param schemaVersion - Schema version
+ * @param options - Backup options
+ * @returns Backup as a Uint8Array
+ */
+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
+ */
+declare function readBackupManifest(data: Uint8Array): BackupManifest;
+/**
+ * Validate the backup checksum.
+ *
+ * @param data - The raw backup data
+ * @returns True if the checksum is valid
+ */
+declare function verifyBackupChecksum(data: Uint8Array): Promise<boolean>;
+/**
+ * Restore a backup into a store.
+ *
+ * @param adapter - The storage adapter
+ * @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>;
+
+/**
+ * Build a {@link PersistedAuditTrace} from a merge-related Kora event.
+ */
+declare function persistedAuditTraceFromEvent(event: Extract<KoraEvent, {
+    type: 'merge:completed' | 'merge:conflict' | 'constraint:violated';
+}>): PersistedAuditTrace;
+
+/**
+ * Decode an audit export binary into structured data.
+ */
+declare function decodeAuditExport(data: Uint8Array): AuditExportPayload;
+/**
+ * Read only the manifest from an audit export without decoding all sections.
+ */
+declare function readAuditExportManifest(data: Uint8Array): AuditExportManifest;
+/**
+ * Verify the checksum of an audit export file.
+ */
+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, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, 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, 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 };