@soulcraft/brainy 4.10.2 → 4.10.3

package/dist/storage/adapters/fileSystemStorage.d.ts

@@ -53,6 +53,7 @@ export declare class FileSystemStorage extends BaseStorage {
     private ensureDirectoryExists;
     /**
      * Save a node to storage
+     * CRITICAL FIX (v4.10.3): Added atomic write pattern to prevent file corruption during concurrent imports
      */
     protected saveNode(node: HNSWNode): Promise<void>;
     /**
@@ -78,6 +79,7 @@ export declare class FileSystemStorage extends BaseStorage {
     protected deleteNode(id: string): Promise<void>;
     /**
      * Save an edge to storage
+     * CRITICAL FIX (v4.10.3): Added atomic write pattern to prevent file corruption during concurrent imports
      */
     protected saveEdge(edge: Edge): Promise<void>;
     /**
@@ -110,6 +112,7 @@ export declare class FileSystemStorage extends BaseStorage {
      * Primitive operation: Write object to path
      * All metadata operations use this internally via base class routing
      * v4.0.0: Supports gzip compression for 60-80% disk savings
+     * CRITICAL FIX (v4.10.3): Added atomic write pattern to prevent file corruption during concurrent imports
      */
     protected writeObjectToPath(pathStr: string, data: any): Promise<void>;
     /**

package/dist/storage/adapters/fileSystemStorage.js

@@ -180,6 +180,7 @@ export class FileSystemStorage extends BaseStorage {
     }
     /**
      * Save a node to storage
+     * CRITICAL FIX (v4.10.3): Added atomic write pattern to prevent file corruption during concurrent imports
      */
     async saveNode(node) {
         await this.ensureInitialized();
@@ -194,8 +195,25 @@ export class FileSystemStorage extends BaseStorage {
             // NO metadata field - saved separately for scalability
         };
         const filePath = this.getNodePath(node.id);
-        await this.ensureDirectoryExists(path.dirname(filePath));
-        await fs.promises.writeFile(filePath, JSON.stringify(serializableNode, null, 2));
+        const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).substring(2)}`;
+        try {
+            // ATOMIC WRITE SEQUENCE (v4.10.3):
+            // 1. Write to temp file
+            await this.ensureDirectoryExists(path.dirname(tempPath));
+            await fs.promises.writeFile(tempPath, JSON.stringify(serializableNode, null, 2));
+            // 2. Atomic rename temp → final (crash-safe, prevents truncation during concurrent writes)
+            await fs.promises.rename(tempPath, filePath);
+        }
+        catch (error) {
+            // Clean up temp file on any error
+            try {
+                await fs.promises.unlink(tempPath);
+            }
+            catch (cleanupError) {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
         // Count tracking happens in baseStorage.saveNounMetadata_internal (v4.1.2)
         // This fixes the race condition where metadata didn't exist yet
     }
@@ -344,6 +362,7 @@ export class FileSystemStorage extends BaseStorage {
     }
     /**
      * Save an edge to storage
+     * CRITICAL FIX (v4.10.3): Added atomic write pattern to prevent file corruption during concurrent imports
      */
     async saveEdge(edge) {
         await this.ensureInitialized();
@@ -362,8 +381,25 @@ export class FileSystemStorage extends BaseStorage {
             // metadata field is saved separately via saveVerbMetadata()
         };
         const filePath = this.getVerbPath(edge.id);
-        await this.ensureDirectoryExists(path.dirname(filePath));
-        await fs.promises.writeFile(filePath, JSON.stringify(serializableEdge, null, 2));
+        const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).substring(2)}`;
+        try {
+            // ATOMIC WRITE SEQUENCE (v4.10.3):
+            // 1. Write to temp file
+            await this.ensureDirectoryExists(path.dirname(tempPath));
+            await fs.promises.writeFile(tempPath, JSON.stringify(serializableEdge, null, 2));
+            // 2. Atomic rename temp → final (crash-safe, prevents truncation during concurrent writes)
+            await fs.promises.rename(tempPath, filePath);
+        }
+        catch (error) {
+            // Clean up temp file on any error
+            try {
+                await fs.promises.unlink(tempPath);
+            }
+            catch (cleanupError) {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
         // Count tracking happens in baseStorage.saveVerbMetadata_internal (v4.1.2)
         // This fixes the race condition where metadata didn't exist yet
     }
@@ -507,24 +543,42 @@ export class FileSystemStorage extends BaseStorage {
      * Primitive operation: Write object to path
      * All metadata operations use this internally via base class routing
      * v4.0.0: Supports gzip compression for 60-80% disk savings
+     * CRITICAL FIX (v4.10.3): Added atomic write pattern to prevent file corruption during concurrent imports
      */
     async writeObjectToPath(pathStr, data) {
         await this.ensureInitialized();
         const fullPath = path.join(this.rootDir, pathStr);
         await this.ensureDirectoryExists(path.dirname(fullPath));
         if (this.compressionEnabled) {
-            // Write compressed data with .gz extension
+            // Write compressed data with .gz extension using atomic pattern
             const compressedPath = `${fullPath}.gz`;
-            const jsonString = JSON.stringify(data, null, 2);
-            const compressed = await new Promise((resolve, reject) => {
-                zlib.gzip(Buffer.from(jsonString, 'utf-8'), { level: this.compressionLevel }, (err, result) => {
-                    if (err)
-                        reject(err);
-                    else
-                        resolve(result);
+            const tempPath = `${compressedPath}.tmp.${Date.now()}.${Math.random().toString(36).substring(2)}`;
+            try {
+                // ATOMIC WRITE SEQUENCE (v4.10.3):
+                // 1. Compress and write to temp file
+                const jsonString = JSON.stringify(data, null, 2);
+                const compressed = await new Promise((resolve, reject) => {
+                    zlib.gzip(Buffer.from(jsonString, 'utf-8'), { level: this.compressionLevel }, (err, result) => {
+                        if (err)
+                            reject(err);
+                        else
+                            resolve(result);
+                    });
                 });
-            });
-            await fs.promises.writeFile(compressedPath, compressed);
+                await fs.promises.writeFile(tempPath, compressed);
+                // 2. Atomic rename temp → final (crash-safe, prevents truncation during concurrent writes)
+                await fs.promises.rename(tempPath, compressedPath);
+            }
+            catch (error) {
+                // Clean up temp file on any error
+                try {
+                    await fs.promises.unlink(tempPath);
+                }
+                catch (cleanupError) {
+                    // Ignore cleanup errors
+                }
+                throw error;
+            }
             // Clean up uncompressed file if it exists (migration from uncompressed)
             try {
                 await fs.promises.unlink(fullPath);
@@ -537,8 +591,25 @@ export class FileSystemStorage extends BaseStorage {
             }
         }
         else {
-            // Write uncompressed data
-            await fs.promises.writeFile(fullPath, JSON.stringify(data, null, 2));
+            // Write uncompressed data using atomic pattern
+            const tempPath = `${fullPath}.tmp.${Date.now()}.${Math.random().toString(36).substring(2)}`;
+            try {
+                // ATOMIC WRITE SEQUENCE (v4.10.3):
+                // 1. Write to temp file
+                await fs.promises.writeFile(tempPath, JSON.stringify(data, null, 2));
+                // 2. Atomic rename temp → final (crash-safe, prevents truncation during concurrent writes)
+                await fs.promises.rename(tempPath, fullPath);
+            }
+            catch (error) {
+                // Clean up temp file on any error
+                try {
+                    await fs.promises.unlink(tempPath);
+                }
+                catch (cleanupError) {
+                    // Ignore cleanup errors
+                }
+                throw error;
+            }
         }
     }
     /**

package/package.json

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