@soulcraft/brainy 3.14.2 → 3.16.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.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/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({
@@ -247,6 +268,20 @@ export class VirtualFileSystem {
                 data: entityData,
                 metadata
             });
+            // Ensure Contains relationship exists (fix for missing relationships)
+            const existingRelations = await this.brain.getRelations({
+                from: parentId,
+                to: existingId,
+                type: VerbType.Contains
+            });
+            // Create relationship if it doesn't exist
+            if (existingRelations.length === 0) {
+                await this.brain.relate({
+                    from: parentId,
+                    to: existingId,
+                    type: VerbType.Contains
+                });
+            }
         }
         else {
             // Create new file entity
@@ -736,9 +771,13 @@ export class VirtualFileSystem {
             return entityId;
         }
         catch (err) {
-            // Directory doesn't exist, create it recursively
-            await this.mkdir(path, { recursive: true });
-            return await this.pathResolver.resolve(path);
+            // Only create directory if it doesn't exist (ENOENT error)
+            if (err instanceof VFSError && err.code === VFSErrorCode.ENOENT) {
+                await this.mkdir(path, { recursive: true });
+                return await this.pathResolver.resolve(path);
+            }
+            // Re-throw other errors (like ENOTDIR)
+            throw err;
         }
     }
     async getEntityById(id) {
@@ -746,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) {
@@ -2016,7 +2090,13 @@ export class VirtualFileSystem {
             path = `${from}/${path}`;
         }
         // Normalize path
-        return path.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+        const normalizedPath = path.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+        // Special case for root
+        if (normalizedPath === '/') {
+            return this.rootEntityId;
+        }
+        // Resolve the path to an entity ID
+        return await this.pathResolver.resolve(normalizedPath);
     }
 }
 //# sourceMappingURL=VirtualFileSystem.js.map

package/package.json

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