feat: add entity versioning system with critical bug fixes (v5.3.0)

Entity Versioning (NEW):
- Add complete entity versioning API (brain.versions.*) with 18 methods
- Content-addressable storage with SHA-256 deduplication
- Git-style version control: save, restore, compare, undo, prune
- Auto-versioning augmentation with pattern-based filtering
- Branch-isolated version histories
- Complete integration tests and API documentation

Critical Bug Fixes:
- Fix commit() not updating branch refs (brainy.ts:2385)
  - Root cause: Passed "heads/main" which normalized to "refs/heads/heads/main"
  - Impact: All Git-style versioning features were broken
  - Fix: Pass branch name directly for correct normalization
- Fix VFS entities missing isVFSEntity flag
  - Add isVFSEntity: true to all VFS files/folders for filtering
  - Resolves pollution of semantic search with filesystem entities
  - Updated in writeFile(), mkdir(), and root directory init

Implementation:
- src/versioning/VersionManager.ts - Core versioning engine
- src/versioning/VersionStorage.ts - Content-addressable storage
- src/versioning/VersionIndex.ts - Metadata indexing
- src/versioning/VersionDiff.ts - Version comparison
- src/versioning/VersioningAPI.ts - Public API interface
- src/augmentations/versioningAugmentation.ts - Auto-versioning
- tests/integration/versioning.test.ts - Full integration tests
- tests/unit/versioning/ - Unit test suite

Documentation:
- Complete Entity Versioning API section in docs/api/README.md
- VFS entity filtering guide with examples
- Updated "What's New" section for v5.3.0
- Strategy docs for both critical bugs

Test Results:
- 1168 tests passing
- Build: PASSING (no TypeScript errors)
- Integration tests: ALL PASSING

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
David Snelling 2025-11-04 11:19:02 -08:00
parent b31997b1ea
commit c488fa82cc
16 changed files with 5394 additions and 9 deletions

View file

@ -33,7 +33,8 @@ export interface VFSMetadata {
name: string // Filename or directory name
parent?: string // Parent directory entity ID
vfsType: 'file' | 'directory' | 'symlink'
isVFS?: boolean // v4.3.3: Mark as VFS entity (separates from knowledge graph)
isVFS?: boolean // v4.3.3: Mark as VFS entity (internal, separates from knowledge graph)
isVFSEntity?: boolean // v5.3.0: Explicit developer-facing flag for filtering VFS entities
// File attributes
size: number // Size in bytes (0 for directories)