@soulcraft/brainy 3.15.0 → 3.17.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.
 
+## [3.17.0](https://github.com/soulcraftlabs/brainy/compare/v3.16.0...v3.17.0) (2025-09-27)
+
+## [3.15.0](https://github.com/soulcraftlabs/brainy/compare/v3.14.2...v3.15.0) (2025-09-26)
+
+### Bug Fixes
+
+* **vfs**: Ensure Contains relationships are maintained when updating files
+* **vfs**: Fix root directory metadata handling to prevent "Not a directory" errors
+* **vfs**: Add entity metadata compatibility layer for proper VFS operations
+* **vfs**: Fix resolvePath() to return entity IDs instead of path strings
+* **vfs**: Improve error handling in ensureDirectory() method
+
+### Features
+
+* **vfs**: Add comprehensive tests for Contains relationship integrity
+* **vfs**: Ensure all VFS entities use standard Brainy NounType and VerbType enums
+* **vfs**: Add metadata validation and repair for existing entities
+
 ## [3.0.1](https://github.com/soulcraftlabs/brainy/compare/v2.14.3...v3.0.1) (2025-09-15)
 
 **Brainy 3.0 Production Release** - World's first Triple Intelligence™ database unifying vector, graph, and document search

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

@@ -288,6 +288,21 @@ export declare class FileSystemStorage extends BaseStorage {
      * Consistent across all entity types
      */
     private getShardedPath;
+    /**
+     * Get all JSON files from a sharded directory structure
+     * Properly traverses sharded subdirectories based on current sharding depth
+     */
+    private getAllShardedFiles;
+    /**
+     * Production-scale streaming pagination for very large datasets
+     * Avoids loading all filenames into memory
+     */
+    private getVerbsWithPaginationStreaming;
+    /**
+     * Stream through sharded files without loading all names into memory
+     * Production-scale implementation for millions of files
+     */
+    private streamShardedFiles;
     /**
      * Check if a file exists (handles both sharded and non-sharded)
      */

package/dist/storage/adapters/fileSystemStorage.js

@@ -39,7 +39,7 @@ export class FileSystemStorage extends BaseStorage {
         super();
         // Intelligent sharding configuration
         this.shardingDepth = 2; // 0=flat, 1=ab/, 2=ab/cd/
-        this.SHARDING_THRESHOLD = 1000; // Enable deep sharding at 1k files
+        this.SHARDING_THRESHOLD = 100; // Enable deep sharding at 100 files for optimal performance
         this.useDualWrite = true; // Write to both locations during migration
         this.activeLocks = new Set();
         this.lockTimers = new Map(); // Track timers for cleanup
@@ -182,7 +182,8 @@ export class FileSystemStorage extends BaseStorage {
                 id: parsedNode.id,
                 vector: parsedNode.vector,
                 connections,
-                level: parsedNode.level || 0
+                level: parsedNode.level || 0,
+                metadata: parsedNode.metadata
             };
         }
         catch (error) {
@@ -303,6 +304,8 @@ export class FileSystemStorage extends BaseStorage {
      */
     async saveEdge(edge) {
         await this.ensureInitialized();
+        // Check if this is a new edge to update counts
+        const isNew = !(await this.fileExists(this.getVerbPath(edge.id)));
         // Convert connections Map to a serializable format
         const serializableEdge = {
             ...edge,
@@ -311,6 +314,14 @@ export class FileSystemStorage extends BaseStorage {
         const filePath = this.getVerbPath(edge.id);
         await this.ensureDirectoryExists(path.dirname(filePath));
         await fs.promises.writeFile(filePath, JSON.stringify(serializableEdge, null, 2));
+        // Update verb count for new edges (production-scale optimizations)
+        if (isNew) {
+            this.totalVerbCount++;
+            // Persist counts periodically (every 10 operations for efficiency)
+            if (this.totalVerbCount % 10 === 0) {
+                this.persistCounts(); // Async persist, don't await
+            }
+        }
     }
     /**
      * Get an edge from storage
@@ -502,8 +513,22 @@ export class FileSystemStorage extends BaseStorage {
      */
     async saveVerbMetadata_internal(id, metadata) {
         await this.ensureInitialized();
+        console.log(`[DEBUG] Saving verb metadata for ${id} to: ${this.verbMetadataDir}`);
         const filePath = path.join(this.verbMetadataDir, `${id}.json`);
-        await fs.promises.writeFile(filePath, JSON.stringify(metadata, null, 2));
+        console.log(`[DEBUG] Full file path: ${filePath}`);
+        try {
+            await this.ensureDirectoryExists(path.dirname(filePath));
+            console.log(`[DEBUG] Directory ensured: ${path.dirname(filePath)}`);
+            await fs.promises.writeFile(filePath, JSON.stringify(metadata, null, 2));
+            console.log(`[DEBUG] File written successfully: ${filePath}`);
+            // Verify the file was actually written
+            const exists = await fs.promises.access(filePath).then(() => true).catch(() => false);
+            console.log(`[DEBUG] File exists after write: ${exists}`);
+        }
+        catch (error) {
+            console.error(`[DEBUG] Error saving verb metadata:`, error);
+            throw error;
+        }
     }
     /**
      * Get verb metadata from storage
@@ -531,9 +556,8 @@ export class FileSystemStorage extends BaseStorage {
         const limit = options.limit || 100;
         const cursor = options.cursor;
         try {
-            // Get all noun files
-            const files = await fs.promises.readdir(this.nounsDir);
-            const nounFiles = files.filter((f) => f.endsWith('.json'));
+            // Get all noun files (handles sharding properly)
+            const nounFiles = await this.getAllShardedFiles(this.nounsDir);
             // Sort for consistent pagination
             nounFiles.sort();
             // Find starting position - prioritize offset for O(1) operation
@@ -562,7 +586,8 @@ export class FileSystemStorage extends BaseStorage {
             // Second pass: load the current page
             for (const file of pageFiles) {
                 try {
-                    const data = await fs.promises.readFile(path.join(this.nounsDir, file), 'utf-8');
+                    const id = file.replace('.json', '');
+                    const data = await fs.promises.readFile(this.getNodePath(id), 'utf-8');
                     const noun = JSON.parse(data);
                     // Apply filter if provided
                     if (options.filter) {
@@ -872,29 +897,30 @@ export class FileSystemStorage extends BaseStorage {
         const limit = options.limit || 100;
         const startIndex = options.cursor ? parseInt(options.cursor, 10) : 0;
         try {
-            // List all verb files in the verbs directory
-            // Note: For very large directories (millions of files), this could be memory-intensive
-            // Future optimization: Use fs.opendir() for streaming directory reads
-            const files = await fs.promises.readdir(this.verbsDir);
-            const verbFiles = files.filter((f) => f.endsWith('.json'));
-            // Sort files for consistent ordering
-            verbFiles.sort();
-            // Calculate pagination
-            const totalCount = verbFiles.length;
+            // Production-scale optimization: Use persisted count for total instead of scanning
+            const totalCount = this.totalVerbCount || 0;
+            // For large datasets, warn about performance
+            if (totalCount > 1000000) {
+                console.warn(`Very large verb dataset detected (${totalCount} verbs). Performance may be degraded. Consider database storage for optimal performance.`);
+            }
+            // Calculate pagination bounds
             const endIndex = Math.min(startIndex + limit, totalCount);
             const hasMore = endIndex < totalCount;
-            // Safety check for large datasets
-            if (totalCount > 100000) {
-                console.warn(`Large verb dataset detected (${totalCount} verbs). Consider using a database for better performance.`);
+            // For production-scale datasets, use streaming approach
+            if (totalCount > 50000) {
+                return await this.getVerbsWithPaginationStreaming(options, startIndex, limit);
             }
+            // For smaller datasets, use the current approach (with optimizations)
+            const verbFiles = await this.getAllShardedFiles(this.verbsDir);
+            verbFiles.sort(); // This is still acceptable for <50k files
             // Load the requested page of verbs
             const verbs = [];
             for (let i = startIndex; i < endIndex; i++) {
                 const file = verbFiles[i];
                 const id = file.replace('.json', '');
                 try {
-                    // Read the verb data (HNSWVerb stored as edge)
-                    const filePath = path.join(this.verbsDir, file);
+                    // Read the verb data (HNSWVerb stored as edge) - use sharded path
+                    const filePath = this.getVerbPath(id);
                     const data = await fs.promises.readFile(filePath, 'utf-8');
                     const edge = JSON.parse(data);
                     // Get metadata which contains the actual verb information
@@ -1336,20 +1362,19 @@ export class FileSystemStorage extends BaseStorage {
      */
     async initializeCountsFromDisk() {
         try {
-            // Count nouns
-            const nounFiles = await fs.promises.readdir(this.nounsDir);
-            const validNounFiles = nounFiles.filter((f) => f.endsWith('.json'));
+            // Count nouns (handles sharding properly)
+            const validNounFiles = await this.getAllShardedFiles(this.nounsDir);
             this.totalNounCount = validNounFiles.length;
-            // Count verbs
-            const verbFiles = await fs.promises.readdir(this.verbsDir);
-            const validVerbFiles = verbFiles.filter((f) => f.endsWith('.json'));
+            // Count verbs (handles sharding properly)
+            const validVerbFiles = await this.getAllShardedFiles(this.verbsDir);
             this.totalVerbCount = validVerbFiles.length;
             // Sample some files to get type distribution (don't read all)
             const sampleSize = Math.min(100, validNounFiles.length);
             for (let i = 0; i < sampleSize; i++) {
                 try {
                     const file = validNounFiles[i];
-                    const data = await fs.promises.readFile(path.join(this.nounsDir, file), 'utf-8');
+                    const id = file.replace('.json', '');
+                    const data = await fs.promises.readFile(this.getNodePath(id), 'utf-8');
                     const noun = JSON.parse(data);
                     const type = noun.metadata?.type || noun.metadata?.nounType || 'default';
                     this.entityCounts.set(type, (this.entityCounts.get(type) || 0) + 1);
@@ -1449,6 +1474,327 @@ export class FileSystemStorage extends BaseStorage {
                 return path.join(baseDir, shard1Deep, shard2Deep, `${id}.json`);
         }
     }
+    /**
+     * Get all JSON files from a sharded directory structure
+     * Properly traverses sharded subdirectories based on current sharding depth
+     */
+    async getAllShardedFiles(baseDir) {
+        const allFiles = [];
+        const depth = this.cachedShardingDepth ?? this.getOptimalShardingDepth();
+        try {
+            switch (depth) {
+                case 0:
+                    // Flat structure: read directly from baseDir
+                    const flatFiles = await fs.promises.readdir(baseDir);
+                    for (const file of flatFiles) {
+                        if (file.endsWith('.json')) {
+                            allFiles.push(file);
+                        }
+                    }
+                    break;
+                case 1:
+                    // Single-level sharding: baseDir/ab/
+                    try {
+                        const shardDirs = await fs.promises.readdir(baseDir);
+                        for (const shardDir of shardDirs) {
+                            const shardPath = path.join(baseDir, shardDir);
+                            try {
+                                const stat = await fs.promises.stat(shardPath);
+                                if (stat.isDirectory()) {
+                                    const shardFiles = await fs.promises.readdir(shardPath);
+                                    for (const file of shardFiles) {
+                                        if (file.endsWith('.json')) {
+                                            allFiles.push(file);
+                                        }
+                                    }
+                                }
+                            }
+                            catch (shardError) {
+                                // Skip inaccessible shard directories
+                                continue;
+                            }
+                        }
+                    }
+                    catch (baseError) {
+                        // If baseDir doesn't exist, return empty array
+                        if (baseError.code === 'ENOENT') {
+                            return [];
+                        }
+                        throw baseError;
+                    }
+                    break;
+                case 2:
+                default:
+                    // Deep sharding: baseDir/ab/cd/
+                    try {
+                        const level1Dirs = await fs.promises.readdir(baseDir);
+                        for (const level1Dir of level1Dirs) {
+                            const level1Path = path.join(baseDir, level1Dir);
+                            try {
+                                const level1Stat = await fs.promises.stat(level1Path);
+                                if (level1Stat.isDirectory()) {
+                                    const level2Dirs = await fs.promises.readdir(level1Path);
+                                    for (const level2Dir of level2Dirs) {
+                                        const level2Path = path.join(level1Path, level2Dir);
+                                        try {
+                                            const level2Stat = await fs.promises.stat(level2Path);
+                                            if (level2Stat.isDirectory()) {
+                                                const shardFiles = await fs.promises.readdir(level2Path);
+                                                for (const file of shardFiles) {
+                                                    if (file.endsWith('.json')) {
+                                                        allFiles.push(file);
+                                                    }
+                                                }
+                                            }
+                                        }
+                                        catch (level2Error) {
+                                            // Skip inaccessible level2 directories
+                                            continue;
+                                        }
+                                    }
+                                }
+                            }
+                            catch (level1Error) {
+                                // Skip inaccessible level1 directories
+                                continue;
+                            }
+                        }
+                    }
+                    catch (baseError) {
+                        // If baseDir doesn't exist, return empty array
+                        if (baseError.code === 'ENOENT') {
+                            return [];
+                        }
+                        throw baseError;
+                    }
+                    break;
+            }
+            // Sort for consistent ordering
+            allFiles.sort();
+            return allFiles;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Directory doesn't exist yet
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Production-scale streaming pagination for very large datasets
+     * Avoids loading all filenames into memory
+     */
+    async getVerbsWithPaginationStreaming(options, startIndex, limit) {
+        const verbs = [];
+        const totalCount = this.totalVerbCount || 0;
+        let processedCount = 0;
+        let skippedCount = 0;
+        let resultCount = 0;
+        const depth = this.cachedShardingDepth ?? this.getOptimalShardingDepth();
+        try {
+            // Stream through sharded directories efficiently
+            const hasMore = await this.streamShardedFiles(this.verbsDir, depth, async (filename, filePath) => {
+                // Skip files until we reach start index
+                if (skippedCount < startIndex) {
+                    skippedCount++;
+                    return true; // continue
+                }
+                // Stop if we have enough results
+                if (resultCount >= limit) {
+                    return false; // stop streaming
+                }
+                try {
+                    const id = filename.replace('.json', '');
+                    // Read verb data and metadata
+                    const data = await fs.promises.readFile(filePath, 'utf-8');
+                    const edge = JSON.parse(data);
+                    const metadata = await this.getVerbMetadata(id);
+                    if (!metadata) {
+                        processedCount++;
+                        return true; // continue, skip this verb
+                    }
+                    // Reconstruct GraphVerb
+                    const verb = {
+                        id: edge.id,
+                        vector: edge.vector,
+                        connections: edge.connections || new Map(),
+                        sourceId: metadata.sourceId || metadata.source,
+                        targetId: metadata.targetId || metadata.target,
+                        source: metadata.source || metadata.sourceId,
+                        target: metadata.target || metadata.targetId,
+                        verb: metadata.verb || metadata.type,
+                        type: metadata.type || metadata.verb,
+                        weight: metadata.weight,
+                        metadata: metadata.metadata || metadata,
+                        data: metadata.data,
+                        createdAt: metadata.createdAt,
+                        updatedAt: metadata.updatedAt,
+                        createdBy: metadata.createdBy,
+                        embedding: metadata.embedding || edge.vector
+                    };
+                    // Apply filters
+                    if (options.filter) {
+                        const filter = options.filter;
+                        if (filter.verbType) {
+                            const types = Array.isArray(filter.verbType) ? filter.verbType : [filter.verbType];
+                            const verbType = verb.type || verb.verb;
+                            if (verbType && !types.includes(verbType))
+                                return true; // continue
+                        }
+                        if (filter.sourceId) {
+                            const sources = Array.isArray(filter.sourceId) ? filter.sourceId : [filter.sourceId];
+                            const sourceId = verb.sourceId || verb.source;
+                            if (!sourceId || !sources.includes(sourceId))
+                                return true; // continue
+                        }
+                        if (filter.targetId) {
+                            const targets = Array.isArray(filter.targetId) ? filter.targetId : [filter.targetId];
+                            const targetId = verb.targetId || verb.target;
+                            if (!targetId || !targets.includes(targetId))
+                                return true; // continue
+                        }
+                    }
+                    verbs.push(verb);
+                    resultCount++;
+                    processedCount++;
+                    return true; // continue
+                }
+                catch (error) {
+                    console.warn(`Failed to read verb from ${filePath}:`, error);
+                    processedCount++;
+                    return true; // continue
+                }
+            });
+            const finalHasMore = (startIndex + resultCount) < totalCount;
+            return {
+                items: verbs,
+                totalCount,
+                hasMore: finalHasMore,
+                nextCursor: finalHasMore ? String(startIndex + resultCount) : undefined
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return {
+                    items: [],
+                    totalCount: 0,
+                    hasMore: false
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Stream through sharded files without loading all names into memory
+     * Production-scale implementation for millions of files
+     */
+    async streamShardedFiles(baseDir, depth, processor) {
+        let hasMore = true;
+        switch (depth) {
+            case 0:
+                // Flat structure
+                try {
+                    const files = await fs.promises.readdir(baseDir);
+                    const sortedFiles = files.filter((f) => f.endsWith('.json')).sort();
+                    for (const file of sortedFiles) {
+                        const shouldContinue = await processor(file, path.join(baseDir, file));
+                        if (!shouldContinue) {
+                            hasMore = false;
+                            break;
+                        }
+                    }
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        hasMore = false;
+                }
+                break;
+            case 1:
+                // Single-level sharding: ab/
+                try {
+                    const shardDirs = await fs.promises.readdir(baseDir);
+                    const sortedShardDirs = shardDirs.sort();
+                    for (const shardDir of sortedShardDirs) {
+                        const shardPath = path.join(baseDir, shardDir);
+                        try {
+                            const stat = await fs.promises.stat(shardPath);
+                            if (stat.isDirectory()) {
+                                const files = await fs.promises.readdir(shardPath);
+                                const sortedFiles = files.filter((f) => f.endsWith('.json')).sort();
+                                for (const file of sortedFiles) {
+                                    const shouldContinue = await processor(file, path.join(shardPath, file));
+                                    if (!shouldContinue) {
+                                        hasMore = false;
+                                        break;
+                                    }
+                                }
+                                if (!hasMore)
+                                    break;
+                            }
+                        }
+                        catch (shardError) {
+                            continue; // Skip inaccessible shard directories
+                        }
+                    }
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        hasMore = false;
+                }
+                break;
+            case 2:
+            default:
+                // Deep sharding: ab/cd/
+                try {
+                    const level1Dirs = await fs.promises.readdir(baseDir);
+                    const sortedLevel1Dirs = level1Dirs.sort();
+                    for (const level1Dir of sortedLevel1Dirs) {
+                        const level1Path = path.join(baseDir, level1Dir);
+                        try {
+                            const level1Stat = await fs.promises.stat(level1Path);
+                            if (level1Stat.isDirectory()) {
+                                const level2Dirs = await fs.promises.readdir(level1Path);
+                                const sortedLevel2Dirs = level2Dirs.sort();
+                                for (const level2Dir of sortedLevel2Dirs) {
+                                    const level2Path = path.join(level1Path, level2Dir);
+                                    try {
+                                        const level2Stat = await fs.promises.stat(level2Path);
+                                        if (level2Stat.isDirectory()) {
+                                            const files = await fs.promises.readdir(level2Path);
+                                            const sortedFiles = files.filter((f) => f.endsWith('.json')).sort();
+                                            for (const file of sortedFiles) {
+                                                const shouldContinue = await processor(file, path.join(level2Path, file));
+                                                if (!shouldContinue) {
+                                                    hasMore = false;
+                                                    break;
+                                                }
+                                            }
+                                            if (!hasMore)
+                                                break;
+                                        }
+                                    }
+                                    catch (level2Error) {
+                                        continue; // Skip inaccessible level2 directories
+                                    }
+                                }
+                                if (!hasMore)
+                                    break;
+                            }
+                        }
+                        catch (level1Error) {
+                            continue; // Skip inaccessible level1 directories
+                        }
+                    }
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        hasMore = false;
+                }
+                break;
+        }
+        return hasMore;
+    }
     /**
      * Check if a file exists (handles both sharded and non-sharded)
      */

package/dist/vfs/VFSHealthCheck.d.ts

@@ -0,0 +1,78 @@
+import { Brainy } from '../brainy.js';
+import { VirtualFileSystem } from './VirtualFileSystem.js';
+export interface VFSHealthReport {
+    healthy: boolean;
+    rootDirectory: {
+        exists: boolean;
+        isDirectory: boolean;
+        accessible: boolean;
+    };
+    containsRelationships: {
+        intact: boolean;
+        orphanedFiles: string[];
+        missingRelationships: number;
+    };
+    metadataIntegrity: {
+        valid: boolean;
+        malformedEntities: string[];
+    };
+    performance: {
+        readLatency: number;
+        writeLatency: number;
+        cacheHitRate: number;
+    };
+    recommendations: string[];
+}
+/**
+ * VFS Health Check and Recovery System
+ *
+ * Provides automated health checks, diagnostics, and recovery
+ * procedures for the Virtual File System.
+ */
+export declare class VFSHealthCheck {
+    private vfs;
+    private brain;
+    private logger;
+    constructor(vfs: VirtualFileSystem, brain: Brainy);
+    /**
+     * Perform comprehensive health check
+     */
+    checkHealth(): Promise<VFSHealthReport>;
+    /**
+     * Check root directory health
+     */
+    private checkRootDirectory;
+    /**
+     * Check Contains relationships integrity
+     */
+    private checkContainsRelationships;
+    /**
+     * Check metadata integrity
+     */
+    private checkMetadataIntegrity;
+    /**
+     * Check performance metrics
+     */
+    private checkPerformance;
+    /**
+     * Generate recommendations based on health report
+     */
+    private generateRecommendations;
+    /**
+     * Attempt to recover VFS to healthy state
+     */
+    recover(): Promise<void>;
+    /**
+     * Recover root directory
+     */
+    private recoverRootDirectory;
+    /**
+     * Repair orphaned files by creating missing Contains relationships
+     */
+    private repairOrphanedFiles;
+    /**
+     * Fix malformed metadata
+     */
+    private fixMalformedMetadata;
+    private getParentPath;
+}

package/dist/vfs/VFSHealthCheck.js

@@ -0,0 +1,299 @@
+import { VFSError, VFSErrorCode } from './types.js';
+import { Logger } from '../utils/logger.js';
+/**
+ * VFS Health Check and Recovery System
+ *
+ * Provides automated health checks, diagnostics, and recovery
+ * procedures for the Virtual File System.
+ */
+export class VFSHealthCheck {
+    constructor(vfs, brain) {
+        this.vfs = vfs;
+        this.brain = brain;
+        this.logger = new Logger('VFSHealthCheck');
+    }
+    /**
+     * Perform comprehensive health check
+     */
+    async checkHealth() {
+        const report = {
+            healthy: true,
+            rootDirectory: {
+                exists: false,
+                isDirectory: false,
+                accessible: false
+            },
+            containsRelationships: {
+                intact: true,
+                orphanedFiles: [],
+                missingRelationships: 0
+            },
+            metadataIntegrity: {
+                valid: true,
+                malformedEntities: []
+            },
+            performance: {
+                readLatency: 0,
+                writeLatency: 0,
+                cacheHitRate: 0
+            },
+            recommendations: []
+        };
+        // Check root directory
+        await this.checkRootDirectory(report);
+        // Check Contains relationships
+        await this.checkContainsRelationships(report);
+        // Check metadata integrity
+        await this.checkMetadataIntegrity(report);
+        // Check performance metrics
+        await this.checkPerformance(report);
+        // Generate recommendations
+        this.generateRecommendations(report);
+        report.healthy =
+            report.rootDirectory.exists &&
+                report.rootDirectory.isDirectory &&
+                report.rootDirectory.accessible &&
+                report.containsRelationships.intact &&
+                report.metadataIntegrity.valid;
+        return report;
+    }
+    /**
+     * Check root directory health
+     */
+    async checkRootDirectory(report) {
+        try {
+            // Check if root exists
+            const rootId = await this.vfs.resolvePath('/');
+            report.rootDirectory.exists = !!rootId;
+            if (rootId) {
+                // Get root entity
+                const rootEntity = await this.brain.get(rootId);
+                // Check if it's a directory
+                report.rootDirectory.isDirectory =
+                    rootEntity?.metadata?.vfsType === 'directory' ||
+                        rootEntity?.vfsType === 'directory';
+                // Check if it's accessible
+                try {
+                    await this.vfs.readdir('/');
+                    report.rootDirectory.accessible = true;
+                }
+                catch {
+                    report.rootDirectory.accessible = false;
+                }
+            }
+        }
+        catch (error) {
+            this.logger.error('Root directory check failed:', error);
+            report.rootDirectory.exists = false;
+        }
+    }
+    /**
+     * Check Contains relationships integrity
+     */
+    async checkContainsRelationships(report) {
+        try {
+            // Get all file entities
+            const files = await this.brain.find({
+                metadata: { vfsType: 'file' },
+                limit: 1000
+            });
+            for (const file of files) {
+                // Check if file has a Contains relationship with its parent
+                const parentPath = this.getParentPath(file.metadata.path);
+                if (parentPath) {
+                    try {
+                        const parentId = await this.vfs.resolvePath(parentPath);
+                        const relations = await this.brain.getRelations({
+                            from: parentId,
+                            to: file.id,
+                            type: 'Contains'
+                        });
+                        if (relations.length === 0) {
+                            report.containsRelationships.orphanedFiles.push(file.metadata.path);
+                            report.containsRelationships.missingRelationships++;
+                            report.containsRelationships.intact = false;
+                        }
+                    }
+                    catch {
+                        // Parent doesn't exist
+                        report.containsRelationships.orphanedFiles.push(file.metadata.path);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            this.logger.error('Contains relationships check failed:', error);
+            report.containsRelationships.intact = false;
+        }
+    }
+    /**
+     * Check metadata integrity
+     */
+    async checkMetadataIntegrity(report) {
+        try {
+            // Get all VFS entities
+            const entities = await this.brain.find({
+                metadata: { path: { $exists: true } },
+                limit: 1000
+            });
+            for (const entity of entities) {
+                // Check required metadata fields
+                if (!entity.metadata?.vfsType ||
+                    !entity.metadata?.path ||
+                    entity.metadata.vfsType !== 'file' && entity.metadata.vfsType !== 'directory') {
+                    report.metadataIntegrity.malformedEntities.push(entity.id);
+                    report.metadataIntegrity.valid = false;
+                }
+            }
+        }
+        catch (error) {
+            this.logger.error('Metadata integrity check failed:', error);
+            report.metadataIntegrity.valid = false;
+        }
+    }
+    /**
+     * Check performance metrics
+     */
+    async checkPerformance(report) {
+        try {
+            // Test read performance
+            const readStart = Date.now();
+            await this.vfs.readdir('/');
+            report.performance.readLatency = Date.now() - readStart;
+            // Test write performance
+            const writeStart = Date.now();
+            const testPath = '/.health-check-' + Date.now();
+            await this.vfs.writeFile(testPath, 'test');
+            report.performance.writeLatency = Date.now() - writeStart;
+            // Clean up test file
+            await this.vfs.unlink(testPath);
+            // Calculate cache hit rate (if available)
+            const stats = await this.brain.getStatistics();
+            if (stats?.cache) {
+                report.performance.cacheHitRate = stats.cache.hitRate || 0;
+            }
+        }
+        catch (error) {
+            this.logger.error('Performance check failed:', error);
+        }
+    }
+    /**
+     * Generate recommendations based on health report
+     */
+    generateRecommendations(report) {
+        if (!report.rootDirectory.exists || !report.rootDirectory.isDirectory) {
+            report.recommendations.push('Run VFS recovery to rebuild root directory');
+        }
+        if (report.containsRelationships.orphanedFiles.length > 0) {
+            report.recommendations.push(`Repair ${report.containsRelationships.orphanedFiles.length} orphaned files`);
+        }
+        if (report.metadataIntegrity.malformedEntities.length > 0) {
+            report.recommendations.push(`Fix metadata for ${report.metadataIntegrity.malformedEntities.length} malformed entities`);
+        }
+        if (report.performance.readLatency > 100) {
+            report.recommendations.push('Consider enabling caching or optimizing indexes');
+        }
+        if (report.performance.cacheHitRate < 0.5) {
+            report.recommendations.push('Increase cache size or TTL for better performance');
+        }
+    }
+    /**
+     * Attempt to recover VFS to healthy state
+     */
+    async recover() {
+        this.logger.info('Starting VFS recovery...');
+        // 1. Ensure root directory exists and is properly configured
+        await this.recoverRootDirectory();
+        // 2. Repair orphaned files
+        await this.repairOrphanedFiles();
+        // 3. Fix malformed metadata
+        await this.fixMalformedMetadata();
+        this.logger.info('VFS recovery completed');
+    }
+    /**
+     * Recover root directory
+     */
+    async recoverRootDirectory() {
+        try {
+            // Force recreation of root directory with proper metadata
+            const rootId = await this.vfs['initializeRoot']();
+            // Verify root is now accessible
+            await this.vfs.readdir('/');
+            this.logger.info('Root directory recovered successfully');
+        }
+        catch (error) {
+            this.logger.error('Failed to recover root directory:', error);
+            throw new VFSError(VFSErrorCode.EIO, 'Failed to recover root directory', '/', 'recover');
+        }
+    }
+    /**
+     * Repair orphaned files by creating missing Contains relationships
+     */
+    async repairOrphanedFiles() {
+        const report = await this.checkHealth();
+        for (const filePath of report.containsRelationships.orphanedFiles) {
+            try {
+                const fileId = await this.vfs.resolvePath(filePath);
+                const parentPath = this.getParentPath(filePath);
+                if (parentPath) {
+                    // Ensure parent directory exists
+                    await this.vfs.mkdir(parentPath, { recursive: true });
+                    const parentId = await this.vfs.resolvePath(parentPath);
+                    // Create missing Contains relationship
+                    await this.brain.relate({
+                        from: parentId,
+                        to: fileId,
+                        type: 'Contains'
+                    });
+                    this.logger.info(`Repaired orphaned file: ${filePath}`);
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to repair orphaned file ${filePath}:`, error);
+            }
+        }
+    }
+    /**
+     * Fix malformed metadata
+     */
+    async fixMalformedMetadata() {
+        const report = await this.checkHealth();
+        for (const entityId of report.metadataIntegrity.malformedEntities) {
+            try {
+                const entity = await this.brain.get(entityId);
+                if (entity) {
+                    // Reconstruct metadata
+                    const fixedMetadata = {
+                        path: entity.metadata?.path || entity.path || '/',
+                        name: entity.metadata?.name || entity.name || '',
+                        vfsType: entity.metadata?.vfsType || entity.vfsType || 'file',
+                        size: entity.metadata?.size || entity.size || 0,
+                        permissions: entity.metadata?.permissions || 0o644,
+                        owner: entity.metadata?.owner || 'user',
+                        group: entity.metadata?.group || 'users',
+                        accessed: entity.metadata?.accessed || Date.now(),
+                        modified: entity.metadata?.modified || Date.now(),
+                        ...entity.metadata
+                    };
+                    // Update entity with fixed metadata
+                    await this.brain.update({
+                        id: entityId,
+                        metadata: fixedMetadata
+                    });
+                    this.logger.info(`Fixed metadata for entity: ${entityId}`);
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to fix metadata for entity ${entityId}:`, error);
+            }
+        }
+    }
+    getParentPath(path) {
+        const normalized = path.replace(/\/+/g, '/').replace(/\/$/, '');
+        const lastSlash = normalized.lastIndexOf('/');
+        if (lastSlash <= 0)
+            return '/';
+        return normalized.substring(0, lastSlash);
+    }
+}
+//# sourceMappingURL=VFSHealthCheck.js.map

package/dist/vfs/VirtualFileSystem.js

@@ -62,16 +62,37 @@ export class VirtualFileSystem {
      * Create or find the root directory entity
      */
     async initializeRoot() {
-        // Check if root already exists
+        // Check if root already exists - search using where clause
         const existing = await this.brain.find({
             where: {
-                path: '/',
-                vfsType: 'directory'
+                'metadata.path': '/',
+                'metadata.vfsType': 'directory'
             },
             limit: 1
         });
         if (existing.length > 0) {
-            return existing[0].entity.id;
+            const rootEntity = existing[0];
+            // Ensure the root entity has proper metadata structure
+            const entityMetadata = rootEntity.metadata || rootEntity;
+            if (!entityMetadata.vfsType) {
+                // Update the root entity with proper metadata
+                await this.brain.update({
+                    id: rootEntity.id,
+                    metadata: {
+                        path: '/',
+                        name: '',
+                        vfsType: 'directory',
+                        size: 0,
+                        permissions: 0o755,
+                        owner: 'root',
+                        group: 'root',
+                        accessed: Date.now(),
+                        modified: Date.now(),
+                        ...entityMetadata // Preserve any existing metadata
+                    }
+                });
+            }
+            return rootEntity.id;
         }
         // Create root directory
         const root = await this.brain.add({
@@ -764,6 +785,41 @@ export class VirtualFileSystem {
         if (!entity) {
             throw new VFSError(VFSErrorCode.ENOENT, `Entity not found: ${id}`);
         }
+        // Ensure entity has proper VFS metadata structure
+        // Handle both nested and flat metadata structures for compatibility
+        if (!entity.metadata || !entity.metadata.vfsType) {
+            // Check if metadata is at top level (legacy structure)
+            const anyEntity = entity;
+            if (anyEntity.vfsType || anyEntity.path) {
+                entity.metadata = {
+                    path: anyEntity.path || '/',
+                    name: anyEntity.name || '',
+                    vfsType: anyEntity.vfsType || (anyEntity.path === '/' ? 'directory' : 'file'),
+                    size: anyEntity.size || 0,
+                    permissions: anyEntity.permissions || (anyEntity.vfsType === 'directory' ? 0o755 : 0o644),
+                    owner: anyEntity.owner || 'user',
+                    group: anyEntity.group || 'users',
+                    accessed: anyEntity.accessed || Date.now(),
+                    modified: anyEntity.modified || Date.now(),
+                    ...entity.metadata // Preserve any existing nested metadata
+                };
+            }
+            else if (entity.id === this.rootEntityId) {
+                // Special case: ensure root directory always has proper metadata
+                entity.metadata = {
+                    path: '/',
+                    name: '',
+                    vfsType: 'directory',
+                    size: 0,
+                    permissions: 0o755,
+                    owner: 'root',
+                    group: 'root',
+                    accessed: Date.now(),
+                    modified: Date.now(),
+                    ...entity.metadata
+                };
+            }
+        }
         return entity;
     }
     getParentPath(path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.15.0",
+  "version": "3.17.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",