@soulcraft/brainy 6.2.9 → 6.3.1

package/dist/versioning/VersionStorage.js

@@ -1,19 +1,18 @@
 /**
- * VersionStorage - Hybrid Storage for Entity Versions (v5.3.0)
+ * VersionStorage - Hybrid Storage for Entity Versions (v5.3.0, v6.3.0 fix)
  *
  * Implements content-addressable storage for entity versions:
  * - SHA-256 content hashing for deduplication
- * - Stores versions in .brainy/versions/ directory
+ * - Uses BaseStorage.saveMetadata/getMetadata for storage (v6.3.0)
  * - Integrates with COW commit system
  * - Space-efficient: Only stores unique content
  *
- * Storage structure:
- * .brainy/versions/
- *   ├── entities/
- *   │   └── {entityId}/
- *   │       └── {contentHash}.json  # Entity version data
- *   └── index/
- *       └── {entityId}.json         # Version index (managed by VersionIndex)
+ * Storage structure (v6.3.0):
+ * Version content is stored using system metadata keys:
+ *   __system_version_{entityId}_{contentHash}
+ *
+ * This integrates with BaseStorage's routing which places system keys
+ * in the _system/ directory, keeping version data separate from entities.
  *
  * NO MOCKS - Production implementation
  */
@@ -118,31 +117,34 @@ export class VersionStorage {
         await this.deleteVersionData(versionPath);
     }
     /**
-     * Get version storage path
+     * Get version storage key
+     *
+     * Uses __system_ prefix so BaseStorage routes to system storage (_system/ directory)
+     * This keeps version data separate from entity data.
      *
      * @param entityId Entity ID
      * @param contentHash Content hash
-     * @returns Storage path
+     * @returns Storage key for version content
      */
     getVersionPath(entityId, contentHash) {
-        return `versions/entities/${entityId}/${contentHash}.json`;
+        // v6.3.0: Use system-prefixed key for BaseStorage.saveMetadata/getMetadata
+        // BaseStorage recognizes __system_ prefix and routes to _system/ directory
+        return `__system_version_${entityId}_${contentHash}`;
     }
     /**
      * Check if content exists in storage
      *
-     * @param path Storage path
+     * @param key Storage key
      * @returns True if exists
      */
-    async contentExists(path) {
+    async contentExists(key) {
         try {
-            // Use storage adapter's exists check if available
+            // v6.3.0: Use getMetadata to check existence
             const adapter = this.brain.storageAdapter;
-            if (adapter && typeof adapter.exists === 'function') {
-                return await adapter.exists(path);
-            }
-            // Fallback: Try to read and catch error
-            await this.readVersionData(path);
-            return true;
+            if (!adapter)
+                return false;
+            const data = await adapter.getMetadata(key);
+            return data !== null;
         }
         catch {
             return false;
@@ -151,72 +153,54 @@ export class VersionStorage {
     /**
      * Write version data to storage
      *
-     * @param path Storage path
+     * @param key Storage key
      * @param entity Entity data
      */
-    async writeVersionData(path, entity) {
+    async writeVersionData(key, entity) {
         const adapter = this.brain.storageAdapter;
         if (!adapter) {
             throw new Error('Storage adapter not available');
         }
-        // Serialize entity data
-        const data = JSON.stringify(entity, null, 2);
-        // Write to storage using adapter
-        if (typeof adapter.writeFile === 'function') {
-            await adapter.writeFile(path, data);
-        }
-        else if (typeof adapter.set === 'function') {
-            await adapter.set(path, data);
-        }
-        else {
-            throw new Error('Storage adapter does not support write operations');
-        }
+        // v6.3.0: Use saveMetadata for storing version content
+        // The key is system-prefixed so it routes to _system/ directory
+        await adapter.saveMetadata(key, entity);
     }
     /**
      * Read version data from storage
      *
-     * @param path Storage path
+     * @param key Storage key
      * @returns Entity data
      */
-    async readVersionData(path) {
+    async readVersionData(key) {
         const adapter = this.brain.storageAdapter;
         if (!adapter) {
             throw new Error('Storage adapter not available');
         }
-        // Read from storage using adapter
-        let data;
-        if (typeof adapter.readFile === 'function') {
-            data = await adapter.readFile(path);
-        }
-        else if (typeof adapter.get === 'function') {
-            data = await adapter.get(path);
+        // v6.3.0: Use getMetadata for reading version content
+        const entity = await adapter.getMetadata(key);
+        if (!entity) {
+            throw new Error(`Version data not found: ${key}`);
         }
-        else {
-            throw new Error('Storage adapter does not support read operations');
-        }
-        // Parse entity data
-        return JSON.parse(data);
+        return entity;
     }
     /**
      * Delete version data from storage
      *
-     * @param path Storage path
+     * Note: Version content is content-addressed and immutable.
+     * Deleting the version index entry (via VersionIndex.removeVersion) is sufficient.
+     * The content may be shared with other versions (same contentHash).
+     *
+     * v6.3.0: We don't actually delete version content to avoid breaking
+     * other versions that may reference the same content hash.
+     * A separate garbage collection process could clean up unreferenced content.
+     *
+     * @param key Storage key (unused - kept for API compatibility)
      */
-    async deleteVersionData(path) {
-        const adapter = this.brain.storageAdapter;
-        if (!adapter) {
-            throw new Error('Storage adapter not available');
-        }
-        // Delete from storage using adapter
-        if (typeof adapter.deleteFile === 'function') {
-            await adapter.deleteFile(path);
-        }
-        else if (typeof adapter.delete === 'function') {
-            await adapter.delete(path);
-        }
-        else {
-            throw new Error('Storage adapter does not support delete operations');
-        }
+    async deleteVersionData(_key) {
+        // v6.3.0: Version content is content-addressed and may be shared.
+        // We don't delete it here to prevent breaking other versions.
+        // The version INDEX is deleted via VersionIndex.removeVersion().
+        // A GC process could clean up unreferenced content in the future.
     }
 }
 //# sourceMappingURL=VersionStorage.js.map

package/dist/vfs/PathResolver.d.ts

@@ -62,6 +62,12 @@ export declare class PathResolver {
      * Create a new path entry (for mkdir/writeFile)
      */
     createPath(path: string, entityId: string): Promise<void>;
+    /**
+     * Invalidate ALL caches (v6.3.0)
+     * Call this when switching branches (checkout), clearing data (clear), or forking
+     * This ensures no stale data from previous branch/state remains in cache
+     */
+    invalidateAllCaches(): void;
     /**
      * Invalidate cache entries for a path and its children
      * v6.2.9 FIX: Also invalidates UnifiedCache to prevent stale entity IDs

package/dist/vfs/PathResolver.js

@@ -252,6 +252,26 @@ export class PathResolver {
             this.parentCache.get(parentId).add(name);
         }
     }
+    /**
+     * Invalidate ALL caches (v6.3.0)
+     * Call this when switching branches (checkout), clearing data (clear), or forking
+     * This ensures no stale data from previous branch/state remains in cache
+     */
+    invalidateAllCaches() {
+        // Clear all local caches
+        this.pathCache.clear();
+        this.parentCache.clear();
+        this.hotPaths.clear();
+        // Clear all VFS entries from UnifiedCache
+        getGlobalCache().deleteByPrefix('vfs:path:');
+        // Reset statistics (optional but helpful for debugging)
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+        this.metadataIndexHits = 0;
+        this.metadataIndexMisses = 0;
+        this.graphTraversalFallbacks = 0;
+        prodLog.info('[PathResolver] All caches invalidated');
+    }
     /**
      * Invalidate cache entries for a path and its children
      * v6.2.9 FIX: Also invalidates UnifiedCache to prevent stale entity IDs

package/dist/vfs/semantic/SemanticPathResolver.d.ts

@@ -92,6 +92,12 @@ export declare class SemanticPathResolver {
      * Uses UnifiedCache's clear method
      */
     invalidateSemanticCache(): void;
+    /**
+     * Invalidate ALL caches (v6.3.0)
+     * Clears both traditional path cache AND semantic cache
+     * Call this when switching branches, clearing data, or forking
+     */
+    invalidateAllCaches(): void;
     /**
      * Cleanup resources
      */

package/dist/vfs/semantic/SemanticPathResolver.js

@@ -231,6 +231,17 @@ export class SemanticPathResolver {
     invalidateSemanticCache() {
         this.cache.clear();
     }
+    /**
+     * Invalidate ALL caches (v6.3.0)
+     * Clears both traditional path cache AND semantic cache
+     * Call this when switching branches, clearing data, or forking
+     */
+    invalidateAllCaches() {
+        // Clear traditional PathResolver caches (including UnifiedCache VFS entries)
+        this.pathResolver.invalidateAllCaches();
+        // Clear semantic cache
+        this.cache.clear();
+    }
     /**
      * Cleanup resources
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "6.2.9",
+  "version": "6.3.1",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/dist/augmentations/KnowledgeAugmentation.d.ts

@@ -1,40 +0,0 @@
-/**
- * Knowledge Layer Augmentation for VFS
- *
- * Adds intelligent features to VFS without modifying core functionality:
- * - Event recording for all operations
- * - Semantic versioning based on content changes
- * - Entity and concept extraction
- * - Git bridge for import/export
- *
- * This is a TRUE augmentation - VFS works perfectly without it
- */
-import { Brainy } from '../brainy.js';
-import { BaseAugmentation } from './brainyAugmentation.js';
-export declare class KnowledgeAugmentation extends BaseAugmentation {
-    name: string;
-    timing: 'after';
-    metadata: 'none';
-    operations: any;
-    priority: number;
-    constructor(config?: any);
-    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
-    private eventRecorder?;
-    private semanticVersioning?;
-    private entitySystem?;
-    private conceptSystem?;
-    private gitBridge?;
-    private originalMethods;
-    initialize(context: any): Promise<void>;
-    augment(brain: Brainy): Promise<void>;
-    /**
-     * Wrap a VFS method to add Knowledge Layer functionality
-     */
-    private wrapMethod;
-    /**
-     * Add Knowledge Layer methods to VFS
-     */
-    private addKnowledgeMethods;
-    private isSemanticChange;
-    cleanup(brain: Brainy): Promise<void>;
-}

package/dist/augmentations/KnowledgeAugmentation.js

@@ -1,251 +0,0 @@
-/**
- * Knowledge Layer Augmentation for VFS
- *
- * Adds intelligent features to VFS without modifying core functionality:
- * - Event recording for all operations
- * - Semantic versioning based on content changes
- * - Entity and concept extraction
- * - Git bridge for import/export
- *
- * This is a TRUE augmentation - VFS works perfectly without it
- */
-import { BaseAugmentation } from './brainyAugmentation.js';
-import { EventRecorder } from '../vfs/EventRecorder.js';
-import { SemanticVersioning } from '../vfs/SemanticVersioning.js';
-import { PersistentEntitySystem } from '../vfs/PersistentEntitySystem.js';
-import { ConceptSystem } from '../vfs/ConceptSystem.js';
-import { GitBridge } from '../vfs/GitBridge.js';
-export class KnowledgeAugmentation extends BaseAugmentation {
-    constructor(config = {}) {
-        super(config);
-        this.name = 'knowledge';
-        this.timing = 'after'; // Process after VFS operations
-        this.metadata = 'none'; // No metadata access needed
-        this.operations = []; // VFS-specific augmentation, no operation interception
-        this.priority = 100; // Run last
-        this.originalMethods = new Map();
-    }
-    async execute(operation, params, next) {
-        // Pass through - this augmentation works at VFS level, not operation level
-        return await next();
-    }
-    async initialize(context) {
-        await this.augment(context.brain);
-    }
-    async augment(brain) {
-        // Only augment if VFS exists
-        const vfs = brain.vfs?.();
-        if (!vfs) {
-            console.warn('KnowledgeAugmentation: VFS not found, skipping');
-            return;
-        }
-        // Initialize Knowledge Layer components
-        this.eventRecorder = new EventRecorder(brain);
-        this.semanticVersioning = new SemanticVersioning(brain);
-        this.entitySystem = new PersistentEntitySystem(brain);
-        this.conceptSystem = new ConceptSystem(brain);
-        this.gitBridge = new GitBridge(vfs, brain);
-        // Wrap VFS methods to add intelligence WITHOUT slowing them down
-        this.wrapMethod(vfs, 'writeFile', async (original, path, data, options) => {
-            // Call original first (stays fast)
-            const result = await original.call(vfs, path, data, options);
-            // Knowledge processing in background (non-blocking)
-            setImmediate(async () => {
-                try {
-                    // Record event
-                    if (this.eventRecorder) {
-                        await this.eventRecorder.recordEvent({
-                            type: 'write',
-                            path,
-                            content: data,
-                            size: data.length,
-                            author: options?.author || 'system'
-                        });
-                    }
-                    // Check for semantic versioning
-                    if (this.semanticVersioning) {
-                        const existingContent = await vfs.readFile(path).catch(() => null);
-                        const shouldVersion = existingContent && this.isSemanticChange(existingContent, data);
-                        if (shouldVersion) {
-                            await this.semanticVersioning.createVersion(path, data, {
-                                message: 'Automatic semantic version'
-                            });
-                        }
-                    }
-                    // Extract concepts
-                    if (this.conceptSystem && options?.extractConcepts !== false) {
-                        await this.conceptSystem.extractAndLinkConcepts(path, data);
-                    }
-                    // Extract entities
-                    if (this.entitySystem && options?.extractEntities !== false) {
-                        await this.entitySystem.extractEntities(data.toString('utf8'), data);
-                    }
-                }
-                catch (error) {
-                    // Knowledge Layer errors should not affect VFS operations
-                    console.debug('KnowledgeLayer background processing error:', error);
-                }
-            });
-            return result;
-        });
-        this.wrapMethod(vfs, 'unlink', async (original, path) => {
-            const result = await original.call(vfs, path);
-            // Record deletion event
-            setImmediate(async () => {
-                if (this.eventRecorder) {
-                    await this.eventRecorder.recordEvent({
-                        type: 'delete',
-                        path,
-                        author: 'system'
-                    });
-                }
-            });
-            return result;
-        });
-        this.wrapMethod(vfs, 'rename', async (original, oldPath, newPath) => {
-            const result = await original.call(vfs, oldPath, newPath);
-            // Record rename event
-            setImmediate(async () => {
-                if (this.eventRecorder) {
-                    await this.eventRecorder.recordEvent({
-                        type: 'rename',
-                        path: oldPath,
-                        metadata: { newPath },
-                        author: 'system'
-                    });
-                }
-            });
-            return result;
-        });
-        // Add Knowledge Layer methods to VFS
-        this.addKnowledgeMethods(vfs);
-        console.log('✨ Knowledge Layer augmentation enabled');
-    }
-    /**
-     * Wrap a VFS method to add Knowledge Layer functionality
-     */
-    wrapMethod(vfs, methodName, wrapper) {
-        const original = vfs[methodName];
-        if (!original)
-            return;
-        // Store original for cleanup
-        this.originalMethods.set(methodName, original);
-        // Replace with wrapped version
-        vfs[methodName] = async (...args) => {
-            return await wrapper(original, ...args);
-        };
-    }
-    /**
-     * Add Knowledge Layer methods to VFS
-     */
-    addKnowledgeMethods(vfs) {
-        // Event history
-        vfs.getHistory = async (path, options) => {
-            if (!this.eventRecorder)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.eventRecorder.getHistory(path, options);
-        };
-        vfs.reconstructAtTime = async (path, timestamp) => {
-            if (!this.eventRecorder)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.eventRecorder.reconstructFileAtTime(path, timestamp);
-        };
-        // Semantic versioning
-        vfs.getVersions = async (path) => {
-            if (!this.semanticVersioning)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.semanticVersioning.getVersions(path);
-        };
-        vfs.restoreVersion = async (path, versionId) => {
-            if (!this.semanticVersioning)
-                throw new Error('Knowledge Layer not initialized');
-            const version = await this.semanticVersioning.getVersion(path, versionId);
-            if (version) {
-                await vfs.writeFile(path, version);
-            }
-        };
-        // Entities
-        vfs.findEntity = async (query) => {
-            if (!this.entitySystem)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.entitySystem.findEntity(query);
-        };
-        vfs.getEntityAppearances = async (entityId) => {
-            if (!this.entitySystem)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.entitySystem.getEvolution(entityId);
-        };
-        // Concepts
-        vfs.getConcepts = async (path) => {
-            if (!this.conceptSystem)
-                throw new Error('Knowledge Layer not initialized');
-            const concepts = await this.conceptSystem.findConcepts({ manifestedIn: path });
-            return concepts;
-        };
-        vfs.getConceptGraph = async (options) => {
-            if (!this.conceptSystem)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.conceptSystem.getConceptGraph(options);
-        };
-        // Git bridge
-        vfs.exportToGit = async (vfsPath, gitPath) => {
-            if (!this.gitBridge)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.gitBridge.exportToGit(vfsPath, gitPath);
-        };
-        vfs.importFromGit = async (gitPath, vfsPath) => {
-            if (!this.gitBridge)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.gitBridge.importFromGit(gitPath, vfsPath);
-        };
-        // Temporal coupling
-        vfs.findTemporalCoupling = async (path, windowMs) => {
-            if (!this.eventRecorder)
-                throw new Error('Knowledge Layer not initialized');
-            return await this.eventRecorder.findTemporalCoupling(path, windowMs);
-        };
-    }
-    isSemanticChange(oldContent, newContent) {
-        // Simple heuristic - significant size change or different content
-        const oldStr = oldContent.toString('utf8');
-        const newStr = newContent.toString('utf8');
-        // Check for significant size change (>10%)
-        const sizeDiff = Math.abs(oldStr.length - newStr.length) / oldStr.length;
-        if (sizeDiff > 0.1)
-            return true;
-        // Check for structural changes (simplified)
-        const oldLines = oldStr.split('\n').filter(l => l.trim());
-        const newLines = newStr.split('\n').filter(l => l.trim());
-        // Different number of non-empty lines
-        return Math.abs(oldLines.length - newLines.length) > 5;
-    }
-    async cleanup(brain) {
-        const vfs = brain.vfs?.();
-        if (!vfs)
-            return;
-        // Restore original methods
-        for (const [methodName, original] of this.originalMethods) {
-            vfs[methodName] = original;
-        }
-        // Remove added methods
-        delete vfs.getHistory;
-        delete vfs.reconstructAtTime;
-        delete vfs.getVersions;
-        delete vfs.restoreVersion;
-        delete vfs.findEntity;
-        delete vfs.getEntityAppearances;
-        delete vfs.getConcepts;
-        delete vfs.getConceptGraph;
-        delete vfs.exportToGit;
-        delete vfs.importFromGit;
-        delete vfs.findTemporalCoupling;
-        // Clean up components
-        this.eventRecorder = undefined;
-        this.semanticVersioning = undefined;
-        this.entitySystem = undefined;
-        this.conceptSystem = undefined;
-        this.gitBridge = undefined;
-        console.log('Knowledge Layer augmentation removed');
-    }
-}
-//# sourceMappingURL=KnowledgeAugmentation.js.map

package/dist/importManager.d.ts

@@ -1,78 +0,0 @@
-/**
- * Import Manager - Comprehensive data import with intelligent type detection
- *
- * Handles multiple data sources:
- * - Direct data (objects, arrays)
- * - Files (JSON, CSV, text)
- * - URLs (fetch and parse)
- * - Streams (for large files)
- *
- * Uses NeuralImportAugmentation for intelligent processing
- */
-import { NounType } from './types/graphTypes.js';
-export interface ImportOptions {
-    source?: 'data' | 'file' | 'url' | 'auto';
-    format?: 'json' | 'csv' | 'text' | 'yaml' | 'auto';
-    batchSize?: number;
-    autoDetect?: boolean;
-    typeHint?: NounType;
-    extractRelationships?: boolean;
-    csvDelimiter?: string;
-    csvHeaders?: boolean;
-    parallel?: boolean;
-    maxConcurrency?: number;
-}
-export interface ImportResult {
-    success: boolean;
-    nouns: string[];
-    verbs: string[];
-    errors: string[];
-    stats: {
-        total: number;
-        imported: number;
-        failed: number;
-        relationships: number;
-    };
-}
-export declare class ImportManager {
-    private neuralImport;
-    private typeMatcher;
-    private brain;
-    constructor(brain: any);
-    /**
-     * Initialize the import manager
-     */
-    init(): Promise<void>;
-    /**
-     * Main import method - handles all sources
-     */
-    import(source: string | Buffer | any[] | any, options?: ImportOptions): Promise<ImportResult>;
-    /**
-     * Import from file
-     */
-    importFile(filePath: string, options?: ImportOptions): Promise<ImportResult>;
-    /**
-     * Import from URL
-     */
-    importUrl(url: string, options?: ImportOptions): Promise<ImportResult>;
-    /**
-     * Detect source type
-     */
-    private detectSourceType;
-    /**
-     * Detect format from file path
-     */
-    private detectFormatFromPath;
-    /**
-     * Read file
-     */
-    private readFile;
-    /**
-     * Fetch from URL
-     */
-    private fetchFromUrl;
-}
-/**
- * Create an import manager instance
- */
-export declare function createImportManager(brain: any): ImportManager;