@soulcraft/brainy 4.7.4 → 4.8.1

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

@@ -89,6 +89,10 @@ export interface AddParams<T = any> {
     service?: string;
     confidence?: number;
     weight?: number;
+    createdBy?: {
+        augmentation: string;
+        version: string;
+    };
 }
 /**
  * Parameters for updating entities

package/dist/types/graphTypes.d.ts

@@ -206,6 +206,7 @@ export interface GraphVerb {
     createdAt: Timestamp;
     updatedAt: Timestamp;
     createdBy: CreatorMetadata;
+    service?: string;
     data?: Record<string, any>;
     embedding?: number[];
     confidence?: number;

package/dist/utils/entityIdMapper.js

@@ -33,8 +33,9 @@ export class EntityIdMapper {
     async init() {
         try {
             const metadata = await this.storage.getMetadata(this.storageKey);
-            if (metadata && metadata.data) {
-                const data = metadata.data;
+            // v4.8.0: metadata IS the data (no nested 'data' property)
+            if (metadata && metadata.nextId !== undefined) {
+                const data = metadata;
                 this.nextId = data.nextId;
                 // Rebuild maps from serialized data
                 this.uuidToInt = new Map(Object.entries(data.uuidToInt).map(([k, v]) => [k, Number(v)]));

package/dist/utils/metadataIndex.d.ts

@@ -228,7 +228,13 @@ export declare class MetadataIndexManager {
      */
     private shouldIndexField;
     /**
-     * Extract indexable field-value pairs from metadata
+     * Extract indexable field-value pairs from entity or metadata
+     *
+     * v4.8.0: Now handles BOTH entity structure (with top-level fields) AND plain metadata
+     * - Extracts from top-level fields (confidence, weight, timestamps, type, service, etc.)
+     * - Also extracts from nested metadata field (custom user fields)
+     * - Skips HNSW-specific fields (vector, connections, level, id)
+     * - Maps 'type' → 'noun' for backward compatibility with existing indexes
      *
      * BUG FIX (v3.50.1): Exclude vector embeddings and large arrays from indexing
      * BUG FIX (v3.50.2): Also exclude purely numeric field names (array indices)
@@ -238,14 +244,29 @@ export declare class MetadataIndexManager {
     private extractIndexableFields;
     /**
      * Add item to metadata indexes
+     *
+     * v4.8.0: Now accepts either entity structure or plain metadata
+     * - Entity structure: { id, type, confidence, weight, createdAt, metadata: {...} }
+     * - Plain metadata: { noun, confidence, weight, createdAt, ... }
+     *
+     * @param id - Entity ID
+     * @param entityOrMetadata - Either full entity structure (v4.8.0+) or plain metadata (backward compat)
+     * @param skipFlush - Skip automatic flush (used during batch operations)
      */
-    addToIndex(id: string, metadata: any, skipFlush?: boolean): Promise<void>;
+    addToIndex(id: string, entityOrMetadata: any, skipFlush?: boolean): Promise<void>;
     /**
      * Update field index with value count
      */
     private updateFieldIndex;
     /**
      * Remove item from metadata indexes
+     *
+     * v4.8.0: Now accepts either entity structure or plain metadata (same as addToIndex)
+     * - Entity structure: { id, type, confidence, weight, createdAt, metadata: {...} }
+     * - Plain metadata: { noun, confidence, weight, createdAt, ... }
+     *
+     * @param id - Entity ID to remove
+     * @param metadata - Optional entity or metadata structure (if not provided, requires scanning all fields - slow!)
      */
     removeFromIndex(id: string, metadata?: any): Promise<void>;
     /**

package/dist/utils/metadataIndex.js

@@ -856,22 +856,28 @@ export class MetadataIndexManager {
         return true;
     }
     /**
-     * Extract indexable field-value pairs from metadata
+     * Extract indexable field-value pairs from entity or metadata
+     *
+     * v4.8.0: Now handles BOTH entity structure (with top-level fields) AND plain metadata
+     * - Extracts from top-level fields (confidence, weight, timestamps, type, service, etc.)
+     * - Also extracts from nested metadata field (custom user fields)
+     * - Skips HNSW-specific fields (vector, connections, level, id)
+     * - Maps 'type' → 'noun' for backward compatibility with existing indexes
      *
      * BUG FIX (v3.50.1): Exclude vector embeddings and large arrays from indexing
      * BUG FIX (v3.50.2): Also exclude purely numeric field names (array indices)
      * - Vector fields (384+ dimensions) were creating 825K chunk files for 1,144 entities
      * - Arrays converted to objects with numeric keys were still being indexed
      */
-    extractIndexableFields(metadata) {
+    extractIndexableFields(data) {
         const fields = [];
-        // Fields that should NEVER be indexed (vectors, embeddings, large arrays)
-        const NEVER_INDEX = new Set(['vector', 'embedding', 'embeddings', 'connections']);
+        // Fields that should NEVER be indexed (vectors, embeddings, large arrays, HNSW internals)
+        const NEVER_INDEX = new Set(['vector', 'embedding', 'embeddings', 'connections', 'level', 'id']);
         const extract = (obj, prefix = '') => {
             for (const [key, value] of Object.entries(obj)) {
                 const fullKey = prefix ? `${prefix}.${key}` : key;
-                // Skip fields in never-index list (CRITICAL: prevents vector indexing bug)
-                if (NEVER_INDEX.has(key))
+                // Skip fields in never-index list (CRITICAL: prevents vector indexing bug + HNSW fields)
+                if (!prefix && NEVER_INDEX.has(key))
                     continue;
                 // Skip purely numeric field names (array indices converted to object keys)
                 // Legitimate field names should never be purely numeric
@@ -881,6 +887,14 @@ export class MetadataIndexManager {
                 // Skip fields based on user configuration
                 if (!this.shouldIndexField(fullKey))
                     continue;
+                // Special handling for metadata field at top level
+                // v4.8.0: Flatten metadata fields to top-level (no prefix) for cleaner queries
+                // Standard fields are already at top-level, custom fields go in metadata
+                // By flattening here, queries can use { category: 'B' } instead of { 'metadata.category': 'B' }
+                if (key === 'metadata' && !prefix && typeof value === 'object' && !Array.isArray(value)) {
+                    extract(value, ''); // Flatten to top-level, no prefix
+                    continue;
+                }
                 // Skip large arrays (> 10 elements) - likely vectors or bulk data
                 if (Array.isArray(value) && value.length > 10)
                     continue;
@@ -900,20 +914,30 @@ export class MetadataIndexManager {
                 }
                 else {
                     // Primitive value: index it
-                    fields.push({ field: fullKey, value });
+                    // v4.8.0: Map 'type' → 'noun' for backward compatibility
+                    const indexField = (!prefix && key === 'type') ? 'noun' : fullKey;
+                    fields.push({ field: indexField, value });
                 }
             }
         };
-        if (metadata && typeof metadata === 'object') {
-            extract(metadata);
+        if (data && typeof data === 'object') {
+            extract(data);
         }
         return fields;
     }
     /**
      * Add item to metadata indexes
+     *
+     * v4.8.0: Now accepts either entity structure or plain metadata
+     * - Entity structure: { id, type, confidence, weight, createdAt, metadata: {...} }
+     * - Plain metadata: { noun, confidence, weight, createdAt, ... }
+     *
+     * @param id - Entity ID
+     * @param entityOrMetadata - Either full entity structure (v4.8.0+) or plain metadata (backward compat)
+     * @param skipFlush - Skip automatic flush (used during batch operations)
      */
-    async addToIndex(id, metadata, skipFlush = false) {
-        const fields = this.extractIndexableFields(metadata);
+    async addToIndex(id, entityOrMetadata, skipFlush = false) {
+        const fields = this.extractIndexableFields(entityOrMetadata);
         // Sort fields to process 'noun' field first for type-field affinity tracking
         fields.sort((a, b) => {
             if (a.field === 'noun')
@@ -930,7 +954,7 @@ export class MetadataIndexManager {
             await this.addToChunkedIndex(field, value, id);
             // Update statistics and tracking
             this.updateCardinalityStats(field, value, 'add');
-            this.updateTypeFieldAffinity(id, field, value, 'add', metadata);
+            this.updateTypeFieldAffinity(id, field, value, 'add', entityOrMetadata);
             await this.updateFieldIndex(field, value, 1);
             // Yield to event loop every 5 fields to prevent blocking
             if (i % 5 === 4) {
@@ -988,6 +1012,13 @@ export class MetadataIndexManager {
     }
     /**
      * Remove item from metadata indexes
+     *
+     * v4.8.0: Now accepts either entity structure or plain metadata (same as addToIndex)
+     * - Entity structure: { id, type, confidence, weight, createdAt, metadata: {...} }
+     * - Plain metadata: { noun, confidence, weight, createdAt, ... }
+     *
+     * @param id - Entity ID to remove
+     * @param metadata - Optional entity or metadata structure (if not provided, requires scanning all fields - slow!)
      */
     async removeFromIndex(id, metadata) {
         if (metadata) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "4.7.4",
+  "version": "4.8.1",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",