@soulcraft/brainy 3.9.1 → 3.10.0

package/dist/vfs/EntityManager.js

@@ -0,0 +1,216 @@
+/**
+ * EntityManager Base Class
+ *
+ * Provides standardized entity ID management for all Knowledge Layer components
+ * Solves the root cause of ID mismatch issues by establishing clear patterns
+ */
+import { v4 as uuidv4 } from '../universal/uuid.js';
+/**
+ * EntityManager Base Class
+ *
+ * All Knowledge Layer components should extend this to get standardized:
+ * - Entity storage and retrieval
+ * - ID management and mapping
+ * - Query patterns
+ * - Relationship creation
+ */
+export class EntityManager {
+    constructor(brain, systemName) {
+        this.brain = brain;
+        this.systemName = systemName;
+        this.idMappings = new Map(); // domainId -> brainyId
+        this.brainyToMappings = new Map(); // brainyId -> domainId
+    }
+    /**
+     * Store an entity with proper ID management
+     */
+    async storeEntity(entity, nounType, embedding, data) {
+        // Generate domain ID if not provided
+        if (!entity.id) {
+            entity.id = uuidv4();
+        }
+        // Store in Brainy and get the Brainy entity ID
+        const brainyId = await this.brain.add({
+            type: nounType,
+            data: data || Buffer.from(JSON.stringify(entity)),
+            metadata: {
+                ...entity,
+                system: this.systemName,
+                domainId: entity.id, // Store the domain ID for reference
+                storedAt: Date.now()
+            },
+            vector: embedding
+        });
+        // Store ID mapping
+        this.idMappings.set(entity.id, brainyId);
+        this.brainyToMappings.set(brainyId, entity.id);
+        // Update entity with Brainy ID
+        entity.brainyId = brainyId;
+        return entity.id; // Return domain ID for external use
+    }
+    /**
+     * Update an existing entity
+     */
+    async updateEntity(entity, embedding) {
+        const brainyId = this.idMappings.get(entity.id);
+        if (!brainyId) {
+            throw new Error(`Entity ${entity.id} not found in mappings`);
+        }
+        await this.brain.update({
+            id: brainyId,
+            data: Buffer.from(JSON.stringify(entity)),
+            metadata: {
+                ...entity,
+                system: this.systemName,
+                domainId: entity.id,
+                updatedAt: Date.now()
+            },
+            vector: embedding
+        });
+    }
+    /**
+     * Retrieve entity by domain ID
+     */
+    async getEntity(domainId) {
+        // First try from cache
+        let brainyId = this.idMappings.get(domainId);
+        // If not in cache, search by domain ID in metadata
+        if (!brainyId) {
+            const results = await this.brain.find({
+                where: {
+                    domainId,
+                    system: this.systemName
+                },
+                limit: 1
+            });
+            if (results.length === 0) {
+                return null;
+            }
+            brainyId = results[0].entity.id;
+            // Cache the mapping
+            this.idMappings.set(domainId, brainyId);
+            this.brainyToMappings.set(brainyId, domainId);
+        }
+        // Get entity using Brainy ID
+        const brainyEntity = await this.brain.get(brainyId);
+        if (!brainyEntity) {
+            return null;
+        }
+        // Parse entity from metadata
+        const entity = brainyEntity.metadata;
+        entity.brainyId = brainyId;
+        return entity;
+    }
+    /**
+     * Find entities by metadata criteria
+     */
+    async findEntities(criteria, nounType, limit = 100) {
+        const query = {
+            ...criteria,
+            system: this.systemName
+        };
+        const results = await this.brain.find({
+            where: query,
+            type: nounType,
+            limit
+        });
+        const entities = [];
+        for (const result of results) {
+            const entity = result.entity.metadata;
+            entity.brainyId = result.entity.id;
+            // Update mappings cache
+            this.idMappings.set(entity.id, result.entity.id);
+            this.brainyToMappings.set(result.entity.id, entity.id);
+            entities.push(entity);
+        }
+        return entities;
+    }
+    /**
+     * Create relationship between entities using proper Brainy IDs
+     */
+    async createRelationship(fromDomainId, toDomainId, relationshipType, metadata) {
+        // Get Brainy IDs for both entities
+        const fromBrainyId = await this.getBrainyId(fromDomainId);
+        const toBrainyId = await this.getBrainyId(toDomainId);
+        if (!fromBrainyId || !toBrainyId) {
+            throw new Error(`Cannot find Brainy IDs for relationship: ${fromDomainId} -> ${toDomainId}`);
+        }
+        // Create relationship using Brainy IDs
+        await this.brain.relate({
+            from: fromBrainyId,
+            to: toBrainyId,
+            type: relationshipType,
+            metadata
+        });
+    }
+    /**
+     * Get Brainy ID for a domain ID
+     */
+    async getBrainyId(domainId) {
+        // Check cache first
+        let brainyId = this.idMappings.get(domainId);
+        if (!brainyId) {
+            // Search in Brainy
+            const results = await this.brain.find({
+                where: {
+                    domainId,
+                    system: this.systemName
+                },
+                limit: 1
+            });
+            if (results.length > 0) {
+                brainyId = results[0].entity.id;
+                // Cache the mapping
+                this.idMappings.set(domainId, brainyId);
+                this.brainyToMappings.set(brainyId, domainId);
+            }
+        }
+        return brainyId || null;
+    }
+    /**
+     * Get domain ID for a Brainy ID
+     */
+    getDomainId(brainyId) {
+        return this.brainyToMappings.get(brainyId) || null;
+    }
+    /**
+     * Delete entity by domain ID
+     */
+    async deleteEntity(domainId) {
+        const brainyId = await this.getBrainyId(domainId);
+        if (brainyId) {
+            await this.brain.delete(brainyId);
+            // Clean up mappings
+            this.idMappings.delete(domainId);
+            this.brainyToMappings.delete(brainyId);
+        }
+    }
+    /**
+     * Clear ID mapping cache (useful for tests)
+     */
+    clearMappingCache() {
+        this.idMappings.clear();
+        this.brainyToMappings.clear();
+    }
+    /**
+     * Batch load mappings for performance
+     */
+    async loadMappings(domainIds) {
+        const unknownIds = domainIds.filter(id => !this.idMappings.has(id));
+        if (unknownIds.length === 0)
+            return;
+        const results = await this.brain.find({
+            where: {
+                domainId: { $in: unknownIds },
+                system: this.systemName
+            },
+            limit: unknownIds.length
+        });
+        for (const result of results) {
+            const domainId = result.entity.metadata.domainId;
+            this.idMappings.set(domainId, result.entity.id);
+            this.brainyToMappings.set(result.entity.id, domainId);
+        }
+    }
+}
+//# sourceMappingURL=EntityManager.js.map

package/dist/vfs/EventRecorder.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Event Recording System for VFS
+ *
+ * Records every file operation as an event for complete history tracking
+ * PRODUCTION-READY: No mocks, real implementation
+ */
+import { Brainy } from '../brainy.js';
+/**
+ * File operation event
+ */
+export interface FileEvent {
+    id: string;
+    type: 'create' | 'write' | 'append' | 'delete' | 'move' | 'rename' | 'mkdir' | 'rmdir';
+    path: string;
+    timestamp: number;
+    content?: Buffer;
+    size?: number;
+    hash?: string;
+    author?: string;
+    metadata?: Record<string, any>;
+    previousHash?: string;
+    oldPath?: string;
+}
+/**
+ * Event Recorder - Stores all file operations as searchable events
+ */
+export declare class EventRecorder {
+    private brain;
+    constructor(brain: Brainy);
+    /**
+     * Record a file operation event
+     */
+    recordEvent(event: Omit<FileEvent, 'id' | 'timestamp'>): Promise<string>;
+    /**
+     * Get all events matching criteria
+     */
+    getEvents(options?: {
+        since?: number;
+        until?: number;
+        types?: string[];
+        limit?: number;
+    }): Promise<FileEvent[]>;
+    /**
+     * Get complete history for a file
+     */
+    getHistory(path: string, options?: {
+        limit?: number;
+        since?: number;
+        until?: number;
+        types?: FileEvent['type'][];
+    }): Promise<FileEvent[]>;
+    /**
+     * Replay events to reconstruct file state at a specific time
+     */
+    reconstructFileAtTime(path: string, timestamp: number): Promise<Buffer | null>;
+    /**
+     * Get file changes between two timestamps
+     */
+    getChanges(since: number, until?: number): Promise<FileEvent[]>;
+    /**
+     * Calculate statistics for a file or directory
+     */
+    getStatistics(path: string): Promise<{
+        totalEvents: number;
+        firstEvent: number | null;
+        lastEvent: number | null;
+        totalWrites: number;
+        totalBytes: number;
+        authors: string[];
+    }>;
+    /**
+     * Find files that changed together (temporal coupling)
+     */
+    findTemporalCoupling(path: string, windowMs?: number): Promise<Map<string, number>>;
+    /**
+     * Generate embedding for an event (for semantic search)
+     */
+    private generateEventEmbedding;
+    /**
+     * Prune old events (for storage management)
+     */
+    pruneEvents(olderThan: number, keepEvery?: number): Promise<number>;
+}

package/dist/vfs/EventRecorder.js

@@ -0,0 +1,292 @@
+/**
+ * Event Recording System for VFS
+ *
+ * Records every file operation as an event for complete history tracking
+ * PRODUCTION-READY: No mocks, real implementation
+ */
+import { NounType } from '../types/graphTypes.js';
+import { v4 as uuidv4 } from '../universal/uuid.js';
+import { createHash } from 'crypto';
+/**
+ * Event Recorder - Stores all file operations as searchable events
+ */
+export class EventRecorder {
+    constructor(brain) {
+        this.brain = brain;
+    }
+    /**
+     * Record a file operation event
+     */
+    async recordEvent(event) {
+        const eventId = uuidv4();
+        const timestamp = Date.now();
+        // Calculate content hash if content provided
+        const hash = event.content
+            ? createHash('sha256').update(event.content).digest('hex')
+            : undefined;
+        // Store event as Brainy entity
+        const entity = await this.brain.add({
+            type: NounType.Event,
+            data: event.content || Buffer.from(JSON.stringify(event)),
+            metadata: {
+                ...event,
+                id: eventId,
+                timestamp,
+                hash,
+                eventType: 'file-operation',
+                system: 'vfs'
+            },
+            // Generate embedding for content-based events
+            vector: event.content && event.content.length < 100000
+                ? await this.generateEventEmbedding(event)
+                : undefined
+        });
+        return entity;
+    }
+    /**
+     * Get all events matching criteria
+     */
+    async getEvents(options) {
+        const limit = options?.limit || 100;
+        const since = options?.since || 0;
+        const until = options?.until || Date.now();
+        const query = {
+            eventType: 'file-operation'
+        };
+        // Add time filters
+        if (since || until) {
+            query.timestamp = {};
+            if (since)
+                query.timestamp.$gte = since;
+            if (until)
+                query.timestamp.$lte = until;
+        }
+        // Add type filter
+        if (options?.types && options.types.length > 0) {
+            query.type = { $in: options.types };
+        }
+        // Query events from Brainy
+        const results = await this.brain.find({
+            where: query,
+            type: NounType.Event,
+            limit
+        });
+        const events = [];
+        for (const result of results) {
+            if (result.entity?.metadata) {
+                events.push(result.entity.metadata);
+            }
+        }
+        return events.sort((a, b) => b.timestamp - a.timestamp);
+    }
+    /**
+     * Get complete history for a file
+     */
+    async getHistory(path, options) {
+        const query = {
+            path,
+            eventType: 'file-operation'
+        };
+        // Add time filters
+        if (options?.since || options?.until) {
+            query.timestamp = {};
+            if (options.since)
+                query.timestamp.$gte = options.since;
+            if (options.until)
+                query.timestamp.$lte = options.until;
+        }
+        // Add type filter
+        if (options?.types && options.types.length > 0) {
+            query.type = { $in: options.types };
+        }
+        // Query events from Brainy
+        const results = await this.brain.find({
+            where: query,
+            type: NounType.Event,
+            limit: options?.limit || 100,
+            // Sort by timestamp descending (newest first)
+            // Note: Sorting would need to be implemented in Brainy
+        });
+        // Convert results to FileEvent format
+        const events = results.map(r => ({
+            id: r.entity.metadata.id,
+            type: r.entity.metadata.type,
+            path: r.entity.metadata.path,
+            timestamp: r.entity.metadata.timestamp,
+            content: r.entity.metadata.content,
+            size: r.entity.metadata.size,
+            hash: r.entity.metadata.hash,
+            author: r.entity.metadata.author,
+            metadata: r.entity.metadata.metadata,
+            previousHash: r.entity.metadata.previousHash
+        }));
+        // Sort by timestamp (newest first)
+        return events.sort((a, b) => b.timestamp - a.timestamp);
+    }
+    /**
+     * Replay events to reconstruct file state at a specific time
+     */
+    async reconstructFileAtTime(path, timestamp) {
+        // Get all events up to the specified time
+        const events = await this.getHistory(path, {
+            until: timestamp,
+            types: ['create', 'write', 'append', 'delete']
+        });
+        // Sort chronologically for replay
+        const chronological = events.reverse();
+        // Find last write or create event
+        let lastContent = null;
+        let deleted = false;
+        for (const event of chronological) {
+            switch (event.type) {
+                case 'create':
+                case 'write':
+                    lastContent = event.content || null;
+                    deleted = false;
+                    break;
+                case 'append':
+                    if (lastContent && event.content) {
+                        lastContent = Buffer.concat([lastContent, event.content]);
+                    }
+                    break;
+                case 'delete':
+                    deleted = true;
+                    lastContent = null;
+                    break;
+            }
+        }
+        return deleted ? null : lastContent;
+    }
+    /**
+     * Get file changes between two timestamps
+     */
+    async getChanges(since, until) {
+        const query = {
+            eventType: 'file-operation',
+            timestamp: { $gte: since }
+        };
+        if (until) {
+            query.timestamp.$lte = until;
+        }
+        const results = await this.brain.find({
+            where: query,
+            type: NounType.Event,
+            limit: 1000
+        });
+        return results.map(r => ({
+            id: r.entity.metadata.id,
+            type: r.entity.metadata.type,
+            path: r.entity.metadata.path,
+            timestamp: r.entity.metadata.timestamp,
+            size: r.entity.metadata.size,
+            hash: r.entity.metadata.hash,
+            author: r.entity.metadata.author
+        }));
+    }
+    /**
+     * Calculate statistics for a file or directory
+     */
+    async getStatistics(path) {
+        const events = await this.getHistory(path, { limit: 10000 });
+        if (events.length === 0) {
+            return {
+                totalEvents: 0,
+                firstEvent: null,
+                lastEvent: null,
+                totalWrites: 0,
+                totalBytes: 0,
+                authors: []
+            };
+        }
+        const stats = {
+            totalEvents: events.length,
+            firstEvent: events[events.length - 1].timestamp, // Oldest
+            lastEvent: events[0].timestamp, // Newest
+            totalWrites: 0,
+            totalBytes: 0,
+            authors: new Set()
+        };
+        for (const event of events) {
+            if (event.type === 'write' || event.type === 'append') {
+                stats.totalWrites++;
+                stats.totalBytes += event.size || 0;
+            }
+            if (event.author) {
+                stats.authors.add(event.author);
+            }
+        }
+        return {
+            ...stats,
+            authors: Array.from(stats.authors)
+        };
+    }
+    /**
+     * Find files that changed together (temporal coupling)
+     */
+    async findTemporalCoupling(path, windowMs = 60000) {
+        const events = await this.getHistory(path);
+        const coupling = new Map();
+        for (const event of events) {
+            // Find other files changed within the time window
+            const related = await this.getChanges(event.timestamp - windowMs, event.timestamp + windowMs);
+            for (const relatedEvent of related) {
+                if (relatedEvent.path !== path) {
+                    const count = coupling.get(relatedEvent.path) || 0;
+                    coupling.set(relatedEvent.path, count + 1);
+                }
+            }
+        }
+        // Sort by coupling strength
+        return new Map(Array.from(coupling.entries())
+            .sort((a, b) => b[1] - a[1]));
+    }
+    /**
+     * Generate embedding for an event (for semantic search)
+     */
+    async generateEventEmbedding(event) {
+        try {
+            // Generate embedding based on event type and content
+            let textToEmbed;
+            if (event.type === 'write' || event.type === 'create') {
+                // For write/create events with content, embed the content
+                if (event.content && event.content.length < 100000) {
+                    // Convert Buffer to string for text files
+                    textToEmbed = Buffer.isBuffer(event.content)
+                        ? event.content.toString('utf8', 0, Math.min(10240, event.content.length))
+                        : String(event.content).slice(0, 10240);
+                }
+                else {
+                    // For large files or no content, create descriptive text
+                    textToEmbed = `File ${event.type} event at ${event.path}, size: ${event.size || 0} bytes`;
+                }
+            }
+            else {
+                // For other events (read, delete, rename, etc), create descriptive text
+                textToEmbed = `File ${event.type} event at ${event.path}${event.oldPath ? ` from ${event.oldPath}` : ''}`;
+            }
+            // Use Brainy's embed function
+            const vector = await this.brain.embed(textToEmbed);
+            return vector;
+        }
+        catch (error) {
+            console.error('Failed to generate event embedding:', error);
+            return undefined;
+        }
+    }
+    /**
+     * Prune old events (for storage management)
+     */
+    async pruneEvents(olderThan, keepEvery = 10) {
+        const events = await this.getChanges(0, Date.now() - olderThan);
+        let pruned = 0;
+        for (let i = 0; i < events.length; i++) {
+            // Keep every Nth event for history sampling
+            if (i % keepEvery !== 0) {
+                await this.brain.delete(events[i].id);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+}
+//# sourceMappingURL=EventRecorder.js.map

package/dist/vfs/FSCompat.d.ts

@@ -0,0 +1,85 @@
+/**
+ * fs-Compatible Interface for VFS
+ *
+ * Provides a drop-in replacement for Node's fs module
+ * that uses VFS for storage instead of the real filesystem.
+ *
+ * Usage:
+ *   import { FSCompat } from '@soulcraft/brainy/vfs'
+ *   const fs = new FSCompat(brain.vfs())
+ *
+ *   // Now use like Node's fs
+ *   await fs.promises.readFile('/path')
+ *   fs.createReadStream('/path').pipe(output)
+ */
+import { VirtualFileSystem } from './VirtualFileSystem.js';
+import type { VFSStats, VFSDirent } from './types.js';
+export declare class FSCompat {
+    private vfs;
+    /**
+     * Promise-based API (like fs.promises)
+     */
+    readonly promises: FSPromises;
+    constructor(vfs: VirtualFileSystem);
+    readFile(path: string, callback: (err: Error | null, data?: Buffer) => void): void;
+    readFile(path: string, encoding: BufferEncoding, callback: (err: Error | null, data?: string) => void): void;
+    writeFile(path: string, data: Buffer | string, callback: (err: Error | null) => void): void;
+    mkdir(path: string, callback: (err: Error | null) => void): void;
+    rmdir(path: string, callback: (err: Error | null) => void): void;
+    readdir(path: string, callback: (err: Error | null, files?: string[]) => void): void;
+    stat(path: string, callback: (err: Error | null, stats?: VFSStats) => void): void;
+    lstat(path: string, callback: (err: Error | null, stats?: VFSStats) => void): void;
+    unlink(path: string, callback: (err: Error | null) => void): void;
+    rename(oldPath: string, newPath: string, callback: (err: Error | null) => void): void;
+    copyFile(src: string, dest: string, callback: (err: Error | null) => void): void;
+    copyFile(src: string, dest: string, flags: number, callback: (err: Error | null) => void): void;
+    exists(path: string, callback: (exists: boolean) => void): void;
+    access(path: string, callback: (err: Error | null) => void): void;
+    access(path: string, mode: number, callback: (err: Error | null) => void): void;
+    appendFile(path: string, data: Buffer | string, callback: (err: Error | null) => void): void;
+    createReadStream(path: string, options?: any): NodeJS.ReadableStream;
+    createWriteStream(path: string, options?: any): NodeJS.WritableStream;
+    watch(path: string, listener?: any): {
+        close(): void;
+    };
+    watchFile(path: string, listener: any): void;
+    unwatchFile(path: string): void;
+    /**
+     * Import a directory from real filesystem (VFS extension)
+     */
+    importDirectory(sourcePath: string, options?: any): Promise<any>;
+    /**
+     * Search files semantically (VFS extension)
+     */
+    search(query: string, options?: any): Promise<import("./types.js").SearchResult[]>;
+}
+/**
+ * Promise-based fs API (like fs.promises)
+ */
+declare class FSPromises {
+    private vfs;
+    constructor(vfs: VirtualFileSystem);
+    readFile(path: string, options?: any): Promise<Buffer | string>;
+    writeFile(path: string, data: Buffer | string, options?: any): Promise<void>;
+    mkdir(path: string, options?: any): Promise<void>;
+    rmdir(path: string, options?: any): Promise<void>;
+    readdir(path: string, options?: any): Promise<string[] | VFSDirent[]>;
+    stat(path: string): Promise<VFSStats>;
+    lstat(path: string): Promise<VFSStats>;
+    unlink(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    copyFile(src: string, dest: string, flags?: number): Promise<void>;
+    access(path: string, mode?: number): Promise<void>;
+    appendFile(path: string, data: Buffer | string, options?: any): Promise<void>;
+    realpath(path: string): Promise<string>;
+    chmod(path: string, mode: number): Promise<void>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
+    symlink(target: string, path: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    search(query: string, options?: any): Promise<import("./types.js").SearchResult[]>;
+    findSimilar(path: string, options?: any): Promise<import("./types.js").SearchResult[]>;
+    importDirectory(sourcePath: string, options?: any): Promise<any>;
+}
+export declare function createFS(vfs: VirtualFileSystem): FSCompat;
+export {};