@taladb/react 0.10.1 → 0.11.0

package/dist/query/index.d.mts

@@ -0,0 +1,1664 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { Filter, Document, Value, Collection, TalaDB } from 'taladb';
+
+/**
+ * Request parameters, declared once and used three times.
+ *
+ * An application already has `?category=book&page=1&sort=-createdAt`. Restating
+ * `category` a second time as an engine predicate is duplication that drifts, so
+ * one declaration feeds the query key, the request, and the local filter.
+ *
+ * **Nothing is inferred.** The obvious convention — "a param whose name matches
+ * a document field is a predicate, anything else is pagination" — has to be
+ * rejected, because there is no reliable way to know a collection's field names:
+ * schemas are Standard Schema values with no portable key enumeration, and
+ * sampling documents fails exactly when it matters most, on a cold empty
+ * collection. Guessing wrong there is silent: `page: 1` treated as a predicate
+ * matches nothing and renders an empty screen with `status: 'success'`.
+ *
+ * So an undeclared param contributes no local predicate. It still reaches the
+ * key and the request; it simply does not narrow the local read. The local
+ * filter is then *broader* than the server's, never narrower — and being
+ * broader costs nothing, because the query's stored id list still bounds the
+ * result.
+ */
+type ParamOp = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$contains';
+type ParamPrimitive = string | number | boolean;
+type ParamValue = ParamPrimitive | ParamPrimitive[] | null | undefined;
+/**
+ * What one request parameter means.
+ *
+ * `TValue` is carried only for inference, so `defineParams` can type its own
+ * call signature from the declaration.
+ */
+interface ParamSpec<TValue = ParamValue> {
+    readonly kind: 'predicate' | 'shape';
+    readonly field?: string;
+    readonly op?: ParamOp;
+    /** Phantom. Never read at runtime. */
+    readonly __value?: TValue;
+}
+/** `?status=open` → `{ status: 'open' }` */
+declare const eq: (field: string) => ParamSpec<ParamPrimitive>;
+/** `?exclude=archived` → `{ status: { $ne: 'archived' } }` */
+declare const ne: (field: string) => ParamSpec<ParamPrimitive>;
+/** `?minPrice=10` → `{ price: { $gte: 10 } }` */
+declare const gte: (field: string) => ParamSpec<number | string>;
+/** `?maxPrice=99` → `{ price: { $lte: 99 } }` */
+declare const lte: (field: string) => ParamSpec<number | string>;
+/** `?after=2026-01-01` → `{ createdAt: { $gt: … } }` */
+declare const gt: (field: string) => ParamSpec<number | string>;
+/** `?before=2026-01-01` → `{ createdAt: { $lt: … } }` */
+declare const lt: (field: string) => ParamSpec<number | string>;
+/** `?search=dune` → `{ title: { $contains: 'dune' } }` */
+declare const contains: (field: string) => ParamSpec<string>;
+/** `?tags=a,b` → `{ tags: { $in: ['a', 'b'] } }` */
+declare const oneOf: (field: string) => ParamSpec<ParamPrimitive[]>;
+/**
+ * A parameter that shapes the *response* rather than selecting documents —
+ * `page`, `perPage`, `sort`, `cursor`.
+ *
+ * These have no local meaning at all: the stored id list already *is* the slice,
+ * in the server's order. Declaring them explicitly is what turns a typo'd param
+ * name into something visible rather than a param that quietly stops filtering.
+ */
+declare const shape: () => ParamSpec<ParamPrimitive>;
+/** A parameter set with its values bound, ready for a request and a query. */
+interface BoundParams<TValues = Record<string, ParamValue>> {
+    /** The values as given. */
+    readonly values: TValues;
+    /**
+     * The request half. Empty and `null` values are dropped; arrays are
+     * comma-joined; booleans become `true`/`false`.
+     */
+    toSearchParams(): URLSearchParams;
+    /**
+     * The collection half — `undefined` when no declared parameter is set, which
+     * is the case for a plain object.
+     */
+    toFilter(): Filter<Document> | undefined;
+    /** Declared parameters of kind `shape` that currently have a value. */
+    shapeParams(): string[];
+}
+/** The value type a declaration accepts. Every parameter is optional. */
+type ValuesOf<S> = {
+    [K in keyof S]?: S[K] extends ParamSpec<infer V> ? V : never;
+};
+/**
+ * Declare a parameter set.
+ *
+ * Returns a function that binds values to it. The value type is inferred from
+ * the declaration, so a typo is a compile error rather than a parameter that
+ * silently stops filtering — protection a stringly-typed `?category=` never
+ * gives you.
+ */
+declare function defineParams<S extends Record<string, ParamSpec<never>>>(spec: S): (values: ValuesOf<S>) => BoundParams<ValuesOf<S>>;
+/** True for anything already bound — a declaration's output, not a plain object. */
+declare function isBoundParams(value: unknown): value is BoundParams;
+/**
+ * Accept either form.
+ *
+ * A plain object gets the request half and no local predicates — which is the
+ * safe default, and the reason upgrading to `defineParams` is additive rather
+ * than a rewrite.
+ */
+declare function normalizeParams(params: BoundParams | Record<string, ParamValue> | undefined): BoundParams | undefined;
+
+/** Where a document sits relative to the server. Indexed — this *is* the queue. */
+type SyncState = 'synced' | 'pending' | 'failed';
+/** What a pending document still owes the server. */
+type SyncOp = 'insert' | 'update' | 'delete';
+/**
+ * Fields this layer adds to every document it manages, alongside the engine's
+ * own `_id`, `_changed_at` and `_v`.
+ *
+ * They live *on the document* rather than in a separate outbox collection
+ * because TalaDB exposes no multi-collection transaction: a document write and
+ * an outbox row describing it would be two commits, and a crash between them
+ * either orphans a queued mutation or strands a document that never syncs.
+ * Keeping the state here makes every queued write a single atomic commit.
+ *
+ * All `_`-prefixed names are reserved. A user schema that declares one will be
+ * rejected rather than silently overwritten.
+ */
+interface SyncEnvelope {
+    /** Drain state. Indexed. */
+    _sync: SyncState;
+    /** Meaningful only while `_sync !== 'synced'`. */
+    _op?: SyncOp;
+    /** Retry count, drives backoff. */
+    _attempt: number;
+    /** Last terminal error, surfaced by `useSyncStatus`. */
+    _error: string | null;
+    /**
+     * Epoch ms of the last server hydration, or `0` for a document that only
+     * exists locally so far.
+     *
+     * There is deliberately no `_expires_at` companion. Freshness belongs to a
+     * *query*, not a document — see {@link QueryRecord} — and nothing here
+     * expires by deletion: these documents live in the application's own
+     * collections, which it also reads directly, so a TTL sweep would delete real
+     * user data rather than reclaim a cache.
+     */
+    _fetched_at: number;
+    /**
+     * Epoch ms before which the drain will not retry this document. `0` means
+     * eligible now; the drain pushes it forward as it backs off.
+     */
+    _retry_at: number;
+    /**
+     * Where this write is going, as a URL template — `/api/v2/todos/:id`.
+     *
+     * Stamped when the write is queued, because a queued write outlives the
+     * component that made it: the drain may send it after a route change, a
+     * reload, or a week later, when no closure survives to ask. A template is
+     * data and can be stored; a function cannot.
+     *
+     * Absent falls back to the provider's backend.
+     */
+    _endpoint?: string;
+    /** HTTP verb for the current `_op`, recomputed whenever `_op` changes. */
+    _method?: string;
+    /** Opaque local revision used to detect edits while a request is in flight. */
+    _revision: string | null;
+}
+/**
+ * One record per query shape, in the `taladb_queries` collection.
+ *
+ * Separate from the documents on purpose. A collection name says *where
+ * documents live*; a query key says *what went stale*. Collapse the two and TTL
+ * becomes meaningless — a document belongs to many queries with different
+ * freshness — and result-set membership becomes unrecoverable.
+ */
+interface QueryRecord extends Document {
+    /** `deriveDocId(QUERY_COLLECTION, collection + key)` — deterministic. */
+    _id: string;
+    /** The collection whose documents this query returned. */
+    collection: string;
+    /** The serialised query key, for debugging and inspection. */
+    key: string;
+    /** Result-set membership, in server order. */
+    ids: string[];
+    fetchedAt: number;
+    /** Freshness window in ms. `0` means "always revalidate". */
+    ttl: number;
+    /**
+     * What `queryFn` returned, so a warm mount can rebuild the same shape without
+     * fetching. A detail view whose response was one document must not come back
+     * as a one-element array after a reload.
+     */
+    shape?: ResultShape;
+    /**
+     * The raw response, for envelope queries only.
+     *
+     * Stored so `assemble` has its non-document half — `total`, `nextCursor` —
+     * available on a warm mount. Written only when `assemble` is supplied, since
+     * nothing else ever reads it and the response duplicates every document it
+     * carries.
+     */
+    payload?: Value;
+}
+/**
+ * How a request came out, from the drain loop's point of view.
+ *
+ * `applied` is the one people forget. A write that timed out and was retried
+ * will often come back 409 — already applied. Without a way to say so, every
+ * retried write poisons the queue permanently.
+ */
+type WriteOutcome = 'ok' | 'applied' | 'retry' | 'terminal';
+/** One queued write, as handed to the backend adapter. */
+interface PendingWrite {
+    collection: string;
+    /** The client-generated ULID. Authoritative — the server must not reassign it. */
+    id: string;
+    type: SyncOp;
+    /** The stored document after the local commit; `null` for a delete. */
+    document: Record<string, unknown> | null;
+}
+/**
+ * The application's backend, described well enough for the drain loop to talk
+ * to it. This is the only extension point: the library never guesses at URL
+ * shapes or status codes.
+ */
+interface BackendDefinition {
+    /** Where this write goes. */
+    url: (op: PendingWrite) => string;
+    /** Defaults to POST / PUT / DELETE for insert / update / delete. */
+    method?: Partial<Record<SyncOp, string>>;
+    /** Resolved per request, so a write queued offline sends a current token. */
+    headers?: () => HeadersInit | Promise<HeadersInit>;
+    /** Map a response onto the four outcomes. */
+    classify: (response: Response, op: PendingWrite) => WriteOutcome;
+    /** Override the fetch implementation (tests, instrumentation). */
+    fetch?: typeof globalThis.fetch;
+}
+/** A `BackendDefinition` with defaults filled in. */
+interface ResolvedBackend extends BackendDefinition {
+    method: Record<SyncOp, string>;
+}
+/**
+ * When the queue drains. Separate from the mutation call site on purpose: the
+ * call site expresses *intent*, the provider expresses *timing*. "Write now,
+ * sync later on a schedule" is this knob, not a third mutation mode.
+ */
+type DrainPolicy = 'auto' | 'interval' | 'online-only' | 'manual';
+interface DrainOptions {
+    /**
+     * `auto` (default) sends an `optimistic` write as soon as it commits.
+     * `interval` waits for its timer. `online-only` sends while online and resumes
+     * on the browser's `online` event. `manual` never drains on its own.
+     *
+     * A `queued` mutation ignores `auto` and waits for a trigger either way.
+     */
+    policy?: DrainPolicy;
+    /** For `'interval'`. */
+    intervalMs?: number;
+    /** Documents per drain cycle. */
+    batch?: number;
+    /**
+     * Flush once this many writes have queued since the last cycle, whatever the
+     * policy says. Default `100`; `false` disables it.
+     *
+     * The timer is the fallback, not the mechanism. Under a long `interval` a
+     * burst would otherwise sit unsent for the whole window, and the queue would
+     * grow without bound between ticks.
+     */
+    flushAt?: number | false;
+    /**
+     * Flush when the tab is hidden or closing. Default `true`.
+     *
+     * This is the moment a queue most needs draining and the one the timer is
+     * least likely to be about to cover. `visibilitychange` does the real work —
+     * the page is still alive, so requests complete normally. `pagehide` is a
+     * last-ditch attempt sent with `keepalive`, which browsers cap at 64 KB
+     * across all in-flight requests, so it is best-effort by construction and the
+     * queue stays correct without it.
+     */
+    flushOnHide?: boolean;
+}
+/**
+ * Identifies a query *shape*, not a storage location.
+ *
+ * A collection name says where documents live; a key says what went stale.
+ * Collapsing the two makes TTL meaningless and server-side removals invisible,
+ * so they stay separate: documents land in `collection`, freshness is tracked
+ * per `key`.
+ */
+type QueryKey = readonly unknown[];
+/**
+ * The constraint on a user's model type.
+ *
+ * Deliberately **not** `Document`. `Document` carries an index signature, and
+ * TypeScript does not give interfaces implicit index signatures, so an ordinary
+ * application model —
+ *
+ * ```ts
+ * interface Todo { _id: string; title: string }
+ * ```
+ *
+ * — fails `T extends Document` outright. Requiring every model in a migrating
+ * codebase to be restated as a type alias or to `extends Document` is a far
+ * larger diff than the import line this surface exists to keep small. The
+ * narrowing to `Document` happens internally, at the collection boundary, where
+ * the registered schema validates at runtime anyway.
+ */
+type Doc = {
+    _id?: string;
+};
+/** `false` never, `true` when stale, `'always'` regardless of freshness. */
+type RefetchTrigger = boolean | 'always';
+/** `false` never, `true` forever, a number of attempts, or a per-failure decision. */
+type RetryOption = boolean | number | ((failureCount: number, error: Error) => boolean);
+/** A fixed delay, or one computed from the zero-based attempt index. */
+type RetryDelayOption = number | ((attemptIndex: number, error: Error) => number);
+/** How connectivity gates fetching. */
+type NetworkMode = 'online' | 'always' | 'offlineFirst';
+/** What `queryFn` is handed. Mirrors TanStack's `QueryFunctionContext`. */
+interface QueryFunctionContext {
+    queryKey: QueryKey;
+    signal: AbortSignal;
+    meta?: Record<string, unknown>;
+    /**
+     * The bound request parameters, if `params` was given.
+     *
+     * Always in bound form, even when a plain object was passed, so
+     * `params.toSearchParams()` works either way. The library never builds a URL
+     * itself — it only reads the half of the declaration that concerns the
+     * collection.
+     */
+    params?: BoundParams;
+}
+/**
+ * Options shared by every `queryFn` shape.
+ *
+ * `TFetched` is what `queryFn` returns; `TData` is what `data` ends up as once
+ * `assemble` and `select` have run. They differ whenever a transform is in play.
+ */
+interface BaseQueryOptions<TFetched = unknown, TData = unknown> {
+    /**
+     * Where fetched documents are stored.
+     *
+     * Optional: defaults to `queryKey[0]` when that is a string, which is what
+     * makes a migrated `queryKey: ['todos', …]` need no edit. Inference is
+     * validated against the provider's collection registry rather than trusted —
+     * this option decides the *physical destination* of every fetched document,
+     * so a wrong value pours server data into a collection the app reads for
+     * something else.
+     */
+    collection?: string;
+    queryKey: QueryKey;
+    /**
+     * Freshness window in ms. Defaults to **one hour**, not TanStack's `0`.
+     *
+     * A memory cache that dies on reload is usually seconds old and revalidating
+     * it is nearly free; a cache that survives reload and is expected to work
+     * offline is neither. Pass `0` for TanStack's behaviour, or set it once on
+     * the provider.
+     */
+    staleTime?: number;
+    /**
+     * Default `true`. A function is re-evaluated on every render, which is how a
+     * dependent query waits for the value it needs.
+     *
+     * Note it takes no arguments, where TanStack passes the query — exposing our
+     * internals to make one signature match would be a poor trade.
+     */
+    enabled?: boolean | (() => boolean);
+    /** Opaque; passed through to `queryFn`. */
+    meta?: Record<string, unknown>;
+    /**
+     * Data to start from on a cold key, instead of fetching into a spinner.
+     *
+     * Unlike {@link BaseQueryOptions.placeholderData} this is **persisted**: the
+     * documents are hydrated into the collection and a query record is written,
+     * exactly as a fetch would. It is server data the app happened to already
+     * have — from SSR, a route loader, a bundled seed — not a stand-in for it.
+     */
+    initialData?: NoInfer<TFetched> | (() => NoInfer<TFetched>);
+    /**
+     * When {@link BaseQueryOptions.initialData} was last true, as epoch ms.
+     * Defaults to now.
+     *
+     * Feeds staleness, so seeded data can be born stale and revalidate straight
+     * away — which is usually what an SSR payload wants.
+     */
+    initialDataUpdatedAt?: number;
+    /**
+     * Data to show *instead of* a pending state, never written anywhere.
+     *
+     * `placeholderData: keepPreviousData` is the common case: hold the last page
+     * on screen while the next one loads rather than blanking the list. The
+     * result reports `isPlaceholderData: true` so the UI can dim it.
+     *
+     * This is in the *final* `data` space — after `assemble` and `select` — which
+     * is what lets `keepPreviousData` hand back the previous `data` untouched.
+     * TanStack places it before `select`; the difference shows only for a
+     * placeholder that is not the previous value.
+     */
+    placeholderData?: NoInfer<TData> | ((previous: NoInfer<TData> | undefined) => NoInfer<TData> | undefined);
+    /**
+     * How many times to retry a failed fetch. Default `3`.
+     *
+     * `false` disables retrying, `true` retries forever, a number caps the
+     * attempts, and a predicate decides per failure — which is how a 404 is kept
+     * from being retried four times.
+     */
+    retry?: RetryOption;
+    /** Milliseconds between attempts. Default is exponential from 1s, capped at 30s. */
+    retryDelay?: RetryDelayOption;
+    /**
+     * Revalidate on mount when the data is stale. Default `true`.
+     *
+     * `'always'` revalidates whatever `staleTime` says; `false` leaves a mounted
+     * query showing whatever the device has until something else asks.
+     */
+    refetchOnMount?: RefetchTrigger;
+    /** Revalidate when the window regains focus, if stale. Default `true`. */
+    refetchOnWindowFocus?: RefetchTrigger;
+    /** Revalidate when the network comes back, if stale. Default `true`. */
+    refetchOnReconnect?: RefetchTrigger;
+    /** Poll every N ms. Default `false`. A function is re-evaluated per render. */
+    refetchInterval?: number | false | (() => number | false);
+    /** Keep polling while the tab is hidden. Default `false`. */
+    refetchIntervalInBackground?: boolean;
+    /**
+     * What to do about fetching while offline. Default `'online'`.
+     *
+     * `'online'` reports `fetchStatus: 'paused'` instead of failing, and resumes
+     * on reconnect. `'always'` ignores connectivity — the right setting when
+     * `queryFn` talks to something local. `'offlineFirst'` attempts once, which
+     * suits a request that may be answered by a service worker.
+     */
+    networkMode?: NetworkMode;
+    /**
+     * How long to remember this query's result set after nothing is using it.
+     * Default `Infinity` — remember indefinitely.
+     *
+     * **Not garbage collection, and deliberately not called that.** Documents are
+     * never deleted: they live in your own collections, which the application
+     * also reads directly, so sweeping them would destroy real user data rather
+     * than reclaim a cache. What expires is the *record* of which documents this
+     * query returned — a few hundred bytes — after which the next mount is cold
+     * and refetches to re-establish membership.
+     *
+     * The default is `Infinity` because a query record is what makes a warm start
+     * warm, and a cache that survives reload has no memory pressure to relieve.
+     * Set it when a result set is genuinely disposable — a search whose terms
+     * will never be typed again.
+     */
+    forgetAfter?: number;
+    /**
+     * Rethrow a fetch error during render, for an error boundary to catch.
+     * Default `false`.
+     */
+    throwOnError?: boolean | ((error: Error) => boolean);
+    /**
+     * Serialise a query key into the string that identifies its record.
+     *
+     * The default sorts plain-object properties and preserves `undefined`, so
+     * `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` are one query rather than two.
+     * Replace it only if you need keys this cannot express — the result becomes
+     * part of the record's identity on disk.
+     */
+    queryKeyHashFn?: (queryKey: QueryKey) => string;
+    /**
+     * Request parameters — `?category=book&page=1`.
+     *
+     * Appended to `queryKey`, handed to `queryFn`, and (for parameters declared
+     * with `defineParams`) translated into a local filter. A plain object gets
+     * the first two; declaring the parameters adds the third.
+     */
+    params?: BoundParams | Record<string, ParamValue>;
+    /**
+     * What to answer with when the key is cold and the fetch fails.
+     *
+     * `'strict'` (default) keeps the guarantee that `data` is exactly what the
+     * server returned: no record, no answer. `'collection'` falls back to
+     * querying everything cached through the `params` filter and reports
+     * `fromCollection: true`, so the UI can say so rather than presenting a
+     * partial set as authoritative.
+     *
+     * Only meaningful with parameters declared via `defineParams` — there is
+     * otherwise no predicate to query the collection with.
+     */
+    offline?: 'strict' | 'collection';
+    /**
+     * Accepted and ignored — every result field is computed either way. Present
+     * so migrated code compiles; noted once in development.
+     */
+    notifyOnChangeProps?: readonly string[] | 'all' | (() => readonly string[] | 'all' | undefined);
+    /**
+     * Accepted and ignored — structural sharing is always on here. Present so
+     * migrated code compiles; noted once in development.
+     */
+    structuralSharing?: boolean | ((previous: unknown, next: unknown) => unknown);
+}
+/**
+ * `queryFn` returns a list of documents. The common case.
+ *
+ * `TData` is inferred from `select` when it is present, and is `T[]` otherwise.
+ */
+interface UseQueryOptions<T extends Doc, TData = T[]> extends BaseQueryOptions<T[], TData> {
+    /** Fetch the current server state for this key. Honour `signal`. */
+    queryFn: (context: QueryFunctionContext) => Promise<T[]>;
+    /**
+     * Transform what this component sees, without changing what is stored.
+     *
+     * Runs over the live documents on every render in which they change, and its
+     * output gets the same structural sharing they do — so an inline arrow here
+     * is safe, and `data` keeps a stable identity between equal results.
+     */
+    select?: (data: T[]) => TData;
+    /**
+     * Narrow this query's result set locally, in the engine.
+     *
+     * Composed with the query's stored id list as `$and`, so it filters *within*
+     * what the server returned rather than replacing it. Indexed, and live: a
+     * document edited out of the predicate leaves the view immediately, without
+     * waiting for a refetch.
+     *
+     * Deliberately **not** part of the query key. That is the whole point — one
+     * fetch, many narrowings, so All / Active / Done can be three components over
+     * a single request. Folding it into the key would give each its own record
+     * and its own fetch, which is worse than not having the option.
+     *
+     * It also never touches the stored record: the id list stays exactly what the
+     * server returned. Otherwise a refetch would fight the filter, and a
+     * locally-excluded document would be indistinguishable from one the server
+     * deleted.
+     */
+    where?: Filter<T & Document>;
+    documents?: never;
+    assemble?: never;
+}
+/**
+ * `queryFn` returns one document — a detail view.
+ *
+ * `data` is that document, not a one-element array, and becomes `undefined` if
+ * the document is deleted locally while the query is on screen. `select` is
+ * only called when there is a document, so it never has to handle the gap.
+ */
+interface UseDocumentQueryOptions<T extends Doc, TData = T> extends BaseQueryOptions<T, TData | undefined> {
+    queryFn: (context: QueryFunctionContext) => Promise<T>;
+    select?: (data: T) => TData;
+    /**
+     * Narrow this query's result set locally, in the engine.
+     *
+     * Composed with the query's stored id list as `$and`, so it filters *within*
+     * what the server returned rather than replacing it. Indexed, and live: a
+     * document edited out of the predicate leaves the view immediately, without
+     * waiting for a refetch.
+     *
+     * Deliberately **not** part of the query key. That is the whole point — one
+     * fetch, many narrowings, so All / Active / Done can be three components over
+     * a single request. Folding it into the key would give each its own record
+     * and its own fetch, which is worse than not having the option.
+     *
+     * It also never touches the stored record: the id list stays exactly what the
+     * server returned. Otherwise a refetch would fight the filter, and a
+     * locally-excluded document would be indistinguishable from one the server
+     * deleted.
+     */
+    where?: Filter<T & Document>;
+    documents?: never;
+    assemble?: never;
+}
+/**
+ * `queryFn` returns an envelope — `{ items, total, nextCursor }` and the like.
+ *
+ * This is the one shape no rename can absorb: `data` is rebuilt from the local
+ * collection, so the response has to say which part of itself is documents.
+ * `documents` extracts them; `assemble` puts the result back together, and is
+ * what keeps liveness — `data.items` re-renders on a local write while
+ * `data.total` stays whatever the server said.
+ */
+interface UseEnvelopeQueryOptions<TRaw, TDoc extends Doc, TAssembled = TDoc[], TData = TAssembled> extends BaseQueryOptions<TRaw, TData> {
+    queryFn: (context: QueryFunctionContext) => Promise<TRaw>;
+    documents: (raw: TRaw) => TDoc[];
+    /** Defaults to returning the documents alone. */
+    assemble?: (documents: TDoc[], raw: TRaw) => TAssembled;
+    /**
+     * Narrow this query's result set locally, in the engine.
+     *
+     * Composed with the query's stored id list as `$and`, so it filters *within*
+     * what the server returned rather than replacing it. Indexed, and live: a
+     * document edited out of the predicate leaves the view immediately, without
+     * waiting for a refetch.
+     *
+     * Deliberately **not** part of the query key. That is the whole point — one
+     * fetch, many narrowings, so All / Active / Done can be three components over
+     * a single request. Folding it into the key would give each its own record
+     * and its own fetch, which is worse than not having the option.
+     *
+     * It also never touches the stored record: the id list stays exactly what the
+     * server returned. Otherwise a refetch would fight the filter, and a
+     * locally-excluded document would be indistinguishable from one the server
+     * deleted.
+     */
+    where?: Filter<TDoc & Document>;
+    select?: (data: TAssembled) => TData;
+}
+/**
+ * Provider-wide defaults, in TanStack's `new QueryClient({ defaultOptions })`
+ * shape so that config migrates as a copy-paste.
+ *
+ * This is also where `staleTime: 0` goes to restore TanStack's revalidate-on-
+ * every-mount behaviour in one line, and where a test harness sets
+ * `retry: false` so failing requests fail immediately.
+ */
+interface QueryDefaults {
+    queries?: Pick<BaseQueryOptions, 'staleTime' | 'retry' | 'retryDelay' | 'refetchOnMount' | 'refetchOnWindowFocus' | 'refetchOnReconnect' | 'refetchInterval' | 'refetchIntervalInBackground' | 'networkMode' | 'forgetAfter' | 'throwOnError'>;
+}
+/** Any of the three forms, as the implementation sees them. */
+type AnyQueryOptions = BaseQueryOptions<unknown, unknown> & {
+    queryFn: (context: QueryFunctionContext) => Promise<unknown>;
+    documents?: (raw: never) => Doc[];
+    assemble?: (documents: never, raw: never) => unknown;
+    select?: (data: never) => unknown;
+    where?: Filter<Document>;
+};
+/** How a `queryFn`'s return value maps onto documents. Stored on the record. */
+type ResultShape = 'array' | 'document' | 'envelope';
+/** Fields present on a query result whatever its status. */
+interface QueryResultCommon<TData> {
+    /** `'fetching'` while a request is in flight, `'paused'` when offline. */
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+    /** `isPending && isFetching` — a first load with nothing to show yet. */
+    isLoading: boolean;
+    isFetching: boolean;
+    isPaused: boolean;
+    /** Fetching over data that is already on screen. */
+    isRefetching: boolean;
+    /**
+     * Past `staleTime`.
+     *
+     * Note this is *not* "currently revalidating" — that is `isFetching`. The two
+     * were one flag before parity work and the meanings are opposite.
+     */
+    isStale: boolean;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isPlaceholderData: boolean;
+    /**
+     * `data` was answered from the whole collection rather than from this
+     * query's stored result set — see `offline: 'collection'`. Always `false`
+     * under the default `'strict'`.
+     */
+    fromCollection: boolean;
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    refetch: (options?: {
+        /** Reject rather than recording the failure on the result. */
+        throwOnError?: boolean;
+        /**
+         * Default `true`: abandon any request already on its way and start again.
+         * `false` joins the in-flight request instead.
+         */
+        cancelRefetch?: boolean;
+    }) => Promise<QueryResult<TData>>;
+}
+/**
+ * The result of `useQuery`.
+ *
+ * A discriminated union rather than one object with `data: T[] | undefined`,
+ * because the canonical React Query component shape depends on narrowing:
+ *
+ * ```tsx
+ * if (isPending) return <Spinner/>
+ * if (isError) return <p>{error.message}</p>
+ * return <ul>{data.map(…)}</ul>   // `data` is T[] here, with no `!` or `?.`
+ * ```
+ *
+ * `data` is resolved through the local database rather than from the fetch
+ * response, so a local write to any document in the set re-renders this query
+ * immediately — there is no cache to invalidate, because the collection *is*
+ * the state.
+ */
+type QueryResult<TData> = (QueryResultCommon<TData> & {
+    status: 'pending';
+    /** Undefined, never `[]` — an empty array would render as an empty list. */
+    data: undefined;
+    error: null;
+    isPending: true;
+    isSuccess: false;
+    isError: false;
+    isLoadingError: false;
+    isRefetchError: false;
+}) | (QueryResultCommon<TData> & {
+    status: 'success';
+    data: TData;
+    error: null;
+    isPending: false;
+    isSuccess: true;
+    isError: false;
+    isLoadingError: false;
+    isRefetchError: false;
+}) | (QueryResultCommon<TData> & {
+    status: 'error';
+    /** Nothing was cached, so the failure left nothing to render. */
+    data: undefined;
+    error: Error;
+    isPending: false;
+    isSuccess: false;
+    isError: true;
+    isLoadingError: true;
+    isRefetchError: false;
+}) | (QueryResultCommon<TData> & {
+    status: 'error';
+    /**
+     * A *refetch* failed over data the device already holds. Clearing the
+     * screen here would undo the point of a persistent cache.
+     */
+    data: TData;
+    error: Error;
+    isPending: false;
+    isSuccess: false;
+    isError: true;
+    isLoadingError: false;
+    isRefetchError: true;
+});
+/**
+ * When the network happens, relative to the local write.
+ *
+ * - `optimistic` (default) — commit locally, return, and send in the
+ *   background as soon as possible. `pending` stays false: the UI never waits.
+ * - `immediate` — send first and write locally only once the server agrees.
+ *   `pending` reflects the request. For writes the user would be misled by if
+ *   they silently failed: checkout, payment, anything irreversible.
+ * - `queued` — commit locally and wait for the provider's schedule rather than
+ *   sending straight away. For high-volume writes worth batching.
+ */
+type MutationMode = 'optimistic' | 'immediate' | 'queued';
+/** Which write a mutation performs. Declared once, not passed per call. */
+type MutationOperation = 'insert' | 'update' | 'delete';
+/**
+ * What `mutate` takes, per operation.
+ *
+ * These differ, and defaulting all three to `T` would be wrong in two of them:
+ * an insert has no `_id` yet (it is minted client-side), and an update carries
+ * only the fields being changed. Getting this wrong shows up as a compile error
+ * on every call site, which is how it was found.
+ */
+type InsertVariables<T extends Doc> = Omit<T, '_id'> & {
+    _id?: string;
+};
+type UpdateVariables<T extends Doc> = {
+    _id: string;
+} & Partial<Omit<T, '_id'>>;
+type DeleteVariables = {
+    _id: string;
+};
+/** Passed between a mutation's callbacks, as TanStack's `context` is. */
+type MutationContext = unknown;
+interface MutationCallbacks<T extends Doc, TVariables, TContext = MutationContext> {
+    /**
+     * Runs before the write. Its return value becomes `context` for the
+     * callbacks below.
+     *
+     * In TanStack this is where an optimistic update is applied by hand and a
+     * rollback snapshot returned. Neither is needed here — the optimism *is* the
+     * database, and every query over these documents re-renders on the local
+     * commit — so this is a plain hook point for logging and deriving context.
+     */
+    onMutate?: (variables: TVariables) => TContext | Promise<TContext>;
+    /**
+     * The write succeeded.
+     *
+     * Under `optimistic` and `queued` that means the **local commit**: the write
+     * is durable and the UI has already updated, but nothing has reached the
+     * server. Under `immediate` it means the server agreed.
+     *
+     * Waiting for the server in every mode would be more faithful to TanStack and
+     * much worse in practice — the drain often lands after this component is
+     * gone, so the callback would silently never fire. Use `onSynced` for server
+     * confirmation, and `useSyncStatus` for anything that must survive
+     * navigation.
+     */
+    onSuccess?: (data: T, variables: TVariables, context: TContext) => unknown;
+    onError?: (error: Error, variables: TVariables, context: TContext | undefined) => unknown;
+    onSettled?: (data: T | undefined, error: Error | null, variables: TVariables, context: TContext | undefined) => unknown;
+    /**
+     * The **server** has confirmed this write.
+     *
+     * Best-effort by nature: under `optimistic` and `queued` the drain may land
+     * after this component has gone, in another tab, or on a later run of the
+     * app, and then nothing here fires. Anything that must not be missed — a
+     * failed write needing a human decision — belongs in `useSyncStatus`, which
+     * survives navigation.
+     *
+     * Under `immediate` it fires immediately after `onSuccess`, because the two
+     * mean the same thing in that mode.
+     */
+    onSynced?: (data: T, variables: TVariables) => unknown;
+}
+interface UseMutationOptions<T extends Doc = Doc, TVariables = InsertVariables<T>, TContext = MutationContext> extends MutationCallbacks<T, TVariables, TContext> {
+    collection: string;
+    /**
+     * Which write this hook performs. Default `'insert'`.
+     *
+     * Deliberately **not** inferred from the presence of `_id`: a caller who
+     * passes an id on an insert would silently get an update instead.
+     */
+    operation?: MutationOperation;
+    /**
+     * URL template for this collection's writes — `/api/v2/todos/:id`.
+     *
+     * `:id` and `:collection` interpolate; an insert drops a trailing `/:id`.
+     * A template rather than a function because a queued write is sent long
+     * after its component is gone, so the route has to be storable.
+     *
+     * Omitted falls back to the provider's backend.
+     */
+    url?: string;
+    /** Verb overrides. Defaults to POST / PUT / DELETE. */
+    method?: Partial<Record<SyncOp, string>>;
+    /** Default `'optimistic'`. */
+    mode?: MutationMode;
+    /**
+     * Perform the request yourself. **`mode: 'immediate'` only.**
+     *
+     * Under `optimistic` and `queued` the request is sent by the drain loop long
+     * after this component is gone — after a route change, a reload, a week. A
+     * closure cannot be stored, so there would be nothing left to call; accepting
+     * one there would mean silently dropping the write on reload, which is worse
+     * than refusing it. Those modes route by `url` instead, which is data.
+     *
+     * Given one, `url`, `method` and the provider's `classify` do not apply: the
+     * function owns the request. Its resolved value is stored as the document.
+     */
+    mutationFn?: (variables: TVariables) => Promise<T>;
+    /** Opaque; carried for instrumentation. */
+    meta?: Record<string, unknown>;
+    /**
+     * How many times to retry a failed write. Default `0`.
+     *
+     * **Not** the queries' default of 3, and deliberately so: a read is
+     * idempotent and a write may not be. Retrying a `POST` that timed out after
+     * the server accepted it is how duplicate rows appear. Turn it on only where
+     * the endpoint is genuinely idempotent — which contract rule 2 asks for, but
+     * the default should not assume.
+     *
+     * Applies to `immediate` only. Queued writes have their own durable backoff
+     * in the drain, which survives reload; this one does not.
+     */
+    retry?: RetryOption;
+    /** Milliseconds between attempts. Default is exponential from 1s, capped at 30s. */
+    retryDelay?: RetryDelayOption;
+    /**
+     * What to do about writing while offline. Default `'online'`.
+     *
+     * Under `immediate`, `'online'` **pauses** rather than failing — the mutation
+     * stays pending, reports `isPaused`, and goes as soon as the connection
+     * returns. `'always'` attempts regardless.
+     *
+     * `optimistic` and `queued` ignore this: they commit locally and the drain
+     * owns connectivity from there.
+     */
+    networkMode?: NetworkMode;
+    /** Rethrow a write error during render, for an error boundary to catch. */
+    throwOnError?: boolean | ((error: Error) => boolean);
+    /**
+     * Run mutations sharing an id one at a time, in call order.
+     *
+     * Without it, two rapid submits race and the later response may land first.
+     * Note this is a *scheduling* guarantee, distinct from the layer's rule that
+     * a document has at most one pending operation — that one coalesces edits,
+     * this one orders requests.
+     */
+    scope?: {
+        id: string;
+    };
+}
+/** Fields present on a mutation result whatever its status. */
+interface MutationResultCommon<T extends Doc, TVariables> {
+    /** Fire-and-forget. Errors surface on `error`, never thrown to render. */
+    mutate: (variables: TVariables, options?: MutationCallbacks<T, TVariables>) => void;
+    /** Awaitable. Under `optimistic`, resolves on the *local* commit. */
+    mutateAsync: (variables: TVariables, options?: MutationCallbacks<T, TVariables>) => Promise<T>;
+    /** Back to `idle`, forgetting the last result. */
+    reset: () => void;
+    /** Offline, so an `immediate` write has not been attempted. */
+    isPaused: boolean;
+    failureCount: number;
+    failureReason: Error | null;
+    /** Epoch ms of the last `mutate` call, or `0`. */
+    submittedAt: number;
+}
+/**
+ * The result of `useMutation`.
+ *
+ * A discriminated union on `status`, so `if (isSuccess)` narrows `data` and
+ * `if (isError)` narrows `error` — the same treatment `QueryResult` gets, for
+ * the same reason.
+ *
+ * Note `idle`, which has no `useQuery` equivalent: a mutation that has never
+ * run has not failed and is not loading, and migrated code branches on it to
+ * render a clean form.
+ */
+type MutationResult<T extends Doc = Doc, TVariables = InsertVariables<T>> = (MutationResultCommon<T, TVariables> & {
+    status: 'idle';
+    data: undefined;
+    error: null;
+    variables: undefined;
+    isIdle: true;
+    isPending: false;
+    isSuccess: false;
+    isError: false;
+}) | (MutationResultCommon<T, TVariables> & {
+    status: 'pending';
+    data: undefined;
+    error: null;
+    variables: TVariables;
+    isIdle: false;
+    isPending: true;
+    isSuccess: false;
+    isError: false;
+}) | (MutationResultCommon<T, TVariables> & {
+    status: 'success';
+    /** The stored document. Locally committed, or the server's body under `immediate`. */
+    data: T;
+    error: null;
+    variables: TVariables;
+    isIdle: false;
+    isPending: false;
+    isSuccess: true;
+    isError: false;
+}) | (MutationResultCommon<T, TVariables> & {
+    status: 'error';
+    data: undefined;
+    error: Error;
+    variables: TVariables;
+    isIdle: false;
+    isPending: false;
+    isSuccess: false;
+    isError: true;
+});
+/**
+ * A write intent, as the storage layer sees it.
+ *
+ * No longer the public `mutate` signature — that takes plain variables, as
+ * TanStack's does — but still the internal representation, because a queued
+ * write has to be *data* to survive the component that made it.
+ *
+ * `where` is `{ _id }` rather than an arbitrary filter: a filter-based write
+ * issued from a secondary tab is forwarded to the primary and re-evaluated
+ * there against authoritative data, so it can affect a different set of
+ * documents than the optimistic UI just showed.
+ */
+type MutationOp<T extends Doc> = {
+    type: 'insert';
+    doc: Omit<T, '_id'> & {
+        _id?: string;
+    };
+} | {
+    type: 'update';
+    where: {
+        _id: string;
+    };
+    set: Partial<Omit<T, '_id'>>;
+} | {
+    type: 'delete';
+    where: {
+        _id: string;
+    };
+};
+/** A write that failed terminally and will not retry on its own. */
+interface FailedWrite {
+    collection: string;
+    id: string;
+    op: SyncOp;
+    error: string;
+    attempts: number;
+}
+interface SyncStatus {
+    /** Queued, will send. */
+    pending: number;
+    /** Terminal. Needs a human decision. */
+    failed: FailedWrite[];
+    /** A drain cycle is running. */
+    draining: boolean;
+    online: boolean;
+    /** Requeue a failed write. */
+    retry: (id: string) => void;
+    /** Drop the local change and stop trying. */
+    discard: (id: string) => void;
+}
+
+interface QueryContextValue {
+    /** The `taladb_queries` collection, or `null` until it has opened. */
+    queries: Collection<QueryRecord> | null;
+    backend: ResolvedBackend;
+    drain: Required<Pick<DrainOptions, 'policy'>> & DrainOptions;
+    /** Maps a query key to a collection name. See `QueryProviderProps`. */
+    resolveCollection?: (queryKey: QueryKey) => string | undefined;
+    /** Provider-wide query defaults. Each hook option overrides its entry. */
+    defaults: QueryDefaults['queries'];
+    /** Declare a collection as managed, so the drain looks at it. */
+    register: (collection: string) => void;
+    /** Collections currently managed. Stable identity until one is added. */
+    collections: string[];
+    /** A drain cycle is in flight. */
+    draining: boolean;
+    /** Ask for a drain cycle soon. `force` is reserved for an explicit retry. */
+    requestDrain: (force?: boolean) => void;
+    /**
+     * Record a write that is deliberately *not* asking to be sent yet — a
+     * `queued` mutation.
+     *
+     * Separate from `requestDrain` because the difference between `queued` and
+     * `optimistic` is exactly whether the write asks for a cycle. It still has to
+     * be counted, or a backlog building under a long interval would never trip
+     * the threshold.
+     */
+    noteWrite: () => void;
+}
+/**
+ * Read the query layer's context.
+ *
+ * Throws rather than returning a default, because every plausible default is
+ * wrong: silently doing nothing would make a missing provider look like an
+ * empty result set.
+ */
+declare function useQueryContext(): QueryContextValue;
+interface QueryProviderProps {
+    children: ReactNode;
+    /**
+     * Headers for every outbound write, resolved **at send time**.
+     *
+     * That timing is the reason this lives here rather than on the hook: a write
+     * queued while offline and drained an hour later must carry a current token,
+     * not the one it was made with.
+     */
+    headers?: () => HeadersInit | Promise<HeadersInit>;
+    /**
+     * Map a response onto what the queue should do. Optional — by default `2xx`
+     * succeeds, `409` is already-applied, `5xx`/`408`/`429` retry, and any other
+     * `4xx` is terminal.
+     */
+    classify?: (response: Response, op: PendingWrite) => WriteOutcome;
+    /** Override the fetch implementation (tests, instrumentation). */
+    fetch?: typeof globalThis.fetch;
+    drain?: DrainOptions;
+    /**
+     * Work out which collection a query key's documents belong in.
+     *
+     * `useQuery` infers the collection from `queryKey[0]`, which covers the usual
+     * `['todos', …]` convention. Codebases whose keys do not lead with the
+     * collection — `['api', 'v2', 'todos']`, or keys built by a helper — set this
+     * once here rather than passing `collection` at every call site.
+     *
+     * Returning `undefined` falls back to the default inference. The result is
+     * still checked against the registered collections.
+     */
+    resolveCollection?: (queryKey: QueryKey) => string | undefined;
+    /**
+     * Defaults for every `useQuery` below this provider, in TanStack's
+     * `new QueryClient({ defaultOptions })` shape so existing config moves across
+     * unchanged.
+     *
+     * ```tsx
+     * <QueryProvider defaultOptions={{ queries: { staleTime: 0, retry: false } }}>
+     * ```
+     *
+     * `staleTime: 0` here is the one-line way back to TanStack's
+     * revalidate-on-every-mount behaviour.
+     */
+    defaultOptions?: QueryDefaults;
+}
+/**
+ * Provides the query layer's shared state beneath a `<TalaDBProvider>`.
+ *
+ * Nested rather than merged into `TalaDBProvider` so an application using only
+ * the local hooks never opens the query-record collection at all.
+ */
+declare function QueryProvider({ children, headers, classify, fetch, drain, resolveCollection, defaultOptions, }: QueryProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * One hour.
+ *
+ * TanStack defaults `staleTime` to `0`, which revalidates on every mount. That
+ * is right for a cache that dies on reload — the data is usually seconds old
+ * and the request is usually free — and wrong for one that survives reload and
+ * is expected to work offline, where it turns every mount into a network hit
+ * against data the device already holds.
+ */
+declare const DEFAULT_STALE_TIME: number;
+/**
+ * Pass this as `placeholderData` to hold the previous key's data on screen
+ * while the next one loads.
+ *
+ * v5 replaced the old `keepPreviousData` *option* with exactly this identity
+ * function, so it is exported under the same name a migrating codebase already
+ * imports.
+ */
+declare function keepPreviousData<T>(previous: T | undefined): T | undefined;
+/**
+ * Read a slice of a collection, hydrated from a server and revalidated in the
+ * background.
+ *
+ * `data` is resolved through the local database rather than from the fetch
+ * response, so a local write to any document in the set re-renders this query
+ * immediately — there is no cache to invalidate, because the collection *is*
+ * the state. Documents arrive in the order the server returned them.
+ *
+ * On a cold key the hook fetches and reports `pending`. On a warm key it
+ * renders what it has straight away and revalidates behind that only once
+ * `staleTime` has elapsed — a reload never shows a spinner over data the device
+ * already holds.
+ */
+declare function useQuery<T extends Doc, TData = T[]>(options: UseQueryOptions<T, TData>): QueryResult<TData>;
+declare function useQuery<T extends Doc, TData = T>(options: UseDocumentQueryOptions<T, TData>): QueryResult<TData | undefined>;
+declare function useQuery<TRaw, TDoc extends Doc, TAssembled = TDoc[], TData = TAssembled>(options: UseEnvelopeQueryOptions<TRaw, TDoc, TAssembled, TData>): QueryResult<TData>;
+/** Test seam — pending timers are module state that would leak between cases. */
+declare function resetForgetTimers(): void;
+
+/**
+ * Structural sharing: keep the previous reference when the new value is equal.
+ *
+ * Without this, `data` is a fresh array on every database snapshot — the live
+ * query re-runs, rebuilds its documents, and hands back objects that are deeply
+ * equal but referentially new. Migrated code is full of `useEffect(…, [data])`
+ * and `useMemo(…, [data])`, and every one of them would fire on each snapshot,
+ * including snapshots that changed nothing relevant to this query. TanStack does
+ * the same thing for the same reason.
+ *
+ * The result is that a component re-renders only when something it can actually
+ * observe has changed, and that `data === data` across renders holds as long as
+ * the contents hold.
+ */
+declare function replaceEqualDeep<T>(previous: unknown, next: T): T;
+
+/**
+ * One request per key, however many components ask for it.
+ *
+ * Without this, a screen holding a list, a count badge and a header that all use
+ * `queryKey: ['todos']` fires three identical requests on mount. Each hook here
+ * owns its own state — there is no shared observer the way TanStack has one — so
+ * nothing else would collapse them. It is invisible in tests that mount
+ * sequentially, because the first writes a record the rest read warm, which is
+ * exactly why it needs its own guard rather than an assertion somewhere.
+ *
+ * The shared work is the *whole* fetch — request, hydration, and the query
+ * record — not just the network call. Sharing only the response would still have
+ * every waiter hydrate the same documents, and write amplification is a real
+ * hazard here: on a secondary tab each of those writes is forwarded against a
+ * bounded buffer.
+ */
+/** Identifies a request. Same collection and key hash means the same work. */
+declare function inflightKey(collection: string, keyHash: string): string;
+/**
+ * Run `work` once for this key, or join the run already happening.
+ *
+ * `callerSignal` expresses only this caller's interest. Abandoning it does not
+ * abort the shared request unless every other caller has abandoned it too —
+ * otherwise one component unmounting would cancel a fetch three others are
+ * still waiting on.
+ */
+declare function runShared<T>(key: string, work: (signal: AbortSignal) => Promise<T>, callerSignal: AbortSignal): Promise<T>;
+/**
+ * Abandon the in-flight request for a key, if there is one.
+ *
+ * This is what `refetch({ cancelRefetch: true })` — the default — means: start
+ * again rather than return whatever is already on its way.
+ */
+declare function cancelShared(key: string): void;
+/** Whether a request for this key is already on its way. */
+declare function isShared(key: string): boolean;
+/** Test seam — in-flight state is module state that would leak between cases. */
+declare function resetInflight(): void;
+
+/**
+ * Read-path retry policy.
+ *
+ * Deliberately separate from the write queue's backoff in `drain.ts`. They look
+ * alike and mean different things: a queued write must survive a reload and a
+ * week offline, so its attempt count lives on the document. A read is
+ * in-flight state belonging to one mounted component, and is abandoned the
+ * moment that component unmounts.
+ */
+/** TanStack's default: three retries, so four attempts in all. */
+declare const DEFAULT_RETRY = 3;
+/**
+ * Whether to try again after `failureCount` failures.
+ *
+ * `failureCount` is the number of attempts that have already failed, so a
+ * numeric `retry` of 3 keeps going while it is 1, 2 or 3 and gives up at 4.
+ */
+declare function shouldRetry(retry: RetryOption | undefined, failureCount: number, error: Error): boolean;
+/**
+ * How long to wait before attempt `attemptIndex + 1`.
+ *
+ * Exponential from one second, capped at thirty — the same curve TanStack uses,
+ * so a migrated app's retry timing does not quietly change.
+ */
+declare function retryDelayMs(retryDelay: RetryDelayOption | undefined, attemptIndex: number, error: Error): number;
+/** Whether the browser believes it is offline. Unknown counts as online. */
+declare function isOffline(): boolean;
+
+/**
+ * Development-time notices.
+ *
+ * Some TanStack options are accepted here and do nothing — a drop-in that
+ * *throws* on an unknown option is not a drop-in. But silence is a trap, so
+ * every such option says so once, loudly enough to find and quietly enough to
+ * live with.
+ */
+declare function isDev(): boolean;
+/**
+ * Warn once per key for the life of the session.
+ *
+ * A hook warning on every render is noise that gets filtered out, which is the
+ * same as not warning at all.
+ */
+declare function warnOnce(key: string, message: string): void;
+/** Test seam — the warn-once set is module state that would leak between cases. */
+declare function resetWarnings(): void;
+/** Announce any accept-and-ignore option present on this call. */
+declare function noteIgnoredOptions(options: Record<string, unknown>): void;
+
+/**
+ * Work out which collection a query's documents belong in.
+ *
+ * This is the one option TanStack Query has no analogue for, and the one most
+ * worth getting right: it is not a cache label, it is the physical destination.
+ * `hydrate` writes every fetched document into `db.collection(name)`, so a wrong
+ * value does not degrade a cache — it pours server documents into a collection
+ * the application reads for something else, or conjures one nobody declared.
+ * There is no cache-miss failure mode here to soften the landing.
+ *
+ * So inference is allowed, but never trusted: the provider's `collections`
+ * registry is the list of legal answers, and a guess that is not on it is an
+ * error rather than a new collection.
+ */
+interface ResolveCollectionInput {
+    /** Explicit option from the call site. Always wins. */
+    collection?: string;
+    queryKey: QueryKey;
+    /** Provider-level override, for keys that do not lead with the collection. */
+    resolve?: (queryKey: QueryKey) => string | undefined;
+    /** Registered collection names, from the `TalaDBProvider` registry. */
+    registered: string[];
+}
+declare function resolveCollectionName({ collection, queryKey, resolve, registered, }: ResolveCollectionInput): string;
+
+/**
+ * Work out which documents a `queryFn` response contains.
+ *
+ * This is the deepest mismatch with TanStack Query and the one no rename can
+ * absorb: their `data` *is* whatever `queryFn` returned, ours is rebuilt from
+ * the local collection. So a response has to reduce to documents, and the three
+ * shapes that reduce cleanly are recognised without configuration:
+ *
+ * - `T[]`  — a list. The common case.
+ * - `T`    — one document, for a detail view.
+ * - anything else — an envelope, which must say which part of itself is
+ *   documents via `documents`, and how to put itself back together via
+ *   `assemble`.
+ *
+ * A response that is none of those fails loudly. It is the one case a codemod
+ * cannot fix, so the runtime has to explain it.
+ */
+interface ExtractInput {
+    raw: unknown;
+    collection: string;
+    queryKey: QueryKey;
+    documents?: (raw: unknown) => Doc[];
+}
+interface Extracted {
+    documents: Doc[];
+    shape: ResultShape;
+}
+declare function extractDocuments({ raw, collection, queryKey, documents, }: ExtractInput): Extracted;
+
+/**
+ * Write to a collection.
+ *
+ * `mutate(variables)` takes the document — TanStack's signature — and the
+ * operation is declared once on the hook:
+ *
+ * ```ts
+ * const createTodo = useMutation<Todo>({ collection: 'todos', url: '/api/todos/:id' })
+ * createTodo.mutate({ title: 'Buy milk' })
+ *
+ * const updateTodo = useMutation<Todo>({ collection: 'todos', url: '/api/todos/:id', operation: 'update' })
+ * updateTodo.mutate({ _id, done: true })
+ * ```
+ *
+ * `url` is a template rather than a function for one reason: under `optimistic`
+ * and `queued` the request is sent by the drain loop, long after this component
+ * is gone — after a route change, a reload, a week. A template is data and can
+ * be stored on the queued document; a closure cannot. That is also why
+ * `mutationFn` is only possible under `immediate`.
+ *
+ * Auth and error policy stay on `<QueryProvider>`. `headers` in particular has
+ * to be resolved at send time, so a write queued offline carries a current
+ * token instead of the expired one it was made with.
+ */
+declare function useMutation<T extends Doc, TVariables = T>(options: UseMutationOptions<T, TVariables> & {
+    mode: 'immediate';
+    mutationFn: (variables: TVariables) => Promise<T>;
+}): MutationResult<T, TVariables>;
+declare function useMutation<T extends Doc = Doc>(options: UseMutationOptions<T, InsertVariables<T>> & {
+    operation?: 'insert';
+}): MutationResult<T, InsertVariables<T>>;
+declare function useMutation<T extends Doc = Doc>(options: UseMutationOptions<T, UpdateVariables<T>> & {
+    operation: 'update';
+}): MutationResult<T, UpdateVariables<T>>;
+declare function useMutation<T extends Doc = Doc>(options: UseMutationOptions<T, DeleteVariables> & {
+    operation: 'delete';
+}): MutationResult<T, DeleteVariables>;
+/** Test seam — scope chains are module state that would leak between cases. */
+declare function resetMutationScopes(): void;
+
+/**
+ * What the write queue is doing, live.
+ *
+ * Optimistic writes are the point of this layer and its biggest hazard: a
+ * request that fails after the user has navigated away has no UI left to fail
+ * into. Without something rendering this, a write can be lost with no symptom
+ * at all — which is how local-first libraries lose people's trust. Show
+ * `pending` somewhere quiet and `failed` somewhere loud.
+ *
+ * A terminal failure is never retried on its own. It needs a decision:
+ * `retry` when the cause has been fixed server-side, `discard` to stop trying.
+ */
+declare function useSyncStatus(): SyncStatus;
+
+/** Where a queued write should be sent, stamped onto the document. */
+interface Route {
+    url?: string;
+    method?: Partial<Record<SyncOp, string>>;
+}
+/** What a local write did, for tests and for `useSyncStatus` to count. */
+interface LocalWriteResult {
+    id: string;
+    /** What the document now owes the server, or `null` if it owes nothing. */
+    op: SyncOp | null;
+    /** The write cancelled an unsent insert, so the document was removed outright. */
+    cancelled: boolean;
+}
+/**
+ * Apply a write locally and record what the server still owes.
+ *
+ * Deletes become **tombstones**, not deletions. A queued delete lives on the
+ * document it deletes; calling `deleteOne` here would erase the only record of
+ * the operation, and the server would never hear about it. The document is
+ * removed for real once the drain gets an acknowledgement.
+ *
+ * At most one operation is pending per document — a second edit folds into the
+ * first rather than queueing behind it. That is what removes the dependency
+ * graph, the id-remap table, and the replay log in one stroke; the cost is that
+ * intermediate states are lost, so `$inc`-style writes cannot be expressed
+ * offline.
+ */
+declare function writeLocal<T extends Document>(collection: Collection<T>, op: MutationOp<T>, now: number, route?: Route): Promise<LocalWriteResult>;
+/**
+ * Apply a confirmed server document locally, after a `remote-first` write.
+ *
+ * The response body is canonical, so server-set fields — timestamps, defaults,
+ * computed columns — land without a second fetch.
+ */
+declare function writeConfirmed<T extends Document>(collection: Collection<T>, doc: T, now: number): Promise<void>;
+
+interface DrainStats {
+    sent: number;
+    /** Confirmed by the server (`ok` or `applied`). */
+    synced: number;
+    /** Will be retried after a back-off. */
+    deferred: number;
+    /** Terminal — parked for a human decision. */
+    failed: number;
+    /** Superseded by a local edit that landed while the request was in flight. */
+    superseded: number;
+    /** True when the cycle did not run because this tab is not the primary. */
+    skippedNotPrimary: boolean;
+}
+interface DrainDeps {
+    db: TalaDB;
+    /** Fallback for documents queued without their own route. */
+    backend: ResolvedBackend | null;
+    /** Collections this layer manages, resolved fresh each cycle. */
+    collections: () => string[];
+    batch?: number;
+    now?: () => number;
+    random?: () => number;
+    /** Send with `keepalive`, for a flush on `pagehide`. */
+    keepalive?: boolean;
+}
+/** 1s, doubling, ±25% jitter, capped at five minutes. */
+declare function backoffMs(attempt: number, random?: () => number): number;
+/**
+ * Send every eligible queued write once.
+ *
+ * **Runs only on the primary tab.** This is a correctness requirement, not an
+ * optimisation. A secondary tab reads a pending set that lags other tabs by up
+ * to half a second, and its own bookkeeping — marking a document synced after a
+ * successful request — is itself a forwarded write applied at the primary
+ * later. Until that lands the document still reads as pending locally, so the
+ * next cycle sends it again. Contract rules 2 and 3 keep that survivable rather
+ * than corrupting, which is exactly why they are rules.
+ *
+ * Primary status changes mid-session when the owning tab closes, so it is
+ * re-checked every cycle rather than cached.
+ */
+declare function drainOnce(deps: DrainDeps): Promise<DrainStats>;
+
+interface SendResult {
+    outcome: WriteOutcome;
+    /** The canonical document, when the response carried one. */
+    document: Record<string, unknown> | null;
+    status: number;
+}
+/**
+ * Send one queued write to the application's backend and classify the result.
+ *
+ * Shared by `remote-first` mutations and the drain loop, so both agree on what
+ * a 409 means and neither invents its own retry policy.
+ */
+declare function sendWrite(backend: ResolvedBackend, op: PendingWrite, signal?: AbortSignal, attempt?: number, 
+/**
+ * Ask the browser to let this request outlive the page.
+ *
+ * Set only for a flush on `pagehide`, where an ordinary `fetch` is cancelled
+ * the moment the document goes away. The cost is a hard 64 KB cap on the
+ * combined body of all in-flight keepalive requests, which is why this is
+ * never the default — a normal drain has a live page and does not need it.
+ */
+keepalive?: boolean): Promise<SendResult>;
+/** Describe a stored document as the write the backend should receive. */
+declare function toPendingWrite(collection: string, id: string, type: PendingWrite['type'], document: Record<string, unknown> | null): PendingWrite;
+
+interface HydrateResult {
+    /** Documents the device had never seen. */
+    inserted: number;
+    /** Documents refreshed from the response. */
+    updated: number;
+    /** Documents left alone because they carry unsynced local work. */
+    skipped: number;
+}
+/**
+ * Write a server response into the local collection.
+ *
+ * The rule that matters, and the one a naive bulk upsert gets wrong: **a
+ * response must never overwrite a document with unsynced local work.** The
+ * moment connectivity returns, a refetch and a queued edit race, and the
+ * obvious implementation silently discards whatever the user did offline.
+ * Anything not `synced` is therefore left exactly as it is — the drain loop
+ * owns those documents until the server accepts them.
+ *
+ * Inserts go through one `insertMany`; updates cannot be batched, because each
+ * document sets different values and the engine exposes no upsert. That matters
+ * on a secondary browser tab, where every write is forwarded to the primary and
+ * the forward buffer is bounded — see PLAN-query.md §5.
+ */
+declare function hydrate<T extends Document>(collection: Collection<T>, docs: T[], now: number): Promise<HydrateResult>;
+
+/**
+ * Rules 1 and 2 — client ids are authoritative, and writes are idempotent.
+ *
+ * Same detection, different consequence: on a first attempt a reassigned id
+ * means every write will duplicate from now on; on a retry it means this write
+ * *just* duplicated, because the server treated the retry as a new record.
+ */
+declare function checkResponseId(op: PendingWrite, body: Record<string, unknown> | null, attempt: number): void;
+/** Rule 4 — the response body is the canonical document. */
+declare function checkResponseBody(op: PendingWrite, body: Record<string, unknown> | null): void;
+/** Rule 3 — error classes are explicit, and a 4xx is not retryable. */
+declare function checkClassification(op: PendingWrite, status: number, outcome: WriteOutcome): void;
+/** Rule 6 — mutation filters must be `_id`-based. */
+declare function checkMutationFilter(where: unknown): void;
+
+/**
+ * Fields this layer owns on every document it manages.
+ *
+ * They live on the document rather than in a separate outbox collection because
+ * TalaDB exposes no multi-collection transaction: a document write and an
+ * outbox row describing it would be two commits, and a crash between them
+ * either orphans a queued mutation or strands a document that never syncs.
+ * Keeping the state here makes every queued write a single atomic commit — and
+ * turns the queue into an indexed query.
+ */
+declare const ENVELOPE_FIELDS: readonly ["_sync", "_op", "_attempt", "_error", "_fetched_at", "_retry_at", "_endpoint", "_method", "_revision"];
+/**
+ * Indexes this layer needs on every collection it manages.
+ *
+ * `_sync` is the queue the drain selects on. `_changed_at` is its order: the
+ * drain sorts by it to send per-document writes in the order they happened, and
+ * since 0.11.0 that field is no longer indexed automatically — without this the
+ * sort falls back to reading the whole collection. `createIndex` is idempotent,
+ * so both are safe to run on every registration.
+ */
+declare const ENVELOPE_INDEXES: readonly ["_sync", "_changed_at"];
+/**
+ * Reserved field names present in a document, if any.
+ *
+ * Checked against real documents rather than against the registered schema:
+ * schemas are Standard Schema values (Zod, Valibot, …) with no portable way to
+ * enumerate their keys, and the failure this guards against — a server response
+ * carrying a `_sync` field that overwrites the envelope and drops the document
+ * out of the queue — shows up in the data regardless of what the schema says.
+ */
+declare function reservedFieldsIn(doc: Record<string, unknown>): string[];
+/** A document as stored: the caller's fields plus the envelope. */
+type Enveloped<T extends Document> = T & SyncEnvelope;
+/**
+ * Stamp a document that came from the server and matches it.
+ *
+ * Only ever applied to documents that are not currently pending — a response
+ * must never overwrite an unsynced local edit, which is the mistake a bulk
+ * upsert makes by default.
+ */
+declare function stampSynced<T extends Document>(doc: T, now: number): Enveloped<T>;
+/**
+ * Stamp a locally-written document that the server has not seen yet.
+ *
+ * `_fetched_at` is deliberately preserved from any previous hydration: it
+ * records when the server last spoke about this document, and a local edit does
+ * not change that.
+ */
+declare function stampPending<T extends Document>(doc: T, op: SyncOp, previous?: Partial<SyncEnvelope>): Enveloped<T>;
+/**
+ * Fold a new write into whatever this document already owed the server.
+ *
+ * At most one operation is pending per document, so a second edit overwrites
+ * the first rather than queueing behind it. This is what removes the dependency
+ * graph, the id-remap table, and the replay log in one go — the cost being that
+ * intermediate states are lost, so `$inc`-style operations cannot be expressed
+ * offline.
+ *
+ * Returns `null` when the write cancels the pending operation outright: an
+ * insert the server never saw, then deleted, is simply gone.
+ */
+declare function coalesce(pending: SyncOp | undefined, next: SyncOp): SyncOp | null;
+
+/**
+ * The collection holding one record per query shape.
+ *
+ * Not `_queries`: the engine reserves collection names beginning with `_` and
+ * rejects them outright with `InvalidName`.
+ */
+declare const QUERY_COLLECTION = "taladb_queries";
+/**
+ * Serialise a query key to a string that is identical for equal keys and
+ * different for unequal ones.
+ *
+ * Plain-object properties are emitted in sorted order, so `{ a: 1, b: 2 }` and
+ * `{ b: 2, a: 1 }` — which a component may produce on alternating renders from
+ * the same props — hash to one record rather than two. Arrays keep their order,
+ * because `['a', 'b']` and `['b', 'a']` are genuinely different keys.
+ *
+ * `undefined` is preserved as an explicit marker rather than dropped, so
+ * `{ status: undefined }` and `{}` stay distinct: the first says "this filter
+ * exists and is unset", the second says "no such filter".
+ *
+ * Keys must be JSON-shaped — primitives, arrays, plain objects. A function,
+ * symbol, or class instance throws rather than silently collapsing two
+ * different queries onto one record.
+ */
+declare function hashQueryKey(key: QueryKey): string;
+/**
+ * The `_id` of the `taladb_queries` record for one query shape.
+ *
+ * Document ids are 16 raw bytes on disk and must be ULIDs, so the natural key —
+ * here `(collection, key)` — is folded into one by the same `deriveDocId` used
+ * for hydrating rows that already have an identity upstream. The mapping is
+ * deterministic, which is what lets a refetch overwrite its own record instead
+ * of accumulating a second one.
+ */
+declare function queryRecordId(collection: string, key: QueryKey, 
+/** Override the key serialiser — see the `queryKeyHashFn` option. */
+hash?: (key: QueryKey) => string): string;
+/**
+ * Mint a document id on the client.
+ *
+ * Client ids are authoritative — contract rule 1 — so a write must know its id
+ * before it reaches the network, not after. That matters most for a
+ * `remote-first` insert, which has no local document to take an
+ * engine-generated id from, and it is what lets a retried insert be recognised
+ * as a duplicate rather than creating a second row.
+ *
+ * Routed through `deriveDocId` rather than a second ULID encoder, so there is
+ * exactly one implementation of "produce an id this engine will accept".
+ */
+declare function newDocId(collection: string): string;
+
+/** The verb each operation uses unless the caller overrides it. */
+declare const DEFAULT_METHODS: Record<SyncOp, string>;
+/**
+ * Resolve a URL template for one write.
+ *
+ * A template rather than a function because a queued write is sent long after
+ * the component that made it is gone — possibly after a reload — so the route
+ * has to be storable alongside the document. `:id` and `:collection`
+ * interpolate.
+ *
+ * An insert has no id in the path: `/api/todos/:id` becomes `/api/todos`. That
+ * matches how REST endpoints are actually shaped, so one template covers all
+ * three verbs instead of forcing a branch at every call site.
+ */
+declare function resolveUrl(template: string, collection: string, id: string, type: SyncOp): string;
+/**
+ * How a response is read when the application has not supplied a `classify`.
+ *
+ * Deliberately conservative: only a 409 is assumed to mean "already applied",
+ * because that is the one convention universal enough to guess at. Everything
+ * else follows the HTTP status class.
+ */
+declare function defaultClassify(response: Response): WriteOutcome;
+
+/**
+ * Prepare a collection to be managed by this layer.
+ *
+ * Idempotent — `createIndex` is a no-op when the index already exists, so this
+ * runs on every registration rather than needing to track what it has seen.
+ */
+declare function ensureEnvelopeIndexes(collection: Collection<Document>): Promise<void>;
+/** The `taladb_queries` collection, prepared for use. */
+declare function openQueryCollection(db: TalaDB): Promise<Collection<QueryRecord>>;
+/**
+ * Read the record for one query shape, or `null` if this query has never been
+ * fetched on this device.
+ */
+declare function readQueryRecord(queries: Collection<QueryRecord>, collection: string, key: QueryKey, hash?: (key: QueryKey) => string): Promise<QueryRecord | null>;
+/**
+ * Forget which documents a query returned.
+ *
+ * Deliberately *only* the record. The documents stay: they live in the
+ * application's own collections, which it also reads directly, so deleting them
+ * would destroy real user data rather than reclaim a cache. Dropping the record
+ * makes the next mount cold, and it refetches to re-establish membership.
+ */
+declare function deleteQueryRecord(queries: Collection<QueryRecord>, collection: string, key: QueryKey, hash?: (key: QueryKey) => string): Promise<void>;
+/**
+ * Record what a fetch returned: which documents were in the result set, in
+ * server order, and when.
+ *
+ * Membership is stored rather than derived because the two facts a client
+ * cannot otherwise distinguish — "this document no longer matches the filter"
+ * and "this document was deleted upstream" — look identical from here. Keeping
+ * the id list means a refetch can shrink the result set without having to
+ * delete anything.
+ */
+declare function writeQueryRecord(queries: Collection<QueryRecord>, collection: string, key: QueryKey, ids: string[], now: number, ttl: number, 
+/** How `queryFn`'s return value mapped onto documents. */
+shape?: ResultShape, 
+/** The raw response, for envelope queries. `undefined` for every other shape. */
+payload?: Value, 
+/** Override the key serialiser — see `queryKeyHashFn`. */
+hash?: (key: QueryKey) => string): Promise<QueryRecord>;
+/**
+ * Whether a record is past its freshness window.
+ *
+ * Staleness drives a background refetch — never a deletion. The documents this
+ * layer hydrates land in the application's own collections, which the app also
+ * reads directly; a TTL sweep over them would delete real user data, not
+ * reclaim cache. A record with `ttl: 0` is always stale, which is how
+ * "revalidate on every mount" is expressed.
+ */
+declare function isStale(record: QueryRecord, now: number): boolean;
+
+export { type AnyQueryOptions, type BackendDefinition, type BaseQueryOptions, type BoundParams, DEFAULT_METHODS, DEFAULT_RETRY, DEFAULT_STALE_TIME, type DeleteVariables, type Doc, type DrainDeps, type DrainOptions, type DrainPolicy, type DrainStats, ENVELOPE_FIELDS, ENVELOPE_INDEXES, type Enveloped, type ExtractInput, type Extracted, type FailedWrite, type HydrateResult, type InsertVariables, type LocalWriteResult, type MutationCallbacks, type MutationContext, type MutationMode, type MutationOp, type MutationOperation, type MutationResult, type MutationResultCommon, type NetworkMode, type ParamOp, type ParamPrimitive, type ParamSpec, type ParamValue, type PendingWrite, QUERY_COLLECTION, type QueryContextValue, type QueryDefaults, type QueryFunctionContext, type QueryKey, QueryProvider, type QueryProviderProps, type QueryRecord, type QueryResult, type QueryResultCommon, type RefetchTrigger, type ResolveCollectionInput, type ResolvedBackend, type ResultShape, type RetryDelayOption, type RetryOption, type Route, type SendResult, type SyncEnvelope, type SyncOp, type SyncState, type SyncStatus, type UpdateVariables, type UseDocumentQueryOptions, type UseEnvelopeQueryOptions, type UseMutationOptions, type UseQueryOptions, type ValuesOf, type WriteOutcome, backoffMs, cancelShared, checkClassification, checkMutationFilter, checkResponseBody, checkResponseId, coalesce, contains, defaultClassify, defineParams, deleteQueryRecord, drainOnce, ensureEnvelopeIndexes, eq, extractDocuments, gt, gte, hashQueryKey, hydrate, inflightKey, isBoundParams, isDev, isOffline, isShared, isStale, keepPreviousData, lt, lte, ne, newDocId, normalizeParams, noteIgnoredOptions, oneOf, openQueryCollection, queryRecordId, readQueryRecord, replaceEqualDeep, reservedFieldsIn, resetWarnings as resetCollectionWarnings, resetForgetTimers, resetInflight, resetMutationScopes, resetWarnings, resolveCollectionName, resolveUrl, retryDelayMs, runShared, sendWrite, shape, shouldRetry, stampPending, stampSynced, toPendingWrite, useMutation, useQuery, useQueryContext, useSyncStatus, warnOnce, writeConfirmed, writeLocal, writeQueryRecord };