@soulcraft/brainy 5.7.3 → 5.7.5

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.7.4](https://github.com/soulcraftlabs/brainy/compare/v5.7.3...v5.7.4) (2025-11-12)
+
+- fix: resolve v5.7.3 race condition by persisting write-through cache (v5.7.4) (6e19ec8)
+
+
 ### [5.7.3](https://github.com/soulcraftlabs/brainy/compare/v5.7.2...v5.7.3) (2025-11-12)
 
 

package/dist/brainy.js

@@ -1613,21 +1613,6 @@ export class Brainy {
                 lastBatchTime = Date.now();
             }
         }
-        // v5.7.3: Ensure nounTypeCache is populated for all successful entities
-        // This prevents cache misses that trigger expensive 42-type searches
-        // when entities are immediately queried (e.g., during brain.relate())
-        const cacheWarmingNeeded = result.successful.filter(id => !this.storage.nounTypeCache?.has(id));
-        if (cacheWarmingNeeded.length > 0) {
-            // Warm the cache by fetching metadata for entities not in cache
-            await Promise.all(cacheWarmingNeeded.map(async (id) => {
-                try {
-                    await this.storage.getNounMetadata(id);
-                }
-                catch (error) {
-                    // Ignore errors during cache warming (entity may be invalid)
-                }
-            }));
-        }
         result.duration = Date.now() - startTime;
         return result;
     }
@@ -3094,15 +3079,15 @@ export class Brainy {
             // 3. Flush graph adjacency index (relationship cache)
             // Note: Graph structure is already persisted via storage.saveVerb() calls
             // This just flushes the in-memory cache for performance
-            this.graphIndex.flush(),
-            // 4. v5.7.3: Clear write-through cache after flush
-            // Cache persists during batch operations for read-after-write consistency
-            // Cleared here after all writes are guaranteed flushed to disk
-            (async () => {
-                if (this.storage && typeof this.storage.writeCache !== 'undefined') {
-                    this.storage.writeCache.clear();
-                }
-            })()
+            this.graphIndex.flush()
+            // Note: Write-through cache (storage.writeCache) is NOT cleared here
+            // Cache persists indefinitely for read-after-write consistency
+            // Provides safety net for:
+            // - Cloud storage eventual consistency (S3, GCS, Azure, R2)
+            // - Filesystem buffer cache timing
+            // - Type cache warming period (nounTypeCache population)
+            // Cache entries are removed only when explicitly deleted (deleteObjectFromBranch)
+            // Memory footprint is negligible for typical workloads (<10MB for 100k entities)
         ]);
         const elapsed = Date.now() - startTime;
         console.log(`✅ All indexes flushed to disk in ${elapsed}ms`);

package/dist/import/ImportCoordinator.js

@@ -643,10 +643,6 @@ export class ImportCoordinator {
             if (addResult.failed.length > 0) {
                 console.warn(`⚠️  ${addResult.failed.length} entities failed to create`);
             }
-            // v5.7.3: Ensure all writes are flushed before creating relationships
-            // Fixes "Source entity not found" error in v5.7.0/v5.7.1/v5.7.2
-            // Guarantees entities are fully persisted and queryable before brain.relate() is called
-            await this.brain.flush();
             // Create provenance links in batch
             if (documentEntityId && options.createProvenanceLinks !== false && entities.length > 0) {
                 const provenanceParams = entities.map((entity, idx) => {

package/dist/storage/baseStorage.js

@@ -238,6 +238,11 @@ export class BaseStorage extends BaseStorageAdapter {
                     if (Buffer.isBuffer(data)) {
                         return data;
                     }
+                    // v5.7.5: Unwrap binary data stored as {_binary: true, data: "base64..."}
+                    // Fixes "Blob integrity check failed" - hash must be calculated on original content
+                    if (data._binary && typeof data.data === 'string') {
+                        return Buffer.from(data.data, 'base64');
+                    }
                     return Buffer.from(JSON.stringify(data));
                 }
                 catch (error) {

package/dist/storage/cow/BlobStorage.d.ts

@@ -84,6 +84,7 @@ export declare class BlobStorage {
     private stats;
     private zstdCompress?;
     private zstdDecompress?;
+    private compressionReady;
     private readonly CACHE_MAX_SIZE;
     private readonly MULTIPART_THRESHOLD;
     private readonly COMPRESSION_THRESHOLD;
@@ -96,6 +97,11 @@ export declare class BlobStorage {
      * (Avoids loading if not needed)
      */
     private initCompression;
+    /**
+     * v5.7.5: Ensure compression is ready before write operations
+     * Fixes race condition where write happens before async compression init completes
+     */
+    private ensureCompressionReady;
     /**
      * Compute SHA-256 hash of data
      *

package/dist/storage/cow/BlobStorage.js

@@ -29,6 +29,7 @@ import { NULL_HASH, isNullHash } from './constants.js';
  */
 export class BlobStorage {
     constructor(adapter, options) {
+        this.compressionReady = false;
         // Configuration
         this.CACHE_MAX_SIZE = 100 * 1024 * 1024; // 100MB default
         this.MULTIPART_THRESHOLD = 5 * 1024 * 1024; // 5MB
@@ -74,6 +75,16 @@ export class BlobStorage {
             this.zstdDecompress = undefined;
         }
     }
+    /**
+     * v5.7.5: Ensure compression is ready before write operations
+     * Fixes race condition where write happens before async compression init completes
+     */
+    async ensureCompressionReady() {
+        if (this.compressionReady)
+            return;
+        await this.initCompression();
+        this.compressionReady = true;
+    }
     /**
      * Compute SHA-256 hash of data
      *
@@ -107,6 +118,9 @@ export class BlobStorage {
             this.stats.dedupSavings += data.length;
             return hash;
         }
+        // v5.7.5: Ensure compression is initialized before writing
+        // Fixes race condition where write happens before async init completes
+        await this.ensureCompressionReady();
         // Determine compression strategy
         const compression = this.selectCompression(data, options);
         // Compress if needed
@@ -117,11 +131,14 @@ export class BlobStorage {
             compressedSize = finalData.length;
         }
         // Create metadata
+        // v5.7.5: Store ACTUAL compression state, not intended
+        // Prevents corruption if compression failed to initialize
+        const actualCompression = finalData === data ? 'none' : compression;
         const metadata = {
             hash,
             size: data.length,
             compressedSize,
-            compression,
+            compression: actualCompression,
             type: options.type || 'blob', // CRITICAL FIX: Use 'blob' default to match storage prefix
             createdAt: Date.now(),
             refCount: 1

package/package.json

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