# Операции RAGRAF: выбор и границы

Справочник к навыку `ragraf-core`. Задача — выбирать операцию вместо чтения файлов
и знать, чего операция не показывает.

## 1. Полный набор

Фасад объявляет 38 операций вида `op_*` (`src/ragraf/facade.py`). Поверхность
инструментов агента — 40 инструментов с префиксом `ragraf_`
(`src/ragraf/mcp_server.py`). Разница не ошибка: инструментов больше, потому что
дополнительно выставлены приведение корпуса в актуальное состояние, выбор корпуса,
сводка телеметрии и состояние индекса, а одна операция фасада наружу не выставляется.

## 2. По типу вопроса

| Вопрос | Операция | Что показывает | Чего не показывает |
|---|---|---|---|
| Где определён символ | `symbol` | файл, строки, вид, подпись, разобранные параметры | тела функции |
| Где ещё используется | `references` | все места со ссылками | порядок выполнения |
| Кто вызывает | `callers` | вызывающие с доказательством | вызовы через строку или ссылку из данных |
| Что вызывает | `callees` | вызываемые | то же |
| Что затронет правка | `impact` | достижимые места по графу | конфликты веток и время выполнения |
| Структурный срез | `slice` | контекст без тел, только при полной сборке CPG | ничего при `capability=degraded` |
| Тело символа | `code` | точный текст | смысл вызывающих его мест |
| Карта репозитория | `repo_map` | файлы и объёмы в бюджете | связи между ними |
| Поиск по смыслу и словам | `search` | чанки с путями и строками | доказательство связи, это поиск, а не граф |
| Несколько строк сразу; где копии и какая рабочая | `search_multi` | все вхождения по каждому запросу, кодировка файла, группировка по семействам, роль файла (точка входа / активный / копия) с ссылкой `path:line` | смысл найденного кода |
| Какие файлы — копии друг друга | `duplicates` | группы «одно имя с номерами» и байт-идентичные, главный файл и доказательство его активности | намерение автора: копия может быть веткой развития |
| Точки входа | `entrypoints` | роуты, HTTP-обработчики, CLI-скрипты, endpoint'ы разметки; с `path` — достижим ли файл | порядок выполнения внутри обработчика |
| Что не подключено | `dead_code` | файлы и подпрограммы без входящих ссылок И вне достижимости, с причиной и списком оправданных (`refuted`) | «удалять»: это находка, а не решение |
| Что в таблице | `schema` | колонки, типы, PK/UNIQUE/AUTO_INCREMENT и генерируемые колонки из миграций | фактическое состояние живой базы |
| Кто читает или пишет таблицу | `table_usage` | места чтения и записи, текст запроса и способ вызова (`prepared`/прямой) | права доступа базы данных |
| Можно ли так записать | `write_check` | сверка плана записи со схемой до выполнения | типы значений и ограничения |
| Кто и почему получает право | `policy_trace` | ветви решения, точки отказа | фактическую роль пользователя |
| Что в ЖИВОЙ базе | `db_schema` | базы, таблицы, колонки, типы, индексы | схему из миграций |
| Устройство одной таблицы | `db_table` | колонки, индексы, ключи, скрытые поля | связь `derived` как факт |
| Связи таблицы | `db_relations` | `stated` (факт) и `derived` (вывод) раздельно | считать вывод структурой |
| Как выглядят данные | `db_sample` | сборный пример, домены значений | текущее состояние данных |
| Что изменилось в структуре | `db_drift` | изменения между ревизиями И расхождения «миграции ↔ живая база» | изменение данных |
| Чего нет в базе из используемого кодом | `db_cross` | `used_missing` (с источником имени, видом доступа и доказательством `path:line`), `unused` (с размером и признаком «база используется кодом»), `write_paths`, `case_mismatch` и **слепые зоны** `dynamic_sql` | что удалять: это находка, а не решение |
| Что изменилось между ревизиями | `diff` | файлы, символы, рёбра, а также регрессии: `callers_lost` (символ потерял всех вызывающих) и `writes_lost` (таблица перестала заполняться) | смысл изменения: «исчезло» при `capability=degraded` может означать «не было разобрано» |
| Что мы уже знаем о проекте | `note` / `notes` | короткие заметки с автором, временем и задачей | проверку: заметка — знание агента, а не факт индекса (`source: note`) |
| Можно ли искать по файлам, а не по индексу | `gate` | решение `allow`/`ask`/`deny`, правило, причина и ответ в формате хука DSH (отказ — код 2) | что гейт перепишет команду: он только разрешает, спрашивает или отказывает |
| Чем подтверждена работа по задаче | `task_stats` | готовый отчёт: обращения, факты, заменённое чтение, ответы по устаревшей ревизии, решения гейта, заметки | смысл фактов: это сводка по журналу, а не проверка кода |
| Классы оформления | `class_usage` | описано правило или нет, где применён | итоговый вид в браузере, каскад |
| Маршруты и обработчики | `routes` | HTTP-маршруты и их обработчики | поведение за обработчиком |
| Актуальность индекса | `freshness` | расхождение сумм, при необходимости реиндексация | качество самих фактов |
| Состояние индекса | `index_status` | ревизия, полнота разбора, покрытие, стадии | ничего сверх состояния |
| Журнал расхождений | `drift_report` | что изменилось после ревизии | тела изменений |
| Живое чтение | `live_read` | текущее содержимое файла с пометкой отличий | связи и граф |
| Статистика обращений | `usage` | вызовы, факты, экономия | смысл фактов |
| Реестр разработок | `catalog` | что заведено и с какими числами | содержимое индекса |

## 3. Правила выбора

1. **Навигация — операция, содержание — чтение.** «Где» отвечает операция; «как
   именно работает» требует чтения того фрагмента, который операция указала.
2. **План записи — всегда `write_check`.** Это единственная проверка, которая
   ловит несуществующую колонку до запуска кода.
3. **Решения о правах — всегда `policy_trace`.** Читать большой набор ветвей глазами
   бесполезно: неизвестное действие, оставшееся разрешённым по умолчанию, видно
   только статически.
4. **Перед правкой разметки — `class_usage`.** Отсутствие правила в стилях не даёт
   ошибки: страница отрисуется оформлением браузера и будет работать.
5. **`slice` только при полной сборке.** Иначе операция откажет с кодом 3 —
   это ожидаемое поведение, а не поломка.
6. **`live_read` — когда файл точно изменился после ревизии.** В остальных случаях
   достаточно индекса, и это дешевле.

## 4. Готовые рецепты (десять типовых вопросов)

| Вопрос агента | Вызов | Что считается ответом |
|---|---|---|
| Где выводится эта строка | `search` / `search_multi` (несколько строк через `|`) | пути и строки; в `search_multi` — кодировка файла и роль копии |
| Все списки расширений в проекте | `search_multi` с массивом запросов | все вхождения сразу, сгруппированные по семействам |
| Кто пишет в таблицу | `table_usage --mode write` | места записи, текст запроса, `via` (prepared или прямой вызов) |
| Какие ключи перевода есть | `search` по ключу, затем `references("tpl:<ключ>")` | шаблон и код в одном узле графа |
| Что затронет правка кнопки/функции | `impact` | достижимые места с разделением факт/вывод |
| Какие файлы — копии | `duplicates` | группы, главный файл, чем доказана активность |
| Какие файлы не подключены | `entrypoints`, затем `dead_code` | список с причиной и опровергнутыми кандидатами |
| Генерируемые колонки таблицы | `schema` (миграции), `db_schema` (живая база), `write_check` до записи | `generated_columns`, `generated_kind`, `columns_marks` |
| Поиск в CP1251 | `search_multi` | поле `encoding` у каждого хита подтверждает, что файл прочитан верно |
| Что изменилось после правок | `diff` (код), `drift_report` (расхождения), `db_drift` (схема) | ревизии, что добавилось и исчезло, кто потерял вызывающих, какая таблица перестала заполняться |
| Ответ, а не сырые хиты | любая из `search`, `search_multi`, `symbol`, `callers`, `impact` с `answer=true` | готовая фраза и ссылки `файл:строка` (≤ 1–2 КБ) вместо структурного JSON |
| «Что мы уже знаем» | `notes` (по задаче или подстроке), запись — `note` | заметки агента с автором и временем; `source: note` отличает их от фактов |

## 5. Как читать ответ

Обязательные поля конверта: `op` (операция), `index_rev` (какая ревизия отвечала),
`capability` (`full` или `degraded`), `drift` (есть ли незакрытые расхождения),
`provenance` (откуда данные: индекс, живое чтение или смешанно), `limits`,
`result`, `stale_warnings`, `found`. Дополнительно бывают `error` и `freshness`.

- `found=false` при коде 0 — это «не найдено», а не сбой.
- Непустые `stale_warnings` означают, что факт мог быть затронут правками после
  ревизии; такой факт нельзя выдавать за актуальный без пометки.
- `provenance=live` означает, что данные получены чтением файла, а не из индекса:
  их доказательство — сам файл, а не ревизия.

## 6. Чего в проекте нет

- Нет языка запросов к графу. Только фиксированные операции; текст, похожий на
  запрос к графу, отвергается с ошибкой вызова.
- Нет штатной команды проверки версий зависимостей, хотя `requirements.txt`
  её обещает.
- Нет единого раннера проверок: конфигурации pytest нет, файлы в каталоге `tests`
  запускаются по отдельности. Есть обёртка `python tools/check_all.py`
  (группа `core` — по умолчанию, `--list` показывает состав групп), но это запуск
  существующих скриптов, а не pytest.