@soulcraft/brainy 3.20.2 → 3.20.3

package/dist/vfs/SemanticVersioning.js

@@ -1,309 +0,0 @@
-/**
- * Semantic Versioning System for VFS
- *
- * Only creates versions when the MEANING of content changes significantly
- * PRODUCTION-READY: Real implementation using embeddings
- */
-import { NounType, VerbType } from '../types/graphTypes.js';
-import { cosineDistance } from '../utils/distance.js';
-import { createHash } from 'crypto';
-import { v4 as uuidv4 } from '../universal/uuid.js';
-import { EntityManager } from './EntityManager.js';
-/**
- * Semantic Versioning System
- *
- * Creates versions only when content meaning changes significantly
- * Uses vector embeddings to detect semantic changes
- */
-export class SemanticVersioning extends EntityManager {
-    constructor(brain, config) {
-        super(brain, 'vfs-version');
-        this.versionCache = new Map();
-        this.config = {
-            threshold: config?.threshold ?? 0.3,
-            maxVersions: config?.maxVersions ?? 10,
-            minInterval: config?.minInterval ?? 60000, // 1 minute
-            sizeChangeThreshold: config?.sizeChangeThreshold ?? 0.5
-        };
-    }
-    /**
-     * Check if content has changed enough to warrant a new version
-     */
-    async shouldVersion(oldContent, newContent) {
-        // Quick hash check - if identical, no version needed
-        const oldHash = this.hashContent(oldContent);
-        const newHash = this.hashContent(newContent);
-        if (oldHash === newHash) {
-            return false;
-        }
-        // Check size change
-        const sizeChange = Math.abs(oldContent.length - newContent.length) / Math.max(oldContent.length, 1);
-        if (sizeChange > this.config.sizeChangeThreshold) {
-            return true; // Large size change warrants version
-        }
-        // For small files, any change is significant
-        if (oldContent.length < 100 || newContent.length < 100) {
-            return true;
-        }
-        // Check semantic change using embeddings
-        try {
-            const semanticDistance = await this.calculateSemanticDistance(oldContent, newContent);
-            return semanticDistance > this.config.threshold;
-        }
-        catch (error) {
-            // If embedding fails, fall back to size-based decision
-            console.warn('Failed to calculate semantic distance:', error);
-            return sizeChange > 0.2;
-        }
-    }
-    /**
-     * Create a new version
-     */
-    async createVersion(path, content, metadata) {
-        const versionId = uuidv4();
-        const timestamp = Date.now();
-        const hash = this.hashContent(content);
-        // Get current version number
-        const versions = await this.getVersions(path);
-        const versionNumber = versions.length + 1;
-        const parentVersion = versions[0]?.id;
-        // Generate embedding for semantic comparison
-        let embedding;
-        let semanticHash;
-        try {
-            // Only generate embedding for reasonably sized content
-            if (content.length < 100000) {
-                embedding = await this.generateEmbedding(content);
-                if (embedding) {
-                    semanticHash = this.hashEmbedding(embedding);
-                }
-            }
-        }
-        catch (error) {
-            console.warn('Failed to generate embedding for version:', error);
-        }
-        // Create version entity
-        const version = {
-            id: versionId,
-            path,
-            version: versionNumber,
-            timestamp,
-            hash,
-            semanticHash,
-            size: content.length,
-            author: metadata?.author,
-            message: metadata?.message,
-            parentVersion
-        };
-        // Store version using EntityManager (with actual content as data)
-        await this.storeEntity(version, NounType.State, embedding, content);
-        // Create relationship to parent version if exists
-        if (parentVersion) {
-            try {
-                await this.createRelationship(versionId, parentVersion, VerbType.Succeeds);
-            }
-            catch (error) {
-                console.warn(`Failed to create parent relationship for version ${versionId}:`, error);
-                // Continue without relationship - non-critical for version functionality
-            }
-        }
-        // Update cache
-        if (!this.versionCache.has(path)) {
-            this.versionCache.set(path, []);
-        }
-        this.versionCache.get(path).unshift({
-            id: versionId,
-            path,
-            version: versionNumber,
-            timestamp,
-            hash,
-            size: content.length,
-            semanticHash,
-            author: metadata?.author,
-            message: metadata?.message,
-            parentVersion
-        });
-        // Prune old versions if needed
-        await this.pruneVersions(path);
-        return versionId;
-    }
-    /**
-     * Get all versions for a file
-     */
-    async getVersions(path) {
-        // Check cache first
-        if (this.versionCache.has(path)) {
-            return this.versionCache.get(path);
-        }
-        // Query using EntityManager
-        const versions = await this.findEntities({ path }, NounType.State, this.config.maxVersions * 2 // Get extra in case some are pruned
-        );
-        // Sort by timestamp (newest first)
-        versions.sort((a, b) => b.timestamp - a.timestamp);
-        // Update cache
-        this.versionCache.set(path, versions);
-        return versions;
-    }
-    /**
-     * Get a specific version's content
-     */
-    async getVersion(path, versionId) {
-        // Get the version entity
-        const version = await this.getEntity(versionId);
-        if (!version || version.path !== path) {
-            return null;
-        }
-        // Get the content from Brainy using the Brainy ID
-        const brainyId = await this.getBrainyId(versionId);
-        if (!brainyId) {
-            return null;
-        }
-        const entity = await this.brain.get(brainyId);
-        return entity?.data;
-    }
-    /**
-     * Restore a file to a specific version
-     */
-    async restoreVersion(path, versionId) {
-        const content = await this.getVersion(path, versionId);
-        if (!content) {
-            throw new Error(`Version ${versionId} not found for ${path}`);
-        }
-        // Create a new version pointing to the restored one
-        await this.createVersion(path, content, {
-            message: `Restored to version ${versionId}`
-        });
-        return content;
-    }
-    /**
-     * Get version history with diffs
-     */
-    async getVersionHistory(path, limit = 10) {
-        const versions = await this.getVersions(path);
-        const history = [];
-        for (let i = 0; i < Math.min(versions.length, limit); i++) {
-            const version = versions[i];
-            let changes = undefined;
-            // Calculate changes from parent
-            if (version.parentVersion && i < versions.length - 1) {
-                const parentVersion = versions[i + 1];
-                if (parentVersion.id === version.parentVersion) {
-                    // Simple size-based diff for now
-                    changes = {
-                        additions: Math.max(0, version.size - parentVersion.size),
-                        deletions: Math.max(0, parentVersion.size - version.size),
-                        semanticChange: version.semanticHash && parentVersion.semanticHash
-                            ? this.estimateSemanticChange(version.semanticHash, parentVersion.semanticHash)
-                            : 0
-                    };
-                }
-            }
-            history.push({ version, changes });
-        }
-        return history;
-    }
-    /**
-     * Prune old versions beyond the limit
-     */
-    async pruneVersions(path) {
-        const versions = await this.getVersions(path);
-        if (versions.length <= this.config.maxVersions) {
-            return;
-        }
-        // Keep important versions (first, last, and evenly distributed)
-        const toKeep = new Set();
-        const toDelete = [];
-        // Always keep first and last
-        toKeep.add(versions[0].id); // Newest
-        toKeep.add(versions[versions.length - 1].id); // Oldest
-        // Keep evenly distributed versions
-        const step = Math.floor(versions.length / this.config.maxVersions);
-        for (let i = 0; i < versions.length; i += step) {
-            toKeep.add(versions[i].id);
-        }
-        // Mark others for deletion
-        for (const version of versions) {
-            if (!toKeep.has(version.id)) {
-                toDelete.push(version.id);
-            }
-        }
-        // Delete excess versions
-        for (const id of toDelete.slice(0, versions.length - this.config.maxVersions)) {
-            await this.deleteEntity(id);
-        }
-        // Update cache
-        this.versionCache.set(path, versions.filter(v => !toDelete.includes(v.id)));
-    }
-    /**
-     * Calculate semantic distance between two pieces of content
-     */
-    async calculateSemanticDistance(oldContent, newContent) {
-        // Generate embeddings
-        const [oldEmbedding, newEmbedding] = await Promise.all([
-            this.generateEmbedding(oldContent),
-            this.generateEmbedding(newContent)
-        ]);
-        if (!oldEmbedding || !newEmbedding) {
-            throw new Error('Failed to generate embeddings');
-        }
-        // Calculate cosine distance
-        return cosineDistance(oldEmbedding, newEmbedding);
-    }
-    /**
-     * Generate embedding for content
-     */
-    async generateEmbedding(content) {
-        try {
-            // For text content, use first 10KB for embedding
-            const text = content.toString('utf8', 0, Math.min(10240, content.length));
-            // Use Brainy's embedding function
-            const vector = await this.brain.embed(text);
-            return vector;
-        }
-        catch (error) {
-            console.error('Failed to generate embedding:', error);
-            return undefined;
-        }
-    }
-    /**
-     * Hash content for quick comparison
-     */
-    hashContent(content) {
-        return createHash('sha256').update(content).digest('hex');
-    }
-    /**
-     * Hash embedding for quick comparison
-     */
-    hashEmbedding(embedding) {
-        return createHash('sha256')
-            .update(Buffer.from(new Float32Array(embedding).buffer))
-            .digest('hex');
-    }
-    /**
-     * Estimate semantic change from hashes (rough approximation)
-     */
-    estimateSemanticChange(hash1, hash2) {
-        if (hash1 === hash2)
-            return 0;
-        // Simple hamming distance on first few characters
-        // This is a rough approximation
-        let distance = 0;
-        for (let i = 0; i < Math.min(hash1.length, hash2.length, 8); i++) {
-            if (hash1[i] !== hash2[i])
-                distance++;
-        }
-        return distance / 8;
-    }
-    /**
-     * Clear version cache for a file
-     */
-    clearCache(path) {
-        if (path) {
-            this.versionCache.delete(path);
-        }
-        else {
-            this.versionCache.clear();
-        }
-    }
-}
-//# sourceMappingURL=SemanticVersioning.js.map

package/dist/vfs/VFSHealthCheck.d.ts

@@ -1,78 +0,0 @@
-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

@@ -1,299 +0,0 @@
-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