@korajs/store 0.6.0 → 1.0.0-beta.1

package/dist/index.d.cts

@@ -1,10 +1,12 @@
-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-k6AZgiH4.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-k6AZgiH4.cjs';
+import { Operation, KoraError, VersionVector, SchemaDefinition, HLCTimestamp, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraBytesValue, KoraEvent, BlobRefMetadata, BlobRef } 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-DfPiPwKr.cjs';
+export { C as Collection } from './types-DfPiPwKr.cjs';
 import * as yjs from 'yjs';
+import { C as ContentAddressedBlobStore, M as MemoryBlobStore } from './content-addressed-blob-store-Dcj3SB9r.cjs';
+export { B as BlobIntegrityError } from './content-addressed-blob-store-Dcj3SB9r.cjs';
 
 /**
  * In-memory materialized state at a causal cut in the operation log.
@@ -33,6 +35,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.
  */
@@ -101,6 +115,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.
@@ -692,6 +720,7 @@ declare class Store implements OperationLog {
     private localMutationHandler;
     private relationEnforcer;
     private causalTracker;
+    private readonly secretKeyProvider;
     constructor(config: StoreConfig);
     /**
      * Open the store: initialize the database, load or generate a node ID,
@@ -715,6 +744,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.
@@ -722,6 +757,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.
@@ -775,6 +822,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).
      */
@@ -798,6 +853,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.
      */
@@ -1185,8 +1252,14 @@ declare function asRichTextSyncEngine(engine: unknown): RichTextSyncEngine | nul
 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.
  */
@@ -1287,4 +1360,392 @@ 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, 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 };
+/**
+ * The minimal directory abstraction an {@link OpfsBlobStore} needs. Blobs are
+ * laid out as `<shard>/<name>` (shard = first two hex chars of the hash) so a
+ * single directory never holds millions of entries.
+ *
+ * The real backend ({@link createOpfsBlobDirectory}) is the browser Origin
+ * Private File System; tests supply an in-memory implementation. Keeping this
+ * port small means the content-addressed logic (hashing, integrity, dedup,
+ * sharding) is fully testable without a browser.
+ */
+interface OpfsBlobDirectory {
+    /** Read the bytes at `<shard>/<name>`, or null if absent. */
+    read(shard: string, name: string): Promise<Uint8Array | null>;
+    /**
+     * Write bytes at `<shard>/<name>`, creating the shard directory as needed.
+     * Must be atomic: a crash mid-write may not leave a partially-written file
+     * that a later read would trust.
+     */
+    write(shard: string, name: string, bytes: Uint8Array): Promise<void>;
+    /** Remove `<shard>/<name>`. Returns whether anything was removed. */
+    remove(shard: string, name: string): Promise<boolean>;
+    /** Whether `<shard>/<name>` exists. */
+    has(shard: string, name: string): Promise<boolean>;
+    /** Count of stored blobs across all shards (temp files excluded). */
+    count(): Promise<number>;
+    /** Every stored blob name (hash) across all shards (temp files excluded). */
+    keys(): Promise<string[]>;
+}
+/**
+ * A persistent {@link ContentAddressedBlobStore} for the browser, backed by the
+ * Origin Private File System (OPFS) — the same durable storage the SQLite WASM
+ * adapter uses. Blobs survive reloads, are sharded by hash prefix, deduplicated,
+ * and integrity-verified on read (the returned bytes are checked to hash to the
+ * requested key). Writes commit atomically so a torn write cannot surface as
+ * trusted data.
+ *
+ * The store itself is environment-neutral: it talks to an {@link OpfsBlobDirectory}.
+ * Use {@link createOpfsBlobStore} in a browser to get one backed by real OPFS.
+ */
+declare class OpfsBlobStore implements ContentAddressedBlobStore {
+    private readonly dir;
+    constructor(dir: OpfsBlobDirectory);
+    private shardFor;
+    put(bytes: Uint8Array, metadata?: BlobRefMetadata): Promise<BlobRef>;
+    get(hash: string): Promise<Uint8Array | null>;
+    has(hash: string): Promise<boolean>;
+    delete(hash: string): Promise<boolean>;
+    size(): Promise<number>;
+    list(): Promise<string[]>;
+}
+/**
+ * Create an {@link OpfsBlobDirectory} backed by the browser's Origin Private
+ * File System, rooted at a named subdirectory. Best-effort requests persistent
+ * storage so the browser is less likely to evict blobs under storage pressure.
+ *
+ * @param rootDirName - The OPFS subdirectory to store blobs under (default `kora-blobs`)
+ * @throws {Error} If OPFS is unavailable (e.g. called outside a browser)
+ */
+declare function createOpfsBlobDirectory(rootDirName?: string): Promise<OpfsBlobDirectory>;
+/**
+ * Create a persistent {@link OpfsBlobStore} backed by real browser OPFS.
+ *
+ * @param rootDirName - The OPFS subdirectory to store blobs under (default `kora-blobs`)
+ * @throws {Error} If OPFS is unavailable (e.g. called outside a browser)
+ */
+declare function createOpfsBlobStore(rootDirName?: string): Promise<OpfsBlobStore>;
+
+/** Default chunk size for out-of-band blob transfer (256 KiB). */
+declare const DEFAULT_CHUNK_SIZE: number;
+/**
+ * A manifest describing how a blob is split into content-addressed chunks.
+ *
+ * The manifest is small and travels with the operation stream (or alongside it);
+ * the chunk bytes travel out of band. Because every chunk is content-addressed,
+ * identical chunks across blobs are stored and transferred once, and a peer only
+ * ever requests chunk hashes it does not already hold.
+ */
+interface BlobManifest {
+    /** Hex SHA-256 hash of the full reassembled blob (its content address). */
+    blobHash: string;
+    /** Total size of the full blob in bytes. */
+    size: number;
+    /** The chunk size used to split the blob. */
+    chunkSize: number;
+    /** Ordered hashes of each chunk. Repeats when identical chunks recur. */
+    chunkHashes: string[];
+    mimeType?: string;
+    filename?: string;
+}
+/** Optional metadata carried on a manifest. */
+interface BlobManifestMetadata {
+    mimeType?: string;
+    filename?: string;
+}
+/**
+ * Split a blob into content-addressed chunks and produce its manifest.
+ *
+ * @param bytes - The full blob content
+ * @param chunkSize - Bytes per chunk (defaults to {@link DEFAULT_CHUNK_SIZE})
+ * @param metadata - Optional mime type / filename to record on the manifest
+ * @returns The manifest and a map of chunk hash to chunk bytes (deduplicated)
+ */
+declare function chunkBlob(bytes: Uint8Array, chunkSize?: number, metadata?: BlobManifestMetadata): Promise<{
+    manifest: BlobManifest;
+    chunks: Map<string, Uint8Array>;
+}>;
+/**
+ * Reassemble a blob from chunks held in a content-addressed store, verifying
+ * integrity at both levels: each chunk is verified by the store on read, and the
+ * reassembled whole is verified against the manifest's blob hash.
+ *
+ * @param manifest - The blob manifest
+ * @param chunkStore - A store holding the chunk bytes keyed by chunk hash
+ * @returns The full reassembled blob bytes
+ * @throws {BlobIntegrityError} If the reassembled bytes do not match blobHash
+ * @throws {Error} If a chunk named in the manifest is missing from the store
+ */
+declare function reassembleBlob(manifest: BlobManifest, chunkStore: ContentAddressedBlobStore): Promise<Uint8Array>;
+
+/**
+ * A source of chunk bytes on the sending side of a transfer. In production this
+ * is backed by the sync connection (the receiver requests a chunk hash, the peer
+ * that holds the blob answers with the bytes); in tests it is backed by a map.
+ */
+interface ChunkProvider {
+    /** Fetch the bytes for a chunk hash, or null if the provider does not have it. */
+    getChunk(hash: string): Promise<Uint8Array | null>;
+}
+/** Result of receiving a blob out of band. */
+interface ReceiveBlobResult {
+    /** The content-addressed reference to the reassembled blob. */
+    ref: BlobRef;
+    /** Number of chunks actually fetched from the provider. */
+    chunksFetched: number;
+    /** Number of chunks skipped because they were already held locally. */
+    chunksSkipped: number;
+}
+/** Stores used while receiving a blob. */
+interface ReceiveBlobStores {
+    /**
+     * Where fetched chunks are staged, keyed by chunk hash. A persistent chunk
+     * store makes a transfer resumable: an interrupted transfer leaves its chunks
+     * here, and a resumed transfer skips them.
+     */
+    chunkStore: ContentAddressedBlobStore;
+    /** Where the fully reassembled, verified blob is written. */
+    blobStore: ContentAddressedBlobStore;
+}
+/**
+ * Receive a blob out of band, chunk by chunk, resumably and with integrity
+ * verification at every step.
+ *
+ * For each chunk named in the manifest: if the chunk store already holds it (a
+ * prior, possibly interrupted transfer), it is skipped; otherwise it is fetched
+ * from the provider and verified to hash to the expected chunk hash before being
+ * staged. Once every chunk is present, the blob is reassembled, verified against
+ * the manifest's blob hash, and written to the blob store (which deduplicates).
+ *
+ * The transfer is idempotent: running it again after completion fetches nothing
+ * and returns the same reference.
+ *
+ * @param manifest - The manifest of the blob to receive
+ * @param provider - The source of chunk bytes
+ * @param stores - The chunk staging store and the destination blob store
+ * @returns The reference plus how many chunks were fetched versus skipped
+ * @throws {BlobIntegrityError} If a fetched chunk or the whole blob fails verification
+ * @throws {Error} If the provider cannot supply a required chunk
+ */
+declare function receiveBlob(manifest: BlobManifest, provider: ChunkProvider, stores: ReceiveBlobStores): Promise<ReceiveBlobResult>;
+/**
+ * Prepare a blob for out-of-band sending: split it into chunks, stage those
+ * chunks in a content-addressed store, and return the manifest plus a
+ * {@link ChunkProvider} that serves the chunks from that store.
+ *
+ * @param bytes - The full blob content
+ * @param chunkStore - Where to stage the chunks (served to receivers)
+ * @param options - Optional chunk size and metadata
+ * @returns The manifest and a provider that serves the staged chunks
+ */
+declare function prepareBlobForSend(bytes: Uint8Array, chunkStore: ContentAddressedBlobStore, options?: {
+    chunkSize?: number;
+    mimeType?: string;
+    filename?: string;
+}): Promise<{
+    manifest: BlobManifest;
+    provider: ChunkProvider;
+}>;
+
+/**
+ * Serialize a {@link BlobManifest} to canonical bytes for content addressing.
+ *
+ * Fields are emitted in a fixed order so the same manifest always produces the
+ * same bytes, which is what lets the manifest be stored and fetched under its own
+ * SHA-256 hash. Optional fields are omitted when absent.
+ */
+declare function serializeBlobManifest(manifest: BlobManifest): Uint8Array;
+/**
+ * Parse canonical manifest bytes back into a {@link BlobManifest}, validating the
+ * shape. Throws on malformed input rather than returning a partial manifest.
+ */
+declare function parseBlobManifest(bytes: Uint8Array): BlobManifest;
+/**
+ * Store a blob for out-of-band transfer, addressed entirely by content.
+ *
+ * Stages the blob's chunks (so this device can serve them), stores the full blob
+ * (so local reads by hash are O(1)), and stores the blob's manifest as its own
+ * content-addressed object. The returned {@link BlobRef} carries `manifestHash`,
+ * so a peer that receives the reference in a synced record can pull the bytes
+ * knowing only the reference — no separate manifest hand-off.
+ *
+ * @param store - The content-addressed store to stage chunks, blob, and manifest in
+ * @param bytes - The full blob content
+ * @param options - Optional chunk size and metadata
+ * @returns The reference (including `manifestHash`) and the manifest
+ */
+declare function putBlobForTransfer(store: ContentAddressedBlobStore, bytes: Uint8Array, options?: {
+    chunkSize?: number;
+} & BlobRefMetadata): Promise<{
+    ref: BlobRef;
+    manifest: BlobManifest;
+}>;
+/**
+ * Fetch and integrity-verify a blob's manifest from a {@link ChunkProvider}.
+ *
+ * The manifest is a content-addressed object like a chunk, so it is requested by
+ * its hash, verified to hash to that value, and parsed. Used to resolve a
+ * {@link BlobRef}'s manifest before pulling the blob's chunks.
+ *
+ * @param provider - The source to fetch the manifest bytes from
+ * @param manifestHash - The manifest's content hash (from `BlobRef.manifestHash`)
+ * @throws {BlobIntegrityError} If the fetched bytes do not hash to `manifestHash`
+ * @throws {Error} If the provider cannot supply the manifest
+ */
+declare function fetchBlobManifest(provider: ChunkProvider, manifestHash: string): Promise<BlobManifest>;
+/**
+ * Resolve the manifest for a {@link BlobRef} that was stored via
+ * {@link putBlobForTransfer}. Fetches and verifies the manifest by the ref's
+ * `manifestHash`.
+ *
+ * @throws {Error} If the ref has no `manifestHash` (it was not stored for transfer)
+ */
+declare function resolveBlobManifest(provider: ChunkProvider, ref: BlobRef): Promise<BlobManifest>;
+
+/**
+ * The server-side blob callbacks a `KoraSyncServer` accepts: read a chunk by
+ * hash (to serve it) and persist an uploaded chunk by hash (to store it).
+ */
+interface ServerBlobCallbacks {
+    resolveBlobChunk: (hash: string) => Promise<Uint8Array | null>;
+    persistBlobChunk: (hash: string, bytes: Uint8Array) => Promise<void>;
+}
+/**
+ * Adapt a {@link ContentAddressedBlobStore} into the read/persist callbacks a
+ * `KoraSyncServer` needs for central blob storage. The server package depends
+ * only on these plain function signatures, so a self-hosted server can back its
+ * blob storage with any store (for example a `FilesystemBlobStore`) without the
+ * server package taking a dependency on `@korajs/store`.
+ *
+ * @example
+ * ```typescript
+ * const server = new KoraSyncServer({
+ *   store,
+ *   ...toServerBlobCallbacks(new FilesystemBlobStore('/var/kora/blobs')),
+ * })
+ * ```
+ */
+declare function toServerBlobCallbacks(store: ContentAddressedBlobStore): ServerBlobCallbacks;
+/**
+ * Convenience: an in-memory central blob store plus its server callbacks. For
+ * tests and single-process deployments. Persistent deployments should back
+ * {@link toServerBlobCallbacks} with a durable store instead.
+ */
+declare function createMemoryServerBlobStore(): {
+    store: MemoryBlobStore;
+    callbacks: ServerBlobCallbacks;
+};
+
+/** Outcome of a blob garbage-collection sweep. */
+interface BlobGcResult {
+    /** Total distinct blobs held before the sweep. */
+    scanned: number;
+    /** Distinct hashes kept because a live reference points to them (blob, manifest, or chunk). */
+    live: number;
+    /** Number of blobs deleted (or, with `dryRun`, that would be deleted). */
+    collected: number;
+    /** The hashes deleted (or, with `dryRun`, that would be deleted). */
+    collectedHashes: string[];
+}
+/** Options for {@link collectBlobGarbage}. */
+interface BlobGcOptions {
+    /** Compute what would be collected without deleting anything. */
+    dryRun?: boolean;
+}
+/**
+ * Extract the {@link BlobRef}s referenced by a materialized record. Scans the
+ * record's top-level field values, so it works without the schema; a `blob`
+ * field simply holds a `BlobRef`.
+ */
+declare function extractBlobRefs(record: Record<string, unknown>): BlobRef[];
+/**
+ * Garbage-collect a content-addressed blob store by mark-and-sweep: keep every
+ * blob reachable from a live reference, delete the rest.
+ *
+ * The live set is closed over the reference graph — for each live {@link BlobRef}
+ * it retains the blob hash, the manifest hash, and every chunk hash named in that
+ * manifest. Because chunks (and blobs) are shared by content address, a chunk
+ * referenced by any surviving blob is retained even if another blob that used it
+ * was collected. This makes GC safe under deduplication.
+ *
+ * Mark-and-sweep (rather than reference counting) is deliberate: counts are
+ * fragile under concurrent edits and CRDT merges, whereas a sweep against the
+ * current live set is always correct for the state it observes. Run it
+ * periodically or on demand.
+ *
+ * A manifest that cannot be read or parsed (corruption) contributes no chunk
+ * hashes; its own hash still counts as live. The blob it describes is already
+ * unusable, so its chunks becoming collectable is acceptable, and GC never
+ * throws on a single bad manifest.
+ *
+ * @param store - The blob store to sweep
+ * @param liveRefs - Every reference still reachable from live records
+ * @param options - `dryRun` to report without deleting
+ */
+declare function collectBlobGarbage(store: ContentAddressedBlobStore, liveRefs: Iterable<BlobRef>, options?: BlobGcOptions): Promise<BlobGcResult>;
+
+/**
+ * Blob chunk exchange messages. These ride any message transport (the sync
+ * WebSocket in production, an in-memory pair in tests). A receiver requests a
+ * chunk by hash and correlates the answer by `requestId`.
+ */
+interface ChunkRequestMessage {
+    type: 'blob-chunk-request';
+    requestId: string;
+    hash: string;
+}
+interface ChunkResponseMessage {
+    type: 'blob-chunk-response';
+    requestId: string;
+    /** The chunk bytes, or null when the responder does not hold that hash. */
+    bytes: Uint8Array | null;
+}
+type ChunkMessage = ChunkRequestMessage | ChunkResponseMessage;
+/**
+ * A bidirectional message port carrying {@link ChunkMessage}s. Implemented over
+ * the sync connection in production; `createChunkPortPair` provides an in-memory
+ * duplex pair for tests.
+ */
+interface ChunkMessagePort {
+    send(message: ChunkMessage): void;
+    /** Register a handler for incoming messages. Multiple handlers are allowed. */
+    onMessage(handler: (message: ChunkMessage) => void): void;
+}
+/** A {@link ChunkProvider} that fetches chunks over a message port. */
+interface RemoteChunkProvider extends ChunkProvider {
+    /** Number of requests still awaiting a response (for diagnostics/tests). */
+    pendingCount(): number;
+}
+/**
+ * Create a {@link ChunkProvider} that requests chunks over a message port,
+ * correlating each answer to its request and timing out a stalled request so a
+ * dropped response cannot hang a transfer forever (the transfer is resumable, so
+ * a timed-out request can simply be retried).
+ *
+ * @param port - The message port to the peer that holds the blob
+ * @param options.timeoutMs - Per-request timeout (default 30s)
+ */
+declare function createRemoteChunkProvider(port: ChunkMessagePort, options?: {
+    timeoutMs?: number;
+}): RemoteChunkProvider;
+/**
+ * Serve blob chunk requests arriving on a message port from a blob store. Answers
+ * each `blob-chunk-request` with the bytes for that hash, or null when the store
+ * does not hold it. Returns nothing; attach it once per connection.
+ *
+ * @param port - The message port from the peer requesting chunks
+ * @param blobStore - The store to serve chunks from (keyed by chunk hash)
+ */
+declare function serveBlobChunks(port: ChunkMessagePort, blobStore: ContentAddressedBlobStore): void;
+/**
+ * Create a connected in-memory pair of {@link ChunkMessagePort}s. Messages sent
+ * on one arrive on the other, asynchronously (next microtask) so the pair models
+ * a real transport rather than re-entrant synchronous delivery. For tests.
+ */
+declare function createChunkPortPair(): {
+    a: ChunkMessagePort;
+    b: ChunkMessagePort;
+};
+
+export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, type BlobGcOptions, type BlobGcResult, type BlobManifest, type BlobManifestMetadata, COMPACTION_BASELINE_META_KEY, type ChunkMessage, type ChunkMessagePort, type ChunkProvider, type ChunkRequestMessage, type ChunkResponseMessage, type ClockRebaseResult, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, ContentAddressedBlobStore, type CreateRichTextControllerOptions, DEFAULT_CHUNK_SIZE, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, MemoryBlobStore, type OpfsBlobDirectory, OpfsBlobStore, OptimisticLockError, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, type ReceiveBlobResult, type ReceiveBlobStores, RecordNotFoundError, type RemoteChunkProvider, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, RowVersionState, SequenceManager, type ServerBlobCallbacks, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, chunkBlob, collectBlobGarbage, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createChunkPortPair, createMemoryServerBlobStore, createOpfsBlobDirectory, createOpfsBlobStore, createRemoteChunkProvider, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, extractBlobRefs, fetchBlobManifest, getSharedQueryStoreCache, mergeVersionVectors, parseBlobManifest, persistedAuditTraceFromEvent, pluralize, prepareBlobForSend, putBlobForTransfer, readAuditExportManifest, readBackupManifest, reassembleBlob, receiveBlob, resolveBlobManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeBlobManifest, serializeVersionVectorToMeta, serveBlobChunks, singularize, toServerBlobCallbacks, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };