@soulcraft/brainy 3.37.3 → 3.37.5

package/dist/storage/adapters/fileSystemStorage.js

@@ -1349,13 +1349,17 @@ export class FileSystemStorage extends BaseStorage {
     mergeStatistics(storageStats, localStats) {
         // Handle null cases
         if (!storageStats && !localStats) {
+            // CRITICAL FIX (v3.37.4): Statistics files don't exist yet (first init)
+            // Return minimal stats with counts instead of zeros
+            // This prevents HNSW from seeing entityCount=0 during index rebuild
             return {
                 nounCount: {},
                 verbCount: {},
                 metadataCount: {},
                 hnswIndexSize: 0,
-                totalNodes: 0,
-                totalEdges: 0,
+                totalNodes: this.totalNounCount,
+                totalEdges: this.totalVerbCount,
+                totalMetadata: 0,
                 lastUpdated: new Date().toISOString()
             };
         }

package/dist/storage/adapters/gcsStorage.js

@@ -392,6 +392,8 @@ export class GcsStorage extends BaseStorage {
             this.logger.trace(`Getting node ${id}`);
             // Get the GCS key with UUID-based sharding
             const key = this.getNounKey(id);
+            // DIAGNOSTIC LOGGING: Show exact path being accessed
+            this.logger.trace(`Computed GCS key: ${key}`);
             // Download from GCS
             const file = this.bucket.file(key);
             const [contents] = await file.download();
@@ -421,7 +423,12 @@ export class GcsStorage extends BaseStorage {
             this.releaseBackpressure(false, requestId);
             // Check if this is a "not found" error
             if (error.code === 404) {
-                this.logger.trace(`Node not found: ${id}`);
+                // DIAGNOSTIC LOGGING: Upgrade 404 errors to WARN level with full details
+                const key = this.getNounKey(id);
+                prodLog.warn(`[getNode] ❌ 404 NOT FOUND: File does not exist at GCS path: ${key}`);
+                prodLog.warn(`[getNode] UUID: ${id}`);
+                prodLog.warn(`[getNode] Bucket: ${this.bucketName}`);
+                prodLog.warn(`[getNode] This suggests a path mismatch or the file was not written correctly`);
                 return null;
             }
             // Handle throttling
@@ -785,6 +792,13 @@ export class GcsStorage extends BaseStorage {
         await this.ensureInitialized(); // CRITICAL: Must initialize before using this.bucket
         const limit = options.limit || 100;
         const useCache = options.useCache !== false;
+        // DIAGNOSTIC LOGGING: Track pagination performance
+        prodLog.info(`[getNodesWithPagination] Starting pagination: limit=${limit}, cursor=${options.cursor || 'none'}`);
+        const startTime = Date.now();
+        let shardsChecked = 0;
+        let filesFound = 0;
+        let nodesLoaded = 0;
+        let nodesFailed = 0;
         try {
             const nodes = [];
             // Parse cursor (format: "shardIndex:gcsPageToken")
@@ -799,6 +813,7 @@ export class GcsStorage extends BaseStorage {
             for (let shardIndex = startShardIndex; shardIndex < TOTAL_SHARDS; shardIndex++) {
                 const shardId = getShardIdByIndex(shardIndex);
                 const shardPrefix = `${this.nounPrefix}${shardId}/`;
+                shardsChecked++;
                 // List objects in this shard
                 // Cap maxResults to GCS API limit to prevent "Invalid unsigned integer" errors
                 const requestedPageSize = limit - nodes.length;
@@ -808,6 +823,12 @@ export class GcsStorage extends BaseStorage {
                     maxResults: cappedPageSize,
                     pageToken: shardIndex === startShardIndex ? gcsPageToken : undefined
                 });
+                // DIAGNOSTIC LOGGING: Show files found per shard (only log non-empty shards)
+                if (files && files.length > 0) {
+                    filesFound += files.length;
+                    prodLog.info(`[Shard ${shardId}] Found ${files.length} files in "${shardPrefix}"`);
+                    prodLog.info(`[Shard ${shardId}] Sample file names: ${files.slice(0, 3).map((f) => f.name).join(', ')}`);
+                }
                 // Extract node IDs from file names
                 if (files && files.length > 0) {
                     const nodeIds = files
@@ -824,11 +845,21 @@ export class GcsStorage extends BaseStorage {
                         return name;
                     })
                         .filter((id) => id && id.length > 0);
+                    // DIAGNOSTIC LOGGING: Show extracted UUIDs
+                    prodLog.info(`[Shard ${shardId}] Extracted ${nodeIds.length} UUIDs: ${nodeIds.slice(0, 3).join(', ')}...`);
                     // Load nodes
                     for (const id of nodeIds) {
+                        // DIAGNOSTIC LOGGING: Show each getNode() attempt
+                        prodLog.info(`[Shard ${shardId}] Calling getNode("${id}")...`);
                         const node = await this.getNode(id);
                         if (node) {
                             nodes.push(node);
+                            nodesLoaded++;
+                            prodLog.info(`[Shard ${shardId}] ✅ Successfully loaded node ${id}`);
+                        }
+                        else {
+                            nodesFailed++;
+                            prodLog.warn(`[Shard ${shardId}] ❌ getNode("${id}") returned null!`);
                         }
                         if (nodes.length >= limit) {
                             break;
@@ -861,6 +892,14 @@ export class GcsStorage extends BaseStorage {
                 // Continue to next shard
             }
             // No more shards or nodes
+            // DIAGNOSTIC LOGGING: Final summary
+            const elapsedTime = Date.now() - startTime;
+            prodLog.info(`[getNodesWithPagination] COMPLETED in ${elapsedTime}ms:`);
+            prodLog.info(`  - Shards checked: ${shardsChecked}/${TOTAL_SHARDS}`);
+            prodLog.info(`  - Files found: ${filesFound}`);
+            prodLog.info(`  - Nodes loaded: ${nodesLoaded}`);
+            prodLog.info(`  - Nodes failed: ${nodesFailed}`);
+            prodLog.info(`  - Success rate: ${filesFound > 0 ? ((nodesLoaded / filesFound) * 100).toFixed(1) : 'N/A'}%`);
             return {
                 nodes,
                 totalCount: this.totalNounCount,
@@ -1188,8 +1227,20 @@ export class GcsStorage extends BaseStorage {
         }
         catch (error) {
             if (error.code === 404) {
-                this.logger.trace('Statistics not found (creating new)');
-                return null;
+                // CRITICAL FIX (v3.37.4): Statistics file doesn't exist yet (first restart)
+                // Return minimal stats with counts instead of null
+                // This prevents HNSW from seeing entityCount=0 during index rebuild
+                this.logger.trace('Statistics file not found - returning minimal stats with counts');
+                return {
+                    nounCount: {},
+                    verbCount: {},
+                    metadataCount: {},
+                    hnswIndexSize: 0,
+                    totalNodes: this.totalNounCount,
+                    totalEdges: this.totalVerbCount,
+                    totalMetadata: 0,
+                    lastUpdated: new Date().toISOString()
+                };
             }
             this.logger.error('Failed to get statistics:', error);
             return null;

package/dist/storage/adapters/memoryStorage.js

@@ -551,7 +551,19 @@ export class MemoryStorage extends BaseStorage {
      */
     async getStatisticsData() {
         if (!this.statistics) {
-            return null;
+            // CRITICAL FIX (v3.37.4): Statistics don't exist yet (first init)
+            // Return minimal stats with counts instead of null
+            // This prevents HNSW from seeing entityCount=0 during index rebuild
+            return {
+                nounCount: {},
+                verbCount: {},
+                metadataCount: {},
+                hnswIndexSize: 0,
+                totalNodes: this.totalNounCount,
+                totalEdges: this.totalVerbCount,
+                totalMetadata: 0,
+                lastUpdated: new Date().toISOString()
+            };
         }
         // Return a deep copy to avoid reference issues
         return {

package/dist/storage/adapters/opfsStorage.js

@@ -1212,13 +1212,36 @@ export class OPFSStorage extends BaseStorage {
                         }
                     }
                     catch (error) {
-                        // If the legacy file doesn't exist either, return null
-                        return null;
+                        // CRITICAL FIX (v3.37.4): No statistics files exist (first init)
+                        // Return minimal stats with counts instead of null
+                        // This prevents HNSW from seeing entityCount=0 during index rebuild
+                        return {
+                            nounCount: {},
+                            verbCount: {},
+                            metadataCount: {},
+                            hnswIndexSize: 0,
+                            totalNodes: this.totalNounCount,
+                            totalEdges: this.totalVerbCount,
+                            totalMetadata: 0,
+                            lastUpdated: new Date().toISOString()
+                        };
                     }
                 }
             }
-            // If we get here and statistics is null, return default statistics
-            return this.statistics ? this.statistics : null;
+            // If we get here and statistics is null, return minimal stats with counts
+            if (!this.statistics) {
+                return {
+                    nounCount: {},
+                    verbCount: {},
+                    metadataCount: {},
+                    hnswIndexSize: 0,
+                    totalNodes: this.totalNounCount,
+                    totalEdges: this.totalVerbCount,
+                    totalMetadata: 0,
+                    lastUpdated: new Date().toISOString()
+                };
+            }
+            return this.statistics;
         }
         catch (error) {
             console.error('Failed to get statistics data:', error);

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -2198,6 +2198,19 @@ export class S3CompatibleStorage extends BaseStorage {
                     totalEdges: this.totalVerbCount
                 };
             }
+            // If we get here and statistics is null, return minimal stats with counts
+            if (!statistics) {
+                return {
+                    nounCount: {},
+                    verbCount: {},
+                    metadataCount: {},
+                    hnswIndexSize: 0,
+                    totalNodes: this.totalNounCount,
+                    totalEdges: this.totalVerbCount,
+                    totalMetadata: 0,
+                    lastUpdated: new Date().toISOString()
+                };
+            }
             // Successfully loaded statistics from storage
             return statistics;
         }
@@ -2212,7 +2225,19 @@ export class S3CompatibleStorage extends BaseStorage {
                     totalEdges: this.totalVerbCount
                 };
             }
-            return null;
+            // CRITICAL FIX (v3.37.4): Statistics file doesn't exist yet (first restart)
+            // Return minimal stats with counts instead of null
+            // This prevents HNSW from seeing entityCount=0 during index rebuild
+            return {
+                nounCount: {},
+                verbCount: {},
+                metadataCount: {},
+                hnswIndexSize: 0,
+                totalNodes: this.totalNounCount,
+                totalEdges: this.totalVerbCount,
+                totalMetadata: 0,
+                lastUpdated: new Date().toISOString()
+            };
         }
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.37.3",
+  "version": "3.37.5",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",