@delali/narsil 0.1.1 → 0.1.2

package/README.md

@@ -1,5 +1,11 @@
 # Narsil
 
+[![CI](https://github.com/assetcorp/narsil/actions/workflows/ci.yml/badge.svg)](https://github.com/assetcorp/narsil/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@delali/narsil)](https://www.npmjs.com/package/@delali/narsil)
+[![downloads](https://img.shields.io/npm/dw/@delali/narsil)](https://www.npmjs.com/package/@delali/narsil)
+[![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.
 
 Narsil is a distributed search engine with full-text, vector, hybrid, and geosearch. It auto-partitions large indexes across workers, serializes them into a cross-language binary format (.nrsl), and merges results back into a single ranked answer. The TypeScript package is the first implementation.
@@ -140,6 +146,18 @@ const results = await narsil.query('products', {
 // hit.highlights.title.snippet => '<mark>Mechanical</mark> Keyboard'
 ```
 
+### Term suggestions
+
+Get autocomplete suggestions from the index's term dictionary. The API tokenizes the input, extracts the last word, and matches it against stored terms across all partitions. Results are ranked by document frequency.
+
+```ts
+const suggestions = await narsil.suggest('products', {
+  prefix: 'mech',
+  limit: 5,
+})
+// suggestions.terms => [{ term: 'mechan', documentFrequency: 12 }, ...]
+```
+
 ### Cursor-based pagination
 
 Deep pagination using `searchAfter` cursors that track position across partitions. No offset-based performance degradation for deep result sets.
@@ -204,6 +222,27 @@ import '@delali/narsil/languages/twi'
 | Vector | `mode: 'vector'` | Cosine similarity, dot product, or Euclidean distance |
 | Hybrid | `mode: 'hybrid'` | Weighted combination of BM25 + vector similarity |
 
+## Search quality
+
+Ranking quality is measured against the [Cranfield Collection](https://ir-datasets.com/cranfield.html), the foundational information retrieval benchmark created in the 1960s. It contains 1,400 documents and 225 queries with exhaustive human relevance judgments, meaning every query-document pair was scored by domain experts. All engines in this comparison use identical stop words (Lucene English, 35 terms), Porter stemming, and default BM25 parameters.
+
+| Engine | nDCG@10 | P@10 | MAP | MRR |
+| --- | ---: | ---: | ---: | ---: |
+| **Narsil 0.1.1** | **0.3739** | **0.2458** | **0.2614** | **0.5638** |
+| Orama 3.1.18 | 0.2911 | 0.1836 | 0.1846 | 0.4821 |
+| MiniSearch 7.2.0 | 0.0077 | 0.0067 | 0.0027 | 0.0139 |
+
+**What these metrics mean:**
+
+- **nDCG@10** measures whether the most relevant documents appear near the top of the results. A score of 1.0 would mean perfect ranking; 0.0 means no relevant documents in the top 10.
+- **P@10** is the fraction of the top 10 results that are relevant. Narsil averages about 2.5 relevant results in every top-10 list.
+- **MAP** tracks precision at every rank where a relevant document appears. Higher MAP means relevant documents cluster near the top rather than being spread through the result set.
+- **MRR** measures how far a user scrolls to find the first relevant result. Narsil's 0.56 means the first relevant document typically appears at position 2.
+
+These scores fall within the expected range for BM25 on standard IR benchmarks (published BM25 baselines on BEIR datasets range from 0.24 to 0.63 nDCG@10). Narsil also runs a [Cranfield regression test](src/__tests__/relevance/cranfield.test.ts) in CI that fails the build if ranking quality drops below calibrated thresholds.
+
+Reproduce: `pnpm -C packages/benchmarks bench --tiers quality`
+
 ## Runtime support (TypeScript)
 
 | Runtime | Concurrency | Persistence | Invalidation |

package/dist/adapters/filesystem.mjs

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

package/dist/adapters/indexeddb.mjs

@@ -1,4 +1,4 @@
-import { NarsilError, ErrorCodes } from '../chunk-JKIBUPAY.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-7GKPWGCN.mjs';
 
 // src/persistence/indexeddb.ts
 var DEFAULT_DB_NAME = "narsil";

package/dist/{chunk-JKIBUPAY.mjs → chunk-7GKPWGCN.mjs}

@@ -26,7 +26,8 @@ var ErrorCodes = {
   SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR",
   LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED",
   ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH",
-  ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC"
+  ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC",
+  PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED"
 };
 var NarsilError = class extends Error {
   code;

package/dist/chunk-GVN2W4VA.mjs

@@ -0,0 +1,570 @@
+// src/vector/simd-wasm-binary.ts
+var SIMD_DISTANCE_WASM_BASE64 = "AGFzbQEAAAABDgJgA39/fwF9YAJ/fwF9AwUEAAEAAAUDAQABB1YFBm1lbW9yeQIAC2RvdF9wcm9kdWN0AAAJbWFnbml0dWRlAAEac3F1YXJlZF9ldWNsaWRlYW5fZGlzdGFuY2UAAhJldWNsaWRlYW5fZGlzdGFuY2UAAwqqBASuAQQBfwF7AX0BfyACQXxxIQb9DAAAAAAAAAAAAAAAAAAAAAAhBEEAIQMCQANAIAMgBk8NASAEIAAgA0ECdGr9AAQAIAEgA0ECdGr9AAQA/eYB/eQBIQQgA0EEaiEDDAALCyAE/R8AIAT9HwGSIAT9HwIgBP0fA5KSIQUCQANAIAMgAk8NASAFIAAgA0ECdGoqAgAgASADQQJ0aioCAJSSIQUgA0EBaiEDDAALCyAFC6kBBAF/AnsBfQF/IAFBfHEhBv0MAAAAAAAAAAAAAAAAAAAAACEDQQAhAgJAA0AgAiAGTw0BIAAgAkECdGr9AAQAIQQgAyAEIAT95gH95AEhAyACQQRqIQIMAAsLIAP9HwAgA/0fAZIgA/0fAiAD/R8DkpIhBQJAA0AgAiABTw0BIAUgACACQQJ0aioCACAAIAJBAnRqKgIAlJIhBSACQQFqIQIMAAsLIAWRC8ABBQF/AnsBfQF/AX0gAkF8cSEH/QwAAAAAAAAAAAAAAAAAAAAAIQRBACEDAkADQCADIAdPDQEgACADQQJ0av0ABAAgASADQQJ0av0ABAD95QEhBSAEIAUgBf3mAf3kASEEIANBBGohAwwACwsgBP0fACAE/R8BkiAE/R8CIAT9HwOSkiEGAkADQCADIAJPDQEgACADQQJ0aioCACABIANBAnRqKgIAkyEIIAYgCCAIlJIhBiADQQFqIQMMAAsLIAYLCwAgACABIAIQApEL";
+
+// src/vector/simd.ts
+var wasmExports = null;
+var f32View = null;
+function decodeBase64(base64) {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(base64, "base64"));
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+try {
+  const bytes = decodeBase64(SIMD_DISTANCE_WASM_BASE64);
+  const wasmBuffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  if (typeof WebAssembly !== "undefined" && typeof WebAssembly.validate === "function" && WebAssembly.validate(wasmBuffer)) {
+    const module = new WebAssembly.Module(wasmBuffer);
+    const instance = new WebAssembly.Instance(module);
+    wasmExports = instance.exports;
+    f32View = new Float32Array(wasmExports.memory.buffer);
+  }
+} catch {
+  wasmExports = null;
+  f32View = null;
+}
+var OFFSET_B_BYTES = 16384;
+function ensureMemory(dim) {
+  if (!wasmExports || !f32View) return;
+  const needed = OFFSET_B_BYTES + dim * 4;
+  const currentSize = wasmExports.memory.buffer.byteLength;
+  if (needed > currentSize) {
+    const pagesNeeded = Math.ceil(needed / 65536);
+    const currentPages = currentSize / 65536;
+    wasmExports.memory.grow(pagesNeeded - currentPages);
+    f32View = new Float32Array(wasmExports.memory.buffer);
+  }
+}
+function getF32View() {
+  if (!f32View) {
+    throw new Error("SIMD memory is not initialized");
+  }
+  return f32View;
+}
+function copyOneVector(a) {
+  getF32View().set(a, 0);
+}
+function copyTwoVectors(a, b) {
+  const view = getF32View();
+  view.set(a, 0);
+  view.set(b, OFFSET_B_BYTES / 4);
+}
+function simdDotProduct(a, b) {
+  if (!wasmExports || !f32View) return null;
+  ensureMemory(a.length);
+  copyTwoVectors(a, b);
+  return wasmExports.dot_product(0, OFFSET_B_BYTES, a.length);
+}
+function simdMagnitude(a) {
+  if (!wasmExports || !f32View) return null;
+  ensureMemory(a.length);
+  copyOneVector(a);
+  return wasmExports.magnitude(0, a.length);
+}
+function simdEuclideanDistance(a, b) {
+  if (!wasmExports || !f32View) return null;
+  ensureMemory(a.length);
+  copyTwoVectors(a, b);
+  return wasmExports.euclidean_distance(0, OFFSET_B_BYTES, a.length);
+}
+function isSimdAvailable() {
+  return wasmExports !== null;
+}
+
+// src/core/heap.ts
+function createMinHeap(compare) {
+  return createHeap(compare);
+}
+function createHeap(compare) {
+  const items = [];
+  function siftUp(idx) {
+    while (idx > 0) {
+      const parent = idx - 1 >> 1;
+      if (compare(items[idx], items[parent]) >= 0) break;
+      const tmp = items[idx];
+      items[idx] = items[parent];
+      items[parent] = tmp;
+      idx = parent;
+    }
+  }
+  function siftDown(idx) {
+    const len = items.length;
+    while (true) {
+      let smallest = idx;
+      const left = 2 * idx + 1;
+      const right = 2 * idx + 2;
+      if (left < len && compare(items[left], items[smallest]) < 0) smallest = left;
+      if (right < len && compare(items[right], items[smallest]) < 0) smallest = right;
+      if (smallest === idx) break;
+      const tmp = items[idx];
+      items[idx] = items[smallest];
+      items[smallest] = tmp;
+      idx = smallest;
+    }
+  }
+  return {
+    push(item) {
+      items.push(item);
+      siftUp(items.length - 1);
+    },
+    pop() {
+      if (items.length === 0) return void 0;
+      const top = items[0];
+      const last = items.pop();
+      if (items.length > 0) {
+        items[0] = last;
+        siftDown(0);
+      }
+      return top;
+    },
+    peek() {
+      return items[0];
+    },
+    get size() {
+      return items.length;
+    },
+    toSortedArray() {
+      return [...items].sort(compare);
+    }
+  };
+}
+
+// src/vector/similarity.ts
+function magnitude(v) {
+  const result = simdMagnitude(v);
+  if (result !== null) return result;
+  let sum = 0;
+  for (let i = 0; i < v.length; i++) {
+    sum += v[i] * v[i];
+  }
+  return Math.sqrt(sum);
+}
+function cosineSimilarityWithMagnitudes(a, b, magA, magB) {
+  if (magA === 0 || magB === 0) return 0;
+  return dotProduct(a, b) / (magA * magB);
+}
+function dotProduct(a, b) {
+  const result = simdDotProduct(a, b);
+  if (result !== null) return result;
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) {
+    sum += a[i] * b[i];
+  }
+  return sum;
+}
+function euclideanDistance(a, b) {
+  const result = simdEuclideanDistance(a, b);
+  if (result !== null) return result;
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) {
+    const diff = a[i] - b[i];
+    sum += diff * diff;
+  }
+  return Math.sqrt(sum);
+}
+
+// src/vector/hnsw.ts
+var MAX_LAYER_CAP = 32;
+function toDistance(a, b, magA, magB, metric) {
+  switch (metric) {
+    case "cosine":
+      return 1 - cosineSimilarityWithMagnitudes(a, b, magA, magB);
+    case "dotProduct":
+      return -dotProduct(a, b);
+    case "euclidean":
+      return euclideanDistance(a, b);
+  }
+}
+function toScore(distance, metric) {
+  switch (metric) {
+    case "cosine":
+      return 1 - distance;
+    case "dotProduct":
+      return -distance;
+    case "euclidean":
+      return 1 / (1 + distance);
+  }
+}
+var distanceAsc = (a, b) => a.distance - b.distance;
+var distanceDesc = (a, b) => b.distance - a.distance;
+function createHNSWIndex(dimension, config) {
+  const M = config?.m ?? 16;
+  const Mmax0 = M * 2;
+  const efCons = config?.efConstruction ?? 200;
+  const buildMetric = config?.metric ?? "cosine";
+  const mL = 1 / Math.log(M);
+  const nodes = /* @__PURE__ */ new Map();
+  let entryPointId = null;
+  let topLayer = -1;
+  function randomLevel() {
+    let u = Math.random();
+    if (u === 0) u = Number.MIN_VALUE;
+    return Math.min(Math.floor(-Math.log(u) * mL), MAX_LAYER_CAP);
+  }
+  function nodeDistance(a, b, metric) {
+    return toDistance(a.vector, b.vector, a.mag, b.mag, metric);
+  }
+  function queryDistance(qVec, qMag, node, metric) {
+    return toDistance(qVec, node.vector, qMag, node.mag, metric);
+  }
+  function maxConns(layer) {
+    return layer === 0 ? Mmax0 : M;
+  }
+  function searchLayer(qVec, qMag, eps, ef, layer, metric) {
+    const visited = /* @__PURE__ */ new Set();
+    const candidates = createMinHeap(distanceAsc);
+    const results = createMinHeap(distanceDesc);
+    let furthestDist = Number.POSITIVE_INFINITY;
+    for (const epId of eps) {
+      if (visited.has(epId)) continue;
+      visited.add(epId);
+      const node = nodes.get(epId);
+      if (!node) continue;
+      const dist = queryDistance(qVec, qMag, node, metric);
+      const pair = { docId: epId, distance: dist };
+      candidates.push(pair);
+      results.push(pair);
+      if (results.size > ef) {
+        results.pop();
+      }
+    }
+    const topResult = results.peek();
+    if (topResult) furthestDist = topResult.distance;
+    while (candidates.size > 0) {
+      const nearest = candidates.pop();
+      if (!nearest) break;
+      if (nearest.distance > furthestDist) break;
+      const node = nodes.get(nearest.docId);
+      if (!node || layer >= node.connections.length) continue;
+      for (const neighborId of node.connections[layer]) {
+        if (visited.has(neighborId)) continue;
+        visited.add(neighborId);
+        const neighborNode = nodes.get(neighborId);
+        if (!neighborNode) continue;
+        const dist = queryDistance(qVec, qMag, neighborNode, metric);
+        if (dist < furthestDist || results.size < ef) {
+          const pair = { docId: neighborId, distance: dist };
+          candidates.push(pair);
+          results.push(pair);
+          if (results.size > ef) {
+            results.pop();
+          }
+          const newTop = results.peek();
+          if (newTop) furthestDist = newTop.distance;
+        }
+      }
+    }
+    return results.toSortedArray();
+  }
+  function selectNeighborsHeuristic(targetVec, targetMag, candidates, maxConnections, layer, metric, extendCandidates, keepPruned) {
+    const working = [...candidates].sort((a, b) => a.distance - b.distance);
+    const selected = [];
+    const discarded = [];
+    for (const candidate of working) {
+      if (selected.length >= maxConnections) break;
+      let accepted = true;
+      for (const sel of selected) {
+        const selNode = nodes.get(sel.docId);
+        const candNode = nodes.get(candidate.docId);
+        if (!selNode || !candNode) continue;
+        const distBetween = nodeDistance(candNode, selNode, metric);
+        if (candidate.distance >= distBetween) {
+          accepted = false;
+          break;
+        }
+      }
+      if (accepted) {
+        selected.push(candidate);
+      } else {
+        discarded.push(candidate);
+      }
+    }
+    {
+      for (const disc of discarded) {
+        if (selected.length >= maxConnections) break;
+        selected.push(disc);
+      }
+    }
+    return selected;
+  }
+  function pruneConnections(node, layer, metric) {
+    const mc = maxConns(layer);
+    if (node.connections[layer].size <= mc) return;
+    const conns = [];
+    for (const connId of node.connections[layer]) {
+      const connNode = nodes.get(connId);
+      if (!connNode) continue;
+      conns.push({
+        docId: connId,
+        distance: nodeDistance(node, connNode, metric)
+      });
+    }
+    const pruned = selectNeighborsHeuristic(node.vector, node.mag, conns, mc, layer, metric);
+    node.connections[layer] = new Set(pruned.map((p) => p.docId));
+  }
+  function insert(docId, vector) {
+    if (vector.length !== dimension) {
+      throw new Error(`Vector dimension mismatch: expected ${dimension}, got ${vector.length}`);
+    }
+    if (nodes.has(docId)) {
+      remove(docId);
+    }
+    const mag = magnitude(vector);
+    const l = randomLevel();
+    const node = {
+      docId,
+      vector,
+      mag,
+      maxLayer: l,
+      connections: Array.from({ length: l + 1 }, () => /* @__PURE__ */ new Set())
+    };
+    nodes.set(docId, node);
+    if (entryPointId === null) {
+      entryPointId = docId;
+      topLayer = l;
+      return;
+    }
+    const metric = buildMetric;
+    let currentEPs = [entryPointId];
+    for (let layer = topLayer; layer > l; layer--) {
+      const nearest = searchLayer(vector, mag, currentEPs, 1, layer, metric);
+      if (nearest.length > 0) {
+        currentEPs = [nearest[0].docId];
+      }
+    }
+    for (let layer = Math.min(l, topLayer); layer >= 0; layer--) {
+      const mc = maxConns(layer);
+      const nearest = searchLayer(vector, mag, currentEPs, efCons, layer, metric);
+      const neighbors = selectNeighborsHeuristic(vector, mag, nearest, mc, layer, metric);
+      for (const neighbor of neighbors) {
+        node.connections[layer].add(neighbor.docId);
+        const neighborNode = nodes.get(neighbor.docId);
+        if (neighborNode && layer < neighborNode.connections.length) {
+          neighborNode.connections[layer].add(docId);
+          pruneConnections(neighborNode, layer, metric);
+        }
+      }
+      if (nearest.length > 0) {
+        currentEPs = nearest.map((n) => n.docId);
+      }
+    }
+    if (l > topLayer) {
+      entryPointId = docId;
+      topLayer = l;
+    }
+  }
+  function remove(docId) {
+    const node = nodes.get(docId);
+    if (!node) return;
+    const metric = buildMetric;
+    for (let layer = 0; layer <= node.maxLayer; layer++) {
+      if (layer >= node.connections.length) continue;
+      const formerNeighborIds = new Set(node.connections[layer]);
+      for (const neighborId of formerNeighborIds) {
+        const neighborNode = nodes.get(neighborId);
+        if (neighborNode && layer < neighborNode.connections.length) {
+          neighborNode.connections[layer].delete(docId);
+        }
+      }
+      for (const neighborId of formerNeighborIds) {
+        const neighborNode = nodes.get(neighborId);
+        if (!neighborNode || layer >= neighborNode.connections.length) continue;
+        const mc = maxConns(layer);
+        if (neighborNode.connections[layer].size >= mc) continue;
+        const candidateIds = new Set(neighborNode.connections[layer]);
+        for (const otherId of formerNeighborIds) {
+          if (otherId !== neighborId && otherId !== docId) {
+            candidateIds.add(otherId);
+          }
+        }
+        const candidates = [];
+        for (const candId of candidateIds) {
+          const candNode = nodes.get(candId);
+          if (!candNode) continue;
+          candidates.push({
+            docId: candId,
+            distance: nodeDistance(neighborNode, candNode, metric)
+          });
+        }
+        const selected = selectNeighborsHeuristic(
+          neighborNode.vector,
+          neighborNode.mag,
+          candidates,
+          mc,
+          layer,
+          metric);
+        const newConns = new Set(selected.map((s) => s.docId));
+        neighborNode.connections[layer] = newConns;
+        for (const newConnId of newConns) {
+          const newConnNode = nodes.get(newConnId);
+          if (newConnNode && layer < newConnNode.connections.length) {
+            newConnNode.connections[layer].add(neighborId);
+            pruneConnections(newConnNode, layer, metric);
+          }
+        }
+      }
+    }
+    nodes.delete(docId);
+    if (entryPointId === docId) {
+      if (nodes.size === 0) {
+        entryPointId = null;
+        topLayer = -1;
+        return;
+      }
+      let newEntryId = null;
+      let newTopLayer = -1;
+      for (const [nId, n] of nodes) {
+        if (n.maxLayer > newTopLayer) {
+          newTopLayer = n.maxLayer;
+          newEntryId = nId;
+        }
+      }
+      entryPointId = newEntryId;
+      topLayer = newTopLayer;
+    }
+  }
+  function search(query, k, searchMetric, minSimilarity, filterDocIds, efSearch) {
+    if (query.length !== dimension) {
+      throw new Error(`Query dimension mismatch: expected ${dimension}, got ${query.length}`);
+    }
+    if (entryPointId === null || nodes.size === 0) {
+      return [];
+    }
+    let ef = Math.max(efSearch ?? 50, k);
+    if (filterDocIds && filterDocIds.size < nodes.size) {
+      const selectivity = filterDocIds.size / nodes.size;
+      ef = Math.max(ef, Math.ceil(k / Math.max(selectivity, 0.01)));
+      ef = Math.min(ef, nodes.size);
+    }
+    const qMag = magnitude(query);
+    let currentEPs = [entryPointId];
+    for (let layer = topLayer; layer >= 1; layer--) {
+      const nearest = searchLayer(query, qMag, currentEPs, 1, layer, searchMetric);
+      if (nearest.length > 0) {
+        currentEPs = [nearest[0].docId];
+      }
+    }
+    const candidates = searchLayer(query, qMag, currentEPs, ef, 0, searchMetric);
+    const results = [];
+    for (const cand of candidates) {
+      if (filterDocIds && !filterDocIds.has(cand.docId)) continue;
+      const score = toScore(cand.distance, searchMetric);
+      if (score < minSimilarity) continue;
+      results.push({
+        docId: cand.docId,
+        score,
+        termFrequencies: {},
+        fieldLengths: {},
+        idf: {}
+      });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, k);
+  }
+  function serialize() {
+    const nodeArray = [];
+    for (const [docId, node] of nodes) {
+      const layerConns = [];
+      for (let layer = 0; layer < node.connections.length; layer++) {
+        if (node.connections[layer].size > 0) {
+          layerConns.push([layer, Array.from(node.connections[layer])]);
+        }
+      }
+      nodeArray.push([docId, node.maxLayer, layerConns]);
+    }
+    return {
+      entryPoint: entryPointId ?? "",
+      maxLayer: topLayer,
+      m: M,
+      efConstruction: efCons,
+      metric: buildMetric,
+      nodes: nodeArray
+    };
+  }
+  function deserialize(data, vectors) {
+    nodes.clear();
+    for (const [docId, maxLayer, layerConns] of data.nodes) {
+      const vecData = vectors.get(docId);
+      if (!vecData) continue;
+      const connections = Array.from({ length: maxLayer + 1 }, () => /* @__PURE__ */ new Set());
+      for (const [layer, neighbors] of layerConns) {
+        if (layer < connections.length) {
+          connections[layer] = new Set(neighbors);
+        }
+      }
+      nodes.set(docId, {
+        docId,
+        vector: vecData.vector,
+        mag: vecData.mag,
+        maxLayer,
+        connections
+      });
+    }
+    if (data.entryPoint && nodes.has(data.entryPoint)) {
+      entryPointId = data.entryPoint;
+      topLayer = data.maxLayer;
+    } else if (nodes.size > 0) {
+      let bestId = null;
+      let bestLayer = -1;
+      for (const [nId, n] of nodes) {
+        if (n.maxLayer > bestLayer) {
+          bestLayer = n.maxLayer;
+          bestId = nId;
+        }
+      }
+      entryPointId = bestId;
+      topLayer = bestLayer;
+    } else {
+      entryPointId = null;
+      topLayer = -1;
+    }
+  }
+  function clear() {
+    nodes.clear();
+    entryPointId = null;
+    topLayer = -1;
+  }
+  function* entriesIterator() {
+    for (const [docId, node] of nodes) {
+      yield [docId, { docId, vector: node.vector, magnitude: node.mag }];
+    }
+  }
+  return {
+    get dimension() {
+      return dimension;
+    },
+    get size() {
+      return nodes.size;
+    },
+    get entryPointId() {
+      return entryPointId;
+    },
+    get topLayer() {
+      return topLayer;
+    },
+    get m() {
+      return M;
+    },
+    get efConstruction() {
+      return efCons;
+    },
+    get metric() {
+      return buildMetric;
+    },
+    insert,
+    remove,
+    has: (docId) => nodes.has(docId),
+    search,
+    clear,
+    entries: entriesIterator,
+    serialize,
+    deserialize
+  };
+}
+
+export { cosineSimilarityWithMagnitudes, createHNSWIndex, dotProduct, euclideanDistance, isSimdAvailable, magnitude };