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

package/README.md

@@ -1,4 +1,4 @@
-![Narsil, a distributed search engine](https://raw.githubusercontent.com/assetcorp/narsil/main/assets/banner.png)
+![Narsil, an open source search engine](https://raw.githubusercontent.com/assetcorp/narsil/main/assets/banner.png)
 
 # Narsil
 
@@ -8,15 +8,19 @@
 [![types](https://img.shields.io/badge/types-TypeScript-blue)](https://www.npmjs.com/package/@delali/narsil)
 [![license](https://img.shields.io/npm/l/@delali/narsil)](https://github.com/assetcorp/narsil/blob/main/LICENSE)
 
-Distributed search, reforged.
+The search engine that scales with your data.
 
-Narsil is a distributed search engine with full-text, vector, hybrid, and geosearch. One codebase runs in two contexts: embedded in your application process, where queries answer without a network hop, and as a standalone search server with a REST API, a write-ahead log, and bulk NDJSON ingest. Both contexts run the same engine and store indexes in the same cross-language binary format (.nrsl), so an index built in one loads in the other.
+Narsil is an open source search engine with full-text, vector, hybrid, and geosearch on one typed index. You can embed Narsil in your application process, where the engine searches without a network hop, or deploy it as a standalone search server with a REST API, a write-ahead log, and bulk NDJSON ingest. Both forms contain the same engine, which stores indexes in one cross-language binary format (`.nrsl`), so you can load an index from one form into the other.
 
-The engine partitions large indexes across workers and merges partition results into a single ranked answer. Its BM25 ranking matches the Anserini reference within 0.006 nDCG@10 on the BEIR datasets. On BEIR SciFact it takes the top nDCG@10 at 0.681, narrowly ahead of Elasticsearch and OpenSearch at 0.679, and answers 958 keyword queries per second against their 841 and 878 ([benchmarks](https://github.com/assetcorp/narsil/blob/main/BENCHMARKS.md)). This TypeScript package is the reference implementation of the cross-language `.nrsl` format, and a second-language port in Go or Rust is the headline item on the [roadmap](https://github.com/assetcorp/narsil/blob/main/ROADMAP.md).
+The engine partitions large indexes across workers and merges the results of the partitions into a single ranked list. This TypeScript package is the reference implementation of the `.nrsl` format, so a second implementation in Go or Rust is the headline item on the [roadmap](https://github.com/assetcorp/narsil/blob/main/ROADMAP.md).
+
+<!-- BENCH:headline START -->
+On BEIR SciFact, Narsil's BM25 ranking scores 0.681 nDCG@10, which is within 0.002 of the Anserini reference of 0.679. Elasticsearch scores 0.679 and OpenSearch scores 0.679 on the same queries. On SciFact, Narsil answers 958 keyword queries a second at its peak, and OpenSearch follows with 878. On SciFact with every engine held at 0.99 recall, Narsil answers 259 vector queries a second at its peak, while OpenSearch leads with 730. Narsil has the highest peak throughput in 2 of the 6 keyword, vector, and hybrid comparisons in the newest recorded run, so read each figure beside its table. The harness recorded these figures in run `20260804T184221Z` on 2026-08-04, on GCP c3-standard-8, us-central1-a. You'll find every dataset, every engine's settings, and the full method in [`BENCHMARKS.md`](https://github.com/assetcorp/narsil/blob/main/BENCHMARKS.md).
+<!-- BENCH:headline END -->
 
 Try it in your browser at [narsil.sondelali.com/demo](https://narsil.sondelali.com/demo). Read the full documentation at [narsil.sondelali.com/docs](https://narsil.sondelali.com/docs).
 
-> *narsil* is the sword of Elendil in Tolkien's Lord of the Rings, shattered into shards and later reforged. The name maps to the architecture: data shatters into partitions, the engine persists each shard on its own, and every query reforges them into one ranked answer.
+> *narsil* is the sword of Elendil in Tolkien's Lord of the Rings, shattered into shards and later reforged. The name fits the design, because the engine splits your data into partitions that it persists one by one, then merges their results into one ranked list for each query.
 
 ## Contents
 
@@ -36,7 +40,9 @@ Try it in your browser at [narsil.sondelali.com/demo](https://narsil.sondelali.c
 pnpm add @delali/narsil
 ```
 
-Narsil requires Node.js 22 or newer. It also runs in Bun, Deno, and browsers; see [Runtime support](#runtime-support).
+Narsil works in Node.js 22 or newer, and in Bun, Deno, and browsers. The [Runtime support](#runtime-support) table covers each runtime.
+
+On an arm64 or x64 machine under macOS, Linux, or Windows, the package manager also installs Narsil's native search core as an optional dependency, and the engine searches vector graphs through it. If you omit optional dependencies, Narsil searches those graphs through WebAssembly, with the same results, as it always does in a browser.
 
 ## Quick start
 
@@ -79,21 +85,21 @@ const results = await narsil.query('products', {
 })
 ```
 
-Every hit holds the document, its id, and its BM25 score. `results.count` reports how many documents matched in total, `results.elapsed` reports the query time in milliseconds, and `results.coverage` reports how many partitions the search read, which is how you spot a cluster that answered from part of its data.
+Every hit holds the document, its id, and its BM25 score. Beside the hits, `results.count` holds the total number of matching documents, `results.elapsed` holds the query time in milliseconds, and `results.coverage` counts the partitions that the search covered, so you can tell when a cluster returns results from part of its data.
 
 ## Features
 
-**Search.** [Full-text search](https://github.com/assetcorp/narsil/blob/main/docs/full-text-search.md) scores with BM25 and supports field boosting, fuzzy matching through bounded Levenshtein distance, search as you type through last-word prefix matching, and term-coverage and score thresholds. Queries compose with [filters, facets, sorting, grouping, cursor pagination, and pinned results](https://github.com/assetcorp/narsil/blob/main/docs/filters-facets-and-pagination.md).
+**Search.** For [full-text search](https://github.com/assetcorp/narsil/blob/main/docs/full-text-search.md), the engine scores with BM25 and supports field boosting, fuzzy matching through bounded Levenshtein distance, search as you type through last-word prefix matching, and term-coverage and score thresholds. You can combine a query with [filters, facets, sorting, grouping, cursor pagination, and pinned results](https://github.com/assetcorp/narsil/blob/main/docs/filters-facets-and-pagination.md).
 
-**Vector and hybrid retrieval.** [Vector search](https://github.com/assetcorp/narsil/blob/main/docs/vector-search.md) serves cosine, dot-product, and Euclidean queries, starts on an exact scan, and promotes a field to an HNSW graph as it grows, with scalar quantization on by default. [Hybrid search](https://github.com/assetcorp/narsil/blob/main/docs/hybrid-search.md) fuses BM25 and vector rankings through reciprocal rank fusion or linear blending, and [embedding adapters](https://github.com/assetcorp/narsil/blob/main/docs/embedding-adapters.md) turn text into vectors on insert and query, through OpenAI, local Transformers.js models, or an adapter of your own.
+**Vector and hybrid retrieval.** For [vector search](https://github.com/assetcorp/narsil/blob/main/docs/vector-search.md), the engine compares vectors by cosine similarity, dot product, or Euclidean distance. It scans a field exactly until the field holds 1,024 vectors, a count that you can change, after which it builds an HNSW graph with optimised scalar quantization on by default. Outside a browser, on an arm64 or x64 machine under macOS, Linux, or Windows, the engine searches that graph through a [native core in C](https://github.com/assetcorp/narsil/blob/main/docs/vector-search.md#native-search-core), which returns the same results as its WebAssembly search. For [hybrid search](https://github.com/assetcorp/narsil/blob/main/docs/hybrid-search.md), the engine fuses BM25 and vector rankings through reciprocal rank fusion or linear blending. [Embedding adapters](https://github.com/assetcorp/narsil/blob/main/docs/embedding-adapters.md) turn text into vectors on insert and query, through OpenAI, local Transformers.js models, or an adapter of your own.
 
-**Geosearch.** [Geo filters](https://github.com/assetcorp/narsil/blob/main/docs/geosearch.md) match by radius, using Haversine or Vincenty distance, or by polygon containment, and they compose with every other query feature.
+**Geosearch.** [Geo filters](https://github.com/assetcorp/narsil/blob/main/docs/geosearch.md) match documents by radius, using Haversine or Vincenty distance, or by polygon containment. You can combine a geo filter with every other query feature.
 
-**Storage.** [Persistence adapters](https://github.com/assetcorp/narsil/blob/main/docs/persistence-and-durability.md) plug in filesystem, IndexedDB, memory, or custom backends. Durability adds a write-ahead log with periodic checkpoints and automatic recovery, and snapshots capture a whole index as one portable byte array.
+**Storage.** [Persistence adapters](https://github.com/assetcorp/narsil/blob/main/docs/persistence-and-durability.md) store indexes on the filesystem, in IndexedDB, in memory, or in a backend of your own. With durability on, the engine keeps a write-ahead log with periodic checkpoints and recovers on its own after a crash. A snapshot captures a whole index as one portable byte array.
 
-**Scale.** [Partitioned indexes](https://github.com/assetcorp/narsil/blob/main/docs/partitions-and-workers.md) route documents by deterministic hash and reshape online through `rebalance()`, with writes buffering in a write-ahead queue during the reshape. Worker copies answer keyword queries on half the worker threads once an index holds 1,000 documents, and the HTTP server receives requests on the threads that hold them.
+**Scale.** The engine routes each document to a [partition](https://github.com/assetcorp/narsil/blob/main/docs/partitions-and-workers.md) by a deterministic hash. When you call `rebalance()`, the engine reshapes the partitions online and buffers incoming writes in a write-ahead queue. Once an index holds 1,000 documents, the engine serves keyword queries from worker copies on half its worker threads, while the HTTP server receives requests on the threads that hold those copies.
 
-**Operations.** The [HTTP server](https://github.com/assetcorp/narsil/blob/main/docs/http-server.md) subpath wraps an engine in a REST API with health probes, bulk NDJSON import, snapshot and restore endpoints, and task-based long operations. The [client](https://github.com/assetcorp/narsil/blob/main/docs/client.md) subpath reaches every one of those routes from a browser or from Node under the engine's own method names, and the [React](https://github.com/assetcorp/narsil/blob/main/docs/react.md) subpath gives those methods to components as hooks. [Events, plugins, and memory reporting](https://github.com/assetcorp/narsil/blob/main/docs/observability.md) cover observability, and [language modules](https://github.com/assetcorp/narsil/blob/main/docs/language-support.md) cover 107 languages as separate entry points, 20 of them African.
+**Operations.** The [HTTP server](https://github.com/assetcorp/narsil/blob/main/docs/http-server.md) subpath wraps an engine in a REST API with health probes, bulk NDJSON import, snapshot and restore endpoints, and task-based long operations. The [client](https://github.com/assetcorp/narsil/blob/main/docs/client.md) subpath calls every one of those routes from a browser or from Node under the engine's own method names. The [React](https://github.com/assetcorp/narsil/blob/main/docs/react.md) subpath exposes those methods to components as hooks. For observability, you get [events, plugins, and memory reporting](https://github.com/assetcorp/narsil/blob/main/docs/observability.md). [Language modules](https://github.com/assetcorp/narsil/blob/main/docs/language-support.md) cover 107 languages as separate entry points, including 20 African languages.
 
 ## Documentation
 
@@ -103,7 +109,7 @@ Every hit holds the document, its id, and its BM25 score. `results.count` report
 | [Indexes and documents](../../docs/indexes-and-documents.md) | Schemas, index management, inserts, reads, updates, removals, and batch operations |
 | [Full-text search](../../docs/full-text-search.md) | Term queries, fuzzy matching, prefix completion, thresholds, highlighting, scoring modes, and suggestions |
 | [Filters, facets, and pagination](../../docs/filters-facets-and-pagination.md) | Field, array, presence, and geo filters, facet counts, sorting, grouping, cursors, and pinning |
-| [Vector search](../../docs/vector-search.md) | Vector fields, distance metrics, HNSW promotion, quantization, and graph maintenance |
+| [Vector search](../../docs/vector-search.md) | Vector fields, distance metrics, HNSW promotion, quantization, the native search core, and graph maintenance |
 | [Hybrid search](../../docs/hybrid-search.md) | Reciprocal rank fusion and linear blending of text and vector rankings |
 | [Geosearch](../../docs/geosearch.md) | Radius and polygon filters, and the two distance formulas |
 | [Embedding adapters](../../docs/embedding-adapters.md) | Automatic embedding on insert and query, named adapters, the bundled ones, and custom ones |
@@ -111,42 +117,42 @@ Every hit holds the document, its id, and its BM25 score. `results.count` report
 | [Partitions and workers](../../docs/partitions-and-workers.md) | Partition routing, online rebalancing, worker copies, and multi-instance invalidation |
 | [Language support](../../docs/language-support.md) | The 107 language modules, analysis revisions and rebuilds, and named tokenizers and stop words |
 | [HTTP server](../../docs/http-server.md) | Wrapping an engine in a REST API, every route it serves, and long-running tasks |
-| [Cluster mode](../../docs/cluster.md) | Multi-node indexes: nodes and roles, replication, routed writes, distributed searches and reads, and what a cluster refuses |
+| [Cluster mode](../../docs/cluster.md) | Multi-node indexes: nodes and roles, replication, routed writes, distributed searches and reads, and the calls that fail in a cluster |
 | [Client](../../docs/client.md) | Reaching a server from a browser or Node, following a task, and the codes it raises |
 | [React](../../docs/react.md) | The hooks over the client, one shared request per key, and loading a corpus from a component |
 | [Observability](../../docs/observability.md) | Plugin hooks, engine events, and memory reporting |
 | [Errors](../../docs/errors.md) | Every error code and what throws it |
 
-The [specification](../spec/) defines the `.nrsl` format, the analysis pipeline, and the replication invariants that every implementation follows.
+The [specification](../spec/) defines the `.nrsl` format, the analysis pipeline, and the replication invariants that every implementation must uphold.
 
 ## Examples
 
 | Example | What it shows |
 | --- | --- |
-| [HTTP server](examples/http-server/README.md) | The launcher runs the engine as a REST service with durability, API-key auth, and Docker packaging, and its README documents the full API surface. |
+| [HTTP server](examples/http-server/README.md) | The launcher serves the engine as a REST service with durability, API-key auth, and Docker packaging, and every setting comes from the environment. |
 | [Browser](examples/browser/README.md) | The app embeds the engine in a browser with IndexedDB persistence and Web Worker search. |
-| [Server app](examples/server-app/README.md) | The app reaches the HTTP server through the client SDK and the React hooks, loads corpora as import tasks, and answers questions from them in an Ask view. |
+| [Server app](examples/server-app/README.md) | The app calls the HTTP server through the client SDK and the React hooks to load corpora as import tasks. In its Ask view, you can ask questions about those corpora. |
 
 ## Distribution
 
-`@delali/narsil/distribution` holds Narsil's multi-node cluster mode: nodes and roles, replication, coordinator adapters for etcd and in-process testing, TCP and gRPC transports with mutual TLS, and distributed query routing. A cluster node creates, drops, clears, writes, updates, searches, lists, counts, and suggests across every partition, and the [cluster dashboard example](examples/cluster-dashboard) runs three nodes against etcd and shows what each partition does while you cut the links between them. The layer is experimental and its APIs change without notice, so pin an exact version before you depend on it. The [cluster guide](../../docs/cluster.md) covers the surface, and [`packages/spec/distribution`](../spec/distribution) specifies the contract every implementation follows.
+`@delali/narsil/distribution` holds Narsil's multi-node cluster mode: nodes and roles, replication, coordinator adapters for etcd and in-process testing, TCP and gRPC transports with mutual TLS, and distributed query routing. A cluster node can create, drop, clear, write, update, search, list, count, and suggest across every partition. The [cluster dashboard example](examples/cluster-dashboard) starts three nodes against etcd and shows the state of each partition while you cut the network links. Because the layer is experimental and we may change its APIs without notice, pin an exact version before you depend on it. The [cluster guide](../../docs/cluster.md) covers the API. For the contract that every implementation must uphold, read [`packages/spec/distribution`](../spec/distribution).
 
 ## Search quality
 
-Ranking quality is measured against the [BEIR](https://github.com/beir-cellar/beir) SciFact corpus, 5,183 documents with 300 judged queries, where a human relevance judgment scores each query-document pair. Narsil runs in one process against Orama and MiniSearch, and every engine uses identical stop words (Lucene English, 33 terms) and default BM25 parameters, while each one stems English with its own implementation. Narsil takes the top nDCG@10 of the three.
+We measure ranking quality on the [BEIR](https://github.com/beir-cellar/beir) SciFact corpus, which holds 5,183 documents and 300 queries with human relevance judgements. We compare Narsil with Orama and MiniSearch in one process. All three use the same 33 Lucene English stop words and default BM25 parameters, although each one stems English in its own way. Narsil has the top nDCG@10 of the three.
 
 **What these metrics mean:**
 
-- **nDCG@10** measures whether the most relevant documents appear near the top of the results. A score of 1.0 means perfect ranking, and 0.0 means no relevant documents appear in the top 10.
+- **nDCG@10** measures whether the most relevant documents appear near the top of the results. A score of 1.0 means a perfect ranking, while 0.0 means that no relevant document appears in the top 10.
 - **P@10** is the fraction of the top 10 results that are relevant.
-- **MAP** tracks precision at every rank where a relevant document appears. A higher MAP means relevant documents cluster near the top of the ranking.
-- **MRR** measures how soon the first relevant result appears. A higher value puts the first relevant document nearer the top.
+- **MAP** tracks precision at every rank where a relevant document appears. A higher MAP means that relevant documents cluster near the top of the ranking.
+- **MRR** measures how soon the first relevant result appears. A higher MRR means that the first relevant document appears nearer the top.
 
-A separate [SciFact regression test](src/__tests__/relevance/scifact.test.ts) runs in CI on the same corpus and fails the build if ranking quality drops below calibrated thresholds.
+Continuous integration executes a separate [SciFact regression test](src/__tests__/relevance/scifact.test.ts) on the same corpus. That test fails the build when ranking quality drops below calibrated thresholds.
 
-Reproduce these scores with `pnpm --filter benchmarks bench -- --tiers relevance`. The full quality, throughput, latency, and memory tables for all three engines are in [BENCHMARKS.md](https://github.com/assetcorp/narsil/blob/main/BENCHMARKS.md).
+Reproduce these scores with `pnpm --filter benchmarks bench -- --tiers relevance`. [BENCHMARKS.md](https://github.com/assetcorp/narsil/blob/main/BENCHMARKS.md) holds the full quality, throughput, and latency tables for all three engines.
 
-Narsil also runs as a search server. On the BEIR information-retrieval datasets it is measured against Elasticsearch, OpenSearch, Qdrant, Weaviate, Typesense, and Meilisearch across keyword, vector, and hybrid retrieval. See [the full benchmarks](https://github.com/assetcorp/narsil/blob/main/BENCHMARKS.md) for those results.
+Narsil also works as a search server. On the BEIR datasets, we compare the server with Elasticsearch, OpenSearch, Qdrant, Weaviate, Typesense, and Meilisearch across keyword, vector, and hybrid retrieval. See [the full benchmarks](https://github.com/assetcorp/narsil/blob/main/BENCHMARKS.md) for those results.
 
 ## Runtime support
 
@@ -157,7 +163,7 @@ Narsil also runs as a search server. On the BEIR information-retrieval datasets
 | Deno | Web Workers | Filesystem | BroadcastChannel |
 | Browser | Web Workers | IndexedDB | BroadcastChannel |
 
-The [browser example](examples/browser/README.md) shows an embedded engine with IndexedDB persistence, and the [server app example](examples/server-app/README.md) shows the same UI over the client SDK and the React hooks.
+The [browser example](examples/browser/README.md) shows an embedded engine with IndexedDB persistence, while the [server app example](examples/server-app/README.md) shows the same interface over the client SDK and the React hooks.
 
 ## License
 

package/dist/adapters/filesystem.mjs

@@ -1,4 +1,4 @@
-import { NarsilError, ErrorCodes } from '../chunk-P4ELXVJQ.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-FRQVMFY7.mjs';
 
 // src/persistence/filesystem.ts
 var cachedFs = null;

package/dist/adapters/indexeddb.mjs

@@ -1,4 +1,4 @@
-import { NarsilError, ErrorCodes } from '../chunk-P4ELXVJQ.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-FRQVMFY7.mjs';
 
 // src/persistence/constants.ts
 var DEFAULT_INDEXEDDB_NAME = "narsil";

package/dist/{capabilities-BWm4IITU.d.ts → capabilities-DlYw0Ov0.d.ts}

@@ -1,6 +1,6 @@
 import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
-import { C as ClusterNamespace } from './config-Czh2YNDi.js';
-import { h as TaskStore } from './tasks-DT7L1p6w.js';
+import { C as ClusterNamespace } from './config-CNas6wJH.js';
+import { h as TaskStore } from './tasks-Df73Tjgq.js';
 
 /**
  * Context handed to {@link OnRequestHook} for every inbound request, captured
@@ -181,6 +181,17 @@ interface NarsilServer {
     listen(): Promise<void>;
     /** Closes the socket and ends the server. The engine keeps running. */
     close(): Promise<void>;
+    /**
+     * Closes the server and then shuts the engine down, which is what a process
+     * whose work is this server calls on its way out.
+     *
+     * Shutting the engine down is what ends the request threads, so Node aborts
+     * a process that exits while one of those threads still holds a client
+     * connection. Call {@link NarsilServer.close} on its own where the engine
+     * keeps running after the server closes, as in a process that fronts one
+     * engine with two servers.
+     */
+    shutdown(): Promise<void>;
     /** The server bound to this port, which is what you read after binding to port 0. */
     readonly listeningPort: number;
     /**

package/dist/{chunk-KMMJMDUA.mjs → chunk-3L4U6EJQ.mjs}

@@ -1,5 +1,12 @@
+import { NATIVE_CRC32_MIN_BYTES } from './chunk-IFBKLBGB.mjs';
+import * as zlib from 'zlib';
+
+var candidate = zlib.crc32;
+var nativeCrc32 = typeof candidate === "function" ? candidate : null;
+
 // src/serialization/crc32.ts
 var IEEE_POLYNOMIAL = 3988292384;
+var ALL_BITS = 4294967295;
 var cachedTable = null;
 function buildTable() {
   const table = new Uint32Array(256);
@@ -18,18 +25,16 @@ function getTable() {
   }
   return cachedTable;
 }
-function crc32(data) {
-  const table = getTable();
-  let crc = 4294967295;
-  for (let i = 0; i < data.length; i++) {
-    crc = crc >>> 8 ^ table[(crc ^ data[i]) & 255];
-  }
-  return (crc ^ 4294967295) >>> 0;
+function crc322(data) {
+  return crc32Final(crc32Update(crc32Init(), data));
 }
 function crc32Init() {
-  return 4294967295;
+  return ALL_BITS;
 }
 function crc32Update(state, data) {
+  if (nativeCrc32 !== null && data.length >= NATIVE_CRC32_MIN_BYTES) {
+    return nativeCrc32(data, (state ^ ALL_BITS) >>> 0) ^ ALL_BITS;
+  }
   const table = getTable();
   let crc = state;
   for (let i = 0; i < data.length; i++) {
@@ -38,7 +43,7 @@ function crc32Update(state, data) {
   return crc;
 }
 function crc32Final(state) {
-  return (state ^ 4294967295) >>> 0;
+  return (state ^ ALL_BITS) >>> 0;
 }
 
-export { crc32, crc32Final, crc32Init, crc32Update };
+export { crc322 as crc32, crc32Final, crc32Init, crc32Update, nativeCrc32 };

package/dist/chunk-4NVPQ6S5.mjs

@@ -0,0 +1,366 @@
+import { validateRequiredFields } from './chunk-L225SHNB.mjs';
+import { ErrorCodes, NarsilError } from './chunk-FRQVMFY7.mjs';
+
+// src/narsil/internals.ts
+var engineCores = /* @__PURE__ */ new WeakMap();
+function bindEngineCore(engine, core) {
+  engineCores.set(engine, core);
+}
+function engineCoreOf(engine) {
+  return engineCores.get(engine);
+}
+
+// src/distribution/constants.ts
+var WIRE_BATCH_BUDGET = {
+  maxCount: 1e3,
+  maxBytes: 8388608,
+  overheadBytes: 256
+};
+var MAX_PARTITION_COUNT = 65536;
+var MAX_REPLICATION_FACTOR = 255;
+
+// src/engine/embed.ts
+function assertDocumentCarriesMappedVectors(document, embeddingConfig, adapterName) {
+  for (const targetField of Object.keys(embeddingConfig.fields)) {
+    const existing = resolveFieldValue(document, targetField);
+    if (existing === void 0 || existing === null) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_CONFIG_INVALID,
+        adapterName ? `The index embeds "${targetField}" via adapter "${adapterName}", which is not registered on this engine. Register the adapter or supply the vector on the document.` : `The index embeds "${targetField}" automatically but no embedding adapter is bound. Bind an adapter or supply the vector on the document.`,
+        adapterName ? { field: targetField, adapter: adapterName } : { field: targetField }
+      );
+    }
+  }
+}
+function validateVector(vector, targetField, expectedDimensions) {
+  if (!(vector instanceof Float32Array)) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_FAILED,
+      `Adapter returned ${typeof vector} for field "${targetField}", expected Float32Array`,
+      { field: targetField, returnedType: typeof vector }
+    );
+  }
+  if (vector.length !== expectedDimensions) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_DIMENSION_MISMATCH,
+      `Adapter returned ${vector.length}-dimensional vector for field "${targetField}", expected ${expectedDimensions}`,
+      { field: targetField, expected: expectedDimensions, actual: vector.length }
+    );
+  }
+  for (let i = 0; i < vector.length; i++) {
+    if (Number.isNaN(vector[i])) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_FAILED,
+        `Adapter returned vector with NaN at index ${i} for field "${targetField}"`,
+        { field: targetField, index: i }
+      );
+    }
+  }
+  return vector;
+}
+function resolveFieldValue(document, path) {
+  if (!path.includes(".")) return document[path];
+  const segments = path.split(".");
+  let current = document;
+  for (const segment of segments) {
+    if (current === null || current === void 0 || typeof current !== "object") return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function setFieldValue(document, path, value) {
+  if (!path.includes(".")) {
+    document[path] = value;
+    return;
+  }
+  const segments = path.split(".");
+  let current = document;
+  for (let i = 0; i < segments.length - 1; i++) {
+    let next = current[segments[i]];
+    if (next === null || next === void 0 || typeof next !== "object") {
+      next = {};
+      current[segments[i]] = next;
+    }
+    current = next;
+  }
+  current[segments[segments.length - 1]] = value;
+}
+function deleteFieldValue(document, path) {
+  if (!path.includes(".")) {
+    delete document[path];
+    return;
+  }
+  const segments = path.split(".");
+  let current = document;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const next = current[segments[i]];
+    if (next === null || next === void 0 || typeof next !== "object") return;
+    current = next;
+  }
+  delete current[segments[segments.length - 1]];
+}
+function collectSourceText(document, sourceFields, targetField, documentIndex) {
+  const sources = Array.isArray(sourceFields) ? sourceFields : [sourceFields];
+  const parts = [];
+  for (const source of sources) {
+    const value = resolveFieldValue(document, source);
+    if (value === void 0 || value === null || value === "") continue;
+    if (typeof value !== "string") {
+      throw new NarsilError(
+        ErrorCodes.DOC_VALIDATION_FAILED,
+        `Embedding source field "${source}" must be a string, got ${typeof value}`,
+        { field: source, targetField }
+      );
+    }
+    parts.push(value);
+  }
+  if (parts.length === 0) {
+    const details = { field: targetField };
+    if (documentIndex !== void 0) {
+      details.documentIndex = documentIndex;
+    }
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_NO_SOURCE,
+      `All source fields for embedding target "${targetField}" are missing or empty`,
+      details
+    );
+  }
+  return parts.join("\n");
+}
+function wrapAdapterError(err, targetField) {
+  if (err instanceof NarsilError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  return new NarsilError(ErrorCodes.EMBEDDING_FAILED, `Embedding failed for field "${targetField}": ${message}`, {
+    field: targetField,
+    cause: message
+  });
+}
+async function embedDocumentFields(document, embeddingConfig, adapter, signal) {
+  const embeddedFields = /* @__PURE__ */ new Set();
+  try {
+    for (const [targetField, sourceFields] of Object.entries(embeddingConfig.fields)) {
+      const existing = resolveFieldValue(document, targetField);
+      if (existing !== void 0 && existing !== null) continue;
+      const text = collectSourceText(document, sourceFields, targetField);
+      let vector;
+      try {
+        const raw = await adapter.embed(text, "document", signal);
+        vector = validateVector(raw, targetField, adapter.dimensions);
+      } catch (err) {
+        throw wrapAdapterError(err, targetField);
+      }
+      setFieldValue(document, targetField, vector);
+      embeddedFields.add(targetField);
+    }
+  } catch (err) {
+    for (const field of embeddedFields) {
+      deleteFieldValue(document, field);
+    }
+    throw err;
+  }
+  return embeddedFields;
+}
+var SOURCE_FAILURE_CODES = /* @__PURE__ */ new Set([
+  ErrorCodes.EMBEDDING_NO_SOURCE,
+  ErrorCodes.DOC_VALIDATION_FAILED
+]);
+function isDocumentSourceError(err) {
+  return err instanceof NarsilError && SOURCE_FAILURE_CODES.has(err.code);
+}
+async function embedBatchDocumentFields(documents, embeddingConfig, adapter, signal) {
+  const embedded = /* @__PURE__ */ new Map();
+  const failed = /* @__PURE__ */ new Map();
+  try {
+    for (const [targetField, sourceFields] of Object.entries(embeddingConfig.fields)) {
+      const needsEmbedding = [];
+      for (let i = 0; i < documents.length; i++) {
+        if (failed.has(i)) continue;
+        const doc = documents[i];
+        const existing = resolveFieldValue(doc, targetField);
+        if (existing !== void 0 && existing !== null) continue;
+        try {
+          const text = collectSourceText(doc, sourceFields, targetField, i);
+          needsEmbedding.push({ docIndex: i, text });
+        } catch (err) {
+          if (isDocumentSourceError(err)) {
+            failed.set(i, err);
+          } else {
+            throw err;
+          }
+        }
+      }
+      if (needsEmbedding.length === 0) continue;
+      const texts = needsEmbedding.map((entry) => entry.text);
+      let vectors;
+      try {
+        if (adapter.embedBatch) {
+          vectors = await adapter.embedBatch(texts, "document", signal);
+        } else {
+          vectors = [];
+          const concurrency = 8;
+          for (let start = 0; start < texts.length; start += concurrency) {
+            const chunk = texts.slice(start, start + concurrency);
+            const chunkResults = await Promise.all(chunk.map((t) => adapter.embed(t, "document", signal)));
+            vectors.push(...chunkResults);
+          }
+        }
+      } catch (err) {
+        throw wrapAdapterError(err, targetField);
+      }
+      if (vectors.length !== needsEmbedding.length) {
+        throw new NarsilError(
+          ErrorCodes.EMBEDDING_FAILED,
+          `Adapter returned ${vectors.length} vectors for ${needsEmbedding.length} inputs on field "${targetField}"`,
+          { field: targetField, expected: needsEmbedding.length, actual: vectors.length }
+        );
+      }
+      for (let j = 0; j < needsEmbedding.length; j++) {
+        const { docIndex } = needsEmbedding[j];
+        const validated = validateVector(vectors[j], targetField, adapter.dimensions);
+        setFieldValue(documents[docIndex], targetField, validated);
+        let fieldSet = embedded.get(docIndex);
+        if (!fieldSet) {
+          fieldSet = /* @__PURE__ */ new Set();
+          embedded.set(docIndex, fieldSet);
+        }
+        fieldSet.add(targetField);
+      }
+    }
+  } catch (err) {
+    for (const [docIndex, fields] of embedded) {
+      for (const field of fields) {
+        deleteFieldValue(documents[docIndex], field);
+      }
+    }
+    throw err;
+  }
+  return { embedded, failed };
+}
+
+// src/engine/mutations/insert-admission.ts
+function providedDocId(document) {
+  const id = document.id;
+  return typeof id === "string" && id.length > 0 ? id : void 0;
+}
+function asBatchInsertError(err) {
+  return err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, String(err));
+}
+function admitInsert(ctx, indexName, manager, docId, pendingAdmitted = 0) {
+  if (!ctx.isRebalancing(indexName)) {
+    manager.assertCapacity(pendingAdmitted);
+    return;
+  }
+  const bufferedState = ctx.bufferedDocState(indexName, docId);
+  const exists = bufferedState !== void 0 ? bufferedState === "present" : manager.has(docId);
+  if (exists) {
+    throw new NarsilError(ErrorCodes.DOC_ALREADY_EXISTS, `Document "${docId}" already exists`, { docId });
+  }
+  manager.assertCapacity(
+    ctx.pendingRebalanceWrites(indexName) + pendingAdmitted,
+    ctx.rebalanceTargetPartitionCount(indexName)
+  );
+}
+function collectRequiredFieldFailures(documents, chunkStart, chunkEnd, required, chunkFailedIndexes, failed) {
+  for (let i = chunkStart; i < chunkEnd; i++) {
+    try {
+      validateRequiredFields(documents[i], required);
+    } catch (err) {
+      chunkFailedIndexes.add(i);
+      failed.push({ docId: providedDocId(documents[i]) ?? "", error: asBatchInsertError(err) });
+    }
+  }
+}
+async function embedChunkDocuments(entry, documents, chunkStart, chunkEnd, signal, chunkFailedIndexes, failed) {
+  if (entry.config.embedding === void 0) return;
+  if (entry.embeddingAdapter === null) {
+    for (let i = chunkStart; i < chunkEnd; i++) {
+      if (chunkFailedIndexes.has(i)) continue;
+      try {
+        assertDocumentCarriesMappedVectors(
+          documents[i],
+          entry.config.embedding,
+          entry.embeddingAdapterName
+        );
+      } catch (err) {
+        chunkFailedIndexes.add(i);
+        failed.push({
+          docId: providedDocId(documents[i]) ?? "",
+          error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.EMBEDDING_FAILED, String(err))
+        });
+      }
+    }
+    return;
+  }
+  const embeddableSlice = [];
+  const embeddableOriginalIndexes = [];
+  for (let i = chunkStart; i < chunkEnd; i++) {
+    if (chunkFailedIndexes.has(i)) continue;
+    embeddableSlice.push(documents[i]);
+    embeddableOriginalIndexes.push(i);
+  }
+  if (embeddableSlice.length === 0) return;
+  try {
+    const embedResult = await embedBatchDocumentFields(
+      embeddableSlice,
+      entry.config.embedding,
+      entry.embeddingAdapter,
+      signal
+    );
+    for (const [sliceIndex, error] of embedResult.failed) {
+      const originalIdx = embeddableOriginalIndexes[sliceIndex];
+      chunkFailedIndexes.add(originalIdx);
+      failed.push({ docId: providedDocId(documents[originalIdx]) ?? "", error });
+    }
+  } catch (err) {
+    const embeddingError = err instanceof NarsilError ? err : new NarsilError(ErrorCodes.EMBEDDING_FAILED, String(err));
+    for (const originalIdx of embeddableOriginalIndexes) {
+      chunkFailedIndexes.add(originalIdx);
+      failed.push({ docId: providedDocId(documents[originalIdx]) ?? "", error: embeddingError });
+    }
+  }
+}
+
+// src/engine/resolve-vector-text.ts
+async function resolveVectorText(params, embeddingAdapter, signal, embeddingAdapterName) {
+  if (!params.vector) return params;
+  if (params.vector.text === void 0 && params.vector.value === void 0) return params;
+  if (params.vector.value !== void 0 && params.vector.text === void 0) return params;
+  if (params.vector.text !== void 0 && params.vector.value !== void 0) {
+    throw new NarsilError(ErrorCodes.EMBEDDING_CONFIG_INVALID, "Vector query cannot have both 'text' and 'value'");
+  }
+  if (!embeddingAdapter) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_CONFIG_INVALID,
+      embeddingAdapterName ? `Vector query with 'text' needs embedding adapter "${embeddingAdapterName}", which is not registered on this engine. Register it with registerEmbeddingAdapter or supply a raw vector.` : "Vector query with 'text' requires an embedding adapter on the index or instance",
+      embeddingAdapterName ? { adapter: embeddingAdapterName } : void 0
+    );
+  }
+  if (typeof params.vector.text !== "string") {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Vector query 'text' must be a string, got ${typeof params.vector.text}`
+    );
+  }
+  if (params.vector.text.length === 0) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Vector query 'text' must not be empty");
+  }
+  const raw = await embeddingAdapter.embed(params.vector.text, "query", signal);
+  if (!(raw instanceof Float32Array)) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_FAILED,
+      `Adapter returned ${typeof raw} for query embedding, expected Float32Array`
+    );
+  }
+  if (raw.length !== embeddingAdapter.dimensions) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_DIMENSION_MISMATCH,
+      `Adapter returned ${raw.length}-dimensional vector for query, expected ${embeddingAdapter.dimensions}`,
+      { expected: embeddingAdapter.dimensions, actual: raw.length }
+    );
+  }
+  const resolved = { ...params.vector, value: Array.from(raw) };
+  delete resolved.text;
+  return { ...params, vector: resolved };
+}
+
+export { MAX_PARTITION_COUNT, MAX_REPLICATION_FACTOR, WIRE_BATCH_BUDGET, admitInsert, asBatchInsertError, assertDocumentCarriesMappedVectors, bindEngineCore, collectRequiredFieldFailures, embedChunkDocuments, embedDocumentFields, engineCoreOf, providedDocId, resolveVectorText };