verso-db 0.1.4 → 0.2.0

package/dist/HNSWIndex.js

@@ -0,0 +1,2818 @@
+// Bun-native file operations - no fs import needed
+import { dotProductFast, l2SquaredFast, normalizeInPlace } from './backends/JsDistanceBackend.js';
+import { BinaryHeap } from './BinaryHeap.js';
+import { MaxBinaryHeap } from './MaxBinaryHeap.js';
+import { ScalarQuantizer, l2SquaredInt8, cosineDistanceInt8, dotProductInt8 } from './quantization/ScalarQuantizer.js';
+import { deltaEncodeNeighbors, deltaDecodeNeighbors } from './encoding/DeltaEncoder.js';
+import { VectorDBError } from './errors.js';
+export class HNSWIndex {
+    // 0xFFFFFFFF is reserved as "missing result" sentinel in batch flat output.
+    static MISSING_ID_SENTINEL = 0xFFFFFFFF;
+    static MAX_NODE_ID = HNSWIndex.MISSING_ID_SENTINEL - 1;
+    static MAX_ARRAY_BUFFER_BYTES = 0x7FFFFFFF;
+    static MAX_NODE_SLOTS = 50_000_000;
+    /**
+     * Allocate a Float32Array backed by SharedArrayBuffer when available.
+     * This allows workers to read vector data without copying.
+     */
+    static allocateFloat32(length, useSharedMemory = false) {
+        if (useSharedMemory && typeof SharedArrayBuffer !== 'undefined') {
+            return new Float32Array(new SharedArrayBuffer(length * 4));
+        }
+        return new Float32Array(length);
+    }
+    /**
+     * Allocate an Int8Array, optionally backed by SharedArrayBuffer.
+     */
+    static allocateInt8(length, useSharedMemory = false) {
+        if (useSharedMemory && typeof SharedArrayBuffer !== 'undefined') {
+            return new Int8Array(new SharedArrayBuffer(length));
+        }
+        return new Int8Array(length);
+    }
+    /** Whether flatVectors/flatInt8Vectors use SharedArrayBuffer */
+    useSharedMemory = false;
+    M; // Max number of connections per node per level
+    M0; // Max number of connections for level 0 (typically M * 2)
+    efConstruction; // Size of candidate list during construction
+    levelMult; // Probability multiplier for level selection
+    maxLevel;
+    entryPointId;
+    // OPTIMIZATION: Use array instead of Map for O(1) indexed access (3-5x faster than Map.get)
+    nodes;
+    nodeCount = 0;
+    nextAutoId = 0;
+    dimension;
+    metric;
+    maxLayers;
+    // OPTIMIZATION: Flat vector storage for cache-friendly batch distance calculations
+    // All vectors stored contiguously: [v0_d0, v0_d1, ..., v1_d0, v1_d1, ...]
+    flatVectors;
+    flatVectorsCapacity = 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
+    visitedArray;
+    visitedArraySize;
+    visitedGeneration = 0; // Increment to "clear" without filling
+    // Reusable heaps for searchLayer - avoids allocation on every call
+    candidatesHeap;
+    resultsHeap;
+    selectionHeap; // Reusable heap for selectNeighbors
+    heapCapacity;
+    // Pre-normalization optimization for cosine distance
+    vectorsAreNormalized = false;
+    // Cached distance function to avoid switch overhead
+    distanceFn;
+    // Quantization support for 3-4x faster search with Int8
+    scalarQuantizer = null;
+    // OPTIMIZATION: Use array instead of Map for int8 vectors too
+    int8Vectors = [];
+    quantizationEnabled = false;
+    // OPTIMIZATION: Contiguous Int8 storage for cache-friendly batch distance calculations
+    // Layout: [v0_d0...v0_dn, v1_d0...v1_dn, ...], offset: nodeId * dim
+    flatInt8Vectors = null;
+    flatInt8VectorsCapacity = 0;
+    // Reusable Int8 query buffer for quantized search — avoids allocation per query
+    queryInt8Buffer = null;
+    // Lazy loading support (v3+ format)
+    lazyLoadEnabled = false;
+    vectorOffsets = new Map(); // nodeId -> byte offset in file
+    vectorBuffer = null; // Cached buffer for lazy loading
+    vectorsLoaded = 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)
+    queryNormBuffer;
+    // 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
+    neighborSets = new Map();
+    // Construction-time quantization: use int8 search at layer 0 during bulk insert
+    // Set by addPointsBulkSync when useInt8Construction option is enabled
+    useInt8Construction = false;
+    constructionMode = false;
+    // Adaptive efSearch calibration stats
+    calibrationStats = null;
+    constructor(dimension, metric = '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
+        // Use SharedArrayBuffer when available so workers can read vectors without copying
+        this.flatVectorsCapacity = initialCapacity;
+        this.flatVectors = HNSWIndex.allocateFloat32(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, b) => {
+                const dot = dotProductFast(a, b);
+                const distance = 1 - dot;
+                return distance < 1e-10 ? 0 : distance;
+            };
+        }
+        else if (metric === 'euclidean') {
+            this.distanceFn = (a, b) => {
+                return Math.sqrt(l2SquaredFast(a, b));
+            };
+        }
+        else if (metric === 'dot_product') {
+            this.distanceFn = (a, b) => {
+                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
+     */
+    ensureCapacity(minCapacity) {
+        const projectedVectorBytes = minCapacity * this.dimension * 4;
+        if (minCapacity > HNSWIndex.MAX_NODE_SLOTS ||
+            !Number.isSafeInteger(projectedVectorBytes) ||
+            projectedVectorBytes > HNSWIndex.MAX_ARRAY_BUFFER_BYTES) {
+            throw new VectorDBError(`Node ID allocation would exceed supported index capacity (requested ${minCapacity} slots at dimension ${this.dimension}). Use dense/sequential IDs or smaller batches.`, 'VALIDATION_ERROR');
+        }
+        // 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 = HNSWIndex.allocateFloat32(newCapacity * this.dimension, this.useSharedMemory);
+            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 = HNSWIndex.allocateInt8(newCapacity * this.dimension, this.useSharedMemory);
+            newFlatInt8.set(this.flatInt8Vectors);
+            this.flatInt8Vectors = newFlatInt8;
+            this.flatInt8VectorsCapacity = newCapacity;
+        }
+    }
+    /**
+     * Set vector in flat storage
+     */
+    setFlatVector(nodeId, vector) {
+        const offset = nodeId * this.dimension;
+        this.flatVectors.set(vector, offset);
+    }
+    /**
+     * Set node by ID
+     */
+    setNode(node) {
+        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
+    batchNeighborIds = [];
+    batchDistances = [];
+    /**
+     * 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
+     */
+    calculateDistancesBatch(query, neighborIds, outDistances, count) {
+        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)
+     */
+    calculateDistancesBatchInt8(queryInt8, neighborIds, outDistances, count) {
+        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.
+     */
+    isVisited(id) {
+        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.
+     */
+    markVisited(id) {
+        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.
+     */
+    clearVisited() {
+        this.visitedGeneration++;
+        // Wrap around to avoid overflow (65535 is max for Uint16)
+        if (this.visitedGeneration > 65000) {
+            this.visitedArray.fill(0);
+            this.visitedGeneration = 1;
+        }
+    }
+    normalizeVector(vector) {
+        normalizeInPlace(vector);
+        return vector;
+    }
+    selectLevel() {
+        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, b) {
+        return this.distanceFn(a, b);
+    }
+    validateQueryVector(query, context = 'Query') {
+        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');
+            }
+        }
+    }
+    validateSearchParams(k, efSearch) {
+        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');
+        }
+    }
+    validateNodeId(id) {
+        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)
+     */
+    getNodeVector(nodeId) {
+        const node = this.nodes[nodeId];
+        if (!node)
+            return null;
+        if (this.lazyLoadEnabled && !this.vectorsLoaded.has(nodeId)) {
+            this.loadVector(nodeId);
+        }
+        return node.vector;
+    }
+    getLayerMaxConnections(layer) {
+        return layer === 0 ? this.M0 : this.M;
+    }
+    selectNeighbors(currentId, candidates, layer) {
+        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(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;
+    }
+    addBidirectionalConnection(fromId, toId, level) {
+        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.
+     */
+    pruneConnections(_nodeId, node, level, _maxConnections, neighborSet) {
+        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.
+     */
+    ensureHeapCapacity(ef) {
+        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.
+     */
+    searchLayer(query, nearest, layer, ef) {
+        // 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 = 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;
+    }
+    greedySearch(query, entryNode, level) {
+        // 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, vector, options) {
+        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, vector, options) {
+        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;
+        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(level + 1);
+        for (let i = 0; i <= level; i++) {
+            neighbors[i] = [];
+        }
+        const newNode = {
+            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, k, efSearch) {
+        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, k, efSearch) {
+        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(numQueries);
+            for (let i = 0; i < numQueries; i++) {
+                emptyResults[i] = [];
+            }
+            return emptyResults;
+        }
+        // Pre-allocate results array
+        const results = new Array(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, numQueries, k, efSearch) {
+        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
+    // ============================================
+    allocateAutoId() {
+        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) {
+        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, k = 10) {
+        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) {
+        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(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, options) {
+        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.
+     */
+    reorderForDiversity(points) {
+        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 = [];
+        const usedIndices = new Set();
+        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 = [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();
+        for (const pos of seedSamplePositions) {
+            seedOriginalIndices.add(sampleIndices[pos]);
+        }
+        // Build reordered array: seeds first, then remaining in original order
+        const reordered = [];
+        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, options) {
+        if (points.length === 0)
+            return;
+        // Validate whole batch first so invalid inputs don't leave partial inserts.
+        const seenIds = new Set();
+        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
+        }
+    }
+    /**
+     * Parallel bulk insertion using worker threads for search phase.
+     * Workers perform HNSW search (the expensive part), main thread adds connections.
+     * Uses SharedArrayBuffer for zero-copy vector sharing with workers.
+     *
+     * @param points Array of {id, vector} to insert
+     * @param pool WorkerPool instance (caller manages lifecycle)
+     * @param options.seedFraction Fraction of points to insert sequentially as seed (default: 0.1)
+     * @param options.batchSize Points per parallel batch (default: 200). Larger = faster but lower recall.
+     *   200: ~10x speedup, ~96% recall. 50: ~1.5x speedup, ~97% recall.
+     * @param options.resyncInterval Full re-sync worker graph every N batches (default: 100)
+     * @param options.repair Run 1-hop neighbor expansion after build to improve recall (default: false)
+     * @param options.skipNormalization Skip vector normalization
+     */
+    async addPointsBulkParallel(points, pool, options) {
+        if (points.length === 0)
+            return;
+        const seedFraction = options?.seedFraction ?? 0.1;
+        const batchSize = options?.batchSize ?? 200;
+        const resyncInterval = options?.resyncInterval ?? 100;
+        const doRepair = options?.repair ?? false;
+        const skipNorm = options?.skipNormalization;
+        // Validate whole batch first
+        const seenIds = new Set();
+        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');
+                }
+            }
+        }
+        // Pre-normalize all vectors if needed
+        const normalizedPoints = points.map(p => {
+            if (this.vectorsAreNormalized && !skipNorm) {
+                const v = new Float32Array(p.vector);
+                normalizeInPlace(v);
+                return { id: p.id, vector: v };
+            }
+            return p;
+        });
+        // Phase 1: Sequential seed insertion
+        const seedSize = Math.min(Math.max(500, Math.floor(normalizedPoints.length * seedFraction)), normalizedPoints.length);
+        // Enable shared memory so ensureCapacity allocates SAB-backed arrays.
+        // Workers hold a reference to the SAB — regular ArrayBuffer can't be shared.
+        // Pre-allocate capacity for ALL points so SAB doesn't get replaced during construction.
+        this.enableSharedMemory();
+        const maxId = normalizedPoints.reduce((max, p) => Math.max(max, p.id), 0);
+        this.ensureCapacity(maxId + 1);
+        this.constructionMode = true;
+        this.neighborSets.clear();
+        try {
+            for (let i = 0; i < seedSize; i++) {
+                this.addPointSync(normalizedPoints[i].id, normalizedPoints[i].vector, { skipNormalization: true });
+            }
+            if (seedSize >= normalizedPoints.length)
+                return;
+            // Phase 2: Init workers with current graph + SAB vectors
+            // Workers get a view of the full-capacity SAB (pre-allocated above)
+            await pool.init(this);
+            // Phase 3: Process remaining points in parallel batches
+            let batchCount = 0;
+            for (let start = seedSize; start < normalizedPoints.length; start += batchSize) {
+                const end = Math.min(start + batchSize, normalizedPoints.length);
+                const batch = normalizedPoints.slice(start, end);
+                // Pre-assign levels for all points in batch
+                const levels = batch.map(() => this.selectLevel());
+                // Workers search for neighbors for each point in the batch
+                // Workers search for neighbors — efConstruction as both k and ef
+                // to get the full candidate list for neighbor selection
+                const searchPromises = batch.map(p => pool.search(p.vector, this.efConstruction, this.efConstruction)
+                    .then(results => [results]) // Wrap in layer array format
+                );
+                const allResults = await Promise.all(searchPromises);
+                // Track all nodes whose neighbor lists change (for incremental graph update)
+                const modifiedNodeIds = new Set();
+                // Main thread: create nodes and add connections
+                for (let i = 0; i < batch.length; i++) {
+                    const { id, vector } = batch[i];
+                    const level = levels[i];
+                    // Create node with empty neighbors
+                    const neighbors = new Array(level + 1);
+                    for (let l = 0; l <= level; l++)
+                        neighbors[l] = [];
+                    const newNode = { id, level, vector, neighbors };
+                    this.setNode(newNode);
+                    // Keep quantized representation in sync
+                    if (this.quantizationEnabled && this.scalarQuantizer) {
+                        this.int8Vectors[id] = this.scalarQuantizer.quantize(vector);
+                        if (this.flatInt8Vectors) {
+                            this.scalarQuantizer.quantizeInto(vector, this.flatInt8Vectors, id * this.dimension);
+                        }
+                    }
+                    // Layer 0: use worker search results
+                    const l0Results = allResults[i][0] || [];
+                    const l0Neighbors = this.selectNeighbors(id, l0Results, 0);
+                    modifiedNodeIds.add(id);
+                    for (const nid of l0Neighbors) {
+                        this.addBidirectionalConnection(id, nid, 0);
+                        modifiedNodeIds.add(nid); // existing node got new connection
+                    }
+                    // Higher layers: search sequentially in main thread (rare: ~6% of nodes)
+                    if (level > 0) {
+                        let currentEntryPoint = this.nodes[this.entryPointId];
+                        let currentBest = {
+                            id: currentEntryPoint.id,
+                            distance: this.calculateDistance(vector, currentEntryPoint.vector)
+                        };
+                        // Greedy descent to level+1
+                        for (let l = this.maxLevel; l > level; l--) {
+                            const result = this.greedySearch(vector, currentEntryPoint, l);
+                            if (result.distance < currentBest.distance) {
+                                currentBest = result;
+                                currentEntryPoint = this.nodes[currentBest.id];
+                            }
+                        }
+                        // Search and connect at each layer from level to 1 (layer 0 already done)
+                        for (let l = Math.min(level, this.maxLevel); l >= 1; l--) {
+                            const searchResults = this.searchLayer(vector, currentBest, l, this.efConstruction);
+                            const layerNeighbors = this.selectNeighbors(id, searchResults, l);
+                            for (const nid of layerNeighbors) {
+                                this.addBidirectionalConnection(id, nid, l);
+                                modifiedNodeIds.add(nid);
+                            }
+                            if (searchResults.length > 0) {
+                                currentBest = searchResults[0];
+                            }
+                        }
+                    }
+                    // Update entry point if new level is higher
+                    if (level > this.maxLevel) {
+                        this.maxLevel = level;
+                        this.entryPointId = id;
+                    }
+                }
+                batchCount++;
+                // Send incremental graph update: ALL modified nodes (new + existing with new connections)
+                const graphUpdate = [];
+                for (const nid of modifiedNodeIds) {
+                    const node = this.nodes[nid];
+                    if (node) {
+                        graphUpdate.push({ id: nid, neighbors: node.neighbors });
+                    }
+                }
+                pool.broadcastGraphUpdate(graphUpdate, this.entryPointId, this.maxLevel);
+                // Full re-sync periodically for accumulated neighbor changes
+                // (bidirectional connections modify existing nodes' neighbor lists)
+                if (batchCount % resyncInterval === 0 && start + batchSize < normalizedPoints.length) {
+                    pool.destroy();
+                    await pool.init(this);
+                }
+            }
+            // Phase 4 (optional): Repair pass — 1-hop neighbor expansion to improve edges
+            if (doRepair) {
+                this.repairGraphConnections(normalizedPoints.map(p => p.id));
+            }
+        }
+        finally {
+            this.constructionMode = false;
+            this.neighborSets.clear();
+        }
+    }
+    /**
+     * Repair graph connections via 1-hop neighbor expansion.
+     * For each node, check if any neighbor-of-neighbor is closer than current neighbors.
+     * This is O(N * M0^2) distance computations — much cheaper than re-searching.
+     * Two passes catches transitive improvements.
+     */
+    repairGraphConnections(nodeIds) {
+        const maxConn = this.M0;
+        for (let pass = 0; pass < 2; pass++) {
+            for (const id of nodeIds) {
+                const node = this.nodes[id];
+                if (!node || !node.neighbors[0] || node.neighbors[0].length === 0)
+                    continue;
+                // Collect candidates: current neighbors + their neighbors (1-hop expansion)
+                const seen = new Set();
+                seen.add(id);
+                const candidates = [];
+                for (const nid of node.neighbors[0]) {
+                    if (!seen.has(nid)) {
+                        seen.add(nid);
+                        const nnode = this.nodes[nid];
+                        if (nnode) {
+                            candidates.push({
+                                id: nid,
+                                distance: this.calculateDistance(node.vector, nnode.vector)
+                            });
+                            // 1-hop: check neighbor's neighbors
+                            for (const nnid of nnode.neighbors[0]) {
+                                if (!seen.has(nnid)) {
+                                    seen.add(nnid);
+                                    const nnnode = this.nodes[nnid];
+                                    if (nnnode) {
+                                        candidates.push({
+                                            id: nnid,
+                                            distance: this.calculateDistance(node.vector, nnnode.vector)
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                // Select best neighbors from expanded candidate set
+                candidates.sort((a, b) => a.distance - b.distance);
+                const oldNeighborSet = new Set(node.neighbors[0]);
+                const newNeighbors = candidates.slice(0, maxConn).map(c => c.id);
+                // Check if anything changed
+                let changed = false;
+                if (newNeighbors.length !== node.neighbors[0].length) {
+                    changed = true;
+                }
+                else {
+                    for (const nid of newNeighbors) {
+                        if (!oldNeighborSet.has(nid)) {
+                            changed = true;
+                            break;
+                        }
+                    }
+                }
+                if (changed) {
+                    node.neighbors[0] = newNeighbors;
+                    // Add reverse connections for newly added neighbors
+                    for (const nid of newNeighbors) {
+                        if (!oldNeighborSet.has(nid)) {
+                            const neighbor = this.nodes[nid];
+                            if (neighbor && neighbor.neighbors[0] && !neighbor.neighbors[0].includes(id)) {
+                                if (neighbor.neighbors[0].length < maxConn) {
+                                    neighbor.neighbors[0].push(id);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Clear construction-time data structures to free memory.
+     * Called automatically after addPointsBulk(), but can be called
+     * manually if needed.
+     */
+    clearConstructionCache() {
+        this.constructionMode = false;
+        this.neighborSets.clear();
+    }
+    // Format version constants
+    static MAGIC = 0x484E5357; // "HNSW" in ASCII (big-endian: 0x48='H', 0x4E='N', 0x53='S', 0x57='W')
+    static FORMAT_VERSION = 3; // v3: vector offset index for lazy loading
+    static HEADER_SIZE = 40; // 4 (magic) + 4 (version) + 28 (existing header) + 4 (vectorDataOffset)
+    static ensureReadable(bufferLength, offset, bytes, context) {
+        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');
+        }
+    }
+    static wrapDeserializeError(error) {
+        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)
+     */
+    getNodesArray() {
+        const result = [];
+        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.
+     */
+    /**
+     * Convert flat vector storage to SharedArrayBuffer for zero-copy worker sharing.
+     * Called automatically by addPointsBulkParallel. Can also be called before WorkerPool.init()
+     * to enable zero-copy search dispatch.
+     */
+    enableSharedMemory() {
+        if (this.useSharedMemory)
+            return; // Already enabled
+        if (typeof SharedArrayBuffer === 'undefined')
+            return; // Not available
+        this.useSharedMemory = true;
+        // Migrate flatVectors to SAB
+        if (!(this.flatVectors.buffer instanceof SharedArrayBuffer)) {
+            const sabFloat = new Float32Array(new SharedArrayBuffer(this.flatVectorsCapacity * this.dimension * 4));
+            sabFloat.set(this.flatVectors);
+            this.flatVectors = sabFloat;
+        }
+        // Migrate flatInt8Vectors to SAB if present
+        if (this.flatInt8Vectors && !(this.flatInt8Vectors.buffer instanceof SharedArrayBuffer)) {
+            const sabInt8 = new Int8Array(new SharedArrayBuffer(this.flatInt8VectorsCapacity * this.dimension));
+            sabInt8.set(this.flatInt8Vectors);
+            this.flatInt8Vectors = sabInt8;
+        }
+    }
+    getSharedSearchData() {
+        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;
+        }
+        // When backed by SharedArrayBuffer, share the FULL capacity buffer (zero-copy).
+        // Workers get a view into the same memory, including space for new nodes added later.
+        // For regular ArrayBuffer, copy only the used portion.
+        const usedLength = this.nodeCount * this.dimension;
+        let flatVectors;
+        if (this.flatVectors.buffer instanceof SharedArrayBuffer) {
+            // Share full capacity — allows workers to see nodes added after init
+            flatVectors = new Float32Array(this.flatVectors.buffer, 0, this.flatVectorsCapacity * this.dimension);
+        }
+        else {
+            // Fallback: copy if not SharedArrayBuffer
+            flatVectors = new Float32Array(this.flatVectors.buffer.slice(0, usedLength * 4));
+        }
+        // Share int8 vectors if quantization is enabled
+        let flatInt8Vectors = null;
+        let quantizationParams = null;
+        if (this.quantizationEnabled && this.flatInt8Vectors) {
+            if (this.flatInt8Vectors.buffer instanceof SharedArrayBuffer) {
+                flatInt8Vectors = new Int8Array(this.flatInt8Vectors.buffer, 0, this.flatInt8VectorsCapacity * this.dimension);
+            }
+            else {
+                flatInt8Vectors = new Int8Array(this.flatInt8Vectors.buffer.slice(0, usedLength));
+            }
+            if (this.scalarQuantizer) {
+                quantizationParams = this.scalarQuantizer.getParams();
+            }
+        }
+        return {
+            flatVectors,
+            flatInt8Vectors,
+            dimension: this.dimension,
+            nodeCount: this.nodeCount,
+            metric: this.metric,
+            entryPointId: this.entryPointId,
+            maxLevel: this.maxLevel,
+            M: this.M,
+            M0: this.M0,
+            graphData,
+            nodeLevels,
+            quantizationEnabled: this.quantizationEnabled,
+            quantizationParams,
+        };
+    }
+    /**
+     * Serialize graph structure (neighbor lists) into a compact ArrayBuffer.
+     * Format per node: [numLayers:uint8] [numNeighbors:uint16, neighborId:uint32...] per layer
+     */
+    serializeGraphStructure() {
+        // 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() {
+        if (this.nodeCount === 0 || this.entryPointId === -1) {
+            return new Map();
+        }
+        const dim = this.dimension;
+        const oldToNew = new Map();
+        const visited = new Set();
+        const queue = [];
+        // 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(newId);
+        const newFlatVectors = HNSWIndex.allocateFloat32(Math.max(newId, this.flatVectorsCapacity) * dim, this.useSharedMemory);
+        let newFlatInt8Vectors = null;
+        let newInt8Vectors = [];
+        if (this.quantizationEnabled && this.flatInt8Vectors) {
+            newFlatInt8Vectors = HNSWIndex.allocateInt8(Math.max(newId, this.flatInt8VectorsCapacity) * dim, this.useSharedMemory);
+            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 = [];
+            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() {
+        // 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();
+        for (let i = 0; i < nodesArray.length; i++) {
+            idToIndex.set(nodesArray[i].id, i);
+        }
+        // Pre-encode all neighbor lists with delta encoding
+        const encodedNeighbors = [];
+        let totalNeighborBytes = 0;
+        for (const node of nodesArray) {
+            const nodeEncodings = [];
+            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, options) {
+        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, context) => {
+                HNSWIndex.ensureReadable(buffer.byteLength, offset, bytes, context);
+            };
+            const readUint32 = (context) => {
+                ensureReadable(4, context);
+                const value = view.getUint32(offset, true);
+                offset += 4;
+                return value;
+            };
+            const readInt32 = (context) => {
+                ensureReadable(4, context);
+                const value = view.getInt32(offset, true);
+                offset += 4;
+                return value;
+            };
+            const readFloat32 = (context) => {
+                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;
+            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 = new Array(nodeCount);
+            if (formatVersion >= 3) {
+                // V3 format: vectors at end, supports lazy loading
+                const nodeMetadata = [];
+                const neighborMetadata = [];
+                // 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 = [];
+                    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 = [];
+                for (let i = 0; i < nodeCount; i++) {
+                    const level = nodeMetadata[i].level;
+                    const neighbors = new Array(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 = {
+                            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 = { 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 = [];
+                const neighborMetadata = [];
+                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 = [];
+                    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(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 = { 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(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 = { 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) {
+        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) {
+        if (!this.lazyLoadEnabled)
+            return;
+        for (const nodeId of nodeIds) {
+            this.loadVector(nodeId);
+        }
+    }
+    /**
+     * Check if lazy loading is enabled
+     */
+    isLazyLoadEnabled() {
+        return this.lazyLoadEnabled;
+    }
+    /**
+     * Get lazy loading statistics
+     */
+    getLazyLoadStats() {
+        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) {
+        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) {
+        const file = Bun.file(filePath);
+        const buffer = await file.arrayBuffer();
+        return HNSWIndex.deserialize(buffer);
+    }
+    // Clean up resources
+    destroy() {
+        // Clear all nodes to free memory
+        this.nodes = [];
+        this.nodeCount = 0;
+        this.nextAutoId = 0;
+        this.flatVectors = new Float32Array(0);
+        this.flatVectorsCapacity = 0;
+        this.useSharedMemory = false;
+        // 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() {
+        // 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() {
+        return this.dimension;
+    }
+    getMetric() {
+        return this.metric;
+    }
+    getM() {
+        return this.M;
+    }
+    getEfConstruction() {
+        return this.efConstruction;
+    }
+    /**
+     * Get all vectors for brute-force search
+     */
+    getAllVectors() {
+        const result = new Map();
+        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() {
+        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 = [];
+        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 = HNSWIndex.allocateInt8(this.flatInt8VectorsCapacity * dim, this.useSharedMemory);
+        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() {
+        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, k, candidateMultiplier = 3, efSearch) {
+        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(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(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) {
+        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 = [];
+        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() {
+        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, k, baseEfSearch) {
+        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;
+        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.
+     */
+    searchLayerQuantized(query, nearest, layer, ef) {
+        // Quantize query once — reuse pre-allocated buffer when available
+        let int8Query = 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;
+                    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 = 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() {
+        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)'
+        };
+    }
+}
+//# sourceMappingURL=HNSWIndex.js.map