ADR 0114: Тип отношения на рёбрах графа (`relation_kind`) — семантика связи¶

Статус: Proposed
Дата: 2026-05-14

Связанные ADR¶

ADR	Роль
0065 §6	`graph_kind` — какой доменный граф (ортогонально)
0067	Измерение edge / node provenance
0113 § оси	Сводка трёх осей и HCI
0039	Навигация workspace, related files
0105	Hybrid index, `hit_kind`

Резюме¶

Ось relation_kind на рёбрах графа («наследует», partial peer, …).
Ортогонально graph_kind и provenance (0113).

Проблема¶

Для graph-backed поверхностей мы уже разводим:

graph_kind — форма доменного графа (карта намерений, related files, дерево модулей Git, …);
edge_provenance — источник вычисления связи (Roslyn, MSBuild workspace navigation, HCI FTS/vec, композит).

Этого недостаточно, чтобы пользователь и агент одинаково понимали смысл ребра: «наследник», «реализует интерфейс», «ссылается на тип», «тот же partial», «просто встречается в тексте рядом с именем» — разные отношения, и смешение их в одном безымянном «ребро есть» ломает доверие к карте, подсказкам MCP и авто-действиям.

Нужен явный словарь типа отношения на ребре (или на логической связи узел→узел), независимый от того, кто его построил и в каком graph_kind экране оно показано.

Решение¶

1. Понятие: `relation_kind` (рабочее имя)¶

Ввести ось relation_kind (или эквивалент в wire-модели / MCP): какую семантику отношения мы утверждаем между двумя сущностями (или узлом и внешним якорем).

Инвариант: relation_kind отвечает на вопрос «что это за связь по смыслу?», а не «кто посчитал» (edge_provenance) и не «какой это экран графа» (graph_kind).

2. Три оси (кратко)¶

Ось	Вопрос
`graph_kind`	В каком доменном графе мы работаем (0065).
`edge_provenance`	На какой модели/индексе основана связь (0113, 0067).
`relation_kind`	Какое отношение между сущностями мы показываем или передаём в MCP (этот ADR).

Три значения взаимно не подменяют друг друга: одно и то же relation_kind (например «ссылка на тип») может встречаться при разном edge_provenance (Roslyn vs черновой HCI-кандидат — тогда разный доверительный вес, но тот же смысл метки, если мы сознательно маппим HCI-hit в «кандидат ссылается на»).

3. Черновой каталог `relation_kind` (расширяемо, не исчерпывающий enum в v1)¶

Группы ниже — ориентир для контракта; точные строковые идентификаторы и набор фиксируются при появлении поля в DTO/MCP.

A. Символьные отношения (C# / Roslyn как источник истины для смысла)
Примеры смыслов (имена условные до кодификации):

наследование / реализация (inherits, implements);
ссылка на тип или член (references_type, references_member);
вызов (calls);
импорт пространства имён / сборки (imports, assembly_reference — если отражается на графе).

B. Отношения навигации по workspace (эвристики MSBuild / пресеты related)
Согласовать с 0039 и видами related:

«тот же тип partial» (partial_peer);
«сосед по проекту / peer» (project_peer);
«тест к коду» (tests_peer);
иные виды из пресетов workspace navigation — как отдельные relation_kind, а не «просто edge без имени».

C. Корпусные отношения (HCI / FTS / vec)
Здесь важно не называть связь символьными именами из группы A, если источник только текст:

«текстовое совпадение / вхождение имени» (textual_name_match);
«похожий фрагмент по embedding» (vector_similarity);
при явном сценарии «кандидат под символьное referenced-by» — отдельный маркер уровня кандидат (например candidate_symbol_reference), если продукт вводит двухшаговый контур HCI → Roslyn (0113).

D. Структурные / не-код (другие graph_kind)
Например для repository_module_tree: submodule_parent_of, contains_path — другой словарь, но та же ось relation_kind по смыслу «что означает ребро».

4. Связь с `hit_kind` (0105)¶

Поле hit_kind в ответе HCI описывает канал попадания в индексе (text_fts, text_vector, …), а не обязательно отношение между двумя узлами графа. Маппинг «hit → ребро с relation_kind» — отдельный слой (CCU / композитор), где relation_kind выбирается осознанно (часто группа C), а не копируется из hit_kind.

5. Последствия для контракта¶

В wire-моделях subgraph / MCP, когда передаётся ребро или логическая связь, рекомендуется явное поле relation_kind (или вложенный объект «семантика связи»), если смысл не выводится однозначно из graph_kind + доменных типов узлов.
Агентские подсказки и «следующий шаг» (go-to-def, usages) должны учитывать relation_kind: для textual_name_match — иной дефолт действия, чем для references_member при symbolic_roslyn.
Полный закрытый enum на все языки и домены не цель этого ADR — только ось и черновой каталог; расширение по мере сценариев.

6. Не цели (v1 документа)¶

Онтология уровня RDF/OWL для всего IDE.
Замена существующих доменных полей узла там, где они уже однозначно кодируют то же отношение — дублирование не требуется, но при экспорте в MCP агенту полезна стабильная проекция в relation_kind.

Связь с предыдущими правками 0113 / 0067¶

0113 §1a — таблица трёх осей; третья строка ссылается на этот ADR.
0067 — в таблице измерений graph-backed surface добавлена строка Relation kind со ссылкой сюда.

Rollout (эскиз)¶

Документ (этот ADR) как общий язык для ревью UI и MCP.
Первое поле в JSON/DTO для одного инструмента (например related-files или semantic map export) с минимальным набором relation_kind.
Расширение каталога и выравнивание с Roslyn API / workspace presets — итеративно.

ADR 0114: Тип отношения на рёбрах графа (relation_kind) — семантика связи¶