@soulcraft/brainy 5.8.0 → 5.10.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 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.
 
+### [5.9.0](https://github.com/soulcraftlabs/brainy/compare/v5.8.0...v5.9.0) (2025-11-14)
+
+- fix: resolve VFS tree corruption from blob errors (v5.8.0) (93d2d70)
+
+
 ### [5.8.0](https://github.com/soulcraftlabs/brainy/compare/v5.7.13...v5.8.0) (2025-11-14)
 
 - feat: add v5.8.0 features - transactions, pagination, and comprehensive docs (e40fee3)

package/dist/augmentations/intelligentImport/handlers/imageHandler.d.ts

@@ -1,13 +1,13 @@
 /**
- * Image Import Handler (v5.2.0)
+ * Image Import Handler (v5.8.0 - Pure JavaScript)
  *
  * Handles image files with:
- * - EXIF metadata extraction (camera, GPS, timestamps)
- * - Thumbnail generation (multiple sizes)
- * - Image metadata (dimensions, format, color space)
- * - Support for JPEG, PNG, WebP, GIF, TIFF, AVIF, etc.
+ * - EXIF metadata extraction (camera, GPS, timestamps) via exifr
+ * - Image metadata (dimensions, format) via probe-image-size
+ * - Support for JPEG, PNG, WebP, GIF, TIFF, BMP, SVG
  *
- * NO MOCKS - Production implementation using sharp and exifr
+ * NO NATIVE DEPENDENCIES - Pure JavaScript implementation
+ * Replaces Sharp (v5.7.x) with lightweight pure-JS alternatives
  */
 import { BaseFormatHandler } from './base.js';
 import type { FormatHandlerOptions, ProcessedData } from '../types.js';
@@ -17,18 +17,12 @@ export interface ImageMetadata {
     height: number;
     /** Image format (jpeg, png, webp, etc.) */
     format: string;
-    /** Color space */
-    space: string;
-    /** Number of channels */
-    channels: number;
-    /** Bit depth */
-    depth: string;
     /** File size in bytes */
     size: number;
-    /** Whether image has alpha channel */
-    hasAlpha: boolean;
     /** Orientation (EXIF) */
     orientation?: number;
+    /** MIME type */
+    mimeType?: string;
 }
 export interface EXIFData {
     /** Camera make (e.g., "Canon", "Nikon") */
@@ -74,6 +68,8 @@ export interface ImageHandlerOptions extends FormatHandlerOptions {
  * Processes image files and extracts rich metadata including EXIF data.
  * Enables developers to import images into the knowledge graph with
  * full metadata extraction.
+ *
+ * v5.8.0: Pure JavaScript implementation (no native dependencies)
  */
 export declare class ImageHandler extends BaseFormatHandler {
     readonly format = "image";
@@ -89,11 +85,11 @@ export declare class ImageHandler extends BaseFormatHandler {
      */
     process(data: Buffer | string, options?: ImageHandlerOptions): Promise<ProcessedData>;
     /**
-     * Extract image metadata using sharp
+     * Extract image metadata using probe-image-size (pure JS)
      */
     private extractMetadata;
     /**
-     * Extract EXIF data using exifr
+     * Extract EXIF data using exifr (pure JS)
      */
     private extractEXIF;
     /**

package/dist/augmentations/intelligentImport/handlers/imageHandler.js

@@ -1,23 +1,26 @@
 /**
- * Image Import Handler (v5.2.0)
+ * Image Import Handler (v5.8.0 - Pure JavaScript)
  *
  * Handles image files with:
- * - EXIF metadata extraction (camera, GPS, timestamps)
- * - Thumbnail generation (multiple sizes)
- * - Image metadata (dimensions, format, color space)
- * - Support for JPEG, PNG, WebP, GIF, TIFF, AVIF, etc.
+ * - EXIF metadata extraction (camera, GPS, timestamps) via exifr
+ * - Image metadata (dimensions, format) via probe-image-size
+ * - Support for JPEG, PNG, WebP, GIF, TIFF, BMP, SVG
  *
- * NO MOCKS - Production implementation using sharp and exifr
+ * NO NATIVE DEPENDENCIES - Pure JavaScript implementation
+ * Replaces Sharp (v5.7.x) with lightweight pure-JS alternatives
  */
 import { BaseFormatHandler } from './base.js';
-import sharp from 'sharp';
 import exifr from 'exifr';
+import probeImageSize from 'probe-image-size';
+import { Readable } from 'stream';
 /**
  * ImageImportHandler
  *
  * Processes image files and extracts rich metadata including EXIF data.
  * Enables developers to import images into the knowledge graph with
  * full metadata extraction.
+ *
+ * v5.8.0: Pure JavaScript implementation (no native dependencies)
  */
 export class ImageHandler extends BaseFormatHandler {
     constructor() {
@@ -93,25 +96,36 @@ export class ImageHandler extends BaseFormatHandler {
         }
     }
     /**
-     * Extract image metadata using sharp
+     * Extract image metadata using probe-image-size (pure JS)
      */
     async extractMetadata(buffer) {
-        const image = sharp(buffer);
-        const metadata = await image.metadata();
-        return {
-            width: metadata.width || 0,
-            height: metadata.height || 0,
-            format: metadata.format || 'unknown',
-            space: metadata.space || 'unknown',
-            channels: metadata.channels || 0,
-            depth: metadata.depth || 'unknown',
-            size: buffer.length,
-            hasAlpha: metadata.hasAlpha || false,
-            orientation: metadata.orientation
-        };
+        try {
+            // Convert Buffer to Stream for probe-image-size
+            const stream = Readable.from(buffer);
+            const result = await probeImageSize(stream);
+            return {
+                width: result.width,
+                height: result.height,
+                format: result.type, // 'jpeg', 'png', 'webp', etc.
+                size: buffer.length,
+                mimeType: result.mime,
+                orientation: result.orientation
+            };
+        }
+        catch (error) {
+            // Fallback: Try to detect format from magic bytes
+            const detectedFormat = this.detectImageFormat(buffer);
+            return {
+                width: 0,
+                height: 0,
+                format: detectedFormat || 'unknown',
+                size: buffer.length,
+                mimeType: detectedFormat ? `image/${detectedFormat}` : undefined
+            };
+        }
     }
     /**
-     * Extract EXIF data using exifr
+     * Extract EXIF data using exifr (pure JS)
      */
     async extractEXIF(buffer) {
         try {
@@ -199,6 +213,10 @@ export class ImageHandler extends BaseFormatHandler {
             (buffer[0] === 0x4d && buffer[1] === 0x4d && buffer[2] === 0x00 && buffer[3] === 0x2a)) {
             return 'tiff';
         }
+        // BMP: 42 4D
+        if (buffer[0] === 0x42 && buffer[1] === 0x4d) {
+            return 'bmp';
+        }
         return null;
     }
     /**

package/dist/vfs/VirtualFileSystem.d.ts

@@ -29,6 +29,8 @@ export declare class VirtualFileSystem implements IVirtualFileSystem {
     private watchers;
     private backgroundTimer;
     private mkdirLocks;
+    private rootInitPromise;
+    private static readonly VFS_ROOT_ID;
     constructor(brain?: Brainy);
     /**
      * v5.2.0: Access to BlobStorage for unified file storage
@@ -46,7 +48,32 @@ export declare class VirtualFileSystem implements IVirtualFileSystem {
      * Zero-config: All semantic dimensions work out of the box
      */
     private registerBuiltInProjections;
+    /**
+     * v5.8.0: CRITICAL FIX - Prevent duplicate root creation
+     * Uses singleton promise pattern to ensure only ONE root initialization
+     * happens even with concurrent init() calls
+     */
     private initializeRoot;
+    /**
+     * v5.10.0: Atomic root initialization with fixed ID
+     * Uses deterministic ID to prevent duplicates across all VFS instances
+     *
+     * ARCHITECTURAL FIX: Instead of query-then-create (race condition),
+     * we use a fixed ID so storage-level uniqueness prevents duplicates.
+     */
+    private doInitializeRoot;
+    /**
+     * v5.10.0: Get standard root metadata
+     * Centralized to ensure consistency
+     */
+    private getRootMetadata;
+    /**
+     * v5.10.0: Cleanup old UUID-based VFS roots (migration from v5.9.0)
+     * Called during init to remove duplicate roots created before fixed-ID fix
+     *
+     * This is a one-time migration helper that can be removed in future versions.
+     */
+    private cleanupOldRoots;
     /**
      * Read a file's content
      */

package/dist/vfs/VirtualFileSystem.js

@@ -28,6 +28,8 @@ export class VirtualFileSystem {
         this.backgroundTimer = null;
         // Mutex for preventing race conditions in directory creation
         this.mkdirLocks = new Map();
+        // v5.8.0: Singleton promise for root initialization (prevents duplicate roots)
+        this.rootInitPromise = null;
         this.brain = brain || new Brainy();
         this.contentCache = new Map();
         this.statCache = new Map();
@@ -59,6 +61,8 @@ export class VirtualFileSystem {
         // Removed brain.init() check to prevent infinite recursion
         // Create or find root entity
         this.rootEntityId = await this.initializeRoot();
+        // v5.10.0: Clean up old UUID-based roots from v5.9.0 (one-time migration)
+        await this.cleanupOldRoots();
         // Initialize projection registry with auto-discovery of built-in projections
         this.projectionRegistry = new ProjectionRegistry();
         this.registerBuiltInProjections();
@@ -99,76 +103,140 @@ export class VirtualFileSystem {
             }
         }
     }
+    /**
+     * v5.8.0: CRITICAL FIX - Prevent duplicate root creation
+     * Uses singleton promise pattern to ensure only ONE root initialization
+     * happens even with concurrent init() calls
+     */
     async initializeRoot() {
-        // FIXED (v4.3.3): Use correct field names in where clause
-        // Metadata index stores flat fields: path, vfsType, name
-        // NOT nested: 'metadata.path', 'metadata.vfsType'
-        const existing = await this.brain.find({
-            type: NounType.Collection,
-            where: {
-                path: '/', // ✅ Correct field name
-                vfsType: 'directory' // ✅ Correct field name
-            },
-            limit: 10
-        });
-        if (existing.length > 0) {
-            // Handle duplicate roots (Workshop team reported ~10 duplicates!)
-            if (existing.length > 1) {
-                console.warn(`⚠️  Found ${existing.length} root entities! Using first one, consider cleanup.`);
-                // Sort by creation time - use oldest root (most likely to have children)
-                // v4.5.3: FIX - createdAt is in entity object, not at Result level!
-                // brain.find() returns Result[], which has entity.createdAt, not top-level createdAt
-                existing.sort((a, b) => {
-                    const aTime = a.entity?.createdAt || a.metadata?.modified || 0;
-                    const bTime = b.entity?.createdAt || b.metadata?.modified || 0;
-                    return aTime - bTime;
-                });
+        // If initialization already in progress, wait for it (automatic mutex)
+        if (this.rootInitPromise) {
+            return await this.rootInitPromise;
+        }
+        // Start initialization and cache the promise
+        this.rootInitPromise = this.doInitializeRoot();
+        try {
+            const rootId = await this.rootInitPromise;
+            return rootId;
+        }
+        catch (error) {
+            // On error, clear promise so retry is possible
+            this.rootInitPromise = null;
+            throw error;
+        }
+        // NOTE: On success, we intentionally keep the promise cached
+        // This prevents re-initialization and serves as a cache
+    }
+    /**
+     * v5.10.0: Atomic root initialization with fixed ID
+     * Uses deterministic ID to prevent duplicates across all VFS instances
+     *
+     * ARCHITECTURAL FIX: Instead of query-then-create (race condition),
+     * we use a fixed ID so storage-level uniqueness prevents duplicates.
+     */
+    async doInitializeRoot() {
+        const rootId = VirtualFileSystem.VFS_ROOT_ID;
+        // Try to get existing root by fixed ID (O(1) lookup, not query)
+        try {
+            const existingRoot = await this.brain.get(rootId);
+            if (existingRoot) {
+                // Root exists - verify metadata is correct
+                const metadata = existingRoot.metadata || existingRoot;
+                if (!metadata.vfsType || metadata.vfsType !== 'directory') {
+                    console.warn('⚠️  VFS: Root metadata incomplete, repairing...');
+                    await this.brain.update({
+                        id: rootId,
+                        metadata: this.getRootMetadata()
+                    });
+                }
+                return rootId;
             }
-            const rootEntity = existing[0];
-            // Ensure the root entity has proper metadata structure
-            const entityMetadata = rootEntity.metadata || rootEntity;
-            if (!entityMetadata.vfsType) {
-                // Update the root entity with proper metadata
-                await this.brain.update({
-                    id: rootEntity.id,
-                    metadata: {
-                        path: '/',
-                        name: '',
-                        vfsType: 'directory',
-                        isVFS: true, // v4.3.3: Mark as VFS entity (internal)
-                        isVFSEntity: true, // v5.3.0: Explicit flag for developer filtering
-                        size: 0,
-                        permissions: 0o755,
-                        owner: 'root',
-                        group: 'root',
-                        accessed: Date.now(),
-                        modified: Date.now(),
-                        ...entityMetadata // Preserve any existing metadata
-                    }
-                });
+        }
+        catch (error) {
+            // Root doesn't exist yet - proceed to creation
+        }
+        // Create root with fixed ID (idempotent - fails gracefully if exists)
+        try {
+            console.log('VFS: Creating root directory (fixed ID: 00000000-0000-0000-0000-000000000000)');
+            await this.brain.add({
+                id: rootId, // Fixed ID - storage ensures uniqueness
+                data: '/',
+                type: NounType.Collection,
+                metadata: this.getRootMetadata()
+            });
+            return rootId;
+        }
+        catch (error) {
+            // If creation failed due to duplicate ID, another instance created it
+            // This is normal in concurrent scenarios - just return the fixed ID
+            const errorMsg = error?.message?.toLowerCase() || '';
+            if (errorMsg.includes('already exists') ||
+                errorMsg.includes('duplicate') ||
+                errorMsg.includes('eexist')) {
+                console.log('VFS: Root already created by another instance, using existing');
+                return rootId;
             }
-            return rootEntity.id;
+            // Unexpected error
+            throw error;
         }
-        // Create root directory (only if truly doesn't exist)
-        const root = await this.brain.add({
-            data: '/', // Root directory content as string
-            type: NounType.Collection,
-            metadata: {
-                path: '/',
-                name: '',
-                vfsType: 'directory',
-                isVFS: true, // v4.3.3: Mark as VFS entity (internal)
-                isVFSEntity: true, // v5.3.0: Explicit flag for developer filtering
-                size: 0,
-                permissions: 0o755,
-                owner: 'root',
-                group: 'root',
-                accessed: Date.now(),
-                modified: Date.now(),
-                createdAt: Date.now() // Track creation time for duplicate detection
+    }
+    /**
+     * v5.10.0: Get standard root metadata
+     * Centralized to ensure consistency
+     */
+    getRootMetadata() {
+        return {
+            path: '/',
+            name: '',
+            vfsType: 'directory',
+            isVFS: true,
+            isVFSEntity: true,
+            size: 0,
+            permissions: 0o755,
+            owner: 'root',
+            group: 'root',
+            accessed: Date.now(),
+            modified: Date.now()
+        };
+    }
+    /**
+     * v5.10.0: Cleanup old UUID-based VFS roots (migration from v5.9.0)
+     * Called during init to remove duplicate roots created before fixed-ID fix
+     *
+     * This is a one-time migration helper that can be removed in future versions.
+     */
+    async cleanupOldRoots() {
+        try {
+            // Find any old VFS roots with UUID-based IDs (not our fixed ID)
+            const oldRoots = await this.brain.find({
+                type: NounType.Collection,
+                where: {
+                    path: '/',
+                    vfsType: 'directory'
+                },
+                limit: 100,
+                excludeVFS: false
+            });
+            // Filter out our fixed-ID root
+            const duplicates = oldRoots.filter(r => r.id !== VirtualFileSystem.VFS_ROOT_ID);
+            if (duplicates.length > 0) {
+                console.log(`VFS: Found ${duplicates.length} old UUID-based root(s) from v5.9.0, cleaning up...`);
+                for (const duplicate of duplicates) {
+                    try {
+                        await this.brain.delete(duplicate.id);
+                        console.log(`VFS: Deleted old root ${duplicate.id.substring(0, 8)}`);
+                    }
+                    catch (error) {
+                        console.warn(`VFS: Failed to delete old root ${duplicate.id}:`, error);
+                    }
+                }
+                console.log('VFS: Cleanup complete - all old roots removed');
             }
-        });
-        return root;
+        }
+        catch (error) {
+            // Non-critical error - log and continue
+            console.warn('VFS: Cleanup of old roots failed (non-critical):', error);
+        }
     }
     // ============= File Operations =============
     /**
@@ -194,19 +262,30 @@ export class VirtualFileSystem {
         if (!entity.metadata.storage?.type || entity.metadata.storage.type !== 'blob') {
             throw new VFSError(VFSErrorCode.EIO, `File has no blob storage: ${path}. Requires v5.2.0+ storage format.`, path, 'readFile');
         }
-        // Read from BlobStorage (handles decompression automatically)
-        const content = await this.blobStorage.read(entity.metadata.storage.hash);
-        // Update access time
-        await this.updateAccessTime(entityId);
-        // Cache the content
-        if (options?.cache !== false) {
-            this.contentCache.set(path, { data: content, timestamp: Date.now() });
+        // v5.8.0: CRITICAL FIX - Isolate blob errors from VFS tree corruption
+        // Blob read errors MUST NOT cascade to VFS tree structure
+        try {
+            // Read from BlobStorage (handles decompression automatically)
+            const content = await this.blobStorage.read(entity.metadata.storage.hash);
+            // Update access time
+            await this.updateAccessTime(entityId);
+            // Cache the content
+            if (options?.cache !== false) {
+                this.contentCache.set(path, { data: content, timestamp: Date.now() });
+            }
+            // Apply encoding if requested
+            if (options?.encoding) {
+                return Buffer.from(content.toString(options.encoding));
+            }
+            return content;
         }
-        // Apply encoding if requested
-        if (options?.encoding) {
-            return Buffer.from(content.toString(options.encoding));
+        catch (blobError) {
+            // Blob error isolated - VFS tree structure remains intact
+            const errorMsg = blobError instanceof Error ? blobError.message : String(blobError);
+            console.error(`VFS: Cannot read blob for ${path}:`, errorMsg);
+            // Throw VFSError (not blob error) - prevents cascading corruption
+            throw new VFSError(VFSErrorCode.EIO, `File read failed: ${errorMsg}`, path, 'readFile');
         }
-        return content;
     }
     /**
      * Write a file
@@ -2050,4 +2129,7 @@ export class VirtualFileSystem {
         return await this.pathResolver.resolve(normalizedPath);
     }
 }
+// v5.10.0: Fixed VFS root ID (prevents duplicates across instances)
+// Uses deterministic UUID format for storage compatibility
+VirtualFileSystem.VFS_ROOT_ID = '00000000-0000-0000-0000-000000000000';
 //# sourceMappingURL=VirtualFileSystem.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.8.0",
+  "version": "5.10.0",
   "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",
@@ -161,7 +161,7 @@
     "@testcontainers/redis": "^11.5.1",
     "@types/mime": "^3.0.4",
     "@types/node": "^20.11.30",
-    "@types/sharp": "^0.31.1",
+    "@types/probe-image-size": "^7.2.5",
     "@types/uuid": "^10.0.0",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -196,9 +196,9 @@
     "mime": "^4.1.0",
     "ora": "^8.2.0",
     "pdfjs-dist": "^4.0.379",
+    "probe-image-size": "^7.2.3",
     "prompts": "^2.4.2",
     "roaring-wasm": "^1.1.0",
-    "sharp": "^0.33.5",
     "uuid": "^9.0.1",
     "ws": "^8.18.3",
     "xlsx": "^0.18.5"