@soulcraft/brainy 3.20.1 → 3.20.3

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [3.20.2](https://github.com/soulcraftlabs/brainy/compare/v3.20.1...v3.20.2) (2025-09-30)
+
+### Bug Fixes
+
+* **vfs**: resolve VFS race conditions and decompression errors ([1a2661f](https://github.com/soulcraftlabs/brainy/commit/1a2661f))
+  - Fixes duplicate directory nodes caused by concurrent writes
+  - Fixes file read decompression errors caused by rawData compression state mismatch
+  - Adds mutex-based concurrency control for mkdir operations
+  - Adds explicit compression tracking for file reads
+
+### BREAKING CHANGES (Deprecated API Removal)
+
+* **removed BrainyData**: The deprecated `BrainyData` class has been completely removed
+  - `BrainyData` was never part of the official Brainy 3.0 API
+  - All users should migrate to the `Brainy` class
+  - Migration is simple: Replace `new BrainyData()` with `new Brainy()` and add `await brain.init()`
+  - See `.strategy/NEURAL_API_RESPONSE.md` for complete migration guide
+  - Renamed `brainyDataInterface.ts` to `brainyInterface.ts` for clarity
+
 ### [3.19.1](https://github.com/soulcraftlabs/brainy/compare/v3.19.0...v3.19.1) (2025-09-29)
 
 ## [3.19.0](https://github.com/soulcraftlabs/brainy/compare/v3.18.0...v3.19.0) (2025-09-29)

package/bin/brainy-interactive.js

@@ -7,7 +7,7 @@
  */
 
 import { program } from 'commander'
-import { BrainyData } from '../dist/brainyData.js'
+import { Brainy } from '../dist/index.js'
 import chalk from 'chalk'
 import inquirer from 'inquirer'
 import ora from 'ora'
@@ -61,7 +61,7 @@ async function getBrainy() {
   if (!brainyInstance) {
     const spinner = ora('Initializing Brainy...').start()
     try {
-      brainyInstance = new BrainyData()
+      brainyInstance = new Brainy()
       await brainyInstance.init()
       spinner.succeed('Brainy initialized')
     } catch (error) {

package/dist/brainy.d.ts

@@ -12,7 +12,7 @@ import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js';
 import { VirtualFileSystem } from './vfs/VirtualFileSystem.js';
 import { Entity, Relation, Result, AddParams, UpdateParams, RelateParams, FindParams, SimilarParams, GetRelationsParams, AddManyParams, DeleteManyParams, RelateManyParams, BatchResult, BrainyConfig } from './types/brainy.types.js';
 import { NounType } from './types/graphTypes.js';
-import { BrainyInterface } from './types/brainyDataInterface.js';
+import { BrainyInterface } from './types/brainyInterface.js';
 /**
  * The main Brainy class - Clean, Beautiful, Powerful
  * REAL IMPLEMENTATION - No stubs, no mocks

package/dist/mcp/brainyMCPAdapter.d.ts

@@ -5,7 +5,7 @@
  * It wraps a Brainy instance and exposes methods for getting vectors, searching similar items,
  * and getting relationships.
  */
-import { BrainyInterface } from '../types/brainyDataInterface.js';
+import { BrainyInterface } from '../types/brainyInterface.js';
 import { MCPResponse, MCPDataAccessRequest } from '../types/mcpTypes.js';
 export declare class BrainyMCPAdapter {
     private brainyData;

package/dist/mcp/brainyMCPService.d.ts

@@ -6,7 +6,7 @@
  * MCPAugmentationToolset classes and provides WebSocket and REST server implementations
  * for external model access.
  */
-import { BrainyInterface } from '../types/brainyDataInterface.js';
+import { BrainyInterface } from '../types/brainyInterface.js';
 import { MCPRequest, MCPResponse, MCPServiceOptions } from '../types/mcpTypes.js';
 export declare class BrainyMCPService {
     private dataAdapter;

package/dist/neural/embeddedPatterns.d.ts

@@ -2,7 +2,7 @@
  * 🧠 BRAINY EMBEDDED PATTERNS
  *
  * AUTO-GENERATED - DO NOT EDIT
- * Generated: 2025-09-29T17:05:30.153Z
+ * Generated: 2025-09-30T23:01:33.167Z
  * Patterns: 220
  * Coverage: 94-98% of all queries
  *

package/dist/neural/embeddedPatterns.js

@@ -2,7 +2,7 @@
  * 🧠 BRAINY EMBEDDED PATTERNS
  *
  * AUTO-GENERATED - DO NOT EDIT
- * Generated: 2025-09-29T17:05:30.153Z
+ * Generated: 2025-09-30T23:01:33.167Z
  * Patterns: 220
  * Coverage: 94-98% of all queries
  *

package/dist/shared/default-augmentations.d.ts

@@ -4,7 +4,7 @@
  * 🧠⚛️ Pre-installed augmentations that come with every Brainy installation
  * These are the core "sensory organs" of the atomic age brain-in-jar system
  */
-import { BrainyInterface } from '../types/brainyDataInterface.js';
+import { BrainyInterface } from '../types/brainyInterface.js';
 /**
  * Default augmentations that ship with Brainy
  * These are automatically registered on startup

package/dist/types/{brainyDataInterface.js → brainyInterface.js}

@@ -7,4 +7,4 @@
  * NO DEPRECATED METHODS - Only clean, modern API patterns.
  */
 export {};
-//# sourceMappingURL=brainyDataInterface.js.map
+//# sourceMappingURL=brainyInterface.js.map

package/dist/vfs/VirtualFileSystem.d.ts

@@ -28,6 +28,7 @@ export declare class VirtualFileSystem implements IVirtualFileSystem {
     private statCache;
     private watchers;
     private backgroundTimer;
+    private mkdirLocks;
     constructor(brain?: Brainy);
     /**
      * Initialize the VFS

package/dist/vfs/VirtualFileSystem.js

@@ -25,6 +25,8 @@ export class VirtualFileSystem {
         this.currentUser = 'system'; // Track current user for collaboration
         // Background task timer
         this.backgroundTimer = null;
+        // Mutex for preventing race conditions in directory creation
+        this.mkdirLocks = new Map();
         this.brain = brain || new Brainy();
         this.contentCache = new Map();
         this.statCache = new Map();
@@ -159,16 +161,20 @@ export class VirtualFileSystem {
         }
         // Get content based on storage type
         let content;
+        let isCompressed = false;
         if (!entity.metadata.storage || entity.metadata.storage.type === 'inline') {
             // Content stored in metadata for new files, or try entity data for compatibility
             if (entity.metadata.rawData) {
+                // rawData is ALWAYS stored uncompressed as base64
                 content = Buffer.from(entity.metadata.rawData, 'base64');
+                isCompressed = false; // rawData is never compressed
             }
             else if (!entity.data) {
                 content = Buffer.alloc(0);
             }
             else if (Buffer.isBuffer(entity.data)) {
                 content = entity.data;
+                isCompressed = entity.metadata.storage?.compressed || false;
             }
             else if (typeof entity.data === 'string') {
                 content = Buffer.from(entity.data);
@@ -180,16 +186,18 @@ export class VirtualFileSystem {
         else if (entity.metadata.storage.type === 'reference') {
             // Content stored in external storage
             content = await this.readExternalContent(entity.metadata.storage.key);
+            isCompressed = entity.metadata.storage.compressed || false;
         }
         else if (entity.metadata.storage.type === 'chunked') {
             // Content stored in chunks
             content = await this.readChunkedContent(entity.metadata.storage.chunks);
+            isCompressed = entity.metadata.storage.compressed || false;
         }
         else {
             throw new VFSError(VFSErrorCode.EIO, `Unknown storage type: ${entity.metadata.storage.type}`, path, 'readFile');
         }
-        // Decompress if needed
-        if (entity.metadata.storage?.compressed && options?.decompress !== false) {
+        // Decompress if needed (but NOT for rawData which is never compressed)
+        if (isCompressed && options?.decompress !== false) {
             content = await this.decompress(content);
         }
         // Update access time
@@ -317,7 +325,7 @@ export class VirtualFileSystem {
                 type: this.getFileNounType(mimeType),
                 metadata
             });
-            // Create parent-child relationship
+            // Create parent-child relationship (no need to check for duplicates on new entities)
             await this.brain.relate({
                 from: parentId,
                 to: entity,
@@ -498,78 +506,106 @@ export class VirtualFileSystem {
      */
     async mkdir(path, options) {
         await this.ensureInitialized();
-        // Check if already exists
-        try {
-            const existing = await this.pathResolver.resolve(path);
-            const entity = await this.getEntityById(existing);
-            if (entity.metadata.vfsType === 'directory') {
-                if (!options?.recursive) {
-                    throw new VFSError(VFSErrorCode.EEXIST, `Directory exists: ${path}`, path, 'mkdir');
+        // Use mutex to prevent race conditions when creating the same directory concurrently
+        // If another call is already creating this directory, wait for it to complete
+        const existingLock = this.mkdirLocks.get(path);
+        if (existingLock) {
+            await existingLock;
+            // After waiting, check if directory now exists
+            try {
+                const existing = await this.pathResolver.resolve(path);
+                const entity = await this.getEntityById(existing);
+                if (entity.metadata.vfsType === 'directory') {
+                    return; // Directory was created by the other call
                 }
-                return; // Already exists and recursive is true
             }
-            else {
-                // Path exists but it's not a directory
-                throw new VFSError(VFSErrorCode.EEXIST, `File exists: ${path}`, path, 'mkdir');
-            }
-        }
-        catch (err) {
-            // Only proceed if it's a ENOENT error (path doesn't exist)
-            if (err instanceof VFSError && err.code !== VFSErrorCode.ENOENT) {
-                throw err; // Re-throw non-ENOENT errors
+            catch (err) {
+                // Still doesn't exist, proceed to create
             }
-            // Doesn't exist, proceed to create
         }
-        // Parse path
-        const parentPath = this.getParentPath(path);
-        const name = this.getBasename(path);
-        // Ensure parent exists (recursive mkdir if needed)
-        let parentId;
-        if (parentPath === '/' || parentPath === null) {
-            parentId = this.rootEntityId;
-        }
-        else if (options?.recursive) {
-            parentId = await this.ensureDirectory(parentPath);
-        }
-        else {
+        // Create a lock promise for this path
+        let resolveLock;
+        const lockPromise = new Promise(resolve => { resolveLock = resolve; });
+        this.mkdirLocks.set(path, lockPromise);
+        try {
+            // Check if already exists
             try {
-                parentId = await this.pathResolver.resolve(parentPath);
+                const existing = await this.pathResolver.resolve(path);
+                const entity = await this.getEntityById(existing);
+                if (entity.metadata.vfsType === 'directory') {
+                    if (!options?.recursive) {
+                        throw new VFSError(VFSErrorCode.EEXIST, `Directory exists: ${path}`, path, 'mkdir');
+                    }
+                    return; // Already exists and recursive is true
+                }
+                else {
+                    // Path exists but it's not a directory
+                    throw new VFSError(VFSErrorCode.EEXIST, `File exists: ${path}`, path, 'mkdir');
+                }
             }
             catch (err) {
-                throw new VFSError(VFSErrorCode.ENOENT, `Parent directory not found: ${parentPath}`, path, 'mkdir');
+                // Only proceed if it's a ENOENT error (path doesn't exist)
+                if (err instanceof VFSError && err.code !== VFSErrorCode.ENOENT) {
+                    throw err; // Re-throw non-ENOENT errors
+                }
+                // Doesn't exist, proceed to create
             }
-        }
-        // Create directory entity
-        const metadata = {
-            path,
-            name,
-            parent: parentId,
-            vfsType: 'directory',
-            size: 0,
-            permissions: options?.mode || this.config.permissions?.defaultDirectory || 0o755,
-            owner: 'user',
-            group: 'users',
-            accessed: Date.now(),
-            modified: Date.now(),
-            ...options?.metadata
-        };
-        const entity = await this.brain.add({
-            data: path, // Directory path as string content
-            type: NounType.Collection,
-            metadata
-        });
-        // Create parent-child relationship
-        if (parentId !== entity) { // Don't relate to self (root)
-            await this.brain.relate({
-                from: parentId,
-                to: entity,
-                type: VerbType.Contains
+            // Parse path
+            const parentPath = this.getParentPath(path);
+            const name = this.getBasename(path);
+            // Ensure parent exists (recursive mkdir if needed)
+            let parentId;
+            if (parentPath === '/' || parentPath === null) {
+                parentId = this.rootEntityId;
+            }
+            else if (options?.recursive) {
+                parentId = await this.ensureDirectory(parentPath);
+            }
+            else {
+                try {
+                    parentId = await this.pathResolver.resolve(parentPath);
+                }
+                catch (err) {
+                    throw new VFSError(VFSErrorCode.ENOENT, `Parent directory not found: ${parentPath}`, path, 'mkdir');
+                }
+            }
+            // Create directory entity
+            const metadata = {
+                path,
+                name,
+                parent: parentId,
+                vfsType: 'directory',
+                size: 0,
+                permissions: options?.mode || this.config.permissions?.defaultDirectory || 0o755,
+                owner: 'user',
+                group: 'users',
+                accessed: Date.now(),
+                modified: Date.now(),
+                ...options?.metadata
+            };
+            const entity = await this.brain.add({
+                data: path, // Directory path as string content
+                type: NounType.Collection,
+                metadata
             });
+            // Create parent-child relationship (no need to check for duplicates on new entities)
+            if (parentId !== entity) { // Don't relate to self (root)
+                await this.brain.relate({
+                    from: parentId,
+                    to: entity,
+                    type: VerbType.Contains
+                });
+            }
+            // Update path resolver cache
+            await this.pathResolver.createPath(path, entity);
+            // Trigger watchers
+            this.triggerWatchers(path, 'rename');
+        }
+        finally {
+            // Release the lock
+            resolveLock();
+            this.mkdirLocks.delete(path);
         }
-        // Update path resolver cache
-        await this.pathResolver.createPath(path, entity);
-        // Trigger watchers
-        this.triggerWatchers(path, 'rename');
     }
     /**
      * Remove a directory
@@ -1964,17 +2000,20 @@ export class VirtualFileSystem {
         };
         let earliestModified = null;
         let latestModified = null;
-        const traverse = async (currentPath) => {
+        const traverse = async (currentPath, isRoot = false) => {
             try {
                 const entityId = await this.pathResolver.resolve(currentPath);
                 const entity = await this.getEntityById(entityId);
                 if (entity.metadata.vfsType === 'directory') {
-                    stats.directoryCount++;
+                    // Don't count the root/starting directory itself
+                    if (!isRoot) {
+                        stats.directoryCount++;
+                    }
                     // Traverse children
                     const children = await this.readdir(currentPath);
                     for (const child of children) {
                         const childPath = currentPath === '/' ? `/${child}` : `${currentPath}/${child}`;
-                        await traverse(childPath);
+                        await traverse(childPath, false);
                     }
                 }
                 else if (entity.metadata.vfsType === 'file') {
@@ -2005,7 +2044,7 @@ export class VirtualFileSystem {
                 // Skip if path doesn't exist
             }
         };
-        await traverse(path);
+        await traverse(path, true);
         // Calculate averages
         if (stats.fileCount > 0) {
             stats.averageFileSize = Math.round(stats.totalSize / stats.fileCount);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.20.1",
+  "version": "3.20.3",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/dist/augmentationFactory.d.ts

@@ -1,86 +0,0 @@
-/**
- * Augmentation Factory
- *
- * This module provides a simplified factory for creating augmentations with minimal boilerplate.
- * It reduces the complexity of creating and using augmentations by providing a fluent API
- * and handling common patterns automatically.
- */
-import { IAugmentation, AugmentationResponse, ISenseAugmentation, IConduitAugmentation, IMemoryAugmentation, IWebSocketSupport, WebSocketConnection } from './types/augmentations.js';
-/**
- * Options for creating an augmentation
- */
-export interface AugmentationOptions {
-    name: string;
-    description?: string;
-    enabled?: boolean;
-    autoRegister?: boolean;
-    autoInitialize?: boolean;
-}
-/**
- * Factory for creating sense augmentations
- */
-export declare function createSenseAugmentation(options: AugmentationOptions & {
-    processRawData?: (rawData: Buffer | string, dataType: string) => Promise<AugmentationResponse<{
-        nouns: string[];
-        verbs: string[];
-    }>> | AugmentationResponse<{
-        nouns: string[];
-        verbs: string[];
-    }>;
-    listenToFeed?: (feedUrl: string, callback: (data: {
-        nouns: string[];
-        verbs: string[];
-    }) => void) => Promise<void>;
-}): ISenseAugmentation;
-/**
- * Factory for creating conduit augmentations
- */
-export declare function createConduitAugmentation(options: AugmentationOptions & {
-    establishConnection?: (targetSystemId: string, config: Record<string, unknown>) => Promise<AugmentationResponse<WebSocketConnection>> | AugmentationResponse<WebSocketConnection>;
-    readData?: (query: Record<string, unknown>, options?: Record<string, unknown>) => Promise<AugmentationResponse<unknown>> | AugmentationResponse<unknown>;
-    writeData?: (data: Record<string, unknown>, options?: Record<string, unknown>) => Promise<AugmentationResponse<unknown>> | AugmentationResponse<unknown>;
-    monitorStream?: (streamId: string, callback: (data: unknown) => void) => Promise<void>;
-}): IConduitAugmentation;
-/**
- * Factory for creating memory augmentations
- */
-export declare function createMemoryAugmentation(options: AugmentationOptions & {
-    storeData?: (key: string, data: unknown, options?: Record<string, unknown>) => Promise<AugmentationResponse<boolean>> | AugmentationResponse<boolean>;
-    retrieveData?: (key: string, options?: Record<string, unknown>) => Promise<AugmentationResponse<unknown>> | AugmentationResponse<unknown>;
-    updateData?: (key: string, data: unknown, options?: Record<string, unknown>) => Promise<AugmentationResponse<boolean>> | AugmentationResponse<boolean>;
-    deleteData?: (key: string, options?: Record<string, unknown>) => Promise<AugmentationResponse<boolean>> | AugmentationResponse<boolean>;
-    listDataKeys?: (pattern?: string, options?: Record<string, unknown>) => Promise<AugmentationResponse<string[]>> | AugmentationResponse<string[]>;
-    search?: (query: unknown, k?: number, options?: Record<string, unknown>) => Promise<AugmentationResponse<Array<{
-        id: string;
-        score: number;
-        data: unknown;
-    }>>> | AugmentationResponse<Array<{
-        id: string;
-        score: number;
-        data: unknown;
-    }>>;
-}): IMemoryAugmentation;
-/**
- * Factory for creating WebSocket-enabled augmentations
- * This can be combined with other augmentation factories to create WebSocket-enabled versions
- */
-export declare function addWebSocketSupport<T extends IAugmentation>(augmentation: T, options: {
-    connectWebSocket?: (url: string, protocols?: string | string[]) => Promise<WebSocketConnection>;
-    sendWebSocketMessage?: (connectionId: string, data: unknown) => Promise<void>;
-    onWebSocketMessage?: (connectionId: string, callback: (data: unknown) => void) => Promise<void>;
-    offWebSocketMessage?: (connectionId: string, callback: (data: unknown) => void) => Promise<void>;
-    closeWebSocket?: (connectionId: string, code?: number, reason?: string) => Promise<void>;
-}): T & IWebSocketSupport;
-/**
- * Simplified function to execute an augmentation method with automatic error handling
- * This provides a more concise way to execute augmentation methods compared to the full pipeline
- */
-export declare function executeAugmentation<T, R>(augmentation: IAugmentation, method: string, ...args: any[]): Promise<AugmentationResponse<R>>;
-/**
- * Dynamically load augmentations from a module at runtime
- * This allows for lazy-loading augmentations when needed instead of at build time
- */
-export declare function loadAugmentationModule(modulePromise: Promise<any>, options?: {
-    autoRegister?: boolean;
-    autoInitialize?: boolean;
-}): Promise<IAugmentation[]>;