@soulcraft/brainy 6.2.0 → 6.2.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.
 
+### [6.2.2](https://github.com/soulcraftlabs/brainy/compare/v6.2.1...v6.2.2) (2025-11-25)
+
+- refactor: remove 3,700+ LOC of unused HNSW implementations (e3146ce)
+- fix(hnsw): entry point recovery prevents import failures and log spam (52eae67)
+
+
 ## [6.2.0](https://github.com/soulcraftlabs/brainy/compare/v6.1.0...v6.2.0) (2025-11-20)
 
 ### ⚡ Critical Performance Fix

package/dist/brainy.d.ts

@@ -1566,9 +1566,11 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     get counts(): {
         entities: () => number;
         relationships: () => number;
-        byType: (type?: string) => number | {
-            [k: string]: number;
-        };
+        byType: (typeOrOptions?: string | {
+            excludeVFS?: boolean;
+        }, options?: {
+            excludeVFS?: boolean;
+        }) => Promise<number | Record<string, number>>;
         byTypeEnum: (type: NounType) => number;
         topTypes: (n?: number) => NounType[];
         topVerbTypes: (n?: number) => VerbType[];
@@ -1579,12 +1581,12 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
         };
         byCriteria: (field: string, value: any) => Promise<number>;
         getAllTypeCounts: () => Map<string, number>;
-        getStats: () => {
+        getStats: (options?: {
+            excludeVFS?: boolean;
+        }) => Promise<{
             entities: {
                 total: number;
-                byType: {
-                    [k: string]: number;
-                };
+                byType: Record<string, number>;
             };
             relationships: {
                 totalRelationships: number;
@@ -1594,7 +1596,7 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
                 totalNodes: number;
             };
             density: number;
-        };
+        }>;
     };
     /**
      * Augmentations API - Clean and simple
@@ -1607,14 +1609,16 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     /**
      * Get complete statistics - convenience method
      * For more granular counting, use brain.counts API
+     * v6.2.1: Added optional excludeVFS using Roaring bitmap intersection
+     * @param options Optional settings - excludeVFS: filter out VFS entities
      * @returns Complete statistics including entities, relationships, and density
      */
-    getStats(): {
+    getStats(options?: {
+        excludeVFS?: boolean;
+    }): Promise<{
         entities: {
             total: number;
-            byType: {
-                [k: string]: number;
-            };
+            byType: Record<string, number>;
         };
         relationships: {
             totalRelationships: number;
@@ -1624,7 +1628,7 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
             totalNodes: number;
         };
         density: number;
-    };
+    }>;
     /**
      * Parse natural language query using advanced NLP with 220+ patterns
      * The embedding model is always available as it's core to Brainy's functionality

package/dist/brainy.js

@@ -6,7 +6,6 @@
  */
 import { v4 as uuidv4 } from './universal/uuid.js';
 import { HNSWIndex } from './hnsw/hnswIndex.js';
-import { HNSWIndexOptimized } from './hnsw/hnswIndexOptimized.js';
 import { TypeAwareHNSWIndex } from './hnsw/typeAwareHNSWIndex.js';
 import { createStorage } from './storage/storageFactory.js';
 import { defaultEmbeddingFunction, cosineDistance } from './utils/index.js';
@@ -768,7 +767,13 @@ export class Brainy {
                     }
                 }
                 // Operation 5-6: Update metadata index (remove old, add new)
-                tx.addOperation(new RemoveFromMetadataIndexOperation(this.metadataIndex, params.id, existing.metadata));
+                // v6.2.1: Fix - Include type in removal metadata so noun index is properly updated
+                // existing.metadata only contains custom fields, not 'type' which maps to 'noun'
+                const removalMetadata = {
+                    ...existing.metadata,
+                    type: existing.type // Include type so it maps to 'noun' during removal
+                };
+                tx.addOperation(new RemoveFromMetadataIndexOperation(this.metadataIndex, params.id, removalMetadata));
                 tx.addOperation(new AddToMetadataIndexOperation(this.metadataIndex, params.id, entityForIndexing));
             });
         });
@@ -796,7 +801,7 @@ export class Brainy {
                     if (this.index instanceof TypeAwareHNSWIndex && metadata.noun) {
                         tx.addOperation(new RemoveFromTypeAwareHNSWOperation(this.index, id, noun.vector, metadata.noun));
                     }
-                    else if (this.index instanceof HNSWIndex || this.index instanceof HNSWIndexOptimized) {
+                    else if (this.index instanceof HNSWIndex) {
                         tx.addOperation(new RemoveFromHNSWOperation(this.index, id, noun.vector));
                     }
                 }
@@ -1881,7 +1886,7 @@ export class Brainy {
                                 if (this.index instanceof TypeAwareHNSWIndex && metadata.noun) {
                                     tx.addOperation(new RemoveFromTypeAwareHNSWOperation(this.index, id, noun.vector, metadata.noun));
                                 }
-                                else if (this.index instanceof HNSWIndex || this.index instanceof HNSWIndexOptimized) {
+                                else if (this.index instanceof HNSWIndex) {
                                     tx.addOperation(new RemoveFromHNSWOperation(this.index, id, noun.vector));
                                 }
                             }
@@ -3405,7 +3410,39 @@ export class Brainy {
             // O(1) total relationship count
             relationships: () => this.graphIndex.getTotalRelationshipCount(),
             // O(1) count by type (string-based, backward compatible)
-            byType: (type) => {
+            // v6.2.1: Added optional excludeVFS using Roaring bitmap intersection
+            byType: async (typeOrOptions, options) => {
+                // Handle overloaded signature: byType(type), byType({ excludeVFS }), byType(type, { excludeVFS })
+                let type;
+                let excludeVFS = false;
+                if (typeof typeOrOptions === 'string') {
+                    type = typeOrOptions;
+                    excludeVFS = options?.excludeVFS ?? false;
+                }
+                else if (typeOrOptions && typeof typeOrOptions === 'object') {
+                    excludeVFS = typeOrOptions.excludeVFS ?? false;
+                }
+                if (excludeVFS) {
+                    const allCounts = this.metadataIndex.getAllEntityCounts();
+                    // Uses Roaring bitmap intersection - hardware accelerated
+                    const vfsCounts = await this.metadataIndex.getAllVFSEntityCounts();
+                    if (type) {
+                        const total = allCounts.get(type) || 0;
+                        const vfs = vfsCounts.get(type) || 0;
+                        return total - vfs;
+                    }
+                    // Return all counts with VFS subtracted
+                    const result = {};
+                    for (const [t, total] of allCounts) {
+                        const vfs = vfsCounts.get(t) || 0;
+                        const nonVfs = total - vfs;
+                        if (nonVfs > 0) {
+                            result[t] = nonVfs;
+                        }
+                    }
+                    return result;
+                }
+                // Default path (unchanged) - synchronous for backward compatibility
                 if (type) {
                     return this.metadataIndex.getEntityCountByType(type);
                 }
@@ -3447,7 +3484,32 @@ export class Brainy {
             // Get all type counts as Map for performance-critical operations
             getAllTypeCounts: () => this.metadataIndex.getAllEntityCounts(),
             // Get complete statistics
-            getStats: () => {
+            // v6.2.1: Added optional excludeVFS using Roaring bitmap intersection
+            getStats: async (options) => {
+                if (options?.excludeVFS) {
+                    const allCounts = this.metadataIndex.getAllEntityCounts();
+                    // Uses Roaring bitmap intersection - hardware accelerated
+                    const vfsCounts = await this.metadataIndex.getAllVFSEntityCounts();
+                    // Compute non-VFS counts via subtraction
+                    const byType = {};
+                    let total = 0;
+                    for (const [type, count] of allCounts) {
+                        const vfs = vfsCounts.get(type) || 0;
+                        const nonVfs = count - vfs;
+                        if (nonVfs > 0) {
+                            byType[type] = nonVfs;
+                            total += nonVfs;
+                        }
+                    }
+                    const entityStats = { total, byType };
+                    const relationshipStats = this.graphIndex.getRelationshipStats();
+                    return {
+                        entities: entityStats,
+                        relationships: relationshipStats,
+                        density: total > 0 ? relationshipStats.totalRelationships / total : 0
+                    };
+                }
+                // Default path (unchanged) - synchronous for backward compatibility
                 const entityStats = {
                     total: this.metadataIndex.getTotalEntityCount(),
                     byType: Object.fromEntries(this.metadataIndex.getAllEntityCounts())
@@ -3474,10 +3536,12 @@ export class Brainy {
     /**
      * Get complete statistics - convenience method
      * For more granular counting, use brain.counts API
+     * v6.2.1: Added optional excludeVFS using Roaring bitmap intersection
+     * @param options Optional settings - excludeVFS: filter out VFS entities
      * @returns Complete statistics including entities, relationships, and density
      */
-    getStats() {
-        return this.counts.getStats();
+    async getStats(options) {
+        return this.counts.getStats(options);
     }
     // ============= HELPER METHODS =============
     /**

package/dist/hnsw/hnswIndex.d.ts

@@ -83,6 +83,12 @@ export declare class HNSWIndex {
      * Add a vector to the index
      */
     addItem(item: VectorDocument): Promise<string>;
+    /**
+     * O(1) entry point recovery using highLevelNodes index (v6.2.3).
+     * At any reasonable scale (1000+ nodes), level 2+ nodes are guaranteed to exist.
+     * For tiny indexes with only level 0-1 nodes, any node works as entry point.
+     */
+    private recoverEntryPointO1;
     /**
      * Search for nearest neighbors
      */

package/dist/hnsw/hnswIndex.js

@@ -210,9 +210,8 @@ export class HNSWIndex {
         }
         // Find entry point
         if (!this.entryPointId) {
-            console.error('Entry point ID is null');
-            // If there's no entry point, this is the first noun, so we should have returned earlier
-            // This is a safety check
+            // No entry point but nouns exist - corrupted state, recover by using this item
+            // This shouldn't normally happen as first item sets entry point above
             this.entryPointId = id;
             this.maxLevel = nounLevel;
             this.nouns.set(id, noun);
@@ -220,7 +219,7 @@ export class HNSWIndex {
         }
         const entryPoint = this.nouns.get(this.entryPointId);
         if (!entryPoint) {
-            console.error(`Entry point with ID ${this.entryPointId} not found`);
+            // Entry point was deleted but ID not updated - recover by using new item
             // If the entry point doesn't exist, treat this as the first noun
             this.entryPointId = id;
             this.maxLevel = nounLevel;
@@ -383,6 +382,27 @@ export class HNSWIndex {
         }
         return id;
     }
+    /**
+     * O(1) entry point recovery using highLevelNodes index (v6.2.3).
+     * At any reasonable scale (1000+ nodes), level 2+ nodes are guaranteed to exist.
+     * For tiny indexes with only level 0-1 nodes, any node works as entry point.
+     */
+    recoverEntryPointO1() {
+        // O(1) recovery: check highLevelNodes from highest to lowest level
+        for (let level = this.MAX_TRACKED_LEVELS; level >= 2; level--) {
+            const nodesAtLevel = this.highLevelNodes.get(level);
+            if (nodesAtLevel && nodesAtLevel.size > 0) {
+                for (const nodeId of nodesAtLevel) {
+                    if (this.nouns.has(nodeId)) {
+                        return { id: nodeId, level };
+                    }
+                }
+            }
+        }
+        // No high-level nodes - use any available node (works fine for HNSW)
+        const firstNode = this.nouns.keys().next().value;
+        return { id: firstNode ?? null, level: 0 };
+    }
     /**
      * Search for nearest neighbors
      */
@@ -398,14 +418,33 @@ export class HNSWIndex {
             throw new Error(`Query vector dimension mismatch: expected ${this.dimension}, got ${queryVector.length}`);
         }
         // Start from the entry point
+        // If entry point is null but nouns exist, attempt O(1) recovery (v6.2.3)
+        if (!this.entryPointId && this.nouns.size > 0) {
+            const { id: recoveredId, level: recoveredLevel } = this.recoverEntryPointO1();
+            if (recoveredId) {
+                this.entryPointId = recoveredId;
+                this.maxLevel = recoveredLevel;
+            }
+        }
         if (!this.entryPointId) {
-            console.error('Entry point ID is null');
+            // Truly empty index - return empty results silently
             return [];
         }
-        const entryPoint = this.nouns.get(this.entryPointId);
+        let entryPoint = this.nouns.get(this.entryPointId);
         if (!entryPoint) {
-            console.error(`Entry point with ID ${this.entryPointId} not found`);
-            return [];
+            // Entry point ID exists but noun was deleted - O(1) recovery (v6.2.3)
+            if (this.nouns.size > 0) {
+                const { id: recoveredId, level: recoveredLevel } = this.recoverEntryPointO1();
+                if (recoveredId) {
+                    this.entryPointId = recoveredId;
+                    this.maxLevel = recoveredLevel;
+                    entryPoint = this.nouns.get(recoveredId);
+                }
+            }
+            // If still no entry point, return empty
+            if (!entryPoint) {
+                return [];
+            }
         }
         let currObj = entryPoint;
         // OPTIMIZATION: Preload entry point vector
@@ -915,6 +954,40 @@ export class HNSWIndex {
                     offset += batchSize; // v5.7.11: Increment offset for next page
                 }
             }
+            // Step 5: CRITICAL - Recover entry point if missing (v6.2.3 - O(1))
+            // This ensures consistency even if getHNSWSystem() returned null
+            if (this.nouns.size > 0 && this.entryPointId === null) {
+                prodLog.warn('HNSW rebuild: Entry point was null after loading nouns - recovering with O(1) lookup');
+                const { id: recoveredId, level: recoveredLevel } = this.recoverEntryPointO1();
+                this.entryPointId = recoveredId;
+                this.maxLevel = recoveredLevel;
+                prodLog.info(`HNSW entry point recovered: ${recoveredId} at level ${recoveredLevel}`);
+                // Persist recovered state to prevent future recovery
+                if (this.storage && recoveredId) {
+                    await this.storage.saveHNSWSystem({
+                        entryPointId: this.entryPointId,
+                        maxLevel: this.maxLevel
+                    }).catch((error) => {
+                        prodLog.error('Failed to persist recovered HNSW system data:', error);
+                    });
+                }
+            }
+            // Step 6: Validate entry point exists if set (handles stale/deleted entry point)
+            if (this.entryPointId && !this.nouns.has(this.entryPointId)) {
+                prodLog.warn(`HNSW: Entry point ${this.entryPointId} not found in loaded nouns - recovering with O(1) lookup`);
+                const { id: recoveredId, level: recoveredLevel } = this.recoverEntryPointO1();
+                this.entryPointId = recoveredId;
+                this.maxLevel = recoveredLevel;
+                // Persist corrected state
+                if (this.storage && recoveredId) {
+                    await this.storage.saveHNSWSystem({
+                        entryPointId: this.entryPointId,
+                        maxLevel: this.maxLevel
+                    }).catch((error) => {
+                        prodLog.error('Failed to persist corrected HNSW system data:', error);
+                    });
+                }
+            }
             const cacheInfo = shouldPreload
                 ? ` (vectors preloaded)`
                 : ` (adaptive caching - vectors loaded on-demand)`;

package/dist/index.d.ts

@@ -51,9 +51,8 @@ export { StorageAugmentation, DynamicStorageAugmentation, MemoryStorageAugmentat
 export { WebSocketConduitAugmentation };
 import type { Vector, VectorDocument, SearchResult, DistanceFunction, EmbeddingFunction, EmbeddingModel, HNSWNoun, HNSWVerb, HNSWConfig, StorageAdapter } from './coreTypes.js';
 import { HNSWIndex } from './hnsw/hnswIndex.js';
-import { HNSWIndexOptimized, HNSWOptimizedConfig } from './hnsw/hnswIndexOptimized.js';
-export { HNSWIndex, HNSWIndexOptimized };
-export type { Vector, VectorDocument, SearchResult, DistanceFunction, EmbeddingFunction, EmbeddingModel, HNSWNoun, HNSWVerb, HNSWConfig, HNSWOptimizedConfig, StorageAdapter };
+export { HNSWIndex };
+export type { Vector, VectorDocument, SearchResult, DistanceFunction, EmbeddingFunction, EmbeddingModel, HNSWNoun, HNSWVerb, HNSWConfig, StorageAdapter };
 import type { AugmentationResponse, BrainyAugmentation, BaseAugmentation, AugmentationContext } from './types/augmentations.js';
 export { AugmentationManager, type AugmentationInfo } from './augmentationManager.js';
 export type { AugmentationResponse, BrainyAugmentation, BaseAugmentation, AugmentationContext };

package/dist/index.js

@@ -111,10 +111,9 @@ MemoryStorageAugmentation, FileSystemStorageAugmentation, OPFSStorageAugmentatio
 createAutoStorageAugmentation, createStorageAugmentationFromConfig };
 // Other augmentation exports
 export { WebSocketConduitAugmentation };
-// Export HNSW index and optimized version
+// Export HNSW index
 import { HNSWIndex } from './hnsw/hnswIndex.js';
-import { HNSWIndexOptimized } from './hnsw/hnswIndexOptimized.js';
-export { HNSWIndex, HNSWIndexOptimized };
+export { HNSWIndex };
 // Export augmentation manager for type-safe augmentation management
 export { AugmentationManager } from './augmentationManager.js';
 import { NounType, VerbType } from './types/graphTypes.js';

package/dist/storage/adapters/azureBlobStorage.js

@@ -1269,7 +1269,15 @@ export class AzureBlobStorage extends BaseStorage {
             return JSON.parse(downloaded.toString());
         }
         catch (error) {
-            if (error.statusCode === 404 || error.code === 'BlobNotFound') {
+            // Azure may return not found errors in different formats
+            const isNotFound = error.statusCode === 404 ||
+                error.code === 'BlobNotFound' ||
+                error.code === 404 ||
+                error.details?.code === 'BlobNotFound' ||
+                error.message?.includes('BlobNotFound') ||
+                error.message?.includes('not found') ||
+                error.message?.includes('404');
+            if (isNotFound) {
                 return null;
             }
             this.logger.error('Failed to get HNSW system data:', error);

package/dist/storage/adapters/gcsStorage.js

@@ -1260,7 +1260,14 @@ export class GcsStorage extends BaseStorage {
             return JSON.parse(contents.toString());
         }
         catch (error) {
-            if (error.code === 404) {
+            // GCS may return 404 in different formats depending on SDK version
+            const is404 = error.code === 404 ||
+                error.statusCode === 404 ||
+                error.status === 404 ||
+                error.message?.includes('No such object') ||
+                error.message?.includes('not found') ||
+                error.message?.includes('404');
+            if (is404) {
                 return null;
             }
             this.logger.error('Failed to get HNSW system data:', error);

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -2829,9 +2829,14 @@ export class S3CompatibleStorage extends BaseStorage {
             return JSON.parse(bodyContents);
         }
         catch (error) {
-            if (error.name === 'NoSuchKey' ||
+            // S3 may return not found errors in different formats
+            const isNotFound = error.name === 'NoSuchKey' ||
+                error.code === 'NoSuchKey' ||
+                error.$metadata?.httpStatusCode === 404 ||
                 error.message?.includes('NoSuchKey') ||
-                error.message?.includes('not found')) {
+                error.message?.includes('not found') ||
+                error.message?.includes('404');
+            if (isNotFound) {
                 return null;
             }
             this.logger.error('Failed to get HNSW system data:', error);

package/dist/triple/TripleIntelligenceSystem.d.ts

@@ -13,7 +13,6 @@
  * - Fusion: O(k log k) where k = result count
  */
 import { HNSWIndex } from '../hnsw/hnswIndex.js';
-import { HNSWIndexOptimized } from '../hnsw/hnswIndexOptimized.js';
 import { TypeAwareHNSWIndex } from '../hnsw/typeAwareHNSWIndex.js';
 import { MetadataIndexManager } from '../utils/metadataIndex.js';
 import { Vector } from '../coreTypes.js';
@@ -68,7 +67,7 @@ export declare class TripleIntelligenceSystem {
     private planner;
     private embedder;
     private storage;
-    constructor(metadataIndex: MetadataIndexManager, hnswIndex: HNSWIndex | HNSWIndexOptimized | TypeAwareHNSWIndex, graphIndex: GraphAdjacencyIndex, embedder: (text: string) => Promise<Vector>, storage: any);
+    constructor(metadataIndex: MetadataIndexManager, hnswIndex: HNSWIndex | TypeAwareHNSWIndex, graphIndex: GraphAdjacencyIndex, embedder: (text: string) => Promise<Vector>, storage: any);
     /**
      * Main find method - executes Triple Intelligence queries
      * Phase 3: Now with automatic type inference for 40% latency reduction

package/dist/utils/metadataIndex.d.ts

@@ -436,6 +436,23 @@ export declare class MetadataIndexManager {
      * Get all entity types and their counts - O(1) operation
      */
     getAllEntityCounts(): Map<string, number>;
+    /**
+     * Get VFS entity count for a specific type using Roaring bitmap intersection
+     * Uses hardware-accelerated SIMD operations (AVX2/SSE4.2)
+     * @param type The noun type to query
+     * @returns Count of VFS entities of this type
+     */
+    getVFSEntityCountByType(type: string): Promise<number>;
+    /**
+     * Get all VFS entity counts by type using Roaring bitmap operations
+     * @returns Map of type -> VFS entity count
+     */
+    getAllVFSEntityCounts(): Promise<Map<string, number>>;
+    /**
+     * Get total count of VFS entities - O(1) using Roaring bitmap cardinality
+     * @returns Total VFS entity count
+     */
+    getTotalVFSEntityCount(): Promise<number>;
     /**
      * Get entity count for a noun type using type enum (O(1) array access)
      * More efficient than Map-based getEntityCountByType

package/dist/utils/metadataIndex.js

@@ -1230,6 +1230,21 @@ export class MetadataIndexManager {
                 const subIds = await this.getIdsForFilter(subFilter);
                 subIds.forEach(id => unionIds.add(id));
             }
+            // v6.2.1: Fix - Check for outer-level field conditions that need AND application
+            // This handles cases like { anyOf: [...], vfsType: { exists: false } }
+            // where the anyOf results must be intersected with other field conditions
+            const outerFields = Object.keys(filter).filter((k) => k !== 'anyOf' && k !== 'allOf' && k !== 'not');
+            if (outerFields.length > 0) {
+                // Build filter with just outer fields and get matching IDs
+                const outerFilter = {};
+                for (const field of outerFields) {
+                    outerFilter[field] = filter[field];
+                }
+                const outerIds = await this.getIdsForFilter(outerFilter);
+                const outerIdSet = new Set(outerIds);
+                // Intersect: anyOf union AND outer field conditions
+                return Array.from(unionIds).filter((id) => outerIdSet.has(id));
+            }
             return Array.from(unionIds);
         }
         // Process field filters with range support
@@ -1865,6 +1880,54 @@ export class MetadataIndexManager {
         return new Map(this.totalEntitiesByType);
     }
     // ============================================================================
+    // v6.2.1: VFS Statistics Methods (uses existing Roaring bitmap infrastructure)
+    // ============================================================================
+    /**
+     * Get VFS entity count for a specific type using Roaring bitmap intersection
+     * Uses hardware-accelerated SIMD operations (AVX2/SSE4.2)
+     * @param type The noun type to query
+     * @returns Count of VFS entities of this type
+     */
+    async getVFSEntityCountByType(type) {
+        const vfsBitmap = await this.getBitmapFromChunks('isVFSEntity', true);
+        const typeBitmap = await this.getBitmapFromChunks('noun', type);
+        if (!vfsBitmap || !typeBitmap)
+            return 0;
+        // Hardware-accelerated intersection + O(1) cardinality
+        const intersection = RoaringBitmap32.and(vfsBitmap, typeBitmap);
+        return intersection.size;
+    }
+    /**
+     * Get all VFS entity counts by type using Roaring bitmap operations
+     * @returns Map of type -> VFS entity count
+     */
+    async getAllVFSEntityCounts() {
+        const vfsBitmap = await this.getBitmapFromChunks('isVFSEntity', true);
+        if (!vfsBitmap || vfsBitmap.size === 0) {
+            return new Map();
+        }
+        const result = new Map();
+        // Iterate through all known types and compute VFS count via intersection
+        for (const type of this.totalEntitiesByType.keys()) {
+            const typeBitmap = await this.getBitmapFromChunks('noun', type);
+            if (typeBitmap) {
+                const intersection = RoaringBitmap32.and(vfsBitmap, typeBitmap);
+                if (intersection.size > 0) {
+                    result.set(type, intersection.size);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Get total count of VFS entities - O(1) using Roaring bitmap cardinality
+     * @returns Total VFS entity count
+     */
+    async getTotalVFSEntityCount() {
+        const vfsBitmap = await this.getBitmapFromChunks('isVFSEntity', true);
+        return vfsBitmap?.size ?? 0;
+    }
+    // ============================================================================
     // Phase 1b: Type Enum Methods (O(1) access via Uint32Arrays)
     // ============================================================================
     /**

package/package.json

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