@media-engine/core 0.1.0 → 1.0.0

package/dist/engine/engine.js

@@ -1,46 +1,55 @@
-import { MediaEngineError, ProviderError, toProviderFailure } from "../errors/index.js";
+import { MediaEngineError } from "../errors/index.js";
 import { DefaultMergeStrategy } from "../merge/index.js";
 import { ProviderRegistry } from "../providers/index.js";
-// Top-level public external ID shortcuts supported by engine queries.
-// Верхнеуровневые публичные сокращения внешних ID, поддерживаемые query движка.
-const EXTERNAL_ID_SHORTCUTS = [
-    "imdb",
-    "tmdb",
-    "kinopoisk",
-    "shikimori",
-    "myAnimeList",
-    "aniList",
-];
-const SEARCH_ID_ENRICHMENT_LIMIT = 6;
-const SEARCH_ID_ENRICHMENT_TIMEOUT_MS = 1_500;
-const SEARCH_DETAILS_POSTER_ENRICHMENT_LIMIT = 3;
-const SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS = 1_500;
-const SEARCH_FALLBACK_MIN_TOKENS = 3;
-const SEARCH_FALLBACK_MIN_LAST_TOKEN_LENGTH = 4;
-const SEARCH_JOINED_FALLBACK_MIN_LENGTH = 6;
-const SEARCH_JOINED_FALLBACK_MAX_LENGTH = 8;
-const SEARCH_JOINED_FALLBACK_MIN_PART_LENGTH = 3;
-const MAX_SEARCH_LIMIT = 100;
-const MAX_PROVIDER_SEARCH_LIMIT = 100;
-const EXPIRING_AVAILABILITY_CACHE_SAFETY_MS = 1_000;
+import { createAvailabilityCacheOptions, hasUnknownStreamValidation, mergeAvailabilityResults, selectStreamingProviders, } from "./availability.js";
+import { ProviderCircuitBreaker } from "./circuit-breaker.js";
+import { ProviderConcurrencyLimiter } from "./concurrency-limiter.js";
+import { callTimedProviderAvailability, callTimedProviderDetails, callTimedProviderSearch, retryFailedSearchProviders, } from "./provider-calls.js";
+import { createAvailabilityCacheKey, createDetailsCacheKey, createProviderSearchQuery, createSearchCacheKey, createSearchFallbackQuery, createSearchIdentitySnapshotCacheKey, inferTitleLanguage, normalizeDetailsQuery, normalizeSearchQuery, normalizeStreamQuery, normalizeTorrentQuery, validateDetailsQuery, validateSearchQuery, validateStreamQuery, validateTorrentQuery, } from "./query.js";
+import { createResponseMeta, elapsedSince } from "./response-meta.js";
+import { applySearchDetailsEnrichments, executeSearchEnrichmentPlan } from "./search-enrichment.js";
+import { needsFallbackTitleDiscovery, needsPrimaryTitleBroadening } from "./search-discovery.js";
+import { applySearchPosterEnrichments } from "./search-poster-enrichment.js";
+import { applySearchIdEnrichments, createFrozenDiscoveryResults, createSearchEnrichmentCandidates, finalizeSearchRankingEvidence, filterFrozenSearchResults, } from "./search-result-freeze.js";
+import { createSearchIdentitySnapshot, isUsableSearchIdentitySnapshot, recoverSearchIdentitySnapshot, SEARCH_IDENTITY_SNAPSHOT_CACHE_OPTIONS, } from "./search-identity-snapshot.js";
+import { SearchOutcomeAccumulator } from "./search-outcomes.js";
+import { InFlightRequestCoalescer } from "./in-flight.js";
+import { throwIfAborted, waitForCaller } from "./operation.js";
+import { resolveProviderTimeoutMs, validateStreamingProviders, validateTorrentProviders, } from "./runtime.js";
+import { executeTorrentDiscovery } from "./torrents.js";
+import { loadWithStaleFallback } from "./stale-fallback.js";
+import { ProviderTimeoutBudget } from "./timeout-budget.js";
 // Main entry point for using Media Engine core.
 // Главная точка входа для использования Media Engine core.
 export class MediaEngine {
     registry;
     streamingProviders;
+    torrentProviders;
     cache;
     mergeStrategy;
     timeoutMs;
     providerTimeouts;
     debug;
+    circuitBreaker;
+    concurrencyLimiter;
+    inFlightRequests = new InFlightRequestCoalescer();
     constructor(options = {}) {
         this.registry = new ProviderRegistry(options.providers ?? []);
         this.streamingProviders = validateStreamingProviders(options.streamingProviders ?? []);
+        this.torrentProviders = validateTorrentProviders(options.torrentProviders ?? []);
         this.cache = options.cache;
         this.mergeStrategy = options.mergeStrategy ?? new DefaultMergeStrategy();
         this.timeoutMs = options.timeoutMs;
         this.providerTimeouts = { ...options.providerTimeouts };
         this.debug = options.debug ?? false;
+        this.circuitBreaker =
+            options.circuitBreaker === false
+                ? undefined
+                : new ProviderCircuitBreaker(options.circuitBreaker);
+        this.concurrencyLimiter =
+            options.providerConcurrency === false
+                ? undefined
+                : new ProviderConcurrencyLimiter(options.providerConcurrency);
     }
     // Returns safe registered provider metadata without provider internals.
     // Возвращает безопасные метаданные зарегистрированных провайдеров без внутренних данных.
@@ -65,304 +74,491 @@ export class MediaEngine {
             },
         }));
     }
+    // Returns safe registered torrent provider metadata without provider internals.
+    // Возвращает безопасные метаданные torrent-провайдеров без внутренних данных.
+    getTorrentProviders() {
+        return this.torrentProviders.map((provider) => ({
+            name: provider.name,
+            version: provider.version,
+            kind: provider.kind,
+            catalog: provider.catalog
+                ? {
+                    displayName: provider.catalog.displayName,
+                    scope: provider.catalog.scope,
+                    ...(provider.catalog.locale ? { locale: provider.catalog.locale } : {}),
+                }
+                : undefined,
+            capabilities: {
+                mediaTypes: [...provider.capabilities.mediaTypes],
+                lookup: {
+                    byTitle: provider.capabilities.lookup.byTitle,
+                    byExternalIds: [...provider.capabilities.lookup.byExternalIds],
+                    byEpisode: provider.capabilities.lookup.byEpisode,
+                },
+                features: provider.capabilities.features ? [...provider.capabilities.features] : undefined,
+            },
+        }));
+    }
+    // Returns process-local provider reliability counters without exposing provider internals.
+    // Возвращает локальные health-счетчики провайдеров без раскрытия их внутренностей.
+    getProviderHealth() {
+        const metadata = this.registry
+            .getProviders()
+            .map((provider) => this.createProviderHealthStatus(provider.name, "metadata"));
+        const streaming = this.streamingProviders.map((provider) => this.createProviderHealthStatus(provider.name, "streaming"));
+        const torrent = this.torrentProviders.map((provider) => this.createProviderHealthStatus(provider.name, "torrent"));
+        return [...metadata, ...streaming, ...torrent];
+    }
     // Searches media through selected providers and merges normalized results.
     // Ищет медиа через выбранных провайдеров и объединяет нормализованные результаты.
-    async search(query) {
+    async search(query, options = {}) {
+        throwIfAborted(options.signal);
         const startedAt = Date.now();
         const normalizedQuery = normalizeSearchQuery(query);
         validateSearchQuery(normalizedQuery);
+        if (normalizedQuery.limit === 0) {
+            return {
+                query: normalizedQuery,
+                results: [],
+                meta: createResponseMeta({
+                    requested: [],
+                    successful: [],
+                    failed: [],
+                    warnings: [],
+                    cached: false,
+                    tookMs: elapsedSince(startedAt),
+                    debug: this.debug,
+                    timings: [],
+                }),
+            };
+        }
         const searchLanguage = normalizedQuery.language ?? inferTitleLanguage(normalizedQuery.title);
         const cacheKey = createSearchCacheKey(normalizedQuery);
-        const cached = await this.cache?.get(cacheKey);
+        const identitySnapshotCacheKey = createSearchIdentitySnapshotCacheKey(normalizedQuery);
+        const cached = await waitForCaller(this.cache?.get(cacheKey), options.signal);
         if (cached) {
+            const response = structuredClone(cached);
             return {
-                ...cached,
+                ...response,
                 query: normalizedQuery,
                 meta: {
-                    ...cached.meta,
+                    ...response.meta,
                     cached: true,
                     tookMs: elapsedSince(startedAt),
                 },
             };
         }
-        const providers = this.registry.selectSearchProviders(normalizedQuery);
-        const requested = providers.map((provider) => provider.name);
-        const successful = [];
-        const failed = [];
-        const warnings = [];
-        const providerResults = [];
-        const providerTimings = [];
-        let outcomes = await Promise.all(providers.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(normalizedQuery), {
-            debug: this.debug,
-            language: searchLanguage,
-            timeoutMs: this.getProviderTimeoutMs(provider.name),
-        })));
-        if (outcomes.length > 0 && outcomes.every((outcome) => outcome.failure)) {
-            outcomes = await retryFailedSearchProviders(providers, outcomes, normalizedQuery, {
-                debug: this.debug,
-                language: searchLanguage,
-                getTimeoutMs: (providerName) => this.getProviderTimeoutMs(providerName),
+        const stale = await waitForCaller(this.cache?.getStale?.(cacheKey), options.signal);
+        const inFlight = this.inFlightRequests.forCaller(options);
+        const pending = inFlight.run(`search:${cacheKey}`, async (operationSignal) => {
+            const timeoutBudget = this.createProviderTimeoutBudget();
+            const providers = this.registry.selectSearchProviders(normalizedQuery, {
+                titleDiscovery: "primary",
             });
-        }
-        for (const outcome of outcomes) {
-            providerTimings.push(outcome.timing);
-            if (outcome.failure) {
-                failed.push(outcome.failure);
-            }
-            else {
-                successful.push(outcome.provider);
-                providerResults.push(...outcome.results);
-            }
-        }
-        if (providers.length > 0 && successful.length === 0 && failed.length > 0) {
-            throw new MediaEngineError({
-                code: "PROVIDER_ERROR",
-                message: "All search providers failed.",
-                cause: { failed },
+            const primaryProviderNames = new Set(providers.map((provider) => provider.name));
+            const fallbackProviders = this.registry
+                .selectSearchProviders(normalizedQuery, { titleDiscovery: "fallback" })
+                .filter((provider) => !primaryProviderNames.has(provider.name));
+            const requested = providers.map((provider) => provider.name);
+            const successful = [];
+            const failed = [];
+            const warnings = [];
+            const providerResults = [];
+            const providerTimings = [];
+            const searchOutcomes = new SearchOutcomeAccumulator({
+                successful,
+                failed,
+                results: providerResults,
+                timings: providerTimings,
+                warnings,
             });
-        }
-        let results = this.mergeStrategy.mergeSearchResults(providerResults, {
-            query: normalizedQuery,
-            language: searchLanguage,
-            debug: this.debug,
-            warnings,
-            includeIrrelevantSearchResults: true,
-        });
-        const fallbackQuery = createSearchFallbackQuery(normalizedQuery);
-        const hasRelevantResults = fallbackQuery
-            ? this.mergeStrategy.mergeSearchResults(providerResults, {
-                query: normalizedQuery,
-                language: searchLanguage,
-                debug: this.debug,
-            }).length > 0
-            : true;
-        if (fallbackQuery && !hasRelevantResults) {
-            const fallbackOutcomes = await Promise.all(providers.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(fallbackQuery), {
+            const outcomes = await Promise.all(providers.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(normalizedQuery), {
                 debug: this.debug,
                 language: searchLanguage,
-                timeoutMs: this.getProviderTimeoutMs(provider.name),
+                signal: operationSignal,
+                timeoutMs: timeoutBudget.getRemainingMs(provider.name),
+                circuitBreaker: this.circuitBreaker,
+                concurrencyLimiter: this.concurrencyLimiter,
             })));
-            appendUniqueSearchResults(providerResults, fallbackOutcomes.flatMap((outcome) => (outcome.failure ? [] : outcome.results)));
-            results = this.mergeStrategy.mergeSearchResults(providerResults, {
+            searchOutcomes.appendMandatory(outcomes, "primary");
+            if (outcomes.length > 0 && outcomes.every((outcome) => outcome.failure)) {
+                const retryOutcomes = await retryFailedSearchProviders(providers, outcomes, normalizedQuery, {
+                    debug: this.debug,
+                    language: searchLanguage,
+                    signal: operationSignal,
+                    circuitBreaker: this.circuitBreaker,
+                    concurrencyLimiter: this.concurrencyLimiter,
+                    getTimeoutMs: (providerName) => timeoutBudget.getRemainingMs(providerName),
+                });
+                searchOutcomes.appendMandatory(retryOutcomes, "retry");
+            }
+            let results = this.mergeStrategy.mergeSearchResults(providerResults, {
                 query: normalizedQuery,
                 language: searchLanguage,
                 debug: this.debug,
                 warnings,
                 includeIrrelevantSearchResults: true,
             });
-        }
-        const excludedPosterProviders = new Set(failed.map((failure) => failure.provider));
-        const posterEnrichmentPromise = Promise.all(results
-            .slice(0, SEARCH_DETAILS_POSTER_ENRICHMENT_LIMIT)
-            .filter((result) => hasExternalIds(result.item.ids))
-            .map(async (result) => ({
-            ids: result.item.ids,
-            poster: await this.loadSearchPoster(result.item.type, result.item.ids, searchLanguage, excludedPosterProviders).catch(() => undefined),
-        })));
-        const enrichmentResultsPromise = Promise.all(results
-            .slice(0, SEARCH_ID_ENRICHMENT_LIMIT)
-            .filter((result) => needsSearchEnrichment(result.item) && hasExternalIds(result.item.ids))
-            .map(async (result) => {
-            const existingProviders = new Set(result.sources.map((source) => source.provider));
-            const enrichmentType = result.item.type === "anime" ? undefined : result.item.type;
-            const enrichmentProvider = this.registry
-                .selectSearchProviders({ ids: result.item.ids, type: enrichmentType })
-                .find((provider) => !existingProviders.has(provider.name));
-            if (!enrichmentProvider) {
-                return [];
+            const fallbackQuery = createSearchFallbackQuery(normalizedQuery);
+            let relevantResults = fallbackQuery || fallbackProviders.length > 0
+                ? this.mergeStrategy.mergeSearchResults(providerResults, {
+                    query: normalizedQuery,
+                    language: searchLanguage,
+                    debug: this.debug,
+                })
+                : results;
+            let primaryTitleBroadened = false;
+            if (fallbackQuery && needsPrimaryTitleBroadening(normalizedQuery, relevantResults)) {
+                primaryTitleBroadened = true;
+                const fallbackOutcomes = await Promise.all(providers.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(fallbackQuery), {
+                    debug: this.debug,
+                    language: searchLanguage,
+                    signal: operationSignal,
+                    timeoutMs: timeoutBudget.getRemainingMs(provider.name),
+                    circuitBreaker: this.circuitBreaker,
+                    concurrencyLimiter: this.concurrencyLimiter,
+                })));
+                searchOutcomes.appendMandatory(fallbackOutcomes, "fallback", {
+                    deduplicateResults: true,
+                });
+                results = this.mergeStrategy.mergeSearchResults(providerResults, {
+                    query: normalizedQuery,
+                    language: searchLanguage,
+                    debug: this.debug,
+                    warnings,
+                    includeIrrelevantSearchResults: true,
+                });
+                relevantResults = this.mergeStrategy.mergeSearchResults(providerResults, {
+                    query: normalizedQuery,
+                    language: searchLanguage,
+                    debug: this.debug,
+                });
             }
-            const providerTimeoutMs = this.getProviderTimeoutMs(enrichmentProvider.name);
-            const enrichmentTimeoutMs = providerTimeoutMs === undefined
-                ? SEARCH_ID_ENRICHMENT_TIMEOUT_MS
-                : Math.min(providerTimeoutMs, SEARCH_ID_ENRICHMENT_TIMEOUT_MS);
-            const outcome = await callTimedProviderSearch(enrichmentProvider, {
-                ids: result.item.ids,
-                type: enrichmentType,
-                limit: 1,
+            if (fallbackProviders.length > 0 &&
+                !(primaryTitleBroadened && relevantResults.length > 0) &&
+                needsFallbackTitleDiscovery(normalizedQuery, relevantResults)) {
+                requested.push(...fallbackProviders.map((provider) => provider.name));
+                const providerFallbackQuery = relevantResults.length === 0 && fallbackQuery ? fallbackQuery : normalizedQuery;
+                const providerFallbackOutcomes = await Promise.all(fallbackProviders.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(providerFallbackQuery), {
+                    debug: this.debug,
+                    language: searchLanguage,
+                    signal: operationSignal,
+                    timeoutMs: timeoutBudget.getRemainingMs(provider.name),
+                    circuitBreaker: this.circuitBreaker,
+                    concurrencyLimiter: this.concurrencyLimiter,
+                })));
+                searchOutcomes.appendMandatory(providerFallbackOutcomes, "provider_fallback", {
+                    deduplicateResults: true,
+                });
+                results = this.mergeStrategy.mergeSearchResults(providerResults, {
+                    query: normalizedQuery,
+                    language: searchLanguage,
+                    debug: this.debug,
+                    warnings,
+                    includeIrrelevantSearchResults: true,
+                });
+            }
+            if (requested.length > 0 && successful.length === 0 && failed.length > 0) {
+                throw new MediaEngineError({
+                    code: "PROVIDER_ERROR",
+                    message: "All search providers failed.",
+                    cause: { failed },
+                });
+            }
+            const preliminaryDiscoveryResults = results;
+            if (this.mergeStrategy instanceof DefaultMergeStrategy) {
+                const rankedDiscoveryResults = this.mergeStrategy.mergeSearchResults(providerResults, {
+                    query: normalizedQuery,
+                    language: searchLanguage,
+                    debug: this.debug,
+                });
+                results = createFrozenDiscoveryResults(rankedDiscoveryResults, results);
+            }
+            let identitySnapshotDebug;
+            const hasRetryableMandatoryFailure = searchOutcomes.hasRetryableMandatoryFailure();
+            const identitySnapshot = await waitForCaller(this.cache?.get(identitySnapshotCacheKey), operationSignal);
+            if (failed.length === 0 || hasRetryableMandatoryFailure) {
+                const recovery = recoverSearchIdentitySnapshot(results, identitySnapshot);
+                results = recovery.results;
+                identitySnapshotDebug = recovery.debug;
+                if (recovery.debug) {
+                    warnings.push({
+                        code: hasRetryableMandatoryFailure
+                            ? "SEARCH_IDENTITY_SNAPSHOT_FALLBACK"
+                            : "SEARCH_IDENTITY_SNAPSHOT_STABILIZED",
+                        message: hasRetryableMandatoryFailure
+                            ? "Restored previously confirmed search identities because mandatory discovery was retryably degraded."
+                            : "Kept previously confirmed search identities stable across equivalent searches.",
+                    });
+                }
+            }
+            const frozenDiscoveryResults = results;
+            const enrichmentCandidates = createSearchEnrichmentCandidates(frozenDiscoveryResults, preliminaryDiscoveryResults);
+            const excludedPosterProviders = new Set(failed.map((failure) => failure.provider));
+            const enrichment = await executeSearchEnrichmentPlan({
+                results: enrichmentCandidates,
+                publicLimit: normalizedQuery.limit,
                 language: searchLanguage,
-            }, {
+                excludedProviders: excludedPosterProviders,
+                registry: this.registry,
+                mergeStrategy: this.mergeStrategy,
                 debug: this.debug,
-                language: searchLanguage,
-                timeoutMs: enrichmentTimeoutMs,
+                signal: operationSignal,
+                circuitBreaker: this.circuitBreaker,
+                concurrencyLimiter: this.concurrencyLimiter,
+                getProviderTimeoutMs: (providerName) => timeoutBudget.getRemainingMs(providerName),
+                loadReusableDetails: (query, signal, maxWaitMs) => this.loadReusableDetails(query, signal, maxWaitMs),
             });
-            return outcome.failure ? [] : outcome.results;
-        }));
-        const [enrichmentResults, posterEnrichments] = await Promise.all([
-            enrichmentResultsPromise,
-            posterEnrichmentPromise,
-        ]);
-        const flattenedEnrichmentResults = enrichmentResults.flat();
-        if (flattenedEnrichmentResults.length > 0) {
-            providerResults.push(...flattenedEnrichmentResults);
-        }
-        if (this.mergeStrategy instanceof DefaultMergeStrategy ||
-            flattenedEnrichmentResults.length > 0) {
-            results = this.mergeStrategy.mergeSearchResults(providerResults, {
+            const idOutcomes = enrichment.idEnrichments.map((item) => item.outcome);
+            searchOutcomes.appendIdEnrichment(idOutcomes, enrichment.skippedId);
+            searchOutcomes.observePosterEnrichment(enrichment.posterEnrichments.flatMap((item) => item.outcomes), enrichment.skippedPoster);
+            searchOutcomes.appendEnrichmentWarnings();
+            const idEnrichedResults = applySearchIdEnrichments(frozenDiscoveryResults, enrichment.idEnrichments, warnings, searchLanguage);
+            const detailsEnrichedResults = applySearchDetailsEnrichments(idEnrichedResults, enrichment.detailsEnrichments);
+            const posterEnrichedResults = applySearchPosterEnrichments(detailsEnrichedResults, enrichment.posterEnrichments);
+            const filteredResults = this.mergeStrategy instanceof DefaultMergeStrategy
+                ? filterFrozenSearchResults(posterEnrichedResults, normalizedQuery)
+                : posterEnrichedResults;
+            const visibleResultSet = new Set(filteredResults);
+            const visibleDiscoveryResults = frozenDiscoveryResults.filter((_, index) => visibleResultSet.has(posterEnrichedResults[index]));
+            const visibleResults = finalizeSearchRankingEvidence(filteredResults);
+            const limitedResults = normalizedQuery.limit === undefined
+                ? visibleResults
+                : visibleResults.slice(0, normalizedQuery.limit);
+            const response = {
                 query: normalizedQuery,
-                language: searchLanguage,
-                debug: this.debug,
-                warnings,
-            });
-        }
-        const posterEnrichedResults = results.map((result) => {
-            const poster = posterEnrichments.find((enrichment) => enrichment.poster && hasSharedExternalId(result.item.ids, enrichment.ids))?.poster;
-            return poster ? { ...result, item: { ...result.item, poster } } : result;
+                results: limitedResults,
+                meta: createResponseMeta({
+                    requested,
+                    successful,
+                    failed,
+                    warnings,
+                    cached: false,
+                    tookMs: elapsedSince(startedAt),
+                    debug: this.debug,
+                    timings: providerTimings,
+                    enrichment: searchOutcomes.getEnrichmentDebugMeta(),
+                    identitySnapshot: identitySnapshotDebug,
+                }),
+            };
+            throwIfAborted(operationSignal);
+            if (failed.length === 0 && !isUsableSearchIdentitySnapshot(identitySnapshot)) {
+                const newIdentitySnapshot = createSearchIdentitySnapshot(visibleDiscoveryResults);
+                if (newIdentitySnapshot) {
+                    await this.cache?.set(identitySnapshotCacheKey, newIdentitySnapshot, SEARCH_IDENTITY_SNAPSHOT_CACHE_OPTIONS);
+                }
+                else {
+                    await this.cache?.delete(identitySnapshotCacheKey);
+                }
+            }
+            // Keep the complete response most recent when a bounded cache can retain only one entry.
+            // Сохраняем полный ответ последним, если bounded cache вмещает только одну запись.
+            if (!hasRetryableMandatoryFailure) {
+                await this.cache?.set(cacheKey, structuredClone(response));
+            }
+            return response;
+        });
+        return loadWithStaleFallback({
+            stale,
+            pending,
+            tookMs: () => elapsedSince(startedAt),
         });
-        const limitedResults = normalizedQuery.limit === undefined
-            ? posterEnrichedResults
-            : posterEnrichedResults.slice(0, normalizedQuery.limit);
-        const response = {
-            query: normalizedQuery,
-            results: limitedResults,
-            meta: createResponseMeta({
-                requested,
-                successful,
-                failed,
-                warnings,
-                cached: false,
-                tookMs: elapsedSince(startedAt),
-                debug: this.debug,
-                timings: providerTimings,
-            }),
-        };
-        await this.cache?.set(cacheKey, response);
-        return response;
     }
     // Loads media details through selected providers and merges normalized results.
     // Загружает детали медиа через выбранных провайдеров и объединяет нормализованные результаты.
-    async getDetails(query) {
+    async getDetails(query, options = {}) {
+        throwIfAborted(options.signal);
         const startedAt = Date.now();
         const normalizedQuery = normalizeDetailsQuery(query);
         validateDetailsQuery(normalizedQuery);
         const cacheKey = createDetailsCacheKey(normalizedQuery);
-        const cached = await this.cache?.get(cacheKey);
+        const cached = await waitForCaller(this.cache?.get(cacheKey), options.signal);
         if (cached) {
+            const response = structuredClone(cached);
             return {
-                ...cached,
+                ...response,
                 query: normalizedQuery,
                 meta: {
-                    ...cached.meta,
+                    ...response.meta,
                     cached: true,
                     tookMs: elapsedSince(startedAt),
                 },
             };
         }
-        const providers = this.registry.selectDetailsProviders(normalizedQuery);
-        const requested = providers.map((provider) => provider.name);
-        const successful = [];
-        const failed = [];
-        const warnings = [];
-        const providerResults = [];
-        const providerTimings = [];
-        const outcomes = await Promise.all(providers.map((provider) => callTimedProviderDetails(provider, normalizedQuery, {
-            debug: this.debug,
-            language: normalizedQuery.language,
-            timeoutMs: this.getProviderTimeoutMs(provider.name),
-        })));
-        for (const outcome of outcomes) {
-            providerTimings.push(outcome.timing);
-            if (outcome.failure) {
-                failed.push(outcome.failure);
-            }
-            else {
-                successful.push(outcome.provider);
-                if (outcome.result) {
-                    providerResults.push(outcome.result);
+        const stale = await waitForCaller(this.cache?.getStale?.(cacheKey), options.signal);
+        const inFlight = this.inFlightRequests.forCaller(options);
+        const pending = inFlight.run(`details:${cacheKey}`, async (operationSignal) => {
+            const timeoutBudget = this.createProviderTimeoutBudget();
+            const providers = this.registry.selectDetailsProviders(normalizedQuery);
+            const requested = providers.map((provider) => provider.name);
+            const successful = [];
+            const failed = [];
+            const warnings = [];
+            const providerResults = [];
+            const providerTimings = [];
+            const outcomes = await Promise.all(providers.map((provider) => callTimedProviderDetails(provider, normalizedQuery, {
+                debug: this.debug,
+                language: normalizedQuery.language,
+                signal: operationSignal,
+                timeoutMs: timeoutBudget.getRemainingMs(provider.name),
+                circuitBreaker: this.circuitBreaker,
+                concurrencyLimiter: this.concurrencyLimiter,
+            })));
+            for (const outcome of outcomes) {
+                providerTimings.push(outcome.timing);
+                if (outcome.failure) {
+                    failed.push(outcome.failure);
+                }
+                else {
+                    successful.push(outcome.provider);
+                    if (outcome.result) {
+                        providerResults.push(outcome.result);
+                    }
                 }
             }
-        }
-        if (providers.length > 0 && successful.length === 0 && failed.length > 0) {
-            throw new MediaEngineError({
-                code: "PROVIDER_ERROR",
-                message: "All details providers failed.",
-                cause: { failed },
+            if (providers.length > 0 && successful.length === 0 && failed.length > 0) {
+                throw new MediaEngineError({
+                    code: "PROVIDER_ERROR",
+                    message: "All details providers failed.",
+                    cause: { failed },
+                });
+            }
+            const details = this.mergeStrategy.mergeDetails(providerResults, {
+                query: normalizedQuery,
+                language: normalizedQuery.language,
+                debug: this.debug,
+                warnings,
             });
-        }
-        const details = this.mergeStrategy.mergeDetails(providerResults, {
-            query: normalizedQuery,
-            language: normalizedQuery.language,
-            debug: this.debug,
-            warnings,
+            const response = {
+                query: normalizedQuery,
+                details,
+                meta: createResponseMeta({
+                    requested,
+                    successful,
+                    failed,
+                    warnings,
+                    cached: false,
+                    tookMs: elapsedSince(startedAt),
+                    debug: this.debug,
+                    timings: providerTimings,
+                }),
+            };
+            throwIfAborted(operationSignal);
+            if (!hasRetryableProviderFailure(failed)) {
+                await this.cache?.set(cacheKey, structuredClone(response));
+            }
+            return response;
+        });
+        return loadWithStaleFallback({
+            stale,
+            pending,
+            tookMs: () => elapsedSince(startedAt),
         });
-        const response = {
-            query: normalizedQuery,
-            details,
-            meta: createResponseMeta({
-                requested,
-                successful,
-                failed,
-                warnings,
-                cached: false,
-                tookMs: elapsedSince(startedAt),
-                debug: this.debug,
-                timings: providerTimings,
-            }),
-        };
-        await this.cache?.set(cacheKey, response);
-        return response;
     }
     // Loads normalized player and stream availability through streaming providers.
     // Загружает нормализованную доступность player и stream через streaming-провайдеры.
-    async getAvailability(query) {
+    async getAvailability(query, options = {}) {
+        throwIfAborted(options.signal);
         const startedAt = Date.now();
         const normalizedQuery = normalizeStreamQuery(query);
         validateStreamQuery(normalizedQuery);
         const cacheKey = createAvailabilityCacheKey(normalizedQuery);
-        const cached = await this.cache?.get(cacheKey);
+        const cached = await waitForCaller(this.cache?.get(cacheKey), options.signal);
         if (cached) {
+            const response = structuredClone(cached);
             return {
-                ...cached,
+                ...response,
                 query: normalizedQuery,
-                meta: cached.meta
+                meta: response.meta
                     ? {
-                        ...cached.meta,
+                        ...response.meta,
                         cached: true,
                         tookMs: elapsedSince(startedAt),
                     }
                     : undefined,
             };
         }
-        const providers = selectStreamingProviders(this.streamingProviders, normalizedQuery);
-        const requested = providers.map((provider) => provider.name);
-        const successful = [];
-        const failed = [];
-        const providerResults = [];
-        const providerTimings = [];
-        const outcomes = await Promise.all(providers.map((provider) => callTimedProviderAvailability(provider, normalizedQuery, {
-            debug: this.debug,
-            language: normalizedQuery.language,
-            timeoutMs: this.getProviderTimeoutMs(provider.name),
-        })));
-        for (const outcome of outcomes) {
-            providerTimings.push(outcome.timing);
-            if (outcome.failure) {
-                failed.push(outcome.failure);
+        const inFlight = this.inFlightRequests.forCaller(options);
+        return inFlight.run(`availability:${cacheKey}`, async (operationSignal) => {
+            const timeoutBudget = this.createProviderTimeoutBudget();
+            const providers = selectStreamingProviders(this.streamingProviders, normalizedQuery);
+            const requested = providers.map((provider) => provider.name);
+            const successful = [];
+            const failed = [];
+            const providerResults = [];
+            const providerTimings = [];
+            const outcomes = await Promise.all(providers.map((provider) => callTimedProviderAvailability(provider, normalizedQuery, {
+                debug: this.debug,
+                language: normalizedQuery.language,
+                signal: operationSignal,
+                timeoutMs: timeoutBudget.getRemainingMs(provider.name),
+                circuitBreaker: this.circuitBreaker,
+                concurrencyLimiter: this.concurrencyLimiter,
+            })));
+            for (const outcome of outcomes) {
+                providerTimings.push(outcome.timing);
+                if (outcome.failure) {
+                    failed.push(outcome.failure);
+                }
+                else {
+                    successful.push(outcome.provider);
+                    if (outcome.result) {
+                        providerResults.push(outcome.result);
+                    }
+                }
             }
-            else if (outcome.result) {
-                successful.push(outcome.provider);
-                providerResults.push(outcome.result);
+            if (providers.length > 0 && failed.length === providers.length) {
+                throw new MediaEngineError({
+                    code: "PROVIDER_ERROR",
+                    message: "All streaming providers failed.",
+                    cause: { failed },
+                });
             }
-        }
-        if (providers.length > 0 && providerResults.length === 0 && failed.length > 0) {
-            throw new MediaEngineError({
-                code: "PROVIDER_ERROR",
-                message: "All streaming providers failed.",
-                cause: { failed },
+            const availability = mergeAvailabilityResults(normalizedQuery, providerResults);
+            const hasUnknownValidation = hasUnknownStreamValidation(availability);
+            availability.meta = createResponseMeta({
+                requested,
+                successful,
+                failed,
+                warnings: hasUnknownValidation
+                    ? [
+                        {
+                            code: "STREAM_VALIDATION_DEGRADED",
+                            message: "One or more discovered player options could not be validated reliably.",
+                        },
+                    ]
+                    : [],
+                cached: false,
+                tookMs: elapsedSince(startedAt),
+                debug: this.debug,
+                timings: providerTimings,
             });
-        }
-        const availability = mergeAvailabilityResults(normalizedQuery, providerResults);
-        availability.meta = createResponseMeta({
-            requested,
-            successful,
-            failed,
-            warnings: [],
-            cached: false,
-            tookMs: elapsedSince(startedAt),
+            throwIfAborted(operationSignal);
+            if (!hasRetryableProviderFailure(failed) && !hasUnknownValidation) {
+                await this.cache?.set(cacheKey, structuredClone(availability), createAvailabilityCacheOptions(availability));
+            }
+            return availability;
+        });
+    }
+    // Discovers normalized torrent handoff candidates through torrent providers.
+    // Находит нормализованные torrent handoff кандидаты через torrent-провайдеры.
+    async discoverTorrents(query, options = {}) {
+        throwIfAborted(options.signal);
+        const startedAt = Date.now();
+        const normalizedQuery = normalizeTorrentQuery(query);
+        validateTorrentQuery(normalizedQuery);
+        return executeTorrentDiscovery({
+            query: normalizedQuery,
+            options,
+            startedAt,
+            providers: this.torrentProviders,
+            cache: this.cache,
             debug: this.debug,
-            timings: providerTimings,
+            circuitBreaker: this.circuitBreaker,
+            concurrencyLimiter: this.concurrencyLimiter,
+            inFlightRequests: this.inFlightRequests,
+            getProviderTimeoutMs: (providerName) => this.getProviderTimeoutMs(providerName),
         });
-        await this.cache?.set(cacheKey, availability, createAvailabilityCacheOptions(availability));
-        return availability;
     }
     // Gives future engine methods access to the registered providers.
     // Дает будущим методам движка доступ к зарегистрированным провайдерам.
@@ -387,621 +583,87 @@ export class MediaEngine {
     // Resolves a provider override without allowing it to exceed the global boundary.
     // Выбирает override провайдера, не позволяя ему превысить глобальную границу.
     getProviderTimeoutMs(providerName) {
-        const providerTimeoutMs = this.providerTimeouts[providerName];
-        if (providerTimeoutMs === undefined) {
-            return this.timeoutMs;
-        }
-        return this.timeoutMs === undefined
-            ? providerTimeoutMs
-            : Math.min(this.timeoutMs, providerTimeoutMs);
+        return resolveProviderTimeoutMs(providerName, this.timeoutMs, this.providerTimeouts);
     }
-    // Loads only the canonical poster needed by search without blocking on a full details request.
-    // Загружает только канонический постер для search, не блокируя полный details-запрос.
-    async loadSearchPoster(type, ids, language, excludedProviders) {
-        if (!hasExternalIds(ids)) {
+    createProviderTimeoutBudget() {
+        return new ProviderTimeoutBudget((providerName) => this.getProviderTimeoutMs(providerName));
+    }
+    async loadReusableDetails(query, signal, maxWaitMs) {
+        if (maxWaitMs <= 0) {
             return undefined;
         }
-        const query = { type, ids, language };
-        const providers = this.registry
-            .selectDetailsProviders(query)
-            .filter((provider) => !excludedProviders.has(provider.name));
-        const outcomes = await Promise.all(providers.map((provider) => {
-            const providerTimeoutMs = this.getProviderTimeoutMs(provider.name);
-            return callTimedProviderDetails(provider, query, {
-                debug: this.debug,
-                language,
-                timeoutMs: providerTimeoutMs === undefined
-                    ? SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS
-                    : Math.min(providerTimeoutMs, SEARCH_DETAILS_POSTER_ENRICHMENT_TIMEOUT_MS),
+        const normalizedQuery = normalizeDetailsQuery(query);
+        const cacheKey = createDetailsCacheKey(normalizedQuery);
+        const timeoutController = new AbortController();
+        const timeout = setTimeout(() => timeoutController.abort(), maxWaitMs);
+        const waitSignal = signal
+            ? AbortSignal.any([signal, timeoutController.signal])
+            : timeoutController.signal;
+        try {
+            const cached = await waitForCaller(this.cache?.get(cacheKey), waitSignal);
+            if (cached) {
+                return cached.details ?? undefined;
+            }
+            const inFlight = this.inFlightRequests.joinExisting(`details:${cacheKey}`, {
+                signal: waitSignal,
             });
-        }));
-        const providerResults = outcomes.flatMap((outcome) => outcome.failure || !outcome.result ? [] : [outcome.result]);
-        return this.mergeStrategy.mergeDetails(providerResults, {
-            query,
-            language,
-            debug: this.debug,
-            warnings: [],
-        })?.poster;
-    }
-    // Gives future engine methods access to the debug flag.
-    // Дает будущим методам движка доступ к debug-флагу.
-    get engineDebug() {
-        return this.debug;
-    }
-}
-// Enriches compact catalog hits when follow-up cards would otherwise choose different metadata.
-// Обогащает compact catalog hits, чтобы search и details не выбирали разные metadata.
-function needsSearchEnrichment(item) {
-    return !item.ratings?.length || !item.description?.trim() || !item.poster;
-}
-// Validates streaming providers and rejects duplicate public names.
-// Проверяет streaming-провайдеры и отклоняет дубли публичных имен.
-function validateStreamingProviders(providers) {
-    const names = new Set();
-    for (const provider of providers) {
-        const name = provider.name.trim();
-        if (!name) {
-            throw new Error("Streaming provider name is required.");
-        }
-        if (name !== provider.name) {
-            throw new Error(`Streaming provider name "${provider.name}" must not include leading or trailing whitespace.`);
-        }
-        if (names.has(name)) {
-            throw new Error(`Streaming provider "${name}" is already registered.`);
-        }
-        names.add(name);
-    }
-    return [...providers];
-}
-// Normalizes top-level external ID shortcuts into the ids object.
-// Нормализует верхнеуровневые сокращения внешних ID в объект ids.
-function normalizeSearchQuery(query) {
-    const ids = { ...(query.ids ?? {}) };
-    for (const key of EXTERNAL_ID_SHORTCUTS) {
-        const value = query[key];
-        if (value) {
-            ids[key] = value;
-        }
-    }
-    return {
-        ...query,
-        title: query.title?.trim(),
-        ids: hasExternalIds(ids) ? ids : undefined,
-    };
-}
-// Infers a provider lookup language only when the caller did not specify one.
-// Определяет язык provider lookup только если caller не передал его явно.
-function inferTitleLanguage(title) {
-    if (!title)
-        return undefined;
-    if (/[а-яё]/iu.test(title))
-        return "ru";
-    if (/[\u3040-\u30ff\u3400-\u9fff]/u.test(title))
-        return "ja";
-    return /[a-z]/iu.test(title) ? "en" : undefined;
-}
-// Normalizes top-level external ID shortcuts into a details ids object.
-// Нормализует верхнеуровневые сокращения внешних ID в объект ids для details.
-function normalizeDetailsQuery(query) {
-    const ids = { ...(query.ids ?? {}) };
-    for (const key of EXTERNAL_ID_SHORTCUTS) {
-        const value = query[key];
-        if (value) {
-            ids[key] = value;
-        }
-    }
-    return {
-        ...query,
-        ids: hasExternalIds(ids) ? ids : undefined,
-    };
-}
-// Normalizes top-level external ID shortcuts into a streaming ids object.
-// Нормализует верхнеуровневые сокращения внешних ID в объект ids для streaming.
-function normalizeStreamQuery(query) {
-    const queryWithShortcuts = query;
-    const ids = { ...(query.ids ?? {}) };
-    const providers = query.providers?.map((provider) => provider.trim()).filter(Boolean);
-    const language = query.language?.trim();
-    for (const key of EXTERNAL_ID_SHORTCUTS) {
-        const value = queryWithShortcuts[key];
-        if (value) {
-            ids[key] = value;
-        }
-    }
-    return {
-        ...query,
-        title: query.title?.trim(),
-        ...(hasExternalIds(ids) ? { ids } : {}),
-        ...(providers && providers.length > 0 ? { providers } : {}),
-        ...(language ? { language } : {}),
-    };
-}
-// Validates that a search query has at least one supported lookup input.
-// Проверяет, что search query содержит хотя бы один поддерживаемый вход для поиска.
-function validateSearchQuery(query) {
-    if (query.limit !== undefined &&
-        (!Number.isInteger(query.limit) || query.limit < 0 || query.limit > MAX_SEARCH_LIMIT)) {
-        throw new MediaEngineError({
-            code: "INVALID_QUERY",
-            message: `Search query limit must be an integer between 0 and ${MAX_SEARCH_LIMIT}.`,
-        });
-    }
-    if (query.title || hasExternalIds(query.ids)) {
-        return;
-    }
-    throw new MediaEngineError({
-        code: "INVALID_QUERY",
-        message: "Search query must include title or external ids.",
-    });
-}
-// Validates that a details query has at least one supported lookup input.
-// Проверяет, что details query содержит хотя бы один поддерживаемый вход для поиска.
-function validateDetailsQuery(query) {
-    if (query.id?.trim() || hasExternalIds(query.ids)) {
-        return;
-    }
-    throw new MediaEngineError({
-        code: "INVALID_QUERY",
-        message: "Details query must include id or external ids.",
-    });
-}
-// Validates that a streaming query can identify a media item or episode.
-// Проверяет, что streaming query может определить медиа или эпизод.
-function validateStreamQuery(query) {
-    if (!query.type) {
-        throw new MediaEngineError({
-            code: "INVALID_QUERY",
-            message: "Stream query type is required.",
-        });
-    }
-    if ([query.year, query.seasonNumber, query.episodeNumber, query.absoluteEpisodeNumber].some((value) => value !== undefined && (!Number.isInteger(value) || value < 0))) {
-        throw new MediaEngineError({
-            code: "INVALID_QUERY",
-            message: "Stream query numeric fields must be non-negative integers.",
-        });
-    }
-    if (query.title || hasExternalIds(query.ids)) {
-        return;
-    }
-    throw new MediaEngineError({
-        code: "INVALID_QUERY",
-        message: "Stream query must include title or external ids.",
-    });
-}
-// Selects streaming providers that can answer the normalized stream query.
-// Выбирает streaming-провайдеры, которые могут ответить на нормализованный stream query.
-function selectStreamingProviders(providers, query) {
-    return providers.filter((provider) => {
-        if (query.providers && !query.providers.includes(provider.name)) {
-            return false;
-        }
-        if (!provider.capabilities.mediaTypes.includes(query.type)) {
-            return false;
+            if (!inFlight) {
+                return undefined;
+            }
+            return (await inFlight).details ?? undefined;
         }
-        if (hasEpisodeQuery(query) && !provider.capabilities.lookup.byEpisode) {
-            return false;
+        catch (error) {
+            if (signal?.aborted) {
+                throw error;
+            }
+            if (timeoutController.signal.aborted) {
+                return undefined;
+            }
+            throw error;
         }
-        return (Boolean(query.title && provider.capabilities.lookup.byTitle) ||
-            hasSupportedExternalId(query.ids, provider.capabilities.lookup.byExternalIds));
-    });
-}
-// Gives providers enough candidates so the engine can rank before applying the public limit.
-// Дает провайдерам достаточно кандидатов, чтобы движок ранжировал до применения публичного limit.
-function createProviderSearchQuery(query) {
-    if (query.limit === undefined || query.limit === 0) {
-        return query;
-    }
-    return {
-        ...query,
-        limit: getProviderSearchLimit(query),
-    };
-}
-// Retries only transient failures when every selected search provider failed together.
-// Повторяет только временные ошибки, когда одновременно упали все выбранные search-провайдеры.
-async function retryFailedSearchProviders(providers, outcomes, query, context) {
-    return Promise.all(outcomes.map(async (outcome, index) => {
-        const provider = providers[index];
-        if (!provider || !outcome.failure?.retryable) {
-            return outcome;
+        finally {
+            clearTimeout(timeout);
         }
-        return callTimedProviderSearch(provider, createProviderSearchQuery(query), {
-            debug: context.debug,
-            language: context.language,
-            timeoutMs: context.getTimeoutMs(provider.name),
-        });
-    }));
-}
-// Broadens an empty typo search or separates one likely joined compound title.
-// Расширяет пустой поиск с опечаткой или разделяет вероятно слитное составное название.
-function createSearchFallbackQuery(query) {
-    if (!query.title || hasExternalIds(query.ids)) {
-        return undefined;
-    }
-    const title = query.title.trim();
-    const tokens = title.split(/\s+/);
-    const lastToken = tokens.at(-1);
-    if (tokens.length >= SEARCH_FALLBACK_MIN_TOKENS &&
-        lastToken &&
-        lastToken.length >= SEARCH_FALLBACK_MIN_LAST_TOKEN_LENGTH) {
-        return {
-            ...query,
-            title: tokens.slice(0, -1).join(" "),
-        };
-    }
-    const characters = [...title];
-    if (tokens.length !== 1 ||
-        characters.length < SEARCH_JOINED_FALLBACK_MIN_LENGTH ||
-        characters.length > SEARCH_JOINED_FALLBACK_MAX_LENGTH ||
-        !/^\p{Script=Cyrillic}+$/u.test(title)) {
-        return undefined;
-    }
-    const splitIndex = Math.floor(characters.length / 2);
-    if (splitIndex < SEARCH_JOINED_FALLBACK_MIN_PART_LENGTH ||
-        characters.length - splitIndex < SEARCH_JOINED_FALLBACK_MIN_PART_LENGTH) {
-        return undefined;
     }
-    return {
-        ...query,
-        title: `${characters.slice(0, splitIndex).join("")} ${characters.slice(splitIndex).join("")}`,
-    };
-}
-// Adds fallback discoveries without duplicating the same provider item and its attribution.
-// Добавляет fallback-результаты без дублирования item и атрибуции одного провайдера.
-function appendUniqueSearchResults(target, candidates) {
-    for (const candidate of candidates) {
-        const isDuplicate = target.some((existing) => existing.provider === candidate.provider &&
-            existing.item.type === candidate.item.type &&
-            existing.item.id === candidate.item.id);
-        if (!isDuplicate) {
-            target.push(candidate);
+    createProviderHealthStatus(provider, kind) {
+        if (!this.circuitBreaker) {
+            return {
+                provider,
+                kind,
+                circuitState: "disabled",
+                consecutiveFailures: 0,
+                totalRequests: 0,
+                totalSuccesses: 0,
+                totalFailures: 0,
+            };
         }
-    }
-}
-// Expands broad short queries more because final ranking needs enough cross-provider candidates.
-// Расширяет короткие широкие запросы сильнее, потому что финальному ranking нужны кандидаты разных провайдеров.
-function getProviderSearchLimit(query) {
-    if (isBroadShortTitleSearch(query)) {
-        return Math.min(MAX_PROVIDER_SEARCH_LIMIT, Math.max(query.limit * 10, 50));
-    }
-    return Math.min(MAX_PROVIDER_SEARCH_LIMIT, Math.max(query.limit * 5, 10));
-}
-// Detects searches like "one" or "game" where popular canonical results may be deeper.
-// Определяет поиски вроде "one" или "game", где популярные канонические результаты могут быть глубже.
-function isBroadShortTitleSearch(query) {
-    if (query.type || hasExternalIds(query.ids)) {
-        return false;
-    }
-    const normalizedTitle = query.title?.trim().replace(/\s+/g, " ") ?? "";
-    return (normalizedTitle.length > 0 && normalizedTitle.length <= 4 && !normalizedTitle.includes(" "));
-}
-// Calls one search provider and returns normalized timing/failure metadata.
-// Вызывает один search-провайдер и возвращает нормализованные timing/failure метаданные.
-async function callTimedProviderSearch(provider, query, context) {
-    const startedAt = Date.now();
-    try {
-        const results = await callProviderSearch(provider, query, context);
-        return {
-            provider: provider.name,
-            timing: {
-                provider: provider.name,
-                status: "success",
-                tookMs: elapsedSince(startedAt),
-            },
-            results,
-        };
-    }
-    catch (error) {
+        const snapshot = this.circuitBreaker.getSnapshot(`${kind}:${provider}`);
         return {
-            provider: provider.name,
-            timing: {
-                provider: provider.name,
-                status: "failed",
-                tookMs: elapsedSince(startedAt),
-            },
-            results: [],
-            failure: toProviderFailure(provider.name, error),
+            provider,
+            kind,
+            circuitState: snapshot.state,
+            consecutiveFailures: snapshot.consecutiveFailures,
+            totalRequests: snapshot.totalRequests,
+            totalSuccesses: snapshot.totalSuccesses,
+            totalFailures: snapshot.totalFailures,
+            lastSuccessAt: snapshot.lastSuccessAt === undefined
+                ? undefined
+                : new Date(snapshot.lastSuccessAt).toISOString(),
+            lastFailureAt: snapshot.lastFailureAt === undefined
+                ? undefined
+                : new Date(snapshot.lastFailureAt).toISOString(),
+            lastFailureCode: snapshot.lastFailureCode,
+            failureCounts: snapshot.totalFailures > 0 ? snapshot.failureCounts : undefined,
+            retryAfterMs: snapshot.retryAfterMs,
         };
     }
-}
-// Calls one details provider and returns normalized timing/failure metadata.
-// Вызывает один details-провайдер и возвращает нормализованные timing/failure метаданные.
-async function callTimedProviderDetails(provider, query, context) {
-    const startedAt = Date.now();
-    try {
-        const result = await callProviderDetails(provider, query, context);
-        return {
-            provider: provider.name,
-            timing: {
-                provider: provider.name,
-                status: "success",
-                tookMs: elapsedSince(startedAt),
-            },
-            result,
-        };
-    }
-    catch (error) {
-        return {
-            provider: provider.name,
-            timing: {
-                provider: provider.name,
-                status: "failed",
-                tookMs: elapsedSince(startedAt),
-            },
-            result: null,
-            failure: toProviderFailure(provider.name, error),
-        };
-    }
-}
-// Calls one streaming provider and returns normalized timing/failure metadata.
-// Вызывает один streaming-провайдер и возвращает нормализованные timing/failure метаданные.
-async function callTimedProviderAvailability(provider, query, context) {
-    const startedAt = Date.now();
-    try {
-        const result = await callProviderAvailability(provider, query, context);
-        return {
-            provider: provider.name,
-            timing: {
-                provider: provider.name,
-                status: "success",
-                tookMs: elapsedSince(startedAt),
-            },
-            result,
-        };
-    }
-    catch (error) {
-        return {
-            provider: provider.name,
-            timing: {
-                provider: provider.name,
-                status: "failed",
-                tookMs: elapsedSince(startedAt),
-            },
-            result: null,
-            failure: toProviderFailure(provider.name, error),
-        };
-    }
-}
-// Calls one provider search method with timeout and abort signal support.
-// Вызывает search одного провайдера с поддержкой timeout и abort signal.
-async function callProviderSearch(provider, query, context) {
-    return withProviderTimeout(provider.name, context, (controller) => provider.search(query, {
-        signal: controller.signal,
-        timeoutMs: context.timeoutMs,
-        debug: context.debug,
-        language: context.language,
-    }));
-}
-// Calls one provider details method with timeout and abort signal support.
-// Вызывает getDetails одного провайдера с поддержкой timeout и abort signal.
-async function callProviderDetails(provider, query, context) {
-    if (!provider.getDetails) {
-        return null;
-    }
-    return withProviderTimeout(provider.name, context, (controller) => provider.getDetails(query, {
-        signal: controller.signal,
-        timeoutMs: context.timeoutMs,
-        debug: context.debug,
-        language: context.language,
-    }));
-}
-// Calls one streaming provider with timeout and abort signal support.
-// Вызывает один streaming-провайдер с поддержкой timeout и abort signal.
-async function callProviderAvailability(provider, query, context) {
-    return withProviderTimeout(provider.name, context, (controller) => provider.getAvailability(query, {
-        signal: controller.signal,
-        timeoutMs: context.timeoutMs,
-        debug: context.debug,
-        language: context.language,
-    }));
-}
-// Merges availability results without hiding provider attribution.
-// Объединяет availability-результаты, не скрывая атрибуцию провайдеров.
-function mergeAvailabilityResults(query, results) {
-    return {
-        query,
-        item: results.find((result) => result.item)?.item,
-        episodes: mergeEpisodeAvailability(results),
-        options: uniqueBy(results.flatMap((result) => result.options), (option) => `${option.provider}:${option.id}`),
-        sourceProviders: uniqueBy(results.flatMap((result) => result.sourceProviders), (source) => createStreamingSourceKey(source)),
-        checkedAt: new Date().toISOString(),
-    };
-}
-// Merges episode-level availability blocks by episode identity.
-// Объединяет episode-level availability блоки по идентичности эпизода.
-function mergeEpisodeAvailability(results) {
-    const episodesByKey = new Map();
-    for (const episode of results.flatMap((result) => [
-        ...(result.episodes ?? []),
-        ...createEpisodeAvailabilityFromOptions(result.options),
-    ])) {
-        const key = createEpisodeKey(episode);
-        const existing = episodesByKey.get(key);
-        if (!existing) {
-            episodesByKey.set(key, {
-                seasonNumber: episode.seasonNumber,
-                episodeNumber: episode.episodeNumber,
-                absoluteEpisodeNumber: episode.absoluteEpisodeNumber,
-                title: episode.title,
-                options: uniqueBy(episode.options, (option) => `${option.provider}:${option.id}`),
-            });
-            continue;
-        }
-        existing.options = uniqueBy([...existing.options, ...episode.options], (option) => `${option.provider}:${option.id}`);
-        existing.title ??= episode.title;
-    }
-    return episodesByKey.size > 0 ? [...episodesByKey.values()] : undefined;
-}
-// Creates episode blocks from top-level options that carry episode identity.
-// Создает episode blocks из top-level options, которые содержат идентичность эпизода.
-function createEpisodeAvailabilityFromOptions(options) {
-    return options
-        .filter((option) => option.episode)
-        .map((option) => ({
-        seasonNumber: option.episode?.seasonNumber,
-        episodeNumber: option.episode?.episodeNumber,
-        absoluteEpisodeNumber: option.episode?.absoluteEpisodeNumber,
-        options: [option],
-    }));
-}
-// Wraps a provider promise with configured timeout behavior.
-// Оборачивает promise провайдера настроенным timeout-поведением.
-async function withProviderTimeout(providerName, context, run) {
-    const controller = new AbortController();
-    let timeout;
-    try {
-        const providerPromise = run(controller);
-        if (context.timeoutMs === undefined) {
-            return await providerPromise;
-        }
-        const timeoutPromise = new Promise((_, reject) => {
-            const timeoutError = new ProviderError({
-                provider: providerName,
-                code: "PROVIDER_TIMEOUT",
-                message: `Provider "${providerName}" timed out.`,
-                retryable: true,
-            });
-            if (context.timeoutMs <= 0) {
-                controller.abort(timeoutError);
-                reject(timeoutError);
-                return;
-            }
-            timeout = setTimeout(() => {
-                controller.abort(timeoutError);
-                reject(timeoutError);
-            }, context.timeoutMs);
-        });
-        return await Promise.race([providerPromise, timeoutPromise]);
-    }
-    finally {
-        if (timeout) {
-            clearTimeout(timeout);
-        }
-    }
-}
-// Creates public response metadata for a search call.
-// Создает публичные метаданные ответа для search-вызова.
-function createResponseMeta(input) {
-    return {
-        providers: {
-            requested: input.requested,
-            successful: input.successful,
-            failed: input.failed,
-        },
-        cached: input.cached,
-        tookMs: input.tookMs,
-        warnings: input.warnings.length > 0 ? input.warnings : undefined,
-        debug: input.debug
-            ? {
-                providers: input.requested,
-                timings: input.timings ?? [],
-            }
-            : undefined,
-    };
-}
-// Creates a stable cache key for a normalized search query.
-// Создает стабильный cache key для нормализованного search query.
-function createSearchCacheKey(query) {
-    return `search:${JSON.stringify(sortObject(query))}`;
-}
-// Creates a stable cache key for a normalized details query.
-// Создает стабильный cache key для нормализованного details query.
-function createDetailsCacheKey(query) {
-    return `details:${JSON.stringify(sortObject(query))}`;
-}
-// Creates a stable cache key for a normalized streaming query.
-// Создает стабильный cache key для нормализованного streaming query.
-function createAvailabilityCacheKey(query) {
-    return `availability:${JSON.stringify(sortObject(query))}`;
-}
-// Keeps cached direct links from outliving the earliest advertised expiration.
-// Не позволяет кешированным прямым ссылкам пережить ближайший заявленный срок действия.
-function createAvailabilityCacheOptions(availability) {
-    const expiresAtValues = [
-        ...availability.options,
-        ...(availability.episodes?.flatMap((episode) => episode.options) ?? []),
-    ]
-        .map((option) => option.expiresAt)
-        .filter((value) => value !== undefined)
-        .map((value) => Date.parse(value))
-        .filter(Number.isFinite);
-    if (expiresAtValues.length === 0) {
-        return undefined;
-    }
-    const earliestExpiration = Math.min(...expiresAtValues);
-    return {
-        ttlMs: Math.max(0, earliestExpiration - Date.now() - EXPIRING_AVAILABILITY_CACHE_SAFETY_MS),
-    };
-}
-// Checks whether an external ID object contains at least one ID.
-// Проверяет, содержит ли объект внешних ID хотя бы один ID.
-function hasExternalIds(ids) {
-    return Boolean(ids && Object.values(ids).some((value) => Boolean(value)));
-}
-// Checks whether two normalized media identities share at least one exact external ID.
-// Проверяет, совпадает ли у двух нормализованных media identity хотя бы один внешний ID.
-function hasSharedExternalId(left, right) {
-    if (!left || !right) {
-        return false;
-    }
-    return EXTERNAL_ID_SHORTCUTS.some((key) => Boolean(left[key] && left[key] === right[key]));
-}
-// Checks whether query ids overlap provider-supported external ID sources.
-// Проверяет, пересекаются ли query ids с поддерживаемыми провайдером источниками ID.
-function hasSupportedExternalId(ids, supportedSources) {
-    return Boolean(ids && supportedSources.some((source) => Boolean(ids[source])));
-}
-// Checks whether query targets a concrete episode.
-// Проверяет, нацелен ли query на конкретный эпизод.
-function hasEpisodeQuery(query) {
-    return (query.seasonNumber !== undefined ||
-        query.episodeNumber !== undefined ||
-        query.absoluteEpisodeNumber !== undefined);
-}
-// Creates a stable identity for an episode availability block.
-// Создает стабильную идентичность для блока доступности эпизода.
-function createEpisodeKey(episode) {
-    return [
-        episode.seasonNumber ?? "",
-        episode.episodeNumber ?? "",
-        episode.absoluteEpisodeNumber ?? "",
-    ].join(":");
-}
-// Creates a stable identity for provider source attribution.
-// Создает стабильную идентичность для атрибуции источника провайдера.
-function createStreamingSourceKey(source) {
-    return `${source.provider}:${source.url ?? ""}:${JSON.stringify(sortObject(source.ids ?? {}))}`;
-}
-// Keeps the first value for each derived key.
-// Оставляет первое значение для каждого вычисленного ключа.
-function uniqueBy(values, getKey) {
-    const seen = new Set();
-    const unique = [];
-    for (const value of values) {
-        const key = getKey(value);
-        if (!seen.has(key)) {
-            seen.add(key);
-            unique.push(value);
-        }
+    // Gives future engine methods access to the debug flag.
+    // Дает будущим методам движка доступ к debug-флагу.
+    get engineDebug() {
+        return this.debug;
     }
-    return unique;
-}
-// Returns elapsed milliseconds since a start timestamp.
-// Возвращает количество миллисекунд, прошедших с начального timestamp.
-function elapsedSince(startedAt) {
-    return Date.now() - startedAt;
 }
-// Sorts object keys recursively for deterministic JSON cache keys.
-// Рекурсивно сортирует ключи объекта для детерминированных JSON cache keys.
-function sortObject(value) {
-    if (Array.isArray(value)) {
-        return value.map(sortObject);
-    }
-    if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value)
-            .filter(([, entryValue]) => entryValue !== undefined)
-            .sort(([left], [right]) => left.localeCompare(right))
-            .map(([key, entryValue]) => [key, sortObject(entryValue)]));
-    }
-    return value;
+function hasRetryableProviderFailure(failures) {
+    return failures.some((failure) => failure.retryable);
 }
 //# sourceMappingURL=engine.js.map