@animastor/orchestration 0.1.7 → 0.2.0

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

@@ -86,6 +86,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
+                });
+            }
         }
     }