Node-граф

Типізований DAG-executor і canvas-редактор — нода не знає про граф, executor рахує хвилями.

Спрощений аналог ComfyUI: типізований DAG-executor плюс canvas-редактор. Користувач збирає граф із нод (текст, LLM, генерація зображень/відео/озвучки, монтаж), зберігає, запускає — воркер рахує граф хвилями, прогрес летить у браузер по WebSocket.

Ключова ідея: нода не знає про граф. Вона оголошує типізовані входи/виходи і run(); реєстр і executor роблять решту, а фронтенд малює ноду з даних GET /nodes. Додати ноду = написати клас (приклад — packages/kumquat-graphs/README.md).

Основні файли:

• packages/kumquat-graphs/src/kumquat_graphs/engine/ — рушій: ports.py, registry.py, graph.py (валідація + топосорт), executor.py, node.py, services.py, storage.py, factory.py (які графи потребують платних провайдерів і preflight балансу).
  • engine/nodes/ — самі ноди: text.py, flow.py, llm.py, media.py, compose.py;
  • engine/nodes/kie/ — каталог моделей і фабрика генеративних нод.
• kumquat_core/integrations/ — клієнти: kie.py (kie.ai), gemini.py / openrouter.py (LLM), s3.py. Прогрес і скасування приходять колбеками, тому клієнт не знає про рушій.
• kumquat_api/generation.py — збірка NodeServices на запуск (kie + S3 + LLM).
• kumquat_api/routes/graphs.py — графи, каталог нод і шаблони; graph_runs.py — запуски та WebSocket; graph_history.py — історія; graph_common.py — спільні перевірки.
• kumquat_api/worker/tasks.py — Celery-задача tasks.graphs.execute; worker/cache.py — кеш виходів (MongoNodeCache) і чекпойнти (MongoCheckpointStore).
• frontend/src/modules/canvas/ — редактор на @xyflow/react.

Порти й ноди

PortType: string, integer, float, boolean, object, image, video, audio. Сумісність ребра — строга рівність типів, неявних приведень немає.

InputPort(name, type, label, required, default, options, placeholder, ui_hint, is_list). options робить із входу <select>, is_list=True — порт бере цілий список (див. «Списки й фан-аут»), а ui_hint просить у канваса спеціальний віджет замість текстового поля:

repeatable=True — не порт, а шаблон: нода отримує стільки пронумерованих портів (videos_1, videos_2, …), скільки слотів їй задано власним параметром <name>_count (типово два, стеля 12). Кожен слот — окремий handle на канвасі, тож порядок склеювання це ребро, яке можна перетягнути, а не рядок у віджеті, який доводиться перебивати. Ноду це не стосується: collapse_inputs() віддає слоти в run() одним списком під іменем шаблону, а порожній слот у нього не потрапляє. Розгортання й згортання живуть у ports.py, а канвас дзеркалить те саме правило в inputSlots().

Нода — клас із node_type, title, category, description, inputs, outputs і async run(). Плюс прапорці: version (входить у fingerprint кешу), cacheable, generates (нода кличе модель — палітра сортує такі після звичайних) і requires — які поля NodeServices їй потрібні (kie, llm, media). run() отримує розв’язані входи як kwargs і мусить повернути dict рівно з оголошеними ключами виходів; значення мусять бути JSON-серіалізовними — вони їдуть у Mongo, кеш і WebSocket.

requires живе на самій ноді, а не в списку, який запуск звіряє окремо: інакше нову ноду легко забути в тому списку, і вона доїжджає до run() із порожнім ctx.services. required_services() у factory.py просто збирає об’єднання по нодах графа.

Реєстрація — декоратор @register_node у глобальний registry; падає на порожній/зайнятий node_type і на дублі імен портів. registry.specs() → GET /nodes → палітра фронтенду. Ноди підключає load_builtin_nodes(), який викликають обидва процеси (роут і воркер) — реєстри мусять збігатися.

Каталог нод

image/video/audio навмисно суміщають «джерело» і «прев’ю»: вставлений URL стає таким самим артефактом {"url": ...}, який віддають генеративні ноди, тож нижче по графу різниці немає.

Imagen 4 свідомо відсутній. І google/imagen4, і google/imagen4-fast віддають миттєвий 500 Internal Error (0 кредитів, ~1 мс) на будь-який payload, включно з документованим прикладом kie. Це не блок родини: google/nano-banana на тому ж ключі працює.

Списки й фан-аут

Це те, що робить із графа «дай N варіантів» замість однієї гілки.

• Список у скалярний порт (is_list=False) розмножує ноду: один виклик на елемент, усі паралельно. Скалярні виходи такої ноди стають списками, list-виходи конкатенуються (шість варіацій кожного з двох піків — це дванадцять варіацій, а не два списки по шість).
• Список у list-порт передається цілим — це спосіб працювати з колекцією. З одним винятком, і він вирішальний: якщо цей список — результат розмноженої гілки (скалярний вихід ноди, яка сама виконалась по разу на елемент), то list-порт теж розмножується, і кожен виклик отримує свій елемент. Інакше Join, під’єднаний до варіацій, склеїв би їх усі в один файл замість того, щоб дозбирати кожну.
• Списковий вихід розмноженої ноди — це колекція, а не елементи. vary.items віддає плаский список усіх варіацій, тож filter_items бачить його цілим. Різниця між двома випадками — чи вихідний порт is_list, і саме вона робить правило однозначним: обидва приходять як список, відрізняє їх лише походження.
• Скаляр у list-порт загортається в список з одного елемента, тож T -> list[T] не потребує коду в ноді.
• Кілька розмножених входів зіпуються за індексом; список із одного елемента бродкаститься на всі виклики. Саме це дозволяє compose(video_i, audio_i) звичайними ребрами, без сабграфа. Різні довжини (крім 1) — помилка, а не мовчазне обрізання.
• Порожній список = нуль викликів. Нода все одно завершується (item_count=0) і віддає порожні списки, тож уся гілка під нею коштує нічого. На цьому тримаються filter_items.
• Ліміти: MAX_NODE_FANOUT = 32 на ноду і MAX_RUN_INVOCATIONS = 512 на запуск. Обидва — про гроші, а не пам’ять: LLM, який відповів 400 варіантами, має завалити запуск, а не рахунок.

Кілька ребер в один вхід приймає лише list-порт: там ребра — це внески в один список, і конкатенація в порядку під’єднання — єдине, чим вони можуть бути. Усе інше бере одне значення; щоб склеїти кілька текстів, є нода concat_text, де порядок і сепаратор видно на канвасі, а не заховані в поведінці ребра.

Разом ці два правила дають те, заради чого вони існують: concat_video, у слоти якого заходять варіації і незмінне тіло ролика, робить по одному готовому файлу на варіацію — кліп цієї варіації плюс спільне тіло. Слот — звичайний скалярний порт, тож розмножена гілка в ньому розмножує й саму ноду, а тіло з одним значенням бродкаститься на всі виклики.

Порядок розв’язання входу: ребро > params > default порту. Немає нічого й порт обов’язковий → NodeExecutionError.

Пауза на людину

select_input не має вибору серед своїх входів — він його питає. Якщо на цю ноду ще немає відповіді, вона кидає RunPaused, запуск паркується в awaiting_input, а в документі лишається pending_input = {node_id, request} з питанням і показаними варіантами.

POST /runs/{id}/resume записує відповідь (індекси обраних варіантів) у мапу answers і ставить запуск у чергу знову. Граф виконується з нуля, але все вище відповідальної ноди читається з кешу, тож двічі за те саме ніхто не платить. Мапа (а не одне поле) — щоб граф із кількома воротами тримав попередні відповіді на кожному повторі. Сама нода cacheable = False: відповідь не є її входом, тож fingerprint не описав би результат.

Приклад: граф «Hook Variations»

Збережений граф у node_graphs — повний конвеєр варіацій хука для RockIn. Наразі націлений на креатив-talking-head 9:16 (ed959071…, «Zodiac Signs and Crystals to Avoid»): ведуча в машині з чорним турмаліном у руці, а далі — незмінне тіло ролика з інфографікою знаків зодіаку. Він же найкраща ілюстрація механік вище.

brief (text_prompt) ──system──> усі 6 LLM-нод
                              │
                           dimensions (llm_list, count=3)
                              │ items: [{dimension, current_value, channel}]
                              ▼
                           gate (select_input, multi)     ← людина обирає, що варіювати
                              │ selected: список об'єктів
                              ▼  (у скалярний порт context ⇒ фан-аут)
                           vary (llm_list, count=2)
                              │ items: {dimension, channel, value}, пласкі
        ┌─────────────────────┼─────────────────────┐
   visual_only            voice_only           overlay_only     (filter_items за channel)
        │                     │                     │
   frame + motion           line                 caption        (llm_text, фан-аут по елементах)
        │                     │
   nano_banana → clip      speech (TTS)
        │                     │
   visual_cut             voice_cut                             (compose_video)
   (clip + базове аудіо)  (базовий кліп + нова озвучка)
        │                     │
   visual_full            voice_full  ← body (незмінне тіло)    (concat_video)

Як це читається механіками рушія:

1. brief — один text_prompt, підключений у system усіх LLM-нод. Одне джерело правди про креатив замість шести копій промпта.
2. dimensions описує що є, а не що змінити: fields тут — рядки з редактора полів, де channel — закритий набір (video|voiceover|on-screen text), який провайдер зобов’язаний дотримати. Саме тому на це поле можна безпечно маршрутизувати.
3. gate паркує запуск. Оператор бачить три виміри й обирає, скажімо, два.
4. Два обрані об’єкти прилітають у скалярний context ноди vary → вона виконується двічі, по разу на вимір, кожен раз повертаючи count=2 варіанти. Її items — list-вихід, тож результати конкатенуються: на виході чотири варіації, а не два списки по дві.
5. Три filter_items розрізають ці чотири за channel. Вимір, якого ніхто не обрав, дає порожній список — і вся гілка під ним виконується нуль разів, безкоштовно.
6. Далі кожен llm_text знову розмножується — по разу на варіацію свого носія — і тягне за собою свою генерацію: frame → nano_banana → first_frame_url для clip, line → speech. Гілка caption закінчується текстом: екранний напис нічого не генерує.
7. compose_video мукситься проти незмінного базового треку: варіація озвучки бере старий кліп, а варіація відео лишає звук, який прийшов із самим кліпом (у Audio нічого не під’єднано). Так у A/B-тесті змінюється рівно один вимір.
8. concat_video доклеює тіло ролика до кожної варіації — те саме body на обидві гілки, бо скалярний вхід із одним значенням бродкаститься на всі елементи фан-ауту. На виході готовий до заливки mp4, а не самий хук.

Кеш і чекпойнти тут поелементні: змінили одну варіацію — переплачується тільки її гілка, решта приходить із кешу (подія node_cached з item_index).

Відео в графі рахується в 480p — на етапі тестування хука важливо, чи спрацювала ідея, а не роздільність; це ж і дефолт порту resolution.

Текстові ноди (LLM)

Провайдер налаштовується (LLM__PROVIDER): Gemini напряму або OpenRouter; LLM__MODEL іде з провайдером у парі, бо id моделі різні (gemini-3.1-flash проти google/gemini-3.1-flash). Клієнт синхронний (google-genai SDK), тому ноди кличуть його через asyncio.to_thread — інакше одна генерація тексту блокувала б увесь executor.

Кожна нода володіє своїм промптом: поле prompt — шаблон, {field} заповнюються з об’єкта context (списки й словники розгортаються в читабельний текст). Увесь context дописується під промпт незалежно від того, чи згадані його поля — названі просто повторюються рядком нижче. Раніше згадка одного поля відкидала решту, тож плейсхолдер, доданий для зручності, тихо звужував те, що бачила модель. Немає контексту — промпт береться дослівно, тож literal-фігурні дужки не ламаються. Невідоме поле — помилка з назвою поля. Порожні поля в дописаний блок не потрапляють. Це єдиний порт із ui_hint="template", тож канвас підсвічує в ньому {field} — видно, що саме приїде з контексту, ще до запуску.

llm_list додатково перетворює fields на JSON-схему відповіді. Форма одна — та, яку пише редактор полів на канвасі: [{"name": …, "type": "text|number|boolean|enum", "values": [...]}], і зберігається вона саме так — списком рядків, а не рядком JSON. Той самий рядок JSON parse_fields() теж читає: ним збережені старіші графи, і саме він приїжджає ребром у порт. enum — закритий набір, який провайдер зобов’язаний дотримати; це те, що робить поле придатним для маршрутизації через filter_items. Вільний текст замість рядків відхиляється, а не вгадується: схему, якої ніхто не обирав, провайдеру краще не відправляти.

Оголошені імена йдуть графом далі. Node.field_source каже, звідки нода бере ключі своїх object-виходів ("fields" — з власного редактора, "input:<порт>" — з того, що прийшло), а канвас іде цим уперед і показує кожній ноді, які {імена} їй доступні: невідомий плейсхолдер і невідома назва поля у pick_field/filter_items підсвічуються одразу, а не на запуску. Де вище нічого полів не оголошує, канвас мовчить — червона позначка, з якою нічого не зробиш, гірша за її відсутність.

Кількість іде і у схему (minItems == maxItems == count), і окремим реченням у промпт: схема обмежує відповідь, речення її пояснює. Стеля — 32 елементи.

Аналіз відео (VLM)

analyze_video дивиться кліп цілком — рух, монтаж і звук, а не окремі кадри — і повертає об’єкт із полями, які ви назвали тим самим редактором fields, що й llm_list. Це те, чого текстові ноди не вміють: вони читають запис про кліп, а кліп, за яким запису немає (щойно експортований монтаж, боді за URL), описувати нічим. Вихід — OBJECT, тобто та сама форма, яку бере порт context генеративних текстових нод: аналіз доходить до промптів так само, як Pack чи Creative.

Ключ і модель — ті самі LLM__*, але провайдер має бути саме Gemini: файл їде через Gemini Files API, чого OpenRouter не проксює. На LLM__PROVIDER=openrouter нода відмовляє і називає налаштування, а решта графа працює як раніше. Нода тягне файл із медіа-сховища на диск і віддає байти — провайдер не має доступу до нашого бакета, — а аплоуд видаляється одразу після відповіді, успішної чи ні.

Саме на цій ноді тримається шаблон «Hook from a brief and a body» — вісім нод в один рядок: тіло ролика → аналіз → бриф оператора → промпт хука → перший кадр → кліп → склейка з тілом. Ані фан-ауту, ані воріт: хук уже вирішений брифом, лишається зняти його.

Шаблони

kumquat-cli seed-template-graphs кладе на канвас три графи, з яких команда починає. Шаблон — це граф без власника і з template: true. Обидві половини важливі: правила запису й так відхиляють чужий граф («duplicate it to change it»), тож граф без власника лишається read-only для всіх без окремого правила, а прапорець тримає ці три поза особистими списками — у списку графів вони за власною вкладкою (GET /graphs?templates=only).

Кожен шаблон клонується з живого графа — визначення плюс його найсвіжіший успішний запуск, — тож відкривається на реальних результатах, а не на порожніх нодах. Джерела не змінюються: шаблон це копія, не конвертація. Повторний запуск команди освіжає шаблони на місці, лишаючи їм той самий id.

Генеративні ноди (kie.ai)

Провайдер — kie.ai Market API: єдина пара POST /api/v1/jobs/createTask → GET /api/v1/jobs/recordInfo?taskId= обслуговує всі моделі, тож integrations/kie.py — єдине місце, що знає формат провайдера. Стани задачі: waiting | queuing | generating | success | fail.

Одна нода = одна модель. Дискавері — задача палітри (пошук + групування за category), не дропдауна в ноді: у кожної моделі своя схема входів. Каталог (nodes/kie/catalog.py) — список ModelSpec; build_node() робить із кожного клас зі спільним run(). Додати модель = дописати ModelSpec: ні нового класу, ні змін у рушії, ні на фронті. node_type навмисно провайдер-незалежний (z_image, не kie_z_image) — це ключ у збережених графах; перейменувати його = осиротити всі графи, що на нього посилаються.

ModelPort описує, як порт потрапляє в input провайдера: скаляри — як є, медіа-порти віддають .url зі свого артефакту. Якщо формат моделі взагалі не «значення на порт», спек має build_input — так TTS показує на канвасі один рядок тексту, а провайдеру віддає каст і сценарій справжніми масивами.

Хід одного run():

1. є ctx.checkpoint["task_id"] → не створювати задачу, а дополлити наявну;
2. інакше createTask і зразу save_checkpoint({"task_id": ...});
3. poll() до термінального стану, форвардячи прогрес і перевіряючи скасування;
4. report_cost(creditsConsumed);
5. завантажити результат у S3, віддати артефакт {url, key, sha256, model, prompt}.

Помилки поділені так, як їх мусить трактувати викликач: KieFatalError (4xx, state=fail, відхилений промпт) — ретрай лише заплатить ще раз за ту саму відмову; KieTransientError (429/5xx, мережа, застій понад дедлайн) — ретрай із backoff.

recordInfo не повертає жодного відсотка — лише грубий state. Тому прогрес оцінюється: підлога за станом плюс асимптотичне наближення за часом (стеля 0.95, τ = 60 с). Він лише зростає й ніколи не досягає 1.0 — єдиний чесний сигнал завершення це термінальний стан. Стан їде в message, тож у вузлі видно слово, а не тільки число.

Кредити дробові (зображення ~0.8), тож усі поля — float. Тривалість ноди рушій міряє сам: costTime від kie показує 14 мс на картинку, тобто це не wall-clock.

Виконання лишається інлайн-полінгом у Celery: execute_graph має власні time_limit=3600 / soft_time_limit=3300, решта черг тримають свої жорсткі ліміти.

Сховище результатів

Провайдерські URL протухають, тож нода завантажує результат і кладе його в S3 під ключем від sha256 самих байтів: {ASSETS__GENERATED_PREFIX}/{sha256}/{node_type}.{ext}. Бакет і CDN ті самі, що в gdrive-sync — розділені лише префіксом (videos/ проти generations/). Однаковий контент перезаписує той самий об’єкт, тому ретрай ноди ідемпотентний. Роздача — CDN над бакетом (ASSETS__BASE_URL), стабільними публічними URL без presigning. В артефакті лежить і key, щоб URL можна було перерахувати, якщо CDN зміниться.

compose_video і concat_video користуються тим самим контрактом з іншого боку: fetch() кладе входи на диск, ffmpeg робить mp4, store_file() повертає його назад. ffmpeg уже є в образі воркера (пайплайн аналізу Drive), команди будуються чистими функціями, тож тестуються без бінарника.

concat_video бере по кліпу на пронумерований слот (repeatable, див. «Порти й ноди») — так само, як concat_text бере свої частини. Перед склеюванням нода вирівнює всі кліпи до найбільшого кадру й найвищої частоти з набору (менший вписується з полями, а не розтягується), а сегменту без звуку генерує тишу його довжини — інакше concat відмовиться зшивати сегменти з різною кількістю потоків.

Окремої моделі ассета (галерея, provenance, дедуп між запусками) немає — тільки сховище.

Витрати: creditsConsumed пишеться на ноду і $inc-ом у суму запуску. Кеш-хіт додає 0. Перед платним запуском воркер перевіряє баланс проти KIE__MIN_CREDIT_BALANCE і валить запуск ще до running. Граф без генеративних нод не потребує ні ключа, ні бакета — незібрана можливість лишається None, і про неї скаржиться саме та нода, якій вона знадобилась.

Виконання

Граф приходить із фронтенду як JSON; params ключуються іменами вхідних портів (окремого простору налаштувань ноди немає):

{
  "nodes": [{"id": "n1", "type": "text_prompt", "params": {"text": "cat"}}],
  "edges": [{"source": "n1", "source_output": "text",
             "target": "n2", "target_input": "prompt"}]
}

validate_graph() перевіряє унікальність id, відомість type, існування портів, рівність типів і кількість ребер на вхід; усі помилки збираються в один GraphValidationError. topological_order() — Kahn із детермінованим порядком, цикл → та сама помилка.

Виконання хвилями: кожна ітерація бере всі ноди, чиї джерела вже готові, і рахує їх разом; елементи однієї розмноженої ноди теж ідуть паралельно. Спільний семафор тримає одночасність на DEFAULT_CONCURRENCY = 4. Хвиля завжди дочікується до кінця, навіть якщо сусід уже впав: кинути задачу в польоті означало б осиротити платний виклик, який більше нікому полити й чекпойнтити.

Кеш content-addressed: fingerprint = sha256 від {type, version, inputs}, де inputs — реальні значення, з якими викликалась нода, а не ланцюг угору. Через це змінений один елемент розмноженої ноди інвалідовує лише свій виклик, а не сусідів. version у формулі — це Node.version: змінив код або зміст портів, підняв версію, і інвалідовується сама нода плюс усе нижче.

NodeCache — Protocol; у пакеті InMemoryCache, у проді MongoNodeCache (колекція node_results, _id = fingerprint) — без TTL: виходи ноди це квитанція за платний виклик провайдера, втратити їх означає заплатити вдруге.

CheckpointStore (MongoCheckpointStore пише в nodes.<id>.checkpoint, а для розмноженої ноди — в nodes.<id>.items.<i>.checkpoint) — проміжний стан ноди. Потрібен через task_acks_late + task_reject_on_worker_lost: убитий воркер програє задачу повторно, і без чекпойнта нода створила б другу платну задачу. Завершені ноди прикриті кешем — чекпойнт рятує саму задачу в польоті.

Події через колбек on_event: run_started, node_started, node_progress, node_finished, node_cached, node_failed, run_finished, run_failed, run_cancelled, run_awaiting_input. Події розмноженої ноди несуть item_index/item_count; після них іде один підсумковий node_finished без індексу — зі зібраними списками. credits_consumed у події — це витрачене зараз, тож node_cached завжди несе 0.

NodeContext дає ноді: node_id/run_id/owner_id, services (клієнти провайдерів і сховище, збирає воркер на запуск), checkpoint, answer, report_progress(), report_cost(), save_checkpoint(), raise_if_cancelled().

Скасування

POST /runs/{run_id}/cancel ставить cancel_requested; якщо запуск ще queued — додатково revoke Celery-задачі за збереженим task_id. Воркер помічає флаг між хвилями й на кожному полінгу провайдера (ctx.raise_if_cancelled() → RunCancelled → подія run_cancelled, статус cancelled). Читання флага мемоїзоване на ~2 с, щоб полінг не бомбардував Mongo.

Чесне обмеження: ми перестаємо чекати, а не зупиняємо провайдера — кредити, вже витрачені на задачу в польоті, не повертаються.

Дані

node_graphs — збережений граф: name, description, owner_id, definition (сирий JSON графа), ui_state (позиції нод для React Flow), таймстемпи. Індекс (owner_id, updated_at desc).

graph_runs — один запуск: graph_id, owner_id, definition (знімок графа на момент запуску, тож пізніші правки не переписують історію), status (queued|running|awaiting_input|succeeded|failed|cancelled), nodes — стан по нодах, credits_consumed (сума), cancel_requested, answers (відповіді оператора по node_id), pending_input, task_id (Celery), error, таймстемпи. Індекси (graph_id, created_at desc) і (owner_id, created_at desc).

Стан ноди — {status, progress, outputs, error, message, credits_consumed, duration_seconds, checkpoint} зі статусом pending|running|awaiting_input|succeeded|cached|failed|cancelled, плюс items — та сама структура на кожен виклик розмноженої ноди (ключ — індекс рядком, бо в Mongo немає цілочисельних ключів). Поля самої ноди при цьому лишаються підсумком.

Виходи зберігаються один раз — у підсумку ноди, а не ще й на кожному елементі: це ті самі значення двічі в одному документі, а найширші фан-аути якраз і є найближчими до ліміту в 16 МБ. Ціна: якщо запуск упав посеред фан-ауту, виходи вцілілих елементів лишаються тільки в кеші (node_results) — заплачено за них не буде вдруге, але в документі запуску їх не видно. Кожна подія — один запис у Mongo, підсумок ноди включно: елемент шле прогрес на кожному полінгу провайдера, тож другий round trip на подію був би основним трафіком широкого фан-ауту.

node_results — постійний кеш виходів, _id = fingerprint, плюс node_type, version, credits_consumed, created_at/last_used_at. Читається по _id; індекс на last_used_at існує тільки для майбутнього прибирання.

Виходи нод лежать інлайн у документі запуску (і в кеші) — самі байти в S3.

Схема графа живе в engine/ і валідується на межі API — тому в моделях definition і ui_state це dict[str, Any], і пакет лишається незалежним від рушія.

API

Усе під /api/v1, Bearer Clerk JWT, конверт Response[T].

Кожен хендлер перевіряє owner_id: чужий граф/запуск → 403, неіснуючий → 404. Невалідний definition, порожній PATCH і запуск графа без нод → 422. Постановка в чергу винесена в залежність get_run_enqueuer() — так пакет не імпортує kumquat_api (той самий підхід, що в задачах).

WebSocket. Токен у query, бо браузерний WebSocket не дає заголовків. Коди закриття: 4401 немає/невалідний токен, 4404 запуск не знайдено, 4403 чужий запуск. Порядок навмисний: спершу SUBSCRIBE на graph_run:<run_id>, потім кадр {"type": "snapshot", "run": ...} з Mongo — тож події між читанням і підпискою не втрачаються. Термінальний або запаркований запуск закривається одразу після знімка. Pub/sub нічого не буферизує, але стан кожної ноди персиститься в Mongo паралельно з публікацією, тож реконект відновлює картинку зі знімка.

Обмеження

• Обробка помилок — падіння однієї ноди валить увесь запуск; немає skipped-нод і продовження решти гілок.
• Кілька результатів від моделі — якщо провайдер вернув кілька resultUrls, беремо перший (решта — в лог): порт моделі скалярний, для батчу потрібен list-вихід у самій ModelSpec.
• Подвійна оплата звужена, але не виключена — падіння між createTask і save_checkpoint осиротить одну платну задачу.
• Модель ассета — байти в S3 є, а галереї, provenance й дедупу між запусками немає.
• Заміна моделі — нода = модель, тож поміняти модель означає перезібрати ноду й ребра.
• Редактор — немає undo/redo, copy/paste, автосейву, сабграфів, повторного запуску окремої ноди.
• Шаблони — немає способу віддати креативній команді граф як форму з кількома полями.
• Черга — одна graphs без пріоритетів, без глибини черги в UI й ліміту на користувача; довгий інлайн-полінг тримає слот воркера на весь час генерації.
• Осиротілі графи — у node_graphs лежать старі документи з типами, яких у реєстрі вже немає (generate_image, image_to_video, preview_image, imagen4); вони не валідуються й не запускаються. Видалення типу ноди вимагає міграції збережених графів — як constant_int, чиє значення переїхало в params ноди, яку він живив.