adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/server/handlers.py

@@ -0,0 +1,2849 @@
+"""MCP request handlers.
+
+Implements the business logic for each MCP tool/endpoint.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import math
+import re
+import time
+import functools
+from collections import Counter, deque
+from typing import List, Dict, Any, NamedTuple, Optional, Tuple
+from pathlib import Path
+
+from adl_drift.server.protocol import (
+    MCPRequest, MCPResponse, MCPContextItem,
+    MCPInitializeResponse, MCPToolDefinition
+)
+from adl_drift.detectors.base import DetectorRegistry
+from adl_drift.lang.registry import backend_for_file, get_backend
+from adl_drift.graph.builder import CallGraphBuilder, GRAPH_SCHEMA_VERSION
+from adl_drift.graph.node import GraphNode
+from adl_drift.graph.edges import EdgeType
+from adl_drift.graph.cluster import detect_communities
+from adl_drift.cortex.memory import CortexMemory, GRAPH_CACHE_RACY_WINDOW_SECONDS
+from adl_drift.cortex.patterns import PatternManager
+from adl_drift.cortex.telemetry import TelemetryRecorder
+from adl_drift.utils.types import SCAN_FILE_ERRORS, Pattern, PatternCategory
+from adl_drift.scanner.incremental import IncrementalScanner, java_incremental_scope
+from adl_drift.scanner.parallel import parallel_analyze, should_parallelize
+from adl_drift.scanner.discovery import (
+    CachedDiscovery, discover_file_groups, discover_files, select_backend,
+)
+
+
+class _GraphCacheEntry(NamedTuple):
+    """In-memory graph of the last ``_build_full_graph`` call.
+
+    ``fingerprint`` is ``CortexMemory._source_state()``'s stat-based digest
+    (relative path, size, mtime_ns of every discovered source) — the same
+    value ``load_graph`` compares to decide whether the persisted graph is
+    still valid. ``taken_at`` is the wall-clock time just before that stat
+    walk started.
+    """
+
+    fingerprint: str
+    taken_at: float
+    builder: CallGraphBuilder
+
+
+class MCPHandlers:
+    """Handles all MCP tool invocations.
+
+    Read tools:
+    - drift_scan: Scan a file or project (updates the persisted graph)
+    - drift_query: Query patterns by category
+    - drift_search: Symbol search (ranked: exact id > exact name > substring)
+    - drift_node: Node detail + source snippet + edge counts
+    - drift_graph: Get call graph for a symbol
+    - drift_callers / drift_callees: Depth-bounded dependency walks
+    - drift_impact: Blast-radius analysis
+    - drift_path: Shortest path between two symbols
+    - drift_status: Index freshness + graph health
+    - drift_communities: Louvain module clusters
+    - drift_why: Ask "why" about a pattern (tribal knowledge)
+    - drift_context: Graph-ranked context for an AI query
+
+    Write tools (append/flag-only DB writes — no filesystem):
+    - drift_learn: Record tribal knowledge
+    - drift_approve: Approve a detected pattern
+
+    List-returning tools accept ``limit`` and ``max_tokens`` (≈4 chars/token
+    on the JSON payload); trimmed responses carry a ``truncated`` count.
+    """
+
+    # P2.11 Part 3: write-tool input caps (content is stored verbatim in
+    # SQLite; these only bound abuse, not expression).
+    MAX_TOPIC_LEN = 200
+    MAX_CONTENT_LEN = 10_000
+    MAX_TAGS = 20
+
+    def __init__(self, project_path: Path, db_path: Optional[Path] = None):
+        self.project_path = project_path
+        self.project_root = CallGraphBuilder.find_project_root(project_path) or project_path
+        self.memory = (
+            CortexMemory(db_path)
+            if db_path is not None
+            else CortexMemory.for_project(self.project_root)
+        )
+        self.pattern_manager = PatternManager(self.memory)
+        # P2.5: per-file errors from the most recent _build_full_graph().
+        self.last_graph_errors: List[Dict[str, str]] = []
+        # MCP_GRAPH_CACHE_PLAN.md Lớp 1: graph returned by the previous
+        # _build_full_graph() call, reused while the source fingerprint is
+        # unchanged. Dropped whenever this process persists a graph through
+        # another path (_scan_directory) so that graph is not shadowed.
+        self._graph_cache: Optional[_GraphCacheEntry] = None
+        # MCP_INCREMENTAL_REBUILD_PLAN.md Lớp 1: how the last _build_full_graph()
+        # produced its graph — same shape as DriftCommands.last_graph_update
+        # ({"mode", "invalidated_files", "reason"}); mode is one of "cached",
+        # "dependency_scoped" (Java body-only edit) or "full_rebuild".
+        self.last_graph_update: Dict[str, Any] = {}
+        self._discovery_caches: Dict[Path, CachedDiscovery] = {}
+
+        self.backend = None
+        self._configure_backend(project_path)
+
+        # Initialize detector registry
+        # P1.11: route detectors reused by _build_full_graph (which skips full
+        # detection) so route handlers are still marked as entry points.
+        self._route_detectors = self.registry.get_for_category(PatternCategory.ROUTES)
+
+        # MONITOR: wrap every tool handler so each call records telemetry
+        # (tokens returned vs. read+grep baseline, confidence profile) into
+        # cortex.db for the project monitor UI. Best-effort, never fatal.
+        # Accounting lives in the shared TelemetryRecorder so the CLI path
+        # (cli/commands.py) reports the identical metric (PM.1 / PM.2).
+        self._telemetry = TelemetryRecorder(self.memory, self.project_root)
+        self._install_telemetry()
+
+    def _configure_backend(self, path: Path, backend_name: Optional[str] = None) -> None:
+        backend = get_backend(backend_name) if backend_name else select_backend(path)
+        if self.backend is not None and self.backend.name == backend.name:
+            return
+        self.backend = backend
+        self.config = backend.project_config(path)
+        self.parser = backend.parser()
+        self.extractor = backend.extractor()
+        self.registry = DetectorRegistry(backend.detectors())
+        self._route_detectors = self.registry.get_for_category(PatternCategory.ROUTES)
+
+    def _resolver_config(self):
+        return self.backend.resolver_config()
+
+    @staticmethod
+    def _backend_name(file_path: Path) -> str:
+        backend = backend_for_file(file_path)
+        return backend.name if backend else "python"
+
+    @classmethod
+    def _group_paths(cls, paths: List[Path]) -> Dict[str, List[Path]]:
+        groups: Dict[str, List[Path]] = {}
+        for path in paths:
+            groups.setdefault(cls._backend_name(path), []).append(path)
+        return groups
+
+    def _file_groups(self, path: Path) -> Dict[str, List[Path]]:
+        # A no-change query otherwise re-walks the tree three times and
+        # re-parses every build file before the Lớp 1 fingerprint can hit.
+        cache = self._discovery_caches.get(path)
+        if cache is None:
+            cache = self._discovery_caches[path] = CachedDiscovery(
+                path, racy_window=GRAPH_CACHE_RACY_WINDOW_SECONDS,
+            )
+        return cache.groups()
+
+    def _parse_file(self, file_path: Path):
+        self._configure_backend(file_path, self._backend_name(file_path))
+        return self.parser.parse_file(file_path)
+
+    def _resolve_graph(
+        self,
+        builder: CallGraphBuilder,
+        parses: Dict[Path, Any],
+        results: Dict[Path, Any],
+    ) -> None:
+        if not parses:
+            return
+        builder.resolve_relationships(results)
+        for backend_name in sorted({self._backend_name(path) for path in parses}):
+            self._configure_backend(self.project_path, backend_name)
+            builder.resolver_config = self._resolver_config()
+            builder._resolver = None
+            group = {
+                path: parse for path, parse in parses.items()
+                if self._backend_name(path) == backend_name
+            }
+            builder.resolve_decorator_types(group, results)
+            builder.resolve_calls(group, results)
+            builder.harvest_literal_candidates(group, results)
+
+    # ---- MONITOR telemetry --------------------------------------------------
+
+    _TELEMETRY_MAP = {
+        "drift_scan": "handle_scan",
+        "drift_query": "handle_query",
+        "drift_search": "handle_search",
+        "drift_node": "handle_node",
+        "drift_graph": "handle_graph",
+        "drift_callers": "handle_callers",
+        "drift_callees": "handle_callees",
+        "drift_impact": "handle_impact",
+        "drift_explore": "handle_explore",
+        "drift_path": "handle_path",
+        "drift_status": "handle_status",
+        "drift_communities": "handle_communities",
+        "drift_why": "handle_why",
+        "drift_context": "handle_context",
+        "drift_plan_change": "handle_plan_change",
+        "drift_verify_change": "handle_verify_change",
+    }
+
+    def _install_telemetry(self) -> None:
+        for tool, method_name in self._TELEMETRY_MAP.items():
+            original = getattr(self, method_name)
+
+            def make_wrapper(tool: str, original):
+                @functools.wraps(original)
+                def wrapper(params=None):
+                    params = params or {}
+                    t0 = time.perf_counter()
+                    response = original(params)
+                    try:
+                        self._record_invocation(
+                            tool, params, response,
+                            (time.perf_counter() - t0) * 1000.0,
+                        )
+                    except Exception:
+                        pass
+                    return response
+                return wrapper
+
+            setattr(self, method_name, make_wrapper(tool, original))
+
+    def _record_invocation(self, tool: str, params: Dict[str, Any],
+                           response: Any, duration_ms: float) -> None:
+        """Estimate token savings + confidence profile for one MCP tool call."""
+        payload = response.model_dump() if hasattr(response, "model_dump") else {}
+        is_error = payload.get("error") is not None
+        result = payload.get("result")
+        body = result if result is not None else payload.get("error")
+        self._telemetry.record(
+            tool, params, body,
+            is_error=is_error, duration_ms=duration_ms, source="mcp",
+        )
+
+    def _route_patterns(self, parse_result: Any, file_path: Path) -> List[Pattern]:
+        """P1.11: ROUTES-only detection for the graph-build path."""
+        patterns: List[Pattern] = []
+        for det in self._route_detectors:
+            try:
+                patterns.extend(det.detect(parse_result.tree, parse_result.source_bytes, file_path))
+            except Exception:
+                continue
+        return patterns
+
+    def initialize(self) -> MCPInitializeResponse:
+        """Return server capabilities."""
+        return MCPInitializeResponse(
+            server_info={
+                "name": "adl-drift",
+                "version": "0.1.0",
+            },
+            tools=[
+                MCPToolDefinition(
+                    name="drift_scan",
+                    description="Scan Python and Java files for patterns",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "path": {"type": "string", "description": "File or directory to scan"},
+                            "category": {"type": "string", "description": "Pattern category filter"},
+                            "limit": {"type": "integer", "description": "Max results (default: all)"},
+                            "max_tokens": {"type": "integer", "description": "Token budget for results"},
+                            "cursor": {"type": "string", "description": "Continuation token from a previous next_cursor"},
+                        },
+                        "required": ["path"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_query",
+                    description="Query detected patterns from memory",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "category": {"type": "string"},
+                            "approved_only": {"type": "boolean"},
+                            "limit": {"type": "integer", "description": "Max patterns (default 50)"},
+                            "max_tokens": {"type": "integer", "description": "Token budget for patterns"},
+                            "cursor": {"type": "string", "description": "Continuation token from a previous next_cursor"},
+                        },
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_graph",
+                    description="Get call graph for a symbol",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "symbol": {"type": "string", "description": "Fully qualified symbol name"},
+                            "symbols": {"type": "array", "items": {"type": "string"}, "description": "Batch alternative to symbol: fetch call graphs for several symbols in one call"},
+                            "limit": {"type": "integer", "description": "Max items per list"},
+                            "max_tokens": {"type": "integer", "description": "Token budget per list (default 2000; 0 = unbounded)"},
+                        },
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_why",
+                    description="Get tribal knowledge about a topic",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "topic": {"type": "string"},
+                        },
+                        "required": ["topic"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_impact",
+                    description="Blast-radius analysis: direct + transitive callers of a symbol. "
+                                "If the name doesn't match exactly, a token-overlap guess is used "
+                                "instead (fuzzy_fallback=true) -- no need to drift_search first.",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "symbol": {"type": "string", "description": "Symbol name (simple or qualified); a loose/behavior-phrased name falls back to a fuzzy guess"},
+                            "max_tokens": {"type": "integer", "description": "Token budget (default 6000; 0 = unbounded, capped at 11000). Counts stay exact, lists are cut, `truncated` says what was dropped"},
+                            "limit": {"type": "integer", "description": "Max items per list"},
+                            "max_depth": {"type": "integer", "description": "Transitive caller depth horizon (default: unbounded)"},
+                            "max_nodes": {"type": "integer", "description": "Cap on node ids across all lists"},
+                            "include_initializers": {"type": "boolean", "description": "Count synthetic Java <init>/<clinit> contexts as callers (default false; they are otherwise returned separately)"},
+                            "cursor": {"type": "string", "description": "Continuation token from a previous next_cursor"},
+                        },
+                        "required": ["symbol"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_explore",
+                    description="Everything about one symbol in a single call: resolved detail "
+                                "(signature/docstring/snippet), blast radius (direct + transitive "
+                                "callers), and dependencies (what it calls) -- instead of "
+                                "drift_node + drift_impact + drift_graph as 3 round trips. Falls "
+                                "back to a fuzzy guess like drift_impact. Use drift_impact/"
+                                "drift_graph/drift_callers directly instead for a single aspect, "
+                                "or to page a huge list with `cursor` (not supported here).",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "symbol": {"type": "string", "description": "Symbol name (simple or qualified); a loose/behavior-phrased name falls back to a fuzzy guess"},
+                            "max_tokens": {"type": "integer", "description": "Total token budget, split across detail/impact/dependencies (default 6000; 0 = unbounded, capped at 11000)"},
+                            "limit": {"type": "integer", "description": "Max items per list (impact's caller lists and dependencies)"},
+                            "max_depth": {"type": "integer", "description": "Transitive caller depth horizon for impact (default: unbounded)"},
+                            "max_nodes": {"type": "integer", "description": "Cap on node ids across impact's lists"},
+                            "callees_depth": {"type": "integer", "description": "Depth of the dependencies (callees) walk (default 1)"},
+                            "include_initializers": {"type": "boolean", "description": "Count synthetic Java <init>/<clinit> contexts as callers (default false)"},
+                            "snippet_lines": {"type": "integer", "description": "Source lines for detail.snippet; omit to size to the symbol's real body length (capped at 200)"},
+                            "max_source_lines": {"type": "integer", "description": "Hard cap on detail.snippet length"},
+                        },
+                        "required": ["symbol"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_context",
+                    description="Get graph-ranked project context for AI assistance",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "query": {"type": "string", "description": "What the AI is trying to do"},
+                            "file_path": {"type": "string"},
+                            "max_tokens": {"type": "integer", "description": "Token budget (default 2000; 0 = unbounded)"},
+                        },
+                        "required": ["query"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_search",
+                    description="Search symbols by name (ranked: exact id > exact name > substring; degree-boosted)",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "query": {"type": "string", "description": "Symbol name or substring"},
+                            "queries": {"type": "array", "items": {"type": "string"}, "description": "Batch alternative to query: run several searches in one call"},
+                            "kind": {"type": "string", "description": "Filter: function | class | module | variable"},
+                            "limit": {"type": "integer", "description": "Max matches (default 20)"},
+                            "max_tokens": {"type": "integer", "description": "Token budget (default 2000; 0 = unbounded)"},
+                            "cursor": {"type": "string", "description": "Continuation token from a previous next_cursor (single-query only)"},
+                            "include_source": {"type": "boolean", "description": "Embed a source snippet on each match, like drift_node (default false)"},
+                            "snippet_lines": {"type": "integer", "description": "Snippet length when include_source is set; omit to size to the symbol's real body length (capped at 200)"},
+                        },
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_node",
+                    description="Node detail: file/line/signature/docstring, source snippet, edge counts by type",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "node_id": {"type": "string", "description": "Node id (qualified or simple name)"},
+                            "node_ids": {"type": "array", "items": {"type": "string"}, "description": "Batch alternative to node_id: fetch several nodes in one call"},
+                            "snippet_lines": {"type": "integer", "description": "Source lines to include; omit to size to the symbol's real body length (capped at 200)"},
+                            "max_tokens": {"type": "integer", "description": "Token budget; trims the snippet from the bottom"},
+                            "max_source_lines": {"type": "integer", "description": "Hard cap on snippet lines"},
+                        },
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_callers",
+                    description="Who depends on this symbol (depth-bounded reverse walk over calls/refs/types)",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "symbol": {"type": "string"},
+                            "max_depth": {"type": "integer", "description": "BFS depth (default 1)"},
+                            "limit": {"type": "integer", "description": "Max items (default 50)"},
+                            "max_tokens": {"type": "integer", "description": "Token budget (default 2000; 0 = unbounded)"},
+                            "cursor": {"type": "string", "description": "Continuation token from a previous next_cursor"},
+                        },
+                        "required": ["symbol"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_callees",
+                    description="What this symbol depends on (depth-bounded forward walk over calls/instantiations)",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "symbol": {"type": "string"},
+                            "max_depth": {"type": "integer", "description": "BFS depth (default 1)"},
+                            "limit": {"type": "integer", "description": "Max items (default 50)"},
+                            "max_tokens": {"type": "integer", "description": "Token budget (default 2000; 0 = unbounded)"},
+                            "cursor": {"type": "string", "description": "Continuation token from a previous next_cursor"},
+                        },
+                        "required": ["symbol"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_path",
+                    description="Shortest dependency path from one symbol to another. Check "
+                                "`factual` (and per-hop `direction`/`edge_to_next.reversed`) "
+                                "before treating the path as a real call-order trace: an "
+                                "undirected or uncertain hop means the path proves connectivity, "
+                                "not the direction asked about.",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "from_symbol": {"type": "string"},
+                            "to_symbol": {"type": "string"},
+                            "max_tokens": {"type": "integer", "description": "Token budget; middle steps are elided, endpoints kept, `length` stays the true hop count"},
+                            "alternates": {"type": "integer", "description": "Also return up to N alternative simple paths (ids only; default 0)"},
+                        },
+                        "required": ["from_symbol", "to_symbol"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_status",
+                    description="Index health: file/node/edge counts, freshness, staleness flag",
+                    parameters={"type": "object", "properties": {}},
+                ),
+                MCPToolDefinition(
+                    name="drift_communities",
+                    description="Module clusters (Louvain): sizes, top members, dominant module. Also returns god_nodes (highest-degree architectural linchpins).",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "limit": {"type": "integer", "description": "Max communities (default 20)"},
+                            "max_tokens": {"type": "integer", "description": "Token budget (default 2000; 0 = unbounded)"},
+                            "god_nodes_top_n": {"type": "integer", "description": "How many god nodes to include (default 10)"},
+                            "cursor": {"type": "string", "description": "Continuation token from a previous next_cursor"},
+                        },
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_learn",
+                    description="Record tribal knowledge (append-only DB write)",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "topic": {"type": "string"},
+                            "content": {"type": "string"},
+                            "tags": {"type": "array", "items": {"type": "string"}},
+                        },
+                        "required": ["topic", "content"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_approve",
+                    description="Approve a detected pattern by id (flag-only DB write)",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "pattern_id": {"type": "string"},
+                        },
+                        "required": ["pattern_id"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_plan_change",
+                    description="Predict the blast radius of a planned code change. Resolves the target symbol from a natural-language description, runs drift_impact, and returns an editable checklist plus a baseline snapshot for later verification.",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "description": {"type": "string", "description": "Natural-language change request, e.g. 'add required audit_tag to jsonable_encoder'"},
+                            "symbol": {"type": "string", "description": "Optional explicit target symbol; if omitted, resolved from description"},
+                            "max_depth": {"type": "integer", "description": "Impact traversal depth (default 2)"},
+                            "max_tokens": {"type": "integer", "description": "Token budget for the embedded impact report (default 3000; 0 = unbounded)"},
+                            "limit": {"type": "integer", "description": "Max items per impact list"},
+                            "max_nodes": {"type": "integer", "description": "Cap on node ids across the impact lists"},
+                        },
+                        "required": ["description"],
+                    }
+                ),
+                MCPToolDefinition(
+                    name="drift_verify_change",
+                    description="Verify a code change is consistent: incrementally rescan changed files and compare the new impact against the baseline returned by drift_plan_change.",
+                    parameters={
+                        "type": "object",
+                        "properties": {
+                            "baseline": {"type": "object", "description": "Baseline snapshot from drift_plan_change"},
+                            "changed_files": {"type": "array", "items": {"type": "string"}, "description": "Optional list of changed file paths; if omitted, auto-detects changed files"},
+                            "symbol": {"type": "string", "description": "Optional override of the symbol to verify"},
+                            "max_tokens": {"type": "integer", "description": "Token budget for the embedded impact report (default 3000; 0 = unbounded)"},
+                            "limit": {"type": "integer", "description": "Max items per impact list"},
+                            "max_nodes": {"type": "integer", "description": "Cap on node ids across the impact lists"},
+                        },
+                        "required": ["baseline"],
+                    }
+                ),
+            ]
+        )
+
+    def handle_scan(self, params: Dict[str, Any]) -> MCPResponse:
+        """Handle drift_scan tool invocation."""
+        path = Path(params["path"])
+        category_filter = params.get("category")
+        self._configure_backend(path)
+
+        errors: List[Dict[str, str]] = []
+        if path.is_file() and backend_for_file(path) is not None:
+            try:
+                results, _, _ = self._scan_file(path, category_filter)
+            except SCAN_FILE_ERRORS as e:
+                return MCPResponse(
+                    id=params.get("request_id"),
+                    error={"code": -32603, "message": f"Scan failed for {path}: {type(e).__name__}: {e}"}
+                )
+            # P2.11 Part 5: keep the persisted graph consistent with what
+            # was just scanned. The incremental machinery sees only this
+            # file as changed (content hash), so this is a one-file update.
+            self._build_full_graph()
+            errors = self.last_graph_errors
+        elif path.is_dir():
+            results, errors = self._scan_directory(path, category_filter)
+        else:
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": "Invalid path"}
+            )
+
+        scanned = len(results)
+        results, truncated, nxt, err = self._page(
+            "drift_scan", params, results, default_limit=None, default_tokens=None
+        )
+        if err:
+            return err
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "scanned": scanned,
+                "results": results,
+                "truncated": truncated,
+                "next_cursor": nxt,
+                "errors": errors,
+                "error_count": len(errors),
+            }
+        )
+
+    def handle_query(self, params: Dict[str, Any]) -> MCPResponse:
+        """Handle drift_query tool invocation."""
+        category = params.get("category")
+        approved_only = params.get("approved_only", False)
+        limit = params.get("limit", 50)
+
+        patterns = self.memory.get_patterns(category=category, approved_only=approved_only)
+        patterns, truncated, nxt, err = self._page(
+            "drift_query", {**params, "limit": limit}, patterns, default_limit=50, default_tokens=None
+        )
+        if err:
+            return err
+
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={"patterns": patterns, "count": len(patterns), "truncated": truncated, "next_cursor": nxt}
+        )
+
+    # ---- shared P2.11 helpers ----
+
+    @staticmethod
+    def _apply_budget(
+        items: List[Dict[str, Any]],
+        limit: Optional[int] = None,
+        max_tokens: Optional[int] = None,
+    ) -> Tuple[List[Dict[str, Any]], int]:
+        """Trim a relevance-ordered list (P2.11 token-budget convention).
+
+        ``max_tokens`` is estimated at 4 chars/token on the JSON-serialized
+        items; trimming drops from the tail, so callers must pass items
+        highest-relevance first. Returns (kept, truncated_count).
+        """
+        total = len(items)
+        if limit is not None and limit >= 0:
+            items = items[:limit]
+        if max_tokens is not None and max_tokens > 0:
+            budget = max_tokens * 4
+            used = 0
+            kept: List[Dict[str, Any]] = []
+            for it in items:
+                cost = len(json.dumps(it, default=str))
+                if kept and used + cost > budget:
+                    break
+                kept.append(it)
+                used += cost
+            items = kept
+        return items, total - len(items)
+
+    # MCP_TOKEN_BUDGET_PLAN.md Lớp 1 — budget for the tools that had none.
+    # Convention: *_count fields stay exact, list fields are ordered
+    # (depth asc, confidence desc, id) and cut; ``truncated`` reports what
+    # was dropped. Defaults follow HARNESS.md ("max_tokens=2000 on impact");
+    # pass max_tokens=0/null for the unbounded report.
+    # Lớp 2: an edge is "uncertain" below this confidence or when the resolver
+    # fanned out over an interface (metadata.strategy == interface_fanout,
+    # confidence 0.45). HARNESS.md already tells agents to treat < 0.6 that way.
+    UNCERTAIN_CONFIDENCE = 0.6
+    UNCERTAIN_RESOLUTIONS = frozenset({"interface_fanout"})
+    DEFAULT_MAX_TOKENS = 2000          # search / graph / callers / callees / communities
+    # Snippet sizing (P7 continuation, 2026-10-01): when the caller doesn't pin
+    # snippet_lines, size the snippet to the symbol's real body (node.end_line)
+    # instead of a flat default -- a method longer than DEFAULT_SNIPPET_LINES no
+    # longer needs a follow-up Read just to see the rest of it. Capped at
+    # MAX_ADAPTIVE_SNIPPET_LINES so one pathological (e.g. generated) method
+    # can't blow up a response by default; an explicit snippet_lines/
+    # max_source_lines always overrides both.
+    DEFAULT_SNIPPET_LINES = 10
+    MAX_ADAPTIVE_SNIPPET_LINES = 200
+    # Higher than DEFAULT_MAX_TOKENS: drift_impact splits its budget across 8
+    # lists (direct/initializer/uncertain callers, entry points, affected
+    # files/members, transitive callers). _round_robin_take gives each list a
+    # turn per round, but on a hub symbol with ~80+ real callers even that
+    # round-robin needs real room to move past everyone's 1-item floor.
+    IMPACT_DEFAULT_MAX_TOKENS = 6000
+    PLAN_DEFAULT_MAX_TOKENS = 3000     # plan_change / verify_change (impact + plan text)
+    # max_tokens=0 ("give me everything") is capped here rather than made
+    # truly infinite: an MCP host can outright refuse an oversized tool
+    # result instead of just costing more tokens -- observed live, Claude
+    # Code rejected a 68k-character drift_impact response on a hub symbol
+    # and forced a save-to-file + jq/Bash recovery that cost ~5x more than
+    # the request that triggered it. This ceiling stays well under that
+    # failure point while still being far more complete than the default.
+    IMPACT_UNBOUNDED_MAX_TOKENS = 11000
+    # drift_explore (P7 continuation, 2026-10-01): one call combining impact
+    # + node detail + dependencies, so it needs its own budget split across
+    # all three -- same default as impact alone (it was the highest-value,
+    # most-fielded section in practice) and the same "0 still means a
+    # generous but bounded ceiling" policy as IMPACT_UNBOUNDED_MAX_TOKENS,
+    # applied up front so all three sections share one consistent ceiling
+    # instead of impact alone being capped while detail/dependencies stay
+    # literally unbounded.
+    EXPLORE_DEFAULT_MAX_TOKENS = 6000
+    EXPLORE_UNBOUNDED_MAX_TOKENS = 11000
+
+    @staticmethod
+    def _max_tokens(params: Dict[str, Any], default: Optional[int]) -> Optional[int]:
+        """Budget resolution: absent or null -> ``default``; 0 -> unbounded.
+
+        The stdio layer forwards ``max_tokens=None`` for an omitted argument,
+        so ``params.get("max_tokens", default)`` alone would never apply the
+        default over MCP (the baseline bench found drift_graph at 24k tokens
+        for exactly this reason).
+        """
+        value = params.get("max_tokens")
+        return default if value is None else value
+
+    @staticmethod
+    def _char_budget(max_tokens: Optional[int]) -> Optional[int]:
+        return max_tokens * 4 if max_tokens is not None and max_tokens > 0 else None
+
+    # ---- Lớp 3: continuation ----
+    # A cursor is opaque, self-contained and server-stateless: base64 of
+    # {"t": tool, "a": args fingerprint, "o": offset(s), "f": graph fingerprint}.
+    # The graph fingerprint is the same stat digest _build_full_graph() caches
+    # on, so a cursor minted before a source edit is refused with a clear
+    # message instead of silently paging a different graph.
+    CURSOR_ARGS = (
+        "symbol", "query", "kind", "max_depth", "include_initializers",
+        "category", "approved_only", "path",
+    )
+
+    def _graph_fingerprint(self) -> str:
+        return self._graph_cache.fingerprint if self._graph_cache is not None else ""
+
+    def _cursor_args(self, params: Dict[str, Any]) -> str:
+        return json.dumps({k: params.get(k) for k in self.CURSOR_ARGS if params.get(k) is not None}, sort_keys=True)
+
+    def _make_cursor(self, tool: str, params: Dict[str, Any], offset: Any) -> str:
+        raw = json.dumps({"t": tool, "a": self._cursor_args(params), "o": offset, "f": self._graph_fingerprint()})
+        return base64.urlsafe_b64encode(raw.encode()).decode()
+
+    def _read_cursor(self, tool: str, params: Dict[str, Any]) -> Tuple[Any, Optional[MCPResponse]]:
+        """(offset, None) for a valid cursor, (None, error) otherwise; (0/{} , None) when absent."""
+        cursor = params.get("cursor")
+        if not cursor:
+            return None, None
+        try:
+            data = json.loads(base64.urlsafe_b64decode(cursor.encode()).decode())
+        except (ValueError, UnicodeDecodeError):
+            return None, MCPResponse(id=params.get("request_id"),
+                                     error={"code": -32602, "message": "cursor is not an ADL Drift continuation token"})
+        if data.get("t") != tool or data.get("a") != self._cursor_args(params):
+            return None, MCPResponse(id=params.get("request_id"), error={
+                "code": -32602,
+                "message": f"cursor was issued by {data.get('t')} with different arguments; repeat the original call"})
+        if data.get("f") != self._graph_fingerprint():
+            return None, MCPResponse(id=params.get("request_id"), error={
+                "code": -32602,
+                "message": "cursor is stale: sources changed since it was issued; repeat the original call without cursor"})
+        return data.get("o"), None
+
+    def _page(
+        self, tool: str, params: Dict[str, Any], items: List[Any],
+        *, default_limit: Optional[int], default_tokens: Optional[int],
+    ) -> Tuple[List[Any], int, Optional[str], Optional[MCPResponse]]:
+        """Offset-paged _apply_budget: (kept, truncated, next_cursor, error).
+
+        ``truncated`` counts what is still unread after this page (items
+        before the offset are not counted again); ``next_cursor`` is set only
+        while something remains.
+        """
+        offset, err = self._read_cursor(tool, params)
+        if err:
+            return [], 0, None, err
+        offset = int(offset or 0)
+        kept, truncated = self._apply_budget(
+            items[offset:], params.get("limit", default_limit), self._max_tokens(params, default_tokens)
+        )
+        nxt = self._make_cursor(tool, params, offset + len(kept)) if truncated else None
+        return kept, truncated, nxt, None
+
+    @staticmethod
+    def _cut(items: List[Any], limit: Optional[int], char_budget: Optional[int], cost) -> Tuple[List[Any], int, int]:
+        """Prefix of ``items`` within ``limit`` and ``char_budget``; (kept, dropped, chars_used).
+
+        Same rule as _apply_budget: the first item is always kept so a
+        response never comes back empty under a tiny budget.
+        """
+        kept: List[Any] = []
+        used = 0
+        for it in items:
+            if limit is not None and limit >= 0 and len(kept) >= limit:
+                break
+            c = cost(it)
+            if char_budget is not None and kept and used + c > char_budget:
+                break
+            kept.append(it)
+            used += c
+        return kept, len(items) - len(kept), used
+
+    @staticmethod
+    def _round_robin_take(
+        fields: List[Tuple[str, List[Any], Any]],
+        limit: Optional[int],
+        remaining: Optional[int],
+        remaining_nodes: List[Optional[int]],
+        offsets: Dict[str, int],
+        truncated: Dict[str, int],
+        next_offsets: Dict[str, int],
+    ) -> Tuple[Dict[str, List[Any]], Optional[int]]:
+        """One item per field per round, instead of exhausting field 1's
+        list before field 2 gets a turn -- a hub symbol with hundreds of
+        direct callers can otherwise consume the entire shared char budget
+        on that one field alone, leaving every other field (``affected_files``
+        included) at the bare "always keep >=1" floor. ``fields`` is given in
+        priority order: when the shared budget runs out mid-round, fields
+        already visited that round keep their extra item and later ones in
+        that same round do not -- so priority order still matters, just
+        gradually instead of all-or-nothing per field.
+        """
+        items_of: Dict[str, List[Any]] = {}
+        skip_of: Dict[str, int] = {}
+        cost_of: Dict[str, Any] = {}
+        kept: Dict[str, List[Any]] = {}
+        for name, items, cost in fields:
+            skip = int(offsets.get(name, 0))
+            skip_of[name] = skip
+            items_of[name] = items[skip:]
+            cost_of[name] = cost
+            kept[name] = []
+        active = [name for name in items_of if items_of[name]]
+        while active:
+            progressed = False
+            for name in list(active):
+                items = items_of[name]
+                i = len(kept[name])
+                if i >= len(items):
+                    active.remove(name)
+                    continue
+                if limit is not None and limit >= 0 and i >= limit:
+                    active.remove(name)
+                    continue
+                if remaining_nodes[0] is not None and remaining_nodes[0] <= 0:
+                    active.remove(name)
+                    continue
+                it = items[i]
+                c = cost_of[name](it)
+                if remaining is not None and kept[name] and remaining - c < 0:
+                    active.remove(name)
+                    continue
+                kept[name].append(it)
+                if remaining is not None:
+                    remaining = max(0, remaining - c)
+                if remaining_nodes[0] is not None:
+                    remaining_nodes[0] -= 1
+                progressed = True
+            if not progressed:
+                break
+        for name, items in items_of.items():
+            dropped = len(items) - len(kept[name])
+            if dropped:
+                truncated[name] = dropped
+            next_offsets[name] = skip_of[name] + len(kept[name])
+        return kept, remaining
+
+    def _bound_impact(
+        self,
+        builder: CallGraphBuilder,
+        report: Dict[str, Any],
+        *,
+        limit: Optional[int] = None,
+        max_tokens: Optional[int] = None,
+        max_depth: Optional[int] = None,
+        max_nodes: Optional[int] = None,
+        offsets: Optional[Dict[str, int]] = None,
+    ) -> Dict[str, Any]:
+        """Bounded copy of ``CallGraphBuilder.get_impact_analysis()`` (Lớp 1).
+
+        Lớp 3: ``max_nodes`` caps the number of node ids across all lists;
+        ``offsets`` (from a continuation cursor) skips already-served items
+        per list and ``out["_next_offsets"]`` carries the offsets for the
+        next page (``None`` when nothing remains).
+
+        ``max_depth`` keeps transitive callers at depth <= max_depth and
+        recomputes entry points / files / counts for that horizon (the
+        builder report is unbounded; drift_plan_change promised a depth).
+        Lists are ordered depth asc, confidence desc, id and cut to
+        ``limit`` items / ``max_tokens`` in priority order: direct callers,
+        entry points, files, transitive callers, members. ``node_languages``
+        shrinks to the ids still present. ``truncated`` maps field -> dropped.
+        Counts (``*_count``) are never affected by ``limit``/``max_tokens``.
+        """
+        out = dict(report)
+        nodes = builder._nodes
+        cc = {c["id"]: c for c in report.get("caller_confidence", [])}
+        icc = {c["id"]: c for c in report.get("initializer_caller_confidence", [])}
+        conf = {i: c["confidence"] for i, c in cc.items()}
+        # Lớp 2: resolution of the edge that made each direct caller direct.
+        seeds = [report.get("target"), *report.get("affected_members", [])]
+        for cid, entry in cc.items():
+            for seed in seeds:
+                prov = builder._edge_strategy(cid, seed, entry.get("edge_type")) if seed else {}
+                if prov.get("resolution"):
+                    entry["resolution"] = prov["resolution"]
+                    break
+        trans = dict(report.get("transitive_callers", {}))
+        initializer_trans = dict(report.get("transitive_initializer_callers", {}))
+        depth_limited = False
+        traversed_depths = [*trans.values(), *initializer_trans.values()]
+        if (
+            max_depth is not None and max_depth >= 1
+            and traversed_depths and max(traversed_depths) > max_depth
+        ):
+            trans = {k: v for k, v in trans.items() if v <= max_depth}
+            initializer_trans = {
+                k: v for k, v in initializer_trans.items() if v <= max_depth
+            }
+            depth_limited = True
+        direct_all = sorted(report.get("direct_callers", []), key=lambda i: (-conf.get(i, 0.0), i))
+        initializers = sorted(report.get("initializer_callers", []))
+        uncertain = [i for i in direct_all if i in cc and self._is_uncertain(cc[i])]
+        direct = [i for i in direct_all if i not in set(uncertain)]
+        trans_items = sorted(trans.items(), key=lambda kv: (kv[1], -conf.get(kv[0], 0.0), kv[0]))
+        entry_set = set(report.get("affected_entry_points", []))
+        entries = [c for c, _ in trans_items if c in entry_set]
+        file_depth: Dict[str, int] = {report.get("target_file"): 0}
+        for c, d in trans_items:
+            n = nodes.get(c)
+            if n is not None:
+                file_depth[n.file_path] = min(file_depth.get(n.file_path, d), d)
+        if depth_limited:
+            files = sorted(file_depth, key=lambda f: (file_depth[f], f))
+            out.update({
+                "transitive_caller_count": len(trans_items),
+                "transitive_initializer_caller_count": len(initializer_trans),
+                "affected_entry_count": len(entries),
+                "affected_file_count": len(files),
+                "max_depth": max((d for _, d in trans_items), default=0),
+                "depth_limit": max_depth,
+            })
+        else:
+            files = sorted(report.get("affected_files", []), key=lambda f: (file_depth.get(f, 1 << 30), f))
+        members = list(report.get("affected_members", []))
+
+        truncated: Dict[str, int] = {}
+        offsets = dict(offsets or {})
+        next_offsets: Dict[str, int] = {}
+        remaining_nodes = [max_nodes if max_nodes is not None and max_nodes > 0 else None]
+        char_budget = self._char_budget(max_tokens)
+        if max_tokens == 0:
+            # see IMPACT_UNBOUNDED_MAX_TOKENS -- "unbounded" still gets a
+            # generous, safe ceiling instead of literal infinity.
+            char_budget = self._char_budget(self.IMPACT_UNBOUNDED_MAX_TOKENS)
+        if char_budget is not None or limit is not None or offsets or remaining_nodes[0] is not None:
+            skeleton = {
+                **out, "direct_callers": [], "caller_confidence": [],
+                "initializer_callers": [], "initializer_caller_confidence": [],
+                "transitive_callers": {}, "transitive_initializer_callers": {},
+                "affected_entry_points": [], "affected_files": [], "affected_members": [],
+                "node_languages": {}, "truncated": {},
+            }
+            remaining = None if char_budget is None else max(0, char_budget - len(json.dumps(skeleton, default=str)))
+            initializer_trans_sorted = sorted(initializer_trans.items(), key=lambda kv: (kv[1], kv[0]))
+
+            # Priority order: the two fields a caller most often actually
+            # wants (who calls it directly, what files does it affect)
+            # first. _round_robin_take gives every field a turn each round
+            # rather than letting field 1 exhaust the whole shared budget
+            # before field 2 is even attempted.
+            fields: List[Tuple[str, List[Any], Any]] = [
+                ("direct_callers", direct,
+                 lambda i: len(json.dumps(i)) + 2 + (len(json.dumps(cc[i], default=str)) + 2 if i in cc else 0)),
+                # cost against the relative path -- the same string _rel()
+                # emits below -- not the raw absolute path, which can be 2x
+                # longer and was making this field look far more expensive
+                # than it truncates to.
+                ("affected_files", files, lambda f: len(json.dumps(self._rel(f))) + 2),
+                ("affected_entry_points", entries, lambda i: len(json.dumps(i)) + 2),
+                ("initializer_callers", initializers,
+                 lambda i: len(json.dumps(i)) + 2
+                 + (len(json.dumps(icc[i], default=str)) + 2 if i in icc else 0)),
+                ("uncertain_callers", uncertain, lambda i: len(json.dumps(cc[i], default=str)) + 2),
+                ("transitive_callers", trans_items, lambda kv: len(json.dumps(kv[0])) + 6),
+                ("transitive_initializer_callers", initializer_trans_sorted,
+                 lambda kv: len(json.dumps(kv[0])) + 6),
+                ("affected_members", members, lambda i: len(json.dumps(i)) + 2),
+            ]
+            kept_by_field, remaining = self._round_robin_take(
+                fields, limit, remaining, remaining_nodes, offsets, truncated, next_offsets
+            )
+            direct = kept_by_field["direct_callers"]
+            files = kept_by_field["affected_files"]
+            entries = kept_by_field["affected_entry_points"]
+            initializers = kept_by_field["initializer_callers"]
+            uncertain = kept_by_field["uncertain_callers"]
+            trans_items = kept_by_field["transitive_callers"]
+            initializer_trans_items = kept_by_field["transitive_initializer_callers"]
+            members = kept_by_field["affected_members"]
+        else:
+            initializer_trans_items = sorted(
+                initializer_trans.items(), key=lambda kv: (kv[1], kv[0])
+            )
+
+        out["direct_callers"] = direct
+        out["caller_confidence"] = [cc[i] for i in direct if i in cc]
+        out["initializer_callers"] = initializers
+        out["initializer_caller_confidence"] = [
+            icc[i] for i in initializers if i in icc
+        ]
+        direct_kept = set(direct)
+        out["instantiator_confidence"] = [
+            e for e in report.get("instantiator_confidence", []) if e["id"] in direct_kept
+        ]
+        out["instantiators"] = [e["id"] for e in out["instantiator_confidence"]]
+        out["uncertain_callers"] = [cc[i] for i in uncertain]
+        out["uncertain_caller_count"] = len([i for i in direct_all if i in cc and self._is_uncertain(cc[i])])
+        out["transitive_callers"] = dict(trans_items)
+        out["transitive_initializer_callers"] = dict(initializer_trans_items)
+        out["affected_entry_points"] = entries
+        out["affected_files"] = [self._rel(f) for f in files]
+        out["target_file"] = self._rel(report.get("target_file"))
+        out["affected_members"] = members
+        keep_ids = ({report.get("target")} | set(direct) | set(initializers)
+                    | set(uncertain) | set(members)
+                    | set(out["transitive_callers"])
+                    | set(out["transitive_initializer_callers"])
+                    | set(entries) | set(report.get("ambiguous_matches", [])))
+        langs = {k: v for k, v in report.get("node_languages", {}).items() if k in keep_ids}
+        # Lớp 2: the per-id language map repeats every id once more; keep it
+        # only for polyglot results, otherwise a {language: count} summary.
+        out["languages"] = dict(Counter(report.get("node_languages", {}).values()))
+        if len(set(langs.values())) > 1:
+            out["node_languages"] = langs
+        else:
+            out.pop("node_languages", None)
+        out["truncated"] = truncated
+        out["_next_offsets"] = next_offsets if truncated else None
+        out["summary"] = (
+            f"{out['direct_caller_count']} direct callers ({out['uncertain_caller_count']} uncertain, "
+            f"{out['instantiator_count']} instantiators), "
+            f"{out['initializer_caller_count']} initializer callers"
+            f" ({'included' if out['include_initializers'] else 'separate'}), "
+            f"{out['transitive_initializer_caller_count']} transitive initializers, "
+            f"{out['transitive_caller_count']} transitive, {out['affected_entry_count']} entry points, "
+            f"{out['affected_file_count']} files"
+            + (f" within depth {max_depth}" if depth_limited else "")
+            + (f"; truncated {truncated}" if truncated else "")
+        )
+        return out
+
+    @classmethod
+    def _is_uncertain(cls, item: Dict[str, Any]) -> bool:
+        conf = item.get("confidence")
+        if isinstance(conf, (int, float)) and conf < cls.UNCERTAIN_CONFIDENCE:
+            return True
+        return item.get("resolution") in cls.UNCERTAIN_RESOLUTIONS
+
+    def _rel(self, path: Any) -> Any:
+        """Lớp 2: file paths project-relative — the absolute prefix repeated on
+        every item was ~20 tokens × items per response for nothing."""
+        if not isinstance(path, str) or not path:
+            return path
+        try:
+            return str(Path(path).relative_to(self.project_root))
+        except ValueError:
+            return path
+
+    def _node_summary(self, builder: CallGraphBuilder, node_id: str) -> Dict[str, Any]:
+        """Compact node payload: id, name, type, file, line."""
+        node = builder._nodes.get(node_id)
+        if node is None:
+            return {"id": node_id}
+        return {
+            "id": node_id,
+            "qualified_name": node.qualified_name,
+            "name": node.name,
+            "type": node.node_type.name,
+            "file": self._rel(node.file_path),
+            "line": node.line,
+            "language": node.language,
+            "signature": node.signature,
+        }
+
+    def _resolve_symbol(
+        self, builder: CallGraphBuilder, symbol: str, request_id: Any
+    ) -> Tuple[Optional[str], List[str], Optional[MCPResponse], bool]:
+        """find_nodes + uniform not-found error.
+
+        Returns (node_id, matches, error_response, is_fuzzy). When
+        find_nodes's exact/substring tiers find nothing, falls back to the
+        token-overlap guesser (P7 fuzzy fallback) so a behavior-phrased or
+        slightly-off symbol name still resolves to a best guess instead of
+        an error, with ``is_fuzzy=True`` telling the caller to surface the
+        guesses as uncertain.
+        """
+        matches = builder.find_nodes(symbol)
+        if not matches:
+            fuzzy = self._fuzzy_search_nodes(builder, symbol)
+            if not fuzzy:
+                return None, [], MCPResponse(
+                    id=request_id,
+                    error={"code": -32602, "message": f"Symbol {symbol} not found"},
+                ), False
+            return fuzzy[0]["id"], [m["id"] for m in fuzzy], None, True
+        return matches[0], matches, None, False
+
+    _STOPWORDS = frozenset({
+        "a", "an", "and", "by", "for", "in", "is", "of", "on", "or", "the", "to", "with",
+    })
+
+    _TOKEN_SPLIT_RE = re.compile(
+        r'[^a-zA-Z0-9]+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])'
+    )
+
+    @classmethod
+    def _tokenize(cls, text: str) -> List[str]:
+        """Split an identifier or free-text query into lowercase word tokens.
+
+        Splits camelCase/PascalCase and snake_case/dotted boundaries (so
+        ``detectViolations`` yields ``["detect", "violations"]``) and drops
+        stopwords, so a free-text query tokenizes to roughly the same words
+        as the identifiers it describes.
+        """
+        tokens = [t.lower() for t in cls._TOKEN_SPLIT_RE.split(text) if t]
+        return [t for t in tokens if t not in cls._STOPWORDS]
+
+    @classmethod
+    def _fuzzy_search_nodes(
+        cls,
+        builder: CallGraphBuilder,
+        query: str,
+        kind: Optional[str] = None,
+        limit: int = 10,
+    ) -> List[Dict[str, Any]]:
+        """Token-overlap fallback used when ``_search_nodes``'s exact/substring
+        tiers find nothing.
+
+        Coding questions are often phrased as behavior ("verify
+        detectViolations") rather than an exact identifier, and the tiers in
+        ``_search_nodes`` only match literal substrings of a symbol's name —
+        every such query used to burn a full round trip for zero results.
+        This scores nodes by how many query tokens appear (as a whole token,
+        or as a substring of/containing a candidate token) in the node's
+        name or qualified_name, so the agent gets a ranked guess instead of
+        an empty result.
+        """
+        query_tokens = cls._tokenize(query)
+        if not query_tokens:
+            return []
+        out: List[Dict[str, Any]] = []
+        for nid, node in builder._nodes.items():
+            if kind and node.node_type.name.lower() != kind.lower():
+                continue
+            cand_tokens = set(cls._tokenize(node.name)) | set(cls._tokenize(node.qualified_name))
+            if not cand_tokens:
+                continue
+            hits = sum(
+                1 for qt in query_tokens
+                if qt in cand_tokens or any(qt in ct or ct in qt for ct in cand_tokens)
+            )
+            if hits == 0:
+                continue
+            coverage = hits / len(query_tokens)
+            if coverage < 0.34:
+                continue
+            degree = builder.graph.degree(nid)
+            out.append({
+                "id": nid,
+                "qualified_name": node.qualified_name,
+                "name": node.name,
+                "type": node.node_type.name,
+                "file": node.file_path,
+                "line": node.line,
+                "language": node.language,
+                "signature": node.signature,
+                "degree": degree,
+                "score": round(10 * coverage + math.log2(degree + 1), 2),
+                "fuzzy": True,
+            })
+        out.sort(key=lambda m: (-m["score"], m["id"]))
+        return out[:limit]
+
+    @staticmethod
+    def _search_nodes(
+        builder: CallGraphBuilder, query: str, kind: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """P2.11: ranked symbol search.
+
+        Rank: exact id (100) > exact qualified_name (90, P1.10) > exact name
+        (80) > case-insensitive name (70) > name substring (50) > id /
+        qualified_name substring (30); +log2(degree+1) boost so hubs outrank
+        leaves within a band.
+        """
+        q = query.lower()
+        out: List[Dict[str, Any]] = []
+        for nid, node in builder._nodes.items():
+            if kind and node.node_type.name.lower() != kind.lower():
+                continue
+            if nid == query:
+                base = 100.0
+            elif node.qualified_name == query:
+                base = 90.0
+            elif node.name == query:
+                base = 80.0
+            elif node.name.lower() == q:
+                base = 70.0
+            elif q and q in node.name.lower():
+                base = 50.0
+            elif q and (q in nid.lower() or q in node.qualified_name.lower()):
+                base = 30.0
+            else:
+                continue
+            degree = builder.graph.degree(nid)
+            out.append({
+                "id": nid,
+                "qualified_name": node.qualified_name,
+                "name": node.name,
+                "type": node.node_type.name,
+                "file": node.file_path,
+                "line": node.line,
+                "language": node.language,
+                "signature": node.signature,
+                "degree": degree,
+                "score": round(base + math.log2(degree + 1), 2),
+            })
+        out.sort(key=lambda m: (-m["score"], m["id"]))
+        return out
+
+    @staticmethod
+    def _module_id_for_file(builder: CallGraphBuilder, file_path: Path) -> Optional[str]:
+        """Return the graph module node owned by ``file_path``.
+
+        Java module ids come from the source package declaration, not the file
+        path. Use the builder's persisted ownership table first, then fall back
+        to module-node file paths and finally the Python path-derived id.
+        """
+        raw_path = str(file_path)
+        try:
+            resolved_path = str(file_path.resolve())
+        except OSError:
+            resolved_path = raw_path
+        candidates = {raw_path, resolved_path}
+
+        for module_id, owners in builder._module_owners.items():
+            if candidates.intersection(owners):
+                return module_id
+            for owner in owners:
+                try:
+                    if str(Path(owner).resolve()) == resolved_path:
+                        return module_id
+                except OSError:
+                    continue
+
+        for node_id, node in builder._nodes.items():
+            if node.node_type.name != "MODULE":
+                continue
+            if node.file_path in candidates:
+                return node_id
+            try:
+                if str(Path(node.file_path).resolve()) == resolved_path:
+                    return node_id
+            except OSError:
+                continue
+
+        module_id = builder._path_to_module(file_path)
+        if module_id in builder._nodes:
+            return module_id
+        return None
+
+    def _build_graph_result(
+        self,
+        builder: CallGraphBuilder,
+        node_id: str,
+        matches: List[str],
+        is_fuzzy: bool,
+        limit: Optional[int],
+        max_tokens: Optional[int],
+    ) -> Dict[str, Any]:
+        """Shared single-symbol graph payload builder for handle_graph and its batch path.
+
+        P2.11 Part 5: callers/dependencies are node payloads with
+        edge_type + confidence, not bare id lists.
+        """
+        def _enrich(walk: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+            out = [{**self._node_summary(builder, w["id"]), **w} for w in walk]
+            for w in out:
+                if self._is_uncertain(w):
+                    w["uncertain"] = True
+            return out
+
+        callers = self._order_walk(_enrich(builder.walk_callers(node_id, max_depth=1)))
+        dependencies = self._order_walk(_enrich(builder.walk_callees(node_id, max_depth=None)))
+        callers, callers_truncated = self._apply_budget(callers, limit, max_tokens)
+        dependencies, deps_truncated = self._apply_budget(dependencies, limit, max_tokens)
+        return {
+            "symbol": node_id,
+            "language": builder._nodes[node_id].language,
+            "signature": builder._nodes[node_id].signature,
+            "callers": callers,
+            "dependencies": dependencies,
+            "truncated": callers_truncated + deps_truncated,
+            "is_entry_point": builder._nodes[node_id].is_entry_point,
+            "ambiguous_matches": matches if (len(matches) > 1 or is_fuzzy) else [],
+            "fuzzy_fallback": is_fuzzy,
+        }
+
+    def handle_graph(self, params: Dict[str, Any]) -> MCPResponse:
+        """Handle drift_graph tool invocation.
+
+        Batch: pass `symbols` (list) instead of `symbol` to fetch call
+        graphs for a cluster of related classes in one round trip (P7
+        batch retrieval) instead of one drift_graph call per symbol —
+        a question spanning ~10 classes used to cost ~10 sequential
+        calls just for this step.
+        """
+        symbols = params.get("symbols")
+        limit = params.get("limit")
+        max_tokens = self._max_tokens(params, self.DEFAULT_MAX_TOKENS)
+        builder = self._build_full_graph()
+
+        if symbols:
+            per_item_tokens = max_tokens
+            if max_tokens and len(symbols) > 1:
+                per_item_tokens = max(max_tokens // len(symbols), 1)
+            graphs: List[Dict[str, Any]] = []
+            truncated_total = 0
+            for symbol_name in symbols:
+                node_id, matches, err, is_fuzzy = self._resolve_symbol(
+                    builder, symbol_name, params.get("request_id")
+                )
+                if err:
+                    graphs.append({"symbol": symbol_name, "error": err.error["message"]})
+                    continue
+                g = self._build_graph_result(builder, node_id, matches, is_fuzzy, limit, per_item_tokens)
+                if node_id != symbol_name:
+                    g["requested_symbol"] = symbol_name
+                truncated_total += g["truncated"]
+                graphs.append(g)
+            return MCPResponse(
+                id=params.get("request_id"),
+                result={
+                    "scan_errors": self.last_graph_errors,
+                    "graphs": graphs,
+                    "count": len(graphs),
+                    "truncated": truncated_total,
+                },
+            )
+
+        symbol_name = params["symbol"]
+        node_id, matches, err, is_fuzzy = self._resolve_symbol(
+            builder, symbol_name, params.get("request_id")
+        )
+        if err:
+            return err
+        result = self._build_graph_result(builder, node_id, matches, is_fuzzy, limit, max_tokens)
+        result["scan_errors"] = self.last_graph_errors
+        return MCPResponse(id=params.get("request_id"), result=result)
+
+    @classmethod
+    def _effective_snippet_lines(
+        cls, explicit: Optional[int], node: Optional[GraphNode]
+    ) -> int:
+        """Snippet length for a node: ``explicit`` if the caller set one,
+        otherwise the symbol's real body length (node.end_line - node.line +
+        1) capped at MAX_ADAPTIVE_SNIPPET_LINES, falling back to
+        DEFAULT_SNIPPET_LINES when the node has no end_line (synthetic nodes,
+        pre-P7 cache entries)."""
+        if explicit is not None:
+            return max(1, int(explicit))
+        if node is not None and node.end_line and node.end_line >= node.line:
+            return min(node.end_line - node.line + 1, cls.MAX_ADAPTIVE_SNIPPET_LINES)
+        return cls.DEFAULT_SNIPPET_LINES
+
+    @staticmethod
+    def _read_snippet(file_path: str, line: int, snippet_lines: int) -> Optional[str]:
+        try:
+            fp = Path(file_path)
+            if fp.is_file() and line > 0:
+                lines = fp.read_text(encoding="utf-8", errors="replace").splitlines()
+                start = line - 1
+                return "\n".join(lines[start:start + snippet_lines])
+        except OSError:
+            pass
+        return None
+
+    def _handle_search_batch(
+        self,
+        builder: CallGraphBuilder,
+        params: Dict[str, Any],
+        queries: List[str],
+    ) -> MCPResponse:
+        """Batch drift_search: run each query independently so one empty or
+        fuzzy-fallback query doesn't affect the others — the natural unit
+        for a multi-symbol question is a cluster of queries, not one
+        drift_search call per symbol (P7 batch retrieval)."""
+        kind = params.get("kind")
+        limit = params.get("limit")
+        max_tokens = self._max_tokens(params, self.DEFAULT_MAX_TOKENS)
+        per_item_tokens = max_tokens
+        if max_tokens and len(queries) > 1:
+            per_item_tokens = max(max_tokens // len(queries), 1)
+        include_source = bool(params.get("include_source"))
+        requested_snippet_lines = params.get("snippet_lines")
+        char_budget = self._char_budget(per_item_tokens)
+
+        results: List[Dict[str, Any]] = []
+        truncated_total = 0
+        for query in queries:
+            matches = self._search_nodes(builder, query, kind)
+            fuzzy = False
+            if not matches:
+                matches = self._fuzzy_search_nodes(builder, query, kind)
+                fuzzy = bool(matches)
+            matches, truncated = self._apply_budget(matches, limit, per_item_tokens)
+            if include_source and matches:
+                per_match_budget = (
+                    max(char_budget // len(matches), 1) if char_budget is not None else None
+                )
+                for m in matches:
+                    snippet_lines = self._effective_snippet_lines(
+                        requested_snippet_lines, builder._nodes.get(m["id"])
+                    )
+                    snippet = self._read_snippet(m["file"], m["line"], snippet_lines)
+                    if per_match_budget is not None and snippet:
+                        lines = snippet.splitlines()
+                        while len(lines) > 1 and len("\n".join(lines)) > per_match_budget:
+                            lines.pop()
+                        snippet = "\n".join(lines)
+                    m["snippet"] = snippet
+            truncated_total += truncated
+            results.append({
+                "query": query, "matches": matches, "count": len(matches),
+                "truncated": truncated, "fuzzy_fallback": fuzzy,
+            })
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={"results": results, "count": len(results), "truncated": truncated_total},
+        )
+
+    def handle_search(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_search (P2.11): ranked symbol search with kind filter.
+
+        include_source=true embeds a source snippet directly on each
+        returned match (like drift_node's snippet) so a single-symbol
+        question doesn't need a follow-up drift_node call.
+
+        Batch: pass `queries` (list) instead of `query` to run several
+        searches in one call (P7 batch retrieval) — a question spanning
+        several unrelated symbols used to cost one drift_search call per
+        symbol. Batch mode does not support `cursor`.
+        """
+        builder = self._build_full_graph()
+        queries = params.get("queries")
+        if queries:
+            return self._handle_search_batch(builder, params, queries)
+
+        query = params["query"]
+        matches = self._search_nodes(builder, query, params.get("kind"))
+        fuzzy = False
+        if not matches:
+            matches = self._fuzzy_search_nodes(builder, query, params.get("kind"))
+            fuzzy = bool(matches)
+        matches, truncated, nxt, err = self._page(
+            "drift_search", params, matches, default_limit=20, default_tokens=self.DEFAULT_MAX_TOKENS
+        )
+        if err:
+            return err
+
+        include_source = bool(params.get("include_source"))
+        if include_source and matches:
+            requested_snippet_lines = params.get("snippet_lines")
+            char_budget = self._char_budget(params.get("max_tokens"))
+            per_item_budget = (
+                max(char_budget // len(matches), 1) if char_budget is not None else None
+            )
+            for m in matches:
+                snippet_lines = self._effective_snippet_lines(
+                    requested_snippet_lines, builder._nodes.get(m["id"])
+                )
+                snippet = self._read_snippet(m["file"], m["line"], snippet_lines)
+                if per_item_budget is not None and snippet:
+                    lines = snippet.splitlines()
+                    while len(lines) > 1 and len("\n".join(lines)) > per_item_budget:
+                        lines.pop()
+                    snippet = "\n".join(lines)
+                m["snippet"] = snippet
+
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={"query": query, "matches": matches,
+                    "count": len(matches), "truncated": truncated, "next_cursor": nxt,
+                    "fuzzy_fallback": fuzzy},
+        )
+
+    def _build_node_result(
+        self,
+        builder: CallGraphBuilder,
+        node_id: str,
+        matches: List[str],
+        is_fuzzy: bool,
+        requested_snippet_lines: Optional[int],
+        max_source_lines: Optional[int],
+        char_budget: Optional[int],
+    ) -> Dict[str, Any]:
+        """Shared single-node payload builder for handle_node and its batch path."""
+        node = builder._nodes[node_id]
+        snippet_lines = self._effective_snippet_lines(requested_snippet_lines, node)
+        if max_source_lines is not None and int(max_source_lines) > 0:
+            snippet_lines = min(snippet_lines, int(max_source_lines))
+        snippet = self._read_snippet(node.file_path, node.line, snippet_lines)
+
+        in_counts: Counter = Counter(
+            d.get("type") for _, _, d in builder.graph.in_edges(node_id, data=True)
+        )
+        out_counts: Counter = Counter(
+            d.get("type") for _, _, d in builder.graph.out_edges(node_id, data=True)
+        )
+        result = {
+                **self._node_summary(builder, node_id),
+                "module": node.module.split("::", 1)[-1],
+                "signature": node.signature,
+                "docstring": node.docstring,
+                "decorators": node.decorators,
+                "is_async": node.is_async,
+                "is_entry_point": node.is_entry_point,
+                "is_test": node.is_test,
+                "contained_in": node.contained_in,
+                "metadata": node.metadata,
+                "snippet": snippet,
+                "in_edges": dict(in_counts),
+                "out_edges": dict(out_counts),
+                "ambiguous_matches": matches if (len(matches) > 1 or is_fuzzy) else [],
+                "fuzzy_fallback": is_fuzzy,
+        }
+        # Lớp 1: max_tokens trims the snippet from the bottom; everything
+        # else on a node is scalar. truncated = source lines dropped --
+        # either the snippet is shorter than the symbol's real body (capped
+        # adaptive default, or an explicit snippet_lines/max_source_lines
+        # smaller than the body) or max_tokens trimmed it further below.
+        truncated = 0
+        if node.end_line and node.end_line >= node.line:
+            body_lines = node.end_line - node.line + 1
+            if body_lines > snippet_lines:
+                truncated += body_lines - snippet_lines
+        if char_budget is not None and snippet:
+            lines = snippet.splitlines()
+            overhead = len(json.dumps({**result, "snippet": "", "truncated": 0}, default=str))
+            while len(lines) > 1 and overhead + len("\n".join(lines)) > char_budget:
+                lines.pop()
+                truncated += 1
+            result["snippet"] = "\n".join(lines)
+        result["truncated"] = truncated
+        return result
+
+    def _handle_node_batch(
+        self,
+        builder: CallGraphBuilder,
+        params: Dict[str, Any],
+        node_ids: List[str],
+        requested_snippet_lines: Optional[int],
+        max_source_lines: Optional[int],
+    ) -> MCPResponse:
+        """Batch drift_node: resolve + build each id independently so one
+        missing/ambiguous symbol doesn't fail the whole cluster lookup —
+        the natural unit for a multi-class question is a cluster, not a
+        single symbol (P7 batch retrieval)."""
+        total_char_budget = self._char_budget(params.get("max_tokens"))
+        per_item_budget = (
+            max(total_char_budget // max(len(node_ids), 1), 1)
+            if total_char_budget is not None else None
+        )
+        nodes: List[Dict[str, Any]] = []
+        truncated = 0
+        for requested_id in node_ids:
+            node_id, matches, err, is_fuzzy = self._resolve_symbol(
+                builder, requested_id, params.get("request_id")
+            )
+            if err:
+                nodes.append({"id": requested_id, "error": err.error["message"]})
+                continue
+            node_result = self._build_node_result(
+                builder, node_id, matches, is_fuzzy,
+                requested_snippet_lines, max_source_lines, per_item_budget,
+            )
+            if node_id != requested_id:
+                node_result["requested_id"] = requested_id
+            truncated += node_result["truncated"]
+            nodes.append(node_result)
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={"nodes": nodes, "count": len(nodes), "truncated": truncated},
+        )
+
+    def handle_node(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_node (P2.11): node detail + source snippet + edge counts.
+
+        Batch: pass `node_ids` (list) instead of `node_id` to fetch several
+        nodes in one call (P7 batch retrieval) — a question spanning
+        several classes used to cost one drift_search + drift_node pair
+        per class.
+
+        snippet_lines, when omitted, is sized to the symbol's real body
+        (node.end_line), capped at MAX_ADAPTIVE_SNIPPET_LINES, instead of a
+        flat default — pass snippet_lines explicitly to override either way.
+        """
+        builder = self._build_full_graph()
+        requested_snippet_lines = params.get("snippet_lines")
+        max_source_lines = params.get("max_source_lines")
+
+        node_ids = params.get("node_ids")
+        if node_ids:
+            return self._handle_node_batch(builder, params, node_ids, requested_snippet_lines, max_source_lines)
+
+        node_id, matches, err, is_fuzzy = self._resolve_symbol(
+            builder, params["node_id"], params.get("request_id")
+        )
+        if err:
+            return err
+        char_budget = self._char_budget(params.get("max_tokens"))
+        result = self._build_node_result(
+            builder, node_id, matches, is_fuzzy, requested_snippet_lines, max_source_lines, char_budget
+        )
+        return MCPResponse(id=params.get("request_id"), result=result)
+
+    @staticmethod
+    def _order_walk(items: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Lớp 1: deterministic relevance order before tail-drop — depth asc,
+        confidence desc, id — so a budget keeps the nearest, surest items."""
+        return sorted(
+            items,
+            key=lambda w: (w.get("depth", 0), -float(w.get("confidence") or 0.0), w["id"]),
+        )
+
+    def _handle_walk(self, params: Dict[str, Any], direction: str) -> MCPResponse:
+        """Shared drift_callers / drift_callees implementation."""
+        builder = self._build_full_graph()
+        node_id, matches, err, is_fuzzy = self._resolve_symbol(
+            builder, params["symbol"], params.get("request_id")
+        )
+        if err:
+            return err
+        max_depth = params.get("max_depth", 1)
+        walk_fn = builder.walk_callers if direction == "callers" else builder.walk_callees
+        items = self._order_walk([
+            {**self._node_summary(builder, w["id"]), **w}
+            for w in walk_fn(node_id, max_depth=max_depth)
+        ])
+        # Lớp 2: factual items first, uncertain (low confidence / interface
+        # fan-out) after them, one budget over both so the sure ones survive.
+        certain = [w for w in items if not self._is_uncertain(w)]
+        uncertain = [w for w in items if self._is_uncertain(w)]
+        kept, truncated, nxt, err = self._page(
+            f"drift_{direction}", params, certain + uncertain,
+            default_limit=50, default_tokens=self.DEFAULT_MAX_TOKENS,
+        )
+        if err:
+            return err
+        sure = [w for w in kept if not self._is_uncertain(w)]
+        unsure = [w for w in kept if self._is_uncertain(w)]
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "symbol": node_id,
+                direction: sure,
+                "uncertain": unsure,
+                "count": len(sure),
+                "uncertain_count": len(unsure),
+                "truncated": truncated,
+                "next_cursor": nxt,
+                "max_depth": max_depth,
+                "ambiguous_matches": matches if (len(matches) > 1 or is_fuzzy) else [],
+                "fuzzy_fallback": is_fuzzy,
+            },
+        )
+
+    def handle_callers(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_callers (P2.11): depth-bounded reverse dependency walk."""
+        return self._handle_walk(params, "callers")
+
+    def handle_callees(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_callees (P2.11): depth-bounded forward dependency walk."""
+        return self._handle_walk(params, "callees")
+
+    def handle_path(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_path (P2.11): shortest path between two symbols.
+
+        `factual` is true only when every hop is a directed, non-uncertain
+        edge — only then does the path order reflect an actual call
+        direction. A "trace how A reaches B" question must check `factual`
+        (or the per-hop `direction`/`edge_to_next.reversed`) before quoting
+        the path as a forward trace; an undirected path (e.g. built from
+        reference edges) only proves A and B are connected, not which one
+        calls the other.
+        """
+        builder = self._build_full_graph()
+        src_id, src_matches, err, src_fuzzy = self._resolve_symbol(
+            builder, params["from_symbol"], params.get("request_id")
+        )
+        if err:
+            return err
+        dst_id, dst_matches, err, dst_fuzzy = self._resolve_symbol(
+            builder, params["to_symbol"], params.get("request_id")
+        )
+        if err:
+            return err
+        ambiguous_matches = {
+            "from": src_matches if (len(src_matches) > 1 or src_fuzzy) else [],
+            "to": dst_matches if (len(dst_matches) > 1 or dst_fuzzy) else [],
+        }
+        path = builder.find_path(src_id, dst_id)
+        if path is None:
+            return MCPResponse(
+                id=params.get("request_id"),
+                result={
+                    "from": src_id, "to": dst_id, "no_path": True,
+                    "ambiguous_matches": ambiguous_matches,
+                },
+            )
+        steps = [
+            {**self._node_summary(builder, step["id"]),
+             "edge_to_next": step["edge_to_next"]}
+            for step in path["path"]
+        ]
+        # Lớp 1: a path cannot be tail-dropped; under max_tokens the middle
+        # is elided (endpoints always kept), ``length`` stays the true hop
+        # count and ``truncated`` = steps elided.
+        truncated = 0
+        char_budget = self._char_budget(params.get("max_tokens"))
+        if char_budget is not None:
+            while len(steps) > 2 and len(json.dumps(steps, default=str)) > char_budget:
+                steps.pop(len(steps) // 2)
+                truncated += 1
+        path["path"] = steps
+        # Lớp 3: the primary (shortest) path first; up to `alternates` further
+        # simple paths on request, ids only, directed graph only.
+        alternates: List[Dict[str, Any]] = []
+        want = int(params.get("alternates") or 0)
+        if want > 0 and path["direction"] == "directed":
+            alternates = builder.alternate_paths(src_id, dst_id, want)
+        path["alternates"] = alternates
+        hops = [s["edge_to_next"] for s in path["path"] if s.get("edge_to_next")]
+        factual = path["direction"] == "directed" and not any(self._is_uncertain(h) for h in hops)
+        uncertain_hops = sum(1 for h in hops if self._is_uncertain(h))
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "from": src_id, "to": dst_id, "no_path": False, **path,
+                "factual": factual,
+                "truncated": truncated,
+                "ambiguous_matches": ambiguous_matches,
+                "summary": f"{path['length']} hops, {path['direction']}, "
+                           f"{uncertain_hops} uncertain hop(s)" + (f", {truncated} elided" if truncated else ""),
+            },
+        )
+
+    def handle_status(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_status (P2.11): index freshness + health, without
+        triggering a rebuild (a rebuild would mask staleness)."""
+        meta = self.memory.get_graph_metadata(self.project_path)
+        files = self._find_files(self.project_path)
+        max_mtime = 0.0
+        for fp in files:
+            try:
+                max_mtime = max(max_mtime, fp.stat().st_mtime)
+            except OSError:
+                continue
+        stale = (
+            meta is None
+            or meta["graph_version"] != GRAPH_SCHEMA_VERSION
+            or max_mtime > (meta["saved_at"] or 0.0)
+        )
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "project": str(self.project_path),
+                "indexed": meta is not None,
+                "stale": stale,
+                "source_files": len(files),
+                "current_schema_version": GRAPH_SCHEMA_VERSION,
+                "graph": meta,
+                "scan_errors": self.last_graph_errors,
+            },
+        )
+
+    def handle_communities(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_communities (P2.11): Louvain clusters for repo orientation."""
+        builder = self._build_full_graph()
+        membership = detect_communities(builder.graph)
+        groups: Dict[int, List[str]] = {}
+        for nid, cid in membership.items():
+            groups.setdefault(cid, []).append(nid)
+
+        communities: List[Dict[str, Any]] = []
+        for cid, members in groups.items():
+            by_degree = sorted(members, key=lambda n: -builder.graph.degree(n))
+            modules = Counter(
+                builder._nodes[n].module for n in members if n in builder._nodes
+            )
+            communities.append({
+                "id": cid,
+                "size": len(members),
+                "top_members": by_degree[:5],
+                "dominant_module": modules.most_common(1)[0][0] if modules else None,
+            })
+        communities.sort(key=lambda c: (-c["size"], c["id"]))
+        communities, truncated, nxt, err = self._page(
+            "drift_communities", params, communities, default_limit=20, default_tokens=self.DEFAULT_MAX_TOKENS
+        )
+        if err:
+            return err
+        god_nodes = builder.god_nodes(top_n=params.get("god_nodes_top_n", 10))
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "communities": communities,
+                "count": len(communities),
+                "total_communities": len(groups),
+                "truncated": truncated,
+                "next_cursor": nxt,
+                "god_nodes": god_nodes,
+            },
+        )
+
+    def handle_learn(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_learn (P2.11 Part 3): record tribal knowledge.
+
+        Append-only DB write; inputs length-capped, no filesystem access.
+        """
+        topic = (params.get("topic") or "").strip()
+        content = (params.get("content") or "").strip()
+        tags = params.get("tags") or []
+        if not topic or not content:
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": "topic and content are required"},
+            )
+        if len(topic) > self.MAX_TOPIC_LEN or len(content) > self.MAX_CONTENT_LEN:
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": (
+                    f"topic must be <= {self.MAX_TOPIC_LEN} chars and content "
+                    f"<= {self.MAX_CONTENT_LEN} chars"
+                )},
+            )
+        if not isinstance(tags, list) or len(tags) > self.MAX_TAGS \
+           or any(not isinstance(t, str) for t in tags):
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": f"tags must be <= {self.MAX_TAGS} strings"},
+            )
+        knowledge_id = self.memory.add_tribal_knowledge(topic, content, tags)
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={"id": knowledge_id, "topic": topic, "stored": True},
+        )
+
+    def handle_approve(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_approve (P2.11 Part 3): flag a pattern as approved.
+
+        Id validated against existing rows — flag-only DB write.
+        """
+        pattern_id = (params.get("pattern_id") or "").strip()
+        existing = self.memory.get_pattern(pattern_id) if pattern_id else None
+        if existing is None:
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": f"Pattern {pattern_id!r} not found"},
+            )
+        self.memory.approve_pattern(pattern_id)
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "approved": True,
+                "pattern_id": pattern_id,
+                "name": existing.get("name"),
+                "category": existing.get("category"),
+            },
+        )
+
+    def _impact_report_with_fallback(
+        self, builder: CallGraphBuilder, symbol: str, include_initializers: bool
+    ) -> Tuple[Dict[str, Any], bool, List[str]]:
+        """``get_impact_analysis`` + a fuzzy-guess second try, shared by
+        handle_impact and handle_explore.
+
+        ``get_impact_analysis`` merges across every distinct exact/substring
+        match itself (so it intentionally does not collapse to a single id
+        the way ``_resolve_symbol`` does) -- fuzzy fallback is therefore only
+        tried as a second step, when that exact/substring search finds
+        nothing at all. Without this, a behavior-phrased or slightly-off
+        symbol name forced a drift_search round trip just to find the exact
+        name before drift_impact would accept it, the single most common
+        multi-call chain observed in real agent sessions.
+        """
+        report = builder.get_impact_analysis(symbol, include_initializers=include_initializers)
+        fuzzy_fallback = False
+        ambiguous_matches: List[str] = []
+        if "error" in report:
+            fuzzy = self._fuzzy_search_nodes(builder, symbol)
+            if fuzzy:
+                report = builder.get_impact_analysis(
+                    fuzzy[0]["id"], include_initializers=include_initializers
+                )
+                fuzzy_fallback = True
+                ambiguous_matches = [m["id"] for m in fuzzy]
+        return report, fuzzy_fallback, ambiguous_matches
+
+    def handle_impact(self, params: Dict[str, Any]) -> MCPResponse:
+        """Handle drift_impact - blast-radius for a symbol."""
+        builder = self._build_full_graph()
+        symbol = params["symbol"]
+        include_initializers = bool(params.get("include_initializers", False))
+        report, fuzzy_fallback, ambiguous_matches = self._impact_report_with_fallback(
+            builder, symbol, include_initializers
+        )
+        if "error" in report:
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": report["error"]},
+            )
+        offsets, err = self._read_cursor("drift_impact", params)
+        if err:
+            return err
+        report = self._bound_impact(
+            builder, report,
+            limit=params.get("limit"),
+            max_tokens=self._max_tokens(params, self.IMPACT_DEFAULT_MAX_TOKENS),
+            max_depth=params.get("max_depth"),
+            max_nodes=params.get("max_nodes"),
+            offsets=offsets,
+        )
+        nxt = report.pop("_next_offsets")
+        report["next_cursor"] = self._make_cursor("drift_impact", params, nxt) if nxt else None
+        report["scan_errors"] = self.last_graph_errors
+        report["fuzzy_fallback"] = fuzzy_fallback
+        if fuzzy_fallback:
+            # get_impact_analysis's own ambiguous_matches (multiple exact
+            # matches merged by _distinct_impact_targets) only applies to the
+            # exact/substring path; a fuzzy resolution replaces it with its
+            # own candidate list instead of stacking on top of it.
+            report["ambiguous_matches"] = ambiguous_matches
+        return MCPResponse(id=params.get("request_id"), result=report)
+
+    def handle_explore(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_explore: everything about one symbol in a single call.
+
+        Combines what used to take up to 3 round trips on the same symbol
+        (the most common multi-tool chains in real agent sessions, after
+        search->impact itself: impact->graph, impact->callers, graph->
+        callers) -- resolved detail (signature/docstring/snippet, like
+        drift_node), blast radius (direct + transitive callers, like
+        drift_impact), and dependencies (what it calls, like drift_graph's
+        ``dependencies``) -- into one response. A new, additive tool:
+        drift_node/drift_impact/drift_graph/drift_callers/drift_callees are
+        unchanged and still the right call for a narrower, single-aspect
+        question or for paging through a huge list via ``cursor`` (this
+        tool does not support one).
+
+        Token budget (default EXPLORE_DEFAULT_MAX_TOKENS, 0 = unbounded) is
+        split across the three sections -- impact gets the largest share
+        since it has the most fields and was the highest-value part in
+        practice; ``*_truncated`` on each section reports what was cut.
+        """
+        builder = self._build_full_graph()
+        symbol = params["symbol"]
+        include_initializers = bool(params.get("include_initializers", False))
+        report, fuzzy_fallback, ambiguous_matches = self._impact_report_with_fallback(
+            builder, symbol, include_initializers
+        )
+        if "error" in report:
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": report["error"]},
+            )
+        target_id = report["target"]
+
+        total_tokens = self._max_tokens(params, self.EXPLORE_DEFAULT_MAX_TOKENS)
+        if total_tokens == 0:
+            # "unbounded" still gets a generous, safe ceiling (same policy,
+            # same value as IMPACT_UNBOUNDED_MAX_TOKENS) instead of letting
+            # detail/dependencies stay literally uncapped while impact alone
+            # would get bounded by _bound_impact's own such a check.
+            total_tokens = self.EXPLORE_UNBOUNDED_MAX_TOKENS
+        impact_tokens = max(int(total_tokens * 0.55), 1)
+        deps_tokens = max(int(total_tokens * 0.25), 1)
+        detail_tokens = max(total_tokens - impact_tokens - deps_tokens, 1)
+
+        impact = self._bound_impact(
+            builder, report,
+            limit=params.get("limit"),
+            max_tokens=impact_tokens,
+            max_depth=params.get("max_depth"),
+            max_nodes=params.get("max_nodes"),
+        )
+        impact.pop("_next_offsets", None)
+        for key in ("query", "target", "target_name", "target_file",
+                    "target_language", "ambiguous_matches"):
+            impact.pop(key, None)
+
+        detail = self._build_node_result(
+            builder, target_id, [], False,
+            params.get("snippet_lines"), params.get("max_source_lines"),
+            self._char_budget(detail_tokens),
+        )
+        detail.pop("ambiguous_matches", None)
+        detail.pop("fuzzy_fallback", None)
+        detail_truncated = detail.pop("truncated", 0)
+
+        callees_depth = params.get("callees_depth", 1)
+        dependencies = self._order_walk([
+            {**self._node_summary(builder, w["id"]), **w}
+            for w in builder.walk_callees(target_id, max_depth=callees_depth)
+        ])
+        for w in dependencies:
+            if self._is_uncertain(w):
+                w["uncertain"] = True
+        dependencies, deps_truncated = self._apply_budget(dependencies, params.get("limit"), deps_tokens)
+
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "symbol": symbol,
+                "target": target_id,
+                "fuzzy_fallback": fuzzy_fallback,
+                "ambiguous_matches": ambiguous_matches,
+                "detail": detail,
+                "detail_truncated": detail_truncated,
+                "impact": impact,
+                "dependencies": dependencies,
+                "dependencies_truncated": deps_truncated,
+                "scan_errors": self.last_graph_errors,
+            },
+        )
+
+    # ---- harness workflow tools (Antigravity predict-edit-prove loop) ----
+
+    def _resolve_symbol_from_description(
+        self, builder: CallGraphBuilder, description: str, request_id: Any
+    ) -> Tuple[Optional[str], Optional[MCPResponse]]:
+        """Try to find a symbol query from a natural-language change description.
+
+        1. Look for backtick/quoted identifiers.
+        2. Try likely symbol tokens (dotted, underscored, CamelCase, or any
+           identifier-like word) — the first one that matches *anything* in
+           the graph wins.
+        3. Fall back to drift_search on the full description.
+
+        Returns (query, error_response); either is set. Bugfix: this used to
+        resolve the winning token down to a single ``matches[0]`` node id via
+        ``_resolve_symbol`` before returning it, which silently discarded any
+        ambiguity that token itself carried (e.g. an overloaded factory
+        method) before ``get_impact_analysis`` ever got a chance to merge or
+        report it. It now returns the raw token/id string unresolved, so the
+        caller can feed it straight into ``get_impact_analysis`` and let that
+        function's own matches/targets merge and ``ambiguous_*`` reporting run
+        as designed.
+        """
+        # Candidate extraction: backticks, quotes, or identifier-like tokens.
+        candidates: List[str] = []
+        for match in re.finditer(r"`([^`]+)`|\"([^\"]+)\"|'([^']+)'", description):
+            candidates.extend(p for p in match.groups() if p)
+        for token in re.findall(r"[A-Za-z_][A-Za-z0-9_.]*", description):
+            if len(token) >= 2 and token not in candidates:
+                candidates.append(token)
+
+        # Resolve in priority order: quoted candidates first, then symbol-shaped
+        # tokens (dot/underscore/CamelCase), then any remaining word.
+        def _priority(token: str) -> int:
+            if "." in token or "_" in token or token[0].isupper():
+                return 0
+            return 1
+
+        for cand in sorted(candidates, key=_priority):
+            if builder.find_nodes(cand):
+                return cand, None
+
+        # Fallback: ranked search on the full description (already relevance-
+        # ranked by _search_nodes, so matches[0]["id"] here is a deliberate
+        # best guess rather than an arbitrary insertion-order pick).
+        matches = self._search_nodes(builder, description)
+        if matches:
+            return matches[0]["id"], None
+
+        return None, MCPResponse(
+            id=request_id,
+            error={
+                "code": -32602,
+                "message": f"Could not resolve a target symbol from: {description!r}",
+            },
+        )
+
+    def _compact_baseline(self, full: Dict[str, Any]) -> Dict[str, Any]:
+        """Lớp 2: the agent carries only id + counts; the caller / file sets
+        verify needs live in cortex.db (`impact_baselines`). On JUnit5 hubs the
+        full snapshot alone was 15-45k tokens, paid on the way out *and* back."""
+        return {
+            "id": self.memory.save_impact_baseline(full),
+            "symbol": full["symbol"],
+            "node_count": full["node_count"],
+            "calls_edges": full["calls_edges"],
+            "direct_caller_count": full["direct_caller_count"],
+            "affected_file_count": len(full.get("affected_files", [])),
+        }
+
+    def _expand_baseline(self, baseline: Dict[str, Any]) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+        """Accept a compact baseline ({id, ...}) or a full pre-Lớp-2 one."""
+        if "direct_callers" in baseline:
+            return baseline, None
+        bid = baseline.get("id")
+        if not bid:
+            return None, "baseline has neither an id nor direct_callers; pass the baseline object from drift_plan_change"
+        stored = self.memory.load_impact_baseline(str(bid))
+        if stored is None:
+            return None, f"baseline {bid} not found in this project's cortex.db; run drift_plan_change again"
+        return stored, None
+
+    def _impact_baseline(self, builder: CallGraphBuilder, symbol: str) -> Dict[str, Any]:
+        """Snapshot blast-radius-critical facts for consistency checks."""
+        calls = sum(
+            1 for _, _, d in builder.graph.edges(data=True)
+            if d.get("type") == EdgeType.CALLS.name
+        )
+        report = builder.get_impact_analysis(symbol)
+        return {
+            "symbol": symbol,
+            "node_count": len(builder._nodes),
+            "calls_edges": calls,
+            "direct_callers": sorted(report.get("direct_callers", [])),
+            "direct_caller_count": report.get("direct_caller_count", 0),
+            "affected_files": sorted(report.get("affected_files", [])),
+        }
+
+    def handle_plan_change(self, params: Dict[str, Any]) -> MCPResponse:
+        """Predict the blast radius of a planned change and produce a checklist.
+
+        Input: description (required), symbol (optional).
+        Output: resolved symbol, impact report, affected files, editable plan,
+        and a baseline snapshot to pass to drift_verify_change.
+        """
+        description = (params.get("description") or "").strip()
+        if not description:
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": "description is required"},
+            )
+
+        builder = self._build_full_graph()
+        symbol = params.get("symbol", "").strip()
+        request_id = params.get("request_id")
+
+        if symbol:
+            query = symbol
+        else:
+            query, err = self._resolve_symbol_from_description(
+                builder, description, request_id
+            )
+            if err:
+                return err
+
+        # Bugfix: `query` is passed through unresolved (not pre-collapsed to
+        # matches[0] via _resolve_symbol) so get_impact_analysis performs its
+        # own matches/targets merge and reports ambiguous_matches/
+        # ambiguous_targets correctly for an ambiguous name (see drift_path's
+        # equivalent fix) instead of silently analyzing one arbitrary target.
+        impact_report = builder.get_impact_analysis(query)
+        if "error" in impact_report:
+            return MCPResponse(
+                id=request_id,
+                error={"code": -32602, "message": impact_report["error"]},
+            )
+        node_id = impact_report["target"]
+        # Lớp 1: max_depth was advertised (default 2) but never applied; the
+        # embedded report is now depth- and token-bounded like drift_impact.
+        impact_report = self._bound_impact(
+            builder, impact_report,
+            limit=params.get("limit"),
+            max_tokens=self._max_tokens(params, self.PLAN_DEFAULT_MAX_TOKENS),
+            max_depth=params.get("max_depth", 2),
+            max_nodes=params.get("max_nodes"),
+        )
+        impact_report.pop("_next_offsets", None)
+        impact_report["scan_errors"] = self.last_graph_errors
+
+        affected_files = impact_report.get("affected_files", [])
+        more_files = impact_report["truncated"].get("affected_files", 0)
+
+        plan_steps: List[str] = [
+            f"Edit the definition of {node_id}.",
+        ]
+        if impact_report["direct_caller_count"]:
+            plan_steps.append(
+                f"Update {impact_report['direct_caller_count']} direct caller(s) across "
+                f"{impact_report['affected_file_count']} file(s): {', '.join(affected_files)}"
+                + (f" (+{more_files} more)." if more_files else ".")
+            )
+        else:
+            plan_steps.append("No direct callers found — confirm the change surface with drift_search if needed.")
+        plan_steps.append("After editing, call drift_verify_change with the baseline to rescan and prove consistency.")
+
+        # Lớp 2: affected_files / direct_callers are already in `impact`;
+        # repeating them here was the biggest duplicate in the baseline bench.
+        result = {
+            "symbol": node_id,
+            "description": description,
+            "summary": impact_report["summary"],
+            "impact": impact_report,
+            "plan": "\n".join(f"{i + 1}. {step}" for i, step in enumerate(plan_steps)),
+            "baseline": self._compact_baseline(self._impact_baseline(builder, query)),
+            "next_tool": "drift_verify_change",
+        }
+        return MCPResponse(id=request_id, result=result)
+
+    def handle_verify_change(self, params: Dict[str, Any]) -> MCPResponse:
+        """Verify a code change: rescan changed files and compare to a baseline.
+
+        Input: baseline (required, from drift_plan_change), changed_files (optional),
+        symbol (optional override).
+        Output: scan result, consistency verdict, before/after metrics, next actions.
+        """
+        baseline = params.get("baseline")
+        if not isinstance(baseline, dict):
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": "baseline is required (pass the baseline from drift_plan_change)"},
+            )
+
+        baseline, problem = self._expand_baseline(baseline)
+        if problem:
+            return MCPResponse(id=params.get("request_id"), error={"code": -32602, "message": problem})
+
+        symbol = (params.get("symbol") or baseline.get("symbol") or "").strip()
+        if not symbol:
+            return MCPResponse(
+                id=params.get("request_id"),
+                error={"code": -32602, "message": "baseline is missing a symbol"},
+            )
+
+        request_id = params.get("request_id")
+        changed_files = params.get("changed_files") or []
+
+        # 1. Rescan changed files (auto-detect if not provided).
+        if changed_files:
+            scanned = 0
+            errors: List[Dict[str, str]] = []
+            for raw in changed_files:
+                fp = Path(raw)
+                if not fp.is_absolute():
+                    fp = (self.project_path / fp).resolve()
+                if fp.is_file() and backend_for_file(fp) is not None:
+                    try:
+                        self._scan_file(fp, None)
+                        scanned += 1
+                    except SCAN_FILE_ERRORS as e:
+                        errors.append({"file": str(fp), "error": f"{type(e).__name__}: {e}"})
+            # Rebuild graph so subsequent impact uses fresh data.
+            builder = self._build_full_graph()
+            scan_errors = self.last_graph_errors + errors
+        else:
+            scanner = IncrementalScanner(self.memory, self.parser, self.extractor, self.registry)
+            files = self._find_files(self.project_path)
+            changed, _, _deleted = scanner.classify_files(self.project_path, files)
+            # MCP_GRAPH_CACHE_PLAN.md Lớp 2: _build_full_graph() already does
+            # "rebuild if anything changed, else the persisted graph" — and
+            # serves the in-memory copy when nothing changed.
+            builder = self._build_full_graph()
+            scan_errors = self.last_graph_errors
+            scanned = len(changed)
+
+        # 2. Re-run impact on the target symbol.
+        after_report = builder.get_impact_analysis(symbol)
+        if "error" in after_report:
+            return MCPResponse(
+                id=request_id,
+                error={"code": -32602, "message": after_report["error"]},
+            )
+        after_baseline = self._impact_baseline(builder, symbol)
+        # Lớp 1: the embedded report is bounded; the consistency check above
+        # and below uses the full baselines, never the bounded copy.
+        after_report = self._bound_impact(
+            builder, after_report,
+            limit=params.get("limit"),
+            max_tokens=self._max_tokens(params, self.PLAN_DEFAULT_MAX_TOKENS),
+            max_nodes=params.get("max_nodes"),
+        )
+        after_report.pop("_next_offsets", None)
+
+        # 3. Consistency check against baseline.
+        problems: List[str] = []
+        before_nodes = baseline.get("node_count", 0)
+        after_nodes = after_baseline["node_count"]
+        if after_nodes < before_nodes:
+            problems.append(f"node count dropped {before_nodes} -> {after_nodes}")
+
+        before_calls = baseline.get("calls_edges", 0)
+        after_calls = after_baseline["calls_edges"]
+        if before_calls > 0 and after_calls < before_calls * 0.9:
+            problems.append(
+                f"CALLS edges collapsed {before_calls} -> {after_calls} (>10% loss)"
+            )
+
+        before_callers = set(baseline.get("direct_callers", []))
+        after_callers = set(after_baseline["direct_callers"])
+        lost = before_callers - after_callers
+        gained = after_callers - before_callers
+        if lost:
+            problems.append(f"lost {len(lost)} caller edge(s): {sorted(lost)}")
+
+        consistent = not problems and not scan_errors
+        verdict = "CONSISTENT" if consistent else "INCONSISTENT"
+
+        # 4. Suggest next actions.
+        next_actions: List[str] = []
+        if scan_errors:
+            next_actions.append("Fix scan errors and re-run drift_verify_change.")
+        if gained:
+            next_actions.append(
+                f"Review {len(gained)} newly-resolved caller(s): {sorted(gained)}."
+            )
+        if lost:
+            next_actions.append(
+                "Caller edges were lost — check that all call sites were updated and rescan."
+            )
+        if consistent:
+            next_actions.append("Graph is consistent. You can proceed to the next change or finish.")
+
+        result = {
+            "scanned": scanned,
+            "scan_errors": scan_errors,
+            "consistent": consistent,
+            "verdict": verdict,
+            "symbol": symbol,
+            "node_count": {"before": before_nodes, "after": after_nodes},
+            "calls_edges": {"before": before_calls, "after": after_calls},
+            "direct_callers": {
+                "before": baseline.get("direct_caller_count", 0),
+                "after": after_baseline["direct_caller_count"],
+                "lost": sorted(lost),
+                "gained": sorted(gained),
+            },
+            # Lớp 2: the before/after file lists are in the baseline (input)
+            # and in `impact`; only the delta is new information.
+            "affected_files": {
+                "before": len(baseline.get("affected_files", [])),
+                "after": len(after_baseline["affected_files"]),
+                "added": sorted(self._rel(f) for f in set(after_baseline["affected_files"]) - set(baseline.get("affected_files", []))),
+                "removed": sorted(self._rel(f) for f in set(baseline.get("affected_files", [])) - set(after_baseline["affected_files"])),
+            },
+            "summary": f"{verdict}: {after_report['summary']}"
+                       + (f"; lost {len(lost)}, gained {len(gained)}" if lost or gained else ""),
+            "impact": after_report,
+            "next_actions": next_actions,
+        }
+        return MCPResponse(id=request_id, result=result)
+
+    def _build_full_graph(self) -> CallGraphBuilder:
+        """Build or incrementally update the call graph.
+
+        Per-file failures are recorded in ``self.last_graph_errors`` (P2.5)
+        and attached to graph/impact responses.
+
+        MCP_GRAPH_CACHE_PLAN.md Lớp 1: the builder from the previous call is
+        kept in memory with the stat-based source fingerprint it was built or
+        loaded against. An unchanged fingerprint returns it without touching
+        SQLite or hashing any file (``last_graph_errors`` is left as-is: the
+        graph did not change, so neither did its per-file errors). A hit whose
+        newest source mtime lies inside ``GRAPH_CACHE_RACY_WINDOW_SECONDS`` of
+        the cached fingerprint's stat time is confirmed by the content-hash
+        classification first, since such a file may have been rewritten
+        without altering its size/mtime.
+        """
+        taken_at = time.time()
+        # Lớp 2: discover once; the fingerprint, the change classification
+        # and the deleted-file prune below all consume this same list.
+        files = self._find_files(self.project_path)
+        max_mtime, fingerprint = CortexMemory._source_state(self.project_path, files)
+        cache = self._graph_cache
+        cache_hit = cache is not None and cache.fingerprint == fingerprint
+        cached_update = {"mode": "cached", "invalidated_files": [], "reason": "no source changes"}
+        if cache_hit and max_mtime < cache.taken_at - GRAPH_CACHE_RACY_WINDOW_SECONDS:
+            self.last_graph_update = cached_update
+            return cache.builder
+
+        scanner = IncrementalScanner(self.memory, self.parser, self.extractor, self.registry)
+        changed, unchanged, deleted = scanner.classify_files(self.project_path, files)
+
+        if cache_hit and not changed and not deleted:
+            # Racy-window hit confirmed clean by content hash; re-stamp so the
+            # next call outside the window takes the fast path.
+            self._graph_cache = _GraphCacheEntry(fingerprint, taken_at, cache.builder)
+            self.last_graph_update = cached_update
+            return cache.builder
+
+        self.last_graph_errors = []
+        if not changed and not deleted:
+            builder = self.memory.load_graph(self.project_path, files=files)
+            if builder is not None:
+                self._graph_cache = _GraphCacheEntry(fingerprint, taken_at, builder)
+                self.last_graph_update = cached_update
+                return builder
+            # Nothing changed but no valid persisted graph: rebuild from the
+            # cached per-file results below.
+            mode, reason = "full_rebuild", "persisted graph unavailable"
+        else:
+            # MCP_INCREMENTAL_REBUILD_PLAN.md Lớp 1 — same decision as
+            # DriftCommands.build_graph(incremental=True): a Java edit that
+            # changes any declaration surface (or deletes a .java file) can
+            # alter resolution anywhere, so it is a deliberate full rebuild;
+            # a body-only edit re-resolves just the changed units on top of
+            # the persisted graph.
+            builder = None
+            if any(fp.suffix != ".java" for fp in (*changed, *deleted)):
+                # MCP_INCREMENTAL_REBUILD_PLAN.md Decision #9: only Java has a
+                # declaration-fingerprint scope rule. A Python declaration
+                # change would leave callers in *unchanged* files unresolved
+                # (Decision #8), so any non-Java change keeps the pre-Lớp-1
+                # behaviour — correct, full rebuild — until that rule exists.
+                mode, reason = "full_rebuild", "non-Java change: no incremental scope rule for this language yet"
+            else:
+                scope, reason = java_incremental_scope(self.project_path, scanner, changed, deleted)
+                if scope is None:
+                    mode = "full_rebuild"
+                else:
+                    mode = "dependency_scoped"
+                    changed = [fp for fp in changed if fp in scope]
+            if mode != "full_rebuild":
+                # allow_stale: the source fingerprint has moved by definition;
+                # this path removes and rebuilds the invalidated scope itself.
+                builder = self.memory.load_graph(self.project_path, allow_stale=True)
+                if builder is None:
+                    mode, reason = "full_rebuild", "persisted graph unavailable"
+                else:
+                    # Mirror DriftCommands: the persisted graph is keyed by the
+                    # scan root; reapply the project root and drop the derived
+                    # caches so changed files get the same module namespace a
+                    # full rebuild would assign.
+                    builder.project_root = self.project_root.resolve()
+                    builder._project_languages = None
+                    builder._java_build_module_roots = None
+                    builder._java_namespace_visibility = None
+
+        self.last_graph_update = {
+            "mode": mode,
+            "invalidated_files": [str(fp) for fp in (*changed, *deleted)],
+            "reason": reason,
+        }
+        full_rebuild = builder is None
+        if full_rebuild:
+            builder = CallGraphBuilder(project_root=self.project_root)
+            if mode == "full_rebuild" and (changed or deleted) and reason != "persisted graph unavailable":
+                # Deliberate full rebuild (structural Java change): every
+                # file is re-parsed and its cached result refreshed, exactly
+                # like DriftCommands.build_graph(incremental=False).
+                changed, unchanged, deleted = list(files), [], []
+
+        for fp in deleted + changed:
+            builder.remove_file(str(fp))
+
+        parses: Dict[Path, Any] = {}
+        results: Dict[Path, Any] = {}
+
+        for fp in changed:
+            try:
+                self._configure_backend(self.project_path, self._backend_name(fp))
+                pr = self.parser.parse_file(fp)
+                ar = self.extractor._build(pr, fp)
+                # P1.11: this path skips full detection, but the graph still
+                # needs ROUTES patterns to mark route handlers as entry points.
+                ar.patterns = self._route_patterns(pr, fp)
+                parses[fp] = pr
+                results[fp] = ar
+            except SCAN_FILE_ERRORS as e:
+                self.last_graph_errors.append({
+                    "file": str(fp), "error": f"{type(e).__name__}: {e}",
+                })
+        scanner.store_results(self.project_path, list(results.items()))
+
+        results.update(scanner.load_cached_results(self.project_path, unchanged))
+
+        # A persisted builder already owns every unchanged node/edge; adding
+        # those results again repopulates pending indexes and defeats the
+        # scoped update (mirrored from DriftCommands). A fresh builder needs
+        # the complete set.
+        changed_set = set(changed)
+        for fp, ar in results.items():
+            if full_rebuild or fp in changed_set:
+                builder.add_file_result(ar)
+
+        # Full rebuild: re-parse unchanged files too, or their outbound
+        # CALLS edges are lost (P0.5 fix, mirrored from DriftCommands).
+        if full_rebuild:
+            for fp in results.keys():
+                if fp not in parses:
+                    try:
+                        parses[fp] = self._parse_file(fp)
+                    except SCAN_FILE_ERRORS as e:
+                        self.last_graph_errors.append({
+                            "file": str(fp), "error": f"{type(e).__name__}: {e}",
+                        })
+
+        if parses:
+            self._resolve_graph(builder, parses, results)
+        builder.reconcile_edges()
+
+        scanner.prune_deleted_files(self.project_path, {str(f.resolve()) for f in files})
+        self.memory.save_graph(self.project_path, builder, files=files)
+        self._graph_cache = _GraphCacheEntry(fingerprint, taken_at, builder)
+        return builder
+
+    def handle_why(self, params: Dict[str, Any]) -> MCPResponse:
+        """Handle drift_why tool - retrieve tribal knowledge."""
+        topic = params["topic"]
+        knowledge = self.memory.get_tribal_knowledge(topic=topic)
+
+        # Also do semantic search
+        similar = self.memory.search_similar(topic, limit=5)
+
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "topic": topic,
+                "knowledge": knowledge,
+                "similar_patterns": similar,
+            }
+        )
+
+    # drift_context v2 (P2.11 Part 4): closure BFS follows dependency edges
+    # plus CONTAINS, in both directions, at most this many hops from a seed.
+    CONTEXT_CLOSURE_HOPS = 2
+    CONTEXT_SEEDS = 5
+
+    def handle_context(self, params: Dict[str, Any]) -> MCPResponse:
+        """drift_context v2 (P2.11 Part 4) — graph-ranked context assembly.
+
+        1. Seed: query terms ranked against node names (drift_search ranking).
+        2. Closure: BFS <= 2 hops from top-5 seeds over IMPACT_EDGE_TYPES +
+           CONTAINS, both directions.
+        3. Rank: 1/(1+dist) * (1+log2(degree+1)) * community-overlap bonus,
+           normalized to [0, 1].
+        4. Assemble: symbols (signature + first docstring line + file:line),
+           patterns on closure files, tribal knowledge by term match,
+           framework hint.
+        5. Trim to max_tokens (default 2000), lowest score first.
+        """
+        query = params["query"]
+        file_path = params.get("file_path")
+        max_tokens = int(self._max_tokens(params, self.DEFAULT_MAX_TOKENS) or 0)
+        builder = self._build_full_graph()
+
+        # 1. Seeds — best score per node across the full query + its terms.
+        terms = [t for t in re.split(r"[^\w.]+", query) if len(t) >= 3]
+        best: Dict[str, Dict[str, Any]] = {}
+        for term in [query] + terms:
+            for m in self._search_nodes(builder, term):
+                cur = best.get(m["id"])
+                if cur is None or m["score"] > cur["score"]:
+                    best[m["id"]] = m
+        seeds = sorted(best.values(), key=lambda m: -m["score"])[:self.CONTEXT_SEEDS]
+        seed_ids = [s["id"] for s in seeds]
+        # The current file's module node anchors the closure when provided.
+        if file_path:
+            mod_id = self._module_id_for_file(builder, Path(file_path))
+            if mod_id in builder._nodes and mod_id not in seed_ids:
+                seed_ids.append(mod_id)
+
+        # 2. Closure
+        closure_types = set(CallGraphBuilder.IMPACT_EDGE_TYPES) | {EdgeType.CONTAINS.name}
+        dist: Dict[str, int] = {sid: 0 for sid in seed_ids}
+        q: deque = deque((sid, 0) for sid in seed_ids)
+        while q:
+            cur, d = q.popleft()
+            if d >= self.CONTEXT_CLOSURE_HOPS:
+                continue
+            neighbors = [
+                v for _, v, dd in builder.graph.out_edges(cur, data=True)
+                if dd.get("type") in closure_types
+            ] + [
+                u for u, _, dd in builder.graph.in_edges(cur, data=True)
+                if dd.get("type") in closure_types
+            ]
+            for n in neighbors:
+                if n not in dist:
+                    dist[n] = d + 1
+                    q.append((n, d + 1))
+
+        # 3. Rank
+        membership = detect_communities(builder.graph)
+        seed_comms = {membership.get(sid) for sid in seed_ids} - {None}
+        raw: Dict[str, float] = {}
+        for nid, d in dist.items():
+            if nid not in builder._nodes:
+                continue
+            degree = builder.graph.degree(nid)
+            bonus = 1.5 if membership.get(nid) in seed_comms else 1.0
+            raw[nid] = (1.0 / (1.0 + d)) * (1.0 + math.log2(degree + 1)) * bonus
+        max_raw = max(raw.values(), default=1.0)
+
+        # 4. Assemble
+        context_items: List[MCPContextItem] = []
+        file_score: Dict[str, float] = {}
+        for nid, score_raw in raw.items():
+            node = builder._nodes[nid]
+            score = round(score_raw / max_raw, 4)
+            file_score[node.file_path] = max(file_score.get(node.file_path, 0.0), score)
+            doc_lines = (node.docstring or "").strip().splitlines()
+            context_items.append(MCPContextItem(
+                type="symbol",
+                content=f"{node.node_type.name.lower()} {nid}: {node.signature or node.name}",
+                source=f"{self._rel(node.file_path)}:{node.line}",
+                relevance_score=score,
+                metadata={
+                    "docstring": doc_lines[0] if doc_lines else None,
+                    "distance": dist[nid],
+                },
+            ))
+
+        for p in self.memory.get_patterns():
+            rel = 0.8 * file_score.get(p.get("file_path") or "", 0.0)
+            if rel <= 0:
+                continue
+            context_items.append(MCPContextItem(
+                type="pattern",
+                content=f"{p['name']}: {p.get('description') or ''}",
+                source=p.get("file_path"),
+                relevance_score=round(rel, 4),
+            ))
+
+        lowered = [t.lower() for t in [query] + terms]
+        for k in self.memory.get_tribal_knowledge():
+            haystack = f"{k['topic']} {k['content']}".lower()
+            if any(t in haystack for t in lowered):
+                context_items.append(MCPContextItem(
+                    type="tribal_knowledge",
+                    content=k["content"],
+                    source=f"tribal:{k['topic']}",
+                    relevance_score=0.9,
+                ))
+
+        if self.config.frameworks:
+            context_items.append(MCPContextItem(
+                type="framework",
+                content=f"Detected frameworks: {', '.join(self.config.frameworks)}",
+                relevance_score=1.0,
+            ))
+
+        # 5. Trim
+        context_items.sort(key=lambda i: -(i.relevance_score or 0.0))
+        payloads = [item.model_dump() for item in context_items]
+        payloads, truncated = self._apply_budget(payloads, None, max_tokens)
+
+        return MCPResponse(
+            id=params.get("request_id"),
+            result={
+                "query": query,
+                "seeds": seed_ids,
+                "context_items": payloads,
+                "item_count": len(payloads),
+                "truncated": truncated,
+            }
+        )
+
+    def _scan_file(self, path: Path, category_filter: Optional[str] = None):
+        """Scan a single file and return pattern dicts plus parse/extract results."""
+        self._configure_backend(path, self._backend_name(path))
+        parse_result = self.parser.parse_file(path)
+        patterns = self.registry.run_all(parse_result.tree, parse_result.source_bytes, path)
+        ar = self.extractor._build(parse_result, path)
+
+        if category_filter:
+            patterns = [p for p in patterns if p.category.name.lower() == category_filter.lower()]
+
+        # Store in memory
+        self.memory.store_patterns(patterns)
+
+        # P1.11: carry patterns on the result so the graph builder can mark
+        # route handlers (incl. ones nested in a factory) as entry points.
+        ar.patterns = patterns
+
+        results = [{
+            "name": p.name,
+            "category": p.category.name,
+            "description": p.description,
+            "file": str(p.file_path),
+            "line": p.position.line,
+            "confidence": p.confidence,
+            "metadata": p.metadata,
+        } for p in patterns]
+        return results, parse_result, ar
+
+    def _scan_directory(
+        self, path: Path, category_filter: Optional[str] = None
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, str]]]:
+        """Scan all supported files in a directory incrementally.
+
+        Returns (pattern dicts, per-file errors) — P2.5: failures are
+        reported, not swallowed.
+        """
+        files = self._find_files(path)
+        scanner = IncrementalScanner(self.memory, self.parser, self.extractor, self.registry)
+        changed, unchanged, deleted = scanner.classify_files(path, files)
+
+        all_results: List[Dict[str, Any]] = []
+        errors: List[Dict[str, str]] = []
+        parses: Dict[Path, Any] = {}
+        results: Dict[Path, Any] = {}
+        pending_metadata: List[Any] = []
+
+        if should_parallelize(len(changed)):
+            for backend_name, backend_files in self._group_paths(changed).items():
+                self._configure_backend(path, backend_name)
+                for fp, ar, patterns, err in parallel_analyze(
+                    backend_files,
+                    backend_name=backend_name,
+                    category_filter=category_filter,
+                ):
+                    if err is not None or ar is None:
+                        errors.append({"file": str(fp), "error": err or "unknown"})
+                        continue
+                    self.memory.store_patterns(patterns)
+                    for p in patterns:
+                        all_results.append({
+                            "name": p.name,
+                            "category": p.category.name,
+                            "description": p.description,
+                            "file": str(p.file_path),
+                            "line": p.position.line,
+                            "confidence": p.confidence,
+                            "metadata": p.metadata,
+                        })
+                    ar.patterns = patterns
+                    results[fp] = ar
+                    pending_metadata.append((fp, ar))
+            scanner.store_results(path, pending_metadata)
+            pending_metadata = []
+            # Re-parse in main proc to get Trees for resolve_calls.
+            for fp in list(results.keys()):
+                try:
+                    parses[fp] = self._parse_file(fp)
+                except SCAN_FILE_ERRORS as e:
+                    results.pop(fp, None)
+                    errors.append({"file": str(fp), "error": f"{type(e).__name__}: {e}"})
+        else:
+            for file_path in changed:
+                try:
+                    file_results, pr, ar = self._scan_file(file_path, category_filter)
+                    all_results.extend(file_results)
+                    if pr and ar:
+                        parses[file_path] = pr
+                        results[file_path] = ar
+                        pending_metadata.append((file_path, ar))
+                except SCAN_FILE_ERRORS as e:
+                    errors.append({"file": str(file_path), "error": f"{type(e).__name__}: {e}"})
+            scanner.store_results(path, pending_metadata)
+
+        # Load unchanged results for graph completeness
+        for file_path in unchanged:
+            ar = scanner.load_cached_result(path, file_path)
+            if ar is not None:
+                results[file_path] = ar
+
+        # Update graph incrementally
+        if results:
+            # MCP_INCREMENTAL_REBUILD_PLAN.md Lớp 1: same rule as
+            # _build_full_graph / DriftCommands.build_graph — keep the
+            # persisted graph (allow_stale) unless a Java declaration surface
+            # changed or a .java file was deleted, which is a full rebuild.
+            builder = None
+            # Decision #9: non-Java changes have no scope rule → full rebuild.
+            needs_full = any(fp.suffix != ".java" for fp in (*changed, *deleted))
+            if not needs_full and (changed or deleted):
+                scope, _reason = java_incremental_scope(path, scanner, changed, deleted)
+                needs_full = scope is None
+            if not needs_full:
+                builder = self.memory.load_graph(path, allow_stale=True)
+                if builder is not None:
+                    builder.project_root = self.project_root.resolve()
+                    builder._project_languages = None
+                    builder._java_build_module_roots = None
+                    builder._java_namespace_visibility = None
+            full_rebuild = builder is None
+            if full_rebuild:
+                builder = CallGraphBuilder(project_root=self.project_root)
+            for fp in deleted + changed:
+                builder.remove_file(str(fp))
+            # Fresh builder has no nodes for unchanged files — add everything.
+            # Loaded builder already contains them — add only changed files.
+            add_paths = results.keys() if full_rebuild else [fp for fp in changed if fp in results]
+            for fp in add_paths:
+                builder.add_file_result(results[fp])
+            # Full rebuild: re-parse unchanged files too, or their outbound
+            # CALLS edges are lost (P0.5 fix, mirrored from DriftCommands).
+            if full_rebuild:
+                for fp in results.keys():
+                    if fp not in parses:
+                        try:
+                            parses[fp] = self._parse_file(fp)
+                        except SCAN_FILE_ERRORS as e:
+                            errors.append({"file": str(fp), "error": f"{type(e).__name__}: {e}"})
+            if parses:
+                self._resolve_graph(builder, parses, results)
+            builder.reconcile_edges()
+            scanner.prune_deleted_files(path, {str(f.resolve()) for f in files})
+            self.memory.save_graph(path, builder)
+            # MCP_GRAPH_CACHE_PLAN.md Lớp 1: this graph carries the full
+            # detector set (e.g. java_test → is_test) that the ROUTES-only
+            # _build_full_graph() path does not; drop the in-memory copy so
+            # the next query reloads what was just persisted.
+            self._graph_cache = None
+            # P2.19: taint analysis over the freshly built graph.
+            python_parses = {
+                file_path: parse for file_path, parse in parses.items()
+                if self._backend_name(file_path) == "python"
+            }
+            self._run_taint_pass(path, builder, python_parses, all_results, category_filter)
+
+        return all_results, errors
+
+    def _run_taint_pass(
+        self,
+        project_path: Path,
+        builder: CallGraphBuilder,
+        parses: Dict[Path, Any],
+        results: List[Dict[str, Any]],
+        category_filter: Optional[str],
+    ) -> None:
+        """P2.19: run taint analysis, persist paths, surface CRITICAL TAINT
+        findings. Best-effort — never aborts a scan."""
+        if not parses:
+            return
+        try:
+            from adl_drift.detectors.taint import TaintAnalyzer
+            from adl_drift.utils.types import PatternCategory, SourcePosition
+            paths = TaintAnalyzer().analyze(builder, parses)
+        except Exception:
+            return
+        analyzed_fids = set()
+        try:
+            for fp, pr in parses.items():
+                module = builder._path_to_module(fp)
+                for _, nid in builder._iter_func_cst(pr.tree.root_node, pr.source_bytes, module):
+                    analyzed_fids.add(nid)
+        except Exception:
+            pass
+        try:
+            self.memory.store_taint_paths(project_path, paths, replace_function_ids=list(analyzed_fids))
+        except Exception:
+            pass
+        if category_filter and category_filter.lower() != "taint":
+            return
+        for p in paths:
+            chain_str = " -> ".join(p.chain)
+            pat = Pattern(
+                category=PatternCategory.TAINT,
+                name=f"taint_{p.sink_category}",
+                description=f"{p.sink_category}: {chain_str}",
+                position=SourcePosition(
+                    line=p.sink_site.line, column=p.sink_site.column,
+                    end_line=p.sink_site.end_line, end_column=p.sink_site.end_column,
+                ),
+                file_path=Path(p.file_path),
+                confidence=p.confidence,
+                metadata={
+                    "severity": "CRITICAL", "sink": p.sink,
+                    "sink_category": p.sink_category, "source": p.source_label,
+                    "binding": p.binding_name or "", "chain": chain_str,
+                    "cross_function": p.cross_function, "function": p.function_id,
+                },
+            )
+            try:
+                self.memory.store_pattern(pat)
+            except Exception:
+                pass
+            results.append({
+                "name": pat.name, "category": pat.category.name,
+                "description": pat.description, "file": str(pat.file_path),
+                "line": pat.position.line, "confidence": pat.confidence,
+                "metadata": pat.metadata,
+            })
+
+    def _find_files(self, path: Path) -> List[Path]:
+        return sorted(
+            (file for files in self._file_groups(path).values() for file in files),
+            key=str,
+        )
+
+    @classmethod
+    def _find_python_files(cls, path: Path) -> List[Path]:
+        """Compatibility wrapper for downstream Python-only callers."""
+        from adl_drift.lang.registry import get_backend
+
+        return discover_files(path, get_backend("python"))