| 1 | # ADR 0113: HCI и Semantic Map — слой ориентации (не граф) |
| 2 | |
| 3 | **Статус:** Proposed |
| 4 | **Дата:** 2026-05-14 |
| 5 | **Обновлено:** 2026-05-14 — оси `graph_kind`, provenance, `relation_kind` ([0114](0114-graph-edge-relation-kind-taxonomy.md)). Подробности — [§ История](#adr0113-history). |
| 6 | |
| 7 | ## Связанные ADR |
| 8 | |
| 9 | | ADR | Роль | |
| 10 | |-----|------| |
| 11 | | [0106](0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md) | Граница Semantic Map / слой B; интеграция IDE | |
| 12 | | [0105](0105-hybrid-codebase-index-for-csharp-web.md) | Hybrid index, MCP | |
| 13 | | [0039](0039-workspace-navigation-affordances.md) | Карта как поверхность навигации | |
| 14 | | [0053](0053-semantic-map-control-flow-pfd.md) | Control flow на PFD | |
| 15 | | [0067](0067-graph-backed-surfaces-contract.md) | Контракт graph-backed поверхностей | |
| 16 | | [0065 §6](0065-instrument-categories-domain-taxonomy.md#adr0065-p6) | Ось `graph_kind` | |
| 17 | | [0114](0114-graph-edge-relation-kind-taxonomy.md) | Семантика `relation_kind` на ребре | |
| 18 | | [0097](0097-cockpit-compute-units-transport-to-channel-dto.md) | `SemanticMapInputSnapshot` в CCU | |
| 19 | |
| 20 | ## Проблема |
| 21 | |
| 22 | В **[0106](0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md)** в одном документе смешаны: подключение Core, оркестратор, свежесть, DataBus, MFD INDEX — и краткая формулировка роли HCI рядом с **Semantic Map**. Читатель нередко читает это как «HCI обогащает **граф** карты», хотя ADR уже противопоставляет слой B и канонический граф; явного **контракта ориентации** (что именно показываем, чего не делаем, какие DTO) в одном месте не хватает. |
| 23 | |
| 24 | --- |
| 25 | |
| 26 | ## Решение |
| 27 | |
| 28 | ### 1. Роль HCI относительно Semantic Map |
| 29 | |
| 30 | **Hybrid Codebase Index (HCI)** в связке с Semantic Map даёт только **слой ориентации по кодовой базе**: |
| 31 | |
| 32 | - топовые **текстовые** (FTS) и при включении — **векторные** попадания с путями, сниппетами и явным **`hit_kind`** ([0105](0105-hybrid-codebase-index-for-csharp-web.md)); |
| 33 | - **метаданные индекса** (готовность, версия формата, scope) как контекст доверия к строке ориентации; |
| 34 | - опционально в перспективе — **вход для declutter** подсветки карты (фильтрация «шума» в UI), **без** подмены символьной топологии графа. |
| 35 | |
| 36 | HCI **не** является источником рёбер CFG, **не** заменяет **Roslyn** для go-to-definition / символьной связности и **не** смешивает `hit_kind` с фактами графа. |
| 37 | |
| 38 | <a id="adr0113-axes"></a> |
| 39 | |
| 40 | ### 1a. Три ортогональные оси (`graph_kind`, `edge_provenance`, `relation_kind`) |
| 41 | |
| 42 | Чтобы не смешивать **какой граф рисуем**, **на чём основаны рёбра** и **что ребро означает**, держим разводку явно (третья ось — **[0114](0114-graph-edge-relation-kind-taxonomy.md)**): |
| 43 | |
| 44 | | Ось | Вопрос | Где зафиксировано | Примеры | |
| 45 | |-----|--------|-------------------|---------| |
| 46 | | **Тип / домен графа** (`graph_kind`) | Какой **смысловой** подграф в кабине: намерения кода, связанные файлы, дерево модулей Git, … | **[0065 §6](0065-instrument-categories-domain-taxonomy.md#adr0065-p6)** | `code_intent_code_navigation_map`, `related_files`, `repository_module_tree` | |
| 47 | | **Происхождение связей** (`edge_provenance`) | **Откуда** взята доказуемость «узел A связан с B»: символьная модель, эвристика workspace, полнотекст / vec по корпусу, цепочка из нескольких источников | **0113** + измерение в **[0067](0067-graph-backed-surfaces-contract.md#adr0067-dimensions)** | `symbolic_roslyn`, `workspace_navigation_msbuild`, `hci_fulltext`, `hci_vector`, `composite_hci_then_roslyn` | |
| 48 | | **Тип отношения** (`relation_kind`) | **Какое отношение** между сущностями мы показываем: наследует, ссылается на тип, partial peer, текстовое совпадение, … | **[0114](0114-graph-edge-relation-kind-taxonomy.md#adr0114-three-axes)** | `inherits`, `references_type`, `partial_peer`, `textual_name_match`, … | |
| 49 | |
| 50 | **Зачем:** один и тот же `graph_kind` (например карта намерений) может **визуально** соседствовать с данными разного происхождения: CFG/Roslyn — канон для control flow; HCI — быстрый **корпусный** слой («где в репо всплывает имя типа / фрагмент» → черновой **referenced-by по тексту**), затем уточнение через Roslyn. При этом **смысл** связи для UX и агента задаётся **`relation_kind`** (например `references_type` у Roslyn vs `textual_name_match` или `candidate_symbol_reference` у HCI), а не только `edge_provenance`. Отдельный инструмент «граф только из HCI» — по-прежнему отдельное решение и согласование с [0067](0067-graph-backed-surfaces-contract.md). |
| 51 | |
| 52 | ### 2. Продуктовый контур «карта + HCI» |
| 53 | |
| 54 | - **PFD / MFD:** краткая **строка ориентации** (или отдельный микро-канал), согласованная с тем же scope и `databasePath`, что оркестратор HCI ([0106](0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md)). |
| 55 | - **Следующий шаг для пользователя/агента:** из попадания HCI — осмысленные действия уровня **Roslyn** (definition, usages, diagnostics), как в эскизе **«Hybrid search → Roslyn точность»** в 0106 / дорожной карте 0105 — без объявления попадания HCI «истиной символа». Продуктовая линза **«быстро referenced-by по корпусу»** укладывается в **`hci_fulltext` / `hci_vector`** на оси provenance; символьный **referenced-by** — **`symbolic_roslyn`**; **смысл** связи при этом размечается **`relation_kind`** ([0114](0114-graph-edge-relation-kind-taxonomy.md)), чтобы не путать `references_type` с `textual_name_match`. |
| 56 | |
| 57 | ### 3. DTO и CCU (целевое состояние) |
| 58 | |
| 59 | Нормализованный вход для graph-backed поверхностей после стабилизации границы CCU — **`SemanticMapInputSnapshot`** ([0097](0097-cockpit-compute-units-transport-to-channel-dto.md)): состав полей (топ hits, версия индекса, ошибки запроса, флаги declutter) фиксируется отдельно при внедрении; **0113** задаёт семантику слоя, а не замену 0097. |
| 60 | |
| 61 | --- |
| 62 | |
| 63 | ## Не делаем (явные non-goals) |
| 64 | |
| 65 | - Не объявляем узлы/рёбра Semantic Map «проиндексированными HCI» без отдельного ADR и согласования с **[0067](0067-graph-backed-surfaces-contract.md)**. |
| 66 | - Не подменяем палитру **`t:`/`m:`** полным HCI без политики из **[0112](0112-command-palette-query-modes-strategy.md)** (там уже разведены ripgrep, FTS и semantic). |
| 67 | |
| 68 | --- |
| 69 | |
| 70 | ## Последствия |
| 71 | |
| 72 | - **[0106](0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md)** остаётся точкой входа по **интеграции HCI в CascadeIDE**; деталь контракта «карта ↔ HCI» для читателей и ревью — **0113**. |
| 73 | - Изменения в UI-строке ориентации или в `SemanticMapInputSnapshot` ссылаются на **0113** (и при необходимости на 0097), а не раздувают 0106. |
| 74 | |
| 75 | --- |
| 76 | |
| 77 | ## Rollout (эскиз) |
| 78 | |
| 79 | 1. Зафиксировать в коде/UX только **ориентацию** и ссылки на scope/HCI errors — без подмешивания в граф Roslyn. |
| 80 | 2. По готовности DTO — один PR с `SemanticMapInputSnapshot` + тесты границы CCU; обновить этот ADR до **Accepted · Implemented** для соответствующих пунктов. |
| 81 | |
| 82 | --- |
| 83 | |
| 84 | ## История изменений |
| 85 | |
| 86 | <a id="adr0113-history"></a> |
| 87 | |
| 88 | | Дата | Изменение | |
| 89 | |------|-----------| |
| 90 | | 2026-05-14 | оси **`graph_kind`**, **provenance** и **`relation_kind`** ([0114](0114-graph-edge-relation-kind-taxonomy.md)); линза «быстрый referenced-by по корпусу». | |
| 91 | |