@soulcraft/brainy 3.8.3 → 3.9.0

package/dist/brainy.d.ts

@@ -26,6 +26,10 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     private distance;
     private augmentationRegistry;
     private config;
+    private coordinator?;
+    private shardManager?;
+    private cacheSync?;
+    private readWriteSeparation?;
     private originalConsole?;
     private _neural?;
     private _nlp?;
@@ -111,6 +115,16 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Clear all data from the database
      */
     clear(): Promise<void>;
+    /**
+     * Get total count of nouns - O(1) operation
+     * @returns Promise that resolves to the total number of nouns
+     */
+    getNounCount(): Promise<number>;
+    /**
+     * Get total count of verbs - O(1) operation
+     * @returns Promise that resolves to the total number of verbs
+     */
+    getVerbCount(): Promise<number>;
     /**
      * Neural API - Advanced AI operations
      */
@@ -353,6 +367,19 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Close and cleanup
      */
     close(): Promise<void>;
+    /**
+     * Intelligently auto-detect distributed configuration
+     * Zero-config: Automatically determines best distributed settings
+     */
+    private autoDetectDistributed;
+    /**
+     * Setup distributed components with zero-config intelligence
+     */
+    private setupDistributedComponents;
+    /**
+     * Pass distributed components to storage adapter
+     */
+    private connectDistributedStorage;
 }
 export * from './types/brainy.types.js';
 export { NounType, VerbType } from './types/graphTypes.js';

package/dist/brainy.js

@@ -18,6 +18,7 @@ import { MetadataIndexManager } from './utils/metadataIndex.js';
 import { GraphAdjacencyIndex } from './graph/graphAdjacencyIndex.js';
 import { createPipeline } from './streaming/pipeline.js';
 import { configureLogger, LogLevel } from './utils/logger.js';
+import { DistributedCoordinator, ShardManager, CacheSync, ReadWriteSeparation } from './distributed/index.js';
 import { NounType } from './types/graphTypes.js';
 /**
  * The main Brainy class - Clean, Beautiful, Powerful
@@ -35,6 +36,10 @@ export class Brainy {
         this.distance = cosineDistance;
         this.embedder = this.setupEmbedder();
         this.augmentationRegistry = this.setupAugmentations();
+        // Setup distributed components if enabled
+        if (this.config.distributed?.enabled) {
+            this.setupDistributedComponents();
+        }
         // Index and storage are initialized in init() because they may need each other
     }
     /**
@@ -113,6 +118,8 @@ export class Brainy {
                     }
                 }
             });
+            // Connect distributed components to storage
+            await this.connectDistributedStorage();
             // Warm up if configured
             if (this.config.warmup) {
                 await this.warmup();
@@ -269,6 +276,10 @@ export class Brainy {
      * Delete an entity
      */
     async delete(id) {
+        // Handle invalid IDs gracefully
+        if (!id || typeof id !== 'string') {
+            return; // Silently return for invalid IDs
+        }
         await this.ensureInitialized();
         return this.augmentationRegistry.execute('delete', { id }, async () => {
             // Remove from vector index
@@ -289,6 +300,9 @@ export class Brainy {
             const targetVerbs = await this.storage.getVerbsByTarget(id);
             const allVerbs = [...verbs, ...targetVerbs];
             for (const verb of allVerbs) {
+                // Remove from graph index first
+                await this.graphIndex.removeVerb(verb.id);
+                // Then delete from storage
                 await this.storage.deleteVerb(verb.id);
             }
         });
@@ -407,10 +421,53 @@ export class Brainy {
         const startTime = Date.now();
         const result = await this.augmentationRegistry.execute('find', params, async () => {
             let results = [];
-            // Handle empty query - return paginated results from storage
-            const hasSearchCriteria = params.query || params.vector || params.where ||
-                params.type || params.service || params.near || params.connected;
-            if (!hasSearchCriteria) {
+            // Distinguish between search criteria (need vector search) and filter criteria (metadata only)
+            // Treat empty string query as no query
+            const hasVectorSearchCriteria = (params.query && params.query.trim() !== '') || params.vector || params.near;
+            const hasFilterCriteria = params.where || params.type || params.service;
+            const hasGraphCriteria = params.connected;
+            // Handle metadata-only queries (no vector search needed)
+            if (!hasVectorSearchCriteria && !hasGraphCriteria && hasFilterCriteria) {
+                // Build filter for metadata index
+                let filter = {};
+                if (params.where)
+                    Object.assign(filter, params.where);
+                if (params.service)
+                    filter.service = params.service;
+                if (params.type) {
+                    const types = Array.isArray(params.type) ? params.type : [params.type];
+                    if (types.length === 1) {
+                        filter.noun = types[0];
+                    }
+                    else {
+                        filter = {
+                            anyOf: types.map(type => ({
+                                noun: type,
+                                ...filter
+                            }))
+                        };
+                    }
+                }
+                // Get filtered IDs and paginate BEFORE loading entities
+                const filteredIds = await this.metadataIndex.getIdsForFilter(filter);
+                const limit = params.limit || 10;
+                const offset = params.offset || 0;
+                const pageIds = filteredIds.slice(offset, offset + limit);
+                // Load entities for the paginated results
+                for (const id of pageIds) {
+                    const entity = await this.get(id);
+                    if (entity) {
+                        results.push({
+                            id,
+                            score: 1.0, // All metadata-filtered results equally relevant
+                            entity
+                        });
+                    }
+                }
+                return results;
+            }
+            // Handle completely empty query - return all results paginated
+            if (!hasVectorSearchCriteria && !hasFilterCriteria && !hasGraphCriteria) {
                 const limit = params.limit || 20;
                 const offset = params.offset || 0;
                 const storageResults = await this.storage.getNouns({
@@ -803,6 +860,22 @@ export class Brainy {
             this._tripleIntelligence = undefined;
         });
     }
+    /**
+     * Get total count of nouns - O(1) operation
+     * @returns Promise that resolves to the total number of nouns
+     */
+    async getNounCount() {
+        await this.ensureInitialized();
+        return this.storage.getNounCount();
+    }
+    /**
+     * Get total count of verbs - O(1) operation
+     * @returns Promise that resolves to the total number of verbs
+     */
+    async getVerbCount() {
+        await this.ensureInitialized();
+        return this.storage.getVerbCount();
+    }
     // ============= SUB-APIS =============
     /**
      * Neural API - Advanced AI operations
@@ -1462,18 +1535,27 @@ export class Brainy {
         if (config?.index?.efSearch && (config.index.efSearch < 1 || config.index.efSearch > 1000)) {
             throw new Error(`Invalid index efSearch: ${config.index.efSearch}. Must be between 1 and 1000`);
         }
+        // Auto-detect distributed mode based on environment and configuration
+        const distributedConfig = this.autoDetectDistributed(config?.distributed);
         return {
             storage: config?.storage || { type: 'auto' },
             model: config?.model || { type: 'fast' },
             index: config?.index || {},
             cache: config?.cache ?? true,
             augmentations: config?.augmentations || {},
+            distributed: distributedConfig, // Type will be fixed when used
             warmup: config?.warmup ?? false,
             realtime: config?.realtime ?? false,
             multiTenancy: config?.multiTenancy ?? false,
             telemetry: config?.telemetry ?? false,
             verbose: config?.verbose ?? false,
-            silent: config?.silent ?? false
+            silent: config?.silent ?? false,
+            // New performance options with smart defaults
+            disableAutoRebuild: config?.disableAutoRebuild ?? false, // false = auto-decide based on size
+            disableMetrics: config?.disableMetrics ?? false,
+            disableAutoOptimize: config?.disableAutoOptimize ?? false,
+            batchWrites: config?.batchWrites ?? true,
+            maxConcurrentOperations: config?.maxConcurrentOperations ?? 10
         };
     }
     /**
@@ -1483,17 +1565,49 @@ export class Brainy {
         try {
             // Check if storage has data
             const entities = await this.storage.getNouns({ pagination: { limit: 1 } });
-            if (entities.totalCount === 0 || entities.items.length === 0) {
+            const totalCount = entities.totalCount || 0;
+            if (totalCount === 0) {
                 // No data in storage, no rebuild needed
                 return;
             }
+            // Intelligent decision: Auto-rebuild only for small datasets
+            // For large datasets, use lazy loading for optimal performance
+            const AUTO_REBUILD_THRESHOLD = 1000; // Only auto-rebuild if < 1000 items
             // Check if metadata index is empty
             const metadataStats = await this.metadataIndex.getStats();
-            if (metadataStats.totalEntries === 0) {
-                console.log('🔄 Rebuilding metadata index for existing data...');
+            if (metadataStats.totalEntries === 0 && totalCount > 0) {
+                if (totalCount < AUTO_REBUILD_THRESHOLD) {
+                    // Small dataset - rebuild for convenience
+                    if (!this.config.silent) {
+                        console.log(`🔄 Small dataset (${totalCount} items) - rebuilding index for optimal performance...`);
+                    }
+                    await this.metadataIndex.rebuild();
+                    const newStats = await this.metadataIndex.getStats();
+                    if (!this.config.silent) {
+                        console.log(`✅ Index rebuilt: ${newStats.totalEntries} entries`);
+                    }
+                }
+                else {
+                    // Large dataset - use lazy loading
+                    if (!this.config.silent) {
+                        console.log(`⚡ Large dataset (${totalCount} items) - using lazy loading for optimal startup performance`);
+                        console.log('💡 Tip: Indexes will build automatically as you use the system');
+                    }
+                }
+            }
+            // Override with explicit config if provided
+            if (this.config.disableAutoRebuild === true) {
+                if (!this.config.silent) {
+                    console.log('⚡ Auto-rebuild explicitly disabled via config');
+                }
+                return;
+            }
+            else if (this.config.disableAutoRebuild === false && metadataStats.totalEntries === 0) {
+                // Explicitly enabled - rebuild regardless of size
+                if (!this.config.silent) {
+                    console.log('🔄 Auto-rebuild explicitly enabled - rebuilding index...');
+                }
                 await this.metadataIndex.rebuild();
-                const newStats = await this.metadataIndex.getStats();
-                console.log(`✅ Metadata index rebuilt: ${newStats.totalEntries} entries`);
             }
             // Note: GraphAdjacencyIndex will rebuild itself as relationships are added
             // Vector index should already be populated if storage has data
@@ -1525,6 +1639,113 @@ export class Brainy {
         // We'll just mark as not initialized
         this.initialized = false;
     }
+    /**
+     * Intelligently auto-detect distributed configuration
+     * Zero-config: Automatically determines best distributed settings
+     */
+    autoDetectDistributed(config) {
+        // If explicitly disabled, respect that
+        if (config?.enabled === false) {
+            return config;
+        }
+        // Auto-detect based on environment variables (common in production)
+        const envEnabled = process.env.BRAINY_DISTRIBUTED === 'true' ||
+            process.env.NODE_ENV === 'production' ||
+            process.env.CLUSTER_SIZE ||
+            process.env.KUBERNETES_SERVICE_HOST; // Running in K8s
+        // Auto-detect based on storage type (S3/R2/GCS implies distributed)
+        const storageImpliesDistributed = this.config?.storage?.type === 's3' ||
+            this.config?.storage?.type === 'r2' ||
+            this.config?.storage?.type === 'gcs';
+        // If not explicitly configured but environment suggests distributed
+        if (!config && (envEnabled || storageImpliesDistributed)) {
+            return {
+                enabled: true,
+                nodeId: process.env.HOSTNAME || process.env.NODE_ID || `node-${Date.now()}`,
+                nodes: process.env.BRAINY_NODES?.split(',') || [],
+                coordinatorUrl: process.env.BRAINY_COORDINATOR || undefined,
+                shardCount: parseInt(process.env.BRAINY_SHARDS || '64'),
+                replicationFactor: parseInt(process.env.BRAINY_REPLICAS || '3'),
+                consensus: process.env.BRAINY_CONSENSUS || 'raft',
+                transport: process.env.BRAINY_TRANSPORT || 'http'
+            };
+        }
+        // Merge with provided config, applying intelligent defaults
+        return config ? {
+            ...config,
+            nodeId: config.nodeId || process.env.HOSTNAME || `node-${Date.now()}`,
+            shardCount: config.shardCount || 64,
+            replicationFactor: config.replicationFactor || 3,
+            consensus: config.consensus || 'raft',
+            transport: config.transport || 'http'
+        } : undefined;
+    }
+    /**
+     * Setup distributed components with zero-config intelligence
+     */
+    setupDistributedComponents() {
+        const distConfig = this.config.distributed;
+        if (!distConfig?.enabled)
+            return;
+        console.log('🌍 Initializing distributed mode:', {
+            nodeId: distConfig.nodeId,
+            shards: distConfig.shardCount,
+            replicas: distConfig.replicationFactor
+        });
+        // Initialize coordinator for consensus
+        this.coordinator = new DistributedCoordinator({
+            nodeId: distConfig.nodeId,
+            address: distConfig.coordinatorUrl?.split(':')[0] || 'localhost',
+            port: parseInt(distConfig.coordinatorUrl?.split(':')[1] || '8080'),
+            nodes: distConfig.nodes
+        });
+        // Start the coordinator to establish leadership
+        this.coordinator.start().catch(err => {
+            console.warn('Coordinator start failed (will retry on init):', err.message);
+        });
+        // Initialize shard manager for data distribution
+        this.shardManager = new ShardManager({
+            shardCount: distConfig.shardCount,
+            replicationFactor: distConfig.replicationFactor,
+            virtualNodes: 150, // Optimal for consistent distribution
+            autoRebalance: true
+        });
+        // Initialize cache synchronization
+        this.cacheSync = new CacheSync({
+            nodeId: distConfig.nodeId,
+            syncInterval: 1000
+        });
+        // Initialize read/write separation if we have replicas
+        // Note: Will be properly initialized after coordinator starts
+        if (distConfig.replicationFactor && distConfig.replicationFactor > 1) {
+            // Defer creation until coordinator is ready
+            setTimeout(() => {
+                this.readWriteSeparation = new ReadWriteSeparation({
+                    nodeId: distConfig.nodeId,
+                    consistencyLevel: 'eventual',
+                    role: 'replica', // Start as replica, will promote if leader
+                    syncInterval: 5000
+                }, this.coordinator, this.shardManager, this.cacheSync);
+            }, 100);
+        }
+    }
+    /**
+     * Pass distributed components to storage adapter
+     */
+    async connectDistributedStorage() {
+        if (!this.config.distributed?.enabled)
+            return;
+        // Check if storage supports distributed operations
+        if ('setDistributedComponents' in this.storage) {
+            this.storage.setDistributedComponents({
+                coordinator: this.coordinator,
+                shardManager: this.shardManager,
+                cacheSync: this.cacheSync,
+                readWriteSeparation: this.readWriteSeparation
+            });
+            console.log('✅ Distributed storage connected');
+        }
+    }
 }
 // Re-export types for convenience
 export * from './types/brainy.types.js';

package/dist/coreTypes.d.ts

@@ -512,4 +512,14 @@ export interface StorageAdapter {
      * @returns Promise that resolves to an array of changes
      */
     getChangesSince?(timestamp: number, limit?: number): Promise<any[]>;
+    /**
+     * Get total count of nouns in storage - O(1) operation
+     * @returns Promise that resolves to the total number of nouns
+     */
+    getNounCount(): Promise<number>;
+    /**
+     * Get total count of verbs in storage - O(1) operation
+     * @returns Promise that resolves to the total number of verbs
+     */
+    getVerbCount(): Promise<number>;
 }

package/dist/hnsw/hnswIndex.d.ts

@@ -7,6 +7,8 @@ export declare class HNSWIndex {
     private nouns;
     private entryPointId;
     private maxLevel;
+    private highLevelNodes;
+    private readonly MAX_TRACKED_LEVELS;
     private config;
     private distanceFunction;
     private dimension;

package/dist/hnsw/hnswIndex.js

@@ -15,6 +15,9 @@ export class HNSWIndex {
         this.nouns = new Map();
         this.entryPointId = null;
         this.maxLevel = 0;
+        // Track high-level nodes for O(1) entry point selection
+        this.highLevelNodes = new Map(); // level -> node IDs
+        this.MAX_TRACKED_LEVELS = 10; // Only track top levels for memory efficiency
         this.dimension = null;
         this.useParallelization = true; // Whether to use parallelization for performance-critical operations
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -203,6 +206,13 @@ export class HNSWIndex {
         }
         // Add noun to the index
         this.nouns.set(id, noun);
+        // Track high-level nodes for O(1) entry point selection
+        if (nounLevel >= 2 && nounLevel <= this.MAX_TRACKED_LEVELS) {
+            if (!this.highLevelNodes.has(nounLevel)) {
+                this.highLevelNodes.set(nounLevel, new Set());
+            }
+            this.highLevelNodes.get(nounLevel).add(id);
+        }
         return id;
     }
     /**

package/dist/neural/improvedNeuralAPI.d.ts

@@ -159,8 +159,21 @@ export declare class ImprovedNeuralAPI {
      * Group items by their semantic noun types
      */
     private _groupBySemanticType;
-    private _getAllItemIds;
+    /**
+     * Iterate through all items without loading them all at once
+     * This scales to millions of items without memory issues
+     */
+    private _iterateAllItems;
+    /**
+     * Get a sample of item IDs for operations that don't need all items
+     * This is O(1) for small samples
+     */
+    private _getSampleItemIds;
+    /**
+     * Get total count using the brain's O(1) counting API
+     */
     private _getTotalItemCount;
+    private _getAllItemIds;
     private _calculateTotalWeight;
     private _getNeighborCommunities;
     private _calculateModularityGain;

package/dist/neural/improvedNeuralAPI.js

@@ -80,8 +80,8 @@ export class ImprovedNeuralAPI {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             throw new SimilarityError(`Failed to calculate similarity: ${errorMessage}`, {
-                inputA: typeof a === 'object' ? 'vector' : String(a).substring(0, 50),
-                inputB: typeof b === 'object' ? 'vector' : String(b).substring(0, 50),
+                inputA: Array.isArray(a) ? 'vector' : typeof a === 'string' ? a.substring(0, 50) : 'unknown',
+                inputB: Array.isArray(b) ? 'vector' : typeof b === 'string' ? b.substring(0, 50) : 'unknown',
                 options
             });
         }
@@ -1172,8 +1172,8 @@ export class ImprovedNeuralAPI {
     // Utility methods for internal operations
     _isId(value) {
         return typeof value === 'string' &&
-            (value.length === 36 && value.includes('-')) || // UUID-like
-            (value.length > 10 && !value.includes(' ')); // ID-like string
+            ((value.length === 36 && value.includes('-')) || // UUID-like
+                (value.length > 10 && !value.includes(' '))); // ID-like string
     }
     _isVector(value) {
         return Array.isArray(value) &&
@@ -1441,28 +1441,67 @@ export class ImprovedNeuralAPI {
         }
         return groups;
     }
-    // Placeholder implementations for complex operations
-    async _getAllItemIds() {
-        // Get all noun IDs from the brain
-        // Get total item count using find with empty query
-        const allItems = await this.brain.find({ query: '', limit: Number.MAX_SAFE_INTEGER });
-        const stats = { totalNouns: allItems.length || 0 };
-        if (!stats.totalNouns || stats.totalNouns === 0) {
-            return [];
+    // Iterator-based implementations for scalability
+    /**
+     * Iterate through all items without loading them all at once
+     * This scales to millions of items without memory issues
+     */
+    async *_iterateAllItems(options) {
+        const batchSize = options?.batchSize || 1000;
+        let cursor;
+        let hasMore = true;
+        while (hasMore) {
+            const result = await this.brain.find({
+                query: '',
+                limit: batchSize,
+                cursor
+            });
+            for (const item of result.items || result) {
+                yield item;
+            }
+            hasMore = result.hasMore || false;
+            cursor = result.nextCursor;
+            // Safety check to prevent infinite loops
+            if (!result.items || result.items.length === 0) {
+                break;
+            }
         }
-        // Get nouns with pagination (limit to 10000 for performance)
-        const limit = Math.min(stats.totalNouns, 10000);
+    }
+    /**
+     * Get a sample of item IDs for operations that don't need all items
+     * This is O(1) for small samples
+     */
+    async _getSampleItemIds(sampleSize = 1000) {
         const result = await this.brain.find({
             query: '',
-            limit
+            limit: Math.min(sampleSize, 10000) // Cap at 10k for safety
         });
-        return result.map((item) => item.id).filter((id) => id);
+        const items = result.items || result;
+        return items.map((item) => item.entity?.id || item.id).filter((id) => id);
     }
+    /**
+     * Get total count using the brain's O(1) counting API
+     */
     async _getTotalItemCount() {
-        // Get total item count using find with empty query
-        const allItems = await this.brain.find({ query: '', limit: Number.MAX_SAFE_INTEGER });
-        const stats = { totalNouns: allItems.length || 0 };
-        return stats.totalNouns || 0;
+        // Use the brain's O(1) counting API if available
+        if (this.brain.counts && typeof this.brain.counts.entities === 'function') {
+            return await this.brain.counts.entities();
+        }
+        // Fallback: Get from storage statistics
+        const storage = this.brain.storage;
+        if (storage && typeof storage.getStatistics === 'function') {
+            const stats = await storage.getStatistics();
+            return stats?.totalNodes || 0;
+        }
+        // Last resort: Sample and estimate
+        const sample = await this.brain.find({ query: '', limit: 1 });
+        return sample.totalCount || 0;
+    }
+    // Deprecated: Remove methods that load everything
+    // These are kept for backward compatibility but should not be used
+    async _getAllItemIds() {
+        console.warn('⚠️ _getAllItemIds() is deprecated and will fail with large datasets. Use _iterateAllItems() or _getSampleItemIds() instead.');
+        return this._getSampleItemIds(10000); // Return sample only
     }
     // ===== GRAPH ALGORITHM SUPPORTING METHODS =====
     _calculateTotalWeight(edges) {

package/dist/neural/naturalLanguageProcessorStatic.d.ts

@@ -47,6 +47,7 @@ export declare class NaturalLanguageProcessor {
     private buildFieldConstraints;
     /**
      * Find similar queries from history (without using Brainy)
+     * NOTE: Currently unused - reserved for future query caching optimization
      */
     private findSimilarQueries;
     /**

package/dist/neural/naturalLanguageProcessorStatic.js

@@ -119,10 +119,11 @@ export class NaturalLanguageProcessor {
     }
     /**
      * Find similar queries from history (without using Brainy)
+     * NOTE: Currently unused - reserved for future query caching optimization
      */
     findSimilarQueries(embedding) {
-        // Simple similarity check against recent history
-        // This is just a placeholder - real implementation would use cosine similarity
+        // Not implemented - not required for core functionality
+        // Would implement cosine similarity against queryHistory if needed
         return [];
     }
     /**

package/dist/storage/adapters/baseStorageAdapter.d.ts

@@ -253,4 +253,63 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
      * Include throttling metrics in statistics
      */
     getStatisticsWithThrottling(): Promise<StatisticsData | null>;
+    protected totalNounCount: number;
+    protected totalVerbCount: number;
+    protected entityCounts: Map<string, number>;
+    protected verbCounts: Map<string, number>;
+    protected countCache: Map<string, {
+        count: number;
+        timestamp: number;
+    }>;
+    protected readonly COUNT_CACHE_TTL = 60000;
+    /**
+     * Get total noun count - O(1) operation
+     * @returns Promise that resolves to the total number of nouns
+     */
+    getNounCount(): Promise<number>;
+    /**
+     * Get total verb count - O(1) operation
+     * @returns Promise that resolves to the total number of verbs
+     */
+    getVerbCount(): Promise<number>;
+    /**
+     * Increment count for entity type - O(1) operation
+     * Protected by storage-specific mechanisms (mutex, distributed consensus, etc.)
+     * @param type The entity type
+     */
+    protected incrementEntityCount(type: string): void;
+    /**
+     * Thread-safe increment for concurrent scenarios
+     * Uses mutex for single-node, distributed consensus for multi-node
+     */
+    protected incrementEntityCountSafe(type: string): Promise<void>;
+    /**
+     * Decrement count for entity type - O(1) operation
+     * @param type The entity type
+     */
+    protected decrementEntityCount(type: string): void;
+    /**
+     * Thread-safe decrement for concurrent scenarios
+     */
+    protected decrementEntityCountSafe(type: string): Promise<void>;
+    /**
+     * Increment verb count - O(1) operation with mutex protection
+     * @param type The verb type
+     */
+    protected incrementVerbCount(type: string): Promise<void>;
+    /**
+     * Decrement verb count - O(1) operation with mutex protection
+     * @param type The verb type
+     */
+    protected decrementVerbCount(type: string): Promise<void>;
+    /**
+     * Initialize counts from storage - must be implemented by each adapter
+     * @protected
+     */
+    protected abstract initializeCounts(): Promise<void>;
+    /**
+     * Persist counts to storage - must be implemented by each adapter
+     * @protected
+     */
+    protected abstract persistCounts(): Promise<void>;
 }