@soulcraft/brainy 6.4.0 → 6.5.0

package/dist/vfs/VirtualFileSystem.d.ts

@@ -285,8 +285,22 @@ export declare class VirtualFileSystem implements IVirtualFileSystem {
         type: string;
         metadata: any;
     }>>;
+    /**
+     * Sort bulk operations to prevent race conditions
+     *
+     * Strategy:
+     * 1. mkdir operations first, sorted by path depth (shallowest first)
+     * 2. Other operations (write, delete, update) after, in original order
+     *
+     * This ensures parent directories exist before files are written,
+     * preventing duplicate entity creation from concurrent mkdir calls.
+     */
+    private sortBulkOperations;
     /**
      * Bulk write operations for performance
+     *
+     * v6.5.0: Prevents race condition by processing mkdir operations
+     * sequentially before parallel batch processing of other operations.
      */
     bulkWrite(operations: Array<{
         type: 'write' | 'delete' | 'mkdir' | 'update';

package/dist/vfs/VirtualFileSystem.js

@@ -1930,8 +1930,40 @@ export class VirtualFileSystem {
             metadata: result.entity?.metadata || {}
         }));
     }
+    /**
+     * Sort bulk operations to prevent race conditions
+     *
+     * Strategy:
+     * 1. mkdir operations first, sorted by path depth (shallowest first)
+     * 2. Other operations (write, delete, update) after, in original order
+     *
+     * This ensures parent directories exist before files are written,
+     * preventing duplicate entity creation from concurrent mkdir calls.
+     */
+    sortBulkOperations(operations) {
+        const mkdirOps = [];
+        const otherOps = [];
+        for (const op of operations) {
+            if (op.type === 'mkdir') {
+                mkdirOps.push(op);
+            }
+            else {
+                otherOps.push(op);
+            }
+        }
+        // Sort mkdir by path depth (shallowest first)
+        mkdirOps.sort((a, b) => {
+            const depthA = (a.path.match(/\//g) || []).length;
+            const depthB = (b.path.match(/\//g) || []).length;
+            return depthA !== depthB ? depthA - depthB : a.path.localeCompare(b.path);
+        });
+        return [...mkdirOps, ...otherOps];
+    }
     /**
      * Bulk write operations for performance
+     *
+     * v6.5.0: Prevents race condition by processing mkdir operations
+     * sequentially before parallel batch processing of other operations.
      */
     async bulkWrite(operations) {
         await this.ensureInitialized();
@@ -1939,10 +1971,31 @@ export class VirtualFileSystem {
             successful: 0,
             failed: []
         };
-        // Process operations in batches for better performance
+        // Sort operations: mkdirs first (by depth), then others
+        const sortedOps = this.sortBulkOperations(operations);
+        // Separate mkdir operations for sequential processing
+        const mkdirOps = sortedOps.filter(op => op.type === 'mkdir');
+        const otherOps = sortedOps.filter(op => op.type !== 'mkdir');
+        // Phase 1: Process mkdir operations SEQUENTIALLY
+        // This prevents the race condition where parallel mkdir calls
+        // create duplicate directory entities due to mutex timing window
+        for (const op of mkdirOps) {
+            try {
+                await this.mkdir(op.path, op.options);
+                result.successful++;
+            }
+            catch (error) {
+                result.failed.push({
+                    operation: op,
+                    error: error.message || 'Unknown error'
+                });
+            }
+        }
+        // Phase 2: Process other operations in parallel batches
+        // These can safely run in parallel since parent directories now exist
         const batchSize = 10;
-        for (let i = 0; i < operations.length; i += batchSize) {
-            const batch = operations.slice(i, i + batchSize);
+        for (let i = 0; i < otherOps.length; i += batchSize) {
+            const batch = otherOps.slice(i, i + batchSize);
             // Process batch in parallel
             const promises = batch.map(async (op) => {
                 try {
@@ -1953,9 +2006,6 @@ export class VirtualFileSystem {
                         case 'delete':
                             await this.unlink(op.path);
                             break;
-                        case 'mkdir':
-                            await this.mkdir(op.path, op.options);
-                            break;
                         case 'update': {
                             // Update only metadata without changing content
                             const entityId = await this.pathResolver.resolve(op.path);

package/package.json

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