@soulcraft/brainy 5.7.13 → 5.9.0

package/dist/transaction/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Transaction System Types
+ *
+ * Provides atomicity for Brainy operations - all succeed or all rollback.
+ * Prevents partial failures that leave system in inconsistent state.
+ */
+/**
+ * Transaction state
+ */
+export type TransactionState = 'pending' | 'executing' | 'committed' | 'rolling_back' | 'rolled_back';
+/**
+ * Rollback action - undoes an operation
+ * Must be idempotent (safe to call multiple times)
+ */
+export type RollbackAction = () => Promise<void>;
+/**
+ * Operation that can be executed and rolled back
+ */
+export interface Operation {
+    /**
+     * Execute the operation
+     * @returns Rollback action to undo this operation (or undefined if no rollback needed)
+     */
+    execute(): Promise<RollbackAction | undefined>;
+    /**
+     * Optional: Name of operation for debugging
+     */
+    readonly name?: string;
+}
+/**
+ * Transaction context passed to user functions
+ */
+export interface TransactionContext {
+    /**
+     * Add an operation to the transaction
+     */
+    addOperation(operation: Operation): void;
+    /**
+     * Get current transaction state
+     */
+    getState(): TransactionState;
+    /**
+     * Get number of operations in transaction
+     */
+    getOperationCount(): number;
+}
+/**
+ * Function that builds a transaction
+ */
+export type TransactionFunction<T> = (ctx: TransactionContext) => Promise<T>;
+/**
+ * Transaction execution result
+ */
+export interface TransactionResult<T> {
+    /**
+     * Result value from user function
+     */
+    value: T;
+    /**
+     * Number of operations executed
+     */
+    operationCount: number;
+    /**
+     * Execution time in milliseconds
+     */
+    executionTimeMs: number;
+}
+/**
+ * Transaction execution options
+ */
+export interface TransactionOptions {
+    /**
+     * Timeout in milliseconds (default: 30000 = 30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Whether to log transaction execution (default: false)
+     */
+    logging?: boolean;
+    /**
+     * Maximum number of rollback retry attempts (default: 3)
+     */
+    maxRollbackRetries?: number;
+}

package/dist/transaction/types.js

@@ -0,0 +1,8 @@
+/**
+ * Transaction System Types
+ *
+ * Provides atomicity for Brainy operations - all succeed or all rollback.
+ * Prevents partial failures that leave system in inconsistent state.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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.7.13",
+  "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"