hyperspace-sdk-ts 3.1.2 → 3.1.3

package/README.md

@@ -1,6 +1,6 @@
 # HyperspaceDB TypeScript SDK
 
-Official TypeScript client for HyperspaceDB gRPC API v3.1.0.
+Official TypeScript client for HyperspaceDB gRPC API v3.1.1.
 
 Use this SDK for:
 - collection lifecycle management
@@ -144,9 +144,9 @@ const results = await client.searchText("How to use HyperspaceDB?", 10, "coll",
 });
 ```
 
-### Geometric Filters (New in v3.0)
+### Geometric Filters
 
-HyperspaceDB v3.0 introduces advanced spatial filters that run on the engine level:
+HyperspaceDB introduces advanced spatial filters that run on the engine level:
 
 ```ts
 // 1. Proximity Search (Ball)
@@ -323,7 +323,7 @@ const syncedThought = CognitiveMath.contextResonance(thought, globalContext, 0.5
 const relation = await client.predictRelation(1, 2);
 ```
 
-## Implicit Graph Engine (v3.2)
+## Implicit Graph Engine (v3.1.1)
 
 HyperspaceDB treats your vectors as nodes in a dynamic graph. Relationships are inferred from the geometry:
 - **Lorentz / Poincare**: Hierarchy and subsumption (light cones).
@@ -420,3 +420,58 @@ const vector = await embedder.encode("my text");
 All methods reject on transport/protocol errors. Targets gRPC data plane operations.
 For control plane endpoints (`/api/*`), use regular HTTP requests to the server's HTTP port.
 
+## Zero-Knowledge Client-Side Encryption (ZK-Privacy)
+
+HyperspaceDB v3.1.1 introduces Zero-Knowledge client-side encryption (ZK-Privacy). All private data (vectors, metadata, payloads) are encrypted/obfuscated *before* they leave the client. The database server never sees the raw vectors or plaintext data, ensuring maximum security even in public or untrusted DePIN environments.
+
+### Key Features
+1. **Vector Projection**: High-dimensional vectors are projected using a deterministic orthogonal matrix (or Lorentz boost matrix for hyperbolic spaces) generated from the collection key. This preserves distances (L2, Cosine, Lorentz) while hiding the vector coordinates.
+2. **Anisotropic Noise Injection**: Injecting subtle deterministic noise into the vectors to prevent reconstruction attacks.
+3. **Payload Encryption**: Sidecar payloads are encrypted client-side using AES-256-GCM before being sent to the database.
+4. **Metadata Hashing**: Metadata keys and values are obfuscated using HMAC-SHA256.
+
+### Usage Example
+
+```ts
+import { HyperspaceClient } from "hyperspace-sdk-ts";
+
+async function main() {
+  const client = new HyperspaceClient("localhost:50051", "I_LOVE_HYPERSPACEDB");
+  
+  const collection = "encrypted_docs";
+  const secretKey = "my-super-secret-key";
+
+  // Register collection key to enable automatic client-side encryption/decryption
+  // noiseSigma defaults to 0.02 (2% anisotropic noise)
+  client.registerCollectionKey(collection, secretKey, "cosine", 0.02);
+
+  // 1. Insert vector (will be projected, noise injected, payload encrypted, metadata hashed)
+  await client.insert(
+    1, 
+    [0.1, 0.2, 0.3], 
+    { category: "confidential" }, 
+    collection,
+    undefined,
+    undefined,
+    Buffer.from("This is a highly secret document payload", "utf-8")
+  );
+
+  // 2. Search (search vector is projected and noise-injected; results are decrypted locally)
+  const results = await client.search([0.1, 0.2, 0.3], 5, collection, {
+    // Filters are automatically hashed client-side
+    filter: { category: "confidential" }
+  });
+
+  for (const res of results) {
+    console.log(`ID: ${res.id}, Distance: ${res.distance}`);
+    if (res.payload) {
+      console.log(`Decrypted Payload: ${Buffer.from(res.payload).toString("utf-8")}`);
+    }
+  }
+
+  client.close();
+}
+
+main().catch(console.error);
+```
+

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import * as grpc from '@grpc/grpc-js';
 import { DurabilityLevel, EventMessage } from './proto/hyperspace_pb';
 import * as hyperspace_pb from './proto/hyperspace_pb';
-export * as CognitiveMath from './math';
+export * as CognitiveMathExport from './math';
 export { TribunalContext } from './agents';
 export { DurabilityLevel };
 export type TypedMetadataValue = string | number | boolean;
@@ -140,12 +140,30 @@ export declare class HyperspaceClient {
     private host;
     private apiKey?;
     private userId?;
+    embedder?: {
+        encode: (text: string) => Promise<number[]> | number[];
+    };
+    private collectionKeys;
+    private encryptionContexts;
+    private collectionMetrics;
+    private collectionNoiseSigmas;
+    private collectionSchemas;
     private static toVectorList;
     private static toProtoMetadataValue;
     private static parseTypedMetadata;
     private toProtoFilter;
     constructor(host?: string, apiKey?: string, userId?: string);
-    createCollection(name: string, schema: CollectionSchema): Promise<boolean>;
+    registerCollectionKey(collectionName: string, key: string, metric?: string, noiseSigma?: number, schema?: CollectionSchema): void;
+    private deriveKeys;
+    private encryptPayload;
+    private decryptPayload;
+    private hashMetadataKey;
+    private hashMetadataValue;
+    private _getEncryptionContext;
+    private _projectSingleBlock;
+    private _projectCollectionVector;
+    private _encryptFilters;
+    createCollection(name: string, schema: CollectionSchema, encryptionKey?: string, noiseSigma?: number): Promise<boolean>;
     deleteCollection(name: string): Promise<boolean>;
     freezeCollection(name: string): Promise<string>;
     unfreezeCollection(name: string): Promise<string>;

package/dist/client.js

@@ -33,13 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HyperspaceClient = exports.HyperbolicMath = exports.DurabilityLevel = exports.TribunalContext = exports.CognitiveMath = void 0;
+exports.HyperspaceClient = exports.HyperbolicMath = exports.DurabilityLevel = exports.TribunalContext = exports.CognitiveMathExport = void 0;
 const grpc = __importStar(require("@grpc/grpc-js"));
 const hyperspace_grpc_pb_1 = require("./proto/hyperspace_grpc_pb");
 const hyperspace_pb_1 = require("./proto/hyperspace_pb");
 Object.defineProperty(exports, "DurabilityLevel", { enumerable: true, get: function () { return hyperspace_pb_1.DurabilityLevel; } });
 const hyperspace_pb = __importStar(require("./proto/hyperspace_pb")); // New, for direct access to types
-exports.CognitiveMath = __importStar(require("./math"));
+const CognitiveMath = __importStar(require("./math"));
+exports.CognitiveMathExport = __importStar(require("./math"));
 var agents_1 = require("./agents");
 Object.defineProperty(exports, "TribunalContext", { enumerable: true, get: function () { return agents_1.TribunalContext; } });
 exports.HyperbolicMath = {
@@ -292,6 +293,11 @@ class HyperspaceClient {
         return pf;
     }
     constructor(host = 'localhost:50051', apiKey, userId) {
+        this.collectionKeys = {};
+        this.encryptionContexts = {};
+        this.collectionMetrics = {};
+        this.collectionNoiseSigmas = {};
+        this.collectionSchemas = {};
         this.host = host;
         this.apiKey = apiKey;
         this.userId = userId;
@@ -313,8 +319,223 @@ class HyperspaceClient {
             this.metadata.add('x-hyperspace-user-id', userId);
         }
     }
+    registerCollectionKey(collectionName, key, metric = "l2", noiseSigma = 0.02, schema) {
+        this.collectionKeys[collectionName] = key;
+        this.collectionMetrics[collectionName] = metric;
+        this.collectionNoiseSigmas[collectionName] = noiseSigma;
+        if (schema) {
+            this.collectionSchemas[collectionName] = schema;
+        }
+        if (this.encryptionContexts[collectionName]) {
+            delete this.encryptionContexts[collectionName];
+        }
+    }
+    deriveKeys(password, collectionName) {
+        const crypto = require('crypto');
+        const salt = crypto.createHash('sha256').update(collectionName).digest();
+        const aesKey = crypto.pbkdf2Sync(password, salt, 100000, 32, 'sha256');
+        const hmacKey = crypto.pbkdf2Sync(password, salt, 100000, 32, 'sha256');
+        return { aesKey, hmacKey };
+    }
+    encryptPayload(plaintext, aesKey) {
+        const crypto = require('crypto');
+        const iv = crypto.randomBytes(12);
+        const pbkdf2Salt = crypto.randomBytes(16);
+        const derivedAesKey = crypto.pbkdf2Sync(aesKey, pbkdf2Salt, 100000, 32, 'sha256');
+        const cipherPayload = crypto.createCipheriv('aes-256-gcm', derivedAesKey, iv);
+        const encryptedPayload = Buffer.concat([cipherPayload.update(plaintext), cipherPayload.final()]);
+        const payloadTag = cipherPayload.getAuthTag();
+        return Buffer.concat([pbkdf2Salt, iv, encryptedPayload, payloadTag]);
+    }
+    decryptPayload(data, aesKey) {
+        const crypto = require('crypto');
+        if (data.length < 16 + 12 + 16) {
+            throw new Error("Invalid encrypted payload size");
+        }
+        const pbkdf2Salt = data.subarray(0, 16);
+        const iv = data.subarray(16, 28);
+        const ciphertext = data.subarray(28, data.length - 16);
+        const tag = data.subarray(data.length - 16);
+        const derivedAesKey = crypto.pbkdf2Sync(aesKey, pbkdf2Salt, 100000, 32, 'sha256');
+        const decipher = crypto.createDecipheriv('aes-256-gcm', derivedAesKey, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    hashMetadataKey(key, hmacKey) {
+        const crypto = require('crypto');
+        const hash = crypto.createHmac('sha256', hmacKey).update(key).digest('hex');
+        return "tag_" + hash.slice(0, 16);
+    }
+    hashMetadataValue(value, hmacKey) {
+        const crypto = require('crypto');
+        const hash = crypto.createHmac('sha256', hmacKey).update(value).digest('hex');
+        return "val_" + hash;
+    }
+    async _getEncryptionContext(collection, vectorDim, metric = "l2") {
+        if (!collection)
+            return null;
+        const key = this.collectionKeys[collection];
+        if (!key)
+            return null;
+        if (!this.collectionSchemas[collection]) {
+            try {
+                const stats = await this.getCollectionStats(collection);
+                if (stats && stats.schema) {
+                    this.collectionSchemas[collection] = stats.schema;
+                }
+            }
+            catch (e) { }
+        }
+        if (!this.encryptionContexts[collection]) {
+            const { aesKey, hmacKey } = this.deriveKeys(key, collection);
+            this.encryptionContexts[collection] = {
+                aesKey,
+                hmacKey,
+                projectionMatrices: {}
+            };
+        }
+        const context = this.encryptionContexts[collection];
+        if (vectorDim !== undefined) {
+            if (!context.projectionMatrices[vectorDim]) {
+                const isLorentz = ["lorentz", "poincare"].includes(metric.toLowerCase());
+                const matrixDim = metric.toLowerCase() === "poincare" ? vectorDim + 1 : vectorDim;
+                if (isLorentz) {
+                    context.projectionMatrices[vectorDim] = CognitiveMath.generateLorentzMatrix(matrixDim, context.hmacKey);
+                }
+                else {
+                    context.projectionMatrices[vectorDim] = CognitiveMath.generateOrthogonalMatrix(matrixDim, context.hmacKey);
+                }
+            }
+        }
+        return context;
+    }
+    _projectSingleBlock(subVec, metric, context, blockId) {
+        const dim = subVec.length;
+        if (dim === 0)
+            return [];
+        const cacheKey = blockId ? `${dim}_${blockId}` : `${dim}`;
+        if (!context.projectionMatrices[cacheKey]) {
+            const isLorentz = ["lorentz", "poincare"].includes(metric.toLowerCase());
+            const matrixDim = metric.toLowerCase() === "poincare" ? dim + 1 : dim;
+            const crypto = require('crypto');
+            let seed = context.hmacKey;
+            if (blockId) {
+                seed = crypto.createHash('sha256').update(seed).update(blockId).digest();
+            }
+            if (isLorentz) {
+                context.projectionMatrices[cacheKey] = CognitiveMath.generateLorentzMatrix(matrixDim, seed);
+            }
+            else {
+                context.projectionMatrices[cacheKey] = CognitiveMath.generateOrthogonalMatrix(matrixDim, seed);
+            }
+        }
+        const matrix = context.projectionMatrices[cacheKey];
+        if (metric.toLowerCase() === "poincare") {
+            const lorentzVec = CognitiveMath.poincareToLorentz(subVec);
+            const projLorentz = CognitiveMath.projectVector(lorentzVec, matrix);
+            return CognitiveMath.lorentzToPoincare(projLorentz);
+        }
+        else {
+            return CognitiveMath.projectVector(subVec, matrix);
+        }
+    }
+    _projectCollectionVector(collection, vector, context, metric = "l2") {
+        const schema = this.collectionSchemas[collection];
+        if (!schema || !schema.components || schema.components.length === 0) {
+            return this._projectSingleBlock(vector, metric, context);
+        }
+        const components = schema.components;
+        const cascade = schema.cascadePipeline || [];
+        const componentCutoffs = {};
+        for (const layer of cascade) {
+            const compName = layer.componentName;
+            const cutoff = layer.cutoffDimension;
+            if (compName && cutoff) {
+                if (!componentCutoffs[compName]) {
+                    componentCutoffs[compName] = [];
+                }
+                componentCutoffs[compName].push(cutoff);
+            }
+        }
+        for (const compName in componentCutoffs) {
+            componentCutoffs[compName] = Array.from(new Set(componentCutoffs[compName])).sort((a, b) => a - b);
+        }
+        const projectedParts = [];
+        let currentOffset = 0;
+        for (const comp of components) {
+            const compName = comp.name;
+            const compMetric = comp.metric;
+            const compDim = comp.fullDimension;
+            if (currentOffset >= vector.length) {
+                break;
+            }
+            let subVec = vector.slice(currentOffset, currentOffset + compDim);
+            if (subVec.length < compDim) {
+                subVec = subVec.concat(new Array(compDim - subVec.length).fill(0));
+            }
+            const cutoffs = componentCutoffs[compName] || [];
+            const validCutoffs = cutoffs.filter(c => c < compDim);
+            let projSub = [];
+            if (validCutoffs.length === 0) {
+                projSub = this._projectSingleBlock(subVec, compMetric, context);
+            }
+            else {
+                let blockStart = 0;
+                for (const cutoff of validCutoffs) {
+                    const blockData = subVec.slice(blockStart, cutoff);
+                    const projBlock = this._projectSingleBlock(blockData, compMetric, context, `${compName}_block_${blockStart}_${cutoff}`);
+                    projSub = projSub.concat(projBlock);
+                    blockStart = cutoff;
+                }
+                if (blockStart < compDim) {
+                    const blockData = subVec.slice(blockStart, compDim);
+                    const projBlock = this._projectSingleBlock(blockData, compMetric, context, `${compName}_block_${blockStart}_${compDim}`);
+                    projSub = projSub.concat(projBlock);
+                }
+            }
+            projectedParts.push(...projSub);
+            currentOffset += compDim;
+        }
+        if (currentOffset < vector.length) {
+            projectedParts.push(...vector.slice(currentOffset));
+        }
+        return projectedParts;
+    }
+    _encryptFilters(filters, context) {
+        if (!filters)
+            return filters;
+        return filters.map(f => {
+            const nf = { ...f };
+            if (nf.match) {
+                nf.match = {
+                    key: this.hashMetadataKey(nf.match.key, context.hmacKey),
+                    value: this.hashMetadataValue(nf.match.value, context.hmacKey)
+                };
+            }
+            if (nf.prefix) {
+                nf.prefix = {
+                    key: this.hashMetadataKey(nf.prefix.key, context.hmacKey),
+                    prefix: this.hashMetadataValue(nf.prefix.prefix, context.hmacKey)
+                };
+            }
+            if (nf.and) {
+                nf.and = this._encryptFilters(nf.and, context);
+            }
+            if (nf.or) {
+                nf.or = this._encryptFilters(nf.or, context);
+            }
+            if (nf.not) {
+                nf.not = this._encryptFilters([nf.not], context)[0];
+            }
+            return nf;
+        });
+    }
     // ... (create/delete unchanged) ...
-    createCollection(name, schema) {
+    createCollection(name, schema, encryptionKey = '', noiseSigma = 0.02) {
+        const metric = (schema.components && schema.components[0]) ? schema.components[0].metric : "l2";
+        if (encryptionKey) {
+            this.registerCollectionKey(name, encryptionKey, metric, noiseSigma, schema);
+        }
         return new Promise((resolve, reject) => {
             const req = new hyperspace_pb_1.CreateCollectionRequest();
             req.setName(name);
@@ -443,35 +664,85 @@ class HyperspaceClient {
     }
     insert(id, vector, meta, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL, typedMetadata, payload // Sidecar Payload Storage (v3.2)
     ) {
-        return new Promise((resolve, reject) => {
-            const req = new hyperspace_pb_1.InsertRequest();
-            req.setVectorList(HyperspaceClient.toVectorList(vector));
-            req.setId(id);
-            if (meta) {
-                const map = req.getMetadataMap();
-                for (const k in meta)
-                    map.set(k, meta[k]);
-            }
-            if (typedMetadata) {
-                const map = req.getTypedMetadataMap();
-                for (const k in typedMetadata)
-                    map.set(k, HyperspaceClient.toProtoMetadataValue(typedMetadata[k]));
+        return new Promise(async (resolve, reject) => {
+            var _a;
+            try {
+                const req = new hyperspace_pb_1.InsertRequest();
+                let vectorList = HyperspaceClient.toVectorList(vector);
+                const metric = this.collectionMetrics[collection] || "l2";
+                const context = await this._getEncryptionContext(collection, vectorList.length, metric);
+                if (context) {
+                    const sigma = (_a = this.collectionNoiseSigmas[collection]) !== null && _a !== void 0 ? _a : 0.02;
+                    if (sigma > 0.0) {
+                        vectorList = CognitiveMath.injectAnisotropicNoise(vectorList, context.hmacKey, sigma);
+                    }
+                    vectorList = this._projectCollectionVector(collection, vectorList, context, metric);
+                    let rawPayload = null;
+                    if (payload) {
+                        rawPayload = Buffer.from(payload);
+                    }
+                    if (rawPayload) {
+                        const encrypted = this.encryptPayload(rawPayload, context.aesKey);
+                        req.setPayload(new Uint8Array(encrypted));
+                    }
+                    if (meta) {
+                        const map = req.getMetadataMap();
+                        for (const k in meta) {
+                            const ek = this.hashMetadataKey(k, context.hmacKey);
+                            const ev = this.hashMetadataValue(meta[k], context.hmacKey);
+                            map.set(ek, ev);
+                        }
+                    }
+                    if (typedMetadata) {
+                        const map = req.getTypedMetadataMap();
+                        for (const k in typedMetadata) {
+                            const ek = this.hashMetadataKey(k, context.hmacKey);
+                            const ev = this.hashMetadataValue(String(typedMetadata[k]), context.hmacKey);
+                            map.set(ek, HyperspaceClient.toProtoMetadataValue(ev));
+                        }
+                    }
+                }
+                else {
+                    if (meta) {
+                        const map = req.getMetadataMap();
+                        for (const k in meta)
+                            map.set(k, meta[k]);
+                    }
+                    if (typedMetadata) {
+                        const map = req.getTypedMetadataMap();
+                        for (const k in typedMetadata)
+                            map.set(k, HyperspaceClient.toProtoMetadataValue(typedMetadata[k]));
+                    }
+                    if (payload) {
+                        req.setPayload(payload);
+                    }
+                }
+                req.setVectorList(vectorList);
+                req.setId(id);
+                req.setCollection(collection);
+                req.setOriginNodeId('');
+                req.setLogicalClock(0);
+                req.setDurability(durability);
+                this.client.insert(req, this.metadata, (err, resp) => {
+                    if (err)
+                        return reject(err);
+                    resolve(resp.getSuccess());
+                });
             }
-            req.setCollection(collection);
-            req.setOriginNodeId('');
-            req.setLogicalClock(0);
-            req.setDurability(durability);
-            if (payload) {
-                req.setPayload(payload);
+            catch (e) {
+                reject(e);
             }
-            this.client.insert(req, this.metadata, (err, resp) => {
-                if (err)
-                    return reject(err);
-                resolve(resp.getSuccess());
-            });
         });
     }
     insertText(id, text, meta, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL) {
+        if (this.collectionKeys[collection]) {
+            if (!this.embedder) {
+                return Promise.reject(new Error("An embedder must be configured to use insertText on encrypted collections."));
+            }
+            return Promise.resolve(this.embedder.encode(text)).then(vector => {
+                return this.insert(id, vector, meta, collection, durability, undefined, Buffer.from(text, 'utf-8'));
+            });
+        }
         return new Promise((resolve, reject) => {
             const req = new hyperspace_pb_1.InsertTextRequest();
             req.setText(text);
@@ -532,85 +803,135 @@ class HyperspaceClient {
         });
     }
     search(vector, topK, collection = '', options) {
-        return new Promise((resolve, reject) => {
-            const req = new hyperspace_pb_1.SearchRequest();
-            req.setVectorList(HyperspaceClient.toVectorList(vector));
-            req.setTopK(topK);
-            req.setCollection(collection);
-            if (options === null || options === void 0 ? void 0 : options.filter) {
-                const map = req.getFilterMap();
-                for (const k in options.filter) {
-                    map.set(k, options.filter[k]);
+        return new Promise(async (resolve, reject) => {
+            var _a;
+            try {
+                const req = new hyperspace_pb_1.SearchRequest();
+                let vectorList = HyperspaceClient.toVectorList(vector);
+                req.setTopK(topK);
+                req.setCollection(collection);
+                const metric = this.collectionMetrics[collection] || "l2";
+                const context = await this._getEncryptionContext(collection, vectorList.length, metric);
+                let optFilters = options === null || options === void 0 ? void 0 : options.filters;
+                let optFilter = options === null || options === void 0 ? void 0 : options.filter;
+                let includePayload = options === null || options === void 0 ? void 0 : options.includePayload;
+                if (context) {
+                    const sigma = (_a = this.collectionNoiseSigmas[collection]) !== null && _a !== void 0 ? _a : 0.02;
+                    if (sigma > 0.0) {
+                        vectorList = CognitiveMath.injectAnisotropicNoise(vectorList, context.hmacKey, sigma);
+                    }
+                    vectorList = this._projectCollectionVector(collection, vectorList, context, metric);
+                    if (optFilter) {
+                        const hashedFilter = {};
+                        for (const k in optFilter) {
+                            const ek = this.hashMetadataKey(k, context.hmacKey);
+                            const ev = this.hashMetadataValue(optFilter[k], context.hmacKey);
+                            hashedFilter[ek] = ev;
+                        }
+                        optFilter = hashedFilter;
+                    }
+                    if (optFilters) {
+                        optFilters = this._encryptFilters(optFilters, context);
+                    }
+                    includePayload = true;
                 }
-            }
-            if ((options === null || options === void 0 ? void 0 : options.restartFactor) !== undefined) {
-                const map = req.getFilterMap();
-                map.set('wave_restart_factor', options.restartFactor.toString());
-            }
-            if ((options === null || options === void 0 ? void 0 : options.useWave) !== undefined) {
-                req.setUseWave(options.useWave);
-            }
-            if (options === null || options === void 0 ? void 0 : options.filters) {
-                req.setFiltersList(options.filters.map(f => this.toProtoFilter(f)));
-            }
-            if (options === null || options === void 0 ? void 0 : options.hybridQuery)
-                req.setHybridQuery(options.hybridQuery);
-            if ((options === null || options === void 0 ? void 0 : options.hybridAlpha) !== undefined)
-                req.setHybridAlpha(options.hybridAlpha);
-            if ((options === null || options === void 0 ? void 0 : options.mrlDimension) !== undefined)
-                req.setMrlDimension(options.mrlDimension);
-            if ((options === null || options === void 0 ? void 0 : options.useWasserstein) !== undefined)
-                req.setUseWasserstein(options.useWasserstein);
-            if ((options === null || options === void 0 ? void 0 : options.includePayload) !== undefined)
-                req.setIncludePayload(options.includePayload);
-            if (options === null || options === void 0 ? void 0 : options.componentWeights) {
-                const map = req.getComponentWeightsMap();
-                for (const k in options.componentWeights) {
-                    map.set(k, options.componentWeights[k]);
+                req.setVectorList(vectorList);
+                if (optFilter) {
+                    const map = req.getFilterMap();
+                    for (const k in optFilter) {
+                        map.set(k, optFilter[k]);
+                    }
                 }
-            }
-            if (options === null || options === void 0 ? void 0 : options.bm25) {
-                const bm25Msg = new hyperspace_pb_1.Bm25Options();
-                if (options.bm25.method !== undefined)
-                    bm25Msg.setMethod(options.bm25.method);
-                if (options.bm25.k1 !== undefined)
-                    bm25Msg.setK1(options.bm25.k1);
-                if (options.bm25.b !== undefined)
-                    bm25Msg.setB(options.bm25.b);
-                if (options.bm25.delta !== undefined)
-                    bm25Msg.setDelta(options.bm25.delta);
-                if (options.bm25.language !== undefined)
-                    bm25Msg.setLanguage(options.bm25.language);
-                if (options.bm25.ngrams !== undefined)
-                    bm25Msg.setNgrams(options.bm25.ngrams);
-                if (options.bm25.fusionMethod !== undefined)
-                    bm25Msg.setFusionMethod(options.bm25.fusionMethod);
-                req.setBm25Options(bm25Msg);
-            }
-            this.client.search(req, this.metadata, (err, resp) => {
-                if (err)
-                    return reject(err);
-                const results = resp.getResultsList().map(r => {
-                    const metaMap = r.getMetadataMap();
-                    const meta = {};
-                    if (metaMap.getLength() > 0) {
-                        metaMap.forEach((entry, key) => {
-                            meta[key] = entry;
-                        });
+                if ((options === null || options === void 0 ? void 0 : options.restartFactor) !== undefined) {
+                    const map = req.getFilterMap();
+                    map.set('wave_restart_factor', options.restartFactor.toString());
+                }
+                if ((options === null || options === void 0 ? void 0 : options.useWave) !== undefined) {
+                    req.setUseWave(options.useWave);
+                }
+                if (optFilters) {
+                    req.setFiltersList(optFilters.map(f => this.toProtoFilter(f)));
+                }
+                if (options === null || options === void 0 ? void 0 : options.hybridQuery)
+                    req.setHybridQuery(options.hybridQuery);
+                if ((options === null || options === void 0 ? void 0 : options.hybridAlpha) !== undefined)
+                    req.setHybridAlpha(options.hybridAlpha);
+                if ((options === null || options === void 0 ? void 0 : options.mrlDimension) !== undefined)
+                    req.setMrlDimension(options.mrlDimension);
+                if ((options === null || options === void 0 ? void 0 : options.useWasserstein) !== undefined)
+                    req.setUseWasserstein(options.useWasserstein);
+                if (includePayload !== undefined)
+                    req.setIncludePayload(includePayload);
+                if (options === null || options === void 0 ? void 0 : options.componentWeights) {
+                    const map = req.getComponentWeightsMap();
+                    for (const k in options.componentWeights) {
+                        map.set(k, options.componentWeights[k]);
                     }
-                    return {
-                        id: r.getId(),
-                        distance: r.getDistance(),
-                        metadata: meta,
-                        typedMetadata: HyperspaceClient.parseTypedMetadata(r.getTypedMetadataMap()),
-                        payload: r.getPayload_asU8()
-                    };
+                }
+                if (options === null || options === void 0 ? void 0 : options.bm25) {
+                    const bm25Msg = new hyperspace_pb_1.Bm25Options();
+                    if (options.bm25.method !== undefined)
+                        bm25Msg.setMethod(options.bm25.method);
+                    if (options.bm25.k1 !== undefined)
+                        bm25Msg.setK1(options.bm25.k1);
+                    if (options.bm25.b !== undefined)
+                        bm25Msg.setB(options.bm25.b);
+                    if (options.bm25.delta !== undefined)
+                        bm25Msg.setDelta(options.bm25.delta);
+                    if (options.bm25.language !== undefined)
+                        bm25Msg.setLanguage(options.bm25.language);
+                    if (options.bm25.ngrams !== undefined)
+                        bm25Msg.setNgrams(options.bm25.ngrams);
+                    if (options.bm25.fusionMethod !== undefined)
+                        bm25Msg.setFusionMethod(options.bm25.fusionMethod);
+                    req.setBm25Options(bm25Msg);
+                }
+                this.client.search(req, this.metadata, (err, resp) => {
+                    if (err)
+                        return reject(err);
+                    const results = resp.getResultsList().map(r => {
+                        const metaMap = r.getMetadataMap();
+                        const meta = {};
+                        if (metaMap.getLength() > 0) {
+                            metaMap.forEach((entry, key) => {
+                                meta[key] = entry;
+                            });
+                        }
+                        let payloadBytes = r.getPayload_asU8();
+                        if (context && payloadBytes && payloadBytes.length > 0) {
+                            try {
+                                const decrypted = this.decryptPayload(Buffer.from(payloadBytes), context.aesKey);
+                                payloadBytes = new Uint8Array(decrypted);
+                            }
+                            catch (e) {
+                                // Decryption error
+                            }
+                        }
+                        return {
+                            id: r.getId(),
+                            distance: r.getDistance(),
+                            metadata: meta,
+                            typedMetadata: HyperspaceClient.parseTypedMetadata(r.getTypedMetadataMap()),
+                            payload: payloadBytes
+                        };
+                    });
+                    resolve(results);
                 });
-                resolve(results);
-            });
+            }
+            catch (e) {
+                reject(e);
+            }
         });
     }
     searchText(text, topK, collection = '', options) {
+        if (this.collectionKeys[collection]) {
+            if (!this.embedder) {
+                return Promise.reject(new Error("An embedder must be configured to use searchText on encrypted collections."));
+            }
+            return Promise.resolve(this.embedder.encode(text)).then(vector => {
+                return this.search(vector, topK, collection, options);
+            });
+        }
         return new Promise((resolve, reject) => {
             const req = new hyperspace_pb_1.SearchTextRequest();
             req.setText(text);

package/dist/math.d.ts

@@ -42,3 +42,7 @@ export declare function koopmanExtrapolate(past: number[], current: number[], st
  * Pulls the thought towards the context along the geodesic by `resonanceFactor` [0, 1].
  */
 export declare function contextResonance(thought: number[], globalContext: number[], resonanceFactor: number, c?: number): number[];
+export declare function generateOrthogonalMatrix(dimension: number, seedBytes: Uint8Array): number[][];
+export declare function generateLorentzMatrix(dimension: number, seedBytes: Uint8Array): number[][];
+export declare function projectVector(v: number[], projectionMatrix: number[][]): number[];
+export declare function injectAnisotropicNoise(vector: number[], noiseSeed: Uint8Array, sigma?: number): number[];

package/dist/math.js

@@ -21,6 +21,10 @@ exports.localEntropy = localEntropy;
 exports.lyapunovConvergence = lyapunovConvergence;
 exports.koopmanExtrapolate = koopmanExtrapolate;
 exports.contextResonance = contextResonance;
+exports.generateOrthogonalMatrix = generateOrthogonalMatrix;
+exports.generateLorentzMatrix = generateLorentzMatrix;
+exports.projectVector = projectVector;
+exports.injectAnisotropicNoise = injectAnisotropicNoise;
 function dot(a, b) {
     let sum = 0;
     for (let i = 0; i < a.length; i++)
@@ -232,3 +236,149 @@ function contextResonance(thought, globalContext, resonanceFactor, c = 1.0) {
     const appliedPull = pullDir.map(v => v * factor);
     return expMap(thought, appliedPull, c);
 }
+function generateOrthogonalMatrix(dimension, seedBytes) {
+    const crypto = require('crypto');
+    const matrix = [];
+    let currentHash = crypto.createHash('sha256').update(seedBytes).digest();
+    let hashOffset = 0;
+    for (let i = 0; i < dimension; i++) {
+        const row = [];
+        for (let j = 0; j < dimension; j++) {
+            if (hashOffset >= 32) {
+                currentHash = crypto.createHash('sha256').update(currentHash).digest();
+                hashOffset = 0;
+            }
+            const val = (currentHash.readUInt32LE(hashOffset) / 4294967296.0) * 2.0 - 1.0;
+            row.push(val);
+            hashOffset += 4;
+        }
+        matrix.push(row);
+    }
+    // Gram-Schmidt Orthonormalization with Reorthogonalization (twice is enough)
+    for (let i = 0; i < dimension; i++) {
+        let v = matrix[i];
+        for (let j = 0; j < i; j++) {
+            const u = matrix[j];
+            let uDotV = dot(u, v);
+            v = v.map((vi, k) => vi - uDotV * u[k]);
+            // Re-project to eliminate floating-point leakage
+            uDotV = dot(u, v);
+            v = v.map((vi, k) => vi - uDotV * u[k]);
+        }
+        const vNorm = norm(v);
+        if (vNorm > 1e-15) {
+            matrix[i] = v.map(vi => vi / vNorm);
+        }
+        else {
+            matrix[i] = new Array(dimension).fill(0);
+            matrix[i][i] = 1.0;
+        }
+    }
+    return matrix;
+}
+function generateLorentzMatrix(dimension, seedBytes) {
+    const d = dimension - 1;
+    const crypto = require('crypto');
+    const rSeed = crypto.createHash('sha256').update(seedBytes).update("spatial").digest();
+    const R = generateOrthogonalMatrix(d, rSeed);
+    const bSeed = crypto.createHash('sha256').update(seedBytes).update("boost").digest();
+    let beta = [];
+    let currentHash = bSeed;
+    let hashOffset = 0;
+    for (let i = 0; i < d; i++) {
+        if (hashOffset >= 32) {
+            currentHash = crypto.createHash('sha256').update(currentHash).digest();
+            hashOffset = 0;
+        }
+        const val = (currentHash.readUInt32LE(hashOffset) / 4294967296.0) * 2.0 - 1.0;
+        beta.push(val);
+        hashOffset += 4;
+    }
+    const betaNorm = norm(beta);
+    if (betaNorm > 1e-15) {
+        beta = beta.map(v => (v / betaNorm) * 0.1);
+    }
+    else {
+        beta = new Array(d).fill(0);
+        beta[0] = 0.1;
+    }
+    const betaSq = dot(beta, beta);
+    const gamma = 1.0 / Math.sqrt(1.0 - betaSq);
+    const Lambda_B = [];
+    for (let i = 0; i < dimension; i++) {
+        Lambda_B.push(new Array(dimension).fill(0));
+    }
+    Lambda_B[0][0] = gamma;
+    for (let j = 1; j < dimension; j++) {
+        Lambda_B[0][j] = -gamma * beta[j - 1];
+        Lambda_B[j][0] = -gamma * beta[j - 1];
+    }
+    const factor = (gamma - 1.0) / betaSq;
+    for (let i = 1; i < dimension; i++) {
+        for (let j = 1; j < dimension; j++) {
+            const delta = i === j ? 1.0 : 0.0;
+            Lambda_B[i][j] = delta + factor * beta[i - 1] * beta[j - 1];
+        }
+    }
+    const Lambda_R = [];
+    for (let i = 0; i < dimension; i++) {
+        Lambda_R.push(new Array(dimension).fill(0));
+    }
+    Lambda_R[0][0] = 1.0;
+    for (let i = 1; i < dimension; i++) {
+        for (let j = 1; j < dimension; j++) {
+            Lambda_R[i][j] = R[i - 1][j - 1];
+        }
+    }
+    const Lambda = [];
+    for (let i = 0; i < dimension; i++) {
+        const row = [];
+        for (let j = 0; j < dimension; j++) {
+            let sum = 0;
+            for (let k = 0; k < dimension; k++) {
+                sum += Lambda_R[i][k] * Lambda_B[k][j];
+            }
+            row.push(sum);
+        }
+        Lambda.push(row);
+    }
+    return Lambda;
+}
+function projectVector(v, projectionMatrix) {
+    const dimension = v.length;
+    const projected = new Array(dimension).fill(0);
+    for (let j = 0; j < dimension; j++) {
+        let sum = 0;
+        for (let i = 0; i < dimension; i++) {
+            sum += v[i] * projectionMatrix[i][j];
+        }
+        projected[j] = sum;
+    }
+    return projected;
+}
+function injectAnisotropicNoise(vector, noiseSeed, sigma = 0.02) {
+    if (sigma <= 0.0)
+        return [...vector];
+    const crypto = require('crypto');
+    const vecBytes = Buffer.from(vector.toString());
+    const hash = crypto.createHash('sha256').update(noiseSeed).update(vecBytes).digest();
+    let currentHash = hash;
+    const noise = [];
+    for (let i = 0; i < vector.length; i++) {
+        if (currentHash.length < 16) {
+            currentHash = crypto.createHash('sha256').update(currentHash).digest();
+        }
+        const u1 = Math.max(1e-15, (currentHash.readUInt32LE(0) + 1) / 4294967296);
+        const u2 = Math.max(1e-15, (currentHash.readUInt32LE(4) + 1) / 4294967296);
+        const z0 = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
+        noise.push(z0 * sigma);
+        currentHash = currentHash.subarray(8);
+    }
+    const noisy = vector.map((v, i) => v + noise[i]);
+    const origNorm = norm(vector);
+    const noisyNorm = norm(noisy);
+    if (noisyNorm > 1e-15) {
+        return noisy.map(v => (v / noisyNorm) * origNorm);
+    }
+    return noisy;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperspace-sdk-ts",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "Official TypeScript SDK for HyperspaceDB gRPC API",
   "main": "dist/client.js",
   "types": "dist/client.d.ts",