@animastor/orchestration 0.1.5 → 0.1.7

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);
+    });
+});

package/src/runtime/dispatch-outcomes.js

@@ -1,124 +0,0 @@
-// ======================================================
-// DISPATCH OUTCOMES — the shared taxonomy of "nothing was enqueued"
-//
-// Stage 118 (audit 117 · D3/M4/M5): the classification of an executor
-// outcome lives in ONE module so the dispatch engine (runtime tier) and the
-// stage executors (orchestration tier) cannot drift apart.
-//
-// Buckets
-// ───────
-// • capacity   — the GPU capacity is not there right now:
-//                'no_worker_available' | 'duplicate_pending' | 'ambiguous_post'
-//                ⇒ a BOUNDED retry (deferral window) is the right response.
-//
-// • idempotent — the logical task is ALREADY COMPLETE (the completion marker
-//                exists): 'already_completed'.
-//                This is NOT a capacity problem and MUST NOT be classified as
-//                one (audit 117 · M4): mixing it into the capacity bucket
-//                turned "this task will never run" into an endless retry
-//                loop. It gets its own, much longer backoff window and its
-//                own reporting class.
-//
-// The host side (@animastor/generation → backend/src/helpers/queue-idempotency)
-// mirrors these sets for the transport-level reasons it produces; the two
-// lists must stay in sync (see queue-idempotency.cjs · CAPACITY_REASONS).
-// ======================================================
-
-const CAPACITY_OUTCOMES = new Set([
-    'no_worker_available',   // no live, type-compatible worker
-    'duplicate_pending',     // the job is already pending in the lane
-    'ambiguous_post',        // the POST outcome was ambiguous (the hub may have taken the task)
-    // Stage 129: the intent-fence step could not run (Redis refused the atomic
-    // path / the client cannot run it). Nothing was enqueued and the send IS
-    // retryable, so it belongs to the bounded-retry bucket.
-    'intent_receipt_unavailable',
-]);
-
-const IDEMPOTENT_OUTCOMES = new Set([
-    'already_completed',     // the logical task is already complete (artifact missing)
-]);
-
-/**
- * Fence rejections (Stage 129, audit 128 · F5): the backend refused this
- * dispatch because it belongs to a generation the intent record already
- * superseded, or because the dispatch/intent pair is inconsistent.
- *
- * Retrying the SAME generation can never succeed, so they are NOT retryable —
- * but they must also not fall into the historic "immediate retry on the next
- * tick" bucket, which would turn a stale send into a 5-second dispatch →
- * cancel → rollback loop. They get the long (idempotent) deferral window and
- * stay visible in the logs/metrics.
- */
-const FENCE_REJECTED_OUTCOMES = new Set([
-    'stale_intent',
-    'receipt_conflict',
-    'intent_not_active',
-    'intent_corrupt',
-    'intent_missing',
-]);
-
-/** Is this outcome a CAPACITY gap (bounded retry with a short window)? */
-function isCapacityOutcome(reason) {
-    return CAPACITY_OUTCOMES.has(String(reason || ''));
-}
-
-/** Is this outcome an idempotent suppression (the task is already done)? */
-function isIdempotentOutcome(reason) {
-    return IDEMPOTENT_OUTCOMES.has(String(reason || ''));
-}
-
-/** Is this outcome a fence rejection (terminal for this generation)? */
-function isFenceRejectedOutcome(reason) {
-    return FENCE_REJECTED_OUTCOMES.has(String(reason || ''));
-}
-
-/** Is this outcome deferrable at all (capacity, idempotent OR fence-rejected)? */
-function isDeferrableOutcome(reason) {
-    return isCapacityOutcome(reason) || isIdempotentOutcome(reason) || isFenceRejectedOutcome(reason);
-}
-
-/**
- * Classify the reasons why NOTHING was enqueued for a stage.
- *
- * Stage 118 (audit 117 · M3): the Stage 116 implementation required EXACTLY
- * ONE distinct reason (`notSentReasons.size === 1`). A scene whose units
- * failed for two DIFFERENT deferrable reasons (e.g. one unit gated by
- * "no live worker" and another suppressed as "duplicate pending") was
- * therefore NOT deferred and kept the 5-second dispatch/cancel churn.
- *
- * The rule now: EVERY reason must be deferrable; the most frequent one is
- * reported. A single non-deferrable reason (a real failure) keeps the
- * historic semantics (an immediate retry on the next tick) — the
- * audit-6929ba5 contract depends on it.
- *
- * @param {Map<string, number>|Object<string, number>} reasons
- * @returns {string|null} the dominant deferrable reason, or null.
- */
-function classifyNotSentReasons(reasons) {
-    const entries = reasons instanceof Map
-        ? [...reasons.entries()]
-        : Object.entries(reasons || {});
-    if (entries.length === 0) return null;
-    if (!entries.every(([reason]) => isDeferrableOutcome(reason))) return null;
-    let dominant = null;
-    let dominantCount = -1;
-    for (const [reason, count] of entries) {
-        const n = Number(count) || 0;
-        if (n > dominantCount) {
-            dominant = reason;
-            dominantCount = n;
-        }
-    }
-    return dominant;
-}
-
-module.exports = {
-    CAPACITY_OUTCOMES,
-    IDEMPOTENT_OUTCOMES,
-    FENCE_REJECTED_OUTCOMES,
-    isCapacityOutcome,
-    isIdempotentOutcome,
-    isFenceRejectedOutcome,
-    isDeferrableOutcome,
-    classifyNotSentReasons,
-};