@animastor/orchestration 0.1.4 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@animastor/orchestration",
-    "version": "0.1.4",
+    "version": "0.1.7",
     "description": "Animastor Orchestration — the generation orchestration/runtime contour of the Animastor backend, physically extracted from the host (§32.30): the unified generation lifecycle owner (orchestrator facade, stage executor, scene callbacks/restoration), the dispatch engine and its lease/quota/retry managers, the reconciliation engine and counter reconciliation, the scene window/scheduler/worker-health, the runtime-result emitter/consumer, and the eight O-2..O-10 port contracts (Persistence, SceneData, PlaceholderAudio, ProgressEvents, AudioFsm, VideoFsm, HubCancel, LayerConfig). The package reaches the host (runtime config slices, Redis-domain state layer, media facades, the S-5 seam registry, the artifact root, the PW-2 workspace resolver) ONLY through the composition-root host-bindings seam — no backend/src require, no storage/book/routes/services, no Redis, no PG, no Express inside.",
     "keywords": [
         "animastor",

package/src/orchestration/orchestrator.js

@@ -20,6 +20,10 @@
 
 // S-2: media-type knowledge (stage lists, fail-event map) resolved via registry
 const mediaRegistry = require('@animastor/generation').mediaRegistry;
+// S-4: filename grammar composed from the canonical owner (bytes unchanged).
+// D1 (stage146): must live at module scope — resetScenes() uses it outside the
+// beginStage() body, so a per-function declaration threw ReferenceError there.
+const artifactNaming = require('@animastor/generation').artifactNaming;
 // 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');
@@ -56,8 +60,6 @@ async function planScene(redis, bookId, chapterId, sceneId) {
 // для исполнения генерации).
 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;
@@ -157,20 +159,37 @@ async function completeStage(redis, bookId, chapterId, sceneId, stage, buildId,
 
                 if (sceneRows.length === 1) {
                     const sv = sceneRows[0];
-                    const asset = await persist('sceneAssets.getAsset')(bookId, chapterId, sceneId, stage, buildId);
-
-                    if (asset) {
+                    const versionsConfirm = (row) => {
                         const contentVersionConfirmed =
-                            asset.scene_content_version != null &&
+                            row.scene_content_version != null &&
                             sv.content_version != null &&
-                            asset.scene_content_version >= sv.content_version;
+                            row.scene_content_version >= sv.content_version;
                         const audioVersionConfirmed =
                             stage !== 'audio' || (
-                                asset.scene_audio_config_version != null &&
+                                row.scene_audio_config_version != null &&
                                 sv.audio_config_version != null &&
-                                asset.scene_audio_config_version >= sv.audio_config_version
+                                row.scene_audio_config_version >= sv.audio_config_version
                             );
-                        shouldWriteReady = contentVersionConfirmed && audioVersionConfirmed;
+                        return contentVersionConfirmed && audioVersionConfirmed;
+                    };
+
+                    let asset = await persist('sceneAssets.getAsset')(bookId, chapterId, sceneId, stage, buildId);
+
+                    if (!asset) {
+                        // A1 (stage147): единственная строка ключа может быть
+                        // легаси-строкой с build_id = NULL (Stage 73/76 семейство):
+                        // getAsset(buildId) её не видит, а markReady — единственный
+                        // писатель build_id — вызывается ПОСЛЕ gate (замкнутый цикл
+                        // DIRTY каждые 5 с, stage146 §5.4). РОВНО одно дополнительное
+                        // чтение строки того же ключа с build_id IS NULL — не строки
+                        // другого билда и не «последней любой». Версии проверяются
+                        // теми же правилами; после пропуска markReady проставит
+                        // build_id по существующей логике (buildIdFromArtifactPath).
+                        asset = await persist('sceneAssets.getAssetNullBuild')(bookId, chapterId, sceneId, stage);
+                    }
+
+                    if (asset) {
+                        shouldWriteReady = versionsConfirm(asset);
                     }
                 } else if (sceneRows.length === 0) {
                     // Legacy-книга без version-схемы — READY разрешён (сцена

package/src/runtime/persistence-port.js

@@ -24,7 +24,8 @@
 //                      is a routes-side concern and stays there
 //   sceneAssets      — per-asset status truth + version gates + dirty
 //                      units (orchestrator completeStage version gate,
-//                      scene-orchestrator dirty reads, scene-window
+//                      incl. its A1 build_id IS NULL fallback read
+//                      getAssetNullBuild, scene-orchestrator dirty reads, scene-window
 //                      staleness, scene-callbacks markReady/dirty clears,
 //                      scene-restoration, reconciliation rebuildWorkList);
 //                      markStale is consumed by state/scene-state-ops
@@ -58,6 +59,9 @@ const OPS = [
     'tasks.hasActiveTaskForScene',
 
     'sceneAssets.getAsset',
+    // A1 (stage147): version-gate fallback read — same key with
+    // build_id IS NULL ONLY (never another build, never "latest any row").
+    'sceneAssets.getAssetNullBuild',
     'sceneAssets.markReady',
     'sceneAssets.stampSceneVersionsForDispatch',
     'sceneAssets.getDirtyUnitIds',

package/test/stage146-d1-artifact-naming.test.js

@@ -0,0 +1,103 @@
+// ======================================================
+// STAGE 146 — D1 REGRESSION: artifactNaming must be visible to resetScenes
+// ======================================================
+// D1: `const artifactNaming = require('@animastor/generation').artifactNaming;`
+// used to live INSIDE beginStage(). resetScenes() also reads it (step 6 — the
+// stale-PNG/preview pre-delete branch, formerly lines 534/537/555), so on the
+// pre-fix code that branch threw `ReferenceError: artifactNaming is not
+// defined` and /regenerate returned HTTP 500.
+//
+// This test exercises EXACTLY that branch on the fresh package sources:
+//   • resetScenes() with a dirty unit and cleanPngUnitIds reaches step 6;
+//   • it must NOT throw;
+//   • it must delete the old PNG AND the old preview for that unit.
+//
+// The test FAILS on the pre-fix code (the ReferenceError escapes resetScenes —
+// step 6 is not wrapped in try/catch) and PASSES once artifactNaming is hoisted
+// to module scope.
+// ======================================================
+
+const { expect } = require('chai');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { bindHostModules } = require('../src/host/host-bindings');
+const { setHubCancelPort, _resetHubCancelPort } = require('../src/runtime/hub-cancel-port');
+const { createMockRedis } = require('./mocks/redis-mock');
+const artifactNaming = require('@animastor/generation').artifactNaming;
+
+const orchestrator = require('../src/orchestration/orchestrator');
+
+const BOOK = 'b1';
+const CHAPTER = 'ch1';
+const SCENE = 'sc1';
+const BUILD = 'build1';
+const UID = 'iu_001';
+
+describe('Stage 146 — D1: resetScenes reads artifactNaming at module scope', function () {
+    this.timeout(10000);
+
+    let tmpRoot;
+    let redis;
+
+    before(() => {
+        tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'stage146-d1-'));
+        redis = createMockRedis();
+        // resetScenes reaches the PNG-delete branch through these two seams.
+        bindHostModules({
+            config: () => ({
+                OUTPUT_DIR: tmpRoot,
+                TIMEOUTS: { FORCE_DISPATCH_TTL_S: 3600 },
+            }),
+            journal: () => ({
+                EventType: { SCENE_RESET: 'SCENE_RESET', SCENE_RESET_COMPLETED: 'SCENE_RESET_COMPLETED' },
+                appendSceneEvent: async () => {},
+            }),
+        });
+        setHubCancelPort({ clearHubDispatches: async () => ({ requested: 0, cleared: 0, failed: 0 }) });
+    });
+
+    after(() => {
+        _resetHubCancelPort();
+        // Restore the fail-fast default from test/test-bindings.js.
+        bindHostModules({
+            config: () => { throw new Error('[D1-TEST] config unwired'); },
+            journal: () => { throw new Error('[D1-TEST] journal unwired'); },
+        });
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+    });
+
+    it('removes the stale PNG and preview of a dirty unit without throwing', async () => {
+        const buildDir = path.join(tmpRoot, BUILD);
+        fs.mkdirSync(buildDir, { recursive: true });
+
+        const pngPath = path.join(buildDir, artifactNaming.sceneImageName(BOOK, CHAPTER, SCENE, UID));
+        const previewPath = path.join(buildDir, artifactNaming.sceneImagePreviewName(BOOK, CHAPTER, SCENE, UID));
+        fs.writeFileSync(pngPath, 'png-bytes');
+        fs.writeFileSync(previewPath, 'preview-bytes');
+        expect(fs.existsSync(pngPath), 'fixture PNG must exist').to.equal(true);
+        expect(fs.existsSync(previewPath), 'fixture preview must exist').to.equal(true);
+
+        const scenes = [{ chapter_id: CHAPTER, scene_id: SCENE, dirty_layers: ['image'] }];
+        const layerCfg = { image_enabled: true };
+        const bookDiff = { markDirtyScenes: async () => ({ marked: 1 }) };
+
+        const res = await orchestrator.resetScenes(
+            redis, BOOK, BUILD, scenes, layerCfg,
+            {
+                scope: 'SCENE',
+                chapterId: CHAPTER,
+                sceneId: SCENE,
+                bookDiff,
+                cleanPngUnitIds: { [`${CHAPTER}_${SCENE}`]: [UID] },
+            }
+        );
+
+        expect(res.reset_scenes).to.equal(1);
+        expect(res.marked).to.equal(1);
+        // The pre-fix bug threw before this point, so these two assertions are
+        // what the regression pins down.
+        expect(fs.existsSync(pngPath), 'old PNG must be deleted').to.equal(false);
+        expect(fs.existsSync(previewPath), 'old preview must be deleted').to.equal(false);
+    });
+});

package/test/stage147-a1-null-build-gate.test.js

@@ -0,0 +1,211 @@
+// ======================================================
+// STAGE 147 — A1 REGRESSION: version-gate must see the build_id IS NULL row
+// ======================================================
+// A1 (stage146 §5.4): the key's only scene_assets row had build_id = NULL.
+// completeStage read the asset via sceneAssets.getAsset(..., buildId) —
+// which filters `build_id = $5` — so the row was invisible; markReady, the
+// ONLY writer able to stamp build_id (buildIdFromArtifactPath), runs BEHIND
+// the gate. Result: endless DIRTY + re-dispatch every 5 s scheduler tick
+// (cache_hit → callback → "stale" → DIRTY).
+//
+// The fix (orchestrator.completeStage): when the build-scoped read misses,
+// perform exactly ONE additional read of the SAME key with build_id IS NULL
+// (port op sceneAssets.getAssetNullBuild — never another build's row, never
+// "latest any row"), apply the SAME version rules, then let markReady stamp
+// build_id as before.
+//
+// On the PRE-FIX code tests 1 and 2 FAIL (gate stays DIRTY / fallback op
+// never consulted); they PASS with the fix. Fail-closed on PG errors is
+// preserved for both reads.
+// ======================================================
+
+const { expect } = require('chai');
+const { bindHostModules } = require('../src/host/host-bindings');
+const {
+    OPS, setPersistencePort, _resetPersistencePort,
+} = require('../src/runtime/persistence-port');
+const { createMockRedis } = require('./mocks/redis-mock');
+
+const ORCH = require.resolve('../src/orchestration/orchestrator');
+const CALLBACKS = require.resolve('../src/orchestration/scene-callbacks');
+const DISPATCH = require.resolve('../src/runtime/dispatch-engine');
+
+const BOOK = 'book-a1';
+const CHAPTER = 'ch-a1';
+const SCENE = 'sc-a1';
+const BUILD = 'build_a1';
+const ARTIFACT = `/data/output/${BUILD}/scene_a1.png`;
+const SCENE_VERSIONS = [{ content_version: 5, audio_config_version: 5 }];
+
+// Port adapter built from the declared OPS (contract completeness is
+// asserted implicitly: setPersistencePort fails fast on any missing op).
+function makeAdapter(overrides = {}) {
+    const adapter = {};
+    for (const op of OPS) {
+        const noop = async () => null;
+        const [ns, fn] = op.includes('.') ? op.split('.') : [null, op];
+        if (ns === null) adapter[fn] = overrides[op] || noop;
+        else {
+            adapter[ns] = adapter[ns] || {};
+            adapter[ns][fn] = (overrides[op]) || noop;
+        }
+    }
+    return adapter;
+}
+
+describe('Stage 147 — A1: version-gate fallback на строку build_id IS NULL (пакет)', function () {
+    this.timeout(10000);
+
+    let redis;
+    let calls;
+    let savedCache;
+
+    function stubModule(resolvedPath, exports) {
+        savedCache.set(resolvedPath, require.cache[resolvedPath]);
+        require.cache[resolvedPath] = { exports, loaded: true };
+    }
+
+    beforeEach(() => {
+        redis = createMockRedis();
+        calls = { markReady: [], nullBuildReads: [] };
+        savedCache = new Map();
+        for (const p of [CALLBACKS, DISPATCH]) {
+            savedCache.set(p, require.cache[p]);
+            delete require.cache[p];
+        }
+
+        // Host seams the gate path touches (state restore after READY).
+        bindHostModules({
+            config: () => ({ OUTPUT_DIR: '/data/output' }),
+            state: () => ({
+                AssetState: {
+                    NEW: 'new', DIRTY: 'dirty', PENDING: 'pending',
+                    GENERATING: 'generating', READY: 'ready', FAILED: 'failed',
+                },
+                unsafeRestoreAssetState: async (r, b, c, s, asset, status) => {
+                    calls.stateWrite = { asset, status };
+                },
+            }),
+            journal: () => ({ EventType: {}, appendSceneEvent: async () => {} }),
+        });
+
+        stubModule(CALLBACKS, {
+            STAGE_HANDLERS: {
+                image: async () => ({ ok: true, artifact: { buildId: BUILD, path: ARTIFACT } }),
+            },
+        });
+        stubModule(DISPATCH, {
+            verifyDispatchIdentity: async () => ({ valid: true, metadata: {} }),
+            finalizeDispatch: async (r, b, c, s, stage, opts) => {
+                calls.finalize = { stage, opts };
+                return { finalized: true };
+            },
+        });
+
+        setPersistencePort(makeAdapter({
+            'sceneVersions.getSceneVersions': async () => SCENE_VERSIONS,
+            'sceneAssets.getAsset': async () => (calls.buildRow === undefined ? null : calls.buildRow),
+            'sceneAssets.getAssetNullBuild': async (...args) => {
+                calls.nullBuildReads.push(args);
+                if (calls.nullRowError) throw calls.nullRowError;
+                return calls.nullRow || null;
+            },
+            'sceneAssets.markReady': async (...args) => {
+                calls.markReady.push(args);
+                return { status: 'ready' };
+            },
+        }));
+    });
+
+    afterEach(() => {
+        for (const [p, entry] of savedCache) {
+            if (entry) require.cache[p] = entry;
+            else delete require.cache[p];
+        }
+        _resetPersistencePort();
+        calls = {};
+        // Возврат fail-fast дефолтов из test/test-bindings.js
+        bindHostModules({
+            journal: () => {
+                throw new Error('[ORCH-TEST-BINDINGS] host journal not wired — wire it in the test that asserts journal behavior');
+            },
+        });
+    });
+
+    async function runGate(stage = 'image') {
+        const orchestrator = require(ORCH);
+        return orchestrator.completeStage(redis, BOOK, CHAPTER, SCENE, stage, BUILD, 'dispatch-a1');
+    }
+
+    it('1. NULL-строка с подтверждённой версией → READY с одного вызова, markReady вызван', async () => {
+        calls.buildRow = null; // getAsset(buildId) промахнулся
+        calls.nullRow = { build_id: null, scene_content_version: 5, scene_audio_config_version: 5 };
+
+        const result = await runGate();
+
+        expect(result.completed, 'fallback-чтение должно пропустить READY').to.be.true;
+        expect(calls.markReady).to.have.length(1);
+        expect(calls.markReady[0].slice(0, 5)).to.deep.equal([BOOK, CHAPTER, SCENE, 'image', ARTIFACT]);
+        expect(calls.nullBuildReads, 'дополнительное чтение — ровно одно').to.have.length(1);
+        expect(calls.nullBuildReads[0]).to.deep.equal([BOOK, CHAPTER, SCENE, 'image']);
+        expect(calls.stateWrite).to.deep.equal({ asset: 'image', status: 'ready' });
+        expect(calls.finalize.opts.outcome).to.equal('success');
+    });
+
+    it('2. NULL-строка с устаревшей версией (2 < 5) → не READY', async () => {
+        calls.buildRow = null;
+        calls.nullRow = { build_id: null, scene_content_version: 2, scene_audio_config_version: 2 };
+
+        const result = await runGate();
+
+        expect(result.completed).to.be.false;
+        expect(result.reason).to.equal('stale');
+        expect(calls.markReady).to.have.length(0);
+        expect(calls.stateWrite).to.deep.equal({ asset: 'image', status: 'dirty' });
+    });
+
+    it('3. строки этого билда нет, NULL-строки нет (только чужой билд) → не READY', async () => {
+        calls.buildRow = null;
+        calls.nullRow = null;
+
+        const result = await runGate();
+
+        expect(result.completed).to.be.false;
+        expect(result.reason).to.equal('stale');
+        expect(calls.markReady).to.have.length(0);
+        expect(calls.nullBuildReads).to.have.length(1);
+    });
+
+    it('4. строка этого билда найдена → fallback не выполняется', async () => {
+        calls.buildRow = { build_id: BUILD, scene_content_version: 5, scene_audio_config_version: 5 };
+        calls.nullRow = { build_id: null, scene_content_version: 5, scene_audio_config_version: 5 };
+
+        const result = await runGate();
+
+        expect(result.completed).to.be.true;
+        expect(calls.nullBuildReads).to.have.length(0);
+        expect(calls.markReady).to.have.length(1);
+    });
+
+    it('5. ошибка PG при основном чтении → fail-closed', async () => {
+        const adapter = require('../src/runtime/persistence-port').persistence();
+        adapter.sceneAssets.getAsset = async () => { throw new Error('pg down'); };
+        calls.nullRow = { build_id: null, scene_content_version: 5, scene_audio_config_version: 5 };
+
+        const result = await runGate();
+
+        expect(result.completed).to.be.false;
+        expect(calls.markReady).to.have.length(0);
+    });
+
+    it('6. ошибка PG при fallback-чтении → fail-closed', async () => {
+        calls.buildRow = null;
+        calls.nullRowError = new Error('pg down (null-build read)');
+
+        const result = await runGate();
+
+        expect(result.completed).to.be.false;
+        expect(result.reason).to.equal('stale');
+        expect(calls.markReady).to.have.length(0);
+    });
+});