@animastor/orchestration 0.1.7 → 0.3.0

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/progress-events-port.js

@@ -39,6 +39,11 @@
 //                           pre-pass; the getAssetStates callback arrives
 //                           as an argument exactly as pre-O-5)
 //
+//   blockSceneStage       — command-only generation (2026-10-31): no live
+//                           worker of a stage's type → block the command
+//                           that asked for it (registry + PG are host-side;
+//                           runtime-scheduler via command-gate)
+//
 // Deliberately NOT in the port: createTasks/listTasks/getTask/updateTask/
 // markCompleted/markCancelled/removeTask/clear (routes-side task CRUD —
 // the HTTP contour owns task lifecycle), getActiveTasksByType,
@@ -53,6 +58,7 @@ const OPS = [
     'getSceneTaskState',
     'hasActiveTasks',
     'reconcileCompletedTasks',
+    'blockSceneStage',
 ];
 
 let impl = null;