@soulcraft/brainy 5.0.0 → 5.1.0

package/dist/storage/baseStorage.js

@@ -124,22 +124,41 @@ export class BaseStorage extends BaseStorageAdapter {
             await this.init();
         }
     }
+    /**
+     * Lightweight COW enablement - just enables branch-scoped paths
+     * Called during init() to ensure all data is stored with branch prefixes from the start
+     * RefManager/BlobStorage/CommitLog are lazy-initialized on first fork()
+     * @param branch - Branch name to use (default: 'main')
+     */
+    enableCOWLightweight(branch = 'main') {
+        if (this.cowEnabled) {
+            return;
+        }
+        this.currentBranch = branch;
+        this.cowEnabled = true;
+        // RefManager/BlobStorage/CommitLog remain undefined until first fork()
+    }
     /**
      * 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
      */
     async initializeCOW(options) {
-        if (this.cowEnabled) {
-            // Already initialized
+        // Check if RefManager already initialized (full COW setup complete)
+        if (this.refManager) {
             return;
         }
-        // Set current branch
-        this.currentBranch = options?.branch || 'main';
+        // Enable lightweight COW if not already enabled
+        if (!this.cowEnabled) {
+            this.currentBranch = options?.branch || 'main';
+            this.cowEnabled = true;
+        }
         // Create COWStorageAdapter bridge
         // This adapts BaseStorage's methods to the simple key-value interface
         const cowAdapter = {
@@ -227,6 +246,119 @@ export class BaseStorage extends BaseStorageAdapter {
         }
         this.cowEnabled = true;
     }
+    /**
+     * Resolve branch-scoped path for COW isolation
+     * @protected - Available to subclasses for COW implementation
+     */
+    resolveBranchPath(basePath, branch) {
+        if (!this.cowEnabled) {
+            return basePath; // COW disabled, use direct path
+        }
+        const targetBranch = branch || this.currentBranch || 'main';
+        // Branch-scoped path: branches/<branch>/<basePath>
+        return `branches/${targetBranch}/${basePath}`;
+    }
+    /**
+     * Write object to branch-specific path (COW layer)
+     * @protected - Available to subclasses for COW implementation
+     */
+    async writeObjectToBranch(path, data, branch) {
+        const branchPath = this.resolveBranchPath(path, branch);
+        return this.writeObjectToPath(branchPath, data);
+    }
+    /**
+     * Read object with inheritance from parent branches (COW layer)
+     * Tries current branch first, then walks commit history
+     * @protected - Available to subclasses for COW implementation
+     */
+    async readWithInheritance(path, branch) {
+        if (!this.cowEnabled) {
+            // COW disabled, direct read
+            return this.readObjectFromPath(path);
+        }
+        const targetBranch = branch || this.currentBranch || 'main';
+        // Try current branch first
+        const branchPath = this.resolveBranchPath(path, targetBranch);
+        let data = await this.readObjectFromPath(branchPath);
+        if (data !== null) {
+            return data; // Found in current branch
+        }
+        // Not in branch, check if we're on main (no inheritance needed)
+        if (targetBranch === 'main') {
+            return null;
+        }
+        // Not in branch, walk commit history to find in parent
+        if (this.refManager && this.commitLog) {
+            try {
+                const commitHash = await this.refManager.resolveRef(targetBranch);
+                if (commitHash) {
+                    // Walk parent commits until we find the data
+                    for await (const commit of this.commitLog.walk(commitHash)) {
+                        // Try reading from parent's branch path
+                        const parentBranch = commit.metadata?.branch || 'main';
+                        if (parentBranch === targetBranch)
+                            continue; // Skip self
+                        const parentPath = this.resolveBranchPath(path, parentBranch);
+                        data = await this.readObjectFromPath(parentPath);
+                        if (data !== null) {
+                            return data; // Found in ancestor
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                // Commit walk failed, fall back to main
+                const mainPath = this.resolveBranchPath(path, 'main');
+                return this.readObjectFromPath(mainPath);
+            }
+        }
+        // Last fallback: try main branch
+        const mainPath = this.resolveBranchPath(path, 'main');
+        return this.readObjectFromPath(mainPath);
+    }
+    /**
+     * Delete object from branch-specific path (COW layer)
+     * @protected - Available to subclasses for COW implementation
+     */
+    async deleteObjectFromBranch(path, branch) {
+        const branchPath = this.resolveBranchPath(path, branch);
+        return this.deleteObjectFromPath(branchPath);
+    }
+    /**
+     * List objects under path in branch (COW layer)
+     * @protected - Available to subclasses for COW implementation
+     */
+    async listObjectsInBranch(prefix, branch) {
+        const branchPrefix = this.resolveBranchPath(prefix, branch);
+        const paths = await this.listObjectsUnderPath(branchPrefix);
+        // Remove branch prefix from results
+        const targetBranch = branch || this.currentBranch || 'main';
+        const prefixToRemove = `branches/${targetBranch}/`;
+        return paths.map(p => p.startsWith(prefixToRemove) ? p.substring(prefixToRemove.length) : p);
+    }
+    /**
+     * List objects with inheritance (v5.0.1)
+     * Lists objects from current branch AND main branch, returns unique paths
+     * This enables fork to see parent's data in pagination operations
+     *
+     * Simplified approach: All branches inherit from main
+     */
+    async listObjectsWithInheritance(prefix, branch) {
+        if (!this.cowEnabled) {
+            return this.listObjectsInBranch(prefix, branch);
+        }
+        const targetBranch = branch || this.currentBranch || 'main';
+        // Collect paths from current branch
+        const pathsSet = new Set();
+        const currentBranchPaths = await this.listObjectsInBranch(prefix, targetBranch);
+        currentBranchPaths.forEach(p => pathsSet.add(p));
+        // If not on main, also list from main (all branches inherit from main)
+        if (targetBranch !== 'main') {
+            const mainPaths = await this.listObjectsInBranch(prefix, 'main');
+            mainPaths.forEach(p => pathsSet.add(p));
+        }
+        return Array.from(pathsSet);
+    }
     /**
      * Save a noun to storage (v4.0.0: vector only, metadata saved separately)
      * @param noun Pure HNSW vector data (no metadata)
@@ -839,7 +971,7 @@ export class BaseStorage extends BaseStorageAdapter {
     async saveMetadata(id, metadata) {
         await this.ensureInitialized();
         const keyInfo = this.analyzeKey(id, 'system');
-        return this.writeObjectToPath(keyInfo.fullPath, metadata);
+        return this.writeObjectToBranch(keyInfo.fullPath, metadata);
     }
     /**
      * Get metadata from storage (v4.0.0: now typed)
@@ -848,7 +980,7 @@ export class BaseStorage extends BaseStorageAdapter {
     async getMetadata(id) {
         await this.ensureInitialized();
         const keyInfo = this.analyzeKey(id, 'system');
-        return this.readObjectFromPath(keyInfo.fullPath);
+        return this.readWithInheritance(keyInfo.fullPath);
     }
     /**
      * Save noun metadata to storage (v4.0.0: now typed)
@@ -873,10 +1005,10 @@ export class BaseStorage extends BaseStorageAdapter {
         await this.ensureInitialized();
         // Determine if this is a new entity by checking if metadata already exists
         const keyInfo = this.analyzeKey(id, 'noun-metadata');
-        const existingMetadata = await this.readObjectFromPath(keyInfo.fullPath);
+        const existingMetadata = await this.readWithInheritance(keyInfo.fullPath);
         const isNew = !existingMetadata;
-        // Save the metadata
-        await this.writeObjectToPath(keyInfo.fullPath, metadata);
+        // Save the metadata (COW-aware - writes to branch-specific path)
+        await this.writeObjectToBranch(keyInfo.fullPath, metadata);
         // CRITICAL FIX (v4.1.2): Increment count for new entities
         // This runs AFTER metadata is saved, guaranteeing type information is available
         // Uses synchronous increment since storage operations are already serialized
@@ -896,7 +1028,7 @@ export class BaseStorage extends BaseStorageAdapter {
     async getNounMetadata(id) {
         await this.ensureInitialized();
         const keyInfo = this.analyzeKey(id, 'noun-metadata');
-        return this.readObjectFromPath(keyInfo.fullPath);
+        return this.readWithInheritance(keyInfo.fullPath);
     }
     /**
      * Delete noun metadata from storage
@@ -905,7 +1037,7 @@ export class BaseStorage extends BaseStorageAdapter {
     async deleteNounMetadata(id) {
         await this.ensureInitialized();
         const keyInfo = this.analyzeKey(id, 'noun-metadata');
-        return this.deleteObjectFromPath(keyInfo.fullPath);
+        return this.deleteObjectFromBranch(keyInfo.fullPath);
     }
     /**
      * Save verb metadata to storage (v4.0.0: now typed)
@@ -931,10 +1063,10 @@ export class BaseStorage extends BaseStorageAdapter {
         await this.ensureInitialized();
         // Determine if this is a new verb by checking if metadata already exists
         const keyInfo = this.analyzeKey(id, 'verb-metadata');
-        const existingMetadata = await this.readObjectFromPath(keyInfo.fullPath);
+        const existingMetadata = await this.readWithInheritance(keyInfo.fullPath);
         const isNew = !existingMetadata;
-        // Save the metadata
-        await this.writeObjectToPath(keyInfo.fullPath, metadata);
+        // Save the metadata (COW-aware - writes to branch-specific path)
+        await this.writeObjectToBranch(keyInfo.fullPath, metadata);
         // CRITICAL FIX (v4.1.2): Increment verb count for new relationships
         // This runs AFTER metadata is saved
         // Verb type is now stored in metadata (as of v4.1.2) to avoid loading HNSWVerb
@@ -955,7 +1087,7 @@ export class BaseStorage extends BaseStorageAdapter {
     async getVerbMetadata(id) {
         await this.ensureInitialized();
         const keyInfo = this.analyzeKey(id, 'verb-metadata');
-        return this.readObjectFromPath(keyInfo.fullPath);
+        return this.readWithInheritance(keyInfo.fullPath);
     }
     /**
      * Delete verb metadata from storage
@@ -964,7 +1096,7 @@ export class BaseStorage extends BaseStorageAdapter {
     async deleteVerbMetadata(id) {
         await this.ensureInitialized();
         const keyInfo = this.analyzeKey(id, 'verb-metadata');
-        return this.deleteObjectFromPath(keyInfo.fullPath);
+        return this.deleteObjectFromBranch(keyInfo.fullPath);
     }
     /**
      * Helper method to convert a Map to a plain object for serialization

package/dist/storage/cow/BlobStorage.d.ts

@@ -49,6 +49,7 @@ export interface BlobWriteOptions {
 export interface BlobReadOptions {
     skipDecompression?: boolean;
     skipCache?: boolean;
+    skipVerification?: boolean;
 }
 /**
  * Blob statistics for observability

package/dist/storage/cow/BlobStorage.js

@@ -189,11 +189,13 @@ export class BlobStorage {
             finalData = await this.zstdDecompress(data);
         }
         // Verify hash (optional, expensive)
-        if (!options.skipCache && BlobStorage.hash(finalData) !== hash) {
+        if (!options.skipVerification && BlobStorage.hash(finalData) !== hash) {
             throw new Error(`Blob integrity check failed: ${hash}`);
         }
-        // Add to cache
-        this.addToCache(hash, finalData, metadata);
+        // Add to cache (only if not skipped)
+        if (!options.skipCache) {
+            this.addToCache(hash, finalData, metadata);
+        }
         return finalData;
     }
     /**

package/dist/storage/storageFactory.d.ts

@@ -292,10 +292,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;
-    enableCOW?: boolean;
     enableCompression?: boolean;
 }
 /**

package/dist/storage/storageFactory.js

@@ -39,12 +39,13 @@ async function wrapWithTypeAware(underlying, options, verbose = false) {
         underlyingStorage: underlying,
         verbose
     });
-    // Initialize COW if enabled
-    if (options?.enableCOW && typeof wrapped.initializeCOW === 'function') {
-        await wrapped.initializeCOW({
-            branch: options.branch || 'main',
-            enableCompression: options.enableCompression !== false
-        });
+    // v5.0.1: COW will be initialized AFTER storage.init() in Brainy
+    // Store COW options for later initialization
+    if (typeof wrapped.initializeCOW === 'function') {
+        wrapped._cowOptions = {
+            branch: options?.branch || 'main',
+            enableCompression: options?.enableCompression !== false
+        };
     }
     return wrapped;
 }

package/dist/types/brainy.types.d.ts

@@ -459,7 +459,6 @@ export interface BrainyConfig {
         type: 'auto' | 'memory' | 'filesystem' | 's3' | 'r2' | 'opfs' | 'gcs';
         options?: any;
         branch?: string;
-        enableCOW?: boolean;
     };
     model?: {
         type: 'fast' | 'accurate' | 'balanced' | 'custom';

package/dist/vfs/FSCompat.d.ts

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   import { FSCompat } from '@soulcraft/brainy/vfs'
- *   const fs = new FSCompat(brain.vfs())
+ *   const fs = new FSCompat(brain.vfs)
  *
  *   // Now use like Node's fs
  *   await fs.promises.readFile('/path')

package/dist/vfs/FSCompat.js

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   import { FSCompat } from '@soulcraft/brainy/vfs'
- *   const fs = new FSCompat(brain.vfs())
+ *   const fs = new FSCompat(brain.vfs)
  *
  *   // Now use like Node's fs
  *   await fs.promises.readFile('/path')

package/dist/vfs/VirtualFileSystem.js

@@ -42,10 +42,9 @@ export class VirtualFileSystem {
             return;
         // Merge config with defaults
         this.config = { ...this.getDefaultConfig(), ...config };
-        // Initialize Brainy if needed
-        if (!this.brain.isInitialized) {
-            await this.brain.init();
-        }
+        // v5.0.1: VFS is now auto-initialized during brain.init()
+        // Brain is guaranteed to be initialized when this is called
+        // Removed brain.init() check to prevent infinite recursion
         // Create or find root entity
         this.rootEntityId = await this.initializeRoot();
         // Initialize projection registry with auto-discovery of built-in projections
@@ -847,11 +846,11 @@ export class VirtualFileSystem {
             throw new VFSError(VFSErrorCode.EINVAL, 'VFS not initialized. Call await vfs.init() before using VFS operations.\n\n' +
                 '✅ After brain.import():\n' +
                 '  await brain.import(file, { vfsPath: "/imports/data" })\n' +
-                '  const vfs = brain.vfs()\n' +
+                '  const vfs = brain.vfs\n' +
                 '  await vfs.init()  // ← Required! Safe to call multiple times\n' +
                 '  const files = await vfs.readdir("/imports/data")\n\n' +
                 '✅ Direct VFS usage:\n' +
-                '  const vfs = brain.vfs()\n' +
+                '  const vfs = brain.vfs\n' +
                 '  await vfs.init()  // ← Always required before first use\n' +
                 '  await vfs.writeFile("/docs/readme.md", "Hello")\n\n' +
                 '📖 Docs: https://github.com/soulcraftlabs/brainy/blob/main/docs/vfs/QUICK_START.md', '<unknown>', 'VFS');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",