| 1 | <!-- English translation of adr/0067-graph-backed-surfaces-contract.md. Canonical Russian: ../../adr/0067-graph-backed-surfaces-contract.md --> |
| 2 | |
| 3 | # ADR 0067: Graph-backed surfaces - a general contract for a family of graph screens |
| 4 | |
| 5 | **Status:** Accepted |
| 6 | **Date:** 2026-04-19 |
| 7 | **Updated:** 2026-05-14 - link to placing the shared implementation layer in **CDS** ([0115](0115-cds-graph-backed-shared-layer.md)), not IDS. Details - [§ History](#adr0067-history). |
| 8 | |
| 9 | ## Related ADRs |
| 10 | |
| 11 | | ADR | Role | |
| 12 | |-----|------| |
| 13 | | [0065](0065-instrument-categories-domain-taxonomy.md) | Axis `graph_kind`, tool categories | |
| 14 | | [0113](0113-hci-semantic-map-orientation-layer.md) | Axes **provenance**, summary of three axes | |
| 15 | | [0114](0114-graph-edge-relation-kind-taxonomy.md) | Directory `relation_kind` on edges | |
| 16 | | [0115](0115-cds-graph-backed-shared-layer.md) | General implementation layer in **CDS**, not IDS | |
| 17 | | [0062](0062-git-submodules-semantic-map-subgraph.md) | GitMap - data domain, general pipeline | |
| 18 | | [0053](0053-semantic-map-control-flow-pfd.md) | Semantic Map, control flow | |
| 19 | | [0056](0056-semantic-map-pipeline-adoption.md) | Introduction of Skia pipeline into the map | |
| 20 | | [0055](0055-skia-instrument-composition-pipeline.md) | Intent → Declutter → Layout → Render | |
| 21 | | [0039](0039-workspace-navigation-affordances.md) | Navigation, MCP, subgraph | |
| 22 | | [0047](0047-cockpit-instrument-descriptor-and-slot-composition.md) | Instrument, slot, surface | |
| 23 | | [0021](0021-pfd-mfd-cockpit-attention-model.md) | PFD/MFD Focus Areas | |
| 24 | | [0066](0066-cockpit-ui-vs-ide-presentation-layer.md) | Device surface vs chrome IDE (`ModalOverlay`) | |
| 25 | |
| 26 | ## Summary |
| 27 | |
| 28 | - General **contract of graph-backed surfaces**: data, interaction, layout, sync. |
| 29 | - Family: intent map, GitMap, future graphs; implementation - [0115](0115-cds-graph-backed-shared-layer.md). |
| 30 | - Axes **`graph_kind`**, provenance, **`relation_kind`** - in [0065](0065-instrument-categories-domain-taxonomy.md), [0114](0114-graph-edge-relation-kind-taxonomy.md). |
| 31 | |
| 32 | --- |
| 33 | ## Context |
| 34 | |
| 35 | In the IDE, **not one** graph screen appears, but a **family** of surfaces, where the user and agent work with the **graph** as the main object: Semantic Map (code intent / control flow), GitMap / submodules ([0062](0062-git-submodules-semantic-map-subgraph.md)), possible future graphs (dependencies, service topology, etc.). |
| 36 | |
| 37 | If each script is run by a **separate ad-hoc viewer**, the following will inevitably be duplicated: |
| 38 | |
| 39 | - data model and node/edge identity in the workspace; |
| 40 | - interaction (zoom, scrolling, hit-test, gestures); |
| 41 | - navigation semantics (“go to symbol”, “expand subgraph”, “synchronize with editor”); |
| 42 | - layout abstraction (so as not to copy the layout between domains); |
| 43 | - selection, focus, keyboard outline; |
| 44 | - coordination with the rest of the workspace (decision tree, open files, MCP, invalidation when changing branches/git). |
| 45 | |
| 46 | We need a **general UI architectural class** - **graph-backed surface** - and an explicit **contract** for the dimensions below; **the graph domain and data source are different**, rather than reinventing the wheel for each use case. |
| 47 | |
| 48 | A task at the **platform architecture** level, and not a request to “draw nodes and edges.” |
| 49 | |
| 50 | <a id="adr0067-key"></a> |
| 51 | |
| 52 | ### Key idea: a graph is not just a visualization |
| 53 | |
| 54 | **Graph** in this IDE is **not** synonymous with a picture for a report. |
| 55 | |
| 56 | **Graph-backed surface** is an **navigation surface IDE** with the same rights as **editor**, **terminal**, **diagnostics**, **solution explorer**: not a decorative diagram and not an export-only preview, but an **operational surface** through which both a person and an agent can explore the structure, select nodes, go to sources, filter, focus and perform actions. Visualization is a consequence of the model and contract, and not vice versa. |
| 57 | |
| 58 | --- |
| 59 | |
| 60 | ## Solution |
| 61 | |
| 62 | Fix the concept of **graph-backed surface** (working name): **tool or UI fragment**, in which **primary** is work with a **oriented (or labeled) graph** as an object of navigation and actions, coordinated with the cockpit and workspace according to uniform rules; rendering is one of the layers, not the definition of the surface. **Placing the general implementation** of reused parts of this class in the product - in the **CDS / Cockpit** circuit, not in the **IDS**; see **[0115](0115-cds-graph-backed-shared-layer.md)**. |
| 63 | |
| 64 | <a id="adr0067-not"></a> |
| 65 | |
| 66 | ### Limitations: What it is not |
| 67 | |
| 68 | So that the implementation and external agents do not “go” to the one-time viewer: |
| 69 | - this is **not** “diagram control” as a complete answer (diagram without navigation model and synchronization with workspace); |
| 70 | - this is **not** a layer **only** rendering; |
| 71 | - this is **not** a feature under **one** CFG / one use case; |
| 72 | is an **extensible platform** for **several** graph-backed tools (Semantic Map, GitMap, future dependency/relationship graphs, etc.). |
| 73 | |
| 74 | <a id="adr0067-extra"></a> |
| 75 | |
| 76 | ### Additional platform requirements |
| 77 | |
| 78 | In addition to the [dimensions table](#adr0067-dimensions), the target contract includes: |
| 79 | |
| 80 | - **Single graph document abstraction** (e.g. **GraphDocument** or equivalent): nodes/edges, metadata, domain binding and `graph_kind` ([0065](0065-instrument-categories-domain-taxonomy.md)). |
| 81 | - **Unified semantics of navigation commands**: from a node - to **sources**, **details**, **related subgraph** / related graph (wording may differ by domain, **action channel** is the same). |
| 82 | - **Serializable state** surface: selection, viewport, filters - to restore the session, tests and consistency with other panels. |
| 83 | - **Agent introspection**: surface state is **readable** by agent and commands (MCP / `ide_*`), without sole reliance on pixels. |
| 84 | - **Different layout engines** as plug-in strategies **without** breaking the document model (see Layout abstraction and [0055](0055-skia-instrument-composition-pipeline.md)). |
| 85 | |
| 86 | **Invariant:** Semantic Map, GitMap and subsequent graph screens are **representations of one class** in the sense of the contract; they **do not** have to** share the same `instrument_id` or the same JSON wire format, but **must** be comparable across dimensions [§2](#adr0067-dimensions) so that the team and agent can transfer expectations between screens. |
| 87 | |
| 88 | Implementation is allowed **step by step** (strangler): first, two consumers (for example Semantic Map + GitMap) identify a common minimum; the contract in the code (`interface`/set of protocols) is extended without breaking ADR. |
| 89 | |
| 90 | <a id="adr0067-dimensions"></a> |
| 91 | |
| 92 | ### Contract dimensions (what is explicitly agreed upon) |
| 93 | | Measurement | Question answered by layer | Note | |
| 94 | |-----------|-------------------------|-----------| |
| 95 | | **Data model** | What is a node and an edge in **this** domain; stable **key** within a session; association with `graph_kind` and tool category ([0065](0065-instrument-categories-domain-taxonomy.md)). | The domains are orthogonal: code vs git topology - different graphs, same surface class. | |
| 96 | | **Edge/node provenance** | What **source of truth** are the connections and nodes for this screen based on: symbolic model (Roslyn), workspace heuristic (MSBuild), full-text/vec on corpus (HCI), composite (for example HCI → Roslyn). | Orthogonal to **`graph_kind`**: the same map type can combine layers with different provenance; table and names - **[0113 § axes](0113-hci-semantic-map-orientation-layer.md#adr0113-axes)**. | |
| 97 | | **Relation kind** | What **relationship** between entities does the edge assert (inherits, refers to, partial peer, text match, ...). | **[0114](0114-graph-edge-relation-kind-taxonomy.md)**; orthogonal to **`graph_kind`** and **provenance**. | |
| 98 | | **Interaction model** | Pan, zoom, drag-and-drop view, hit-test, FPS/Dark Cockpit limitations ([0021](0021-pfd-mfd-cockpit-attention-model.md) §6). | General patterns; details may vary by tool. | |
| 99 | | **Navigation semantics** | What does it mean to “go”, “open”, “request subgraph”, how does it fit in with the MCP and the agent ([0039](0039-workspace-navigation-affordances.md)). | Semantics of **actions**, not just rendering. | |
| 100 | | **Layout abstraction** | Where is the boundary between graph data and geometry: stages [0055](0055-skia-instrument-composition-pipeline.md); replaceable **layout engines** to match the appearance of the graph without duplicating Render. | GitMap and CFG are not required to have the same layout engine; must have **the same connection point** in the pipeline. | |
| 101 | | **Selection / focus model** | One or more selected nodes; keyboard focus; connection with the “current” node for the agent and UI. | It needs consistency with the rest of the cockpit. | |
| 102 | | **Command routing** | IDE commands, context menus, and hotkeys reach the surface predictably; do not duplicate disparate handlers without a policy. | Communication with [0013](0013-command-surface-and-discoverability.md), [0030](0030-command-ids-hotkeys-and-ui-registry-layers.md). | |
| 103 | | **Deep-linking / reproducibility** | Follow the link to the node/filter/view state; consistency with serializable state. | Not necessarily in v1 completely; direction is fixed. | |
| 104 | | **Sync with workspace** | Communication of the selection with the editor, decision tree, git state; invalidation when changing a file, branch, solution; without a second source of truth. | Explicit events or snapshots, not hidden globals. | |
| 105 | | **Observability (agent)** | Surface state snapshot for agent and automation; not only “what is drawn”, but also selection, focus, domain keys of nodes. | See [add. requirements](#adr0067-extra). | |
| 106 | |
| 107 | The contract **doesn't** require one common `Graph` type in memory for all domains - it requires **comparability** of protocols and **absence** of inconsistent one-off viewers without justification. |
| 108 | |
| 109 | <a id="adr0067-agent-prompt"></a> |
| 110 | |
| 111 | ### Starting prompt for the agent (English) |
| 112 | |
| 113 | The text below can be used as a single starting point for design and review (Cursor, etc.): |
| 114 | |
| 115 | We need to design a **reusable graph-surface architecture** for the IDE, not a one-off graph viewer. Existing and upcoming features such as Semantic Map (CFG), Git submodules, and future dependency / relationship graphs should all fit the **same conceptual model**. |
| 116 | |
| 117 | A graph in this IDE is **not** just a visualization; it is an **interactive workspace surface** with navigation, focus, selection, commands, synchronization with other panes, and **agent-readable state** — on par with the editor, terminal, diagnostics, and solution explorer. |
| 118 | |
| 119 | **This is not:** only a diagram control; only a rendering layer; a single feature for one CFG use case. **It should be** an **extensible platform** for multiple graph-backed tools. |
| 120 | |
| 121 | Please propose an architecture for a generic graph-surface framework, including where appropriate: |
| 122 | - graph **document** model and node/edge metadata; |
| 123 | - **layout** abstraction and pluggable layout engines without breaking the document model; |
| 124 | - **interaction** contract (pan/zoom/hit-test as needed); |
| 125 | - **command routing** and unified navigation semantics (e.g. node → source / details / related graph); |
| 126 | - **selection/focus** and synchronization with the rest of the IDE workspace; |
| 127 | - **deep-linking** and **serializable** surface state; |
| 128 | - **agent introspection** over surface state. |
| 129 | |
| 130 | Cross-check with ADR **0067** (graph-backed surfaces) and related ADRs on `graph_kind`, Semantic Map, GitMap, and the Skia pipeline. |
| 131 | |
| 132 | --- |
| 133 | |
| 134 | ## Consequences |
| 135 | |
| 136 | - New graph features are checked: **which dimension** is already covered by a general layer, **what** is domain-specific. |
| 137 | - Documentation and reviews can refer to **graph-backed surface** and dimension table instead of "another map". |
| 138 | - Pipeline [0055](0055-skia-instrument-composition-pipeline.md) remains a **common place** for Layout/Render; graph sources are connected as **adapters**, not viewer forks. |
| 139 | |
| 140 | --- |
| 141 | |
| 142 | ## Non-targets (current phase) |
| 143 | |
| 144 | - A single **universal** layout for all types of graphs in one release. |
| 145 | - Full implementation of all measurements in the code before the appearance of the second and third consumers of the contract - let's say **minimum v0** and extension. |
| 146 | - Replacing [0062](0062-git-submodules-semantic-map-subgraph.md) or [0065](0065-instrument-categories-domain-taxonomy.md): they clarify **domain**; this ADR specifies the **UI class**. |
| 147 | |
| 148 | --- |
| 149 | |
| 150 | ## Alternatives (briefly) |
| 151 | |
| 152 | | Option | Minus | |
| 153 | |--------|--------| |
| 154 | | Separate viewer for each graph | Duplication, divergence of navigation and synchronization with workspace | |
| 155 | | One hard `GraphView` control for all data | Does not bend to different domains and layouts; slows down evolution | |
| 156 | | Only guide in Markdown without ADR | No stable link for review and onboarding | |
| 157 | |
| 158 | --- |
| 159 | |
| 160 | ## History of changes |
| 161 | |
| 162 | <a id="adr0067-history"></a> |
| 163 | |
| 164 | | Date | Change | |
| 165 | |------|-----------| |
| 166 | | 2026-04-19 | key idea “operating surface”, limitations, additional. requirements, seed for agent (EN). | |
| 167 | | 2026-05-14 | dimensions **Edge / node provenance** ([0113 § axes](0113-hci-semantic-map-orientation-layer.md#adr0113-axes)) and **Relation kind** ([0114](0114-graph-edge-relation-kind-taxonomy.md)); both are orthogonal to `graph_kind`. | |
| 168 | | 2026-05-14 | reference to placing the shared implementation layer in **CDS** ([0115](0115-cds-graph-backed-shared-layer.md)), not IDS. | |