| 1 | # ADR 0098: Семантика первична; документ и репозиторий — проекции (Semantic-First) |
| 2 | |
| 3 | **Статус:** Proposed |
| 4 | **Дата:** 2026-04-24 |
| 5 | |
| 6 | ## Связанные ADR |
| 7 | |
| 8 | | ADR | Роль | |
| 9 | |-----|------| |
| 10 | | [0039](0039-workspace-navigation-affordances.md) | навигация, **semantic map**, MCP subgraph | |
| 11 | | [0065](0065-instrument-categories-domain-taxonomy.md) | Категории инструментов и типы графов (ортогонально слоту и `instrument_id`) | |
| 12 | | [0053](0053-semantic-map-control-flow-pfd.md) | Карта намерений и поток управления на PFD (control flow) | |
| 13 | | [0056](0056-semantic-map-pipeline-adoption.md) | карта намерений как продуктовый граф | |
| 14 | | [0067](0067-graph-backed-surfaces-contract.md) | graph-backed surfaces | |
| 15 | | [0036](0036-cds-channel-compositor-surface-pipeline.md) | CDS, канал кабины | |
| 16 | | [0094](0094-ingestion-bus-afdx-analogy-and-threading-channels.md) | шина доставки | |
| 17 | | [0097](0097-cockpit-compute-units-transport-to-channel-dto.md) | CCU — свёртка в DTO канала | |
| 18 | | [0068](0068-deck-row-payload-and-presentation-projection.md) | полезная нагрузка vs проекция | |
| 19 | | [0079](0079-ide-display-system-ids-overlay-pipeline.md) | IDS | |
| 20 | | [0084](0084-agent-edits-editor-source-of-truth-presence-channel.md) | текст в редакторе — источник правды **для сессии правок**; см. [§2.4](#adr0098-alignment-0084 | |
| 21 | | [0095](0095-workspace-solution-ide-health-stratification.md) | три уровня Health, `stratum` | |
| 22 | | [0045](0045-agent-chat-persistence-event-log-and-projections.md) | события + проекции | |
| 23 | | [0009](0009-strangler-migration-and-exceptions.md) | strangler | |
| 24 | | [0155](0155-documentation-code-correspondence-and-architectural-drift.md) | сквозной каркас correspondence / drift; этот ADR = **L0** | |
| 25 | ## Резюме |
| 26 | |
| 27 | - **Semantic-first:** карта смысла первична; код/доки/git — проекции. |
| 28 | - Согласование с сессией правок ([0084](0084-agent-edits-editor-source-of-truth-presence-channel.md)). |
| 29 | |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | <a id="adr0098-context"></a> |
| 34 | |
| 35 | ## 1. Контекст |
| 36 | |
| 37 | В классическом «IDE как редактор файлов» **первичен текст в буфере и дерево в репозитории**: архитектура, зависимости и намерения выводятся **из** артефактов (C#, csproj, ADR, конфиги). Семантика — производная, часто несогласованная с тем, что человек *имел в виду*. |
| 38 | |
| 39 | С другой стороны в Cascade уже закреплены куски **смысловой** ориентира: **карта намерений** ([0053](0053-semantic-map-control-flow-pfd.md), [0056](0056-semantic-map-pipeline-adoption.md)), **graph-backed** контракт ([0067](0067-graph-backed-surfaces-contract.md)), навигация с упором на граф и MCP ([0039](0039-workspace-navigation-affordances.md)). Шина, Health и CCU ([0094](0094-ingestion-bus-afdx-analogy-and-threading-channels.md), [0095](0095-workspace-solution-ide-health-stratification.md), [0097](0097-cockpit-compute-units-transport-to-channel-dto.md)) оперируют **нормализованным смыслом** после доставки, а не сырым «потоком без адреса». |
| 40 | |
| 41 | Этот ADR формулирует **северо-звезду**: отказ от чисто **документо-центричной** модели в пользу **semantic-first** — без требования немедленно переписать весь продукт. |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | <a id="adr0098-decision"></a> |
| 46 | |
| 47 | ## 2. Решение (инварианты) |
| 48 | |
| 49 | <a id="adr0098-semantic-map"></a> |
| 50 | |
| 51 | ### 2.1 Первична семантическая карта (Semantic Map) |
| 52 | |
| 53 | - **Смысловая модель** (намерения, границы, связи, состояния, пригодные для маршрутизации внимания и инструментов) рассматривается как **первичный** слой проектирования системы. |
| 54 | - **Исходный код**, **текстовые документы** (в т.ч. ADR, TOML, Markdown) и **git-артефакты** — **проекции и упаковка**: детерминированные или полудетерминированные **представления**, которые можно версионировать, диффить, отдавать в LSP, CI и агенту. |
| 55 | |
| 56 | <a id="adr0098-cds-ids-instruments"></a> |
| 57 | |
| 58 | ### 2.2 Канал кабины, IDS, векторные/графовые инструменты |
| 59 | |
| 60 | - **CDS-канал** ([0036](0036-cds-channel-compositor-surface-pipeline.md)), **CCU** ([0097](0097-cockpit-compute-units-transport-to-channel-dto.md)), **IDS** ([0079](0079-ide-display-system-ids-overlay-pipeline.md)), приборы и deck опираются на **согласованный смысл** (DTO, снимки, `stratum` и т.д.), а не на «как догадался парсер из одного файла» как единственный источник. |
| 61 | - **Forward** (редактор кода) остаётся **мощным каналом ввода** в эту карту, но **не** абсолютом всей правды о системе в долгую. |
| 62 | - Для **semantic map** CCU трактуется как слой **входного снимка** (нормализация источников, версия/свежесть, derived-поля), а не как место для графового UX. Traversal, layout, selection и интеракции остаются в graph-backed surface-контуре ([0067](0067-graph-backed-surfaces-contract.md), [0097 §6 — кандидаты CCU](0097-cockpit-compute-units-transport-to-channel-dto.md#adr0097-candidates-next)). |
| 63 | |
| 64 | <a id="adr0098-coexistence"></a> |
| 65 | |
| 66 | ### 2.3 Coexistence: две истины там, где нужен strangler |
| 67 | |
| 68 | - В переходных фазах допустимы **двухслойные** сценарии: «истина в git для релиза» + «истина в карте для кабины/агента», с явной политикой **синхронизации** и приоритета на конфликтах. Цель — **свести** к одной приоритетной семантике, а не вечно плодить разрыв. |
| 69 | |
| 70 | <a id="adr0098-alignment-0084"></a> |
| 71 | |
| 72 | ### 2.4 Согласование с [0084](0084-agent-edits-editor-source-of-truth-presence-channel.md) |
| 73 | |
| 74 | - [0084](0084-agent-edits-editor-source-of-truth-presence-channel.md) фиксирует **оперативный** инвариант: при совместной работе **один текст в буфере редактора** — канон **для применяемой правки** (паритет человек/агент, присутствие, отсутствие «второй правды в чате»). |
| 75 | - **0098** не отменяет 0084: в момент правки **текстовая проекция** остаётся **каноном ввода** в этой сессии. Долгосрочно **семантическая карта** — канон **архитектуры смысла**; 0084 описывает **как** безопасно писать в проекцию, пока round-trip **в/из** карты не стал единым автоматом. |
| 76 | |
| 77 | --- |
| 78 | |
| 79 | <a id="adr0098-non-goals"></a> |
| 80 | |
| 81 | ## 3. Не-цели (явно) |
| 82 | |
| 83 | - **Не** «выкинуть git», **не** «не делать диффы», **не** «всё в одной базе без файлов». |
| 84 | - **Не** требовать полной **round-trip** семантика ↔ репо в v1 этого ADR: это **направление** и **инварианты**; миграция — strangler (см. [0009](0009-strangler-migration-and-exceptions.md)). |
| 85 | - **Не** дублировать здесь детальную **онтологию** полей Semantic Map: по мере введения — отдельные ADR, контракты, CASCOPE* при необходимости (как для других границ). |
| 86 | - **Не** отождествлять semantic-first с требованием **заранее** иметь **полное** семантическое или символьное **дерево всего solution** (materialized graph «до первого keypress»). Допустимы **частичные** снимки, **ленивое** наращивание карты (активный документ, подграф навигации/MCP, Roslyn/LSP **по запросу**), а **CCU** остаётся слоем **входного снимка** ([0097](0097-cockpit-compute-units-transport-to-channel-dto.md)), а не единственным хранилищем «всей правды» до готовности графа. |
| 87 | - **Не** смешивать **приоритет смысла в архитектуре продукта** (этот ADR) с **полнотой** инструментального графа компилятора: полнота Roslyn/компиляции **подтягивается там, где нужна** (анализ, навигация, рефакторинг), а не как **глобальный предусловный** шаг для любой функции IDE. |
| 88 | |
| 89 | --- |
| 90 | |
| 91 | <a id="adr0098-consequences"></a> |
| 92 | |
| 93 | ## 4. Последствия и риски |
| 94 | |
| 95 | - **Плюс:** единая ось для CCU, каналов, агента и кабины — **одна и та же** адресуемая семантика, меньше «тихого рассхождения» файла и пикселя. |
| 96 | - **Риск:** сложность **синхронизации** проекции и карты; потребуется дисциплина, инструменты, тесты на согласованность. |
| 97 | - **Риск детерминизма:** генерация кода/доков из карты — контроль воспроизводимости и стабильный порядок при необходимости. |
| 98 | |
| 99 | --- |
| 100 | |
| 101 | <a id="adr0098-link-0100"></a> |
| 102 | |
| 103 | ## 5. Связь с будущим ADR 0100 (намёк) |
| 104 | |
| 105 | - Следующий круговой **«центр»** (субъектность агента, интегрированная среда смыслов, роль оператора) логично опирать на **0098** как на **северо-звезду по первичности смысла**; 0100 не обязан повторять этот ADR — он может сместить фокус на **субъект/экосистему**. |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | <a id="adr0098-rejected"></a> |
| 110 | |
| 111 | ## 6. Отклонённая альтернатива (кратко) |
| 112 | |
| 113 | - **Полный документо-центризм** как единственная правда: проще для v0, но **не масштабируется** на кокпит, агрегаты Health, графы намерений и согласованный UX ([0063](0063-instrument-deck-named-composition-one-anchor.md)–[0068](0068-deck-row-payload-and-presentation-projection.md)) без постоянного «догоняющего» маппинга. |
| 114 | |
| 115 | --- |
| 116 | |
| 117 | <a id="adr0098-adoption-status"></a> |
| 118 | |
| 119 | ## 7. Статус внедрения |
| 120 | |
| 121 | - **Proposed** — норматив **намерения** и границы; конкретные модули, хранилище карты и сроки — по follow-up ADR и дорожной карте. |
| 122 | |
| 123 | --- |
| 124 | |
| 125 | <a id="adr0098-faq"></a> |
| 126 | |
| 127 | ## 8. FAQ |
| 128 | |
| 129 | **Нужно ли при semantic-first заранее простроить полное семантическое дерево solution?** |
| 130 | **Нет** ([см. §3 — два последних пункта](#adr0098-non-goals)). Инвариант ADR — **роль** смыслового слоя и согласованных снимков, а не обязательная **априорная полнота** графа. Практическая семантика может накапливаться **инкрементально** и **по области** (файл, проект, запрос к Language Service), вперемешку с файловой проекцией, пока действует strangler. |
| 131 | |