@soulcraft/brainy 6.1.0 → 6.2.1

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

@@ -0,0 +1,252 @@
+/**
+ * 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 { HNSWNoun, HNSWVerb, HNSWVerbWithMetadata, NounMetadata, VerbMetadata, 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 cache
+     *
+     * v4.0.0: Metadata is stored separately, so we rely on the cache
+     * which is populated when saveNounMetadata is called
+     */
+    private getNounType;
+    /**
+     * Get verb type from verb object
+     *
+     * ARCHITECTURAL FIX (v3.50.1): Simplified - verb field is now always present
+     */
+    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)
+     *
+     * ARCHITECTURAL FIX (v3.50.1): No more caching hack needed!
+     * HNSWVerb now includes verb field, so type is always available
+     */
+    protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
+    /**
+     * Get verb (type-first path)
+     *
+     * ARCHITECTURAL FIX (v3.50.1): Cache still useful for performance
+     * Once we know where a verb is, we can retrieve it O(1) instead of searching all types
+     */
+    protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
+    /**
+     * Get verbs by source
+     */
+    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
+    /**
+     * Get verbs by target
+     */
+    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
+    /**
+     * Get verbs by type (O(1) with type-first paths!)
+     *
+     * v4.0.0: Load verbs and combine with metadata
+     */
+    protected getVerbsByType_internal(verbType: string): Promise<HNSWVerbWithMetadata[]>;
+    /**
+     * Delete verb (type-first path)
+     */
+    protected deleteVerb_internal(id: string): Promise<void>;
+    /**
+     * Save noun metadata (override to cache type for type-aware routing)
+     *
+     * v4.0.0: Extract and cache noun type when metadata is saved
+     */
+    saveNounMetadata(id: string, metadata: NounMetadata): Promise<void>;
+    /**
+     * Get noun metadata (override to use type-aware paths)
+     */
+    getNounMetadata(id: string): Promise<NounMetadata | null>;
+    /**
+     * Delete noun metadata (override to use type-aware paths)
+     */
+    deleteNounMetadata(id: string): Promise<void>;
+    /**
+     * Save verb metadata (override to use type-aware paths)
+     *
+     * Note: Verb type comes from HNSWVerb.verb field, not metadata
+     * We need to read the verb to get the type for path routing
+     */
+    saveVerbMetadata(id: string, metadata: VerbMetadata): Promise<void>;
+    /**
+     * Get verb metadata (override to use type-aware paths)
+     */
+    getVerbMetadata(id: string): Promise<VerbMetadata | null>;
+    /**
+     * Delete verb metadata (override to use type-aware paths)
+     */
+    deleteVerbMetadata(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;
+    };
+}