@delali/narsil 0.2.4-next.54 → 0.2.4-next.59

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { b as StopWordOverride, C as CustomTokenizer } from './schema-mLpXZBEh.js';
-export { A as AnyDocument, B as BM25Params, E as EmbeddingFieldConfig, F as FieldType, I as IndexConfig, a as InsertOptions, P as PartitionConfig, S as SchemaDefinition, c as ScoringMode, V as VectorIndexConfig, d as VectorQuantizationMode, e as VectorStorageMode, W as WriteOptions } from './schema-mLpXZBEh.js';
+import { b as StopWordOverride, C as CustomTokenizer } from './schema-d5Afu03A.js';
+export { A as AnyDocument, B as BM25Params, E as EmbeddingFieldConfig, F as FieldType, I as IndexConfig, a as InsertOptions, P as PartitionConfig, S as SchemaDefinition, c as ScoringMode, V as VectorIndexConfig, d as VectorQuantizationMode, e as VectorStorageMode, W as WriteOptions } from './schema-d5Afu03A.js';
 import { L as LanguageModule } from './language-DB8KG1z5.js';
 export { T as TokenizerConfig } from './language-DB8KG1z5.js';
-export { A as ArrayFilter, B as BatchResult, C as ClientErrorCode, a as ClientErrorCodes, l as ComparisonFilter, D as DocumentProjection, E as ErrorCode, b as ErrorCodes, F as FacetConfig, m as FacetResult, n as FieldFilter, o as FilterExpression, G as GeoFilter, p as GeoPolygonFilter, q as GeoRadiusFilter, r as GroupConfig, s as GroupReducer, t as GroupResult, H as HighlightConfig, u as HighlightMatch, v as Hit, w as HybridConfig, I as IndexInfo, f as IndexStats, L as ListParams, g as ListResult, x as ListedDocument, M as MemoryStats, N as NarsilError, c as NarsilErrorCode, P as PartitionStatsResult, h as PreflightResult, y as PresenceFilter, z as ProcessMemoryReport, J as QueryCoverage, Q as QueryParams, e as QueryResult, K as ScoreComponents, O as SearchMode, S as ServerErrorCode, d as ServerErrorCodes, R as SortField, T as SortSpec, U as StringFilter, j as SuggestParams, k as SuggestResult, W as TermMatchPolicy, V as VectorMaintenanceResult, X as VectorQueryConfig, Y as WorkerCopyReport, i as isNarsilError } from './memory-xrXOZMbw.js';
-import { N as NarsilConfig } from './config-bXxnJrQc.js';
-export { A as AnalysisConfig, D as DurabilityConfig, I as IndexContext, a as IndexLifecycleConfig, b as InsertContext, M as MainCopyQueries, c as NarsilPlugin, P as PartitionContext, R as RemoveContext, S as SearchContext, d as StaleAnalysis, U as UpdateContext, W as WorkerConfig, e as WorkerContext } from './config-bXxnJrQc.js';
-import { a as Narsil } from './engine-Dj4I91Jv.js';
-export { D as DocumentWriteOperations, I as IndexLifecycleOperations, N as NarsilEventMap } from './engine-Dj4I91Jv.js';
+export { A as ArrayFilter, B as BatchResult, C as ClientErrorCode, a as ClientErrorCodes, l as ComparisonFilter, D as DocumentProjection, E as ErrorCode, b as ErrorCodes, F as FacetConfig, m as FacetResult, n as FieldFilter, o as FilterExpression, G as GeoFilter, p as GeoPolygonFilter, q as GeoRadiusFilter, r as GroupConfig, s as GroupReducer, t as GroupResult, H as HighlightConfig, u as HighlightMatch, v as Hit, w as HybridConfig, I as IndexInfo, f as IndexStats, L as ListParams, g as ListResult, x as ListedDocument, M as MemoryStats, N as NarsilError, c as NarsilErrorCode, P as PartitionStatsResult, h as PreflightResult, y as PresenceFilter, z as ProcessMemoryReport, J as QueryCoverage, Q as QueryParams, e as QueryResult, K as ScoreComponents, O as SearchMode, S as ServerErrorCode, d as ServerErrorCodes, R as SortField, T as SortSpec, U as StringFilter, j as SuggestParams, k as SuggestResult, W as TermMatchPolicy, V as VectorMaintenanceResult, X as VectorQueryConfig, Y as WorkerCopyReport, i as isNarsilError } from './memory-yFaVn2xZ.js';
+import { N as NarsilConfig } from './config-DmXULPa-.js';
+export { A as AnalysisConfig, D as DurabilityConfig, I as IndexContext, a as IndexLifecycleConfig, b as InsertContext, M as MainCopyQueries, c as NarsilPlugin, P as PartitionContext, R as RemoveContext, S as SearchContext, d as StaleAnalysis, U as UpdateContext, W as WorkerConfig, e as WorkerContext } from './config-DmXULPa-.js';
+import { a as Narsil } from './engine-CIOyFozK.js';
+export { D as DocumentWriteOperations, I as IndexLifecycleOperations, N as NarsilEventMap } from './engine-CIOyFozK.js';
 export { E as EmbeddingAdapter, I as InvalidationAdapter, a as InvalidationEvent, b as PartitionStatistics, P as PersistenceAdapter } from './adapters-79OIa4xm.js';
 export { i as isSimdAvailable } from './simd-DW5AtJ6B.js';
 

package/dist/index.mjs

@@ -1,19 +1,19 @@
-export { VERSION, createNarsil } from './chunk-BH5SYB5W.mjs';
+export { VERSION, createNarsil } from './chunk-24RXHMEL.mjs';
 import './chunk-GCM3JFVA.mjs';
-import './chunk-4NVPQ6S5.mjs';
-export { getLanguage, getStopWords, getTokenizer, hasStopWords, hasTokenizer, registerLanguage, registerStopWords, registerTokenizer } from './chunk-XNQAIO74.mjs';
+import './chunk-UXNWQZST.mjs';
+export { getLanguage, getStopWords, getTokenizer, hasStopWords, hasTokenizer, registerLanguage, registerStopWords, registerTokenizer } from './chunk-ZZT3EAUC.mjs';
 import './chunk-AV4IJKD2.mjs';
-import './chunk-TVT5V4E7.mjs';
-import './chunk-D2S642IV.mjs';
-export { clearNormalizationCache, configureNormalizationCache, getNormalizationCacheSize, resetNormalizationCache } from './chunk-5T6AOR37.mjs';
-import './chunk-L225SHNB.mjs';
+import './chunk-B2TFROFX.mjs';
+import './chunk-3LHGNRYE.mjs';
+export { clearNormalizationCache, configureNormalizationCache, getNormalizationCacheSize, resetNormalizationCache } from './chunk-ZNZBXMP5.mjs';
+import './chunk-L6TNPLAR.mjs';
 import './chunk-TGP5M5R7.mjs';
-export { isSimdAvailable } from './chunk-U2AL3SON.mjs';
+export { isSimdAvailable } from './chunk-THYRHHO2.mjs';
 import './chunk-ZJ4CSAB2.mjs';
-import './chunk-UTOFOJOR.mjs';
+import './chunk-YNVIUGF5.mjs';
 import './chunk-3L4U6EJQ.mjs';
 import './chunk-IFBKLBGB.mjs';
 import './chunk-U2BKYEC7.mjs';
-import './chunk-2GWVQWGA.mjs';
+import './chunk-YMZCMH5M.mjs';
 import './chunk-POWOTUKJ.mjs';
-export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes, isNarsilError } from './chunk-FRQVMFY7.mjs';
+export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes, isNarsilError } from './chunk-USKFU7J5.mjs';

package/dist/invalidation/filesystem.mjs

@@ -1,4 +1,4 @@
-import { compareCodePoints } from '../chunk-2GWVQWGA.mjs';
+import { compareCodePoints } from '../chunk-YMZCMH5M.mjs';
 import { DEFAULT_POLL_INTERVAL_MS, MARKER_MAX_AGE_MS } from '../chunk-YEO6G2NG.mjs';
 
 // src/invalidation/filesystem.ts

package/dist/{memory-xrXOZMbw.d.ts → memory-yFaVn2xZ.d.ts}

@@ -1,4 +1,4 @@
-import { A as AnyDocument, S as SchemaDefinition, c as ScoringMode } from './schema-mLpXZBEh.js';
+import { A as AnyDocument, S as SchemaDefinition, c as ScoringMode } from './schema-d5Afu03A.js';
 
 /**
  * Every code a {@link NarsilError} carries, grouped by the part of the engine
@@ -22,6 +22,7 @@ declare const ErrorCodes: {
     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";
@@ -234,10 +235,30 @@ declare function isNarsilError(value: unknown): value is NarsilError;
  * @public
  */
 interface QueryResult<T = AnyDocument> {
-    /** These documents matched, cut to the query's `limit`, best score first or in the query's sort order. */
+    /** 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 matched in total, before `limit` and `offset` applied. */
+    /**
+     * 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`. */
@@ -340,15 +361,20 @@ interface HighlightMatch {
  * @public
  */
 interface FacetResult {
-    /** This many documents matched per value, keyed by value. */
+    /** This many documents match per value, keyed by value. */
     values: Record<string, number>;
-    /** The field held this many distinct values across the matching documents. */
+    /** This is the number of entries in `values`, which is at most the facet's `limit`. */
     count: number;
     /**
-     * No value's count is short by more than this. Counting runs per partition
-     * and each one reports only its own top values, so a value that is common
-     * overall but ranks low on a partition loses that partition's share. A bound
-     * of 0 means every count here is exact.
+     * 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.
      */
     errorBound: number;
 }
@@ -376,6 +402,8 @@ interface GroupResult {
 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. */
@@ -568,6 +596,10 @@ type ComparisonFilter = {
  * Everything {@link ComparisonFilter} offers, with the set and prefix tests a
  * string field also supports.
  *
+ * On a `string[]` field, the engine compares each element of the list, so
+ * `eq`, `in`, `startsWith`, and `endsWith` match a document where one element
+ * matches, and `ne` and `nin` match a document where no element matches.
+ *
  * @public
  */
 type StringFilter = ComparisonFilter & {
@@ -615,19 +647,29 @@ type PresenceFilter = {
  * @public
  */
 type GeoRadiusFilter = {
-    /** The filter tests the field against this circle. */
+    /** The engine tests the field against this circle. */
     radius: {
         /** The centre has this latitude, in degrees. */
         lat: number;
         /** The centre has this longitude, in degrees. */
         lon: number;
-        /** The circle reaches this far, measured in `unit`. */
+        /** The circle has this radius, measured in `unit`. */
         distance: number;
-        /** `distance` is given in kilometres, miles, or metres. */
+        /**
+         * 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';
-        /** This keeps the points inside the circle. Set it to false to keep the points outside. It is true by default. */
+        /** 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;
-        /** Setting this measures along the earth's curve instead of a flat approximation, which costs time and gains accuracy over long distances. */
+        /**
+         * 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;
     };
 };
@@ -637,14 +679,23 @@ type GeoRadiusFilter = {
  * @public
  */
 type GeoPolygonFilter = {
-    /** The filter tests the field against this polygon. */
+    /** The engine tests the field against this polygon. */
     polygon: {
-        /** These corners run in order. The engine closes the ring, so repeating the first point is unnecessary. */
+        /**
+         * 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, since
+         * such a ring encloses no area. 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;
         }>;
-        /** This keeps the points inside the polygon. Set it to false to keep the points outside. It is true by default. */
+        /** 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;
     };
 };
@@ -681,6 +732,57 @@ type FilterExpression = {
     not?: FilterExpression;
 };
 
+/**
+ * Everything {@link Narsil.suggest} accepts.
+ *
+ * @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
+ */
+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;
+    /**
+     * 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.
+     */
+    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.
@@ -705,6 +807,17 @@ interface SortField {
     field: string;
     /** Ascending or descending order for this field. */
     direction: 'asc' | 'desc';
+    /**
+     * 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[]`.
+     */
+    mode?: 'min' | 'max' | 'avg' | 'median';
 }
 /**
  * A sort, either as an object keyed by field or as a list of fields in the
@@ -729,15 +842,25 @@ type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
  * @public
  */
 interface QueryParams {
-    /** The engine searches for this text, analysed with the index's own language module. */
+    /** 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 narrows the candidates before scoring. */
+    /**
+     * 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;
-    /** These multipliers raise or lower each field's contribution to the score, keyed by field. */
+    /**
+     * 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 query gathers term statistics this way, and follows the index's `defaultScoring` otherwise. */
+    /** 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,
@@ -745,36 +868,48 @@ interface QueryParams {
      * query can reject every hit in another.
      */
     minScore?: number;
-    /** A document has to carry this many query terms. The engine accepts one by default. */
+    /** The engine keeps a document only where it matches this many query terms, and one term is enough by default. */
     termMatch?: TermMatchPolicy;
-    /** A term may differ by this edit distance and still match, which is how a typo still finds its document. */
+    /** The engine matches an indexed term within this edit distance of a query term, so a query with a typo still finds its document. */
     tolerance?: number;
-    /** This many leading characters have to match exactly before `tolerance` applies, which keeps fuzzy matching honest. */
+    /** The engine applies `tolerance` only to indexed terms that share this many leading characters with the query term, 2 by default. */
     prefixLength?: number;
     /**
-     * Treat the last query token as an unfinished word so it also matches
-     * indexed terms that complete it ('secur' matches 'security'). Earlier
-     * tokens must match fully; `tolerance` keeps applying to them but not to
-     * the prefix token. Completions score against a shared document frequency
-     * and are demoted below full-word matches. Ignored when `exact` is true.
-     * Off by default.
+     * Setting this makes the engine treat the last query term as an unfinished
+     * word, so `secur` matches `security`. The earlier terms must match whole,
+     * and `tolerance` applies to them alone. The engine scores completions
+     * against a shared document frequency and ranks them below whole-word
+     * matches. It ignores this setting where `exact` is true, and the setting
+     * defaults to false.
      */
     prefix?: boolean;
     /**
-     * Setting this requires every query term to equal an indexed term outright,
-     * 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 said `running` through their shared stem.
+     * 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;
-    /** These settings name the fields the query counts values for, and control how each count is cut and sorted. */
+    /**
+     * 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;
     /**
-     * This sorts the hits by field value, which replaces the relevance ranking.
-     * Pass an object keyed by field, or a list of fields in the order they
-     * apply. Fusion defines the order of hybrid results, so a hybrid query takes
-     * no sort. The engine throws `SEARCH_INVALID_MODE` for a query that sets
-     * both.
+     * 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. A sort can name a `number`,
+     * `boolean`, `enum`, or `string:sortable` field, or a list field, which the
+     * engine reduces to one value by the entry's `mode`. The engine throws
+     * `SEARCH_INVALID_FIELD` for a sort on a plain `string`, a `geopoint`, or a
+     * vector field, because ordering a plain string takes far more memory per
+     * document than ordering a number, while the other two types have no order.
+     * The engine orders hybrid results by fusion, so it throws
+     * `SEARCH_INVALID_MODE` for a hybrid query that sets a sort, and it throws
+     * the same code for a direction other than `asc` and `desc`.
      */
     sort?: SortSpec;
     /** These settings collapse the hits into groups by field value. */
@@ -906,11 +1041,11 @@ interface VectorQueryConfig {
  * @public
  */
 interface HybridConfig {
-    /** The rankings merge this way, and by rank fusion by default. */
+    /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
     strategy?: 'rrf' | 'linear';
-    /** This rank-fusion constant softens the advantage of the top ranks, and `rrf` alone reads it. */
+    /** 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;
-    /** This weights the vector score, from 0 to 1, and `linear` alone reads it. */
+    /** 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;
 }
 /**
@@ -921,11 +1056,11 @@ interface HybridConfig {
 interface FacetConfig {
     /** Each key names a field the query counts values for. */
     [field: string]: {
-        /** The facet returns this many values for the field, most frequent first. */
+        /** 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;
-        /** This orders the returned values by their count. */
+        /** 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';
-        /** These ranges bucket a numeric field, instead of counting each value. */
+        /** 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;
@@ -940,11 +1075,15 @@ interface FacetConfig {
 interface GroupConfig {
     /** The values of these fields define a group, and several fields group by their combination. */
     fields: string[];
-    /** Each group keeps this many hits, and one by default, which is the collapse behaviour. */
+    /** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
     maxPerGroup?: number;
-    /** The result keeps this many groups, best first, and every group without it. */
+    /** The engine returns this many groups, best first, and every group where you leave this out. */
     limit?: number;
-    /** This folds each group's hits into one value, such as a sum or an average. */
+    /**
+     * 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;
 }
 /**
@@ -970,77 +1109,30 @@ type GroupReducer = {
  * Which fields a query returns highlighted snippets for, and how those
  * snippets are marked up.
  *
- * The highlighter re-analyses each returned field's text and marks the spans
- * whose stems match the query, so it works whatever the index's
- * `trackPositions` setting says.
+ * The engine analyses the text of each returned field again and marks every
+ * word that the query matches. That covers a word whose stem equals a query
+ * stem, a word within the query's `tolerance` of a query stem, and, for a
+ * `prefix` query, a word that completes the last query term. The engine
+ * therefore marks the same words whatever the index's `trackPositions`
+ * setting is.
  *
  * @public
  */
 interface HighlightConfig {
     /** The engine highlights these fields. */
     fields: string[];
-    /** This opens each match, and is `<mark>` by default. */
+    /** The engine writes this before each match, and writes `<mark>` by default. */
     preTag?: string;
-    /** This closes each match, and is `</mark>` by default. */
+    /** 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. The snippet that comes back is longer than
-     * that number, because the engine then adds the opening and closing tags,
-     * and an ellipsis at each end where it cut the field.
+     * 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;
 }
-/**
- * Everything {@link Narsil.suggest} accepts.
- *
- * @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
- */
-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;
-    /**
-     * 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.
-     */
-    sort?: SortSpec;
-    /** This chooses how much of each stored document comes back, and the whole document by default. */
-    document?: DocumentProjection;
-}
 
 /**
  * Snapshot of V8 heap usage as reported by `process.memoryUsage()`, with the

package/dist/persistence/durability/checkpoint-worker.d.ts

@@ -1,4 +1,4 @@
-import { P as PartitionConfig, c as ScoringMode, V as VectorIndexConfig } from '../../schema-mLpXZBEh.js';
+import { P as PartitionConfig, c as ScoringMode, V as VectorIndexConfig } from '../../schema-d5Afu03A.js';
 import '../../adapters-79OIa4xm.js';
 
 interface IndexMetadata {

package/dist/persistence/durability/checkpoint-worker.mjs

@@ -1,22 +1,22 @@
-import { CHECKPOINT_WORKER_HEARTBEAT_MS, createDurableDirectory, writeCheckpointSegments } from '../../chunk-BH5SYB5W.mjs';
+import { CHECKPOINT_WORKER_HEARTBEAT_MS, createDurableDirectory, writeCheckpointSegments } from '../../chunk-24RXHMEL.mjs';
 import '../../chunk-GCM3JFVA.mjs';
-import '../../chunk-4NVPQ6S5.mjs';
-import '../../chunk-XNQAIO74.mjs';
+import '../../chunk-UXNWQZST.mjs';
+import '../../chunk-ZZT3EAUC.mjs';
 import '../../chunk-AV4IJKD2.mjs';
-import '../../chunk-TVT5V4E7.mjs';
-import '../../chunk-D2S642IV.mjs';
-import '../../chunk-5T6AOR37.mjs';
-import '../../chunk-L225SHNB.mjs';
+import '../../chunk-B2TFROFX.mjs';
+import '../../chunk-3LHGNRYE.mjs';
+import '../../chunk-ZNZBXMP5.mjs';
+import '../../chunk-L6TNPLAR.mjs';
 import '../../chunk-TGP5M5R7.mjs';
-import '../../chunk-U2AL3SON.mjs';
+import '../../chunk-THYRHHO2.mjs';
 import '../../chunk-ZJ4CSAB2.mjs';
-import '../../chunk-UTOFOJOR.mjs';
+import '../../chunk-YNVIUGF5.mjs';
 import '../../chunk-3L4U6EJQ.mjs';
 import '../../chunk-IFBKLBGB.mjs';
 import '../../chunk-U2BKYEC7.mjs';
-import '../../chunk-2GWVQWGA.mjs';
+import '../../chunk-YMZCMH5M.mjs';
 import '../../chunk-POWOTUKJ.mjs';
-import '../../chunk-FRQVMFY7.mjs';
+import '../../chunk-USKFU7J5.mjs';
 
 // src/persistence/durability/rebuild.ts
 async function rebuildSegmentsFromDurable(root, metadata, targets, compactionThreshold, capturedPartitions = []) {

package/dist/react.d.ts

@@ -1,10 +1,10 @@
-import { N as NarsilError, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, Q as QueryParams, h as PreflightResult, e as QueryResult, j as SuggestParams, k as SuggestResult } from './memory-xrXOZMbw.js';
-export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './memory-xrXOZMbw.js';
-import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-Df73Tjgq.js';
-export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-Df73Tjgq.js';
+import { N as NarsilError, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, Q as QueryParams, h as PreflightResult, e as QueryResult, j as SuggestParams, k as SuggestResult } from './memory-yFaVn2xZ.js';
+export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './memory-yFaVn2xZ.js';
+import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-CH2Dod8w.js';
+export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-CH2Dod8w.js';
 import { ReactNode, ReactElement } from 'react';
-import { N as NarsilClient, I as ImportSource } from './client-CQUqt9Ir.js';
-import { A as AnyDocument } from './schema-mLpXZBEh.js';
+import { N as NarsilClient, I as ImportSource } from './client-BQK6Tf6A.js';
+import { A as AnyDocument } from './schema-d5Afu03A.js';
 import './adapters-79OIa4xm.js';
 
 /**

package/dist/react.mjs

@@ -14,6 +14,7 @@ var ErrorCodes = {
   INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS",
   INDEX_ORPHANED: "INDEX_ORPHANED",
   INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED",
+  INSTANCE_SHUT_DOWN: "INSTANCE_SHUT_DOWN",
   PARTITION_CORRUPTED: "PARTITION_CORRUPTED",
   PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE",
   WORKER_CRASHED: "WORKER_CRASHED",

package/dist/{schema-mLpXZBEh.d.ts → schema-d5Afu03A.d.ts}

@@ -155,11 +155,16 @@ interface IndexConfig {
     trackPositions?: boolean;
     /** These settings control when vector fields move to an HNSW graph, and how that graph is built. */
     vectorPromotion?: VectorIndexConfig;
-    /** Setting this rejects a document carrying a field the schema does not declare. The engine accepts extra fields by default. */
+    /**
+     * Setting this makes the engine reject a document with a field that the
+     * schema does not declare, and throw `SEARCH_INVALID_FIELD` for a filter,
+     * sort, facet, or group on such a field. The engine accepts extra fields by
+     * default.
+     */
     strict?: boolean;
     /** These settings embed text fields into vector fields on every write. */
     embedding?: EmbeddingFieldConfig;
-    /** The engine rejects a document that omits any of these fields. */
+    /** The engine rejects an insert or an update of a document that lacks any of these fields, with `DOC_MISSING_REQUIRED_FIELD`. */
     required?: string[];
     /**
      * Setting this to false stops the index recording the spellings a stemmer