verso-db 0.3.0 → 0.4.0

package/dist/HNSWIndex.js

@@ -11,6 +11,7 @@ export class HNSWIndex {
     static MAX_NODE_ID = HNSWIndex.MISSING_ID_SENTINEL - 1;
     static MAX_ARRAY_BUFFER_BYTES = 0x7FFFFFFF;
     static MAX_NODE_SLOTS = 50_000_000;
+    static MAX_SERIALIZED_LEVEL = 31;
     /**
      * Allocate a Float32Array backed by SharedArrayBuffer when available.
      * This allows workers to read vector data without copying.
@@ -69,6 +70,7 @@ export class HNSWIndex {
     vectorsAreNormalized = false;
     // Cached distance function to avoid switch overhead
     distanceFn;
+    random;
     // Quantization support for 3-4x faster search with Int8
     scalarQuantizer = null;
     // OPTIMIZATION: Use array instead of Map for int8 vectors too
@@ -98,7 +100,7 @@ export class HNSWIndex {
     constructionMode = false;
     // Adaptive efSearch calibration stats
     calibrationStats = null;
-    constructor(dimension, metric = 'cosine', M = 24, efConstruction = 200) {
+    constructor(dimension, metric = 'cosine', M = 24, efConstruction = 200, random = Math.random) {
         if (dimension <= 0 || !Number.isInteger(dimension)) {
             throw new VectorDBError(`Invalid dimension: must be a positive integer, got ${dimension}`, 'VALIDATION_ERROR');
         }
@@ -108,8 +110,12 @@ export class HNSWIndex {
         if (efConstruction <= 0 || !Number.isInteger(efConstruction)) {
             throw new VectorDBError(`Invalid efConstruction parameter: must be a positive integer, got ${efConstruction}`, 'VALIDATION_ERROR');
         }
+        if (typeof random !== 'function') {
+            throw new VectorDBError('Invalid random source: must be a function returning a number in [0, 1)', 'VALIDATION_ERROR');
+        }
         this.dimension = dimension;
         this.metric = metric;
+        this.random = random;
         this.M = M;
         this.M0 = M * 2;
         this.efConstruction = efConstruction;
@@ -437,8 +443,18 @@ export class HNSWIndex {
         normalizeInPlace(vector);
         return vector;
     }
+    randomFloat() {
+        const value = this.random();
+        if (!Number.isFinite(value))
+            return 0;
+        if (value <= 0)
+            return 0;
+        if (value >= 1)
+            return 1 - Number.EPSILON;
+        return value;
+    }
     selectLevel() {
-        const r = Math.random() || Number.MIN_VALUE;
+        const r = this.randomFloat() || Number.MIN_VALUE;
         const level = Math.floor(-Math.log(r) * this.levelMult);
         return Math.max(0, Math.min(level, this.maxLayers - 1));
     }
@@ -780,23 +796,10 @@ export class HNSWIndex {
         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;
-        }
+        // Always take ownership of vector data. Reusing caller-owned
+        // Float32Arrays lets later external mutation diverge node.vector from the
+        // flat vector store and corrupt search behavior.
+        let floatVector = new Float32Array(vector);
         if (floatVector.length !== this.dimension) {
             throw new VectorDBError(`Vector dimension ${floatVector.length} does not match expected ${this.dimension}`, 'DIMENSION_MISMATCH');
         }
@@ -1121,7 +1124,7 @@ export class HNSWIndex {
         const sampleIndices = [];
         const usedIndices = new Set();
         while (sampleIndices.length < sampleSize) {
-            const idx = Math.floor(Math.random() * n);
+            const idx = Math.floor(this.randomFloat() * n);
             if (!usedIndices.has(idx)) {
                 usedIndices.add(idx);
                 sampleIndices.push(idx);
@@ -1303,12 +1306,11 @@ export class HNSWIndex {
         }
         // Pre-normalize all vectors if needed
         const normalizedPoints = points.map(p => {
+            const vector = new Float32Array(p.vector);
             if (this.vectorsAreNormalized && !skipNorm) {
-                const v = new Float32Array(p.vector);
-                normalizeInPlace(v);
-                return { id: p.id, vector: v };
+                normalizeInPlace(vector);
             }
-            return p;
+            return { id: p.id, vector };
         });
         // Phase 1: Sequential seed insertion
         const seedSize = Math.min(Math.max(500, Math.floor(normalizedPoints.length * seedFraction)), normalizedPoints.length);
@@ -2114,6 +2116,18 @@ export class HNSWIndex {
             const entryPointId = readInt32('entryPointId');
             const nodeCount = readUint32('nodeCount');
             const vectorByteLength = dimension * 4;
+            if (nodeCount > HNSWIndex.MAX_NODE_SLOTS) {
+                throw new VectorDBError(`Corrupt HNSW data: node count ${nodeCount} exceeds maximum supported ${HNSWIndex.MAX_NODE_SLOTS}`, 'CORRUPT_INDEX');
+            }
+            if (maxLevel < -1 || maxLevel > HNSWIndex.MAX_SERIALIZED_LEVEL) {
+                throw new VectorDBError(`Corrupt HNSW data: invalid maxLevel ${maxLevel}`, 'CORRUPT_INDEX');
+            }
+            if (nodeCount === 0 && (entryPointId !== -1 || maxLevel !== -1)) {
+                throw new VectorDBError('Corrupt HNSW data: empty index has non-empty entry point metadata', 'CORRUPT_INDEX');
+            }
+            if (nodeCount > 0 && (entryPointId < 0 || maxLevel < 0)) {
+                throw new VectorDBError('Corrupt HNSW data: populated index has missing entry point metadata', 'CORRUPT_INDEX');
+            }
             // V3+ has vectorDataOffset in header
             let vectorDataOffset = 0;
             if (formatVersion >= 3) {
@@ -2126,6 +2140,41 @@ export class HNSWIndex {
             index.maxLevel = maxLevel;
             index.entryPointId = entryPointId;
             const indexToId = new Array(nodeCount);
+            const seenNodeIds = new Set();
+            let observedMaxLevel = -1;
+            const validateSerializedNode = (id, level, nodeIndex) => {
+                if (id > HNSWIndex.MAX_NODE_ID) {
+                    throw new VectorDBError(`Corrupt HNSW data: node ${nodeIndex} has reserved or unsupported ID ${id}`, 'CORRUPT_INDEX');
+                }
+                if (level > HNSWIndex.MAX_SERIALIZED_LEVEL || level > maxLevel) {
+                    throw new VectorDBError(`Corrupt HNSW data: node ${nodeIndex} has invalid level ${level}`, 'CORRUPT_INDEX');
+                }
+                if (seenNodeIds.has(id)) {
+                    throw new VectorDBError(`Corrupt HNSW data: duplicate node ID ${id}`, 'CORRUPT_INDEX');
+                }
+                seenNodeIds.add(id);
+                if (level > observedMaxLevel)
+                    observedMaxLevel = level;
+            };
+            const validateNeighborList = (nodeId, layer, neighbors) => {
+                const maxConnections = layer === 0 ? M * 2 : M;
+                if (neighbors.length > maxConnections) {
+                    throw new VectorDBError(`Corrupt HNSW data: node ${nodeId} layer ${layer} has ${neighbors.length} neighbors, maximum is ${maxConnections}`, 'CORRUPT_INDEX');
+                }
+                const seenNeighbors = new Set();
+                for (const neighborId of neighbors) {
+                    if (!seenNodeIds.has(neighborId)) {
+                        throw new VectorDBError(`Corrupt HNSW data: node ${nodeId} references missing neighbor ${neighborId}`, 'CORRUPT_INDEX');
+                    }
+                    if (neighborId === nodeId) {
+                        throw new VectorDBError(`Corrupt HNSW data: node ${nodeId} references itself as a neighbor`, 'CORRUPT_INDEX');
+                    }
+                    if (seenNeighbors.has(neighborId)) {
+                        throw new VectorDBError(`Corrupt HNSW data: node ${nodeId} has duplicate neighbor ${neighborId}`, 'CORRUPT_INDEX');
+                    }
+                    seenNeighbors.add(neighborId);
+                }
+            };
             if (formatVersion >= 3) {
                 // V3 format: vectors at end, supports lazy loading
                 const nodeMetadata = [];
@@ -2134,6 +2183,7 @@ export class HNSWIndex {
                 for (let i = 0; i < nodeCount; i++) {
                     const id = readUint32(`node ${i} id`);
                     const level = readUint32(`node ${i} level`);
+                    validateSerializedNode(id, level, i);
                     indexToId[i] = id;
                     nodeMetadata.push({ id, level });
                 }
@@ -2172,6 +2222,7 @@ export class HNSWIndex {
                             }
                             return indexToId[idx];
                         });
+                        validateNeighborList(nodeMetadata[i].id, l, neighbors[l]);
                     }
                     nodeNeighbors.push(neighbors);
                 }
@@ -2236,6 +2287,7 @@ export class HNSWIndex {
                 for (let i = 0; i < nodeCount; i++) {
                     const id = readUint32(`node ${i} id`);
                     const level = readUint32(`node ${i} level`);
+                    validateSerializedNode(id, level, i);
                     indexToId[i] = id;
                     const vector = new Float32Array(dimension);
                     for (let j = 0; j < dimension; j++) {
@@ -2275,6 +2327,7 @@ export class HNSWIndex {
                             }
                             return indexToId[idx];
                         });
+                        validateNeighborList(id, l, neighbors[l]);
                     }
                     const node = { id, level, vector, neighbors };
                     index.setNode(node);
@@ -2285,6 +2338,7 @@ export class HNSWIndex {
                 for (let i = 0; i < nodeCount; i++) {
                     const id = readUint32(`node ${i} id`);
                     const level = readUint32(`node ${i} level`);
+                    validateSerializedNode(id, level, i);
                     indexToId[i] = id;
                     const vector = new Float32Array(dimension);
                     for (let j = 0; j < dimension; j++) {
@@ -2310,9 +2364,20 @@ export class HNSWIndex {
                             }
                             node.neighbors[l][j] = indexToId[neighborIndex];
                         }
+                        validateNeighborList(node.id, l, node.neighbors[l]);
                     }
                 }
             }
+            if (nodeCount > 0 && observedMaxLevel !== maxLevel) {
+                throw new VectorDBError(`Corrupt HNSW data: maxLevel ${maxLevel} does not match highest node level ${observedMaxLevel}`, 'CORRUPT_INDEX');
+            }
+            if (nodeCount > 0 && !seenNodeIds.has(entryPointId)) {
+                throw new VectorDBError(`Corrupt HNSW data: entry point ${entryPointId} is not present in node table`, 'CORRUPT_INDEX');
+            }
+            const entryPoint = nodeCount > 0 ? index.nodes[entryPointId] : undefined;
+            if (entryPoint && entryPoint.level !== maxLevel) {
+                throw new VectorDBError(`Corrupt HNSW data: entry point level ${entryPoint.level} does not match maxLevel ${maxLevel}`, 'CORRUPT_INDEX');
+            }
             return index;
         }
         catch (error) {
@@ -2479,7 +2544,7 @@ export class HNSWIndex {
                 continue;
             const vector = this.getNodeVector(node.id);
             if (vector) {
-                result.set(node.id, vector);
+                result.set(node.id, new Float32Array(vector));
             }
         }
         return result;