@flaxia/node 0.3.7 → 0.5.1

package/dist/vector-store/HNSWIndex.d.ts

@@ -9,6 +9,19 @@ export interface NodeExport {
     level: number;
     neighbors: Record<number, number[]>;
 }
+/**
+ * Storage/robustness limits for a node's index.
+ *
+ * - `MAX_HNSW_NODES` bounds how many vectors a volunteer node persists (the
+ *   IndexedDB graph is writable by any same-origin script, so a corrupted or
+ *   hostile dump must not be able to grow the in-memory graph without limit).
+ * - `MAX_HNSW_LEVEL` matches `randomLevel()`; an imported level above it would
+ *   otherwise be used to index `neighbors` maps that were never created.
+ * - `MAX_HNSW_NEIGHBORS_PER_LEVEL` bounds adjacency lists read back from disk.
+ */
+export declare const MAX_HNSW_NODES = 100000;
+export declare const MAX_HNSW_LEVEL = 16;
+export declare const MAX_HNSW_NEIGHBORS_PER_LEVEL = 1024;
 export declare class HNSWIndex {
     private dimensions;
     private metric;
@@ -20,14 +33,31 @@ export declare class HNSWIndex {
     private nextNodeId;
     private maxLevel;
     constructor(dimensions: number, metric?: 'cosine' | 'l2', M?: number, efConstruction?: number);
+    /** Vector width this index was built for. */
+    get dimensionsValue(): number;
     insert(docId: string, vector: Float32Array): void;
     search(query: Float32Array, k: number): SearchResult[];
     private searchLayer;
     private selectNeighbors;
+    /**
+     * Distance between two vectors. Dimensions must match: iterating `a.length`
+     * over a shorter `b` used to return `NaN` (or a silently truncated score),
+     * which corrupted search results instead of failing.
+     */
     private distance;
     private randomLevel;
     size(): number;
     exportNodes(): Map<number, NodeExport>;
+    /**
+     * Rebuild the graph from persisted/imported nodes.
+     *
+     * The input comes from IndexedDB, which any same-origin script can write, so
+     * it is validated before it can reach the search path: levels must be within
+     * `MAX_HNSW_LEVEL`, adjacency must reference nodes that exist in the same
+     * dump (and stay within the per-level cap), every vector must be a finite
+     * Float32Array of the index's dimension and every node needs one. A bad dump
+     * throws instead of producing an index that returns NaN distances.
+     */
     importNodes(exported: NodeExport[], vectors: Map<number, Float32Array>): void;
 }
 //# sourceMappingURL=HNSWIndex.d.ts.map

package/dist/vector-store/HNSWIndex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HNSWIndex.d.ts","sourceRoot":"","sources":["../../src/vector-store/HNSWIndex.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACrC;AAED,qBAAa,SAAS;IAQlB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,CAAC;IACT,OAAO,CAAC,cAAc;IAVxB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAK;gBAGX,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,QAAQ,GAAG,IAAe,EAClC,CAAC,GAAE,MAAW,EACd,cAAc,GAAE,MAAY;IAGtC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAuEjD,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE;IAmCtD,OAAO,CAAC,WAAW;IA4DnB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,QAAQ;IAkBhB,OAAO,CAAC,WAAW;IAMnB,IAAI,IAAI,MAAM;IAEd,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAiBtC,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,IAAI;CAsB9E"}
+{"version":3,"file":"HNSWIndex.d.ts","sourceRoot":"","sources":["../../src/vector-store/HNSWIndex.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,SAAU,CAAC;AACtC,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,qBAAa,SAAS;IAQlB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,CAAC;IACT,OAAO,CAAC,cAAc;IAVxB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAK;gBAGX,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,QAAQ,GAAG,IAAe,EAClC,CAAC,GAAE,MAAW,EACd,cAAc,GAAE,MAAY;IAGtC,6CAA6C;IAC7C,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAgFjD,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE;IAmCtD,OAAO,CAAC,WAAW;IA4DnB,OAAO,CAAC,eAAe;IAIvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAqBhB,OAAO,CAAC,WAAW;IAMnB,IAAI,IAAI,MAAM;IAEd,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAiBtC;;;;;;;;;OASG;IACH,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,IAAI;CA8F9E"}

package/dist/vector-store/VectorStoreEngine.d.ts

@@ -1,4 +1,34 @@
 import type { VectorStorePayload, VectorStoreResult, VectorQueryPayload, VectorQueryResult } from '@flaxia/sdk';
+/**
+ * Vector shape limits.
+ *
+ * `payload.vector` / `payload.queryVector` are typed as `number[]` but arrive
+ * from the network as arbitrary JSON: a plain array-like such as
+ * `{ length: 2 ** 30 }` would otherwise make `new Float32Array(value)` attempt a
+ * ~4 GiB allocation *before* any dimension check. Every value is therefore
+ * validated as a real, bounded array first.
+ */
+export declare const MAX_VECTOR_DIMENSIONS = 4096;
+/** Upper bound for the total number of elements in one request. */
+export declare const MAX_VECTOR_ELEMENTS = 1048576;
+/** Upper bound for the number of vectors persisted on this node. */
+export declare const MAX_STORED_VECTORS = 100000;
+/** Largest accepted `topK` for a query. */
+export declare const MAX_QUERY_TOP_K = 1000;
+/**
+ * Validate a vector-ish value and return its length without allocating.
+ *
+ * Rejects: non-arrays, array-likes (`{length: n}`), `arguments`-style objects,
+ * non-integer/negative/NaN lengths, lengths above `maxDimensions` and element
+ * counts above `maxElements`.
+ */
+export declare function assertVectorShape(value: unknown, name: string, maxDimensions?: number, maxElements?: number): number;
+/**
+ * Validate a shard key with `Number.isInteger`. `parseInt('not-a-number')` is
+ * `NaN`, and both `NaN < start` and `NaN > end` are false, so the old check let
+ * non-numeric keys through the shard gate.
+ */
+export declare function assertShardKey(value: unknown, rangeStart: number, rangeEnd: number): number;
 interface VectorRecord {
     docId: string;
     vector: Float32Array;
@@ -23,6 +53,19 @@ export declare class VectorStoreEngine {
     getVector(docId: string): Promise<VectorRecord | undefined>;
     deleteVector(docId: string): Promise<void>;
     getVectorCount(): number;
+    /**
+     * Rebuild the in-memory graph from IndexedDB.
+     *
+     * The records are same-origin writable storage, so they are treated as
+     * untrusted: `importNodes` re-validates levels, adjacency and vector
+     * dimensions and throws on a corrupted graph instead of silently building an
+     * index that later produces NaN distances.
+     *
+     * Residual risk (documented, accepted for this workload): the persisted
+     * vectors and metadata are stored in plaintext in IndexedDB, so any script on
+     * the same origin can read them. They are node-local working data for the
+     * customer's own task, and the quota above bounds how much can be stored.
+     */
     private loadGraphFromDB;
     private saveGraphSnapshot;
 }

package/dist/vector-store/VectorStoreEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VectorStoreEngine.d.ts","sourceRoot":"","sources":["../../src/vector-store/VectorStoreEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAiDhH,UAAU,YAAY;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AASD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,SAAS,CAAyD;IAC1E,OAAO,CAAC,WAAW,CAAK;IAElB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB3B,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhE,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6B9D,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoB9D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAI3D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD,cAAc,IAAI,MAAM;YAIV,eAAe;YAsBf,iBAAiB;CAWhC"}
+{"version":3,"file":"VectorStoreEngine.d.ts","sourceRoot":"","sources":["../../src/vector-store/VectorStoreEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhH;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAC7C,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,SAAiB,CAAC;AACjD,2CAA2C;AAC3C,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,aAAa,SAAwB,EACrC,WAAW,SAAsB,GAChC,MAAM,CAqBR;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY3F;AAgDD,UAAU,YAAY;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AASD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,SAAS,CAAyD;IAC1E,OAAO,CAAC,WAAW,CAAK;IAElB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB3B,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhE,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwC9D,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA+B9D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAI3D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD,cAAc,IAAI,MAAM;IAIxB;;;;;;;;;;;;OAYG;YACW,eAAe;YA8Bf,iBAAiB;CAWhC"}

package/dist/vector-store/__tests__/HNSWIndex.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=HNSWIndex.test.d.ts.map

package/dist/vector-store/__tests__/HNSWIndex.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HNSWIndex.test.d.ts","sourceRoot":"","sources":["../../../src/vector-store/__tests__/HNSWIndex.test.ts"],"names":[],"mappings":""}

package/dist/vector-store/__tests__/VectorStoreEngine.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=VectorStoreEngine.test.d.ts.map

package/dist/vector-store/__tests__/VectorStoreEngine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorStoreEngine.test.d.ts","sourceRoot":"","sources":["../../../src/vector-store/__tests__/VectorStoreEngine.test.ts"],"names":[],"mappings":""}

package/dist/worker/__tests__/main.worker.abort.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.worker.abort.test.d.ts.map

package/dist/worker/__tests__/main.worker.abort.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.worker.abort.test.d.ts","sourceRoot":"","sources":["../../../src/worker/__tests__/main.worker.abort.test.ts"],"names":[],"mappings":""}

package/dist/worker/__tests__/main.worker.control.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.worker.control.test.d.ts.map

package/dist/worker/__tests__/main.worker.control.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.worker.control.test.d.ts","sourceRoot":"","sources":["../../../src/worker/__tests__/main.worker.control.test.ts"],"names":[],"mappings":""}