@delali/narsil 0.2.4-next.42 → 0.2.4-next.44

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { c as StopWordOverride, C as CustomTokenizer } from './schema-ZRbk8BgH.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, b as ScoringMode, V as VectorIndexConfig, d as VectorQuantizationMode } from './schema-ZRbk8BgH.js';
+import { c as StopWordOverride, C as CustomTokenizer } from './schema-B7juWg8Q.js';
+export { A as AnyDocument, B as BM25Params, E as EmbeddingFieldConfig, F as FieldType, I as IndexConfig, b as InsertOptions, P as PartitionConfig, S as SchemaDefinition, a as ScoringMode, V as VectorIndexConfig, d as VectorQuantizationMode } from './schema-B7juWg8Q.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, k as ComparisonFilter, D as DocumentProjection, E as ErrorCode, b as ErrorCodes, F as FacetConfig, l as FacetResult, m as FieldFilter, n as FilterExpression, G as GeoFilter, o as GeoPolygonFilter, p as GeoRadiusFilter, q as GroupConfig, r as GroupReducer, s as GroupResult, H as HighlightConfig, t as HighlightMatch, u as Hit, v as HybridConfig, I as IndexInfo, f as IndexStats, L as ListParams, g as ListResult, w as ListedDocument, M as MemoryStats, N as NarsilError, c as NarsilErrorCode, P as PartitionStatsResult, h as PreflightResult, x as PresenceFilter, y as ProcessMemoryReport, z as QueryCoverage, Q as QueryParams, e as QueryResult, J as ScoreComponents, K as SearchMode, S as ServerErrorCode, d as ServerErrorCodes, O as SortField, R as SortSpec, T as StringFilter, i as SuggestParams, j as SuggestResult, U as TermMatchPolicy, V as VectorMaintenanceResult, W as VectorQueryConfig } from './search-DHuXwJYk.js';
-import { N as NarsilConfig } from './config-Byyl1QqH.js';
-export { A as AnalysisConfig, D as DurabilityConfig, I as IndexContext, a as InsertContext, b as NarsilPlugin, P as PartitionContext, R as RemoveContext, S as SearchContext, c as StaleAnalysis, U as UpdateContext, W as WorkerConfig, d as WorkerContext } from './config-Byyl1QqH.js';
-import { a as Narsil } from './engine-BE45D5ZG.js';
-export { N as NarsilEventMap } from './engine-BE45D5ZG.js';
+export { A as ArrayFilter, B as BatchResult, C as ClientErrorCode, a as ClientErrorCodes, k as ComparisonFilter, D as DocumentProjection, E as ErrorCode, b as ErrorCodes, F as FacetConfig, l as FacetResult, m as FieldFilter, n as FilterExpression, G as GeoFilter, o as GeoPolygonFilter, p as GeoRadiusFilter, q as GroupConfig, r as GroupReducer, s as GroupResult, H as HighlightConfig, t as HighlightMatch, u as Hit, v as HybridConfig, I as IndexInfo, f as IndexStats, L as ListParams, g as ListResult, w as ListedDocument, M as MemoryStats, N as NarsilError, c as NarsilErrorCode, P as PartitionStatsResult, h as PreflightResult, x as PresenceFilter, y as ProcessMemoryReport, z as QueryCoverage, Q as QueryParams, e as QueryResult, J as ScoreComponents, K as SearchMode, S as ServerErrorCode, d as ServerErrorCodes, O as SortField, R as SortSpec, T as StringFilter, i as SuggestParams, j as SuggestResult, U as TermMatchPolicy, V as VectorMaintenanceResult, W as VectorQueryConfig } from './search-DDHjfXhJ.js';
+import { N as NarsilConfig } from './config-BZRExglL.js';
+export { A as AnalysisConfig, D as DurabilityConfig, I as IndexContext, a as IndexLifecycleConfig, b as InsertContext, 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-BZRExglL.js';
+import { a as Narsil } from './engine-Cjr1uBLa.js';
+export { I as IndexLifecycleOperations, N as NarsilEventMap } from './engine-Cjr1uBLa.js';
 export { E as EmbeddingAdapter, I as InvalidationAdapter, a as InvalidationEvent, b as PartitionStatistics, P as PersistenceAdapter } from './adapters-79OIa4xm.js';
 
 /**
@@ -154,8 +154,8 @@ declare function getLanguage(name: string): LanguageModule;
  *
  * The engine holds every index you create, so an application usually keeps one
  * instance for its lifetime. When you configure persistence, this recovers the
- * indexes already on disk before it resolves, so the engine is ready to query
- * as soon as you have it.
+ * indexes already on disk before it resolves. Lifecycle settings register
+ * those indexes as closed and load each one when its first request arrives.
  *
  * @param config - This carries the persistence, partitioning, and worker
  * invalidation settings. Omit it for an engine that keeps everything in memory.

package/dist/index.mjs

@@ -1,7 +1,7 @@
-export { VERSION, createNarsil } from './chunk-MMSWEEZT.mjs';
+export { VERSION, createNarsil } from './chunk-WASNWIEK.mjs';
 import './chunk-JQUL2T6I.mjs';
-import './chunk-WU2UZEVD.mjs';
-export { clearNormalizationCache, configureNormalizationCache, getLanguage, getNormalizationCacheSize, getStopWords, getTokenizer, hasStopWords, hasTokenizer, registerLanguage, registerStopWords, registerTokenizer, resetNormalizationCache } from './chunk-GRWFY2HI.mjs';
+import './chunk-XWICBGYT.mjs';
+export { clearNormalizationCache, configureNormalizationCache, getLanguage, getNormalizationCacheSize, getStopWords, getTokenizer, hasStopWords, hasTokenizer, registerLanguage, registerStopWords, registerTokenizer, resetNormalizationCache } from './chunk-XNCJFU2E.mjs';
 import './chunk-TGP5M5R7.mjs';
 import './chunk-OBXS7OZM.mjs';
 export { isSimdAvailable } from './chunk-WDL632CN.mjs';
@@ -9,4 +9,4 @@ import './chunk-KMMJMDUA.mjs';
 import './chunk-U2BKYEC7.mjs';
 import './chunk-BFIH7OV5.mjs';
 import './chunk-WTONLDU3.mjs';
-export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes } from './chunk-GB2IIJJG.mjs';
+export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes } from './chunk-P4ELXVJQ.mjs';

package/dist/{options-EXYFcem-.d.ts → options-BC68VPoE.d.ts}

@@ -1,6 +1,6 @@
-import { C as ClusterNamespace } from './config-fLC4lbmg.js';
+import { C as ClusterNamespace } from './config-B-ZI-ft5.js';
 import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
-import { h as TaskStore } from './tasks-CnMLpfk-.js';
+import { h as TaskStore } from './tasks-Bn4R1NPN.js';
 
 /**
  * Marks that `POST /indexes/{name}/documents/_import` accepts `?async=true` and
@@ -29,6 +29,13 @@ declare const TASK_FILTER_CAPABILITY = "tasks.filter";
  * @public
  */
 declare const REBUILD_ANALYSIS_CAPABILITY = "indexes.rebuildAnalysis";
+/**
+ * Marks that `POST /indexes/{name}/_open` and `POST /indexes/{name}/_close`
+ * load and release an index's server memory.
+ *
+ * @public
+ */
+declare const INDEX_LIFECYCLE_CAPABILITY = "indexes.lifecycle";
 /**
  * Every capability this server announces at `/capabilities`.
  *
@@ -240,4 +247,4 @@ interface ErrorEnvelope {
     };
 }
 
-export { ASYNC_IMPORT_CAPABILITY as A, type CorsOptions as C, type ErrorEnvelope as E, type NarsilServer as N, type OnRequestHook as O, REBUILD_ANALYSIS_CAPABILITY as R, SERVER_CAPABILITIES as S, TASK_CANCEL_CAPABILITY as T, TASK_FILTER_CAPABILITY as a, type ServerOptions as b, type RequestContext as c, type RequestDenial as d, type ServerLimits as e };
+export { ASYNC_IMPORT_CAPABILITY as A, type CorsOptions as C, type ErrorEnvelope as E, INDEX_LIFECYCLE_CAPABILITY as I, type NarsilServer as N, type OnRequestHook as O, REBUILD_ANALYSIS_CAPABILITY as R, SERVER_CAPABILITIES as S, TASK_CANCEL_CAPABILITY as T, TASK_FILTER_CAPABILITY as a, type ServerOptions as b, type RequestContext as c, type RequestDenial as d, type ServerLimits as e };

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

@@ -1,8 +1,10 @@
-import { P as PartitionConfig, b as ScoringMode, V as VectorIndexConfig } from '../../schema-ZRbk8BgH.js';
+import { P as PartitionConfig, a as ScoringMode, V as VectorIndexConfig } from '../../schema-B7juWg8Q.js';
 import '../../adapters-79OIa4xm.js';
 
 interface IndexMetadata {
     indexName: string;
+    /** Number of documents represented by the last completed checkpoint. */
+    documentCount?: number;
     /** The identity a cluster gave the index at creation; absent on a single engine. */
     indexUuid?: string;
     /** The partitions this copy holds, which a cluster node answers a partition-stores request from. */

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

@@ -1,7 +1,7 @@
-import { createDurableDirectory, writeSegmentedCheckpoint } from '../../chunk-MMSWEEZT.mjs';
+import { createDurableDirectory, writeSegmentedCheckpoint } from '../../chunk-WASNWIEK.mjs';
 import '../../chunk-JQUL2T6I.mjs';
-import '../../chunk-WU2UZEVD.mjs';
-import '../../chunk-GRWFY2HI.mjs';
+import '../../chunk-XWICBGYT.mjs';
+import '../../chunk-XNCJFU2E.mjs';
 import '../../chunk-TGP5M5R7.mjs';
 import '../../chunk-OBXS7OZM.mjs';
 import '../../chunk-WDL632CN.mjs';
@@ -9,7 +9,7 @@ import '../../chunk-KMMJMDUA.mjs';
 import '../../chunk-U2BKYEC7.mjs';
 import '../../chunk-BFIH7OV5.mjs';
 import '../../chunk-WTONLDU3.mjs';
-import '../../chunk-GB2IIJJG.mjs';
+import '../../chunk-P4ELXVJQ.mjs';
 
 // src/persistence/durability/rebuild.ts
 async function rebuildSnapshotFromDurable(root, metadata, targets, compactionThreshold) {

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, i as SuggestParams, j as SuggestResult } from './search-DHuXwJYk.js';
-export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes } from './search-DHuXwJYk.js';
-import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-CnMLpfk-.js';
-export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-CnMLpfk-.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, i as SuggestParams, j as SuggestResult } from './search-DDHjfXhJ.js';
+export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes } from './search-DDHjfXhJ.js';
+import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-Bn4R1NPN.js';
+export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-Bn4R1NPN.js';
 import { ReactNode, ReactElement } from 'react';
-import { N as NarsilClient, I as ImportSource } from './client-BobVnoIK.js';
-import { A as AnyDocument } from './schema-ZRbk8BgH.js';
+import { N as NarsilClient, I as ImportSource } from './client-C5BkUqB8.js';
+import { A as AnyDocument } from './schema-B7juWg8Q.js';
 import './adapters-79OIa4xm.js';
 
 /**

package/dist/react.mjs

@@ -3,7 +3,6 @@ import { createContext, useState, useEffect, createElement, useRef, useEffectEve
 // src/errors.ts
 var ErrorCodes = {
   SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE",
-  SCHEMA_MISSING_FIELD: "SCHEMA_MISSING_FIELD",
   SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED",
   SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION",
   SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT",
@@ -13,6 +12,7 @@ var ErrorCodes = {
   INDEX_NOT_FOUND: "INDEX_NOT_FOUND",
   INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS",
   INDEX_ORPHANED: "INDEX_ORPHANED",
+  INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED",
   PARTITION_CORRUPTED: "PARTITION_CORRUPTED",
   PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE",
   WORKER_CRASHED: "WORKER_CRASHED",
@@ -25,7 +25,6 @@ var ErrorCodes = {
   PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT",
   PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED",
   SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD",
-  SEARCH_INVALID_VECTOR_SIZE: "SEARCH_INVALID_VECTOR_SIZE",
   VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH",
   SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER",
   SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE",
@@ -49,8 +48,6 @@ var ErrorCodes = {
   ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES",
   ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG",
   ALLOCATION_FAILED: "ALLOCATION_FAILED",
-  CONTROLLER_LEASE_LOST: "CONTROLLER_LEASE_LOST",
-  CONTROLLER_NOT_ACTIVE: "CONTROLLER_NOT_ACTIVE",
   CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID",
   NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED",
   NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED",
@@ -106,6 +103,7 @@ var ServerErrorCodes = {
   TASK_NOT_FOUND: "TASK_NOT_FOUND",
   TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE",
   TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE",
+  TASK_INTERRUPTED: "TASK_INTERRUPTED",
   TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS",
   HOOK_ERROR: "HOOK_ERROR",
   INTERNAL_ERROR: "INTERNAL_ERROR"

package/dist/{schema-ZRbk8BgH.d.ts → schema-B7juWg8Q.d.ts}

@@ -61,7 +61,12 @@ type VectorQuantizationMode = 'sq8' | 'none';
 interface VectorIndexConfig {
     /** The engine promotes the field to an HNSW graph once it holds this many vectors. */
     threshold?: number;
-    /** A filtered search prefers the graph over a scan once the field holds this many vectors. */
+    /**
+     * A selectivity ratio between 0 and 1, defaulting to 0.03. A filtered search
+     * whose filter matches a smaller share of the graph's vectors scans just the
+     * matches, and one matching a larger share searches the graph. The engine
+     * clamps any value outside that range to it.
+     */
     filterThreshold?: number;
     /** These settings shape the graph: neighbours per node, build-time exploration, and the metric that ranks results. */
     hnswConfig?: {
@@ -69,7 +74,7 @@ interface VectorIndexConfig {
         efConstruction?: number;
         metric?: 'cosine' | 'dotProduct' | 'euclidean';
     };
-    /** The engine stores the promoted vectors at this precision. It keeps full precision by default. */
+    /** The engine stores the promoted vectors at this precision, and it quantises to `sq8` by default. Set `none` to keep full precision. */
     quantization?: VectorQuantizationMode;
 }
 /**
@@ -117,7 +122,12 @@ interface IndexConfig {
     stopWords?: StopWordOverride | string;
     /** This replaces the language's tokeniser, either inline or by the name a tokeniser registered under. */
     tokenizer?: CustomTokenizer | string;
-    /** Setting this records term positions, which phrase queries and highlighting need. */
+    /**
+     * Setting this records term positions in each posting, which the `.nrsl`
+     * format carries for readers that match phrases. This engine's highlighter
+     * re-analyses the stored text instead of reading them, so an index that
+     * opts out answers every query the same way and stores less.
+     */
     trackPositions?: boolean;
     /** These settings control when vector fields move to an HNSW graph, and how that graph is built. */
     vectorPromotion?: VectorIndexConfig;
@@ -170,8 +180,9 @@ interface CustomTokenizer {
      * Splits one field value into the tokens the engine indexes.
      *
      * @param text - The raw field value, before any stemming or stop word removal.
-     * @returns Each token with the character offset it starts at, which
-     * highlighting and phrase matching rely on.
+     * @returns Each token with its ordinal position in the field, which the
+     * engine writes into postings when `trackPositions` is on, and which a
+     * prefix query reads to find the last typed word.
      */
     tokenize(text: string): Array<{
         token: string;
@@ -220,4 +231,4 @@ interface InsertOptions {
     skipClone?: boolean;
 }
 
-export type { AnyDocument as A, BM25Params as B, CustomTokenizer as C, EmbeddingFieldConfig as E, FieldType as F, IndexConfig as I, PartitionConfig as P, SchemaDefinition as S, VectorIndexConfig as V, InsertOptions as a, ScoringMode as b, StopWordOverride as c, VectorQuantizationMode as d };
+export type { AnyDocument as A, BM25Params as B, CustomTokenizer as C, EmbeddingFieldConfig as E, FieldType as F, IndexConfig as I, PartitionConfig as P, SchemaDefinition as S, VectorIndexConfig as V, ScoringMode as a, InsertOptions as b, StopWordOverride as c, VectorQuantizationMode as d };

package/dist/{search-DHuXwJYk.d.ts → search-DDHjfXhJ.d.ts}

@@ -1,4 +1,4 @@
-import { A as AnyDocument, S as SchemaDefinition, b as ScoringMode } from './schema-ZRbk8BgH.js';
+import { A as AnyDocument, S as SchemaDefinition, a as ScoringMode } from './schema-B7juWg8Q.js';
 
 /**
  * Every code a {@link NarsilError} carries, grouped by the part of the engine
@@ -12,7 +12,6 @@ import { A as AnyDocument, S as SchemaDefinition, b as ScoringMode } from './sch
  */
 declare const ErrorCodes: {
     readonly SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE";
-    readonly SCHEMA_MISSING_FIELD: "SCHEMA_MISSING_FIELD";
     readonly SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED";
     readonly SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION";
     readonly SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT";
@@ -22,6 +21,7 @@ declare const ErrorCodes: {
     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 PARTITION_CORRUPTED: "PARTITION_CORRUPTED";
     readonly PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE";
     readonly WORKER_CRASHED: "WORKER_CRASHED";
@@ -34,7 +34,6 @@ declare const ErrorCodes: {
     readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
     readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
     readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
-    readonly SEARCH_INVALID_VECTOR_SIZE: "SEARCH_INVALID_VECTOR_SIZE";
     readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
     readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
     readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
@@ -58,8 +57,6 @@ declare const ErrorCodes: {
     readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
     readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
     readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
-    readonly CONTROLLER_LEASE_LOST: "CONTROLLER_LEASE_LOST";
-    readonly CONTROLLER_NOT_ACTIVE: "CONTROLLER_NOT_ACTIVE";
     readonly CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID";
     readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
     readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
@@ -131,6 +128,7 @@ declare const ServerErrorCodes: {
     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";
@@ -334,6 +332,10 @@ interface GroupResult {
     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;
 }
 /**
  * What {@link Narsil.preflight} returns: how many documents a query matches,
@@ -370,7 +372,7 @@ interface BatchResult {
  * @public
  */
 interface IndexStats {
-    /** The index holds this many documents. */
+    /** 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;
@@ -397,7 +399,7 @@ interface IndexStats {
 interface IndexInfo {
     /** The index was created under this name. */
     name: string;
-    /** The index holds this many documents. */
+    /** 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;
@@ -405,6 +407,10 @@ interface IndexInfo {
     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
@@ -483,6 +489,12 @@ interface MemoryStats {
      * `process.heapUsed` cannot tell engines apart.
      */
     estimatedIndexBytes: number;
+    /** This many indexes currently occupy engine memory. */
+    openIndexCount: number;
+    /** This many indexes remain registered without occupying engine memory, including parked recovery failures. */
+    closedIndexCount: number;
+    /** This counts successful index loads since this engine started. */
+    reopenCount: number;
     /**
      * Per-worker V8 heap usage when the engine has been promoted to a worker
      * pool. Empty when no workers are active.
@@ -752,7 +764,11 @@ interface QueryParams {
     boost?: Record<string, number>;
     /** The query gathers term statistics this way, and follows the index's `defaultScoring` otherwise. */
     scoring?: ScoringMode;
-    /** The engine drops any hit scoring below this value. */
+    /**
+     * 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;
     /** A document has to carry this many query terms. The engine accepts one by default. */
     termMatch?: TermMatchPolicy;
@@ -769,7 +785,12 @@ interface QueryParams {
      * Off by default.
      */
     prefix?: boolean;
-    /** Setting this matches the term as written, skipping stemming and fuzzy matching. */
+    /**
+     * 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.
+     */
     exact?: boolean;
     /** These settings name the fields the query counts values for, and control how each count is cut and sorted. */
     facets?: FacetConfig;
@@ -931,6 +952,8 @@ interface GroupConfig {
     fields: string[];
     /** Each group keeps this many hits, and one by default, which is the collapse behaviour. */
     maxPerGroup?: number;
+    /** The result keeps this many groups, best first, and every group without it. */
+    limit?: number;
     /** This folds each group's hits into one value, such as a sum or an average. */
     reduce?: GroupReducer;
 }
@@ -957,8 +980,9 @@ type GroupReducer = {
  * Which fields a query returns highlighted snippets for, and how those
  * snippets are marked up.
  *
- * The index has to have been created with `trackPositions`, because
- * highlighting reads the positions that setting records.
+ * 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.
  *
  * @public
  */

package/dist/server.d.ts

@@ -1,14 +1,14 @@
-import { b as ServerOptions, N as NarsilServer } from './options-EXYFcem-.js';
-export { A as ASYNC_IMPORT_CAPABILITY, C as CorsOptions, E as ErrorEnvelope, O as OnRequestHook, R as REBUILD_ANALYSIS_CAPABILITY, c as RequestContext, d as RequestDenial, S as SERVER_CAPABILITIES, e as ServerLimits, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './options-EXYFcem-.js';
-import { a as Narsil } from './engine-BE45D5ZG.js';
-import { h as TaskStore, e as TaskRecord, d as TaskProgress, b as ImportResult } from './tasks-CnMLpfk-.js';
-export { C as CapabilitiesResponse, a as CreateIndexEmbedding, i as CreateIndexRequest, H as HttpIndexConfig, I as ImportError, T as TaskListPage, c as TaskListQuery, f as TaskStatus, g as TaskType } from './tasks-CnMLpfk-.js';
-export { d as ServerErrorCodes } from './search-DHuXwJYk.js';
-import './config-fLC4lbmg.js';
-import './config-Byyl1QqH.js';
+import { b as ServerOptions, N as NarsilServer } from './options-BC68VPoE.js';
+export { A as ASYNC_IMPORT_CAPABILITY, C as CorsOptions, E as ErrorEnvelope, I as INDEX_LIFECYCLE_CAPABILITY, O as OnRequestHook, R as REBUILD_ANALYSIS_CAPABILITY, c as RequestContext, d as RequestDenial, S as SERVER_CAPABILITIES, e as ServerLimits, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './options-BC68VPoE.js';
+import { a as Narsil } from './engine-Cjr1uBLa.js';
+import { h as TaskStore, e as TaskRecord, d as TaskProgress, b as ImportResult } from './tasks-Bn4R1NPN.js';
+export { C as CapabilitiesResponse, a as CreateIndexEmbedding, i as CreateIndexRequest, H as HttpIndexConfig, I as ImportError, T as TaskListPage, c as TaskListQuery, f as TaskStatus, g as TaskType } from './tasks-Bn4R1NPN.js';
+export { d as ServerErrorCodes } from './search-DDHjfXhJ.js';
+import './config-B-ZI-ft5.js';
+import './config-BZRExglL.js';
 import './adapters-79OIa4xm.js';
-import './schema-ZRbk8BgH.js';
-import './types-B5Tsaalz.js';
+import './schema-B7juWg8Q.js';
+import './types-DsSSjY4d.js';
 import './types-D5OwhtsQ.js';
 
 /**

package/dist/server.mjs

@@ -1,6 +1,6 @@
-import { validateIndexName } from './chunk-WU2UZEVD.mjs';
-import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-GB2IIJJG.mjs';
-export { ServerErrorCodes } from './chunk-GB2IIJJG.mjs';
+import { validateIndexName } from './chunk-XWICBGYT.mjs';
+import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
+export { ServerErrorCodes } from './chunk-P4ELXVJQ.mjs';
 import { randomUUID } from 'crypto';
 
 // src/server/capabilities.ts
@@ -8,11 +8,13 @@ var ASYNC_IMPORT_CAPABILITY = "documents.import.async";
 var TASK_CANCEL_CAPABILITY = "tasks.cancel";
 var TASK_FILTER_CAPABILITY = "tasks.filter";
 var REBUILD_ANALYSIS_CAPABILITY = "indexes.rebuildAnalysis";
+var INDEX_LIFECYCLE_CAPABILITY = "indexes.lifecycle";
 var SERVER_CAPABILITIES = [
   ASYNC_IMPORT_CAPABILITY,
   TASK_CANCEL_CAPABILITY,
   TASK_FILTER_CAPABILITY,
-  REBUILD_ANALYSIS_CAPABILITY
+  REBUILD_ANALYSIS_CAPABILITY,
+  INDEX_LIFECYCLE_CAPABILITY
 ];
 
 // src/server/cors.ts
@@ -52,20 +54,19 @@ var STATUS_BY_CODE = {
   TASK_NOT_FOUND: 404,
   TASK_NOT_CANCELLABLE: 409,
   TASK_OWNED_BY_ANOTHER_INSTANCE: 409,
+  TASK_INTERRUPTED: 503,
   TOO_MANY_REQUESTS: 429,
   HOOK_ERROR: 500,
   INTERNAL_ERROR: 500,
   ENVELOPE_INVALID_MAGIC: 400,
   ENVELOPE_VERSION_MISMATCH: 400,
   SCHEMA_INVALID_TYPE: 400,
-  SCHEMA_MISSING_FIELD: 400,
   SCHEMA_DEPTH_EXCEEDED: 400,
   SCHEMA_INVALID_VECTOR_DIMENSION: 400,
   SCHEMA_INVALID_GEOPOINT: 400,
   DOC_VALIDATION_FAILED: 400,
   DOC_MISSING_REQUIRED_FIELD: 400,
   SEARCH_INVALID_FIELD: 400,
-  SEARCH_INVALID_VECTOR_SIZE: 400,
   VECTOR_DIMENSION_MISMATCH: 400,
   SEARCH_INVALID_FILTER: 400,
   SEARCH_INVALID_MODE: 400,
@@ -80,6 +81,7 @@ var STATUS_BY_CODE = {
   DOC_NOT_FOUND: 404,
   INDEX_ALREADY_EXISTS: 409,
   INDEX_ORPHANED: 409,
+  INDEX_REOPEN_CAPACITY_EXHAUSTED: 503,
   DOC_ALREADY_EXISTS: 409,
   PARTITION_REBALANCING_BACKPRESSURE: 409,
   PARTITION_CAPACITY_EXCEEDED: 409,
@@ -114,8 +116,6 @@ var STATUS_BY_CODE = {
   ALLOCATION_INVALID_CONFIG: 400,
   ALLOCATION_NO_DATA_NODES: 503,
   ALLOCATION_FAILED: 503,
-  CONTROLLER_LEASE_LOST: 503,
-  CONTROLLER_NOT_ACTIVE: 503,
   NODE_ALREADY_JOINED: 409,
   NODE_NOT_JOINED: 503,
   NODE_NOT_READY: 503,
@@ -309,7 +309,7 @@ function validateQuery(params, maxWindow) {
   const rowBound = overWindow("limit", params.limit, maxWindow) ?? overWindow("offset", params.offset, maxWindow);
   if (rowBound) return rowBound;
   if (params.group && typeof params.group === "object") {
-    const grouped = overWindow("group.maxPerGroup", params.group.maxPerGroup, maxWindow);
+    const grouped = overWindow("group.maxPerGroup", params.group.maxPerGroup, maxWindow) ?? overWindow("group.limit", params.group.limit, maxWindow);
     if (grouped) return grouped;
   }
   if (params.facets && typeof params.facets === "object") {
@@ -1151,7 +1151,23 @@ function createIndexHandlers(deps) {
       respondError(ctx, err);
     }
   }
-  return { create, list, drop, stats, partitions, clear };
+  async function open(ctx) {
+    try {
+      await engine.open(ctx.params[0]);
+      respondJson(ctx, { name: ctx.params[0], state: "open" });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function close(ctx) {
+    try {
+      await engine.close(ctx.params[0]);
+      respondJson(ctx, { name: ctx.params[0], state: "closed" });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  return { create, list, drop, stats, partitions, clear, open, close };
 }
 
 // src/server/handlers/search.ts
@@ -1559,7 +1575,7 @@ var TaskRegistry = class {
         ...record,
         status: "failed",
         completedAt: Date.now(),
-        error: { code: "TASK_INTERRUPTED", message: "The server restarted while this task was running" }
+        error: { code: ServerErrorCodes.TASK_INTERRUPTED, message: "The server restarted while this task was running" }
       };
       try {
         await this.store.set(failed, TERMINAL_TTL_MS);
@@ -1745,6 +1761,8 @@ var NarsilHttpServer = class {
     app.get("/indexes/:name/partitions", json(idx.partitions, { paramCount: 1, maxBytes: 0 }));
     app.get("/indexes/:name/cluster", json(cluster.allocation, { paramCount: 1, maxBytes: 0 }));
     app.post("/indexes/:name/_clear", json(idx.clear, { paramCount: 1, maxBytes: 0 }));
+    app.post("/indexes/:name/_open", json(idx.open, { paramCount: 1, maxBytes: 0 }));
+    app.post("/indexes/:name/_close", json(idx.close, { paramCount: 1, maxBytes: 0 }));
     app.get("/indexes/:name/count", json(doc.count, { paramCount: 1, maxBytes: 0 }));
     app.post("/indexes/:name/documents", json(doc.insert, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes }));
     app.post(
@@ -1810,4 +1828,4 @@ function createServer(engine, options) {
   return new NarsilHttpServer(engine, options);
 }
 
-export { ASYNC_IMPORT_CAPABILITY, InMemoryTaskStore, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, createServer, httpStatusForNarsilError };
+export { ASYNC_IMPORT_CAPABILITY, INDEX_LIFECYCLE_CAPABILITY, InMemoryTaskStore, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, createServer, httpStatusForNarsilError };

package/dist/{tasks-CnMLpfk-.d.ts → tasks-Bn4R1NPN.d.ts}

@@ -54,7 +54,7 @@ interface HttpIndexConfig {
     };
     /** This list replaces the language's stop words. */
     stopWords?: string[];
-    /** Setting this records term positions, which phrase queries and highlighting need. */
+    /** Setting this records term positions in each posting, which the `.nrsl` format carries for readers that match phrases. Highlighting works without it. */
     trackPositions?: boolean;
     /** Setting this to false returns index stems from suggestions and prefix expansion, instead of the words users typed. */
     surfaceForms?: boolean;

package/dist/{types-B5Tsaalz.d.ts → types-DsSSjY4d.d.ts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './schema-ZRbk8BgH.js';
+import { S as SchemaDefinition } from './schema-B7juWg8Q.js';
 
 /**
  * What a node does in a cluster. A node may hold several roles at once.

package/dist/workers/entry.mjs

@@ -1,5 +1,5 @@
 import { isValidWorkerAction } from '../chunk-WTONLDU3.mjs';
-import { NarsilError, ErrorCodes } from '../chunk-GB2IIJJG.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-P4ELXVJQ.mjs';
 
 // src/workers/action-handler.ts
 function buildErrorResponse(requestId, code, message) {
@@ -55,7 +55,7 @@ async function setup() {
   } catch {
     parentPort = null;
   }
-  const { createDirectExecutor } = await import('../direct-executor-MSJEVPZU.mjs');
+  const { createDirectExecutor } = await import('../direct-executor-IMXNRS7O.mjs');
   const handleAction = createActionHandler(createDirectExecutor());
   if (parentPort) {
     const port = parentPort;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delali/narsil",
-  "version": "0.2.4-next.42",
+  "version": "0.2.4-next.44",
   "type": "module",
   "description": "A distributed full-text search engine with cross-language portable binary format.",
   "author": "Delali (https://sondelali.com)",