# Tasks Как строить — `design.md` (дальше «решение N»), что должно получиться — дельта `specs/load-benchmark/spec.md`. Перед первым файлом слоя прочитать его правило: `bench.md`, `docker.md`, `run-modes.md`. Замер для отчёта снимается с закоммиченного кода. Коммит — только после подтверждения пользователя, `make bench` полной матрицы — только с его согласия (`bench.md`, «Измеренное состояние — commit», «Результаты»). Рабочий стенд (`mtusi-lab2`) не трогать ни на одном шаге. ## 1. Проба `auto_explain` - [x] 1.1 Проверить решение 5 до остального кода, на временном проекте compose `mtusi-bench` с override из задачи 2.1: - Postgres с `shared_preload_libraries=auto_explain`, миграции, API; - пара сообщений через HTTP; - включение `auto_explain` через `ALTER SYSTEM` + `pg_reload_conf()`, маркеры `RAISE LOG`; - один запрос истории уже открытым соединением пула. Проверка: в `docker logs` между маркерами есть запись `duration: … plan:` с `Query Text` запроса `messages`, `Query Parameters` и `Buffers`. После `ALTER SYSTEM RESET` новых записей нет. Стенд удалён (`down -v`). Если план не пишется — остановиться и обсудить с пользователем, а не менять способ молча. ## 2. Стенд на compose - [x] 2.1 `bench/bench.compose.yml` и `bench/bench.env` (решение 1): - имена `mtusi-bench-*` и сеть `mtusi-bench`; - `ports: !reset []`, у `api` и `migrate` — `volumes: !reset []`; - образ `mtusi-messenger:bench`; - у api — `healthcheck: disable`, у всех — `restart: "no"`; - лимиты и `AUTH__SESSION_TTL_SECONDS` из `${BENCH_*:?}`; - `command` Postgres с `auto_explain`; - в `bench.env` только несекретные имена и порты. Проверка: `docker compose -p mtusi-bench --env-file bench/bench.env -f docker-compose.yml -f bench/bench.compose.yml config` с переменными `BENCH_*` и паролями показывает лимиты, отсутствие `ports` и `config.toml`, сеть `mtusi-bench`. Без `BENCH_*` — ошибка `:?`. Рабочий `.env` на вывод не влияет: с `--env-file` у API `DATABASE__USER=bench`, без флага — значение из рабочего `.env` (сам `.env` не правится). - [x] 2.2 `bench/run.py`: класс `Stand` поверх compose (решения 1, 2): - одна функция вызова с `-p mtusi-bench`, обоими `-f` и собранным окружением: пароли из `secrets` на прогон, `BENCH_*` из новых полей `Profile`; - на размер: `down -v`, `up --wait postgres valkey`, `run --rm migrate`, `up --no-deps --no-build api`, ожидание готовности; - `check_free` по контейнерам проекта и `mtusi-bench-k6`; - предупреждение в вывод и `host_warnings`, если сумма лимитов памяти API, Postgres и Valkey больше памяти VM минус 1,5 ГиБ; - уборка в `finally` и по Ctrl+C. Проверка: `uv run python bench/run.py --profile quick --label quick-stand --sizes 1000` проходит размер, предупреждения о VM нет при лимитах 2 + 3 + 0,5 ГБ на VM 7,75 ГиБ. С `--memory 6g` (отладка) предупреждение есть. Во время прогона `docker ps` показывает `mtusi-bench-{postgres,valkey,api,k6}` без портов. После — нет контейнеров, сети и volume `mtusi-bench*`. Ctrl+C посреди наполнения — то же; `make run_docker` на 8080 всё время отвечает, его `StartedAt` не меняется. ## 3. Идентификация в k6 - [x] 3.1 `bench/k6/lib.js` и `prepare.js` (решение 3): - `authHeaders(token)` — Bearer; - регистрация с паролем из `crypto.randomBytes`, вход по Basic; - токены в `fixture.json`; - `createChat` и `sendMessage` с токеном. - [x] 3.2 `prefill.js`, `write.js`, `read.js`, `cursors.js`, `tail.js` — токен отправителя или читателя из фикстуры. Проверка задач 3.1–3.2: - короткий прогон проходит все этапы без 401 и `errors`; - в access-логе API нет `X-User-Id`-запросов; - `grep -r` по каталогу метки на токены и пароли из `.work/` (снять до уборки) ничего не находит; - `.work/` после прогона удалён. ## 4. Обслуживание БД и метрики хранилища - [x] 4.1 Обслуживание после наполнения (решение 4): `VACUUM (ANALYZE)` и `CHECKPOINT` через `docker exec … psql` от пользователя контейнера, строка этапа в выводе. Затем размеры таблицы и индексов `messages`, `count(*)`, `db_bytes_per_message` в `meta.sizes` и в сводку. Проверка: в выводе короткого прогона строки этапов идут по порядку наполнение → обслуживание → курсоры. В `meta.json` у каждого размера поля объёма заполнены, `count(*)` = N. - [x] 4.2 `db_cpu_cores` в конце `RUN_FIELDS` и `PREFILL_FIELDS`, `db` в строке прогона (решение 6). Проверка: в `runs.csv` и `prefill.csv` прежние столбцы на месте и в том же порядке, новый — последним и заполнен. - [x] 4.3 Сторож Postgres и Valkey: пометка `stand_down`, остановка матрицы с именем контейнера (решение 6). Проверка: `docker kill mtusi-bench-postgres` во время прогона чтения короткого профиля — прогон помечен, команда называет контейнер, код ≠ 0, стенд убран. ## 5. План запроса истории - [x] 5.1 `bench/k6/explain.js`: первая страница, середина и последний курсор пула, проверка 200 и полной страницы. - [x] 5.2 Этап «план» в `run.py` (решение 5): маркеры, включение и выключение `auto_explain`, разбор журнала, ровно три записи `messages` или `BenchError` с размером. Затем psql-пара с индексом и без в `BEGIN … ROLLBACK`, проверка индекса по `pg_indexes`, файл `explain-<размер>.txt`, раздел «Планы запроса истории» в `summary.md`. Проверка на коротком прогоне: - у каждого размера есть файл с тремя планами приложения и парой psql; - сводка показывает узел, буферы и время; - после этапа `\d messages` в Postgres стенда содержит `ix_messages_chat_id_created_at_id`; - при выключенном вызове `explain.js` (временная правка, не коммитить) команда падает с размером и убирает стенд. ## 6. Паспорт и сравнение меток - [x] 6.1 Паспорт (решение 7): - `stand.postgres`: образ, версия, настройки; - `stand.valkey`: образ, версия, `maxmemory`; - `limits` по трём контейнерам; - `app_env` без `PASSWORD`; - версии SQLAlchemy, asyncpg и redis. Проверка: в `meta.json` короткого прогона поля заполнены, `grep -i password` по каталогу метки находит только имена ключей, не значения. - [x] 6.2 `bench/compare.py` (решение 8): рекурсивная методика, таблица памяти с байтами в БД. Проверка на двух коротких метках: - метка сама с собой — нули во всех ячейках; - метка с `--memory 1g` против обычной — отказ с ключом `limits.api.memory` и обоими значениями; - ручная правка `stand.postgres.settings.shared_buffers` в копии `meta.json` — отказ с этим ключом. - [ ] 6.3 `bench/ab.py` без `bench_inproc`, проверка занятости — каталог метки стенда. Проверка: `uv run python bench/ab.py --before a --after b --reapply HEAD --dry-run` на чистом дереве печатает план без `bench_inproc`. Занятая метка и нечистое дерево — отказ до первого шага. ## 7. Удаление `inproc.py` и цели Makefile - [x] 7.1 Удалить `bench/inproc.py`, цель `bench_inproc` и строку `evidence/profile/quick-*.txt` в `.gitignore`. Обновить комментарии целей `bench*` в `Makefile`: заголовок без «трек 1», оценки времени — по факту задачи 8.2. Проверка: `grep -rn inproc` вне `openspec/changes/archive` и этого change пуст. `make -n bench bench_quick bench_compare bench_ab` печатает команды без ошибок. ## 8. Проверка стенда и коммит кода - [x] 8.1 `make lint`. Проверка: без замечаний. - [x] 8.2 `make bench_quick` целиком. Проверка: - код 0, все размеры и прогоны без пометок `errors`; - в сводке планы на 10k; - время прогона и скорость наполнения записаны для оценки полной матрицы. Если оценка заметно больше часа — сказать пользователю до baseline. - [ ] 8.3 Показать `git status` и `git diff --stat`, предложить сообщение, после подтверждения закоммитить код стенда (`feat: run load bench on PostgreSQL with query plans`). Проверка: `git status` чистый, на этом commit `run.py` пишет `dirty: false`. ## 9. Документация - [x] 9.1 `.claude/rules/bench.md`: - раздел «Что доработать под лабу 2» убрать; - в «Что не меняется между метками» — лимиты и образы Postgres и Valkey, настройки Postgres образа с `auto_explain`, окружение приложения из override, обслуживание после наполнения; - в «Как писать» — граница чёрного ящика для Postgres стенда (решение 4) вместо исключения `--child`; - раздел «Диагностика» удалить; - таблица инструментов без `inproc.py`. Проверка: правило не упоминает `MemoryStore`, `X-User-Id` и `bench_inproc`. - [x] 9.2 `AGENTS.md`: - строки `bench*` в таблице команд с оценками времени по факту; - карта кода: `bench.compose.yml`, `bench.env`, `explain.js`, без `inproc.py` и `evidence/profile/`; - в «Переходном состоянии» убрать пункт `bench/`. Проверка: `grep -n "inproc\|не доработан" AGENTS.md` пуст. ## 10. Базовый замер и отчёт - [ ] 10.1 Записать гипотезы H1–H4 (решение 10) в раздел экспериментов `REPORT.md` до запуска полной матрицы. Проверка: раздел есть в diff до появления `evidence/bench/baseline/`. - [ ] 10.2 Подготовить хост (питание, swap, `memory_pressure`, нет посторонних контейнеров) и с согласия пользователя запустить `make bench BENCH_LABEL=baseline`. Проверка: - код 0, `status: complete`, 54 прогона; - в паспорте `dirty: false`, без `host_warnings`; - файлы `explain-10k.txt`, `explain-100k.txt`, `explain-1M.txt` есть. Предупреждение о хосте — переснять, а не игнорировать. - [ ] 10.3 Показать изменения, после подтверждения закоммитить `evidence/bench/baseline/` (`docs: add PostgreSQL baseline bench evidence`). - [ ] 10.4 `REPORT.md`: - раздел экспериментов: стенд и лимиты трёх контейнеров, профиль, таблица результатов по ячейкам, ссылка на каталог, итог по H1–H4 как получилось; - в разделе архитектуры — обоснование индекса истории: запрос, планы первой, средней и последней страницы на 10k / 100k / 1M, сравнение без индекса, ссылки на `explain-*.txt`; - строка уровня 4 «индекс истории и EXPLAIN» в таблице доказательств вместо TODO; - ограничения: один большой чат, настройки Postgres по умолчанию, generic и custom plan, Docker Desktop; - убрать «EXPLAIN — следующий change» из «Ограничений» и «Переходного состояния» `AGENTS.md`. Проверка: каждое число в тексте есть в `summary.md`, `runs.csv` или `explain-*.txt` метки `baseline`. Commit метки указан. - [ ] 10.5 Показать изменения, после подтверждения закоммитить отчёт и документацию (`docs: report PostgreSQL baseline and history index plans`). `graphify update .`. Проверка: `git status` чистый, `openspec validate bench-postgres --strict` проходит.