Files
mtusi2026lab5/openspec/changes/async-attachments/tasks.md
T
2026-10-31 04:06:09 +03:00

43 KiB
Raw Blame History

Tasks

Как строить — design.md (дальше «решение N»), что должно получиться — дельты в specs/. Перед первым файлом слоя прочитать его правило: service-layer.md, repo-layer.md, dto.md, infra.md, api-layer.md, api-contract.md, migrations.md, logging.md, settings.md, run-modes.md, docker.md, balancer.md, student-tests.md, bench.md.

Граница коммита. Группы 1–14 — код, тесты, инструменты и правила: проверяются на рабочем дереве, агент apply не коммитит и в evidence/ не пишет. Группа 15 — снятие evidence и REPORT.md: её запускает основная сессия после коммита групп 1–14, на закоммиченном коде (bench.md, «Измеренное состояние — commit»).

Шага оператора нет. make env_setup сам дописывает секреты брокера и ключи worker в существующий .env, значения не печатает. Руками .env не читать и не править.

Ожидаемо красное, остальное разбирается по AGENTS.md:

  • make test и сценарии вложений — до конца группы 9: API ещё не на 202 или worker нет;
  • между задачами 10.1 и 10.9 — сверка покрытия: «marker points to unknown scenario»; sync раньше тестов дал бы обратное, «no test and no exclusion»;
  • test_exclusion_evidence_exists — до группы 15, а по файлам старых исключений — до последнего шага всего прогона (QUESTIONS.md, «Перенос из лабы 4»). В группах 1–14 это не регрессия, но падать он должен только по missing_evidence.

Решения по ходу работы — design, «Уточнения apply»; вопросы и решения без пользователя — QUESTIONS.md, ## async-attachments; дефект, найденный попутно, — KNOWN_ISSUES.md.

1. Зависимости, настройки, общие типы

  • 1.1 Зависимости: aio-pika>=10.2.1,<11 в основной группе, pillow>=13,<14 из dev-группы в основную, uv lock.

    Проверка: uv lock --check; в uv.lock aio-pika 10.2.1, aiormq 7.2.4, pamqp 4.0.1, Pillow 13.0.0; uv tree --no-dev содержит обе.

  • 1.2 Настройки по решению 13 и дельте service-configuration:

    • классы Broker и Worker в src/config/settings.py, пароль — SecretStr, как у [s3];
    • graceful_shutdown_seconds не больше 9, сроки больше нуля, concurrency и max_attempts не меньше 1;
    • строки с комментариями единиц в config_example.toml.

    Проверка: uv run python -c "from src.config import settings; print(settings.worker)" — значения по умолчанию; BROKER__PUBLISH_TIMEOUT_SECONDS=0 и =abc, WORKER__CONCURRENCY=0, WORKER__MAX_ATTEMPTS=abc, WORKER__GRACEFUL_SHUTDOWN_SECONDS=10 — ошибка проверки настроек называет поле.

  • 1.3 Секреты и порты по решению 13:

    • .env.example: блок брокера (RABBITMQ_DEFAULT_USER, RABBITMQ_DEFAULT_PASS пустой, RABBITMQ_HOST, RABBITMQ_PORT, RABBITMQ_OUT_PORT, мосты BROKER__*), ключи S3_WORKER_*, шапка с сопоставлением имён skeleton BROKER_URL_FILE, WORKER_CONCURRENCY, JOB_MAX_ATTEMPTS, JOB_TIMEOUT_SECONDS, STAGING_RETENTION_SECONDS;
    • Makefile: ENV_SECRETS, ENV_FILLED.

    Проверка: подстановки рецепта env_setup дважды в поток, а не в файл: новые секреты непустые и различаются, сравнение по хэшу, значения не печатаются. make env_setup на рабочем каталоге печатает только имена дописанных переменных, повтор ничего не дописывает.

  • 1.4 Общие типы:

    • src/schemas/enums/attachment.py: AttachmentStatus — ещё queued, processing, failed; новые AttachmentJobState, AttachmentVariantName, AttachmentErrorCode, AttachmentJobReason;
    • src/utils/constants.py: ATTACHMENT_PIPELINE_VERSION, ATTACHMENT_JOB_TYPE, ATTACHMENT_JOB_SCHEMA_VERSION, ATTACHMENT_STAGING_PREFIX, THUMBNAIL_MAX_SIDE, THUMBNAIL_JPEG_QUALITY, имя очереди;
    • src/core/exceptions: AttachmentNotReady и AttachmentFailed (409 в DOMAIN_ERRORS), BrokerUnavailable(ServiceUnavailable).

    Проверка: make lint; uv run python -c "import src.api.errors".

2. Схема

  • 2.1 Модели по решению 1: новые колонки и CHECK Attachment, AttachmentJob, AttachmentVariant в src/infra/db/models/attachment.py.

    Проверка: make lint; совпадение со схемой — задача 2.2.

  • 2.2 Ревизия поверх 5c3e1f0a9b7d руками по решению 1 и migrations.md: первой строкой SET LOCAL lock_timeout = '2s', колонки, замена CHECK статуса и новый CHECK error_code с NOT VALID, две таблицы, downgrade.

    Проверка на временной базе (createdb в контейнере postgres, DATABASE__NAME в окружении, после — DROP DATABASE):

    • upgrade с нуля, uv run alembic check пуст, повтор ничего не меняет, downgrade -1, upgrade;
    • на базе со строками pending и ready: status прежний, pg_constraint.convalidated у обоих CHECK — false;
    • второе задание той же версии, второй вариант того же имени, error_code у не failed, failed без кода — нарушение ограничения; удаление вложения с заданием — нарушение внешнего ключа;
    • транзакция держит attachments дольше 2 с: миграция падает без изменений, повтор проходит.

3. DTO и repo

  • 3.1 DTO по dto.md: AttachmentFullDTO — staging_key, error_code, variants кортежем по умолчанию; AttachmentInListDTO.staging_key; AttachmentJobDTO, AttachmentVariantDTO; __init__.py.

    Проверка: make lint.

  • 3.2 src/core/repos/attachment.py по решениям 1–3 и repo-layer.md, одно выражение на функцию, updated_at через greatest:

    • _ATTACHMENT_COLUMNS, _STALE_COLUMNS, вставка со staging_key;
    • mark_ready заменяется на mark_queued с теми же условиями (pending, updated_at = created_at);
    • новые: возврат в pending, перевод в processing и обратно в queued, условная фиксация ready и failed с кодом.

    Проверка: make lint; поведение — группы 6–8 и 10.

  • 3.3 src/core/repos/attachment_job.py по решениям 1, 3, 7: вставка, чтение с FOR UPDATE, чтение по вложению, начало попытки, возврат в queued с условием своей попытки, завершение, отметка published_at, условное удаление (state = 'queued' AND attempt = 0).

    Проверка: make lint; поведение — группы 6–7 и 10.

  • 3.4 src/core/repos/attachment_variant.py: вставка ON CONFLICT DO NOTHING по ключу эффекта, варианты вложения, один вариант по имени.

    Проверка: make lint; поведение — группы 6–7 и 10.

  • 3.5 src/core/repos/attachment_object.py по решению 1: staging_key, variant_key, parse_variant_key; запись и чтение остаются по ключу.

    Проверка: разовый вызов parse_variant_key: свой id и v1-thumbnail — id, верхний регистр, версия 0, неизвестное имя, original, чужой префикс — None; make lint.

4. Брокер: сервис и клиент

  • 4.1 Сервис rabbitmq по решению 4 и docker.md:

    • docker-compose.yml: образ с тегом и digest из решения 4, hostname, volume, порт, алиас, healthcheck, лимиты, stop_grace_period, якорь x-broker-env;
    • infra/rabbitmq/rabbitmq.conf, монтирование read-only длинной записью;
    • цели start_broker, stop_broker.

    Проверка на рабочем стенде:

    • docker buildx imagetools inspect rabbitmq:4.3.7 — тот же digest;
    • make start_broker — healthy; rabbitmqctl -q status --formatter json — предел памяти 400 МиБ; docker port — только AMQP на 127.0.0.1;
    • docker compose stop rabbitmq — код 0 раньше срока;
    • docker compose up -d --force-recreate rabbitmq — healthy, имя узла rabbit@rabbitmq прежнее; очередь с сообщениями после пересоздания — тест test_broker_recreated.
  • 4.2 Клиент по решению 5: src/infra/broker/client.py (JobPublisher, JobConsumer, имя очереди из namespace, сброс соединения после любой ошибки), aio_pika и aiormq на WARNING в src/infra/logger.py, записи журнала по решению 18.

    Проверка — разовый скрипт в scratchpad против брокера стенда:

    • публикация с подтверждением, очередь durable, сообщение persistent;
    • нет маршрута при удалённой очереди и docker compose stop rabbitmq — BrokerUnavailable быстрее срока; docker pause — не позже срока с запасом;
    • после возврата брокера следующая публикация проходит на том же объекте издателя;
    • потребитель получает сообщение, prefetch_count соблюдён, обрыв завершает его итератор;
    • значения пароля в выводе нет (сравнение с .env без печати).
  • 4.3 Глобал API по решению 5: src/infra/broker/instance.py, src/api/dependencies.py, закрытие в lifespan src/main.py, поля брокера в «Started API».

    Проверка: make lint; процесс API стартует и отвечает /health/ready при остановленном брокере; в «Started API» адрес, очередь и срок, пароля нет.

5. Thumbnail

  • 5.1 src/utils/thumbnail.py по решению 8.

    Проверка — разовый скрипт в scratchpad с генераторами student-tests/images.py:

    • 320 × 200 → 256 × 160, 100 × 50 и 256 × 256 без изменений, 1000 × 601 → 256 × 153, 601 × 1000 → 153 × 256, 5000 × 10 → 256 × 1, 10 × 5000 → 1 × 256;
    • orientation 1–8: размеры и пиксели как у ImageOps.exif_transpose;
    • alpha, палитра с tRNS, LA — белый на месте прозрачности;
    • все png_variants() и jpeg_variants() — настоящий JPEG; точность SOF 12 — InvalidImage;
    • пик RSS PNG RGBA 8000 × 5000 в контейнере образа с лимитом 1 ГБ — не больше ~350 МиБ.

    grep -rn "PIL" src — только этот модуль; его импортирует только сервис обработки.

6. API

  • 6.1 AttachmentService по решению 3: издатель в конструкторе и зависимости; _store пишет в staging; _mark_ready → перевод в queued с заданием и той же компенсацией; публикация, отметка published_at, транзакция отмены; места загрузки держатся до ответа; записи журнала по решению 18, filename в них нет.

    Проверка: make lint; один PNG против консольного API и брокера стенда — 202, строка queued, объект только в staging, одно сообщение; сбои — тесты группы 10.

  • 6.2 Чтение по решению 9: pending — 404, остальные — 200, варианты только у ready; open_content(variant=…): статус не ready — AttachmentNotReady без обращения к S3, нет варианта — 404, нет объекта варианта или другой размер — 500 с записью error; ветки оригинала и lost_at прежние.

    Проверка: make lint; поведение — тесты группы 10.

  • 6.3 MessageService по решению 9: неизвестное, чужое и pending — 404 до ключа; failed — после захвата ключа: новый ключ — откат и AttachmentFailed, занятый — прежняя ветка повтора.

    Проверка: make lint; поведение — тесты группы 10, в том числе «Повтор после failed вложения».

  • 6.4 HTTP по решению 9: status_code=202, variant как Literal четырёх значений, модель Attachment с status, variants, error_code, модель варианта, DOMAIN_ERRORS, версия 1.5.0 в create_app.

    Проверка: /openapi.json запущенного API против contracts/openapi.json: поля и обязательность Attachment и Variant, перечисления, код успеха загрузки, info.version.

7. Worker

  • 7.1 Сообщение задания: pydantic-модель src/schemas/jobs/attachment.py (решение 7), сборка тела из строки задания и номера попытки. Правило dto.md дополняется в задаче 13.1.

    Проверка: тело по contracts/jobs.schema.json (jsonschema dev-группы); лишнее поле, чужая schema_version, attempt 0, неверный traceparent — ошибка разбора; traceparent и tracestate по схеме проходят.

  • 7.2 AttachmentProcessingService в src/core/services/attachment_processing.py по решениям 2 и 7: разбор, таблица claim, обработка под сроком, фиксация ready с вариантом одной транзакцией, временные и постоянные ошибки, недоступный PostgreSQL, исход ACK или REQUEUE; порядок блокировок — задание, затем вложение; журнал по дельте service-logging.

    Проверка: make lint; поведение — тесты группы 10.

  • 7.3 Процесс src/worker/ по решению 6: __main__.py (early_stop.install("worker"), «Invalid worker settings», код 2, os._exit), main.py (сигналы, свои engine, S3 и клиенты брокера, цикл переподключения, ограниченная конкуренция, контекст request_id, остановка в срок, «Started worker» и «Stopped worker»).

    Проверка без стенда: WORKER__CONCURRENCY=0 uv run python -m src.worker — код 2, запись называет поле без значений; make lint. На стенде — задача 9.6.

8. Уборщик и сверка

  • 8.1 Уборщик по решению 11: staging_key в выборках; remove_stale_pending удаляет staging_key or object_key, запись журнала называет удалённый ключ.

    Проверка: make lint; разовый python -m src.cleaner --once на стенде после 9.6 — код 0; поведение — тесты группы 10. Профиль reconcile со строками прежнего вида — задача 11.2.

  • 8.2 Сверка по решению 11: разбор ключа варианта в _list_objects, id вариантов в выборке страницы, ветка варианта в _classify_object (строка есть — пропуск, нет — объект без метаданных, свежий — свежий); находка зависшей загрузки называет ключ staging; is_own_key по-прежнему смотрит object_key.

    Проверка: make lint; на стенде обе стратегии без --apply не называют объекты вариантов; поведение — тесты группы 10.

9. Стенд

  • 9.1 docker-compose.yml по решениям 6 и 10: сервис worker, x-broker-env и depends_on брокера у api, ключи S3_WORKER_* у s3-bootstrap.

    Проверка: docker compose --env-file .env config --quiet; docker compose config — секреты по сервисам по дельте container-run: пароль брокера только у rabbitmq, api, worker, ключи worker только у s3-bootstrap и worker, у worker нет пароля Valkey и ключей API и уборщика.

  • 9.2 infra/s3/bootstrap.sh по решению 12: apply_user worker worker-objects, политика, ожидание ключа, проверки apply и check, отказ на удаление и список; driver.py s3-check — строки ключа worker.

    Проверка на временном проекте compose (-p своё имя, --env-file — файл в scratchpad, порты свободные; без down -v: созданные volumes перечислить в отчёте и оставить основной сессии): первый запуск — «user worker created»; повтор дважды — «exists», код 0; новый секрет — ключ пересоздан, прежний отклонён; все запреты сценария «Запрещённые операции worker» — 403.

  • 9.3 Makefile: run_worker (рецепт с @, ключи worker в окружение процесса), run_dev и test_isolated зависят от start_broker, текст wipe_data называет volume брокера, комментарии стенда.

    Проверка: make run_worker не печатает значения ключей; make run_dev и make run_worker — загрузка становится ready, «Started worker» называет адрес 127.0.0.1:$RABBITMQ_OUT_PORT.

  • 9.4 scripts/restart.sh по решению 14 (брокер в restart и up --wait --no-recreate), шапка; комментарии scripts/rolling-update.sh и infra/haproxy/haproxy.cfg — 29 с и 76 с.

    Проверка: scripts/restart.sh на стенде — код 0 не дольше 90 с, у брокера и реплик те же ID и новый StartedAt, у worker и уборщика прежний StartedAt, RestartCount 0; haproxy -c закреплённым образом.

  • 9.5 CI по решению 14: .github/ci/compose.yml (rabbitmq, worker), .github/ci/stand-env.sh (CI_RABBITMQ_CONF); шаги workflow не меняются.

    Проверка: COMPOSE_FILE=docker-compose.yml:.github/ci/compose.yml, CI_IMAGE_TAG и . .github/ci/stand-env.sh, docker compose config --quiet — без ошибок; в docker compose config у rabbitmq и worker нет ports и bind mount, у rabbitmq есть volume данных, а образ worker — тег прогона.

  • 9.6 Рабочий стенд на рабочем дереве: make run_docker.

    Проверка:

    • docker compose ps — две реплики, уборщик, worker, брокер и S3 в рабочем состоянии, bootstrap с кодом 0;
    • make test — PASS: lab5;
    • журнал worker: «Started worker» со всеми значениями, затем запись о готовом вложении; filename smoke в журнале нет;
    • docker compose stop worker — быстрее 10 с, код 0, «Stopped worker»; docker compose up -d --no-deps worker и сразу stop — код 0 и «Stopped worker before startup»;
    • /proc/1/cmdline контейнера worker — python -m src.worker, проверки здоровья нет; в /proc/1/maps реплики API нет _imaging;
    • make s3_check — код 0, строки ключа worker на месте.

10. Тесты

  • 10.1 Клиент и генераторы по решению 15: api_client.py (upload — 202 и снимок queued, wait_attachment, upload_ready, скачивание варианта), contract.py (код 202, схема Variant, assert_content для варианта), images.py (JPEG с точностью 12 и с EXIF orientation, половины цветов, PNG с прозрачной половиной и палитрой с tRNS, большой PNG RGBA).

    Проверка: make lint; wait_attachment при остановленном worker падает и называет queued (сценарий «Worker не работает»).

  • 10.2 Прежние сценарии вложений во всех модулях обычного набора (test_attachments.py, test_messages.py, test_idempotency.py, test_rubric.py, test_data_storage.py, test_api_conventions.py, test_load_balancing.py и другие, где есть загрузка): 202 и ожидание ready там, где нужны байты или итог; метаданные сравниваются по полям оригинала и отдельно по полям состояния; проверки не ослабляются и не пропускаются (спек student-tests, «Готовность вложения в тестах»).

    Проверка: make student_test через LB — прежние сценарии зелёные, красное только из шапки.

  • 10.3 Новый модуль test_attachment_processing.py и новые тесты обычного набора по таблице «Покрытие сценариев» design: test_attachment_becomes_ready, test_thumbnail_*, test_download_thumbnail, test_missing_variant, test_variant_outsider, test_message_with_failed_attachment, test_accepted_attachment_visible_on_other_replica; маркеры spec дословно по сценариям дельт.

    Проверка: uv run pytest student-tests/test_attachment_processing.py с BASE_URL стенда; thumbnail скачан и его настоящие размеры, sha256 и size_bytes сверены с метаданными варианта.

  • 10.4 Hook student-tests/fault_hook.py по решению 15 и дельте student-tests: действия брокера и worker, worker-state, queue-state, peek-job, publish-job, delete-queue, job, staging-ids, variant-object-count; put-object и delete-object под префиксами вложений и staging; режимы fail-attachments на queued и → ready; docstring. Ключи S3 и пароль брокера hook не получает и не печатает.

    Проверка: разбор fs.tree на образце (original и v1-thumbnail в одном каталоге, staging отдельно); hook отказывается работать с проектом рабочего стенда; поведение действий — тесты 10.6 и 10.7.

  • 10.5 Стенд отказов по решению 15: failures.compose.yml (rabbitmq без порта, worker с короткими сроками, restart: "no"), run_failures.py (брокер в up --wait, worker после bootstrap, FAULT_WORKER_*, журнал worker при падении, строка start worker, уборка), docstring.

    Проверка: make failure_checks FAULT_ARGS='-k health' — код 0, строка worker в выводе, стенд и volumes удалены; -k no_such_test — ненулевой код, журналы API, уборщика и worker напечатаны, стенд удалён.

  • 10.6 Прежние проверки отказов test_failures.py по решению 15 и дельтам attachments и storage-consistency:

    • upload_ready и множества id там, где нужен готовый объект;
    • test_ready_failure_compensated → test_queued_failure_compensated, test_ready_commit_outcome_unknown → test_queued_commit_outcome_unknown; test_killed_between_put_and_ready, test_upload_outlives_grace, test_cleaner_failure_after_object_delete — на queued и staging-ids;
    • тесты сверки: зависшая загрузка — объект в staging, готовые вложения — с объектами вариантов.

    Проверка: make failure_checks FAULT_ARGS='-k "attachment or object_storage or cleaner or reconcile or upload"' — код 0.

  • 10.7 Новые проверки отказов по таблице «Покрытие сценариев» design: сценарии attachment-processing, message-broker, messages, idempotency, health, attachments, storage-consistency, а также test_worker_stop_during_processing (спек graceful-shutdown в докстринге). Отказы — в with outage(...), worker запускается в finally, триггеры снимаются в finally. Сообщение проверяется по contracts/jobs.schema.json.

    Проверка: полный make failure_checks — код 0, сводка журнала PostgreSQL без признаков аварии, стенд удалён, у контейнеров рабочего стенда прежний StartedAt; время прогона — в design, «Уточнения apply».

  • 10.8 make test_isolated по решению 15: run_isolated.py — контейнер <проект>-test-worker с той же подменой базы, журналы обоих контейнеров, удаление очереди в начале и в конце, KEEP_TEST_DB печатает очередь; проверка имени очереди — как у префикса, иначе код 2.

    Проверка: make test_isolated при работающем стенде — код 0; после него нет контейнеров, базы, объектов и очереди временной базы, а сообщения и счётчики рабочей очереди и StartedAt рабочего стенда прежние; прерывание Ctrl+C — уборка выполнена; KEEP_TEST_DB=1 — остаётся и печатается.

  • 10.9 Сверка покрытия:

    • attachment-processing и message-broker в CAPABILITIES, записи EXCLUDED с причинами и способом проверки по design (message-broker «Сервис брокера запущен», «Предел памяти брокера», «Остановка брокера», «Очереди разных баз разделены», data-storage «Ограничения обработки в схеме»);
    • sync всех 18 дельт в основные спеки (/opsx:sync): сверка читает только openspec/specs/.

    Проверка: openspec validate --specs; make student_test — сверка без «no test and no exclusion» и «unknown scenario», красное только missing_evidence; итог называет число сценариев проверок отказов с новыми.

  • 10.10 Тесты ловят нарушение: временные регрессии, каждая откатывается и не попадает в рабочее дерево:

    • ack до фиксации результата → test_worker_killed_during_processing красный;
    • публикация без подтверждения → test_upload_with_broker_stopped или test_upload_with_broker_paused красный;
    • очередь не durable → test_broker_restart_keeps_job красный;
    • Image.thumbnail вместо своего расчёта → test_thumbnail_rounding красный;
    • failed до захвата ключа → test_replay_after_attachment_failed красный;
    • сверка без ветки варианта → test_reconcile_variant_objects красный.

    Проверка: итог по каждой регрессии — в design, «Уточнения apply»; git diff после откатов совпадает с кодом до них.

11. bench/

  • 11.1 Стенд по решению 16: bench.compose.yml (rabbitmq, worker, лимиты), bench.env, compose_env (пароль брокера, ключи worker), поля Profile, SECRET_ENV_MARKS покрывает новые имена, старт брокера в профиле загрузок, новый volume брокера на прогон, остатки и уборка.

    Проверка: uv run python bench/uploads.py --selftest; make bench_quick — код 0, брокер и worker не запущены, stand.app_env без секретов.

  • 11.2 Профиль загрузок по решению 16: k6/uploads.js, uploads.py (s201 — код успеха варианта, столбец success_code в конце, раздел паспорта), run.py, тексты сводки.

    Проверка: make bench_uploads_quick — код 0, успешные загрузки — 202, пик памяти реплики и 429 — в тех же границах, что у прежних сценариев спека; make bench_reconcile_quick — код 0, зависшие строки прежнего вида убраны: сверка моделей сошлась. Метки quick-* в git не идут.

12. Драйвер скилла run-mtusi-messenger

  • 12.1 Прежние команды по решению 17: start поднимает брокер и worker, upload, download, flow, attachment-failover, attachment-storage, upload-consistency, reconcile-*, s3-idle — 202 и ожидание ready; заглушка реплики lb-upload-timeouts — 202; attachment-storage — ещё пробы ограничений обработки в откатываемой транзакции.

    Проверка: каждая из этих команд на рабочем стенде — код 0; driver.py lb-upload-timeouts — пять случаев с 202.

  • 12.2 Новые команды по решению 17: defense-scenario, broker-check [--require-test-queue], worker-process; раздел в SKILL.md: шаги, что проверяется, коды выхода, gotchas.

    Проверка:

    • defense-scenario на рабочем стенде — код 0, вывод с шагами, кодами, id и StartedAt до и после, токенов и секретов нет;
    • прерывание сигналом посреди сценария — worker запущен, код ненулевой;
    • broker-check, worker-process — код 0; отрицательная: broker-check --require-test-queue без прогона на временной базе — код 1;
    • ruff format --check драйвера.

13. Правила и карта кода

  • 13.1 Правила по решениям:

    • новое .claude/rules/worker.md с paths (src/worker/**, сервис обработки, thumbnail.py), строка в AGENTS.md, «Где лежат инструкции»;
    • api-contract.md — 202, 409, 404, attachment_ids; api-layer.md — параметр variant;
    • service-layer.md, repo-layer.md, dto.md (модель сообщения), infra.md (broker/), migrations.md, logging.md, settings.md, run-modes.md, docker.md, balancer.md (29 с и 76 с, порядок обновления), student-tests.md (hook, модуль, ожидание ready, время прогона), bench.md.

    Проверка: grep -rn "201 Attachment\|mark_ready\|Pillow — только dev" .claude AGENTS.md — только верные упоминания; make lint.

  • 13.2 AGENTS.md: текущий статус, правила лабы 5, таблица важных файлов и команд, карта кода (src/worker/, src/infra/broker/, сервис обработки, thumbnail.py, infra/rabbitmq/, новые модули и файлы тестов), время make failure_checks. KNOWN_ISSUES.md — разрыв COMMIT и publish до pipeline-reliability, смесь версий при замене. QUESTIONS.md — решения, принятые в apply.

    Проверка: каждый новый файл git status назван в карте кода или таблице; make lint, make check.

14. Регресс на рабочем дереве

  • 14.1 Смесь версий и откат по Migration Plan design на рабочем стенде: docker compose stop worker cleaner, make rolling_update COMMIT=cc33a03 MIGRATE=0, затем вперёд: make rolling_update, docker compose up -d --no-deps cleaner worker. Первое обновление с прежней версии под нагрузкой показывает make bench_rollout_quick (задача 14.3).

    Проверка: на прежнем образе сообщения и история — 200, загрузка — 201 ready, чтение вложения в новом статусе — 500 (названное ограничение); после возврата на текущий код lb_stats без ручных состояний, новые вложения становятся ready, вложение прежнего образа — 200, variants пуст, variant=thumbnail — 404, сверка без расхождений по нему.

  • 14.2 Рабочий стенд:

    • make test — PASS: lab5, make validate, make check;
    • make student_test через LB — красное только missing_evidence;
    • make run_dev с make run_worker и EXPECT_REPLICAS=1 make student_test — те же итоги, кроме тестов реплик;
    • make test_isolated, полный make failure_checks;
    • make test-persistence ACTION_SCRIPT=scripts/restart.sh;
    • make test-failover ACTION_SCRIPT=scripts/stop-one.sh дважды (stop, STOP_MODE=kill) с make replicas между ними;
    • make s3_check, make reconcile — код 0;
    • driver.py --port <LB> defense-scenario;
    • make wipe_data не выполнять: текст запроса и docker compose config --volumes проверить чтением.
  • 14.3 Регресс bench/: make bench_quick, make bench_failover_quick, make bench_rollout_quick (обе фазы образов, новая миграция под нагрузкой без ошибок), make bench_restore_quick, make bench_uploads_quick, make bench_reconcile_quick — код 0.

  • 14.4 Сборка из чистого дерева: команда git ls-files -z -co --exclude-standard | tar … из docker.md; в образе импорт Pillow и aio-pika, версии как в uv.lock, uv и компиляторов нет. make lint, openspec validate async-attachments --strict, openspec validate --specs.

  • 14.5 Отчёт apply для основной сессии: git status, git diff --stat, предложенное сообщение коммита, созданные пробами volumes, что осталось красным и почему. Агент останавливается здесь: коммит и группу 15 выполняет основная сессия.

15. Evidence и отчёт (после коммита, основная сессия)

Снимать на закоммиченном коде: рабочий стенд собран из HEAD (make run_docker), рабочее дерево чистое, в шапке каждого файла команда, дата, commit и стенд. Без токенов, паролей, ключей и секретов.

  • 15.1 Коммит кода групп 1–14 на ветке feat/async-attachments, стенд на этом commit: make run_docker, make replicas.

    Проверка: git status чист; docker compose ps — как в задаче 9.6; make test — PASS: lab5.

  • 15.2 Проверки и исключения сверки:

    • evidence/attachments/defense.md — driver.py --port <LB> defense-scenario;
    • evidence/broker/stand.md — driver.py --port <LB> broker-check;
    • evidence/broker/isolated.md — make test_isolated KEEP_TEST_DB=1, broker-check --require-test-queue, затем make test_isolated;
    • evidence/attachments/storage.md — driver.py --port <LB> attachment-storage, с пробами ограничений обработки;
    • evidence/attachments/failover.md — driver.py --port <LB> attachment-failover;
    • evidence/attachments/consistency.md — driver.py --port <LB> upload-consistency;
    • evidence/replicas/test-persistence.md — make test-persistence ACTION_SCRIPT=scripts/restart.sh, контейнеры и StartedAt до и после.

    Проверка: test_exclusion_evidence_exists называет только файлы старых исключений последнего шага прогона; в broker/isolated.md очередь есть после первого прогона и нет после второго.

  • 15.3 Процесс, ключи, журнал, схема:

    • evidence/worker/process.md — driver.py --port <LB> worker-process: PID 1, лимиты, остановка, неверные WORKER__*, рестарт хранилищ, значения по умолчанию и подмена окружением;
    • evidence/worker/logs.md — журнал готового и failed вложения одного request_id, запись error сообщения не по схеме, filename и секретов нет;
    • evidence/s3/worker-key.md — make s3_check и строки ключа worker;
    • evidence/migrations/async-attachments.md — проба задачи 2.2, откат на образ cc33a03 и возврат задачи 14.1;
    • evidence/uploads/lb-timeouts.md — driver.py lb-upload-timeouts.

    Проверка: grep значений секретов из .env по evidence/ пуст (значения не печатаются).

  • 15.4 Прогоны наборов на этом commit: evidence/tests/student-test-lb.md (make student_test через LB), evidence/tests/test-isolated.md, evidence/tests/failure-checks.md (полный make failure_checks, число проверок и время), метка make bench_rollout ROLLOUT_LABEL=async-attachments.

    Проверка: числа в файлах совпадают с выводом команд; красное только missing_evidence по файлам последнего шага прогона.

  • 15.5 REPORT.md:

    • архитектура стенда с брокером и worker, таблица ролей и сумма лимитов, расчёт соединений PostgreSQL;
    • запуск из чистого clone двумя способами, make run_worker;
    • сопоставление имён skeleton BROKER_URL_FILE, WORKER_CONCURRENCY, JOB_MAX_ATTEMPTS, JOB_TIMEOUT_SECONDS, STAGING_RETENTION_SECONDS;
    • таблица критериев уровня 3 с командой, наблюдением и файлом;
    • критичные и некритичные зависимости /health/ready с причинами, поведение при отказе брокера;
    • разрыв COMMIT и publish и окна отказа (решение 3), что закрывает pipeline-reliability;
    • ограничения из спеков: зависший worker и срок подтверждения брокера, постоянная пауза повтора, staging после ready и у failed, staging и конечный префикс на одном сервере S3, объект staging при заморозке API, смесь версий при замене и новые статусы, прерванное остановкой задание, сверка не проверяет объекты вариантов и staging, искажения данных скана JPEG, цепочка LB 76 с с формулой;
    • ответы на вопросы защиты README.md, порядок сценария защиты и ссылка на evidence/attachments/defense.md;
    • вопросы преподавателю из QUESTIONS.md, ## async-attachments, в разделе «Открытые вопросы преподавателю».

    Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл; make lint, make check, openspec validate async-attachments --strict.

  • 15.6 Коммит evidence и REPORT.md основной сессией. Проверка: git status чист; git log -2 — commit кода назван в шапках файлов evidence.