@sochdb/sochdb 0.4.0 → 0.4.2

package/dist/esm/semantic-cache.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Semantic Cache for LLM responses
+ *
+ * Cache LLM responses with similarity-based retrieval for cost savings.
+ * Uses database prefix scanning to store and retrieve cached responses.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticCache = void 0;
+/**
+ * Calculate cosine similarity between two vectors
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error('Vectors must have same length');
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0) {
+        return 0;
+    }
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+/**
+ * Semantic Cache with vector similarity matching
+ *
+ * @example
+ * ```typescript
+ * const cache = new SemanticCache(db, 'llm_responses');
+ *
+ * // Store response
+ * await cache.put(
+ *   'What is Python?',
+ *   'Python is a high-level programming language...',
+ *   embedding,
+ *   3600  // TTL in seconds
+ * );
+ *
+ * // Check cache
+ * const hit = await cache.get(queryEmbedding, 0.85);
+ * if (hit) {
+ *   console.log(`Cache HIT: ${hit.value} (similarity: ${hit.score})`);
+ * }
+ * ```
+ */
+class SemanticCache {
+    db;
+    cacheName;
+    prefix;
+    hits = 0;
+    misses = 0;
+    constructor(db, cacheName) {
+        this.db = db;
+        this.cacheName = cacheName;
+        this.prefix = Buffer.from(`cache:${cacheName}:`);
+    }
+    /**
+     * Store a cached response
+     */
+    async put(key, value, embedding, ttlSeconds = 0, metadata) {
+        const entry = {
+            key,
+            value,
+            embedding,
+            timestamp: Date.now(),
+            ttl: ttlSeconds > 0 ? ttlSeconds : undefined,
+            metadata,
+        };
+        const entryKey = Buffer.concat([
+            this.prefix,
+            Buffer.from(key),
+        ]);
+        await this.db.put(entryKey, Buffer.from(JSON.stringify(entry)));
+    }
+    /**
+     * Retrieve cached response by similarity
+     *
+     * @param queryEmbedding - Query embedding vector
+     * @param threshold - Minimum cosine similarity (0-1)
+     * @returns Best matching cache entry or null
+     */
+    async get(queryEmbedding, threshold = 0.85) {
+        const now = Date.now();
+        let bestMatch = null;
+        let bestScore = threshold;
+        // Scan all cache entries with this prefix
+        try {
+            for await (const [_, valueBuffer] of this.db.scanPrefix(this.prefix)) {
+                const entry = JSON.parse(valueBuffer.toString());
+                // Check TTL expiration
+                if (entry.ttl && entry.timestamp) {
+                    const expiresAt = entry.timestamp + entry.ttl * 1000;
+                    if (now > expiresAt) {
+                        continue; // Skip expired entries
+                    }
+                }
+                // Calculate similarity
+                const score = cosineSimilarity(queryEmbedding, entry.embedding);
+                // Update best match
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestMatch = { ...entry, score };
+                }
+            }
+        }
+        catch (error) {
+            // If scan fails, return null
+            this.misses++;
+            return null;
+        }
+        if (bestMatch) {
+            this.hits++;
+        }
+        else {
+            this.misses++;
+        }
+        return bestMatch;
+    }
+    /**
+     * Delete a specific cache entry
+     */
+    async delete(key) {
+        const entryKey = Buffer.concat([
+            this.prefix,
+            Buffer.from(key),
+        ]);
+        await this.db.delete(entryKey);
+    }
+    /**
+     * Clear all entries in this cache
+     */
+    async clear() {
+        let deleted = 0;
+        try {
+            const toDelete = [];
+            for await (const [key] of this.db.scanPrefix(this.prefix)) {
+                toDelete.push(key);
+            }
+            for (const key of toDelete) {
+                await this.db.delete(key);
+                deleted++;
+            }
+        }
+        catch (error) {
+            // If operation fails, return count so far
+            return deleted;
+        }
+        // Reset stats
+        this.hits = 0;
+        this.misses = 0;
+        return deleted;
+    }
+    /**
+     * Get cache statistics
+     */
+    async stats() {
+        const now = Date.now();
+        let count = 0;
+        let memoryUsage = 0;
+        try {
+            for await (const [key, value] of this.db.scanPrefix(this.prefix)) {
+                const entry = JSON.parse(value.toString());
+                // Skip expired entries
+                if (entry.ttl && entry.timestamp) {
+                    const expiresAt = entry.timestamp + entry.ttl * 1000;
+                    if (now > expiresAt) {
+                        continue;
+                    }
+                }
+                count++;
+                memoryUsage += key.length + value.length;
+            }
+        }
+        catch (error) {
+            // Return partial stats if operation fails
+        }
+        const total = this.hits + this.misses;
+        const hitRate = total > 0 ? this.hits / total : 0;
+        return {
+            count,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate,
+            memoryUsage,
+        };
+    }
+    /**
+     * Purge expired entries
+     */
+    async purgeExpired() {
+        const now = Date.now();
+        let purged = 0;
+        try {
+            const toDelete = [];
+            for await (const [key, value] of this.db.scanPrefix(this.prefix)) {
+                const entry = JSON.parse(value.toString());
+                if (entry.ttl && entry.timestamp) {
+                    const expiresAt = entry.timestamp + entry.ttl * 1000;
+                    if (now > expiresAt) {
+                        toDelete.push(key);
+                    }
+                }
+            }
+            for (const key of toDelete) {
+                await this.db.delete(key);
+                purged++;
+            }
+        }
+        catch (error) {
+            // Return count so far
+            return purged;
+        }
+        return purged;
+    }
+}
+exports.SemanticCache = SemanticCache;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VtYW50aWMtY2FjaGUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc2VtYW50aWMtY2FjaGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7OztHQUtHOzs7QUFJSDs7R0FFRztBQUNILFNBQVMsZ0JBQWdCLENBQUMsQ0FBVyxFQUFFLENBQVc7SUFDaEQsSUFBSSxDQUFDLENBQUMsTUFBTSxLQUFLLENBQUMsQ0FBQyxNQUFNLEVBQUUsQ0FBQztRQUMxQixNQUFNLElBQUksS0FBSyxDQUFDLCtCQUErQixDQUFDLENBQUM7SUFDbkQsQ0FBQztJQUVELElBQUksVUFBVSxHQUFHLENBQUMsQ0FBQztJQUNuQixJQUFJLEtBQUssR0FBRyxDQUFDLENBQUM7SUFDZCxJQUFJLEtBQUssR0FBRyxDQUFDLENBQUM7SUFFZCxLQUFLLElBQUksQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDLEdBQUcsQ0FBQyxDQUFDLE1BQU0sRUFBRSxDQUFDLEVBQUUsRUFBRSxDQUFDO1FBQ2xDLFVBQVUsSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO1FBQzFCLEtBQUssSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO1FBQ3JCLEtBQUssSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0lBQ3ZCLENBQUM7SUFFRCxJQUFJLEtBQUssS0FBSyxDQUFDLElBQUksS0FBSyxLQUFLLENBQUMsRUFBRSxDQUFDO1FBQy9CLE9BQU8sQ0FBQyxDQUFDO0lBQ1gsQ0FBQztJQUVELE9BQU8sVUFBVSxHQUFHLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsR0FBRyxJQUFJLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUM7QUFDNUQsQ0FBQztBQXVCRDs7Ozs7Ozs7Ozs7Ozs7Ozs7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QUM7UUFFRCxPQUFPLE1BQU0sQ0FBQztJQUNoQixDQUFDO0NBQ0Y7QUExTUQsc0NBME1DIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBTZW1hbnRpYyBDYWNoZSBmb3IgTExNIHJlc3BvbnNlc1xuICogXG4gKiBDYWNoZSBMTE0gcmVzcG9uc2VzIHdpdGggc2ltaWxhcml0eS1iYXNlZCByZXRyaWV2YWwgZm9yIGNvc3Qgc2F2aW5ncy5cbiAqIFVzZXMgZGF0YWJhc2UgcHJlZml4IHNjYW5uaW5nIHRvIHN0b3JlIGFuZCByZXRyaWV2ZSBjYWNoZWQgcmVzcG9uc2VzLlxuICovXG5cbmltcG9ydCB7IEVtYmVkZGVkRGF0YWJhc2UgfSBmcm9tICcuL2VtYmVkZGVkJztcblxuLyoqXG4gKiBDYWxjdWxhdGUgY29zaW5lIHNpbWlsYXJpdHkgYmV0d2VlbiB0d28gdmVjdG9yc1xuICovXG5mdW5jdGlvbiBjb3NpbmVTaW1pbGFyaXR5KGE6IG51bWJlcltdLCBiOiBudW1iZXJbXSk6IG51bWJlciB7XG4gIGlmIChhLmxlbmd0aCAhPT0gYi5sZW5ndGgpIHtcbiAgICB0aHJvdyBuZXcgRXJyb3IoJ1ZlY3RvcnMgbXVzdCBoYXZlIHNhbWUgbGVuZ3RoJyk7XG4gIH1cblxuICBsZXQgZG90UHJvZHVjdCA9IDA7XG4gIGxldCBub3JtQSA9IDA7XG4gIGxldCBub3JtQiA9IDA7XG5cbiAgZm9yIChsZXQgaSA9IDA7IGkgPCBhLmxlbmd0aDsgaSsrKSB7XG4gICAgZG90UHJvZHVjdCArPSBhW2ldICogYltpXTtcbiAgICBub3JtQSArPSBhW2ldICogYVtpXTtcbiAgICBub3JtQiArPSBiW2ldICogYltpXTtcbiAgfVxuXG4gIGlmIChub3JtQSA9PT0gMCB8fCBub3JtQiA9PT0gMCkge1xuICAgIHJldHVybiAwO1xuICB9XG5cbiAgcmV0dXJuIGRvdFByb2R1Y3QgLyAoTWF0aC5zcXJ0KG5vcm1BKSAqIE1hdGguc3FydChub3JtQikpO1xufVxuXG5leHBvcnQgaW50ZXJmYWNlIENhY2hlRW50cnkge1xuICBrZXk6IHN0cmluZztcbiAgdmFsdWU6IHN0cmluZztcbiAgZW1iZWRkaW5nOiBudW1iZXJbXTtcbiAgdGltZXN0YW1wOiBudW1iZXI7XG4gIHR0bD86IG51bWJlcjtcbiAgbWV0YWRhdGE/OiBSZWNvcmQ8c3RyaW5nLCBhbnk+O1xufVxuXG5leHBvcnQgaW50ZXJmYWNlIENhY2hlSGl0IGV4dGVuZHMgQ2FjaGVFbnRyeSB7XG4gIHNjb3JlOiBudW1iZXI7XG59XG5cbmV4cG9ydCBpbnRlcmZhY2UgQ2FjaGVTdGF0cyB7XG4gIGNvdW50OiBudW1iZXI7XG4gIGhpdHM6IG51bWJlcjtcbiAgbWlzc2VzOiBudW1iZXI7XG4gIGhpdFJhdGU6IG51bWJlcjtcbiAgbWVtb3J5VXNhZ2U6IG51bWJlcjtcbn1cblxuLyoqXG4gKiBTZW1hbnRpYyBDYWNoZSB3aXRoIHZlY3RvciBzaW1pbGFyaXR5IG1hdGNoaW5nXG4gKiBcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBjb25zdCBjYWNoZSA9IG5ldyBTZW1hbnRpY0NhY2hlKGRiLCAnbGxtX3Jlc3BvbnNlcycpO1xuICogXG4gKiAvLyBTdG9yZSByZXNwb25zZVxuICogYXdhaXQgY2FjaGUucHV0KFxuICogICAnV2hhdCBpcyBQeXRob24/JyxcbiAqICAgJ1B5dGhvbiBpcyBhIGhpZ2gtbGV2ZWwgcHJvZ3JhbW1pbmcgbGFuZ3VhZ2UuLi4nLFxuICogICBlbWJlZGRpbmcsXG4gKiAgIDM2MDAgIC8vIFRUTCBpbiBzZWNvbmRzXG4gKiApO1xuICogXG4gKiAvLyBDaGVjayBjYWNoZVxuICogY29uc3QgaGl0ID0gYXdhaXQgY2FjaGUuZ2V0KHF1ZXJ5RW1iZWRkaW5nLCAwLjg1KTtcbiAqIGlmIChoaXQpIHtcbiAqICAgY29uc29sZS5sb2coYENhY2hlIEhJVDogJHtoaXQudmFsdWV9IChzaW1pbGFyaXR5OiAke2hpdC5zY29yZX0pYCk7XG4gKiB9XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGNsYXNzIFNlbWFudGljQ2FjaGUge1xuICBwcml2YXRlIGRiOiBFbWJlZGRlZERhdGFiYXNlO1xuICBwcml2YXRlIGNhY2hlTmFtZTogc3RyaW5nO1xuICBwcml2YXRlIHByZWZpeDogQnVmZmVyO1xuICBwcml2YXRlIGhpdHMgPSAwO1xuICBwcml2YXRlIG1pc3NlcyA9IDA7XG5cbiAgY29uc3RydWN0b3IoZGI6IEVtYmVkZGVkRGF0YWJhc2UsIGNhY2hlTmFtZTogc3RyaW5nKSB7XG4gICAgdGhpcy5kYiA9IGRiO1xuICAgIHRoaXMuY2FjaGVOYW1lID0gY2FjaGVOYW1lO1xuICAgIHRoaXMucHJlZml4ID0gQnVmZmVyLmZyb20oYGNhY2hlOiR7Y2FjaGVOYW1lfTpgKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBTdG9yZSBhIGNhY2hlZCByZXNwb25zZVxuICAgKi9cbiAgYXN5bmMgcHV0KFxuICAgIGtleTogc3RyaW5nLFxuICAgIHZhbHVlOiBzdHJpbmcsXG4gICAgZW1iZWRkaW5nOiBudW1iZXJbXSxcbiAgICB0dGxTZWNvbmRzID0gMCxcbiAgICBtZXRhZGF0YT86IFJlY29yZDxzdHJpbmcsIGFueT5cbiAgKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgY29uc3QgZW50cnk6IENhY2hlRW50cnkgPSB7XG4gICAgICBrZXksXG4gICAgICB2YWx1ZSxcbiAgICAgIGVtYmVkZGluZyxcbiAgICAgIHRpbWVzdGFtcDogRGF0ZS5ub3coKSxcbiAgICAgIHR0bDogdHRsU2Vjb25kcyA+IDAgPyB0dGxTZWNvbmRzIDogdW5kZWZpbmVkLFxuICAgICAgbWV0YWRhdGEsXG4gICAgfTtcblxuICAgIGNvbnN0IGVudHJ5S2V5ID0gQnVmZmVyLmNvbmNhdChbXG4gICAgICB0aGlzLnByZWZpeCxcbiAgICAgIEJ1ZmZlci5mcm9tKGtleSksXG4gICAgXSk7XG5cbiAgICBhd2FpdCB0aGlzLmRiLnB1dChlbnRyeUtleSwgQnVmZmVyLmZyb20oSlNPTi5zdHJpbmdpZnkoZW50cnkpKSk7XG4gIH1cblxuICAvKipcbiAgICogUmV0cmlldmUgY2FjaGVkIHJlc3BvbnNlIGJ5IHNpbWlsYXJpdHlcbiAgICogXG4gICAqIEBwYXJhbSBxdWVyeUVtYmVkZGluZyAtIFF1ZXJ5IGVtYmVkZGluZyB2ZWN0b3JcbiAgICogQHBhcmFtIHRocmVzaG9sZCAtIE1pbmltdW0gY29zaW5lIHNpbWlsYXJpdHkgKDAtMSlcbiAgICogQHJldHVybnMgQmVzdCBtYXRjaGluZyBjYWNoZSBlbnRyeSBvciBudWxsXG4gICAqL1xuICBhc3luYyBnZXQoXG4gICAgcXVlcnlFbWJlZGRpbmc6IG51bWJlcltdLFxuICAgIHRocmVzaG9sZCA9IDAuODVcbiAgKTogUHJvbWlzZTxDYWNoZUhpdCB8IG51bGw+IHtcbiAgICBjb25zdCBub3cgPSBEYXRlLm5vdygpO1xuICAgIGxldCBiZXN0TWF0Y2g6IENhY2hlSGl0IHwgbnVsbCA9IG51bGw7XG4gICAgbGV0IGJlc3RTY29yZSA9IHRocmVzaG9sZDtcblxuICAgIC8vIFNjYW4gYWxsIGNhY2hlIGVudHJpZXMgd2l0aCB0aGlzIHByZWZpeFxuICAgIHRyeSB7XG4gICAgICBmb3IgYXdhaXQgKGNvbnN0IFtfLCB2YWx1ZUJ1ZmZlcl0gb2YgdGhpcy5kYi5zY2FuUHJlZml4KHRoaXMucHJlZml4KSkge1xuICAgICAgICBjb25zdCBlbnRyeTogQ2FjaGVFbnRyeSA9IEpTT04ucGFyc2UodmFsdWVCdWZmZXIudG9TdHJpbmcoKSk7XG5cbiAgICAgICAgLy8gQ2hlY2sgVFRMIGV4cGlyYXRpb25cbiAgICAgICAgaWYgKGVudHJ5LnR0bCAmJiBlbnRyeS50aW1lc3RhbXApIHtcbiAgICAgICAgICBjb25zdCBleHBpcmVzQXQgPSBlbnRyeS50aW1lc3RhbXAgKyBlbnRyeS50dGwgKiAxMDAwO1xuICAgICAgICAgIGlmIChub3cgPiBleHBpcmVzQXQpIHtcbiAgICAgICAgICAgIGNvbnRpbnVlOyAvLyBTa2lwIGV4cGlyZWQgZW50cmllc1xuICAgICAgICAgIH1cbiAgICAgICAgfVxuXG4gICAgICAgIC8vIENhbGN1bGF0ZSBzaW1pbGFyaXR5XG4gICAgICAgIGNvbnN0IHNjb3JlID0gY29zaW5lU2ltaWxhcml0eShxdWVyeUVtYmVkZGluZywgZW50cnkuZW1iZWRkaW5nKTtcblxuICAgICAgICAvLyBVcGRhdGUgYmVzdCBtYXRjaFxuICAgICAgICBpZiAoc2NvcmUgPiBiZXN0U2NvcmUpIHtcbiAgICAgICAgICBiZXN0U2NvcmUgPSBzY29yZTtcbiAgICAgICAgICBiZXN0TWF0Y2ggPSB7IC4uLmVudHJ5LCBzY29yZSB9O1xuICAgICAgICB9XG4gICAgICB9XG4gICAgfSBjYXRjaCAoZXJyb3IpIHtcbiAgICAgIC8vIElmIHNjYW4gZmFpbHMsIHJldHVybiBudWxsXG4gICAgICB0aGlzLm1pc3NlcysrO1xuICAgICAgcmV0dXJuIG51bGw7XG4gICAgfVxuXG4gICAgaWYgKGJlc3RNYXRjaCkge1xuICAgICAgdGhpcy5oaXRzKys7XG4gICAgfSBlbHNlIHtcbiAgICAgIHRoaXMubWlzc2VzKys7XG4gICAgfVxuXG4gICAgcmV0dXJuIGJlc3RNYXRjaDtcbiAgfVxuXG4gIC8qKlxuICAgKiBEZWxldGUgYSBzcGVjaWZpYyBjYWNoZSBlbnRyeVxuICAgKi9cbiAgYXN5bmMgZGVsZXRlKGtleTogc3RyaW5nKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgY29uc3QgZW50cnlLZXkgPSBCdWZmZXIuY29uY2F0KFtcbiAgICAgIHRoaXMucHJlZml4LFxuICAgICAgQnVmZmVyLmZyb20oa2V5KSxcbiAgICBdKTtcbiAgICBhd2FpdCB0aGlzLmRiLmRlbGV0ZShlbnRyeUtleSk7XG4gIH1cblxuICAvKipcbiAgICogQ2xlYXIgYWxsIGVudHJpZXMgaW4gdGhpcyBjYWNoZVxuICAgKi9cbiAgYXN5bmMgY2xlYXIoKTogUHJvbWlzZTxudW1iZXI+IHtcbiAgICBsZXQgZGVsZXRlZCA9IDA7XG5cbiAgICB0cnkge1xuICAgICAgY29uc3QgdG9EZWxldGU6IEJ1ZmZlcltdID0gW107XG4gICAgICBmb3IgYXdhaXQgKGNvbnN0IFtrZXldIG9mIHRoaXMuZGIuc2NhblByZWZpeCh0aGlzLnByZWZpeCkpIHtcbiAgICAgICAgdG9EZWxldGUucHVzaChrZXkpO1xuICAgICAgfVxuXG4gICAgICBmb3IgKGNvbnN0IGtleSBvZiB0b0RlbGV0ZSkge1xuICAgICAgICBhd2FpdCB0aGlzLmRiLmRlbGV0ZShrZXkpO1xuICAgICAgICBkZWxldGVkKys7XG4gICAgICB9XG4gICAgfSBjYXRjaCAoZXJyb3IpIHtcbiAgICAgIC8vIElmIG9wZXJhdGlvbiBmYWlscywgcmV0dXJuIGNvdW50IHNvIGZhclxuICAgICAgcmV0dXJuIGRlbGV0ZWQ7XG4gICAgfVxuXG4gICAgLy8gUmVzZXQgc3RhdHNcbiAgICB0aGlzLmhpdHMgPSAwO1xuICAgIHRoaXMubWlzc2VzID0gMDtcblxuICAgIHJldHVybiBkZWxldGVkO1xuICB9XG5cbiAgLyoqXG4gICAqIEdldCBjYWNoZSBzdGF0aXN0aWNzXG4gICAqL1xuICBhc3luYyBzdGF0cygpOiBQcm9taXNlPENhY2hlU3RhdHM+IHtcbiAgICBjb25zdCBub3cgPSBEYXRlLm5vdygpO1xuICAgIGxldCBjb3VudCA9IDA7XG4gICAgbGV0IG1lbW9yeVVzYWdlID0gMDtcblxuICAgIHRyeSB7XG4gICAgICBmb3IgYXdhaXQgKGNvbnN0IFtrZXksIHZhbHVlXSBvZiB0aGlzLmRiLnNjYW5QcmVmaXgodGhpcy5wcmVmaXgpKSB7XG4gICAgICAgIGNvbnN0IGVudHJ5OiBDYWNoZUVudHJ5ID0gSlNPTi5wYXJzZSh2YWx1ZS50b1N0cmluZygpKTtcbiAgICAgICAgXG4gICAgICAgIC8vIFNraXAgZXhwaXJlZCBlbnRyaWVzXG4gICAgICAgIGlmIChlbnRyeS50dGwgJiYgZW50cnkudGltZXN0YW1wKSB7XG4gICAgICAgICAgY29uc3QgZXhwaXJlc0F0ID0gZW50cnkudGltZXN0YW1wICsgZW50cnkudHRsICogMTAwMDtcbiAgICAgICAgICBpZiAobm93ID4gZXhwaXJlc0F0KSB7XG4gICAgICAgICAgICBjb250aW51ZTtcbiAgICAgICAgICB9XG4gICAgICAgIH1cblxuICAgICAgICBjb3VudCsrO1xuICAgICAgICBtZW1vcnlVc2FnZSArPSBrZXkubGVuZ3RoICsgdmFsdWUubGVuZ3RoO1xuICAgICAgfVxuICAgIH0gY2F0Y2ggKGVycm9yKSB7XG4gICAgICAvLyBSZXR1cm4gcGFydGlhbCBzdGF0cyBpZiBvcGVyYXRpb24gZmFpbHNcbiAgICB9XG5cbiAgICBjb25zdCB0b3RhbCA9IHRoaXMuaGl0cyArIHRoaXMubWlzc2VzO1xuICAgIGNvbnN0IGhpdFJhdGUgPSB0b3RhbCA+IDAgPyB0aGlzLmhpdHMgLyB0b3RhbCA6IDA7XG5cbiAgICByZXR1cm4ge1xuICAgICAgY291bnQsXG4gICAgICBoaXRzOiB0aGlzLmhpdHMsXG4gICAgICBtaXNzZXM6IHRoaXMubWlzc2VzLFxuICAgICAgaGl0UmF0ZSxcbiAgICAgIG1lbW9yeVVzYWdlLFxuICAgIH07XG4gIH1cblxuICAvKipcbiAgICogUHVyZ2UgZXhwaXJlZCBlbnRyaWVzXG4gICAqL1xuICBhc3luYyBwdXJnZUV4cGlyZWQoKTogUHJvbWlzZTxudW1iZXI+IHtcbiAgICBjb25zdCBub3cgPSBEYXRlLm5vdygpO1xuICAgIGxldCBwdXJnZWQgPSAwO1xuXG4gICAgdHJ5IHtcbiAgICAgIGNvbnN0IHRvRGVsZXRlOiBCdWZmZXJbXSA9IFtdO1xuXG4gICAgICBmb3IgYXdhaXQgKGNvbnN0IFtrZXksIHZhbHVlXSBvZiB0aGlzLmRiLnNjYW5QcmVmaXgodGhpcy5wcmVmaXgpKSB7XG4gICAgICAgIGNvbnN0IGVudHJ5OiBDYWNoZUVudHJ5ID0gSlNPTi5wYXJzZSh2YWx1ZS50b1N0cmluZygpKTtcbiAgICAgICAgXG4gICAgICAgIGlmIChlbnRyeS50dGwgJiYgZW50cnkudGltZXN0YW1wKSB7XG4gICAgICAgICAgY29uc3QgZXhwaXJlc0F0ID0gZW50cnkudGltZXN0YW1wICsgZW50cnkudHRsICogMTAwMDtcbiAgICAgICAgICBpZiAobm93ID4gZXhwaXJlc0F0KSB7XG4gICAgICAgICAgICB0b0RlbGV0ZS5wdXNoKGtleSk7XG4gICAgICAgICAgfVxuICAgICAgICB9XG4gICAgICB9XG5cbiAgICAgIGZvciAoY29uc3Qga2V5IG9mIHRvRGVsZXRlKSB7XG4gICAgICAgIGF3YWl0IHRoaXMuZGIuZGVsZXRlKGtleSk7XG4gICAgICAgIHB1cmdlZCsrO1xuICAgICAgfVxuICAgIH0gY2F0Y2ggKGVycm9yKSB7XG4gICAgICAvLyBSZXR1cm4gY291bnQgc28gZmFyXG4gICAgICByZXR1cm4gcHVyZ2VkO1xuICAgIH1cblxuICAgIHJldHVybiBwdXJnZWQ7XG4gIH1cbn1cbiJdfQ==

package/dist/types/context-builder.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Context Query Builder for LLM Context Assembly
+ *
+ * Token-aware context assembly with priority-based truncation.
+ */
+export declare enum ContextOutputFormat {
+    TOON = "toon",
+    JSON = "json",
+    MARKDOWN = "markdown"
+}
+export declare enum TruncationStrategy {
+    TAIL_DROP = "tail_drop",// Drop from end
+    HEAD_DROP = "head_drop",// Drop from beginning
+    PROPORTIONAL = "proportional"
+}
+export interface ContextResult {
+    text: string;
+    tokenCount: number;
+    sections: Array<{
+        name: string;
+        tokenCount: number;
+        truncated: boolean;
+    }>;
+}
+/**
+ * Context Query Builder for assembling LLM context
+ */
+export declare class ContextQueryBuilder {
+    private sessionId?;
+    private tokenBudget;
+    private format;
+    private truncation;
+    private sections;
+    private currentSection?;
+    /**
+     * Set session ID for context
+     */
+    forSession(sessionId: string): this;
+    /**
+     * Set token budget
+     */
+    withBudget(tokens: number): this;
+    /**
+     * Set output format
+     */
+    setFormat(format: ContextOutputFormat): this;
+    /**
+     * Set truncation strategy
+     */
+    setTruncation(strategy: TruncationStrategy): this;
+    /**
+     * Add literal text section
+     */
+    literal(name: string, priority: number, text: string): this;
+    /**
+     * Start a new section
+     */
+    section(name: string, priority: number): this;
+    /**
+     * Add content to current section
+     */
+    get(path: string): this;
+    /**
+     * Add last N records query
+     */
+    last(n: number, table: string): this;
+    /**
+     * Add where equals condition
+     */
+    whereEq(field: string, value: any): this;
+    /**
+     * Add vector search
+     */
+    search(collection: string, embedding: string, k: number): this;
+    /**
+     * Add SQL query
+     */
+    sql(query: string): this;
+    /**
+     * Finish current section
+     */
+    done(): this;
+    /**
+     * Execute and build context
+     */
+    execute(): ContextResult;
+    private estimateTokens;
+    private truncateText;
+    private buildToonFormat;
+    private buildJsonFormat;
+    private buildMarkdownFormat;
+}
+/**
+ * Create a context query builder
+ */
+export declare function createContextBuilder(): ContextQueryBuilder;
+//# sourceMappingURL=context-builder.d.ts.map

package/dist/types/context-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../../src/context-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oBAAY,mBAAmB;IAC7B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,aAAa;CACtB;AAED,oBAAY,kBAAkB;IAC5B,SAAS,cAAc,CAAQ,gBAAgB;IAC/C,SAAS,cAAc,CAAQ,sBAAsB;IACrD,YAAY,iBAAiB;CAC9B;AASD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,MAAM,CAAiD;IAC/D,OAAO,CAAC,UAAU,CAAoD;IACtE,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,cAAc,CAAC,CAAU;IAEjC;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKnC;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKhC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAK5C;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAKjD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAW3D;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAU7C;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQvB;;OAEG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQpC;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAQxC;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ9D;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQxB;;OAEG;IACH,IAAI,IAAI,IAAI;IASZ;;OAEG;IACH,OAAO,IAAI,aAAa;IA2FxB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,mBAAmB;CAY5B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,mBAAmB,CAE1D"}

package/dist/types/database.d.ts

@@ -99,7 +99,7 @@ export declare class Transaction {
  *
  * @example
  * ```typescript
- * import { Database } from '@sushanth/sochdb';
+ * import { Database } from '@sochdb/sochdb';
  *
  * // Open a database
  * const db = await Database.open('./my_database');

package/dist/types/embedded/database.d.ts

@@ -18,7 +18,7 @@ export interface EmbeddedDatabaseConfig {
  *
  * @example
  * ```typescript
- * import { EmbeddedDatabase } from '@sushanth/sochdb';
+ * import { EmbeddedDatabase } from '@sochdb/sochdb';
  *
  * const db = await EmbeddedDatabase.open('./mydb');
  * await db.put(Buffer.from('key'), Buffer.from('value'));

package/dist/types/embedded/ffi/hnsw-bindings.d.ts

@@ -0,0 +1,90 @@
+/**
+ * HNSW Vector Index FFI Bindings
+ *
+ * Native vector search using HNSW (Hierarchical Navigable Small World) algorithm.
+ *
+ * @see sochdb-index/src/ffi.rs
+ */
+export interface SearchResult {
+    id: string;
+    distance: number;
+}
+export interface HnswConfig {
+    dimension: number;
+    maxConnections?: number;
+    efConstruction?: number;
+    efSearch?: number;
+}
+export declare class HnswBindings {
+    private static instance;
+    private lib;
+    hnsw_new: any;
+    hnsw_free: any;
+    hnsw_insert: any;
+    hnsw_insert_batch: any;
+    hnsw_insert_flat: any;
+    hnsw_insert_batch_flat: any;
+    hnsw_search: any;
+    hnsw_search_fast: any;
+    hnsw_search_ultra: any;
+    hnsw_len: any;
+    hnsw_dimension: any;
+    hnsw_set_ef_search: any;
+    hnsw_get_ef_search: any;
+    hnsw_build_flat_cache: any;
+    private constructor();
+    static getInstance(): HnswBindings;
+}
+/**
+ * High-level HNSW Index wrapper
+ */
+export declare class HnswIndex {
+    private ptr;
+    private bindings;
+    private _dimension;
+    private _efSearch;
+    constructor(config: HnswConfig);
+    /**
+     * Insert a single vector
+     */
+    insert(id: string, vector: number[]): void;
+    /**
+     * Insert multiple vectors in batch (faster)
+     */
+    insertBatch(ids: string[], vectors: number[][]): void;
+    /**
+     * Search for k nearest neighbors
+     */
+    search(queryVector: number[], k: number, fast?: boolean): SearchResult[];
+    /**
+     * Ultra-fast search with minimal ef_search
+     */
+    searchUltra(queryVector: number[], k: number): SearchResult[];
+    /**
+     * Get number of vectors in index
+     */
+    get length(): number;
+    /**
+     * Get vector dimension
+     */
+    get dimension(): number;
+    /**
+     * Set ef_search parameter (controls search quality vs speed)
+     */
+    set efSearch(value: number);
+    /**
+     * Get ef_search parameter
+     */
+    get efSearch(): number;
+    /**
+     * Build flat cache for faster searches
+     */
+    buildFlatCache(): void;
+    /**
+     * Free native resources
+     */
+    close(): void;
+    private stringToId;
+    private idToString;
+}
+//# sourceMappingURL=hnsw-bindings.d.ts.map

package/dist/types/embedded/ffi/hnsw-bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw-bindings.d.ts","sourceRoot":"","sources":["../../../../src/embedded/ffi/hnsw-bindings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,YAAY;IACrB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAe;IACtC,OAAO,CAAC,GAAG,CAAM;IAGV,QAAQ,EAAE,GAAG,CAAC;IACd,SAAS,EAAE,GAAG,CAAC;IACf,WAAW,EAAE,GAAG,CAAC;IACjB,iBAAiB,EAAE,GAAG,CAAC;IACvB,gBAAgB,EAAE,GAAG,CAAC;IACtB,sBAAsB,EAAE,GAAG,CAAC;IAC5B,WAAW,EAAE,GAAG,CAAC;IACjB,gBAAgB,EAAE,GAAG,CAAC;IACtB,iBAAiB,EAAE,GAAG,CAAC;IACvB,QAAQ,EAAE,GAAG,CAAC;IACd,cAAc,EAAE,GAAG,CAAC;IACpB,kBAAkB,EAAE,GAAG,CAAC;IACxB,kBAAkB,EAAE,GAAG,CAAC;IACxB,qBAAqB,EAAE,GAAG,CAAC;IAElC,OAAO;WAuFO,WAAW,IAAI,YAAY;CAM5C;AAED;;GAEG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,UAAU;IAmB9B;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAgB1C;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;IAmCrD;;OAEG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,OAAe,GAAG,YAAY,EAAE;IAgC/E;;OAEG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE;IA6B7D;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,EAGzB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,cAAc,IAAI,IAAI;IAOtB;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,UAAU;CAIrB"}

package/dist/types/embedded/ffi/library-finder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library-finder.d.ts","sourceRoot":"","sources":["../../../../src/embedded/ffi/library-finder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAyDpC"}
+{"version":3,"file":"library-finder.d.ts","sourceRoot":"","sources":["../../../../src/embedded/ffi/library-finder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAiEpC"}

package/dist/types/embedded/index.d.ts

@@ -6,4 +6,5 @@
  */
 export { EmbeddedDatabase, EmbeddedDatabaseConfig } from './database';
 export { EmbeddedTransaction } from './transaction';
+export { HnswIndex, HnswConfig, HnswBindings, SearchResult } from './ffi/hnsw-bindings';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/embedded/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/embedded/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/embedded/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/types/errors.d.ts

@@ -3,11 +3,31 @@
  *
  * @packageDocumentation
  */
+/**
+ * Error codes matching Rust error codes.
+ */
+export declare enum ErrorCode {
+    CONNECTION_FAILED = 1001,
+    CONNECTION_TIMEOUT = 1002,
+    CONNECTION_CLOSED = 1003,
+    PROTOCOL_ERROR = 1004,
+    TRANSACTION_ABORTED = 2001,
+    TRANSACTION_CONFLICT = 2002,
+    INTERNAL_ERROR = 9001,
+    STORAGE_ERROR = 9003,
+    DATABASE_LOCKED = 10001,
+    LOCK_TIMEOUT = 10002,
+    EPOCH_MISMATCH = 10003,
+    SPLIT_BRAIN = 10004,
+    STALE_LOCK = 10005
+}
 /**
  * Base error class for all SochDB errors.
  */
 export declare class SochDBError extends Error {
-    constructor(message: string);
+    readonly code: ErrorCode;
+    readonly remediation?: string;
+    constructor(message: string, code?: ErrorCode, remediation?: string);
 }
 /**
  * Error thrown when connection to the database fails.
@@ -33,4 +53,40 @@ export declare class ProtocolError extends SochDBError {
 export declare class DatabaseError extends SochDBError {
     constructor(message: string);
 }
+/**
+ * Base class for lock-related errors.
+ */
+export declare class LockError extends SochDBError {
+    constructor(message: string, code?: ErrorCode, remediation?: string);
+}
+/**
+ * Error thrown when database is locked by another process.
+ */
+export declare class DatabaseLockedError extends LockError {
+    readonly path: string;
+    readonly holderPid?: number;
+    constructor(path: string, holderPid?: number);
+}
+/**
+ * Error thrown when timed out waiting for database lock.
+ */
+export declare class LockTimeoutError extends LockError {
+    readonly path: string;
+    readonly timeoutSecs: number;
+    constructor(path: string, timeoutSecs: number);
+}
+/**
+ * Error thrown when WAL epoch mismatch detected (stale writer).
+ */
+export declare class EpochMismatchError extends LockError {
+    readonly expected: number;
+    readonly actual: number;
+    constructor(expected: number, actual: number);
+}
+/**
+ * Error thrown when split-brain condition detected (multiple writers).
+ */
+export declare class SplitBrainError extends LockError {
+    constructor(message?: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,EAAE,MAAM;CAK5B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH;;GAEG;AACH,oBAAY,SAAS;IAEnB,iBAAiB,OAAO;IACxB,kBAAkB,OAAO;IACzB,iBAAiB,OAAO;IACxB,cAAc,OAAO;IAGrB,mBAAmB,OAAO;IAC1B,oBAAoB,OAAO;IAG3B,cAAc,OAAO;IACrB,aAAa,OAAO;IAGpB,eAAe,QAAQ;IACvB,YAAY,QAAQ;IACpB,cAAc,QAAQ;IACtB,WAAW,QAAQ;IACnB,UAAU,QAAQ;CACnB;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,WAAW,CAAC,EAAE,MAAM,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,SAAoC,EAAE,WAAW,CAAC,EAAE,MAAM;CAO9F;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,EAAE,MAAM;CAK5B;AAMD;;GAEG;AACH,qBAAa,SAAU,SAAQ,WAAW;gBAC5B,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,SAAqC,EAAE,WAAW,CAAC,EAAE,MAAM;CAK/F;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEvB,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAU7C;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,WAAW,EAAE,MAAM,CAAC;gBAExB,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAW9C;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAW7C;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,GAAE,MAAwD;CAS9E"}

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * SochDB Node.js SDK v0.4.0
+ * SochDB Node.js SDK v0.4.2
  *
  * Dual-mode architecture: Embedded (FFI) + Server (gRPC/IPC)
  *
@@ -35,16 +35,28 @@
  * await client.putKv('key', Buffer.from('value'));
  * ```
  */
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.4.2";
 export { EmbeddedDatabase, EmbeddedDatabaseConfig } from './embedded';
 export { EmbeddedTransaction } from './embedded';
+export { HnswIndex, HnswConfig, HnswBindings } from './embedded';
+export { SearchResult as HnswSearchResult } from './embedded';
 export { EmbeddedDatabase as Database } from './embedded';
+export { Namespace, Collection, DistanceMetric, NamespaceNotFoundError, NamespaceExistsError, CollectionNotFoundError, CollectionExistsError, } from './namespace';
+export type { NamespaceConfig, CollectionConfig, SearchRequest, SearchResult as NamespaceSearchResult, } from './namespace';
+export { PriorityQueue, TaskState, createQueue, } from './queue';
+export type { QueueConfig, QueueKey, Task, QueueStats, } from './queue';
+export { SemanticCache, } from './semantic-cache';
+export type { CacheEntry, CacheHit, CacheStats, } from './semantic-cache';
+export { ContextQueryBuilder, ContextOutputFormat, TruncationStrategy, createContextBuilder, } from './context-builder';
+export type { ContextResult, } from './context-builder';
+export { ExtractionPipeline, Consolidator, HybridRetriever, AllowedSet, NamespacePolicy, } from './memory';
+export type { Entity, Relation, Assertion, RawAssertion, CanonicalFact, ExtractionResult, ExtractionSchema, ConsolidationConfig, RetrievalConfig, RetrievalResult, RetrievalResponse, NamespaceGrant, } from './memory';
 export { SochDBClient } from './grpc-client';
 export type { SearchResult, Document, GraphNode, GraphEdge, } from './grpc-client';
 export { IpcClient } from './ipc-client';
 export { WireFormat, ContextFormat, CanonicalFormat, FormatCapabilities, FormatConversionError, } from './format';
 export { Query } from './query';
 export type { QueryResult } from './query';
-export { SochDBError, ConnectionError, TransactionError, ProtocolError, DatabaseError, } from './errors';
+export { SochDBError, ConnectionError, TransactionError, ProtocolError, DatabaseError, ErrorCode, LockError, DatabaseLockedError, LockTimeoutError, EpochMismatchError, SplitBrainError, } from './errors';
 export { SochDBClient as GrpcClient } from './grpc-client';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EACL,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,YAAY,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9D,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,EACL,SAAS,EACT,UAAU,EACV,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,IAAI,qBAAqB,GACtC,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,aAAa,EACb,SAAS,EACT,WAAW,GACZ,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,WAAW,EACX,QAAQ,EACR,IAAI,EACJ,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,aAAa,GACd,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,UAAU,EACV,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,MAAM,EACN,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EACL,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EAEb,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,YAAY,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/types/ipc-client.d.ts

@@ -51,7 +51,7 @@ export interface IpcClientConfig {
  *
  * @example
  * ```typescript
- * import { IpcClient } from '@sushanth/sochdb';
+ * import { IpcClient } from '@sochdb/sochdb';
  *
  * const client = await IpcClient.connect('/tmp/sochdb.sock');
  *