@soulcraft/brainy 5.7.9 → 5.7.11

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [5.7.11](https://github.com/soulcraftlabs/brainy/compare/v5.7.10...v5.7.11) (2025-11-13)
+
+
+### 🐛 Bug Fixes
+
+* resolve critical 378x pagination infinite loop bug (v5.7.11) ([e86f765](https://github.com/soulcraftlabs/brainy/commit/e86f765f3d30be41707e2ef7d07bb5c92d4ca3da))
+
 ### [5.7.9](https://github.com/soulcraftlabs/brainy/compare/v5.7.8...v5.7.9) (2025-11-13)
 
 - fix: implement exists: false and missing operators in MetadataIndexManager (b0f72ef)

package/dist/hnsw/hnswIndex.js

@@ -858,12 +858,12 @@ export class HNSWIndex {
                 // Cloud storage: Use pagination with native cloud APIs
                 prodLog.info(`HNSW: Using cloud pagination strategy (${storageType})`);
                 let hasMore = true;
-                let cursor = undefined;
+                let offset = 0; // v5.7.11: Use offset-based pagination instead of cursor (bug fix for infinite loop)
                 while (hasMore) {
                     // Fetch batch of nouns from storage (cast needed as method is not in base interface)
                     const result = await this.storage.getNounsWithPagination({
                         limit: batchSize,
-                        cursor
+                        offset // v5.7.11: Pass offset for proper pagination (previously passed cursor which was ignored)
                     });
                     // Set total count on first batch
                     if (totalCount === undefined && result.totalCount !== undefined) {
@@ -912,7 +912,7 @@ export class HNSWIndex {
                     }
                     // Check for more data
                     hasMore = result.hasMore;
-                    cursor = result.nextCursor;
+                    offset += batchSize; // v5.7.11: Increment offset for next page
                 }
             }
             const cacheInfo = shouldPreload

package/dist/hnsw/typeAwareHNSWIndex.js

@@ -342,14 +342,14 @@ export class TypeAwareHNSWIndex {
         }
         // Load ALL nouns ONCE and route to correct type indexes
         // This is O(N) instead of O(42*N) from the previous parallel approach
-        let cursor = undefined;
+        let offset = 0; // v5.7.11: Use offset-based pagination instead of cursor (bug fix for infinite loop)
         let hasMore = true;
         let totalLoaded = 0;
         const loadedByType = new Map();
         while (hasMore) {
             const result = await this.storage.getNounsWithPagination({
                 limit: batchSize,
-                cursor
+                offset // v5.7.11: Pass offset for proper pagination (previously passed cursor which was ignored)
             });
             // Route each noun to its type index
             for (const nounData of result.items) {
@@ -407,7 +407,7 @@ export class TypeAwareHNSWIndex {
                 }
             }
             hasMore = result.hasMore;
-            cursor = result.nextCursor;
+            offset += batchSize; // v5.7.11: Increment offset for next page
             // Progress logging
             if (totalLoaded % 1000 === 0) {
                 prodLog.info(`Progress: ${totalLoaded.toLocaleString()} entities loaded...`);

package/dist/storage/adapters/optimizedS3Search.js

@@ -48,7 +48,7 @@ export class OptimizedS3Search {
                 }
             }
             // Determine if there are more items
-            const hasMore = listResult.hasMore || nouns.length >= limit;
+            const hasMore = listResult.hasMore || nouns.length > limit; // v5.7.11: Fixed >= to > (was causing infinite loop)
             // Set next cursor
             let nextCursor;
             if (hasMore && nouns.length > 0) {
@@ -114,7 +114,7 @@ export class OptimizedS3Search {
                 }
             }
             // Determine if there are more items
-            const hasMore = listResult.hasMore || verbs.length >= limit;
+            const hasMore = listResult.hasMore || verbs.length > limit; // v5.7.11: Fixed >= to > (was causing infinite loop)
             // Set next cursor
             let nextCursor;
             if (hasMore && verbs.length > 0) {

package/dist/storage/baseStorage.d.ts

@@ -458,6 +458,30 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Verb type is a required field in HNSWVerb
      */
     protected getVerbType(verb: HNSWVerb | GraphVerb): VerbType;
+    /**
+     * Deserialize HNSW connections from JSON storage format
+     *
+     * Converts plain object { "0": ["id1"], "1": ["id2"] }
+     * into Map<number, Set<string>>
+     *
+     * v5.7.10: Central helper to fix serialization bug across all code paths
+     * Root cause: JSON.stringify(Map) = {} (empty object), must reconstruct on read
+     */
+    protected deserializeConnections(connections: any): Map<number, Set<string>>;
+    /**
+     * Deserialize HNSWNoun from JSON storage format
+     *
+     * v5.7.10: Ensures connections are properly reconstructed from Map → object → Map
+     * Fixes: "TypeError: noun.connections.entries is not a function"
+     */
+    protected deserializeNoun(data: any): HNSWNoun;
+    /**
+     * Deserialize HNSWVerb from JSON storage format
+     *
+     * v5.7.10: Ensures connections are properly reconstructed from Map → object → Map
+     * Fixes same serialization bug for verbs
+     */
+    protected deserializeVerb(data: any): HNSWVerb;
     /**
      * Save a noun to storage (type-first path)
      */

package/dist/storage/baseStorage.js

@@ -879,7 +879,7 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async getNounsWithPagination(options) {
         await this.ensureInitialized();
-        const { limit, offset = 0, filter } = options;
+        const { limit, offset = 0, filter } = options; // cursor intentionally not extracted (not yet implemented)
         const collectedNouns = [];
         const targetCount = offset + limit; // Early termination target
         // v5.5.0 BUG FIX: Only use optimization if counts are reliable
@@ -912,8 +912,11 @@ export class BaseStorage extends BaseStorageAdapter {
                     if (!nounPath.endsWith('.json'))
                         continue;
                     try {
-                        const noun = await this.readWithInheritance(nounPath);
-                        if (noun) {
+                        const rawNoun = await this.readWithInheritance(nounPath);
+                        if (rawNoun) {
+                            // v5.7.10: Deserialize connections Map from JSON storage format
+                            // Replaces v5.7.8 manual deserialization (removed 13 lines at 1156-1168)
+                            const noun = this.deserializeNoun(rawNoun);
                             // Load metadata
                             const metadataPath = getNounMetadataPath(type, noun.id);
                             const metadata = await this.readWithInheritance(metadataPath);
@@ -925,24 +928,10 @@ export class BaseStorage extends BaseStorageAdapter {
                                         continue;
                                     }
                                 }
-                                // v5.7.8: Convert connections from plain object to Map (JSON deserialization fix)
-                                // When loaded from JSON, Map becomes plain object - must reconstruct
-                                const connections = new Map();
-                                if (noun.connections && typeof noun.connections === 'object') {
-                                    for (const [levelStr, ids] of Object.entries(noun.connections)) {
-                                        if (Array.isArray(ids)) {
-                                            connections.set(parseInt(levelStr, 10), new Set(ids));
-                                        }
-                                        else if (ids && typeof ids === 'object') {
-                                            // Handle if it's already an array-like or Set-like object
-                                            connections.set(parseInt(levelStr, 10), new Set(Object.values(ids)));
-                                        }
-                                    }
-                                }
                                 // Combine noun + metadata (v5.4.0: Extract standard fields to top-level)
                                 collectedNouns.push({
                                     ...noun,
-                                    connections, // Use reconstructed Map instead of plain object
+                                    // v5.7.10: connections already deserialized by deserializeNoun()
                                     type: metadata.noun || type, // Required: Extract type from metadata
                                     confidence: metadata.confidence,
                                     weight: metadata.weight,
@@ -971,7 +960,7 @@ export class BaseStorage extends BaseStorageAdapter {
         }
         // Apply pagination (v5.5.0: Efficient slicing after early termination)
         const paginatedNouns = collectedNouns.slice(offset, offset + limit);
-        const hasMore = collectedNouns.length >= targetCount;
+        const hasMore = collectedNouns.length > targetCount; // v5.7.11: Fixed >= to > (was causing infinite loop)
         return {
             items: paginatedNouns,
             totalCount: collectedNouns.length, // Accurate count of collected results
@@ -998,7 +987,7 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async getVerbsWithPagination(options) {
         await this.ensureInitialized();
-        const { limit, offset = 0, filter } = options;
+        const { limit, offset = 0, filter } = options; // cursor intentionally not extracted (not yet implemented)
         const collectedVerbs = [];
         const targetCount = offset + limit; // Early termination target
         // v5.5.0 BUG FIX: Only use optimization if counts are reliable
@@ -1057,7 +1046,7 @@ export class BaseStorage extends BaseStorageAdapter {
         }
         // Apply pagination (v5.5.0: Efficient slicing after early termination)
         const paginatedVerbs = collectedVerbs.slice(offset, offset + limit);
-        const hasMore = collectedVerbs.length >= targetCount;
+        const hasMore = collectedVerbs.length > targetCount; // v5.7.11: Fixed >= to > (was causing infinite loop)
         return {
             items: paginatedVerbs,
             totalCount: collectedVerbs.length, // Accurate count of collected results
@@ -1312,7 +1301,7 @@ export class BaseStorage extends BaseStorageAdapter {
             }
             // Apply pagination (slice for offset)
             const paginatedVerbs = collectedVerbs.slice(offset, offset + limit);
-            const hasMore = collectedVerbs.length >= targetCount;
+            const hasMore = collectedVerbs.length > targetCount; // v5.7.11: Fixed >= to > (was causing infinite loop)
             return {
                 items: paginatedVerbs,
                 totalCount: collectedVerbs.length, // Accurate count of filtered results
@@ -1731,6 +1720,64 @@ export class BaseStorage extends BaseStorageAdapter {
         return 'relatedTo';
     }
     // ============================================================================
+    // DESERIALIZATION HELPERS (v5.7.10)
+    // Centralized Map/Set reconstruction from JSON storage format
+    // ============================================================================
+    /**
+     * Deserialize HNSW connections from JSON storage format
+     *
+     * Converts plain object { "0": ["id1"], "1": ["id2"] }
+     * into Map<number, Set<string>>
+     *
+     * v5.7.10: Central helper to fix serialization bug across all code paths
+     * Root cause: JSON.stringify(Map) = {} (empty object), must reconstruct on read
+     */
+    deserializeConnections(connections) {
+        const result = new Map();
+        if (!connections || typeof connections !== 'object') {
+            return result;
+        }
+        // Already a Map (in-memory, not from JSON)
+        if (connections instanceof Map) {
+            return connections;
+        }
+        // Deserialize from plain object
+        for (const [levelStr, ids] of Object.entries(connections)) {
+            if (Array.isArray(ids)) {
+                result.set(parseInt(levelStr, 10), new Set(ids));
+            }
+            else if (ids && typeof ids === 'object') {
+                // Handle Set-like or array-like objects
+                result.set(parseInt(levelStr, 10), new Set(Object.values(ids)));
+            }
+        }
+        return result;
+    }
+    /**
+     * Deserialize HNSWNoun from JSON storage format
+     *
+     * v5.7.10: Ensures connections are properly reconstructed from Map → object → Map
+     * Fixes: "TypeError: noun.connections.entries is not a function"
+     */
+    deserializeNoun(data) {
+        return {
+            ...data,
+            connections: this.deserializeConnections(data.connections)
+        };
+    }
+    /**
+     * Deserialize HNSWVerb from JSON storage format
+     *
+     * v5.7.10: Ensures connections are properly reconstructed from Map → object → Map
+     * Fixes same serialization bug for verbs
+     */
+    deserializeVerb(data) {
+        return {
+            ...data,
+            connections: this.deserializeConnections(data.connections)
+        };
+    }
+    // ============================================================================
     // ABSTRACT METHOD IMPLEMENTATIONS (v5.4.0)
     // Converted from abstract to concrete - all adapters now have built-in type-aware
     // ============================================================================
@@ -1760,7 +1807,9 @@ export class BaseStorage extends BaseStorageAdapter {
         if (cachedType) {
             const path = getNounVectorPath(cachedType, id);
             // COW-aware read (v5.0.1): Use COW helper for branch isolation
-            return await this.readWithInheritance(path);
+            const data = await this.readWithInheritance(path);
+            // v5.7.10: Deserialize connections Map from JSON storage format
+            return data ? this.deserializeNoun(data) : null;
         }
         // Need to search across all types (expensive, but cached after first access)
         for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
@@ -1772,7 +1821,8 @@ export class BaseStorage extends BaseStorageAdapter {
                 if (noun) {
                     // Cache the type for next time
                     this.nounTypeCache.set(id, type);
-                    return noun;
+                    // v5.7.10: Deserialize connections Map from JSON storage format
+                    return this.deserializeNoun(noun);
                 }
             }
             catch (error) {
@@ -1796,7 +1846,8 @@ export class BaseStorage extends BaseStorageAdapter {
                 // COW-aware read (v5.0.1): Use COW helper for branch isolation
                 const noun = await this.readWithInheritance(path);
                 if (noun) {
-                    nouns.push(noun);
+                    // v5.7.10: Deserialize connections Map from JSON storage format
+                    nouns.push(this.deserializeNoun(noun));
                     // Cache the type
                     this.nounTypeCache.set(noun.id, type);
                 }
@@ -1891,7 +1942,8 @@ export class BaseStorage extends BaseStorageAdapter {
             const path = getVerbVectorPath(cachedType, id);
             // COW-aware read (v5.0.1): Use COW helper for branch isolation
             const verb = await this.readWithInheritance(path);
-            return verb;
+            // v5.7.10: Deserialize connections Map from JSON storage format
+            return verb ? this.deserializeVerb(verb) : null;
         }
         // Search across all types (only on first access)
         for (let i = 0; i < VERB_TYPE_COUNT; i++) {
@@ -1903,7 +1955,8 @@ export class BaseStorage extends BaseStorageAdapter {
                 if (verb) {
                     // Cache the type for next time (read from verb.verb field)
                     this.verbTypeCache.set(id, verb.verb);
-                    return verb;
+                    // v5.7.10: Deserialize connections Map from JSON storage format
+                    return this.deserializeVerb(verb);
                 }
             }
             catch (error) {
@@ -2040,29 +2093,24 @@ export class BaseStorage extends BaseStorageAdapter {
         for (const path of paths) {
             try {
                 // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const hnswVerb = await this.readWithInheritance(path);
-                if (!hnswVerb)
+                const rawVerb = await this.readWithInheritance(path);
+                if (!rawVerb)
                     continue;
+                // v5.7.10: Deserialize connections Map from JSON storage format
+                // Replaces v5.7.8 manual deserialization (lines 2599-2605)
+                const hnswVerb = this.deserializeVerb(rawVerb);
                 // Cache type from HNSWVerb for future O(1) retrievals
                 this.verbTypeCache.set(hnswVerb.id, hnswVerb.verb);
                 // Load metadata separately (optional in v4.0.0!)
                 // FIX: Don't skip verbs without metadata - metadata is optional!
                 const metadata = await this.getVerbMetadata(hnswVerb.id);
-                // Create HNSWVerbWithMetadata (verbs don't have level field)
-                // Convert connections from plain object to Map<number, Set<string>>
-                const connectionsMap = new Map();
-                if (hnswVerb.connections && typeof hnswVerb.connections === 'object') {
-                    for (const [level, ids] of Object.entries(hnswVerb.connections)) {
-                        connectionsMap.set(Number(level), new Set(ids));
-                    }
-                }
                 // v4.8.0: Extract standard fields from metadata to top-level
                 const metadataObj = (metadata || {});
                 const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const verbWithMetadata = {
                     id: hnswVerb.id,
                     vector: [...hnswVerb.vector],
-                    connections: connectionsMap,
+                    connections: hnswVerb.connections, // v5.7.10: Already deserialized
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,

package/dist/utils/rebuildCounts.js

@@ -39,9 +39,12 @@ export async function rebuildCounts(storage) {
         throw new Error('Storage adapter does not support getNounsWithPagination');
     }
     let hasMore = true;
-    let cursor;
+    let offset = 0; // v5.7.11: Use offset-based pagination instead of cursor (bug fix for infinite loop)
     while (hasMore) {
-        const result = await storageWithPagination.getNounsWithPagination({ limit: 100, cursor });
+        const result = await storageWithPagination.getNounsWithPagination({
+            limit: 100,
+            offset // v5.7.11: Pass offset for proper pagination (previously passed cursor which was ignored)
+        });
         for (const noun of result.items) {
             const metadata = await storage.getNounMetadata(noun.id);
             if (metadata?.noun) {
@@ -51,7 +54,7 @@ export async function rebuildCounts(storage) {
             }
         }
         hasMore = result.hasMore;
-        cursor = result.nextCursor;
+        offset += 100; // v5.7.11: Increment offset for next page
     }
     console.log(`   Found ${totalNouns} entities across ${entityCounts.size} types`);
     // Scan all verbs using pagination
@@ -60,9 +63,12 @@ export async function rebuildCounts(storage) {
         throw new Error('Storage adapter does not support getVerbsWithPagination');
     }
     hasMore = true;
-    cursor = undefined;
+    offset = 0; // v5.7.11: Reset offset for verbs pagination
     while (hasMore) {
-        const result = await storageWithPagination.getVerbsWithPagination({ limit: 100, cursor });
+        const result = await storageWithPagination.getVerbsWithPagination({
+            limit: 100,
+            offset // v5.7.11: Pass offset for proper pagination (previously passed cursor which was ignored)
+        });
         for (const verb of result.items) {
             if (verb.verb) {
                 const verbType = verb.verb;
@@ -71,7 +77,7 @@ export async function rebuildCounts(storage) {
             }
         }
         hasMore = result.hasMore;
-        cursor = result.nextCursor;
+        offset += 100; // v5.7.11: Increment offset for next page
     }
     console.log(`   Found ${totalVerbs} relationships across ${verbCounts.size} types`);
     // Update storage adapter's in-memory counts FIRST

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.7.9",
+  "version": "5.7.11",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",