The __words__ keyword index stores 50-5000 entries per entity (one per
word), which inflated avg entries/entity well above the corruption
threshold of 100. This caused:
1. validateConsistency() to falsely detect corruption on every startup,
triggering unnecessary clearAllIndexData() + rebuild() cycles
2. getStats() to log false "Metadata index may be corrupted" warnings
and report inflated totalEntries/totalIds stats
Both methods now skip __words__ when counting, so stats and health
checks reflect metadata fields only (noun, type, createdAt, etc.).
Keyword search is unaffected since the __words__ field index itself
is not modified.
VFS files store content in BlobStorage, but versioning was capturing
stale embedding text from entity.data instead of actual file content.
Changes:
- VersionManager.save() now reads fresh content via vfs.readFile()
- VersionManager.restore() writes content back via vfs.writeFile()
- Text files stored as UTF-8, binary as base64 with encoding flag
- Added comprehensive VFS versioning test suite (10 tests)
- Updated API docs with VFS file versioning example
Fixes: Workshop team bug report where all VFS file versions had
identical data despite different metadata.size values.
v6.3.0 Versioning System Overhaul:
- Rewrite VersionIndex to use pure key-value storage (not entities)
- Fix restore() to use brain.update() - updates all indexes (HNSW, metadata, graph)
- Remove 525 LOC dead code (versioningAugmentation.ts - untested, unused)
- Fix branch isolation in tests (fork() vs checkout() semantics)
Key improvements:
- Versions no longer pollute find() results
- restore() properly updates all indexes
- 75 tests passing (60 unit + 15 integration)
- Net reduction of ~290 lines while fixing bugs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixed three critical bugs in v5.3.0:
1. COW ref resolution bug (lines 2354, 2856, 2895 in src/brainy.ts):
- getHistory(), commit(), deleteBranch() were prepending 'heads/' to branch names
- This caused RefManager to resolve 'heads/main' to 'refs/heads/heads/main'
- Actual ref file at 'refs/heads/main' could not be found
- Result: "Ref not found: heads/main" error breaking all COW operations
2. VersionManager commitHash bug (lines 212, 222 in src/versioning/VersionManager.ts):
- save() was assigning entire Ref object to commitHash instead of ref.commitHash
- Expected string, got object causing type mismatches in version metadata
3. Test mock improvements (tests/unit/versioning/VersionManager.test.ts):
- Fixed searchByMetadata to skip metadata check for 'type' property
- Added glob pattern support for tag filtering (e.g. 'v1.*')
- Added deleteNounMetadata mock
- Fixed getNounMetadata to return null for missing version entities
Fixes:
- src/brainy.ts (3 lines): Remove 'heads/' prefix from ref resolution calls
- src/versioning/VersionManager.ts (2 lines): Use ref.commitHash instead of ref
- tests/unit/versioning/VersionManager.test.ts: Fix test mocks
- tests/integration/history-ref-resolution-bug.test.ts: Add regression tests
Test Results:
- Before: 16 test failures
- After: 0 failures in VersionManager tests, 1183/1208 total tests passing (98%)
