@soulcraft/brainy 4.11.2 → 5.1.0

package/dist/brainy.js

@@ -18,6 +18,7 @@ import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js';
 import { VirtualFileSystem } from './vfs/VirtualFileSystem.js';
 import { MetadataIndexManager } from './utils/metadataIndex.js';
 import { GraphAdjacencyIndex } from './graph/graphAdjacencyIndex.js';
+import { CommitBuilder } from './storage/cow/CommitObject.js';
 import { createPipeline } from './streaming/pipeline.js';
 import { configureLogger, LogLevel } from './utils/logger.js';
 import { DistributedCoordinator, ShardManager, CacheSync, ReadWriteSeparation } from './distributed/index.js';
@@ -96,6 +97,12 @@ export class Brainy {
             // Setup and initialize storage
             this.storage = await this.setupStorage();
             await this.storage.init();
+            // Enable COW immediately after storage init (v5.0.1)
+            // This ensures ALL data is stored in branch-scoped paths from the start
+            // Lightweight: just sets cowEnabled=true and currentBranch, no RefManager/BlobStorage yet
+            if (typeof this.storage.enableCOWLightweight === 'function') {
+                this.storage.enableCOWLightweight(this.config.storage?.branch || 'main');
+            }
             // Setup index now that we have storage
             this.index = this.setupIndex();
             // Initialize core metadata index
@@ -134,7 +141,13 @@ export class Brainy {
                 this.registerShutdownHooks();
                 Brainy.shutdownHooksRegisteredGlobally = true;
             }
+            // Mark as initialized BEFORE VFS init (v5.0.1)
+            // VFS.init() needs brain to be marked initialized to call brain methods
             this.initialized = true;
+            // Initialize VFS (v5.0.1): Ensure VFS is ready when accessed as property
+            // This eliminates need for separate vfs.init() calls - zero additional complexity
+            this._vfs = new VirtualFileSystem(this);
+            await this._vfs.init();
         }
         catch (error) {
             throw new Error(`Failed to initialize Brainy: ${error}`);
@@ -306,14 +319,16 @@ export class Brainy {
                 ...(params.weight !== undefined && { weight: params.weight }),
                 ...(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,
                 connections: new Map(),
                 level: 0
             });
-            await this.storage.saveNounMetadata(id, storageMetadata);
             // v4.8.0: Build entity structure for indexing (NEW - with top-level fields)
             const entityForIndexing = {
                 id,
@@ -1770,6 +1785,671 @@ export class Brainy {
             this._tripleIntelligence = undefined;
         });
     }
+    // ============= COW (COPY-ON-WRITE) API - v5.0.0 =============
+    /**
+     * Fork the brain (instant clone via Snowflake-style COW)
+     *
+     * Creates a shallow copy in <100ms using copy-on-write (COW) technology.
+     * Fork shares storage and HNSW data structures with parent, copying only
+     * when modified (lazy deep copy).
+     *
+     * **How It Works (v5.0.0)**:
+     * 1. HNSW Index: Shallow copy via `enableCOW()` (~10ms for 1M+ nodes)
+     * 2. Metadata Index: Fast rebuild from shared storage (<100ms)
+     * 3. Graph Index: Fast rebuild from shared storage (<500ms)
+     *
+     * **Performance**:
+     * - Fork time: <100ms @ 10K entities (MEASURED)
+     * - Memory overhead: 10-20% (shared HNSW nodes)
+     * - Storage overhead: 10-20% (shared blobs)
+     *
+     * **Write Isolation**: Changes in fork don't affect parent, and vice versa.
+     *
+     * @param branch - Optional branch name (auto-generated if not provided)
+     * @param options - Optional fork metadata (author, message)
+     * @returns New Brainy instance (forked, fully independent)
+     *
+     * @example
+     * ```typescript
+     * const brain = new Brainy()
+     * await brain.init()
+     *
+     * // Add data to parent
+     * await brain.add({ type: 'user', data: { name: 'Alice' } })
+     *
+     * // Fork instantly (<100ms)
+     * const experiment = await brain.fork('test-migration')
+     *
+     * // Make changes safely in fork
+     * await experiment.add({ type: 'user', data: { name: 'Bob' } })
+     *
+     * // Original untouched
+     * console.log((await brain.find({})).length)       // 1 (Alice)
+     * console.log((await experiment.find({})).length)  // 2 (Alice + Bob)
+     * ```
+     *
+     * @since v5.0.0
+     */
+    async fork(branch, options) {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('fork', { branch, options }, async () => {
+            const branchName = branch || `fork-${Date.now()}`;
+            // v5.0.1: Lazy COW initialization - enable automatically on first fork()
+            // This is zero-config and transparent to users
+            if (!('refManager' in this.storage) || !this.storage.refManager) {
+                // Storage supports COW but isn't initialized yet - initialize now
+                if (typeof this.storage.initializeCOW === 'function') {
+                    await this.storage.initializeCOW({
+                        branch: this.config.storage?.branch || 'main',
+                        enableCompression: true
+                    });
+                }
+                else {
+                    // Storage adapter doesn't support COW at all
+                    throw new Error('Fork requires COW-enabled storage. ' +
+                        'This storage adapter does not support branching. ' +
+                        'Please use v5.0.0+ storage adapters.');
+                }
+            }
+            const refManager = this.storage.refManager;
+            const currentBranch = this.storage.currentBranch || 'main';
+            // Step 1: Copy storage ref (COW layer - instant!)
+            await refManager.copyRef(currentBranch, branchName);
+            // Step 2: Create new Brainy instance pointing to fork branch
+            const forkConfig = {
+                ...this.config,
+                storage: {
+                    ...(this.config.storage || { type: 'memory' }),
+                    branch: branchName
+                }
+            };
+            const clone = new Brainy(forkConfig);
+            // Step 3: Clone storage with separate currentBranch
+            // Share RefManager/BlobStorage/CommitLog but maintain separate branch context
+            clone.storage = Object.create(this.storage);
+            clone.storage.currentBranch = branchName;
+            // isInitialized inherited from prototype
+            // Shallow copy HNSW index (INSTANT - just copies Map references)
+            clone.index = this.setupIndex();
+            // Enable COW (handle both HNSWIndex and TypeAwareHNSWIndex)
+            if ('enableCOW' in clone.index && typeof clone.index.enableCOW === 'function') {
+                clone.index.enableCOW(this.index);
+            }
+            // Fast rebuild for small indexes from COW storage (Metadata/Graph are fast)
+            clone.metadataIndex = new MetadataIndexManager(clone.storage);
+            await clone.metadataIndex.init();
+            clone.graphIndex = new GraphAdjacencyIndex(clone.storage);
+            await clone.graphIndex.rebuild();
+            // Setup augmentations
+            clone.augmentationRegistry = this.setupAugmentations();
+            await clone.augmentationRegistry.initializeAll({
+                brain: clone,
+                storage: clone.storage,
+                config: clone.config,
+                log: (message, level) => {
+                    if (!clone.config.silent) {
+                        console[level || 'info'](message);
+                    }
+                }
+            });
+            // Mark as initialized
+            clone.initialized = true;
+            clone.dimensions = this.dimensions;
+            return clone;
+        });
+    }
+    /**
+     * List all branches/forks
+     * @returns Array of branch names
+     *
+     * @example
+     * ```typescript
+     * const branches = await brain.listBranches()
+     * console.log(branches) // ['main', 'experiment', 'backup']
+     * ```
+     */
+    async listBranches() {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('listBranches', {}, async () => {
+            if (!('refManager' in this.storage)) {
+                throw new Error('Branch management requires COW-enabled storage (v5.0.0+)');
+            }
+            const refManager = this.storage.refManager;
+            const refs = await refManager.listRefs();
+            // Filter to branches only (exclude tags)
+            return refs
+                .filter((ref) => ref.name.startsWith('refs/heads/'))
+                .map((ref) => ref.name.replace('refs/heads/', ''));
+        });
+    }
+    /**
+     * Get current branch name
+     * @returns Current branch name
+     *
+     * @example
+     * ```typescript
+     * const current = await brain.getCurrentBranch()
+     * console.log(current) // 'main'
+     * ```
+     */
+    async getCurrentBranch() {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('getCurrentBranch', {}, async () => {
+            if (!('currentBranch' in this.storage)) {
+                return 'main'; // Default branch
+            }
+            return this.storage.currentBranch || 'main';
+        });
+    }
+    /**
+     * Switch to a different branch
+     * @param branch - Branch name to switch to
+     *
+     * @example
+     * ```typescript
+     * await brain.checkout('experiment')
+     * console.log(await brain.getCurrentBranch()) // 'experiment'
+     * ```
+     */
+    async checkout(branch) {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('checkout', { branch }, async () => {
+            if (!('refManager' in this.storage)) {
+                throw new Error('Branch management requires COW-enabled storage (v5.0.0+)');
+            }
+            // Verify branch exists
+            const branches = await this.listBranches();
+            if (!branches.includes(branch)) {
+                throw new Error(`Branch '${branch}' does not exist`);
+            }
+            // Update storage currentBranch
+            this.storage.currentBranch = branch;
+            // Reload from new branch
+            // Clear indexes and reload
+            this.index = this.setupIndex();
+            this.metadataIndex = new MetadataIndexManager(this.storage);
+            this.graphIndex = new GraphAdjacencyIndex(this.storage);
+            // Re-initialize
+            this.initialized = false;
+            await this.init();
+        });
+    }
+    /**
+     * Create a commit with current state
+     * @param options - Commit options (message, author, metadata)
+     * @returns Commit hash
+     *
+     * @example
+     * ```typescript
+     * await brain.add({ noun: 'user', data: { name: 'Alice' } })
+     * const commitHash = await brain.commit({
+     *   message: 'Add Alice user',
+     *   author: 'dev@example.com'
+     * })
+     * ```
+     */
+    async commit(options) {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('commit', { options }, async () => {
+            if (!('refManager' in this.storage) || !('commitLog' in this.storage) || !('blobStorage' in this.storage)) {
+                throw new Error('Commit requires COW-enabled storage (v5.0.0+)');
+            }
+            const refManager = this.storage.refManager;
+            const blobStorage = this.storage.blobStorage;
+            const currentBranch = await this.getCurrentBranch();
+            // Get current HEAD commit (parent)
+            const currentCommitHash = await refManager.resolveRef(`heads/${currentBranch}`);
+            // Get current state statistics
+            const entityCount = await this.getNounCount();
+            const relationshipCount = await this.getVerbCount();
+            // Build commit object using builder pattern
+            const builder = CommitBuilder.create(blobStorage)
+                .tree('0000000000000000000000000000000000000000000000000000000000000000') // Empty tree hash for now
+                .message(options?.message || 'Snapshot commit')
+                .author(options?.author || 'unknown')
+                .timestamp(Date.now())
+                .entityCount(entityCount)
+                .relationshipCount(relationshipCount);
+            // Set parent if this is not the first commit
+            if (currentCommitHash) {
+                builder.parent(currentCommitHash);
+            }
+            // Add custom metadata
+            if (options?.metadata) {
+                Object.entries(options.metadata).forEach(([key, value]) => {
+                    builder.meta(key, value);
+                });
+            }
+            // Build and persist commit (returns hash directly)
+            const commitHash = await builder.build();
+            // Update branch ref to point to new commit
+            await refManager.setRef(`heads/${currentBranch}`, commitHash, {
+                author: options?.author || 'unknown',
+                message: options?.message || 'Snapshot commit'
+            });
+            return commitHash;
+        });
+    }
+    /**
+     * Merge a source branch into target branch
+     * @param sourceBranch - Branch to merge from
+     * @param targetBranch - Branch to merge into
+     * @param options - Merge options (strategy, author, onConflict)
+     * @returns Merge result with statistics
+     *
+     * @example
+     * ```typescript
+     * const result = await brain.merge('experiment', 'main', {
+     *   strategy: 'last-write-wins',
+     *   author: 'dev@example.com'
+     * })
+     * console.log(result) // { added: 5, modified: 3, deleted: 1, conflicts: 0 }
+     * ```
+     */
+    async merge(sourceBranch, targetBranch, options) {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('merge', { sourceBranch, targetBranch, options }, async () => {
+            if (!('refManager' in this.storage) || !('blobStorage' in this.storage)) {
+                throw new Error('Merge requires COW-enabled storage (v5.0.0+)');
+            }
+            const strategy = options?.strategy || 'last-write-wins';
+            let added = 0;
+            let modified = 0;
+            let deleted = 0;
+            let conflicts = 0;
+            // Verify both branches exist
+            const branches = await this.listBranches();
+            if (!branches.includes(sourceBranch)) {
+                throw new Error(`Source branch '${sourceBranch}' does not exist`);
+            }
+            if (!branches.includes(targetBranch)) {
+                throw new Error(`Target branch '${targetBranch}' does not exist`);
+            }
+            // 1. Create temporary fork of source branch to read from
+            const sourceFork = await this.fork(`${sourceBranch}-merge-temp-${Date.now()}`);
+            await sourceFork.checkout(sourceBranch);
+            // 2. Save current branch and checkout target
+            const currentBranch = await this.getCurrentBranch();
+            if (currentBranch !== targetBranch) {
+                await this.checkout(targetBranch);
+            }
+            try {
+                // 3. Get all entities from source and target
+                const sourceResults = await sourceFork.find({});
+                const targetResults = await this.find({});
+                // Create maps for faster lookup
+                const targetMap = new Map(targetResults.map(r => [r.entity.id, r.entity]));
+                // 4. Merge entities
+                for (const sourceResult of sourceResults) {
+                    const sourceEntity = sourceResult.entity;
+                    const targetEntity = targetMap.get(sourceEntity.id);
+                    if (!targetEntity) {
+                        // NEW entity in source - ADD to target
+                        await this.add({
+                            id: sourceEntity.id,
+                            type: sourceEntity.type,
+                            data: sourceEntity.data,
+                            vector: sourceEntity.vector
+                        });
+                        added++;
+                    }
+                    else {
+                        // Entity exists in both branches - check for conflicts
+                        const sourceTime = sourceEntity.updatedAt || sourceEntity.createdAt || 0;
+                        const targetTime = targetEntity.updatedAt || targetEntity.createdAt || 0;
+                        // If timestamps are identical, no change needed
+                        if (sourceTime === targetTime) {
+                            continue;
+                        }
+                        // Apply merge strategy
+                        if (strategy === 'last-write-wins') {
+                            if (sourceTime > targetTime) {
+                                // Source is newer, update target
+                                await this.update({ id: sourceEntity.id, data: sourceEntity.data });
+                                modified++;
+                            }
+                            // else target is newer, keep target
+                        }
+                        else if (strategy === 'first-write-wins') {
+                            if (sourceTime < targetTime) {
+                                // Source is older, update target
+                                await this.update({ id: sourceEntity.id, data: sourceEntity.data });
+                                modified++;
+                            }
+                        }
+                        else if (strategy === 'custom' && options?.onConflict) {
+                            // Custom conflict resolution
+                            const resolved = await options.onConflict(targetEntity, sourceEntity);
+                            await this.update({ id: sourceEntity.id, data: resolved.data });
+                            modified++;
+                            conflicts++;
+                        }
+                        else {
+                            // Conflict detected but no resolution strategy
+                            conflicts++;
+                        }
+                    }
+                }
+                // 5. Merge relationships (verbs)
+                const sourceVerbsResult = await sourceFork.storage.getVerbs({});
+                const targetVerbsResult = await this.storage.getVerbs({});
+                const sourceVerbs = sourceVerbsResult.items || [];
+                const targetVerbs = targetVerbsResult.items || [];
+                // Create set of existing target relationships for deduplication
+                const targetRelSet = new Set(targetVerbs.map((v) => `${v.sourceId}-${v.verb}-${v.targetId}`));
+                // Add relationships that don't exist in target
+                for (const sourceVerb of sourceVerbs) {
+                    const key = `${sourceVerb.sourceId}-${sourceVerb.verb}-${sourceVerb.targetId}`;
+                    if (!targetRelSet.has(key)) {
+                        // Only add if both entities exist in target
+                        const hasSource = targetMap.has(sourceVerb.sourceId);
+                        const hasTarget = targetMap.has(sourceVerb.targetId);
+                        if (hasSource && hasTarget) {
+                            await this.relate({
+                                from: sourceVerb.sourceId,
+                                to: sourceVerb.targetId,
+                                type: sourceVerb.verb,
+                                weight: sourceVerb.weight,
+                                metadata: sourceVerb.metadata
+                            });
+                        }
+                    }
+                }
+                // 6. Create merge commit
+                if ('commitLog' in this.storage) {
+                    await this.commit({
+                        message: `Merge ${sourceBranch} into ${targetBranch}`,
+                        author: options?.author || 'system',
+                        metadata: {
+                            mergeType: 'branch',
+                            source: sourceBranch,
+                            target: targetBranch,
+                            strategy,
+                            stats: { added, modified, deleted, conflicts }
+                        }
+                    });
+                }
+            }
+            finally {
+                // 7. Clean up temporary fork (just delete the temp branch)
+                try {
+                    const tempBranchName = `${sourceBranch}-merge-temp-${Date.now()}`;
+                    const branches = await this.listBranches();
+                    if (branches.includes(tempBranchName)) {
+                        await this.deleteBranch(tempBranchName);
+                    }
+                }
+                catch (err) {
+                    // Ignore cleanup errors
+                }
+                // Restore original branch if needed
+                if (currentBranch !== targetBranch) {
+                    await this.checkout(currentBranch);
+                }
+            }
+            return { added, modified, deleted, conflicts };
+        });
+    }
+    /**
+     * Compare differences between two branches (like git diff)
+     * @param sourceBranch - Branch to compare from (defaults to current branch)
+     * @param targetBranch - Branch to compare to (defaults to 'main')
+     * @returns Diff result showing added, modified, and deleted entities/relationships
+     *
+     * @example
+     * ```typescript
+     * // Compare current branch with main
+     * const diff = await brain.diff()
+     *
+     * // Compare two specific branches
+     * const diff = await brain.diff('experiment', 'main')
+     * console.log(diff)
+     * // {
+     * //   entities: { added: 5, modified: 3, deleted: 1 },
+     * //   relationships: { added: 10, modified: 2, deleted: 0 }
+     * // }
+     * ```
+     */
+    async diff(sourceBranch, targetBranch) {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('diff', { sourceBranch, targetBranch }, async () => {
+            // Default branches
+            const source = sourceBranch || (await this.getCurrentBranch());
+            const target = targetBranch || 'main';
+            const currentBranch = await this.getCurrentBranch();
+            // If source is current branch, use this instance directly (no fork needed)
+            let sourceFork;
+            let sourceForkCreated = false;
+            if (source === currentBranch) {
+                sourceFork = this;
+            }
+            else {
+                sourceFork = await this.fork(`temp-diff-source-${Date.now()}`);
+                sourceForkCreated = true;
+                try {
+                    await sourceFork.checkout(source);
+                }
+                catch (err) {
+                    // If checkout fails, branch may not exist - just use current state
+                }
+            }
+            // If target is current branch, use this instance directly (no fork needed)
+            let targetFork;
+            let targetForkCreated = false;
+            if (target === currentBranch) {
+                targetFork = this;
+            }
+            else {
+                targetFork = await this.fork(`temp-diff-target-${Date.now()}`);
+                targetForkCreated = true;
+                try {
+                    await targetFork.checkout(target);
+                }
+                catch (err) {
+                    // If checkout fails, branch may not exist - just use current state
+                }
+            }
+            try {
+                // Get all entities from both branches
+                const sourceResults = await sourceFork.find({});
+                const targetResults = await targetFork.find({});
+                // Create maps for lookup
+                const sourceMap = new Map(sourceResults.map(r => [r.entity.id, r.entity]));
+                const targetMap = new Map(targetResults.map(r => [r.entity.id, r.entity]));
+                // Track differences
+                const entitiesAdded = [];
+                const entitiesModified = [];
+                const entitiesDeleted = [];
+                // Find added and modified entities
+                for (const [id, sourceEntity] of sourceMap.entries()) {
+                    const targetEntity = targetMap.get(id);
+                    if (!targetEntity) {
+                        // Entity exists in source but not target = ADDED
+                        entitiesAdded.push({
+                            id: sourceEntity.id,
+                            type: sourceEntity.type,
+                            data: sourceEntity.data
+                        });
+                    }
+                    else {
+                        // Entity exists in both - check for modifications
+                        const changes = [];
+                        if (sourceEntity.data !== targetEntity.data) {
+                            changes.push('data');
+                        }
+                        if ((sourceEntity.updatedAt || 0) !== (targetEntity.updatedAt || 0)) {
+                            changes.push('updatedAt');
+                        }
+                        if (changes.length > 0) {
+                            entitiesModified.push({
+                                id: sourceEntity.id,
+                                type: sourceEntity.type,
+                                changes
+                            });
+                        }
+                    }
+                }
+                // Find deleted entities (in target but not in source)
+                for (const [id, targetEntity] of targetMap.entries()) {
+                    if (!sourceMap.has(id)) {
+                        entitiesDeleted.push({
+                            id: targetEntity.id,
+                            type: targetEntity.type
+                        });
+                    }
+                }
+                // Compare relationships
+                const sourceVerbsResult = await sourceFork.storage.getVerbs({});
+                const targetVerbsResult = await targetFork.storage.getVerbs({});
+                const sourceVerbs = sourceVerbsResult.items || [];
+                const targetVerbs = targetVerbsResult.items || [];
+                const sourceRelMap = new Map(sourceVerbs.map((v) => [`${v.sourceId}-${v.verb}-${v.targetId}`, v]));
+                const targetRelMap = new Map(targetVerbs.map((v) => [`${v.sourceId}-${v.verb}-${v.targetId}`, v]));
+                const relationshipsAdded = [];
+                const relationshipsModified = [];
+                const relationshipsDeleted = [];
+                // Find added and modified relationships
+                for (const [key, sourceVerb] of sourceRelMap.entries()) {
+                    const targetVerb = targetRelMap.get(key);
+                    if (!targetVerb) {
+                        // Relationship exists in source but not target = ADDED
+                        relationshipsAdded.push({
+                            from: sourceVerb.sourceId,
+                            to: sourceVerb.targetId,
+                            type: sourceVerb.verb
+                        });
+                    }
+                    else {
+                        // Relationship exists in both - check for modifications
+                        const changes = [];
+                        if ((sourceVerb.weight || 0) !== (targetVerb.weight || 0)) {
+                            changes.push('weight');
+                        }
+                        if (JSON.stringify(sourceVerb.metadata) !== JSON.stringify(targetVerb.metadata)) {
+                            changes.push('metadata');
+                        }
+                        if (changes.length > 0) {
+                            relationshipsModified.push({
+                                from: sourceVerb.sourceId,
+                                to: sourceVerb.targetId,
+                                type: sourceVerb.verb,
+                                changes
+                            });
+                        }
+                    }
+                }
+                // Find deleted relationships
+                for (const [key, targetVerb] of targetRelMap.entries()) {
+                    if (!sourceRelMap.has(key)) {
+                        relationshipsDeleted.push({
+                            from: targetVerb.sourceId,
+                            to: targetVerb.targetId,
+                            type: targetVerb.verb
+                        });
+                    }
+                }
+                return {
+                    entities: {
+                        added: entitiesAdded,
+                        modified: entitiesModified,
+                        deleted: entitiesDeleted
+                    },
+                    relationships: {
+                        added: relationshipsAdded,
+                        modified: relationshipsModified,
+                        deleted: relationshipsDeleted
+                    },
+                    summary: {
+                        entitiesAdded: entitiesAdded.length,
+                        entitiesModified: entitiesModified.length,
+                        entitiesDeleted: entitiesDeleted.length,
+                        relationshipsAdded: relationshipsAdded.length,
+                        relationshipsModified: relationshipsModified.length,
+                        relationshipsDeleted: relationshipsDeleted.length
+                    }
+                };
+            }
+            finally {
+                // Clean up temporary forks (only if we created them)
+                try {
+                    const branches = await this.listBranches();
+                    if (sourceForkCreated && sourceFork !== this) {
+                        const sourceBranchName = await sourceFork.getCurrentBranch();
+                        if (branches.includes(sourceBranchName)) {
+                            await this.deleteBranch(sourceBranchName);
+                        }
+                    }
+                    if (targetForkCreated && targetFork !== this) {
+                        const targetBranchName = await targetFork.getCurrentBranch();
+                        if (branches.includes(targetBranchName)) {
+                            await this.deleteBranch(targetBranchName);
+                        }
+                    }
+                }
+                catch (err) {
+                    // Ignore cleanup errors
+                }
+            }
+        });
+    }
+    /**
+     * Delete a branch/fork
+     * @param branch - Branch name to delete
+     *
+     * @example
+     * ```typescript
+     * await brain.deleteBranch('old-experiment')
+     * ```
+     */
+    async deleteBranch(branch) {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('deleteBranch', { branch }, async () => {
+            if (!('refManager' in this.storage)) {
+                throw new Error('Branch management requires COW-enabled storage (v5.0.0+)');
+            }
+            const currentBranch = await this.getCurrentBranch();
+            if (branch === currentBranch) {
+                throw new Error('Cannot delete current branch');
+            }
+            const refManager = this.storage.refManager;
+            await refManager.deleteRef(`heads/${branch}`);
+        });
+    }
+    /**
+     * Get commit history for current branch
+     * @param options - History options (limit, offset, author)
+     * @returns Array of commits
+     *
+     * @example
+     * ```typescript
+     * const history = await brain.getHistory({ limit: 10 })
+     * history.forEach(commit => {
+     *   console.log(`${commit.hash}: ${commit.message}`)
+     * })
+     * ```
+     */
+    async getHistory(options) {
+        await this.ensureInitialized();
+        return this.augmentationRegistry.execute('getHistory', { options }, async () => {
+            if (!('commitLog' in this.storage) || !('refManager' in this.storage)) {
+                throw new Error('History requires COW-enabled storage (v5.0.0+)');
+            }
+            const commitLog = this.storage.commitLog;
+            const currentBranch = await this.getCurrentBranch();
+            // Get commit history for current branch
+            const commits = await commitLog.getHistory(`heads/${currentBranch}`, {
+                maxCount: options?.limit || 10
+            });
+            // Map to expected format (compute hash for each commit)
+            return commits.map((commit) => ({
+                hash: this.storage.blobStorage.constructor.hash(Buffer.from(JSON.stringify(commit))),
+                message: commit.message,
+                author: commit.author,
+                timestamp: commit.timestamp,
+                metadata: commit.metadata
+            }));
+        });
+    }
     /**
      * Get total count of nouns - O(1) operation
      * @returns Promise that resolves to the total number of nouns
@@ -1971,36 +2651,46 @@ export class Brainy {
         return await coordinator.import(source, options);
     }
     /**
-     * Virtual File System API - Knowledge Operating System
+     * Virtual File System API - Knowledge Operating System (v5.0.1+)
      *
-     * Returns a cached VFS instance. You must call vfs.init() before use:
+     * Returns a cached VFS instance that is auto-initialized during brain.init().
+     * No separate initialization needed!
      *
      * @example After import
      * ```typescript
      * await brain.import('./data.xlsx', { vfsPath: '/imports/data' })
-     *
-     * const vfs = brain.vfs()
-     * await vfs.init()  // Required! (safe to call multiple times)
-     * const files = await vfs.readdir('/imports/data')
+     * // VFS ready immediately - no init() call needed!
+     * const files = await brain.vfs.readdir('/imports/data')
      * ```
      *
      * @example Direct VFS usage
      * ```typescript
-     * const vfs = brain.vfs()
-     * await vfs.init()  // Always required before first use
-     * await vfs.writeFile('/docs/readme.md', 'Hello World')
-     * const content = await vfs.readFile('/docs/readme.md')
+     * await brain.init()  // VFS auto-initialized here!
+     * await brain.vfs.writeFile('/docs/readme.md', 'Hello World')
+     * const content = await brain.vfs.readFile('/docs/readme.md')
      * ```
      *
-     * **Note:** brain.import() automatically initializes the VFS, so after
-     * an import you can call vfs.init() again (it's idempotent) and immediately
-     * query the imported files.
+     * @example With fork (COW isolation)
+     * ```typescript
+     * await brain.init()
+     * await brain.vfs.writeFile('/config.json', '{"v": 1}')
+     *
+     * const fork = await brain.fork('experiment')
+     * // Fork inherits parent's files
+     * const config = await fork.vfs.readFile('/config.json')
+     * // Fork modifications are isolated
+     * await fork.vfs.writeFile('/test.txt', 'Fork only')
+     * ```
      *
-     * **Pattern:** The VFS instance is cached, so multiple calls to brain.vfs()
+     * **Pattern:** The VFS instance is cached, so multiple calls to brain.vfs
      * return the same instance. This ensures import and user code share state.
+     *
+     * @since v5.0.1 - Auto-initialization during brain.init()
      */
-    vfs() {
+    get vfs() {
         if (!this._vfs) {
+            // VFS is initialized during brain.init() (v5.0.1)
+            // If not initialized yet, create instance but user should call brain.init() first
             this._vfs = new VirtualFileSystem(this);
         }
         return this._vfs;