@animastor/orchestration 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@animastor/orchestration",
-    "version": "0.1.4",
+    "version": "0.1.5",
     "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/scene-callbacks.js

@@ -277,9 +277,17 @@ async function handleImageCompleted(redis, bookId, chapterId, sceneId, buildId)
     // T1: возвращает { ok, retryable, reason, artifact }
     log(`IMAGE_CALLBACK: ${bookId}/${chapterId}/${sceneId}`);
 
-    const sceneImage = image.resolveCanonicalSceneImage(
+    // Stage 143a: legacy canonical scan first (unchanged behavior, also the
+    // path every host stub knows), then — flag on and scan empty — the
+    // published pointer of this scene build as the completion proof.
+    let sceneImage = image.resolveCanonicalSceneImage(
         artifactRoot(), buildId, bookId, chapterId, sceneId
     );
+    if (!sceneImage && typeof image.resolveVersionedSceneProof === 'function') {
+        sceneImage = await image.resolveVersionedSceneProof(
+            artifactRoot(), buildId, bookId, chapterId, sceneId
+        );
+    }
 
     // Per-asset check
     const assetStates = await state.getAssetStates(redis, bookId, chapterId, sceneId);
@@ -334,7 +342,28 @@ async function handleImageCompleted(redis, bookId, chapterId, sceneId, buildId)
             const stillPending = [];
             for (const uid of dirtyIds) {
                 const pngPath = path.join(buildDir, artifactNaming.sceneImageName(bookId, chapterId, sceneId, uid));
-                if (!fs.existsSync(pngPath)) {
+                if (fs.existsSync(pngPath)) continue;
+                // ── Stage 143a (phase 2a · N1) ─────────────────────
+                // A versioned-only build never writes the canonical file, so
+                // the published pointer is the completion proof for this
+                // unit. Without it the dirty marker is never cleared and the
+                // unit is force-regenerated on EVERY reconcile pass (infinite
+                // regeneration loop with the flag on).
+                // Flag OFF ⇒ the facade answers null with zero PG calls → the
+                // legacy check above decides, exactly as before.
+                // A pointer-store ERROR keeps the unit pending (never cleared
+                // on an unknown verdict) and is logged.
+                let provenByPointer = false;
+                try {
+                    if (image && typeof image.resolveIuImagePath === 'function') {
+                        const published = await image.resolveIuImagePath(
+                            artifactRoot(), buildId, bookId, chapterId, sceneId, uid);
+                        provenByPointer = !!(published && published.status === 'ok');
+                    }
+                } catch (pgErr) {
+                    warn(`[DIRTY-UNITS] pointer proof unavailable for ${uid}: ${pgErr.message} — keeping it pending`);
+                }
+                if (!provenByPointer) {
                     stillPending.push(uid);
                 }
             }
@@ -343,8 +372,31 @@ async function handleImageCompleted(redis, bookId, chapterId, sceneId, buildId)
                 log(`[DIRTY-UNITS-CLEARED] ${bookId}/${chapterId}/${sceneId}: all ${dirtyIds.length} dirty unit(s) completed, cleared`);
                 try {
                     const iuPrefix = artifactNaming.iuImagePrefix(bookId, chapterId, sceneId);
+                    const scenePrefix = artifactNaming.scenePrefix(bookId, chapterId, sceneId);
                     const allFiles = fs.existsSync(buildDir) ? fs.readdirSync(buildDir) : [];
-                    const iuFileCount = allFiles.filter(f => f.startsWith(iuPrefix) && f.endsWith('.png')).length;
+                    // ── Stage 143a (phase 2a · N2) ─────────────────
+                    // Ready units = canonical file names ∪ published pointer
+                    // ids (versioned files are invisible to this scan). The
+                    // counter is a DISPLAY source (consumers clamp it), so a
+                    // pointer-store error here only logs and leaves the
+                    // legacy count — never a readiness decision.
+                    const readyIds = new Set();
+                    for (const f of allFiles) {
+                        if (f.startsWith(iuPrefix) && f.endsWith('.png')) {
+                            readyIds.add(f.startsWith(`${scenePrefix}_`)
+                                ? f.slice(scenePrefix.length + 1, -4)
+                                : f);
+                        }
+                    }
+                    if (image && typeof image.listPublishedIuIdsForScene === 'function') {
+                        try {
+                            const publishedIds = await image.listPublishedIuIdsForScene(buildId, bookId, chapterId, sceneId);
+                            for (const id of publishedIds) readyIds.add(String(id));
+                        } catch (pgErr) {
+                            warn(`[IU-COUNTER-RESET] published ids unavailable for ${bookId}/${chapterId}/${sceneId}: ${pgErr.message} — counting canonical files only`);
+                        }
+                    }
+                    const iuFileCount = readyIds.size;
                     if (iuFileCount > 0) {
                         const progKey = `animastor:iu-progress:${bookId}:${chapterId}:${sceneId}:image`;
                         await redis.set(progKey, String(iuFileCount), 'EX', 14400);

package/src/orchestration/scene-orchestrator.js

@@ -13,10 +13,15 @@ const chunks = lazyHostBinding('media.audio.chunks');
 // orchestrator never requires gpu-dispatcher or the workflow connector.
 const provider = require('@animastor/generation').comfyuiProvider;
 const runtimeScheduler = require('../runtime/runtime-scheduler');
+// Stage 118 (M3): the shared outcome taxonomy — the dispatch engine (runtime
+// tier) and the stage executors (orchestration tier) must classify a
+// "nothing was enqueued" outcome IDENTICALLY.
+const { classifyNotSentReasons } = require('../runtime/dispatch-outcomes');
 // O-2: persistence arrives ONLY through the PersistencePort (host adapter:
 // storage/runtime-persistence-adapter) — the scene-assets repository left
 // this file. SQL lives host-side.
 const persist = require('../runtime/persistence-port').persist;
+const isPersistencePortWired = require('../runtime/persistence-port').isPersistencePortWired;
 // O-3: scene content arrives ONLY through the SceneDataPort (host adapter:
 // storage/scene-data-adapter) — the Book Model facade (../book →
 // @animastor/vbook-runtime) left this file. Aliased `sceneDataPort` because
@@ -300,8 +305,22 @@ async function executeAudioDispatch(redis, scene, loadedBook, buildId, dispatchI
         const completion = await completeStage(redis, bookId, chapterId, sceneId, 'audio', buildId, dispatchId);
         return { dispatched: false, jobs: 0, completed: completion.completed, reason: 'no_segments' };
     } else {
-        warn(`AUDIO_DISPATCH: generateSceneAudio did not send jobs for ${bookId}/${chapterId}/${sceneId}`);
-        return { dispatched: false, jobs: 0, reason: 'no_jobs_generated' };
+        // Stage 116 (D3) / Stage 118 (B3, M3): nothing was enqueued — carry
+        // the precise reason (no live worker / everything already queued /
+        // ambiguous POST) so the dispatch engine can apply a BOUNDED deferral
+        // instead of a fatal cancel.
+        //
+        // Stage 118 (B3): the merged (pure-dialogue) path and the per-segment
+        // path must produce the SAME classification — the merged branch used
+        // to leave the reason empty, so a pure-dialogue scene kept the
+        // 5-second retry loop. `deferReason` is computed by the host (audio
+        // generation) for EVERY path; the fallback below keeps the historic
+        // 'no_jobs_generated' semantics when the host could not classify it.
+        const deferReason = (result && result.reason === 'no_jobs_accepted' && result.deferReason)
+            ? result.deferReason
+            : 'no_jobs_generated';
+        warn(`AUDIO_DISPATCH: generateSceneAudio did not send jobs for ${bookId}/${chapterId}/${sceneId} (${deferReason})`);
+        return { dispatched: false, jobs: 0, reason: deferReason, retryable: true };
     }
 }
 
@@ -352,8 +371,11 @@ async function executeImageDispatch(redis, scene, loadedBook, buildId, dispatchI
 
     // T3: generateSceneIUImages возвращает количество отправленных jobs
     let jobsSent = 0;
+    // Stage 116 (D3): the result is needed AFTER the try/catch (the deferral
+    // reason) — it must be visible outside the block.
+    let genResult = null;
     try {
-        const genResult = await image.generateSceneIUImages(
+        genResult = await image.generateSceneIUImages(
             redis,
             sceneData,
             bookData,
@@ -377,6 +399,16 @@ async function executeImageDispatch(redis, scene, loadedBook, buildId, dispatchI
         return { dispatched: true, jobs: jobsSent, reason: null };
     }
 
+    // Stage 116 (D3) / Stage 118 (M3): the executor sent NOTHING. That is
+    // not a lost task and not a fatal cancellation — it is a bounded
+    // deferral. The precise reason (no live worker / everything already
+    // queued / ambiguous POST) is carried through so the deferral can be
+    // classified by the shared taxonomy (runtime/dispatch-outcomes).
+    if (genResult && genResult.deferReason) {
+        warn(`IMAGE_DISPATCH: ${bookId}/${chapterId}/${sceneId} — nothing enqueued (${genResult.deferReason}); deferring`);
+        return { dispatched: false, jobs: 0, reason: genResult.deferReason, retryable: true };
+    }
+
     log(`IMAGE_DISPATCH: ${bookId}/${chapterId}/${sceneId} — no jobs sent (cache hit or empty units)`);
     return { dispatched: false, jobs: 0, reason: 'no_jobs_sent' };
 }
@@ -551,15 +583,41 @@ async function executeVideoDispatch(redis, scene, loadedBook, buildId, dispatchI
     await videoOrch.setWaitingChunks(redis, bookId, chapterId, sceneId);
 
     let sentCount = 0;
+    // Stage 116 (D3) / Stage 118 (M3): collect WHY a job was not sent — the
+    // dominant reason becomes the deferral reason (bounded backoff) instead
+    // of the generic 'send_failed'.
+    const notSentReasons = new Map();
     for (const jobSpec of jobsToSend) {
         try {
-            const sendResult = await provider.generate(jobSpec);
+            let sendResult = await provider.generate(jobSpec);
+            // Stage 122 (N2): the group file was probed absent above (a cached
+            // group never reaches this loop), so an `already_completed` verdict
+            // is by construction an ORPHANED completion marker. Free it and
+            // retry ONCE so the video regenerates instead of looping on a
+            // 900 s deferral with the scene stuck in the active index (audit
+            // 121 · N2). The release rides the persistence port — the
+            // orchestration tier cannot require the backend helper directly.
+            // Skipped when the port is unwired (harnesses that don't exercise
+            // orphan cleanup); production always wires it in backend.cjs.
+            if (isPersistencePortWired()) {
+                let released = false;
+                try {
+                    released = await persist('idem.releaseTaskDoneIfOrphan')(redis, sendResult);
+                } catch (_) { released = false; }
+                if (released) {
+                    log(`VIDEO_DISPATCH: orphaned completion marker released for ${jobSpec.job_id} — regenerating`);
+                    sendResult = await provider.generate(jobSpec);
+                }
+            }
             if (sendResult.sent) {
                 sentCount++;
             } else {
-                warn(`VIDEO_DISPATCH: Hub rejected job ${jobSpec.job_id}: ${sendResult.error || 'unknown'}`);
+                const reason = sendResult.reason || 'send_failed';
+                notSentReasons.set(reason, (notSentReasons.get(reason) || 0) + 1);
+                warn(`VIDEO_DISPATCH: Hub rejected job ${jobSpec.job_id}: ${sendResult.error || reason}`);
             }
         } catch (sendErr) {
+            notSentReasons.set('send_failed', (notSentReasons.get('send_failed') || 0) + 1);
             warn(`VIDEO_DISPATCH: provider generate failed for job ${jobSpec.job_id}: ${sendErr.message}`);
         }
     }
@@ -569,8 +627,13 @@ async function executeVideoDispatch(redis, scene, loadedBook, buildId, dispatchI
         return { dispatched: true, jobs: sentCount, reason: null };
     }
 
-    warn(`VIDEO_DISPATCH: ${bookId}/${chapterId}/${sceneId}: all provider.generate calls failed`);
-    return { dispatched: false, jobs: 0, reason: 'send_failed' };
+    // Stage 116 (D3) / Stage 118 (M3): the shared taxonomy decides whether
+    // the outcome is a bounded deferral. EVERY reason must be deferrable —
+    // a single real failure (send_failed) keeps the historic 'send_failed'
+    // semantics (an immediate retry on the next tick).
+    const deferReason = classifyNotSentReasons(notSentReasons) || 'send_failed';
+    warn(`VIDEO_DISPATCH: ${bookId}/${chapterId}/${sceneId}: nothing enqueued (${deferReason})`);
+    return { dispatched: false, jobs: 0, reason: deferReason, retryable: true };
 }
 
 // T4: dispatchStage принимает dispatchId (из dispatch-engine) и передаёт executors

package/src/runtime/dispatch-engine.js

@@ -730,10 +730,194 @@ async function shouldSkipDispatch(redis, bookId, chapterId, sceneId, stage) {
  * - { dispatched: true, dispatchId, stage, leaseKey }
  * - { dispatched: false, reason, skip: true/false }
  */
+// ======================================================
+// STAGE 116 (D3) — BOUNDED DEFERRAL (capacity backoff)
+// STAGE 118 (audit 117 · M2/M4) — taxonomy + force handling
+// ======================================================
+// The scheduler ticks every SCHEDULER_TICK_MS (5 s). A stage whose jobs could
+// not be enqueued (no live compatible worker, or every job already pending in
+// the lane) used to be re-dispatched on EVERY tick: lease created → executor
+// sent nothing → 'no_jobs_sent' → dispatch cancelled → FSM rolled back →
+// next tick repeats. That is an unbounded dispatch/cancel loop with FSM
+// churn, lease churn and unbounded event-journal growth (Stage 115 D3).
+//
+// The deferral is a bounded, per-stage backoff:
+//   • checked BEFORE any side effect (no lease, no metadata, no FSM write,
+//     no journal event) ⇒ a deferred stage costs one Redis GET per tick;
+//   • the stage stays PENDING and stays in the active index ⇒ recoverable;
+//   • an explicit cancel clears it (the user asked for the work to run).
+//
+// Stage 118 — three corrections of the Stage 116 implementation:
+//
+// 1. The reason taxonomy now distinguishes CAPACITY from IDEMPOTENT
+//    suppression ('already_completed' is NOT a capacity gap — audit 117 · M4).
+//    The idempotent bucket gets its own, much longer window: the stage is not
+//    "waiting for capacity", it is "already done" — retrying it every minute
+//    for a week is not a fix.
+// 2. `force=true` NO LONGER BYPASSES the deferral (audit 117 · M2). The
+//    force-dispatch flag lives for FORCE_DISPATCH_TTL_S (120 s) and is set for
+//    the WHOLE book by /regenerate, so bypassing the backoff there restored
+//    the very dispatch/cancel churn D3 was built to remove (≈24 full attempts
+//    per scene per regeneration). The explicit intent (a regeneration, a
+//    cancel) clears the deferral at ITS call site — the backoff then applies
+//    again after the next capacity failure.
+// 3. The deferral key encodes its components (audit 117 · M1): a book_id may
+//    contain ':' (the bundle book_id is client-controlled), so a raw
+//    ':'-joined key is ambiguous — `a:b` + chapter `c` collides with book
+//    `a` + chapter `b`.
+const DEFERRED_STAGE_KEY_PREFIX = 'animastor:runtime:deferred:';
+const DEFERRED_STAGE_TTL_S = 60;        // capacity backoff window (bounded retry)
+const DEFERRED_IDEMPOTENT_TTL_S = 900;  // idempotent-suppression window (15 min)
+
+/**
+ * Executor outcomes that mean "nothing could be enqueued — retry later".
+ *
+ * The taxonomy lives in ./dispatch-outcomes (shared with the stage
+ * executors). The generic 'no_jobs_sent' / 'no_jobs_generated' /
+ * 'send_failed' outcomes keep their historic contract (retry on the next
+ * tick — the audit-6929ba5 regression tests rely on it): deferring them
+ * would change the meaning of an executor result that does not necessarily
+ * mean "no capacity".
+ */
+const {
+    CAPACITY_OUTCOMES,
+    IDEMPOTENT_OUTCOMES,
+    FENCE_REJECTED_OUTCOMES,
+    isCapacityOutcome,
+    isIdempotentOutcome,
+    isFenceRejectedOutcome,
+    isDeferrableOutcome,
+} = require('./dispatch-outcomes');
+
+/**
+ * Encode one key component so that ':' (and the glob metacharacters) can
+ * never be mistaken for the separator. encodeURIComponent escapes ':' as
+ * '%3A' and leaves '_' readable.
+ */
+function encodeKeyComponent(value) {
+    return encodeURIComponent(String(value == null ? '' : value));
+}
+
+function deferredStageKey(bookId, chapterId, sceneId, stage) {
+    return `${DEFERRED_STAGE_KEY_PREFIX}`
+        + `${encodeKeyComponent(bookId)}:${encodeKeyComponent(chapterId)}`
+        + `:${encodeKeyComponent(sceneId)}:${encodeKeyComponent(stage)}`;
+}
+
+/** Is this stage currently deferred (backoff active)? */
+async function isStageDeferred(redis, bookId, chapterId, sceneId, stage) {
+    try {
+        const value = await redis.get(deferredStageKey(bookId, chapterId, sceneId, stage));
+        return value != null;
+    } catch (_) {
+        return false;
+    }
+}
+
+/**
+ * Defer a stage for the bounded backoff window.
+ * @param {number} [ttlSeconds] — the capacity window by default; the
+ *        idempotent window for an 'already_completed' suppression.
+ */
+async function deferStage(redis, bookId, chapterId, sceneId, stage, ttlSeconds = DEFERRED_STAGE_TTL_S) {
+    try {
+        await redis.set(deferredStageKey(bookId, chapterId, sceneId, stage), '1', 'EX', ttlSeconds);
+    } catch (_) { /* best effort — a missed deferral only costs one extra attempt */ }
+}
+
+/** Clear the deferral (the stage dispatched, completed or was cancelled). */
+async function clearStageDeferral(redis, bookId, chapterId, sceneId, stage) {
+    try {
+        await redis.del(deferredStageKey(bookId, chapterId, sceneId, stage));
+    } catch (_) { /* best effort */ }
+}
+
+/**
+ * Clear the capacity backoff of EVERY stage of a book.
+ *
+ * Stage 118 (audit 117 · M2/B4): the explicit intents — a cancel, a cache
+ * teardown, a deletion — ask for the work to run again, so the backoff must
+ * not survive them. The deferral key is owned by this package, so the
+ * package clears it (the host only injects the port).
+ *
+ * @returns {Promise<number>} the number of cleared deferrals.
+ */
+async function clearDeferralsForBook(redis, bookId) {
+    if (!redis || !bookId) return 0;
+    return clearDeferralsByPrefix(redis, `${DEFERRED_STAGE_KEY_PREFIX}${encodeKeyComponent(bookId)}:`);
+}
+
+/**
+ * Clear the capacity backoff of every stage of one scene (an explicit
+ * regeneration of that scene).
+ */
+async function clearDeferralsForScene(redis, bookId, chapterId, sceneId) {
+    if (!redis || !bookId || !chapterId || !sceneId) return 0;
+    return clearDeferralsByPrefix(redis, `${DEFERRED_STAGE_KEY_PREFIX}`
+        + `${encodeKeyComponent(bookId)}:${encodeKeyComponent(chapterId)}:${encodeKeyComponent(sceneId)}:`);
+}
+
+async function clearDeferralsByPrefix(redis, prefix) {
+    let cleared = 0;
+    if (!redis || !prefix) return cleared;
+    let cursor = '0';
+    try {
+        do {
+            const [next, keys] = await redis.scan(cursor, 'MATCH', `${prefix}*`, 'COUNT', 200);
+            cursor = next;
+            for (const key of keys || []) {
+                if (!key.startsWith(prefix)) continue;
+                await redis.del(key);
+                cleared++;
+            }
+        } while (cursor !== '0');
+    } catch (_) { /* best effort */ }
+    return cleared;
+}
+
+/**
+ * The backoff window that fits the outcome: a capacity gap retries in
+ * minutes, an idempotent suppression (already complete) in quarters of an
+ * hour — it is not waiting for capacity, it is simply done.
+ */
+function deferralWindowFor(reason) {
+    // Stage 129 (audit 128 · F5): a fence rejection is terminal for THIS
+    // generation — retrying it immediately would only recreate the
+    // dispatch → cancel → rollback churn. It shares the long window with the
+    // idempotent suppressions and stays visible through the log/metric.
+    return (isIdempotentOutcome(reason) || isFenceRejectedOutcome(reason))
+        ? DEFERRED_IDEMPOTENT_TTL_S
+        : DEFERRED_STAGE_TTL_S;
+}
+
 async function dispatchStage(redis, bookId, chapterId, sceneId, stage, loadedBook, buildId, options = {}) {
     const { force = false } = options;
     const dispatchId = generateDispatchToken();
 
+    // ─────────────────────────────────────────────────────────────────────
+    // Stage 116 (D3) / Stage 118 (M2) — BOUNDED DEFERRAL (retry/backoff)
+    // ─────────────────────────────────────────────────────────────────────
+    // A stage that could not enqueue anything (no live compatible worker, or
+    // every job already pending in the lane) must NOT be retried on every
+    // scheduler tick: the tick is 5 s, so the un-deferred path produced an
+    // endless dispatch → cancel → FSM-rollback cycle (lease churn, FSM churn
+    // and UNBOUNDED event-journal growth).
+    //
+    // The deferral is checked BEFORE any side effect (no lease, no dispatch
+    // metadata, no FSM write, no journal event) ⇒ a deferred stage costs one
+    // Redis GET per tick. The stage stays PENDING and stays in the active
+    // index ⇒ it is recoverable: as soon as the deferral window expires (or a
+    // worker appears) the next tick dispatches it again.
+    //
+    // Stage 118 (M2): the check applies in FORCE mode as well. The
+    // force-dispatch flag is per BOOK and lives for 120 s, so bypassing the
+    // backoff there reproduced the very churn D3 removes (≈24 full attempts
+    // per scene per /regenerate). An EXPLICIT intent (a regeneration, a
+    // cancel) clears the deferral at its own call site.
+    if (await isStageDeferred(redis, bookId, chapterId, sceneId, stage)) {
+        return { dispatched: false, reason: 'deferred_capacity', retryable: true, deferred: true, dispatchId };
+    }
+
     log(`DISPATCH_REQUEST: ${bookId}/${chapterId}/${sceneId}:${stage}${force ? ' (force=true)' : ''}`);
 
     // Force mode pre-clear: cancel existing dispatch, release quota ТОЛЬКО при наличии lease
@@ -908,6 +1092,18 @@ async function dispatchStage(redis, bookId, chapterId, sceneId, stage, loadedBoo
             if (!result.dispatched) {
                 log(`DISPATCH_SKIPPED: ${bookId}/${chapterId}/${sceneId}:${stage} - ${result.reason || 'already_done'}`);
                 if (!result.completed) {
+                    // Stage 116 (D3): a stage that enqueued NOTHING is not a
+                    // lost task and not a fatal cancellation — it is a bounded
+                    // deferral. Remember it for a bounded window so the
+                    // scheduler's 5 s tick does not spin.
+                    //
+                    // Stage 118 (M4): the window depends on the bucket — a
+                    // capacity gap retries within a minute, an idempotent
+                    // suppression ('already_completed') is NOT waiting for
+                    // capacity and gets the long window.
+                    if (isDeferrableOutcome(result.reason)) {
+                        await deferStage(redis, bookId, chapterId, sceneId, stage, deferralWindowFor(result.reason));
+                    }
                     await finalizeDispatch(redis, bookId, chapterId, sceneId, stage, {
                         outcome: 'cancelled',
                         dispatchId,
@@ -918,13 +1114,29 @@ async function dispatchStage(redis, bookId, chapterId, sceneId, stage, loadedBoo
                     if (result.rollbackFailed) {
                         error(`STATE_ROLLBACK_FAILED: ${bookId}/${chapterId}/${sceneId}:${stage}: ${result.rollbackReason || 'unknown'} — stage may be stuck in GENERATING`);
                     }
+                } else {
+                    // The stage completed (cache hit / already done) — it is no
+                    // longer waiting for capacity.
+                    await clearStageDeferral(redis, bookId, chapterId, sceneId, stage);
                 }
                 // Cancelled finalize does not touch the circuit breaker — release
                 // the test permit here so a half-open circuit can keep recovering.
                 await releaseTestPermit();
-                return { dispatched: false, dispatchId, reason: result.reason || 'already_done', result };
+                return {
+                    dispatched: false,
+                    dispatchId,
+                    reason: result.reason || 'already_done',
+                    retryable: isDeferrableOutcome(result.reason),
+                    // Stage 118 (M9): the caller (scheduler) must be able to
+                    // tell "nothing happened, try later" from a real error.
+                    deferred: isDeferrableOutcome(result.reason),
+                    result,
+                };
             }
 
+            // The stage really dispatched — capacity deferral is over.
+            await clearStageDeferral(redis, bookId, chapterId, sceneId, stage);
+
             // T6: Start lease renewal for this actively dispatched job
             // Only started after confirming dispatcher returned dispatched:true
             // (not for cache hits, backpressure, or empty executor results)
@@ -1296,6 +1508,9 @@ async function markDispatchFailed(redis, bookId, chapterId, sceneId, stage, erro
  * T6: Останавливает in-memory renewal timer, чтобы избежать утечки.
  */
 async function cancelActiveDispatch(redis, bookId, chapterId, sceneId, stage, reason = 'cancelled') {
+    // Stage 116 (D3): an explicit cancel means the work is wanted again — a
+    // capacity deferral must not survive it.
+    await clearStageDeferral(redis, bookId, chapterId, sceneId, stage);
     const metadata = await getDispatchMetadata(redis, bookId, chapterId, sceneId, stage);
     if (metadata?.dispatch_id) {
         const result = await finalizeDispatch(redis, bookId, chapterId, sceneId, stage, {
@@ -1383,9 +1598,33 @@ async function clearLeasesForScenes(redis, bookId, scenes) {
 }
 
 /**
- * Remove specific cancelled dispatches from GPU Hub.
+ * Remove cancelled dispatches from GPU Hub.
  * Kept here with dispatch cancellation so every caller uses the same auth and
  * error-handling contract.
+ *
+ * Stage 122 (N1): the hub's `DELETE /queue/clear` accepts EITHER a
+ * `dispatch_id` (per-job) OR a `book_id` (whole-book lane sweep). Before this
+ * stage the function only honoured the per-id form; a caller that passed an
+ * EMPTY id list together with `book_id` (the regenerate post-release sweep,
+ * audit 121 · N1) fell straight through the id loop and issued ZERO requests —
+ * a silent NO-OP that left orphan lane entries behind while looking like a
+ * successful sweep.
+ *
+ * The contract now is:
+ *   - ids present        → one `?dispatch_id=` DELETE per id (unchanged);
+ *   - no ids + book_id   → exactly ONE `?book_id=` DELETE (the whole-book sweep
+ *                          the hub already supports and cache/delete paths use);
+ *   - neither            → NO request at all (never a fake HTTP call).
+ *
+ * A book-scoped sweep is checked against the hub's echoed `scope.book_id`:
+ * if the hub answers `ok` but echoes a DIFFERENT scope (or none at all while
+ * reporting a full wipe) it did not honour our ownership and other books may
+ * have been touched — that is counted as `failed` and warned, never as a
+ * success. Failures never throw (best-effort contract, callers keep claims).
+ *
+ * @returns {Promise<{requested:number, cleared:number, failed:number}>}
+ *   `requested` = number of hub requests actually attempted (1 for a
+ *   book-scoped sweep, ids.length for per-id, 0 when there is nothing to do).
  */
 async function clearHubDispatches(dispatchIds, options = {}) {
     const ids = [...new Set((dispatchIds || []).filter(Boolean))];
@@ -1396,16 +1635,59 @@ async function clearHubDispatches(dispatchIds, options = {}) {
     const context = options.context || 'DISPATCH';
     const reportWarning = typeof options.warn === 'function' ? options.warn : warn;
     const fetchImpl = options.fetchImpl || globalThis.fetch;
+    const bookId = options.book_id || options.bookId || null;
     let cleared = 0;
     let failed = 0;
 
+    const authHeaders = () => {
+        const headers = {};
+        if (apiKey) headers['x-api-key'] = apiKey;
+        return headers;
+    };
+
+    // ── Book-scoped sweep (no explicit dispatch ids) ──────────────────────
+    // Exactly one request; the hub filters by record.book_id so only this
+    // book's queue/running/result entries are removed.
+    if (ids.length === 0 && bookId) {
+        try {
+            const response = await fetchImpl(
+                `${hubUrl}/queue/clear?book_id=${encodeURIComponent(bookId)}`,
+                { method: 'DELETE', headers: authHeaders() }
+            );
+            if (!response.ok) {
+                failed++;
+                reportWarning(`${context}: GPU hub book cleanup returned ${response.status} for ${bookId}`);
+            } else {
+                // Verify the hub honoured OUR scope. A mismatched echo means it
+                // may have swept a different book (or everything) — that is a
+                // failure, not a success we can report.
+                let enforcedScope = true;
+                try {
+                    const body = typeof response.json === 'function' ? await response.json() : null;
+                    if (body && body.scope && body.scope.book_id != null && body.scope.book_id !== bookId) {
+                        enforcedScope = false;
+                    }
+                } catch (_) { /* unparseable body — trust the ok status */ }
+                if (!enforcedScope) {
+                    failed++;
+                    reportWarning(`${context}: GPU hub book cleanup echoed a foreign scope for ${bookId} — treated as failed`);
+                } else {
+                    cleared++;
+                }
+            }
+        } catch (err) {
+            failed++;
+            reportWarning(`${context}: GPU hub book cleanup failed for ${bookId}: ${err.message}`);
+        }
+        return { requested: 1, cleared, failed };
+    }
+
+    // ── Per-dispatch cleanup (unchanged) ─────────────────────────────────
     for (const dispatchId of ids) {
         try {
-            const headers = {};
-            if (apiKey) headers['x-api-key'] = apiKey;
             const response = await fetchImpl(
                 `${hubUrl}/queue/clear?dispatch_id=${encodeURIComponent(dispatchId)}`,
-                { method: 'DELETE', headers }
+                { method: 'DELETE', headers: authHeaders() }
             );
             if (!response.ok) {
                 failed++;
@@ -1781,6 +2063,29 @@ module.exports = {
     LEASE_TTLS,
     QUOTAS,
 
+    // Stage 116 (D3) / Stage 118 (M2/M4): bounded deferral (retry/backoff) —
+    // the stage is not retried on every 5 s scheduler tick while it cannot
+    // enqueue. Stage 118: the capacity and the idempotent bucket have their
+    // own windows, and the taxonomy is shared with the stage executors.
+    DEFERRED_STAGE_KEY_PREFIX,
+    DEFERRED_STAGE_TTL_S,
+    DEFERRED_IDEMPOTENT_TTL_S,
+    deferredStageKey,
+    isStageDeferred,
+    deferStage,
+    clearStageDeferral,
+    clearDeferralsForBook,
+    clearDeferralsForScene,
+    deferralWindowFor,
+    encodeKeyComponent,
+    isDeferrableOutcome,
+    isCapacityOutcome,
+    isIdempotentOutcome,
+    isFenceRejectedOutcome,
+    CAPACITY_OUTCOMES,
+    IDEMPOTENT_OUTCOMES,
+    FENCE_REJECTED_OUTCOMES,
+
     // PW-2: dispatch identity generation (crypto-hardened)
     generateDispatchToken
 };

package/src/runtime/dispatch-outcomes.js

@@ -0,0 +1,124 @@
+// ======================================================
+// 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,
+};

package/src/runtime/hub-cancel-port.js

@@ -30,6 +30,12 @@
 //                        a cancelled dispatch still owns on the GPU Hub
 //                        (orchestrator resetScenes cancel leg,
 //                        reconciliation RELEASE_STALE_LEASE recovery leg).
+//                        Accepts EITHER an array of dispatch ids (one
+//                        `?dispatch_id=` DELETE per id) OR an empty list with
+//                        `options.book_id` (Stage 122 · N1 — a single
+//                        book-scoped `?book_id=` sweep, used by the
+//                        regenerate post-release lane sweep; audit 121 found
+//                        the empty-list + book_id form was a silent no-op).
 //                        Returns { requested, cleared, failed }; hub
 //                        unavailability is non-fatal per-id (warn + count),
 //                        never throws for a single failed id.

package/src/runtime/persistence-port.js

@@ -82,6 +82,12 @@ const OPS = [
     'registry.registerSceneImageRedis',
     'registry.registerSceneVideoRedis',
 
+    // Stage 122 (N2 · audit 121): the video send path frees an ORPHANED
+    // completion marker through this op (Redis-domain, `redis`-first like the
+    // registry.*Redis ops) — the orchestration tier cannot require the backend
+    // queue-idempotency helper directly.
+    'idem.releaseTaskDoneIfOrphan',
+
     'filesystem.getSceneAudioPath',
 
     'listBooks',

package/src/runtime/reconciliation-engine.js

@@ -157,7 +157,7 @@ async function checkOrphanImageState(redis, bookId, chapterId, sceneId) {
     // Orphan-check uses the canonical book build identity (audit d9d67a3).
     const buildId = resolveBookBuildId(bookId);
     const imageModule = lazyHostBinding('media.image');
-    const imageInfo = imageModule.resolveCanonicalSceneImage(
+    let imageInfo = imageModule.resolveCanonicalSceneImage(
         artifactRoot(),
         buildId,
         bookId,
@@ -165,6 +165,31 @@ async function checkOrphanImageState(redis, bookId, chapterId, sceneId) {
         sceneId,
     );
 
+    // ── Stage 143a (phase 2a · B2) ───────────────────────────────────
+    // Legacy scan first (byte-identical legacy behavior). A versioned-only
+    // build never writes the canonical file, so with the scan empty we ask
+    // the image facade for the published pointer of this scene build — the
+    // facade is flag-gated, flag OFF answers null with ZERO PG calls.
+    //
+    // An UNREADABLE pointer store ABORTS this reconcile pass (logged,
+    // `pass_incomplete`) instead of being read as "no publication": that
+    // reading would recommend regenerating a scene that is already
+    // published. No orphan issue is emitted on the aborted pass, so no
+    // regeneration is launched.
+    if (!imageInfo) {
+        try {
+            if (typeof imageModule.resolveVersionedSceneProof === 'function') {
+                imageInfo = await imageModule.resolveVersionedSceneProof(
+                    artifactRoot(), buildId, bookId, chapterId, sceneId);
+            }
+        } catch (pgErr) {
+            error(`versioned image proof unavailable for ${bookId}/${chapterId}/${sceneId}: ${pgErr.message} — pass skipped, no regeneration launched`);
+            const err = new Error(`reconcile_pass_incomplete: image proof unavailable for ${bookId}/${chapterId}/${sceneId} (${pgErr.message})`);
+            err.code = 'pass_incomplete';
+            throw err;
+        }
+    }
+
     if (!imageInfo) {
         return {
             type: 'orphan_image_state',
@@ -251,11 +276,37 @@ async function checkOrphanAssets(redis, bookId, chapterId, sceneId) {
         try {
             await fs.access(assets.image.path);
         } catch (err) {
-            orphanAssets.push({
-                type: 'missing_image_file',
-                scene: { bookId, chapterId, sceneId },
-                path: assets.image.path
-            });
+            // ── Stage 143a (phase 2a · B2) ───────────────────────────
+            // With the flag ON a published pointer is the authority: a LIVE
+            // versioned file for this scene build explains the missing
+            // canonical file (versioned-only build) → no issue is emitted.
+            // Flag OFF ⇒ the facade answers null with ZERO PG calls and the
+            // legacy issue is reported exactly as before.
+            // An UNREADABLE pointer store aborts the pass (logged) instead of
+            // emitting a regeneration recommendation on a guess.
+            let coveredByPointer = false;
+            const imageModule = lazyHostBinding('media.image');
+            try {
+                if (typeof imageModule.resolveVersionedSceneProof === 'function') {
+                    const buildId = resolveBookBuildId(bookId);
+                    coveredByPointer = !!(await imageModule.resolveVersionedSceneProof(
+                        artifactRoot(), buildId, bookId, chapterId, sceneId));
+                }
+            } catch (pgErr) {
+                error(`versioned image proof unavailable for ${bookId}/${chapterId}/${sceneId}: ${pgErr.message} — pass skipped, no recommendation emitted`);
+                const e = new Error(`reconcile_pass_incomplete: image proof unavailable for ${bookId}/${chapterId}/${sceneId} (${pgErr.message})`);
+                e.code = 'pass_incomplete';
+                throw e;
+            }
+            if (coveredByPointer) {
+                log(`missing_image_file suppressed: ${bookId}/${chapterId}/${sceneId} is covered by a published versioned pointer`);
+            } else {
+                orphanAssets.push({
+                    type: 'missing_image_file',
+                    scene: { bookId, chapterId, sceneId },
+                    path: assets.image.path
+                });
+            }
         }
     }
 

package/src/runtime/runtime-scheduler.js

@@ -388,6 +388,7 @@ async function tick(redis, loadedBooks = {}) {
             throttled: 0,
             skipped: 0,
             completed: 0,
+            deferred: 0,
             errors: []
         };
 
@@ -466,6 +467,10 @@ async function tick(redis, loadedBooks = {}) {
                     summary.skipped++;
                 } else if (result.throttled > 0) {
                     summary.throttled += result.throttled;
+                } else if (result.deferred > 0) {
+                    // Stage 118 (M9): a bounded deferral is a normal, quiet
+                    // state — it must not pollute the tick error list.
+                    summary.deferred += result.deferred;
                 } else if (result.reason === 'backpressure' || result.reason === 'throttled') {
                     summary.throttled++;
                 } else if (result.success) {
@@ -480,7 +485,7 @@ async function tick(redis, loadedBooks = {}) {
         }
 
         log(`=== TICK COMPLETE ===`);
-        log(`Active: ${summary.totalActive}, Dispatched: ${summary.dispatched}, Skipped: ${summary.skipped}, Throttled: ${summary.throttled}, Completed: ${summary.completed}`);
+        log(`Active: ${summary.totalActive}, Dispatched: ${summary.dispatched}, Skipped: ${summary.skipped}, Throttled: ${summary.throttled}, Completed: ${summary.completed}, Deferred: ${summary.deferred}`);
 
         if (summary.errors.length > 0) {
             log(`Errors: ${summary.errors.length}`);
@@ -572,6 +577,9 @@ async function attemptDispatch(redis, bookId, chapterId, sceneId, loadedBook, fo
     let dispatched = 0;
     let throttled = 0;
     let anyCompleted = false;
+    // Stage 118 (M9): bounded deferrals are counted separately — they are
+    // neither a dispatch nor an error.
+    let deferred = 0;
     const failures = [];
 
     // Dispatch ALL eligible stages in this tick.
@@ -595,6 +603,12 @@ async function attemptDispatch(redis, bookId, chapterId, sceneId, loadedBook, fo
             // Stage finished inside the executor (already_done / cache_hit /
             // no_segments) — not a failure, nothing to dispatch.
             anyCompleted = true;
+        } else if (result.deferred) {
+            // Stage 118 (M9): a bounded deferral is NOT an error — nothing
+            // happened, the stage is waiting for capacity (or is already
+            // idempotently complete). Reporting it as a failure filled the
+            // tick summary with "errors" 12 times per minute per scene.
+            deferred++;
         } else {
             // Stage 50: раньше per-stage отказ (circuit_open, retry budget,
             // lease, generating_transition_failed, …) молча проглатывался и
@@ -607,6 +621,9 @@ async function attemptDispatch(redis, bookId, chapterId, sceneId, loadedBook, fo
     if (dispatched > 0) {
         return { dispatched, throttled, stages: stages.length };
     }
+    if (deferred > 0 && failures.length === 0) {
+        return { dispatched: 0, throttled, deferred, stages: stages.length, success: true, reason: 'deferred' };
+    }
     if (failures.length > 0) {
         return { dispatched: 0, throttled, stages: stages.length, success: false, reason: failures.join(', ') };
     }

package/src/runtime/scene-window.js

@@ -158,6 +158,34 @@ async function getSceneFilesStatus(buildDir, bookId, chapterId, sceneId) {
         result.image.exists = files.some(f => f.startsWith(imagePrefix) && f.endsWith('.png'));
     } catch (_) {}
 
+    // ── Stage 143a (phase 2a · B1) ───────────────────────────────────
+    // A versioned-only build keeps its IU images under {build}/.versions/**,
+    // which this scan can never see. Only when the LEGACY scan came up empty
+    // do we ask the image facade for a published pointer; the facade is
+    // flag-gated, so flag OFF answers null with ZERO PostgreSQL calls and
+    // this function behaves exactly as before (condition 2).
+    //
+    // A pointer-store ERROR is logged and treated as "no proof" — image
+    // stays NOT existing. It is never read as "the file is there" (that
+    // would write a false READY) and never throws: this is an advisory
+    // checker whose five callers (checkSceneContentCache,
+    // restoreChunkStatusForScene, reconcileWindowStatuses, scene-restoration,
+    // rebuildWorkList) must keep running on a PG outage.
+    if (!result.image.exists) {
+        try {
+            const imageModule = lazyHostBinding('media.image');
+            if (imageModule && typeof imageModule.resolveVersionedSceneProof === 'function') {
+                const buildId = path.basename(path.resolve(buildDir));
+                const proof = await imageModule.resolveVersionedSceneProof(
+                    OUTPUT_DIR, buildId, bookId, chapterId, sceneId);
+                if (proof) result.image.exists = true;
+            }
+        } catch (err) {
+            warn(`image pointer proof unavailable for ${bookId}/${chapterId}/${sceneId} (${err.message}) — image treated as absent`);
+            result.image.exists = false;
+        }
+    }
+
     // Check video file
     const videoPath = path.join(buildDir, artifactNaming.sceneVideoName(bookId, chapterId, sceneId));
     result.video.exists = fs.existsSync(videoPath);

package/test/capacity-deferral.test.js

@@ -0,0 +1,265 @@
+// ======================================================
+// Stage 116 (D3) — CAPACITY DEFERRAL (bounded retry/backoff)
+// ======================================================
+// Regression net for the Stage 115 defect D3: a stage that could not enqueue
+// anything (no live compatible worker, or every job already pending in the
+// lane) was re-dispatched on EVERY scheduler tick (SCHEDULER_TICK_MS = 5 s).
+// Each attempt created a lease + dispatch metadata, the executor sent
+// nothing, the dispatch was cancelled and the FSM was rolled back — an
+// unbounded dispatch/cancel loop with lease churn, FSM churn and unbounded
+// event-journal growth.
+//
+// The fix: a bounded per-stage deferral. While the deferral window is open
+// the dispatch engine returns WITHOUT any side effect (no lease, no metadata,
+// no FSM write, no journal event), the stage stays PENDING and recoverable,
+// and the deferral is cleared by a successful dispatch or an explicit cancel.
+//
+// Isolated: in-memory Redis mock + stubbed host bindings. No production
+// Redis/PG, no hub, no network.
+
+const { expect } = require('chai');
+const { createMockRedis } = require('./mocks/redis-mock');
+const { bindHostModules, clearHostBindings } = require('../src/host/host-bindings');
+
+const BOOK = 'test-stage116-book';
+const CHAPTER = 'ch-stage116';
+const SCENE = 'sc-stage116';
+const BUILD = 'build_test-stage116-book';
+
+describe('Stage 116 (D3): capacity deferral (bounded retry/backoff)', () => {
+    let redis;
+    let dispatchEngine;
+    let journalEvents;
+    let executorCalls;
+    let executorResult;
+    let rollbacks;
+
+    beforeEach(async () => {
+        redis = createMockRedis();
+        journalEvents = [];
+        executorCalls = 0;
+        rollbacks = [];
+        executorResult = { dispatched: false, jobs: 0, reason: 'no_worker_available', retryable: true };
+
+        clearHostBindings();
+        bindHostModules({
+            journal: () => ({
+                appendSceneEvent: async (r, b, c, s, type, state, details) => {
+                    journalEvents.push({ type, state, details });
+                    return true;
+                },
+            }),
+            seams: () => ({
+                getOrchestrationSeam: (name) => {
+                    if (name === 'dispatchStage') {
+                        return async () => {
+                            executorCalls++;
+                            return executorResult;
+                        };
+                    }
+                    if (name === 'rollbackStageToPending') {
+                        return async (r, b, c, s, stage, buildId, reason) => {
+                            rollbacks.push({ stage, reason });
+                            return { changed: true };
+                        };
+                    }
+                    throw new Error(`[stage116-test] seam not wired: ${name}`);
+                },
+            }),
+        });
+
+        dispatchEngine = require('../src/runtime/dispatch-engine');
+    });
+
+    afterEach(() => {
+        clearHostBindings();
+    });
+
+    const dispatch = () => dispatchEngine.dispatchStage(
+        redis, BOOK, CHAPTER, SCENE, 'image', { book_id: BOOK }, BUILD
+    );
+
+    it('a stage that enqueued nothing is deferred and reported as retryable', async () => {
+        const result = await dispatch();
+        expect(result.dispatched).to.equal(false);
+        expect(result.reason).to.equal('no_worker_available');
+        expect(result.retryable).to.equal(true);
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+    });
+
+    it('a deferred stage is NOT re-dispatched on the next tick (no side effects)', async () => {
+        await dispatch();                       // attempt 1 — really attempted
+        const callsAfterFirst = executorCalls;
+        const journalAfterFirst = journalEvents.length;
+
+        // the next scheduler tick (5 s later) must be a no-op
+        const second = await dispatch();
+        expect(second.dispatched).to.equal(false);
+        expect(second.reason).to.equal('deferred_capacity');
+        expect(second.retryable).to.equal(true);
+        expect(executorCalls).to.equal(callsAfterFirst);          // executor NOT called
+        expect(journalEvents.length).to.equal(journalAfterFirst); // no journal event
+    });
+
+    it('100 scheduler ticks inside the deferral window ⇒ ONE attempt (bounded churn)', async () => {
+        await dispatch();
+        for (let i = 0; i < 99; i++) await dispatch();
+        expect(executorCalls).to.equal(1);
+        // the journal must not grow with the tick count (bounded, not unbounded)
+        const journalAfterLoop = journalEvents.length;
+        expect(journalAfterLoop).to.be.lessThan(10);
+    });
+
+    it('the deferral window expires ⇒ the stage is dispatched again', async () => {
+        await dispatch();
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+        // simulate the TTL elapsing (the mock keeps keys until told otherwise)
+        await redis.del(dispatchEngine.deferredStageKey(BOOK, CHAPTER, SCENE, 'image'));
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(false);
+
+        executorResult = { dispatched: true, jobs: 2, reason: null };
+        const result = await dispatch();
+        expect(result.dispatched).to.equal(true);
+        expect(executorCalls).to.equal(2);
+    });
+
+    it('a successful dispatch clears the deferral', async () => {
+        await dispatch();                       // deferred
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+        await redis.del(dispatchEngine.deferredStageKey(BOOK, CHAPTER, SCENE, 'image'));
+        executorResult = { dispatched: true, jobs: 1, reason: null };
+        await dispatch();
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(false);
+    });
+
+    it('an explicit cancel clears the deferral (the user asked for the work)', async () => {
+        await dispatch();
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+        await dispatchEngine.cancelActiveDispatch(redis, BOOK, CHAPTER, SCENE, 'image', 'user_cancel');
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(false);
+    });
+
+    it('a deferred attempt does NOT consume the retry budget (it is not a failure)', async () => {
+        const budgetKey = `animastor:retry-budget:${BOOK}:${CHAPTER}:${SCENE}:image`;
+        await redis.set(budgetKey, '3');
+        await dispatch();
+        const after = await redis.get(budgetKey);
+        expect(after).to.equal('3');     // unchanged — no budget consumed
+    });
+
+    it('a deferred attempt is not reported as a failure (retryable, not fatal)', async () => {
+        const result = await dispatch();
+        expect(result.dispatched).to.equal(false);
+        expect(result.reason).to.equal('no_worker_available');
+        expect(result.retryable).to.equal(true);
+        // the dispatch engine must not have marked the stage as failed
+        expect(result.result && result.result.retryable).to.equal(true);
+    });
+
+    it('the deferral is per stage — another stage of the same scene is not blocked', async () => {
+        await dispatch();                       // image stage deferred
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+        expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'video')).to.equal(false);
+        expect(await dispatchEngine.isStageDeferred(redis, 'other-book', CHAPTER, SCENE, 'image')).to.equal(false);
+    });
+
+    it('deferrable outcomes are classified explicitly (capacity only)', () => {
+        expect(dispatchEngine.isDeferrableOutcome('no_worker_available')).to.equal(true);
+        expect(dispatchEngine.isDeferrableOutcome('duplicate_pending')).to.equal(true);
+        expect(dispatchEngine.isDeferrableOutcome('ambiguous_post')).to.equal(true);
+        // Stage 118 (M4): 'already_completed' is NOT a capacity gap — the
+        // logical task is already complete. It stays deferrable (the stage
+        // must not spin) but in its OWN bucket with its own window.
+        expect(dispatchEngine.isCapacityOutcome('already_completed')).to.equal(false);
+        expect(dispatchEngine.isIdempotentOutcome('already_completed')).to.equal(true);
+        expect(dispatchEngine.isDeferrableOutcome('already_completed')).to.equal(true);
+        // the generic "sent nothing" outcomes keep their historic contract
+        // (immediate retry) — the audit-6929ba5 regressions depend on it
+        expect(dispatchEngine.isDeferrableOutcome('no_jobs_sent')).to.equal(false);
+        expect(dispatchEngine.isDeferrableOutcome('no_jobs_generated')).to.equal(false);
+        expect(dispatchEngine.isDeferrableOutcome('send_failed')).to.equal(false);
+        expect(dispatchEngine.isDeferrableOutcome('already_ready')).to.equal(false);
+        expect(dispatchEngine.isDeferrableOutcome('circuit_open')).to.equal(false);
+    });
+
+    it('the deferral window is bounded (not a permanent block)', () => {
+        expect(dispatchEngine.DEFERRED_STAGE_TTL_S).to.be.a('number');
+        expect(dispatchEngine.DEFERRED_STAGE_TTL_S).to.be.greaterThan(0);
+        expect(dispatchEngine.DEFERRED_STAGE_TTL_S).to.be.lessThanOrEqual(600);
+        // the key lives under the runtime namespace (backend-owned family)
+        expect(dispatchEngine.DEFERRED_STAGE_KEY_PREFIX).to.equal('animastor:runtime:deferred:');
+    });
+
+    // ── Stage 118 (audit 117) ─────────────────────────────────────────────
+    describe('Stage 118: audit 117 corrections', () => {
+        it('M2: force mode does NOT bypass the deferral', async () => {
+            await dispatch();                       // deferred (capacity)
+            expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+            const callsBefore = executorCalls;
+            // The force-dispatch flag lives for 120 s and is set for the WHOLE
+            // book by /regenerate — bypassing the backoff there reproduced the
+            // very churn D3 removes (≈24 full attempts per scene).
+            const forced = await dispatchEngine.dispatchStage(
+                redis, BOOK, CHAPTER, SCENE, 'image', { book_id: BOOK }, BUILD, { force: true }
+            );
+            expect(forced.dispatched).to.equal(false);
+            expect(forced.reason).to.equal('deferred_capacity');
+            expect(forced.deferred).to.equal(true);
+            expect(executorCalls).to.equal(callsBefore);   // no side effect
+        });
+
+        it('M4: the idempotent suppression gets its OWN (longer) window', async () => {
+            executorResult = { dispatched: false, jobs: 0, reason: 'already_completed', retryable: true };
+            await dispatch();
+            expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+            expect(dispatchEngine.deferralWindowFor('already_completed'))
+                .to.equal(dispatchEngine.DEFERRED_IDEMPOTENT_TTL_S);
+            expect(dispatchEngine.deferralWindowFor('no_worker_available'))
+                .to.equal(dispatchEngine.DEFERRED_STAGE_TTL_S);
+            expect(dispatchEngine.DEFERRED_IDEMPOTENT_TTL_S)
+                .to.be.greaterThan(dispatchEngine.DEFERRED_STAGE_TTL_S);
+        });
+
+        it('M1: a book_id containing ":" cannot reach into another book key space', async () => {
+            const bookA = 'a';
+            const bookB = 'a:b';
+            const chapter = 'ch';
+            const scene = 'sc';
+            // the deferral key of book 'a' / chapter 'b' must not collide
+            // with the key of book 'a:b'
+            executorResult = { dispatched: false, jobs: 0, reason: 'no_worker_available', retryable: true };
+            await dispatchEngine.dispatchStage(redis, bookA, chapter, scene, 'image', { book_id: bookA }, BUILD);
+            expect(await dispatchEngine.isStageDeferred(redis, bookA, chapter, scene, 'image')).to.equal(true);
+            expect(await dispatchEngine.isStageDeferred(redis, bookB, chapter, scene, 'image')).to.equal(false);
+            expect(dispatchEngine.deferredStageKey(bookA, chapter, scene, 'image'))
+                .to.not.equal(dispatchEngine.deferredStageKey(bookB, chapter, scene, 'image'));
+        });
+
+        it('M2: an explicit intent clears the backoff of a book / a scene', async () => {
+            await dispatch();
+            expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+            const cleared = await dispatchEngine.clearDeferralsForBook(redis, BOOK);
+            expect(cleared).to.be.greaterThan(0);
+            expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(false);
+
+            await dispatch();
+            expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(true);
+            await dispatchEngine.clearDeferralsForScene(redis, BOOK, CHAPTER, SCENE);
+            expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(false);
+            // a sibling book is untouched
+            await dispatchEngine.dispatchStage(redis, 'other-book', CHAPTER, SCENE, 'image', { book_id: 'other-book' }, BUILD);
+            await dispatchEngine.clearDeferralsForBook(redis, 'other-book');
+            expect(await dispatchEngine.isStageDeferred(redis, BOOK, CHAPTER, SCENE, 'image')).to.equal(false);
+        });
+
+        it('M3: several deferrable reasons are classified (the dominant one is reported)', () => {
+            const { classifyNotSentReasons } = require('../src/runtime/dispatch-outcomes');
+            expect(classifyNotSentReasons(new Map([['no_worker_available', 3], ['duplicate_pending', 1]])))
+                .to.equal('no_worker_available');
+            // a real failure keeps the historic semantics
+            expect(classifyNotSentReasons(new Map([['no_worker_available', 3], ['send_failed', 1]])))
+                .to.equal(null);
+            expect(classifyNotSentReasons(new Map())).to.equal(null);
+        });
+    });
+});