@animastor/orchestration 0.1.1

package/src/orchestration/orchestrator.js

@@ -0,0 +1,630 @@
+// ======================================================
+// ORCHESTRATOR — единый владелец жизненного цикла генерации
+// ======================================================
+// Шаг 0 (см. docs-claude/03_Orchestrator.md §12): тонкий фасад поверх уже
+// существующих функций. На этом шаге команды НИЧЕГО не меняют в логике —
+// только дают единую точку входа, через которую постепенно (по одному
+// вызывающему за коммит) будут проходить все писатели lifecycle-состояния.
+//
+// Контракт пяти команд (цели последующих шагов в скобках):
+//   markDirty(deps, redis, bookId, buildId, dirtyScenes, layerCfg) → { marked }
+//   planScene(redis, bookId, chapterId, sceneId)        → { stages, allDone }   (Д.2: сделать чистой)
+//   beginStage(redis, scene, loadedBook, buildId, stage) → dispatchResult       (Д.1: GENERATING уже есть)
+//   completeStage(redis, bookId, chapterId, sceneId, stage, buildId) → void     (Д.1: idempotent по token)
+//   reconcile(redis, bookId, chapterId, sceneId)        → reconcileResult        (Д.3: диск как факт)
+//
+// Зависимости подтягиваются lazy-require внутри тел команд — это сознательный
+// компромисс Шага 0, чтобы не углублять существующий цикл orchestration и
+// runtime (диспетчер уже делал отложенный импорт orchestration-фасада).
+// Развязка интерфейсом — отдельная задача (после К.4).
+
+// S-2: media-type knowledge (stage lists, fail-event map) resolved via registry
+const mediaRegistry = require('@animastor/generation').mediaRegistry;
+// S-5: pure FSM-writer ownership (markDirtyScene/setScene*) — re-exported from
+// the state layer; bodies moved verbatim (see state/scene-state-ops.js header).
+const { lazyHostBinding } = require('../host/host-bindings');
+// §32.30: former host requires resolve lazily through the host-bindings seam.
+const stateOps = lazyHostBinding('stateOps');
+const state = lazyHostBinding('state');
+const journal = lazyHostBinding('journal');
+const runtimeConfig = lazyHostBinding('config');
+
+// ── markDirty ─────────────────────────────────────────
+// Единственный способ объявить «нужна регенерация». Делегирует в
+// deps.bookDiff.markDirtyScenes — это метод DI-инстанса (book-diff.cjs —
+// фабрика), поэтому инстанс приходит через deps, а не через require.
+async function markDirty(deps, redis, bookId, buildId, dirtyScenes, layerCfg) {
+    if (!deps || !deps.bookDiff || typeof deps.bookDiff.markDirtyScenes !== 'function') {
+        throw new Error('orchestrator.markDirty: deps.bookDiff.markDirtyScenes is required');
+    }
+    return deps.bookDiff.markDirtyScenes(redis, bookId, buildId, dirtyScenes, layerCfg);
+}
+
+// ── planScene ─────────────────────────────────────────
+// Решение «что генерировать». Делегирует в shouldScheduleAssets — теперь это
+// ЧИСТАЯ функция (Д.2): только читает per-asset состояния и layer-config, ничего
+// не пишет. Version-stale reset вынесен в явный пред-проход attemptDispatch
+// (detectVersionStale → markVersionStaleDirty).
+async function planScene(redis, bookId, chapterId, sceneId) {
+    const scheduler = require('../runtime/runtime-scheduler');
+    return scheduler.shouldScheduleAssets(redis, bookId, chapterId, sceneId);
+}
+
+// ── beginStage ────────────────────────────────────────
+// Старт стадии: lease + quota + per-asset GENERATING. Делегирует в
+// dispatch-engine.dispatchStage (который сам зовёт назад orchestration.dispatchStage
+// для исполнения генерации).
+async function beginStage(redis, scene, loadedBook, buildId, stage) {
+    const dispatchEngine = require('../runtime/dispatch-engine');
+    // S-4: filename grammar composed from the canonical owner (bytes unchanged)
+const artifactNaming = require('@animastor/generation').artifactNaming;
+    const bookId = scene.book_id;
+    const chapterId = scene.chapter_id;
+    const sceneId = scene.scene_id;
+    // T8: syncLinearState удалён — per-asset state единственный source of truth
+    const result = await dispatchEngine.dispatchStage(redis, bookId, chapterId, sceneId, stage, loadedBook, buildId);
+    return result;
+}
+
+// ── completeStage ─────────────────────────────────────
+// Завершение стадии: колбэк завершения + release lease/quota (markDispatchCompleted),
+// в той же error-safe связке (try/finally), что сейчас повторена в task-handler.cjs
+// в шести местах. Фасад даёт ОДНУ реализацию этой пары.
+// ЦЕЛЬ Д.1: идемпотентность по dispatch-token (повторный вызов безвреден).
+//
+// ======================================================
+// T1: Callback completion contract
+// --------------------------------------
+// 1. Handler вызывается, возвращает { ok, retryable, reason, artifact }
+// 2. READY/DIRTY пишется ТОЛЬКО после handler.ok === true
+// 3. PG markReady вызывается ПОСЛЕ версионного gate (fail-closed)
+// 4. Исключение handler → failure, не success
+// 5. ok:false → НЕ ставит READY, не пишет PG
+// ======================================================
+async function completeStage(redis, bookId, chapterId, sceneId, stage, buildId, dispatchId) {
+    const callbacks = require('./scene-callbacks');
+    const dispatchEngine = require('../runtime/dispatch-engine');
+        const { log, warn, error } = require('./scene-utils');
+    // O-2: PG persistence via the PersistencePort (host adapter:
+    // storage/runtime-persistence-adapter) — the scene-assets repository and
+    // the database handle left this file. SQL lives host-side.
+    const persist = require('../runtime/persistence-port').persist;
+
+    // S-2: resolve the completion handler through the registry-driven map.
+    // Fallback to the direct named handlers keeps backward compatibility with
+    // partial stubs of scene-callbacks (older test contracts inject only the
+    // three named handlers) — in production getStageHandler is always present.
+    const handler = (callbacks.getStageHandler && callbacks.getStageHandler(stage))
+        || (callbacks.STAGE_HANDLERS && callbacks.STAGE_HANDLERS[stage])
+        || (stage === 'audio' && callbacks.handleAudioCompleted)
+        || (stage === 'image' && callbacks.handleImageCompleted)
+        || (stage === 'video' && callbacks.handleVideoCompleted);
+    if (!handler) {
+        throw new Error(`orchestrator.completeStage: unknown stage '${stage}'`);
+    }
+
+    const identity = await dispatchEngine.verifyDispatchIdentity(
+        redis,
+        bookId,
+        chapterId,
+        sceneId,
+        stage,
+        dispatchId
+    );
+    if (!identity.valid) {
+        warn(`[COMPLETE-STAGE] Rejected ${bookId}/${chapterId}/${sceneId} ${stage}: ${identity.reason}`);
+        return { completed: false, reason: identity.reason };
+    }
+
+    let handlerResult;
+    let handlerError = null;
+    let handlerOk = false;  // T2: true если handler вернул ok:true
+
+    let phaseCompleted = false;
+    let phaseReason = 'handler_rejected';
+
+    try {
+        try {
+            handlerResult = await handler(redis, bookId, chapterId, sceneId, buildId);
+        } catch (err) {
+            // T1.7: Исключение handler → failure path, не success
+            handlerError = err;
+            error(`completeStage: handler threw for ${bookId}/${chapterId}/${sceneId} ${stage}: ${err.message}`);
+        }
+
+        // ── Check handler result (T1.6) ────────────────────
+        if (handlerError || !handlerResult || handlerResult.ok !== true) {
+            const reason = handlerResult?.reason || (handlerError ? handlerError.message : 'unknown');
+            phaseReason = reason;
+            handlerOk = false;
+            log(`[COMPLETE-STAGE] ${bookId}/${chapterId}/${sceneId} ${stage}: rejected (reason=${reason}) — NOT setting READY`);
+        } else {
+            handlerOk = true;
+
+            // ── Handler succeeded — version gate (T1.11: fail-closed) ────
+            // VERSION-GATE: сцена без строки в `scenes` (legacy-книга, импорт
+            // без version-схемы) НЕ блокируется fail-closed — иначе video/audio
+            // никогда не получат READY (строка scene_assets создаётся только
+            // markReady, который вызывается ПОСЛЕ gate — замкнутый круг).
+            // Для таких сцен gate считается пройденным; строки версий
+            // создаются лениво (ensureSceneRow) при следующем bump.
+            let shouldWriteReady = false;
+            try {
+                // O-2: version gate reads via the PersistencePort — the raw
+                // database handle and the repo left this file; the SQL moved
+                // verbatim into the host adapter (sceneVersions.getSceneVersions).
+                const sceneRows = await persist('sceneVersions.getSceneVersions')(bookId, chapterId, sceneId);
+
+                if (sceneRows.length === 1) {
+                    const sv = sceneRows[0];
+                    const asset = await persist('sceneAssets.getAsset')(bookId, chapterId, sceneId, stage, buildId);
+
+                    if (asset) {
+                        const contentVersionConfirmed =
+                            asset.scene_content_version != null &&
+                            sv.content_version != null &&
+                            asset.scene_content_version >= sv.content_version;
+                        const audioVersionConfirmed =
+                            stage !== 'audio' || (
+                                asset.scene_audio_config_version != null &&
+                                sv.audio_config_version != null &&
+                                asset.scene_audio_config_version >= sv.audio_config_version
+                            );
+                        shouldWriteReady = contentVersionConfirmed && audioVersionConfirmed;
+                    }
+                } else if (sceneRows.length === 0) {
+                    // Legacy-книга без version-схемы — READY разрешён (сцена
+                    // не может устареть относительно несуществующей версии).
+                    shouldWriteReady = true;
+                }
+            } catch (pgErr) {
+                // T1.11: Fail-closed — ошибка PG не разрешает READY
+                shouldWriteReady = false;
+                warn(`[VERSION-GATE] PG query failed for ${bookId}/${chapterId}/${sceneId}: ${pgErr.message} — blocking READY (fail-closed)`);
+            }
+
+            if (shouldWriteReady) {
+                // T1.10: PG markReady ПОСЛЕ version gate
+                const artifactPath = handlerResult.artifact?.path;
+                if (!artifactPath) {
+                    handlerOk = false;
+                    phaseReason = 'artifact_path_missing';
+                } else {
+                    await persist('sceneAssets.markReady')(bookId, chapterId, sceneId, stage, artifactPath);
+                    log(`[PG-${stage.toUpperCase()}-READY] ${bookId}/${chapterId}/${sceneId}: status=ready`);
+
+                    await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, stage, state.AssetState.READY);
+                    log(`[COMPLETE-STAGE] ${bookId}/${chapterId}/${sceneId}: ${stage} → READY`);
+                    phaseCompleted = true;
+                    phaseReason = null;
+                }
+            } else {
+                // T2: version gate stale — dispatch успешен, но artifact устарел.
+                // Финализируем как success (диспетчеризация выполнена), просто не ставим READY.
+                log(`[VERSION-GATE] ${bookId}/${chapterId}/${sceneId}: ${stage} stale — DIRTY instead of READY`);
+                await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, stage, state.AssetState.DIRTY);
+                phaseCompleted = false;
+                phaseReason = 'stale';
+                // handlerOk остаётся true — финализируем как success
+            }
+        }
+    } catch (completionErr) {
+        handlerOk = false;
+        phaseCompleted = false;
+        phaseReason = `completion_error:${completionErr.message}`;
+        error(`completeStage failed for ${bookId}/${chapterId}/${sceneId} ${stage}: ${completionErr.message}`);
+    } finally {
+        // T2: finalizeDispatch — handlerOk определяет success/failure
+        // Если handler вернул ok:true (handlerOk = true) — всегда success,
+        // даже при version gate stale. Failure только при ok:false/error handler.
+        //
+        // Fix (video-retry-targeted-investigation-2026-08-26): pass the
+        // taxonomy-classified failureType instead of the implicit 'transient'
+        // default — a rejected completion (e.g. 'invalid_asset_state', which is
+        // PERMANENT by failure-taxonomy) must not consume the transient retry
+        // budget and must not be retried like a transient GPU failure.
+        try {
+            const outcome = handlerOk ? 'success' : 'failure';
+            const failureTaxonomy = require('../runtime/failure-taxonomy');
+            await dispatchEngine.finalizeDispatch(redis, bookId, chapterId, sceneId, stage, {
+                outcome,
+                dispatchId,
+                reason: handlerOk ? (phaseReason || undefined) : (phaseReason || 'handler_rejected'),
+                failureType: handlerOk ? undefined : failureTaxonomy.classifyFailure(new Error(phaseReason || 'handler_rejected')).type,
+            });
+        } catch (dispErr) {
+            warn(`completeStage: finalizeDispatch(${stage}) failed: ${dispErr.message}`);
+        }
+    }
+
+    return { completed: phaseCompleted, reason: phaseReason };
+}
+
+// ── failStage ─────────────────────────────────────────
+// T3 консолидации: единственный способ зафиксировать «генерация упала».
+// Вызывается endpoint'ом /gpu/task/error (ошибка воркера, форвард через
+// gpu-hub, включая worker_timeout) и внутренними обработчиками сбоев.
+// Делает: asset-state → FAILED (с валидацией перехода — поздняя ошибка
+// после успешного retry не сбивает READY), событие *_FAILED в journal,
+// release lease+quota через идемпотентный markDispatchCompleted.
+// После FAILED (если redispatch=true, по умолчанию) ассет переводится в
+// PENDING — планировщик передиспатчит на следующем тике под защитой
+// circuit-breaker и retry-budget (dispatch-engine). Это зеркалит проверенный
+// путь исчерпания merge-ретраев в task-handler; сам failStage retry-политику
+// не содержит.
+async function failStage(redis, bookId, chapterId, sceneId, stage, buildId, reason = 'unknown', { redispatch = true, dispatchId } = {}) {
+        const dispatchEngine = require('../runtime/dispatch-engine');
+        const { log, warn } = require('./scene-utils');
+
+    // S-2: fail event type map — derived from journal event types.
+    // Maps media type → failure event type for the event journal.
+    // S-2: fail event types derived from journal event types
+    const FAIL_EVENT_TYPES = {};
+    for (const t of mediaRegistry.listMediaTypes()) {
+        const key = `${t.toUpperCase()}_FAILED`;
+        if (journal.EventType[key]) FAIL_EVENT_TYPES[t] = journal.EventType[key];
+    }
+    const eventType = FAIL_EVENT_TYPES[stage];
+    if (!eventType) {
+        throw new Error(`orchestrator.failStage: unknown stage '${stage}'`);
+    }
+
+    const identity = await dispatchEngine.verifyDispatchIdentity(
+        redis,
+        bookId,
+        chapterId,
+        sceneId,
+        stage,
+        dispatchId
+    );
+    if (!identity.valid) {
+        log(`[FAIL-STAGE] Rejected ${bookId}/${chapterId}/${sceneId} ${stage}: ${identity.reason}`);
+        return { failed: false, reason: identity.reason };
+    }
+
+    try {
+        const states = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+        const current = states ? states[stage] : null;
+        const check = state.validateAssetTransition(current, state.AssetState.FAILED);
+
+        if (!check.valid) {
+            // Например READY→FAILED: результат уже принят (поздний/повторный
+            // сигнал ошибки) — фиксируем в журнале, состояние не трогаем.
+            log(`[FAIL-STAGE] ${bookId}/${chapterId}/${sceneId}: ${stage} ${current}→failed отклонён (${check.reason}) — ignoring late error (reason=${reason})`);
+            await journal.appendSceneEvent(redis, bookId, chapterId, sceneId,
+                journal.EventType.INVALID_STATE_CALLBACK, current,
+                { stage, reason, attempted: 'failed', ignored: true }).catch(() => {});
+            return { failed: false, reason: check.reason, current };
+        }
+
+        await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, stage, state.AssetState.FAILED);
+        // F2: sync audio-orch/video-orch phase → FAILED through the orchestrator facade
+        try {
+            // O-7: the audio FSM sync rides the AudioFsmPort (host adapter:
+            // storage/audio-fsm-adapter) — the audio-orchestrator host
+            // service left this file.
+            // O-8: the video FSM sync rides the VideoFsmPort (host adapter:
+            // storage/video-fsm-adapter) — the video-orchestrator host
+            // service left this file.
+            if (stage === 'audio') {
+                await require('../runtime/audio-fsm-port').audioFsmOp('setFailed')(redis, bookId, chapterId, sceneId, reason);
+            } else if (stage === 'video') {
+                await require('../runtime/video-fsm-port').videoFsmOp('setFailed')(redis, bookId, chapterId, sceneId, reason);
+            }
+        } catch (_) {}
+        log(`[FAIL-STAGE] ${bookId}/${chapterId}/${sceneId}: ${stage} → FAILED (reason=${reason})`);
+        await journal.appendSceneEvent(redis, bookId, chapterId, sceneId,
+            eventType, state.AssetState.FAILED, { stage, reason, buildId }).catch(() => {});
+
+        // T8: syncLinearState удалён — per-asset state единственный source of truth
+        if (redispatch) {
+            await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, stage, state.AssetState.PENDING);
+            log(`[FAIL-STAGE] ${bookId}/${chapterId}/${sceneId}: ${stage} → PENDING (re-dispatch queued)`);
+        }
+        return { failed: true, reason, redispatch };
+    } finally {
+        // T2: finalizeDispatch('failure') — recordFailure + consumeRetryBudget,
+        // НЕ recordSuccess, НЕ DISPATCH_COMPLETED.
+        try {
+            const failureTaxonomy = require('../runtime/failure-taxonomy');
+            const failureClass = failureTaxonomy.classifyFailure(new Error(reason || 'unknown'));
+            await dispatchEngine.finalizeDispatch(redis, bookId, chapterId, sceneId, stage, {
+                outcome: 'failure',
+                dispatchId,
+                reason: reason || 'unknown',
+                failureType: failureClass.type
+            });
+        } catch (dispErr) {
+            warn(`failStage: finalizeDispatch(${stage}) failed: ${dispErr.message}`);
+        }
+    }
+}
+
+// ── rollbackStageToPending ───────────────────────────
+// FSM-валидный откат стадии в PENDING после dispatch, который НЕ отправил
+// ни одного GPU job (no_jobs_sent / cancelled / dispatch_error).
+//
+// Прямой переход generating→pending ЗАПРЕЩЁН FSM (scene-state.js), поэтому
+// GENERATING откатывается двухшаговым штатным путём:
+//   GENERATING → DIRTY → PENDING
+// (PLACEHOLDER → DIRTY → PENDING — аналогично; NEW/DIRTY/FAILED → PENDING
+// напрямую). READY не трогаем — результат уже принят.
+//
+// Ошибки rollback НЕ проглатываются: error-лог + TRANSITION_FAILED в journal
+// + счётчик stateRollbackFailures. Иначе сцена навсегда остаётся в GENERATING
+// (ghost, forensic audit 6929ba5: no_jobs_sent → setScenePending rejected →
+// rejection проглочен → вечный GENERATING).
+async function rollbackStageToPending(redis, bookId, chapterId, sceneId, asset, buildId = null, reason = 'dispatch_cancelled') {
+            const { log, error } = require('./scene-utils');
+
+    const states = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+    const current = states?.[asset];
+
+    if (current === state.AssetState.PENDING) {
+        return { changed: false, alreadyPending: true, reason: 'already_pending' };
+    }
+    if (current === state.AssetState.READY) {
+        // Результат уже принят — откат повредил бы завершённую работу.
+        log(`[ROLLBACK] ${bookId}/${chapterId}/${sceneId} ${asset}: already READY — rollback skipped (reason=${reason})`);
+        return { changed: false, reason: 'already_ready' };
+    }
+
+    // Только FSM-валидные рёбра (AssetTransitions):
+    //   GENERATING/PLACEHOLDER → DIRTY → PENDING
+    //   NEW/DIRTY/FAILED → PENDING
+    const path = (current === state.AssetState.GENERATING || current === state.AssetState.PLACEHOLDER)
+        ? [state.AssetState.DIRTY, state.AssetState.PENDING]
+        : [state.AssetState.PENDING];
+
+    try {
+        let from = current;
+        for (const next of path) {
+            const check = state.validateAssetTransition(from, next);
+            if (!check.valid) {
+                throw new Error(`invalid_transition:${from}->${next}`);
+            }
+            await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, asset, next);
+            from = next;
+        }
+        log(`[ROLLBACK] ${bookId}/${chapterId}/${sceneId} ${asset}: ${current} → ${path.join(' → ')} (reason=${reason})`);
+        await journal.appendSceneEvent(redis, bookId, chapterId, sceneId,
+            journal.EventType.SCENE_PENDING, state.AssetState.PENDING,
+            { asset, buildId, rollback: true, via: path.join('->'), reason }).catch(() => {});
+        return { changed: true, from: current, path };
+    } catch (err) {
+        // НЕ глотаем: без явной диагностики сцена останется в GENERATING навсегда.
+        error(`[ROLLBACK] FAILED ${bookId}/${chapterId}/${sceneId} ${asset}: ${current} → pending (reason=${reason}): ${err.message} — stage may be stuck in GENERATING`);
+        try {
+            await journal.appendSceneEvent(redis, bookId, chapterId, sceneId,
+                journal.EventType.TRANSITION_FAILED, current,
+                { asset, attempted: 'rollback_to_pending', via: path.join('->'), reason, error: err.message });
+        } catch (_) {}
+        try {
+            const runtimeMetrics = require('../runtime/runtime-metrics');
+            await runtimeMetrics.incrementCounter(redis, 'stateRollbackFailures');
+        } catch (_) {}
+        return { changed: false, reason: `rollback_failed:${err.message}` };
+    }
+}
+
+// ── completeStageWithoutVideo ────────────────────────
+// When video is disabled by layer config, mark video as READY
+// and complete remaining scene lifecycle (cleanup, slide).
+// Callback function handles cleanup only — state is set here in the facade.
+async function completeStageWithoutVideo(redis, loadedBook, bookId, chapterId, sceneId, buildId) {
+        const callbacks = require('./scene-callbacks');
+    await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, 'video', state.AssetState.READY);
+    await callbacks.completeSceneWithoutVideo(redis, loadedBook, bookId, chapterId, sceneId, buildId);
+}
+
+// ── completeStageWithoutImage ─────────────────────────
+// When image is disabled by layer config, mark image as READY
+// and complete remaining scene lifecycle.
+async function completeStageWithoutImage(redis, loadedBook, bookId, chapterId, sceneId, buildId) {
+        const callbacks = require('./scene-callbacks');
+    await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, 'image', state.AssetState.READY);
+    await callbacks.completeSceneWithoutImage(redis, loadedBook, bookId, chapterId, sceneId, buildId);
+}
+
+// ── reconcile ─────────────────────────────────────────
+// Сверка фактов (PG/диск) с состоянием. Делегирует в reconciliation-engine.
+// ЦЕЛЬ Д.3: диск становится источником ФАКТА, решение принимает фасад.
+async function reconcile(redis, bookId, chapterId, sceneId) {
+    const reconciliationEngine = require('../runtime/reconciliation-engine');
+    return reconciliationEngine.reconcileScene(redis, bookId, chapterId, sceneId);
+}
+
+// ── resetScenes ───────────────────────────────────────
+// T4 консолидации: единственная команда для reset'а сцен при регенерации.
+// Собирает ритуал из /regenerate роута (очистка iu-progress/iu-in-flight,
+// снятие lease, чистка очередей gpu-hub, markDirty) в одну команду фасада.
+//
+// Параметры:
+//   scenes — [{chapter_id, scene_id}] — список сцен для reset'а
+//   options.cleanPngUnitIds — мапу {chapterId_sceneId: [unitId, ...]} для удаления stale PNG
+//   options.bookDiff — DI-инстанс book-diff (передаётся из route)
+//   options.readdToActiveIndex — вернуть сцены планировщику после reset (default true)
+//
+// Что делает:
+//   1. force-dispatch флаг
+//   2. событие SCENE_RESET в journal
+//   3. удаление из active index
+//   4. снятие dispatch leases только для сбрасываемых стадий
+//   5. очистка очередей gpu-hub (HTTP DELETE /queue/clear)
+//   6. pre-delete stale PNG для указанных unit_id
+//   7. очистка iu-progress + iu-in-flight
+//   8. markDirty (через bookDiff.markDirtyScenes)
+//   9. добавление сцен обратно в active index
+//   10. событие SCENE_RESET_COMPLETED в journal
+async function resetScenes(redis, bookId, buildId, scenes, layerCfg, options = {}) {
+    // force — зарезервировано для будущего использования (например, пропуск
+    // version-проверок на PG при полном reset). Сейчас resetScenes всегда
+    // очищает всё безусловно — это корректно для регенерации.
+    const {
+        scope = 'WHOLE_BOOK',
+        chapterId = null,
+        sceneId = null,
+        bookDiff = null,
+        cleanPngUnitIds = null,
+        readdToActiveIndex = true,
+    } = options;
+    const { log, warn } = require('./scene-utils');
+    
+    if (!scenes || scenes.length === 0) {
+        log('[RESET-SCENES] No scenes to reset');
+        return { marked: 0, reset_scenes: 0 };
+    }
+
+    const scopeDisplay = `${scope}${chapterId ? '/' + chapterId : ''}${sceneId ? '/' + sceneId : ''}`;
+    log(`[RESET-SCENES] ${bookId}: ${scenes.length} scenes, scope=${scopeDisplay}`);
+
+    // 1. Force-dispatch flag (T1: TTL из TIMEOUTS)
+        await redis.set(
+        `animastor:force-dispatch:${bookId}`, '1',
+        'EX', runtimeConfig.TIMEOUTS.FORCE_DISPATCH_TTL_S
+    );
+
+    // 2. Event journal — start
+    await journal.appendSceneEvent(redis, bookId, chapterId || bookId, sceneId || 'all',
+        journal.EventType.SCENE_RESET, 'INITIATED',
+        { scenes_count: scenes.length, scope, force: !!options.force }
+    ).catch(() => {});
+
+    // 3. Remove from active index
+    const scheduler = require('../runtime/runtime-scheduler');
+    await scheduler.removeScenesFromActiveIndex(redis, bookId, scenes);
+
+    // 4. Clear dispatch leases only for stages requested by this regeneration.
+    // A parallel Image request must not cancel an already-running Audio lease
+    // for the same scene.
+    const dispatchEngine = require('../runtime/dispatch-engine');
+    const leaseResetScenes = scenes.map(ds => ({
+        chapter_id: ds.chapter_id,
+        scene_id: ds.scene_id,
+        stages: (ds.dirty_layers || mediaRegistry.listMediaTypes()).filter(stage =>
+            layerCfg?.[`${stage}_enabled`] !== false
+        ),
+    }));
+    const resetStagesByScene = new Map(leaseResetScenes.map(s => [
+        `${s.chapter_id}:${s.scene_id}`,
+        s.stages,
+    ]));
+    const cancellation = await dispatchEngine.clearLeasesForScenes(redis, bookId, leaseResetScenes);
+
+    // 5. Clear only jobs belonging to the cancelled dispatches.
+    // O-9: hub-queue cleanup goes through the HubCancelPort (the tier must
+    // not own hub HTTP); lease clearing above stays a direct dispatch-engine
+    // call (Redis domain operation).
+    await require('../runtime/hub-cancel-port').hubCancelOp('clearHubDispatches')(cancellation.dispatchIds, {
+        context: 'RESET-SCENES',
+        warn,
+    });
+
+    // 6. Pre-delete stale PNGs for specific unit IDs
+    const path = require('path');
+    const fs = require('fs');
+    if (cleanPngUnitIds && typeof cleanPngUnitIds === 'object' && buildId) {
+        const buildDir = path.join(runtimeConfig.OUTPUT_DIR, buildId);
+        if (fs.existsSync(buildDir)) {
+            let deletedCount = 0;
+            for (const ds of scenes) {
+                const sceneKey = `${ds.chapter_id}_${ds.scene_id}`;
+                const unitIds = cleanPngUnitIds[sceneKey] || [];
+                for (const uid of unitIds) {
+                    const pngPath = path.join(buildDir, artifactNaming.sceneImageName(bookId, ds.chapter_id, ds.scene_id, uid));
+                    try { if (fs.existsSync(pngPath)) { fs.unlinkSync(pngPath); deletedCount++; } } catch (_) {}
+                    const strippedUid = uid.replace(/^iu/, '');
+                    const previewPath = path.join(buildDir, artifactNaming.sceneImagePreviewName(bookId, ds.chapter_id, ds.scene_id, uid));
+                    try { if (fs.existsSync(previewPath)) { fs.unlinkSync(previewPath); } } catch (_) {}
+                }
+            }
+            if (deletedCount > 0) log(`[RESET-SCENES] Deleted ${deletedCount} stale PNG files`);
+        }
+    }
+
+    // 7. Clear image-specific IU progress only for scenes whose image stage is reset.
+    for (const ds of scenes) {
+        const resetStages = resetStagesByScene.get(`${ds.chapter_id}:${ds.scene_id}`) || [];
+        if (!resetStages.includes('image')) continue;
+
+        const progKey = `animastor:iu-progress:${bookId}:${ds.chapter_id}:${ds.scene_id}:image`;
+        try { await redis.del(progKey); } catch (_) {}
+
+        try {
+            let cursor = '0';
+            const scenePrefix = artifactNaming.iuScanPrefix(bookId, ds.chapter_id, ds.scene_id);
+            do {
+                const [nextCursor, keys] = await redis.scan(cursor, 'MATCH', `animastor:iu-in-flight:${scenePrefix}*`, 'COUNT', 50);
+                cursor = nextCursor;
+                if (keys.length > 0) await redis.del(...keys);
+            } while (cursor !== '0');
+        } catch (_) {}
+    }
+
+    // 8. markDirty (через bookDiff.markDirtyScenes — обязательный DI-инстанс из route)
+    // R7: bookDiff обязателен — неатомарный fallback удалён.
+    if (!bookDiff || typeof bookDiff.markDirtyScenes !== 'function') {
+        throw new Error(`resetScenes: bookDiff.markDirtyScenes is required for book ${bookId}`);
+    }
+    // W1: try/catch вокруг markDirty гарантирует, что addSceneToActiveIndex
+    // (шаг 9) выполнится даже при runtime-ошибке (PG failure, Redis timeout).
+    // Сцена без dirty не страшна; сцена вне active index — scheduler её не
+    // увидит, и она зависнет навсегда. Programming error (bookDiff missing)
+    // валидируется выше и падает жёстко — это контракт, а не runtime-сбой.
+    let marked = { marked: 0 };
+    try {
+        marked = await markDirty({ bookDiff }, redis, bookId, buildId, scenes, layerCfg);
+    } catch (mdErr) {
+        warn(`[RESET-SCENES] markDirty failed for ${bookId}: ${mdErr.message} — continuing to re-add scenes to active index`);
+    }
+
+    // 9. Re-add to active index (планировщик подберёт на следующем тике).
+    // Selective generation can defer this until its task registry is ready.
+    // Гарантированно выполняется даже при ошибке markDirty (шаг 8).
+    if (readdToActiveIndex) {
+        for (const ds of scenes) {
+            await scheduler.addSceneToActiveIndex(redis, bookId, ds.chapter_id, ds.scene_id);
+        }
+        log(`[RESET-SCENES] ${bookId}: ${scenes.length} scenes re-added to active index`);
+    } else {
+        log(`[RESET-SCENES] ${bookId}: activation deferred for ${scenes.length} scenes`);
+    }
+
+    // 10. Event journal — completion
+    await journal.appendSceneEvent(redis, bookId, chapterId || bookId, sceneId || 'all',
+        journal.EventType.SCENE_RESET_COMPLETED, 'DONE',
+        { scenes_count: scenes.length, marked: marked.marked }
+    ).catch(() => {});
+
+    return { ...marked, reset_scenes: scenes.length };
+}
+
+// ── S-5: pure FSM-writer ownership moved to the state layer ──
+// markDirtyScene / setScenePending / setSceneGenerating / setSceneAllReady /
+// setScenePlaceholder now live in state/scene-state-ops.js (bodies verbatim;
+// canonical owner next to the asset-state store + journal). They are
+// RE-EXPORTED below so the facade command surface and every existing caller
+// (deps.orchestrator.*, orchestration index spread, seam wiring) stay
+// byte-compatible. rollbackStageToPending remains a facade-owned function:
+// it additionally reports the runtime-owned stateRollbackFailures metric.
+
+// §32.30: the FSM-writer re-exports resolve the stateOps binding lazily via
+// getters — the facade module must stay loadable before the composition root
+// binds host modules (byte-compatible surface, deferred resolution).
+module.exports = {
+    markDirty,
+    get markDirtyScene() { return stateOps.markDirtyScene; },
+    planScene,
+    beginStage,
+    completeStage,
+    failStage,
+    completeStageWithoutVideo,
+    completeStageWithoutImage,
+    get setScenePending() { return stateOps.setScenePending; },
+    get setSceneGenerating() { return stateOps.setSceneGenerating; },
+    get setSceneAllReady() { return stateOps.setSceneAllReady; },
+    get setScenePlaceholder() { return stateOps.setScenePlaceholder; },
+    rollbackStageToPending,
+    reconcile,
+    resetScenes,
+};