@soulcraft/brainy 5.0.0 → 5.1.0

package/dist/brainy.js

@@ -97,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
@@ -135,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}`);
@@ -307,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,
@@ -1820,11 +1834,22 @@ export class Brainy {
         await this.ensureInitialized();
         return this.augmentationRegistry.execute('fork', { branch, options }, async () => {
             const branchName = branch || `fork-${Date.now()}`;
-            // Check if storage has RefManager (COW enabled)
-            if (!('refManager' in this.storage)) {
-                throw new Error('Fork requires COW-enabled storage. ' +
-                    'This storage adapter does not support branching. ' +
-                    'Please use v5.0.0+ storage adapters.');
+            // 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';
@@ -1839,9 +1864,11 @@ export class Brainy {
                 }
             };
             const clone = new Brainy(forkConfig);
-            // Step 3: TRUE INSTANT FORK - Shallow copy indexes (O(1), <10ms)
-            // Share storage reference (already COW-enabled)
-            clone.storage = this.storage;
+            // 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)
@@ -1891,8 +1918,8 @@ export class Brainy {
             const refs = await refManager.listRefs();
             // Filter to branches only (exclude tags)
             return refs
-                .filter((ref) => ref.startsWith('heads/'))
-                .map((ref) => ref.replace('heads/', ''));
+                .filter((ref) => ref.name.startsWith('refs/heads/'))
+                .map((ref) => ref.name.replace('refs/heads/', ''));
         });
     }
     /**
@@ -2163,6 +2190,208 @@ export class Brainy {
             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
@@ -2422,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}')
      *
-     * **Pattern:** The VFS instance is cached, so multiple calls to brain.vfs()
+     * 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
      * 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;

package/dist/cli/commands/import.js

@@ -416,7 +416,7 @@ export const importCommands = {
             spinner = ora('Initializing VFS import...').start();
             const brain = getBrainy();
             // Get VFS
-            const vfs = await brain.vfs();
+            const vfs = await brain.vfs;
             // Load DirectoryImporter
             const { DirectoryImporter } = await import('../../vfs/importers/DirectoryImporter.js');
             const importer = new DirectoryImporter(vfs, brain);

package/dist/cli/commands/vfs.js

@@ -9,9 +9,10 @@ import Table from 'cli-table3';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { Brainy } from '../../brainy.js';
 let brainyInstance = null;
-const getBrainy = () => {
+const getBrainy = async () => {
     if (!brainyInstance) {
         brainyInstance = new Brainy();
+        await brainyInstance.init(); // v5.0.1: Initialize brain (VFS auto-initialized here!)
     }
     return brainyInstance;
 };
@@ -38,10 +39,9 @@ export const vfsCommands = {
     async read(path, options) {
         const spinner = ora('Reading file...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
-            const buffer = await vfs.readFile(path, {
+            const brain = await getBrainy(); // v5.0.1: Await async getBrainy
+            // v5.0.1: VFS auto-initialized, no need for vfs.init()
+            const buffer = await brain.vfs.readFile(path, {
                 encoding: options.encoding
             });
             spinner.succeed('File read successfully');
@@ -70,9 +70,7 @@ export const vfsCommands = {
     async write(path, options) {
         const spinner = ora('Writing file...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
+            const brain = await getBrainy();
             let data;
             if (options.file) {
                 // Read from local file
@@ -85,7 +83,7 @@ export const vfsCommands = {
                 spinner.fail('Must provide --content or --file');
                 process.exit(1);
             }
-            await vfs.writeFile(path, data, {
+            await brain.vfs.writeFile(path, data, {
                 encoding: options.encoding
             });
             spinner.succeed('File written successfully');
@@ -109,10 +107,8 @@ export const vfsCommands = {
     async ls(path, options) {
         const spinner = ora('Listing directory...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
-            const entries = await vfs.readdir(path, { withFileTypes: true });
+            const brain = await getBrainy();
+            const entries = await brain.vfs.readdir(path, { withFileTypes: true });
             spinner.succeed(`Found ${Array.isArray(entries) ? entries.length : 0} items`);
             if (!options.json) {
                 if (!Array.isArray(entries) || entries.length === 0) {
@@ -128,7 +124,7 @@ export const vfsCommands = {
                     for (const entry of entries) {
                         if (!options.all && entry.name.startsWith('.'))
                             continue;
-                        const stat = await vfs.stat(`${path}/${entry.name}`);
+                        const stat = await brain.vfs.stat(`${path}/${entry.name}`);
                         table.push([
                             entry.isDirectory() ? chalk.blue('DIR') : 'FILE',
                             entry.isDirectory() ? '-' : formatBytes(stat.size),
@@ -169,10 +165,8 @@ export const vfsCommands = {
     async stat(path, options) {
         const spinner = ora('Getting file stats...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
-            const stats = await vfs.stat(path);
+            const brain = await getBrainy();
+            const stats = await brain.vfs.stat(path);
             spinner.succeed('Stats retrieved');
             if (!options.json) {
                 console.log(chalk.cyan('\nFile Statistics:'));
@@ -199,10 +193,8 @@ export const vfsCommands = {
     async mkdir(path, options) {
         const spinner = ora('Creating directory...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
-            await vfs.mkdir(path, { recursive: options.parents });
+            const brain = await getBrainy();
+            await brain.vfs.mkdir(path, { recursive: options.parents });
             spinner.succeed('Directory created');
             if (!options.json) {
                 console.log(chalk.green(`✓ Created: ${path}`));
@@ -223,15 +215,13 @@ export const vfsCommands = {
     async rm(path, options) {
         const spinner = ora('Removing...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
-            const stats = await vfs.stat(path);
+            const brain = await getBrainy();
+            const stats = await brain.vfs.stat(path);
             if (stats.isDirectory()) {
-                await vfs.rmdir(path, { recursive: options.recursive });
+                await brain.vfs.rmdir(path, { recursive: options.recursive });
             }
             else {
-                await vfs.unlink(path);
+                await brain.vfs.unlink(path);
             }
             spinner.succeed('Removed successfully');
             if (!options.json) {
@@ -255,10 +245,8 @@ export const vfsCommands = {
     async search(query, options) {
         const spinner = ora('Searching files...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
-            const results = await vfs.search(query, {
+            const brain = await getBrainy();
+            const results = await brain.vfs.search(query, {
                 path: options.path,
                 limit: options.limit ? parseInt(options.limit) : 10
             });
@@ -297,10 +285,8 @@ export const vfsCommands = {
     async similar(path, options) {
         const spinner = ora('Finding similar files...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
-            const results = await vfs.findSimilar(path, {
+            const brain = await getBrainy();
+            const results = await brain.vfs.findSimilar(path, {
                 limit: options.limit ? parseInt(options.limit) : 10,
                 threshold: options.threshold ? parseFloat(options.threshold) : 0.7
             });
@@ -336,10 +322,8 @@ export const vfsCommands = {
     async tree(path, options) {
         const spinner = ora('Building tree...').start();
         try {
-            const brain = getBrainy();
-            const vfs = brain.vfs();
-            await vfs.init();
-            const tree = await vfs.getTreeStructure(path, {
+            const brain = await getBrainy();
+            const tree = await brain.vfs.getTreeStructure(path, {
                 maxDepth: options.depth ? parseInt(options.depth) : 3
             });
             spinner.succeed('Tree built');

package/dist/import/ImportHistory.js

@@ -23,7 +23,7 @@ export class ImportHistory {
      */
     async init() {
         try {
-            const vfs = this.brain.vfs();
+            const vfs = this.brain.vfs;
             await vfs.init();
             // Try to load existing history
             const content = await vfs.readFile(this.historyFile);
@@ -102,7 +102,7 @@ export class ImportHistory {
         }
         // Delete VFS files
         try {
-            const vfs = this.brain.vfs();
+            const vfs = this.brain.vfs;
             await vfs.init();
             for (const vfsPath of entry.vfsPaths) {
                 try {
@@ -160,7 +160,7 @@ export class ImportHistory {
      */
     async persist() {
         try {
-            const vfs = this.brain.vfs();
+            const vfs = this.brain.vfs;
             await vfs.init();
             // Ensure directory exists
             const dir = this.historyFile.substring(0, this.historyFile.lastIndexOf('/'));

package/dist/importers/VFSStructureGenerator.d.ts

@@ -65,7 +65,7 @@ export declare class VFSStructureGenerator {
      * Initialize the generator
      *
      * CRITICAL: Gets brain's VFS instance and initializes it if needed.
-     * This ensures that after import, brain.vfs() returns an initialized instance.
+     * This ensures that after import, brain.vfs returns an initialized instance.
      */
     init(): Promise<void>;
     /**

package/dist/importers/VFSStructureGenerator.js

@@ -15,7 +15,7 @@ import { NounType } from '../types/graphTypes.js';
 export class VFSStructureGenerator {
     constructor(brain) {
         this.brain = brain;
-        // CRITICAL FIX: Use brain.vfs() instead of creating separate instance
+        // CRITICAL FIX: Use brain.vfs instead of creating separate instance
         // This ensures VFSStructureGenerator and user code share the same VFS instance
         // Before: Created separate instance that wasn't accessible to users
         // After: Uses brain's cached instance, making VFS queryable after import
@@ -24,11 +24,11 @@ export class VFSStructureGenerator {
      * Initialize the generator
      *
      * CRITICAL: Gets brain's VFS instance and initializes it if needed.
-     * This ensures that after import, brain.vfs() returns an initialized instance.
+     * This ensures that after import, brain.vfs returns an initialized instance.
      */
     async init() {
         // Get brain's cached VFS instance (creates if doesn't exist)
-        this.vfs = this.brain.vfs();
+        this.vfs = this.brain.vfs;
         // CRITICAL FIX (v4.10.2): Always call vfs.init() explicitly
         // The previous code tried to check if initialized via stat('/') but this was unreliable
         // vfs.init() is idempotent, so calling it multiple times is safe

package/dist/storage/adapters/memoryStorage.d.ts

@@ -37,11 +37,13 @@ export declare class MemoryStorage extends BaseStorage {
     init(): Promise<void>;
     /**
      * Save a noun to storage (v4.0.0: pure vector only, no metadata)
+     * v5.0.1: COW-aware - uses branch-prefixed paths for fork isolation
      */
     protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
     /**
      * Get a noun from storage (v4.0.0: returns pure vector only)
      * Base class handles combining with metadata
+     * v5.0.1: COW-aware - reads from branch-prefixed paths with inheritance
      */
     protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
     /**
@@ -90,15 +92,18 @@ export declare class MemoryStorage extends BaseStorage {
     protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
     /**
      * Delete a noun from storage (v4.0.0)
+     * v5.0.1: COW-aware - deletes from branch-prefixed paths
      */
     protected deleteNoun_internal(id: string): Promise<void>;
     /**
      * Save a verb to storage (v4.0.0: pure vector + core fields, no metadata)
+     * v5.0.1: COW-aware - uses branch-prefixed paths for fork isolation
      */
     protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
     /**
      * Get a verb from storage (v4.0.0: returns pure vector + core fields)
      * Base class handles combining with metadata
+     * v5.0.1: COW-aware - reads from branch-prefixed paths with inheritance
      */
     protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
     /**
@@ -143,6 +148,7 @@ export declare class MemoryStorage extends BaseStorage {
     protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Delete a verb from storage
+     * v5.0.1: COW-aware - deletes from branch-prefixed paths
      */
     protected deleteVerb_internal(id: string): Promise<void>;
     /**