@delali/narsil 0.2.4-next.52 → 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,11 +8,15 @@
 [![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. 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.
+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 the results of the partitions into a single ranked list. Its BM25 nDCG@10 is within 0.006 of the Anserini reference on BEIR SciFact and NFCorpus. On SciFact, Narsil scores 0.681 nDCG@10, ahead of Elasticsearch and OpenSearch at 0.679. At its peak, it also serves 958 keyword queries per second on SciFact, while Elasticsearch serves 841 and OpenSearch serves 878 ([benchmarks](https://github.com/assetcorp/narsil/blob/main/BENCHMARKS.md)). 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).
+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).
 

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-CuTSXvbN.d.ts → capabilities-DlYw0Ov0.d.ts}

@@ -1,6 +1,6 @@
 import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
-import { C as ClusterNamespace } from './config-qMLpi5T4.js';
-import { h as TaskStore } from './tasks-DiF1c9v2.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-U36IDJN7.mjs → chunk-4NVPQ6S5.mjs}

@@ -1,5 +1,5 @@
-import { validateRequiredFields } from './chunk-ZT5BRDFW.mjs';
-import { ErrorCodes, NarsilError } from './chunk-P4ELXVJQ.mjs';
+import { validateRequiredFields } from './chunk-L225SHNB.mjs';
+import { ErrorCodes, NarsilError } from './chunk-FRQVMFY7.mjs';
 
 // src/narsil/internals.ts
 var engineCores = /* @__PURE__ */ new WeakMap();

package/dist/{chunk-WM7IS45M.mjs → chunk-5T6AOR37.mjs}

@@ -1,6 +1,6 @@
-import { flattenSchema, SORTABLE_TEXT_FIELD_TYPE, MAX_SORT_FIELDS, MAX_SORT_FIELD_NAME_LENGTH, MAX_CURSOR_LENGTH, RESULT_WINDOW, DEFAULT_PAGE_SIZE, PROTOTYPE_POLLUTION_KEYS, isTextFieldType, PREFIX_MAX_EXPANSIONS, MAX_CURSOR_ANCHOR_CODE_POINTS } from './chunk-ZT5BRDFW.mjs';
+import { flattenSchema, SORTABLE_TEXT_FIELD_TYPE, MAX_SORT_FIELDS, MAX_SORT_FIELD_NAME_LENGTH, MAX_CURSOR_LENGTH, RESULT_WINDOW, DEFAULT_PAGE_SIZE, PROTOTYPE_POLLUTION_KEYS, isTextFieldType, PREFIX_MAX_EXPANSIONS, MAX_CURSOR_ANCHOR_CODE_POINTS } from './chunk-L225SHNB.mjs';
 import { compareCodePoints, compareComparableKeys, toComparableSortValue, readSortField, SORT_VALUE_MAX_CODE_POINTS, compareSortValues } from './chunk-2GWVQWGA.mjs';
-import { createNarsilError, ErrorCodes, NarsilError } from './chunk-P4ELXVJQ.mjs';
+import { createNarsilError, ErrorCodes, NarsilError } from './chunk-FRQVMFY7.mjs';
 
 // src/core/tokenizer/constants.ts
 var TOKEN_CACHE_SIZE_FLOOR = 5e4;

package/dist/{chunk-ULJ36FK4.mjs → chunk-BH5SYB5W.mjs}

@@ -1,17 +1,17 @@
 import { ReplicationMessageTypes } from './chunk-GCM3JFVA.mjs';
-import { WIRE_BATCH_BUDGET, resolveVectorText, bindEngineCore, collectRequiredFieldFailures, embedChunkDocuments, providedDocId, admitInsert, asBatchInsertError, embedDocumentFields, assertDocumentCarriesMappedVectors } from './chunk-U36IDJN7.mjs';
-import { getNestedValue, generateId, getLanguage, splitWorkerBudget, resolveWorkerCount, createDirectExecutor, createPartitionRouter, createCompositePartition, deserializePayloadV2, createSharedFrozenSegment, createPartitionManager, buildSegmentPayload, resolvePartitionInsertOptions, readHeapStatistics, resolveIndexAnalysis, deserializePayloadV1, decodeVectorIndexParts, resolveRequestThreadCount, createPartitionIndex, VECTOR_FILE_MAX_VECTORS, deadBytesFor, mergeFrozenSegments, isCompositePartition, workerResourceLimits, deserializeMetadata, isNodeMainThread, spawnNodeWorker, freezeSegmentShared, DEFAULT_BACKPRESSURE_LIMIT, DEFAULT_REQUEST_TIMEOUT_MS, serializeMetadata, SHUTDOWN_TIMEOUT_MS, encodeSegmentState, CONSECUTIVE_TIMEOUTS_BEFORE_DEATH, decodeVectorFilePayload, documentsOfPayloadV2, countDead, decodeVectorGraphPayload, deadBitsWhere, NO_LIVE_VECTOR_AT_POSITION, createFrozenSegment } from './chunk-2FO7KZ6K.mjs';
+import { WIRE_BATCH_BUDGET, resolveVectorText, bindEngineCore, collectRequiredFieldFailures, embedChunkDocuments, providedDocId, admitInsert, asBatchInsertError, embedDocumentFields, assertDocumentCarriesMappedVectors } from './chunk-4NVPQ6S5.mjs';
+import { getNestedValue, generateId, getLanguage, splitWorkerBudget, resolveWorkerCount, createDirectExecutor, createPartitionRouter, createCompositePartition, deserializePayloadV2, createSharedFrozenSegment, createPartitionManager, buildSegmentPayload, resolvePartitionInsertOptions, readHeapStatistics, resolveIndexAnalysis, deserializePayloadV1, decodeVectorIndexParts, resolveRequestThreadCount, createPartitionIndex, VECTOR_FILE_MAX_VECTORS, deadBytesFor, mergeFrozenSegments, isCompositePartition, workerResourceLimits, deserializeMetadata, isNodeMainThread, spawnNodeWorker, freezeSegmentShared, DEFAULT_BACKPRESSURE_LIMIT, DEFAULT_REQUEST_TIMEOUT_MS, serializeMetadata, SHUTDOWN_TIMEOUT_MS, encodeSegmentState, CONSECUTIVE_TIMEOUTS_BEFORE_DEATH, decodeVectorFilePayload, documentsOfPayloadV2, countDead, decodeVectorGraphPayload, deadBitsWhere, NO_LIVE_VECTOR_AT_POSITION, createFrozenSegment } from './chunk-XNQAIO74.mjs';
 import { detectRuntime } from './chunk-AV4IJKD2.mjs';
-import { validateWorkerConfig, validateIndexName, validateBM25Params, validatePartitionConfig, executeQuery, queryBindingOf, executePreflight, executeSuggest, executeListDocuments, validateDocId } from './chunk-YPYULM5E.mjs';
-import { BATCH_CHUNK_SIZE, STATISTICS_BROADCAST_INTERVAL_MS, MAX_SWEEP_INTERVAL_MS, MIN_SWEEP_INTERVAL_MS, HEAP_PRESSURE_WARNING_FRACTION, FOREIGN_STATS_TTL_MS, MIN_DOCUMENTS_FOR_SEGMENTS, HEAP_PRESSURE_REARM_FRACTION } from './chunk-3GWP2TO6.mjs';
-import { collectQueryTermStats, mergePartitionStats, fnv1a, kWayMerge, mergeFacets } from './chunk-WM7IS45M.mjs';
-import { extractVectorFieldsFromSchema, validateSchema, validateVectorPromotion, validateVectorStorage, flattenSchema, isTextFieldType, validateRequiredFields, validateDocument, validateDocumentStrict } from './chunk-ZT5BRDFW.mjs';
-import { releaseLocksHeldBy } from './chunk-T62YOSGS.mjs';
+import { validateWorkerConfig, validateIndexName, validateBM25Params, validatePartitionConfig, executeQuery, queryBindingOf, executePreflight, executeSuggest, executeListDocuments, validateDocId } from './chunk-TVT5V4E7.mjs';
+import { BATCH_CHUNK_SIZE, STATISTICS_BROADCAST_INTERVAL_MS, MAX_SWEEP_INTERVAL_MS, MIN_SWEEP_INTERVAL_MS, HEAP_PRESSURE_WARNING_FRACTION, FOREIGN_STATS_TTL_MS, MIN_DOCUMENTS_FOR_SEGMENTS, HEAP_PRESSURE_REARM_FRACTION } from './chunk-D2S642IV.mjs';
+import { collectQueryTermStats, mergePartitionStats, fnv1a, kWayMerge, mergeFacets } from './chunk-5T6AOR37.mjs';
+import { extractVectorFieldsFromSchema, validateSchema, validateVectorPromotion, validateVectorStorage, flattenSchema, isTextFieldType, validateRequiredFields, validateDocument, validateDocumentStrict } from './chunk-L225SHNB.mjs';
+import { releaseLocksHeldBy } from './chunk-U2AL3SON.mjs';
 import { crc32, nativeCrc32, crc32Final, crc32Init, crc32Update } from './chunk-3L4U6EJQ.mjs';
 import { CHECKSUM_TIMEOUT_MS, CHECKSUM_YIELD_CHUNK_BYTES } from './chunk-IFBKLBGB.mjs';
 import { compareCodePoints } from './chunk-2GWVQWGA.mjs';
 import { createRequestId, isValidWorkerResponse, threadSlotOfWorker } from './chunk-POWOTUKJ.mjs';
-import { NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
+import { NarsilError, ErrorCodes } from './chunk-FRQVMFY7.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 // src/partitioning/constants.ts
@@ -1083,7 +1083,7 @@ async function unpackEnvelope(data, maxAcceptedVersion = CURRENT_ENVELOPE_VERSIO
   if (header.envelopeFormatVersion > maxAcceptedVersion) {
     throw new NarsilError(
       ErrorCodes.ENVELOPE_VERSION_MISMATCH,
-      `This data was written by Narsil envelope format v${header.envelopeFormatVersion} and requires a newer version of Narsil. You are running ${VERSION}.`
+      `This data holds Narsil envelope format v${header.envelopeFormatVersion}, while this build of @delali/narsil reads up to v${maxAcceptedVersion}, so upgrade the package to read it.`
     );
   }
   if (header.flags.encryptionEnabled) {
@@ -3824,6 +3824,8 @@ async function spawnWorker2() {
     if (typeof worker.unref === "function") {
       worker.unref();
     }
+    worker.on("error", () => discardWorker(worker));
+    worker.on("exit", () => discardWorker(worker));
     spawnedWorkerCount += 1;
     return worker;
   } catch {
@@ -6008,12 +6010,20 @@ function createInvalidationIntegration(deps) {
 }
 
 // src/engine/heap-pressure.ts
+function spentHeapFraction(heap) {
+  if (heap.configuredLimitBytes !== null) return heap.usedBytes / heap.configuredLimitBytes;
+  if (heap.availableBytes === null) return heap.usedBytes / heap.limitBytes;
+  return 1 - heap.availableBytes / heap.limitBytes;
+}
+function ceilingBytes(heap) {
+  return heap.configuredLimitBytes ?? heap.limitBytes;
+}
 function createHeapPressureNotifier(deps) {
   let warned = false;
   function check(indexName) {
     const heap = deps.readHeap();
     if (heap === null) return;
-    const fraction = heap.usedBytes / heap.limitBytes;
+    const fraction = spentHeapFraction(heap);
     if (warned) {
       if (fraction < HEAP_PRESSURE_REARM_FRACTION) warned = false;
       return;
@@ -6023,7 +6033,7 @@ function createHeapPressureNotifier(deps) {
     deps.emit({
       indexName,
       heapUsed: heap.usedBytes,
-      heapLimit: heap.limitBytes,
+      heapLimit: ceilingBytes(heap),
       estimatedMemoryBytes: deps.estimateIndexBytes(indexName)
     });
   }
@@ -6751,7 +6761,7 @@ function createWorkerExecutor(worker, config) {
     clearTimeout(entry.timeoutId);
     pending.delete(response.requestId);
     if (response.type === "error") {
-      entry.reject(new NarsilError(response.code, response.message));
+      entry.reject(new NarsilError(response.code, response.message, response.details));
     } else {
       entry.resolve(response.data);
     }
@@ -7312,6 +7322,7 @@ function scheduleRequestThreadPoolRestart(state) {
   if (typeof timer.unref === "function") timer.unref();
 }
 async function serveRequestsOnWorkers(state, listener) {
+  if (!state.workersEnabled) return 0;
   state.requestThreads = listener;
   state.keywordWorkerCount = resolveRequestThreadCount(state.config?.workers?.count);
   if (state.vectorCopyPolicy !== void 0) {
@@ -7334,6 +7345,7 @@ async function serveRequestsOnWorkers(state, listener) {
   return pool.workerCount;
 }
 function requestThreadCountOf(state) {
+  if (!state.workersEnabled) return 0;
   return resolveRequestThreadCount(state.config?.workers?.count);
 }
 function stopRequestThreads(state) {
@@ -8275,6 +8287,16 @@ function createEngineCore(config, hooks) {
 }
 
 // src/engine/index-lifecycle.ts
+async function runLifecycleHook(core, hookName, context) {
+  try {
+    await core.pluginRegistry.runHook(hookName, context);
+  } catch (err) {
+    console.warn(`${hookName} plugin hook error:`, err instanceof Error ? err.message : String(err));
+  }
+}
+async function announceIndexCreated(core, name, config) {
+  await runLifecycleHook(core, "onIndexCreate", { indexName: name, config });
+}
 async function createEngineIndex(core, config, name, indexConfig, indexUuid) {
   core.guardShutdown();
   validateIndexName(name);
@@ -8346,7 +8368,7 @@ async function createEngineIndex(core, config, name, indexConfig, indexUuid) {
   if (core.durability) {
     await core.durability.manager.persistMetadata(name);
   }
-  await core.pluginRegistry.runHook("onIndexCreate", { indexName: name, config: indexConfig });
+  await runLifecycleHook(core, "onIndexCreate", { indexName: name, config: indexConfig });
 }
 async function dropEngineIndex(core, name) {
   core.guardShutdown();
@@ -8366,7 +8388,7 @@ async function dropEngineIndex(core, name) {
     core.watermarkNotifier.forget(name);
     core.analysisRebuild.clearStale(name);
   });
-  await core.pluginRegistry.runHook("onIndexDrop", { indexName: name, config: entry.config });
+  await runLifecycleHook(core, "onIndexDrop", { indexName: name, config: entry.config });
 }
 function registerEngineEmbeddingAdapter(core, name, adapter) {
   core.guardShutdown();
@@ -8487,7 +8509,15 @@ async function awaitWriteVisibility(ctx, indexName) {
 async function insertDocument(ctx, indexName, document, docId, options) {
   ctx.guardShutdown();
   const entry = ctx.requireIndex(indexName);
-  const resolvedDocId = docId ?? providedDocId(document) ?? ctx.idGenerator();
+  const embeddedDocId = providedDocId(document);
+  if (docId !== void 0 && embeddedDocId !== void 0 && embeddedDocId !== docId) {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `The call names document id "${docId}" while the document's own id field is "${embeddedDocId}", so the stored document would contradict the key that it is stored under`,
+      { docId, documentId: embeddedDocId }
+    );
+  }
+  const resolvedDocId = docId ?? embeddedDocId ?? ctx.idGenerator();
   validateDocId(resolvedDocId);
   await ctx.pluginRegistry.runHook("beforeInsert", { indexName, docId: resolvedDocId, document });
   if (entry.config.required && entry.config.required.length > 0) {
@@ -8758,13 +8788,12 @@ async function admitBatchDocuments(ctx, indexName, documents, failed) {
 // src/engine/mutations/insert-batch-documents.ts
 async function applyAdmittedDocuments(ctx, indexName, admitted, options, failed) {
   const hasAfterHook = ctx.pluginRegistry.hasHooks("afterInsert");
-  const chunkSize = hasAfterHook ? 1 : BATCH_CHUNK_SIZE;
   const succeeded = [];
   const buffered = /* @__PURE__ */ new Set();
   const touchedVectorFields = /* @__PURE__ */ new Set();
-  for (let chunkStart = 0; chunkStart < admitted.length; chunkStart += chunkSize) {
+  for (let chunkStart = 0; chunkStart < admitted.length; chunkStart += BATCH_CHUNK_SIZE) {
     if (ctx.abortController.signal.aborted) break;
-    const chunk = admitted.slice(chunkStart, chunkStart + chunkSize);
+    const chunk = admitted.slice(chunkStart, chunkStart + BATCH_CHUNK_SIZE);
     const applications = await applyInsertChunk(ctx, indexName, chunk, options);
     for (let i = 0; i < chunk.length; i++) {
       const doc = chunk[i];
@@ -8791,8 +8820,8 @@ async function applyAdmittedDocuments(ctx, indexName, admitted, options, failed)
       }
       succeeded.push(doc.docId);
     }
-    const applied = chunkStart + chunkSize;
-    if (applied < admitted.length && applied % BATCH_CHUNK_SIZE === 0) {
+    const applied = chunkStart + BATCH_CHUNK_SIZE;
+    if (applied < admitted.length) {
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -9161,7 +9190,6 @@ async function insertDocumentBatch(ctx, indexName, documents, options) {
   const failed = [];
   const hasBeforeHook = ctx.pluginRegistry.hasHooks("beforeInsert");
   const hasAfterHook = ctx.pluginRegistry.hasHooks("afterInsert");
-  const documentByDocument = hasBeforeHook || hasAfterHook;
   const required = entry.config.required;
   const batchManager = ctx.requireManager(indexName);
   const batchVecIndexes = batchManager.getVectorIndexes();
@@ -9241,9 +9269,6 @@ async function insertDocumentBatch(ctx, indexName, documents, options) {
       } catch (err) {
         failed.push({ docId: batchDocId, error: asBatchInsertError(err) });
       }
-      if (documentByDocument && prepared.length > 0) {
-        await applyPrepared(prepared.splice(0, prepared.length));
-      }
     }
     if (prepared.length > 0) await applyPrepared(prepared);
     if (chunkEnd < documents.length) {
@@ -9358,12 +9383,10 @@ async function removeDocumentBatch(ctx, indexName, docIds, options) {
   const succeeded = [];
   const failed = [];
   const manager = ctx.requireManager(indexName);
-  const hooked = ctx.pluginRegistry.hasHooks("beforeRemove") || ctx.pluginRegistry.hasHooks("afterRemove");
-  const chunkSize = hooked ? 1 : BATCH_CHUNK_SIZE;
   manager.beginBatchRemove();
   try {
-    for (let chunkStart = 0; chunkStart < docIds.length; chunkStart += chunkSize) {
-      const chunkEnd = Math.min(chunkStart + chunkSize, docIds.length);
+    for (let chunkStart = 0; chunkStart < docIds.length; chunkStart += BATCH_CHUNK_SIZE) {
+      const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, docIds.length);
       const prepared = [];
       for (let i = chunkStart; i < chunkEnd; i++) {
         try {
@@ -9390,13 +9413,14 @@ async function removeDocumentBatch(ctx, indexName, docIds, options) {
         if (!removal.buffered) await settleRemoval(ctx, indexName, removal.docId);
         succeeded.push(removal.docId);
       }
-      if (chunkEnd < docIds.length && chunkEnd % BATCH_CHUNK_SIZE === 0) {
+      if (chunkEnd < docIds.length) {
         await new Promise((r) => setTimeout(r, 0));
       }
     }
   } finally {
     manager.endBatchRemove();
   }
+  ctx.checkHeapPressure(indexName);
   if (options?.wait === true) await awaitWriteVisibility(ctx, indexName);
   return { succeeded, failed };
 }
@@ -9557,10 +9581,8 @@ async function updateDocumentBatch(ctx, indexName, updates, options) {
   const updateBatchManager = ctx.requireManager(indexName);
   const updateBatchVecIndexes = updateBatchManager.getVectorIndexes();
   const touchedVectorFields = /* @__PURE__ */ new Set();
-  const hooked = ctx.pluginRegistry.hasHooks("beforeUpdate") || ctx.pluginRegistry.hasHooks("afterUpdate");
-  const chunkSize = hooked ? 1 : BATCH_CHUNK_SIZE;
-  for (let chunkStart = 0; chunkStart < updates.length; chunkStart += chunkSize) {
-    const chunkEnd = Math.min(chunkStart + chunkSize, updates.length);
+  for (let chunkStart = 0; chunkStart < updates.length; chunkStart += BATCH_CHUNK_SIZE) {
+    const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, updates.length);
     const prepared = [];
     for (let i = chunkStart; i < chunkEnd; i++) {
       try {
@@ -9590,7 +9612,7 @@ async function updateDocumentBatch(ctx, indexName, updates, options) {
       }
       succeeded.push(update.docId);
     }
-    if (chunkEnd < updates.length && chunkEnd % BATCH_CHUNK_SIZE === 0) {
+    if (chunkEnd < updates.length) {
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -10225,6 +10247,7 @@ async function restoreFromSnapshot(indexName, data, deps) {
       await deps.durability.manager.persistMetadata(indexName);
       await deps.durability.manager.checkpoint(indexName);
     }
+    await deps.announceIndexCreated(indexName, indexConfig);
   } catch (err) {
     try {
       deps.executor.dropIndex(indexName);
@@ -10296,13 +10319,14 @@ function readProcessMemory() {
   }
   try {
     const usage = proc.memoryUsage();
+    const heap = readHeapStatistics();
     if (!Number.isFinite(usage.heapUsed) || !Number.isFinite(usage.heapTotal) || !Number.isFinite(usage.external) || !Number.isFinite(usage.rss)) {
       return null;
     }
     return {
       heapUsed: usage.heapUsed,
       heapTotal: usage.heapTotal,
-      heapLimit: readHeapStatistics()?.limitBytes ?? null,
+      heapLimit: heap === null ? null : heap.configuredLimitBytes ?? heap.limitBytes,
       external: usage.external,
       rss: usage.rss
     };
@@ -10335,13 +10359,14 @@ async function runEngineQuery(core, indexName, params, options) {
   try {
     const entry = core.requireIndex(indexName);
     const manager = core.requireManager(indexName);
+    const scoped = scopedParams(params, options);
+    await core.pluginRegistry.runHook("beforeSearch", { indexName, params: scoped });
     const resolvedParams = await resolveVectorText(
-      scopedParams(params, options),
+      scoped,
       entry.embeddingAdapter,
       core.abortController.signal,
       entry.embeddingAdapterName
     );
-    await core.pluginRegistry.runHook("beforeSearch", { indexName, params: resolvedParams });
     const workerSearch = core.orchestrator.hasWorkerPool() ? core.orchestrator.searchViaWorker.bind(core.orchestrator) : void 0;
     const result = await executeQuery(resolvedParams, {
       manager,
@@ -10353,14 +10378,13 @@ async function runEngineQuery(core, indexName, params, options) {
       partitionIds: options?.partitionIds,
       cursorBinding: queryBindingOf(params)
     });
-    try {
-      await core.pluginRegistry.runHook("afterSearch", {
-        indexName,
-        params: resolvedParams,
-        results: result
-      });
-    } catch (err) {
-      console.warn("afterSearch plugin hook error:", err);
+    if (core.pluginRegistry.hasHooks("afterSearch")) {
+      const observed = { ...result, hits: [...result.hits] };
+      try {
+        await core.pluginRegistry.runHook("afterSearch", { indexName, params: resolvedParams, results: observed });
+      } catch (err) {
+        console.warn("afterSearch plugin hook error:", err);
+      }
     }
     if (core.analysisRebuild.isStale(indexName)) {
       result.analysisStale = true;
@@ -10376,8 +10400,10 @@ async function runEnginePreflight(core, indexName, params, options) {
   try {
     const entry = core.requireIndex(indexName);
     const manager = core.requireManager(indexName);
+    const scoped = scopedParams(params, options);
+    await core.pluginRegistry.runHook("beforeSearch", { indexName, params: scoped });
     const resolvedParams = await resolveVectorText(
-      scopedParams(params, options),
+      scoped,
       entry.embeddingAdapter,
       core.abortController.signal,
       entry.embeddingAdapterName
@@ -10616,6 +10642,7 @@ function createNarsilFromCore(core, config) {
         indexRegistry,
         getVectorFieldPaths,
         dropIndex: narsil.dropIndex.bind(narsil),
+        announceIndexCreated: (name, restoredConfig) => announceIndexCreated(core, name, restoredConfig),
         requireManager,
         durability,
         filesystemDurability: core.filesystemDurability,

package/dist/{chunk-3GWP2TO6.mjs → chunk-D2S642IV.mjs}

@@ -1,4 +1,4 @@
-import { DEFAULT_PAGE_SIZE } from './chunk-ZT5BRDFW.mjs';
+import { DEFAULT_PAGE_SIZE } from './chunk-L225SHNB.mjs';
 
 // src/engine/constants.ts
 var MIN_DOCUMENTS_FOR_SEGMENTS = 64;
@@ -6,6 +6,8 @@ var BATCH_CHUNK_SIZE = 1e3;
 var DEFAULT_LIMIT = DEFAULT_PAGE_SIZE;
 var DEFAULT_OFFSET = 0;
 var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var ABSOLUTE_WINDOWS_PATH_PATTERN = /^[a-zA-Z]:[\\/]/;
+var MODULE_URL_SCHEME_PATTERN = /^(file|https?|data|node):/;
 var MAX_INDEX_NAME_LENGTH = 255;
 var MAX_DOC_ID_LENGTH = 512;
 var MIN_SWEEP_INTERVAL_MS = 100;
@@ -20,4 +22,4 @@ var SUGGEST_OVERSAMPLE_FACTOR = 1.5;
 var SUGGEST_OVERSAMPLE_PADDING = 10;
 var MAX_SUGGEST_SCATTER_LIMIT = Math.ceil(MAX_SUGGEST_LIMIT * SUGGEST_OVERSAMPLE_FACTOR) + SUGGEST_OVERSAMPLE_PADDING;
 
-export { BATCH_CHUNK_SIZE, DEFAULT_LIMIT, DEFAULT_OFFSET, DEFAULT_SUGGEST_LIMIT, FOREIGN_STATS_TTL_MS, HEAP_PRESSURE_REARM_FRACTION, HEAP_PRESSURE_WARNING_FRACTION, INDEX_NAME_PATTERN, MAX_DOC_ID_LENGTH, MAX_INDEX_NAME_LENGTH, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, MAX_SWEEP_INTERVAL_MS, MIN_DOCUMENTS_FOR_SEGMENTS, MIN_SWEEP_INTERVAL_MS, STATISTICS_BROADCAST_INTERVAL_MS, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING };
+export { ABSOLUTE_WINDOWS_PATH_PATTERN, BATCH_CHUNK_SIZE, DEFAULT_LIMIT, DEFAULT_OFFSET, DEFAULT_SUGGEST_LIMIT, FOREIGN_STATS_TTL_MS, HEAP_PRESSURE_REARM_FRACTION, HEAP_PRESSURE_WARNING_FRACTION, INDEX_NAME_PATTERN, MAX_DOC_ID_LENGTH, MAX_INDEX_NAME_LENGTH, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, MAX_SWEEP_INTERVAL_MS, MIN_DOCUMENTS_FOR_SEGMENTS, MIN_SWEEP_INTERVAL_MS, MODULE_URL_SCHEME_PATTERN, STATISTICS_BROADCAST_INTERVAL_MS, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING };

package/dist/{chunk-P4ELXVJQ.mjs → chunk-FRQVMFY7.mjs}

@@ -1,4 +1,5 @@
 // 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",
@@ -16,6 +17,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",
@@ -135,8 +137,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;
+}
 function createNarsilError(code, message, details) {
   return new NarsilError(code, message, details);
 }
@@ -144,4 +150,4 @@ function describeError(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
-export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes, createNarsilError, describeError };
+export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes, createNarsilError, describeError, isNarsilError };

package/dist/{chunk-ZT5BRDFW.mjs → chunk-L225SHNB.mjs}

@@ -1,5 +1,5 @@
-import { MAX_M } from './chunk-WFKIGEBY.mjs';
-import { NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
+import { MAX_M } from './chunk-UTOFOJOR.mjs';
+import { NarsilError, ErrorCodes } from './chunk-FRQVMFY7.mjs';
 
 // src/schema/constants.ts
 var MAX_NESTING_DEPTH = 4;

package/dist/{chunk-72AXTIBW.mjs → chunk-NTZYA3SJ.mjs}

@@ -1,6 +1,6 @@
-import { MAX_PARTITION_COUNT, MAX_REPLICATION_FACTOR } from './chunk-U36IDJN7.mjs';
-import { MAX_INDEX_NAME_LENGTH, INDEX_NAME_PATTERN } from './chunk-3GWP2TO6.mjs';
-import { NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
+import { MAX_PARTITION_COUNT, MAX_REPLICATION_FACTOR } from './chunk-4NVPQ6S5.mjs';
+import { MAX_INDEX_NAME_LENGTH, INDEX_NAME_PATTERN } from './chunk-D2S642IV.mjs';
+import { NarsilError, ErrorCodes } from './chunk-FRQVMFY7.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 var INDEX_CONFIG_PREFIX = "_narsil/index/";

package/dist/{chunk-EY2ULUMT.mjs → chunk-RGS7FMCB.mjs}

@@ -1,5 +1,6 @@
-import { MAX_SORT_FIELDS } from './chunk-ZT5BRDFW.mjs';
-import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
+import { MAX_SORT_FIELDS } from './chunk-L225SHNB.mjs';
+import { nativeSearchCoreIsEnabled, loadNativeCore } from './chunk-UTOFOJOR.mjs';
+import { NarsilError, ServerErrorCodes, ErrorCodes } from './chunk-FRQVMFY7.mjs';
 
 // src/server/capabilities.ts
 var ASYNC_IMPORT_CAPABILITY = "documents.import.async";
@@ -122,6 +123,7 @@ var STATUS_BY_CODE = {
   PARTITION_CORRUPTED: 503,
   WORKER_CRASHED: 503,
   WORKER_TIMEOUT: 503,
+  WORKER_ACTION_FAILED: 500,
   PERSISTENCE_SAVE_FAILED: 503,
   PERSISTENCE_LOAD_FAILED: 503,
   PERSISTENCE_DELETE_FAILED: 503,
@@ -224,6 +226,8 @@ var DEFAULT_MAX_FETCH_DOCUMENTS = 1e4;
 var DEFAULT_MAX_IMPORT_ERRORS = 100;
 var DEFAULT_MAX_TASK_PAGE_SIZE = 1e3;
 var DEFAULT_MAX_CONCURRENT_TASKS = 4;
+var MIN_COUNTED_SERVER_LIMIT = 1;
+var MIN_UNBOUNDED_SERVER_LIMIT = 0;
 var RESPONSE_STREAM_THRESHOLD_BYTES = 64 * 1024;
 var MAX_INDEX_TOUCH_INTERVAL_MS = 1e3;
 var INDEX_TOUCH_INTERVALS_PER_IDLE_TIMEOUT = 4;
@@ -484,7 +488,7 @@ function validateRebalance(body) {
   return null;
 }
 var TASK_TYPES = ["optimizeVectors", "rebalance", "restore", "import", "rebuildAnalysis"];
-var TASK_STATUSES = ["queued", "running", "succeeded", "failed", "cancelled"];
+var TASK_STATUSES = ["running", "succeeded", "failed", "cancelled"];
 function parseCountParam(raw, field, minimum) {
   if (raw === null) return minimum;
   const value = Number(raw);
@@ -603,6 +607,22 @@ function indexDocNotFound(docId) {
   return new NarsilError(ErrorCodes.DOC_NOT_FOUND, `Document "${docId}" not found`, { docId });
 }
 
+// src/vector/native/search-path.ts
+function vectorSearchPath() {
+  return nativeSearchCoreIsEnabled() && loadNativeCore() !== null ? "native" : "wasm";
+}
+
+// src/server/handlers/version.ts
+function versionReport(build) {
+  return { name: "narsil", ...build, vectorSearch: vectorSearchPath() };
+}
+function createVersionHandler(deps) {
+  function report(ctx) {
+    respondJson(ctx, versionReport(deps.build));
+  }
+  return { report };
+}
+
 // src/server/request.ts
 function initAbortHandler(res) {
   const listeners = [];
@@ -790,7 +810,7 @@ function serverRoutes(limits) {
   return [
     { method: "get", path: "/livez", handler: "livez", options: probe },
     { method: "get", path: "/readyz", handler: "readyz", options: probe },
-    { method: "get", path: "/health", handler: "livez", options: probe },
+    { method: "get", path: "/health", handler: "readyz", options: probe },
     { method: "get", path: "/version", handler: "version", options: probe },
     { method: "get", path: "/capabilities", handler: "capabilities", options: probe },
     { method: "get", path: "/cluster", handler: "clusterTopology", options: bare },
@@ -896,4 +916,4 @@ function childAppOf(app) {
   return candidate;
 }
 
-export { ASYNC_IMPORT_CAPABILITY, DEFAULT_IMPORT_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_CONCURRENT_REQUESTS, DEFAULT_MAX_CONCURRENT_TASKS, DEFAULT_MAX_FETCH_DOCUMENTS, DEFAULT_MAX_IMPORT_BYTES, DEFAULT_MAX_IMPORT_ERRORS, DEFAULT_MAX_LINE_BYTES, DEFAULT_MAX_RESULT_WINDOW, DEFAULT_MAX_RETAINED_TASKS, DEFAULT_MAX_TASK_PAGE_SIZE, DEFAULT_TASK_PAGE_SIZE, IMPORT_FLUSHES_IN_FLIGHT, INDEX_LIFECYCLE_CAPABILITY, INDEX_TOUCH_INTERVALS_PER_IDLE_TIMEOUT, MAIN_THREAD_GATE_SLOT, MAX_INDEX_TOUCH_INTERVAL_MS, REBUILD_ANALYSIS_CAPABILITY, RUNNING_TASK_TTL_MS, SERVER_CAPABILITIES, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, TASK_PROGRESS_WRITE_INTERVAL_MS, TERMINAL_TASK_TTL_MS, acceptorOf, authorizerFor, badRequest, childAppOf, clearGateSlot, corsWriter, createDocumentReadHandlers, createRouteRunner, createSharedGateBuffer, createSharedRequestGate, gateSlotOfWorker, httpStatusForNarsilError, loadUWebSockets, parseJson, parseJsonOptional, parseTaskListQuery, registerServerRoutes, rejectInvalid, resolveCors, respondError, respondJson, sendBinary, sendError, sendRelayed, serializeBatchResult, serializeNarsilError, serverRoutes, validateBatch, validateCreateIndex, validateDocumentBody, validateQuery, validateRebalance, validateSuggest };
+export { ASYNC_IMPORT_CAPABILITY, DEFAULT_IMPORT_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_CONCURRENT_REQUESTS, DEFAULT_MAX_CONCURRENT_TASKS, DEFAULT_MAX_FETCH_DOCUMENTS, DEFAULT_MAX_IMPORT_BYTES, DEFAULT_MAX_IMPORT_ERRORS, DEFAULT_MAX_LINE_BYTES, DEFAULT_MAX_RESULT_WINDOW, DEFAULT_MAX_RETAINED_TASKS, DEFAULT_MAX_TASK_PAGE_SIZE, DEFAULT_TASK_PAGE_SIZE, IMPORT_FLUSHES_IN_FLIGHT, INDEX_LIFECYCLE_CAPABILITY, INDEX_TOUCH_INTERVALS_PER_IDLE_TIMEOUT, MAIN_THREAD_GATE_SLOT, MAX_INDEX_TOUCH_INTERVAL_MS, MIN_COUNTED_SERVER_LIMIT, MIN_UNBOUNDED_SERVER_LIMIT, REBUILD_ANALYSIS_CAPABILITY, RUNNING_TASK_TTL_MS, SERVER_CAPABILITIES, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, TASK_PROGRESS_WRITE_INTERVAL_MS, TERMINAL_TASK_TTL_MS, acceptorOf, authorizerFor, badRequest, childAppOf, clearGateSlot, corsWriter, createDocumentReadHandlers, createRouteRunner, createSharedGateBuffer, createSharedRequestGate, createVersionHandler, gateSlotOfWorker, httpStatusForNarsilError, loadUWebSockets, parseJson, parseJsonOptional, parseTaskListQuery, registerServerRoutes, rejectInvalid, resolveCors, respondError, respondJson, sendBinary, sendError, sendRelayed, serializeBatchResult, serializeNarsilError, serverRoutes, toHttpError, validateBatch, validateCreateIndex, validateDocumentBody, validateQuery, validateRebalance, validateSuggest, versionReport };