feagi_api/endpoints/

system.rs

// Copyright 2025 Neuraville Inc.
// Licensed under the Apache License, Version 2.0

//! System API Endpoints - Exact port from Python `/v1/system/*`
//!
//! Reference: feagi-py/feagi/api/v1/system.py

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

use crate::amalgamation;
use crate::common::ApiState;
use crate::common::{ApiError, ApiResult, Json, State};

// ============================================================================
// REQUEST/RESPONSE MODELS (matching Python schemas exactly)
// ============================================================================

#[allow(non_snake_case)] // Field name matches Python API for compatibility
#[derive(Debug, Serialize, Deserialize, utoipa::ToSchema)]
pub struct FatigueInfo {
    /// Fatigue index (0-100) - maximum utilization across all fatigue criteria
    pub fatigue_index: Option<u8>,
    /// Whether fatigue is currently active (triggers fatigue neuron injection)
    pub fatigue_active: Option<bool>,
    /// Regular neuron utilization percentage (0-100)
    pub regular_neuron_util: Option<u8>,
    /// Memory neuron utilization percentage (0-100)
    pub memory_neuron_util: Option<u8>,
    /// Synapse utilization percentage (0-100)
    pub synapse_util: Option<u8>,
}

#[allow(non_snake_case)] // Field name matches Python API for compatibility
#[derive(Debug, Serialize, Deserialize, utoipa::ToSchema)]
pub struct HealthCheckResponse {
    pub burst_engine: bool,
    pub connected_agents: Option<i32>,
    pub influxdb_availability: bool,
    pub neuron_count_max: i64,
    pub synapse_count_max: i64,
    pub latest_changes_saved_externally: bool,
    pub genome_availability: bool,
    pub genome_validity: Option<bool>,
    pub brain_readiness: bool,
    /// True while a prioritized genome load/upload is in progress (StateManager genome state is Loading).
    pub genome_loading: bool,
    /// Genome lifecycle: missing, loading, loaded, saving, or error.
    pub genome_state: String,
    pub feagi_session: Option<i64>,
    pub fitness: Option<f64>,
    pub cortical_area_count: Option<i32>,
    pub neuron_count: Option<i64>,
    pub memory_neuron_count: Option<i64>,
    pub regular_neuron_count: Option<i64>,
    pub synapse_count: Option<i64>,
    pub estimated_brain_size_in_MB: Option<f64>,
    pub genome_num: Option<i32>,
    pub genome_timestamp: Option<i64>,
    pub simulation_timestep: Option<f64>,
    pub memory_area_stats: Option<HashMap<String, HashMap<String, serde_json::Value>>>,
    pub amalgamation_pending: Option<HashMap<String, serde_json::Value>>,
    /// Hash of brain regions (hierarchy, membership, and properties)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub brain_regions_hash: Option<u64>,
    /// Hash of cortical areas and properties (excluding mappings)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cortical_areas_hash: Option<u64>,
    /// Hash of brain geometry (area positions/dimensions and 2D coordinates)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub brain_geometry_hash: Option<u64>,
    /// Hash of morphology registry
    #[serde(skip_serializing_if = "Option::is_none")]
    pub morphologies_hash: Option<u64>,
    /// Hash of cortical mappings
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cortical_mappings_hash: Option<u64>,
    /// Hash of agent data (ids, capabilities, connection properties)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub agent_data_hash: Option<u64>,
    /// Root brain region ID (UUID string) for O(1) root lookup
    #[serde(skip_serializing_if = "Option::is_none")]
    pub brain_regions_root: Option<String>,
    /// Fatigue information (index, active state, and breakdown of contributing elements)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fatigue: Option<FatigueInfo>,
}

// ============================================================================
// ENDPOINTS
// ============================================================================

/// Get comprehensive system health including burst engine status, neuron/synapse counts, and genome availability.
#[utoipa::path(
    get,
    path = "/v1/system/health_check",
    responses(
        (status = 200, description = "System health retrieved successfully", body = HealthCheckResponse),
        (status = 500, description = "Internal server error")
    ),
    tag = "system"
)]
pub async fn get_health_check(
    State(state): State<ApiState>,
) -> ApiResult<Json<HealthCheckResponse>> {
    let analytics_service = state.analytics_service.as_ref();

    // Get system health from analytics service
    let health = analytics_service
        .get_system_health()
        .await
        .map_err(|e| ApiError::internal(format!("Failed to get system health: {}", e)))?;

    // Get runtime status if available (source of truth for current burst frequency).
    let runtime_status = state.runtime_service.get_status().await.ok();
    let burst_engine_active = runtime_status
        .as_ref()
        .map(|status| status.is_running)
        .unwrap_or(false);

    let _burst_count = state.runtime_service.get_burst_count().await.ok();

    // Get connected agents count from agent service
    let connected_agents = if let Some(agent_service) = state.agent_service.as_ref() {
        agent_service
            .list_agents()
            .await
            .ok()
            .map(|agents| agents.len() as i32)
    } else {
        None
    };

    // Get total synapse count from analytics service
    let synapse_count = analytics_service
        .get_total_synapse_count()
        .await
        .ok()
        .map(|count| count as i64);

    // Get regular and memory neuron counts
    let regular_neuron_count = analytics_service
        .get_regular_neuron_count()
        .await
        .ok()
        .map(|count| count as i64);

    let memory_neuron_count = analytics_service
        .get_memory_neuron_count()
        .await
        .ok()
        .map(|count| count as i64);

    // Get genome info for simulation_timestep, genome_num, and genome_timestamp
    let genome_info = state.genome_service.get_genome_info().await.ok();

    // Prefer runtime frequency-derived timestep to reflect the active simulation rate.
    let runtime_timestep = runtime_status.as_ref().map(|status| {
        if status.frequency_hz > 0.0 {
            1.0 / status.frequency_hz
        } else {
            0.0
        }
    });
    let simulation_timestep =
        runtime_timestep.or_else(|| genome_info.as_ref().map(|info| info.simulation_timestep));
    let genome_num = genome_info.as_ref().and_then(|info| info.genome_num);
    let genome_timestamp = genome_info.as_ref().and_then(|info| info.genome_timestamp);

    // Calculate estimated brain size in MB
    // Rough estimates: ~64 bytes per neuron + ~16 bytes per synapse + metadata
    #[allow(non_snake_case)] // Matching Python API field name for compatibility
    let estimated_brain_size_in_MB = {
        let neuron_bytes = health.neuron_count * 64;
        let synapse_bytes = synapse_count.unwrap_or(0) as usize * 16;
        let metadata_bytes = health.cortical_area_count * 512; // ~512 bytes per area
        let total_bytes = neuron_bytes + synapse_bytes + metadata_bytes;
        Some((total_bytes as f64) / (1024.0 * 1024.0))
    };

    // Get actual NPU capacity from SystemHealth (single source of truth from config)
    let neuron_count_max = health.neuron_capacity as i64;
    let synapse_count_max = health.synapse_capacity as i64;

    // Configuration values (should eventually come from config service)
    let influxdb_availability = false; // TODO: Get from monitoring service
    let latest_changes_saved_externally = false; // TODO: Get from state manager
    let genome_availability = health.cortical_area_count > 0;
    // Real genome validity comes from the chain report, written by the
    // loader into core state. Falls back to `None` until a genome has
    // been loaded in this process. See `SystemHealth::genome_validity`.
    let genome_validity = health.genome_validity;

    // Get FEAGI session timestamp (unique identifier for this FEAGI instance)
    let feagi_session = Some(state.feagi_session_timestamp);

    // Fields requiring future service implementations
    let fitness = None; // TODO: Get from evolution service

    // Get memory area stats from plasticity service cache (event-driven updates).
    //
    // IMPORTANT: BV expects both:
    // - per-area stats keyed by cortical_id (base64), and
    // - a global `memory_neuron_count` that matches the sum of per-area `neuron_count`.
    let (memory_area_stats, memory_neuron_count_from_cache) = state
        .memory_stats_cache
        .as_ref()
        .map(|cache| {
            let snapshot = feagi_npu_plasticity::memory_stats_cache::get_stats_snapshot(cache);
            let total = snapshot
                .values()
                .map(|s| s.neuron_count as i64)
                .sum::<i64>();
            let per_area = snapshot
                .into_iter()
                .map(|(name, stats)| {
                    let mut inner_map = HashMap::new();
                    inner_map.insert(
                        "neuron_count".to_string(),
                        serde_json::json!(stats.neuron_count),
                    );
                    inner_map.insert(
                        "created_total".to_string(),
                        serde_json::json!(stats.created_total),
                    );
                    inner_map.insert(
                        "deleted_total".to_string(),
                        serde_json::json!(stats.deleted_total),
                    );
                    inner_map.insert(
                        "last_updated".to_string(),
                        serde_json::json!(stats.last_updated),
                    );
                    (name, inner_map)
                })
                .collect::<HashMap<String, HashMap<String, serde_json::Value>>>();
            (Some(per_area), Some(total))
        })
        .unwrap_or((None, None));

    // Prefer the plasticity cache-derived total to avoid discrepancies.
    let memory_neuron_count = memory_neuron_count_from_cache.or(memory_neuron_count);

    // BV expects `amalgamation_pending` to be a dict with:
    // - amalgamation_id
    // - genome_title
    // - circuit_size
    let amalgamation_pending = state.amalgamation_state.read().pending.as_ref().map(|p| {
        let v = amalgamation::pending_summary_to_health_json(&p.summary);
        v.as_object()
            .cloned()
            .unwrap_or_default()
            .into_iter()
            .collect::<HashMap<String, serde_json::Value>>()
    });

    // Get root region ID from ConnectomeManager (only available when services feature is enabled)
    #[cfg(feature = "services")]
    let brain_regions_root = feagi_brain_development::ConnectomeManager::instance()
        .read()
        .get_root_region_id();
    #[cfg(not(feature = "services"))]
    let brain_regions_root = None; // WASM: Use connectome service instead

    // Get fatigue information from state manager
    // Note: feagi-state-manager is included in the "services" feature
    #[cfg(feature = "services")]
    let fatigue = {
        use feagi_state_manager::StateManager;
        // Initialize singleton on first access (Lazy will handle this)
        match StateManager::instance().try_read() {
            Some(state_manager) => {
                let core_state = state_manager.get_core_state();
                Some(FatigueInfo {
                    fatigue_index: Some(core_state.get_fatigue_index()),
                    fatigue_active: Some(core_state.is_fatigue_active()),
                    regular_neuron_util: Some(core_state.get_regular_neuron_util()),
                    memory_neuron_util: Some(core_state.get_memory_neuron_util()),
                    synapse_util: Some(core_state.get_synapse_util()),
                })
            }
            None => {
                // State manager is locked, return None (shouldn't happen in normal operation)
                tracing::warn!(target: "feagi-api", "StateManager is locked, cannot read fatigue data");
                None
            }
        }
    };
    #[cfg(not(feature = "services"))]
    let fatigue = {
        tracing::debug!(target: "feagi-api", "Services feature not enabled, fatigue data unavailable");
        None
    };

    let (
        brain_regions_hash,
        cortical_areas_hash,
        brain_geometry_hash,
        morphologies_hash,
        cortical_mappings_hash,
        agent_data_hash,
        genome_loading,
        genome_state,
    ) = {
        use feagi_state_manager::GenomeState;
        let state_manager = feagi_state_manager::StateManager::instance();
        let state_manager = state_manager.read();
        let gs = state_manager.get_genome_state();
        let genome_state = match gs {
            GenomeState::Missing => "missing",
            GenomeState::Loading => "loading",
            GenomeState::Loaded => "loaded",
            GenomeState::Saving => "saving",
            GenomeState::Error => "error",
        }
        .to_string();
        let genome_loading = gs == GenomeState::Loading;
        (
            Some(state_manager.get_brain_regions_hash()),
            Some(state_manager.get_cortical_areas_hash()),
            Some(state_manager.get_brain_geometry_hash()),
            Some(state_manager.get_morphologies_hash()),
            Some(state_manager.get_cortical_mappings_hash()),
            Some(state_manager.get_agent_data_hash()),
            genome_loading,
            genome_state,
        )
    };

    Ok(Json(HealthCheckResponse {
        burst_engine: burst_engine_active,
        connected_agents,
        influxdb_availability,
        neuron_count_max,
        synapse_count_max,
        latest_changes_saved_externally,
        genome_availability,
        genome_validity,
        brain_readiness: health.brain_readiness,
        genome_loading,
        genome_state,
        feagi_session,
        fitness,
        cortical_area_count: Some(health.cortical_area_count as i32),
        neuron_count: Some(health.neuron_count as i64),
        memory_neuron_count,
        regular_neuron_count,
        synapse_count,
        estimated_brain_size_in_MB,
        genome_num,
        genome_timestamp,
        simulation_timestep,
        memory_area_stats,
        amalgamation_pending,
        brain_regions_hash,
        cortical_areas_hash,
        brain_geometry_hash,
        morphologies_hash,
        cortical_mappings_hash,
        agent_data_hash,
        brain_regions_root, // NEW: Root region ID for O(1) lookup
        fatigue,
    }))
}

/// Get the visualization skip rate (how many frames to skip during visualization).
#[utoipa::path(
    get,
    path = "/v1/system/cortical_area_visualization_skip_rate",
    responses(
        (status = 200, description = "Skip rate retrieved successfully", body = i32),
        (status = 500, description = "Internal server error")
    ),
    tag = "system"
)]
pub async fn get_cortical_area_visualization_skip_rate(
    State(_state): State<ApiState>,
) -> ApiResult<Json<i32>> {
    // TODO: Get from visualization config service
    // For now return default value
    Ok(Json(1))
}

/// Set the visualization skip rate to reduce visualization frequency and improve performance.
#[utoipa::path(
    put,
    path = "/v1/system/cortical_area_visualization_skip_rate",
    request_body = i32,
    responses(
        (status = 200, description = "Skip rate updated successfully"),
        (status = 500, description = "Internal server error")
    ),
    tag = "system"
)]
pub async fn set_cortical_area_visualization_skip_rate(
    State(_state): State<ApiState>,
    Json(skip_rate): Json<i32>,
) -> ApiResult<Json<serde_json::Value>> {
    // TODO: Set in visualization config service
    Ok(Json(serde_json::json!({
        "message": format!("Skip rate set to {}", skip_rate)
    })))
}

/// Get the threshold below which cortical areas are suppressed from visualization.
#[utoipa::path(
    get,
    path = "/v1/system/cortical_area_visualization_suppression_threshold",
    responses(
        (status = 200, description = "Threshold retrieved successfully", body = i32),
        (status = 500, description = "Internal server error")
    ),
    tag = "system"
)]
pub async fn get_cortical_area_visualization_suppression_threshold(
    State(_state): State<ApiState>,
) -> ApiResult<Json<i32>> {
    // TODO: Get from visualization config service
    // For now return default value
    Ok(Json(0))
}

/// Set the threshold for suppressing low-activity cortical areas from visualization.
#[utoipa::path(
    put,
    path = "/v1/system/cortical_area_visualization_suppression_threshold",
    request_body = i32,
    responses(
        (status = 200, description = "Threshold updated successfully"),
        (status = 500, description = "Internal server error")
    ),
    tag = "system"
)]
pub async fn set_cortical_area_visualization_suppression_threshold(
    State(_state): State<ApiState>,
    Json(threshold): Json<i32>,
) -> ApiResult<Json<serde_json::Value>> {
    // TODO: Set in visualization config service
    Ok(Json(serde_json::json!({
        "message": format!("Suppression threshold set to {}", threshold)
    })))
}

// ============================================================================
// SYSTEM VERSION & INFO ENDPOINTS
// ============================================================================

/// Get the current FEAGI version string.
#[utoipa::path(
    get,
    path = "/v1/system/version",
    tag = "system",
    responses(
        (status = 200, description = "Version string", body = String)
    )
)]
pub async fn get_version(State(_state): State<ApiState>) -> ApiResult<Json<String>> {
    Ok(Json(env!("CARGO_PKG_VERSION").to_string()))
}

/// Get detailed version information for all FEAGI crates and components.
#[utoipa::path(
    get,
    path = "/v1/system/versions",
    tag = "system",
    responses(
        (status = 200, description = "Version information", body = HashMap<String, String>)
    )
)]
pub async fn get_versions(
    State(state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, String>>> {
    // Use system service to get version information
    // The application (feagi-rust) provides this at startup with all crates it was compiled with
    match state.system_service.get_version().await {
        Ok(version_info) => {
            let mut versions = version_info.crates.clone();

            // Add build metadata
            versions.insert("rust".to_string(), version_info.rust_version);
            versions.insert("build_timestamp".to_string(), version_info.build_timestamp);

            Ok(Json(versions))
        }
        Err(e) => {
            // Fallback to minimal version info
            tracing::warn!(
                "Failed to get version from system service: {}, using fallback",
                e
            );
            let mut versions = HashMap::new();
            versions.insert(
                "error".to_string(),
                "system service unavailable".to_string(),
            );
            Ok(Json(versions))
        }
    }
}

/// Get system configuration including API settings, neuron capacity, and synapse limits.
#[utoipa::path(
    get,
    path = "/v1/system/configuration",
    tag = "system",
    responses(
        (status = 200, description = "System configuration", body = HashMap<String, serde_json::Value>)
    )
)]
pub async fn get_configuration(
    State(state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, serde_json::Value>>> {
    // Get actual NPU capacity from analytics service
    let health = state
        .analytics_service
        .get_system_health()
        .await
        .map_err(|e| ApiError::internal(format!("Failed to get system health: {}", e)))?;

    let mut config = HashMap::new();
    config.insert("api_host".to_string(), serde_json::json!("0.0.0.0"));
    config.insert("api_port".to_string(), serde_json::json!(8000));
    // Use actual NPU capacity from system health (NOT hardcoded values)
    config.insert(
        "max_neurons".to_string(),
        serde_json::json!(health.neuron_capacity),
    );
    config.insert(
        "max_synapses".to_string(),
        serde_json::json!(health.synapse_capacity),
    );

    Ok(Json(config))
}

/// Get user preferences including advanced mode, UI magnification, and auto-creation settings.
#[utoipa::path(
    get,
    path = "/v1/system/user_preferences",
    tag = "system",
    responses(
        (status = 200, description = "User preferences", body = HashMap<String, serde_json::Value>)
    )
)]
pub async fn get_user_preferences(
    State(_state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, serde_json::Value>>> {
    let mut prefs = HashMap::new();
    prefs.insert("adv_mode".to_string(), serde_json::json!(false));
    prefs.insert("ui_magnification".to_string(), serde_json::json!(1.0));
    prefs.insert(
        "auto_pns_area_creation".to_string(),
        serde_json::json!(true),
    );

    Ok(Json(prefs))
}

/// Update user preferences for UI customization and behavior settings.
#[utoipa::path(
    put,
    path = "/v1/system/user_preferences",
    tag = "system",
    responses(
        (status = 200, description = "Preferences updated", body = HashMap<String, String>)
    )
)]
pub async fn put_user_preferences(
    State(_state): State<ApiState>,
    Json(_prefs): Json<HashMap<String, serde_json::Value>>,
) -> ApiResult<Json<HashMap<String, String>>> {
    Ok(Json(HashMap::from([(
        "message".to_string(),
        "User preferences updated successfully".to_string(),
    )])))
}

/// Get list of available cortical area types (Sensory, Motor, Custom, Memory, Core).
#[utoipa::path(
    get,
    path = "/v1/system/cortical_area_types",
    tag = "system",
    responses(
        (status = 200, description = "Cortical area types", body = Vec<String>)
    )
)]
pub async fn get_cortical_area_types_list(
    State(_state): State<ApiState>,
) -> ApiResult<Json<Vec<String>>> {
    Ok(Json(vec![
        "Sensory".to_string(),
        "Motor".to_string(),
        "Custom".to_string(),
        "Memory".to_string(),
        "Core".to_string(),
    ]))
}

/// Enable the Fire Queue (FQ) sampler for visualization data streaming.
#[utoipa::path(
    post,
    path = "/v1/system/enable_visualization_fq_sampler",
    tag = "system",
    responses(
        (status = 200, description = "FQ sampler enabled", body = HashMap<String, String>)
    )
)]
pub async fn post_enable_visualization_fq_sampler(
    State(state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, String>>> {
    let runtime_service = state.runtime_service.as_ref();

    runtime_service
        .set_fcl_sampler_config(None, Some(1))
        .await
        .map_err(|e| ApiError::internal(format!("Failed to enable FQ sampler: {}", e)))?;

    Ok(Json(HashMap::from([(
        "message".to_string(),
        "Visualization FQ sampler enabled".to_string(),
    )])))
}

/// Disable the Fire Queue (FQ) sampler to stop visualization data streaming.
#[utoipa::path(
    post,
    path = "/v1/system/disable_visualization_fq_sampler",
    tag = "system",
    responses(
        (status = 200, description = "FQ sampler disabled", body = HashMap<String, String>)
    )
)]
pub async fn post_disable_visualization_fq_sampler(
    State(state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, String>>> {
    let runtime_service = state.runtime_service.as_ref();

    runtime_service
        .set_fcl_sampler_config(None, Some(0))
        .await
        .map_err(|e| ApiError::internal(format!("Failed to disable FQ sampler: {}", e)))?;

    Ok(Json(HashMap::from([(
        "message".to_string(),
        "Visualization FQ sampler disabled".to_string(),
    )])))
}

/// Get Fire Candidate List (FCL) sampler status including frequency and consumer state.
#[utoipa::path(
    get,
    path = "/v1/system/fcl_status",
    tag = "system",
    responses(
        (status = 200, description = "FCL status", body = HashMap<String, serde_json::Value>)
    )
)]
pub async fn get_fcl_status_system(
    State(state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, serde_json::Value>>> {
    let runtime_service = state.runtime_service.as_ref();

    let (frequency, consumer) = runtime_service
        .get_fcl_sampler_config()
        .await
        .map_err(|e| ApiError::internal(format!("Failed to get FCL status: {}", e)))?;

    let mut response = HashMap::new();
    response.insert("available".to_string(), serde_json::json!(true));
    response.insert("frequency".to_string(), serde_json::json!(frequency));
    response.insert("consumer".to_string(), serde_json::json!(consumer));
    response.insert("enabled".to_string(), serde_json::json!(consumer > 0));

    Ok(Json(response))
}

/// Reset the Fire Candidate List (FCL) to clear all pending fire candidates.
#[utoipa::path(
    post,
    path = "/v1/system/fcl_reset",
    tag = "system",
    responses(
        (status = 200, description = "FCL reset", body = HashMap<String, String>)
    )
)]
pub async fn post_fcl_reset_system(
    State(_state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, String>>> {
    tracing::info!(target: "feagi-api", "FCL reset requested");

    Ok(Json(HashMap::from([(
        "message".to_string(),
        "FCL reset successfully".to_string(),
    )])))
}

/// Get status of active system processes including burst engine and API server.
#[utoipa::path(
    get,
    path = "/v1/system/processes",
    tag = "system",
    responses(
        (status = 200, description = "Active processes", body = HashMap<String, serde_json::Value>)
    )
)]
pub async fn get_processes(
    State(state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, serde_json::Value>>> {
    let runtime_service = state.runtime_service.as_ref();

    let status = runtime_service
        .get_status()
        .await
        .map_err(|e| ApiError::internal(format!("Failed to get processes: {}", e)))?;

    let mut processes = HashMap::new();
    processes.insert(
        "burst_engine".to_string(),
        serde_json::json!({
            "active": status.is_running,
            "paused": status.is_paused
        }),
    );
    processes.insert(
        "api_server".to_string(),
        serde_json::json!({"active": true}),
    );

    Ok(Json(processes))
}

/// Get collection of unique log messages for debugging and monitoring.
#[utoipa::path(
    get,
    path = "/v1/system/unique_logs",
    tag = "system",
    responses(
        (status = 200, description = "Unique logs", body = HashMap<String, Vec<String>>)
    )
)]
pub async fn get_unique_logs(
    State(_state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, Vec<String>>>> {
    let mut response = HashMap::new();
    response.insert("logs".to_string(), Vec::new());

    Ok(Json(response))
}

// ============================================================================
// LOG TAIL (in-process tracing ring buffer)
// ============================================================================

/// Single log record returned from the ring buffer.
#[derive(Debug, Clone, Serialize, utoipa::ToSchema)]
pub struct LogTailRecord {
    pub timestamp_ms: i64,
    pub level: String,
    pub target: String,
    #[serde(skip_serializing_if = "String::is_empty")]
    pub file: String,
    pub line: u32,
    pub message: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fields: Option<serde_json::Value>,
}

/// Response payload for `GET /v1/system/log_tail`.
#[derive(Debug, Clone, Serialize, utoipa::ToSchema)]
pub struct LogTailResponse {
    /// True when the in-process log ring buffer is enabled. False indicates the
    /// `FEAGI_LOG_RING_BUFFER_CAPACITY` environment variable is set to 0 or the
    /// initialiser has not yet run.
    pub enabled: bool,
    /// Configured ring buffer capacity (records).
    pub capacity: usize,
    /// Records that matched the supplied filters, oldest first.
    pub records: Vec<LogTailRecord>,
    /// Number of records returned (matches `records.len()`).
    pub returned: usize,
}

/// Get a tail of recent log messages from FEAGI's in-process tracing ring buffer.
///
/// Filters (all optional, AND'd together):
/// * `since_ts_ms` - only records with `timestamp_ms >= since_ts_ms`
/// * `level`       - minimum severity (`TRACE` < `DEBUG` < `INFO` < `WARN` < `ERROR`)
/// * `target_prefix` - only records whose tracing target starts with this prefix
/// * `limit`       - cap on returned record count (most recent records win)
///
/// The buffer is bounded; old records are dropped when capacity is exceeded.
/// Capacity is controlled by `FEAGI_LOG_RING_BUFFER_CAPACITY` (default 2000,
/// set to 0 to disable).
#[utoipa::path(
    get,
    path = "/v1/system/log_tail",
    tag = "system",
    params(
        ("since_ts_ms" = Option<i64>, Query, description = "Only return records emitted at or after this Unix timestamp (ms)"),
        ("level" = Option<String>, Query, description = "Minimum severity (TRACE/DEBUG/INFO/WARN/ERROR)"),
        ("target_prefix" = Option<String>, Query, description = "Restrict to tracing targets starting with this prefix"),
        ("limit" = Option<usize>, Query, description = "Maximum number of records to return")
    ),
    responses(
        (status = 200, description = "Recent log records", body = LogTailResponse)
    )
)]
pub async fn get_log_tail(
    State(_state): State<ApiState>,
    axum::extract::Query(query): axum::extract::Query<HashMap<String, String>>,
) -> ApiResult<Json<LogTailResponse>> {
    let since_ts_ms = query.get("since_ts_ms").and_then(|v| v.parse::<i64>().ok());
    let level = query.get("level").map(|v| v.as_str());
    let target_prefix = query.get("target_prefix").map(|v| v.as_str());
    let limit = query.get("limit").and_then(|v| v.parse::<usize>().ok());

    let Some(ring) = feagi_observability::global_ring() else {
        return Ok(Json(LogTailResponse {
            enabled: false,
            capacity: 0,
            records: Vec::new(),
            returned: 0,
        }));
    };

    let snap = ring.snapshot(since_ts_ms, level, target_prefix, limit);
    let records: Vec<LogTailRecord> = snap
        .into_iter()
        .map(|r| LogTailRecord {
            timestamp_ms: r.timestamp_ms,
            level: r.level,
            target: r.target,
            file: r.file,
            line: r.line,
            message: r.message,
            fields: r.fields,
        })
        .collect();
    let returned = records.len();

    Ok(Json(LogTailResponse {
        enabled: true,
        capacity: ring.capacity(),
        records,
        returned,
    }))
}

/// Configure logging settings including log level and output destinations.
#[utoipa::path(
    post,
    path = "/v1/system/logs",
    tag = "system",
    responses(
        (status = 200, description = "Log config updated", body = HashMap<String, String>)
    )
)]
pub async fn post_logs(
    State(_state): State<ApiState>,
    Json(_config): Json<HashMap<String, serde_json::Value>>,
) -> ApiResult<Json<HashMap<String, String>>> {
    Ok(Json(HashMap::from([(
        "message".to_string(),
        "Log configuration updated".to_string(),
    )])))
}

/// Get list of all beacon subscribers currently monitoring system events.
#[utoipa::path(
    get,
    path = "/v1/system/beacon/subscribers",
    tag = "system",
    responses(
        (status = 200, description = "Beacon subscribers", body = Vec<String>)
    )
)]
pub async fn get_beacon_subscribers(
    State(_state): State<ApiState>,
) -> ApiResult<Json<Vec<String>>> {
    Ok(Json(Vec::new()))
}

/// Subscribe to system beacon for event notifications and status updates.
#[utoipa::path(
    post,
    path = "/v1/system/beacon/subscribe",
    tag = "system",
    responses(
        (status = 200, description = "Subscribed", body = HashMap<String, String>)
    )
)]
pub async fn post_beacon_subscribe(
    State(_state): State<ApiState>,
    Json(_request): Json<HashMap<String, String>>,
) -> ApiResult<Json<HashMap<String, String>>> {
    Ok(Json(HashMap::from([(
        "message".to_string(),
        "Subscribed to beacon".to_string(),
    )])))
}

/// Unsubscribe from system beacon to stop receiving event notifications.
#[utoipa::path(
    delete,
    path = "/v1/system/beacon/unsubscribe",
    tag = "system",
    responses(
        (status = 200, description = "Unsubscribed", body = HashMap<String, String>)
    )
)]
pub async fn delete_beacon_unsubscribe(
    State(_state): State<ApiState>,
    Json(_request): Json<HashMap<String, String>>,
) -> ApiResult<Json<HashMap<String, String>>> {
    Ok(Json(HashMap::from([(
        "message".to_string(),
        "Unsubscribed from beacon".to_string(),
    )])))
}

/// Get global activity visualization configuration including enabled state and frequency.
#[utoipa::path(
    get,
    path = "/v1/system/global_activity_visualization",
    tag = "system",
    responses(
        (status = 200, description = "Global activity viz status", body = HashMap<String, serde_json::Value>)
    )
)]
pub async fn get_global_activity_visualization(
    State(_state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, serde_json::Value>>> {
    let mut response = HashMap::new();
    response.insert("enabled".to_string(), serde_json::json!(false));
    response.insert("frequency_hz".to_string(), serde_json::json!(30.0));

    Ok(Json(response))
}

/// Configure global activity visualization settings and frequency.
#[utoipa::path(
    put,
    path = "/v1/system/global_activity_visualization",
    tag = "system",
    responses(
        (status = 200, description = "Configured", body = HashMap<String, String>)
    )
)]
pub async fn put_global_activity_visualization(
    State(_state): State<ApiState>,
    Json(_config): Json<HashMap<String, serde_json::Value>>,
) -> ApiResult<Json<HashMap<String, String>>> {
    Ok(Json(HashMap::from([(
        "message".to_string(),
        "Global activity visualization configured".to_string(),
    )])))
}

/// Set the file system path for the circuit library storage location.
#[utoipa::path(
    post,
    path = "/v1/system/circuit_library_path",
    tag = "system",
    responses(
        (status = 200, description = "Path set", body = HashMap<String, String>)
    )
)]
pub async fn post_circuit_library_path(
    State(_state): State<ApiState>,
    Json(_request): Json<HashMap<String, String>>,
) -> ApiResult<Json<HashMap<String, String>>> {
    Ok(Json(HashMap::from([(
        "message".to_string(),
        "Circuit library path updated".to_string(),
    )])))
}

/// Test connectivity to InfluxDB database for time-series data storage.
#[utoipa::path(
    get,
    path = "/v1/system/db/influxdb/test",
    tag = "system",
    responses(
        (status = 200, description = "Test result", body = HashMap<String, bool>)
    )
)]
pub async fn get_influxdb_test(
    State(_state): State<ApiState>,
) -> ApiResult<Json<HashMap<String, bool>>> {
    let mut response = HashMap::new();
    response.insert("connected".to_string(), false);
    response.insert("available".to_string(), false);

    Ok(Json(response))
}

/// Register a new system component or module with FEAGI.
#[utoipa::path(
    post,
    path = "/v1/system/register",
    tag = "system",
    responses(
        (status = 200, description = "Registered", body = HashMap<String, String>)
    )
)]
pub async fn post_register_system(
    State(_state): State<ApiState>,
    Json(_request): Json<HashMap<String, serde_json::Value>>,
) -> ApiResult<Json<HashMap<String, String>>> {
    Ok(Json(HashMap::from([(
        "message".to_string(),
        "System component registered".to_string(),
    )])))
}