@soulcraft/brainy 6.2.2 → 6.2.4

package/dist/storage/baseStorage.d.ts

@@ -618,6 +618,18 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Periodically called when counts are updated
      */
     protected saveTypeStatistics(): Promise<void>;
+    /**
+     * Get noun counts by type (O(1) access to type statistics)
+     * v6.2.2: Exposed for MetadataIndexManager to use as single source of truth
+     * @returns Uint32Array indexed by NounType enum value (42 types)
+     */
+    getNounCountsByType(): Uint32Array;
+    /**
+     * Get verb counts by type (O(1) access to type statistics)
+     * v6.2.2: Exposed for MetadataIndexManager to use as single source of truth
+     * @returns Uint32Array indexed by VerbType enum value (127 types)
+     */
+    getVerbCountsByType(): Uint32Array;
     /**
      * Rebuild type counts from actual storage (v5.5.0)
      * Called when statistics are missing or inconsistent

package/dist/storage/baseStorage.js

@@ -1983,6 +1983,22 @@ export class BaseStorage extends BaseStorageAdapter {
         };
         await this.writeObjectToPath(`${SYSTEM_DIR}/type-statistics.json`, stats);
     }
+    /**
+     * Get noun counts by type (O(1) access to type statistics)
+     * v6.2.2: Exposed for MetadataIndexManager to use as single source of truth
+     * @returns Uint32Array indexed by NounType enum value (42 types)
+     */
+    getNounCountsByType() {
+        return this.nounCountsByType;
+    }
+    /**
+     * Get verb counts by type (O(1) access to type statistics)
+     * v6.2.2: Exposed for MetadataIndexManager to use as single source of truth
+     * @returns Uint32Array indexed by VerbType enum value (127 types)
+     */
+    getVerbCountsByType() {
+        return this.verbCountsByType;
+    }
     /**
      * Rebuild type counts from actual storage (v5.5.0)
      * Called when statistics are missing or inconsistent

package/dist/types/brainyDataInterface.d.ts

@@ -0,0 +1,52 @@
+/**
+ * BrainyInterface - Modern API Only
+ *
+ * This interface defines the MODERN methods from Brainy 3.0.
+ * Used to break circular dependencies while enforcing modern API usage.
+ *
+ * NO DEPRECATED METHODS - Only clean, modern API patterns.
+ */
+import { Vector } from '../coreTypes.js';
+import { AddParams, RelateParams, Result, Entity, FindParams, SimilarParams } from './brainy.types.js';
+export interface BrainyInterface<T = unknown> {
+    /**
+     * Initialize the database
+     */
+    init(): Promise<void>;
+    /**
+     * Modern add method - unified entity creation
+     * @param params Parameters for adding entities
+     * @returns The ID of the created entity
+     */
+    add(params: AddParams<T>): Promise<string>;
+    /**
+     * Modern relate method - unified relationship creation
+     * @param params Parameters for creating relationships
+     * @returns The ID of the created relationship
+     */
+    relate(params: RelateParams<T>): Promise<string>;
+    /**
+     * Modern find method - unified search and discovery
+     * @param query Search query or parameters object
+     * @returns Array of search results
+     */
+    find(query: string | FindParams<T>): Promise<Result<T>[]>;
+    /**
+     * Modern get method - retrieve entities by ID
+     * @param id The entity ID to retrieve
+     * @returns Entity or null if not found
+     */
+    get(id: string): Promise<Entity<T> | null>;
+    /**
+     * Modern similar method - find similar entities
+     * @param params Parameters for similarity search
+     * @returns Array of similar entities with scores
+     */
+    similar(params: SimilarParams<T>): Promise<Result<T>[]>;
+    /**
+     * Generate embedding vector from text
+     * @param text The text to embed
+     * @returns Vector representation of the text
+     */
+    embed(text: string): Promise<Vector>;
+}

package/dist/types/brainyDataInterface.js

@@ -0,0 +1,10 @@
+/**
+ * BrainyInterface - Modern API Only
+ *
+ * This interface defines the MODERN methods from Brainy 3.0.
+ * Used to break circular dependencies while enforcing modern API usage.
+ *
+ * NO DEPRECATED METHODS - Only clean, modern API patterns.
+ */
+export {};
+//# sourceMappingURL=brainyDataInterface.js.map

package/dist/utils/metadataIndex.d.ts

@@ -112,8 +112,9 @@ export declare class MetadataIndexManager {
      */
     private releaseLock;
     /**
-     * Lazy load entity counts from storage statistics (O(1) operation)
-     * This avoids rebuilding the entire index on startup
+     * Lazy load entity counts from the 'noun' field sparse index (O(n) where n = number of types)
+     * v6.2.2 FIX: Previously read from stats.nounCount which was SERVICE-keyed, not TYPE-keyed
+     * Now computes counts from the sparse index which has the correct type information
      */
     private lazyLoadCounts;
     /**
@@ -434,6 +435,9 @@ export declare class MetadataIndexManager {
     getTotalEntityCount(): number;
     /**
      * Get all entity types and their counts - O(1) operation
+     * v6.2.2: Fixed - totalEntitiesByType is correctly populated by updateTypeFieldAffinity
+     * during add operations. lazyLoadCounts was reading wrong data but that doesn't
+     * affect freshly-added entities within the same session.
      */
     getAllEntityCounts(): Map<string, number>;
     /**

package/dist/utils/metadataIndex.js

@@ -84,8 +84,9 @@ export class MetadataIndexManager {
         this.chunkingStrategy = new AdaptiveChunkingStrategy();
         // Initialize Field Type Inference (v3.48.0)
         this.fieldTypeInference = new FieldTypeInference(storage);
-        // Lazy load counts from storage statistics on first access
-        this.lazyLoadCounts();
+        // v6.2.2: Removed lazyLoadCounts() call from constructor
+        // It was a race condition (not awaited) and read from wrong source.
+        // Now properly called in init() after warmCache() loads the sparse index.
     }
     /**
      * Initialize the metadata index manager
@@ -97,11 +98,15 @@ export class MetadataIndexManager {
         await this.loadFieldRegistry();
         // Initialize EntityIdMapper (loads UUID ↔ integer mappings from storage)
         await this.idMapper.init();
-        // Phase 1b: Sync loaded counts to fixed-size arrays
-        // This populates the Uint32Arrays from the Maps loaded by lazyLoadCounts()
-        this.syncTypeCountsToFixed();
         // Warm the cache with common fields (v3.44.1 - lazy loading optimization)
+        // This loads the 'noun' sparse index which is needed for type counts
         await this.warmCache();
+        // v6.2.2: Load type counts AFTER warmCache (sparse index is now cached)
+        // Previously called in constructor without await and read from wrong source
+        await this.lazyLoadCounts();
+        // Phase 1b: Sync loaded counts to fixed-size arrays
+        // Now correctly happens AFTER lazyLoadCounts() finishes
+        this.syncTypeCountsToFixed();
     }
     /**
      * Warm the cache by preloading common field sparse indices (v3.44.1)
@@ -226,25 +231,34 @@ export class MetadataIndexManager {
         this.activeLocks.delete(lockKey);
     }
     /**
-     * Lazy load entity counts from storage statistics (O(1) operation)
-     * This avoids rebuilding the entire index on startup
+     * Lazy load entity counts from the 'noun' field sparse index (O(n) where n = number of types)
+     * v6.2.2 FIX: Previously read from stats.nounCount which was SERVICE-keyed, not TYPE-keyed
+     * Now computes counts from the sparse index which has the correct type information
      */
     async lazyLoadCounts() {
         try {
-            // Get statistics from storage (should be O(1) with our FileSystemStorage improvements)
-            const stats = await this.storage.getStatistics();
-            if (stats && stats.nounCount) {
-                // Populate entity counts from storage statistics
-                for (const [type, count] of Object.entries(stats.nounCount)) {
-                    if (typeof count === 'number' && count > 0) {
-                        this.totalEntitiesByType.set(type, count);
+            // v6.2.2: Load counts from sparse index (correct source)
+            const nounSparseIndex = await this.loadSparseIndex('noun');
+            if (!nounSparseIndex) {
+                // No sparse index yet - counts will be populated as entities are added
+                return;
+            }
+            // Iterate through all chunks and sum up bitmap sizes by type
+            for (const chunkId of nounSparseIndex.getAllChunkIds()) {
+                const chunk = await this.chunkManager.loadChunk('noun', chunkId);
+                if (chunk) {
+                    for (const [type, bitmap] of chunk.entries) {
+                        const currentCount = this.totalEntitiesByType.get(type) || 0;
+                        this.totalEntitiesByType.set(type, currentCount + bitmap.size);
                     }
                 }
             }
+            prodLog.debug(`✅ Loaded type counts from sparse index: ${this.totalEntitiesByType.size} types`);
         }
         catch (error) {
             // Silently fail - counts will be populated as entities are added
             // This maintains zero-configuration principle
+            prodLog.debug('Could not load type counts from sparse index:', error);
         }
     }
     /**
@@ -1875,6 +1889,9 @@ export class MetadataIndexManager {
     }
     /**
      * Get all entity types and their counts - O(1) operation
+     * v6.2.2: Fixed - totalEntitiesByType is correctly populated by updateTypeFieldAffinity
+     * during add operations. lazyLoadCounts was reading wrong data but that doesn't
+     * affect freshly-added entities within the same session.
      */
     getAllEntityCounts() {
         return new Map(this.totalEntitiesByType);

package/dist/vfs/ConceptSystem.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Universal Concept System for VFS
+ *
+ * Manages concepts that transcend files and exist independently
+ * Ideas that can be linked to multiple manifestations across domains
+ * PRODUCTION-READY: Real implementation using Brainy
+ */
+import { Brainy } from '../brainy.js';
+import { EntityManager, ManagedEntity } from './EntityManager.js';
+/**
+ * Universal concept that exists independently of files
+ */
+export interface UniversalConcept extends ManagedEntity {
+    id: string;
+    name: string;
+    description?: string;
+    domain: string;
+    category: string;
+    keywords: string[];
+    links: ConceptLink[];
+    manifestations: ConceptManifestation[];
+    strength: number;
+    created: number;
+    lastUpdated: number;
+    version: number;
+    metadata: Record<string, any>;
+    conceptType?: string;
+}
+/**
+ * A link between concepts
+ */
+export interface ConceptLink {
+    id: string;
+    targetConceptId: string;
+    relationship: 'extends' | 'implements' | 'uses' | 'opposite' | 'related' | 'contains' | 'part-of';
+    strength: number;
+    context?: string;
+    bidirectional: boolean;
+}
+/**
+ * A manifestation of a concept in a specific location
+ */
+export interface ConceptManifestation extends ManagedEntity {
+    id: string;
+    conceptId: string;
+    filePath: string;
+    context: string;
+    form: 'definition' | 'usage' | 'example' | 'discussion' | 'implementation';
+    position?: {
+        line?: number;
+        column?: number;
+        offset?: number;
+    };
+    confidence: number;
+    timestamp: number;
+    extractedBy: 'manual' | 'auto' | 'ai';
+}
+/**
+ * Configuration for concept system
+ */
+export interface ConceptSystemConfig {
+    autoLink?: boolean;
+    similarityThreshold?: number;
+    maxManifestations?: number;
+    strengthDecay?: number;
+}
+/**
+ * Concept graph structure for visualization
+ */
+export interface ConceptGraph {
+    concepts: Array<{
+        id: string;
+        name: string;
+        domain: string;
+        strength: number;
+        manifestationCount: number;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        relationship: string;
+        strength: number;
+    }>;
+}
+/**
+ * Universal Concept System
+ *
+ * Manages concepts that exist independently of any specific file or context
+ * Examples:
+ * - "Authentication" concept appearing in docs, code, tests
+ * - "Customer Journey" concept in marketing, UX, analytics
+ * - "Dependency Injection" pattern across multiple codebases
+ * - "Sustainability" theme in various research papers
+ */
+export declare class ConceptSystem extends EntityManager {
+    private config;
+    private conceptCache;
+    constructor(brain: Brainy, config?: ConceptSystemConfig);
+    /**
+     * Create a new universal concept
+     */
+    createConcept(concept: Omit<UniversalConcept, 'id' | 'created' | 'lastUpdated' | 'version' | 'links' | 'manifestations'>): Promise<string>;
+    /**
+     * Find concepts by various criteria
+     */
+    findConcepts(query: {
+        name?: string;
+        domain?: string;
+        category?: string;
+        keywords?: string[];
+        similar?: string;
+        manifestedIn?: string;
+    }): Promise<UniversalConcept[]>;
+    /**
+     * Link two concepts together
+     */
+    linkConcept(fromConceptId: string, toConceptId: string, relationship: ConceptLink['relationship'], options?: {
+        strength?: number;
+        context?: string;
+        bidirectional?: boolean;
+    }): Promise<string>;
+    /**
+     * Record a manifestation of a concept in a file
+     */
+    recordManifestation(conceptId: string, filePath: string, context: string, form: ConceptManifestation['form'], options?: {
+        position?: ConceptManifestation['position'];
+        confidence?: number;
+        extractedBy?: ConceptManifestation['extractedBy'];
+    }): Promise<string>;
+    /**
+     * Extract and link concepts from content
+     */
+    extractAndLinkConcepts(filePath: string, content: Buffer): Promise<string[]>;
+    /**
+     * Get concept graph for visualization
+     */
+    getConceptGraph(options?: {
+        domain?: string;
+        minStrength?: number;
+        maxConcepts?: number;
+    }): Promise<ConceptGraph>;
+    /**
+     * Find appearances of a concept
+     */
+    findAppearances(conceptId: string, options?: {
+        filePath?: string;
+        form?: ConceptManifestation['form'];
+        minConfidence?: number;
+        limit?: number;
+    }): Promise<ConceptManifestation[]>;
+    /**
+     * Auto-link concept to similar concepts
+     */
+    private autoLinkConcept;
+    /**
+     * Get concept by ID
+     */
+    private getConcept;
+    /**
+     * Update stored concept
+     */
+    private updateConcept;
+    /**
+     * Calculate similarity between two concepts
+     */
+    private calculateConceptSimilarity;
+    /**
+     * Generate embedding for concept
+     */
+    private generateConceptEmbedding;
+    /**
+     * Generate embedding for text
+     */
+    private generateTextEmbedding;
+    /**
+     * Get reverse relationship type
+     */
+    private getReverseRelationship;
+    /**
+     * Map concept relationship to VerbType
+     */
+    private getVerbType;
+    /**
+     * Detect concept domain from context
+     */
+    private detectDomain;
+    /**
+     * Detect concept category
+     */
+    private detectCategory;
+    /**
+     * Detect manifestation form from context
+     */
+    private detectManifestationForm;
+    /**
+     * Extract context around a position
+     */
+    private extractContext;
+    /**
+     * Clear concept cache
+     */
+    clearCache(conceptId?: string): void;
+}