335 releases 524 tags

RSS feed

• v5.7.2 b40ad56821

  Compare

  v5.7.2 - Race Condition Fix Stable

  dpsifr released this 2025-11-12 18:33:21 +01:00 | 585 commits to main since this release

  🐛 Critical Bug Fix

  Resolves the critical race condition in v5.7.0/v5.7.1 where brain.add() followed by brain.relate() would fail with "Source entity not found" error.

  Problem

  • v5.7.0 removed inline deduplication for 12-24x import speedup
  • Exposed async write race condition: entities written weren't immediately queryable
  • Caused PDF import failures and VFS structure generation errors

  Solution

  Write-through cache at storage layer (baseStorage.ts):

  • Caches data during async writes (synchronous operation)
  • Checks cache before disk reads (guarantees read-after-write consistency)
  • Self-cleaning (cache clears after write completes)
  • Zero-config, automatic for all 8 storage adapters
  • Works with COW branch isolation

  Impact

  ✅ Fixes PDF import failures in v5.7.0/v5.7.1
  ✅ Maintains 12-24x import speedup from v5.7.0
  ✅ Production-ready for billion-scale deployments
  ✅ Zero breaking changes, drop-in replacement

  Test Coverage

  • 8 unit tests (write-through cache behavior)
  • 7 integration tests (brain.add → brain.relate scenarios)
  • 74 regression tests verified passing

  Upgrade Path

  npm install @soulcraft/brainy@5.7.2
  

  No code changes required - the fix is automatic at the storage layer.

  Technical Details

  Modified: src/storage/baseStorage.ts

  • Added write-through cache (Map<string, any>)
  • Modified writeObjectToBranch() to cache during writes
  • Modified readWithInheritance() to check cache first
  • Modified deleteObjectFromBranch() to clear cache

  Commit: 732d23b

  Downloads

  • Source code (ZIP)
    1 download
  • Source code (TAR.GZ)
    1 download