Critical fix for v3.37.1 GCS persistence bug where HNSW rebuild reported
"Preloading 0 vectors" and hung indefinitely during container restarts.
Root Cause:
HNSW rebuild (hnswIndex.ts:835) calls storage.getStatistics() and expects
stats.totalNodes to determine entity count for adaptive caching. When
totalNodes was undefined, entityCount evaluated to 0, causing HNSW to
report "0 vectors" and hang waiting for entities that it couldn't find.
Fixes Applied:
- GcsStorage: Populate totalNodes/totalEdges from this.totalNounCount/totalVerbCount
- MemoryStorage: Populate totalNodes/totalEdges from in-memory counts
- OPFSStorage: Populate totalNodes/totalEdges in ALL return paths (cache, current day, yesterday, legacy)
- S3CompatibleStorage: Populate totalNodes/totalEdges in ALL return paths (cache, fresh stats, error fallback)
Impact:
- ✅ GCS container restarts now work correctly
- ✅ HNSW rebuild correctly detects entity count
- ✅ Adaptive caching strategy works as designed
- ✅ All storage adapters now consistent
Files exist in GCS, counts load correctly, but HNSW couldn't see them
because getStatisticsData() didn't populate the totalNodes field that
HNSW depends on.
Closes: BRAINY_V3_37_1_INDEX_REBUILD_BUG.md
Related: v3.37.0 (metadata reconstruction), v3.37.1 (getNoun_internal fix)
Fixed critical bug in 2-file architecture where getNoun_internal() and
getVerb_internal() only returned vector data without metadata, causing
brain.get() to return null despite data being correctly saved.
Changes:
- Updated all 5 storage adapters (GCS, S3, FileSystem, Memory, OPFS)
- Fixed getNoun_internal() to fetch and combine vector + metadata
- Fixed getVerb_internal() to fetch and combine vector + metadata
- Added metadata field to HNSWVerb interface for consistency
The 2-file architecture now works correctly for both read and write operations.
Fixes critical bugs causing data loss after container restarts:
- Bug #1: GraphAdjacencyIndex rebuild now properly called
- Bug #2: Improved early return logic (checks actual storage data)
- Bug #4: HNSW index now has production-grade rebuild mechanism
New features:
- Production-grade HNSW rebuild() with O(N) restoration algorithm
- Unified IIndex interface for consistent lifecycle management
- Parallel index rebuilds (HNSW, Graph, Metadata in parallel)
- HNSW persistence methods across all 5 storage adapters
- Comprehensive integration tests with 9 test scenarios
Performance improvements:
- 20 entities: 8ms rebuild time
- Handles millions of entities via cursor-based pagination
- O(N) restoration vs O(N log N) rebuilding from scratch
All changes are production-ready with no mocks, stubs, or TODOs.
Fixed critical bugs affecting test suite:
**Clustering (2 tests fixed)**
- Fixed entity.type field reference bug in _getItemsByField()
- Changed entity.noun to entity.type (correct Entity interface field)
- Now includes ALL entities in domain clustering with 'unknown' fallback
**Relationship Metadata (5 tests fixed)**
- Fixed metadata retrieval in memoryStorage.ts getVerbs()
- Changed metadata.data to metadata.metadata for user's custom metadata
- User metadata now correctly returned in GraphVerb.metadata field
**Delete Relationship Cleanup (2 tests fixed)**
- Added deleteVerbMetadata() method to BaseStorage
- Fixed deleteVerb_internal() in memoryStorage to delete verb metadata
- Relationships now properly cleaned up when entities are deleted
**Validation (1 test fixed)**
- Removed overly restrictive self-referential relationship check
- Self-relationships now allowed (valid in graph systems)
Test results: 27 failures → 17 failures (37% improvement)
All 467 tests now enabled (0 skipped)
Critical fix for GCS/S3 native storage adapters crashing on metadata index keys.
Problem:
- GCS and S3 adapters crashed with "Invalid UUID format" errors
- System keys like __metadata_field_index__status are NOT UUIDs
- Adapters incorrectly tried to shard all metadata keys as UUIDs
Solution:
- Move sharding/routing logic from adapters to BaseStorage class
- Add analyzeKey() method to detect system keys vs entity UUIDs
- System keys route to _system/ directory (no sharding)
- Entity UUIDs route to sharded directories (256 shards)
- All adapters now implement 4 primitive operations:
* writeObjectToPath(path, data)
* readObjectFromPath(path)
* deleteObjectFromPath(path)
* listObjectsUnderPath(prefix)
Benefits:
- Impossible for future adapters to repeat this mistake
- Zero breaking changes, full backward compatibility
- No data migration required
- Cleaner architecture with better separation of concerns
Updated adapters: GcsStorage, S3CompatibleStorage, OPFSStorage,
FileSystemStorage, MemoryStorage
Added: docs/architecture/data-storage-architecture.md
Updated: README.md with architecture docs link
Major enhancements for type safety and developer experience:
- Add BrainyTypes static API for type management and AI-powered suggestions
- Implement strict type validation for all 31 NounType categories
- Remove dangerous generic add() method that bypassed type safety
- Add intelligent type inference with confidence scoring
- Provide helpful error messages with typo suggestions using Levenshtein distance
- Update all internal code, examples, and documentation to use typed methods
- Enhance CLI with new type management commands (types, suggest, validate)
Breaking changes:
- Remove deprecated add() method - use addNoun() with explicit type parameter
- All addNoun() calls now require explicit type as second parameter
This release significantly improves type safety across the entire system while
maintaining backward compatibility for properly typed method calls.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
