@soulcraft/brainy 5.8.0 → 5.9.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,7 @@ export declare class VirtualFileSystem implements IVirtualFileSystem {
     private watchers;
     private backgroundTimer;
     private mkdirLocks;
+    private rootInitPromise;
     constructor(brain?: Brainy);
     /**
      * v5.2.0: Access to BlobStorage for unified file storage
@@ -46,7 +47,22 @@ 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.8.0: Actual root initialization logic
+     * Uses brain.find() with no caching to get consistent results
+     */
+    private doInitializeRoot;
+    /**
+     * v5.8.0: Smart root selection when duplicates exist
+     * Selects root with MOST children (not oldest) to preserve user data
+     */
+    private selectBestRoot;
     /**
      * 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();
@@ -99,77 +101,154 @@ 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({
+        // 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.8.0: Actual root initialization logic
+     * Uses brain.find() with no caching to get consistent results
+     */
+    async doInitializeRoot() {
+        // Query for existing roots using brain.find()
+        // Use higher limit and no cache to ensure we catch all roots
+        const roots = await this.brain.find({
             type: NounType.Collection,
             where: {
-                path: '/', // ✅ Correct field name
-                vfsType: 'directory' // ✅ Correct field name
+                path: '/',
+                vfsType: 'directory'
             },
-            limit: 10
+            limit: 50, // Higher limit to catch all possible duplicates
+            excludeVFS: false // CRITICAL: Don't exclude VFS entities!
         });
-        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;
-                });
-            }
-            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
+        if (roots.length > 0) {
+            // Auto-heal if duplicates exist
+            if (roots.length > 1) {
+                console.warn(`⚠️  VFS: Found ${roots.length} duplicate root directories`);
+                console.warn(`⚠️  VFS: Auto-selecting best root (most children)`);
+                return await this.selectBestRoot(roots);
+            }
+            // Single root - verify metadata and return
+            const root = roots[0];
+            // Extract metadata safely from Result object
+            const metadata = root.metadata || root;
+            // Ensure proper metadata structure
+            if (!metadata.vfsType || metadata.vfsType !== 'directory') {
+                console.warn(`⚠️  VFS: Root metadata incomplete, repairing...`);
                 await this.brain.update({
-                    id: rootEntity.id,
+                    id: root.id,
                     metadata: {
+                        ...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
+                        isVFS: true,
+                        isVFSEntity: true,
                         size: 0,
                         permissions: 0o755,
                         owner: 'root',
                         group: 'root',
                         accessed: Date.now(),
-                        modified: Date.now(),
-                        ...entityMetadata // Preserve any existing metadata
+                        modified: Date.now()
                     }
                 });
             }
-            return rootEntity.id;
+            return root.id;
         }
-        // Create root directory (only if truly doesn't exist)
+        // ONLY create root if absolutely zero roots exist
+        console.log('VFS: Creating root directory (verified zero roots exist)');
         const root = await this.brain.add({
-            data: '/', // Root directory content as string
+            data: '/',
             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
+                isVFS: true,
+                isVFSEntity: true,
                 size: 0,
                 permissions: 0o755,
                 owner: 'root',
                 group: 'root',
                 accessed: Date.now(),
                 modified: Date.now(),
-                createdAt: Date.now() // Track creation time for duplicate detection
+                createdAt: Date.now()
             }
         });
         return root;
     }
+    /**
+     * v5.8.0: Smart root selection when duplicates exist
+     * Selects root with MOST children (not oldest) to preserve user data
+     */
+    async selectBestRoot(roots) {
+        // Count descendants for each root
+        const rootStats = await Promise.all(roots.map(async (root) => {
+            const children = await this.brain.find({
+                where: { parent: root.id },
+                limit: 1000 // Cap to prevent huge queries
+            });
+            // Extract metadata safely from Result object
+            const metadata = root.metadata || root;
+            return {
+                id: root.id,
+                createdAt: metadata.createdAt || metadata.modified || 0,
+                childCount: children.length,
+                sampleChildren: children.slice(0, 3).map(c => {
+                    const childMeta = c.metadata || c;
+                    return childMeta.path || childMeta.name || 'unknown';
+                })
+            };
+        }));
+        // Sort by child count (DESC), then by creation time (ASC) as tiebreaker
+        rootStats.sort((a, b) => {
+            if (b.childCount !== a.childCount) {
+                return b.childCount - a.childCount; // Most children first
+            }
+            return a.createdAt - b.createdAt; // Oldest first (tiebreaker)
+        });
+        const bestRoot = rootStats[0];
+        const emptyRoots = rootStats.filter(r => r.childCount === 0);
+        // Log detailed statistics
+        console.warn(`\n📊 VFS Root Statistics:`);
+        for (const stat of rootStats) {
+            const shortId = stat.id.substring(0, 8);
+            const created = stat.createdAt ? new Date(stat.createdAt).toISOString() : 'unknown';
+            console.warn(`  Root ${shortId}: ${stat.childCount} children, created ${created}`);
+            if (stat.sampleChildren.length > 0) {
+                console.warn(`    Sample: ${stat.sampleChildren.join(', ')}`);
+            }
+        }
+        console.warn(`\n✅ VFS: Selected root ${bestRoot.id.substring(0, 8)} (${bestRoot.childCount} children)`);
+        // Suggest cleanup for empty roots
+        if (emptyRoots.length > 0) {
+            console.warn(`\n💡 VFS: Found ${emptyRoots.length} empty duplicate root(s), suggest cleanup:`);
+            for (const empty of emptyRoots) {
+                console.warn(`   await brain.delete('${empty.id}')  // Empty VFS root`);
+            }
+        }
+        return bestRoot.id;
+    }
     // ============= File Operations =============
     /**
      * Read a file's content
@@ -194,19 +273,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() });
-        }
-        // Apply encoding if requested
-        if (options?.encoding) {
-            return Buffer.from(content.toString(options.encoding));
+        // 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;
+        }
+        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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.8.0",
+  "version": "5.9.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"