@media-engine/core 0.1.1 → 1.1.0

package/dist/engine/engine.js

@@ -1,25 +1,30 @@
 import { MediaEngineError } from "../errors/index.js";
 import { DefaultMergeStrategy } from "../merge/index.js";
 import { ProviderRegistry } from "../providers/index.js";
-import { createAvailabilityCacheOptions, mergeAvailabilityResults, selectStreamingProviders, } from "./availability.js";
+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 { appendUniqueSearchResults, createAvailabilityCacheKey, createDetailsCacheKey, createProviderSearchQuery, createSearchCacheKey, createSearchFallbackQuery, hasExternalIds, inferTitleLanguage, normalizeDetailsQuery, normalizeSearchQuery, normalizeStreamQuery, validateDetailsQuery, validateSearchQuery, validateStreamQuery, } from "./query.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 { applySearchPosterEnrichments, loadSearchPoster, needsSearchEnrichment, } from "./search-enrichment.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 { resolveProviderTimeoutMs, validateStreamingProviders } from "./runtime.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";
-const SEARCH_ID_ENRICHMENT_LIMIT = 6;
-const SEARCH_ID_ENRICHMENT_TIMEOUT_MS = 1_500;
-const SEARCH_DETAILS_POSTER_ENRICHMENT_LIMIT = 3;
 // Main entry point for using Media Engine core.
 // Главная точка входа для использования Media Engine core.
 export class MediaEngine {
     registry;
     streamingProviders;
+    torrentProviders;
     cache;
     mergeStrategy;
     timeoutMs;
@@ -31,6 +36,7 @@ export class MediaEngine {
     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;
@@ -68,6 +74,31 @@ 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() {
@@ -75,17 +106,36 @@ export class MediaEngine {
             .getProviders()
             .map((provider) => this.createProviderHealthStatus(provider.name, "metadata"));
         const streaming = this.streamingProviders.map((provider) => this.createProviderHealthStatus(provider.name, "streaming"));
-        return [...metadata, ...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 {
@@ -98,48 +148,49 @@ export class MediaEngine {
                 },
             };
         }
-        const stale = await this.cache?.getStale?.(cacheKey);
-        const pending = this.inFlightRequests.run(`search:${cacheKey}`, async () => {
+        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);
+            const providers = this.registry.selectSearchProviders(normalizedQuery, {
+                titleDiscovery: "primary",
+            });
+            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 = [];
-            let outcomes = await Promise.all(providers.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(normalizedQuery), {
+            const searchOutcomes = new SearchOutcomeAccumulator({
+                successful,
+                failed,
+                results: providerResults,
+                timings: providerTimings,
+                warnings,
+            });
+            const outcomes = await Promise.all(providers.map((provider) => callTimedProviderSearch(provider, createProviderSearchQuery(normalizedQuery), {
                 debug: this.debug,
                 language: searchLanguage,
+                signal: operationSignal,
                 timeoutMs: timeoutBudget.getRemainingMs(provider.name),
                 circuitBreaker: this.circuitBreaker,
                 concurrencyLimiter: this.concurrencyLimiter,
             })));
+            searchOutcomes.appendMandatory(outcomes, "primary");
             if (outcomes.length > 0 && outcomes.every((outcome) => outcome.failure)) {
-                outcomes = await retryFailedSearchProviders(providers, outcomes, normalizedQuery, {
+                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),
                 });
-            }
-            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 },
-                });
+                searchOutcomes.appendMandatory(retryOutcomes, "retry");
             }
             let results = this.mergeStrategy.mergeSearchResults(providerResults, {
                 query: normalizedQuery,
@@ -149,22 +200,27 @@ export class MediaEngine {
                 includeIrrelevantSearchResults: true,
             });
             const fallbackQuery = createSearchFallbackQuery(normalizedQuery);
-            const hasRelevantResults = fallbackQuery
+            let relevantResults = fallbackQuery || fallbackProviders.length > 0
                 ? this.mergeStrategy.mergeSearchResults(providerResults, {
                     query: normalizedQuery,
                     language: searchLanguage,
                     debug: this.debug,
-                }).length > 0
-                : true;
-            if (fallbackQuery && !hasRelevantResults) {
+                })
+                : 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,
                 })));
-                appendUniqueSearchResults(providerResults, fallbackOutcomes.flatMap((outcome) => (outcome.failure ? [] : outcome.results)));
+                searchOutcomes.appendMandatory(fallbackOutcomes, "fallback", {
+                    deduplicateResults: true,
+                });
                 results = this.mergeStrategy.mergeSearchResults(providerResults, {
                     query: normalizedQuery,
                     language: searchLanguage,
@@ -172,73 +228,103 @@ export class MediaEngine {
                     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 loadSearchPoster({
-                    result,
+                relevantResults = this.mergeStrategy.mergeSearchResults(providerResults, {
+                    query: normalizedQuery,
                     language: searchLanguage,
-                    excludedProviders: excludedPosterProviders,
-                    registry: this.registry,
-                    mergeStrategy: this.mergeStrategy,
                     debug: this.debug,
-                    circuitBreaker: this.circuitBreaker,
-                    concurrencyLimiter: this.concurrencyLimiter,
-                    getProviderTimeoutMs: (providerName) => timeoutBudget.getRemainingMs(providerName),
-                }).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 enrichmentTimeoutMs = timeoutBudget.getRemainingMs(enrichmentProvider.name, SEARCH_ID_ENRICHMENT_TIMEOUT_MS);
-                const outcome = await callTimedProviderSearch(enrichmentProvider, {
-                    ids: result.item.ids,
-                    type: enrichmentType,
-                    limit: 1,
-                    language: searchLanguage,
-                }, {
+                });
+            }
+            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,
-                    timeoutMs: enrichmentTimeoutMs,
+                    signal: operationSignal,
+                    timeoutMs: timeoutBudget.getRemainingMs(provider.name),
                     circuitBreaker: this.circuitBreaker,
                     concurrencyLimiter: this.concurrencyLimiter,
+                })));
+                searchOutcomes.appendMandatory(providerFallbackOutcomes, "provider_fallback", {
+                    deduplicateResults: true,
                 });
-                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, {
                     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 posterEnrichedResults = applySearchPosterEnrichments(results, posterEnrichments);
+            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,
+                signal: operationSignal,
+                circuitBreaker: this.circuitBreaker,
+                concurrencyLimiter: this.concurrencyLimiter,
+                getProviderTimeoutMs: (providerName) => timeoutBudget.getRemainingMs(providerName),
+                loadReusableDetails: (query, signal, maxWaitMs) => this.loadReusableDetails(query, signal, maxWaitMs),
+            });
+            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
-                ? posterEnrichedResults
-                : posterEnrichedResults.slice(0, normalizedQuery.limit);
+                ? visibleResults
+                : visibleResults.slice(0, normalizedQuery.limit);
             const response = {
                 query: normalizedQuery,
                 results: limitedResults,
@@ -251,9 +337,23 @@ export class MediaEngine {
                     tookMs: elapsedSince(startedAt),
                     debug: this.debug,
                     timings: providerTimings,
+                    enrichment: searchOutcomes.getEnrichmentDebugMeta(),
+                    identitySnapshot: identitySnapshotDebug,
                 }),
             };
-            if (!hasRetryableProviderFailure(failed)) {
+            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;
@@ -266,12 +366,13 @@ export class MediaEngine {
     }
     // 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 {
@@ -284,8 +385,9 @@ export class MediaEngine {
                 },
             };
         }
-        const stale = await this.cache?.getStale?.(cacheKey);
-        const pending = this.inFlightRequests.run(`details:${cacheKey}`, async () => {
+        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);
@@ -297,6 +399,7 @@ export class MediaEngine {
             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,
@@ -340,6 +443,7 @@ export class MediaEngine {
                     timings: providerTimings,
                 }),
             };
+            throwIfAborted(operationSignal);
             if (!hasRetryableProviderFailure(failed)) {
                 await this.cache?.set(cacheKey, structuredClone(response));
             }
@@ -353,12 +457,18 @@ export class MediaEngine {
     }
     // 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 playbackUserAgent = normalizePlaybackUserAgent(options.playbackUserAgent);
+        const providers = selectStreamingProviders(this.streamingProviders, normalizedQuery);
+        const cachePlaybackUserAgent = providers.some((provider) => provider.availabilityDependsOnPlaybackUserAgent)
+            ? playbackUserAgent
+            : undefined;
+        const cacheKey = createAvailabilityCacheKey(normalizedQuery, cachePlaybackUserAgent);
+        const cached = await waitForCaller(this.cache?.get(cacheKey), options.signal);
         if (cached) {
             const response = structuredClone(cached);
             return {
@@ -373,9 +483,9 @@ export class MediaEngine {
                     : undefined,
             };
         }
-        return this.inFlightRequests.run(`availability:${cacheKey}`, async () => {
+        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 = [];
@@ -384,6 +494,8 @@ export class MediaEngine {
             const outcomes = await Promise.all(providers.map((provider) => callTimedProviderAvailability(provider, normalizedQuery, {
                 debug: this.debug,
                 language: normalizedQuery.language,
+                playbackUserAgent,
+                signal: operationSignal,
                 timeoutMs: timeoutBudget.getRemainingMs(provider.name),
                 circuitBreaker: this.circuitBreaker,
                 concurrencyLimiter: this.concurrencyLimiter,
@@ -393,12 +505,14 @@ export class MediaEngine {
                 if (outcome.failure) {
                     failed.push(outcome.failure);
                 }
-                else if (outcome.result) {
+                else {
                     successful.push(outcome.provider);
-                    providerResults.push(outcome.result);
+                    if (outcome.result) {
+                        providerResults.push(outcome.result);
+                    }
                 }
             }
-            if (providers.length > 0 && providerResults.length === 0 && failed.length > 0) {
+            if (providers.length > 0 && failed.length === providers.length) {
                 throw new MediaEngineError({
                     code: "PROVIDER_ERROR",
                     message: "All streaming providers failed.",
@@ -406,22 +520,51 @@ export class MediaEngine {
                 });
             }
             const availability = mergeAvailabilityResults(normalizedQuery, providerResults);
+            const hasUnknownValidation = hasUnknownStreamValidation(availability);
             availability.meta = createResponseMeta({
                 requested,
                 successful,
                 failed,
-                warnings: [],
+                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,
             });
-            if (!hasRetryableProviderFailure(failed)) {
+            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,
+            circuitBreaker: this.circuitBreaker,
+            concurrencyLimiter: this.concurrencyLimiter,
+            inFlightRequests: this.inFlightRequests,
+            getProviderTimeoutMs: (providerName) => this.getProviderTimeoutMs(providerName),
+        });
+    }
     // Gives future engine methods access to the registered providers.
     // Дает будущим методам движка доступ к зарегистрированным провайдерам.
     get providerRegistry() {
@@ -450,6 +593,43 @@ export class MediaEngine {
     createProviderTimeoutBudget() {
         return new ProviderTimeoutBudget((providerName) => this.getProviderTimeoutMs(providerName));
     }
+    async loadReusableDetails(query, signal, maxWaitMs) {
+        if (maxWaitMs <= 0) {
+            return undefined;
+        }
+        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,
+            });
+            if (!inFlight) {
+                return undefined;
+            }
+            return (await inFlight).details ?? undefined;
+        }
+        catch (error) {
+            if (signal?.aborted) {
+                throw error;
+            }
+            if (timeoutController.signal.aborted) {
+                return undefined;
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
     createProviderHealthStatus(provider, kind) {
         if (!this.circuitBreaker) {
             return {
@@ -491,4 +671,14 @@ export class MediaEngine {
 function hasRetryableProviderFailure(failures) {
     return failures.some((failure) => failure.retryable);
 }
+function normalizePlaybackUserAgent(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length > 0 &&
+        normalized.length <= 512 &&
+        !/[\u0000-\u001f\u007f]/u.test(normalized)
+        ? normalized
+        : undefined;
+}
 //# sourceMappingURL=engine.js.map