@animastor/orchestration 0.1.1

package/src/runtime/failure-taxonomy.js

@@ -0,0 +1,125 @@
+// ======================================================
+// FAILURE TAXONOMY - MINIMAL CLASSIFIER
+// ======================================================
+// S1 (2026-07-19): сокращён с 424 строк до ~80.
+// Избыточные pattern-matching, severity levels, retry policies,
+// retry metadata, error wrappers и metrics counters удалены —
+// они не использовались в production-пути.
+//
+// Использование:
+//   - orchestrator.failStage(): classifyFailure() → failureType для journal
+//   - dispatch-engine.finalizeDispatch('failure'): failureType для retry budget
+//
+// Контракт:
+//   classifyFailure(err) → { type: 'transient'|'permanent'|'infrastructure'|'orchestration',
+//                             retryable: boolean }
+//
+// Классификация: trans|orchestration → transient (retry), permanent/infrastructure → нет.
+// Отброшенные патче HTTP-коды и stack-trace парсинг мёртвого retry-manager не нужны.
+
+const logPrefix = '[FAILURE]';
+function log(msg) { console.log(`${logPrefix} ${msg}`); }
+
+const FailureType = {
+    TRANSIENT: 'transient',
+    PERMANENT: 'permanent',
+    INFRASTRUCTURE: 'infrastructure',
+    ORCHESTRATION: 'orchestration'
+};
+
+const FailureSeverity = {
+    LOW: 'low',
+    MEDIUM: 'medium',
+    HIGH: 'high',
+    CRITICAL: 'critical'
+};
+
+// Минимальный набор паттернов для отличия permanent (не retry) от остального.
+const PERMANENT_PATTERNS = [
+    /invalid.*workflow/i,
+    /invalid.*asset/i,
+    /corrupted/i,
+    /invalid.*scene.*data/i,
+    /missing.*required.*field/i,
+    /unsupported.*format/i,
+    /(.*)not.*found$/i
+];
+
+const INFRASTRUCTURE_PATTERNS = [
+    /redis.*unavailable/i,
+    /redis.*connection/i,
+    /filesystem.*error/i,
+    /ffmpeg.*missing/i,
+    /ffmpeg.*not.*found/i,
+    /disk.*full/i,
+    /out.*of.*memory/i
+];
+
+function matchPattern(message, patterns) {
+    if (!message) return false;
+    for (const p of patterns) {
+        if (p.test(message)) return true;
+    }
+    return false;
+}
+
+/**
+ * Classify an error into a failure category.
+ * Returns: { type, retryable, severity, message, code }
+ *
+ * Priority: infrastructure → permanent → orchestration → transient (default).
+ * For 1-5 concurrent users этого достаточно — нет нужды в HTTP-кодах и severity logic.
+ */
+function classifyFailure(err) {
+    if (!err) {
+        return {
+            type: FailureType.TRANSIENT,
+            retryable: true,
+            severity: FailureSeverity.LOW,
+            message: 'Unknown error'
+        };
+    }
+
+    const message = (err.message || err.toString() || '');
+    const code = err.code || null;
+    const lower = message.toLowerCase();
+
+    let type = FailureType.TRANSIENT;
+    let retryable = true;
+    let severity = FailureSeverity.MEDIUM;
+
+    if (matchPattern(lower, INFRASTRUCTURE_PATTERNS)) {
+        type = FailureType.INFRASTRUCTURE;
+        retryable = true;
+        severity = FailureSeverity.HIGH;
+    } else if (matchPattern(lower, PERMANENT_PATTERNS)) {
+        type = FailureType.PERMANENT;
+        retryable = false;
+        severity = FailureSeverity.HIGH;
+    } else if (/invalid.*transition|duplicate.*dispatch|stale.*lease|counter.*drift|token.*mismatch/i.test(lower)) {
+        type = FailureType.ORCHESTRATION;
+        retryable = false;
+        severity = FailureSeverity.MEDIUM;
+    } else if (code === 'EPERM' || code === 'EACCES' || code === 'ENOENT') {
+        type = FailureType.PERMANENT;
+        retryable = false;
+        severity = FailureSeverity.HIGH;
+    } else {
+        type = FailureType.TRANSIENT;
+        retryable = true;
+        severity = FailureSeverity.LOW;
+    }
+
+    return { type, retryable, severity, message, code, classifiedAt: Date.now() };
+}
+
+function getFailureTypeKeys() {
+    return ['transient', 'permanent', 'infrastructure', 'orchestration'];
+}
+
+module.exports = {
+    FailureType,
+    FailureSeverity,
+    classifyFailure,
+    getFailureTypeKeys
+};

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

@@ -0,0 +1,122 @@
+// ======================================================
+// O-9 PORT: HubCancelPort — runtime/orchestration
+// hub-queue cleanup contract
+// ======================================================
+// The runtime and orchestration tiers must not own GPU Hub HTTP cleanup.
+// The hub URL/API-key resolution, the DELETE /queue/clear endpoint shape,
+// per-dispatch retry/warn behavior and the { requested, cleared, failed }
+// result accounting stay HOST-side (backend/src/runtime/dispatch-engine.js
+// clearHubDispatches — the same auth and error-handling contract every
+// caller uses); the tiers purge cancelled dispatches from the hub queue
+// ONLY through this port, wired by the composition root (backend.cjs) at
+// startup.
+//
+//   runtime/** + orchestration/**        (tier consumers)
+//       ↓ consume hub-cancel ops through
+//   runtime/hub-cancel-port.js           ← THIS PORT (tier-owned contract)
+//       ↑ wired by the host
+//   storage/hub-cancel-adapter            (host adapter → dispatch-engine)
+//
+// This is the O-2/O-3/O-4/O-5/O-7/O-8 port convention (runtime/persistence-
+// port.js, runtime/scene-data-port.js, runtime/placeholder-audio-port.js,
+// runtime/progress-events-port.js, runtime/audio-fsm-port.js,
+// runtime/video-fsm-port.js): a zero-require contract module, a fail-fast
+// call-time resolver, one set/wired/reset surface. No hub URL, no API key,
+// no fetch, no HTTP method/endpoint knowledge and no "future ops" cross
+// the boundary — the contract below is EXACTLY the set of operations the
+// two tiers use today (measured at O-9 reconnaissance, §32.26):
+//
+//   clearHubDispatches  — best-effort removal of the queue/running copies
+//                        a cancelled dispatch still owns on the GPU Hub
+//                        (orchestrator resetScenes cancel leg,
+//                        reconciliation RELEASE_STALE_LEASE recovery leg).
+//                        Returns { requested, cleared, failed }; hub
+//                        unavailability is non-fatal per-id (warn + count),
+//                        never throws for a single failed id.
+//
+// Optional-load/error semantics are the CALLER's concern, preserved
+// exactly through the port: the reconciliation RELEASE_STALE_LEASE leg
+// keeps its pre-O-9 `try { … } catch (hubErr) { warn }` best-effort
+// wrapper around the port call (hub cleanup failure must not block state
+// recovery); the orchestrator resetScenes leg keeps its plain await.
+//
+// Deliberately NOT in the port: lease cancellation itself (cancelActive-
+// Dispatch / clearLeasesForScenes / clearLeasesForBookByStage / clearAll-
+// LeasesForBook stay direct dispatch-engine calls — they are Redis-key
+// domain operations, not hub HTTP), job dispatch (the S-3/S-6 Dispatch-
+// Transport seam owns it), any combined "cancel everything" surface and
+// any CRUD "for later".
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md §32.26 (O-9)
+// ======================================================
+
+const OPS = [
+    'clearHubDispatches',
+];
+
+let impl = null;
+
+/**
+ * Wire the host hub-cancel adapter. Called once by the composition root
+ * (backend.cjs) BEFORE any runtime/orchestration hub-cancel consumer runs.
+ * The adapter must expose every op in OPS as a function; lazy resolution
+ * of the host implementation happens at CALL time (the O-2..O-8 adapter
+ * discipline), so wiring never forces a dispatch-engine load.
+ * @param {object} adapter — map with every op in OPS as a function
+ */
+function setHubCancelPort(adapter) {
+    if (!adapter) {
+        throw new Error('hub-cancel-port: adapter is required');
+    }
+    for (const op of OPS) {
+        if (typeof adapter[op] !== 'function') {
+            throw new Error(`hub-cancel-port: adapter must implement ${op}()`);
+        }
+    }
+    impl = adapter;
+}
+
+/** Resolve the port at CALL time — fail-fast when unwired. */
+function hubCancel() {
+    if (!impl) {
+        throw new Error(
+            'hub-cancel-port: not wired — the composition root must call ' +
+            'setHubCancelPort(adapter) (storage/hub-cancel-adapter) ' +
+            'before runtime/orchestration hub-cancel consumers run (O-9)'
+        );
+    }
+    return impl;
+}
+
+/**
+ * Shorthand op resolver: `hubCancelOp('clearHubDispatches')(...)`.
+ * Fails fast when the port or the single op is missing — a missing hub
+ * cleanup silently degrading into a no-op would accumulate duplicate job
+ * copies a worker would later drain (audit c8b79f6).
+ * @param {string} op — op name from OPS
+ */
+function hubCancelOp(op) {
+    const fn = impl?.[op];
+    if (typeof fn !== 'function') {
+        throw new Error(`hub-cancel-port: op '${op}' is not wired (O-9)`);
+    }
+    return fn;
+}
+
+function isHubCancelPortWired() {
+    return impl !== null;
+}
+
+/** Test hygiene: drop the wiring (mocha hooks). */
+function _resetHubCancelPort() {
+    impl = null;
+}
+
+module.exports = {
+    OPS,
+    setHubCancelPort,
+    hubCancel,
+    hubCancelOp,
+    isHubCancelPortWired,
+    _resetHubCancelPort,
+};

package/src/runtime/layer-config-port.js

@@ -0,0 +1,136 @@
+// ======================================================
+// O-10 PORT: LayerConfigPort — runtime/orchestration
+// per-book layer-config contract
+// ======================================================
+// The runtime and orchestration tiers must not know the layer-config host
+// service. The Redis key grammar (`animastor:layer-config:*`), the
+// normalize/clamp pipeline, the durable book.json copy (Кирпич №2) and
+// the fs scanning the service performs stay HOST-side
+// (backend/src/services/layer-config.js); the tiers consume the
+// per-book layer-config operations they actually use ONLY through this
+// port, wired by the composition root (backend.cjs) at startup.
+//
+//   runtime/** + orchestration/**        (tier consumers)
+//       ↓ consume layer-config ops through
+//   runtime/layer-config-port.js         ← THIS PORT (tier-owned contract)
+//       ↑ wired by the host
+//   storage/layer-config-adapter         (host service adapter)
+//
+// This is the O-2..O-9 port convention (runtime/persistence-port.js,
+// runtime/scene-data-port.js, runtime/placeholder-audio-port.js,
+// runtime/progress-events-port.js, runtime/audio-fsm-port.js,
+// runtime/video-fsm-port.js, runtime/hub-cancel-port.js): a zero-require
+// contract module, a fail-fast call-time resolver, one set/wired/reset
+// surface. No Redis key, no fs path, no BOOKS_DIR, no normalize/clamp
+// rules and no "future ops" cross the boundary — the contract below is
+// EXACTLY the set of operations the two tiers use today (measured at
+// O-10 reconnaissance, §32.27):
+//
+//   get               — read the normalized per-book layer config
+//                       (scene-orchestrator executeVideoDispatch
+//                       per-type timeout leg; reconciliation-engine
+//                       rebuildWorkList enabled-layers read)
+//   restoreFromBooks  — heal missing Redis keys from the durable book.json
+//                       copy (reconciliation-engine PHASE C6)
+//
+// The tier-local RAW Redis reads of `animastor:layer-config:*`
+// (reconciliation-engine video-stall threshold, scene-window
+// isWindowComplete/isSceneWindowDone, runtime-scheduler getLayerConfig)
+// are NOT part of this port: they read the key in place with their own
+// bespoke fallback semantics (partial-parse, per-field defaults) that a
+// normalize() call would change — moving them is its own measured
+// decision, not a rider on this seam. The raw Redis channel itself is
+// not a host-service edge (redis is an injected parameter).
+//
+// Deliberately NOT in the port: set/persistToBook (routes/import
+// workflow), getChunkSize (routes + services/agent consumers),
+// SCOPES/ANALYSIS_MODES/DEFAULTS vocabulary (routes/services constants),
+// key/KEY_PREFIX grammar, normalize (host-internal), and any CRUD "for
+// later". The host adapter owns every Redis read, the durable book.json
+// scan and every clamp rule.
+//
+// Optional-load/error semantics are the CALLER's concern, preserved
+// exactly through the port: the reconciliation PHASE C6 leg keeps its
+// pre-O-10 `try { … } catch (err) { warn; summary.errors }` wrapper with
+// the missing-module degrade (a require failure of the host service
+// previously left `layerConfig = null` and skipped the phase silently —
+// the adapter's lazy call-time resolver throws at the same point the
+// pre-O-10 require did, and the caller's catch handles it identically);
+// the scene-orchestrator timeout leg keeps its `try { … } catch (_) {}`
+// tolerance; the rebuildWorkList read stays a plain mandatory await.
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md §32.27 (O-10)
+// ======================================================
+
+const OPS = [
+    'get',
+    'restoreFromBooks',
+];
+
+let impl = null;
+
+/**
+ * Wire the host layer-config adapter. Called once by the composition root
+ * (backend.cjs) BEFORE any runtime/orchestration layer-config consumer
+ * runs. The adapter must expose every op in OPS as a function; lazy
+ * resolution of the host implementation happens at CALL time (the
+ * O-2..O-9 adapter discipline), so wiring never forces a
+ * services/layer-config load.
+ * @param {object} adapter — flat map with every op in OPS as a function.
+ */
+function setLayerConfigPort(adapter) {
+    if (!adapter) {
+        throw new Error('layer-config-port: adapter is required');
+    }
+    for (const op of OPS) {
+        if (typeof adapter[op] !== 'function') {
+            throw new Error(`layer-config-port: adapter must implement ${op}()`);
+        }
+    }
+    impl = adapter;
+}
+
+/** Resolve the port at CALL time — fail-fast when unwired. */
+function layerConfig() {
+    if (!impl) {
+        throw new Error(
+            'layer-config-port: not wired — the composition root must call ' +
+            'setLayerConfigPort(adapter) (storage/layer-config-adapter) ' +
+            'before runtime/orchestration layer-config consumers run (O-10)'
+        );
+    }
+    return impl;
+}
+
+/**
+ * Shorthand op resolver: `layerConfigOp('get')(...)`.
+ * Fails fast when the port or the single op is missing — callers that
+ * tolerate failure keep their own try/catch around the call (the
+ * caller-owned optional-load discipline of O-7/O-9).
+ * @param {string} op — op name from OPS
+ */
+function layerConfigOp(op) {
+    const fn = impl?.[op];
+    if (typeof fn !== 'function') {
+        throw new Error(`layer-config-port: op '${op}' is not wired (O-10)`);
+    }
+    return fn;
+}
+
+function isLayerConfigPortWired() {
+    return impl !== null;
+}
+
+/** Test hygiene: drop the wiring (mocha hooks). */
+function _resetLayerConfigPort() {
+    impl = null;
+}
+
+module.exports = {
+    OPS,
+    setLayerConfigPort,
+    layerConfig,
+    layerConfigOp,
+    isLayerConfigPortWired,
+    _resetLayerConfigPort,
+};