@korajs/store 0.3.2 → 0.5.0

package/dist/index.d.cts

@@ -1,6 +1,24 @@
-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 } from './types-DF-KDSK1.cjs';
-export { M as MigrationPlan, c as OrderByClause, T as Transaction, d as WhereOperators } from './types-DF-KDSK1.cjs';
-import { KoraError, Operation, CollectionDefinition, SchemaDefinition, OperationLog, VersionVector, HybridLogicalClock } 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_.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';
+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';
+
+/**
+ * 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.).
@@ -46,14 +64,279 @@ declare class PersistenceError extends KoraError {
 }
 
 /**
- * Manages reactive subscriptions. When a mutation occurs on a collection,
- * affected subscriptions are re-evaluated in a microtask batch and callbacks
- * are invoked only if results actually changed.
+ * 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.
+ */
+interface SubscriptionManagerOptions {
+    /**
+     * Minimum number of subscriptions before activating bloom filter.
+     * Below this threshold, linear scanning is used (bloom filter overhead not worth it).
+     * @default 100
+     */
+    bloomThreshold?: number;
+    /**
+     * Expected number of unique collection+field dependencies for bloom filter sizing.
+     * @default 500
+     */
+    bloomExpectedItems?: number;
+    /**
+     * Target false positive rate for the bloom filter.
+     * Lower values require more memory but reduce unnecessary precise checks.
+     * @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.
+ */
+interface SubscriptionStats {
+    /** Total number of mutation notifications processed */
+    totalChecks: number;
+    /** Number of times bloom filter said "maybe" (proceeded to precise check) */
+    bloomFilterHits: number;
+    /** Number of times bloom filter said "definitely not" (skipped all subscriptions) */
+    bloomFilterMisses: number;
+    /** Number of times bloom filter said "maybe" but precise check found no match */
+    falsePositives: number;
+    /** Average time per check in milliseconds */
+    averageCheckTimeMs: number;
+    /** Whether bloom filter is currently active */
+    bloomFilterActive: boolean;
+    /** Current subscription count */
+    subscriptionCount: number;
+}
+/**
+ * Manages reactive subscriptions with two-level dependency checking.
+ *
+ * When a mutation occurs on a collection, affected subscriptions are re-evaluated
+ * in a microtask batch and callbacks are invoked only if results actually changed.
+ *
+ * For large subscription counts (>= bloomThreshold), a bloom filter provides O(k)
+ * pre-filtering to avoid scanning all subscriptions on every mutation:
+ *
+ * Level 1 (Bloom filter): Fast O(k) check -- does this mutation potentially affect
+ * any subscription? If NO: skip all subscriptions (guaranteed correct).
+ * If MAYBE: proceed to Level 2.
+ *
+ * Level 2 (Precise check): Only evaluate subscriptions that match the mutated
+ * collection, including included (related) collection tracking.
  */
 declare class SubscriptionManager {
     private subscriptions;
     private pendingCollections;
     private flushScheduled;
+    private readonly onQuerySubscribed?;
+    private bloomFilter;
+    private bloomDirty;
+    private readonly bloomThreshold;
+    private readonly bloomExpectedItems;
+    private readonly bloomFalsePositiveRate;
+    private totalChecks;
+    private bloomFilterHits;
+    private bloomFilterMisses;
+    private falsePositives;
+    private totalCheckTimeMs;
+    constructor(options?: SubscriptionManagerOptions);
     /**
      * Register a new subscription.
      *
@@ -87,10 +370,38 @@ declare class SubscriptionManager {
     clear(): void;
     /** Number of active subscriptions (for testing/debugging) */
     get size(): number;
+    /**
+     * Get performance statistics for monitoring subscription checking efficiency.
+     * Useful for DevTools integration and performance tuning.
+     */
+    getStats(): SubscriptionStats;
+    /**
+     * Check if bloom filter is currently active.
+     * Active when subscription count meets or exceeds the threshold.
+     */
+    isBloomActive(): boolean;
+    /**
+     * Find subscriptions affected by mutations to the given collections.
+     * Uses two-level checking when bloom filter is active:
+     *
+     * Level 1: Bloom filter pre-check -- if no subscription depends on any
+     * of the mutated collections, skip everything (O(k) per collection).
+     *
+     * Level 2: Precise check -- linear scan of subscriptions, matching
+     * against the mutated collections.
+     */
+    private findAffectedSubscriptions;
+    /**
+     * Rebuild the bloom filter from all current subscriptions.
+     * Adds collection-level dependencies for every subscription, plus
+     * any included collection dependencies.
+     */
+    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;
 }
@@ -192,6 +503,162 @@ declare class QueryBuilder<T = CollectionRecord> {
     private findRelation;
 }
 
+/**
+ * Manages offline-safe sequences backed by a `_kora_sequences` table.
+ *
+ * Each sequence counter is scoped by (name, scope, nodeId), ensuring
+ * that different devices never collide. The counter is atomically
+ * incremented within a database transaction.
+ *
+ * @example
+ * ```typescript
+ * const mgr = new SequenceManager(adapter, 'node-abc')
+ *
+ * const receipt = await mgr.next('receipt', {
+ *   scope: 'store-1',
+ *   format: 'S-{date}-{node4}-{seq}',
+ * })
+ * // → "S-20260508-node-0001"
+ * ```
+ */
+declare class SequenceManager {
+    private readonly adapter;
+    private readonly nodeId;
+    constructor(adapter: StorageAdapter, nodeId: string);
+    /**
+     * Get the next value in a sequence, atomically incrementing the counter.
+     *
+     * @param name - The sequence name (e.g., 'receipt', 'invoice')
+     * @param config - Optional configuration for scope, format, and starting value
+     * @returns The formatted sequence value
+     */
+    next(name: string, config?: SequenceConfig): Promise<string>;
+    /**
+     * Get the current counter value without incrementing.
+     *
+     * @param name - The sequence name
+     * @param config - Optional scope
+     * @returns The current counter value, or 0 if the sequence has never been used
+     */
+    current(name: string, config?: {
+        scope?: string;
+    }): Promise<number>;
+    /**
+     * Reset a sequence counter.
+     *
+     * @param name - The sequence name
+     * @param config - Optional scope and target value
+     */
+    reset(name: string, config?: {
+        scope?: string;
+        to?: number;
+    }): 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.
+ */
+interface TransactionContextConfig {
+    schema: SchemaDefinition;
+    adapter: StorageAdapter;
+    clock: HybridLogicalClock;
+    nodeId: string;
+    sequenceAllocator: TransactionSequenceAllocator;
+    relationEnforcer: RelationEnforcer | null;
+    causalTracker: CausalTracker | null;
+    localMutationHandler: LocalMutationHandler | null;
+}
+/**
+ * A collection accessor within a transaction.
+ * Operations are buffered and committed atomically when the transaction completes.
+ */
+interface TransactionCollectionAccessor {
+    insert(data: Record<string, unknown>): Promise<CollectionRecord>;
+    update(id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<CollectionRecord | null>;
+}
+/**
+ * TransactionContext provides atomic multi-collection operations.
+ *
+ * All mutations are buffered and committed in a single StorageAdapter.transaction()
+ * call. All operations share the same transactionId (UUID v7).
+ *
+ * Subscription notifications are deferred until after commit.
+ *
+ * @example
+ * ```typescript
+ * const { operations, affectedCollections } = await txContext.commit()
+ * // Notify subscriptions after commit
+ * for (const op of operations) {
+ *   subscriptionManager.notify(op.collection, op)
+ * }
+ * ```
+ */
+declare class TransactionContext {
+    private readonly transactionId;
+    private mutationName;
+    private readonly buffer;
+    private committed;
+    private rolledBack;
+    private readonly config;
+    constructor(config: TransactionContextConfig);
+    /**
+     * Set a human-readable mutation name for this transaction.
+     * Propagated to all operations for DevTools display.
+     */
+    setMutationName(name: string): void;
+    /**
+     * Get the mutation name, if set.
+     */
+    getMutationName(): string | undefined;
+    /**
+     * Get a collection accessor for buffered operations within this transaction.
+     */
+    collection(name: string): TransactionCollectionAccessor;
+    /**
+     * Commit all buffered operations atomically.
+     * Returns the list of operations and affected collections for subscription notification.
+     */
+    commit(): Promise<{
+        operations: Operation[];
+        affectedCollections: Set<string>;
+    }>;
+    /**
+     * Mark the transaction as rolled back. No operations will be committed.
+     */
+    rollback(): void;
+    /**
+     * Get the transaction ID shared by all operations in this transaction.
+     */
+    getTransactionId(): string;
+    private ensureActive;
+    private insert;
+    private update;
+    private deleteRecord;
+    private findById;
+    /**
+     * Get the effective state of a record, considering both the database and buffered operations.
+     * Buffered inserts/updates take precedence over the database state.
+     */
+    private getEffectiveRecord;
+}
+
 /**
  * Store is the main orchestrator. It owns a schema, a storage adapter,
  * a clock, and a subscription manager. It creates Collection instances
@@ -214,10 +681,16 @@ declare class Store implements OperationLog {
     private clock;
     private collections;
     private subscriptionManager;
+    private sequenceManager;
     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,
@@ -247,23 +720,166 @@ 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;
-    private nextSequenceNumber;
+    /**
+     * Get the sequence manager for offline-safe sequence generation.
+     * @throws {StoreNotOpenError} If the store is not open
+     */
+    getSequenceManager(): SequenceManager;
+    /**
+     * Create a TransactionContext for atomic multi-collection operations.
+     * The returned context buffers all mutations and commits them atomically.
+     *
+     * After commit, the caller is responsible for notifying subscriptions
+     * and emitting events for each operation.
+     */
+    createTransaction(): TransactionContext;
+    /**
+     * Execute a function within a transaction. All mutations performed on the
+     * TransactionContext are committed atomically. Subscription notifications
+     * are batched and fired after the commit.
+     *
+     * If the function throws, the transaction is rolled back and the error is re-thrown.
+     *
+     * @param fn - Function receiving a TransactionContext for buffered operations
+     * @returns The operations that were committed
+     */
+    transaction(fn: (tx: TransactionContext) => Promise<void>): Promise<Operation[]>;
+    /**
+     * 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.
+     */
+    private runMigrationsIfNeeded;
+    /**
+     * Get the stored schema version from _kora_meta. Returns 0 if not set.
+     */
+    private getStoredSchemaVersion;
+    /**
+     * Run a backfill transform on all records in a collection.
+     * Reads all rows, applies the transform, and updates changed fields.
+     */
+    private runBackfill;
     private loadOrGenerateNodeId;
     private loadSequenceNumber;
     private loadVersionVector;
@@ -281,56 +897,148 @@ interface CollectionAccessor {
 }
 
 /**
- * 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.
+ * Bloom filter for subscription dependency tracking.
+ *
+ * Each subscription adds its watched collection (and optionally fields) to the
+ * filter. When a mutation arrives, we check "collection" and "collection:field"
+ * keys against the filter. A negative result means no subscription cares about
+ * this mutation, so we can skip the expensive per-subscription scan.
+ *
+ * @example
+ * ```typescript
+ * const filter = new SubscriptionBloomFilter(100, 0.01)
+ * filter.add('todos')
+ * filter.add('todos', 'completed')
+ *
+ * filter.mightContain('todos')              // true (definitely added)
+ * filter.mightContain('projects')           // false (definitely not added)
+ * filter.mightContain('todos', 'completed') // true (definitely added)
+ * ```
  */
-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;
-    constructor(name: string, definition: CollectionDefinition, schema: SchemaDefinition, adapter: StorageAdapter, clock: HybridLogicalClock, nodeId: string, getSequenceNumber: () => number, onMutation: MutationCallback);
+declare class SubscriptionBloomFilter {
+    private bits;
+    private readonly bitCount;
+    private readonly hashCount;
+    private itemCount;
+    constructor(expectedItems: number, falsePositiveRate?: number);
     /**
-     * Insert a new record into the collection.
-     * Generates a UUID v7 for the id, validates data, and persists atomically.
+     * Add a collection (and optional field) to the bloom filter.
      *
-     * @param data - The record data (auto fields and defaults are applied automatically)
-     * @returns The inserted record with id, createdAt, updatedAt
+     * @param collection - Collection name (e.g., "todos")
+     * @param field - Optional field name (e.g., "completed")
      */
-    insert(data: Record<string, unknown>): Promise<CollectionRecord>;
+    add(collection: string, field?: string): void;
     /**
-     * Find a record by its ID. Returns null if not found or soft-deleted.
+     * Check if a collection (and optional field) might be in the filter.
+     *
+     * A return value of `false` means the item is DEFINITELY NOT in the filter.
+     * A return value of `true` means the item MIGHT be in the filter (possible false positive).
+     *
+     * @param collection - Collection name to check
+     * @param field - Optional field name to check
+     * @returns false = definitely absent, true = possibly present
      */
-    findById(id: string): Promise<CollectionRecord | null>;
+    mightContain(collection: string, field?: string): boolean;
     /**
-     * Update an existing record. Only the provided fields are changed.
+     * Reset the bloom filter, clearing all bits and the item count.
+     */
+    clear(): void;
+    /**
+     * Estimate the current false positive rate based on the number of items inserted.
+     *
+     * Formula: (1 - e^(-kn/m))^k
+     * where k = hash count, n = item count, m = bit count.
      *
-     * @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
+     * @returns Estimated false positive rate as a number between 0 and 1
      */
-    update(id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
+    estimatedFalsePositiveRate(): number;
+    /**
+     * @returns The number of items that have been added to the filter
+     */
+    getItemCount(): number;
+    /**
+     * @returns The total number of bits in the filter
+     */
+    getBitCount(): number;
     /**
-     * Soft-delete a record by its ID.
+     * @returns The number of hash functions used
+     */
+    getHashCount(): number;
+    /**
+     * Count the number of bits currently set to 1.
+     * Uses Brian Kernighan's algorithm: each iteration clears the lowest set bit,
+     * so the loop runs exactly as many times as there are set bits.
      *
-     * @param id - The record ID to delete
-     * @throws {RecordNotFoundError} If the record doesn't exist or is already deleted
+     * @returns Number of bits set to 1
      */
-    delete(id: string): Promise<void>;
-    /** Get the collection name */
-    getName(): string;
-    /** Get the collection definition */
-    getDefinition(): CollectionDefinition;
+    getSetBitCount(): number;
+    /**
+     * Compute k bit positions for a given key using Kirsch-Mitzenmacker double hashing.
+     *
+     * Instead of computing k independent hash functions, we compute two base hashes
+     * (h1 and h2) and derive the rest as: h_i = (h1 + i * h2) mod m.
+     * This technique is proven to have the same asymptotic false positive rate as
+     * k independent hash functions.
+     *
+     * We derive h1 and h2 from a single FNV-1a hash by splitting and mixing:
+     * h1 = fnv1a(key), h2 = fnv1a(key + "\0salt") to ensure independence.
+     */
+    private getPositions;
+}
+
+/**
+ * Error thrown when a local mutation attempts an invalid state transition.
+ *
+ * Contains enough context to debug without reproduction:
+ * the collection, record, field, current state, attempted state, and allowed transitions.
+ */
+declare class InvalidStateTransitionError extends KoraError {
+    readonly collection: string;
+    readonly recordId: string;
+    readonly field: string;
+    readonly fromState: string;
+    readonly toState: string;
+    readonly allowedStates: string[];
+    constructor(collection: string, recordId: string, field: string, fromState: string, toState: string, allowedStates: string[]);
 }
+/**
+ * Validates a state machine transition for a local mutation (insert or update).
+ *
+ * For inserts: validates that the initial state (from the data or the default value)
+ * is a known state in the state machine.
+ *
+ * For updates: looks up the current state field value and checks whether
+ * the transition to the new value is allowed.
+ *
+ * @param collectionName - Name of the collection
+ * @param recordId - The record being mutated
+ * @param stateMachine - The state machine definition
+ * @param currentState - The current value of the state field (null for inserts)
+ * @param newState - The new value being set for the state field
+ * @returns An object indicating whether the transition is valid, and if not, the allowed states.
+ *          When `onInvalidTransition` is 'last-valid-state', callers should suppress the field update
+ *          rather than throwing.
+ */
+declare function validateStateTransition(collectionName: string, recordId: string, stateMachine: StateMachineDefinition, currentState: string | null, newState: string): {
+    valid: boolean;
+    allowedStates: string[];
+};
+/**
+ * Checks whether a collection update data object contains a change to the state machine field,
+ * and if so, validates the transition.
+ *
+ * If the state field is not in the update data, returns the data unchanged.
+ * If the transition is invalid and mode is 'last-valid-state', removes the field from the data.
+ * If the transition is invalid and mode is 'reject', throws InvalidStateTransitionError.
+ *
+ * @param collectionName - Name of the collection
+ * @param recordId - The record being updated
+ * @param collectionDef - The collection definition from the schema
+ * @param currentRecord - The current record data (must include the state field)
+ * @param updateData - The partial update data
+ * @returns The update data, potentially with the state field removed if invalid and mode is 'last-valid-state'
+ */
+declare function validateUpdateStateMachine(collectionName: string, recordId: string, collectionDef: CollectionDefinition, currentRecord: Record<string, unknown>, updateData: Record<string, unknown>): Record<string, unknown>;
 
 type RichtextInput = string | Uint8Array | ArrayBuffer | null | undefined;
 /**
@@ -345,6 +1053,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.
@@ -373,4 +1086,63 @@ declare function pluralize(word: string): string;
  */
 declare function singularize(word: string): string;
 
-export { AdapterError, ApplyResult, Collection, type CollectionAccessor, CollectionRecord, OrderByDirection, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, RecordNotFoundError, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionCallback, SubscriptionManager, WhereClause, WorkerInitError, WorkerTimeoutError, decodeRichtext, encodeRichtext, pluralize, richtextToPlainText, singularize };
+/**
+ * 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, 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 };