@vkontakte/videoplayer-core 2.0.179-dev.4cee6bcff.0 → 2.0.179-dev.62f578567.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vkontakte/videoplayer-core",
-  "version": "2.0.179-dev.4cee6bcff.0",
+  "version": "2.0.179-dev.62f578567.0",
   "author": "vk.ru",
   "description": "Videoplayer core library based on the vk.ru platform",
   "homepage": "https://vk.ru",
@@ -42,6 +42,6 @@
     "**/*.d.ts"
   ],
   "dependencies": {
-    "@vkontakte/videoplayer-shared": "1.0.108-dev.4cee6bcff.0"
+    "@vkontakte/videoplayer-shared": "1.0.108-dev.62f578567.0"
   }
 }

package/types/player/Player.d.ts

@@ -30,7 +30,7 @@ export default class Player implements IPlayer {
 	experimental: PlayerExperimentalImpl;
 	private devNullLog;
 	private collectDecodingInfoDestroyCb;
-	private hasReleasedTimers;
+	private releaseTimers;
 	constructor(tuning?: IOptionalTuningConfig, tracer?: ITracer, playerOptions?: IPlayerOptions);
 	private readonly doInit;
 	/**

package/types/player/types.d.ts

@@ -315,12 +315,14 @@ export interface PlayerInfoValues {
 	*
 	* default value: `undefined`
 	*/
+	currentVirtualVideoBuffer$: StartEnd<Seconds> | undefined;
 	currentVideoBuffer$: StartEnd<Seconds> | undefined;
 	/**
 	* Текущий аудио-буффер плеера (тот; который содержит текущую позицию воспроизведения)
 	*
 	* default value: `undefined`
 	*/
+	currentVirtualAudioBuffer$: StartEnd<Seconds> | undefined;
 	currentAudioBuffer$: StartEnd<Seconds> | undefined;
 	/**
 	* Текущий браузерный видео-буффер (тот; который содержит текущую позицию воспроизведения)

package/types/providers/DashProvider/lib/buffer.d.ts

@@ -42,6 +42,7 @@ export declare class BufferManager {
 	private parsedInitData;
 	private representations;
 	private segments;
+	private segmentIndexMap;
 	private allInitsLoaded;
 	private activeSegments;
 	private forwardBufferRepresentations;
@@ -110,6 +111,7 @@ export declare class BufferManager {
 	private feedPreDownloadedFirstSegment;
 	private loadByteRangeSegments;
 	private prepareByteRangeFetchSegmentParams;
+	private buildCacheMetadata;
 	private prepareTemplateFetchSegmentParams;
 	private abortActiveSegments;
 	private onSomeTemplateDataLoaded;

package/types/providers/DashProvider/lib/fetcher.d.ts

@@ -4,6 +4,7 @@ import type { Byte, IValueSubject, ISubject, Milliseconds, IRange, ITracer, IErr
 import { abortable } from "@vkontakte/videoplayer-shared";
 import type { ExactVideoQuality } from "@vkontakte/videoplayer-shared";
 import type { CommonInit, GenericContainerParser, Segment, SegmentReference } from "../../utils/parsers/types";
+import type { ISegmentCacheStorage, CacheMetadata, SegmentCacheMode } from "../../utils/segmentCache";
 declare global {
 	interface Navigator {
 		connection: {
@@ -24,12 +25,13 @@ export interface IParams {
 	tracer: ITracer;
 	useEnableSubtitlesParam?: boolean;
 	handleExtendedNetworkErrorsSet?: boolean;
-	useUrlCacheMechanism?: boolean;
 	measureNonSegmentRequests?: boolean;
 	measureFastSamples?: boolean;
 	cacheHitTtfbMaxMs?: Milliseconds;
 	preloadFirstSegment?: boolean;
 	maxQualityForFirstSegmentPreload?: ExactVideoQuality;
+	segmentCacheService?: ISegmentCacheStorage;
+	segmentCacheMode?: SegmentCacheMode;
 }
 export type Priority = "high" | "low" | "auto";
 export interface FetchParamsWithUrl extends FetchParams {
@@ -46,8 +48,8 @@ export interface FetchParams {
 	isLowLatency?: boolean;
 	bufferOptimisation?: boolean;
 	ignoreNetworkErrors?: boolean;
-	urlCacheMechanismEnabled?: boolean;
 	representationHeight?: number;
+	cacheMetadata?: CacheMetadata;
 }
 export type RepresentationFetchResult = {
 	init: CommonInit | null;
@@ -74,17 +76,18 @@ export declare class Fetcher {
 	private readonly subscription;
 	private compatibilityMode;
 	private useEnableSubtitlesParam;
-	private useUrlCacheMechanism;
 	private measureNonSegmentRequests;
 	private measureFastSamples;
 	private cacheHitTtfbMaxMs;
 	private preloadFirstSegment;
 	private maxQualityForFirstSegmentPreload;
+	private segmentCacheService;
+	private mediaBatchCache;
 	private startupPhase;
 	private performanceObserver;
 	private pendingConnectionMetrics;
 	private handleExtendedNetworkErrorsSet;
-	constructor({ throughputEstimator, requestQuic, tracer, compatibilityMode, useEnableSubtitlesParam, handleExtendedNetworkErrorsSet, useUrlCacheMechanism, measureNonSegmentRequests, measureFastSamples, cacheHitTtfbMaxMs, preloadFirstSegment, maxQualityForFirstSegmentPreload }: IParams);
+	constructor({ throughputEstimator, requestQuic, tracer, compatibilityMode, useEnableSubtitlesParam, handleExtendedNetworkErrorsSet, measureNonSegmentRequests, measureFastSamples, cacheHitTtfbMaxMs, preloadFirstSegment, maxQualityForFirstSegmentPreload, segmentCacheService, segmentCacheMode }: IParams);
 	private onHeadersReceived;
 	private setupPerformanceObserver;
 	private processPerformanceResourceTiming;
@@ -95,6 +98,8 @@ export declare class Fetcher {
 	fetchManifest: ReturnType<typeof abortable<[string], string | null>>;
 	fetch: ReturnType<typeof abortable<[string, FetchParams], ArrayBuffer | null>>;
 	fetchRepresentation(segmentReference: SegmentReference, parser: GenericContainerParser<unknown>, fetchParams: FetchParams): Promise<RepresentationFetchResult | null>;
+	/** Скипнутые сегменты не записаны в кэш — при следующем запросе региона докачаются как miss. */
+	private traceSkippedCacheSegments;
 	destroy(): void;
 	private fetchByteRangeRepresentation;
 	private fetchTemplateRepresentation;

package/types/providers/DashProvider/lib/player.d.ts

@@ -40,6 +40,7 @@ export declare class Player {
 	private subscriptionRemovable;
 	private representationSubscription;
 	private fetcher;
+	private segmentCacheService;
 	state$: StateMachine<State>;
 	currentVideoRepresentation$: IValueSubject<Representation["id"] | undefined>;
 	currentVideoRepresentationInit$: IValueSubject<CommonInit | undefined>;

package/types/providers/DashProviderVirtual/lib/buffer/types.d.ts

@@ -3,6 +3,7 @@ import type { CommonInit, Manifest, Representation, Segment } from "../../../uti
 import type { Fetcher } from "../fetcher";
 import type { ITuningConfig } from "../../../../utils/tuningConfig";
 import type { VideoSegmentLoadProgress } from "../../../utils/Abr/types";
+import type { ISegmentCacheStorage } from "../../../utils/segmentCache";
 export type TRepresentationSwitchMode = "lazy" | "force";
 export declare enum SwithRepresentationMode {
 	Lazy = "lazy",
@@ -15,6 +16,7 @@ export interface Dependencies {
 	tuning: ITuningConfig;
 	compatibilityMode?: boolean;
 	manifest: Manifest | null;
+	segmentCacheService?: ISegmentCacheStorage;
 	getCurrentPosition(): Milliseconds | undefined;
 	getCurrentStallDuration(): Milliseconds;
 	isActiveLowLatency(): boolean;

package/types/providers/DashProviderVirtual/lib/buffer/virtualBuffer/baseVirtualBufferManager.d.ts

@@ -2,6 +2,7 @@ import type { Fetcher, FetchParamsWithUrl, Priority, RepresentationFetchResult }
 import type { CommonInit, ContainerParser, Representation, Segment } from "../../../../utils/parsers/types";
 import { StreamKind } from "../../../../utils/parsers/types";
 import type { ITuningConfig } from "../../../../../utils/tuningConfig";
+import type { ISegmentCacheStorage } from "../../../../utils/segmentCache";
 import type { Byte, IError, IRange, ISubject, ITracer, IValueSubject, Milliseconds, Seconds } from "@vkontakte/videoplayer-shared";
 import { abortable, Subscription } from "@vkontakte/videoplayer-shared";
 import type { NativeBufferManager } from "../nativeBufferManager";
@@ -19,6 +20,7 @@ export declare abstract class BaseVirtualBufferManager<T extends Segment> implem
 	protected readonly fetcher: Fetcher;
 	protected readonly tracer: ITracer;
 	protected readonly tuning: ITuningConfig;
+	protected readonly segmentCacheService: ISegmentCacheStorage | undefined;
 	protected representations: Map<Representation["id"], Representation>;
 	protected playingRepresentationId: Representation["id"] | undefined;
 	protected downloadingRepresentationId: Representation["id"] | undefined;
@@ -54,7 +56,7 @@ export declare abstract class BaseVirtualBufferManager<T extends Segment> implem
 	protected readonly getCurrentPosition: () => Milliseconds | undefined;
 	protected readonly getCurrentStallDuration: () => Milliseconds | undefined;
 	protected brokenSegmentAppendDetected: boolean;
-	protected constructor(kind: StreamKind, nativeBufferManager: NativeBufferManager, representations: Representation[], { fetcher, tracer, tuning, getCurrentPosition, getCurrentStallDuration, manifest }: Dependencies);
+	protected constructor(kind: StreamKind, nativeBufferManager: NativeBufferManager, representations: Representation[], { fetcher, tracer, tuning, getCurrentPosition, getCurrentStallDuration, manifest, segmentCacheService }: Dependencies);
 	protected abstract loadItems(itemsToLoad: IBufferPlaybackQueueItem<T>[], representation: Representation, priority?: Priority): Promise<void>;
 	protected abstract selectItemsToLoad(): IBufferPlaybackQueueItem<T>[];
 	protected abstract prepareFetchParams(items: IBufferPlaybackQueueItem<T>[], representation: Representation): FetchParamsWithUrl;

package/types/providers/DashProviderVirtual/lib/buffer/virtualBuffer/byteRangeVirtualBufferManager.d.ts

@@ -8,6 +8,7 @@ export declare class ByteRangeVirtualBufferManager extends BaseVirtualBufferMana
 	protected override loadItems(itemsToLoad: IBufferPlaybackQueueItem<ByteRangeSegment>[], representation: Representation, priority?: Priority): Promise<void>;
 	protected override selectItemsToLoad(): IBufferPlaybackQueueItem<ByteRangeSegment>[];
 	protected override prepareFetchParams(items: IBufferPlaybackQueueItem<ByteRangeSegment>[], representation: Representation): FetchParamsWithUrl;
+	private buildCacheMetadata;
 	/**
 	* Закидываем в буфер сегменты атомарнее чем сегмент целиком. Например, по боксам в мпеге и по блокам в вебме.
 	* Таким образом не ждём его полной загрузки и готовы играть его намного быстрее

package/types/providers/DashProviderVirtual/lib/fetcher.d.ts

@@ -4,6 +4,7 @@ import type { Byte, IError, IRange, ISubject, ITracer, IValueSubject, Millisecon
 import { abortable } from "@vkontakte/videoplayer-shared";
 import type { ExactVideoQuality } from "@vkontakte/videoplayer-shared";
 import type { CommonInit, GenericContainerParser, Segment, SegmentReference, StreamKind } from "../../utils/parsers/types";
+import type { ISegmentCacheStorage, CacheMetadata, SegmentCacheMode } from "../../utils/segmentCache";
 declare global {
 	interface Navigator {
 		connection: {
@@ -24,12 +25,13 @@ export interface IParams {
 	tracer: ITracer;
 	useEnableSubtitlesParam?: boolean;
 	handleExtendedNetworkErrorsSet?: boolean;
-	useUrlCacheMechanism?: boolean;
 	measureNonSegmentRequests?: boolean;
 	measureFastSamples?: boolean;
 	cacheHitTtfbMaxMs?: Milliseconds;
 	preloadFirstSegment?: boolean;
 	maxQualityForFirstSegmentPreload?: ExactVideoQuality;
+	segmentCacheService?: ISegmentCacheStorage;
+	segmentCacheMode?: SegmentCacheMode;
 }
 export type Priority = "high" | "low" | "auto";
 export interface FetchParamsWithUrl extends FetchParams {
@@ -45,8 +47,8 @@ export interface FetchParams {
 	measureThroughput?: boolean;
 	isLowLatency?: boolean;
 	bufferOptimisation?: boolean;
-	urlCacheMechanismEnabled?: boolean;
 	kind: StreamKind;
+	cacheMetadata?: CacheMetadata;
 }
 export type RepresentationFetchResult<T extends Segment> = {
 	initMetadata: CommonInit | null;
@@ -73,17 +75,18 @@ export declare class Fetcher {
 	private subscription;
 	private compatibilityMode;
 	private useEnableSubtitlesParam;
-	private useUrlCacheMechanism;
 	private measureNonSegmentRequests;
 	private measureFastSamples;
 	private cacheHitTtfbMaxMs;
 	private preloadFirstSegment;
 	private maxQualityForFirstSegmentPreload;
+	private segmentCacheService;
+	private mediaBatchCache;
 	private startupPhase;
 	private performanceObserver;
 	private pendingConnectionMetrics;
 	private handleExtendedNetworkErrorsSet;
-	constructor({ throughputEstimator, requestQuic, tracer, compatibilityMode, useEnableSubtitlesParam, handleExtendedNetworkErrorsSet, useUrlCacheMechanism, measureNonSegmentRequests, measureFastSamples, cacheHitTtfbMaxMs, preloadFirstSegment, maxQualityForFirstSegmentPreload }: IParams);
+	constructor({ throughputEstimator, requestQuic, tracer, compatibilityMode, useEnableSubtitlesParam, handleExtendedNetworkErrorsSet, measureNonSegmentRequests, measureFastSamples, cacheHitTtfbMaxMs, preloadFirstSegment, maxQualityForFirstSegmentPreload, segmentCacheService, segmentCacheMode }: IParams);
 	private onHeadersReceived;
 	private setupPerformanceObserver;
 	private processResourceTiming;
@@ -94,6 +97,8 @@ export declare class Fetcher {
 	fetchManifest: ReturnType<typeof abortable<[string], string | null>>;
 	fetch: ReturnType<typeof abortable<[string, FetchParams], ArrayBuffer | null>>;
 	fetchRepresentation<T extends Segment>(segmentReference: SegmentReference, parser: GenericContainerParser<unknown>, dowbloadAbortSignal: AbortSignal, priority?: Priority, representationHeight?: number, kind?: StreamKind): Promise<RepresentationFetchResult<T> | null | undefined>;
+	/** Скипнутые сегменты не записаны в кэш — при следующем запросе региона докачаются как miss. */
+	private traceSkippedCacheSegments;
 	destroy(): void;
 	private fetchByteRangeRepresentation;
 	private fetchTemplateRepresentation;

package/types/providers/DashProviderVirtual/lib/player/basePlayer.d.ts

@@ -9,6 +9,7 @@ import type { IError, IRange, ISubject, ISubscription, ITracer, IValueSubject, M
 import { abortable, Subject, Subscription, SubscriptionRemovable } from "@vkontakte/videoplayer-shared";
 import type { VideoSegmentLoadProgress } from "../../../utils/Abr/types";
 import { Fetcher } from "../fetcher";
+import type { ISegmentCacheStorage } from "../../../utils/segmentCache";
 import type { Dependencies, IVirtualBufferManager, SwithRepresentationMode } from "../buffer/types";
 import type { Params } from "./types";
 import { State } from "./types";
@@ -34,6 +35,7 @@ export declare abstract class BasePlayer {
 	protected subscriptionRemovable: SubscriptionRemovable;
 	protected representationSubscription: Subscription;
 	protected fetcher: Fetcher;
+	protected segmentCacheService: ISegmentCacheStorage | undefined;
 	protected forceEnded$: ISubject<void>;
 	protected stallWatchdogSubscription: ISubscription | undefined;
 	protected destroyController: AbortController;
@@ -62,10 +64,11 @@ export declare abstract class BasePlayer {
 	liveSeekableDuration$: IValueSubject<Milliseconds>;
 	liveAvailabilityStartTime$: IValueSubject<Milliseconds>;
 	liveStreamStatus$: IValueSubject<LiveStreamStatus | undefined>;
-	currentVideoBuffer$: IValueSubject<IRange<Seconds>>;
-	currentAudioBuffer$: IValueSubject<IRange<Seconds>>;
+	currentVirtualVideoBuffer$: IValueSubject<IRange<Seconds>>;
+	currentVirtualAudioBuffer$: IValueSubject<IRange<Seconds>>;
 	bufferLength$: IValueSubject<Milliseconds>;
 	nativeBufferLength$: IValueSubject<Milliseconds>;
+	nativeVideoBufferLength$: IValueSubject<IRange<Seconds>>;
 	nativeAudioBufferLength$: IValueSubject<IRange<Seconds>>;
 	liveLatency$: IValueSubject<Milliseconds | undefined>;
 	liveLoadBufferLength$: IValueSubject<Milliseconds>;

package/types/providers/ProviderContainer/index.d.ts

@@ -37,6 +37,7 @@ export default class ProviderContainer implements IProviderContainer {
 	private currentProviderStarted;
 	private volumeMultiplierManager;
 	private dashMaxTvVideoQuality;
+	private segmentCacheCleared;
 	private mayday;
 	private maydayStatistics;
 	constructor(params: IParams);
@@ -50,6 +51,8 @@ export default class ProviderContainer implements IProviderContainer {
 	private destroyProvider;
 	private handleMaydayRecommendation;
 	private applyErrorSideEffects;
+	/** Битые данные в кэше могут вызывать повторные ошибки после реинита — очищаем кэш целиком. */
+	private clearSegmentCacheOnError;
 	private createProvider;
 	private createScreenProvider;
 	private createChromecastProvider;

package/types/providers/types.d.ts

@@ -81,8 +81,8 @@ export interface IProviderOutput {
 	autoVideoTrackLimits$: IValueSubject<QualityLimits | undefined>;
 	autoVideoTrackLimitingAvailable$: IValueSubject<boolean>;
 	canChangePlaybackSpeed$: IValueSubject<boolean | undefined>;
-	currentVideoBuffer$: IValueSubject<IRange<Seconds> | undefined>;
-	currentAudioBuffer$: IValueSubject<IRange<Seconds> | undefined>;
+	currentVirtualVideoBuffer$: IValueSubject<IRange<Seconds> | undefined>;
+	currentVirtualAudioBuffer$: IValueSubject<IRange<Seconds> | undefined>;
 	currentNativeVideoBuffer$: IValueSubject<IRange<Seconds> | undefined>;
 	currentNativeAudioBuffer$: IValueSubject<IRange<Seconds> | undefined>;
 	totalBufferDuration$: IValueSubject<Milliseconds | undefined>;

package/types/providers/utils/Abr/abrController.d.ts

@@ -1,14 +1,16 @@
 import type { AbrLimitSources, IAbrController, IAbrRule, IBaseAbrControllerContext, IRuleInitContext, RuleLogData } from "./types";
 import type { IBaseTrack } from "../../../player/types";
+import { HistoryController } from "./controllers/historyController";
 export declare const formatRuleLog: ({ name, ...logData }: RuleLogData) => string;
 export default class AbrController<
 	T extends IBaseTrack,
 	C extends IBaseAbrControllerContext
 > implements IAbrController<T> {
-	private history;
+	private historyController;
 	private rules;
 	private _context;
 	private _limitSources;
+	constructor(historyController?: HistoryController<T>);
 	get context(): C;
 	get limitSources(): AbrLimitSources;
 	init(rules: IAbrRule<T, C>[], initContext: IRuleInitContext): void;
@@ -17,7 +19,8 @@ export default class AbrController<
 	autoSelectTrack(rules?: IAbrRule<T, C>[]): T;
 	private traceQualitySwitch;
 	private isLowQuality;
-	private selectTrackBasedOnHistory;
-	/** при переключении аудио стрима очищаем историю для предотвращения залипания в `onCooldown` */
-	historyReset(): void;
+	/** Полный сброс истории: cooldown, осцилляции и баны. */
+	resetHistory(): void;
+	resetOscillation(): void;
+	resetTrackOutcome(): void;
 }

package/types/providers/utils/Abr/controllers/historyController.d.ts

@@ -0,0 +1,67 @@
+import type { IBaseTrack } from "../../../../player/types";
+import type { IObservable } from "@vkontakte/videoplayer-shared";
+import type { ITuningConfig } from "../../../../utils/tuningConfig";
+import type { IBaseAbrControllerContext } from "../types";
+import type { TrackBans } from "./trackOutcomeController";
+import type { OscillationReturnStats } from "./oscillationController";
+import type { TrackOutcomeStats } from "./trackOutcomeController";
+/** Телеметрия истории переключений: разрезы осцилляции и исходов (баны, испытательный срок). */
+export type HistoryStats = {
+	oscillation: OscillationReturnStats;
+	outcome: TrackOutcomeStats | undefined;
+};
+type SelectBasedOnHistoryParams<T extends IBaseTrack> = {
+	candidate: T;
+	context: IBaseAbrControllerContext;
+};
+type ConstructorParams = {
+	/**
+	* Конфиг автоподбора качества; при отсутствии — только cooldown включается.
+	* oscillationCooldownEnabled включает влияние осцилляционного замка на выбор,
+	* trackOutcomeEnabled — применение банов; сбор журнала и исходов идёт всегда.
+	*/
+	autoTrackSelection?: ITuningConfig["autoTrackSelection"];
+	severeStallOccurred$?: IObservable<boolean>;
+	isSeeked$?: IObservable<boolean>;
+};
+/**
+* Решает, допускается ли переключение дорожки: трековый cooldown и доказанная осцилляция.
+* Владеет историей выборов дорожек, детекцией осцилляции (OscillationController)
+* и исходами переключений (TrackOutcomeController) — в исходы попадают только выполненные
+* переключения. Состояние ведётся по id дорожек одного вида (видео или аудио) —
+* общий инстанс для разных видов смешал бы осцилляции и баны.
+*/
+export declare class HistoryController<T extends IBaseTrack = IBaseTrack> {
+	private lastApprovedTrack;
+	private lastSelectedAtById;
+	private readonly oscillationController;
+	private readonly outcomeController;
+	private readonly oscillationLockEnabled;
+	private readonly trackOutcomeEnabled;
+	private readonly subscription;
+	constructor({ autoTrackSelection, severeStallOccurred$, isSeeked$ }?: ConstructorParams);
+	get last(): T | undefined;
+	/**
+	* Полный сценарий гейтирования против истории переключений: решение по кандидату
+	* (cooldown / осцилляция), обновление всей истории (выборы, журнал, исходы)
+	* и телеметрия при блоке. Возвращает трек, который следует выбрать.
+	*/
+	selectBasedOnHistory({ candidate, context }: SelectBasedOnHistoryParams<T>): T;
+	private decide;
+	private isUpgrade;
+	private isTrackOnCooldown;
+	/** Полный сброс: cooldown, журнал осцилляций и исходы переключений. */
+	clear(): void;
+	/** Журнал фиксирует отклонённое намерение, исходы не трогаются: испытательный срок не начинался. */
+	private rejectSwitch;
+	private commitSwitch;
+	getActiveBans(): TrackBans | undefined;
+	/** Телеметрия истории: статистика осцилляций и исходов переключений (у аудио outcome-контроллера нет). */
+	getStats(): HistoryStats;
+	/** Телеметрия и лог заблокированного переключения; снапшот контекста — для состояния сети/буфера. */
+	private reportBlockedSwitch;
+	resetOscillation(): void;
+	resetOutcome(): void;
+	destroy(): void;
+}
+export {};

package/types/providers/utils/Abr/controllers/oscillationController.d.ts

@@ -0,0 +1,83 @@
+import type { IBaseTrack } from "../../../../player/types";
+import type { Milliseconds } from "@vkontakte/videoplayer-shared";
+export declare const OSCILLATION_WINDOW_MS = 6e4;
+export declare const OSCILLATION_MIN_RETURNS = 2;
+export declare enum BlockReason {
+	TrackCooldown = "track-cooldown",
+	OscillationCooldown = "oscillation-cooldown"
+}
+export type SwitchDirection = "up" | "down";
+export type SwitchEvent = {
+	kind: "switch";
+	fromId: IBaseTrack["id"];
+	toId: IBaseTrack["id"];
+	direction: SwitchDirection;
+	/** true — отклонённое намерение; отсутствие флага — выполненное переключение */
+	rejected?: boolean;
+	timestamp: Milliseconds;
+};
+export type SwitchJournalEntry = SwitchEvent | {
+	kind: "stallStart" | "stallEnd";
+	timestamp: Milliseconds;
+};
+export type SwitchRecordParams = {
+	fromId: IBaseTrack["id"];
+	toId: IBaseTrack["id"];
+	direction: SwitchDirection;
+	rejected?: boolean;
+};
+export type OscillationReturnStats = {
+	maxTrackReturns: number;
+	sumTrackReturns: number;
+	maxPairReturns: number;
+	sumPairReturns: number;
+};
+/**
+* Осцилляция — метание качества туда-сюда (флаппинг): ABR гоняет качество
+* 720p → 480p → 720p → 480p, обычно потому что оценка канала скачет вокруг границы
+* двух качеств: чуть выросла — поднялись, чуть просела — упали. Вреден тем, что каждое
+* переключение — это сброс загружаемых сегментов и риск буферизации, а зритель видит
+* «пилящую» картинку.
+*
+* Владеет журналом последних событий ABR: переключения дорожек (выполненные и отклонённые
+* cooldown намерения) и stall start/end. Журнал хранит порядок событий (в отличие от истории
+* выборов с таймстампами) — только по порядку можно отличить флаппинг от разовых событий.
+* Детектор isOscillationProven отвечает на вопрос «доказана ли осцилляция» — по нему
+* AbrController решает, применять ли трековый cooldown. События stall/seek раздаёт
+* HistoryController. Подробно: docs/architecture/abr/switch-journal.md
+*/
+export declare class OscillationController {
+	private buffer;
+	private lastEntry;
+	recordStall(isOccurred: boolean): void;
+	recordSwitch({ fromId, toId, direction, rejected }: SwitchRecordParams): void;
+	entries(): readonly SwitchJournalEntry[];
+	reset(): void;
+	isOscillationProven(): boolean;
+	/**
+	* Телеметрия near-miss к доказательству осцилляции: немедленные откаты в окне журнала,
+	* просуммированные тремя способами — по возвращённой дорожке, по неупорядоченной паре
+	* дорожек пинг-понга и итогово (max/сумма). Показывает форму пилообразной серии там,
+	* где порог OSCILLATION_MIN_RETURNS ещё не взят или взят с запасом: одиночный ramp
+	* размазывает откаты по разным дорожкам и парам (max 1 при сумме 2), пила через разные
+	* вершины концентрирует откаты на одной дорожке, но на разных парах (maxTrack 2 при
+	* maxPair 1), пинг-понг на двух дорожках — и там и там (maxPair ≥ maxTrack).
+	* Решение о расширении критерия детекции принимается по этим счётчикам в A/B,
+	* а не по boolean isOscillationProven.
+	*/
+	getStats(): OscillationReturnStats;
+	/**
+	* Считает немедленные откаты в окне осцилляции (OSCILLATION_WINDOW_MS от текущего момента).
+	* «Возврат» — переключение на дорожку, с которой ушли предыдущей записью, в противоположном
+	* направлении (A → B → A): одиночный ramp вниз-вверх (congestion без stall) не считается
+	* осцилляцией, а повторные откаты на ту же дорожку — считаются. Отклонённые cooldown
+	* намерения не считаются. Stall-запись обнуляет счётчики и разрывает смежность переключений:
+	* каскад до просадки и восстановление после неё — не осцилляция.
+	*
+	* Возвращает два разреза одних и тех же откатов: по дорожке и по паре (см. ImmediateReturnCounts).
+	*/
+	private countImmediateReturns;
+	private push;
+	private isConsecutiveDuplicateRejectedIntent;
+	private dropEntriesOlderThanWindow;
+}

package/types/providers/utils/Abr/controllers/trackOutcomeController.d.ts

@@ -0,0 +1,53 @@
+import type { IBaseTrack } from "../../../../player/types";
+import type { Milliseconds } from "@vkontakte/videoplayer-shared";
+import type { ITuningConfig } from "../../../../utils/tuningConfig";
+export type TrackBans = Record<IBaseTrack["id"], Milliseconds>;
+/** Телеметрия исходов переключений: испытательный срок, недавние фейлы и активные баны. */
+export type TrackOutcomeStats = {
+	/** Текущая дорожка на испытательном сроке (или просто последняя выбранная). */
+	currentTrackId: IBaseTrack["id"] | undefined;
+	/** Сколько мс текущая дорожка уже выбрана — прогресс испытательного срока. */
+	currentProbationMs: Milliseconds;
+	/** Провален ли испытательный срок текущей дорожки (stall или слишком ранний уход). */
+	probationFailed: boolean;
+	/** Число недавних фейлов в окне trackBanWindowMs по каждой дорожке. */
+	failsByTrack: Record<IBaseTrack["id"], number>;
+	/** Активные баны: id -> до какого времени. */
+	activeBans: TrackBans;
+};
+export type TrackSwitchOutcomeParams = {
+	fromId: IBaseTrack["id"];
+	toId: IBaseTrack["id"];
+	isUpgrade: boolean;
+};
+/**
+* Владелец исходов переключений: испытательный срок trackProbationMs и баны за неудачные подъёмы.
+* Питается ТОЛЬКО выполненными переключениями (после всех гейтов контроллера) и severe stall —
+* отклонённые cooldown намерения не являются попыткой испытательного срока.
+* См. docs/superpowers/specs/2026-08-30-anchor-ban-abr-design.md.
+*/
+export declare class TrackOutcomeController {
+	private readonly autoTrackSelection;
+	private currentId;
+	private currentTrackSelectedAt;
+	private probationFailed;
+	private fails;
+	private bans;
+	constructor({ autoTrackSelection }: {
+		autoTrackSelection: ITuningConfig["autoTrackSelection"];
+	});
+	/**
+	* Первый трек сессии не приходит переключением (уходить не с чего), поэтому без явной
+	* регистрации его испытательный срок не начинается: severe stall на стартовом качестве
+	* и спуск с него не дают неудачи, хотя это самый частый сценарий «взяли высоко — не потянули».
+	*/
+	recordInitialTrack(trackId: IBaseTrack["id"]): void;
+	recordSwitch({ fromId, toId, isUpgrade }: TrackSwitchOutcomeParams): void;
+	/** Отдаёт только ещё активные баны и подчищает истёкшие. */
+	getActiveBans(): TrackBans;
+	getStats(): TrackOutcomeStats;
+	reset(): void;
+	private finishProbation;
+	recordSevereStallHappened(): void;
+	private pushFail;
+}

package/types/providers/utils/Abr/rules/video/banBasedOnHistoryRule.d.ts

@@ -0,0 +1,17 @@
+import type { IAbrRule, IAbrRuleResolution, IVideoAbrContext, RuleLogData } from "../../types";
+import type { IVideoTrack } from "../../../../../player/types";
+import { LimitAboveRule } from "../limitAboveRule";
+import type { RulePhaseConfig } from "../../controllers/abrPhaseController";
+type BanLogsArgs = [bannedIds: string[]];
+/**
+* Правило банов по истории переключений: активный banUntil (TrackOutcomeController, см. спеку
+* anchor-ban) отсекает дорожку и всё выше неё — не потянули 720, не потянут и 1080. Потолок —
+* старший незабаненный ниже самого низкого забаненного, поэтому всё не выше потолка (и победитель
+* слияния лимитов в том числе) гарантированно незабаненное.
+*/
+export declare class BanBasedOnHistoryRule extends LimitAboveRule<IVideoTrack, IVideoAbrContext, BanLogsArgs> implements IAbrRule<IVideoTrack, IVideoAbrContext> {
+	constructor(phaseConfig: RulePhaseConfig);
+	execute(context: IVideoAbrContext): IAbrRuleResolution<IVideoTrack>;
+	protected createLogData(selectedTrack: IVideoTrack, bannedIds: string[]): RuleLogData;
+}
+export {};

package/types/providers/utils/Abr/types.d.ts

@@ -5,6 +5,7 @@ import type { Representation, Segment } from "../parsers/types";
 import type { ElementSizeManager } from "../HTMLVideoElement/ElementSizeManager";
 import type { IObservableMediaElement } from "../HTMLVideoElement/observable";
 import type { AbrPhase } from "./controllers/abrPhaseController";
+import type { TrackBans } from "./controllers/trackOutcomeController";
 export type AbrLimitSources = {
 	readonly above: string | undefined;
 	readonly below: string | undefined;
@@ -25,7 +26,8 @@ export declare enum VideoRuleName {
 	UpperLimit = "upper_limit_rule",
 	Throughput = "throughput_rule",
 	AbandonRequest = "abandon_request_rule",
-	InsufficientBuffer = "insufficient_buffer_rule"
+	InsufficientBuffer = "insufficient_buffer_rule",
+	Ban = "ban_rule"
 }
 export declare enum AudioRuleName {
 	MinAudioForVideo = "min_audio_for_video_rule",
@@ -92,12 +94,12 @@ export interface IAbrRule<
 	C extends IBaseAbrControllerContext
 > {
 	readonly activePhases: ReadonlySet<AbrPhase>;
-	init(initContext: IRuleInitContext): void;
+	init(ruleContext: IRuleInitContext): void;
 	destroy(): void;
 	execute(context: C): IAbrRuleResolution<T>;
 }
 export interface IAbrController<T extends IBaseTrack> {
-	init(rules: IAbrRule<T, IBaseAbrControllerContext>[], initContext: IRuleInitContext): void;
+	init(rules: IAbrRule<T, IBaseAbrControllerContext>[], ruleContext: IRuleInitContext): void;
 	destroy(): void;
 	updateContext(context: IBaseAbrControllerContext): void;
 	autoSelectTrack(rules?: IAbrRule<T, IBaseAbrControllerContext>[]): T;
@@ -115,6 +117,7 @@ export interface IBaseAbrControllerContext extends IVideoTracksContext {
 	forwardBufferDuration: Milliseconds | undefined;
 	playbackRate: number;
 	throughputVariance: number;
+	bannedUntil?: TrackBans;
 }
 export type VideoSegmentLoadProgress = {
 	startedAtMs: Milliseconds;

package/types/providers/utils/Abr/utils.d.ts

@@ -7,6 +7,7 @@ export declare enum CompareTrack {
 	Ascending = 1
 }
 export declare const isVideoTrack: (track: IBaseTrack) => track is IVideoTrack;
+export declare const describeTrack: (track: Nullable<IBaseTrack>) => string | number | undefined;
 export declare const getAudioTrackComparator: (type: CompareTrack) => (track1: IAudioTrack, track2: IAudioTrack) => number;
 export declare const getVideoTrackComparator: (type: CompareTrack) => (track1: IVideoTrack, track2: IVideoTrack) => number;
 export declare const getTrackComparator: <T extends IBaseTrack>(compareTrack: CompareTrack) => (track1: T, track2: T) => number;