@soulcraft/brainy 6.1.0 → 6.2.1

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,84 @@
+/**
+ * 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';
+import { EntityManager, ManagedEntity } from './EntityManager.js';
+/**
+ * File operation event
+ */
+export interface FileEvent extends ManagedEntity {
+    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;
+    eventType?: string;
+}
+/**
+ * Event Recorder - Stores all file operations as searchable events
+ */
+export declare class EventRecorder extends EntityManager {
+    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,269 @@
+/**
+ * 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';
+import { EntityManager } from './EntityManager.js';
+/**
+ * Event Recorder - Stores all file operations as searchable events
+ */
+export class EventRecorder extends EntityManager {
+    constructor(brain) {
+        super(brain, 'vfs');
+    }
+    /**
+     * 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;
+        // Create file event
+        const fileEvent = {
+            id: eventId,
+            type: event.type,
+            path: event.path,
+            timestamp,
+            content: event.content,
+            size: event.size,
+            hash,
+            author: event.author,
+            metadata: event.metadata,
+            previousHash: event.previousHash,
+            oldPath: event.oldPath
+        };
+        // Generate embedding for content-based events
+        const embedding = event.content && event.content.length < 100000
+            ? await this.generateEventEmbedding(event)
+            : undefined;
+        // Add eventType for event classification
+        const eventWithType = {
+            ...fileEvent,
+            eventType: 'file-operation'
+        };
+        // Store event using EntityManager
+        await this.storeEntity(eventWithType, NounType.Event, embedding, event.content || Buffer.from(JSON.stringify(event)));
+        return eventId;
+    }
+    /**
+     * 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 using EntityManager
+        const events = await this.findEntities(query, NounType.Event, limit);
+        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 using EntityManager
+        const events = await this.findEntities(query, NounType.Event, options?.limit || 100);
+        // 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;
+        }
+        // Query using EntityManager
+        const events = await this.findEntities(query, NounType.Event, 1000);
+        return events.map(event => ({
+            id: event.id,
+            type: event.type,
+            path: event.path,
+            timestamp: event.timestamp,
+            size: event.size,
+            hash: event.hash,
+            author: event.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.deleteEntity(events[i].id);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+}
+//# sourceMappingURL=EventRecorder.js.map