@animastor/orchestration 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@animastor/orchestration",
-    "version": "0.1.3",
+    "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(
-        '/data/output', buildId, bookId, chapterId, sceneId
+    // 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);
@@ -390,7 +442,7 @@ async function handleVideoCompleted(redis, bookId, chapterId, sceneId, buildId)
     // T1: возвращает { ok, retryable, reason, artifact }
     log(`VIDEO_CALLBACK: ${bookId}/${chapterId}/${sceneId}`);
 
-    const videoPath = `/data/output/${buildId}/${bookId}_${chapterId}_${sceneId}.mp4`;
+    const videoPath = `${artifactRoot()}/${buildId}/${bookId}_${chapterId}_${sceneId}.mp4`;
     const { valid, duration, metadata } = video.validateVideoFile(videoPath);
 
     const assetStates = await state.getAssetStates(redis, bookId, chapterId, sceneId);

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