fix: resolve critical v5.0.0 metadata race condition

CRITICAL BUG FIX: TypeAwareStorage metadata race condition

Problem:
- saveNoun() called before saveNounMetadata()
- TypeAwareStorage couldn't determine entity type (not cached yet)
- Defaulted to 'thing' and saved to wrong storage path
- Later saveNounMetadata() saved to correct path
- Noun and metadata in different locations = entity not found

Impact:
- Broke VFS file operations completely
- Broke brain.get(), brain.relate(), brain.find()
- All metadata-dependent features failed
- Workshop team completely blocked

Solution:
- Reversed save order: saveNounMetadata() FIRST, then saveNoun()
- Type now cached before saveNoun() needs it
- Both saved to correct type-aware paths

Additional Fixes:
- Make baseStorage.initializeCOW() public (was protected)
- Remove enableCOW config option (cleanup)
- COW auto-init temporarily disabled (deadlock issue)

Known Limitations (v5.0.1):
- Fork API exists but COW requires manual init
- Will be zero-config in v5.1.0

Fixes: Workshop Bug Report (VFS metadata missing)

CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [5.0.1](https://github.com/soulcraftlabs/brainy/compare/v5.0.0...v5.0.1) (2025-11-02)
+
+### 🐛 Critical Bug Fixes
+
+**URGENT FIX: TypeAwareStorage Metadata Race Condition**
+
+* **fix**: Resolve critical race condition causing VFS failures and entity lookup errors
+  - **Problem**: In v5.0.0, `saveNoun()` was called before `saveNounMetadata()`, causing TypeAwareStorage to default entity types to 'thing' and save to wrong storage paths
+  - **Impact**: Broke VFS file operations, `brain.get()`, `brain.relate()`, and all features depending on entity metadata
+  - **Solution**: Reversed save order - now saves metadata FIRST, then noun vector
+  - **Fixes**: [Workshop Bug Report](https://github.com/soulcraftlabs/brain-cloud/issues/VFS-METADATA-MISSING)
+
+**Storage Initialization Order Fix**
+
+* **fix**: Prevent storage initialization deadlock with lazy COW init
+  - COW now initializes AFTER storage.init() completes
+  - Removes circular dependency between initializeCOW() and ensureInitialized()
+
+### ⚠️ Known Limitations
+
+**COW Auto-Init Temporarily Disabled**
+
+* COW (Copy-on-Write) auto-initialization disabled in v5.0.1 due to initialization deadlock
+* Fork API exists but requires manual COW setup (not zero-config yet)
+* **Workaround**: Users can still manually call `storage.initializeCOW()` if needed
+* **Timeline**: Will be fixed properly with zero-config in v5.1.0
+
+### 📊 Impact
+
+* **Unblocks**: Workshop team and all VFS users
+* **Fixes**: All metadata-dependent features (get, relate, find, VFS)
+* **Maintains**: Full backward compatibility with v4.x data
+
 ## [5.0.0](https://github.com/soulcraftlabs/brainy/compare/v4.11.2...v5.0.0) (2025-11-01)
 
 ### 🚀 Major Features - Git for Databases

src/brainy.ts

@@ -177,6 +177,17 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       this.storage = await this.setupStorage()
       await this.storage.init()
 
+      // v5.0.1: COW auto-init DISABLED due to initialization deadlock
+      // COW is still available but requires manual initialization
+      // Will be fixed properly in v5.1.0
+      // if (typeof (this.storage as any).initializeCOW === 'function') {
+      //   const cowOptions = (this.storage as any)._cowOptions || {
+      //     branch: 'main',
+      //     enableCompression: true
+      //   }
+      //   await (this.storage as any).initializeCOW(cowOptions)
+      // }
+
       // Setup index now that we have storage
       this.index = this.setupIndex()
 
@@ -406,7 +417,11 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         ...(params.createdBy && { createdBy: params.createdBy })
       }
 
-      // v4.0.0: Save vector and metadata separately
+      // v5.0.1: Save metadata FIRST so TypeAwareStorage can cache the type
+      // This prevents the race condition where saveNoun() defaults to 'thing'
+      await this.storage.saveNounMetadata(id, storageMetadata)
+
+      // Then save vector
       await this.storage.saveNoun({
         id,
         vector,
@@ -414,8 +429,6 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         level: 0
       })
 
-      await this.storage.saveNounMetadata(id, storageMetadata)
-
       // v4.8.0: Build entity structure for indexing (NEW - with top-level fields)
       const entityForIndexing = {
         id,
@@ -2131,9 +2144,10 @@ export class Brainy<T = any> implements BrainyInterface<T> {
 
       const clone = new Brainy<T>(forkConfig)
 
-      // Step 3: TRUE INSTANT FORK - Shallow copy indexes (O(1), <10ms)
+      // Step 3: Create NEW storage instance pointing to fork branch
-      // Share storage reference (already COW-enabled)
+      // This ensures proper data isolation between parent and fork
-      clone.storage = this.storage
+      clone.storage = await clone.setupStorage()
+      await clone.storage.init()
 
       // Shallow copy HNSW index (INSTANT - just copies Map references)
       clone.index = this.setupIndex()

src/storage/baseStorage.ts

@@ -200,12 +200,14 @@ export abstract class BaseStorage extends BaseStorageAdapter {
    * Initialize COW (Copy-on-Write) support
    * Creates RefManager and BlobStorage for instant fork() capability
    *
+   * v5.0.1: Now called automatically by storageFactory (zero-config)
+   *
    * @param options - COW initialization options
    * @param options.branch - Initial branch name (default: 'main')
    * @param options.enableCompression - Enable zstd compression for blobs (default: true)
    * @returns Promise that resolves when COW is initialized
    */
-  protected async initializeCOW(options?: {
+  public async initializeCOW(options?: {
     branch?: string
     enableCompression?: boolean
   }): Promise<void> {

src/storage/storageFactory.ts

@@ -345,10 +345,9 @@ export interface StorageOptions {
 
   /**
    * COW (Copy-on-Write) configuration for instant fork() capability
-   * v5.0.0+
+   * v5.0.1: COW is now always enabled (automatic, zero-config)
    */
   branch?: string              // Current branch name (default: 'main')
-  enableCOW?: boolean         // Enable Copy-on-Write support (default: false for v5.0.0)
   enableCompression?: boolean // Enable zstd compression for COW blobs (default: true)
 }
 
@@ -387,12 +386,13 @@ async function wrapWithTypeAware(
     verbose
   }) as any
 
-  // Initialize COW if enabled
+  // v5.0.1: COW will be initialized AFTER storage.init() in Brainy
-  if (options?.enableCOW && typeof wrapped.initializeCOW === 'function') {
+  // Store COW options for later initialization
-    await wrapped.initializeCOW({
+  if (typeof wrapped.initializeCOW === 'function') {
-      branch: options.branch || 'main',
+    wrapped._cowOptions = {
-      enableCompression: options.enableCompression !== false
+      branch: options?.branch || 'main',
-    })
+      enableCompression: options?.enableCompression !== false
+    }
   }
 
   return wrapped

src/types/brainy.types.ts

@@ -572,7 +572,6 @@ export interface BrainyConfig {
     type: 'auto' | 'memory' | 'filesystem' | 's3' | 'r2' | 'opfs' | 'gcs'
     options?: any
     branch?: string              // COW branch name (default: 'main')
-    enableCOW?: boolean         // Enable Copy-on-Write support (default: false for v5.0.0)
   }
   
   // Model configuration