@soulcraft/brainy 6.2.7 → 6.2.9

package/dist/brainy.d.ts

@@ -1795,6 +1795,10 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * - 87% memory reduction through separate graphs per entity type
      * - 10x faster type-specific queries
      * - Automatic type routing
+     *
+     * v6.2.8: Smart defaults for HNSW persistence mode
+     * - Cloud storage (GCS/S3/R2/Azure): 'deferred' for 30-50× faster adds
+     * - Local storage (FileSystem/Memory/OPFS): 'immediate' (already fast)
      */
     private setupIndex;
     /**
@@ -1846,6 +1850,9 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     private rebuildIndexesIfNeeded;
     /**
      * Close and cleanup
+     *
+     * v6.2.8: Now flushes HNSW dirty nodes before closing
+     * This ensures deferred persistence mode data is saved
      */
     close(): Promise<void>;
     /**

package/dist/brainy.js

@@ -3974,20 +3974,35 @@ export class Brainy {
      * - 87% memory reduction through separate graphs per entity type
      * - 10x faster type-specific queries
      * - Automatic type routing
+     *
+     * v6.2.8: Smart defaults for HNSW persistence mode
+     * - Cloud storage (GCS/S3/R2/Azure): 'deferred' for 30-50× faster adds
+     * - Local storage (FileSystem/Memory/OPFS): 'immediate' (already fast)
      */
     setupIndex() {
         const indexConfig = {
             ...this.config.index,
             distanceFunction: this.distance
         };
+        // v6.2.8: Determine persist mode (user config > smart default)
+        let persistMode = this.config.hnswPersistMode || 'immediate';
+        // Smart default: Use deferred mode for cloud storage adapters
+        if (!this.config.hnswPersistMode) {
+            const storageType = this.config.storage?.type || 'auto';
+            const cloudStorageTypes = ['gcs', 's3', 'r2', 'azure'];
+            if (cloudStorageTypes.includes(storageType)) {
+                persistMode = 'deferred';
+            }
+        }
         // Phase 2: Use TypeAwareHNSWIndex for billion-scale optimization
         if (this.config.storage?.type !== 'memory') {
             return new TypeAwareHNSWIndex(indexConfig, this.distance, {
                 storage: this.storage,
-                useParallelization: true
+                useParallelization: true,
+                persistMode
             });
         }
-        return new HNSWIndex(indexConfig);
+        return new HNSWIndex(indexConfig, this.distance, { persistMode });
     }
     /**
      * Setup augmentations
@@ -4071,7 +4086,9 @@ export class Brainy {
             maxConcurrentOperations: config?.maxConcurrentOperations ?? 10,
             // Memory management options (v5.11.0)
             maxQueryLimit: config?.maxQueryLimit ?? undefined,
-            reservedQueryMemory: config?.reservedQueryMemory ?? undefined
+            reservedQueryMemory: config?.reservedQueryMemory ?? undefined,
+            // HNSW persistence mode (v6.2.8) - undefined = smart default in setupIndex
+            hnswPersistMode: config?.hnswPersistMode ?? undefined
         };
     }
     /**
@@ -4241,8 +4258,16 @@ export class Brainy {
     }
     /**
      * Close and cleanup
+     *
+     * v6.2.8: Now flushes HNSW dirty nodes before closing
+     * This ensures deferred persistence mode data is saved
      */
     async close() {
+        // v6.2.8: Flush HNSW dirty nodes before closing
+        // In deferred persistence mode, this persists all pending HNSW graph data
+        if (this.index && typeof this.index.flush === 'function') {
+            await this.index.flush();
+        }
         // Shutdown augmentations
         const augs = this.augmentationRegistry.getAll();
         for (const aug of augs) {

package/dist/hnsw/hnswIndex.d.ts

@@ -19,9 +19,13 @@ export declare class HNSWIndex {
     private cowEnabled;
     private cowModifiedNodes;
     private cowParent;
+    private persistMode;
+    private dirtyNodes;
+    private dirtySystem;
     constructor(config?: Partial<HNSWConfig>, distanceFunction?: DistanceFunction, options?: {
         useParallelization?: boolean;
         storage?: BaseStorage;
+        persistMode?: 'immediate' | 'deferred';
     });
     /**
      * Set whether to use parallelization for performance-critical operations
@@ -31,6 +35,29 @@ export declare class HNSWIndex {
      * Get whether parallelization is enabled
      */
     getUseParallelization(): boolean;
+    /**
+     * v6.2.8: Flush dirty HNSW data to storage
+     *
+     * In deferred persistence mode, HNSW connections are tracked as dirty but not
+     * immediately persisted. Call flush() to persist all pending changes.
+     *
+     * This is automatically called by:
+     * - brain.close()
+     * - brain.flush()
+     * - Process shutdown (SIGTERM/SIGINT)
+     *
+     * @returns Number of nodes flushed
+     */
+    flush(): Promise<number>;
+    /**
+     * Get the number of dirty (unpersisted) nodes
+     * Useful for monitoring and debugging
+     */
+    getDirtyNodeCount(): number;
+    /**
+     * Get the current persist mode
+     */
+    getPersistMode(): 'immediate' | 'deferred';
     /**
      * Enable COW (Copy-on-Write) mode - Instant fork via shallow copy
      *

package/dist/hnsw/hnswIndex.js

@@ -28,6 +28,12 @@ export class HNSWIndex {
         this.cowEnabled = false;
         this.cowModifiedNodes = new Set();
         this.cowParent = null;
+        // v6.2.8: Deferred HNSW persistence for cloud storage performance
+        // In deferred mode, HNSW connections are only persisted on flush/close
+        // This reduces GCS operations from 70 to 2-3 per add() (30-50× faster)
+        this.persistMode = 'immediate';
+        this.dirtyNodes = new Set(); // Nodes with unpersisted HNSW data
+        this.dirtySystem = false; // Whether system data (entryPoint, maxLevel) needs persist
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.distanceFunction = distanceFunction;
         this.useParallelization =
@@ -35,6 +41,7 @@ export class HNSWIndex {
                 ? options.useParallelization
                 : true;
         this.storage = options.storage || null;
+        this.persistMode = options.persistMode || 'immediate';
         // Use SAME UnifiedCache as Graph and Metadata for fair memory competition
         this.unifiedCache = getGlobalCache();
     }
@@ -50,6 +57,82 @@ export class HNSWIndex {
     getUseParallelization() {
         return this.useParallelization;
     }
+    /**
+     * v6.2.8: Flush dirty HNSW data to storage
+     *
+     * In deferred persistence mode, HNSW connections are tracked as dirty but not
+     * immediately persisted. Call flush() to persist all pending changes.
+     *
+     * This is automatically called by:
+     * - brain.close()
+     * - brain.flush()
+     * - Process shutdown (SIGTERM/SIGINT)
+     *
+     * @returns Number of nodes flushed
+     */
+    async flush() {
+        if (!this.storage) {
+            return 0;
+        }
+        if (this.dirtyNodes.size === 0 && !this.dirtySystem) {
+            return 0;
+        }
+        const startTime = Date.now();
+        const nodeCount = this.dirtyNodes.size;
+        // Batch persist all dirty nodes concurrently
+        if (this.dirtyNodes.size > 0) {
+            const batchSize = 50; // Reasonable batch size for cloud storage
+            const nodeIds = Array.from(this.dirtyNodes);
+            for (let i = 0; i < nodeIds.length; i += batchSize) {
+                const batch = nodeIds.slice(i, i + batchSize);
+                const promises = batch.map(nodeId => {
+                    const noun = this.nouns.get(nodeId);
+                    if (!noun)
+                        return Promise.resolve(); // Node was deleted
+                    const connectionsObj = {};
+                    for (const [level, nounIds] of noun.connections.entries()) {
+                        connectionsObj[level.toString()] = Array.from(nounIds);
+                    }
+                    return this.storage.saveHNSWData(nodeId, {
+                        level: noun.level,
+                        connections: connectionsObj
+                    }).catch(error => {
+                        console.error(`[HNSW flush] Failed to persist node ${nodeId}:`, error);
+                    });
+                });
+                await Promise.allSettled(promises);
+            }
+            this.dirtyNodes.clear();
+        }
+        // Persist system data if dirty
+        if (this.dirtySystem) {
+            await this.storage.saveHNSWSystem({
+                entryPointId: this.entryPointId,
+                maxLevel: this.maxLevel
+            }).catch(error => {
+                console.error('[HNSW flush] Failed to persist system data:', error);
+            });
+            this.dirtySystem = false;
+        }
+        const duration = Date.now() - startTime;
+        if (nodeCount > 0) {
+            prodLog.info(`[HNSW] Flushed ${nodeCount} dirty nodes in ${duration}ms`);
+        }
+        return nodeCount;
+    }
+    /**
+     * Get the number of dirty (unpersisted) nodes
+     * Useful for monitoring and debugging
+     */
+    getDirtyNodeCount() {
+        return this.dirtyNodes.size;
+    }
+    /**
+     * Get the current persist mode
+     */
+    getPersistMode() {
+        return this.persistMode;
+    }
     /**
      * Enable COW (Copy-on-Write) mode - Instant fork via shallow copy
      *
@@ -284,14 +367,11 @@ export class HNSWIndex {
                 }
                 // Persist updated neighbor HNSW data (v3.35.0+)
                 //
-                // PERFORMANCE OPTIMIZATION (v4.10.0): Concurrent neighbor updates
-                // Previously (v4.9.2): Serial await - 100% safe but 48-64× slower
-                // Now: Promise.allSettled() - 48-64× faster bulk imports
-                // Safety: All storage adapters handle concurrent writes via:
-                //   - Optimistic locking with retry (GCS/S3/Azure/R2)
-                //   - Mutex serialization (Memory/OPFS/FileSystem)
-                // Trade-off: More retry activity under high contention (expected and handled)
-                if (this.storage) {
+                // v6.2.8: Deferred persistence mode for cloud storage performance
+                // In deferred mode, we track dirty nodes instead of persisting immediately
+                // This reduces GCS operations from 70 to 2-3 per add() (30-50× faster)
+                if (this.storage && this.persistMode === 'immediate') {
+                    // IMMEDIATE MODE: Original behavior - persist each neighbor update
                     const neighborConnectionsObj = {};
                     for (const [lvl, nounIds] of neighbor.connections.entries()) {
                         neighborConnectionsObj[lvl.toString()] = Array.from(nounIds);
@@ -304,9 +384,13 @@ export class HNSWIndex {
                         })
                     });
                 }
+                else if (this.persistMode === 'deferred') {
+                    // DEFERRED MODE: Track dirty nodes for later batch persistence
+                    this.dirtyNodes.add(neighborId);
+                }
             }
-            // Execute all neighbor updates concurrently (with optional batch size limiting)
-            if (neighborUpdates.length > 0) {
+            // Execute all neighbor updates concurrently (only in immediate mode)
+            if (neighborUpdates.length > 0 && this.persistMode === 'immediate') {
                 const batchSize = this.config.maxConcurrentNeighborWrites || neighborUpdates.length;
                 const allFailures = [];
                 // Process in chunks if batch size specified
@@ -360,8 +444,9 @@ export class HNSWIndex {
             this.highLevelNodes.get(nounLevel).add(id);
         }
         // Persist HNSW graph data to storage (v3.35.0+)
-        if (this.storage) {
-            // Convert connections Map to serializable format
+        // v6.2.8: Respect persistMode setting
+        if (this.storage && this.persistMode === 'immediate') {
+            // IMMEDIATE MODE: Original behavior - persist new entity and system data
             const connectionsObj = {};
             for (const [level, nounIds] of noun.connections.entries()) {
                 connectionsObj[level.toString()] = Array.from(nounIds);
@@ -380,6 +465,11 @@ export class HNSWIndex {
                 console.error('Failed to persist HNSW system data:', error);
             });
         }
+        else if (this.persistMode === 'deferred') {
+            // DEFERRED MODE: Track dirty nodes for later batch persistence
+            this.dirtyNodes.add(id);
+            this.dirtySystem = true;
+        }
         return id;
     }
     /**

package/dist/hnsw/typeAwareHNSWIndex.d.ts

@@ -43,16 +43,18 @@ export declare class TypeAwareHNSWIndex {
     private distanceFunction;
     private storage;
     private useParallelization;
+    private persistMode;
     /**
      * Create a new TypeAwareHNSWIndex
      *
      * @param config HNSW configuration (M, efConstruction, efSearch, ml)
      * @param distanceFunction Distance function (default: euclidean)
-     * @param options Additional options (storage, parallelization)
+     * @param options Additional options (storage, parallelization, persistMode)
      */
     constructor(config?: Partial<HNSWConfig>, distanceFunction?: DistanceFunction, options?: {
         useParallelization?: boolean;
         storage?: BaseStorage;
+        persistMode?: 'immediate' | 'deferred';
     });
     /**
      * Enable COW (Copy-on-Write) mode - Instant fork via shallow copy
@@ -63,6 +65,24 @@ export declare class TypeAwareHNSWIndex {
      * @param parent - Parent TypeAwareHNSWIndex to copy from
      */
     enableCOW(parent: TypeAwareHNSWIndex): void;
+    /**
+     * v6.2.8: Flush dirty HNSW data to storage for all type-specific indexes
+     *
+     * In deferred persistence mode, HNSW connections are tracked as dirty but not
+     * immediately persisted. Call flush() to persist all pending changes across
+     * all type-specific indexes.
+     *
+     * @returns Total number of nodes flushed across all indexes
+     */
+    flush(): Promise<number>;
+    /**
+     * Get the total number of dirty (unpersisted) nodes across all type-specific indexes
+     */
+    getDirtyNodeCount(): number;
+    /**
+     * Get the current persist mode
+     */
+    getPersistMode(): 'immediate' | 'deferred';
     /**
      * Get or create HNSW index for a specific type (lazy initialization)
      *

package/dist/hnsw/typeAwareHNSWIndex.js

@@ -35,7 +35,7 @@ export class TypeAwareHNSWIndex {
      *
      * @param config HNSW configuration (M, efConstruction, efSearch, ml)
      * @param distanceFunction Distance function (default: euclidean)
-     * @param options Additional options (storage, parallelization)
+     * @param options Additional options (storage, parallelization, persistMode)
      */
     constructor(config = {}, distanceFunction = euclideanDistance, options = {}) {
         // One HNSW index per noun type (lazy initialization)
@@ -47,6 +47,7 @@ export class TypeAwareHNSWIndex {
             options.useParallelization !== undefined
                 ? options.useParallelization
                 : true;
+        this.persistMode = options.persistMode || 'immediate';
         prodLog.info('TypeAwareHNSWIndex initialized (Phase 2: Type-Aware HNSW)');
     }
     /**
@@ -64,13 +65,51 @@ export class TypeAwareHNSWIndex {
         for (const [type, parentIndex] of parent.indexes.entries()) {
             const childIndex = new HNSWIndex(this.config, this.distanceFunction, {
                 useParallelization: this.useParallelization,
-                storage: this.storage || undefined
+                storage: this.storage || undefined,
+                persistMode: this.persistMode
             });
             childIndex.enableCOW(parentIndex);
             this.indexes.set(type, childIndex);
         }
         prodLog.info(`TypeAwareHNSWIndex COW enabled: ${parent.indexes.size} type-specific indexes shallow copied`);
     }
+    /**
+     * v6.2.8: Flush dirty HNSW data to storage for all type-specific indexes
+     *
+     * In deferred persistence mode, HNSW connections are tracked as dirty but not
+     * immediately persisted. Call flush() to persist all pending changes across
+     * all type-specific indexes.
+     *
+     * @returns Total number of nodes flushed across all indexes
+     */
+    async flush() {
+        if (this.indexes.size === 0) {
+            return 0;
+        }
+        const flushPromises = Array.from(this.indexes.values()).map(index => index.flush());
+        const results = await Promise.all(flushPromises);
+        const totalFlushed = results.reduce((sum, count) => sum + count, 0);
+        if (totalFlushed > 0) {
+            prodLog.info(`[TypeAwareHNSW] Flushed ${totalFlushed} dirty nodes across ${this.indexes.size} type indexes`);
+        }
+        return totalFlushed;
+    }
+    /**
+     * Get the total number of dirty (unpersisted) nodes across all type-specific indexes
+     */
+    getDirtyNodeCount() {
+        let total = 0;
+        for (const index of this.indexes.values()) {
+            total += index.getDirtyNodeCount();
+        }
+        return total;
+    }
+    /**
+     * Get the current persist mode
+     */
+    getPersistMode() {
+        return this.persistMode;
+    }
     /**
      * Get or create HNSW index for a specific type (lazy initialization)
      *
@@ -90,7 +129,8 @@ export class TypeAwareHNSWIndex {
             prodLog.info(`Creating HNSW index for type: ${type}`);
             const index = new HNSWIndex(this.config, this.distanceFunction, {
                 useParallelization: this.useParallelization,
-                storage: this.storage || undefined
+                storage: this.storage || undefined,
+                persistMode: this.persistMode
             });
             this.indexes.set(type, index);
         }

package/dist/storage/baseStorage.js

@@ -1276,6 +1276,42 @@ export class BaseStorage extends BaseStorageAdapter {
                     nextCursor
                 };
             }
+            // v6.2.9: Fast path for SINGLE sourceId + verbType combo (common VFS pattern)
+            // This avoids the slow type-iteration fallback for VFS operations
+            // NOTE: Only use fast path for single sourceId to avoid incomplete results
+            const isSingleSourceId = options.filter.sourceId &&
+                !Array.isArray(options.filter.sourceId);
+            if (isSingleSourceId &&
+                options.filter.verbType &&
+                !options.filter.targetId &&
+                !options.filter.service &&
+                !options.filter.metadata) {
+                const sourceId = options.filter.sourceId;
+                const verbTypes = Array.isArray(options.filter.verbType)
+                    ? options.filter.verbType
+                    : [options.filter.verbType];
+                prodLog.debug(`[BaseStorage] getVerbs: Using fast path for sourceId=${sourceId}, verbTypes=${verbTypes.join(',')}`);
+                // Get verbs by source (uses GraphAdjacencyIndex if available)
+                const verbsBySource = await this.getVerbsBySource_internal(sourceId);
+                // Filter by verbType in memory (fast - usually small number of verbs per source)
+                const filtered = verbsBySource.filter(v => verbTypes.includes(v.verb));
+                // Apply pagination
+                const paginatedVerbs = filtered.slice(offset, offset + limit);
+                const hasMore = offset + limit < filtered.length;
+                // Set next cursor if there are more items
+                let nextCursor = undefined;
+                if (hasMore && paginatedVerbs.length > 0) {
+                    const lastItem = paginatedVerbs[paginatedVerbs.length - 1];
+                    nextCursor = lastItem.id;
+                }
+                prodLog.debug(`[BaseStorage] getVerbs: Fast path returned ${filtered.length} verbs (${paginatedVerbs.length} after pagination)`);
+                return {
+                    items: paginatedVerbs,
+                    totalCount: filtered.length,
+                    hasMore,
+                    nextCursor
+                };
+            }
         }
         // For more complex filtering or no filtering, use a paginated approach
         // that avoids loading all verbs into memory at once
@@ -1336,14 +1372,32 @@ export class BaseStorage extends BaseStorageAdapter {
             // Only use type-skipping optimization if counts are non-zero (reliable)
             const totalVerbCountFromArray = this.verbCountsByType.reduce((sum, c) => sum + c, 0);
             const useOptimization = totalVerbCountFromArray > 0;
+            // v6.2.9 BUG FIX: Pre-compute requested verb types to avoid skipping them
+            // When a specific verbType filter is provided, we MUST check that type
+            // even if verbCountsByType shows 0 (counts can be stale after restart)
+            const requestedVerbTypes = options?.filter?.verbType;
+            const requestedVerbTypesSet = requestedVerbTypes
+                ? new Set(Array.isArray(requestedVerbTypes) ? requestedVerbTypes : [requestedVerbTypes])
+                : null;
             // Iterate through all 127 verb types (Stage 3 CANONICAL) with early termination
             // OPTIMIZATION: Skip types with zero count (only if counts are reliable)
             for (let i = 0; i < VERB_TYPE_COUNT && collectedVerbs.length < targetCount; i++) {
-                // Skip empty types for performance (but only if optimization is enabled)
-                if (useOptimization && this.verbCountsByType[i] === 0) {
+                const type = TypeUtils.getVerbFromIndex(i);
+                // v6.2.9 FIX: Never skip a type that's explicitly requested in the filter
+                // This fixes VFS bug where Contains relationships were skipped after restart
+                // when verbCountsByType[Contains] was 0 due to stale statistics
+                const isRequestedType = requestedVerbTypesSet?.has(type) ?? false;
+                const countIsZero = this.verbCountsByType[i] === 0;
+                // Skip empty types for performance (but only if optimization is enabled AND not requested)
+                if (useOptimization && countIsZero && !isRequestedType) {
                     continue;
                 }
-                const type = TypeUtils.getVerbFromIndex(i);
+                // v6.2.9: Log when we DON'T skip a requested type that would have been skipped
+                // This helps diagnose stale statistics issues in production
+                if (useOptimization && countIsZero && isRequestedType) {
+                    prodLog.debug(`[BaseStorage] getVerbs: NOT skipping type=${type} despite count=0 (type was explicitly requested). ` +
+                        `Statistics may be stale - consider running rebuildTypeCounts().`);
+                }
                 try {
                     const verbsOfType = await this.getVerbsByType_internal(type);
                     // Apply filtering inline (memory efficient)
@@ -2169,8 +2223,11 @@ export class BaseStorage extends BaseStorageAdapter {
         this.nounCountsByType[typeIndex]++;
         // COW-aware write (v5.0.1): Use COW helper for branch isolation
         await this.writeObjectToBranch(path, noun);
-        // Periodically save statistics (every 100 saves)
-        if (this.nounCountsByType[typeIndex] % 100 === 0) {
+        // Periodically save statistics
+        // v6.2.9: Also save on first noun of each type to ensure low-count types are tracked
+        const shouldSave = this.nounCountsByType[typeIndex] === 1 || // First noun of type
+            this.nounCountsByType[typeIndex] % 100 === 0; // Every 100th
+        if (shouldSave) {
             await this.saveTypeStatistics();
         }
     }
@@ -2277,7 +2334,11 @@ export class BaseStorage extends BaseStorageAdapter {
             prodLog.warn(`[BaseStorage] graphIndex is null, cannot update index for verb ${verb.id}`);
         }
         // Periodically save statistics
-        if (this.verbCountsByType[typeIndex] % 100 === 0) {
+        // v6.2.9: Also save on first verb of each type to ensure low-count types are tracked
+        // This prevents stale statistics after restart for types with < 100 verbs (common for VFS)
+        const shouldSave = this.verbCountsByType[typeIndex] === 1 || // First verb of type
+            this.verbCountsByType[typeIndex] % 100 === 0; // Every 100th
+        if (shouldSave) {
             await this.saveTypeStatistics();
         }
     }

package/dist/types/brainy.types.d.ts

@@ -552,6 +552,7 @@ export interface BrainyConfig {
     disableAutoOptimize?: boolean;
     batchWrites?: boolean;
     maxConcurrentOperations?: number;
+    hnswPersistMode?: 'immediate' | 'deferred';
     maxQueryLimit?: number;
     reservedQueryMemory?: number;
     verbose?: boolean;

package/dist/utils/unifiedCache.d.ts

@@ -92,6 +92,13 @@ export declare class UnifiedCache {
      * Delete specific item from cache
      */
     delete(key: string): boolean;
+    /**
+     * Delete all items with keys starting with the given prefix
+     * v6.2.9: Added for VFS cache invalidation (fixes stale parent ID bug)
+     * @param prefix - The key prefix to match
+     * @returns Number of items deleted
+     */
+    deleteByPrefix(prefix: string): number;
     /**
      * Clear cache or specific type
      */

package/dist/utils/unifiedCache.js

@@ -304,6 +304,23 @@ export class UnifiedCache {
         }
         return false;
     }
+    /**
+     * Delete all items with keys starting with the given prefix
+     * v6.2.9: Added for VFS cache invalidation (fixes stale parent ID bug)
+     * @param prefix - The key prefix to match
+     * @returns Number of items deleted
+     */
+    deleteByPrefix(prefix) {
+        let deleted = 0;
+        for (const [key, item] of this.cache) {
+            if (key.startsWith(prefix)) {
+                this.currentSize -= item.size;
+                this.cache.delete(key);
+                deleted++;
+            }
+        }
+        return deleted;
+    }
     /**
      * Clear cache or specific type
      */

package/dist/vfs/PathResolver.d.ts

@@ -64,6 +64,8 @@ export declare class PathResolver {
     createPath(path: string, entityId: string): Promise<void>;
     /**
      * Invalidate cache entries for a path and its children
+     * v6.2.9 FIX: Also invalidates UnifiedCache to prevent stale entity IDs
+     * This fixes the "Source entity not found" bug after delete+recreate operations
      */
     invalidatePath(path: string, recursive?: boolean): void;
     /**

package/dist/vfs/PathResolver.js

@@ -254,26 +254,38 @@ export class PathResolver {
     }
     /**
      * Invalidate cache entries for a path and its children
+     * v6.2.9 FIX: Also invalidates UnifiedCache to prevent stale entity IDs
+     * This fixes the "Source entity not found" bug after delete+recreate operations
      */
     invalidatePath(path, recursive = false) {
         const normalizedPath = this.normalizePath(path);
-        // Remove from all caches
+        // v6.2.9 FIX: Clear parent cache BEFORE deleting from pathCache
+        // (we need the entityId from the cache entry)
+        const cached = this.pathCache.get(normalizedPath);
+        if (cached) {
+            this.parentCache.delete(cached.entityId);
+        }
+        // Remove from local caches
         this.pathCache.delete(normalizedPath);
         this.hotPaths.delete(normalizedPath);
+        // v6.2.9 CRITICAL FIX: Also invalidate UnifiedCache (global LRU cache)
+        // This was missing before, causing stale entity IDs to be returned after delete
+        const cacheKey = `vfs:path:${normalizedPath}`;
+        getGlobalCache().delete(cacheKey);
         if (recursive) {
             // Remove all paths that start with this path
             const prefix = normalizedPath.endsWith('/') ? normalizedPath : normalizedPath + '/';
-            for (const [cachedPath] of this.pathCache) {
+            for (const [cachedPath, entry] of this.pathCache) {
                 if (cachedPath.startsWith(prefix)) {
                     this.pathCache.delete(cachedPath);
                     this.hotPaths.delete(cachedPath);
+                    // v6.2.9: Also clear parent cache for this entry
+                    this.parentCache.delete(entry.entityId);
                 }
             }
-        }
-        // Clear parent cache for the entity
-        const cached = this.pathCache.get(normalizedPath);
-        if (cached) {
-            this.parentCache.delete(cached.entityId);
+            // v6.2.9 CRITICAL FIX: Also invalidate UnifiedCache entries with this prefix
+            const globalCachePrefix = `vfs:path:${prefix}`;
+            getGlobalCache().deleteByPrefix(globalCachePrefix);
         }
     }
     /**

package/package.json

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