chore: recovery checkpoint - v3.0 API successfully recovered

CRITICAL CHECKPOINT - DO NOT PUSH TO GITHUB

Recovery Status:
- Successfully recovered brainy.ts from compiled JavaScript
- All core v3.0 API methods functional (add, get, update, delete, relate, find, etc.)
- Neural subsystem intact (562KB embedded patterns, NLP working)
- Augmentation pipeline operational (20+ augmentations)
- HNSW clustering system complete
- Triple Intelligence compiled (needs constructor fix)
- Test suite validates functionality

Changes preserved:
- 898 files with changes from last 3 days
- 144,475 insertions
- All augmentation improvements
- All test coverage enhancements
- Complete v3.0 feature set

This is a LOCAL checkpoint only - contains recovered work after corruption incident.
Created backup in .backups/brainy-full-20250910-151314.tar.gz

Branch: recovery-checkpoint-20250910-151433
Date: Wed Sep 10 03:18:04 PM PDT 2025

.recovery-workspace/dist-backup-20250910-141917/utils/unifiedCache.d.ts

@@ -0,0 +1,103 @@
+/**
+ * UnifiedCache - Single cache for both HNSW and MetadataIndex
+ * Prevents resource competition with cost-aware eviction
+ */
+export interface CacheItem {
+    key: string;
+    type: 'hnsw' | 'metadata' | 'embedding' | 'other';
+    data: any;
+    size: number;
+    rebuildCost: number;
+    lastAccess: number;
+    accessCount: number;
+}
+export interface UnifiedCacheConfig {
+    maxSize?: number;
+    enableRequestCoalescing?: boolean;
+    enableFairnessCheck?: boolean;
+    fairnessCheckInterval?: number;
+    persistPatterns?: boolean;
+}
+export declare class UnifiedCache {
+    private cache;
+    private access;
+    private loadingPromises;
+    private typeAccessCounts;
+    private totalAccessCount;
+    private currentSize;
+    private readonly maxSize;
+    private readonly config;
+    constructor(config?: UnifiedCacheConfig);
+    /**
+     * Get item from cache with request coalescing
+     */
+    get(key: string, loadFn?: () => Promise<any>): Promise<any>;
+    /**
+     * Set item in cache with cost-aware eviction
+     */
+    set(key: string, data: any, type: 'hnsw' | 'metadata' | 'embedding' | 'other', size: number, rebuildCost?: number): void;
+    /**
+     * Evict item with lowest value (access count / rebuild cost)
+     */
+    private evictLowestValue;
+    /**
+     * Size-aware eviction - try to match needed size
+     */
+    evictForSize(bytesNeeded: number): boolean;
+    /**
+     * Fairness monitoring - prevent one type from hogging cache
+     */
+    private startFairnessMonitor;
+    private checkFairness;
+    /**
+     * Force evict items of a specific type
+     */
+    private evictType;
+    /**
+     * Delete specific item from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear cache or specific type
+     */
+    clear(type?: 'hnsw' | 'metadata' | 'embedding' | 'other'): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        totalSize: number;
+        maxSize: number;
+        utilization: number;
+        itemCount: number;
+        typeSizes: {
+            hnsw: number;
+            metadata: number;
+            embedding: number;
+            other: number;
+        };
+        typeCounts: {
+            hnsw: number;
+            metadata: number;
+            embedding: number;
+            other: number;
+        };
+        typeAccessCounts: {
+            hnsw: number;
+            metadata: number;
+            embedding: number;
+            other: number;
+        };
+        totalAccessCount: number;
+        hitRate: number;
+    };
+    /**
+     * Save access patterns for cold start optimization
+     */
+    saveAccessPatterns(): Promise<any>;
+    /**
+     * Load access patterns for warm start
+     */
+    loadAccessPatterns(patterns: any): Promise<void>;
+}
+export declare function getGlobalCache(config?: UnifiedCacheConfig): UnifiedCache;
+export declare function clearGlobalCache(): void;