@soulcraft/brainy 4.7.4 → 4.8.0

package/dist/storage/adapters/gcsStorage.js

@@ -8,6 +8,7 @@
  * 3. Service Account Credentials Object
  * 4. HMAC Keys (fallback for backward compatibility)
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, SYSTEM_DIR, STATISTICS_KEY, getDirectoryPath } from '../baseStorage.js';
 import { BrainyError } from '../../errors/brainyError.js';
 import { CacheManager } from '../cacheManager.js';
@@ -832,13 +833,23 @@ export class GcsStorage extends BaseStorage {
                         continue;
                 }
             }
-            // Combine node with metadata
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = (metadata || {});
+            const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
             const nounWithMetadata = {
                 id: node.id,
                 vector: [...node.vector],
                 connections: new Map(node.connections),
                 level: node.level || 0,
-                metadata: (metadata || {}) // Empty if none
+                type: nounType || NounType.Thing,
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                metadata: customMetadata
             };
             items.push(nounWithMetadata);
         }
@@ -1076,7 +1087,9 @@ export class GcsStorage extends BaseStorage {
                             continue;
                     }
                 }
-                // Combine verb with metadata
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const verbWithMetadata = {
                     id: hnswVerb.id,
                     vector: [...hnswVerb.vector],
@@ -1084,7 +1097,14 @@ export class GcsStorage extends BaseStorage {
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,
-                    metadata: metadata || {}
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 items.push(verbWithMetadata);
             }

package/dist/storage/adapters/memoryStorage.js

@@ -2,6 +2,7 @@
  * Memory Storage Adapter
  * In-memory storage adapter for environments where persistent storage is not available or needed
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage } from '../baseStorage.js';
 // No type aliases needed - using the original types directly
 /**
@@ -154,13 +155,26 @@ export class MemoryStorage extends BaseStorage {
             // Get metadata from separate storage
             // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
             const metadata = await this.getNounMetadata(id);
-            // v4.0.0: Create HNSWNounWithMetadata with metadata field
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = (metadata || {});
+            const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
+            // v4.8.0: Create HNSWNounWithMetadata with standard fields at top-level
             const nounWithMetadata = {
                 id: noun.id,
                 vector: [...noun.vector],
                 connections: new Map(),
                 level: noun.level || 0,
-                metadata: (metadata || {}) // Include metadata field (empty if none)
+                // v4.8.0: Standard fields at top-level
+                type: nounType || NounType.Thing,
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                // Only custom user fields in metadata
+                metadata: customMetadata
             };
             // Copy connections
             for (const [level, connections] of noun.connections.entries()) {
@@ -359,7 +373,10 @@ export class MemoryStorage extends BaseStorage {
             // FIX v4.7.4: Don't skip verbs without metadata - metadata is optional in v4.0.0
             // Core fields (verb, sourceId, targetId) are in HNSWVerb itself
             const metadata = await this.getVerbMetadata(id);
-            // v4.0.0: Create HNSWVerbWithMetadata with metadata field
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = metadata || {};
+            const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
+            // v4.8.0: Create HNSWVerbWithMetadata with standard fields at top-level
             const verbWithMetadata = {
                 id: hnswVerb.id,
                 vector: [...hnswVerb.vector],
@@ -368,8 +385,16 @@ export class MemoryStorage extends BaseStorage {
                 verb: hnswVerb.verb,
                 sourceId: hnswVerb.sourceId,
                 targetId: hnswVerb.targetId,
-                // Metadata field (empty if none)
-                metadata: metadata || {}
+                // v4.8.0: Standard fields at top-level
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                // Only custom user fields in metadata
+                metadata: customMetadata
             };
             // Copy connections
             for (const [level, connections] of hnswVerb.connections.entries()) {

package/dist/storage/adapters/opfsStorage.js

@@ -2,6 +2,7 @@
  * OPFS (Origin Private File System) Storage Adapter
  * Provides persistent storage for the vector database using the Origin Private File System API
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, NOUNS_DIR, VERBS_DIR, METADATA_DIR, NOUN_METADATA_DIR, VERB_METADATA_DIR, INDEX_DIR } from '../baseStorage.js';
 import { getShardIdFromUuid } from '../sharding.js';
 import '../../types/fileSystemTypes.js';
@@ -1446,13 +1447,23 @@ export class OPFSStorage extends BaseStorage {
                             continue;
                     }
                 }
-                // v4.0.0: Create HNSWNounWithMetadata by combining noun with metadata
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const nounWithMetadata = {
                     id: noun.id,
                     vector: [...noun.vector],
                     connections: new Map(noun.connections),
                     level: noun.level || 0,
-                    metadata: (metadata || {}) // Empty if none
+                    type: nounType || NounType.Thing,
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 items.push(nounWithMetadata);
             }
@@ -1572,7 +1583,9 @@ export class OPFSStorage extends BaseStorage {
                             continue;
                     }
                 }
-                // v4.0.0: Create HNSWVerbWithMetadata by combining verb with metadata
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const verbWithMetadata = {
                     id: hnswVerb.id,
                     vector: [...hnswVerb.vector],
@@ -1580,7 +1593,14 @@ export class OPFSStorage extends BaseStorage {
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,
-                    metadata: (metadata || {}) // Empty if none
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 items.push(verbWithMetadata);
             }

package/dist/storage/adapters/r2Storage.js

@@ -11,6 +11,7 @@
  *
  * Based on latest GCS and S3 implementations with R2-specific enhancements
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, SYSTEM_DIR, STATISTICS_KEY, getDirectoryPath } from '../baseStorage.js';
 import { BrainyError } from '../../errors/brainyError.js';
 import { CacheManager } from '../cacheManager.js';
@@ -918,13 +919,23 @@ export class R2Storage extends BaseStorage {
                             continue;
                     }
                 }
-                // v4.0.0: Create HNSWNounWithMetadata by combining noun with metadata
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const nounWithMetadata = {
                     id: noun.id,
                     vector: [...noun.vector],
                     connections: new Map(noun.connections),
                     level: noun.level || 0,
-                    metadata: (metadata || {}) // Empty if none
+                    type: nounType || NounType.Thing,
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 items.push(nounWithMetadata);
             }

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -3,6 +3,7 @@
  * Uses the AWS S3 client to interact with S3-compatible storage services
  * including Amazon S3, Cloudflare R2, and Google Cloud Storage
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, INDEX_DIR, SYSTEM_DIR, STATISTICS_KEY, getDirectoryPath } from '../baseStorage.js';
 import { StorageCompatibilityLayer } from '../backwardCompatibility.js';
 import { StorageOperationExecutors } from '../../utils/operationUtils.js';
@@ -1479,6 +1480,9 @@ export class S3CompatibleStorage extends BaseStorage {
         const verbsWithMetadata = [];
         for (const hnswVerb of result.edges) {
             const metadata = await this.getVerbMetadata(hnswVerb.id);
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = (metadata || {});
+            const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
             const verbWithMetadata = {
                 id: hnswVerb.id,
                 vector: [...hnswVerb.vector],
@@ -1486,7 +1490,14 @@ export class S3CompatibleStorage extends BaseStorage {
                 verb: hnswVerb.verb,
                 sourceId: hnswVerb.sourceId,
                 targetId: hnswVerb.targetId,
-                metadata: metadata || {}
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                metadata: customMetadata
             };
             verbsWithMetadata.push(verbWithMetadata);
         }
@@ -2899,13 +2910,23 @@ export class S3CompatibleStorage extends BaseStorage {
                     }
                 }
             }
-            // Create HNSWNounWithMetadata
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = (metadata || {});
+            const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
             const nounWithMetadata = {
                 id: node.id,
                 vector: [...node.vector],
                 connections: new Map(node.connections),
                 level: node.level || 0,
-                metadata: (metadata || {}) // Empty if none
+                type: nounType || NounType.Thing,
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                metadata: customMetadata
             };
             nounsWithMetadata.push(nounWithMetadata);
         }

package/dist/storage/adapters/typeAwareStorageAdapter.js

@@ -366,6 +366,9 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                             connectionsMap.set(Number(level), new Set(ids));
                         }
                     }
+                    // v4.8.0: Extract standard fields from metadata to top-level
+                    const metadataObj = (metadata || {});
+                    const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                     const verbWithMetadata = {
                         id: hnswVerb.id,
                         vector: [...hnswVerb.vector],
@@ -373,7 +376,14 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                         verb: hnswVerb.verb,
                         sourceId: hnswVerb.sourceId,
                         targetId: hnswVerb.targetId,
-                        metadata: metadata || {} // Empty metadata if none exists
+                        createdAt: createdAt || Date.now(),
+                        updatedAt: updatedAt || Date.now(),
+                        confidence: confidence,
+                        weight: weight,
+                        service: service,
+                        data: data,
+                        createdBy,
+                        metadata: customMetadata
                     };
                     verbs.push(verbWithMetadata);
                 }
@@ -417,6 +427,9 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                             connectionsMap.set(Number(level), new Set(ids));
                         }
                     }
+                    // v4.8.0: Extract standard fields from metadata to top-level
+                    const metadataObj = (metadata || {});
+                    const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                     const verbWithMetadata = {
                         id: hnswVerb.id,
                         vector: [...hnswVerb.vector],
@@ -424,7 +437,14 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                         verb: hnswVerb.verb,
                         sourceId: hnswVerb.sourceId,
                         targetId: hnswVerb.targetId,
-                        metadata: metadata || {} // Empty metadata if none exists
+                        createdAt: createdAt || Date.now(),
+                        updatedAt: updatedAt || Date.now(),
+                        confidence: confidence,
+                        weight: weight,
+                        service: service,
+                        data: data,
+                        createdBy,
+                        metadata: customMetadata
                     };
                     verbs.push(verbWithMetadata);
                 }
@@ -463,6 +483,9 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                         connectionsMap.set(Number(level), new Set(ids));
                     }
                 }
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const verbWithMetadata = {
                     id: hnswVerb.id,
                     vector: [...hnswVerb.vector],
@@ -470,7 +493,14 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,
-                    metadata: metadata || {} // Empty metadata if none exists
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 verbs.push(verbWithMetadata);
             }

package/dist/storage/baseStorage.js

@@ -5,6 +5,7 @@
 import { GraphAdjacencyIndex } from '../graph/graphAdjacencyIndex.js';
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
 import { validateNounType, validateVerbType } from '../utils/typeValidation.js';
+import { NounType } from '../types/graphTypes.js';
 import { getShardIdFromUuid } from './sharding.js';
 // Clean directory structure (v4.7.2+)
 // All storage adapters use this consistent structure
@@ -46,6 +47,10 @@ export class BaseStorage extends BaseStorageAdapter {
      * @private
      */
     analyzeKey(id, context) {
+        // v4.8.0: Guard against undefined/null IDs
+        if (!id || typeof id !== 'string') {
+            throw new Error(`Invalid storage key: ${id} (must be a non-empty string)`);
+        }
         // System resource detection
         const isSystemKey = id.startsWith('__metadata_') ||
             id.startsWith('__index_') ||
@@ -142,13 +147,24 @@ export class BaseStorage extends BaseStorageAdapter {
             console.warn(`[Storage] Noun ${id} has vector but no metadata - this should not happen in v4.0.0`);
             return null;
         }
-        // Combine into HNSWNounWithMetadata
+        // Combine into HNSWNounWithMetadata - v4.8.0: Extract standard fields to top-level
+        const { noun, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadata;
         return {
             id: vector.id,
             vector: vector.vector,
             connections: vector.connections,
             level: vector.level,
-            metadata
+            // v4.8.0: Standard fields at top-level
+            type: noun || NounType.Thing,
+            createdAt: createdAt || Date.now(),
+            updatedAt: updatedAt || Date.now(),
+            confidence: confidence,
+            weight: weight,
+            service: service,
+            data: data,
+            createdBy,
+            // Only custom user fields remain in metadata
+            metadata: customMetadata
         };
     }
     /**
@@ -160,14 +176,25 @@ export class BaseStorage extends BaseStorageAdapter {
         await this.ensureInitialized();
         // Internal method returns HNSWNoun[], need to combine with metadata
         const nouns = await this.getNounsByNounType_internal(nounType);
-        // Combine each noun with its metadata
+        // Combine each noun with its metadata - v4.8.0: Extract standard fields to top-level
         const nounsWithMetadata = [];
         for (const noun of nouns) {
             const metadata = await this.getNounMetadata(noun.id);
             if (metadata) {
+                const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadata;
                 nounsWithMetadata.push({
                     ...noun,
-                    metadata
+                    // v4.8.0: Standard fields at top-level
+                    type: nounType || NounType.Thing,
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    // Only custom user fields in metadata
+                    metadata: customMetadata
                 });
             }
         }
@@ -220,7 +247,8 @@ export class BaseStorage extends BaseStorageAdapter {
             console.warn(`[Storage] Verb ${id} has vector but no metadata - this should not happen in v4.0.0`);
             return null;
         }
-        // Combine into HNSWVerbWithMetadata
+        // Combine into HNSWVerbWithMetadata - v4.8.0: Extract standard fields to top-level
+        const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadata;
         return {
             id: verb.id,
             vector: verb.vector,
@@ -228,7 +256,16 @@ export class BaseStorage extends BaseStorageAdapter {
             verb: verb.verb,
             sourceId: verb.sourceId,
             targetId: verb.targetId,
-            metadata
+            // v4.8.0: Standard fields at top-level
+            createdAt: createdAt || Date.now(),
+            updatedAt: updatedAt || Date.now(),
+            confidence: confidence,
+            weight: weight,
+            service: service,
+            data: data,
+            createdBy,
+            // Only custom user fields remain in metadata
+            metadata: customMetadata
         };
     }
     /**

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.0",
   "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",