# Proposal ## Why Уровень «4» требует обосновать индекс истории запросом и `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях и показать, что пагинация не просматривает всю историю на каждую страницу (`README.md`). Наполнить такую историю и снять план должен нагрузочный стенд `bench/`, но он перенесён из лабы 1 и на коде лабы 2 не работает: - `run.py` поднимает только контейнер API, без PostgreSQL, Valkey и миграций; - сценарии k6 ходят с `X-User-Id`, которого API больше не принимает; - `inproc.py` собирает приложение над удалённым `MemoryStore`. Трек «5» №2 (`track2-query-plans`, `track2-backup-restore`) тоже стоит на этом стенде: сравнение индексов и стоимости записи — это метки `make bench`, а метки лабы 1 сюда не переносились. Поэтому сначала стенду нужны базовый замер на PostgreSQL и план запроса истории. ## What Changes - **Стенд на PostgreSQL.** `make bench` поднимает свой проект compose `mtusi-bench` из того же `docker-compose.yml` с override: - PostgreSQL и Valkey с теми же пинами и конфигурацией, что у рабочего стенда, со своими лимитами CPU и памяти; - миграции до наполнения; - API с прежними лимитами (1 CPU, 2 ГБ без swap); - без портов на хосте, без `.env` и `config.toml` рабочего стенда. Каждый размер истории начинается со свежего стенда: новый volume Postgres, новые Valkey и API. Рабочий стенд, его база и кэш не затрагиваются. - **Идентификация как в контракте.** Сценарии k6 регистрируют пользователей с паролем, входят по Basic и шлют Bearer. Срок сессии стенда больше длительности размера. - **Обслуживание БД перед замером.** После наполнения — `VACUUM (ANALYZE)` и `CHECKPOINT`: статистика планировщика и состояние таблицы одинаковы у всех меток. - **План запроса истории.** На каждом размере стенд снимает `EXPLAIN (ANALYZE, BUFFERS)` того запроса страницы истории, который выполняет само приложение (`auto_explain` в Postgres стенда), для первой, средней и последней страницы. Для сравнения снимается тот же запрос без использованного индекса, в транзакции, которая откатывается. Планы лежат в каталоге метки, сводка — в `summary.md`. - **Метрики хранилища.** Новые столбцы в конце таблиц: CPU контейнера Postgres на прогон и порцию наполнения. На размер — объём таблицы и индексов `messages` и байты на сообщение. В паспорт идут образы, версии, лимиты и настройки Postgres и Valkey, а также окружение API без секретов. Пароли стенда генерируются на прогон и никуда не пишутся. - **BREAKING (инструменты стенда):** удаляются `bench/inproc.py` и цель `make bench_inproc`. Разложение времени внутри процесса было инструментом трека 1 лабы 1. На PostgreSQL время запроса уходит в основном в БД, и его объясняет план запроса. `make bench_ab` снимает только стенд. - `make bench_compare` проверяет методику по лимитам всех контейнеров, образам и настройкам Postgres и Valkey. Таблица памяти показывает байты на сообщение в БД. - **Базовый замер** `baseline` полной матрицы (10k, 100k, 1M) на закоммиченном коде. По нему в `REPORT.md` пишутся раздел экспериментов и строка уровня 4 «индекс истории и EXPLAIN». ## Capabilities ### New Capabilities Нет. ### Modified Capabilities - `load-benchmark`: - изменённые требования: - стенд из API, PostgreSQL и Valkey с миграциями, лимитами и свежим volume на каждый размер; - идентификация Bearer в сценариях; - обслуживание БД после наполнения; - метрики Postgres; - паспорт со сведениями о хранилищах; - пометка прогона при падении хранилища; - проверка методики в сравнении меток; - прогоны «до/после» без разложения; - базовый замер на PostgreSQL; - новое требование: план запроса истории; - удалено требование: «Разложение стоимости запроса». ## Impact - **Код стенда:** - `bench/run.py` — стенд через compose, обслуживание БД, план, метрики, паспорт; - новый `bench/bench.compose.yml`, новый `bench/bench.env`; - `bench/k6/` — `lib.js`, `prepare.js`, сценарии, новый `explain.js`; - `bench/compare.py`, `bench/ab.py`; - удаляется `bench/inproc.py`. - **Makefile:** цели `bench*`, удаляется `bench_inproc`. - **Код приложения (`src/`), миграции, контракт и тесты** не меняются. - **Документация:** - `.gitignore` (строки `evidence/profile`); - `.claude/rules/bench.md` — раздел «Что доработать» закрывается, «Что не меняется между метками» пополняется параметрами хранилищ, раздел о диагностике удаляется; - `AGENTS.md` — команды, карта кода, переходное состояние; - `REPORT.md` — эксперименты, уровень 4, ограничения. - **Доказательства:** `evidence/bench/baseline/`, включая `explain-<размер>.txt`. - **Время хоста:** полная матрица на PostgreSQL — ориентировочно около часа (не измерено). Запуск — только с согласия пользователя и после подготовки хоста (`bench.md`, «Результаты»).