@animastor/orchestration 0.1.1

package/src/orchestration/runtime-result-consumer.js

@@ -0,0 +1,54 @@
+// ======================================================
+// Runtime Result Consumer — Phase 5 seam (consumer side)
+// ======================================================
+// Orchestration-side adapter for the Runtime Result Contract.
+// Implemented in orchestration, injected into runtime's emitter from the
+// composition root (backend.cjs) — runtime never imports this module
+// statically (the dependency flows through the injected callback).
+//
+// Direction after Phase 5:
+//   orchestration ▶ runtime ▶ Runtime Result Contract ▶ this consumer
+//
+// Phase 5 scope: the consumer OBSERVES dispatch finalizations (completed /
+// failed / cancelled). Semantic reactions (state writes, re-dispatch policy)
+// stay with the existing flows (task-handler → completeStage/failStage,
+// reconciliation) — migrating them here is future work, see
+// docs/architecture/PHASE_5_ORCHESTRATION_RUNTIME.md §7.
+//
+// Zero relative imports: this module must stay a leaf so that wiring it in
+// cannot create a new architectural cycle (Phase 5 T8).
+
+'use strict';
+
+const LOG_PREFIX = '[RUNTIME-RESULT-CONSUMER]';
+
+/**
+ * @param {Object} [options]
+ * @param {(msg: string) => void} [options.log] injectable logger (tests)
+ * @returns {(result: object) => Promise<void>} consumer for the runtime result emitter
+ */
+function createRuntimeResultConsumer(options = {}) {
+    const log = typeof options.log === 'function'
+        ? options.log
+        : (msg) => console.log(`${LOG_PREFIX} ${msg}`);
+
+    return async function handleRuntimeResult(result) {
+        if (!result || typeof result !== 'object') {
+            log('received non-object runtime result — ignoring');
+            return;
+        }
+
+        const where = `${result.bookId}/${result.chapterId}/${result.sceneId}`;
+        const stage = result.stage ? `:${result.stage}` : '';
+        const id = result.dispatchId
+            ? `dispatch=${result.dispatchId.slice(0, 24)}...`
+            : (result.jobId ? `job=${result.jobId}` : 'no-id');
+        const cause = result.error ? ` reason=${result.error}` : '';
+
+        log(`${result.status} ${where}${stage} ${id}${cause}`);
+    };
+}
+
+module.exports = {
+    createRuntimeResultConsumer,
+};

package/src/orchestration/scene-callbacks.js

@@ -0,0 +1,542 @@
+// ======================================================
+// Callback handlers — contract (T1):
+//
+// Каждый handler возвращает:
+//   { ok: true,  artifact: { buildId, path } }           — успех
+//   { ok: false, retryable: true,  reason: '<cause>' }   — временная ошибка (→ failStage)
+//   { ok: false, retryable: false, reason: '<cause>' }   — терминальная ошибка (журнал, NO READY)
+//
+// Handler НЕ пишет PG status='ready' — это делает completeStage()
+// после валидации результата и version gate.
+// ======================================================
+
+const path = require('path');
+const fs = require('fs');
+const { lazyHostBinding, hostBinding } = require('../host/host-bindings');
+// §32.30: former host requires resolve lazily through the host-bindings seam.
+const state = lazyHostBinding('state');
+const audio = lazyHostBinding('media.audio');
+const image = lazyHostBinding('media.image');
+const video = lazyHostBinding('media.video');
+// §32.30: the artifact root (former process.env.OUTPUT_DIR read) resolves
+// through the composition-root host-bindings seam at call time.
+const artifactRoot = () => hostBinding('artifactRoot');
+// S-4: filename grammar composed from the canonical owner (bytes unchanged)
+const artifactNaming = require('@animastor/generation').artifactNaming;
+// O-2: persistence arrives ONLY through the PersistencePort (host adapter:
+// storage/runtime-persistence-adapter) — the storage barrel, the scene-assets
+// and IU repositories left this file. The Redis asset-registry and the
+// audio-path composition are consumed as persistence OPERATIONS through the
+// same port (their implementations stay host-side).
+const persist = require('../runtime/persistence-port').persist;
+const runtimeScheduler = require('../runtime/runtime-scheduler');
+const dispatchEngine = require('../runtime/dispatch-engine');
+// O-3: scene content arrives ONLY through the SceneDataPort (host adapter:
+// storage/scene-data-adapter) — the Book Model facade (../book) left this
+// file. loadBook is consumed as `sceneData('loadBook')(bookId)` at the
+// auto-slide call site.
+// O-3: scene content arrives ONLY through the SceneDataPort (host adapter:
+// storage/scene-data-adapter) — the Book Model facade (../book) left this
+// file. loadBook is consumed as `sceneData('loadBook')(bookId)` at the
+// auto-slide call site.
+const sceneData = require('../runtime/scene-data-port').sceneDataOp;
+// O-4: placeholder audio arrives ONLY through the PlaceholderAudioPort
+// (host adapter: storage/placeholder-audio-adapter) — the ffmpeg/fs host
+// service (../services/placeholder-audio) left this file.
+const placeholderAudioOp = require('../runtime/placeholder-audio-port').placeholderAudioOp;
+// O-5: progress events arrive ONLY through the ProgressEventsPort (host
+// adapter: storage/progress-events-adapter) — the Redis pub/sub host
+// service (../services/progress-pubsub) left this file.
+const progressEventsOp = require('../runtime/progress-events-port').progressEventsOp;
+const { log, warn, error, logEvent } = require('./scene-utils');
+
+// Stage constants (replaces removed scene-state-machine.js)
+const Stage = { AUDIO: 'audio', IMAGE: 'image', VIDEO: 'video' };
+
+// S-2: Stage handler map — derived from concrete handlers.
+// Used by orchestrator.completeStage() to resolve the callback for a stage.
+const STAGE_HANDLERS = {
+    audio: handleAudioCompleted,
+    image: handleImageCompleted,
+    video: handleVideoCompleted,
+};
+
+/**
+ * Get the completion handler for a stage.
+ * @param {string} stage
+ * @returns {Function | undefined}
+ */
+function getStageHandler(stage) {
+    return STAGE_HANDLERS[stage];
+}
+
+async function updateSceneChunks(redis, bookId, chapterId, sceneId, updates) {
+    const prefix = `animastor:chunk:${bookId}_${chapterId}_${sceneId}_`;
+    let cursor = '0';
+    do {
+        const [nextCursor, keys] = await redis.scan(cursor, 'MATCH', `${prefix}*`, 'COUNT', 50);
+        cursor = nextCursor;
+        for (const key of keys) {
+            try {
+                const raw = await redis.get(key);
+                if (raw) {
+                    const chunk = JSON.parse(raw);
+                    Object.assign(chunk, updates);
+                    await redis.set(key, JSON.stringify(chunk));
+                }
+            } catch (e) {
+                warn(`Failed to update chunk ${key}: ${e.message}`);
+            }
+        }
+    } while (cursor !== '0');
+}
+
+async function handleAudioCompleted(redis, bookId, chapterId, sceneId, buildId) {
+    // T1: возвращает { ok, retryable, reason, artifact }
+    // artifact = { buildId, path } при ok:true
+    log(`AUDIO_CALLBACK: ${bookId}/${chapterId}/${sceneId}`);
+
+    const assetStates = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+    const audioAllowed = assetStates && (
+        assetStates.audio === state.AssetState.GENERATING ||
+        assetStates.audio === state.AssetState.PENDING ||
+        assetStates.audio === state.AssetState.DIRTY
+    );
+
+    if (!audioAllowed) {
+        warn(`AUDIO_CALLBACK: Invalid per-asset state: ${assetStates?.audio || 'unknown'} (expected GENERATING/PENDING)`);
+        log(`🔻 AUDIO callback rejected (invalid per-asset state): ${bookId}/${chapterId}/${sceneId}`);
+        return { ok: false, retryable: false, reason: 'invalid_asset_state' };
+    }
+
+    const isReady = await audio.isSceneAudioReady(buildId, bookId, chapterId, sceneId, require('music-metadata'));
+    if (!isReady) {
+        error(`Audio not ready after completion: ${bookId}/${chapterId}/${sceneId}`);
+        const scene = { book_id: bookId, chapter_id: chapterId, scene_id: sceneId };
+        await logEvent(redis, scene, 'AUDIO_FAILED', 'audio_ready', {
+            reason: 'not_ready_validation'
+        });
+        log(`🔻 AUDIO callback: audio not ready: ${bookId}/${chapterId}/${sceneId}`);
+        return { ok: false, retryable: true, reason: 'audio_not_ready' };
+    }
+
+    const scene = { book_id: bookId, chapter_id: chapterId, scene_id: sceneId };
+    await logEvent(redis, scene, 'AUDIO_COMPLETED', 'audio_ready', {
+        buildId
+    });
+
+    const audioPath = persist('filesystem.getSceneAudioPath')(
+        artifactRoot(), buildId, bookId, chapterId, sceneId
+    );
+
+    try {
+        await persist('registry.registerSceneAudioRedis')(redis, bookId, chapterId, sceneId, {
+            canonicalPath: audioPath,
+            ready: true
+        });
+        log(`CACHE-MANIFEST: audio recorded for ${bookId}/${chapterId}/${sceneId}`);
+    } catch (err) {
+        warn(`Failed to register audio asset: ${err.message}`);
+    }
+
+    // T1.10: PG markReady вынесен в completeStage после version gate
+    // T1.10: PG markReady is now called in completeStage() after version gate
+
+    let realDuration = 0;
+    try {
+        const mm = require('music-metadata');
+        try {
+            const metadata = await mm.parseFile(audioPath);
+            realDuration = metadata.format.duration || 0;
+        } catch {}
+        await placeholderAudioOp('replacePlaceholderWithRealAudio')(
+            bookId, chapterId, sceneId, buildId, audioPath, realDuration
+        );
+    } catch (err) {
+        warn(`Failed to replace placeholder audio: ${err.message}`);
+    }
+
+    // ── IU TIMING RECALCULATION ──
+    // TEMPORARY (research): source of truth for unit timings is now the ACTUAL
+    // raw audio chunk durations (.chunk-durations.json written by trackChunkDurations
+    // during merge), not a text-length-proportional split of the merged duration.
+    // Chunks carry unit_id (set during generation), so we sum per-unit durations
+    // and build cumulative boundaries. Falls back to the old proportional split
+    // only when no per-chunk data is available (e.g. pure-dialogue merged chunks).
+    if (realDuration > 0) {
+        try {
+            const units = await persist('iu.getImageUnitsForScene')(buildId, bookId, chapterId, sceneId);
+            if (units && units.length > 0) {
+                const metaPath = audioPath.replace(/\.mp3$/, '.chunk-durations.json');
+                const factual = fs.existsSync(metaPath) ? JSON.parse(fs.readFileSync(metaPath, 'utf8')) : null;
+                // The final cleanup trims trailing silence only from the LAST chunk
+                // of the scene (tail-only mode). To match the merged file exactly,
+                // that last chunk must be counted by its tail duration, all others
+                // by their raw duration (their tail becomes an internal pause).
+                const lastChunkIdx = factual && factual.records && factual.records.length > 0
+                    ? Math.max(...factual.records.map(r => r.chunk_index))
+                    : null;
+                const perUnit = factual && factual.records && factual.records.length > 0
+                    ? factual.records
+                        .filter(r => r.unit_id)
+                        .reduce((acc, r) => {
+                            const isLast = r.chunk_index === lastChunkIdx;
+                            const dur = isLast && r.tail_duration_sec
+                                ? r.tail_duration_sec
+                                : r.raw_duration_sec;
+                            acc[r.unit_id] = (acc[r.unit_id] || 0) + dur;
+                            return acc;
+                        }, {})
+                    : null;
+
+                const oldSceneDur = units[0].scene_duration_sec || 0;
+                const diff = Math.abs(realDuration - oldSceneDur);
+
+                if (perUnit && Object.keys(perUnit).length > 0) {
+                    const durLabel = oldSceneDur > 0
+                        ? `${oldSceneDur.toFixed(2)}s → factual ${realDuration.toFixed(2)}s`
+                        : `first-time factual (${realDuration.toFixed(2)}s)`;
+                    const sumFactual = Object.values(perUnit).reduce((s, v) => s + v, 0);
+                    log(`[IU-RECALC] ${bookId}/${chapterId}/${sceneId}: ${durLabel}, applying ACTUAL chunk timings to ${units.length} IUs (${Object.keys(perUnit).length} units with audio chunks; last-chunk tail fix applied, Σ=${sumFactual.toFixed(2)}s)`);
+                    let cursorMs = 0;
+                    for (const u of units) {
+                        const actualSec = perUnit[u.unit_id] ?? null;
+                        let startMs = cursorMs;
+                        let endMs;
+                        let estSec;
+                        if (actualSec != null && actualSec > 0) {
+                            endMs = cursorMs + Math.round(actualSec * 1000);
+                            estSec = parseFloat(actualSec.toFixed(3));
+                        } else {
+                            // No audio chunk for this unit (e.g. typography) — keep
+                            // the unit at zero width: same start, zero duration.
+                            endMs = cursorMs;
+                            estSec = 0;
+                        }
+                        cursorMs = endMs;
+                        await persist('iu.upsertImageUnit')(buildId, bookId, chapterId, sceneId, u.unit_id, {
+                            scene_order: u.scene_order || 0,
+                            text: u.text,
+                            text_length: u.text_length || 0,
+                            text_proportion: 0,
+                            scene_duration_sec: realDuration,
+                            estimated_duration_sec: estSec,
+                            scene_audio_file: u.scene_audio_file || artifactNaming.sceneAudioName(bookId, chapterId, sceneId),
+                            start_ms: startMs,
+                            end_ms: endMs,
+                        });
+                    }
+                    log(`[IU-RECALC] ✓ ${bookId}/${chapterId}/${sceneId}: ACTUAL unit timings applied (Σ=${Object.values(perUnit).reduce((s, v) => s + v, 0).toFixed(2)}s, merged=${realDuration.toFixed(2)}s)`);
+                } else if (diff > 1.0) {
+                    const durLabel = oldSceneDur > 0
+                        ? `${oldSceneDur.toFixed(2)}s → ${realDuration.toFixed(2)}s (Δ=${diff.toFixed(2)}s)`
+                        : `first-time calculation (${realDuration.toFixed(2)}s)`;
+                    log(`[IU-RECALC] ${bookId}/${chapterId}/${sceneId}: ${durLabel}, recalculating ${units.length} IU timings (proportional fallback — no per-chunk unit data)`);
+                    const totalTextLen = units.reduce((s, u) => s + (u.text_length || 0), 0);
+                    let cursorMs = 0;
+                    const sceneDurationMs = Math.round(realDuration * 1000);
+                    for (const u of units) {
+                        const proportion = totalTextLen > 0 ? (u.text_length || 0) / totalTextLen : 1 / units.length;
+                        const durMs = Math.max(200, Math.round(realDuration * proportion * 1000));
+                        const startMs = cursorMs;
+                        let endMs = cursorMs + durMs;
+                        if (endMs > sceneDurationMs) endMs = sceneDurationMs;
+                        cursorMs = endMs;
+                        await persist('iu.upsertImageUnit')(buildId, bookId, chapterId, sceneId, u.unit_id, {
+                            scene_order: u.scene_order || 0,
+                            text: u.text,
+                            text_length: u.text_length || 0,
+                            text_proportion: parseFloat(proportion.toFixed(6)),
+                            scene_duration_sec: realDuration,
+                            estimated_duration_sec: parseFloat((realDuration * proportion).toFixed(3)),
+                            scene_audio_file: u.scene_audio_file || artifactNaming.sceneAudioName(bookId, chapterId, sceneId),
+                            start_ms: startMs,
+                            end_ms: endMs,
+                        });
+                    }
+                    log(`[IU-RECALC] ✓ ${bookId}/${chapterId}/${sceneId}: ${units.length} IU timings updated to ${realDuration.toFixed(2)}s total (proportional fallback)`);
+                } else {
+                    log(`[IU-RECALC] ${bookId}/${chapterId}/${sceneId}: duration unchanged (${realDuration.toFixed(2)}s ≈ ${oldSceneDur.toFixed(2)}s), skipping`);
+                }
+            }
+        } catch (err) {
+            warn(`[IU-RECALC] Failed to recalculate IU timings: ${err.message}`);
+        }
+    }
+
+    await progressEventsOp('publishProgress')(redis, bookId, { layer: 'audio', chapterId, sceneId });
+    log(`AUDIO_CALLBACK: ${bookId}/${chapterId}/${sceneId} -> READY check passed`);
+
+    return {
+        ok: true,
+        artifact: { buildId, path: audioPath }
+    };
+}
+
+async function handleImageCompleted(redis, bookId, chapterId, sceneId, buildId) {
+    // T1: возвращает { ok, retryable, reason, artifact }
+    log(`IMAGE_CALLBACK: ${bookId}/${chapterId}/${sceneId}`);
+
+    const sceneImage = image.resolveCanonicalSceneImage(
+        '/data/output', buildId, bookId, chapterId, sceneId
+    );
+
+    // Per-asset check
+    const assetStates = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+    const imageAllowed = assetStates && (
+        assetStates.image === state.AssetState.GENERATING ||
+        assetStates.image === state.AssetState.PENDING ||
+        assetStates.image === state.AssetState.DIRTY
+    );
+
+    if (!imageAllowed) {
+        warn(`IMAGE_CALLBACK: Invalid per-asset state: ${assetStates?.image || 'unknown'} — expected GENERATING/PENDING`);
+        log(`🔻 IMAGE callback rejected (invalid per-asset state): ${bookId}/${chapterId}/${sceneId}`);
+        return { ok: false, retryable: false, reason: 'invalid_asset_state' };
+    }
+
+    if (!sceneImage) {
+        error(`Scene image not found after completion: ${bookId}/${chapterId}/${sceneId}`);
+        const scene = { book_id: bookId, chapter_id: chapterId, scene_id: sceneId };
+        await logEvent(redis, scene, 'IMAGE_FAILED', 'image_generating', {
+            reason: 'not_found'
+        });
+        log(`🔻 IMAGE callback: image not found: ${bookId}/${chapterId}/${sceneId}`);
+        // T1.7: не throw, а ok:false — completeStage обработает
+        return { ok: false, retryable: true, reason: 'image_not_found' };
+    }
+
+    const imageInfo = await image.getImageMetadata(sceneImage);
+
+    try {
+        await persist('registry.registerSceneImageRedis')(redis, bookId, chapterId, sceneId, {
+            path: sceneImage,
+            width: imageInfo?.width || null,
+            height: imageInfo?.height || null,
+            ready: true
+        });
+        log(`CACHE-MANIFEST: image recorded for ${bookId}/${chapterId}/${sceneId}`);
+    } catch (err) {
+        warn(`Failed to register image asset: ${err.message}`);
+    }
+
+    const scene = { book_id: bookId, chapter_id: chapterId, scene_id: sceneId };
+    await logEvent(redis, scene, 'IMAGE_COMPLETED', 'image_ready', {
+        buildId,
+        path: sceneImage
+    });
+
+    // R4.1: Clear dirty unit IDs
+    try {
+        const dirtyIds = await persist('sceneAssets.getDirtyUnitIds')(bookId, chapterId, sceneId);
+        if (dirtyIds && dirtyIds.length > 0) {
+            const buildDir = path.join(artifactRoot(), buildId);
+            const stillPending = [];
+            for (const uid of dirtyIds) {
+                const pngPath = path.join(buildDir, artifactNaming.sceneImageName(bookId, chapterId, sceneId, uid));
+                if (!fs.existsSync(pngPath)) {
+                    stillPending.push(uid);
+                }
+            }
+            if (stillPending.length === 0) {
+                await persist('sceneAssets.clearDirtyUnitIds')(bookId, chapterId, sceneId);
+                log(`[DIRTY-UNITS-CLEARED] ${bookId}/${chapterId}/${sceneId}: all ${dirtyIds.length} dirty unit(s) completed, cleared`);
+                try {
+                    const iuPrefix = artifactNaming.iuImagePrefix(bookId, chapterId, sceneId);
+                    const allFiles = fs.existsSync(buildDir) ? fs.readdirSync(buildDir) : [];
+                    const iuFileCount = allFiles.filter(f => f.startsWith(iuPrefix) && f.endsWith('.png')).length;
+                    if (iuFileCount > 0) {
+                        const progKey = `animastor:iu-progress:${bookId}:${chapterId}:${sceneId}:image`;
+                        await redis.set(progKey, String(iuFileCount), 'EX', 14400);
+                        log(`[IU-COUNTER-RESET] ${bookId}/${chapterId}/${sceneId}: counter set to ${iuFileCount}`);
+                    }
+                } catch (counterErr) {
+                    warn(`Failed to reset IU progress counter: ${counterErr.message}`);
+                }
+            } else {
+                await persist('sceneAssets.setDirtyUnitIds')(bookId, chapterId, sceneId, stillPending);
+                log(`[DIRTY-UNITS-PARTIAL] ${bookId}/${chapterId}/${sceneId}: ${stillPending.length}/${dirtyIds.length} dirty units still pending: ${stillPending.join(', ')}`);
+            }
+        }
+    } catch (e) {
+        warn(`Failed to update dirty_unit_ids in IMAGE_CALLBACK: ${e.message}`);
+    }
+
+    try {
+        const scenePrefix = artifactNaming.iuScanPrefix(bookId, chapterId, sceneId);
+        let cursor = '0';
+        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);
+                log(`[IU-IN-FLIGHT-CLEARED] ${bookId}/${chapterId}/${sceneId}: cleared ${keys.length} in-flight markers`);
+            }
+        } while (cursor !== '0');
+    } catch (e) {
+        warn(`Failed to clear in-flight markers in IMAGE_CALLBACK: ${e.message}`);
+    }
+
+    await updateSceneChunks(redis, bookId, chapterId, sceneId, { image: true, image_status: 'ready' });
+    log(`IMAGE_CALLBACK: ${bookId}/${chapterId}/${sceneId} -> READY check passed`);
+
+    return {
+        ok: true,
+        artifact: { buildId, path: sceneImage }
+    };
+}
+
+async function handleVideoCompleted(redis, bookId, chapterId, sceneId, buildId) {
+    // T1: возвращает { ok, retryable, reason, artifact }
+    log(`VIDEO_CALLBACK: ${bookId}/${chapterId}/${sceneId}`);
+
+    const videoPath = `/data/output/${buildId}/${bookId}_${chapterId}_${sceneId}.mp4`;
+    const { valid, duration, metadata } = video.validateVideoFile(videoPath);
+
+    const assetStates = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+    const videoAllowed = assetStates && (
+        assetStates.video === state.AssetState.GENERATING ||
+        assetStates.video === state.AssetState.PENDING ||
+        assetStates.video === state.AssetState.DIRTY
+    );
+
+    if (!videoAllowed) {
+        warn(`VIDEO_CALLBACK: Invalid per-asset state: ${assetStates?.video || 'unknown'} (expected GENERATING/PENDING)`);
+        log(`🔻 VIDEO callback rejected (invalid per-asset state): ${bookId}/${chapterId}/${sceneId}`);
+        return { ok: false, retryable: false, reason: 'invalid_asset_state' };
+    }
+
+    if (!valid) {
+        error(`Video not valid after completion: ${bookId}/${chapterId}/${sceneId}`);
+        const scene = { book_id: bookId, chapter_id: chapterId, scene_id: sceneId };
+        await logEvent(redis, scene, 'VIDEO_FAILED', 'video_generating', {
+            reason: 'invalid'
+        });
+        log(`🔻 VIDEO callback: video invalid: ${bookId}/${chapterId}/${sceneId}`);
+        return { ok: false, retryable: true, reason: 'video_invalid' };
+    }
+
+    try {
+        await persist('registry.registerSceneVideoRedis')(redis, bookId, chapterId, sceneId, {
+            path: videoPath,
+            duration: duration || null,
+            width: metadata?.width || null,
+            height: metadata?.height || null,
+            ready: true
+        });
+        log(`CACHE-MANIFEST: video recorded for ${bookId}/${chapterId}/${sceneId}`);
+    } catch (err) {
+        warn(`Failed to register video asset: ${err.message}`);
+    }
+
+    const scene = { book_id: bookId, chapter_id: chapterId, scene_id: sceneId };
+    await logEvent(redis, scene, 'VIDEO_COMPLETED', 'video_ready', {
+        buildId,
+        path: videoPath,
+        duration: duration || 0
+    });
+
+    await video.updateSceneVideoStatus(redis, bookId, chapterId, sceneId, 'ready');
+    await updateSceneChunks(redis, bookId, chapterId, sceneId, { video: true, video_status: 'ready' });
+    await progressEventsOp('publishProgress')(redis, bookId, { layer: 'video', chapterId, sceneId });
+
+    try {
+        await persist('sceneAssets.clearDirtyFlag')(bookId, chapterId, sceneId);
+        log(`[DIRTY-FLAG-CLEARED] ${bookId}/${chapterId}/${sceneId}: is_dirty=FALSE`);
+    } catch (e) {
+        warn(`Failed to clear dirty flag: ${e.message}`);
+    }
+
+    await runtimeScheduler.removeSceneFromActiveIndex(redis, bookId, chapterId, sceneId);
+    log(`SCENE COMPLETE: ${bookId}/${chapterId}/${sceneId} - removed from active index`);
+
+    try {
+        const bookData = sceneData('loadBook')(bookId);
+        const sceneWindow = require('../runtime/scene-window');
+        const slide = await sceneWindow.trySlideWindowOnComplete(redis, bookId, bookData, buildId);
+        if (slide && slide.started > 0) {
+            log(`SCENE-COMPLETE auto-slide: started=${slide.started} remaining=${slide.remaining}`);
+        } else if (slide && slide.remaining === 0 && slide.started === 0) {
+            log(`SCENE-COMPLETE auto-slide: scope fully complete`);
+            try {
+                await progressEventsOp('publishProgress')(redis, bookId, { type: 'generation_complete' });
+            } catch (_) {}
+        }
+    } catch (e) {
+        warn(`SCENE-COMPLETE auto-slide failed: ${e.message}`);
+    }
+
+    return {
+        ok: true,
+        artifact: { buildId, path: videoPath }
+    };
+}
+
+async function completeSceneWithoutVideo(redis, loadedBook, bookId, chapterId, sceneId, buildId) {
+    log(`Completing scene without video: ${bookId}/${chapterId}/${sceneId}`);
+
+    // M5: setAssetState(READY) + syncLinearState moved to orchestrator.completeStageWithoutVideo
+    // This function is called THROUGH the facade, which handles state BEFORE calling here.
+
+
+    try {
+        await persist('sceneAssets.clearDirtyFlag')(bookId, chapterId, sceneId);
+    } catch (e) {
+        warn(`Failed to clear dirty flag in completeSceneWithoutVideo: ${e.message}`);
+    }
+
+    await runtimeScheduler.removeSceneFromActiveIndex(redis, bookId, chapterId, sceneId);
+    log(`Scene complete (no video): ${bookId}/${chapterId}/${sceneId} - removed from active index`);
+
+    try {
+        const sceneWindow = require('../runtime/scene-window');
+        const slide = await sceneWindow.trySlideWindowOnComplete(redis, bookId, loadedBook, buildId);
+        if (slide && slide.started > 0) {
+            log(`SCENE-COMPLETE auto-slide: started=${slide.started} remaining=${slide.remaining}`);
+        } else if (slide && slide.remaining === 0 && slide.started === 0) {
+            log(`SCENE-COMPLETE auto-slide (no-video): scope fully complete`);
+            try { await progressEventsOp('publishProgress')(redis, bookId, { type: 'generation_complete' }); } catch (_) {}
+        }
+    } catch (e) {
+        warn(`SCENE-COMPLETE auto-slide failed: ${e.message}`);
+    }
+}
+
+async function completeSceneWithoutImage(redis, loadedBook, bookId, chapterId, sceneId, buildId) {
+    log(`Completing scene without image: ${bookId}/${chapterId}/${sceneId}`);
+    // M5: setAssetState(READY) + syncLinearState moved to orchestrator.completeStageWithoutImage
+    // This function is called THROUGH the facade, which handles state BEFORE calling here.
+    log(`Scene complete (no image): ${bookId}/${chapterId}/${sceneId}`);
+
+    try {
+        await persist('sceneAssets.clearDirtyFlag')(bookId, chapterId, sceneId);
+    } catch (e) {
+        warn(`Failed to clear dirty flag in completeSceneWithoutImage: ${e.message}`);
+    }
+
+    await runtimeScheduler.removeSceneFromActiveIndex(redis, bookId, chapterId, sceneId);
+
+    try {
+        const sceneWindow = require('../runtime/scene-window');
+        const slide = await sceneWindow.trySlideWindowOnComplete(redis, bookId, loadedBook, buildId);
+        if (slide && slide.started > 0) {
+            log(`SCENE-COMPLETE auto-slide: started=${slide.started} remaining=${slide.remaining}`);
+        } else if (slide && slide.remaining === 0 && slide.started === 0) {
+            log(`SCENE-COMPLETE auto-slide (no-image): scope fully complete`);
+            try { await progressEventsOp('publishProgress')(redis, bookId, { type: 'generation_complete' }); } catch (_) {}
+        }
+    } catch (e) {
+        warn(`SCENE-COMPLETE auto-slide failed: ${e.message}`);
+    }
+}
+
+module.exports = {
+    updateSceneChunks,
+    handleAudioCompleted,
+    handleImageCompleted,
+    handleVideoCompleted,
+    completeSceneWithoutVideo,
+    completeSceneWithoutImage,
+    getStageHandler,
+    STAGE_HANDLERS,
+};