| 1 | <!-- English translation of adr/0114-graph-edge-relation-kind-taxonomy.md. Canonical Russian: ../../adr/0114-graph-edge-relation-kind-taxonomy.md --> |
| 2 | |
| 3 | # ADR 0114: Relation type on graph edges (`relation_kind`) - connection semantics |
| 4 | |
| 5 | **Status:** Proposed |
| 6 | **Date:** 2026-05-14 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0065 §6](0065-instrument-categories-domain-taxonomy.md#adr0065-p6) | `graph_kind` - *what* domain graph (orthogonal) | |
| 13 | | [0067](0067-graph-backed-surfaces-contract.md#adr0067-dimensions) | Edge/node measurement **provenance** | |
| 14 | | [0113 § axes](0113-hci-semantic-map-orientation-layer.md#adr0113-axes) | Three Axes and HCI Summary | |
| 15 | | [0039](0039-workspace-navigation-affordances.md) | Navigation workspace, related files | |
| 16 | | [0105](0105-hybrid-codebase-index-for-csharp-web.md) | Hybrid index, `hit_kind` | |
| 17 | |
| 18 | ## Summary |
| 19 | |
| 20 | - **`relation_kind`** axis on the edges of the graph (“inherits”, partial peer, ...). |
| 21 | - Orthogonal to `graph_kind` and provenance ([0113](0113-hci-semantic-map-orientation-layer.md)). |
| 22 | |
| 23 | |
| 24 | ## Problem |
| 25 | |
| 26 | For graph-backed surfaces we already breed: |
| 27 | |
| 28 | - **`graph_kind`** - form of a domain graph (intent map, related files, Git modules tree, ...); |
| 29 | - **`edge_provenance`** — connection calculation source (Roslyn, MSBuild workspace navigation, HCI FTS/vec, composite). |
| 30 | |
| 31 | This is **not enough** for the user and the agent to equally understand the **meaning of the edge**: “successor”, “implements an interface”, “refers to a type”, “same partial”, “just appears in the text next to the name” - different **relations**, and mixing them in one nameless “edge exists” breaks trust in the map, MCP hints and auto-actions. |
| 32 | |
| 33 | We need an explicit dictionary of **relationship type** on an edge (or on a node→node logical connection), independent of *who* built it and *in what* `graph_kind` screen it is shown. |
| 34 | |
| 35 | --- |
| 36 | |
| 37 | ## Solution |
| 38 | |
| 39 | ### 1. Concept: `relation_kind` (working name) |
| 40 | |
| 41 | Introduce the axis **`relation_kind`** (or equivalent in the wire model/MCP): **what relation semantics** we assert between two entities (or a node and an external anchor). |
| 42 | |
| 43 | **Invariant:** `relation_kind` answers the question **“what kind of connection is this in meaning?”**, and not “who calculated” (`edge_provenance`) and not “what kind of graph screen is this” (`graph_kind`). |
| 44 | |
| 45 | <a id="adr0114-three-axes"></a> |
| 46 | |
| 47 | ### 2. Three axes (briefly) |
| 48 | |
| 49 | | Axis | Question | |
| 50 | |----------|--------| |
| 51 | | **`graph_kind`** | What **domain** graph are we working in ([0065](0065-instrument-categories-domain-taxonomy.md#adr0065-p6)). | |
| 52 | | **`edge_provenance`** | **What model/index** is the relationship based on ([0113](0113-hci-semantic-map-orientation-layer.md#adr0113-axes), [0067](0067-graph-backed-surfaces-contract.md#adr0067-dimensions)). | |
| 53 | | **`relation_kind`** | **What relationship** between entities are we showing or passing to the MCP (**this ADR**). | |
| 54 | |
| 55 | The three values **do not mutually replace** each other: the same `relation_kind` (for example, “type reference”) can occur with different `edge_provenance` (Roslyn vs draft HCI candidate - then **different confidence weight**, but **same meaning of the label**, if we deliberately map HCI-hit to “candidate refers to”). |
| 56 | |
| 57 | ### 3. Draft directory `relation_kind` (extensible, non-exhaustive enum in v1) |
| 58 | |
| 59 | The groups below are **guidelines for the contract**; the exact string identifiers and set are fixed when the field appears in the DTO/MCP. |
| 60 | |
| 61 | **A. Symbolic relations (C# / Roslyn as a source of truth for meaning)** |
| 62 | Examples of meanings (conditional names before codification): |
| 63 | |
| 64 | - inheritance / implementation (`inherits`, `implements`); |
| 65 | - reference to a type or member (`references_type`, `references_member`); |
| 66 | - call (`calls`); |
| 67 | - namespace/assembly import (`imports`, `assembly_reference` - if reflected in the graph). |
| 68 | |
| 69 | **B. Workspace navigation relationships (MSBuild heuristics / related presets)** |
| 70 | Align with **[0039](0039-workspace-navigation-affordances.md)** and related types: |
| 71 | |
| 72 | - "same type partial" (`partial_peer`); |
| 73 | - “project neighbor / peer” (`project_peer`); |
| 74 | - “test for code” (`tests_peer`); |
| 75 | - other types from the workspace navigation presets - as separate `relation_kind`, and not “just edge without a name”. |
| 76 | |
| 77 | **C. Hull relations (HCI / FTS / vec)** |
| 78 | It is important here to **not name** the relationship with symbolic names from group A if the source is text only: |
| 79 | |
| 80 | - “textual match / name occurrence” (`textual_name_match`); |
| 81 | - “similar fragment by embedding” (`vector_similarity`); |
| 82 | - in an explicit "symbolic referenced-by candidate" scenario, a separate **candidate** layer marker (for example `candidate_symbol_reference`) if the product introduces a two-step **HCI → Roslyn** loop ([0113](0113-hci-semantic-map-orientation-layer.md)). |
| 83 | **D. Structural/non-code** (other `graph_kind`) |
| 84 | For example, for `repository_module_tree`: `submodule_parent_of`, `contains_path` - **different dictionary**, but the same `relation_kind` axis in the sense of “what the edge means”. |
| 85 | |
| 86 | ### 4. Communication with `hit_kind` (0105) |
| 87 | |
| 88 | The **`hit_kind`** field in the HCI response describes the **hit channel** in the index (`text_fts`, `text_vector`, ...), and **not** necessarily the relationship between two graph nodes. Mapping "hit → edge with `relation_kind`" is a separate layer (CCU/composer), where **`relation_kind`** is chosen deliberately (often group C), and not copied from `hit_kind`. |
| 89 | |
| 90 | ### 5. Contract implications |
| 91 | |
| 92 | - In subgraph/MCP wire models, when an edge or logical relationship is passed, an explicit **`relation_kind`** field (or a nested `relationship semantics` object) is **recommended** unless the meaning is unambiguously inferred from the `graph_kind` + domain node types. |
| 93 | - Agent hints and "next step" (go-to-def, usages) should take into account **`relation_kind`**: for `textual_name_match` there is a different action default than for `references_member` with `symbolic_roslyn`. |
| 94 | - Full closed enum for all languages and domains **not** the purpose of this ADR - only **axis** and draft directory; expansion as scenarios progress. |
| 95 | |
| 96 | ### 6. Not goals (v1 document) |
| 97 | |
| 98 | - RDF/OWL level ontology for the entire IDE. |
| 99 | - Replacing existing node domain fields where they already uniquely encode the same relation - no duplication required, but when exporting to MCP the agent benefits from a **stable** projection into `relation_kind`. |
| 100 | |
| 101 | --- |
| 102 | |
| 103 | ## Link to previous edits 0113 / 0067 |
| 104 | |
| 105 | **[0113 §1a](0113-hci-semantic-map-orientation-layer.md#adr0113-axes)** — table of three axes; the third line refers to this ADR. |
| 106 | **[0067](0067-graph-backed-surfaces-contract.md#adr0067-dimensions)** - the **Relation kind** line with a link here has been added to the graph-backed surface dimensions table. |
| 107 | |
| 108 | --- |
| 109 | |
| 110 | ## Rollout (sketch) |
| 111 | |
| 112 | 1. Document (this ADR) as a common language for UI and MCP reviews. |
| 113 | 2. The first field in JSON/DTO for one tool (for example related-files or semantic map export) with a minimum set of `relation_kind`. |
| 114 | 3. Catalog expansion and alignment with Roslyn API / workspace presets - iteratively. |