@delali/narsil 0.2.4-next.45 → 0.2.4-next.47

package/dist/index.browser.mjs

@@ -2406,12 +2406,12 @@ function removeNeighbor(adj, ord, layer, neighborOrd) {
     return;
   }
 }
-function replaceNeighbors(adj, ord, layer, neighbors) {
+function replaceNeighbors(adj, ord, layer, neighbors, count) {
   const base = layerBase(adj, ord, layer);
   if (base === ABSENT) return;
   const array = layerArray(adj, layer);
   const stride = layer === 0 ? adj.level0Stride : adj.upperStride;
-  const limit = Math.min(neighbors.length, stride - 1);
+  const limit = Math.min(count, stride - 1);
   for (let i = 0; i < limit; i++) {
     array[base + i + 1] = neighbors[i];
   }
@@ -12031,90 +12031,6 @@ function createVectorStore() {
   };
 }
 
-// src/core/heap.ts
-function createMinHeap(compare) {
-  return createHeap(compare);
-}
-function createMaxHeap(compare) {
-  return createHeap((a, b) => compare(b, a));
-}
-function createBoundedMaxHeap(compare, capacity) {
-  const heap = createMaxHeap(compare);
-  const innerPush = heap.push;
-  return {
-    push(item) {
-      if (heap.size < capacity) {
-        innerPush(item);
-        return;
-      }
-      const top = heap.peek();
-      if (top !== void 0 && compare(item, top) < 0) {
-        heap.pop();
-        innerPush(item);
-      }
-    },
-    pop: heap.pop,
-    peek: heap.peek,
-    get size() {
-      return heap.size;
-    },
-    toSortedArray: heap.toSortedArray
-  };
-}
-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 siftDown2(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;
-        siftDown2(0);
-      }
-      return top;
-    },
-    peek() {
-      return items[0];
-    },
-    get size() {
-      return items.length;
-    },
-    toSortedArray() {
-      return [...items].sort(compare);
-    }
-  };
-}
-
 // src/vector/hnsw/shared.ts
 var COMPACTION_TOMBSTONE_RATIO = 0.1;
 var COMPACTION_ABSOLUTE_THRESHOLD = 1e3;
@@ -12165,8 +12081,6 @@ function toScore(distance, metric) {
       return 1 / (1 + distance);
   }
 }
-var distanceAsc = (a, b) => a.distance - b.distance;
-var distanceDesc = (a, b) => b.distance - a.distance;
 function randomLevel(mL) {
   let u = Math.random();
   if (u === 0) u = Number.MIN_VALUE;
@@ -12193,37 +12107,168 @@ function addConnection(connections, ord) {
   connections.push(ord);
 }
 
+// src/vector/hnsw/workspace.ts
+var INITIAL_LIST_CAPACITY = 64;
+function createList(capacity) {
+  return { ords: new Int32Array(capacity), distances: new Float64Array(capacity), size: 0 };
+}
+function createHeap(greatestFirst) {
+  return { ...createList(INITIAL_LIST_CAPACITY), greatestFirst, topOrd: -1, topDistance: 0 };
+}
+function createHNSWWorkspace() {
+  return {
+    frontier: createHeap(false),
+    found: createHeap(true),
+    entryPoints: new Int32Array(INITIAL_LIST_CAPACITY),
+    entryPointCount: 0,
+    traversal: createList(INITIAL_LIST_CAPACITY),
+    working: createList(INITIAL_LIST_CAPACITY),
+    insertSelection: createList(INITIAL_LIST_CAPACITY),
+    pruneCandidates: createList(INITIAL_LIST_CAPACITY),
+    pruneSelection: createList(INITIAL_LIST_CAPACITY),
+    repairCandidates: createList(INITIAL_LIST_CAPACITY),
+    repairSelection: createList(INITIAL_LIST_CAPACITY)
+  };
+}
+function ensureListCapacity(list, needed) {
+  if (needed <= list.ords.length) return;
+  let capacity = list.ords.length === 0 ? INITIAL_LIST_CAPACITY : list.ords.length;
+  while (capacity < needed) capacity *= 2;
+  const ords = new Int32Array(capacity);
+  ords.set(list.ords);
+  list.ords = ords;
+  const distances = new Float64Array(capacity);
+  distances.set(list.distances);
+  list.distances = distances;
+}
+function appendToList(list, ord, distance) {
+  ensureListCapacity(list, list.size + 1);
+  list.ords[list.size] = ord;
+  list.distances[list.size] = distance;
+  list.size += 1;
+}
+function copyList(source, target) {
+  ensureListCapacity(target, source.size);
+  target.ords.set(source.ords.subarray(0, source.size));
+  target.distances.set(source.distances.subarray(0, source.size));
+  target.size = source.size;
+}
+function sortListByDistance(list) {
+  const { ords, distances } = list;
+  for (let i = 1; i < list.size; i++) {
+    const ord = ords[i];
+    const distance = distances[i];
+    let j = i - 1;
+    while (j >= 0 && distances[j] > distance) {
+      distances[j + 1] = distances[j];
+      ords[j + 1] = ords[j];
+      j -= 1;
+    }
+    distances[j + 1] = distance;
+    ords[j + 1] = ord;
+  }
+}
+function heapPrecedes(heap, a, b) {
+  return heap.greatestFirst ? heap.distances[a] > heap.distances[b] : heap.distances[a] < heap.distances[b];
+}
+function swapHeapEntries(heap, a, b) {
+  const ord = heap.ords[a];
+  heap.ords[a] = heap.ords[b];
+  heap.ords[b] = ord;
+  const distance = heap.distances[a];
+  heap.distances[a] = heap.distances[b];
+  heap.distances[b] = distance;
+}
+function pushHeap(heap, ord, distance) {
+  appendToList(heap, ord, distance);
+  let index = heap.size - 1;
+  while (index > 0) {
+    const parent = index - 1 >> 1;
+    if (!heapPrecedes(heap, index, parent)) break;
+    swapHeapEntries(heap, index, parent);
+    index = parent;
+  }
+}
+function popHeap(heap) {
+  if (heap.size === 0) return false;
+  heap.topOrd = heap.ords[0];
+  heap.topDistance = heap.distances[0];
+  heap.size -= 1;
+  if (heap.size > 0) {
+    heap.ords[0] = heap.ords[heap.size];
+    heap.distances[0] = heap.distances[heap.size];
+    let index = 0;
+    for (; ; ) {
+      const left = 2 * index + 1;
+      const right = left + 1;
+      let first = index;
+      if (left < heap.size && heapPrecedes(heap, left, first)) first = left;
+      if (right < heap.size && heapPrecedes(heap, right, first)) first = right;
+      if (first === index) break;
+      swapHeapEntries(heap, index, first);
+      index = first;
+    }
+  }
+  return true;
+}
+function resetHeap(heap) {
+  heap.size = 0;
+}
+function drainHeapNearestFirst(heap, list) {
+  const count = heap.size;
+  ensureListCapacity(list, count);
+  list.size = count;
+  for (let i = count - 1; i >= 0; i--) {
+    if (!popHeap(heap)) break;
+    list.ords[i] = heap.topOrd;
+    list.distances[i] = heap.topDistance;
+  }
+}
+function setSingleEntryPoint(workspace, ord) {
+  workspace.entryPoints[0] = ord;
+  workspace.entryPointCount = 1;
+}
+function setEntryPointsFromList(workspace, list) {
+  if (list.size > workspace.entryPoints.length) {
+    let capacity = workspace.entryPoints.length;
+    while (capacity < list.size) capacity *= 2;
+    workspace.entryPoints = new Int32Array(capacity);
+  }
+  workspace.entryPoints.set(list.ords.subarray(0, list.size));
+  workspace.entryPointCount = list.size;
+}
+
 // src/vector/hnsw/graph-ops.ts
-function searchLayer(state, qVec, qMag, eps, ef, layer, metric, skipTombstones, distFn) {
+function searchLayer(state, qVec, qMag, ef, layer, metric, skipTombstones, distFn, results) {
   const getDistance = distFn ?? ((ord) => queryDistanceByOrd(state, qVec, qMag, ord, metric));
+  const workspace = state.workspace;
+  const frontier = workspace.frontier;
+  const found = workspace.found;
   const adjacency = state.adjacency;
   const neighbors = layerArray(adjacency, layer);
   const visited = state.visited;
   const stamp = nextVisitStamp(state);
-  const candidates = createMinHeap(distanceAsc);
-  const results = createMinHeap(distanceDesc);
+  resetHeap(frontier);
+  resetHeap(found);
   let furthestDist = Number.POSITIVE_INFINITY;
-  for (const epOrd of eps) {
+  for (let i = 0; i < workspace.entryPointCount; i++) {
+    const epOrd = workspace.entryPoints[i];
     if (visited[epOrd] === stamp) continue;
     visited[epOrd] = stamp;
     if (!nodeExists(state, epOrd)) continue;
     if (skipTombstones && state.tombstones[epOrd] === 1) continue;
     const dist = getDistance(epOrd);
     if (dist === Number.POSITIVE_INFINITY) continue;
-    const pair = { ord: epOrd, 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 base = layerBase(adjacency, nearest.ord, layer);
+    pushHeap(frontier, epOrd, dist);
+    pushHeap(found, epOrd, dist);
+    if (found.size > ef) {
+      popHeap(found);
+    }
+  }
+  if (found.size > 0) furthestDist = found.distances[0];
+  while (popHeap(frontier)) {
+    if (frontier.topDistance > furthestDist) break;
+    const base = layerBase(adjacency, frontier.topOrd, layer);
     if (base === -1) continue;
     const count = neighbors[base];
     for (let i = 1; i <= count; i++) {
@@ -12234,55 +12279,41 @@ function searchLayer(state, qVec, qMag, eps, ef, layer, metric, skipTombstones,
       if (!nodeExists(state, neighborOrd)) continue;
       const dist = getDistance(neighborOrd);
       if (dist === Number.POSITIVE_INFINITY) continue;
-      if (dist < furthestDist || results.size < ef) {
-        const pair = { ord: neighborOrd, distance: dist };
-        candidates.push(pair);
-        results.push(pair);
-        if (results.size > ef) {
-          results.pop();
+      if (dist < furthestDist || found.size < ef) {
+        pushHeap(frontier, neighborOrd, dist);
+        pushHeap(found, neighborOrd, dist);
+        if (found.size > ef) {
+          popHeap(found);
         }
-        const newTop = results.peek();
-        if (newTop) furthestDist = newTop.distance;
+        furthestDist = found.distances[0];
       }
     }
   }
-  return results;
-}
-function nearestFromHeap(heap) {
-  let nearest;
-  while (heap.size > 0) {
-    nearest = heap.pop();
-  }
-  return nearest;
+  drainHeapNearestFirst(found, results);
 }
-function selectNeighborsHeuristic(state, targetOrd, candidates, maxConnections, layer, metric, extendCandidates, keepPruned) {
-  const working = [...candidates];
-  working.sort((a, b) => a.distance - b.distance);
-  const selected = [];
-  const discarded = [];
-  for (const candidate of working) {
-    if (selected.length >= maxConnections) break;
+function selectNeighborsHeuristic(state, candidates, maxConnections, metric, selected) {
+  const working = state.workspace.working;
+  copyList(candidates, working);
+  sortListByDistance(working);
+  ensureListCapacity(selected, Math.min(maxConnections, working.size));
+  selected.size = 0;
+  for (let i = 0; i < working.size; i++) {
+    if (selected.size >= maxConnections) break;
+    const candidateOrd = working.ords[i];
+    const candidateDistance = working.distances[i];
     let accepted = true;
-    for (const sel of selected) {
-      const distBetween = nodeDistanceByOrd(state, candidate.ord, sel.ord, metric);
-      if (candidate.distance >= distBetween) {
+    for (let s = 0; s < selected.size; s++) {
+      const distBetween = nodeDistanceByOrd(state, candidateOrd, selected.ords[s], metric);
+      if (candidateDistance >= 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);
-    }
+    if (!accepted) continue;
+    selected.ords[selected.size] = candidateOrd;
+    selected.distances[selected.size] = candidateDistance;
+    selected.size += 1;
   }
-  return selected;
 }
 function pruneConnections(state, ord, layer, metric) {
   const adjacency = state.adjacency;
@@ -12292,17 +12323,20 @@ function pruneConnections(state, ord, layer, metric) {
   const neighbors = layerArray(adjacency, layer);
   const count = neighbors[base];
   if (count <= mc) return;
-  const conns = [];
+  const candidates = state.workspace.pruneCandidates;
+  candidates.size = 0;
+  ensureListCapacity(candidates, count);
   for (let i = 1; i <= count; i++) {
     const connOrd = neighbors[base + i];
     const dist = nodeDistanceByOrd(state, ord, connOrd, metric);
     if (dist === Number.POSITIVE_INFINITY) continue;
-    conns.push({ ord: connOrd, distance: dist });
+    candidates.ords[candidates.size] = connOrd;
+    candidates.distances[candidates.size] = dist;
+    candidates.size += 1;
   }
-  const pruned = selectNeighborsHeuristic(state, ord, conns, mc, layer, metric);
-  const next = [];
-  for (const p of pruned) addConnection(next, p.ord);
-  replaceNeighbors(adjacency, ord, layer, next);
+  const kept = state.workspace.pruneSelection;
+  selectNeighborsHeuristic(state, candidates, mc, metric, kept);
+  replaceNeighbors(adjacency, ord, layer, kept.ords, kept.size);
 }
 
 // src/vector/hnsw/mutation.ts
@@ -12312,30 +12346,23 @@ function clearTombstone(state, ord) {
     state.tombstoneCount--;
   }
 }
-function reassignEntryPoint(state) {
+function highestNode(state, includeTombstoned) {
   let bestOrd = -1;
   let bestLayer = -1;
   for (let ord = 0; ord < state.adjacency.slots; ord++) {
     const level = nodeMaxLayer(state, ord);
     if (level === -1) continue;
-    if (state.tombstones[ord] === 1) continue;
+    if (!includeTombstoned && state.tombstones[ord] === 1) continue;
     if (level > bestLayer) {
       bestLayer = level;
       bestOrd = ord;
     }
   }
-  if (bestOrd === -1) {
-    for (let ord = 0; ord < state.adjacency.slots; ord++) {
-      const level = nodeMaxLayer(state, ord);
-      if (level === -1) continue;
-      if (level > bestLayer) {
-        bestLayer = level;
-        bestOrd = ord;
-      }
-    }
-  }
-  state.entryPointOrd = bestOrd;
-  state.topLayer = bestOrd === -1 ? -1 : bestLayer;
+  return bestOrd;
+}
+function setEntryPoint(state, ord) {
+  state.entryPointOrd = ord;
+  state.topLayer = ord === -1 ? -1 : nodeMaxLayer(state, ord);
 }
 function insertNode(state, docId) {
   const ord = state.store.getOrdinal(docId);
@@ -12363,39 +12390,30 @@ function insertNode(state, docId) {
     return;
   }
   const metric = state.buildMetric;
+  const workspace = state.workspace;
+  const candidates = workspace.traversal;
+  const selected = workspace.insertSelection;
   const insertDistFn = (candOrd) => nodeDistanceByOrd(state, ord, candOrd, metric);
-  let currentEPs = [state.entryPointOrd];
+  setSingleEntryPoint(workspace, state.entryPointOrd);
   for (let layer = state.topLayer; layer > l; layer--) {
-    const heap = searchLayer(state, entry.vector, entry.magnitude, currentEPs, 1, layer, metric, false, insertDistFn);
-    const nearest = nearestFromHeap(heap);
-    if (nearest) {
-      currentEPs = [nearest.ord];
+    searchLayer(state, entry.vector, entry.magnitude, 1, layer, metric, false, insertDistFn, candidates);
+    if (candidates.size > 0) {
+      setSingleEntryPoint(workspace, candidates.ords[0]);
     }
   }
   for (let layer = Math.min(l, state.topLayer); layer >= 0; layer--) {
-    const heap = searchLayer(
-      state,
-      entry.vector,
-      entry.magnitude,
-      currentEPs,
-      state.efCons,
-      layer,
-      metric,
-      false,
-      insertDistFn
-    );
-    const candidates = heap.toSortedArray().reverse();
-    const mc = maxConns(state, layer);
-    const neighbors = selectNeighborsHeuristic(state, ord, candidates, mc, layer, metric);
-    for (const neighbor of neighbors) {
-      addNeighbor(state.adjacency, ord, layer, neighbor.ord);
-      if (layer <= nodeMaxLayer(state, neighbor.ord)) {
-        addNeighbor(state.adjacency, neighbor.ord, layer, ord);
-        pruneConnections(state, neighbor.ord, layer, metric);
+    searchLayer(state, entry.vector, entry.magnitude, state.efCons, layer, metric, false, insertDistFn, candidates);
+    selectNeighborsHeuristic(state, candidates, maxConns(state, layer), metric, selected);
+    for (let i = 0; i < selected.size; i++) {
+      const neighborOrd = selected.ords[i];
+      addNeighbor(state.adjacency, ord, layer, neighborOrd);
+      if (layer <= nodeMaxLayer(state, neighborOrd)) {
+        addNeighbor(state.adjacency, neighborOrd, layer, ord);
+        pruneConnections(state, neighborOrd, layer, metric);
       }
     }
-    if (candidates.length > 0) {
-      currentEPs = candidates.map((n) => n.ord);
+    if (candidates.size > 0) {
+      setEntryPointsFromList(workspace, candidates);
     }
   }
   if (l > state.topLayer) {
@@ -12425,17 +12443,18 @@ function removeNodeEager(state, ord, excludeOrds) {
           candidateOrds.add(otherOrd);
         }
       }
-      const candidates = [];
+      const candidates = state.workspace.repairCandidates;
+      candidates.size = 0;
       for (const candOrd of candidateOrds) {
         const dist = nodeDistanceByOrd(state, neighborOrd, candOrd, metric);
         if (dist === Number.POSITIVE_INFINITY) continue;
-        candidates.push({ ord: candOrd, distance: dist });
+        appendToList(candidates, candOrd, dist);
       }
-      const selected = selectNeighborsHeuristic(state, neighborOrd, candidates, mc, layer, metric);
-      const newConns = [];
-      for (const s of selected) addConnection(newConns, s.ord);
-      replaceNeighbors(state.adjacency, neighborOrd, layer, newConns);
-      for (const newConnOrd of newConns) {
+      const selected = state.workspace.repairSelection;
+      selectNeighborsHeuristic(state, candidates, mc, metric, selected);
+      replaceNeighbors(state.adjacency, neighborOrd, layer, selected.ords, selected.size);
+      for (let i = 0; i < selected.size; i++) {
+        const newConnOrd = selected.ords[i];
         if (layer <= nodeMaxLayer(state, newConnOrd)) {
           addNeighbor(state.adjacency, newConnOrd, layer, neighborOrd);
           pruneConnections(state, newConnOrd, layer, metric);
@@ -12448,11 +12467,11 @@ function removeNodeEager(state, ord, excludeOrds) {
   clearTombstone(state, ord);
   if (state.entryPointOrd === ord) {
     if (state.nodeCount === 0) {
-      state.entryPointOrd = -1;
-      state.topLayer = -1;
+      setEntryPoint(state, -1);
       return;
     }
-    reassignEntryPoint(state);
+    const live = highestNode(state, false);
+    setEntryPoint(state, live === -1 ? highestNode(state, true) : live);
   }
 }
 function markTombstone(state, docId) {
@@ -12463,24 +12482,7 @@ function markTombstone(state, docId) {
     state.tombstoneCount++;
   }
   if (state.entryPointOrd === ord) {
-    let bestOrd = -1;
-    let bestLayer = -1;
-    for (let o = 0; o < state.adjacency.slots; o++) {
-      const level = nodeMaxLayer(state, o);
-      if (level === -1) continue;
-      if (state.tombstones[o] === 1) continue;
-      if (level > bestLayer) {
-        bestLayer = level;
-        bestOrd = o;
-      }
-    }
-    if (bestOrd !== -1) {
-      state.entryPointOrd = bestOrd;
-      state.topLayer = bestLayer;
-    } else {
-      state.entryPointOrd = -1;
-      state.topLayer = -1;
-    }
+    setEntryPoint(state, highestNode(state, false));
   }
 }
 function compactTombstones(state) {
@@ -12593,7 +12595,7 @@ function deserializeGraph(state, data) {
   for (const node of nodes) {
     createNode(state.adjacency, node.ord, node.maxLayer);
     for (const [layer, neighbors] of node.layers) {
-      replaceNeighbors(state.adjacency, node.ord, layer, neighbors);
+      replaceNeighbors(state.adjacency, node.ord, layer, neighbors, neighbors.length);
     }
     state.nodeCount++;
   }
@@ -12660,20 +12662,20 @@ function collectHits(state, query, k, searchMetric, minSimilarity, filter, efSea
     const metric = searchMetric;
     distFn = (ord) => store.distanceFromArena(arenaQuery, ord, metric);
   }
-  let currentEPs = [state.entryPointOrd];
+  const workspace = state.workspace;
+  const candidates = workspace.traversal;
+  setSingleEntryPoint(workspace, state.entryPointOrd);
   for (let layer = state.topLayer; layer >= 1; layer--) {
-    const heap = searchLayer(state, query, qMag, currentEPs, 1, layer, searchMetric, true, distFn);
-    const nearest = nearestFromHeap(heap);
-    if (nearest) {
-      currentEPs = [nearest.ord];
+    searchLayer(state, query, qMag, 1, layer, searchMetric, true, distFn, candidates);
+    if (candidates.size > 0) {
+      setSingleEntryPoint(workspace, candidates.ords[0]);
     }
   }
-  const candidateHeap = searchLayer(state, query, qMag, currentEPs, ef, 0, searchMetric, true, distFn);
-  const candidateArray = candidateHeap.toSortedArray().reverse();
+  searchLayer(state, query, qMag, ef, 0, searchMetric, true, distFn, candidates);
   if (useQuantized) {
     return rerankWithFullPrecision(
       state,
-      candidateArray,
+      candidates,
       query,
       qMag,
       arenaQuery,
@@ -12685,33 +12687,35 @@ function collectHits(state, query, k, searchMetric, minSimilarity, filter, efSea
     );
   }
   const hits = [];
-  for (const cand of candidateArray) {
-    if (filter && !ordinalFilterHas(filter, cand.ord)) continue;
-    const score = toScore(cand.distance, searchMetric);
+  for (let i = 0; i < candidates.size; i++) {
+    const ord = candidates.ords[i];
+    if (filter && !ordinalFilterHas(filter, ord)) continue;
+    const score = toScore(candidates.distances[i], searchMetric);
     if (score < minSimilarity) continue;
-    if (!hasDocument(cand.ord)) continue;
-    hits.push({ ord: cand.ord, score });
+    if (!hasDocument(ord)) continue;
+    hits.push({ ord, score });
   }
   return hits;
 }
 function rerankWithFullPrecision(state, candidates, query, qMag, arenaQuery, k, metric, minSimilarity, filter, hasDocument) {
   const reranked = [];
   const rerankLimit = Math.max(k * SQ8_OVERSELECTION_FACTOR, 10);
-  for (const cand of candidates) {
-    if (filter && !ordinalFilterHas(filter, cand.ord)) continue;
+  for (let i = 0; i < candidates.size; i++) {
+    const ord = candidates.ords[i];
+    if (filter && !ordinalFilterHas(filter, ord)) continue;
     let fullDistance;
     if (arenaQuery) {
-      fullDistance = state.store.distanceFromArena(arenaQuery, cand.ord, metric);
+      fullDistance = state.store.distanceFromArena(arenaQuery, ord, metric);
       if (fullDistance === Number.POSITIVE_INFINITY) continue;
     } else {
-      const entry = entryForOrd(state, cand.ord);
+      const entry = entryForOrd(state, ord);
       if (!entry) continue;
       fullDistance = toDistance(query, entry.vector, qMag, entry.magnitude, metric);
     }
     const score = toScore(fullDistance, metric);
     if (score < minSimilarity) continue;
-    if (!hasDocument(cand.ord)) continue;
-    reranked.push({ ord: cand.ord, score });
+    if (!hasDocument(ord)) continue;
+    reranked.push({ ord, score });
     if (reranked.length >= rerankLimit) break;
   }
   return reranked;
@@ -12759,7 +12763,8 @@ function createHNSWIndex(dimension, store, config, quantizer) {
     visited: new Uint32Array(0),
     visitStamp: 0,
     entryPointOrd: -1,
-    topLayer: -1
+    topLayer: -1,
+    workspace: createHNSWWorkspace()
   };
   function clear() {
     resetAdjacency(state.adjacency);
@@ -13046,9 +13051,54 @@ var ESTIMATED_MS_PER_TOMBSTONE = 0.05;
 var ESTIMATED_MS_PER_VECTOR_REBUILD = 0.15;
 var WORKER_BUILD_SIZE_THRESHOLD = 5e3;
 var WORKER_COPY_MIN_VECTORS = 1024;
+var BUILD_CHUNK_SIZE = 100;
+var REBUILD_REMOVED_RATIO = 0.2;
 function liveSize(state) {
   return state.store.size - state.tombstones.size;
 }
+function adoptGraph(state, graph) {
+  if (graph === null && state.hnsw !== null) {
+    state.hnsw.clear();
+  }
+  state.hnsw = graph;
+  state.compactedNodeCount = 0;
+  if (graph === null) return;
+  for (const docId of state.tombstones) {
+    if (graph.has(docId)) {
+      graph.markTombstone(docId);
+    }
+  }
+}
+async function insertIntoGraph(state, graph, docIds, admit, inserted) {
+  let count = 0;
+  for (const docId of docIds) {
+    if (state.disposed) return false;
+    if (!admit(docId)) continue;
+    graph.insertNode(docId);
+    state.buffer.delete(docId);
+    inserted?.(docId);
+    count += 1;
+    if (count % BUILD_CHUNK_SIZE === 0) {
+      await yieldToEventLoop();
+    }
+  }
+  return !state.disposed;
+}
+async function buildGraphFromStore(state) {
+  const graph = createHNSWIndex(state.dimension, state.store, state.hnswConfig, state.sq8 ?? void 0);
+  const completed = await insertIntoGraph(state, graph, allLiveDocIds(state), () => true);
+  if (completed) {
+    adoptGraph(state, graph);
+  }
+}
+function graphNeedsRebuild(state) {
+  const graph = state.hnsw;
+  if (graph === null) return false;
+  const removed = graph.tombstoneCount + state.compactedNodeCount;
+  const held = graph.size + removed;
+  if (held === 0) return false;
+  return removed / held > REBUILD_REMOVED_RATIO;
+}
 function yieldToEventLoop() {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }
@@ -13692,7 +13742,7 @@ function captureCloneSnapshot(state) {
   };
 }
 function scheduleWorkerCopyLoad(state) {
-  if (state.disposed || state.workerCopyLoading) return;
+  if (state.disposed || state.workerCopyLoading || state.building) return;
   if (state.workerCopyHandle !== null) return;
   if (!state.hnsw || state.buffer.size > 0) return;
   if (liveSize(state) < WORKER_COPY_MIN_VECTORS) return;
@@ -13773,7 +13823,7 @@ async function searchViaWorkerCopies(state, query, k, metric, minSimilarity, efS
 }
 
 // src/vector/vector-index/build.ts
-async function tryWorkerBuild(state, liveDocIds, bufferSnapshot) {
+async function tryWorkerBuild(state, liveDocIds) {
   const vectorData = new Float32Array(liveDocIds.length * state.dimension);
   const validDocIds = [];
   let offset = 0;
@@ -13782,6 +13832,7 @@ async function tryWorkerBuild(state, liveDocIds, bufferSnapshot) {
     if (!entry || state.tombstones.has(docId)) continue;
     vectorData.set(entry.vector, offset);
     validDocIds.push(docId);
+    state.buffer.delete(docId);
     offset += state.dimension;
   }
   if (validDocIds.length === 0) return false;
@@ -13793,64 +13844,77 @@ async function tryWorkerBuild(state, liveDocIds, bufferSnapshot) {
   };
   const timeoutMs = Math.max(1e4, liveDocIds.length * 2);
   const outcome = await dispatchWorkerBuild(validDocIds, packedData, state.dimension, resolvedConfig, timeoutMs, true);
-  if (!outcome.ok) return false;
+  if (!outcome.ok || state.disposed) return false;
   const newHnsw = createHNSWIndex(state.dimension, state.store, state.hnswConfig, state.sq8 ?? void 0);
   newHnsw.deserialize(outcome.graph);
-  state.hnsw = newHnsw;
-  for (const docId of state.tombstones) {
-    if (newHnsw.has(docId)) {
-      newHnsw.markTombstone(docId);
-    }
+  adoptGraph(state, newHnsw);
+  return true;
+}
+async function promoteToGraph(state) {
+  const liveDocIds = Array.from(allLiveDocIds(state));
+  if (liveDocIds.length === 0) return;
+  if (state.sq8) {
+    calibrateAndQuantizeAll(state);
   }
-  for (const docId of bufferSnapshot) {
-    state.buffer.delete(docId);
+  if (liveDocIds.length > WORKER_BUILD_SIZE_THRESHOLD) {
+    const built = await tryWorkerBuild(state, liveDocIds);
+    if (built) return;
+  }
+  await buildGraphFromStore(state);
+}
+function quantizeIncoming(state, docId) {
+  const sq8 = state.sq8;
+  if (sq8 === null) return false;
+  if (!sq8.isCalibrated()) {
+    calibrateAndQuantizeAll(state);
+    return false;
+  }
+  const entry = state.store.get(docId);
+  if (entry === void 0) return false;
+  const outsideBounds = sq8.needsRecalibration(entry.vector);
+  sq8.quantize(docId, entry.vector);
+  return outsideBounds;
+}
+async function growGraph(state, graph, bufferSnapshot) {
+  let outsideCalibration = false;
+  const admit = (docId) => {
+    if (state.hnsw !== graph) return false;
+    if (state.tombstones.has(docId) || !state.store.has(docId)) {
+      state.buffer.delete(docId);
+      return false;
+    }
+    return true;
+  };
+  const inserted = (docId) => {
+    if (quantizeIncoming(state, docId)) {
+      outsideCalibration = true;
+    }
+  };
+  await insertIntoGraph(state, graph, bufferSnapshot, admit, inserted);
+  if (outsideCalibration) {
+    recalibrateFromStore(state);
   }
-  return true;
 }
 function triggerBuild(state) {
   if (state.building) return;
   invalidateWorkerCopies(state);
   state.building = true;
-  const liveDocIds = [];
-  for (const [docId] of state.store.entries()) {
-    if (state.tombstones.has(docId)) continue;
-    liveDocIds.push(docId);
-  }
   const bufferSnapshot = new Set(state.buffer);
+  const existingGraph = state.hnsw;
   const buildPromise = (async () => {
     try {
-      if (liveDocIds.length === 0 || state.disposed) return;
-      if (state.sq8) {
-        calibrateAndQuantizeAll(state);
-      }
-      if (liveDocIds.length > WORKER_BUILD_SIZE_THRESHOLD) {
-        const workerResult = await tryWorkerBuild(state, liveDocIds, bufferSnapshot);
-        if (workerResult) return;
-      }
-      const newHnsw = createHNSWIndex(state.dimension, state.store, state.hnswConfig, state.sq8 ?? void 0);
-      const CHUNK_SIZE2 = 100;
-      for (let i = 0; i < liveDocIds.length; i++) {
-        const docId = liveDocIds[i];
-        if (!state.store.has(docId) || state.tombstones.has(docId)) continue;
-        newHnsw.insertNode(docId);
-        if ((i + 1) % CHUNK_SIZE2 === 0) {
-          if (state.disposed) return;
-          await yieldToEventLoop();
-        }
-      }
       if (state.disposed) return;
-      state.hnsw = newHnsw;
-      for (const docId of state.tombstones) {
-        if (newHnsw.has(docId)) {
-          newHnsw.markTombstone(docId);
-        }
-      }
-      for (const docId of bufferSnapshot) {
-        state.buffer.delete(docId);
+      if (existingGraph !== null) {
+        await growGraph(state, existingGraph, bufferSnapshot);
+        return;
       }
+      await promoteToGraph(state);
     } finally {
       state.building = false;
       state.pendingBuild = null;
+      if (state.buffer.size > 0) {
+        scheduleBuild(state);
+      }
     }
   })();
   state.pendingBuild = buildPromise;
@@ -13870,6 +13934,7 @@ function scheduleBuild(state) {
 function compact(state) {
   if (state.tombstones.size === 0) return;
   if (state.hnsw) {
+    state.compactedNodeCount += state.hnsw.tombstoneCount;
     state.hnsw.compactTombstones();
   }
   for (const docId of state.tombstones) {
@@ -13884,43 +13949,48 @@ function compact(state) {
     recalibrateFromStore(state);
   }
 }
-async function optimize(state) {
-  if (state.pendingBuild) {
-    await state.pendingBuild;
-  }
+async function insertMissing(state, graph) {
+  const missingOrReplaced = (docId) => !graph.has(docId) || state.buffer.has(docId);
+  await insertIntoGraph(state, graph, allLiveDocIds(state), missingOrReplaced);
+}
+async function foldIntoGraph(state) {
+  const rebuildNeeded = graphNeedsRebuild(state);
+  const compactRecalibrates = state.tombstones.size > 0 && state.sq8?.isCalibrated() === true;
   compact(state);
-  const live = liveSize(state);
-  if (live === 0) {
-    if (state.hnsw) {
-      state.hnsw.clear();
-      state.hnsw = null;
-    }
+  if (liveSize(state) === 0) {
+    adoptGraph(state, null);
     state.buffer.clear();
     if (state.sq8) {
       state.sq8.clear();
     }
     return;
   }
-  if (state.sq8) {
-    calibrateAndQuantizeAll(state);
+  const graph = state.hnsw;
+  if (graph === null || rebuildNeeded) {
+    await buildGraphFromStore(state);
+  } else {
+    await insertMissing(state, graph);
   }
-  const newHnsw = createHNSWIndex(state.dimension, state.store, state.hnswConfig, state.sq8 ?? void 0);
-  const liveDocIds = [];
-  for (const [docId] of state.store.entries()) {
-    if (state.tombstones.has(docId)) continue;
-    liveDocIds.push(docId);
+  if (state.sq8 && state.store.size > 0 && !compactRecalibrates) {
+    recalibrateFromStore(state);
   }
-  const CHUNK_SIZE2 = 100;
-  for (let i = 0; i < liveDocIds.length; i++) {
-    newHnsw.insertNode(liveDocIds[i]);
-    if ((i + 1) % CHUNK_SIZE2 === 0) {
-      await yieldToEventLoop();
-    }
+}
+async function optimize(state) {
+  while (state.pendingBuild) {
+    await state.pendingBuild;
   }
-  state.hnsw = newHnsw;
-  state.buffer.clear();
-  if (state.sq8 && state.store.size > 0) {
-    recalibrateFromStore(state);
+  if (state.disposed) return;
+  state.building = true;
+  const work = foldIntoGraph(state);
+  state.pendingBuild = work;
+  try {
+    await work;
+  } finally {
+    state.building = false;
+    state.pendingBuild = null;
+    if (state.buffer.size > 0) {
+      scheduleBuild(state);
+    }
   }
 }
 function maintenanceStatus(state) {
@@ -13928,12 +13998,13 @@ function maintenanceStatus(state) {
   const tombstoneRatio = storeSize > 0 ? state.tombstones.size / storeSize : 0;
   const graphCount = state.hnsw ? 1 : 0;
   const estimatedCompactMs = Math.round(state.tombstones.size * ESTIMATED_MS_PER_TOMBSTONE * state.dimensionScale);
-  const estimatedOptimizeMs = Math.round(storeSize * ESTIMATED_MS_PER_VECTOR_REBUILD * state.dimensionScale);
+  const optimizeVectorCount = state.hnsw === null || graphNeedsRebuild(state) ? storeSize : state.buffer.size;
+  const estimatedOptimizeMs = Math.round(optimizeVectorCount * ESTIMATED_MS_PER_VECTOR_REBUILD * state.dimensionScale);
   return {
     tombstoneRatio,
     graphCount,
     bufferSize: state.buffer.size,
-    building: state.building,
+    building: state.building || state.buildScheduled,
     estimatedCompactMs,
     estimatedOptimizeMs
   };
@@ -14024,10 +14095,7 @@ function deserialize(state, payload) {
   state.store.clear();
   state.tombstones.clear();
   state.buffer.clear();
-  if (state.hnsw) {
-    state.hnsw.clear();
-    state.hnsw = null;
-  }
+  adoptGraph(state, null);
   if (state.sq8) {
     state.sq8.clear();
   }
@@ -14052,7 +14120,7 @@ function deserialize(state, payload) {
       state.sq8 ?? void 0
     );
     restoredHnsw.deserialize(graphData);
-    state.hnsw = restoredHnsw;
+    adoptGraph(state, restoredHnsw);
     for (let i = 1; i < payload.graphs.length; i++) {
       const additionalGraph = payload.graphs[i];
       for (const [nodeDocId] of additionalGraph.nodes) {
@@ -14068,8 +14136,7 @@ function deserialize(state, payload) {
       }
     }
     if (state.buffer.size > restoredHnsw.size) {
-      state.hnsw.clear();
-      state.hnsw = null;
+      adoptGraph(state, null);
       state.buffer.clear();
       for (const [docId] of state.store.entries()) {
         if (state.tombstones.has(docId)) continue;
@@ -14084,6 +14151,87 @@ function deserialize(state, payload) {
   }
 }
 
+// src/core/heap.ts
+function createMaxHeap(compare) {
+  return createHeap2((a, b) => compare(b, a));
+}
+function createBoundedMaxHeap(compare, capacity) {
+  const heap = createMaxHeap(compare);
+  const innerPush = heap.push;
+  return {
+    push(item) {
+      if (heap.size < capacity) {
+        innerPush(item);
+        return;
+      }
+      const top = heap.peek();
+      if (top !== void 0 && compare(item, top) < 0) {
+        heap.pop();
+        innerPush(item);
+      }
+    },
+    pop: heap.pop,
+    peek: heap.peek,
+    get size() {
+      return heap.size;
+    },
+    toSortedArray: heap.toSortedArray
+  };
+}
+function createHeap2(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 siftDown2(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;
+        siftDown2(0);
+      }
+      return top;
+    },
+    peek() {
+      return items[0];
+    },
+    get size() {
+      return items.length;
+    },
+    toSortedArray() {
+      return [...items].sort(compare);
+    }
+  };
+}
+
 // src/vector/vector-index/search.ts
 function* bufferCandidates(state, filter) {
   for (const docId of state.buffer) {
@@ -14234,6 +14382,7 @@ function createVectorIndex(fieldName, dimension, config) {
     buffer: /* @__PURE__ */ new Set(),
     sq8: quantizationMode === "sq8" ? createScalarQuantizer(dimension, store) : null,
     hnsw: null,
+    compactedNodeCount: 0,
     building: false,
     buildScheduled: false,
     pendingBuild: null,