codegraph-engine 2.3.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

codegraph/mcp/server.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
+import asyncio
 import functools
 import json
 from pathlib import Path
 from typing import Any
 
+import anyio
+
 from codegraph.architecture import get_architecture as arch_get_architecture
 from codegraph.config import Settings
 from codegraph.context import _resolve_task_or_query_input
@@ -442,9 +445,9 @@ def create_server(
         task: dict[str, Any] | str = "",
         intent: str | None = None,
         max_tokens: int = 4000,
-        max_files: int = 15,
+        max_files: int = 25,
         max_lines: int = 500,
-        top_k: int = 15,
+        top_k: int = 25,
         plan: dict[str, Any] | None = None,
         mode: str = "BALANCED",
         explain: bool = False,
@@ -956,6 +959,58 @@ def create_server(
         with indexer.session() as con:
             return runtime_reconcile_static_runtime(con, indexer.repository, symbol=symbol, route=route, table=table)
 
+    def get_live_services() -> dict[str, Any]:
+        """Detect and attribute active localhost services, ports, PIDs, frameworks, and workspace sub-packages with zero idle CPU. Use when diagnosing running dev servers or multi-service architectures. Does not prove live HTTP response payloads or application layer health."""
+        from codegraph.runtime.port_inspector import (
+            discover_live_listening_ports,
+            discover_static_configured_ports,
+        )
+        live = [s.as_dict() for s in discover_live_listening_ports(indexer.repository)]
+        static = [s.as_dict() for s in discover_static_configured_ports(indexer.repository).values()]
+        return {"live_services": live, "configured_services": static, "count": len(live)}
+
+    def check_db_drift() -> dict[str, Any]:
+        """Detect database schema drift between migration files, live database state, and code ORM models with zero idle CPU. Flags unmapped tables, missing columns, and migration version state. Use when verifying whether database migrations are up to date with code models. Does not execute SQL data assertions or validate column constraints against live row data."""
+        from codegraph.runtime.db_watcher import detect_schema_drift
+        with indexer.session() as con:
+            return detect_schema_drift(con, indexer.repository).as_dict()
+
+    def get_distributed_trace(trace_id: str) -> dict[str, Any]:
+        """Stitch and reconstruct multi-service distributed execution trees across frontend, backend, and database boundaries for a specific W3C trace ID. Use when tracing cross-service requests or debugging multi-service latency bottlenecks. Does not capture unobserved code paths or untraced sidecar requests."""
+        from codegraph.runtime.trace_linker import link_distributed_trace
+        with indexer.session() as con:
+            res = link_distributed_trace(con, indexer.repository, trace_id)
+            return res.as_dict() if res else {"status": "not_found", "trace_id": trace_id}
+
+    def check_route_schema_drift(
+        route: str = "",
+        handler: str = "",
+        table: str | None = None,
+        schema: str | None = None,
+    ) -> dict[str, Any]:
+        """Detect schema validation drift between a route/handler input schema (Pydantic BaseModel, Django Form, DRF Serializer) and destination database table columns. Flags MISSING_REQUIRED_COLUMN, NULLABILITY_MISMATCH, TYPE_INCOMPATIBILITY, LENGTH_CONSTRAINT_DRIFT, and UNUSED_SCHEMA_FIELD. Does not execute live requests."""
+        from codegraph.database.schema_drift import detect_schema_drift as impl_detect_drift
+        target = route or handler
+        with indexer.session() as con:
+            return impl_detect_drift(
+                con,
+                indexer.repository,
+                route_or_handler=target,
+                target_table=table,
+                schema_name=schema,
+            )
+
+    def check_api_drift() -> dict[str, Any]:
+        """Detect client-server API contract drift between frontend fetch or axios calls and backend route registrations. Flags orphaned client endpoints (404s), HTTP method mismatches (405s), and cross-language TypeScript-to-backend model drift. Use when validating frontend API calls against backend endpoints before deployment. Does not execute live HTTP requests or validate dynamic URL strings constructed via runtime interpolation."""
+        from codegraph.api_drift import detect_api_contract_drift
+        with indexer.session() as con:
+            return detect_api_contract_drift(con, indexer.repository).as_dict()
+
+    def get_monorepo_packages() -> dict[str, Any]:
+        """Catalog monorepo workspace packages, tools (pnpm, Turborepo, npm/yarn workspaces), entry points, and inter-package dependencies. Use when mapping multi-package repository structure and package boundaries. Does not prove build system execution order or runtime dependency loading."""
+        from codegraph.monorepo import discover_workspace
+        return discover_workspace(indexer.repository).as_dict()
+
     # -----------------------------------------------------------------------
     # Git Intelligence Tools (5 Unified Capabilities)
     # -----------------------------------------------------------------------
@@ -980,8 +1035,12 @@ def create_server(
     def get_change_impact(base: str = "HEAD~1", head: str = "HEAD", max_depth: int = 2, max_results: int = 50) -> dict[str, Any]:
         """Compute deep downstream change impact across callers, callees, framework routes, covering tests, mutating database queries, and monorepo packages. Use when analyzing blast radius and ripple effects of git commits. Does not assume unobserved runtime paths are impossible."""
         from codegraph.change_impact import get_deep_change_impact
+        target_sym = None
+        clean_base = base.strip()
+        if clean_base.startswith("symbol:"):
+            target_sym = clean_base.split("symbol:", 1)[1]
         with indexer.session() as con:
-            return get_deep_change_impact(indexer.repository, con, base=base, head=head, max_depth=max_depth, max_results=max_results).as_dict()
+            return get_deep_change_impact(indexer.repository, con, base=base, head=head, max_depth=max_depth, max_results=max_results, symbol=target_sym).as_dict()
 
     def check_context_freshness(task: str = "", context_packet: dict[str, Any] | None = None) -> dict[str, Any]:
         """Validate whether a previously compiled context packet or task context is still VALID, PARTIALLY_STALE, or STALE. Use when checking if cached context is valid after edits. Does not invalidate context when only unrelated files change."""
@@ -1015,6 +1074,49 @@ def create_server(
         with indexer.session() as con:
             return impl_detect_semantic_conflicts(indexer.repository, base_branch=base_branch, head_branch=head_branch, con=con).as_dict()
 
+    def safe_rename(
+        target: str,
+        new_name: str,
+        dry_run: bool = True,
+        force_uncertain: bool = False,
+    ) -> dict[str, Any]:
+        """Perform a deterministic, syntax-validated, transaction-safe AST rename of a symbol across the repository.
+        Follows the core invariant: DISCOVER -> PLAN -> PREVIEW -> VALIDATE -> COMMIT -> REINDEX -> VERIFY.
+        When dry_run=True, performs zero disk mutation and returns preview diffs, risk assessment, affected tests, and affected routes.
+        When dry_run=False, validates all preconditions and syntax in memory, commits atomically using sibling temp files and os.replace, persists a rollback manifest, and triggers an incremental index update.
+        If risk != LOW (due to UNKNOWN/POSSIBLE/AMBIGUOUS references), the rename is BLOCKED unless force_uncertain=True."""
+        from codegraph.refactor.renamer import execute_safe_rename
+
+        with indexer.session() as con:
+            result = execute_safe_rename(
+                repository=indexer.repository,
+                con=con,
+                target=target,
+                new_name=new_name,
+                dry_run=dry_run,
+                force_uncertain=force_uncertain,
+            )
+            return result.to_dict()
+
+    def rollback_refactor(
+        transaction_id: str,
+    ) -> dict[str, Any]:
+        """Atomically rollback an applied refactoring transaction using its rollback manifest ID.
+        Verifies that files on disk have not been modified externally since the refactor before restoring original contents."""
+        from codegraph.refactor.models import RefactorStatus
+        from codegraph.refactor.transactions import rollback_refactor as do_rollback
+
+        result = do_rollback(
+            repository=indexer.repository,
+            transaction_id=transaction_id,
+        )
+        if result.status == RefactorStatus.ROLLED_BACK:
+            try:
+                indexer.index()
+            except Exception:
+                pass
+        return result.to_dict()
+
     core_tools: dict[str, Any] = {
         "resolve_symbol": resolve_symbol,
         "search_symbols": search_symbols,
@@ -1040,10 +1142,16 @@ def create_server(
         "detect_semantic_conflicts": detect_semantic_conflicts,
     }
 
+    refactor_tools: dict[str, Any] = {
+        "safe_rename": safe_rename,
+        "rollback_refactor": rollback_refactor,
+    }
+
     # Map of all available tools
     all_tools: dict[str, Any] = {
         **core_tools,
         **git_intelligence_tools,
+        **refactor_tools,
         "search_code": search_code,
         "read_file": read_file,
         "find_symbol": find_symbol,
@@ -1087,6 +1195,12 @@ def create_server(
         "ingest_runtime_traces": ingest_runtime_traces,
         "get_runtime_trace": get_runtime_trace,
         "reconcile_static_runtime": reconcile_static_runtime,
+        "get_live_services": get_live_services,
+        "check_db_drift": check_db_drift,
+        "check_route_schema_drift": check_route_schema_drift,
+        "get_distributed_trace": get_distributed_trace,
+        "check_api_drift": check_api_drift,
+        "get_monorepo_packages": get_monorepo_packages,
     }
 
     agent_names = {
@@ -1179,6 +1293,7 @@ def create_server(
 
             get_graph_cache().clear()
             get_parse_cache().clear()
+            indexer.reset_pool()
             return True
         return False
 
@@ -1196,6 +1311,40 @@ def create_server(
 
         app.tool(name=tool_name)(_make_guarded(target_fn))
 
+    # FastMCP Event Loop Offload:
+    # Ensure synchronous tools execute in worker threads so MCP asyncio loop is never blocked
+    orig_call_tool = app._tool_manager.call_tool
+
+    async def _concurrent_call_tool(
+        name: str,
+        arguments: dict[str, Any],
+        context: Any = None,
+        convert_result: bool = False,
+    ) -> Any:
+        tool = app._tool_manager.get_tool(name)
+        if tool is not None and not tool.is_async:
+            def _invoke_in_thread() -> Any:
+                return asyncio.run(
+                    orig_call_tool(
+                        name,
+                        arguments,
+                        context=context,
+                        convert_result=convert_result,
+                    )
+                )
+
+            return await anyio.to_thread.run_sync(_invoke_in_thread)
+
+        return await orig_call_tool(
+            name,
+            arguments,
+            context=context,
+            convert_result=convert_result,
+        )
+
+    app._tool_manager.call_tool = _concurrent_call_tool  # type: ignore[method-assign]
+
+
     # -----------------------------------------------------------------------
     # MCP Resources
     # -----------------------------------------------------------------------
@@ -1208,47 +1357,60 @@ def create_server(
         return json.dumps(get_capability_manifest(), indent=2)
 
     @app.resource("codebase://status")
-    def resource_status() -> str:
+    async def resource_status() -> str:
         """Repository index status, generation, and file counts."""
-        with indexer.session() as con:
-            report = check_freshness(indexer.repository, con)
-            return json.dumps(
-                {
-                    "repository": str(indexer.repository),
-                    "generation": report.index_generation,
-                    "freshness": report.status.value,
-                    "files": con.execute("SELECT count(*) FROM files").fetchone()[0],
-                    "symbols": con.execute("SELECT count(*) FROM symbols").fetchone()[0],
-                },
-                indent=2,
-            )
+        def _get_status() -> str:
+            with indexer.session() as con:
+                report = check_freshness(indexer.repository, con)
+                return json.dumps(
+                    {
+                        "repository": str(indexer.repository),
+                        "generation": report.index_generation,
+                        "freshness": report.status.value,
+                        "files": con.execute("SELECT count(*) FROM files").fetchone()[0],
+                        "symbols": con.execute("SELECT count(*) FROM symbols").fetchone()[0],
+                    },
+                    indent=2,
+                )
+
+        return await anyio.to_thread.run_sync(_get_status)
 
     @app.resource("codebase://architecture")
-    def resource_architecture() -> str:
+    async def resource_architecture() -> str:
         """High-level architectural overview."""
-        with indexer.session() as con:
-            arch = arch_get_architecture(con, indexer.repository)
-            return json.dumps(arch, indent=2)
+        def _get_arch() -> str:
+            with indexer.session() as con:
+                arch = arch_get_architecture(con, indexer.repository)
+                return json.dumps(arch, indent=2)
+
+        return await anyio.to_thread.run_sync(_get_arch)
 
     @app.resource("codebase://modules")
-    def resource_modules() -> str:
+    async def resource_modules() -> str:
         """List of indexed repository module paths."""
-        with indexer.session() as con:
-            rows = con.execute("SELECT path FROM files ORDER BY path LIMIT 500").fetchall()
-            return "\n".join(r[0] for r in rows)
+        def _get_modules() -> str:
+            with indexer.session() as con:
+                rows = con.execute("SELECT path FROM files ORDER BY path LIMIT 500").fetchall()
+                return "\n".join(r[0] for r in rows)
+
+        return await anyio.to_thread.run_sync(_get_modules)
 
     @app.resource("codebase://health")
-    def resource_health() -> str:
+    async def resource_health() -> str:
         """Database health and integrity report."""
-        with indexer.session() as con:
-            health = check_database_health(con)
-            return json.dumps(health, indent=2)
+        def _get_health() -> str:
+            with indexer.session() as con:
+                health = check_database_health(con)
+                return json.dumps(health, indent=2)
+
+        return await anyio.to_thread.run_sync(_get_health)
 
     @app.resource("codebase://resources")
     def resource_resources() -> str:
         """Resource governor state, memory bounds, pressure, and activity mode."""
         return json.dumps(indexer.governor.get_state().as_dict(), indent=2)
 
+
     # -----------------------------------------------------------------------
     # MCP Prompts
     # -----------------------------------------------------------------------

codegraph/models.py

@@ -56,6 +56,13 @@ EdgeType = Literal[
     "EVENT_LISTENER",
     "TASK_HANDLER",
     "COMMAND_HANDLER",
+    "DISPATCHES_TASK",
+    "TRIGGERS_SIGNAL",
+    "HANDLES_SIGNAL",
+    "RENDERS_TEMPLATE",
+    "DISPATCHES_FORWARD",
+    "TOOL_HANDLER",
+    "PIPELINE_STEP",
     "TESTS",
     "TESTS_ROUTE",
     "TESTS_SYMBOL",

codegraph/monorepo.py

@@ -920,3 +920,6 @@ def detect_workspace(
         unresolved_dependencies=unresolved_dependencies,
         ambiguous_packages=ambiguous_packages,
     )
+
+
+discover_workspace = detect_workspace

codegraph/optimizer.py

@@ -41,7 +41,7 @@ _CONFIDENCE_RANK = {
 
 # Hard upper safety limits enforced even when omitted or exceeded
 HARD_MAX_TOKENS = 20_000
-HARD_MAX_FILES = 30
+HARD_MAX_FILES = 40
 HARD_MAX_LINES = 1_500
 HARD_MAX_SYMBOLS = 50
 HARD_MAX_RELATIONSHIPS = 60
@@ -54,7 +54,7 @@ class ContextBudgetSpec:
     max_tokens: int = 20_000
     max_symbols: int = 25
     max_relationships: int = 30
-    max_files: int = 15
+    max_files: int = 25
     max_lines: int = 500
     max_depth: int = 3
     max_package_depth: int = 2
@@ -94,7 +94,7 @@ class ContextBudget:
     tool_calls: int = 1
     max_symbols: int = 25
     max_relationships: int = 30
-    max_files: int = 15
+    max_files: int = 25
     max_lines: int = 500
     max_depth: int = 3
     max_package_depth: int = 2
@@ -374,6 +374,17 @@ def compute_item_utility(
     dim_unseen = selected_dimensions is not None and dim not in selected_dimensions and dim != "GENERAL"
     coverage_factor = 1.3 if (layer_unseen or dim_unseen) else 1.0
 
+    # Priority boost for task-critical items over tangential ones
+    priority_dim_boost = 0.0
+    if dim == "TARGET" or item.relevance_score >= 0.80:
+        priority_dim_boost = 0.20
+    elif dim in ("ROUTE", "CALLER"):
+        priority_dim_boost = 0.12
+    elif dim == "CALLEE":
+        priority_dim_boost = 0.08
+    elif dim in ("TEST", "GIT", "PACKAGE", "GENERAL") and item.relevance_score < 0.50:
+        priority_dim_boost = -0.08
+
     # Redundancy penalty: heavily discount items sharing duplicate keys with already selected items
     redundancy_penalty = 0.5 if item.duplicate_key in selected_duplicate_keys else 0.0
 
@@ -384,6 +395,7 @@ def compute_item_utility(
         + (fresh_factor * 0.15)
         + (epistemic_factor * 0.10)
         + pkg_adj
+        + priority_dim_boost
     ) * coverage_factor
 
     final_score = max(0.01, utility - redundancy_penalty - conf_penalty - art_penalty - dist_penalty)
@@ -572,7 +584,7 @@ def optimize_context_budget(
     """Deterministically select the highest-utility, coverage-preserving subset of candidates."""
     raw_max_symbols = budget_spec.max_symbols if budget_spec else 25
     raw_max_relationships = budget_spec.max_relationships if budget_spec else 30
-    raw_max_files = budget_spec.max_files if budget_spec else 15
+    raw_max_files = budget_spec.max_files if budget_spec else 25
     raw_max_lines = budget_spec.max_lines if budget_spec else 500
     max_depth = budget_spec.max_depth if budget_spec else 3
     max_package_depth = budget_spec.max_package_depth if budget_spec else 2
@@ -767,7 +779,32 @@ def optimize_context_budget(
                     )
                     break
 
-    # Pass 1b: Architectural Layer Coverage pass — ensure distinct layers
+    # Pass 1b: Task-Critical Candidates Priority pass — ensure all direct targets,
+    # routes, and direct callers/callees are admitted into the file budget before
+    # tangential layer coverage files consume file slots.
+    for item in sorted_candidates:
+        if item in selected or _is_excluded(item, task_spec):
+            continue
+        if item.duplicate_key in selected_duplicate_keys:
+            continue
+        dim = item.infer_dimension()
+        is_task_critical = (
+            dim in ("TARGET", "ROUTE", "CALLER")
+            or item.relevance_score >= 0.70
+            or (dim == "CALLEE" and item.relevance_score >= 0.50)
+        )
+        if is_task_critical:
+            if _can_fit(item) or (dim == "TARGET" and len(selected) == 0 and _trim_to_fit(item)):
+                _accept(
+                    item,
+                    is_coverage_fill=False,
+                    why=[
+                        f"Task-critical priority candidate: dimension '{dim}'",
+                        f"Relevance: {item.relevance_score:.2f}, Evidence: {item.evidence_quality:.2f}",
+                    ],
+                )
+
+    # Pass 1c: Architectural Layer Coverage pass — ensure distinct layers
     # (e.g. ENTRYPOINT, SERVICE, DATA, TEST, GIT) get represented if candidates exist
     for item in sorted_candidates:
         if item in selected or _is_excluded(item, task_spec):

codegraph/process_lifecycle.py

@@ -541,16 +541,28 @@ def is_parent_alive(
 ) -> bool:
     """Return True if the parent process `parent_pid` is still alive and owns this child."""
     if parent_pid <= 1:
-        return False
+        # PID 0 and 1 represent init / systemd / launchd / container root; always considered alive
+        return True
 
-    if sys.platform != "win32":
-        actual_ppid = current_ppid if current_ppid is not None else os.getppid()
-        if actual_ppid != parent_pid:
-            # Reparented to PID 1 / launchd / systemd --user
-            return False
+    # 1. Direct probe whether parent PID exists via os.kill(pid, 0)
+    try:
+        os.kill(parent_pid, 0)
+    except ProcessLookupError:
+        # ESRCH: Process does not exist; parent is definitely dead
+        return False
+    except PermissionError:
+        # EPERM: Process exists, but caller lacks permissions to signal it (e.g. sandbox/different user)
+        return True
+    except OSError:
+        # Other OS error: safe fallback is alive
+        return True
 
     live = get_live_process_info(parent_pid)
-    if live is None or live.is_zombie:
+    if live is None:
+        # If OS inspection was restricted (e.g. sandbox blocking proc_pidinfo),
+        # but os.kill succeeded above, the process is alive.
+        return True
+    if live.is_zombie:
         return False
 
     if parent_create_token and live.create_token and live.create_token != parent_create_token:
@@ -964,16 +976,22 @@ class MCPLifecycleController:
 
     def _watchdog_loop(self) -> None:
         """Low-overhead event-backed watchdog detecting parent termination or closed stdin."""
+        disable_parent_watchdog = (
+            os.environ.get("CODEGRAPH_DISABLE_PARENT_WATCHDOG", "").strip().lower()
+            in ("1", "true", "yes")
+            or self.record.parent_pid <= 1
+        )
         while not self._stop_event.wait(timeout=self.poll_interval_sec):
             if _is_stream_closed_or_eof(sys.stdin):
                 self.shutdown("stdin_closed")
                 return
-            if not is_parent_alive(
-                self.record.parent_pid,
-                self.record.parent_create_token,
-            ):
-                self.shutdown("parent_process_terminated")
-                return
+            if not disable_parent_watchdog:
+                if not is_parent_alive(
+                    self.record.parent_pid,
+                    self.record.parent_create_token,
+                ):
+                    self.shutdown("parent_process_terminated")
+                    return
 
     def _atexit_cleanup(self) -> None:
         self.shutdown("atexit")

codegraph/refactor/__init__.py

@@ -0,0 +1,36 @@
+"""Deterministic, syntax-validated, transaction-safe refactoring engine for CodeGraph MCP."""
+from __future__ import annotations
+
+from codegraph.refactor.models import (
+    RefactorPlan,
+    RefactorResult,
+    RefactorRisk,
+    RefactorStatus,
+    TokenReplacementSpan,
+)
+from codegraph.refactor.renamer import (
+    execute_safe_rename,
+    plan_safe_rename,
+    preview_safe_rename,
+)
+from codegraph.refactor.transactions import (
+    RefactorLock,
+    RefactorLockError,
+    commit_refactor_transaction,
+    rollback_refactor,
+)
+
+__all__ = [
+    "RefactorLock",
+    "RefactorLockError",
+    "RefactorPlan",
+    "RefactorResult",
+    "RefactorRisk",
+    "RefactorStatus",
+    "TokenReplacementSpan",
+    "commit_refactor_transaction",
+    "execute_safe_rename",
+    "plan_safe_rename",
+    "preview_safe_rename",
+    "rollback_refactor",
+]

codegraph/refactor/models.py

@@ -0,0 +1,114 @@
+"""Models and data structures for deterministic, syntax-validated, transaction-safe refactoring."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class RefactorStatus(StrEnum):
+    """Execution status of a refactoring plan or transaction."""
+
+    READY = "READY"
+    BLOCKED = "BLOCKED"
+    APPLIED = "APPLIED"
+    ROLLED_BACK = "ROLLED_BACK"
+    ERROR = "ERROR"
+
+
+class RefactorRisk(StrEnum):
+    """Assessed risk of an AST refactoring operation."""
+
+    LOW = "LOW"        # All affected relationships are FACT / deterministically verified.
+    MEDIUM = "MEDIUM"  # POSSIBLE relationships exist but scope is bounded.
+    HIGH = "HIGH"      # UNKNOWN / AMBIGUOUS / CONFLICT relationships could make rename incomplete.
+
+
+@dataclass(frozen=True)
+class TokenReplacementSpan:
+    """Exact byte/token coordinates for an AST-grounded replacement."""
+
+    path: str
+    start_line: int
+    start_col: int
+    end_line: int
+    end_col: int
+    old_token: str
+    new_token: str
+    evidence: str
+    symbol_id: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class RefactorPlan:
+    """Deterministic refactoring plan before in-memory preview or commit."""
+
+    transaction_id: str
+    target_symbol: str
+    new_name: str
+    files: list[str] = field(default_factory=list)
+    spans: list[TokenReplacementSpan] = field(default_factory=list)
+    risk: RefactorRisk = RefactorRisk.LOW
+    uncertainty_reasons: list[str] = field(default_factory=list)
+    affected_tests: list[str] = field(default_factory=list)
+    affected_routes: list[str] = field(default_factory=list)
+    affected_db_relationships: list[str] = field(default_factory=list)
+    original_file_hashes: dict[str, str] = field(default_factory=dict)
+    original_file_sizes: dict[str, int] = field(default_factory=dict)
+    original_file_mtimes: dict[str, float] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "transaction_id": self.transaction_id,
+            "target_symbol": self.target_symbol,
+            "new_name": self.new_name,
+            "files": sorted(self.files),
+            "spans": [s.to_dict() for s in sorted(self.spans, key=lambda x: (x.path, x.start_line, x.start_col))],
+            "risk": str(self.risk),
+            "uncertainty_reasons": sorted(self.uncertainty_reasons),
+            "affected_tests": sorted(self.affected_tests),
+            "affected_routes": sorted(self.affected_routes),
+            "affected_db_relationships": sorted(self.affected_db_relationships),
+            "original_file_hashes": dict(sorted(self.original_file_hashes.items())),
+        }
+
+
+@dataclass
+class RefactorResult:
+    """Complete result of a refactor preview, apply, or rollback."""
+
+    status: RefactorStatus
+    target_symbol: str
+    new_name: str
+    risk: RefactorRisk
+    uncertainty_reasons: list[str] = field(default_factory=list)
+    files_changed: int = 0
+    symbols_changed: int = 0
+    spans_count: int = 0
+    tests_affected: list[str] = field(default_factory=list)
+    routes_affected: list[str] = field(default_factory=list)
+    db_affected: list[str] = field(default_factory=list)
+    rollback_id: str | None = None
+    diffs: dict[str, str] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": str(self.status),
+            "target_symbol": self.target_symbol,
+            "new_name": self.new_name,
+            "risk": str(self.risk),
+            "uncertainty_reasons": sorted(self.uncertainty_reasons),
+            "files_changed": self.files_changed,
+            "symbols_changed": self.symbols_changed,
+            "spans_count": self.spans_count,
+            "tests_affected": sorted(self.tests_affected),
+            "routes_affected": sorted(self.routes_affected),
+            "db_affected": sorted(self.db_affected),
+            "rollback_id": self.rollback_id,
+            "diffs": dict(sorted(self.diffs.items())),
+            "errors": sorted(self.errors),
+        }