ADR 0067: Graph-backed surfaces - a general contract for a family of graph screens

Status: Accepted
Date: 2026-04-19
Updated: 2026-05-14 - link to placing the shared implementation layer in CDS (0115), not IDS. Details - § History.

Related ADRs

Summary

• General contract of graph-backed surfaces: data, interaction, layout, sync.
• Family: intent map, GitMap, future graphs; implementation - 0115.
• Axes graph_kind, provenance, relation_kind - in 0065, 0114.

Context

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), possible future graphs (dependencies, service topology, etc.).

If each script is run by a separate ad-hoc viewer, the following will inevitably be duplicated:

• data model and node/edge identity in the workspace;
• interaction (zoom, scrolling, hit-test, gestures);
• navigation semantics (“go to symbol”, “expand subgraph”, “synchronize with editor”);
• layout abstraction (so as not to copy the layout between domains);
• selection, focus, keyboard outline;
• coordination with the rest of the workspace (decision tree, open files, MCP, invalidation when changing branches/git).

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.

A task at the platform architecture level, and not a request to “draw nodes and edges.”

Key idea: a graph is not just a visualization

Graph in this IDE is not synonymous with a picture for a report.

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.

Solution

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.

Limitations: What it is not

So that the implementation and external agents do not “go” to the one-time viewer:

• this is not “diagram control” as a complete answer (diagram without navigation model and synchronization with workspace);
• this is not a layer only rendering;
• this is not a feature under one CFG / one use case; is an extensible platform for several graph-backed tools (Semantic Map, GitMap, future dependency/relationship graphs, etc.).

Additional platform requirements

In addition to the dimensions table, the target contract includes:

• Single graph document abstraction (e.g. GraphDocument or equivalent): nodes/edges, metadata, domain binding and graph_kind (0065).
• 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).
• Serializable state surface: selection, viewport, filters - to restore the session, tests and consistency with other panels.
• Agent introspection: surface state is readable by agent and commands (MCP / ide_*), without sole reliance on pixels.
• Different layout engines as plug-in strategies without breaking the document model (see Layout abstraction and 0055).

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 so that the team and agent can transfer expectations between screens.

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.

Contract dimensions (what is explicitly agreed upon)

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.

Starting prompt for the agent (English)

The text below can be used as a single starting point for design and review (Cursor, etc.):

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.

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.

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.

Please propose an architecture for a generic graph-surface framework, including where appropriate:

• graph document model and node/edge metadata;
• layout abstraction and pluggable layout engines without breaking the document model;
• interaction contract (pan/zoom/hit-test as needed);
• command routing and unified navigation semantics (e.g. node → source / details / related graph);
• selection/focus and synchronization with the rest of the IDE workspace;
• deep-linking and serializable surface state;
• agent introspection over surface state.

Cross-check with ADR 0067 (graph-backed surfaces) and related ADRs on graph_kind, Semantic Map, GitMap, and the Skia pipeline.

Consequences

• New graph features are checked: which dimension is already covered by a general layer, what is domain-specific.
• Documentation and reviews can refer to graph-backed surface and dimension table instead of "another map".
• Pipeline 0055 remains a common place for Layout/Render; graph sources are connected as adapters, not viewer forks.

Non-targets (current phase)

• A single universal layout for all types of graphs in one release.
• 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.
• Replacing 0062 or 0065: they clarify domain; this ADR specifies the UI class.

Alternatives (briefly)

History of changes