taladb 0.9.3 → 0.10.0

package/dist/index.d.ts

@@ -36,6 +36,67 @@ interface VectorSearchResult<T extends Document = Document> {
      */
     score: number;
 }
+interface TextSearchResult<T extends Document = Document> {
+    /** The matched document. */
+    document: T;
+    /**
+     * BM25 relevance score — higher means more relevant. Unbounded above, and
+     * only meaningful for ordering within a single query's result set.
+     */
+    score: number;
+}
+/** Tuning for `searchText`'s BM25 ranking. */
+interface TextSearchOptions {
+    /**
+     * Term-frequency saturation (BM25 `k1`, default `1.2`). Higher values let a
+     * repeated term keep adding relevance for longer.
+     */
+    k1?: number;
+    /**
+     * Length normalisation (BM25 `b`, default `0.75`). `0` ignores document
+     * length; `1` normalises fully by length relative to the corpus average.
+     */
+    b?: number;
+}
+interface HybridSearchResult<T extends Document = Document> {
+    /** The matched document. */
+    document: T;
+    /**
+     * Fused reciprocal-rank-fusion score. Small by construction and meaningful
+     * only as an ordering within one result set — never a similarity or a
+     * confidence.
+     */
+    score: number;
+    /**
+     * Zero-based position in the text ranking, or `null` if the text retriever
+     * did not return this document.
+     */
+    textRank: number | null;
+    /**
+     * Zero-based position in the vector ranking, or `null` if the vector
+     * retriever did not return this document.
+     */
+    vectorRank: number | null;
+}
+/** Tuning for `hybridSearch`'s fusion and per-retriever scoring. */
+interface HybridSearchOptions extends TextSearchOptions {
+    /**
+     * Reciprocal rank fusion smoothing constant (default `60`). Larger values
+     * flatten the advantage of the very top ranks.
+     */
+    rrfK?: number;
+    /** Relative weight of the text ranking (default `1`). Set `0` to disable it. */
+    textWeight?: number;
+    /** Relative weight of the vector ranking (default `1`). Set `0` to disable it. */
+    vectorWeight?: number;
+    /**
+     * How many candidates to pull from each retriever before fusing
+     * (default `max(topK * 4, 20)`). Raise it for better recall at more cost;
+     * fusing only `topK` from each side drops documents that rank just outside
+     * one retriever but high in the other.
+     */
+    candidates?: number;
+}
 type Value = null | boolean | number | string | Uint8Array | Value[] | {
     [key: string]: Value;
 };
@@ -43,6 +104,16 @@ type Document = {
     _id?: string;
     [key: string]: Value | undefined;
 };
+/**
+ * Who authored a write, and therefore whether it replicates outward.
+ *
+ * - `'local'` *(default)* — an ordinary user write. Replicates to peers as usual.
+ * - `'remote'` — a row replicated **in** from an authoritative origin. The origin
+ *   already has it, so it must never go back out: rows written this way fire no
+ *   sync events and never appear in `exportChanges()`, and deletes made this way
+ *   leave no tombstone. Enforced in the engine, not by convention.
+ */
+type WriteOrigin = 'local' | 'remote';
 /**
  * The operators available on a single field.
  *
@@ -211,12 +282,42 @@ interface CollectionOptions<T extends Document = Document> {
      * });
      */
     migrateDocument?: (doc: T, fromVersion: number) => T;
+    /**
+     * Lazy, read-time **downcast** — the mirror of {@link migrateDocument}, for a
+     * document written by a *newer* peer. When set, every document returned by
+     * `find` / `findOne` whose `_v` is **above** `syncSchema.version` is passed
+     * through `downgradeDocument(doc, fromVersion)` and projected into the shape
+     * this build understands, so application code on an old client sees a shape
+     * it can actually read instead of an unexpected future one.
+     *
+     * Requires `syncSchema.version`. Must be pure and deterministic.
+     *
+     * **The projection is view-only and is never persisted**, regardless of
+     * {@link persistMigrations}. The stored document keeps its original `_v` and
+     * its newer fields intact, because this replica must continue to replicate
+     * that document faithfully to other peers — an old client is a *reader* of a
+     * newer shape, never its editor. For the same reason the returned document
+     * keeps its original (higher) `_v`: it is a projection of a v-N document, not
+     * a v-M one, and writing it back wholesale would tell the fleet otherwise.
+     *
+     * @example
+     * // This build understands v1. A v2 peer split `name` into first/last.
+     * const users = db.collection<User>('users', {
+     *   syncSchema: { version: 1 },
+     *   downgradeDocument: (doc) => ({ ...doc, name: `${doc.first} ${doc.last}` }),
+     * });
+     */
+    downgradeDocument?: (doc: Readonly<T>, fromVersion: number) => T;
     /**
      * When `true`, a document upgraded by {@link migrateDocument} on read is
-     * **written back** to storage (a best-effort `updateOne` computing the
-     * `$set`/`$unset` diff) so the migration becomes permanent — after which
-     * filters and indexes on the new shape match it. Default `false` (the
-     * migrated shape is returned but not persisted).
+     * **written back** to storage (a best-effort `updateOne` computing a `$set`
+     * diff) so the migration becomes permanent — after which filters and indexes
+     * on the new shape match it. Default `false` (the migrated shape is returned
+     * but not persisted).
+     *
+     * The write-back is **additive-only** except for fields explicitly listed in
+     * {@link retiredFields}. A field present in storage but absent from the
+     * migrated document is otherwise left alone rather than `$unset`.
      *
      * Trade-offs: reads that encounter un-migrated documents now issue writes
      * (which fire live-query and sync-hook notifications like any other write);
@@ -224,6 +325,35 @@ interface CollectionOptions<T extends Document = Document> {
      * one-shot eager rewrite instead, prefer `openDB({ migrations })`.
      */
     persistMigrations?: boolean;
+    /**
+     * Fields an upcast is explicitly allowed to remove during persist-on-read.
+     * Prefer this precise list to {@link allowFieldRemoval}: omissions of any
+     * other field remain additive and are preserved.
+     */
+    retiredFields?: (keyof T & string)[];
+    /**
+     * How to read a field that {@link migrateDocument} left out of its output:
+     * as an intentional removal (`true`), or as a field the migration simply
+     * never heard of (`false`, the default).
+     *
+     * Default `false` — omitted fields are **preserved**: kept on the document
+     * returned to your code, and left in storage by the {@link persistMigrations}
+     * write-back rather than `$unset`.
+     *
+     * This default exists because on a synced collection the two cases are
+     * indistinguishable from the migration's output, and guessing "removal" is
+     * the destructive guess. A migration written today cannot mention a field a
+     * *newer* peer will add tomorrow, so an innocent `(doc) => ({ id, name })`
+     * becomes a deletion of a field its author never heard of — and under
+     * whole-document LWW that deletion replicates to the whole fleet. An old
+     * replica has to stay a faithful carrier of shapes it does not understand.
+     *
+     * Set `true` only on a collection that never syncs, or during a deliberate
+     * add → backfill → dual-read → **retire** rollout, where you already know the
+     * whole fleet has stopped writing the field.
+     */
+    /** @deprecated Prefer {@link retiredFields}; this treats every omission as removal. */
+    allowFieldRemoval?: boolean;
 }
 /** A single MongoDB-style aggregation stage. */
 type AggregateStage<T extends Document = Document> = {
@@ -255,6 +385,39 @@ type AggregatePipeline<T extends Document = Document> = AggregateStage<T>[];
 interface Collection<T extends Document = Document> {
     insert(doc: Omit<T, '_id'>): Promise<string>;
     insertMany(docs: Omit<T, '_id'>[]): Promise<string[]>;
+    /**
+     * Upsert many documents **by `_id`**, in a single commit. Existing rows are
+     * replaced in place, absent rows are created, and rows not named in `docs` are
+     * left alone — so writing page 2 never disturbs page 1.
+     *
+     * Unlike {@link insertMany}, which discards `_id` and mints a fresh ULID, this
+     * *honours* the id you supply. That is the whole point: for a row replicated
+     * from a remote origin, pass `_id: deriveDocId(collection, remoteKey)` and every
+     * later fetch of that row converges on the same document instead of duplicating
+     * it. Idempotent, and safe to run concurrently from a background hydration walk
+     * and an on-demand fetch.
+     *
+     * `origin: 'remote'` marks the rows as replicated in from an authoritative
+     * origin, which means they are **never replicated back out** — they will not
+     * fire sync events and will not appear in `exportChanges()`. Use it for anything
+     * the origin already knows about. Defaults to `'local'`.
+     *
+     * @example
+     * await products.replaceManyWithIds(
+     *   rows.map((r) => ({ ...r, _id: deriveDocId('products', r.id) })),
+     *   'remote',
+     * );
+     */
+    replaceManyWithIds(docs: T[], origin?: WriteOrigin): Promise<string[]>;
+    /**
+     * Delete many documents by `_id`, in a single commit. Returns how many were
+     * present and removed; unknown ids are skipped.
+     *
+     * `origin: 'remote'` deletes **without a tombstone**, so the deletion is not
+     * replicated outward — correct when the origin is the one that told you the row
+     * was deleted. Defaults to `'local'`, which tombstones as usual.
+     */
+    deleteManyWithIds(ids: string[], origin?: WriteOrigin): Promise<number>;
     find(filter?: Filter<T>): Promise<T[]>;
     findOne(filter: Filter<T>): Promise<T | null>;
     updateOne(filter: Filter<T>, update: Update<T>): Promise<boolean>;
@@ -265,7 +428,12 @@ interface Collection<T extends Document = Document> {
     /**
      * Run a MongoDB-style aggregation pipeline (`$match`, `$group`, `$sort`,
      * `$skip`, `$limit`, `$project`) inside the engine. Returns the resulting
-     * documents. Currently available on Node.js and the in-memory browser build.
+     * documents. Available on every runtime: Node, the OPFS worker, the in-memory
+     * browser build, and React Native.
+     *
+     * This is also how you page a collection locally — `find()` has no sort/skip/
+     * limit — but note it returns a **snapshot**. For a paged read that stays live
+     * as rows land, use {@link subscribeAggregate}.
      *
      * @example
      * const byStatus = await orders.aggregate([
@@ -303,6 +471,44 @@ interface Collection<T extends Document = Document> {
     createFtsIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     /** Drop a full-text search index. */
     dropFtsIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Rank documents against a free-text `query` using BM25, most relevant first.
+     *
+     * Unlike the `$contains` filter, which requires **every** token to be
+     * present, this uses OR semantics — a document that matches more of the
+     * query simply scores higher. Requires an FTS index on `field`.
+     *
+     * @example
+     * const hits = await articles.searchText('body', 'reset my password', 5);
+     * // hits: Array<{ document: Article, score: number }>
+     */
+    searchText(field: keyof Omit<T, '_id'> & string, query: string, topK: number, filter?: Filter<T>, options?: TextSearchOptions): Promise<TextSearchResult<T>[]>;
+    /**
+     * Hybrid retrieval: rank by keyword relevance (BM25) **and** vector
+     * similarity, then fuse the two rankings with reciprocal rank fusion.
+     *
+     * The two retrievers fail differently — keyword search misses paraphrases,
+     * vector search misses exact identifiers and rare proper nouns — so fusing
+     * them recovers both. A document both retrievers rank well outranks one that
+     * only a single retriever found. Requires an FTS index on `textField` and a
+     * vector index on `vectorField`.
+     *
+     * The optional `filter` is applied to both retrievers before ranking.
+     *
+     * @example
+     * const hits = await articles.hybridSearch(
+     *   { textField: 'body', text: 'reset my password' },
+     *   { vectorField: 'embedding', vector: queryVec },
+     *   5,
+     * );
+     */
+    hybridSearch(text: {
+        textField: keyof Omit<T, '_id'> & string;
+        text: string;
+    }, vector: {
+        vectorField: keyof Omit<T, '_id'> & string;
+        vector: number[];
+    }, topK: number, filter?: Filter<T>, options?: HybridSearchOptions): Promise<HybridSearchResult<T>[]>;
     /**
      * Return the indexes that currently exist on this collection.
      *
@@ -363,6 +569,28 @@ interface Collection<T extends Document = Document> {
      * unsub();
      */
     subscribe(filter: Filter<T>, callback: (docs: T[]) => void, onError?: (error: unknown) => void): () => void;
+    /**
+     * Subscribe to a live **aggregation** — the same as {@link subscribe}, but the
+     * result set is produced by a pipeline rather than a filter.
+     *
+     * This exists because {@link aggregate} is the only way to sort/skip/limit, and
+     * on its own it returns a dead snapshot: a paged read built on it would never
+     * re-run when new rows land, so a page would sit frozen while a background
+     * hydration filled the collection underneath it. Anything that pages locally
+     * should subscribe here instead of calling `aggregate` in an effect.
+     *
+     * The callback receives a snapshot immediately and again after every write that
+     * could affect the result.
+     *
+     * @returns An unsubscribe function.
+     *
+     * @example
+     * const unsub = products.subscribeAggregate(
+     *   [{ $match: { category: 'kitchen' } }, { $sort: { price: 1 } }, { $limit: 20 }],
+     *   (page) => render(page),
+     * );
+     */
+    subscribeAggregate<R extends Document = Document>(pipeline: AggregatePipeline<T>, callback: (docs: R[]) => void, onError?: (error: unknown) => void): () => void;
 }
 /**
  * A JSON-encoded changeset — the opaque payload exchanged between peers. Produced
@@ -384,9 +612,58 @@ interface SyncAdapter {
      * Fetch remote changes with `changed_at` after `sinceMs` (ms epoch), as a
      * serialized changeset. Return `'[]'` when there is nothing new. Required for
      * `'pull'` / `'both'`.
+     *
+     * @deprecated in spirit, not in support — wall-clock timestamps are not safe
+     * cursors (see {@link CursorSyncAdapter}), which is why every pass built on this
+     * method replays the whole collection from zero. Implement
+     * {@link CursorSyncAdapter.pullWithCursor} instead when your origin can issue a
+     * cursor. Adapters that only implement `pull` keep working unchanged.
      */
     pull?(sinceMs: number): Promise<SerializedChangeset>;
 }
+/** One page of remote changes, plus where to resume from. */
+interface PullResult {
+    /** The changes themselves. `'[]'` when there is nothing new. */
+    changeset: SerializedChangeset;
+    /**
+     * Opaque resume token, issued by the origin. **Never parse this.** It may be a
+     * timestamp, a sequence number, an LSN, a snapshot id — that is the origin's
+     * business, and treating it as a number is how clients reintroduce the
+     * clock-skew bug this type exists to kill.
+     */
+    cursor: string;
+    /** `true` when more pages remain; call again with the returned `cursor`. */
+    hasMore: boolean;
+}
+/**
+ * A {@link SyncAdapter} whose origin can issue a resume cursor.
+ *
+ * ## Why this exists
+ *
+ * The original contract is `pull(sinceMs)`, and it cannot be made correct. Author
+ * wall-clock timestamps are not safe cursors: a write can commit *after* an export
+ * yet carry an *earlier* timestamp, so resuming from "the newest timestamp I saw"
+ * silently drops rows. TalaDB's answer was to give up on cursors entirely and
+ * replay from zero on every pass — correct, but it re-downloads the whole
+ * collection forever, which makes a full local replica of a real catalog
+ * unaffordable.
+ *
+ * The fix is to stop inventing the cursor on the client. The origin issues an
+ * opaque token; we store it and hand it back. Whatever ordering guarantee the
+ * origin has (a sequence, an LSN, a snapshot) travels with the token, and the
+ * client never has to reason about clocks at all.
+ *
+ * `runSync` feature-detects `pullWithCursor` and prefers it. Adapters that only
+ * implement `pull(sinceMs)` are untouched and keep their replay-from-zero
+ * behavior.
+ */
+interface CursorSyncAdapter extends SyncAdapter {
+    /**
+     * Fetch changes after `cursor`, or from the beginning when it is `null`.
+     * Returns the changes plus the token to resume from next time.
+     */
+    pullWithCursor(cursor: string | null): Promise<PullResult>;
+}
 interface SyncOptions {
     /**
      * Collections to sync. Omit to sync **all** user collections (reserved
@@ -593,6 +870,504 @@ declare class HttpSyncAdapter implements SyncAdapter {
     pull(sinceMs: number): Promise<SerializedChangeset>;
 }
 
+/**
+ * Deterministic document ids for replicated rows.
+ *
+ * The engine assigns ULIDs and **ignores a caller-supplied `_id`** — it silently
+ * becomes an ordinary field, so `find({ _id: 'sku-1' })` then matches nothing.
+ * That leaves a document replicated from a remote origin with no stable local
+ * identity to merge on: re-fetching the same row would insert a duplicate.
+ *
+ * Hashing the origin's primary key into the ULID gives that identity back. The
+ * same `(collection, key)` always maps to the same document, which is what makes
+ * replication upserts **idempotent** (re-applying a page is a no-op), **resumable**
+ * (a bootstrap walk can restart mid-way), and **safe to run concurrently** (an
+ * on-demand fetch and the background walk can touch the same row and converge on
+ * one document rather than two).
+ *
+ * ## This must stay byte-identical to the Rust `derive_doc_id`
+ *
+ * The same rows are addressed from both sides. If the two implementations ever
+ * disagree, two clients assign different `_id`s to the same remote row and the
+ * replica silently forks into duplicates — with no error anywhere. The shared
+ * test vectors in `derive-id.test.ts` and `packages/core/src/document.rs` exist to
+ * make that impossible to do by accident; keep them in lockstep.
+ *
+ * FNV-1a is used over a stronger hash precisely *because* it is short enough to
+ * port between the two languages without ambiguity. It is non-cryptographic, which
+ * is fine here: the input is a primary key from an origin the client already
+ * trusts, not adversarial input.
+ */
+/**
+ * Derive a stable `_id` for a row replicated from a remote origin.
+ *
+ * `collection` is part of the preimage, so the same remote id in two different
+ * collections cannot collide.
+ *
+ * @example
+ * deriveDocId('products', 'sku-123')  // → '56GC678DQYWW1Z98HPYJ90WVKH', always
+ *
+ * ## Ordering caveat
+ *
+ * The result is a hash, so its ULID timestamp prefix is **not** chronological.
+ * Documents written with a derived id do not come back in insertion order from an
+ * unsorted `find()`; reads over replicated collections must carry an explicit
+ * sort. Documents written via `insert`/`insertMany` are unaffected — they still
+ * get monotonic ULIDs.
+ */
+declare function deriveDocId(collection: string, key: string): string;
+
+/**
+ * Coverage — "is this collection complete enough, locally, to answer a query
+ * without the network?"
+ *
+ * This is the question the whole coverage-first design turns on, and it is *not*
+ * "have I fetched this page?". A replica assembled from whichever pages a user
+ * happened to visit is an arbitrary partial subset: it cannot answer a query
+ * nobody has asked yet ("products under ₱500" may live on page 43), so every new
+ * filter or sort still goes to the network and the local database buys you almost
+ * nothing. Coverage is what licenses a purely local read.
+ *
+ * Two things make it trustworthy:
+ *
+ * 1. **It is scoped, not per-collection.** `complete` for a bare collection name
+ *    would leak across users: log in as someone else and you inherit the previous
+ *    user's "complete" flag *and* their rows. The key is a tuple.
+ * 2. **It is a state machine, not a boolean.** Only `complete` authorizes a
+ *    local-only read. `best-effort` exists precisely so an origin that *cannot*
+ *    give us a consistent snapshot degrades honestly instead of claiming a
+ *    completeness it never established.
+ */
+
+/** Reserved collection holding one coverage document per replicated scope. */
+declare const COVERAGE_COLLECTION = "__taladb_replica";
+/**
+ * What identifies a replicated scope. Every component must be part of the key,
+ * because each one changes what "complete" means:
+ *
+ * - `origin` — two origins are two different datasets.
+ * - `collection` — the local collection being filled.
+ * - `scope` — the *authorization* slice (a user, a tenant, a store). This is the
+ *   one that bites: without it, user B logging in inherits user A's completeness.
+ * - `projectionVersion` — a replica hydrated with a slimmer projection is not
+ *   complete for a query that needs the dropped fields.
+ * - `schemaVersion` — rows hydrated under an older shape may not satisfy today's.
+ */
+interface CoverageKey {
+    origin: string;
+    collection: string;
+    scope: string;
+    projectionVersion: number;
+    schemaVersion: number;
+}
+type CoverageState = 
+/** Nothing local. */
+{
+    status: 'empty';
+}
+/**
+ * A bootstrap walk is in progress. `snapshot` pins every page to one logical
+ * view of the origin; `nextPage` is the durable resume point.
+ */
+ | {
+    status: 'hydrating';
+    snapshot: string;
+    nextPage: string | number;
+    rowsApplied: number;
+    deltaCursor?: string;
+    total?: number;
+}
+/**
+ * The scope is fully local as of `cursor`. **The only state that permits a
+ * local-only read.**
+ */
+ | {
+    status: 'complete';
+    cursor: string;
+    completedAt: number;
+    rowsApplied: number;
+    total?: number;
+}
+/**
+ * Every row the origin offered was applied, but the origin could not pin a
+ * snapshot, so we cannot *prove* we saw a consistent view — a row that shifted
+ * between pages mid-walk may have been missed. Reads must not treat this as
+ * authoritative.
+ */
+ | {
+    status: 'best-effort';
+    cursor: string;
+    reason: string;
+    rowsApplied: number;
+    total?: number;
+}
+/** Complete once, but known to have fallen behind (e.g. a projection change). */
+ | {
+    status: 'stale';
+    cursor: string;
+    reason: string;
+}
+/** The walk failed. `resumeFrom` is where to pick it up. */
+ | {
+    status: 'error';
+    resumeFrom: string | number;
+    snapshot?: string;
+    deltaCursor?: string;
+    rowsApplied?: number;
+    total?: number;
+    error: string;
+};
+/**
+ * Serialize a {@link CoverageKey} into a stable string.
+ *
+ * Field order is fixed rather than derived from `Object.keys`, so the key cannot
+ * change meaning if someone reorders the interface — a silent coverage reset,
+ * which would look like "the app re-downloads everything for no reason".
+ */
+declare function coverageKey(key: CoverageKey): string;
+/**
+ * Persistent coverage state, one document per scope.
+ *
+ * The state is stored as a JSON string rather than as structured fields: it is a
+ * discriminated union whose shape varies per variant, and TalaDB documents are
+ * flat. Writing it whole also makes each transition a single atomic write, which
+ * is what lets `markComplete` be the durable commit point of a bootstrap.
+ */
+declare class CoverageStore {
+    private readonly col;
+    constructor(db: TalaDB);
+    read(key: CoverageKey): Promise<CoverageState>;
+    write(key: CoverageKey, state: CoverageState): Promise<void>;
+    /** Drop a scope's coverage, forcing a fresh bootstrap on next use. */
+    clear(key: CoverageKey): Promise<void>;
+}
+/**
+ * Whether a local-only read is authorized for this state.
+ *
+ * Deliberately strict: **only `complete`**. `best-effort` is the interesting
+ * exclusion — it means we applied everything the origin gave us, but the origin
+ * could not pin a snapshot, so a row that moved between pages during the walk may
+ * never have been seen. Serving that as authoritative would silently return
+ * incomplete results, which is worse than going to the network.
+ */
+declare function isAuthoritative(state: CoverageState): boolean;
+/** Rows applied so far, for progress reporting. */
+declare function rowsApplied(state: CoverageState): number;
+/** Fractional hydration progress, when the origin told us the total. */
+declare function progress(state: CoverageState): number | undefined;
+
+/**
+ * The replication *source* — wire translation, and nothing else.
+ *
+ * A source knows how to talk to one origin: how to ask for a page, how to ask for
+ * changes since a cursor, how to find a row's primary key, and how to shape a row
+ * into a document. It owns **no orchestration**: no batching, no yielding, no
+ * cursor persistence, no coverage transitions, no retry, no dedup. All of that
+ * belongs to the coordinator, which is generic over sources.
+ *
+ * That split is deliberate. The obvious alternative — make the REST origin a
+ * `SyncAdapter` and let `db.sync()` drive it — does not work: a bootstrap of 100k
+ * rows would sit inside a single `pull()` call with no way to report progress,
+ * pause, resume, or yield to the UI between pages. Orchestration has to live one
+ * level up, or it cannot be orchestrated at all.
+ */
+
+/** The origin's primary key for a row. Stringified before hashing into an id. */
+type RemoteKey = string;
+/** A request for one page of the initial bootstrap walk. */
+interface BootstrapRequest {
+    /**
+     * Where to resume. `null` on the first call — which is also when the origin is
+     * expected to *issue* the snapshot and delta cursor.
+     */
+    page: string | number | null;
+    /**
+     * The snapshot token from the first page, echoed back on every subsequent one.
+     * `null` on the first call, and on origins that don't support snapshots.
+     */
+    snapshot: string | null;
+    /** Rows per page. */
+    limit: number;
+}
+/** One page of the bootstrap walk. */
+interface BootstrapPage<RemoteRow> {
+    rows: RemoteRow[];
+    /** Resume token for the next page; `null` when the walk is done. */
+    nextPage: string | number | null;
+    /**
+     * An opaque token pinning every page of this walk to one logical view of the
+     * origin.
+     *
+     * **Omit it and you get `best-effort` coverage, not `complete`.** Without a
+     * snapshot, a page walk over live data is not a consistent read: fetch page 1,
+     * a row is inserted, everything shifts, and the row that was going to be on
+     * page 20 is now on page 19 — which you already passed. It is never seen. The
+     * walk still "succeeds", and the replica silently has a hole in it. Since
+     * nothing detects that, the honest response is to refuse to call the result
+     * complete, and to keep serving reads from the network.
+     */
+    snapshot?: string;
+    /**
+     * The cursor to begin the *delta* stream from once the walk finishes. Issued on
+     * the first page — i.e. as of the snapshot — so no change made during the walk
+     * can slip between "bootstrap ended" and "delta began".
+     */
+    deltaCursor?: string;
+    /** Total rows in scope, when the origin knows it. Drives progress reporting. */
+    total?: number;
+}
+/** One batch of incremental changes since a cursor. */
+interface DeltaPage<RemoteRow> {
+    changed: RemoteRow[];
+    /**
+     * Primary keys the origin has deleted.
+     *
+     * This is the only way a REST replica learns about deletions. A plain paged GET
+     * returns survivors, and a row's *absence* from a response is ambiguous — it may
+     * have been deleted, or it may merely have shifted to another page. Guessing
+     * would eventually delete live data, so we never infer; the origin must say so.
+     */
+    deleted: RemoteKey[];
+    cursor: string;
+    hasMore: boolean;
+}
+/**
+ * Everything the coordinator needs to replicate one collection from one origin.
+ *
+ * @typeParam RemoteRow - the row shape the origin returns, before mapping.
+ * @typeParam T - the local document shape.
+ */
+interface ReplicationSource<RemoteRow = unknown, T extends Document = Document> {
+    /** Bump when a custom source's behavior changes without changing its metadata. */
+    readonly configVersion?: string | number;
+    /** Stable identity for this origin. Part of the coverage key. */
+    readonly origin: string;
+    /** The local collection this source fills. */
+    readonly collection: string;
+    /**
+     * The authorization slice these rows belong to — a user, tenant, or store.
+     * Part of the coverage key, so one user's completeness never licenses another's
+     * reads. Use a constant for genuinely global data.
+     */
+    readonly scope: string;
+    /** Bump when {@link mapRow} starts producing a different shape. */
+    readonly projectionVersion: number;
+    /** Bump when the local schema changes in a way hydrated rows must match. */
+    readonly schemaVersion: number;
+    /** Fetch one page of the initial walk. */
+    bootstrap(request: BootstrapRequest): Promise<BootstrapPage<RemoteRow>>;
+    /** Fetch changes since `cursor`. Absent when the origin has no delta feed. */
+    delta?(cursor: string): Promise<DeltaPage<RemoteRow>>;
+    /**
+     * Fetch exactly the rows a specific query needs, for the cold-start bridge.
+     *
+     * Optional. When absent, a query against an un-hydrated scope simply waits for
+     * coverage rather than short-circuiting to the network.
+     */
+    fetchQuery?(query: BridgeQuery): Promise<RemoteRow[]>;
+    /** The origin's primary key for a row. Must be stable across fetches. */
+    keyOf(row: RemoteRow): RemoteKey;
+    /**
+     * Monotonic authoritative revision for stale-response protection. Strongly
+     * recommended whenever bridge/bootstrap/delta requests may overlap.
+     */
+    revisionOf(row: RemoteRow): number;
+    /** Shape a remote row into a local document (minus `_id`, which is derived). */
+    mapRow(row: RemoteRow): Omit<T, '_id'>;
+}
+/**
+ * A local query, handed to the bridge so it can ask the origin for the same rows.
+ *
+ * Deliberately loose: every REST API spells pagination and filtering differently,
+ * so translating this into a query string is the source's job, not ours.
+ */
+interface BridgeQuery {
+    filter?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    page?: number;
+    limit?: number;
+}
+
+/**
+ * The replication coordinator — all orchestration, no wire format.
+ *
+ * Owns: the bootstrap walk, resume-after-crash, delta refresh, the cold-start
+ * bridge, batching, yielding, coverage transitions, and in-flight dedup. The
+ * {@link ReplicationSource} it drives owns only wire translation.
+ *
+ * ## The two mechanisms are one mechanism
+ *
+ * "Fetch the page the user is looking at" and "import the whole catalog in the
+ * background" look like separate features. They are the same primitive with two
+ * schedulers: *fetch rows → upsert them by derived id*. Because both write the
+ * **same rows under the same ids**, they compose for free — a bridged fetch is not
+ * a throwaway cache entry, it is a down payment on the replica, and when the walk
+ * later reaches those rows it overwrites them in place instead of duplicating
+ * them. Nothing has to reconcile the two.
+ *
+ * The one thing they do *not* share is coverage. A bridge fetch must never advance
+ * the bootstrap cursor, because it did not come from the walk's snapshot and
+ * proves nothing about completeness. Trading a little duplicate network for a
+ * trustworthy completeness proof is the right side of that bargain.
+ */
+
+interface CoordinatorOptions<T extends Document = Document> {
+    /** Rows per bootstrap page. Larger = fewer commits, longer stalls. */
+    pageSize?: number;
+    /**
+     * Called between pages so the walk yields. Defaults to a macrotask.
+     *
+     * This matters more than it looks. Live queries re-run on a 300 ms poll, and on
+     * React Native every write is *synchronous on the JS thread* — a tight bootstrap
+     * loop starves both, and the UI freezes for the duration of the import.
+     */
+    yieldFn?: () => Promise<void>;
+    /** Fired after each committed page, for progress UI. */
+    onProgress?: (state: CoverageState) => void;
+    /** Collection schema/migration options registered by the host application. */
+    collectionOptions?: CollectionOptions<T>;
+}
+declare const REPLICA_SCOPE_FIELD = "_replica_scope";
+declare const REPLICA_REVISION_FIELD = "_remote_rev";
+interface BridgeResult {
+    count: number;
+    ids: string[];
+}
+declare class ReplicationCoordinator<RemoteRow, T extends Document> {
+    private readonly db;
+    private readonly source;
+    private readonly coverage;
+    private readonly key;
+    private readonly pageSize;
+    private readonly yieldFn;
+    private readonly onProgress?;
+    private readonly collectionOptions?;
+    /**
+     * In-flight passes, keyed by intent. Two components mounting the same query must
+     * fire one request, and the background walk must not race the bridge for the
+     * same rows — both join the existing promise instead.
+     */
+    private readonly inflight;
+    constructor(db: TalaDB, source: ReplicationSource<RemoteRow, T>, options?: CoordinatorOptions<T>);
+    get replicaScope(): string;
+    private get identityNamespace();
+    getCoverage(): Promise<CoverageState>;
+    /** Whether a purely local read is authorized right now. */
+    isReady(): Promise<boolean>;
+    /** Dedup by intent: identical concurrent work joins rather than duplicating. */
+    private dedup;
+    /**
+     * Write a batch of remote rows into the local collection.
+     *
+     * One commit for the whole batch, ids derived from the origin's primary key, and
+     * `origin: 'remote'` so the rows can never replicate back out at the origin they
+     * came from. This is the *only* write path in the coordinator — bootstrap, delta
+     * and bridge all funnel through it, which is precisely why they converge instead
+     * of conflicting.
+     */
+    private applyRows;
+    /**
+     * Hydrate the scope: walk the origin page by page until the whole collection is
+     * local, then mark it complete.
+     *
+     * Resumable and idempotent. If the walk is interrupted — a reload, a crash, a
+     * dead network — the next call picks up from the last committed page, and
+     * re-applying a page it already wrote is a no-op because the ids are derived.
+     */
+    hydrate(): Promise<CoverageState>;
+    private runHydrate;
+    /**
+     * Apply incremental changes since the stored cursor.
+     *
+     * Deletions are applied by mapping the origin's primary keys through the same
+     * `deriveDocId`, and are written with `origin: 'remote'` so they leave no
+     * tombstone — the origin already knows it deleted these, and a tombstone would
+     * push its own deletion back at it.
+     */
+    refresh(): Promise<CoverageState>;
+    private runRefresh;
+    /**
+     * Cold-start bridge: fetch exactly the rows one query needs, right now.
+     *
+     * Needed because a SPA or React Native app has no server render to paint behind
+     * while the replica fills. The rows land in the same collection under the same
+     * derived ids as the walk's, so this is not a cache — it is the replica, arriving
+     * early.
+     *
+     * **Does not advance coverage.** These rows did not come from the bootstrap
+     * snapshot and prove nothing about completeness; treating them as progress would
+     * let a page-1 fetch masquerade as a hydrated catalog.
+     */
+    bridge(query: BridgeQuery): Promise<BridgeResult>;
+    /** Drop coverage and force a fresh bootstrap. Local rows are left alone. */
+    reset(): Promise<void>;
+}
+
+/**
+ * A {@link ReplicationSource} for an ordinary paged JSON API.
+ *
+ * This is the adoption path: point it at `GET /api/products?page=1&limit=500` and
+ * a team on Express + Postgres gets a local replica without rewriting their API to
+ * speak TalaDB's sync contract. Everything here is wire translation — the
+ * coordinator owns the walk, the coverage, and the retries.
+ *
+ * ## What the origin has to provide, and what happens when it doesn't
+ *
+ * | Feature | Endpoint | Without it |
+ * |---|---|---|
+ * | Paged list | `?page=&limit=` | Nothing works. Required. |
+ * | Snapshot token | `snapshot` in the response | Coverage caps at `best-effort`; reads keep hitting the network |
+ * | Delta feed | `?since=<cursor>` | No incremental refresh, and **deletions never propagate** |
+ *
+ * The snapshot and the delta feed are each about twenty minutes of Express work
+ * (a monotonic `updated_at`/revision column, a soft-delete table, and a
+ * `rev <= snapshotRev` predicate). They are worth it: without a snapshot the
+ * replica can never be trusted for a local-only read, which is the entire point.
+ */
+
+interface RestSourceOptions<RemoteRow, T extends Document> {
+    /** Base URL, e.g. `/api/products`. */
+    endpoint: string;
+    /** The local collection to fill. */
+    collection: string;
+    /** Stable identity for the origin. Defaults to `endpoint`. */
+    origin?: string;
+    /**
+     * The authorization slice these rows belong to — a user id, tenant, or store.
+     * Part of the coverage key, so one user's completeness never licenses another
+     * user's reads. Defaults to `'global'`; **set it for anything user-scoped.**
+     */
+    scope?: string;
+    /** Bump when {@link mapRow} starts producing a different shape. Default 1. */
+    projectionVersion?: number;
+    /** Bump when the local schema changes. Default 1. */
+    schemaVersion?: number;
+    /** Field on the remote row holding its primary key. Default `'id'`. */
+    key?: string;
+    /** Field/callback yielding a monotonic numeric row revision. Default `'rev'`. */
+    revision?: string | ((row: RemoteRow) => number | undefined);
+    /** Shape a remote row into a local document. Default: identity, minus `_id`. */
+    mapRow?: (row: RemoteRow) => Omit<T, '_id'>;
+    /** Per-request headers, resolved **at send time** so a refreshed token is used. */
+    getAuth?: () => Promise<Record<string, string>> | Record<string, string>;
+    /** `fetch` implementation. Defaults to the global. */
+    fetch?: typeof fetch;
+    /** Sub-paths appended to `endpoint`. */
+    paths?: {
+        bootstrap?: string;
+        delta?: string;
+    };
+    /** Enable delta polling. Defaults to true only when `paths.delta` is set. */
+    delta?: boolean;
+    /** Meaning of the fallback `page` parameter when no next token is returned. */
+    pagination?: 'page' | 'offset';
+    /** Translate a local query into this API's query-string conventions. */
+    toParams?: (query: BridgeQuery) => Record<string, string>;
+    /** Pull the row array out of a response whose envelope we don't recognize. */
+    parse?: (body: unknown) => unknown[];
+}
+declare function createRestSource<RemoteRow = Record<string, unknown>, T extends Document = Document>(options: RestSourceOptions<RemoteRow, T>): ReplicationSource<RemoteRow, T>;
+
 /**
  * Thrown when a document fails schema validation on `insert` or `insertMany`.
  * The `cause` property holds the original error thrown by the schema library.
@@ -704,4 +1479,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type DurabilityConfig, type Filter, HttpSyncAdapter, type Migration, type OpenDBOptions, type Schema, type SerializedChangeset, type SyncAdapter, type SyncConfig, type SyncDirection, type SyncOptions, type SyncResult, type TalaDB, type TalaDbConfig, TalaDbValidationError, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, applySchema, openDB, runMigrations };
+export { type AggregatePipeline, type AggregateStage, type BootstrapPage, type BootstrapRequest, type BridgeQuery, type BridgeResult, COVERAGE_COLLECTION, type Collection, type CollectionIndexInfo, type CollectionOptions, type CoordinatorOptions, type CoverageKey, type CoverageState, CoverageStore, type CursorSyncAdapter, type DeltaPage, type Document, type DurabilityConfig, type Filter, HttpSyncAdapter, type HybridSearchOptions, type HybridSearchResult, type Migration, type OpenDBOptions, type PullResult, REPLICA_REVISION_FIELD, REPLICA_SCOPE_FIELD, type RemoteKey, ReplicationCoordinator, type ReplicationSource, type RestSourceOptions, type Schema, type SerializedChangeset, type SyncAdapter, type SyncConfig, type SyncDirection, type SyncOptions, type SyncResult, type TalaDB, type TalaDbConfig, TalaDbValidationError, type TextSearchOptions, type TextSearchResult, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, type WriteOrigin, applySchema, coverageKey, createRestSource, deriveDocId, isAuthoritative, openDB, progress, rowsApplied, runMigrations };