@soulcraft/brainy 3.9.0 → 3.10.0

package/dist/vfs/PathResolver.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Path Resolution System with High-Performance Caching
+ *
+ * PRODUCTION-READY path resolution for VFS
+ * Handles millions of paths efficiently with multi-layer caching
+ */
+import { Brainy } from '../brainy.js';
+import { VFSEntity } from './types.js';
+/**
+ * High-performance path resolver with intelligent caching
+ */
+export declare class PathResolver {
+    private brain;
+    private rootEntityId;
+    private pathCache;
+    private parentCache;
+    private hotPaths;
+    private readonly maxCacheSize;
+    private readonly cacheTTL;
+    private readonly hotPathThreshold;
+    private cacheHits;
+    private cacheMisses;
+    private maintenanceTimer;
+    constructor(brain: Brainy, rootEntityId: string, config?: {
+        maxCacheSize?: number;
+        cacheTTL?: number;
+        hotPathThreshold?: number;
+    });
+    /**
+     * Resolve a path to an entity ID
+     * Uses multi-layer caching for optimal performance
+     */
+    resolve(path: string, options?: {
+        followSymlinks?: boolean;
+        cache?: boolean;
+    }): Promise<string>;
+    /**
+     * Full path resolution by traversing the graph
+     */
+    private fullResolve;
+    /**
+     * Resolve a child entity by name within a parent directory
+     */
+    private resolveChild;
+    /**
+     * Get all children of a directory
+     */
+    getChildren(dirId: string): Promise<VFSEntity[]>;
+    /**
+     * Create a new path entry (for mkdir/writeFile)
+     */
+    createPath(path: string, entityId: string): Promise<void>;
+    /**
+     * Invalidate cache entries for a path and its children
+     */
+    invalidatePath(path: string, recursive?: boolean): void;
+    /**
+     * Cache a path entry
+     */
+    private cachePathEntry;
+    /**
+     * Check if a cache entry is still valid
+     */
+    private isCacheValid;
+    /**
+     * Evict old cache entries (LRU with TTL)
+     */
+    private evictOldEntries;
+    /**
+     * Start periodic cache maintenance
+     */
+    private startCacheMaintenance;
+    /**
+     * Get entity by ID
+     */
+    private getEntity;
+    private normalizePath;
+    private splitPath;
+    private joinPath;
+    private getParentPath;
+    private getBasename;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        cacheSize: number;
+        hotPaths: number;
+        hitRate: number;
+        hits: number;
+        misses: number;
+    };
+}

package/dist/vfs/PathResolver.js

@@ -0,0 +1,362 @@
+/**
+ * Path Resolution System with High-Performance Caching
+ *
+ * PRODUCTION-READY path resolution for VFS
+ * Handles millions of paths efficiently with multi-layer caching
+ */
+import { VerbType } from '../types/graphTypes.js';
+import { VFSError, VFSErrorCode } from './types.js';
+/**
+ * High-performance path resolver with intelligent caching
+ */
+export class PathResolver {
+    constructor(brain, rootEntityId, config) {
+        // Statistics
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+        // Maintenance timer
+        this.maintenanceTimer = null;
+        this.brain = brain;
+        this.rootEntityId = rootEntityId;
+        // Initialize caches
+        this.pathCache = new Map();
+        this.parentCache = new Map();
+        this.hotPaths = new Set();
+        // Configure cache
+        this.maxCacheSize = config?.maxCacheSize || 100000;
+        this.cacheTTL = config?.cacheTTL || 5 * 60 * 1000; // 5 minutes
+        this.hotPathThreshold = config?.hotPathThreshold || 10;
+        // Start cache maintenance
+        this.startCacheMaintenance();
+    }
+    /**
+     * Resolve a path to an entity ID
+     * Uses multi-layer caching for optimal performance
+     */
+    async resolve(path, options) {
+        // Normalize path
+        const normalizedPath = this.normalizePath(path);
+        // Handle root
+        if (normalizedPath === '/') {
+            return this.rootEntityId;
+        }
+        // Check L1 cache (hot paths)
+        if (options?.cache !== false && this.hotPaths.has(normalizedPath)) {
+            const cached = this.pathCache.get(normalizedPath);
+            if (cached && this.isCacheValid(cached)) {
+                this.cacheHits++;
+                cached.hits++;
+                return cached.entityId;
+            }
+        }
+        // Check L2 cache (regular cache)
+        if (options?.cache !== false && this.pathCache.has(normalizedPath)) {
+            const cached = this.pathCache.get(normalizedPath);
+            if (this.isCacheValid(cached)) {
+                this.cacheHits++;
+                cached.hits++;
+                // Promote to hot path if accessed frequently
+                if (cached.hits >= this.hotPathThreshold) {
+                    this.hotPaths.add(normalizedPath);
+                }
+                return cached.entityId;
+            }
+            else {
+                // Remove stale entry
+                this.pathCache.delete(normalizedPath);
+            }
+        }
+        this.cacheMisses++;
+        // Try to resolve using parent cache
+        const parentPath = this.getParentPath(normalizedPath);
+        const name = this.getBasename(normalizedPath);
+        if (parentPath && this.pathCache.has(parentPath)) {
+            const parentCached = this.pathCache.get(parentPath);
+            if (this.isCacheValid(parentCached)) {
+                // We have the parent, just need to find the child
+                const entityId = await this.resolveChild(parentCached.entityId, name);
+                if (entityId) {
+                    this.cachePathEntry(normalizedPath, entityId);
+                    return entityId;
+                }
+            }
+        }
+        // Full resolution required
+        const entityId = await this.fullResolve(normalizedPath, options);
+        // Cache the result
+        this.cachePathEntry(normalizedPath, entityId);
+        return entityId;
+    }
+    /**
+     * Full path resolution by traversing the graph
+     */
+    async fullResolve(path, options) {
+        const parts = this.splitPath(path);
+        let currentId = this.rootEntityId;
+        let currentPath = '/';
+        for (const part of parts) {
+            if (!part)
+                continue; // Skip empty parts
+            // Find child with matching name
+            const childId = await this.resolveChild(currentId, part);
+            if (!childId) {
+                throw new VFSError(VFSErrorCode.ENOENT, `No such file or directory: ${path}`, path, 'resolve');
+            }
+            currentPath = this.joinPath(currentPath, part);
+            currentId = childId;
+            // Cache intermediate paths
+            this.cachePathEntry(currentPath, currentId);
+            // Handle symlinks if needed
+            if (options?.followSymlinks) {
+                const entity = await this.getEntity(currentId);
+                if (entity.metadata.vfsType === 'symlink') {
+                    // Resolve symlink target
+                    const target = entity.metadata.attributes?.target;
+                    if (target) {
+                        currentId = await this.resolve(target, options);
+                    }
+                }
+            }
+        }
+        return currentId;
+    }
+    /**
+     * Resolve a child entity by name within a parent directory
+     */
+    async resolveChild(parentId, name) {
+        // Check parent cache first
+        const cachedChildren = this.parentCache.get(parentId);
+        if (cachedChildren && cachedChildren.has(name)) {
+            // We know this child exists, find it by path since parent queries don't work
+            const parentEntity = await this.getEntity(parentId);
+            const parentPath = parentEntity.metadata.path;
+            const childPath = this.joinPath(parentPath, name);
+            const pathResults = await this.brain.find({
+                where: { path: childPath },
+                limit: 1
+            });
+            if (pathResults.length > 0) {
+                return pathResults[0].entity.id;
+            }
+        }
+        // Since parent field queries don't work reliably, construct the expected path
+        // and query by path instead
+        const parentEntity = await this.getEntity(parentId);
+        const parentPath = parentEntity.metadata.path;
+        const childPath = this.joinPath(parentPath, name);
+        const results = await this.brain.find({
+            where: { path: childPath },
+            limit: 1
+        });
+        if (results.length > 0) {
+            const childId = results[0].entity.id;
+            // Update parent cache
+            if (!this.parentCache.has(parentId)) {
+                this.parentCache.set(parentId, new Set());
+            }
+            this.parentCache.get(parentId).add(name);
+            return childId;
+        }
+        return null;
+    }
+    /**
+     * Get all children of a directory
+     */
+    async getChildren(dirId) {
+        // Use Brainy's relationship query to find all children
+        const results = await this.brain.find({
+            connected: {
+                from: dirId,
+                via: VerbType.Contains
+            },
+            limit: 10000 // Large limit for directories
+        });
+        // Filter and process valid VFS entities only
+        const validChildren = [];
+        const childNames = new Set();
+        for (const result of results) {
+            const entity = result.entity;
+            // Only include entities with proper VFS metadata and non-empty names
+            if (entity.metadata?.vfsType &&
+                entity.metadata?.name &&
+                entity.metadata?.path &&
+                entity.id !== dirId) { // Don't include the directory itself
+                validChildren.push(entity);
+                childNames.add(entity.metadata.name);
+            }
+        }
+        this.parentCache.set(dirId, childNames);
+        return validChildren;
+    }
+    /**
+     * Create a new path entry (for mkdir/writeFile)
+     */
+    async createPath(path, entityId) {
+        const normalizedPath = this.normalizePath(path);
+        // Cache the new path
+        this.cachePathEntry(normalizedPath, entityId);
+        // Update parent cache
+        const parentPath = this.getParentPath(normalizedPath);
+        const name = this.getBasename(normalizedPath);
+        if (parentPath) {
+            const parentId = await this.resolve(parentPath);
+            if (!this.parentCache.has(parentId)) {
+                this.parentCache.set(parentId, new Set());
+            }
+            this.parentCache.get(parentId).add(name);
+        }
+    }
+    /**
+     * Invalidate cache entries for a path and its children
+     */
+    invalidatePath(path, recursive = false) {
+        const normalizedPath = this.normalizePath(path);
+        // Remove from all caches
+        this.pathCache.delete(normalizedPath);
+        this.hotPaths.delete(normalizedPath);
+        if (recursive) {
+            // Remove all paths that start with this path
+            const prefix = normalizedPath.endsWith('/') ? normalizedPath : normalizedPath + '/';
+            for (const [cachedPath] of this.pathCache) {
+                if (cachedPath.startsWith(prefix)) {
+                    this.pathCache.delete(cachedPath);
+                    this.hotPaths.delete(cachedPath);
+                }
+            }
+        }
+        // Clear parent cache for the entity
+        const cached = this.pathCache.get(normalizedPath);
+        if (cached) {
+            this.parentCache.delete(cached.entityId);
+        }
+    }
+    /**
+     * Cache a path entry
+     */
+    cachePathEntry(path, entityId) {
+        // Evict old entries if cache is full
+        if (this.pathCache.size >= this.maxCacheSize) {
+            this.evictOldEntries();
+        }
+        const existing = this.pathCache.get(path);
+        this.pathCache.set(path, {
+            entityId,
+            timestamp: Date.now(),
+            hits: existing?.hits || 0
+        });
+    }
+    /**
+     * Check if a cache entry is still valid
+     */
+    isCacheValid(entry) {
+        return (Date.now() - entry.timestamp) < this.cacheTTL;
+    }
+    /**
+     * Evict old cache entries (LRU with TTL)
+     */
+    evictOldEntries() {
+        const now = Date.now();
+        const entries = Array.from(this.pathCache.entries());
+        // Sort by least recently used (combination of timestamp and hits)
+        entries.sort((a, b) => {
+            const scoreA = a[1].timestamp + (a[1].hits * 60000); // Boost for hits
+            const scoreB = b[1].timestamp + (b[1].hits * 60000);
+            return scoreA - scoreB;
+        });
+        // Remove 10% of cache
+        const toRemove = Math.floor(this.maxCacheSize * 0.1);
+        for (let i = 0; i < toRemove && i < entries.length; i++) {
+            const [path] = entries[i];
+            this.pathCache.delete(path);
+            this.hotPaths.delete(path);
+        }
+    }
+    /**
+     * Start periodic cache maintenance
+     */
+    startCacheMaintenance() {
+        this.maintenanceTimer = setInterval(() => {
+            // Clean up expired entries
+            const now = Date.now();
+            for (const [path, entry] of this.pathCache) {
+                if (!this.isCacheValid(entry)) {
+                    this.pathCache.delete(path);
+                    this.hotPaths.delete(path);
+                }
+            }
+            // Log cache statistics (in production, send to monitoring)
+            const hitRate = this.cacheHits / (this.cacheHits + this.cacheMisses);
+            if ((this.cacheHits + this.cacheMisses) % 1000 === 0) {
+                console.log(`[PathResolver] Cache stats: ${Math.round(hitRate * 100)}% hit rate, ${this.pathCache.size} entries, ${this.hotPaths.size} hot paths`);
+            }
+        }, 60000); // Every minute
+    }
+    /**
+     * Get entity by ID
+     */
+    async getEntity(entityId) {
+        const entity = await this.brain.get(entityId);
+        if (!entity) {
+            throw new VFSError(VFSErrorCode.ENOENT, `Entity not found: ${entityId}`, undefined, 'getEntity');
+        }
+        return entity;
+    }
+    // ============= Path Utilities =============
+    normalizePath(path) {
+        // Remove multiple slashes, trailing slashes (except for root)
+        let normalized = path.replace(/\/+/g, '/');
+        if (normalized.length > 1 && normalized.endsWith('/')) {
+            normalized = normalized.slice(0, -1);
+        }
+        return normalized || '/';
+    }
+    splitPath(path) {
+        return this.normalizePath(path).split('/').filter(Boolean);
+    }
+    joinPath(parent, child) {
+        if (parent === '/')
+            return `/${child}`;
+        return `${parent}/${child}`;
+    }
+    getParentPath(path) {
+        const normalized = this.normalizePath(path);
+        if (normalized === '/')
+            return null;
+        const lastSlash = normalized.lastIndexOf('/');
+        if (lastSlash === 0)
+            return '/';
+        return normalized.substring(0, lastSlash);
+    }
+    getBasename(path) {
+        const normalized = this.normalizePath(path);
+        if (normalized === '/')
+            return '';
+        const lastSlash = normalized.lastIndexOf('/');
+        return normalized.substring(lastSlash + 1);
+    }
+    /**
+     * Cleanup resources
+     */
+    cleanup() {
+        if (this.maintenanceTimer) {
+            clearInterval(this.maintenanceTimer);
+            this.maintenanceTimer = null;
+        }
+        this.pathCache.clear();
+        this.parentCache.clear();
+        this.hotPaths.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            cacheSize: this.pathCache.size,
+            hotPaths: this.hotPaths.size,
+            hitRate: this.cacheHits / (this.cacheHits + this.cacheMisses),
+            hits: this.cacheHits,
+            misses: this.cacheMisses
+        };
+    }
+}
+//# sourceMappingURL=PathResolver.js.map

package/dist/vfs/PersistentEntitySystem.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Persistent Entity System for VFS
+ *
+ * Manages entities that evolve across files and time
+ * Not just story characters - any evolving entity: APIs, customers, services, models
+ * PRODUCTION-READY: Real implementation using Brainy
+ */
+import { Brainy } from '../brainy.js';
+/**
+ * Persistent entity that exists across files and evolves over time
+ */
+export interface PersistentEntity {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    aliases: string[];
+    appearances: EntityAppearance[];
+    attributes: Record<string, any>;
+    created: number;
+    lastUpdated: number;
+    version: number;
+}
+/**
+ * An appearance of an entity in a specific file/location
+ */
+export interface EntityAppearance {
+    id: string;
+    entityId: string;
+    filePath: string;
+    context: string;
+    position?: {
+        line?: number;
+        column?: number;
+        offset?: number;
+    };
+    timestamp: number;
+    version: number;
+    changes?: EntityChange[];
+    confidence: number;
+}
+/**
+ * A change/evolution to an entity
+ */
+export interface EntityChange {
+    field: string;
+    oldValue: any;
+    newValue: any;
+    timestamp: number;
+    source: string;
+    reason?: string;
+}
+/**
+ * Configuration for persistent entities
+ */
+export interface PersistentEntityConfig {
+    autoExtract?: boolean;
+    similarityThreshold?: number;
+    maxAppearances?: number;
+    evolutionTracking?: boolean;
+}
+/**
+ * Persistent Entity System
+ *
+ * Tracks entities that exist across multiple files and evolve over time
+ * Examples:
+ * - Story characters that appear in multiple chapters
+ * - API endpoints that evolve across documentation
+ * - Business entities that appear in multiple reports
+ * - Code classes/functions that span multiple files
+ */
+export declare class PersistentEntitySystem {
+    private brain;
+    private config;
+    private entityCache;
+    constructor(brain: Brainy, config?: PersistentEntityConfig);
+    /**
+     * Create a new persistent entity
+     */
+    createEntity(entity: Omit<PersistentEntity, 'id' | 'created' | 'lastUpdated' | 'version' | 'appearances'>): Promise<string>;
+    /**
+     * Find an existing entity by name or attributes
+     */
+    findEntity(query: {
+        name?: string;
+        type?: string;
+        attributes?: Record<string, any>;
+        similar?: string;
+    }): Promise<PersistentEntity[]>;
+    /**
+     * Record an appearance of an entity in a file
+     */
+    recordAppearance(entityId: string, filePath: string, context: string, options?: {
+        position?: EntityAppearance['position'];
+        confidence?: number;
+        extractChanges?: boolean;
+    }): Promise<string>;
+    /**
+     * Get entity evolution history
+     */
+    getEvolution(entityId: string): Promise<{
+        entity: PersistentEntity;
+        timeline: Array<{
+            timestamp: number;
+            version: number;
+            changes: EntityChange[];
+            appearance?: EntityAppearance;
+        }>;
+    }>;
+    /**
+     * Find all appearances of an entity
+     */
+    findAppearances(entityId: string, options?: {
+        filePath?: string;
+        since?: number;
+        until?: number;
+        minConfidence?: number;
+    }): Promise<EntityAppearance[]>;
+    /**
+     * Evolve an entity with new information
+     */
+    evolveEntity(entityId: string, updates: Partial<Pick<PersistentEntity, 'name' | 'description' | 'aliases' | 'attributes'>>, source: string, reason?: string): Promise<void>;
+    /**
+     * Extract entities from content (auto-extraction)
+     */
+    extractEntities(filePath: string, content: Buffer): Promise<string[]>;
+    /**
+     * Update references when a file moves
+     */
+    updateReferences(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Get entity by ID
+     */
+    private getEntity;
+    /**
+     * Update stored entity
+     */
+    private updateEntity;
+    /**
+     * Detect changes in entity from context
+     */
+    private detectChanges;
+    /**
+     * Generate embedding for entity
+     */
+    private generateEntityEmbedding;
+    /**
+     * Generate embedding for text
+     */
+    private generateTextEmbedding;
+    /**
+     * Detect entity type from name and context
+     */
+    private detectEntityType;
+    /**
+     * Extract context around a position
+     */
+    private extractContext;
+    /**
+     * Clear entity cache
+     */
+    clearCache(entityId?: string): void;
+}