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

package/dist/index.mjs

@@ -1,19 +1,19 @@
-export { VERSION, createNarsil } from './chunk-ULJ36FK4.mjs';
+export { VERSION, createNarsil } from './chunk-BH5SYB5W.mjs';
 import './chunk-GCM3JFVA.mjs';
-import './chunk-U36IDJN7.mjs';
-export { getLanguage, getStopWords, getTokenizer, hasStopWords, hasTokenizer, registerLanguage, registerStopWords, registerTokenizer } from './chunk-2FO7KZ6K.mjs';
+import './chunk-4NVPQ6S5.mjs';
+export { getLanguage, getStopWords, getTokenizer, hasStopWords, hasTokenizer, registerLanguage, registerStopWords, registerTokenizer } from './chunk-XNQAIO74.mjs';
 import './chunk-AV4IJKD2.mjs';
-import './chunk-YPYULM5E.mjs';
-import './chunk-3GWP2TO6.mjs';
-export { clearNormalizationCache, configureNormalizationCache, getNormalizationCacheSize, resetNormalizationCache } from './chunk-WM7IS45M.mjs';
-import './chunk-ZT5BRDFW.mjs';
+import './chunk-TVT5V4E7.mjs';
+import './chunk-D2S642IV.mjs';
+export { clearNormalizationCache, configureNormalizationCache, getNormalizationCacheSize, resetNormalizationCache } from './chunk-5T6AOR37.mjs';
+import './chunk-L225SHNB.mjs';
 import './chunk-TGP5M5R7.mjs';
-export { isSimdAvailable } from './chunk-T62YOSGS.mjs';
+export { isSimdAvailable } from './chunk-U2AL3SON.mjs';
 import './chunk-ZJ4CSAB2.mjs';
-import './chunk-WFKIGEBY.mjs';
+import './chunk-UTOFOJOR.mjs';
 import './chunk-3L4U6EJQ.mjs';
 import './chunk-IFBKLBGB.mjs';
 import './chunk-U2BKYEC7.mjs';
 import './chunk-2GWVQWGA.mjs';
 import './chunk-POWOTUKJ.mjs';
-export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes } from './chunk-P4ELXVJQ.mjs';
+export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes, isNarsilError } from './chunk-FRQVMFY7.mjs';

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

@@ -1,4 +1,4 @@
-import { A as AnyDocument, S as SchemaDefinition, c as ScoringMode } from './schema-OSWaaZzx.js';
+import { A as AnyDocument, S as SchemaDefinition, c as ScoringMode } from './schema-mLpXZBEh.js';
 
 /**
  * Every code a {@link NarsilError} carries, grouped by the part of the engine
@@ -27,6 +27,7 @@ declare const ErrorCodes: {
     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";
@@ -140,13 +141,15 @@ declare const ServerErrorCodes: {
  */
 type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
 /**
- * Every code the HTTP client raises when a request never reaches a server, or
- * when the client cannot read the answer.
+ * Every code that the caller's own side raises, where a request never reaches
+ * a server, or where the caller cannot read the answer.
  *
- * No server sends one of these, so a failure under one of them 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 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
  */
@@ -204,6 +207,22 @@ declare class NarsilError extends Error {
      */
     constructor(code: NarsilErrorCode, message: string, details?: Record<string, unknown>);
 }
+/**
+ * Reports whether a caught value is a {@link NarsilError}, including one that
+ * another entry point of this package raises.
+ *
+ * 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.
+ *
+ * @param value - The value that a `catch` block receives.
+ * @returns True where the value holds a code in {@link NarsilError.code}.
+ *
+ * @public
+ */
+declare function isNarsilError(value: unknown): value is NarsilError;
 
 /**
  * What {@link Narsil.query} returns: the ranked hits and everything the query
@@ -283,7 +302,12 @@ interface Hit<T = AnyDocument> {
  * @public
  */
 interface ScoreComponents {
-    /** Each query term appears in this document this often, keyed by term. */
+    /**
+     * 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>;
@@ -298,7 +322,13 @@ interface ScoreComponents {
 interface HighlightMatch {
     /** This is the field's text around the match, wrapped in the query's tags. */
     snippet: string;
-    /** The match covers these character ranges in the original field, for rendering the highlight yourself. */
+    /**
+     * 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;
@@ -462,7 +492,12 @@ interface SuggestResult {
 interface VectorMaintenanceResult {
     /** This describes the named vector field. */
     fieldName: string;
-    /** Tombstones make up this share of the graph's nodes, from 0 to 1. */
+    /**
+     * 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;
@@ -744,7 +779,12 @@ interface QueryParams {
     sort?: SortSpec;
     /** These settings collapse the hits into groups by field value. */
     group?: GroupConfig;
-    /** The query returns this many hits, and 10 by default. */
+    /**
+     * 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;
@@ -943,7 +983,12 @@ interface HighlightConfig {
     preTag?: string;
     /** This closes each match, and is `</mark>` by default. */
     postTag?: string;
-    /** A snippet runs to this many characters before the engine trims it. */
+    /**
+     * 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.
+     */
     maxSnippetLength?: number;
 }
 /**
@@ -1083,4 +1128,4 @@ interface MemoryStats {
     }>;
 }
 
-export { type ArrayFilter as A, type BatchResult as B, type ClientErrorCode as C, type DocumentProjection as D, type ErrorCode as E, type FacetConfig as F, type GeoFilter as G, type HighlightConfig as H, type IndexInfo as I, type ScoreComponents as J, type SearchMode as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type SortField as O, type PartitionStatsResult as P, type QueryParams as Q, type SortSpec as R, type ServerErrorCode as S, type StringFilter as T, type TermMatchPolicy as U, type VectorMaintenanceResult as V, type VectorQueryConfig as W, type WorkerCopyReport as X, ClientErrorCodes as a, ErrorCodes as b, type NarsilErrorCode as c, ServerErrorCodes as d, type QueryResult as e, type IndexStats as f, type ListResult as g, type PreflightResult as h, type SuggestParams as i, type SuggestResult as j, type ComparisonFilter as k, type FacetResult as l, type FieldFilter as m, type FilterExpression as n, type GeoPolygonFilter as o, type GeoRadiusFilter as p, type GroupConfig as q, type GroupReducer as r, type GroupResult as s, type HighlightMatch as t, type Hit as u, type HybridConfig as v, type ListedDocument as w, type PresenceFilter as x, type ProcessMemoryReport as y, type QueryCoverage as z };
+export { type ArrayFilter as A, type BatchResult as B, type ClientErrorCode as C, type DocumentProjection as D, type ErrorCode as E, type FacetConfig as F, type GeoFilter as G, type HighlightConfig as H, type IndexInfo as I, type QueryCoverage as J, type ScoreComponents as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type SearchMode as O, type PartitionStatsResult as P, type QueryParams as Q, type SortField as R, type ServerErrorCode as S, type SortSpec as T, type StringFilter as U, type VectorMaintenanceResult as V, type TermMatchPolicy as W, type VectorQueryConfig as X, type WorkerCopyReport as Y, ClientErrorCodes as a, ErrorCodes as b, type NarsilErrorCode as c, ServerErrorCodes as d, type QueryResult as e, type IndexStats as f, type ListResult as g, type PreflightResult as h, isNarsilError as i, type SuggestParams as j, type SuggestResult as k, type ComparisonFilter as l, type FacetResult as m, type FieldFilter as n, type FilterExpression as o, type GeoPolygonFilter as p, type GeoRadiusFilter as q, type GroupConfig as r, type GroupReducer as s, type GroupResult as t, type HighlightMatch as u, type Hit as v, type HybridConfig as w, type ListedDocument as x, type PresenceFilter as y, type ProcessMemoryReport as z };

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

@@ -1,4 +1,4 @@
-import { P as PartitionConfig, c as ScoringMode, V as VectorIndexConfig } from '../../schema-OSWaaZzx.js';
+import { P as PartitionConfig, c as ScoringMode, V as VectorIndexConfig } from '../../schema-mLpXZBEh.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-ULJ36FK4.mjs';
+import { CHECKPOINT_WORKER_HEARTBEAT_MS, createDurableDirectory, writeCheckpointSegments } from '../../chunk-BH5SYB5W.mjs';
 import '../../chunk-GCM3JFVA.mjs';
-import '../../chunk-U36IDJN7.mjs';
-import '../../chunk-2FO7KZ6K.mjs';
+import '../../chunk-4NVPQ6S5.mjs';
+import '../../chunk-XNQAIO74.mjs';
 import '../../chunk-AV4IJKD2.mjs';
-import '../../chunk-YPYULM5E.mjs';
-import '../../chunk-3GWP2TO6.mjs';
-import '../../chunk-WM7IS45M.mjs';
-import '../../chunk-ZT5BRDFW.mjs';
+import '../../chunk-TVT5V4E7.mjs';
+import '../../chunk-D2S642IV.mjs';
+import '../../chunk-5T6AOR37.mjs';
+import '../../chunk-L225SHNB.mjs';
 import '../../chunk-TGP5M5R7.mjs';
-import '../../chunk-T62YOSGS.mjs';
+import '../../chunk-U2AL3SON.mjs';
 import '../../chunk-ZJ4CSAB2.mjs';
-import '../../chunk-WFKIGEBY.mjs';
+import '../../chunk-UTOFOJOR.mjs';
 import '../../chunk-3L4U6EJQ.mjs';
 import '../../chunk-IFBKLBGB.mjs';
 import '../../chunk-U2BKYEC7.mjs';
 import '../../chunk-2GWVQWGA.mjs';
 import '../../chunk-POWOTUKJ.mjs';
-import '../../chunk-P4ELXVJQ.mjs';
+import '../../chunk-FRQVMFY7.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, i as SuggestParams, j as SuggestResult } from './memory-OmgkX_Z2.js';
-export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes } from './memory-OmgkX_Z2.js';
-import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-DiF1c9v2.js';
-export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-DiF1c9v2.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-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 { ReactNode, ReactElement } from 'react';
-import { N as NarsilClient, I as ImportSource } from './client-BMJWVxOP.js';
-import { A as AnyDocument } from './schema-OSWaaZzx.js';
+import { N as NarsilClient, I as ImportSource } from './client-CQUqt9Ir.js';
+import { A as AnyDocument } from './schema-mLpXZBEh.js';
 import './adapters-79OIa4xm.js';
 
 /**
@@ -297,7 +297,7 @@ declare function useSuggest(indexName: string, params: SuggestParams, options?:
  *
  * @public
  */
-interface NarsilTaskOptions extends NarsilReadOptions {
+interface NarsilTaskOptions extends Omit<NarsilReadOptions, 'refreshIntervalMs'> {
     /** The hook asks again this often while the task runs, and every 250 ms
      * unless you say otherwise, which is how often a running import writes its
      * progress. It stops once the task reaches a final status. */
@@ -306,10 +306,10 @@ interface NarsilTaskOptions extends NarsilReadOptions {
 /**
  * Follows one long-running operation, and stops asking once it finishes.
  *
- * The hook polls while the task is queued or running, pauses while the page is
- * hidden, and reads the figures once more as soon as the page comes back. A
- * failed task arrives as a record carrying its `error`, because a part-finished
- * import still reports what it indexed, so read the status you get.
+ * The hook polls while the task runs, pauses while the page is hidden, and
+ * reads the figures once more as soon as the page comes back. A failed task
+ * arrives as a record carrying its `error`, because a part-finished import
+ * still reports what it indexed, so read the status you get.
  *
  * @param taskId - This names the task to follow, and a nullish or empty id
  * switches the hook off.

package/dist/react.mjs

@@ -1,6 +1,7 @@
 import { createContext, useState, useEffect, createElement, useRef, useEffectEvent, useCallback, useMemo, useContext, useSyncExternalStore } from 'react';
 
 // src/errors.ts
+var NARSIL_ERROR_MARKER = /* @__PURE__ */ Symbol.for("@delali/narsil.NarsilError");
 var ErrorCodes = {
   SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE",
   SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED",
@@ -18,6 +19,7 @@ var ErrorCodes = {
   WORKER_CRASHED: "WORKER_CRASHED",
   WORKER_BUSY: "WORKER_BUSY",
   WORKER_TIMEOUT: "WORKER_TIMEOUT",
+  WORKER_ACTION_FAILED: "WORKER_ACTION_FAILED",
   PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED",
   PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED",
   PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED",
@@ -137,8 +139,12 @@ var NarsilError = class extends Error {
     this.name = "NarsilError";
     this.code = code;
     this.details = details ?? {};
+    Object.defineProperty(this, NARSIL_ERROR_MARKER, { value: true });
   }
 };
+function isNarsilError(value) {
+  return typeof value === "object" && value !== null && NARSIL_ERROR_MARKER in value;
+}
 
 // src/react/constants.ts
 var DEFAULT_KEEP_ALIVE_MS = 2e3;
@@ -148,7 +154,7 @@ var MAX_QUERY_KEY_DEPTH = 32;
 
 // src/react/failure.ts
 function asNarsilError(err, whatFailed) {
-  if (err instanceof NarsilError) return err;
+  if (isNarsilError(err)) return err;
   const message = err instanceof Error ? err.message : String(err);
   return new NarsilError(ClientErrorCodes.CLIENT_UNEXPECTED_ERROR, `${whatFailed} failed unexpectedly: ${message}`);
 }
@@ -519,13 +525,19 @@ function useDocuments(indexName, params, options) {
   );
 }
 
+// src/server/task-status.ts
+var TERMINAL_TASK_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled"]);
+function isTerminalTaskStatus(status) {
+  return TERMINAL_TASK_STATUSES.has(status);
+}
+
 // src/react/task-state.ts
 function pollInterval(interval, failed) {
   return failed ? Math.max(interval, ERROR_RETRY_INTERVAL_MS) : interval;
 }
 function isTerminalTask(record) {
   if (record === null || record === void 0) return false;
-  return record.status === "succeeded" || record.status === "failed" || record.status === "cancelled";
+  return isTerminalTaskStatus(record.status);
 }
 
 // src/react/import.ts
@@ -612,7 +624,7 @@ function useImport(indexName, options) {
     client.cancelTask(taskId, request.current).then((next) => {
       setProgress((prev) => prev.task?.id === taskId ? { task: next, error: void 0, starting: false } : prev);
     }).catch((err) => {
-      if (err instanceof NarsilError && err.code === ServerErrorCodes.TASK_NOT_CANCELLABLE) return;
+      if (isNarsilError(err) && err.code === ServerErrorCodes.TASK_NOT_CANCELLABLE) return;
       setProgress((prev) => prev.task?.id === taskId ? { ...prev, error: asNarsilError(err, "The import") } : prev);
     });
   }, [client, taskId, running, progress.starting]);
@@ -686,4 +698,4 @@ function useTasks(query, options) {
   return useRead(["listTasks", query], (client, request) => client.listTasks(query, request), options);
 }
 
-export { ClientErrorCodes, ErrorCodes, NarsilError, NarsilProvider, ServerErrorCodes, useDocument, useDocuments, useImport, useIndexes, useNarsilClient, usePreflight, useQuery, useStats, useSuggest, useTask, useTasks };
+export { ClientErrorCodes, ErrorCodes, NarsilError, NarsilProvider, ServerErrorCodes, isNarsilError, useDocument, useDocuments, useImport, useIndexes, useNarsilClient, usePreflight, useQuery, useStats, useSuggest, useTask, useTasks };

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

@@ -214,19 +214,26 @@ interface CustomTokenizer {
     }>;
 }
 /**
- * How an index splits its documents across partitions as it grows.
+ * How many partitions an index opens with, and how many documents it accepts.
  *
- * The engine adds a partition once a partition passes its watermark, and it
- * refuses a write once every partition is full and the ceiling is reached.
+ * An index opens with `maxPartitions` partitions and keeps that count until
+ * {@link Narsil.rebalance} changes it, because the engine adds no partition on
+ * its own. Set `watermark` to learn through the `partitionWatermark` event
+ * when an index fills its capacity.
  *
  * @public
  */
 interface PartitionConfig {
-    /** The engine refuses a write that would push one partition past this many documents. */
+    /**
+     * The index accepts this many documents for each of its partitions, so its
+     * capacity is this number multiplied by its partition count. A write beyond
+     * that capacity raises `PARTITION_CAPACITY_EXCEEDED`. Leave the field unset
+     * to accept any number.
+     */
     maxDocsPerPartition?: number;
-    /** The index grows to this many partitions and no further. */
+    /** The index opens with this many partitions, 1 by default, and no rebalance may take it higher. */
     maxPartitions?: number;
-    /** The engine adds a partition once one fills this fraction of `maxDocsPerPartition`, from 0 to 1. */
+    /** The engine emits `partitionWatermark` once the index fills this share of its capacity, above 0 and at most 1. */
     watermark?: number;
 }
 /**

package/dist/server.d.ts

@@ -1,14 +1,14 @@
-import { b as ServerOptions, N as NarsilServer } from './capabilities-CuTSXvbN.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 './capabilities-CuTSXvbN.js';
-import { a as Narsil } from './engine-zhms1qId.js';
-import { d as TaskProgress, b as ImportResult, h as TaskStore, e as TaskRecord } from './tasks-DiF1c9v2.js';
-export { C as CapabilitiesResponse, a as CreateIndexEmbedding, i as CreateIndexRequest, H as HttpIndexConfig, I as ImportError, M as MemoryStatsResponse, T as TaskListPage, c as TaskListQuery, f as TaskStatus, g as TaskType } from './tasks-DiF1c9v2.js';
-export { d as ServerErrorCodes } from './memory-OmgkX_Z2.js';
+export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, N as NarsilError, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './memory-xrXOZMbw.js';
+import { b as ServerOptions, N as NarsilServer } from './capabilities-DlYw0Ov0.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 './capabilities-DlYw0Ov0.js';
+import { a as Narsil } from './engine-Dj4I91Jv.js';
+import { d as TaskProgress, b as ImportResult, h as TaskStore, e as TaskRecord } from './tasks-Df73Tjgq.js';
+export { C as CapabilitiesResponse, a as CreateIndexEmbedding, i as CreateIndexRequest, H as HttpIndexConfig, I as ImportError, M as MemoryStatsResponse, T as TaskListPage, c as TaskListQuery, f as TaskStatus, g as TaskType } from './tasks-Df73Tjgq.js';
+import './schema-mLpXZBEh.js';
 import './adapters-79OIa4xm.js';
-import './config-qMLpi5T4.js';
-import './config-BcYZkdMw.js';
-import './schema-OSWaaZzx.js';
-import './types-LEzMyjVX.js';
+import './config-CNas6wJH.js';
+import './config-bXxnJrQc.js';
+import './types-BTIVO8DI.js';
 import './types-D5OwhtsQ.js';
 
 /**
@@ -59,6 +59,9 @@ type TaskOperation = (ctx: TaskContext) => Promise<void>;
  * @param options - Address, CORS, request limits, the authentication hook, and
  * the task store. Omit it to bind to loopback with the default limits.
  * @returns The server, ready for {@link NarsilServer.listen}.
+ * @throws A `NarsilError` with `CONFIG_INVALID` where the first argument is
+ * some value other than an engine, and where a field of `options.limits` holds
+ * a value outside its range.
  *
  * @public
  */

package/dist/server.mjs

@@ -1,14 +1,14 @@
-import { DEFAULT_MAX_RETAINED_TASKS, loadUWebSockets, resolveCors, authorizerFor, createSharedGateBuffer, gateSlotOfWorker, createRouteRunner, corsWriter, createSharedRequestGate, MAIN_THREAD_GATE_SLOT, registerServerRoutes, DEFAULT_MAX_CONCURRENT_TASKS, DEFAULT_MAX_TASK_PAGE_SIZE, DEFAULT_MAX_IMPORT_ERRORS, DEFAULT_MAX_FETCH_DOCUMENTS, DEFAULT_MAX_RESULT_WINDOW, DEFAULT_MAX_CONCURRENT_REQUESTS, DEFAULT_IMPORT_BATCH_SIZE, DEFAULT_MAX_LINE_BYTES, DEFAULT_MAX_IMPORT_BYTES, DEFAULT_MAX_BODY_BYTES, RUNNING_TASK_TTL_MS, DEFAULT_TASK_PAGE_SIZE, TERMINAL_TASK_TTL_MS, TASK_PROGRESS_WRITE_INTERVAL_MS, serializeNarsilError, acceptorOf, createDocumentReadHandlers, sendError, respondError, respondJson, MAX_INDEX_TOUCH_INTERVAL_MS, INDEX_TOUCH_INTERVALS_PER_IDLE_TIMEOUT, clearGateSlot, parseJson, validateCreateIndex, rejectInvalid, validateBatch, serializeBatchResult, validateDocumentBody, validateSuggest, validateQuery, parseTaskListQuery, parseJsonOptional, validateRebalance, sendBinary, IMPORT_FLUSHES_IN_FLIGHT, badRequest, SERVER_CAPABILITIES } from './chunk-EY2ULUMT.mjs';
-export { ASYNC_IMPORT_CAPABILITY, INDEX_LIFECYCLE_CAPABILITY, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, httpStatusForNarsilError } from './chunk-EY2ULUMT.mjs';
-import { validateIndexName } from './chunk-72AXTIBW.mjs';
-import { engineCoreOf, providedDocId, resolveVectorText } from './chunk-U36IDJN7.mjs';
+import { DEFAULT_MAX_RETAINED_TASKS, loadUWebSockets, resolveCors, authorizerFor, createSharedGateBuffer, gateSlotOfWorker, createRouteRunner, corsWriter, createSharedRequestGate, MAIN_THREAD_GATE_SLOT, registerServerRoutes, DEFAULT_MAX_CONCURRENT_TASKS, DEFAULT_MAX_TASK_PAGE_SIZE, DEFAULT_MAX_IMPORT_ERRORS, DEFAULT_MAX_FETCH_DOCUMENTS, DEFAULT_MAX_RESULT_WINDOW, DEFAULT_MAX_CONCURRENT_REQUESTS, DEFAULT_IMPORT_BATCH_SIZE, DEFAULT_MAX_LINE_BYTES, DEFAULT_MAX_IMPORT_BYTES, DEFAULT_MAX_BODY_BYTES, RUNNING_TASK_TTL_MS, DEFAULT_TASK_PAGE_SIZE, TERMINAL_TASK_TTL_MS, TASK_PROGRESS_WRITE_INTERVAL_MS, serializeNarsilError, createVersionHandler, acceptorOf, createDocumentReadHandlers, sendError, respondError, respondJson, MAX_INDEX_TOUCH_INTERVAL_MS, INDEX_TOUCH_INTERVALS_PER_IDLE_TIMEOUT, clearGateSlot, parseJson, validateCreateIndex, rejectInvalid, validateBatch, serializeBatchResult, validateDocumentBody, validateSuggest, validateQuery, parseTaskListQuery, parseJsonOptional, validateRebalance, sendBinary, IMPORT_FLUSHES_IN_FLIGHT, badRequest, SERVER_CAPABILITIES, toHttpError, MIN_UNBOUNDED_SERVER_LIMIT, MIN_COUNTED_SERVER_LIMIT } from './chunk-RGS7FMCB.mjs';
+export { ASYNC_IMPORT_CAPABILITY, INDEX_LIFECYCLE_CAPABILITY, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, httpStatusForNarsilError } from './chunk-RGS7FMCB.mjs';
+import { validateIndexName } from './chunk-NTZYA3SJ.mjs';
+import { engineCoreOf, providedDocId, resolveVectorText } from './chunk-4NVPQ6S5.mjs';
 import { detectRuntime } from './chunk-AV4IJKD2.mjs';
-import './chunk-3GWP2TO6.mjs';
-import './chunk-ZT5BRDFW.mjs';
-import './chunk-WFKIGEBY.mjs';
+import './chunk-D2S642IV.mjs';
+import './chunk-L225SHNB.mjs';
+import './chunk-UTOFOJOR.mjs';
 import { startIdleHeapCleanup } from './chunk-Y3L5MDRV.mjs';
-import { NarsilError, ServerErrorCodes, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
-export { ServerErrorCodes } from './chunk-P4ELXVJQ.mjs';
+import { NarsilError, ErrorCodes, ServerErrorCodes, isNarsilError } from './chunk-FRQVMFY7.mjs';
+export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes, isNarsilError } from './chunk-FRQVMFY7.mjs';
 import { randomUUID } from 'crypto';
 import { MessageChannel } from 'worker_threads';
 
@@ -748,12 +748,48 @@ function createSearchHandlers(deps) {
   return { search, preflight, suggest };
 }
 
-// src/server/handlers/version.ts
-function createVersionHandler(deps) {
-  function report(ctx) {
-    respondJson(ctx, { name: "narsil", ...deps.build });
+// src/server/options-validation.ts
+var ENGINE_METHOD_SAMPLE = ["createIndex", "listIndexes", "insert", "query", "get", "shutdown"];
+var LIMITS_UNBOUNDED_AT_ZERO = [
+  "maxBodyBytes",
+  "maxImportBytes",
+  "maxLineBytes",
+  "maxImportErrors",
+  "maxConcurrentRequests",
+  "maxConcurrentTasks"
+];
+var COUNTED_LIMITS = ["importBatchSize", "maxResultWindow", "maxFetchDocuments", "maxTaskPageSize"];
+function assertServerEngine(engine) {
+  const candidate = engine;
+  if (typeof candidate !== "object" || candidate === null) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      "The first argument to createServer must be the engine that createNarsil returns, with the options second",
+      { received: candidate === null ? "null" : typeof candidate }
+    );
   }
-  return { report };
+  const members = candidate;
+  const missing = ENGINE_METHOD_SAMPLE.filter((method) => typeof members[method] !== "function");
+  if (missing.length === 0) return;
+  throw new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    `The first argument to createServer offers no ${missing.join(", ")}, so it is some value other than the engine that createNarsil returns`,
+    { missing }
+  );
+}
+function assertLimit(field, value, minimum) {
+  if (value === void 0) return;
+  if (Number.isInteger(value) && value >= minimum) return;
+  throw new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    `limits.${field} must be a whole number of at least ${minimum}; however, this configuration sets it to ${String(value)}`,
+    { field, value, minimum }
+  );
+}
+function assertServerLimits(limits) {
+  if (limits === void 0) return;
+  for (const field of LIMITS_UNBOUNDED_AT_ZERO) assertLimit(field, limits[field], MIN_UNBOUNDED_SERVER_LIMIT);
+  for (const field of COUNTED_LIMITS) assertLimit(field, limits[field], MIN_COUNTED_SERVER_LIMIT);
 }
 
 // src/server/request-threads/captured-response.ts
@@ -885,8 +921,8 @@ async function answerEmbed(core, request) {
       error: null
     };
   } catch (err) {
-    const error = err instanceof NarsilError ? serializeNarsilError(err) : { code: "INTERNAL_ERROR", message: err instanceof Error ? err.message : String(err) };
-    return { type: "embedded", requestId: request.requestId, value: null, error };
+    if (!isNarsilError(err)) console.warn("Embedding a query for a request thread failed:", err);
+    return { type: "embedded", requestId: request.requestId, value: null, error: toHttpError(err).body };
   }
 }
 function touchIntervalFor(copyIdleTimeoutMs) {
@@ -989,6 +1025,12 @@ async function startRequestThreads(options) {
   };
 }
 
+// src/server/task-status.ts
+var TERMINAL_TASK_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled"]);
+function isTerminalTaskStatus(status) {
+  return TERMINAL_TASK_STATUSES.has(status);
+}
+
 // src/server/task-store.ts
 var InMemoryTaskStore = class {
   /**
@@ -1041,7 +1083,7 @@ var InMemoryTaskStore = class {
     if (this.records.size <= this.maxRetained) return;
     for (const [id, record] of this.records) {
       if (this.records.size <= this.maxRetained) break;
-      if (record.status === "succeeded" || record.status === "failed") this.records.delete(id);
+      if (isTerminalTaskStatus(record.status)) this.records.delete(id);
     }
   }
 };
@@ -1118,7 +1160,7 @@ var TaskRegistry = class {
   async cancel(id) {
     const stored = await this.store.get(id);
     if (!stored) return { outcome: "not-found", record: null };
-    if (stored.status !== "running" && stored.status !== "queued") {
+    if (isTerminalTaskStatus(stored.status)) {
       return { outcome: "already-finished", record: stored };
     }
     const task = this.live.get(id);
@@ -1147,7 +1189,7 @@ var TaskRegistry = class {
     }
     for (const record of records) {
       if (record.owner !== this.instanceId) continue;
-      if (record.status !== "running" && record.status !== "queued") continue;
+      if (isTerminalTaskStatus(record.status)) continue;
       const failed = {
         ...record,
         status: "failed",
@@ -1301,6 +1343,8 @@ var NarsilHttpServer = class {
   threads = null;
   stopIdleHeapCleanup = () => void 0;
   constructor(engine, options = {}) {
+    assertServerEngine(engine);
+    assertServerLimits(options.limits);
     this.host = options.host ?? "127.0.0.1";
     this.port = options.port ?? 9876;
     this.options = options;
@@ -1356,6 +1400,10 @@ var NarsilHttpServer = class {
       await threads.stop();
     }
   }
+  async shutdown() {
+    await this.close();
+    await this.engine.shutdown();
+  }
   get listeningPort() {
     if (!this.listenSocket || !this.uws) return -1;
     return this.uws.us_socket_local_port(this.listenSocket);
@@ -1377,7 +1425,7 @@ var NarsilHttpServer = class {
       writeCors: cors ? corsWriter(cors) : void 0
     });
     registerServerRoutes(app, run, handlers, limits, cors);
-    if (core === void 0 || !detectRuntime().supportsWorkerThreads) return;
+    if (core === void 0 || threadCount === 0 || !detectRuntime().supportsWorkerThreads) return;
     try {
       this.threads = await startRequestThreads({ core, app, handlers, authorize, gate, limits, build, cors });
     } catch (err) {

package/dist/{tasks-DiF1c9v2.d.ts → tasks-Df73Tjgq.d.ts}

@@ -1,4 +1,4 @@
-import { M as MemoryStats } from './memory-OmgkX_Z2.js';
+import { M as MemoryStats } from './memory-xrXOZMbw.js';
 
 /** Declarative index configuration accepted over HTTP. Function-valued engine
  * options (custom tokenizer, stopWords-as-function, group reducer, embedding
@@ -144,12 +144,16 @@ type TaskType = 'optimizeVectors' | 'rebalance' | 'restore' | 'import' | 'rebuil
 /**
  * Where a long-running operation stands.
  *
- * A task reaches `cancelled` only when the work itself stopped early, so a
- * cancel that arrives too late leaves the task `succeeded`.
+ * A task starts `running`, because the server begins the work as it accepts
+ * the request. Where the server already drives
+ * {@link ServerLimits.maxConcurrentTasks} tasks, it answers 429
+ * `TOO_MANY_REQUESTS` and starts none. A task reaches `cancelled` only where
+ * the work itself stops early, so a cancel that arrives too late leaves the
+ * task `succeeded`.
  *
  * @public
  */
-type TaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+type TaskStatus = 'running' | 'succeeded' | 'failed' | 'cancelled';
 /**
  * How far a running import has gone, which is what a progress bar reads.
  *
@@ -192,7 +196,7 @@ interface TaskRecord {
     owner: string;
     /** The server accepted the task at this many milliseconds since the epoch. */
     createdAt: number;
-    /** Work started at this many milliseconds since the epoch, and a queued task omits it. */
+    /** Work started at this many milliseconds since the epoch. */
     startedAt?: number;
     /** Work ended at this many milliseconds since the epoch, and a task omits it until it reaches a final status. */
     completedAt?: number;

package/dist/{thread-TLCX43WV.mjs → thread-5UP6MGED.mjs}

@@ -1,12 +1,12 @@
-import { loadUWebSockets, childAppOf, createRouteRunner, corsWriter, createSharedRequestGate, registerServerRoutes, sendRelayed, createDocumentReadHandlers, respondJson, SERVER_CAPABILITIES, sendError, serverRoutes, parseJson, validateSuggest, rejectInvalid, respondError, validateQuery } from './chunk-EY2ULUMT.mjs';
-import { executeListDocuments, executeSuggest, executePreflight, queryBindingOf, executeQuery } from './chunk-YPYULM5E.mjs';
-import './chunk-3GWP2TO6.mjs';
-import { resolveProjection, projectionKeepsField, setNestedValue } from './chunk-WM7IS45M.mjs';
-import { extractVectorFieldsFromSchema } from './chunk-ZT5BRDFW.mjs';
+import { loadUWebSockets, childAppOf, createRouteRunner, corsWriter, createSharedRequestGate, registerServerRoutes, sendRelayed, createDocumentReadHandlers, respondJson, SERVER_CAPABILITIES, versionReport, sendError, serverRoutes, parseJson, validateSuggest, rejectInvalid, respondError, validateQuery } from './chunk-RGS7FMCB.mjs';
+import { executeListDocuments, executeSuggest, executePreflight, queryBindingOf, executeQuery } from './chunk-TVT5V4E7.mjs';
+import './chunk-D2S642IV.mjs';
+import { resolveProjection, projectionKeepsField, setNestedValue } from './chunk-5T6AOR37.mjs';
+import { extractVectorFieldsFromSchema } from './chunk-L225SHNB.mjs';
 import './chunk-ZJ4CSAB2.mjs';
-import './chunk-WFKIGEBY.mjs';
+import './chunk-UTOFOJOR.mjs';
 import './chunk-2GWVQWGA.mjs';
-import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
+import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-FRQVMFY7.mjs';
 
 // src/server/request-threads/held-vectors.ts
 function managerWithHeldVectors(manager, fieldPaths, vectorOf) {
@@ -348,7 +348,7 @@ function threadHandlers(local, relay, settings) {
   return {
     ...forwarded,
     livez: (ctx) => respondJson(ctx, { status: "ok" }),
-    version: (ctx) => respondJson(ctx, { name: "narsil", ...settings.build }),
+    version: (ctx) => respondJson(ctx, versionReport(settings.build)),
     capabilities: (ctx) => respondJson(ctx, { capabilities: [...SERVER_CAPABILITIES] }),
     search: searchHandler({
       fallback: forwarded.search,

package/dist/{types-LEzMyjVX.d.ts → types-BTIVO8DI.d.ts}

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

package/dist/vector/search-worker.d.ts

@@ -1,4 +1,4 @@
-import { d as VectorQuantizationMode } from '../schema-OSWaaZzx.js';
+import { d as VectorQuantizationMode } from '../schema-mLpXZBEh.js';
 import { A as ArenaSimd } from '../simd-DW5AtJ6B.js';
 import '../adapters-79OIa4xm.js';