@soulcraft/brainy 3.44.0 → 3.46.0

package/dist/storage/adapters/typeAwareStorageAdapter.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Type-Aware Storage Adapter
+ *
+ * Implements type-first storage architecture for billion-scale optimization
+ *
+ * Key Features:
+ * - Type-first paths: entities/nouns/{type}/vectors/{shard}/{uuid}.json
+ * - Fixed-size type tracking: Uint32Array(31) for nouns, Uint32Array(40) for verbs
+ * - O(1) type filtering: Can list entities by type via directory structure
+ * - Zero technical debt: Clean implementation, no legacy paths
+ *
+ * Memory Impact @ 1B Scale:
+ * - Type tracking: 284 bytes (vs ~120KB with Maps) = -99.76%
+ * - Metadata index: 3GB (vs 5GB) = -40% (when combined with TypeFirstMetadataIndex)
+ * - Total system: 69GB (vs 557GB) = -88%
+ *
+ * @version 3.45.0
+ * @since Phase 1 - Type-First Implementation
+ */
+import { BaseStorage } from '../baseStorage.js';
+import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
+import { NounType, VerbType } from '../../types/graphTypes.js';
+/**
+ * Options for TypeAwareStorageAdapter
+ */
+export interface TypeAwareStorageOptions {
+    /**
+     * Underlying storage adapter to delegate file operations to
+     * (e.g., FileSystemStorage, S3CompatibleStorage, MemoryStorage)
+     */
+    underlyingStorage: BaseStorage;
+    /**
+     * Optional: Enable verbose logging for debugging
+     */
+    verbose?: boolean;
+}
+/**
+ * Type-Aware Storage Adapter
+ *
+ * Wraps an underlying storage adapter and adds type-first routing
+ * Tracks types with fixed-size arrays for billion-scale efficiency
+ */
+export declare class TypeAwareStorageAdapter extends BaseStorage {
+    private underlying;
+    private verbose;
+    private nounCountsByType;
+    private verbCountsByType;
+    private nounTypeCache;
+    private verbTypeCache;
+    constructor(options: TypeAwareStorageOptions);
+    /**
+     * Helper to access protected methods on underlying storage
+     * TypeScript doesn't allow calling protected methods across instances,
+     * so we cast to any to bypass this restriction
+     */
+    private get u();
+    /**
+     * Initialize storage adapter
+     */
+    init(): Promise<void>;
+    /**
+     * Load type statistics from storage
+     * Rebuilds type counts if needed
+     */
+    private loadTypeStatistics;
+    /**
+     * Save type statistics to storage
+     */
+    private saveTypeStatistics;
+    /**
+     * Get noun type from noun object or cache
+     */
+    private getNounType;
+    /**
+     * Get verb type from verb object or cache
+     */
+    private getVerbType;
+    /**
+     * Save noun (type-first path)
+     */
+    protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
+    /**
+     * Get noun (type-first path)
+     */
+    protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
+    /**
+     * Get nouns by noun type (O(1) with type-first paths!)
+     */
+    protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
+    /**
+     * Delete noun (type-first path)
+     */
+    protected deleteNoun_internal(id: string): Promise<void>;
+    /**
+     * Save verb (type-first path)
+     */
+    protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
+    /**
+     * Get verb (type-first path)
+     */
+    protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
+    /**
+     * Get verbs by source
+     */
+    protected getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
+    /**
+     * Get verbs by target
+     */
+    protected getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
+    /**
+     * Get verbs by type (O(1) with type-first paths!)
+     */
+    protected getVerbsByType_internal(verbType: string): Promise<GraphVerb[]>;
+    /**
+     * Delete verb (type-first path)
+     */
+    protected deleteVerb_internal(id: string): Promise<void>;
+    /**
+     * Write object to path (delegate to underlying storage)
+     */
+    protected writeObjectToPath(path: string, data: any): Promise<void>;
+    /**
+     * Read object from path (delegate to underlying storage)
+     */
+    protected readObjectFromPath(path: string): Promise<any | null>;
+    /**
+     * Delete object from path (delegate to underlying storage)
+     */
+    protected deleteObjectFromPath(path: string): Promise<void>;
+    /**
+     * List objects under path (delegate to underlying storage)
+     */
+    protected listObjectsUnderPath(prefix: string): Promise<string[]>;
+    /**
+     * Save statistics data
+     */
+    protected saveStatisticsData(statistics: StatisticsData): Promise<void>;
+    /**
+     * Get statistics data
+     */
+    protected getStatisticsData(): Promise<StatisticsData | null>;
+    /**
+     * Clear all data
+     */
+    clear(): Promise<void>;
+    /**
+     * Get storage status
+     */
+    getStorageStatus(): Promise<{
+        type: string;
+        used: number;
+        quota: number | null;
+        details?: Record<string, any>;
+    }>;
+    /**
+     * Initialize counts from storage
+     */
+    protected initializeCounts(): Promise<void>;
+    /**
+     * Persist counts to storage
+     */
+    protected persistCounts(): Promise<void>;
+    /**
+     * Get noun vector (delegate to underlying storage)
+     */
+    getNounVector(id: string): Promise<number[] | null>;
+    /**
+     * Save HNSW data for a noun
+     */
+    saveHNSWData(nounId: string, hnswData: {
+        level: number;
+        connections: Record<string, string[]>;
+    }): Promise<void>;
+    /**
+     * Get HNSW data for a noun
+     */
+    getHNSWData(nounId: string): Promise<{
+        level: number;
+        connections: Record<string, string[]>;
+    } | null>;
+    /**
+     * Save HNSW system data (entry point, max level)
+     */
+    saveHNSWSystem(systemData: {
+        entryPointId: string | null;
+        maxLevel: number;
+    }): Promise<void>;
+    /**
+     * Get HNSW system data
+     */
+    getHNSWSystem(): Promise<{
+        entryPointId: string | null;
+        maxLevel: number;
+    } | null>;
+    /**
+     * Get type statistics
+     * Useful for analytics and optimization
+     */
+    getTypeStatistics(): {
+        nouns: Array<{
+            type: NounType;
+            count: number;
+        }>;
+        verbs: Array<{
+            type: VerbType;
+            count: number;
+        }>;
+        totalMemory: number;
+    };
+}