@animastor/orchestration 0.1.1

package/src/orchestration/scene-restoration.js

@@ -0,0 +1,129 @@
+const fs = require('fs');
+const path = require('path');
+const { lazyHostBinding, hostBinding } = require('../host/host-bindings');
+// §32.30: former host requires resolve lazily through the host-bindings seam.
+const state = lazyHostBinding('state');
+// S-4: identifier grammar composed from the canonical owner (bytes unchanged)
+const artifactNaming = require('@animastor/generation').artifactNaming;
+const runtimeScheduler = require('../runtime/runtime-scheduler');
+// O-2: persistence arrives ONLY through 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;
+// 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;
+const { log, warn } = require('./scene-utils');
+
+// §32.29 step 4a: the former process.env.OUTPUT_DIR read is closed — the
+// artifact root arrives through the composition-root host-bindings seam
+// (the host passes config.OUTPUT_DIR; identical value, identical fallback
+// semantics are host-owned now).
+const OUTPUT_DIR = () => hostBinding('artifactRoot');
+
+async function restoreSceneChunkStatus(redis, buildId, bookId, chapterId, sceneId, hasDirtyUnits, unitIds) {
+    const sceneWindow = require('../runtime/scene-window');
+    const buildDir = path.join(OUTPUT_DIR(), buildId);
+    const fileStatus = await sceneWindow.getSceneFilesStatus(buildDir, bookId, chapterId, sceneId);
+
+    if (!hasDirtyUnits) {
+        // Нет информации о конкретных dirty-юнитах (например, rebuild_all=true).
+        // Проверяем, есть ли какой-либо контент на диске.
+        // 🔧 Placeholder audio file counts as EXISTS but NOT as real content.
+        // If only placeholder audio exists, the scene still needs regeneration.
+        let audioIsReal = false;
+        if (fileStatus.audio.exists) {
+            try {
+                audioIsReal = await placeholderAudioOp('hasRealAudio')(bookId, chapterId, sceneId, buildId);
+            } catch (_) {}
+        }
+        const hasAnyContent = audioIsReal || fileStatus.image.exists || fileStatus.video.exists;
+        if (!hasAnyContent) {
+            log(`[RESTORE-SKIP] ${bookId}/${chapterId}/${sceneId}: no real content on disk — leaving as-is for regeneration`);
+            return { restored: false, reason: 'no_content' };
+        }
+
+        // Контент существует на диске (от предыдущей генерации).
+        // Восстанавливаем чанки, чтобы /assets-state показывал корректный прогресс
+        // (файлы, которые уже есть на диске).
+        await sceneWindow.restoreChunkStatusForScene(redis, buildId, bookId, chapterId, sceneId);
+
+        // T8: syncLinearState удалён — per-asset state единственный source of truth
+        log(`[RESTORE-PARTIAL] ${bookId}/${chapterId}/${sceneId}: chunks restored from disk (audio=${audioIsReal ? 'real' : 'placeholder'}, image=${fileStatus.image.exists}), keeping pending for regeneration`);
+        return { restored: true, reason: 'partial_restore' };
+    }
+
+    // Есть конкретные dirty-юниты (изменён visual prompt и т.п.).
+    // Удаляем stale PNG для этих юнитов, чтобы GPU обязательно перегенерировал их.
+    if (unitIds && Array.isArray(unitIds) && unitIds.length > 0) {
+        for (const unitId of unitIds) {
+            const imageIUId = artifactNaming.iuAssetId(bookId, chapterId, sceneId, unitId);
+            const pngPath = path.join(buildDir, `${imageIUId}.png`);
+            try {
+                if (fs.existsSync(pngPath)) {
+                    fs.unlinkSync(pngPath);
+                    log(`[RESTORE-PRE-DELETE] Deleted stale PNG: ${imageIUId}.png`);
+                }
+            } catch (delErr) {
+                console.warn(`[RESTORE-PRE-DELETE] Failed to delete ${imageIUId}.png: ${delErr.message}`);
+            }
+            try {
+                await redis.del(`animastor:job:${imageIUId}:image`);
+                log(`[RESTORE-PRE-DELETE] Cleared GPU dedup for ${imageIUId}`);
+            } catch (dedupErr) {
+                console.warn(`[RESTORE-PRE-DELETE] Failed to clear dedup for ${imageIUId}: ${dedupErr.message}`);
+            }
+        }
+    }
+
+    // Аудио не было затронуто изменением visual prompt — восстанавливаем.
+    await sceneWindow.restoreChunkStatusForScene(redis, buildId, bookId, chapterId, sceneId);
+
+    // Audio: не затронуто, оставляем READY (если файл существует И версия актуальна).
+    // Д.3 (M3): Don't mark audio as READY solely based on file existence —
+    // check PG version first. If content_version was bumped (force-regen),
+    // stale audio files don't count as ready.
+    if (fileStatus.audio.exists) {
+        let audioVersionStale = false;
+        try {
+            // O-2: version staleness via the PersistencePort (same scenes-table
+            // row shape as pre-O-2, SQL lives in the host adapter).
+            const sceneRows = await persist('sceneVersions.getSceneVersions')(bookId, chapterId, sceneId);
+            if (sceneRows.length > 0) {
+                const sv = sceneRows[0];
+                const aAsset = await persist('sceneAssets.getAsset')(bookId, chapterId, sceneId, 'audio', buildId)
+                    || await persist('sceneAssets.getAsset')(bookId, chapterId, sceneId, 'audio');
+                if (aAsset && aAsset.scene_content_version != null && sv.content_version != null &&
+                    aAsset.scene_content_version < sv.content_version) {
+                    audioVersionStale = true;
+                }
+                if (aAsset && aAsset.scene_audio_config_version != null && sv.audio_config_version != null &&
+                    aAsset.scene_audio_config_version < sv.audio_config_version) {
+                    audioVersionStale = true;
+                }
+            }
+        } catch (_) {}
+        if (!audioVersionStale) {
+            await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, 'audio', state.AssetState.READY);
+        } else {
+            log(`[RESTORE-AUDIO-STALE] ${bookId}/${chapterId}/${sceneId}: audio file exists but version is stale — leaving pending`);
+        }
+    }
+    // Image: всегда DIRTY — при наличии dirty-юнитов визуальный контент
+    // нужно перегенерировать. Если сюда попали с hasDirtyUnits=true,
+    // значит есть изменения, влияющие на image.
+    // M5: Route through markDirtyScene — only image needs DIRTY
+    // (audio was just set to READY above, video is not affected)
+    // M5 Шаг 3: syncLinearState уже внутри markDirtyScene
+    // S-5: canonical owner is the state layer (facade re-exports it) —
+    // calling the facade here would keep a scene-restoration→orchestrator
+    // cycle edge inside orchestration.
+    const stateOps = lazyHostBinding('stateOps');
+    await stateOps.markDirtyScene(redis, bookId, chapterId, sceneId, ['image']);
+
+    log(`[RESTORE-PER-UNIT] ${bookId}/${chapterId}/${sceneId}: ${unitIds?.length || 0} dirty unit(s) — audio=${fileStatus.audio.exists}, image=${unitIds?.length > 0 ? 'dirty' : fileStatus.image.exists}, PNG pre-deleted`);
+    return { restored: true, reason: 'per_unit_restore' };
+}
+
+module.exports = { restoreSceneChunkStatus };

package/src/orchestration/scene-utils.js

@@ -0,0 +1,36 @@
+const { lazyHostBinding } = require('../host/host-bindings');
+// §32.30: former host require ('../state/event-journal') resolves lazily
+// through the host-bindings seam.
+const journal = lazyHostBinding('journal');
+
+const logPrefix = '[ORCH]';
+
+function log(msg) {
+    console.log(`${logPrefix} ${msg}`);
+}
+
+function warn(msg) {
+    console.warn(`${logPrefix} ⚠️ ${msg}`);
+}
+
+function error(msg) {
+    console.error(`${logPrefix} ❌ ${msg}`);
+}
+
+async function logEvent(redis, scene, type, stateName, details = {}) {
+    const bookId = scene.book_id;
+    const chapterId = scene.chapter_id;
+    const sceneId = scene.scene_id;
+
+    await journal.appendSceneEvent(
+        redis,
+        bookId,
+        chapterId,
+        sceneId,
+        type,
+        stateName,
+        details
+    );
+}
+
+module.exports = { log, warn, error, logEvent };

package/src/runtime/active-scenes-index.js

@@ -0,0 +1,164 @@
+// ======================================================
+// ACTIVE SCENES INDEX
+// ======================================================
+// Redis Set tracking active scenes (_audio_pending through video_generating).
+// Enables efficient iteration without SCAN operations.
+
+const { lazyHostBinding } = require('../host/host-bindings');
+// §32.30: former host requires resolve lazily through the host-bindings seam.
+const state = lazyHostBinding('state');
+
+const ACTIVE_SCENES_KEY = 'animastor:active-scenes';
+
+/**
+ * Check if a scene is in the active index.
+ */
+async function isActive(redis, bookId, chapterId, sceneId) {
+    const sceneKey = `${bookId}:${chapterId}:${sceneId}`;
+    return await redis.sismember(ACTIVE_SCENES_KEY, sceneKey);
+}
+
+/**
+ * Get all active scene keys.
+ */
+async function getAllActiveSceneKeys(redis) {
+    return await redis.smembers(ACTIVE_SCENES_KEY);
+}
+
+/**
+ * Get count of active scenes.
+ */
+async function getActiveCount(redis) {
+    return await redis.scard(ACTIVE_SCENES_KEY);
+}
+
+/**
+ * Add scene to active index when it enters generating/pending state.
+ */
+async function addActiveScene(redis, bookId, chapterId, sceneId) {
+    const sceneKey = `${bookId}:${chapterId}:${sceneId}`;
+    const added = await redis.sadd(ACTIVE_SCENES_KEY, sceneKey);
+    return { added: added > 0, sceneKey };
+}
+
+/**
+ * Remove scene from active index when it completes or fails.
+ */
+async function removeActiveScene(redis, bookId, chapterId, sceneId) {
+    const sceneKey = `${bookId}:${chapterId}:${sceneId}`;
+    const removed = await redis.srem(ACTIVE_SCENES_KEY, sceneKey);
+    return { removed: removed > 0, sceneKey };
+}
+
+/**
+ * Parse scene key back to components.
+ */
+function parseSceneKey(sceneKey) {
+    const parts = sceneKey.split(':');
+    if (parts.length !== 3) {
+        return null;
+    }
+    return {
+        bookId: parts[0],
+        chapterId: parts[1],
+        sceneId: parts[2]
+    };
+}
+
+/**
+ * Get detailed info about all active scenes.
+ */
+async function getActiveScenesDetail(redis) {
+    const activeKeys = await getAllActiveSceneKeys(redis);
+    const scenes = [];
+
+    for (const key of activeKeys) {
+        const parsed = parseSceneKey(key);
+        if (!parsed) continue;
+
+        const assetStates = await state.getAssetStates(redis, parsed.bookId, parsed.chapterId, parsed.sceneId);
+
+        scenes.push({
+            ...parsed,
+            currentState: 'active',
+            updatedAt: null,
+            buildId: null,
+            assetStates
+        });
+    }
+
+    return scenes;
+}
+
+/**
+ * Find scenes in a specific state.
+ */
+async function findScenesByState(redis, targetState) {
+    const allActive = await getActiveScenesDetail(redis);
+    return allActive.filter(s => s.currentState === targetState);
+}
+
+/**
+ * T8: Check if scene is currently generating (audio, image, or video).
+ * Uses per-asset states as source of truth.
+ */
+async function isGenerating(redis, bookId, chapterId, sceneId) {
+    const assetStates = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+    if (!assetStates) return false;
+    return assetStates.audio === state.AssetState.GENERATING ||
+           assetStates.image === state.AssetState.GENERATING ||
+           assetStates.video === state.AssetState.GENERATING;
+}
+
+/**
+ * T8: Check if scene is in pending state (waiting to start).
+ * Uses per-asset states as source of truth.
+ */
+async function isPending(redis, bookId, chapterId, sceneId) {
+    const assetStates = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+    if (!assetStates) return false;
+    return assetStates.audio === state.AssetState.PENDING ||
+           assetStates.image === state.AssetState.PENDING ||
+           assetStates.video === state.AssetState.PENDING;
+}
+
+/**
+ * T8: Check if scene is in terminal state (complete or failed).
+ * Uses per-asset states as source of truth.
+ */
+async function isTerminal(redis, bookId, chapterId, sceneId) {
+    const assetStates = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+    if (!assetStates) return false;
+    // Terminal: all enabled assets are READY, PLACEHOLDER, or FAILED
+    const allAssetsFinished = (
+        (assetStates.audio === state.AssetState.READY ||
+         assetStates.audio === state.AssetState.PLACEHOLDER ||
+         assetStates.audio === state.AssetState.FAILED) &&
+        (assetStates.image === state.AssetState.READY ||
+         assetStates.image === state.AssetState.PLACEHOLDER ||
+         assetStates.image === state.AssetState.FAILED) &&
+        (assetStates.video === state.AssetState.READY ||
+         assetStates.video === state.AssetState.PLACEHOLDER ||
+         assetStates.video === state.AssetState.FAILED)
+    );
+    return allAssetsFinished;
+}
+
+// ======================================================
+// EXPORTS
+// ======================================================
+
+module.exports = {
+    ACTIVE_SCENES_KEY,
+    isActive,
+    getAllActiveSceneKeys,
+    getActiveCount,
+    addActiveScene,
+    removeActiveScene,
+    parseSceneKey,
+    getActiveScenesDetail,
+    findScenesByState,
+    isGenerating,
+    isPending,
+    isTerminal
+};

package/src/runtime/audio-fsm-port.js

@@ -0,0 +1,187 @@
+// ======================================================
+// O-7 PORT: AudioFsmPort — runtime/orchestration
+// audio-FSM contract
+// ======================================================
+// The runtime and orchestration tiers must not know the audio-orchestrator
+// host service. The Redis key grammar (`animastor:audio-orch:*`), the JSON
+// state envelope, the valid-transition map and every chunk-completeness /
+// merge / hub-dedup detail stay HOST-side (backend/src/services/
+// audio-orchestrator.js); the tiers drive the audio scene FSM ONLY through
+// this port, wired by the composition root (backend.cjs) at startup.
+//
+//   runtime/** + orchestration/**        (tier consumers)
+//       ↓ consume audio-FSM ops through
+//   runtime/audio-fsm-port.js            ← THIS PORT (tier-owned contract)
+//       ↑ wired by the host
+//   storage/audio-fsm-adapter             (host FSM adapter)
+//
+// This is the O-2/O-3/O-4/O-5 port convention (runtime/persistence-port.js,
+// runtime/scene-data-port.js, runtime/placeholder-audio-port.js,
+// runtime/progress-events-port.js): a zero-require contract module, a
+// fail-fast call-time resolver, one set/wired/reset surface. No Redis key
+// strings, no JSON state encoding, no transition-map internals and no
+// "future ops" cross the boundary — the contract below is EXACTLY the set
+// of operations the two tiers use today (measured at O-7 reconnaissance,
+// §32.24; the O-6 audit had measured 13 ops for the combined MediaFsmPort
+// audio half — the tiers' actual usage is 12 ops + the phase constants):
+//
+//   getState           — read the audio-FSM phase record (dispatch DONE
+//                        guard, invariant checks)
+//   setState           — persist a repaired record (recovery leg that
+//                        re-fills expected_count before re-driving merge)
+//   deleteState        — drop a stale record before re-initialization
+//                        (scene-orchestrator stale-phase reset, recovery
+//                        unknown-phase sweep)
+//   initPlaceholderReady — create the initial PLACEHOLDER_READY record
+//                        (scene-window startScene, scene-orchestrator
+//                        no_state/stale-phase recovery init)
+//   setGenerating     — PLACEHOLDER_READY → GENERATING before TTS dispatch
+//   setWaitingChunks  — GENERATING → WAITING_CHUNKS before jobs are sent
+//   setMerging        — → MERGING fast-track legs
+//   setDone           — → DONE fast-track/recovery legs
+//   setFailed         — → FAILED (orchestrator failStage facade sync,
+//                        recovery legs)
+//   completeChunk     — drive chunk-completeness + merge from a chunk
+//                        callback / recovery (host-owned merge logic)
+//   failWaitingScene  — WAITING_CHUNKS → FAILED with hub-dedup cleanup
+//                        (stall watchdog, recovery)
+//   scanAllStates     — enumerate every non-terminal record (stall
+//                        watchdog, startup recovery)
+//   PHASES            — the phase-name constants the tiers compare
+//                        orchState.phase against (DONE, FAILED, NEW,
+//                        PLACEHOLDER_READY, GENERATING, WAITING_CHUNKS,
+//                        MERGING). Phase NAMES are the FSM's public
+//                        vocabulary; everything about their STORAGE
+//                        (key grammar, envelope, transitions) stays
+//                        host-side in the adapter.
+//
+// Optional-load semantics are the ADAPTER's concern, not the port's: the
+// reconciliation optional-load legs (try/catch → return 0 when the host
+// service is absent) keep their exact pre-O-7 behavior by wrapping the
+// ADAPTER's lazy require, not by relaxing this fail-fast contract.
+//
+// Deliberately NOT in the port: the video FSM (services/video-orchestrator
+// — its own future seam step, never merged here), key()/PREFIX/createState/
+// transitionState internals (Redis/storage knowledge), any combined
+// MediaFsmPort surface (rejected at O-6 as a 27-member god-interface) and
+// any CRUD "for later".
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md §32.24 (O-7 DONE)
+// ======================================================
+
+const OPS = [
+    'getState',
+    'setState',
+    'deleteState',
+    'initPlaceholderReady',
+    'setGenerating',
+    'setWaitingChunks',
+    'setMerging',
+    'setDone',
+    'setFailed',
+    'completeChunk',
+    'failWaitingScene',
+    'scanAllStates',
+];
+
+// Phase names the tier consumers compare against — the FSM's public
+// vocabulary (a frozen set: adding one is a contract change, not a key
+// grammar change — the adapter owns the storage behind these names).
+const PHASE_CONSTANTS = [
+    'NEW',
+    'PLACEHOLDER_READY',
+    'GENERATING',
+    'WAITING_CHUNKS',
+    'MERGING',
+    'DONE',
+    'FAILED',
+];
+
+let impl = null;
+
+/**
+ * Wire the host audio-FSM adapter. Called once by the composition root
+ * (backend.cjs) BEFORE any runtime/orchestration audio-FSM consumer runs.
+ * The adapter must expose every op in OPS as a function; the PHASES
+ * constants resolve lazily at call time (audioFsmPhases()) so wiring never
+ * forces a host-service load — the O-2..O-5 lazy-resolution discipline.
+ * @param {object} adapter — flat map with every op in OPS as a function
+ * plus a PHASES constant object (validated on first phase read, not here).
+ */
+function setAudioFsmPort(adapter) {
+    if (!adapter) {
+        throw new Error('audio-fsm-port: adapter is required');
+    }
+    for (const op of OPS) {
+        if (typeof adapter[op] !== 'function') {
+            throw new Error(`audio-fsm-port: adapter must implement ${op}()`);
+        }
+    }
+    if (!('PHASES' in adapter)) {
+        throw new Error('audio-fsm-port: adapter must carry the PHASES constants');
+    }
+    impl = adapter;
+}
+
+/** Resolve the port at CALL time — fail-fast when unwired. */
+function audioFsm() {
+    if (!impl) {
+        throw new Error(
+            'audio-fsm-port: not wired — the composition root must call ' +
+            'setAudioFsmPort(adapter) (storage/audio-fsm-adapter) ' +
+            'before runtime/orchestration audio-FSM consumers run (O-7)'
+        );
+    }
+    return impl;
+}
+
+/**
+ * Shorthand op resolver: `audioFsmOp('getState')(...)`.
+ * Fails fast when the port or the single op is missing — a missing phase
+ * writer silently degrading into a no-op would corrupt the audio FSM
+ * (ghost GENERATING scenes, lost recovery legs).
+ * @param {string} op — op name from OPS
+ */
+function audioFsmOp(op) {
+    const fn = impl?.[op];
+    if (typeof fn !== 'function') {
+        throw new Error(`audio-fsm-port: op '${op}' is not wired (O-7)`);
+    }
+    return fn;
+}
+
+/** Phase constants through the port (fail-fast at CALL time — never loaded
+ *  during composition-root wiring, preserving the lazy-resolution parity
+ *  with test stubs). */
+function audioFsmPhases() {
+    const phases = audioFsm().PHASES;
+    if (!phases || typeof phases !== 'object') {
+        throw new Error('audio-fsm-port: PHASES is not wired (O-7)');
+    }
+    for (const phase of PHASE_CONSTANTS) {
+        if (!(phase in phases)) {
+            throw new Error(`audio-fsm-port: PHASES is missing the ${phase} constant (O-7)`);
+        }
+    }
+    return phases;
+}
+
+function isAudioFsmPortWired() {
+    return impl !== null;
+}
+
+/** Test hygiene: drop the wiring (mocha hooks). */
+function _resetAudioFsmPort() {
+    impl = null;
+}
+
+module.exports = {
+    OPS,
+    PHASE_CONSTANTS,
+    setAudioFsmPort,
+    audioFsm,
+    audioFsmOp,
+    audioFsmPhases,
+    isAudioFsmPortWired,
+    _resetAudioFsmPort,
+};