ADR 0098: Семантика первична; документ и репозиторий — проекции (Semantic-First)¶
Статус: Proposed
Дата: 2026-04-24
Связанные ADR¶
| ADR | Роль |
|---|---|
| 0039 | навигация, semantic map, MCP subgraph |
| 0065 | Категории инструментов и типы графов (ортогонально слоту и instrument_id) |
| 0053 | Карта намерений и поток управления на PFD (control flow) |
| 0056 | карта намерений как продуктовый граф |
| 0067 | graph-backed surfaces |
| 0036 | CDS, канал кабины |
| 0094 | шина доставки |
| 0097 | CCU — свёртка в DTO канала |
| 0068 | полезная нагрузка vs проекция |
| 0079 | IDS |
| 0084 | текст в редакторе — источник правды для сессии правок; см. [§2.4](#adr0098-alignment-0084 |
| 0095 | три уровня Health, stratum |
| 0045 | события + проекции |
| 0009 | strangler |
| ## Резюме |
- Semantic-first: карта смысла первична; код/доки/git — проекции.
- Согласование с сессией правок (0084).
1. Контекст¶
В классическом «IDE как редактор файлов» первичен текст в буфере и дерево в репозитории: архитектура, зависимости и намерения выводятся из артефактов (C#, csproj, ADR, конфиги). Семантика — производная, часто несогласованная с тем, что человек имел в виду.
С другой стороны в Cascade уже закреплены куски смысловой ориентира: карта намерений (0053, 0056), graph-backed контракт (0067), навигация с упором на граф и MCP (0039). Шина, Health и CCU (0094, 0095, 0097) оперируют нормализованным смыслом после доставки, а не сырым «потоком без адреса».
Этот ADR формулирует северо-звезду: отказ от чисто документо-центричной модели в пользу semantic-first — без требования немедленно переписать весь продукт.
2. Решение (инварианты)¶
2.1 Первична семантическая карта (Semantic Map)¶
- Смысловая модель (намерения, границы, связи, состояния, пригодные для маршрутизации внимания и инструментов) рассматривается как первичный слой проектирования системы.
- Исходный код, текстовые документы (в т.ч. ADR, TOML, Markdown) и git-артефакты — проекции и упаковка: детерминированные или полудетерминированные представления, которые можно версионировать, диффить, отдавать в LSP, CI и агенту.
2.2 Канал кабины, IDS, векторные/графовые инструменты¶
- CDS-канал (0036), CCU (0097), IDS (0079), приборы и deck опираются на согласованный смысл (DTO, снимки,
stratumи т.д.), а не на «как догадался парсер из одного файла» как единственный источник. - Forward (редактор кода) остаётся мощным каналом ввода в эту карту, но не абсолютом всей правды о системе в долгую.
- Для semantic map CCU трактуется как слой входного снимка (нормализация источников, версия/свежесть, derived-поля), а не как место для графового UX. Traversal, layout, selection и интеракции остаются в graph-backed surface-контуре (0067, 0097 §6 — кандидаты CCU).
2.3 Coexistence: две истины там, где нужен strangler¶
- В переходных фазах допустимы двухслойные сценарии: «истина в git для релиза» + «истина в карте для кабины/агента», с явной политикой синхронизации и приоритета на конфликтах. Цель — свести к одной приоритетной семантике, а не вечно плодить разрыв.
2.4 Согласование с 0084¶
- 0084 фиксирует оперативный инвариант: при совместной работе один текст в буфере редактора — канон для применяемой правки (паритет человек/агент, присутствие, отсутствие «второй правды в чате»).
- 0098 не отменяет 0084: в момент правки текстовая проекция остаётся каноном ввода в этой сессии. Долгосрочно семантическая карта — канон архитектуры смысла; 0084 описывает как безопасно писать в проекцию, пока round-trip в/из карты не стал единым автоматом.
3. Не-цели (явно)¶
- Не «выкинуть git», не «не делать диффы», не «всё в одной базе без файлов».
- Не требовать полной round-trip семантика ↔ репо в v1 этого ADR: это направление и инварианты; миграция — strangler (см. 0009).
- Не дублировать здесь детальную онтологию полей Semantic Map: по мере введения — отдельные ADR, контракты, CASCOPE* при необходимости (как для других границ).
- Не отождествлять semantic-first с требованием заранее иметь полное семантическое или символьное дерево всего solution (materialized graph «до первого keypress»). Допустимы частичные снимки, ленивое наращивание карты (активный документ, подграф навигации/MCP, Roslyn/LSP по запросу), а CCU остаётся слоем входного снимка (0097), а не единственным хранилищем «всей правды» до готовности графа.
- Не смешивать приоритет смысла в архитектуре продукта (этот ADR) с полнотой инструментального графа компилятора: полнота Roslyn/компиляции подтягивается там, где нужна (анализ, навигация, рефакторинг), а не как глобальный предусловный шаг для любой функции IDE.
4. Последствия и риски¶
- Плюс: единая ось для CCU, каналов, агента и кабины — одна и та же адресуемая семантика, меньше «тихого рассхождения» файла и пикселя.
- Риск: сложность синхронизации проекции и карты; потребуется дисциплина, инструменты, тесты на согласованность.
- Риск детерминизма: генерация кода/доков из карты — контроль воспроизводимости и стабильный порядок при необходимости.
5. Связь с будущим ADR 0100 (намёк)¶
- Следующий круговой «центр» (субъектность агента, интегрированная среда смыслов, роль оператора) логично опирать на 0098 как на северо-звезду по первичности смысла; 0100 не обязан повторять этот ADR — он может сместить фокус на субъект/экосистему.
6. Отклонённая альтернатива (кратко)¶
- Полный документо-центризм как единственная правда: проще для v0, но не масштабируется на кокпит, агрегаты Health, графы намерений и согласованный UX (0063–0068) без постоянного «догоняющего» маппинга.
7. Статус внедрения¶
- Proposed — норматив намерения и границы; конкретные модули, хранилище карты и сроки — по follow-up ADR и дорожной карте.
8. FAQ¶
Нужно ли при semantic-first заранее простроить полное семантическое дерево solution?
Нет (см. §3 — два последних пункта). Инвариант ADR — роль смыслового слоя и согласованных снимков, а не обязательная априорная полнота графа. Практическая семантика может накапливаться инкрементально и по области (файл, проект, запрос к Language Service), вперемешку с файловой проекцией, пока действует strangler.