php_lsp/backend/

server.rs

use std::collections::HashMap;
use std::sync::Arc;

use tower_lsp_server::LanguageServer;
use tower_lsp_server::jsonrpc::Result;
use tower_lsp_server::ls_types::*;

use super::DiagnosticPublish;
use super::panic_guard::{guard_async, guard_async_result};
use crate::analysis::callable_info::{callable_info_for_name, format_declared_params};
use crate::completion::{CompletionCtx, filtered_completions_at};
use crate::document::ast::ParsedDoc;
use crate::document::open_files::compute_open_file_diagnostics;
use crate::hover::{extract_static_class_before_cursor, hover_info_with_maps};
use crate::index::file_index::ClassKind;
use crate::index::workspace_scan::{scan_workspace, send_refresh_requests};
use crate::lang::config::LspConfig;
use crate::lang::is_unresolvable_bareword_at;
use crate::navigation::symbols::{
    document_symbols, resolve_workspace_symbol, workspace_symbols_from_workspace,
};
use crate::text::word_at_position;

use crate::navigation::call_hierarchy::{
    incoming_calls_indexed, outgoing_calls_via_mir, prepare_call_hierarchy_indexed,
};
use crate::navigation::declaration::{goto_declaration, goto_declaration_from_index};
use crate::navigation::moniker::moniker_at;
use crate::navigation::type_definition::type_class_fqns;
use crate::navigation::type_hierarchy::{
    prepare_type_hierarchy_from_fqn, subtypes_from_sites, supertypes_of_from_workspace,
};

use crate::analysis::code_lens::{code_lenses, subtype_site_to_location};
use crate::analysis::diagnostics::{diagnostics_from_doc, parse_document, parse_document_no_diags};
use crate::analysis::document_highlight::document_highlights;
use crate::analysis::inlay_hints::inlay_hints;
use crate::analysis::inline_value::inline_values_in_range;
use crate::analysis::semantic_tokens::{
    compute_token_delta, semantic_tokens, semantic_tokens_range, token_hash,
};

use crate::editing::document_link::document_links;
use crate::editing::folding::folding_ranges;
use crate::editing::formatting::{format_document, format_range};
use crate::editing::on_type_format::on_type_format;
use crate::editing::rename::{prepare_rename, rename_variable};
use crate::editing::selection_range::selection_ranges;
use crate::editing::signature_help::signature_help;

use super::helpers::{cursor_is_on_property_decl, promoted_property_at_cursor, run_phpunit};
use super::{Backend, publish_with_dependents};

/// Idle time after the last edit before the background analysis re-warm runs.
/// Long enough that a typing burst triggers one sweep, not one per pause;
/// short enough that references asked "shortly after editing" are warm again.
const WARM_RESWEEP_IDLE_MS: u64 = 1_000;

fn normalized_php_fqn(name: &str) -> &str {
    name.trim_start_matches('\\')
}

fn is_bare_php_name(name: &str) -> bool {
    crate::text::fqn_short_name(name) == name
}

fn class_lookup_fqn(doc: &ParsedDoc, name: &str, imports: &HashMap<String, String>) -> String {
    if is_bare_php_name(name) {
        crate::navigation::moniker::resolve_fqn(doc, name, imports)
    } else {
        normalized_php_fqn(name).to_string()
    }
}

fn inlay_hint_symbol_from_data(data: &serde_json::Value) -> Option<mir_analyzer::Name> {
    let kind = data.get("php_lsp_symbol_kind")?.as_str()?;
    let name = data.get("php_lsp_fn")?.as_str()?;
    match kind {
        "function" => Some(mir_analyzer::Name::function(name)),
        "method" => {
            let class = data.get("php_lsp_class")?.as_str()?;
            Some(mir_analyzer::Name::method(class, name))
        }
        "class" => Some(mir_analyzer::Name::class(name)),
        _ => None,
    }
}

fn completion_symbol_from_item(
    name: &str,
    kind: Option<CompletionItemKind>,
    class_hint: Option<&str>,
) -> Option<mir_analyzer::Name> {
    if let Some(class_name) = class_hint {
        return Some(mir_analyzer::Name::method(class_name, name));
    }
    match kind {
        Some(CompletionItemKind::FUNCTION) => Some(mir_analyzer::Name::function(name)),
        Some(CompletionItemKind::CLASS)
        | Some(CompletionItemKind::INTERFACE)
        | Some(CompletionItemKind::ENUM) => Some(mir_analyzer::Name::class(name)),
        _ => None,
    }
}

fn hover_markup(value: String) -> Hover {
    Hover {
        contents: HoverContents::Markup(MarkupContent {
            kind: MarkupKind::Markdown,
            value,
        }),
        range: None,
    }
}

fn hover_display_class_name(snapshot: &mir_analyzer::AnalysisSnapshot, name: &str) -> String {
    let normalized = normalized_php_fqn(name);
    if !is_bare_php_name(normalized) {
        return normalized.to_string();
    }
    if let Ok(true) = snapshot.is_builtin_class(normalized) {
        return format!("\\{normalized}");
    }
    normalized.to_string()
}

fn class_hover_for_fqcn(session: &mir_analyzer::AnalysisSnapshot, fqcn: &str) -> Option<Hover> {
    let class = {
        let db = session.db();
        let here = mir_analyzer::db::Fqcn::from_str(db, fqcn);
        mir_analyzer::db::find_class_like(db, here)?
    };
    let sig = match &class {
        mir_analyzer::db::ClassLike::Class(c) => {
            let mut sig = if c.is_abstract {
                format!("abstract class {}", c.short_name)
            } else if c.is_readonly {
                format!("readonly class {}", c.short_name)
            } else if c.is_final {
                format!("final class {}", c.short_name)
            } else {
                format!("class {}", c.short_name)
            };
            if let Some(parent) = &c.parent {
                sig.push_str(&format!(
                    " extends {}",
                    hover_display_class_name(session, parent)
                ));
            }
            if !c.interfaces.is_empty() {
                let list: Vec<String> = c
                    .interfaces
                    .iter()
                    .map(|s| hover_display_class_name(session, s))
                    .collect();
                sig.push_str(&format!(" implements {}", list.join(", ")));
            }
            sig
        }
        mir_analyzer::db::ClassLike::Interface(i) => {
            let mut sig = format!("interface {}", i.short_name);
            if !i.extends.is_empty() {
                let list: Vec<String> = i
                    .extends
                    .iter()
                    .map(|s| hover_display_class_name(session, s))
                    .collect();
                sig.push_str(&format!(" extends {}", list.join(", ")));
            }
            sig
        }
        mir_analyzer::db::ClassLike::Trait(t) => format!("trait {}", t.short_name),
        mir_analyzer::db::ClassLike::Enum(e) => {
            let mut sig = if let Some(scalar) = &e.scalar_type {
                format!("enum {}: {}", e.short_name, scalar)
            } else {
                format!("enum {}", e.short_name)
            };
            if !e.interfaces.is_empty() {
                let list: Vec<String> = e
                    .interfaces
                    .iter()
                    .map(|s| hover_display_class_name(session, s))
                    .collect();
                sig.push_str(&format!(" implements {}", list.join(", ")));
            }
            sig
        }
    };
    Some(hover_markup(crate::hover::formatting::wrap_php(&sig)))
}

fn method_hover_for_fqcn(
    session: &mir_analyzer::AnalysisSnapshot,
    fqcn: &str,
    method_name: &str,
) -> Option<Hover> {
    let db = session.db();
    let (_, m) = mir_analyzer::db::find_method_in_chain(
        db,
        mir_analyzer::db::Fqcn::from_str(db, fqcn),
        method_name,
    )?;
    let ret = m
        .return_type
        .as_deref()
        .or(m.inferred_return_type.as_deref())
        .map(|r| format!(": {}", r))
        .unwrap_or_default();
    let sig = format!(
        "{}::{}({}){}",
        crate::text::fqn_short_name(fqcn),
        m.name,
        format_declared_params(&m.params),
        ret
    );
    let mut value = crate::hover::formatting::wrap_php(&sig);
    if let Some(docstring) = m.docstring.as_deref().filter(|s| !s.is_empty()) {
        value.push_str("\n\n---\n\n");
        value.push_str(docstring);
    }
    Some(hover_markup(value))
}

fn callable_signature_for_symbol(
    db: &mir_analyzer::db::MirDbStorage,
    symbol: &mir_analyzer::Name,
) -> Option<(String, Option<String>)> {
    let info = callable_info_for_name(db, symbol)?;
    match symbol {
        mir_analyzer::Name::Function(fqn) => {
            let short = fqn.rsplit('\\').next().unwrap_or(fqn.as_ref());
            if mir_analyzer::is_builtin_function(short) {
                return None;
            }
            let ret = info
                .return_type
                .as_deref()
                .map(|ty| format!(": {ty}"))
                .unwrap_or_default();
            Some((
                format!("function {}({}){}", short, info.params, ret),
                info.documentation,
            ))
        }
        mir_analyzer::Name::Method { class: _, name } => {
            let ret = info
                .return_type
                .as_deref()
                .map(|ty| format!(": {ty}"))
                .unwrap_or_default();
            Some((
                format!("function {}({}){}", name, info.params, ret),
                info.documentation,
            ))
        }
        mir_analyzer::Name::Class(_) => Some((
            format!("function __construct({})", info.params),
            info.documentation,
        )),
        _ => None,
    }
}

fn inlay_hint_tooltip_for_symbol(
    db: &mir_analyzer::db::MirDbStorage,
    symbol: &mir_analyzer::Name,
) -> Option<String> {
    let (signature, docstring) = callable_signature_for_symbol(db, symbol)?;
    let mut value = format!("```php\n{signature}\n```");
    if let Some(docstring) = docstring.filter(|s| !s.is_empty()) {
        value.push_str("\n\n---\n\n");
        value.push_str(&docstring);
    }
    Some(value)
}

fn completion_signature_and_docstring_for_symbol(
    db: &mir_analyzer::db::MirDbStorage,
    symbol: &mir_analyzer::Name,
) -> (Option<String>, Option<String>) {
    if let Some((signature, docstring)) = callable_signature_for_symbol(db, symbol) {
        return (Some(signature), docstring.filter(|s| !s.is_empty()));
    }
    if let mir_analyzer::Name::Function(fqn) = symbol {
        let short = fqn.rsplit('\\').next().unwrap_or(fqn.as_ref());
        if mir_analyzer::is_builtin_function(short) {
            return (
                None,
                Some(format!(
                    "```php\nfunction {}()\n```\n\n[php.net documentation]({})",
                    short,
                    crate::lang::php_names::php_doc_url(short)
                )),
            );
        }
    }
    (None, None)
}

impl LanguageServer for Backend {
    async fn initialize(&self, params: InitializeParams) -> Result<InitializeResult> {
        self.handle_initialize(params).await
    }

    async fn initialized(&self, _params: InitializedParams) {
        guard_async("initialized", async move {
            self.handle_initialized(_params).await
        })
        .await
    }

    async fn did_change_configuration(&self, _params: DidChangeConfigurationParams) {
        guard_async("did_change_configuration", async move {
            // Pull the current configuration from the client rather than parsing the
            // (often-null) params.settings, which not all clients populate.
            let items = vec![ConfigurationItem {
                scope_uri: None,
                section: Some("php-lsp".to_string()),
            }];
            if let Ok(values) = self.client.configuration(items).await
                && let Some(value) = values.into_iter().next()
            {
                let roots = self.root_paths.load_full();

                // Re-read .php-lsp.json so a user who edits the file and then
                // triggers a configuration reload picks up the latest values.
                let file_cfg = crate::lang::autoload::load_project_config_json(&roots);

                if let Some(ver) = value.get("phpVersion").and_then(|v| v.as_str())
                    && !crate::lang::autoload::is_valid_php_version(ver)
                {
                    self.client
                        .log_message(
                            tower_lsp_server::ls_types::MessageType::WARNING,
                            format!(
                                "php-lsp: unsupported phpVersion {ver:?} — valid values: {}",
                                crate::lang::autoload::SUPPORTED_PHP_VERSIONS.join(", ")
                            ),
                        )
                        .await;
                }

                let file_obj = file_cfg.as_ref().filter(|v| v.is_object());
                let merged = LspConfig::merge_project_configs(file_obj, Some(&value));
                let mut cfg = LspConfig::from_value(&merged);

                // Resolve the PHP version and log what was chosen and why.
                let (ver, source) = self.resolve_php_version(cfg.php_version.as_deref());
                self.client
                    .log_message(
                        tower_lsp_server::ls_types::MessageType::INFO,
                        format!("php-lsp: using PHP {ver} ({source})"),
                    )
                    .await;
                // Clamp unsupported versions to the nearest supported one and warn.
                let ver = if source != "set by editor"
                    && !crate::lang::autoload::is_valid_php_version(&ver)
                {
                    let clamped = crate::lang::autoload::clamp_php_version(&ver);
                    self.client
                        .show_message(
                            tower_lsp_server::ls_types::MessageType::WARNING,
                            format!(
                                "php-lsp: detected PHP {ver} is outside the supported range ({}); \
                             using PHP {clamped} for analysis",
                                crate::lang::autoload::SUPPORTED_PHP_VERSIONS.join(", ")
                            ),
                        )
                        .await;
                    clamped.to_string()
                } else {
                    ver
                };
                cfg.php_version = Some(ver.clone());
                let version_changed = ver
                    .parse::<mir_analyzer::PhpVersion>()
                    .is_ok_and(|pv| self.docs.set_php_version(pv));
                self.config.store(Arc::new(cfg));
                if version_changed {
                    // set_php_version's drop_session_scoped_state cleared
                    // lsp_ws_files and nothing else repopulates it — without
                    // this, workspace_file_paths() (and everything scoped by
                    // it: references, rename, ...) silently sees an empty
                    // workspace until files are individually re-touched. The
                    // rescan below walks disk files but explicitly skips ones
                    // already open, so open buffers need re-mirroring too.
                    self.remirror_open_files();
                    self.rescan_roots_after_version_change(&roots).await;
                }
                send_refresh_requests(&self.client).await;
            }
        })
        .await
    }

    async fn did_change_workspace_folders(&self, params: DidChangeWorkspaceFoldersParams) {
        guard_async("did_change_workspace_folders", async move {
            // Remove folders from our tracked roots.
            {
                let mut roots = (**self.root_paths.load()).clone();
                for removed in &params.event.removed {
                    if let Some(path) = removed.uri.to_file_path() {
                        roots.retain(|r| r.as_path() != path.as_ref());
                    }
                }
                self.root_paths.store(Arc::new(roots));
            }

            // Add new folders and kick off background scans for each.
            let (exclude_paths, include_paths, max_indexed_files, cache_path) = {
                let cfg = self.config.load();
                let mut exclude = cfg.exclude_paths.clone();
                if !cfg.index_vendor && !exclude.iter().any(|p| p == "vendor" || p == "vendor/") {
                    exclude.push("vendor/".to_string());
                }
                (
                    exclude,
                    cfg.include_paths.clone(),
                    cfg.max_indexed_files,
                    cfg.cache_path.clone(),
                )
            };
            for added in &params.event.added {
                if let Some(path) = added.uri.to_file_path().map(|c| c.into_owned()) {
                    let is_new = {
                        let mut roots = (**self.root_paths.load()).clone();
                        if !roots.contains(&path) {
                            roots.push(path.clone());
                            self.root_paths.store(Arc::new(roots));
                            true
                        } else {
                            false
                        }
                    };
                    if is_new {
                        let docs = Arc::clone(&self.docs);
                        let open_files = self.open_files.clone();
                        let open_urls = open_files.urls();
                        let ex = exclude_paths.clone();
                        let ip = include_paths.clone();
                        let extensions = self.config.load().php_file_extensions();
                        let path_clone = path.clone();
                        let client = self.client.clone();
                        let cp = cache_path.clone();
                        let warm_analysis = self.config.load().warm_analysis;
                        tokio::spawn(async move {
                            let cache = if let Some(p) = cp {
                                Some(crate::index::cache::WorkspaceCache::with_dir(p))
                            } else {
                                crate::index::cache::WorkspaceCache::new(&path_clone)
                            };
                            scan_workspace(
                                path_clone,
                                Arc::clone(&docs),
                                open_files,
                                cache,
                                &ex,
                                &ip,
                                &extensions,
                                max_indexed_files,
                                None,
                            )
                            .await;
                            // Replay disk-cached index postings/subtype edges for
                            // this folder's files, then run the reference-warm
                            // phase (Mir's returned priority set, plus the
                            // ambient sweep when configured) — same as the boot
                            // path, so a folder added at runtime ends up as warm
                            // as the startup roots, not just scan-mirrored.
                            super::offload::run("workspaceFolders.warmStart", move || {
                                docs.get_workspace_index_salsa();
                                let untrusted = docs.warm_start_indexes();
                                docs.warm_references_phase(
                                    untrusted,
                                    &open_urls,
                                    warm_analysis,
                                    None,
                                );
                            })
                            .await;
                            send_refresh_requests(&client).await;
                        });
                    }
                }
            }
        })
        .await
    }

    async fn shutdown(&self) -> Result<()> {
        // Postings committed since the last warm sweep (on-demand query
        // freshness passes, edit re-sweeps) reach disk only via a flush.
        let docs = Arc::clone(&self.docs);
        self.blocking("shutdown.flush", move || docs.flush_analysis_cache())
            .await;
        Ok(())
    }

    #[tracing::instrument(skip_all)]
    async fn did_open(&self, params: DidOpenTextDocumentParams) {
        guard_async("did_open", async move {
            let uri = params.text_document.uri;
            let text = params.text_document.text;
            let version = params.text_document.version;
            let lifecycle_generation = super::lifecycle_generation();

            // The transport recorded a later close before this future got a
            // chance to run. Do not resurrect a document the client has
            // already closed.
            if !self
                .open_files
                .should_apply_lifecycle(&uri, lifecycle_generation, true)
            {
                return;
            }

            // Store text immediately so other features work while parsing.
            // This also mirrors the new text into salsa, so the codebase query
            // sees it when semantic_diagnostics runs below.
            self.set_open_text(uri.clone(), text);
            // didOpen can make a brand-new declaring file visible to sibling
            // open files that were analyzed earlier. Mir invalidates its own
            // resolver caches; sync only php-lsp's retained analysis_cache.
            self.docs.sync_analysis_cache_declarations(&uri);
            // Seed parse diagnostics from the salsa-cached doc. On the fast
            // path this is a lock-free DashMap lookup — no re-parse — but a
            // cache miss triggers a full parse, so keep it off the async task.
            let docs = Arc::clone(&self.docs);
            let uri_for_task = uri.clone();
            let parse_diags = self
                .blocking_gated(super::debug_gate::GATE_DID_OPEN_PARSE, move || {
                    let target = docs.workspace_php_version();
                    docs.get_doc_salsa(&uri_for_task)
                        .map(|doc| diagnostics_from_doc(&doc, target))
                        .unwrap_or_default()
                })
                .await
                .unwrap_or_default();
            if !self
                .open_files
                .should_apply_lifecycle(&uri, lifecycle_generation, true)
            {
                return;
            }
            self.set_parse_diagnostics(&uri, parse_diags);

            publish_with_dependents(
                self.client.clone(),
                Arc::clone(&self.docs),
                self.open_files.clone(),
                uri,
                DiagnosticPublish::Open {
                    version,
                    generation: lifecycle_generation,
                },
                self.config.load().diagnostics.clone(),
                self.laravel.load_full().is_laravel,
            )
            .await;
        })
        .await
    }

    #[tracing::instrument(skip_all)]
    async fn did_change(&self, params: DidChangeTextDocumentParams) {
        guard_async("did_change", async move {
            let uri = params.text_document.uri;
            let document_version = params.text_document.version;
            // Incremental sync: apply changes in order to the live buffer.
            // Each ranged change refers to the document state produced by the
            // previous one; a change without a range is a full-document
            // replacement (clients may still send those under INCREMENTAL).
            let mut updated: Option<String> = None;
            for change in params.content_changes {
                match change.range {
                    None => updated = Some(change.text),
                    Some(range) => {
                        let mut cur = match updated.take() {
                            Some(t) => t,
                            None => self.get_open_text(&uri).unwrap_or_default().to_string(),
                        };
                        crate::text::apply_content_change(&mut cur, range, &change.text);
                        updated = Some(cur);
                    }
                }
            }
            let Some(text) = updated else { return };

            // Store text immediately and capture the version token.
            // Features (completion, hover, …) see the new text instantly while
            // the parse runs in the background.
            let version = self.set_open_text(uri.clone(), text.clone());

            let docs = Arc::clone(&self.docs);
            let open_files = self.open_files.clone();
            let client = self.client.clone();
            let cfg = self.config.load();
            let diag_cfg = cfg.diagnostics.clone();
            let debounce_ms = cfg.debounce_ms;
            let warm_analysis = cfg.warm_analysis;
            let is_laravel = self.laravel.load_full().is_laravel;
            tokio::spawn(async move {
                // Debounce: if another edit arrives before we parse, the version
                // gate below will discard this result.
                tokio::time::sleep(std::time::Duration::from_millis(debounce_ms)).await;

                // Skip the expensive parse+analyze if a newer edit already
                // superseded this one. Collapses N rapid keystrokes into 1
                // spawn_blocking call instead of N.
                if open_files.current_version(&uri) != Some(version) {
                    return;
                }

                let parse_docs = Arc::clone(&docs);
                let (_doc, parse_diags) = super::offload::run("did_change.parse", move || {
                    parse_document(&text, parse_docs.workspace_php_version())
                })
                .await
                .unwrap_or_default();

                // Only apply if no newer edit arrived while we were parsing.
                if open_files.current_version(&uri) != Some(version) {
                    return;
                }
                open_files.set_parse_diagnostics(&uri, parse_diags);
                publish_with_dependents(
                    client,
                    Arc::clone(&docs),
                    open_files.clone(),
                    uri.clone(),
                    DiagnosticPublish::Other(Some(document_version)),
                    diag_cfg,
                    is_laravel,
                )
                .await;

                // Re-warm the analysis memos this edit invalidated once typing
                // goes idle, so the next references/rename stays a memo hit.
                // Unaffected files revalidate without re-analysis, so the sweep
                // cost tracks what the edit actually touched.
                if warm_analysis && docs.is_index_ready() {
                    tokio::time::sleep(std::time::Duration::from_millis(WARM_RESWEEP_IDLE_MS))
                        .await;
                    if open_files.current_version(&uri) != Some(version) {
                        return;
                    }
                    let open_urls = open_files.urls();
                    // Deliberately not `offload::run`: spawn_blocking schedules
                    // synchronously at the call, but `run`'s async body is lazy
                    // and would never even start the sweep without an `.await`
                    // this fire-and-forget site intentionally omits.
                    drop(tokio::task::spawn_blocking(move || {
                        let cancel = docs.begin_warm_sweep();
                        docs.warm_analysis_sweep(&open_urls, &cancel);
                    }));
                }
            });
        })
        .await
    }

    async fn did_close(&self, params: DidCloseTextDocumentParams) {
        guard_async("did_close", async move {
            let uri = params.text_document.uri;
            let lifecycle_generation = super::lifecycle_generation();
            // `didOpen` may have arrived after this close but begun execution
            // first. The transport ingress state is authoritative, so an old
            // close must not erase that reopened buffer.
            if !self
                .open_files
                .should_apply_lifecycle(&uri, lifecycle_generation, false)
            {
                return;
            }
            self.close_open_file(&uri);
            // The salsa-mirrored text still holds the last edited buffer, which may
            // include unsaved changes the user just discarded on close. Re-sync from
            // disk so cross-file features resolve against the on-disk content; if the
            // file is gone (never saved / deleted), drop it from the index.
            let disk_path = uri.to_file_path().map(|path| path.into_owned());
            let disk_text = self
                .blocking_gated(super::debug_gate::GATE_DID_CLOSE_DISK_SYNC, move || {
                    disk_path.and_then(|path| std::fs::read_to_string(path).ok())
                })
                .await
                .flatten();
            if !self
                .open_files
                .should_apply_lifecycle(&uri, lifecycle_generation, false)
            {
                return;
            }
            // The disk read awaited above; a reopen may have raced in. Only mutate
            // the index if the file is still closed, so we never clobber a fresh
            // buffer.
            if !self.open_files.contains(&uri) {
                match disk_text {
                    Some(text) => self.docs.ingest(uri.clone(), &text),
                    None => self.docs.remove(&uri),
                }
            }
            // Clear editor diagnostics; the file stays indexed for cross-file features
            self.client.publish_diagnostics(uri, vec![], None).await;
        })
        .await
    }

    async fn will_save(&self, _params: WillSaveTextDocumentParams) {}

    async fn will_save_wait_until(
        &self,
        params: WillSaveTextDocumentParams,
    ) -> Result<Option<Vec<TextEdit>>> {
        guard_async_result("will_save_wait_until", async move {
            let source = self
                .get_open_text(&params.text_document.uri)
                .unwrap_or_default();
            // Spawns and blocks on an external formatter process; keep that
            // wait off the async runtime worker.
            Ok(self
                .blocking("willSaveWaitUntil.format", move || format_document(&source))
                .await
                .unwrap_or_default())
        })
        .await
    }

    async fn did_save(&self, params: DidSaveTextDocumentParams) {
        guard_async("did_save", async move {
            let uri = params.text_document.uri;
            // Re-publish diagnostics on save so editors that defer diagnostics
            // until save (rather than on every keystroke) see up-to-date results.
            // Must include semantic diagnostics — publishDiagnostics replaces the
            // prior set entirely, so omitting them would clear errors the editor
            // showed after the last did_change.
            let diag_cfg = self.config.load().diagnostics.clone();
            let is_laravel = self.laravel.load_full().is_laravel;
            // Includes the semantic (mir) analysis pass, same as
            // `publish_with_dependents` — keep it off the async runtime worker
            // here too, not just on the did_open/did_change path.
            let docs = Arc::clone(&self.docs);
            let open_files = self.open_files.clone();
            let uri_for_diags = uri.clone();
            let all = self
                .blocking_gated(super::debug_gate::GATE_DID_SAVE_DIAGNOSTICS, move || {
                    compute_open_file_diagnostics(
                        &docs,
                        &open_files,
                        &uri_for_diags,
                        &diag_cfg,
                        is_laravel,
                    )
                })
                .await
                .unwrap_or_default();
            self.open_files
                .note_published(&uri, super::diagnostics_content_hash(&all));
            self.client
                .publish_diagnostics(uri.clone(), all, None)
                .await;

            // Persist the FileIndex to the disk cache so that a server restart
            // can skip re-parsing this file even for edits that happened between
            // workspace scans. Content-keyed so the entry matches the scan's key
            // on restart regardless of mtime granularity.
            let cache_path = self.config.load().cache_path.clone();
            if let Some(path) = uri.to_file_path().map(|c| c.into_owned()) {
                let root = self.root_paths.load().first().cloned();
                // Deliberately not `offload::run` — see the fire-and-forget
                // comment on `did_change`'s warm-resweep; this cache write is
                // never awaited either.
                tokio::task::spawn_blocking({
                    let path = path.clone();
                    let uri = uri.clone();
                    let root = root.clone();
                    move || {
                        let cache = if let Some(p) = cache_path {
                            crate::index::cache::WorkspaceCache::with_dir(p)
                        } else if let Some(r) = &root {
                            let Some(c) = crate::index::cache::WorkspaceCache::new(r) else {
                                return;
                            };
                            c
                        } else {
                            return;
                        };
                        let Ok(text) = std::fs::read_to_string(&path) else {
                            return;
                        };
                        let key = crate::index::cache::WorkspaceCache::key_for(uri.as_str(), &text);
                        let doc = parse_document_no_diags(&text);
                        let index = crate::index::file_index::FileIndex::extract(&doc);
                        let _ = cache.write(&key, &index);
                    }
                });

                // External tools (PHPStan/PHPCS) are opt-in and much slower
                // than the in-process analyzer, so they run in the background
                // and republish once done rather than delaying the publish
                // above. Guarded by the version token so an edit that lands
                // while the tool is still running discards its result instead
                // of showing diagnostics against text the buffer no longer
                // holds.
                let ext_cfg = self.config.load().external_tools.clone();
                if (ext_cfg.phpstan.enabled || ext_cfg.phpcs.enabled)
                    && let Some(version) = self.open_files.current_version(&uri)
                {
                    let client = self.client.clone();
                    let docs = Arc::clone(&self.docs);
                    let open_files = self.open_files.clone();
                    let diag_cfg = self.config.load().diagnostics.clone();
                    let uri = uri.clone();
                    tokio::spawn(async move {
                        let diagnostics = crate::analysis::external::run_external_diagnostics(
                            &ext_cfg,
                            &path,
                            root.as_deref(),
                        )
                        .await;
                        if open_files.current_version(&uri) != Some(version) {
                            return;
                        }
                        open_files.set_external_diagnostics(&uri, version, diagnostics);
                        publish_with_dependents(
                            client,
                            docs,
                            open_files,
                            uri,
                            DiagnosticPublish::Other(None),
                            diag_cfg,
                            is_laravel,
                        )
                        .await;
                    });
                }
            }
        })
        .await
    }

    async fn did_change_watched_files(&self, params: DidChangeWatchedFilesParams) {
        guard_async("did_change_watched_files", async move {
            enum Change {
                Upsert(Uri, String),
                Delete(Uri),
            }
            let mut changes = Vec::with_capacity(params.changes.len());
            for change in params.changes {
                match change.typ {
                    FileChangeType::CREATED | FileChangeType::CHANGED => {
                        if let Some(path) = change.uri.to_file_path()
                            && let Ok(text) = tokio::fs::read_to_string(&path).await
                        {
                            changes.push(Change::Upsert(change.uri.clone(), text));
                        }
                    }
                    FileChangeType::DELETED => changes.push(Change::Delete(change.uri.clone())),
                    _ => {}
                }
            }

            // Parsing is CPU-bound and a bulk change (git checkout, a
            // generator run) can cover hundreds of files at once; process
            // the whole batch in one spawn_blocking call instead of
            // re-entering the blocking pool per file.
            let docs = Arc::clone(&self.docs);
            let open_files = self.open_files.clone();
            self.blocking_gated(
                super::debug_gate::GATE_DID_CHANGE_WATCHED_FILES,
                move || {
                    for change in changes {
                        match change {
                            Change::Upsert(uri, text) => {
                                // Salsa path: ingest_from_doc mirrors the new text into
                                // the SourceFile input. On the next codebase() call,
                                // salsa re-runs file_definitions for this file and the
                                // aggregator re-folds — no manual remove/collect/finalize.
                                let doc = parse_document_no_diags(&text);
                                if !open_files.contains(&uri) {
                                    docs.ingest_from_doc(uri.clone(), &doc);
                                }
                                // Keep php-lsp's retained FileAnalysis cache
                                // coherent for consumers analyzed before this
                                // external file change landed. Mir handles its
                                // own workspace invalidation.
                                docs.sync_analysis_cache_declarations(&uri);
                            }
                            Change::Delete(uri) => docs.remove(&uri),
                        }
                    }
                },
            )
            .await;
            // File changes may affect cross-file features — refresh all live editors.
            send_refresh_requests(&self.client).await;

            // Bulk external changes (git checkout, generators) invalidate many
            // analysis memos at once; re-warm so references stay fast after a
            // branch switch, not just after in-editor edits.
            if self.config.load().warm_analysis && self.docs.is_index_ready() {
                let docs = Arc::clone(&self.docs);
                let open_urls = self.open_files.urls();
                // Deliberately not `offload::run` — see the matching comment
                // in `did_change`'s warm-resweep.
                drop(tokio::task::spawn_blocking(move || {
                    let cancel = docs.begin_warm_sweep();
                    docs.warm_analysis_sweep(&open_urls, &cancel);
                }));
            }
        })
        .await
    }

    #[tracing::instrument(skip_all)]
    async fn completion(&self, params: CompletionParams) -> Result<Option<CompletionResponse>> {
        guard_async_result("completion", async move {
            // Held for the request's lifetime so a concurrent background
            // warm/reanalysis sweep yields at its next chunk boundary
            // instead of racing this interactive read for CPU/rayon workers.
            let _interactive = self.docs.interactive_read_guard();
            let uri = &params.text_document_position.text_document.uri;
            let position = params.text_document_position.position;
            let cancel_rev = self.docs.write_rev();
            let source = self.get_open_text(uri).unwrap_or_default();
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(Some(CompletionResponse::Array(vec![]))),
            };
            let other_docs: Vec<Arc<ParsedDoc>> = self
                .docs
                .other_docs(uri, &self.open_urls())
                .into_iter()
                .map(|(_, d)| d)
                .collect();
            // Clone to owned so the closure is 'static + Send.
            let trigger = params
                .context
                .as_ref()
                .and_then(|c| c.trigger_character.clone());
            let laravel_arc = self.laravel.load_full();
            let imports = self.file_imports(uri);
            let wi = self.workspace_index_async().await;
            let wi_for_class_search = Arc::clone(&wi);
            let uri_for_class_search = uri.clone();
            let docs_for_lookup = Arc::clone(&self.docs);
            let doc_for_lookup = Arc::clone(&doc);
            let imports_for_lookup = imports.clone();
            let find_class_doc_fn = move |name: &str| -> Option<Arc<ParsedDoc>> {
                let fqn = class_lookup_fqn(&doc_for_lookup, name, &imports_for_lookup);
                let cr = docs_for_lookup
                    .resolve_class_ref_by_fqn(&wi, &fqn)
                    .or_else(|| {
                        if !is_bare_php_name(name) {
                            return None;
                        }
                        let name_lc = name.to_lowercase();
                        let table = &wi.classes_by_lowercase_name;
                        let pos =
                            table.partition_point(|(short, _)| short.as_ref() < name_lc.as_str());
                        table.get(pos).and_then(|(short, cr)| {
                            (short.as_ref() == name_lc.as_str()).then_some(*cr)
                        })
                    })?;
                let (uri, _) = wi.at(cr)?;
                docs_for_lookup.get_doc_salsa(uri)
            };
            // Finds classes anywhere in the workspace index — including
            // vendor/ and other files that are never opened as editor
            // buffers — whose short name starts with `prefix`. Complements
            // `other_docs`, which only covers currently open documents.
            //
            // `classes_by_lowercase_name` is sorted once per workspace
            // revision (shared via `Arc` across every completion request
            // until a file changes), so this does a binary search for the
            // prefix range instead of scanning + re-lowercasing every class
            // name on every keystroke.
            const WORKSPACE_CLASS_SEARCH_LIMIT: usize = 50;
            let workspace_class_search_fn =
                move |prefix: &str| -> Vec<(String, CompletionItemKind, String)> {
                    let prefix_lc = prefix.to_lowercase();
                    let table = &wi_for_class_search.classes_by_lowercase_name;
                    let start =
                        table.partition_point(|(name, _)| name.as_ref() < prefix_lc.as_str());
                    let mut out = Vec::new();
                    for (name, cr) in &table[start..] {
                        if !name.starts_with(prefix_lc.as_str()) {
                            break;
                        }
                        let Some((file_uri, cls)) = wi_for_class_search.at(*cr) else {
                            continue;
                        };
                        if *file_uri == uri_for_class_search {
                            continue;
                        }
                        let kind = match cls.kind {
                            ClassKind::Class | ClassKind::Trait => CompletionItemKind::CLASS,
                            ClassKind::Interface => CompletionItemKind::INTERFACE,
                            ClassKind::Enum => CompletionItemKind::ENUM,
                        };
                        out.push((cls.name.to_string(), kind, cls.fqn.to_string()));
                        if out.len() >= WORKSPACE_CLASS_SEARCH_LIMIT {
                            break;
                        }
                    }
                    out
                };
            let analysis = self
                .cached_analysis_async_cancellable(uri, cancel_rev)
                .await;
            let docs = Arc::clone(&self.docs);
            let uri_owned = uri.clone();
            // Offload to spawn_blocking: filtered_completions_at walks the full
            // AST + workspace index which can take tens of milliseconds on large
            // files, blocking the async executor from unrelated requests.
            let items = self
                .blocking("completion", move || {
                    let ctx = CompletionCtx {
                        source: Some(&source),
                        position: Some(position),
                        doc_uri: Some(&uri_owned),
                        file_imports: Some(&imports),
                        find_class_doc: Some(&find_class_doc_fn),
                        workspace_class_search: Some(&workspace_class_search_fn),
                        analysis: analysis.as_deref(),
                        session: Some(&docs),
                        laravel: Some(&laravel_arc),
                    };
                    filtered_completions_at(&doc, &other_docs, trigger.as_deref(), &ctx)
                })
                .await
                .unwrap_or_default();
            Ok(Some(CompletionResponse::Array(items)))
        })
        .await
    }

    async fn completion_resolve(&self, mut item: CompletionItem) -> Result<CompletionItem> {
        guard_async_result("completion_resolve", async move {
            if item.documentation.is_some() && item.detail.is_some() {
                return Ok(item);
            }
            // Strip trailing ':' from named-argument labels (e.g. "param:") before lookup.
            let name = item.label.trim_end_matches(':').to_string();
            // Method completion items carry their owning class in `data` (see
            // member.rs's all_members) so two unrelated classes declaring a
            // same-named method don't resolve to whichever is indexed first.
            let class_hint = item
                .data
                .as_ref()
                .and_then(|d| d.get("class"))
                .and_then(|v| v.as_str())
                .map(str::to_string);
            let symbol = completion_symbol_from_item(&name, item.kind, class_hint.as_deref());
            let need_detail = item.detail.is_none();
            let need_docs = item.documentation.is_none();
            let docs = Arc::clone(&self.docs);
            let (detail, documentation) = self
                .blocking_gated(super::debug_gate::GATE_COMPLETION_RESOLVE, move || {
                    let Some(symbol) = symbol.as_ref() else {
                        return (None, None);
                    };
                    let (resolved_detail, resolved_docstring) = docs
                        .read_snapshot(|snap| {
                            completion_signature_and_docstring_for_symbol(snap.db(), symbol)
                        })
                        .unwrap_or_default();
                    let detail = if need_detail {
                        resolved_detail.clone()
                    } else {
                        None
                    };
                    let documentation = need_docs
                        .then(|| {
                            match (resolved_detail.as_deref(), resolved_docstring.as_deref()) {
                                (Some(_), Some(doc)) if need_detail => Some(doc.to_string()),
                                (Some(sig), Some(doc)) => {
                                    Some(format!("```php\n{sig}\n```\n\n---\n\n{doc}"))
                                }
                                (Some(sig), None) => Some(format!("```php\n{sig}\n```")),
                                (None, Some(doc)) => Some(doc.to_string()),
                                (None, None) => None,
                            }
                        })
                        .flatten();
                    (detail, documentation)
                })
                .await
                .unwrap_or_default();
            if let Some(sig) = detail {
                item.detail = Some(sig);
            }
            if let Some(md) = documentation {
                item.documentation = Some(Documentation::MarkupContent(MarkupContent {
                    kind: MarkupKind::Markdown,
                    value: md,
                }));
            }
            Ok(item)
        })
        .await
    }

    async fn goto_definition(
        &self,
        params: GotoDefinitionParams,
    ) -> Result<Option<GotoDefinitionResponse>> {
        guard_async_result("goto_definition", async move {
            self.handle_goto_definition(params).await
        })
        .await
    }

    async fn references(&self, params: ReferenceParams) -> Result<Option<Vec<Location>>> {
        guard_async_result(
            "references",
            async move { self.handle_references(params).await },
        )
        .await
    }

    async fn prepare_rename(
        &self,
        params: TextDocumentPositionParams,
    ) -> Result<Option<PrepareRenameResponse>> {
        guard_async_result("prepare_rename", async move {
            let uri = &params.text_document.uri;
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            let position = params.position;
            // For a keyword-shaped identifier (`match`, `list`, ...),
            // `prepare_rename` walks the whole AST to check whether it's used
            // as a real member name; keep that off the async runtime worker.
            let range = self
                .blocking_gated(super::debug_gate::GATE_PREPARE_RENAME, move || {
                    prepare_rename(&doc, position)
                })
                .await
                .unwrap_or_default();
            Ok(range.map(PrepareRenameResponse::Range))
        })
        .await
    }

    async fn rename(&self, params: RenameParams) -> Result<Option<WorkspaceEdit>> {
        guard_async_result("rename", async move {
            let uri = &params.text_document_position.text_document.uri;
            let position = params.text_document_position.position;
            let source = self.get_open_text(uri).unwrap_or_default();
            let word = match word_at_position(&source, position) {
                Some(w) => w,
                None => return Ok(None),
            };
            if word.starts_with('$') {
                let doc = match self.get_doc(uri) {
                    Some(d) => d,
                    None => return Ok(None),
                };
                // Cursor on a property declaration (`public int $x`) or a promoted
                // constructor parameter (`private string $x`) — both act as property
                // declarations and take the cross-file indexed path below. Plain
                // variables stay on the single-document scope walker. Both checks
                // and the walker itself scan every class member/statement in the
                // document, so keep them off the async runtime worker.
                let word_task = word.clone();
                let new_name = params.new_name.clone();
                let uri_task = uri.clone();
                let doc_task = Arc::clone(&doc);
                let source_task = Arc::clone(&source);
                let variable_edit = self
                    .blocking_gated(super::debug_gate::GATE_RENAME_VARIABLE, move || {
                        let on_property_decl = cursor_is_on_property_decl(
                            &source_task,
                            &doc_task.program().stmts,
                            position,
                        )
                        .is_some()
                            || promoted_property_at_cursor(
                                &source_task,
                                &doc_task.program().stmts,
                                position,
                            )
                            .is_some();
                        if on_property_decl {
                            None
                        } else {
                            Some(rename_variable(
                                &word_task, &new_name, &uri_task, &doc_task, position,
                            ))
                        }
                    })
                    .await
                    .flatten();
                if let Some(edit) = variable_edit {
                    return Ok(Some(edit));
                }
            }
            // Everything else — classes, functions, methods, properties,
            // constants — renames from mir's posting lists (declaration
            // token and `use` import lines included).
            Ok(self.indexed_rename(uri, position, &params.new_name).await)
        })
        .await
    }

    async fn signature_help(&self, params: SignatureHelpParams) -> Result<Option<SignatureHelp>> {
        guard_async_result("signature_help", async move {
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let source = self.get_open_text(uri).unwrap_or_default();
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            let analysis = self.cached_analysis_async(uri).await;
            let docs = Arc::clone(&self.docs);
            let doc_clone = Arc::clone(&doc);
            let result = self
                .blocking("signature_help", move || {
                    docs.read_snapshot(|snap| {
                        signature_help(
                            &source,
                            &doc_clone,
                            position,
                            analysis.as_deref(),
                            Some(snap.db()),
                        )
                    })
                    .ok()
                })
                .await
                .flatten()
                .flatten();
            Ok(result)
        })
        .await
    }

    #[tracing::instrument(skip_all)]
    async fn hover(&self, params: HoverParams) -> Result<Option<Hover>> {
        guard_async_result("hover", async move {
            // Held for the request's lifetime so a concurrent background
            // warm/reanalysis sweep yields at its next chunk boundary
            // instead of racing this interactive read for CPU/rayon workers.
            let _interactive = self.docs.interactive_read_guard();
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let mut source = self.get_open_text(uri).unwrap_or_default();
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => {
                    // tower-lsp-server polls concurrent inbound messages out
                    // of order. A hover sent immediately after didClose then
                    // didOpen can therefore run while the earlier didOpen is
                    // queued but has not yet installed its buffer. Yield one
                    // turn only on this closed-document path so that lifecycle
                    // notification can publish its state; ordinary hovers keep
                    // the zero-yield fast path.
                    tokio::task::yield_now().await;
                    source = self.get_open_text(uri).unwrap_or_default();
                    match self.get_doc(uri) {
                        Some(d) => d,
                        None => return Ok(None),
                    }
                }
            };
            // Laravel string-key calls (`env('KEY')`, `config('a.b')`, ...) —
            // resolved before the general hover pipeline below, since a
            // string literal is never a `word_at_position` match. Mirrors
            // `handle_goto_definition`'s same early check.
            let laravel = self.laravel.load();
            let laravel_root = self.root_paths.load().first().cloned();
            let laravel_hover = crate::laravel::hover_for_string_key(
                &doc,
                position,
                &laravel,
                laravel_root.as_deref(),
            )
            .or_else(|| {
                crate::laravel::blade::hover(
                    uri,
                    &source,
                    position,
                    &laravel,
                    laravel_root.as_deref(),
                )
            });
            drop(laravel);
            if let Some(hover) = laravel_hover {
                return Ok(Some(hover));
            }
            let open = self.open_urls();
            let other_docs = self.docs.other_docs(uri, &open);
            let other_maps = self.docs.other_symbol_maps(uri, &open);
            let analysis = self.cached_analysis_async(uri).await;
            let docs_for_hover = Arc::clone(&self.docs);
            let source_clone = source.clone();
            let doc_clone = Arc::clone(&doc);
            // Lets mir-member/static-prop hover resolve a class's declaring doc
            // via the workspace index even when that file isn't open in the
            // editor, instead of only searching `other_docs` (open files).
            // Cached across this request: nothing between here and the
            // fallback branch below lazily ingests a new vendor file, so the
            // same Arc is safe to reuse instead of re-awaiting the index.
            let mut wi_cache: Option<Arc<crate::db::workspace_index::WorkspaceIndexData>> = None;
            let wi = self.workspace_index_cached(&mut wi_cache).await;
            let docs_for_lookup = Arc::clone(&self.docs);
            let imports_for_lookup = doc.file_imports();
            let doc_for_lookup = Arc::clone(&doc);
            let find_class_doc_fn = move |name: &str| -> Option<Arc<ParsedDoc>> {
                let fqn = class_lookup_fqn(&doc_for_lookup, name, &imports_for_lookup);
                let cr = docs_for_lookup
                    .resolve_class_ref_by_fqn(&wi, &fqn)
                    .or_else(|| {
                        if !is_bare_php_name(name) {
                            return None;
                        }
                        let name_lc = name.to_lowercase();
                        let table = &wi.classes_by_lowercase_name;
                        let pos =
                            table.partition_point(|(short, _)| short.as_ref() < name_lc.as_str());
                        table.get(pos).and_then(|(short, cr)| {
                            (short.as_ref() == name_lc.as_str()).then_some(*cr)
                        })
                    })?;
                let (uri, _) = wi.at(cr)?;
                docs_for_lookup.get_doc_salsa(uri)
            };
            let result = self
                .blocking("hover", move || {
                    hover_info_with_maps(
                        &source_clone,
                        &doc_clone,
                        analysis.as_deref(),
                        position,
                        &other_docs,
                        &other_maps,
                        Some(&docs_for_hover),
                        Some(&find_class_doc_fn),
                    )
                })
                .await
                .flatten();
            if result.is_some() {
                return Ok(result);
            }
            // Fallback: look up the word in the workspace index so class names in
            // extends clauses and parameter types resolve even when their defining
            // file is never opened.  Also try the alias-resolved name so that
            // `use Foo as Bar` works even when Foo is only in the index.
            if let Some(word) = crate::text::word_at_position(&source, position) {
                let wi = self.workspace_index_cached(&mut wi_cache).await;
                let docs = Arc::clone(&self.docs);
                let doc = Arc::clone(&doc);
                let source = source.clone();
                let uri = uri.clone();
                // Off the async worker: every step below takes the session lock.
                let fallback = self
                    .blocking("hover_fallback", move || {
                        let fallback_imports = doc.file_imports();
                        let fallback_class_fqcn = |name: &str| {
                            let fqn = class_lookup_fqn(&doc, name, &fallback_imports);
                            docs.resolve_class_ref_by_fqn(&wi, &fqn).and_then(|cr| {
                                wi.at(cr)
                                    .map(|(_, cls)| normalized_php_fqn(&cls.fqn).to_string())
                            })
                        };
                        // mir resolves the cursor class through imports, aliases and the
                        // namespace, so same-short-named classes can't be confused.
                        if let Some(offset) = crate::text::word_range_at(&source, position)
                            .map(|r| doc.view().byte_of_position(r.start))
                            && let Ok(Some(mir_analyzer::Name::Class(fqcn))) =
                                docs.mir_name_at(&uri, offset)
                            && let Some(h) = docs
                                .read_snapshot(|snap| class_hover_for_fqcn(snap, &fqcn))
                                .ok()
                                .flatten()
                        {
                            return Some(h);
                        }
                        // Try static method hover: `ClassName::method(…)`.
                        if let Some(line_text) = source.lines().nth(position.line as usize)
                            && let Some(class_token) = extract_static_class_before_cursor(
                                line_text,
                                position.character as usize,
                            )
                        {
                            if let Some(fqcn) = fallback_class_fqcn(&class_token)
                                && let Some(h) = docs
                                    .read_snapshot(|snap| method_hover_for_fqcn(snap, &fqcn, &word))
                                    .ok()
                                    .flatten()
                            {
                                return Some(h);
                            }
                            if let Some(resolved_class) =
                                crate::hover::resolve_use_alias(&doc.program().stmts, &class_token)
                                && let Some(fqcn) = fallback_class_fqcn(&resolved_class)
                                && let Some(h) = docs
                                    .read_snapshot(|snap| method_hover_for_fqcn(snap, &fqcn, &word))
                                    .ok()
                                    .flatten()
                            {
                                return Some(h);
                            }
                        }
                        None
                    })
                    .await
                    .flatten();
                return Ok(fallback);
            }
            Ok(None)
        })
        .await
    }

    async fn document_symbol(
        &self,
        params: DocumentSymbolParams,
    ) -> Result<Option<DocumentSymbolResponse>> {
        guard_async_result("document_symbol", async move {
            let uri = &params.text_document.uri;
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            // The AST walk is CPU-bound; keep it off the async runtime worker.
            let symbols = self
                .blocking_gated(super::debug_gate::GATE_DOCUMENT_SYMBOL, move || {
                    document_symbols(doc.source(), &doc)
                })
                .await
                .unwrap_or_default();
            Ok(Some(DocumentSymbolResponse::Nested(symbols)))
        })
        .await
    }

    async fn folding_range(&self, params: FoldingRangeParams) -> Result<Option<Vec<FoldingRange>>> {
        guard_async_result("folding_range", async move {
            let uri = &params.text_document.uri;
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            // The AST walk plus full-text comment/region scans are CPU-bound;
            // keep them off the async runtime worker.
            let ranges = self
                .blocking_gated(super::debug_gate::GATE_FOLDING_RANGE, move || {
                    folding_ranges(doc.source(), &doc)
                })
                .await
                .unwrap_or_default();
            Ok(if ranges.is_empty() {
                None
            } else {
                Some(ranges)
            })
        })
        .await
    }

    async fn inlay_hint(&self, params: InlayHintParams) -> Result<Option<Vec<InlayHint>>> {
        guard_async_result("inlay_hint", async move {
            let uri = &params.text_document.uri;
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            let analysis = self.cached_analysis_async(uri).await;
            let docs = Arc::clone(&self.docs);
            let hints = self
                .blocking("inlay_hint", move || {
                    docs.read_snapshot(|snap| {
                        inlay_hints(
                            doc.source(),
                            &doc,
                            analysis.as_deref(),
                            Some(snap.db()),
                            params.range,
                        )
                    })
                    .unwrap_or_default()
                })
                .await
                .unwrap_or_default();
            Ok(Some(hints))
        })
        .await
    }

    async fn inlay_hint_resolve(&self, mut item: InlayHint) -> Result<InlayHint> {
        let fallback = item.clone();
        let resolved = guard_async("inlay_hint_resolve", async move {
            if item.tooltip.is_some() {
                return Some(item);
            }
            let symbol = item.data.as_ref().and_then(inlay_hint_symbol_from_data);
            if let Some(symbol) = symbol {
                let docs = Arc::clone(&self.docs);
                let tooltip = self
                    .blocking_gated(super::debug_gate::GATE_INLAY_HINT_RESOLVE, move || {
                        docs.read_snapshot(|snap| inlay_hint_tooltip_for_symbol(snap.db(), &symbol))
                            .ok()
                    })
                    .await
                    .flatten()
                    .flatten();
                if let Some(md) = tooltip {
                    item.tooltip = Some(InlayHintTooltip::MarkupContent(MarkupContent {
                        kind: MarkupKind::Markdown,
                        value: md,
                    }));
                }
            }
            Some(item)
        })
        .await;
        Ok(resolved.unwrap_or(fallback))
    }

    async fn symbol(
        &self,
        params: WorkspaceSymbolParams,
    ) -> Result<Option<WorkspaceSymbolResponse>> {
        guard_async_result("symbol", async move {
            // Phase J: read through the salsa-memoized aggregate so repeated
            // workspace-symbol queries (every keystroke in the picker) share the
            // same `Arc` until a file changes.
            let wi = self.workspace_index_async().await;
            let docs = Arc::clone(&self.docs);
            let query = params.query;
            let results = self
                .blocking("workspace/symbol", move || {
                    let get_doc = |uri: &Uri| docs.get_doc_salsa(uri);
                    workspace_symbols_from_workspace(&query, &wi, &get_doc)
                })
                .await
                .unwrap_or_default();
            Ok(Some(WorkspaceSymbolResponse::Flat(results)))
        })
        .await
    }

    async fn symbol_resolve(&self, params: WorkspaceSymbol) -> Result<WorkspaceSymbol> {
        // For resolve, we need the full range from the ParsedDoc of open files.
        let docs = self.docs.docs_for(&self.open_urls());
        let fallback = params.clone();
        let resolved = guard_async("symbol_resolve", async move {
            Some(resolve_workspace_symbol(params, &docs))
        })
        .await;
        Ok(resolved.unwrap_or(fallback))
    }

    #[tracing::instrument(skip_all)]
    async fn semantic_tokens_full(
        &self,
        params: SemanticTokensParams,
    ) -> Result<Option<SemanticTokensResult>> {
        guard_async_result("semantic_tokens_full", async move {
            let uri = params.text_document.uri;
            let doc = match self.get_doc(&uri) {
                Some(d) => d,
                None => {
                    return Ok(Some(SemanticTokensResult::Tokens(SemanticTokens {
                        result_id: None,
                        data: vec![],
                    })));
                }
            };
            let docs = Arc::clone(&self.docs);
            let uri_for_task = uri.clone();
            // The AST walk is CPU-bound; keep it off the async runtime worker
            // (see `document_highlight` for the same pattern).
            let (result_id, data) = self
                .blocking_gated(super::debug_gate::GATE_SEMANTIC_TOKENS_FULL, move || {
                    let tokens = semantic_tokens(doc.source(), &doc);
                    let result_id = token_hash(&tokens);
                    let tokens_arc = Arc::new(tokens);
                    docs.store_token_cache(
                        &uri_for_task,
                        result_id.clone(),
                        Arc::clone(&tokens_arc),
                    );
                    let data = Arc::try_unwrap(tokens_arc).unwrap_or_else(|arc| (*arc).clone());
                    (result_id, data)
                })
                .await
                .unwrap_or_default();
            Ok(Some(SemanticTokensResult::Tokens(SemanticTokens {
                result_id: Some(result_id),
                data,
            })))
        })
        .await
    }

    async fn semantic_tokens_range(
        &self,
        params: SemanticTokensRangeParams,
    ) -> Result<Option<SemanticTokensRangeResult>> {
        guard_async_result("semantic_tokens_range", async move {
            let uri = params.text_document.uri;
            let doc = match self.get_doc(&uri) {
                Some(d) => d,
                None => {
                    return Ok(Some(SemanticTokensRangeResult::Tokens(SemanticTokens {
                        result_id: None,
                        data: vec![],
                    })));
                }
            };
            let range = params.range;
            let tokens = self
                .blocking_gated(super::debug_gate::GATE_SEMANTIC_TOKENS_RANGE, move || {
                    semantic_tokens_range(doc.source(), &doc, range)
                })
                .await
                .unwrap_or_default();
            Ok(Some(SemanticTokensRangeResult::Tokens(SemanticTokens {
                result_id: None,
                data: tokens,
            })))
        })
        .await
    }

    async fn semantic_tokens_full_delta(
        &self,
        params: SemanticTokensDeltaParams,
    ) -> Result<Option<SemanticTokensFullDeltaResult>> {
        guard_async_result("semantic_tokens_full_delta", async move {
            let uri = params.text_document.uri;
            let doc = match self.get_doc(&uri) {
                Some(d) => d,
                None => return Ok(None),
            };

            let docs = Arc::clone(&self.docs);
            let uri_for_task = uri.clone();
            let prev_id = params.previous_result_id;
            let result = self
                .blocking_gated(
                    super::debug_gate::GATE_SEMANTIC_TOKENS_FULL_DELTA,
                    move || {
                        let new_tokens = Arc::new(semantic_tokens(doc.source(), &doc));
                        let new_result_id = token_hash(&new_tokens);

                        let result = match docs.get_token_cache(&uri_for_task, &prev_id) {
                            Some(old_tokens) => {
                                let edits = compute_token_delta(&old_tokens, &new_tokens);
                                SemanticTokensFullDeltaResult::TokensDelta(SemanticTokensDelta {
                                    result_id: Some(new_result_id.clone()),
                                    edits,
                                })
                            }
                            // Unknown previous result — fall back to full tokens
                            None => SemanticTokensFullDeltaResult::Tokens(SemanticTokens {
                                result_id: Some(new_result_id.clone()),
                                data: (*new_tokens).clone(),
                            }),
                        };

                        docs.store_token_cache(&uri_for_task, new_result_id, new_tokens);
                        result
                    },
                )
                .await;
            let Some(result) = result else {
                return Ok(None);
            };
            Ok(Some(result))
        })
        .await
    }

    async fn selection_range(
        &self,
        params: SelectionRangeParams,
    ) -> Result<Option<Vec<SelectionRange>>> {
        guard_async_result("selection_range", async move {
            let uri = &params.text_document.uri;
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            // Walks every top-level statement per requested position; keep
            // that off the async runtime worker, same as document_symbol
            // and folding_range's whole-document walks.
            let ranges = self
                .blocking_gated(super::debug_gate::GATE_SELECTION_RANGE, move || {
                    selection_ranges(&doc, &params.positions)
                })
                .await
                .unwrap_or_default();
            Ok(if ranges.is_empty() {
                None
            } else {
                Some(ranges)
            })
        })
        .await
    }

    async fn prepare_call_hierarchy(
        &self,
        params: CallHierarchyPrepareParams,
    ) -> Result<Option<Vec<CallHierarchyItem>>> {
        guard_async_result("prepare_call_hierarchy", async move {
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let source = self.get_open_text(uri).unwrap_or_default();
            let word = match word_at_position(&source, position) {
                Some(w) => w,
                None => return Ok(None),
            };
            // A bare keyword can never be a callable name; skip it here so it
            // doesn't fall through to the trait-alias exhaustive scan in
            // `prepare_call_hierarchy_indexed`.
            if is_unresolvable_bareword_at(&source, position, &word) {
                return Ok(None);
            }
            // O(matches) lookup via mir's mention index instead of scanning
            // every workspace doc, but a miss falls through to a
            // workspace-wide trait-alias scan — keep that off the async
            // runtime worker, same as incoming_calls/outgoing_calls below.
            let wi = self.workspace_index_async().await;
            let docs = Arc::clone(&self.docs);
            let cursor_uri = uri.clone();
            let item = self
                .blocking_gated(super::debug_gate::GATE_PREPARE_CALL_HIERARCHY, move || {
                    let get_doc = |u: &Uri| docs.get_doc_salsa(u);
                    let mention_candidates =
                        |name: &str| docs.declaration_candidate_files(&wi, name);
                    prepare_call_hierarchy_indexed(
                        &word,
                        (&cursor_uri, position),
                        &wi,
                        &get_doc,
                        &mention_candidates,
                    )
                })
                .await
                .flatten();
            Ok(item.map(|item| vec![item]))
        })
        .await
    }

    async fn incoming_calls(
        &self,
        params: CallHierarchyIncomingCallsParams,
    ) -> Result<Option<Vec<CallHierarchyIncomingCall>>> {
        guard_async_result("incoming_calls", async move {
            // Call sites come from mir's posting lists; only the documents
            // containing them are parsed to resolve the enclosing caller.
            let docs = Arc::clone(&self.docs);
            let item = params.item;
            let calls = self
                .blocking("incoming_calls", move || {
                    // Pause the background scan and snapshot a settled revision so
                    // only a genuine user edit cancels the lookup.
                    let (_interactive, cancel_rev) = docs.settled_write_rev_guard();
                    incoming_calls_indexed(&item, &docs, Some(cancel_rev))
                })
                .await
                .unwrap_or_default();
            Ok(if calls.is_empty() { None } else { Some(calls) })
        })
        .await
    }

    async fn outgoing_calls(
        &self,
        params: CallHierarchyOutgoingCallsParams,
    ) -> Result<Option<Vec<CallHierarchyOutgoingCall>>> {
        guard_async_result("outgoing_calls", async move {
            let docs = Arc::clone(&self.docs);
            let item = params.item;
            let calls = self
                .blocking("outgoing_calls", move || {
                    outgoing_calls_via_mir(&docs, &item).unwrap_or_default()
                })
                .await
                .unwrap_or_default();
            Ok(if calls.is_empty() { None } else { Some(calls) })
        })
        .await
    }

    async fn document_highlight(
        &self,
        params: DocumentHighlightParams,
    ) -> Result<Option<Vec<DocumentHighlight>>> {
        guard_async_result("document_highlight", async move {
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let source = self.get_open_text(uri).unwrap_or_default();
            // Stale-tolerant: a highlight fired on every cursor move must never
            // spin on the salsa `Cancelled` retry loop while the user types.
            let doc = match self.get_doc_stale(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            // The AST walk is CPU-bound; keep it off the async runtime worker.
            let highlights = self
                .blocking("document_highlight", move || {
                    document_highlights(&source, &doc, position)
                })
                .await
                .unwrap_or_default();
            Ok(if highlights.is_empty() {
                None
            } else {
                Some(highlights)
            })
        })
        .await
    }

    async fn linked_editing_range(
        &self,
        params: LinkedEditingRangeParams,
    ) -> Result<Option<LinkedEditingRanges>> {
        guard_async_result("linked_editing_range", async move {
            self.handle_linked_editing_range(params).await
        })
        .await
    }

    async fn goto_implementation(
        &self,
        params: tower_lsp_server::ls_types::request::GotoImplementationParams,
    ) -> Result<Option<tower_lsp_server::ls_types::request::GotoImplementationResponse>> {
        guard_async_result("goto_implementation", async move {
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let source = self.get_open_text(uri).unwrap_or_default();
            let imports = self.file_imports(uri);
            let raw_word = crate::text::word_at_position(&source, position).unwrap_or_default();
            if raw_word.is_empty() || is_unresolvable_bareword_at(&source, position, &raw_word) {
                return Ok(None);
            }
            // `word_at_position` includes `\` as a word character, so the cursor on
            // a use-statement import (`use A\B\Foo`) returns the full qualified name.
            let (word, fqn): (String, String) = if is_bare_php_name(&raw_word) {
                // Resolve via this file's imports + namespace; covers usages,
                // aliases, and the type's own declaration (which resolves to
                // `<current-namespace>\<word>`).
                let resolved = match self.get_doc(uri) {
                    Some(doc) => crate::navigation::moniker::resolve_fqn(&doc, &raw_word, &imports),
                    None => raw_word.clone(),
                };
                (raw_word, normalized_php_fqn(&resolved).to_string())
            } else {
                let short = crate::text::fqn_short_name(&raw_word).to_string();
                (short, normalized_php_fqn(&raw_word).to_string())
            };

            // A method name can collide case-insensitively with a class name
            // (`Guard` interface vs `guard()` method in one namespace); mir's
            // symbol at the cursor decides which sense wins.
            let method_offset = self.get_doc(uri).and_then(|doc| {
                crate::text::word_range_at(&source, position)
                    .map(|r| doc.view().byte_of_position(r.start))
            });
            let docs_for_method_check = Arc::clone(&self.docs);
            let uri_for_method_check = uri.clone();
            let on_method_decl = self
                .blocking_gated(super::debug_gate::GATE_GOTO_IMPLEMENTATION, move || {
                    method_offset.is_some_and(|offset| {
                        matches!(
                            docs_for_method_check.mir_name_at(&uri_for_method_check, offset),
                            Ok(Some(mir_analyzer::Name::Method { .. }))
                        )
                    })
                })
                .await
                .unwrap_or(false);

            // Subtypes of the type under the cursor, from mir's maintained
            // subtype edge index (aliased/FQN extends forms all resolve).
            let mut locs: Vec<Location> = if on_method_decl {
                Vec::new()
            } else {
                let docs = Arc::clone(&self.docs);
                let fqn_task = fqn.clone();
                self.blocking("goto_implementation.subtypes", move || {
                    docs.indexed_subtype_classes(&fqn_task, false)
                })
                .await
                .unwrap_or_else(|| Ok(Vec::new()))?
                .into_iter()
                .filter_map(|site| subtype_site_to_location(&site.file, &site.range))
                .collect()
            };
            if locs.is_empty() && !on_method_decl {
                let wi = self.workspace_index_async().await;
                let docs = Arc::clone(&self.docs);
                let target_fqn = fqn.clone();
                let target_short = word.clone();
                locs = self
                    .blocking("goto_implementation.index_fallback", move || {
                        let mention_candidates =
                            |name: &str| docs.declaration_candidate_files(&wi, name);
                        let get_doc = |uri: &Uri| docs.get_doc_salsa(uri);
                        implementation_locations_from_index(
                            &wi,
                            &target_fqn,
                            &target_short,
                            &mention_candidates,
                            &get_doc,
                        )
                    })
                    .await
                    .unwrap_or_default();
            }

            // Cursor on a method name inside its declaring class/interface:
            // concrete overrides in every subtype.
            if locs.is_empty()
                && let Some(doc) = self.get_doc(uri)
                && let Some(enclosing) =
                    crate::types::type_map::enclosing_class_at(&source, &doc, position)
            {
                let resolved_enclosing =
                    crate::navigation::moniker::resolve_fqn(&doc, &enclosing, &imports);
                let enclosing_fqn = normalized_php_fqn(&resolved_enclosing).to_string();
                let docs = Arc::clone(&self.docs);
                let method = word.clone();
                let impls = self
                    .blocking("goto_implementation.method_impls", move || {
                        docs.indexed_method_implementations(&enclosing_fqn, &method)
                    })
                    .await
                    .unwrap_or_else(|| Ok(Vec::new()))?;
                locs = impls
                    .into_iter()
                    .filter_map(|(_, file, range)| subtype_site_to_location(&file, &range))
                    .collect();
            }
            if locs.is_empty() {
                Ok(None)
            } else {
                Ok(Some(GotoDefinitionResponse::Array(locs)))
            }
        })
        .await
    }

    async fn goto_declaration(
        &self,
        params: tower_lsp_server::ls_types::request::GotoDeclarationParams,
    ) -> Result<Option<tower_lsp_server::ls_types::request::GotoDeclarationResponse>> {
        guard_async_result("goto_declaration", async move {
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let source = self.get_open_text(uri).unwrap_or_default();
            if let Some(doc) = self.get_doc(uri)
                && let Some(offset) = crate::text::word_range_at(&source, position)
                    .map(|range| doc.view().byte_of_position(range.start))
            {
                let docs = Arc::clone(&self.docs);
                let uri_task = uri.clone();
                let implemented = self
                    .blocking("goto_declaration.implemented", move || {
                        crate::navigation::mir_definition::mir_implemented_declaration(
                            &docs, &uri_task, offset,
                        )
                    })
                    .await;
                if let Some(Ok(Some(loc))) = implemented {
                    return Ok(Some(GotoDefinitionResponse::Scalar(loc)));
                }
            }
            // First pass: open-file ParsedDocs give accurate character
            // positions. Walking every open doc's AST is CPU-bound; keep it
            // off the async runtime worker. A separate hop (rather than one
            // spawn_blocking around both passes) so a first-pass hit skips
            // the second pass's workspace-index fetch entirely, as before.
            let open_docs = self.docs.docs_for(&self.open_urls());
            let source_for_pass1 = source.clone();
            let first_pass = self
                .blocking("goto_declaration.open_docs", move || {
                    goto_declaration(&source_for_pass1, &open_docs, position)
                })
                .await
                .unwrap_or_default();
            if let Some(loc) = first_pass {
                return Ok(Some(GotoDefinitionResponse::Scalar(loc)));
            }
            // Second pass: background files via the aggregated workspace index
            // (line-only positions for anything not covered by a mention hit).
            let wi = self.workspace_index_async().await;
            let docs = Arc::clone(&self.docs);
            let second_pass = self
                .blocking("goto_declaration.index", move || {
                    let mention_candidates =
                        |name: &str| docs.declaration_candidate_files(&wi, name);
                    let get_doc = |uri: &Uri| docs.get_doc_salsa(uri);
                    goto_declaration_from_index(
                        &source,
                        &wi,
                        position,
                        &get_doc,
                        &mention_candidates,
                    )
                })
                .await
                .unwrap_or_default();
            Ok(second_pass.map(GotoDefinitionResponse::Scalar))
        })
        .await
    }

    async fn goto_type_definition(
        &self,
        params: tower_lsp_server::ls_types::request::GotoTypeDefinitionParams,
    ) -> Result<Option<tower_lsp_server::ls_types::request::GotoTypeDefinitionResponse>> {
        guard_async_result("goto_type_definition", async move {
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let source = self.get_open_text(uri).unwrap_or_default();
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            let analysis = self.cached_analysis_async(uri).await;
            let docs = Arc::clone(&self.docs);

            let results = self
                .blocking_gated(super::debug_gate::GATE_GOTO_TYPE_DEFINITION, move || {
                    let fqns = type_class_fqns(&source, &doc, analysis.as_deref(), position);
                    crate::navigation::mir_definition::mir_class_locations(&docs, &fqns)
                })
                .await
                .unwrap_or_else(|| Ok(Vec::new()))?;
            Ok(match results.len() {
                0 => None,
                1 => Some(GotoDefinitionResponse::Scalar(
                    results.into_iter().next().unwrap(),
                )),
                _ => Some(GotoDefinitionResponse::Array(results)),
            })
        })
        .await
    }

    async fn prepare_type_hierarchy(
        &self,
        params: TypeHierarchyPrepareParams,
    ) -> Result<Option<Vec<TypeHierarchyItem>>> {
        guard_async_result("prepare_type_hierarchy", async move {
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let wi = self.workspace_index_async().await;
            let class_ref = self
                .get_doc(uri)
                .and_then(|doc| {
                    word_at_position(doc.source(), position).map(|word| {
                        let imports = doc.file_imports();
                        crate::navigation::moniker::resolve_fqn(&doc, &word, &imports)
                    })
                })
                .and_then(|fqn| self.docs.class_ref_by_fqn(&wi, &fqn));
            let item = self
                .blocking_gated(super::debug_gate::GATE_TYPE_HIERARCHY, move || {
                    prepare_type_hierarchy_from_fqn(class_ref?, &wi)
                })
                .await
                .flatten();
            Ok(item.map(|item| vec![item]))
        })
        .await
    }

    async fn supertypes(
        &self,
        params: TypeHierarchySupertypesParams,
    ) -> Result<Option<Vec<TypeHierarchyItem>>> {
        guard_async_result("supertypes", async move {
            // Phase J: resolve parents via the aggregate, mention-index-narrowed.
            // Pre-load any direct vendor supertypes via PSR-4 so they appear in the
            // workspace index before the lookup runs.
            let wi = self.workspace_index_async().await;
            let Some(item_fqn) = crate::navigation::type_hierarchy::item_fqn(&params.item) else {
                return Ok(None);
            };
            let loaded_new = self.ensure_direct_supertypes_loaded(item_fqn, &wi).await;
            let wi = if loaded_new {
                self.workspace_index_async().await
            } else {
                wi
            };
            let docs = Arc::clone(&self.docs);
            let item_fqn = item_fqn.to_owned();
            let result = self
                .blocking_gated(super::debug_gate::GATE_TYPE_HIERARCHY, move || {
                    let supertype_fqns = docs.class_direct_supertypes(&item_fqn)?;
                    let resolve_class_ref = |fqn: &str| docs.resolve_class_ref_by_fqn(&wi, fqn);
                    Ok::<_, crate::document::document_store::ContentModified>(
                        supertypes_of_from_workspace(&supertype_fqns, &wi, &resolve_class_ref),
                    )
                })
                .await
                .unwrap_or_else(|| Ok(Vec::new()))?;
            Ok(if result.is_empty() {
                None
            } else {
                Some(result)
            })
        })
        .await
    }

    async fn subtypes(
        &self,
        params: TypeHierarchySubtypesParams,
    ) -> Result<Option<Vec<TypeHierarchyItem>>> {
        guard_async_result("subtypes", async move {
            let docs = Arc::clone(&self.docs);
            let item = params.item;
            let Some(item_fqn) = crate::navigation::type_hierarchy::item_fqn(&item) else {
                return Ok(None);
            };
            let item_fqn = item_fqn.to_owned();
            let result = self
                .blocking_gated(super::debug_gate::GATE_TYPE_HIERARCHY, move || {
                    let sites = docs.indexed_direct_subtype_classes(&item_fqn, true)?;
                    Ok::<_, crate::document::document_store::ContentModified>(subtypes_from_sites(
                        &sites,
                    ))
                })
                .await
                .unwrap_or_else(|| Ok(Vec::new()))?;
            Ok(if result.is_empty() {
                None
            } else {
                Some(result)
            })
        })
        .await
    }

    async fn code_lens(&self, params: CodeLensParams) -> Result<Option<Vec<CodeLens>>> {
        guard_async_result("code_lens", async move {
            let uri = &params.text_document.uri;
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            // Lens counts come from mir's inverted indexes; still run on the
            // blocking pool (index freshness passes may analyze on demand).
            // A write during computation (write_rev advances) cancels early —
            // stale lens counts are useless and the editor will request fresh
            // ones after the edit.
            let docs = Arc::clone(&self.docs);
            let docs_cancel = Arc::clone(&self.docs);
            let uri_owned = uri.clone();
            let imports = self.file_imports(uri);
            let lenses = self
                .blocking("code_lens", move || {
                    // Pause the background scan and snapshot a settled revision so
                    // only a genuine user edit cancels the sweep.
                    let (_interactive, cancel_rev) = docs.settled_write_rev_guard();
                    code_lenses(
                        &uri_owned,
                        &doc,
                        &docs,
                        &imports,
                        Some(cancel_rev),
                        move || docs_cancel.write_rev() != cancel_rev,
                    )
                })
                .await
                .unwrap_or_default();
            Ok(if lenses.is_empty() {
                None
            } else {
                Some(lenses)
            })
        })
        .await
    }

    async fn code_lens_resolve(&self, params: CodeLens) -> Result<CodeLens> {
        let fallback = params.clone();
        let resolved = guard_async("code_lens_resolve", async move {
            // Lenses are fully populated by code_lens; nothing to add.
            Some(params)
        })
        .await;
        Ok(resolved.unwrap_or(fallback))
    }

    async fn document_link(&self, params: DocumentLinkParams) -> Result<Option<Vec<DocumentLink>>> {
        guard_async_result("document_link", async move {
            let uri = params.text_document.uri;
            let doc = match self.get_doc(&uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            let laravel = self.laravel.load_full();
            // The AST walk plus full-text `@link`/`@see` scan are CPU-bound;
            // keep them off the async runtime worker.
            let links = self
                .blocking_gated(super::debug_gate::GATE_DOCUMENT_LINK, move || {
                    let mut links = document_links(&uri, &doc, doc.source());
                    links.extend(crate::laravel::document_links(&doc, &laravel));
                    links.extend(crate::laravel::blade::document_links(
                        &uri,
                        doc.source(),
                        &laravel,
                    ));
                    links
                })
                .await
                .unwrap_or_default();
            Ok(if links.is_empty() { None } else { Some(links) })
        })
        .await
    }

    async fn document_link_resolve(&self, params: DocumentLink) -> Result<DocumentLink> {
        let fallback = params.clone();
        let resolved = guard_async("document_link_resolve", async move {
            // Links already carry their target URI; nothing to add.
            Some(params)
        })
        .await;
        Ok(resolved.unwrap_or(fallback))
    }

    async fn formatting(&self, params: DocumentFormattingParams) -> Result<Option<Vec<TextEdit>>> {
        guard_async_result("formatting", async move {
            let uri = &params.text_document.uri;
            let source = self.get_open_text(uri).unwrap_or_default();
            // Spawns and blocks on an external formatter process; keep that
            // wait off the async runtime worker.
            Ok(self
                .blocking("formatting", move || format_document(&source))
                .await
                .unwrap_or_default())
        })
        .await
    }

    async fn range_formatting(
        &self,
        params: DocumentRangeFormattingParams,
    ) -> Result<Option<Vec<TextEdit>>> {
        guard_async_result("range_formatting", async move {
            let uri = &params.text_document.uri;
            let source = self.get_open_text(uri).unwrap_or_default();
            let range = params.range;
            Ok(self
                .blocking("range_formatting", move || format_range(&source, range))
                .await
                .unwrap_or_default())
        })
        .await
    }

    async fn on_type_formatting(
        &self,
        params: DocumentOnTypeFormattingParams,
    ) -> Result<Option<Vec<TextEdit>>> {
        guard_async_result("on_type_formatting", async move {
            let uri = &params.text_document_position.text_document.uri;
            let source = self.get_open_text(uri).unwrap_or_default();
            let position = params.text_document_position.position;
            // `}` fires a whole-document char-vec + string-literal-mask scan
            // to find the matching brace; every keystroke fires this handler,
            // so keep it off the async runtime worker like the other
            // whole-document walks.
            let edits = self
                .blocking_gated(super::debug_gate::GATE_ON_TYPE_FORMATTING, move || {
                    on_type_format(&source, position, &params.ch, &params.options)
                })
                .await
                .unwrap_or_default();
            Ok(if edits.is_empty() { None } else { Some(edits) })
        })
        .await
    }

    async fn execute_command(
        &self,
        params: ExecuteCommandParams,
    ) -> Result<Option<serde_json::Value>> {
        guard_async_result("execute_command", async move {
            match params.command.as_str() {
                "php-lsp.runTest" => {
                    // Arguments: [uri_string, "ClassName::methodName"]
                    let file_uri = params
                        .arguments
                        .first()
                        .and_then(|v| v.as_str())
                        .and_then(|s| (s).parse::<Uri>().ok());
                    let filter = params
                        .arguments
                        .get(1)
                        .and_then(|v| v.as_str())
                        .unwrap_or("")
                        .to_string();

                    let root = self.root_paths.load().first().cloned();
                    let client = self.client.clone();

                    tokio::spawn(async move {
                        run_phpunit(&client, &filter, root.as_deref(), file_uri.as_ref()).await;
                    });

                    Ok(None)
                }
                _ => Ok(None),
            }
        })
        .await
    }

    async fn will_rename_files(&self, params: RenameFilesParams) -> Result<Option<WorkspaceEdit>> {
        guard_async_result("will_rename_files", async move {
            self.handle_will_rename_files(params).await
        })
        .await
    }

    async fn did_rename_files(&self, params: RenameFilesParams) {
        guard_async("did_rename_files", async move {
            self.handle_did_rename_files(params).await
        })
        .await
    }

    async fn will_create_files(&self, params: CreateFilesParams) -> Result<Option<WorkspaceEdit>> {
        guard_async_result("will_create_files", async move {
            self.handle_will_create_files(params).await
        })
        .await
    }

    async fn did_create_files(&self, params: CreateFilesParams) {
        guard_async("did_create_files", async move {
            self.handle_did_create_files(params).await
        })
        .await
    }

    /// Before a file is deleted, return workspace edits that remove every
    /// `use` import referencing its PSR-4 class name.
    async fn will_delete_files(&self, params: DeleteFilesParams) -> Result<Option<WorkspaceEdit>> {
        guard_async_result("will_delete_files", async move {
            self.handle_will_delete_files(params).await
        })
        .await
    }

    async fn did_delete_files(&self, params: DeleteFilesParams) {
        guard_async("did_delete_files", async move {
            self.handle_did_delete_files(params).await
        })
        .await
    }

    async fn moniker(&self, params: MonikerParams) -> Result<Option<Vec<Moniker>>> {
        guard_async_result("moniker", async move {
            let uri = &params.text_document_position_params.text_document.uri;
            let position = params.text_document_position_params.position;
            let source = self.get_open_text(uri).unwrap_or_default();
            let doc = match self.get_doc(uri) {
                Some(d) => d,
                None => return Ok(None),
            };
            let imports = self.file_imports(uri);
            let moniker = self
                .blocking_gated(super::debug_gate::GATE_MONIKER, move || {
                    moniker_at(&source, &doc, position, &imports)
                })
                .await
                .flatten();
            Ok(moniker.map(|m| vec![m]))
        })
        .await
    }

    async fn inline_value(&self, params: InlineValueParams) -> Result<Option<Vec<InlineValue>>> {
        guard_async_result("inline_value", async move {
            let uri = &params.text_document.uri;
            let source = self.get_open_text(uri).unwrap_or_default();
            let range = params.range;
            let values = self
                .blocking_gated(super::debug_gate::GATE_INLINE_VALUE, move || {
                    inline_values_in_range(&source, range)
                })
                .await
                .unwrap_or_default();
            Ok(if values.is_empty() {
                None
            } else {
                Some(values)
            })
        })
        .await
    }

    async fn diagnostic(
        &self,
        params: DocumentDiagnosticParams,
    ) -> Result<DocumentDiagnosticReportResult> {
        let report = guard_async("diagnostic", async move {
            Some(self.handle_diagnostic(params).await)
        })
        .await;
        match report {
            Some(r) => r,
            None => Ok(DocumentDiagnosticReportResult::Report(
                DocumentDiagnosticReport::Full(RelatedFullDocumentDiagnosticReport::default()),
            )),
        }
    }

    async fn workspace_diagnostic(
        &self,
        params: WorkspaceDiagnosticParams,
    ) -> Result<WorkspaceDiagnosticReportResult> {
        let report = guard_async("workspace_diagnostic", async move {
            Some(self.handle_workspace_diagnostic(params).await)
        })
        .await;
        match report {
            Some(r) => r,
            None => Ok(WorkspaceDiagnosticReportResult::Report(
                WorkspaceDiagnosticReport::default(),
            )),
        }
    }

    async fn code_action(&self, params: CodeActionParams) -> Result<Option<CodeActionResponse>> {
        guard_async_result("code_action", async move {
            self.handle_code_action(params).await
        })
        .await
    }

    async fn code_action_resolve(&self, item: CodeAction) -> Result<CodeAction> {
        guard_async_result("code_action_resolve", async move {
            self.handle_code_action_resolve(item).await
        })
        .await
    }
}

/// Fallback for `goto_implementation` when mir has no resolved subtype sites.
///
/// The primary path above is the authoritative one: mir's graph has already
/// resolved aliases, leading slashes, and namespace context. This fallback keeps
/// interactive behavior useful while the graph is cold or while a workspace has
/// incomplete/invalid PHP by narrowing to files that mention the target short
/// name, then verifying each candidate's declaration-level `extends`/
/// `implements` clauses against its own namespace/import context. Exact FQN
/// matches are preferred; the short-name pass preserves the legacy behavior for
/// unresolved symbols without scanning the whole workspace.
fn implementation_locations_from_index(
    wi: &crate::db::workspace_index::WorkspaceIndexData,
    target_fqn: &str,
    target_short: &str,
    mention_candidates: &dyn Fn(&str) -> Vec<Uri>,
    get_doc: &dyn Fn(&Uri) -> Option<Arc<ParsedDoc>>,
) -> Vec<Location> {
    let mut exact = Vec::new();
    let mut short_name = Vec::new();
    let candidate_uris = mention_candidates(target_short);
    wi.for_each_class_in_uris(&candidate_uris, |uri, cls| {
        let Some(doc) = get_doc(uri) else {
            return;
        };
        let imports = doc.file_imports();
        let mut saw_short_name_match = false;
        let mut relation_matches = |name: &str| {
            let resolved = crate::navigation::moniker::resolve_fqn(&doc, name, &imports);
            if normalized_php_fqn(&resolved).eq_ignore_ascii_case(target_fqn) {
                return true;
            }
            if crate::text::fqn_short_name(name).eq_ignore_ascii_case(target_short) {
                saw_short_name_match = true;
            }
            false
        };
        let exact_match = cls.parent.as_deref().is_some_and(&mut relation_matches)
            || cls
                .implements
                .iter()
                .any(|iface| relation_matches(iface.as_ref()));

        let loc = class_index_location(uri, cls);
        if exact_match {
            exact.push(loc);
        } else if saw_short_name_match {
            short_name.push(loc);
        }
    });

    let mut result = if exact.is_empty() { short_name } else { exact };
    result.sort_by(|a, b| {
        a.uri
            .as_str()
            .cmp(b.uri.as_str())
            .then(a.range.start.line.cmp(&b.range.start.line))
            .then(a.range.start.character.cmp(&b.range.start.character))
    });
    result.dedup_by(|a, b| a.uri == b.uri && a.range == b.range);
    result
}

fn class_index_location(uri: &Uri, cls: &crate::index::file_index::ClassDef) -> Location {
    let start = Position {
        line: cls.start_line,
        character: cls.name_char,
    };
    Location {
        uri: uri.clone(),
        range: Range {
            start,
            end: Position {
                line: cls.start_line,
                character: cls.name_char + cls.name.len() as u32,
            },
        },
    }
}

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

    /// Resolving a bare builtin interface loads its stub (a salsa input
    /// write) — the hover's own db handle must be gone by then. Mirrored via
    /// `upsert_source_file`, like the workspace scan, so no stub is preloaded.
    #[test]
    fn class_hover_loads_builtin_interface_stub_without_deadlock() {
        let (tx, rx) = std::sync::mpsc::channel();
        std::thread::spawn(move || {
            let mut session = mir_analyzer::AnalysisSession::new(mir_analyzer::PhpVersion::LATEST);
            session.upsert_source_file(
                Arc::from("file:///foo.php"),
                Arc::from("<?php\nclass Foo implements Countable {\n    public function count(): int { return 0; }\n}\n"),
                salsa::Durability::LOW,
            );
            let hover = class_hover_for_fqcn(&session.snapshot(), "Foo");
            let _ = tx.send(hover.map(|h| match h.contents {
                HoverContents::Markup(m) => m.value,
                _ => String::new(),
            }));
        });
        let value = rx
            .recv_timeout(std::time::Duration::from_secs(30))
            .expect("class hover deadlocked")
            .expect("class hover for Foo");
        assert!(value.contains("implements \\Countable"), "{value}");
    }
}