# Tasks Как строить — `design.md` (дальше «решение N»), что должно получиться — дельты в `specs/`. Перед первым файлом слоя прочитать его правило: `service-layer.md`, `repo-layer.md`, `dto.md`, `infra.md`, `migrations.md`, `logging.md`, `settings.md`, `run-modes.md`, `docker.md`, `balancer.md`, `student-tests.md`, `bench.md`. Evidence снимается с закоммиченного кода, коммит — только после подтверждения пользователя (`bench.md`, «Измеренное состояние — commit»). **Шаг оператора до группы 5** — заменён в apply ответом основной сессии (`PLAN.md`, `### upload-consistency` → «Вопросы», п. 1): `make env_setup` сам дописывает недостающие переменные шаблона в существующий `.env` (design, «Уточнения apply», п. 1). Прежний текст: в рабочий `.env` нужно перенести строки `S3_CLEANER_ACCESS_KEY` и `S3_CLEANER_SECRET_KEY` из `.env.example`, секреты — `openssl rand -hex 10` и `openssl rand -hex 20`. Делает это пользователь (`PLAN.md`, `### upload-consistency` → «Вопросы», п. 1). Агент `.env` не читает и не правит. До переноса любая команда compose останавливается на `:?`: и рабочий стенд, и `make failure_checks`, и `make test_isolated`. Ожидаемо красное по ходу работы, остальное разбирается по AGENTS.md: между задачами 6.3 и 6.4 (sync дельт) сверка покрытия в `make student_test` падает на маркерах новых сценариев: «marker points to unknown scenario». Sync раньше тестов дал бы обратное — «no test and no exclusion». ## 1. Настройки, общий контекст сессии, ранний обработчик - [x] 1.1 Секция `[cleaner]` по решению 4 и дельте `service-configuration`: - класс `Cleaner` в `src/config/settings.py`: `interval_seconds` (float, > 0, 60), `pending_grace_seconds` (int, > 0, 900), `batch_size` (int, ≥ 1, 100); - строки с комментариями единиц в `config_example.toml`. Проверка: `uv run python -c "from src.config import settings; print(settings.cleaner)"` — значения по умолчанию; `CLEANER__INTERVAL_SECONDS=0` — ошибка проверки настроек называет `interval_seconds`. - [x] 1.2 Общий контекст сессии по решению 7. Функция `session_scope(session_factory, *, timeout_seconds)` в `src/infra/db/` с телом нынешнего `db_session_scope`: срок, `is_db_unavailable` → `invalidate()`, `warning`, `ServiceUnavailable`. `db_session_scope` и `get_db_session` в `src/api/dependencies.py` становятся обёртками над ней с фабрикой процесса API. Проверка: `make lint`; поведение API — группа 6 и задача 8.1, итоги прежних тестов те же. - [x] 1.3 `src/infra/early_stop.py`: имя процесса в записи «Stopped … before startup», по умолчанию — прежний текст API (решение 2). Проверка: `make lint`; `driver.py stop-at-start` — запись API прежняя («Stopped API before startup»), код 0; уборщик — задача 5.3. ## 2. Схема: частичный индекс - [x] 2.1 Индекс по решению 6: - `Index(..., postgresql_where=...)` по `(created_at, id)` в модели `Attachment`; - ревизия поверх `ef25d50b01a8` руками: `autocommit_block`, `SET lock_timeout = '2s'`, `create_index(..., postgresql_concurrently=True, if_not_exists=True)`, `RESET lock_timeout`; - `downgrade` — `drop_index(..., postgresql_concurrently=True, if_exists=True)`. Проверка: - `uv run alembic upgrade head --sql` — `CREATE INDEX CONCURRENTLY IF NOT EXISTS` вне `BEGIN … COMMIT` прежних ревизий; - временная база (`createdb` в контейнере `postgres`, `DATABASE__NAME` в окружении): `upgrade` с нуля → повтор без изменений → `downgrade -1` → `upgrade`, затем `DROP DATABASE`; - `pg_index.indisvalid` — true; - на рабочей базе в транзакции с откатом: несколько тысяч строк `pending` и `ready` → `EXPLAIN (ANALYZE, BUFFERS)` выборки кандидатов решения 3 — `Index Scan` по `ix_attachments_pending_created_at`. Итог — в design, «Уточнения apply». ## 3. Repo и сервисы - [x] 3.1 Repo по решению 3, в каждой функции одно выражение: - `src/core/repos/attachment.py`: выборка кандидатов (keyset по `(created_at, id)`, `status = 'pending'`, `created_at < :older_than`, `LIMIT`); блокировка одного кандидата (`FOR UPDATE SKIP LOCKED` с теми же условиями); удаление строки; - `src/core/repos/attachment_object.py`: `delete_original`. Проверка: `make lint`; поведение — группы 5 и 6. - [x] 3.2 `AttachmentService.upload` по решению 1: - флаг «COMMIT отправлен» вокруг `mark_ready` и `commit()`; - компенсация (`delete_original`, без повторов) при сбое tx2 до COMMIT и при `mark_ready` → `None`; - `None` — `ServiceUnavailable` и `error` вместо `RuntimeError`; - записи журнала по решению 1, без `filename`. Проверка: `make lint`; по HTTP — тесты 6.3 «Фиксация ready не удалась» и «Объект без фиксации убран», драйвер 7.1. - [x] 3.3 Сервис уборки `AttachmentCleanupService(db_scope, storage)` в `src/core/services/attachment_cleanup.py` по решениям 3 и 5: - проход `clean_stale_pending(*, older_than, batch_size)`: каждая строка — своя транзакция, сначала объект, потом строка; - отказ S3 прерывает проход, отказ БД его пропускает; - DTO итога прохода в `src/schemas/dataclasses/attachment.py` по `dto.md`; - журнал по дельте `service-logging`. Проверка: `make lint`; поведение — группы 5 и 6. ## 4. Процесс уборщика - [x] 4.1 Пакет `src/cleaner/` по решениям 2, 4 и 5: - `__main__.py` — ранний обработчик с именем процесса, затем `main()`; - `main.py`: - проверка grace против `2 × request_timeout_seconds + s3.timeout_seconds`, иначе `error` и код 2; - свой engine и `session_scope`, клиент S3 с namespace — именем базы; - цикл с ожиданием интервала или сигнала, обработчики SIGTERM и SIGINT в asyncio; - `--once` с кодами 0, 1, 2; - записи «Started cleaner» (интервал, grace, выборка, адрес S3, bucket, база) и «Stopped cleaner». Проверка без стенда: - `CLEANER__PENDING_GRACE_SECONDS=17 uv run python -m src.cleaner --once` — код 2, ошибка называет grace, оба срока и границу 17 с, к БД и S3 нет ни одного обращения; - `CLEANER__INTERVAL_SECONDS=abc` — ошибка проверки настроек; - `make lint`. ## 5. Стенд - [x] 5.1 Секреты уборщика по решению 8: - строки `S3_CLEANER_ACCESS_KEY`, `S3_CLEANER_SECRET_KEY` с комментарием в `.env.example`; - `ENV_SECRETS` и замены в `make env_setup`; - шапка шаблона — «шесть секретов S3». Проверка: подстановки рецепта `env_setup` дважды с выводом в поток, а не в файл. Секреты уборщика непустые и различаются, сравнение по хэшу, значения не печатаются. Рабочий `.env` не меняется. Затем — шаг оператора из шапки. - [x] 5.2 Bootstrap по решению 8 и дельте `object-storage`: - `infra/s3/bootstrap.sh`: шаги пользователя общие для `api` и `cleaner`; - политика `cleaner-objects` (`s3:GetObject`, `s3:DeleteObject` на `/*`); - ожидание ключа уборщика через DELETE несуществующего ключа, распознавание нового секрета; - проверки `apply` по спеку, строки режима `check` со своим проверочным объектом, уборка в `cleanup`; - окружение `s3-bootstrap` в `docker-compose.yml` — `S3_CLEANER_*`. Проверка на временном проекте compose (`-p` своё имя, `--env-file` — файл в scratchpad из `.env.example` со случайными секретами; после — `down`, созданные volumes перечислить в отчёте): - первый запуск — «user cleaner created»; - повтор дважды — «exists», код 0; - новый секрет уборщика — ключ пересоздан, прежний секрет — 403 `SignatureDoesNotMatch`; - ключ уборщика: GET и DELETE своего объекта — 200 и 204, повторный DELETE — 204, запись, список, bucket, политика, ACL, чужой bucket — 403. На рабочем стенде после шага оператора — `make s3_check`: код 0, строки ключа уборщика есть. - [x] 5.3 Сервис `cleaner` по решению 9 и дельте `container-run`: - якорь S3 делится на адрес и ключи; - `DATABASE__POOL_SIZE: "1"`; - healthcheck выключен, `stop_grace_period: 10s`; - лимиты по замеру `docker stats` в простое и во время прохода. Проверка на рабочем стенде (`make run_docker`, решение 9, «Migration Plan»): - `docker compose ps` — `cleaner` работает, портов нет; - журнал — «Started cleaner» с интервалом 60, grace 900, выборкой 100; - `docker compose config` — секреты по сервисам по дельте; - `docker compose stop cleaner` — быстрее 10 с, код 0, «Stopped cleaner»; - `docker compose up -d --no-deps cleaner && docker compose stop cleaner` сразу после старта — код 0 и «Stopped cleaner before startup». - [x] 5.4 `bench/` по решению 9: - `compose_env` — `S3_CLEANER_*`; - `bench.compose.yml` — `cleaner` описан, как `s3`, и не запускается; - комментарии. Проверка — задача 8.2. ## 6. Тесты отказов - [x] 6.1 `student-tests/fault_hook.py` по таблице решения 10: - действия `attachment-ids`, `last-pending`, `object-ids` (файлы `original` из `fs.tree`), `fail-attachments insert|ready|stall `, `clear-fail-attachments`, `kill-api`, `start-api`; - `count-attachments`, `count-objects` убраны; - docstring. Имя контейнера API — только `-api`. Проверка: разбор `fs.tree` на образце из пробы design (каталог `` без `original` не считается, `id` с `original` в середине и в конце списка считаются); поведение — тесты 6.3. - [x] 6.2 `run_failures.py` и `failures.compose.yml` по решению 10: - `cleaner` после bootstrap с grace 20 с, интервалом 1 с, `restart: "no"`; - `FAULT_CLEANER_GRACE_S`, `FAULT_CLEANER_INTERVAL_S` — тестам и строкой `say` в вывод команды; - журнал уборщика при падении; - docstring. Проверка: - `make failure_checks FAULT_ARGS='-k health'` — код 0, в выводе строка уборщика с grace 20 и интервалом 1, стенд удалён; - `make failure_checks FAULT_ARGS='-k no_such_test'` — pytest не собрал тестов (код 5), команда завершается с ненулевым кодом, вывела журналы API и уборщика, стенд удалён. - [x] 6.3 `student-tests/test_failures.py` по таблице решения 10: - меняются `test_upload_with_object_storage_stopped` (множества `id` и S6), `test_rejected_uploads_leave_nothing` (множества `id`), `test_object_storage_paused` (уборка после `unpause`); - новые `test_metadata_insert_failure`, `test_interrupted_body`, `test_ready_failure_compensated`, `test_killed_between_put_and_ready`, `test_cleaner_survives_outages`; - маркеры `spec` дословно по сценариям дельт, отказы хранилищ — в `with outage(...)`, триггеры снимаются в `finally`; - помощники: множества, объекты без строки, ожидание с крайним сроком G + I + 5 с. Проверка: - `make failure_checks FAULT_ARGS='-k "attachment or object_storage or cleaner or interrupted or metadata or killed or ready_failure"'`; - полный `make failure_checks` — код 0, сводка журнала PostgreSQL без признаков аварии, стенд удалён, у рабочего стенда прежний `StartedAt`; - время прогона — в design, «Уточнения apply». - [x] 6.4 Сверка покрытия: - `storage-consistency` в `CAPABILITIES` (`spec_coverage.py`); - синхронизация всех дельт change в основные спеки (`/opsx:sync`), как в `attachments`. Проверка: `make student_test` через LB — сверка без «no test and no exclusion» и «unknown scenario», итог называет число сценариев проверок отказов с новыми; `openspec validate --specs`. ## 7. Драйвер скилла `run-mtusi-messenger` - [x] 7.1 `driver.py --port upload-consistency` по решению 11 и раздел в `SKILL.md`: шаги, что проверяется, коды выхода, gotchas. Gotchas: - grace разового запуска не меньше 18 с; - уборщик сервиса эти строки не трогает; - на время `pause` S3 вложения стенда отвечают 503. Проверка: - на рабочем стенде — код 0; после команды у `attachments` нет триггеров драйвера, его функций тоже нет (psql: `\dS+ attachments`, `\df`); - отрицательная: `--port` консольного процесса без LB — код 2 и понятное сообщение; - `make lint` и `ruff format --check` драйвера. ## 8. Регресс и проверка кода - [x] 8.1 Рабочий стенд после `make run_docker`, иначе `make rolling_update` и `docker compose up -d s3-bootstrap cleaner`: - `make test` — `PASS: lab4`; - `make student_test` через LB; - `make test_isolated` — зелёный; - `make test-persistence ACTION_SCRIPT=scripts/restart.sh`. Уборщик переживает рестарт PostgreSQL и S3: в его журнале `warning` отказа, `RestartCount` 0 и прежний `StartedAt`, а разовый `docker compose run --rm --no-deps cleaner --once` после рестарта — код 0; - `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, между прогонами `make replicas`; - `make s3_check`. - [x] 8.2 Регресс `bench/`: `make bench_quick`, `make bench_failover_quick`, `make bench_rollout_quick`, `make bench_restore_quick` — код 0. В `rollout` с `e1161f7` применяются обе ревизии, в том числе индекс под нагрузкой, ошибок нет. Метки `quick-*` в git не идут. - [x] 8.3 `make lint`, `make check`, `openspec validate upload-consistency --type change --strict`, `openspec validate --specs`, `graphify update .`. ## 9. Документы - [x] 9.1 Правила по решениям: - `service-layer.md` — ветки ошибок загрузки и компенсация, сервис уборки и его транзакции; - `repo-layer.md` — функции кандидатов, блокировки и удаления, `delete_original`; - `infra.md` — `session_scope`, клиенты процесса уборщика, пул 1; - `docker.md` — сервис `cleaner`, healthcheck, секреты по сервисам, пользователь уборщика в bootstrap, `restart.sh` уборщика не трогает; - `settings.md` — `[cleaner]`, `S3_CLEANER_*`, шаг оператора; - `logging.md` — записи уборщика и новые записи `attachment_service`; - `run-modes.md` — точка входа уборщика, сигналы, консоль без уборщика; - `migrations.md` — индекс `CONCURRENTLY` в `autocommit_block` и починка INVALID-индекса; - `student-tests.md` — действия hook, множества вместо счётчиков, новые тесты, уборщик на стенде отказов, время прогона; - `balancer.md` — `rolling-update.sh` уборщика не пересоздаёт. AGENTS.md: - карта кода: `src/cleaner/`, `attachment_cleanup.py`, `session_scope`; - команды: `driver.py upload-consistency`, время `make failure_checks`; - правила лабы 4: уборщик и его права S3; - таблица важных файлов. `PLAN.md`, `### upload-consistency` — «Решения» из apply. Проверка: `grep -rn "count-objects\|count-attachments" AGENTS.md .claude student-tests` пуст; `make lint`. ## 10. Коммит, evidence, отчёт - [x] 10.1 Финальная проверка задач 8.1 и 6.3 на текущем коде. Затем показать изменения, предложить сообщение коммита и после подтверждения закоммитить (основная сессия). - [x] 10.2 Evidence с закоммиченного кода по решению 11. Без токенов, паролей и секретов S3, в каждом файле команда, дата, commit и стенд: - `evidence/attachments/consistency.md`; - `evidence/attachments/cleaner-process.md`; - `evidence/s3/cleaner-key.md`; - `evidence/migrations/pending-index.md`; - `evidence/tests/failure-checks.md`. Проверка: `grep` значений секретов из `.env` по `evidence/` пуст (значения не печатаются); `make student_test` зелёный. Коммит — после подтверждения. - [x] 10.3 `REPORT.md` по решению 11: - раздел «Согласованность БД и S3»; - ответ на вопрос защиты «PUT прошёл, COMMIT нет»; - строка уборщика в таблице сервисов, сумма лимитов и расчёт соединений; - строки уровня «4» вместо TODO `upload-consistency`; - ограничения; - шаг оператора `.env`. Строку этапа 3 в `PLAN.md` — по факту. Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл; `make lint`, `make check`, `openspec validate upload-consistency --type change --strict`. Коммит — после подтверждения. ## 11. Замечания проверки Verify 2026-10-21: 0 CRITICAL, 4 WARNING, 1 SUGGESTION; решения основной сессии — design, «Уточнения apply», п. 16–20. Новый или изменённый сценарий правится и в дельте, и в основном спеке дословно. - [x] 11.1 W1, «`ready` без объекта» при откате уборщика — закрыть кодом (решение 3, «Уточнения apply», п. 16): - уборщик: `lock_stale_pending` → пометка `updated_at = utcnow()` (`mark_removing`) → commit; DELETE объекта; своя транзакция — `lock_stale_pending` → `delete_attachment` → commit; - `mark_ready` — только непомеченная строка (`updated_at = created_at`), помеченная — `None` (503 и компенсация); - требование «Безопасность уборки» (`storage-consistency`), сценарий «Сбой уборки после удаления объекта», ограничение «Уборщика незавершённых загрузок», Decisions и Risks design; окно `make rolling_update`; - режим hook `fail-attachments undeletable ` и тест `test_cleaner_failure_after_object_delete`. Проверка: вставка `pending` пишет `created_at` и `updated_at` одним значением (и в коде до change); красный прогон теста на коде до правки (201 вместо 503), зелёный — после; полный `make failure_checks`. - [x] 11.2 W2, «исход COMMIT неизвестен»: режим hook `fail-attachments commit ` (отложенный триггер ограничения, 08006), сценарий «Исход фиксации неизвестен» (`attachments`), тест `test_ready_commit_outcome_unknown`: 503, строка `pending`, объект есть сразу после ответа; через G + I + 5 с ни строки, ни объекта, объектов без строки нет. Проверка: тест красный на временной регрессии «компенсация на любой сбой» (правка откатывается), зелёный на коде. - [x] 11.3 W3, «строку убрал уборщик до `ready`»: режим hook `fail-attachments outlive ` (вставка на час старше вместе с `updated_at`, ожидание перевода в `ready` в триггере уровня оператора `BEFORE UPDATE OF status`), сценарий «Загрузка дольше grace» (`storage-consistency`), тест `test_upload_outlives_grace`: 503 (не 201 и не 500), ни строки, ни объекта, объектов без строки нет. Проверка: тест красный на временном возврате `RuntimeError`, зелёный на коде. - [ ] 11.4 W4, evidence сценария `service-logging` «Отказ S3 во время прохода» — раздел в `evidence/attachments/cleaner-process.md` (`pause s3` → `cleaner --once` с grace 30 с: код 1, «Object storage is unavailable» и «Interrupted cleanup pass» с `interrupted_by: object_storage`, строка на месте → `unpause` → `--once` убирает) и строка `REPORT.md`. Снимается с закоммиченного кода. Проверка: `grep` секретов по `evidence/` пуст. - [x] 11.5 S1: `.claude/rules/docker.md`, раздел «Уборщик» — `entrypoint`, а не `command`. Проверка: текст совпадает с `docker-compose.yml`. - [x] 11.6 Документы и регресс: правила (`service-layer.md`, `repo-layer.md`, `student-tests.md`), AGENTS.md (карта кода, действия hook, время `make failure_checks`), `PLAN.md`. Проверки: `make lint`, `make check`, `openspec validate upload-consistency --type change --strict`, `openspec validate --specs`, полный `make failure_checks` (код 0, сводка PostgreSQL без признаков аварии); на рабочем стенде после `make rolling_update` и `docker compose up -d --no-deps cleaner` — `make test`, `make student_test` через LB, `make test_isolated`, `driver.py --port upload-consistency` (код 0). - [ ] 11.7 После коммита основной сессии: evidence 11.4, пересъёмка `evidence/tests/failure-checks.md` и чисел в `evidence/tests/` и `REPORT.md`; `REPORT.md` — порядок уборки с пометкой и остаточный риск, новые проверки, строка W4; строка этапа 3 `PLAN.md`.