@soulcraft/brainy 5.12.0 → 6.0.1

package/dist/storage/adapters/gcsStorage.js

@@ -165,7 +165,8 @@ export class GcsStorage extends BaseStorage {
             this.nounCacheManager.clear();
             this.verbCacheManager.clear();
             prodLog.info('✅ Cache cleared - starting fresh');
-            this.isInitialized = true;
+            // v6.0.0: Initialize GraphAdjacencyIndex and type statistics
+            await super.init();
         }
         catch (error) {
             this.logger.error('Failed to initialize GCS storage:', error);

package/dist/storage/adapters/historicalStorageAdapter.js

@@ -107,8 +107,8 @@ export class HistoricalStorageAdapter extends BaseStorage {
         if (!commit) {
             throw new Error(`Commit not found: ${this.commitId}`);
         }
-        // Mark as initialized
-        this.isInitialized = true;
+        // v6.0.0: Initialize GraphAdjacencyIndex and type statistics
+        await super.init();
     }
     // ============= Abstract Method Implementations =============
     /**

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

@@ -30,7 +30,7 @@ export declare class MemoryStorage extends BaseStorage {
     getBatchConfig(): StorageBatchConfig;
     /**
      * Initialize the storage adapter
-     * Nothing to initialize for in-memory storage
+     * v6.0.0: Calls super.init() to initialize GraphAdjacencyIndex and type statistics
      */
     init(): Promise<void>;
     /**

package/dist/storage/adapters/memoryStorage.js

@@ -55,10 +55,10 @@ export class MemoryStorage extends BaseStorage {
     }
     /**
      * Initialize the storage adapter
-     * Nothing to initialize for in-memory storage
+     * v6.0.0: Calls super.init() to initialize GraphAdjacencyIndex and type statistics
      */
     async init() {
-        this.isInitialized = true;
+        await super.init();
     }
     // v5.4.0: Removed saveNoun_internal and getNoun_internal - using BaseStorage's type-first implementation
     /**
@@ -248,25 +248,23 @@ export class MemoryStorage extends BaseStorage {
      * Initialize counts from in-memory storage - O(1) operation (v4.0.0)
      */
     async initializeCounts() {
-        // v5.4.0: Scan objectStore paths (type-first structure) to count entities
+        // v6.0.0: Scan objectStore paths (ID-first structure) to count entities
         this.entityCounts.clear();
         this.verbCounts.clear();
         let totalNouns = 0;
         let totalVerbs = 0;
         // Scan all paths in objectStore
         for (const path of this.objectStore.keys()) {
-            // Count nouns by type (entities/nouns/{type}/vectors/{shard}/{id}.json)
-            const nounMatch = path.match(/^entities\/nouns\/([^/]+)\/vectors\//);
+            // Count nouns (entities/nouns/{shard}/{id}/vectors.json)
+            const nounMatch = path.match(/^entities\/nouns\/[0-9a-f]{2}\/[^/]+\/vectors\.json$/);
             if (nounMatch) {
-                const type = nounMatch[1];
-                this.entityCounts.set(type, (this.entityCounts.get(type) || 0) + 1);
+                // v6.0.0: Type is in metadata, not path - just count total
                 totalNouns++;
             }
-            // Count verbs by type (entities/verbs/{type}/vectors/{shard}/{id}.json)
-            const verbMatch = path.match(/^entities\/verbs\/([^/]+)\/vectors\//);
+            // Count verbs (entities/verbs/{shard}/{id}/vectors.json)
+            const verbMatch = path.match(/^entities\/verbs\/[0-9a-f]{2}\/[^/]+\/vectors\.json$/);
             if (verbMatch) {
-                const type = verbMatch[1];
-                this.verbCounts.set(type, (this.verbCounts.get(type) || 0) + 1);
+                // v6.0.0: Type is in metadata, not path - just count total
                 totalVerbs++;
             }
         }

package/dist/storage/adapters/opfsStorage.js

@@ -131,7 +131,8 @@ export class OPFSStorage extends BaseStorage {
             });
             // Initialize counts from storage
             await this.initializeCounts();
-            this.isInitialized = true;
+            // v6.0.0: Initialize GraphAdjacencyIndex and type statistics
+            await super.init();
         }
         catch (error) {
             console.error('Failed to initialize OPFS storage:', error);

package/dist/storage/adapters/r2Storage.js

@@ -232,7 +232,8 @@ export class R2Storage extends BaseStorage {
             prodLog.info('🧹 R2: Clearing cache from previous run');
             this.nounCacheManager.clear();
             this.verbCacheManager.clear();
-            this.isInitialized = true;
+            // v6.0.0: Initialize GraphAdjacencyIndex and type statistics
+            await super.init();
         }
         catch (error) {
             this.logger.error('Failed to initialize R2 storage:', error);

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -345,7 +345,8 @@ export class S3CompatibleStorage extends BaseStorage {
             else {
                 prodLog.info('🧹 Node cache is empty - starting fresh');
             }
-            this.isInitialized = true;
+            // v6.0.0: Initialize GraphAdjacencyIndex and type statistics
+            await super.init();
             this.logger.info(`Initialized ${this.serviceType} storage with bucket ${this.bucketName}`);
         }
         catch (error) {

package/dist/storage/baseStorage.d.ts

@@ -60,8 +60,6 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     currentBranch: string;
     protected nounCountsByType: Uint32Array<ArrayBuffer>;
     protected verbCountsByType: Uint32Array<ArrayBuffer>;
-    protected nounTypeCache: Map<string, NounType>;
-    protected verbTypeCache: Map<string, VerbType>;
     private typeCountsRebuilt;
     /**
      * Analyze a storage key to determine its routing and path
@@ -78,6 +76,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * IMPORTANT: If your adapter overrides init(), call await super.init() first!
      */
     init(): Promise<void>;
+    /**
+     * Rebuild GraphAdjacencyIndex from existing verbs (v6.0.0)
+     * Call this manually if you have existing verb data that needs to be indexed
+     * @public
+     */
+    rebuildGraphIndex(): Promise<void>;
     /**
      * Ensure the storage adapter is initialized
      */
@@ -406,6 +410,17 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     /**
      * Get noun metadata from storage (METADATA-ONLY, NO VECTORS)
      *
+     * **Performance (v6.0.0)**: Direct O(1) ID-first lookup - NO type search needed!
+     * - **All lookups**: 1 read, ~500ms on cloud (consistent performance)
+     * - **No cache needed**: Type is in the metadata, not the path
+     * - **No type search**: ID-first paths eliminate 42-type search entirely
+     *
+     * **Clean architecture (v6.0.0)**:
+     * - Path: `entities/nouns/{SHARD}/{ID}/metadata.json`
+     * - Type is just a field in metadata (`noun: "document"`)
+     * - MetadataIndex handles type queries (no path scanning needed)
+     * - Scales to billions without any overhead
+     *
      * **Performance (v5.11.1)**: Fast path for metadata-only reads
      * - **Speed**: 10ms vs 43ms (76-81% faster than getNoun)
      * - **Bandwidth**: 300 bytes vs 6KB (95% less)
@@ -435,13 +450,15 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * @returns Metadata or null if not found
      *
      * @performance
-     * - Type cache O(1) lookup for cached entities
-     * - Type scan O(N_types) for cache misses (typically <100ms)
-     * - Uses readWithInheritance() for COW branch support
+     * - O(1) direct ID lookup - always 1 read (~500ms on cloud, ~10ms local)
+     * - No caching complexity
+     * - No type search fallbacks
+     * - Works in distributed systems without sync issues
      *
      * @since v4.0.0
-     * @since v5.4.0 - Type-first paths
+     * @since v5.4.0 - Type-first paths (removed in v6.0.0)
      * @since v5.11.1 - Promoted to fast path for brain.get() optimization
+     * @since v6.0.0 - CLEAN FIX: ID-first paths eliminate all type-search complexity
      */
     getNounMetadata(id: string): Promise<NounMetadata | null>;
     /**
@@ -525,8 +542,7 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      */
     getBatchConfig(): StorageBatchConfig;
     /**
-     * Delete noun metadata from storage
-     * v5.4.0: Uses type-first paths (must match saveNounMetadata_internal)
+     * Delete noun metadata from storage (v6.0.0: ID-first, O(1) delete)
      */
     deleteNounMetadata(id: string): Promise<void>;
     /**
@@ -536,7 +552,7 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     saveVerbMetadata(id: string, metadata: VerbMetadata): Promise<void>;
     /**
      * Internal method for saving verb metadata (v4.0.0: now typed)
-     * v5.4.0: Uses type-first paths (must match getVerbMetadata)
+     * v5.4.0: Uses ID-first paths (must match getVerbMetadata)
      *
      * CRITICAL (v4.1.2): Count synchronization happens here
      * This ensures verb counts are updated AFTER metadata exists, fixing the race condition
@@ -549,12 +565,11 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     protected saveVerbMetadata_internal(id: string, metadata: VerbMetadata): Promise<void>;
     /**
      * Get verb metadata from storage (v4.0.0: now typed)
-     * v5.4.0: Uses type-first paths (must match saveVerbMetadata_internal)
+     * v5.4.0: Uses ID-first paths (must match saveVerbMetadata_internal)
      */
     getVerbMetadata(id: string): Promise<VerbMetadata | null>;
     /**
-     * Delete verb metadata from storage
-     * v5.4.0: Uses type-first paths (must match saveVerbMetadata_internal)
+     * Delete verb metadata from storage (v6.0.0: ID-first, O(1) delete)
      */
     deleteVerbMetadata(id: string): Promise<void>;
     /**
@@ -574,8 +589,9 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      */
     protected rebuildTypeCounts(): Promise<void>;
     /**
-     * Get noun type from cache or metadata
-     * Relies on nounTypeCache populated during metadata saves
+     * Get noun type (v6.0.0: type no longer needed for paths!)
+     * With ID-first paths, this is only used for internal statistics tracking.
+     * The actual type is stored in metadata and indexed by MetadataIndexManager.
      */
     protected getNounType(noun: HNSWNoun): NounType;
     /**
@@ -608,32 +624,32 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      */
     protected deserializeVerb(data: any): HNSWVerb;
     /**
-     * Save a noun to storage (type-first path)
+     * Save a noun to storage (ID-first path)
      */
     protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
     /**
-     * Get a noun from storage (type-first path)
+     * Get a noun from storage (ID-first path)
      */
     protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
     /**
-     * Get nouns by noun type (O(1) with type-first paths!)
+     * Get nouns by noun type (v6.0.0: Shard-based iteration!)
      */
     protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
     /**
-     * Delete a noun from storage (type-first path)
+     * Delete a noun from storage (v6.0.0: ID-first, O(1) delete)
      */
     protected deleteNoun_internal(id: string): Promise<void>;
     /**
-     * Save a verb to storage (type-first path)
+     * Save a verb to storage (ID-first path)
      */
     protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
     /**
-     * Get a verb from storage (type-first path)
+     * Get a verb from storage (ID-first path)
      */
     protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
     /**
-     * Get verbs by source (COW-aware implementation)
-     * v5.4.0: Fixed to directly list verb files instead of directories
+     * Get verbs by source (v6.0.0: Uses GraphAdjacencyIndex when available)
+     * Falls back to shard iteration during initialization to avoid circular dependency
      */
     protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
@@ -676,11 +692,11 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      */
     protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
-     * Get verbs by type (O(1) with type-first paths!)
+     * Get verbs by type (v6.0.0: Shard iteration with type filtering)
      */
     protected getVerbsByType_internal(verbType: string): Promise<HNSWVerbWithMetadata[]>;
     /**
-     * Delete a verb from storage (type-first path)
+     * Delete a verb from storage (v6.0.0: ID-first, O(1) delete)
      */
     protected deleteVerb_internal(id: string): Promise<void>;
     /**