ADR 0065: Категории инструментов и типы графов (ортогонально слоту и `instrument_id`)¶

Статус: Accepted
Дата: 2026-04-18
Обновлено: 2026-04-22 — «Карта намерений» = подграф намерений вокруг якоря, не вся solution map. Подробности — § История.

Связанные ADR¶

ADR	Роль
0047	`Instrument`, слот, композитор, поверхность
0063	Форма представления vs композиция в якоре
0039	Навигация, MCP, subgraph
0053	Карта намерений, control flow
0056	Pipeline adoption для карты
0062	GitMap / submodules
0055	Pipeline внутри Skia-инструмента
0067	Контракт graph-backed; `graph_kind` внутри семейства
0113	Ось provenance vs `graph_kind`
0114	Ось `relation_kind` на рёбрах

Резюме¶

Категории инструментов и graph_kind — домен ортогонален слоту.
«Карта намерений» = подграф намерений кода вокруг якоря, не вся solution map.

Контекст¶

В обсуждении кокпита неоднократно смешивались уровни:

slot_id (куда в зоне внимания — PFD, MFD, …) — см. 0047 §1;
instrument_id (какой именованный выбор смонтировать в слот) — см. 0047 §1–2;
данные (граф навигации, CFG, git-дерево, канал CDS);
продуктовые имена («Карта намерений» в меню, workspace_navigation_map в коде).

0047 уже развёл инструмент и Control, но не вводит явной оси «какого рода смысл у этого инструмента для пилота и агента». В результате одно и то же слово («workspace», «карта намерений» / устар. semantic map) читается то как домен данных, то как id прибора, то как название графа.

Нужна устойчивая, узкая таксономия категорий — не замена instrument_id и не дублирование 0063 (там другие оси: ContentRepresentation vs deck).

Решение¶

Категория инструмента (instrument_category в будущем расширении дескриптора, см. последствия) — это отдельная ось, ортогональная:
slot_id (география внимания),
instrument_id (стабильное имя выбора композитора),
двум осям 0063 (форма страницы vs состав колоды в якоре).

Категория отвечает на вопрос: какой класс задач человека/агента обслуживает этот инструмент (навигация по коду, по файлам, топология репозитория, …).

«Карта намерений» в узком продуктовом смысле — это семантическая карта намерений кода (какие шаги, ветви и намерения в потоке метода/фрагмента кода отражены на карте), не «любой граф смысловых связей» вообще и не синоним Instrument и не место отрисовки. Отображение по-прежнему через инструмент (например workspace_navigation_map в слоте PFD) и pipeline 0055. Общий wire-контейнер (CodeNavigationMapSubgraphDocument и JSON MCP) может нести разные виды графов — см. п.6.

Канонический минимум категорий (строковые идентификаторы, расширяемы по мере продуктовой необходимости):

Категория	Смысл	Примечание
`code_navigation`	Навигация и связи в коде (символы, вызовы, control flow, предикаты; контракт агента и MCP для кода).	Домен CodeNavigation.
`workspace_navigation`	Зависимости и связи между файлами/артефактами в смысле структуры workspace (дерево решения, peer-файлы, каталоги).	Не путать с git-топологией ниже.
`repository_topology`	Топология репозитория (submodules, границы вложенных репо) как дерево / GitMap — 0062.	Отдельно от `code_navigation` и от узкого `workspace_navigation`.

Дополнительные категории (например проекция канала CDS, readout окружения, deck по 0064) вводятся отдельными ADR или дополнениями к таблице, чтобы не раздувать минимум без реального второго инструмента.

Связь с существующими instrument_id: у текущих идентификаторов (например workspace_navigation_map) историческое имя может не совпадать с категорией из таблицы — это нормально: instrument_id остаётся стабильным контрактом; категория добавляет семантику для документации, фильтров и агента, а не переименование id в лоб.

Skia pipeline (0055) остаётся внутренним к конкретному инструменту; категория не заменяет Intent / Declutter / Layout — она про домен источника данных, а не про шаги пайплайна.

Тип графа (graph_kind, рабочее имя; опционально в wire-модели и MCP) — ось структуры и семантики подграфа, ортогональная категории инструмента там, где один и тот же контейнер JSON несёт разные формы графа (например control flow vs звезда связанных файлов). Минимальный набор для различения (расширяемо):

`graph_kind`	Смысл
`code_intent_code_navigation_map`	Семантическая карта намерений кода — узкий смысл продукта «Карта намерений»: какие намерения и шаги в потоке кода отражены на карте; отображение control flow на PFD — в этом же контексте (0053). (Устар. имя `code_intent_semantic_map` в парсере по-прежнему принимается.)
`related_files`	Граф связанных файлов (peer, тест, XAML и т.д.), не «карта намерений кода».
`repository_module_tree`	Дерево модулей / submodules (0062).

Пока различение частично косвенное (уровень карты file vs controlFlow, поля kind на узлах). Рекомендация: при следующем изменении контракта subgraph добавить явное поле graph_kind (или эквивалент в MCP), чтобы агент и UI не выводили тип графа из эвристик.

Ось graph_kind отвечает на вопрос какой доменный граф (форма подграфа). Она ортогональна оси происхождения связей (Roslyn vs MSBuild workspace navigation vs HCI FTS/vec и композиты) — см. ADR 0113 § оси. Третья ось — тип отношения (relation_kind: «наследует», «ссылается на», …) — ADR 0114.

Связь категория инструмента ↔ тип графа: типично code_navigation ↔ code_intent_code_navigation_map; workspace_navigation ↔ related_files; repository_topology ↔ repository_module_tree. Соответствие не обязано быть 1:1 (один инструмент может переключать режим и тем самым тип графа).

Последствия¶

Реестр инструментов и документация MCP могут ссылаться на instrument_category для группировки («покажи только навигацию по коду») без чтения кода каждого instrument_id.
CockpitInstrumentDescriptor (и связанные типы) рекомендуется расширить опциональным полем категории, когда появится второй инструмент с явно другим доменом в том же слоте — без обязательной миграции всех id в v1.
Код wire-моделей (CodeNavigationMapSubgraphDocument и т.д.) не обязан сжиматься в одно имя без префикса: типы сцены/рендера — CodeNavigationMapSceneDrawing / CodeNavigationMapVisualTheme и т.д.; уточняющий смысл графа — через graph_kind и доменные поля.
Контракт MCP / JSON subgraph: добавить graph_kind (или аналог) в той же мажорной линии, что и расширение CockpitInstrumentDescriptor категорией — по отдельному решению, с миграцией агента.

Не цели (v1)¶

Полный enum категорий и типов графов в коде для всех режимов — только после стабилизации списка и одного реального сценария «два разных graph_kind в одном инструменте».
Слияние с DeckPrimitiveKind (0064): виды индикаторов и категория инструмента / тип графа — разные оси.

Отклонённые альтернативы¶

Только переименовать instrument_id под домен — ломает стабильность контракта и MCP без выигрыша в ортогональности слоту.
Полагаться только на комментарии в коде — недостаточно для агента и внешней документации.

История изменений¶

Дата Изменение

2026-04-22 продукт в UI — «Карта намерений»: подграф намерений и потока вокруг якоря (фрагмент кода / метод), не карта всего решения в духе Code Map в VS; в узком смысле совпадает с картой намерений кода. Ранее (2026-04-18): введена ось типов графов (graph_kind). 2026-05-14: ось graph_kind ортогональна оси происхождения связей — 0113 § оси. 2026-05-14: третья ось relation_kind — 0114.

ADR 0065: Категории инструментов и типы графов (ортогонально слоту и instrument_id)¶