@voltro/plugin-search 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import { ColumnDefinition } from '@voltro/database';
 import { DataStore } from '@voltro/database';
 import { PluginChangeEvent } from '@voltro/protocol';
+import { QueryDescriptor } from '@voltro/database';
+import { Schedule } from 'effect';
+import { Schema } from 'effect';
 import { TableIndex } from '@voltro/database';
 import { TableLike } from '@voltro/database';
 import { VoidIfEmpty } from 'effect/Types';
@@ -12,14 +15,56 @@ import { YieldableError } from 'effect/Cause';
  *  tolerance (`typoTolerance`), engine-param passthrough.
  *  DEGRADED: like Meili, no numeric edit-distance knob — `fuzziness:0` maps to
  *  `typoTolerance:false`; other values keep Algolia's built-in tolerance. */
-export declare const algoliaBackend: (cfg: VendorConfig) => SearchBackend;
+export declare const algoliaBackend: (cfg: VendorConfig, hooks?: BackendHooks) => SearchBackend;
+
+/** The engineParams keys this engine accepts from a wire caller — exported so
+ *  the docs and tests read the same list the runtime enforces. */
+export declare const allowedEngineParams: (engine: SearchEngine) => ReadonlyArray<string>;
 
 /** Apply one ChangeEvent to the backend (pure-ish; exported for tests). */
 export declare const applyChange: (backend: SearchBackend, spec: IndexSpec, event: PluginChangeEvent) => Promise<void>;
 
+/**
+ * Coerce whatever the sync path threw into the typed error the retry policy
+ * reads. Anything that is not a `SearchBackendError` — a `map(row)` that threw
+ * a TypeError on one row's shape — is by definition NOT transient: retrying a
+ * deterministic throw spends the whole budget and cannot succeed.
+ */
+export declare const asBackendError: (e: unknown) => SearchBackendError;
+
+export declare const auditMemoryBackend: (input: MemoryBackendAuditInput) => MemoryBackendVerdict;
+
+/** Anything the `backend` option accepts, narrowed to what the guard reads. */
+export declare type BackendConfigLike = undefined | 'memory' | (SearchBackend & {
+    readonly engineKind?: string;
+}) | {
+    readonly engine?: string;
+};
+
+/**
+ * Server-side knobs a vendor backend takes from whoever CONSTRUCTS it (the
+ * plugin, from `app.config.ts`). Deliberately not part of `VendorConfig` and
+ * never reachable from the wire — these decide how much of a wire caller's
+ * `engineParams` is honoured, so a caller must not be able to set them.
+ */
+export declare interface BackendHooks {
+    /** Extra `engineParams` keys THIS app trusts, on top of the built-in
+     *  presentation-only allowlist. Keys that select the document set
+     *  (`filter_by`, `facetFilters`, `restrictSearchableAttributes`, …) stay
+     *  refused regardless — see `NEVER_ALLOWED_ENGINE_PARAMS`. */
+    readonly allowEngineParams?: ReadonlyArray<string>;
+    /** Called when a query is stripped of `engineParams` keys, so a refusal that
+     *  changes the answer is visible in the log rather than silent. */
+    readonly onWarn?: (message: string, fields?: Record<string, unknown>) => void;
+}
+
+export declare const backendKindOf: (cfg: BackendConfigLike) => SearchBackendKind;
+
 /** Seed an index from existing rows (call from a `*.startup.tsx` or a CLI). */
 export declare const backfillIndex: (backend: SearchBackend, spec: IndexSpec, rows: ReadonlyArray<Record<string, unknown>>) => Promise<number>;
 
+export declare const dataStoreDriftLedger: (store: DataStore) => DriftLedger;
+
 /**
  * DataStore-backed stats. Each replica owns one row per index (keyed by
  * `replicaId`). A counter bump is a compare-and-set loop on THAT row (mirror of
@@ -29,9 +74,76 @@ export declare const backfillIndex: (backend: SearchBackend, spec: IndexSpec, ro
  */
 export declare const dataStoreStatsStore: (store: DataStore, replicaId?: string) => StatsStore;
 
+/** One un-applied change, as the ledger stores it. */
+export declare interface DriftEntry {
+    readonly indexName: string;
+    /** Source table the row lives in — repair re-reads it from here. */
+    readonly sourceTable: string;
+    /** Primary key of the source ROW (what repair re-reads). */
+    readonly rowId: string;
+    /** Id of the search DOC (`map(row).id`) — what repair removes when the row
+     *  is gone. Not always the row id: `map` may re-key. */
+    readonly docId: string;
+    readonly op: DriftOp;
+    /** How many times applying this row has failed (first failure = 1). */
+    readonly attempts: number;
+    readonly lastError: string;
+    readonly firstFailedAt: string;
+    readonly lastFailedAt: string;
+}
+
+export declare interface DriftLedger {
+    /** Record (or re-record) a row whose index update did not land. */
+    readonly record: (entry: DriftRecord) => Promise<void>;
+    /** Oldest-first batch to repair. */
+    readonly list: (limit: number) => Promise<ReadonlyArray<DriftEntry>>;
+    readonly summary: (indexName: string) => Promise<DriftSummary>;
+    /** Drop the entry — the row is in sync again. */
+    readonly clear: (indexName: string, rowId: string) => Promise<void>;
+}
+
+/** What the repair has to do for this row: put the doc back, or take it out. */
+export declare type DriftOp = 'upsert' | 'remove';
+
+/** The write side of `DriftEntry` — the counters/timestamps are the ledger's. */
+export declare interface DriftRecord {
+    readonly indexName: string;
+    readonly sourceTable: string;
+    readonly rowId: string;
+    readonly docId: string;
+    readonly op: DriftOp;
+    readonly error: string;
+}
+
+/** Re-read ONE source row by primary key. Exported so `index.ts` can drive the
+ *  repair through the store handle it already holds, without importing the
+ *  query builder itself. */
+export declare const driftSourceQuery: (sourceTable: string, rowId: string) => QueryDescriptor;
+
+/** Per-index drift, as `/indexes` reports it. `pending > 0` means the index is
+ *  KNOWN to disagree with the database right now. */
+export declare interface DriftSummary {
+    readonly pending: number;
+    readonly lastFailedAt: string | null;
+}
+
+declare interface DriftTable extends TableLike {
+    readonly fields: Record<string, ColumnDefinition<unknown>>;
+    readonly appliedIndexes: ReadonlyArray<TableIndex>;
+}
+
+/** All tables for `extendSchema.tables`. */
+export declare const driftTables: () => ReadonlyArray<DriftTable>;
+
 /** field → (value → count). Present only for the requested `facets`. */
 export declare type FacetCounts = Record<string, Record<string, number>>;
 
+/** A caller-supplied field name must be a plain field path: an identifier,
+ *  optionally dotted for a nested attribute. No spaces, quotes, brackets,
+ *  operators or boolean keywords — i.e. nothing that means anything to a
+ *  filter DSL. */
+export declare const FIELD_NAME_PATTERN: RegExp;
+
 /** Typo-tolerance knob: a max edit distance (0 = exact), or `'auto'` to let the
  *  engine pick per-term length. Memory approximates `'auto'` as distance 1–2. */
 export declare type Fuzziness = number | 'auto';
@@ -52,6 +164,19 @@ export declare interface IndexSpec {
     /** Doc field carrying the tenant id — when set, `search.query` auto-filters
      *  to the caller's tenant (no cross-tenant leakage). */
     readonly tenantField?: string;
+    /**
+     * Doc fields a WIRE caller may name — in `filters[].field`, `facets[]` and
+     * `highlight.fields[]`. When set, anything else is refused with a typed
+     * `SearchFieldRejected`; when omitted, any plain field path
+     * (`^[A-Za-z_][A-Za-z0-9_.]*$`) is accepted.
+     *
+     * Opt-in because it cannot be derived: `map(row)` is a FUNCTION, so the doc's
+     * field set only exists at runtime. The pattern is the floor every index gets
+     * without declaring anything; this narrows it to what your UI actually needs.
+     * `tenantField` does not belong here — the tenant clause is injected AFTER
+     * this check, by the server, and is never a caller's to name.
+     */
+    readonly queryableFields?: ReadonlyArray<string>;
 }
 
 /** Aggregated, cross-replica stats for one index — the exact wire shape the
@@ -59,28 +184,119 @@ export declare interface IndexSpec {
 export declare interface IndexStats {
     readonly synced: number;
     readonly removed: number;
+    /** Changes that exhausted the sync retry and were written to the drift
+     *  ledger instead of reaching the engine. Cumulative; `> 0` means the index
+     *  HAS drifted at some point (see `DriftSummary.pending` for now). */
+    readonly dropped: number;
     /** The MOST RECENT reindex across all replicas (max of each replica's). */
     readonly lastReindexAt: string | null;
     /** Docs seeded by that most-recent reindex. */
     readonly lastReindexCount: number;
 }
 
+export declare const isSafeFieldName: (field: string) => boolean;
+
+export declare const makeSearchStatsBuffer: (options: SearchStatsBufferOptions) => SearchStatsBuffer;
+
 /** Meilisearch. Native: filters (range+negation), facets
  *  (`facets`→`facetDistribution`), highlighting (`attributesToHighlight`), typo
  *  tolerance (on by default; `fuzziness:0` disables), engine-param passthrough.
  *  DEGRADED: Meilisearch has no numeric edit-distance knob — a `fuzziness`
  *  number other than 0 falls back to its built-in typo tolerance (documented). */
-export declare const meilisearchBackend: (cfg: VendorConfig) => SearchBackend;
+export declare const meilisearchBackend: (cfg: VendorConfig, hooks?: BackendHooks) => SearchBackend;
+
+/**
+ * A backend that is BOTH per-process and non-durable, tagged so the plugin can
+ * recognise it however it arrived — as the `'memory'` string, as the
+ * zero-config default, or handed in through the `SearchBackend` slot.
+ *
+ * The tag exists because the boot refusal (`./memoryGuard`) would otherwise be
+ * decorative: `backend: memoryBackend()` is the same deployment as
+ * `backend: 'memory'` and must read the same to the guard.
+ */
+export declare interface MemoryBackend extends SearchBackend {
+    /** Discriminator read by `backendKindOf` — see `./memoryGuard`. */
+    readonly engineKind: 'memory';
+}
 
 /** In-process inverted-ish search: substring (or fuzzy) match over stringified
  *  doc values + structured filters. Computes facets + highlights ITSELF (it's
  *  the honest-degradation reference — every feature works, just not at scale).
  *  Not for scale — but correct + dependency-free, and the right default for
- *  dev/tests/single-process apps. */
-export declare const memoryBackend: () => SearchBackend;
+ *  dev/tests/single-process apps.
+ *
+ *  It holds every doc in THIS process's heap: a second replica has its own
+ *  copy, and a restart starts empty. `./memoryGuard` is what keeps that from
+ *  being a production surprise. */
+export declare const memoryBackend: () => MemoryBackend;
+
+export declare interface MemoryBackendAuditInput {
+    readonly backendKind: SearchBackendKind;
+    /** `NODE_ENV === 'production'`. */
+    readonly production: boolean;
+    /** The app asserted the single-process + re-seed contract — see
+     *  `SearchPluginOptions.singleProcessMemoryIndex`. */
+    readonly singleProcessDeclared: boolean;
+}
+
+/**
+ * `'quiet'` says nothing at all (the common, correct cases). `'note'` logs at
+ * info — the app declared the memory contract and we restate what it signed up
+ * for, once, at boot. `'refuse'` aborts the boot.
+ */
+export declare type MemoryBackendVerdict = {
+    readonly level: 'quiet';
+} | {
+    readonly level: 'note';
+    readonly message: string;
+} | {
+    readonly level: 'refuse';
+    readonly message: string;
+};
+
+/** In-process ledger. The default until `bindDataStore` swaps in the durable
+ *  one — it still makes drift OBSERVABLE (`/indexes` reports it) and still
+ *  self-heals in a running dev process; it just does not survive a restart. */
+export declare const memoryDriftLedger: () => DriftLedger;
 
 export declare const memoryStatsStore: () => StatsStore;
 
+/**
+ * The message logged when a peer replica actually announces itself while this
+ * process is serving search from its own heap. Fires once per boot, in ANY
+ * environment — this is an observation, so it does not care what `NODE_ENV`
+ * says.
+ */
+export declare const peerObservedWarning: (peerInstanceId: string, singleProcessDeclared: boolean) => string;
+
+export declare type ResolvedSyncOptions = {
+    readonly [K in keyof typeof SYNC_DEFAULTS]: number;
+};
+
+export declare const resolveSyncOptions: (o: SearchSyncOptions | undefined) => ResolvedSyncOptions;
+
+/**
+ * The surviving keys, split by HOW they were allowed — the two halves merge on
+ * opposite sides of the adapter's own mapped params:
+ *
+ *   - `params` (built-in list) merges FIRST, so a wire caller can fill a gap
+ *     the adapter leaves but never overwrite something it mapped. That is the
+ *     hedge against the allowlist itself being wrong about a key.
+ *   - `appAllowed` (this app's `allowedEngineParams`) merges LAST, because the
+ *     app owner widened it on purpose — usually to reach a key the adapter
+ *     defaults (Typesense `query_by: '*'`), which merging first would make a
+ *     silent no-op.
+ */
+export declare interface SanitizedEngineParams {
+    readonly params: Record<string, unknown>;
+    readonly appAllowed: Record<string, unknown>;
+    /** The keys that survived neither, in input order. Never silent: the caller
+     *  asked for something the server refused, and that changes the answer. */
+    readonly dropped: ReadonlyArray<string>;
+}
+
+export declare const sanitizeEngineParams: (engine: SearchEngine, params: Record<string, unknown> | undefined, extraAllowed: ReadonlyArray<string> | undefined) => SanitizedEngineParams;
+
 /**
  * Compute the backend filters for a query, FAIL-CLOSED on tenant scoping.
  * Returns `null` when the caller must see NOTHING: a tenant-scoped index
@@ -91,6 +307,8 @@ export declare const memoryStatsStore: () => StatsStore;
  */
 export declare const scopeSearchFilters: (tenantField: string | undefined, tenantId: string | null, filters: ReadonlyArray<SearchFilter> | undefined) => ReadonlyArray<SearchFilter> | null;
 
+export declare const SEARCH_DRIFT_TABLE = "_voltro_search_drift";
+
 export declare const SEARCH_STATS_TABLE = "_voltro_search_stats";
 
 export declare interface SearchBackend {
@@ -119,11 +337,65 @@ declare const SearchBackendError_base: new <A extends Record<string, any> = {}>(
     readonly _tag: "SearchBackendError";
 } & Readonly<A>;
 
+/**
+ * How the resolved backend answers queries — not which vendor it is.
+ *
+ * `'custom'` is an app-supplied `SearchBackend` the framework knows nothing
+ * about; the app owns its durability. `memoryBackend()` is NOT custom however
+ * it was passed (it carries `engineKind: 'memory'`), because it is the same
+ * deployment either way.
+ */
+export declare type SearchBackendKind = 'memory' | 'vendor' | 'custom';
+
+/** Thrown from `onActivate` to abort the boot. */
+export declare class SearchBackendNotDurable extends Error {
+    readonly _tag = "SearchBackendNotDurable";
+    constructor(message: string);
+}
+
 export declare interface SearchDoc {
     readonly id: string;
     readonly [field: string]: unknown;
 }
 
+/**
+ * `_voltro_search_drift` — one row per (indexName, rowId) that is known to be
+ * missing from / stale in the index. UNIQUE over the pair so every replica's
+ * `insertIgnore` is idempotent and a repeatedly-failing row stays ONE entry.
+ *
+ * A `_voltro_*` table needs an explicit `id({ prefix })` (a typeid prefix
+ * cannot be derived from a name starting with `_`), and needs no codemod: the
+ * declarative differ reconciles it on `voltro db apply` and on a `voltro dev`
+ * boot, on every dialect.
+ */
+export declare const searchDriftTable: DriftTable;
+
+export declare type SearchEngine = 'typesense' | 'meilisearch' | 'algolia';
+
+/**
+ * A field name the caller supplied — in `filters[].field`, `facets[]` or
+ * `highlight.fields[]` — was refused before it could reach the engine.
+ *
+ * `reason: 'not-an-identifier'` — the name is not a plain field path
+ * (`^[A-Za-z_][A-Za-z0-9_.]*$`). Every vendor adapter interpolates the name
+ * into that engine's filter DSL, so anything else is a control-plane injection
+ * (a Typesense `filter_by` is ONE flat string with `||`, so a crafted name
+ * re-groups the boolean tree around the appended tenant clause).
+ *
+ * `reason: 'not-queryable'` — the name is well-formed but not in the index's
+ * declared `queryableFields` allowlist.
+ */
+export declare class SearchFieldRejected extends SearchFieldRejected_base {
+}
+
+declare const SearchFieldRejected_base: Schema.TaggedErrorClass<SearchFieldRejected, "SearchFieldRejected", {
+    readonly _tag: Schema.tag<"SearchFieldRejected">;
+} & {
+    field: typeof Schema.String;
+    where: Schema.Literal<["filter", "facet", "highlight"]>;
+    reason: Schema.Literal<["not-an-identifier", "not-queryable"]>;
+}>;
+
 export declare interface SearchFilter {
     readonly field: string;
     readonly op: SearchFilterOp;
@@ -147,13 +419,80 @@ export declare interface SearchHit {
     readonly highlights?: Record<string, string>;
 }
 
+/**
+ * The queried index is not one the app declared in `searchPlugin({ indexes })`.
+ *
+ * This is a REFUSAL, not an empty result, and the distinction is the whole
+ * point: an unknown index has no `IndexSpec`, therefore no `tenantField`,
+ * therefore no tenant clause — so answering it would run an unfiltered query
+ * against whatever collection of that name exists on the (usually shared)
+ * engine. Fail instead of querying something we cannot scope.
+ */
+export declare class SearchIndexNotFound extends SearchIndexNotFound_base {
+}
+
+declare const SearchIndexNotFound_base: Schema.TaggedErrorClass<SearchIndexNotFound, "SearchIndexNotFound", {
+    readonly _tag: Schema.tag<"SearchIndexNotFound">;
+} & {
+    index: typeof Schema.String;
+}>;
+
 export declare const searchPlugin: (options: SearchPluginOptions) => VoltroPlugin;
 
 export declare interface SearchPluginOptions {
     readonly backend?: SearchBackendConfig;
     /** Map of source table → index spec. */
     readonly indexes: Record<string, IndexSpec>;
+    /** Retry / drift-repair tunables — see {@link SearchSyncOptions}. */
+    readonly sync?: SearchSyncOptions;
+    /**
+     * Namespace for this plugin's rpc tags + inspect endpoints. Default `search`.
+     *
+     * Set it when your app already publishes under that name — an exact tag
+     * collision is fatal at codegen, and this is the way out. Orthogonal to
+     * `name` below: `alias` REPLACES the namespace, `name` distinguishes two
+     * installations within it.
+     *
+     * The cost, stated because nothing else states it: the local and cloud
+     * dashboards fetch this plugin's panel at the DEFAULT slug, so an aliased
+     * install keeps working while its dashboard panel 404s. Alias to escape a
+     * collision, not for taste.
+     */
+    readonly alias?: string;
+    /**
+     * Discriminator for a SECOND installation of this plugin, when one app runs
+     * two (`@voltro/plugin-search#analytics`). Not a rename — for that use
+     * `alias`.
+     */
     readonly name?: string;
+    /**
+     * Extra `engineParams` keys a wire caller may set, on top of the built-in
+     * per-engine allowlist of presentation-only keys (paging / ordering / typo
+     * tolerance / highlight shaping).
+     *
+     * This is the deliberate, server-side widening of the escape hatch — an app
+     * that needs, say, Typesense's `query_by` says so in `app.config.ts` rather
+     * than every caller getting it. Keys that select the DOCUMENT SET
+     * (`filter_by`, `filter`, `facetFilters`, `restrictSearchableAttributes`,
+     * `preset`, `pinned_hits`, …) stay refused even when listed here: they are
+     * the authority the injected tenant clause holds, and a filter belongs in the
+     * validated `filters[]` list, which is ANDed with that clause.
+     */
+    readonly allowedEngineParams?: ReadonlyArray<string>;
+    /**
+     * Assert that this deployment runs the in-memory backend the only way it can
+     * be correct outside dev: **exactly one process**, which **re-seeds every
+     * index at startup** (a `*.startup.tsx` calling `backfillIndex`).
+     *
+     * Without it, `NODE_ENV=production` + the memory backend REFUSES to boot —
+     * see `./memoryGuard` for why a single replica is not on its own enough (the
+     * heap-resident index is empty after every deploy).
+     *
+     * This is not a mute switch. It is a claim the plugin holds you to: if the
+     * membership registry reports a peer replica, the plugin logs that the claim
+     * has been contradicted, in any environment.
+     */
+    readonly singleProcessMemoryIndex?: boolean;
 }
 
 export declare interface SearchQuery {
@@ -170,9 +509,15 @@ export declare interface SearchQuery {
     readonly highlight?: HighlightSpec;
     /** Typo tolerance. Omit ⇒ the engine default (memory: exact substring). */
     readonly fuzziness?: Fuzziness;
-    /** Escape hatch: forwarded VERBATIM into the engine's search-params object,
-     *  shallow-merged AFTER the mapped params (so it can override them). Ignored
-     *  by the memory backend (nothing to forward to). */
+    /** Escape hatch, ALLOWLISTED per engine: keys on that engine's
+     *  presentation-only list (paging / ordering / typo / highlight — see
+     *  `sanitize.ts`) are shallow-merged BEFORE the mapped params, so they can
+     *  never out-vote the injected tenant filter; keys the APP widened to via
+     *  `BackendHooks.allowEngineParams` merge after (that widening is
+     *  server-side config, and its point is to reach a key the adapter
+     *  defaults). Every other key is dropped and reported through
+     *  `BackendHooks.onWarn`. Ignored by the memory backend (nothing to forward
+     *  to). */
     readonly engineParams?: Record<string, unknown>;
 }
 
@@ -183,33 +528,161 @@ export declare interface SearchResult {
     readonly facets: FacetCounts;
 }
 
+export declare interface SearchStatsBuffer {
+    /** Count one sync/remove/drop. Synchronous, no I/O. */
+    readonly bump: (index: string, kind: StatsKind, scope: StatsScope) => void;
+    /** Write everything pending now. */
+    readonly flushNow: () => Promise<void>;
+    /** Flush the tail and stop the timer. Idempotent. */
+    readonly shutdown: () => Promise<void>;
+    /** Buffered bump count — for tests and the truthfulness flush in `/indexes`. */
+    readonly pending: () => number;
+}
+
+export declare interface SearchStatsBufferOptions {
+    /** Apply one index's accumulated window. Must ADD the deltas — never assign. */
+    readonly flush: (index: string, delta: StatsDelta, scope: StatsScope) => Promise<void>;
+    /** Flush cadence (ms). Tunable via `searchPlugin({ sync: { statsFlushIntervalMs } })`. */
+    readonly intervalMs: number;
+    /** Flush early once this many bumps are buffered ACROSS all indexes, so a
+     *  burst doesn't sit a whole window away from durability. Tunable via
+     *  `sync.statsFlushMaxBuffered`. */
+    readonly maxBuffered: number;
+}
+
 /** `_voltro_search_stats` — one row per (indexName, replicaId). UNIQUE over the
  *  pair so each replica's create-path `insertIgnore` is idempotent and the CAS
  *  increment targets exactly its own row (no cross-replica contention). */
 export declare const searchStatsTable: StatsTable;
 
+/**
+ * Durability knobs for the change→index sync. Every number the plugin would
+ * otherwise pick on your behalf lives here, with a default.
+ *
+ * The retry only fires for a failure the backend marked `transient` (network /
+ * engine unavailable / 5xx / rate-limited). A permanent failure — an
+ * unsupported query shape, a `map(row)` that throws on this row — is NOT
+ * retried: repeating it costs latency and changes nothing. Both kinds end in
+ * the drift ledger, which is what makes the distinction safe to draw.
+ */
+export declare interface SearchSyncOptions {
+    /** Retries AFTER the first attempt, for a `transient` failure. Default 5
+     *  (≈ 200 ms → 3.2 s of backoff before giving up). `0` disables retry. */
+    readonly retries?: number;
+    /** First backoff delay; doubles per attempt. Default 200 ms. */
+    readonly retryBaseDelayMs?: number;
+    /** Backoff ceiling — no single wait exceeds this. Default 10_000 ms. */
+    readonly retryMaxDelayMs?: number;
+    /**
+     * How often the cluster-coordinated sweep repairs drift-ledger entries.
+     * Default 60_000 ms. `0` turns the automatic sweep off entirely, leaving the
+     * `POST /resync` inspect endpoint as the (manual) repair path — the ledger
+     * still records, so nothing is lost, it just waits for an operator.
+     */
+    readonly resyncIntervalMs?: number;
+    /** Max ledger entries repaired per sweep. Default 200. */
+    readonly resyncBatchSize?: number;
+    /**
+     * Rows per page for the `/reindex` backfill. The endpoint STREAMS the table
+     * (keyset-paginated `streamTable`) and upserts one page at a time, so memory
+     * is bounded by this number regardless of table size — it never loads the
+     * whole table. Default 1000.
+     */
+    readonly reindexBatchSize?: number;
+    /**
+     * How often buffered sync-stat counters are flushed to
+     * `_voltro_search_stats` (ms). Counting is in-memory per event; the
+     * read+CAS against the OLTP primary happens once per window per index
+     * instead of once per write. Default 5000. `0` disables buffering — every
+     * event pays the per-write CAS again (the pre-buffer behaviour).
+     *
+     * The trade, stated plainly: a CRASH loses the current window (up to this
+     * many ms of counts). A graceful shutdown loses nothing — the plugin's
+     * deactivate flushes the tail. Counters, not billing inputs.
+     */
+    readonly statsFlushIntervalMs?: number;
+    /** Flush the stats buffer early once this many bumps are pending across all
+     *  indexes, so a burst is never a whole window away from durability.
+     *  Default 1000. */
+    readonly statsFlushMaxBuffered?: number;
+}
+
 /** All tables for `extendSchema.tables`. */
 export declare const searchTables: () => ReadonlyArray<StatsTable>;
 
+/** One flushed window of buffered counts — what `StatsStore.add` applies in a
+ *  single CAS round instead of one round-trip per event. */
+export declare interface StatsDelta {
+    readonly synced: number;
+    readonly removed: number;
+    readonly dropped: number;
+}
+
+/** What a bump counts. `dropped` is the drift counter — the one an operator
+ *  must be able to see WITHOUT reading logs. */
+export declare type StatsKind = 'synced' | 'removed' | 'dropped';
+
+/** The store's change visibility, as `PluginChangeEvent.changeScope` reports
+ *  it — it decides SUM vs MAX on read (see the header). */
+export declare type StatsScope = 'local' | 'fleet';
+
 /** The stats store. All ops key on the index name; the durable impl fans out to
  *  per-replica rows internally and aggregates on read. */
 export declare interface StatsStore {
-    /** +1 synced (an insert/update mirrored) or +1 removed (a delete). */
-    readonly bump: (index: string, kind: 'synced' | 'removed') => Promise<void>;
-    /** Record a reindex: +count synced AND set lastReindex{At,Count}. */
+    /** +1 synced (an insert/update mirrored), +1 removed (a delete), or +1
+     *  dropped (retries exhausted → drift). `scope` is the event's changeScope;
+     *  it decides how this replica's row aggregates with its peers'. */
+    readonly bump: (index: string, kind: StatsKind, scope: StatsScope) => Promise<void>;
+    /** Apply one buffered window's deltas — ADDS each counter (never assigns),
+     *  in ONE CAS round. This is what the in-memory stats buffer flushes through:
+     *  N indexed-table writes cost one read+CAS per flush window instead of one
+     *  per write against the OLTP primary. */
+    readonly add: (index: string, delta: StatsDelta, scope: StatsScope) => Promise<void>;
+    /** Record a reindex: +count synced AND set lastReindex{At,Count}. Takes no
+     *  scope — a reindex is one deliberate act on one replica, and stamping the
+     *  row's `scope` from it would overwrite what the change STREAM reported. */
     readonly recordReindex: (index: string, count: number, at: string) => Promise<void>;
-    /** Aggregated stats for one index (summed across replicas). */
+    /** Aggregated stats for one index (summed or maxed across replicas — see the
+     *  file header). */
     readonly get: (index: string) => Promise<IndexStats>;
 }
 
+/** Adapt a (live-rebindable) StatsStore into the buffer's flush fn. Reads the
+ *  store through the getter at FLUSH time, so the memory→durable swap
+ *  `bindDataStore` performs is honoured by windows buffered before it ran. */
+export declare const statsStoreFlush: (store: () => StatsStore) => SearchStatsBufferOptions["flush"];
+
 declare interface StatsTable extends TableLike {
     readonly fields: Record<string, ColumnDefinition<unknown>>;
     readonly appliedIndexes: ReadonlyArray<TableIndex>;
 }
 
+/** Defaults for every {@link SearchSyncOptions} knob, in ONE place — the
+ *  `/indexes` panel reports the policy actually in force from here, so a
+ *  default can never be a number only the source knows. */
+export declare const SYNC_DEFAULTS: {
+    readonly retries: 5;
+    readonly retryBaseDelayMs: 200;
+    readonly retryMaxDelayMs: 10000;
+    readonly resyncIntervalMs: 60000;
+    readonly resyncBatchSize: 200;
+    readonly reindexBatchSize: 1000;
+    readonly statsFlushIntervalMs: 5000;
+    readonly statsFlushMaxBuffered: 1000;
+};
+
+/**
+ * Bounded, capped exponential backoff — and the first READER of
+ * `SearchBackendError.transient`, which every vendor adapter has been setting
+ * into the void. `whileInput` exits the retry the moment the failure is
+ * permanent; `intersect(recurs)` bounds the attempts; `either(spaced)` caps a
+ * single wait at `retryMaxDelayMs`.
+ */
+export declare const syncRetrySchedule: (o: ResolvedSyncOptions) => Schedule.Schedule<unknown, SearchBackendError>;
+
 /** Typesense (self-host / cloud). Native: filters (range+negation), facets,
  *  highlighting, typo tolerance (`num_typos`), engine-param passthrough. */
-export declare const typesenseBackend: (cfg: VendorConfig) => SearchBackend;
+export declare const typesenseBackend: (cfg: VendorConfig, hooks?: BackendHooks) => SearchBackend;
 
 export declare interface VendorConfig {
     readonly url?: string;