swarm_engine_core/learn/

facade.rs

//! Learnable Swarm Facade - 学習機能付き Swarm の統合ファサード
//!
//! ## 設計思想
//!
//! **Orchestrator + LearningDaemon + Subscriber の統合を隠蔽し、
//! Ready な Swarm を提供する。**
//!
//! ```text
//! LearnableSwarmBuilder
//!   ├── OrchestratorBuilder 設定
//!   ├── LearningDaemon 起動
//!   ├── ActionEventSubscriber 連動
//!   └── LearningEventSubscriber 連動
//!         │
//!         ▼
//!   LearnableSwarm (Ready to run)
//!         │
//!    ┌────┴────┐
//!    ▼         ▼
//! EvalRunner  run command / GUI
//! ```
//!
//! ## 使用例
//!
//! ```ignore
//! use swarm_engine_core::learn::facade::{LearnableSwarm, LearnableSwarmBuilder};
//!
//! let swarm = LearnableSwarmBuilder::new(runtime.handle().clone())
//!     .scenario("troubleshooting")
//!     .with_learning(true)
//!     .with_offline_model(model)
//!     .build()?;
//!
//! let result = swarm.run_task(task)?;
//!
//! // Graceful shutdown (Subscriber / Daemon 終了待ち)
//! swarm.shutdown().await;
//! ```
//!
//! ## 責務分離
//!
//! | レイヤー | 責務 |
//! |----------|------|
//! | `LearnableSwarm` | 統合・ライフサイクル管理 |
//! | `Orchestrator` | Tick 駆動実行 |
//! | `LearningDaemon` | 継続的学習 |
//! | `Subscriber` | Event → Record 変換 |

use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;

use tokio::runtime::Handle;
use tokio::sync::mpsc;
use tokio::task::JoinHandle;

use crate::agent::{BatchInvoker, ManagerAgent, WorkerAgent};
use crate::error::SwarmError;
use crate::events::{ActionEventPublisher, LearningEventChannel, LifecycleHook, TraceSubscriber};
use crate::exploration::{DependencyGraph, DependencyGraphProvider, NodeRules, OperatorProvider};
use crate::extensions::Extensions;
use crate::orchestrator::{Orchestrator, OrchestratorBuilder, SwarmConfig, SwarmResult};
use crate::types::SwarmTask;

use super::daemon::{
    ActionEventSubscriber, DaemonConfig, DaemonError, EventSubscriberConfig, LearningDaemon,
    LearningEventSubscriber,
};
use super::profile_adapter::profile_to_offline_model;
use super::scenario_profile::ScenarioProfile;
use super::snapshot::LearningStore;
use super::trigger::{TrainTrigger, TriggerBuilder};
use super::LearningSnapshot;
use super::OfflineModel;

// ============================================================================
// Type Aliases
// ============================================================================

/// LearningDaemon の JoinHandle 型
type DaemonHandle = JoinHandle<Result<(), DaemonError>>;

/// Learning コンポーネントのセットアップ結果
#[derive(Default)]
struct LearningSetupResult {
    /// LearningDaemon の JoinHandle
    daemon_handle: Option<DaemonHandle>,
    /// Subscriber の JoinHandle 群
    subscriber_handles: Vec<JoinHandle<()>>,
    /// Shutdown 送信チャンネル
    shutdown_tx: Option<mpsc::Sender<()>>,
}

// ============================================================================
// LearnableSwarmConfig
// ============================================================================

/// 学習機能付き Swarm の設定
#[derive(Debug, Clone)]
pub struct LearnableSwarmConfig {
    /// シナリオ名（学習データのキー）
    pub scenario: String,
    /// 学習データディレクトリ
    pub data_dir: PathBuf,
    /// 学習機能の有効/無効
    pub learning_enabled: bool,
    /// Subscriber のバッチサイズ
    pub subscriber_batch_size: usize,
    /// Subscriber のフラッシュ間隔（ミリ秒）
    pub subscriber_flush_interval_ms: u64,
    /// Daemon のチェック間隔
    pub daemon_check_interval: Duration,
}

impl Default for LearnableSwarmConfig {
    fn default() -> Self {
        Self {
            scenario: String::new(),
            data_dir: default_learning_dir(),
            learning_enabled: false,
            subscriber_batch_size: 100,
            subscriber_flush_interval_ms: 100,
            daemon_check_interval: Duration::from_secs(10),
        }
    }
}

impl LearnableSwarmConfig {
    /// 新しい設定を作成
    pub fn new(scenario: impl Into<String>) -> Self {
        Self {
            scenario: scenario.into(),
            ..Default::default()
        }
    }

    /// 学習を有効化
    pub fn with_learning(mut self, enabled: bool) -> Self {
        self.learning_enabled = enabled;
        self
    }

    /// データディレクトリを設定
    pub fn data_dir(mut self, path: impl Into<PathBuf>) -> Self {
        self.data_dir = path.into();
        self
    }
}

fn default_learning_dir() -> PathBuf {
    dirs::data_dir()
        .unwrap_or_else(|| PathBuf::from("."))
        .join("swarm-engine")
        .join("learning")
}

// ============================================================================
// LearnableSwarmBuilder
// ============================================================================

/// 学習機能付き Swarm のビルダー
///
/// Orchestrator + LearningDaemon + Subscriber を統合構築する。
pub struct LearnableSwarmBuilder {
    /// Tokio runtime handle
    runtime: Handle,
    /// 設定
    config: LearnableSwarmConfig,
    /// Swarm 設定
    swarm_config: Option<SwarmConfig>,
    /// Workers
    workers: Vec<Box<dyn WorkerAgent>>,
    /// Managers
    managers: Vec<Box<dyn ManagerAgent>>,
    /// BatchInvoker
    batch_invoker: Option<Box<dyn BatchInvoker>>,
    /// DependencyGraphProvider
    dependency_provider: Option<Box<dyn DependencyGraphProvider>>,
    /// OperatorProvider
    operator_provider: Option<Box<dyn OperatorProvider<NodeRules>>>,
    /// Extensions
    extensions: Option<Extensions>,
    /// DependencyGraph
    dependency_graph: Option<DependencyGraph>,
    /// Offline model
    offline_model: Option<OfflineModel>,
    /// Prior snapshot
    prior_snapshot: Option<LearningSnapshot>,
    /// LearningStore
    learning_store: Option<LearningStore>,
    /// Train trigger
    train_trigger: Option<Arc<dyn TrainTrigger>>,
    /// LifecycleHook
    lifecycle_hook: Option<Box<dyn LifecycleHook>>,
    /// Exploration 有効化
    enable_exploration: bool,
    /// Deferred error from builder methods (checked in build())
    deferred_error: Option<SwarmError>,
    /// Trace subscriber (ActionEvent のトレース出力)
    trace_subscriber: Option<Arc<dyn TraceSubscriber>>,
}

impl LearnableSwarmBuilder {
    /// 新しいビルダーを作成
    pub fn new(runtime: Handle) -> Self {
        Self {
            runtime,
            config: LearnableSwarmConfig::default(),
            swarm_config: None,
            workers: Vec::new(),
            managers: Vec::new(),
            batch_invoker: None,
            dependency_provider: None,
            operator_provider: None,
            extensions: None,
            dependency_graph: None,
            offline_model: None,
            prior_snapshot: None,
            learning_store: None,
            train_trigger: None,
            lifecycle_hook: None,
            enable_exploration: false,
            deferred_error: None,
            trace_subscriber: None,
        }
    }

    /// シナリオ名を設定
    pub fn scenario(mut self, name: impl Into<String>) -> Self {
        self.config.scenario = name.into();
        self
    }

    /// 学習機能を有効化
    ///
    /// Note: `LearningEventChannel` の有効化は `build()` 時に行われる。
    pub fn with_learning(mut self, enabled: bool) -> Self {
        self.config.learning_enabled = enabled;
        self
    }

    /// データディレクトリを設定
    pub fn data_dir(mut self, path: impl Into<PathBuf>) -> Self {
        self.config.data_dir = path.into();
        self
    }

    /// Swarm 設定を追加
    pub fn swarm_config(mut self, config: SwarmConfig) -> Self {
        self.swarm_config = Some(config);
        self
    }

    /// Worker を追加
    pub fn add_worker(mut self, worker: Box<dyn WorkerAgent>) -> Self {
        self.workers.push(worker);
        self
    }

    /// 複数の Workers を追加
    pub fn workers(mut self, workers: Vec<Box<dyn WorkerAgent>>) -> Self {
        self.workers = workers;
        self
    }

    /// Manager を追加
    pub fn add_manager(mut self, manager: Box<dyn ManagerAgent>) -> Self {
        self.managers.push(manager);
        self
    }

    /// 複数の Managers を追加
    pub fn managers(mut self, managers: Vec<Box<dyn ManagerAgent>>) -> Self {
        self.managers = managers;
        self
    }

    /// BatchInvoker を設定
    pub fn batch_invoker(mut self, invoker: Box<dyn BatchInvoker>) -> Self {
        self.batch_invoker = Some(invoker);
        self
    }

    /// DependencyGraphProvider を設定
    pub fn dependency_provider(mut self, provider: Box<dyn DependencyGraphProvider>) -> Self {
        self.dependency_provider = Some(provider);
        self
    }

    /// OperatorProvider を設定
    pub fn operator_provider(mut self, provider: Box<dyn OperatorProvider<NodeRules>>) -> Self {
        self.operator_provider = Some(provider);
        self
    }

    /// Extensions を設定
    pub fn extensions(mut self, extensions: Extensions) -> Self {
        self.extensions = Some(extensions);
        self
    }

    /// DependencyGraph を設定
    pub fn dependency_graph(mut self, graph: DependencyGraph) -> Self {
        self.dependency_graph = Some(graph);
        self
    }

    /// Offline model を設定
    pub fn offline_model(mut self, model: OfflineModel) -> Self {
        self.offline_model = Some(model);
        self
    }

    /// ScenarioProfile から OfflineModel を生成して設定
    ///
    /// ScenarioProfile の各コンポーネント（LearnedExploration, LearnedStrategy, LearnedDepGraph）
    /// を OfflineModel に変換し、Orchestrator に適用する。
    ///
    /// # Example
    ///
    /// ```ignore
    /// use swarm_engine_core::learn::{LearnableSwarmBuilder, ScenarioProfile};
    ///
    /// let profile = load_profile("troubleshooting")?;
    /// let swarm = LearnableSwarmBuilder::new(runtime.handle().clone())
    ///     .with_scenario_profile(&profile)
    ///     .build()?;
    /// ```
    pub fn with_scenario_profile(mut self, profile: &ScenarioProfile) -> Self {
        let model = profile_to_offline_model(profile);
        self.offline_model = Some(model);
        // シナリオ名も自動設定
        if self.config.scenario.is_empty() {
            self.config.scenario = profile.id.0.clone();
        }
        self
    }

    /// Offline model への参照を取得（build 前に参照する場合）
    pub fn offline_model_ref(&self) -> Option<&OfflineModel> {
        self.offline_model.as_ref()
    }

    /// Prior snapshot を設定
    pub fn prior_snapshot(mut self, snapshot: LearningSnapshot) -> Self {
        self.prior_snapshot = Some(snapshot);
        self
    }

    /// LearningStore を設定（ロードなし、store のみ設定）
    pub fn learning_store(mut self, store: LearningStore) -> Self {
        self.learning_store = Some(store);
        self
    }

    /// 既存の LearningStore からシナリオデータを自動ロード
    ///
    /// prior_snapshot, offline_model, data_dir を自動設定し、learning を有効化する。
    /// EvalRunner など、store を保持し続ける必要がある場合に使用。
    ///
    /// # Note
    /// ロード時のクリティカルエラー（permission denied 等）は `build()` 時に返される。
    /// `NotFound`（初回実行）は正常として扱われる。
    pub fn with_learning_store(mut self, store: LearningStore) -> Self {
        if let Err(e) = self.load_from_store(&store) {
            self.deferred_error = Some(e);
        }
        self.config.data_dir = store.storage().base_dir().to_path_buf();
        self.config.learning_enabled = true;
        self.learning_store = Some(store);
        self
    }

    /// Train trigger を設定
    pub fn train_trigger(mut self, trigger: Arc<dyn TrainTrigger>) -> Self {
        self.train_trigger = Some(trigger);
        self
    }

    /// LifecycleHook を設定
    pub fn lifecycle_hook(mut self, hook: Box<dyn LifecycleHook>) -> Self {
        self.lifecycle_hook = Some(hook);
        self
    }

    /// Exploration を有効化
    pub fn enable_exploration(mut self, enabled: bool) -> Self {
        self.enable_exploration = enabled;
        self
    }

    /// TraceSubscriber を設定（ActionEvent のトレース出力）
    ///
    /// # Example
    ///
    /// ```ignore
    /// use swarm_engine_core::events::{InMemoryTraceSubscriber, JsonlTraceSubscriber};
    ///
    /// // InMemory: 最後にまとめて出力
    /// let trace = Arc::new(InMemoryTraceSubscriber::new());
    /// builder.with_trace_subscriber(trace.clone());
    ///
    /// // Jsonl: リアルタイム出力
    /// let trace = Arc::new(JsonlTraceSubscriber::new("trace.jsonl")?);
    /// builder.with_trace_subscriber(trace);
    /// ```
    pub fn with_trace_subscriber(mut self, subscriber: Arc<dyn TraceSubscriber>) -> Self {
        self.trace_subscriber = Some(subscriber);
        self
    }

    /// LearningStore からシナリオデータを自動ロード（パス指定）
    ///
    /// prior_snapshot と offline_model を自動設定する。
    ///
    /// # Note
    /// Store 作成失敗やロード時のクリティカルエラーは `build()` 時に返される。
    pub fn with_learning_store_path(mut self, path: impl AsRef<std::path::Path>) -> Self {
        match LearningStore::new(&path) {
            Ok(store) => {
                if let Err(e) = self.load_from_store(&store) {
                    self.deferred_error = Some(e);
                }
                self.config.learning_enabled = true;
                self.learning_store = Some(store);
            }
            Err(e) => {
                // Store 作成失敗もクリティカル
                self.deferred_error = Some(SwarmError::Config {
                    message: format!(
                        "Failed to create LearningStore at '{}': {}",
                        path.as_ref().display(),
                        e
                    ),
                });
            }
        }
        self
    }

    /// LearningStore からシナリオデータをロード（内部ヘルパー）
    ///
    /// # Errors
    /// - `NotFound`: 初回実行時（データなし）→ 正常、None を返す
    /// - その他の IO エラー: クリティカル → Err を返す
    fn load_from_store(&mut self, store: &LearningStore) -> Result<(), SwarmError> {
        let scenario_key = &self.config.scenario;

        // Prior snapshot をロード
        match store.load_scenario(scenario_key) {
            Ok(snapshot) => {
                self.prior_snapshot = Some(snapshot);
            }
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                // 初回実行時は存在しない → 正常
                tracing::debug!(scenario = %scenario_key, "No prior snapshot found (first run)");
            }
            Err(e) => {
                // Permission denied, corrupted data 等 → クリティカル
                return Err(SwarmError::Config {
                    message: format!(
                        "Failed to load prior snapshot for '{}': {}",
                        scenario_key, e
                    ),
                });
            }
        }

        // Offline model をロード
        match store.load_offline_model(scenario_key) {
            Ok(model) => {
                tracing::debug!(
                    ucb1_c = model.parameters.ucb1_c,
                    strategy = %model.strategy_config.initial_strategy,
                    action_order = model.action_order.is_some(),
                    "Offline model loaded"
                );
                self.offline_model = Some(model);
            }
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                // 初回実行時は存在しない → 正常
                tracing::debug!(scenario = %scenario_key, "No offline model found (first run)");
            }
            Err(e) => {
                // Permission denied, corrupted data 等 → クリティカル
                return Err(SwarmError::Config {
                    message: format!("Failed to load offline model for '{}': {}", scenario_key, e),
                });
            }
        }

        Ok(())
    }

    /// LearnableSwarm を構築
    pub fn build(mut self) -> Result<LearnableSwarm, SwarmError> {
        // ========================================================================
        // バリデーション
        // ========================================================================
        // Deferred error from builder methods (e.g., load_from_store failure)
        if let Some(err) = self.deferred_error.take() {
            return Err(err);
        }

        if self.config.learning_enabled && self.config.scenario.is_empty() {
            return Err(SwarmError::Config {
                message: "scenario is required when learning is enabled".into(),
            });
        }

        // LearningEventChannel の有効化（ここで一度だけ行う）
        if self.config.learning_enabled {
            LearningEventChannel::global().enable();
        }

        let swarm_config = self.swarm_config.take().unwrap_or_default();

        // ========================================================================
        // Learning 関連の起動（learning_enabled の場合のみ）
        // ========================================================================
        // Note: Initial receiver is not needed; subscribers call action_publisher.subscribe()
        let (action_publisher, _initial_rx) = ActionEventPublisher::new(1024);

        // TraceSubscriber の起動（action_publisher を move する前に subscribe）
        let mut subscriber_handles_trace = Vec::new();
        if let Some(trace_subscriber) = self.trace_subscriber.take() {
            let rx = action_publisher.subscribe();
            let handle = self.runtime.spawn(async move {
                run_trace_subscriber(rx, trace_subscriber).await;
            });
            subscriber_handles_trace.push(handle);
        }

        let LearningSetupResult {
            daemon_handle,
            mut subscriber_handles,
            shutdown_tx,
        } = if self.config.learning_enabled {
            self.setup_learning_components(&action_publisher)?
        } else {
            LearningSetupResult::default()
        };

        // TraceSubscriber の handle を追加
        subscriber_handles.extend(subscriber_handles_trace);

        // ========================================================================
        // OrchestratorBuilder を構築
        // ========================================================================
        // Note: Extensions は self からフィールドを take() するため、
        //       workers/managers を move する前に呼ぶ必要がある
        let extensions = self.build_extensions();

        let mut orch_builder = OrchestratorBuilder::new()
            .config(swarm_config)
            .extensions(extensions);

        // Workers
        for worker in self.workers {
            orch_builder = orch_builder.add_worker_boxed(worker);
        }

        // Managers
        for manager in self.managers {
            orch_builder = orch_builder.add_manager_boxed(manager);
        }

        // BatchInvoker
        if let Some(invoker) = self.batch_invoker {
            orch_builder = orch_builder.batch_invoker_boxed(invoker);
        }

        // DependencyGraphProvider
        if let Some(provider) = self.dependency_provider {
            orch_builder = orch_builder.dependency_provider_boxed(provider);
        }

        // OperatorProvider
        if let Some(provider) = self.operator_provider {
            orch_builder = orch_builder.operator_provider_boxed(provider);
        }

        // Exploration
        if self.enable_exploration {
            orch_builder = orch_builder.with_exploration();
        }

        // Offline model
        if let Some(ref model) = self.offline_model {
            orch_builder = orch_builder.with_offline_model(model.clone());
        }

        // LifecycleHook
        if let Some(hook) = self.lifecycle_hook {
            orch_builder = orch_builder.lifecycle_hook(hook);
        }

        // ActionEventPublisher を Orchestrator に渡す
        orch_builder = orch_builder.action_collector(action_publisher);

        // Orchestrator を構築
        let orchestrator = orch_builder.build(self.runtime.clone());

        Ok(LearnableSwarm {
            orchestrator,
            runtime: self.runtime,
            config: self.config,
            learning_store: self.learning_store,
            offline_model: self.offline_model,
            daemon_handle,
            subscriber_handles,
            shutdown_tx,
        })
    }

    /// Extensions を構築（DependencyGraph, PriorSnapshot を統合）
    fn build_extensions(&mut self) -> Extensions {
        let mut ext = self.extensions.take().unwrap_or_default();

        if let Some(graph) = self.dependency_graph.take() {
            ext.insert(graph);
        }
        if let Some(snapshot) = self.prior_snapshot.take() {
            ext.insert(snapshot);
        }

        ext
    }

    /// Learning 関連コンポーネントをセットアップ
    fn setup_learning_components(
        &self,
        action_publisher: &ActionEventPublisher,
    ) -> Result<LearningSetupResult, SwarmError> {
        // LearningDaemon を作成
        let daemon_config = DaemonConfig::new(&self.config.scenario)
            .data_dir(&self.config.data_dir)
            .check_interval(self.config.daemon_check_interval);

        let trigger = self
            .train_trigger
            .clone()
            .unwrap_or_else(|| TriggerBuilder::never());

        let mut daemon =
            LearningDaemon::new(daemon_config, trigger).map_err(|e| SwarmError::Config {
                message: format!("Failed to create LearningDaemon: {}", e),
            })?;

        let record_tx = daemon.record_sender();
        let shutdown_tx = daemon.shutdown_sender();

        // Subscriber 設定
        let sub_config = EventSubscriberConfig::new()
            .batch_size(self.config.subscriber_batch_size)
            .flush_interval_ms(self.config.subscriber_flush_interval_ms);

        let mut subscriber_handles = Vec::new();

        // ActionEventSubscriber 起動
        let action_sub = ActionEventSubscriber::with_config(
            action_publisher.subscribe(),
            record_tx.clone(),
            sub_config.clone(),
        );
        let action_handle = self.runtime.spawn(async move {
            action_sub.run().await;
        });
        subscriber_handles.push(action_handle);

        // LearningEventSubscriber 起動
        let learning_channel = LearningEventChannel::global();
        let learning_sub = LearningEventSubscriber::with_config(
            learning_channel.subscribe(),
            record_tx,
            sub_config,
        );
        let learning_handle = self.runtime.spawn(async move {
            learning_sub.run().await;
        });
        subscriber_handles.push(learning_handle);

        // LearningDaemon を起動
        let daemon_handle = self.runtime.spawn(async move { daemon.run().await });

        Ok(LearningSetupResult {
            daemon_handle: Some(daemon_handle),
            subscriber_handles,
            shutdown_tx: Some(shutdown_tx),
        })
    }
}

// ============================================================================
// LearnableSwarm
// ============================================================================

/// 学習機能付き Swarm
///
/// Orchestrator + LearningDaemon + Subscriber を統合管理する。
pub struct LearnableSwarm {
    /// Orchestrator
    orchestrator: Orchestrator,
    /// Runtime handle
    runtime: Handle,
    /// 設定
    config: LearnableSwarmConfig,
    /// LearningStore
    learning_store: Option<LearningStore>,
    /// Offline model
    offline_model: Option<OfflineModel>,
    /// LearningDaemon の JoinHandle
    daemon_handle: Option<DaemonHandle>,
    /// Subscriber の JoinHandle
    subscriber_handles: Vec<JoinHandle<()>>,
    /// Shutdown 送信チャンネル
    shutdown_tx: Option<mpsc::Sender<()>>,
}

impl LearnableSwarm {
    /// タスクを実行
    pub fn run_task(&mut self, task: SwarmTask) -> Result<SwarmResult, SwarmError> {
        self.orchestrator.run_task(task)
    }

    /// メインループを実行（タスクなし）
    pub fn run(&mut self) -> SwarmResult {
        self.orchestrator.run()
    }

    /// Orchestrator への参照を取得
    pub fn orchestrator(&self) -> &Orchestrator {
        &self.orchestrator
    }

    /// Orchestrator への可変参照を取得
    pub fn orchestrator_mut(&mut self) -> &mut Orchestrator {
        &mut self.orchestrator
    }

    /// DependencyGraph への参照を取得
    pub fn dependency_graph(&self) -> Option<&DependencyGraph> {
        self.orchestrator.dependency_graph()
    }

    /// 設定を取得
    pub fn config(&self) -> &LearnableSwarmConfig {
        &self.config
    }

    /// LearningStore を取得
    pub fn learning_store(&self) -> Option<&LearningStore> {
        self.learning_store.as_ref()
    }

    /// Offline model を取得
    pub fn offline_model(&self) -> Option<&OfflineModel> {
        self.offline_model.as_ref()
    }

    /// 学習機能が有効かどうか
    pub fn is_learning_enabled(&self) -> bool {
        self.config.learning_enabled
    }

    /// LearnStatsSnapshot Event を発行
    ///
    /// セッション終了時に呼び出し、LearnStats をスナップショットとして記録する。
    /// Learning が有効な場合、shutdown 前に必ず呼び出すこと。
    pub fn emit_stats_snapshot(&self) {
        use crate::events::{LearnStatsOutcome, LearningEvent};
        use crate::util::epoch_millis;

        let state = self.orchestrator.state();
        let tick = state.shared.tick;
        let total_actions = state.shared.stats.total_visits() as u64;

        // LearnStats を JSON シリアライズ
        let stats_json = if let Some(provider) = self.orchestrator.learned_provider() {
            provider
                .stats()
                .map(|stats| serde_json::to_string(stats).unwrap_or_default())
                .unwrap_or_default()
        } else {
            String::new()
        };

        // Session ID を生成（timestamp ベース）
        let session_id = format!("{}", epoch_millis());

        // 結果を判定（environment_done で成功判定）
        let outcome = if state.shared.environment_done {
            LearnStatsOutcome::Success { score: 1.0 }
        } else {
            LearnStatsOutcome::Timeout {
                partial_score: None,
            }
        };

        // Event を発行
        let event = LearningEvent::learn_stats_snapshot(&self.config.scenario)
            .session_id(session_id)
            .stats_json(stats_json)
            .total_ticks(tick)
            .total_actions(total_actions);

        let event = match outcome {
            LearnStatsOutcome::Success { score } => event.success(score),
            LearnStatsOutcome::Timeout { partial_score } => event.timeout(partial_score),
            LearnStatsOutcome::Failure { reason } => event.failure(reason),
        };

        LearningEventChannel::global().emit(event.build());

        tracing::debug!(
            scenario = %self.config.scenario,
            tick = tick,
            total_actions = total_actions,
            "LearnStatsSnapshot emitted"
        );
    }

    /// Shutdown 送信チャンネルを取得（所有権を移動）
    ///
    /// 非同期 shutdown が不可能な環境（tokio runtime 内での block_on）で使用。
    /// 取得後、`try_send(())` でシャットダウン信号を送信し、Drop で cleanup。
    pub fn take_shutdown_tx(&mut self) -> Option<mpsc::Sender<()>> {
        self.shutdown_tx.take()
    }

    /// Graceful shutdown
    ///
    /// LearningDaemon と Subscriber を停止し、完了を待つ。
    /// 学習が有効な場合、shutdown 前に LearnStatsSnapshot Event を発行する。
    pub async fn shutdown(self) {
        // 学習が有効な場合、LearnStatsSnapshot を発行
        if self.config.learning_enabled {
            self.emit_stats_snapshot();
        }

        // Shutdown signal を送信
        if let Some(tx) = self.shutdown_tx {
            let _ = tx.send(()).await;
        }

        // Daemon の終了を待つ
        if let Some(handle) = self.daemon_handle {
            match handle.await {
                Ok(Ok(())) => {
                    tracing::debug!("LearningDaemon shutdown completed");
                }
                Ok(Err(e)) => {
                    tracing::warn!("LearningDaemon error on shutdown: {}", e);
                }
                Err(e) => {
                    tracing::warn!("LearningDaemon join error: {}", e);
                }
            }
        }

        // Subscriber の終了を待つ
        for handle in self.subscriber_handles {
            let _ = handle.await;
        }

        tracing::debug!("LearnableSwarm shutdown completed");
    }

    /// 同期的な shutdown（blocking）
    pub fn shutdown_blocking(self) {
        let runtime = self.runtime.clone();
        runtime.block_on(self.shutdown());
    }
}

// ============================================================================
// TraceSubscriber Runner
// ============================================================================

/// TraceSubscriber を実行するタスク
async fn run_trace_subscriber(
    mut rx: tokio::sync::broadcast::Receiver<crate::events::ActionEvent>,
    subscriber: Arc<dyn TraceSubscriber>,
) {
    while let Ok(event) = rx.recv().await {
        subscriber.on_event(&event);
    }
    subscriber.finish();
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use crate::agent::GenericWorker;

    fn make_test_runtime() -> tokio::runtime::Runtime {
        tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
            .unwrap()
    }

    #[test]
    fn test_config_default() {
        let config = LearnableSwarmConfig::default();
        assert!(!config.learning_enabled);
        assert!(config.scenario.is_empty());
    }

    #[test]
    fn test_config_builder() {
        let config = LearnableSwarmConfig::new("test-scenario")
            .with_learning(true)
            .data_dir("/tmp/test");

        assert_eq!(config.scenario, "test-scenario");
        assert!(config.learning_enabled);
        assert_eq!(config.data_dir, PathBuf::from("/tmp/test"));
    }

    #[test]
    fn test_builder_basic() {
        let rt = make_test_runtime();

        let builder = LearnableSwarmBuilder::new(rt.handle().clone())
            .scenario("test")
            .add_worker(Box::new(GenericWorker::new(0)));

        assert_eq!(builder.config.scenario, "test");
        assert_eq!(builder.workers.len(), 1);
    }

    #[test]
    fn test_builder_with_learning() {
        let rt = make_test_runtime();

        let builder = LearnableSwarmBuilder::new(rt.handle().clone())
            .scenario("test")
            .with_learning(true)
            .add_worker(Box::new(GenericWorker::new(0)));

        assert!(builder.config.learning_enabled);
    }

    #[test]
    fn test_builder_learning_without_scenario_fails() {
        let rt = make_test_runtime();

        let result = LearnableSwarmBuilder::new(rt.handle().clone())
            .with_learning(true)
            .add_worker(Box::new(GenericWorker::new(0)))
            .build();

        assert!(result.is_err());
        if let Err(err) = result {
            assert!(err.to_string().contains("scenario is required"));
        }
    }

    #[test]
    fn test_builder_learning_disabled_without_scenario_ok() {
        let rt = make_test_runtime();

        // learning_enabled=false の場合、scenario が空でも OK
        let result = LearnableSwarmBuilder::new(rt.handle().clone())
            .add_worker(Box::new(GenericWorker::new(0)))
            .build();

        assert!(result.is_ok());
    }

    #[test]
    fn test_builder_with_scenario_profile() {
        use crate::learn::learned_component::LearnedExploration;
        use crate::learn::scenario_profile::{ScenarioProfile, ScenarioSource};

        let rt = make_test_runtime();

        // Create a profile with exploration data
        let mut profile =
            ScenarioProfile::new("test-profile", ScenarioSource::from_path("/test.toml"));
        profile.exploration = Some(LearnedExploration::new(2.5, 0.4, 1.2));

        let builder = LearnableSwarmBuilder::new(rt.handle().clone())
            .with_scenario_profile(&profile)
            .add_worker(Box::new(GenericWorker::new(0)));

        // Scenario should be auto-set from profile
        assert_eq!(builder.config.scenario, "test-profile");
        // OfflineModel should be set
        assert!(builder.offline_model.is_some());
        let model = builder.offline_model.as_ref().unwrap();
        assert_eq!(model.parameters.ucb1_c, 2.5);
    }
}