@soulcraft/brainy 5.4.0 → 5.6.0

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

@@ -1,300 +0,0 @@
-/**
- * Type-Aware Storage Adapter
- *
- * Wraps underlying storage (FileSystem, GCS, S3, etc.) with type-first organization.
- * Enables efficient type-based queries via directory structure.
- *
- * IMPLEMENTED Features (v3.45.0):
- * - Type-first paths: entities/nouns/{type}/vectors/{shard}/{uuid}.json
- * - Fixed-size type count tracking: Uint32Array(31 + 40) = 284 bytes
- * - Type-based filtering: List entities by type via directory structure
- * - Type caching: Map<id, type> for frequently accessed entities
- *
- * MEASURED Performance (tests up to 1M entities):
- * - Type count memory: 284 bytes (vs Map-based: ~100KB at 1M scale) = 99.7% reduction
- * - getNounsByType: O(entities_of_type) via directory scan (vs O(total) full scan)
- * - getVerbsByType: O(entities_of_type) via directory scan (vs O(total) full scan)
- * - Type-cached lookups: O(1) after first access
- *
- * PROJECTED Performance (billion-scale, NOT tested):
- * - Total memory: PROJECTED ~50-100GB (vs theoretical 500GB baseline)
- * - Type count: 284 bytes remains constant (not dependent on entity count)
- * - Type cache: Grows with usage (10% cached at 1B = ~5GB overhead)
- * - Note: Billion-scale claims are EXTRAPOLATIONS, not measurements
- *
- * LIMITATIONS:
- * - Type cache grows unbounded (no eviction policy)
- * - Uncached entity lookups: O(types) worst case (searches all type directories)
- * - v4.8.1: getVerbsBySource/Target delegate to underlying (previously O(total_verbs))
- *
- * TEST COVERAGE:
- * - Unit tests: typeAwareStorageAdapter.test.ts (17 tests passing)
- * - Integration tests: Tested with 1,155 entities (Workshop data)
- * - Performance tests: None (no benchmark comparisons yet)
- *
- * @version 3.45.0 (created), 4.8.1 (performance fix)
- * @since Phase 1 - Type-First Implementation
- */
-import { BaseStorage } from '../baseStorage.js';
-import { HNSWNoun, HNSWVerb, HNSWNounWithMetadata, 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>;
-    /**
-     * Get nouns with pagination (v5.0.1: COW-aware)
-     * Required for find() to work with TypeAwareStorage
-     */
-    getNounsWithPagination(options: {
-        limit?: number;
-        offset?: number;
-        cursor?: string;
-        filter?: any;
-    }): Promise<{
-        items: HNSWNounWithMetadata[];
-        totalCount: number;
-        hasMore: boolean;
-        nextCursor?: string;
-    }>;
-    /**
-     * Get verbs with pagination (v5.0.1: COW-aware)
-     * Required for GraphAdjacencyIndex rebuild and find() to work
-     */
-    getVerbsWithPagination(options: {
-        limit?: number;
-        offset?: number;
-        cursor?: string;
-        filter?: any;
-    }): Promise<{
-        items: HNSWVerbWithMetadata[];
-        totalCount: number;
-        hasMore: boolean;
-        nextCursor?: string;
-    }>;
-    /**
-     * 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;
-    };
-}