@media-engine/core 0.1.0 → 1.0.0

package/README.md

@@ -1,295 +1,80 @@
 # @media-engine/core
 
-Core TypeScript package for Media Engine.
+**English** | [Русский](https://github.com/Yaneart/media-engine/blob/main/packages/core/README.ru.md)
 
-It owns the framework-independent engine, public media types, provider contracts, streaming provider contracts, provider registry, merge strategy, cache interface, error model, and testing utilities.
+This is the part of Media Engine that does the thinking: it chooses providers, runs them, merges their answers, caches results, and turns failures into a predictable shape.
 
-Core does not import concrete providers and does not read API keys from the environment. Providers are passed in from the outside.
+It does not contain any real data sources. For those, install `@media-engine/providers` too.
 
 ## Install
 
 ```bash
-npm install @media-engine/core
+npm install @media-engine/core @media-engine/providers
 ```
 
-## Basic Usage
+## Basic use
 
 ```ts
-import { MediaEngine, createMockProvider } from "@media-engine/core";
+import { MediaEngine } from "@media-engine/core";
+import { cinemetaProvider, kinobdProvider } from "@media-engine/providers";
 
 const media = new MediaEngine({
-  providers: [createMockProvider()],
+  providers: [kinobdProvider(), cinemetaProvider()],
 });
 
-const response = await media.search({
-  title: "Interstellar",
-});
-
-console.log(response.results[0]?.item.title);
-console.log(response.meta.providers.successful);
-```
-
-## Usage With Mock Provider
-
-```ts
-import {
-  MediaEngine,
-  createDetailsResult,
-  createMockProvider,
-  createSearchResult,
-  sampleMovie,
-} from "@media-engine/core";
-
-const mockProvider = createMockProvider({
-  name: "local-fixture",
-  searchResults: [createSearchResult("local-fixture", sampleMovie)],
-  detailsResult: createDetailsResult("local-fixture", sampleMovie),
-});
-
-const media = new MediaEngine({
-  providers: [mockProvider],
-});
-
-const search = await media.search({
-  imdb: "tt0816692",
-});
-
-const details = await media.getDetails({
-  imdb: "tt0816692",
-});
-
-console.log(search.results.length);
-console.log(details.details?.title);
-```
-
-## Provider Contract Overview
+const search = await media.search({ title: "Interstellar" });
+const details = await media.getDetails({ imdb: "tt0816692" });
 
-A provider is a small object that implements the `MediaProvider` contract:
-
-```ts
-import type { MediaProvider } from "@media-engine/core";
-
-export const provider: MediaProvider = {
-  name: "example",
-  kind: "metadata",
-  capabilities: {
-    mediaTypes: ["movie", "series", "anime"],
-    search: {
-      byTitle: true,
-      byExternalIds: ["imdb", "tmdb"],
-    },
-    details: {
-      byExternalIds: ["imdb", "tmdb"],
-    },
-  },
-  async search(query, context) {
-    return [];
-  },
-  async getDetails(query, context) {
-    return null;
-  },
-};
+console.log(search.results[0]?.item);
+console.log(details.details);
 ```
 
-`capabilities` tell the engine when a provider can be selected. `search` returns normalized provider search results. `getDetails` is optional; providers without it are skipped by `MediaEngine.getDetails`.
+Details lookup requires a namespaced external ID through `ids` or a shortcut such as `imdb`. The plain `id` field is deprecated because provider-native IDs are not globally unique.
 
-Provider methods receive a `context` with `signal`, `timeoutMs`, `debug`, and `language`. Providers should respect `context.signal` when they perform slow work.
+The engine also has `getAvailability()` for optional streaming providers and a separate `discoverTorrents()` contract for torrent discovery providers.
 
-Applications can bound slower optional providers independently while keeping a global upper limit:
+## What comes from core
 
-```ts
-const media = new MediaEngine({
-  providers,
-  timeoutMs: 5_000,
-  providerTimeouts: {
-    cinemeta: 2_500,
-    wikidata: 2_500,
-  },
-});
-```
+- `MediaEngine`;
+- search, details, media, streaming, and torrent-discovery types;
+- metadata, streaming, and torrent provider contracts;
+- merge and cache interfaces;
+- `MemoryCache`;
+- normalized errors and provider failure metadata;
+- mock providers and fixtures for tests.
 
-The effective timeout is the smaller of `timeoutMs` and the matching `providerTimeouts` value.
+Provider calls run concurrently. If one source fails and another succeeds, the response keeps the useful data and lists the failure in `meta.providers.failed`. Search failures and debug timings include an optional execution `phase`; repeated failures from one provider are represented once in the public failure list. Mandatory retryable primary/fallback degradation is not stored in the normal cache.
 
-## Streaming Availability Contract
+Title search distinguishes primary discovery from slower fallback identity sources through optional `capabilities.search.titleDiscovery`. Custom providers are primary by default. Supported multi-word typos are broadened through primary providers when no exact title exists, even if weak fuzzy noise is present. Fallback providers run when the remaining result is empty, a multi-word query has no exact identity, or exact-title identities conflict. External-ID search still calls every compatible provider immediately.
 
-Streaming availability is separate from metadata search and details. Configure streaming providers through `streamingProviders` and call `getAvailability` with a media or episode identity.
+With a cache configured, the first healthy mandatory discovery whose top candidate has a strong external ID stores a separate identity snapshot for 30 minutes without refreshing it inside that window. Equivalent cache misses with another `limit` share up to 20 confirmed candidates and retain their known order even when a successful upstream response drifts. Stabilization adds `SEARCH_IDENTITY_SNAPSHOT_STABILIZED`. A retryably degraded partial search uses `SEARCH_IDENTITY_SNAPSHOT_FALLBACK` while retaining `meta.providers.failed`, `meta.cached: false`, and the no-cache policy. Neither path accepts conflicting strong IDs; non-retryable degradation does not use the snapshot, and a weak top candidate without a strong ID cannot establish one. Debug mode exposes restored/reordered counters. A first cold degraded request has no snapshot to recover from.
 
-```ts
-import { MediaEngine, createMockProvider } from "@media-engine/core";
-import type { StreamingProvider } from "@media-engine/core";
-
-const streamingProvider: StreamingProvider = {
-  name: "example-streaming",
-  kind: "streaming",
-  capabilities: {
-    mediaTypes: ["movie", "series", "anime"],
-    lookup: {
-      byTitle: true,
-      byExternalIds: ["imdb"],
-      byEpisode: true,
-    },
-    features: ["embed", "translations", "qualities"],
-  },
-  async getAvailability(query) {
-    return {
-      query,
-      options: [],
-      sourceProviders: [{ provider: "example-streaming" }],
-      checkedAt: new Date().toISOString(),
-    };
-  },
-};
+Providers can separately set `capabilities.searchEnrichment: false` to stay out of best-effort search-card ID/poster work. This keeps short optional enrichment deadlines from consuming the reliability budget of a mandatory fallback identity source.
 
-const media = new MediaEngine({
-  providers: [createMockProvider()],
-  streamingProviders: [streamingProvider],
-});
+Optional search ID/poster enrichment failures do not discard the base results. They produce bounded `meta.warnings`, remain cacheable with those warnings, and expose attempted/skipped/succeeded/failed counters plus phase-aware timings when debug mode is enabled. One planner limits enrichment to the bounded top discovery window, at most six additional calls, at most two calls per provider, and 1.5 seconds total. It skips providers that cannot improve a missing field and reuses matching ID-search plus cached or in-flight details outcomes for poster selection.
 
-const availability = await media.getAvailability({
-  type: "movie",
-  imdb: "tt0816692",
-});
-```
+Mandatory discovery and eligible snapshot recovery freeze result identity, score, and order before optional enrichment. Matching enrichment may add presentation fields, non-conflicting external IDs, and source attribution, including aliases that make an unresolved candidate relevant. It never adds provider candidates as new results, changes `id`, `type`, `title`, `originalTitle`, or `year`, recalculates a score, or reranks the response. Conflicting added IDs retain the discovery value and emit `EXTERNAL_ID_CONFLICT`.
 
-Core does not decide whether a third-party player source is appropriate for a product. Concrete streaming providers must document their own source rules and expose only safe access URLs.
+Mandatory ranking favors close multi-word title completions and external IDs that support reliable cross-catalog follow-up. Popular anime catalog identities remain competitive when their audience is established; small audience counters and ratings without vote counts do not receive full ranking weight.
 
-## Search Response Example
+The built-in strategy keeps the first result and every score unchanged, but may interleave a similarly ranked candidate inside the top ten after two results from the same normalized matched-title/media-type family. The alternative must be within `0.03` score and `0.05` title relevance, so weak noise is not promoted merely for variety. Debug mode adds optional per-result `ranking` evidence with the formula, match/title evidence, weighted signal contributions, and raw-score/diversity/final positions; normal responses omit it.
 
-```ts
-import { MediaEngine, createSuccessProvider } from "@media-engine/core";
+`MemoryCache` can retain metadata for a separate bounded stale window. `MediaEngine` uses it only for search and details when every selected provider fails retryably; stale streaming links are never returned. Such responses set `meta.cached` and `meta.stale` to `true`.
 
-const media = new MediaEngine({
-  providers: [createSuccessProvider()],
-});
+Public search, details, availability, and torrent-discovery inputs are canonicalized before provider selection and cache/coalescing keys are built: strings and IDs are trimmed, language is lowercased, top-level ID shortcuts become `ids`, torrent `alternativeTitles` are trimmed and deduplicated, and provider filters are trimmed, deduplicated, and sorted. Known IMDb/numeric ID formats and bounded field lengths and alias counts are validated. Search and torrent discovery with `limit: 0` return empty uncached responses without provider or cache work.
 
-const response = await media.search({
-  title: "Interstellar",
-});
-```
+`MemoryCache` accepts only non-negative safe-integer TTL values. Omit `defaultTtlMs` and per-entry `ttlMs` for entries without expiration; negative values are not a no-expiry sentinel. Stale TTL values follow the same numeric validation.
 
-Shape:
+`search`, `getDetails`, `getAvailability`, and `discoverTorrents` accept optional `{ signal }` operation options. Identical requests still share one provider operation, but each caller has an independent subscription: aborting one caller does not affect the others, while the shared provider signal is aborted once no active subscribers remain. Fully cancelled work is not cached, and client cancellation is not counted as an upstream circuit-breaker failure.
 
-```ts
-{
-  query: {
-    title: "Interstellar",
-  },
-  results: [
-    {
-      item: {
-        id: "sample-movie-interstellar",
-        type: "movie",
-        title: "Interstellar",
-        year: 2014,
-      },
-      score: 0.5,
-      sources: [
-        {
-          provider: "success-provider",
-        },
-      ],
-    },
-  ],
-  meta: {
-    providers: {
-      requested: ["success-provider"],
-      successful: ["success-provider"],
-      failed: [],
-    },
-    cached: false,
-    tookMs: 1,
-  },
-}
-```
-
-`score`, `tookMs`, and optional fields can vary with the provider result and merge strategy.
-
-## Details Response Example
-
-```ts
-import { MediaEngine, createSuccessProvider } from "@media-engine/core";
-
-const media = new MediaEngine({
-  providers: [createSuccessProvider()],
-});
-
-const response = await media.getDetails({
-  imdb: "tt0816692",
-});
-```
-
-Shape:
-
-```ts
-{
-  query: {
-    imdb: "tt0816692",
-    ids: {
-      imdb: "tt0816692",
-    },
-  },
-  details: {
-    id: "sample-movie-interstellar",
-    type: "movie",
-    title: "Interstellar",
-    year: 2014,
-  },
-  meta: {
-    providers: {
-      requested: ["success-provider"],
-      successful: ["success-provider"],
-      failed: [],
-    },
-    cached: false,
-    tookMs: 1,
-  },
-}
-```
-
-If selected providers return no details, `details` is `null`.
-
-## Availability Response Example
-
-```ts
-import { MediaEngine, createSuccessProvider } from "@media-engine/core";
-
-const media = new MediaEngine({
-  providers: [createSuccessProvider()],
-});
-
-const response = await media.getAvailability({
-  type: "movie",
-  imdb: "tt0816692",
-});
-```
-
-When no streaming providers are configured, `options` is empty and `sourceProviders` is empty. Provider failures are exposed through response metadata when configured providers fail.
-
-## Bounded Memory Cache
-
-```ts
-import { MediaEngine, MemoryCache } from "@media-engine/core";
-
-const media = new MediaEngine({
-  cache: new MemoryCache({
-    defaultTtlMs: 5 * 60_000,
-    maxEntries: 500,
-  }),
-});
-```
+A streaming provider that resolves `null` is recorded as a successful no-result lookup. The engine reports an all-failed error only when every selected streaming provider actually failed. Discovered player options with an uncertain validation result remain visible with `availability: "unknown"`; the response includes `STREAM_VALIDATION_DEGRADED` and is retried instead of being stored in the normal availability cache.
 
-`defaultTtlMs` applies when a cache write does not specify its own TTL. `maxEntries` bounds memory usage and evicts the least-recently-used entry when full.
+The constructor also accepts streaming and torrent providers, a cache, global and per-provider timeouts, a custom merge strategy, and debug mode. Provider calls are bounded to two concurrent operations per provider by default, with a cancellable queue of 100; `providerConcurrency` can tune per-provider limits or disable the gate. Queue waiting remains inside the existing provider timeout. Core never imports concrete provider packages itself.
 
-## Testing Utilities
+Torrent discovery remains independent from streaming availability. A `TorrentProvider` returns normalized candidates with source attribution and an explicit `magnet`, `torrent_file`, or `external` handoff. Optional provider `catalog` metadata supports regional/international UI grouping, and a candidate may retain a concrete meta-indexer `catalogSource`; neither field guarantees a release audio language. Core does not open that handoff, download torrent metadata, join a swarm, select files, store media, proxy traffic, or transcode video. No concrete torrent provider is bundled in core.
 
-The core package exports deterministic helpers for tests and examples:
+Exact types are available from the package exports. The short [public API guide](https://github.com/Yaneart/media-engine/blob/main/docs/public-api.md) explains the four main operations without repeating every field.
 
-- `createMockProvider`;
-- `createSuccessProvider`;
-- `createFailingProvider`;
-- `createTimeoutProvider`;
-- `sampleMovie`;
-- `sampleSeries`;
-- `sampleAnime`.
+## License
 
-These helpers do not call real APIs and do not require API keys.
+MIT

package/README.ru.md

@@ -0,0 +1,80 @@
+# @media-engine/core
+
+[English](https://github.com/Yaneart/media-engine/blob/main/packages/core/README.md) | **Русский**
+
+Это часть Media Engine, которая отвечает за основную логику: выбирает провайдеры, запускает их, объединяет ответы, кеширует результат и приводит ошибки к предсказуемому виду.
+
+Самих источников данных в core нет. Для них установите ещё и `@media-engine/providers`.
+
+## Установка
+
+```bash
+npm install @media-engine/core @media-engine/providers
+```
+
+## Простой пример
+
+```ts
+import { MediaEngine } from "@media-engine/core";
+import { cinemetaProvider, kinobdProvider } from "@media-engine/providers";
+
+const media = new MediaEngine({
+  providers: [kinobdProvider(), cinemetaProvider()],
+});
+
+const search = await media.search({ title: "Интерстеллар" });
+const details = await media.getDetails({ imdb: "tt0816692" });
+
+console.log(search.results[0]?.item);
+console.log(details.details);
+```
+
+Для загрузки деталей нужен внешний ID с указанием источника — через `ids` или сокращение вроде `imdb`. Обычное поле `id` устарело, потому что внутренние ID разных провайдеров не образуют общее пространство имён.
+
+Для опциональных стриминговых провайдеров у движка также есть `getAvailability()`, а для torrent discovery — отдельный контракт `discoverTorrents()`.
+
+## Что экспортирует core
+
+- `MediaEngine`;
+- типы поиска, деталей, медиа, стриминга и torrent discovery;
+- контракты metadata-, streaming- и torrent-провайдеров;
+- интерфейсы объединения и кеша;
+- `MemoryCache`;
+- нормализованные ошибки и сведения о сбоях провайдеров;
+- mock-провайдеры и примеры данных для тестов.
+
+Провайдеры запускаются параллельно. Если один источник не сработал, а другой вернул данные, полезный ответ сохранится, а ошибка попадёт в `meta.providers.failed`. Search-ошибки и debug timings содержат опциональную фазу выполнения `phase`; повторные ошибки одного провайдера представлены одной записью в публичном списке. Обязательная retryable-деградация primary/fallback не записывается в normal cache.
+
+Title search разделяет основные discovery-источники и более медленные fallback identity-источники через опциональный `capabilities.search.titleDiscovery`. Пользовательские провайдеры по умолчанию считаются primary. Поддерживаемые multi-word опечатки расширяются через primary-провайдеры при отсутствии точного title, даже если присутствует weak fuzzy noise. Fallback-провайдеры запускаются при пустом результате, отсутствии точной identity у multi-word запроса или конфликтующих точных title-identity. Поиск по внешнему ID по-прежнему сразу вызывает все совместимые провайдеры.
+
+При настроенном cache первая здоровая mandatory discovery, у top-кандидата которой есть strong external ID, отдельно сохраняет identity snapshot на 30 минут без продления этого окна. Эквивалентные cache misses с другим `limit` используют до 20 общих подтвержденных кандидатов и сохраняют их известный порядок, даже если успешный upstream-ответ меняется. Такая стабилизация добавляет `SEARCH_IDENTITY_SNAPSHOT_STABILIZED`. Retryable-деградированный частичный поиск использует `SEARCH_IDENTITY_SNAPSHOT_FALLBACK`, сохраняя `meta.providers.failed`, `meta.cached: false` и запрет обычного кеширования. Оба пути не принимают конфликтующий strong ID; при non-retryable-деградации snapshot не применяется, а слабый top-кандидат без strong ID не может создать snapshot. Debug-режим показывает счетчики restored/reordered. У первого холодного деградированного запроса snapshot для восстановления ещё нет.
+
+Отдельный `capabilities.searchEnrichment: false` исключает провайдер из best-effort ID/poster enrichment поисковых карточек. Так короткий optional enrichment deadline не расходует reliability budget обязательного fallback identity-источника.
+
+Ошибки опционального ID/poster enrichment не удаляют базовые результаты. Они формируют ограниченные `meta.warnings`, могут кэшироваться вместе с предупреждениями, а в debug-режиме предоставляют счетчики attempted/skipped/succeeded/failed и phase-aware timings. Единый planner ограничивает enrichment ограниченным top discovery window, максимум шестью дополнительными вызовами, двумя вызовами одного провайдера и общим временем 1,5 секунды. Он пропускает провайдеры, неспособные улучшить отсутствующее поле, и переиспользует совпадающий ID-search, а также cached или in-flight details для выбора poster.
+
+Mandatory discovery и подходящее snapshot recovery фиксируют identity, score и порядок результатов до optional enrichment. Совпавшее enrichment может добавить presentation-поля, непротиворечивые external IDs и source attribution, включая aliases, которые делают ранее unresolved candidate релевантным. Оно не добавляет provider candidates как новые результаты, не меняет `id`, `type`, `title`, `originalTitle` или `year`, не пересчитывает score и не переставляет ответ. При конфликте добавляемого ID сохраняется discovery-значение и формируется `EXTERNAL_ID_CONFLICT`.
+
+Mandatory ranking предпочитает близкие по длине multi-word title completions и external IDs, пригодные для надёжного cross-catalog follow-up. Популярные anime catalog identities остаются конкурентными при подтверждённой аудитории; малые audience counters и ratings без vote count не получают полный ranking weight.
+
+Встроенная стратегия сохраняет первый результат и все score, но внутри top-10 может поднять сопоставимый кандидат после двух результатов одной normalized matched-title/media-type family. Альтернатива должна отличаться не более чем на `0.03` по score и `0.05` по title relevance, поэтому слабый шум не продвигается только ради разнообразия. В debug-режиме результат получает опциональный `ranking` с formula, match/title evidence, взвешенными signal contributions и позициями raw score/diversity/final; в обычном ответе этого поля нет.
+
+`MemoryCache` может сохранять метаданные в отдельном ограниченном stale-окне. `MediaEngine` использует их только для поиска и деталей, когда все выбранные провайдеры завершились с retryable-ошибками; устаревшие streaming-ссылки никогда не возвращаются. В таком ответе `meta.cached` и `meta.stale` равны `true`.
+
+Публичные search, details, availability и torrent-discovery запросы приводятся к canonical-виду до выбора провайдеров и построения cache/coalescing keys: строки и ID обрезаются, язык переводится в нижний регистр, top-level ID shortcuts переносятся в `ids`, torrent `alternativeTitles` обрезаются и дедуплицируются, а provider filters обрезаются, дедуплицируются и сортируются. Известные форматы IMDb/numeric ID, длины полей и количество aliases валидируются. Search и torrent discovery с `limit: 0` возвращают пустые некешированные ответы без обращений к провайдерам или cache.
+
+`MemoryCache` принимает для TTL только неотрицательные safe integer значения. Для записей без срока истечения не задавайте `defaultTtlMs` и per-entry `ttlMs`; отрицательные значения не являются no-expiry sentinel. Для stale TTL действует та же числовая валидация.
+
+`search`, `getDetails`, `getAvailability` и `discoverTorrents` принимают опциональные operation options `{ signal }`. Одинаковые запросы по-прежнему делят одну provider operation, но у каждого caller отдельная подписка: отмена одного caller не влияет на остальных, а общий provider signal отменяется, когда активных подписчиков не осталось. Полностью отмененная работа не кешируется, а client cancellation не считается upstream-сбоем circuit breaker.
+
+Если streaming-провайдер возвращает `null`, это считается успешным запросом без результата. Ошибка all-failed возникает, только когда действительно завершились ошибкой все выбранные streaming-провайдеры. Найденные плееры с неопределённым результатом проверки остаются в ответе с `availability: "unknown"`; engine добавляет `STREAM_VALIDATION_DEGRADED` и повторяет lookup вместо записи такого ответа в обычный availability-кеш.
+
+Конструктор также принимает streaming- и torrent-провайдеры, кеш, общий и индивидуальные тайм-ауты, собственную стратегию объединения и debug-режим. По умолчанию одновременно выполняются не более двух операций каждого провайдера, а отменяемая очередь ограничена 100 элементами; `providerConcurrency` позволяет настроить отдельные лимиты или отключить gate. Ожидание в очереди входит в существующий тайм-аут провайдера. Сам core никогда не импортирует пакеты с конкретными провайдерами.
+
+Torrent discovery не смешивается со streaming availability. `TorrentProvider` возвращает нормализованные кандидаты с source attribution и явным handoff типа `magnet`, `torrent_file` или `external`. Опциональные provider `catalog` metadata позволяют UI группировать региональные и международные каталоги, а candidate может сохранять конкретный `catalogSource` meta-indexer; ни одно из этих полей не гарантирует язык аудиодорожки релиза. Core не открывает handoff, не загружает torrent metadata, не подключается к swarm, не выбирает файлы, не хранит media, не проксирует трафик и не транскодирует видео. Сам core не содержит конкретного torrent-провайдера.
+
+Точные типы доступны через exports пакета. В коротком [описании публичного API](https://github.com/Yaneart/media-engine/blob/main/docs/public-api.md) разобраны четыре основные операции без перечисления каждого поля.
+
+## Лицензия
+
+MIT

package/dist/cache/memory.d.ts

@@ -2,18 +2,23 @@ import type { Cache, CacheSetOptions } from "./types.js";
 export interface MemoryCacheOptions {
     now?: () => number;
     defaultTtlMs?: number;
+    defaultStaleTtlMs?: number;
     maxEntries?: number;
 }
 export declare class MemoryCache implements Cache {
     private readonly entries;
     private readonly now;
     private readonly defaultTtlMs?;
+    private readonly defaultStaleTtlMs?;
     private readonly maxEntries?;
     constructor(options?: MemoryCacheOptions);
     get<T>(key: string): T | undefined;
+    getStale<T>(key: string): T | undefined;
     set<T>(key: string, value: T, options?: CacheSetOptions): void;
     delete(key: string): void;
     clear(): void;
     private isExpired;
+    private isBeyondStaleWindow;
+    private deleteIfBeyondStaleWindow;
     private evictOverflow;
 }

package/dist/cache/memory.js

@@ -4,14 +4,18 @@ export class MemoryCache {
     entries = new Map();
     now;
     defaultTtlMs;
+    defaultStaleTtlMs;
     maxEntries;
     constructor(options = {}) {
         if (options.maxEntries !== undefined &&
             (!Number.isInteger(options.maxEntries) || options.maxEntries <= 0)) {
             throw new TypeError("MemoryCache maxEntries must be a positive integer.");
         }
+        validateTtl("defaultTtlMs", options.defaultTtlMs);
+        validateTtl("defaultStaleTtlMs", options.defaultStaleTtlMs);
         this.now = options.now ?? Date.now;
         this.defaultTtlMs = options.defaultTtlMs;
+        this.defaultStaleTtlMs = options.defaultStaleTtlMs;
         this.maxEntries = options.maxEntries;
     }
     // Reads a cached value and removes it when it has expired.
@@ -22,6 +26,23 @@ export class MemoryCache {
             return undefined;
         }
         if (this.isExpired(entry)) {
+            this.deleteIfBeyondStaleWindow(key, entry);
+            return undefined;
+        }
+        if (this.maxEntries !== undefined) {
+            this.entries.delete(key);
+            this.entries.set(key, entry);
+        }
+        return cloneCacheValue(entry.value);
+    }
+    // Reads a value only after normal TTL expiration and before its stale window closes.
+    // Читает значение только после обычного TTL и до завершения stale-окна.
+    getStale(key) {
+        const entry = this.entries.get(key);
+        if (!entry || !this.isExpired(entry)) {
+            return undefined;
+        }
+        if (this.isBeyondStaleWindow(entry)) {
             this.entries.delete(key);
             return undefined;
         }
@@ -35,9 +56,15 @@ export class MemoryCache {
     // Сохраняет значение с опциональным TTL в миллисекундах.
     set(key, value, options = {}) {
         const ttlMs = options.ttlMs ?? this.defaultTtlMs;
-        const expiresAt = ttlMs === undefined || ttlMs < 0 ? undefined : this.now() + ttlMs;
+        const staleTtlMs = options.staleTtlMs ?? this.defaultStaleTtlMs;
+        validateTtl("ttlMs", ttlMs);
+        validateTtl("staleTtlMs", staleTtlMs);
+        const expiresAt = ttlMs === undefined ? undefined : this.now() + ttlMs;
+        const staleUntil = expiresAt === undefined || staleTtlMs === undefined || staleTtlMs <= 0
+            ? undefined
+            : expiresAt + staleTtlMs;
         this.entries.delete(key);
-        this.entries.set(key, { value: cloneCacheValue(value), expiresAt });
+        this.entries.set(key, { value: cloneCacheValue(value), expiresAt, staleUntil });
         this.evictOverflow();
     }
     // Removes one cache entry by key.
@@ -55,6 +82,14 @@ export class MemoryCache {
     isExpired(entry) {
         return entry.expiresAt !== undefined && entry.expiresAt <= this.now();
     }
+    isBeyondStaleWindow(entry) {
+        return entry.staleUntil === undefined || entry.staleUntil <= this.now();
+    }
+    deleteIfBeyondStaleWindow(key, entry) {
+        if (this.isBeyondStaleWindow(entry)) {
+            this.entries.delete(key);
+        }
+    }
     // Evicts expired entries first, then least-recently-used entries until the bound is met.
     // Сначала удаляет истекшие записи, затем давно не использованные до соблюдения лимита.
     evictOverflow() {
@@ -62,7 +97,7 @@ export class MemoryCache {
             return;
         }
         for (const [key, entry] of this.entries) {
-            if (this.isExpired(entry)) {
+            if (this.isExpired(entry) && this.isBeyondStaleWindow(entry)) {
                 this.entries.delete(key);
             }
         }
@@ -80,4 +115,9 @@ export class MemoryCache {
 function cloneCacheValue(value) {
     return structuredClone(value);
 }
+function validateTtl(name, value) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+        throw new TypeError(`MemoryCache ${name} must be a non-negative safe integer.`);
+    }
+}
 //# sourceMappingURL=memory.js.map

package/dist/cache/memory.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/cache/memory.ts"],"names":[],"mappings":"AAiBA,gEAAgE;AAChE,oEAAoE;AACpE,MAAM,OAAO,WAAW;IACL,OAAO,GAAG,IAAI,GAAG,EAAqC,CAAC;IACvD,GAAG,CAAe;IAClB,YAAY,CAAU;IACtB,UAAU,CAAU;IAErC,YAAY,UAA8B,EAAE;QAC1C,IACE,OAAO,CAAC,UAAU,KAAK,SAAS;YAChC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,EAClE,CAAC;YACD,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;QAC5E,CAAC;QAED,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACvC,CAAC;IAED,2DAA2D;IAC3D,2DAA2D;IAC3D,GAAG,CAAI,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEpC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO,eAAe,CAAC,KAAK,CAAC,KAAU,CAAC,CAAC;IAC3C,CAAC;IAED,uDAAuD;IACvD,yDAAyD;IACzD,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,UAA2B,EAAE;QACzD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QACjD,MAAM,SAAS,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QAEpF,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,aAAa,EAAE,CAAC;IACvB,CAAC;IAED,kCAAkC;IAClC,sCAAsC;IACtC,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,6BAA6B;IAC7B,4BAA4B;IAC5B,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,iEAAiE;IACjE,8DAA8D;IACtD,SAAS,CAAC,KAAgC;QAChD,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACxE,CAAC;IAED,yFAAyF;IACzF,uFAAuF;IAC/E,aAAa;QACnB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1E,OAAO;QACT,CAAC;QAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAA2B,CAAC;YAEzE,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,MAAM;YACR,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;CACF;AAED,2EAA2E;AAC3E,8EAA8E;AAC9E,SAAS,eAAe,CAAI,KAAQ;IAClC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/cache/memory.ts"],"names":[],"mappings":"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"}

package/dist/cache/types.d.ts

@@ -1,8 +1,10 @@
 export interface CacheSetOptions {
     ttlMs?: number;
+    staleTtlMs?: number;
 }
 export interface Cache {
     get<T>(key: string): Promise<T | undefined> | T | undefined;
+    getStale?<T>(key: string): Promise<T | undefined> | T | undefined;
     set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void> | void;
     delete(key: string): Promise<void> | void;
     clear(): Promise<void> | void;

package/dist/details/types.d.ts

@@ -1,6 +1,12 @@
 import type { ExternalIds, MediaDetails, MediaType } from "../media/index.js";
 import type { ResponseMeta } from "../response/index.js";
 export interface DetailsQuery {
+    /**
+     * @deprecated Provider-native IDs do not share a global namespace. Use `ids`
+     * or a named external ID shortcut such as `imdb` or `kinopoisk`.
+     * RU: внутренние ID провайдеров не имеют общего namespace; используйте `ids`
+     * или именованное сокращение внешнего ID.
+     */
     id?: string;
     ids?: ExternalIds;
     imdb?: string;

package/dist/engine/availability.d.ts

@@ -0,0 +1,6 @@
+import type { CacheSetOptions } from "../cache/index.js";
+import type { MediaAvailability, StreamQuery, StreamingProvider } from "../streaming/index.js";
+export declare function selectStreamingProviders(providers: StreamingProvider[], query: StreamQuery): StreamingProvider[];
+export declare function mergeAvailabilityResults(query: StreamQuery, results: MediaAvailability[]): MediaAvailability;
+export declare function createAvailabilityCacheOptions(availability: MediaAvailability): CacheSetOptions | undefined;
+export declare function hasUnknownStreamValidation(availability: MediaAvailability): boolean;