Propose critical lab5 review fixes as an openspec change

This commit is contained in:
Artyom
2026-11-06 23:29:25 +03:00
parent 544b9c78d3
commit ef55f9ac0a
7 changed files with 139 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-06
@@ -0,0 +1,27 @@
## Context
Причины и область — в proposal.md. Затронут только адаптер изображений зоны attachments и топология её брокера. `VariantRenderer` остаётся портом, `ProcessVariantRenderer`/Pillow — адаптером, `attachments/ioc.py` — сборкой; FastStream consumer остаётся в entrypoints. БД хранит состояния, S3 — байты, RabbitMQ — доставку. SQL и схема не меняются.
## Goals / Non-Goals
**Goals:** не терять доставку принятого задания при недоступной БД; накладывать все поддерживаемые формы PNG-прозрачности на белый фон.
**Non-Goals:** новые очереди, миграции, изменение ack/lease/fencing и исправление minor. Docker и нагрузка запрещены этапу исправлений: динамическое подтверждение передаётся финальному агенту, не считается выполненным при архивации.
## Decisions
1. Политика рабочей очереди получает `delivery-limit=-1`. [RabbitMQ 4.1](https://www.rabbitmq.com/docs/4.1/quorum-queues#poison-message-handling) допускает отключение лимита политикой без пересоздания очереди. Это предотвращает помещение валидного задания в DLQ до получения доступа к PostgreSQL. Сохраняются секундная задержка nack и журнал `job.requeued`, ограниченный prefetch, reject невалидных сообщений в DLX, `JOB_MAX_ATTEMPTS` и backoff/jitter для ошибок обработки после claim. Альтернативы: периодическая переотправка queued потребовала бы нового запроса/индекса и создаёт дополнительные дубли; удержание unacked ограничено consumer timeout и повторными падениями процесса. Транспортный повтор не увеличивает application `attempt`.
2. Порядок устойчивой записи сохраняется: staging → COMMIT attachment/job/outbox → publisher confirm → отметка outbox; worker claim COMMIT → запись S3 → COMMIT результата → ack. При отказе до claim сообщение остаётся в очереди; после claim аренда восстанавливается relay; после записи S3 повтор пользуется ключом эффекта `(attachment_id, pipeline_version, variant)`; после COMMIT повтор — no-op. Публикация версий остаётся монотонной.
3. В Pillow наличие `info.transparency` учитывается независимо от режима RGB/L/P/1: преобразование в RGBA перед существующей композицией. Для 16-битного grayscale точное сравнение с tRNS делается до нормализации, через LUT 65536 значений и одноканальную маску; прозрачные пиксели заменяются белым, затем сохраняется прежнее преобразование оттенков. Это не смешивает соседние исходные значения. [Документация Pillow 13.0.0](https://github.com/python-pillow/pillow/blob/13.0.0/docs/handbook/concepts.rst), полученная через Context7, описывает прозрачность без alpha band в `info`. Новых зависимостей нет.
4. Проверки: offline-вызов реального обработчика на 12 ошибках и последующем успехе, политика очереди, все варианты v1/v2 для tRNS и непрозрачных контрольных пикселей. Реальный RabbitMQ-тест расширяется до 12 повторов и проверки неизменности DLQ; запуск на этом этапе исключён.
## Risks / Trade-offs
- Неустранимая ошибка до claim может повторяться неограниченно → сообщение сохраняется, каждый повтор виден в журнале; ошибки обработки после claim по-прежнему конечны. Это цена сохранности при отказе БД произвольной длительности.
- Смена политики не возвращает автоматически сообщения, уже попавшие в DLQ при старой конфигурации → на финальном стенде проверить DLQ и зафиксировать её исходную глубину; не удалять данные.
- Для grayscale с tRNS нужна дополнительная маска 1 байт/пиксель и LUT; прежние ограничения пикселей, памяти процесса и времени действуют. Динамические проверки лимитов для этого пути остаются финальному этапу.
- Ранее измеренные JPEG/PNG без tRNS сохраняют байты и параметры рендера; новые результаты tRNS нельзя объявлять проверенными по старому evidence.
## Migration Plan
При следующем разрешённом старте применить definitions к RabbitMQ 4.1.8 с сохранением volume, подтвердить эффективный `delivery-limit=-1` для существующей очереди и повторить отказ БД дольше десяти доставок. Пересобрать worker для Pillow-исправления. Очереди, volumes и схема не пересоздаются. Откат старой политики возвращает риск потери транспорта, поэтому его нельзя считать безопасным исправлением.
@@ -0,0 +1,30 @@
## Why
Ревью snapshot `544b9c78d39d0e9dd07f841894c390895896605a` обнаружило два major: принятое задание теряет транспорт после десяти повторов при недоступной БД, а PNG с tRNS получает цветной или чёрный фон вместо белого. Это нарушает обязательные критерии «3» (сохранность принятой работы, thumbnail) и «4» (crop/optimized).
## What Changes
- Отключить транспортный delivery-limit для рабочей очереди, сохранив задержку nack, DLX для невалидных сообщений и ограниченные повторы обработки в PostgreSQL.
- Учитывать tRNS при композиции на белый фон, включая grayscale до потери точности при преобразовании 16 → 8 бит.
- Добавить offline-регрессии и расширить существующую проверку реального брокера; последнюю передать финальному агенту без запуска Docker.
- Сохранить команды, результаты и перечень обязательных затронутых динамических проверок в evidence для отдельного отчётного этапа.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `lab5-job-delivery`: инфраструктурные повторы не исчерпывают доставки до восстановления PostgreSQL.
- `lab5-job-recovery`: DLQ предназначена для отклонённых сообщений; транспортный лимит больше не отправляет туда принятые задания.
- `lab5-image-variants`: прозрачность tRNS применяется во всех вариантах обеих версий pipeline.
## Impact
Зона attachments: адаптер Pillow, конфигурация RabbitMQ, собственные тесты. Порты, SQLAlchemy/Alembic, порядок COMMIT/ack и ключ эффекта сохраняются. Нормы: `contracts/README.md` (thumbnail и прозрачность), `contracts/attachment-states.md` (окна отказа), рубрика `README.md` «3»/«4». Материалы для строк будущего REPORT «at-least-once и восстановление» и «варианты на белом фоне» будут в `evidence/review-fixes-2026-11-06/`; сам REPORT оформляет отдельный агент.
## Non-goals
Minor из ревью остаются ограничениями отчёта. Out of scope из `openspec/config.yaml` сохраняется. Нагрузку, Docker, публикацию, другие лабораторные и runner/state этот этап не затрагивает.
@@ -0,0 +1,25 @@
## MODIFIED Requirements
### Requirement: Crop и optimized
Worker SHALL строить для каждого задания, кроме `thumbnail`, вариант `crop` — JPEG, центрированный квадрат 128×128 после применения EXIF orientation, с увеличением маленьких исходников, — и вариант `optimized` — WebP, вписанный в 1280×1280 с сохранением пропорций, без увеличения, размеры округлены вниз и не меньше 1 px. Прозрачность (альфа-канал и PNG tRNS) во всех вариантах обеих версий pipeline SHALL компоноваться на белый фон согласно `contracts/README.md` («Вложения»). Варианты SHALL NOT содержать EXIF, ICC и XMP; параметры кодирования SHALL быть документированы (`crop` — JPEG `quality` 85, `optimized` — WebP с потерями `quality` 80, `method` 4). Метаданные каждого варианта (`content_type`, `size_bytes`, `width`, `height`, `sha256`) SHALL совпадать с байтами, которые отдаёт `/content?variant=<имя>`.
#### Scenario: Fixture 320×200
- **WHEN** обработана `tests/fixtures/sample.png`
- **THEN** у вложения варианты `crop` 128×128 `image/jpeg`, `optimized` 320×200 `image/webp` и `thumbnail` 256×160, каждый `/content?variant=<имя>` отдаёт настоящий файл этого формата длиной `size_bytes` с SHA-256 из метаданных и реальными размерами из метаданных
#### Scenario: Большой и вытянутый исходник
- **WHEN** обработаны JPEG 4000×3000 и PNG 3000×2
- **THEN** `optimized` 1280×960 и 1280×1 соответственно, `crop` в обоих случаях 128×128
#### Scenario: Ориентация и прозрачность
- **WHEN** обработаны JPEG 400×200 с EXIF orientation 6 и PNG RGBA с прозрачным фоном
- **THEN** `optimized` первого 200×400, прозрачные области `crop` и `optimized` второго белые, ни в одном варианте нет EXIF
#### Scenario: Прозрачность tRNS без альфа-канала
- **WHEN** загружен допустимый PNG RGB, L, 1-битный или 16-битный grayscale с tRNS
- **THEN** прозрачные пиксели `thumbnail`, `crop` и `optimized` белые, непрозрачные сохраняют цвет с учётом кодирования; соседнее непрозрачное значение 16-битного grayscale не становится прозрачным при округлении до 8 бит
@@ -0,0 +1,20 @@
## MODIFIED Requirements
### Requirement: Брокер и отдельные процессы в стенде
Стенд SHALL содержать сервисы `broker` (RabbitMQ с volume и фиксированным именем узла), `relay` и `worker`, запускаемые из того же образа, что и API, но отдельными процессами. Очередь заданий SHALL быть durable quorum-очередью с dead-letter exchange. Повторные доставки при инфраструктурной ошибке до фиксации результата SHALL NOT исчерпываться транспортным лимитом; обработка задания SHALL оставаться ограниченной `JOB_MAX_ATTEMPTS` согласно уровню «3» `README.md`. Наружу SHALL публиковаться только UI брокера на `127.0.0.1`; AMQP, relay и worker портов на хосте не имеют. API SHALL NOT иметь учётных данных брокера.
#### Scenario: Топология
- **WHEN** выполняется `rabbitmqctl list_queues -p messenger name type durable` и `list_consumers -p messenger`
- **THEN** `attachments.process` и `attachments.process.dlq` — `quorum`, durable; у `attachments.process` один consumer worker с `prefetch_count` равным `WORKER_CONCURRENCY`
#### Scenario: Сервисы
- **WHEN** выполняется `docker compose ps` после `make up`
- **THEN** `broker`, `relay`, `worker` в состоянии `healthy`, процессы не от root, опубликованы только порты `lb` и UI брокера на `127.0.0.1`
#### Scenario: БД недоступна дольше десяти доставок
- **WHEN** принятое задание опубликовано, а PostgreSQL недоступен при захвате более десяти повторных доставок
- **THEN** сообщение остаётся доступным в рабочей очереди с теми же `job_id` и `attempt`, DLQ не пополняется из-за этого отказа; после восстановления БД вложение становится `ready` без replay, с одним набором вариантов
@@ -0,0 +1,20 @@
## MODIFIED Requirements
### Requirement: Реестр failed и явный replay
Задания в `failed` SHALL быть доступны оператору списком с `attachment_id`, `job_id`, `error_code`, `attempt`, классом последней ошибки и временем. Команда `python -m messenger.admin replay --attachment-id <id>` SHALL переводить вложение `failed` в `queued` тем же `job_id` с `attempt` 1 и новой публикацией, записывая в журнал задания событие `replayed` с оператором; для вложения в `ready`, `queued` или `processing` SHALL отвечать `noop` и записывать `replay_noop`, не создавая работы; для `failed`, чей staging уже удалён по retention, — `expired`. Последняя строка вывода команды SHALL быть JSON с полем `result`. Сообщения не по схеме SHALL попадать в dead-letter очередь, которую оператор просматривает без извлечения. Недоступность БД SHALL NOT отправлять принятое задание в DLQ по числу доставок; ограничение попыток обработки и реестр failed SHALL сохраняться согласно уровню «3»/«4» `README.md`.
#### Scenario: Replay после retry_exhausted
- **WHEN** вложение `failed` с `retry_exhausted`, оператор выполняет replay
- **THEN** вывод `{"result": "replayed", ...}`, вложение становится `ready`, `attempt` не превышает `JOB_MAX_ATTEMPTS`, в журнале есть `replayed`
#### Scenario: Replay готового вложения
- **WHEN** оператор повторяет replay уже `ready`-вложения
- **THEN** вывод `{"result": "noop", ...}`, в очередь ничего не публикуется, метаданные и строки вариантов не меняются
#### Scenario: Реестр
- **WHEN** оператор выполняет `python -m messenger.admin failed`
- **THEN** вывод — JSON-список `failed`-заданий без текста исключений, ключей S3 и учётных данных
@@ -0,0 +1,15 @@
## 1. Доставка уровня «3»
- [ ] 1.1 Изменить политику рабочей очереди для инфраструктурных повторов, сохранив DLX и конечные application retries.
- [ ] 1.2 Добавить offline-регрессию consumer и политики; расширить реальный RabbitMQ-тест до 12 ошибок, не запуская Docker. Проверить offline consumer через pytest.
## 2. Прозрачность вариантов уровней «3»/«4» и версий трека «5»
- [ ] 2.1 Исправить tRNS в Pillow до композиции на белый фон, сохранив непрозрачные оттенки.
- [ ] 2.2 Добавить и выполнить offline-регрессии всех вариантов v1/v2 для RGB/L/1/16-bit PNG, а также прежние renderer/domain тесты.
## 3. Проверки и передача
- [ ] 3.1 Выполнить make check, make validate, make lint и строгую валидацию OpenSpec; сохранить реальные результаты offline-проверок.
- [ ] 3.2 Зафиксировать обязательные динамические проверки для финального агента и прежние minor для отчёта; не объявлять их исправленными или проверенными.
- [ ] 3.3 Синхронизировать specs и архивировать завершённый цикл с датой и lab: 5; проверить отсутствие активного change.