verso-db 0.1.5 → 0.2.0

package/src/HNSWIndex.ts

@@ -1,2894 +0,0 @@
-// Bun-native file operations - no fs import needed
-import { dotProductFast, l2SquaredFast, normalizeInPlace } from './backends/JsDistanceBackend';
-import { BinaryHeap } from './BinaryHeap';
-import { MaxBinaryHeap } from './MaxBinaryHeap';
-import { ScalarQuantizer, l2SquaredInt8, cosineDistanceInt8, dotProductInt8 } from './quantization/ScalarQuantizer';
-import { deltaEncodeNeighbors, deltaDecodeNeighbors } from './encoding/DeltaEncoder';
-import { VectorDBError } from './errors';
-export type DistanceMetric = 'cosine' | 'euclidean' | 'dot_product';
-
-export interface Node {
-  id: number;
-  level: number;
-  vector: Float32Array;
-  neighbors: number[][]; // neighbors[layer][neighbor_index] = neighbor_id
-}
-
-export class HNSWIndex {
-  // 0xFFFFFFFF is reserved as "missing result" sentinel in batch flat output.
-  private static readonly MISSING_ID_SENTINEL = 0xFFFFFFFF;
-  private static readonly MAX_NODE_ID = HNSWIndex.MISSING_ID_SENTINEL - 1;
-
-  private M: number; // Max number of connections per node per level
-  private M0: number; // Max number of connections for level 0 (typically M * 2)
-  private efConstruction: number; // Size of candidate list during construction
-  private levelMult: number; // Probability multiplier for level selection
-  private maxLevel: number;
-  private entryPointId: number;
-  // OPTIMIZATION: Use array instead of Map for O(1) indexed access (3-5x faster than Map.get)
-  private nodes: (Node | undefined)[];
-  private nodeCount: number = 0;
-  private nextAutoId: number = 0;
-  private dimension: number;
-  private metric: DistanceMetric;
-  private maxLayers: number;
-
-  // OPTIMIZATION: Flat vector storage for cache-friendly batch distance calculations
-  // All vectors stored contiguously: [v0_d0, v0_d1, ..., v1_d0, v1_d1, ...]
-  private flatVectors: Float32Array;
-  private flatVectorsCapacity: number = 0;
-
-  // TypedArray for fast visited tracking - much faster than Set<number>
-  // Uint16Array allows generation wrap at 65000 instead of 250, reducing fill(0) frequency ~260x
-  private visitedArray: Uint16Array;
-  private visitedArraySize: number;
-  private visitedGeneration: number = 0; // Increment to "clear" without filling
-  // Reusable heaps for searchLayer - avoids allocation on every call
-  private candidatesHeap: BinaryHeap;
-  private resultsHeap: MaxBinaryHeap;
-  private selectionHeap: BinaryHeap; // Reusable heap for selectNeighbors
-  private heapCapacity: number;
-  // Pre-normalization optimization for cosine distance
-  private vectorsAreNormalized: boolean = false;
-  // Cached distance function to avoid switch overhead
-  private distanceFn: (a: Float32Array, b: Float32Array) => number;
-
-  // Quantization support for 3-4x faster search with Int8
-  private scalarQuantizer: ScalarQuantizer | null = null;
-  // OPTIMIZATION: Use array instead of Map for int8 vectors too
-  private int8Vectors: (Int8Array | undefined)[] = [];
-  private quantizationEnabled: boolean = false;
-
-  // OPTIMIZATION: Contiguous Int8 storage for cache-friendly batch distance calculations
-  // Layout: [v0_d0...v0_dn, v1_d0...v1_dn, ...], offset: nodeId * dim
-  private flatInt8Vectors: Int8Array | null = null;
-  private flatInt8VectorsCapacity: number = 0;
-  // Reusable Int8 query buffer for quantized search — avoids allocation per query
-  private queryInt8Buffer: Int8Array | null = null;
-
-  // Lazy loading support (v3+ format)
-  private lazyLoadEnabled: boolean = false;
-  private vectorOffsets: Map<number, number> = new Map(); // nodeId -> byte offset in file
-  private vectorBuffer: ArrayBuffer | null = null; // Cached buffer for lazy loading
-  private vectorsLoaded: Set<number> = new Set(); // Track which vectors are loaded
-
-  // Reusable query buffer for search operations - avoids allocation per query
-  // Profiling showed 17% improvement with buffer reuse (99.5ms → 82.7ms for 1000 queries)
-  private queryNormBuffer: Float32Array;
-
-  // Bulk construction optimization - O(1) neighbor lookup during construction
-  // Uses parallel Set<number>[] alongside neighbor arrays for fast membership testing
-  // Memory is released after construction completes
-  private neighborSets: Map<number, Set<number>[]> = new Map();
-
-  // Construction-time quantization: use int8 search at layer 0 during bulk insert
-  // Set by addPointsBulkSync when useInt8Construction option is enabled
-  private useInt8Construction: boolean = false;
-  private constructionMode: boolean = false;
-
-  // Adaptive efSearch calibration stats
-  private calibrationStats: {
-    meanEntryDist: number;
-    stdEntryDist: number;
-  } | null = null;
-
-  constructor(dimension: number, metric: DistanceMetric = 'cosine', M = 24, efConstruction = 200) {
-    if (dimension <= 0 || !Number.isInteger(dimension)) {
-      throw new VectorDBError(`Invalid dimension: must be a positive integer, got ${dimension}`, 'VALIDATION_ERROR');
-    }
-    if (M <= 0 || !Number.isInteger(M)) {
-      throw new VectorDBError(`Invalid M parameter: must be a positive integer, got ${M}`, 'VALIDATION_ERROR');
-    }
-    if (efConstruction <= 0 || !Number.isInteger(efConstruction)) {
-      throw new VectorDBError(`Invalid efConstruction parameter: must be a positive integer, got ${efConstruction}`, 'VALIDATION_ERROR');
-    }
-    this.dimension = dimension;
-    this.metric = metric;
-    this.M = M;
-    this.M0 = M * 2;
-    this.efConstruction = efConstruction;
-    this.levelMult = 1 / Math.log(M);
-    this.maxLevel = -1;
-    this.entryPointId = -1;
-    // OPTIMIZATION: Pre-allocate node array with initial capacity
-    const initialCapacity = 10000;
-    this.nodes = new Array(initialCapacity);
-    this.nodeCount = 0;
-    this.nextAutoId = 0;
-    // OPTIMIZATION: Pre-allocate flat vector storage
-    this.flatVectorsCapacity = initialCapacity;
-    this.flatVectors = new Float32Array(initialCapacity * dimension);
-    this.maxLayers = 32; // Maximum possible layers to pre-allocate
-    // Initialize visited tracking with TypedArray for speed
-    // Start with reasonable size, will grow as needed
-    this.visitedArraySize = 10000;
-    this.visitedArray = new Uint16Array(this.visitedArraySize);
-    this.visitedGeneration = 1;
-
-    // Pre-allocate searchLayer heaps - sized for typical ef values
-    // Will be resized if needed for larger ef
-    this.heapCapacity = Math.max(efConstruction * 2, 500);
-    this.candidatesHeap = new BinaryHeap(this.heapCapacity);
-    this.resultsHeap = new MaxBinaryHeap(this.heapCapacity);
-    // Selection heap sized for M0 (largest neighbor list size)
-    this.selectionHeap = new BinaryHeap(Math.max(M * 2, efConstruction));
-
-    // For cosine metric, we pre-normalize vectors for faster distance computation
-    this.vectorsAreNormalized = (metric === 'cosine');
-
-    // Pre-allocate query normalization buffer - reused across all searches
-    this.queryNormBuffer = new Float32Array(dimension);
-
-    // Initialize cached distance function based on metric
-    // This avoids switch statement overhead on every distance calculation
-    if (metric === 'cosine') {
-      // For cosine with pre-normalized vectors, just compute 1 - dot product
-      this.distanceFn = (a: Float32Array, b: Float32Array): number => {
-        const dot = dotProductFast(a, b);
-        const distance = 1 - dot;
-        return distance < 1e-10 ? 0 : distance;
-      };
-    } else if (metric === 'euclidean') {
-      this.distanceFn = (a: Float32Array, b: Float32Array): number => {
-        return Math.sqrt(l2SquaredFast(a, b));
-      };
-    } else if (metric === 'dot_product') {
-      this.distanceFn = (a: Float32Array, b: Float32Array): number => {
-        return -dotProductFast(a, b);
-      };
-    } else {
-      throw new VectorDBError(`Unsupported metric: ${metric}`, 'VALIDATION_ERROR');
-    }
-  }
-
-  // ============================================
-  // OPTIMIZATION: Capacity and flat storage helpers
-  // ============================================
-
-  /**
-   * Ensure node array and flat vector storage have enough capacity
-   */
-  private ensureCapacity(minCapacity: number): void {
-    // Grow node array if needed
-    if (minCapacity > this.nodes.length) {
-      const newCapacity = Math.max(this.nodes.length * 2, minCapacity);
-      const newNodes = new Array(newCapacity);
-      for (let i = 0; i < this.nodeCount; i++) {
-        newNodes[i] = this.nodes[i];
-      }
-      this.nodes = newNodes;
-    }
-
-    // Grow flat vector storage if needed
-    if (minCapacity > this.flatVectorsCapacity) {
-      const newCapacity = Math.max(this.flatVectorsCapacity * 2, minCapacity);
-      const newFlatVectors = new Float32Array(newCapacity * this.dimension);
-      newFlatVectors.set(this.flatVectors);
-      this.flatVectors = newFlatVectors;
-      this.flatVectorsCapacity = newCapacity;
-    }
-
-    // Grow contiguous Int8 storage if quantization is enabled
-    if (this.quantizationEnabled && this.flatInt8Vectors !== null && minCapacity > this.flatInt8VectorsCapacity) {
-      const newCapacity = Math.max(this.flatInt8VectorsCapacity * 2, minCapacity);
-      const newFlatInt8 = new Int8Array(newCapacity * this.dimension);
-      newFlatInt8.set(this.flatInt8Vectors);
-      this.flatInt8Vectors = newFlatInt8;
-      this.flatInt8VectorsCapacity = newCapacity;
-    }
-  }
-
-  /**
-   * Set vector in flat storage
-   */
-  private setFlatVector(nodeId: number, vector: Float32Array): void {
-    const offset = nodeId * this.dimension;
-    this.flatVectors.set(vector, offset);
-  }
-
-  /**
-   * Set node by ID
-   */
-  private setNode(node: Node): void {
-    const id = node.id;
-    this.ensureCapacity(id + 1);
-    this.nodes[id] = node;
-    // Store vector in flat storage too
-    this.setFlatVector(id, node.vector);
-    // Track node count
-    if (id >= this.nodeCount) {
-      this.nodeCount = id + 1;
-    }
-    if (id >= this.nextAutoId) {
-      this.nextAutoId = id + 1;
-    }
-  }
-
-  // OPTIMIZATION: Reusable arrays for batch distance calculation
-  private batchNeighborIds: number[] = [];
-  private batchDistances: number[] = [];
-
-  /**
-   * OPTIMIZATION: Batch distance calculation for better cache locality
-   * Computes distances from query to multiple neighbors at once
-   * Uses flat vector storage for contiguous memory access
-   */
-  private calculateDistancesBatch(
-    query: Float32Array,
-    neighborIds: number[],
-    outDistances: number[],
-    count?: number
-  ): void {
-    const dim = this.dimension;
-    const flatVectors = this.flatVectors;
-    const len = count ?? neighborIds.length;
-
-    for (let i = 0; i < len; i++) {
-      const neighborId = neighborIds[i];
-      const offset = neighborId * dim;
-
-      // Inline distance calculation for better performance
-      // This avoids function call overhead per neighbor
-      if (this.metric === 'cosine') {
-        // Pre-normalized vectors: distance = 1 - dot(a, b)
-        let sum0 = 0, sum1 = 0, sum2 = 0, sum3 = 0;
-        let sum4 = 0, sum5 = 0, sum6 = 0, sum7 = 0;
-        let d = 0;
-        const limit8 = dim - 7;
-
-        for (; d < limit8; d += 8) {
-          sum0 += flatVectors[offset + d] * query[d];
-          sum1 += flatVectors[offset + d + 1] * query[d + 1];
-          sum2 += flatVectors[offset + d + 2] * query[d + 2];
-          sum3 += flatVectors[offset + d + 3] * query[d + 3];
-          sum4 += flatVectors[offset + d + 4] * query[d + 4];
-          sum5 += flatVectors[offset + d + 5] * query[d + 5];
-          sum6 += flatVectors[offset + d + 6] * query[d + 6];
-          sum7 += flatVectors[offset + d + 7] * query[d + 7];
-        }
-        for (; d < dim; d++) {
-          sum0 += flatVectors[offset + d] * query[d];
-        }
-
-        const dot = sum0 + sum1 + sum2 + sum3 + sum4 + sum5 + sum6 + sum7;
-        const dist = 1 - dot;
-        outDistances[i] = dist < 1e-10 ? 0 : dist;
-      } else if (this.metric === 'euclidean') {
-        // L2 squared distance
-        let sum0 = 0, sum1 = 0, sum2 = 0, sum3 = 0;
-        let sum4 = 0, sum5 = 0, sum6 = 0, sum7 = 0;
-        let d = 0;
-        const limit8 = dim - 7;
-
-        for (; d < limit8; d += 8) {
-          const d0 = flatVectors[offset + d] - query[d];
-          const d1 = flatVectors[offset + d + 1] - query[d + 1];
-          const d2 = flatVectors[offset + d + 2] - query[d + 2];
-          const d3 = flatVectors[offset + d + 3] - query[d + 3];
-          const d4 = flatVectors[offset + d + 4] - query[d + 4];
-          const d5 = flatVectors[offset + d + 5] - query[d + 5];
-          const d6 = flatVectors[offset + d + 6] - query[d + 6];
-          const d7 = flatVectors[offset + d + 7] - query[d + 7];
-          sum0 += d0 * d0;
-          sum1 += d1 * d1;
-          sum2 += d2 * d2;
-          sum3 += d3 * d3;
-          sum4 += d4 * d4;
-          sum5 += d5 * d5;
-          sum6 += d6 * d6;
-          sum7 += d7 * d7;
-        }
-        for (; d < dim; d++) {
-          const diff = flatVectors[offset + d] - query[d];
-          sum0 += diff * diff;
-        }
-
-        outDistances[i] = Math.sqrt(sum0 + sum1 + sum2 + sum3 + sum4 + sum5 + sum6 + sum7);
-      } else {
-        // dot_product: negative dot product
-        let sum0 = 0, sum1 = 0, sum2 = 0, sum3 = 0;
-        let sum4 = 0, sum5 = 0, sum6 = 0, sum7 = 0;
-        let d = 0;
-        const limit8 = dim - 7;
-
-        for (; d < limit8; d += 8) {
-          sum0 += flatVectors[offset + d] * query[d];
-          sum1 += flatVectors[offset + d + 1] * query[d + 1];
-          sum2 += flatVectors[offset + d + 2] * query[d + 2];
-          sum3 += flatVectors[offset + d + 3] * query[d + 3];
-          sum4 += flatVectors[offset + d + 4] * query[d + 4];
-          sum5 += flatVectors[offset + d + 5] * query[d + 5];
-          sum6 += flatVectors[offset + d + 6] * query[d + 6];
-          sum7 += flatVectors[offset + d + 7] * query[d + 7];
-        }
-        for (; d < dim; d++) {
-          sum0 += flatVectors[offset + d] * query[d];
-        }
-
-        outDistances[i] = -(sum0 + sum1 + sum2 + sum3 + sum4 + sum5 + sum6 + sum7);
-      }
-    }
-  }
-
-  /**
-   * OPTIMIZATION: Batch Int8 distance calculation for cache-friendly quantized search.
-   * Mirrors calculateDistancesBatch but operates on contiguous flatInt8Vectors.
-   *
-   * For cosine (pre-normalized) and dot_product: uses -dotProductInt8 (1 sum, 8-wide)
-   * For euclidean: uses l2Squared on int8 (8-wide unrolled)
-   */
-  private calculateDistancesBatchInt8(
-    queryInt8: Int8Array,
-    neighborIds: number[],
-    outDistances: number[],
-    count: number
-  ): void {
-    const dim = this.dimension;
-    const flatInt8 = this.flatInt8Vectors!;
-
-    if (this.metric === 'euclidean') {
-      // L2 squared distance on int8
-      for (let i = 0; i < count; i++) {
-        const offset = neighborIds[i] * dim;
-        let sum0 = 0, sum1 = 0, sum2 = 0, sum3 = 0;
-        let sum4 = 0, sum5 = 0, sum6 = 0, sum7 = 0;
-        let d = 0;
-        const limit8 = dim - 7;
-
-        for (; d < limit8; d += 8) {
-          const d0 = queryInt8[d] - flatInt8[offset + d];
-          const d1 = queryInt8[d + 1] - flatInt8[offset + d + 1];
-          const d2 = queryInt8[d + 2] - flatInt8[offset + d + 2];
-          const d3 = queryInt8[d + 3] - flatInt8[offset + d + 3];
-          const d4 = queryInt8[d + 4] - flatInt8[offset + d + 4];
-          const d5 = queryInt8[d + 5] - flatInt8[offset + d + 5];
-          const d6 = queryInt8[d + 6] - flatInt8[offset + d + 6];
-          const d7 = queryInt8[d + 7] - flatInt8[offset + d + 7];
-          sum0 += d0 * d0;
-          sum1 += d1 * d1;
-          sum2 += d2 * d2;
-          sum3 += d3 * d3;
-          sum4 += d4 * d4;
-          sum5 += d5 * d5;
-          sum6 += d6 * d6;
-          sum7 += d7 * d7;
-        }
-        for (; d < dim; d++) {
-          const diff = queryInt8[d] - flatInt8[offset + d];
-          sum0 += diff * diff;
-        }
-
-        outDistances[i] = Math.sqrt(sum0 + sum1 + sum2 + sum3 + sum4 + sum5 + sum6 + sum7);
-      }
-    } else {
-      // cosine (pre-normalized) and dot_product both use -dotProduct as distance
-      // cosine: vectors are pre-normalized, so distance ≈ -dot (higher dot = closer)
-      // dot_product: distance = -dot (standard convention)
-      for (let i = 0; i < count; i++) {
-        const offset = neighborIds[i] * dim;
-        let sum0 = 0, sum1 = 0, sum2 = 0, sum3 = 0;
-        let sum4 = 0, sum5 = 0, sum6 = 0, sum7 = 0;
-        let d = 0;
-        const limit8 = dim - 7;
-
-        for (; d < limit8; d += 8) {
-          sum0 += queryInt8[d] * flatInt8[offset + d];
-          sum1 += queryInt8[d + 1] * flatInt8[offset + d + 1];
-          sum2 += queryInt8[d + 2] * flatInt8[offset + d + 2];
-          sum3 += queryInt8[d + 3] * flatInt8[offset + d + 3];
-          sum4 += queryInt8[d + 4] * flatInt8[offset + d + 4];
-          sum5 += queryInt8[d + 5] * flatInt8[offset + d + 5];
-          sum6 += queryInt8[d + 6] * flatInt8[offset + d + 6];
-          sum7 += queryInt8[d + 7] * flatInt8[offset + d + 7];
-        }
-        for (; d < dim; d++) {
-          sum0 += queryInt8[d] * flatInt8[offset + d];
-        }
-
-        outDistances[i] = -(sum0 + sum1 + sum2 + sum3 + sum4 + sum5 + sum6 + sum7);
-      }
-    }
-  }
-
-  /**
-   * Check if a node has been visited in the current search.
-   * Uses generation counting to avoid clearing the array.
-   */
-  private isVisited(id: number): boolean {
-    if (id >= this.visitedArraySize) {
-      return false; // Not in array = not visited
-    }
-    return this.visitedArray[id] === this.visitedGeneration;
-  }
-
-  /**
-   * Mark a node as visited in the current search.
-   * Grows the array if needed.
-   */
-  private markVisited(id: number): void {
-    if (id >= this.visitedArraySize) {
-      // Grow array to accommodate larger IDs
-      const newSize = Math.max(this.visitedArraySize * 2, id + 1000);
-      const newArray = new Uint16Array(newSize);
-      newArray.set(this.visitedArray);
-      this.visitedArray = newArray;
-      this.visitedArraySize = newSize;
-    }
-    this.visitedArray[id] = this.visitedGeneration;
-  }
-
-  /**
-   * Clear all visited markers by incrementing the generation.
-   * Much faster than filling the array with zeros.
-   */
-  private clearVisited(): void {
-    this.visitedGeneration++;
-    // Wrap around to avoid overflow (65535 is max for Uint16)
-    if (this.visitedGeneration > 65000) {
-      this.visitedArray.fill(0);
-      this.visitedGeneration = 1;
-    }
-  }
-
-  private normalizeVector(vector: Float32Array): Float32Array {
-    normalizeInPlace(vector);
-    return vector;
-  }
-
-  private selectLevel(): number {
-    const r = Math.random() || Number.MIN_VALUE;
-    const level = Math.floor(-Math.log(r) * this.levelMult);
-    return Math.max(0, Math.min(level, this.maxLayers - 1));
-  }
-
-  /**
-   * Calculate distance between two vectors using the configured metric.
-   * Uses cached function pointer to avoid switch overhead.
-   */
-  calculateDistance(a: Float32Array, b: Float32Array): number {
-    return this.distanceFn(a, b);
-  }
-
-  private validateQueryVector(query: Float32Array, context: string = 'Query'): void {
-    if (query.length !== this.dimension) {
-      throw new VectorDBError(`${context} dimension ${query.length} does not match expected ${this.dimension}`, 'DIMENSION_MISMATCH');
-    }
-    for (let i = 0; i < query.length; i++) {
-      if (!Number.isFinite(query[i])) {
-        throw new VectorDBError(`${context} contains non-finite value at index ${i}: ${query[i]}`, 'VALIDATION_ERROR');
-      }
-    }
-  }
-
-  private validateSearchParams(k: number, efSearch?: number): void {
-    if (!Number.isInteger(k) || k <= 0) {
-      throw new VectorDBError(`k must be a positive integer, got ${k}`, 'VALIDATION_ERROR');
-    }
-    if (efSearch !== undefined && (!Number.isInteger(efSearch) || efSearch <= 0)) {
-      throw new VectorDBError(`efSearch must be a positive integer, got ${efSearch}`, 'VALIDATION_ERROR');
-    }
-  }
-
-  private validateNodeId(id: number): void {
-    if (!Number.isInteger(id) || id < 0) {
-      throw new VectorDBError(`Invalid node ID ${id}: IDs must be non-negative integers`, 'VALIDATION_ERROR');
-    }
-    if (id > HNSWIndex.MAX_NODE_ID) {
-      throw new VectorDBError(
-        `Invalid node ID ${id}: maximum supported ID is ${HNSWIndex.MAX_NODE_ID} (0x${HNSWIndex.MAX_NODE_ID.toString(16)})`,
-        'VALIDATION_ERROR'
-      );
-    }
-  }
-
-  /**
-   * Get a node's vector, loading it if necessary (for lazy loading support)
-   */
-  private getNodeVector(nodeId: number): Float32Array | null {
-    const node = this.nodes[nodeId];
-    if (!node) return null;
-
-    if (this.lazyLoadEnabled && !this.vectorsLoaded.has(nodeId)) {
-      this.loadVector(nodeId);
-    }
-
-    return node.vector;
-  }
-
-  private getLayerMaxConnections(layer: number): number {
-    return layer === 0 ? this.M0 : this.M;
-  }
-
-  private selectNeighbors(currentId: number, candidates: Array<{ id: number; distance: number }>, layer: number): number[] {
-    const maxConnections = this.getLayerMaxConnections(layer);
-
-    // Reuse selection heap - clear and ensure capacity
-    this.selectionHeap.clear();
-
-    // Add all candidates to the heap (skip self-reference)
-    for (const candidate of candidates) {
-      if (candidate.id !== currentId) {
-        this.selectionHeap.push(candidate.id, candidate.distance);
-      }
-    }
-
-    // Extract the best neighbors (closest first)
-    // Pre-allocate array for expected size
-    const selected = new Array<number>(Math.min(maxConnections, this.selectionHeap.size()));
-    let idx = 0;
-
-    // Extract up to maxConnections elements from heap
-    // Candidates from searchLayer are already unique (visited tracking)
-    while (idx < maxConnections && !this.selectionHeap.isEmpty()) {
-      const id = this.selectionHeap.pop();
-      if (id !== -1) {
-        selected[idx++] = id;
-      }
-    }
-
-    // Trim if needed
-    if (idx < selected.length) {
-      selected.length = idx;
-    }
-
-    return selected;
-  }
-
-  private addBidirectionalConnection(fromId: number, toId: number, level: number): void {
-    const fromNode = this.nodes[fromId];
-    const toNode = this.nodes[toId];
-
-    if (!fromNode || !toNode) return;
-
-    // Ensure neighbor arrays exist
-    if (!fromNode.neighbors[level]) {
-      fromNode.neighbors[level] = [];
-    }
-    if (!toNode.neighbors[level]) {
-      toNode.neighbors[level] = [];
-    }
-
-    const maxConnections = this.getLayerMaxConnections(level);
-
-    if (this.constructionMode) {
-      // O(1) lookup using Sets during bulk construction
-      let fromSets = this.neighborSets.get(fromId);
-      if (!fromSets) {
-        fromSets = [];
-        this.neighborSets.set(fromId, fromSets);
-      }
-      if (!fromSets[level]) {
-        fromSets[level] = new Set(fromNode.neighbors[level]);
-      }
-
-      let toSets = this.neighborSets.get(toId);
-      if (!toSets) {
-        toSets = [];
-        this.neighborSets.set(toId, toSets);
-      }
-      if (!toSets[level]) {
-        toSets[level] = new Set(toNode.neighbors[level]);
-      }
-
-      // O(1) membership test with Set.has()
-      if (!fromSets[level].has(toId)) {
-        fromSets[level].add(toId);
-        fromNode.neighbors[level].push(toId);
-      }
-
-      if (!toSets[level].has(fromId)) {
-        toSets[level].add(fromId);
-        toNode.neighbors[level].push(fromId);
-      }
-
-      // Prune reverse connection if it exceeds maxConnections
-      if (toNode.neighbors[level].length > maxConnections) {
-        this.pruneConnections(toId, toNode, level, maxConnections, toSets[level]);
-      }
-    } else {
-      // Original O(M) lookup for single inserts (fallback)
-      if (!fromNode.neighbors[level].includes(toId)) {
-        fromNode.neighbors[level].push(toId);
-      }
-      if (!toNode.neighbors[level].includes(fromId)) {
-        toNode.neighbors[level].push(fromId);
-      }
-
-      // Prune reverse connection if it exceeds maxConnections
-      if (toNode.neighbors[level].length > maxConnections) {
-        this.pruneConnections(toId, toNode, level, maxConnections);
-      }
-    }
-  }
-
-  /**
-   * Prune a node's neighbor list to maxConnections by removing the most distant neighbor.
-   */
-  private pruneConnections(_nodeId: number, node: Node, level: number, _maxConnections: number, neighborSet?: Set<number>): void {
-    const neighbors = node.neighbors[level];
-    const nodeVector = node.vector;
-
-    // Find the most distant neighbor
-    let worstIdx = 0;
-    let worstDist = -Infinity;
-    for (let i = 0; i < neighbors.length; i++) {
-      const nVector = this.nodes[neighbors[i]]?.vector;
-      if (!nVector) {
-        // Missing node — remove it
-        worstIdx = i;
-        worstDist = Infinity;
-        break;
-      }
-      const dist = this.distanceFn(nodeVector, nVector);
-      if (dist > worstDist) {
-        worstDist = dist;
-        worstIdx = i;
-      }
-    }
-
-    const removedId = neighbors[worstIdx];
-    // Swap-remove for O(1)
-    neighbors[worstIdx] = neighbors[neighbors.length - 1];
-    neighbors.pop();
-
-    if (neighborSet) {
-      neighborSet.delete(removedId);
-    }
-  }
-
-  /**
-   * Ensure heap capacity is sufficient for the given ef value.
-   * Resizes heaps if needed.
-   */
-  private ensureHeapCapacity(ef: number): void {
-    const requiredCapacity = Math.max(ef * 2, 100);
-    if (requiredCapacity > this.heapCapacity) {
-      this.heapCapacity = requiredCapacity;
-      this.candidatesHeap = new BinaryHeap(this.heapCapacity);
-      this.resultsHeap = new MaxBinaryHeap(this.heapCapacity);
-    }
-  }
-
-  /**
-   * Search a layer using the standard two-heap HNSW algorithm.
-   *
-   * Uses two heaps:
-   * - candidatesHeap (min-heap): Tracks nodes to explore, prioritizing closest
-   * - resultsHeap (max-heap): Tracks top-ef results, allowing O(log n) eviction of furthest
-   *
-   * Termination: Stops when closest unvisited candidate is farther than furthest result.
-   */
-  private searchLayer(
-    query: Float32Array,
-    nearest: { id: number; distance: number },
-    layer: number,
-    ef: number
-  ): Array<{ id: number; distance: number }> {
-    // Clear visited tracking
-    this.clearVisited();
-
-    // Ensure heaps are large enough, then clear and reuse
-    this.ensureHeapCapacity(ef);
-    this.candidatesHeap.clear();
-    this.resultsHeap.clear();
-
-    // Initialize with entry point
-    this.markVisited(nearest.id);
-    this.candidatesHeap.push(nearest.id, nearest.distance);
-    this.resultsHeap.push(nearest.id, nearest.distance);
-
-    // Cache the furthest result distance - only changes when resultsHeap is modified
-    let furthestResultDist = nearest.distance;
-
-    // OPTIMIZATION: Pre-allocate batch arrays for distance calculation
-    // Reuse across iterations to avoid allocation
-    const batchIds = this.batchNeighborIds;
-    const batchDists = this.batchDistances;
-
-    while (!this.candidatesHeap.isEmpty()) {
-      // Get closest unexplored candidate
-      const closestCandidateDist = this.candidatesHeap.peekValue();
-      const closestCandidateId = this.candidatesHeap.pop();
-
-      if (closestCandidateId === -1) continue;
-
-      // TERMINATION: Stop if closest candidate is farther than worst result
-      if (this.resultsHeap.size() >= ef && closestCandidateDist > furthestResultDist) {
-        break;
-      }
-
-      const node = this.nodes[closestCandidateId];
-      if (!node) continue;
-
-      const neighbors = node.neighbors[layer] || [];
-
-      // Use batch distance calculation for non-lazy indices (better cache locality)
-      // Fall back to one-by-one for lazy-loaded indices (vectors may not be in flatVectors)
-      if (!this.lazyLoadEnabled) {
-        // OPTIMIZATION: Collect unvisited neighbors and compute distances in batch
-        let batchCount = 0;
-        for (let i = 0; i < neighbors.length; i++) {
-          const neighborId = neighbors[i];
-          if (!this.nodes[neighborId]) continue;
-          if (!this.isVisited(neighborId)) {
-            this.markVisited(neighborId);
-            batchIds[batchCount] = neighborId;
-            batchCount++;
-          }
-        }
-
-        // Calculate all distances at once (better cache utilization)
-        if (batchCount > 0) {
-          // Ensure batch arrays are large enough
-          if (batchDists.length < batchCount) {
-            this.batchDistances.length = batchCount;
-          }
-
-          this.calculateDistancesBatch(query, batchIds, batchDists, batchCount);
-
-          // Process batch results
-          for (let i = 0; i < batchCount; i++) {
-            const neighborId = batchIds[i];
-            const distance = batchDists[i];
-
-            // Add to results if it's good enough
-            if (this.resultsHeap.size() < ef || distance < furthestResultDist) {
-              this.candidatesHeap.push(neighborId, distance);
-              this.resultsHeap.push(neighborId, distance);
-
-              // Maintain max size of ef and update cached furthest distance
-              if (this.resultsHeap.size() > ef) {
-                this.resultsHeap.pop(); // Remove furthest (O(log n))
-              }
-              furthestResultDist = this.resultsHeap.peekValue();
-            }
-          }
-        }
-      } else {
-        // Original one-by-one for lazy-loaded indices
-        for (const neighborId of neighbors) {
-          if (this.isVisited(neighborId)) continue;
-          this.markVisited(neighborId);
-
-          const neighborVector = this.getNodeVector(neighborId);
-          if (!neighborVector) continue;
-
-          const distance = this.calculateDistance(query, neighborVector);
-
-          // Add to results if it's good enough
-          if (this.resultsHeap.size() < ef || distance < furthestResultDist) {
-            this.candidatesHeap.push(neighborId, distance);
-            this.resultsHeap.push(neighborId, distance);
-
-            // Maintain max size of ef and update cached furthest distance
-            if (this.resultsHeap.size() > ef) {
-              this.resultsHeap.pop(); // Remove furthest (O(log n))
-            }
-            furthestResultDist = this.resultsHeap.peekValue();
-          }
-        }
-      }
-    }
-
-    // Extract results from max-heap into pre-sized array
-    // Build in reverse order to avoid reverse() call
-    const resultCount = this.resultsHeap.size();
-    const results: Array<{ id: number; distance: number }> = new Array(resultCount);
-    let idx = resultCount - 1;
-    while (!this.resultsHeap.isEmpty()) {
-      const dist = this.resultsHeap.peekValue();
-      const id = this.resultsHeap.pop();
-      results[idx--] = { id, distance: dist };
-    }
-
-    return results;
-  }
-
-  private greedySearch(query: Float32Array, entryNode: Node, level: number): { id: number; distance: number } {
-    // Simplified greedy search - no heap needed, just follow the best neighbor
-    this.clearVisited();
-
-    let currentNode = entryNode;
-    // Load entry node vector if lazy loading is enabled
-    const entryVector = this.getNodeVector(entryNode.id);
-    let currentDistance = entryVector ? this.calculateDistance(query, entryVector) : Infinity;
-    this.markVisited(currentNode.id);
-
-    // Keep following the best neighbor until no improvement
-    let improved = true;
-    while (improved) {
-      improved = false;
-      const neighbors = currentNode.neighbors[level] || [];
-
-      for (const neighborId of neighbors) {
-        if (this.isVisited(neighborId)) continue;
-        this.markVisited(neighborId);
-
-        const neighborVector = this.getNodeVector(neighborId);
-        if (!neighborVector) continue;
-
-        const neighborNode = this.nodes[neighborId];
-        if (!neighborNode) continue;
-
-        const distance = this.calculateDistance(query, neighborVector);
-
-        if (distance < currentDistance) {
-          currentDistance = distance;
-          currentNode = neighborNode;
-          improved = true;
-        }
-      }
-    }
-
-    return { id: currentNode.id, distance: currentDistance };
-  }
-
-  /**
-   * Add a point to the index (async wrapper for API compatibility)
-   * For bulk operations, use addPointsBulk() which uses the faster sync version internally
-   */
-  async addPoint(id: number, vector: number[] | Float32Array, options?: { skipNormalization?: boolean }): Promise<void> {
-    this.addPointSync(id, vector, options);
-  }
-
-  /**
-   * Synchronous version of addPoint - avoids async/await microtask overhead
-   * 10-15x faster for bulk insertions where async is not needed
-   * @param skipNormalization - Set true if vectors are already unit-normalized (e.g., Cohere embeddings)
-   */
-  addPointSync(id: number, vector: number[] | Float32Array, options?: { skipNormalization?: boolean }): void {
-    this.validateNodeId(id);
-    if (this.nodes[id]) {
-      throw new VectorDBError(`Duplicate node ID ${id}: node already exists`, 'DUPLICATE_VECTOR');
-    }
-
-    // Optimize: only copy when necessary
-    // - Always copy arrays (need Float32Array)
-    // - Copy Float32Array only if we need to normalize (modifies in place)
-    // - Reuse input directly if skipNormalization is set (caller guarantees immutability)
-    let floatVector: Float32Array;
-    if (Array.isArray(vector)) {
-      floatVector = new Float32Array(vector);
-    } else if (this.vectorsAreNormalized && !options?.skipNormalization) {
-      // Need to copy because normalizeVector modifies in place
-      floatVector = new Float32Array(vector);
-    } else {
-      // No normalization needed and input is Float32Array - use directly
-      // Note: caller should not modify this array after passing it
-      floatVector = vector;
-    }
-
-    if (floatVector.length !== this.dimension) {
-      throw new VectorDBError(`Vector dimension ${floatVector.length} does not match expected ${this.dimension}`, 'DIMENSION_MISMATCH');
-    }
-
-    // Validate vector contains no NaN or Infinity values (these corrupt the graph)
-    for (let i = 0; i < floatVector.length; i++) {
-      if (!isFinite(floatVector[i])) {
-        throw new VectorDBError(`Vector contains non-finite value at index ${i}: ${floatVector[i]}`, 'VALIDATION_ERROR');
-      }
-    }
-
-    // Pre-normalize vectors for cosine metric for faster distance computation
-    // Skip if caller indicates vectors are already normalized
-    if (this.vectorsAreNormalized && !options?.skipNormalization) {
-      floatVector = this.normalizeVector(floatVector);
-    }
-
-    // Create new node
-    const level = this.selectLevel();
-    // Pre-allocate neighbors array without Array.from overhead
-    const neighbors = new Array<number[]>(level + 1);
-    for (let i = 0; i <= level; i++) {
-      neighbors[i] = [];
-    }
-    const newNode: Node = {
-      id,
-      level,
-      vector: floatVector,
-      neighbors,
-    };
-
-    this.setNode(newNode);
-
-    // Keep quantized representation in sync for indexes that were
-    // quantized before new inserts.
-    if (this.quantizationEnabled && this.scalarQuantizer) {
-      this.int8Vectors[id] = this.scalarQuantizer.quantize(floatVector);
-      // Also update contiguous Int8 storage
-      if (this.flatInt8Vectors) {
-        this.scalarQuantizer.quantizeInto(floatVector, this.flatInt8Vectors, id * this.dimension);
-      }
-    }
-
-    // If this is the first node, make it the entry point
-    if (this.entryPointId === -1) {
-      this.entryPointId = id;
-      this.maxLevel = level;
-      return;
-    }
-
-    // Find the entry point at the highest level
-    let currentEntryPoint = this.nodes[this.entryPointId]!;
-    let currentBest = { id: currentEntryPoint.id, distance: this.calculateDistance(floatVector, currentEntryPoint.vector) };
-
-    // Go down from max level to insertion level
-    for (let l = this.maxLevel; l > level; l--) {
-      const result = this.greedySearch(floatVector, currentEntryPoint, l);
-      if (result.distance < currentBest.distance) {
-        currentBest = result;
-        currentEntryPoint = this.nodes[currentBest.id]!;
-      }
-    }
-
-    // Now connect at each level from the insertion level down to 0
-    for (let l = Math.min(level, this.maxLevel); l >= 0; l--) {
-      // Search in the current level
-      // Use int8 quantized search at layer 0 during construction if enabled
-      const searchResults = (this.useInt8Construction && this.quantizationEnabled && l === 0)
-        ? this.searchLayerQuantized(floatVector, currentBest, l, this.efConstruction)
-        : this.searchLayer(floatVector, currentBest, l, this.efConstruction);
-
-      // Get neighbors for this level
-      const neighbors = this.selectNeighbors(id, searchResults, l);
-
-      // Add bidirectional connections
-      for (const neighborId of neighbors) {
-        this.addBidirectionalConnection(id, neighborId, l);
-      }
-
-      // Update the current best for the next level
-      if (searchResults.length > 0) {
-        currentBest = searchResults[0];
-      }
-    }
-
-    // Update the entry point if a higher level was created
-    if (level > this.maxLevel) {
-      this.maxLevel = level;
-      this.entryPointId = id;
-    }
-  }
-
-  searchKNN(query: Float32Array, k: number, efSearch?: number): Array<{ id: number; distance: number }> {
-    this.validateSearchParams(k, efSearch);
-    this.validateQueryVector(query);
-
-    if (this.entryPointId === -1 || this.nodeCount === 0) {
-      return [];
-    }
-
-    const effectiveEf = efSearch || Math.max(k * 2, 50);
-
-    // Normalize query vector for cosine metric to match stored normalized vectors
-    // Reuse pre-allocated buffer to avoid allocation per query (17% measured speedup)
-    let normalizedQuery = query;
-    if (this.vectorsAreNormalized) {
-      // Copy to reusable buffer and normalize in place
-      this.queryNormBuffer.set(query);
-      normalizedQuery = this.normalizeVector(this.queryNormBuffer);
-    }
-
-    // Start from the entry point at the highest level
-    let currentEntryPoint = this.nodes[this.entryPointId]!;
-    const entryVector = this.getNodeVector(this.entryPointId);
-    if (!entryVector) return [];
-    let currentBest = { id: currentEntryPoint.id, distance: this.calculateDistance(normalizedQuery, entryVector) };
-
-    // Go down from max level to level 1
-    for (let l = this.maxLevel; l > 0; l--) {
-      const result = this.greedySearch(normalizedQuery, currentEntryPoint, l);
-      if (result.distance < currentBest.distance) {
-        currentBest = result;
-        currentEntryPoint = this.nodes[currentBest.id]!;
-      }
-    }
-
-    // At level 0, perform detailed search
-    const candidates = this.searchLayer(normalizedQuery, currentBest, 0, effectiveEf);
-
-    // Results from searchLayer are already sorted by distance ascending.
-    // Only re-sort if there are exact distance ties (virtually never with float32).
-    let hasTies = false;
-    for (let i = 1; i < candidates.length; i++) {
-      if (candidates[i].distance === candidates[i - 1].distance) {
-        hasTies = true;
-        break;
-      }
-    }
-    if (hasTies) {
-      candidates.sort((a, b) => {
-        const diff = a.distance - b.distance;
-        return diff !== 0 ? diff : a.id - b.id;
-      });
-    }
-
-    // Return only top k results - truncate in place instead of slice
-    if (candidates.length > k) candidates.length = k;
-
-    return candidates;
-  }
-
-  /**
-   * Batch search for multiple query vectors.
-   * More efficient than calling searchKNN multiple times as it reuses internal buffers.
-   *
-   * @param queries Array of query vectors
-   * @param k Number of nearest neighbors to return per query
-   * @param efSearch Search effort parameter (higher = better recall, slower)
-   * @returns Array of results, one per query
-   */
-  searchKNNBatch(
-    queries: Float32Array[],
-    k: number,
-    efSearch?: number
-  ): Array<Array<{ id: number; distance: number }>> {
-    const numQueries = queries.length;
-    this.validateSearchParams(k, efSearch);
-
-    for (let i = 0; i < numQueries; i++) {
-      this.validateQueryVector(queries[i], `Query ${i}`);
-    }
-
-    if (this.entryPointId === -1 || this.nodeCount === 0) {
-      // Pre-allocate empty result arrays
-      const emptyResults = new Array<Array<{ id: number; distance: number }>>(numQueries);
-      for (let i = 0; i < numQueries; i++) {
-        emptyResults[i] = [];
-      }
-      return emptyResults;
-    }
-
-    // Pre-allocate results array
-    const results = new Array<Array<{ id: number; distance: number }>>(numQueries);
-
-    for (let i = 0; i < numQueries; i++) {
-      // searchKNN handles its own clearVisited() internally
-      results[i] = this.searchKNN(queries[i], k, efSearch);
-    }
-
-    return results;
-  }
-
-  /**
-   * Optimized batch search that returns results in a flat structure for better performance.
-   * Useful when you need to process many queries quickly.
-   *
-   * @param queries Flat Float32Array containing all queries concatenated
-   * @param numQueries Number of queries in the array
-   * @param k Number of nearest neighbors to return per query
-   * @param efSearch Search effort parameter
-   * @returns Object with flat arrays for ids and distances
-   */
-  searchKNNBatchFlat(
-    queries: Float32Array,
-    numQueries: number,
-    k: number,
-    efSearch?: number
-  ): { ids: Uint32Array; distances: Float32Array } {
-    this.validateSearchParams(k, efSearch);
-    if (!Number.isInteger(numQueries) || numQueries < 0) {
-      throw new VectorDBError(`numQueries must be a non-negative integer, got ${numQueries}`, 'VALIDATION_ERROR');
-    }
-    const expectedLength = numQueries * this.dimension;
-    if (queries.length !== expectedLength) {
-      throw new VectorDBError(`Flat query buffer length ${queries.length} does not match expected ${expectedLength}`, 'VALIDATION_ERROR');
-    }
-    for (let i = 0; i < queries.length; i++) {
-      if (!Number.isFinite(queries[i])) {
-        throw new VectorDBError(`Query contains non-finite value at flat index ${i}: ${queries[i]}`, 'VALIDATION_ERROR');
-      }
-    }
-
-    if (this.entryPointId === -1 || this.nodeCount === 0) {
-      return {
-        ids: new Uint32Array(numQueries * k).fill(HNSWIndex.MISSING_ID_SENTINEL),
-        distances: new Float32Array(numQueries * k).fill(Infinity)
-      };
-    }
-
-    const ids = new Uint32Array(numQueries * k);
-    const distances = new Float32Array(numQueries * k);
-
-    for (let q = 0; q < numQueries; q++) {
-      // Extract query vector
-      const queryStart = q * this.dimension;
-      const query = queries.subarray(queryStart, queryStart + this.dimension);
-
-      // searchKNN handles its own clearVisited() internally
-      const results = this.searchKNN(query, k, efSearch);
-
-      // Copy results to output arrays
-      const resultStart = q * k;
-      for (let i = 0; i < k; i++) {
-        if (i < results.length) {
-          ids[resultStart + i] = results[i].id;
-          distances[resultStart + i] = results[i].distance;
-        } else {
-          ids[resultStart + i] = HNSWIndex.MISSING_ID_SENTINEL; // sentinel for "no result"
-          distances[resultStart + i] = Infinity;
-        }
-      }
-    }
-
-    return { ids, distances };
-  }
-
-  // ============================================
-  // Convenience Methods
-  // ============================================
-
-  private allocateAutoId(): number {
-    if (this.nextAutoId > HNSWIndex.MAX_NODE_ID) {
-      throw new VectorDBError(
-        `Cannot allocate new node ID: exhausted supported ID space (max ${HNSWIndex.MAX_NODE_ID})`,
-        'VALIDATION_ERROR'
-      );
-    }
-    const id = this.nextAutoId;
-    this.nextAutoId++;
-    return id;
-  }
-
-  /**
-   * Add a single vector with auto-generated ID.
-   * Returns the assigned ID.
-   *
-   * @param vector Vector to add
-   * @returns The auto-generated ID
-   *
-   * @example
-   * ```typescript
-   * const id = await index.add([0.1, 0.2, 0.3]);
-   * console.log(`Added vector with ID: ${id}`);
-   * ```
-   */
-  async add(vector: number[] | Float32Array): Promise<number> {
-    const id = this.allocateAutoId();
-    await this.addPoint(id, vector);
-    return id;
-  }
-
-  /**
-   * Simple query interface - find k nearest neighbors.
-   *
-   * @param vector Query vector
-   * @param k Number of results (default: 10)
-   * @returns Array of {id, distance} results
-   *
-   * @example
-   * ```typescript
-   * const results = index.query([0.1, 0.2, 0.3], 5);
-   * results.forEach(r => console.log(`ID: ${r.id}, Distance: ${r.distance}`));
-   * ```
-   */
-  query(vector: number[] | Float32Array, k: number = 10): Array<{ id: number; distance: number }> {
-    const floatVector = Array.isArray(vector) ? new Float32Array(vector) : vector;
-    return this.searchKNN(floatVector, k);
-  }
-
-  /**
-   * Add multiple vectors with auto-generated IDs.
-   * Returns the assigned IDs.
-   *
-   * @param vectors Array of vectors to add
-   * @returns Array of auto-generated IDs
-   *
-   * @example
-   * ```typescript
-   * const ids = await index.addAll([[0.1, 0.2], [0.3, 0.4]]);
-   * ```
-   */
-  async addAll(vectors: Array<number[] | Float32Array>): Promise<number[]> {
-    if (vectors.length === 0) return [];
-
-    const lastId = this.nextAutoId + vectors.length - 1;
-    if (!Number.isSafeInteger(lastId) || lastId > HNSWIndex.MAX_NODE_ID) {
-      throw new VectorDBError(
-        `Cannot allocate ${vectors.length} node IDs: exhausted supported ID space (max ${HNSWIndex.MAX_NODE_ID})`,
-        'VALIDATION_ERROR'
-      );
-    }
-
-    const startId = this.nextAutoId;
-    this.nextAutoId = lastId + 1;
-
-    // Use bulk construction mode for better performance
-    const points = new Array<{ id: number; vector: Float32Array }>(vectors.length);
-    for (let i = 0; i < vectors.length; i++) {
-      const vector = vectors[i];
-      points[i] = {
-        id: startId + i,
-        vector: vector instanceof Float32Array ? vector : new Float32Array(vector)
-      };
-    }
-
-    await this.addPointsBulk(points);
-    return points.map(p => p.id);
-  }
-
-  /**
-   * Bulk add multiple points with optimized O(1) neighbor lookups.
-   * Significantly faster than sequential addPoint() calls for large batches.
-   * Uses Set-based membership testing during construction, then releases memory.
-   *
-   * @param points Array of {id, vector} to add
-   * @example
-   * ```typescript
-   * await index.addPointsBulk([
-   *   { id: 0, vector: new Float32Array([0.1, 0.2, ...]) },
-   *   { id: 1, vector: new Float32Array([0.3, 0.4, ...]) },
-   * ]);
-   * ```
-   */
-  async addPointsBulk(points: Array<{ id: number; vector: Float32Array }>, options?: { skipNormalization?: boolean; useInt8Construction?: boolean; diverseSeedInsertion?: boolean }): Promise<void> {
-    this.addPointsBulkSync(points, options);
-  }
-
-  /**
-   * Reorder points for diversity — inserts "diverse seeds" first to create a better graph backbone.
-   * Uses farthest-point sampling on a random subset to select diverse initial points.
-   */
-  private reorderForDiversity(
-    points: Array<{ id: number; vector: Float32Array }>
-  ): Array<{ id: number; vector: Float32Array }> {
-    if (points.length <= 1000) return points;
-
-    const n = points.length;
-    const dim = this.dimension;
-    const sampleSize = Math.min(Math.ceil(Math.sqrt(n)), 2000);
-    const seedCount = Math.min(Math.ceil(Math.sqrt(n)), 500);
-
-    // Random sample indices
-    const sampleIndices: number[] = [];
-    const usedIndices = new Set<number>();
-    while (sampleIndices.length < sampleSize) {
-      const idx = Math.floor(Math.random() * n);
-      if (!usedIndices.has(idx)) {
-        usedIndices.add(idx);
-        sampleIndices.push(idx);
-      }
-    }
-
-    // Farthest-point sampling on the sample
-    // Start with a random point from the sample
-    const seedSamplePositions: number[] = [0]; // positions within sampleIndices
-    const minDists = new Float64Array(sampleSize);
-    minDists.fill(Infinity);
-
-    // Compute initial distances from first seed
-    const firstVec = points[sampleIndices[0]].vector;
-    for (let i = 1; i < sampleSize; i++) {
-      const vec = points[sampleIndices[i]].vector;
-      let dist = 0;
-      for (let d = 0; d < dim; d++) {
-        const diff = firstVec[d] - vec[d];
-        dist += diff * diff;
-      }
-      minDists[i] = dist;
-    }
-
-    // Greedily pick the farthest point from current set
-    for (let s = 1; s < seedCount; s++) {
-      // Find farthest point
-      let maxDist = -1;
-      let maxIdx = -1;
-      for (let i = 0; i < sampleSize; i++) {
-        if (minDists[i] > maxDist) {
-          maxDist = minDists[i];
-          maxIdx = i;
-        }
-      }
-      if (maxIdx === -1) break;
-
-      seedSamplePositions.push(maxIdx);
-      minDists[maxIdx] = -1; // Mark as selected
-
-      // Update min distances
-      const newSeedVec = points[sampleIndices[maxIdx]].vector;
-      for (let i = 0; i < sampleSize; i++) {
-        if (minDists[i] <= 0) continue; // Already selected or invalid
-        const vec = points[sampleIndices[i]].vector;
-        let dist = 0;
-        for (let d = 0; d < dim; d++) {
-          const diff = newSeedVec[d] - vec[d];
-          dist += diff * diff;
-        }
-        if (dist < minDists[i]) minDists[i] = dist;
-      }
-    }
-
-    // Map sample positions back to original indices
-    const seedOriginalIndices = new Set<number>();
-    for (const pos of seedSamplePositions) {
-      seedOriginalIndices.add(sampleIndices[pos]);
-    }
-
-    // Build reordered array: seeds first, then remaining in original order
-    const reordered: Array<{ id: number; vector: Float32Array }> = [];
-    for (const idx of seedOriginalIndices) {
-      reordered.push(points[idx]);
-    }
-    for (let i = 0; i < n; i++) {
-      if (!seedOriginalIndices.has(i)) {
-        reordered.push(points[i]);
-      }
-    }
-
-    return reordered;
-  }
-
-  /**
-   * Synchronous bulk insertion - 10-15x faster than async version
-   * Uses addPointSync() internally to avoid microtask queue overhead
-   * @param options.skipNormalization - Set true if vectors are already unit-normalized
-   * @param options.useInt8Construction - Use int8 quantized search at layer 0 during construction.
-   *   First 1000 vectors are inserted with float32 (to train quantizer), then remaining use int8.
-   *   Can yield 2-4x faster build times with minimal recall loss.
-   * @param options.diverseSeedInsertion - Reorder points to insert diverse seeds first for better graph backbone.
-   *   Uses farthest-point sampling on a random subset to select diverse initial points.
-   *   Only applies to batches > 1000 vectors.
-   */
-  addPointsBulkSync(
-    points: Array<{ id: number; vector: Float32Array }>,
-    options?: { skipNormalization?: boolean; useInt8Construction?: boolean; diverseSeedInsertion?: boolean }
-  ): void {
-    if (points.length === 0) return;
-
-    // Validate whole batch first so invalid inputs don't leave partial inserts.
-    const seenIds = new Set<number>();
-    for (const { id, vector } of points) {
-      this.validateNodeId(id);
-      if (seenIds.has(id) || this.nodes[id]) {
-        throw new VectorDBError(
-          `Duplicate node ID ${id}: node already exists or appears multiple times in batch`,
-          'DUPLICATE_VECTOR'
-        );
-      }
-      seenIds.add(id);
-
-      if (vector.length !== this.dimension) {
-        throw new VectorDBError(`Vector dimension ${vector.length} does not match expected ${this.dimension}`, 'DIMENSION_MISMATCH');
-      }
-      for (let i = 0; i < vector.length; i++) {
-        if (!Number.isFinite(vector[i])) {
-          throw new VectorDBError(`Vector contains non-finite value at index ${i}: ${vector[i]}`, 'VALIDATION_ERROR');
-        }
-      }
-    }
-
-    // Reorder for diverse seed insertion if requested
-    if (options?.diverseSeedInsertion) {
-      points = this.reorderForDiversity(points);
-    }
-
-    // Enable construction mode for O(1) neighbor lookups
-    this.constructionMode = true;
-    this.neighborSets.clear();
-
-    // Construction-time quantization: insert first batch with float32 to train quantizer,
-    // then switch to int8 search at layer 0 for remaining vectors
-    const int8ConstructionRequested = options?.useInt8Construction === true;
-    const trainingSetSize = Math.min(1000, points.length);
-
-    try {
-      if (int8ConstructionRequested && points.length > trainingSetSize) {
-        // Phase 1: Insert training set with float32 search
-        for (let i = 0; i < trainingSetSize; i++) {
-          this.addPointSync(points[i].id, points[i].vector, options);
-        }
-
-        // Train quantizer and enable quantization on inserted vectors
-        if (!this.quantizationEnabled) {
-          this.enableQuantization();
-        }
-
-        // Phase 2: Insert remaining vectors using int8 search at layer 0
-        this.useInt8Construction = true;
-        for (let i = trainingSetSize; i < points.length; i++) {
-          this.addPointSync(points[i].id, points[i].vector, options);
-        }
-      } else {
-        // Standard insertion (no int8 construction)
-        for (const { id, vector } of points) {
-          this.addPointSync(id, vector, options);
-        }
-      }
-    } finally {
-      // Always cleanup, even on error
-      this.constructionMode = false;
-      this.useInt8Construction = false;
-      this.neighborSets.clear(); // Release memory
-    }
-  }
-
-  /**
-   * Clear construction-time data structures to free memory.
-   * Called automatically after addPointsBulk(), but can be called
-   * manually if needed.
-   */
-  clearConstructionCache(): void {
-    this.constructionMode = false;
-    this.neighborSets.clear();
-  }
-
-  // Format version constants
-  private static readonly MAGIC = 0x484E5357; // "HNSW" in ASCII (big-endian: 0x48='H', 0x4E='N', 0x53='S', 0x57='W')
-  private static readonly FORMAT_VERSION = 3; // v3: vector offset index for lazy loading
-  private static readonly HEADER_SIZE = 40; // 4 (magic) + 4 (version) + 28 (existing header) + 4 (vectorDataOffset)
-
-  private static ensureReadable(bufferLength: number, offset: number, bytes: number, context: string): void {
-    if (offset + bytes > bufferLength) {
-      const available = Math.max(0, bufferLength - offset);
-      throw new VectorDBError(
-        `Corrupt HNSW data: truncated ${context} (need ${bytes} bytes, only ${available} available)`,
-        'CORRUPT_INDEX'
-      );
-    }
-  }
-
-  private static wrapDeserializeError(error: unknown): VectorDBError {
-    if (error instanceof VectorDBError) {
-      return error;
-    }
-    if (error instanceof Error) {
-      return new VectorDBError(`Corrupt HNSW data: ${error.message}`, 'CORRUPT_INDEX');
-    }
-    return new VectorDBError('Corrupt HNSW data: failed to deserialize index', 'CORRUPT_INDEX');
-  }
-
-  /**
-   * Get all nodes as an array (filters out undefined slots)
-   */
-  private getNodesArray(): Node[] {
-    const result: Node[] = [];
-    for (let i = 0; i < this.nodeCount; i++) {
-      const node = this.nodes[i];
-      if (node) result.push(node);
-    }
-    return result;
-  }
-
-  /**
-   * Get shared search data for worker pool parallelism.
-   * Returns a copy of flat vectors and serialized graph structure.
-   */
-  getSharedSearchData(): {
-    flatVectors: Float32Array;
-    dimension: number;
-    nodeCount: number;
-    metric: DistanceMetric;
-    entryPointId: number;
-    maxLevel: number;
-    M: number;
-    M0: number;
-    graphData: ArrayBuffer;
-    nodeLevels: Uint8Array;
-  } | null {
-    if (this.nodeCount === 0 || this.entryPointId === -1) return null;
-
-    const graphData = this.serializeGraphStructure();
-    const nodeLevels = new Uint8Array(this.nodeCount);
-    for (let i = 0; i < this.nodeCount; i++) {
-      const node = this.nodes[i];
-      if (node) nodeLevels[i] = node.level;
-    }
-
-    return {
-      flatVectors: new Float32Array(this.flatVectors.buffer.slice(0, this.nodeCount * this.dimension * 4)),
-      dimension: this.dimension,
-      nodeCount: this.nodeCount,
-      metric: this.metric,
-      entryPointId: this.entryPointId,
-      maxLevel: this.maxLevel,
-      M: this.M,
-      M0: this.M0,
-      graphData,
-      nodeLevels,
-    };
-  }
-
-  /**
-   * Serialize graph structure (neighbor lists) into a compact ArrayBuffer.
-   * Format per node: [numLayers:uint8] [numNeighbors:uint16, neighborId:uint32...] per layer
-   */
-  private serializeGraphStructure(): ArrayBuffer {
-    // Estimate size
-    let totalSize = 0;
-    for (let i = 0; i < this.nodeCount; i++) {
-      const node = this.nodes[i];
-      if (!node) {
-        totalSize += 1; // numLayers = 0
-        continue;
-      }
-      totalSize += 1; // numLayers byte
-      for (const neighbors of node.neighbors) {
-        totalSize += 2; // numNeighbors uint16
-        totalSize += (neighbors?.length ?? 0) * 4; // neighbor IDs uint32
-      }
-    }
-
-    const buffer = new ArrayBuffer(totalSize);
-    const view = new DataView(buffer);
-    let offset = 0;
-
-    for (let i = 0; i < this.nodeCount; i++) {
-      const node = this.nodes[i];
-      if (!node) {
-        view.setUint8(offset++, 0);
-        continue;
-      }
-
-      const numLayers = node.neighbors.length;
-      view.setUint8(offset++, numLayers);
-
-      for (let l = 0; l < numLayers; l++) {
-        const neighbors = node.neighbors[l] ?? [];
-        view.setUint16(offset, neighbors.length, true);
-        offset += 2;
-        for (const nid of neighbors) {
-          view.setUint32(offset, nid, true);
-          offset += 4;
-        }
-      }
-    }
-
-    return buffer;
-  }
-
-  /**
-   * Reorder nodes for BFS cache locality. Nodes are renumbered so that
-   * neighbors in the graph are stored contiguously in memory, reducing
-   * cache misses during search.
-   *
-   * @returns Map from old node ID to new node ID
-   */
-  reorderForLocality(): Map<number, number> {
-    if (this.nodeCount === 0 || this.entryPointId === -1) {
-      return new Map();
-    }
-
-    const dim = this.dimension;
-    const oldToNew = new Map<number, number>();
-    const visited = new Set<number>();
-    const queue: number[] = [];
-
-    // BFS from entry point to assign new sequential IDs
-    let newId = 0;
-    queue.push(this.entryPointId);
-    visited.add(this.entryPointId);
-
-    while (queue.length > 0) {
-      const oldId = queue.shift()!;
-      oldToNew.set(oldId, newId++);
-
-      const node = this.nodes[oldId];
-      if (!node) continue;
-
-      // Traverse all layers' neighbors
-      for (const neighbors of node.neighbors) {
-        if (!neighbors) continue;
-        for (const neighborId of neighbors) {
-          if (!visited.has(neighborId)) {
-            visited.add(neighborId);
-            queue.push(neighborId);
-          }
-        }
-      }
-    }
-
-    // Any nodes not reachable from entry point (disconnected) get IDs at the end
-    for (let i = 0; i < this.nodeCount; i++) {
-      if (this.nodes[i] && !oldToNew.has(i)) {
-        oldToNew.set(i, newId++);
-      }
-    }
-
-    // Build new data structures
-    const newNodes = new Array<Node | undefined>(newId);
-    const newFlatVectors = new Float32Array(Math.max(newId, this.flatVectorsCapacity) * dim);
-    let newFlatInt8Vectors: Int8Array | null = null;
-    let newInt8Vectors: (Int8Array | undefined)[] = [];
-
-    if (this.quantizationEnabled && this.flatInt8Vectors) {
-      newFlatInt8Vectors = new Int8Array(Math.max(newId, this.flatInt8VectorsCapacity) * dim);
-      newInt8Vectors = new Array(newId);
-    }
-
-    // Copy nodes with remapped IDs and neighbor lists
-    for (const [oldId, nid] of oldToNew) {
-      const oldNode = this.nodes[oldId];
-      if (!oldNode) continue;
-
-      // Remap neighbor lists
-      const newNeighbors: number[][] = [];
-      for (const neighbors of oldNode.neighbors) {
-        if (!neighbors) {
-          newNeighbors.push([]);
-          continue;
-        }
-        newNeighbors.push(neighbors.map(n => oldToNew.get(n) ?? n));
-      }
-
-      // Copy vector data
-      const oldOffset = oldId * dim;
-      const newOffset = nid * dim;
-      for (let d = 0; d < dim; d++) {
-        newFlatVectors[newOffset + d] = this.flatVectors[oldOffset + d];
-      }
-
-      // Copy int8 data if present
-      if (newFlatInt8Vectors && this.flatInt8Vectors) {
-        for (let d = 0; d < dim; d++) {
-          newFlatInt8Vectors[newOffset + d] = this.flatInt8Vectors[oldOffset + d];
-        }
-      }
-      if (this.int8Vectors[oldId]) {
-        newInt8Vectors[nid] = this.int8Vectors[oldId];
-      }
-
-      // Create new node with vector from flat storage
-      const vec = new Float32Array(dim);
-      vec.set(newFlatVectors.subarray(newOffset, newOffset + dim));
-
-      newNodes[nid] = {
-        id: nid,
-        level: oldNode.level,
-        vector: vec,
-        neighbors: newNeighbors,
-      };
-    }
-
-    // Update entry point
-    this.entryPointId = oldToNew.get(this.entryPointId) ?? this.entryPointId;
-
-    // Swap in new structures
-    this.nodes = newNodes;
-    this.flatVectors = newFlatVectors;
-    this.flatVectorsCapacity = Math.max(newId, this.flatVectorsCapacity);
-    if (newFlatInt8Vectors) {
-      this.flatInt8Vectors = newFlatInt8Vectors;
-      this.flatInt8VectorsCapacity = Math.max(newId, this.flatInt8VectorsCapacity);
-    }
-    this.int8Vectors = newInt8Vectors;
-    this.nodeCount = newId;
-    this.nextAutoId = newId;
-
-    // Reset visited array for new ID space
-    this.visitedArraySize = Math.max(newId + 1000, this.visitedArraySize);
-    this.visitedArray = new Uint16Array(this.visitedArraySize);
-    this.visitedGeneration = 1;
-
-    return oldToNew;
-  }
-
-  serialize(): ArrayBuffer {
-    // Format v3: Vectors stored separately at end with offset table for lazy loading
-    const nodesArray = this.getNodesArray();
-    const nodeCount = nodesArray.length;
-
-    // Build ID to index mapping first (needed for delta encoding)
-    const idToIndex = new Map<number, number>();
-    for (let i = 0; i < nodesArray.length; i++) {
-      idToIndex.set(nodesArray[i].id, i);
-    }
-
-    // Pre-encode all neighbor lists with delta encoding
-    const encodedNeighbors: Uint8Array[][] = [];
-    let totalNeighborBytes = 0;
-
-    for (const node of nodesArray) {
-      const nodeEncodings: Uint8Array[] = [];
-      for (let l = 0; l <= node.level; l++) {
-        const neighborIndices = node.neighbors[l].map((id) => {
-          const idx = idToIndex.get(id);
-          if (idx === undefined) {
-            throw new VectorDBError(
-              `Corrupt HNSW graph: node ${node.id} references missing neighbor ${id}`,
-              'CORRUPT_INDEX'
-            );
-          }
-          return idx;
-        });
-        const encoded = deltaEncodeNeighbors(neighborIndices);
-        nodeEncodings.push(encoded);
-        totalNeighborBytes += encoded.length;
-      }
-      encodedNeighbors.push(nodeEncodings);
-    }
-
-    // Calculate sizes for v3 format:
-    // - Header: 40 bytes (includes vectorDataOffset)
-    // - Node metadata: nodeCount * 8 (id + level)
-    // - Neighbor metadata: sum of (level+1) * 8 per node
-    // - Encoded neighbors: totalNeighborBytes
-    // - Vector offset table: nodeCount * 4 (offset within vector section)
-    // - Vectors: nodeCount * dimension * 4 (at end for lazy loading)
-    let graphSize = HNSWIndex.HEADER_SIZE;
-    graphSize += nodeCount * 8; // id + level per node
-
-    for (const node of nodesArray) {
-      graphSize += (node.level + 1) * 8; // neighbor metadata per level
-    }
-    graphSize += totalNeighborBytes;
-    graphSize += nodeCount * 4; // vector offset table
-
-    const vectorDataOffset = graphSize;
-    const vectorDataSize = nodeCount * this.dimension * 4;
-    const totalSize = graphSize + vectorDataSize;
-
-    const buffer = new ArrayBuffer(totalSize);
-    const view = new DataView(buffer);
-    const uint8Array = new Uint8Array(buffer);
-
-    let offset = 0;
-
-    // Write header with magic, version, and vectorDataOffset
-    view.setUint32(offset, HNSWIndex.MAGIC, true); offset += 4;
-    view.setUint32(offset, HNSWIndex.FORMAT_VERSION, true); offset += 4;
-    view.setUint32(offset, this.dimension, true); offset += 4;
-    const metricCode = this.metric === 'cosine' ? 0 : this.metric === 'euclidean' ? 1 : 2;
-    view.setUint32(offset, metricCode, true); offset += 4;
-    view.setUint32(offset, this.M, true); offset += 4;
-    view.setUint32(offset, this.efConstruction, true); offset += 4;
-    view.setInt32(offset, this.maxLevel, true); offset += 4;
-    view.setInt32(offset, this.entryPointId, true); offset += 4;
-    view.setUint32(offset, nodeCount, true); offset += 4;
-    view.setUint32(offset, vectorDataOffset, true); offset += 4; // New in v3
-
-    // Write node metadata (without vectors)
-    for (let i = 0; i < nodesArray.length; i++) {
-      const node = nodesArray[i];
-      view.setUint32(offset, node.id, true); offset += 4;
-      view.setUint32(offset, node.level, true); offset += 4;
-    }
-
-    // Write neighbor metadata (counts and encoded sizes)
-    for (let i = 0; i < nodesArray.length; i++) {
-      const node = nodesArray[i];
-      const nodeEncodings = encodedNeighbors[i];
-
-      for (let l = 0; l <= node.level; l++) {
-        view.setUint32(offset, node.neighbors[l].length, true); offset += 4;
-        view.setUint32(offset, nodeEncodings[l].length, true); offset += 4;
-      }
-    }
-
-    // Write all encoded neighbor data
-    for (let i = 0; i < nodesArray.length; i++) {
-      const nodeEncodings = encodedNeighbors[i];
-      for (const encoded of nodeEncodings) {
-        uint8Array.set(encoded, offset);
-        offset += encoded.length;
-      }
-    }
-
-    // Write vector offset table (offset within vector section)
-    for (let i = 0; i < nodesArray.length; i++) {
-      view.setUint32(offset, i * this.dimension * 4, true); // Relative offset
-      offset += 4;
-    }
-
-    // Write vectors at end (for lazy loading capability)
-    for (let i = 0; i < nodesArray.length; i++) {
-      const node = nodesArray[i];
-      for (let j = 0; j < this.dimension; j++) {
-        view.setFloat32(offset, node.vector[j], true);
-        offset += 4;
-      }
-    }
-
-    return buffer;
-  }
-
-  /**
-   * Deserialize an HNSW index from a buffer.
-   *
-   * @param buffer The serialized index buffer
-   * @param options Optional loading options
-   *   - lazyLoadVectors: If true, don't load vectors immediately (v3+ only)
-   */
-  static deserialize(buffer: ArrayBuffer, options?: { lazyLoadVectors?: boolean }): HNSWIndex {
-    try {
-      if (buffer.byteLength < 4) {
-        throw new VectorDBError('Corrupt HNSW data: buffer too small for header', 'CORRUPT_INDEX');
-      }
-
-      const view = new DataView(buffer);
-      const uint8Array = new Uint8Array(buffer);
-      const lazyLoad = options?.lazyLoadVectors ?? false;
-
-      let offset = 0;
-
-      const ensureReadable = (bytes: number, context: string): void => {
-        HNSWIndex.ensureReadable(buffer.byteLength, offset, bytes, context);
-      };
-
-      const readUint32 = (context: string): number => {
-        ensureReadable(4, context);
-        const value = view.getUint32(offset, true);
-        offset += 4;
-        return value;
-      };
-
-      const readInt32 = (context: string): number => {
-        ensureReadable(4, context);
-        const value = view.getInt32(offset, true);
-        offset += 4;
-        return value;
-      };
-
-      const readFloat32 = (context: string): number => {
-        ensureReadable(4, context);
-        const value = view.getFloat32(offset, true);
-        offset += 4;
-        return value;
-      };
-
-      // Check for magic header (new format v1+)
-      const possibleMagic = readUint32('magic header');
-      let formatVersion = 0;
-
-      if (possibleMagic === HNSWIndex.MAGIC) {
-        formatVersion = readUint32('format version');
-
-        if (formatVersion > HNSWIndex.FORMAT_VERSION) {
-          throw new VectorDBError(
-            `Unsupported HNSW format version: ${formatVersion}. Maximum supported: ${HNSWIndex.FORMAT_VERSION}`,
-            'UNSUPPORTED_FORMAT'
-          );
-        }
-      } else {
-        formatVersion = 0;
-        offset = 0;
-      }
-
-      // Read common header fields
-      const dimension = readUint32('dimension');
-      const metricCode = readUint32('metric');
-      let metric: DistanceMetric;
-      if (metricCode === 0) {
-        metric = 'cosine';
-      } else if (metricCode === 1) {
-        metric = 'euclidean';
-      } else if (metricCode === 2) {
-        metric = 'dot_product';
-      } else {
-        throw new VectorDBError(`Corrupt HNSW data: unknown metric code ${metricCode}`, 'CORRUPT_INDEX');
-      }
-      const M = readUint32('M');
-      const efConstruction = readUint32('efConstruction');
-      const maxLevel = readInt32('maxLevel');
-      const entryPointId = readInt32('entryPointId');
-      const nodeCount = readUint32('nodeCount');
-      const vectorByteLength = dimension * 4;
-
-      // V3+ has vectorDataOffset in header
-      let vectorDataOffset = 0;
-      if (formatVersion >= 3) {
-        vectorDataOffset = readUint32('vectorDataOffset');
-        if (vectorDataOffset > buffer.byteLength) {
-          throw new VectorDBError(
-            `Corrupt HNSW data: vectorDataOffset ${vectorDataOffset} exceeds buffer size ${buffer.byteLength}`,
-            'CORRUPT_INDEX'
-          );
-        }
-      }
-
-      const index = new HNSWIndex(dimension, metric, M, efConstruction);
-      index.maxLevel = maxLevel;
-      index.entryPointId = entryPointId;
-
-      const indexToId: number[] = new Array(nodeCount);
-
-      if (formatVersion >= 3) {
-        // V3 format: vectors at end, supports lazy loading
-        const nodeMetadata: Array<{ id: number; level: number }> = [];
-        const neighborMetadata: Array<Array<{ count: number; encodedSize: number }>> = [];
-
-        // First pass: read node metadata (no vectors here)
-        for (let i = 0; i < nodeCount; i++) {
-          const id = readUint32(`node ${i} id`);
-          const level = readUint32(`node ${i} level`);
-          indexToId[i] = id;
-          nodeMetadata.push({ id, level });
-        }
-
-        // Second pass: read neighbor metadata
-        for (let i = 0; i < nodeCount; i++) {
-          const level = nodeMetadata[i].level;
-          const levelMeta: Array<{ count: number; encodedSize: number }> = [];
-
-          for (let l = 0; l <= level; l++) {
-            const count = readUint32(`node ${i} layer ${l} neighbor count`);
-            const encodedSize = readUint32(`node ${i} layer ${l} encoded neighbor size`);
-            if ((count === 0) !== (encodedSize === 0)) {
-              throw new VectorDBError(
-                `Corrupt HNSW data: node ${i} layer ${l} has inconsistent neighbor metadata (count=${count}, encodedSize=${encodedSize})`,
-                'CORRUPT_INDEX'
-              );
-            }
-            levelMeta.push({ count, encodedSize });
-          }
-
-          neighborMetadata.push(levelMeta);
-        }
-
-        // Third pass: read and decode neighbor data
-        const nodeNeighbors: number[][][] = [];
-        for (let i = 0; i < nodeCount; i++) {
-          const level = nodeMetadata[i].level;
-          const neighbors = new Array<number[]>(level + 1);
-
-          for (let l = 0; l <= level; l++) {
-            const { count, encodedSize } = neighborMetadata[i][l];
-
-            if (count === 0) {
-              neighbors[l] = [];
-              continue;
-            }
-
-            ensureReadable(encodedSize, `node ${i} layer ${l} encoded neighbor payload`);
-            const encodedSlice = uint8Array.subarray(offset, offset + encodedSize);
-            offset += encodedSize;
-
-            const neighborIndices = deltaDecodeNeighbors(encodedSlice, count);
-            neighbors[l] = neighborIndices.map((idx) => {
-              if (idx < 0 || idx >= indexToId.length) {
-                throw new VectorDBError(
-                  `Corrupt HNSW data: neighbor index ${idx} out of range`,
-                  'CORRUPT_INDEX'
-                );
-              }
-              return indexToId[idx];
-            });
-          }
-
-          nodeNeighbors.push(neighbors);
-        }
-
-        // Vector offset table must be directly before vector data
-        const vectorTableBytes = nodeCount * 4;
-        if (offset + vectorTableBytes > vectorDataOffset) {
-          throw new VectorDBError(
-            `Corrupt HNSW data: vectorDataOffset ${vectorDataOffset} overlaps graph payload ending at ${offset + vectorTableBytes}`,
-            'CORRUPT_INDEX'
-          );
-        }
-        if (offset + vectorTableBytes < vectorDataOffset) {
-          throw new VectorDBError(
-            `Corrupt HNSW data: unexpected gap before vector section (expected offset ${offset + vectorTableBytes}, got ${vectorDataOffset})`,
-            'CORRUPT_INDEX'
-          );
-        }
-
-        // Read vector offset table
-        for (let i = 0; i < nodeCount; i++) {
-          const relativeOffset = readUint32(`node ${i} vector relative offset`);
-          const absoluteOffset = vectorDataOffset + relativeOffset;
-          if (absoluteOffset > buffer.byteLength - vectorByteLength) {
-            throw new VectorDBError(
-              `Corrupt HNSW data: node ${i} vector offset ${absoluteOffset} out of range`,
-              'CORRUPT_INDEX'
-            );
-          }
-          const id = nodeMetadata[i].id;
-          index.vectorOffsets.set(id, absoluteOffset);
-        }
-
-        if (offset !== vectorDataOffset) {
-          throw new VectorDBError(
-            `Corrupt HNSW data: vector section starts at ${vectorDataOffset}, but parser reached ${offset}`,
-            'CORRUPT_INDEX'
-          );
-        }
-
-        // Create nodes and optionally load vectors
-        if (lazyLoad) {
-          // Lazy loading: store buffer, don't load vectors yet
-          index.lazyLoadEnabled = true;
-          index.vectorBuffer = buffer;
-
-          for (let i = 0; i < nodeCount; i++) {
-            const { id, level } = nodeMetadata[i];
-            // Create node with empty vector (will be loaded on demand)
-            const node: Node = {
-              id,
-              level,
-              vector: new Float32Array(dimension), // Placeholder
-              neighbors: nodeNeighbors[i]
-            };
-            index.setNode(node);
-          }
-        } else {
-          // Eager loading: load all vectors now
-          for (let i = 0; i < nodeCount; i++) {
-            const { id, level } = nodeMetadata[i];
-            const vectorOffset = index.vectorOffsets.get(id)!;
-
-            const vector = new Float32Array(dimension);
-            for (let j = 0; j < dimension; j++) {
-              HNSWIndex.ensureReadable(
-                buffer.byteLength,
-                vectorOffset + j * 4,
-                4,
-                `node ${i} vector component ${j}`
-              );
-              vector[j] = view.getFloat32(vectorOffset + j * 4, true);
-            }
-
-            const node: Node = { id, level, vector, neighbors: nodeNeighbors[i] };
-            index.setNode(node);
-            index.vectorsLoaded.add(id);
-          }
-        }
-      } else if (formatVersion >= 2) {
-        // V2 format: delta-encoded neighbor lists, vectors inline
-        const nodeMetadata: Array<{ id: number; level: number; vector: Float32Array }> = [];
-        const neighborMetadata: Array<Array<{ count: number; encodedSize: number }>> = [];
-
-        for (let i = 0; i < nodeCount; i++) {
-          const id = readUint32(`node ${i} id`);
-          const level = readUint32(`node ${i} level`);
-          indexToId[i] = id;
-
-          const vector = new Float32Array(dimension);
-          for (let j = 0; j < dimension; j++) {
-            vector[j] = readFloat32(`node ${i} vector component ${j}`);
-          }
-
-          nodeMetadata.push({ id, level, vector });
-        }
-
-        for (let i = 0; i < nodeCount; i++) {
-          const level = nodeMetadata[i].level;
-          const levelMeta: Array<{ count: number; encodedSize: number }> = [];
-
-          for (let l = 0; l <= level; l++) {
-            const count = readUint32(`node ${i} layer ${l} neighbor count`);
-            const encodedSize = readUint32(`node ${i} layer ${l} encoded neighbor size`);
-            if ((count === 0) !== (encodedSize === 0)) {
-              throw new VectorDBError(
-                `Corrupt HNSW data: node ${i} layer ${l} has inconsistent neighbor metadata (count=${count}, encodedSize=${encodedSize})`,
-                'CORRUPT_INDEX'
-              );
-            }
-            levelMeta.push({ count, encodedSize });
-          }
-
-          neighborMetadata.push(levelMeta);
-        }
-
-        for (let i = 0; i < nodeCount; i++) {
-          const { id, level, vector } = nodeMetadata[i];
-          const neighbors = new Array<number[]>(level + 1);
-
-          for (let l = 0; l <= level; l++) {
-            const { count, encodedSize } = neighborMetadata[i][l];
-
-            if (count === 0) {
-              neighbors[l] = [];
-              continue;
-            }
-
-            ensureReadable(encodedSize, `node ${i} layer ${l} encoded neighbor payload`);
-            const encodedSlice = uint8Array.subarray(offset, offset + encodedSize);
-            offset += encodedSize;
-
-            const neighborIndices = deltaDecodeNeighbors(encodedSlice, count);
-            neighbors[l] = neighborIndices.map((idx) => {
-              if (idx < 0 || idx >= indexToId.length) {
-                throw new VectorDBError(
-                  `Corrupt HNSW data: neighbor index ${idx} out of range`,
-                  'CORRUPT_INDEX'
-                );
-              }
-              return indexToId[idx];
-            });
-          }
-
-          const node: Node = { id, level, vector, neighbors };
-          index.setNode(node);
-        }
-      } else {
-        // V0/V1 format: raw neighbor IDs
-        for (let i = 0; i < nodeCount; i++) {
-          const id = readUint32(`node ${i} id`);
-          const level = readUint32(`node ${i} level`);
-          indexToId[i] = id;
-
-          const vector = new Float32Array(dimension);
-          for (let j = 0; j < dimension; j++) {
-            vector[j] = readFloat32(`node ${i} vector component ${j}`);
-          }
-
-          const neighbors = new Array<number[]>(level + 1);
-          for (let l = 0; l <= level; l++) {
-            const neighborCount = readUint32(`node ${i} layer ${l} neighbor count`);
-            neighbors[l] = new Array(neighborCount);
-          }
-          const node: Node = { id, level, vector, neighbors };
-
-          index.setNode(node);
-        }
-
-        for (let i = 0; i < index.nodeCount; i++) {
-          const node = index.nodes[i];
-          if (!node) continue;
-          for (let l = 0; l <= node.level; l++) {
-            for (let j = 0; j < node.neighbors[l].length; j++) {
-              const neighborIndex = readInt32(`node ${i} layer ${l} neighbor index ${j}`);
-              if (neighborIndex < 0 || neighborIndex >= indexToId.length) {
-                throw new VectorDBError(
-                  `Corrupt HNSW data: neighbor index ${neighborIndex} out of range`,
-                  'CORRUPT_INDEX'
-                );
-              }
-              node.neighbors[l][j] = indexToId[neighborIndex];
-            }
-          }
-        }
-      }
-
-      return index;
-    } catch (error) {
-      throw HNSWIndex.wrapDeserializeError(error);
-    }
-  }
-
-  /**
-   * Load a specific vector on demand (for lazy-loaded indices).
-   * Returns the vector if lazy loading is enabled, otherwise returns the already-loaded vector.
-   */
-  loadVector(nodeId: number): Float32Array | null {
-    const node = this.nodes[nodeId];
-    if (!node) return null;
-
-    // If not lazy loading or already loaded, return existing vector
-    if (!this.lazyLoadEnabled || this.vectorsLoaded.has(nodeId)) {
-      return node.vector;
-    }
-
-    // Load vector from buffer
-    if (!this.vectorBuffer) return null;
-
-    const vectorOffset = this.vectorOffsets.get(nodeId);
-    if (vectorOffset === undefined) return null;
-
-    const view = new DataView(this.vectorBuffer);
-    const vector = new Float32Array(this.dimension);
-    for (let j = 0; j < this.dimension; j++) {
-      vector[j] = view.getFloat32(vectorOffset + j * 4, true);
-    }
-
-    // Update node with loaded vector
-    node.vector = vector;
-    this.vectorsLoaded.add(nodeId);
-
-    // OPTIMIZATION: Also update flat vector storage for batch distance calculations
-    this.setFlatVector(nodeId, vector);
-
-    return vector;
-  }
-
-  /**
-   * Preload vectors for specific node IDs.
-   * Useful for warming up cache before searches.
-   */
-  preloadVectors(nodeIds: number[]): void {
-    if (!this.lazyLoadEnabled) return;
-
-    for (const nodeId of nodeIds) {
-      this.loadVector(nodeId);
-    }
-  }
-
-  /**
-   * Check if lazy loading is enabled
-   */
-  isLazyLoadEnabled(): boolean {
-    return this.lazyLoadEnabled;
-  }
-
-  /**
-   * Get lazy loading statistics
-   */
-  getLazyLoadStats(): { enabled: boolean; totalNodes: number; loadedVectors: number; memoryReduction: string } {
-    const totalNodes = this.nodeCount;
-    const loadedVectors = this.vectorsLoaded.size;
-
-    if (!this.lazyLoadEnabled) {
-      return {
-        enabled: false,
-        totalNodes,
-        loadedVectors: totalNodes,
-        memoryReduction: '0%'
-      };
-    }
-
-    const reduction = totalNodes > 0 ? ((1 - loadedVectors / totalNodes) * 100).toFixed(1) : '0';
-    return {
-      enabled: true,
-      totalNodes,
-      loadedVectors,
-      memoryReduction: `${reduction}%`
-    };
-  }
-
-  /**
-   * Save to binary file using Bun APIs.
-   * @deprecated Use serialize() with a StorageBackend instead for cross-platform support.
-   */
-  async saveToFile(filePath: string): Promise<void> {
-    const buffer = this.serialize();
-    await Bun.write(filePath, buffer);
-  }
-
-  /**
-   * Load from binary file using Bun APIs.
-   * @deprecated Use StorageBackend.read() + deserialize() instead for cross-platform support.
-   */
-  static async loadFromFile(filePath: string): Promise<HNSWIndex> {
-    const file = Bun.file(filePath);
-    const buffer = await file.arrayBuffer();
-    return HNSWIndex.deserialize(buffer);
-  }
-
-  // Clean up resources
-  destroy(): void {
-    // Clear all nodes to free memory
-    this.nodes = [];
-    this.nodeCount = 0;
-    this.nextAutoId = 0;
-    this.flatVectors = new Float32Array(0);
-    this.flatVectorsCapacity = 0;
-    // Reset entry point and level so reuse after destroy doesn't crash
-    this.entryPointId = -1;
-    this.maxLevel = -1;
-    // Clear quantization state
-    this.int8Vectors = [];
-    this.quantizationEnabled = false;
-    this.scalarQuantizer = null;
-    // Clear lazy-load state
-    this.lazyLoadEnabled = false;
-    this.vectorOffsets.clear();
-    this.vectorBuffer = null;
-    this.vectorsLoaded.clear();
-  }
-
-  /**
-   * Get memory usage statistics
-   */
-  getMemoryUsage(): number {
-    // Calculate approximate memory usage in bytes
-    let totalBytes = 0;
-
-    // Node objects
-    for (let i = 0; i < this.nodeCount; i++) {
-      const node = this.nodes[i];
-      if (!node) continue;
-      // Node structure: id (4 bytes), level (4 bytes), vector (4*dimension), neighbors array overhead
-      totalBytes += 8; // id + level
-      totalBytes += node.vector.length * 4; // vector data
-      totalBytes += 24; // neighbors array overhead (rough estimate)
-
-      // Neighbor connections
-      for (const neighborList of node.neighbors) {
-        totalBytes += neighborList.length * 4; // neighbor IDs
-        totalBytes += 16; // array overhead per level
-      }
-    }
-
-    // Flat vector storage
-    totalBytes += this.flatVectors.byteLength;
-
-    // Array overhead
-    totalBytes += this.nodeCount * 8; // Array entry overhead (rough estimate)
-
-    // Object overhead
-    totalBytes += 1024; // Base object overhead
-
-    return totalBytes;
-  }
-
-  getDimension(): number {
-    return this.dimension;
-  }
-
-  getMetric(): DistanceMetric {
-    return this.metric;
-  }
-
-  getM(): number {
-    return this.M;
-  }
-
-  getEfConstruction(): number {
-    return this.efConstruction;
-  }
-
-  /**
-   * Get all vectors for brute-force search
-   */
-  getAllVectors(): Map<number, Float32Array> {
-    const result = new Map<number, Float32Array>();
-    for (let i = 0; i < this.nodeCount; i++) {
-      const node = this.nodes[i];
-      if (!node) continue;
-      const vector = this.getNodeVector(node.id);
-      if (vector) {
-        result.set(node.id, vector);
-      }
-    }
-    return result;
-  }
-
-  // ============================================
-  // Quantized Search (Int8 with automatic rescoring)
-  // ============================================
-
-  /**
-   * Enable Int8 quantization for faster search with automatic rescoring.
-   * Trains the quantizer on existing vectors and quantizes them.
-   *
-   * Performance:
-   * - 4x memory reduction
-   * - 3-4x faster distance calculations
-   * - 99%+ recall with automatic rescoring
-   *
-   * @example
-   * ```typescript
-   * // After adding vectors
-   * index.enableQuantization();
-   *
-   * // Now use quantized search (automatically rescores for high recall)
-   * const results = index.searchKNNQuantized(query, 10);
-   * ```
-   */
-  enableQuantization(): void {
-    if (this.nodeCount === 0) {
-      throw new VectorDBError('Cannot enable quantization on empty index. Add vectors first.', 'VALIDATION_ERROR');
-    }
-
-    // Collect all vectors for training
-    const vectors: Float32Array[] = [];
-    for (let i = 0; i < this.nodeCount; i++) {
-      const node = this.nodes[i];
-      if (!node) continue;
-      const vector = this.getNodeVector(node.id);
-      if (!vector) {
-        throw new VectorDBError(`Cannot enable quantization: missing vector for node ${node.id}`, 'CORRUPT_INDEX');
-      }
-      vectors.push(vector);
-    }
-
-    // Initialize and train scalar (int8) quantizer
-    this.scalarQuantizer = new ScalarQuantizer(this.dimension);
-    this.scalarQuantizer.train(vectors);
-
-    // Quantize all existing vectors - use array instead of Map
-    this.int8Vectors = new Array(this.nodeCount);
-
-    // Also build contiguous Int8 storage for cache-friendly batch distance calculations
-    const dim = this.dimension;
-    this.flatInt8VectorsCapacity = Math.max(this.nodeCount, this.flatVectorsCapacity);
-    this.flatInt8Vectors = new Int8Array(this.flatInt8VectorsCapacity * dim);
-
-    for (let i = 0; i < this.nodeCount; i++) {
-      const node = this.nodes[i];
-      if (node) {
-        const vector = this.getNodeVector(node.id);
-        if (!vector) {
-          throw new VectorDBError(`Cannot quantize node ${node.id}: vector is unavailable`, 'CORRUPT_INDEX');
-        }
-        this.int8Vectors[node.id] = this.scalarQuantizer.quantize(vector);
-        // Also store in contiguous buffer
-        this.scalarQuantizer.quantizeInto(vector, this.flatInt8Vectors!, node.id * dim);
-      }
-    }
-
-    // Pre-allocate reusable query buffer for quantized search
-    this.queryInt8Buffer = new Int8Array(dim);
-
-    this.quantizationEnabled = true;
-  }
-
-  /**
-   * Check if quantization is enabled
-   */
-  isQuantizationEnabled(): boolean {
-    return this.quantizationEnabled;
-  }
-
-  /**
-   * Fast quantized search with automatic rescoring.
-   *
-   * Uses Int8 quantized vectors for initial candidate retrieval (3-4x faster),
-   * then rescores top candidates with float32 for accurate ranking.
-   *
-   * @param query Query vector
-   * @param k Number of results to return
-   * @param candidateMultiplier How many extra candidates to retrieve for rescoring (default: 3)
-   * @param efSearch Search effort parameter
-   * @returns Array of {id, distance} results (same format as searchKNN)
-   *
-   * Performance:
-   * - 3-4x faster than float32 for distance calculations
-   * - 99%+ recall with candidateMultiplier=3 (automatic rescoring)
-   * - 4x memory reduction
-   */
-  searchKNNQuantized(
-    query: Float32Array,
-    k: number,
-    candidateMultiplier: number = 3,
-    efSearch?: number
-  ): Array<{ id: number; distance: number }> {
-    this.validateSearchParams(k, efSearch);
-    this.validateQueryVector(query);
-    if (!Number.isInteger(candidateMultiplier) || candidateMultiplier <= 0) {
-      throw new VectorDBError(`candidateMultiplier must be a positive integer, got ${candidateMultiplier}`, 'VALIDATION_ERROR');
-    }
-
-    // Fallback to standard search if quantization not enabled
-    if (!this.quantizationEnabled) {
-      return this.searchKNN(query, k, efSearch);
-    }
-
-    if (this.entryPointId === -1 || this.nodeCount === 0) {
-      return [];
-    }
-
-    // Normalize query if needed - reuse buffer for efficiency
-    let normalizedQuery = query;
-    if (this.vectorsAreNormalized) {
-      this.queryNormBuffer.set(query);
-      normalizedQuery = this.normalizeVector(this.queryNormBuffer);
-    }
-
-    // Get more candidates than needed for rescoring.
-    // When efSearch is explicit, respect it as-is — the caller controls the
-    // recall/latency tradeoff. When omitted, auto-size based on candidateMultiplier.
-    const numCandidates = k * candidateMultiplier;
-    const effectiveEf = efSearch || Math.max(numCandidates * 2, 50);
-
-    // Phase 1: Fast HNSW navigation using float32 (only for graph traversal)
-    let currentEntryPoint = this.nodes[this.entryPointId]!;
-    const entryVector = this.getNodeVector(this.entryPointId);
-    if (!entryVector) return [];
-    let currentBest = { id: currentEntryPoint.id, distance: this.calculateDistance(normalizedQuery, entryVector) };
-
-    for (let l = this.maxLevel; l > 0; l--) {
-      const result = this.greedySearch(normalizedQuery, currentEntryPoint, l);
-      if (result.distance < currentBest.distance) {
-        currentBest = result;
-        currentEntryPoint = this.nodes[currentBest.id]!;
-      }
-    }
-
-    // Phase 2: Search layer 0 with quantized distance for speed
-    const candidates = this.searchLayerQuantized(normalizedQuery, currentBest, 0, effectiveEf);
-
-    // Phase 3: Rescore top candidates with float32 for accuracy
-    const rescoreCount = Math.min(candidates.length, numCandidates);
-
-    if (rescoreCount <= k) {
-      // Small array — direct rescore + sort
-      const rescored = new Array<{ id: number; distance: number }>(rescoreCount);
-      for (let i = 0; i < rescoreCount; i++) {
-        const c = candidates[i];
-        const nodeVector = this.getNodeVector(c.id);
-        if (nodeVector) {
-          rescored[i] = { id: c.id, distance: this.calculateDistance(normalizedQuery, nodeVector) };
-        } else {
-          rescored[i] = c;
-        }
-      }
-      rescored.sort((a, b) => {
-        const diff = a.distance - b.distance;
-        return diff !== 0 ? diff : a.id - b.id;
-      });
-      return rescored;
-    }
-
-    // Use max-heap to maintain top-k — O(n + k log k) vs O(n log n) sort
-    const heap = new MaxBinaryHeap(k);
-    for (let i = 0; i < rescoreCount; i++) {
-      const c = candidates[i];
-      const nodeVector = this.getNodeVector(c.id);
-      const dist = nodeVector ? this.calculateDistance(normalizedQuery, nodeVector) : c.distance;
-      if (heap.size() < k) {
-        heap.push(c.id, dist);
-      } else if (dist < heap.peekValue()) {
-        heap.pop();
-        heap.push(c.id, dist);
-      }
-    }
-
-    // Extract sorted results (drain max-heap in reverse)
-    const heapSize = heap.size();
-    const result = new Array<{ id: number; distance: number }>(heapSize);
-    for (let i = heapSize - 1; i >= 0; i--) {
-      result[i] = { id: heap.peek(), distance: heap.peekValue() };
-      heap.pop();
-    }
-    return result;
-  }
-
-  /**
-   * Calibrate the index for adaptive efSearch. Runs greedy descent for sample
-   * queries and records statistics about entry distances.
-   *
-   * @param sampleQueries Array of query vectors to calibrate with
-   */
-  calibrate(sampleQueries: Float32Array[]): void {
-    if (sampleQueries.length === 0) {
-      throw new VectorDBError('calibrate() requires at least one sample query', 'VALIDATION_ERROR');
-    }
-    if (this.entryPointId === -1 || this.nodeCount === 0) {
-      throw new VectorDBError('Cannot calibrate empty index', 'VALIDATION_ERROR');
-    }
-
-    const distances: number[] = [];
-
-    for (const query of sampleQueries) {
-      this.validateQueryVector(query, 'Calibration query');
-
-      // Normalize if needed
-      let normalizedQuery = query;
-      if (this.vectorsAreNormalized) {
-        this.queryNormBuffer.set(query);
-        normalizedQuery = this.normalizeVector(this.queryNormBuffer);
-      }
-
-      // Greedy descent to find best node
-      let currentEntryPoint = this.nodes[this.entryPointId]!;
-      const entryVector = this.getNodeVector(this.entryPointId);
-      if (!entryVector) continue;
-      let currentBest = { id: currentEntryPoint.id, distance: this.calculateDistance(normalizedQuery, entryVector) };
-
-      for (let l = this.maxLevel; l > 0; l--) {
-        const result = this.greedySearch(normalizedQuery, currentEntryPoint, l);
-        if (result.distance < currentBest.distance) {
-          currentBest = result;
-          currentEntryPoint = this.nodes[currentBest.id]!;
-        }
-      }
-
-      distances.push(currentBest.distance);
-    }
-
-    if (distances.length === 0) return;
-
-    const mean = distances.reduce((s, d) => s + d, 0) / distances.length;
-    const variance = distances.reduce((s, d) => s + (d - mean) ** 2, 0) / distances.length;
-    const std = Math.sqrt(variance);
-
-    this.calibrationStats = { meanEntryDist: mean, stdEntryDist: std };
-  }
-
-  /**
-   * Check if the index has been calibrated for adaptive search.
-   */
-  isCalibrated(): boolean {
-    return this.calibrationStats !== null;
-  }
-
-  /**
-   * Adaptive efSearch — scales ef based on query difficulty.
-   * Easy queries (close to graph) use lower ef, hard queries (far from graph) use higher ef.
-   * Falls back to baseEfSearch if not calibrated.
-   *
-   * @param query Query vector
-   * @param k Number of results to return
-   * @param baseEfSearch Base ef parameter (will be scaled up/down)
-   * @returns Same format as searchKNN
-   */
-  searchKNNAdaptive(
-    query: Float32Array,
-    k: number,
-    baseEfSearch?: number
-  ): Array<{ id: number; distance: number }> {
-    this.validateSearchParams(k, baseEfSearch);
-    this.validateQueryVector(query);
-
-    const baseEf = baseEfSearch || Math.max(k * 2, 50);
-
-    // If not calibrated, fall back to standard search
-    if (!this.calibrationStats) {
-      return this.searchKNN(query, k, baseEf);
-    }
-
-    if (this.entryPointId === -1 || this.nodeCount === 0) {
-      return [];
-    }
-
-    // Normalize query if needed
-    let normalizedQuery = query;
-    if (this.vectorsAreNormalized) {
-      this.queryNormBuffer.set(query);
-      normalizedQuery = this.normalizeVector(this.queryNormBuffer);
-    }
-
-    // Greedy descent to layer 0 entry
-    let currentEntryPoint = this.nodes[this.entryPointId]!;
-    const entryVector = this.getNodeVector(this.entryPointId);
-    if (!entryVector) return [];
-    let currentBest = { id: currentEntryPoint.id, distance: this.calculateDistance(normalizedQuery, entryVector) };
-
-    for (let l = this.maxLevel; l > 0; l--) {
-      const result = this.greedySearch(normalizedQuery, currentEntryPoint, l);
-      if (result.distance < currentBest.distance) {
-        currentBest = result;
-        currentEntryPoint = this.nodes[currentBest.id]!;
-      }
-    }
-
-    // Compute adaptive ef based on entry distance relative to calibration
-    const ratio = currentBest.distance / (this.calibrationStats.meanEntryDist || 1);
-    let adaptiveEf: number;
-    if (ratio < 0.5) {
-      adaptiveEf = Math.round(baseEf * 0.5); // Easy query
-    } else if (ratio > 2.0) {
-      adaptiveEf = Math.round(baseEf * 2.0); // Hard query
-    } else {
-      adaptiveEf = baseEf;
-    }
-
-    // Clamp between k and baseEf * 4
-    adaptiveEf = Math.max(k, Math.min(adaptiveEf, baseEf * 4));
-
-    // Search layer 0 with adaptive ef
-    const candidates = this.searchLayer(normalizedQuery, currentBest, 0, adaptiveEf);
-
-    // Conditional sort (same as searchKNN)
-    let hasTies = false;
-    for (let i = 1; i < candidates.length; i++) {
-      if (candidates[i].distance === candidates[i - 1].distance) {
-        hasTies = true;
-        break;
-      }
-    }
-    if (hasTies) {
-      candidates.sort((a, b) => {
-        const diff = a.distance - b.distance;
-        return diff !== 0 ? diff : a.id - b.id;
-      });
-    }
-
-    if (candidates.length > k) candidates.length = k;
-    return candidates;
-  }
-
-  /**
-   * Search layer using Int8 quantized distances for speed.
-   * OPTIMIZED: Uses batch distance calculation on contiguous flatInt8Vectors.
-   * Falls back to one-by-one with int8Vectors[] if contiguous storage unavailable.
-   */
-  private searchLayerQuantized(
-    query: Float32Array,
-    nearest: { id: number; distance: number },
-    layer: number,
-    ef: number
-  ): Array<{ id: number; distance: number }> {
-    // Quantize query once — reuse pre-allocated buffer when available
-    let int8Query: Int8Array | null = null;
-    if (this.scalarQuantizer) {
-      if (this.queryInt8Buffer) {
-        this.scalarQuantizer.quantizeInto(query, this.queryInt8Buffer, 0);
-        int8Query = this.queryInt8Buffer;
-      } else {
-        int8Query = this.scalarQuantizer.quantize(query);
-      }
-    }
-
-    // Clear visited tracking
-    this.clearVisited();
-
-    // Ensure heaps are large enough, then clear and reuse
-    this.ensureHeapCapacity(ef);
-    this.candidatesHeap.clear();
-    this.resultsHeap.clear();
-
-    // Initialize with entry point - recompute distance using int8 for consistent scale
-    this.markVisited(nearest.id);
-    let entryDist = nearest.distance;
-    if (int8Query && this.flatInt8Vectors) {
-      // Use contiguous storage for entry point distance
-      const dim = this.dimension;
-      const offset = nearest.id * dim;
-      const flatInt8 = this.flatInt8Vectors;
-      if (this.metric === 'euclidean') {
-        let sum = 0;
-        for (let d = 0; d < dim; d++) {
-          const diff = int8Query[d] - flatInt8[offset + d];
-          sum += diff * diff;
-        }
-        entryDist = Math.sqrt(sum);
-      } else {
-        // cosine/dot_product: -dotProduct
-        let sum = 0;
-        for (let d = 0; d < dim; d++) {
-          sum += int8Query[d] * flatInt8[offset + d];
-        }
-        entryDist = -sum;
-      }
-    } else if (int8Query) {
-      const entryInt8 = this.int8Vectors[nearest.id];
-      if (entryInt8) {
-        if (this.metric === 'cosine') {
-          entryDist = cosineDistanceInt8(int8Query, entryInt8);
-        } else if (this.metric === 'dot_product') {
-          entryDist = -dotProductInt8(int8Query, entryInt8);
-        } else {
-          entryDist = Math.sqrt(l2SquaredInt8(int8Query, entryInt8));
-        }
-      }
-    }
-    this.candidatesHeap.push(nearest.id, entryDist);
-    this.resultsHeap.push(nearest.id, entryDist);
-
-    let furthestResultDist = entryDist;
-
-    // OPTIMIZATION: Use batch path when contiguous int8 storage is available
-    const useBatchPath = int8Query !== null && this.flatInt8Vectors !== null;
-
-    // Reuse batch arrays from parent class
-    const batchIds = this.batchNeighborIds;
-    const batchDists = this.batchDistances;
-
-    while (!this.candidatesHeap.isEmpty()) {
-      const closestCandidateDist = this.candidatesHeap.peekValue();
-      const closestCandidateId = this.candidatesHeap.pop();
-
-      if (closestCandidateId === -1) continue;
-
-      // TERMINATION
-      if (this.resultsHeap.size() >= ef && closestCandidateDist > furthestResultDist) {
-        break;
-      }
-
-      const node = this.nodes[closestCandidateId];
-      if (!node) continue;
-
-      const neighbors = node.neighbors[layer] || [];
-
-      if (useBatchPath) {
-        // OPTIMIZED: Collect unvisited neighbors and compute distances in batch
-        let batchCount = 0;
-        for (let i = 0; i < neighbors.length; i++) {
-          const neighborId = neighbors[i];
-          if (!this.nodes[neighborId]) continue;
-          if (!this.isVisited(neighborId)) {
-            this.markVisited(neighborId);
-            batchIds[batchCount] = neighborId;
-            batchCount++;
-          }
-        }
-
-        if (batchCount > 0) {
-          if (batchDists.length < batchCount) {
-            this.batchDistances.length = batchCount;
-          }
-
-          this.calculateDistancesBatchInt8(int8Query!, batchIds, batchDists, batchCount);
-
-          for (let i = 0; i < batchCount; i++) {
-            const neighborId = batchIds[i];
-            const distance = batchDists[i];
-
-            if (this.resultsHeap.size() < ef || distance < furthestResultDist) {
-              this.candidatesHeap.push(neighborId, distance);
-              this.resultsHeap.push(neighborId, distance);
-
-              if (this.resultsHeap.size() > ef) {
-                this.resultsHeap.pop();
-              }
-              furthestResultDist = this.resultsHeap.peekValue();
-            }
-          }
-        }
-      } else {
-        // Fallback: one-by-one (no contiguous storage or no quantizer)
-        for (const neighborId of neighbors) {
-          if (this.isVisited(neighborId)) continue;
-          this.markVisited(neighborId);
-
-          let distance: number;
-          if (int8Query) {
-            const neighborInt8 = this.int8Vectors[neighborId];
-            if (neighborInt8) {
-              if (this.metric === 'cosine') {
-                distance = cosineDistanceInt8(int8Query, neighborInt8);
-              } else if (this.metric === 'dot_product') {
-                distance = -dotProductInt8(int8Query, neighborInt8);
-              } else {
-                distance = Math.sqrt(l2SquaredInt8(int8Query, neighborInt8));
-              }
-            } else {
-              const neighborVector = this.getNodeVector(neighborId);
-              if (!neighborVector) continue;
-              distance = this.calculateDistance(query, neighborVector);
-            }
-          } else {
-            const neighborVector = this.getNodeVector(neighborId);
-            if (!neighborVector) continue;
-            distance = this.calculateDistance(query, neighborVector);
-          }
-
-          if (this.resultsHeap.size() < ef || distance < furthestResultDist) {
-            this.candidatesHeap.push(neighborId, distance);
-            this.resultsHeap.push(neighborId, distance);
-
-            if (this.resultsHeap.size() > ef) {
-              this.resultsHeap.pop();
-            }
-            furthestResultDist = this.resultsHeap.peekValue();
-          }
-        }
-      }
-    }
-
-    // Extract results from max-heap
-    const resultCount = this.resultsHeap.size();
-    const results: Array<{ id: number; distance: number }> = new Array(resultCount);
-    let idx = resultCount - 1;
-    while (!this.resultsHeap.isEmpty()) {
-      const dist = this.resultsHeap.peekValue();
-      const id = this.resultsHeap.pop();
-      results[idx--] = { id, distance: dist };
-    }
-
-    return results;
-  }
-
-  /**
-   * Get quantization statistics
-   */
-  getQuantizationStats(): {
-    enabled: boolean;
-    vectorCount: number;
-    memoryReduction: string;
-    expectedSpeedup: string;
-  } {
-    const vectorCount = this.nodeCount;
-    const float32Size = vectorCount * this.dimension * 4;
-
-    if (this.quantizationEnabled) {
-      const int8Size = vectorCount * this.dimension;
-      const reduction = (float32Size / int8Size).toFixed(1);
-      return {
-        enabled: true,
-        vectorCount,
-        memoryReduction: `${reduction}x (${(float32Size / 1024 / 1024).toFixed(1)}MB → ${(int8Size / 1024 / 1024).toFixed(1)}MB)`,
-        expectedSpeedup: '3-4x for distance calculations'
-      };
-    }
-
-    return {
-      enabled: false,
-      vectorCount,
-      memoryReduction: '1x (no quantization)',
-      expectedSpeedup: '1x (baseline)'
-    };
-  }
-}