ryo_app/api/

mod.rs

//! Api - External interface for RYO operations.
//!
//! This module provides the main entry point for RYO operations.
//! It orchestrates Intent → Mutation → Execution flow.
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────┐
//! │  Api (Application Facade)                                        │
//! │  ├── discover(...)  → DiscoverResponse                          │
//! │  ├── suggest(...)   → SuggestResponse                           │
//! │  ├── run(...)       → RunResponse                               │
//! │  ├── graph_cascade(...) → CascadeResponse                       │
//! │  └── status()       → StatusResponse                            │
//! └─────────────────────────────────────────────────────────────────┘
//!                     │
//!                     ▼
//! ┌─────────────────────────────────────────────────────────────────┐
//! │  Internal Services (non-public)                                  │
//! │  ├── DiscoverService                                             │
//! │  ├── SuggestionEngine                                            │
//! │  ├── GraphApi                                                    │
//! │  └── SpecService                                                 │
//! └─────────────────────────────────────────────────────────────────┘
//! ```
//!
//! # Example
//!
//! ```ignore
//! use ryo_app::{Api, DiscoverRequest};
//!
//! // Create API from project path
//! let api = Api::from_path("/path/to/project")?;
//!
//! // Discover symbols
//! let response = api.discover(DiscoverRequest {
//!     pattern: "Config*".to_string(),
//!     kind: None,
//!     sort: None,
//!     limit: Some(10),
//! })?;
//!
//! for sym in response.results {
//!     println!("{}: {}", sym.name, sym.path.display());
//! }
//! ```

mod types;

pub use types::*;

use crate::config::{RyoConfig, SuggestConfig};
use crate::intent::{ConflictStrategy, Goal, Intent};
use crate::planner::{PlanError, Planner};
use crate::project::Project;
use crate::storage::Storage;
use ryo_analysis::{
    AnalysisContext, DiscoveryEngine, DiscoveryQuery, SymbolId, SymbolKind, UuidPersistence,
};
use ryo_executor::{collect_affected_ids, BlueprintExecutor, Conflict, ParallelBlueprint};
use ryo_query_language::{MatchResult, MatchView, QueryExecutor};
use ryo_storage::{FileUuidStorage, TxAction, TxLog};
use ryo_suggest::{
    EnhancedSuggestion, RuleStore, SafetyLevel, StringErrorType, SuggestId, SuggestQuery,
    SuggestRegistry, SuggestService, UnnecessaryClone, UnwrapToExpect,
};
use ryo_symbol::{ResolveError, WorkspaceType};
use ryo_verification::{
    CargoVerifier, FileChange, GraphVerifier, InMemoryVerifier, VerificationInput,
    VerificationPipeline,
};
use std::cell::RefCell;
use std::path::{Path, PathBuf};
use std::time::Instant;

type DefinitionDetails = (
    Vec<types::TypeFieldInfo>,
    Vec<types::TypeVariantInfo>,
    Vec<types::TypeParamInfo>,
    Option<String>,
    Vec<String>,
    Option<String>,
    Vec<String>,
);

/// Convert QueryExecutor's MatchResult to tarpc-compatible DiscoveredSymbol
fn convert_match_result_to_discovered_symbol(m: MatchResult) -> types::DiscoveredSymbol {
    let (view_mode, definition, doc, body, snippet) = match m.view {
        MatchView::Snippet { text } => ("snippet".to_string(), None, None, None, Some(text)),
        MatchView::Precise => ("precise".to_string(), None, None, None, None),
        MatchView::Def {
            module_path: _,
            definition,
            doc,
        } => ("def".to_string(), Some(definition), doc, None, None),
        MatchView::Full {
            module_path: _,
            definition,
            doc,
            body,
        } => ("full".to_string(), Some(definition), doc, Some(body), None),
    };

    types::DiscoveredSymbol {
        id: m.id,
        uuid: m.uuid,
        path: m.path,
        name: m.name,
        kind: m.node_kind,
        view_mode,
        definition,
        doc,
        body,
        snippet,
    }
}

/// Extract parent path string from an Intent (if it has one).
///
/// Returns the path string for intents that have a parent field (like AddCode).
/// Used for validating that `crate::` prefixed paths are unambiguous in workspaces.
fn format_generics(g: &ryo_analysis::detail_store::GenericInfo) -> String {
    let mut parts = Vec::new();
    for lt in &g.lifetimes {
        parts.push(lt.clone());
    }
    for tp in &g.type_params {
        parts.push(tp.clone());
    }
    for (name, ty) in &g.const_params {
        parts.push(format!("const {}: {}", name, ty));
    }
    format!("<{}>", parts.join(", "))
}

fn extract_parent_path_string(intent: &Intent) -> Option<String> {
    match intent {
        Intent::AddCode { symbol_path, .. } => {
            // symbol_pathが"::"を含む場合のみ検証対象
            symbol_path.as_ref().filter(|p| p.contains("::")).cloned()
        }
        // Other intents don't have parent paths that need validation
        _ => None,
    }
}

/// Error type for API operations.
#[derive(Debug, thiserror::Error)]
pub enum ApiError {
    #[error("Project error: {0}")]
    Project(#[from] crate::project::ProjectError),

    #[error("Planning error: {0}")]
    Planning(#[from] PlanError),

    #[error("Execution error: {0}")]
    Execution(String),

    #[error("Storage error: {0}")]
    Storage(#[from] ryo_storage::StorageError),

    #[error("Invalid goal: {0}")]
    InvalidGoal(String),

    #[error("Conflicts detected: {0} conflicts require resolution")]
    Conflicts(usize),

    #[error("Syntax error after mutation: {0}")]
    SyntaxError(String),

    #[error("Not found: {0}")]
    NotFound(String),

    #[error("Graph error: {0}")]
    Graph(#[from] crate::graph::GraphError),

    #[error("Discover error: {0}")]
    Discover(#[from] crate::discover::DiscoverError),

    #[error("Spec error: {0}")]
    Spec(#[from] crate::spec::SpecError),

    #[error("{0}")]
    Resolve(#[from] ResolveError),

    #[error("File sync error: {0}")]
    Sync(#[from] ryo_executor::SyncError),
}

/// Result type for API operations.
pub type ApiResult<T> = Result<T, ApiError>;

/// Options for execution.
#[derive(Debug, Clone, Default)]
pub struct ExecuteOptions {
    /// Skip actual mutation execution (plan and validate only).
    /// When true, planning and conflict detection are performed but no changes are applied.
    pub dry_run: bool,

    /// Verify syntax after mutations using syn parser.
    /// When true, all modified files are parsed to ensure valid Rust syntax.
    pub check_syntax: bool,
}

impl ExecuteOptions {
    /// Create new options with defaults.
    pub fn new() -> Self {
        Self::default()
    }

    /// Enable dry-run mode.
    pub fn dry_run(mut self) -> Self {
        self.dry_run = true;
        self
    }

    /// Enable syntax checking.
    pub fn check_syntax(mut self) -> Self {
        self.check_syntax = true;
        self
    }
}

/// Execution result from API.
#[derive(Debug, Clone)]
pub struct ExecutionResult {
    /// Structured status with code and detailed reason.
    /// This is the primary way to understand the execution outcome.
    pub status: ExecutionStatus,
    /// Number of files modified
    pub files_modified: usize,
    /// Total changes made
    pub total_changes: usize,
    /// Session ID (if logged)
    pub session_id: Option<String>,
    /// Transaction log with mutation history
    pub log: TxLog,
    /// Paths of modified files
    pub modified_files: Vec<PathBuf>,
    /// Detected conflicts (if any)
    pub conflicts: Vec<Conflict>,
    /// Syntax errors found during verification (if check_syntax enabled)
    pub syntax_errors: Vec<String>,
    /// Whether execution completed successfully (derived from status.is_success())
    pub success: bool,
}

impl ExecutionResult {
    /// Create a new ExecutionResult with the given status.
    pub fn with_status(status: ExecutionStatus) -> Self {
        let success = status.is_success();
        Self {
            status,
            files_modified: 0,
            total_changes: 0,
            session_id: None,
            log: TxLog::new(),
            modified_files: vec![],
            conflicts: vec![],
            syntax_errors: vec![],
            success,
        }
    }

    /// Create a successful result with OK status.
    pub fn ok(changes: usize, files: usize) -> Self {
        let reason = format!("{} changes in {} files", changes, files);
        Self {
            status: ExecutionStatus::ok(reason),
            files_modified: files,
            total_changes: changes,
            session_id: None,
            log: TxLog::new(),
            modified_files: vec![],
            conflicts: vec![],
            syntax_errors: vec![],
            success: true,
        }
    }

    /// Create a no-change result.
    pub fn no_change(reason: impl Into<String>) -> Self {
        Self {
            status: ExecutionStatus::no_change(reason),
            files_modified: 0,
            total_changes: 0,
            session_id: None,
            log: TxLog::new(),
            modified_files: vec![],
            conflicts: vec![],
            syntax_errors: vec![],
            success: true,
        }
    }
}

/// Main API for RYO operations.
///
/// This is the primary entry point for external consumers (CLI, UI, Agent).
/// All operations go through this facade.
pub struct Api {
    /// Analysis context - owned directly for mutable access during execution.
    /// The context maintains SymbolRegistry and FileRegistry which must persist
    /// across Discover → Run sequences to keep SymbolId/FileId valid.
    context: AnalysisContext,
    /// Storage backend for persistence
    storage: Box<dyn Storage>,
    /// UUID persistence backend
    uuid_storage: Box<dyn UuidPersistence>,
    /// Project for file operations
    project: Project,
    /// Cached SpecFlowData (invalidated on context.files change)
    spec_cache: Option<crate::spec::SpecFlowData>,
    /// Suggestion service for code improvement suggestions
    suggest: SuggestService,
    /// Suggestion configuration
    suggest_config: SuggestConfig,
    /// Generator templates for parameterized code generation
    generator_store: ryo_suggest::GeneratorStore,
}

impl Api {
    /// Create a new API from a project path.
    ///
    /// This loads the project and builds the analysis context.
    /// Uses `from_workspace_root` for full workspace analysis (not just entry points).
    pub fn from_path(path: impl AsRef<Path>) -> ApiResult<Self> {
        let project = Project::load(path.as_ref())?;
        // Use from_workspace_root for full workspace analysis
        // (Project::load only traverses mod declarations from entry points,
        // which misses files not reachable via mod tree)
        let context = AnalysisContext::from_workspace_root(project.workspace_root())
            .map_err(|e| ApiError::Execution(format!("Context build failed: {}", e)))?;

        // Load suggest config from project's ryo.toml
        let config = RyoConfig::load_or_default(path.as_ref());
        let suggest_config = config.suggest.clone();

        // Create SuggestService with configured strategy
        let registry = Self::create_default_registry(project.root());
        let suggest = SuggestService::with_strategy(registry, suggest_config.to_strategy());

        // Load generator templates
        let generator_store = ryo_suggest::GeneratorStore::load(project.root())
            .unwrap_or_else(|_| ryo_suggest::GeneratorStore::new());

        // Create UUID storage
        let uuid_storage = Box::new(FileUuidStorage::new(project.root()));

        Ok(Self {
            context,
            storage: Box::new(crate::storage::InMemoryStorage::new()),
            uuid_storage,
            project,
            spec_cache: None,
            suggest,
            suggest_config,
            generator_store,
        })
    }

    /// Create a new API with a pre-built context.
    ///
    /// This is useful for server mode where the context is already loaded.
    /// Loads suggest configuration from ryo.toml via the Project.
    pub fn with_context(
        context: AnalysisContext,
        project: Project,
        storage: Box<dyn Storage>,
    ) -> Self {
        // Load suggest config from ryo.toml
        let suggest_config = project.config().suggest.clone();
        let registry = Self::create_default_registry(project.root());
        let suggest = SuggestService::with_strategy(registry, suggest_config.to_strategy());

        // Load generator templates
        let generator_store = ryo_suggest::GeneratorStore::load(project.root())
            .unwrap_or_else(|_| ryo_suggest::GeneratorStore::new());

        // Create UUID storage
        let uuid_storage = Box::new(FileUuidStorage::new(project.root()));

        Self {
            context,
            storage,
            uuid_storage,
            project,
            spec_cache: None,
            suggest,
            suggest_config,
            generator_store,
        }
    }

    /// Create a new API with the given storage backend.
    ///
    /// This is the legacy constructor for backward compatibility.
    /// Uses current directory to load project.
    /// Loads suggest configuration from ryo.toml.
    ///
    /// # Panics
    ///
    /// Panics if project cannot be loaded from current directory.
    /// Consider using `from_path()` instead.
    pub fn new(storage: Box<dyn Storage>) -> Self {
        let cwd = std::env::current_dir().unwrap_or_default();
        let project = Project::load(&cwd).unwrap_or_else(|e| {
            panic!(
                "Api::new(): failed to load project from {:?}: {}. \
                 Use Api::from_path(path, storage) to avoid relying on the current directory.",
                cwd, e
            )
        });
        let context = AnalysisContext::from_workspace_root(project.root()).unwrap_or_else(|e| {
            panic!(
                "Api::new(): failed to create analysis context from {:?}: {}",
                project.root(),
                e
            )
        });

        // Load suggest config from ryo.toml
        let suggest_config = project.config().suggest.clone();
        let registry = Self::create_default_registry(project.root());
        let suggest = SuggestService::with_strategy(registry, suggest_config.to_strategy());

        // Load generator templates
        let generator_store = ryo_suggest::GeneratorStore::load(project.root())
            .unwrap_or_else(|_| ryo_suggest::GeneratorStore::new());

        // Create UUID storage
        let uuid_storage = Box::new(FileUuidStorage::new(project.root()));

        Self {
            context,
            storage,
            uuid_storage,
            project,
            spec_cache: None,
            suggest,
            suggest_config,
            generator_store,
        }
    }

    /// Create the default SuggestRegistry with built-in patterns.
    ///
    /// Loads rules from all sources (builtin, global, project) and registers
    /// them as PatternBasedSuggest in the registry.
    fn create_default_registry(project_path: &Path) -> SuggestRegistry {
        let mut registry = SuggestRegistry::new();

        // Register performance suggests
        registry.register(UnnecessaryClone::new());
        tracing::debug!("Registered performance suggests: UnnecessaryClone");

        // Register safety suggests
        registry.register(UnwrapToExpect::new());
        registry.register(StringErrorType::new());
        tracing::debug!("Registered safety suggests: UnwrapToExpect, StringErrorType");

        // Load rules from all sources (builtin + global + project)
        match RuleStore::load(project_path) {
            Ok(store) => {
                let count = registry.register_from_rule_store(&store);
                tracing::debug!("Registered {} lint rules from RuleStore", count);
            }
            Err(e) => {
                tracing::warn!("Failed to load RuleStore: {}", e);
                // Fall back to builtin rules only
                if let Ok(store) = RuleStore::builtin_only() {
                    let count = registry.register_from_rule_store(&store);
                    tracing::debug!("Registered {} builtin lint rules (fallback)", count);
                }
            }
        }

        registry
    }

    // ========================================================================
    // UUID Resolution Helpers
    // ========================================================================

    /// Resolve a SymbolId from UUID, SymbolId string, or name.
    ///
    /// Resolution priority:
    /// 1. `uuid` - Persistent cross-session identifier (highest priority)
    /// 2. `id` - Session-volatile SymbolId string (e.g., "165v1")
    /// 3. `name` - Symbol name pattern (lowest priority)
    ///
    /// # Returns
    /// - `Ok(Some(SymbolId))` if resolved successfully
    /// - `Ok(None)` if no identifier provided
    /// - `Err(ApiError::NotFound)` if identifier provided but not found
    fn resolve_symbol_id(
        &self,
        uuid: Option<&str>,
        id: Option<&str>,
        name: Option<&str>,
    ) -> ApiResult<Option<SymbolId>> {
        // Priority 1: UUID (persistent)
        if let Some(uuid_str) = uuid {
            let uuid = uuid::Uuid::parse_str(uuid_str).map_err(|_| {
                ApiError::InvalidGoal(format!("Invalid UUID format: '{}'", uuid_str))
            })?;
            return self
                .context
                .registry
                .lookup_by_uuid(uuid)
                .map(Some)
                .ok_or_else(|| {
                    ApiError::NotFound(format!("UUID '{}' not found in registry", uuid_str))
                });
        }

        // Priority 2: SymbolId string (session-volatile)
        if let Some(id_str) = id {
            let symbol_id = SymbolId::parse(id_str).ok_or_else(|| {
                ApiError::InvalidGoal(format!(
                    "Invalid SymbolId format: '{}'. Expected format: '165v1'",
                    id_str
                ))
            })?;
            // Verify symbol exists
            if self.context.registry.resolve(symbol_id).is_none() {
                let info = self
                    .context
                    .registry
                    .resolve(symbol_id)
                    .map(|m| format!(" (symbol: {})", m.name()))
                    .unwrap_or_default();
                return Err(ApiError::NotFound(format!("'{}'{}", id_str, info)));
            }
            return Ok(Some(symbol_id));
        }

        // Priority 3: Name pattern (requires search)
        if let Some(_name_pattern) = name {
            // Name resolution is handled by the calling method
            // since it may need fuzzy matching or glob patterns
            return Ok(None);
        }

        Ok(None)
    }

    /// Resolve a SymbolId from UUID or SymbolId string (required).
    ///
    /// This is a stricter version for APIs that require an identifier.
    /// Unlike `resolve_symbol_id`, this returns an error if no identifier provided.
    fn resolve_symbol_id_required(&self, uuid: Option<&str>, id: &str) -> ApiResult<SymbolId> {
        // Try UUID first
        if let Some(uuid_str) = uuid {
            let uuid = uuid::Uuid::parse_str(uuid_str).map_err(|_| {
                ApiError::InvalidGoal(format!("Invalid UUID format: '{}'", uuid_str))
            })?;
            return self.context.registry.lookup_by_uuid(uuid).ok_or_else(|| {
                ApiError::NotFound(format!("UUID '{}' not found in registry", uuid_str))
            });
        }

        // Fall back to SymbolId string
        let symbol_id = SymbolId::parse(id).ok_or_else(|| {
            ApiError::InvalidGoal(format!(
                "Invalid SymbolId format: '{}'. Expected format: '165v1'",
                id
            ))
        })?;

        // Verify symbol exists and provide better error message
        if self.context.registry.resolve(symbol_id).is_none() {
            let info = self
                .context
                .registry
                .resolve(symbol_id)
                .map(|m| format!(" (symbol: {})", m.name()))
                .unwrap_or_default();
            return Err(ApiError::NotFound(format!("'{}'{}", id, info)));
        }

        Ok(symbol_id)
    }

    /// Build a helpful error when no variables are found in the dataflow graph.
    ///
    /// Detects if the user passed a type name (Struct/Enum/Trait/etc.)
    /// and provides a targeted suggestion.
    fn no_vars_error(
        &self,
        name: Option<&str>,
        display_name: &str,
        registry: &ryo_symbol::SymbolRegistry,
    ) -> ApiError {
        if let Some(name) = name {
            let type_kind = registry.find_by_name(name).into_iter().find_map(|sid| {
                let kind = registry.kind(sid)?;
                matches!(
                    kind,
                    ryo_symbol::SymbolKind::Struct
                        | ryo_symbol::SymbolKind::Enum
                        | ryo_symbol::SymbolKind::Trait
                        | ryo_symbol::SymbolKind::TypeAlias
                        | ryo_symbol::SymbolKind::Union
                )
                .then_some(kind)
            });
            if let Some(kind) = type_kind {
                return ApiError::InvalidGoal(format!(
                    "'{}' is a {:?}. This command analyzes variables within functions. \
                     Pass a function/method name that uses '{}' instead.",
                    name, kind, name
                ));
            }
        }
        ApiError::NotFound(format!(
            "'{}': no variables found in dataflow graph. Pass a function/method name.",
            display_name
        ))
    }

    // ========================================================================
    // Read Operations
    // ========================================================================

    /// Discover symbols by pattern.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.discover(DiscoverRequest {
    ///     pattern: "Config*".to_string(),
    ///     kind: Some(ItemKind::Struct),
    ///     sort: Some(SortOrder::Refs),
    ///     limit: Some(10),
    /// })?;
    /// ```
    pub fn discover(&mut self, request: DiscoverRequest) -> ApiResult<DiscoverResponse> {
        let start = Instant::now();

        // Handle --id: direct lookup by SymbolId
        if request.is_id {
            return self.discover_by_id(&request, start);
        }

        let engine = DiscoveryEngine::new(&self.context.code_graph, &self.context.registry, None);

        let sort = request.sort.map(|s| match s {
            SortOrder::Alpha => ryo_analysis::SortOrder::Alpha,
            SortOrder::Refs => ryo_analysis::SortOrder::Refs,
            SortOrder::Impls => ryo_analysis::SortOrder::Impls,
        });

        // Don't apply limit to query - we apply it after filtering
        let mut query = DiscoveryQuery::symbol(&request.pattern);

        if let Some(kind) = request.kind {
            query = query.kind(kind);
        }
        if let Some(s) = sort {
            query = query.sort(s);
        }
        if request.ignore_case {
            query = query.ignore_case();
        }
        if request.ignore_word_separate {
            query = query.ignore_word_separate();
        }

        let result = engine.execute(&query);

        // Apply RyoQL-style post-filters
        let filtered_symbols = self.apply_discover_filters(
            result.symbols,
            request.is_async,
            request.is_unsafe,
            request.scope_path.as_deref(),
            request.attr.as_deref(),
        );

        // Apply limit after filtering
        let (symbols_to_convert, truncated) = if let Some(limit) = request.limit {
            if filtered_symbols.len() > limit {
                (
                    filtered_symbols.into_iter().take(limit).collect::<Vec<_>>(),
                    true,
                )
            } else {
                (filtered_symbols, result.truncated)
            }
        } else {
            (filtered_symbols, result.truncated)
        };

        let total = symbols_to_convert.len();

        // Use QueryExecutor to convert symbols with view mode
        let view_mode = request.view.unwrap_or_default();
        let executor = QueryExecutor::new(&self.context);

        // Convert to tarpc-compatible DiscoveredSymbol
        let symbols: Vec<types::DiscoveredSymbol> = symbols_to_convert
            .iter()
            .map(|sym| {
                let match_result = executor.to_match_result(sym, view_mode);
                convert_match_result_to_discovered_symbol(match_result)
            })
            .collect();

        let status = if total == 0 {
            "not_found"
        } else if truncated {
            "partial"
        } else {
            "found"
        };

        // Generate hint when 0 results with kind filter
        let hint = if total == 0 && request.kind.is_some() {
            self.generate_discover_hint(&request.pattern, &engine)
        } else {
            None
        };

        Ok(DiscoverResponse {
            status: status.to_string(),
            symbols,
            total,
            elapsed_ms: start.elapsed().as_millis() as u32,
            hint,
        })
    }

    /// Discover a single symbol by SymbolId.
    ///
    /// Used when `request.is_id` is true. Performs direct registry lookup
    /// instead of pattern matching.
    fn discover_by_id(
        &self,
        request: &DiscoverRequest,
        start: Instant,
    ) -> ApiResult<DiscoverResponse> {
        use ryo_analysis::DiscoveredSymbol;

        if request.pattern.contains('*') || request.pattern.contains('?') {
            return Err(ApiError::Execution(
                "--id does not support glob patterns (* or ?)".to_string(),
            ));
        }

        let symbol_id = SymbolId::parse(&request.pattern).ok_or_else(|| {
            ApiError::Execution(format!(
                "Invalid SymbolId format: '{}'. Expected format: '165v1' or 'SymbolId(165v1)'",
                request.pattern
            ))
        })?;

        let mut discovered = Vec::new();
        if let Some(path) = self.context.registry.resolve(symbol_id) {
            let kind = self
                .context
                .registry
                .kind(symbol_id)
                .unwrap_or(ryo_analysis::SymbolKind::Any);
            let mut symbol = DiscoveredSymbol::new(symbol_id, path.clone(), kind);
            if let Some(span) = self.context.registry.span(symbol_id) {
                symbol = symbol.with_span(span.clone());
            }
            if let Some(vis) = self.context.registry.visibility(symbol_id) {
                symbol = symbol.with_visibility(vis.clone());
            }
            discovered.push(symbol);
        }

        let total = discovered.len();
        let view_mode = request.view.unwrap_or_default();
        let executor = QueryExecutor::new(&self.context);

        let symbols: Vec<types::DiscoveredSymbol> = discovered
            .iter()
            .map(|sym| {
                let match_result = executor.to_match_result(sym, view_mode);
                convert_match_result_to_discovered_symbol(match_result)
            })
            .collect();

        let status = if total == 0 { "not_found" } else { "found" };

        Ok(DiscoverResponse {
            status: status.to_string(),
            symbols,
            total,
            elapsed_ms: start.elapsed().as_millis() as u32,
            hint: None,
        })
    }

    /// Get codebase overview (module tree, key types, statistics).
    pub fn overview(&self, _request: types::OverviewRequest) -> ApiResult<types::OverviewResponse> {
        use std::collections::BTreeMap;

        let start = Instant::now();

        // 1. Crate/Module structure (iter_by_kind avoids full registry scan)
        let mut crate_modules: BTreeMap<String, Vec<String>> = BTreeMap::new();
        for symbol_id in self
            .context
            .registry
            .iter_by_kind(ryo_analysis::SymbolKind::Mod)
        {
            let Some(path) = self.context.registry.resolve(symbol_id) else {
                continue;
            };
            let path_str = path.to_string();
            let parts: Vec<&str> = path_str.split("::").collect();
            if let Some(crate_name) = parts.first() {
                let module_path = parts[1..].join("::");
                if !module_path.is_empty() {
                    crate_modules
                        .entry(crate_name.to_string())
                        .or_default()
                        .push(module_path);
                } else {
                    crate_modules.entry(crate_name.to_string()).or_default();
                }
            }
        }

        let crates: Vec<types::CrateOverview> = crate_modules
            .into_iter()
            .map(|(name, modules)| types::CrateOverview { name, modules })
            .collect();

        // 2. Top structs by ref_count
        let engine = DiscoveryEngine::new(&self.context.code_graph, &self.context.registry, None);
        let struct_query = DiscoveryQuery::symbol("*")
            .kind(ryo_analysis::SymbolKind::Struct)
            .sort(ryo_analysis::SortOrder::Refs);
        let struct_result = engine.execute(&struct_query);
        let top_structs: Vec<types::OverviewSymbol> = struct_result
            .symbols
            .iter()
            .take(10)
            .map(|s| types::OverviewSymbol {
                path: s.path.to_string(),
                count: s.ref_count,
            })
            .collect();

        // 3. Top traits by impl_count
        let trait_query = DiscoveryQuery::symbol("*")
            .kind(ryo_analysis::SymbolKind::Trait)
            .sort(ryo_analysis::SortOrder::Impls);
        let trait_result = engine.execute(&trait_query);
        let top_traits: Vec<types::OverviewSymbol> = trait_result
            .symbols
            .iter()
            .take(10)
            .map(|s| types::OverviewSymbol {
                path: s.path.to_string(),
                count: s.impl_count,
            })
            .collect();

        // 4. Statistics
        let crate_count = crates.len();
        let kinds = [
            (ryo_analysis::SymbolKind::Function, "Functions"),
            (ryo_analysis::SymbolKind::Struct, "Structs"),
            (ryo_analysis::SymbolKind::Enum, "Enums"),
            (ryo_analysis::SymbolKind::Trait, "Traits"),
            (ryo_analysis::SymbolKind::Impl, "Impls"),
            (ryo_analysis::SymbolKind::Mod, "Mods"),
            (ryo_analysis::SymbolKind::Const, "Consts"),
            (ryo_analysis::SymbolKind::Static, "Statics"),
            (ryo_analysis::SymbolKind::TypeAlias, "TypeAliases"),
        ];
        let by_kind: Vec<(String, usize)> = kinds
            .iter()
            .filter_map(|(kind, name)| {
                let count = self.context.registry.iter_by_kind(*kind).count();
                if count > 0 {
                    Some((name.to_string(), count))
                } else {
                    None
                }
            })
            .collect();

        Ok(types::OverviewResponse {
            crates,
            top_structs,
            top_traits,
            stats: types::OverviewStats {
                crate_count,
                by_kind,
            },
            elapsed_ms: start.elapsed().as_millis() as u32,
        })
    }

    /// Execute a RyoQL query and return structured results.
    ///
    /// Parses the query string (YAML/JSON), determines view mode, and executes
    /// against the analysis context.
    pub fn query_ryoql(&self, request: types::RyoqlRequest) -> ApiResult<types::QueryResponse> {
        use ryo_query_language::{QueryExecutor, QueryParser};

        let query = QueryParser::parse(&request.query)
            .map_err(|e| ApiError::SyntaxError(format!("RyoQL parse error: {}", e)))?;

        let view_mode = query.view.or(request.default_view).unwrap_or_default();
        let executor = QueryExecutor::new(&self.context).with_view_mode(view_mode);

        executor
            .execute(&query)
            .map_err(|e| ApiError::Execution(format!("RyoQL execution failed: {}", e)))
    }

    /// Search literals in source code using the LiteralIndex.
    #[cfg(feature = "literal-search")]
    pub fn search_literal(
        &self,
        request: types::LiteralSearchRequest,
    ) -> ApiResult<types::LiteralSearchResponse> {
        use ryo_analysis::literal::{LiteralKind, LiteralQuery};

        let start = Instant::now();

        let literal_index = self
            .context
            .literal_index
            .as_ref()
            .ok_or_else(|| ApiError::Execution("Literal index not available".to_string()))?;

        let mut query = LiteralQuery::new(&request.pattern).with_limit(request.limit);
        if let Some(ref kind_str) = request.kind {
            if let Some(kind) = LiteralKind::parse_kind(kind_str) {
                query = query.with_kind(kind);
            }
        }

        let matches = literal_index
            .search(&query)
            .map_err(|e| ApiError::Execution(format!("Literal search failed: {}", e)))?;

        let total = matches.len();
        let results: Vec<types::LiteralMatchResult> = matches
            .into_iter()
            .map(|m| {
                let symbol_name = self
                    .context
                    .registry
                    .path(m.symbol_id)
                    .map(|p| p.to_string())
                    .unwrap_or_else(|| m.symbol_id.to_string());
                types::LiteralMatchResult {
                    value: m.value,
                    kind: m.kind.to_string(),
                    symbol_id: symbol_name,
                    file_path: m.file_path,
                    score: m.score,
                }
            })
            .collect();

        Ok(types::LiteralSearchResponse {
            matches: results,
            total,
            elapsed_ms: start.elapsed().as_millis() as u32,
        })
    }

    /// Search literals - stub when feature is disabled.
    #[cfg(not(feature = "literal-search"))]
    pub fn search_literal(
        &self,
        _request: types::LiteralSearchRequest,
    ) -> ApiResult<types::LiteralSearchResponse> {
        Err(ApiError::Execution(
            "Literal search not available. Rebuild with `literal-search` feature.".to_string(),
        ))
    }

    /// Apply RyoQL-style filters to discovered symbols.
    fn apply_discover_filters(
        &self,
        symbols: Vec<ryo_analysis::DiscoveredSymbol>,
        is_async: Option<bool>,
        is_unsafe: Option<bool>,
        scope_path: Option<&str>,
        attr: Option<&str>,
    ) -> Vec<ryo_analysis::DiscoveredSymbol> {
        use glob::Pattern as GlobPattern;

        let mut filtered = symbols;

        // Filter by is_async
        if let Some(expected_async) = is_async {
            filtered.retain(|sym| {
                if let Some(detail) = self.context.detail_store.function(sym.id) {
                    detail.is_async == expected_async
                } else {
                    // Non-function symbols: async=false
                    !expected_async
                }
            });
        }

        // Filter by is_unsafe
        if let Some(expected_unsafe) = is_unsafe {
            filtered.retain(|sym| {
                // Check function
                if let Some(detail) = self.context.detail_store.function(sym.id) {
                    return detail.is_unsafe == expected_unsafe;
                }
                // Check trait
                if let Some(detail) = self.context.detail_store.trait_(sym.id) {
                    return detail.is_unsafe == expected_unsafe;
                }
                // Check impl
                if let Some(detail) = self.context.detail_store.impl_(sym.id) {
                    return detail.is_unsafe == expected_unsafe;
                }
                // Other symbols: unsafe=false
                !expected_unsafe
            });
        }

        // Filter by scope_path (glob pattern)
        if let Some(pattern) = scope_path {
            if let Ok(glob) = GlobPattern::new(pattern) {
                filtered.retain(|sym| {
                    if let Some(ref span) = sym.span {
                        glob.matches(span.file.as_relative().to_string_lossy().as_ref())
                    } else {
                        false // No span = excluded
                    }
                });
            }
        }

        // Filter by attribute pattern (glob-style)
        if let Some(pattern) = attr {
            if let Ok(glob) = GlobPattern::new(pattern) {
                filtered.retain(|sym| {
                    // Collect attrs from any detail type that matches this symbol
                    let attrs = self.get_symbol_attrs(sym.id);
                    attrs.iter().any(|a| glob.matches(a))
                });
            }
        }

        filtered
    }

    /// Get attributes for a symbol from any matching detail type.
    fn get_symbol_attrs(&self, id: ryo_analysis::SymbolId) -> Vec<&str> {
        let detail_store = &self.context.detail_store;

        // Check function
        if let Some(detail) = detail_store.function(id) {
            return detail.attrs.iter().map(|s| s.as_str()).collect();
        }
        // Check struct
        if let Some(detail) = detail_store.struct_(id) {
            return detail.attrs.iter().map(|s| s.as_str()).collect();
        }
        // Check enum
        if let Some(detail) = detail_store.enum_(id) {
            return detail.attrs.iter().map(|s| s.as_str()).collect();
        }
        // Check trait
        if let Some(detail) = detail_store.trait_(id) {
            return detail.attrs.iter().map(|s| s.as_str()).collect();
        }
        // Check impl
        if let Some(detail) = detail_store.impl_(id) {
            return detail.attrs.iter().map(|s| s.as_str()).collect();
        }

        Vec::new()
    }

    /// Generate alternative search hint when 0 results with kind filter.
    ///
    /// Searches with `*pattern*`, `kind=None`, `ignore_case=true`, `ignore_word_separate=true`
    /// and returns a hint message if matches are found.
    fn generate_discover_hint(&self, pattern: &str, engine: &DiscoveryEngine) -> Option<String> {
        // Build glob pattern: *Word* for contains search
        let glob_pattern = if pattern.contains('*') {
            pattern.to_string()
        } else {
            format!("*{}*", pattern)
        };

        // Re-search with kind=None (any), ignore_case=true, ignore_word_separate=true
        let alt_query = DiscoveryQuery::symbol(&glob_pattern)
            .ignore_case()
            .ignore_word_separate();
        let alt_result = engine.execute(&alt_query);

        if alt_result.symbols.is_empty() {
            return None;
        }

        // Show up to 5 unique matches as hints
        let samples: Vec<_> = alt_result
            .symbols
            .iter()
            .take(5)
            .map(|s| format!("  - {} [{}]", s.path, s.kind))
            .collect();

        let more = if alt_result.symbols.len() > 5 {
            format!("\n  ... and {} more", alt_result.symbols.len() - 5)
        } else {
            String::new()
        };

        Some(format!(
            "Hint: {} matches found with \"{}\" --kind any -i -w:\n{}{}",
            alt_result.symbols.len(),
            glob_pattern,
            samples.join("\n"),
            more
        ))
    }

    /// Get improvement suggestions.
    ///
    /// Uses the integrated SuggestService to query cached suggestions.
    /// Call `suggest_scan()` first to detect new suggestions.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.suggest(SuggestRequest {
    ///     pattern_filter: Some("*Service*".to_string()),
    ///     high_impact: true,
    ///     quick: false,
    /// })?;
    /// ```
    pub fn suggest(&self, request: SuggestRequest) -> ApiResult<SuggestResponse> {
        // Parse scope filter from request
        let scope_filter: Vec<ryo_suggest::SymbolScope> = request
            .scope_filter
            .iter()
            .filter_map(|s| s.parse().ok())
            .collect();

        // Run scan if requested
        if request.scan {
            if request.precheck {
                let _ = self.suggest_scan_with_precheck();
            } else {
                let _ = self.suggest_scan_with_scope(&scope_filter);
            }
        }

        // Build query from request
        let mut query = SuggestQuery::all();

        // Apply filters
        if request.high_impact {
            query = query.with_max_safety(SafetyLevel::Auto);
        }

        // Query the suggest service
        let results = self.suggest.query(&query);

        // Convert to response format with exclusion filter
        let exclude_rules = &request.exclude_rules;
        let suggestions: Vec<Suggestion> = results
            .iter()
            .filter_map(|(id, category, safety)| {
                // Filter out excluded rules
                if !exclude_rules.is_empty() {
                    if let Some(rule_id) = self.suggest.rule_id(*id) {
                        if exclude_rules.iter().any(|ex| ex == rule_id) {
                            return None;
                        }
                    }
                }

                let stored = self.suggest.get(*id)?;

                // Filter by scope
                if !scope_filter.is_empty() && !scope_filter.contains(&stored.opportunity.scope) {
                    return None;
                }

                let pattern_name = self.suggest.pattern_name(*id)?;
                let rule_id = self.suggest.rule_id(*id).map(|s| s.to_string());

                Some(Suggestion {
                    id: id.to_string(),
                    rule_id,
                    title: pattern_name.to_string(),
                    description: stored.opportunity.message.clone(),
                    category: format!("{:?}", category),
                    impact: format!("{:?}", safety),
                    file: PathBuf::from(&stored.opportunity.location.file),
                    symbol_path: Some(stored.opportunity.location.symbol_path.to_string()),
                    fix_intent: None, // TODO: Generate intent from MutationSpec
                })
            })
            .collect();

        // Sort suggestions by ID for deterministic output
        let mut suggestions = suggestions;
        suggestions.sort_by(|a, b| a.id.cmp(&b.id));

        // Build summary
        let total = suggestions.len();
        let high_impact = suggestions.iter().filter(|s| s.impact == "Auto").count();

        // Count by category
        let mut by_category = std::collections::HashMap::new();
        for s in &suggestions {
            *by_category.entry(s.category.clone()).or_insert(0) += 1;
        }

        // Build enhanced suggestions if requested
        let enhanced = if request.enhanced {
            results
                .iter()
                .filter_map(|(id, _category, _safety)| {
                    // Filter out excluded rules
                    if !exclude_rules.is_empty() {
                        if let Some(rule_id) = self.suggest.rule_id(*id) {
                            if exclude_rules.iter().any(|ex| ex == rule_id) {
                                return None;
                            }
                        }
                    }

                    let stored = self.suggest.get(*id)?;

                    // Filter by scope
                    if !scope_filter.is_empty() && !scope_filter.contains(&stored.opportunity.scope)
                    {
                        return None;
                    }

                    Some(
                        EnhancedSuggestion::from_opportunity(&stored.opportunity, *id)
                            .with_description(stored.opportunity.message.clone()),
                    )
                })
                .collect()
        } else {
            Vec::new()
        };

        Ok(SuggestResponse {
            suggestions,
            summary: SuggestionSummary {
                total,
                high_impact,
                by_category: by_category.into_iter().collect(),
            },
            enhanced,
        })
    }

    /// Scan the codebase and detect new suggestions.
    ///
    /// This runs all registered patterns against the current context
    /// and populates the suggestion cache.
    ///
    /// Respects `disabled_rules`, `enabled_rules`, and `severity_overrides` from ryo.toml.
    pub fn suggest_scan(&self) -> usize {
        self.suggest_scan_with_scope(&[])
    }

    /// Scan with scope filtering.
    ///
    /// If `scope_filter` is empty, all scopes are included.
    /// Otherwise, only suggestions matching one of the specified scopes are stored.
    pub fn suggest_scan_with_scope(&self, scope_filter: &[ryo_suggest::SymbolScope]) -> usize {
        use ryo_suggest::LintSeverity;

        // Collect all symbol IDs from the registry
        let all_symbols: Vec<SymbolId> = self.context.registry.iter().map(|(id, _)| id).collect();

        // Build allow store
        let allow_store = ryo_suggest::AllowStore::from_context(&self.context);

        // Run detection with full configuration
        // Use project config for module-level rule filtering
        let config = self.project.config();
        self.suggest.detect_with_config_and_scope(
            &self.context,
            &all_symbols,
            &allow_store,
            |rule_id, file_path| config.is_rule_enabled_for_file(file_path, rule_id),
            |rule_id| {
                self.suggest_config
                    .get_severity_override(rule_id)
                    .and_then(|s| s.parse::<LintSeverity>().ok())
            },
            scope_filter,
        )
    }

    /// Scan the codebase with pre-check verification.
    ///
    /// This runs all registered patterns against the current context,
    /// verifies each suggestion speculatively, and only stores suggestions
    /// that pass the pre-check. This ensures that Apply will succeed.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let result = api.suggest_scan_with_precheck();
    /// println!("Passed: {}, Failed: {}", result.passed, result.failed_precheck);
    /// ```
    pub fn suggest_scan_with_precheck(&self) -> ryo_suggest::DetectWithPrecheckResult {
        use std::sync::atomic::{AtomicU64, Ordering};

        // Timing accumulators (in microseconds)
        static FORK_TIME: AtomicU64 = AtomicU64::new(0);
        static EXEC_TIME: AtomicU64 = AtomicU64::new(0);
        static GRAPH_REBUILD_TIME: AtomicU64 = AtomicU64::new(0);
        static VERIFY_TIME: AtomicU64 = AtomicU64::new(0);
        static COUNT: AtomicU64 = AtomicU64::new(0);

        // Reset counters
        FORK_TIME.store(0, Ordering::Relaxed);
        EXEC_TIME.store(0, Ordering::Relaxed);
        GRAPH_REBUILD_TIME.store(0, Ordering::Relaxed);
        VERIFY_TIME.store(0, Ordering::Relaxed);
        COUNT.store(0, Ordering::Relaxed);

        // Collect all symbol IDs from the registry
        let all_symbols: Vec<SymbolId> = self.context.registry.iter().map(|(id, _)| id).collect();

        // Measure wall-clock time for the parallel phase
        let wall_start = Instant::now();

        // Run detection with parallel pre-check (rayon-based)
        // OPTIMIZATION: Use thread_local to cache forked context per thread.
        // - First use on thread: fork_clone (expensive, ~78ms)
        // - Subsequent uses: snapshot → apply → verify → rollback (cheap)
        // This reduces fork_clone calls from N (=suggestions) to T (=thread count).
        thread_local! {
            static CACHED_CTX: RefCell<Option<AnalysisContext>> = const { RefCell::new(None) };
        }

        // Limit to top 100 candidates by priority to keep precheck fast
        const PRECHECK_LIMIT: usize = 100;

        // Use rule filter from config for project-level disabled_rules/enabled_rules
        let result = self.suggest.detect_with_parallel_precheck_and_rule_filter(
            &self.context,
            &all_symbols,
            Some(PRECHECK_LIMIT),
            |rule_id| self.suggest_config.is_rule_enabled(rule_id),
            |opp, specs, ctx| {
                COUNT.fetch_add(1, Ordering::Relaxed);

                CACHED_CTX.with(|cell| {
                    let mut borrow = cell.borrow_mut();

                    // First use on this thread: fork_clone (expensive, but only once per thread)
                    let forked_ctx = borrow.get_or_insert_with(|| {
                        let t0 = Instant::now();
                        let cloned = ctx.fork_clone();
                        FORK_TIME.fetch_add(t0.elapsed().as_micros() as u64, Ordering::Relaxed);
                        cloned
                    });

                    // Get target symbols from opportunity for snapshot
                    let target_ids = &opp.targets;

                    // Take snapshot before mutation (cheap: just copies affected AST items)
                    let t_snapshot = Instant::now();
                    let snapshot = forked_ctx.snapshot_symbols(target_ids);
                    // Include snapshot time in FORK_TIME for comparison
                    FORK_TIME.fetch_add(t_snapshot.elapsed().as_micros() as u64, Ordering::Relaxed);

                    // Apply mutations speculatively
                    let t1 = Instant::now();
                    let blueprint = ParallelBlueprint::from_mutations(specs.to_vec());
                    let executor = BlueprintExecutor::default();
                    let exec_result = executor.execute_v2(&blueprint, forked_ctx);
                    EXEC_TIME.fetch_add(t1.elapsed().as_micros() as u64, Ordering::Relaxed);

                    if !exec_result.success {
                        // Rollback and return false
                        forked_ctx.rollback(snapshot, target_ids);
                        return false;
                    }

                    // Rebuild analysis graphs from MutationEvents (symbol-based, O(S))
                    // CRITICAL: Without this, GraphVerifier would check against stale indices
                    let t_rebuild = Instant::now();
                    let all_events: Vec<_> = exec_result
                        .results
                        .iter()
                        .flat_map(|r| r.events.clone())
                        .collect();
                    let affected_ids: Vec<SymbolId> = if !all_events.is_empty() {
                        let ids = collect_affected_ids(&all_events, forked_ctx.registry());
                        forked_ctx.rebuild_after_mutation_by_symbols(&ids);
                        ids
                    } else {
                        target_ids.clone()
                    };
                    GRAPH_REBUILD_TIME
                        .fetch_add(t_rebuild.elapsed().as_micros() as u64, Ordering::Relaxed);

                    // Verify
                    let t2 = Instant::now();
                    let verifier = GraphVerifier::new();
                    let vresult = verifier.verify_precheck(forked_ctx);
                    VERIFY_TIME.fetch_add(t2.elapsed().as_micros() as u64, Ordering::Relaxed);

                    // Rollback to original state for next iteration
                    let t_rollback = Instant::now();
                    forked_ctx.rollback(snapshot, &affected_ids);
                    // Include rollback time in GRAPH_REBUILD_TIME
                    GRAPH_REBUILD_TIME
                        .fetch_add(t_rollback.elapsed().as_micros() as u64, Ordering::Relaxed);

                    vresult.is_success()
                })
            },
        );

        // Measure wall-clock time
        let wall_elapsed = wall_start.elapsed();

        // Write timing summary to file
        let count = COUNT.load(Ordering::Relaxed);
        if count > 0 {
            let cpu_total = (FORK_TIME.load(Ordering::Relaxed)
                + EXEC_TIME.load(Ordering::Relaxed)
                + GRAPH_REBUILD_TIME.load(Ordering::Relaxed)
                + VERIFY_TIME.load(Ordering::Relaxed)) as f64
                / 1000.0;
            let wall_ms = wall_elapsed.as_millis() as f64;
            let parallelism = if wall_ms > 0.0 {
                cpu_total / wall_ms
            } else {
                0.0
            };

            let timing = format!(
                "\n=== Precheck Timing ({} suggestions) ===\n\
                 fork_clone:    {:>8.2}ms total, {:>6.2}ms avg\n\
                 execute_v2:    {:>8.2}ms total, {:>6.2}ms avg\n\
                 graph_rebuild: {:>8.2}ms total, {:>6.2}ms avg\n\
                 verify:        {:>8.2}ms total, {:>6.2}ms avg\n\
                 ---\n\
                 CPU TOTAL:     {:>8.2}ms\n\
                 WALL CLOCK:    {:>8.2}ms\n\
                 PARALLELISM:   {:>8.2}x (effective threads)\n\
                 =====================================\n",
                count,
                FORK_TIME.load(Ordering::Relaxed) as f64 / 1000.0,
                FORK_TIME.load(Ordering::Relaxed) as f64 / 1000.0 / count as f64,
                EXEC_TIME.load(Ordering::Relaxed) as f64 / 1000.0,
                EXEC_TIME.load(Ordering::Relaxed) as f64 / 1000.0 / count as f64,
                GRAPH_REBUILD_TIME.load(Ordering::Relaxed) as f64 / 1000.0,
                GRAPH_REBUILD_TIME.load(Ordering::Relaxed) as f64 / 1000.0 / count as f64,
                VERIFY_TIME.load(Ordering::Relaxed) as f64 / 1000.0,
                VERIFY_TIME.load(Ordering::Relaxed) as f64 / 1000.0 / count as f64,
                cpu_total,
                wall_ms,
                parallelism,
            );
            let _ = std::fs::write("/tmp/precheck_timing.txt", &timing);
        }

        result
    }

    /// Get the SuggestService for direct access.
    pub fn suggest_service(&self) -> &SuggestService {
        &self.suggest
    }

    /// Get the SuggestConfig.
    pub fn suggest_config(&self) -> &SuggestConfig {
        &self.suggest_config
    }

    /// Take the suggestion store contents for preservation across reload.
    ///
    /// Returns the current store, leaving an empty store in place.
    pub fn take_suggest_store(&self) -> ryo_suggest::SuggestStore {
        self.suggest.take_store()
    }

    /// Restore suggestion store contents after reload.
    pub fn restore_suggest_store(&self, store: ryo_suggest::SuggestStore) {
        self.suggest.restore_store(store);
    }

    /// Apply suggestions by ID.
    ///
    /// Takes suggestion IDs, generates MutationSpecs, and executes them.
    /// Returns information about which suggestions were successfully applied.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.suggest_apply(SuggestApplyRequest {
    ///     ids: vec!["S001g0".to_string(), "S002g0".to_string()],
    ///     dry_run: false,
    ///     check_syntax: true,
    /// })?;
    ///
    /// if response.success {
    ///     println!("Applied {} suggestions", response.applied_ids.len());
    /// }
    /// ```
    pub fn suggest_apply(
        &mut self,
        request: SuggestApplyRequest,
    ) -> ApiResult<SuggestApplyResponse> {
        let mut response = SuggestApplyResponse::default();
        let mut all_specs = Vec::new();
        let mut valid_ids = Vec::new();

        // Phase 1: Parse IDs and collect MutationSpecs
        for id_str in &request.ids {
            // Parse the suggestion ID
            let suggest_id: SuggestId = match id_str.parse() {
                Ok(id) => id,
                Err(e) => {
                    response
                        .failed
                        .push((id_str.clone(), format!("Invalid ID format: {}", e)));
                    continue;
                }
            };

            // Check if suggestion exists and is valid
            if !self.suggest.is_valid(suggest_id) {
                response.failed.push((
                    id_str.clone(),
                    "Suggestion not found or expired".to_string(),
                ));
                continue;
            }

            // Generate MutationSpecs for this suggestion
            match self.suggest.to_mutation_specs(suggest_id, &self.context) {
                Some(specs) if !specs.is_empty() => {
                    all_specs.extend(specs);
                    valid_ids.push((id_str.clone(), suggest_id));
                }
                Some(_) => {
                    response
                        .failed
                        .push((id_str.clone(), "No mutations generated".to_string()));
                }
                None => {
                    response
                        .failed
                        .push((id_str.clone(), "Failed to generate mutations".to_string()));
                }
            }
        }

        // If no valid specs, return early
        if all_specs.is_empty() {
            if response.failed.is_empty() {
                response.error = Some("No suggestions to apply".to_string());
            }
            return Ok(response);
        }

        // Phase 2: Dry run — execute on forked context, report real changes
        if request.dry_run {
            let mut forked_ctx = self.context.fork_clone();
            let blueprint = ParallelBlueprint::from_mutations(all_specs);
            let executor = BlueprintExecutor::default();
            let exec_result = executor.execute_v2(&blueprint, &mut forked_ctx);

            if !exec_result.success {
                response.error = exec_result.error.clone();
                for (id_str, _) in &valid_ids {
                    response.failed.push((
                        id_str.clone(),
                        exec_result
                            .error
                            .clone()
                            .unwrap_or_else(|| "Execution failed".to_string()),
                    ));
                }
                return Ok(response);
            }

            response.success = true;
            response.total_changes = exec_result.total_changes;
            response.files_modified = exec_result.modified_files.len();
            response.modified_files = exec_result
                .modified_files
                .iter()
                .map(|p| p.to_absolute())
                .collect();
            for (id_str, _) in &valid_ids {
                response.applied_ids.push(id_str.clone());
            }
            return Ok(response);
        }

        // Phase 3: Real apply — execute on self.context
        let blueprint = ParallelBlueprint::from_mutations(all_specs);
        let executor = BlueprintExecutor::default();
        let exec_result = executor.execute_v2(&blueprint, &mut self.context);

        if !exec_result.success {
            response.error = exec_result.error.clone();
            for (id_str, _) in &valid_ids {
                response.failed.push((
                    id_str.clone(),
                    exec_result
                        .error
                        .clone()
                        .unwrap_or_else(|| "Execution failed".to_string()),
                ));
            }
            return Ok(response);
        }

        // Phase 3.5: Sync files and rebuild analysis graphs
        let modified_workspace_paths =
            BlueprintExecutor::sync_files_and_rebuild(&exec_result, &mut self.context)?;

        // Phase 4: Collect results
        response.success = true;
        response.total_changes = exec_result.total_changes;

        // Collect modified files (convert WorkspaceFilePath to PathBuf)
        let modified_files: Vec<PathBuf> = modified_workspace_paths
            .iter()
            .map(|p| p.to_absolute())
            .collect();
        response.files_modified = modified_files.len();
        response.modified_files = modified_files.clone();

        // Mark successfully applied IDs
        for (id_str, _) in &valid_ids {
            response.applied_ids.push(id_str.clone());
        }

        // Phase 5: Write to disk
        // INVARIANT: Only write when actual mutations occurred.
        // total_changes == 0 means no AST was modified → no file should be touched.
        if exec_result.total_changes > 0 {
            for workspace_path in &modified_workspace_paths {
                if let Some(file) = self.context.files.get(workspace_path) {
                    let source = match file.to_source() {
                        Ok(s) => s,
                        Err(e) => {
                            response.syntax_errors.push(format!(
                                "Failed to generate source for {}: {}",
                                workspace_path.to_absolute().display(),
                                e
                            ));
                            continue;
                        }
                    };
                    // Use WorkspaceFilePath::write() to ensure parent dirs are created
                    if let Err(e) = workspace_path.write(&source) {
                        response.syntax_errors.push(format!(
                            "Failed to write {}: {}",
                            workspace_path.to_absolute().display(),
                            e
                        ));
                    }
                }
            }
        }

        // Close the applied suggestions
        for (_, suggest_id) in &valid_ids {
            self.suggest.close(*suggest_id, "Applied via suggest_apply");
        }

        // Phase 5: Syntax check (if requested)
        if request.check_syntax {
            for workspace_path in &modified_workspace_paths {
                if let Some(file) = self.context.files.get(workspace_path) {
                    let source = match file.to_source() {
                        Ok(s) => s,
                        Err(e) => {
                            response.syntax_errors.push(format!(
                                "{}: source generation failed: {}",
                                workspace_path.to_absolute().display(),
                                e
                            ));
                            continue;
                        }
                    };
                    if let Err(e) = syn::parse_file(&source) {
                        let abs_path = workspace_path.to_absolute();
                        response
                            .syntax_errors
                            .push(format!("{}: {}", abs_path.display(), e));
                    }
                }
            }
        }

        Ok(response)
    }

    /// Generate code graph summary.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.graph_summary(GraphSummaryRequest::new())?;
    /// println!("{}", response.content);
    /// ```
    pub fn graph_summary(&self, request: GraphSummaryRequest) -> ApiResult<GraphSummaryResponse> {
        use ryo_analysis::SymbolKind;

        let registry = &self.context.registry;
        let max_items = request.max_items.unwrap_or(50);

        // Collect statistics
        let mut functions = 0usize;
        let mut structs = 0usize;
        let mut enums = 0usize;
        let mut traits = 0usize;
        let mut impls = 0usize;

        for (id, _) in registry.iter() {
            if let Some(kind) = registry.kind(id) {
                match kind {
                    SymbolKind::Function => functions += 1,
                    SymbolKind::Struct => structs += 1,
                    SymbolKind::Enum => enums += 1,
                    SymbolKind::Trait => traits += 1,
                    SymbolKind::Impl => impls += 1,
                    _ => {}
                }
            }
        }

        let node_count = self.context.code_graph.node_count();
        let edge_count = self.context.code_graph.edge_count();
        let file_count = self.context.files.len();

        // Build summary string
        let mut out = String::new();
        out.push_str("=== CodeGraph ===\n");

        if request.detailed {
            out.push_str(&format!("Nodes: {}\n", node_count));
            out.push_str(&format!("Edges: {}\n", edge_count));
            out.push_str(&format!(
                "Types: {} functions, {} structs, {} enums, {} traits, {} impls\n",
                functions, structs, enums, traits, impls
            ));
            out.push_str(&format!("Files: {}\n", file_count));
        } else if !request.compact {
            out.push_str(&format!(
                "Nodes: {}, Edges: {}, Files: {}\n",
                node_count, edge_count, file_count
            ));
        }

        out.push('\n');

        // Functions section
        let fn_iter: Vec<_> = registry
            .iter_by_kind(SymbolKind::Function)
            .take(max_items)
            .collect();
        if !fn_iter.is_empty() {
            out.push_str("[Functions]\n");
            for id in &fn_iter {
                let vis = registry.visibility(*id).map_or("", |v| {
                    if matches!(v, ryo_analysis::Visibility::Public) {
                        "pub "
                    } else {
                        ""
                    }
                });
                let name = registry
                    .resolve(*id)
                    .map(|p| p.name().to_string())
                    .unwrap_or_default();
                if request.compact {
                    out.push_str(&format!("  {}fn {}\n", vis, name));
                } else {
                    out.push_str(&format!("  {}fn {} [{:?}]\n", vis, name, id));
                }
            }
            if functions > max_items {
                out.push_str(&format!("  ... and {} more\n", functions - max_items));
            }
            out.push('\n');
        }

        // Structs section
        let struct_iter: Vec<_> = registry
            .iter_by_kind(SymbolKind::Struct)
            .take(max_items)
            .collect();
        if !struct_iter.is_empty() {
            out.push_str("[Structs]\n");
            for id in &struct_iter {
                let vis = registry.visibility(*id).map_or("", |v| {
                    if matches!(v, ryo_analysis::Visibility::Public) {
                        "pub "
                    } else {
                        ""
                    }
                });
                let name = registry
                    .resolve(*id)
                    .map(|p| p.name().to_string())
                    .unwrap_or_default();
                if request.compact {
                    out.push_str(&format!("  {}struct {}\n", vis, name));
                } else {
                    out.push_str(&format!("  {}struct {} [{:?}]\n", vis, name, id));
                }
            }
            if structs > max_items {
                out.push_str(&format!("  ... and {} more\n", structs - max_items));
            }
            out.push('\n');
        }

        // Enums section
        let enum_iter: Vec<_> = registry
            .iter_by_kind(SymbolKind::Enum)
            .take(max_items)
            .collect();
        if !enum_iter.is_empty() {
            out.push_str("[Enums]\n");
            for id in &enum_iter {
                let vis = registry.visibility(*id).map_or("", |v| {
                    if matches!(v, ryo_analysis::Visibility::Public) {
                        "pub "
                    } else {
                        ""
                    }
                });
                let name = registry
                    .resolve(*id)
                    .map(|p| p.name().to_string())
                    .unwrap_or_default();
                if request.compact {
                    out.push_str(&format!("  {}enum {}\n", vis, name));
                } else {
                    out.push_str(&format!("  {}enum {} [{:?}]\n", vis, name, id));
                }
            }
            out.push('\n');
        }

        // Traits section
        let trait_iter: Vec<_> = registry
            .iter_by_kind(SymbolKind::Trait)
            .take(max_items)
            .collect();
        if !trait_iter.is_empty() {
            out.push_str("[Traits]\n");
            for id in &trait_iter {
                let vis = registry.visibility(*id).map_or("", |v| {
                    if matches!(v, ryo_analysis::Visibility::Public) {
                        "pub "
                    } else {
                        ""
                    }
                });
                let name = registry
                    .resolve(*id)
                    .map(|p| p.name().to_string())
                    .unwrap_or_default();
                if request.compact {
                    out.push_str(&format!("  {}trait {}\n", vis, name));
                } else {
                    out.push_str(&format!("  {}trait {} [{:?}]\n", vis, name, id));
                }
            }
            out.push('\n');
        }

        Ok(GraphSummaryResponse {
            content: out,
            build_time_ms: 0, // Server already has context loaded
            node_count,
            edge_count,
            file_count,
        })
    }

    /// Analyze cascade effects of changing a symbol.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.graph_cascade(CascadeRequest {
    ///     id: "165v1".to_string(),
    ///     uuid: None, // or Some("550e8400-e29b-41d4-a716-446655440000".to_string())
    ///     depth: Some(3),
    /// })?;
    /// ```
    pub fn graph_cascade(&self, request: CascadeRequest) -> ApiResult<CascadeResponse> {
        let _depth = request.depth.unwrap_or(3);

        // Resolve SymbolId (UUID takes precedence over id)
        let symbol_id = self.resolve_symbol_id_required(request.uuid.as_deref(), &request.id)?;

        let symbol_kind = self.context.registry.kind(symbol_id);

        // Get callers from code graph
        let callers: Vec<String> = self
            .context
            .code_graph
            .callers_of(symbol_id)
            .filter_map(|id| {
                self.context
                    .registry
                    .resolve(id)
                    .map(|path| format!("{} [{:?}]", path, id))
            })
            .collect();

        // Get type users (types that reference this symbol, via TypeFlow)
        let users: Vec<String> = self
            .context
            .typeflow_graph
            .type_users(symbol_id)
            .filter_map(|id| {
                self.context
                    .registry
                    .resolve(id)
                    .map(|path| format!("{} [{:?}]", path, id))
            })
            .collect();

        // For enums: scan PureFiles for functions containing match expressions
        // on this enum. The match_expr_index in CodeGraphV2 is not yet populated
        // by the analysis pipeline, so we scan at query time.
        let match_functions: Vec<String> = if symbol_kind == Some(SymbolKind::Enum) {
            let enum_name = self
                .context
                .registry
                .resolve(symbol_id)
                .map(|p| p.name().to_string())
                .unwrap_or_default();
            if enum_name.is_empty() {
                Vec::new()
            } else {
                self.find_match_functions_for_enum(&enum_name)
            }
        } else {
            Vec::new()
        };

        // For types with TypeFlow definitions: find containing types
        let containing_types: Vec<String> = {
            let impact = self.context.typeflow_graph.impact(symbol_id);
            impact
                .containing_types
                .iter()
                .filter_map(|id| {
                    self.context
                        .registry
                        .resolve(*id)
                        .map(|path| format!("{} [{:?}]", path, id))
                })
                .collect()
        };

        let display_name = self
            .context
            .registry
            .resolve(symbol_id)
            .map(|p| p.name().to_string())
            .unwrap_or_else(|| request.id.clone());

        Ok(CascadeResponse {
            display_name,
            callers,
            users,
            match_functions,
            containing_types,
        })
    }

    /// Scan PureFiles for functions/methods that contain match expressions on a given enum.
    fn find_match_functions_for_enum(&self, enum_name: &str) -> Vec<String> {
        use crate::discover::pattern_contains_enum;
        use ryo_source::pure::{PureExpr, PureImplItem, PureItem, PureStmt};

        let mut results = Vec::new();

        for (_path, file) in self.context.files().iter() {
            let wfp = _path;
            let crate_name = wfp.crate_name();
            let resolver = ryo_symbol::SymbolPathResolver::new(crate_name.as_str());
            let mod_path = resolver.module_path_str(wfp);

            for item in &file.items {
                match item {
                    PureItem::Fn(func) if block_has_match_on_enum(&func.body, enum_name) => {
                        let fn_path = format!("{}::{}", mod_path, func.name);
                        results.push(fn_path);
                    }
                    PureItem::Impl(impl_block) => {
                        let type_name = &impl_block.self_ty;
                        for impl_item in &impl_block.items {
                            if let PureImplItem::Fn(func) = impl_item {
                                if block_has_match_on_enum(&func.body, enum_name) {
                                    let fn_path =
                                        format!("{}::{}::{}", mod_path, type_name, func.name);
                                    results.push(fn_path);
                                }
                            }
                        }
                    }
                    _ => {}
                }
            }
        }

        /// Check if a PureBlock contains a match expression on the given enum.
        fn block_has_match_on_enum(block: &ryo_source::pure::PureBlock, enum_name: &str) -> bool {
            for stmt in &block.stmts {
                let expr = match stmt {
                    PureStmt::Expr(e) | PureStmt::Semi(e) => Some(e),
                    PureStmt::Local { init: Some(e), .. } => Some(e),
                    _ => None,
                };
                if let Some(expr) = expr {
                    if expr_has_match_on_enum(expr, enum_name) {
                        return true;
                    }
                }
            }
            false
        }

        /// Recursively check if an expression contains a match on the given enum.
        fn expr_has_match_on_enum(expr: &PureExpr, enum_name: &str) -> bool {
            match expr {
                PureExpr::Match { arms, expr: inner } => {
                    let has_enum = arms
                        .iter()
                        .any(|arm| pattern_contains_enum(&arm.pattern, enum_name));
                    if has_enum {
                        return true;
                    }
                    expr_has_match_on_enum(inner, enum_name)
                }
                PureExpr::Block { block, .. }
                | PureExpr::Unsafe(block)
                | PureExpr::Async { body: block, .. }
                | PureExpr::Loop { body: block, .. } => block_has_match_on_enum(block, enum_name),
                PureExpr::If {
                    cond,
                    then_branch,
                    else_branch,
                } => {
                    expr_has_match_on_enum(cond, enum_name)
                        || block_has_match_on_enum(then_branch, enum_name)
                        || else_branch
                            .as_ref()
                            .is_some_and(|e| expr_has_match_on_enum(e, enum_name))
                }
                _ => false,
            }
        }

        results
    }

    /// Type relationship analysis using TypeFlowGraph.
    ///
    /// Analyzes type definitions → usage relationships with O(1) impact analysis
    /// via inverted index.
    pub fn graph_type(&self, request: TypeAnalysisRequest) -> ApiResult<TypeAnalysisResponse> {
        use types::{TypeAnalysisMode as ApiMode, TypeImpactInfo, TypeUsageInfo};

        // Resolve symbol: UUID > SymbolId > name
        let (symbol_id, display_name) = if let Some(sid) =
            self.resolve_symbol_id(request.uuid.as_deref(), request.id.as_deref(), None)?
        {
            let name = self
                .context
                .registry
                .resolve(sid)
                .map(|p| p.name().to_string())
                .unwrap_or_else(|| format!("{:?}", sid));
            (sid, name)
        } else if let Some(ref name) = request.name {
            let symbol_ids = self.context.registry.find_by_name(name);
            match symbol_ids.len() {
                0 => return Err(ApiError::NotFound(name.clone())),
                1 => (symbol_ids[0], name.clone()),
                _ => {
                    // Multiple symbols with the same name — report all candidates
                    let candidates: Vec<String> = symbol_ids
                        .iter()
                        .filter_map(|&sid| {
                            let path = self.context.registry.resolve(sid)?;
                            let kind = self.context.registry.kind(sid)?;
                            Some(format!("  {} ({:?}) --id {}", path, kind, sid))
                        })
                        .collect();
                    return Err(ApiError::InvalidGoal(format!(
                        "Ambiguous name '{}': {} symbols found. Use --id to specify:\n{}",
                        name,
                        symbol_ids.len(),
                        candidates.join("\n")
                    )));
                }
            }
        } else {
            return Err(ApiError::InvalidGoal(
                "Either 'name', 'id', or 'uuid' must be provided".to_string(),
            ));
        };

        let typeflow = &self.context.typeflow_graph;
        let registry = &self.context.registry;

        // Get basic info (always)
        let mod_path = registry.resolve(symbol_id).map(|p| p.to_string());
        let kind = typeflow.definition(symbol_id).and_then(|def_node| {
            typeflow
                .get_definition(def_node)
                .map(|d| format!("{:?}", d.kind))
        });

        // Usage count (always needed for summary)
        let usage_count = typeflow.usages(symbol_id).count();

        // Collect usages (Usage/Impact modes only)
        let usage_infos: Vec<TypeUsageInfo> = match request.mode {
            ApiMode::Usage | ApiMode::Impact => typeflow
                .usages(symbol_id)
                .take(20)
                .filter_map(|usage_node| {
                    typeflow.get_usage(usage_node).map(|u| TypeUsageInfo {
                        context: format!("{:?}", u.context),
                        ref_kind: format!("{:?}", u.ref_kind),
                        container: u.container.and_then(|cid| {
                            self.context.registry.resolve(cid).map(|p| p.to_string())
                        }),
                    })
                })
                .collect(),
            ApiMode::Definition => Vec::new(),
        };

        // Get impact info (Impact mode only)
        let impact = match request.mode {
            ApiMode::Impact => {
                let impact = typeflow.impact(symbol_id);
                let containing: Vec<String> = impact
                    .containing_types
                    .iter()
                    .take(10)
                    .filter_map(|&id| registry.resolve(id).map(|p| format!("{} [{:?}]", p, id)))
                    .collect();
                Some(TypeImpactInfo {
                    direct_usages: impact.direct_usages.len(),
                    bound_usages: impact.bound_usages.len(),
                    containing_types: containing,
                })
            }
            _ => None,
        };

        // Definition details (Definition mode only)
        let (fields, variants, params, return_type, methods, generics, attrs) = match request.mode {
            ApiMode::Definition => self.collect_definition_details(symbol_id),
            _ => Default::default(),
        };

        // Get supertraits (for traits only, Definition mode)
        let supertraits = match request.mode {
            ApiMode::Definition => self
                .context
                .detail_store
                .trait_(symbol_id)
                .map(|t| t.supertraits.clone())
                .unwrap_or_default(),
            _ => Vec::new(),
        };

        // Get implementors (for traits only, Definition mode)
        let implementors: Vec<String> = match request.mode {
            ApiMode::Definition => self
                .context
                .code_graph
                .implementors_of(symbol_id)
                .take(20)
                .filter_map(|impl_id| {
                    registry
                        .resolve(impl_id)
                        .map(|p| format!("{} [{:?}]", p, impl_id))
                })
                .collect(),
            _ => Vec::new(),
        };

        Ok(TypeAnalysisResponse {
            symbol_id: format!("{:?}", symbol_id),
            display_name,
            mod_path,
            kind,
            usage_count,
            usages: usage_infos,
            impact,
            supertraits,
            implementors,
            fields,
            variants,
            params,
            return_type,
            methods,
            generics,
            attrs,
        })
    }

    /// Collect definition details from DetailStore for Definition mode.
    fn collect_definition_details(&self, symbol_id: ryo_analysis::SymbolId) -> DefinitionDetails {
        let ds = &self.context.detail_store;

        // Struct
        if let Some(detail) = ds.struct_(symbol_id) {
            let fields = detail
                .fields
                .iter()
                .map(|f| types::TypeFieldInfo {
                    name: f.name.clone(),
                    ty: f.ty.clone(),
                    is_public: f.is_public,
                })
                .collect();
            let generics = if detail.generics.is_empty() {
                None
            } else {
                Some(format_generics(&detail.generics))
            };
            return (
                fields,
                Vec::new(),
                Vec::new(),
                None,
                Vec::new(),
                generics,
                detail
                    .attrs
                    .iter()
                    .filter(|a| !a.starts_with("doc"))
                    .cloned()
                    .collect(),
            );
        }

        // Enum
        if let Some(detail) = ds.enum_(symbol_id) {
            let variants = detail
                .variants
                .iter()
                .map(|v| types::TypeVariantInfo {
                    name: v.name.clone(),
                    fields: v
                        .fields
                        .iter()
                        .map(|f| types::TypeFieldInfo {
                            name: f.name.clone(),
                            ty: f.ty.clone(),
                            is_public: f.is_public,
                        })
                        .collect(),
                })
                .collect();
            let generics = if detail.generics.is_empty() {
                None
            } else {
                Some(format_generics(&detail.generics))
            };
            return (
                Vec::new(),
                variants,
                Vec::new(),
                None,
                Vec::new(),
                generics,
                detail
                    .attrs
                    .iter()
                    .filter(|a| !a.starts_with("doc"))
                    .cloned()
                    .collect(),
            );
        }

        // Function/Method
        if let Some(detail) = ds.function(symbol_id) {
            let params = detail
                .params
                .iter()
                .filter(|p| !p.is_self)
                .map(|p| types::TypeParamInfo {
                    name: p.name.clone(),
                    ty: p.ty.clone(),
                })
                .collect();
            let generics = if detail.generics.is_empty() {
                None
            } else {
                Some(format_generics(&detail.generics))
            };
            return (
                Vec::new(),
                Vec::new(),
                params,
                detail.return_type.clone(),
                Vec::new(),
                generics,
                detail
                    .attrs
                    .iter()
                    .filter(|a| !a.starts_with("doc"))
                    .cloned()
                    .collect(),
            );
        }

        // Trait
        if let Some(detail) = ds.trait_(symbol_id) {
            let generics = if detail.generics.is_empty() {
                None
            } else {
                Some(format_generics(&detail.generics))
            };
            return (
                Vec::new(),
                Vec::new(),
                Vec::new(),
                None,
                detail.methods.clone(),
                generics,
                detail
                    .attrs
                    .iter()
                    .filter(|a| !a.starts_with("doc"))
                    .cloned()
                    .collect(),
            );
        }

        Default::default()
    }

    /// Data flow analysis (provenance and impact tracking).
    ///
    /// Tracks data provenance (where values come from) and impact
    /// (where values flow to). Identifies sources and sinks.
    pub fn graph_flow(&self, request: FlowAnalysisRequest) -> ApiResult<FlowAnalysisResponse> {
        use ryo_analysis::VarId;
        use types::{FlowAnalysisMode as ApiMode, VarInfo};

        let dataflow = &self.context.dataflow_graph;
        let registry = &self.context.registry;

        // Helper to convert VarId to VarInfo
        let var_to_info = |var_id: VarId| -> VarInfo {
            let name = dataflow.var_name(var_id).unwrap_or("unknown").to_string();
            let (kind, parent) = dataflow
                .var(var_id)
                .map(|d| {
                    let kind = format!("{:?}", d.kind);
                    let parent = registry
                        .resolve(d.parent)
                        .map(|p| format!("{} ({:?})", p.name(), d.parent))
                        .unwrap_or_else(|| format!("{:?}", d.parent));
                    (kind, parent)
                })
                .unwrap_or_else(|| ("unknown".to_string(), "unknown".to_string()));
            let symbol_path = dataflow
                .var_to_symbol(var_id)
                .and_then(|s| registry.resolve(s))
                .map(|p| p.to_string());
            VarInfo {
                name,
                kind,
                parent,
                symbol_path,
            }
        };

        let symbol_id =
            self.resolve_symbol_id(request.uuid.as_deref(), request.id.as_deref(), None)?;
        let (matching_vars, display_name) = dataflow
            .resolve_vars(symbol_id, request.name.as_deref(), registry)
            .ok_or_else(|| {
                ApiError::InvalidGoal("Either 'name', 'id', or 'uuid' must be provided".to_string())
            })?;

        if matching_vars.is_empty() {
            return Err(self.no_vars_error(request.name.as_deref(), &display_name, registry));
        }

        let found_vars: Vec<VarInfo> = matching_vars
            .iter()
            .take(5)
            .map(|&v| var_to_info(v))
            .collect();

        let mut provenance = Vec::new();
        let mut impact = Vec::new();
        let mut sources = Vec::new();
        let mut sinks = Vec::new();

        match request.mode {
            ApiMode::Provenance | ApiMode::Chain => {
                for &var_id in matching_vars.iter().take(3) {
                    for prov_id in dataflow.provenance(var_id).into_iter().take(5) {
                        provenance.push(var_to_info(prov_id));
                    }
                }
            }
            _ => {}
        }

        match request.mode {
            ApiMode::Impact | ApiMode::Chain => {
                for &var_id in matching_vars.iter().take(3) {
                    for impact_id in dataflow.impact(var_id).into_iter().take(5) {
                        impact.push(var_to_info(impact_id));
                    }
                }
            }
            _ => {}
        }

        if matches!(request.mode, ApiMode::Sources) {
            sources = dataflow
                .iter_vars()
                .filter(|(var_id, _)| dataflow.incoming(*var_id).is_empty())
                .take(20)
                .map(|(var_id, _)| var_to_info(var_id))
                .collect();
        }

        if matches!(request.mode, ApiMode::Sinks) {
            sinks = dataflow
                .iter_vars()
                .filter(|(var_id, _)| dataflow.outgoing(*var_id).is_empty())
                .take(20)
                .map(|(var_id, _)| var_to_info(var_id))
                .collect();
        }

        Ok(FlowAnalysisResponse {
            display_name,
            found_vars,
            provenance,
            impact,
            sources,
            sinks,
        })
    }

    /// Borrow analysis (conflict detection, use-after-move).
    ///
    /// Tracks active borrows and detects potential conflicts or
    /// use-after-move errors.
    pub fn graph_borrow(
        &self,
        request: BorrowAnalysisRequest,
    ) -> ApiResult<BorrowAnalysisResponse> {
        use ryo_analysis::BorrowKind;
        use types::BorrowStatus;

        let dataflow = &self.context.dataflow_graph;
        let registry = &self.context.registry;
        let tracker = dataflow.borrow_tracker();

        let symbol_id =
            self.resolve_symbol_id(request.uuid.as_deref(), request.id.as_deref(), None)?;
        let (matching_vars, display_name) = dataflow
            .resolve_vars(symbol_id, request.name.as_deref(), registry)
            .ok_or_else(|| {
                ApiError::InvalidGoal("Either 'name', 'id', or 'uuid' must be provided".to_string())
            })?;

        if matching_vars.is_empty() {
            return Err(self.no_vars_error(request.name.as_deref(), &display_name, registry));
        }

        let mut statuses = Vec::new();

        for &var_id in matching_vars.iter().take(10) {
            let var_data = dataflow.var(var_id);
            let var_name = dataflow.var_name(var_id).unwrap_or("unknown").to_string();
            let line = var_data.map(|d| d.line).unwrap_or(0);

            let parent_info = var_data
                .and_then(|d| {
                    registry
                        .resolve(d.parent)
                        .map(|p| format!("{} ({:?})", p.name(), d.parent))
                })
                .unwrap_or_default();

            let mut_conflicts = tracker.conflicts(var_id, BorrowKind::Mutable, line);
            let shared_conflicts = tracker.conflicts(var_id, BorrowKind::Shared, line);

            let has_conflict = !mut_conflicts.is_empty() || !shared_conflicts.is_empty();
            let errors: Vec<String> = mut_conflicts
                .iter()
                .chain(shared_conflicts.iter())
                .map(|c| format!("`{}`: {}", var_name, c))
                .collect();

            if !request.conflicts_only || has_conflict {
                statuses.push(BorrowStatus {
                    var_name,
                    line,
                    parent_info,
                    has_conflict,
                    errors,
                });
            }
        }

        Ok(BorrowAnalysisResponse {
            display_name,
            found_count: matching_vars.len(),
            statuses,
        })
    }

    /// Lock analysis (critical sections and optimization).
    ///
    /// Analyzes lock usage patterns, critical section sizes,
    /// and provides optimization suggestions.
    pub fn graph_lock(&self, request: LockAnalysisRequest) -> ApiResult<LockAnalysisResponse> {
        use ryo_analysis::LockGranularityAnalyzerV2;
        use types::{LockAcquisition, LockStats, LockSuggestionInfo};

        let dataflow = &self.context.dataflow_graph;
        let registry = &self.context.registry;
        let tracker = dataflow.lock_tracker();
        let analyzer = LockGranularityAnalyzerV2::new(tracker);

        // Resolve symbol_id and display_name
        let resolved_symbol_id =
            self.resolve_symbol_id(request.uuid.as_deref(), request.id.as_deref(), None)?;

        let display_name = if let Some(symbol_id) = resolved_symbol_id {
            registry
                .resolve(symbol_id)
                .map(|p| p.name().to_string())
                .unwrap_or_else(|| format!("{:?}", symbol_id))
        } else if let Some(ref name) = request.name {
            name.clone()
        } else {
            return Err(ApiError::InvalidGoal(
                "Either 'name', 'id', or 'uuid' must be provided".to_string(),
            ));
        };

        // Get statistics
        let stats_data = analyzer.stats();
        let stats = LockStats {
            total_locks: stats_data.total_locks as u32,
            mutex_count: stats_data.mutex_count as u32,
            rwlock_count: stats_data.rwlock_count as u32,
            refcell_count: stats_data.refcell_count as u32,
            total_field_accesses: stats_data.total_field_accesses as u32,
            max_cs_span: stats_data.max_cs_span,
        };

        // Get acquisitions: --id mode filters by owner function, name mode uses pattern match
        let acquisitions: Vec<LockAcquisition> = if let Some(symbol_id) = resolved_symbol_id {
            tracker
                .acquisitions_by_owner(symbol_id)
                .into_iter()
                .take(10)
                .map(|acq| LockAcquisition {
                    lock_name: acq.lock_name.clone(),
                    lock_type: format!("{:?}", acq.lock_type),
                    line: acq.line,
                })
                .collect()
        } else {
            tracker
                .acquisitions()
                .iter()
                .filter(|acq| matches_lock_pattern_server(acq, &display_name))
                .take(10)
                .map(|acq| LockAcquisition {
                    lock_name: acq.lock_name.clone(),
                    lock_type: format!("{:?}", acq.lock_type),
                    line: acq.line,
                })
                .collect()
        };

        // Get suggestions if requested
        let suggestions = if request.suggest {
            analyzer
                .analyze()
                .into_iter()
                .take(10)
                .map(|s| {
                    use ryo_analysis::LockSuggestion;
                    match s {
                        LockSuggestion::UseAtomic {
                            field,
                            suggested_type,
                            line,
                            ..
                        } => LockSuggestionInfo {
                            kind: "UseAtomic".to_string(),
                            target: field,
                            description: suggested_type,
                            line,
                        },
                        LockSuggestion::SplitLock {
                            lock_name,
                            suggested_splits,
                            line,
                        } => LockSuggestionInfo {
                            kind: "SplitLock".to_string(),
                            target: lock_name,
                            description: format!("Split into {} parts", suggested_splits.len()),
                            line,
                        },
                        LockSuggestion::ReduceScope {
                            guard_name,
                            current_span,
                            ..
                        } => LockSuggestionInfo {
                            kind: "ReduceScope".to_string(),
                            target: guard_name,
                            description: format!("lines {}-{}", current_span.0, current_span.1),
                            line: current_span.0,
                        },
                        LockSuggestion::UseRwLock {
                            lock_name, line, ..
                        } => LockSuggestionInfo {
                            kind: "UseRwLock".to_string(),
                            target: lock_name,
                            description: "Consider RwLock".to_string(),
                            line,
                        },
                        LockSuggestion::LockAcrossAwait {
                            guard_name,
                            lock_line,
                            await_line,
                            ..
                        } => LockSuggestionInfo {
                            kind: "LockAcrossAwait".to_string(),
                            target: guard_name,
                            description: format!("await at line {}", await_line),
                            line: lock_line,
                        },
                        LockSuggestion::RemoveLock {
                            lock_name,
                            reason,
                            line,
                        } => LockSuggestionInfo {
                            kind: "RemoveLock".to_string(),
                            target: lock_name,
                            description: reason,
                            line,
                        },
                    }
                })
                .collect()
        } else {
            Vec::new()
        };

        Ok(LockAnalysisResponse {
            display_name,
            stats,
            acquisitions,
            suggestions,
        })
    }

    /// Transitive call chain traversal.
    ///
    /// Analyzes the transitive closure of call/use relationships up to a specified depth.
    /// Uses BFS for level-order traversal with accurate depth tracking.
    ///
    /// # Directions
    /// - **Callers**: Who calls this function (transitively)?
    /// - **Callees**: What does this function call (transitively)?
    /// - **Users**: What types use this type (transitively)?
    /// - **Uses**: What types does this type use (transitively)?
    pub fn graph_chain(&self, request: ChainAnalysisRequest) -> ApiResult<ChainAnalysisResponse> {
        use ryo_analysis::ChainDirection;
        use std::collections::BTreeMap;

        // Resolve SymbolId (UUID takes precedence over id)
        let symbol_id = self.resolve_symbol_id_required(request.uuid.as_deref(), &request.id)?;

        let max_depth = request.depth.unwrap_or(5);

        // Execute chain analysis — Callers/Callees via CodeGraph, TypeUsers/TypeDeps via TypeFlow
        let result = match request.mode {
            types::ChainMode::Callers => {
                self.context
                    .code_graph
                    .analyze_chain(symbol_id, max_depth, ChainDirection::Callers)
            }
            types::ChainMode::Callees => {
                self.context
                    .code_graph
                    .analyze_chain(symbol_id, max_depth, ChainDirection::Callees)
            }
            types::ChainMode::TypeUsers => self.context.typeflow_graph.analyze_type_chain(
                symbol_id,
                max_depth,
                ChainDirection::TypeUsers,
            ),
            types::ChainMode::TypeDeps => self.context.typeflow_graph.analyze_type_chain(
                symbol_id,
                max_depth,
                ChainDirection::TypeDeps,
            ),
        };

        // Get display name for starting symbol
        let display_name = self
            .context
            .registry
            .resolve(symbol_id)
            .map(|p| p.to_string())
            .unwrap_or_else(|| format!("{:?}", symbol_id));

        // Group nodes by depth with full info
        let mut by_depth: BTreeMap<usize, Vec<types::ChainNodeInfo>> = BTreeMap::new();
        for node in &result.nodes {
            let path = self
                .context
                .registry
                .resolve(node.symbol)
                .map(|p| p.to_string())
                .unwrap_or_default();
            let kind = self
                .context
                .registry
                .kind(node.symbol)
                .map(|k| format!("{:?}", k));

            by_depth
                .entry(node.depth)
                .or_default()
                .push(types::ChainNodeInfo {
                    id: format!("{:?}", node.symbol),
                    path,
                    kind,
                    depth: node.depth,
                });
        }

        Ok(ChainAnalysisResponse {
            display_name,
            direction: result.direction.to_string(),
            total_count: result.nodes.len(),
            max_actual_depth: result.max_actual_depth,
            by_depth,
        })
    }

    /// Get server/context status.
    pub fn status(&self) -> StatusResponse {
        StatusResponse {
            project: self.project.root().to_path_buf(),
            symbols: self.context.registry.len(),
            files: self.context.file_count(),
        }
    }

    /// Query spec hierarchy.
    ///
    /// Uses cached SpecFlowData for efficient repeated queries.
    /// The cache is initialized on first call and invalidated when files change.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.spec(SpecRequest::show())?;
    /// ```
    pub fn spec(&mut self, request: SpecRequest) -> ApiResult<SpecResponse> {
        use crate::spec::{LintSeverity, SpecService, SpecSourceKind};

        // Use cached SpecFlowData (lazy initialized, invalidated on files change)
        if self.spec_cache.is_none() {
            self.spec_cache =
                Some(SpecService::from_context(&self.context).map_err(ApiError::Spec)?);
        }
        let data = self
            .spec_cache
            .as_ref()
            .expect("spec_cache was just initialized to Some above");

        match request.query {
            SpecQueryKind::Show => {
                let show = data.to_show_response();
                Ok(SpecResponse::Show(SpecShowData {
                    groups: show
                        .groups
                        .into_iter()
                        .map(|g| SpecGroupData {
                            name: g.name,
                            specs: g
                                .specs
                                .into_iter()
                                .map(|s| SpecInfoData {
                                    alias_name: s.alias_name,
                                    wrapped_type_name: s.wrapped_type_name,
                                    source: match s.source {
                                        SpecSourceKind::TypeAlias => "type_alias".to_string(),
                                        SpecSourceKind::Comment => "comment".to_string(),
                                        SpecSourceKind::Inferred => "inferred".to_string(),
                                    },
                                })
                                .collect(),
                        })
                        .collect(),
                    relations: show
                        .relations
                        .into_iter()
                        .map(|r| SpecRelationData {
                            from: r.from,
                            to: r.to,
                            kind: format!("{:?}", r.kind).to_lowercase(),
                        })
                        .collect(),
                    stats: SpecStatsData {
                        groups: show.stats.groups,
                        specs: show.stats.specs,
                        nodes: show.stats.nodes,
                        edges: show.stats.edges,
                    },
                }))
            }
            SpecQueryKind::Groups => {
                let groups = data.group_names();
                Ok(SpecResponse::Groups(groups))
            }
            SpecQueryKind::TypesInGroup { group } => {
                let specs = data.specs_in_group(&group);
                Ok(SpecResponse::TypesInGroup(
                    specs
                        .into_iter()
                        .map(|s| SpecInfoData {
                            alias_name: s.alias_name,
                            wrapped_type_name: s.wrapped_type_name,
                            source: match s.source {
                                SpecSourceKind::TypeAlias => "type_alias".to_string(),
                                SpecSourceKind::Comment => "comment".to_string(),
                                SpecSourceKind::Inferred => "inferred".to_string(),
                            },
                        })
                        .collect(),
                ))
            }
            SpecQueryKind::Dependencies { ref type_name } => {
                // 未実装: SpecFlowDataが名前ベースの依存クエリを公開していない
                tracing::warn!(
                    type_name = %type_name,
                    "spec dependencies query is not yet implemented (requires name->SpecNodeId lookup)"
                );
                Ok(SpecResponse::Dependencies(vec![]))
            }
            SpecQueryKind::Dependents { ref type_name } => {
                // 未実装: SpecFlowDataが名前ベースの依存クエリを公開していない
                tracing::warn!(
                    type_name = %type_name,
                    "spec dependents query is not yet implemented (requires name->SpecNodeId lookup)"
                );
                Ok(SpecResponse::Dependents(vec![]))
            }
            SpecQueryKind::Stats => {
                let stats = data.stats();
                Ok(SpecResponse::Stats(SpecStatsData {
                    groups: stats.groups,
                    specs: stats.specs,
                    nodes: stats.nodes,
                    edges: stats.edges,
                }))
            }
            SpecQueryKind::Lint => {
                let lint = data.lint();
                Ok(SpecResponse::Lint(SpecLintData {
                    issues: lint
                        .issues
                        .into_iter()
                        .map(|i| SpecLintIssueData {
                            severity: match i.severity {
                                LintSeverity::Warning => "warning".to_string(),
                                LintSeverity::Error => "error".to_string(),
                            },
                            message: i.message,
                            location: i.location,
                        })
                        .collect(),
                    warnings: lint.warnings,
                    errors: lint.errors,
                }))
            }
            SpecQueryKind::Mermaid => {
                let mermaid = data.to_mermaid();
                Ok(SpecResponse::Mermaid(mermaid))
            }
        }
    }

    // ========================================================================
    // Write Operations
    // ========================================================================

    /// Execute code transformations.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.run(RunRequest {
    ///     goal: Goal::new(Intent::RenameIdent { ... }),
    ///     dry_run: false,
    ///     check_syntax: true,
    /// })?;
    /// ```
    pub fn run(&mut self, request: RunRequest) -> ApiResult<RunResponse> {
        let opts = ExecuteOptions {
            dry_run: request.dry_run,
            check_syntax: request.check_syntax,
        };

        match self.execute_with_options(request.goal, opts) {
            Ok(result) => Ok(RunResponse {
                success: result.success,
                files_modified: result.files_modified,
                total_changes: result.total_changes,
                modified_files: result.modified_files,
                conflicts: result
                    .conflicts
                    .iter()
                    .map(|c| format!("{:?}", c))
                    .collect(),
                syntax_errors: result.syntax_errors,
                error: None,
            }),
            Err(e) => Ok(RunResponse {
                success: false,
                error: Some(e.to_string()),
                ..Default::default()
            }),
        }
    }

    /// Execute a goal with default options.
    ///
    /// This is a convenience wrapper around `execute_with_options` with default settings.
    pub fn execute(&mut self, goal: Goal) -> ApiResult<ExecutionResult> {
        self.execute_with_options(goal, ExecuteOptions::default())
    }

    /// Expand AddVariant intents with cascade effects (AddMatchArm).
    ///
    /// When an AddVariant intent is found, this method searches for match expressions
    /// that use the target enum and generates AddMatchArm intents for each.
    fn expand_add_variant_cascades(&self, mut goal: Goal) -> Goal {
        use crate::discover::find_cascade_effects;
        use crate::intent::Intent;

        let mut cascade_intents = Vec::new();

        for intent in &goal.intents {
            if let Intent::AddVariant {
                target_enum,
                variant_name,
                variant_type,
                ..
            } = intent
            {
                // Find match expressions that need new arms
                let enum_name_str = target_enum.as_deref().unwrap_or("");
                let cascade_result = find_cascade_effects(
                    &self.context.files,
                    enum_name_str,
                    Some(variant_name),
                    Some(variant_type),
                );

                // Convert CascadeSpecs to Intents
                for spec in cascade_result.specs {
                    cascade_intents.push(Intent::from(spec));
                }

                tracing::debug!(
                    "AddVariant cascade: {} AddMatchArm intents generated for {}::{}",
                    cascade_intents.len(),
                    enum_name_str,
                    variant_name
                );
            }
        }

        // Append cascade intents to the goal
        if !cascade_intents.is_empty() {
            goal.intents.extend(cascade_intents);
        }

        goal
    }

    /// Expand RemoveVariant intents with cascade effects (RemoveMatchArm).
    ///
    /// When a RemoveVariant intent is found, this method searches for match expressions
    /// that use the target enum and generates RemoveMatchArm intents for arms referencing
    /// the removed variant.
    fn expand_remove_variant_cascades(&self, mut goal: Goal) -> Goal {
        use crate::discover::find_remove_cascade_effects;
        use crate::intent::Intent;

        let mut cascade_intents = Vec::new();

        for intent in &goal.intents {
            if let Intent::RemoveVariant {
                target_enum,
                variant_name,
                ..
            } = intent
            {
                let enum_name_str = target_enum.as_deref().unwrap_or("");
                let cascade_result =
                    find_remove_cascade_effects(&self.context.files, enum_name_str, variant_name);

                for spec in cascade_result.specs {
                    cascade_intents.push(Intent::from(spec));
                }

                tracing::debug!(
                    "RemoveVariant cascade: {} RemoveMatchArm intents generated for {}::{}",
                    cascade_intents.len(),
                    enum_name_str,
                    variant_name
                );
            }
        }

        if !cascade_intents.is_empty() {
            goal.intents.extend(cascade_intents);
        }

        goal
    }

    /// Validate that `crate::` prefixed parent paths are unambiguous in this workspace.
    ///
    /// In a multi-crate workspace, `crate::xxx` is ambiguous because it's unclear
    /// which crate's `xxx` is being referred to. This validation prevents such
    /// ambiguous paths from being processed.
    ///
    /// # Errors
    ///
    /// Returns `ApiError::Resolve(ResolveError::AmbiguousCratePath)` if an ambiguous
    /// `crate::` path is found in a multi-crate workspace.
    fn validate_workspace_parent_paths(&self, goal: &Goal) -> ApiResult<()> {
        let metadata = self.project.metadata();
        let workspace_type = metadata.workspace_type();

        // Only validate for multi-crate workspaces
        if workspace_type != WorkspaceType::Workspace {
            return Ok(());
        }

        // Get workspace members for error message
        let workspace_root_str = self.project.workspace_root().to_string_lossy();
        let workspace_members: Vec<String> = metadata
            .members()
            .filter_map(|info| {
                // Convert manifest path to relative crate path
                info.manifest_path.parent().map(|p| {
                    p.as_str()
                        .strip_prefix(workspace_root_str.as_ref())
                        .unwrap_or(p.as_str())
                        .trim_start_matches('/')
                        .to_string()
                })
            })
            .filter(|s| !s.is_empty())
            .collect();

        // Check if there are multiple workspace members
        if workspace_members.len() <= 1 {
            return Ok(());
        }

        // Create resolver with workspace type
        let resolver = self.project.path_resolver();

        // Check each intent for ambiguous crate:: paths
        for intent in &goal.intents {
            if let Some(path) = extract_parent_path_string(intent) {
                resolver.validate_crate_path(&path, &workspace_members)?;
            }
        }

        Ok(())
    }

    /// Execute a goal on a project with custom options.
    ///
    /// This is the main entry point for code transformations with full control.
    ///
    /// # Flow
    /// 1. Validate goal confidence
    /// 2. Plan mutations from Intent using Planner
    /// 3. Build ParallelBlueprint from MutationSpecs
    /// 4. Handle conflicts according to ConflictStrategy
    /// 5. Execute via BlueprintExecutor (unless dry_run)
    /// 6. Verify syntax if check_syntax enabled
    /// 7. Record mutations to TxLog
    /// 8. Apply changes back to Project
    ///
    /// # Conflict Handling
    /// - `ConflictStrategy::Fail`: Returns error if conflicts detected
    /// - `ConflictStrategy::IntentOrder`: Clears conflicts, executes in intent order
    /// - `ConflictStrategy::ParallelOnly`: Skips conflicting mutations
    pub fn execute_with_options(
        &mut self,
        goal: Goal,
        options: ExecuteOptions,
    ) -> ApiResult<ExecutionResult> {
        // Validate goal
        if goal.confidence < 0.5 {
            return Err(ApiError::InvalidGoal(format!(
                "Low confidence goal: {}",
                goal.confidence
            )));
        }

        tracing::info!(?goal.intents, ?options, "Executing goal");

        // Validate workspace parent paths before planning
        self.validate_workspace_parent_paths(&goal)?;

        // Expand AddVariant intents with cascade effects (AddMatchArm)
        let goal = self.expand_add_variant_cascades(goal);

        // Expand RemoveVariant intents with cascade effects (RemoveMatchArm)
        let goal = self.expand_remove_variant_cascades(goal);

        // Initialize transaction log
        let mut log = TxLog::with_project(self.project.root().to_string_lossy());

        // 1. Plan mutations from Intent
        // Pass registry to resolve symbol_id to SymbolPath
        let specs = Planner::plan(&goal, Some(self.context.registry()))?;
        tracing::debug!("Planned {} mutation specs", specs.len());

        if specs.is_empty() {
            return Ok(ExecutionResult {
                status: ExecutionStatus::no_change("No mutation specs generated from goal"),
                files_modified: 0,
                total_changes: 0,
                session_id: None,
                log,
                modified_files: vec![],
                conflicts: vec![],
                syntax_errors: vec![],
                success: true,
            });
        }

        // 2. Build ParallelBlueprint
        let mut blueprint = ParallelBlueprint::from_mutations(specs);
        tracing::debug!(
            "Blueprint: {} mutations, {} conflicts",
            blueprint.mutations.len(),
            blueprint.conflicts.len()
        );

        // 3. Handle conflicts according to ConflictStrategy
        let detected_conflicts = blueprint.conflicts.clone();
        if blueprint.needs_escalation() {
            match goal.conflict_strategy {
                ConflictStrategy::Fail => {
                    tracing::warn!(
                        "Conflicts detected with Fail strategy: {} conflicts",
                        detected_conflicts.len()
                    );
                    return Err(ApiError::Conflicts(detected_conflicts.len()));
                }
                ConflictStrategy::IntentOrder => {
                    // Clear conflicts to allow sequential execution in intent order
                    tracing::info!(
                        "Resolving {} conflicts by intent order",
                        detected_conflicts.len()
                    );
                    blueprint.conflicts.clear();
                }
                ConflictStrategy::ParallelOnly => {
                    // Return partial result indicating skipped mutations
                    tracing::warn!(
                        "ParallelOnly strategy: {} mutations skipped due to conflicts",
                        detected_conflicts.len()
                    );
                    let status = ExecutionStatus::conflict(format!(
                        "{} mutations skipped due to conflicts",
                        detected_conflicts.len()
                    ))
                    .with_explanation(
                        "ParallelOnly strategy was used, which skips conflicting mutations.",
                    )
                    .with_suggestion(
                        "Use ConflictStrategy::IntentOrder to resolve conflicts by execution order",
                    );
                    return Ok(ExecutionResult {
                        status,
                        files_modified: 0,
                        total_changes: 0,
                        session_id: None,
                        log,
                        modified_files: vec![],
                        conflicts: detected_conflicts,
                        syntax_errors: vec![],
                        success: false,
                    });
                }
            }
        }

        // 4. If dry_run, return planned result without execution
        if options.dry_run {
            tracing::info!("Dry run: skipping execution");
            let status = ExecutionStatus::ok(format!(
                "{} mutations planned (dry run)",
                blueprint.mutations.len()
            ))
            .with_explanation("Dry run mode: changes were planned but not applied.");
            return Ok(ExecutionResult {
                status,
                files_modified: 0,
                total_changes: blueprint.mutations.len(),
                session_id: None,
                log,
                modified_files: vec![],
                conflicts: detected_conflicts,
                syntax_errors: vec![],
                success: true,
            });
        }

        // 5. Execute via BlueprintExecutor using existing context
        // IMPORTANT: We reuse self.context to maintain SymbolId/FileId validity
        // across Discover → Run sequences. Do NOT create a new context here.
        // Using execute_v2 for ASTRegistry-centric execution path.
        let executor = BlueprintExecutor::new();
        let result = executor.execute_v2(&blueprint, &mut self.context);

        // 6. Invalidate spec_cache since files may have been modified
        // (even on partial failure, some mutations may have succeeded)
        self.spec_cache = None;

        if !result.success {
            return Err(ApiError::Execution(
                result
                    .error
                    .unwrap_or_else(|| "Unknown execution error".to_string()),
            ));
        }

        // 6.5. Sync files and rebuild analysis graphs
        // execute_v2 only updates ASTRegistry - we need to sync files for disk write
        // and rebuild graphs for subsequent operations
        let modified_files = BlueprintExecutor::sync_files_and_rebuild(&result, &mut self.context)?;

        tracing::debug!(
            "sync_files_and_rebuild returned {} modified files",
            modified_files.len()
        );
        if modified_files.is_empty() && result.total_changes > 0 {
            tracing::warn!(
                "sync_files_and_rebuild returned 0 files despite {} total changes - possible bug",
                result.total_changes
            );
        }
        for (i, file) in modified_files.iter().enumerate() {
            tracing::debug!("  Modified file {}: {}", i, file.as_relative().display());
        }

        // 7. Verify syntax if check_syntax enabled
        let syntax_errors = if options.check_syntax {
            let mut errors = Vec::new();
            for file_path in &modified_files {
                if let Some(file) = self.context.file(file_path) {
                    let source = match file.to_source() {
                        Ok(s) => s,
                        Err(e) => {
                            errors.push(format!(
                                "{}: source generation failed: {}",
                                file_path.as_relative().display(),
                                e
                            ));
                            continue;
                        }
                    };
                    let path_str = file_path.as_relative().display().to_string();
                    if let Err(e) = syn::parse_file(&source) {
                        errors.push(format!("{}: {}", path_str, e));
                    }
                }
            }
            errors
        } else {
            vec![]
        };

        // 8. Record mutations to TxLog with affected_symbols
        for spec_result in &result.results {
            if spec_result.success && spec_result.changes > 0 {
                // Get the original MutationSpec from blueprint
                let spec = &blueprint.mutations[spec_result.index];
                let mutation_data = serde_json::to_value(spec).ok();

                // Get first affected file path for logging
                let file_path = spec_result
                    .affected_files
                    .first()
                    .map(|wfp| wfp.to_absolute());
                log.log(TxAction::MutationApplied {
                    mutation_type: spec_result.spec_type.clone(),
                    target: format!("{:?}", spec_result.affected_symbols),
                    changes: spec_result.changes,
                    mutation_data,
                    file_path,
                    pre_state: None,
                    post_state: None,
                    affected_symbols: spec_result.affected_symbols.clone(),
                });
            }
        }

        // 9. Sync changes from Context to Project (for backward compatibility)
        // In the Context-centric design, AnalysisContext is the Single Source of Truth.
        // We sync to Project.files only for code that still reads from it.
        let success = syntax_errors.is_empty();
        if success {
            self.project
                .sync_from_context(&self.context, &modified_files);

            // 10. Apply registry updates to keep SymbolRegistry in sync with AST changes
            // This enables correct symbol resolution after rename operations.
            if !result.registry_updates.is_empty() {
                self.context.commit_changes(&result.registry_updates);
            }

            // 11. Invalidate suggest cache for affected symbols
            for spec_result in &result.results {
                for symbol_path in &spec_result.affected_symbols {
                    if let Some(symbol_id) = self.context.registry().lookup(symbol_path) {
                        self.suggest.invalidate_for_symbol(&symbol_id);
                    }
                }
            }
        }

        // Convert WorkspaceFilePath to PathBuf for result
        let modified_paths: Vec<PathBuf> =
            modified_files.iter().map(|wfp| wfp.to_absolute()).collect();

        tracing::info!(
            "Executed {} changes across {} files (success={})",
            result.total_changes,
            modified_paths.len(),
            success
        );

        // Build status based on outcome
        let status = if !syntax_errors.is_empty() {
            ExecutionStatus::syntax_error(format!(
                "{} syntax errors in {} files",
                syntax_errors.len(),
                modified_paths.len()
            ))
            .with_explanation("Mutations were applied but resulted in invalid Rust syntax.")
            .with_suggestions(syntax_errors.iter().map(|e| format!("Fix: {}", e)))
        } else if result.total_changes == 0 {
            ExecutionStatus::no_change("No changes were made")
                .with_explanation("The goal was processed but no mutations were applied.")
        } else if !detected_conflicts.is_empty() {
            ExecutionStatus::resolved(format!(
                "{} changes ({} conflicts auto-resolved)",
                result.total_changes,
                detected_conflicts.len()
            ))
            .with_explanation("Conflicts were automatically resolved by execution order.")
        } else {
            ExecutionStatus::ok(format!(
                "{} changes in {} files",
                result.total_changes,
                modified_paths.len()
            ))
        };

        Ok(ExecutionResult {
            status,
            files_modified: modified_paths.len(),
            total_changes: result.total_changes,
            session_id: None,
            log,
            modified_files: modified_paths,
            conflicts: detected_conflicts,
            syntax_errors,
            success,
        })
    }

    /// Execute a goal and save the session.
    pub fn execute_and_save(&mut self, goal: Goal) -> ApiResult<ExecutionResult> {
        self.execute_and_save_with_options(goal, ExecuteOptions::default())
    }

    /// Execute a goal with options and save the session.
    pub fn execute_and_save_with_options(
        &mut self,
        goal: Goal,
        options: ExecuteOptions,
    ) -> ApiResult<ExecutionResult> {
        let mut result = self.execute_with_options(goal, options)?;

        // Save session with mutation history
        let session_id = self.storage.save(&result.log)?;
        result.session_id = Some(session_id);

        Ok(result)
    }

    /// List all sessions.
    pub fn list_sessions(&self) -> ApiResult<Vec<String>> {
        Ok(self.storage.list_sessions()?)
    }

    /// Load a session's transaction log.
    pub fn load_session(&self, session_id: &str) -> ApiResult<ryo_storage::TxLog> {
        Ok(self.storage.load(session_id)?)
    }

    /// Get mutable access to storage (for initialization, etc.)
    pub fn storage_mut(&mut self) -> &mut dyn Storage {
        self.storage.as_mut()
    }

    /// Get reference to the analysis context.
    pub fn context(&self) -> &AnalysisContext {
        &self.context
    }

    /// Get reference to the project.
    pub fn project(&self) -> &Project {
        &self.project
    }

    /// Save UUID mappings to disk for persistence across sessions.
    ///
    /// **Callers must explicitly call this method** to persist UUID mappings.
    /// This is NOT called automatically on drop.
    ///
    /// # When to Call
    ///
    /// - **Server mode**: On shutdown RPC and idle timeout (see `RyoServer`)
    /// - **Standalone mode**: At the end of commands that modify symbols
    ///
    /// UUID mappings are saved to `.ryo/uuid-mapping.json` in the workspace root.
    pub fn save_uuid_mappings(&self) -> ApiResult<()> {
        let mappings = self.context.registry.export_uuid_mapping_strings();
        self.uuid_storage
            .save(&mappings)
            .map_err(|e| ApiError::Execution(format!("Failed to save UUID mappings: {}", e)))
    }

    /// Get design choices for a suggestion.
    ///
    /// Returns the available design choices for a suggestion that has multiple
    /// implementation approaches (e.g., different refactoring strategies).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.suggest_choices(SuggestChoicesRequest::new("S001g0"))?;
    /// if response.has_choices {
    ///     for choice in &response.choices {
    ///         println!("{}: {} ({})", choice.label, choice.title, choice.description);
    ///     }
    /// }
    /// ```
    pub fn suggest_choices(
        &self,
        request: SuggestChoicesRequest,
    ) -> ApiResult<SuggestChoicesResponse> {
        // Parse the suggestion ID
        let suggest_id: SuggestId = request
            .id
            .parse()
            .map_err(|e| ApiError::InvalidGoal(format!("Invalid ID format: {}", e)))?;

        // Check if suggestion exists
        if !self.suggest.is_valid(suggest_id) {
            return Ok(SuggestChoicesResponse {
                suggestion_id: request.id,
                error: Some("Suggestion not found or expired".to_string()),
                ..Default::default()
            });
        }

        // Get pattern name
        let pattern_name = self
            .suggest
            .pattern_name(suggest_id)
            .unwrap_or("Unknown")
            .to_string();

        // Get design choices from enhanced suggestion if available
        let stored = self.suggest.get(suggest_id);
        if stored.is_none() {
            return Ok(SuggestChoicesResponse {
                suggestion_id: request.id,
                pattern_name,
                error: Some("Suggestion data not available".to_string()),
                ..Default::default()
            });
        }

        // TODO: Currently design choices are not populated at scan time.
        // Return empty choices with has_choices = false for now.
        // Future: implement design choice generation in pattern detection.
        Ok(SuggestChoicesResponse {
            suggestion_id: request.id,
            pattern_name,
            choices: Vec::new(),
            has_choices: false,
            error: None,
        })
    }

    /// Verify a suggestion before applying.
    ///
    /// Runs verification checks on a suggestion to ensure it can be safely applied.
    /// Supports two verification levels:
    /// - Light: Fast in-memory graph check
    /// - Full: Cargo check in temporary workspace
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.suggest_verify(SuggestVerifyRequest::new("S001g0").level(VerifyLevel::Full))?;
    /// if response.passed {
    ///     println!("Verification passed in {}ms", response.duration_ms);
    /// } else {
    ///     for diag in &response.diagnostics {
    ///         println!("  {}", diag);
    ///     }
    /// }
    /// ```
    pub fn suggest_verify(
        &self,
        request: SuggestVerifyRequest,
    ) -> ApiResult<SuggestVerifyResponse> {
        let start = Instant::now();

        // Parse the suggestion ID
        let suggest_id: SuggestId = request
            .id
            .parse()
            .map_err(|e| ApiError::InvalidGoal(format!("Invalid ID format: {}", e)))?;

        // Check if suggestion exists
        if !self.suggest.is_valid(suggest_id) {
            return Ok(SuggestVerifyResponse {
                suggestion_id: request.id,
                choice_id: request.choice_id,
                passed: false,
                level: format!("{:?}", request.level),
                duration_ms: start.elapsed().as_millis() as u64,
                diagnostics: vec!["Suggestion not found or expired".to_string()],
                error: Some("Suggestion not found or expired".to_string()),
            });
        }

        // Get mutation specs for this suggestion
        let specs = match self.suggest.to_mutation_specs(suggest_id, &self.context) {
            Some(specs) if !specs.is_empty() => specs,
            _ => {
                return Ok(SuggestVerifyResponse {
                    suggestion_id: request.id,
                    choice_id: request.choice_id,
                    passed: false,
                    level: format!("{:?}", request.level),
                    duration_ms: start.elapsed().as_millis() as u64,
                    diagnostics: vec!["No mutations could be generated".to_string()],
                    error: Some("No mutations could be generated".to_string()),
                });
            }
        };

        // Perform verification based on level
        let (passed, diagnostics) = match request.level {
            VerifyLevel::Light => {
                // Light verification: apply mutations speculatively and run graph check
                self.verify_with_graph_check(&specs)
            }
            VerifyLevel::Full => {
                // Full verification: apply mutations speculatively and run cargo check
                self.verify_with_cargo_check(&specs)
            }
        };

        Ok(SuggestVerifyResponse {
            suggestion_id: request.id,
            choice_id: request.choice_id,
            passed,
            level: format!("{:?}", request.level),
            duration_ms: start.elapsed().as_millis() as u64,
            diagnostics,
            error: None,
        })
    }

    /// Verify mutations with cargo check in a temporary workspace.
    ///
    /// This method:
    /// 1. Clones the analysis context
    /// 2. Applies mutations speculatively
    /// 3. Creates file changes from the diff
    /// 4. Runs cargo check in a temp workspace
    fn verify_with_cargo_check(&self, specs: &[ryo_executor::MutationSpec]) -> (bool, Vec<String>) {
        use ryo_symbol::WorkspacePathResolver;
        use std::collections::HashMap;

        // 1. Clone context for speculative execution (O(clone) not O(rebuild))
        let mut forked_ctx = self.context.fork_clone();
        let original_files = self.context.files.clone();

        // 2. Apply mutations speculatively
        let blueprint = ParallelBlueprint::from_mutations(specs.to_vec());
        let executor = BlueprintExecutor::default();
        let exec_result = executor.execute_v2(&blueprint, &mut forked_ctx);

        if !exec_result.success {
            return (
                false,
                vec![format!(
                    "Mutation execution failed: {}",
                    exec_result
                        .error
                        .unwrap_or_else(|| "Unknown error".to_string())
                )],
            );
        }

        // 3. No-op check via BlueprintResult (AST-level, no sync needed)
        if exec_result.total_changes == 0 {
            return (
                true,
                vec!["No file changes detected (no-op mutation)".to_string()],
            );
        }

        // 4. Sync files from AST for subsequent verification
        let original_sources: HashMap<_, _> = HashMap::new();
        if let Err(e) = BlueprintExecutor::sync_files_and_rebuild(&exec_result, &mut forked_ctx) {
            return (false, vec![format!("File sync failed: {}", e)]);
        }
        let changes = match FileChange::from_execution_diff(
            &original_files,
            &forked_ctx.files,
            &original_sources,
        ) {
            Ok(c) => c,
            Err(e) => return (false, vec![format!("Source generation failed: {}", e)]),
        };

        // 5. Create verification input
        let resolver = WorkspacePathResolver::new(self.context.workspace_root().to_path_buf());
        let input = VerificationInput::new(changes.clone(), resolver);

        // 6. Run verification pipeline with cargo check
        let pipeline = VerificationPipeline::new().add_filesystem(CargoVerifier::new());

        match pipeline.run_postcheck(&input) {
            Ok(result) => {
                let passed = result.pipeline_result.is_success();
                let mut diagnostics = vec![format!(
                    "{} file(s) changed, cargo check {}",
                    changes.len(),
                    if passed { "passed" } else { "failed" }
                )];

                // Add any error diagnostics
                for diag in result.pipeline_result.all_diagnostics() {
                    diagnostics.push(format!("  {:?}: {}", diag.level, diag.message));
                }

                (passed, diagnostics)
            }
            Err(e) => (false, vec![format!("Verification failed: {}", e)]),
        }
    }

    /// Verify mutations with GraphVerifier (in-memory check).
    ///
    /// This method:
    /// 1. Clones the analysis context
    /// 2. Applies mutations speculatively
    /// 3. Creates file changes from the diff
    /// 4. Runs GraphVerifier for fast in-memory validation
    fn verify_with_graph_check(&self, specs: &[ryo_executor::MutationSpec]) -> (bool, Vec<String>) {
        use ryo_symbol::WorkspacePathResolver;
        use std::collections::HashMap;

        // 1. Clone context for speculative execution (O(clone) not O(rebuild))
        let mut forked_ctx = self.context.fork_clone();
        let original_files = self.context.files.clone();

        // 2. Apply mutations speculatively
        let blueprint = ParallelBlueprint::from_mutations(specs.to_vec());
        let executor = BlueprintExecutor::default();
        let exec_result = executor.execute_v2(&blueprint, &mut forked_ctx);

        if !exec_result.success {
            return (
                false,
                vec![format!(
                    "Mutation execution failed: {}",
                    exec_result
                        .error
                        .unwrap_or_else(|| "Unknown error".to_string())
                )],
            );
        }

        // 3. No-op check via BlueprintResult (AST-level, no sync needed)
        if exec_result.total_changes == 0 {
            return (
                true,
                vec!["No file changes detected (no-op mutation)".to_string()],
            );
        }

        // 4. Sync files from AST for subsequent verification
        let original_sources: HashMap<_, _> = HashMap::new();
        if let Err(e) = BlueprintExecutor::sync_files_and_rebuild(&exec_result, &mut forked_ctx) {
            return (false, vec![format!("File sync failed: {}", e)]);
        }
        let changes = match FileChange::from_execution_diff(
            &original_files,
            &forked_ctx.files,
            &original_sources,
        ) {
            Ok(c) => c,
            Err(e) => return (false, vec![format!("Source generation failed: {}", e)]),
        };

        // 5. Create verification input
        let resolver = WorkspacePathResolver::new(self.context.workspace_root().to_path_buf());
        let input = VerificationInput::new(changes.clone(), resolver);

        // 6. Run GraphVerifier for in-memory validation
        let verifier = GraphVerifier::new();
        let result = verifier.verify_in_memory(&input, &forked_ctx);

        let passed = result.is_success();
        let mut diagnostics = vec![format!(
            "{} file(s) changed, graph check {} ({:.2}ms)",
            changes.len(),
            if passed { "passed" } else { "failed" },
            result.duration.as_secs_f64() * 1000.0
        )];

        // Add any error diagnostics
        for diag in &result.diagnostics {
            diagnostics.push(format!("  {:?}: {}", diag.level, diag.message));
        }

        (passed, diagnostics)
    }

    /// Compare design choices for a suggestion.
    ///
    /// Generates a comparison table showing trade-offs between different
    /// implementation approaches for a suggestion.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = api.suggest_compare(SuggestCompareRequest::new("S001g0"))?;
    /// println!("{}", response.comparison_table);
    /// for choice in &response.ranked_choices {
    ///     println!("{}: {}", choice.label, choice.title);
    /// }
    /// ```
    pub fn suggest_compare(
        &self,
        request: SuggestCompareRequest,
    ) -> ApiResult<SuggestCompareResponse> {
        // Parse the suggestion ID
        let suggest_id: SuggestId = request
            .id
            .parse()
            .map_err(|e| ApiError::InvalidGoal(format!("Invalid ID format: {}", e)))?;

        // Check if suggestion exists
        if !self.suggest.is_valid(suggest_id) {
            return Ok(SuggestCompareResponse {
                suggestion_id: request.id,
                error: Some("Suggestion not found or expired".to_string()),
                ..Default::default()
            });
        }

        // Get pattern name
        let pattern_name = self
            .suggest
            .pattern_name(suggest_id)
            .unwrap_or("Unknown")
            .to_string();

        // TODO: Currently design choices are not populated at scan time.
        // Return empty comparison for now.
        let comparison_table = format!(
            "Suggestion: {}\nPattern: {}\n\nNo design choices available for comparison.\n",
            request.id, pattern_name
        );

        Ok(SuggestCompareResponse {
            suggestion_id: request.id,
            comparison_table,
            ranked_choices: Vec::new(),
            recommendation_reason: None,
            error: None,
        })
    }

    /// Generate code from parameterized patterns.
    ///
    /// This method supports two modes:
    /// 1. **List mode** (`list: true`): Returns available parameterized patterns
    /// 2. **Generate mode**: Creates code from a pattern with parameters
    ///
    /// # Example
    ///
    /// ```ignore
    /// // List available patterns
    /// let list_req = SuggestGenerateRequest::list_patterns();
    /// let patterns = api.suggest_generate(list_req)?;
    ///
    /// // Generate OrderAPI
    /// let gen_req = SuggestGenerateRequest::generate("api-pattern")
    ///     .with_param("name", "Order");
    /// let result = api.suggest_generate(gen_req)?;
    /// ```
    pub fn suggest_generate(
        &self,
        request: SuggestGenerateRequest,
    ) -> ApiResult<SuggestGenerateResponse> {
        use crate::api::types::{ParamInfo, PatternInfo};

        // Mode 1: List available patterns
        if request.list {
            // From SuggestService (parameterized Suggests)
            let mut patterns: Vec<PatternInfo> = self
                .suggest
                .list_parameterized()
                .into_iter()
                .map(|info| PatternInfo {
                    name: info.name.to_string(),
                    description: info.description,
                    category: format!("{:?}", info.category),
                    params: info
                        .param_schema
                        .into_iter()
                        .map(|p| ParamInfo {
                            name: p.name,
                            description: p.description,
                            required: p.required,
                        })
                        .collect(),
                })
                .collect();

            // From GeneratorStore (YAML templates)
            for entry in self.generator_store.all_generators() {
                patterns.push(PatternInfo {
                    name: entry.template.name().to_string(),
                    description: entry.template.description().to_string(),
                    category: entry.template.category().unwrap_or("generator").to_string(),
                    params: entry
                        .template
                        .params
                        .iter()
                        .map(|p| ParamInfo {
                            name: p.name.clone(),
                            description: p.description.clone(),
                            required: p.required,
                        })
                        .collect(),
                });
            }

            return Ok(SuggestGenerateResponse {
                patterns,
                ..Default::default()
            });
        }

        // Mode 2: Generate from pattern
        let pattern = match &request.pattern {
            Some(p) => p,
            None => {
                return Ok(SuggestGenerateResponse {
                    error: Some(
                        "Pattern name required. Use --list to see available patterns.".to_string(),
                    ),
                    ..Default::default()
                });
            }
        };

        // Try SuggestService first
        if let Some(opps) =
            self.suggest
                .generate_with_params(&self.context, pattern, &request.params)
        {
            if !opps.is_empty() {
                return self.generate_from_suggest_service(pattern, opps, &request);
            }
        }

        // Try GeneratorStore (YAML templates)
        if let Some(entry) = self.generator_store.find_by_name(pattern) {
            return self.generate_from_template(entry, &request);
        }

        // Also try by ID
        if let Some(entry) = self.generator_store.find_by_id(pattern) {
            return self.generate_from_template(entry, &request);
        }

        Ok(SuggestGenerateResponse {
            error: Some(format!(
                "Pattern '{}' not found. Use --list to see available patterns.",
                pattern
            )),
            ..Default::default()
        })
    }

    /// Generate from SuggestService parameterized suggest
    fn generate_from_suggest_service(
        &self,
        pattern: &str,
        opportunities: Vec<ryo_suggest::SuggestOpportunity>,
        request: &SuggestGenerateRequest,
    ) -> ApiResult<SuggestGenerateResponse> {
        // Convert to Suggestion type for response
        let suggestions: Vec<Suggestion> = opportunities
            .iter()
            .enumerate()
            .map(|(i, opp)| Suggestion {
                id: format!("GEN{:03}", i),
                rule_id: None,
                title: format!("Generate {}", pattern),
                description: opp.message.clone(),
                category: "Generation".to_string(),
                impact: "medium".to_string(),
                file: std::path::PathBuf::from(&opp.location.file),
                symbol_path: Some(opp.location.symbol_path.to_string()),
                fix_intent: None,
            })
            .collect();

        // Generate preview
        let preview = if !request.apply {
            let mut preview_text = String::new();
            for opp in &opportunities {
                if let Some((_, suggest)) = self.suggest.registry().get_by_name(pattern) {
                    if let Ok(specs) = suggest.to_mutation_specs(&self.context, opp) {
                        for spec in specs {
                            preview_text.push_str(&format!("{:?}\n", spec));
                        }
                    }
                }
            }
            Some(preview_text)
        } else {
            None
        };

        // Apply if requested
        let (applied, files_modified) = if request.apply && !request.dry_run {
            // TODO: Actually apply the mutations
            (false, 0)
        } else {
            (false, 0)
        };

        Ok(SuggestGenerateResponse {
            suggestions,
            preview,
            applied,
            files_modified,
            ..Default::default()
        })
    }

    /// Generate from GeneratorStore YAML template
    fn generate_from_template(
        &self,
        entry: &ryo_suggest::GeneratorEntry,
        request: &SuggestGenerateRequest,
    ) -> ApiResult<SuggestGenerateResponse> {
        let template = &entry.template;

        // Validate and render
        let rendered = match template.render(&request.params) {
            Ok(code) => code,
            Err(e) => {
                return Ok(SuggestGenerateResponse {
                    error: Some(format!("Template render error: {}", e)),
                    ..Default::default()
                });
            }
        };

        let target_file = template.render_target_file(&request.params);

        // Create suggestion
        let suggestions = vec![Suggestion {
            id: format!("GEN-{}", template.id()),
            rule_id: Some(template.id().to_string()),
            title: format!("Generate {}", template.name()),
            description: template.description().to_string(),
            category: template.category().unwrap_or("generator").to_string(),
            impact: "medium".to_string(),
            file: std::path::PathBuf::from(&target_file),
            symbol_path: None, // Generator creates new code, no existing symbol
            fix_intent: None,
        }];

        // Preview shows the rendered code
        let preview = if !request.apply {
            Some(format!(
                "// Target: {}\n// Position: {:?}\n\n{}",
                target_file, template.template.position, rendered
            ))
        } else {
            None
        };

        // Apply if requested
        let (applied, files_modified) = if request.apply && !request.dry_run {
            // TODO: Actually write the file
            // For now, just return false
            (false, 0)
        } else {
            (false, 0)
        };

        Ok(SuggestGenerateResponse {
            suggestions,
            preview,
            applied,
            files_modified,
            ..Default::default()
        })
    }
}

/// Match a lock acquisition against a search pattern.
///
/// Supports wildcards (`*`), lock type names (`Mutex`, `RwLock`), and substring match.
fn matches_lock_pattern_server(acq: &ryo_analysis::LockAcquisitionV2, pattern: &str) -> bool {
    if pattern.is_empty() || pattern == "*" {
        return true;
    }

    let pattern_lower = pattern.to_lowercase();

    // Check lock type name match
    let type_name = format!("{:?}", acq.lock_type).to_lowercase();
    if type_name == pattern_lower || type_name.contains(&pattern_lower) {
        return true;
    }

    let name_lower = acq.lock_name.to_lowercase();

    // Glob-style matching
    if pattern_lower.starts_with('*') && pattern_lower.ends_with('*') && pattern_lower.len() > 1 {
        let middle = &pattern_lower[1..pattern_lower.len() - 1];
        if middle.is_empty() {
            return true;
        }
        name_lower.contains(middle)
    } else if let Some(stripped) = pattern_lower.strip_prefix('*') {
        name_lower.ends_with(stripped)
    } else if pattern_lower.ends_with('*') {
        name_lower.starts_with(&pattern_lower[..pattern_lower.len() - 1])
    } else {
        name_lower.contains(&pattern_lower)
    }
}

// ============================================================================
// Post-Execution Hook
// ============================================================================

/// Result of a post-execution hook.
#[derive(Debug, Clone)]
pub enum HookResult {
    /// Hook completed successfully.
    Success,
    /// Hook completed with a warning.
    Warning(String),
    /// Hook failed with an error.
    Error(String),
}

impl HookResult {
    /// Check if the hook was successful.
    pub fn is_success(&self) -> bool {
        matches!(self, HookResult::Success)
    }

    /// Check if the hook had an error.
    pub fn is_error(&self) -> bool {
        matches!(self, HookResult::Error(_))
    }
}

/// Trait for post-execution hooks.
///
/// Hooks are called after mutation execution completes. They can perform
/// additional validation, external tool invocation, or other side effects.
///
/// # Example
///
/// ```ignore
/// use ryo_app::{PostExecutionHook, ExecutionResult, HookResult};
/// use std::path::Path;
///
/// struct CargoCheckHook;
///
/// impl PostExecutionHook for CargoCheckHook {
///     fn name(&self) -> &str {
///         "cargo-check"
///     }
///
///     fn run(&self, result: &ExecutionResult, project_path: &Path) -> HookResult {
///         // Run cargo check...
///         HookResult::Success
///     }
/// }
/// ```
pub trait PostExecutionHook: Send + Sync {
    /// Hook name for logging/display.
    fn name(&self) -> &str;

    /// Run the hook after execution.
    ///
    /// # Arguments
    /// * `result` - The execution result from Api
    /// * `project_path` - Path to the project root
    ///
    /// # Returns
    /// * `HookResult` indicating success, warning, or error
    fn run(&self, result: &ExecutionResult, project_path: &Path) -> HookResult;

    /// Whether to run this hook on dry-run executions.
    /// Default is false (skip on dry-run).
    fn run_on_dry_run(&self) -> bool {
        false
    }

    /// Whether to run this hook when execution had syntax errors.
    /// Default is false (skip on syntax errors).
    fn run_on_syntax_error(&self) -> bool {
        false
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::intent::{ConflictStrategy, Goal, IdentKind, Intent, ScopeHint, StmtInsertPosition};
    use std::fs;
    use tempfile::tempdir;

    /// Create a test project
    fn create_test_project() -> (tempfile::TempDir, Project) {
        let dir = tempdir().unwrap();
        let src = dir.path().join("src");
        fs::create_dir(&src).unwrap();

        // Create Cargo.toml (required for CargoMetadataProvider)
        fs::write(
            dir.path().join("Cargo.toml"),
            r#"[package]
name = "test-project"
version = "0.1.0"
edition = "2021"
"#,
        )
        .unwrap();

        fs::write(
            src.join("lib.rs"),
            r#"
pub fn old_name() -> i32 {
    42
}

pub struct OldStruct {
    pub value: i32,
}
"#,
        )
        .unwrap();

        let project = Project::load(dir.path()).unwrap();
        (dir, project)
    }

    // ------------------------------------------------------------------------
    // Api Construction Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_api_new() {
        let (dir, _project) = create_test_project();
        let _api = Api::from_path(dir.path()).unwrap();
        // Just verify no panic
    }

    #[test]
    fn test_api_from_path() {
        let (dir, _project) = create_test_project();
        let api = Api::from_path(dir.path()).unwrap();
        assert!(!api.context.registry().is_empty());
    }

    #[test]
    fn test_storage_mut() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();
        let _storage = api.storage_mut();
        // Just verify access works
    }

    // ------------------------------------------------------------------------
    // ExecuteOptions Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_execute_options_default() {
        let opts = ExecuteOptions::default();
        assert!(!opts.dry_run);
        assert!(!opts.check_syntax);
    }

    #[test]
    fn test_execute_options_new() {
        let opts = ExecuteOptions::new();
        assert!(!opts.dry_run);
        assert!(!opts.check_syntax);
    }

    #[test]
    fn test_execute_options_dry_run() {
        let opts = ExecuteOptions::new().dry_run();
        assert!(opts.dry_run);
        assert!(!opts.check_syntax);
    }

    #[test]
    fn test_execute_options_check_syntax() {
        let opts = ExecuteOptions::new().check_syntax();
        assert!(!opts.dry_run);
        assert!(opts.check_syntax);
    }

    #[test]
    fn test_execute_options_chained() {
        let opts = ExecuteOptions::new().dry_run().check_syntax();
        assert!(opts.dry_run);
        assert!(opts.check_syntax);
    }

    // ------------------------------------------------------------------------
    // Discover Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_discover_all() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let response = api
            .discover(DiscoverRequest {
                pattern: "*".to_string(),
                ..Default::default()
            })
            .unwrap();

        assert!(response.total > 0);
    }

    #[test]
    fn test_discover_with_pattern() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let response = api
            .discover(DiscoverRequest {
                pattern: "Old*".to_string(),
                ..Default::default()
            })
            .unwrap();

        // Should find OldStruct and old_name
        assert!(response.symbols.iter().any(|s| s.name.starts_with("Old")));
    }

    // ------------------------------------------------------------------------
    // Status Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_status() {
        let (dir, _project) = create_test_project();
        let api = Api::from_path(dir.path()).unwrap();

        let status = api.status();
        assert!(status.files > 0);
        assert!(status.symbols > 0);
    }

    // ------------------------------------------------------------------------
    // Goal Validation Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_execute_low_confidence_goal() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "rename old_name to new_name",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("old_name".to_string()),
                to: "new_name".to_string(),
                kind: IdentKind::Any,
            },
        )
        .with_confidence(0.3); // Low confidence

        let result = api.execute(goal);
        assert!(result.is_err());
        assert!(matches!(result.unwrap_err(), ApiError::InvalidGoal(_)));
    }

    // ------------------------------------------------------------------------
    // Empty Goal Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_execute_empty_intents() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Goal with no intents
        let goal = Goal {
            query: String::new(),
            intents: vec![],
            scope: ScopeHint::default(),
            constraints: vec![],
            confidence: 1.0,
            conflict_strategy: ConflictStrategy::Fail,
        };

        let result = api.execute(goal).unwrap();
        assert!(result.success);
        assert_eq!(result.files_modified, 0);
        assert_eq!(result.total_changes, 0);
    }

    // ------------------------------------------------------------------------
    // Dry Run Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_execute_dry_run() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "rename old_name to new_name",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("old_name".to_string()),
                to: "new_name".to_string(),
                kind: IdentKind::Any,
            },
        );

        let opts = ExecuteOptions::new().dry_run();
        let result = api.execute_with_options(goal, opts).unwrap();

        assert!(result.success);
        // Dry run doesn't modify files
        assert_eq!(result.files_modified, 0);
    }

    // ------------------------------------------------------------------------
    // Run API Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_run_api() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "rename old_name to new_name",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("old_name".to_string()),
                to: "new_name".to_string(),
                kind: IdentKind::Any,
            },
        );

        let response = api
            .run(RunRequest {
                goal,
                dry_run: true,
                check_syntax: false,
            })
            .unwrap();

        assert!(response.success);
    }

    // ------------------------------------------------------------------------
    // Session Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_list_sessions_empty() {
        let (dir, _project) = create_test_project();
        let api = Api::from_path(dir.path()).unwrap();

        let sessions = api.list_sessions().unwrap();
        assert!(sessions.is_empty());
    }

    #[test]
    fn test_execute_and_save() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Empty goal for simple test
        let goal = Goal {
            query: String::new(),
            intents: vec![],
            scope: ScopeHint::default(),
            constraints: vec![],
            confidence: 1.0,
            conflict_strategy: ConflictStrategy::Fail,
        };

        let result = api.execute_and_save(goal).unwrap();
        assert!(result.session_id.is_some());

        let sessions = api.list_sessions().unwrap();
        assert_eq!(sessions.len(), 1);
    }

    #[test]
    fn test_load_session() {
        let (dir, _project) = create_test_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal {
            query: String::new(),
            intents: vec![],
            scope: ScopeHint::default(),
            constraints: vec![],
            confidence: 1.0,
            conflict_strategy: ConflictStrategy::Fail,
        };

        let result = api.execute_and_save(goal).unwrap();
        let session_id = result.session_id.unwrap();

        let log = api.load_session(&session_id).unwrap();
        let _ = log.entries().len(); // verify log is accessible
    }

    // ------------------------------------------------------------------------
    // HookResult Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_hook_result_success() {
        let result = HookResult::Success;
        assert!(result.is_success());
        assert!(!result.is_error());
    }

    #[test]
    fn test_hook_result_warning() {
        let result = HookResult::Warning("test warning".to_string());
        assert!(!result.is_success());
        assert!(!result.is_error());
    }

    #[test]
    fn test_hook_result_error() {
        let result = HookResult::Error("test error".to_string());
        assert!(!result.is_success());
        assert!(result.is_error());
    }

    // ------------------------------------------------------------------------
    // ApiError Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_api_error_display() {
        let err = ApiError::InvalidGoal("test".to_string());
        assert!(err.to_string().contains("Invalid goal"));

        let err = ApiError::Conflicts(3);
        assert!(err.to_string().contains("3 conflicts"));

        let err = ApiError::SyntaxError("parse failed".to_string());
        assert!(err.to_string().contains("Syntax error"));
    }

    // ------------------------------------------------------------------------
    // ExecutionResult Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_execution_result_fields() {
        let result = ExecutionResult {
            status: ExecutionStatus::ok("5 changes in 2 files"),
            files_modified: 2,
            total_changes: 5,
            session_id: Some("test-session".to_string()),
            log: TxLog::new(),
            modified_files: vec![PathBuf::from("file1.rs"), PathBuf::from("file2.rs")],
            conflicts: vec![],
            syntax_errors: vec![],
            success: true,
        };

        assert_eq!(result.files_modified, 2);
        assert_eq!(result.total_changes, 5);
        assert!(result.success);
        assert!(result.status.is_success());
        assert_eq!(result.modified_files.len(), 2);
    }

    #[test]
    fn test_execution_status_codes() {
        // Success statuses
        assert!(StatusCode::Ok.is_success());
        assert!(StatusCode::NoChange.is_success());
        assert!(StatusCode::Resolved.is_success());

        // Error statuses
        assert!(StatusCode::Invalid.is_error());
        assert!(StatusCode::NotFound.is_error());
        assert!(StatusCode::Conflict.is_error());
        assert!(StatusCode::SyntaxError.is_error());

        // HTTP codes
        assert_eq!(StatusCode::Ok.as_http_code(), 200);
        assert_eq!(StatusCode::NoChange.as_http_code(), 204);
        assert_eq!(StatusCode::Conflict.as_http_code(), 409);
    }

    #[test]
    fn test_execution_status_builder() {
        let status = ExecutionStatus::ok("3 changes")
            .with_explanation("Renamed foo to bar")
            .with_suggestion("Run tests to verify");

        assert!(status.is_success());
        assert_eq!(status.detail.reason, "3 changes");
        assert!(status.detail.explanation.is_some());
        assert_eq!(status.detail.suggestions.len(), 1);
    }

    // ------------------------------------------------------------------------
    // Context Lifecycle Integration Tests
    // ------------------------------------------------------------------------
    //
    // These tests verify that AnalysisContext maintains SymbolId/FileId validity
    // across Discover → Run sequences. This is critical for Server mode where
    // a client may obtain SymbolIds from Discover and use them in subsequent Run calls.

    /// Helper to create a test project with multiple functions for renaming tests
    fn create_multi_function_project() -> (tempfile::TempDir, Project) {
        let dir = tempdir().unwrap();
        let src = dir.path().join("src");
        fs::create_dir(&src).unwrap();

        fs::write(
            src.join("lib.rs"),
            r#"
pub fn alpha() -> i32 {
    1
}

pub fn beta() -> i32 {
    alpha() + 1
}

pub fn gamma() -> i32 {
    beta() + alpha()
}
"#,
        )
        .unwrap();

        // Add Cargo.toml for proper project detection
        fs::write(
            dir.path().join("Cargo.toml"),
            r#"[package]
name = "test-project"
version = "0.1.0"
edition = "2021"
"#,
        )
        .unwrap();

        let project = Project::load(dir.path()).unwrap();
        (dir, project)
    }

    #[test]
    fn test_discover_then_run_preserves_symbol_id() {
        // Scenario: Discover a symbol, then Run a rename on it using the same Api instance.
        // The SymbolId obtained from Discover should remain valid for the Run operation.
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Step 1: Discover the 'alpha' function
        let discover_response = api
            .discover(DiscoverRequest {
                pattern: "alpha".to_string(),
                ..Default::default()
            })
            .unwrap();

        assert!(discover_response.total > 0, "Should find 'alpha' function");

        // Verify we found the symbol
        let alpha_symbol = discover_response
            .symbols
            .iter()
            .find(|s| s.name == "alpha")
            .expect("Should find 'alpha' in discover response");
        assert_eq!(alpha_symbol.name, "alpha");

        // Step 2: Run a rename using the Api (simulating Server mode workflow)
        let goal = Goal::new(
            "rename alpha to alpha_renamed",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("alpha".to_string()),
                to: "alpha_renamed".to_string(),
                kind: IdentKind::Fn,
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(result.success, "Rename should succeed");
        assert!(result.total_changes > 0, "Should have made changes");

        // Step 3: Verify the Context still has valid file registry
        // The original FileId should still be resolvable
        let files: Vec<_> = api.context().files().keys().cloned().collect();
        assert!(!files.is_empty(), "Should still have files in context");

        // Verify each file path can be resolved to a file
        for file_path in &files {
            assert!(
                api.context().file(file_path).is_some(),
                "File {:?} should be accessible after run",
                file_path
            );
        }

        // Step 4: Verify the renamed symbol exists by discovering it
        let discover_after = api
            .discover(DiscoverRequest {
                pattern: "alpha_renamed".to_string(),
                ..Default::default()
            })
            .unwrap();

        // Note: Due to SymbolRegistry not being updated (Phase 6 not implemented),
        // the old path "alpha" may still be in registry. This test verifies the
        // Context lifecycle is maintained, not that SymbolRegistry is updated.
        // Phase 6 will address SymbolRegistry updates.
        let _ = discover_after; // Acknowledge we've checked

        // The key assertion: the Api's context survived the Run operation
        // and FileIds remain valid
        assert!(
            !api.context().registry().is_empty(),
            "FileRegistry should have entries after run"
        );
    }

    #[test]
    fn test_run_then_discover_context_survives() {
        // Verify that after running a mutation, subsequent Discover calls work correctly
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Step 1: Run a rename
        let goal = Goal::new(
            "rename beta to beta_new",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("beta".to_string()),
                to: "beta_new".to_string(),
                kind: IdentKind::Fn,
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(result.success, "First rename should succeed");

        // Step 2: Discover should still work and use the same Context
        let discover_response = api
            .discover(DiscoverRequest {
                pattern: "gamma".to_string(),
                ..Default::default()
            })
            .unwrap();

        // gamma should still be discoverable (it wasn't renamed)
        assert!(
            discover_response.symbols.iter().any(|s| s.name == "gamma"),
            "gamma should still be discoverable after run"
        );

        // Step 3: Run another mutation to verify Context is still usable
        let goal2 = Goal::new(
            "rename gamma to gamma_new",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("gamma".to_string()),
                to: "gamma_new".to_string(),
                kind: IdentKind::Fn,
            },
        );

        let result2 = api.execute(goal2).unwrap();
        assert!(result2.success, "Second rename should succeed");
    }

    #[test]
    fn test_multiple_sequential_runs_preserve_context() {
        // Verify that multiple Run operations don't corrupt the Context
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Get initial file count
        let initial_file_count = api.context().files().len();

        // Run 3 sequential renames
        let renames = [
            ("alpha", "alpha_v2"),
            ("beta", "beta_v2"),
            ("gamma", "gamma_v2"),
        ];

        for (from, to) in renames {
            let goal = Goal::new(
                format!("rename {} to {}", from, to),
                Intent::RenameIdent {
                    symbol_id: None,
                    symbol_path: None,
                    target_ident: Some(from.to_string()),
                    to: to.to_string(),
                    kind: IdentKind::Fn,
                },
            );

            let result = api.execute(goal).unwrap();
            assert!(result.success, "Rename {} -> {} should succeed", from, to);
        }

        // Verify Context integrity after multiple runs
        assert_eq!(
            api.context().files().len(),
            initial_file_count,
            "File count should remain stable after multiple runs"
        );

        // Verify all files are still accessible
        for (file_path, _) in api.context().files().iter() {
            assert!(
                api.context().file(file_path).is_some(),
                "File {:?} should be accessible after multiple runs",
                file_path
            );
        }
    }

    #[test]
    fn test_spec_cache_invalidated_after_run() {
        // Verify that spec_cache is properly invalidated after a Run operation
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Step 1: Call spec() to populate the cache
        let spec_request = SpecRequest::show();
        let spec_result1 = api.spec(spec_request.clone());
        assert!(spec_result1.is_ok(), "First spec() call should succeed");

        // Step 2: Run a mutation that modifies files
        let goal = Goal::new(
            "rename alpha to alpha_changed",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("alpha".to_string()),
                to: "alpha_changed".to_string(),
                kind: IdentKind::Fn,
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(result.success, "Rename should succeed");

        // Step 3: Call spec() again - it should work (cache was invalidated and rebuilt)
        let spec_result2 = api.spec(spec_request);
        assert!(
            spec_result2.is_ok(),
            "spec() after run should succeed (cache invalidated and rebuilt)"
        );
    }

    #[test]
    fn test_file_content_updated_in_context_after_run() {
        // Verify that file content in Context is actually updated after Run
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Get initial file content
        let file_id = api.context().files().keys().next().unwrap().clone();
        let initial_content = api.context().file(&file_id).unwrap().to_source().unwrap();
        assert!(
            initial_content.contains("fn alpha()"),
            "Initial content should contain 'fn alpha()'"
        );

        // Run a rename
        let goal = Goal::new(
            "rename alpha to alpha_modified",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("alpha".to_string()),
                to: "alpha_modified".to_string(),
                kind: IdentKind::Fn,
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(result.success);

        // Verify the file content in Context was updated
        let updated_content = api.context().file(&file_id).unwrap().to_source().unwrap();
        assert!(
            updated_content.contains("fn alpha_modified()"),
            "Updated content should contain 'fn alpha_modified()'"
        );
        assert!(
            !updated_content.contains("fn alpha()"),
            "Updated content should NOT contain original 'fn alpha()'"
        );
    }

    // ------------------------------------------------------------------------
    // Phase 6: SymbolRegistry Update Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_discover_finds_renamed_symbol() {
        // Phase 6 test: After renaming a symbol, Discover should find it by the new name
        // and NOT find it by the old name.
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Step 1: Verify 'alpha' exists before rename
        let before = api
            .discover(DiscoverRequest {
                pattern: "alpha".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            before.symbols.iter().any(|s| s.name == "alpha"),
            "Should find 'alpha' before rename"
        );

        // Step 2: Rename alpha → omega
        let goal = Goal::new(
            "rename alpha to omega",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("alpha".to_string()),
                to: "omega".to_string(),
                kind: IdentKind::Fn,
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(result.success, "Rename should succeed");

        // Step 3: Discover should now find 'omega'
        let after_new = api
            .discover(DiscoverRequest {
                pattern: "omega".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            after_new.symbols.iter().any(|s| s.name == "omega"),
            "Should find 'omega' after rename"
        );

        // Step 4: Discover should NOT find 'alpha' anymore (in registry)
        let after_old = api
            .discover(DiscoverRequest {
                pattern: "alpha".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            !after_old.symbols.iter().any(|s| s.name == "alpha"),
            "Should NOT find 'alpha' in registry after rename"
        );
    }

    #[test]
    fn test_registry_updated_after_sequential_renames() {
        // Phase 6 test: Sequential renames should keep registry in sync
        // alpha → beta_new, then beta → gamma_new
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // First rename: alpha → alpha_new
        let goal1 = Goal::new(
            "rename alpha to alpha_new",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("alpha".to_string()),
                to: "alpha_new".to_string(),
                kind: IdentKind::Fn,
            },
        );

        let result1 = api.execute(goal1).unwrap();
        assert!(result1.success, "First rename should succeed");

        // Second rename: beta → beta_new
        let goal2 = Goal::new(
            "rename beta to beta_new",
            Intent::RenameIdent {
                symbol_id: None,
                symbol_path: None,
                target_ident: Some("beta".to_string()),
                to: "beta_new".to_string(),
                kind: IdentKind::Fn,
            },
        );

        let result2 = api.execute(goal2).unwrap();
        assert!(result2.success, "Second rename should succeed");

        // Verify both new names are findable
        let discover_alpha = api
            .discover(DiscoverRequest {
                pattern: "alpha_new".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            discover_alpha.symbols.iter().any(|s| s.name == "alpha_new"),
            "Should find 'alpha_new' after rename"
        );

        let discover_beta = api
            .discover(DiscoverRequest {
                pattern: "beta_new".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            discover_beta.symbols.iter().any(|s| s.name == "beta_new"),
            "Should find 'beta_new' after rename"
        );

        // Old names should not be found
        let discover_old_alpha = api
            .discover(DiscoverRequest {
                pattern: "alpha".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            !discover_old_alpha.symbols.iter().any(|s| s.name == "alpha"),
            "Should NOT find 'alpha' after rename"
        );
    }

    // ------------------------------------------------------------------------
    // Phase 7: SymbolId Resolution Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_symbol_id_resolves_to_name() {
        // Phase 7 test: symbol_id field should resolve to the symbol's name
        // via SymbolRegistry when planning mutations.
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Step 1: Discover 'alpha' to get its SymbolId
        let discover_result = api
            .discover(DiscoverRequest {
                pattern: "alpha".to_string(),
                ..Default::default()
            })
            .unwrap();

        let alpha_symbol = discover_result
            .symbols
            .iter()
            .find(|s| s.name == "alpha")
            .expect("Should find 'alpha' symbol");

        // Step 2: Create a rename intent using symbol_id field with the SymbolId
        let goal = Goal::new(
            "rename alpha to zeta using symbol_id",
            Intent::RenameIdent {
                symbol_id: Some(alpha_symbol.id.clone()),
                symbol_path: None,
                target_ident: None,
                to: "zeta".to_string(),
                kind: IdentKind::Fn,
            },
        );

        // Step 3: Execute the rename - this should work because symbol_id
        // is resolved to "alpha" via the SymbolRegistry
        let result = api.execute(goal).unwrap();
        assert!(result.success, "Rename using symbol_id should succeed");
        assert!(result.total_changes > 0, "Should have made changes");

        // Step 4: Verify 'zeta' exists and 'alpha' doesn't
        let discover_zeta = api
            .discover(DiscoverRequest {
                pattern: "zeta".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            discover_zeta.symbols.iter().any(|s| s.name == "zeta"),
            "Should find 'zeta' after rename via symbol_id"
        );

        let discover_alpha = api
            .discover(DiscoverRequest {
                pattern: "alpha".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            !discover_alpha.symbols.iter().any(|s| s.name == "alpha"),
            "Should NOT find 'alpha' after rename via symbol_id"
        );
    }

    #[test]
    fn test_symbol_id_sequential_operations() {
        // Phase 7 test: symbol_id should work correctly in a sequence of operations
        // where the symbol is discovered, renamed, discovered again, and renamed again.
        let (dir, _project) = create_multi_function_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Step 1: Discover 'alpha' to get its SymbolId
        let discover1 = api
            .discover(DiscoverRequest {
                pattern: "alpha".to_string(),
                ..Default::default()
            })
            .unwrap();
        let alpha_id_str = discover1
            .symbols
            .iter()
            .find(|s| s.name == "alpha")
            .unwrap()
            .id
            .clone();

        // Step 2: Rename alpha → phi using symbol_id
        let goal1 = Goal::new(
            "rename alpha to phi",
            Intent::RenameIdent {
                symbol_id: Some(alpha_id_str.clone()),
                symbol_path: None,
                target_ident: None,
                to: "phi".to_string(),
                kind: IdentKind::Fn,
            },
        );
        let result1 = api.execute(goal1).unwrap();
        assert!(result1.success, "First rename should succeed");

        // Step 3: Discover 'phi' to get its (updated) SymbolId
        let discover2 = api
            .discover(DiscoverRequest {
                pattern: "phi".to_string(),
                ..Default::default()
            })
            .unwrap();
        let phi_id_str = discover2
            .symbols
            .iter()
            .find(|s| s.name == "phi")
            .unwrap()
            .id
            .clone();

        // The symbol ID should be the same (we renamed, not created new)
        assert_eq!(
            alpha_id_str, phi_id_str,
            "SymbolId should be preserved across renames"
        );

        // Step 4: Rename phi → psi using symbol_id with the same ID
        let goal2 = Goal::new(
            "rename phi to psi",
            Intent::RenameIdent {
                symbol_id: Some(phi_id_str),
                symbol_path: None,
                target_ident: None,
                to: "psi".to_string(),
                kind: IdentKind::Fn,
            },
        );
        let result2 = api.execute(goal2).unwrap();
        assert!(result2.success, "Second rename should succeed");

        // Step 5: Verify 'psi' exists
        let discover3 = api
            .discover(DiscoverRequest {
                pattern: "psi".to_string(),
                ..Default::default()
            })
            .unwrap();
        assert!(
            discover3.symbols.iter().any(|s| s.name == "psi"),
            "Should find 'psi' after sequential renames using symbol_id"
        );
    }

    // ------------------------------------------------------------------------
    // AddVariant → Cascade → AddMatchArm E2E Tests
    // ------------------------------------------------------------------------

    fn create_enum_match_project() -> (tempfile::TempDir, Project) {
        let dir = tempdir().unwrap();
        let src = dir.path().join("src");
        fs::create_dir(&src).unwrap();

        fs::write(
            dir.path().join("Cargo.toml"),
            r#"[package]
name = "test-enum-match"
version = "0.1.0"
edition = "2021"
"#,
        )
        .unwrap();

        fs::write(
            src.join("lib.rs"),
            r#"
pub enum Status {
    Active,
    Inactive,
}

pub fn handle_status(s: Status) -> &'static str {
    match s {
        Status::Active => "active",
        Status::Inactive => "inactive",
    }
}

pub struct Processor;

impl Processor {
    pub fn label(s: &Status) -> &'static str {
        match s {
            Status::Active => "A",
            Status::Inactive => "I",
        }
    }
}
"#,
        )
        .unwrap();

        let project = Project::load(dir.path()).unwrap();
        (dir, project)
    }

    #[test]
    fn test_add_variant_cascade_adds_match_arms() {
        // Regression E2E: AddVariant should cascade AddMatchArm for both
        // free functions and methods, producing total_changes > 0.
        let (dir, _project) = create_enum_match_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "add Pending variant to Status",
            Intent::AddVariant {
                symbol_id: None,
                symbol_path: None,
                target_enum: Some("Status".to_string()),
                variant_name: "Pending".to_string(),
                variant_type: "unit".to_string(),
            },
        );

        let result = api.execute(goal).unwrap();

        // The AddVariant itself should succeed
        assert!(
            result.success,
            "AddVariant with cascade should succeed: {:?}",
            result
        );

        // Should have changes: AddVariant (1) + AddMatchArm (2, one per match expr)
        assert!(
            result.total_changes >= 3,
            "Expected at least 3 changes (1 AddVariant + 2 AddMatchArm), got {}",
            result.total_changes
        );
    }

    #[test]
    fn test_graph_cascade_enum_returns_match_functions() {
        // Regression: graph_cascade for an enum should return match_functions,
        // not just callers (which are always 0 for enums).
        let (dir, _project) = create_enum_match_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        // Find the Status enum SymbolId
        let discover_result = api
            .discover(DiscoverRequest {
                pattern: "Status".to_string(),
                kind: Some(ryo_analysis::SymbolKind::Enum),
                ..Default::default()
            })
            .unwrap();
        let status_sym = discover_result
            .symbols
            .iter()
            .find(|s| s.name == "Status")
            .expect("Status enum should exist");

        let cascade = api
            .graph_cascade(CascadeRequest::new(&status_sym.id))
            .unwrap();

        // match_functions should contain both handle_status and label
        assert!(
            cascade.match_functions.len() >= 2,
            "Expected at least 2 match functions, got {}: {:?}",
            cascade.match_functions.len(),
            cascade.match_functions
        );

        let has_handle_status = cascade
            .match_functions
            .iter()
            .any(|f| f.contains("handle_status"));
        let has_label = cascade.match_functions.iter().any(|f| f.contains("label"));
        assert!(
            has_handle_status,
            "match_functions should include handle_status: {:?}",
            cascade.match_functions
        );
        assert!(
            has_label,
            "match_functions should include label: {:?}",
            cascade.match_functions
        );
    }

    /// Create a project with TupleStruct variant patterns for match arm testing
    fn create_tuple_variant_project() -> (tempfile::TempDir, Project) {
        let dir = tempdir().unwrap();
        let src = dir.path().join("src");
        fs::create_dir(&src).unwrap();

        fs::write(
            dir.path().join("Cargo.toml"),
            r#"[package]
name = "test-tuple-variant"
version = "0.1.0"
edition = "2021"
"#,
        )
        .unwrap();

        fs::write(
            src.join("lib.rs"),
            r#"
pub enum Message {
    Text(String),
    Number(i32),
    Empty,
}

pub fn describe(msg: &Message) -> String {
    match msg {
        Message::Text(s) => format!("text: {}", s),
        Message::Number(n) => format!("num: {}", n),
        Message::Empty => "empty".to_string(),
    }
}
"#,
        )
        .unwrap();

        let project = Project::load(dir.path()).unwrap();
        (dir, project)
    }

    #[test]
    fn test_replace_match_arm_tuple_variant() {
        // Regression: ReplaceMatchArm should work with TupleStruct patterns
        // like Message::Text(s), not just unit patterns like Status::Active.
        let (dir, _project) = create_tuple_variant_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "replace Text arm body",
            Intent::ReplaceMatchArm {
                symbol_id: None,
                symbol_path: None,
                target_fn: Some("describe".to_string()),
                enum_name: "Message".to_string(),
                old_pattern: "Message::Text(s)".to_string(),
                new_pattern: "Message::Text(s)".to_string(),
                new_body: "format!(\"text_v2: {}\", s)".to_string(),
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(
            result.success && result.total_changes >= 1,
            "ReplaceMatchArm with TupleStruct pattern should succeed: {:?}",
            result
        );
    }

    #[test]
    fn test_replace_match_arm_by_symbol_id() {
        // ReplaceMatchArm works with symbol_id
        let (dir, _project) = create_enum_match_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let discover_result = api
            .discover(DiscoverRequest {
                pattern: "handle_status".to_string(),
                ..Default::default()
            })
            .unwrap();
        let fn_sym = discover_result
            .symbols
            .iter()
            .find(|s| s.name == "handle_status")
            .expect("handle_status should exist");

        let goal = Goal::new(
            "replace Active arm body",
            Intent::ReplaceMatchArm {
                symbol_id: Some(fn_sym.id.clone()),
                symbol_path: None,
                target_fn: None,
                enum_name: "Status".to_string(),
                old_pattern: "Status::Active".to_string(),
                new_pattern: "Status::Active".to_string(),
                new_body: "\"active_v2\"".to_string(),
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(
            result.success && result.total_changes >= 1,
            "ReplaceMatchArm by symbol_id should succeed: {:?}",
            result
        );
    }

    #[test]
    fn test_replace_match_arm_by_target_fn() {
        // ReplaceMatchArm with target_fn (Priority 3, name-based search)
        let (dir, _project) = create_enum_match_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "replace Active arm body via target_fn",
            Intent::ReplaceMatchArm {
                symbol_id: None,
                symbol_path: None,
                target_fn: Some("handle_status".to_string()),
                enum_name: "Status".to_string(),
                old_pattern: "Status::Active".to_string(),
                new_pattern: "Status::Active".to_string(),
                new_body: "\"active_v2\"".to_string(),
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(
            result.success && result.total_changes >= 1,
            "ReplaceMatchArm by target_fn should succeed: {:?}",
            result
        );
    }

    #[test]
    fn test_replace_match_arm_by_symbol_path() {
        // ReplaceMatchArm with full symbol_path
        let (dir, _project) = create_enum_match_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "replace Active arm body via symbol_path",
            Intent::ReplaceMatchArm {
                symbol_id: None,
                symbol_path: Some("test_enum_match::handle_status".to_string()),
                target_fn: None,
                enum_name: "Status".to_string(),
                old_pattern: "Status::Active".to_string(),
                new_pattern: "Status::Active".to_string(),
                new_body: "\"active_v2\"".to_string(),
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(
            result.success && result.total_changes >= 1,
            "ReplaceMatchArm by symbol_path should succeed: {:?}",
            result
        );
    }

    // -----------------------------------------------------------------------
    // Bug #4: AddVariant cascade — multi-match function overmatch
    // -----------------------------------------------------------------------

    /// Create a project where functions have multiple match expressions
    /// on DIFFERENT types to test cascade specificity.
    fn create_multi_match_project() -> (tempfile::TempDir, Project) {
        let dir = tempdir().unwrap();
        let src = dir.path().join("src");
        fs::create_dir(&src).unwrap();
        fs::write(
            dir.path().join("Cargo.toml"),
            r#"[package]
name = "test-multi-match"
version = "0.1.0"
edition = "2021"
"#,
        )
        .unwrap();
        fs::write(
            src.join("lib.rs"),
            r#"
pub enum Filter {
    Recurse(usize),
    Exclude(String),
}

pub enum FilterKind {
    Inclusive,
    Exclusive,
}

pub fn evaluate(f: Filter, name: &str) -> String {
    // First: match on Option (unrelated)
    let idx = match name.find('/') {
        Some(i) => i,
        None => 0,
    };
    // Second: match on Filter (the target)
    match f {
        Filter::Recurse(depth) => format!("recurse {}", depth),
        Filter::Exclude(pat) => format!("exclude {}", pat),
    }
}

pub fn classify(fk: FilterKind) -> &'static str {
    // Matches on FilterKind — NOT Filter
    // But "FilterKind::Inclusive".contains("Filter") == true (false positive)
    match fk {
        FilterKind::Inclusive => "inclusive",
        FilterKind::Exclusive => "exclusive",
    }
}

pub fn nested_eval(f: Filter) -> String {
    // Nested match on the SAME enum — should still produce only 1 arm addition
    match f {
        Filter::Recurse(depth) => {
            match f {
                Filter::Recurse(d) => format!("double recurse {}", d),
                Filter::Exclude(_) => String::new(),
            }
        }
        Filter::Exclude(pat) => format!("exclude {}", pat),
    }
}
"#,
        )
        .unwrap();
        let project = Project::load(dir.path()).unwrap();
        (dir, project)
    }

    #[test]
    fn test_add_variant_cascade_no_overmatch() {
        // AddVariant(Filter::Map(String)) should:
        // 1. Add variant Map(String) to enum Filter
        // 2. Add match arm Filter::Map(_) ONLY to evaluate() — NOT type_name()
        // 3. No duplicate arms
        // 4. Pattern must include "Filter::" prefix
        let (dir, _project) = create_multi_match_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "add Map variant to Filter",
            Intent::AddVariant {
                symbol_id: None,
                symbol_path: None,
                target_enum: Some("Filter".to_string()),
                variant_name: "Map".to_string(),
                variant_type: "tuple:String".to_string(),
            },
        );

        let result = api.execute(goal).unwrap();
        assert!(
            result.success && result.total_changes >= 1,
            "AddVariant cascade should succeed with changes: {:?}",
            result
        );

        // Read the generated source from in-memory context
        // (execute() doesn't write to disk — it updates the AST registry)
        let src_content = {
            let ctx = api.context();
            let mut source = String::new();
            for (_wfp, file) in ctx.files().iter() {
                source = file.to_source().unwrap();
            }
            source
        };

        // The Filter enum should have the new variant
        assert!(
            src_content.contains("Map(String)"),
            "Filter enum should contain Map(String):\n{}",
            src_content
        );

        // Count Filter::Map occurrences in match arm positions.
        // Expected: exactly 2 (evaluate: 1, nested_eval: 1 in outer match).
        // The walker returns true after the first matching match expression,
        // so nested_eval's inner match does not get a separate arm.
        // NOT in classify (FilterKind != Filter).
        let map_arm_count = src_content.matches("Filter::Map").count();
        assert_eq!(
            map_arm_count, 2,
            "Should have exactly 2 Filter::Map arms (evaluate=1, nested_eval=1), got {}:\n{}",
            map_arm_count, src_content
        );

        // classify() should NOT have any Map arm
        // (FilterKind::Inclusive contains "Filter" as substring, but is a different enum)
        let classify_start = src_content
            .find("fn classify")
            .expect("classify should exist");
        let classify_end = src_content[classify_start..]
            .find("\n}\n")
            .map(|i| classify_start + i + 3)
            .unwrap_or(src_content.len());
        let classify_body = &src_content[classify_start..classify_end];
        assert!(
            !classify_body.contains("Filter::Map"),
            "classify() should NOT have Filter::Map arm (FilterKind != Filter):\n{}",
            classify_body
        );

        // nested_eval: should NOT have duplicate Filter::Map arms
        let nested_start = src_content
            .find("fn nested_eval")
            .expect("nested_eval should exist");
        let nested_body = &src_content[nested_start..];
        let nested_map_count = nested_body.matches("Filter::Map").count();
        // nested_eval has 2 match expressions on Filter.
        // Each should get at most 1 Filter::Map arm.
        assert!(
            nested_map_count <= 2,
            "nested_eval() should have at most 2 Filter::Map arms (one per match), got {}:\n{}",
            nested_map_count,
            nested_body
        );

        // No "Map(_)" without "Filter::" prefix in match arms
        let has_bare_map = src_content.lines().any(|line| {
            let trimmed = line.trim();
            trimmed.contains("Map(_)") && !trimmed.contains("Filter::Map")
        });
        assert!(
            !has_bare_map,
            "Should not have bare 'Map(_)' without 'Filter::' prefix:\n{}",
            src_content
        );
    }

    // =========================================================================
    // InsertStatement AfterPattern E2E tests
    // =========================================================================

    fn create_insert_statement_project() -> (tempfile::TempDir, Project) {
        let dir = tempdir().unwrap();
        let src = dir.path().join("src");
        fs::create_dir(&src).unwrap();

        fs::write(
            dir.path().join("Cargo.toml"),
            r#"[package]
name = "test-insert"
version = "0.1.0"
edition = "2021"
"#,
        )
        .unwrap();

        fs::write(
            src.join("lib.rs"),
            r#"
pub fn setup(config: &mut Config) {
    let db = connect_db();
    let cache = init_cache();
    start_server();
}
"#,
        )
        .unwrap();

        let project = Project::load(dir.path()).unwrap();
        (dir, project)
    }

    #[test]
    fn test_insert_statement_after_pattern_e2e() {
        let (dir, _project) = create_insert_statement_project();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "insert pool init after db connect",
            Intent::InsertStatement {
                target_mod: None,
                target_fn: "setup".to_string(),
                stmt: "let pool = create_pool(&db);".to_string(),
                position: StmtInsertPosition::AfterPattern,
                reference_pattern: Some("let db = connect_db()".to_string()),
                symbol_path: None,
            },
        );

        let result = api.execute(goal).unwrap();
        eprintln!("InsertStatement AfterPattern result: {:?}", result);

        assert!(
            result.success,
            "InsertStatement AfterPattern should succeed: {:?}",
            result
        );
        assert!(
            result.total_changes >= 1,
            "Should have at least 1 change, got {}. Result: {:?}",
            result.total_changes,
            result
        );

        // Verify the inserted statement appears after the reference
        let src_content = {
            let ctx = api.context();
            let mut source = String::new();
            for (_wfp, file) in ctx.files().iter() {
                source = file.to_source().unwrap();
            }
            source
        };

        assert!(
            src_content.contains("create_pool"),
            "Inserted statement should appear in output:\n{}",
            src_content
        );

        // Verify ordering: "connect_db" should appear before "create_pool"
        let db_pos = src_content
            .find("connect_db")
            .expect("connect_db should exist");
        let pool_pos = src_content
            .find("create_pool")
            .expect("create_pool should exist");
        assert!(
            db_pos < pool_pos,
            "connect_db should appear before create_pool:\n{}",
            src_content
        );
    }

    #[test]
    fn test_insert_statement_after_pattern_macro_e2e() {
        // Test with macro statement as reference pattern
        let dir = tempdir().unwrap();
        let src = dir.path().join("src");
        fs::create_dir(&src).unwrap();

        fs::write(
            dir.path().join("Cargo.toml"),
            r#"[package]
name = "test-insert-macro"
version = "0.1.0"
edition = "2021"
"#,
        )
        .unwrap();

        fs::write(
            src.join("lib.rs"),
            r#"
pub fn run() {
    println!("starting");
    do_work();
    println!("done");
}
"#,
        )
        .unwrap();

        let _project = Project::load(dir.path()).unwrap();
        let mut api = Api::from_path(dir.path()).unwrap();

        let goal = Goal::new(
            "insert log after starting",
            Intent::InsertStatement {
                target_mod: None,
                target_fn: "run".to_string(),
                stmt: r#"println!("logging");"#.to_string(),
                position: StmtInsertPosition::AfterPattern,
                reference_pattern: Some(r#"println!("starting")"#.to_string()),
                symbol_path: None,
            },
        );

        let result = api.execute(goal).unwrap();
        eprintln!("InsertStatement macro AfterPattern result: {:?}", result);

        assert!(
            result.success,
            "InsertStatement macro AfterPattern should succeed: {:?}",
            result
        );
        assert!(
            result.total_changes >= 1,
            "Should have at least 1 change, got {}. Result: {:?}",
            result.total_changes,
            result
        );
    }

    /// JSON経由のデシリアライズ: 正しいフィールド名で成功するか
    #[test]
    fn test_insert_statement_json_deserialize_correct_fields() {
        let json = serde_json::json!({
            "type": "InsertStatement",
            "target_fn": "setup",
            "stmt": "let pool = create_pool();",
            "position": "after_pattern",
            "reference_pattern": "let db = connect_db()"
        });
        let intent: Result<Intent, _> = serde_json::from_value(json);
        assert!(
            intent.is_ok(),
            "Correct field names should deserialize: {:?}",
            intent.err()
        );
    }
}