@delali/narsil 0.3.1-next.73 → 0.3.1-next.74

package/dist/{memory-B4jMmygw.d.ts → memory-DJEwWoCi.d.ts}

@@ -1,1421 +1,1446 @@
-import { A as AnyDocument, S as SchemaDefinition, d as ScoringMode } from './schema-BBOCdhND.js';
+import { A as AnyDocument, d as ScoringMode, S as SchemaDefinition } from './schema-DgyDijhf.js';
 
 /**
- * Every code a {@link NarsilError} carries, grouped by the part of the engine
- * that raises it.
- *
- * Match on the code rather than on the message, because a code is stable and a
- * message is not. The HTTP server maps each code to a status, so a code also
- * tells you whether the caller or the engine is at fault.
+ * Compares one field against a value. Setting several keys narrows the match,
+ * because a document has to satisfy all of them.
  *
  * @public
  */
-declare const ErrorCodes: {
-    readonly SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE";
-    readonly SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED";
-    readonly SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION";
-    readonly SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT";
-    readonly DOC_NOT_FOUND: "DOC_NOT_FOUND";
-    readonly DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS";
-    readonly DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED";
-    readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
-    readonly INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS";
-    readonly INDEX_ORPHANED: "INDEX_ORPHANED";
-    readonly INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED";
-    readonly INSTANCE_SHUT_DOWN: "INSTANCE_SHUT_DOWN";
-    readonly PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
-    readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
-    readonly WORKER_CRASHED: "WORKER_CRASHED";
-    readonly WORKER_BUSY: "WORKER_BUSY";
-    readonly WORKER_TIMEOUT: "WORKER_TIMEOUT";
-    readonly WORKER_ACTION_FAILED: "WORKER_ACTION_FAILED";
-    readonly PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED";
-    readonly PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED";
-    readonly PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED";
-    readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
-    readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
-    readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
-    readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
-    readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
-    readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
-    readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
-    readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
-    readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
-    readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
-    readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
-    readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
-    readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
-    readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
-    readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
-    readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
-    readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
-    readonly EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID";
-    readonly DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD";
-    readonly CONFIG_INVALID: "CONFIG_INVALID";
-    readonly QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED";
-    readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
-    readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
-    readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
-    readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
-    readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
-    readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
-    readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
-    readonly CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID";
-    readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
-    readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
-    readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
-    readonly NODE_NOT_READY: "NODE_NOT_READY";
-    readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
-    readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
-    readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
-    readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
-    readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
-    readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
-    readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
-    readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
-    readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
-    readonly REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH";
-    readonly REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED";
-    readonly PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY";
-    readonly PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED";
-    readonly INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS";
-    readonly SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED";
-    readonly SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID";
-    readonly SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND";
-    readonly SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED";
-    readonly SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED";
-    readonly SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED";
-    readonly SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID";
-    readonly SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID";
-    readonly SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH";
-    readonly SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER";
-    readonly SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW";
-    readonly SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED";
-    readonly SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING";
-    readonly SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING";
-    readonly SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH";
-    readonly SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR";
-    readonly SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS";
-    readonly SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED";
-    readonly SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE";
-    readonly SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED";
-    readonly SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED";
-    readonly SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT";
-    readonly SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE";
-    readonly SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED";
-    readonly SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED";
+type ComparisonFilter = {
+    /** This matches a field equal to the value, or a list field where one element equals it. */
+    eq?: number | string | boolean;
+    /**
+     * This matches a document that holds the field with a value other than this
+     * one, or a list field where every element differs from it, which an empty
+     * list does.
+     */
+    ne?: number | string | boolean;
+    /** This matches a field greater than the number. */
+    gt?: number;
+    /** This matches a field less than the number. */
+    lt?: number;
+    /** This matches a field greater than or equal to the number. */
+    gte?: number;
+    /** This matches a field less than or equal to the number. */
+    lte?: number;
+    /** This matches a field inside the inclusive range, given as `[low, high]`. */
+    between?: [number, number];
 };
 /**
- * Any one of the codes in {@link ErrorCodes}, which is the type to narrow on
- * when you branch on a failure the engine raised.
+ * The engine tests a text field against this filter for equality, for a text
+ * range, or with the set and prefix tests.
  *
- * @public
- */
-type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
-/**
- * Every code the HTTP layer raises for a failure that arises before or around
- * the engine call, such as parsing the body, enforcing a limit, or routing.
+ * The engine compares each element of a `string[]`, `verbatim[]`, or `enum[]` field, so
+ * it matches a document with `eq`, `in`, `startsWith`, `endsWith`, or
+ * `contains` where one element passes the test, while it matches a document
+ * with `ne` or `nin` where every element differs from the values.
  *
- * The engine raises none of these, so a failure carrying one of them says the
- * request never reached the engine.
+ * The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
+ * to a single `string` or `verbatim` field whose type includes `sortable`,
+ * while it throws `SEARCH_INVALID_FILTER` for a text range on any other field.
+ * It orders the values as a sort on the field does, comparing their case folds
+ * first and their raw code points only where the folds are equal.
  *
- * @public
- */
-declare const ServerErrorCodes: {
-    readonly INVALID_REQUEST: "INVALID_REQUEST";
-    readonly INVALID_JSON: "INVALID_JSON";
-    readonly EMPTY_BODY: "EMPTY_BODY";
-    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
-    readonly NOT_FOUND: "NOT_FOUND";
-    readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
-    readonly TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE";
-    readonly TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE";
-    readonly TASK_INTERRUPTED: "TASK_INTERRUPTED";
-    readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
-    readonly HOOK_ERROR: "HOOK_ERROR";
-    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-};
-/**
- * Any one of the codes in {@link ServerErrorCodes}.
+ * A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
+ * `string[]` field whose type includes `pattern`. On such a field, the engine
+ * answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`, and `contains`
+ * from the field's pattern index. `caseFold` applies to each of those tests.
+ * On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
+ * `startsWith`, and `endsWith` from the field's index of values. It throws
+ * `SEARCH_INVALID_FILTER` for `eq`, `ne`, `in`, `nin`, `startsWith`, or
+ * `endsWith` on a `string` or `string[]` field whose type leaves out
+ * `pattern`, because such a field keeps no index of whole values.
+ * The engine compares the code points of each value as stored, with no
+ * Unicode normalisation. It throws `SEARCH_INVALID_FILTER` for `contains` or
+ * `caseFold` on any other field, for a test text longer than 1,024 code points
+ * on a pattern field, and for a `caseFold` test whose text has a case fold
+ * longer than 2,048 code points.
  *
  * @public
  */
-type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
+type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
+    /** This matches a value that comes after the text in sort order. */
+    gt?: string;
+    /** This matches a value that comes before the text in sort order. */
+    lt?: string;
+    /** This matches a value equal to the text or after it in sort order. */
+    gte?: string;
+    /** This matches a value equal to the text or before it in sort order. */
+    lte?: string;
+    /** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
+    between?: [string, string];
+    /** This matches a field equal to any value in the list, which holds at most 65,536 values. */
+    in?: string[];
+    /** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
+    nin?: string[];
+    /** This matches a field starting with the text. */
+    startsWith?: string;
+    /** This matches a field ending with the text. */
+    endsWith?: string;
+    /** This matches a pattern field whose value holds the text anywhere in it. */
+    contains?: string;
+    /**
+     * When this is true, the engine compares the case fold of each value of a
+     * pattern field with the case fold of the text, so a test for `error` matches
+     * `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
+     * and `contains`.
+     */
+    caseFold?: boolean;
+};
 /**
- * Every code that the caller's own side raises, where a request never reaches
- * a server, or where the caller cannot read the answer.
+ * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
+ * `enum[]`, `verbatim[]`, or `string[]` field.
  *
- * The HTTP client raises the first five. The React bindings raise
- * `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. No
- * server sends any of them, so a failure under one means the exchange broke
- * before the operation ran. `STATUS_BY_CODE` in `src/server/errors.ts`
- * therefore maps none of them, because no request can arrive under one and no
- * HTTP status belongs to one.
+ * The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
+ * field, for a value whose type differs from the type of the list's elements,
+ * and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
+ * out `pattern`.
  *
  * @public
  */
-declare const ClientErrorCodes: {
-    readonly CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED";
-    readonly CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT";
-    readonly CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED";
-    readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
-    readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
-    readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
+type ArrayFilter = {
+    /** This matches a list holding every one of the values, at most 65,536 of them, so an empty set of values matches every list. */
+    containsAll?: (string | number | boolean)[];
+    /** This matches a list holding at least one of the values, at most 65,536 of them. */
+    matchesAny?: (string | number | boolean)[];
+    /** This compares the number of elements in the list. */
+    size?: ComparisonFilter;
 };
 /**
- * Any one of the codes in {@link ClientErrorCodes}.
+ * Tests whether a field carries a value at all, without looking at what it
+ * holds.
  *
  * @public
  */
-type ClientErrorCode = (typeof ClientErrorCodes)[keyof typeof ClientErrorCodes];
+type PresenceFilter = {
+    /** This matches a document where the field holds a value other than null. */
+    exists?: boolean;
+    /** This matches a document where the field is absent or null. */
+    notExists?: boolean;
+    /** This matches a document where the field is absent, null, an empty string, or an empty list. */
+    isEmpty?: boolean;
+    /** This matches a document where the field holds a value other than an empty string or an empty list. */
+    isNotEmpty?: boolean;
+};
 /**
- * Every code a {@link NarsilError} can carry: one the engine raised, one the
- * HTTP layer raised, one the client raised, or any other string.
- *
- * The last arm exists for a server's `onRequest` hook, which rejects a request
- * under a code of its own, such as `UNAUTHORIZED`, and the client then passes
- * that code through unchanged. An editor still completes every code Narsil
- * defines.
+ * Matches a `geopoint` field against a circle drawn on the earth.
  *
  * @public
  */
-type NarsilErrorCode = ErrorCode | ServerErrorCode | ClientErrorCode | (string & {});
-/**
- * The error every part of the engine throws.
+type GeoRadiusFilter = {
+    /** The engine tests the field against this circle. */
+    radius: {
+        /** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
+        lat: number;
+        /** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
+        lon: number;
+        /** The circle has this radius, measured in `unit`. */
+        distance: number;
+        /**
+         * The engine measures `distance` in kilometres under `'km'`, in miles
+         * under `'mi'`, and in metres under `'m'`. For any other unit, it throws
+         * `SEARCH_INVALID_FILTER`.
+         */
+        unit: 'km' | 'mi' | 'm';
+        /** The engine matches the points inside the circle while this is true, which is the default, and the points outside it while this is false. */
+        inside?: boolean;
+        /**
+         * The engine measures each distance with the Haversine formula on a sphere
+         * by default, and with Vincenty's formula on the WGS-84 ellipsoid while
+         * this is true. Vincenty's formula iterates, so the engine takes longer
+         * to compute each distance. The two formulas differ by less than 0.3% under about
+         * 100 km, while across a continent they can differ by up to 0.5%.
+         */
+        highPrecision?: boolean;
+    };
+};
+/**
+ * Matches a `geopoint` field against a polygon drawn on the earth.
  *
- * Catch it, read {@link NarsilError.code} to decide what to do, and read
- * {@link NarsilError.details} for the values that caused it. The engine lets
- * this error propagate unchanged, so the code you catch is the code the
- * failing operation raised.
+ * @public
+ */
+type GeoPolygonFilter = {
+    /** The engine tests the field against this polygon. */
+    polygon: {
+        /**
+         * The engine closes the ring through these corners in the order that you
+         * list them, so you can leave the first point off the end. It throws
+         * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
+         * encloses no area, and for a corner whose latitude is outside -90 to 90
+         * or whose longitude is outside -180 to 180. It also throws that error for
+         * a ring of more than 65,536 corners. List the corners counter-clockwise
+         * around the area, as in an exterior ring of GeoJSON. Where the corners
+         * span 180 degrees of longitude or more, the engine matches the area on
+         * the left of that path, so a ring listed that way can cross the
+         * antimeridian or span more than half the globe.
+         */
+        points: Array<{
+            lat: number;
+            lon: number;
+        }>;
+        /** The engine matches the points inside the polygon while this is true, which is the default, and the points outside it while this is false. */
+        inside?: boolean;
+    };
+};
+/**
+ * Either shape a `geopoint` field is matched against.
  *
  * @public
  */
-declare class NarsilError extends Error {
-    /** This says which failure it is. */
-    readonly code: NarsilErrorCode;
-    /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
-    readonly details: Record<string, unknown>;
-    /**
-     * Builds an error carrying a code the caller can branch on.
-     *
-     * @param code - The failure this error reports, from {@link ErrorCodes} for
-     * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
-     * or {@link ClientErrorCodes} for one that stopped a request from reaching a
-     * server.
-     * @param message - Plain description, for a log or a person.
-     * @param details - Values behind the failure, which reach
-     * {@link NarsilError.details}.
-     */
-    constructor(code: NarsilErrorCode, message: string, details?: Record<string, unknown>);
-}
+type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
 /**
- * Reports whether a caught value is a {@link NarsilError}, including one that
- * another entry point of this package raises.
+ * The filter one field accepts. Which of these forms applies follows from the
+ * field's declared type.
  *
- * Each browser bundle holds its own copy of the class, so an `instanceof` test
- * inside the React bindings returns false for an error that the client raises,
- * although that error still holds its code. This function tests for the marker
- * that the constructor writes, so it returns true for an error from any entry
- * point.
+ * @public
+ */
+type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
+/**
+ * The filter that a query runs, built from per-field tests and the boolean
+ * operators that combine them.
  *
- * @param value - The value that a `catch` block receives.
- * @returns True where the value holds a code in {@link NarsilError.code}.
+ * The engine answers every test from an index that it keeps for the field. It
+ * applies the filter before scoring, so a narrow filter makes a search
+ * cheaper. A filter nests at most 30 levels deep and holds at most 1,024
+ * tests, counted across every field and nested expression. Past either limit,
+ * the engine throws `SEARCH_INVALID_FILTER`, while it throws
+ * `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
  *
  * @public
  */
-declare function isNarsilError(value: unknown): value is NarsilError;
+type FilterExpression = {
+    /** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
+    fields?: Record<string, FieldFilter>;
+    /** Every nested expression has to match. */
+    and?: FilterExpression[];
+    /** At least one nested expression has to match. */
+    or?: FilterExpression[];
+    /** The nested expression has to fail. */
+    not?: FilterExpression;
+};
 
 /**
- * This map lists every event that the engine emits, with the payload of each
- * one.
+ * Everything {@link Narsil.suggest} accepts.
  *
- * {@link Narsil.on} registers a listener under a key from this map, so that the
- * engine can pass the matching payload to that listener. Most of these events
- * report work that the engine does in the background, away from the call that
- * started it, so a failure that such an event reports never rejects a promise
- * that you are holding.
+ * @public
+ */
+interface SuggestParams {
+    /** The returned terms complete this text. */
+    prefix: string;
+    /** The lookup returns this many completions, most widely used first, and 10 by default. */
+    limit?: number;
+}
+/**
+ * Everything {@link Narsil.listDocuments} accepts.
+ *
+ * {@link Narsil.listDocuments} reads the stored documents without ranking them,
+ * which is how you page through a whole index. Leave `cursor` out to start at
+ * the first document, then pass back the cursor each result carries until it
+ * comes back null.
+ *
+ * A cursor belongs to the sort it was made under, so pass the same `sort` back
+ * with it. Changing `sort` invalidates the cursor, and the engine then throws
+ * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
  *
  * @public
  */
-type NarsilEventMap = {
+interface ListParams {
     /**
-     * The engine emits this event after a call changes what a read returns from
-     * an index. The calls are the inserts, updates, and removals, singly or in a
-     * batch, together with `clear`, `restore`, `rebalance`, `rebuildAnalysis`,
-     * `compactVectors`, `optimizeVectors`, `createIndex`, and `dropIndex`. The
-     * engine emits the event after a call that throws as well, because a call can
-     * change the index before it throws. It also emits the event after it reloads
-     * an index, once a shared invalidation adapter reports that another instance
-     * saved that index. The engine emits one event per batch, however many
-     * documents the batch holds.
-     *
-     * The engine emits the event once a query can see the change, which means
-     * after every worker copy applies the change and after any rebalance in
-     * progress replays it. A query that a listener sends from its handler
-     * therefore returns results that include the change. The engine waits for the
-     * change to become visible only while a listener is registered for the event.
+     * This cursor comes from a previous result, and continues where it stopped.
+     * The engine ties a cursor to the sort that produced it, and it throws
+     * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
      */
-    write: {
-        /** This is the name of the index that changed. */
-        indexName: string;
-    };
+    cursor?: string;
+    /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
+    limit?: number;
+    /** This narrows the listing to the documents the filter accepts. */
+    filters?: FilterExpression;
     /**
-     * A worker thread exited unexpectedly. The pool removes the thread and fails
-     * the requests that the thread was serving with `WORKER_CRASHED`. The engine
-     * then sends each of those queries again on the main thread, so the caller
-     * receives a result with no error. The remaining workers keep serving
-     * queries, because each of them holds a full worker copy of every promoted
-     * index.
+     * This orders the listing by field value rather than by document id, and the
+     * engine applies the fields in the order they are listed. Pass an object
+     * keyed by field, or a list of fields in the order they apply. It breaks a
+     * tie on document id, and it sorts by at most eight fields. The engine uses
+     * document-id order when you leave this out.
      *
-     * After a delay, the engine spawns a replacement and loads every copy onto
-     * it before it sends queries to the replacement. Once no worker is left, the
-     * main thread serves every query, because it holds every document. The first
-     * request after the delay then starts a new pool. The delay starts at one
-     * second and doubles up to a minute while replacements keep failing.
+     * The engine reads every document the listing covers to build a sorted page,
+     * so a sorted listing costs more than the default order on a large index.
      */
-    workerCrash: {
-        /** This is the id of the worker that exited. */
-        workerId: number;
-        /** These are the indexes that the worker held. */
-        indexNames: string[];
-        /** This is the error that ended the worker. */
-        error: Error;
-    };
-    /** An index gained worker copies, either because it reached the copy
-     * threshold or because a request loaded its copies again after an idle
-     * spell. */
-    workerPromote: {
-        /** This is the number of workers in the pool. */
-        workerCount: number;
-        /** This is the reason that the index gained its copies, such as the copy
-         * threshold that it reached. */
-        reason: string;
-    };
-    /** An index could not gain worker copies, so the main thread keeps serving
-     * its queries. */
-    workerPromoteFailure: {
-        /** This is the reason that the engine tried to load the copies. */
-        reason: string;
-        /** This is the error that stopped the load. */
-        error: Error;
-        /** This is true when the engine will try again at a later threshold. */
-        retryable: boolean;
-    };
-    /** An index finished spreading its documents across a new number of
-     * partitions. */
-    partitionRebalance: {
-        /** This is the name of the index that the engine rebalanced. */
-        indexName: string;
-        /** This is the number of partitions before the rebalance. */
-        oldCount: number;
-        /** This is the number of partitions after the rebalance. */
-        newCount: number;
-    };
+    sort?: SortSpec;
+    /** This chooses how much of each stored document comes back, and the whole document by default. */
+    document?: DocumentProjection;
+}
+
+/**
+ * Which engine answers a query: keyword matching, vector similarity, or both
+ * merged into one ranking.
+ *
+ * @public
+ */
+type SearchMode = 'fulltext' | 'vector' | 'hybrid';
+/**
+ * How many of a query's terms a document has to carry. `all` demands every
+ * term, `any` accepts one, and a number demands that many.
+ *
+ * @public
+ */
+type TermMatchPolicy = 'all' | 'any' | number;
+/**
+ * One field of a sort, and the direction that field orders by.
+ *
+ * @public
+ */
+interface SortField {
+    /** The field the engine reads, which may name a nested field with dots. */
+    field: string;
+    /** Ascending or descending order for this field. */
+    direction: 'asc' | 'desc';
     /**
-     * An index passed its watermark, so its partitions are close to their
-     * capacity. On a cluster node, the engine reports the document count and the
-     * capacity of the one partition that `partitionId` identifies, which this
-     * node leads.
-     */
-    partitionWatermark: {
-        /** This is the name of the index that crossed the mark. */
-        indexName: string;
-        /** This is the number of documents in the index, or in the partition on a
-         * cluster node. */
-        documentCount: number;
-        /** This is the number of documents that the current partitions of the
-         * index can hold, or that the partition can hold on a cluster node. */
-        capacity: number;
-        /** This is the number of partitions in the index. */
-        partitionCount: number;
-        /** On a cluster node, this is the partition that crossed the mark, while
-         * outside a cluster the field is absent. */
-        partitionId?: number;
-    };
-    /**
-     * The process uses nine tenths of its heap, as measured during a write or a
-     * load, so the next large index can end the process with an out-of-memory
-     * error.
-     *
-     * Where `--max-old-space-size` or `--max-old-space-size-percentage` sets a
-     * limit, on the command line or in `NODE_OPTIONS`, the engine measures the
-     * used bytes against that limit, which `heapLimit` then reports. Where
-     * neither flag sets a limit, the engine measures the share of the heap that
-     * V8 reports as no longer available. V8 reports a limit about 192 MB above
-     * the true ceiling, so a process on a default heap below about 2 GB can end before
-     * this event fires.
-     *
-     * The engine emits the event once per crossing, then arms it again once the
-     * free share of the heap recovers to two tenths. Raise the limit with
-     * `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
-     * idle index; see {@link ProcessMemoryReport.heapLimit}.
+     * Where a document's field holds a list, the engine sorts that document by
+     * one value from the list: the smallest under `'min'`, the largest under
+     * `'max'`, and the mean or the median of the list's numbers under `'avg'`
+     * or `'median'`. Where you leave this out, the engine uses `'min'` for an
+     * ascending sort and `'max'` for a descending one. It sorts by a field that
+     * holds a single value as that value stands, under every mode. It throws
+     * `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
+     * schema declares as anything other than `number` or `number[]`.
      */
-    heapPressure: {
-        /** This is the index that a write or a load was touching when the heap
-         * reached that point. */
-        indexName: string;
-        /** This is the heap that the process uses, in bytes. */
-        heapUsed: number;
-        /** This is the size in bytes that the heap can grow to. */
-        heapLimit: number;
-        /** This is the estimate of the bytes that the index holds. */
-        estimatedMemoryBytes: number;
-    };
-    /** The engine started, completed, or failed a rebuild that brings the terms
-     * of an index up to the current analysis of its language module. */
-    analysisRebuild: {
-        /** This is the name of the index under rebuild. */
-        indexName: string;
-        /** This is the stage that the rebuild has reached. */
-        status: 'started' | 'completed' | 'failed';
-        /** This is the number of partitions that the rebuild has covered so far. */
-        partitionsRebuilt: number;
-        /** This is the number of partitions that the rebuild covers in total. */
-        partitionCount: number;
-        /** This is the error that stopped the rebuild, which only a `failed`
-         * status includes. */
-        error?: Error;
-    };
-    /** The engine started, completed, or failed the rewrite of an index that you
-     * saved with an earlier release. The engine rewrites the index as it
-     * recovers it, before it serves the index's first request. Because the
-     * engine writes the new manifest last, the earlier files stay intact through
-     * a failed rewrite. The engine then starts the rewrite again the next time
-     * it recovers the index. Without index lifecycle settings, the engine
-     * recovers every index before {@link createNarsil} returns, so pass the
-     * listener in the `events` setting of {@link createNarsil}. */
-    layoutUpgrade: {
-        /** This is the name of the index under rewrite. */
-        indexName: string;
-        /** This is the stage that the rewrite has reached. */
-        status: 'started' | 'completed' | 'failed';
-        /** This is `manifest` where the earlier index is a segment manifest with
-         * its files, and `bundle` where it is a single snapshot bundle. */
-        layout: 'manifest' | 'bundle';
-        /** This is the error that stopped the rewrite, which only a `failed`
-         * status includes. */
-        error?: Error;
-    };
-    /** A write to the write-ahead log or a checkpoint failed, so the writes since
-     * the last checkpoint are at risk. */
-    durabilityError: {
-        /** This is the error that the durability layer threw. */
-        error: Error;
-    };
-    /** The invalidation channel failed, so this instance can serve partitions
-     * that another instance has since changed. */
-    invalidationError: {
-        /** This is the error that the adapter threw. */
-        error: Error;
-    };
-};
+    mode?: 'min' | 'max' | 'avg' | 'median';
+}
 /**
- * This map holds a listener for any event of {@link NarsilEventMap}, so that
- * the engine can register each listener before it starts.
+ * A sort, either as an object keyed by field or as a list of fields in the
+ * order they apply.
+ *
+ * Both forms order by the first field, break a tie on the second, and carry on
+ * that way. Prefer the list where the order of the fields matters, because
+ * JavaScript moves an all-digit key such as `2024` to the front of an object
+ * and the list keeps the order you wrote.
  *
  * @public
  */
-type NarsilEventHandlers = {
-    [K in keyof NarsilEventMap]?: (payload: NarsilEventMap[K]) => void;
-};
-
+type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
 /**
- * What {@link Narsil.query} returns: the ranked hits and everything the query
- * asked for alongside them.
+ * Everything {@link Narsil.query} accepts.
  *
- * @typeParam T - Shape of the stored documents, which flows through to each
- * hit's `document`.
+ * Set `term` for keyword search, `vector` for similarity search, and `mode`
+ * when you want both. The engine matches nothing for a query carrying neither
+ * of them, so page through an index with {@link Narsil.listDocuments}
+ * instead.
  *
  * @public
  */
-interface QueryResult<T = AnyDocument> {
-    /** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
-    hits: Array<Hit<T>>;
+interface QueryParams {
+    /** The engine analyses this text with the index's language module and searches for the terms that result. */
+    term?: string;
+    /** The engine searches the term in these fields, and in every text field in the schema by default. */
+    fields?: string[];
     /**
-     * This many documents match in total, before the engine applies `limit`
-     * and `offset`. For a keyword search the engine counts every match. For a
-     * vector search it counts every vector that passes the query's filter and
-     * its `similarity` floor, which is every vector in the field where the query
-     * sets neither of them. The engine also counts each pinned document that
-     * the query does not match, since it places that document among the hits.
+     * The engine scores only the documents that pass this filter. It throws
+     * `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
+     * operator on a field of another type, such as `startsWith` on a number
+     * field.
      */
-    count: number;
+    filters?: FilterExpression;
     /**
-     * `count` holds the exact number of matches where this is true, and a
-     * number at or below the true total where it is false. Where a query sets a
-     * `similarity` floor on a vector field that holds a graph, the engine
-     * counts only the vectors that it fetches, because it compares the query
-     * with only a fraction of that field's vectors. For a hybrid query the
-     * engine fuses two rankings, so the count is exact only where each of those
-     * rankings contains every matching document. Where you pin a document from
-     * outside the hits that the engine fetches, the engine reports true only
-     * where it holds every match of the query, because only then can it test
-     * whether the query matches that document.
+     * The engine multiplies the score from each named field by its weight. It
+     * throws `SEARCH_INVALID_FIELD` for any field other than a text field that
+     * the schema declares, and `CONFIG_INVALID` for a weight that is not a
+     * finite number.
      */
-    countExact: boolean;
-    /** The engine spent this many milliseconds on the search. */
-    elapsed: number;
-    /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
-    cursor?: string;
-    /** These facet counts are keyed by the field each facet was asked for. */
-    facets?: Record<string, FacetResult>;
-    /** These groups arrive when the query asked for grouping. */
-    groups?: GroupResult[];
-    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
-    analysisStale?: boolean;
-    /** The search read this much of the index, which is how you spot a degraded answer. */
-    coverage: QueryCoverage;
+    boost?: Record<string, number>;
+    /** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
+    scoring?: ScoringMode;
+    /**
+     * The engine drops any hit scoring below this value. It ranks with BM25,
+     * which has no fixed upper bound, so a floor that suits one index and one
+     * query can reject every hit in another.
+     */
+    minScore?: number;
+    /**
+     * The engine keeps a document only where the document matches this many
+     * query terms, under the same `tolerance` and `prefixLength` that the search
+     * uses. One term is enough by default.
+     */
+    termMatch?: TermMatchPolicy;
+    /**
+     * The engine matches an indexed term within this edit distance of a query
+     * term, so it finds a document for a query with a typo. It counts each
+     * Unicode code point as one character. Set an integer from 0 to 10.
+     */
+    tolerance?: number;
+    /**
+     * The engine applies `tolerance` only to the indexed terms that share this
+     * many leading characters with the query term, or to the terms that start
+     * with the whole query term when the query term is shorter. Set an integer
+     * from 0 to 1,024; the default is 2.
+     */
+    prefixLength?: number;
+    /**
+     * With this set, the engine treats the last query term as an unfinished
+     * word, so `secur` matches `security`. The engine matches that last term by
+     * its stem or by completing it, while `tolerance` applies only to the earlier
+     * terms, which have to match whole. The engine scores completions against a
+     * shared document frequency. It also ranks them below whole-word matches.
+     * The engine ignores this setting where `exact` is true, and the setting is
+     * false by default.
+     */
+    prefix?: boolean;
+    /**
+     * With this set, the engine also matches each query word of three or more
+     * characters inside the longer words of every field whose type includes
+     * `partial`, so a search for `proof` matches a document with `waterproof`
+     * in such a field. The engine counts each Unicode code point as one
+     * character. It looks for the query word, before stemming, inside each word
+     * exactly as that word appears in a document.
+     *
+     * The engine adds at most 50 such words to a query, which it divides as
+     * evenly as it can among the query words. Within the share of each query
+     * word, it adds first the words that the most documents contain. It scores
+     * a match inside a longer word in proportion to the part of that word that
+     * the query word makes up, so it scores such a match below a whole-word
+     * match at the same frequency in a field of the same length. With
+     * `highlight`, it tags each whole word that contains a query word in a
+     * searched `partial` field.
+     *
+     * The engine applies no `tolerance` to these matches. It ignores this
+     * setting where `exact` is true or where the searched fields include no
+     * `partial` field. Where the setting is absent, the engine treats it as
+     * false, while it throws `CONFIG_INVALID` for any value other than `true`
+     * or `false`.
+     */
+    partialWords?: boolean;
+    /**
+     * With this set, the engine matches each query term only against an equal
+     * indexed term, so it turns off fuzzy matching, prefix completion, and
+     * partial-word matching. The engine still stems the query, because the
+     * index stores stemmed terms, so a search for `running` matches a document
+     * that contains `runs` through the stem that both words share.
+     */
+    exact?: boolean;
+    /**
+     * The engine counts the values of these fields across the matching
+     * documents, and each entry sets how it cuts and sorts that field's counts.
+     * For a field outside the schema, it counts the values that the documents
+     * store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
+     * field.
+     */
+    facets?: FacetConfig;
+    /**
+     * The engine sorts the hits by the values of these fields, in place of the
+     * relevance ranking. Pass an object keyed by field, or a list of fields in
+     * the order that the engine compares them. The engine sorts by a `number`,
+     * `boolean`, or `enum` field, by a text field whose type includes
+     * `sortable`, or by a list of any of these, which it reduces to one value by
+     * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
+     * `geopoint` or a vector field, because neither type has an order. It throws
+     * the same code for a sort on any other text field, since the engine keeps
+     * up to the first 512 code points of every document's value in memory to
+     * sort by a text field. The engine orders hybrid results by fusion, so it
+     * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
+     * that code for a direction other than `asc` and `desc`.
+     */
+    sort?: SortSpec;
+    /** These settings collapse the hits into groups by field value. */
+    group?: GroupConfig;
+    /**
+     * The query returns this many hits, and 10 by default. Pass 0 to read the
+     * match count with no hits. The engine reads a value below 0 as 0. It falls
+     * back to the default for `NaN` and for an infinite value, so a page size
+     * that you compute from user input never fails the query.
+     */
+    limit?: number;
+    /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
+    offset?: number;
+    /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
+    searchAfter?: string;
+    /** These settings name the fields that come back with highlighted snippets. */
+    highlight?: HighlightConfig;
+    /** These documents take fixed positions, ahead of the ranking. */
+    pinned?: Array<{
+        docId: string;
+        position: number;
+    }>;
+    /** This picks which engine answers the query. Keyword search runs by default. */
+    mode?: SearchMode;
+    /** These vector-search inputs are required in `vector` and `hybrid` mode. */
+    vector?: VectorQueryConfig;
+    /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
+    hybrid?: HybridConfig;
+    /**
+     * Setting this returns relevance scores on a sorted query. A query that
+     * names a sort ranks by sort values alone and computes no scores, so its
+     * hits carry none until this restores them. A query without a sort ignores
+     * this and always carries scores.
+     */
+    includeScores?: boolean;
+    /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
+    includeScoreComponents?: boolean;
+    /** This chooses how much of each stored document comes back, and the whole document by default. */
+    document?: DocumentProjection;
 }
 /**
- * How much of an index one search read, which is what you check before you
- * trust a count or a ranking.
- *
- * An embedded engine reads every partition it holds, so `queriedPartitions`
- * matches `totalPartitions` there and the other two stay zero. A search across
- * a cluster may find a node slow or unreachable, which it counts here while
- * still returning the hits the other nodes gave it.
+ * How much of a stored document each hit carries back.
  *
- * @public
- */
-interface QueryCoverage {
-    /** The search should have read this many partitions. */
-    totalPartitions: number;
-    /** The search read this many of them. */
-    queriedPartitions: number;
-    /** The search counts a partition here when the node holding it took longer than the query allowed. */
-    timedOutPartitions: number;
-    /** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
-    failedPartitions: number;
-}
-/**
- * One matching document, with the score that ranked it.
+ * Pass `false` when the ids and scores are all you need, and every hit's
+ * `document` is then an empty object. Pass `include` to keep named fields
+ * alone, or `exclude` to drop named fields and keep the rest; naming both
+ * keeps the included fields and then drops the excluded ones from those. Use
+ * dots to name a nested field, so `author.name` addresses the `name` inside
+ * `author`, and a name that matches no field changes nothing.
  *
- * @typeParam T - Shape of the stored document.
+ * Drop a vector field on a similarity search, because the engine otherwise
+ * reads every hit's vector back out of the index and writes it into the
+ * response.
  *
  * @public
  */
-interface Hit<T = AnyDocument> {
-    /** The document is stored under this id. */
-    id: string;
-    /**
-     * This score ranked the hit. Scores compare within one result set, never
-     * across searches. A sorted query ranks by sort values instead and carries
-     * no score unless it sets `includeScores`.
-     */
-    score?: number;
-    /** This is the stored document. */
-    document: T;
-    /** These are the parts the score was built from, which arrive when the query asked for them. */
-    scoreComponents?: ScoreComponents;
-    /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
-    highlights?: Record<string, HighlightMatch>;
-}
+type DocumentProjection = boolean | {
+    /** Names the fields to keep, so every field left out of this list is dropped. */
+    include?: string[];
+    /** Names the fields to drop, so every other field is kept. */
+    exclude?: string[];
+};
 /**
- * The numbers BM25 combined into one hit's score, which is what you read when
- * a ranking surprises you.
+ * Vector-search inputs passed under `QueryParams.vector`.
+ *
+ * Supply either a raw `value` array or a `text` string for auto-embedding;
+ * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
+ * by the outer query's `limit`, not by any field on this object.
  *
  * @public
  */
-interface ScoreComponents {
+interface VectorQueryConfig {
     /**
-     * Each query term appears in one field of this document this many times,
-     * under a key of `field:term`. A term that appears in two fields therefore
-     * has two entries here, while the keys of {@link ScoreComponents.idf} hold
-     * the bare term.
+     * Name of the schema field that holds the vector to compare against.
+     * Must reference a field declared as `vector[N]` in the index schema.
      */
-    termFrequencies: Record<string, number>;
-    /** Each field the query searched holds this many tokens, keyed by field. */
-    fieldLengths: Record<string, number>;
-    /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
-    idf: Record<string, number>;
-}
-/**
- * A highlighted field, ready to render.
- *
- * @public
- */
-interface HighlightMatch {
-    /** This is the field's text around the match, wrapped in the query's tags. */
-    snippet: string;
+    field: string;
     /**
-     * Each range gives the start and the end of one match in the original field,
-     * so you can render the highlight yourself. Where the snippet covers part of
-     * the field alone, the engine lists only the matches that the snippet
-     * displays. Every offset is a character count from the start of the original
-     * field, whatever the snippet contains.
+     * Raw query vector, given as a number array or a `Float32Array`. Length
+     * must match the indexed field's dimension or the search rejects the
+     * request with `VECTOR_DIMENSION_MISMATCH`.
      */
-    positions: Array<{
-        start: number;
-        end: number;
-    }>;
-}
-/**
- * Counts for one faceted field.
- *
- * @public
- */
-interface FacetResult {
-    /** This many documents match per value, keyed by value. */
-    values: Record<string, number>;
-    /** This is the number of entries in `values`, which is at most the facet's `limit`. */
-    count: number;
+    value?: number[] | Float32Array;
     /**
-     * Every count in `values` is at most this far below its true count. A value
-     * that the engine leaves out of `values` because of `limit` has a true
-     * count of at most this figure too. Where the engine counts a field on one
-     * thread, it counts every value exactly, so this figure is the largest
-     * count that it leaves out. Where it splits the count across worker copies
-     * or cluster nodes, each of them returns only its own top values, so the
-     * merged count of a value that is common overall but rare on one of them
-     * can lack the matches on that one. A bound of 0 means that `values` holds
-     * every matching value, each with its exact count.
+     * Text to embed at query time using the index or instance embedding
+     * adapter. Mutually exclusive with `value`; requires a configured adapter.
      */
-    errorBound: number;
-}
-/**
- * One group of hits, produced by a query that grouped its results.
- *
- * @public
- */
-interface GroupResult {
-    /** Each grouping field holds this value for the group, keyed by field. */
-    values: Record<string, unknown>;
-    /** These hits fall in the group, cut to the query's `maxPerGroup`. */
-    hits: Array<Hit>;
-    /** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
-    reduced?: unknown;
-    /** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
-    reducerError?: string;
+    text?: string;
+    /**
+     * Score floor applied during ranking. Hits scoring below this value
+     * are dropped before `limit` is enforced, so the returned hit count
+     * can be smaller than `limit` even when more documents exist. The
+     * floor is interpreted in score space for every metric; for
+     * `euclidean`, distance is mapped to a similarity score of
+     * `1 / (1 + distance)` first. Defaults to no floor.
+     */
+    similarity?: number;
+    /**
+     * Similarity metric used for ranking. Defaults to `cosine`. Choose
+     * `dotProduct` for raw inner-product scoring on already-normalised
+     * vectors and `euclidean` for distance-based ordering.
+     */
+    metric?: 'cosine' | 'dotProduct' | 'euclidean';
+    /**
+     * HNSW exploration factor for approximate search. Higher values raise
+     * recall at the cost of latency. Ignored while the field is still
+     * served by the brute-force backend. Defaults to the engine's built-in
+     * value when omitted.
+     */
+    efSearch?: number;
+    /**
+     * How many times `limit` a quantized field re-scores against its
+     * full-precision vectors before it returns the best `limit`. A value below
+     * 1 or one that is not a finite number fails with `CONFIG_INVALID`. The
+     * engine ignores this on a field whose quantization is `none`. When a query
+     * omits it, the engine takes 3 for `osq1` and `osq2`, 2 for `osq8`, and 2
+     * for `osq4` at 1,024 dimensions and above, but 5 for `osq4` below 1,024,
+     * where a four-bit code ranks the true neighbours less reliably.
+     */
+    oversample?: number;
 }
 /**
- * What {@link Narsil.preflight} returns: how many documents a query matches,
- * without building or ranking a single hit.
+ * How a hybrid query merges its keyword ranking with its vector ranking.
  *
- * @public
- */
-interface PreflightResult {
-    /** The query matches this many documents. */
-    count: number;
-    /** `count` holds the exact number of matches where this is true, and a number at or below the true total where it is false, under the rule in {@link QueryResult.countExact}. */
-    countExact: boolean;
-    /** The count took this many milliseconds. */
-    elapsed: number;
-    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
-    analysisStale?: boolean;
-}
-/**
- * What a batch write returns. One bad document never abandons the rest, so
- * read both lists.
+ * `rrf` combines the two by rank alone, which needs no tuning and handles
+ * scores that live on different scales. `linear` blends the scores directly,
+ * which gives you control once you know what each side's scores look like.
  *
  * @public
  */
-interface BatchResult {
-    /** The engine wrote the documents under these ids. */
-    succeeded: string[];
-    /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
-    failed: Array<{
-        docId: string;
-        error: NarsilError;
-    }>;
+interface HybridConfig {
+    /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
+    strategy?: 'rrf' | 'linear';
+    /** The engine uses this rank-fusion constant under `rrf` alone, where a larger value reduces the lead of the top ranks. Set a whole number of at least 1, or leave it out for 60. The engine throws `CONFIG_INVALID` for any other value. */
+    k?: number;
+    /** The engine uses this weight of the vector score, from 0 to 1, under `linear` alone, and 0.5 where you leave it out. It throws `CONFIG_INVALID` for a value outside that range. */
+    alpha?: number;
 }
 /**
- * What {@link Narsil.importDocumentExport} returns. The engine continues past each
- * refused line, so read the refusals to learn which documents it skipped.
+ * Fields a query counts values for, keyed by field name.
  *
  * @public
  */
-interface DocumentImportResult {
-    /** The engine wrote this many documents, counting each one that it replaced. */
-    imported: number;
-    /** The engine refused this many lines in total. */
-    refusedCount: number;
-    /** These are the 1,000 refusals with the lowest line numbers. Each entry contains the line number, where the header is line 1, along with the error code and a message. */
-    refused: Array<{
-        line: number;
-        code: NarsilErrorCode;
-        message: string;
-    }>;
+interface FacetConfig {
+    /** Each key names a field the query counts values for. */
+    [field: string]: {
+        /** The engine returns this many values for the field, in the order of `sort`. An engine returns every value where you leave this out, while a cluster returns 10, or every range of a field that sets `ranges`. */
+        limit?: number;
+        /** The engine orders the returned values by their count, putting the highest first under `'desc'`, which is the default, and the lowest first under `'asc'`. Under `'asc'`, each cluster node sends the count of up to 10,000 values of the field, so the lowest counts are exact wherever no node holds more values than that. */
+        sort?: 'asc' | 'desc';
+        /** The engine counts a numeric field's matches into these ranges, with one count for each range. A cluster search counts up to 1,000 ranges on a field and throws `CONFIG_INVALID` for more. */
+        ranges?: Array<{
+            from: number;
+            to: number;
+        }>;
+    };
 }
 /**
- * What {@link Narsil.getStats} returns about one index.
+ * How a query collapses its hits into groups.
  *
  * @public
  */
-interface IndexStats {
-    /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
-    documentCount: number;
-    /** The index is spread across this many partitions. */
-    partitionCount: number;
+interface GroupConfig {
+    /** The values of these fields define a group, and several fields group by their combination. */
+    fields: string[];
+    /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
+    maxPerGroup?: number;
+    /** The engine returns this many groups, best first, and every group where you leave this out. */
+    limit?: number;
     /**
-     * Formula-based estimate of the index's main-thread memory footprint, summed
-     * across every partition and vector index for this index. Computed from
-     * structural counters (document count, posting counts, field-index sizes),
-     * not measured. Per-object V8 overhead (hidden classes, map transitions,
-     * GC headers) is not captured here, so this number routinely undershoots
-     * the real heap by a meaningful factor. Use {@link Narsil.getMemoryStats}
-     * when sizing host memory.
-     */
-    estimatedMemoryBytes: number;
-    /** The index analyses text with this language module. */
-    language: string;
-    /** The index was created with this field layout. */
-    schema: SchemaDefinition;
-}
-/**
- * A summary of one index, as {@link Narsil.listIndexes} reports it.
- *
- * @public
- */
-interface IndexInfo {
-    /** The index was created under this name. */
-    name: string;
-    /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
-    documentCount: number;
-    /** The index is spread across this many partitions. */
-    partitionCount: number;
-    /** The index analyses text with this language module. */
-    language: string;
-    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
-    analysisStale?: boolean;
-    /** This is `open` in memory, `closed` after release, and `reopen-failed` after five recovery failures. */
-    state: 'open' | 'closed' | 'reopen-failed';
-    /** This counts successful loads since this engine started. */
-    reopenCount: number;
+     * The engine folds every hit of each group into one value, such as a sum or
+     * an average, including the hits beyond `maxPerGroup`. In cluster mode the
+     * coordinator fetches up to 10,000 hits of each group to fold.
+     */
+    reduce?: GroupReducer;
 }
 /**
- * What {@link Narsil.getPartitionStats} reports for one partition, which is
- * where you look when an index grows unevenly.
+ * Folds the hits of one group into a single value.
  *
  * @public
  */
-interface PartitionStatsResult {
-    /** This identifies the partition within its index. */
-    partitionId: number;
-    /** The partition holds this many documents. */
-    documentCount: number;
+type GroupReducer = {
     /**
-     * Formula-based estimate of this partition's memory footprint. V8 has no
-     * per-object heap accounting API, so this number is derived from structural
-     * counters (document count, posting counts, field-index sizes) and does not
-     * include per-object overhead. Treat as an estimate, not a measurement.
+     * Folds one hit into the running value.
+     *
+     * @param accumulator - What the previous call returned, or what
+     * `initialValue` produced for the first hit.
+     * @param doc - The hit's stored document.
+     * @param score - The hit's relevance score.
+     * @returns The new running value.
      */
-    estimatedMemoryBytes: number;
-}
+    reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
+    /** Produces the starting value for each group. The engine calls it once per group. */
+    initialValue: () => unknown;
+};
 /**
- * What {@link Narsil.suggest} returns: the indexed terms that complete a
- * prefix, ready to offer as you-type suggestions.
+ * This configuration names the fields that receive highlighted snippets. It
+ * also sets how the engine marks those snippets up.
+ *
+ * The engine analyses the text of each returned field again to tag every word
+ * that it matched, so it tags the same words whatever the index's
+ * `trackPositions` setting is. It tags a word whose stem equals a query stem,
+ * and a word within the query's `tolerance` of a query stem. For a `prefix`
+ * query, it tags a word for the last query term only when that word completes
+ * the term or shares its stem.
  *
  * @public
  */
-interface SuggestResult {
-    /** These completions run most widely used first. */
-    terms: Array<{
-        /** This is the completed term, as the index holds it. */
-        term: string;
-        /** The term appears in this many documents, which is what ordered the list. */
-        documentFrequency: number;
-    }>;
-    /** The lookup took this many milliseconds. */
-    elapsed: number;
-    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
-    analysisStale?: boolean;
+interface HighlightConfig {
+    /** The engine highlights these fields. */
+    fields: string[];
+    /** The engine writes this before each match, and writes `<mark>` by default. */
+    preTag?: string;
+    /** The engine writes this after each match, and writes `</mark>` by default. */
+    postTag?: string;
+    /**
+     * The engine takes this many characters of the field around the densest run
+     * of matches, 200 by default. It returns a snippet longer than that number,
+     * because it then adds the opening and closing tags, and an ellipsis at each
+     * end where it cuts the field.
+     */
+    maxSnippetLength?: number;
 }
+
 /**
- * The state of one vector field, and what maintenance would cost, as
- * {@link Narsil.vectorMaintenanceStatus} reports it.
+ * Every code a {@link NarsilError} carries, grouped by the part of the engine
+ * that raises it.
  *
- * Removing a vector leaves a tombstone in the graph, and enough of them slow a
- * search down. Read this to decide when compaction earns its cost.
+ * Match on the code rather than on the message, because a code is stable and a
+ * message is not. The HTTP server maps each code to a status, so a code also
+ * tells you whether the caller or the engine is at fault.
  *
  * @public
  */
-interface VectorMaintenanceResult {
-    /** This describes the named vector field. */
-    fieldName: string;
-    /**
-     * Tombstones make up this share of the graph's nodes, from 0 to 1. Before
-     * the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
-     * the engine divides by the number of stored vectors, because no graph
-     * exists yet.
-     */
-    tombstoneRatio: number;
-    /** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
-    graphCount: number;
-    /** This many vectors wait outside the graph, which a search scans one by one. */
-    bufferSize: number;
-    /** This stays true while a graph build runs. */
-    building: boolean;
-    /** {@link Narsil.compactVectors} would take about this many milliseconds. */
-    estimatedCompactMs: number;
-    /** {@link Narsil.optimizeVectors} would take about this many milliseconds. */
-    estimatedOptimizeMs: number;
-}
+declare const ErrorCodes: {
+    readonly SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE";
+    readonly SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED";
+    readonly SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION";
+    readonly SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT";
+    readonly DOC_NOT_FOUND: "DOC_NOT_FOUND";
+    readonly DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS";
+    readonly DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED";
+    readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
+    readonly INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS";
+    readonly INDEX_ORPHANED: "INDEX_ORPHANED";
+    readonly INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED";
+    readonly INSTANCE_SHUT_DOWN: "INSTANCE_SHUT_DOWN";
+    readonly PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
+    readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
+    readonly WORKER_CRASHED: "WORKER_CRASHED";
+    readonly WORKER_BUSY: "WORKER_BUSY";
+    readonly WORKER_TIMEOUT: "WORKER_TIMEOUT";
+    readonly WORKER_ACTION_FAILED: "WORKER_ACTION_FAILED";
+    readonly PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED";
+    readonly PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED";
+    readonly PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED";
+    readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
+    readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
+    readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
+    readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
+    readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
+    readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
+    readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
+    readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
+    readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
+    readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
+    readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
+    readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
+    readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
+    readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
+    readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
+    readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
+    readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
+    readonly EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID";
+    readonly DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED";
+    readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
+    readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
+    readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
+    readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
+    readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
+    readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
+    readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
+    readonly CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID";
+    readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
+    readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
+    readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
+    readonly NODE_NOT_READY: "NODE_NOT_READY";
+    readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
+    readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
+    readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
+    readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
+    readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
+    readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
+    readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
+    readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
+    readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
+    readonly REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH";
+    readonly REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED";
+    readonly PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY";
+    readonly PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED";
+    readonly INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS";
+    readonly SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED";
+    readonly SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID";
+    readonly SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND";
+    readonly SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED";
+    readonly SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED";
+    readonly SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED";
+    readonly SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID";
+    readonly SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID";
+    readonly SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH";
+    readonly SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER";
+    readonly SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW";
+    readonly SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED";
+    readonly SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING";
+    readonly SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING";
+    readonly SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH";
+    readonly SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR";
+    readonly SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS";
+    readonly SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED";
+    readonly SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE";
+    readonly SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED";
+    readonly SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED";
+    readonly SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT";
+    readonly SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE";
+    readonly SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED";
+    readonly SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED";
+};
 /**
- * One stored document, as {@link Narsil.listDocuments} returns it.
+ * Any one of the codes in {@link ErrorCodes}, which is the type to narrow on
+ * when you branch on a failure the engine raised.
  *
- * @typeParam T - Shape of the stored document.
+ * @public
+ */
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Every code the HTTP layer raises for a failure that arises before or around
+ * the engine call, such as parsing the body, enforcing a limit, or routing.
+ *
+ * The engine raises none of these, so a failure carrying one of them says the
+ * request never reached the engine.
  *
  * @public
  */
-interface ListedDocument<T = AnyDocument> {
-    /** The document is stored under this id. */
-    id: string;
-    /** This holds the stored document, cut down to what the projection kept. */
-    document: T;
-}
+declare const ServerErrorCodes: {
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly INVALID_JSON: "INVALID_JSON";
+    readonly EMPTY_BODY: "EMPTY_BODY";
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
+    readonly TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE";
+    readonly TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE";
+    readonly TASK_INTERRUPTED: "TASK_INTERRUPTED";
+    readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
+    readonly HOOK_ERROR: "HOOK_ERROR";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
 /**
- * What {@link Narsil.listDocuments} returns: one page of stored documents and
- * the cursor that reaches the next one.
+ * Any one of the codes in {@link ServerErrorCodes}.
  *
- * @typeParam T - Shape of the stored documents.
+ * @public
+ */
+type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
+/**
+ * Every code that the caller's own side raises, where a request never reaches
+ * a server, or where the caller cannot read the answer.
+ *
+ * The HTTP client raises the first five. The React bindings raise
+ * `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. No
+ * server sends any of them, so a failure under one means the exchange broke
+ * before the operation ran. `STATUS_BY_CODE` in `src/server/errors.ts`
+ * therefore maps none of them, because no request can arrive under one and no
+ * HTTP status belongs to one.
  *
  * @public
  */
-interface ListResult<T = AnyDocument> {
-    /** These documents make up the page, in ascending document-id order. */
-    documents: Array<ListedDocument<T>>;
-    /** This opaque cursor reaches the next page, and is null once the listing is finished. */
-    cursor: string | null;
-    /** The listing covers this many documents in total, and any filter narrows that count. */
-    total: number;
-    /** The engine spent this many milliseconds building the page. */
-    elapsed: number;
-}
-
+declare const ClientErrorCodes: {
+    readonly CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED";
+    readonly CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT";
+    readonly CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED";
+    readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
+    readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
+    readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
+};
 /**
- * Compares one field against a value. Setting several keys narrows the match,
- * because a document has to satisfy all of them.
+ * Any one of the codes in {@link ClientErrorCodes}.
  *
  * @public
  */
-type ComparisonFilter = {
-    /** This matches a field equal to the value, or a list field where one element equals it. */
-    eq?: number | string | boolean;
-    /**
-     * This matches a document that holds the field with a value other than this
-     * one, or a list field where every element differs from it, which an empty
-     * list does.
-     */
-    ne?: number | string | boolean;
-    /** This matches a field greater than the number. */
-    gt?: number;
-    /** This matches a field less than the number. */
-    lt?: number;
-    /** This matches a field greater than or equal to the number. */
-    gte?: number;
-    /** This matches a field less than or equal to the number. */
-    lte?: number;
-    /** This matches a field inside the inclusive range, given as `[low, high]`. */
-    between?: [number, number];
-};
+type ClientErrorCode = (typeof ClientErrorCodes)[keyof typeof ClientErrorCodes];
 /**
- * The engine tests a text field against this filter for equality, for a text
- * range, or with the set and prefix tests.
+ * Every code a {@link NarsilError} can carry: one the engine raised, one the
+ * HTTP layer raised, one the client raised, or any other string.
  *
- * The engine compares each element of a `string[]`, `verbatim[]`, or `enum[]` field, so
- * it matches a document with `eq`, `in`, `startsWith`, `endsWith`, or
- * `contains` where one element passes the test, while it matches a document
- * with `ne` or `nin` where every element differs from the values.
+ * The last arm exists for a server's `onRequest` hook, which rejects a request
+ * under a code of its own, such as `UNAUTHORIZED`, and the client then passes
+ * that code through unchanged. An editor still completes every code Narsil
+ * defines.
  *
- * The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
- * to a single `string` or `verbatim` field whose type includes `sortable`,
- * while it throws `SEARCH_INVALID_FILTER` for a text range on any other field.
- * It orders the values as a sort on the field does, comparing their case folds
- * first and their raw code points only where the folds are equal.
+ * @public
+ */
+type NarsilErrorCode = ErrorCode | ServerErrorCode | ClientErrorCode | (string & {});
+/**
+ * The error every part of the engine throws.
  *
- * A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
- * `string[]` field whose type includes `pattern`. On such a field, the engine
- * answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`, and `contains`
- * from the field's pattern index. `caseFold` applies to each of those tests.
- * On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
- * `startsWith`, and `endsWith` from the field's index of values. It throws
- * `SEARCH_INVALID_FILTER` for `eq`, `ne`, `in`, `nin`, `startsWith`, or
- * `endsWith` on a `string` or `string[]` field whose type leaves out
- * `pattern`, because such a field keeps no index of whole values.
- * The engine compares the code points of each value as stored, with no
- * Unicode normalisation. It throws `SEARCH_INVALID_FILTER` for `contains` or
- * `caseFold` on any other field, for a test text longer than 1,024 code points
- * on a pattern field, and for a `caseFold` test whose text has a case fold
- * longer than 2,048 code points.
+ * Catch it, read {@link NarsilError.code} to decide what to do, and read
+ * {@link NarsilError.details} for the values that caused it. The engine lets
+ * this error propagate unchanged, so the code you catch is the code the
+ * failing operation raised.
  *
  * @public
  */
-type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
-    /** This matches a value that comes after the text in sort order. */
-    gt?: string;
-    /** This matches a value that comes before the text in sort order. */
-    lt?: string;
-    /** This matches a value equal to the text or after it in sort order. */
-    gte?: string;
-    /** This matches a value equal to the text or before it in sort order. */
-    lte?: string;
-    /** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
-    between?: [string, string];
-    /** This matches a field equal to any value in the list, which holds at most 65,536 values. */
-    in?: string[];
-    /** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
-    nin?: string[];
-    /** This matches a field starting with the text. */
-    startsWith?: string;
-    /** This matches a field ending with the text. */
-    endsWith?: string;
-    /** This matches a pattern field whose value holds the text anywhere in it. */
-    contains?: string;
+declare class NarsilError extends Error {
+    /** This says which failure it is. */
+    readonly code: NarsilErrorCode;
+    /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
+    readonly details: Record<string, unknown>;
     /**
-     * When this is true, the engine compares the case fold of each value of a
-     * pattern field with the case fold of the text, so a test for `error` matches
-     * `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
-     * and `contains`.
+     * Builds an error carrying a code the caller can branch on.
+     *
+     * @param code - The failure this error reports, from {@link ErrorCodes} for
+     * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
+     * or {@link ClientErrorCodes} for one that stopped a request from reaching a
+     * server.
+     * @param message - Plain description, for a log or a person.
+     * @param details - Values behind the failure, which reach
+     * {@link NarsilError.details}.
      */
-    caseFold?: boolean;
-};
+    constructor(code: NarsilErrorCode, message: string, details?: Record<string, unknown>);
+}
 /**
- * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
- * `enum[]`, `verbatim[]`, or `string[]` field.
+ * Reports whether a caught value is a {@link NarsilError}, including one that
+ * another entry point of this package raises.
  *
- * The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
- * field, for a value whose type differs from the type of the list's elements,
- * and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
- * out `pattern`.
+ * Each browser bundle holds its own copy of the class, so an `instanceof` test
+ * inside the React bindings returns false for an error that the client raises,
+ * although that error still holds its code. This function tests for the marker
+ * that the constructor writes, so it returns true for an error from any entry
+ * point.
  *
- * @public
- */
-type ArrayFilter = {
-    /** This matches a list holding every one of the values, at most 65,536 of them, so an empty set of values matches every list. */
-    containsAll?: (string | number | boolean)[];
-    /** This matches a list holding at least one of the values, at most 65,536 of them. */
-    matchesAny?: (string | number | boolean)[];
-    /** This compares the number of elements in the list. */
-    size?: ComparisonFilter;
-};
-/**
- * Tests whether a field carries a value at all, without looking at what it
- * holds.
+ * @param value - The value that a `catch` block receives.
+ * @returns True where the value holds a code in {@link NarsilError.code}.
  *
  * @public
  */
-type PresenceFilter = {
-    /** This matches a document where the field holds a value other than null. */
-    exists?: boolean;
-    /** This matches a document where the field is absent or null. */
-    notExists?: boolean;
-    /** This matches a document where the field is absent, null, an empty string, or an empty list. */
-    isEmpty?: boolean;
-    /** This matches a document where the field holds a value other than an empty string or an empty list. */
-    isNotEmpty?: boolean;
-};
+declare function isNarsilError(value: unknown): value is NarsilError;
+
 /**
- * Matches a `geopoint` field against a circle drawn on the earth.
+ * This map lists every event that the engine emits, with the payload of each
+ * one.
+ *
+ * {@link Narsil.on} registers a listener under a key from this map, so that the
+ * engine can pass the matching payload to that listener. Most of these events
+ * report work that the engine does in the background, away from the call that
+ * started it, so a failure that such an event reports never rejects a promise
+ * that you are holding.
  *
  * @public
  */
-type GeoRadiusFilter = {
-    /** The engine tests the field against this circle. */
-    radius: {
-        /** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
-        lat: number;
-        /** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
-        lon: number;
-        /** The circle has this radius, measured in `unit`. */
-        distance: number;
-        /**
-         * The engine measures `distance` in kilometres under `'km'`, in miles
-         * under `'mi'`, and in metres under `'m'`. For any other unit, it throws
-         * `SEARCH_INVALID_FILTER`.
-         */
-        unit: 'km' | 'mi' | 'm';
-        /** The engine matches the points inside the circle while this is true, which is the default, and the points outside it while this is false. */
-        inside?: boolean;
-        /**
-         * The engine measures each distance with the Haversine formula on a sphere
-         * by default, and with Vincenty's formula on the WGS-84 ellipsoid while
-         * this is true. Vincenty's formula iterates, so the engine takes longer
-         * to compute each distance. The two formulas differ by less than 0.3% under about
-         * 100 km, while across a continent they can differ by up to 0.5%.
-         */
-        highPrecision?: boolean;
+type NarsilEventMap = {
+    /**
+     * The engine emits this event after a call changes what a read returns from
+     * an index. The calls are the inserts, updates, and removals, singly or in a
+     * batch, together with `clear`, `restore`, `rebalance`, `rebuildAnalysis`,
+     * `compactVectors`, `optimizeVectors`, `createIndex`, and `dropIndex`. The
+     * engine emits the event after a call that throws as well, because a call can
+     * change the index before it throws. It also emits the event after it reloads
+     * an index, once a shared invalidation adapter reports that another instance
+     * saved that index. The engine emits one event per batch, however many
+     * documents the batch holds.
+     *
+     * The engine emits the event once a query can see the change, which means
+     * after every worker copy applies the change and after any rebalance in
+     * progress replays it. A query that a listener sends from its handler
+     * therefore returns results that include the change. The engine waits for the
+     * change to become visible only while a listener is registered for the event.
+     */
+    write: {
+        /** This is the name of the index that changed. */
+        indexName: string;
+    };
+    /**
+     * A worker thread exited unexpectedly. The pool removes the thread and fails
+     * the requests that the thread was serving with `WORKER_CRASHED`. The engine
+     * then sends each of those queries again on the main thread, so the caller
+     * receives a result with no error. The remaining workers keep serving
+     * queries, because each of them holds a full worker copy of every promoted
+     * index.
+     *
+     * After a delay, the engine spawns a replacement and loads every copy onto
+     * it before it sends queries to the replacement. Once no worker is left, the
+     * main thread serves every query, because it holds every document. The first
+     * request after the delay then starts a new pool. The delay starts at one
+     * second and doubles up to a minute while replacements keep failing.
+     */
+    workerCrash: {
+        /** This is the id of the worker that exited. */
+        workerId: number;
+        /** These are the indexes that the worker held. */
+        indexNames: string[];
+        /** This is the error that ended the worker. */
+        error: Error;
+    };
+    /** An index gained worker copies, either because it reached the copy
+     * threshold or because a request loaded its copies again after an idle
+     * spell. */
+    workerPromote: {
+        /** This is the number of workers in the pool. */
+        workerCount: number;
+        /** This is the reason that the index gained its copies, such as the copy
+         * threshold that it reached. */
+        reason: string;
+    };
+    /** An index could not gain worker copies, so the main thread keeps serving
+     * its queries. */
+    workerPromoteFailure: {
+        /** This is the reason that the engine tried to load the copies. */
+        reason: string;
+        /** This is the error that stopped the load. */
+        error: Error;
+        /** This is true when the engine will try again at a later threshold. */
+        retryable: boolean;
+    };
+    /** An index finished spreading its documents across a new number of
+     * partitions. */
+    partitionRebalance: {
+        /** This is the name of the index that the engine rebalanced. */
+        indexName: string;
+        /** This is the number of partitions before the rebalance. */
+        oldCount: number;
+        /** This is the number of partitions after the rebalance. */
+        newCount: number;
+    };
+    /**
+     * An index passed its watermark, so its partitions are close to their
+     * capacity. On a cluster node, the engine reports the document count and the
+     * capacity of the one partition that `partitionId` identifies, which this
+     * node leads.
+     */
+    partitionWatermark: {
+        /** This is the name of the index that crossed the mark. */
+        indexName: string;
+        /** This is the number of documents in the index, or in the partition on a
+         * cluster node. */
+        documentCount: number;
+        /** This is the number of documents that the current partitions of the
+         * index can hold, or that the partition can hold on a cluster node. */
+        capacity: number;
+        /** This is the number of partitions in the index. */
+        partitionCount: number;
+        /** On a cluster node, this is the partition that crossed the mark, while
+         * outside a cluster the field is absent. */
+        partitionId?: number;
+    };
+    /**
+     * The process uses nine tenths of its heap, as measured during a write or a
+     * load, so the next large index can end the process with an out-of-memory
+     * error.
+     *
+     * Where `--max-old-space-size` or `--max-old-space-size-percentage` sets a
+     * limit, on the command line or in `NODE_OPTIONS`, the engine measures the
+     * used bytes against that limit, which `heapLimit` then reports. Where
+     * neither flag sets a limit, the engine measures the share of the heap that
+     * V8 reports as no longer available. V8 reports a limit about 192 MB above
+     * the true ceiling, so a process on a default heap below about 2 GB can end before
+     * this event fires.
+     *
+     * The engine emits the event once per crossing, then arms it again once the
+     * free share of the heap recovers to two tenths. Raise the limit with
+     * `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
+     * idle index; see {@link ProcessMemoryReport.heapLimit}.
+     */
+    heapPressure: {
+        /** This is the index that a write or a load was touching when the heap
+         * reached that point. */
+        indexName: string;
+        /** This is the heap that the process uses, in bytes. */
+        heapUsed: number;
+        /** This is the size in bytes that the heap can grow to. */
+        heapLimit: number;
+        /** This is the estimate of the bytes that the index holds. */
+        estimatedMemoryBytes: number;
+    };
+    /** The engine started, completed, or failed a rebuild that brings the terms
+     * of an index up to the current analysis of its language module. */
+    analysisRebuild: {
+        /** This is the name of the index under rebuild. */
+        indexName: string;
+        /** This is the stage that the rebuild has reached. */
+        status: 'started' | 'completed' | 'failed';
+        /** This is the number of partitions that the rebuild has covered so far. */
+        partitionsRebuilt: number;
+        /** This is the number of partitions that the rebuild covers in total. */
+        partitionCount: number;
+        /** This is the error that stopped the rebuild, which only a `failed`
+         * status includes. */
+        error?: Error;
+    };
+    /** The engine started, completed, or failed the rewrite of an index that you
+     * saved with an earlier release. The engine rewrites the index as it
+     * recovers it, before it serves the index's first request. Because the
+     * engine writes the new manifest last, the earlier files stay intact through
+     * a failed rewrite. The engine then starts the rewrite again the next time
+     * it recovers the index. Without index lifecycle settings, the engine
+     * recovers every index before {@link createNarsil} returns, so pass the
+     * listener in the `events` setting of {@link createNarsil}. */
+    layoutUpgrade: {
+        /** This is the name of the index under rewrite. */
+        indexName: string;
+        /** This is the stage that the rewrite has reached. */
+        status: 'started' | 'completed' | 'failed';
+        /** This is `manifest` where the earlier index is a segment manifest with
+         * its files, and `bundle` where it is a single snapshot bundle. */
+        layout: 'manifest' | 'bundle';
+        /** This is the error that stopped the rewrite, which only a `failed`
+         * status includes. */
+        error?: Error;
+    };
+    /** A write to the write-ahead log or a checkpoint failed, so the writes since
+     * the last checkpoint are at risk. */
+    durabilityError: {
+        /** This is the error that the durability layer threw. */
+        error: Error;
+    };
+    /** The invalidation channel failed, so this instance can serve partitions
+     * that another instance has since changed. */
+    invalidationError: {
+        /** This is the error that the adapter threw. */
+        error: Error;
     };
 };
 /**
- * Matches a `geopoint` field against a polygon drawn on the earth.
+ * This map holds a listener for any event of {@link NarsilEventMap}, so that
+ * the engine can register each listener before it starts.
  *
  * @public
  */
-type GeoPolygonFilter = {
-    /** The engine tests the field against this polygon. */
-    polygon: {
-        /**
-         * The engine closes the ring through these corners in the order that you
-         * list them, so you can leave the first point off the end. It throws
-         * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
-         * encloses no area, and for a corner whose latitude is outside -90 to 90
-         * or whose longitude is outside -180 to 180. It also throws that error for
-         * a ring of more than 65,536 corners. List the corners counter-clockwise
-         * around the area, as in an exterior ring of GeoJSON. Where the corners
-         * span 180 degrees of longitude or more, the engine matches the area on
-         * the left of that path, so a ring listed that way can cross the
-         * antimeridian or span more than half the globe.
-         */
-        points: Array<{
-            lat: number;
-            lon: number;
-        }>;
-        /** The engine matches the points inside the polygon while this is true, which is the default, and the points outside it while this is false. */
-        inside?: boolean;
-    };
+type NarsilEventHandlers = {
+    [K in keyof NarsilEventMap]?: (payload: NarsilEventMap[K]) => void;
 };
+
 /**
- * Either shape a `geopoint` field is matched against.
+ * What {@link Narsil.query} returns: the ranked hits and everything the query
+ * asked for alongside them.
  *
- * @public
- */
-type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
-/**
- * The filter one field accepts. Which of these forms applies follows from the
- * field's declared type.
+ * @typeParam T - Shape of the stored documents, which flows through to each
+ * hit's `document`.
  *
  * @public
  */
-type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
+interface QueryResult<T = AnyDocument> {
+    /** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
+    hits: Array<Hit<T>>;
+    /**
+     * This many documents match in total, before the engine applies `limit`
+     * and `offset`. For a keyword search the engine counts every match. For a
+     * vector search it counts every vector that passes the query's filter and
+     * its `similarity` floor, which is every vector in the field where the query
+     * sets neither of them. The engine also counts each pinned document that
+     * the query does not match, since it places that document among the hits.
+     */
+    count: number;
+    /**
+     * `count` holds the exact number of matches where this is true, and a
+     * number at or below the true total where it is false. Where a query sets a
+     * `similarity` floor on a vector field that holds a graph, the engine
+     * counts only the vectors that it fetches, because it compares the query
+     * with only a fraction of that field's vectors. For a hybrid query the
+     * engine fuses two rankings, so the count is exact only where each of those
+     * rankings contains every matching document. Where you pin a document from
+     * outside the hits that the engine fetches, the engine reports true only
+     * where it holds every match of the query, because only then can it test
+     * whether the query matches that document.
+     */
+    countExact: boolean;
+    /** The engine spent this many milliseconds on the search. */
+    elapsed: number;
+    /** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
+    cursor?: string;
+    /** These facet counts are keyed by the field each facet was asked for. */
+    facets?: Record<string, FacetResult>;
+    /** These groups arrive when the query asked for grouping. */
+    groups?: GroupResult[];
+    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
+    analysisStale?: boolean;
+    /** The search read this much of the index, which is how you spot a degraded answer. */
+    coverage: QueryCoverage;
+}
 /**
- * The filter that a query runs, built from per-field tests and the boolean
- * operators that combine them.
- *
- * The engine answers every test from an index that it keeps for the field. It
- * applies the filter before scoring, so a narrow filter makes a search
- * cheaper. A filter nests at most 30 levels deep and holds at most 1,024
- * tests, counted across every field and nested expression. Past either limit,
- * the engine throws `SEARCH_INVALID_FILTER`, while it throws
- * `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
+ * How much of an index one search read, which is what you check before you
+ * trust a count or a ranking.
  *
- * @public
- */
-type FilterExpression = {
-    /** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
-    fields?: Record<string, FieldFilter>;
-    /** Every nested expression has to match. */
-    and?: FilterExpression[];
-    /** At least one nested expression has to match. */
-    or?: FilterExpression[];
-    /** The nested expression has to fail. */
-    not?: FilterExpression;
-};
-
-/**
- * Everything {@link Narsil.suggest} accepts.
+ * An embedded engine reads every partition it holds, so `queriedPartitions`
+ * matches `totalPartitions` there and the other two stay zero. A search across
+ * a cluster may find a node slow or unreachable, which it counts here while
+ * still returning the hits the other nodes gave it.
  *
  * @public
  */
-interface SuggestParams {
-    /** The returned terms complete this text. */
-    prefix: string;
-    /** The lookup returns this many completions, most widely used first, and 10 by default. */
-    limit?: number;
+interface QueryCoverage {
+    /** The search should have read this many partitions. */
+    totalPartitions: number;
+    /** The search read this many of them. */
+    queriedPartitions: number;
+    /** The search counts a partition here when the node holding it took longer than the query allowed. */
+    timedOutPartitions: number;
+    /** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
+    failedPartitions: number;
 }
 /**
- * Everything {@link Narsil.listDocuments} accepts.
- *
- * {@link Narsil.listDocuments} reads the stored documents without ranking them,
- * which is how you page through a whole index. Leave `cursor` out to start at
- * the first document, then pass back the cursor each result carries until it
- * comes back null.
+ * One matching document, with the score that ranked it.
  *
- * A cursor belongs to the sort it was made under, so pass the same `sort` back
- * with it. Changing `sort` invalidates the cursor, and the engine then throws
- * `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
+ * @typeParam T - Shape of the stored document.
  *
  * @public
  */
-interface ListParams {
-    /**
-     * This cursor comes from a previous result, and continues where it stopped.
-     * The engine ties a cursor to the sort that produced it, and it throws
-     * `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
-     */
-    cursor?: string;
-    /** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
-    limit?: number;
-    /** This narrows the listing to the documents the filter accepts. */
-    filters?: FilterExpression;
+interface Hit<T = AnyDocument> {
+    /** The document is stored under this id. */
+    id: string;
     /**
-     * This orders the listing by field value rather than by document id, and the
-     * engine applies the fields in the order they are listed. Pass an object
-     * keyed by field, or a list of fields in the order they apply. It breaks a
-     * tie on document id, and it sorts by at most eight fields. The engine uses
-     * document-id order when you leave this out.
-     *
-     * The engine reads every document the listing covers to build a sorted page,
-     * so a sorted listing costs more than the default order on a large index.
+     * This score ranked the hit. Scores compare within one result set, never
+     * across searches. A sorted query ranks by sort values instead and carries
+     * no score unless it sets `includeScores`.
      */
-    sort?: SortSpec;
-    /** This chooses how much of each stored document comes back, and the whole document by default. */
-    document?: DocumentProjection;
+    score?: number;
+    /** This is the stored document. */
+    document: T;
+    /** These are the parts the score was built from, which arrive when the query asked for them. */
+    scoreComponents?: ScoreComponents;
+    /** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
+    highlights?: Record<string, HighlightMatch>;
 }
-
 /**
- * Which engine answers a query: keyword matching, vector similarity, or both
- * merged into one ranking.
+ * The numbers BM25 combined into one hit's score, which is what you read when
+ * a ranking surprises you.
  *
  * @public
  */
-type SearchMode = 'fulltext' | 'vector' | 'hybrid';
+interface ScoreComponents {
+    /**
+     * Each query term appears in one field of this document this many times,
+     * under a key of `field:term`. A term that appears in two fields therefore
+     * has two entries here, while the keys of {@link ScoreComponents.idf} hold
+     * the bare term.
+     */
+    termFrequencies: Record<string, number>;
+    /** Each field the query searched holds this many tokens, keyed by field. */
+    fieldLengths: Record<string, number>;
+    /** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
+    idf: Record<string, number>;
+}
 /**
- * How many of a query's terms a document has to carry. `all` demands every
- * term, `any` accepts one, and a number demands that many.
+ * A highlighted field, ready to render.
  *
  * @public
  */
-type TermMatchPolicy = 'all' | 'any' | number;
+interface HighlightMatch {
+    /** This is the field's text around the match, wrapped in the query's tags. */
+    snippet: string;
+    /**
+     * Each range gives the start and the end of one match in the original field,
+     * so you can render the highlight yourself. Where the snippet covers part of
+     * the field alone, the engine lists only the matches that the snippet
+     * displays. Every offset is a character count from the start of the original
+     * field, whatever the snippet contains.
+     */
+    positions: Array<{
+        start: number;
+        end: number;
+    }>;
+}
 /**
- * One field of a sort, and the direction that field orders by.
+ * Counts for one faceted field.
  *
  * @public
  */
-interface SortField {
-    /** The field the engine reads, which may name a nested field with dots. */
-    field: string;
-    /** Ascending or descending order for this field. */
-    direction: 'asc' | 'desc';
+interface FacetResult {
+    /** This many documents match per value, keyed by value. */
+    values: Record<string, number>;
+    /** This is the number of entries in `values`, which is at most the facet's `limit`. */
+    count: number;
     /**
-     * Where a document's field holds a list, the engine sorts that document by
-     * one value from the list: the smallest under `'min'`, the largest under
-     * `'max'`, and the mean or the median of the list's numbers under `'avg'`
-     * or `'median'`. Where you leave this out, the engine uses `'min'` for an
-     * ascending sort and `'max'` for a descending one. It sorts by a field that
-     * holds a single value as that value stands, under every mode. It throws
-     * `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
-     * schema declares as anything other than `number` or `number[]`.
+     * Every count in `values` is at most this far below its true count. A value
+     * that the engine leaves out of `values` because of `limit` has a true
+     * count of at most this figure too. Where the engine counts a field on one
+     * thread, it counts every value exactly, so this figure is the largest
+     * count that it leaves out. Where it splits the count across worker copies
+     * or cluster nodes, each of them returns only its own top values, so the
+     * merged count of a value that is common overall but rare on one of them
+     * can lack the matches on that one. A bound of 0 means that `values` holds
+     * every matching value, each with its exact count.
      */
-    mode?: 'min' | 'max' | 'avg' | 'median';
+    errorBound: number;
 }
 /**
- * A sort, either as an object keyed by field or as a list of fields in the
- * order they apply.
- *
- * Both forms order by the first field, break a tie on the second, and carry on
- * that way. Prefer the list where the order of the fields matters, because
- * JavaScript moves an all-digit key such as `2024` to the front of an object
- * and the list keeps the order you wrote.
+ * One group of hits, produced by a query that grouped its results.
  *
  * @public
  */
-type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
+interface GroupResult {
+    /** Each grouping field holds this value for the group, keyed by field. */
+    values: Record<string, unknown>;
+    /** These hits fall in the group, cut to the query's `maxPerGroup`. */
+    hits: Array<Hit>;
+    /** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
+    reduced?: unknown;
+    /** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
+    reducerError?: string;
+}
 /**
- * Everything {@link Narsil.query} accepts.
+ * What {@link Narsil.preflight} returns: how many documents a query matches,
+ * without building or ranking a single hit.
  *
- * Set `term` for keyword search, `vector` for similarity search, and `mode`
- * when you want both. The engine matches nothing for a query carrying neither
- * of them, so page through an index with {@link Narsil.listDocuments}
- * instead.
+ * @public
+ */
+interface PreflightResult {
+    /** The query matches this many documents. */
+    count: number;
+    /** `count` holds the exact number of matches where this is true, and a number at or below the true total where it is false, under the rule in {@link QueryResult.countExact}. */
+    countExact: boolean;
+    /** The count took this many milliseconds. */
+    elapsed: number;
+    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
+    analysisStale?: boolean;
+}
+/**
+ * What a batch write returns. One bad document never abandons the rest, so
+ * read both lists.
  *
  * @public
  */
-interface QueryParams {
-    /** The engine analyses this text with the index's language module and searches for the terms that result. */
-    term?: string;
-    /** The engine searches the term in these fields, and in every text field in the schema by default. */
-    fields?: string[];
-    /**
-     * The engine scores only the documents that pass this filter. It throws
-     * `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
-     * operator on a field of another type, such as `startsWith` on a number
-     * field.
-     */
-    filters?: FilterExpression;
-    /**
-     * The engine multiplies the score from each named field by its weight. It
-     * throws `SEARCH_INVALID_FIELD` for any field other than a text field that
-     * the schema declares, and `CONFIG_INVALID` for a weight that is not a
-     * finite number.
-     */
-    boost?: Record<string, number>;
-    /** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
-    scoring?: ScoringMode;
-    /**
-     * The engine drops any hit scoring below this value. It ranks with BM25,
-     * which has no fixed upper bound, so a floor that suits one index and one
-     * query can reject every hit in another.
-     */
-    minScore?: number;
-    /**
-     * The engine keeps a document only where the document matches this many
-     * query terms, under the same `tolerance` and `prefixLength` that the search
-     * uses. One term is enough by default.
-     */
-    termMatch?: TermMatchPolicy;
-    /**
-     * The engine matches an indexed term within this edit distance of a query
-     * term, so it finds a document for a query with a typo. It counts each
-     * Unicode code point as one character. Set an integer from 0 to 10.
-     */
-    tolerance?: number;
-    /**
-     * The engine applies `tolerance` only to the indexed terms that share this
-     * many leading characters with the query term, or to the terms that start
-     * with the whole query term when the query term is shorter. Set an integer
-     * from 0 to 1,024; the default is 2.
-     */
-    prefixLength?: number;
-    /**
-     * With this set, the engine treats the last query term as an unfinished
-     * word, so `secur` matches `security`. The engine matches that last term by
-     * its stem or by completing it, while `tolerance` applies only to the earlier
-     * terms, which have to match whole. The engine scores completions against a
-     * shared document frequency. It also ranks them below whole-word matches.
-     * The engine ignores this setting where `exact` is true, and the setting is
-     * false by default.
-     */
-    prefix?: boolean;
-    /**
-     * Setting this makes the engine match each query term only against an equal
-     * indexed term, which turns off fuzzy matching and prefix completion. The
-     * engine still stems the query, because the index stores stemmed terms, so
-     * `running` matches a document that holds `runs` through their shared stem.
-     */
-    exact?: boolean;
-    /**
-     * The engine counts the values of these fields across the matching
-     * documents, and each entry sets how it cuts and sorts that field's counts.
-     * For a field outside the schema, it counts the values that the documents
-     * store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
-     * field.
-     */
-    facets?: FacetConfig;
-    /**
-     * The engine sorts the hits by the values of these fields, in place of the
-     * relevance ranking. Pass an object keyed by field, or a list of fields in
-     * the order that the engine compares them. The engine sorts by a `number`,
-     * `boolean`, or `enum` field, by a text field whose type includes
-     * `sortable`, or by a list of any of these, which it reduces to one value by
-     * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
-     * `geopoint` or a vector field, because neither type has an order. It throws
-     * the same code for a sort on any other text field, since the engine keeps
-     * up to the first 512 code points of every document's value in memory to
-     * sort by a text field. The engine orders hybrid results by fusion, so it
-     * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
-     * that code for a direction other than `asc` and `desc`.
-     */
-    sort?: SortSpec;
-    /** These settings collapse the hits into groups by field value. */
-    group?: GroupConfig;
-    /**
-     * The query returns this many hits, and 10 by default. Pass 0 to read the
-     * match count with no hits. The engine reads a value below 0 as 0. It falls
-     * back to the default for `NaN` and for an infinite value, so a page size
-     * that you compute from user input never fails the query.
-     */
-    limit?: number;
-    /** The query skips this many hits before returning. A deep offset costs more than a cursor. */
-    offset?: number;
-    /** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
-    searchAfter?: string;
-    /** These settings name the fields that come back with highlighted snippets. */
-    highlight?: HighlightConfig;
-    /** These documents take fixed positions, ahead of the ranking. */
-    pinned?: Array<{
+interface BatchResult {
+    /** The engine wrote the documents under these ids. */
+    succeeded: string[];
+    /** The engine rejected each of these documents, and each entry carries the error that rejected it. */
+    failed: Array<{
         docId: string;
-        position: number;
+        error: NarsilError;
     }>;
-    /** This picks which engine answers the query. Keyword search runs by default. */
-    mode?: SearchMode;
-    /** These vector-search inputs are required in `vector` and `hybrid` mode. */
-    vector?: VectorQueryConfig;
-    /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
-    hybrid?: HybridConfig;
-    /**
-     * Setting this returns relevance scores on a sorted query. A query that
-     * names a sort ranks by sort values alone and computes no scores, so its
-     * hits carry none until this restores them. A query without a sort ignores
-     * this and always carries scores.
-     */
-    includeScores?: boolean;
-    /** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
-    includeScoreComponents?: boolean;
-    /** This chooses how much of each stored document comes back, and the whole document by default. */
-    document?: DocumentProjection;
 }
 /**
- * How much of a stored document each hit carries back.
- *
- * Pass `false` when the ids and scores are all you need, and every hit's
- * `document` is then an empty object. Pass `include` to keep named fields
- * alone, or `exclude` to drop named fields and keep the rest; naming both
- * keeps the included fields and then drops the excluded ones from those. Use
- * dots to name a nested field, so `author.name` addresses the `name` inside
- * `author`, and a name that matches no field changes nothing.
- *
- * Drop a vector field on a similarity search, because the engine otherwise
- * reads every hit's vector back out of the index and writes it into the
- * response.
+ * What {@link Narsil.importDocumentExport} returns. The engine continues past each
+ * refused line, so read the refusals to learn which documents it skipped.
  *
  * @public
  */
-type DocumentProjection = boolean | {
-    /** Names the fields to keep, so every field left out of this list is dropped. */
-    include?: string[];
-    /** Names the fields to drop, so every other field is kept. */
-    exclude?: string[];
-};
+interface DocumentImportResult {
+    /** The engine wrote this many documents, counting each one that it replaced. */
+    imported: number;
+    /** The engine refused this many lines in total. */
+    refusedCount: number;
+    /** These are the 1,000 refusals with the lowest line numbers. Each entry contains the line number, where the header is line 1, along with the error code and a message. */
+    refused: Array<{
+        line: number;
+        code: NarsilErrorCode;
+        message: string;
+    }>;
+}
 /**
- * Vector-search inputs passed under `QueryParams.vector`.
- *
- * Supply either a raw `value` array or a `text` string for auto-embedding;
- * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
- * by the outer query's `limit`, not by any field on this object.
+ * What {@link Narsil.getStats} returns about one index.
  *
  * @public
  */
-interface VectorQueryConfig {
-    /**
-     * Name of the schema field that holds the vector to compare against.
-     * Must reference a field declared as `vector[N]` in the index schema.
-     */
-    field: string;
-    /**
-     * Raw query vector, given as a number array or a `Float32Array`. Length
-     * must match the indexed field's dimension or the search rejects the
-     * request with `VECTOR_DIMENSION_MISMATCH`.
-     */
-    value?: number[] | Float32Array;
-    /**
-     * Text to embed at query time using the index or instance embedding
-     * adapter. Mutually exclusive with `value`; requires a configured adapter.
-     */
-    text?: string;
-    /**
-     * Score floor applied during ranking. Hits scoring below this value
-     * are dropped before `limit` is enforced, so the returned hit count
-     * can be smaller than `limit` even when more documents exist. The
-     * floor is interpreted in score space for every metric; for
-     * `euclidean`, distance is mapped to a similarity score of
-     * `1 / (1 + distance)` first. Defaults to no floor.
-     */
-    similarity?: number;
-    /**
-     * Similarity metric used for ranking. Defaults to `cosine`. Choose
-     * `dotProduct` for raw inner-product scoring on already-normalised
-     * vectors and `euclidean` for distance-based ordering.
-     */
-    metric?: 'cosine' | 'dotProduct' | 'euclidean';
-    /**
-     * HNSW exploration factor for approximate search. Higher values raise
-     * recall at the cost of latency. Ignored while the field is still
-     * served by the brute-force backend. Defaults to the engine's built-in
-     * value when omitted.
-     */
-    efSearch?: number;
+interface IndexStats {
+    /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
+    documentCount: number;
+    /** The index is spread across this many partitions. */
+    partitionCount: number;
     /**
-     * How many times `limit` a quantized field re-scores against its
-     * full-precision vectors before it returns the best `limit`. A value below
-     * 1 or one that is not a finite number fails with `CONFIG_INVALID`. The
-     * engine ignores this on a field whose quantization is `none`. When a query
-     * omits it, the engine takes 3 for `osq1` and `osq2`, 2 for `osq8`, and 2
-     * for `osq4` at 1,024 dimensions and above, but 5 for `osq4` below 1,024,
-     * where a four-bit code ranks the true neighbours less reliably.
+     * Formula-based estimate of the index's main-thread memory footprint, summed
+     * across every partition and vector index for this index. Computed from
+     * structural counters (document count, posting counts, field-index sizes),
+     * not measured. Per-object V8 overhead (hidden classes, map transitions,
+     * GC headers) is not captured here, so this number routinely undershoots
+     * the real heap by a meaningful factor. Use {@link Narsil.getMemoryStats}
+     * when sizing host memory.
      */
-    oversample?: number;
+    estimatedMemoryBytes: number;
+    /** The index analyses text with this language module. */
+    language: string;
+    /** The index was created with this field layout. */
+    schema: SchemaDefinition;
 }
 /**
- * How a hybrid query merges its keyword ranking with its vector ranking.
+ * A summary of one index, as {@link Narsil.listIndexes} reports it.
  *
- * `rrf` combines the two by rank alone, which needs no tuning and handles
- * scores that live on different scales. `linear` blends the scores directly,
- * which gives you control once you know what each side's scores look like.
+ * @public
+ */
+interface IndexInfo {
+    /** The index was created under this name. */
+    name: string;
+    /** The index holds this many documents. A closed index reports its count as of the last checkpoint. */
+    documentCount: number;
+    /** The index is spread across this many partitions. */
+    partitionCount: number;
+    /** The index analyses text with this language module. */
+    language: string;
+    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
+    analysisStale?: boolean;
+    /** This is `open` in memory, `closed` after release, and `reopen-failed` after five recovery failures. */
+    state: 'open' | 'closed' | 'reopen-failed';
+    /** This counts successful loads since this engine started. */
+    reopenCount: number;
+}
+/**
+ * What {@link Narsil.getPartitionStats} reports for one partition, which is
+ * where you look when an index grows unevenly.
  *
  * @public
  */
-interface HybridConfig {
-    /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
-    strategy?: 'rrf' | 'linear';
-    /** The engine uses this rank-fusion constant under `rrf` alone, where a larger value reduces the lead of the top ranks. Set a whole number of at least 1, or leave it out for 60. The engine throws `CONFIG_INVALID` for any other value. */
-    k?: number;
-    /** The engine uses this weight of the vector score, from 0 to 1, under `linear` alone, and 0.5 where you leave it out. It throws `CONFIG_INVALID` for a value outside that range. */
-    alpha?: number;
+interface PartitionStatsResult {
+    /** This identifies the partition within its index. */
+    partitionId: number;
+    /** The partition holds this many documents. */
+    documentCount: number;
+    /**
+     * Formula-based estimate of this partition's memory footprint. V8 has no
+     * per-object heap accounting API, so this number is derived from structural
+     * counters (document count, posting counts, field-index sizes) and does not
+     * include per-object overhead. Treat as an estimate, not a measurement.
+     */
+    estimatedMemoryBytes: number;
 }
 /**
- * Fields a query counts values for, keyed by field name.
+ * What {@link Narsil.suggest} returns: the indexed terms that complete a
+ * prefix, ready to offer as you-type suggestions.
  *
  * @public
  */
-interface FacetConfig {
-    /** Each key names a field the query counts values for. */
-    [field: string]: {
-        /** The engine returns this many values for the field, in the order of `sort`. An engine returns every value where you leave this out, while a cluster returns 10, or every range of a field that sets `ranges`. */
-        limit?: number;
-        /** The engine orders the returned values by their count, putting the highest first under `'desc'`, which is the default, and the lowest first under `'asc'`. Under `'asc'`, each cluster node sends the count of up to 10,000 values of the field, so the lowest counts are exact wherever no node holds more values than that. */
-        sort?: 'asc' | 'desc';
-        /** The engine counts a numeric field's matches into these ranges, with one count for each range. A cluster search counts up to 1,000 ranges on a field and throws `CONFIG_INVALID` for more. */
-        ranges?: Array<{
-            from: number;
-            to: number;
-        }>;
-    };
+interface SuggestResult {
+    /** These completions run most widely used first. */
+    terms: Array<{
+        /** This is the completed term, as the index holds it. */
+        term: string;
+        /** The term appears in this many documents, which is what ordered the list. */
+        documentFrequency: number;
+    }>;
+    /** The lookup took this many milliseconds. */
+    elapsed: number;
+    /** This turns true when the index's terms came from an older analysis than its language module produces now. */
+    analysisStale?: boolean;
 }
 /**
- * How a query collapses its hits into groups.
+ * The state of one vector field, and what maintenance would cost, as
+ * {@link Narsil.vectorMaintenanceStatus} reports it.
+ *
+ * Removing a vector leaves a tombstone in the graph, and enough of them slow a
+ * search down. Read this to decide when compaction earns its cost.
  *
  * @public
  */
-interface GroupConfig {
-    /** The values of these fields define a group, and several fields group by their combination. */
-    fields: string[];
-    /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
-    maxPerGroup?: number;
-    /** The engine returns this many groups, best first, and every group where you leave this out. */
-    limit?: number;
+interface VectorMaintenanceResult {
+    /** This describes the named vector field. */
+    fieldName: string;
     /**
-     * The engine folds every hit of each group into one value, such as a sum or
-     * an average, including the hits beyond `maxPerGroup`. In cluster mode the
-     * coordinator fetches up to 10,000 hits of each group to fold.
+     * Tombstones make up this share of the graph's nodes, from 0 to 1. Before
+     * the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
+     * the engine divides by the number of stored vectors, because no graph
+     * exists yet.
      */
-    reduce?: GroupReducer;
+    tombstoneRatio: number;
+    /** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
+    graphCount: number;
+    /** This many vectors wait outside the graph, which a search scans one by one. */
+    bufferSize: number;
+    /** This stays true while a graph build runs. */
+    building: boolean;
+    /** {@link Narsil.compactVectors} would take about this many milliseconds. */
+    estimatedCompactMs: number;
+    /** {@link Narsil.optimizeVectors} would take about this many milliseconds. */
+    estimatedOptimizeMs: number;
 }
 /**
- * Folds the hits of one group into a single value.
+ * One stored document, as {@link Narsil.listDocuments} returns it.
+ *
+ * @typeParam T - Shape of the stored document.
  *
  * @public
  */
-type GroupReducer = {
-    /**
-     * Folds one hit into the running value.
-     *
-     * @param accumulator - What the previous call returned, or what
-     * `initialValue` produced for the first hit.
-     * @param doc - The hit's stored document.
-     * @param score - The hit's relevance score.
-     * @returns The new running value.
-     */
-    reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
-    /** Produces the starting value for each group. The engine calls it once per group. */
-    initialValue: () => unknown;
-};
+interface ListedDocument<T = AnyDocument> {
+    /** The document is stored under this id. */
+    id: string;
+    /** This holds the stored document, cut down to what the projection kept. */
+    document: T;
+}
 /**
- * This configuration names the fields that receive highlighted snippets. It
- * also sets how the engine marks those snippets up.
+ * What {@link Narsil.listDocuments} returns: one page of stored documents and
+ * the cursor that reaches the next one.
  *
- * The engine analyses the text of each returned field again to tag every word
- * that it matched, so it tags the same words whatever the index's
- * `trackPositions` setting is. It tags a word whose stem equals a query stem,
- * and a word within the query's `tolerance` of a query stem. For a `prefix`
- * query, it tags a word for the last query term only when that word completes
- * the term or shares its stem.
+ * @typeParam T - Shape of the stored documents.
  *
  * @public
  */
-interface HighlightConfig {
-    /** The engine highlights these fields. */
-    fields: string[];
-    /** The engine writes this before each match, and writes `<mark>` by default. */
-    preTag?: string;
-    /** The engine writes this after each match, and writes `</mark>` by default. */
-    postTag?: string;
-    /**
-     * The engine takes this many characters of the field around the densest run
-     * of matches, 200 by default. It returns a snippet longer than that number,
-     * because it then adds the opening and closing tags, and an ellipsis at each
-     * end where it cuts the field.
-     */
-    maxSnippetLength?: number;
+interface ListResult<T = AnyDocument> {
+    /** These documents make up the page, in ascending document-id order. */
+    documents: Array<ListedDocument<T>>;
+    /** This opaque cursor reaches the next page, and is null once the listing is finished. */
+    cursor: string | null;
+    /** The listing covers this many documents in total, and any filter narrows that count. */
+    total: number;
+    /** The engine spent this many milliseconds building the page. */
+    elapsed: number;
 }
 
 /**