Files
mtusi2026lab2/openspec/changes/track2-query-plans/tasks.md
T
2026-10-02 05:01:47 +03:00

8.4 KiB
Raw Blame History

Tasks

Как строить — design.md (дальше «решение N»), что должно получиться — дельта specs/load-benchmark/spec.md. Перед первым файлом слоя прочитать его правило: bench.md. Замер для отчёта снимается с закоммиченного кода (bench.md, «Измеренное состояние — commit»). Код приложения, миграции, контракт и student-tests/ не меняются. Рабочий стенд (mtusi-lab2) не трогать.

1. Профиль и фоновые чаты

  • 1.1 Поля Profile (решения 1, 4, 5):

    • background;
    • index_variants;
    • write_probe_rows = 20 000;
    • write_probe_repeats = 3.

    Значения full и quick — по таблице решения 1. Проверка: uv run python -c с импортом bench/run.py печатает asdict обоих профилей. Сумма фона у full — 100 000.

  • 1.2 prepare.js создаёт фоновые чаты по уровням из окружения (BACKGROUND), в фикстуре — bgChats (id, размер). Проверка: на коротком прогоне в fixture.json (снять до уборки) 62 фоновых чата quick. Все 201, без 401.

2. Наполнение по расписанию

  • 2.1 Функция расписания в run.py (решение 2) и запись .work/schedule.json; prefill.js берёт чат из расписания. Проверка:
    • для quick и N = 1000 у каждого чата в расписании ровно его размер;
    • первые 100 позиций содержат разные чаты, а не один подряд;
    • два вызова дают одинаковый результат.
  • 2.2 Порции, ETA и store_messages считают N + фон. Проверка распределения после обслуживания (GROUP BY chat_id): ровно N, размеры уровней и 0 у чата записи, иначе BenchError с размером. Проверка: короткий прогон проходит. Временно испорченное ожидание (правка, не коммитить) — отказ с размером и убранный стенд.

3. Планы по уровням и варианты

  • 3.1 plan_cursors.js и .work/plan_pages.json; explain.js читает страницы из файла и проверяет число строк (решение 3). Проверка: на коротком прогоне в журнале ровно столько записей messages, сколько страниц. Для quick это 3 + 3 + 1 + 1.

  • 3.2 Варианты в psql (решение 4):

    • app, generic, or-cursor, no-index и варианты профиля, по второму выполнению;
    • замена условия курсора на OR с отказом, если шаблон не найден;
    • сверка pg_indexes до и после.

    Проверка на коротком прогоне:

    • в explain-<размер>.txt у каждой страницы сравнения есть все варианты;
    • у covering узел Index Only Scan, у or-cursor есть Filter;
    • индексы messages после этапа те же.
  • 3.3 Раздел «Планы запроса истории» в summary.md: чат, уровень, размер чата, страница, позиция, вариант, узел, буферы, время, тип плана. Проверка: таблица короткого прогона заполнена, без — в узле у вариантов.

4. Стоимость записи

  • 4.1 Пробы записи в конце размера (решение 5):

    • конфигурации app, варианты профиля и none;
    • повторы со сдвигом порядка, CHECKPOINT перед вставкой, VACUUM после;
    • длинное сообщение в DO с NOTICE;
    • сверка числа строк и индексов после всех проб.

    Проверка на коротком прогоне:

    • у covering длинное сообщение не вставляется, текст ошибки записан;
    • у app и chat_only — вставляется;
    • count(*) и индексы после проб те же.
  • 4.2 meta.sizes[].write_cost и раздел «Стоимость записи по вариантам индекса» в summary.md: индекс МиБ и байт на сообщение, мкс на сообщение (медиана, min–max), WAL байт на сообщение, FPI на 1 000, длинное сообщение. Проверка: раздел короткого прогона заполнен.

5. Проверка и коммит кода

  • 5.1 make lint. Проверка: без замечаний.

  • 5.2 make bench_quick целиком. Проверка:

    • код 0, прогоны без пометок;
    • в сводке планы всех уровней с вариантами и таблица стоимости записи;
    • в каталоге метки нет токенов и паролей (grep по значениям из .work/ до уборки);
    • время прогона записано для оценки полной матрицы.
  • 5.3 .claude/rules/bench.md:

    • в «Что не меняется» — фоновые чаты, варианты индекса и пробы записи;
    • в «Как писать» — новые исключения границы чёрного ящика (решение 6).

    AGENTS.md: карта кода (plan_cursors.js) и оценка времени make bench. Проверка: grep -n "plan_cursors\|фонов" AGENTS.md .claude/rules/bench.md находит строки.

  • 5.4 Закоммитить код стенда и документацию (feat: compare history indexes on uneven chats in bench). Проверка: git status чистый.

6. Полная матрица и отчёт

  • 6.1 Записать в REPORT.md гипотезы P1–P6 и правило выбора (решение 7) до полной матрицы и закоммитить (docs: record track 2 query plan hypotheses). Проверка: commit гипотез раньше каталога evidence/bench/track2/.

  • 6.2 Подготовить хост (bench.md, «Результаты»: питание, swap, memory_pressure, нет посторонних контейнеров) и запустить make bench BENCH_LABEL=track2. Проверка:

    • код 0, status: complete, 54 прогона без пометок;
    • dirty: false, без host_warnings;
    • файлы explain-{10k,100k,500k}.txt;
    • в сводке стоимость записи по всем размерам.

    Предупреждение о хосте — переснять, а не игнорировать.

  • 6.3 Закоммитить evidence/bench/track2/ (docs: add track 2 query plan bench evidence). Проверка: git status чистый.

  • 6.4 REPORT.md, трек 2 «план запроса»:

    • набор данных;
    • таблица планов по уровням и вариантам (500k и выборочно 10k);
    • стоимость записи;
    • итог по P1–P6 как получился, решение по правилу выбора;
    • ограничения.

    Строка «Трек 5» в таблице доказательств — часть «план запроса». В AGENTS.md закрыть пункт трека 2 «план запроса» в «Переходном состоянии». Проверка: каждое число в тексте есть в summary.md или explain-*.txt метки track2, commit метки указан.

  • 6.5 Закоммитить отчёт (docs: report track 2 history index comparison). openspec validate track2-query-plans --strict проходит, git status чистый.