COMPO POSTER ENGINE
ПЛАН И ТЗ / START PROJECT
Версия: 0.2 API-first architecture / SOL audit revision
Дата: 2026-08-24
Статус: AUDIT-G0 PASS; READY FOR LUNA IMPLEMENTATION

===============================================================================
1. ПАСПОРТ ПРОЕКТА
===============================================================================

Проект: COMPO Creative Engine / Poster Engine
Тип: API-first сервис и отдельный SUBPLAN поверх существующего COMPO и Workbench
Цель: принимать графические материалы и человеческий brief, анализировать их,
подбирать/создавать визуальные элементы и собирать проверяемый visual draft.

Продукт с самого начала позиционируется как композиционный мотор. Веб-сайт —
один из клиентов. Другими клиентами являются Figma plugin, Hermes/SMM,
внешние приложения и пакетные content-plan процессы. Все клиенты используют
один versioned API и не реализуют собственную композиционную логику.

Главное ограничение: Poster Engine не переписывает canonical Topics 1–72 и не
получает право автоматически менять COMPO CANON. Он выпускает draft, evidence,
trace и human-review result.

Конечный результат для владельца или внешней системы:
1) загрузить исходные изображения или выбрать материалы из графической базы;
2) описать задачу простыми словами;
3) получить анализ объектов, цвета, геометрии и семантических рисков;
4) получить один или несколько poster drafts;
5) понять, почему элементы поставлены именно так;
6) утвердить, отклонить или исправить результат;
7) передать результат другой ИИ в виде ссылки на HTML и JSON.
8) получить редактируемую CompositionScene для Figma или другого renderer.
9) отправить пакет задач из content plan и получить отдельный job на каждый item.

===============================================================================
2. ДЛЯ ВЛАДЕЛЬЦА — КАК ЭТО РАБОТАЕТ
===============================================================================

ВХОД:
изображение/набор изображений + текстовая задача + ограничения формата.

АНАЛИЗ:
а) image-vision слой описывает объекты, лица, текст, глубину, возможные
семантические конфликты и важные области изображения;
б) deterministic image-metrics слой измеряет размеры, bounding boxes, цветовые
массы, контраст, пустое поле, края, выравнивания и пересечения;
в) text-AI слой переводит brief в роли: dominant, support, accent, text zone,
background, forbidden overlap;
г) COMPO rules дают проверяемые ограничения, но не выдумывают отсутствующую
семантику.

СБОРКА:
composition planner строит несколько bounded candidates. Flux Klein на SRV1
может создать только явно разрешённый новый визуальный материал или расширить
фон; исходные пользовательские иллюстрации не изменяются без отдельной команды.

ВЫХОД:
CompositionScene + draft PNG/WebP + machine-readable manifest + image analysis
+ WHY/WHY-NOT trace + human review record. CompositionScene содержит элементы,
роли, координаты, constraints и provenance; Figma/raster/HTML являются разными
renderer adapters. Публичная публикация результата не происходит без
owner-gated действия Workbench.

===============================================================================
3. ФАКТИЧЕСКОЕ СТАРТОВОЕ СОСТОЯНИЕ
===============================================================================

Локально обнаружено:
- deploy/workbench/server.py — Workbench HTTP service;
- deploy/workbench/image_adapter.py — validation и Flux adapter;
- deploy/workbench/image_metrics.py — deterministic image measurements;
- deploy/workbench/canon_state.py — read-only derived CANON state;
- deploy/workbench/smoke_test_*.py — smoke tests для image/runtime;
- deploy/workbench/workflows/COMPO_TEXT_TO_IMAGE_FLUX2_KLEIN_4B_v1.json;
- deploy/workbench/workflows/COMPO_TEXT_TO_IMAGE_FLUX2_KLEIN_9B_v1.json;
- опубликованы image review, image evidence, metrics, comparison и feedback
  страницы Workbench.

server2 (live):
- Ubuntu Server; /mnt/ssd_projects: около 860 GB свободно;
- compo-workbench.service active; адрес процесса 127.0.0.1:8110;
- Workbench status: CONTRACT_ONLY; runtimeReady=false;
- registry: PARTIALLY_RUNNABLE; 4 сценария;
- systemd sandbox: отдельный пользователь, NoNewPrivileges, ограниченные пути
  записи; публичные результаты отделены от приватных.

SRV1 (live):
- Ubuntu Server;
- NVIDIA GeForce RTX 5070 Ti; 16303 MiB VRAM; driver 570.211.01;
- ComfyUI отвечает на 192.168.0.114:8188;
- ComfyUI 0.12.0; PyTorch 2.10.0+cu128; Flux workflows доступны через
  server2 adapter.

Графическая база:
- локальная папка C:\Users\Ivan\Downloads\= содержит 72 объекта;
- среди них: 70 botanic dither, grained/blurred shapes, halftone paper,
  marble ink, wood and paint, 3d lines, tech innovations и отдельные PNG/JPG;
- исходная папка Telegram Desktop сохранена; папка = используется как рабочая
  копия библиотеки.

Неподтверждено:
- проект 24_img_Vision имеет API contract и Figma plugin foundation, но gateway
  сейчас не запущен; порт 8765 занят сервисом другого проекта;
- используемый ранее vision backend ошибся в контрольном OCR: IEK → TEK/TK;
- нет доказанного стабильного production vision model и benchmark для
  композиционных/семантических вопросов;
- нет утверждённого storage/retention policy для больших исходных изображений;
- нет production-grade poster composition runtime;
- нет benchmark на реальном наборе пользовательских материалов.

===============================================================================
4. SOURCES OF TRUTH
===============================================================================

Код и тесты Workbench → фактическое поведение runtime.
Live systemd/nginx/ComfyUI → текущая инфраструктура.
COMPO MAIN/CONTEXT и machine-data → canonical rules и ownership.
Эта спецификация → границы Poster Engine и порядок реализации.
OWNER decisions → право публикации, коммерческие/приватные материалы и final
human approval.

При конфликте сначала фиксировать конфликт, затем выбирать более сильный
источник. Не подменять UNVERIFIED догадкой.

===============================================================================
5. АРХИТЕКТУРА И DATA FLOW
===============================================================================

CHANNEL CLIENT: Web | Figma | Hermes | External API | ContentBatch
  → Creative Request API (auth, tenant, idempotency, profile version)
  → Asset intake (hash, mime, dimensions, provenance)
  → CreativeProfile resolver (explicit + inferred + derived preferences)
  → Vision analysis (objects, text, faces, semantic regions)
  → Deterministic metrics (geometry, color, contrast, edges, whitespace)
  → Brief interpreter (roles, intent, constraints)
  → Candidate planner (bounded layout candidates)
  → Optional Flux generation (allowlisted, owner-gated)
  → CompositionScene (editable, renderer-neutral)
  → Figma | Raster | HTML renderer (draft only)
  → Validator + trace (WHY/WHY NOT, warnings, N/A)
  → Human review
  → Private result HTML/JSON
  → Optional public publication or return to requesting client.

Один слой не присваивает себе ownership метрик другого слоя. N/A не равен 0.
Семантическое предположение не становится геометрическим фактом без provenance.
Клиентский адаптер не содержит собственной копии COMPO rules.

===============================================================================
6. ПОЛНЫЙ ПЛАН ФАЗ И АТОМАРНЫХ TASK
===============================================================================

PHASE-01 — Discovery и контракт (текущая)
TASK-001 DONE: снять live/local inventory, определить sources of truth.
  Acceptance: зафиксированы факты server2, SRV1, Workbench, графической базы и
  явные UNVERIFIED области; секреты не раскрыты.
TASK-002 READY: заморозить контракт первого сценария IMAGE-POSTER-DRAFT-001.
  Вход: один PNG/JPG/WebP + brief + canvas size.
  Выход: validated asset manifest и draft request без исполнения.
  Acceptance: schema validation, hash, размер, mime, bounded limits, N/A cases.
TASK-003 PLANNED: определить vision adapter boundary и schema.
TASK-004 PLANNED: определить deterministic metrics schema и provenance.
Checkpoint CP-01: контракт и границы не позволяют произвольный код, SSH или
автоматическую мутацию CANON.

PHASE-02 — Foundation и reusable analysis
TASK-005: asset intake, hashing, safe storage reference.
TASK-006: image-metrics adapter для geometry/color/contrast/whitespace.
TASK-007: vision-result schema с confidence, evidence и human override.
TASK-008: brief-to-roles interpreter; draft only.
TASK-009: golden fixtures на 5 синтетических и 3 реальных разрешённых изображениях.
SOL AUDIT-G1: data contracts, privacy, provenance, storage и rollback.

PHASE-03 — Candidate composer
TASK-010: bounded poster candidate schema.
TASK-011: layout candidates на существующих COMPO rules.
TASK-012: semantic collision warnings: лицо/текст/объект/край/негативный смысл.
TASK-013: renderer draft HTML/PNG/WebP.
TASK-014: WHY/WHY-NOT trace и deterministic replay.
SOL AUDIT-G2: первая полная петля input → analysis → candidate → trace.

PHASE-04 — Generation bridge
TASK-015: allowlisted Flux Klein request adapter.
TASK-016: prompt/provenance/seed/result manifest.
TASK-017: web optimization без перезаписи исходника.
TASK-018: owner-gated private result publication.
SOL AUDIT-G3: SRV1 boundary, resource limits, privacy, failure/rollback.

PHASE-05 — Human feedback и handoff
TASK-019: упрощённый human review без обязательного длинного текста.
TASK-020: feedback JSON и связи с candidate/trace.
TASK-021: AI-readable handoff page для автора основных COMPO-текстов.
TASK-022: benchmark и acceptance report.
SOL AUDIT-G4: перед экспериментальным публичным запуском.

BACKLOG, не включать в текущую реализацию:
- обучение собственной нейросети на собранных данных;
- автоматическое изменение canonical Topic modules;
- unrestricted agent, произвольные shell-команды и автоматический SSH;
- массовое публичное хранение пользовательских изображений;
- полноценный коммерческий SaaS.

===============================================================================
7. REUSE MATRIX И SPIKE
===============================================================================

ADOPT/PATTERN:
- Workbench owner-gated command/preview/execute boundary;
- image_adapter.py validation и Flux workflow;
- image_metrics.py как базовый deterministic слой;
- private result HTML/JSON и duplicate protection;
- existing COMPO machine-data и provenance conventions.

SPIKE до крупной реализации:
- vision model/API: сравнить доступные варианты на 8 изображениях;
- image storage: сравнить local private storage и object-like path reference;
- renderer: проверить standalone HTML/Canvas против существующего renderer;
- queue: не вводить очередь, пока bounded runtime не покажет необходимость.

Для каждого SPIKE записать license, security, compatibility, maintenance,
benchmark и решение ADOPT/ADAPT/PATTERN/REJECT.

===============================================================================
8. ОГРАНИЧЕНИЯ, SECURITY, ROLLBACK
===============================================================================

Нельзя хранить в документах password, token, cookie, private key или secret env.
Vision input может содержать PII; по умолчанию результаты private.
Публичный URL только после owner gate.
Генерация ограничена allowlist workflow, размерами, steps и timeout.
Исходники не перезаписываются; каждый draft имеет hash и runRef.
Rollback: удалить/скрыть draft reference и вернуть предыдущий manifest; исходный
asset остаётся неизменным.

Owner gates: paid API, production deploy, DNS/firewall, публикация private data,
изменение внешнего API и irreversible deletion.

===============================================================================
9. MODEL ROUTE И CHECKPOINTS
===============================================================================

Luna / GPT-5.6 MEDIUM: discovery, implementation, tests, docs, benchmarks.
Sol / GPT-5.6 HIGH: AUDIT-G0 после discovery, G1 contracts/security, G2 full
loop, G3 generation bridge, G4 public readiness.
Маршрут: LUNA → SOL → LUNA. Следующая точка после этого файла: AUDIT-G0.

На текущем шаге нет доказательства browser/CDP run record: статус browser
verification = NOT_PROVEN.

===============================================================================
10. CURRENT TASK / NEXT ACTION
===============================================================================

Current phase: PHASE-01 API-first architecture freeze.
Current task: TASK-009 READY.
Required model: LUNA_MEDIUM.
Current audit gate: AUDIT-G0 PASS.
Next exact action: проверить CreativeJob и CompositionScene state machine:
transitions, artifacts, review и failure states.

TASK-023 выполнен: 4 versioned JSON schemas, channel boundary и smoke-test.
Теперь выполнить TASK-024 CreativeProfile и TASK-025 CreativeJob /
CompositionScene state machine; затем возвращаться к TASK-002.

===============================================================================
10A. API-FIRST PRODUCT CONTRACT — AMENDMENT v0.2
===============================================================================

Стабильная граница продукта:

COMPO Creative Engine API
  принимает CreativeRequest / ContentBatch
  разрешает CreativeProfile
  создаёт CreativeJob
  возвращает CompositionScene и render artifacts
  хранит trace, provenance и review state.

Каналы:
- Web App: простой заказ, onboarding, профиль, review и скачивание;
- Figma Plugin: отправляет selection/assets и получает редактируемые nodes;
- Hermes Adapter: получает content-plan items и возвращает visual candidates;
- External API/SDK: submit, status, artifact, review, webhook;
- Admin/Workbench: capability status, audit, replay, private evidence.

API v1 должен поддерживать:
- POST /v1/creative-jobs;
- POST /v1/content-batches;
- GET /v1/jobs/{job_id};
- GET /v1/jobs/{job_id}/artifacts;
- POST /v1/jobs/{job_id}/review;
- POST /v1/profiles;
- POST /v1/profiles/{profile_id}/versions;
- GET /v1/profiles/{profile_id}/versions/{version};
- POST /v1/connectors/figma/import и отдельный export callback contract;
- Hermes adapter как внутренний client, не прямой доступ к БД Hermes.

Обязательные свойства: versioning, tenant isolation, idempotency key, bounded
uploads, asynchronous jobs, retry policy, cancellation, safe status projection,
webhook signatures, quotas и capability discovery. Long-lived credentials не
хранятся в Figma plugin или браузере.

===============================================================================
10B. CREATIVE PROFILE — ПРЕДУСТАНОВКИ ПОЛЬЗОВАТЕЛЯ
===============================================================================

Предустановка называется CreativeProfile и всегда имеет immutable version.
Это не один непроверяемый prompt. Профиль собирается из отдельных слоёв:

1. explicit_preferences — ответы пользователя и прямые запреты;
2. brand_constraints — логотип, палитра, типографика, safe zones, каналы;
3. reference_assets — изображения с правами и назначением;
4. derived_visual_profile — измеренные цвета, плотность, ритм, формы;
5. inferred_preferences — выводы vision/text AI с confidence;
6. semantic_safety — лица, текст, товар, запрещённые перекрытия и смыслы;
7. channel_defaults — формат, поля, text density, platform overlays;
8. provenance — кто/что/когда создал каждое правило;
9. unresolved_questions — то, что нельзя считать установленным.

Правило приоритета:
explicit user rule > approved brand rule > approved derived rule > inferred rule.
Inference никогда молча не заменяет explicit preference. UNKNOWN сохраняется.

Onboarding имеет два режима:
- быстрый: пользователь сразу делает заказ, профиль optional;
- калибровочный: адаптивный опрос + reference images + серия сравнений.

После первого заказа сервис предлагает улучшить профиль, но не блокирует работу.
Опрос задаёт следующий вопрос на основании уже полученных ответов; одинаковые
вопросы не повторяются. Каждое изменение создаёт новую версию профиля, поэтому
старый результат можно воспроизвести.

===============================================================================
10C. CONTENT PLAN И BATCH MODE
===============================================================================

Ссылка на content plan не исполняется напрямую. Connector создаёт immutable
snapshot и нормализует его в ContentBatch:

- batch_id, source_type, source_ref, source_hash, profile_version;
- items[]: item_id, brief, channel, target_date, output_spec, source_assets;
- policy: max_concurrency, budget, review_mode, failure_mode;
- provenance и permission record.

URL, документ и внешний API считаются untrusted input. После изменения источника
создаётся новая версия batch. Один неудачный item не должен уничтожать остальные.
По умолчанию каждый результат ждёт human review; массовая auto-publication не
входит в первый релиз.

===============================================================================
10D. INTEGRATION FACTS И REUSE
===============================================================================

24_img_Vision:
- ADAPT API envelope, job/status pattern, user_question и Figma export helper;
- не копировать ad hoc HTTP-код — зависеть от shared contract/client;
- расширить vision result структурированными observations/confidence/evidence;
- точный OCR вынести в отдельную capability; текущий OCR benchmark FAIL;
- production gateway требует отдельного порта/service и live qualification.

Hermes:
- ADOPT content-plan/items как upstream source concept;
- ADOPT existing visual review, approved/draft states, outbox readiness и
  image-job provenance patterns;
- Poster Engine возвращает candidates/artifacts через adapter API;
- Hermes остаётся owner контент-плана, текста, расписания и публикации;
- Poster Engine владеет CreativeProfile, CompositionScene и composition trace;
- не писать напрямую в Hermes DB и не включать его disabled capabilities молча;
- интеграцию делать отдельным CR в dirty worktree только по точному allowlist.

Figma:
- первая интеграция импортирует selected frames/images;
- ответ должен содержать editable scene graph, а не только bitmap;
- plugin получает short-lived session/job token, не server credentials;
- domain allowlist и production endpoint оформляются отдельным deployment task.

===============================================================================
10E. ДОБАВЛЕННЫЕ АТОМАРНЫЕ TASK — ID НЕ ПЕРЕНУМЕРОВЫВАТЬ
===============================================================================

TASK-023 DONE: API-first service boundary и domain contracts; 4 schemas и smoke-test PASS.
TASK-024 READY: CreativeProfile schema, provenance, priority и versioning.
TASK-025 PLANNED: CreativeJob, CompositionScene, Artifact и state machine.
TASK-026 PLANNED: quick/adaptive onboarding questionnaire.
TASK-027 PLANNED: reference-image calibration и profile update proposal.
TASK-028 PLANNED: renderer-neutral editable CompositionScene schema.
TASK-029 PLANNED: Figma import/export adapter поверх 24_img_Vision helper.
TASK-030 PLANNED: Hermes content-plan adapter без прямой DB-связи.
TASK-031 PLANNED: ContentBatch snapshot/import connector.
TASK-032 PLANNED: external API auth, tenant isolation, quotas и idempotency.
TASK-033 PLANNED: webhook/status/SDK contract.
TASK-034 PLANNED: website quick-order + optional profile onboarding.
TASK-035 PLANNED: integration/load/privacy/retention acceptance suite.

Новая PHASE-06 — Channel adapters: TASK-029–034.
Новая PHASE-07 — Product hardening: TASK-032, TASK-033, TASK-035.

Dependency order:
TASK-023 → TASK-024 → TASK-025 → TASK-002/003/004 → PHASE-02 → PHASE-03.
Figma/Hermes/public API adapters не начинать до PASS первой полной private loop.

===============================================================================
11. ACCEPTANCE ДЛЯ ЭТОГО СТАРТОВОГО ПАКЕТА
===============================================================================

[x] Инструкция 4.1 прочитана.
[x] Local discovery выполнен.
[x] Live server2/SRV1 discovery выполнен.
[x] Workbench/ComfyUI/графическая база связаны в data flow.
[x] Canonical COMPO отделён от нового Poster Engine.
[x] Atomic task list и SOL gates определены.
[x] Secrets не записаны.
[x] HTML passport создаётся отдельно.
[x] 24_img_Vision и Hermes исследованы как reuse/integration sources.
[x] API-first, CreativeProfile, ContentBatch, Figma и Hermes contracts добавлены.
[x] Независимый SOL AUDIT-G0: PASS после amendment v0.2.

SOL VERDICT AUDIT-G0: PASS
Условия следующего этапа: сначала TASK-023/024/025; не подключать production
vision, Hermes DB, массовую генерацию или внешнюю публикацию до своих gates.