soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

docs: remove exaggerated performance claims and add honest benchmarks

Browse source 
- Fixed TypeAwareStorageAdapter header comments with MEASURED vs PROJECTED labels
- Removed unverified billion-scale claims from README (tested at 1K-1M scale only)
- Fixed CHANGELOG to remove fake "TypeFirstMetadataIndex" branding
- Added performance benchmark tests with real measurements at 1K scale
- Documented limitations and projections clearly
This commit is contained in:
David Snelling 2025-10-28 09:54:01 -07:00
parent 1d4d737c60
commit 0cc00a4619
4 changed files with 220 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

38
src/storage/adapters/typeAwareStorageAdapter.ts
View file

@ -1,20 +1,38 @@
/**
* Type-Aware Storage Adapter
*
* Implements type-first storage architecture for billion-scale optimization
* Wraps underlying storage (FileSystem, GCS, S3, etc.) with type-first organization.
* Enables efficient type-based queries via directory structure.
*
* Key Features:
* IMPLEMENTED Features (v3.45.0):
* - Type-first paths: entities/nouns/{type}/vectors/{shard}/{uuid}.json
* - Fixed-size type tracking: Uint32Array(31) for nouns, Uint32Array(40) for verbs
* - O(1) type filtering: Can list entities by type via directory structure
* - Zero technical debt: Clean implementation, no legacy paths
* - 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
*
* Memory Impact @ 1B Scale:
* - Type tracking: 284 bytes (vs ~120KB with Maps) = -99.76%
* - Metadata index: 3GB (vs 5GB) = -40% (when combined with TypeFirstMetadataIndex)
* - Total system: 69GB (vs 557GB) = -88%
* 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
*
* @version 3.45.0
* 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
*/