Configuration Management Technical Specification

use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;
use tokio::sync::RwLock;
use anyhow::{Result, Context};
use serde::{Deserialize, Serialize};
use async_trait::async_trait;
 
/// Core trait defining configuration schema behavior with schema manager integration
/// **Pattern Applied: Template Method Pattern**
pub trait ConfigurationSchema: Send + Sync + 'static {
    type ConfigType: for<'de> Deserialize<'de> + Serialize + Clone + Send + Sync + 'static;
    
    fn schema_name() -> &'static str;
    fn schema_version() -> &'static str;
    fn schema_file_patterns() -> Vec<&'static str> {
        vec![
            &format!("schemas/{}.schema.toml", Self::schema_name()),
            &format!("schemas/{}.schema.yaml", Self::schema_name()),
            &format!("schemas/{}.schema.json", Self::schema_name()),
        ]
    }
    fn default_configuration() -> Self::ConfigType;
    fn validation_rules() -> Vec<Box<dyn ValidationRule<Self::ConfigType>>>;
    fn schema_dependencies() -> Vec<&'static str> { vec![] }
    fn schema_inheritance() -> Option<&'static str> { None }
    
    /// Template method defining the standard loading workflow
    async fn load_configuration(discovery: &ConfigurationDiscovery) -> Result<Self::ConfigType> {
        // Step 1: Discover configuration files
        let discovered = discovery.discover_files(Self::schema_name()).await?;
        
        // Step 2: Parse discovered files
        let parsed = Self::parse_configurations(discovered).await?;
        
        // Step 3: Merge configurations
        let merged = Self::merge_configurations(parsed).await?;
        
        // Step 4: Validate final configuration
        Self::validate_configuration(&merged).await?;
        
        Ok(merged)
    }
    
    async fn parse_configurations(files: Vec<DiscoveredFile>) -> Result<Vec<Self::ConfigType>>;
    async fn merge_configurations(configs: Vec<Self::ConfigType>) -> Result<Self::ConfigType>;
    async fn validate_configuration(config: &Self::ConfigType) -> Result<()>;
}
 
/// Trait for configuration validation rules
/// **Pattern Applied: Strategy Pattern**
pub trait ValidationRule<T>: Send + Sync {
    fn name(&self) -> &'static str;
    fn validate(&self, config: &T) -> Result<ValidationResult>;
    fn severity(&self) -> ValidationSeverity;
}
 
/// Configuration change observer trait
/// **Pattern Applied: Observer Pattern**
#[async_trait]
pub trait ConfigurationObserver: Send + Sync {
    async fn on_configuration_changed(&self, change: ConfigurationChange) -> Result<()>;
    async fn on_validation_failed(&self, error: ValidationError) -> Result<()>;
    async fn on_reload_completed(&self, success: bool) -> Result<()>;
}

/// Configuration discovery engine implementing chain of responsibility
/// **Pattern Applied: Chain of Responsibility Pattern**
pub struct ConfigurationDiscovery {
    discovery_chain: Vec<Box<dyn DiscoveryHandler>>,
    format_factory: Arc<FormatParserFactory>,
    schema_manager: Arc<SchemaManager>,
}
 
/// Schema Manager handles schema discovery, loading, and caching
/// **Pattern Applied: Singleton Pattern + Factory Pattern**
pub struct SchemaManager {
    schema_cache: Arc<RwLock<HashMap<String, CachedSchema>>>,
    schema_discovery: SchemaDiscoveryEngine,
    schema_loader: SchemaLoader,
    schema_validator: SchemaValidator,
}
 
struct CachedSchema {
    metadata: SchemaMetadata,
    definition: SchemaDefinition,
    loaded_at: std::time::Instant,
    dependencies: Vec<String>,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SchemaMetadata {
    pub name: String,
    pub version: semver::Version,
    pub compatible_versions: Vec<semver::VersionReq>,
    pub description: String,
    pub author: String,
    pub created: chrono::DateTime<chrono::Utc>,
    pub last_modified: chrono::DateTime<chrono::Utc>,
    pub tags: Vec<String>,
    pub inheritance: Option<SchemaInheritance>,
    pub dependencies: SchemaDependencies,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SchemaInheritance {
    pub parent_schema: String,
    pub override_mode: OverrideMode,
    pub excluded_fields: Vec<String>,
    pub included_fields: Option<Vec<String>>,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SchemaDependencies {
    pub required_schemas: Vec<String>,
    pub optional_schemas: Vec<String>,
    pub version_constraints: HashMap<String, semver::VersionReq>,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum OverrideMode {
    DeepMerge,
    ShallowMerge,
    SelectiveMerge,
    Replace,
}
 
impl ConfigurationDiscovery {
    /// **Pattern Applied: Builder Pattern**
    pub fn builder() -> ConfigurationDiscoveryBuilder {
        ConfigurationDiscoveryBuilder::new()
    }
    
    pub async fn discover_files(&self, module_name: &str) -> Result<Vec<DiscoveredFile>> {
        // First, load the schema for this module
        let schema = self.schema_manager.load_schema(module_name).await?;
        
        // Use schema information to guide discovery
        for handler in &self.discovery_chain {
            if let Some(files) = handler.discover_with_schema(module_name, &schema).await? {
                return Ok(files);
            }
        }
        
        // Return default configuration if no files found
        Ok(vec![DiscoveredFile::default_with_schema(module_name, schema)])
    }
    
    pub async fn discover_schema_files(&self, module_name: &str) -> Result<Vec<DiscoveredSchemaFile>> {
        let mut discovered_schemas = Vec::new();
        
        // Search in all schema locations
        for handler in &self.discovery_chain {
            if let Some(schema_files) = handler.discover_schemas(module_name).await? {
                discovered_schemas.extend(schema_files);
            }
        }
        
        Ok(discovered_schemas)
    }
}
 
/// Builder for configuration discovery
/// **Pattern Applied: Builder Pattern**
pub struct ConfigurationDiscoveryBuilder {
    discovery_handlers: Vec<Box<dyn DiscoveryHandler>>,
    custom_search_paths: Vec<PathBuf>,
    format_precedence: Vec<ConfigurationFormat>,
    enable_environment_overrides: bool,
    enable_hot_reload: bool,
}
 
impl ConfigurationDiscoveryBuilder {
    pub fn new() -> Self {
        Self {
            discovery_handlers: Vec::new(),
            custom_search_paths: Vec::new(),
            format_precedence: vec![
                ConfigurationFormat::Toml,
                ConfigurationFormat::Yaml,
                ConfigurationFormat::Json,
            ],
            enable_environment_overrides: true,
            enable_hot_reload: false,
        }
    }
    
    pub fn build(self) -> Result<ConfigurationDiscovery> {
        let mut discovery_handlers: Vec<Box<dyn DiscoveryHandler>> = vec![
            Box::new(ProjectSchemaDiscoveryHandler::new()),
            Box::new(UserSchemaDiscoveryHandler::new()),
            Box::new(SystemSchemaDiscoveryHandler::new()),
            Box::new(EmbeddedSchemaDiscoveryHandler::new()),
        ];
        
        // Add custom handlers
        discovery_handlers.extend(self.discovery_handlers);
        
        let schema_manager = Arc::new(SchemaManager::new(
            SchemaDiscoveryEngine::new(self.custom_search_paths.clone()),
            SchemaLoader::new(),
            SchemaValidator::new(),
        ));
        
        Ok(ConfigurationDiscovery {
            discovery_chain: discovery_handlers,
            format_factory: Arc::new(FormatParserFactory::new()),
            schema_manager,
        })
    }
    
    pub fn add_search_path(mut self, path: PathBuf) -> Self {
        self.custom_search_paths.push(path);
        self
    }
    
    pub fn with_format_precedence(mut self, formats: Vec<ConfigurationFormat>) -> Self {
        self.format_precedence = formats;
        self
    }
    
    pub fn enable_hot_reload(mut self) -> Self {
        self.enable_hot_reload = true;
        self
    }
    
    pub fn with_schema_directory(mut self, schema_dir: PathBuf) -> Self {
        self.custom_search_paths.push(schema_dir.join("schemas"));
        self
    }
    
    pub fn with_embedded_schemas(mut self, embedded: bool) -> Self {
        if embedded {
            // Add embedded schema handler
        }
        self
    }
    
    pub fn disable_environment_overrides(mut self) -> Self {
        self.enable_environment_overrides = false;
        self
    }
}
 
// Schema discovery handlers implementing specific search strategies
/// **Pattern Applied: Chain of Responsibility Pattern**
 
/// Project-level schema discovery handler
pub struct ProjectSchemaDiscoveryHandler {
    search_paths: Vec<PathBuf>,
}
 
impl ProjectSchemaDiscoveryHandler {
    pub fn new() -> Self {
        Self {
            search_paths: vec![
                PathBuf::from("./schemas"),
                PathBuf::from("./config/schemas"),
                PathBuf::from("./.sindhan/schemas"),
            ],
        }
    }
}
 
#[async_trait]
impl SchemaDiscoveryHandler for ProjectSchemaDiscoveryHandler {
    async fn discover_schemas(&self, module_name: &str) -> Result<Option<Vec<DiscoveredSchemaFile>>> {
        for base_path in &self.search_paths {
            let schema_patterns = vec![
                format!("{}.schema.toml", module_name),
                format!("{}.schema.yaml", module_name),
                format!("{}.schema.yml", module_name),
                format!("{}.schema.json", module_name),
            ];
            
            for pattern in schema_patterns {
                let schema_path = base_path.join(&pattern);
                if schema_path.exists() {
                    return Ok(Some(vec![DiscoveredSchemaFile {
                        path: schema_path,
                        source: SchemaSource::Project,
                        format: SchemaFormat::from_extension(&pattern)?,
                        priority: 1,
                    }]));
                }
            }
        }
        Ok(None)
    }
    
    fn priority(&self) -> u8 { 1 }
    fn name(&self) -> &'static str { "Project Schema Discovery" }
}
 
/// User-level schema discovery handler
pub struct UserSchemaDiscoveryHandler {
    user_schema_dir: PathBuf,
}
 
impl UserSchemaDiscoveryHandler {
    pub fn new() -> Self {
        let home_dir = dirs::home_dir().unwrap_or_else(|| PathBuf::from("."));
        Self {
            user_schema_dir: home_dir.join(".sindhan").join("schemas"),
        }
    }
}
 
#[async_trait]
impl SchemaDiscoveryHandler for UserSchemaDiscoveryHandler {
    async fn discover_schemas(&self, module_name: &str) -> Result<Option<Vec<DiscoveredSchemaFile>>> {
        let schema_patterns = vec![
            format!("{}.schema.toml", module_name),
            format!("{}.schema.yaml", module_name),
            format!("{}.schema.yml", module_name),
            format!("{}.schema.json", module_name),
        ];
        
        for pattern in schema_patterns {
            let schema_path = self.user_schema_dir.join(&pattern);
            if schema_path.exists() {
                return Ok(Some(vec![DiscoveredSchemaFile {
                    path: schema_path,
                    source: SchemaSource::User,
                    format: SchemaFormat::from_extension(&pattern)?,
                    priority: 2,
                }]));
            }
        }
        Ok(None)
    }
    
    fn priority(&self) -> u8 { 2 }
    fn name(&self) -> &'static str { "User Schema Discovery" }
}
 
/// System-level schema discovery handler
pub struct SystemSchemaDiscoveryHandler {
    system_schema_dir: Option<PathBuf>,
}
 
impl SystemSchemaDiscoveryHandler {
    pub fn new() -> Self {
        let system_dir = std::env::var("SINDHAN_SCHEMA_DIR")
            .ok()
            .map(|dir| PathBuf::from(dir).join("schemas"));
        
        Self {
            system_schema_dir: system_dir,
        }
    }
}
 
#[async_trait]
impl SchemaDiscoveryHandler for SystemSchemaDiscoveryHandler {
    async fn discover_schemas(&self, module_name: &str) -> Result<Option<Vec<DiscoveredSchemaFile>>> {
        if let Some(ref schema_dir) = self.system_schema_dir {
            let schema_patterns = vec![
                format!("{}.schema.toml", module_name),
                format!("{}.schema.yaml", module_name),
                format!("{}.schema.yml", module_name),
                format!("{}.schema.json", module_name),
            ];
            
            for pattern in schema_patterns {
                let schema_path = schema_dir.join(&pattern);
                if schema_path.exists() {
                    return Ok(Some(vec![DiscoveredSchemaFile {
                        path: schema_path,
                        source: SchemaSource::System,
                        format: SchemaFormat::from_extension(&pattern)?,
                        priority: 3,
                    }]));
                }
            }
        }
        Ok(None)
    }
    
    fn priority(&self) -> u8 { 3 }
    fn name(&self) -> &'static str { "System Schema Discovery" }
}
 
/// Embedded schema discovery handler for built-in schemas
pub struct EmbeddedSchemaDiscoveryHandler {
    embedded_registry: Arc<EmbeddedSchemaRegistry>,
}
 
impl EmbeddedSchemaDiscoveryHandler {
    pub fn new() -> Self {
        Self {
            embedded_registry: Arc::new(EmbeddedSchemaRegistry::default()),
        }
    }
}
 
#[async_trait]
impl SchemaDiscoveryHandler for EmbeddedSchemaDiscoveryHandler {
    async fn discover_schemas(&self, module_name: &str) -> Result<Option<Vec<DiscoveredSchemaFile>>> {
        if let Some(embedded_schema) = self.embedded_registry.get_schema(module_name) {
            return Ok(Some(vec![DiscoveredSchemaFile {
                path: PathBuf::from(format!("embedded://{}.schema.toml", module_name)),
                source: SchemaSource::Embedded,
                format: SchemaFormat::Toml,
                priority: 4,
            }]));
        }
        Ok(None)
    }
    
    fn priority(&self) -> u8 { 4 }
    fn name(&self) -> &'static str { "Embedded Schema Discovery" }
}
 
/// Registry for embedded schemas compiled into the binary
pub struct EmbeddedSchemaRegistry {
    schemas: HashMap<String, &'static str>,
}
 
impl Default for EmbeddedSchemaRegistry {
    fn default() -> Self {
        let mut schemas = HashMap::new();
        
        // Built-in schemas for core modules
        schemas.insert("global".to_string(), include_str!("../schemas/global.schema.toml"));
        schemas.insert("agent-identity".to_string(), include_str!("../schemas/agent-identity.schema.toml"));
        schemas.insert("memory-systems".to_string(), include_str!("../schemas/memory-systems.schema.toml"));
        schemas.insert("context-management".to_string(), include_str!("../schemas/context-management.schema.toml"));
        schemas.insert("environment-awareness".to_string(), include_str!("../schemas/environment-awareness.schema.toml"));
        schemas.insert("observability".to_string(), include_str!("../schemas/observability.schema.toml"));
        schemas.insert("tools-mcp".to_string(), include_str!("../schemas/tools-mcp.schema.toml"));
        schemas.insert("agent-interface".to_string(), include_str!("../schemas/agent-interface.schema.toml"));
        
        Self { schemas }
    }
}
 
impl EmbeddedSchemaRegistry {
    pub fn get_schema(&self, module_name: &str) -> Option<&'static str> {
        self.schemas.get(module_name).copied()
    }
    
    pub fn register_schema(&mut self, module_name: String, schema_content: &'static str) {
        self.schemas.insert(module_name, schema_content);
    }
}
 
/// Schema Manager implementation
impl SchemaManager {
    pub fn new(
        discovery_engine: SchemaDiscoveryEngine,
        loader: SchemaLoader,
        validator: SchemaValidator,
    ) -> Self {
        Self {
            schema_cache: Arc::new(RwLock::new(HashMap::new())),
            schema_discovery: discovery_engine,
            schema_loader: loader,
            schema_validator: validator,
        }
    }
    
    /// Load a schema for the specified module
    pub async fn load_schema(&self, module_name: &str) -> Result<SchemaDefinition> {
        let cache_key = format!("{}:latest", module_name);
        
        // Check cache first
        {
            let cache = self.schema_cache.read().await;
            if let Some(cached) = cache.get(&cache_key) {
                // Check if cache is still valid (e.g., not expired)
                if cached.loaded_at.elapsed() < std::time::Duration::from_secs(300) {
                    return Ok(cached.definition.clone());
                }
            }
        }
        
        // Discover schema files
        let discovered_files = self.schema_discovery.discover_schema_files(module_name).await?;
        
        if discovered_files.is_empty() {
            return Err(anyhow::anyhow!("No schema found for module: {}", module_name));
        }
        
        // Load the highest priority schema
        let primary_schema_file = discovered_files
            .iter()
            .min_by_key(|file| file.priority)
            .unwrap();
        
        let schema_definition = self.schema_loader
            .load_schema_file(&primary_schema_file.path)
            .await?;
        
        // Validate schema
        self.schema_validator.validate_schema(&schema_definition).await?;
        
        // Process inheritance if specified
        let final_schema = if let Some(inheritance) = &schema_definition.metadata.inheritance {
            self.process_schema_inheritance(&schema_definition, inheritance).await?
        } else {
            schema_definition
        };
        
        // Cache the loaded schema
        {
            let mut cache = self.schema_cache.write().await;
            cache.insert(cache_key, CachedSchema {
                metadata: final_schema.metadata.clone(),
                definition: final_schema.clone(),
                loaded_at: std::time::Instant::now(),
                dependencies: final_schema.metadata.dependencies.required_schemas.clone(),
            });
        }
        
        Ok(final_schema)
    }
    
    /// Process schema inheritance by loading and merging parent schemas
    async fn process_schema_inheritance(
        &self,
        child_schema: &SchemaDefinition,
        inheritance: &SchemaInheritance,
    ) -> Result<SchemaDefinition> {
        // Load parent schema
        let parent_schema = self.load_schema(&inheritance.parent_schema).await?;
        
        // Merge schemas based on override mode
        match inheritance.override_mode {
            OverrideMode::DeepMerge => {
                self.deep_merge_schemas(&parent_schema, child_schema, inheritance).await
            },
            OverrideMode::ShallowMerge => {
                self.shallow_merge_schemas(&parent_schema, child_schema, inheritance).await
            },
            OverrideMode::SelectiveMerge => {
                self.selective_merge_schemas(&parent_schema, child_schema, inheritance).await
            },
            OverrideMode::Replace => {
                Ok(child_schema.clone())
            },
        }
    }
    
    async fn deep_merge_schemas(
        &self,
        parent: &SchemaDefinition,
        child: &SchemaDefinition,
        inheritance: &SchemaInheritance,
    ) -> Result<SchemaDefinition> {
        // Implementation for deep merging schemas
        // This would recursively merge all schema sections
        todo!("Implement deep schema merging")
    }
    
    async fn shallow_merge_schemas(
        &self,
        parent: &SchemaDefinition,
        child: &SchemaDefinition,
        inheritance: &SchemaInheritance,
    ) -> Result<SchemaDefinition> {
        // Implementation for shallow merging schemas
        // This would merge only top-level sections
        todo!("Implement shallow schema merging")
    }
    
    async fn selective_merge_schemas(
        &self,
        parent: &SchemaDefinition,
        child: &SchemaDefinition,
        inheritance: &SchemaInheritance,
    ) -> Result<SchemaDefinition> {
        // Implementation for selective merging schemas
        // This would merge only specified fields
        todo!("Implement selective schema merging")
    }
}
 
/// Schema-aware discovery handler trait
#[async_trait]
pub trait SchemaDiscoveryHandler: Send + Sync {
    async fn discover_schemas(&self, module_name: &str) -> Result<Option<Vec<DiscoveredSchemaFile>>>;
    fn priority(&self) -> u8;
    fn name(&self) -> &'static str;
}
 
/// Discovered schema file information
#[derive(Debug, Clone)]
pub struct DiscoveredSchemaFile {
    pub path: PathBuf,
    pub source: SchemaSource,
    pub format: SchemaFormat,
    pub priority: u8,
}
 
#[derive(Debug, Clone, PartialEq)]
pub enum SchemaSource {
    Project,
    User,
    System,
    Embedded,
    Remote,
}
 
#[derive(Debug, Clone, PartialEq)]
pub enum SchemaFormat {
    Toml,
    Yaml,
    Json,
}
 
impl SchemaFormat {
    fn from_extension(filename: &str) -> Result<Self> {
        match filename.split('.').last() {
            Some("toml") => Ok(SchemaFormat::Toml),
            Some("yaml") | Some("yml") => Ok(SchemaFormat::Yaml),
            Some("json") => Ok(SchemaFormat::Json),
            _ => Err(anyhow::anyhow!("Unsupported schema format")),
        }
    }
}
 
/// Complete schema definition structure
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SchemaDefinition {
    pub metadata: SchemaMetadata,
    pub config_structure: ConfigStructure,
    pub validation_rules: ValidationRules,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConfigStructure {
    pub fields: HashMap<String, FieldDefinition>,
    pub sections: HashMap<String, SectionDefinition>,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FieldDefinition {
    pub field_type: FieldType,
    pub required: bool,
    pub default_value: Option<serde_json::Value>,
    pub validation: Option<FieldValidation>,
    pub description: String,
    pub sensitive: bool,
    pub encrypted: bool,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum FieldType {
    String,
    Integer,
    Float,
    Boolean,
    Array(Box<FieldType>),
    Object(ConfigStructure),
    Enum(Vec<String>),
    Duration,
    Url,
    Path,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FieldValidation {
    pub pattern: Option<String>,
    pub min_length: Option<usize>,
    pub max_length: Option<usize>,
    pub min_value: Option<f64>,
    pub max_value: Option<f64>,
    pub custom_validator: Option<String>,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SectionDefinition {
    pub required: bool,
    pub fields: HashMap<String, FieldDefinition>,
    pub subsections: HashMap<String, SectionDefinition>,
    pub description: String,
}
 
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ValidationRules {
    pub field_rules: HashMap<String, Vec<ValidationRule>>,
    pub section_rules: HashMap<String, Vec<ValidationRule>>,
    pub global_rules: Vec<ValidationRule>,
}
 
/// Discovery handler trait for chain of responsibility
/// **Pattern Applied: Chain of Responsibility Pattern**
#[async_trait]
pub trait DiscoveryHandler: Send + Sync {
    async fn discover(&self, module_name: &str) -> Result<Option<Vec<DiscoveredFile>>>;
    async fn discover_with_schema(
        &self, 
        module_name: &str, 
        schema: &SchemaDefinition
    ) -> Result<Option<Vec<DiscoveredFile>>> {
        // Default implementation falls back to standard discovery
        self.discover(module_name).await
    }
    async fn discover_schemas(&self, module_name: &str) -> Result<Option<Vec<DiscoveredSchemaFile>>> {
        // Default implementation returns None for non-schema handlers
        Ok(None)
    }
    fn priority(&self) -> u8;
    fn name(&self) -> &'static str;
}
 
/// Current directory discovery handler
pub struct CurrentDirectoryHandler {
    format_precedence: Vec<ConfigurationFormat>,
}
 
#[async_trait]
impl DiscoveryHandler for CurrentDirectoryHandler {
    async fn discover(&self, module_name: &str) -> Result<Option<Vec<DiscoveredFile>>> {
        let current_dir = std::env::current_dir()
            .context("Failed to get current directory")?;
        
        for format in &self.format_precedence {
            let filename = format!("{}.{}", module_name, format.extension());
            let config_path = current_dir.join(&filename);
            
            if config_path.exists() {
                return Ok(Some(vec![DiscoveredFile {
                    path: config_path,
                    format: *format,
                    source: DiscoverySource::CurrentDirectory,
                    priority: self.priority(),
                }]));
            }
        }
        
        Ok(None)
    }
    
    fn priority(&self) -> u8 { 1 }
    fn name(&self) -> &'static str { "CurrentDirectory" }
}
 
/// Home directory discovery handler
pub struct HomeDirectoryHandler {
    format_precedence: Vec<ConfigurationFormat>,
}
 
#[async_trait]
impl DiscoveryHandler for HomeDirectoryHandler {
    async fn discover(&self, module_name: &str) -> Result<Option<Vec<DiscoveredFile>>> {
        let home_dir = dirs::home_dir()
            .context("Failed to get home directory")?;
        let sindhan_dir = home_dir.join(".sindhan");
        
        if !sindhan_dir.exists() {
            return Ok(None);
        }
        
        for format in &self.format_precedence {
            let filename = format!("{}.{}", module_name, format.extension());
            let config_path = sindhan_dir.join(&filename);
            
            if config_path.exists() {
                return Ok(Some(vec![DiscoveredFile {
                    path: config_path,
                    format: *format,
                    source: DiscoverySource::HomeDirectory,
                    priority: self.priority(),
                }]));
            }
        }
        
        Ok(None)
    }
    
    fn priority(&self) -> u8 { 2 }
    fn name(&self) -> &'static str { "HomeDirectory" }
}
 
/// Environment directory discovery handler
pub struct EnvironmentDirectoryHandler {
    format_precedence: Vec<ConfigurationFormat>,
}
 
#[async_trait]
impl DiscoveryHandler for EnvironmentDirectoryHandler {
    async fn discover(&self, module_name: &str) -> Result<Option<Vec<DiscoveredFile>>> {
        let env_dir = match std::env::var("SINDHAN_CONFIG_DIR") {
            Ok(dir) => PathBuf::from(dir),
            Err(_) => return Ok(None),
        };
        
        if !env_dir.exists() {
            return Ok(None);
        }
        
        for format in &self.format_precedence {
            let filename = format!("{}.{}", module_name, format.extension());
            let config_path = env_dir.join(&filename);
            
            if config_path.exists() {
                return Ok(Some(vec![DiscoveredFile {
                    path: config_path,
                    format: *format,
                    source: DiscoverySource::EnvironmentDirectory,
                    priority: self.priority(),
                }]));
            }
        }
        
        Ok(None)
    }
    
    fn priority(&self) -> u8 { 3 }
    fn name(&self) -> &'static str { "EnvironmentDirectory" }
}

/// Factory for creating format-specific parsers
/// **Pattern Applied: Factory Pattern**
pub struct FormatParserFactory {
    parsers: HashMap<ConfigurationFormat, Box<dyn ConfigurationParser>>,
}
 
impl FormatParserFactory {
    pub fn new() -> Self {
        let mut parsers: HashMap<ConfigurationFormat, Box<dyn ConfigurationParser>> = HashMap::new();
        
        parsers.insert(ConfigurationFormat::Toml, Box::new(TomlParser::new()));
        parsers.insert(ConfigurationFormat::Yaml, Box::new(YamlParser::new()));
        parsers.insert(ConfigurationFormat::Json, Box::new(JsonParser::new()));
        
        Self { parsers }
    }
    
    pub fn create_parser(&self, format: ConfigurationFormat) -> Result<&dyn ConfigurationParser> {
        self.parsers.get(&format)
            .map(|p| p.as_ref())
            .context(format!("No parser available for format: {:?}", format))
    }
    
    /// Register a custom parser
    pub fn register_parser(&mut self, format: ConfigurationFormat, parser: Box<dyn ConfigurationParser>) {
        self.parsers.insert(format, parser);
    }
}
 
/// Configuration parser trait
/// **Pattern Applied: Strategy Pattern**
#[async_trait]
pub trait ConfigurationParser: Send + Sync {
    async fn parse<T>(&self, content: &str) -> Result<T> 
    where 
        T: for<'de> Deserialize<'de>;
    
    fn format(&self) -> ConfigurationFormat;
    fn can_parse(&self, content: &str) -> bool;
}
 
/// TOML parser implementation
pub struct TomlParser;
 
impl TomlParser {
    pub fn new() -> Self {
        Self
    }
}
 
#[async_trait]
impl ConfigurationParser for TomlParser {
    async fn parse<T>(&self, content: &str) -> Result<T> 
    where 
        T: for<'de> Deserialize<'de>
    {
        toml::from_str(content)
            .context("Failed to parse TOML configuration")
    }
    
    fn format(&self) -> ConfigurationFormat {
        ConfigurationFormat::Toml
    }
    
    fn can_parse(&self, content: &str) -> bool {
        // Simple heuristic - check for TOML-specific syntax
        content.contains('[') && content.contains('=') && !content.contains('{')
    }
}
 
/// YAML parser implementation
pub struct YamlParser;
 
impl YamlParser {
    pub fn new() -> Self {
        Self
    }
}
 
#[async_trait]
impl ConfigurationParser for YamlParser {
    async fn parse<T>(&self, content: &str) -> Result<T> 
    where 
        T: for<'de> Deserialize<'de>
    {
        serde_yaml::from_str(content)
            .context("Failed to parse YAML configuration")
    }
    
    fn format(&self) -> ConfigurationFormat {
        ConfigurationFormat::Yaml
    }
    
    fn can_parse(&self, content: &str) -> bool {
        // Simple heuristic - check for YAML-specific syntax
        content.contains(':') && (content.contains("---") || content.contains("  "))
    }
}
 
/// JSON parser implementation
pub struct JsonParser;
 
impl JsonParser {
    pub fn new() -> Self {
        Self
    }
}
 
#[async_trait]
impl ConfigurationParser for JsonParser {
    async fn parse<T>(&self, content: &str) -> Result<T> 
    where 
        T: for<'de> Deserialize<'de>
    {
        serde_json::from_str(content)
            .context("Failed to parse JSON configuration")
    }
    
    fn format(&self) -> ConfigurationFormat {
        ConfigurationFormat::Json
    }
    
    fn can_parse(&self, content: &str) -> bool {
        // Simple heuristic - check for JSON-specific syntax
        content.trim().starts_with('{') && content.trim().ends_with('}')
    }
}

/// Configuration merge strategy trait
/// **Pattern Applied: Strategy Pattern**
pub trait MergeStrategy<T>: Send + Sync {
    fn merge(&self, base: T, override_config: T) -> Result<T>;
    fn strategy_name(&self) -> &'static str;
    fn supports_type(&self) -> bool;
}
 
/// Deep merge strategy for complex nested configurations
pub struct DeepMergeStrategy;
 
impl<T> MergeStrategy<T> for DeepMergeStrategy 
where 
    T: Serialize + for<'de> Deserialize<'de> + Clone
{
    fn merge(&self, base: T, override_config: T) -> Result<T> {
        // Convert to JSON values for deep merging
        let mut base_value: serde_json::Value = serde_json::to_value(base)?;
        let override_value: serde_json::Value = serde_json::to_value(override_config)?;
        
        self.deep_merge_values(&mut base_value, override_value);
        
        // Convert back to the target type
        serde_json::from_value(base_value)
            .context("Failed to deserialize merged configuration")
    }
    
    fn strategy_name(&self) -> &'static str {
        "DeepMerge"
    }
    
    fn supports_type(&self) -> bool {
        true
    }
}
 
impl DeepMergeStrategy {
    fn deep_merge_values(&self, base: &mut serde_json::Value, override_val: serde_json::Value) {
        match (base, override_val) {
            (serde_json::Value::Object(base_map), serde_json::Value::Object(override_map)) => {
                for (key, value) in override_map {
                    match base_map.entry(key) {
                        serde_json::map::Entry::Occupied(mut entry) => {
                            self.deep_merge_values(entry.get_mut(), value);
                        }
                        serde_json::map::Entry::Vacant(entry) => {
                            entry.insert(value);
                        }
                    }
                }
            }
            (base_val, override_val) => {
                *base_val = override_val;
            }
        }
    }
}
 
/// Shallow merge strategy for simple configurations
pub struct ShallowMergeStrategy;
 
impl<T> MergeStrategy<T> for ShallowMergeStrategy 
where 
    T: Serialize + for<'de> Deserialize<'de> + Clone
{
    fn merge(&self, _base: T, override_config: T) -> Result<T> {
        // Shallow merge simply returns the override configuration
        Ok(override_config)
    }
    
    fn strategy_name(&self) -> &'static str {
        "ShallowMerge"
    }
    
    fn supports_type(&self) -> bool {
        true
    }
}
 
/// Array append strategy for configurations with array values
pub struct ArrayAppendStrategy;
 
impl<T> MergeStrategy<T> for ArrayAppendStrategy 
where 
    T: Serialize + for<'de> Deserialize<'de> + Clone
{
    fn merge(&self, base: T, override_config: T) -> Result<T> {
        let mut base_value: serde_json::Value = serde_json::to_value(base)?;
        let override_value: serde_json::Value = serde_json::to_value(override_config)?;
        
        self.append_arrays(&mut base_value, override_value);
        
        serde_json::from_value(base_value)
            .context("Failed to deserialize merged configuration")
    }
    
    fn strategy_name(&self) -> &'static str {
        "ArrayAppend"
    }
    
    fn supports_type(&self) -> bool {
        true
    }
}
 
impl ArrayAppendStrategy {
    fn append_arrays(&self, base: &mut serde_json::Value, override_val: serde_json::Value) {
        match (base, override_val) {
            (serde_json::Value::Array(base_array), serde_json::Value::Array(override_array)) => {
                base_array.extend(override_array);
            }
            (serde_json::Value::Object(base_map), serde_json::Value::Object(override_map)) => {
                for (key, value) in override_map {
                    match base_map.entry(key) {
                        serde_json::map::Entry::Occupied(mut entry) => {
                            self.append_arrays(entry.get_mut(), value);
                        }
                        serde_json::map::Entry::Vacant(entry) => {
                            entry.insert(value);
                        }
                    }
                }
            }
            (base_val, override_val) => {
                *base_val = override_val;
            }
        }
    }
}

/// Main configuration manager implementing multiple patterns
/// **Pattern Applied: Singleton Pattern, Observer Pattern**
pub struct ConfigurationManager<T: ConfigurationSchema> {
    config: Arc<RwLock<T::ConfigType>>,
    discovery: ConfigurationDiscovery,
    observers: Arc<RwLock<Vec<Arc<dyn ConfigurationObserver>>>>,
    merge_strategy: Box<dyn MergeStrategy<T::ConfigType>>,
    validator: ValidationPipeline<T::ConfigType>,
    hot_reload_enabled: bool,
    _file_watcher: Option<tokio::task::JoinHandle<()>>,
}
 
impl<T: ConfigurationSchema> ConfigurationManager<T> {
    /// **Pattern Applied: Builder Pattern**
    pub fn builder() -> ConfigurationManagerBuilder<T> {
        ConfigurationManagerBuilder::new()
    }
    
    pub async fn load_configuration(&self) -> Result<()> {
        let config = T::load_configuration(&self.discovery).await?;
        
        // Validate the loaded configuration
        let validation_result = self.validator.validate(&config).await?;
        
        if !validation_result.is_valid() {
            return Err(anyhow::anyhow!("Configuration validation failed: {:?}", validation_result.errors()));
        }
        
        // Update the configuration
        let mut config_guard = self.config.write().await;
        *config_guard = config.clone();
        drop(config_guard);
        
        // Notify observers
        self.notify_observers(ConfigurationChange::Loaded { config }).await?;
        
        Ok(())
    }
    
    pub async fn get_configuration(&self) -> T::ConfigType {
        self.config.read().await.clone()
    }
    
    pub async fn update_configuration(&self, new_config: T::ConfigType) -> Result<()> {
        // Validate the new configuration
        let validation_result = self.validator.validate(&new_config).await?;
        
        if !validation_result.is_valid() {
            return Err(anyhow::anyhow!("Configuration validation failed: {:?}", validation_result.errors()));
        }
        
        let old_config = {
            let mut config_guard = self.config.write().await;
            let old = config_guard.clone();
            *config_guard = new_config.clone();
            old
        };
        
        // Notify observers
        self.notify_observers(ConfigurationChange::Updated { 
            old_config, 
            new_config 
        }).await?;
        
        Ok(())
    }
    
    /// **Pattern Applied: Observer Pattern**
    pub async fn add_observer(&self, observer: Arc<dyn ConfigurationObserver>) {
        let mut observers = self.observers.write().await;
        observers.push(observer);
    }
    
    async fn notify_observers(&self, change: ConfigurationChange) -> Result<()> {
        let observers = self.observers.read().await;
        
        for observer in observers.iter() {
            if let Err(e) = observer.on_configuration_changed(change.clone()).await {
                eprintln!("Observer notification failed: {}", e);
            }
        }
        
        Ok(())
    }
    
    async fn start_file_watcher(&self) -> Result<tokio::task::JoinHandle<()>> {
        // File watching implementation would go here
        // This is a placeholder for the actual file watching logic
        Ok(tokio::spawn(async {
            // File watching loop
        }))
    }
}
 
/// Builder for configuration manager
/// **Pattern Applied: Builder Pattern**
pub struct ConfigurationManagerBuilder<T: ConfigurationSchema> {
    discovery_builder: Option<ConfigurationDiscoveryBuilder>,
    merge_strategy: Option<Box<dyn MergeStrategy<T::ConfigType>>>,
    validation_rules: Vec<Box<dyn ValidationRule<T::ConfigType>>>,
    hot_reload_enabled: bool,
    initial_observers: Vec<Arc<dyn ConfigurationObserver>>,
}
 
impl<T: ConfigurationSchema> ConfigurationManagerBuilder<T> {
    pub fn new() -> Self {
        Self {
            discovery_builder: None,
            merge_strategy: None,
            validation_rules: T::validation_rules(),
            hot_reload_enabled: false,
            initial_observers: Vec::new(),
        }
    }
    
    pub fn with_discovery(mut self, discovery_builder: ConfigurationDiscoveryBuilder) -> Self {
        self.discovery_builder = Some(discovery_builder);
        self
    }
    
    pub fn with_merge_strategy(mut self, strategy: Box<dyn MergeStrategy<T::ConfigType>>) -> Self {
        self.merge_strategy = Some(strategy);
        self
    }
    
    pub fn add_validation_rule(mut self, rule: Box<dyn ValidationRule<T::ConfigType>>) -> Self {
        self.validation_rules.push(rule);
        self
    }
    
    pub fn enable_hot_reload(mut self) -> Self {
        self.hot_reload_enabled = true;
        self
    }
    
    pub fn add_observer(mut self, observer: Arc<dyn ConfigurationObserver>) -> Self {
        self.initial_observers.push(observer);
        self
    }
    
    pub async fn build(self) -> Result<ConfigurationManager<T>> {
        let discovery = self.discovery_builder
            .unwrap_or_else(|| ConfigurationDiscovery::builder())
            .build()?;
        
        let merge_strategy = self.merge_strategy
            .unwrap_or_else(|| Box::new(DeepMergeStrategy));
        
        let validator = ValidationPipeline::new(self.validation_rules);
        
        let config = Arc::new(RwLock::new(T::default_configuration()));
        let observers = Arc::new(RwLock::new(self.initial_observers));
        
        let mut manager = ConfigurationManager {
            config,
            discovery,
            observers,
            merge_strategy,
            validator,
            hot_reload_enabled: self.hot_reload_enabled,
            _file_watcher: None,
        };
        
        if manager.hot_reload_enabled {
            let file_watcher = manager.start_file_watcher().await?;
            manager._file_watcher = Some(file_watcher);
        }
        
        Ok(manager)
    }
}