DECISION_LOG.md

Журнал принятых решений

Актуально на 2026-08-13. Этот документ фиксирует не только выбранную реализацию, но и отвергнутые альтернативы, чтобы следующие итерации не повторяли уже пройденные эксперименты.

Статусы: accepted — действующее решение; revisit — решение работает как временный компромисс; rejected — вариант проверен или признан вредным.

Контрольная точка — 2026-08-13

• Текущий функциональный baseline: commit 47faa2a; рабочее дерево перед обновлением журнала чистое.
• Полный real-world-ui-v1 в режиме Quality: 9/9 automated pass; unit/integration suite: 63 passed.
• Основной путь полностью локальный: OpenCV/scorer → Mask R-CNN → gated SAM → iterative selector → OCR/design ownership → gated MODNet/BiRefNet/GrabCut → Big-LaMa background → JSON/SVG/RGBA bundle и edit replay.
• Ключевой продуктовый принцип: чистый независимый слой важнее минимального reconstruction MAE. Поэтому baked poster shadows не копируются как RGB-часть объекта, даже если их удаление увеличивает MAE собранного исходника.
• Последние зафиксированные изменения:
  • 7981e4a: gated BiRefNet уточняет alpha проверенных bottle/umbrella;
  • 36a52f0: Linux deployment использует CPU-only PyTorch wheels, macOS — MPS;
  • 5123560: Linux DejaVu/Liberation fallback устранил OCR-related HTTP 500;
  • 47faa2a: web UI получил отдельную вкладку перемещения объектов.
• Проверенные golden cases: R07 cat без регрессии; R09 shirts имеет три чистых независимых cutout, отдельные headline/CTA и чистый background; R05 portrait сохраняет мягкий контур волос; R08 содержит SAM-completed office desk.
• Ближайший технический приоритет: open-vocabulary discovery объектов, для которых COCO detector не создаёт seed (шкаф и правый факел R08), затем occlusion-aware/amodal completion для hide/delete и сохранение UI transforms в scene graph/экспорт.

ADR-001 — Строим редактируемый документ, а не набор красивых масок

• Статус: accepted.
• Решение: канонический результат — versioned JSON scene graph, RGBA assets, SVG и renderer. PSD остаётся возможным экспортом, но не источником правды.
• Причина: одинаково правдоподобных разложений может быть несколько; полезность определяется операциями delete/move/recolor/replace-text и сохранностью остальных пикселей.
• Следствие: reconstruction MAE необходим, но недостаточен; нужен edit replay.

ADR-002 — Сначала синтетический контролируемый baseline

• Статус: accepted.
• Решение: генерировать flattened layouts из заранее известных слоёв, отдельно держать train/validation/frozen test и независимые фото/шрифты в test.
• Причина: маски, z-order и ожидаемые правки получаются почти бесплатно.
• Ограничение: synthetic score не доказывает качество на пользовательских изображениях; реальные hard cases образуют отдельный regression set.
• Evidence: experiments/006_mvp_acceptance и experiments/012_realistic_v2_final.

ADR-003 — Локальный гибридный pipeline вместо одной генеративной модели

• Статус: accepted.
• Решение: объединять OCR, design primitives, semantic instance masks, selector, background completion и verifier.
• Причина: это быстрее, дешевле и аудируемее монолитной генерации, а каждый провал можно отнести к конкретной подсистеме.
• LayerD оставлен медленным fallback, а не основным engine: в первом sweep он был слабее и существенно медленнее.

ADR-004 — Обучаем маленький ranker на proposal features

• Статус: accepted.
• Решение: Random Forest ранжирует геометрические и цветовые proposals; пороги выбираются на validation, frozen test не участвует в настройке.
• Причина: на текущем объёме данных это воспроизводимый baseline без дорогого fine-tuning большой vision-модели.
• Пересмотр: когда появятся размеченные trajectories и edit-replay labels, заменить эвристику на next-layer ranker и stop head.

ADR-005 — Text-first, но с явным ownership

• Статус: revisit.
• Первоначальное решение: распознанный текст удаляется из растра, фон восстанавливается, затем создаётся live TextLayer.
• Обнаруженная проблема: OCR-inpaint портит принты на одежде, стилизованные заголовки и CTA внутри цветных carrier-элементов.
• Текущее решение: классифицировать OCR-линии как live text, object_texture, styled_headline или graphic_carrier. Последние три сохраняются пиксельно, пока render-and-fit не докажет безопасную замену.
• Компромисс: текст остаётся читаемым, но часть надписей пока не редактируема.
• Evidence: commit afae64e, experiments/019_shirts_text_ownership.

ADR-006 — Semantic candidates и аудируемый selector

• Статус: accepted.
• Решение: Mask R-CNN и design proposals образуют общий неизменяемый pool; selector последовательно принимает полезные слои и пишет причину каждого accepted/rejected/skipped/stop решения.
• Причина: photo objects нельзя надёжно извлечь только цветовой кластеризацией, а диагностический trace нужен для обучения и поиска regressions.
• Evidence: commit 9c9f0ce, experiments/016_iterative_semantic.

ADR-007 — SAM используется как optional class-agnostic refiner

• Статус: accepted.
• Решение: SAM уточняет найденные маски и добавляет крупные объекты вне уверенного COCO-словаря; без checkpoint pipeline продолжает работать.
• Причина: Mask R-CNN пропускает пальмы и путает design elements с COCO-классами.
• Ограничение: SAM способен объединить соседние объекты или съесть тонкие волосы; поэтому его mask не считается финальным alpha matte.

ADR-008 — Quality background через Big-LaMa, Fast как fallback

• Статус: accepted.
• Решение: Quality использует локальный Big-LaMa, расширенную halo-safe mask, согласование blur/зерна и feather blending. Fast остаётся локальным Telea/Navier–Stokes fallback.
• Причина: Telea создавал радиальные клинья после удаления крупных объектов.
• Ограничение: completion не исправляет неполную object mask; большие окклюзии, волосы и прикреплённые тени всё ещё требуют amodal/shadow ownership.
• Evidence: commit fe61f0b, experiments/018_background_v4.

ADR-009 — Анализ ограничен 1024 px, финальные пиксели полноразмерные

• Статус: accepted.
• Решение: web-path уменьшает длинную сторону до 1024 px для анализа; source, canvas и экспорт остаются в native resolution, когда pipeline вызывается напрямую.
• Причина: контролируемая CPU latency и память.
• Риск: мелкий текст и тонкие разрывы масок ведут себя иначе, чем при полном разрешении; UI-path обязан иметь собственную регрессию.

ADR-010 — Не удалять найденные объекты перед следующим detector pass

• Статус: rejected для destructive iteration.
• Рассмотренный вариант: после каждого найденного слоя делать inpaint и снова запускать detector.
• Причина отказа: последующие проходы начинают анализировать сгенерированные пиксели и могут повышать артефакты до объектов.
• Текущее решение: источник неизменяем; если одна proposal mask содержит несколько крупных островов, тонкий ложный мост разрывается, затем mask делится по connected components. Рекурсивно можно разбирать только выбранный compound layer, не изменяя исходный canvas.

ADR-011 — Grounding DINO + SAM только как целевой fallback

• Статус: revisit.
• Решение: не добавлять ещё один detector в каждый запрос. Вызывать open-vocabulary grounding только для крупной неоднозначной маски, которая не проходит topology/edit-independence проверку.
• Причина: deterministic component split уже исправил shirts-case без цены дополнительной 0.2B-модели; касающиеся объекты этим способом не разделить.

ADR-012 — Пользовательские hard cases являются release-gate

• Статус: accepted.
• Решение: девять примеров из интерфейса фиксируются как именованный regression set с проверками текста, object count, ложных объектов и delete/hide replay.
• Причина: средние synthetic-метрики скрыли регрессии Editorial, Glass card, Bold type, волос, CTA и сложного office/beach composite.
• Следствие: изменение нельзя принимать только по reconstruction MAE или одному исправленному изображению. Полный контракт описан в REGRESSION_SUITE.md.

ADR-016 — Point-prompted SAM completion для неполных объектов

• Решение: для сильных bottle/person/chair/plant/umbrella proposals запускать SAM не только с box, но и с положительной точкой. Принимать completion лишь при recall исходной mask не ниже 0.90 и росте площади не меньше 2%.
• Причина: box prompt повторяет усечённый detector box; point prompt смог достроить флакон вместе с пипеткой.
• Ограничение: SAM quality не является доказательством правильности COCO label. Итоговый score сохраняет semantic prior исходного detector seed.
• Статус: accepted.

ADR-015 — Не удалять тень, пока она не принадлежит слою

• Решение: основной decomposition path отключает attached shadows; halo expansion уменьшен примерно с 1.5% до 0.5% длинной стороны.
• Причина: расширенная тень удалялась из background, но не возвращалась ни одним layer, поэтому даже полностью включённая сцена не могла восстановить original.
• Результат: office+beach reconstruction MAE снизился с 9.1826 до 2.1721 в сопоставимом Fast-прогоне.
• Статус: accepted; тень позже должна стать child/compound asset.

ADR-017 — Чистый poster background и residual-matte принадлежат объекту

• Статус: accepted как консервативный специальный путь.
• Решение: для сцен с минимум тремя крупными раздельными объектами сходного размера на спокойном фоне строить более широкую inpaint-маску только для background. Удалённые тени и краевой residual возвращаются в RGBA ближайшего объекта минимальным difference-matte.
• Gate: значимые semantic masks занимают 7.5–24% изображения каждая, их не меньше трёх, размеры согласованы, суммарное покрытие не ниже 28%, edge density видимого фона не выше 0.16, итоговая cleanup mask не выше 86% canvas.
• Ownership: residual partitioned по ближайшему объекту; пиксели других accepted object/design layers защищены и не могут приклеиться к футболке.
• Причина: тесная alpha mask оставляла на background три тёмных силуэта, а простое расширение без ownership ухудшало собранную сцену.
• Evidence: shirts background mask 61.94% → 80.73%, reconstruction MAE 1.7647 → 1.5524; полный quality regression 9/9, cleanup включился только на R09-shirts. 42 unit/integration tests pass.

ADR-018 — Вложенный semantic motif принадлежит raster-объекту

• Статус: accepted.
• Решение: маленький semantic-кандидат классов, типичных для принтов (teddy bear, animals, ball, kite), отклоняется как самостоятельный слой, только если он почти полностью лежит внутри уверенной alpha крупного объекта, занимает не более 8% его площади и окружён parent-mask.
• Причина: принт панды синей футболки принимался как отдельный Teddy Bear и оставался висеть в воздухе после hide shirt.
• Защита реальных объектов: если parent alpha исключает предмет перед человеком или маска не окружена parent support, child сохраняется самостоятельным.
• Evidence: R09-shirts 8 → 7 editable layers, MAE неизменен 1.5524; полный quality regression 9/9, обе птицы R08 сохранены; 43 tests pass.

ADR-019 — Portrait matting применяется только при согласии с instance mask

• Статус: accepted.
• Решение: локальный MODNet ONNX запускается, только когда selector выбрал ровно один semantic layer person. Soft matte не заменяет instance mask, а лишь добавляет детали в ограниченной окрестности исходного силуэта.
• Gate: matte занимает 2–55% canvas, сохраняет не менее 85% исходного person и не менее 80% своего foreground подтверждает исходной mask. Иначе результат отклоняется как incompatible_prediction без изменения слоя и background.
• Причина: Mask R-CNN/SAM теряли внешние пряди волос; голый MODNet на постере с футболками ошибочно считал foreground 67% изображения.
• Модель: MODNet, Apache-2.0; ONNX 25.9 MB загружается в ignored cache и проверяется SHA-256 07c308cf0fc7e6e8b2065a12ed7fc07e1de8febb7dc7839d7b7f15dd66584df9.
• Evidence: полный quality regression 9/9; R05 MAE 0.4007 → 0.1219, R01 3.0505 → 2.8482, R03 2.3117 → 2.2155. Gate отклонил R02/R04 и не запускался для R08/R09. Добавленная CPU latency 0.11–0.14 с; 46 tests pass.

ADR-020 — Слабая furniture seed принимается только после SAM completion

• Статус: accepted для компактного dining table.
• Решение: table seed с detector score от 0.25 и площадью не более 10% canvas получает приоритет внутри ограниченного point-prompted SAM budget. Selector снижает порог только для completed-dining-table с SAM stability не ниже 0.80 и площадью не более 12%; сырой слабый detector-кандидат не принимается.
• Причина: R08 уже содержал почти правильную маску офисного стола, но COCO detector давал score 0.352 ниже общего порога. Positive point позволил SAM достроить столешницу и тумбу без глобального снижения precision.
• Защита: крупные table/surface masks по-прежнему отклоняются; ложный table в R06-product остался low_confidence_large_surface.
• Evidence: R08 25 → 26 layers, SAM stability 0.9353, bbox включает стол и тумбу; полный quality regression 9/9, R07/R09 без изменений, 48 tests pass. Reconstruction MAE R08 1.7849 → 1.9127 — допустимая цена нового soft edge; hide desk всё ещё требует amodal completion человека за столом.

ADR-021 — Poster shadows не являются RGB-продолжением объекта

• Статус: accepted.
• Решение: в gated repeated-object poster path residual может быть только гладким нейтральным затемнением с alpha не выше 0.16. Bright seams, цветные остатки и channel-ratio-inconsistent пиксели не получают ownership объекта.
• Дополнение: до и после residual composition крупная product alpha уточняется GrabCut. Уверенное эродированное ядро задаёт foreground, внешнее кольцо — background; refinement принимается при сохранении минимум 76% исходной mask. Внутренность принятого силуэта уплотняется до alpha 245, мягкой остаётся лишь внешняя граница.
• Причина: solved RGB residual приклеивал к серой футболке второй полупрозрачный низ, а к синей — яркий ореол. Часть тени уже находилась внутри detector alpha, поэтому одной фильтрации residual было недостаточно.
• Product trade-off: переносимая чистая alpha важнее pixel-perfect повторения baked shadows. R09 Quality MAE вырос 1.5524 → 3.0278, но три RGBA cutout визуально чисты на тёмном и светлом фоне.
• Evidence: полный quality regression 9/9; refinement применился только к трём футболкам R09, остальные восемь кейсов сохранили прежние метрики; 51 test passes.

ADR-022 — Все SAM completion masks проходят instance component split

• Статус: accepted.
• Решение: disconnected-component split применяется и к refined, и к completed SAM proposals до замещения detector-кандидатов. Дополнительно selector отклоняет крупный completed-кандидат, если тот содержит как минимум две непересекающиеся selectable same-label instances.
• Причина: на Apple MPS point-prompted SAM completion футболки возвращал одну mask с двумя крупными несвязанными компонентами. Она принималась раньше отдельных detector/refined masks и объединяла центральную и правую футболки, одновременно захватывая правую растительность. CPU случайно не проявлял этот дефект, поэтому device-only smoke test был недостаточен.
• Evidence: R09 на MPS снова даёт три независимые футболки, две Potted Plant, headline и CTA; automatic gate pass, 7 editable layers. MPS Fast regression R05/R06/R08/R09: 4/4 pass; 55 tests pass.

ADR-023 — BiRefNet используется как gated instance-aware alpha refiner

• Статус: accepted для узкого runtime allowlist.
• Решение: проверить ZhengPeng7/BiRefNet_HR-matting как уточнитель soft alpha после Mask R-CNN/SAM. BiRefNet запускается не на всей сцене, а на crop уже выбранного instance с контекстом; результат принимается только при согласии с исходной instance mask и при отсутствии захвата соседних выбранных объектов.
• Причина: BiRefNet обучен для high-resolution foreground/background segmentation и matting с отдельной reconstruction-веткой и gradient supervision. Это перспективно для волос, шерсти, листьев и краёв одежды, но сама модель не решает поиск и разделение нескольких слоёв, OCR или inpainting.
• Сравнение: исходная SAM/Mask R-CNN alpha, текущий gated MODNet, BiRefNet-matting 1024 и BiRefNet_HR-matting 2048 на R01/R03/R05/R07/R09, а также product/plant crops из R06/R08. Gate измеряет boundary quality, сохранность interior, рост за пределы seed, захват соседей и hide replay.
• Runtime gate: включены только визуально подтверждённые классы bottle и umbrella. Остальные классы сохраняют прежний путь; модель не запускается.
• Deployment: checkpoint хранится вне Git и устанавливается отдельно через scripts/download_models.py --birefnet. Локальный инстанс использует MPS, публичный demo-server — принудительно CPU; на обоих BiRefNet включается только при наличии проверенного checkpoint и только для runtime allowlist. Для Linux uv получает torch и torchvision из официального PyTorch CPU index; это исключает установку CUDA runtime на CPU-only demo-host. На macOS зависимости продолжают разрешаться из PyPI и сохраняют MPS.
• Device parity: на фиксированном 1024 crop CPU и MPS дали support IoU 1.0; различались два alpha-пикселя на 1/255.
• Лицензия: официальный код и выбранные веса помечены MIT; не использовать briaai/RMBG-2.0, чьи веса имеют non-commercial ограничения.
• Evidence: experiments/024_birefnet_alpha; полный MPS Quality regression 9/9, 61 tests pass. R06 MAE 0.1925, R08 MAE 1.8237, R09 unchanged. End-to-end запрос R06 через /v1/preview вернул два слоя, применил refinement к bottle за 2.785 с на MPS и прошёл встроенную verification без warnings. После deployment тот же запрос на demo-server вернул два слоя и accepted refinement без warnings; холодный BiRefNet CPU-проход занял 35.665 с.

ADR-024 — Подбор live-font обязан быть кроссплатформенным

• Статус: accepted.
• Решение: default font candidates содержат системные пути macOS Arial/Verdana/ Georgia и Linux DejaVu/Liberation. Отсутствующие файлы пропускаются, fit выполняется по доступному подмножеству.
• Причина: CPU demo-host успешно проходил детекторы и OCR на R08 office+beach, но падал в самом конце /v1/preview с HTTP 500: fit_text_line() видел только macOS-пути и сообщал No font candidates are available.
• Evidence: после deployment R08 через внутренний API и публичный HTTPS вернул HTTP 200, 28 слоёв, один live-text layer и verification accepted. Полный CPU-запрос занял около 111 секунд; suite — 63 tests pass.

ADR-025 — Перемещение слоёв начинается как клиентская edit-preview операция

• Статус: accepted как промежуточный UI baseline.
• Решение: рядом со «Слои» добавлена вкладка «Редактор». Для каждого raster- и text-layer браузер хранит dx/dy; фон неподвижен. Объект можно тянуть мышью, двигать стрелками на 1 px или с Shift на 10 px и вернуть все позиции одной кнопкой. Координаты ограничиваются canvas, видимость и редактирование текста продолжают работать через общий state.
• Причина: возможность проверить независимость и качество cutout при движении — более содержательная edit-replay метрика, чем одна реконструкция исходника.
• Ограничение: transforms пока живут только в текущей browser session и не записываются в document.json или скачиваемый ZIP. Следующий этап — сделать позицию частью scene graph и рендеринга/экспорта.
• Evidence: визуальный тест в локальном UI переместил bottle на +146/-55 px; рамка и RGBA синхронны. Reset вернул нулевую позицию, клавиатурный тест дал +1/+10 px. Интерфейс развёрнут локально на MPS и публично на CPU.

ADR-014 — SAM mask quality не заменяет category plausibility

• Решение: refined SAM proposal наследует confidence исходного detector seed и получает semantic-prior penalty; bird и cat требуют усиленного evidence.
• Причина: SAM мог дать технически устойчивую mask сухоцвета и поднять ложный cat до 0.98, хотя исходный COCO seed имел confidence около 0.10.
• Статус: accepted.

ADR-013 — Pixel-faithful compound design layers

• Решение: styled headline, CTA carrier и длинные editorial strokes извлекаются как отдельные raster design layers с точной исходной текстурой. OCR ownership записывает конкретный owner id.
• Причина: live-font recreation портила фирменный шрифт, а глобальная защита оставляла headline/CTA навечно в background или дырявила carrier.
• Статус: accepted.