@soulcraft/brainy 5.7.1 → 5.7.3

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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.3](https://github.com/soulcraftlabs/brainy/compare/v5.7.2...v5.7.3) (2025-11-12)
+
+
+### 🐛 Bug Fixes
+
+* resolve REAL v5.7.x race condition - type cache layer (v5.7.3) ([ee17565](https://github.com/soulcraftlabs/brainy/commit/ee1756565ca01666e2aa3b31a80b62c6aa8046e8))
+
+### [5.7.2](https://github.com/soulcraftlabs/brainy/compare/v5.7.1...v5.7.2) (2025-11-12)
+
+
+### 🐛 Bug Fixes
+
+* resolve v5.7.x race condition with write-through cache (v5.7.2) ([732d23b](https://github.com/soulcraftlabs/brainy/commit/732d23bd2afb4ac9559a9beb7835e0f623065ff2))
+
 ### [5.7.1](https://github.com/soulcraftlabs/brainy/compare/v5.7.0...v5.7.1) (2025-11-11)
 
 - fix: resolve v5.7.0 deadlock by restoring storage layer separation (v5.7.1) (eb9af45)

package/dist/brainy.js

@@ -1613,6 +1613,21 @@ 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;
     }
@@ -3079,7 +3094,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()
+            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();
+                }
+            })()
         ]);
         const elapsed = Date.now() - startTime;
         console.log(`✅ All indexes flushed to disk in ${elapsed}ms`);

package/dist/import/ImportCoordinator.js

@@ -643,6 +643,10 @@ 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.d.ts

@@ -53,6 +53,7 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     protected graphIndex?: GraphAdjacencyIndex;
     protected graphIndexPromise?: Promise<GraphAdjacencyIndex>;
     protected readOnly: boolean;
+    private writeCache;
     refManager?: RefManager;
     blobStorage?: BlobStorage;
     commitLog?: CommitLog;

package/dist/storage/baseStorage.js

@@ -74,6 +74,13 @@ export class BaseStorage extends BaseStorageAdapter {
         super(...arguments);
         this.isInitialized = false;
         this.readOnly = false;
+        // v5.7.2: Write-through cache for read-after-write consistency
+        // v5.7.3: Extended lifetime - persists until explicit flush() call
+        // Guarantees that immediately after writeObjectToBranch(), readWithInheritance() returns the data
+        // Cache key: resolved branchPath (includes branch scope for COW isolation)
+        // Cache lifetime: write start → flush() call (provides safety net for batch operations)
+        // Memory footprint: Bounded by batch size (typically <1000 items during imports)
+        this.writeCache = new Map();
         this.currentBranch = 'main';
         this.cowEnabled = false;
         // Type-first indexing support (v5.4.0)
@@ -353,7 +360,14 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async writeObjectToBranch(path, data, branch) {
         const branchPath = this.resolveBranchPath(path, branch);
-        return this.writeObjectToPath(branchPath, data);
+        // v5.7.2: Add to write cache BEFORE async write (guarantees read-after-write consistency)
+        // v5.7.3: Cache persists until flush() is called (extended lifetime for batch operations)
+        // This ensures readWithInheritance() returns data immediately, fixing "Source entity not found" bug
+        this.writeCache.set(branchPath, data);
+        // Write to storage (async)
+        await this.writeObjectToPath(branchPath, data);
+        // v5.7.3: Cache is NOT cleared here anymore - persists until flush()
+        // This provides a safety net for immediate queries after batch writes
     }
     /**
      * Read object with inheritance from parent branches (COW layer)
@@ -362,12 +376,24 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async readWithInheritance(path, branch) {
         if (!this.cowEnabled) {
-            // COW disabled, direct read
+            // COW disabled: check write cache, then direct read
+            // v5.7.2: Check cache first for read-after-write consistency
+            const cachedData = this.writeCache.get(path);
+            if (cachedData !== undefined) {
+                return cachedData;
+            }
             return this.readObjectFromPath(path);
         }
         const targetBranch = branch || this.currentBranch || 'main';
-        // Try current branch first
         const branchPath = this.resolveBranchPath(path, targetBranch);
+        // v5.7.2: Check write cache FIRST (synchronous, instant)
+        // This guarantees read-after-write consistency within the same process
+        // Fixes bug: brain.add() → brain.relate() → "Source entity not found"
+        const cachedData = this.writeCache.get(branchPath);
+        if (cachedData !== undefined) {
+            return cachedData;
+        }
+        // Try current branch first
         let data = await this.readObjectFromPath(branchPath);
         if (data !== null) {
             return data; // Found in current branch
@@ -411,6 +437,9 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async deleteObjectFromBranch(path, branch) {
         const branchPath = this.resolveBranchPath(path, branch);
+        // v5.7.2: Remove from write cache immediately (before async delete)
+        // Ensures subsequent reads don't return stale cached data
+        this.writeCache.delete(branchPath);
         return this.deleteObjectFromPath(branchPath);
     }
     /**

package/package.json

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