Propose bounded PNG rendering memory as an OpenSpec change

This commit is contained in:
Artyom
2026-11-07 00:41:52 +03:00
parent fb682bc384
commit 429f12d0bc
5 changed files with 141 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-07
@@ -0,0 +1,56 @@
## Context
Причина и исходные FAIL — в proposal.md. Pillow 13.0.0 хранит RGB в четырёх байтах
на пиксель. Контекст `with Image.open(...)` закрывает файл, но оставляет pixel core:
это подтверждено Context7 `/python-pillow/pillow/13.0.0`,
[Image lifecycle](https://github.com/python-pillow/pillow/blob/13.0.0/docs/reference/open_files.rst).
Поэтому два RGB-декодирования, несколько L-масок, RGBA и RGB-фон одновременно
переполняют бюджет. Для grayscale16 дополнительно создаётся полноразмерный I.
## Goals / Non-Goals
Сохранить исходные пиксели и результат кодирования при меньшем пике памяти.
Не менять размеры/качество вариантов, лимиты и поведение ошибок.
Исправление принадлежит infrastructure зоны attachments, за портом VariantRenderer;
ProcessVariantRenderer собирается в attachments/entrypoints/ioc.py для worker.
Домен, shared, SQLAlchemy/Alembic и инфраструктура стенда не меняются.
## Decisions
1. Выполнять точечные преобразования цвета и построение RGB-маски небольшими
плитками. Полноразмерными остаются исходник, выходной RGB либо L-маска.
Получаем ограниченную рабочую память; цена — несколько сотен вызовов Pillow.
Масштабирование и фильтрация выполняются после сборки, поэтому швов нет.
Уменьшение изображения до сравнения tRNS отвергнуто: потеряется точность
соседних 16-битных значений и изменятся варианты.
2. Последовательно декодировать младшие и старшие байты RGB16. Между проходами
закрывать core низких байтов через close(); после пересечения масок освобождать
обе маски перед EXIF/resize. Получаем отсутствие двух полноразмерных RGB
одновременно; сохраняем штатные PNG-фильтры и Adam7 декодера Pillow.
3. Сохранить ограничения по байтам до декодирования и пикселям по заголовку;
RLIMIT_AS=448 MiB и timeout=30 с остаются в дочернем процессе, concurrency=2.
При 40 Мп grayscale16 исходник занимает около 80 MB, выходной RGB — 160 MB,
временные плитки ограничены. RGB16 требует 160 MB изображения и до трёх
40 MB масок при пересечении, вместо двух изображений и масок. Это расчёт
pixel buffers, а не измерение всего адресного пространства Linux worker.
4. Проверить пиксели и освобождение core offline, сохранить Linux-тест с реальными
импортами worker для следующего этапа. Увеличение лимитов и зависимости не нужны.
## Risks / Trade-offs
- Ошибка границ плиток или потеря info/transparency → сравнение полных пикселей
и вариантов с независимым эталоном на нескольких плитках, нечётных размерах,
фильтрах, Adam7, EXIF и обеих версиях pipeline.
- Разные расходы адресного пространства macOS/Linux → финальный агент обязан
повторить Linux RLIMIT_AS и HTTP 40 Мп; offline PASS этого не заменяет.
- Исторический design указывает upload 201 → применяется нормативный 202 ЛР5.
S3 staging → COMMIT attachment/job/outbox, fencing и ack после COMMIT сохраняются.
- Рекомендации apply/archive требуют полного стенда → прямой запрет пользователя
ограничивает фазу offline-проверками и передачей затронутых проверок.
## Migration Plan
Миграций нет. После независимого review финальный агент пересобирает только образ
назначенного стенда и повторяет PNG/ресурсные сценарии. Старые FAIL сохраняются.
Откат — возврат изменения renderer; он возвращает известный major, поэтому релиз
до новых Linux/HTTP доказательств не квалифицируется.
@@ -0,0 +1,39 @@
## Why
Граничный PNG 8000×5000 обязан становиться ready при штатных лимитах worker. На snapshot
`fb682bc38476d785d02d4611ba4913e5f37bed62` четыре tRNS-изображения вместо этого дают
MemoryError и processing_failed: `evidence/final-validation-2026-11-07/png-limits.json`
и `resource-probe-worker.txt`. Нарушен уровень «4»: пределы обработки и варианты;
в REPORT это строка граничного PNG и блокирующий major финальной validation.
## What Changes
- Ограничить размер временных буферов наложения прозрачности и сравнения RGB16;
явно освобождать Pillow core до следующего полного декодирования.
- Сохранить точное сравнение tRNS, белый фон, EXIF и варианты v1/v2.
- Добавить offline-регрессии управления памятью, сохранить evidence и конкретный
список обязательных адресных Linux/HTTP проверок финальному агенту.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `lab5-image-variants`: уточнить граничный сценарий для grayscale 2/4/16 и RGB16
с tRNS при 448 MiB/30 с, в том числе повторную обработку обеими версиями pipeline.
## Impact
Только адаптер Pillow зоны attachments, собственные тесты, OpenSpec и evidence.
Лимиты, зависимости, API, PostgreSQL/SQLAlchemy/Alembic, S3, outbox и брокер сохраняются.
Upload по нормативному контракту остаётся `202 queued` после COMMIT.
## Non-goals
Out of scope из `openspec/config.yaml` сохраняется. Minor не исправляются.
Docker, нагрузка, установка окружений, push и Telegram запрещены этой фазе.
Нормативные файлы и старые FAIL не меняются; полная динамическая квалификация
не заявляется по результатам offline-проверок.
@@ -0,0 +1,30 @@
## MODIFIED Requirements
### Requirement: Пределы обработки изображения в worker
Worker SHALL ограничивать обработку одного задания: размер оригинала — `MAX_UPLOAD_BYTES`, число пикселей по заголовку до декодирования — `MAX_IMAGE_PIXELS`, время рендера — `RENDER_TIMEOUT_SECONDS`, адресное пространство процесса рендера — `RENDER_MEMORY_MB`; рендер SHALL выполняться в отдельном процессе, число одновременных рендеров SHALL не превышать `WORKER_CONCURRENCY`, а процесс worker SHALL иметь предел памяти контейнера не меньше суммы пределов рендеров и собственной памяти. Превышение предела SHALL переводить вложение в `failed` с `processing_failed` без повторов; процесс, превысивший время, SHALL принудительно завершаться. Падение процесса рендера по внешней причине SHALL считаться временной ошибкой. Worker SHALL продолжать обрабатывать другие задания после любого из этих исходов.
#### Scenario: Рендер дольше предела
- **WHEN** worker запущен с `RENDER_TIMEOUT_SECONDS` меньше времени рендера загруженного изображения
- **THEN** вложение становится `failed` с `processing_failed` после первой попытки, процесс worker продолжает работать, следующая загрузка становится `ready`
#### Scenario: Рендер больше предела памяти
- **WHEN** worker запущен с `RENDER_MEMORY_MB` меньше пика рендера изображения 40 Мпикс
- **THEN** вложение становится `failed` с `processing_failed`, процесс worker продолжает работать
#### Scenario: Изображение на пределе пикселей
- **WHEN** со штатными пределами загружен PNG 8000×5000
- **THEN** вложение становится `ready` с тремя вариантами, пик памяти контейнера worker ниже его предела
#### Scenario: Прозрачный PNG на пределе пикселей
- **WHEN** последовательно обработаны PNG 8000×5000 grayscale 2/4/16 и RGB16 с tRNS при штатных 448 MiB адресного пространства рендера и 30 с на задание, затем запрошена версия pipeline 2
- **THEN** каждый upload отвечает `202 queued`, обе версии становятся `ready` с тремя вариантами и неизменным оригиналом; прозрачные области белые, соседний непрозрачный цвет сохраняется, worker остаётся работоспособным и обрабатывает следующее обычное задание
#### Scenario: Пиксели сверх предела по заголовку
- **WHEN** worker получает задание на оригинал, у которого по заголовку больше `MAX_IMAGE_PIXELS` пикселей
- **THEN** изображение не декодируется, вложение становится `failed` с `invalid_image`
@@ -0,0 +1,14 @@
## 1. Адаптер attachments: уровни «3» и «4»
- [ ] 1.1 Ограничить временные изображения наложения прозрачности и RGB16-масок плитками, освободить core между проходами без изменения лимитов.
- [ ] 1.2 Проверить thumbnail/crop/optimized offline: точное tRNS, белый фон, границы плиток, EXIF, ошибки и обе версии pipeline.
## 2. Регрессии и доказательства
- [ ] 2.1 Добавить тест освобождения памяти на малых данных и Linux-регрессию реальных четырёх 40 Мп fixtures с импортами worker для финальной фазы.
- [ ] 2.2 Выполнить целевые offline-тесты, границы зон, make check/validate/lint и OpenSpec strict; сохранить команды, результаты и хеши.
- [ ] 2.3 Сохранить список обязательных финальных Linux/HTTP PNG и ресурсных проверок, ограничения применимости evidence и прежние minor.
## 3. Завершение
- [ ] 3.1 Синхронизировать спецификацию и архивировать change; проверить чистоту нормативных файлов и сделать английские коммиты после make lint.