@soulcraft/brainy 3.0.0 → 3.1.0

package/dist/brainyData.js

@@ -8,14 +8,15 @@ import { HNSWIndexOptimized } from './hnsw/hnswIndexOptimized.js';
 import { cosineDistance, defaultEmbeddingFunction, cleanupWorkerPools, batchEmbed } from './utils/index.js';
 import { getAugmentationVersion } from './utils/version.js';
 import { matchesMetadataFilter } from './utils/metadataFilter.js';
+import { enforceNodeVersion } from './utils/nodeVersionCheck.js';
 import { createNamespacedMetadata, updateNamespacedMetadata, markDeleted, markRestored, isDeleted, getUserMetadata } from './utils/metadataNamespace.js';
 import { PeriodicCleanup } from './utils/periodicCleanup.js';
 import { NounType, VerbType } from './types/graphTypes.js';
-import { createServerSearchAugmentations } from './augmentations/serverSearchAugmentations.js';
-import { augmentationPipeline } from './augmentationPipeline.js';
+import { validateNounType, validateSearchQuery, validateSearchOptions, validateDataInput } from './utils/typeValidation.js';
+import { BrainyError } from './errors/brainyError.js';
 import { prodLog } from './utils/logger.js';
 import { prepareJsonForVectorization, extractFieldFromJson } from './utils/jsonProcessing.js';
-import { DistributedConfigManager, HashPartitioner, OperationalModeFactory, DomainDetector } from './distributed/index.js';
+import { DistributedConfigManager, HashPartitioner, OperationalModeFactory, DomainDetector, DistributedCoordinator, ShardManager, CacheSync, ReadWriteSeparation } from './distributed/index.js';
 import { CacheAutoConfigurator } from './utils/cacheAutoConfig.js';
 import { RequestDeduplicator } from './utils/requestDeduplicator.js';
 import { AugmentationRegistry } from './augmentations/brainyAugmentation.js';
@@ -27,10 +28,8 @@ import { EntityRegistryAugmentation, AutoRegisterEntitiesAugmentation } from './
 import { createDefaultAugmentations } from './augmentations/defaultAugmentations.js';
 // import { RealtimeStreamingAugmentation } from './augmentations/realtimeStreamingAugmentation.js'
 import { IntelligentVerbScoringAugmentation } from './augmentations/intelligentVerbScoringAugmentation.js';
-import { NeuralAPI } from './neural/neuralAPI.js';
-import { TripleIntelligenceEngine } from './triple/TripleIntelligence.js';
+import { ImprovedNeuralAPI } from './neural/improvedNeuralAPI.js';
 export class BrainyData {
-    // REMOVED: HealthMonitor is now handled by MonitoringAugmentation
     // Statistics collector
     // REMOVED: StatisticsCollector is now handled by MetricsAugmentation
     // Clean augmentation accessors for internal use
@@ -52,6 +51,11 @@ export class BrainyData {
     get monitoring() {
         return this.augmentations.get('monitoring');
     }
+    // ================================================================
+    // SECTION 1: CONFIGURATION & PROPERTIES
+    // ================================================================
+    // Configuration getters, dimensions, and system properties
+    // These provide access to core system configuration and status
     /**
      * Get the vector dimensions
      */
@@ -78,8 +82,15 @@ export class BrainyData {
     get initialized() {
         return this.isInitialized;
     }
+    // ================================================================
+    // SECTION 2: CONSTRUCTOR & INITIALIZATION
+    // ================================================================
+    // Constructor, initialization logic, and system setup
+    // Handles zero-config setup and system bootstrapping
     /**
      * Create a new vector database
+     * @param config - Zero-config string ('production', 'development', 'minimal'),
+     *                 simplified config object, or legacy full config
      */
     constructor(config = {}) {
         this.storage = null;
@@ -123,72 +134,96 @@ export class BrainyData {
         this.partitioner = null;
         this.operationalMode = null;
         this.domainDetector = null;
-        // Store config
-        this.config = config;
+        // REMOVED: HealthMonitor is now handled by MonitoringAugmentation
+        // New distributed components for 3.0
+        this.networkTransport = null;
+        this.coordinator = null;
+        this.shardManager = null;
+        this.cacheSync = null;
+        this.readWriteSeparation = null;
+        this.httpTransport = null; // HTTPTransport from dynamic import
+        this.storageDiscovery = null; // StorageDiscovery from dynamic import
+        this.queryPlanner = null; // DistributedQueryPlanner from dynamic import
+        this.shardMigrationManager = null; // ShardMigrationManager from dynamic import
+        // Enforce Node.js version requirement for ONNX stability
+        if (typeof process !== 'undefined' && process.version && !process.env.BRAINY_SKIP_VERSION_CHECK) {
+            enforceNodeVersion();
+        }
+        // Store raw config for processing in init()
+        this.rawConfig = config;
+        // For now, process as legacy config if it's an object
+        // The actual zero-config processing will happen in init() since it's async
+        if (typeof config === 'object') {
+            this.config = config;
+        }
+        else {
+            // String preset or simplified config - use minimal defaults for now
+            this.config = {};
+        }
         // Set dimensions to fixed value of 384 (all-MiniLM-L6-v2 dimension)
         this._dimensions = 384;
         // Set distance function
-        this.distanceFunction = config.distanceFunction || cosineDistance;
+        this.distanceFunction = this.config.distanceFunction || cosineDistance;
         // Always use the optimized HNSW index implementation
         // Configure HNSW with disk-based storage when a storage adapter is provided
-        const hnswConfig = config.hnsw || {};
-        if (config.storageAdapter) {
+        const hnswConfig = this.config.hnsw || {};
+        if (this.config.storageAdapter) {
             hnswConfig.useDiskBasedIndex = true;
         }
         // Temporarily use base HNSW index for metadata filtering
         this.hnswIndex = new HNSWIndex(hnswConfig, this.distanceFunction);
         this.useOptimizedIndex = false;
         // Set storage if provided, otherwise it will be initialized in init()
-        this.storage = config.storageAdapter || null;
+        this.storage = this.config.storageAdapter || null;
         // Store logging configuration
-        if (config.logging !== undefined) {
+        if (this.config.logging !== undefined) {
             this.loggingConfig = {
                 ...this.loggingConfig,
-                ...config.logging
+                ...this.config.logging
             };
         }
         // Set embedding function if provided, otherwise create one with the appropriate verbose setting
-        if (config.embeddingFunction) {
-            this.embeddingFunction = config.embeddingFunction;
+        if (this.config.embeddingFunction) {
+            this.embeddingFunction = this.config.embeddingFunction;
         }
         else {
             this.embeddingFunction = defaultEmbeddingFunction;
         }
         // Set persistent storage request flag
         this.requestPersistentStorage =
-            config.storage?.requestPersistentStorage || false;
+            this.config.storage?.requestPersistentStorage || false;
         // Set read-only flag
-        this.readOnly = config.readOnly || false;
+        this.readOnly = this.config.readOnly || false;
         // Set frozen flag (defaults to false to allow optimizations in readOnly mode)
-        this.frozen = config.frozen || false;
+        this.frozen = this.config.frozen || false;
         // Set lazy loading in read-only mode flag
-        this.lazyLoadInReadOnlyMode = config.lazyLoadInReadOnlyMode || false;
+        this.lazyLoadInReadOnlyMode = this.config.lazyLoadInReadOnlyMode || false;
         // Set write-only flag
-        this.writeOnly = config.writeOnly || false;
+        this.writeOnly = this.config.writeOnly || false;
         // Set allowDirectReads flag
-        this.allowDirectReads = config.allowDirectReads || false;
+        this.allowDirectReads = this.config.allowDirectReads || false;
         // Validate that readOnly and writeOnly are not both true
         if (this.readOnly && this.writeOnly) {
             throw new Error('Database cannot be both read-only and write-only');
         }
         // Set default service name if provided
-        if (config.defaultService) {
-            this.defaultService = config.defaultService;
+        if (this.config.defaultService) {
+            this.defaultService = this.config.defaultService;
         }
         // Store storage configuration for later use in init()
-        this.storageConfig = config.storage || {};
+        this.storageConfig = this.config.storage || {};
         // Store timeout and retry configuration
-        this.timeoutConfig = config.timeouts || {};
-        this.retryConfig = config.retryPolicy || {};
+        this.timeoutConfig = this.config.timeouts || {};
+        this.retryConfig = this.config.retryPolicy || {};
         // Store remote server configuration if provided
-        if (config.remoteServer) {
-            this.remoteServerConfig = config.remoteServer;
+        if (this.config.remoteServer) {
+            this.remoteServerConfig = this.config.remoteServer;
         }
         // Initialize real-time update configuration if provided
-        if (config.realtimeUpdates) {
+        if (this.config.realtimeUpdates) {
             this.realtimeUpdateConfig = {
                 ...this.realtimeUpdateConfig,
-                ...config.realtimeUpdates
+                ...this.config.realtimeUpdates
             };
         }
         // Initialize cache configuration with intelligent defaults
@@ -206,15 +241,15 @@ export class BrainyData {
             }
         };
         // Override defaults with user-provided configuration if available
-        if (config.cache) {
+        if (this.config.cache) {
             this.cacheConfig = {
                 ...this.cacheConfig,
-                ...config.cache
+                ...this.config.cache
             };
         }
         // Store distributed configuration
-        if (config.distributed) {
-            if (typeof config.distributed === 'boolean') {
+        if (this.config.distributed) {
+            if (typeof this.config.distributed === 'boolean') {
                 // Auto-mode enabled
                 this.distributedConfig = {
                     enabled: true
@@ -222,7 +257,7 @@ export class BrainyData {
             }
             else {
                 // Explicit configuration
-                this.distributedConfig = config.distributed;
+                this.distributedConfig = this.config.distributed;
             }
         }
         // Initialize cache auto-configurator first
@@ -296,11 +331,11 @@ export class BrainyData {
             ttl: 5000,
             maxSize: 1000
         }));
-        // Priority 10: Enhancement features  
-        const intelligentVerbAugmentation = new IntelligentVerbScoringAugmentation(this.config.intelligentVerbScoring || { enabled: false });
+        // Priority 10: Core relationship quality features  
+        const intelligentVerbAugmentation = new IntelligentVerbScoringAugmentation(this.config.intelligentVerbScoring || { enabled: true });
         this.augmentations.register(intelligentVerbAugmentation);
-        // Store reference if intelligent verb scoring is enabled
-        if (this.config.intelligentVerbScoring?.enabled) {
+        // Store reference if intelligent verb scoring is enabled (enabled by default)
+        if (this.config.intelligentVerbScoring?.enabled !== false) {
             this.intelligentVerbScoring = intelligentVerbAugmentation.getScoring();
         }
     }
@@ -350,16 +385,28 @@ export class BrainyData {
                     console.warn('Ignoring s3Storage configuration due to missing required fields');
                 }
             }
-            // Check if specific storage is configured
+            // Check if specific storage is configured (legacy and new formats)
             if (storageOptions.s3Storage || storageOptions.r2Storage ||
                 storageOptions.gcsStorage || storageOptions.forceMemoryStorage ||
-                storageOptions.forceFileSystemStorage) {
-                // Create storage from config
-                const { createStorage } = await import('./storage/storageFactory.js');
-                this.storage = await createStorage(storageOptions);
-                // Wrap in augmentation for consistency
-                const wrapper = new DynamicStorageAugmentation(this.storage);
-                this.augmentations.register(wrapper);
+                storageOptions.forceFileSystemStorage ||
+                typeof storageOptions === 'string') {
+                // Handle string storage types (new zero-config)
+                if (typeof storageOptions === 'string') {
+                    const { createAutoStorageAugmentation } = await import('./augmentations/storageAugmentations.js');
+                    // For now, use auto-detection - TODO: extend to support preferred types
+                    const autoAug = await createAutoStorageAugmentation({
+                        rootDirectory: './brainy-data'
+                    });
+                    this.augmentations.register(autoAug);
+                }
+                else {
+                    // Legacy object config
+                    const { createStorage } = await import('./storage/storageFactory.js');
+                    this.storage = await createStorage(storageOptions);
+                    // Wrap in augmentation for consistency
+                    const wrapper = new DynamicStorageAugmentation(this.storage);
+                    this.augmentations.register(wrapper);
+                }
             }
             else {
                 // Zero-config: auto-select based on environment
@@ -376,7 +423,7 @@ export class BrainyData {
             await this.storage.init();
         }
         else {
-            throw new Error('Failed to resolve storage');
+            throw BrainyError.storage('Failed to resolve storage');
         }
     }
     /**
@@ -410,7 +457,7 @@ export class BrainyData {
      */
     async initializePeriodicCleanup() {
         if (!this.storage) {
-            throw new Error('Cannot initialize periodic cleanup: storage not available');
+            throw BrainyError.storage('Cannot initialize periodic cleanup: storage not available');
         }
         // Skip cleanup if in read-only or frozen mode
         if (this.readOnly || this.frozen) {
@@ -831,16 +878,12 @@ export class BrainyData {
      */
     getCurrentAugmentation() {
         try {
-            // Get all registered augmentations
-            const augmentationTypes = augmentationPipeline.getAvailableAugmentationTypes();
-            // Check each type of augmentation
-            for (const type of augmentationTypes) {
-                const augmentations = augmentationPipeline.getAugmentationsByType(type);
-                // Find the first augmentation (all registered augmentations are considered enabled)
-                for (const augmentation of augmentations) {
-                    if (augmentation) {
-                        return augmentation.name;
-                    }
+            // Get all registered augmentations from the new API
+            const allAugmentations = this.augmentations.getAll();
+            // Find the first enabled augmentation
+            for (const augmentation of allAugmentations) {
+                if (augmentation && augmentation.config?.enabled !== false) {
+                    return augmentation.name;
                 }
             }
             return 'default';
@@ -878,23 +921,38 @@ export class BrainyData {
             return;
         }
         this.isInitializing = true;
-        // CRITICAL: Initialize universal memory manager ONLY for default embedding function
-        // This preserves custom embedding functions (like test mocks)
-        if (typeof this.embeddingFunction === 'function' && this.embeddingFunction === defaultEmbeddingFunction) {
+        // Process zero-config if needed
+        if (this.rawConfig !== undefined) {
             try {
-                const { universalMemoryManager } = await import('./embeddings/universal-memory-manager.js');
-                this.embeddingFunction = await universalMemoryManager.getEmbeddingFunction();
-                console.log('✅ UNIVERSAL: Memory-safe embedding system initialized');
+                const { applyZeroConfig } = await import('./config/index.js');
+                const processedConfig = await applyZeroConfig(this.rawConfig);
+                // Apply processed config if it's different from raw
+                if (processedConfig !== this.rawConfig) {
+                    // Log if verbose
+                    if (processedConfig.logging?.verbose) {
+                        console.log('🤖 Zero-config applied successfully');
+                    }
+                    // Update config with processed values
+                    this.config = processedConfig;
+                    // Update relevant properties from processed config
+                    this.storageConfig = processedConfig.storage || {};
+                    this.loggingConfig = processedConfig.logging || { verbose: false };
+                    // Update embedding function if precision was specified
+                    if (processedConfig.embeddingOptions?.precision) {
+                        const { createEmbeddingFunctionWithPrecision } = await import('./config/index.js');
+                        this.embeddingFunction = await createEmbeddingFunctionWithPrecision(processedConfig.embeddingOptions.precision);
+                    }
+                }
             }
             catch (error) {
-                console.error('🚨 CRITICAL: Universal memory manager initialization failed!');
-                console.error('Falling back to standard embedding with potential memory issues.');
-                console.warn('Consider reducing usage or restarting process periodically.');
-                // Continue with default function - better than crashing
+                console.warn('Zero-config processing failed, using defaults:', error);
+                // Continue with existing config
             }
         }
-        else if (this.embeddingFunction !== defaultEmbeddingFunction) {
-            console.log('✅ CUSTOM: Using custom embedding function (test or production override)');
+        // The embedding function is already set (either custom or default)
+        // EmbeddingManager handles all initialization internally
+        if (this.embeddingFunction !== defaultEmbeddingFunction) {
+            console.log('✅ Using custom embedding function');
         }
         try {
             // Pre-load the embedding model early to ensure it's always available
@@ -984,16 +1042,6 @@ export class BrainyData {
                     offset += limit;
                 }
             }
-            // Connect to remote server if configured with autoConnect
-            if (this.remoteServerConfig && this.remoteServerConfig.autoConnect) {
-                try {
-                    await this.connectToRemoteServer(this.remoteServerConfig.url, this.remoteServerConfig.protocols);
-                }
-                catch (remoteError) {
-                    console.warn('Failed to auto-connect to remote server:', remoteError);
-                    // Continue initialization even if remote connection fails
-                }
-            }
             // Initialize statistics collector with existing data
             try {
                 const existingStats = await this.storage.getStatistics();
@@ -1102,6 +1150,8 @@ export class BrainyData {
         // Create operational mode based on role
         const role = this.configManager.getRole();
         this.operationalMode = OperationalModeFactory.createMode(role);
+        // Initialize NEW distributed components for 3.0
+        await this.initializeDistributedComponents(sharedConfig);
         // Validate that role matches the configured mode
         // Don't override explicitly set readOnly/writeOnly
         if (role === 'reader' && !this.readOnly) {
@@ -1162,473 +1212,316 @@ export class BrainyData {
         }
     }
     /**
-     * Get distributed health status
-     * @returns Health status if distributed mode is enabled
+     * Initialize NEW distributed components for Brainy 3.0
+     * This enables true multi-node operation with consensus and sharding
+     */
+    async initializeDistributedComponents(sharedConfig) {
+        // Extract distributed configuration with type safety
+        const distConfig = typeof this.distributedConfig === 'object' && this.distributedConfig !== null
+            ? this.distributedConfig
+            : {};
+        // Generate or use node ID
+        const nodeId = distConfig.instanceId || sharedConfig.nodeId ||
+            `node-${Math.random().toString(36).substring(2, 11)}`;
+        // Use zero-config discovery if storage is available
+        if (this.storage && distConfig.useStorageDiscovery !== false) {
+            // Use storage-based discovery for true zero-config
+            const { StorageDiscovery } = await import('./distributed/storageDiscovery.js');
+            this.storageDiscovery = new StorageDiscovery(this.storage, nodeId);
+            // Start discovery and join cluster
+            const port = distConfig.port || 0; // 0 = auto-detect
+            const cluster = await this.storageDiscovery.start(port);
+            // Use discovered nodes as seeds
+            distConfig.peers = cluster.nodes.map((n) => `${n.address}:${n.port}`);
+        }
+        // Initialize HTTP transport (replaces NetworkTransport)
+        const { HTTPTransport } = await import('./distributed/httpTransport.js');
+        this.httpTransport = new HTTPTransport(nodeId);
+        // Start HTTP transport
+        const actualPort = await this.httpTransport.start();
+        console.log(`[${nodeId}] HTTP transport listening on port ${actualPort}`);
+        // Initialize coordinator for consensus
+        this.coordinator = new DistributedCoordinator({
+            nodeId,
+            heartbeatInterval: distConfig.heartbeatInterval || 1000,
+            electionTimeout: distConfig.electionTimeout || 5000,
+            nodes: distConfig.peers || []
+        });
+        // Start coordinator with HTTP transport adapter
+        const transportAdapter = {
+            send: (nodeId, message) => this.httpTransport.call(nodeId, 'coordinator', message),
+            broadcast: (message) => this.httpTransport.broadcast('coordinator', message),
+            on: (event, handler) => {
+                // Register handler for coordinator messages
+                if (event === 'message') {
+                    this.httpTransport.registerHandler('coordinator', handler);
+                }
+            }
+        };
+        await this.coordinator.start(transportAdapter);
+        // Initialize shard manager
+        this.shardManager = new ShardManager({
+            shardCount: distConfig.shardCount || 8,
+            replicationFactor: distConfig.replicationFactor || 3,
+            virtualNodes: distConfig.virtualNodes || 100,
+            autoRebalance: distConfig.autoRebalance !== false
+        });
+        // Initialize cache synchronization
+        this.cacheSync = new CacheSync({
+            nodeId,
+            syncInterval: distConfig.syncInterval || 5000
+        });
+        // Initialize read/write separation
+        // Note: This requires all components to be initialized
+        this.readWriteSeparation = new ReadWriteSeparation({
+            nodeId,
+            role: this.readOnly ? 'replica' : this.writeOnly ? 'primary' : 'auto',
+            primaryUrl: distConfig.primaryUrl || '',
+            replicaUrls: distConfig.replicaUrls || [],
+            syncInterval: distConfig.syncInterval || 5000,
+            readPreference: distConfig.readPreference || 'nearest',
+            consistencyLevel: distConfig.consistencyLevel || 'eventual'
+        }, this.coordinator, this.shardManager, this.cacheSync);
+        // Initialize query planner for distributed queries
+        const { DistributedQueryPlanner } = await import('./distributed/queryPlanner.js');
+        this.queryPlanner = new DistributedQueryPlanner(nodeId, this.coordinator, this.shardManager, this.httpTransport, this.storage, this._tripleEngine);
+        // Set up coordinator event handlers
+        this.coordinator.on('leaderElected', (leaderId) => {
+            if (leaderId === nodeId) {
+                console.log(`[${nodeId}] Became the leader`);
+                // Update read/write separation if needed
+                if (this.readWriteSeparation) {
+                    this.readWriteSeparation.setPrimary(true);
+                }
+            }
+            else {
+                console.log(`[${nodeId}] Following leader: ${leaderId}`);
+                if (this.readWriteSeparation) {
+                    this.readWriteSeparation.setPrimary(false);
+                }
+            }
+        });
+        // Set up distributed operation handlers
+        this.setupDistributedOperations();
+        if (this.loggingConfig?.verbose) {
+            console.log(`[${nodeId}] Distributed components initialized`);
+            console.log(`- Network: ${this.networkTransport ? 'Ready' : 'Not initialized'}`);
+            console.log(`- Coordinator: ${this.coordinator.getState().state}`);
+            console.log(`- Shards: ${this.shardManager.getTotalShards()} total`);
+        }
+    }
+    /**
+     * Execute a query on local shards
      */
-    getHealthStatus() {
-        return this.monitoring?.getHealthStatus() || null;
+    async executeLocalQuery(query, shards) {
+        // For now, just do a regular find
+        // In production, this would filter by shard assignments
+        const results = await this.find(query.text || query.query, query.k || 10);
+        return results;
     }
     /**
-     * Connect to a remote Brainy server for search operations
-     * @param serverUrl WebSocket URL of the remote Brainy server
-     * @param protocols Optional WebSocket protocols to use
-     * @returns The connection object
+     * Set up distributed operation handlers
      */
-    async connectToRemoteServer(serverUrl, protocols) {
-        await this.ensureInitialized();
-        try {
-            // Create server search augmentations
-            const { conduit, connection } = await createServerSearchAugmentations(serverUrl, {
-                protocols,
-                localDb: this
+    setupDistributedOperations() {
+        // Set up handlers for HTTP transport if available
+        if (this.httpTransport) {
+            // Handle distributed query requests
+            this.httpTransport.registerHandler('query', async (data) => {
+                const { query, shards } = data;
+                try {
+                    // Execute query on specified shards
+                    const results = await this.executeLocalQuery(query, shards);
+                    return { success: true, results, count: results.length };
+                }
+                catch (error) {
+                    return { success: false, error: error.message };
+                }
+            });
+            // Handle migration batch receives
+            this.httpTransport.registerHandler('receiveMigrationBatch', async (data) => {
+                if (this.shardMigrationManager) {
+                    await this.shardMigrationManager.receiveMigrationBatch(data);
+                }
+                return { success: true };
+            });
+            // Handle migration validation
+            this.httpTransport.registerHandler('validateMigration', async (data) => {
+                if (this.shardMigrationManager) {
+                    return await this.shardMigrationManager.validateMigration(data);
+                }
+                return { valid: false, error: 'No migration manager' };
             });
-            // TODO: Store conduit and connection (post-2.0.0 feature)
-            // this.serverSearchConduit = conduit
-            // this.serverConnection = connection
-            return connection;
         }
-        catch (error) {
-            console.error('Failed to connect to remote server:', error);
-            throw new Error(`Failed to connect to remote server: ${error}`);
+        // Set up legacy NetworkTransport handlers if still used
+        if (this.networkTransport) {
+            const handlers = this.networkTransport.messageHandlers;
+            // Handle distributed add requests
+            handlers.set('DISTRIBUTED_ADD', async (msg) => {
+                const { data, type, metadata } = msg.data;
+                try {
+                    const id = await this.localAdd(data, type, metadata);
+                    return { success: true, id };
+                }
+                catch (error) {
+                    return { success: false, error: error.message };
+                }
+            });
+            // Handle distributed find requests
+            handlers.set('DISTRIBUTED_FIND', async (msg) => {
+                const { query, shardId } = msg.data;
+                try {
+                    const results = await this.localFind(query, shardId);
+                    return { success: true, results };
+                }
+                catch (error) {
+                    return { success: false, error: error.message };
+                }
+            });
+            // Handle cache sync messages
+            handlers.set('CACHE_SYNC', async (msg) => {
+                if (this.cacheSync) {
+                    await this.cacheSync.handleSyncMessage(msg.data);
+                }
+                return { success: true };
+            });
         }
     }
     /**
-     * Add data to the database with intelligent processing
-     *
-     * @param vectorOrData Vector or data to add
-     * @param metadata Optional metadata to associate with the data
-     * @param options Additional options for processing
-     * @returns The ID of the added data
-     *
-     * @example
-     * // Auto mode - intelligently decides processing
-     * await brainy.add("Customer feedback: Great product!")
-     *
-     * @example
-     * // Explicit literal mode for sensitive data
-     * await brainy.add("API_KEY=secret123", null, { process: 'literal' })
-     *
-     * @example
-     * // Force neural processing
-     * await brainy.add("John works at Acme Corp", null, { process: 'neural' })
+     * Local add operation (without distribution)
+     */
+    async localAdd(data, type, metadata) {
+        // Use the existing addNoun method but bypass distribution checks
+        const tempDistributed = this.shardManager;
+        this.shardManager = null; // Temporarily disable to prevent recursion
+        try {
+            const id = await this.addNoun(data, type, metadata);
+            return id;
+        }
+        finally {
+            this.shardManager = tempDistributed; // Restore
+        }
+    }
+    /**
+     * Local find operation (potentially for a specific shard)
+     */
+    async localFind(query, shardId) {
+        // TODO: Implement shard-aware find
+        // For now, just use regular find
+        return this.find(query);
+    }
+    /**
+     * Get distributed health status
+     * @returns Health status if distributed mode is enabled
+     */
+    getHealthStatus() {
+        return this.monitoring?.getHealthStatus() || null;
+    }
+    // REMOVED: addItem() - Use addNoun() instead (cleaner 2.0 API)
+    // REMOVED: addToBoth() - Remote server functionality moved to post-2.0.0
+    /**
+     * Add multiple vectors or data items to the database
+     * @param items Array of items to add
+     * @param options Additional options
+     * @returns Array of IDs for the added items
+     */
+    /**
+     * Add multiple nouns in batch with required types
+     * @param items Array of nouns to add (all must have types)
+     * @param options Batch processing options
+     * @returns Array of generated IDs
      */
-    async add(vectorOrData, metadata, options = {}) {
+    async addNouns(items, options = {}) {
         await this.ensureInitialized();
         // Check if database is in read-only mode
         this.checkReadOnly();
-        // Validate input is not null or undefined
-        if (vectorOrData === null || vectorOrData === undefined) {
-            throw new Error('Input cannot be null or undefined');
-        }
-        try {
-            let vector;
-            // First validate if input is an array but contains non-numeric values
-            if (Array.isArray(vectorOrData)) {
-                for (let i = 0; i < vectorOrData.length; i++) {
-                    if (typeof vectorOrData[i] !== 'number') {
-                        throw new Error('Vector contains non-numeric values');
-                    }
-                }
-            }
-            // Check if input is already a vector
-            if (Array.isArray(vectorOrData) && !options.forceEmbed) {
-                // Input is already a vector (and we've validated it contains only numbers)
-                vector = vectorOrData;
+        // Validate all types upfront for better error handling
+        const invalidItems = [];
+        items.forEach((item, index) => {
+            if (!item.nounType || typeof item.nounType !== 'string') {
+                invalidItems.push(index);
             }
             else {
-                // Input needs to be vectorized
+                // Validate the type is valid
                 try {
-                    // Check if input is a JSON object and process it specially
-                    if (typeof vectorOrData === 'object' &&
-                        vectorOrData !== null &&
-                        !Array.isArray(vectorOrData)) {
-                        // Process JSON object for better vectorization
-                        const preparedText = prepareJsonForVectorization(vectorOrData, {
-                            // Prioritize common name/title fields if they exist
-                            priorityFields: [
-                                'name',
-                                'title',
-                                'company',
-                                'organization',
-                                'description',
-                                'summary'
-                            ]
-                        });
-                        vector = await this.embeddingFunction(preparedText);
-                        // IMPORTANT: When an object is passed as data and no metadata is provided,
-                        // use the object AS the metadata too. This is expected behavior for the API.
-                        // Users can pass either:
-                        // 1. addNoun(string, metadata) - vectorize string, store metadata
-                        // 2. addNoun(object) - vectorize object text, store object as metadata
-                        // 3. addNoun(object, metadata) - vectorize object text, store provided metadata
-                        if (!metadata) {
-                            metadata = vectorOrData;
-                        }
-                        // Track field names for this JSON document
-                        const service = this.getServiceName(options);
-                        if (this.storage) {
-                            await this.storage.trackFieldNames(vectorOrData, service);
-                        }
-                    }
-                    else {
-                        // Use standard embedding for non-JSON data
-                        vector = await this.embeddingFunction(vectorOrData);
-                    }
+                    validateNounType(item.nounType);
                 }
-                catch (embedError) {
-                    throw new Error(`Failed to vectorize data: ${embedError}`);
+                catch (error) {
+                    invalidItems.push(index);
                 }
             }
-            // Check if vector is defined
-            if (!vector) {
-                throw new Error('Vector is undefined or null');
-            }
-            // Validate vector dimensions
-            if (vector.length !== this._dimensions) {
-                throw new Error(`Vector dimension mismatch: expected ${this._dimensions}, got ${vector.length}`);
-            }
-            // Use ID from options if it exists, otherwise from metadata, otherwise generate a new UUID
-            const id = options.id ||
-                (metadata && typeof metadata === 'object' && 'id' in metadata
-                    ? metadata.id
-                    : uuidv4());
-            // Check for existing noun (both write-only and normal modes)
-            let existingNoun;
-            if (options.id) {
-                try {
-                    if (this.writeOnly) {
-                        // In write-only mode, check storage directly
-                        existingNoun =
-                            (await this.storage.getNoun(options.id)) ?? undefined;
+        });
+        if (invalidItems.length > 0) {
+            throw new Error(`Type validation failed for ${invalidItems.length} items at indices: ${invalidItems.slice(0, 5).join(', ')}${invalidItems.length > 5 ? '...' : ''}\n` +
+                'All items must have valid noun types.\n' +
+                'Example: { vectorOrData: "data", nounType: NounType.Content, metadata: {...} }');
+        }
+        // Default concurrency to 4 if not specified
+        const concurrency = options.concurrency || 4;
+        // Default batch size to 50 if not specified
+        const batchSize = options.batchSize || 50;
+        try {
+            // Process items in batches to control concurrency and memory usage
+            const ids = [];
+            const itemsToProcess = [...items]; // Create a copy to avoid modifying the original array
+            while (itemsToProcess.length > 0) {
+                // Take up to 'batchSize' items to process in a batch
+                const batch = itemsToProcess.splice(0, batchSize);
+                // Separate items that are already vectors from those that need embedding
+                const vectorItems = [];
+                const textItems = [];
+                // Categorize items
+                batch.forEach((item, index) => {
+                    if (Array.isArray(item.vectorOrData) &&
+                        item.vectorOrData.every((val) => typeof val === 'number') &&
+                        !options.forceEmbed) {
+                        // Item is already a vector
+                        vectorItems.push({
+                            vectorOrData: item.vectorOrData,
+                            nounType: item.nounType,
+                            metadata: item.metadata,
+                            index
+                        });
                     }
-                    else {
-                        // In normal mode, check index first, then storage
-                        existingNoun = this.index.getNouns().get(options.id);
-                        if (!existingNoun) {
-                            existingNoun =
-                                (await this.storage.getNoun(options.id)) ?? undefined;
-                        }
+                    else if (typeof item.vectorOrData === 'string') {
+                        // Item is text that needs embedding
+                        textItems.push({
+                            text: item.vectorOrData,
+                            nounType: item.nounType,
+                            metadata: item.metadata,
+                            index
+                        });
                     }
-                    if (existingNoun) {
-                        // Check if existing noun is a placeholder
-                        const existingMetadata = await this.storage.getMetadata(options.id);
-                        const isPlaceholder = existingMetadata &&
-                            typeof existingMetadata === 'object' &&
-                            existingMetadata.isPlaceholder;
-                        if (isPlaceholder) {
-                            // Replace placeholder with real data
-                            if (this.loggingConfig?.verbose) {
-                                console.log(`Replacing placeholder noun ${options.id} with real data`);
-                            }
-                        }
-                        else {
-                            // Real noun already exists, update it
-                            if (this.loggingConfig?.verbose) {
-                                console.log(`Updating existing noun ${options.id}`);
-                            }
-                        }
+                    else {
+                        // For now, treat other types as text
+                        // In a more complete implementation, we might handle other types differently
+                        const textRepresentation = String(item.vectorOrData);
+                        textItems.push({
+                            text: textRepresentation,
+                            nounType: item.nounType,
+                            metadata: item.metadata,
+                            index
+                        });
                     }
+                });
+                // Process vector items (already embedded)
+                const vectorPromises = vectorItems.map((item) => this.addNoun(item.vectorOrData, item.nounType, item.metadata));
+                // Process text items in a single batch embedding operation
+                let textPromises = [];
+                if (textItems.length > 0) {
+                    // Extract just the text for batch embedding
+                    const texts = textItems.map((item) => item.text);
+                    // Perform batch embedding
+                    const embeddings = await batchEmbed(texts);
+                    // Add each item with its embedding
+                    textPromises = textItems.map((item, i) => this.addNoun(embeddings[i], item.nounType, item.metadata));
                 }
-                catch (storageError) {
-                    // Item doesn't exist, continue with add operation
-                }
-            }
-            let noun;
-            // In write-only mode, skip index operations since index is not loaded
-            if (this.writeOnly) {
-                // Create noun object directly without adding to index
-                noun = {
-                    id,
-                    vector,
-                    connections: new Map(),
-                    level: 0, // Default level for new nodes
-                    metadata: undefined // Will be set separately
-                };
-            }
-            else {
-                // Normal mode: Add to HNSW index first
-                await this.hnswIndex.addItem({ id, vector, metadata });
-                // Get the noun from the HNSW index
-                const indexNoun = this.hnswIndex.getNouns().get(id);
-                if (!indexNoun) {
-                    throw new Error(`Failed to retrieve newly created noun with ID ${id}`);
-                }
-                noun = indexNoun;
-            }
-            // Save noun to storage using augmentation system
-            await this.augmentations.execute('saveNoun', { noun, options }, async () => {
-                await this.storage.saveNoun(noun);
-                const service = this.getServiceName(options);
-                await this.storage.incrementStatistic('noun', service);
-            });
-            // Save metadata if provided and not empty
-            if (metadata !== undefined) {
-                // Skip saving if metadata is an empty object
-                if (metadata &&
-                    typeof metadata === 'object' &&
-                    Object.keys(metadata).length === 0) {
-                    // Don't save empty metadata
-                    // Explicitly save null to ensure no metadata is stored
-                    await this.storage.saveMetadata(id, null);
-                }
-                else {
-                    // Validate noun type if metadata is for a GraphNoun
-                    if (metadata && typeof metadata === 'object' && 'noun' in metadata) {
-                        const nounType = metadata.noun;
-                        // Check if the noun type is valid
-                        const isValidNounType = Object.values(NounType).includes(nounType);
-                        if (!isValidNounType) {
-                            console.warn(`Invalid noun type: ${nounType}. Falling back to GraphNoun.`);
-                            metadata.noun = NounType.Concept;
-                        }
-                        // Ensure createdBy field is populated for GraphNoun
-                        const service = options.service || this.getCurrentAugmentation();
-                        const graphNoun = metadata;
-                        // Only set createdBy if it doesn't exist or is being explicitly updated
-                        if (!graphNoun.createdBy || options.service) {
-                            graphNoun.createdBy = getAugmentationVersion(service);
-                        }
-                        // Update timestamps
-                        const now = new Date();
-                        const timestamp = {
-                            seconds: Math.floor(now.getTime() / 1000),
-                            nanoseconds: (now.getTime() % 1000) * 1000000
-                        };
-                        // Set createdAt if it doesn't exist
-                        if (!graphNoun.createdAt) {
-                            graphNoun.createdAt = timestamp;
-                        }
-                        // Always update updatedAt
-                        graphNoun.updatedAt = timestamp;
-                    }
-                    // Create properly namespaced metadata for new items
-                    let metadataToSave = createNamespacedMetadata(metadata);
-                    // Add domain metadata if distributed mode is enabled
-                    if (this.domainDetector) {
-                        // First check if domain is already in metadata
-                        if (metadataToSave.domain) {
-                            // Domain already specified, keep it
-                            const domainInfo = this.domainDetector.detectDomain(metadataToSave);
-                            if (domainInfo.domainMetadata) {
-                                ;
-                                metadataToSave.domainMetadata =
-                                    domainInfo.domainMetadata;
-                            }
-                        }
-                        else {
-                            // Try to detect domain from the data
-                            const dataToAnalyze = Array.isArray(vectorOrData)
-                                ? metadata
-                                : vectorOrData;
-                            const domainInfo = this.domainDetector.detectDomain(dataToAnalyze);
-                            if (domainInfo.domain) {
-                                ;
-                                metadataToSave.domain = domainInfo.domain;
-                                if (domainInfo.domainMetadata) {
-                                    ;
-                                    metadataToSave.domainMetadata =
-                                        domainInfo.domainMetadata;
-                                }
-                            }
-                        }
-                    }
-                    // Add partition information if distributed mode is enabled
-                    if (this.partitioner) {
-                        const partition = this.partitioner.getPartition(id);
-                        metadataToSave.partition = partition;
-                    }
-                    await this.storage.saveMetadata(id, metadataToSave);
-                    // Update metadata index (write-only mode should build indices!)
-                    if (this.index && !this.frozen) {
-                        await this.metadataIndex?.addToIndex?.(id, metadataToSave);
-                    }
-                    // Track metadata statistics
-                    const metadataService = this.getServiceName(options);
-                    await this.storage.incrementStatistic('metadata', metadataService);
-                    // Track content type if it's a GraphNoun
-                    if (metadataToSave &&
-                        typeof metadataToSave === 'object' &&
-                        'noun' in metadataToSave) {
-                        this.metrics.trackContentType(metadataToSave.noun);
-                    }
-                    // Track update timestamp (handled by metrics augmentation)
-                }
-            }
-            // Update HNSW index size with actual index size
-            const indexSize = this.index.size();
-            await this.storage.updateHnswIndexSize(indexSize);
-            // Update health metrics if in distributed mode
-            if (this.monitoring) {
-                const vectorCount = await this.getNounCount();
-                this.monitoring.updateVectorCount(vectorCount);
-            }
-            // If addToRemote is true and we're connected to a remote server, add to remote as well
-            if (options.addToRemote && this.isConnectedToRemoteServer()) {
-                try {
-                    await this.addToRemote(id, vector, metadata);
-                }
-                catch (remoteError) {
-                    console.warn(`Failed to add to remote server: ${remoteError}. Continuing with local add.`);
-                }
-            }
-            // Invalidate search cache since data has changed
-            this.cache?.invalidateOnDataChange('add');
-            // Determine processing mode
-            const processingMode = options.process || 'auto';
-            let shouldProcessNeurally = false;
-            if (processingMode === 'neural') {
-                shouldProcessNeurally = true;
-            }
-            else if (processingMode === 'auto') {
-                // Auto-detect whether to use neural processing
-                shouldProcessNeurally = this.shouldAutoProcessNeurally(vectorOrData, metadata);
-            }
-            // 'literal' mode means no neural processing
-            // 🧠 AI Processing (Neural Import) - Based on processing mode
-            if (shouldProcessNeurally) {
-                try {
-                    // Execute augmentation pipeline for data processing
-                    // Note: Augmentations will be called via this.augmentations.execute during the actual add operation
-                    // This replaces the legacy SENSE pipeline
-                    if (this.loggingConfig?.verbose) {
-                        console.log(`🧠 AI processing completed for data: ${id}`);
-                    }
-                }
-                catch (processingError) {
-                    // Don't fail the add operation if processing fails
-                    console.warn(`🧠 AI processing failed for ${id}:`, processingError);
-                }
-            }
-            return id;
-        }
-        catch (error) {
-            console.error('Failed to add vector:', error);
-            // Track error in health monitor
-            if (this.monitoring) {
-                this.monitoring.recordRequest(0, true);
-            }
-            throw new Error(`Failed to add vector: ${error}`);
-        }
-    }
-    // REMOVED: addItem() - Use addNoun() instead (cleaner 2.0 API)
-    // REMOVED: addToBoth() - Remote server functionality moved to post-2.0.0
-    /**
-     * Add a vector to the remote server
-     * @param id ID of the vector to add
-     * @param vector Vector to add
-     * @param metadata Optional metadata to associate with the vector
-     * @returns True if successful, false otherwise
-     * @private
-     */
-    async addToRemote(id, vector, metadata) {
-        if (!this.isConnectedToRemoteServer()) {
-            return false;
-        }
-        try {
-            // TODO: Remote server operations (post-2.0.0 feature)
-            // if (!this.serverSearchConduit || !this.serverConnection) {
-            //   throw new Error(
-            //     'Server search conduit or connection is not initialized'
-            //   )
-            // }
-            // TODO: Add to remote server
-            // const addResult = await this.serverSearchConduit.addToBoth(
-            //   this.serverConnection.connectionId,
-            //   vector,
-            //   metadata
-            // )
-            throw new Error('Remote server functionality not yet implemented in Brainy 2.0.0');
-            // TODO: Handle remote add result (post-2.0.0 feature)
-            // if (!addResult.success) {
-            //   throw new Error(`Remote add failed: ${addResult.error}`)
-            // }
-            return true;
-        }
-        catch (error) {
-            console.error('Failed to add to remote server:', error);
-            throw new Error(`Failed to add to remote server: ${error}`);
-        }
-    }
-    /**
-     * Add multiple vectors or data items to the database
-     * @param items Array of items to add
-     * @param options Additional options
-     * @returns Array of IDs for the added items
-     */
-    /**
-     * Add multiple nouns in batch
-     * @param items Array of nouns to add
-     * @param options Batch processing options
-     * @returns Array of generated IDs
-     */
-    async addNouns(items, options = {}) {
-        await this.ensureInitialized();
-        // Check if database is in read-only mode
-        this.checkReadOnly();
-        // Default concurrency to 4 if not specified
-        const concurrency = options.concurrency || 4;
-        // Default batch size to 50 if not specified
-        const batchSize = options.batchSize || 50;
-        try {
-            // Process items in batches to control concurrency and memory usage
-            const ids = [];
-            const itemsToProcess = [...items]; // Create a copy to avoid modifying the original array
-            while (itemsToProcess.length > 0) {
-                // Take up to 'batchSize' items to process in a batch
-                const batch = itemsToProcess.splice(0, batchSize);
-                // Separate items that are already vectors from those that need embedding
-                const vectorItems = [];
-                const textItems = [];
-                // Categorize items
-                batch.forEach((item, index) => {
-                    if (Array.isArray(item.vectorOrData) &&
-                        item.vectorOrData.every((val) => typeof val === 'number') &&
-                        !options.forceEmbed) {
-                        // Item is already a vector
-                        vectorItems.push({
-                            vectorOrData: item.vectorOrData,
-                            metadata: item.metadata,
-                            index
-                        });
-                    }
-                    else if (typeof item.vectorOrData === 'string') {
-                        // Item is text that needs embedding
-                        textItems.push({
-                            text: item.vectorOrData,
-                            metadata: item.metadata,
-                            index
-                        });
-                    }
-                    else {
-                        // For now, treat other types as text
-                        // In a more complete implementation, we might handle other types differently
-                        const textRepresentation = String(item.vectorOrData);
-                        textItems.push({
-                            text: textRepresentation,
-                            metadata: item.metadata,
-                            index
-                        });
-                    }
-                });
-                // Process vector items (already embedded)
-                const vectorPromises = vectorItems.map((item) => this.addNoun(item.vectorOrData, item.metadata));
-                // Process text items in a single batch embedding operation
-                let textPromises = [];
-                if (textItems.length > 0) {
-                    // Extract just the text for batch embedding
-                    const texts = textItems.map((item) => item.text);
-                    // Perform batch embedding
-                    const embeddings = await batchEmbed(texts);
-                    // Add each item with its embedding
-                    textPromises = textItems.map((item, i) => this.addNoun(embeddings[i], item.metadata));
-                }
-                // Combine all promises
-                const batchResults = await Promise.all([
-                    ...vectorPromises,
-                    ...textPromises
-                ]);
-                // Add the results to our ids array
-                ids.push(...batchResults);
+                // Combine all promises
+                const batchResults = await Promise.all([
+                    ...vectorPromises,
+                    ...textPromises
+                ]);
+                // Add the results to our ids array
+                ids.push(...batchResults);
             }
             return ids;
         }
@@ -1637,20 +1530,6 @@ export class BrainyData {
             throw new Error(`Failed to add batch of items: ${error}`);
         }
     }
-    /**
-     * Add multiple vectors or data items to both local and remote databases
-     * @param items Array of items to add
-     * @param options Additional options
-     * @returns Array of IDs for the added items
-     */
-    async addBatchToBoth(items, options = {}) {
-        // Check if connected to a remote server
-        if (!this.isConnectedToRemoteServer()) {
-            throw new Error('Not connected to a remote server. Call connectToRemoteServer() first.');
-        }
-        // Add to local with addToRemote option
-        return this.addNouns(items, { ...options, addToRemote: true });
-    }
     /**
      * Filter search results by service
      * @param results Search results to filter
@@ -1929,6 +1808,12 @@ export class BrainyData {
      * @param options Simple search options (metadata filters only)
      * @returns Vector search results
      */
+    // ================================================================
+    // SECTION 3: SEARCH & DISCOVERY
+    // ================================================================
+    // Vector search, semantic search, and content discovery operations
+    // Includes find(), search(), searchLocal(), findSimilar() and related methods
+    // Powers the Triple Intelligence search combining vector + graph + field queries
     /**
      * 🔍 Simple Vector Similarity Search - Clean wrapper around find()
      *
@@ -1950,19 +1835,22 @@ export class BrainyData {
      * })
      */
     async search(queryVectorOrData, options = {}) {
-        // Build metadata filter from options
-        const metadataFilter = { ...options.metadata };
+        // Comprehensive input validation
+        const validatedQuery = validateSearchQuery(queryVectorOrData, 'queryVectorOrData');
+        const validatedOptions = validateSearchOptions(options, 'options');
+        // Build metadata filter from validated options
+        const metadataFilter = { ...validatedOptions.metadata };
         // Add noun type filtering
-        if (options.nounTypes && options.nounTypes.length > 0) {
-            metadataFilter.nounType = { in: options.nounTypes };
+        if (validatedOptions.nounTypes && validatedOptions.nounTypes.length > 0) {
+            metadataFilter.nounType = { in: validatedOptions.nounTypes };
         }
         // Add item ID filtering
-        if (options.itemIds && options.itemIds.length > 0) {
-            metadataFilter.id = { in: options.itemIds };
+        if (validatedOptions.itemIds && validatedOptions.itemIds.length > 0) {
+            metadataFilter.id = { in: validatedOptions.itemIds };
         }
         // Build simple TripleQuery for vector similarity
         const tripleQuery = {
-            like: queryVectorOrData
+            like: validatedQuery
         };
         // Add metadata filter if we have conditions
         if (Object.keys(metadataFilter).length > 0) {
@@ -1970,17 +1858,17 @@ export class BrainyData {
         }
         // Extract find() options
         const findOptions = {
-            limit: options.limit,
-            offset: options.offset,
-            cursor: options.cursor,
-            excludeDeleted: options.excludeDeleted,
-            timeout: options.timeout
+            limit: validatedOptions.limit,
+            offset: validatedOptions.offset,
+            cursor: validatedOptions.cursor,
+            excludeDeleted: validatedOptions.excludeDeleted,
+            timeout: validatedOptions.timeout
         };
         // Call find() with structured query - this is the key simplification!
         let results = await this.find(tripleQuery, findOptions);
         // Apply threshold filtering if specified
-        if (options.threshold !== undefined) {
-            results = results.filter(r => (r.fusionScore || r.score || 0) >= options.threshold);
+        if (validatedOptions.threshold !== undefined) {
+            results = results.filter(r => (r.fusionScore || r.score || 0) >= validatedOptions.threshold);
         }
         // Convert to SearchResult format
         return results.map(r => ({
@@ -2093,11 +1981,9 @@ export class BrainyData {
         if (options.searchMode === 'local') {
             return this.searchLocal(queryVectorOrData, k, options);
         }
-        else if (options.searchMode === 'remote') {
-            return this.searchRemote(queryVectorOrData, k, options);
-        }
-        else if (options.searchMode === 'combined') {
-            return this.searchCombined(queryVectorOrData, k, options);
+        else if (options.searchMode === 'remote' || options.searchMode === 'combined') {
+            // Remote and combined search modes not supported - fall back to local
+            return this.searchLocal(queryVectorOrData, k, options);
         }
         // Generate deduplication key for concurrent request handling
         const dedupeKey = RequestDeduplicator.getSearchKey(typeof queryVectorOrData === 'string' ? queryVectorOrData : JSON.stringify(queryVectorOrData), k, options);
@@ -3235,6 +3121,30 @@ export class BrainyData {
             throw new Error(`Failed to get verbs by type ${type}: ${error}`);
         }
     }
+    /**
+     * Get all verbs associated with a specific noun (both as source and target)
+     * @param nounId The ID of the noun
+     * @returns Array of verbs where the noun is either source or target
+     */
+    async getVerbsForNoun(nounId) {
+        await this.ensureInitialized();
+        try {
+            // Get verbs where this noun is the source
+            const sourceVerbs = await this.getVerbsBySource(nounId);
+            // Get verbs where this noun is the target  
+            const targetVerbs = await this.getVerbsByTarget(nounId);
+            // Combine and deduplicate (in case a verb somehow appears in both - shouldn't happen but safety first)
+            const verbMap = new Map();
+            for (const verb of [...sourceVerbs, ...targetVerbs]) {
+                verbMap.set(verb.id, verb);
+            }
+            return Array.from(verbMap.values());
+        }
+        catch (error) {
+            console.error(`Failed to get verbs for noun ${nounId}:`, error);
+            throw error;
+        }
+    }
     /**
      * Delete a verb
      * @param id The ID of the verb to delete
@@ -3248,9 +3158,16 @@ export class BrainyData {
      */
     async addVerbs(verbs) {
         const ids = [];
-        for (const verb of verbs) {
-            const id = await this.addVerb(verb.source, verb.target, verb.type, verb.metadata);
-            ids.push(id);
+        const chunkSize = 10; // Conservative chunk size for parallel processing
+        // Process verbs in parallel chunks to improve performance
+        for (let i = 0; i < verbs.length; i += chunkSize) {
+            const chunk = verbs.slice(i, i + chunkSize);
+            // Process chunk in parallel
+            const chunkPromises = chunk.map(verb => this.addVerb(verb.source, verb.target, verb.type, verb.metadata));
+            // Wait for all in chunk to complete
+            const chunkIds = await Promise.all(chunkPromises);
+            // Maintain order by adding chunk results
+            ids.push(...chunkIds);
         }
         return ids;
     }
@@ -3261,8 +3178,16 @@ export class BrainyData {
      */
     async deleteVerbs(ids) {
         const results = [];
-        for (const id of ids) {
-            results.push(await this.deleteVerb(id));
+        const chunkSize = 10; // Conservative chunk size for parallel processing
+        // Process deletions in parallel chunks to improve performance
+        for (let i = 0; i < ids.length; i += chunkSize) {
+            const chunk = ids.slice(i, i + chunkSize);
+            // Process chunk in parallel
+            const chunkPromises = chunk.map(id => this.deleteVerb(id));
+            // Wait for all in chunk to complete
+            const chunkResults = await Promise.all(chunkPromises);
+            // Maintain order by adding chunk results
+            results.push(...chunkResults);
         }
         return results;
     }
@@ -3346,6 +3271,12 @@ export class BrainyData {
             searchMemoryUsage: this.cache?.getMemoryUsage() || 0
         };
     }
+    // ================================================================
+    // SECTION 8: CACHE & PERFORMANCE
+    // ================================================================
+    // Caching, performance optimization, and memory management
+    // Includes clearCache(), performance tuning, and optimization utilities
+    // Cache management for improved response times and resource efficiency
     /**
      * Clear search cache manually (useful for testing or memory management)
      */
@@ -3514,6 +3445,12 @@ export class BrainyData {
             // Ignore errors in size calculation
         }
     }
+    // ================================================================
+    // SECTION 7: STATISTICS & MONITORING
+    // ================================================================
+    // Analytics, monitoring, and metrics collection operations
+    // Includes getStatistics(), getServiceStatistics(), performance monitoring
+    // System health reporting and data analytics for optimization
     /**
      * Get statistics about the current state of the database
      * @param options Additional options for retrieving statistics
@@ -4276,102 +4213,6 @@ export class BrainyData {
             throw new Error(`Failed to search with text query: ${error}`);
         }
     }
-    /**
-     * Search a remote Brainy server for similar vectors
-     * @param queryVectorOrData Query vector or data to search for
-     * @param k Number of results to return
-     * @param options Additional options
-     * @returns Array of search results
-     */
-    async searchRemote(queryVectorOrData, k = 10, options = {}) {
-        // TODO: Remote server search will be implemented in post-2.0.0 release
-        await this.ensureInitialized();
-        this.checkWriteOnly();
-        throw new Error('Remote server search functionality not yet implemented in Brainy 2.0.0');
-    }
-    /**
-     * Search both local and remote Brainy instances, combining the results
-     * @param queryVectorOrData Query vector or data to search for
-     * @param k Number of results to return
-     * @param options Additional options
-     * @returns Array of search results
-     */
-    async searchCombined(queryVectorOrData, k = 10, options = {}) {
-        await this.ensureInitialized();
-        // Check if database is in write-only mode
-        this.checkWriteOnly();
-        // Check if connected to a remote server
-        if (!this.isConnectedToRemoteServer()) {
-            // If not connected to a remote server, just search locally
-            return this.searchLocal(queryVectorOrData, k, options);
-        }
-        try {
-            // Default to searching local first
-            const localFirst = options.localFirst !== false;
-            if (localFirst) {
-                // Search local first
-                const localResults = await this.searchLocal(queryVectorOrData, k, options);
-                // If we have enough local results, return them
-                if (localResults.length >= k) {
-                    return localResults;
-                }
-                // Otherwise, search remote for additional results
-                const remoteResults = await this.searchRemote(queryVectorOrData, k - localResults.length, { ...options, storeResults: true });
-                // Combine results, removing duplicates
-                const combinedResults = [...localResults];
-                const localIds = new Set(localResults.map((r) => r.id));
-                for (const result of remoteResults) {
-                    if (!localIds.has(result.id)) {
-                        combinedResults.push(result);
-                    }
-                }
-                return combinedResults;
-            }
-            else {
-                // Search remote first
-                const remoteResults = await this.searchRemote(queryVectorOrData, k, {
-                    ...options,
-                    storeResults: true
-                });
-                // If we have enough remote results, return them
-                if (remoteResults.length >= k) {
-                    return remoteResults;
-                }
-                // Otherwise, search local for additional results
-                const localResults = await this.searchLocal(queryVectorOrData, k - remoteResults.length, options);
-                // Combine results, removing duplicates
-                const combinedResults = [...remoteResults];
-                const remoteIds = new Set(remoteResults.map((r) => r.id));
-                for (const result of localResults) {
-                    if (!remoteIds.has(result.id)) {
-                        combinedResults.push(result);
-                    }
-                }
-                return combinedResults;
-            }
-        }
-        catch (error) {
-            console.error('Failed to perform combined search:', error);
-            throw new Error(`Failed to perform combined search: ${error}`);
-        }
-    }
-    /**
-     * Check if the instance is connected to a remote server
-     * @returns True if connected to a remote server, false otherwise
-     */
-    isConnectedToRemoteServer() {
-        // TODO: Remote server connections will be implemented in post-2.0.0 release
-        return false;
-    }
-    /**
-     * Disconnect from the remote server
-     * @returns True if successfully disconnected, false if not connected
-     */
-    async disconnectFromRemoteServer() {
-        // TODO: Remote server disconnection will be implemented in post-2.0.0 release
-        console.warn('disconnectFromRemoteServer: Remote server functionality not yet implemented in Brainy 2.0.0');
-        return false;
-    }
     /**
      * Ensure the database is initialized
      */
@@ -4500,10 +4341,6 @@ export class BrainyData {
                     // Continue with shutdown even if statistics flush fails
                 }
             }
-            // Disconnect from remote server if connected
-            if (this.isConnectedToRemoteServer()) {
-                await this.disconnectFromRemoteServer();
-            }
             // Clean up worker pools to release resources
             cleanupWorkerPools();
             // Additional cleanup could be added here in the future
@@ -4634,8 +4471,12 @@ export class BrainyData {
                             noun.vector = await this.embeddingFunction(noun.metadata);
                         }
                     }
+                    // Extract type from metadata or default to Content
+                    const nounType = (noun.metadata && typeof noun.metadata === 'object' && 'noun' in noun.metadata)
+                        ? noun.metadata.noun
+                        : NounType.Content;
                     // Add the noun with its vector and metadata (custom ID not supported)
-                    await this.addNoun(noun.vector, noun.metadata);
+                    await this.addNoun(noun.vector, nounType, noun.metadata);
                     nounsRestored++;
                 }
                 catch (error) {
@@ -4791,8 +4632,8 @@ export class BrainyData {
                         tags: [`tag-${i % 5}`, `category-${i % 3}`]
                     }
                 };
-                // Add the noun
-                const id = await this.addNoun(metadata.description, metadata);
+                // Add the noun with explicit type
+                const id = await this.addNoun(metadata.description, nounType, metadata);
                 nounIds.push(id);
             }
             // Generate random verbs between nouns
@@ -4982,8 +4823,7 @@ export class BrainyData {
         const configValue = options?.encrypt ? await this.encryptData(JSON.stringify(value)) : value;
         // Use simple text for vectorization
         const searchableText = `Configuration setting for ${key}`;
-        await this.addNoun(searchableText, {
-            nounType: NounType.State,
+        await this.addNoun(searchableText, NounType.State, {
             configKey: key,
             configValue: configValue,
             encrypted: !!options?.encrypt,
@@ -5061,6 +4901,12 @@ export class BrainyData {
     // 6. update() - Update noun data/metadata with index sync
     // 7. delete() - Smart delete with soft delete default (enhanced original)
     // ========================================
+    // ================================================================
+    // SECTION 6: IMPORT & DATA INGESTION
+    // ================================================================
+    // Bulk data import and processing operations
+    // Includes import(), importSparseData() with neural type detection
+    // Smart parsing of CSV, JSON, YAML and automatic relationship extraction
     /**
      * Neural Import - Smart bulk data import with semantic type detection
      * Uses transformer embeddings to automatically detect and classify data types
@@ -5114,17 +4960,346 @@ export class BrainyData {
      * @param metadata Additional metadata
      * @returns Created noun ID
      */
+    // ================================================================
+    // SECTION 4: NOUN OPERATIONS (CRUD)
+    // ================================================================
+    // Create, Read, Update, Delete operations for noun entities
+    // Includes addNoun(), addNouns(), getNoun(), getNouns(), updateNoun(), deleteNoun()
+    // Core data storage and retrieval operations with metadata management
     /**
-     * Add a noun to the database
+     * Add a noun to the database with required type
      * Clean 2.0 API - primary method for adding data
      *
      * @param vectorOrData Vector array or data to embed
-     * @param metadata Metadata to store with the noun
+     * @param nounType Required noun type (one of 31 types)
+     * @param metadata Optional metadata object
      * @returns The generated ID
      */
-    async addNoun(vectorOrData, metadata) {
-        return await this.add(vectorOrData, metadata);
+    async addNoun(vectorOrData, nounType, metadata, options = {}) {
+        // Validate noun type
+        const validatedType = validateNounType(nounType);
+        // Enrich metadata with validated type
+        let enrichedMetadata = {
+            ...metadata,
+            noun: validatedType
+        };
+        await this.ensureInitialized();
+        // Check if database is in read-only mode
+        this.checkReadOnly();
+        // Distributed routing for add operations
+        if (this.shardManager && this.networkTransport && !options.id) {
+            // Generate ID early for consistent shard routing
+            const id = uuidv4();
+            // Determine which shard this data belongs to
+            const shardAssignment = this.shardManager.getShardForKey(id);
+            // If this shard is owned by another node, forward the request
+            if (shardAssignment && shardAssignment.nodeId &&
+                shardAssignment.nodeId !== this.networkTransport.nodeId) {
+                try {
+                    const response = await this.networkTransport.sendToNode(shardAssignment.nodeId, 'DISTRIBUTED_ADD', {
+                        data: vectorOrData,
+                        type: nounType,
+                        metadata: enrichedMetadata,
+                        id // Use the generated ID
+                    });
+                    if (response.success) {
+                        return response.id;
+                    }
+                    else {
+                        throw new Error(`Remote add failed: ${response.error}`);
+                    }
+                }
+                catch (error) {
+                    console.warn(`Failed to forward add to ${shardAssignment.nodeId}, falling back to local add:`, error);
+                    // Fall through to local add
+                }
+            }
+            // If we're here, either we own the shard or forwarding failed
+            options.id = id; // Use the generated ID for local add
+        }
+        // Comprehensive input validation
+        const validatedData = validateDataInput(vectorOrData, 'vectorOrData');
+        try {
+            let vector;
+            if (Array.isArray(validatedData)) {
+                for (let i = 0; i < validatedData.length; i++) {
+                    if (typeof validatedData[i] !== 'number') {
+                        throw new Error('Vector contains non-numeric values');
+                    }
+                }
+            }
+            // Check if input is already a vector
+            if (Array.isArray(validatedData) && !options.forceEmbed) {
+                // Input is already a vector (and we've validated it contains only numbers)
+                vector = validatedData;
+            }
+            else {
+                // Input needs to be vectorized
+                try {
+                    // Check if input is a JSON object and process it specially
+                    if (typeof validatedData === 'object' &&
+                        validatedData !== null &&
+                        !Array.isArray(validatedData)) {
+                        // Process JSON object for better vectorization
+                        const preparedText = prepareJsonForVectorization(validatedData, {
+                            // Prioritize common name/title fields if they exist
+                            priorityFields: [
+                                'name',
+                                'title',
+                                'company',
+                                'organization',
+                                'description',
+                                'summary'
+                            ]
+                        });
+                        vector = await this.embeddingFunction(preparedText);
+                        // IMPORTANT: When an object is passed as data and no metadata is provided,
+                        // use the object AS the metadata too. This is expected behavior for the API.
+                        // Users can pass either:
+                        // 1. addNoun(string, metadata) - vectorize string, store metadata
+                        // 2. addNoun(object) - vectorize object text, store object as metadata
+                        // 3. addNoun(object, metadata) - vectorize object text, store provided metadata
+                        if (!enrichedMetadata || Object.keys(enrichedMetadata).length === 1) { // Only has 'noun' key
+                            enrichedMetadata = { ...validatedData, noun: validatedType };
+                        }
+                        // Track field names for this JSON document
+                        const service = this.getServiceName(options);
+                        if (this.storage) {
+                            await this.storage.trackFieldNames(validatedData, service);
+                        }
+                    }
+                    else {
+                        // Use standard embedding for non-JSON data
+                        vector = await this.embeddingFunction(validatedData);
+                    }
+                }
+                catch (embedError) {
+                    throw new Error(`Failed to vectorize data: ${embedError}`);
+                }
+            }
+            // Check if vector is defined
+            if (!vector) {
+                throw new Error('Vector is undefined or null');
+            }
+            // Validate vector dimensions
+            if (vector.length !== this._dimensions) {
+                throw new Error(`Vector dimension mismatch: expected ${this._dimensions}, got ${vector.length}`);
+            }
+            // Use ID from options if it exists, otherwise from metadata, otherwise generate a new UUID
+            const id = options.id ||
+                (enrichedMetadata && typeof enrichedMetadata === 'object' && 'id' in enrichedMetadata
+                    ? enrichedMetadata.id
+                    : uuidv4());
+            // Check for existing noun (both write-only and normal modes)
+            let existingNoun;
+            if (options.id) {
+                try {
+                    if (this.writeOnly) {
+                        // In write-only mode, check storage directly
+                        existingNoun =
+                            (await this.storage.getNoun(options.id)) ?? undefined;
+                    }
+                    else {
+                        // In normal mode, check index first, then storage
+                        existingNoun = this.index.getNouns().get(options.id);
+                        if (!existingNoun) {
+                            existingNoun =
+                                (await this.storage.getNoun(options.id)) ?? undefined;
+                        }
+                    }
+                    if (existingNoun) {
+                        // Check if existing noun is a placeholder
+                        const existingMetadata = await this.storage.getMetadata(options.id);
+                        const isPlaceholder = existingMetadata &&
+                            typeof existingMetadata === 'object' &&
+                            existingMetadata.isPlaceholder;
+                        if (isPlaceholder) {
+                            // Replace placeholder with real data
+                            if (this.loggingConfig?.verbose) {
+                                console.log(`Replacing placeholder noun ${options.id} with real data`);
+                            }
+                        }
+                        else {
+                            // Real noun already exists, update it
+                            if (this.loggingConfig?.verbose) {
+                                console.log(`Updating existing noun ${options.id}`);
+                            }
+                        }
+                    }
+                }
+                catch (storageError) {
+                    // Item doesn't exist, continue with add operation
+                }
+            }
+            let noun;
+            // In write-only mode, skip index operations since index is not loaded
+            if (this.writeOnly) {
+                // Create noun object directly without adding to index
+                noun = {
+                    id,
+                    vector,
+                    connections: new Map(),
+                    level: 0, // Default level for new nodes
+                    metadata: undefined // Will be set separately
+                };
+            }
+            else {
+                // Normal mode: Add to HNSW index first
+                await this.hnswIndex.addItem({ id, vector, metadata: enrichedMetadata });
+                // Get the noun from the HNSW index
+                const indexNoun = this.hnswIndex.getNouns().get(id);
+                if (!indexNoun) {
+                    throw new Error(`Failed to retrieve newly created noun with ID ${id}`);
+                }
+                noun = indexNoun;
+            }
+            // Save noun to storage using augmentation system
+            await this.augmentations.execute('saveNoun', { noun, options }, async () => {
+                await this.storage.saveNoun(noun);
+                const service = this.getServiceName(options);
+                await this.storage.incrementStatistic('noun', service);
+            });
+            // Save metadata if provided and not empty
+            if (enrichedMetadata !== undefined) {
+                // Skip saving if metadata is an empty object
+                if (enrichedMetadata &&
+                    typeof enrichedMetadata === 'object' &&
+                    Object.keys(enrichedMetadata).length === 0) {
+                    // Don't save empty metadata
+                    // Explicitly save null to ensure no metadata is stored
+                    await this.storage.saveMetadata(id, null);
+                }
+                else {
+                    // Validate noun type if metadata is for a GraphNoun
+                    if (enrichedMetadata && typeof enrichedMetadata === 'object' && 'noun' in enrichedMetadata) {
+                        const nounType = enrichedMetadata.noun;
+                        // Check if the noun type is valid
+                        const isValidNounType = Object.values(NounType).includes(nounType);
+                        if (!isValidNounType) {
+                            console.warn(`Invalid noun type: ${nounType}. Falling back to GraphNoun.`);
+                            enrichedMetadata.noun = NounType.Concept;
+                        }
+                        // Ensure createdBy field is populated for GraphNoun
+                        const service = options.service || this.getCurrentAugmentation();
+                        const graphNoun = enrichedMetadata;
+                        // Only set createdBy if it doesn't exist or is being explicitly updated
+                        if (!graphNoun.createdBy || options.service) {
+                            graphNoun.createdBy = getAugmentationVersion(service);
+                        }
+                        // Update timestamps
+                        const now = new Date();
+                        const timestamp = {
+                            seconds: Math.floor(now.getTime() / 1000),
+                            nanoseconds: (now.getTime() % 1000) * 1000000
+                        };
+                        // Set createdAt if it doesn't exist
+                        if (!graphNoun.createdAt) {
+                            graphNoun.createdAt = timestamp;
+                        }
+                        // Always update updatedAt
+                        graphNoun.updatedAt = timestamp;
+                    }
+                    // Create properly namespaced metadata for new items
+                    let metadataToSave = createNamespacedMetadata(enrichedMetadata);
+                    // Add domain metadata if distributed mode is enabled
+                    if (this.domainDetector) {
+                        // First check if domain is already in metadata
+                        if (metadataToSave.domain) {
+                            // Domain already specified, keep it
+                            const domainInfo = this.domainDetector.detectDomain(metadataToSave);
+                            if (domainInfo.domainMetadata) {
+                                ;
+                                metadataToSave.domainMetadata =
+                                    domainInfo.domainMetadata;
+                            }
+                        }
+                        else {
+                            // Try to detect domain from the data
+                            const dataToAnalyze = Array.isArray(vectorOrData)
+                                ? enrichedMetadata
+                                : vectorOrData;
+                            const domainInfo = this.domainDetector.detectDomain(dataToAnalyze);
+                            if (domainInfo.domain) {
+                                ;
+                                metadataToSave.domain = domainInfo.domain;
+                                if (domainInfo.domainMetadata) {
+                                    ;
+                                    metadataToSave.domainMetadata =
+                                        domainInfo.domainMetadata;
+                                }
+                            }
+                        }
+                    }
+                    // Add partition information if distributed mode is enabled
+                    if (this.partitioner) {
+                        const partition = this.partitioner.getPartition(id);
+                        metadataToSave.partition = partition;
+                    }
+                    await this.storage.saveMetadata(id, metadataToSave);
+                    // Update metadata index (write-only mode should build indices!)
+                    if (this.index && !this.frozen) {
+                        await this.metadataIndex?.addToIndex?.(id, metadataToSave);
+                    }
+                    // Track metadata statistics
+                    const metadataService = this.getServiceName(options);
+                    await this.storage.incrementStatistic('metadata', metadataService);
+                    // Content type tracking removed - metrics system not initialized
+                    // Track update timestamp (handled by metrics augmentation)
+                }
+            }
+            // Update HNSW index size with actual index size
+            const indexSize = this.index.size();
+            await this.storage.updateHnswIndexSize(indexSize);
+            // Update health metrics if in distributed mode
+            if (this.monitoring) {
+                const vectorCount = await this.getNounCount();
+                this.monitoring.updateVectorCount(vectorCount);
+            }
+            // Invalidate search cache since data has changed
+            this.cache?.invalidateOnDataChange('add');
+            // Determine processing mode
+            const processingMode = options.process || 'auto';
+            let shouldProcessNeurally = false;
+            if (processingMode === 'neural') {
+                shouldProcessNeurally = true;
+            }
+            else if (processingMode === 'auto') {
+                // Auto-detect whether to use neural processing
+                shouldProcessNeurally = this.shouldAutoProcessNeurally(vectorOrData, enrichedMetadata);
+            }
+            // 'literal' mode means no neural processing
+            // 🧠 AI Processing (Neural Import) - Based on processing mode
+            if (shouldProcessNeurally) {
+                try {
+                    // Execute augmentation pipeline for data processing
+                    // Note: Augmentations will be called via this.augmentations.execute during the actual add operation
+                    // This replaces the legacy SENSE pipeline
+                    if (this.loggingConfig?.verbose) {
+                        console.log(`🧠 AI processing completed for data: ${id}`);
+                    }
+                }
+                catch (processingError) {
+                    // Don't fail the add operation if processing fails
+                    console.warn(`🧠 AI processing failed for ${id}:`, processingError);
+                }
+            }
+            return id;
+        }
+        catch (error) {
+            console.error('Failed to add vector:', error);
+            // Track error in health monitor
+            if (this.monitoring) {
+                this.monitoring.recordRequest(0, true);
+            }
+            throw new Error(`Failed to add vector: ${error}`);
+        }
     }
+    // ================================================================
+    // SECTION 5: GRAPH OPERATIONS (VERBS)
+    // ================================================================
+    // Relationship and graph operations for verb entities
+    // Includes addVerb(), addVerbs(), getVerb(), getVerbs(), relationship queries
+    // Manages typed connections between nouns with metadata and weights
     /**
      * Add Verb - Unified relationship creation between nouns
      * Creates typed relationships with proper vector embeddings from metadata
@@ -5151,10 +5326,10 @@ export class BrainyData {
             const sourceNoun = this.index.getNouns().get(sourceId);
             const targetNoun = this.index.getNouns().get(targetId);
             if (!sourceNoun) {
-                throw new Error(`Source noun with ID ${sourceId} does not exist`);
+                throw BrainyError.notFound(`Source noun with ID ${sourceId}`);
             }
             if (!targetNoun) {
-                throw new Error(`Target noun with ID ${targetId} does not exist`);
+                throw BrainyError.notFound(`Target noun with ID ${targetId}`);
             }
             // Create embeddable text from verb type and metadata for searchability
             let embeddingText = `${verbType} relationship`;
@@ -5458,10 +5633,10 @@ export class BrainyData {
             }
         };
         // Store coordination plan in _system directory
-        await this.addNoun({
+        await this.addNoun('Cortex coordination plan', NounType.Process, {
             id: '_system/coordination',
             type: 'cortex_coordination',
-            metadata: coordinationPlan
+            ...coordinationPlan
         });
         prodLog.info('📋 Storage migration coordination plan created');
         prodLog.info('All services will automatically detect and execute the migration');
@@ -5686,8 +5861,16 @@ export class BrainyData {
      */
     async deleteNouns(ids) {
         const results = [];
-        for (const id of ids) {
-            results.push(await this.deleteNoun(id));
+        const chunkSize = 10; // Conservative chunk size for parallel processing
+        // Process deletions in parallel chunks to improve performance
+        for (let i = 0; i < ids.length; i += chunkSize) {
+            const chunk = ids.slice(i, i + chunkSize);
+            // Process chunk in parallel
+            const chunkPromises = chunk.map(id => this.deleteNoun(id));
+            // Wait for all in chunk to complete
+            const chunkResults = await Promise.all(chunkPromises);
+            // Maintain order by adding chunk results
+            results.push(...chunkResults);
         }
         return results;
     }
@@ -5712,7 +5895,7 @@ export class BrainyData {
                 // For data updates, we need to regenerate the vector
                 const existingNoun = this.index.getNouns().get(id);
                 if (!existingNoun) {
-                    throw new Error(`Noun with ID ${id} does not exist`);
+                    throw BrainyError.notFound(`Noun with ID ${id}`);
                 }
                 // Get existing metadata from storage (not just from index)
                 const existingMetadata = await this.storage.getMetadata(id) || {};
@@ -5801,7 +5984,7 @@ export class BrainyData {
             // Check if a vector exists
             const noun = this.index.getNouns().get(id);
             if (!noun) {
-                throw new Error(`Vector with ID ${id} does not exist`);
+                throw BrainyError.notFound(`Vector with ID ${id}`);
             }
             // Get existing metadata to preserve namespaces
             const existing = await this.storage.getMetadata(id) || {};
@@ -5868,34 +6051,41 @@ export class BrainyData {
     get neural() {
         if (!this._neural) {
             // Create the unified Neural API instance
-            this._neural = new NeuralAPI(this);
+            this._neural = new ImprovedNeuralAPI(this);
         }
         return this._neural;
     }
     /**
      * Simple similarity check (shorthand for neural.similar)
      */
-    async similar(a, b) {
-        return this.neural.similar(a, b);
+    async similar(a, b, options) {
+        const result = await this.neural.similar(a, b, options);
+        // Always return simple number for main class shortcut
+        return typeof result === 'object' ? result.score : result;
     }
     /**
      * Get semantic clusters (shorthand for neural.clusters)
      */
-    async clusters(options) {
-        return this.neural.clusters(options);
+    async clusters(items, options) {
+        // Support both (items, options) and (options) patterns
+        if (typeof items === 'object' && !Array.isArray(items) && options === undefined) {
+            // First argument is options object
+            return this.neural.clusters(items);
+        }
+        // Standard (items, options) pattern
+        if (options) {
+            return this.neural.clusters({ ...options, items });
+        }
+        return this.neural.clusters(items);
     }
     /**
      * Get related items (shorthand for neural.neighbors)
      */
-    async related(id, limit) {
-        const result = await this.neural.neighbors(id, { limit });
-        return result.neighbors;
-    }
-    /**
-     * Get visualization data (shorthand for neural.visualize)
-     */
-    async visualize(options) {
-        return this.neural.visualize(options);
+    async related(id, options) {
+        const limit = typeof options === 'number' ? options : options?.limit;
+        const fullOptions = typeof options === 'number' ? { limit } : options;
+        const result = await this.neural.neighbors(id, fullOptions);
+        return result.neighbors || [];
     }
     /**
      * 🚀 TRIPLE INTELLIGENCE SEARCH - Natural Language & Complex Queries
@@ -5924,60 +6114,9 @@ export class BrainyData {
         const { limit = 10, offset = 0, cursor, mode = 'auto', maxDepth = 2, parallel = true, timeout, excludeDeleted = true } = options || {};
         // Validate and cap limit for safety
         const safeLimit = Math.min(limit, 10000);
-        if (!this._tripleEngine) {
-            this._tripleEngine = new TripleIntelligenceEngine(this);
-        }
-        // 🎆 NATURAL LANGUAGE AUTO-BREAKDOWN
-        // If query is a string, auto-convert to structured Triple Intelligence query
-        let processedQuery;
-        if (typeof query === 'string') {
-            // Use Brainy's sophisticated natural language processing
-            processedQuery = await this.processNaturalLanguage(query);
-        }
-        else {
-            processedQuery = query;
-        }
-        // Apply pagination options
-        processedQuery.limit = safeLimit;
-        // Handle cursor-based pagination
-        if (cursor) {
-            const decodedCursor = this.decodeCursor(cursor);
-            processedQuery.offset = decodedCursor.offset;
-        }
-        else if (offset > 0) {
-            processedQuery.offset = offset;
-        }
-        // Add soft-delete filter using POSITIVE match (O(1) hash lookup)
-        // We use _brainy.deleted to avoid conflicts with user metadata
-        if (excludeDeleted) {
-            if (!processedQuery.where) {
-                processedQuery.where = {};
-            }
-            // Use namespaced field for O(1) hash lookup in metadata index
-            processedQuery.where['_brainy.deleted'] = false; // or { equals: false }
-        }
-        // Apply mode-specific optimizations
-        if (mode !== 'auto') {
-            processedQuery.mode = mode;
-        }
-        // Apply graph traversal depth limit
-        if (processedQuery.connected) {
-            processedQuery.connected.maxDepth = Math.min(processedQuery.connected.maxDepth || maxDepth, maxDepth);
-        }
-        // Execute with Triple Intelligence engine
-        const results = await this._tripleEngine.find(processedQuery);
-        // Generate next cursor if we hit the limit
-        if (results.length === safeLimit) {
-            const nextCursor = this.encodeCursor({
-                offset: (offset || 0) + safeLimit,
-                timestamp: Date.now()
-            });
-            // Attach cursor to last result for convenience
-            if (results.length > 0) {
-                results[results.length - 1].nextCursor = nextCursor;
-            }
-        }
-        return results;
+        // Triple Intelligence now requires Brainy, not BrainyData
+        // BrainyData is deprecated - use Brainy.find() instead
+        throw new Error('Triple Intelligence search is not available in BrainyData. Please use Brainy.find() instead.');
     }
     /**
      * 🧠 NATURAL LANGUAGE PROCESSING - Auto-breakdown using all Brainy features
@@ -6127,7 +6266,7 @@ export class BrainyData {
      * @returns The BrainyData instance for chaining
      */
     unregister(name) {
-        augmentationPipeline.unregister(name);
+        // Deprecated: use brain.augmentations instead
         return this;
     }
     /**
@@ -6138,7 +6277,8 @@ export class BrainyData {
      * @returns True if augmentation was found and enabled
      */
     enableAugmentation(name) {
-        return augmentationPipeline.enableAugmentation(name);
+        // Deprecated: use brain.augmentations instead
+        return false;
     }
     /**
      * Disable an augmentation by name
@@ -6148,7 +6288,8 @@ export class BrainyData {
      * @returns True if augmentation was found and disabled
      */
     disableAugmentation(name) {
-        return augmentationPipeline.disableAugmentation(name);
+        // Deprecated: use brain.augmentations instead
+        return false;
     }
     /**
      * Check if an augmentation is enabled
@@ -6157,7 +6298,8 @@ export class BrainyData {
      * @returns True if augmentation is found and enabled, false otherwise
      */
     isAugmentationEnabled(name) {
-        return augmentationPipeline.isAugmentationEnabled(name);
+        // Deprecated: use brain.augmentations instead
+        return false;
     }
     /**
      * Get all augmentations with their enabled status
@@ -6166,7 +6308,13 @@ export class BrainyData {
      * @returns Array of augmentations with name, type, and enabled status
      */
     listAugmentations() {
-        return augmentationPipeline.listAugmentationsWithStatus();
+        // Use the real augmentation registry instead of deprecated pipeline
+        return this.augmentations.getInfo().map(aug => ({
+            name: aug.name,
+            type: aug.category, // Map category to type for backward compatibility
+            enabled: aug.enabled,
+            description: aug.description
+        }));
     }
     /**
      * Enable all augmentations of a specific type
@@ -6175,7 +6323,8 @@ export class BrainyData {
      * @returns Number of augmentations enabled
      */
     enableAugmentationType(type) {
-        return augmentationPipeline.enableAugmentationType(type);
+        // Deprecated: use brain.augmentations instead
+        return 0;
     }
     /**
      * Disable all augmentations of a specific type
@@ -6184,7 +6333,8 @@ export class BrainyData {
      * @returns Number of augmentations disabled
      */
     disableAugmentationType(type) {
-        return augmentationPipeline.disableAugmentationType(type);
+        // Deprecated: use brain.augmentations instead
+        return 0;
     }
     // ===== Enhanced Clear Methods (2.0.0 API) =====
     /**
@@ -6275,6 +6425,12 @@ export class BrainyData {
             throw new Error(`Failed to clear all data: ${error}`);
         }
     }
+    // ================================================================
+    // SECTION 9: UTILITIES & CLEANUP  
+    // ================================================================
+    // System utilities, cleanup operations, and maintenance functions
+    // Includes clearAll(), database maintenance, and system shutdown operations
+    // Essential maintenance and administrative functionality
     /**
      * Clear all data from the database (alias for clear)
      * @param options Options including force flag to skip confirmation