python-delphi-lsp 3.6.0__cp310-abi3-win_amd64.whl

delphi_lsp/agent_relations.py

@@ -0,0 +1,1881 @@
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePath, PurePosixPath, PureWindowsPath
+from typing import TypeVar
+
+from .agent_protocol import AgentProtocolError
+from .agent_workspace import AgentWorkspace
+from .consts import AttributeName, SyntaxNodeType
+from .nodes import SyntaxNode
+from .parser import DelphiParser
+from .parser_backend import ParserMode
+from .preprocessor import PreprocessedSource
+from .project_config import workspace_include_loader
+from .project_indexer import ProjectIndexer, ProjectProblem
+from .semantic import (
+    GenericInstanceTypeRef,
+    NamedTypeRef,
+    ProcTypeRef,
+    ReferenceKind,
+    Scope,
+    ScopeKind,
+    SourceRange,
+    Symbol,
+    SymbolIndex,
+    SymbolKind,
+    TypeRef,
+)
+from .source_reader import read_source_text
+from .workspace import WorkspaceSemanticResult, build_workspace_semantics_from_roots
+
+_ROUTINE_KINDS = frozenset(
+    {
+        SymbolKind.METHOD.value,
+        SymbolKind.FUNCTION.value,
+        SymbolKind.PROCEDURE.value,
+        SymbolKind.CONSTRUCTOR.value,
+        SymbolKind.DESTRUCTOR.value,
+    }
+)
+_TYPE_KINDS = frozenset(
+    {
+        SymbolKind.CLASS.value,
+        SymbolKind.RECORD.value,
+        SymbolKind.INTERFACE.value,
+    }
+)
+_GroupKey = tuple[str, str, str, str]
+_AdjacencyValue = TypeVar("_AdjacencyValue")
+_MAX_RELATION_PROBLEM_SUMMARIES = 50
+_MAX_REFERENCE_CANDIDATE_FILES = 64
+_REFERENCE_SEMANTIC_BATCH_SIZE = 8
+
+
+@dataclass(frozen=True)
+class RelationTarget:
+    target_id: str
+    source_path: str
+    path: str
+    unit_id: str
+    unit_name: str
+    name: str
+    qualified_name: str
+    kind: str
+    signature: str
+    line: int
+    column: int
+    card: Mapping[str, object]
+    visibility: str = ""
+    type_name: str = ""
+    owner: str = ""
+
+
+@dataclass(frozen=True)
+class _ReferenceRecord:
+    target_group: _GroupKey
+    owner_group: _GroupKey | None
+    kind: ReferenceKind
+    evidence: Mapping[str, object]
+    referencing_symbol: Mapping[str, object] | None
+
+
+@dataclass(frozen=True)
+class _TypeEdge:
+    source_group: _GroupKey
+    target_group: _GroupKey
+    evidence: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class _UnitEdge:
+    source_group: _GroupKey
+    target_group: _GroupKey
+    evidence: Mapping[str, object]
+
+
+class ProjectRelationIndex:
+    """Lazy deep semantic graph for one selected project revision."""
+
+    def __init__(
+        self,
+        workspace: AgentWorkspace,
+        project_id: str,
+        revision: str,
+        targets: Sequence[RelationTarget],
+        *,
+        targets_complete: bool = True,
+        unit_targets_complete: bool = True,
+    ) -> None:
+        self.project_id = project_id
+        self.revision = revision
+        self.targets_complete = targets_complete
+        self.unit_targets_complete = unit_targets_complete
+        self._workspace = workspace
+        self._root = workspace.root
+        self._unit_name_counts: dict[str, int] = {}
+        for unit in workspace.units:
+            normalized_name = _normalized(unit.name)
+            self._unit_name_counts[normalized_name] = (
+                self._unit_name_counts.get(normalized_name, 0) + 1
+            )
+        self._targets = {target.target_id: target for target in targets}
+        duplicate_target_units = {
+            _normalized(target.unit_name)
+            for target in targets
+            if self._unit_name_counts.get(_normalized(target.unit_name), 0) > 1
+        }
+        self._project_memberships = (
+            _workspace_project_memberships(workspace)
+            if duplicate_target_units
+            else ()
+        )
+        self._target_groups = {
+            target.target_id: _target_group(target)
+            for target in targets
+        }
+        self._groups: dict[_GroupKey, list[RelationTarget]] = {}
+        for target in targets:
+            self._groups.setdefault(_target_group(target), []).append(target)
+        for group in self._groups.values():
+            group.sort(key=_target_sort_key)
+
+        self._path_display: dict[str, str] = {}
+        self._exact_targets: dict[tuple[str, int, int, str, str], list[RelationTarget]] = {}
+        self._position_targets: dict[tuple[str, int, int, str], list[RelationTarget]] = {}
+        self._line_targets: dict[tuple[str, int, str, str], list[RelationTarget]] = {}
+        self._identity_targets: dict[tuple[str, str, str], list[RelationTarget]] = {}
+        for target in targets:
+            path_key = _path_key(target.source_path)
+            self._path_display.setdefault(path_key, target.path)
+            exact = (path_key, target.line, target.column, target.kind, _normalized(target.name))
+            self._exact_targets.setdefault(exact, []).append(target)
+            position = (path_key, target.line, target.column, target.kind)
+            self._position_targets.setdefault(position, []).append(target)
+            line = (path_key, target.line, target.kind, _normalized(target.name))
+            self._line_targets.setdefault(line, []).append(target)
+            identity = (
+                _normalized(target.qualified_name),
+                target.kind,
+                _target_signature_identity(target),
+            )
+            self._identity_targets.setdefault(identity, []).append(target)
+
+        self._roots: dict[str, SyntaxNode] = {}
+        self._problems: list[dict[str, object]] = []
+        self._semantics: WorkspaceSemanticResult | None = None
+        self._semantic_unit_paths: dict[int, str] = {}
+        self._symbol_targets: dict[int, RelationTarget | None] = {}
+        self._references: list[_ReferenceRecord] = []
+        self._unit_edges: list[_UnitEdge] = []
+        self._inherits: list[_TypeEdge] = []
+        self._implements: list[_TypeEdge] = []
+        self._unresolved_references = 0
+        self._ambiguous_references = 0
+        self._deep_graph_ready = False
+        self._reference_groups_loaded: set[_GroupKey] = set()
+        self._reference_groups_complete: dict[_GroupKey, bool] = {}
+        self._unit_sources_loaded: set[_GroupKey] = set()
+        self._index_graph()
+
+    @property
+    def estimated_cache_bytes(self) -> int:
+        adjacency_maps = (
+            self._references_by_target,
+            self._calls_by_target,
+            self._calls_by_owner,
+            self._unit_edges_by_source,
+            self._unit_edges_by_target,
+            self._inherits_by_source,
+            self._implements_by_source,
+        )
+        adjacency_groups = sum(len(groups) for groups in adjacency_maps)
+        adjacency_slots = sum(
+            len(values)
+            for groups in adjacency_maps
+            for values in groups.values()
+        )
+        edge_bytes = (
+            len(self._references) * 384
+            + len(self._unit_edges) * 320
+            + (len(self._inherits) + len(self._implements)) * 288
+        )
+        return (
+            4096
+            + len(self._targets) * 512
+            + edge_bytes
+            + adjacency_groups * 192
+            + adjacency_slots * 8
+            + len(self._problems) * 512
+        )
+
+    def has_target(self, target_id: str) -> bool:
+        return target_id in self._targets
+
+    def trace(
+        self,
+        target_id: str,
+        relation: str,
+        *,
+        cancel_check: Callable[[], None] | None = None,
+        max_relations: int = 12,
+    ) -> list[dict[str, object]]:
+        target = self._targets.get(target_id)
+        if target is None:
+            raise AgentProtocolError("target_not_found", f"Target not found: {target_id}.")
+        self._validate_applicability(target, relation)
+        group = self._target_groups[target_id]
+        active_project = self._workspace.active_project
+        lightweight_units = (
+            active_project is not None
+            and active_project.kind == "workspace"
+        )
+        if relation == "references" and (
+            len(self._workspace.units) >= 256
+            or (
+                target.kind != SymbolKind.UNIT.value
+                and self._unit_name_counts.get(
+                    _normalized(target.unit_name),
+                    0,
+                ) > 1
+            )
+        ):
+            self._ensure_reference_graph(
+                group,
+                target,
+                cancel_check=cancel_check,
+                max_relations=max_relations,
+            )
+        elif relation == "uses" and lightweight_units:
+            self._ensure_unit_graph((group,))
+        elif relation == "used_by" and lightweight_units:
+            self._ensure_unit_graph(
+                tuple(
+                    candidate_group
+                    for candidate_group, candidates in self._groups.items()
+                    if candidates and candidates[0].kind == SymbolKind.UNIT.value
+                )
+            )
+        else:
+            self._ensure_deep_graph(cancel_check=cancel_check)
+
+        if relation == "references":
+            items = [
+                self._relation_item(
+                    relation,
+                    record.owner_group or record.target_group,
+                    record.evidence,
+                    referencing_symbol=record.referencing_symbol,
+                )
+                for record in self._references_by_target.get(group, ())
+            ]
+            if target.kind == SymbolKind.UNIT.value:
+                items.extend(
+                    self._relation_item(relation, edge.source_group, edge.evidence)
+                    for edge in self._unit_edges_by_target.get(group, ())
+                )
+        elif relation == "callers":
+            items = [
+                self._relation_item(relation, record.owner_group, record.evidence)
+                for record in self._calls_by_target.get(group, ())
+                if record.owner_group is not None
+            ]
+        elif relation == "callees":
+            items = [
+                self._relation_item(relation, record.target_group, record.evidence)
+                for record in self._calls_by_owner.get(group, ())
+            ]
+        elif relation == "uses":
+            items = [
+                self._relation_item(relation, edge.target_group, edge.evidence)
+                for edge in self._unit_edges_by_source.get(group, ())
+            ]
+        elif relation == "used_by":
+            items = [
+                self._relation_item(relation, edge.source_group, edge.evidence)
+                for edge in self._unit_edges_by_target.get(group, ())
+            ]
+        elif relation == "inherits":
+            items = [
+                self._relation_item(relation, edge.target_group, edge.evidence)
+                for edge in self._inherits_by_source.get(group, ())
+            ]
+        elif relation == "implements":
+            items = [
+                self._relation_item(relation, edge.target_group, edge.evidence)
+                for edge in self._implements_by_source.get(group, ())
+            ]
+        else:  # AgentRequest validation normally rejects this first.
+            raise AgentProtocolError("invalid_relation", f"Unsupported relation value: {relation!r}.")
+
+        compact_items = [item for item in items if item is not None]
+        relations = _dedupe_mappings(compact_items)
+        relations.sort(key=_relation_sort_key)
+        problem_summaries, problem_count = _summarize_relation_problems(
+            self._problems,
+            limit=_MAX_RELATION_PROBLEM_SUMMARIES,
+        )
+        result = list(relations)
+        result.append(
+            self._metadata(
+                relation,
+                problem_summaries=problem_summaries,
+                problem_count=problem_count,
+                scan_complete=(
+                    self._deep_graph_ready
+                    or self._reference_groups_complete.get(group, False)
+                    if relation == "references"
+                    else True
+                ),
+            )
+        )
+        return result
+
+    def _ensure_unit_graph(self, groups: Sequence[_GroupKey]) -> None:
+        if self._deep_graph_ready:
+            return
+        for group in groups:
+            if group in self._unit_sources_loaded:
+                continue
+            self._unit_sources_loaded.add(group)
+            candidates = self._groups.get(group)
+            if not candidates:
+                continue
+            source = candidates[0]
+            try:
+                text = read_source_text(Path(source.source_path))
+                parsed = DelphiParser(
+                    include_paths=self._workspace.include_paths,
+                    defines=self._workspace.defines,
+                    include_loader=workspace_include_loader(
+                        self._workspace.project_config,
+                        self._workspace.include_paths,
+                    ),
+                    mode=(
+                        ParserMode.TOLERANT
+                        if len(self._workspace.units) >= 256
+                        else ParserMode.STRICT
+                    ),
+                ).parse(
+                    text,
+                    source.source_path,
+                    build_semantic=False,
+                )
+            except Exception as error:
+                self._problems.append(
+                    {
+                        "item_type": "relation_problem",
+                        "kind": "cant_parse_file",
+                        "message": _safe_problem_message(
+                            f"{type(error).__name__}: {error}",
+                            self._root,
+                            (
+                                source.source_path,
+                                getattr(error, "filename", None),
+                                getattr(error, "filename2", None),
+                            ),
+                        ),
+                        "path": source.path,
+                    }
+                )
+                continue
+            if parsed.problems:
+                first = parsed.problems[0]
+                self._problems.append(
+                    {
+                        "item_type": "relation_problem",
+                        "kind": "partial_parse",
+                        "message": (
+                            f"Partial DelphiAST parse at {first.line}:{first.column}: "
+                            f"{first.message}"
+                        ),
+                        "path": source.path,
+                    }
+                )
+            self._add_lightweight_unit_edges(
+                source,
+                parsed.root,
+                parsed.preprocessed,
+            )
+        self._index_graph()
+        self._problems = _dedupe_mappings(self._problems)
+
+    def _add_lightweight_unit_edges(
+        self,
+        source: RelationTarget,
+        root: SyntaxNode,
+        preprocessed: PreprocessedSource,
+    ) -> None:
+        source_group = _target_group(source)
+        unit_targets: dict[str, list[RelationTarget]] = {}
+        for target in self._targets.values():
+            if target.kind != SymbolKind.UNIT.value:
+                continue
+            unit_targets.setdefault(
+                _normalized(target.unit_name or target.name),
+                [],
+            ).append(target)
+        pending = [root]
+        while pending:
+            node = pending.pop()
+            pending.extend(reversed(node.child_nodes))
+            if node.typ not in {
+                SyntaxNodeType.ntUses,
+                SyntaxNodeType.ntContains,
+                SyntaxNodeType.ntRequires,
+            }:
+                continue
+            for child in node.child_nodes:
+                if child.typ != SyntaxNodeType.ntUnit:
+                    continue
+                name = child.get_attribute(AttributeName.anName).strip()
+                candidates = unit_targets.get(_normalized(name), ())
+                resolved_target = self._lightweight_unit_target(source, candidates)
+                if resolved_target is None:
+                    self._unresolved_references += 1
+                    self._problems.append(
+                        {
+                            "item_type": "relation_problem",
+                            "kind": "unresolved_unit",
+                            "message": f"Unit not found: {name}",
+                            "path": source.path,
+                            "line": child.line,
+                            "column": child.col,
+                        }
+                    )
+                    continue
+                mapped_file, mapped_line, mapped_column = (
+                    preprocessed.map_position(child.line, child.col)
+                )
+                evidence = {
+                    "path": (
+                        self._display_path(mapped_file)
+                        if mapped_file and mapped_line > 0
+                        else source.path
+                    ),
+                    "line": mapped_line if mapped_line > 0 else child.line,
+                    "column": (
+                        mapped_column if mapped_column > 0 else child.col
+                    ),
+                    "kind": (
+                        "contains"
+                        if node.typ == SyntaxNodeType.ntContains
+                        else "uses"
+                    ),
+                }
+                self._unit_edges.append(
+                    _UnitEdge(
+                        source_group=source_group,
+                        target_group=_target_group(resolved_target),
+                        evidence=evidence,
+                    )
+                )
+
+    def _lightweight_unit_target(
+        self,
+        source: RelationTarget,
+        candidates: Sequence[RelationTarget],
+    ) -> RelationTarget | None:
+        if len(candidates) == 1:
+            return candidates[0]
+        source_path = _path_key(source.source_path)
+        local = [
+            candidate
+            for candidate in candidates
+            if any(
+                source_path in membership
+                and _path_key(candidate.source_path) in membership
+                for membership in self._project_memberships
+            )
+        ]
+        local_groups = {_target_group(candidate) for candidate in local}
+        if len(local_groups) == 1:
+            return min(local, key=_target_sort_key)
+        source_parent = _path_key(Path(source.source_path).parent)
+        same_directory = [
+            candidate
+            for candidate in candidates
+            if _path_key(Path(candidate.source_path).parent) == source_parent
+        ]
+        same_directory_groups = {
+            _target_group(candidate) for candidate in same_directory
+        }
+        if len(same_directory_groups) == 1:
+            return min(same_directory, key=_target_sort_key)
+        return None
+
+    def _ensure_reference_graph(
+        self,
+        group: _GroupKey,
+        target: RelationTarget,
+        *,
+        cancel_check: Callable[[], None] | None,
+        max_relations: int,
+    ) -> None:
+        if self._deep_graph_ready or group in self._reference_groups_loaded:
+            return
+        scan_complete = self._scan_reference_sources(
+            group,
+            target,
+            cancel_check=cancel_check,
+            max_relations=max_relations,
+        )
+        self._reference_groups_loaded.add(group)
+        self._reference_groups_complete[group] = scan_complete
+        self._index_graph()
+        self._problems = _dedupe_mappings(self._problems)
+
+    def _scan_reference_sources(
+        self,
+        group: _GroupKey,
+        target: RelationTarget,
+        *,
+        cancel_check: Callable[[], None] | None,
+        max_relations: int,
+    ) -> bool:
+        parser = DelphiParser(
+            include_paths=self._workspace.include_paths,
+            defines=self._workspace.defines,
+            include_loader=workspace_include_loader(
+                self._workspace.project_config,
+                self._workspace.include_paths,
+            ),
+            mode=(
+                ParserMode.TOLERANT
+                if len(self._workspace.units) >= 256
+                else ParserMode.STRICT
+            ),
+            legacy_fallback_max_chars=0,
+        )
+        target_path = Path(target.source_path).expanduser().resolve()
+        bounded = len(self._workspace.units) >= 256
+
+        def relation_budget_reached() -> bool:
+            return (
+                bounded
+                and len(self._references_by_target.get(group, ()))
+                >= max_relations
+            )
+
+        target_parse_path = target_path
+        target_parsed = None
+        target_is_unit = False
+        owner_candidates: list[Path] = []
+        for unit in self._workspace.units:
+            source_path = Path(unit.path)
+            if not source_path.is_absolute():
+                source_path = self._workspace.root / source_path
+            source_path = source_path.expanduser().resolve()
+            if source_path == target_path:
+                target_is_unit = True
+                break
+            if _normalized(unit.name) == _normalized(target.unit_name):
+                owner_candidates.append(source_path)
+        if not target_is_unit:
+            target_path_key = _path_key(target_path)
+            for owner_path in owner_candidates:
+                try:
+                    owner_text = read_source_text(owner_path)
+                    owner_parsed = parser.parse(
+                        owner_text,
+                        str(owner_path),
+                        build_semantic=False,
+                    )
+                except Exception as error:  # noqa: BLE001
+                    self._add_load_problem(owner_path, error)
+                    continue
+                if any(
+                    _path_key(entry.file_name) == target_path_key
+                    for entry in owner_parsed.preprocessed.source_map
+                ):
+                    target_parse_path = owner_path
+                    target_parsed = owner_parsed
+                    break
+        if target_parsed is None:
+            try:
+                target_text = read_source_text(target_path)
+                target_parsed = parser.parse(
+                    target_text,
+                    str(target_path),
+                    build_semantic=False,
+                )
+            except Exception as error:  # noqa: BLE001
+                self._add_load_problem(target_path, error)
+                return True
+
+        def add_semantics(
+            candidates: Sequence[tuple[Path, SyntaxNode, PreprocessedSource]],
+        ) -> None:
+            roots = {str(target_parse_path): target_parsed.root}
+            sources = {
+                str(target_parse_path): target_parsed.preprocessed,
+            }
+            for source_path, root, preprocessed in candidates:
+                roots[str(source_path)] = root
+                sources[str(source_path)] = preprocessed
+            semantics = build_workspace_semantics_from_roots(
+                roots,
+                preprocessed_sources=sources,
+            )
+            self._semantics = semantics
+            self._roots = roots
+            # Semantic symbols belong to this short-lived candidate batch.
+            # Object ids may be reused after the previous batch is released.
+            self._symbol_targets.clear()
+            self._build_graph(
+                semantics,
+                cancel_check=cancel_check,
+            )
+            self._add_semantic_problems(semantics)
+            self._index_graph()
+
+        needle = target.name.casefold()
+        unit_needle = target.unit_name.casefold()
+        legacy_candidates_parsed = 0
+        exact_extras_parsed = 0
+        scan_complete = True
+        candidate_batch: list[tuple[Path, SyntaxNode, PreprocessedSource]] = []
+        semantics_built = False
+
+        def flush_candidates() -> bool:
+            nonlocal semantics_built
+            add_semantics(candidate_batch)
+            candidate_batch.clear()
+            semantics_built = True
+            return relation_budget_reached()
+
+        for unit in self._workspace.units:
+            if cancel_check is not None:
+                cancel_check()
+            source_path = Path(unit.path)
+            if not source_path.is_absolute():
+                source_path = self._workspace.root / source_path
+            source_path = source_path.expanduser().resolve()
+            if source_path == target_path:
+                continue
+            if _normalized(unit.name) == _normalized(target.unit_name):
+                continue
+            try:
+                text = read_source_text(source_path)
+            except Exception as error:  # noqa: BLE001
+                self._add_load_problem(source_path, error)
+                continue
+            folded_text = text.casefold()
+            if needle not in folded_text or unit_needle not in folded_text:
+                continue
+            legacy_limit_reached = (
+                legacy_candidates_parsed >= _MAX_REFERENCE_CANDIDATE_FILES
+            )
+            if legacy_limit_reached:
+                scan_complete = False
+            exact_candidate = _text_contains_reference_token(
+                text,
+                needle,
+            ) and _text_contains_reference_token(text, unit_needle)
+            if legacy_limit_reached and (
+                not exact_candidate
+                or exact_extras_parsed >= _MAX_REFERENCE_CANDIDATE_FILES
+            ):
+                continue
+            if cancel_check is not None:
+                cancel_check()
+            try:
+                parsed = parser.parse(
+                    text,
+                    str(source_path),
+                    build_semantic=False,
+                )
+            except Exception as error:  # noqa: BLE001
+                self._add_load_problem(source_path, error)
+                continue
+            if legacy_limit_reached:
+                exact_extras_parsed += 1
+            else:
+                legacy_candidates_parsed += 1
+            if cancel_check is not None:
+                cancel_check()
+            candidate_batch.append(
+                (source_path, parsed.root, parsed.preprocessed)
+            )
+            if (
+                len(candidate_batch) >= _REFERENCE_SEMANTIC_BATCH_SIZE
+                and flush_candidates()
+            ):
+                return False
+        budget_reached = (
+            (candidate_batch or not semantics_built)
+            and flush_candidates()
+        )
+        return scan_complete and not budget_reached
+
+    def _add_load_problem(
+        self,
+        source_path: Path,
+        error: Exception,
+    ) -> None:
+        self._problems.append(
+            {
+                "item_type": "relation_problem",
+                "kind": "cant_parse_file",
+                "message": _safe_problem_message(
+                    f"{type(error).__name__}: {error}",
+                    self._root,
+                    (
+                        source_path,
+                        getattr(error, "filename", None),
+                        getattr(error, "filename2", None),
+                    ),
+                ),
+                "path": _display_project_path(
+                    source_path,
+                    self._root,
+                ),
+            }
+        )
+
+    def _ensure_deep_graph(
+        self,
+        *,
+        cancel_check: Callable[[], None] | None = None,
+    ) -> None:
+        if self._deep_graph_ready:
+            return
+        if cancel_check is None:
+            roots, preprocessed_sources, load_problems = _load_project_roots(
+                self._workspace,
+            )
+        else:
+            roots, preprocessed_sources, load_problems = _load_project_roots(
+                self._workspace,
+                cancel_check=cancel_check,
+            )
+        self._roots = roots
+        self._problems = list(load_problems)
+        self._semantics = (
+            build_workspace_semantics_from_roots(
+                roots,
+                preprocessed_sources=preprocessed_sources,
+            )
+            if roots
+            else None
+        )
+        self._symbol_targets.clear()
+        self._references.clear()
+        self._unit_edges.clear()
+        self._inherits.clear()
+        self._implements.clear()
+        self._unresolved_references = 0
+        self._ambiguous_references = 0
+        if self._semantics is not None:
+            self._build_graph(
+                self._semantics,
+                cancel_check=cancel_check,
+            )
+            self._add_contains_edges(self._semantics)
+            self._add_semantic_problems(self._semantics)
+        self._deep_graph_ready = True
+        self._index_graph()
+        self._problems = _dedupe_mappings(self._problems)
+
+    def _index_graph(self) -> None:
+        references_by_target: dict[_GroupKey, list[_ReferenceRecord]] = {}
+        calls_by_target: dict[_GroupKey, list[_ReferenceRecord]] = {}
+        calls_by_owner: dict[_GroupKey, list[_ReferenceRecord]] = {}
+        for record in self._references:
+            references_by_target.setdefault(record.target_group, []).append(record)
+            if record.kind != ReferenceKind.CALL:
+                continue
+            calls_by_target.setdefault(record.target_group, []).append(record)
+            if record.owner_group is not None:
+                calls_by_owner.setdefault(record.owner_group, []).append(record)
+        self._references_by_target = _freeze_adjacency(references_by_target)
+        self._calls_by_target = _freeze_adjacency(calls_by_target)
+        self._calls_by_owner = _freeze_adjacency(calls_by_owner)
+
+        unit_edges_by_source: dict[_GroupKey, list[_UnitEdge]] = {}
+        unit_edges_by_target: dict[_GroupKey, list[_UnitEdge]] = {}
+        for edge in self._unit_edges:
+            unit_edges_by_source.setdefault(edge.source_group, []).append(edge)
+            unit_edges_by_target.setdefault(edge.target_group, []).append(edge)
+        self._unit_edges_by_source = _freeze_adjacency(unit_edges_by_source)
+        self._unit_edges_by_target = _freeze_adjacency(unit_edges_by_target)
+
+        inherits_by_source: dict[_GroupKey, list[_TypeEdge]] = {}
+        for edge in self._inherits:
+            inherits_by_source.setdefault(edge.source_group, []).append(edge)
+        self._inherits_by_source = _freeze_adjacency(inherits_by_source)
+
+        implements_by_source: dict[_GroupKey, list[_TypeEdge]] = {}
+        for edge in self._implements:
+            implements_by_source.setdefault(edge.source_group, []).append(edge)
+        self._implements_by_source = _freeze_adjacency(implements_by_source)
+
+    def _build_graph(
+        self,
+        semantics: WorkspaceSemanticResult,
+        *,
+        cancel_check: Callable[[], None] | None = None,
+    ) -> None:
+        self._semantic_unit_paths = {
+            id(model.unit_scope): _path_key(file_name)
+            for file_name, model in semantics.models.items()
+        }
+        for model in semantics.models.values():
+            if cancel_check is not None:
+                cancel_check()
+            for reference in model.references:
+                resolved = reference.resolved
+                fallback_resolved = False
+                if resolved is None and reference.kind == ReferenceKind.VALUE:
+                    resolved = _resolve_declaring_type_field(
+                        reference.name,
+                        reference.scope,
+                        reference.ref_range,
+                    )
+                    fallback_resolved = resolved is not None
+                if resolved is None:
+                    self._unresolved_references += 1
+                    continue
+                resolved_matches_unit = self._reference_matches_resolved_unit(
+                    reference.ref_range,
+                    resolved,
+                )
+                if resolved_matches_unit:
+                    candidate_groups = (
+                        self._exact_candidate_groups(resolved)
+                        if fallback_resolved
+                        else self._resolved_candidate_groups(resolved)
+                    )
+                else:
+                    candidate_groups = self._project_local_candidate_groups(
+                        reference.ref_range,
+                        resolved,
+                    )
+                if len(candidate_groups) != 1:
+                    if len(candidate_groups) > 1:
+                        self._ambiguous_references += 1
+                    elif resolved.kind == SymbolKind.TYPE_PARAMETER:
+                        continue
+                    else:
+                        self._unresolved_references += 1
+                    continue
+                target_group = next(iter(candidate_groups))
+                owner = self._scope_target(
+                    reference.scope,
+                    call_owner=reference.kind == ReferenceKind.CALL,
+                )
+                owner_group = _target_group(owner) if owner is not None else None
+                evidence = self._evidence(reference.ref_range, reference.kind.value)
+                record = _ReferenceRecord(
+                    target_group=target_group,
+                    owner_group=owner_group,
+                    kind=reference.kind,
+                    evidence=evidence,
+                    referencing_symbol=self._referencing_symbol(reference.scope),
+                )
+                self._references.append(record)
+                if reference.kind == ReferenceKind.UNIT and owner_group is not None:
+                    self._unit_edges.append(
+                        _UnitEdge(
+                            source_group=owner_group,
+                            target_group=target_group,
+                            evidence=evidence,
+                        )
+                    )
+
+        seen_symbols: set[int] = set()
+        for model in semantics.models.values():
+            if cancel_check is not None:
+                cancel_check()
+            for symbol in _symbols_in_scope(model.unit_scope):
+                if (
+                    id(symbol) in seen_symbols
+                    or symbol.kind
+                    not in {SymbolKind.CLASS, SymbolKind.INTERFACE, SymbolKind.RECORD}
+                    or not symbol.base_types
+                ):
+                    continue
+                seen_symbols.add(id(symbol))
+                source_target = self._target_for_symbol(symbol)
+                if source_target is None:
+                    continue
+                source_group = _target_group(source_target)
+                for base_ref in symbol.base_types:
+                    base_symbol = _resolve_type_symbol(base_ref, symbol.scope, semantics.index)
+                    base_target = self._target_for_symbol(base_symbol) if base_symbol is not None else None
+                    if base_target is None:
+                        self._unresolved_references += 1
+                        continue
+                    target_group = _target_group(base_target)
+                    evidence = self._evidence(symbol.decl_range, "base_type")
+                    relation = _classify_type_relation(symbol.kind, base_symbol.kind)
+                    if relation == "inherits":
+                        self._inherits.append(_TypeEdge(source_group, target_group, evidence))
+                    elif relation == "implements":
+                        self._implements.append(_TypeEdge(source_group, target_group, evidence))
+
+    def _reference_matches_resolved_unit(
+        self,
+        reference_range: SourceRange,
+        resolved: Symbol,
+    ) -> bool:
+        unit_name = _symbol_unit_name(resolved)
+        if self._unit_name_counts.get(_normalized(unit_name), 0) <= 1:
+            return True
+        if _path_key(reference_range.file_name) == _path_key(
+            resolved.decl_range.file_name
+        ):
+            return True
+        reference_path = _path_key(reference_range.file_name)
+        declaration_path = _path_key(resolved.decl_range.file_name)
+        return any(
+            reference_path in membership
+            and declaration_path in membership
+            for membership in self._project_memberships
+        )
+
+    def _add_contains_edges(self, semantics: WorkspaceSemanticResult) -> None:
+        unit_targets = {
+            _normalized(target.unit_name or target.name): target
+            for target in self._targets.values()
+            if target.kind == SymbolKind.UNIT.value
+        }
+        for file_name, root in self._roots.items():
+            contains = root.find_node(SyntaxNodeType.ntContains)
+            if contains is None:
+                continue
+            model = semantics.models.get(file_name)
+            source_target = self._target_for_symbol(model.unit_scope.owner) if model is not None else None
+            if source_target is None:
+                continue
+            source_group = _target_group(source_target)
+            for child in contains.child_nodes:
+                if child.typ != SyntaxNodeType.ntUnit:
+                    continue
+                name = child.get_attribute(AttributeName.anName)
+                target = unit_targets.get(_normalized(name))
+                if target is None:
+                    self._unresolved_references += 1
+                    continue
+                evidence = self._evidence(
+                    SourceRange(
+                        file_name=child.file_name or file_name,
+                        start_line=child.line,
+                        start_col=child.col,
+                        end_line=child.line,
+                        end_col=child.col,
+                    ),
+                    "contains",
+                )
+                self._unit_edges.append(_UnitEdge(source_group, _target_group(target), evidence))
+
+    def _add_semantic_problems(self, semantics: WorkspaceSemanticResult) -> None:
+        for model in semantics.models.values():
+            for problem in model.problems:
+                self._problems.append(
+                    {
+                        "item_type": "relation_problem",
+                        "kind": "semantic",
+                        "message": problem.message,
+                        "path": self._display_path(problem.range.file_name),
+                        "line": problem.range.start_line,
+                        "column": problem.range.start_col,
+                    }
+                )
+
+    def _resolved_candidate_groups(self, symbol: Symbol) -> set[_GroupKey]:
+        groups: set[_GroupKey] = set()
+        for candidate in (symbol, *symbol.overloads):
+            target = self._target_for_symbol(candidate)
+            if target is not None:
+                groups.add(_target_group(target))
+        return groups
+
+    def _project_local_candidate_groups(
+        self,
+        reference_range: SourceRange,
+        symbol: Symbol,
+    ) -> set[_GroupKey]:
+        identity = (
+            _normalized(_semantic_qualified_name(symbol)),
+            symbol.kind.value,
+            _symbol_signature_identity(symbol),
+        )
+        reference_path = _path_key(reference_range.file_name)
+        candidates = self._identity_targets.get(identity, ())
+        project_local = {
+            _target_group(candidate)
+            for candidate in candidates
+            if any(
+                reference_path in membership
+                and _path_key(candidate.source_path) in membership
+                for membership in self._project_memberships
+            )
+        }
+        if len(project_local) == 1:
+            return project_local
+        reference_parent = _path_key(Path(reference_range.file_name).parent)
+        same_directory = {
+            _target_group(candidate)
+            for candidate in candidates
+            if _path_key(Path(candidate.source_path).parent) == reference_parent
+        }
+        if len(same_directory) == 1:
+            return same_directory
+        return project_local
+
+    def _exact_candidate_groups(self, symbol: Symbol) -> set[_GroupKey]:
+        groups: set[_GroupKey] = set()
+        for candidate in (symbol, *symbol.overloads):
+            exact = (
+                _path_key(candidate.decl_range.file_name),
+                candidate.decl_range.start_line,
+                candidate.decl_range.start_col,
+                candidate.kind.value,
+                _normalized(candidate.name),
+            )
+            groups.update(
+                _target_group(target)
+                for target in self._exact_targets.get(exact, ())
+            )
+        return groups
+
+    def _target_for_symbol(self, symbol: Symbol | None) -> RelationTarget | None:
+        if symbol is None:
+            return None
+        cached = self._symbol_targets.get(id(symbol), ...)
+        if cached is not ...:
+            return cached
+        path_key = _path_key(symbol.decl_range.file_name)
+        exact = (
+            path_key,
+            symbol.decl_range.start_line,
+            symbol.decl_range.start_col,
+            symbol.kind.value,
+            _normalized(symbol.name),
+        )
+        candidates = list(self._exact_targets.get(exact, ()))
+        if not candidates:
+            position = (
+                path_key,
+                symbol.decl_range.start_line,
+                symbol.decl_range.start_col,
+                symbol.kind.value,
+            )
+            candidates = list(self._position_targets.get(position, ()))
+        if not candidates:
+            line = (
+                path_key,
+                symbol.decl_range.start_line,
+                symbol.kind.value,
+                _normalized(symbol.name),
+            )
+            candidates = list(self._line_targets.get(line, ()))
+        if not candidates:
+            qualified_name = _semantic_qualified_name(symbol)
+            candidates = list(
+                self._identity_targets.get(
+                    (
+                        _normalized(qualified_name),
+                        symbol.kind.value,
+                        _symbol_signature_identity(symbol),
+                    ),
+                    (),
+                )
+            )
+            if self._unit_name_counts.get(
+                _normalized(_symbol_unit_name(symbol)),
+                0,
+            ) > 1:
+                semantic_unit_path = self._semantic_unit_paths.get(
+                    id(_symbol_unit_scope(symbol)),
+                    "",
+                )
+                provenance_path = semantic_unit_path or path_key
+                candidates = [
+                    candidate
+                    for candidate in candidates
+                    if _path_key(candidate.source_path) == provenance_path
+                ]
+        target = min(candidates, key=_target_sort_key) if candidates else None
+        self._symbol_targets[id(symbol)] = target
+        return target
+
+    def _scope_target(self, scope: Scope, *, call_owner: bool = False) -> RelationTarget | None:
+        current: Scope | None = scope
+        while current is not None:
+            if current.kind == ScopeKind.ROUTINE:
+                target = self._target_for_symbol(current.owner)
+                if target is not None:
+                    return target
+                if call_owner:
+                    return None
+            elif current.kind == ScopeKind.UNIT:
+                if call_owner:
+                    return None
+                target = self._target_for_symbol(current.owner)
+                if target is not None:
+                    return target
+            current = current.parent
+        return None
+
+    def _relation_item(
+        self,
+        relation: str,
+        group: _GroupKey | None,
+        evidence: Mapping[str, object],
+        *,
+        referencing_symbol: Mapping[str, object] | None = None,
+    ) -> dict[str, object] | None:
+        if group is None:
+            return None
+        candidates = self._groups.get(group)
+        if not candidates:
+            return None
+        target = candidates[0]
+        card = (
+            dict(target.card)
+            if target.card
+            else {
+                "target_id": target.target_id,
+                "unit_id": target.unit_id,
+                "name": target.name,
+                "qualified_name": target.qualified_name,
+                "kind": target.kind,
+                "path": target.path,
+                "line": target.line,
+                "column": target.column,
+                "visibility": target.visibility,
+                "owner": target.owner,
+                "type": target.type_name,
+            }
+        )
+        item: dict[str, object] = {
+            "item_type": "relation",
+            "relation": relation,
+            **card,
+            "evidence": dict(evidence),
+        }
+        if referencing_symbol is not None:
+            item["referencing_symbol"] = dict(referencing_symbol)
+        return item
+
+    def _referencing_symbol(
+        self,
+        scope: Scope,
+    ) -> dict[str, object] | None:
+        current: Scope | None = scope
+        while current is not None:
+            symbol = current.owner
+            if symbol is not None:
+                source_range = symbol.name_range
+                return {
+                    "name": symbol.name,
+                    "qualified_name": _semantic_qualified_name(symbol),
+                    "kind": symbol.kind.value,
+                    "path": self._display_path(source_range.file_name),
+                    "line": source_range.start_line,
+                    "column": source_range.start_col,
+                }
+            current = current.parent
+        return None
+
+    def _evidence(self, source_range: SourceRange, kind: str) -> dict[str, object]:
+        return {
+            "path": self._display_path(source_range.file_name),
+            "line": source_range.start_line,
+            "column": source_range.start_col,
+            "kind": kind,
+        }
+
+    def _display_path(self, file_name: str) -> str:
+        key = _path_key(file_name)
+        known = self._path_display.get(key)
+        if known is not None:
+            return known
+        path = Path(file_name).expanduser()
+        if path.is_absolute():
+            try:
+                return path.resolve().relative_to(self._root).as_posix()
+            except ValueError:
+                return f"@external/relation/{_stable_component(path.name)}"
+        return file_name.replace("\\", "/")
+
+    def _metadata(
+        self,
+        relation: str,
+        *,
+        problem_summaries: Sequence[Mapping[str, object]],
+        problem_count: int,
+        scan_complete: bool,
+    ) -> dict[str, object]:
+        limitations = {
+            "references": ["Only resolved semantic references are reported; text matches are excluded."],
+            "callers": [
+                "CALL edges cover explicit parsed calls only.",
+                "Bare parameterless, overload, virtual, and procedural dispatch can be incomplete.",
+            ],
+            "callees": [
+                "CALL edges cover explicit parsed calls only.",
+                "Bare parameterless, overload, virtual, and procedural dispatch can be incomplete.",
+            ],
+            "uses": ["Includes resolved uses clauses and project/package contains clauses."],
+            "used_by": ["Includes resolved uses clauses and project/package contains clauses."],
+            "inherits": ["Reports resolved class-to-class and interface-to-interface base types."],
+            "implements": [
+                "Reports class/record base types resolved to interfaces; property delegation is not modeled."
+            ],
+        }
+        return {
+            "item_type": "relation_metadata",
+            "relation": relation,
+            "completeness": "sound_partial",
+            "unresolved_references": self._unresolved_references,
+            "ambiguous_references": self._ambiguous_references,
+            "deep_problem_count": problem_count,
+            "problems": [dict(problem) for problem in problem_summaries],
+            "problems_truncated": problem_count > len(problem_summaries),
+            "scan_complete": scan_complete,
+            "limitations": limitations[relation],
+        }
+
+    @staticmethod
+    def _validate_applicability(target: RelationTarget, relation: str) -> None:
+        applicable = True
+        if relation in {"callers", "callees"}:
+            applicable = target.kind in _ROUTINE_KINDS
+        elif relation in {"uses", "used_by"}:
+            applicable = target.kind == SymbolKind.UNIT.value
+        elif relation == "inherits":
+            applicable = target.kind in {SymbolKind.CLASS.value, SymbolKind.INTERFACE.value}
+        elif relation == "implements":
+            applicable = target.kind in {SymbolKind.CLASS.value, SymbolKind.RECORD.value}
+        if not applicable:
+            raise AgentProtocolError(
+                "relation_not_applicable",
+                f"Relation {relation!r} does not apply to {target.kind} target {target.target_id}.",
+            )
+
+
+def _load_project_roots(
+    workspace: AgentWorkspace,
+    *,
+    cancel_check: Callable[[], None] | None = None,
+) -> tuple[
+    dict[str, SyntaxNode],
+    dict[str, PreprocessedSource],
+    list[dict[str, object]],
+]:
+    active_project = workspace.active_project
+    if active_project is None:
+        raise AgentProtocolError("project_required", "Select a project before tracing relations.")
+    parser_mode = (
+        ParserMode.TOLERANT
+        if len(workspace.units) >= 256
+        else ParserMode.STRICT
+    )
+    if active_project.kind != "workspace":
+        if cancel_check is not None:
+            cancel_check()
+        project_path = Path(active_project.path)
+        if not project_path.is_absolute():
+            project_path = workspace.root / project_path
+        indexer = ProjectIndexer(
+            search_paths=workspace.search_paths,
+            include_paths=workspace.include_paths,
+            defines=workspace.defines,
+            mode=parser_mode,
+            project_config=workspace.project_config,
+        )
+        result = indexer.index(str(project_path.resolve()))
+        if cancel_check is not None:
+            cancel_check()
+        roots = {
+            str(Path(unit.path).expanduser().resolve()): unit.syntax_tree
+            for unit in result.parsed_units
+            if unit.syntax_tree is not None
+        }
+        preprocessed_sources = {
+            str(Path(unit.path).expanduser().resolve()): unit.preprocessed
+            for unit in result.parsed_units
+            if unit.syntax_tree is not None and unit.preprocessed is not None
+        }
+        problems = [_project_problem_item(problem, workspace.root) for problem in result.problems]
+        return roots, preprocessed_sources, problems
+
+    parser = DelphiParser(
+        include_paths=workspace.include_paths,
+        defines=workspace.defines,
+        include_loader=workspace_include_loader(
+            workspace.project_config,
+            workspace.include_paths,
+        ),
+        mode=parser_mode,
+        legacy_fallback_max_chars=0,
+    )
+    roots: dict[str, SyntaxNode] = {}
+    preprocessed_sources: dict[str, PreprocessedSource] = {}
+    problems: list[dict[str, object]] = []
+    for unit in workspace.units:
+        if cancel_check is not None:
+            cancel_check()
+        source_path = Path(unit.path)
+        if not source_path.is_absolute():
+            source_path = workspace.root / source_path
+        source_path = source_path.expanduser().resolve()
+        try:
+            text = read_source_text(source_path)
+            parsed = parser.parse(
+                text,
+                str(source_path),
+                build_semantic=False,
+            )
+            roots[str(source_path)] = parsed.root
+            preprocessed_sources[str(source_path)] = parsed.preprocessed
+            if parsed.problems:
+                first = parsed.problems[0]
+                problems.append(
+                    {
+                        "item_type": "relation_problem",
+                        "kind": "partial_parse",
+                        "message": (
+                            f"Partial DelphiAST parse at {first.line}:{first.column}: "
+                            f"{first.message}"
+                        ),
+                        "path": _display_project_path(source_path, workspace.root),
+                    }
+                )
+        except Exception as exc:
+            problems.append(
+                {
+                    "item_type": "relation_problem",
+                    "kind": "cant_parse_file",
+                    "message": _safe_problem_message(
+                        f"{type(exc).__name__}: {exc}",
+                        workspace.root,
+                        (
+                            source_path,
+                            getattr(exc, "filename", None),
+                            getattr(exc, "filename2", None),
+                        ),
+                    ),
+                    "path": _display_project_path(source_path, workspace.root),
+                }
+            )
+    return roots, preprocessed_sources, problems
+
+
+def _project_problem_item(problem: ProjectProblem, root: Path) -> dict[str, object]:
+    return {
+        "item_type": "relation_problem",
+        "kind": problem.problem_type.value,
+        "message": _safe_problem_message(problem.description, root, (problem.file_name,)),
+        "path": _display_project_path(problem.file_name, root),
+    }
+
+
+def _safe_problem_message(
+    message: str,
+    root: Path,
+    known_paths: Iterable[str | PurePath | None],
+) -> str:
+    replacements: dict[str, str] = {}
+    for value in known_paths:
+        if value is None:
+            continue
+        original = str(value)
+        pattern = _separator_agnostic_absolute_path_pattern(original)
+        if pattern is None:
+            continue
+        safe_path = _display_project_path(original, root)
+        replacements[pattern] = safe_path
+    for pattern in sorted(replacements, key=len, reverse=True):
+        replacement = replacements[pattern]
+        message = re.sub(pattern, lambda _match: replacement, message)
+    return message
+
+
+def _display_project_path(path: str | PurePath, root: Path) -> str:
+    path_text = str(path)
+    if not _is_cross_platform_absolute(path_text):
+        return Path(path_text).as_posix()
+    host_path = Path(path_text)
+    if host_path.is_absolute():
+        resolved = host_path.expanduser().resolve()
+        relative = _portable_relative_to_root(resolved, root)
+        if relative is not None:
+            return relative
+        return f"@external/relation/{_stable_component(resolved.name)}"
+    relative = _portable_relative_to_root(path_text, root)
+    if relative is not None:
+        return relative
+    return f"@external/relation/{_stable_component(_portable_name(path_text))}"
+
+
+def _is_cross_platform_absolute(path: str | PurePath) -> bool:
+    text = str(path)
+    return PurePosixPath(text).is_absolute() or PureWindowsPath(text).is_absolute()
+
+
+def _separator_agnostic_absolute_path_pattern(path: str | PurePath) -> str | None:
+    text = str(path)
+    windows_path = PureWindowsPath(text)
+    if windows_path.is_absolute():
+        canonical = windows_path.as_posix()
+        case_insensitive = True
+    else:
+        posix_path = PurePosixPath(text)
+        if not posix_path.is_absolute():
+            return None
+        canonical = posix_path.as_posix()
+        case_insensitive = False
+    pattern = r"[\\/]+".join(re.escape(component) for component in canonical.split("/"))
+    return f"(?i:{pattern})" if case_insensitive else pattern
+
+
+def _portable_relative_to_root(path: str | PurePath, root: Path) -> str | None:
+    text = str(path)
+    posix_path = PurePosixPath(text)
+    posix_root = PurePosixPath(str(root))
+    if posix_path.is_absolute() and posix_root.is_absolute():
+        try:
+            return posix_path.relative_to(posix_root).as_posix()
+        except ValueError:
+            pass
+
+    windows_path = PureWindowsPath(text)
+    windows_root = PureWindowsPath(str(root))
+    if windows_path.is_absolute() and windows_root.is_absolute():
+        try:
+            return windows_path.relative_to(windows_root).as_posix()
+        except ValueError:
+            pass
+    return None
+
+
+def _portable_name(path: str | PurePath) -> str:
+    return PurePosixPath(str(path).replace("\\", "/")).name or "unknown"
+
+
+def _resolve_type_symbol(type_ref: TypeRef, scope: Scope, index: SymbolIndex) -> Symbol | None:
+    if isinstance(type_ref, GenericInstanceTypeRef):
+        return _resolve_type_symbol(type_ref.base, scope, index)
+    if not isinstance(type_ref, NamedTypeRef):
+        return None
+    if type_ref.unit_name:
+        unit_scope = index.lookup_unit(type_ref.unit_name)
+        if unit_scope is not None:
+            symbols = unit_scope.lookup_local(type_ref.name)
+            return symbols[0] if symbols else None
+    if "." in type_ref.name:
+        symbols = index.resolve_qualified(type_ref.name)
+        if symbols:
+            return symbols[0]
+    symbols = scope.resolve(type_ref.name)
+    return symbols[0] if symbols else None
+
+
+def _resolve_declaring_type_field(
+    name: str,
+    scope: Scope,
+    reference_range: SourceRange,
+) -> Symbol | None:
+    """Resolve an unqualified field used by a qualified method implementation."""
+    if name.startswith("&"):
+        return None
+    parts = name.split(".")
+    explicit_self = len(parts) > 1 and parts[0].casefold() == "self"
+    if not explicit_self or len(parts) != 2:
+        return None
+    if _has_escaped_reference_prefix(reference_range, name):
+        return None
+    field_name = parts[1]
+    current: Scope | None = scope
+    while current is not None:
+        owner = current.owner
+        if (
+            current.kind == ScopeKind.ROUTINE
+            and owner is not None
+            and "." in owner.name
+        ):
+            type_name = owner.name.rsplit(".", 1)[0]
+            unit_scope = current
+            while unit_scope.parent is not None:
+                unit_scope = unit_scope.parent
+            type_symbols = [
+                candidate
+                for candidate in unit_scope.lookup_local(type_name)
+                if candidate.kind in {
+                    SymbolKind.CLASS,
+                    SymbolKind.RECORD,
+                    SymbolKind.TYPE,
+                }
+                and candidate.member_scope is not None
+            ]
+            fields = {
+                id(candidate): candidate
+                for type_symbol in type_symbols
+                for candidate in type_symbol.member_scope.lookup_local(field_name)
+                if candidate.kind == SymbolKind.FIELD
+            }
+            return next(iter(fields.values())) if len(fields) == 1 else None
+        current = current.parent
+    return None
+
+
+def _has_escaped_reference_prefix(
+    reference_range: SourceRange,
+    name: str,
+) -> bool:
+    root_name = name.split(".", 1)[0]
+    if reference_range.start_col <= 1 or not root_name:
+        return False
+    try:
+        lines = read_source_text(Path(reference_range.file_name)).splitlines()
+    except (OSError, UnicodeError):
+        return False
+    if not 1 <= reference_range.start_line <= len(lines):
+        return False
+    line = lines[reference_range.start_line - 1]
+    position = reference_range.start_col - 1
+    window_start = max(0, position - len(root_name) - 1)
+    window_end = min(len(line), position + len(root_name) + 1)
+    escaped_root = re.compile(
+        rf"&{re.escape(root_name)}\b",
+        re.IGNORECASE,
+    )
+    return escaped_root.search(line, window_start, window_end) is not None
+
+
+def _classify_type_relation(source_kind: SymbolKind, target_kind: SymbolKind) -> str | None:
+    if (
+        source_kind == SymbolKind.CLASS
+        and target_kind == SymbolKind.CLASS
+    ) or (
+        source_kind == SymbolKind.INTERFACE
+        and target_kind == SymbolKind.INTERFACE
+    ):
+        return "inherits"
+    if source_kind in {SymbolKind.CLASS, SymbolKind.RECORD} and target_kind == SymbolKind.INTERFACE:
+        return "implements"
+    return None
+
+
+def _symbols_in_scope(scope: Scope) -> Iterable[Symbol]:
+    seen_scopes: set[int] = set()
+
+    def visit(current: Scope) -> Iterable[Symbol]:
+        if id(current) in seen_scopes:
+            return
+        seen_scopes.add(id(current))
+        for symbols in current.symbols.values():
+            for symbol in symbols:
+                yield symbol
+                if symbol.member_scope is not None:
+                    yield from visit(symbol.member_scope)
+
+    yield from visit(scope)
+
+
+def _workspace_project_memberships(
+    workspace: AgentWorkspace,
+) -> tuple[frozenset[str], ...]:
+    parser = DelphiParser(
+        include_paths=workspace.include_paths,
+        defines=workspace.defines,
+        include_loader=workspace_include_loader(
+            workspace.project_config,
+            workspace.include_paths,
+        ),
+        mode=ParserMode.TOLERANT,
+        legacy_fallback_max_chars=0,
+    )
+    unit_paths_by_name: dict[str, list[Path]] = {}
+    for unit in workspace.units:
+        unit_path = Path(unit.path)
+        if not unit_path.is_absolute():
+            unit_path = workspace.root / unit_path
+        unit_paths_by_name.setdefault(_normalized(unit.name), []).append(
+            unit_path.expanduser().resolve()
+        )
+    memberships: list[frozenset[str]] = []
+    for project in workspace.projects:
+        if project.kind == "workspace":
+            continue
+        project_path = Path(project.path)
+        if not project_path.is_absolute():
+            project_path = workspace.root / project_path
+        project_path = project_path.expanduser().resolve()
+        try:
+            text = read_source_text(project_path)
+            root = parser.parse(
+                text,
+                str(project_path),
+                build_semantic=False,
+            ).root
+        except Exception:  # noqa: BLE001, S112
+            continue
+        members = {_path_key(project_path)}
+        pending = [root]
+        while pending:
+            node = pending.pop()
+            pending.extend(reversed(node.child_nodes))
+            if node.typ != SyntaxNodeType.ntUnit:
+                continue
+            declared_path = node.get_attribute(AttributeName.anPath).strip()
+            if not declared_path:
+                unit_name = node.get_attribute(AttributeName.anName).strip()
+                local_candidates = [
+                    candidate
+                    for candidate in unit_paths_by_name.get(
+                        _normalized(unit_name),
+                        (),
+                    )
+                    if candidate.parent == project_path.parent
+                ]
+                if len(local_candidates) == 1:
+                    members.add(_path_key(str(local_candidates[0])))
+                continue
+            member_path = Path(declared_path.replace("\\", "/"))
+            if not member_path.is_absolute():
+                member_path = project_path.parent / member_path
+            members.add(_path_key(str(member_path.expanduser().resolve())))
+        if len(members) > 1:
+            memberships.append(frozenset(members))
+    return tuple(memberships)
+
+
+def _symbol_unit_scope(symbol: Symbol) -> Scope:
+    scope = symbol.scope
+    while scope.parent is not None:
+        scope = scope.parent
+    return scope
+
+
+def _symbol_unit_name(symbol: Symbol) -> str:
+    return _symbol_unit_scope(symbol).name
+
+
+def _semantic_qualified_name(symbol: Symbol) -> str:
+    scope = symbol.scope
+    unit_scope = scope
+    while unit_scope.parent is not None:
+        unit_scope = unit_scope.parent
+    unit_name = unit_scope.name
+    if symbol.kind == SymbolKind.UNIT:
+        return unit_name
+    if scope.kind == ScopeKind.TYPE and scope.owner is not None:
+        return f"{unit_name}.{scope.owner.name}.{symbol.name}"
+    return f"{unit_name}.{symbol.name}"
+
+
+def _target_group(target: RelationTarget) -> _GroupKey:
+    return (
+        _path_key(target.source_path),
+        _normalized(target.qualified_name),
+        target.kind,
+        _target_signature_identity(target),
+    )
+
+
+def _target_signature_identity(target: RelationTarget) -> str:
+    if target.kind not in _ROUTINE_KINDS:
+        return ""
+    return _canonical_signature_identity(target.signature)
+
+
+def _symbol_signature_identity(symbol: Symbol) -> str:
+    if symbol.kind.value not in _ROUTINE_KINDS or not isinstance(symbol.type_ref, ProcTypeRef):
+        return ""
+    parameter_symbols = []
+    if symbol.member_scope is not None:
+        parameter_symbols = sorted(
+            (
+                candidate
+                for symbols in symbol.member_scope.symbols.values()
+                for candidate in symbols
+                if candidate.kind == SymbolKind.PARAMETER
+            ),
+            key=lambda candidate: (
+                candidate.decl_range.start_line,
+                candidate.decl_range.start_col,
+                candidate.name.casefold(),
+            ),
+        )
+    normalized_params: list[str] = []
+    for index, param in enumerate(symbol.type_ref.params):
+        modifier = ""
+        if index < len(parameter_symbols):
+            modifier = _normalized(parameter_symbols[index].attributes.get("modifier", ""))
+        type_name = _normalized(param.display_name()).replace(" ", "")
+        normalized_params.append(f"{modifier}:{type_name}")
+    params = ",".join(normalized_params)
+    signature = f"({params})"
+    if symbol.type_ref.return_type is not None:
+        result = _normalized(symbol.type_ref.return_type.display_name()).replace(" ", "")
+        signature = f"{signature}:{result}"
+    calling_convention = _normalized(symbol.attributes.get("callingconvention", ""))
+    if calling_convention:
+        signature = f"{signature}|cc:{calling_convention}"
+    return _canonical_signature_identity(signature)
+
+
+def _canonical_signature_identity(signature: str) -> str:
+    def split_parameters(content: str) -> list[str]:
+        parameters: list[str] = []
+        start = 0
+        depth = 0
+        for index, char in enumerate(content):
+            if char == "(":
+                depth += 1
+            elif char == ")":
+                depth -= 1
+            elif char in ";," and depth == 0:
+                parameters.append(content[start:index])
+                start = index + 1
+        parameters.append(content[start:])
+        return parameters
+
+    def canonicalize(content: str) -> str:
+        parts: list[str] = []
+        index = 0
+        while index < len(content):
+            if content[index] != "(":
+                parts.append(content[index])
+                index += 1
+                continue
+            depth = 1
+            end = index + 1
+            while end < len(content) and depth:
+                if content[end] == "(":
+                    depth += 1
+                elif content[end] == ")":
+                    depth -= 1
+                end += 1
+            if depth:
+                parts.append(content[index:])
+                break
+            parameters = split_parameters(content[index + 1 : end - 1])
+            expanded: list[str] = []
+            for parameter in parameters:
+                match = re.fullmatch(r"\s*((?:var|const|out)\s*)?#(\d+):(.*)", parameter, re.DOTALL)
+                if match is None:
+                    expanded.append(canonicalize(parameter))
+                    continue
+                modifier, count, parameter_type = match.groups()
+                expanded.extend(
+                    f"{modifier or ''}:{canonicalize(parameter_type)}"
+                    for _ in range(int(count))
+                )
+            parts.append(f"({','.join(expanded)})")
+            index = end
+        return "".join(parts)
+
+    return _normalized(canonicalize(signature).replace(" ", ""))
+
+
+def _target_sort_key(target: RelationTarget) -> tuple[object, ...]:
+    return (
+        target.path.casefold(),
+        target.line,
+        target.column,
+        target.qualified_name.casefold(),
+        target.signature.casefold(),
+        target.target_id,
+    )
+
+
+def _relation_sort_key(item: Mapping[str, object]) -> tuple[object, ...]:
+    evidence = item.get("evidence")
+    evidence_mapping = evidence if isinstance(evidence, Mapping) else {}
+    return (
+        str(item.get("qualified_name", "")).casefold(),
+        str(item.get("path", "")).casefold(),
+        int(item.get("line", 0)),
+        int(item.get("column", 0)),
+        str(evidence_mapping.get("path", "")).casefold(),
+        int(evidence_mapping.get("line", 0)),
+        int(evidence_mapping.get("column", 0)),
+        str(evidence_mapping.get("kind", "")),
+        str(item.get("target_id", "")),
+    )
+
+
+def _freeze_adjacency(
+    groups: Mapping[_GroupKey, list[_AdjacencyValue]],
+) -> dict[_GroupKey, tuple[_AdjacencyValue, ...]]:
+    return {key: tuple(values) for key, values in groups.items()}
+
+
+def _dedupe_mappings(items: Iterable[Mapping[str, object]]) -> list[dict[str, object]]:
+    result: list[dict[str, object]] = []
+    seen: set[str] = set()
+    for item in items:
+        mapping = dict(item)
+        key = repr(_freeze(mapping))
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(mapping)
+    return result
+
+
+def _summarize_relation_problems(
+    problems: Iterable[Mapping[str, object]],
+    *,
+    limit: int,
+) -> tuple[list[dict[str, object]], int]:
+    summaries: list[dict[str, object]] = []
+    seen: set[tuple[str, str, str]] = set()
+    for problem in problems:
+        mapping = dict(problem)
+        key = (
+            str(mapping.get("path", mapping.get("file", ""))),
+            str(mapping.get("kind", "")),
+            str(mapping.get("message", "")),
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        if len(summaries) < limit:
+            summaries.append(mapping)
+    return summaries, len(seen)
+
+
+def _freeze(value: object) -> object:
+    if isinstance(value, Mapping):
+        return tuple(sorted((str(key), _freeze(item)) for key, item in value.items()))
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+def _path_key(value: str | Path) -> str:
+    return str(Path(value).expanduser().resolve()).casefold()
+
+
+def _normalized(value: str) -> str:
+    return unicodedata.normalize("NFC", value).casefold()
+
+
+def _text_contains_reference_token(text: str, value: str) -> bool:
+    needle = _normalized(value)
+    normalized_text = _normalized(text) if not needle.isascii() else text.casefold()
+    if not needle:
+        return False
+    if re.fullmatch(r"[^\W\d]\w*(?:\.[^\W\d]\w*)*", needle) is None:
+        return needle in normalized_text
+    return re.search(
+        rf"(?<!\w){re.escape(needle)}(?!\w)",
+        normalized_text,
+    ) is not None
+
+
+def _stable_component(value: str) -> str:
+    return unicodedata.normalize("NFC", value).replace("\\", "_").replace("/", "_") or "unknown"
+
+
+__all__ = ["ProjectRelationIndex", "RelationTarget"]