@soulcraft/cortex 1.3.1 → 1.4.1

package/dist/utils/NativeUnifiedCache.d.ts

@@ -0,0 +1,81 @@
+/**
+ * NativeUnifiedCacheWrapper — Native Rust eviction engine with JS data storage
+ *
+ * The Rust NativeUnifiedCache manages eviction metadata (key, type, size, cost,
+ * access counts) but does NOT store actual JS data. This wrapper:
+ * - Keeps a Map<string, any> for actual cached data
+ * - Delegates eviction decisions to the native engine
+ * - Implements request coalescing in JS (same as brainy's UnifiedCache)
+ * - Drop-in replacement for brainy's UnifiedCache
+ */
+import type { UnifiedCacheConfig } from '@soulcraft/brainy/internals';
+export declare class NativeUnifiedCacheWrapper {
+    private data;
+    private native;
+    private loadingPromises;
+    private readonly maxSize;
+    private readonly config;
+    private readonly memoryInfo;
+    private readonly allocationStrategy;
+    private memoryPressureCheckTimer;
+    private lastMemoryWarning;
+    constructor(config?: UnifiedCacheConfig);
+    get(key: string, loadFn?: () => Promise<any>): Promise<any>;
+    getSync(key: string): any | undefined;
+    set(key: string, data: any, type: 'hnsw' | 'metadata' | 'embedding' | 'other', size: number, rebuildCost?: number): void;
+    delete(key: string): boolean;
+    deleteByPrefix(prefix: string): number;
+    clear(type?: 'hnsw' | 'metadata' | 'embedding' | 'other'): void;
+    evictForSize(bytesNeeded: number): boolean;
+    private startFairnessMonitor;
+    private checkFairness;
+    private startMemoryPressureMonitor;
+    private checkMemoryPressure;
+    getStats(): {
+        totalSize: number;
+        maxSize: number;
+        utilization: number;
+        itemCount: number;
+        typeSizes: Record<string, number>;
+        typeCounts: Record<string, number>;
+        typeAccessCounts: Record<string, number>;
+        totalAccessCount: number;
+        hitRate: number;
+        memory: {
+            available: number;
+            source: "cgroup-v2" | "cgroup-v1" | "system" | "fallback";
+            isContainer: boolean;
+            systemTotal: number;
+            allocationRatio: number;
+            environment: "production" | "development" | "container" | "unknown";
+        };
+    };
+    getMemoryInfo(): {
+        memoryInfo: {
+            available: number;
+            source: "cgroup-v2" | "cgroup-v1" | "system" | "fallback";
+            isContainer: boolean;
+            systemTotal: number;
+            free: number;
+            warnings: string[];
+        };
+        allocationStrategy: {
+            cacheSize: number;
+            ratio: number;
+            minSize: number;
+            maxSize: number | null;
+            environment: "production" | "development" | "container" | "unknown";
+            modelMemory: number;
+            modelPrecision: "q8" | "fp32";
+            availableForCache: number;
+            reasoning: string;
+        };
+        currentPressure: {
+            pressure: "none" | "moderate" | "high" | "critical";
+            warnings: string[];
+        };
+    };
+    saveAccessPatterns(): Promise<any>;
+    loadAccessPatterns(patterns: any): Promise<void>;
+}
+//# sourceMappingURL=NativeUnifiedCache.d.ts.map

package/dist/utils/NativeUnifiedCache.js

@@ -0,0 +1,268 @@
+/**
+ * NativeUnifiedCacheWrapper — Native Rust eviction engine with JS data storage
+ *
+ * The Rust NativeUnifiedCache manages eviction metadata (key, type, size, cost,
+ * access counts) but does NOT store actual JS data. This wrapper:
+ * - Keeps a Map<string, any> for actual cached data
+ * - Delegates eviction decisions to the native engine
+ * - Implements request coalescing in JS (same as brainy's UnifiedCache)
+ * - Drop-in replacement for brainy's UnifiedCache
+ */
+import { loadNativeModule } from '../native/index.js';
+import { prodLog } from '@soulcraft/brainy/internals';
+import { getRecommendedCacheConfig, formatBytes, checkMemoryPressure, } from '@soulcraft/brainy/internals';
+// Cache type enum matching Rust (0-3)
+const CACHE_TYPE_MAP = {
+    hnsw: 0,
+    metadata: 1,
+    embedding: 2,
+    other: 3,
+};
+export class NativeUnifiedCacheWrapper {
+    data = new Map();
+    native;
+    loadingPromises = new Map();
+    maxSize;
+    config;
+    memoryInfo;
+    allocationStrategy;
+    memoryPressureCheckTimer = null;
+    lastMemoryWarning = 0;
+    constructor(config = {}) {
+        const recommendation = getRecommendedCacheConfig({
+            manualSize: config.maxSize,
+            minSize: config.minSize,
+            developmentMode: config.developmentMode,
+        });
+        this.memoryInfo = recommendation.memoryInfo;
+        this.allocationStrategy = recommendation.allocation;
+        this.maxSize = recommendation.allocation.cacheSize;
+        prodLog.info(`NativeUnifiedCache initialized: ${formatBytes(this.maxSize)} ` +
+            `(${this.allocationStrategy.environment} mode, ` +
+            `${(this.allocationStrategy.ratio * 100).toFixed(0)}% of ${formatBytes(this.allocationStrategy.availableForCache)} ` +
+            `after ${formatBytes(this.allocationStrategy.modelMemory)} ${this.allocationStrategy.modelPrecision.toUpperCase()} model)`);
+        for (const warning of recommendation.warnings) {
+            prodLog.warn(`NativeUnifiedCache: ${warning}`);
+        }
+        this.config = {
+            enableRequestCoalescing: true,
+            enableFairnessCheck: true,
+            fairnessCheckInterval: 30000,
+            persistPatterns: true,
+            enableMemoryMonitoring: true,
+            memoryCheckInterval: 30000,
+            ...config,
+        };
+        const bindings = loadNativeModule();
+        this.native = new bindings.NativeUnifiedCache(this.maxSize);
+        if (this.config.enableFairnessCheck) {
+            this.startFairnessMonitor();
+        }
+        if (this.config.enableMemoryMonitoring) {
+            this.startMemoryPressureMonitor();
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Core API
+    // ---------------------------------------------------------------------------
+    async get(key, loadFn) {
+        // Check JS data map
+        const cached = this.data.get(key);
+        if (cached !== undefined) {
+            this.native.recordAccess(key);
+            return cached;
+        }
+        if (!loadFn)
+            return undefined;
+        // Request coalescing
+        if (this.config.enableRequestCoalescing && this.loadingPromises.has(key)) {
+            return this.loadingPromises.get(key);
+        }
+        const loadPromise = loadFn();
+        if (this.config.enableRequestCoalescing) {
+            this.loadingPromises.set(key, loadPromise);
+        }
+        try {
+            const result = await loadPromise;
+            return result;
+        }
+        finally {
+            if (this.config.enableRequestCoalescing) {
+                this.loadingPromises.delete(key);
+            }
+        }
+    }
+    getSync(key) {
+        const cached = this.data.get(key);
+        if (cached !== undefined) {
+            this.native.recordAccess(key);
+            return cached;
+        }
+        return undefined;
+    }
+    set(key, data, type, size, rebuildCost = 1) {
+        const cacheType = CACHE_TYPE_MAP[type] ?? 3;
+        // Remove existing entry if present
+        if (this.data.has(key)) {
+            this.native.remove(key);
+        }
+        // Insert into native (may trigger eviction)
+        const evictionResult = this.native.insert(key, cacheType, size, rebuildCost);
+        // Remove evicted keys from JS data
+        for (const evictedKey of evictionResult.evictedKeys) {
+            this.data.delete(evictedKey);
+        }
+        // Store actual data in JS
+        this.data.set(key, data);
+    }
+    delete(key) {
+        const existed = this.data.has(key);
+        if (existed) {
+            this.native.remove(key);
+            this.data.delete(key);
+        }
+        return existed;
+    }
+    deleteByPrefix(prefix) {
+        const removedKeys = this.native.removeByPrefix(prefix);
+        for (const key of removedKeys) {
+            this.data.delete(key);
+        }
+        return removedKeys.length;
+    }
+    clear(type) {
+        if (!type) {
+            const clearedKeys = this.native.clear();
+            for (const key of clearedKeys) {
+                this.data.delete(key);
+            }
+            // Also clear any remaining data entries
+            this.data.clear();
+        }
+        else {
+            const cacheType = CACHE_TYPE_MAP[type] ?? 3;
+            const clearedKeys = this.native.clear(cacheType);
+            for (const key of clearedKeys) {
+                this.data.delete(key);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Eviction
+    // ---------------------------------------------------------------------------
+    evictForSize(bytesNeeded) {
+        const result = this.native.evictForSize(bytesNeeded);
+        for (const key of result.evictedKeys) {
+            this.data.delete(key);
+        }
+        return result.bytesFreed >= bytesNeeded;
+    }
+    // ---------------------------------------------------------------------------
+    // Fairness
+    // ---------------------------------------------------------------------------
+    startFairnessMonitor() {
+        const timer = setInterval(() => {
+            this.checkFairness();
+        }, this.config.fairnessCheckInterval);
+        if (timer.unref)
+            timer.unref();
+    }
+    checkFairness() {
+        const result = this.native.checkFairness();
+        for (const key of result.evictedKeys) {
+            this.data.delete(key);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Memory pressure
+    // ---------------------------------------------------------------------------
+    startMemoryPressureMonitor() {
+        const checkInterval = this.config.memoryCheckInterval || 30000;
+        this.memoryPressureCheckTimer = setInterval(() => {
+            this.checkMemoryPressure();
+        }, checkInterval);
+        if (this.memoryPressureCheckTimer.unref) {
+            this.memoryPressureCheckTimer.unref();
+        }
+    }
+    checkMemoryPressure() {
+        const stats = this.native.getStats();
+        const pressure = checkMemoryPressure(stats.totalSize, this.memoryInfo);
+        const now = Date.now();
+        const fiveMinutes = 5 * 60 * 1000;
+        if (pressure.warnings.length > 0 && now - this.lastMemoryWarning > fiveMinutes) {
+            for (const warning of pressure.warnings) {
+                prodLog.warn(`NativeUnifiedCache: ${warning}`);
+            }
+            this.lastMemoryWarning = now;
+        }
+        if (pressure.pressure === 'critical') {
+            const targetSize = Math.floor(this.maxSize * 0.7);
+            const bytesToFree = stats.totalSize - targetSize;
+            if (bytesToFree > 0) {
+                prodLog.warn(`NativeUnifiedCache: Critical memory pressure - forcing eviction of ${formatBytes(bytesToFree)}`);
+                this.evictForSize(bytesToFree);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Statistics
+    // ---------------------------------------------------------------------------
+    getStats() {
+        const nativeStats = this.native.getStats();
+        const typeNames = ['hnsw', 'metadata', 'embedding', 'other'];
+        const typeSizes = {};
+        const typeCounts = {};
+        const typeAccessCounts = {};
+        for (let i = 0; i < typeNames.length; i++) {
+            typeSizes[typeNames[i]] = nativeStats.typeSizes[i] || 0;
+            typeCounts[typeNames[i]] = nativeStats.typeCounts[i] || 0;
+            typeAccessCounts[typeNames[i]] = nativeStats.typeAccessCounts[i] || 0;
+        }
+        const hitRate = nativeStats.totalAccessCount > 0
+            ? nativeStats.itemCount / nativeStats.totalAccessCount
+            : 0;
+        return {
+            totalSize: nativeStats.totalSize,
+            maxSize: nativeStats.maxSize,
+            utilization: nativeStats.maxSize > 0 ? nativeStats.totalSize / nativeStats.maxSize : 0,
+            itemCount: nativeStats.itemCount,
+            typeSizes,
+            typeCounts,
+            typeAccessCounts,
+            totalAccessCount: nativeStats.totalAccessCount,
+            hitRate,
+            memory: {
+                available: this.memoryInfo.available,
+                source: this.memoryInfo.source,
+                isContainer: this.memoryInfo.isContainer,
+                systemTotal: this.memoryInfo.systemTotal,
+                allocationRatio: this.allocationStrategy.ratio,
+                environment: this.allocationStrategy.environment,
+            },
+        };
+    }
+    getMemoryInfo() {
+        const stats = this.native.getStats();
+        return {
+            memoryInfo: { ...this.memoryInfo },
+            allocationStrategy: { ...this.allocationStrategy },
+            currentPressure: checkMemoryPressure(stats.totalSize, this.memoryInfo),
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Access pattern persistence
+    // ---------------------------------------------------------------------------
+    async saveAccessPatterns() {
+        if (!this.config.persistPatterns)
+            return;
+        const json = this.native.saveAccessPatterns();
+        return JSON.parse(json);
+    }
+    async loadAccessPatterns(patterns) {
+        if (!patterns)
+            return;
+        this.native.loadAccessPatterns(JSON.stringify(patterns));
+    }
+}
+//# sourceMappingURL=NativeUnifiedCache.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cortex",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Native Rust acceleration for Brainy — SIMD distance, vector quantization, zero-copy mmap, native embeddings. Commercial license required (14-day free trial).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",