# Tasks Как строить — `design.md` (дальше «решение N»), что должно получиться — дельты в `specs/`. Перед первым файлом слоя прочитать его правило: `settings.md`, `api-contract.md`, `api-layer.md`, `service-layer.md`, `repo-layer.md`, `service-tests.md`, `student-tests.md`, `logging.md`, `bench.md`, `docker.md`, `worker.md`. **Граница коммита.** Группы 1–7 — код, тесты, инструменты и правила: проверяются на рабочем дереве, агент apply не коммитит и в `evidence/` не пишет. Группа 8 — гипотезы в `REPORT.md` и коммит кода: основная сессия, **раньше любой метки замера**. Группа 9 — метка и отчёт на закоммиченном коде (`bench.md`, «Измеренное состояние — commit»). **Шага оператора нет.** Новых секретов нет, `config.toml` читается как есть. Руками `.env` не читать и не править. **Ожидаемо красное**, остальное разбирается по AGENTS.md: - между задачами 4.6 и 4.7 — сверка покрытия: «marker points to unknown scenario», sync раньше тестов дал бы обратное; - `test_exclusion_evidence_exists` — по `evidence/queue/baseline/summary.md`, пока метка не снята (группа 9); падать он должен только по этому файлу. Решения по ходу работы — design, новый раздел «Уточнения apply»; вопросы и решения без пользователя — `QUESTIONS.md`, `## track1-queue-overload`; дефект, найденный попутно, — `KNOWN_ISSUES.md`. Сервисы — только на портах и `self.uow` (`service-layer.md`), новый метод repo — порт, SQL, фейк и строка контракта. ## 1. Настройка и ответ 429 - [x] 1.1 `Uploads.max_unfinished_jobs: int = Field(default=250, ge=0)` с комментарием (`src/config/settings.py`), строка в `config_example.toml` (`[uploads]`), `uploads_max_unfinished_jobs` в записи «Started API» (`src/main.py`). Проверка: `uv run python -c "from src.config import settings; print(settings.uploads.max_unfinished_jobs)"` — 250; `UPLOADS__MAX_UNFINISHED_JOBS=-1` — ошибка проверки с именем поля. - [x] 1.2 Константа `UPLOAD_BACKLOG_RETRY_AFTER_SECONDS = 5` с обоснованием решения 2 (`src/utils/constants.py`), `UploadBacklogFull` (`src/core/exceptions/attachment.py`, реэкспорт), строки в `DOMAIN_ERRORS` и `RETRY_AFTER` (`src/api/errors.py`). Проверка: тест задачи 3.2 видит 429 `rate_limited` и `Retry-After: 5`; `make service_test`. ## 2. Счёт незавершённых - [x] 2.1 `count_unfinished(*, limit: int) -> int` по решению 3: порт с докстрингом-контрактом («сумма не меньше `limit` тогда и только тогда…»), `SqlAlchemyAttachmentJobRepository` — сумма трёх `SELECT count(*) FROM (SELECT … LIMIT :limit)` по условиям трёх частичных индексов, состояния `literal_execute`, один `execute`; фейк в `service-tests/fakes/repos.py`. Проверка: `service-tests/unit/test_architecture.py` зелёный; `EXPLAIN` на базе стенда — три Index Only Scan по `ix_attachment_jobs_outbox`, `ix_attachment_jobs_published`, `ix_attachment_jobs_lease`, без Seq Scan. - [x] 2.2 `check_count_unfinished` в `service-tests/repo_contract.py`: `queued` без отметки, с отметкой и со сроком, `processing` считаются; `succeeded` и `failed` — нет; решение «не меньше предела» верно при счётах ниже, на и выше предела, в том числе когда одна группа больше предела. Строка `count_unfinished` в `test_status_is_a_constant_in_statement`. Проверка: `make service_test`, `make service_test_db`. ## 3. Сервис загрузки - [x] 3.1 `AttachmentService.upload` по решению 3: 415, 413 и счёт — в первом блоке единицы работы, после `require_member`; при `max_unfinished_jobs == 0` запроса нет; `info` «Rejected attachment» `reason=backlog`, `unfinished`, `limit`; докстринг — новый порядок. `_store` и места — без изменений. Проверка: `make lint`; `driver.py lb-upload-timeouts` — без изменений (цепочка та же). - [x] 3.2 Быстрые тесты `service-tests/unit/test_attachment_service.py`: у предела — `UploadBacklogFull`, тело не читается, место не занято, строк и объектов нет; ниже предела и при 0 — загрузка идёт; при 0 метод не вызывается (`database.events`); порядок: посторонний, тип и `Content-Length` раньше предела. `settings.uploads.max_unfinished_jobs` — в `fixed_settings` `unit/conftest.py`. Проверка: `make service_test` — зелёный; временная регрессия (убрать проверку) делает новые тесты красными. ## 4. Проверки отказов - [x] 4.1 `student-tests/run_failures.py` по решению 13: `UPLOADS__MAX_UNFINISHED_JOBS=0` у четырёх прежних API, пятый `<проект>-api-backlog` с `BACKLOG_ENV` (`UPLOADS__MAX_UNFINISHED_JOBS=3`), `FAULT_BACKLOG_BASE_URL`, `FAULT_BACKLOG_ENV`, журнал при падении, уборка. `conftest.py`: фикстура `backlog_api`, отказ `pytest -m fault` без адреса. Проверка: `make failure_checks FAULT_ARGS='-k upload_slots_busy'` — поднимаются пять API, прежний тест зелёный. - [x] 4.2 `fault_hook.py`: действие `unfinished-jobs` (число заданий `queued` и `processing`); `test_failures.py`: `assert_backlog_stand`, помощник «дождаться нуля незавершённых» при работающем worker. Проверка: `make failure_checks FAULT_ARGS='-k backlog'` выводит число. - [x] 4.3 `test_backlog_limit` (fault) — сценарии `queue-overload` «Предел достигнут», «Порядок проверок у предела», «Остальной API у предела», «Загрузки снова принимаются»: worker остановлен, незавершённых ноль, `sample.png` до K: 202, следующая — 429, `assert_error(resp, 429)`, `Retry-After` 5, быстрее секунды, `attachment-ids` и `object-ids` те же; посторонний, 30 MiB по `Content-Length`, `text/plain` — 404, 413, 415; текст, история, метаданные и байты готового, сообщение со ссылкой на принятое, `/health/ready` — без ошибок; запуск worker, ноль незавершённых — 202 и все `ready`. Проверка: `make failure_checks FAULT_ARGS='-k test_backlog_limit'` зелёный; на временной регрессии (`DOMAIN_ERRORS` без строки, 400) — красный. - [x] 4.4 `test_backlog_ignores_finished`: `ready` и `failed` больше K, незавершённых ноль — 202. `test_backlog_counts_waiting_retry`: задание со сроком следующей попытки в будущем (`set-next-attempt`) считается: 429; срок снят — обрабатывается. `test_backlog_without_broker`: брокер и relay остановлены — 202 быстрее секунды до K, затем 429; после запуска брокера, relay и worker все `ready`. Проверка: `make failure_checks FAULT_ARGS='-k backlog'`. - [x] 4.5 `test_backlog_overshoot_bounded`: worker остановлен, 40 клиентов за `threading.Barrier` (больше мест и очереди реплики) по малому PNG: ответы 202 или 429, 5xx нет; принято не меньше K и не больше K + (`max_concurrent` + `max_waiting`) реплики; запуск worker — все `ready`. `test_backlog_off`: обычный API при K незавершённых и больше — 202. Проверка: `make failure_checks FAULT_ARGS='-k backlog'`. - [x] 4.6 Прочее: `images` и `contract.py` без изменений, если хватает; маркеры `@pytest.mark.spec("queue-overload", …)` на всех тестах; прежние тесты не правятся (решение 13). Проверка: `uv run pytest student-tests --collect-only -q -m fault` видит новые тесты; `git diff --stat student-tests/` — только новые тесты, `run_failures.py`, `conftest.py`, `fault_hook.py`, `spec_coverage.py`. - [x] 4.7 Сверка покрытия: `queue-overload` в `CAPABILITIES`; исключения девяти сценариев (нужны открытая нагрузка, счётчики и рестарт контейнера) со ссылкой `evidence/queue/baseline/summary.md` и командой `make bench_queue`; sync всех дельт в основные спеки (`/opsx:sync`): сверка читает только `openspec/specs/`. Проверка: `make student_test` — сверка: нет ни «no test», ни «marker points»; `test_exclusion_evidence_exists` называет только `evidence/queue/baseline/summary.md`. ## 5. Стенд `bench/` - [x] 5.1 `bench/make_images.py` по решению 5: stdlib и Pillow образа, зерно из аргумента, файлы `s`, `m`, `lj`, `lp`, JSON с размерами и SHA-256 на stdout; больше 10 485 760 байт или 40 млн пикселей — код 1. `Stand.make_images` — контейнер `mtusi-bench-images` на образе стенда, `--network none`, запись в `.work/`. Построение и зерно — решение 5. Проверка: дважды подряд — те же SHA-256; размеры в границах; `python -m src.worker.render` на каждом — код 0; `make_images` не импортирует `src`. - [x] 5.2 `bench/overload.py` (`--selftest`, только stdlib, без docker; не `queue.py`: затенил бы модуль stdlib) по решениям 5–8 и 11–12: план кругами `plan_cells`; разбор строк `q,…`, `qs,…`, `qv,…`, строк `jobs`, `mq`, `mp` и журналов контейнеров (записи — по `event`); окна, throughput, время до `ready`, очередь, пики; жизни контейнера: сброс счётчиков cgroup после перезапуска (решение 10); 429 по причинам из журнала реплик и моменты первого `busy` и первого `backlog`; строка `cells.csv` (`CELL_FIELDS`, в том числе `worker_restarts`) и посекундная `timeline.csv`; пометки решения 11; вердикты H1–H9 по таблице решения 12 («подтверждено», «нет», «нет данных»); правило рекомендации; `render_summary` и графики на `plots.Svg`. Новая метрика — столбец в конце. Проверка: `uv run python bench/overload.py --selftest` покрывает: план без повтора подряд, окна на границе, `updated_at` в микросекундах, потерянное и зависшее вложение, `oom`, перезапуск контейнера посреди ячейки (наибольшее и сумма по жизням), каждый вердикт в обе стороны и «нет данных», рекомендацию (2, 2) и другую. - [x] 5.3 `bench/k6/queue.js` по решению 6 (сценарии окон `constant-arrival-rate`, `timeUnit: "10s"`, VU заранее `queue_pre_vus` без прибавления, 429 не повторяется, строка `q,…` с `Retry-After`, порог итераций для сверки строк) и `bench/k6/queue_sweep.js` по решению 9 (`shared-iterations`, ids из `.work/`, строка `qs,…` на вложение, у выборки — SHA-256 оригинала и вариантов, строка `qv,…`). Идентификация — как в `uploads.js`. Проверка: `make bench_queue_quick` (задача 5.7): число строк `q,…` равно итерациям; выборка сошлась. - [x] 5.4 `bench/sampler.sh`, режим `queue` по решению 10; `bench/queue.compose.yml` (плагин брокера, `restart: unless-stopped` у worker), `bench/rabbitmq/enabled_plugins`, `bench/rabbitmq/91-bench.conf`. Режимы `list`, `scan`, `peak` и их разбор не меняются. Проверка: `uv run python bench/scaling.py --selftest`, `uv run python bench/resources.py --selftest`; на стенде строки `mq` идут раз в секунду, `missing` при остановленном брокере; значение совпадает с `rabbitmqctl list_queues`; порт 15692 не опубликован на хосте; `docker inspect` контейнера worker — политика `unless-stopped`, контейнеров других профилей — прежняя; разбор перезапуска — `--selftest` задачи 5.2 (завершение ядром случайно, по команде его не вызвать: `docker kill` демон считает ручной остановкой и не перезапускает). - [x] 5.5 `bench/run.py`: `Profile` (`queue_*`, `is_queue`), профили `queue` и `queue_quick` по решениям 5, 6, 8, 14; `Stand.start` при `is_queue` и `queue.compose.yml`; `leftovers`, `stop`, `vm_warnings`, `limits` — новые роли и `mtusi-bench-worker-2`, `mtusi-bench-images`; `compose kill` перед `down`; бюджет CPU — код 2 до стенда; каталог `evidence/queue/<метка>/`; `--resume` у `is_queue` (`resume_problems`, готовая строка `cells.csv`). Проверка: `make bench_uploads_quick` и `make bench_quick` — код 0, паспорт без изменений, кроме `.work/variant.compose.yml` у `uploads` (задача 5.8); `make bench_queue` на чужой занятой метке — код 2. - [x] 5.6 `Bench.run_queue` и `queue_cell`: разогрев, сэмплер, контрольный `background.js` (остановка SIGINT, `reconcile.line_problems`), `queue.js`, ожидание нуля незавершённых по строкам `jobs` со сроком, окно `after`, `queue_sweep.js`, чтение SQL, журналы (сверка «Started worker» с ячейкой — отказ при расхождении), строка `cells.csv`; блоки решения 8: пределы, приём (15/с, 45 с, причины 429 из журнала реплик), второй worker в конце `over`, KILL worker и рестарт брокера посреди `over`; сторож сэмплера; код команды по пометкам решения 11. Секреты в метку не попадают: `raw/` — только итоги k6, журналы не копируются. Проверка: `make bench_queue_quick`; в каталоге метки нет значений паролей и токенов (`meta.json` — через фильтр `SECRET_ENV_MARKS`, `raw/` — только итоги k6, журналы не копируются); прерывание Ctrl+C — стенд удалён, метка «незавершена»; `RESUME=1` — готовые ячейки не снимаются. - [x] 5.7 `Makefile`: `bench_queue [QUEUE_LABEL=...] [RESUME=1]`, `bench_queue_quick` (метка `quick-queue-<время>`), `$(KEEP_AWAKE)`, комментарии в стиле соседних; `.gitignore`: `evidence/queue/quick-*/`. Проверка: `make bench_queue_quick` — код 0 за ~11 мин, все вердикты посчитаны (на коротких окнах часть — «нет данных»), `git status` не видит каталога метки. - [x] 5.8 Профиль `uploads` по решению 13: `UPLOADS__MAX_UNFINISHED_JOBS=0` в override всех вариантов, `app_env` в паспорте. Проверка: `make bench_uploads_quick` — код 0, все 429 — от мест (`reason=busy`), ни одного `backlog`. ## 6. Правила и карта кода - [x] 6.1 `.claude/rules/`: `bench.md` — раздел «Профиль очереди», таблица инструментов, новая роль в «что не меняется», граница чёрного ящика; `worker.md` — правило concurrency и prefetch: `concurrency ≤ min(CPU + ожидание, (лимит − база) / пик)`, `prefetch = concurrency`, ограничения `prefetch / потолок` (30 мин, 300 с), завершение процесса 1 ядром при превышении лимита и перезапуск, ссылка на метку; `settings.md`, `api-contract.md` (таблица кодов, порядок проверок), `service-layer.md`, `repo-layer.md`, `logging.md`, `student-tests.md` (пятый API, hook, тесты), `run-modes.md` по необходимости. Проверка: `grep -n "max_unfinished_jobs\|UploadBacklogFull\|bench_queue" .claude/rules/*.md` находит правила; новых утверждений о числах метки нет: они — в `REPORT.md`. - [x] 6.2 `AGENTS.md`: статус лабы и change, инвариант предела (уровень 5), команды `make bench_queue`, `make bench_queue_quick`, карта кода: `bench/overload.py`, `make_images.py`, `queue.compose.yml`, `k6/queue*.js`, `evidence/queue/`, `count_unfinished`; в `KNOWN_ISSUES.md` теперь девять открытых записей (запись о памяти S3 добавлена стадией propose). Проверка: `graphify update .` без ошибок; команды из таблицы существуют (`make -n bench_queue_quick`). - [x] 6.3 `.claude/skills/run-mtusi-messenger/SKILL.md` — строка о `make bench_queue_quick` для защиты. `QUESTIONS.md` — решения apply. Проверка: `make check`; `make lint`. ## 7. Регресс на рабочем дереве - [x] 7.1 `make lint`, `make check`, `make validate PYTHON=.venv/bin/python`, `make service_test`, `make service_test_db`. Проверка: всё зелёное; `tests/`, `contracts/`, `README.md`, `lab.json` без изменений (`git status`). - [x] 7.2 Рабочий стенд на дереве: `make run_docker`, `make test`, `make student_test`; `make test_isolated`. Проверка: `PASS: lab5`; красное только `test_exclusion_evidence_exists` по метке группы 9. - [x] 7.3 Полный `make failure_checks` (рабочий стенд остановлен: `make stop`). Проверка: все проверки зелёные, число и время — в отчёт apply; `crash markers 0`. - [x] 7.4 `make bench_queue_quick`, `make bench_uploads_quick`, `make bench_rollout_quick`. Проверка: код 0 у всех, очередь поднимается и опускается на шкале, у `kill-worker` две попытки у взятых, нет `lost`, `stuck`, `duplicate`. ## 8. Гипотезы до меток (основная сессия) - [x] 8.1 `REPORT.md`, новый раздел «Очередь под перегрузкой»: гипотезы H1–H9 с порогами из решения 12, методика, определения решения 7, правило рекомендации. Числа метки — пока нет. Вопросы из `QUESTIONS.md` — в «Открытые вопросы преподавателю». Проверка: раздел называет порог у каждой гипотезы; `make lint`. - [x] 8.2 Коммит кода, правил и гипотез на ветке `feat/track1-queue-overload`. Проверка: `git status` чист; commit с гипотезами раньше первой метки в `git log`. ## 9. Метка и отчёт (после коммита, основная сессия) Снимать на закоммиченном коде, дерево чистое, рабочий стенд `make stop`, питание от сети, давления на память нет (`bench.md`). - [x] 9.1 `make bench_queue` (метка `baseline`, ~2 ч 10 мин). Прерывание — `RESUME=1`. Проверка: код 0; `meta.json`: `git.dirty` false, `host_state`, план 57 ячеек; `swapouts_delta` 0 или пометка разобрана: настоящая помеха — переснять под новой меткой. - [ ] 9.2 Коммит метки. `make student_test` на рабочем стенде после `make run_docker`. Проверка: `test_exclusion_evidence_exists` зелёный. - [ ] 9.3 `REPORT.md`, раздел «Очередь под перегрузкой»: таблицы из `summary.md` — throughput, очередь, p50, p95, p99 до `ready`, RSS, `memory.peak`, CPU и троттлинг по настройкам и классам; блоки; backpressure и ограничение принятой работы (таблица решения 4 с числами метки); восстановление; вывод по каждой гипотезе; компромисс latency и ресурсов; рекомендация и решение о значениях по умолчанию; обоснование предела по измеренному потолку; S3 как общий ресурс приёма и worker; завершение процесса 1 ядром; ограничения метода, в том числе память S3 на долго живущем стенде (`KNOWN_ISSUES.md`). «Трек 1 уровня 5» в таблице критериев; разделы «Сервисы», «Ограничения», «Следующие шаги», «Ответы на вопросы защиты» — по изменениям; шаг защиты. Проверка: числа совпадают с `summary.md` метки; `make lint`, `make check`, `openspec validate track1-queue-overload --strict`. - [ ] 9.4 Если правило решения 12 меняет значения по умолчанию — отдельный commit значения, `make bench_queue_quick`, строка в отчёте. Иначе — запись в отчёте, что значения оставлены, и почему. Проверка: `git log` называет шаг; `make test`. - [ ] 9.5 Коммит отчёта основной сессией. Проверка: `git status` чист, шапка отчёта называет commit метки.