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

335 releases 523 tags

RSS feed
  • v5.11.0 b27dda8251

    v5.11.0 - COW Always-On + Cloud Storage Fix Stable

    dpsifr released this 2025-11-18 22:48:27 +01:00 | 538 commits to main since this release

    🚀 v5.11.0 - COW Always-On Architecture + Cloud Storage Clear() Fix

    Critical Bug Fix: Cloud Storage clear()

    FIXED: Cloud storage adapters (GCS, S3, R2, Azure) now correctly delete ALL data on clear(). Previous versions did nothing, leading to corrupted buckets.

    Major Architectural Improvement: COW Always-On

    COW (Copy-on-Write) is now always enabled and mandatory - users cannot disable it or create corrupted storage.

    What's Changed

    🔧 Core Fixes

    • Fixed GCS clear() using correct paths (branches/ instead of entities/nouns/)
    • Fixed S3 clear() path structure
    • Fixed R2 clear() implementation
    • Fixed Azure, FileSystem, OPFS, Memory clear() COW flag handling
    • clear() now deletes: branches/, _cow/, _system/
    • Result: Cloud buckets can now be fully cleared (previously impossible)

    🏗️ Architectural Changes

    • Removed cowEnabled flag from BaseStorage (COW cannot be disabled)
    • Eliminated marker file system (checkClearMarker, createClearMarker)
    • Simplified all code paths to assume COW is always enabled
    • COW automatically re-initializes after clear() operations

    📦 Container Memory Detection

    • Auto-detect Docker/K8s/Cloud Run memory limits (cgroup v1/v2)
    • Smart memory allocation (75% graph data, 25% query operations)
    • Environment variable support (CLOUD_RUN_MEMORY, MEMORY_LIMIT)
    • Production-grade containerized deployment support

    📚 Documentation

    • Complete v5.11.0 file structure reference
    • Detailed path construction algorithms
    • 8 common storage scenarios with examples
    • Type-first storage, sharding, COW architecture explained
    • See: docs/architecture/data-storage-architecture.md (1063 lines)

    Migration Guide

    For Library Users

    NO ACTION REQUIRED - This release has ZERO breaking changes.

    What you'll notice:

    • clear() now works correctly on cloud storage (GCS, S3, R2, Azure)
    • COW always enabled (can't be disabled anymore)
    • No more corrupted buckets after clear()

    If you have a corrupted bucket (data persists after clear()):

    1. Upgrade to v5.11.0
    2. Call storage.clear() again
    3. Bucket will now be fully cleared

    Technical Details

    Files Modified (14 files)

    • All 8 storage adapters (GCS, S3, R2, Azure, FS, OPFS, Memory, Historical)
    • BaseStorage core architecture
    • CommitLog with streaming support
    • Brainy memory configuration
    • Parameter validation with container detection
    • Comprehensive storage architecture documentation

    Breaking Changes

    NONE - COW was already enabled by default. This removes the ability to disable it.

    Performance Impact

    Negligible - COW was already enabled by default. Only removed conditional checks (faster, not slower).

    clear() Behavior

    • Before: Set cowEnabled = false, created marker file
    • After: Resets COW managers (auto-reinitialize on next use)
    • COW is NEVER disabled - just reinitialized fresh

    Installation

    npm install @soulcraft/brainy@5.11.0

    Or upgrade:

    npm update @soulcraft/brainy

    Full Changelog

    See commit history for detailed changes:

    • feat: COW always-on architecture + cloud storage clear() fix (v5.11.0)
    • Container memory detection for production deployments
    • Comprehensive storage architecture documentation

    Status: Production Ready ✅
    Recommended: YES - Fixes critical data loss bug

    For more information, see the release summary.

    Downloads