brainy/src/types/distributedTypes.ts

/**
 * Distributed types for Brainy
 * Defines types for distributed operations across multiple instances
 */

export type InstanceRole = 'reader' | 'writer' | 'hybrid'

export type PartitionStrategy = 'hash' | 'semantic' | 'manual'

export interface DistributedConfig {
  /**
   * Enable distributed mode
   * Can be boolean for auto-detection or specific configuration
   */
  enabled?: boolean | 'auto'
  
  /**
   * Role of this instance in the distributed system
   * - reader: Read-only access, optimized for queries
   * - writer: Write-focused, handles data ingestion
   * - hybrid: Can both read and write (requires coordination)
   */
  role?: InstanceRole
  
  /**
   * Unique identifier for this instance
   * Auto-generated if not provided
   */
  instanceId?: string
  
  /**
   * Path to shared configuration file in S3
   * Default: '_brainy/config.json'
   */
  configPath?: string
  
  /**
   * Heartbeat interval in milliseconds
   * Default: 30000 (30 seconds)
   */
  heartbeatInterval?: number
  
  /**
   * Config check interval in milliseconds
   * Default: 10000 (10 seconds)
   */
  configCheckInterval?: number
  
  /**
   * Instance timeout in milliseconds
   * Instances not seen for this duration are considered dead
   * Default: 60000 (60 seconds)
   */
  instanceTimeout?: number
}

export interface SharedConfig {
  /**
   * Configuration version for compatibility checking
   */
  version: number
  
  /**
   * Last update timestamp
   */
  updated: string
  
  /**
   * Global settings that must be consistent across all instances
   */
  settings: {
    /**
     * Partitioning strategy
     * - hash: Deterministic hash-based partitioning (recommended for multi-writer)
     * - semantic: Group similar vectors (single writer only)
     * - manual: Explicit partition assignment
     */
    partitionStrategy: PartitionStrategy
    
    /**
     * Number of partitions (for hash strategy)
     */
    partitionCount: number
    
    /**
     * Embedding model name (must be consistent)
     */
    embeddingModel: string
    
    /**
     * Vector dimensions
     */
    dimensions: number
    
    /**
     * Distance metric
     */
    distanceMetric: 'cosine' | 'euclidean' | 'manhattan'
    
    /**
     * HNSW parameters (must be consistent for index compatibility)
     */
    hnswParams?: {
      M: number
      efConstruction: number
      maxElements?: number
    }
  }
  
  /**
   * Active instances in the distributed system
   */
  instances: {
    [instanceId: string]: InstanceInfo
  }
  
  /**
   * Partition assignments (for manual strategy)
   */
  partitionAssignments?: {
    [instanceId: string]: string[]
  }
}

export interface InstanceInfo {
  /**
   * Instance role
   */
  role: InstanceRole
  
  /**
   * Instance status
   */
  status: 'active' | 'inactive' | 'unhealthy'
  
  /**
   * Last heartbeat timestamp
   */
  lastHeartbeat: string
  
  /**
   * Optional endpoint for health checks
   */
  endpoint?: string
  
  /**
   * Instance metrics
   */
  metrics?: {
    vectorCount?: number
    cacheHitRate?: number
    memoryUsage?: number
    cpuUsage?: number
  }
  
  /**
   * Assigned partitions (for manual assignment)
   */
  assignedPartitions?: string[]
  
  /**
   * Preferred partitions (for affinity)
   */
  preferredPartitions?: number[]
}

export interface DomainMetadata {
  /**
   * Domain identifier for logical data separation
   */
  domain?: string
  
  /**
   * Additional domain-specific metadata
   */
  domainMetadata?: Record<string, any>
}

export interface CacheStrategy {
  /**
   * Percentage of memory allocated to hot cache (0-1)
   */
  hotCacheRatio: number
  
  /**
   * Enable aggressive prefetching
   */
  prefetchAggressive?: boolean
  
  /**
   * Cache time-to-live in milliseconds
   */
  ttl?: number
  
  /**
   * Enable compression to trade CPU for memory
   */
  compressionEnabled?: boolean
  
  /**
   * Write buffer size for batching
   */
  writeBufferSize?: number
  
  /**
   * Enable write batching
   */
  batchWrites?: boolean
  
  /**
   * Adaptive caching based on workload
   */
  adaptive?: boolean
}

export interface OperationalMode {
  /**
   * Whether this mode can read
   */
  canRead: boolean
  
  /**
   * Whether this mode can write
   */
  canWrite: boolean
  
  /**
   * Whether this mode can delete
   */
  canDelete: boolean
  
  /**
   * Cache strategy for this mode
   */
  cacheStrategy: CacheStrategy
}